Market

Instructions from the ferum::market module

Public Functions are denoted by:

public entry fun: These are functions individuals call from Move Modules or Clients (such as Aptos CLI).
public fun: These are functions you can call from Move Modules and are commonly used by protocols when building integrations. These functions also return additional variables that the protocols can utilize.

Entry Functions

init_market_entry

Initializes a market for the given instrument and quote coins.

Types:

I: CoinType of the instrument coin of this market. For APT/USDC, APT is I.
Q: CoinType for the quote coin of this market. For APT/USDC, USDC is Q.

Parameters:

owner: &signer Wallet signing the transaction
instrumentDecimals: u8 Number of decimal places the instrument coin should support for this market. Must satisfy instrumentDecimals + quoteDecimals <= min(coin::decimals(), coin::decimals())
quoteDecimals: u8 Number of decimal places the quote coin should support for this market. Must satisfy instrumentDecimals + quoteDecimals <= min(coin::decimals(), coin::decimals())

open_market_account_entry

Open a market account.

Users must first create a market account (using this function) and deposit into it (using the next function), before trading on ferum.

Types:

I: CoinType for the instrument coin of this market. For APT/USDC, APT is I.
Q: CoinType of the quote coin of this market. For APT/USDC, USDC is Q.

Parameters:

owner: &signer Owner of the market account.

deposit_to_market_account_entry

Deposit funds to trade with into the market account from the address of the owner.

Users must first create a market account (using the above function) and deposit into it (using this function), before trading on ferum.

Types:

I: CoinType for the instrument coin of this market. For APT/USDC, APT is I.
Q: CoinType of the quote coin of this market. For APT/USDC, USDC is Q.

Parameters:

owner: &signer Owner of the market account. Assets will be withdrawn from this address.
coinIAmt: u64: The qty of I tokens to be deposited. Fixedpoint Value.
coinQAmt: u64: The qty of Q tokens to be deposited. Fixedpoint Value.

withdraw_from_market_account_entry

Withdraws coins from the market account into the address of the owner.

Types:

I: CoinType for the instrument coin of this market. For APT/USDC, APT is I.
Q: CoinType of the quote coin of this market. For APT/USDC, USDC is Q.

Parameters:

owner: &signer Owner of the market account. Assets will be deposited into this address.
coinIAmt: u64: The qty of I tokens to be withdrawn. Fixedpoint Value.
coinQAmt: u64: The qty of Q tokens to be withdrawn. Fixedpoint Value.

rebalance_cache_entry

Rebalances the orders in Vector Cache and B+ Tree based on existing prices, usually called by the a crank process.

Parameters:

owner: &signer Signer for the transaction.
limit: u8: The maximum number of price levels that should be rebalanced.

crank_entry

Types:

I: CoinType for the instrument coin of this market. For APT/USDC, APT is I.
Q: CoinType of the quote coin of this market. For APT/USDC, USDC is Q.

Parameters:

owner: &signer Signer for the transaction.
limit: u8: The number of Nodes to crank. Each Node contains a set number of events (currently 5). So this means that at most, 5*limit events will be processed.

Node side is defined as EVENT_QUEUE_NODE_SIZE in the market module.

add_order_entry

Adds an order to the market for types I/Q. As this is an entry function, nothing is returned. If you need a function that returns the id of the order, use add_order.

Types:

I: CoinType for the instrument coin of this market. For APT/USDC, APT is I.
Q: CoinType of the quote coin of this market. For APT/USDC, USDC is Q.

Parameters:

owner: &signer Signer for the owner of the order.
side: u8 Side the order is taking. Valid choices are: buy = 1, sell = 2. All other values will result in an error.
behaviour: u8 Behaviour of the order. Valid choices are: gtc = 1, post = 2, ioc = 3, fok = 4. All other values will result in an error. See Order Behaviour for more details.
price: u64 For a buy, the maximum price the order will execute at. For a sell, the minimum price the order will execute at. For a market order, set the price to 0. Fixedpoint Value.
qty: u64 Quantity for the order. Fixedpoint Value.
clientOrderID: u32 Optional metadata added to order.
marketBuyMaxCollateral: u64 For market orders, specify the amount of funds that can be utilized. If the price is 0 (market order) and marketBuyMaxCollateral is not specified, the transaction will error. Fixedpoint Value.

cancel_order_entry

Cancels an order with the given id.

Types:

I: CoinType of the instrument coin of this market. For APT/USDC, APT is I.
Q: CoinType for the quote coin of this market. For APT/USDC, USDC is Q.

Parameters:

owner: &signer Signer for user that placed this order.
counter: u32 The counter portion of the OrderID.

cancel_all_orders_for_owner_entry

Cancels all orders placed by the signer.

Types:

I: CoinType of the instrument coin of this market. For APT/USDC, APT is I.
Q: CoinType for the quote coin of this market. For APT/USDC, USDC is Q.

Parameters:

owner: &signer Signer for the wallet that the orders were placed through.

Public Functions

Usually used by integrated protocols to place trades on behalf of users or manage to margin, returns additional variables that the protocol can utilize.

get_order_id

Returns the OrderID.

Parameters:

accountKey: MarketAccountKey Market account for the order. Can be generated from get_market_account_key.
counter: u32 Counter portion of the order id

Returns:

OrderID OrderID of a specific order based on Market Account Key and Counter.

open_market_account

Open a market account.

Users must first create a market account (using this function) and deposit into it (using the next function), before trading on ferum.

Types:

I: CoinType for the instrument coin of this market. For APT/USDC, APT is I.
Q: CoinType of the quote coin of this market. For APT/USDC, USDC is Q.

Parameters:

owner: &signer User to open market account for
accountIdentifier: vector<AccountIdentifier> Vector containing single AccountIdentifier generated from gen_account_identifier. If empty, will return the key for the ferum market account for this user.

Returns

MarketAccountKey: Returns the Market Account Key here to be used in other Functions.

deposit_to_market_account

osit funds to trade with into the market account from the address of the owner.

Users must first create a market account (using the above function) and deposit into it (using this function), before trading on ferum.

Types:

I: CoinType for the instrument coin of this market. For APT/USDC, APT is I.
Q: CoinType of the quote coin of this market. For APT/USDC, USDC is Q.

Parameters:

owner: &signer Owner of the market account. Assets will be withdrawn from this address.
accountKey: MarketAccountKey MarketAccountKey of the user, generated from get_market_account_key
coinIAmt: u64: The qty of I tokens to be deposited. Fixedpoint Value.
coinQAmt: u64: The qty of Q tokens to be deposited. Fixedpoint Value.

withdraw_from_market_account

Withdraws coins from a market account created earlier, useful after trades are settled.

Types:

I: CoinType for the instrument coin of this market. For APT/USDC, APT is I.
Q: CoinType of the quote coin of this market. For APT/USDC, USDC is Q.

Parameters:

owner: &signer Owner of the market account. Assets will be deposited to this address.
accountKey: MarketAccountKey MarketAccountKey of the user, generated from get_market_account_key
coinIAmt: u64,: The qty of I tokens to be withdrawn. Fixedpoint Value.
coinQAmt: u64,: The qty of Q tokens to be withdrawn. Fixedpoint Value.

get_market_account_key

Get the MarketAccountKey of an account.

Types:

I: CoinType for the instrument coin of this market. For APT/USDC, APT is I.
Q: CoinType of the quote coin of this market. For APT/USDC, USDC is Q.

Parameters:

owner: &signer User to get the market account of
accountIdentifier: vector<AccountIdentifier> Vector containing single AccountIdentifier generated from gen_account_identifier. If empty, will return the key for the ferum market account for this user.

Returns:

MarketAccountKey: MarketAccountKey

add_order

Adds an order to the market for types I/Q, returning the OrderID of the order that is created.

Types:

I: CoinType for the instrument coin of this market. For APT/USDC, APT is I.
Q: CoinType of the quote coin of this market. For APT/USDC, USDC is Q.

Parameters:

owner: &signer Signer for the owner of the order.
accountKey: MarketAccountKey MarketAccountKey of the account placing this order. the owner must be able to take actions for this market account. Trades will be settled into this account.
side: u8 Side the order is taking. Valid choices are: buy = 1, sell = 2. All other values will result in an error.
behaviour: u8 Valid choices are: GTC = 1, post = 2, ioc = 3, fok = 4. All other values will result in an error. See Order Types for more details.
price: u64 FixedPoint Value. Set 0 for a market order, and specify a price for a limit order. For a buy, the maximum price the order will execute at. For a sell, the minimum price the order will execute at.
qty: u64 FixedPoint Value. Quantity for the order.
clientOrderID: u32 Optional metadata added to order.
marketBuyMaxCollateral: u64 For market orders, specify the amount of funds that can be utilized. If the price is 0 (market order) and marketBuyMaxCollateral is not specified, the transaction will error. Fixedpoint Value.

