Adding Golden Traces¶
Process¶
- select scenario and initial state.
- record ordered tx/events.
- capture expected state after each step.
- replay in harness and assert exact match.
Priority Scenarios¶
- first successful deposit with full baseline checks
- observation conflict then conflict close
- reserve-backed smoothing advance then recoup
- exit + settlement + principal claim + reward claim
Acceptance Criteria¶
A golden trace is not useful unless it is replayable by another engineer from a clean checkout. Include deterministic input data, expected transaction ordering, expected event topics, and state snapshots after every action. For economic paths, include source ids, source groups, receipt kinds, epochs, reserve state, and expected claimability.
Review Rule¶
Every new trace must explain which invariant, state machine, or runbook it supports. If a trace covers only the happy path, label it that way and add a paired failure trace before using it as release evidence.
Evidence Model¶
| Field | Requirement |
|---|---|
| Purpose | procedure for adding reproducible scenario examples. |
| Expected location | fixture directory and expected output files. |
| Current local evidence status | Evidence required unless the named artifact is present in this repository or the Solidity source snapshot and has been inspected in the current run. |
| What it proves | scenario regression stability. |
| What it does not prove | formal proof or full production coverage. |
| How to regenerate | Run the documented tool from a clean environment, archive command, commit/source hash, config, stdout/stderr, and result files. |
| Production requirement | Results must be tied to the exact source manifest lock, compiler version, dependency lock, and deployment artifact under review. |
| Owner responsible | Protocol engineering owns source/test correctness; security review owns independent challenge; governance owns accepting residual risk. |
| Failure meaning | A failure blocks release, launch, upgrade, or operation until root cause is fixed or explicitly accepted with documented risk. |
Review Notes¶
Do not write “pass” for Golden trace additions without current evidence. If evidence is missing, stale, or tied to a different source snapshot, write Evidence required and keep the gap visible in the release or operations checklist.