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

package/dist/lsUoraDpp.js

@@ -0,0 +1,152 @@
+import { tryParseUoraAnchor, UORA_ANCHOR_PREFIX } from './uoraAnchor.js';
+export const UORA_TOPIC = 'tm_uora_dpp';
+export const UORA_SERVICE = 'ls_uora_dpp';
+/**
+ * `ls_uora_dpp`: the DID-keyed lookup.
+ *
+ * The question this exists to answer is "what has this party attested", keyed
+ * on the issuer's `did:key`, and it is the question no index over the v1 anchor
+ * format could answer at all: a v1 anchor names no issuer, so an indexer
+ * holding one has a digest and no idea whose claim it covers.
+ *
+ * Four other selectors come free from the same fields and are worth having:
+ * the subject (every claim about one passport, from every party), the
+ * attestation id (the anchor for one known claim), the digest (given an
+ * attestation in hand, has anyone anchored exactly this), and the UORA type,
+ * which narrows any of the others.
+ *
+ * ## What the answer is, and what it is not
+ *
+ * The answer is outputs, as BRC-24 requires, so the caller receives the anchors
+ * as chain data and checks them without trusting this service. That matters
+ * more here than for a passport lookup: this index is derived from the outputs,
+ * so an index that lied would be caught by the caller reading the same outputs
+ * it just returned.
+ *
+ * The answer is **not** the attestations. Those are never on chain, by the
+ * privacy rule, so a caller who wants the claim itself fetches it from the
+ * resolver and checks its digest against the anchor this returned. The anchor
+ * is the proof; the resolver is merely convenient.
+ */
+export class UoraAnchorLookupService {
+    storage;
+    admissionMode = 'locking-script';
+    spendNotificationMode = 'txid';
+    constructor(storage) {
+        this.storage = storage;
+    }
+    async outputAdmittedByTopic(payload) {
+        if (payload.mode !== 'locking-script')
+            throw new Error('Invalid admission mode');
+        if (payload.topic !== UORA_TOPIC)
+            return;
+        const anchor = tryParseUoraAnchor(payload.lockingScript);
+        // Admission already validated this; a null here would mean the topic
+        // manager and this service disagree, and indexing a half-read output is
+        // worse than not indexing it.
+        if (anchor == null)
+            return;
+        await this.storage.insert({
+            txid: payload.txid,
+            outputIndex: payload.outputIndex,
+            digest: anchor.digest,
+            attestationId: anchor.attestationId,
+            issuer: anchor.issuer,
+            issuerKey: anchor.issuerKey,
+            subject: anchor.subject,
+            uoraType: anchor.uoraType,
+            anchoredBy: anchor.anchoredBy,
+            lockingKey: anchor.lockingKey,
+            createdAt: new Date(),
+        });
+    }
+    /**
+     * An anchor is a leaf and should never be spent. If one is, the claim it
+     * carries is unaffected: the digest sat at that point in the chain's order
+     * whatever later happened to the satoshi. So the record stays, and the spend
+     * is not recorded, because nothing about this index turns on it.
+     */
+    async outputSpent(payload) {
+        if (payload.mode !== 'txid')
+            throw new Error('Invalid spend notification mode');
+    }
+    async outputNoLongerRetainedInHistory(txid, outputIndex, topic) {
+        if (topic !== UORA_TOPIC)
+            return;
+        await this.storage.delete(txid, outputIndex);
+    }
+    async outputEvicted(txid, outputIndex) {
+        await this.storage.delete(txid, outputIndex);
+    }
+    async lookup(question) {
+        if (question.service !== UORA_SERVICE) {
+            throw new Error(`Unsupported service ${question.service}`);
+        }
+        const query = (question.query ?? {});
+        // Refused rather than ignored: `selectors()` in the storage layer would
+        // drop a non-string field, and a query that silently loses a selector
+        // answers broader than it was asked, up to a full scan under the cap.
+        const fields = [
+            'issuer',
+            'issuerKey',
+            'subject',
+            'attestationId',
+            'digest',
+            'uoraType',
+            'anchoredBy',
+        ];
+        for (const field of fields) {
+            const value = query[field];
+            if (value != null && typeof value !== 'string') {
+                throw new Error(`Query field ${field} must be a string`);
+            }
+        }
+        // `uoraType` alone is every anchor of a common type, which is a table scan
+        // wearing a query, so it narrows and never selects.
+        const selective = [
+            query.issuer,
+            query.issuerKey,
+            query.subject,
+            query.attestationId,
+            query.digest,
+            query.anchoredBy,
+        ].some((value) => typeof value === 'string' && value !== '');
+        if (!selective) {
+            throw new Error('Query must provide issuer, issuerKey, subject, attestationId, digest or anchoredBy');
+        }
+        const records = await this.storage.find(query);
+        return records.map((record) => ({ txid: record.txid, outputIndex: record.outputIndex }));
+    }
+    async getDocumentation() {
+        return [
+            `# ${UORA_SERVICE}`,
+            '',
+            `Lookup for ${UORA_ANCHOR_PREFIX} attestation anchors, keyed on the issuer DID.`,
+            '',
+            'Query with at least one of `issuer` (a did:key), `issuerKey` (the same',
+            'key as hex), `subject` (a passport id), `attestationId`, `digest`, or',
+            '`anchoredBy` (the treasury that wrote the anchor). `uoraType` narrows any',
+            'of them and cannot select on its own. All are',
+            'exact matches. `limit` caps the answer and is itself capped.',
+            '',
+            'Every indexed field is one the anchoring service signed, at the boundary',
+            'it is read at: the signature covers each field behind its length, so the',
+            'subject this index is keyed on is the subject that was written. Anchors',
+            'in the superseded uora-anchor-v2 layout are not admitted and are',
+            'therefore not indexed, because their signature left that boundary open.',
+            '',
+            'The answer is the anchor outputs as BEEF, so the caller verifies them',
+            'against the chain rather than trusting this index. The attestations',
+            'themselves are never on chain: fetch one from the resolver and check its',
+            "canonical digest against the anchor's.",
+        ].join('\n');
+    }
+    async getMetaData() {
+        return {
+            name: UORA_SERVICE,
+            shortDescription: 'UORA attestation anchor lookup, keyed on issuer DID',
+            version: '1.0.0',
+        };
+    }
+}
+//# sourceMappingURL=lsUoraDpp.js.map

