Saltar al contenido principal

PYUSD en Solana: Guía práctica de integración (con RPC de BlockEden.xyz)

· 9 min de lectura
Dora Noda
Dora Noda
Software Engineer

PayPal USD (PYUSD) ha llegado a Solana, marcando un hito importante para los pagos digitales. Esta guía ofrece un recorrido directo y orientado a producción para ingenieros que integren PYUSD en carteras, dApps y plataformas de comercio en Solana.

Todos los ejemplos usan código fresco compatible con Token-2022 y están diseñados para funcionar sin problemas con los endpoints RPC de Solana de baja latencia de BlockEden.xyz.

TL;DR​

  • Qué: PayPal USD (PYUSD) es ahora un token SPL nativo Token-2022 en Solana, que ofrece liquidación rápida y de bajo costo para una stablecoin reconocida globalmente.
  • Parámetros clave: Mint 2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo, decimales 6 y programa de token Token-2022.
  • Conjunto de funciones: Aprovecha las Extensiones de Token de Solana (Token-2022). Tiene un Transfer Hook inicializado pero actualmente inactivo (programa nulo), junto con capacidades de transferencia confidencial y otras extensiones.
  • Cross-chain: Una integración oficial con LayerZero permite que PYUSD se mueva entre Ethereum y Solana mediante un mecanismo seguro de quemado y acuñación, evitando puentes tradicionales.
  • Acción: Usa esta guía como plantilla lista para añadir soporte de PYUSD a tu aplicación con los RPC fiables de Solana de BlockEden.xyz.

Por qué PYUSD en Solana es importante​

La combinación de la marca PayPal con el rendimiento de Solana crea una nueva vía poderosa para dólares digitales.

  1. Confianza del consumidor + UX cripto: PYUSD es emitido por la compañía fiduciaria regulada Paxos y está profundamente integrado en PayPal y Venmo. Esto brinda a los usuarios un activo familiar. Pueden mantener un único saldo de PYUSD y elegir retirarlo a una cartera externa ya sea en Ethereum o Solana, abstraído de la complejidad de la cadena.
  2. Rieles listos para pagos: La arquitectura de Solana ofrece finalización de transacciones en menos de un segundo y tarifas que son fracciones de centavo. PYUSD coloca una unidad de cuenta estable y reconocible sobre esta red de liquidación eficiente, haciéndola ideal para pagos, comercio y remesas.
  3. Controles de nivel institucional: Al lanzarse como token Token-2022, PYUSD puede utilizar extensiones integradas para funciones como transferencias confidenciales, metadatos ricos y un delegado permanente. Esto permite cumplimiento avanzado y funcionalidad sin requerir contratos inteligentes personalizados y difíciles de auditar.

Lo esencial (fija esto)​

Antes de escribir una sola línea de código, asegura estos parámetros. Siempre verifica la dirección del mint en un explorador de confianza para evitar interactuar con tokens fraudulentos.

  • Mint (Mainnet): 2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo
  • Decimales: 6 (significa 1 PYUSD = 1,000,000 unidades base)
  • Programa de token: Token-2022 (Program ID: TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb)
  • Extensiones de token usadas (en el mint):
    • Metadata y Metadata Pointer
    • Delegado permanente
    • Transfer Hook (inicializado con programa nulo)
    • Configuración de Transferencia Confidencial

Puedes verificar todo esto en el Explorador de Solana. El explorador mostrará claramente la dirección oficial del mint y sus extensiones habilitadas.

Configura tu proyecto​

Preparemos el entorno. Necesitarás las últimas librerías web3 y SPL token de Solana para garantizar compatibilidad total con Token-2022.

1. Librerías​

Instala los paquetes necesarios desde npm.

npm i @solana/web3.js @solana/spl-token

2. Conexión RPC​

Apunta tu aplicación al endpoint RPC de Solana Mainnet de BlockEden.xyz. Para producción, las variables de entorno son obligatorias.

// 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";

// Usa tu URL RPC de Solana de BlockEden.xyz desde tu panel
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",
);

