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:

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

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

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