Introduction

In the CosmWasm SDK, submessages are a powerful feature that allows a contract to execute additional messages within the context of its own execution. SubMsg just wraps the CosmosMsg, adding some info to it: the id field, and reply_on. reply_on describes if the reply message should be sent on processing success, on failure, or both. To create submessages, instead of setting all the fields separately, you would typically use helper constructors: SubMsg::reply_on_success, SubMsg::reply_on_error and SubMsg::reply_always.

In this tutorial, you will learn how to use submessages to execute a counter smart contract on Secret Network from another Secret Network smart contract 😊

Getting Started

1. Fund your Secret testnet wallet

2. git clone the submessages example repository:

git clone https://github.com/writersblockchain/secret-submessages

Our Multi Contract System

In this tutorial, we will use submessages to execute a counter smart contract that is already deployed to the Secret Network Testnet. Thus, we are working with two smart contracts:

1. Manager Contract - which executes the Counter Contract using submessages

2. Counter Contract - which is executed by the Manager Contract

Designing the Manager Contract

We will be designing a Manager Smart Contract which can execute a Counter Contract that is deployed to the Secret testnet. Let's start by examining the message that we want to execute on the counter smart contract. In the src directory, open msg.rs and review the Increment msg:

#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum ExecuteMsg {
    Increment { contract: String },
}

Increment contains one parameter, the string contract. This is the contract address of the counter contract, which we will increment.

Notice that we implement HandleCallBack for our ExecuteMsg enum, which is what allows our submessages to be converted into a CosmosMsg and executed:

use secret_toolkit::utils::HandleCallback;

impl HandleCallback for ExecuteMsg {
    const BLOCK_SIZE: usize = BLOCK_SIZE;
}

Reply entry point

Submessages offer different options for the other contract to provide a reply. There are four reply options you can choose:

pub enum ReplyOn {
    /// Always perform a callback after SubMsg is processed
    Always,
    /// Only callback if SubMsg returned an error, no callback on success case
    Error,
    /// Only callback if SubMsg was successful, no callback on error case
    Success,
    /// Never make a callback - this is like the original CosmosMsg semantics
    Never,
}

In order to handle the reply from the other contract, the calling contract must implement a new entry point, called reply:

#[entry_point]
pub fn reply(deps: DepsMut, _env: Env, msg: Reply) -> Result<Response, ContractError> {
    match msg.id {
        EXECUTE_INCREMENT_REPLY_ID => handle_increment_reply(deps, msg),
        id => Err(ContractError::UnexpectedReplyId { id }),
    }
}

Here is an example of how to handle the reply:

fn handle_increment_reply(_deps: DepsMut, msg: Reply) -> Result<Response, ContractError> {
    match msg.result {
        SubMsgResult::Ok(_) => Ok(Response::new().add_attribute("action", "increment")),

        SubMsgResult::Err(e) => Err(ContractError::CustomError { val: e }),
    }
}

The submessage returns a Result containing:

• Ok(Response) if the submessage executed successfully, with an action attribute set to "increment".

• Err(ContractError) if the submessage execution failed, with the error encapsulated in a custom contract error.

Executing the Manager contract

Now let's use this manager smart contract to increment a counter smart contract with submessages!

The counter contract we will be executing is deployed here:

const contractAddress = "secret1cldglt6wvueva2akly4x3wvzzlevk2hxzv0cvq";

cd into manager/node:

cd manager/node

Install the dependencies:

npm i 

Run node execute to execute the counter contract:

node execute 

Upon successful execution, you will see a tx returned in your terminal:

{
  height: 5867847,
  timestamp: '',
  transactionHash: '046C97A2E2404FBF2AB75AFA0850BCD3CC7693BE270FA9DB86D2CE85EEDA5094',
  code: 0,
  codespace: '',
  info: '',
  tx: {
    '@type': '/cosmos.tx.v1beta1.Tx',
    body: {
      messages: [Array],
      memo: '',
      timeout_height: '0',
      extension_options: [],
      non_critical_extension_options: []
    }

Querying the counter contract

Now, let's query the counter contract to make sure it was executed correctly!

cd into counter/node:

cd counter/node

Install the dependencies:

npm i 

And run node query:

node query 

You will see that the counter contract has been incremented by 1 :)

{ count: 1 }

Summary

In this tutorial, you learned how to utilize submessages in the CosmWasm SDK to perform complex, atomic operations within smart contracts on the Secret Network. This guide walked you through executing a counter smart contract from another contract, detailing the setup of a Manager Contract that triggered the Counter Contract using submessages, managing replies, and verifying the execution results 🤓

Contract code hash helper function

To retrieve a Secret Network smart contract's code hash from within a Secret contract call, you can use Stargate queries to directly query the on-chain data from inside the contract.

This helper function is particularly interesting if you desire to make complicated contract structures that involve submessages or just cross-contract messages to different Secret Network contracts. With this code snippet, you do not need to supply the code_hash of each contract that you are going to call in submessage or normal messages. It is sufficient to know the contract address of the other contract, the code snipped will fetch the latest on chain code_hash for you.

The Secret Network team has designed a helper function, get_contract_code_hash, exactly for this purpose.

Simply add the Anybuf package and the "stargate" feature for cosmwasm-std to your cargo.toml:

[dependencies]
cosmwasm-std = { package = "secret-cosmwasm-std", version = "1.1.10", features = ["stargate"]}
anybuf = {version = "0.5.0"}

And then add the function to your contract:

fn get_contract_code_hash(deps: DepsMut, contract_address: String) -> StdResult<String> {
    let code_hash_query: cosmwasm_std::QueryRequest<cosmwasm_std::Empty> = cosmwasm_std::QueryRequest::Stargate {
        path: "/secret.compute.v1beta1.Query/CodeHashByContractAddress".into(),
        data: Binary(Anybuf::new()
        .append_string(1, contract_address)
        .into_vec())
    };

    let raw = to_vec(&code_hash_query).map_err(|serialize_err| {
        StdError::generic_err(format!("Serializing QueryRequest: {}", serialize_err))
    })?;

    let code_hash = match deps.querier.raw_query(&raw) {
        SystemResult::Err(system_err) => Err(StdError::generic_err(format!(
            "Querier system error: {}",
            system_err
        ))),
        SystemResult::Ok(ContractResult::Err(contract_err)) => Err(StdError::generic_err(format!(
            "Querier contract error: {}",
            contract_err
        ))),
        SystemResult::Ok(ContractResult::Ok(value)) => Ok(value)
    }?;

    // Remove the "\n@" if it exists at the start of the code_hash
    let mut code_hash_str = String::from_utf8(code_hash.to_vec()).map_err(|err| {
        StdError::generic_err(format!("Invalid UTF-8 sequence: {}", err))
    })?;

    if code_hash_str.starts_with("\n@") {
        code_hash_str = code_hash_str.trim_start_matches("\n@").to_string();
    }

    Ok(code_hash_str)
}