Skip to content

Commit 175125f

Browse files
dannywillemsdannywillems
committed
Website: add doc for replayer
1 parent 2049ad7 commit 175125f

File tree

8 files changed

+249
-0
lines changed

8 files changed

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