Machine Payments Protocol na Solana

O Machine Payments Protocol (MPP) aplica a semântica de autenticação HTTP aos pagamentos. Um servidor lança um desafio a uma requisição não paga, um cliente devolve uma credencial de pagamento e o servidor retorna um recibo depois de aceitar o pagamento.

O MPP separa três responsabilidades:

• Uma intenção descreve a interação comercial, como uma cobrança única (charge) ou uma sessão medida (session).
• Um método de pagamento descreve como o valor é movimentado. O método da Solana suporta SOL nativo e tokens SPL para cobranças.
• Um transporte HTTP transporta desafios, credenciais, recibos e erros.

O MPP é publicado como um conjunto de Internet-Drafts. Trate as especificações atuais como a fonte de verdade e esteja preparado para que os detalhes evoluam enquanto os rascunhos estiverem em andamento.

Troca HTTP

O MPP usa campos padrão de autenticação HTTP em vez de cabeçalhos de pagamento específicos do protocolo:

Um desafio inclui um ID gerado pelo servidor, realm, método, intenção, requisição de pagamento codificada e prazo de validade. A credencial repete o desafio e acrescenta a prova de pagamento específica do método. O servidor deve verificar ambos; uma transferência válida que pertença a um desafio diferente não deve liberar o recurso.

Cobranças únicas na Solana

A intenção charge da Solana suporta dois tipos de credencial:

• O modo pull usa uma transação assinada. O cliente assina a transferência e envia a transação ao servidor. O servidor a verifica, opcionalmente adiciona uma assinatura de pagador de taxas, transmite, confirma e retorna a assinatura da transação no recibo.
• O modo push usa uma assinatura de transação. O cliente transmite primeiro e depois envia a assinatura confirmada ao servidor. O servidor busca e verifica a transação antes de retornar o recurso.

O modo pull permite o patrocínio de taxas de transação pelo servidor e lógica de nova tentativa no lado do servidor. O modo push é útil quando uma carteira exige que o cliente envie a própria transação, mas não pode usar o patrocínio de taxas do servidor.

Para os campos normativos e as regras de verificação, consulte a especificação de cobrança da Solana.

Adicione uma cobrança MPP a uma API Express

O Solana Pay Kit oferece uma integração atual em TypeScript para MPP e x402. Instale-o com o Express:

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

Este exemplo mínimo usa o sandbox Surfpool hospedado e o destinatário de demonstração público do pacote. Serve apenas para desenvolvimento local:

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");
});

Execute-o e compare uma requisição sem pagamento com uma requisição com suporte a pagamento:

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

O manipulador da rota só é executado depois que o middleware aceita o pagamento.

Sessões medidas

Use uma session MPP da Solana quando um cliente fizer muitos pagamentos pequenos e relacionados. Uma sessão abre um canal de pagamento onchain com um depósito máximo e, em seguida, usa vouchers assinados cumulativos à medida que o uso cresce. O servidor pode verificar os vouchers offchain e liquidar o maior valor aceito posteriormente.

Isso é útil para inferência medida por token, downloads medidos por byte, dados em tempo real e chamadas repetidas de ferramentas. Não é o mesmo que enviar um pagamento onchain separado para cada evento.

Chame uma sessão de pagamento de sessão, canal de pagamento ou autorização repetida limitada. Só a chame de pagamento em fluxo contínuo quando o serviço e o contrato de pagamento realmente medirem um fluxo de uso.

Verificação em produção

Para cada cobrança na Solana, o servidor deve verificar pelo menos:

• Que o desafio é autêntico, não expirou, está vinculado a esta requisição e destina-se a este realm.
• Que a transação usa a rede, o ativo ou mint, o destinatário, o valor e o programa de tokens esperados.
• Que quaisquer instruções de pagador de taxas ou de associated token account são explicitamente permitidas e não podem esgotar os fundos do signatário do servidor.
• Que a transação foi bem-sucedida no nível de commitment exigido.
• Que a assinatura da transação ainda não foi consumida.
• Que a verificação de replay e a operação de consumo são atômicas em todas as instâncias do servidor.

Para sessões, persista também o estado do canal, o valor cumulativo aceito e a marca d'água de liquidação em um armazenamento compartilhado. Documente como os clientes recuperam os fundos não utilizados caso o servidor fique indisponível.

Recursos relacionados

• Especificações do MPP
• Documentação do protocolo MPP
• Solana Pay Kit
• Visão geral dos pagamentos agênticos
• Prontidão para produção