@obbyx/x402-obyte 0.0.0-stage → 0.1.0

package/dist/exact/facilitator-v1.js

@@ -0,0 +1,81 @@
+import { getNetwork, isObyteNetwork } from '@obbyx/obyte';
+import { EXACT_SCHEME } from './requirements.js';
+export function requirementsV1ToV2(req) {
+    return {
+        scheme: req.scheme,
+        network: getNetwork(req.network).caip2,
+        asset: req.asset,
+        amount: req.maxAmountRequired,
+        payTo: req.payTo,
+        maxTimeoutSeconds: req.maxTimeoutSeconds,
+        extra: req.extra ?? {},
+    };
+}
+export function requirementsV2ToV1(req, resource) {
+    return {
+        scheme: req.scheme,
+        network: getNetwork(req.network).v1Name,
+        maxAmountRequired: req.amount,
+        resource: resource.url,
+        description: resource.description ?? '',
+        mimeType: resource.mimeType ?? '',
+        outputSchema: {},
+        payTo: req.payTo,
+        maxTimeoutSeconds: req.maxTimeoutSeconds,
+        asset: req.asset,
+        extra: req.extra,
+    };
+}
+export class ExactObyteFacilitatorV1 {
+    v2;
+    scheme = EXACT_SCHEME;
+    caipFamily = 'obyte-*';
+    constructor(v2) {
+        this.v2 = v2;
+    }
+    getExtra(network) {
+        return this.v2.getExtra(getNetwork(network).caip2);
+    }
+    getSigners() {
+        return [];
+    }
+    async verify(payload, requirements) {
+        const converted = this.convert(payload, requirements);
+        if (!converted.ok)
+            return { isValid: false, invalidReason: converted.reason };
+        return this.v2.verify(converted.payload, converted.requirements);
+    }
+    async settle(payload, requirements) {
+        const converted = this.convert(payload, requirements);
+        const v1Network = requirements.network;
+        if (!converted.ok)
+            return { success: false, errorReason: converted.reason, transaction: '', network: v1Network };
+        const res = await this.v2.settle(converted.payload, converted.requirements);
+        return { ...res, network: v1Network };
+    }
+    convert(payload, requirements) {
+        const p = payload;
+        const r = requirements;
+        if (p.x402Version !== 1)
+            return { ok: false, reason: 'invalid_x402_version' };
+        if (p.scheme !== EXACT_SCHEME || r.scheme !== EXACT_SCHEME)
+            return { ok: false, reason: 'unsupported_scheme' };
+        if (!isObyteNetwork(r.network) || p.network !== r.network)
+            return { ok: false, reason: 'invalid_network' };
+        if (typeof r.maxAmountRequired !== 'string')
+            return { ok: false, reason: 'invalid_payment_requirements' };
+        const v2req = requirementsV1ToV2(r);
+        // v1 has no `accepted`: the client paid the requirements the server sent.
+        return {
+            ok: true,
+            requirements: v2req,
+            payload: {
+                x402Version: 2,
+                resource: { url: r.resource, description: r.description, mimeType: r.mimeType },
+                accepted: v2req,
+                payload: p.payload,
+            },
+        };
+    }
+}
+//# sourceMappingURL=facilitator-v1.js.map

package/dist/exact/facilitator-v1.js.map

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

package/dist/exact/facilitator.d.ts

