Руководство по интеграции систем

СПРАВКА
В настоящее время эта документация находится в стадии разработки, и она регулярно дополняется.

Если вы предоставляете услуги блокчейна своим пользователям и хотите добавить блокчейн Aptos в свою платформу, то это руководство для вас. Это руководство для интеграции систем расскажет вам обо всем, что необходимо для интеграции блокчейна Aptos в вашу платформу. Это руководство предполагает, что вы знакомы с блокчейн.

Обзор

В этом руководстве рассматриваются следующие темы для интеграции с Aptos:

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

Давайте приступим к работе

Существует два хорошо поддерживаемых подхода для интеграции с блокчейном Aptos:

Локальная разработка с использованием нашего автономного тестнета
Devnet - общий ресурс для сообщества

Локальный тестнет
Существует два варианта запуска локальной сети тестирования:

Запустить локальную тестовую сеть напрямую, следуя этому руководству.
Использовать CLI: 1) установить с помощью CLI и 2) запустить локальную ноду с помощью faucet.

Это позволит открыть сервис REST API на http://127.0.0.1:8080/v1 и сервис Faucet на http://127.0.0.1:8000 для варианта 1 или http://127.0.0.1:8081 для варианта 2. Приложения будут выводить местоположение сервисов.

Доступ к Devnet

Сервис Faucet: https://faucet.devnet.aptoslabs.com/ Сервис REST API: https://fullnode.devnet.aptoslabs.com/v1

SDKs
В настоящее время Aptos имеет два SDK:

Другие направления
Использование CLI, включающее создание учетных записей, перевод coins и публикацию модулей
Typescript SDK
Python SDK
Спецификация REST API
Локальный поток разработки тестовой сети

Учетные записи на Aptos

Учетная запись представляет собой ресурс на блокчейне Aptos, который может отправлять транзакции. Каждая учетная запись идентифицируется определенным 32-байтовым адресом и является контейнером для модулей Move и ресурсов Move. В Aptos учетные записи должны быть созданы в сети перед любыми операциями в блокчейне с участием этой учетной записи. Фреймворк Aptos поддерживает косвенное создание учетных записей при переводе Aptos coin через aptos_account::transfer или прямое через aptos_account::create_account.

При создании учетная запись Aptos содержит:

Ресурс, содержащий Aptos Coin, а также депозит и вывод coins с этого ресурса.
Ключ аутентификации, связанный с текущим открытым и закрытым ключом (ключами).
Строго возрастающий порядковый номер, который представляет собой порядковый номер следующей транзакции учетной записи для предотвращения атак повтора.
Строго возрастающее число, представляющее собой следующий отдельный номер создания guid.
Поток событий для всех новых типов coins, добавленных на учетную запись.
Поток событий для всех ротаций ключей на учетной записи.

Идентификаторы учетных записей

В настоящее время Aptos поддерживает только один унифицированный идентификатор для учетной записи. Учетные записи на Aptos повсеместно представлены в виде 32-байтовой шестнадцатеричной строки. Шестнадцатеричная строка короче 32 байт также допустима, но в этом случае она дополняется ведущими нулями, например, 0x1 => 0x0000000000000...01.

Создание адреса учетной записи
Адреса учетных записей определяются во время создания как односторонняя функция от открытого ключа (ключей) и алгоритма подписи, используемых для аутентификации учетной записи.

ЧИТАТЬ БОЛЬШЕ
Это подробно описано в документации по учетным записям и продемонстрировано в Typescript SDK и Python SDK. Обратите внимание, что в настоящее время эти SDK демонстрируют только генерацию адреса от одного подписанта Ed25519.

Ротация ключей
В учетных записях на Aptos есть возможность ротации ключей, чтобы потенциально скомпрометированные ключи не могли быть использованы для доступа к учетным записям. Ключи можно повернуть с помощью функции account::rotate_authentication_key.

ЧИТАТЬ БОЛЬШЕ
Смотрите больше в разделе Адрес учетной записи.

Обновление ключей обычно считается хорошей гигиеной в области безопасности. Однако это представляет проблему для интеграции систем , которые привыкли использовать мнемонику для обозначения закрытого ключа и связанного с ним учетной записи. Чтобы упростить задачу для системных интеграторов, Aptos предоставит отображение в сети до запуска сети. Данные в сети сопоставляют эффективный адрес учетной записи, определенный текущей мнемоникой, с фактическим адресом учетной записи.

