Перейти к содержанию

Blockchain Connector XLM Service API

Обзор

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

Параметры запросов, встроенные в url, например, идентификатор блокчейна, являются обязательными. Параметры в query string или JSON теле запроса могут быть опциональными и подробно описаны в соответствующих разделах.

Адрес сервера: https://cloud.spatium.net/blockchain-connector-xlm/v1 Swagger

Для данного адреса сервера доступно взаимодействие с блокчейном Stellar (xlm).

Структура запросов и информации в ответах для них одинакова.

Типы данных

Network

Network - тип сети. Как правило, блокчейны поддерживают минимум два варианта: тестовая сеть для разработки (testnet) с фиктивными активами и стабильная рабочая сеть (livenet) с реальными активами.

Структура данных:

type Network = 'livenet' | 'testnet';

API

Генерация адреса из публичного ключа

Swagger Get address

Структура запроса

POST /api/get-address/xlm

{
   publicKey: string;
   network?: Network;
   prefix?: boolean;
}

{
  requestId: string;
  data: {
    address: string;
  };
}

Параметры

  • publicKey - публичный ключ, обязательный параметр (строка);

  • network - тип сети, необязательный параметр, значение по умолчанию 'livenet' (Network);

  • prefix - наличие префикса в адресе, необязательный параметр, значение по умолчанию false (логическое значение).

Получение данных для формирования транзакции

Swagger Prepare transaction API

Для формирования транзакции Stellar необходимо указать только максимальный размер комиссии. Это означает что указывается сумма, которую пользователь готов заплатить за данную транзакцию, но по факту взиматься будет только минимальная необходимая сумма, достаточная для того, чтобы транзакция была обработана. При отсутствии нагрузки на сеть будет уплачиваться только минимум - в текущий момент он составляет 100 stroops[^1] на одну операцию, соответственно передаваемая для формирования транзакции комиссия не может быть меньше этого значения.

Комиссия сети

Swagger Prepare transaction FeeStat

Для указания максимального размера комиссии при формировании транзакции полезно ориентироваться на статистику текущих комиссий сети. Данный эндпоинт предоставляет данные об уплаченных по факту минимальной и максимальной комиссиях за последние 5 реестров сети.

Примечание

Существуют различные стратегии формирования максимальной комиссии, однако стоит учитывать, что транзакция с невысокой максимальной комиссией не будет обработана при нагрузке на сеть, поэтому мы ориентируем пользователей на значение статистической максимальной комиссии с добавлением небольшого запаса - текущей минимальной комиссии за операцию (feeCharged.max + lastLedgerBaseFee), при этом оставляя возможность указать любое значение комиссии вручную.

Структура запроса

GET api/prepare-transaction/fee-stat/xlm/?network={network}

{
   network: Network;
}

{
 requestId: string;
 data: {
   lastLedgerBaseFee: string;
   feeCharged: { 
    min: string;
    max: string;
   };
 };
}
Параметры
  • network - тип сети, необязательный параметр, значение по умолчанию 'livenet' (Network).

Получение хэша транзакции

Получение хэша транзакции отправки валюты

Данный эндпоинт поддерживает отправку нативной валюты блокчейна, а также любых ассетов Stellar. При отправке нативной валюты проверяется наличие аккаунта с конечным адресом в сети, при его отсутствии происходит автоматическое создание этого аккаунта со стартовым балансом равным переданному в запросе amount, иначе выполняется обычный перевод средств.

Важно

В соответствии с логикой работы сети Stellar нельзя отправить валюту на несуществующий в сети аккаунт (необходимо сначала создать этот аккаунт). Данный эндпоинт автоматически определяет наличие аккаунта в сети и и при необходимости создает его, предупреждения об отсутствии аккаунта в сети не будет! Если вам необходимо оповестить пользователя об отсутствии аккаунта с данным адресом в сети Stellar, вы можете воспользоваться дополнительным эндпоинтом проверки существования аккаунта (метод checkXLMAccount).

Структура запроса

POST api/transaction/get-hash/xlm/transfer

{
  publicKey: string;
  network?: Network;
  to: string;
  amount: string;
  asset?: StellarAsset;
  fee: string;
  memo?: string;
}

{
requestId: string;
 data: {
   unsignedMessage: string;
   hash: string;
 };
}
Параметры

  • publicKey - публичный ключ, обязательный параметр (строка);

  • network - тип сети, необязательный параметр, значение по умолчанию 'livenet' (Network);

  • to- адрес получателя, обязательный параметр (строка);

  • amount - сумма лимита хранения данного ассета на текущем адресе во внутреннем целочисленном формате или 0 для удаления трастлайна, необязательный параметр (строка), по умолчанию используется определяемое блокчейном максимальное значение для переданного ассета;

  • asset - криптовалюта на основе блокчейна Stellar, определяемая адресом эмитента данного актива и кодом актива, для которой добавляется трастлайн, обязательный параметр (StellarAsset);

  • fee - комиссия транзакции (строка);

  • memo - дополнительные данные транзакции (строка).

Получение хэша транзакции добавления трастлайна

Структура запроса

POST api/transaction/get-hash/xlm/add-trustline

{
  publicKey: string;
  network?: Network;
  amount: string;
  asset?: StellarAsset;
  fee: string;
  memo?: string;
}

