外部crate中的使用

重要的是使用生成代码在外部代码中的可能性。首先，让我们从生成 crate 的文档开始

cargo doc --document-private-items --open

这将生成并打开 crate 的文档，包括所有生成的结构。--document-private-item 是可选的，但它将生成非公开模块的文档，这在某些情况下可能很有用。

在查看文档时，您将看到所有消息都是在它们的结构体/特质模块中生成的。要向合同发送消息，我们可以直接使用它们

use sylvia::cw_std::{WasmMsg, to_json_binary};

fn some_handler(my_contract_addr: String) -> StdResult<Response> {
    let msg = my_contract_crate::sv::ExecMsg::Increment {};
    let msg = WasmMsg::ExecMsg {
        contract_addr: my_contract_addr,
        msg: to_json_binary(&msg)?,
        funds: vec![],
    }

    let resp = Response::new()
        .add_message(msg);
    Ok(resp)
}

我们可以用类似的方式使用特质中的消息

let msg = my_contract_crate::group::QueryMsg::IsMember {
    member: addr,
};

let is_member: my_contract_crate::group::IsMemberResp =
    deps.querier.query_wasm_smart(my_contract_addr, &msg)?;

重要的是不要混淆生成的 ContractExecMsg/ContractQueryMsg 与 ExecMsg/QueryMsg - 前者是仅为合同生成，不是为接口，也不用于向合同发送消息 - 它们的目的是仅用于正确的消息分发，不应在入口点之外使用。

查询助手

为了使查询更加用户友好，Sylvia 为用户提供 sylvia::types::BoundQuerier 和 sylvia::types::Remote 助手。后者用于存储某些远程合同的地址。对于合同中的每个查询方法，Sylvia 都会在生成的 sv::Querier 特质中添加一个方法。然后 sv::Querier 为 sylvia::types::BoundQuerier 实现，这样用户就可以调用该方法。

让我们修改前一段中的查询。目前，它将如下所示

let is_member = Remote::<OtherContractType>::new(remote_addr)
    .querier(&ctx.deps.querier)
    .is_member(addr)?;

您的合同可能需要定期与某些其他合同通信。在这种情况下，您可能希望将其存储为 Contract 中的字段

pub struct MyContract<'a> {
    counter: Item<'a, u64>,
    members: Map<'a, &'a Addr, Empty>,
    remote: Item<'a, Remote<'static, OtherContractType>>,
}

#[sv::msg(exec)]
pub fn evaluate_member(&self, ctx: ExecCtx, ...) -> StdResult<Response> {
    let is_member = self
        .remote
        .load(ctx.deps.storage)?
        .querier(&ctx.deps.querier)
        .is_member(addr)?;
}

执行器消息构建器

Sylvia 定义了 ExecutorBuilder 类型，可以通过 Remote::executor 访问。它针对合约类型进行泛型化，并通过自动生成的 Executor 特性暴露合约及其所有接口的执行方法。可以使用 Remote 构建 其他合约的执行消息，通过调用 executor 方法。它返回一个消息构建器，该构建器实现了所有 Sylvia 合约的自动生成的 Executor 特性。在 Executor 特性中定义的方法构建一个执行消息，其变体对应于方法名。然后，消息被包装在 WasmMsg 中，并在调用 ExecutorBuilder::build() 方法后返回。

use sylvia::types::Remote;
use other_contract::contract::OtherContract;
use other_contract::contract::sv::Executor;

let some_exec_msg: WasmMsg = Remote::<OtherContract>::new(remote_addr)
    .executor()
    .some_exec_method()?
    .build();

使用不支持的入口点

如果需要 Sylvia 中未实现的入口点，可以使用 #[entry_point] 宏手动实现。以下是如何实现消息回复的示例：

use sylvia::cw_std::{DepsMut, Env, Reply, Response};