package/dist/lsUoraDpp.js.map

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

package/dist/policyConfig.d.ts

@@ -0,0 +1,31 @@
+import { type PublisherPolicy, type PublisherRole } from '@bsv/dpp-core';
+export interface PublisherPolicyConfig {
+    /** The verified chain, oldest first. */
+    chain: PublisherPolicy[];
+    /** Operator identifier to compressed identity key, from the environment. */
+    operators: Record<string, string>;
+    /** The versions `verifyPolicyChain` accepted, in chain order. */
+    versions: number[];
+    /** Where the chain came from, for logs. */
+    source: string;
+}
+/** `operator=compressedKey` pairs, comma-separated. Malformed input stops the boot rather than naming no operator. */
+export declare function parseOperatorIdentityKeys(value: string | undefined): Record<string, string>;
+/** Read and verify a chain file. Every failure is an Error whose message names the file, the version and the reason. */
+export declare function loadPublisherPolicy(file: string, operators: Record<string, string>): PublisherPolicyConfig;
+/** The policy the environment configures, or undefined when it configures none. */
+export declare function publisherPolicyFromEnvironment(): PublisherPolicyConfig | undefined;
+/**
+ * The publisher keys a topic accepts at an instant under the chain.
+ *
+ * `undefined` means the version in force does not cover the topic: a policy
+ * may name `scope.topics`, and a topic outside them keeps its static
+ * configuration (the identity key, or ANCHOR_SERVICE_KEYS). An empty array
+ * means the policy covers the topic and no key is active, which admits
+ * nothing, and is also the answer for an instant before the first version was
+ * issued: a key admits nothing dated before its activation.
+ */
+export declare function policyKeysFor(chain: PublisherPolicy[], at: string | Date, role: PublisherRole, topic: string): string[] | undefined;
+/** The newest version of the chain, the one that names the operator profile and the current keys. */
+export declare function newestPolicy(config: PublisherPolicyConfig): PublisherPolicy;
+//# sourceMappingURL=policyConfig.d.ts.map

