# Ордер

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

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

О способах создания ордера читайте в разделе Как обменивать токены.

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

# JSON-представление ордера

JSON-представление ордера в REST API ноды Waves:

{
   "version": 3,
   "id": "72iHDmfr7VWH1cbuP4FjscUU1kcW8CJ629ctVKMyDLBm",
   "sender": "3PB4PKHZ69qtxtQi4zTjcpisyUbEYgs6CD1",
   "senderPublicKey": "3g4rdPwkZmjSe18MGuZtVLtiN1uQ1fP4eqnHYjApoSU5",
   "matcherPublicKey": "9cpfKN9suPNvfeUNphzxXMjcnn974eme8ZhWUjaktzU5",
   "assetPair": {
      "amountAsset": "6nSpVyNH7yM69eg446wrQR94ipbbcmZMU1ENPwanC97g",
      "priceAsset": null
   },
   "orderType": "buy",
   "amount": 15637504,
   "price": 12114051100,
   "timestamp": 1637671821599,
   "expiration": 1637844621599,
   "matcherFee": 300000,
   "signature": "2YjtusNiBzevq23v7wV8tkt5Ri1vtmDAoW5qhRThcpUqqZcyP6joqe7StMXyLaXjM6rYCe1tPMB973Sq9TPRfcsU",
   "proofs": [
      "2YjtusNiBzevq23v7wV8tkt5Ri1vtmDAoW5qhRThcpUqqZcyP6joqe7StMXyLaXjM6rYCe1tPMB973Sq9TPRfcsU"
   ],
   "matcherFeeAssetId": null
}

Поле	Описание
version	Версия ордера
id	Идентификатор ордера: байты в кодировке base58. Идентификатор ордера вычисляется аналогично идентификатору транзакции, см. раздел Cryptographic practical details
sender	Адрес отправителя ордера: байты в кодировке base58
senderPublicKey	Открытый ключ отправителя ордера: байты в кодировке base58
matcher_public_key	Открытый ключ матчера, на который отправлен ордер: байты в кодировке base58
assetPair.amountAsset	ID amount-ассета (базовой валюты): байты в кодировке base58. `null` означает WAVES
assetPair.priceAsset	ID price-ассета (валюты котировки): байты в кодировке base58. `null` означает WAVES
orderType	Тип ордера: • buy — отправитель получает amount-ассет, • sell — отправитель тратит amount-ассет
amount	Количество amount-ассета. Целое число, выраженное в атомарных единицах ассета
price	Стоимость 1 amount-ассета, выраженная в price-ассете, умноженная на коэффициент: • 10⁸ для ордера версии 4 с атрибутом `"priceMode": "fixedDecimals"` или без атрибута `"priceMode"`; • 10^{8 + priceAssetDecimals – amountAssetDecimals} для ордера версии 4 с атрибутом `"priceMode": "assetDecimals"`, а также для ордера версии 3, 2 или 1. Здесь `amountAssetDecimals`, `priceAssetDecimals` — количество знаков после запятой у amount- и price-ассета соответственно (параметр токена). Целое число. См. пояснение ниже
priceMode	Способ задания значения в поле `price`. Поле доступно с момента активации фичи № 17 “Ride V6, MetaMask support”
timestamp	Временная метка ордера: Unix-время в миллисекундах
expiration	Окончание срока действия ордера: Unix-время в миллисекундах
matcherFee	Комиссия матчера. Целое число, выраженное в атомарных единицах токена комиссии
signature	• Подпись отправителя в ордере версии 1. • В последующих версиях ордера в поле возвращается первый элемент массива `proofs`
proofs	Подтверждения ордера, используемые для его верификации, аналогично подтверждениям транзакции. До 8 подтверждений, каждое подтверждение до 64 байт, байты в кодировке base58. Отсутствуют у ордера, подписанного пользователем MetaMask
eip712Signature	Только для ордера, подписанного пользователем MetaMask: подпись ECDSA в кодировке HEX. Поддержка MetaMask доступна c момента активации фичи № 17 “Ride V6, MetaMask support”. Подробнее в разделе Подписание транзакций и ордеров в MetaMask
matcherFeeAssetId	ID токена, в котором указана комиссия матчера: байты в кодировке base58. `null` означает, что комиссия указана в WAVES
attachment	Произвольные данные, до 1024 байт, в кодировке base58. Поле доступно с момента активации фичи № 22 “Light Node”

