NEAR Integration
SandboxManager, NearDevnetClient, contract deployment, and relayer mode
SandboxManager
SandboxManager handles the full lifecycle of a local NEAR Sandbox instance: downloading the binary, starting the process, and exposing the RPC endpoint for contract interactions.
Download Binary
Checks if near-sandbox exists in the local cache directory. If not, downloads the platform-specific binary from the NEAR releases page. Verifies checksum and sets executable permissions.
Initialize Genesis
Runs near-sandbox init to create the genesis configuration. Sets up the root account (test.near) with initial balance and configures block production parameters.
Start Process
Spawns the sandbox process with the configured home directory. Listens on 127.0.0.1:3030 for JSON-RPC requests. Stdout/stderr captured to log files.
Wait for Ready
Polls the /status endpoint until the sandbox responds with a valid block height. Timeout configurable, defaults to 30 seconds.
Shutdown
Sends SIGTERM to the sandbox process. Waits for graceful shutdown, then SIGKILL if needed. Cleans up data directory if preserve_data is not set.
NearDevnetClient
The NearDevnetClient wraps py-near to provide high-level account and contract operations against the local sandbox.
Account Operations
create_account
Creates a new named account under the root account (e.g. alice.test.near). Generates a new key pair and funds the account from root.
create_key
Generates and adds a new access key for an existing account. Supports full-access and function-call-only key types.
delete_account
Deletes an account and transfers remaining balance to a beneficiary account.
view_account
Queries account state: balance, storage usage, code hash, and nonce.
Contract Operations
deploy_contract
Deploys a WASM binary to a target account. The contract bytes are sent as a DeployContract action in a transaction.
call_function
Calls a method on a deployed contract. Supports both view (read-only, no gas) and change (mutating, requires gas and deposit) calls.
view_state
Reads raw key-value state from a contract’s storage trie with optional prefix filtering.
send_tokens
Transfers NEAR tokens between accounts. Used for funding test accounts during E2E setup.
Contract Resolution
merobox resolves contract binaries from multiple sources before deployment.
The workflow YAML specifies contracts via contract_path (local file) or contract_url (remote download). After resolution, the WASM binary is deployed to a dedicated account on the sandbox.
Relayer Mode vs Local Sandbox
merobox supports two modes for NEAR integration, depending on the target environment.
Local Sandbox (default)
- Downloads and runs near-sandbox locally
- Fully isolated from public NEAR networks
- Fast block production (~1 second)
- Unlimited test tokens for account funding
- No gas fees, no external dependencies
- Data is ephemeral (wiped on nuke)
E2E testing
Relayer Mode
- Connects to an existing NEAR network (testnet/mainnet)
- Uses a relayer account for meta-transactions
- Real network conditions and gas costs
- Requires funded accounts and access keys
- Persistent state across runs
- Configured via workflow YAML near.relayer section
staging
Sandbox Integration Flow
How the NEAR sandbox integrates with the workflow execution pipeline.