# Mina O1js Debugging Performance

> Use when debugging or optimizing Mina o1js compile, prove, transaction, AccountUpdate, permission, witness, constraint count, browser proving, worker, memory, or performance issues.

- Skill: `mysteryon88/mina-o1js-debugging-performance` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add mysteryon88/mina-o1js-debugging-performance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mysteryon88/mina-o1js-debugging-performance/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mysteryon88 (https://skillmd.com/u/mysteryon88)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mysteryon88/mina-o1js-debugging-performance

---


# Mina o1js Debugging and Performance Skill

## Use when

Use this skill when the user has failing proofs, slow proving, compile errors, transaction failures, state mismatch, frontend prover issues or confusing o1js behavior.

## Shared references

If installed from the full package, shared resources live in `../mina-protocol-agent/references/`. Load `../mina-protocol-agent/references/INDEX.md` only when task cards, examples, templates, source links or deeper checklists are needed.

## Compatibility gate

Before a version-sensitive claim, record the target network, active protocol era, exact `o1js` and signer versions, wallet/CLI versions, endpoints, and the origin of verification keys and proof caches. Load `../mina-protocol-agent/references/playbooks/NETWORK_ERA_AND_O1JS_COMPATIBILITY.md` for Berkeley/Mesa and o1js 3 migration rules. If the era is unknown, label the guidance unverified rather than guessing from package or endpoint names.

## Runtime and cache split

Classify the prover backend before tuning: browser/WASM worker, Node.js native prover, or other supported runtime. The native prover is not available as a browser shortcut. For unexplained compile/prove failures after an upgrade, isolate a clean cache, record verification-key hashes, and test a minimal proof before changing circuit logic. For send failures, switch to `../mina-protocol-agent/references/playbooks/TRANSACTION_LIFECYCLE_AND_WALLET_PREFLIGHT.md` instead of treating every failure as proving performance.

## Debugging rule

Separate three failure classes:

```text
TypeScript/runtime error
Proof/constraint error
Mina transaction/AccountUpdate/permission error
```

Do not debug all three at once. Reduce to the smallest failing case.

## First output

```text
Failure type:
Where it fails: compile / prove / sign / send / fetch / frontend
Minimal reproduction:
o1js version:
Proofs enabled:
Contract/program involved:
Inputs:
State before:
Expected state after:
```

## Debug workflow

### 1. Compile-time/circuit issues

Check:

- dynamic arrays in provable code;
- JS values used where provable types are expected;
- unsupported branching on provable values;
- witness shape changes between compile and prove;
- methods not async when expected by current style;
- imported API from wrong o1js version.

### 2. Proof failures

Check:

- assertion actually fails;
- witness callback returns unexpected value;
- hash field order/domain mismatch;
- signature message mismatch;
- Merkle witness generated for different root/index;
- range check fails;
- public input differs from frontend/backend expectation.

### 3. Transaction failures

Use `mina-accountupdate-transaction-debugger`.

Check:

- missing proof;
- missing signature;
- missing `fundNewAccount`;
- wrong network/address;
- stale state precondition;
- wrong token id;
- permission mismatch;
- verification key mismatch.

### 4. Performance issues

Check:

- proof generated in browser vs Node/backend;
- repeated compile in hot path;
- large fixed arrays;
- expensive hash or signature loops;
- unnecessary recursion depth;
- too many AccountUpdates;
- no caching of compiled artifacts;
- frontend bundle too heavy.

Use constraint analysis for heavy pure provable functions when possible.

## Common fixes

- replace `get()` with `getAndRequireEquals()` for state mismatch bugs;
- use `UInt64`/`UInt32` instead of `Field` for bounded values;
- include domain/action/recipient/nonce in signature message;
- use fixed `Provable.Array` size;
- precompute off-circuit data, but prove the relation in-circuit;
- move heavy proof generation out of blocking UI path;
- compile once, prove many times where architecture allows;
- add a minimal failing test before changing logic.

## Output format

```text
Likely failure class
Minimal reproduction
Root cause hypothesis
Fix
Regression test
Performance notes
```