Пояснение:

Приведенный выше ордер — это заявка на покупку 15,637504 NSBT по цене не выше 1,21140511 WAVES за 1 NSBT.

Amount-ассетом является NSBT, amountAssetDecimals равно 6.

Price-ассетом является WAVES, priceAssetDecimals равно 8.

Значение amount в ордере равно 15,637504 × 10^{amountAssetDecimals} = 15637504.

Значение price в ордере равно 1,21140511 × 10^{8 + priceAssetDecimals – amountAssetDecimals} = 12114051100 (поскольку это ордер версии 3).

Нормализация

Все числа на блокчейне являются целыми — это позволяет избежать ошибок округления. Ордер (исполненный полностью или частично) появляется на блокчейне в составе транзакции обмена, поэтому значения amount и price в ордере, подписанном пользователем, должны быть указаны в виде целых чисел.

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

Поле amount содержит количество ассета, поэтому для нормализации используется коэффициент 10^{amountAssetDecimals}.

Однако поле price содержит не количество, а отношение. Размерность цены зависит от обоих ассетов в паре — подобно тому как цена яблок измеряется, например, в долларах за килограмм, но не в долларах. В приведенном выше примере единица измерения цены — WAVES/NSBT. Исходя из этого, для нормализации цены в ордерах версий 1, 2, 3 выбран коэффициент нормализации

10⁸ × (10^{priceAssetDecimals} / 10^{amountAssetDecimals}) = 10^{8 + priceAssetDecimals – amountAssetDecimals}.

Множитель 10⁸ нужен, потому что priceAssetDecimals может быть меньше, чем amountAssetDecimals.

Отметим, что максимальное значение нормализованной цены равно 9 223 372 036 854 775 807: это максимальное допустимое число на блокчейне. В случае если priceAssetDecimals = 8, а amountAssetDecimals = 0, коэффициент нормализации равен 10¹⁶. Следовательно, реальная цена не может превышать 922,3372036854775807. Таким образом, например, в случае обмена NFT на WAVES максимальная стоимость NFT — менее 1000 WAVES. Чтобы устранить это ограничение, в ордере версии 4 добавлена возможность выбирать коэффициент нормализации:

10⁸ в режиме "priceMode": "fixedDecimals",
10^{8 + priceAssetDecimals – amountAssetDecimals} в режиме "priceMode": "assetDecimals".

Расчет количества price-ассета

В ордере указывается только количество amount-ассета (который переходит от продавца к покупателю) и цена. На основе этих значений рассчитывается количество price-ассета (который переходит от покупателя к продавцу в обмен на amount-ассет). Количество price-ассета в атомарных единицах вычисляется по формуле:

в ордере версии 4 с атрибутом "priceMode": "fixedDecimals" или без атрибута priceMode:

amount × price × 10^{(priceAssetDecimals - amountAssetDecimals - 8)}
в ордере версии 4 с атрибутом "priceMode": "assetDecimals", в ордере версии 3, 2 или 1:

amount × price × 10^-8.

(amount и price — нормализованные значения, указанные в ордере.)

Если в результате вычисления получено значение с дробной частью, то она отбрасывается.

Например, в ордере версии 3, приведенном выше, количество price-ассета рассчитывается как:

15637504 × 12114051100 × 10^-8 = 1894335225,324544,

после отбрасывания дробной части — 1894335225 в атомарных единицах, что соответствует 18,94335225 WAVES.

# Бинарный формат ордера

См. раздел Бинарный формат ордера.

# Структура Ride

Для операций с ордером в смарт-контрактах используется структура Order.