跳到主要内容

1 篇博文 含有标签“integration”

Platform integrations

查看所有标签

Solana 上的 PYUSD：实用集成指南（配合 BlockEden.xyz RPC）

· 阅读需 10 分钟
Dora Noda
Dora Noda
Software Engineer

PayPal USD (PYUSD) 已登陆 Solana，这标志着数字支付的一个重要里程碑。本指南为工程师提供了一个直接的、面向生产环境的演练，用于将 PYUSD 集成到 Solana 上的钱包、dApp 和商业平台中。

所有示例均使用最新的兼容 Token-2022 的代码，并旨在与 BlockEden.xyz 的低延迟 Solana RPC 端点无缝协作。

摘要​

  • 内容： PayPal USD (PYUSD) 现在是 Solana 上的原生 Token-2022 SPL 代币，为这种全球认可的稳定币提供快速、低费用的结算。
  • 关键参数： Mint 地址 2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo，精度 6，代币程序 Token-2022。
  • 功能特性： 利用 Solana 代币扩展 (Token-2022)。它包含一个已初始化但当前未激活（空程序）的转账钩子 (Transfer Hook)，以及机密转账功能和其他扩展。
  • 跨链： 官方的 LayerZero 集成允许 PYUSD 通过安全的销毁与铸造 (burn-and-mint) 机制在以太坊和 Solana 之间移动，从而绕过传统的桥接方式。
  • 行动： 使用本指南作为现成的模板，通过 BlockEden.xyz 可靠的 Solana RPC 将 PYUSD 支持添加到您的应用程序中。

为什么 Solana 上的 PYUSD 至关重要​

PayPal 的品牌效应与 Solana 的高性能相结合，为数字美元创造了一条强大的新路径。

  1. 消费者信任与加密货币用户体验的结合： PYUSD 由受监管的信托公司 Paxos 发行，并深度集成到 PayPal 和 Venmo 中。这为用户提供了一个熟悉的资产。他们可以持有单一的 PYUSD 余额，并选择提现到以太坊或 Solana 上的外部钱包，从而抽象掉了链的复杂性。
  2. 支付就绪的轨道： Solana 的架构提供了秒级以下的交易确认和不足一分钱的费用。PYUSD 在这种高效的结算网络之上增加了一个稳定、可识别的记账单位，使其成为支付、商业和汇款的理想选择。
  3. 机构级控制： 通过作为 Token-2022 代币启动，PYUSD 可以利用内置扩展功能，如机密转账、丰富的元数据和永久委托。这在不需要定制且难以审计的智能合约的情况下，实现了高级的合规性和功能性。

核心要素（建议置顶）​

在编写代码之前，请先锁定这些参数。务必在受信任的浏览器中验证 Mint 地址，以避免与欺诈代币交互。

  • Mint 地址 (主网): 2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo
  • 精度 (Decimals): 6（意味着 1 PYUSD = 1,000,000 基础单位）
  • 代币程序 (Token Program): Token-2022（程序 ID: TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb）
  • 使用的代币扩展（铸造时）：
    • 元数据与元数据指针 (Metadata & Metadata Pointer)
    • 永久委托 (Permanent Delegate)
    • 转账钩子 (Transfer Hook)（已初始化为空程序）
    • 机密转账配置 (Confidential Transfer Configuration)

您可以在 Solana Explorer 上验证所有这些信息。浏览器将清楚地显示官方 Mint 地址及其启用的扩展。

设置项目​

让我们准备好环境。您需要最新的 Solana web3 和 SPL 代币库，以确保完全兼容 Token-2022。

1. 库​

从 npm 安装必要的包。

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

2. RPC 连接​

将您的应用程序指向您的 BlockEden.xyz Solana 主网 RPC URL。对于生产环境，环境变量是必须的。

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

// 使用您 Dashboard 中的 BlockEden.xyz Solana RPC URL
const RPC_ENDPOINT =
  process.env.SOLANA_RPC_URL ??
  "https://your-blockeden-solana-mainnet-endpoint.com";
export const connection = new Connection(RPC_ENDPOINT, "confirmed");

// PYUSD (主网)
export const PYUSD_MINT = new PublicKey(
  "2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo",
);

读取 PYUSD Mint 数据​

首先，让我们通过编程方式确认 PYUSD Mint 的属性。这是确保常量正确并获取总供应量等细节的关键第一步。