Предотвращение атак повтора

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

ЧИТАТЬ БОЛЬШЕ
Подробнее о порядковом номере учетной записи читайте здесь.

Транзакции

Транзакции Aptos кодируются в BCS (Binary Canonical Serialization). Транзакции содержат такую информацию, как адрес учетной записи отправителя, аутентификация отправителя, желаемая операция, которая должна быть выполнена на блокчейне Aptos, и количество газа, которое отправитель готов заплатить за выполнение транзакции.

Состояния транзакции
Транзакция может завершиться в одном из следующих состояний:

Зафиксирована в блокчейне и выполнена. Это считается успешной транзакцией.
Зафиксирована в блокчейне и прервана. Код прерывания указывает, почему транзакция не была выполнена.
Отклонена во время отправки транзакции из-за проверки валидности, такой как недостаточный газ, неверный формат транзакции или неверный ключ.
Отклонена после отправки транзакции, но до попытки выполнения. Это может быть связано с тайм-аутом или недостаточным количеством газа из-за других транзакций, затрагивающих учетную запись.

С учетной записи отправителя будет снят газ за все совершенные транзакции.

Во время отправки транзакции отправитель получает уведомление об успешной отправке или о причине неудачной проверки в противном случае.

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

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

В сети Aptos devnet время между отправкой и подтверждением составляет несколько секунд.

ЧИТАТЬ БОЛЬШЕ
Полное описание жизненного цикла транзакции смотрите здесь.

Создание транзакции

Aptos поддерживает два метода создания транзакций:

Создание JSON-кодированных объектов и взаимодействие с Web API для создания собственных транзакций.
Использование клиентских библиотек Aptos для создания собственных транзакций.

Транзакции в JSON-кодировке

Транзакции в кодировке JSON можно генерировать через REST API, выполнив следующие шаги:

Сначала создайте соответствующую полезную нагрузку JSON для конечной точки /transactions/encode_submission, как показано в Python SDK.
На выходе получается объект, содержащий message, которое должно быть локально подписано закрытым ключом отправителя.
Наконец, исходная полезная нагрузка JSON дополняется информацией о подписи и отправляется в конечную точку /transactions. В результате возвращается результат отправки транзакции, который, в случае успеха, содержит хэш транзакции в поле hash.

Транзакции в кодировке JSON обеспечивают быструю разработку и поддерживают бесшовные ABI-преобразования аргументов транзакций в собственные типы. Однако большинство системных интеграторов предпочитают генерировать транзакции в рамках собственного технологического стека. Как TypeScript SDK, так и Python SDK поддерживают генерацию транзакций BCS.

Транзакции с кодировкой BCS

Транзакции в кодировке BCS могут быть отправлены в конечную точку /transactions, но в HTTP-заголовках необходимо указать Content-Type: application/x.aptos.signed_transaction+bcs. Это вернет результат отправки транзакции, который, в случае успеха, будет содержать хэш транзакции в поле hash.

Типы транзакций
В рамках данной транзакции цель выполнения может быть одного из двух типов:

точка входа (ранее известная как функция скрипта), и/или
скрипт (полезная нагрузка).

В настоящее время SDK: Python и Typescript поддерживают только генерацию транзакций, нацеленных на точки входа. Это руководство указывает на многие из этих точек входа, такие как coin::transfer и aptos_account::create_account.

Все операции на блокчейне Aptos должны быть доступны через вызовы точек входа. Хотя можно последовательно отправить несколько транзакций, вызывающих точки входа, многие такие операции могут выиграть от атомарного вызова из одной транзакции. Транзакция с полезной нагрузкой криптовалюты может вызывать любую точку входа или публичную функцию, определенную в любом модуле.

КНИГА MOVE
В настоящее время в этом руководстве нет уроков по полезным нагрузкам скриптов, но в книге Move они рассматриваются довольно подробно.

ЧИТАТЬ БОЛЬШЕ
Смотрите следующую документацию по генерации правильных транзакций:

