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

package/dist/storage.js

@@ -0,0 +1,158 @@
+/**
+ * The one accepted spelling of a selector: exactly one key, a non-empty string.
+ * Checked in the store and not only at the HTTP handler, because the Mongo
+ * store would run whatever object it is handed as a filter.
+ */
+export function selectorFilter(selector) {
+    const passportId = typeof selector.passportId === 'string' && selector.passportId !== '' ? selector.passportId : undefined;
+    const uid = typeof selector.uid === 'string' && selector.uid !== '' ? selector.uid : undefined;
+    if (passportId != null && uid == null)
+        return { passportId };
+    if (uid != null && passportId == null)
+        return { uid };
+    throw new Error('selector must name exactly one of passportId or uid, non-empty');
+}
+const COUNTER_ID = 'dppRecords';
+export class MongoDppStorage {
+    records;
+    counters;
+    ready;
+    constructor(db) {
+        this.records = db.collection('dppRecords');
+        this.counters = db.collection('dppCounters');
+    }
+    /**
+     * Indexes, and the one migration this store has ever needed: rows written
+     * before `sequence` existed are numbered in createdAt, txid, outputIndex
+     * order, so every row has a position before the first page is served and the
+     * pages of an old deployment read in the order its lookups always answered.
+     * Runs once per process on first use, and `main()` awaits it at boot so the
+     * numbering never races a request. Idempotent: a second boot finds nothing
+     * to number.
+     */
+    async ensureReady() {
+        this.ready ??= (async () => {
+            await this.records.createIndex({ passportId: 1, sequence: 1 });
+            await this.records.createIndex({ uid: 1, sequence: 1 });
+            await this.records.createIndex({ txid: 1, outputIndex: 1 }, { unique: true });
+            const legacy = this.records
+                .find({ sequence: { $exists: false } })
+                .sort({ createdAt: 1, txid: 1, outputIndex: 1 });
+            for await (const row of legacy) {
+                const sequence = await this.nextSequence();
+                // The filter repeats the existence test so a row a concurrent insert
+                // numbered in the meantime keeps the number it was given.
+                await this.records.updateOne({ txid: row.txid, outputIndex: row.outputIndex, sequence: { $exists: false } }, { $set: { sequence } });
+            }
+        })().catch((error) => {
+            this.ready = undefined;
+            throw error;
+        });
+        await this.ready;
+    }
+    /** One atomic increment per insert: the counter is the order, gaps included. */
+    async nextSequence() {
+        const counter = await this.counters.findOneAndUpdate({ _id: COUNTER_ID }, { $inc: { value: 1 } }, { upsert: true, returnDocument: 'after' });
+        if (counter == null)
+            throw new Error('the sequence counter did not answer');
+        return counter.value;
+    }
+    async insert(record) {
+        await this.ensureReady();
+        // The sequence is allotted before the row is written, so a snapshot taken
+        // between the two may pin a number whose row lands a moment later. The
+        // Engine admits one transaction at a time per request, so the window is
+        // the width of one write; a page that has already passed that position
+        // does not go back for it, and the next snapshot has it.
+        const sequence = await this.nextSequence();
+        await this.records.updateOne({ txid: record.txid, outputIndex: record.outputIndex }, 
+        // $setOnInsert: a re-admitted output keeps the position it was first
+        // given, and only its other fields are refreshed.
+        { $set: record, $setOnInsert: { sequence } }, { upsert: true });
+    }
+    async markSpent(txid, outputIndex, spendingTxid) {
+        await this.ensureReady();
+        await this.records.updateOne({ txid, outputIndex }, { $set: { spent: true, spendingTxid } });
+    }
+    async markUnspent(txid, outputIndex) {
+        await this.ensureReady();
+        await this.records.updateOne({ txid, outputIndex }, { $set: { spent: false, spendingTxid: '' } });
+    }
+    async delete(txid, outputIndex) {
+        await this.ensureReady();
+        await this.records.deleteOne({ txid, outputIndex });
+    }
+    async findByPassport(passportId) {
+        await this.ensureReady();
+        return await this.records.find({ passportId }).sort({ sequence: 1 }).toArray();
+    }
+    async findByUid(uid) {
+        await this.ensureReady();
+        return await this.records.find({ uid }).sort({ sequence: 1 }).toArray();
+    }
+    async highestSequence() {
+        await this.ensureReady();
+        const counter = await this.counters.findOne({ _id: COUNTER_ID });
+        return counter?.value ?? 0;
+    }
+    async findPage(selector, range, limit) {
+        await this.ensureReady();
+        const filter = {
+            ...selectorFilter(selector),
+            sequence: { $gt: range.after, $lte: range.upTo },
+        };
+        return await this.records.find(filter).sort({ sequence: 1 }).limit(limit).toArray();
+    }
+}
+export class InMemoryDppStorage {
+    records = new Map();
+    assigned = 0;
+    key(txid, outputIndex) {
+        return `${txid}.${outputIndex}`;
+    }
+    async insert(record) {
+        const key = this.key(record.txid, record.outputIndex);
+        // As the Mongo store: a re-admitted output keeps its first position.
+        const sequence = this.records.get(key)?.sequence ?? ++this.assigned;
+        this.records.set(key, { ...record, sequence });
+    }
+    async markSpent(txid, outputIndex, spendingTxid) {
+        const record = this.records.get(this.key(txid, outputIndex));
+        if (record != null) {
+            record.spent = true;
+            record.spendingTxid = spendingTxid;
+        }
+    }
+    async markUnspent(txid, outputIndex) {
+        const record = this.records.get(this.key(txid, outputIndex));
+        if (record != null) {
+            record.spent = false;
+            record.spendingTxid = '';
+        }
+    }
+    async delete(txid, outputIndex) {
+        this.records.delete(this.key(txid, outputIndex));
+    }
+    async findByPassport(passportId) {
+        return [...this.records.values()]
+            .filter((r) => r.passportId === passportId)
+            .sort((a, b) => a.sequence - b.sequence);
+    }
+    async findByUid(uid) {
+        return [...this.records.values()]
+            .filter((r) => r.uid === uid)
+            .sort((a, b) => a.sequence - b.sequence);
+    }
+    async highestSequence() {
+        return this.assigned;
+    }
+    async findPage(selector, range, limit) {
+        const filter = selectorFilter(selector);
+        const matches = (r) => 'passportId' in filter ? r.passportId === filter.passportId : r.uid === filter.uid;
+        return [...this.records.values()]
+            .filter((r) => matches(r) && r.sequence > range.after && r.sequence <= range.upTo)
+            .sort((a, b) => a.sequence - b.sequence)
+            .slice(0, limit);
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

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

package/dist/sync.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Peer synchronisation (`spec/services.md` section 1, operator profile
+ * `federated-operators@1`): pulling the states and anchors another operator
+ * holds, through the overlay SDK's GASP, from a declared list of peers.
+ *
+ * The SDK does the protocol: `Engine.startGASPSync` walks every topic the
+ * `syncConfiguration` names, asks each peer for the outputs it holds since
+ * the last checkpoint, fetches each unknown output's graph, checks it against
+ * Bitcoin's rules and this node's own topic managers, and admits it through
+ * `Engine.submit` as a historical transaction. Admission during
+ * synchronisation is therefore the same admission as `/submit`: a state a
+ * peer offers is admitted only under the publisher policy and the chain
+ * rules, and a peer offering anything else is refused by name in the log.
+ *
+ * This module adds what the SDK leaves to the host: reading the peers from
+ * the environment, building the configuration for the two current topics
+ * (the legacy topic only when asked), running rounds on an interval, keeping
+ * a failing peer from stopping the node or blocking a request, and logging
+ * what each round did. Discovery is static: the peers are the ones named,
+ * never ones a lookup found, so the capability document says
+ * `static-peers` and nothing here authorises a publisher.
+ */
+import type { Engine } from '@bsv/overlay';
+/** The Engine's shape for `syncConfiguration`: peers per topic, 'SHIP' for discovered peers, or false. */
+export type SyncConfiguration = Record<string, string[] | 'SHIP' | false>;
+export declare const DEFAULT_SYNC_INTERVAL_MS = 60000;
+export interface SyncSettings {
+    /** Peer base URLs, normalised: trimmed, no trailing slash, de-duplicated. */
+    peers: string[];
+    /** Milliseconds between rounds; 0 runs the round after startup and no other. */
+    intervalMs: number;
+    /** Whether the historical UORA topic synchronises too. */
+    legacy: boolean;
+}
+export declare function parseSyncPeers(value: string | undefined): string[];
+export declare function syncSettingsFromEnvironment(): SyncSettings;
+/**
+ * The Engine's configuration for the named topics: the peers for the passport
+ * and attestation topics, the legacy topic only when asked, false everywhere
+ * without peers, which is exactly the configuration the node has always run.
+ */
+export declare function syncConfigurationFor(settings: Pick<SyncSettings, 'peers' | 'legacy'>, topics: {
+    passport: string;
+    attestation: string;
+    legacy: string;
+}): SyncConfiguration;
+export interface SyncRound {
+    round: number;
+    startedAt: string;
+    durationMs: number;
+    ok: boolean;
+    error?: string;
+}
+export interface PeerSynchronisation {
+    /** Run one round now, or join the round in flight; never rejects. */
+    runOnce: () => Promise<SyncRound>;
+    /** Stop the interval; a round in flight finishes. */
+    stop: () => void;
+    /** The rounds run so far, newest last, at most the last hundred. */
+    readonly rounds: SyncRound[];
+}
+/**
+ * Rounds on an interval, each logged, none overlapping, none able to fail the
+ * node: `startGASPSync` already isolates one peer's failure from the next,
+ * and whatever escapes it is caught here and named. Requests are never
+ * blocked, because a round is ordinary asynchronous work on the same event
+ * loop and nothing awaits it but the round itself.
+ */
+export declare function startPeerSynchronisation(engine: Pick<Engine, 'startGASPSync'>, options: {
+    intervalMs: number;
+    peers: string[];
+    log?: (line: string) => void;
+    warn?: (line: string) => void;
+}): PeerSynchronisation;
+//# sourceMappingURL=sync.d.ts.map

package/dist/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAA;AAE1C,0GAA0G;AAC1G,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,KAAK,CAAC,CAAA;AAEzE,eAAO,MAAM,wBAAwB,QAAS,CAAA;AAE9C,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAA;IAClB,0DAA0D;IAC1D,MAAM,EAAE,OAAO,CAAA;CAChB;AAUD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAkBlE;AAED,wBAAgB,2BAA2B,IAAI,YAAY,CAa1D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,QAAQ,CAAC,EAChD,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAChE,iBAAiB,CAOnB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,EAAE,EAAE,OAAO,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,OAAO,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,CAAA;IACjC,qDAAqD;IACrD,IAAI,EAAE,MAAM,IAAI,CAAA;IAChB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,CAAA;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,eAAe,CAAC,EACrC,OAAO,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAC5G,mBAAmB,CAmDrB"}

package/dist/sync.js

@@ -0,0 +1,118 @@
+export const DEFAULT_SYNC_INTERVAL_MS = 60_000;
+/** Comma-separated base URLs. Anything that is not an http or https URL stops the boot; a peer is not a thing to guess. */
+/** A peer URL without its trailing slashes, scanned rather than matched so a long run of slashes costs linear time. */
+function stripTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value[end - 1] === '/')
+        end--;
+    return value.slice(0, end);
+}
+export function parseSyncPeers(value) {
+    const peers = [];
+    for (const raw of (value ?? '').split(',')) {
+        const candidate = raw.trim();
+        if (candidate === '')
+            continue;
+        let url;
+        try {
+            url = new URL(candidate);
+        }
+        catch {
+            throw new Error(`SYNC_PEERS entry "${candidate}" is not a URL`);
+        }
+        if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+            throw new Error(`SYNC_PEERS entry "${candidate}" must be an http or https URL`);
+        }
+        const normalised = stripTrailingSlashes(candidate);
+        if (!peers.includes(normalised))
+            peers.push(normalised);
+    }
+    return peers;
+}
+export function syncSettingsFromEnvironment() {
+    const peers = parseSyncPeers(process.env.SYNC_PEERS);
+    const rawInterval = (process.env.SYNC_INTERVAL_MS ?? '').trim();
+    let intervalMs = DEFAULT_SYNC_INTERVAL_MS;
+    if (rawInterval !== '') {
+        if (!/^\d+$/.test(rawInterval))
+            throw new Error('SYNC_INTERVAL_MS must be a non-negative integer of milliseconds');
+        intervalMs = Number(rawInterval);
+    }
+    const legacy = (process.env.SYNC_LEGACY ?? '').trim() === '1';
+    if (peers.length === 0 && (rawInterval !== '' || legacy)) {
+        console.warn('SYNC_INTERVAL_MS or SYNC_LEGACY is set but SYNC_PEERS is not: nothing synchronises');
+    }
+    return { peers, intervalMs, legacy };
+}
+/**
+ * The Engine's configuration for the named topics: the peers for the passport
+ * and attestation topics, the legacy topic only when asked, false everywhere
+ * without peers, which is exactly the configuration the node has always run.
+ */
+export function syncConfigurationFor(settings, topics) {
+    const peers = settings.peers.length === 0 ? false : [...settings.peers];
+    return {
+        [topics.passport]: peers,
+        [topics.attestation]: peers,
+        [topics.legacy]: settings.legacy ? peers : false,
+    };
+}
+/**
+ * Rounds on an interval, each logged, none overlapping, none able to fail the
+ * node: `startGASPSync` already isolates one peer's failure from the next,
+ * and whatever escapes it is caught here and named. Requests are never
+ * blocked, because a round is ordinary asynchronous work on the same event
+ * loop and nothing awaits it but the round itself.
+ */
+export function startPeerSynchronisation(engine, options) {
+    const log = options.log ?? ((line) => console.log(line));
+    const warn = options.warn ?? ((line) => console.warn(line));
+    const rounds = [];
+    let count = 0;
+    let inFlight;
+    const run = async () => {
+        const round = ++count;
+        const started = Date.now();
+        log(`peer synchronisation round ${round} started with ${options.peers.length} peer${options.peers.length === 1 ? '' : 's'}: ${options.peers.join(', ')}`);
+        let result;
+        try {
+            await engine.startGASPSync();
+            result = { round, startedAt: new Date(started).toISOString(), durationMs: Date.now() - started, ok: true };
+            log(`peer synchronisation round ${round} finished in ${result.durationMs} ms`);
+        }
+        catch (cause) {
+            const error = cause instanceof Error ? cause.message : String(cause);
+            result = { round, startedAt: new Date(started).toISOString(), durationMs: Date.now() - started, ok: false, error };
+            warn(`peer synchronisation round ${round} failed after ${result.durationMs} ms: ${error}`);
+        }
+        rounds.push(result);
+        if (rounds.length > 100)
+            rounds.shift();
+        return result;
+    };
+    const runOnce = () => {
+        if (inFlight == null) {
+            inFlight = run().finally(() => {
+                inFlight = undefined;
+            });
+        }
+        return inFlight;
+    };
+    let timer;
+    if (options.intervalMs > 0) {
+        timer = setInterval(() => {
+            void runOnce();
+        }, options.intervalMs);
+        timer.unref();
+    }
+    return {
+        runOnce,
+        stop: () => {
+            if (timer != null)
+                clearInterval(timer);
+            timer = undefined;
+        },
+        rounds,
+    };
+}
+//# sourceMappingURL=sync.js.map

