Перейти к основному содержимому

Интеграция выплат в USDT ERC-20 в Ethereum

Добавьте на сайт форму массовых выплат: отправитель подключает свой кошелёк, указывает получателей и суммы в USDT, проверяет комиссию и подписывает пакет выплат. Контракт выплат Volet.com отправляет USDT ERC-20 с кошелька отправителя прямо на кошельки получателей, поэтому средства не проходят через аккаунт Volet.com.

Это руководство описывает основную сеть Ethereum (Ethereum Mainnet). Для других сетей см. TRON и BNB Smart Chain.

Перед началом​

  • Кошелёк отправителя — MetaMask или другой браузерный кошелёк, совместимый с EIP-1193. В примерах используется MetaMask в Google Chrome.
  • Средства на кошельке отправителя — USDT ERC-20 на выплаты и комиссию за обработку, а также ETH на комиссии сети. Чтобы сделать форму, пополнять кошелёк не нужно: платит отправитель, когда отправляет пакет выплат.
  • Библиотека — ethers.js v6. SDK Volet.com не нужен.
  • Сайт — по HTTPS или на localhost во время разработки.
  • Бэкенд и база данных — чтобы хранить каждый пакет выплат и проверять выплаты.
  • RPC-провайдер — узел Ethereum Mainnet или сервис для проверки на бэкенде.

Как это работает​

  1. Отправитель заполняет форму выплат на вашем сайте: адреса получателей, суммы в USDT и, при необходимости, адрес партнёра.
  2. Отправитель подключает кошелёк. Его приватный ключ вашему сайту не нужен.
  3. Ваш фронтенд проверяет пакет выплат и получает комиссию за обработку из контракта через previewCommission().
  4. Сайт показывает сумму выплат, комиссию за обработку, сколько всего нужно USDT, и оценку комиссии сети.
  5. Когда отправитель подтверждает выплату, фронтенд проверяет баланс USDT и разрешение (allowance). Если разрешения не хватает, кошелёк сначала просит отправителя подписать транзакцию approve().
  6. Фронтенд ещё раз проверяет комиссию, кошелёк, сеть и получателей, затем кошелёк просит отправителя подписать batchPayout().
  7. Бэкенд сохраняет хеш транзакции (txid) и проверяет перевод USDT каждому получателю, прежде чем отметить его выплату как выполненную.

Если выплата одному получателю не прошла, остальные не обязательно отменяются, поэтому успешная транзакция не доказывает, что деньги получили все. См. Шаг 7. Проверьте каждую выплату.

Контракт выплат​

Значение
СетьEthereum Mainnet, chain ID 1 (0x1)
Контракт выплат0x765A0cd00e07C23d1f760BDc794940967Bc6ccC7 (Etherscan)
Контракт USDT0xdAC17F958D2ee523a2206206994597C13D831ec7
Знаков после запятой у USDT6 (1 USDT = 1 000 000 базовых единиц)
Чем оплачивается комиссия сетиETH
Нулевой адрес (без партнёра)0x0000000000000000000000000000000000000000

Тот же адрес контракта выплат есть и в BNB Smart Chain. Это разные развёртывания, они не взаимозаменяемы: прежде чем запрашивать подпись, всегда проверяйте chain ID кошелька и результат usdt() контракта.

Функции контракта:

function usdt() external view returns (address);
function MAX_BATCH_SIZE() external view returns (uint256);
function paused() external view returns (bool);
function previewCommission(uint256 total, uint256 count)
external view returns (uint256 commission);
function previewCommissionSplit(uint256 total, uint256 count, address whiteLabel)
external view returns (uint256 platformCommission, uint256 partnerShare);
function getPartner(address partner)
external view returns (bool active, uint16 shareBps);
function batchPayout(
address[] calldata recipients,
uint256[] calldata amounts,
address whiteLabel
) external;

Контракт генерирует события BatchPayout, PayoutFailed, RefundSent, PartnerNotFound и CommissionTransferFailed. PayoutFailed перечисляет получателей и суммы, которые не были выплачены.