// 通过 Token-2022 API 确认 PYUSD Mint 信息
const mintInfo = await getMint(
  connection,
  PYUSD_MINT,
  "confirmed",
  TOKEN_2022_PROGRAM_ID, // 指定程序 ID
);

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

注意我们显式传递了 TOKEN_2022_PROGRAM_ID。这是在使用代币扩展时最常见的错误来源。

创建或获取关联代币账户 (ATA)​

Token-2022 代币的关联代币账户 必须 使用 Token-2022 程序 ID 派生。如果使用旧版的 TOKEN_PROGRAM_ID，交易将失败并提示 "incorrect program id" 错误。

// 新 ATA 的付款人和所有者。请根据您的钱包逻辑进行替换。
const owner = Keypair.generate();

// 创建或获取所有者的 PYUSD ATA（兼容 Token-2022）
const ownerAta = await getOrCreateAssociatedTokenAccount(
  connection,
  owner, // 用于创建的付款人
  PYUSD_MINT, // 铸造地址 (Mint)
  owner.publicKey, // ATA 的所有者
  false, // allowOwnerOffCurve
  "confirmed",
  undefined, // 选项
  TOKEN_2022_PROGRAM_ID, // <-- 重要：使用 Token-2022 程序 ID
);

console.log("所有者 PYUSD ATA:", ownerAta.address.toBase58());

检查 PYUSD 余额​

要检查用户的 PYUSD 余额，请查询其 ATA，并同样记得指定正确的程序 ID。

使用 @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; // 精度 (decimals) = 6
console.log("PYUSD 余额:", balance);

使用直接 JSON-RPC (curl)​

您也可以检查某个所有者的所有代币账户，并通过 Token-2022 程序 ID 进行过滤。

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" }
  ]
}'

转账 PYUSD（用户间转账）​

转账任何 Token-2022 资产的经验法则是使用 createTransferCheckedInstruction。该指令包含代币的精度 (decimals)，可防止潜在的精度相关漏洞。

这是一个完整的、可重复使用的 PYUSD 转账函数。

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

async function transferPyusd({
  fromWallet,     // 发送者的密钥对 (Keypair)
  toPubkey,       // 接收者的公钥 (PublicKey)
  uiAmount,       // PYUSD 金额，例如 1.25
}: {
  fromWallet: Keypair;
  toPubkey: PublicKey;
  uiAmount: number;
}) {
  const decimals = 6; // 来自 mintInfo.decimals
  const rawAmount = BigInt(Math.round(uiAmount * (10 ** decimals)));

  // 获取发送者的 ATA 地址
  const fromAta = await getAssociatedTokenAddress(
    PYUSD_MINT,
    fromWallet.publicKey,
    false,
    TOKEN_2022_PROGRAM_ID
  );

  // 确保接收者的 Token-2022 ATA 已存在
  const toAta = await getOrCreateAssociatedTokenAccount(
    connection,
    fromWallet, // 付款人
    PYUSD_MINT,
    toPubkey,
    false,
    'confirmed',
    undefined,
    TOKEN_2022_PROGRAM_ID
  );

  const transferInstruction = createTransferCheckedInstruction(
    fromAta,                // 源 ATA
    PYUSD_MINT,             // 铸造地址
    toAta.address,          // 目标 ATA
    fromWallet.publicKey,   // 源 ATA 的所有者
    rawAmount,              // 原始单位金额
    decimals,               // 精度
    [],                     // 多签签署人
    TOKEN_2022_PROGRAM_ID   // <-- 重要
  );

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

  // 设置近期区块哈希和手续费支付者
  transaction.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
  transaction.feePayer = fromWallet.publicKey;

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

  console.log('交易成功，签名：', signature);
  return signature;
}

关于转账钩子 (Transfer Hook) 的说明： PYUSD 的铸造地址初始化了转账钩子扩展，但将其程序设置为 null。这意味着标准的转账目前无需额外的账户或逻辑即可运行。如果 PayPal/Paxos 激活了该钩子，他们将更新铸造地址以指向一个新程序。届时，您的集成将需要传递该程序接口所需的额外账户。

Solana CLI 快速测试​

如需在命令行中进行快速手动测试，可以使用带有正确程序 ID 的 spl-token。

# 确保您的 CLI 指向主网且您的密钥对有足够的资金。
# 向接收者转账 1.00 PYUSD。
spl-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  transfer 2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo 1.00 <RECIPIENT_PUBKEY> \
  --fund-recipient --allow-unfunded-recipient