Транзакции в кодировке JSON с помощью Typescript, Python и Rust.
Пример перевода coin в кодировке BCS на языке Python.
Пример перевода coin в кодировке BCS на языке Typescript.
Публикация транзакций с помощью CLI.
Публикация вашего первого модуля Move с помощью Typescript, Python и Rust.

Статус транзакции

Статус транзакции можно узнать, запросив API [/transactions/by_hash/{hash}](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/get_transaction_by_hash) с хэшем, полученным при отправке транзакции.

Разумной стратегией для отправки транзакций является ограничение времени их жизни 30-60 секундами, и регулярный опрос API до успеха или через несколько секунд после истечения этого времени. Если в сети нет обязательств, транзакция, скорее всего, была отклонена.

Тестирование транзакций или предварительное выполнение транзакций
Чтобы облегчить оценку транзакций, Aptos поддерживает API моделирования, который не требует и не должен содержать действительных подписей на транзакциях.

API моделирования работает идентично API отправки транзакций, за исключением того, что он выполняет транзакцию и возвращает результаты вместе с использованным газом. Доступ к API моделирования можно получить, отправив транзакцию по адресу [/transactions/simulate](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/simulate_transaction).

ЧИТАТЬ БОЛЬШЕ
Вот пример, показывающий, как использовать API моделирования в Typescript SDK. Обратите внимание, что расход газа может меняться в зависимости от состояния учетной записи. Мы рекомендуем, чтобы максимальное количество газа было больше, чем количество, указанное в данном API.

Просмотр текущего и исторического состояния

Большинство интеграций в блокчейн Aptos выигрывают от целостного и всеобъемлющего обзора текущего и исторического состояния блокчейна. Aptos предоставляет исторические транзакции, состояние и события, которые являются результатом выполнения транзакций.

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

Сервис хранилища ноды использует две формы удаления данных с ноды:

состояние, и
события, транзакции и все остальное.

Хотя любую из этих функций можно отключить, хранение версий состояния не является особенно устойчивым.