@@ -0,0 +1,77 @@
+import type { Network, PaymentPayload, PaymentRequirements, SchemeNetworkFacilitator, SettleResponse, VerifyResponse } from '@x402/core/types';
+import { type Logger } from '@obbyx/obyte/logger';
+import type obyte from 'obyte';
+import { type SettlementRecord, type SettlementStore } from './store.js';
+/**
+ * x402 `exact` facilitator for Obyte (ADR-0002).
+ *
+ * The client signs a unit paying `payTo` and carrying the seller's binding in a
+ * data message; it does not broadcast. `/verify` checks it read-only (local
+ * profile + ledger reads); `/settle` claims it in the store, broadcasts it and
+ * reports success only when the configured finality policy is met.
+ *
+ * obyte.js is used directly (`client.api.*`); every hub call goes through
+ * {@link hubCall} for timeouts and unknown-outcome classification (I7).
+ */
+export type FinalityPolicy = 'stable' | 'accepted';
+export { EXACT_SETTLE_REASONS } from './reasons.js';
+export { HISTORY_PROBE_ADDRESS, isTransientPostError } from './finality.js';
+export interface ExactObyteFacilitatorOptions {
+    /** obyte.js clients by CAIP-2 network id. */
+    readonly clients: ReadonlyMap<string, obyte.Client>;
+    readonly store: SettlementStore;
+    readonly logger: Logger;
+    /** Allowed assets per CAIP-2 network ('base' = bytes). */
+    readonly allowedAssets: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly finality?: FinalityPolicy;
+    /** Addresses controlled by the facilitator; they may never be the payer. */
+    readonly facilitatorAddresses?: readonly string[];
+    readonly hubTimeoutMs?: number;
+    /** Tolerated clock difference between client, hub and us (seconds). */
+    readonly maxClockSkewSeconds?: number;
+    /** After acceptance, how long a claimed unit may still be (re)broadcast. */
+    readonly publishWindowSeconds?: number;
+    /**
+     * Oldest accepted `last_ball` of a payment unit, seconds (default 10800 = 3 h).
+     * Independent of `maxTimeoutSeconds`: with few transactions the network's
+     * stable point normally lags up to ~2 hours, while the unit's freshness is already guaranteed by the
+     * offer binding (it contains a random quoteId issued at most quote-TTL ago).
+     */
+    readonly maxLastBallAgeSeconds?: number;
+    /** Address with no history for the mandatory `addresses` of history requests. */
+    readonly historyProbeAddress?: string;
+    readonly now?: () => number;
+}
+export declare class ExactObyteFacilitator implements SchemeNetworkFacilitator {
+    private readonly options;
+    readonly scheme = "exact";
+    readonly caipFamily: "obyte:*";
+    private readonly log;
+    private readonly finality;
+    private readonly hubTimeoutMs;
+    private readonly skew;
+    private readonly publishWindow;
+    private readonly maxLastBallAge;
+    private readonly now;
+    /** Serializes settle/resume per settlement key inside this process. */
+    private readonly inFlight;
+    constructor(options: ExactObyteFacilitatorOptions);
+    getExtra(network: Network): Record<string, unknown> | undefined;
+    /** The payer pays its own fees; the facilitator signs nothing in `exact`. */
+    getSigners(): string[];
+    verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
+    settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
+    /** Re-drives a non-terminal settlement (used by the recovery worker). */
+    resume(record: SettlementRecord): Promise<SettleResponse>;
+    private check;
+    /** Known plain (non-AA) recipients; an address can never turn into an AA. */
+    private readonly plainRecipients;
+    private recipientIsNotAa;
+    private fetchDefinition;
+    private drive;
+    private step;
+    private move;
+    private respond;
+    private key;
+}
+//# sourceMappingURL=facilitator.d.ts.map

package/dist/exact/facilitator.d.ts.map

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

package/dist/exact/facilitator.js

