PYUSD no Solana: O Guia Prático de Integração (com RPC da BlockEden.xyz)
PayPal USD (PYUSD) chegou ao Solana, marcando um marco significativo para pagamentos digitais. Este guia fornece um passo‑a‑passo direto e focado em produção para engenheiros que desejam integrar o PYUSD em carteiras, dApps e plataformas de comércio no Solana.
Todos os exemplos utilizam código atualizado e compatível com Token-2022 e são projetados para funcionar perfeitamente com os endpoints RPC de baixa latência da BlockEden.xyz.
TL;DR
- O que: PayPal USD (PYUSD) agora é um token SPL nativo Token-2022 no Solana, oferecendo liquidação rápida e com baixas taxas para um stablecoin reconhecido globalmente.
- Parâmetros principais: Mint
2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo
, decimais6
e programa de tokenToken-2022
. - Conjunto de recursos: Utiliza as Extensões de Token do Solana (Token-2022). Possui um Transfer Hook inicializado, mas atualmente inativo (programa nulo), além de capacidades de transferência confidencial e outras extensões.
- Cross‑chain: Uma integração oficial com LayerZero permite que o PYUSD se mova entre Ethereum e Solana via um mecanismo seguro de queima‑e‑mint, contornando pontes tradicionais.
- Ação: Use este guia como um modelo pronto para adicionar suporte ao PYUSD em sua aplicação com o RPC confiável da BlockEden.xyz.
Por que o PYUSD no Solana é importante
A combinação da marca PayPal com o desempenho do Solana cria uma nova via poderosa para dólares digitais.
- Confiança do consumidor encontra UX cripto: O PYUSD é emitido pela empresa regulada Paxos e está profundamente integrado ao PayPal e ao Venmo. Isso oferece ao usuário um ativo familiar. Eles podem manter um único saldo em PYUSD e escolher retirar para uma carteira externa tanto no Ethereum quanto no Solana, abstraindo a complexidade das cadeias.
- Infraestrutura pronta para pagamentos: A arquitetura do Solana fornece finalização de transação em subsegundos e taxas que são frações de centavo. O PYUSD adiciona uma unidade de conta estável e reconhecível sobre essa rede de liquidação eficiente, tornando‑o ideal para pagamentos, comércio e remessas.
- Controles de nível institucional: Ao ser lançado como token Token-2022, o PYUSD pode utilizar extensões nativas para recursos como transferências confidenciais, metadados ricos e delegado permanente. Isso permite conformidade avançada e funcionalidade sem a necessidade de contratos inteligentes personalizados e difíceis de auditar.
O essencial absoluto (fixe isso)
Antes de escrever uma única linha de código, tenha esses parâmetros bloqueados. Sempre verifique o endereço da mint em um explorador confiável para evitar interagir com tokens fraudulentos.
- Mint (Mainnet):
2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo
- Decimais:
6
(significa 1 PYUSD = 1.000.000 unidades base) - Programa de Token:
Token-2022
(Program ID:TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
) - Extensões de Token usadas (na mint):
- Metadados e Ponte de Metadados
- Delegado Permanente
- Transfer Hook (inicializado com programa nulo)
- Configuração de Transferência Confidencial
Você pode verificar tudo isso no Explorador Solana. O explorador mostrará claramente o endereço oficial da mint e as extensões habilitadas.
Configurando seu projeto
Vamos preparar o ambiente. Você precisará das bibliotecas mais recentes de Solana web3 e SPL token para garantir compatibilidade total com Token-2022.
1. Bibliotecas
Instale os pacotes necessários via npm.
npm i @solana/web3.js @solana/spl-token
2. Conexão RPC
Aponte sua aplicação para a URL RPC do Solana Mainnet da BlockEden.xyz. Em produção, variáveis de ambiente são obrigatórias.
// package.json
// npm i @solana/web3.js @solana/spl-token
import { Connection, Keypair, PublicKey } from "@solana/web3.js";
import {
TOKEN_2022_PROGRAM_ID,
getMint,
getOrCreateAssociatedTokenAccount,
getAssociatedTokenAddress,
createTransferCheckedInstruction,
} from "@solana/spl-token";
// Use sua URL RPC da BlockEden.xyz obtida no painel
const RPC_ENDPOINT =
process.env.SOLANA_RPC_URL ??
"[https://your-blockeden-solana-mainnet-endpoint.com](https://your-blockeden-solana-mainnet-endpoint.com)";
export const connection = new Connection(RPC_ENDPOINT, "confirmed");
// PYUSD (mainnet)
export const PYUSD_MINT = new PublicKey(
"2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo",
);
Lendo dados da Mint PYUSD
Primeiro, confirme programaticamente as propriedades da mint PYUSD. Esta é uma etapa crucial para garantir que suas constantes estejam corretas e para buscar detalhes como o suprimento total.
// Confirme as informações da mint PYUSD via APIs Token-2022
const mintInfo = await getMint(
connection,
PYUSD_MINT,
"confirmed",
TOKEN_2022_PROGRAM_ID, // Especifique o ID do programa
);
console.log({
supply: mintInfo.supply.toString(),
decimals: mintInfo.decimals, // Espera 6
isInitialized: mintInfo.isInitialized,
});
Observe que passamos explicitamente TOKEN_2022_PROGRAM_ID
. Essa é a fonte mais comum de erros ao trabalhar com Extensões de Token.
Criar ou buscar Contas de Token Associadas (ATAs)
Contas de Token Associadas para tokens Token-2022 devem ser derivadas usando o ID do programa Token-2022. Se usar o TOKEN_PROGRAM_ID
legado, as transações falharão com erro “incorrect program id”.
// Pagador e proprietário da nova ATA. Substitua pela lógica da sua carteira.
const owner = Keypair.generate();
// Crie ou busque a ATA PYUSD do proprietário (compatível com Token-2022)
const ownerAta = await getOrCreateAssociatedTokenAccount(
connection,
owner, // Pagador pela criação
PYUSD_MINT, // Mint
owner.publicKey, // Proprietário da ATA
false, // allowOwnerOffCurve
"confirmed",
undefined, // options
TOKEN_2022_PROGRAM_ID, // <-- IMPORTANTE: Use o ID do programa Token-2022
);
console.log("Owner PYUSD ATA:", ownerAta.address.toBase58());
Verificando saldos de PYUSD
Para consultar o saldo de PYUSD de um usuário, consulte sua ATA, lembrando sempre de especificar o ID do programa correto.
Usando @solana/spl-token
import { getAccount } from "@solana/spl-token";
const accountInfo = await getAccount(
connection,
ownerAta.address,
"confirmed",
TOKEN_2022_PROGRAM_ID,
);
const balance = Number(accountInfo.amount) / 10 ** mintInfo.decimals; // decimais = 6
console.log("PYUSD balance:", balance);
Usando JSON‑RPC direto (curl
)
Também é possível listar todas as contas de token de um proprietário e filtrar pelo ID do programa Token-2022.
curl -X POST "$SOLANA_RPC_URL" -H 'content-type: application/json' -d '{
"jsonrpc":"2.0",
"id":1,
"method":"getTokenAccountsByOwner",
"params":[
"<OWNER_PUBLIC_KEY>",
{ "programId":"TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb" },
{ "encoding":"jsonParsed" }
]
}'
Transferindo PYUSD (Usuário‑para‑Usuário)
A regra de ouro para transferir qualquer ativo Token-2022 é usar createTransferCheckedInstruction
. Essa instrução inclui os decimais do token, prevenindo vulnerabilidades relacionadas a casas decimais.
Aqui está uma função completa e reutilizável para transferir PYUSD.
import { Transaction } from '@solana/web3.js';
async function transferPyusd({
fromWallet, // Keypair do remetente
toPubkey, // PublicKey do destinatário
uiAmount, // Valor em PYUSD, ex.: 1.25
}: {
fromWallet: Keypair;
toPubkey: PublicKey;
uiAmount: number;
}) {
const decimals = 6; // De mintInfo.decimals
const rawAmount = BigInt(Math.round(uiAmount * (10 ** decimals)));
// Obtenha o endereço ATA do remetente
const fromAta = await getAssociatedTokenAddress(
PYUSD_MINT,
fromWallet.publicKey,
false,
TOKEN_2022_PROGRAM_ID
);
// Garanta que a ATA do destinatário exista para Token-2022
const toAta = await getOrCreateAssociatedTokenAccount(
connection,
fromWallet, // Pagador
PYUSD_MINT,
toPubkey,
false,
'confirmed',
undefined,
TOKEN_2022_PROGRAM_ID
);
const transferInstruction = createTransferCheckedInstruction(
fromAta, // ATA de origem
PYUSD_MINT, // Mint
toAta.address, // ATA de destino
fromWallet.publicKey, // Dono da ATA de origem
rawAmount, // Valor em unidades base
decimals, // Decimais
[], // Signatários multisig
TOKEN_2022_PROGRAM_ID // <-- IMPORTANTE
);
const transaction = new Transaction().add(transferInstruction);
// Defina blockhash recente e pagador da taxa
transaction.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
transaction.feePayer = fromWallet.publicKey;
const signature = await connection.sendTransaction(transaction, [fromWallet]);
await connection.confirmTransaction(signature, 'confirmed');
console.log('Transação bem‑sucedida com assinatura:', signature);
return signature;
}
Nota sobre o Transfer Hook: A mint do PYUSD inicializa a extensão Transfer Hook, mas define seu programa como null
. Isso significa que transferências padrão funcionam sem contas ou lógica adicionais. Caso a PayPal/Paxos ative o hook no futuro, eles atualizarão a mint para apontar para um novo programa, e sua integração precisará passar as contas extras exigidas pela nova interface.
Teste rápido com Solana CLI
Para um teste manual rápido via linha de comando, use spl-token
com o ID de programa correto.
# Certifique-se de que sua CLI esteja apontando para mainnet e que seu keypair esteja financiado.
# Transfira 1.00 PYUSD para um destinatário.
spl-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
transfer 2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo 1.00 <RECIPIENT_PUBKEY> \
--fund-recipient --allow-unfunded-recipient
PYUSD Cross‑Chain (Ethereum ↔ Solana)
A PayPal implementou uma funcionalidade oficial cross‑chain usando LayerZero. Em vez de depender de pontes de terceiros arriscadas, este é um processo nativo de queima‑e‑mint: o PYUSD é queimado na cadeia de origem (por exemplo, Ethereum) e uma quantidade equivalente é mintada na cadeia de destino (Solana). Isso elimina riscos específicos de pontes e slippage.
Você pode encontrar o tutorial completo e os parâmetros na documentação oficial do PayPal Developer.
Teste com Faucets
Para desenvolvimento e testes, não use ativos da mainnet. Utilize os faucets oficiais:
- Faucet Paxos PYUSD: Para obter tokens PYUSD de teste.
- Faucet Solana: Para obter SOL de devnet/testnet para taxas de transação.
Armadilhas comuns (e correções)
- ID de programa errado: Problema: Transações falham com
incorrect program id for instruction
. Correção: Passe explicitamenteTOKEN_2022_PROGRAM_ID
para todas as funções auxiliares dospl-token
(getOrCreateAssociatedTokenAccount
,getAccount
,createTransferCheckedInstruction
, etc.). - Mint errada ou ativos falsificados: Problema: Sua aplicação interage com um token PYUSD falso. Correção: Codifique e verifique o endereço oficial da mint:
2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo
. Use um explorador que avise sobre mints não canônicas. - Descompasso de decimais: Problema: Enviar 1 PYUSD na verdade envia 0.000001 PYUSD. Correção: Sempre converta valores de UI para valores brutos multiplicando por
10^6
. Busque programaticamente os decimais da mint para garantir. - Suposições sobre Hook: Problema: Você implementou lógica complexa para um hook de transferência que ainda não está ativo. Correção: Verifique os dados de extensão da mint. Atualmente, o hook do PYUSD é nulo. Construa seu sistema para adaptar-se caso o programa do hook seja habilitado no futuro.
Checklist de produção para PYUSD + BlockEden.xyz
Ao migrar para produção, garanta que sua infraestrutura seja robusta.
- RPC: Use um endpoint BlockEden.xyz de alta disponibilidade. Use o compromisso
confirmed
para UX responsiva e consulte comfinalized
para operações críticas. - Segurança das chaves: Armazene as
Keypair
em cofres seguros (por exemplo, HSM ou serviços de gerenciamento de segredos). - Monitoramento: Registre métricas de latência e taxa de erro dos endpoints RPC.
- Conformidade: Mantenha logs de auditoria de todas as transações de pagamento.
Pronto para construir? Pegue seu endpoint de alto desempenho da BlockEden.xyz RPC e comece a integrar o futuro dos pagamentos hoje.