package/dist/policyConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policyConfig.d.ts","sourceRoot":"","sources":["../src/policyConfig.ts"],"names":[],"mappings":"AAkBA,OAAO,EAIL,KAAK,eAAe,EACpB,KAAK,aAAa,EACnB,MAAM,eAAe,CAAA;AAEtB,MAAM,WAAW,qBAAqB;IACpC,wCAAwC;IACxC,KAAK,EAAE,eAAe,EAAE,CAAA;IACxB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACjC,iEAAiE;IACjE,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAA;CACf;AAID,sHAAsH;AACtH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAyB3F;AAED,wHAAwH;AACxH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,qBAAqB,CAyB1G;AAED,mFAAmF;AACnF,wBAAgB,8BAA8B,IAAI,qBAAqB,GAAG,SAAS,CAalF;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,eAAe,EAAE,EACxB,EAAE,EAAE,MAAM,GAAG,IAAI,EACjB,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,MAAM,GACZ,MAAM,EAAE,GAAG,SAAS,CAKtB;AAED,qGAAqG;AACrG,wBAAgB,YAAY,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAE3E"}

package/dist/policyConfig.js

@@ -0,0 +1,112 @@
+/**
+ * The publisher key policy as this node is configured with it
+ * (`spec/services.md` section 1, `contracts/publisher-policy.schema.json`).
+ *
+ * `PUBLISHER_POLICY_FILE` names a JSON file holding the chain of
+ * `dpp-publisher-policy@1` versions, oldest first, and `OPERATOR_IDENTITY_KEYS`
+ * names each operator's identity key, because the chain's genesis is signed
+ * by an operator and the policy itself is never the source of the key that
+ * authorises it. The chain is verified once, at boot, with the core's
+ * `verifyPolicyChain`; a chain that does not verify stops the boot and names
+ * the version and the reason, since admitting under an unverified list would
+ * be admitting under whatever a file said.
+ *
+ * Without a policy file nothing here is consulted: the single
+ * `SERVICE_IDENTITY_KEY` is an implicit single-operator policy with no
+ * rotation history, and the capability document says so.
+ */
+import { readFileSync } from 'node:fs';
+import { policyInForceAt, publisherKeysAt, verifyPolicyChain, } from '@bsv/dpp-core';
+const COMPRESSED_KEY = /^0[23][0-9a-f]{64}$/;
+/** `operator=compressedKey` pairs, comma-separated. Malformed input stops the boot rather than naming no operator. */
+export function parseOperatorIdentityKeys(value) {
+    const operators = {};
+    const pairs = (value ?? '')
+        .split(',')
+        .map((pair) => pair.trim())
+        .filter((pair) => pair !== '');
+    for (const pair of pairs) {
+        const separator = pair.indexOf('=');
+        if (separator <= 0) {
+            throw new Error(`OPERATOR_IDENTITY_KEYS entry "${pair}" is not of the form operator=compressedKey`);
+        }
+        const operator = pair.slice(0, separator).trim();
+        const key = pair.slice(separator + 1).trim();
+        if (!COMPRESSED_KEY.test(key)) {
+            throw new Error(`OPERATOR_IDENTITY_KEYS: the key given for ${operator} is not a compressed public key`);
+        }
+        if (operators[operator] != null)
+            throw new Error(`OPERATOR_IDENTITY_KEYS names ${operator} twice`);
+        // One key under two names would let it sign a federation rotation and
+        // countersign it as "another operator": the whole point of the
+        // countersignature is that it comes from a different key.
+        const holder = Object.entries(operators).find(([, existing]) => existing === key)?.[0];
+        if (holder != null)
+            throw new Error(`OPERATOR_IDENTITY_KEYS gives ${operator} the same key as ${holder}`);
+        operators[operator] = key;
+    }
+    return operators;
+}
+/** Read and verify a chain file. Every failure is an Error whose message names the file, the version and the reason. */
+export function loadPublisherPolicy(file, operators) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch (cause) {
+        throw new Error(`PUBLISHER_POLICY_FILE ${file} could not be read: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`PUBLISHER_POLICY_FILE ${file} is not JSON`);
+    }
+    if (!Array.isArray(parsed) || parsed.some((p) => typeof p !== 'object' || p === null || Array.isArray(p))) {
+        throw new Error(`PUBLISHER_POLICY_FILE ${file} must hold a JSON array of dpp-publisher-policy@1 documents, oldest first`);
+    }
+    const chain = parsed;
+    const result = verifyPolicyChain(chain, operators);
+    if (!result.ok || result.failure != null) {
+        const failure = result.failure ?? { version: 0, reason: 'format', detail: 'the chain did not verify' };
+        throw new Error(`PUBLISHER_POLICY_FILE ${file}: policy version ${failure.version} refused, ${failure.reason}: ${failure.detail}`);
+    }
+    return { chain, operators, versions: result.versions, source: file };
+}
+/** The policy the environment configures, or undefined when it configures none. */
+export function publisherPolicyFromEnvironment() {
+    const file = (process.env.PUBLISHER_POLICY_FILE ?? '').trim();
+    const operators = process.env.OPERATOR_IDENTITY_KEYS;
+    if (file === '') {
+        if (operators != null && operators.trim() !== '') {
+            console.warn('OPERATOR_IDENTITY_KEYS is set but PUBLISHER_POLICY_FILE is not: the operator keys are ignored, ' +
+                'because there is no policy chain for them to authorise');
+        }
+        return undefined;
+    }
+    return loadPublisherPolicy(file, parseOperatorIdentityKeys(operators));
+}
+/**
+ * The publisher keys a topic accepts at an instant under the chain.
+ *
+ * `undefined` means the version in force does not cover the topic: a policy
+ * may name `scope.topics`, and a topic outside them keeps its static
+ * configuration (the identity key, or ANCHOR_SERVICE_KEYS). An empty array
+ * means the policy covers the topic and no key is active, which admits
+ * nothing, and is also the answer for an instant before the first version was
+ * issued: a key admits nothing dated before its activation.
+ */
+export function policyKeysFor(chain, at, role, topic) {
+    const inForce = policyInForceAt(chain, at);
+    if (inForce == null)
+        return [];
+    if (inForce.scope.topics != null && !inForce.scope.topics.includes(topic))
+        return undefined;
+    return publisherKeysAt(chain, at, role);
+}
+/** The newest version of the chain, the one that names the operator profile and the current keys. */
+export function newestPolicy(config) {
+    return config.chain[config.chain.length - 1];
+}
+//# sourceMappingURL=policyConfig.js.map

package/dist/policyConfig.js.map

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

package/dist/retraction.d.ts

@@ -0,0 +1,41 @@
+import type { LookupService } from '@bsv/overlay';
+import type { RetractableStorage } from './engineStorage.js';
+import type { DppRecordStore } from './storage.js';
+export type RetractionRefusalCode = 'output-unknown' | 'retraction-refused' | 'chain-tracker-unavailable';
+export declare class RetractionRefused extends Error {
+    readonly status: number;
+    readonly code: RetractionRefusalCode;
+    constructor(status: number, code: RetractionRefusalCode, message: string);
+}
+export interface RetractionRequest {
+    storage: RetractableStorage;
+    lookupServices: Record<string, LookupService>;
+    records: DppRecordStore;
+    topic: string;
+    txid: string;
+    outputIndex: number;
+    reason: string;
+    /**
+     * Whether the network knows the transaction, asked of the configured chain
+     * tracker's source. Undefined when the deployment has no header source
+     * (CHAIN_TRACKER=scripts-only): the check is then not run, and the answer
+     * says so.
+     */
+    knownOnChain?: (txid: string) => Promise<boolean>;
+}
+export interface Retraction {
+    txid: string;
+    outputIndex: number;
+    reason: string;
+    /** Whether the network was asked; false under scripts-only, where the local proof check is the whole check. */
+    networkChecked: boolean;
+    /** The predecessor made the tip again, when the retracted state had one. */
+    restoredTip?: {
+        txid: string;
+        outputIndex: number;
+    };
+    /** Repairs the engine storage could not make, by name, when it is not one of this package's. */
+    unrepaired: string[];
+}
+export declare function retractOutput(request: RetractionRequest): Promise<Retraction>;
+//# sourceMappingURL=retraction.d.ts.map

package/dist/retraction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retraction.d.ts","sourceRoot":"","sources":["../src/retraction.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,aAAa,EAAU,MAAM,cAAc,CAAA;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAElD,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,GAAG,oBAAoB,GAAG,2BAA2B,CAAA;AAEzG,qBAAa,iBAAkB,SAAQ,KAAK;IAExC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,qBAAqB;gBAD3B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,qBAAqB,EACpC,OAAO,EAAE,MAAM;CAIlB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,kBAAkB,CAAA;IAC3B,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IAC7C,OAAO,EAAE,cAAc,CAAA;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAClD;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,+GAA+G;IAC/G,cAAc,EAAE,OAAO,CAAA;IACvB,4EAA4E;IAC5E,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;IACnD,gGAAgG;IAChG,UAAU,EAAE,MAAM,EAAE,CAAA;CACrB;AAyBD,wBAAsB,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAiFnF"}

package/dist/retraction.js

@@ -0,0 +1,147 @@
+/**
+ * Retraction (`POST /retract`): removing a state the index admitted on
+ * announcement and the network then refused.
+ *
+ * `spec/writing.md` lets a writer announce a state before it sends it, so the
+ * index can hold an output no block will ever contain. That phantom sits on
+ * the passport as its tip: the writer's next state builds on nothing, and a
+ * reader's `chainFromBeef` finds two successors of one state and can order
+ * neither. The writer, who alone knows the network's answer, asks the index
+ * to forget the output.
+ *
+ * What is never retracted: a state with a merkle path (the network did take
+ * it), a state the configured chain tracker knows (same), and a spent state
+ * (its successor was admitted against it; retracting the middle of a history
+ * would leave the successor pointing at nothing).
+ *
+ * How the removal is done. The Engine's own removal path is its stale-output
+ * eviction, `deleteUTXODeep`: delete the output, tell every lookup service it
+ * is no longer retained, then recurse into the outputs it consumed and delete
+ * each of those too once nothing else consumes them. That recursion is right
+ * for the Engine's own case, a topic that did not retain a spent coin, and
+ * wrong here: on a history-retaining topic the consumed lineage is the whole
+ * lifecycle, and the retraction of one phantom would erase the passport back
+ * to its genesis. `deleteUTXODeep` is also private to the Engine. So this
+ * module performs the eviction's first step through the same storage and
+ * lookup-service calls (`deleteOutput`, then the eviction hook), repairs the
+ * predecessor's `consumedBy` exactly as the eviction does, and stops there;
+ * then it makes the two repairs the eviction never needs, clearing the
+ * predecessor's spent mark and the phantom's applied-transaction record, so
+ * the real tip is a tip again and the same transaction can be announced
+ * again should the network take it after all.
+ */
+import { Beef } from '@bsv/sdk';
+export class RetractionRefused extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+/** Whether the stored BEEF proves the transaction: a bump for its txid, or a merkle path on it. */
+function beefProves(beef, txid) {
+    if (beef == null)
+        return false;
+    try {
+        const parsed = Beef.fromBinary(beef);
+        const held = parsed.findTxid(txid);
+        return held != null && (held.bumpIndex != null || held.tx?.merklePath != null);
+    }
+    catch {
+        return false;
+    }
+}
+/** Why an output as it stands may not be retracted, or undefined when it may. */
+function refusalFor(output, txid) {
+    if (output.spent || output.consumedBy.length > 0) {
+        return 'the output is spent: a later state was admitted against it, and a history is never cut in the middle';
+    }
+    if (output.blockHeight != null || beefProves(output.beef, txid)) {
+        return 'this index holds a merkle path for the output: the network took the transaction, so there is nothing to retract';
+    }
+    return undefined;
+}
+export async function retractOutput(request) {
+    const { storage, topic, txid, outputIndex } = request;
+    const output = await storage.findOutput(txid, outputIndex, topic, undefined, true);
+    if (output == null) {
+        throw new RetractionRefused(404, 'output-unknown', `this index holds no ${topic} output ${txid}:${outputIndex}`);
+    }
+    const refusal = refusalFor(output, txid);
+    if (refusal != null)
+        throw new RetractionRefused(409, 'retraction-refused', refusal);
+    let networkChecked = false;
+    if (request.knownOnChain != null) {
+        let known;
+        try {
+            known = await request.knownOnChain(txid);
+        }
+        catch (cause) {
+            throw new RetractionRefused(503, 'chain-tracker-unavailable', `the chain tracker could not be asked whether it knows ${txid}; the retraction was not applied, try again: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+        if (known) {
+            throw new RetractionRefused(409, 'retraction-refused', 'the chain tracker knows this transaction: the network took it, so there is nothing to retract');
+        }
+        networkChecked = true;
+    }
+    // Nothing here is atomic with the Engine: while the network was asked, a
+    // /submit may have admitted a successor or an /arc-ingest may have proven
+    // the output. So the output is read again immediately before the delete
+    // and refused if it no longer qualifies; the window left is the delete
+    // itself, which the storage interface gives no way to close.
+    const current = await storage.findOutput(txid, outputIndex, topic, undefined, true);
+    if (current == null) {
+        throw new RetractionRefused(404, 'output-unknown', `this index no longer holds ${topic} output ${txid}:${outputIndex}`);
+    }
+    const changed = refusalFor(current, txid);
+    if (changed != null) {
+        throw new RetractionRefused(409, 'retraction-refused', `the output changed while the retraction was being checked and nothing was removed: ${changed}`);
+    }
+    // The eviction's first step, through the same calls it makes.
+    await storage.deleteOutput(txid, outputIndex, topic);
+    for (const service of Object.values(request.lookupServices)) {
+        try {
+            await service.outputEvicted(txid, outputIndex);
+        }
+        catch (cause) {
+            console.error(`retraction of ${txid}:${outputIndex}: a lookup service failed to evict it:`, cause);
+        }
+    }
+    // The eviction's repair of the predecessor, then the two it never needs.
+    const unrepaired = [];
+    let restoredTip;
+    for (const consumed of output.outputsConsumed) {
+        const predecessor = await storage.findOutput(consumed.txid, consumed.outputIndex, topic);
+        if (predecessor == null)
+            continue;
+        const consumedBy = predecessor.consumedBy.filter((c) => !(c.txid === txid && c.outputIndex === outputIndex));
+        await storage.updateConsumedBy(consumed.txid, consumed.outputIndex, topic, consumedBy);
+        if (consumedBy.length > 0)
+            continue;
+        if (storage.markUTXOAsUnspent != null) {
+            await storage.markUTXOAsUnspent(consumed.txid, consumed.outputIndex, topic);
+        }
+        else {
+            unrepaired.push(`engine storage still marks ${consumed.txid}:${consumed.outputIndex} spent`);
+        }
+        await request.records.markUnspent(consumed.txid, consumed.outputIndex);
+        restoredTip = { txid: consumed.txid, outputIndex: consumed.outputIndex };
+    }
+    if (storage.deleteAppliedTransaction != null) {
+        await storage.deleteAppliedTransaction(txid, topic);
+    }
+    else {
+        unrepaired.push(`engine storage still records ${txid} as applied to ${topic}, so a re-announcement would be skipped as a duplicate`);
+    }
+    return {
+        txid,
+        outputIndex,
+        reason: request.reason,
+        networkChecked,
+        ...(restoredTip == null ? {} : { restoredTip }),
+        unrepaired,
+    };
+}
+//# sourceMappingURL=retraction.js.map

