Solana Pay, Actions e Blinks
Solana Pay, Actions e Blinks são a stack de interação embutível da Solana: formas de solicitar valor ou assinaturas fora de um shell dApp customizado completo.
Compartilham uma ideia. Um client (wallet, provedor Blink ou scanner QR) descobre uma intenção, opcionalmente busca uma transação construída no servidor e pede ao usuário para assinar. Você possui o endpoint HTTPS e instruções; a wallet possui chaves e a tela de aprovação.
Esta página é o guarda-chuva da seção. Páginas irmãs cobrem URLs de pagamento, transaction requests, contrato HTTP Actions, Blinks, implementação e verificação.
Resumo
- Solana Pay começa como URLs e fluxos QR orientados a pagamento; transaction requests estendem isso a transações construídas no servidor; Actions generaliza o padrão em API padronizada de metadata + transação; Blinks empacotam Actions como links compartilháveis e embutíveis.
- Por que importa: A maior parte do crescimento de produto não é "abra nosso SPA e conecte". PDV, faturas, CTAs sociais, votos de governança e mints de um toque precisam de intenções portáteis que qualquer wallet compatível complete sem novo esquema de deep-link por client.
- Conceitos-chave: transfer request, transaction request, conta de referência, Action GET/POST, metadata de Action, Blink, unfurl, CORS, wire transaction base64, simulação, verificação de liquidação.
- Quando usar: Checkout e doações, QR presencial, CTAs sociais ou de campanha, botões on-chain leves (voto, mint, swap) e qualquer fluxo em que comerciante ou protocolo deve construir a transação que o usuário assina.
- Limitações / trade-offs: Você troca UX in-app completa por alcance. Hospedagem, TLS, CORS, rate limits e resistência a phishing viram requisitos de produto. Usuários ainda devem entender o que assinam; wallets e clients Blink não inventam confiança para domínio malicioso.
- Tópicos relacionados: Noções Básicas de Solana Pay, Transaction Requests, Actions (a spec), Blinks, Construindo uma Action, Segurança e Verificação.
Fundamentos
Comece com Solana Pay como camada de pagamento.
Um transfer request codifica destinatário, valor (e mint SPL opcional), label, message e chaves públicas de referência opcionais em URL que wallets entendem. Comerciantes renderizam como QR para ponto de venda ou compartilham para checkout remoto. A wallet preenche transferência; o usuário assina; a chain liquida.
Referências dirigem bookkeeping. Uma pubkey de referência única por pedido permite que seu servidor observe RPC ou websockets por transação correspondente e marque fatura como paga sem confiar apenas em callback do browser. Valor e mint ainda precisam de verificações no servidor; referência correspondente é correlação, não prova completa sozinha.
Transaction requests elevam o mesmo padrão "wallet busca intenção de HTTPS" além de transferências simples. O endpoint do comerciante recebe conta do cliente, constrói transação versionada com essa conta como fee payer ou signer obrigatório e retorna transação serializada que a wallet pode visualizar e assinar. Checkout pode fazer swap, mint ou chamar programa customizado em uma aprovação.
Solana Actions generaliza endpoints que produzem transações além de pay clássico de comerciante. A especificação Actions define como clients descobrem metadata legível (title, icon, description, label e campos relacionados) e como obtêm transação codificada em base64 para account conectada. Wallets, portais Blink e unfurlers sociais falam o mesmo contrato.
Blinks (blockchain links) são a camada de distribuição. Um Blink é URL de Action apresentada por client ou proxy compatível com Blink para unfurl em card rico: ícone, copy e botão que executa fluxo POST de Action. A Action permanece sua API HTTPS; o Blink é como usuários encontram e compartilham no X, Discord, sites parceiros e superfícies Blink.
Este site constrói código client e servidor com @solana/kit 7.0.0, faz deploy de programas sob Agave 4.1.1 / Solana CLI 3.0.10 e frequentemente compõe instruções de programas Anchor 0.32.1 em Rust 1.91.1. Pay e Actions são principalmente TypeScript e HTTP; os programas que você invoca ainda obedecem regras de conta e CU do Sealevel.
Mecânica e interações
Caminho de transferência Solana Pay
- Comerciante cria URL de transferência (
encodeURLdo@solana/payou campos construídos manualmente conforme spec Pay). - Cliente escaneia QR ou abre link na wallet.
- Wallet mostra valor, label e destinatário; usuário assina transferência (SOL ou SPL).
- Comerciante monitora referência (e valor) via RPC até confirmed, depois atende pedido.
Use transfer requests quando a ação é "enviar N do ativo X para destinatário Y" sem composição multi-instrução no servidor.
Caminho de transaction request
- Wallet abre
https://merchant.example/pay?...(ou formato transaction-request que sua wallet suporta). - Endpoint valida params, carrega blockhash, constrói instruções para conta conectada, serializa wire transaction (unsigned, ou parcialmente assinada apenas quando você co-assina intencionalmente).
- Wallet simula e mostra preview; usuário assina; rede executa.
- Comerciante verifica liquidação via referências, saldos, eventos de programa ou fingerprints de instrução.
Transaction requests e Actions sobrepõem-se muito. Muitos produtos implementam Actions (ou handlers compatíveis com Action) e tratam transaction requests Solana Pay como ancestral do mesmo padrão com sabor de pagamento.
Actions: metadata GET, transação POST
| Método | Papel |
|---|---|
OPTIONS | Preflight CORS para clients browser e extension |
GET | Metadata read-only para cards e unfurlers |
POST | Aceita { account } (e campos body opcionais), retorna { transaction } base64 |
GET não deve mutar estado. É apresentação cacheável: ícone HTTPS, title, description, label de botão, inputs opcionais. POST é dinâmico por usuário: insira pubkey dele como signer/fee payer, defina blockhash fresco, anexe apenas contas e instruções necessárias para aquele CTA.
Clients mostram sua metadata, depois POST o endereço da wallet conectada. Seu servidor retorna transação que a wallet assina. Callbacks opcionais reportam conclusão; nunca os trate como prova única sem confirmação RPC.
Blinks: Actions compartilháveis
Um client Blink pega URL de Action (frequentemente via query de provedor como ?action=https://...) e:
- Busca metadata GET de Action para card de unfurl.
- Renderiza ícone, título e CTA na superfície host.
- Executa o mesmo caminho POST → assinar → enviar que client Actions nativo.
Seu trabalho permanece o endpoint Action: CORS, TLS, metadata precisa e transações least-privilege. Provedores Blink e wallets adicionam allowlists, avisos e badges; isso complementa construção segura, não substitui.
Construindo uma Action (loop de implementação)
Actions de produção geralmente vivem como route handlers (por exemplo Next.js App Router em app/api/actions/...):
- Scaffold GET, POST e OPTIONS com headers CORS de Actions.
- GET retorna assets de branding estáveis no seu domínio.
- POST interpreta
account, constrói instruções (builders Kit ou helpers Codama/IDL para programas Anchor), define fee payer e blockhash, serializa base64. - Simule antes de retornar quando falha desperdiçaria atenção ou esconderia config quebrada.
- Observe custo RPC, erros e assinaturas no servidor com rate limits.
Separe program IDs e URLs RPC para devnet e mainnet-beta. Action mainnet apontando para program ID devnet é bug comum de lançamento.
Segurança e verificação como mecânica de primeira classe
- Transporte: HTTPS apenas para URLs Action, ícones e endpoints Pay.
- Origem: usuários devem ver domínio real; sites clone roubam ícones e labels.
- Conteúdo da transação: least privilege; sem
SetAuthorityinesperado, aprovações ilimitadas ou transferências não relacionadas. - Simulação: wallets simulam; seu handler POST também deve simular para caminhos conhecidamente bons.
- Liquidação: para comércio, confirme on-chain com referência + valor (e mint) antes do atendimento.
- Abuso: rate-limit POST, limite patrocínio de taxa e evite endpoints abertos que constroem drains escolhidos por atacante sob sua marca.
Verificação no lado Blink também cobre registries de client, verificações de domínio e integridade de unfurl (ícone ainda no seu host). Trate caches de unfurl como propensos a obsolescência; versione URLs de assets estáticos quando branding mudar.
Considerações avançadas e aplicações
Escolhendo a camada certa
| Necessidade | Prefira | Evite quando |
|---|---|---|
| Pagamento SOL/SPL presencial | Solana Pay transfer + QR | Precisa composição multi-ix |
| Checkout com swap/mint/ix customizada | Transaction request ou Action | URL de transferência simples basta |
| CTA social compartilhável | Action + Blink | Apenas PDV offline |
| UX de produto multi-tela completa | dApp wallet-adapter | Só precisa CTA de um toque |
| Movimentação de dinheiro alto risco | Programa escrow + liquidação verificada | Confiar apenas em eventos "paid" do client |
Muitos times rodam ambos: Solana Pay ou Actions para aquisição e PDV, e dApp completo para power users. A habilidade compartilhada é construir transações seguras para pubkey de cliente.
Padrões de produto
- Faturas e doações: transfer requests com referências únicas e labels curtos.
- Comércio com inventário: transaction request ou Action que minta recibo, queima PDA de cupom ou move fundos de vault sob regras de programa.
- Governança e comunidade: CTAs de voto, claim ou stake como Blinks.
- Pontos de entrada DeFi: um conjunto de ix swap ou depósito com slippage explícito; nunca esconda aprovações ilimitadas atrás de label "Claim".
- Patrocínio de taxa: partial-sign opcional para UX gasless, com caps rígidos, auth e monitoramento para que patrocínio não seja drenado.
Client, stack e ops
Use @solana/kit 7.0.0 para RPC, endereços, construção de mensagem e codificação wire. Prefira transações versionadas e simulação. Para programas Anchor 0.32.1, gere builders tipados (Codama/IDL) para que account metas permaneçam corretos conforme programas evoluem.
Uma Action apenas entrega transação que o usuário assina; não relaxa verificações Sealevel, PDAs, regras de token ou limites de CU nos programas que você chama.
Operacionalmente: cache CDN de metadata GET estável, nunca cache txs POST entre usuários; rotacione blockhashes a cada POST; registre latência e falhas sem secrets em query strings; se Action ruim for ao ar, tire rota offline e rotacione assets quando clones de phishing aparecerem.
Equívocos comuns
- "Solana Pay é só QR codes para SOL." Pay cobre fluxos de transfer e transaction-request, incluindo valores SPL e APIs de comerciante mais ricas.
- "Actions substituem wallets." Actions alimentam wallets e clients Blink; usuário ainda assina em contexto de wallet.
- "Blink é programa on-chain diferente." Blink é distribuição e UX de unfurl em torno de URL Action; mudanças de estado on-chain só quando transação assinada chega.
- "Simulação verde significa que comerciante pode marcar pago." Simulação não é liquidação. Confirme assinaturas e saldos no commitment exigido.
- "GET pode criar efeitos colaterais de fatura." GET é para metadata. Criar pedidos ou queimar nonces em GET convida caches e crawlers a corromper estado.
- "CORS wildcard é sempre OK." Clients da spec precisam CORS, mas endpoints sensíveis ou patrocinados ainda precisam rate limits, auth e monitoramento de abuso.
- "Ícone e título provam legitimidade." Clones de phishing copiam ambos. Inspeção de domínio e verificação de client importam mais que branding sozinho.
- "Uma URL Action pode significar qualquer coisa que o body pedir com segurança." Prefira templates fixos e auditados por rota (
/vote,/mint,/pay) em vez de builders abertos. - "Transaction requests e Actions são não relacionados." Compartilham transações construídas no servidor; Actions são o padrão mais amplo e pronto para social.
- "Patrocínio de taxa é crescimento grátis." Patrocínio sem cap é vetor de drain. Orçamente, autentique e meça.
FAQs
Que problema Solana Pay, Actions e Blinks resolvem juntos?
Permitem que usuários completem intenções on-chain (pagar, votar, mintar, fazer swap) a partir de links, QR codes e superfícies sociais sem forçar toda interação por dApp multi-página customizado.
Quando devo usar transfer request simples em vez de Action?
Quando a intenção é pagamento SOL ou SPL simples para destinatário e valor conhecidos e você não precisa de lógica multi-instrução ou CTAs sociais com unfurl. URLs de transferência são a menor superfície.
O que é conta de referência em Solana Pay?
Chave pública incluída no pagamento para seu backend encontrar transação on-chain correspondente e ligá-la a id de pedido. Gere referência única por sessão de checkout e verifique valor no servidor.
Como transaction requests diferem de transfer requests?
Transfer requests descrevem pagamento que a wallet pode construir localmente. Transaction requests atingem sua API HTTPS para o servidor retornar transação completa (swap, mint, programa customizado, etc.) para o cliente assinar.
O que um endpoint Actions deve implementar?
No mínimo: CORS/OPTIONS conforme exigido por clients, metadata GET para exibição humana e POST que aceita conta do usuário e retorna transação base64. Siga campos da especificação Actions atual que suas wallets alvo suportam.
Blink é API separada de Action?
Geralmente não. A Action é a API. Blink é como essa Action é linkada, unfurled e apresentada dentro de apps e provedores compatíveis com Blink.
Por que ícones Action precisam HTTPS no meu domínio?
Clients carregam ícones para cards e unfurls. Hotlinking ou assets HTTP quebram renderização, enfraquecem sinais de confiança e criam risco de supply chain se terceiro troca imagem.
Posso construir Actions com @solana/kit 7.0.0?
Sim. Kit é a stack TypeScript que este site fixa para RPC, endereços e construção de mensagem de transação em handlers POST.
Preciso de Anchor para lançar Action?
Não. Actions são HTTP mais qualquer transação Solana válida. Anchor 0.32.1 ajuda quando seu CTA chama programa Anchor e você quer builders orientados por IDL; programas nativos funcionam igual no nível wire.
Como comerciantes devem verificar que pagamento teve sucesso?
Confirme via RPC (e preferencialmente websockets ou indexer) transação que corresponda a regras de referência, valor, mint e destinatário no seu nível de commitment. Não confie em callbacks apenas do client.
Quais são os erros de maior risco em handlers POST de Action?
Transações com privilégios excessivos, pular simulação, patrocínio de taxa sem cap, rate limits ausentes e program IDs de cluster errado em produção.
Como Blinks tratam confiança para domínios desconhecidos?
Clients podem avisar, allowlist ou mostrar badges de verificação. Assuma que usuários ignoram avisos; mantenha transações mínimas e domínios consistentes com sua marca.
Metadata GET deve ser cacheada no CDN?
Sim para branding estável, com TTLs curtos se títulos mudam frequentemente. Nunca cache respostas POST de transação entre usuários ou tempo.
O que ler em seguida nesta seção?
Comece com Noções Básicas de Solana Pay e Transaction Requests, depois Actions (a spec) e Blinks. Implemente com Construindo uma Action e endureça com Segurança e Verificação.
Relacionados
- Noções Básicas de Solana Pay - URLs de transferência, fluxos QR, referências e metadata de pagamento
- Transaction Requests - transações construídas no servidor para checkout além de transferências simples
- Actions (a spec) - contrato GET metadata e POST transação
- Blinks - links Action compartilháveis e embutíveis e UX de unfurl
- Construindo uma Action - endpoints, CORS, metadata e fluxo de assinatura ponta a ponta
- Segurança e Verificação - confiança, phishing, simulação e verificações de liquidação
Versões da stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 e @solana/kit 7.0.0.