@enbox/dwn-sdk-js 0.4.0 → 0.4.1

package/src/state-index/state-index-level.ts

@@ -1,239 +0,0 @@
-/**
- * LevelDB-backed implementation of the StateIndex interface.
- *
- * Manages per-tenant Sparse Merkle Trees (global + per-protocol sub-trees).
- *
- * All data lives within a single LevelDB instance, partitioned by sublevels:
- *   {tenant}/global/        -> SMT nodes + root for the tenant's global tree
- *   {tenant}/proto/{proto}/ -> SMT nodes + root for a protocol-scoped tree
- *   {tenant}/meta/{cid}     -> JSON(indexes) for reverse lookup during deletion
- */
-
-import type { Hash } from '../types/smt-types.js';
-import type { KeyValues } from '../types/query-types.js';
-import type { StateIndex } from '../types/state-index.js';
-
-import { initDefaultHashes } from '../smt/smt-utils.js';
-import { SMTStoreLevel } from '../smt/smt-store-level.js';
-import { SparseMerkleTree } from '../smt/sparse-merkle-tree.js';
-import { createLevelDatabase, LevelWrapper } from '../store/level-wrapper.js';
-
-export type StateIndexLevelConfig = {
-  /**
-   * Must be a directory path (relative or absolute) where LevelDB will store its files,
-   * or in browsers, the name of the IDBDatabase to be opened.
-   */
-  location? : string;
-  createLevelDatabase? : typeof createLevelDatabase;
-};
-
-export class StateIndexLevel implements StateIndex {
-  private readonly config: StateIndexLevelConfig;
-  private db!: LevelWrapper<string>;
-
-  /**
-   * Cache of per-tenant global SMTs. Lazily populated on first access.
-   * Stores promises to avoid race conditions when multiple concurrent operations
-   * trigger lazy initialization of the same tenant's SMT.
-   */
-  private readonly globalTrees: Map<string, Promise<SparseMerkleTree>> = new Map();
-
-  /**
-   * Cache of per-tenant, per-protocol SMTs. Key format: `{tenant}\x00{protocol}`
-   * Stores promises to avoid race conditions (same reason as globalTrees).
-   */
-  private readonly protocolTrees: Map<string, Promise<SparseMerkleTree>> = new Map();
-
-  constructor(config?: StateIndexLevelConfig) {
-    this.config = {
-      location            : 'STATEINDEX',
-      createLevelDatabase : createLevelDatabase,
-      ...config,
-    };
-  }
-
-  async open(): Promise<void> {
-    this.db = new LevelWrapper<string>({
-      location            : this.config.location!,
-      createLevelDatabase : this.config.createLevelDatabase,
-      keyEncoding         : 'utf8',
-    });
-    await this.db.open();
-
-    // Ensure default hashes are initialized
-    await initDefaultHashes();
-  }
-
-  async close(): Promise<void> {
-    this.globalTrees.clear();
-    this.protocolTrees.clear();
-
-    await this.db.close();
-  }
-
-  async clear(): Promise<void> {
-    this.globalTrees.clear();
-    this.protocolTrees.clear();
-
-    await this.db.clear();
-  }
-
-  async insert(tenant: string, messageCid: string, indexes: KeyValues): Promise<void> {
-    // Insert into the global tree
-    const globalSmt = await this.getGlobalTree(tenant);
-    await globalSmt.insert(messageCid);
-
-    // Insert into the protocol-scoped tree if the message has a protocol (e.g. RecordsWrite).
-    // Non-record messages like ProtocolsConfigure do not have a protocol.
-    const protocol = indexes.protocol as string | undefined;
-    if (protocol !== undefined) {
-      const protoSmt = await this.getProtocolTree(tenant, protocol);
-      await protoSmt.insert(messageCid);
-    }
-
-    // Store the reverse lookup so we know the protocol during deletion
-    await this.storeIndexes(tenant, messageCid, indexes);
-  }
-
-  async delete(tenant: string, messageCids: string[]): Promise<void> {
-    const globalSmt = await this.getGlobalTree(tenant);
-
-    for (const messageCid of messageCids) {
-      // Look up stored indexes to find the protocol
-      const indexes = await this.getStoredIndexes(tenant, messageCid);
-
-      // Delete from global tree
-      await globalSmt.delete(messageCid);
-
-      // Delete from protocol tree if the message had a protocol
-      if (indexes !== undefined) {
-        const protocol = indexes.protocol as string | undefined;
-        if (protocol !== undefined) {
-          const protoSmt = await this.getProtocolTree(tenant, protocol);
-          await protoSmt.delete(messageCid);
-        }
-      }
-
-      // Remove the reverse lookup
-      await this.deleteStoredIndexes(tenant, messageCid);
-    }
-  }
-
-  async getRoot(tenant: string): Promise<Hash> {
-    const smt = await this.getGlobalTree(tenant);
-    return smt.getRoot();
-  }
-
-  async getProtocolRoot(tenant: string, protocol: string): Promise<Hash> {
-    const smt = await this.getProtocolTree(tenant, protocol);
-    return smt.getRoot();
-  }
-
-  async getSubtreeHash(tenant: string, prefix: boolean[]): Promise<Hash> {
-    const smt = await this.getGlobalTree(tenant);
-    return smt.getSubtreeHash(prefix);
-  }
-
-  async getProtocolSubtreeHash(tenant: string, protocol: string, prefix: boolean[]): Promise<Hash> {
-    const smt = await this.getProtocolTree(tenant, protocol);
-    return smt.getSubtreeHash(prefix);
-  }
-
-  async getLeaves(tenant: string, prefix: boolean[]): Promise<string[]> {
-    const smt = await this.getGlobalTree(tenant);
-    return smt.getLeaves(prefix);
-  }
-
-  async getProtocolLeaves(tenant: string, protocol: string, prefix: boolean[]): Promise<string[]> {
-    const smt = await this.getProtocolTree(tenant, protocol);
-    return smt.getLeaves(prefix);
-  }
-
-  // ─── Private helpers ────────────────────────────────────────────────────
-
-  /**
-   * Get or create the global SMT for a tenant.
-   * Uses a promise-based cache to prevent concurrent callers from racing to
-   * initialize the same tenant's SMT twice.
-   */
-  private getGlobalTree(tenant: string): Promise<SparseMerkleTree> {
-    let smtPromise = this.globalTrees.get(tenant);
-    if (smtPromise !== undefined) {
-      return smtPromise;
-    }
-
-    smtPromise = this.createTree(this.db, [tenant, 'global']);
-    this.globalTrees.set(tenant, smtPromise);
-    return smtPromise;
-  }
-
-  /**
-   * Get or create a protocol-scoped SMT for a tenant.
-   * Uses a promise-based cache to prevent concurrent callers from racing to
-   * initialize the same tenant's SMT twice.
-   */
-  private getProtocolTree(tenant: string, protocol: string): Promise<SparseMerkleTree> {
-    const cacheKey = `${tenant}\x00${protocol}`;
-    let smtPromise = this.protocolTrees.get(cacheKey);
-    if (smtPromise !== undefined) {
-      return smtPromise;
-    }
-
-    smtPromise = this.createTree(this.db, [tenant, 'proto', protocol]);
-    this.protocolTrees.set(cacheKey, smtPromise);
-    return smtPromise;
-  }
-
-  /**
-   * Create and initialize a new SparseMerkleTree backed by a sublevel chain
-   * within the single LevelDB instance.
-   */
-  private async createTree(db: LevelWrapper<string>, sublevels: string[]): Promise<SparseMerkleTree> {
-    let partition = db;
-    for (const name of sublevels) {
-      partition = await partition.partition(name);
-    }
-
-    const store = new SMTStoreLevel(partition);
-    const smt = new SparseMerkleTree(store);
-    await smt.initialize();
-    return smt;
-  }
-
-  /**
-   * Store the indexes for a messageCid so we can look up the protocol during deletion.
-   */
-  private async storeIndexes(tenant: string, messageCid: string, indexes: KeyValues): Promise<void> {
-    const metaPartition = await this.getMetaPartition(tenant);
-    // Store the protocol index needed for deletion
-    const minimalIndexes: KeyValues = { protocol: indexes.protocol };
-    await metaPartition.put(messageCid, JSON.stringify(minimalIndexes));
-  }
-
-  /**
-   * Get the stored indexes for a messageCid.
-   */
-  private async getStoredIndexes(tenant: string, messageCid: string): Promise<KeyValues | undefined> {
-    const metaPartition = await this.getMetaPartition(tenant);
-    const value = await metaPartition.get(messageCid);
-    if (value === undefined) {
-      return undefined;
-    }
-    return JSON.parse(value) as KeyValues;
-  }
-
-  /**
-   * Delete the stored indexes for a messageCid.
-   */
-  private async deleteStoredIndexes(tenant: string, messageCid: string): Promise<void> {
-    const metaPartition = await this.getMetaPartition(tenant);
-    await metaPartition.delete(messageCid);
-  }
-
-  /**
-   * Get the metadata partition for a tenant.
-   */
-  private async getMetaPartition(tenant: string): Promise<LevelWrapper<string>> {
-    return (await this.db.partition(tenant)).partition('meta');
-  }
-}

