How to Use CometMock for Testing Blockchain Networks with Starship

To use CometMock for testing blockchain networks with Starship, add a cometmock block with enabled: true to your chain configuration YAML, deploy the testnet using starship up, and the CLI automatically handles port-forwarding to the mock's RPC endpoint on port 22331 instead of the standard Tendermint port.

Starship, developed by hyperweb-io, is a Kubernetes-based tool for spinning up full-node testnets for Cosmos SDK chains. When you need a lightweight alternative to the full Tendermint/CometBFT consensus engine for fast CI pipelines or local development, enabling CometMock for testing blockchain networks with Starship replaces the heavy binary with a mock implementation that maintains API compatibility while significantly reducing resource overhead.

Architecture Overview

Starship implements CometMock support through four key components defined in the source code:

• Configuration Structure: The Chain.Cometmock struct in starship/cmd/starship/model.go defines the enabled, image, and port override fields that Helm consumes during deployment.
• Helm Templates: The file starship/charts/devnet/templates/chains/cosmos/cometmock.yaml creates a Service and StatefulSet that deploys the cometmock container and copies the binary from the chain image via an init container.
• Port Management: Logic in starship/cmd/starship/connect.go detects chain.Cometmock.Enabled and automatically rewires port-forwarding from your local port to the mock's internal port 22331.
• Reference Configuration: The example file starship/tests/e2e/configs/two-chain-cometmock.yaml demonstrates a working multi-chain setup with CometMock enabled for integration testing.

Step-by-Step Configuration

Enable CometMock in Your Helm Values

Add the cometmock block to your chain definition in your Starship configuration YAML. According to starship/cmd/starship/model.go, the struct expects an enabled boolean and optional image string.

chains:
  - id: osmosis-1
    name: osmosis
    numValidators: 2
    cometmock:
      enabled: true
      image: ghcr.io/informalsystems/cometmock:v0.37.x  # optional

    ports:
      rpc: 26653
      exposer: 38083

If you omit the image field, Starship defaults to ghcr.io/informalsystems/cometmock:v0.37.x as defined in the Helm chart values.

Deploy the Testnet

Execute the deployment command from your working directory:

starship up -f starship/tests/e2e/configs/two-chain-cometmock.yaml

During deployment, Starship generates Helm values that include your cometmock configuration. The template starship/charts/devnet/templates/chains/cosmos/cometmock.yaml renders a StatefulSet named <chain-name>-cometmock and runs an init container that executes cp /usr/local/bin/cometmock /chain/cometmock to place the binary in a shared volume.

Port-Forward to the Mock RPC

Run the port-forward command to establish local access:

starship port-forward -f starship/tests/e2e/configs/two-chain-cometmock.yaml

The CLI detects chain.Cometmock.Enabled in starship/cmd/starship/connect.go (lines 70-78) and automatically adjusts the forwarding logic. Instead of connecting to the standard Tendermint RPC port, it forwards your local port (e.g., 26653) to port 22331 on the cometmock pod.

You will see output similar to:

port-forwarding: osmosis-1: cometmock-rpc: to: http://localhost:26653

Query the Blockchain via CometMock

With port-forwarding active, interact with the mock using any Tendermint-compatible client. The mock responds with JSON that matches the standard Tendermint RPC schema.

curl http://localhost:26653/status

Advanced Configuration Options

Using a Custom CometMock Image

For specialized testing scenarios requiring debug flags or patched binaries, specify a custom image in your configuration:

cometmock:
  enabled: true
  image: myregistry.com/custom-cometmock:latest

Starship pulls this image for the init-comet container defined in starship/charts/devnet/templates/chains/cosmos/cometmock.yaml and uses the binary located at /usr/local/bin/cometmock inside that image.

Summary

• Enable CometMock by adding a cometmock block with enabled: true to your chain configuration in Starship.
• Port 22331 is the hardcoded internal port that CometMock uses, which starship/cmd/starship/connect.go automatically targets when the feature is enabled.
• Default image is ghcr.io/informalsystems/cometmock:v0.37.x unless overridden in your YAML.
• Deployment creates a separate StatefulSet via starship/charts/devnet/templates/chains/cosmos/cometmock.yaml, copying the binary through an init container before starting the mock process.
• Port-forwarding automatically adjusts to route traffic to the mock instead of standard Tendermint when Cometmock.Enabled is true.

Frequently Asked Questions

What port does CometMock use in Starship?

CometMock always listens on container port 22331 inside the Kubernetes pod. When you enable the feature, the Starship CLI code in starship/cmd/starship/connect.go automatically detects this setting and forwards your local rpc port to the pod's port 22331 instead of the standard Tendermint RPC port (typically 26657).

Can I use CometMock with multiple validators?

Yes. Set numValidators to your desired count in the chain configuration. The init scripts in the Helm template starship/charts/devnet/templates/chains/cosmos/cometmock.yaml handle validator key duplication automatically before starting the cometmock process. No additional configuration is required for multi-validator setups.

How do I view logs for the CometMock container?

Because the mock runs as a separate pod named <chain-name>-cometmock-0, you can inspect its output using standard Kubernetes commands:

kubectl logs osmosis-1-cometmock-0 -f

This is useful for debugging block production or RPC request handling when using CometMock for testing blockchain networks with Starship.

What happens if I don't specify a CometMock image?

If you omit the image field from the cometmock configuration block, Starship uses the default value ghcr.io/informalsystems/cometmock:v0.37.x as defined in the Helm chart values. The system pulls this image during the init-container phase and copies the binary to the shared chain volume at /chain/cometmock.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}