Skip to content

Commit 8fe7e93

Browse files
dannywillemsdannywillems
committed
Website: add doc for replayer
1 parent 2049ad7 commit 8fe7e93

File tree

8 files changed

+251
-0
lines changed

8 files changed

+251
-0
lines changed

‎website/docs/developers/scripts/replayer/record-node.sh‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
#!/bin/bash
2+
# Record node execution for debugging and replay
3+
4+
# Run node with recording enabled
5+
mina node \
6+
--network devnet \
7+
--record state-with-input-actions \
8+
--work-dir ~/.mina-replay-test

‎website/docs/developers/scripts/replayer/record-with-custom-dir.sh‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
#!/bin/bash
2+
# Record node execution with custom working directory
3+
4+
WORK_DIR="$1"
5+
if [ -z "$WORK_DIR" ]; then
6+
echo "Usage: $0 <work-directory>"
7+
exit 1
8+
fi
9+
10+
# Run node with recording enabled using custom directory
11+
mina node \
12+
--network devnet \
13+
--record state-with-input-actions \
14+
--work-dir "$WORK_DIR"

‎website/docs/developers/scripts/replayer/replay-dynamic-effects.sh‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
#!/bin/bash
2+
# Build custom effects library and replay with custom effects
3+
4+
# Build custom effects library
5+
cargo build --release -p replay_dynamic_effects
6+
7+
# Replay with custom effects
8+
mina replay state-with-input-actions \
9+
--dir ~/.mina-replay-test/recorder \
10+
--dynamic-effects-lib ./target/release/libreplay_dynamic_effects.so

‎website/docs/developers/scripts/replayer/replay-ignore-mismatch.sh‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
#!/bin/bash
2+
# Replay and ignore build environment differences
3+
4+
mina replay state-with-input-actions \
5+
--dir ~/.mina-replay-test/recorder \
6+
--ignore-mismatch

‎website/docs/developers/scripts/replayer/replay-node.sh‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
#!/bin/bash
2+
# Replay recorded node execution
3+
4+
# Replay from the recorded directory
5+
mina replay state-with-input-actions --dir ~/.mina-replay-test/recorder