Удаление событий и транзакций может быть отключено путем установки параметра [enable_ledger_pruner](https://github.com/aptos-labs/aptos-core/blob/cf0bc2e4031a843cdc0c04e70b3f7cd92666afcf/config/src/config/storage_config.rs#L141)) в false. Это будет поведение по умолчанию в Mainnet. В ближайшем будущем Aptos предоставит индексаторы, которые уменьшат необходимость прямого запроса с ноды.

REST API содержит следующие полезные API для запросов транзакций и событий:

Обмен и отслеживание coins

В Aptos есть стандартный тип Coin. Различные типы монет могут быть представлены в этом типе с помощью отдельных структур, которые представляют параметр типа или generic для Coin<T>.

Coins хранятся внутри аккаунта в ресурсе CoinStore<T>. При создании учетной записи каждый пользователь имеет ресурс CoinStore<0x1::aptos_coin::AptosCoin> или сокращенно CoinStore<AptosCoin>. Внутри этого ресурса находится Aptos coin: Coin<AptosCoin>.

Передача coins между пользователями
Coins можно переводить между пользователями с помощью функции [coin::transfer](https://github.com/aptos-labs/aptos-core/blob/36a7c00b29a457469264187d8e44070b2d5391fe/aptos-move/framework/aptos-framework/sources/coin.move#L307) для всех coins и [aptos_account::transfer](https://github.com/aptos-labs/aptos-core/blob/88c9aab3982c246f8aa75eb2caf8c8ab1dcab491/aptos-move/framework/aptos-framework/sources/aptos_account.move#L18) для Aptos coins. Преимущество последней функции в том, что она создает учетную запись назначения, если она не существует.

ВНИМАНИЕ
Важно отметить, что если учетная запись не зарегистрировала CoinStore<T> для данного T, то любой перевод типа T на эту учетную запись будет неудачным.

Текущий баланс для coin
Текущий баланс для Coin<T>, где T - Aptos coin, доступен на url ресурсов учетной записи: https://{rest_api_server}/accounts/{address}/resource/0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>. Баланс хранится в ресурсе coin::amount. Ресурс также содержит общее количество событий депозита и вывода средств, значение counter в deposit_event и withdraw_event соответственно.

{
  "type": "0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>",
  "data": {
    "coin": {
      "value": "3927"
    },
    "deposit_events": {
      "counter": "1",
      "guid": {
        "id": {
          "addr": "0xcb2f940705c44ba110cd3b4f6540c96f2634938bd5f2aabd6946abf12ed88457",
          "creation_num": "1"
        }
      }
    },
    "withdraw_events": {
      "counter": "1",
      "guid": {
        "id": {
          "addr": "0xcb2f940705c44ba110cd3b4f6540c96f2634938bd5f2aabd6946abf12ed88457",
          "creation_num": "2"
        }
      }
    }
  }
}

Запрос событий

Aptos предоставляет четкие и канонические события для всех случаев вывода и депозита coins. Это может быть использовано в координации с соответствующими транзакциями, чтобы представить пользователю изменение баланса его учетной записи с течением времени, когда это произошло и что послужило причиной. С помощью некоторого количества дополнительных разборов можно также передавать метаданные, такие как тип транзакции и другие участвующие стороны.

События можно запросить по url: https://{rest_api_server}/accounts/{address}/events/0x1::coin::CoinStore<0x1::aptos_coin::AptosCoin>/withdraw_events.

[
  {
    "version":"13629679",
    "key": "0x0200000000000000cb2f940705c44ba110cd3b4f6540c96f2634938bd5f2aabd6946abf12ed88457",
    "sequence_number": "0",
    "type": "0x1::coin::WithdrawEvent",
    "data": {
      "amount": "1000"
    }
  }
]

Дополнительную информацию можно получить из транзакции, которая породила событие. Для этого выполните запрос: https://{rest_server_api}/transactions/by_version/{version}, где {version} - то же значение, что и {version} в запросе события.

{
  "version": "13629679",
  "gas_used": "4",
  "success": true,
  "vm_status": "Executed successfully",
  "changes": [
    ...
  ],
  "sender": "0x810026ca8291dd88b5b30a1d3ca2edd683d33d06c4a7f7c451d96f6d47bc5e8b",
  "sequence_number": "0",
  "max_gas_amount": "2000",
  "gas_unit_price": "1",
  "expiration_timestamp_secs": "1660616127",
  "payload": {
    "function": "0x1::coin::transfer",
    "type_arguments": [
      "0x1::aptos_coin::AptosCoin"
    ],
    "arguments": [
      "0x5098df8e7969b58ab3bd2d440c6203f64c60a1fd5c08b9d4abe6ae4216246c3e",
      "1000"
    ],
    "type": "entry_function_payload"
  },
  "events": [
    {
      "key": "0x0200000000000000810026ca8291dd88b5b30a1d3ca2edd683d33d06c4a7f7c451d96f6d47bc5e8b",
      "sequence_number": "0",
      "type": "0x1::coin::WithdrawEvent",
      "data": {
        "amount": "1000"
      }
    },
    {
      "key": "0x01000000000000005098df8e7969b58ab3bd2d440c6203f64c60a1fd5c08b9d4abe6ae4216246c3e",
      "sequence_number": "0",
      "type": "0x1::coin::DepositEvent",
      "data": {
        "amount": "1000"
      }
    }
  ],
  "timestamp": "1660615531147935",
  "type": "user_transaction"
}

Транзакция, в свою очередь, предоставляет другую важную информацию для создания полной картины того, что вызвало событие. Например, она дает timestamp, когда была выполнена транзакция, другие связанные события и gas_used. Транзакции содержат всю необходимую информацию для представления пользователю, включая события, время выполнения и внесенные изменения.

ПОДСКАЗКА
При отслеживании полного движения coins обычно достаточно событий. 0x1::aptos_coin::AptosCoin, однако, требует также просматривать gas_used для каждой транзакции, отправленной с данной учетной записи. Чтобы уменьшить ненужные накладные расходы, извлечение платы за газ, связанной с транзакциями, не вызывает события. Все транзакции для учетной записи могут быть получены из этого API: https://{rest_server_api}/accounts/{address}/transactions.

Чтобы создать несколько образцов данных для изучения, смотрите руководство "Ваша первая транзакция".

Чтобы узнать больше о создании coin, смотрите раздел "Ваш первый Coin".

Blog