@enbox/dwn-sdk-js 0.3.9 → 0.4.1

package/dist/types/src/types/smt-types.d.ts

@@ -1,81 +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>;
-}
-//# sourceMappingURL=smt-types.d.ts.map

package/dist/types/src/types/smt-types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"smt-types.d.ts","sourceRoot":"","sources":["../../../../src/types/smt-types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,MAAM,IAAI,GAAG,UAAU,CAAC;AAE9B;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,OAAO,EAAE,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GACf,eAAe,GACf,WAAW,CAAC;AAEhB,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAG,UAAU,CAAC;IAClB,QAAQ,EAAG,IAAI,CAAC;IAChB,SAAS,EAAG,IAAI,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAG,MAAM,CAAC;IACd,OAAO,EAAG,IAAI,CAAC;IACf,QAAQ,EAAG,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,EAAG,IAAI,EAAE,CAAC;IAClB,QAAQ,EAAG,WAAW,GAAG,SAAS,CAAC;IACnC,KAAK,EAAG,MAAM,CAAC;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,oEAAoE;IACpE,SAAS,EAAG,MAAM,EAAE,CAAC;IACrB,oEAAoE;IACpE,UAAU,EAAG,MAAM,EAAE,CAAC;CACvB,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;IAElD;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtC;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC;IAErC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC"}

package/dist/types/src/types/state-index.d.ts

@@ -1,90 +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[]>;
-}
-//# sourceMappingURL=state-index.d.ts.map

package/dist/types/src/types/state-index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"state-index.d.ts","sourceRoot":"","sources":["../../../../src/types/state-index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEtB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9E;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7D;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC;;;;;;OAMG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjE;;;;;;OAMG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjE;;;;;;OAMG;IACH,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3F;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEhE;;;;;;OAMG;IACH,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC3F"}

package/dist/types/tests/event-emitter-event-log.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=event-emitter-event-log.spec.d.ts.map

package/dist/types/tests/event-emitter-event-log.spec.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"event-emitter-event-log.spec.d.ts","sourceRoot":"","sources":["../../../tests/event-emitter-event-log.spec.ts"],"names":[],"mappings":""}

package/dist/types/tests/handlers/messages-sync.spec.d.ts

@@ -1,2 +0,0 @@
-export declare function testMessagesSyncHandler(): void;
-//# sourceMappingURL=messages-sync.spec.d.ts.map

package/dist/types/tests/handlers/messages-sync.spec.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"messages-sync.spec.d.ts","sourceRoot":"","sources":["../../../../tests/handlers/messages-sync.spec.ts"],"names":[],"mappings":"AAuCA,wBAAgB,uBAAuB,IAAI,IAAI,CA6+D9C"}

package/dist/types/tests/smt/smt-store-level.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=smt-store-level.spec.d.ts.map

package/dist/types/tests/smt/smt-store-level.spec.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"smt-store-level.spec.d.ts","sourceRoot":"","sources":["../../../../tests/smt/smt-store-level.spec.ts"],"names":[],"mappings":""}

package/dist/types/tests/smt/sparse-merkle-tree.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=sparse-merkle-tree.spec.d.ts.map

package/dist/types/tests/smt/sparse-merkle-tree.spec.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"sparse-merkle-tree.spec.d.ts","sourceRoot":"","sources":["../../../../tests/smt/sparse-merkle-tree.spec.ts"],"names":[],"mappings":""}

package/dist/types/tests/state-index/state-index-level.spec.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=state-index-level.spec.d.ts.map

package/dist/types/tests/state-index/state-index-level.spec.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"state-index-level.spec.d.ts","sourceRoot":"","sources":["../../../../tests/state-index/state-index-level.spec.ts"],"names":[],"mappings":""}

package/dist/types/tests/sync/records-projection.spec.d.ts

@@ -1,2 +0,0 @@
-export declare function testRecordsProjection(): void;
-//# sourceMappingURL=records-projection.spec.d.ts.map

package/dist/types/tests/sync/records-projection.spec.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"records-projection.spec.d.ts","sourceRoot":"","sources":["../../../../tests/sync/records-projection.spec.ts"],"names":[],"mappings":"AAUA,wBAAgB,qBAAqB,IAAI,IAAI,CAgP5C"}