‎website/docs/developers/testing/replayer.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
---
2+
title: Replayer
3+
description: Record and replay node execution for debugging
4+
sidebar_position: 8
5+
---
6+
7+
import CodeBlock from "@theme/CodeBlock"; import RecordNode from
8+
"!!raw-loader!../scripts/replayer/record-node.sh"; import ReplayNode from
9+
"!!raw-loader!../scripts/replayer/replay-node.sh"; import RecordWithCustomDir
10+
from "!!raw-loader!../scripts/replayer/record-with-custom-dir.sh"; import
11+
ReplayIgnoreMismatch from
12+
"!!raw-loader!../scripts/replayer/replay-ignore-mismatch.sh"; import
13+
ReplayDynamicEffects from
14+
"!!raw-loader!../scripts/replayer/replay-dynamic-effects.sh";
15+
16+
# Replayer
17+
18+
The replayer is a specialized debugging tool that enables deterministic
19+
recording and replay of node execution. It captures the complete state machine
20+
behavior of a running node, allowing developers to reproduce and debug issues
21+
with perfect accuracy.
22+
23+
## What is a replayer node?
24+
25+
A replayer node is not a separate node type, but rather a mode of operation that
26+
allows you to:
27+
28+
- **Record execution**: Capture initial state and all input actions during node
29+
operation
30+
- **Deterministic replay**: Reproduce the exact sequence of state transitions
31+
offline
32+
- **Debug issues**: Analyze problematic behavior by replaying recorded execution
33+
- **Verify behavior**: Ensure state machine transitions remain consistent across
34+
code changes
35+
36+
### How it works
37+
38+
The replayer operates in two phases:
39+
40+
#### 1. Recording phase
41+
42+
During normal node operation with recording enabled:
43+
44+
- Initial node state is serialized to disk
45+
- All input actions (events that trigger state changes) are logged with metadata
46+
- Effect actions (side effects dispatched by reducers) are tracked
47+
- Data is stored in the `recorder/` directory within the working directory
48+
49+
#### 2. Replay phase
50+
51+
During replay:
52+
53+
- Initial state is loaded from the recording
54+
- Input actions are dispatched in the exact order they occurred
55+
- The replayer verifies that effect actions match the recording
56+
- Any mismatches indicate non-deterministic behavior or code changes
57+
58+
### Use cases
59+
60+
- **Bug reproduction**: Capture a failing node execution and replay it locally
61+
for debugging
62+
- **Regression testing**: Ensure state machine behavior remains consistent after
63+
code changes
64+
- **Performance analysis**: Analyze state transitions without network I/O
65+
overhead
66+
- **CI/CD validation**: Automated testing of recorded scenarios in continuous
67+
integration
68+
69+
<!-- prettier-ignore-start -->
70+
71+
:::note Deterministic behavior requirement
72+
73+
The replayer requires that the node's state machine is deterministic. Any
74+
non-deterministic behavior (random number generation without proper seeding,
75+
system time calls, etc.) will cause replay validation to fail.
76+
77+
The Mina node architecture uses a seeded RNG and controlled time sources to
78+
ensure deterministic behavior.
79+
80+
:::
81+
82+
<!-- prettier-ignore-stop -->
83+
84+
---
85+
86+
## Recording node execution
87+
88+
To record a node's execution, use the `--record` flag with the
89+
`state-with-input-actions` mode.
90+
91+
### Basic recording
92+
93+
<CodeBlock language="bash" title="website/docs/developers/scripts/replayer/record-node.sh">
94+
{RecordNode}
95+
</CodeBlock>
96+
97+
This will:
98+
99+
- Start a node connected to devnet
100+
- Record all state and actions to `~/.mina-replay-test/recorder/`
101+
- Run until manually stopped (Ctrl+C)
102+
103+
### Recording with custom directory
104+
105+
<CodeBlock language="bash"
106+
title="website/docs/developers/scripts/replayer/record-with-custom-dir.sh"
107+
108+
> {RecordWithCustomDir} </CodeBlock>
109+
110+
### Recording options
111+
112+
The `--record` parameter accepts the following values:
113+
114+
- **`none`**: No recording (default)
115+
- **`state-with-input-actions`**: Records initial state and all input actions
116+
117+
### Recorded data structure
118+
119+
When recording is enabled, data is stored in the following structure:
120+
121+
```
122+
<work-dir>/recorder
123+
├──actions_1.postcard
124+
├──actions_2.postcard
125+
├──actions_3.postcard
126+
|──actions_4.postcard
127+
├──actions_5.postcard
128+
├──actions_6.postcard
129+
├──actions_7.postcard
130+
|──actions_8.postcard
131+
└──initial_state.postcard
132+
```
133+
134+
<!-- prettier-ignore-start -->
135+
136+
:::warning Storage considerations
137+
138+
Recording can generate significant data over time. Monitor disk space usage when
139+
running with recording enabled for extended periods.
140+
141+
:::
142+
143+
<!-- prettier-ignore-stop -->
144+
145+
---
146+
147+
## Replaying recorded execution
148+
149+
Once you have recorded node execution, you can replay it using the `mina replay`
150+
command.
151+
152+
### Basic replay
153+
154+
<CodeBlock language="bash" title="website/docs/developers/scripts/replayer/replay-node.sh">
155+
{ReplayNode}
156+
</CodeBlock>
157+
158+
This will:
159+
160+
- Load the initial state from the recording
161+
- Dispatch all recorded actions in order
162+
- Verify that effect actions match the recording
163+
- Exit when all actions have been replayed
164+
165+
### Replay with build environment checking
166+
167+
By default, replay validates that the recorded build environment matches the
168+
current build. To ignore mismatches (useful when testing code changes):
169+
170+
<CodeBlock language="bash"
171+
title="website/docs/developers/scripts/replayer/replay-ignore-mismatch.sh"
172+
173+
> {ReplayIgnoreMismatch} </CodeBlock>
174+
175+
### Replay with dynamic effects
176+
177+
For advanced debugging, you can inject custom effect handlers during replay:
178+
179+
<CodeBlock language="bash"
180+
title="website/docs/developers/scripts/replayer/replay-dynamic-effects.sh"
181+
182+
> {ReplayDynamicEffects} </CodeBlock>
183+
184+
Custom effects allow you to:
185+
186+
- Inspect state at specific points during replay
187+
- Modify behavior for debugging purposes
188+
- Hot-reload the effects library without restarting replay

‎website/docs/node-operators/infrastructure/replayer-nodes.mdx‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Replayer Nodes
3+
description: o1Labs replayer nodes for debugging and verification
4+
sidebar_position: 7
5+
---
6+
7+
# Replayer Nodes
8+
9+
This section is still a work in progress. It will cover nodes running with
10+
recording enabled for debugging production issues and verifying node behavior
11+
through deterministic replay.
12+
13+
For detailed documentation on how to use the replayer for recording and
14+
replaying node execution, see the
15+
[Replayer documentation](/developers/testing/replayer) in the developers testing
16+
section.
17+
18+
Track progress: [Issue #1619](https://github.com/o1-labs/mina-rust/issues/1619)

‎website/sidebars.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ const sidebars: SidebarsConfig = {
4949
'node-operators/infrastructure/plain-nodes',
5050
'node-operators/infrastructure/archive-nodes',
5151
'node-operators/infrastructure/block-producers',
52+
'node-operators/infrastructure/replayer-nodes',
5253
'node-operators/infrastructure/memory-profiler',
5354
'node-operators/infrastructure/network-debugger',
5455
'node-operators/infrastructure/frontend',
@@ -142,6 +143,7 @@ const sidebars: SidebarsConfig = {
142143
'developers/testing/p2p-tests',
143144
'developers/testing/network-connectivity',
144145
'developers/testing/ocaml-node-tests',
146+
'developers/testing/replayer',
145147
],
146148
},
147149
{

0 commit comments

Comments
 (0)