Network Forking Made Easy: Transaction Simulation Sessions on Aptos

Ethereum developers have long relied on tools like Hardhat and Foundry to fork mainnet, run local simulations, and test contracts with live data.

Aptos developers can now do the same, with higher speed, simpler setup, and full parity with Move’s safety model.

Introducing Transaction Simulation Sessions, a native feature in the Aptos CLI designed for real-world testing at mainnet scale.

Testing for Smart Contracts

Every developer faces the same question before deployment: “How can I safely test my contract against real onchain data?”

Until now, the choices were clunky or incomplete.

• Unit tests are fast but completely manual; you have to set up your own state; you are not testing real transactions either, missing out related signals.
• Local nodes let you run full transactions, but they’re slow, heavy, and might require complex resets.
• Testnet persists state changes, making it hard to run tests/simulations repeatedly.

Most importantly, none of these options lets you test directly against real network data and real network conditions.

Transaction Simulation Sessions

Transaction Simulation Sessions introduce a new way to test and debug transactions as if they were executed on a live blockchain under your complete control.

The feature allows you to create persistent local environments that save and restore state between runs, with the ability to inspect every result as structured files.

Each session supports two operating modes that share a unified interface:

• Network Forking Mode: Fork the state of any remote network (devnet, testnet, or mainnet) and simulate transactions using real data.
• Clean Genesis Mode: Start from a fresh Aptos genesis for local testing.

Network Forking Made Easy

Network forking has been one of the most requested developer features.

Fork the network directly and start simulating:

# Fork from a remote network

aptos move sim init --path sess --network devnet --api-key "SOME_API_KEY"

You will need a free developer account and an API key. Forking mode fetches data on demand as transactions access it, without downloading the entire chain state.

Without an API key, you will almost certainly run into rate limit errors. You can follow the official instructions here: Setup an API Key.

Even when using network forking, all simulations happen locally. No onchain state is modified. Developers can experiment, debug, and replay infinitely without affecting the real network.

This workflow is significantly faster than running a local node. It starts instantly, executes quickly, and requires no additional dependencies. Perfect for developers who need repeatable, reproducible simulations.

Clean Genesis Mode: Your Controlled Sandbox

For clean, isolated testing or continuous integration, initialize a session from scratch:

# Start from a clean, local genesis state
aptos move sim init --path sess

This creates a brand-new Aptos genesis locally. All data stays on your machine.

Simulating Transactions Step by Step

Note: Update your Aptos CLI to the latest version. Older versions do not include Transaction Simulation Sessions nor the --session flag.

Once a session is initialized, all interactions happen through the CLI.

Existing aptos move commands now accept a --session argument: run, run-script, publish, view, and more.

There is also a new aptos move sim command family that adds session-specific functionality.

# 1. Fund your default account with 1 APT
#    This uses a test-only API for convenience
aptos move sim fund --session sess --account default --amount 100000000

# 2. Execute a transfer transaction (send 100 Octa to yourself, just for demo)
aptos move run --session sess \
  --function-id 0x1::aptos_account::transfer \
  --args address:default u64:100

# 3. Query your account’s sequence number with a view function
#    You should see your sequence number incremented from the previous transaction
aptos move view --session sess \
  --function-id 0x1::account::get_sequence_number \
  --args address:default

# 4. Inspect your onchain Account resource
aptos move sim view-resource --session sess \
  --account default \
  --resource 0x1::account::Account

# 5. Inspect a resource group.
#    The particular resource group we're inspecting contains your fungible store, 
#    so you can see your APT balance.
aptos move sim view-resource-group --session sess \
  --account default \
  --resource-group 0x1::object::ObjectGroup \
  --derived-object-address 0xA

All simulations are local. Even when forking a network, your transactions never touch the real blockchain.

Inspecting Session Data

Every Transaction Simulation Session structures its data for easy inspection and debugging. Each command you execute, funding, executing or viewing creates a separate directory with full outputs.

sess
├── [0] fund (fungible)
│   └── summary.json
├── [1] execute 0x1::aptos_account::transfer
│   ├── events.json
│   ├── summary.json
│   └── write_set.json
├── [2] view 0x1::account::get_sequence_number
│   └── summary.json
├── [3] view resource 0xdbcb...::0x1::account::Account
│   └── summary.json
├── [4] view resource group 0x20ce...::0x1::object::ObjectGroup
│   └── summary.json
├── config.json
└── delta.json

Sample outputs

[1] execute 0x1::aptos_account::transfer/summary.json
{
  "execute_transaction": {
    "status": {
      "Keep": "Success"
    },
    "gas_used": 498,
    "fee_statement": {
      "total_charge_gas_units": 498,
      "execution_gas_units": 4,
      "io_gas_units": 3,
      "storage_fee_octas": 49160,
      "storage_fee_refund_octas": 0
    }
  }
}

[1] execute 0x1::aptos_account::transfer/events.json
[
  {
    "V2": {
      "type_tag": "0x1::fungible_asset::Withdraw",
      "event_data": {
        "store": "20ce9f242351eae77cae7eb27e7e55f798e6c3b3528fcbb325bccea103e53ff9",
        "amount": 100
      }
    }
  },
  {
    "V2": {
      "type_tag": "0x1::fungible_asset::Deposit",
      "event_data": {
        "store": "20ce9f242351eae77cae7eb27e7e55f798e6c3b3528fcbb325bccea103e53ff9",
        "amount": 100
      }
    }
  },
  {
    "V2": {
      "type_tag": "0x1::transaction_fee::FeeStatement",
      "event_data": {
        "total_charge_gas_units": 498,
        "execution_gas_units": 4,
        "io_gas_units": 3,
        "storage_fee_octas": 49160,
        "storage_fee_refund_octas": 0
      }
    }
  }
]

Why It Matters

Transaction Simulation Sessions bring a familiar workflow (like Hardhat’s network forking) to the Aptos ecosystem.

It is a CLI-native, lightweight framework that enables fast, repeatable, and deterministic testing for Move developers.

Each run is reproducible, every result is inspectable, and the turnaround time is seconds rather than hours. Fork mainnet, test real data, and deploy with confidence.

Roadmap

Future releases will extend Transaction Simulation Sessions with gas profiling, state snapshots, and rollbacks.

A TypeScript-based integration testing framework is also in development, built on top of these sessions. It will deliver better programmability, automation, and end-to-end validation for complex contracts and workflows, offering an experience familiar to Hardhat/Foundry users.

Stay tuned for updates.

More details.