Lectura de datos del Mint PYUSD​

Primero, confirmemos programáticamente las propiedades del mint PYUSD. Este es un paso crucial para asegurar que tus constantes sean correctas y obtener detalles como el suministro total.

// Confirmar información del mint PYUSD vía APIs Token-2022
const mintInfo = await getMint(
  connection,
  PYUSD_MINT,
  "confirmed",
  TOKEN_2022_PROGRAM_ID, // Especificar el ID del programa
);

console.log({
  supply: mintInfo.supply.toString(),
  decimals: mintInfo.decimals, // Esperado 6
  isInitialized: mintInfo.isInitialized,
});

Observa que pasamos explícitamente TOKEN_2022_PROGRAM_ID. Esta es la fuente más común de errores al trabajar con extensiones de token.

Crear o obtener Cuentas de Token Asociadas (ATAs)​

Las Cuentas de Token Asociadas para tokens Token-2022 deben derivarse usando el ID del programa Token-2022. Si usas el TOKEN_PROGRAM_ID legado, las transacciones fallarán con error “incorrect program id”.

// Pagador y propietario de la nueva ATA. Reemplaza con la lógica de tu wallet.
const owner = Keypair.generate();

// Crear o obtener la ATA PYUSD del propietario (compatible con Token-2022)
const ownerAta = await getOrCreateAssociatedTokenAccount(
  connection,
  owner, // Pagador para la creación
  PYUSD_MINT, // Mint
  owner.publicKey, // Propietario de la ATA
  false, // allowOwnerOffCurve
  "confirmed",
  undefined, // options
  TOKEN_2022_PROGRAM_ID, // <-- IMPORTANTE: usar ID del programa Token-2022
);

console.log("Owner PYUSD ATA:", ownerAta.address.toBase58());

Verificar saldos de PYUSD​

Para consultar el saldo de PYUSD de un usuario, consulta su ATA, recordando especificar el ID de programa correcto.

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; // decimales = 6
console.log("PYUSD balance:", balance);

Usando JSON-RPC directo (curl)​

También puedes consultar todas las cuentas de token de un propietario y filtrarlas por el ID del 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" }
  ]
}'

Transferir PYUSD (usuario a usuario)​

La regla de oro para transferir cualquier activo Token-2022 es usar createTransferCheckedInstruction. Esta instrucción incluye los decimales del token, evitando vulnerabilidades relacionadas con decimales.

Aquí tienes una función reutilizable completa para transferir PYUSD.

import { Transaction } from '@solana/web3.js';

async function transferPyusd({
  fromWallet,     // Keypair del remitente
  toPubkey,       // PublicKey del destinatario
  uiAmount,       // Monto en PYUSD, p.ej., 1.25
}: {
  fromWallet: Keypair;
  toPubkey: PublicKey;
  uiAmount: number;
}) {
  const decimals = 6; // De mintInfo.decimals
  const rawAmount = BigInt(Math.round(uiAmount * (10 ** decimals)));

  // Obtener la dirección ATA del remitente
  const fromAta = await getAssociatedTokenAddress(
    PYUSD_MINT,
    fromWallet.publicKey,
    false,
    TOKEN_2022_PROGRAM_ID
  );

  // Asegurar que el ATA del destinatario 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 origen
    PYUSD_MINT,             // Mint
    toAta.address,          // ATA destino
    fromWallet.publicKey,   // Propietario del ATA origen
    rawAmount,              // Monto en unidades base
    decimals,               // Decimales
    [],                     // Firmas multisig
    TOKEN_2022_PROGRAM_ID   // <-- IMPORTANTE
  );

  const transaction = new Transaction().add(transferInstruction);

  // Establecer blockhash reciente y pagador de tarifas
  transaction.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
  transaction.feePayer = fromWallet.publicKey;

  const signature = await connection.sendTransaction(transaction, [fromWallet]);
  await connection.confirmTransaction(signature, 'confirmed');

  console.log('Transaction successful with signature:', signature);
  return signature;
}

