Pular para o conteúdo principal

PYUSD no Solana: O Guia Prático de Integração (com RPC da BlockEden.xyz)

· Leitura de 9 minutos
Dora Noda
Dora Noda
Software Engineer

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, decimais 6 e programa de token Token-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.

  1. 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.
  2. 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.
  3. 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)​

  1. ID de programa errado: Problema: Transações falham com incorrect program id for instruction. Correção: Passe explicitamente TOKEN_2022_PROGRAM_ID para todas as funções auxiliares do spl-token (getOrCreateAssociatedTokenAccount, getAccount, createTransferCheckedInstruction, etc.).
  2. 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.
  3. 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.
  4. 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 com finalized 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.

Share on Twitter