跨链 PYUSD (Ethereum ↔ Solana)​

PayPal 使用 LayerZero 实施了官方跨链功能。这是一种原生的“销毁并铸造” (burn-and-mint) 流程，而不是依赖风险较高的第三方桥：PYUSD 在源链（如 Ethereum）上销毁，并在目标链（Solana）上铸造等量代币。这消除了特定于桥的风险和滑点。

您可以在官方 PayPal 开发者文档 中找到完整的教程和参数。

使用水龙头进行测试​

对于开发和测试，请勿使用主网资产。请使用官方水龙头：

  • Paxos PYUSD 水龙头： 用于获取测试网 PYUSD 代币。
  • Solana 水龙头： 用于获取开发网 / 测试网 SOL 以支付交易手续费。

常见陷阱（及解决方法）​

  1. 错误的程序 ID： 问题： 交易失败，报错 incorrect program id for instruction。解决方法： 显式地将 TOKEN_2022_PROGRAM_ID 传递给所有 spl-token 辅助函数（getOrCreateAssociatedTokenAccount、getAccount、createTransferCheckedInstruction 等）。
  2. 错误的 Mint 地址或伪造资产： 问题： 您的应用程序与伪造的 PYUSD 代币进行交互。解决方法： 硬编码并验证官方 Mint 地址：2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo。使用会在非规范 Mint 时发出警告的浏览器。
  3. 精度（Decimals）不匹配： 问题： 发送 1 PYUSD 实际上只发送了 0.000001 PYUSD。解决方法： 始终通过乘以 10^6 将 UI 金额转换为原始金额。为了安全起见，请通过程序化方式获取 Mint 的精度。
  4. 钩子（Hook）假设： 问题： 您为尚未激活的转账钩子预构建了复杂的逻辑。解决方法： 检查 Mint 的扩展数据。截至目前， PYUSD 的钩子为空。在构建系统时应具备适应性，以便在未来启用钩子程序时进行调整。

PYUSD + BlockEden.xyz 生产环境检查清单​

在迁移到生产环境时，请确保您的基础设施稳健。

  • RPC： 使用高可用的 BlockEden.xyz 端点。对于响应式 UX 使用 confirmed 确认级别，对于需要账本完整性的操作使用 finalized 进行查询。
  • 重试与幂等性： 使用指数退避重试机制包装交易提交。为每个业务操作存储幂等键，以防止重复转账。
  • 可观测性： 记录交易签名、Slot 编号和交易后余额。利用 BlockEden.xyz 的 WebSocket 订阅，为您的应用程序后端获取实时结算信号。
  • 合规性： Token-2022 提供了合规性原语。如果您需要实现诸如旅行规则（travel rule）之类的功能，扩展模型可以支持您干净地实现这些功能，同时保持业务逻辑与代币核心功能的分离。

附录 A — 快速参考​

  • Mint 地址（主网）： 2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo
  • 精度（Decimals）： 6
  • 代币程序 ID： TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
  • 背景： PayPal 于 2024 年 5 月 29 日宣布支持 Solana。
  • 官方文档： Solana Token Extensions, PayPal 开发者门户

附录 B — 直接 JSON-RPC 调用 (curl)​

获取 Mint 账户信息并确认所有者​

此调用检索 Mint 账户数据，并允许您验证其所有者是否为 Token-2022 程序。

替换为您的 BlockEden.xyz RPC URL

curl -s -X POST "$SOLANA_RPC_URL" -H 'content-type: application/json' -d '{
  "jsonrpc":"2.0","id":1,"method":"getAccountInfo",
  "params":["2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo",
    {"encoding":"base64","commitment":"confirmed"}]
}'

在 JSON 响应中，"owner" 字段应等于 "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb"。

列出用户的所有 PYUSD 代币账户​

这对于需要发现给定用户所有 PYUSD 持有情况的钱包非常有用。

curl -s -X POST "$SOLANA_RPC_URL" -H 'content-type: application/json' -d '{
  "jsonrpc":"2.0",
  "id":1,
  "method":"getTokenAccountsByOwner",
  "params":[
    "<OWNER_PUBLIC_KEY>",
    {"mint":"2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo"},
    {"encoding":"jsonParsed","commitment":"confirmed"}
  ]
}'

准备好开始构建了吗？获取您的高性能 BlockEden.xyz RPC 端点，从今天开始集成支付的未来。