package/src/types/smt-types.ts

@@ -1,95 +0,0 @@
-/**
- * Types for the Sparse Merkle Tree implementation.
- */
-
-/**
- * A 32-byte hash (SHA-256 output).
- */
-export type Hash = Uint8Array;
-
-/**
- * Represents the path through the tree as a sequence of bits derived from the key hash.
- * Each bit determines whether to go left (0) or right (1) at each depth level.
- */
-export type BitPath = boolean[];
-
-/**
- * A node in the Sparse Merkle Tree.
- *
- * - `internal`: has left and right child hashes but no leaf data
- * - `leaf`: has a key hash and value (the messageCid) but no children
- * - empty subtrees are represented implicitly via precomputed default hashes
- */
-export type SMTNode =
-  | SMTInternalNode
-  | SMTLeafNode;
-
-export type SMTInternalNode = {
-  type : 'internal';
-  leftHash : Hash;
-  rightHash : Hash;
-};
-
-export type SMTLeafNode = {
-  type : 'leaf';
-  keyHash : Hash;
-  valueCid : string;
-};
-
-/**
- * An inclusion or non-inclusion proof for a key in the SMT.
- *
- * - `siblings`: the sibling hashes along the path from leaf to root
- * - `leafNode`: the leaf node at the path (undefined if non-inclusion proof for an empty slot)
- * - `depth`: the depth at which the proof terminates
- */
-export type SMTProof = {
-  siblings : Hash[];
-  leafNode : SMTLeafNode | undefined;
-  depth : number;
-};
-
-/**
- * Result of diffing two SMT roots.
- */
-export type SMTDiffResult = {
-  /** messageCids present in the local tree but not the remote tree */
-  onlyLocal : string[];
-  /** messageCids present in the remote tree but not the local tree */
-  onlyRemote : string[];
-};
-
-/**
- * Interface for persisting SMT nodes. Implementations can use LevelDB, SQL, or in-memory maps.
- * Nodes are keyed by their hash. The root hash is stored separately.
- */
-export interface SMTNodeStore {
-  open(): Promise<void>;
-  close(): Promise<void>;
-  clear(): Promise<void>;
-
-  /**
-   * Get a node by its hash. Returns undefined if not found.
-   */
-  getNode(hash: Hash): Promise<SMTNode | undefined>;
-
-  /**
-   * Store a node, keyed by its hash.
-   */
-  putNode(hash: Hash, node: SMTNode): Promise<void>;
-
-  /**
-   * Delete a node by its hash.
-   */
-  deleteNode(hash: Hash): Promise<void>;
-
-  /**
-   * Get the current root hash. Returns undefined if no root has been set.
-   */
-  getRoot(): Promise<Hash | undefined>;
-
-  /**
-   * Set the root hash.
-   */
-  setRoot(hash: Hash): Promise<void>;
-}

