@enbox/dwn-sdk-js 0.3.9 → 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/sync/records-projection.ts

@@ -1,328 +0,0 @@
-import type { Filter } from '../types/query-types.js';
-import type { Hash } from '../types/smt-types.js';
-import type { MessageStore, MessageStoreOptions } from '../types/message-store.js';
-
-import { DwnInterfaceName } from '../enums/dwn-interface-method.js';
-import { FilterUtility } from '../utils/filter.js';
-import { hashToHex } from '../smt/smt-utils.js';
-import { isRecordsPrimaryProjectionExcludedProtocol } from '../core/constants.js';
-import { lexicographicalCompare } from '../utils/string.js';
-import { Message } from '../core/message.js';
-import { SMTStoreMemory } from '../smt/smt-store-memory.js';
-import { SparseMerkleTree } from '../smt/sparse-merkle-tree.js';
-
-/**
- * Projection-root algorithm for record-primary scoped subsets.
- *
- * This version builds an on-demand SMT over latest Records primary message CIDs
- * selected by protocol plus optional exact protocolPath or context subtree.
- * Dependency records, protocol configs, and record data payloads are not part
- * of this root.
- */
-export const RECORDS_PROJECTION_ROOT_VERSION = 'records-primary-scope-root-v1';
-
-/**
- * A Records primary projection scope.
- *
- * `protocolPath` is an exact type-path match. `contextId` is a boundary-aware
- * subtree match: the candidate context must equal the scoped context or start
- * with `${contextId}/`. `protocolPath` and `contextId` are mutually exclusive.
- */
-export type RecordsProjectionScope = {
-  protocol: string;
-  protocolPath?: string;
-  contextId?: string;
-};
-
-export type RecordsProjectionInput = {
-  tenant: string;
-  messageStore: MessageStore;
-  scopes: readonly [RecordsProjectionScope, ...RecordsProjectionScope[]];
-  options?: MessageStoreOptions;
-};
-
-export type RecordsProjectionTreeInput = RecordsProjectionInput & {
-  prefix: boolean[];
-};
-
-export type RecordsProjectionSnapshot = {
-  getRoot(): Promise<Hash>;
-  getRootHex(): Promise<string>;
-  getSubtreeHash(prefix: boolean[]): Promise<Hash>;
-  getLeaves(prefix: boolean[]): Promise<string[]>;
-  close(): Promise<void>;
-};
-
-export type NormalizedRecordsProjectionScope = {
-  protocol: string;
-} | {
-  protocol: string;
-  protocolPath: string;
-} | {
-  protocol: string;
-  contextId: string;
-};
-
-/**
- * Computes deterministic on-demand roots for Records projections.
- *
- * The snapshot API performs one store enumeration and serves tree operations
- * from that in-memory view. A future store-level snapshot/high-watermark can be
- * threaded through the `options` input without changing the projection shape.
- */
-export class RecordsProjection {
-
-  /**
-   * Returns the sorted latest Records primary message CIDs covered by a scope union.
-   */
-  public static async getPrimaryMessageCids({
-    tenant,
-    messageStore,
-    scopes,
-    options,
-  }: RecordsProjectionInput): Promise<string[]> {
-    const filters = RecordsProjection.normalizeScopes(scopes)
-      .filter(scope => !isRecordsPrimaryProjectionExcludedProtocol(scope.protocol))
-      .flatMap(scope => RecordsProjection.constructFilters(scope));
-    if (filters.length === 0) {
-      return [];
-    }
-
-    const { messages } = await messageStore.query(tenant, filters, undefined, undefined, options);
-    const messageCids = await Promise.all(messages.map(message => Message.getCid(message)));
-
-    return [...new Set(messageCids)].sort(lexicographicalCompare); // NOSONAR — projection IDs require locale-independent bytewise ordering.
-  }
-
-  /**
-   * Returns the projection root hash.
-   */
-  public static async getRoot(input: RecordsProjectionInput): Promise<Hash> {
-    return RecordsProjection.withTree(input, tree => tree.getRoot());
-  }
-
-  /**
-   * Returns the projection root hash encoded as lowercase hex.
-   */
-  public static async getRootHex(input: RecordsProjectionInput): Promise<string> {
-    return hashToHex(await RecordsProjection.getRoot(input));
-  }
-
-  /**
-   * Returns the subtree hash for a bit prefix within this projection.
-   */
-  public static async getSubtreeHash(input: RecordsProjectionTreeInput): Promise<Hash> {
-    return RecordsProjection.withTree(input, tree => tree.getSubtreeHash(input.prefix));
-  }
-
-  /**
-   * Returns the message CIDs under a bit prefix within this projection.
-   */
-  public static async getLeaves(input: RecordsProjectionTreeInput): Promise<string[]> {
-    return RecordsProjection.withTree(input, tree => tree.getLeaves(input.prefix));
-  }
-
-  /**
-   * Builds an in-memory projection tree from one primary-CID enumeration.
-   */
-  public static async createSnapshot(input: RecordsProjectionInput): Promise<RecordsProjectionSnapshot> {
-    const tree = await RecordsProjection.createTree(input);
-    return {
-      close          : () => tree.close(),
-      getLeaves      : (prefix: boolean[]) => tree.getLeaves(prefix),
-      getRoot        : () => tree.getRoot(),
-      getRootHex     : async () => hashToHex(await tree.getRoot()),
-      getSubtreeHash : (prefix: boolean[]) => tree.getSubtreeHash(prefix),
-    };
-  }
-
-  /**
-   * Normalizes a scope union into sorted, duplicate-free, subsumption-reduced entries.
-   */
-  public static normalizeScopes(
-    scopes: readonly [RecordsProjectionScope, ...RecordsProjectionScope[]],
-  ): [NormalizedRecordsProjectionScope, ...NormalizedRecordsProjectionScope[]] {
-    if (scopes.length === 0) {
-      throw new Error('RecordsProjection: scopes must contain at least one scope.');
-    }
-
-    const normalized = scopes.map(scope => RecordsProjection.normalizeScope(scope));
-    const deduped = new Map<string, NormalizedRecordsProjectionScope>();
-    for (const scope of normalized) {
-      deduped.set(RecordsProjection.scopeKey(scope), scope);
-    }
-
-    const uniqueScopes = [...deduped.values()];
-    const protocolWide = new Set(
-      uniqueScopes
-        .filter(scope => RecordsProjection.isProtocolWideScope(scope))
-        .map(scope => scope.protocol)
-    );
-
-    const reduced = uniqueScopes.filter(scope => {
-      if (protocolWide.has(scope.protocol)) {
-        return RecordsProjection.isProtocolWideScope(scope);
-      }
-
-      if (RecordsProjection.isContextScope(scope)) {
-        return !uniqueScopes.some(candidate =>
-          candidate !== scope &&
-          RecordsProjection.isContextScope(candidate) &&
-          candidate.protocol === scope.protocol &&
-          RecordsProjection.contextIdSubsumes(candidate.contextId, scope.contextId)
-        );
-      }
-
-      return true;
-    });
-
-    const result = reduced.sort(RecordsProjection.compareScopes);
-    return result as [NormalizedRecordsProjectionScope, ...NormalizedRecordsProjectionScope[]];
-  }
-
-  private static async withTree<T>(
-    input: RecordsProjectionInput,
-    fn: (tree: SparseMerkleTree) => Promise<T>,
-  ): Promise<T> {
-    const tree = await RecordsProjection.createTree(input);
-
-    try {
-      return await fn(tree);
-    } finally {
-      await tree.close();
-    }
-  }
-
-  private static async createTree(input: RecordsProjectionInput): Promise<SparseMerkleTree> {
-    const tree = new SparseMerkleTree(new SMTStoreMemory());
-    await tree.initialize();
-
-    try {
-      const messageCids = await RecordsProjection.getPrimaryMessageCids(input);
-      for (const messageCid of messageCids) {
-        await tree.insert(messageCid);
-      }
-
-      return tree;
-    } catch (error) {
-      await tree.close();
-      throw error;
-    }
-  }
-
-  private static normalizeScope(scope: RecordsProjectionScope): NormalizedRecordsProjectionScope {
-    const protocol = RecordsProjection.requireNonEmptyString(scope.protocol, 'protocol');
-
-    if (scope.protocolPath !== undefined && scope.contextId !== undefined) {
-      throw new Error('RecordsProjection: protocolPath and contextId scopes are mutually exclusive.');
-    }
-
-    if (scope.protocolPath !== undefined) {
-      return {
-        protocol,
-        protocolPath: RecordsProjection.requireNonEmptyString(scope.protocolPath, 'protocolPath'),
-      };
-    }
-
-    if (scope.contextId !== undefined) {
-      return {
-        protocol,
-        contextId: RecordsProjection.requireNonEmptyString(scope.contextId, 'contextId'),
-      };
-    }
-
-    return { protocol };
-  }
-
-  private static constructFilters(scope: NormalizedRecordsProjectionScope): Filter[] {
-    const baseFilter: Filter = {
-      interface         : DwnInterfaceName.Records,
-      isLatestBaseState : true,
-      protocol          : scope.protocol,
-    };
-
-    if ('protocolPath' in scope) {
-      return [{ ...baseFilter, protocolPath: scope.protocolPath }];
-    }
-
-    if ('contextId' in scope) {
-      const childContextPrefix = `${scope.contextId}/`;
-      return [
-        { ...baseFilter, contextId: scope.contextId },
-        {
-          ...baseFilter,
-          contextId: FilterUtility.constructPrefixFilterAsRangeFilter(childContextPrefix),
-        },
-      ];
-    }
-
-    return [baseFilter];
-  }
-
-  private static requireNonEmptyString(value: string, field: string): string {
-    if (typeof value !== 'string' || value.length === 0) {
-      throw new Error(`RecordsProjection: ${field} must be a non-empty string.`);
-    }
-
-    return value;
-  }
-
-  private static scopeKey(scope: NormalizedRecordsProjectionScope): string {
-    if ('protocolPath' in scope) {
-      return `${scope.protocol}\u001fprotocolPath\u001f${scope.protocolPath}`;
-    }
-
-    if ('contextId' in scope) {
-      return `${scope.protocol}\u001fcontextId\u001f${scope.contextId}`;
-    }
-
-    return `${scope.protocol}\u001fprotocol`;
-  }
-
-  private static isProtocolWideScope(
-    scope: NormalizedRecordsProjectionScope,
-  ): scope is { protocol: string } {
-    return !('protocolPath' in scope) && !('contextId' in scope);
-  }
-
-  private static isContextScope(
-    scope: NormalizedRecordsProjectionScope,
-  ): scope is { protocol: string; contextId: string } {
-    return 'contextId' in scope;
-  }
-
-  private static contextIdSubsumes(parentContextId: string, childContextId: string): boolean {
-    return childContextId === parentContextId ||
-      childContextId.startsWith(`${parentContextId}/`);
-  }
-
-  private static compareScopes(
-    a: NormalizedRecordsProjectionScope,
-    b: NormalizedRecordsProjectionScope,
-  ): number {
-    const protocolCompare = lexicographicalCompare(a.protocol, b.protocol);
-    if (protocolCompare !== 0) {
-      return protocolCompare;
-    }
-
-    const aRank = RecordsProjection.scopeRank(a);
-    const bRank = RecordsProjection.scopeRank(b);
-    if (aRank !== bRank) {
-      return aRank - bRank;
-    }
-
-    return lexicographicalCompare(RecordsProjection.scopeValue(a), RecordsProjection.scopeValue(b));
-  }
-
-  private static scopeRank(scope: NormalizedRecordsProjectionScope): number {
-    if ('protocolPath' in scope) { return 1; }
-    if ('contextId' in scope) { return 2; }
-    return 0;
-  }
-
-  private static scopeValue(scope: NormalizedRecordsProjectionScope): string {
-    if ('protocolPath' in scope) { return scope.protocolPath; }
-    if ('contextId' in scope) { return scope.contextId; }
-    return '';
-  }
-}

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>;
-}