Kujira ICS20 钩子合约

概述

此 CosmWasm 合约作为 Kujira 的 ICS20 转账回调的包装。它提供了一种在跨链转账完成后执行回调的机制，可以是单个转账后，也可以是在一批转账全部完成后。合约可以处理单个交易中的多个代币转账。

特性

• 执行带可定制回调的跨链转账
• 支持单个交易中多个代币转账
• 两种类型的回调
  • AfterAny: 每次成功转账后触发
  • AfterAll: 仅在批次中所有转账都成功后触发
• 处理转账成功、错误和超时
• 可定制转账超时
• 通过 ID 查询转账状态或检索所有转账

合约消息

InstantiateMsg

用于初始化合约。目前不需要任何参数。

pub struct InstantiateMsg {}

ExecuteMsg

执行合约上操作的主要消息。

pub enum ExecuteMsg {
    Transfer {
        channel_id: String,
        to_address: String,
        timeout: IbcTimeout,
        transfer_callback: CallbackType,
        callback: Option<CallbackData>,
    },
}

• channel_id: 转账的 IBC 通道 ID
• to_address: 目标链上的接收地址
• timeout: IBC 转账的超时时间
• transfer_callback: 执行转账后要执行的回调类型（AfterAny 或 AfterAll）
• callback: 转账启动后立即发送给发送方的回调，包含与转账关联的内部 ID

注意：实际要转账的代币应与此消息一起发送。

QueryMsg

合约中可用的查询

pub enum QueryMsg {
    TransferStatus { id: Uint128 },
    AllTransfers {
        limit: Option<u32>,
        start_after: Option<Uint128>,
    },
}

• TransferStatus: 通过 ID 查询特定转账的状态
• AllTransfers: 查询所有转账的状态，可选分页

回调类型

pub enum CallbackType {
    AfterAny(CallbackData),
    AfterAll(CallbackData),
}

• AfterAny: 每次成功转账后执行回调
• AfterAll: 仅在批次中所有转账都成功后执行回调

pub struct TransferStartedResponse {
    pub id: Uint128,
}

在发起传输后，此信息将返回到初始回调中的 data 字段。

• id：与传输相关的内部ID

用法

1. 在基于Cosmos的区块链上实例化合约。

2. 要使用回调发起传输

   let msg = ExecuteMsg::Transfer {
       channel_id: "channel-0".to_string(),
       to_address: "recipient_address".to_string(),
       timeout: IbcTimeout::with_timestamp(Timestamp::from_seconds(future_timestamp)),
       transfer_callback: CallbackType::AfterAny(CallbackData(Binary::from(b"callback_data"))),
       callback: Some(CallbackData(Binary::from(b"initial_callback_data"))),
   };
   

   发送此消息以及您想要传输的代币。合约将为每个发送的代币发起一个IBC传输。

3. 合约将处理传输并基于指定的类型和传输结果执行回调。

4. 查询传输状态

   let query_msg = QueryMsg::TransferStatus { id: Uint128::new(1) };
   

5. 查询所有传输

   let query_msg = QueryMsg::AllTransfers { limit: Some(10), start_after: None };
   

传输过程

1. 当接收到 ExecuteMsg::Transfer 时，合约处理消息中发送的每个代币。
2. 对于每个代币，使用提供的通道ID、接收者地址和超时发起一个IBC传输。
3. 合约内部跟踪每个传输的状态。
4. 根据指定的类型（AfterAny或AfterAll）和传输的成功与否执行回调。

错误处理

在传输错误或超时的情况下，TransferResult 将设置为 Error 或 Timeout。合约仍将根据指定的类型执行回调。

如果发送方合约在回调执行期间发生错误，它将不会回滚整个事务，因为无论如何都会保存IBC确认。