Сверьтесь с ABI контракта

В примерах на этой странице только те функции и события, которые в них используются. Перед интеграцией откройте контракт выплат на Etherscan, возьмите полный ABI на вкладке Contract и сверьте с ним сигнатуры функций, типы параметров и события в своём коде. Перед отправкой реальных средств также сравните с этой страницей адрес токена из usdt(), число знаков токена, результаты previewCommission() и события контракта.

Комиссии​

Комиссия за обработку — 0.1 USDT за каждого получателя в пакете, сверх сумм выплат. Например, пакету, который выплачивает 10, 20 и 30 USDT трём получателям, нужно 60 USDT на выплаты и 0.3 USDT на комиссию: всего 60.3 USDT.

Всегда показывайте отправителю актуальное значение из previewCommission(), а не комиссию, рассчитанную в вашем коде.

Кроме того, отправитель платит комиссию сети Ethereum в ETH за каждую транзакцию: выплату и, если нужно, одобрение.

Адрес партнёра​

batchPayout() принимает аргумент whiteLabel — необязательный кошелёк партнёра, который получает долю комиссии за обработку. Без партнёра пакет тоже работает: передайте нулевой адрес.

Если партнёр есть, передайте адрес его кошелька. getPartner() показывает, активен ли партнёр и какова его доля в базисных пунктах, а previewCommissionSplit() — как комиссия делится между Volet.com и партнёром. Комиссия для отправителя от этого не меняется: previewCommission() от партнёра не зависит.

Чтобы зарегистрировать кошелёк партнёра, напишите на [email protected], указав адрес кошелька и сеть.

Шаг 1. Добавьте форму выплат​

Установите ethers.js:

npm install ethers@^6

Добавьте элементы формы на страницу. Каждый блок data-payout-row — один получатель; добавляйте и удаляйте блоки, чтобы менять число получателей.

<input id="partner-wallet" type="text" placeholder="Partner wallet (optional)">
<div data-payout-row>
<input name="address" type="text" placeholder="Recipient address">
<input name="amount" type="text" placeholder="USDT amount">
</div>
<button id="connect" type="button">Connect wallet</button>
<button id="preview" type="button">Preview payouts</button>
<button id="send" type="button">Send payouts</button>
<pre id="summary"></pre>

Перед запуском формы в продакшен добавьте свои стили, управление строками, индикаторы выполнения и блокировку кнопок.

Шаг 2. Подключите кошелёк отправителя​

Создайте браузерный модуль ethereum-payouts.js и начните его с настроек контракта и функции подключения. Шаги 3 и 4 дополняют этот же файл.

import { ethers } from 'ethers';

const CHAIN_ID = 1n;
const PAYOUT_ADDRESS = '0x765A0cd00e07C23d1f760BDc794940967Bc6ccC7';
const USDT_ADDRESS = '0xdAC17F958D2ee523a2206206994597C13D831ec7';
export const USDT_DECIMALS = 6;
const EXPLORER_TX = 'https://etherscan.io/tx/';

export const PAYOUT_ABI = [
'function usdt() view returns (address)',
'function MAX_BATCH_SIZE() view returns (uint256)',
'function paused() view returns (bool)',
'function previewCommission(uint256 total, uint256 count) view returns (uint256)',
'function previewCommissionSplit(uint256 total, uint256 count, address whiteLabel) view returns (uint256 platformCommission, uint256 partnerShare)',
'function getPartner(address partner) view returns (bool active, uint16 shareBps)',
'function batchPayout(address[] recipients, uint256[] amounts, address whiteLabel)',
'event BatchPayout(address indexed sender, uint256 total, uint256 commission, uint256 partnerShare, uint256 count, address indexed whiteLabel)',
'event PayoutFailed(address[] recipients, uint256[] amounts)',
'event RefundSent(address indexed sender, uint256 amount)',
'event PartnerNotFound(address indexed whiteLabel)',
'event CommissionTransferFailed(address indexed wallet, uint256 amount)'
];