Returns:

OrderID: OrderID of the above order.

cancel_order

Cancel an order, takes in an OrderID as input.

Types:

I: CoinType of the instrument coin of this market. For APT/USDC, APT is I.
Q: CoinType for the quote coin of this market. For APT/USDC, USDC is Q.

Parameters:

owner: &signer Signer for the transaction.
orderID: OrderID OrderID that should be canceled. The owner must be able to take actions for the market account this order was placed from.

get_market_addr

Returns the address this specified market is stored at.

Types:

I: CoinType of the instrument coin of this market. For APT/USDC, APT is I.
Q: CoinType for the quote coin of this market. For APT/USDC, USDC is Q.

Returns:

address Address the specified market is stored at.

View Functions

View functions are currently not supported on the Aptos testnet

Helpful functions to see the state of a market.

view_market_account

Returns the specified market account

Types:

I: CoinType of the instrument coin of this market. For APT/USDC, APT is I.
Q: CoinType for the quote coin of this market. For APT/USDC, USDC is Q.

Parameters:

protocol: address Address of the protocol portion of the MarketAccountKey
user: address Address of the user portion of the MarketAccountKey

Returns:

MarketAccountView JSON representation of a market account

struct MarketAccountView {
    activeOrders: vector<OrderID>,
    instrumentBalance: u64, // Fixedpoint
    quoteBalance: u64, // Fixedpoint
}

Sample Call

curl --request POST \
  --url https://fullnode.testnet.aptoslabs.com/v1/view \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data '{
  "function": "0x8909e0bb1dc6426039fec370bad122cf223c3ef26f05b4264e7ce7921e498b8b::market::view_market_account",
  "type_arguments": [
    "0x8909e0bb1dc6426039fec370bad122cf223c3ef26f05b4264e7ce7921e498b8b::test_coins::APTF",
    "0x8909e0bb1dc6426039fec370bad122cf223c3ef26f05b4264e7ce7921e498b8b::test_coins::USDF"
  ],
  "arguments": [
    "0x8909e0bb1dc6426039fec370bad122cf223c3ef26f05b4264e7ce7921e498b8b",
    "0x8909e0bb1dc6426039fec370bad122cf223c3ef26f05b4264e7ce7921e498b8b"
  ]
}' | jq .

view_order

Returns the specified order

Types:

I: CoinType of the instrument coin of this market. For APT/USDC, APT is I.
Q: CoinType for the quote coin of this market. For APT/USDC, USDC is Q.

Parameters:

protocol: address Address of the protocol portion of the MarketAccountKey
user: address Address of the user portion of the MarketAccountKey
counter: string Counter portion of the OrderID

Returns:

MarketAccountView JSON representation of a market account

struct OrderView {
    buyCollateral: u64, // Fixedpoint.
    sellCollateral: u64, // Fixedpoint.
    side: u8,
    behaviour: u8,
    price: u64, // Fixedpoint.
    originalQty: u64, // Fixedpoint.
    unfilledQty: u64, // Fixedpoint.
    takerCrankPendingQty: u64, // Fixedpoint.
    clientOrderID: u32,
    marketBuyRemainingCollateral: u64, // Fixedpoint.
}

Sample Call

curl --request POST \
  --url https://fullnode.testnet.aptoslabs.com/v1/view \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data '{
  "function": "0x25e00c9375cf2ad1370c16c1f2cbbfaa523ae6bbb0b05449599c50fa6ee6aff4::market::view_order",
  "type_arguments": [
    "0x25e00c9375cf2ad1370c16c1f2cbbfaa523ae6bbb0b05449599c50fa6ee6aff4::test_coins::APTF",
    "0x25e00c9375cf2ad1370c16c1f2cbbfaa523ae6bbb0b05449599c50fa6ee6aff4::test_coins::USDF"
  ],
  "arguments": [
    "0x25e00c9375cf2ad1370c16c1f2cbbfaa523ae6bbb0b05449599c50fa6ee6aff4",
    "0x25e00c9375cf2ad1370c16c1f2cbbfaa523ae6bbb0b05449599c50fa6ee6aff4",
    "1"
  ]
}' | jq .

PreviousContract Instructions NextPlatform

Last updated 1 year ago