Introduction

Overview and demonstration of cw-orchestrator on an Archway community call.

cw-orchestrator is the most advanced scripting, testing, and deployment framework for CosmWasm smart-contracts. It makes it easy to write cross-environment compatible code for cw-multi-test, Test Tube, Starship (alpha), and live networks, significantly reducing code duplication and test-writing time. Orchestrator's toolkit also brings powerful testing capabilities, currently under development, to the CosmWasm ecosystem including clone-testing, snapshot testing, and a robust CLI.

To learn more about the tool and access all the features available, please go through cw-orchestrator official documentation

Feature-Set TL;DR:

All features are expanded upon further below.

Production-Ready

• Environment-agnostic type-safe interface generation.
• Sync and async Cosmos-SDK queriers and executors over gRPC and RPC.
• Unit testing via cw-multi-test and Test-Tube
• Live network compatibility and integration testing

Pre-Release

• Clone Testing
• IBC-enabled cw-multi-test
• Cosmology's Starship integration
  • Test Cosmos ecosystem + Relaying
  • Multi-chain deployments
  • Channel and packet monitoring.

Alpha

• Snapshot Testing
• Cw-Orch CLI (demo)

The Problem

One of the biggest advantages to CosmWasm as a smart-contract framework is that it's fully based in Rust. This grants access to an extensive array of libraries and unique capabilities not found in other frameworks or languages. Developers can benefit greatly from writing tests in the same language as their smart-contracts, streamlining the development process with faster iteration and more efficient bug resolution.

Being in Rust offers many benefits, though also presents challenges. Extensive boilerplate code is needed to ensure fail-safe and type-safe tests. Additionally, code written for unit tests in this framework is often not transferable to other environments, such as Test Tube or for use on live networks. This lack of reusability necessitates frequent code duplication and rewriting, which can lead to maintenance difficulties over time.

Finally, CosmWasm projects are unable to share their testing code with other teams, forcing integrators to write their own test suites that break each time the upstream protocol changes its contracts. This leads to broken integrations, lossy tests, and increased risk of hacks.

The Solution

CW-Orchestrator's framework allows for writing reusable code compatible with all CosmWasm environments, saving invaluable engineering time and enhancing maintainability. It simplifies interactions with CosmWasm contracts in Rust via macro-based code generation, enhancing readability and reducing the lines of code for writing tests significantly. Because this library is written in Rust, any breaking changes to your contract's interface will cause a compile-time error, enforcing safer code and up-to-date tests.

The framework encourages collaboration with well-defined standards for teams to publish their applications' test suites, allowing for easy integration and testability for consumers.

CW-Orchestrator also provides advanced testing capabilities offered by popular Ethereum testing frameworks such as clone [fork] testing and snapshot testing, which are currently in a pre-release stage.

Why?

CW-Orchestrator was built out of necessity to test the highly complex feature-set offered by the Abstract SDK, a modular CosmWasm smart-contract framework for the development of IBC-based interchain applications. There are tens of thousands of lines of test code written using cw-orchestrator in the Abstract SDK monorepo.

BUIDL 7773...

Abstract tooling is open source and is built on top of notable open-source projects to bring projects a standardized top of class developer experience and maximum integrability in their existing codebases. We choose our libraries very carefully to deliver a product that integrates seamlessly in open-source first projects.

Deep-Dive

Interface Generation

Read more about CW-Orchestrator interfaces here

Interacting with smart-contracts is often verbose with many lines of boilerplate code. Orchestrator solves this problem by providing a macro that generates an interface to a contract. This interface can be used to easily interact with a contract and improves the readability of your tests and deployments.

Parameterless entrypoint

Entrypoint with parameters.

Deployment + Scripting

Read a technical deep-dive here

cw-orchestrator provides the ability to interact with live networks, including mainnets, testnets, and local chain instances. It ships with a simple interface to blockchain nodes that can be used to submit transactions, query state and inspect transaction results. Any blockchain transaction can be broadcasted using cw-orchestrator.