@@ -0,0 +1,331 @@
+import { EXACT_REASONS, OBYTE_CAIP_FAMILY, getNetwork, isObyteNetwork, isSigDefinition, networkKey, validateExactUnit, } from '@obbyx/obyte';
+import { moduleLogger, withLogContext } from '@obbyx/obyte/logger';
+import { hubCall } from '../hub/hub-call.js';
+import { finalityOf, isTransientPostError } from './finality.js';
+import { checkLedger } from './ledger-checks.js';
+import { EXACT_SETTLE_REASONS, fail } from './reasons.js';
+import { EXACT_SCHEME, acceptedMatches, parseExactRequirements, } from './requirements.js';
+import { TERMINAL_STATES } from './store.js';
+export { EXACT_SETTLE_REASONS } from './reasons.js';
+export { HISTORY_PROBE_ADDRESS, isTransientPostError } from './finality.js';
+export class ExactObyteFacilitator {
+    options;
+    scheme = EXACT_SCHEME;
+    caipFamily = OBYTE_CAIP_FAMILY;
+    log;
+    finality;
+    hubTimeoutMs;
+    skew;
+    publishWindow;
+    maxLastBallAge;
+    now;
+    /** Serializes settle/resume per settlement key inside this process. */
+    inFlight = new Map();
+    constructor(options) {
+        this.options = options;
+        this.log = moduleLogger(options.logger, 'x402.exact', { scheme: EXACT_SCHEME });
+        this.finality = options.finality ?? 'stable';
+        this.hubTimeoutMs = options.hubTimeoutMs ?? 15_000;
+        this.skew = options.maxClockSkewSeconds ?? 120;
+        this.publishWindow = options.publishWindowSeconds ?? 300;
+        this.maxLastBallAge = options.maxLastBallAgeSeconds ?? 10_800;
+        this.now = options.now ?? (() => Math.floor(Date.now() / 1000));
+    }
+    getExtra(network) {
+        const assets = this.options.allowedAssets.get(network);
+        return { finality: this.finality, assets: assets === undefined ? [] : [...assets] };
+    }
+    /** The payer pays its own fees; the facilitator signs nothing in `exact`. */
+    getSigners() {
+        return [];
+    }
+    async verify(payload, requirements) {
+        return withLogContext({ scheme: EXACT_SCHEME, network: requirements.network }, async () => {
+            const checked = await this.check(payload, requirements);
+            if (!checked.ok) {
+                this.log.info({ reason: checked.reason, detail: checked.message }, 'verify rejected');
+                return { isValid: false, invalidReason: checked.reason, invalidMessage: checked.message };
+            }
+            const { facts } = checked.value;
+            this.log.info({ proofId: facts.unitHash, payer: facts.payer }, 'verify ok');
+            return { isValid: true, payer: facts.payer };
+        });
+    }
+    async settle(payload, requirements) {
+        return withLogContext({ scheme: EXACT_SCHEME, network: requirements.network }, async () => {
+            const network = requirements.network;
+            const unitHash = unitHashOf(payload);
+            if (unitHash === undefined) {
+                return failure(network, EXACT_SETTLE_REASONS.payload, 'Missing unit');
+            }
+            if (!isObyteNetwork(requirements.network)) {
+                return failure(network, 'invalid_network', 'Not an Obyte network');
+            }
+            const existing = await this.options.store.get(this.key(requirements.network, unitHash));
+            if (existing === undefined) {
+                const checked = await this.check(payload, requirements);
+                if (!checked.ok) {
+                    this.log.info({ proofId: unitHash, reason: checked.reason }, 'settle rejected at verification');
+                    return failure(network, checked.reason, checked.message);
+                }
+                const { facts, req } = checked.value;
+                const { created, record } = await this.options.store.claim({
+                    key: this.key(requirements.network, facts.unitHash),
+                    network: requirements.network,
+                    unitHash: facts.unitHash,
+                    binding: req.extra.binding,
+                    payer: facts.payer,
+                    payTo: req.payTo,
+                    asset: req.asset,
+                    amount: req.amount.toString(),
+                    unitJson: JSON.stringify(payload.payload['unit']),
+                    publishDeadline: this.now() + this.publishWindow,
+                });
+                this.log.info({ proofId: facts.unitHash, created, binding: req.extra.binding }, 'settlement claimed');
+                return this.drive(record);
+            }
+            // Idempotent resume: the same unit is bound to exactly one binding.
+            const binding = requirements.extra.binding;
+            if (existing.binding !== binding || existing.payTo !== requirements.payTo) {
+                return failure(network, 'invalid_payment_reused', 'This payment is bound to another operation');
+            }
+            return this.drive(existing);
+        });
+    }
+    /** Re-drives a non-terminal settlement (used by the recovery worker). */
+    resume(record) {
+        return withLogContext({ scheme: EXACT_SCHEME, network: record.network, proofId: record.unitHash }, () => this.drive(record));
+    }
+    // --- verification ---------------------------------------------------------
+    async check(payload, requirements) {
+        if (payload.x402Version !== 2)
+            return fail(EXACT_SETTLE_REASONS.version, 'Only x402 v2 is supported here');
+        if (!acceptedMatches(payload, requirements)) {
+            return fail(EXACT_SETTLE_REASONS.acceptedMismatch, 'Accepted requirements differ from the server requirements');
+        }
+        const parsed = parseExactRequirements(requirements);
+        if (!parsed.ok)
+            return fail(parsed.reason, parsed.message);
+        const req = parsed.value;
+        const now = this.now();
+        if (req.extra.validUntil < now)
+            return fail(EXACT_SETTLE_REASONS.quoteExpired, 'The payment offer has expired');
+        if (!this.options.allowedAssets.get(req.network.caip2)?.has(req.asset)) {
+            return fail(EXACT_REASONS.asset, 'Asset is not accepted by this facilitator');
+        }
+        const client = this.options.clients.get(req.network.caip2);
+        if (client === undefined)
+            return fail('invalid_network', 'Network is not served');
+        const unit = payload.payload['unit'];
+        const expectation = {
+            network: req.network,
+            payTo: req.payTo,
+            asset: req.asset,
+            amount: req.amount,
+            binding: req.extra.binding,
+            quoteId: req.extra.quoteId,
+            ...(this.options.facilitatorAddresses
+                ? { facilitatorAddresses: this.options.facilitatorAddresses }
+                : {}),
+        };
+        let local = validateExactUnit(unit, expectation);
+        if (!local.ok && local.reason === EXACT_REASONS.definitionRequired) {
+            const definition = await this.fetchDefinition(client, unit);
+            if (!definition.ok)
+                return definition;
+            local = validateExactUnit(unit, expectation, { authorDefinition: definition.value });
+        }
+        if (!local.ok)
+            return fail(local.reason, local.message);
+        const facts = local.value;
+        // Clock sanity: the unit was composed recently.
+        if (Math.abs(facts.timestamp - now) > this.skew + req.maxTimeoutSeconds) {
+            return fail(EXACT_SETTLE_REASONS.stale, 'Unit timestamp is outside the acceptance window');
+        }
+        // payTo must be a plain address: a payment to an autonomous agent triggers
+        // it, and the AA may bounce the funds back to the payer (the unit is still
+        // valid and final, so the seller would serve without being paid).
+        const recipient = await this.recipientIsNotAa(client, req.payTo);
+        if (!recipient.ok)
+            return recipient;
+        const ledger = await checkLedger({
+            hubTimeoutMs: this.hubTimeoutMs,
+            maxLastBallAgeSeconds: this.maxLastBallAge,
+            now: this.now,
+        }, client, req, facts, unit);
+        if (!ledger.ok)
+            return ledger;
+        return { ok: true, value: { facts, req } };
+    }
+    /** Known plain (non-AA) recipients; an address can never turn into an AA. */
+    plainRecipients = new Set();
+    async recipientIsNotAa(client, payTo) {
+        if (this.plainRecipients.has(payTo))
+            return { ok: true, value: null };
+        const res = await hubCall(() => client.api.getDefinition(payTo), this.hubTimeoutMs);
+        if (res.kind !== 'ok')
+            return fail(EXACT_SETTLE_REASONS.ledger, `Cannot read the payTo definition: ${res.error}`);
+        const definition = res.value;
+        if (Array.isArray(definition) && definition[0] === 'autonomous agent') {
+            return fail(EXACT_SETTLE_REASONS.payToAa, 'payTo is an autonomous agent');
+        }
+        // An unused address has no definition yet (null): fine, but not cached.
+        if (definition !== null && definition !== undefined)
+            this.plainRecipients.add(payTo);
+        return { ok: true, value: null };
+    }
+    async fetchDefinition(client, unit) {
+        const address = unit.authors?.[0]?.address;
+        if (typeof address !== 'string')
+            return fail(EXACT_REASONS.unsupported, 'Malformed author');
+        const res = await hubCall(() => client.api.getDefinition(address), this.hubTimeoutMs);
+        if (res.kind !== 'ok')
+            return fail(EXACT_SETTLE_REASONS.ledger, `Cannot read definition: ${res.error}`);
+        if (!isSigDefinition(res.value)) {
+            return fail(EXACT_REASONS.definition, 'Payer definition is unknown or not a single-sig definition');
+        }
+        return { ok: true, value: res.value };
+    }
+    // --- settlement state machine --------------------------------------------------
+    drive(record) {
+        const running = this.inFlight.get(record.key);
+        if (running !== undefined)
+            return running;
+        const promise = this.step(record).finally(() => this.inFlight.delete(record.key));
+        this.inFlight.set(record.key, promise);
+        return promise;
+    }
+    async step(initial) {
+        const store = this.options.store;
+        const client = this.options.clients.get(initial.network);
+        let record = (await store.get(initial.key)) ?? initial;
+        if (client === undefined)
+            return this.respond(record, 'Network is not served');
+        const t = this.hubTimeoutMs;
+        if (record.state === 'claimed' || record.state === 'broadcasting') {
+            // Is it already on the ledger (we or someone else published it)?
+            const known = await hubCall(() => client.api.getJoint(record.unitHash), t);
+            if (known.kind === 'ok' && known.value.joint !== undefined) {
+                record = await this.move(record, 'accepted', { data: { via: 'get_joint' } });
+            }
+            else if (known.kind !== 'ok') {
+                await store.event({
+                    key: record.key,
+                    kind: 'hub_unavailable',
+                    data: { op: 'get_joint', error: known.error },
+                });
+                return this.respond(record);
+            }
+            else if (this.now() > record.publishDeadline) {
+                record = await this.move(record, 'expired', { lastError: 'publication window closed' });
+                return this.respond(record);
+            }
+            else {
+                if (record.state === 'claimed')
+                    record = await this.move(record, 'broadcasting');
+                if (record.unitJson === null)
+                    return this.respond(record, 'Unit body is no longer stored');
+                const unit = JSON.parse(record.unitJson);
+                const posted = await hubCall(() => client.api.postJoint({ unit }), t);
+                await store.event({ key: record.key, kind: 'post_joint', data: { outcome: posted.kind } });
+                if (posted.kind === 'ok') {
+                    record = await this.move(record, 'accepted', {
+                        incrementAttempts: true,
+                        data: { response: posted.value },
+                    });
+                }
+                else if (posted.kind === 'hub_error' && isTransientPostError(posted.error)) {
+                    // The hub is still working on it or lacks context: not a rejection.
+                    // Stay in broadcasting; the next attempt resolves it via get_joint.
+                    this.log.info({ proofId: record.unitHash, hubError: posted.error }, 'broadcast not final yet (transient hub answer)');
+                    return this.respond(record);
+                }
+                else if (posted.kind === 'hub_error') {
+                    // Definite rejection — unless the unit is known after all (e.g. posted earlier).
+                    const recheck = await hubCall(() => client.api.getJoint(record.unitHash), t);
+                    if (recheck.kind === 'ok' && recheck.value.joint !== undefined) {
+                        record = await this.move(record, 'accepted', {
+                            data: { via: 'get_joint after hub error' },
+                        });
+                    }
+                    else if (recheck.kind === 'ok') {
+                        record = await this.move(record, 'rejected', {
+                            lastError: posted.error,
+                            incrementAttempts: true,
+                        });
+                        this.log.warn({ proofId: record.unitHash, hubError: posted.error }, 'unit rejected by the network');
+                        return this.respond(record);
+                    }
+                    else {
+                        return this.respond(record);
+                    }
+                }
+                else {
+                    // Unknown outcome: stay in broadcasting; the next attempt resolves it via get_joint.
+                    this.log.warn({ proofId: record.unitHash, error: posted.error }, 'broadcast outcome unknown');
+                    return this.respond(record);
+                }
+            }
+        }
+        if (record.state === 'accepted') {
+            const finality = await finalityOf({ hubTimeoutMs: this.hubTimeoutMs, historyProbeAddress: this.options.historyProbeAddress }, client, record.unitHash);
+            if (finality === 'good')
+                record = await this.move(record, 'stable_good');
+            else if (finality === 'final_bad') {
+                record = await this.move(record, 'final_bad', { lastError: 'double spend (final-bad)' });
+                this.log.error({ proofId: record.unitHash }, 'settled unit became final-bad');
+            }
+        }
+        return this.respond(record);
+    }
+    async move(record, to, patch = {}) {
+        const next = await this.options.store.transition(record.key, [record.state], to, patch);
+        if (next === undefined) {
+            // Lost a race (another path moved it); continue from the stored state.
+            return (await this.options.store.get(record.key)) ?? record;
+        }
+        this.log.info({ proofId: record.unitHash, from: record.state, to }, 'settlement state changed');
+        return next;
+    }
+    respond(record, problem) {
+        const network = record.network;
+        const base = { payer: record.payer, network, transaction: record.unitHash };
+        const success = record.state === 'stable_good' ||
+            (record.state === 'accepted' && this.finality === 'accepted');
+        if (success)
+            return { success: true, ...base, amount: record.amount };
+        if (!TERMINAL_STATES.has(record.state)) {
+            return {
+                success: false,
+                errorReason: EXACT_SETTLE_REASONS.pending,
+                errorMessage: problem ?? `Settlement is ${record.state}`,
+                // x402: settlement_pending carries a non-empty transaction; the unit
+                // hash is deterministic even before the unit is broadcast.
+                ...base,
+            };
+        }
+        const reason = record.state === 'final_bad'
+            ? EXACT_SETTLE_REASONS.finalBad
+            : record.state === 'expired'
+                ? EXACT_SETTLE_REASONS.expired
+                : EXACT_SETTLE_REASONS.rejected;
+        return {
+            success: false,
+            errorReason: reason,
+            errorMessage: record.lastError ?? record.state,
+            ...base,
+        };
+    }
+    key(network, unitHash) {
+        return networkKey(getNetwork(network), 'unit', unitHash);
+    }
+}
+function unitHashOf(payload) {
+    const unit = payload.payload?.['unit'];
+    const hash = unit && typeof unit === 'object' ? unit.unit : undefined;
+    return typeof hash === 'string' && /^[A-Za-z0-9+/]{43}=$/.test(hash) ? hash : undefined;
+}
+function failure(network, reason, message) {
+    return { success: false, errorReason: reason, errorMessage: message, transaction: '', network };
+}
+//# sourceMappingURL=facilitator.js.map

