1 запись с тегом "integration"

PYUSD на Solana: Практическое руководство по интеграции (с BlockEden.xyz RPC)

24 августа 2025 г. · 9 мин. чтения

Software Engineer

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 и начните интегрировать будущее платежей уже сегодня.

API Marketplace Featured

TL;DR​

Почему PYUSD на Solana важен​

Самое главное (Запомните это)​

Настройка проекта​

1. Библиотеки​

2. RPC-соединение​

Чтение данных минта PYUSD​

Создание или получение связанных токен-аккаунтов (ATA)​

Проверка балансов PYUSD​

Использование @solana/spl-token​

Использование прямого JSON-RPC (curl)​

Передача PYUSD (от пользователя к пользователю)​

Быстрый тест Solana CLI​

Кроссчейн PYUSD (Ethereum ↔ Solana)​

Тестирование с кранами​

Распространенные ошибки (и их исправления)​

Контрольный список для продакшена PYUSD + BlockEden.xyz​

Приложение A — Краткий справочник​

Приложение B — Прямые вызовы JSON-RPC (curl)​

Получить информацию об аккаунте минта и подтвердить владельца​

Перечислить все токен-аккаунты PYUSD для пользователя​