silo-agent 1.0.0

package/build/lib/shared-memory.js

@@ -0,0 +1,398 @@
+/**
+ * SILO — Shared Memory Bus
+ *
+ * Named channels backed by 0G Storage for real-time multi-agent communication.
+ *
+ * Design:
+ *   - Each channel is a linked list of entries on 0G (each entry points to the previous via rootHash)
+ *   - A coordinator layer provides channel locks and optimistic concurrency control
+ *   - A memory index provides root hash discoverability (search by label, tag, channel, author)
+ *   - Periodic snapshots persist the full channel state to 0G for crash recovery
+ *   - Any agent can create, join, write to, or read from a channel
+ *
+ * Safe Write Protocol (when coordinator is attached):
+ *   1. acquireLock(channel) → lockToken
+ *   2. Read current head → {headRootHash, version}
+ *   3. Upload to 0G with prevRootHash = headRootHash
+ *   4. commitWrite(channel, newRootHash, version, lockToken)
+ *   5. Coordinator validates → updates head → releases lock → broadcasts
+ *
+ * Without coordinator, writes are best-effort (backward compatible with v1).
+ */
+import { MemoryIndex } from "./memory-index.js";
+import { createHash } from "node:crypto";
+const DEFAULT_CONFIG = {
+    snapshotThreshold: 10,
+    useCoordinator: true,
+    maxWriteRetries: 3,
+};
+export class SharedMemoryBus {
+    vault;
+    coordinator = null;
+    index;
+    channels = new Map();
+    entries = new Map();
+    subscriptions = new Map();
+    config;
+    agentId;
+    onBroadcast;
+    constructor(vault, config = {}) {
+        this.vault = vault;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.agentId = vault.address;
+        this.index = new MemoryIndex();
+    }
+    /** Attach a coordinator for multi-agent safety (run on the API server) */
+    attachCoordinator(coordinator) {
+        this.coordinator = coordinator;
+    }
+    /** Get the memory index (for search, lookup, stats) */
+    getIndex() { return this.index; }
+    /** Get the coordinator (if attached) */
+    getCoordinator() { return this.coordinator; }
+    /** Register a broadcast handler (e.g., Socket.IO emitter) for cross-process notifications */
+    setBroadcastHandler(handler) {
+        this.onBroadcast = handler;
+    }
+    /**
+     * Create a new named channel with optional schema.
+     * If the channel already exists, returns the existing manifest.
+     */
+    createChannel(name, schema) {
+        if (this.channels.has(name)) {
+            const existing = this.channels.get(name);
+            if (schema && !existing.schema)
+                existing.schema = schema;
+            return existing;
+        }
+        const manifest = {
+            name,
+            createdAt: Date.now(),
+            createdBy: this.agentId,
+            headRootHash: null,
+            version: 0,
+            entryCount: 0,
+            subscribers: [this.agentId],
+            snapshotRootHash: null,
+            lastSnapshotAt: null,
+            schema,
+        };
+        this.channels.set(name, manifest);
+        this.entries.set(name, []);
+        this.subscriptions.set(name, []);
+        this.coordinator?.ensureChannel(name);
+        return manifest;
+    }
+    /** Subscribe to a channel. Callback fires on every new entry. */
+    subscribe(channel, callback) {
+        if (!this.channels.has(channel)) {
+            this.createChannel(channel);
+        }
+        const manifest = this.channels.get(channel);
+        if (!manifest.subscribers.includes(this.agentId)) {
+            manifest.subscribers.push(this.agentId);
+        }
+        const subscription = {
+            channel,
+            agentId: this.agentId,
+            callback,
+        };
+        this.subscriptions.get(channel).push(subscription);
+        return subscription;
+    }
+    /** Unsubscribe from a channel */
+    unsubscribe(subscription) {
+        const subs = this.subscriptions.get(subscription.channel);
+        if (!subs)
+            return;
+        const idx = subs.indexOf(subscription);
+        if (idx !== -1)
+            subs.splice(idx, 1);
+    }
+    /**
+     * Write data to a channel with coordination.
+     *
+     * When a coordinator is attached:
+     *   1. Acquires channel lock
+     *   2. Reads current head + version
+     *   3. Uploads to 0G with correct prevRootHash
+     *   4. Commits via coordinator (validates version)
+     *   5. Retries on conflict up to maxWriteRetries
+     *
+     * Without coordinator: best-effort write (v1 behavior).
+     */
+    async write(channel, data, metadata) {
+        if (!this.channels.has(channel)) {
+            this.createChannel(channel);
+        }
+        if (this.coordinator && this.config.useCoordinator) {
+            return this.coordinatedWrite(channel, data, metadata);
+        }
+        return this.uncoordinatedWrite(channel, data, metadata);
+    }
+    /**
+     * Safe write with full coordination — locks, version checks, conflict retry.
+     */
+    async coordinatedWrite(channel, data, metadata) {
+        const coordinator = this.coordinator;
+        let lastError;
+        for (let attempt = 0; attempt < this.config.maxWriteRetries; attempt++) {
+            const beginResult = coordinator.beginWrite(channel, this.agentId);
+            if ("code" in beginResult) {
+                if (attempt < this.config.maxWriteRetries - 1) {
+                    await sleep(100 * Math.pow(2, attempt));
+                    continue;
+                }
+                throw new Error(`Failed to acquire lock on "${channel}": ${beginResult.message}`);
+            }
+            const { head, lock } = beginResult;
+            try {
+                const envelope = JSON.stringify({
+                    channel,
+                    data,
+                    prevRootHash: head.headRootHash,
+                    version: head.version,
+                    authorId: this.agentId,
+                    timestamp: Date.now(),
+                    metadata,
+                });
+                const result = await this.vault.store(envelope, `shm:${channel}`);
+                const commitResult = coordinator.commitWrite(channel, result.rootHash, head.headRootHash, head.version, this.agentId, lock.token);
+                if ("code" in commitResult) {
+                    lastError = new Error(commitResult.message);
+                    continue;
+                }
+                const entry = {
+                    id: createHash("sha256").update(`${channel}:${result.rootHash}`).digest("hex").slice(0, 16),
+                    channel,
+                    authorId: this.agentId,
+                    timestamp: Date.now(),
+                    data,
+                    rootHash: result.rootHash,
+                    prevRootHash: head.headRootHash,
+                    contentHash: result.contentHash,
+                    version: commitResult.version,
+                    metadata,
+                };
+                const manifest = this.channels.get(channel);
+                manifest.headRootHash = result.rootHash;
+                manifest.version = commitResult.version;
+                manifest.entryCount++;
+                this.entries.get(channel).push(entry);
+                this.registerInIndex(entry, result);
+                this.notifySubscribers(channel, entry);
+                if (manifest.entryCount % this.config.snapshotThreshold === 0) {
+                    await this.snapshot(channel);
+                }
+                return entry;
+            }
+            catch (err) {
+                coordinator.releaseLock(channel, lock.token);
+                lastError = err;
+                if (attempt < this.config.maxWriteRetries - 1) {
+                    await sleep(100 * Math.pow(2, attempt));
+                }
+            }
+        }
+        throw lastError ?? new Error(`Coordinated write to "${channel}" failed after ${this.config.maxWriteRetries} attempts`);
+    }
+    /** Best-effort write without coordination (backward compatible) */
+    async uncoordinatedWrite(channel, data, metadata) {
+        const manifest = this.channels.get(channel);
+        const prevRootHash = manifest.headRootHash;
+        const envelope = JSON.stringify({
+            channel,
+            data,
+            prevRootHash,
+            version: manifest.version,
+            authorId: this.agentId,
+            timestamp: Date.now(),
+            metadata,
+        });
+        const result = await this.vault.store(envelope, `shm:${channel}`);
+        const entry = {
+            id: createHash("sha256").update(`${channel}:${result.rootHash}`).digest("hex").slice(0, 16),
+            channel,
+            authorId: this.agentId,
+            timestamp: Date.now(),
+            data,
+            rootHash: result.rootHash,
+            prevRootHash,
+            contentHash: result.contentHash,
+            version: ++manifest.version,
+            metadata,
+        };
+        manifest.headRootHash = result.rootHash;
+        manifest.entryCount++;
+        this.entries.get(channel).push(entry);
+        this.registerInIndex(entry, result);
+        this.notifySubscribers(channel, entry);
+        if (manifest.entryCount % this.config.snapshotThreshold === 0) {
+            await this.snapshot(channel);
+        }
+        return entry;
+    }
+    registerInIndex(entry, storeResult) {
+        const tags = [entry.channel, "shared_memory"];
+        if (entry.metadata?.tags)
+            tags.push(...entry.metadata.tags);
+        this.index.register({
+            rootHash: entry.rootHash,
+            label: entry.metadata?.label ?? `shm:${entry.channel}`,
+            tags,
+            channel: entry.channel,
+            authorId: entry.authorId,
+            contentType: "shared_memory",
+            size: storeResult.size,
+            createdAt: entry.timestamp,
+            contentHash: entry.contentHash,
+            metadata: entry.metadata,
+        });
+    }
+    notifySubscribers(channel, entry) {
+        const subs = this.subscriptions.get(channel) ?? [];
+        for (const sub of subs) {
+            try {
+                sub.callback(entry);
+            }
+            catch { }
+        }
+        this.onBroadcast?.(channel, entry);
+    }
+    /**
+     * Read the latest N entries from a channel (from local cache).
+     * For full history recovery from 0G, use `recoverChannel()`.
+     */
+    read(channel, limit = 50) {
+        const entries = this.entries.get(channel) ?? [];
+        return entries.slice(-limit);
+    }
+    /** Read a specific entry from 0G by its root hash */
+    async readFromStorage(rootHash) {
+        const raw = await this.vault.retrieve(rootHash, "shm:read");
+        const envelope = JSON.parse(raw);
+        return {
+            data: envelope.data,
+            prevRootHash: envelope.prevRootHash,
+        };
+    }
+    /**
+     * Search the memory index. Agents use this to discover root hashes
+     * without knowing them in advance.
+     */
+    search(query) {
+        return this.index.search(query);
+    }
+    /** Look up what a specific root hash contains */
+    lookupRootHash(rootHash) {
+        return this.index.lookup(rootHash);
+    }
+    /**
+     * Persist the full channel state as a snapshot on 0G.
+     */
+    async snapshot(channel) {
+        const manifest = this.channels.get(channel);
+        if (!manifest)
+            throw new Error(`Channel "${channel}" not found`);
+        const entries = this.entries.get(channel) ?? [];
+        const snapshotData = JSON.stringify({
+            manifest,
+            entries: entries.map(e => ({
+                id: e.id,
+                rootHash: e.rootHash,
+                prevRootHash: e.prevRootHash,
+                authorId: e.authorId,
+                timestamp: e.timestamp,
+                contentHash: e.contentHash,
+                version: e.version,
+                metadata: e.metadata,
+            })),
+            snapshotAt: Date.now(),
+        });
+        const result = await this.vault.store(snapshotData, `shm:snapshot:${channel}`);
+        manifest.snapshotRootHash = result.rootHash;
+        manifest.lastSnapshotAt = Date.now();
+        this.index.register({
+            rootHash: result.rootHash,
+            label: `snapshot:${channel}`,
+            tags: [channel, "snapshot"],
+            channel,
+            authorId: this.agentId,
+            contentType: "snapshot",
+            size: result.size,
+            createdAt: Date.now(),
+            contentHash: result.contentHash,
+        });
+        return result.rootHash;
+    }
+    /**
+     * Recover a channel by walking the linked list from a known head root hash.
+     */
+    async recoverChannel(channel, headRootHash, maxDepth = 100) {
+        const recovered = [];
+        let currentHash = headRootHash;
+        let depth = 0;
+        while (currentHash && depth < maxDepth) {
+            const { data, prevRootHash } = await this.readFromStorage(currentHash);
+            recovered.unshift({
+                id: createHash("sha256").update(`${channel}:${currentHash}`).digest("hex").slice(0, 16),
+                channel,
+                authorId: "recovered",
+                timestamp: Date.now(),
+                data,
+                rootHash: currentHash,
+                prevRootHash,
+                contentHash: createHash("sha256").update(data).digest("hex"),
+                version: depth,
+            });
+            currentHash = prevRootHash;
+            depth++;
+        }
+        if (!this.channels.has(channel)) {
+            this.createChannel(channel);
+        }
+        this.entries.set(channel, recovered);
+        const manifest = this.channels.get(channel);
+        manifest.headRootHash = headRootHash;
+        manifest.entryCount = recovered.length;
+        manifest.version = recovered.length;
+        return recovered;
+    }
+    /**
+     * Ingest an entry from another agent (received via WebSocket broadcast).
+     * Keeps the local cache in sync without re-downloading from 0G.
+     */
+    ingestRemoteEntry(entry) {
+        if (!this.channels.has(entry.channel)) {
+            this.createChannel(entry.channel);
+        }
+        const entries = this.entries.get(entry.channel);
+        if (entries.some(e => e.rootHash === entry.rootHash))
+            return;
+        entries.push(entry);
+        const manifest = this.channels.get(entry.channel);
+        manifest.headRootHash = entry.rootHash;
+        manifest.entryCount = entries.length;
+        if (entry.version > manifest.version)
+            manifest.version = entry.version;
+        const subs = this.subscriptions.get(entry.channel) ?? [];
+        for (const sub of subs) {
+            try {
+                sub.callback(entry);
+            }
+            catch { }
+        }
+    }
+    /** List all known channels */
+    listChannels() {
+        return Array.from(this.channels.values());
+    }
+    /** Get a channel's manifest */
+    getChannel(name) {
+        return this.channels.get(name);
+    }
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=shared-memory.js.map

package/build/lib/shared-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-memory.js","sourceRoot":"","sources":["../../src/lib/shared-memory.ts"],"names":[],"mappings":"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"}

package/build/lib/storage.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 0G Agent Shield — Storage Layer
+ *
+ * Wraps @0glabs/0g-ts-sdk to provide a simple string-in/string-out interface.
+ * The SDK requires file paths, so we handle temp file lifecycle internally.
+ *
+ * IMPORTANT API notes (from the actual SDK docs):
+ *   - indexer.upload(file, evmRpc, signer)  ← evmRpc is 2nd arg, NOT signer alone
+ *   - file.merkleTree() returns [tree, err] ← destructure the tuple
+ *   - indexer.download(rootHash, outPath, withProof)
+ *   - file.close() must be called after merkleTree()
+ */
+export interface UploadResult {
+    rootHash: string;
+    txHash: string;
+    size: number;
+    timestamp: number;
+}
+export declare class StorageClient {
+    private indexer;
+    private signer;
+    private provider;
+    private evmRpc;
+    constructor(privateKey: string, evmRpc: string, indexerRpc: string);
+    get address(): string;
+    getBalance(): Promise<string>;
+    /**
+     * Upload a string to 0G Storage.
+     *
+     * Flow: write temp file → create ZgFile → get merkle tree for root hash
+     *       → upload via indexer → cleanup temp file
+     */
+    upload(data: string): Promise<UploadResult>;
+    /**
+     * Download a file from 0G Storage by its root hash.
+     */
+    download(rootHash: string): Promise<string>;
+}

package/build/lib/storage.js

@@ -0,0 +1,106 @@
+/**
+ * 0G Agent Shield — Storage Layer
+ *
+ * Wraps @0glabs/0g-ts-sdk to provide a simple string-in/string-out interface.
+ * The SDK requires file paths, so we handle temp file lifecycle internally.
+ *
+ * IMPORTANT API notes (from the actual SDK docs):
+ *   - indexer.upload(file, evmRpc, signer)  ← evmRpc is 2nd arg, NOT signer alone
+ *   - file.merkleTree() returns [tree, err] ← destructure the tuple
+ *   - indexer.download(rootHash, outPath, withProof)
+ *   - file.close() must be called after merkleTree()
+ */
+import { Indexer, ZgFile } from "@0glabs/0g-ts-sdk";
+import { ethers } from "ethers";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+export class StorageClient {
+    indexer;
+    signer;
+    provider;
+    evmRpc;
+    constructor(privateKey, evmRpc, indexerRpc) {
+        this.evmRpc = evmRpc;
+        this.provider = new ethers.JsonRpcProvider(evmRpc);
+        this.signer = new ethers.Wallet(privateKey, this.provider);
+        this.indexer = new Indexer(indexerRpc);
+    }
+    get address() {
+        return this.signer.address;
+    }
+    async getBalance() {
+        const balance = await this.provider.getBalance(this.signer.address);
+        return ethers.formatEther(balance);
+    }
+    /**
+     * Upload a string to 0G Storage.
+     *
+     * Flow: write temp file → create ZgFile → get merkle tree for root hash
+     *       → upload via indexer → cleanup temp file
+     */
+    async upload(data) {
+        const tmpPath = path.join(os.tmpdir(), `0g-shield-${Date.now()}-${Math.random().toString(36).slice(2)}.dat`);
+        const dataBytes = Buffer.from(data, "utf-8");
+        await fs.writeFile(tmpPath, dataBytes);
+        let file = null;
+        try {
+            file = await ZgFile.fromFilePath(tmpPath);
+            // 0G TS SDK uses the old testnet ABI, but Galileo testnet upgraded to require a submitter address.
+            // We wrap the signer in a Proxy to intercept and automatically upgrade the transaction payload.
+            const newAbi = ['function submit(tuple(tuple(uint256 length, bytes tags, tuple(bytes32 root, uint256 height)[] nodes) data, address submitter) submission) payable'];
+            const oldAbi = ['function submit(tuple(uint256 length, bytes tags, tuple(bytes32 root, uint256 height)[] nodes) submission) payable'];
+            const newIface = new ethers.Interface(newAbi);
+            const oldIface = new ethers.Interface(oldAbi);
+            const proxySigner = new Proxy(this.signer, {
+                get(target, prop) {
+                    if (prop === 'sendTransaction' || prop === 'estimateGas') {
+                        return async function (tx) {
+                            if (tx.data && tx.data.startsWith('0xef3e12dc')) {
+                                const decoded = oldIface.decodeFunctionData('submit', tx.data);
+                                tx.data = newIface.encodeFunctionData('submit', [[decoded[0], target.address]]);
+                            }
+                            return target[prop](tx);
+                        };
+                    }
+                    if (typeof target[prop] === 'function') {
+                        return target[prop].bind(target);
+                    }
+                    return target[prop];
+                }
+            });
+            const [uploadResult, uploadErr] = await this.indexer.upload(file, this.evmRpc, proxySigner);
+            if (uploadErr !== null) {
+                throw new Error(`0G upload failed: ${uploadErr}`);
+            }
+            return {
+                rootHash: uploadResult.rootHash,
+                txHash: uploadResult.txHash,
+                size: dataBytes.length,
+                timestamp: Date.now(),
+            };
+        }
+        finally {
+            if (file)
+                await file.close();
+            await fs.unlink(tmpPath).catch(() => { });
+        }
+    }
+    /**
+     * Download a file from 0G Storage by its root hash.
+     */
+    async download(rootHash) {
+        const tmpPath = path.join(os.tmpdir(), `0g-down-${Date.now()}-${Math.random().toString(36).slice(2)}.dat`);
+        try {
+            const err = await this.indexer.download(rootHash, tmpPath, true);
+            if (err !== null) {
+                throw new Error(`0G download failed: ${err}`);
+            }
+            return await fs.readFile(tmpPath, "utf-8");
+        }
+        finally {
+            await fs.unlink(tmpPath).catch(() => { });
+        }
+    }
+}
+//# sourceMappingURL=storage.js.map

package/build/lib/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/lib/storage.ts"],"names":[],"mappings":"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"}

package/build/lib/vault.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 0G Agent Shield — AgentVault
+ *
+ * This is the single entry point that ties everything together.
+ * Developers interact with this class, not the internals.
+ *
+ * Usage:
+ *   const vault = new AgentVault({ privateKey, evmRpc, indexerRpc });
+ *   await vault.init();
+ *   const { rootHash } = await vault.store("patient has arrhythmia");
+ *   const data = await vault.retrieve(rootHash);
+ *   const proof = await vault.commitSession(); // attestation
+ */
+export interface VaultConfig {
+    privateKey: string;
+    evmRpc: string;
+    indexerRpc: string;
+    vaultSecret?: string;
+}
+export interface StoreResult {
+    rootHash: string;
+    txHash: string;
+    contentHash: string;
+    size: number;
+    sessionEvent: number;
+    encryptedPayload?: string;
+}
+export interface CommitResult {
+    merkleRoot: string;
+    sessionId: string;
+    eventCount: number;
+    traceRootHash: string;
+    traceTxHash: string;
+}
+export declare class AgentVault {
+    private crypto;
+    private storage;
+    private session;
+    private initialized;
+    private config;
+    constructor(config: VaultConfig);
+    /** Initialize encryption. Must be called before store/retrieve. */
+    init(): Promise<void>;
+    get address(): string;
+    get sessionId(): string;
+    private ensureInit;
+    /**
+     * Encrypt data and store it on 0G Storage.
+     * Automatically records the action in the attestation session.
+     */
+    store(data: string, label?: string): Promise<StoreResult>;
+    /**
+     * Download and decrypt data from 0G Storage.
+     * Automatically records the retrieval in the attestation session.
+     */
+    retrieve(rootHash: string, label?: string): Promise<string>;
+    /**
+     * Finalize the current attestation session:
+     *   1. Compute Merkle root of all events
+     *   2. Encrypt the full trace
+     *   3. Upload encrypted trace to 0G Storage
+     *   4. Return the public commitment (merkleRoot) and trace location
+     *
+     * After this call, a new session begins automatically.
+     */
+    commitSession(): Promise<CommitResult>;
+    /** Get a human-readable summary of the current session */
+    sessionSummary(): string;
+    /** Check wallet balance */
+    getBalance(): Promise<string>;
+}