const TOKEN_ABI = [
'function decimals() view returns (uint8)',
'function balanceOf(address owner) view returns (uint256)',
'function allowance(address owner, address spender) view returns (uint256)',
'function approve(address spender, uint256 amount) returns (bool)'
];

export async function connect() {
if (!window.ethereum) throw new Error('Install and unlock MetaMask.');
await window.ethereum.request({ method: 'eth_requestAccounts' });

const provider = new ethers.BrowserProvider(window.ethereum);
if ((await provider.getNetwork()).chainId !== CHAIN_ID) {
throw new Error('Select Ethereum Mainnet in your wallet, then connect again.');
}

const signer = await provider.getSigner();
const sender = await signer.getAddress();
const payout = new ethers.Contract(PAYOUT_ADDRESS, PAYOUT_ABI, signer);

// Make sure this deployment pays out the expected token.
const tokenAddress = await payout.usdt();
if (tokenAddress.toLowerCase() !== USDT_ADDRESS.toLowerCase()) {
throw new Error('Unexpected USDT token in the payout contract.');
}
const token = new ethers.Contract(tokenAddress, TOKEN_ABI, signer);
if (Number(await token.decimals()) !== USDT_DECIMALS) {
throw new Error('Unexpected token decimals.');
}

return { sender, payout, token };
}

// Signatures go only to the wallet and network the batch was reviewed with.
async function assertWalletUnchanged(session) {
const [chainId, accounts] = await Promise.all([
window.ethereum.request({ method: 'eth_chainId' }),
window.ethereum.request({ method: 'eth_accounts' })
]);
if (BigInt(chainId) !== CHAIN_ID ||
accounts[0]?.toLowerCase() !== session.sender.toLowerCase()) {
throw new Error('Wallet or network changed. Connect again and review the batch.');
}
}

Вызывайте connect(), только когда отправитель нажимает Connect wallet, а не при загрузке страницы. Если кошелёк в другой сети, попросите отправителя переключиться на Ethereum Mainnet.

Шаг 3. Покажите пакет выплат и комиссию​

Добавьте в ethereum-payouts.js функции проверки и предпросмотра. quote() превращает строки формы в аргументы контракта в базовых единицах USDT и получает комиссию, баланс и разрешение.

function parseRows(rows) {
if (!Array.isArray(rows) || rows.length === 0) {
throw new Error('Add at least one recipient.');
}
const recipients = rows.map((row) => {
if (!ethers.isAddress(row.address)) throw new Error(`Invalid recipient address: ${row.address}`);
const address = ethers.getAddress(row.address);
if (address === ethers.ZeroAddress) throw new Error('The zero address cannot receive a payout.');
return address;
});
const amounts = rows.map((row) => {
if (typeof row.amount !== 'string' || !/^\d+(\.\d{1,6})?$/.test(row.amount)) {
throw new Error(`Invalid USDT amount: ${row.amount}`);
}
const amount = ethers.parseUnits(row.amount, USDT_DECIMALS);
if (amount <= 0n) throw new Error('Each amount must be positive.');
return amount;
});
return { recipients, amounts };
}

export async function quote(session, rows, partnerWallet = null) {
const { payout, token, sender } = session;
const { recipients, amounts } = parseRows(rows);

if (await payout.paused()) throw new Error('The payout contract is paused.');
if (BigInt(recipients.length) > await payout.MAX_BATCH_SIZE()) {
throw new Error('The batch has more recipients than the contract allows.');
}
if (partnerWallet && !ethers.isAddress(partnerWallet)) {
throw new Error('Invalid partner address.');
}
const whiteLabel = partnerWallet ? ethers.getAddress(partnerWallet) : ethers.ZeroAddress;

const total = amounts.reduce((sum, amount) => sum + amount, 0n);
const commission = await payout.previewCommission(total, recipients.length);
const [platformCommission, partnerShare] = await payout.previewCommissionSplit(
total, recipients.length, whiteLabel
);

return {
recipients, amounts, whiteLabel, total, commission,
platformCommission, partnerShare,
required: total + commission,
balance: await token.balanceOf(sender),
allowance: await token.allowance(sender, PAYOUT_ADDRESS)
};
}

