glassbox-sdk

Capture, seal, anchor & verify AI agent reasoning on Solana.

Every decision an AI agent makes — every inference, tool call, retrieval and decision — is captured as a ReasoningStep, sealed into a SHA-256 Merkle tree, and the root is anchored on Solana mainnet via the SPL Memo program. The full trace lives off-chain; anyone can recompute the root byte-for-byte and check it against the on-chain anchor. Opaque agents become transparent, tamper-evident systems.

npm install glassbox-sdk

Quickstart

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

Try it without writing code:

npx glassbox demo        # seal → anchor → verify
# set SOLANA_SECRET_KEY for a real mainnet anchor transaction

Real on Solana mainnet

With a funded Solana keypair the SDK builds an SPL Memo instruction carrying glassbox|v1|anchor|<taskId>|<merkleRoot>, signs it, broadcasts it to mainnet-beta, confirms it, and returns the transaction signature and slot. The Merkle root is permanently recorded in the immutable ledger and is independently verifiable forever. Without a key, traces are sealed and verified locally.

Instrument any framework

trace.track() wraps any async operation as a step — timing and ok/error are captured automatically. No framework lock-in.

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

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

// fully local — recompute the tree, compare to the anchor, no network
const result = glass.verifyTrace(trace);
result.match;        // true → computed root === anchored root
result.steps;        // per-step leaf recomputation

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

API

| Method | Description | |---|---| | new GlassBox(opts) | solana?, inference?, agent?, apiUrl?, storage? | | glass.startTrace(taskId, meta?) | begin a Trace | | trace.retrieval / toolCall / observation / decision / delegation | typed steps | | trace.track(type, label, fn, attrs?) | instrument any async op | | trace.infer(label, input) | run the configured model, log an INFERENCE step | | trace.seal() | assemble the Merkle tree → root | | trace.anchor({ onChain? }) | anchor the root (real mainnet tx with a keypair) | | glass.verifyTrace(trace) | recompute + compare locally | | glass.proveStep(trace, i) | Merkle inclusion proof for one step |

Step taxonomy

INFERENCE · TOOL_CALL · RETRIEVAL · DECISION · OBSERVATION · DELEGATION

Links

• Live: https://glassboxsol.xyz
• Source: https://github.com/960/glassbox-protocol

License

MIT