Skip to content

[codex] add contract performance profiling #478

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
Flamki wants to merge 1 commit into
base: master
Choose a base branch
from
+889 −24
Open

[codex] add contract performance profiling #478

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
39 changes: 39 additions & 0 deletions BENCHMARKS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,45 @@ regression comparisons.

---

## Contract performance profiling

Use `advanced-perf profile` when you need an artifact-level profile for a
compiled Soroban contract:

```bash
starforge advanced-perf profile ./target/wasm32-unknown-unknown/release/my_contract.wasm \
--label my-contract \
--dashboard ./target/starforge-profile.html
```

The profiler records:

- execution time analysis using estimated instruction count, CPU gas, and hot
WASM sections;
- memory usage tracking using linear memory pages, static section bytes, and an
estimated peak memory footprint;
- bottleneck identification from gas findings, instruction density, memory
pressure, and high estimated gas cost;
- a JSON profile report under `~/.starforge/contract_profiles/` unless
`--output <path>` is supplied;
- an optional HTML dashboard when `--dashboard <path>` is supplied.

To detect a performance regression, compare the candidate artifact with a saved
profile:

```bash
starforge advanced-perf profile ./target/wasm32-unknown-unknown/release/my_contract.wasm \
--label my-contract \
--baseline ~/.starforge/contract_profiles/profile-abc123def456.json \
--output ./target/candidate-profile.json
```

A regression is flagged when estimated gas, invocation time, or peak memory grows
by more than 10 percent over the baseline. Keep the latest accepted profile as
the next baseline so pull requests can compare performance consistently.

---

## Benchmark groups

| Group | Description |
Expand Down
26 changes: 26 additions & 0 deletions docs/COMMAND_REFERENCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -192,6 +192,32 @@ Coverage analysis tracks Soroban contract functions, line spans, branch paths, u

---

## `advanced-perf`

| Subcommand | Purpose |
|------------|---------|
| `advanced-perf profile <WASM>` | Profile a compiled Soroban contract artifact |
| `advanced-perf profile <WASM> --baseline <JSON>` | Detect gas, execution-time, or memory regressions against a saved profile |
| `advanced-perf profile <WASM> --dashboard <HTML>` | Generate a local performance dashboard |
| `advanced-perf analyze <CONTRACT>` | Analyze recorded runtime metrics for bottlenecks |
| `advanced-perf detect-regression <CONTRACT>` | Detect regressions from recorded metric history |
| `advanced-perf compare <CONTRACT>` | Compare recorded profiles across time windows |
| `advanced-perf generate-dashboard <CONTRACT>` | Show the recorded-metrics performance dashboard |

```bash
starforge advanced-perf profile ./target/wasm32-unknown-unknown/release/token.wasm \
--label token --dashboard ./target/token-profile.html

starforge advanced-perf profile ./target/wasm32-unknown-unknown/release/token.wasm \
--baseline ~/.starforge/contract_profiles/profile-abc123def456.json \
--output ./target/token-profile.json
```

The artifact profiler reports estimated execution time, memory usage, bottlenecks,
baseline regression detection, comparison deltas, and a dashboard summary.

---

## `security`

| Subcommand | Purpose |
Expand Down
Loading