Покажите отправителю total, commission и required, отформатированные через ethers.formatUnits(value, USDT_DECIMALS), вместе с оценкой комиссии сети в ETH. Не пересчитывайте суммы с плавающей точкой: parseUnits() сохраняет их точными.

Проверьте получателей перед подписью

Выплату на неверный адрес нельзя отменить или вернуть. Перед подписью покажите отправителю каждый адрес и сумму и принимайте только адреса Ethereum, которые могут получать USDT ERC-20.

Шаг 4. Одобрите USDT и отправьте пакет выплат​

Добавьте в ethereum-payouts.js функцию отправки. Она проверяет, что после просмотра пакета ничего не изменилось, запрашивает одобрение, если разрешения не хватает, и затем отправляет batchPayout().

function sameBatch(a, b) {
return a.required === b.required &&
a.whiteLabel === b.whiteLabel &&
a.recipients.length === b.recipients.length &&
a.recipients.every((address, i) => address === b.recipients[i] && a.amounts[i] === b.amounts[i]);
}

async function confirmed(tx, message) {
const receipt = await tx.wait();
if (!receipt || receipt.status !== 1) throw new Error(message);
}

export async function send(session, rows, reviewed, partnerWallet = null) {
const { payout, token } = session;

await assertWalletUnchanged(session);
const current = await quote(session, rows, partnerWallet);
if (!sameBatch(current, reviewed)) {
throw new Error('The batch or the fee changed. Review the updated quote.');
}
if (current.balance < current.required) throw new Error('Not enough USDT in the sender wallet.');

if (current.allowance < current.required) {
// Ethereum USDT rejects changing a non-zero allowance to another non-zero value.
if (current.allowance > 0n) {
await confirmed(await token.approve(PAYOUT_ADDRESS, 0n), 'Allowance reset failed.');
}
await confirmed(await token.approve(PAYOUT_ADDRESS, current.required), 'USDT approval failed.');
}

// The fee can change while the approval confirms. Check again before the payout signature.
await assertWalletUnchanged(session);
const fresh = await quote(session, rows, partnerWallet);
if (!sameBatch(fresh, reviewed) ||
fresh.balance < fresh.required ||
fresh.allowance < fresh.required) {
throw new Error('The fee, balance or allowance changed. Review the batch before retrying.');
}

const tx = await payout.batchPayout(fresh.recipients, fresh.amounts, fresh.whiteLabel);
return { txid: tx.hash, explorerUrl: EXPLORER_TX + tx.hash };
}

В зависимости от текущего разрешения отправитель подписывает от одной до трёх транзакций:

Текущее разрешениеТранзакции на подпись
Хватает на пакетВыплата
НулевоеОдобрение, выплата
Ненулевое, но недостаточноеСброс разрешения до нуля, одобрение, выплата

Одобрение покрывает ровно сумму этого пакета, а не неограниченную сумму. Каждое одобрение должно подтвердиться до следующей транзакции; транзакция approve() средства не переводит.

Шаг 5. Подключите кнопки​

Свяжите модуль с формой. Запросы к кошельку отправляются только по нажатию отправителя, а получатели и суммы всегда берутся из формы.

import { ethers } from 'ethers';
import { USDT_DECIMALS, connect, quote, send } from './ethereum-payouts.js';

const $ = (selector) => document.querySelector(selector);
let session = null;
let reviewed = null;

function readRows() {
return [...document.querySelectorAll('[data-payout-row]')].map((row) => ({
address: row.querySelector('[name="address"]').value.trim(),
amount: row.querySelector('[name="amount"]').value.trim()
}));
}

function readPartner() {
return $('#partner-wallet').value.trim() || null;
}

function usdt(units) {
return `${ethers.formatUnits(units, USDT_DECIMALS)} USDT`;
}

function show(text) {
$('#summary').textContent = text;
}

