# How to Use CometMock for Testing Blockchain Networks with Starship

> Learn to test blockchain networks with Starship using CometMock. Configure your chain, deploy your testnet with starship up, and simplify RPC endpoint management for efficient testing.

- Repository: [Hyperweb/starship](https://github.com/hyperweb-io/starship)
- Tags: how-to-guide
- Published: 2026-03-03

---

**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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/starship/cmd/starship/model.go), the struct expects an `enabled` boolean and optional `image` string.

```yaml
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:

```bash
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`](https://github.com/hyperweb-io/starship/blob/main/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:

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

```

The CLI detects `chain.Cometmock.Enabled` in [`starship/cmd/starship/connect.go`](https://github.com/hyperweb-io/starship/blob/main/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.

```bash
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:

```yaml
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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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`](https://github.com/hyperweb-io/starship/blob/main/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:

```bash
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`.