Rust跨链通信库bp-xcm-bridge-hub-router使用指南

简介

bp-xcm-bridge-hub-router是一个用于波卡(Polkadot)生态系统的Rust库，专门处理XCM(Cross-Consensus Messaging)消息的跨桥路由和资产跨链转移。该库简化了在不同平行链之间发送XCM消息和转移资产的复杂过程。

主要功能

1. 跨链消息路由
2. 资产跨链转移
3. 桥接中心(Bridge Hub)之间的通信
4. XCM消息格式处理

安装

在Cargo.toml中添加依赖：

[dependencies]
bp-xcm-bridge-hub-router = { git = "https://github.com/paritytech/polkadot-sdk.git", branch = "master" }

基本使用方法

1. 初始化路由器

use bp_xcm_bridge_hub_router::XcmBridgeHubRouter;

let router = XcmBridgeHubRouter::new(
    source_bridge_hub_id,  // 源BridgeHub链ID
    target_bridge_hub_id,  // 目标BridgeHub链ID
    source_para_id,        // 源平行链ID
    target_para_id         // 目标平行链ID
);

2. 发送简单XCM消息

use xcm::latest::prelude::*;

let message = Xcm(vec![
    Instruction::WithdrawAsset(MultiAssets::from(vec![(Here, 100u128).into()])),
    Instruction::DepositAsset {
        assets: MultiAssetFilter::Definite(MultiAssets::from(vec![(Here, 100u128).into()])),
        beneficiary: Junction::AccountId32 {
            network: None,
            id: [1u8; 32],
        }.into(),
    },
]);

let result = router.send极链资产转移

```rust
use bp_xcm_bridge_hub_router::AssetTransfer;

let transfer = AssetTransfer::new(
    router,  // 使用前面初始化的路由器
    asset_id,  // 要转移的资产ID
    amount,    // 转移数量
    recipient  // 接收方账户
);

match transfer.execute() {
    Ok(()) => println!("资产跨链转移成功"),
    Err(e) => println!("转移失败: {:?}", e),
}

高级功能

自定义XCM路由策略

use bp_xcm_bridge_hub_router::{RoutingStrategy, XcmBridgeHubRouterBuilder};

let router = XcmBridgeHubRouterBuilder::new()
    .with_source(source_bridge_hub_id)
    .with_target(target_bridge_hub_id)
    .with_routing_strategy(RoutingStrategy::OptimizedForFee)
    .build();

处理XCM响应

use xcm::latest::{Response, Outcome};

let message = Xcm(vec![
    /* 指令... */
    Instruction::ReportHolding {
        response_info: QueryResponseInfo {
            destination: MultiLocation::here(),
            query_id: 42,
            max_weight: Weight::from_parts(1_000_000, 1_000_000),
        },
        assets: MultiAssetFilter::Definite(MultiAssets::new()),
    },
]);

router.send_xcm_with_callback(message, |response: Outcome<Response, ()>| {
    match response {
        Outcome::Complete(response) => {
            println!("收到XCM响应: {:?}", response);
        }
        Outcome::Incomplete(_, error) => {
            println!("XCM响应不完整: {:?}", error);
        }
        Outcome::Error(error) => {
            println!("XCM响应错误: {:?}", error);
        }
    }
});

错误处理

use bp_xcm_bridge_hub_router::Error;

match router.send_xcm(message) {
    Ok(()) => { /* 成功处理 */ },
    Err(Error::UnsupportedChain) => {
        println!("不支持的链");
    },
    Err(Error::XcmConstructionFailed) => {
        println!("XCM消息构建失败");
    },
    Err(Error::XcmExecutionFailed) => {
        println!("XCM执行失败");
    },
    Err(e) => {
        println!("其他错误: {:?}", e);
    },
}

最佳实践

1. 总是检查目标链是否支持特定的XCM指令
2. 考虑设置适当的权重和费用预算
3. 处理可能的XCM执行失败情况
4. 对于大额资产转移，考虑分批处理

完整示例代码

以下是一个完整的跨链资产转移示例，包含了错误处理和响应回调：

use bp_xcm_bridge_hub_router::{XcmBridgeHubRouter, AssetTransfer, RoutingStrategy, Error};
use xcm::latest::prelude::*;
use sp_runtime::AccountId32;
use xcm::latest::{Response, Outcome};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. 初始化路由器 - 使用构建器模式配置高级选项
    let router = XcmBridgeHubRouterBuilder::new()
        .with_source(1000)   // Polkadot BridgeHub
        .with_target(2000)   // Kusama BridgeHub
        .with_routing_strategy(RoutingStrategy::OptimizedForFee)
        .build();

    // 2. 准备资产转移参数
    let asset = MultiLocation::new(
        1,                  // 父级相对路径
        X1(Parachain(2001)) // Acala平行链
    );
    let amount = 100_000_000_000u128; // 100 ACA (12位小数)
    let recipient = AccountId32::new([1u8; 32]);
    
    // 3. 创建资产转移对象
    let transfer = AssetTransfer::new(
        router,
        asset.clone(),
        amount,
        recipient.into()
    );

    // 4. 发送带回调的XCM消息
    let message = Xcm(vec![
        Instruction::WithdrawAsset((asset, amount).into()),
        Instruction::DepositAsset {
            assets: MultiAssetFilter::Definite((asset, amount).into()),
            beneficiary: Junction::AccountId32 {
                network: None,
                id: recipient.into(),
            }.into(),
        },
        Instruction::ReportHolding {
            response_info: QueryResponseInfo {
                destination: MultiLocation::here(),
                query_id: 1,
                max_weight: Weight::from_parts(1_000_000, 1_000_000),
            },
            assets: MultiAssetFilter::Definite(MultiAssets::new()),
        },
    ]);

    // 5. 执行转移并处理结果
    match transfer.execute() {
        Ok(_) => {
            println!("资产转移交易已提交");
            
            // 设置回调处理XCM响应
            router.send_xcm_with_callback(message, |response: Outcome<Response, ()>| {
                match response {
                    Outcome::Complete(res) => handle_xcm_response(res),
                    Outcome::Incomplete(_, err) => eprintln!("XCM执行不完整: {:?}", err),
                    Outcome::Error(err) => eprintln!("XCM执行错误: {:?}", err),
                }
            });
        }
        Err(Error::UnsupportedChain) => {
            eprintln!("错误: 不支持的链");
            return Err("不支持的链".into());
        }
        Err(e) => {
            eprintln!("资产转移失败: {:?}", e);
            return Err(e.into());
        }
    }

    Ok(())
}

fn handle_xcm_response(response: Response) {
    println!("收到XCM响应:");
    match response {
        Response::Assets(assets) => {
            println!("返回资产: {:?}", assets);
        }
        Response::Version(_) => {
            println!("版本信息响应");
        }
        _ => {
            println!("其他类型响应: {:?}", response);
        }
    }
}

这个完整示例展示了如何：

1. 使用构建器模式初始化路由器
2. 配置跨链资产转移参数
3. 构建包含响应报告的XCM消息
4. 处理转移执行结果
5. 设置回调函数处理XCM响应

通过这个示例，您可以实现一个完整的跨链资产转移流程，包括错误处理和响应监控。