// A quote is valid only for the wallet and network it was made with.
function resetSession() {
session = null;
reviewed = null;
show('Wallet or network changed. Connect again.');
}
window.ethereum?.on?.('accountsChanged', resetSession);
window.ethereum?.on?.('chainChanged', resetSession);

async function onConnect() {
session = await connect();
reviewed = null;
show(`Connected: ${session.sender}`);
}

async function onPreview() {
if (!session) throw new Error('Connect a wallet first.');
reviewed = await quote(session, readRows(), readPartner());
show([
`Payouts: ${usdt(reviewed.total)}`,
`Processing fee: ${usdt(reviewed.commission)}`,
`Total required: ${usdt(reviewed.required)}`
].join(' | '));
}

async function onSend() {
if (!session || !reviewed) throw new Error('Connect a wallet and preview the batch first.');
if (!window.confirm('Send this batch? Your wallet will ask you to sign each transaction.')) return;
const result = await send(session, readRows(), reviewed, readPartner());
reviewed = null;
show(`Submitted: ${result.explorerUrl}`);
// Send result.txid to your backend together with the batch, then verify it (Step 7).
}

for (const [id, handler] of [['#connect', onConnect], ['#preview', onPreview], ['#send', onSend]]) {
$(id).addEventListener('click', () => {
handler().catch((error) => show(error.shortMessage ?? error.message ?? String(error)));
});
}

Если отправитель изменит форму после предпросмотра, send() остановится с ошибкой «The batch or the fee changed», и отправителю нужно будет посмотреть пакет снова.

Шаг 6. Сохраните пакет выплат​

Сохраняйте каждый пакет на бэкенде до того, как отправитель его подпишет, и никогда не перезаписывайте. Храните:

  • собственный ID пакета
  • сеть и chain ID
  • адрес отправителя
  • список получателей и точные суммы в базовых единицах USDT
  • адрес партнёра или нулевой адрес
  • рассчитанную комиссию за обработку
  • хеши транзакций одобрения, если они были
  • хеш транзакции выплаты (txid)
  • итоговый статус каждого получателя

batchPayout() не принимает ID пакета, поэтому связь пакета с его транзакцией есть только в вашей базе данных. Используйте её против дублей: если транзакция ещё в обработке, отслеживайте её txid и не отправляйте тот же пакет повторно.

Шаг 7. Проверьте каждую выплату​

Хеш транзакции показывает только, что пакет отправлен. Успешная квитанция (receipt) или событие BatchPayout тоже не доказывают, что деньги получили все: если выплата одному получателю не прошла, остальные не обязательно отменяются, а контракт сообщает об этом событием PayoutFailed и может вернуть средства отправителю событием RefundSent.

Бэкенд сверяет каждого получателя с логами Transfer USDT в транзакции. Пример ниже работает в Node.js с ethers v6. Пакет выплат он берёт из вашей базы данных, а не из браузера.

import { ethers } from 'ethers';
import { PAYOUT_ABI } from './ethereum-payouts.js';

const provider = new ethers.JsonRpcProvider(process.env.ETHEREUM_RPC_URL);
const PAYOUT_ADDRESS = '0x765A0cd00e07C23d1f760BDc794940967Bc6ccC7';
const USDT_ADDRESS = '0xdAC17F958D2ee523a2206206994597C13D831ec7';

const tokenEvents = new ethers.Interface([
'event Transfer(address indexed from, address indexed to, uint256 value)'
]);
const payoutEvents = new ethers.Interface(PAYOUT_ABI);