package/dist/exact/facilitator.js.map

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

package/dist/exact/finality.d.ts

@@ -0,0 +1,18 @@
+import obyte from 'obyte';
+/**
+ * Finality of a broadcast `exact` unit (ADR-0002) and classification of the
+ * hub's `post_joint` answers.
+ */
+/**
+ * `light/get_history` requires a non-empty `addresses` list even when only
+ * `requested_joints` matter. This address (chash of a constant definition
+ * nobody can sign for) has no history, so the response stays small.
+ */
+export declare const HISTORY_PROBE_ADDRESS: string;
+/** Stable + good iff the unit's ball is in the proofchain without is_nonserial (ADR-0002). */
+export declare function finalityOf(ctx: {
+    readonly hubTimeoutMs: number;
+    readonly historyProbeAddress?: string | undefined;
+}, client: obyte.Client, unitHash: string): Promise<'good' | 'final_bad' | 'pending'>;
+export declare function isTransientPostError(error: string): boolean;
+//# sourceMappingURL=finality.d.ts.map

package/dist/exact/finality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finality.d.ts","sourceRoot":"","sources":["../../src/exact/finality.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B;;;GAGG;AACH;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,QAA+D,CAAC;AAElG,8FAA8F;AAC9F,wBAAsB,UAAU,CAC9B,GAAG,EAAE;IAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EACzF,MAAM,EAAE,KAAK,CAAC,MAAM,EACpB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC,CAgB3C;AAgBD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAG3D"}

