@bsv/overlay 2.3.1 → 2.6.1

package/dist/types/src/Engine.d.ts

@@ -9,7 +9,12 @@ import { SyncConfiguration } from './SyncConfiguration.js';
 import { type AdmittedListResponse, type BASMPeerSyncReport, type CompoundMerklePathResponse, type RawTransactionResponse, type ReorgReport, type TopicAnchorHeaderResolver, type TopicAnchorRangeResponse, type TopicAnchorTip } from './BASM.js';
 type UTXOHistoryHydrationContext = {
     outputCache: Map<string, Promise<Output | null>>;
+    budgetedOutputs: Set<string>;
+    hydratedNodes: number;
+    relationCount: number;
+    totalBeefBytes: number;
 };
+type SubmissionMode = 'historical-tx' | 'current-tx' | 'historical-tx-no-spv';
 /**
  * An engine for running BSV Overlay Services (topic managers and lookup services).
  */
@@ -38,6 +43,8 @@ export declare class Engine {
     basmSyncEnabled: boolean;
     unprovenEvictionBlocks: number;
     maxLookupResults: number;
+    private submissionTail;
+    private basmFetchImpl?;
     /**
      * Creates a new Overlay Services Engine
      * @param {[key: string]: TopicManager} managers - manages topic admittance
@@ -108,6 +115,7 @@ export declare class Engine {
         rebuildFromHeight: number;
         newTipHeight: number;
     }): Promise<ReorgReport>;
+    private reconcileReorg;
     /**
      * Revalidation sweep: the reorg fallback for chain trackers without a reorg
      * event stream, and the catch-up step on every reorg-SSE (re)connect (the
@@ -134,6 +142,10 @@ export declare class Engine {
     private applyTopicStorageMutation;
     private applyStorageMutations;
     private propagateSubmission;
+    private assertSupportedTopics;
+    private shouldSkipPropagation;
+    private notifySteakReady;
+    private acknowledgeOverlayAdmission;
     /**
      * Submits a transaction for processing by Overlay Services.
      * @param {TaggedBEEF} taggedBEEF - The transaction to process
@@ -141,11 +153,13 @@ export declare class Engine {
      * @param {string} mode — Indicates the submission behavior, whether historical or current. Historical transactions are not broadcast or propagated.
      * @param {number[]} offChainValues — Values necessary to evaluate topical admittance that are not stored on-chain.
      *
-     * The optional callback function should be used to get STEAK when ready, and avoid waiting for broadcast and transaction propagation to complete.
+     * The optional callback is invoked after any required transaction broadcast and
+     * local storage mutations have completed, but before peer-to-peer propagation.
      *
      * @returns {Promise<STEAK>} The submitted transaction execution acknowledgement
      */
-    submit(taggedBEEF: TaggedBEEF, onSteakReady?: (steak: STEAK) => void, mode?: 'historical-tx' | 'current-tx' | 'historical-tx-no-spv', offChainValues?: number[]): Promise<STEAK>;
+    submit(taggedBEEF: TaggedBEEF, onSteakReady?: (steak: STEAK) => void, mode?: SubmissionMode, offChainValues?: number[]): Promise<STEAK>;
+    private submitUnlocked;
     /**
      * Submit a lookup question to the Overlay Services Engine, and receive back a Lookup Answer
      * @param LookupQuestion — The question to ask the Overlay Services Engine
@@ -154,6 +168,8 @@ export declare class Engine {
     lookup(lookupQuestion: LookupQuestion): Promise<LookupAnswer>;
     private createUTXOHistoryHydrationContext;
     private toOutputCacheKey;
+    private assertLookupFormula;
+    private validateLookupOutput;
     private preloadOutputsWithBEEF;
     private loadOutputWithBEEF;
     private hydrateUTXOHistoryNode;
@@ -176,6 +192,7 @@ export declare class Engine {
      * @throws Will throw an error if there are issues during the advertisement synchronization process.
      * @returns {Promise<void>} A promise that resolves when the synchronization process is complete.
      */
+    private validateCurrentAdvertisements;
     syncAdvertisements(): Promise<void>;
     /**
      * This method goes through each topic that we support syncing and attempts to sync with each endpoint
@@ -187,13 +204,23 @@ export declare class Engine {
     startGASPSync(): Promise<void>;
     private syncGASPWithPeer;
     private resolveSyncEndpointsForTopic;
+    private assertSupportedBASMTopic;
+    private assertTopicAnchorTip;
+    private assertTopicBlockAnchor;
     provideTopicAnchorTip(topic: string): Promise<TopicAnchorTip>;
     provideTopicAnchorRange(topic: string, fromHeight: number, toHeight: number): Promise<TopicAnchorRangeResponse>;
     provideAdmittedList(topic: string, blockHeight: number, blockHash?: string): Promise<AdmittedListResponse>;
     provideCompoundMerklePath(topic: string, blockHeight: number, txids: string[]): Promise<CompoundMerklePathResponse>;
-    provideRawTransactions(txids: string[]): Promise<RawTransactionResponse>;
+    provideRawTransactions(txids: string[], topic?: string): Promise<RawTransactionResponse>;
     startBASMSync(): Promise<BASMPeerSyncReport[]>;
     private reconcileBASMWithPeer;
+    private requireMatchingRemoteBASMTip;
+    private finishBASMWhenRemoteIsNotAhead;
+    private requireBASMRangePrefix;
+    private advanceBASMWithRemoteAnchors;
+    private markBASMPeerSyncError;
+    private requireCanonicalBASMAnchor;
+    private validateBASMProofPositions;
     private reconcileRemoteAnchor;
     private fetchBASMMissingTransactions;
     evictUnprovenTransactions(options?: {
@@ -223,6 +250,7 @@ export declare class Engine {
             error: string;
         }>;
     }>;
+    private validateUnprovenCandidates;
     maintainUnprovenTransactions(options: {
         topic?: string;
         thresholdBlocks?: number;
@@ -279,7 +307,7 @@ export declare class Engine {
      * @returns A promise that resolves to a GASPNode containing the raw transaction and other optional data.
      * @throws An error if no output is found for the given transaction ID and output index.
      */
-    provideForeignGASPNode(graphID: string, txid: string, outputIndex: number): Promise<GASPNode>;
+    provideForeignGASPNode(graphID: string, txid: string, outputIndex: number, topic?: string): Promise<GASPNode>;
     /**
      * Traverse and return the history of a UTXO.
      *
@@ -294,7 +322,7 @@ export declare class Engine {
      * @param {number} [currentDepth=0] - The current depth of the traversal relative to the top-level UTXO.
      *
      * @returns {Promise<Output | undefined>} - A promise that resolves to the output history if found, or undefined if not.
-    */
+     */
     getUTXOHistory(output: Output, historySelector?: ((beef: number[], outputIndex: number, currentDepth: number) => Promise<boolean>) | number, currentDepth?: number, context?: UTXOHistoryHydrationContext): Promise<Output | undefined>;
     /**
      * Delete a UTXO and all stale consumed inputs.
@@ -302,6 +330,8 @@ export declare class Engine {
      * @returns {Promise<void>} - A promise that resolves when the deletion process is complete.
      */
     private deleteUTXODeep;
+    private assertStoredOutputRelations;
+    private assertStoredOutputMatches;
     /**
      * Given a new transaction proof (txid, proof),
      * update tx.merklePath if appropriate,
@@ -312,14 +342,8 @@ export declare class Engine {
      * @param proof for txid
      */
     private updateInputProofs;
-    /**
-     * Recursively updates beefs (merkle proofs) of this output and its consumedBy lineage.
-     *
-     * @param output - An output derived from txid which may benefit from new proof.
-     * @param txid - The txid for which proof is a valid merkle path.
-     * @param proof - The merklePath proving txid is a mined transaction hash
-     */
-    private updateMerkleProof;
+    private prepareMerkleProofUpdate;
+    private collectMerkleProofOutputs;
     /**
      * Recursively prune UTXOs when an incoming Merkle Proof is received.
      *

package/dist/types/src/Engine.d.ts.map

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

package/dist/types/src/EngineAdmission.d.ts

@@ -0,0 +1,70 @@
+import type { Transaction } from '@bsv/sdk';
+import { type AdmissionCommit, type AdmissionCommitResult, type AdmissionPayloadRef, type AdmissionStorage, type HistoryFence, type StorageScope } from './storage/AdmissionStorage.js';
+import type { Output } from './Output.js';
+import type { LookupService } from './LookupService.js';
+export declare const OVERLAY_ENGINE_POLICY_ID = "overlay-engine-submit-v1";
+export type OverlayAdmissionMode = 'live' | 'historical';
+type TopicValidationLike = {
+    topic: string;
+    isDupe: boolean;
+    previousCoins: number[];
+    previousOutputs: Array<Output | null>;
+    admissibleOutputs: {
+        outputsToAdmit: number[];
+        coinsToRetain: number[];
+        coinsRemoved?: number[];
+    };
+};
+export interface OverlayAdmissionHost {
+    admission: AdmissionStorage;
+    admissionScope: StorageScope;
+    publishAdmissionPayload?: (input: {
+        kind: AdmissionPayloadRef['kind'];
+        bytes: Uint8Array;
+        txid?: string;
+    }) => Promise<AdmissionPayloadRef>;
+    enlistedIndexTargets?: () => readonly string[];
+    getHistoryFence?: (topic: string) => Promise<HistoryFence>;
+}
+export declare function getOverlayAdmissionHost(storage: unknown): OverlayAdmissionHost | undefined;
+export declare function overlayAdmissionContextDigest(offChainValues?: number[]): string;
+export declare function overlayAdmissionOperationId(_mode: OverlayAdmissionMode, txid: string, topics: string[]): string;
+export declare function overlayAdmissionMode(mode: 'historical-tx' | 'current-tx' | 'historical-tx-no-spv'): OverlayAdmissionMode;
+/**
+ * Selects the topics that require a new admission decision: topics that did
+ * not fail validation, are not already-applied dupes, and actually admit or
+ * retain something (or consume a previously-admitted coin). Already-applied
+ * (dupe) topics are excluded so that a retry — including a historical GASP
+ * replay after a live admit, or a multi-topic resubmit where only some
+ * topics were previously applied — never re-submits an admission decision
+ * for a topic that MongoAdmissionStorage.assertAppliedAvailable would reject
+ * as belonging to a different operation.
+ */
+export declare function selectNewAdmissionTopics<T extends TopicValidationLike>(validations: readonly T[], failedTopics: Set<string>): T[];
+export declare function buildOverlayAdmissionPlan(input: {
+    host: OverlayAdmissionHost;
+    tx: Transaction;
+    txid: string;
+    beef: number[];
+    topics: string[];
+    mode: OverlayAdmissionMode;
+    offChainValues?: number[];
+    validations: TopicValidationLike[];
+    failedTopics: Set<string>;
+    lookupServices: {
+        [key: string]: LookupService;
+    };
+    includePropagation: boolean;
+    applied?: {
+        firstSeenHeight?: number;
+        blockHeight?: number;
+        blockHash?: string;
+        blockIndex?: number;
+        merkleRoot?: string;
+    };
+}): Promise<AdmissionCommit>;
+export declare function waitForAdmissionReceipt(admission: AdmissionStorage, plan: AdmissionCommit, rebuild: () => Promise<AdmissionCommit>): Promise<AdmissionCommitResult & {
+    state: 'committed';
+}>;
+export {};
+//# sourceMappingURL=EngineAdmission.d.ts.map

package/dist/types/src/EngineAdmission.d.ts.map

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

package/dist/types/src/GASP/OverlayGASPRemote.d.ts

@@ -1,8 +1,9 @@
 import { GASPInitialReply, GASPInitialRequest, GASPInitialResponse, GASPNode, GASPNodeResponse, GASPRemote } from '@bsv/gasp';
 export declare class OverlayGASPRemote implements GASPRemote {
-    endpointURL: string;
-    topic: string;
-    constructor(endpointURL: string, topic: string);
+    readonly endpointURL: string;
+    readonly topic: string;
+    private readonly fetchImpl;
+    constructor(endpointURL: string, topic: string, fetchImpl?: typeof fetch);
     /**
      * Given an outgoing initial request, sends the request to the foreign instance and obtains their initial response.
      * @param request

package/dist/types/src/GASP/OverlayGASPRemote.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OverlayGASPRemote.d.ts","sourceRoot":"","sources":["../../../../src/GASP/OverlayGASPRemote.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,QAAQ,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE7H,qBAAa,iBAAkB,YAAW,UAAU;IAC9B,WAAW,EAAE,MAAM;IAAS,KAAK,EAAE,MAAM;IAA7D,YAAoB,WAAW,EAAE,MAAM,EAAS,KAAK,EAAE,MAAM,EAAK;IAElE;;;;OAIG;IACG,kBAAkB,CAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAiCnF;IAED;;;;;;;OAOG;IACG,WAAW,CAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAwC3G;IAKK,eAAe,CAAE,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAEhF;IAIK,UAAU,CAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAExE;CACF"}
+{"version":3,"file":"OverlayGASPRemote.d.ts","sourceRoot":"","sources":["../../../../src/GASP/OverlayGASPRemote.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,QAAQ,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAe7H,qBAAa,iBAAkB,YAAW,UAAU;IAClD,SAAgB,WAAW,EAAE,MAAM,CAAA;IACnC,SAAgB,KAAK,EAAE,MAAM,CAAA;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;IAExC,YAAa,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,OAAO,KAAK,EAMxE;IAED;;;;OAIG;IACG,kBAAkB,CAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAmBnF;IAED;;;;;;;OAOG;IACG,WAAW,CAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAyB3G;IAKK,eAAe,CAAE,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAEhF;IAIK,UAAU,CAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAExE;CACF"}

package/dist/types/src/GASP/OverlayGASPStorage.d.ts

@@ -22,14 +22,20 @@ export declare class OverlayGASPStorage implements GASPStorage {
     topic: string;
     engine: Engine;
     maxNodesInGraph?: number | undefined;
+    maxBytesInGraph: number;
     readonly temporaryGraphNodeRefs: Record<string, GraphNode>;
+    private readonly graphNodeCounts;
+    private readonly graphByteCounts;
     private static activeAnchorValidations;
     private static readonly anchorValidationQueue;
     private static activeFinalizations;
     private static readonly finalizationQueue;
     private static readonly MAX_CONCURRENT_ANCHOR_VALIDATIONS;
     private static readonly MAX_CONCURRENT_FINALIZATIONS;
-    constructor(topic: string, engine: Engine, maxNodesInGraph?: number | undefined);
+    constructor(topic: string, engine: Engine, maxNodesInGraph?: number | undefined, maxBytesInGraph?: number);
+    private graphNodeKey;
+    private graphNode;
+    private nodeByteLength;
     private static acquireAnchorValidationSlot;
     private static releaseAnchorValidationSlot;
     private static acquireFinalizationSlot;
@@ -50,10 +56,10 @@ export declare class OverlayGASPStorage implements GASPStorage {
      */
     hydrateGASPNode(graphID: string, txid: string, outputIndex: number, _metadata: boolean): Promise<GASPNode>;
     /**
-    * For a given node, returns the inputs needed to complete the graph, including whether updated metadata is requested for those inputs.
-    * @param tx The node for which needed inputs should be found.
-    * @returns A promise for a mapping of requested input transactions and whether metadata should be provided for each.
-    */
+     * For a given node, returns the inputs needed to complete the graph, including whether updated metadata is requested for those inputs.
+     * @param tx The node for which needed inputs should be found.
+     * @returns A promise for a mapping of requested input transactions and whether metadata should be provided for each.
+     */
     findNeededInputs(tx: GASPNode): Promise<GASPNodeResponse | undefined>;
     /**
      * Ensures that no inputs are requested from foreign nodes before sending any GASP response
@@ -61,21 +67,21 @@ export declare class OverlayGASPStorage implements GASPStorage {
      */
     private stripAlreadyKnownInputs;
     /**
-    * Appends a new node to a temporary graph.
-    * @param tx The node to append to this graph.
-    * @param spentBy Unless this is the same node identified by the graph ID, denotes the TXID and input index for the node which spent this one, in 36-byte format.
-    * @throws If the node cannot be appended to the graph, either because the graph ID is for a graph the recipient does not want or because the graph has grown to be too large before being finalized.
-    */
+     * Appends a new node to a temporary graph.
+     * @param tx The node to append to this graph.
+     * @param spentBy Unless this is the same node identified by the graph ID, denotes the TXID and input index for the node which spent this one, in 36-byte format.
+     * @throws If the node cannot be appended to the graph, either because the graph ID is for a graph the recipient does not want or because the graph has grown to be too large before being finalized.
+     */
     appendToGraph(tx: GASPNode, spentBy?: string | undefined): Promise<void>;
     private previousCoinIndexes;
     private admitHistoricalBEEF;
     /**
-      * Checks whether the given graph, in its current state, makes reference only to transactions that are proven in the blockchain, or already known by the recipient to be valid.
-      * Additionally, in a breadth-first manner (ensuring that all inputs for any given node are processed before nodes that spend them), it ensures that the root node remains valid according to the rules of the overlay's topic manager,
-      * while considering any coins which the Manager had previously indicated were either valid or invalid.
-      * @param graphID The TXID and output index (in 36-byte format) for the UTXO at the tip of this graph.
-      * @throws If the graph is not well-anchored, according to the rules of Bitcoin or the rules of the Overlay Topic Manager.
-      */
+     * Checks whether the given graph, in its current state, makes reference only to transactions that are proven in the blockchain, or already known by the recipient to be valid.
+     * Additionally, in a breadth-first manner (ensuring that all inputs for any given node are processed before nodes that spend them), it ensures that the root node remains valid according to the rules of the overlay's topic manager,
+     * while considering any coins which the Manager had previously indicated were either valid or invalid.
+     * @param graphID The TXID and output index (in 36-byte format) for the UTXO at the tip of this graph.
+     * @throws If the graph is not well-anchored, according to the rules of Bitcoin or the rules of the Overlay Topic Manager.
+     */
     validateGraphAnchor(graphID: string): Promise<void>;
     /**
      * Deletes all data associated with a temporary graph that has failed to sync, if the graph exists.

package/dist/types/src/GASP/OverlayGASPStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OverlayGASPStorage.d.ts","sourceRoot":"","sources":["../../../../src/GASP/OverlayGASPStorage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE/E,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAErC;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACzC,QAAQ,EAAE,SAAS,EAAE,CAAA;IACrB,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB;AAED,qBAAa,kBAAmB,YAAW,WAAW;IAShC,KAAK,EAAE,MAAM;IAAS,MAAM,EAAE,MAAM;IAAS,eAAe,CAAC,EAAE,MAAM;IARzF,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAK;IAC/D,OAAO,CAAC,MAAM,CAAC,uBAAuB,CAAI;IAC1C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAwB;IACrE,OAAO,CAAC,MAAM,CAAC,mBAAmB,CAAI;IACtC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAwB;IACjE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iCAAiC,CAAI;IAC7D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,4BAA4B,CAAI;IAExD,YAAoB,KAAK,EAAE,MAAM,EAAS,MAAM,EAAE,MAAM,EAAS,eAAe,CAAC,EAAE,MAAM,YAAA,EAAK;mBAEzE,2BAA2B;IAOhD,OAAO,CAAC,MAAM,CAAC,2BAA2B;mBAQrB,uBAAuB;IAO5C,OAAO,CAAC,MAAM,CAAC,uBAAuB;IAQtC;;;;OAIG;IACG,cAAc,CAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAO1D;IAED;;;;;;;OAOG;IACG,eAAe,CAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAoBhH;IAED;;;;MAIE;IACI,gBAAgB,CAAE,EAAE,EAAE,QAAQ,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CA4C3E;IAED;;;OAGG;YACW,uBAAuB;IAkBrC;;;;;MAKE;IACI,aAAa,CAAE,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAwC9E;IAED,OAAO,CAAC,mBAAmB;YAYb,mBAAmB;IAcjC;;;;;;QAMI;IACE,mBAAmB,CAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoCzD;IAED;;;OAGG;IACG,YAAY,CAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQlD;IAED;;;OAGG;IACG,aAAa,CAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBnD;IAED;;;;OAIG;IACH,OAAO,CAAC,2BAA2B;IAuBnC;;;;OAIG;IACH,OAAO,CAAC,cAAc;CAsBvB"}
+{"version":3,"file":"OverlayGASPStorage.d.ts","sourceRoot":"","sources":["../../../../src/GASP/OverlayGASPStorage.ts"],"names":[],"mappings":"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"}

package/dist/types/src/RemoteSecurity.d.ts

@@ -0,0 +1,50 @@
+import { Transaction, type AdmittanceInstructions } from '@bsv/sdk';
+export declare const MAX_GASP_PAGE_SIZE = 10000;
+export declare const MAX_BASM_TXIDS = 256;
+export declare const MAX_REMOTE_JSON_BYTES: number;
+export declare const MAX_GASP_NODE_JSON_BYTES: number;
+export declare const MAX_RAW_TRANSACTION_BYTES: number;
+export declare const REMOTE_BODY_TIMEOUT_MS = 30000;
+export declare function validateAdmittanceInstructions(value: unknown, tx: Transaction, previousCoins: number[]): AdmittanceInstructions;
+export declare function assertTopic(topic: unknown, label?: string): asserts topic is string;
+export declare function assertRegistryName(value: unknown, label: string): asserts value is string;
+export declare function assertHash(value: unknown, label: string): asserts value is string;
+export declare function assertOutputIndex(value: unknown, label: string): asserts value is number;
+export declare function assertNonnegativeInteger(value: unknown, label: string): asserts value is number;
+export declare function assertOutpoint(value: unknown, label: string): asserts value is string;
+export declare function assertHexBytes(value: unknown, label: string, maxBytes: number, allowEmpty?: boolean): asserts value is string;
+export declare function assertTxidList(value: unknown, label: string, options?: {
+    allowEmpty?: boolean;
+    max?: number;
+}): asserts value is string[];
+export declare function normalizePeerEndpoint(endpoint: string): string;
+export declare function securePeerFetch(endpoint: string, supplied?: typeof fetch): {
+    endpoint: string;
+    fetchImpl: typeof fetch;
+};
+export declare function readPeerJSON(response: Response, maxBytes?: number): Promise<unknown>;
+export declare function assertGASPInitialResponse(value: unknown, maxOutputs: number): asserts value is {
+    UTXOList: Array<{
+        txid: string;
+        outputIndex: number;
+        score: number;
+    }>;
+    since: number;
+};
+export declare function assertGASPNode(value: unknown, expected: {
+    graphID: string;
+    txid: string;
+    outputIndex: number;
+}): asserts value is {
+    graphID: string;
+    rawTx: string;
+    outputIndex: number;
+    proof?: string;
+    txMetadata?: string;
+    outputMetadata?: string;
+    inputs?: Record<string, {
+        hash: string;
+    }>;
+};
+export declare function assertRawTransactionMatches(txid: string, rawTx: string): void;
+//# sourceMappingURL=RemoteSecurity.d.ts.map

package/dist/types/src/RemoteSecurity.d.ts.map

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

package/dist/types/src/storage/AdmissionStorage.d.ts

@@ -0,0 +1,185 @@
+import type { HistoryRevisionHandoff } from './RecoveryContract.js';
+/** Canonical unsigned decimal, 0..2^64-1. Never round through a JS number. */
+export type StorageUint64 = string & {
+    readonly __brand: unique symbol;
+};
+export interface StorageScope {
+    network: string;
+    genesisHash: string;
+    nodeId: string;
+}
+/** These revisions are independent: a late admission need not be a reorg. */
+export interface HistoryFence {
+    chainEpoch: StorageUint64;
+    topicHistoryGeneration: StorageUint64;
+}
+export interface AdmissionIdentity {
+    scope: StorageScope;
+    /** Derived from verified immutable transaction bytes before storage is called. */
+    txid: string;
+    mode: 'live' | 'historical';
+    /** Digest of off-chain values and any other immutable admission-policy inputs. */
+    contextDigest: string;
+    topics: Array<{
+        topic: string;
+        policyId: string;
+    }>;
+}
+export interface AdmissionOperationKey {
+    scope: StorageScope;
+    operationId: string;
+    semanticDigest: string;
+}
+/** Small reference to content published outside the database transaction. */
+export interface AdmissionPayloadRef {
+    digest: string;
+    byteLength: StorageUint64;
+    kind: 'raw-transaction' | 'merkle-path' | 'beef-manifest' | 'locking-script' | 'outbox-data';
+}
+export interface AdmissionOutpoint {
+    txid: string;
+    /** Canonical decimal uint32, the transaction wire outpoint index domain. */
+    outputIndex: StorageUint64;
+}
+/** Adapter-issued revision token; absence is also a read predicate. */
+export interface AdmissionReadPredicate {
+    key: string;
+    expectedVersion: string | null;
+}
+export interface AdmissionOutput extends AdmissionOutpoint {
+    satoshis: StorageUint64;
+    score: StorageUint64;
+    /** A byte range supports even an individually oversized output script. */
+    script: {
+        payload: AdmissionPayloadRef;
+        offset: StorageUint64;
+        byteLength: StorageUint64;
+    };
+}
+export interface AdmissionTopicDecision {
+    topic: string;
+    expectedHistory: HistoryFence;
+    /** Includes all point/range/projection reads that influenced topic admission. */
+    reads: AdmissionReadPredicate[];
+    spends: Array<{
+        outpoint: AdmissionOutpoint;
+        expectedVersion: string;
+        spender: string;
+    }>;
+    /** Remove current serving outputs only; retain applied history and evidence. */
+    evictions: AdmissionOutpoint[];
+    outputs: AdmissionOutput[];
+    edges: Array<{
+        source: AdmissionOutpoint;
+        consumer: AdmissionOutpoint;
+    }>;
+    /** Retain this history after output spend, serving moderation or index eviction. */
+    applied: {
+        txid: string;
+        firstSeenHeight?: StorageUint64;
+        proof?: AdmissionPayloadRef;
+        block?: {
+            height: StorageUint64;
+            hash: string;
+            index: StorageUint64;
+            merkleRoot: string;
+        };
+    };
+    /** Invalidate downstream anchors/comparisons; own repair checkpoint moves atomically. */
+    historyUpdate?: {
+        nextTopicHistoryGeneration: StorageUint64;
+        affectedFromHeight: StorageUint64;
+        /** Present when a recovery worker itself caused this history revision. */
+        handoff?: HistoryRevisionHandoff;
+    };
+}
+/** Every event has a stable scope-local ID and ready payload references. */
+export interface AdmissionOutboxIntent {
+    eventId: string;
+    kind: 'lookup' | 'propagation';
+    target: string;
+    payloads: AdmissionPayloadRef[];
+}
+export interface AdmissionCommit {
+    key: AdmissionOperationKey;
+    identity: AdmissionIdentity;
+    /** Shared raw/proof components or a manifest; never per-output inline BEEF. */
+    payloads: AdmissionPayloadRef[];
+    decisions: AdmissionTopicDecision[];
+    outbox: AdmissionOutboxIntent[];
+    /** Exact UTF-8 STEAK JSON saved with the commit, then replayed without regeneration. */
+    steak: string;
+}
+export interface AdmissionReceipt {
+    operationId: string;
+    semanticDigest: string;
+    /** Only the selected adapter can establish this guarantee. */
+    durability: 'atomic-local';
+    steak: string;
+    /** Only enlisted indexes may be visible at commit. External indexes remain pending. */
+    indexes: Array<{
+        target: string;
+        state: 'visible' | 'pending';
+    }>;
+    propagation: 'not-requested' | 'pending';
+}
+/** Pending is not an ACK. Unknown commit must retain its opaque attempt identity. */
+export type AdmissionCommitResult = {
+    state: 'committed';
+    receipt: AdmissionReceipt;
+} | {
+    state: 'pending';
+    attemptId: string;
+} | {
+    state: 'rejected';
+    code: 'digest-mismatch' | 'read-conflict' | 'spend-conflict' | 'payload-not-ready' | 'unsupported-projection' | 'invalid-plan';
+};
+export type AdmissionReconcileResult = AdmissionCommitResult | {
+    state: 'aborted';
+};
+/**
+ * Optional v1 contract, separate from legacy CRUD Storage. No current adapter or
+ * Engine call path implements it. A provider must atomically revalidate reads,
+ * fences, conditional spends and ready-payload pins, and save every effect plus
+ * the receipt. Matching retries return the saved receipt before checking stale
+ * reads; conflicting semantic digests reject. Do not run verification, uploads,
+ * network requests or arbitrary plug-ins inside commitAdmission.
+ *
+ * TransientTransactionError permits a fresh whole-body attempt after abort and
+ * reread/redecision. UnknownTransactionCommitResult requires reconcileAdmission
+ * on the SAME attempt until committed or definitively aborted; absence of an
+ * operation record alone does not establish abort. Repeated commitAdmission
+ * must first recover any persisted unresolved attempt for this operation, even
+ * after a lost response or process restart, before it can start a fresh body.
+ * Transport failures remain
+ * errors, never rejection/abort or a successful local ACK.
+ */
+export interface AdmissionStorage {
+    readonly protocol: 'overlay-admission-v1';
+    commitAdmission: (plan: AdmissionCommit) => Promise<AdmissionCommitResult>;
+    reconcileAdmission: (key: AdmissionOperationKey, attemptId?: string) => Promise<AdmissionReconcileResult>;
+}
+/** External projection delivery may be retried only with both capabilities. */
+export interface ReplaySafeProjection {
+    readonly protocol: 'overlay-projection-v1';
+    applyEvent: (scope: StorageScope, intent: AdmissionOutboxIntent) => Promise<{
+        checkpoint: string;
+    }>;
+    reconcile: (scope: StorageScope, checkpoint: string | null) => Promise<{
+        checkpoint: string;
+    }>;
+}
+/** Shape detection is a declaration, not proof that an adapter is durable. */
+export declare function getAdmissionStorage(storage: unknown): AdmissionStorage | undefined;
+export declare function isReplaySafeProjection(projection: unknown): projection is ReplaySafeProjection;
+export declare function parseStorageUint64(value: string): bigint;
+export declare function asStorageUint64(value: string): StorageUint64;
+/** Validate the wire outpoint domain before conversion to an exact STEAK number. */
+export declare function parseStorageOutputIndex(value: string): number;
+/**
+ * SHA-256 of UTF-8 length-framed fields, see specs/overlay/persistence-v1.md.
+ * Mutable reads/decisions and proof variants are deliberately outside semantic
+ * identity. Their validation and atomic read predicates remain mandatory.
+ */
+export declare function admissionSemanticDigest(identity: AdmissionIdentity): string;
+//# sourceMappingURL=AdmissionStorage.d.ts.map

package/dist/types/src/storage/AdmissionStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdmissionStorage.d.ts","sourceRoot":"","sources":["../../../../src/storage/AdmissionStorage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAEnE,8EAA8E;AAC9E,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,MAAM,CAAA;CAAE,CAAA;AAExE,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;CACf;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,aAAa,CAAA;IACzB,sBAAsB,EAAE,aAAa,CAAA;CACtC;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,YAAY,CAAA;IACnB,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,GAAG,YAAY,CAAA;IAC3B,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACnD;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,YAAY,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,aAAa,CAAA;IACzB,IAAI,EAAE,iBAAiB,GAAG,aAAa,GAAG,eAAe,GAAG,gBAAgB,GAAG,aAAa,CAAA;CAC7F;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,4EAA4E;IAC5E,WAAW,EAAE,aAAa,CAAA;CAC3B;AAED,uEAAuE;AACvE,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;CAC/B;AAED,MAAM,WAAW,eAAgB,SAAQ,iBAAiB;IACxD,QAAQ,EAAE,aAAa,CAAA;IACvB,KAAK,EAAE,aAAa,CAAA;IACpB,0EAA0E;IAC1E,MAAM,EAAE;QAAE,OAAO,EAAE,mBAAmB,CAAC;QAAC,MAAM,EAAE,aAAa,CAAC;QAAC,UAAU,EAAE,aAAa,CAAA;KAAE,CAAA;CAC3F;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAA;IACb,eAAe,EAAE,YAAY,CAAA;IAC7B,iFAAiF;IACjF,KAAK,EAAE,sBAAsB,EAAE,CAAA;IAC/B,MAAM,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,iBAAiB,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACxF,gFAAgF;IAChF,SAAS,EAAE,iBAAiB,EAAE,CAAA;IAC9B,OAAO,EAAE,eAAe,EAAE,CAAA;IAC1B,KAAK,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,iBAAiB,CAAC;QAAC,QAAQ,EAAE,iBAAiB,CAAA;KAAE,CAAC,CAAA;IACxE,oFAAoF;IACpF,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAA;QACZ,eAAe,CAAC,EAAE,aAAa,CAAA;QAC/B,KAAK,CAAC,EAAE,mBAAmB,CAAA;QAC3B,KAAK,CAAC,EAAE;YAAE,MAAM,EAAE,aAAa,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,aAAa,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;KAC1F,CAAA;IACD,yFAAyF;IACzF,aAAa,CAAC,EAAE;QACd,0BAA0B,EAAE,aAAa,CAAA;QACzC,kBAAkB,EAAE,aAAa,CAAA;QACjC,0EAA0E;QAC1E,OAAO,CAAC,EAAE,sBAAsB,CAAA;KACjC,CAAA;CACF;AAED,4EAA4E;AAC5E,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,QAAQ,GAAG,aAAa,CAAA;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,mBAAmB,EAAE,CAAA;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,qBAAqB,CAAA;IAC1B,QAAQ,EAAE,iBAAiB,CAAA;IAC3B,+EAA+E;IAC/E,QAAQ,EAAE,mBAAmB,EAAE,CAAA;IAC/B,SAAS,EAAE,sBAAsB,EAAE,CAAA;IACnC,MAAM,EAAE,qBAAqB,EAAE,CAAA;IAC/B,wFAAwF;IACxF,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;IACtB,8DAA8D;IAC9D,UAAU,EAAE,cAAc,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,uFAAuF;IACvF,OAAO,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,GAAG,SAAS,CAAA;KAAE,CAAC,CAAA;IAChE,WAAW,EAAE,eAAe,GAAG,SAAS,CAAA;CACzC;AAED,qFAAqF;AACrF,MAAM,MAAM,qBAAqB,GAC7B;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,GACjD;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACvC;IACE,KAAK,EAAE,UAAU,CAAA;IACjB,IAAI,EACA,iBAAiB,GACjB,eAAe,GACf,gBAAgB,GAChB,mBAAmB,GACnB,wBAAwB,GACxB,cAAc,CAAA;CACnB,CAAA;AAEL,MAAM,MAAM,wBAAwB,GAAG,qBAAqB,GAAG;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,CAAA;AAEnF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAA;IACzC,eAAe,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAA;IAC1E,kBAAkB,EAAE,CAClB,GAAG,EAAE,qBAAqB,EAC1B,SAAS,CAAC,EAAE,MAAM,KACf,OAAO,CAAC,wBAAwB,CAAC,CAAA;CACvC;AAED,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAA;IAC1C,UAAU,EAAE,CACV,KAAK,EAAE,YAAY,EACnB,MAAM,EAAE,qBAAqB,KAC1B,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACpC,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC/F;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAUlF;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,OAAO,GAAG,UAAU,IAAI,oBAAoB,CAW9F;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMxD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAG5D;AAED,oFAAoF;AACpF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAsC3E"}