Crate ree_exchange_sdk 

The REE Exchange SDK provides a set of types and interfaces for building REE exchanges.

Example

use self::exchange::*;
use candid::CandidType;
use ic_cdk::{query, update};
use ree_exchange_sdk::{prelude::*, types::*};
use serde::{Deserialize, Serialize};

#[derive(Clone, Debug, Deserialize, Serialize, PartialEq, Eq, Default)]
pub struct DummyPoolState {
    pub txid: Txid,
    pub nonce: u64,
    pub coin_reserved: Vec<CoinBalance>,
    pub btc_reserved: u64,
    pub utxos: Vec<Utxo>,
    pub attributes: String,
}

impl StateView for DummyPoolState {
    fn inspect_state(&self) -> StateInfo {
        StateInfo {
            txid: self.txid,
            nonce: self.nonce,
            coin_reserved: self.coin_reserved.clone(),
            btc_reserved: self.btc_reserved,
            utxos: self.utxos.clone(),
            attributes: "{}".to_string(),
        }
    }
}

#[exchange]
pub mod exchange {
    use super::*;

    #[pools]
    pub struct DummyPools;

    impl Pools for DummyPools {
        type PoolState = DummyPoolState;

        type BlockState = u32;

        const POOL_STATE_MEMORY: u8 = 1;

        const BLOCK_STATE_MEMORY: u8 = 2;

        fn network() -> Network {
            Network::Testnet4
        }
    }

    // This is optional
    #[hook]
    impl Hook for DummyPools {}

    // `swap` is the action function that will be called by the REE Orchestrator
    // All actions should return an `ActionResult<S>` where `S` is the pool state of `Pools`.
    // The SDK will automatically commit this state to the IC stable memory.
    #[action(name = "swap")]
    pub async fn execute_swap(
        psbt: &bitcoin::Psbt,
        args: ActionArgs,
    ) -> ActionResult<DummyPoolState> {
        let pool = DummyPools::get(&args.intention.pool_address)
            .ok_or_else(|| format!("Pool not found: {}", args.intention.pool_address))?;
        let mut state = pool.last_state().cloned().unwrap_or_default();
        // do some checks...
        state.nonce = state.nonce + 1;
        state.txid = args.txid.clone();
        Ok(state)
    }
}

#[update]
pub async fn new_pool(name: String) {
    let metadata = Metadata::new::<DummyPools>(name)
        .await
        .expect("Failed to call chain-key API");
    let pool = Pool::new(metadata);
    DummyPools::insert(pool);
}

#[query]
pub fn pre_swap(addr: String) -> Option<StateInfo> {
    DummyPools::get(&addr).and_then(|pool| pool.last_state().map(|s| s.inspect_state()))
}

ic_cdk::export_candid!();

Re-exports

pub use ree_types as types;

Modules

prelude

store

This module provides wrappers around various data structures from the ic_stable_structures crate.

Structs

ActionArgs

The parameter for the action function, which is used to execute a transaction in the exchange.

Block

The parameters for the hook on_block_confirmed and on_block_finalized

Metadata

The metadata for the pool, which includes the key, name, and address. Typically, the key and address should be generated by the IC chain-key.

Pool

The concrete type stored in the IC stable memory. The SDK will automatically manage the pool state S.

StateInfo

The essential information about the pool state.

Enums

Network

The network enum defines the networks supported by the exchange.

Traits

Hook

A hook that can be implemented to respond to block event in the exchange lifecycle. It must be implemented over the BlockState type and marked as #[ree_exchange_sdk::hook].

PoolStorageAccess

A trait for accessing the pool storage. The user-defined Pools type will automatically implement this trait.

Pools

The Pools trait defines the interface for the exchange pools, must be marked as #[ree_exchange_sdk::pools].

StateView

User must implement the StateView trait for customized state to provide this information.

Upgrade

The Upgrade trait is used to handle state migrations when the state type of a Pools implementation changes. Assume MyPools originally has a pool state type MyPoolState and block state type MyBlockState.

Type Aliases

ActionResult

The result type for actions in the exchange, which can either be successful with a state or an error message.