@saw-protocol/sandbox

The foundational Sandbox execution environment for the SAWP Protocol.

This module acts as the second, strict structural line of defense. While the Policy Engine evaluates financial intent dynamically, the Sandbox enforces hard process-level limits (like execution CPU timeouts, memory scope bounding, and explicit infrastructure freezing) ensuring that malicious agents cannot perform Denial of Service attacks or bypass JS-execution safety boundaries.

Installation

npm install @saw-protocol/sandbox

Example Usage

import { NodeSandbox } from "@saw-protocol/sandbox";
import { PublicKey } from "@solana/web3.js";

import { IStorageProvider } from "@saw-protocol/core";

// By default, it operates completely in-memory
// You can pass an explicit persistent storage (e.g. Redis, MongoDB) injected via IStorageProvider!
const mockStorage: IStorageProvider = {
  get: async (key: string) => null,
  set: async (key: string, value: any) => {},
  delete: async (key: string) => {},
};

const sandbox = new NodeSandbox(mockStorage);
const agentId = "did:sol:agentXYZ";

// Bind explicit structural process profile limits for this Agent
await sandbox.bindProfile(agentId, {
  maxConcurrentTransactions: 1,
  networkScope: "devnet",
  allowedProgramIds: [],
  blockedProgramIds: [],
  maxSOLBalance: 10,
  maxSingleTxValue: 5,
  externalCallTimeout: 2000, // Hard stop after 2 seconds
  memoryScope: "isolated",
  canDelegate: true,
  canAcceptDelegation: true,
});

// Example long running malicious attack action
const slowAction = async () => {
  return new Promise((resolve) => setTimeout(resolve, 5000));
};

// The Sandbox transparently executes it, catches the infrastructure timeout, and returns a SandboxViolation Instead
const result = await sandbox.execute(slowAction, {
  agentId,
  walletAddress: new PublicKey("..."),
});

if ("boundaryExceeded" in result) {
  console.log("Violated rules:", result.boundaryExceeded); // "Execution exceeded limit of 2000ms"

  // We can structurally freeze the agent entirely!
  await sandbox.freeze(agentId);
}