Order Data (explanation)

OrderData is a structure that contains all the necessary information to create a new order. It is used as an input for newBuyOrder and newSellOrder functions.

There are also other input parameters like reportingData or crossIdentifier that are considered during placing new orders. But there is no expected structure of reporting data (can be anything) the same as crossIdentifier (can be any unique number/value).

Structure of OrderData

Lp	Size [bits]	Bits range	Name
1	64	152 - 88	Quantity
2	64	87 - 24	Price
3	8	23 - 16	Order Type
5	8	15 - 8	Execution Condition
6	8	7 - 0	Lifetime

Quantity

Quantity is a 64 bit field. It is a number of tokens that are being traded. Value should be provided in a format that is compatible with the internal order book representation and token's decimals.

Example:

Let's take into account some asset that has fractional part ie. Bitcoin. As users we know that we can buy 1.12345678 BTC as it has 8 decimal places. Very often if we want to represent some asset on the blockchain we use 18 decimals. Having that in mind we can follow the simple formula, if token has 18 decimals (native scale), and its representation in real world is 8 (non-native scale) then we need to multiply the real world value by 10^10 (18-8=10). Finally the value that we should provide to the Quantity field is 11 234 567 800.

Price

Price is a 64 bit field. It is a price in stable coin. Value should be provided in a format that is compatible with the internal order book representation and token's decimals.

Example

Let's take into account EURO. As daily users we are used to see prices like 1.23 EUR but often times financial systems use 4 or 6 decimal places to save the price. Very often if we want to represent some asset on the blockchain we use 18 decimals. Having that in mind we can follow the simple formula, if token has 18 decimals (native scale), and its representation in real world is 6 (non-native scale) then we need to multiply the real world value by 10^12 (18-6=12).

Finally the value that we should provide to the Quantity field is 1 230 000 000 000.

Order Type

Order Type is an 8 bit field. It is a type of order that is being placed. The current production release supports only Limit Orders:

• 0 - Limit Orders

Execution Condition

Execution Condition is an 8 bit field. It is a condition that is being placed on the order. The current production release supports only Good for Day orders:

• 0 - Good For Day (default for Limit Orders)

Lifetime

Reserved for later use. Must be 0 for now.

Usage

Putting it all together

import { ethers } from "hardhat";
import BigNumber from "bignumber.js";

bigint lifetime = 3n; // 3 days
bigint executionCondition = 0n; // Good For Day
bigint orderType = 0n; // Limit Order
bigint quantity = 11234567800n; // 1.12345678 in internal scale for base token
bigint price = 1230000000000n; // 1.23 in internal scale for quote token

const types = ["uint64", "uint64", "uint8", "uint8", "uint8"];
const values = [
        quantity,
        price,
        orderType,
        executionCondition,
        lifetime,
];
const encoder = new ethers.AbiCoder();
const orderData = encoder.encode(types, values);

Reporting Data & Cross Identifier

Together with orderData it is required to take care of reporting data and cross identifier parameters for newBuyOrder and newSellOrder. These two parameters are substancial for order book functionality.

1. reportingData as you can imagine it is for reporting purposes. Its details can change in the future but for now there is no predefined structure. The expected type is stream of bytes, it is repeated within events where necessary. Default accepted value is empty string of bytes.

2. crossIdentifier it is a parameter that should be generally used by participants who trade on behalf of other users, i.e., exchanges, to avoid self-trading issues. If you trade on your own, empty string of bytes is acceptable.