ree-types 0.3.0

Data type definitions of REE.
Documentation

REE Types

This repository contains the essential data type definitions for REE (Runes Exchange Environment).

Exchange Interfaces

In REE, every exchange must implement the following six functions:

Function Name Parameters Return Type Description
get_pool_list GetPoolListArgs Vec<PoolInfo> See Get Pool List.
get_pool_info GetPoolInfoArgs Option<PoolInfo> See Get Pool Info.
get_minimal_tx_value GetMinimalTxValueArgs u64 See Get Minimal Tx Value.
execute_tx ExecuteTxArgs Result<String, String> See Execute Tx.
finalize_tx FinalizeTxArgs Result<(), String> See Finalize Tx.
rollback_tx RollbackTxArgs Result<(), String> See Rollback Tx.

Implementation Notes:

  • The REE Orchestrator calls these functions to interact with exchanges WITHOUT attaching any cycles.
  • Every exchange MUST implement these functions exactly as defined in this repository. Failure to do so will prevent the exchange from being registered in the REE Orchestrator, or may cause a registered exchange to be halted.
  • These functions may be implemented as async or synchronous.
  • The get_pool_list, get_pool_info and get_minimal_tx_value may be declared with #[ic_cdk::query] or #[ic_cdk::update] in the exchange canister. The other functions MUST be declared with #[ic_cdk::update].
  • All parameters and return types are defined in the ree_types::exchange_interfaces module.

Get Pool List

Returns the list of pools maintained by the exchange.

Parameters:

pub struct GetPoolListArgs {
    pub from: Option<Pubkey>,
    pub limit: u32,
}

Return Type: Vec<PoolInfo>, where PoolInfo is defined as:

pub struct PoolInfo {
    pub key: Pubkey,
    pub key_derivation_path: Vec<Vec<u8>>,
    pub name: String,
    pub address: String,
    pub nonce: u64,
    pub coin_reserved: Vec<CoinBalance>,
    pub btc_reserved: u64,
    pub utxos: Vec<Utxo>,
    pub attributes: String,
}

Get Pool Info

Returns detailed information about a specified pool.

Parameters:

pub struct GetPoolInfoArgs {
    pub pool_address: String,
}

Return Type: Option<PoolInfo>

Get Minimal Tx Value

Returns the minimum transaction value that can be accepted by the exchange, considering the zero-confirmation transaction queue length for a specific pool.

Parameters:

pub struct GetMinimalTxValueArgs {
    pub pool_address: String,
    pub zero_confirmed_tx_queue_length: u32,
}

Return Type: u64, the minimal transaction value in sats.

Execute Tx

Executes a transaction in the exchange.

Parameters:

pub struct ExecuteTxArgs {
    pub psbt_hex: String,
    pub txid: Txid,
    pub intention_set: IntentionSet,
    pub intention_index: u32,
    pub zero_confirmed_tx_queue_length: u32,
}

Return Type:

  • Ok(String): The signed PSBT data in hex format. The exchange can add corresponding signature(s) to the PSBT data or not, but a valid PSBT data with the same txid with the given psbt_hex MUST be returned.
  • Err(String): An error message if execution fails.

Finalize Tx

Finalizes a transaction in the exchange. All transactions preceding the given transaction should also be considered finalized.

Parameters:

pub struct FinalizeTxArgs {
    pub pool_key: Pubkey,
    pub txid: Txid,
}

Return Type:

  • Ok(()): On successful finalization.
  • Err(String): If an error occurs.

Rollback Tx

Rolls back a transaction in the exchange. All transactions following the given transaction should also be considered canceled.

Parameters:

pub struct RollbackTxArgs {
    pub pool_key: Pubkey,
    pub txid: Txid,
}

Return Type:

  • Ok(()): On successful rollback.
  • Err(String): If an error occurs.