package/dist/exact/finality.js

@@ -0,0 +1,45 @@
+import obyte from 'obyte';
+import { hubCall } from '../hub/hub-call.js';
+import { parseHistory } from '../hub/schemas.js';
+/**
+ * Finality of a broadcast `exact` unit (ADR-0002) and classification of the
+ * hub's `post_joint` answers.
+ */
+/**
+ * `light/get_history` requires a non-empty `addresses` list even when only
+ * `requested_joints` matter. This address (chash of a constant definition
+ * nobody can sign for) has no history, so the response stays small.
+ */
+export const HISTORY_PROBE_ADDRESS = obyte.utils.getChash160(['sig', { pubkey: 'A'.repeat(44) }]);
+/** Stable + good iff the unit's ball is in the proofchain without is_nonserial (ADR-0002). */
+export async function finalityOf(ctx, client, unitHash) {
+    const res = await hubCall(() => client.api.getWitnesses().then((witnesses) => client.api.getHistory({
+        witnesses,
+        addresses: [ctx.historyProbeAddress ?? HISTORY_PROBE_ADDRESS],
+        requested_joints: [unitHash],
+    })), ctx.hubTimeoutMs);
+    if (res.kind !== 'ok')
+        return 'pending';
+    const ball = parseHistory(res.value)?.proofchainBalls.find((b) => b.unit === unitHash);
+    if (ball === undefined)
+        return 'pending';
+    return ball.is_nonserial === true ? 'final_bad' : 'good';
+}
+/**
+ * `post_joint` answers of ocore that do NOT mean the unit was rejected: the hub
+ * is validating it, knows it unverified, or lacks its parents / hash tree (it
+ * is behind). Anything else from the hub is a validation error (definite).
+ */
+const TRANSIENT_POST_ERRORS = [
+    'already handling this unit',
+    'known unverified',
+    'unknown parents',
+    'need hash tree',
+    'timeout',
+    'temporarily',
+];
+export function isTransientPostError(error) {
+    const e = error.toLowerCase();
+    return TRANSIENT_POST_ERRORS.some((t) => e.includes(t));
+}
+//# sourceMappingURL=finality.js.map