package/src/types/state-index.ts

@@ -1,100 +0,0 @@
-import type { Hash } from './smt-types.js';
-import type { KeyValues } from './query-types.js';
-
-/**
- * A Sparse Merkle Tree-backed state index that tracks the set of messageCids
- * for each tenant. Replaces the EventLog as the mechanism for sync state tracking.
- *
- * Key differences from EventLog:
- * - No watermark ordering — the SMT is a set, not a log
- * - Root hash provides O(1) "are we in sync?" comparison
- * - Supports subtree hashing for O(log n) set reconciliation
- * - Per-protocol sub-trees for scoped sync
- */
-export interface StateIndex {
-  /**
-   * Opens a connection to the underlying store.
-   */
-  open(): Promise<void>;
-
-  /**
-   * Closes the connection to the underlying store.
-   */
-  close(): Promise<void>;
-
-  /**
-   * Clears all data. Mainly used for cleaning up in test environments.
-   */
-  clear(): Promise<void>;
-
-  /**
-   * Insert a message into the state index.
-   *
-   * @param tenant - the tenant's DID
-   * @param messageCid - the CID of the message
-   * @param indexes - key-value pairs from the message (used to extract `protocol` for
-   *   per-protocol sub-tree maintenance, and stored for reverse lookup during deletion)
-   */
-  insert(tenant: string, messageCid: string, indexes: KeyValues): Promise<void>;
-
-  /**
-   * Delete messages from the state index.
-   *
-   * @param tenant - the tenant's DID
-   * @param messageCids - the CIDs of the messages to remove
-   */
-  delete(tenant: string, messageCids: string[]): Promise<void>;
-
-  /**
-   * Get the SMT root hash for a tenant's global state (all protocols).
-   *
-   * @param tenant - the tenant's DID
-   * @returns the root hash. Returns the default empty root if no messages exist.
-   */
-  getRoot(tenant: string): Promise<Hash>;
-
-  /**
-   * Get the SMT root hash for a specific protocol's state within a tenant.
-   *
-   * @param tenant - the tenant's DID
-   * @param protocol - the protocol URI
-   * @returns the root hash. Returns the default empty root if no messages exist for this protocol.
-   */
-  getProtocolRoot(tenant: string, protocol: string): Promise<Hash>;
-
-  /**
-   * Get the hash of a subtree at a given bit prefix within a tenant's global tree.
-   * Used by the sync protocol for tree walking during set reconciliation.
-   *
-   * @param tenant - the tenant's DID
-   * @param prefix - array of booleans representing the path (false=left, true=right)
-   */
-  getSubtreeHash(tenant: string, prefix: boolean[]): Promise<Hash>;
-
-  /**
-   * Get the hash of a subtree at a given bit prefix within a protocol-scoped tree.
-   *
-   * @param tenant - the tenant's DID
-   * @param protocol - the protocol URI
-   * @param prefix - array of booleans representing the path (false=left, true=right)
-   */
-  getProtocolSubtreeHash(tenant: string, protocol: string, prefix: boolean[]): Promise<Hash>;
-
-  /**
-   * Get all leaf messageCids under a given prefix in the tenant's global tree.
-   * Used by the sync protocol to enumerate leaves in a divergent subtree.
-   *
-   * @param tenant - the tenant's DID
-   * @param prefix - array of booleans representing the path
-   */
-  getLeaves(tenant: string, prefix: boolean[]): Promise<string[]>;
-
-  /**
-   * Get all leaf messageCids under a given prefix in a protocol-scoped tree.
-   *
-   * @param tenant - the tenant's DID
-   * @param protocol - the protocol URI
-   * @param prefix - array of booleans representing the path
-   */
-  getProtocolLeaves(tenant: string, protocol: string, prefix: boolean[]): Promise<string[]>;
-}