package/dist/sync.js.map

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

package/dist/tmAttestation.d.ts

@@ -0,0 +1,36 @@
+import type { AdmittanceInstructions, TopicManager } from '@bsv/overlay';
+import type { PublisherPolicy } from '@bsv/dpp-core';
+export declare const ATTESTATION_TOPIC = "tm_attestation";
+export interface AttestationAdmissionOptions {
+    /**
+     * The publisher key policy chain (`spec/services.md` section 1), verified by
+     * the caller. When present and in force for this topic, an anchor is
+     * admitted only when its anchoring service is an anchor-publisher key active
+     * at admission time, and the static list is not consulted. Admission time,
+     * not the anchor's time: an anchor carries no timestamp, so the instant a
+     * key's window is held against is the only instant the index has. A late
+     * announcement of an anchor written under a since-retired key is therefore
+     * refused, which the operator resolves by re-announcing before retiring the
+     * key or by keeping the key active until the backlog is announced.
+     */
+    publisherPolicy?: PublisherPolicy[];
+    /** The clock admission time is read from; injectable for tests. */
+    now?: () => Date;
+}
+/** Independent anchor admission. Credential proof, authority and status require the document. */
+export declare class AttestationTopicManager implements TopicManager {
+    private readonly acceptedAnchoringServices;
+    private readonly policy?;
+    private readonly now;
+    constructor(acceptedAnchoringServices?: string[], options?: AttestationAdmissionOptions);
+    /** The anchoring services admitted at this instant; undefined means any well-formed anchor. */
+    private acceptedAt;
+    identifyAdmissibleOutputs(beef: number[]): Promise<AdmittanceInstructions>;
+    getDocumentation(): Promise<string>;
+    getMetaData(): Promise<{
+        name: string;
+        shortDescription: string;
+        version: string;
+    }>;
+}
+//# sourceMappingURL=tmAttestation.d.ts.map

