@rohankumar4179/engram-sdk 0.0.0-stage → 0.1.0

package/dist/tatum.js

@@ -0,0 +1,148 @@
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+import { GrpcTransport } from "@protobuf-ts/grpc-transport";
+import { ChannelCredentials } from "@grpc/grpc-js";
+/** Walrus `Blob` Move type on Sui Mainnet. */
+export const WALRUS_BLOB_TYPE_MAINNET = "0xfdc88f7d7cf30afab2f82e8380d11ee8f70efb90e863d1de8616fae1bb09ea77::blob::Blob";
+/** Tatum's Sui Mainnet gRPC gateway (Sui JSON-RPC was switched off in July 2026). */
+export const TATUM_SUI_GRPC_HOST = "sui-mainnet-grpc.gateway.tatum.io:443";
+/** Walrus stores blob_id as a u256; the SDK shows it as little-endian base64url. */
+export function blobIdFromU256(u256) {
+    let x = BigInt(u256);
+    const b = Buffer.alloc(32);
+    for (let i = 0; i < 32; i++) {
+        b[i] = Number(x & 0xffn);
+        x >>= 8n;
+    }
+    return b.toString("base64url");
+}
+/**
+ * Sui Mainnet through Tatum's gRPC gateway. All of Engram's mainnet reads (and
+ * mainnet anchor transactions) go through here.
+ */
+export class TatumSui {
+    host;
+    apiKey;
+    _client;
+    constructor(opts) {
+        this.apiKey = opts.apiKey;
+        this.host = opts.host ?? TATUM_SUI_GRPC_HOST;
+        this._client = opts.client;
+    }
+    /** The Sui SDK client, connected to Tatum with native gRPC (Tatum doesn't serve gRPC-Web). */
+    get client() {
+        if (!this._client) {
+            const transport = new GrpcTransport({ host: this.host, channelCredentials: ChannelCredentials.createSsl(), meta: { "x-api-key": this.apiKey } });
+            this._client = new SuiGrpcClient({ network: "mainnet", transport });
+        }
+        return this._client;
+    }
+    /** Retries Tatum's transient failures (rate limit, unavailable upstream). */
+    async retry(what, fn) {
+        let last;
+        for (let attempt = 0; attempt < 4; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (err) {
+                last = err;
+                const msg = String(err.message ?? err);
+                if (!/UNAVAILABLE|RESOURCE_EXHAUSTED|DEADLINE|429|503|502|ECONNRESET|healthy upstream/i.test(msg))
+                    break;
+                await new Promise((r) => setTimeout(r, 800 * (attempt + 1)));
+            }
+        }
+        throw new Error(`Tatum Sui ${what}: ${last?.message ?? last}`);
+    }
+    async latestCheckpoint() {
+        return this.retry("service info", async () => {
+            const info = await this.client.ledgerService.getServiceInfo({}).response;
+            return String(info.checkpointHeight ?? "");
+        });
+    }
+    async getObject(id) {
+        return this.retry("getObject", async () => {
+            try {
+                const { object: o } = await this.client.getObject({ objectId: id, include: { json: true, previousTransaction: true } });
+                return toObjectData(o);
+            }
+            catch (err) {
+                if (/not ?found/i.test(String(err.message)))
+                    return null;
+                throw err;
+            }
+        });
+    }
+    /** Owner address of a Walrus Memory account (the wallet that owns the blobs). */
+    async memwalAccountOwner(accountId) {
+        const o = await this.getObject(accountId);
+        const owner = o?.content?.fields?.owner;
+        if (!owner)
+            throw new Error(`Walrus Memory account ${accountId} not found on Sui`);
+        return owner;
+    }
+    /** All Walrus Blob objects owned by an address. */
+    async *ownedBlobs(owner, blobType = WALRUS_BLOB_TYPE_MAINNET) {
+        let cursor = null;
+        do {
+            const page = await this.retry("listOwnedObjects", () => this.client.listOwnedObjects({ owner, type: blobType, cursor, limit: 50, include: { json: true, previousTransaction: true } }));
+            for (const o of page.objects) {
+                const f = o.json;
+                if (!f)
+                    continue;
+                yield {
+                    objectId: o.objectId,
+                    blobId: blobIdFromU256(String(f.blob_id)),
+                    size: Number(f.size),
+                    registeredEpoch: Number(f.registered_epoch),
+                    certifiedEpoch: f.certified_epoch == null ? null : Number(f.certified_epoch),
+                    previousTransaction: o.previousTransaction ?? "",
+                };
+            }
+            cursor = page.hasNextPage ? page.cursor : null;
+        } while (cursor);
+    }
+    async getTransaction(digest) {
+        return this.retry("getTransaction", async () => {
+            const r = await this.client.getTransaction({ digest });
+            const t = r.Transaction ?? r.FailedTransaction;
+            return { digest: t?.digest ?? digest, checkpoint: t?.checkpoint ?? "", timestampMs: Number(t?.timestampMs ?? 0) };
+        });
+    }
+    /** Recent transactions that touched an address (sent or received), newest first. */
+    async transactionsOf(address, limit = 20) {
+        return this.retry("listTransactions", async () => {
+            const call = this.client.ledgerService.listTransactions({
+                readMask: { paths: ["digest", "timestamp", "checkpoint", "balance_changes", "transaction.sender"] },
+                filter: { terms: [{ literals: [{ negated: false, predicate: { oneofKind: "affectedAddress", affectedAddress: { address } } }] }] },
+                options: { limit, ordering: 1 /* descending */ },
+            });
+            const out = [];
+            for await (const frame of call.responses) {
+                const t = frame.transaction;
+                if (!t?.digest)
+                    continue;
+                out.push({
+                    digest: t.digest,
+                    checkpoint: t.checkpoint != null ? String(t.checkpoint) : undefined,
+                    timestampMs: t.timestamp ? String(Number(t.timestamp.seconds) * 1000 + Math.floor((t.timestamp.nanos ?? 0) / 1e6)) : undefined,
+                    transaction: { data: { sender: t.transaction?.sender } },
+                    balanceChanges: (t.balanceChanges ?? []).map((b) => ({ owner: { AddressOwner: b.address ?? "" }, coinType: b.coinType ?? "", amount: b.amount ?? "0" })),
+                });
+                if (out.length >= limit)
+                    break;
+            }
+            return out;
+        });
+    }
+    /** Decimals and symbol of a coin type, or null if it has no metadata. */
+    async coinMetadata(coinType) {
+        return this.retry("getCoinMetadata", async () => {
+            const r = await this.client.getCoinMetadata({ coinType });
+            return r.coinMetadata ? { decimals: r.coinMetadata.decimals, symbol: r.coinMetadata.symbol } : null;
+        });
+    }
+}
+function toObjectData(o) {
+    return { objectId: o.objectId, version: o.version, type: o.type, owner: o.owner, previousTransaction: o.previousTransaction ?? undefined, content: { fields: o.json ?? undefined } };
+}
+//# sourceMappingURL=tatum.js.map

