GnoSwap Performance Tracker

A tool for measuring and comparing Gas usage, Storage Diff, and CPU Cycles of GnoSwap smart contracts.

📊 View Latest Performance Summary →

Installation

# Initialize submodules and install gno
make init
# View available commands
make

Benchmarks now run in isolated git worktrees under .worktrees/. The shared gnoswap/ and gno/ submodules are used as seed repositories and are no longer checked out in place during report generation.

Metric and stress runs build and execute gno only from their temporary GNO_WORKTREE. The binary, its native registry, and GNOROOT therefore always come from the same pinned Gno revision. Do not manually checkout gno/ before running a benchmark.

Usage

The tool provides simplified commands for generating and comparing reports.

There are now three lanes in the tracker:

• tests/metric for canonical gno test metric benchmarks
• tests/stress for canonical gno test stress benchmarks
• research/ for isolated live-chain runtime and exploratory measurements

The report layer is shared, but the runtime layer is intentionally separated.

1. Basic Commands

Command	Description	Existing Reports
make metric	Generate metric reports	Skip (Reuse)
make metric-force	Generate metric reports	Force Regenerate
make stress	Generate stress reports	Skip (Reuse)
make stress-force	Generate stress reports	Force Regenerate
make compare-metric	Compare metric reports	Skip (Reuse)
make compare-metric-force	Compare metric reports	Force Regenerate
make compare-stress	Compare stress reports	Skip (Reuse)
make compare-stress-force	Compare stress reports	Force Regenerate
make research-up	Start research runtime	N/A
make research-down	Stop research runtime scaffold	N/A
make research-test	Run research smoke harness	N/A
make research-report <ref>	Run integrated deploy + probes + report	N/A
make compare-research <refs>	Compare research reports	N/A
make clean-worktrees	Remove cached benchmark worktrees	N/A

2. Examples

Single Commit Report

Generate a report for a specific commit without comparison.

# Standard Metric (skip if exists)
make metric abc1234

# Force regenerate
make metric-force abc1234

# Stress Test
make stress abc1234

Compare Two Commits

Generate reports (if needed) and compare two commits.

# Compare metric reports: commit1 -> commit2 (skip existing)
make compare-metric abc1234 def5678

# Force regenerate all metric comparisons

make compare-metric-force abc1234 def5678

# Compare stress reports
make compare-stress abc1234 def5678

Each <ref> may be a commit hash, local ref, or origin/<branch> ref. The tracker resolves it to a commit before deriving report filenames, so branch names such as fix/launchpad-refund-liability are valid inputs. When an unqualified branch name exists both locally and on origin, metric and stress commands use the fetched origin branch instead of a stale local branch. Tags, explicit refs, commit expressions, and local-only branches retain their normal Git resolution; use refs/heads/main to request local main.

Compare Multiple Commits

Generate reports and compare multiple commits in sequence. (commit1 → commit2, commit2 → commit3, and commit1 → commit3)

# Skip existing reports and comparisons
make compare-metric abc1234 def5678 ghi9012

# Force regenerate everything
make compare-metric-force abc1234 def5678 ghi9012

3. Generate Summary Report

Track performance changes across multiple commits defined in commit-history.txt.

# Generate summary (skip existing reports and comparisons)
make summary

# Force regenerate all reports, comparisons, and summary
make summary-force

4. Research Lane

The research lane is an integrated live-chain runtime namespace under research/.

make research-up
make research-test
GNO_RPC_PORT=46657 GNO_REST_PORT=48888 make research-report 3f2642b8898ae02d14a14c4050d80919f18f3f21
make compare-research main develop
make research-down

This lane does not participate in the default summary flow yet.

make research-report <ref> is the one-shot path: it boots the local chain on the explicit RPC/REST ports you assign, deploys contracts inside the container, executes the probes, and emits normalized markdown through the shared compare pipeline. The <ref> argument is resolved to a full commit, normalized tracker reports are saved as {short_hash}.md, and raw artifacts/runlogs keep <resolved-short-hash>-<utc-timestamp> stems so concurrent runs do not overwrite each other.

The default research milestones are 1,10,100. Override them per run when you want a smaller or denser checkpoint set.

Milestone summaries are cumulative. For example, N=10 reflects samples 1..10, while N=100 reflects samples 1..100.

There is no hidden warm-up pass in the research probes. N=1 represents the first measured execution.

GNO_RPC_PORT=46657 GNO_REST_PORT=48888 WORKLOAD_NS=1,10,100 make research-report 3f2642b8898ae02d14a14c4050d80919f18f3f21
GNO_RPC_PORT=47657 GNO_REST_PORT=49888 WORKLOAD_NS=1,10,100 make research-report main

