ERC-20-адреса на всех EVM-сетях

ERC20-адрес: формат, balanceOf и создание через API

ERC20-адрес — это 42-символьный адрес аккаунта с префиксом 0x, который Ethereum использует для каждого кошелька. Он становится ERC-20-адресом, когда на аккаунте лежат токены по стандарту ERC-20. Та же строка работает в Polygon и Arbitrum, потому что они совместимы с EVM, но токены и балансы относятся к конкретной сети.

7 дней бесплатно — для начала не нужна карта и KYC Некастодиальный — приватные ключи остаются под вашим контролем Тарифы от 49 €/мес (490 €/год) — посмотреть тарифы и лимиты запросов

Баланс ERC-20 возвращает вызов balanceOf(address) к контракту токена. Через REST то же значение, уже декодированное, отдаёт запрос GET /api/v2/ethereum/balances/{address}/erc20/{contract_address}. Чтобы получать токены, достаточно передать отправителю адрес. Чтобы отправлять их, нужны приватный ключ этого адреса и небольшой запас ETH для оплаты газа.

На странице разобраны формат адреса, balanceOf, тот же адрес в Polygon и Arbitrum и создание адресов через REST.

Что такое стандарт ERC-20?

ERC-20 — стандартный интерфейс взаимозаменяемых токенов в Ethereum. EIP-20 определяет шесть функций: totalSupply, balanceOf, transfer, transferFrom, approve и allowance, а также события Transfer и Approval. Любой контракт, который их реализует, считается совместимым токеном. Поэтому кошельки и биржи поддерживают новый токен без отдельной доработки под него.

Тот же интерфейс с примерами разбирает обзор ERC-20 на ethereum.org. Полный механизм описан в нашей статье о стандарте токенов ERC20. Эта страница посвящена адресу: что такое ERC-20-адрес и как работать с ним в коде.

Как выглядит ERC-20-адрес?

ERC-20-адрес — это обычный адрес Ethereum, например 0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed. Это 0x и 40 шестнадцатеричных символов, всего 42 символа. Документация ethereum.org об аккаунтах описывает его как последние 20 байт хеша Keccak-256 от открытого ключа аккаунта.

Название появляется только в контексте. Адрес становится «ERC-20-адресом», когда речь идёт о токенах на нём. Ничто в строке не указывает, что адрес может хранить токены, и тот же адрес работает для ETH, для всех токенов ERC-20 и для NFT.

0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed 1 2 3
  1. Префикс 0x показывает, что значение записано в шестнадцатеричной системе.
  2. 40 шестнадцатеричных символов — это 20 байт: последние 20 байт хеша Keccak-256 от открытого ключа.
  3. Всего 42 символа. Сочетание заглавных и строчных букв — это контрольная сумма EIP-55.
Строение EVM-адреса. Ethereum, Polygon и Arbitrum используют одну и ту же раскладку.

Как balanceOf читает баланс ERC-20?

balanceOf(address) — функция только для чтения, которая возвращает баланс токена на адресе. Баланс хранится не в адресе. Он лежит в смарт-контракте токена, в отображении с адресом в роли ключа, и balanceOf находит его там.

Прямой вызов требует закодировать JSON-RPC-запрос eth_call к контракту токена и декодировать возвращённый hex. Результат представляет собой целое число в наименьшей единице токена, поэтому нужно прочитать ещё и decimals(). У многих стейблкоинов 6 знаков после запятой, у других 18, и ошибка здесь — частая причина багов с разницей в миллион раз.

Chaingateway API берёт кодирование и работу с десятичными знаками на себя. Эндпоинты балансов возвращают обычные числа, поэтому задача с сырым RPC превращается в обычный ответ REST.

Действителен ли один ERC-20-адрес в Polygon и Arbitrum?

Да. Polygon и Arbitrum совместимы с EVM, поэтому их адреса используют тот же формат 0x. Адрес, полученный из одного приватного ключа, — одна и та же строка в Ethereum, Polygon и Arbitrum.

Токены на этом адресе при этом не общие. Контракт токена, развёрнутый в Ethereum, не существует в Polygon, пока кто-нибудь не развернёт его там или не переведёт актив через мост. Поэтому балансы привязаны к сети, даже когда адрес один. Токены в Polygon следуют тому же интерфейсу ERC-20, и один путь в коде обслуживает все три сети.

