Aztec Sandbox Environment
Relevant source files
The following files were used as context for generating this wiki page:
The Aztec Sandbox Environment is a local development and testing infrastructure used to simulate the Aztec Network. It allows developers to deploy, interact with, and test privacy-preserving smart contracts (Noir contracts) in a controlled, local setting before deploying to live networks. This environment is essential for validating the logic of standards such as the Token Contract, NFT Contract, and Escrow Standard.
The sandbox is integrated into the project's testing suite via Vitest, ensuring that a fresh instance is available for running integration tests and benchmarks. It provides a local endpoint (typically on port 8080) that provides access to an Aztec Node and a Private eXecution Environment (PXE).
Sources: README.md:1-45, vitest.setup.ts:7-10, scripts/start-sandbox.ts:25-30
Lifecycle Management
The sandbox lifecycle is automated through TypeScript scripts that handle the spawning, readiness checking, and termination of the Aztec process.
Startup and Readiness Verification
The sandbox is initiated by spawning the aztec CLI process with the start --sandbox flags. To ensure the environment is fully operational before tests begin, the system performs a series of connection retries to the sandbox URL.
The readiness check utilizes the createAztecNodeClient to attempt a getNodeInfo() call. If this call succeeds, the sandbox is considered ready for deployment and testing.
Sources: scripts/start-sandbox.ts:13-40, vitest.setup.ts:10-12
Shutdown Procedure
Upon completion of the test suite, the sandbox is stopped using a coordinated signal strategy. It first attempts a SIGTERM for a graceful exit and falls back to SIGKILL if the process remains active after a 5-second timeout.
Sources: scripts/start-sandbox.ts:46-64, vitest.setup.ts:14-17
Architecture and Components
The sandbox environment provides the necessary backend services for the @aztec/aztec.js library to interact with the simulated network.
| Component | Description | Reference |
|---|---|---|
| Aztec CLI | The command-line tool used to launch the sandbox instance. | scripts/start-sandbox.ts |
| Aztec Node | Simulates the rollup and state management of the Aztec network. | src/ts/test/utils.ts |
| PXE | Private eXecution Environment; handles private state and note management. | src/ts/test/utils.ts |
| Sandbox URL | The local endpoint (default: http://localhost:8080) for API communication. | scripts/start-sandbox.ts |
Testing Integration
The sandbox is heavily utilized within the setupTestSuite utility, which configures the local network and registers initial accounts for testing purposes.
Configuration and Defaults
The environment relies on specific configuration constants and environment variables to manage connectivity and timing.
| Parameter | Default Value | Description |
|---|---|---|
SANDBOX_URL | http://localhost:8080 | The primary endpoint for node communication. |
MAX_WAIT_TIME | 180000 (3 mins) | The maximum time allowed for the sandbox to become ready. |
RETRY_DELAY | 3000 (3 secs) | Interval between connectivity checks during startup. |
NODE_URL | process.env.NODE_URL | Environment variable that can override the sandbox endpoint. |
Sources: scripts/start-sandbox.ts:5-8, src/ts/test/utils.ts:47
Account Management
The sandbox provides a set of pre-funded accounts upon startup. These are registered into a TestWallet during the setup phase of the test suite. This allows developers to simulate multiple participants (e.g., Alice, Bob, Carl) for complex private transactions.
Sources: src/ts/test/utils.ts:74-76, src/ts/test/token.test.ts:31-35
Usage in Development
The project defines several npm scripts in package.json that interact with the sandbox or prepare contracts for it:
yarn test:js: Runs Vitest, which triggers the global setup invitest.setup.tsto start the sandbox.yarn test:nr: Uses theaztec testcommand, which may interact with a running sandbox or internal simulator.yarn compile: Compiles Noir contracts into artifacts compatible with the sandbox.yarn codegen: Generates TypeScript classes from contract artifacts for use with the sandbox node client.
Sources: package.json:17-27, vitest.setup.ts:1-20
Conclusion
The Aztec Sandbox Environment is the cornerstone of the Aztec Standards project's quality assurance process. By automating the deployment of a local node and integrating it directly into the Vitest workflow, the project ensures that all standardized contracts—including tokens, NFTs, and vaults—are rigorously tested against a realistic simulation of the Aztec Network's private and public execution layers.