Interacting with contracts is simple, with all entrypoints available on their interfaces (described above), and Orchestrator saves the contract addresses and CodeIds for each network you’re interacting with in a JSON formatted state file (docs). This allows for replicability and shareability as outlined in the standards section below.

Testing

To read more about cw-multi-test usage, read on here

To read more about test-tube usage, read on here.

The framework has abstractions for simple contract-to-contract interaction tests without having to deal with the overhead of running a node locally. All test environments include the ability to set and query balances, set block height/time and more.

Collaborative Standards

Read more about our collaborative standards here.

We strive to enable more collaboration between developer teams to build better, more innovative products. Projects using Orchestrator are fully compatible with one another, and we outline standards that allow for seamless deployment and integration of other projects such as the Abstract framework. The standards are inclusive of wasm files, on-chain addresses, and version management.

Clone Testing (Pre-release)

Further documentation and access here

Cw-orchestrator supports testing in a forked environment. With this feature, you can execute the application you are developing on a blockchain environment without having to spin up a node yourself and create a fork locally. All the code and application you will be running during the test will be rust code and the storage needed to execute is minimal as only the necessary data is downloaded from actual blockchain nodes.

Native IBC Testing (Pre-Release)

Read more about the IBC capabilities here

Because of its asynchronous nature, IBC makes developing and debugging applications more difficult than simple blockchain transactions. Orchestrator simplifies those tasks by providing developers tools, full testing environments and standard interfaces to interact with applications that leverage IBC capabilities.

Mocked IBC in cw-multi-test allows for testing IBC contract interactions in unit tests without use of Docker or needing to worry about packet relaying.

E2E Testing via Starship allows for testing complex interchain contract and chain interactions with local nodes just as developers would write any other test, with async execution and state introspection capabilities.

See a demo below!

Snapshot Testing (Alpha)

Example snapshots using Orchestrator can be found here.

Snapshot testing allows for all tests to write a "snapshot" of the contract state after the test run has completed. These are written to file and committable to version control, allowing teams to identify issues with state migration and management before they arise on a production environment. It is comparable to snapshot testing in Javascript with Jest.

CosmWasm CLI (Alpha)

Experiment with the CosmWasm CLI (cwi) here. We welcome all feedback!

Having to download, install, and setup a new CLI just to interact with contracts on a new chain sucks. As with testing environments, Orchestrator's CLI unifies all contract interactions with a simple-to-use interface that's both interactive and non-interactive, allowing its use live or in scripts.

It also includes helpers for common actions such as:

• Native & CW20 Asset transfers
• Updating cw-ownable ownership
• Address book for address aliases
• Private key management

CW-Orchestrator Architecture

Development with cw-orchestrator is very modular and extensible:

• You can import all the functionalities that you need such as contract types, mocked code, deploy scripts and wasm artifacts created by the projects that you are using.
• cw-orchestrator is transparent when developing your contracts. It doesn’t overload your wasms because no cw-orchestrator code finds its way into the compiled artifacts.
• During development, in the testing phase or in the deployment phase, Orchestrator however allows you to write robust type-safe tests and scripts. You usually write environment agnostic functions that can be executed on any platform - testing frameworks, actual blockchain node, interchain setup…
• Those testing and scripting libraries are in turn very simple to share with other developers for them to integrate with your code and deployed contracts frictionlessly.

Code Comparison

cw-orchestrator brings everything into the same Rust environments, be it testing/debugging/deploying/maintenance. Notice the simpler and reduced syntax as well as the reusability of the code:

Cw-orch

Cw-Multi-Test

CosmJs

Future Plans

Acknowledgement

We wish to give thanks to the open-source community and the many teams that we've worked with in improving CW-Orchestrator to make the development experience as amazing as possible, including (but not limited to):

• Confio
• FortyTwo
• Yieldmos
• DaoDao
• Cosmology