Introduction to CosmWasm JS — for users, contributors and forkers
CosmWasm JS is an SDK for building client-side applications that connect to Cosmos SDK based blockchains with CosmWasm enabled, such as wasmd. In this context, client-side means anything that connects to a blockchain node, e.g. wallets, faucets, block explorers or scrapers. The “JS” in the name stands for running everywhere, and in fact the SDK is written in TypeScript, giving you all the type safety when using it and giving us the confidence not to introduce unnecessary bugs.
The codebase is inherited by and highly compatible to IOV Core. On the one hand there is a personal history between me and IOV Core making me confident this is a solid foundation to build upon. On the other hand people like the codebase it received an external security audit late 2019. CosmWasm JS uses lower level primitives like @iov/encoding or @iov/crypto directly to get all the hex/base64/bech32/ed25519/secp256k1/BIP39/SLIP10 stuff for free. Additionally it ships with an implementation of IOV’s Blockchain Communication Protocol available in CosmWasm JS, allowing you to easily integrate into the Neuma wallet and browser extension.
CosmWasm JS is a monorepo with multiple npm packages, that build on top of each other:
@cosmwasm/sdk
The low level connector to the REST API. Includes helpers for signing, a raw RestClient and a higher level CosmWasmClient. It allows you to upload, instantiate and call smart contracts. It can also be used as a generic Cosmos SDK 0.38 client with support for reading and writing arbitrary messages.
@cosmwas/cli
A Node.js powered REPL for using the @cosmwasm/sdk. This is primarily for testing and showcasing small code snippets. See this guide or this video to get familiar with the CLI.
@cosmwasm/bcp
An implementation of the Blockchain Communication Protocol, a unified interface to connect to multiple blockchains. With this implementation your CosmWasm chain can easily be integrated into multi-chain products that utilize BCP, like Neuma. Using this package is entirely optional.
@cosmwasm/faucet
A faucet application for your Cosmos SDK chain. Provide an URL to your REST API and a mnemonic with many testnet funds and your users can easily get tokens using a HTTP client like cURL.
Get your hands dirty
If you are waiting for the code examples, I need to disappoint you. Those will be outdated already before the article is published. But here are some basic starting points:
For users
To use the SDK for uploading, instantiating and executing smart contracts, see how we deploy ERC20 contracts to a local wasmd. The faucet is can be run on a server to give people access to your testnet tokens.
For contributors
Found a bug, design can be improved, a feature is missing or you need more flexibility to use the SDK for you chain? Contributions are highly welcome! If you are familiar with Lerna, Yarn and TypeScript, jump right into the code. Otherwise or if you’re a bit shy, open an issue to start the discussion. We are happy to learn about use cases and challenges.
For forkers
Cosmos is all about customization and we don’t think the original CosmWasm JS can work out of the box for every use case. So feel free to fork what is there and adapt it to your needs — it is Apache licensed. However, we encourage you to fork wisely. Much of the existing functionality can easily be generalized to allow for more use cases. And maybe we can continue to work together on one package upstream while you use custom versions of other packages. The modular design of the monorepo makes that possible. Let’s talk on Github or Telegram about your use case.
Kudos go to Ethan who is pushing hard to great client-side developer experience.
Building this software stack in just one month with 1½ developers would not have been possible without the help of IOV’s open source software stack — thank you! Make sure to contribute back upstream when working with CosmWasm JS.
