booker gateway websockets json rpc API Spec (RU)

Методы Booker/gateway websockets-json-rpc API

BookerServer->>GatewayClient API

create_order

Отправляется клиентом шлюза, после успешной обработки (in-)транзакции. Букер ответит объектом созданного им ордера

Hint: Любая транзакция, зафиксированная в Букере этим методом (т.е. обнаруженная шлюзом) будет in-транзакцией в базе данных Букера

Пример: Целевой шлюз увидел в своем блокчейне входящий перевод 55.5 FINTEH.USDT от пользователя (Вывод средств), и просит Букер создать ордер Request -->

{"jsonrpc": "2.0", 
"method": "create_order", 
"params":     
{
 "in_tx": {
    "coin": "FINTEH.USDT",
    "to_address": "gateway_target_address",
    "from_address": "user_target_account", 
    "amount": "66.6",
    "created_at": "2020-09-19 03:10:05.059564",
    "error": "NO_ERROR",
    "tx_id": "Some:BitsharesOperationIdentifier",
    "confirmations": 1,
    "max_confirmations": 5
    },
 "out_tx": {
    "to_address": "gateway_target_address"
    },
"id": "fcd2730a-b539-4b19-93ee-7502f2956b0c"}

<-- Response

{"jsonrpc": "2.0", 
"error": null, 
"result": 
  {
    "order_id": "33b91e2e-5c86-48ce-8530-470b95111659", 
    "order_type": "WITHDRAWAL",
        "in_tx": {
            "coin": "FINTEH.USDT",
            "to_address": "gateway_target_address",
            "from_address": "user_target_account", 
            "amount": "66.6",
            "created_at": "2020-09-19 03:10:05.059564",
            "error": "NO_ERROR",
            "tx_id": "Some:BitsharesOperationIdentifier",
            "confirmations": 1,
            "max_confirmations": 5
           },
    "out_tx": {
        "to_address": "gateway_target_address"
        "coin": "USDT",
        "amount": "66.6"
      },
"id": "fcd2730a-b539-4b19-93ee-7502f2956b0c"}

update_order

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

Пример. Целевой шлюз увидел в блокчейне 2 новых подтверждения in-транзакции(было 1, стало 3), которую мы рассматривали в предыдущем примере, и уведомляет Букер об изменившихся параметрах

Request -->

{"jsonrpc": "2.0", 
"method": "update_order", 
"params":     
{
  "order_id": "33b91e2e-5c86-48ce-8530-470b95111659",
  "in_tx":
      {"confirmations": 3},
},
"id": "fcd2730a-b539-4b19-93ee-7502f2956b0c"}

Букер в ответ сигнализирует об успешности обновлений булевым значением:

<-- Response

{"jsonrpc": "2.0", 
"error": null, 
"result": 
  {"is_updated": true},
"id": "fcd2730a-b539-4b19-93ee-7502f2956b0c"}

GatewayClient->>BookerServer API

validate_address

Booker запрашивает валидацию пользовательского адреса для вывода средств. Необходим для избежания выплат на несуществующие/невалидные/мошеннические адреса.

Request -->

{"jsonrpc": "2.0", 
"method": "validate_address", 
"params": {"user": "some_username", 
          "is_valid": null}, 
"id": "fcd2730a-b539-4b19-93ee-7502f2956b0c"}

<-- Response

{"jsonrpc": "2.0", 
"error": null, 
"result": {"user": "some_username", 
           "is_valid": true},
"id": "fcd2730a-b539-4b19-93ee-7502f2956b0c"}

deposit_address

Booker запрашивает адрес, на который пользователь сможет совершить депозит. Логика выдачи адреса реализуется на стороне клиента

Request -->

{"jsonrpc": "2.0", 
"method": "get_deposit_address", 
"params": {"user": "some_username", 
           "deposit_address": "gateway_deposit_address"},
"id": "fcd2730a-b539-4b19-93ee-7502f2956b0c"}

<-- Response

{"jsonrpc": "2.0", 
"error": null, 
"result": {"user": "USER_NAME", 
           "deposit_address": "GATEWAY_DEPOSIT_ADDRESS"},
"id": "fcd2730a-b539-4b19-93ee-7502f2956b0c"}

init_new_tx

Booker, обработав ордер с успешной in-транзакцией, просит шлюз транслировать новую out-транзацию.

Пример, при котором пользователь делает депозит на биржу 66.6 USDT:

Request -->

{"jsonrpc": "2.0", 
"method": "init_new_tx", 
"params": 
   {"order_id": "33b91e2e-5c86-48ce-8530-470b95111659", 
    "order_type": "DEPOSIT",
    "in_tx": {
        "coin": "USDT",
        "to_address": "gateway_native_deposit_address",
        "from_address": "user_native_wallet_address",
        "amount": "66.6",
        "created_at": "2020-09-19 03:10:05.059564",
        "error": "NO_ERROR",
        "tx_id": "some:tx_hash_from_blockchain",
        "confirmations": 0,
        "max_confirmations": 5
       },
    "out_tx": {
        "coin": "FINTEH.USDT",
        "to_address": "user_target_deposit_address",
        "from_address": "gateway_target_address", 
        "amount": "66.6",
        "created_at": "2020-09-19 03:10:05.059564",
        "error": "NO_ERROR",
        "tx_id": null,
        "confirmations": 0,
        "max_confirmations": 5
    }
  },
"id": "fcd2730a-b539-4b19-93ee-7502f2956b0c"}

Поле ["params"]["out_tx"]["tx_id"] пустое, т.к. это айди будет создано шлюзам, и вернется в ответе, в числе прочих параметров транзакции

<-- Response

{"jsonrpc": "2.0", 
"error": null, 
"result":     
{
    "coin": "USDT",
    "to_address": "gateway_address",
    "from_address": "user_address",
    "amount": 66.6,
    "created_at": "2020-09-19 03:10:05.059564",
    "error": "NO_ERROR",
    "tx_id": "some_hash_of_new_out_transaction",
    "confirmations": 0,
    "max_confirmations": 5
},
"id": "fcd2730a-b539-4b19-93ee-7502f2956b0c"}

create_empty_order

Используется для шлюзов, которым необходимо создавать пустые ордера (без транзакций). Структура params запроса идентичны init_new_tx, с той разницей, что в create_empty_order у транзакций есть только поля coin и to_address Request -->

{"jsonrpc": "2.0", 
"method": "create_empty_order", 
"params": 
   {"order_id": "33b91e2e-5c86-48ce-8530-470b95111659", 
    "order_type": "DEPOSIT",
    "in_tx": {
        "coin": "USDT",
        "to_address": "gateway_native_deposit_address",
       },
    "out_tx": {
        "coin": "FINTEH.USDT",
        "to_address": "user_target_deposit_address",
    }
  },
"id": "fcd2730a-b539-4b19-93ee-7502f2956b0c"}

<-- Response

{"jsonrpc": "2.0", 
"error": null, 
"result":     
{
    "created": true
},
"id": "fcd2730a-b539-4b19-93ee-7502f2956b0c"}

Терминология

Биржа - децентрализованная криптовалютная биржа как совокупность всех микросервисов (Букер, несколько шлюзов и другие сервисы) для обмена активами между пользователями с использованием ресурсов владельца биржи

Шлюз - Микросервис, обслуживающий один блокчейн, обрабатывающий входящие и исходящие транзакции

Букер - Микросервис, координирующий шлюзы между собой

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

Целевой блокчейн - блокчейн, в котором выпускаются активы биржи и происходит прямая децентрализованная торговля (матчинг ордеров)

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

Транзакция - Транзакция в блокчейне, прямой перевод средств с между двумя кошельками блокчейна

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

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

In-транзакция - Транзакция, которая:

Всегда инициализируется ДО создания ордера
Инициатором является пользователь
В базе данных Order.in_tx

Out-транзакция - Транзакция, которая:

Всегда инициализируется ПОСЛЕ создания ордера (т.е. после создания In-транзакции, её валидации, создания ордера в букере и подтверждения In-транзакции в блокчейне)
Инициатором является Биржа/Букер
Является Order.out_tx

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

booker gateway websockets json rpc API Spec (RU)

Методы Booker/gateway websockets-json-rpc API

BookerServer->>GatewayClient API

GatewayClient->>BookerServer API

Терминология

Clone this wiki locally