ERC-721 и ERC-721A: другой стандарт, тот же формат адреса

ERC-721 — стандарт невзаимозаменяемых токенов в Ethereum. У каждого токена свой уникальный ID, в отличие от взаимозаменяемых балансов ERC-20. Интерфейс описан в EIP-721.

ERC-721A — реализация того же интерфейса, оптимизированная по газу и популярная у коллекций, которые выпускают пакетами. Она меняет внутреннее хранение данных в контракте, но не вид адреса владельца. Оба стандарта указывают владельца одним и тем же адресом 0x. Тему NFT подробно разбирает статья о стандарте токенов ERC721.

Создание и чтение ERC-20-адресов через REST

Шесть маршрутов покрывают жизненный цикл адреса в платёжной интеграции.

ЭндпоинтЧто делает
POST /api/v2/ethereum/addressesСгенерировать новый адрес Ethereum
POST /api/v2/ethereum/addresses/importИмпортировать приватный ключ, чтобы API мог подписывать от имени этого адреса
GET /api/v2/ethereum/balances/{address}/erc20/{contract_address}Баланс одного токена ERC-20, уже декодированный
GET /api/v2/ethereum/balances/{address}/erc20Балансы всех токенов кошелька
POST /api/v2/ethereum/webhooksЗарегистрировать вебхук на депозиты ERC-20 на этот адрес
POST /api/v2/ethereum/transactions/erc20Отправить токен ERC-20 с этого адреса

Тот же вид запроса работает с /polygon/ или /arbitrum/ вместо /ethereum/ в пути, так как у всех трёх сетей общие формат адреса и интерфейс ERC-20.

Чтение баланса ERC-20 без eth_call

Адрес контракта ниже — это USDT в мейннете Ethereum. Добавьте X-Network: testnet, чтобы запросить токен в тестовой сети.

cURL
curl https://app.chaingateway.io/api/v2/ethereum/balances/0xYourAddress/erc20/0xdAC17F958D2ee523a2206206994597C13D831ec7 \
  -H "Authorization: Bearer YOUR_API_KEY"

Как проверить ERC-20-адрес перед отправкой?

Сначала сопоставьте строку с шаблоном ^0x[a-fA-F0-9]{40}$: он отсекает неверную длину и лишние символы. Если в адресе смешаны заглавные и строчные буквы, проверьте и контрольную сумму EIP-55. Одна неверная буква тогда не пройдёт проверку.

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

Нужны балансы ERC-20 без ручного декодирования вызовов balanceOf? Создайте бесплатный аккаунт и запросите адрес в testnet через REST. 7-дневный пробный период, без карты и без KYC.

FAQ: ERC-20-адреса

Формат адреса Ethereum с префиксом 0x и 42 символами, который используется для любого аккаунта, держит он токены ERC-20 или нет. ERC-20-адресом его называют по контексту, когда речь именно о токенах на нём.

Набор функций (transfer, approve, balanceOf и другие), которые реализует любой контракт взаимозаменяемого токена в Ethereum. Благодаря этому кошельки и биржи поддерживают новые токены без отдельного кода под каждый.

balanceOf(address) — функция только для чтения, которую предоставляет каждый контракт ERC-20. Прямой вызов означает eth_call к контракту токена и декодирование hex-ответа, а Chaingateway API сразу возвращает декодированный баланс.

Polygon — это блокчейн, а не токен, но он совместим с EVM, поэтому токены в нём реализуют тот же интерфейс ERC-20, что и токены Ethereum, а адрес в Polygon использует тот же формат 0x.

Оптимизированная по газу реализация стандарта NFT ERC-721, распространённая у коллекций, которые выпускают пакетами. Она меняет внутреннее хранение в контракте, но не формат адреса: владение по-прежнему привязано к обычному адресу 0x.

Готовы строить на Ethereum, Polygon или Arbitrum?

Создайте аккаунт и запросите баланс ERC-20 в testnet уже сегодня. 7-дневный пробный период, без карты и без KYC. Полный справочник — в документации Ethereum API, а все семь сетей закрывает мультичейн blockchain API.

Проверил(а) Maurice Sobiera Как мы пишем эти страницы