Getting Started

Overview

starskiff spawns real Cosmos SDK nodes as child processes for integration tests — no Kubernetes, just the chain's node from a binary or a container image. An instance boots in seconds: init → genesis patching → account funding → gentx → start → health-polled until the first block.

Installation

Prerequisites

Most instances run from an image, so a running Docker is all you need — simd, wasmd, gaiad, xplad, and evmd pull their image on first use.

The exceptions: the hermes relayer runs as a host binary (put it on PATH, e.g. from an official release), and marood has no default image — inject a source yourself, either an image or a binary on PATH.

Any instance also accepts a binary or image override — the escape hatch for local development. See the instance pages for the full list, and the CI guide for provisioning binaries on CI runners.

Quick Start

import { Instance, testAccounts } from 'starskiff';
 
const [alice] = testAccounts;
 
const instance = Instance.simd({
  chainId: 'test-1',
  accounts: [{ mnemonic: alice.mnemonic, coins: '1000000000stake', name: alice.name }],
});
 
await instance.start();
 
// Ready-to-use endpoint URLs:
instance.rpcUrl; //  http://localhost:26657 — CometBFT RPC
instance.grpcUrl; // http://localhost:9090  — gRPC
instance.apiUrl; //  http://localhost:1317  — REST (Cosmos SDK API)
 
await instance.stop();

start() resolves once the node reports its first block (and, for EVM chains, once the JSON-RPC server responds). stop() kills the process and removes the temporary home directory — every run starts from a fresh genesis.

Using with cosmjs

import { SigningStargateClient, GasPrice } from '@cosmjs/stargate';
import { DirectSecp256k1HdWallet } from '@cosmjs/proto-signing';
 
const wallet = await DirectSecp256k1HdWallet.fromMnemonic(alice.mnemonic, { prefix: 'cosmos' });
 
const client = await SigningStargateClient.connectWithSigner(instance.rpcUrl, wallet, {
  gasPrice: GasPrice.fromString('0stake'),
});

For wiring instances into your test runner, see the vitest guide; for EVM JSON-RPC testing, see the evmd instance.