#[contract]
#[entry_point]
#[sv::error(ContractError)]
#[sv::messages(group as Group)]
impl MyContract<'_> {
    fn reply(&self, deps: DepsMut, env: Env, reply: Reply) -> Result<Response, ContractError> {
        todo!()
    }
    // [...]
}

#[entry_point]
fn reply(deps: DepsMut, env: Env, reply: Reply) -> Result<Response, ContractError> {
    &MyContract::new().reply(deps, env, reply)
}

在合约类型中创建一个入口函数非常重要，这样它就可以访问该类型上定义的所有状态访问器。

覆盖入口点

有一种方法可以覆盖入口点或添加自定义定义的入口点。以下代码示例：

#[cw_serde]
pub enum UserExecMsg {
    IncreaseByOne {},
}

pub fn increase_by_one(ctx: ExecCtx) -> StdResult<Response> {
    crate::COUNTER.update(ctx.deps.storage, |count| -> Result<u32, StdError> {
        Ok(count + 1)
    })?;
    Ok(Response::new())
}

#[cw_serde]
pub enum CustomExecMsg {
    ContractExec(crate::ContractExecMsg),
    CustomExec(UserExecMsg),
}

impl CustomExecMsg {
    pub fn dispatch(self, ctx: (DepsMut, Env, MessageInfo)) -> StdResult<Response> {
        match self {
            CustomExecMsg::ContractExec(msg) => {
                msg.dispatch(&crate::contract::Contract::new(), ctx)
            }
            CustomExecMsg::CustomExec(_) => increase_by_one(ctx.into()),
        }
    }
}

#[entry_point]
pub fn execute(
    deps: DepsMut,
    env: Env,
    info: MessageInfo,
    msg: CustomExecMsg,
) -> StdResult<Response> {
    msg.dispatch((deps, env, info))
}

可以定义一个自定义的 exec 消息，该消息将调度由您的合约生成的和由您定义的生成的消息。要使用此自定义入口点与 contract 宏一起使用，您可以在 sv::override_entry_point(...) 属性中添加。

#[contract]
#[sv::override_entry_point(exec=crate::entry_points::execute(crate::exec::CustomExecMsg))]
#[sv::override_entry_point(sudo=crate::entry_points::sudo(crate::SudoMsg))]
impl Contract {
    // ...
}

可以像这样覆盖所有消息类型。除了入口点路径之外，您还必须提供自定义消息的类型。在 multitest helpers 中需要反序列化消息。

多测试

Sylvia 还为测试合约生成了一些辅助工具，这些工具隐藏在 mt 功能标志后面，需要启用。

当合约在 wasm 目标中构建时，必须确保没有设置 mt 标志，因为某些依赖项在 Wasm 上不可构建。建议在 dev-dependencies 中添加带有 mt 启用的额外 sylvia 入口，并在合约上添加 mt 功能，这样就可以在其他合约测试中启用 mt 工具。以下是一个 Cargo.toml 示例：

[package]
name = "my-contract"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib", "rlib"]

[features]
library = []
mt = ["sylvia/mt"]

[dependencies]
sylvia = "0.10.0"

# [...]

[dev-dependencies]
sylvia = { version = "0.10.0", features = ["mt"] }

以下是示例代码：

#[cfg(test)]
mod tests {
    use super::*;
    use sylvia::multitest::App;

    #[test]
    fn counter_test() {
        let app = App::default();

        let owner = "owner";

        let code_id = contract::CodeId::store_code(&app);

        let contract = code_id.instantiate(3)
            .with_label("My contract")
            .call(&owner)
            .unwrap();

        let counter = contract.counter().unwrap();
        assert_eq!(counter, contract::CounterResp { counter: 3});

        contract.increment().call(&owner).unwrap();

        let counter = contract.counter().unwrap();
        assert_eq!(counter, contract::CounterResp { counter: 4});
    }
}

