Structures

Cairo structures map for the exchange entities

Fees

Gas fee

struct GasFee {
    gas_per_action: u32,
    fee_token: ContractAddress,
    max_gas_price: u256,
    conversion_rate: (u256, u256), # in case of chain base currency it will be (1,1)
}

Fixed fee

struct FixedFee {
    recipient: ContractAddress, # the one who will recieve specified amount of fees of trade
    maker_pbips: u32, #0.01pct = 1bps = 100pbips
    taker_pbips: u32,
    apply_to_receipt_amount: bool
}

Order fee

struct OrderFee {
    trade_fee: FixedFee,
    router_fee: FixedFee,
    gas_fee: GasFee,
}

---

Order

Onchain fills info

struct OrderTradeInfo {
    filled_base_amount: u256, #base token amount filled
    filled_quote_amount: u256, #quote token amount filled
    last_traded_px: u256, #last traded price
    num_trades_happened: u8,
    as_taker_completed: bool, takers order marks as completed so not fulfillable 
}

STP modes

enum TakerSelfTradePreventionMode {
    NONE, // allow self trading
    EXPIRE_TAKER, // won't allow orders to match if they have the same order signer, 
    EXPIRE_MAKER, // won't allow orders to match if they have the same order signer
    EXPIRE_BOTH, //  won't allow orders to match
} // semantic take place only depending on takers' order mode

Quantity

struct Quantity {
    base_qty: u256, // qunatity in base asset raw amount
    quote_qty: u256, // quantity in quote asset raw amount
    base_asset: u256 // raw amount of base asset representing 1, eg 1 eth is 10**18
}

Constraints

struct Constraints {
    number_of_swaps_allowed: u16, // if order is taker, one can limit maximum number of trades can happens with this taker order (necesasry becase taker order incur gas fees)
    duration_valid: u32, // epoch tine in seconds, time when order becomes invalid
    created_at: u32, // epoch time in seconds, time when order was created by user
    stp: TakerSelfTradePreventionMode,
    nonce: u32, // maker nonce, for order be valid this nonce must be >= in Nonce component
    min_receive_amount: u256, // minimal amount that user willing to receive from the full matching of order, default value 0, for now defined for router takers, serves as slippage that filtered on exchange, no restrictions onchain
    router_signer: ContractAddress, // if taker order is router aka trader outside of our ecosystem then this is router that router this trader to us
}

OrderFlags

struct OrderFlags {
    full_fill_only: bool, 
    best_level_only: bool,
    post_only: bool,
    is_sell_side: bool,
    is_market_order: bool,
    to_ecosystem_book: bool,
    external_funds: bool
}

Order

struct Order {
    maker: ContractAddress, // trading account that created order
    price: u256, // price in quote asset raw amount, for taker order serves as protection price, for passive order executoin price
    qty: Quantity,
    constraints:Constraints,
    salt: felt252, // random salt for security
    ticker: (ContractAddress, ContractAddress), // (base asset address, quote asset address) eg ETH/USDC
    fee: OrderFee, // order fees that user must fulfill once trade happens
    flags: OrderFlags, // various order flags of order
    source: felt252, // from where order originate, e.g. layerakira
}   

Signed entity of order

struct SignedOrder {
    order: Order,
    sign: Span<felt252>, // makers' signer signature of type order,
    router_sign: (felt252,felt252) // router_signer signature of poseidon hash of order in case of router taker order, else (0, 0)
}

---

Nonce

Increase nonce

struct IncreaseNonce {
    maker: ContractAddress,
    new_nonce: u32,
    gas_fee: GasFee,
    salt: felt252,
}

Signed entity of increase nonce

struct SignedIncreaseNonce {
    increase_nonce: IncreaseNonce,
    sign: (felt252, felt252),
}

---

Withdraw

Withdraw

struct Withdraw {
    maker: ContractAddress, // trading account that want to withdraw
    token: ContractAddress, // address of erc20 token of interest, 
    amount: u256, // amount of token, at the end user will receive amount of token diff from gas fee or amount - gas_fee, so user can always withdraw all his balances 
    salt: felt252, // random salt
    gas_fee: GasFee, // for some paths, this activity to be executed requires gasfee
    receiver: ContractAddress // receiver of withdrawal tokens
}

Signed entity of withdraw

struct SignedWithdraw {
    withdraw: Withdraw,
    sign: (felt252, felt252)
}

Utils

struct SlowModeDelay {
    block: u64, #block number
    ts: u64, # timstamp in epoch seconds
}