stellar-interchain-token-service 2.0.0

InterchainTokenService contract, responsible for allowing users/developers to easily create their own token bridge.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

use stellar_axelar_std::events::Event;
use stellar_axelar_std::{ensure, BytesN, Env};

use crate::error::ContractError;
use crate::event::FlowLimitSetEvent;
use crate::storage;

const EPOCH_TIME: u64 = 6 * 60 * 60; // 6 hours in seconds = 21600

pub enum FlowDirection {
    /// An interchain transfer coming in to this chain from another chain
    In,
    /// An interchain transfer going out from this chain to another chain
    Out,
}

impl FlowDirection {
    fn flow(&self, env: &Env, token_id: BytesN<32>) -> i128 {
        match self {
            Self::In => flow_in_amount(env, token_id),
            Self::Out => flow_out_amount(env, token_id),
        }
    }

    fn reverse_flow(&self, env: &Env, token_id: BytesN<32>) -> i128 {
        match self {
            Self::In => flow_out_amount(env, token_id),
            Self::Out => flow_in_amount(env, token_id),
        }
    }

    fn update_flow(&self, env: &Env, token_id: BytesN<32>, new_flow: i128) {
        match self {
            Self::In => storage::set_flow_in(env, token_id, current_epoch(env), &new_flow),
            Self::Out => storage::set_flow_out(env, token_id, current_epoch(env), &new_flow),
        };
    }

    /// Adds flow amount in the specified direction (in/out) for a token.
    /// Flow amounts are stored in temporary storage since they only need to persist for
    /// the 6-hour epoch duration.
    ///
    /// Checks that:
    /// - Flow amount doesn't exceed the flow limit
    /// - The flow in each direction doesn't exceed `i128::MAX`
    /// - Net flow (outgoing minus incoming flow) doesn't exceed the flow limit, i.e |flow - reverse_flow| <= flow_limit
    pub fn add_flow(
        &self,
        env: &Env,
        token_id: BytesN<32>,
        flow_amount: i128,
    ) -> Result<(), ContractError> {
        let Some(flow_limit) = flow_limit(env, token_id.clone()) else {
            return Ok(());
        };

        ensure!(
            flow_amount <= flow_limit,
            ContractError::FlowAmountExceededLimit
        );

        let flow = self.flow(env, token_id.clone());
        let reverse_flow = self.reverse_flow(env, token_id.clone());

        let new_flow = flow
            .checked_add(flow_amount)
            .ok_or(ContractError::FlowAmountOverflow)?;

        // Since `new_flow` and `reverse_flow` are both positive, there won't be any overflow
        let net_flow = new_flow
            .checked_sub(reverse_flow)
            .expect("unexpected overflow");

        // `net_flow.abs()` can't overflow since `net_flow` can never be `i128::MIN` through subtracting two non-negative values
        ensure!(
            net_flow.abs() <= flow_limit,
            ContractError::FlowLimitExceeded
        );

        self.update_flow(env, token_id, new_flow);

        Ok(())
    }
}

pub fn current_epoch(env: &Env) -> u64 {
    env.ledger().timestamp() / EPOCH_TIME
}

pub fn flow_limit(env: &Env, token_id: BytesN<32>) -> Option<i128> {
    storage::try_flow_limit(env, token_id)
}

pub fn set_flow_limit(
    env: &Env,
    token_id: BytesN<32>,
    flow_limit: Option<i128>,
) -> Result<(), ContractError> {
    if let Some(flow_limit) = flow_limit {
        ensure!(flow_limit >= 0, ContractError::InvalidFlowLimit);

        storage::set_flow_limit(env, token_id.clone(), &flow_limit);
    } else {
        storage::remove_flow_limit(env, token_id.clone());
    }

    FlowLimitSetEvent {
        token_id,
        flow_limit,
    }
    .emit(env);

    Ok(())
}

pub fn flow_out_amount(env: &Env, token_id: BytesN<32>) -> i128 {
    storage::try_flow_out(env, token_id, current_epoch(env)).unwrap_or(0)
}

pub fn flow_in_amount(env: &Env, token_id: BytesN<32>) -> i128 {
    storage::try_flow_in(env, token_id, current_epoch(env)).unwrap_or(0)
}