Machine Payments Protocol w sieci Solana

Machine Payments Protocol (MPP) stosuje semantykę uwierzytelniania HTTP do płatności. Serwer wysyła wyzwanie w odpowiedzi na nieopłacone żądanie, klient zwraca poświadczenie płatności, a serwer po zaakceptowaniu płatności zwraca potwierdzenie.

MPP rozdziela trzy kwestie:

• Intencja (intent) opisuje interakcję handlową, na przykład jednorazową opłatę charge lub rozliczaną według zużycia sesję session.
• Metoda płatności opisuje sposób przepływu wartości. Metoda dla Solany obsługuje natywny SOL oraz tokeny SPL w przypadku opłat.
• Transport HTTP przenosi wyzwania, poświadczenia, potwierdzenia i błędy.

MPP jest publikowany jako zestaw dokumentów Internet-Draft. Traktuj aktualne specyfikacje jako źródło prawdy i oczekuj, że szczegóły będą się zmieniać, dopóki prace nad wersjami roboczymi trwają.

Wymiana HTTP

MPP wykorzystuje standardowe pola uwierzytelniania HTTP zamiast nagłówków płatności specyficznych dla protokołu:

Wyzwanie zawiera wygenerowany przez serwer identyfikator, realm, metodę, intencję, zakodowane żądanie płatności oraz termin ważności. Poświadczenie powtarza wyzwanie i dodaje dowód płatności właściwy dla metody. Serwer musi zweryfikować oba elementy; prawidłowy przelew, który należy do innego wyzwania, nie może odblokować zasobu.

Jednorazowe opłaty w sieci Solana

Intencja charge dla Solany obsługuje dwa typy poświadczeń:

• Tryb pull wykorzystuje podpisaną transakcję. Klient podpisuje przelew i wysyła transakcję do serwera. Serwer weryfikuje ją, opcjonalnie dodaje podpis płatnika opłat (fee payer), rozgłasza transakcję, czeka na potwierdzenie i zwraca sygnaturę transakcji w swoim potwierdzeniu.
• Tryb push wykorzystuje sygnaturę transakcji. Klient najpierw rozgłasza transakcję, a następnie wysyła potwierdzoną sygnaturę do serwera. Serwer pobiera i weryfikuje transakcję, zanim zwróci zasób.

Tryb pull umożliwia sponsorowanie opłat transakcyjnych przez serwer oraz logikę ponawiania po stronie serwera. Tryb push jest przydatny, gdy portfel wymaga, aby klient samodzielnie przesłał własną transakcję, ale nie można w nim skorzystać ze sponsorowania opłat przez serwer.

Informacje o polach normatywnych i regułach weryfikacji znajdziesz w specyfikacji opłat Solana charge.

Dodawanie opłaty MPP do API Express

Solana Pay Kit zapewnia aktualną integrację TypeScript dla MPP i x402. Zainstaluj go razem z Express:

pnpm add @solana/pay-kit @solana/kit@^6.9.0 express
pnpm add --save-dev @types/express tsx

Ten najprostszy przykład korzysta z hostowanego środowiska testowego Surfpool oraz publicznego odbiorcy demonstracyjnego z pakietu. Służy wyłącznie do lokalnego programowania:

import express from "express";
import { createPayKit, usd } from "@solana/pay-kit";

const pay = await createPayKit({
  accept: ["mpp"],
  rpcUrl: "https://402.surfnet.dev:8899"
});

const app = express();

app.get("/report", pay.express(usd("0.01")), (_req, res) => {
  res.json({ report: "Paid report" });
});

app.listen(4567, () => {
  console.log("Paid API listening on http://127.0.0.1:4567");
});

Uruchom go i porównaj nieopłacone żądanie z żądaniem uwzględniającym płatność:

pnpm tsx server.ts
curl -i http://127.0.0.1:4567/report
pay --sandbox curl http://127.0.0.1:4567/report

Handler trasy zostaje uruchomiony dopiero po tym, jak middleware zaakceptuje płatność.

Sesje rozliczane według zużycia

Użyj sesji session MPP dla Solany, gdy klient będzie wykonywał wiele drobnych, powiązanych płatności. Sesja otwiera kanał płatności onchain z maksymalnym depozytem, a następnie wykorzystuje skumulowane podpisane vouchery w miarę wzrostu zużycia. Serwer może weryfikować vouchery offchain i rozliczyć najwyższą zaakceptowaną kwotę później.

Sprawdza się to w przypadku inferencji rozliczanej według tokenów, pobierania rozliczanego według bajtów, danych na żywo oraz powtarzanych wywołań narzędzi. To nie to samo, co wysyłanie osobnej płatności onchain dla każdego zdarzenia.

Nazywaj sesję płatnością sesyjną, kanałem płatności lub ograniczoną powtarzalną autoryzacją. Określenia „płatność strumieniowa” używaj tylko wtedy, gdy usługa i umowa płatnicza faktycznie rozliczają strumień zużycia.

Weryfikacja produkcyjna

Przy każdej opłacie w sieci Solana serwer musi zweryfikować co najmniej:

• Wyzwanie jest autentyczne, nie wygasło, jest powiązane z tym żądaniem i przeznaczone dla tego realmu.
• Transakcja używa oczekiwanej sieci, aktywa lub mint, odbiorcy, kwoty oraz token program.
• Wszelkie instrukcje płatnika opłat lub associated token account są jawnie dozwolone i nie mogą opróżnić środków sygnatariusza serwera.
• Transakcja zakończyła się powodzeniem na wymaganym poziomie commitment.
• Sygnatura transakcji nie została jeszcze wykorzystana.
• Sprawdzenie powtórzenia i operacja zużycia są atomowe we wszystkich instancjach serwera.

W przypadku sesji zapisuj też stan kanału, zaakceptowaną kwotę skumulowaną oraz znacznik rozliczenia we współdzielonym magazynie. Opisz w dokumentacji, jak klienci odzyskują niewykorzystane środki, jeśli serwer stanie się niedostępny.

Powiązane zasoby

• Specyfikacje MPP
• Dokumentacja protokołu MPP
• Solana Pay Kit
• Przegląd płatności agentowych
• Gotowość produkcyjna