export async function verifyPayout(batch) {
const receipt = await provider.getTransactionReceipt(batch.txid);
if (!receipt) return { status: 'pending' };
if (receipt.status !== 1) return { status: 'failed' };

if (receipt.to?.toLowerCase() !== PAYOUT_ADDRESS.toLowerCase() ||
receipt.from.toLowerCase() !== batch.sender.toLowerCase()) {
return { status: 'review', reason: 'Unexpected sender or contract.' };
}

const finalized = await provider.getBlock('finalized');
if (!finalized || receipt.blockNumber > finalized.number) return { status: 'pending' };

const received = new Map();
const failed = [];
let refunded = 0n;
for (const log of receipt.logs) {
const source = log.address.toLowerCase();
if (source === USDT_ADDRESS.toLowerCase()) {
const event = tokenEvents.parseLog(log);
if (event?.name !== 'Transfer') continue;
const to = event.args.to.toLowerCase();
received.set(to, (received.get(to) ?? 0n) + event.args.value);
} else if (source === PAYOUT_ADDRESS.toLowerCase()) {
const event = payoutEvents.parseLog(log);
if (event?.name === 'PayoutFailed') failed.push(...event.args.recipients);
if (event?.name === 'RefundSent') refunded += event.args.amount;
}
}

const expected = new Map();
batch.recipients.forEach((address, i) => {
const key = address.toLowerCase();
expected.set(key, (expected.get(key) ?? 0n) + BigInt(batch.amounts[i]));
});

const results = [...expected].map(([address, amount]) => ({
address,
expected: amount.toString(),
received: (received.get(address) ?? 0n).toString(),
paid: received.get(address) === amount
}));

return {
status: results.every((result) => result.paid) ? 'paid' : 'partial',
results,
failed,
refunded: refunded.toString()
};
}

Отмечайте как выполненные только выплаты получателям с paid: true. Для остальных сверьте события PayoutFailed и RefundSent и проверьте баланс отправителя, прежде чем платить им новым пакетом. Никогда не отправляйте весь пакет повторно автоматически.

Эта проверка охватывает переводы получателям. В продакшене бэкенд также сверяет входные данные транзакции с сохранённым пакетом, проверяет события партнёра и комиссии и обрабатывает случаи, когда RPC-провайдер недоступен или не возвращает данные о финальности: оставьте пакет в ожидании и повторите проверку.

Важно​

  • Никогда не просите у отправителей приватные ключи или сид-фразы. Все подписи выполняются в кошельке отправителя.
  • Никогда не запрашивайте по умолчанию неограниченное одобрение USDT.
  • Перед каждой подписью показывайте адрес контракта выплат, получателей, комиссию за обработку и оценку комиссии сети.
  • Кошелёк — последний шаг подтверждения. Проверять результат должно ваше приложение.
  • Подтверждённые транзакции в блокчейне нельзя отменить или отозвать.

Если что-то пошло не так​

ПроблемаПричинаЧто делать
«Install and unlock MetaMask»В браузере нет кошелька EIP-1193 или он заблокированПопросите отправителя установить или разблокировать кошелёк.
«Select Ethereum Mainnet in your wallet»Кошелёк в другой сетиПопросите отправителя переключиться на Ethereum Mainnet и подключиться снова. Не запрашивайте подписи в другой сети.
Отправитель отклоняет подключение, одобрение или выплатуОтправитель отменил запрос в кошелькеНе отправляйте пакет и покажите понятное сообщение.
«Invalid recipient address» или «Invalid USDT amount»В строке формы ошибкаЗаблокируйте предпросмотр и отправку, пока отправитель не исправит данные получателя.
«Not enough USDT in the sender wallet»Баланс меньше суммы выплат и комиссииПокажите, сколько всего нужно, и сколько ETH требуется на комиссии сети.
Одобрение ещё в обработкеТранзакция одобрения ещё не подтвержденаДождитесь подтверждения. Не считайте одобрение выполненным только по хешу транзакции.
Транзакция выплаты ещё в обработкеТранзакция ещё не в финализированном блокеОтслеживайте исходный txid. Не отправляйте тот же пакет повторно.
Транзакция прошла успешно, но у получателя нет USDTВыплата этому получателю не прошлаОтмечайте как выполненные только проверенные переводы. Перед новым пакетом сверьте неудавшиеся выплаты и возврат, если он был.
«The batch or the fee changed»После предпросмотра изменились форма, комиссия или настройки партнёраПокажите пакет снова и попросите отправителя проверить новые суммы.
«The payout contract is paused»Выплаты в контракте временно остановленыНе отправляйте пакет. Повторите попытку позже.