SDK

Drive your Stagenet from TypeScript — mint balances, override state, impersonate accounts, and apply function overrides from your scripts, tests, and deploy pipelines.

Just running ad-hoc commands from your terminal? See the CLI instead.

Topics

• Quickstart — create a Stagenet instance and run your first SDK call.
• Balances — mint native tokens and ERC20s.
• State — set balances, storage, code, and nonces.
• Impersonation — send transactions as any address.
• Function overrides — intercept contract reads and return whatever you want.
• State tracking — record on-chain data over time.

Install

The contract.dev npm package contains both the CLI and the SDK.

npm install contract.dev

Setup

Create a contract.dev.js file in your project root:

npx contract.dev init

Get your Stagenet’s RPC URL from your project dashboard and add it:

/** @type {import('contract.dev').Config} */
module.exports = {
  rpcUrl: "<YOUR_STAGENET_RPC_URL>",
};

Use contract.dev.cjs instead if your package.json has "type": "module".

Run your first SDK call

Create a Stagenet instance using your Stagenet’s RPC URL:

import { createStagenet } from "contract.dev";
 
const stagenet = createStagenet("<YOUR_STAGENET_RPC_URL>");
 
const alice = "0x1111111111111111111111111111111111111111";
 
await stagenet.addBalance(alice, 10n ** 18n);
await stagenet.setNonce(alice, 42);