Nota sobre el Transfer Hook: El mint de PYUSD inicializa la extensión Transfer Hook pero establece su programa en null. Esto significa que las transferencias estándar funcionan actualmente sin cuentas o lógica adicional. Si PayPal/Paxos activan el hook en el futuro, actualizarán el mint para apuntar a un nuevo programa y tu integración deberá pasar las cuentas extra requeridas por esa interfaz.

Prueba rápida con Solana CLI​

Para una prueba manual rápida desde la línea de comandos, puedes usar spl-token con el ID de programa correcto.

# Asegúrate de que tu CLI apunte a mainnet y tu keypair tenga fondos.
# Transferir 1.00 PYUSD a un destinatario.
spl-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  transfer 2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo 1.00 <RECIPIENT_PUBKEY> \
  --fund-recipient --allow-unfunded-recipient

PYUSD cross-chain (Ethereum ↔ Solana)​

PayPal ha implementado una funcionalidad cross-chain oficial usando LayerZero. En lugar de depender de puentes de terceros riesgosos, este es un proceso nativo de quemado y acuñación: PYUSD se quema en la cadena origen (p.ej., Ethereum) y se acuña una cantidad equivalente en la cadena destino (Solana). Esto elimina riesgos específicos de puentes y deslizamientos.

Puedes encontrar el tutorial completo y los parámetros en la documentación oficial de PayPal Developer.

Pruebas con faucets​

Para desarrollo y pruebas, no uses activos de mainnet. Utiliza los faucets oficiales:

  • Faucet de Paxos PYUSD: Para obtener tokens PYUSD de testnet.
  • Faucet de Solana: Para obtener SOL de devnet/testnet para tarifas de transacción.

Errores comunes (y soluciones)​

  1. ID de programa incorrecto: Problema: Las transacciones fallan con incorrect program id for instruction. Solución: Pasa explícitamente TOKEN_2022_PROGRAM_ID a todas las funciones auxiliares de spl-token (getOrCreateAssociatedTokenAccount, getAccount, createTransferCheckedInstruction, etc.).
  2. Mint incorrecto o activos falsificados: Problema: Tu aplicación interactúa con un token PYUSD falso. Solución: Codifica y verifica la dirección oficial del mint: 2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo. Usa un explorador que advierta sobre mints no canónicos.
  3. Desajuste de decimales: Problema: Enviar 1 PYUSD realmente envía 0.000001 PYUSD. Solución: Siempre convierte montos UI a montos crudos multiplicando por 10^6. Obtén los decimales del mint programáticamente para estar seguro.
  4. Suposiciones sobre el Hook: Problema: Construyes lógica compleja para un hook de transferencia que no está activo. Solución: Verifica los datos de extensión del mint. Hoy el hook de PYUSD es nulo. Diseña tu sistema para adaptarse si el programa del hook se habilita en el futuro.

Checklist de producción para PYUSD + BlockEden.xyz​

Al pasar a producción, asegura que tu infraestructura sea robusta.

  • RPC: Usa un endpoint de BlockEden.xyz de alta disponibilidad. Usa compromiso confirmed para una UX responsiva y consulta con finalized para operaciones que requieran integridad del libro mayor.
  • Reintentos & Idempotencia: Envuelve los envíos de transacciones con un mecanismo de reintento exponencial. Almacena una clave de idempotencia con cada operación de negocio para prevenir transferencias duplicadas.
  • Observabilidad: Registra los hashes de transacción, saldos y métricas de latencia. Monitorea los endpoints RPC y alerta sobre aumentos de latencia o errores.
  • Cumplimiento: Implementa auditorías de saldo y registro de eventos usando los logs de Solana y los datos del explorador.

Listado de referencias​

  • Mint oficial: 2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo
  • Program ID Token-2022: TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb

¿Listo para construir? Obtén tu endpoint RPC de alto rendimiento en BlockEden.xyz y comienza a integrar el futuro de los pagos hoy.

Share on Twitter