На этой странице объясняются концепции блокчейна, с которыми вы столкнётесь при интеграции с Vilna API. Это не общее руководство по блокчейну — здесь рассматривается только то, что необходимо для эффективной работы с Vilna. Если вы уже знаете, как работают адреса, ключи и пути деривации, переходите к разделу Основные концепции.
Адрес похож на номер банковского счёта — это идентификатор, на который поступает криптовалюта. Каждый блокчейн имеет собственный формат адресов, и по формату можно определить, к какой сети принадлежит адрес.
EVM-сети (Ethereum, Polygon, BSC, Arbitrum, Optimism, Base, Avalanche) используют единый формат: префикс 0x, за которым следуют 40 шестнадцатеричных символов, итого 42 символа. Один и тот же адрес работает во всех EVM-сетях — если у вас есть адрес Ethereum, вы можете получать токены в Polygon или Arbitrum по тому же адресу. Это одно из ключевых преимуществ экосистемы EVM.
Bitcoin имеет несколько форматов адресов в зависимости от эпохи и технологии:
| Формат | Начинается с | Пример |
|---|---|---|
| Legacy (P2PKH) | 1 | 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa |
| Compatibility (P2SH) | 3 | 3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy |
| Native SegWit (P2WPKH) | bc1q | bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq |
TRON — адреса начинаются с T и имеют длину 34 символа.
Solana — адреса представляют собой строки в кодировке base58, обычно длиной около 44 символов.
При добавлении адреса в Vilna вы указываете chainFamily (evm, bitcoin, solana или tron), а формат адреса определяется автоматически по его значению. Поддерживаемые форматы адресов: evm, p2pkh, p2wpkh, p2wsh, p2sh, solana и tron.
Приватный ключ можно сравнить с паролем от банковского счёта. Любой, кто им владеет, может распоряжаться средствами. Публичный ключ выводится из приватного с помощью односторонних математических преобразований — из приватного можно получить публичный, но не наоборот.
Адрес, в свою очередь, выводится из публичного ключа. Полная цепочка выглядит так:
Приватный ключ — единственный элемент, который должен оставаться в секрете. Публичный ключ и адрес можно свободно передавать другим.
Vilna никогда не запрашивает ваш приватный ключ. Для мониторинга адресов и отслеживания балансов Vilna требуется только публичный ключ или сам адрес. Когда вы импортируете публичный ключ в Vilna, вы предоставляете возможность генерировать и отслеживать адреса, а не распоряжаться средствами.
Для подписания транзакций Vilna Widget хранит приватный ключ локально в вашем браузерном расширении. Ключ никогда не покидает ваше устройство и никогда не отправляется на серверы Vilna.
Управление сотнями или тысячами отдельных приватных ключей непрактично. HD-кошельки решают эту проблему, генерируя дерево ключей из одного мастер-сида.
Идея следующая: вы начинаете с одного секрета (сид-фразы, обычно из 12 или 24 слов). Из этого сида кошелёк может детерминированно сгенерировать неограниченное количество пар ключей. «Детерминированно» означает, что один и тот же сид всегда создаёт одни и те же ключи в одном и том же порядке.
Практическая выгода значительна. Вместо резервного копирования тысяч ключей вы сохраняете одну сид-фразу. Вместо импорта адресов по одному вы импортируете один расширенный публичный ключ и генерируете адреса по мере необходимости.
Именно так работают биржи и платёжные процессоры. Они генерируют уникальный адрес для пополнения для каждого клиента, и все адреса выведены из одного мастер-ключа.
Расширенный публичный ключ — это особая форма публичного ключа, способная генерировать дочерние адреса. Существует три варианта, каждый привязан к определённому формату адреса:
| Префикс ключа | Стандарт | Тип адреса |
|---|---|---|
xPub | BIP-44 | Legacy-адреса (начинаются с 1) |
yPub | BIP-49 | SegWit-совместимые адреса (начинаются с 3) |
zPub | BIP-84 | Native SegWit-адреса (начинаются с bc1) |
Для EVM-сетей (Ethereum, Polygon и др.) используется xPub с деривацией BIP-44.
Эти ключи безопасно передавать Vilna. Расширенный публичный ключ может только генерировать адреса и отслеживать балансы. Он не может подписывать транзакции или перемещать средства.
Когда вы импортируете xPub в Vilna через POST /public_keys, вы можете затем вызвать POST /public_keys/{public_key_id}/addresses/next для генерации следующего адреса в последовательности. Каждый новый адрес автоматически регистрируется для мониторинга.
Путь деривации — это инструкция, указывающая кошельку, какой ветке дерева ключей следовать при генерации адресов. Представьте его как путь к папке в файловой системе — он точно описывает, где в дереве находится конкретный ключ.
Формат выглядит так:
m— корень (мастер-ключ)purpose— идентификатор стандарта (44, 49 или 84)coin_type— идентификатор блокчейна (число из реестра SLIP-44)account— позволяет использовать несколько аккаунтов в одном кошельке (обычно0)'(апостроф) после числа означает «усиленный» (hardened) — функция безопасности, которая предотвращает восстановление родительского ключа из дочерних
Вот распространённые пути, с которыми вы столкнётесь:
| Путь | Блокчейн | Стандарт |
|---|---|---|
m/44'/60'/0' | Ethereum и все EVM-сети | BIP-44 |
m/44'/0'/0' | Bitcoin Legacy | BIP-44 |
m/49'/0'/0' | Bitcoin SegWit-совместимый | BIP-49 |
m/84'/0'/0' | Bitcoin Native SegWit | BIP-84 |
m/44'/195'/0' | TRON | BIP-44 |
m/44'/501'/0' | Solana | BIP-44 |
Числа coin_type определены стандартом SLIP-44: 60 для Ethereum, 0 для Bitcoin, 195 для TRON, 501 для Solana.
Краткое руководство по выбору: Если вы работаете с EVM-сетями, используйте m/44'/60'/0'. Для Bitcoin используйте m/84'/0'/0' (современный Native SegWit), если у вас нет конкретных причин использовать устаревший формат.
Ledger Live: Откройте аккаунт, перейдите в расширенные настройки и найдите «Extended Public Key».
Trezor Suite: Откройте аккаунт и выберите «Show xPub».
MetaMask: MetaMask — это кошелёк на основе аккаунтов, который не поддерживает экспорт xPub. Вместо этого вы можете импортировать отдельные адреса из MetaMask в Vilna как внешние адреса.
Если вы генерируете кошельки в коде, xPub можно получить следующим образом:
import { generateMnemonic, mnemonicToSeedSync } from "bip39";
import BIP32Factory from "bip32";
import * as ecc from "tiny-secp256k1";
const bip32 = BIP32Factory(ecc);
// Generate a new wallet (store the mnemonic securely)
const mnemonic = generateMnemonic();
const seed = mnemonicToSeedSync(mnemonic);
const root = bip32.fromSeed(seed);
// Derive the xPub for Ethereum (BIP-44, coin type 60)
const account = root.derivePath("m/44'/60'/0'");
const xpub = account.neutered().toBase58();
// xpub looks like: xpub6CUGRUonZSQ4TWtTMm...
// Import this xPub into Vilna to generate addressesХраните мнемоническую фразу (сид-фразу) в безопасности и никогда не допускайте её попадания в код, логи или системы контроля версий. Vilna нужен только xPub.
Vilna группирует блокчейны в семейства, объединённые общими характеристиками.
EVM-сети — Ethereum, BSC, Polygon, Arbitrum, Optimism, Base, Avalanche и другие. Все используют одинаковый формат адресов и модель транзакций. Один EVM-адрес работает во всех этих сетях.
Bitcoin-подобные сети — Bitcoin, Litecoin, Dogecoin. Используют модель UTXO (Unspent Transaction Output) и поддерживают несколько форматов адресов. Каждый формат имеет свои компромиссы с точки зрения комиссий и совместимости.
Solana — уникальный формат адресов и другая модель транзакций, основанная на аккаунтах, а не на UTXO.
TRON — внутренне похож на EVM, но работает как отдельная сеть с собственным форматом адресов, начинающихся с T.
Vilna идентифицирует каждую сеть с помощью идентификаторов CAIP-2:
| Идентификатор | Сеть |
|---|---|
eip155:1 | Ethereum |
eip155:56 | BNB Smart Chain |
eip155:137 | Polygon |
eip155:42161 | Arbitrum One |
bip122:000000000019d6689c085ae165831e93 | Bitcoin |
solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp | Solana |
Полный список поддерживаемых сетей см. в разделе Основные концепции.
Каждый блокчейн имеет нативную валюту — она используется для оплаты комиссий за транзакции и существует без смарт-контракта. ETH в Ethereum, BTC в Bitcoin, SOL в Solana, TRX в TRON.
Токены — это дополнительные валюты, построенные поверх блокчейна с помощью смарт-контрактов. USDT, USDC, DAI и тысячи других — всё это токены. Они работают на базе инфраструктуры основного блокчейна.
В EVM-сетях токены следуют стандартизированным интерфейсам:
- ERC-20 — взаимозаменяемые токены (каждая единица идентична, как доллары)
- ERC-721 — невзаимозаменяемые токены (каждый уникален, как предметы с серийными номерами)
TRON имеет аналогичный стандарт TRC-20.
Vilna идентифицирует каждый актив — нативный или токен — с помощью идентификатора CAIP-19:
eip155:1/slip44:60 - ETH on Ethereum
eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7 - USDT on Ethereum
eip155:56/erc20:0x55d398326f99059fF775485246999027B3197955 - USDT on BSCСуммы в API всегда возвращаются в двух форматах:
{
"base": "1500000000000000000",
"formatted": "1.5"
}Значение base — это необработанная сумма в наименьшей единице токена (как копейки по отношению к рублям, но часто с 18 десятичными знаками). Значение formatted — это то, что видит человек. Используйте base для вычислений и хранения; используйте formatted для отображения.
Когда кто-то отправляет транзакцию, она не становится окончательной мгновенно. Вот что происходит:
- Транзакция транслируется в сеть и попадает в зону ожидания, называемую мемпулом. На этом этапе она считается «ожидающей» (pending).
- Майнер или валидатор включает транзакцию в блок. Это первое подтверждение.
- Каждый новый блок, добавленный в цепочку после этого блока, — дополнительное подтверждение.
Чем больше подтверждений, тем выше уверенность в том, что транзакция не будет отменена. Различные блокчейны требуют разное количество подтверждений, прежде чем транзакция считается безопасной:
| Сеть | Обычно требуемое количество подтверждений |
|---|---|
| Bitcoin | ~6 |
| Ethereum | ~12 |
| BSC | ~15 |
| Polygon | ~128 |
Vilna автоматически отслеживает прогресс подтверждений. При настройке уведомлений через вебхуки Vilna уведомит вас, когда транзакция достигнет необходимого порога подтверждений для соответствующей сети.
- Быстрый старт — выполните первый API-запрос и начните мониторинг адреса
- Основные концепции — терминология Vilna и паттерны API
- Паттерны интеграции — типовые архитектуры: обнаружение депозитов, управление HD-кошельками
- Platform API — полная документация по эндпоинтам