Replay transactions from DA-Sequencer blocks to an Aptos Validator Node

[sebtomba]

Summary

• RFCs: $\emptyset$.
• Categories: util

This PR adds a validation utility for the L1 migration. It allows replaying transactions from the DA-Sequencer to an Aptos Validator Node. To run the tool, one must know the current DA synced height of the Movement node, which provides the database for the Aptos Validator Node. The tool can extract the current synced DA block height from a local copy of the movement-da-db. If the movement-da-dab is available on the same machine, the utility can extract the DA height automatically before replaying the blocks/transactions. Besides replaying transactions on the Aptos node, the utility also validates (compares) the execution outputs from both nodes if a URL to a Movement full-node gets provided as a parameter.

Examples

Extract the synced DA height from the movement-da-db:

movement-full-node admin l1-migration validate extract-da-height /home/ubuntu/.movement/movement-da-db/

Replay transactions to a validator node (extern):

movement-full-node admin l1-migration validate replay \
  --movement-api <MOVEMENT_API_URL> \
  --aptos-api <APTOS_API_URL> \
  --da <DA_SEQUENCER_URL> \
  --da-height <HEIGHT>

Replay transactions to a validator node (intern):

movement-full-node admin l1-migration validate replay \
  --movement-api <MOVEMENT_API_URL> \
  --aptos-api <APTOS_API_URL> \
  --da <DA_SEQUENCER_URL> \
  --da-db <PATH>

Changelog

The PR fixes only the spelling of comments and error messages.

Testing

1. Stop the Movement full-node.
2. Copy (rsync) the Aptos database from the Movement full-node.
3. Extract the synced DA-height from movement-da-db (optional, see example above).
4. Generate the waypoint and genesis files.
5. Remove secure-data.json
6. Run the Movement full-node.
7. Run the Aptos validator node.
8. Run the replay and validation of transactions (see examples above).

Outstanding issues

It's expected that the first n submitted transactions by the replay tool might get rejected by the validator node with the following errors:

Error(VmError): Invalid transaction: Type: Validation Code: TRANSACTION_EXPIRED
Error(VmError): Invalid transaction: Type: Validation Code: SEQUENCE_NUMBER_TOO_OLD

Currently, most validated transactions have a different write-set, which needs to be investigated:

2025-08-29T11:39:43.247142Z ERROR movement_full_node::admin::l1_migration::replay::compare: Transaction write-set mismatch (0x9c992ec6a1d590bb8027847a6b16ee312c74393982f6f883c08717cb38bb0967)
2025-08-29T11:39:43.460894Z ERROR movement_full_node::admin::l1_migration::replay::compare: Transaction write-set mismatch (0x5d176e15134db6481735f88ddae8bcd96741b3163f8cc8e6dd3418d508aa54c3)

[musitdev]

The idiomatic way to add a new command to the movement repo is to use the movement_node crate as a CLI.
See the PR #1300 and mostly the new cmd file
And the implementation part. It's not mandatory to put the impl in the maptos/execution part. You can put all the code in the movement-node.

No sure it's important to change your code to the idiomatic way. The advantage of this code organization is that you can use Docker to execute the command on any instance without building it. See the docker script.
One other remarks, if you integrate the code in the movement-node crate, you can reuse the da-db module instead of copying it in your code.