# Router-wasm-bindings The wasm bindings for building CosmWasm smart contracts that can run on the Router chain. ## Prerequisites Before starting, make sure you have [rustup](https://rustup.rs/) along with a recent `rustc` and `cargo` version installed. Currently, we are testing on 1.62.1+. And you need to have the `wasm32-unknown-unknown` target installed as well. You can check that via: ```sh rustc --version cargo --version rustup target list --installed # if wasm32 is not listed above, run this rustup target add wasm32-unknown-unknown ``` ## Context On the Router chain, We can build two types of contracts. - Contracts that are not interacting with cross-chain contracts. - Contracts that are back and forth sending the data request to cross-chain contracts. To build second type of contracts that are interacting with other chains, the user/ applications needs to implement router-wasm-binding crate. ```sh # add the following line in the cargo.toml [dependencies] section router-wasm-bindings = "1.0.4" ``` ## How to use the Router-Wasm-Bindings To implement cross-chain interoperability, the contract needs to implement the following functionality - **HandleIReceive** for handling incoming requests from the other chains - **HandleIAck** to send a request to the other chains. The Contract can write the intermediate business logic in-between the incoming request and outbound request. While writing the intermediate business logic, the developer can convert single or multiple incoming requests into single or multiple outbound requests. Also, while creating requests to other chains, the contract can be developed in such a way that multiple requests can be generated to different chains. You can find examples of different scenarios in the [cw-bridge-contracts](https://github.com/router-protocol/cw-bridge-contracts.git) repository. ## [SudoMsg] The *SudoMsg* is an enum and it has two different message types. 1. HandleIReceive 2. HandleIAck In the following code snippet, we added the details at the field level of the *SudoMsg*. This will helps us in building an understanding of the data that will be coming either in the inbound request or in the outbound acknowledgment request. ```rust #[derive(Serialize, Deserialize, Clone, Debug, PartialEq, JsonSchema)] #[serde(rename_all = "snake_case")] pub enum SudoMsg { // Sudo msg to handle incoming requests from other chains HandleIReceive { // the inbound initiator application contract address request_sender: String, // inbound request src chain id source_chain_id: String, // inbound request event nonce request_identifier: u64, // the inbound request instructions in base64 format payload: Binary, }, // Sudo msg to handle outbound message acknowledgment HandleIAck { // cross-chain request nonce request_identifier: u64, // cross-chain request contract call execution status exec_flag: u64, // cross-chain request contract call execution exec_data: Binary, // excess fee refunded amount refund_amount: Coin, }, } ``` The sudo function is one of the entry-point in a cosmwasm contract. It can be called internally by the chain only. In Router Chain, the developer needs to implement this sudo function to receive an incoming request. Here, in the following code snippet, we have shown the sample sudo function implementation. Developers can have any sort of business logic inside the *handle_sudo_request* and *handle_sudo_ack* functions. ```rust // import router binding message use router_wasm_bindings::{RouterMsg, SudoMsg}; #[cfg_attr(not(feature = "library"), entry_point)] pub fn sudo(deps: DepsMut, _env: Env, msg: SudoMsg) -> StdResult> { match msg { // Sudo msg to handle incoming requests from other chains SudoMsg::HandleIReceive { request_sender, src_chain_id, request_identifier, payload, } => handle_sudo_request( deps, env, request_sender, src_chain_id, request_identifier, payload, ), // Sudo msg to handle outbound message acknowledgment SudoMsg::HandleIAck { request_identifier, exec_flag, exec_data, refund_amount, } => handle_sudo_ack( deps, env, request_identifier, exec_flag, exec_data, refund_amount, ), } } ``` The sudo message `HandleIReceive` contains 4 arguments. This sudo function gets called when an inbound request comes for your middleware contract. We can handle this sudo request in any possible way or even skip it. As you can see in the code snippet, a function `handle_sudo_request` has been created to handle the incoming inbound request in the cosmwasm contact. Within this function, you can apply any logic to the payload from the incoming request before creating the request for the destination chain. Each field has its own purpose and meaning in the `HandleIReceive` request. 1. **request_sender:** The application contract address on the source chain from which the request to the Router chain was sent. 2. **source_chain_id**: The chain ID of the chain from which the inbound request to the Router chain has been initiated. 3. **request_identifier**: The request identifier is a unique identifier of the request that is added by the source chain's gateway contract. 4. **payload:** The payload comes from the source chain contract. The sudo message `HandleIAck` has 4 arguments. This sudo function gets called when the acknowledgment is received by the middleware contract on the Router chain post-execution of the contract call on the destination chain. We can handle this sudo request in any possible way or even skip it. As you can see in the code snippet, the function `handle_sudo_ack` has been created to handle the incoming acknowledgment request in the cosmwasm contact. Each field has its own purpose and meaning in the `HandleIAck` request. 1. **request_identifier**: The unique and incremented integer value for the outbound request. 2. **exec_flag**: The execution status flag for the contract call which was made on the destination chain. 3. **exec_data:** The execution data for all the requests executed on the destination chain. 4. **refund_amount**: The refunded fee amount is the extra fee that we have passed for the destination side contract execution. ## [RouterMsg] The RouterMsg is an enum type inside the **router-wasm-bindings**. It contains one custom message type. 1. CrosschainCall In the following code snippet, we have added one implementation of CrosschainCall. This message is used to create an outbound request. In the outbound request, we can specify the destination chain id & type, the contract addresses & instructions, the request expiry timestamp, the atomicity flag, etc. ```rust // import router binding message use router_wasm_bindings::{RouterMsg, SudoMsg}; use router_wasm_bindings::types::{ AckType, RequestMetaData, }; use cosmwasm_std::{SubMsg, SubMsgResult, Uint128}; let request_packet: Bytes = encode(&[ Token::String(destination_address.clone()), Token::Bytes(payload), ]); let request_metadata: RequestMetaData = RequestMetaData { dest_gas_limit: gas_limit, dest_gas_price: gas_price, ack_gas_limit: 300_000, ack_gas_price: 10_000_000, relayer_fee: Uint128::zero(), ack_type: AckType::AckOnBoth, is_read_call: false, asm_address: String::default(), }; let i_send_request: RouterMsg = RouterMsg::CrosschainCall { version: 1, route_amount, route_recipient, dest_chain_id: destination_chain_id, request_metadata: request_metadata.get_abi_encoded_bytes(), request_packet, }; let cross_chain_sub_msg: SubMsg = SubMsg { id: CREATE_OUTBOUND_REPLY_ID, msg: i_send_request.into(), gas_limit: None, reply_on: ReplyOn::Success, }; let res = Response::new() .add_submessage(cross_chain_sub_msg.into()) Ok(res) ``` The `CrosschainCall` is a data_type that helps the end user to create an cross-chain request to any destination chain. It has 6 arguments. 1. **version**: The chain type of the chain for which the outbound request from the Router chain has been created. 2. **route_amount**: The route token amount that needs to be burned on the router chain and minted/unlocked on the destination chain. 3. **route_recipient**: The recipient address of the route token on the destination chain. 4. **destination_chain_id**: The chain ID of the chain for which the outbound request from the Router chain has been created. 5. **request_metadata**: The request metadata is encodedPacked information that contains information destination gas limit & price, ack gas limit & price, relayer fee, ack_type, is_read_call and asm_address. 6. **request_packet**: The request packet is encoded information of destination address and payload. In example we can see how are we encoding this information. Since the application developer is writing the application middleware contracts, they will have complete control over what kind of data is received in the payload. They can define the encoding and decoding of the data accordingly and perform any operation on the data. ## Compiling and running tests Now that you created your custom contract, make sure you can compile and run it before making any changes. Go into the repository and do: ```sh # this will produce a wasm build in ./target/wasm32-unknown-unknown/release/YOUR_NAME_HERE.wasm cargo wasm # this runs unit tests with helpful backtraces RUST_BACKTRACE=1 cargo unit-test # auto-generate json schema cargo schema ``` ### Understanding the tests The main code is in `src/contract.rs` and the unit tests there run in pure rust, which makes them very quick to execute and give nice output on failures, especially if you do `RUST_BACKTRACE=1 cargo unit-test`. We consider testing critical for anything on a blockchain, and recommend to always keep the tests up to date. ## Generating JSON Schema While the Wasm calls (`instantiate`, `execute`, `query`) accept JSON, this is not enough information to use it. We need to expose the schema for the expected messages to the clients. You can generate this schema by calling `cargo schema`, which will output 3 files in `./schema`, corresponding to the 3 message types the contract accepts. These files are in standard json-schema format, which should be usable by various client side tools, either to auto-generate codecs, or just to validate incoming json wrt. the defined schema. ## Preparing the Wasm bytecode for production Before we upload it to a chain, we need to ensure the smallest output size possible, as this will be included in the body of a transaction. We also want to have a reproducible build process, so third parties can verify that the uploaded Wasm code did indeed come from the claimed rust code. To solve both these issues, we have produced `rust-optimizer`, a docker image to produce an extremely small build output consistently. The suggested way to run it is this: ```sh docker run --rm -v "$(pwd)":/code \ --mount type=volume,source="$(basename "$(pwd)")_cache",target=/code/target \ --mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \ cosmwasm/rust-optimizer:0.12.6 ``` Or, If you're on an arm64 machine, you should use a docker image built with arm64. ```sh docker run --rm -v "$(pwd)":/code \ --mount type=volume,source="$(basename "$(pwd)")_cache",target=/code/target \ --mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \ cosmwasm/rust-optimizer-arm64:0.12.6 ``` We must mount the contract code to `/code`. You can use an absolute path instead of `$(pwd)` if you don't want to `cd` to the directory first. The other two volumes are nice for speedup. Mounting `/code/target` in particular is useful to avoid docker overwriting your local dev files with root permissions. Note the `/code/target` cache is unique for each contract being compiled to limit interference, while the registry cache is global. This is rather slow compared to local compilations, especially the first compilation of a given contract. The use of the two volume caches is very useful to speed up following compiles of the same contract. This produces an `artifacts` directory with a `PROJECT_NAME.wasm`, as well as `checksums.txt`, containing the Sha256 hash of the wasm file. The wasm file is compiled deterministically (anyone else running the same docker on the same git commit should get the identical file with the same Sha256 hash). It is also stripped and minimized for upload to a blockchain (we will also gzip it in the uploading process to make it even smaller).