Skip to content

docs: simplify and upgrade README #111

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
davd-gzl wants to merge 5 commits into
base: main
Choose a base branch
from
Open

docs: simplify and upgrade README #111

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0f018ea
docs: update README
davd-gzl Jan 21, 2026
8bb9b98
docs: simplify and upgrade README
davd-gzl Jan 21, 2026
3f5ab3b
docs: improve readability of project description in README
davd-gzl Jan 21, 2026
658efd2
lint: max 80 columns
davd-gzl Jan 21, 2026
7552aae
docs: port supernova sections from gno docs into README
davd-gzl May 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
187 changes: 132 additions & 55 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,82 +1,159 @@
## Overview

`supernova` is a command-line interface (CLI) tool for stress-testing Gno Tendermint 2 networks. It is used to monitor
and report on node performance by executing transactions and measuring response-time.
# Supernova

A stress-testing tool for Gno TM2 networks. Simulates realistic transaction
patterns and measures performance metrics like TPS and block utilization.
Use it to benchmark node performance by executing transactions under load
and analyzing response times.

## Table of Contents

- [Key Features](#key-features)
- [Why Stress Test Your Network?](#why-stress-test-your-network)
- [Quick Start](#quick-start)
- [CLI Flags](#cli-flags)
- [How Supernova Works](#how-supernova-works)
- [Testing Modes](#testing-modes)
- [Understanding Results](#understanding-results)
- [Integration with Monitoring](#integration-with-monitoring)
- [When to Use](#when-to-use)
- [Resources](#resources)

## Key Features

- 🚀 Batch transactions to make stress testing easier to orchestrate
- 🛠 Multiple stress testing modes: REALM_DEPLOYMENT, PACKAGE_DEPLOYMENT, and REALM_CALL
- 💰 Distributed transaction stress testing through subaccounts
- 💸 Automatic subaccount fund top-up
- 📊 Detailed statistics calculation
- 📈 Output cycle run results to a file

## Results
- Batch transactions for efficient stress testing
- Multiple modes: REALM_DEPLOYMENT, PACKAGE_DEPLOYMENT, REALM_CALL
- Distributed testing through subaccounts
- Automatic subaccount funding
- Detailed statistics and JSON output

To view the results of the stress tests, visit the [benchmarks reports for supernova](https://github.com/gnolang/benchmarks/tree/main/reports/supernova).

## Usage Example
![Banner](.github/demo.gif)

## Why Stress Test Your Network?

To run a stress test with `supernova`, you will need to have `go 1.19` or greater.
Stress testing answers critical questions before production deployment:

1. Build out the binary
| Question | Why It Matters |
|----------|----------------|
| What's my maximum TPS? | Know when performance degrades under load |
| How do gas limits affect throughput? | Optimize block parameters |
| Where are the bottlenecks? | Find issues in consensus, storage, or network |
| How do workloads differ? | Plan capacity for deployments vs calls |

To build out the binary, run the following command:
## Quick Start

Requires Go 1.19 or higher.

```bash
# Build
make build

# Run a stress test
./build/supernova \
-url http://localhost:26657 \
-chain-id dev \
-mnemonic "source bonus chronic canvas draft south burst lottery vacant surface solve popular case indicate oppose farm nothing bullet exhibit title speed wink action roast" \
-sub-accounts 5 \
-transactions 100 \
-mode REALM_CALL \
-output results.json
```

2. Run the stress test by specifying options
This runs a stress test against a Gno TM2 node at `http://localhost:26657`,
using `5` sub-accounts to send `100` transactions.
Results are saved to `results.json`.

```bash
./build/supernova -sub-accounts 5 -transactions 100 -url http://localhost:26657 -mnemonic "source bonus chronic canvas draft south burst lottery vacant surface solve popular case indicate oppose farm nothing bullet exhibit title speed wink action roast" -output result.json
```
For production-grade testing, increase `-sub-accounts` (50-100) and
`-transactions` (5000+).

This will run a stress test against a Gno TM2 node running at `http://localhost:26657`. The test will use `5`
sub-accounts, and send out `100` transactions. The sub-accounts are derived from the specified mnemonic. Finally,
results are saved
to a file `result.json`.
**Note**: This mnemonic derives the default development gnoland account, which is pre-funded in local environments (e.g., `gnodev`). For other environments, ensure the first address (index 0) has sufficient funds for distribution to subaccounts.

For any stress test run, there need to be funds on a specific address.
The address that is in charge of funds distribution to subaccounts is the **first address** with index 0 in the
specified mnemonic. Make sure this address has an appropriate amount of funds before running the stress test.
## CLI Flags

![Banner](.github/demo.gif)
| Flag | Default | Description |
|------|---------|-------------|
| `-url` | (required) | JSON-RPC URL of the Gno node |
| `-mnemonic` | (required) | Mnemonic for deriving accounts |
| `-sub-accounts` | 10 | Number of accounts sending transactions |
| `-transactions` | 100 | Total transactions to send |
| `-mode` | REALM_DEPLOYMENT | REALM_DEPLOYMENT, PACKAGE_DEPLOYMENT, or REALM_CALL |
| `-batch` | 100 | Batch size for JSON-RPC calls |
| `-chain-id` | dev | Chain ID of the network |
| `-output` | (none) | Path to save results JSON |

`supernova` supports the following options:
## How Supernova Works

```bash
USAGE
[flags] [<arg>...]

Starts the stress testing suite against a Gno TM2 cluster

FLAGS
-batch 100 the batch size of JSON-RPC transactions
-chain-id dev the chain ID of the Gno blockchain
-mnemonic string the mnemonic used to generate sub-accounts
-mode REALM_DEPLOYMENT the mode for the stress test. Possible modes: [REALM_DEPLOYMENT, PACKAGE_DEPLOYMENT, REALM_CALL]
-output string the output path for the results JSON
-sub-accounts 10 the number of sub-accounts that will send out transactions
-transactions 100 the total number of transactions to be emitted
-url string the JSON-RPC URL of the cluster
```
Supernova operates in three phases:

### 1. Account Setup

Supernova derives multiple subaccounts from a single mnemonic. This
simulates realistic conditions where transactions come from many different
addresses, testing the network's ability to handle concurrent account
state updates.

The tool automatically distributes funds from the main account (index 0)
to all subaccounts before the test begins.

### 2. Transaction Generation

Based on the selected mode, supernova constructs and signs transactions.
See [Testing Modes](#testing-modes) for details on each mode.

### 3. Result Collection

After broadcasting transactions, supernova monitors the blockchain to
collect metrics like TPS, block utilization, and gas consumption.

## Testing Modes

| Mode | What it Does | Best For |
|------|--------------|----------|
| REALM_DEPLOYMENT | Deploys a new realm per transaction | Testing heavy workloads (compilation, storage, state init) |
| PACKAGE_DEPLOYMENT | Deploys pure packages (stateless libraries) | Testing code storage overhead |
| REALM_CALL | Deploys one realm, then calls its methods | Simulating production workloads |

For most production scenarios, **REALM_CALL** provides the most relevant
metrics since it simulates typical user interactions.

## Understanding Results

### TPS (Transactions Per Second)

Reflects real-world throughput, accounting for transaction propagation, block
production intervals, and consensus overhead.

### Block Utilization

| Utilization | Meaning |
|-------------|---------|
| Low (<50%) | Network has spare capacity |
| High (>80%) | Near capacity, consider increasing gas limits |
| Variable | Inconsistent batching or congestion patterns |

## Modes
## Integration with Monitoring

### REALM_DEPLOYMENT
For deeper insights, run supernova against a node with
[OpenTelemetry enabled](https://github.com/gnolang/gno/tree/master/misc/telemetry).
This allows you to correlate supernova's transaction metrics with internal
node metrics like:

The `REALM_DEPLOYMENT` mode is pretty straightforward - it is a simple `Realm` deployment mode from accounts.
This mode sends out transactions that are deploy transactions for a realm holding state.
- Memory and CPU usage during load
- Consensus round timing
- Storage I/O patterns
- Network message latency

### PACKAGE_DEPLOYMENT
## When to Use

The `PACKAGE_DEPLOYMENT` is similar to `REALM_DEPLOYMENT`. This mode also sends out transactions, but these transactions
deploy a package.
| Scenario | Purpose |
|----------|---------|
| Pre-production | Validate network handles expected load |
| Post-config changes | Verify gas limits and timing parameters |
| Capacity planning | Determine hardware for target TPS |
| Benchmarking | Compare node configurations |

### REALM_CALL
## Resources

The `REALM_CALL` mode deploys a `Realm` to the Gno blockchain network being tested before starting the cycle run.
When the cycle run begins, the transactions that are sent out are method calls.
- [Benchmark reports](https://github.com/gnolang/benchmarks/tree/main/reports/supernova)
- [Gno.land documentation](https://docs.gno.land)