5. Output Locations

• Metric Reports:
  • Individual: reports/metric/commits/{commit_hash}.md
  • Comparison: reports/metric/compares/diff_{new}_{old}.md
• Stress Reports:
  • Individual: reports/stress/commits/{commit_hash}.md
  • Comparison: reports/stress/compares/diff_{new}_{old}.md
• Research Reports:
• Individual: reports/research/commits/{short_hash}.md
• Comparison: reports/research/compares/diff_{new_short_hash}_{old_short_hash}.md
• Summary Report: SUMMARY.md

Raw research artifacts stay under research/artifacts/ and research/.runlogs/, with matching {short_hash}-{timestamp} stems per run.

6. Benchmark Workspace Behavior

• gnoswap/ stays as the source repository for commit resolution.
• Each benchmark resolves the requested ref to a full commit and reuses a cached detached gnoswap worktree under .worktrees/gnoswap/{full_commit}.
• Each run also creates a temporary isolated gno worktree under .worktrees/runs/ so copied scenario files and linked contracts do not mutate the shared gno/ checkout.
• Temporary run worktrees are removed automatically after each benchmark.
• To remove cached worktrees manually, run:

make clean-worktrees

7. Metric-enabled Gno Runtime

The committed gno gitlink is the metric runtime pin. To benchmark a different upstream gnolang/gno revision, prepare a dedicated gas-<sha> branch rather than checking out the shared seed repository:

make prepare-gno-gas <upstream-gno-ref>
git add .gitmodules gno
git commit -m "chore: pin metric-enabled gno runtime"

prepare-gno-gas applies the tracker metric patches, verifies the resulting branch, and updates the pin. Normal make metric, make stress, and comparison commands then build and run the isolated pinned runtime automatically.

The current runtime is based on gnolang/gno tag chain/mainnet at 9c8eb132e483d6fd324d92c193e629ad65a98a37, plus the two metric patches, pinned to a021c9ee3ccfc0ec74350614d0dca9c3e1ade504 (gas-9c8eb132). The full active metric baseline for Gnoswap main 42691b2d593272f86b0638d31bacf5a6b7813e6a is reports/metric/commits/42691b2.md: 85 passing filetests and 119 metric rows.

# Reproduce the pinned baseline without a fixture filter
make metric-force 42691b2d593272f86b0638d31bacf5a6b7813e6a

# Refresh every active metric fixture against fetched Gnoswap main
make metric-force main

Metric execution and report collection include only *_filetest.gno. Intentionally disabled .gnoa fixtures remain disabled, and their historical golden output is not included in new reports. This is a new runtime/fixture baseline, not a like-for-like performance comparison with older reports.

Report Example

Name	Gas Used	Storage Diff	CPU Cycles
TickMathGetSqrtRatioAtTick	652,368	0	641,936
Position Mint	32,077,387	42,822	22,212,424

Comparison Example

Name	Metric	Latest	Previous	Change	%
Position Mint	Gas Used	30,000,000	32,077,387	-2,077,387	-6.47%

Using Scripts Directly

parse_metrics.sh

Convert gno test results to markdown table.

# Use with pipe
gno test . -v -run . 2>&1 | ./scripts/parse_metrics.sh

# Read from file
./scripts/parse_metrics.sh output.txt

compare_reports.sh

Compare two report files.

./scripts/compare_reports.sh <latest.md> <previous.md>

compare_gno_txtar_gas.sh

Compare production-path GAS USED values for one fixed GnoSwap ref across multiple gnolang/gno refs. The script links the selected GnoSwap checkout into each Gno worktree, runs integration txtars through gnoland/gnokey, and emits matching gnokey maketx gas rows.

./scripts/compare_gno_txtar_gas.sh \
  --gnoswap-ref main \
  --ref master:origin/master \
  --ref pr5937:refs/pull/5937/head \
  --ref pr5938:refs/pull/5938/head \
  --test pool_swap_wugnot_gns_tokens \
  --test router_exact_in_swap_route \
  --target WrappedSwap \
  --target gno.land/r/gnoswap/router:ExactInSwapRoute \
  --format markdown

Use this lane when a Gno change affects gnoland app/store gas accounting and therefore cannot be represented by the canonical gno test metric lane.

parse_research.sh

Convert live-chain research TSV rows into a markdown table compatible with the compare pipeline.

./scripts/parse_research.sh < research/artifacts/latest-report.tsv