cosmock

Warning

This project is under active development. APIs may change without notice until v1.0.

HTTP testing instances for Cosmos.

Lightweight alternative to Starship — run real Cosmos SDK chain nodes as child processes without Docker or Kubernetes.

Inspired by prool (HTTP testing instances for Ethereum).

Features

• Spawn real Cosmos SDK nodes as child processes
• No Docker, no Kubernetes — just a Go binary
• Genesis account injection with mnemonic recovery
• Full lifecycle management (start/stop/restart)
• Compatible with @cosmjs/stargate and @cosmjs/cosmwasm-stargate for testing
• Extensible to any Cosmos SDK chain binary via cosmosBase

Instances

Instance	Binary	Modules	Use case
Instance.simd()	simd	bank, staking, gov, mint	Basic Cosmos SDK testing
Instance.wasmd()	wasmd	bank, staking, gov, mint, IBC, CosmWasm	Contract deploy/execute, IBC

Install

pnpm add -D cosmock

Prerequisites

Install the binary for the instance you need. Requires Go >= 1.25.

simd (Cosmos SDK simapp):

git clone --depth 1 https://github.com/cosmos/cosmos-sdk.git /tmp/cosmos-sdk
cd /tmp/cosmos-sdk/simapp && go build -o ~/go/bin/simd ./simd/

wasmd (CosmWasm — includes IBC):

git clone --depth 1 https://github.com/CosmWasm/wasmd.git /tmp/wasmd
cd /tmp/wasmd && go build -o ~/go/bin/wasmd ./cmd/wasmd/

Prebuilt binaries (CI)

Prebuilt linux/amd64 binaries are available in GitHub Releases for CI environments:

# Download and install (e.g. in GitHub Actions)
gh release download "binaries/latest" --repo 2wheeh/cosmock --pattern "*.gz" --dir /tmp
gunzip -c /tmp/simd-linux-amd64.gz > /usr/local/bin/simd
gunzip -c /tmp/wasmd-linux-amd64.gz > /usr/local/bin/wasmd
chmod +x /usr/local/bin/simd /usr/local/bin/wasmd

For local development on macOS/Windows, build from source using the instructions above.

Usage

Basic (simd)

import { Instance } from 'cosmock';

const instance = Instance.simd({
  chainId: 'test-1',
  denom: 'stake',
  accounts: [
    {
      mnemonic: 'abandon abandon abandon ...',
      coins: '1000000000stake',
      name: 'alice',
    },
  ],
});

await instance.start();

// Connect with cosmjs
import { StargateClient } from '@cosmjs/stargate';
const client = await StargateClient.connect(`http://localhost:${instance.port}`);
const balance = await client.getBalance(address, 'stake');

await instance.stop();

CosmWasm (wasmd)

import { Instance } from 'cosmock';
import { SigningCosmWasmClient } from '@cosmjs/cosmwasm-stargate';
import { GasPrice } from '@cosmjs/stargate';

const instance = Instance.wasmd({
  chainId: 'wasm-test-1',
  accounts: [{ mnemonic: '...', coins: '1000000000stake', name: 'alice' }],
});
await instance.start();

const client = await SigningCosmWasmClient.connectWithSigner(`http://localhost:${instance.port}`, wallet, {
  gasPrice: GasPrice.fromString('0stake'),
});

// Upload, instantiate, execute
const { codeId } = await client.upload(address, wasmBytecode, 'auto');
const { contractAddress } = await client.instantiate(address, codeId, initMsg, 'label', 'auto');
const result = await client.execute(address, contractAddress, executeMsg, 'auto');

vitest globalSetup (provide/inject)

// test/global-setup.ts
import type { TestProject } from 'vitest/node';
import { Instance } from 'cosmock';

export default async function setup({ provide }: TestProject) {
  const instance = Instance.wasmd({
    chainId: 'test-1',
    accounts: [{ mnemonic: '...', coins: '1000000000stake' }],
  });
  await instance.start();

  provide('rpcUrl', `http://localhost:${instance.port}`);

  return () => instance.stop();
}