请注意我这里使用的 contract 模块 - 这是一个与前面的代码略有不同的微小变化 - 我假设所有合约代码都位于 contract 模块中，以确保使用类型的位置清晰。因此，如果我使用 contract::something，它就是原始合约模块（很可能是 Sylvia 生成的）中的 something。

首先——我们不直接使用 cw-multi-test 应用。相反，我们在其上使用 sylvia 包装器。它内部包含原始的多测试应用，但以内部可变的方式执行，这使得它可以避免在各个地方传递。它增加了一些开销，但对于测试代码来说不应有问题。

我们首先使用为每个单独的 Sylvia 合约生成的 CodeId 类型。它的目的是抽象化在区块链中存储合约。它确保创建合约对象并将其传递给多测试。

合约的 CodeId 类型有一个特别有趣的功能——instantiate，它调用一个实例化函数。它接受与合约中实例化函数相同的参数，除了 Sylvia 的实用工具会提供的上下文。

该函数不会立即实例化合约——相反，它返回所谓的 InstantiationProxy。我们决定不强迫用户在每次实例化调用时设置所有元数据——管理员、标签和要发送的资金，因为在绝大多数情况下，它们都是无关紧要的。相反，InstantiationProxy 提供了 with_label、with_funds 和 with_amin 函数，这些函数以构建器模式风格设置这些元字段。

当实例化准备就绪时，我们调用 call 函数，传递消息发送者——我们本可以添加另一个 with_sender 函数，但我们决定，由于发送者每次都必须传递，我们可以在这一点上节省一些击键。

当涉及到执行消息时，事情类似。最大的不同之处在于我们不在 CodeId 上调用它，而是在已实例化的合约上调用。我们还需要设置的字段也较少——执行代理仅提供 with_funds 函数。

所有实例化和执行函数都返回类型为 cw_multi_test::AppResponse, ContractError<cw_multi_test::AppResponse, ContractError> 的类型，其中 ContractError 是合约的错误类型。

多测试中的接口项目

声明所有接口方法的特质直接在合约代理类型上实现。

use contract::mt::Group;

#[test]
fn member_test() {
    let app = App::default();

    let owner = "owner";
    let member = "john";

    let code_id = contract::mt::CodeId::store_code(&app);

    let contract = code_id.instantiate(0)
        .with_label("My contract")
        .call(&owner);

    contract
        .add_member(member.to_owned())
        .call(&owner);

    let resp = contract
        .is_member(member.to_owned())

    assert_eq!(resp, group::IsMemberResp { is_member: true });
}

泛型

接口

在接口上定义关联类型与在常规特质上定义它们一样简单。

#[interface]
pub trait Generic {
    type Error: From<StdError>;
    type ExecParam: CustomMsg;
    type QueryParam: CustomMsg;
    type RetType: CustomMsg;

    #[sv::msg(exec)]
    fn generic_exec(
        &self,
        ctx: ExecCtx,
        msgs: Vec<CosmosMsg<Self::ExecParam>>,
    ) -> Result<Response, Self::Error>;

    #[sv::msg(query)]
    fn generic_query(&self, ctx: QueryCtx, param: Self::QueryParam) -> Result<Self::RetType, Self::Error>;
}

泛型合约

合约中的泛型可能用作泛型字段类型，或用作消息中返回类型的泛型参数。当 Sylvia 生成消息的枚举时，仅用于相应方法的泛型将包含在给定的生成消息类型中。

使用示例

pub struct GenericContract<
    InstantiateParam,
    ExecParam,
    FieldType,
> {
    _field: Item<'static, FieldType>,
    _phantom: std::marker::PhantomData<(
        InstantiateParam,
        ExecParam,
    )>,
}

#[contract]
impl<InstantiateParam, ExecParam, FieldType>
    GenericContract<InstantiateParam, ExecParam, FieldType>