package/src/core/record-chain.ts

@@ -1,99 +0,0 @@
-import type { Filter } from '../types/query-types.js';
-import type { MessageStore } from '../types/message-store.js';
-import type { RecordsWriteMessage } from '../types/records-types.js';
-
-import { RecordsWrite } from '../interfaces/records-write.js';
-import { DwnError, DwnErrorCode } from './dwn-error.js';
-import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
-
-/**
- * Fetches the initial RecordsWrite message associated with the given (tenant + recordId).
- */
-export async function fetchInitialWrite(
-  tenant: string,
-  recordId: string,
-  messageStore: MessageStore
-): Promise<RecordsWriteMessage | undefined> {
-
-  const query: Filter = {
-    interface : DwnInterfaceName.Records,
-    method    : DwnMethodName.Write,
-    recordId  : recordId
-  };
-  const { messages } = await messageStore.query(tenant, [query]);
-
-  if (messages.length === 0) {
-    return undefined;
-  }
-
-  const initialWrite = await RecordsWrite.getInitialWrite(messages);
-  return initialWrite;
-}
-
-/**
- * Constructs the chain of EXISTING records in the datastore where the first record is the root initial `RecordsWrite` of the record chain
- * and last record is the initial `RecordsWrite` of the descendant record specified.
- * @param descendantRecordId The ID of the descendent record to start constructing the record chain from by repeatedly looking up the parent.
- * @returns the record chain where each record is represented by its initial `RecordsWrite`;
- *          returns empty array if `descendantRecordId` is `undefined`.
- * @throws {DwnError} if `descendantRecordId` is defined but any initial `RecordsWrite` is not found in the chain of records.
- */
-export async function constructRecordChain(
-  tenant: string,
-  descendantRecordId: string | undefined,
-  messageStore: MessageStore
-): Promise<RecordsWriteMessage[]> {
-
-  if (descendantRecordId === undefined) {
-    return [];
-  }
-
-  const recordChain: RecordsWriteMessage[] = [];
-
-  // keep walking up the chain from the inbound message's parent, until there is no more parent
-  let currentRecordId: string | undefined = descendantRecordId;
-  while (currentRecordId !== undefined) {
-
-    const initialWrite = await fetchInitialWrite(tenant, currentRecordId, messageStore);
-
-    // RecordsWrite needed should be available since we perform necessary checks at the time of writes,
-    // eg. check the immediate parent in `verifyProtocolPathAndContextId` at the time of writing,
-    // so if this condition is triggered, it means there is an unexpected bug that caused an incomplete chain.
-    // We add additional defensive check here because returning an unexpected/incorrect record chain could lead to security vulnerabilities.
-    if (initialWrite === undefined) {
-      throw new DwnError(
-        DwnErrorCode.ProtocolAuthorizationParentNotFoundConstructingRecordChain,
-        `Unexpected error that should never trigger: no parent found with ID ${currentRecordId} when constructing record chain.`
-      );
-    }
-
-    recordChain.push(initialWrite);
-    currentRecordId = initialWrite.descriptor.parentId;
-  }
-
-  return recordChain.reverse(); // root record first
-}
-
-/**
- * Determines the timestamp that governs which protocol definition version applies to the given RecordsWrite.
- * For an update, this is the initial write's `messageTimestamp` (the protocol version is locked at creation time).
- * For a new initial write, returns `undefined` — the latest protocol definition should be used because the
- * record is being created now and must conform to the current protocol rules.
- */
-export async function getGoverningTimestamp(
-  tenant: string,
-  incomingMessage: RecordsWrite,
-  messageStore: MessageStore,
-): Promise<string | undefined> {
-  const existingInitialWrite = await fetchInitialWrite(
-    tenant, incomingMessage.message.recordId, messageStore
-  );
-
-  if (existingInitialWrite !== undefined) {
-    // update case: use the initial write's timestamp
-    return existingInitialWrite.descriptor.messageTimestamp;
-  }
-
-  // initial write case: validate against the latest protocol definition
-  return undefined;
-}