declare module 'vitest' {
  export interface ProvidedContext {
    rpcUrl: string;
  }
}

// vitest.config.ts
export default defineConfig({
  test: {
    globalSetup: './test/global-setup.ts',
  },
});

// test/bank.test.ts
import { inject } from 'vitest';

const rpcUrl = inject('rpcUrl');

it('queries balance', async () => {
  const client = await StargateClient.connect(rpcUrl);
  const balance = await client.getBalance(address, 'stake');
  // ...
});

Multi-chain

const chain1 = Instance.wasmd({
  chainId: 'wasm-1',
  rpcPort: 26657,
  grpcPort: 9090,
  apiPort: 1317,
  p2pPort: 26656,
});

const chain2 = Instance.wasmd({
  chainId: 'wasm-2',
  rpcPort: 26660,
  grpcPort: 9092,
  apiPort: 1318,
  p2pPort: 26661,
});

await Promise.all([chain1.start(), chain2.start()]);

Custom chain binary

import { Instance, cosmosBase } from 'cosmock';

// Any Cosmos SDK binary works — same init/genesis/start flow
const gaiad = Instance.define(params => cosmosBase({ binary: 'gaiad', name: 'gaiad', ...params }));

API

Instance.simd(parameters?, options?)

Creates a simd (Cosmos SDK simapp) instance.

Instance.wasmd(parameters?, options?)

Creates a wasmd (CosmWasm + IBC) instance. Same parameters as simd.

Parameters

Shared by all instances (CosmosChainParameters):

Parameter	Type	Default	Description
binary	string	instance-specific	Path to binary
chainId	string	"cosmock-1"	Chain ID
denom	string	"stake"	Default denom
accounts	CosmosAccount[]	[]	Genesis accounts
minimumGasPrices	string	"0{denom}"	Minimum gas prices
rpcPort	number	26657	CometBFT RPC port
grpcPort	number	9090	gRPC port
apiPort	number	1317	REST API port
p2pPort	number	26656	P2P port
grpcWebPort	number	9091	gRPC-Web port
pprofPort	number	6060	pprof port

Instance options (second argument)

Option	Type	Default	Description
messageBuffer	number	20	Max messages to store in-memory
timeout	number	60000	Start/stop timeout in milliseconds

const instance = Instance.wasmd({ chainId: 'test-1' }, { timeout: 30_000 });

Instance methods

Method	Description
start()	Start the instance. Returns a stop function.
stop()	Stop the instance and cleanup temp directory.
restart()	Stop then start.
on(event, handler)	Listen to events (message, stdout, stderr, listening, exit).
off(event, handler)	Remove event listener.

Instance properties

Property	Type	Description
status	string	idle / starting / started / stopping / stopped / restarting
host	string	Host (default: localhost)
port	number	RPC port
name	string	Instance name
messages	object	.get() returns buffered messages, .clear() clears them

Testing strategies

Strategy	Isolation	Speed	Use case
Account isolation	Practical	Fast	Most tests — each test uses unique accounts
Suite-level instance	Full	~5s setup	Tests that modify chain-wide state
Shared instance	None	Fastest	Read-only queries, smoke tests

Recommended: fund multiple accounts in genesis, assign each test its own account(s).

Why not Starship?

	Starship	cosmock
Infra	Kubernetes + Helm + Docker	None (child process)
Startup	2-5 min	3-5 sec
Dependencies	K8s cluster	Go binary
State reset	Helm redeploy (minutes)	kill + restart (~3s)
Best for	Production simulation	Dev/test

TODO

• cosmosEvmBase — EVM JSON-RPC port support for EVM-enabled chains (e.g. xpla, evmos)
• cosmock.config.ts — config-based chain + relayer declaration
• cosmock/vitest — vitest plugin (automatic setup/teardown via vitestPlugin(config))
• cosmock/playwright — playwright plugin (playwrightPlugin(config))
• Automatic port allocation (avoid port conflicts in parallel tests)
• findFreePorts() utility for direct Instance users
• cosmock/setup-binaries GitHub Action for CI binary setup

License

MIT