{
requestId: string;
 data: {
   unsignedMessage: string;
   hash: string;
 };
}
Параметры

  • publicKey - публичный ключ, обязательный параметр (строка);

  • network - тип сети, необязательный параметр, значение по умолчанию 'livenet' (Network);

  • amount - сумма лимита хранения данного ассета на текущем адресе во внутреннем целочисленном формате или 0 для удаления трастлайна, необязательный параметр (строка), по умолчанию используется определяемое блокчейном максимальное значение для переданного ассета;

  • asset - криптовалюта на основе блокчейна Stellar, определяемая адресом эмитента данного актива и кодом актива, для которой добавляется трастлайн, обязательный параметр (StellarAsset);

  • fee - комиссия транзакции (строка);

  • memo - дополнительные данные транзакции (строка).

Получение хэша транзакции принятия claimableBalance

Структура запроса

POST api/transaction/get-hash/xlm/add-trustline

{
  publicKey: string;
  network?: Network;
  claimableBalanceId: string;
  fee: string;
  memo?: string;
}

{
requestId: string;
 data: {
   unsignedMessage: string;
   hash: string;
 };
}
Параметры

  • publicKey - публичный ключ, обязательный параметр (строка);

  • network - тип сети, необязательный параметр, значение по умолчанию 'livenet' (Network);

  • claimableBalanceId - идентификатор claimableBalance, обязательный параметр (строка);

  • fee - комиссия транзакции (строка);

  • memo - дополнительные данные транзакции (строка).

Подпись транзакции

Структура запроса

POST api/transaction/attach-signature/xlm

{
  publicKey: string;
  network: Network;
  unsignedMessage: string;
  signature: {
    s: string;
    R: string;
  };
}

{
 requestId: string;
 data: {
   txdata: string;
 };
}
Параметры

  • publicKey - публичный ключ, обязательный параметр (строка);

  • network - тип сети, необязательный параметр, значение по умолчанию 'livenet' (Network);

  • unsignedMessage - данные транзакции, полученные на предыдущем этапе (строка);

  • signature - объект с данными подписи.

Отправка транзакции в сеть

Структура запроса

POST api/transaction/send/xlm

{
  txdata: string;
}

{
 requestId: string;
 data: {
   txid: string;
 };
}
Параметры
  • txdata - данные подписанной транзакции, (строка).

Stellar Utility Endpoints

Получение информации о зарезервированном балансе XLM по адресу (метод getXLMAccountReserve)

Структура запроса:

POST /api/utility/account-reserve

{
  address: string;
}

{
  requestId: string;
  reserved: {
    baseReserve: string,
    xlm: string,
    assets: {
    value: string,
    count: number,
    },
  total: string,
  }
}
Параметры
  • address - уникальная строка символов, которая используется для идентификации кошелька на сети Stellar и начинается с буквы "G" и состоит из 56 символов, включая буквы и цифры;
Параметры ответа

  • requestId- идентификатор запроса (строка - uuid);

  • baseReserve - базовый резерв, который сеть использует при расчете минимального баланса счета. Этот минимальный баланс не может быть отправлен или потрачен;

  • xlm - количество XLM, которое находится в резерве на данном аккаунте;

  • assets - объект, который предоставляет информацию о зарезервированных активах;

  • value - количество XLM, которое находится в резерве для доверительных линий на данном аккаунте;

  • count - количество доверительных линий активов, установленных на аккаунте;

  • total - параметр представляет общую сумму резервов на аккаунте, включая как минимальный баланс, так и резерв для доверительных линий.

Получение базового резерва XLM (baseReserve)(метод getXLMBaseReserve)

Структура запроса:

GET /api/utility/base-reserve

{
  requestId: string,
  baseReserve: string,
}
Параметры ответа

  • requestId- идентификатор запроса (строка - uuid);

  • baseReserve - базовый резерв, который сеть использует при расчете минимального баланса счета. Этот минимальный баланс не может быть отправлен или потрачен;

Проверка существования аккаунта (метод checkXLMAccount)

Структура запроса:

POST /api/utility/check-account

{
  address: string;
}

{
  requestId: string
  accountExists: boolean,
}
Параметры
  • address - уникальная строка символов, которая используется для идентификации кошелька на сети Stellar и начинается с буквы "G" и состоит из 56 символов, включая буквы и цифры;
Параметры ответа

  • requestId- идентификатор запроса (строка - uuid);

  • accountExists - булевое значение, показывает существует ли аккаунт.

Проверка наличия в аккаунте доверительных линий (метод checkXLMAccountHasTrustline)

Структура запроса:

POST /api/utility/check-account-trustline

{
  address: string;
  issuer: string;
  code: string
}

{
  requestId: string
  hasTrustline: boolean,
}
Параметры

  • address - уникальная строка символов, которая используется для идентификации кошелька на сети Stellar и начинается с буквы "G" и состоит из 56 символов, включая буквы и цифры;

  • issuer - представляет собой аккаунт в сети Stellar, который создает и выпускает новые активы (токены) на сети. Эмитент отвечает за создание и управление активами, включая их выдачу и уничтожение;

  • code - идентификационный код актива. Этот код обычно состоит из нескольких символов и помогает идентифицировать конкретный актив среди других активов, выпущенных разными эмитентами.

Параметры ответа

  • requestId- идентификатор запроса (строка - uuid);

  • hasTrustline - булевое значение, показывает существует ли трастлайн.