Solana 上的 PYUSD：实用集成指南（配合 BlockEden.xyz RPC）
· 阅读需 10 分钟
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 的高性能相结合，为数字美元创造了一条强大的新路径。
- 消费者信任与加密货币用户体验的结合： PYUSD 由受监管的信托公司 Paxos 发行，并深度集成到 PayPal 和 Venmo 中。这为用户提供了一个熟悉的资产。他们可以持有单一的 PYUSD 余额，并选择提现到以太坊或 Solana 上的外部钱包，从而抽象掉了链的复杂性。
- 支付就绪的轨道： Solana 的架构提供了秒级以下的交易确认和不足一分钱的费用。PYUSD 在这种高效的结算网络之上增加了一个稳定、可识别的记账单位，使其成为支付、商业和汇款的理想选择。
- 机构级控制： 通过作为 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 以支付交易手续费。
常见陷阱（及解决方法）
- 错误的程序 ID： 问题： 交易失败，报错 incorrect program id for instruction。解决方法： 显式地将 TOKEN_2022_PROGRAM_ID 传递给所有 spl-token 辅助函数（getOrCreateAssociatedTokenAccount、getAccount、createTransferCheckedInstruction 等）。
- 错误的 Mint 地址或伪造资产： 问题： 您的应用程序与伪造的 PYUSD 代币进行交互。解决方法： 硬编码并验证官方 Mint 地址：2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo。使用会在非规范 Mint 时发出警告的浏览器。
- 精度（Decimals）不匹配： 问题： 发送 1 PYUSD 实际上只发送了 0.000001 PYUSD。解决方法： 始终通过乘以 10^6 将 UI 金额转换为原始金额。为了安全起见，请通过程序化方式获取 Mint 的精度。
- 钩子（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 端点，从今天开始集成支付的未来。