where
    for<'msg_de> InstantiateParam: CustomMsg + Deserialize<'msg_de> + 'msg_de,
    ExecParam: CustomMsg + DeserializeOwned + 'static,
    FieldType: 'static,
{
    pub const fn new() -> Self {
        Self {
            _field: Item::new("field"),
            _phantom: std::marker::PhantomData,
        }
    }

    #[sv::msg(instantiate)]
    pub fn instantiate(
        &self,
        _ctx: InstantiateCtx,
        _msg: InstantiateParam,
    ) -> StdResult<Response> {
        Ok(Response::new())
    }

    #[sv::msg(exec)]
    pub fn contract_execute(
        &self,
        _ctx: ExecCtx,
        _msg: ExecParam,
    ) -> StdResult<Response> {
        Ok(Response::new())
    }
}

入口点中的泛型

入口点必须使用具体类型生成。在泛型合约上使用 entry_points 宏时，必须指定要使用的类型。我们通过 entry_points(generics<..>) 来做这件事

#[cfg_attr(not(feature = "library"), entry_points(generics<SvCustomMsg, SvCustomMsg, SvCustomMsg>))]
#[contract]
impl<InstantiateParam, ExecParam, FieldType>
    GenericContract<InstantiateParam, ExecParam, FieldType>
where
    for<'msg_de> InstantiateParam: CustomMsg + Deserialize<'msg_de> + 'msg_de,
    ExecParam: CustomMsg + DeserializeOwned + 'static,
    FieldType: 'static,
{
    ...
}

合约可以在自定义消息和查询的位置定义一个泛型类型。在这种情况下，我们必须使用 custom 通知 entry_points 宏。

#[cfg_attr(not(feature = "library"), entry_points(generics<SvCustomMsg, SvCustomMsg, SvCustomMsg>, custom(msg=SvCustomMsg, query=SvCustomQuery))]
#[contract]
#[sv::custom(msg=MsgT, query=QueryT)]
impl<InstantiateParam, ExecParam, FieldType, MsgT, QueryT>
    GenericContract<InstantiateParam, ExecParam, FieldType, MsgT, QueryT>
where
    for<'msg_de> InstantiateParam: CustomMsg + Deserialize<'msg_de> + 'msg_de,
    ExecParam: CustomMsg + DeserializeOwned + 'static,
    FieldType: 'static,
{
    ...
}

生成模式

Sylvia 的设计目的是生成所有 cosmwasm-schema 所依赖的代码 - 这使得生成合同的架构变得非常容易。只需添加一个 bin/schema.rs 模块，该模块会被识别为二进制文件，并在其中添加一个简单的 main 函数。

use cosmwasm_schema::write_api;

use my_contract_crate::contract::{ContractExecMsg, ContractQueryMsg, InstantiateMsg};

fn main() {
    write_api! {
        instantiate: InstantiateMsg,
        execute: ContractExecMsg,
        query: ContractQueryMsg,
    }
}

路线图

目前 Sylvia 处于采用阶段，但我们仍在为用户提供更多功能。以下是未来几个月的大致路线图。

• 回复 - Sylvia 仍然需要支持基本的 CosmWasm 消息，即回复。我们希望它们更智能，以便更直接地表达发送的消息和执行的处理程序之间的关联，而不是隐藏在回复调度器中。
• 迁移 - 另一个我们不支持的 重要消息，但原因与回复类似 - 我们希望它们更智能。我们希望为您提供一个很好的方式来提供合约的升级 API，这将负责其版本控制。
• IBC - 我们也想为您提供优秀的 IBC API！然而，请稍等，我们必须首先理解这里最好的模式。
• 更好的工具支持 - Sylvia 的最大问题是它生成的代码不是微不足道的，并且并非所有工具都能很好地处理它。我们正在努力改进这方面的用户体验。

故障排除

为了获得更多描述性的错误消息，请考虑使用夜间工具链（为 cargo 添加 +nightly 参数）。

• 合约接口中缺少消息 - 您可能缺少 #[sv::messages)] 属性。