PYUSD на Solana: Практическое руководство по интеграции (с BlockEden.xyz RPC)
PayPal USD (PYUSD) появился на Solana, что знаменует собой важную веху для цифровых платежей. Это руководство предлагает прямое, ориентированное на производство пошаговое описание для инженеров, интегрирующих PYUSD в кошельки, dApps и коммерческие платформы на Solana.
Все примеры используют актуальный код, совместимый с Token-2022, и разработаны для бесперебойной работы с RPC-конечными точками Solana от BlockEden.xyz с низкой задержкой.
TL;DR
- Что: PayPal USD (PYUSD) теперь является нативным токеном SPL стандарта Token-2022 на Solana, предлагая быстрые и недорогие расчеты для всемирно признанного стейблкоина.
- Ключевые параметры: Минт
2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo, десятичные знаки6и токен-програм маToken-2022. - Набор функций: Использует расширения токенов Solana (Token-2022). Имеет инициализированный, но в настоящее время неактивный Transfer Hook (нулевая программа), а также возможности конфиденциальной передачи и другие расширения.
- Кроссчейн: Официальная интеграция LayerZero позволяет PYUSD перемещаться между Ethereum и Solana через безопасный механизм сжигания и минтинга, минуя традиционные мосты.
- Действие: Используйте это руководство как готовый шаблон для добавления поддержки PYUSD в ваше приложение с помощью надежного Solana RPC от BlockEden.xyz.
Почему PYUSD на Solana важен
Сочетание бренда PayPal с производительностью Solana создает мощную новую основу для цифровых долларов.
- Доверие потребителей встречается с удобством использования криптовалют: PYUSD выпускается регулируемой трастовой компанией Paxos и глубоко интегрирован в PayPal и Venmo. Это предоставляет пользователям знакомый актив. Они могут хранить единый баланс PYUSD и выбирать вывод средств на внешний кошелек как в Ethereum, так и в Solana, абстрагируясь от сложности блокчейна.
- Готовые к платежам рельсы: Архитектура Solana обеспечивает финализацию транзакций менее чем за секунду и комиссии, составляющие доли цента. PYUSD накладывает стабильную, узнаваемую единицу учета поверх этой эффективной расчетной сети, что делает его идеальным для платежей, коммерции и денежных переводов.
- Контроль институционального уровня: Запускаясь как токен Token-2022, PYUSD может использовать встроенные расширения для таких функций, как конфиденциальные переводы, расширенные метаданные и постоянный делегат. Это обеспечивает расширенное соответствие требованиям и функциональность без необходимости в индивидуальных, трудно поддающихся аудиту смарт-контрактах.
Самое главное (Запомните это)
Прежде чем написать хоть одну строку кода, зафиксируйте эти параметры. Всегда проверяйте адрес минта в надежном эксплорере, чтобы избежать взаимодействия с мошенническими токенами.
- Минт (Mainnet):
2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo - Десятичные знаки:
6(что означает 1 PYUSD = 1 000 000 базовых единиц) - Токен-программа:
Token-2022(ID программы:TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb) - Используемые расширения токенов (при минтинге):
- Метаданные и указатель метаданных
- Постоянный делегат
- Transfer Hook (инициализирован с нулевой программой)
- Конфигурация конфиденциальной передачи
Вы можете проверить все это в Solana Explorer. Эксплорер четко покажет официальный адрес минта и его включенные расширения.
Настройка проекта
Подгот овим наше окружение. Вам понадобятся последние библиотеки Solana web3 и SPL token для обеспечения полной совместимости с Token-2022.
1. Библиотеки
Установите необходимые пакеты из npm.
npm i @solana/web3.js @solana/spl-token
2. RPC-соединение
Направьте ваше приложение на URL-адрес RPC Solana Mainnet от BlockEden.xyz. Для продакшена переменные окружения обязательны.
// 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";
// Используйт е ваш URL-адрес RPC Solana от BlockEden.xyz из вашей панели управления
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 (основная сеть)
export const PYUSD_MINT = new PublicKey(
"2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo",
);
Чтение данных минта PYUSD
Сначала программно подтвердим свойства минта PYUSD. Это важный первый шаг для проверки правильности ваших констант и получения таких деталей, как общий объем предложения.
// Подтверждение информации о минте PYUSD через API Token-2022
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)
Связанные токен-аккаунты (ATA) для токенов Token-2022 должны быть получены с использованием ID программы Token-2022. Если вы используете устаревший TOKEN_PROGRAM_ID, транзакции завершатся ошибкой "incorrect program id".
// Плательщик и владелец нового ATA. Замените на вашу логику кошелька.
const owner = Keypair.generate();
// Создать или получить ATA PYUSD владельца (с учетом Token-2022)
const ownerAta = await getOrCreateAssociatedTokenAccount(
connection,
owner, // Плательщик за создание
PYUSD_MINT, // Минт
owner.publicKey, // Владелец ATA
false, // allowOwnerOffCurve
"confirmed",
undefined, // опции
TOKEN_2022_PROGRAM_ID, // <-- ВАЖНО: Используйте ID программы Token-2022
);
console.log("ATA PYUSD владельца:", 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; // десятичные знаки = 6
console.log("Баланс PYUSD:", balance);
Использование прямого JSON-RPC (curl)
Вы также можете проверить все токен-аккаунты для владельца и отфильтровать их по ID программы 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" }
]
}'
Передача PYUSD (от пользователя к пользователю)
Общее правило для передачи любого актива Token-2022 — использовать createTransferCheckedInstruction. Эта инструкция включает десятичные знаки токена, предотвращая потенциальные уязвимости, связанные с десятичными знаками.
Вот полная, многократно используемая функция для передачи 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
);
// Убедитесь, что ATA получателя существует для Token-2022
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);
// Установить последний blockhash и плательщика комиссии
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 инициализирует расширение Transfer Hook, но устанавливает его программу в null. Это означает, что стандартные переводы в настоящее время работают без дополнительных аккаунтов или логики. Если PayPal/Paxos когда-либо активируют хук, они обновят минт, чтобы он указывал на новую программу. Ваша интеграция тогда должна будет передавать дополнительные аккаунты, требуемые интерфейсом этой программы.
Быстрый тест Solana CLI
Для быстрого ручного тестирования из командной строки вы можете использовать spl-token с правильным ID программы.
# Убедитесь, что ваш CLI указывает на основную сеть и ваш keypair профинансирован.
# Перевести 1.00 PYUSD получателю.
spl-token --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
transfer 2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo 1.00 <RECIPIENT_PUBKEY> \
--fund-recipient --allow-unfunded-recipient
Кроссчейн PYUSD (Ethereum ↔ Solana)
PayPal реализовал официальный кроссчейн-механизм с использованием LayerZero. Вместо того чтобы полагаться на рискованные сторонние мосты, это нативный процесс сжигания и минтинга: PYUSD сжигается в исходной цепочке (например, Ethereum), и эквивалентная сумма минтится в целевой цепочке (Solana). Это устраняет риски, специфичные для мостов, и проскальзывание.
Полное руководство и параметры вы можете найти в официальной документации для разработчиков PayPal.
Тестирование с кранами
Для разработки и тестирования не используйте активы основной сети. Используйте официальные краны:
- Кран Paxos PYUSD: Для получения тестовых токенов PYUSD.
- Кран Solana: Для получения SOL в devnet/testnet для оплаты комиссий за транзакции.
Распространенные ошибки (и их исправления)
- Неправильный ID программы: Проблема: Транзакции завершаются ошибкой
incorrect program id for instruction. Исправление: Явно передавайтеTOKEN_2022_PROGRAM_IDвсем вспомогательным функциямspl-token(getOrCreateAssociatedTokenAccount,getAccount,createTransferCheckedInstructionи т.д.). - Неправильный минт или поддельные активы: Проблема: Ваше приложение взаимодействует с поддельным токеном PYUSD. Исправление: Жестко закодируйте и проверьте официальный адрес минта:
2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo. Используйте эксплорер, который предупреждает о неканонических минтах. - Несоответствие десятичных знаков: Проблема: Отправка 1 PYUSD фактически отправляет 0.000001 PYUSD. Исправление: Всегда конвертируйте суммы пользовательского интерфейса в сырые суммы, умножая на
10^6. Для безопасности программно получайте десятичные знаки минта. - Предположения о хуке: Проблема: Вы заранее создаете сложную логику для Transfer Hook, который не активен. Исправление: Проверьте данные расширения минта. На сегодняшний день хук PYUSD равен null. Создайте свою систему так, чтобы она адаптировалась, если программа хука будет включена в будущем.
Контрольный список для продакшена PYUSD + BlockEden.xyz
При переходе в продакшн убедитесь, что ваша инфраструктура надежна.
- RPC: Используйте высокодоступную конечную точку BlockEden.xyz. Используйте уровень подтверждения
confirmedдля отзывчивого пользовательского интерфейса и запросы сfinalizedдля операций, требующих целостности реестра. - Повторные попытки и идемпотентность: Оберните отправку транзакций механизмом повторных попыток с экспоненциальной задержкой. Храните ключ идемпотентности с каждой бизнес-операцией для предотвращения дублирования переводов.
- Наблюдаемость: Регистрируйте подписи транзакций, номера слотов и балансы после транзакций. Используйте подписки BlockEden.xyz на веб-сокеты для получения сигналов о расчетах в реальном времени для бэкенда вашего приложения.
- Соответствие требованиям: Token-2022 предоставляет примитивы для соответствия требованиям. Если вам нужно реализовать такие функции, как правило путешествий (travel rule), модель расширений позволяет сделать это чисто, сохраняя вашу бизнес-логику отдельно от основной функциональности токена.
Приложение A — Краткий справочник
- Минт (Mainnet):
2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo - Десятичные знаки:
6 - ID программы токена:
TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb - Предыстория: PayPal объявил о поддержке Solana 29 мая 2024 года.
- Официальная документация: Расширения токенов Solana, Портал разработчиков PayPal
Приложение B — Прямые вызовы JSON-RPC (curl)
Получить информацию об аккаунте минта и подтвердить владельца
Этот вызов извлекает данные аккаунта ми нта и позволяет вам убедиться, что его владельцем является программа Token-2022.
# Замените на ваш URL-адрес RPC BlockEden.xyz
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"}
]
}'
Готовы к созданию? Возьмите свою высокопроизводительную RPC-конечную точку BlockEden.xyz и начните интегрировать будущее платежей уже сегодня.