Introducing Forklift: Network Forking and Smart Contract Testing for Aptos

Testing Move smart contracts on Aptos has always been tricky, as there were no easy ways to simulate transaction-based workflows with isolation and repeatability, let alone fork real network state for realistic testing. Until now.

Today, we’re releasing Forklift, a Move smart contract testing and scripting framework for Aptos. Written in TypeScript, it provides a unified interface: the Harness class, which works across local simulation, network forking, and live network execution.

If you’re coming from Ethereum, think of Forklift as Hardhat/Foundry for Aptos.

Why Forklift Changes Everything

Before Forklift, if you wanted to simulate how your contract interacts with a real deployed protocol, say, a DEX or lending platform, your options were limited:

• Unit tests: Great for isolated logic, but can’t simulate real transactions, let alone multiple ones
• Local node: Requires manual setup, slow to start, and you still don’t have a real network state
• Devnet/Testnet: State persists between runs, no isolation, not reproducible
• Mainnet: Costs gas, changes are permanent, high stakes for experimentation

Forklift eliminates these tradeoffs. You can now:

• Fork any network and simulate against real deployed contracts
• Write once and have the same code work in local simulation, on forks, and in production
• Run reproducible tests with isolated sessions, deterministic results, and CI-friendly
• Skip local validator node

This is the workflow Move developers have been missing.

One API, Three Modes

Forklift provides a unified Harness class that works across three execution modes:

What makes the Harness powerful is that your code stays the same across all modes. Define your workflow once, swap the harness to change environments:

function deployAndInteract(harness: Harness) {
  const result = harness.deployCodeObject({
    sender: "alice",
    packageDir: "./move/my_contract",
    packageAddressName: "my_contract",
  });

  harness.runMoveFunction({
    sender: "alice",
    functionId: `${result.Result.deployed_object_address}::my_module::initialize`,
    args: [],
  });
}

// Same workflow, different environments
deployAndInteract(Harness.createLocal());                         // Fast iteration
deployAndInteract(Harness.createNetworkFork("mainnet", apiKey));  // Verify against real state
deployAndInteract(Harness.createLive("mainnet"));                 // Execute for real

The Killer Feature: Network Forking

One capability that really stands out is network forking. With a single line of code, you can fork mainnet (or other networks) and simulate transactions against real chain state.

import { Harness } from "@aptos-labs/forklift";

// Fork mainnet - real state, zero consequences
const harness = Harness.createNetworkFork("mainnet", apiKey);
// Your transactions run against real deployed contracts
harness.runMoveFunction({
  sender: "alice",
  functionId: "0x123...::my_protocol::swap",
  args: [...],
});

// All changes stay local - mainnet is untouched

Want to test how your DeFi protocol interacts with existing liquidity pools? Fork mainnet and find out. Need to dry-run a contract upgrade against real user state? Fork it first. Investigating a potential vulnerability? Fork it and reproduce the exploit safely in isolation.

State is fetched on demand as a local VM executes your transactions. Your modifications stay completely local, and the network is never affected.

Getting Started

npm install --save-dev @aptos-labs/forklift

Prerequisites: Node.js v18+ and Aptos CLI v7.14.1+

Check out the Forklift repository for full documentation and API reference. Also, take a look at the TipJar tutorial for a complete walkthrough from writing a contract to deploying on a real network.

Under the Hood

Architecture

Forklift is built on top of Transaction Simulation Sessions (TSS), a native feature of the Aptos CLI. Its architecture consists of three layers:

• Simulation Infrastructure: The foundation — state management, storage backends, transaction execution
• Transaction Simulation Sessions: Persistence, network forking, and CLI integration
• Forklift: A TypeScript wrapper that makes TSS programmable

Design Philosophy: Thin by Choice

Forklift is intentionally lightweight. It’s a thin wrapper around the CLI rather than a full-blown framework on its own.

This is a deliberate choice:

• Easy to maintain with minimal surface area and few moving parts
• Stay in sync with the CLI and inherit its improvements automatically
• High test coverage thanks to minimal ****surface area
• Port to other languages easily with the thin design

The CLI does the heavy lifting (compilation, simulation, transaction building), while forklift provides the clean programmatic interface.

How Network Forking Works

When you create a network fork:

1. The session connects to the network’s REST API
2. State is fetched on-demand as transactions access it
3. All writes stay local in a delta layer
4. Sessions persist to disk. You can pause, resume, or share them anytime.

The key abstraction is a delta-based state store that stacks local changes on top of remote state. Reads check local first, then fall back to remote reads from the network. Writes always stay local. This makes forking both efficient and safe.

What’s Next

Forklift is ready for use today and we’d love to hear your feedback!

Try it out, and feel free to file issues or PRs if you spot any bugs or want to request new features!

For those who prefer working directly with the CLI, Transaction Simulation Sessions is also available today. See Network Forking Made Easy for details.

Introducing Forklift: Network Forking and Smart Contract Testing for Aptos was originally published in Aptos Labs on Medium, where people are continuing the conversation by highlighting and responding to this story.