package/dist/exact/finality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"finality.js","sourceRoot":"","sources":["../../src/exact/finality.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;;GAGG;AACH;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAElG,8FAA8F;AAC9F,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,GAAyF,EACzF,MAAoB,EACpB,QAAgB;IAEhB,MAAM,GAAG,GAAG,MAAM,OAAO,CACvB,GAAG,EAAE,CACH,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAC3C,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC;QACpB,SAAS;QACT,SAAS,EAAE,CAAC,GAAG,CAAC,mBAAmB,IAAI,qBAAqB,CAAC;QAC7D,gBAAgB,EAAE,CAAC,QAAQ,CAAC;KACpB,CAAC,CACZ,EACH,GAAG,CAAC,YAAY,CACjB,CAAC;IACF,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACxC,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IACvF,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACzC,OAAO,IAAI,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,qBAAqB,GAAG;IAC5B,4BAA4B;IAC5B,kBAAkB;IAClB,iBAAiB;IACjB,gBAAgB;IAChB,SAAS;IACT,aAAa;CACd,CAAC;AAEF,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAC9B,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1D,CAAC"}

package/dist/exact/ledger-checks.d.ts

@@ -0,0 +1,15 @@
+import type obyte from 'obyte';
+import type { ExactUnitFacts } from '@obbyx/obyte';
+import { type Check } from './reasons.js';
+import type { ParsedExactRequirements } from './requirements.js';
+export interface LedgerCheckContext {
+    readonly hubTimeoutMs: number;
+    readonly maxLastBallAgeSeconds: number;
+    readonly now: () => number;
+}
+/**
+ * Ledger checks (hub-trusted, ADR-0001/0002): last ball recency, inputs
+ * exist and belong to the payer, amounts + fees balance, inputs unspent.
+ */
+export declare function checkLedger(ctx: LedgerCheckContext, client: obyte.Client, req: ParsedExactRequirements, facts: ExactUnitFacts, unit: Record<string, unknown>): Promise<Check<null>>;
+//# sourceMappingURL=ledger-checks.d.ts.map

package/dist/exact/ledger-checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-checks.d.ts","sourceRoot":"","sources":["../../src/exact/ledger-checks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD,OAAO,EAAE,KAAK,KAAK,EAA8B,MAAM,cAAc,CAAC;AACtE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAEjE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,kBAAkB,EACvB,MAAM,EAAE,KAAK,CAAC,MAAM,EACpB,GAAG,EAAE,uBAAuB,EAC5B,KAAK,EAAE,cAAc,EACrB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAyFtB"}