package/dist/tmAttestation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmAttestation.d.ts","sourceRoot":"","sources":["../src/tmAttestation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAIpD,eAAO,MAAM,iBAAiB,mBAAmB,CAAA;AAEjD,MAAM,WAAW,2BAA2B;IAC1C;;;;;;;;;;OAUG;IACH,eAAe,CAAC,EAAE,eAAe,EAAE,CAAA;IACnC,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CACjB;AAED,iGAAiG;AACjG,qBAAa,uBAAwB,YAAW,YAAY;IAKxD,OAAO,CAAC,QAAQ,CAAC,yBAAyB;IAJ5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;gBAGb,yBAAyB,GAAE,MAAM,EAAO,EACzD,OAAO,GAAE,2BAAgC;IAM3C,+FAA+F;IAC/F,OAAO,CAAC,UAAU;IAQZ,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAa1E,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAMnC,WAAW,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAG1F"}

package/dist/tmAttestation.js

@@ -0,0 +1,50 @@
+import { Transaction } from '@bsv/sdk';
+import { decodeAttestationAnchor, ATTESTATION_ANCHOR_PREFIX } from './attestationAnchor.js';
+import { policyKeysFor } from './policyConfig.js';
+export const ATTESTATION_TOPIC = 'tm_attestation';
+/** Independent anchor admission. Credential proof, authority and status require the document. */
+export class AttestationTopicManager {
+    acceptedAnchoringServices;
+    policy;
+    now;
+    constructor(acceptedAnchoringServices = [], options = {}) {
+        this.acceptedAnchoringServices = acceptedAnchoringServices;
+        this.policy = options.publisherPolicy != null && options.publisherPolicy.length > 0 ? options.publisherPolicy : undefined;
+        this.now = options.now ?? (() => new Date());
+    }
+    /** The anchoring services admitted at this instant; undefined means any well-formed anchor. */
+    acceptedAt(at) {
+        if (this.policy != null) {
+            const keys = policyKeysFor(this.policy, at, 'anchor-publisher', ATTESTATION_TOPIC);
+            if (keys != null)
+                return keys;
+        }
+        return this.acceptedAnchoringServices.length === 0 ? undefined : this.acceptedAnchoringServices;
+    }
+    async identifyAdmissibleOutputs(beef) {
+        const outputsToAdmit = [];
+        try {
+            const transaction = Transaction.fromBEEF(beef);
+            if (!Array.isArray(transaction.inputs) || transaction.inputs.length === 0 || !Array.isArray(transaction.outputs) || transaction.outputs.length === 0)
+                return { outputsToAdmit: [], coinsToRetain: [] };
+            const accepted = this.acceptedAt(this.now());
+            for (let index = 0; index < transaction.outputs.length; index++) {
+                const anchor = decodeAttestationAnchor(transaction.outputs[index].lockingScript);
+                if (anchor && (accepted == null || accepted.includes(anchor.anchoredBy)))
+                    outputsToAdmit.push(index);
+            }
+        }
+        catch { /* Invalid transaction input admits no outputs. */ }
+        return { outputsToAdmit, coinsToRetain: [] };
+    }
+    async getDocumentation() {
+        const policy = this.policy == null
+            ? ''
+            : ' This index admits anchors only from anchor-publisher keys active at admission time under its publisher key policy (spec/services.md section 1); an anchor carries no timestamp, so admission time is the instant held against the key window. GET /capabilities lists the keys active now.';
+        return `${ATTESTATION_TOPIC} admits ${ATTESTATION_ANCHOR_PREFIX} outputs with ten fields and an exact five-OP_2DROP tail. The anchoring service signs nine length-prefixed fields. The digest commits to the complete secured representation. Carried issuer/subject/type/representation/media metadata must be checked against that document. Admission proves anchoring-service attribution, not credential validity, issuer authority, status, availability or VSC conformance. Legacy UORA layouts belong to their separately named historical topic.${policy}`;
+    }
+    async getMetaData() {
+        return { name: ATTESTATION_TOPIC, shortDescription: 'BSV attestation commitments with explicit representation formats', version: '1.1.0' };
+    }
+}
+//# sourceMappingURL=tmAttestation.js.map

