Generate TypeScript SDKs for your CosmWasm smart contracts

npm install @cosmwasm/ts-codegen

The quickest and easiest way to interact with CosmWasm Contracts. @cosmwasm/ts-codegen converts your CosmWasm smart contracts into dev-friendly TypeScript classes so you can focus on shipping code.

🎥 Checkout our video playlist to learn how to use ts-codegen!

• @cosmwasm/ts-codegen
  • Table of contents
• Usage
  • Programmatic Usage
  • Types
  • TS Clients
  • React Query
  • Recoil
  • Message Composer
  • Message Builder
  • Use Contracts Hook
  • Bundles
  • CLI Usage and Examples
  • Advanced Usage
• JSON Schema
  • JSON Schema Generation
  • Exporting Schemas
• Developing
• Related

For production usage, we recommend setting up a build script that uses the main entry point:

import codegen from '@cosmwasm/ts-codegen';

codegen({
  contracts: [
    {
      name: 'SG721',
      dir: './path/to/sg721/schema'
    },
    {
      name: 'Minter',
      dir: './path/to/Minter/schema'
    }
  ],
  outPath: './path/to/code/src/',

  // options are completely optional ;)
  options: {
    bundle: {
      bundleFile: 'index.ts',
      scope: 'contracts'
    },
    types: {
      enabled: true
    },
    client: {
      enabled: true
    },
    reactQuery: {
      enabled: true,
      optionalClient: true,
      version: 'v4',
      mutations: true,
      queryKeys: true,
      queryFactory: true,
    },
    recoil: {
      enabled: false
    },
    messageComposer: {
      enabled: false
    },
    messageBuilder: {
      enabled: false
    },
    useContractsHook: {
      enabled: false
    }
  }
}).then(() => {
  console.log('✨ all done!');
});

Typescript types and interfaces are generated in separate files so they can be imported into various generated plugins.

see example output code

The client plugin will generate TS client classes for your contracts. This option generates a QueryClient for queries as well as a Client for queries and mutations.

see example output code

Generate react-query v3 or react-query v4 bindings for your contracts with the react-query command.

see example output code

Generate recoil bindings for your contracts with the recoil command.

see example output code

Generate pure message objects with the proper utf8 encoding and typeUrl configured that you can broadcast yourself via cosmjs with the message-composer command.

see example output code

Generate raw message jsons for use in your application with the message-builder command.

see example output code

Generates useContracts hook to easily access contracts, already equipped with a signing client

• Provider
• Contract Providers
• Contract Context
• Context Base

import { useChain } from '@cosmos-kit/react';
import { ContractsProvider } from '../path/to/codegen/contracts-context';

export default function YourComponent() {

  const {
    address,
    getCosmWasmClient,
    getSigningCosmWasmClient
  } = useChain(chainName);

  return (
    <ContractsProvider
      contractsConfig={{
        address,
        getCosmWasmClient,
        getSigningCosmWasmClient,
      }}
    >
        <SomeCoolComponent />
    </ContractsProvider>
  )
};

If you're using Babel, please make sure include '@babel/preset-react' in devDeps and presets in .babelrc.js:

 presets: [
   '@babel/typescript',
   '@babel/env',
   '@babel/preset-react',
 ]

For tsc, you should set the jsx option to 'react' in your tsconfig.json.

Once enabled, you can get contracts very simply:

const { marketplace } = useContracts();

const marketplaceClient = marketplace.signingClient(marketplaceContract);
await marketplaceClient.updateAskPrice({
  collection: token.collectionAddr,
  price: {
    amount,
    denom,
  },
  tokenId,
});

The bundler will make a nice package of all your contracts. For example:

const {
  MinterQueryClient,
  useMinterConfigQuery
} = contracts.Minter;

const { CwAdminFactoryClient } = contracts.CwAdminFactory;

Using shorthand constructor (Might not be transpiled correctly with babel):

  constructor(
    protected address: string | undefined,
    protected cosmWasmClient: CosmWasmClient | undefined,
    protected signingCosmWasmClient: SigningCosmWasmClient | undefined,
    private TSign?: new (
      client: SigningCosmWasmClient,
      sender: string,
      contractAddress: string
    ) => TSign,
    private TQuery?: new (
      client: CosmWasmClient,
      contractAddress: string
    ) => TQuery,
    private TMsgComposer?: new (
      sender: string,
      contractAddress: string
    ) => TMsgComposer
  ) {}

Without using shorthand constructor:

  address: string | undefined;
  ...
  TMsgComposer?: new (
    sender: string,
    contractAddress: string
  ) => TMsgComposer;

  constructor(
    address: string | undefined,
    ...
    TMsgComposer?: new (
      sender: string,
      contractAddress: string
    ) => TMsgComposer
  ) {
    this.address = address;
    ...
    this.TMsgComposer = TMsgComposer;
  }

You can get started quickly using our cli by globally installing via npm:

npm install @cosmwasm/ts-codegen

Clone your project and cd into your contracts folder

git clone https://github.com/cosmology-tech/launchpad.git
cd launchpad/contracts/whitelists/whitelist

Run ts-codegen or cosmwasm-ts-codegen to generate your code.

ts-codegen generate \
          --plugin client \
          --schema ./schema \
          --out ./ts \
          --name Whitelist \
          --no-bundle

The output will be in the folder specified by --out, enjoy!

The CLI is interactive, and if you don't specify an option, it will interactively prompt you.

cosmwasm-ts-codegen generate
? [plugin] which plugins? (Press <space> to select, <a> to toggle all, <i> to invert selection)
❯◯ client
 ◯ recoil
 ◯ react-query
 ◯ message-composer

In this example, you can press space bar to select a number of plugins you wish you enable.

Additionally, it will also show you the name of the field (in this case plugin) so you can specify the parameter (for example when using CI/CD) on the comand line. Here is an exampl with --plugin set to client via CLI:

ts-codegen generate \
    --plugin client
    --schema ./schema \
    --out ./ts \
    --name MyContractName

You can specify multiple --plugin options using the generate command:

ts-codegen generate \
          --plugin client \
          --plugin recoil \
          --schema ./schema \
          --out ./ts \
          --name SG721

All options can be provided so you can bypass the prompt.

For confirm options, you can pass --no-<name> to set the value to false. Here is an example without optional client, using v3 for react-query, without mutations:

ts-codegen generate \
    --plugin client \
    --plugin react-query \
    --schema ./schema \
    --out ./ts \
    --name MyContractName \
    --version v3 \
    --no-optionalClient \
    --no-mutations

Example with optional client, using v4, with mutations:

ts-codegen generate \
    --plugin react-query \
    --schema ./schema \
    --out ./ts \
    --name MyContractName \
    --optionalClient \
    --version v4 \
    --mutations

If needed, you can generate only the types with the typesOnly option;

ts-codegen generate \
          --typesOnly \
          --schema ./schema \
          --out ./ts \
          --name SG721

ts-codegen generate \
    --plugin client
    --schema ./schema \
    --out ./ts \
    --name MyContractName

Here is an example without optional client, using v3 for react-query, without mutations:

ts-codegen generate \
    --plugin client \
    --plugin react-query \
    --schema ./schema \
    --out ./ts \
    --name MyContractName \
    --version v3 \
    --no-optionalClient \
    --no-mutations

Example with optional client, using v4, with mutations:

ts-codegen generate \
    --plugin react-query \
    --schema ./schema \
    --out ./ts \
    --name MyContractName \
    --optionalClient \
    --version v4 \
    --mutations

ts-codegen generate \
    --plugin recoil \
    --schema ./schema \
    --out ./ts \
    --name MyContractName

ts-codegen generate \
    --plugin message-composer \
    --schema ./schema \
    --out ./ts \
    --name MyContractName

ts-codegen generate \
    --plugin message-builder \
    --schema ./schema \
    --out ./ts \
    --name MyContractName

We generate code from the JSON Schema exported from CosmWasm smart contracts.

Currently you have to have the JSON Schema output. Here is an example to start.

First, get the Rust contracts and run cargo build:

git clone git@github.com:public-awesome/stargaze-contracts.git
cd stargaze-contracts
cargo build

now build the schema with cargo schema

cd contracts/sg721/
cargo schema

Using the new write_api method, you can export schemas:

use cosmwasm_schema::write_api;

use cw4_group::msg::{ExecuteMsg, InstantiateMsg, QueryMsg};

fn main() {
    write_api! {
        instantiate: InstantiateMsg,
        execute: ExecuteMsg,
        query: QueryMsg,
    }
}

Here is a legacy example:

use cosmwasm_std::{Addr, CosmosMsg, Empty};

export_schema_with_title(&schema_for!(MinterData), &out_dir, "MinterResponse");
export_schema_with_title(&schema_for!(Addr), &out_dir, "StakingResponse");
export_schema_with_title(&schema_for!(Addr), &out_dir, "DaoResponse");
export_schema_with_title(
      &schema_for!(CosmosMsg<Empty>),
      &out_dir,
      "CosmosMsg_for_Empty",
);

yarn
yarn bootstrap

yarn build

Then cd into a package and run the tests

cd ./packages/ast
yarn test:watch

See the docs in the @cosmwasm/ts-codegen-ast package.

Checkout these related projects:

• @cosmology/telescope Your Frontend Companion for Building with TypeScript with Cosmos SDK Modules.
• @cosmwasm/ts-codegen Convert your CosmWasm smart contracts into dev-friendly TypeScript classes.
• chain-registry Everything from token symbols, logos, and IBC denominations for all assets you want to support in your application.
• cosmos-kit Experience the convenience of connecting with a variety of web3 wallets through a single, streamlined interface.
• create-cosmos-app Set up a modern Cosmos app by running one command.
• interchain-ui The Interchain Design System, empowering developers with a flexible, easy-to-use UI kit.
• starship Unified Testing and Development for the Interchain.

🛠 Built by Cosmology — if you like our tools, please consider delegating to our validator ⚛️

AS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED “AS IS”, AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.

No developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.