package/dist/retraction.js.map

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

package/dist/storage.d.ts

@@ -0,0 +1,117 @@
+import type { Db } from 'mongodb';
+/** One indexed DPP state (admitted output, kept after spend as history). */
+export interface DppRecord {
+    txid: string;
+    outputIndex: number;
+    passportId: string;
+    /** Chip UID from the payload's data-carrier property; '' when absent. */
+    uid: string;
+    op: string;
+    timestamp: string;
+    previousTxid: string;
+    spent: boolean;
+    /** txid of the state that spent this one; '' while unspent. */
+    spendingTxid: string;
+    createdAt: Date;
+    /**
+     * The store's own insertion sequence: assigned once, at insert, and never
+     * rewritten. It is the order `spec/portable-evidence.md` section 1 pages by,
+     * so two readers of one snapshot receive the same pages and a cursor names
+     * a position that a concurrent insert cannot shift. Rows written before the
+     * field existed are numbered at boot in createdAt, txid, outputIndex order,
+     * which is the order the bounded lookup has always answered them in.
+     */
+    sequence: number;
+}
+/** What the lookup service hands the store; the store assigns `sequence`. */
+export type DppRecordInput = Omit<DppRecord, 'sequence'>;
+/** Which records a page or an export is about: one of the two keys, non-empty. */
+export interface RecordSelector {
+    passportId?: string;
+    uid?: string;
+}
+/** The sequences a page reads: after < sequence <= upTo. */
+export interface SequenceRange {
+    after: number;
+    upTo: number;
+}
+/**
+ * Record store for ls_dpp. Abstract so tests (and the backend dev mode) can
+ * run in memory; production uses Mongo via the overlay's lookup-service
+ * factory.
+ */
+export interface DppRecordStore {
+    insert: (record: DppRecordInput) => Promise<void>;
+    markSpent: (txid: string, outputIndex: number, spendingTxid: string) => Promise<void>;
+    /**
+     * Undo `markSpent`: the state that spent this one was retracted, an announced
+     * transaction the network refused (`POST /retract`), so this one is the tip
+     * again.
+     */
+    markUnspent: (txid: string, outputIndex: number) => Promise<void>;
+    delete: (txid: string, outputIndex: number) => Promise<void>;
+    findByPassport: (passportId: string) => Promise<DppRecord[]>;
+    findByUid: (uid: string) => Promise<DppRecord[]>;
+    /**
+     * The highest sequence assigned so far, 0 when nothing was ever inserted:
+     * what a snapshot pins. A deleted row's sequence stays assigned, so the
+     * answer never goes backwards.
+     */
+    highestSequence: () => Promise<number>;
+    /**
+     * The records matching the selector whose sequence lies in the range,
+     * ascending by sequence, at most `limit` of them. The one query a page is
+     * made of, so both stores answer it from an index rather than a scan.
+     */
+    findPage: (selector: RecordSelector, range: SequenceRange, limit: number) => Promise<DppRecord[]>;
+}
+/**
+ * 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 declare function selectorFilter(selector: RecordSelector): {
+    passportId: string;
+} | {
+    uid: string;
+};
+export declare class MongoDppStorage implements DppRecordStore {
+    private readonly records;
+    private readonly counters;
+    private ready?;
+    constructor(db: Db);
+    /**
+     * 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.
+     */
+    ensureReady(): Promise<void>;
+    /** One atomic increment per insert: the counter is the order, gaps included. */
+    private nextSequence;
+    insert(record: DppRecordInput): Promise<void>;
+    markSpent(txid: string, outputIndex: number, spendingTxid: string): Promise<void>;
+    markUnspent(txid: string, outputIndex: number): Promise<void>;
+    delete(txid: string, outputIndex: number): Promise<void>;
+    findByPassport(passportId: string): Promise<DppRecord[]>;
+    findByUid(uid: string): Promise<DppRecord[]>;
+    highestSequence(): Promise<number>;
+    findPage(selector: RecordSelector, range: SequenceRange, limit: number): Promise<DppRecord[]>;
+}
+export declare class InMemoryDppStorage implements DppRecordStore {
+    private readonly records;
+    private assigned;
+    private key;
+    insert(record: DppRecordInput): Promise<void>;
+    markSpent(txid: string, outputIndex: number, spendingTxid: string): Promise<void>;
+    markUnspent(txid: string, outputIndex: number): Promise<void>;
+    delete(txid: string, outputIndex: number): Promise<void>;
+    findByPassport(passportId: string): Promise<DppRecord[]>;
+    findByUid(uid: string): Promise<DppRecord[]>;
+    highestSequence(): Promise<number>;
+    findPage(selector: RecordSelector, range: SequenceRange, limit: number): Promise<DppRecord[]>;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

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