package/dist/tmAttestation.js.map

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

package/dist/tmDpp.d.ts

@@ -0,0 +1,154 @@
+import type { AdmittanceInstructions, Storage, TopicManager } from '@bsv/overlay';
+import { type PublisherPolicy } from '@bsv/dpp-core';
+export declare const DPP_TOPIC = "tm_dpp";
+/**
+ * tm_dpp - DPP Token Standard admission, versions 1 and 2
+ * (`spec/record-model.md` §6 and §8, `spec/record-model-v2.md` §6 and §8).
+ *
+ * Admits a transaction's single DPP output when:
+ * - exactly one well-formed DPP output exists (invariant 1; field rules are
+ *   enforced by the dpp-core codec at parse time),
+ * - user_signature verifies against actor_identity_key + actor_keyID,
+ * - server_signature verifies against the configured service key
+ *   (admission policy, not token validity - §5),
+ * - genesis states satisfy the genesis rules. Non-genesis states spend the
+ *   previously admitted tip (invariant 4, via previousCoins) and satisfy the
+ *   per-link transition rules (invariants 5–7).
+ *
+ * Spent tips are retained (coinsToRetain) so the lifecycle history stays
+ * resolvable (§1: the spend history is the passport's lifecycle).
+ *
+ * One rule is a profile's choice rather than the record model's, and this
+ * manager enforces it only when told to: the owner-signed transfer of
+ * `spec/custody.md` §4, under which a TRANSFER is admitted only when its actor
+ * proves it is the previous owner, by equality or by owner_linkage, or is a
+ * named transfer authority. It is admission policy of the same kind as the
+ * service signature, and the topic documentation says whether this instance
+ * enforces it, so a writer learns the rule from the index and not from a
+ * refusal (`spec/services.md` §6).
+ */
+export interface DppAdmissionOptions {
+    /**
+     * The owner-signed transfer (`spec/custody.md` §4). `true` runs the predicate
+     * on every TRANSFER; an object also names the transfer authorities, identity
+     * keys whose TRANSFER is admitted without proof (recovery). Off by default:
+     * the record model's baseline admits any signed TRANSFER that spends the tip.
+     * A malformed authority throws at construction, so a misconfigured
+     * deployment fails to boot rather than silently never matching.
+     */
+    ownerConsent?: boolean | {
+        authorities: string[];
+    };
+    /**
+     * The publisher key policy chain (`spec/services.md` §1), already verified
+     * by the caller with `verifyPolicyChain`. When present and in force for this
+     * topic, a state's countersignature is accepted only from a state-publisher
+     * key active at the state's own timestamp, and the positional identity key
+     * is not consulted: a retired key still admits the states it signed while
+     * active, and a key admits nothing timestamped before its activation.
+     * Absent, the identity key is the whole policy, as it always was.
+     */
+    publisherPolicy?: PublisherPolicy[];
+    /**
+     * Authorities for version 2 control proofs (`spec/record-model-v2.md` §6):
+     * identity keys whose UPDATE, TRANSFER or RETIRE is admitted without a
+     * control proof. Defaults to the `ownerConsent` authorities, so one list
+     * serves both versions unless a deployment names another. Malformed keys
+     * throw at construction.
+     */
+    controlAuthorities?: string[];
+    /**
+     * The managed-custody profile (`spec/managed-custody.md`): when selected, a
+     * version 2 TRANSFER is admitted only when it carries an
+     * `authorisation_commitment`. Off by default: the record model admits a
+     * TRANSFER with an empty commitment, and the topic documentation says which
+     * this instance runs.
+     */
+    managedAcceptance?: boolean;
+    /**
+     * The engine's own storage, so the manager can read an admitted
+     * predecessor's locking script when the BEEF it is handed does not carry
+     * the predecessor's bytes. Two callers hand it such a BEEF: a writer that
+     * announces a proven state alone, and the SDK's peer synchronisation, whose
+     * per-node BEEF stops at the node's proof and whose admission emulation
+     * lists as previous coins only what the temporary graph holds. Absent, the
+     * manager sees only what the BEEF and its own recent memory show, as it
+     * always did.
+     */
+    admittedOutputs?: Pick<Storage, 'findOutput'> & Partial<Pick<Storage, 'findOutputsForTransaction'>>;
+}
+export declare class DppTopicManager implements TopicManager {
+    private readonly serverIdentityKey;
+    private readonly consentSelected;
+    private readonly authorities;
+    private readonly controlAuthorities;
+    private readonly managedAcceptance;
+    private readonly policy?;
+    private readonly admitted?;
+    /** States inspected recently, by txid: the predecessor a synchronisation pass showed one call ago. */
+    private readonly recent;
+    constructor(serverIdentityKey: string, options?: DppAdmissionOptions);
+    /**
+     * The keys this state's countersignature may come from: under a policy, the
+     * state-publisher keys active at the state's timestamp; otherwise the one
+     * configured identity key. The state's own timestamp is the instant that
+     * matters, not the admission time, because a state announced late is still
+     * the state it was when it was signed.
+     */
+    private publisherKeysFor;
+    private remember;
+    /**
+     * The predecessor's locking script for one input, from the nearest source
+     * that has it: the hydrated input, the submitted BEEF, the engine's storage,
+     * and, on the historical paths only, the manager's recent memory. The txid
+     * the input names commits to the bytes each source yields, so none of them
+     * is trusted more than another; they differ only in who happened to hand
+     * the bytes over. Memory is kept for the synchronisation pass, where the SDK
+     * validates a graph one state at a time before any of it reaches storage;
+     * on the live path a writer's proven state announced without its parent is
+     * judged against what the index holds, never against what it happened to
+     * see, so the contract a submitter is held to stays the one it always was.
+     */
+    private predecessorScript;
+    /**
+     * The genesis outpoint of the lineage a version 2 successor must name
+     * (`spec/record-model-v2.md` §6). A version 2 predecessor carries it; the
+     * ISSUE is it. A version 1 predecessor carries none, so the manager walks
+     * the admitted history back to the genesis through the same sources the
+     * predecessor's own bytes came from: the submitted BEEF, the engine's
+     * storage, and on the historical paths its recent memory. Undefined when
+     * the walk cannot be completed, which refuses the state: a lineage this
+     * index cannot trace is not one it can vouch for.
+     */
+    private lineageGenesisFor;
+    /** The admitted DPP state a transaction carries, by txid, from the BEEF, the engine's storage or recent memory. */
+    private stateAt;
+    /**
+     * The inputs to treat as previously admitted coins. The Engine names them
+     * on the live path; the synchronisation emulation names only what its
+     * temporary graph holds, which for a state on top of a lineage this index
+     * already has is nothing. Then, and only when the storage is at hand, the
+     * inputs that spend an output this index has admitted for the topic stand
+     * in, which is the same question the Engine answers on the live path.
+     */
+    private previousCoinsFor;
+    identifyAdmissibleOutputs(beef: number[], previousCoins: number[], _offChainValues?: number[], mode?: 'historical-tx' | 'current-tx' | 'historical-tx-no-spv'): Promise<AdmittanceInstructions>;
+    /**
+     * What a synchronising peer must fetch before this state can be judged: the
+     * input that spends the predecessor, when the state is not a genesis. The
+     * SDK asks this only for a proven state it could not admit alone, and drops
+     * any input this index already holds, so the answer is the predecessor and
+     * nothing else. Anything that does not decode as one DPP state needs nothing.
+     */
+    identifyNeededInputs(beef: number[]): Promise<Array<{
+        txid: string;
+        outputIndex: number;
+    }>>;
+    getDocumentation(): Promise<string>;
+    getMetaData(): Promise<{
+        name: string;
+        shortDescription: string;
+        version?: string;
+    }>;
+}
+//# sourceMappingURL=tmDpp.d.ts.map

