Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 9 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
# Forklift

[![Tests](https://github.com/aptos-labs/forklift/actions/workflows/run-tests.yml/badge.svg)](https://github.com/aptos-labs/forklift/actions/workflows/run-tests.yml)
[![Tests](https://github.com/MoveIndustries/forklift/actions/workflows/run-tests.yml/badge.svg)](https://github.com/MoveIndustries/forklift/actions/workflows/run-tests.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

Forklift is a TypeScript framework for developing, testing, and scripting Aptos Move smart contracts. It provides a unified interface — the `Harness` class — that works across local simulation, network forking, and live network execution.
Forklift is a TypeScript framework for developing, testing, and scripting Move smart contracts on Movement. It provides a unified interface — the `Harness` class — that works across local simulation, Movement network forking, and live Movement network execution.

## Features

- **Local Simulation**: Develop and test without any network. Runs entirely in memory with instant execution. Includes test-only APIs like instant account funding.
- **Network Forking**: Test against real Mainnet/Testnet/Devnet state without spending gas or affecting the network.
- **Network Forking**: Test against real Movement Mainnet/Testnet/Devnet state without spending gas or affecting the network.
- **Live Scripting**: Deploy contracts and execute transactions on real networks using the same code you tested locally.
- **TypeScript Native**: Write tests and scripts in standard TypeScript with full Node.js capabilities.
- **Easy Setup**: No need to manually spawn or manage a local validator node. Forklift handles the simulation lifecycle automatically.
Expand All @@ -17,7 +17,9 @@ Forklift is a TypeScript framework for developing, testing, and scripting Aptos
## Prerequisites

- **Node.js** v18 or later
- **Aptos CLI** v8.1.0 or later ([installation guide](https://aptos.dev/tools/aptos-cli/)) — validated at runtime with a clear error message if missing or outdated
- **Movement CLI**. Local simulation and network forking require v8.1.0 or later with transaction simulation session support; live mode only requires a CLI that supports the live command being executed.

Forklift invokes `movement` by default. Set `FORKLIFT_CLI_BINARY=/path/to/movement` if the binary is not on `PATH`, or when testing with a specific CLI build.

## Installation

Expand Down Expand Up @@ -57,7 +59,7 @@ harness.cleanup();

For a complete tutorial, see the [TipJar example](./packages/example-tip-jar/).

> **Note:** Forklift uses the same formats as the Aptos CLI for function IDs (`0x1::module::function`), addresses, and typed arguments (`u64:100`, `address:0x1`, `bool:true`). If you're familiar with the CLI, you already know the syntax.
> **Note:** Forklift uses the same formats as the Movement CLI for function IDs (`0x1::module::function`), addresses, and typed arguments (`u64:100`, `address:0x1`, `bool:true`). If you're familiar with the CLI, you already know the syntax.

## The Harness Class

Expand All @@ -71,7 +73,7 @@ All interactions with Forklift go through the `Harness` class. Create one using

**Local simulation** is your starting point. It runs entirely in memory with no network dependencies — perfect for rapid iteration during development and for CI pipelines.

**Network forking** is one of Forklift's most powerful features. It fetches real chain state (accounts, resources, deployed contracts) and lets you simulate against it locally. This is useful for testing interactions with existing protocols or verifying your scripts before executing them for real. The `apiKey` is required to avoid rate limiting when fetching state from the network — [get one for free](https://aptos.dev/build/guides/build-e2e-dapp#setup-api-key).
**Network forking** is one of Forklift's most powerful features. It fetches real Movement chain state (accounts, resources, deployed contracts) and lets you simulate against it locally. This is useful for testing interactions with existing protocols or verifying your scripts before executing them for real. Known network names resolve to Movement endpoints: `mainnet` -> `https://mainnet.movementnetwork.xyz`, `testnet` -> `https://testnet.movementnetwork.xyz`, and `devnet` -> `https://devnet.movementnetwork.xyz`.

**Live mode** executes real transactions on the network. Use this when you're ready to deploy or interact with contracts for real — but remember, this costs gas and changes are permanent.

Expand Down Expand Up @@ -267,7 +269,7 @@ harness.newBlock({ timestampUsecs: 1_800_000_000_000_000 });

- **[TipJar](./packages/example-tip-jar/)** — Full tutorial covering the develop → test → deploy → interact workflow
- **[Testsuite](./packages/testsuite/)** — Internal tests demonstrating various Forklift features
- **[Live Tests](./packages/live-tests/)** — Examples using live mode against a real node. Note: you must spawn and manage your own local node (via the Aptos CLI or SDK) to run these. Prefer local simulation mode when possible — it's simpler to set up, more flexible and provides better isolation.
- **[Live Tests](./packages/live-tests/)** — Examples using live mode against a real node. Note: you must spawn and manage your own local node (via the Movement CLI or SDK) to run these. Prefer local simulation mode when possible — it's simpler to set up, more flexible and provides better isolation.

## Forklift vs. Aptos TS SDK

Expand Down
10 changes: 8 additions & 2 deletions packages/forklift/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,14 @@
# Changelog

## Unreleased

- Default CLI execution now targets `movement`; set `FORKLIFT_CLI_BINARY` to use a specific Movement CLI build.
- Local and forked simulations validate transaction simulation session support without blocking live mode on older Movement CLI versions.
- Known network names resolve to Movement endpoints for live and forked sessions: `mainnet`, `testnet`, and `devnet`.

## 1.2.0

- **Aptos CLI version validation** — The Harness now checks for a compatible Aptos CLI at construction time. Missing CLI gives `"Aptos CLI not found…"` instead of a cryptic `ENOENT`. Outdated CLI tells you the required version and where to update.
- **CLI version validation** — The Harness now checks for a compatible CLI at construction time. Missing CLI gives a clear error instead of a cryptic `ENOENT`. Outdated CLI tells you the required version.
- Exported `MIN_CLI_VERSION` and `compareVersions` for tooling use.

## 1.1.1
Expand All @@ -20,7 +26,7 @@

### Requirements

- Aptos CLI v8.1.0 or later (previously v7.14.2).
- CLI v8.1.0 or later (previously v7.14.2).

## 1.0.1

Expand Down
8 changes: 4 additions & 4 deletions packages/forklift/README.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# Forklift

Forklift is a TypeScript framework for developing, testing, and scripting Aptos Move smart contracts. It provides a unified interface — the `Harness` class — that works across local simulation, network forking, and live network execution.
Forklift is a TypeScript framework for developing, testing, and scripting Move smart contracts on Movement. It provides a unified interface — the `Harness` class — that works across local simulation, Movement network forking, and live Movement network execution.

## Features

- **Local Simulation**: Develop and test without any network. Runs entirely in memory with instant execution. Includes test-only APIs like instant account funding.
- **Network Forking**: Test against real Mainnet/Testnet/Devnet state without spending gas or affecting the network.
- **Network Forking**: Test against real Movement Mainnet/Testnet/Devnet state without spending gas or affecting the network.
- **Live Scripting**: Deploy contracts and execute transactions on real networks using the same code you tested locally.
- **TypeScript Native**: Write tests and scripts in standard TypeScript with full Node.js capabilities.
- **Easy Setup**: No need to manually spawn or manage a local validator node. Forklift handles the simulation lifecycle automatically.
Expand All @@ -17,7 +17,7 @@ Forklift is a TypeScript framework for developing, testing, and scripting Aptos
npm install @aptos-labs/forklift
```

**Prerequisites:** Node.js v18+ and [Aptos CLI](https://aptos.dev/tools/aptos-cli/) v8.1.0+ (validated at runtime)
**Prerequisites:** Node.js v18+ and Movement CLI. Local simulation and network forking require v8.1.0+ with transaction simulation session support; live mode only requires a CLI that supports the live command being executed. Forklift invokes `movement` by default; set `FORKLIFT_CLI_BINARY=/path/to/movement` to use a specific CLI build.

## Quick Start

Expand All @@ -40,7 +40,7 @@ harness.cleanup();

## Documentation

For full documentation, API reference, and examples, see the [GitHub repository](https://github.com/aptos-labs/forklift).
For full documentation, API reference, and examples, see the [GitHub repository](https://github.com/MoveIndustries/forklift).

## License

Expand Down
8 changes: 4 additions & 4 deletions packages/forklift/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -28,12 +28,12 @@
"license": "Apache-2.0",
"repository": {
"type": "git",
"url": "git+https://github.com/aptos-labs/forklift.git",
"url": "git+https://github.com/MoveIndustries/forklift.git",
"directory": "packages/forklift"
},
"homepage": "https://github.com/aptos-labs/forklift#readme",
"homepage": "https://github.com/MoveIndustries/forklift#readme",
"bugs": {
"url": "https://github.com/aptos-labs/forklift/issues"
"url": "https://github.com/MoveIndustries/forklift/issues"
},
"engines": {
"node": ">=18"
Expand All @@ -53,4 +53,4 @@
"smol-toml": "^1.6.0",
"sync-fetch": "^0.6.0"
}
}
}
Loading