# Move Replay

> {{ frontmatter(name="move-replay", description="Replay a committed Aptos user transaction locally. Use to diagnose an on-chain outcome or compare it with local Move package overrides; this does not resubmit the transaction.") }}

- Skill: `aptos-labs/move-replay` (Agent Skill)
- Install (CLI): `npx skillmds@latest add aptos-labs/move-replay`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aptos-labs/move-replay/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aptos-labs (https://skillmd.com/u/aptos-labs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aptos-labs/move-replay

---

{{ frontmatter(name="move-replay", description="Replay a committed Aptos user transaction locally. Use to diagnose an on-chain outcome or compare it with local Move package overrides; this does not resubmit the transaction.") }}

## Replay workflow

Use `{{ tool(name="move_replay_transaction") }}` rather than invoking the Aptos
CLI directly. The tool reads the committed transaction and historical state,
then executes locally; it does not mutate on-chain state.

You need the committed ledger `txn_id` and its network (`mainnet`, `testnet`,
`devnet`, or a REST endpoint). Ask only when those cannot be determined from the
request or workspace.

### Diagnose the recorded transaction

1. Replay without local overrides or tracing.
2. Read `success` and `vm_status`, then use structured `abort` or
   `execution_failure` fields when present.
3. For a Move abort, report its module, raw code, and symbolic reason/description
   when available. Locate the matching source constant only when source-level
   explanation is useful.
4. For an execution failure, report its location, function index, and bytecode
   offset. Do not invent a source line without disassembly or source evidence.
5. `success: null` represents a discarded/retried status rather than a normal
   committed execution; explain it from `vm_status`.

### Compare a local patch

First capture the unmodified replay. Then pass buildable package roots in
`local_package_paths` and supply only the named-address bindings needed to
compile them. Confirm `local_override_in_use: true` and compare the structured
status with the baseline. Label the result as a local simulation, not the
historical on-chain outcome. A link/type incompatibility is a compatibility
failure, not evidence that the patch fixed the transaction.

### Trace only when needed

Start with `trace: true`, which records debugger state-view use. Enable
`trace_storage_reads` only when the user needs touched storage keys; it can
produce hundreds of events. Keep keys redacted unless their contents are
necessary, and raise `max_trace_events` only when the response reports
truncation. This trace does not expose Move call frames, so use the structured
failure plus source/bytecode inspection for the failing instruction.

Report exact status fields, but summarize long traces unless the user asks for
the individual entries. Never print an API key supplied for node access.