NEAR Sandbox (JS and TS Edition)

JavaScript and TypeScript library for running a local NEAR node for development and testing.

Release Notes

Release notes and unreleased changes can be found in the CHANGELOG.

What is NEAR Sandbox?

NEAR Sandbox is a custom build of the NEAR blockchain optimized for local development and testing.
If you're familiar with Ganache for Ethereum, this tool serves a similar purpose for NEAR.

This library provides a simple JavaScript API to quickly download, start, and configure your local NEAR Sandbox instance. The binary is automatically managed and launched for you.

Installation

Install the package globally or as a development dependency:

Using npm:

pnpm install --save-dev near-sandbox

Simple Testing Example

Here's an example of how you might use NEAR Sandbox in a test with async/await:

const { Sandbox } = require("near-sandbox");

(async () => {
  // Start a sandbox instance with default configuration.
  const sandbox = await Sandbox.start({});
  try {
    // Your test code here.
    // You can interact with the sandbox via its RPC `sandbox.rpc` etc.
    console.log(`Sandbox RPC available at: ${sandbox.rpcUrl}`);
  } catch (error) {
    console.error("Error during execution:", error);
  } finally {
    // Stop the sandbox and clean up any files that were created. Note, if you want to persist the sandbox network state and just stop the node, use `stop()` method.
    await sandbox.tearDown();
  }
})();

You can find more and detailed examples in examples

Features

• Easy sandbox startup: Start a local NEAR node with Sandbox.start({}).
• Version selection: Download and run a specific NEAR Sandbox version.
• Custom configuration: Adjust settings such as genesis parameters or network configurations. Add your own accounts as TLA to node.
• Automatic binary management: Automatically downloads and manages the NEAR Sandbox binary if not already present.
• RPC access: Access the sandbox node's RPC endpoint for interacting with your local network.
• Environment variable configuration: Customize binary source, timeouts, and more through environment variables.
• Dumping: dump() the entire chain that return all config files(genesis, config, node_key, validator_key as Records). Genesis and key files can be used to start sandbox as params to run prepared state.

Starting a Sandbox

You can start a sandbox with default settings:

const { Sandbox } = require("near-sandbox");

(async () => {
  const sandbox = await Sandbox.start({});
  // Use sandbox.rpc to interact with the local NEAR node.
  await sandbox.tearDown();
})();

Or, you can specify a particular version:

const { Sandbox } = require("near-sandbox");

(async () => {
  const sandbox = await Sandbox.start({ version: "2.6.3" });
  // Use `sandbox.rpc` for your further interactions.
  await sandbox.tearDown();
})();

Or configure the sandbox with custom settings:

const { Sandbox } = require("near-sandbox");

(async () => {
  // Define your custom configuration here with interface `SandboxConfig`
  const config = {
    rpcPort: rpcPort,
  };
  const sandbox = await Sandbox.start({ config: config });

  await sandbox.tearDown();
})();

CLI using

• Initialize the Sandbox node

  near-sandbox --home /tmp/near-sandbox init
  

• Run it

  near-sandbox --home /tmp/near-sandbox run
  

  by default it is running on http:/127.0.0.1:3030

• Stop the sandox node. Once you're finished using the sandbox node you can stop it by using CtrlC. To clean up the data it generates:

  rm -rf /tmp/near-sandbox
  

To find out other things you can do:

near-sandbox --help

Automatic Binary Management

• On sandbox startup, the appropriate binary for your platform is automatically downloaded if not found locally.
• It will be saved in bin directory inside package (usually located inside node_modules folder of the project).
• The sandbox process runs in the background, and can be terminated by calling stop() or tearDown() methods.

Environment Variables

Customize sandbox behavior using the following environment variables:

• SANDBOX_ARTIFACT_URL: Specify an alternative URL for downloading the near-sandbox binary.
• NEAR_SANDBOX_BIN_PATH: Use a custom-built near-sandbox binary instead of the default.
• DIR_TO_DOWNLOAD_BINARY: Specify direction where you want save Binary. The default is /bin within the package
• NEAR_RPC_TIMEOUT_SECS: Set the timeout (in seconds) for waiting for the sandbox to start (default: 10).
• NEAR_ENABLE_SANDBOX_LOG: Set to 1 to enable sandbox logging of near-sandbox (helpful for debugging).