Основы блокчейна для разработчиков

Здесь разобрано, как адреса, публичные ключи, суммы и подтверждения представлены в API Vilna. Опыт работы с блокчейном не требуется. Уже знакомы с этими понятиями? Начните с Основных концепций.

Забудьте на минуту про хайп. Для интеграции блокчейн - это просто общая книга записей, которую все могут читать и которую никто не может тайком изменить. Новые транзакции продолжают эту историю; реорганизации могут заменить недавние блоки.

Три свойства - всё, что нужно держать в голове:

Публичный реестр позволяет наблюдать за адресом без разрешения владельца кошелька. Мониторинг Platform читает эти публичные данные.

Читать сеть самостоятельно означает держать узлы, индексировать блоки, обрабатывать реорганизации и декодировать каждый формат транзакций, и всё это для каждой сети. Platform делает это для поддерживаемых сетей и отдаёт нормализованные данные. Мониторинг Platform наблюдает за сетью:

Для обычного адреса, управляемого одним приватным ключом, связь ключей и адреса можно представить так:

Вывод для интеграции: адресом и публичным ключом делиться безопасно, приватным - нет. Мониторинг Platform использует публичную сторону: передайте публичный ключ или адрес для наблюдения. Приватный ключ ему не нужен.

Формат адреса может подсказать семейство сетей, но сам адрес не определяет сеть. Перед отправкой проверяйте и идентификатор сети, и адрес:

Одна удобная деталь EVM-сетей: единый адрес 0x… работает в каждой EVM-сети. Тот же адрес Ethereum может принимать средства в Polygon, Arbitrum или Base без каких-либо изменений.

Когда вы регистрируете адрес в Vilna, вы передаёте input.chain_family (evm, bitcoin или tron; solana регистрирует адрес и распознаёт его токены, без балансов и транзакций), а точный формат определяется из самого значения автоматически; эндпоинты см. в Platform API.

Реальным продуктам нужен свежий адрес на каждого клиента, иногда тысячи адресов. Генерировать и резервировать тысячи независимых секретов неуправляемо. HD-кошельки (иерархические детерминированные) решают это одним стартовым секретом.

Вы начинаете с одной seed-фразы, обычно 12 или 24 слова. Из этого seed кошелёк может сгенерировать бесконечное дерево пар ключей. Детерминированность означает, что один и тот же seed всегда даёт одни и те же ключи, в том же порядке, всегда. Путь деривации - это маршрут вниз по дереву к одному конкретному ключу: выберите ветку на каждом уровне и придёте к единственному адресу:

Одна резервная копия seed-фразы охватывает все производные адреса; отдельный адрес для каждого клиента используется в сценарии мониторинга биржи.

Чтобы Vilna могла генерировать и наблюдать это дерево адресов, ни разу не касаясь секрета, вы делитесь расширенным публичным ключом: особым публичным ключом, который умеет порождать дочерние адреса (и только адреса, никогда подписи). У Bitcoin три разновидности, по одной на стиль адреса:

Для EVM-сетей используется xPub (BIP-44). У Bitcoin Taproot нет однобуквенного префикса; используйте xPub с путём Taproot ниже.

Путь деривации - это «адрес внутри дерева», как путь к папке, указывающий на один конкретный ключ. Читается слева направо, сужаясь от мастер-ключа до единственного адреса:

Апостроф (') после числа означает hardened (ужесточённый): защита, которая не даёт по дочернему ключу вычислить родительский. Чаще всего вы будете копировать проверенные пути, а не собирать их вручную:

Импортируйте расширенный публичный ключ через POST/public-keys, затем вызовите POST/public-keys/{public_key_id}/addresses с "chain_family": "evm", "selection": {"kind": "next"} в теле запроса, чтобы получить следующий адрес последовательности. Каждый автоматически ставится на мониторинг.

Большинство кошельков умеют экспортировать расширенный публичный ключ. Три самых частых источника:

Экспортируйте публичный ключ средствами своего кошелька. Не передавайте Vilna seed-фразу или приватные ключи. Затем зарегистрируйте расширенный публичный ключ и выведите адреса; параметры и примеры запросов находятся на страницах операций.

При десятках сетей и тысячах токенов фразы вроде «USDT в BSC» коду недостаточно, чтобы действовать однозначно: есть тестовые сети, мостовые копии и похожие по виду контракты. Поэтому Vilna опирается на два открытых стандарта, превращающих любую сеть или актив в одну точную, однозначную строку, о которой вы и API договариваетесь: CAIP-2 называет сеть, а CAIP-19 называет актив в этой сети.

Вручную их почти не печатают; Vilna возвращает их готовыми в каждом ответе. Здесь цель только в том, чтобы узнавать такую строку при встрече. Читайте слева направо: сеть, за которой опционально следует актив на ней.

Одно различие стоит держать в голове, потому что оно определяет, как работают балансы и комиссии. У каждой сети есть одна встроенная валюта плюс любое число токенов поверх:

Список поддерживаемых сетей доступен через Platform API.

Блокчейны хранят суммы целыми числами в наименьшей единице монеты (думайте «копейки», а не «рубли», но часто с 18 знаками после запятой). Во многих суммах транзакций и балансов есть два поля:

{
  "base": "1500000000000000000",
  "formatted": "1.5"
}

• base - сырое целое в наименьшей единице (wei для ETH, satoshi для BTC). Точное, никогда не округляется.
• formatted - человекочитаемое десятичное число, готовое к выводу в интерфейсе.

Поля сумм счетов устроены иначе; см. Основные концепции.

Отправка транзакции, включение в блок и подтверждение - разные этапы. Ниже показана модель подсчёта подтверждений по блокам; правила конкретной сети могут отличаться:

Финальность (finality) - свойство сети, определяющее, при каких условиях результат считается необратимым. Правила подтверждений и финальности различаются между сетями. Выберите политику подтверждений для своего приложения: фиксированное число блоков не даёт универсальной гарантии.