GlassBox Protocol

Documentation

Integrate verifiable reasoning in minutes

GlassBox is infrastructure, not an application — a protocol-level primitive any agent framework adopts via a lightweight SDK. Everything below actually runs in this repo.

Install the SDK

install

npm install glassbox-sdk
# or:  pnpm add glassbox-sdk   ·   yarn add glassbox-sdk

The SDK records every tool call, inference, retrieval and decision as a ReasoningStep, assembles a real SHA-256 Merkle tree on seal(), and anchors the root via anchor().

agent.ts

import { GlassBox } from 'glassbox-sdk';

const glass = new GlassBox({
  // a funded Solana keypair enables REAL mainnet anchoring
  solana: { secretKey: process.env.SOLANA_SECRET_KEY },
  agent: { name: 'Helios Vault Keeper' },
});

// 1. Capture a reasoning process
const trace = glass.startTrace('swap-analysis-001', {
  title: 'Evaluate SOL/USDC rebalance',
  category: 'DeFi',
});

trace.retrieval('Fetch SOL/USDC orderbook', { attributes: { source: 'jupiter-api' } });
trace.observation('Detect pool imbalance', { output: { skew: 0.023 } });
trace.decision('Select route', { action: 'swap', confidence: 0.87 });

// 2. Seal → SHA-256 Merkle root, 3. Anchor → real SPL Memo tx on Solana
const { merkleRoot } = await trace.seal();
const { signature, onChain } = await trace.anchor();

// 4. Verify — recompute the tree locally and compare to the anchor
const result = glass.verifyTrace(trace);   // result.match === true

Run it end-to-end

npx glassbox demo runs a full seal → anchor → verify cycle. Without a key it anchors locally; with a funded SOLANA_SECRET_KEY it signs and broadcasts a real SPL Memo transaction on mainnet.

quickstart

npm install glassbox-sdk

# run a full seal → anchor → verify cycle
npx glassbox demo

# set a funded key for a REAL Solana mainnet anchor transaction
export SOLANA_SECRET_KEY=<base58 secret>
npx glassbox demo

…or anchor one from the browser

Works with any framework

Instrument your existing calls with trace.track() and trace.infer() — no changes to your agent logic, no framework lock-in.

ElizaOSLangChainCrewAIGOATVercel AI SDKCustom

instrument.ts

// Adapt GlassBox to ANY framework by instrumenting its calls.
// trace.track() wraps any async op and logs timing + ok/error automatically.

const orderbook = await trace.track('TOOL_CALL', 'Jupiter quote', () =>
  jupiter.quote({ inputMint, outputMint, amount }),       // your existing tool
);

const docs = await trace.track('RETRIEVAL', 'Vector search', () =>
  retriever.getRelevantDocuments(query),                  // e.g. a LangChain retriever
);

// bring your own model — logged as an INFERENCE step
const glass = new GlassBox({
  inference: async ({ prompt }) => ({ text: await myModel(prompt) }),
});

Verification API

Verification is permissionless. Any party fetches the on-chain anchor, retrieves the off-chain trace, rebuilds the Merkle tree, and checks it against the recorded root.

verify.ts

// Permissionless & fully local — recompute the tree, compare to the anchor
const result = glass.verifyTrace(trace);

result.match;         // true  → computed root === anchored root
result.computedRoot;  // rebuilt locally from the off-chain trace
result.steps;         // per-step leaf-hash recomputation

// single-step Merkle inclusion proof (no full trace needed)
const proof = glass.proveStep(trace, 2);
proof.valid;          // true

Try it live in the Explorer

Reasoning step taxonomy

A standardized taxonomy ensures cross-framework interoperability — any verifier reads any agent’s reasoning the same way.

Type	Description
INFERENCE	LLM call producing a completion
TOOL_CALL	External tool invocation
RETRIEVAL	Data fetch from an external source
DECISION	Agent selects an action
OBSERVATION	Agent processes environment state
DELEGATION	Agent delegates to a sub-agent