cw-orchestrator

A Rust 工具，用于与 CosmWasm 智能合约交互。它提供了一个类型安全的接口来访问 CosmWasm 合约，并允许您轻松地与之交互。它通过提供一组宏来生成对您的合约的类型安全接口来实现这一点。然后，您可以将您的合约接口组合成一个可以与他人共享的单个对象，以简化集成工作并鼓励协作。

此处的文档为您提供了 cw-orchestrator 提供的功能的简要概述。我们还在 orchestrator.abstract.money 提供了更多文档。

工作原理

与 CosmWasm 合约的交互是通过调用该合约的端点来完成的，使用该端点适当的消息（例如 ExecuteMsg，InstantiateMsg，QueryMsg，MigrateMsg 等）。cw-orchestrator 为您的合约生成类型化接口，允许它们在编译时进行类型检查。这个通用接口允许您编写环境通用的代码，这意味着当您将应用程序部署到测试/主网时，您可以重用您为部署到 cw-multi-test 编写的代码。

维护的接口

我们维护了一个小型接口集，我们在自己的项目中使用它。这些接口由 Abstract 团队维护，并且是使用库的良好参考。

代码库	最新版本
cw-plus
wyndex
AbstractSDK

创建接口

为了生成合约的类型化接口，您可以向 contract 宏传递合约的消息类型，或者您可以将 interface 宏添加到您的端点函数导出中！

contract 宏

向以您的合约命名的新结构体提供您的消息。

use cw_orch::contract;
// Provide the messages in the order Init, Exec, Query, Migrate.
#[interface(InstantiateMsg, ExecuteMsg, QueryMsg, MigrateMsg)]
pub struct Cw20;

然后为其实现一个构造函数

use cw_orch::{CwEnv,Contract};
impl<Chain: CwEnv> Cw20 <Chain>{
    pub fn new(name: &str, chain: Chain) -> Self {
        Self(Contract::new(name, chain))
    }
}

interface_entry_point 宏

您可以通过将宏 interface_entry_point 添加到合约端点来创建一个合约接口。生成的接口名称将是PascalCase格式的crate名称。

#[cw_orch::interface_entry_point]
fn instantiate(...)

#[cw_orch::interface_entry_point]
fn execute(...)

现在，您已经拥有了一个可以与合约交互的合约接口。

用法

您可以使用此接口与合约进行交互。

// ## Environment setup ##
let sender = Addr::unchecked("sender");
// Create a new mock chain (backed by cw-multi-test)
let chain = Mock::new(&sender);

let cw20_base: Cw20<Chain> = Cw20::new("my_token", chain);
// Upload the contract
cw20_base.upload()?;
// instantiate a CW20 token
let cw20_init_msg = cw20_base::msg::InstantiateMsg {
    decimals: 6,
    name: "Test Token".to_string(),
    initial_balances: vec![Cw20Coin {
        address: sender.to_string(),
        amount: 1000000u128.into(),
    }],
    marketing: None,
    mint: None,
    symbol: "TEST".to_string(),
};
cw20_base.instantiate(&cw20_init_msg, None, None)?;

// Query balance
// Notice that this query is generated by a macro and not defined in the object itself!
// There is also no need to provide a return type of the query.
let balance: Cw20BalanceResponse = cw20_base.balance(sender.to_string())?;

功能

cw-orchestrator提供了两个额外的宏，可以提高脚本体验。

ExecuteFns

ExecuteFns 宏可以添加到合约的 ExecuteMsg 定义中。它将生成一个特质，允许您直接调用消息的变体，而无需自己构建结构体。

应该仅在启用“接口”特质时将宏添加到结构体中。以下示例中的 interface 特质确保了这一点

示例

#[cfg_attr(feature="interface", derive(cw_orch::ExecuteFns))]
pub enum ExecuteMsg{
    Freeze {},
    UpdateAdmins { admins: Vec<String> },
    /// the `payable` attribute will add a `coins` argument to the generated function
    #[cfg_attr(feature="interface", derive(cw_orch::payable))]
    Deposit {}
}

// Define the interface, which is generic over the CosmWasm environment (Chain)
#[interface(Empty,ExecuteMsg,Empty,Empty)]
struct Cw1<Chain>

impl<Chain: CwEnv> Cw1<Chain> {
    pub fn test_macro(&self) {
        self.freeze().unwrap();
        self.update_admins(vec!["new_admin".to_string()]).unwrap();
        self.deposit(&[Coin::new(13,"juno")]).unwrap();
    }
}

我们建议将 ExecuteMsgFns 宏放在功能标志后面，以避免默认引入 cw-orchestrator。

QueryFns

QueryFns derive 宏与 ExecuteFns 宏的工作方式相同，但它还使用来自 cosmwasm-schema 的 #[returns(QueryResponse)] 属性来生成具有正确响应类型的查询。

impl_into 特质

对于嵌套消息（执行和查询），您可以添加一个 impl_into 属性。它期望枚举实现提供类型的 Into 特质。这对于处理泛型消息非常有用。

// An execute message that is generic.
pub enum ExecuteMsg<T>{
    Generic(T),
}

#[cfg_attr(feature="interface", derive(cw_orch::ExecuteFns))]
#[cfg_attr(feature="interface", impl_into(ExecuteMsg<T>))]
pub enum Foo {
    Bar { msg: String },
}

impl From<Foo> for ExecuteMsg<Foo> {
    fn from(msg: Foo) -> Self {
        ExecuteMsg::Generic(msg)
    }
}

// Now the following is possible:

#[interface(Empty,ExecuteMsg<Foo>,Empty,Empty)]
struct Example<Chain>

impl<Chain: CwEnv> Example<Chain> {
    pub fn test_macro(&self) {
        // function `bar` is available because of the `impl_into` attribute! 
        self.bar("hello".to_string()).unwrap();
    }
}

贡献

我们非常欢迎您的帮助！请阅读我们的贡献指南 以开始。

文档

文档使用 mdbook 生成。编辑 docs/src 文件夹中的文件，并运行

just serve-docs

以查看更改。

测试

要测试完整的应用程序，您可以运行以下命令

cargo test --jobs 1 --all-features

参考

轻松编写智能合约脚本？通过使用 Abstract 轻松构建您的合约。

免责声明

此软件按原样提供，不提供任何保证。

致谢

cw-orchestrator 受 terra-rust-api 启发，并使用 cosmos-rust 进行 protocol buffer gRPC 通信。