Single Contract Crate Setup

You can find the code for this example in the cw-orch counter-contract folder.

If you are a fast or visual learner, you can find a Before-After view of the cw-orch integration process in the sample contract.

Dependency

Before we can create an interface we need to add cw-orch to the contract’s Cargo.toml file. In counter run:

$ cargo add --optional cw-orch
> Adding cw-orch v0.16.0 to optional dependencies.

or add it manually to the counter/Cargo.toml file:

[dependencies]
cw-orch = {version = "0.16.0", optional = true } # Latest version at time of writing

We add cw-orch as an optional dependency to ensure that it is not included in the wasm artifact of the contract. This way there are no trust assumptions made about the code added by cw-orch, making it safe to use for production contracts.

Feature

However, we will need a way to enable the dependency when we want to use it. To do this add an interface feature to the Cargo.toml and enable cw-orch when it is enabled.

You can do this by including the following in the counter/Cargo.toml:

[features]
interface = ["dep:cw-orch"] # Adds the dependency when the feature is enabled

Features (aka. feature flags) are a way to enable or disable parts of your code. In this case, we are including cw-orch as a dependency when the interface feature is enabled. This is a common pattern for feature flags.

Crate Structure

Now that we have our dependency set up, we can create the files that will contain our interface. We will create that interface in an interface.rs file inside the crate (counter/src/interface.rs). Then, we need to include that file inside our project. However, that file will contain multiple cw-orch imports that we don’t want to have in our final contract wasm. In order to prevent that, we will import our interface.rs file and feature-flag it like so, in counter/src/lib.rs:

#[cfg(feature = "interface")]
mod interface;

NOTE: Agains, this interface feature is very important to make sure that creating interfaces won’t change anything to the actual wasm file that you are uploading on-chain.

In the next section, we will learn how to define the interface to be able to interact with an actual contract inside this interface.rs file.

Final structure

Following the steps above, the directory structure should eventually look like this:

.
├── Cargo.toml
├── artifacts
│   └── counter_contract.wasm (binary file)
└── counter
    ├── Cargo.toml
    ├── bin
    │   └── deploy.rs
    └── src
        ├── contract.rs (execute, instantiate, query, ...)
        ├── msg.rs (ExecuteMsg, QueryMsg, ...)
        ├── interface.rs (`cw-orch` contract structure definition)
        └── ..

NOTE:

  • The artifacts folder is generated by the rust-optimizer, and contains all your compiled contracts

  • Place your scripts inside the bin directory. Those can be run using the following command:

    cargo run --bin deploy
    

Now that the setup is complete, you can go back to the Contracts page to create the interface for your contract and start scripting/testing your contracts withe ease.