package/dist/tmDpp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmDpp.d.ts","sourceRoot":"","sources":["../src/tmDpp.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AACjF,OAAO,EAaL,KAAK,eAAe,EACrB,MAAM,eAAe,CAAA;AAGtB,eAAO,MAAM,SAAS,WAAW,CAAA;AAqBjC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG;QAAE,WAAW,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;IAClD;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,eAAe,EAAE,CAAA;IACnC;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC7B;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAA;CACpG;AAED,qBAAa,eAAgB,YAAW,YAAY;IAWhD,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAVpC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;IACtC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAU;IAC7C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAmF;IAC7G,sGAAsG;IACtG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;gBAGrC,iBAAiB,EAAE,MAAM,EAC1C,OAAO,GAAE,mBAAwB;IAanC;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,QAAQ;IAUhB;;;;;;;;;;;OAWG;YACW,iBAAiB;IAsB/B;;;;;;;;;OASG;YACW,iBAAiB;IAuB/B,mHAAmH;YACrG,OAAO;IA2BrB;;;;;;;OAOG;YACW,gBAAgB;IAWxB,yBAAyB,CAC7B,IAAI,EAAE,MAAM,EAAE,EACd,aAAa,EAAE,MAAM,EAAE,EACvB,eAAe,CAAC,EAAE,MAAM,EAAE,EAC1B,IAAI,CAAC,EAAE,eAAe,GAAG,YAAY,GAAG,sBAAsB,GAC7D,OAAO,CAAC,sBAAsB,CAAC;IA4IlC;;;;;;OAMG;IACG,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAe3F,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IA6DnC,WAAW,IAAI,OAAO,CAAC;QAC3B,IAAI,EAAE,MAAM,CAAA;QACZ,gBAAgB,EAAE,MAAM,CAAA;QACxB,OAAO,CAAC,EAAE,MAAM,CAAA;KACjB,CAAC;CAOH"}