Transaction Simulation Sessions

In the previous tutorials, we demonstrated how you can simulate a transaction locally, or replay a past transaction. However, these methods only work for a single transaction.

To simulate multiple transactions in sequence, you’ll need to use Transaction Simulation Sessions — an advanced CLI feature that allows you to create a persistent local environment that saves and restores states between runs, with the added benefit of being able to inspect transaction outputs with ease.

This makes it possible to test complex workflows — such as contract deployment, resource updates, or multi-step interactions.

Note

Before you get started, make sure you have updated your Aptos CLI to the latest version.

Older versions of the Aptos CLI may not support Transaction Simulation Sessions as it’s a relatively new feature.

Initializing a Session

You can initialize a session either from:

• A clean local genesis, for a completely local, isolated environment, or
• A forked network state (Devnet, Testnet, or Mainnet), allowing you to test your changes against real-world data.

Regardless of which mode you choose, the interface, commands, and how session data is saved are exactly the same. Just specify your preferred mode when you initialize the session.

From a Forked Network State

With network forking, you can test your Move code using live network data — balances, resources, and published modules.

To start with a forked network state, run:

aptos move sim init --path <SESSION_PATH> --network <NETWORK> --api-key <YOUR_API_KEY>

Here <NETWORK> can be one of the following: devnet, testnet, mainnet, or a custom fullnode URL. The session will store all its data in the specified <SESSION_PATH> directory.

Note

You’ll need a free Aptos developer account and an API key to use network forking mode. Without an API key, you are given a very low rate limit and may run into rate limit errors almost certainly.

You can follow the official instructions here: Setup an API Key.

From a Clean Local Genesis

For day-to-day development, sometimes you just need a clean slate — no real network data needed. This is perfect for ad-hoc simulation,synthetic testing, or continuous integration.

To start with a clean local genesis, run:

aptos move sim init --path <SESSION_PATH>

Everything else works the same — except that the simulation won’t touch the network at all, as all data is local.

Running simulations

Once initialized, you can run transactions against your session using the standard aptos move commands, adding the --session argument to indicate which local session to use.

Supported commands include:

• run
• run-script
• publish
• view
• create-object-and-publish-package
• upgrade-object-package
• deploy-object
• upgrade-object
• create-resource-account-and-publish-package

There are also additional utilities under aptos move sim for managing and inspecting sessions.

• fund: fund an account with a given amount of APT
• view-resource: view a Move resource
• view-resource-group: view a resource group

For more detailed help, run aptos move sim --help.

Example Workflow

# 1. Fund your default account with 1 APT (for demo)
aptos move sim fund --session sess --account default --amount 100000000

# 2. Execute a transfer transaction
aptos move run --session sess \
  --function-id 0x1::aptos_account::transfer \
  --args address:default u64:100

# 3. Query your account's sequence number
aptos move view --session sess \
  --function-id 0x1::account::get_sequence_number \
  --args address:default

# 4. View your on-chain Account resource
aptos move sim view-resource --session sess \
  --account default \
  --resource 0x1::account::Account

# 5. View a resource group (e.g. your fungible store)
aptos move sim view-resource-group --session sess \
  --account default \
  --resource-group 0x1::object::ObjectGroup \
  --derived-object-address 0xA

Again, all state changes are local and are stored under your session directory.

Inspecting Session Data

Each Transaction Simulation Session organizes its data in a structured directory tree, making it easy to inspect every step of your simulation.

Here’s how the layout looks like for the sample session:

• Directorysess/

  • Directory[0] fund (fungible)/

    • summary.json
  • Directory[1] execute 0x1::aptos_account::transfer/

    • events.json
    • summary.json
    • write_set.json
  • Directory[2] view 0x1::account::get_sequence_number/

    • summary.json
  • Directory[3] view resource 0xdbcb…::0x1::account::Account/

    • summary.json
  • Directory[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
      }
    }
  }
]

Future Plans

We are working on adding more features to Transaction Simulation Sessions, such as:

• Gas Profiler integration
• Better performance
• Snapshot and rollback support