package/dist/tatum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tatum.js","sourceRoot":"","sources":["../src/tatum.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,8CAA8C;AAC9C,MAAM,CAAC,MAAM,wBAAwB,GAAG,gFAAgF,CAAC;AAEzH,qFAAqF;AACrF,MAAM,CAAC,MAAM,mBAAmB,GAAG,uCAAuC,CAAC;AA0B3E,oFAAoF;AACpF,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IACrB,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC;QACzB,CAAC,KAAK,EAAE,CAAC;IACX,CAAC;IACD,OAAO,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,QAAQ;IACV,IAAI,CAAS;IACd,MAAM,CAAS;IACf,OAAO,CAAiB;IAEhC,YAAY,IAAkB;QAC5B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,mBAAmB,CAAC;QAC7C,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC;IAC7B,CAAC;IAED,8FAA8F;IAC9F,IAAI,MAAM;QACR,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,SAAS,GAAG,IAAI,aAAa,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,kBAAkB,EAAE,kBAAkB,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YACjJ,IAAI,CAAC,OAAO,GAAG,IAAI,aAAa,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC;QACtE,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,6EAA6E;IACrE,KAAK,CAAC,KAAK,CAAI,IAAY,EAAE,EAAoB;QACvD,IAAI,IAAa,CAAC;QAClB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC;YAC7C,IAAI,CAAC;gBACH,OAAO,MAAM,EAAE,EAAE,CAAC;YACpB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,GAAG,CAAC;gBACX,MAAM,GAAG,GAAG,MAAM,CAAE,GAAa,CAAC,OAAO,IAAI,GAAG,CAAC,CAAC;gBAClD,IAAI,CAAC,kFAAkF,CAAC,IAAI,CAAC,GAAG,CAAC;oBAAE,MAAM;gBACzG,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,aAAa,IAAI,KAAM,IAAc,EAAE,OAAO,IAAI,IAAI,EAAE,CAAC,CAAC;IAC5E,CAAC;IAED,KAAK,CAAC,gBAAgB;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,IAAI,EAAE;YAC3C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC;YACzE,OAAO,MAAM,CAAC,IAAI,CAAC,gBAAgB,IAAI,EAAE,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,EAAU;QACxB,OAAO,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,IAAI,EAAE;YACxC,IAAI,CAAC;gBACH,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;gBACxH,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC;YACzB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,aAAa,CAAC,IAAI,CAAC,MAAM,CAAE,GAAa,CAAC,OAAO,CAAC,CAAC;oBAAE,OAAO,IAAI,CAAC;gBACpE,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,iFAAiF;IACjF,KAAK,CAAC,kBAAkB,CAAC,SAAiB;QACxC,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QAC1C,MAAM,KAAK,GAAI,CAAC,EAAE,OAAO,EAAE,MAAyC,EAAE,KAAK,CAAC;QAC5E,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,SAAS,mBAAmB,CAAC,CAAC;QACnF,OAAO,KAAK,CAAC;IACf,CAAC;IAED,mDAAmD;IACnD,KAAK,CAAC,CAAC,UAAU,CAAC,KAAa,EAAE,QAAQ,GAAG,wBAAwB;QAClE,IAAI,MAAM,GAAkB,IAAI,CAAC;QACjC,GAAG,CAAC;YACF,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,kBAAkB,EAAE,GAAG,EAAE,CACrD,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,mBAAmB,EAAE,IAAI,EAAE,EAAE,CAAC,CAC/H,CAAC;YACF,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBAC7B,MAAM,CAAC,GAAG,CAAC,CAAC,IAAyB,CAAC;gBACtC,IAAI,CAAC,CAAC;oBAAE,SAAS;gBACjB,MAAM;oBACJ,QAAQ,EAAE,CAAC,CAAC,QAAQ;oBACpB,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;oBACzC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;oBACpB,eAAe,EAAE,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC;oBAC3C,cAAc,EAAE,CAAC,CAAC,eAAe,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC;oBAC5E,mBAAmB,EAAE,CAAC,CAAC,mBAAmB,IAAI,EAAE;iBACjD,CAAC;YACJ,CAAC;YACD,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;QACjD,CAAC,QAAQ,MAAM,EAAE;IACnB,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,MAAc;QACjC,OAAO,IAAI,CAAC,KAAK,CAAC,gBAAgB,EAAE,KAAK,IAAI,EAAE;YAC7C,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;YACvD,MAAM,CAAC,GAAG,CAAC,CAAC,WAAW,IAAI,CAAC,CAAC,iBAAiB,CAAC;YAC/C,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,IAAI,MAAM,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,IAAI,EAAE,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC,EAAE,WAAW,IAAI,CAAC,CAAC,EAAE,CAAC;QACpH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,oFAAoF;IACpF,KAAK,CAAC,cAAc,CAAC,OAAe,EAAE,KAAK,GAAG,EAAE;QAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,kBAAkB,EAAE,KAAK,IAAI,EAAE;YAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,gBAAgB,CAAC;gBACtD,QAAQ,EAAE,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,CAAC,EAAE;gBACnG,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,SAAS,EAAE,iBAAiB,EAAE,eAAe,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE;gBAClI,OAAO,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,gBAAgB,EAAE;aACxC,CAAC,CAAC;YACZ,MAAM,GAAG,GAAkB,EAAE,CAAC;YAC9B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,IAAI,CAAC,SAA4D,EAAE,CAAC;gBAC5F,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC;gBAC5B,IAAI,CAAC,CAAC,EAAE,MAAM;oBAAE,SAAS;gBACzB,GAAG,CAAC,IAAI,CAAC;oBACP,MAAM,EAAE,CAAC,CAAC,MAAM;oBAChB,UAAU,EAAE,CAAC,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS;oBACnE,WAAW,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS;oBAC9H,WAAW,EAAE,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE;oBACxD,cAAc,EAAE,CAAC,CAAC,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC,OAAO,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,IAAI,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC,CAAC;iBACzJ,CAAC,CAAC;gBACH,IAAI,GAAG,CAAC,MAAM,IAAI,KAAK;oBAAE,MAAM;YACjC,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC,CAAC,CAAC;IACL,CAAC;IAED,yEAAyE;IACzE,KAAK,CAAC,YAAY,CAAC,QAAgB;QACjC,OAAO,IAAI,CAAC,KAAK,CAAC,iBAAiB,EAAE,KAAK,IAAI,EAAE;YAC9C,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC1D,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACtG,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAED,SAAS,YAAY,CAAC,CAAkJ;IACtK,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,mBAAmB,EAAE,CAAC,CAAC,mBAAmB,IAAI,SAAS,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,IAAI,IAAI,SAAS,EAAE,EAAE,CAAC;AACvL,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,122 @@
+/** Where an episode came from. */
+export type EpisodeSource = "user" | "tool" | "tatum" | "agent" | "system";
+/** Encrypted payload as stored on Walrus Memory and on disk. */
+export interface Envelope {
+    /** Format marker so Engram can recognise its own memories. */
+    engram: "episode";
+    v: 1;
+    id: string;
+    keyId: string;
+    /** base64 AES-256-GCM nonce, ciphertext and auth tag. */
+    iv: string;
+    ct: string;
+    tag: string;
+}
+/** An immutable raw event. Its plaintext only exists encrypted. */
+export interface Episode {
+    id: string;
+    ts: number;
+    source: EpisodeSource;
+    /** Short, non-sensitive label shown in logs (e.g. "transfer 450 USDC"). */
+    summary?: string;
+    /** sha256 of the canonical plaintext, before encryption. */
+    contentHash: string;
+    keyId: string;
+    envelope: Envelope;
+    /** Walrus blob ID, set once pushed. */
+    blobId?: string;
+    /** Set when the episode's key was destroyed. */
+    forgottenAt?: number;
+    /** Set once `sleep()` has processed it. */
+    consolidatedAt?: number;
+}
+/** The decrypted contents of an episode. */
+export interface EpisodeContent {
+    source: EpisodeSource;
+    ts: number;
+    data: unknown;
+}
+export type BeliefStatus = "active" | "revised" | "retracted";
+/** One version of a belief. A new version supersedes the previous one. */
+export interface Belief {
+    /** Stable belief ID across versions, e.g. "b_rent". */
+    id: string;
+    version: number;
+    statement: string;
+    /** 0..1 */
+    confidence: number;
+    /** Episode IDs that support this version. */
+    evidence: string[];
+    tags: string[];
+    /** Key of the version this one replaced ("b_rent@1"). */
+    supersedes?: string;
+    status: BeliefStatus;
+    createdAt: number;
+    /** Why this version exists (from the consolidator). */
+    reason?: string;
+    blobId?: string;
+}
+export interface MerkleProofStep {
+    /** hex sha256 of the sibling node */
+    hash: string;
+    /** whether the sibling is on the left */
+    left: boolean;
+}
+/** The signed part of a commit. Hashing this gives the commit ID. */
+export interface CommitManifest {
+    engram: "commit";
+    v: 1;
+    agent: string;
+    parent: string | null;
+    ts: number;
+    message: string;
+    merkleRoot: string;
+    /** "id@version" of every active belief, sorted. */
+    beliefs: string[];
+    /** Episode IDs whose keys were destroyed (ever), sorted. */
+    tombstones: string[];
+    /** Episode ID → Walrus blob ID, for every episode referenced by an active belief. */
+    episodes: Record<string, string>;
+    /** "id@version" → Walrus blob ID of that belief version. */
+    beliefBlobs: Record<string, string>;
+    agentPubKey: string;
+}
+export interface Anchor {
+    /**
+     * walrus-blob: the manifest's own Walrus Blob object on Sui (option A).
+     * move-event:  an `engram_anchor::anchor::Anchored` event carrying the root publicly (option B).
+     */
+    method: "walrus-blob" | "move-event";
+    /** walrus-blob: Sui object ID of the Walrus Blob. move-event: the package ID. */
+    objectId: string;
+    /** Sui transaction that created it. */
+    txDigest: string;
+    checkpoint?: string;
+    timestampMs?: number;
+    /** move-event: Sui network the anchor lives on. Absent means mainnet. */
+    network?: "mainnet" | "testnet";
+}
+export interface Commit {
+    id: string;
+    manifest: CommitManifest;
+    /** hex Ed25519 signature over the canonical manifest. */
+    signature: string;
+    manifestBlobId?: string;
+    anchor?: Anchor;
+}
+export interface Receipt {
+    engram: "receipt";
+    v: 1;
+    id: string;
+    agent: string;
+    commitId: string;
+    ts: number;
+    action: string;
+    inputHash: string;
+    /** "id@version" of beliefs used. */
+    beliefs: string[];
+    proofs: Record<string, MerkleProofStep[]>;
+    agentPubKey: string;
+    signature: string;
+    blobId?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/vault.d.ts

@@ -0,0 +1,31 @@
+import { type Sealed } from "./crypto.js";
+import type { JsonFile } from "./store.js";
+interface VaultFile {
+    v: 1;
+    /** keyId → data key wrapped (AES-GCM) with the master key */
+    keys: Record<string, Sealed & {
+        createdAt: number;
+    }>;
+    /** keyId → time it was destroyed */
+    destroyed: Record<string, number>;
+}
+/**
+ * Holds one random data key per episode, each wrapped by a master key.
+ * Destroying a data key makes that episode unreadable everywhere — the
+ * ciphertext on Walrus stays, but can never be opened again.
+ */
+export declare class KeyVault {
+    private file;
+    private masterKey;
+    constructor(file: JsonFile<VaultFile>, masterKey: Uint8Array);
+    private load;
+    create(): {
+        keyId: string;
+        key: Buffer;
+    };
+    get(keyId: string): Buffer | null;
+    isDestroyed(keyId: string): boolean;
+    /** Removes the wrapped key from disk. Returns false if it was already gone. */
+    destroy(keyId: string): boolean;
+}
+export {};

package/dist/vault.js

@@ -0,0 +1,45 @@
+import { decrypt, encrypt, newDataKey, randomId } from "./crypto.js";
+/**
+ * Holds one random data key per episode, each wrapped by a master key.
+ * Destroying a data key makes that episode unreadable everywhere — the
+ * ciphertext on Walrus stays, but can never be opened again.
+ */
+export class KeyVault {
+    file;
+    masterKey;
+    constructor(file, masterKey) {
+        this.file = file;
+        this.masterKey = masterKey;
+        if (masterKey.length !== 32)
+            throw new Error("master key must be 32 bytes");
+    }
+    load() {
+        return this.file.read() ?? { v: 1, keys: {}, destroyed: {} };
+    }
+    create() {
+        const vault = this.load();
+        const keyId = randomId("k", 8);
+        const key = newDataKey();
+        vault.keys[keyId] = { ...encrypt(key, this.masterKey, keyId), createdAt: Date.now() };
+        this.file.write(vault);
+        return { keyId, key };
+    }
+    get(keyId) {
+        const wrapped = this.load().keys[keyId];
+        return wrapped ? decrypt(wrapped, this.masterKey, keyId) : null;
+    }
+    isDestroyed(keyId) {
+        return keyId in this.load().destroyed;
+    }
+    /** Removes the wrapped key from disk. Returns false if it was already gone. */
+    destroy(keyId) {
+        const vault = this.load();
+        if (!vault.keys[keyId])
+            return false;
+        delete vault.keys[keyId];
+        vault.destroyed[keyId] = Date.now();
+        this.file.write(vault);
+        return true;
+    }
+}
+//# sourceMappingURL=vault.js.map

package/dist/vault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.js","sourceRoot":"","sources":["../src/vault.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAe,MAAM,aAAa,CAAC;AAWlF;;;;GAIG;AACH,MAAM,OAAO,QAAQ;IAET;IACA;IAFV,YACU,IAAyB,EACzB,SAAqB;QADrB,SAAI,GAAJ,IAAI,CAAqB;QACzB,cAAS,GAAT,SAAS,CAAY;QAE7B,IAAI,SAAS,CAAC,MAAM,KAAK,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IAC9E,CAAC;IAEO,IAAI;QACV,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;IAC/D,CAAC;IAED,MAAM;QACJ,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC1B,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC/B,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QACtF,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACvB,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IACxB,CAAC;IAED,GAAG,CAAC,KAAa;QACf,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxC,OAAO,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAClE,CAAC;IAED,WAAW,CAAC,KAAa;QACvB,OAAO,KAAK,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,SAAS,CAAC;IACxC,CAAC;IAED,+EAA+E;IAC/E,OAAO,CAAC,KAAa;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC1B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACrC,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzB,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@rohankumar4179/engram-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Git for agent memory — versioned, provable memory on Walrus Memory",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@grpc/grpc-js": "1.13.4",
+    "@mysten-incubation/memwal": "^0.1.8",
+    "@mysten/seal": "1.5.1",
+    "@mysten/sui": "^2.37.0",
+    "@noble/curves": "^2.4.0",
+    "@noble/hashes": "^2.4.0",
+    "@protobuf-ts/grpc-transport": "2.11.1"
+  },
+  "devDependencies": {
+    "@scure/bip39": "2.4.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rohan911438/Engram.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/rohan911438/Engram#readme",
+  "keywords": [
+    "agents",
+    "memory",
+    "walrus",
+    "sui",
+    "merkle",
+    "ai"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }