@bsv/dpp-overlay-topics 0.4.0-beta.1

package/dist/history.d.ts

@@ -0,0 +1,114 @@
+import { type DppRecord, type DppRecordStore, type RecordSelector } from './storage.js';
+export declare const PAGE_VERSION = "1";
+/** One record as a page carries it: what the record store knows, nothing hydrated. */
+export interface HistoryItem {
+    txid: string;
+    outputIndex: number;
+    op: string;
+    timestamp: string;
+    previousTxid: string;
+    spent: boolean;
+    spendingTxid: string;
+    /** The source's own sequence, the order pages are read in; strictly increasing across the pages of one export. */
+    sequence: number;
+}
+export interface HistoryPage {
+    pageVersion: typeof PAGE_VERSION;
+    items: HistoryItem[];
+    nextCursor: string | null;
+    snapshotId: string;
+    scope: {
+        source: string;
+        query: {
+            passportId: string;
+        } | {
+            uid: string;
+        };
+        /**
+         * The sequences this page covers within the snapshot: from the position
+         * after the previous page to the last item here, or to the snapshot's own
+         * sequence on the last page. Consecutive pages tile the snapshot with no
+         * gap and no overlap, so a reader detects a missing or a repeated page
+         * from the ranges alone.
+         */
+        sequenceRange: {
+            from: number;
+            to: number;
+        };
+    };
+    truncated: boolean;
+    completeForSnapshot: boolean;
+    pageSize: number;
+}
+export type HistoryErrorCode = 'query-invalid' | 'limit-invalid' | 'cursor-invalid' | 'snapshot-expired';
+/** A refusal with the status and the name the wire carries. */
+export declare class HistoryError extends Error {
+    readonly status: number;
+    readonly code: HistoryErrorCode;
+    readonly hint?: string | undefined;
+    constructor(status: number, code: HistoryErrorCode, message: string, hint?: string | undefined);
+}
+export interface Snapshot {
+    id: string;
+    /** Records with a sequence above this are outside the snapshot. */
+    sequence: number;
+    /** When the snapshot was taken, epoch milliseconds; expiry is measured from here. */
+    takenAt: number;
+}
+/**
+ * What a cursor resumes: a page of the history or a part of the complete
+ * export (`spec/portable-evidence.md` section 2). The kind is inside the
+ * signed payload, so a history cursor presented to the export, or the
+ * reverse, is refused by name rather than read as a position.
+ */
+export type CursorKind = 'history' | 'export';
+/** Where an export resumes: the snapshot, the position and the index of the part to build. */
+export interface ExportResumption {
+    snapshot: Snapshot;
+    after: number;
+    part: number;
+}
+export interface HistoryRequest {
+    selector: RecordSelector;
+    /** As received on the wire: absent means the default page size. */
+    limit?: string | null;
+    cursor?: string | null;
+}
+export declare class HistoryPaginator {
+    private readonly records;
+    private readonly secret;
+    private readonly now;
+    constructor(records: DppRecordStore, options?: {
+        secret?: Buffer;
+        now?: () => Date;
+    });
+    /** Pin the store as it is now. The exporter uses this directly; the paginator does on a first page. */
+    takeSnapshot(): Promise<Snapshot>;
+    /** At most `limit` records of the selector within the snapshot after `after`, in sequence order: one part's candidates. */
+    readFrom(selector: RecordSelector, snapshot: Snapshot, after: number, limit: number): Promise<DppRecord[]>;
+    /** Every record of the selector within the snapshot, in sequence order, read page by page. */
+    readAll(selector: RecordSelector, snapshot: Snapshot): Promise<DppRecord[]>;
+    page(request: HistoryRequest): Promise<HistoryPage>;
+    /**
+     * The cursor that resumes the complete export after `after`, at part
+     * `part`, over the snapshot the first part pinned: the same tag, TTL and
+     * query binding as a history cursor, under the export kind.
+     */
+    mintExportCursor(snapshot: Snapshot, query: {
+        passportId: string;
+    }, after: number, part: number): string;
+    /** Where an export cursor resumes, or the named refusal a history cursor or a stale one earns. */
+    openExportCursor(cursor: string, query: {
+        passportId: string;
+    }): ExportResumption;
+    /**
+     * Open a cursor for the given query and kind, refusing by name a cursor
+     * of the other kind, one issued for another query, and one whose snapshot
+     * is older than the TTL.
+     */
+    private resume;
+    private mintCursor;
+    private tag;
+    private openCursor;
+}
+//# sourceMappingURL=history.d.ts.map

package/dist/history.d.ts.map

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

package/dist/history.js

@@ -0,0 +1,215 @@
+/**
+ * Pages of a snapshot (`spec/portable-evidence.md` section 1,
+ * `contracts/paginated-history.schema.json`): the export beside the bounded
+ * lookup, which stays exactly what it is.
+ *
+ * A snapshot is the highest record sequence at the moment the first page is
+ * asked for. Every later page of the export reads only records at or below
+ * it, ordered by the store's own sequence, so a record admitted while a
+ * reader is walking the pages never appears in them and never shifts a page
+ * boundary: two readers of one snapshot receive the same pages. The cursor
+ * carries the snapshot and the position, base64url over JSON, and an
+ * HMAC-SHA256 tag under a secret this process drew at startup, so a cursor
+ * from another process, or one edited in transit, is refused by name rather
+ * than read as a position. A snapshot older than the TTL is refused by name
+ * too, with the instruction to start again without a cursor, because a stale
+ * snapshot continued from the middle would be a history that quietly stopped.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { DPP_SERVICE } from './lsDpp.js';
+import { DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE, SNAPSHOT_TTL_MS } from './limits.js';
+import { selectorFilter } from './storage.js';
+export const PAGE_VERSION = '1';
+/** A refusal with the status and the name the wire carries. */
+export class HistoryError extends Error {
+    status;
+    code;
+    hint;
+    constructor(status, code, message, hint) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.hint = hint;
+    }
+}
+const base64url = (bytes) => bytes.toString('base64url');
+export class HistoryPaginator {
+    records;
+    secret;
+    now;
+    constructor(records, options = {}) {
+        this.records = records;
+        // Per process, never persisted: a cursor is a resumption token for this
+        // node's current snapshot, and outliving the process is exactly what it
+        // must not do.
+        this.secret = options.secret ?? randomBytes(32);
+        this.now = options.now ?? (() => new Date());
+    }
+    /** Pin the store as it is now. The exporter uses this directly; the paginator does on a first page. */
+    async takeSnapshot() {
+        const sequence = await this.records.highestSequence();
+        const takenAt = this.now().getTime();
+        return { id: `${sequence}.${takenAt.toString(36)}`, sequence, takenAt };
+    }
+    /** At most `limit` records of the selector within the snapshot after `after`, in sequence order: one part's candidates. */
+    async readFrom(selector, snapshot, after, limit) {
+        return await this.records.findPage(selector, { after, upTo: snapshot.sequence }, limit);
+    }
+    /** Every record of the selector within the snapshot, in sequence order, read page by page. */
+    async readAll(selector, snapshot) {
+        const all = [];
+        let after = 0;
+        for (;;) {
+            const rows = await this.records.findPage(selector, { after, upTo: snapshot.sequence }, MAX_PAGE_SIZE);
+            all.push(...rows);
+            if (rows.length < MAX_PAGE_SIZE)
+                return all;
+            after = rows[rows.length - 1].sequence;
+        }
+    }
+    async page(request) {
+        let query;
+        try {
+            query = selectorFilter(request.selector);
+        }
+        catch (cause) {
+            throw new HistoryError(400, 'query-invalid', cause instanceof Error ? cause.message : 'invalid query');
+        }
+        const limit = parseLimit(request.limit);
+        let snapshot;
+        let after;
+        if (request.cursor == null || request.cursor === '') {
+            snapshot = await this.takeSnapshot();
+            after = 0;
+        }
+        else {
+            ;
+            ({ snapshot, after } = this.resume(request.cursor, query, 'history'));
+        }
+        // One row beyond the page tells whether the snapshot continues, without a
+        // count query that would race nothing but cost a scan.
+        const rows = await this.records.findPage(query, { after, upTo: snapshot.sequence }, limit + 1);
+        const more = rows.length > limit;
+        const items = rows.slice(0, limit);
+        const last = items[items.length - 1];
+        const to = more && last != null ? last.sequence : snapshot.sequence;
+        const nextCursor = more && last != null
+            ? this.mintCursor({ v: 1, kind: 'history', snapshot, query, after: last.sequence })
+            : null;
+        return {
+            pageVersion: PAGE_VERSION,
+            items: items.map(toItem),
+            nextCursor,
+            snapshotId: snapshot.id,
+            scope: {
+                source: DPP_SERVICE,
+                query,
+                sequenceRange: { from: Math.min(after + 1, to), to },
+            },
+            truncated: more,
+            // Only on the last page: every record of the selector at or below the
+            // snapshot has now been returned across the pages of this export.
+            completeForSnapshot: !more,
+            pageSize: limit,
+        };
+    }
+    /**
+     * The cursor that resumes the complete export after `after`, at part
+     * `part`, over the snapshot the first part pinned: the same tag, TTL and
+     * query binding as a history cursor, under the export kind.
+     */
+    mintExportCursor(snapshot, query, after, part) {
+        return this.mintCursor({ v: 1, kind: 'export', snapshot, query, after, part });
+    }
+    /** Where an export cursor resumes, or the named refusal a history cursor or a stale one earns. */
+    openExportCursor(cursor, query) {
+        const { snapshot, after, part } = this.resume(cursor, query, 'export');
+        if (!Number.isSafeInteger(part) || part < 2) {
+            throw new HistoryError(400, 'cursor-invalid', 'the cursor is not one this node issued: no part index');
+        }
+        return { snapshot, after, part: part };
+    }
+    /**
+     * Open a cursor for the given query and kind, refusing by name a cursor
+     * of the other kind, one issued for another query, and one whose snapshot
+     * is older than the TTL.
+     */
+    resume(cursor, query, kind) {
+        const payload = this.openCursor(cursor);
+        if (payload.kind !== kind) {
+            throw new HistoryError(400, 'cursor-invalid', `the cursor was issued for the ${payload.kind}, not the ${kind}`);
+        }
+        if (!sameQuery(payload.query, query)) {
+            throw new HistoryError(400, 'cursor-invalid', 'the cursor was issued for a different query');
+        }
+        if (this.now().getTime() - payload.snapshot.takenAt > SNAPSHOT_TTL_MS) {
+            throw new HistoryError(410, 'snapshot-expired', `snapshot ${payload.snapshot.id} is older than ${SNAPSHOT_TTL_MS / 1000} seconds`, `restart the ${kind === 'history' ? 'export' : 'complete export'} without a cursor to read a fresh snapshot from its first ${kind === 'history' ? 'page' : 'part'}`);
+        }
+        return { snapshot: payload.snapshot, after: payload.after, part: payload.part };
+    }
+    mintCursor(payload) {
+        const body = base64url(Buffer.from(JSON.stringify(payload), 'utf8'));
+        return `${body}.${this.tag(body)}`;
+    }
+    tag(body) {
+        return base64url(createHmac('sha256', this.secret).update(body).digest());
+    }
+    openCursor(cursor) {
+        const invalid = (detail) => new HistoryError(400, 'cursor-invalid', `the cursor is not one this node issued: ${detail}`);
+        const separator = cursor.lastIndexOf('.');
+        if (separator <= 0)
+            throw invalid('malformed');
+        const body = cursor.slice(0, separator);
+        const given = Buffer.from(cursor.slice(separator + 1), 'base64url');
+        const expected = Buffer.from(this.tag(body), 'base64url');
+        if (given.length !== expected.length || !timingSafeEqual(given, expected))
+            throw invalid('bad signature');
+        let payload;
+        try {
+            payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8'));
+        }
+        catch {
+            throw invalid('unreadable');
+        }
+        if (payload?.v !== 1 ||
+            (payload.kind !== 'history' && payload.kind !== 'export') ||
+            typeof payload.snapshot?.id !== 'string' ||
+            !Number.isSafeInteger(payload.snapshot.sequence) ||
+            !Number.isSafeInteger(payload.snapshot.takenAt) ||
+            !Number.isSafeInteger(payload.after) ||
+            typeof payload.query !== 'object' ||
+            payload.query === null) {
+            throw invalid('unexpected shape');
+        }
+        return payload;
+    }
+}
+/** Default 100, maximum 500, anything else refused: a string of digits is the only accepted spelling. */
+function parseLimit(raw) {
+    if (raw == null || raw === '')
+        return DEFAULT_PAGE_SIZE;
+    if (!/^\d+$/.test(raw))
+        throw new HistoryError(400, 'limit-invalid', `limit must be an integer from 1 to ${MAX_PAGE_SIZE}`);
+    const limit = Number(raw);
+    if (limit < 1 || limit > MAX_PAGE_SIZE) {
+        throw new HistoryError(400, 'limit-invalid', `limit must be an integer from 1 to ${MAX_PAGE_SIZE}`);
+    }
+    return limit;
+}
+function sameQuery(a, b) {
+    return ('passportId' in a ? a.passportId : undefined) === ('passportId' in b ? b.passportId : undefined) &&
+        ('uid' in a ? a.uid : undefined) === ('uid' in b ? b.uid : undefined);
+}
+function toItem(record) {
+    return {
+        txid: record.txid,
+        outputIndex: record.outputIndex,
+        op: record.op,
+        timestamp: record.timestamp,
+        previousTxid: record.previousTxid,
+        spent: record.spent,
+        spendingTxid: record.spendingTxid,
+        sequence: record.sequence,
+    };
+}
+//# sourceMappingURL=history.js.map

package/dist/history.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,269 @@
+/**
+ * The DPP overlay node: an HTTP host for two rails, wrapping the
+ * `@bsv/overlay` Engine.
+ *
+ *   the passport   `tm_dpp` admits states, `ls_dpp` resolves them
+ *   the anchors    `tm_attestation` admits generic anchors, `ls_attestation`
+ *                  looks them up; `tm_uora_dpp` and `ls_uora_dpp` carry the
+ *                  historical UORA anchors
+ *
+ * The wire contract is the ecosystem's standard one (BRC-22 submit, BRC-24
+ * lookup), pinned as OpenAPI in `contracts/overlay.yaml`:
+ *
+ *   POST /submit   application/octet-stream body = BEEF bytes
+ *                  X-Topics: ["tm_dpp"]            -> STEAK as JSON, plus an
+ *                  X-Admission answer header (topic=admitted|duplicate|none)
+ *                  Authorization: Bearer <token>   when SUBMIT_TOKEN is set
+ *   POST /lookup   {"service":"ls_dpp","query":{"passportId"|"uid": "..."}}
+ *                  {"service":"ls_uora_dpp","query":{"issuer":"did:key:z..."}}
+ *                                                  -> {type:"output-list",
+ *                                                      outputs:[{beef,outputIndex}]}
+ *   POST /arc-ingest {"txid","merklePath","blockHeight"}
+ *                                                  -> the proof, checked and
+ *                  applied to the held state (spec/services.md section 2);
+ *                  X-Callback-Token or bearer when ARC_CALLBACK_TOKEN is set
+ *   GET  /health                                   -> {status:"ok",...}
+ *
+ * And the extensions this reference deployment serves beside them, each in
+ * the shape a contract in `contracts/` fixes:
+ *
+ *   GET  /capabilities                             -> the capability document
+ *                  (contracts/capabilities.schema.json), built from constants
+ *                  and configuration, never typed by hand
+ *   GET  /history?passportId=|uid=&limit=&cursor=  -> one page of a stable
+ *                  snapshot (contracts/paginated-history.schema.json), the
+ *                  export beside the bounded lookup
+ *   GET  /evidence-package?passportId=             -> dpp-evidence-package@1
+ *                  as {manifest, files} (contracts/evidence-package.schema.json),
+ *                  signed with EXPORT_SIGNING_KEY; 503 when it is unset;
+ *                  bounded to the newest 500 states, the rest declared absent
+ *   GET  /evidence-export?passportId=&cursor=      -> one part of the complete
+ *                  export (contracts/evidence-export.schema.json): a package
+ *                  over a contiguous sequence range of one snapshot, oldest
+ *                  first, bounded by states and bytes, resumed by cursor;
+ *                  Authorization: Bearer <token> when EXPORT_TOKEN is set
+ *   POST /retract  {"txid","outputIndex","reason"} -> removes a state the
+ *                  network refused, behind the /submit bearer; 409 when the
+ *                  state is proven, spent or known to the chain tracker
+ *   POST /requestSyncResponse, POST /requestForeignGASPNode
+ *                                                  -> the upstream GASP
+ *                  routes a peer synchronises from, exactly as the overlay
+ *                  protocol defines them
+ *
+ * Everything is environment; an unset variable switches its feature off or
+ * falls back, and only a missing identity key (or a policy file that does not
+ * verify) fails the boot. See the Configuration table in this package's
+ * README.
+ *
+ * This file is both the entry point and a library: it boots only when node
+ * runs it directly, so tests can drive `createRequestHandler` and
+ * `startOverlayService` without a container.
+ *
+ * Deliberately absent: a Broadcaster and an Advertiser. The app's wallet has
+ * already broadcast the transaction by the time it announces it here, so a
+ * second broadcast would only add a failure mode; and SHIP/SLAP advertising
+ * would need this service to hold a funded wallet of its own. Neither is
+ * needed for the demo, and both can be added later without changing the wire.
+ * Peer synchronisation is present but static: SYNC_PEERS names the operators
+ * this node pulls from through the SDK's GASP (sync.ts), and a state a peer
+ * offers passes the same topic managers as one a writer announces.
+ * Because this host does not broadcast, no broadcaster's callback reaches it
+ * on its own: merkle proofs arrive through POST /arc-ingest, pushed by the
+ * writer once its wallet has them or by a broadcaster whose callback URL a
+ * writer pointed here (spec/writing.md section 7). Re-announcing a mined state
+ * would not do it: the engine skips a txid it already holds.
+ */
+import { type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { type ChainTracker } from '@bsv/sdk';
+import { Engine, type LookupService } from '@bsv/overlay';
+import { type DppRecordStore } from './storage.js';
+import { type RetractableStorage } from './engineStorage.js';
+import { UORA_SERVICE, UORA_TOPIC } from './lsUoraDpp.js';
+import { ATTESTATION_TOPIC } from './tmAttestation.js';
+import { ATTESTATION_SERVICE } from './lsAttestation.js';
+import { type PublisherPolicyConfig } from './policyConfig.js';
+import { type SyncSettings } from './sync.js';
+export declare const TOPIC = "tm_dpp";
+export declare const SERVICE = "ls_dpp";
+export { UORA_SERVICE, UORA_TOPIC };
+export { ATTESTATION_SERVICE, ATTESTATION_TOPIC };
+/** The slice of the Engine the HTTP layer uses, so a test can stand one in. */
+export type OverlayEngine = Pick<Engine, 'submit' | 'lookup' | 'listTopicManagers' | 'listLookupServiceProviders' | 'handleNewMerkleProof' | 'getDocumentationForTopicManager' | 'getDocumentationForLookupServiceProvider' | 'provideForeignSyncResponse' | 'provideForeignGASPNode'>;
+/**
+ * The stores, services and policy the extension routes work on, which the
+ * Engine does not expose through its own surface. `/history` and
+ * `/evidence-package` read the record store and the engine storage;
+ * `/retract` removes from both and tells the lookup services; `/capabilities`
+ * reports the policy. Without them, the read routes answer 503 by name and the
+ * capability document describes a node with no configured policy.
+ */
+export interface NodeComponents {
+    records: DppRecordStore;
+    engineStorage: RetractableStorage;
+    lookupServices: Record<string, LookupService>;
+    publisherPolicy?: PublisherPolicyConfig;
+    serviceIdentityKey?: string;
+    anchorServiceKeys?: string[];
+    ownerConsent?: boolean | {
+        authorities: string[];
+    };
+    /** CONTROL_AUTHORITIES and ACCEPTANCE_COMMITMENT, the version 2 admission options (`spec/record-model-v2.md` §6, `spec/managed-custody.md`). */
+    controlAuthorities?: string[];
+    managedAcceptance?: boolean;
+    /** SYNC_PEERS and SYNC_INTERVAL_MS, reported by the capability document; the Engine holds the same peers as its syncConfiguration. */
+    sync?: Pick<SyncSettings, 'peers' | 'intervalMs'>;
+}
+export interface OverlayHttpOptions {
+    /**
+     * Shared secret required as `Authorization: Bearer` on POST /submit and
+     * POST /retract, the two routes that change what the index holds.
+     * `/lookup` and `/health` stay open: browser verification is a stated goal,
+     * and a read costs no header quota. Unset leaves both open too, which is only
+     * acceptable on a container nobody else can reach.
+     */
+    submitToken?: string;
+    /**
+     * Shared secret required on POST /arc-ingest, as `Authorization: Bearer` or
+     * as `X-Callback-Token`, the two ways an ARC-compatible broadcaster sends the
+     * token it was given at submission. Unset leaves the route open; every proof
+     * is still verified against the header source before it is stored, so an
+     * open route costs header quota rather than truth.
+     */
+    proofToken?: string;
+    /**
+     * The header source a pushed proof is validated against before it is
+     * applied, normally the same one the engine verifies submissions with.
+     * 'scripts only' or unset applies a proof on its local check alone, which
+     * is the local-development setting the engine's own option already is.
+     */
+    chainTracker?: ChainTracker | 'scripts only';
+    /** Reported by /health. */
+    network?: string;
+    /** Reported by /health. Defaults to the moment the handler was made. */
+    startedAt?: string;
+    /**
+     * The address to bind. Unset binds the wildcard, which is what a container
+     * wants and what `main()` leaves it as.
+     *
+     * **A test must set this, and the reason is not tidiness.** A wildcard bind
+     * on an ephemeral port succeeds even when another process already holds that
+     * exact port bound to `127.0.0.1` alone: there is no `EADDRINUSE`, and
+     * `address().port` reports the port as though it were ours. A request to
+     * `127.0.0.1` then goes to the more specific binding, so the caller is
+     * answered by the other process and the service it started never sees the
+     * request. Found on 2026-08-06 behind an intermittent failure in
+     * `test/http.test.ts`: a Logitech daemon holding three ports at the bottom of
+     * the ephemeral range answered `501` with an empty body, which surfaces
+     * either as a wrong status or as `Unexpected end of JSON input`, roughly once
+     * in a hundred server starts. Binding the loopback explicitly makes the
+     * socket a caller reaches the socket that was bound.
+     */
+    host?: string;
+    /** What the extension routes work on; see `NodeComponents`. */
+    components?: NodeComponents;
+    /**
+     * EXPORT_SIGNING_KEY: the private key, hex, that signs evidence-package
+     * manifests. Unset, GET /evidence-package answers 503 export-unavailable and
+     * the capability document lists the export as unsupported. Malformed, the
+     * handler refuses to be built, which is the boot.
+     */
+    exportSigningKey?: string;
+    /**
+     * EXPORT_TOKEN: shared secret required as `Authorization: Bearer` on GET
+     * /evidence-export, the complete export, whose parts are each bounded but
+     * whose number is not. Unset leaves it open, as GET /history is; the bounded
+     * GET /evidence-package stays open either way, and the capability document
+     * says which.
+     */
+    exportToken?: string;
+    /**
+     * Whether the network knows a transaction, for POST /retract: asked of the
+     * header source's operator before an output is removed. Unset when there is
+     * no header source (CHAIN_TRACKER=scripts-only); the retraction then runs on
+     * the local merkle-path check alone and its answer says so.
+     */
+    knownOnChain?: (txid: string) => Promise<boolean>;
+    /** The clock: snapshot expiry, export time and the policy's "active now" read it. Injectable for tests. */
+    now?: () => Date;
+}
+/**
+ * The whole HTTP surface, as a plain node request listener. Separated from the
+ * server so a test can exercise the wire contract against a stand-in engine.
+ */
+export declare function createRequestHandler(engine: OverlayEngine, options?: OverlayHttpOptions): (request: IncomingMessage, response: ServerResponse) => void;
+export interface RunningService {
+    server: Server;
+    /** The port actually bound, which matters when the caller asked for 0. */
+    port: number;
+    close: () => Promise<void>;
+}
+/** Bind the HTTP surface. Resolves once the socket is listening. */
+export declare function startOverlayService(engine: OverlayEngine, options?: OverlayHttpOptions & {
+    port?: number;
+}): Promise<RunningService>;
+/**
+ * The key `server_signature` is checked against (`spec/record-model.md` §5). Only the
+ * public half is needed, so the deployment should set SERVICE_IDENTITY_KEY
+ * and this service never holds the treasury secret. SERVER_PRIVATE_KEY is
+ * accepted as a fallback because it is what every other component is
+ * configured with, but it grants this container more than it needs.
+ */
+export declare function serviceIdentityKey(): string;
+/**
+ * Identity keys of the anchoring services whose UORA anchors this instance
+ * admits, comma-separated in ANCHOR_SERVICE_KEYS.
+ *
+ * A list rather than one key, because the shared overlay instances this topic
+ * is meant for may serve more than one anchoring deployment, and because the
+ * resolver already established that this programme has anchored under two
+ * treasuries without being able to tell which.
+ *
+ * Public keys only. Unlike `serviceIdentityKey` there is no private-key
+ * fallback: the anchoring treasury is a different custody boundary from this
+ * container, and inviting an operator to paste its secret here to save a step
+ * is exactly the convenience that should not exist.
+ */
+export declare function anchorServiceKeys(): string[];
+/**
+ * The owner-signed transfer (`spec/custody.md` §4) is a profile's choice, and
+ * a deployment selects it with OWNER_CONSENT=required. TRANSFER_AUTHORITIES
+ * then names, comma-separated, the identity keys that may move ownership
+ * without proving consent (recovery); public keys only, as for
+ * ANCHOR_SERVICE_KEYS, and validated when the topic manager is built. Any
+ * other value of OWNER_CONSENT fails the boot rather than being read as a
+ * guess, and authorities set without the policy are a misconfiguration worth a
+ * warning, because they would silently do nothing.
+ */
+export declare function ownerConsentPolicy(): boolean | {
+    authorities: string[];
+};
+/**
+ * The version 2 admission options (`spec/record-model-v2.md` §6,
+ * `spec/managed-custody.md`). ACCEPTANCE_COMMITMENT=required selects the
+ * managed-custody profile: a version 2 TRANSFER is admitted only with its
+ * acceptance commitment. CONTROL_AUTHORITIES names, comma-separated, the
+ * identity keys whose version 2 UPDATE, TRANSFER or RETIRE is admitted without
+ * a control proof; absent, the TRANSFER_AUTHORITIES serve both versions.
+ * Public keys only, validated when the topic manager is built; any other value
+ * of ACCEPTANCE_COMMITMENT fails the boot.
+ */
+export declare function versionTwoAdmission(): {
+    managedAcceptance: boolean;
+    controlAuthorities?: string[];
+};
+/**
+ * EXPORT_SIGNING_KEY: the private key that signs evidence-package manifests
+ * (`spec/portable-evidence.md` section 2). Optional, because a node that
+ * exports nothing needs no key; malformed, it fails the boot, because a key
+ * that cannot sign is a promise the capability document would break.
+ */
+export declare function exportSigningKey(): string | undefined;
+/**
+ * Whether the network knows a transaction, asked of the same explorer the
+ * default header source reads, for POST /retract: a transaction it answers is
+ * one the network took, and an index does not retract what a block holds. A
+ * 404 is the one negative; any other failure is neither and is reported as
+ * the source being unavailable.
+ */
+export declare function whatsOnChainKnows(network: 'main' | 'test', apiKey?: string): (txid: string) => Promise<boolean>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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