@obbyx/x402-obyte 0.0.0-stage → 0.1.0

package/dist/exact/ledger-checks.js

@@ -0,0 +1,85 @@
+import { hubCall } from '../hub/hub-call.js';
+import { parseHistory, parseLedgerUnit } from '../hub/schemas.js';
+import { EXACT_SETTLE_REASONS, fail } from './reasons.js';
+/**
+ * Ledger checks (hub-trusted, ADR-0001/0002): last ball recency, inputs
+ * exist and belong to the payer, amounts + fees balance, inputs unspent.
+ */
+export async function checkLedger(ctx, client, req, facts, unit) {
+    const t = ctx.hubTimeoutMs;
+    const lastBall = await hubCall(() => client.api.getJoint(facts.lastBallUnit), t);
+    if (lastBall.kind !== 'ok')
+        return fail(EXACT_SETTLE_REASONS.ledger, `last ball: ${lastBall.error}`);
+    const lastBallTs = lastBall.value.joint?.unit.timestamp;
+    if (typeof lastBallTs !== 'number')
+        return fail(EXACT_SETTLE_REASONS.stale, 'Unknown last ball unit');
+    const lastBallAge = ctx.now() - lastBallTs;
+    if (lastBallAge > ctx.maxLastBallAgeSeconds) {
+        return fail(EXACT_SETTLE_REASONS.stale, `Last ball is ${lastBallAge} s old; the limit is ${ctx.maxLastBallAgeSeconds} s (MAX_LAST_BALL_AGE_SECONDS)`);
+    }
+    // Inputs: each referenced output exists, belongs to the payer, has the right asset.
+    const totals = new Map();
+    const sources = new Map();
+    for (const input of facts.inputs) {
+        let source = sources.get(input.unit);
+        if (source === undefined) {
+            const res = await hubCall(() => client.api.getJoint(input.unit), t);
+            if (res.kind !== 'ok')
+                return fail(EXACT_SETTLE_REASONS.ledger, `input source: ${res.error}`);
+            if (res.value.joint === undefined)
+                return fail(EXACT_SETTLE_REASONS.inputs, 'Input source unit not found');
+            const parsedSource = parseLedgerUnit(res.value.joint.unit);
+            if (parsedSource === undefined)
+                return fail(EXACT_SETTLE_REASONS.ledger, 'input source: malformed hub answer');
+            source = parsedSource;
+            sources.set(input.unit, source);
+        }
+        const message = source.messages?.[input.messageIndex];
+        const output = message?.payload?.outputs?.[input.outputIndex];
+        const asset = message?.payload?.asset ?? 'base';
+        if (message?.app !== 'payment' || output === undefined) {
+            return fail(EXACT_SETTLE_REASONS.inputs, 'Input refers to a missing output');
+        }
+        if (output.address !== facts.payer ||
+            asset !== input.asset ||
+            !Number.isSafeInteger(output.amount)) {
+            return fail(EXACT_SETTLE_REASONS.inputs, 'Input output does not belong to the payer in this asset');
+        }
+        totals.set(asset, (totals.get(asset) ?? 0n) + BigInt(output.amount));
+    }
+    const fees = BigInt(facts.commissions.headers + facts.commissions.payload) +
+        BigInt(unit['tps_fee'] ?? 0) +
+        BigInt(unit['burn_fee'] ?? 0);
+    for (const [asset, outTotal] of Object.entries(facts.outputTotals)) {
+        const expected = asset === 'base' ? outTotal + fees : outTotal;
+        if (totals.get(asset) !== expected) {
+            return fail(EXACT_SETTLE_REASONS.inputs, `Inputs and outputs do not balance in ${asset}`);
+        }
+    }
+    // Unspent: no other unit of the payer spends these inputs (best effort
+    // until stability; the network decides double-spends definitively).
+    const history = await hubCall(() => client.api
+        .getWitnesses()
+        .then((witnesses) => client.api.getHistory({ witnesses, addresses: [facts.payer] })), t);
+    if (history.kind !== 'ok')
+        return fail(EXACT_SETTLE_REASONS.ledger, `history: ${history.error}`);
+    const parsedHistory = parseHistory(history.value);
+    if (parsedHistory === undefined)
+        return fail(EXACT_SETTLE_REASONS.ledger, 'history: malformed hub answer');
+    const wanted = new Set(facts.inputs.map((i) => `${i.unit}:${i.messageIndex}:${i.outputIndex}`));
+    for (const joint of parsedHistory.joints) {
+        if (joint.unit.unit === facts.unitHash)
+            continue;
+        for (const m of joint.unit.messages ?? []) {
+            if (m.app !== 'payment')
+                continue;
+            for (const inp of m.payload?.inputs ?? []) {
+                if (wanted.has(`${inp.unit}:${inp.message_index}:${inp.output_index}`)) {
+                    return fail(EXACT_SETTLE_REASONS.inputs, 'An input is already spent by another unit');
+                }
+            }
+        }
+    }
+    return { ok: true, value: null };
+}
+//# sourceMappingURL=ledger-checks.js.map

package/dist/exact/ledger-checks.js.map

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

package/dist/exact/reasons.d.ts

@@ -0,0 +1,29 @@
+/** Settlement/verification reasons of the `exact` facilitator beyond the unit profile ones. */
+export declare const EXACT_SETTLE_REASONS: {
+    readonly pending: "settlement_pending";
+    readonly rejected: "invalid_exact_obyte_rejected_by_network";
+    readonly finalBad: "invalid_exact_obyte_double_spend";
+    readonly expired: "invalid_exact_obyte_publication_window_expired";
+    readonly ledger: "invalid_exact_obyte_ledger_unavailable";
+    readonly inputs: "invalid_exact_obyte_inputs";
+    readonly stale: "invalid_exact_obyte_stale";
+    readonly quoteExpired: "invalid_exact_obyte_quote_expired";
+    readonly payToAa: "invalid_exact_obyte_payto_is_aa";
+    readonly acceptedMismatch: "invalid_payment_requirements";
+    readonly version: "invalid_x402_version";
+    readonly payload: "invalid_payload";
+};
+export type Check<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+};
+export declare const fail: (reason: string, message: string) => {
+    ok: false;
+    reason: string;
+    message: string;
+};
+//# sourceMappingURL=reasons.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reasons.d.ts","sourceRoot":"","sources":["../../src/exact/reasons.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;CAavB,CAAC;AAEX,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAC/F,eAAO,MAAM,IAAI,GACf,QAAQ,MAAM,EACd,SAAS,MAAM,KACd;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAI7C,CAAC"}

package/dist/exact/reasons.js

@@ -0,0 +1,21 @@
+/** Settlement/verification reasons of the `exact` facilitator beyond the unit profile ones. */
+export const EXACT_SETTLE_REASONS = {
+    pending: 'settlement_pending',
+    rejected: 'invalid_exact_obyte_rejected_by_network',
+    finalBad: 'invalid_exact_obyte_double_spend',
+    expired: 'invalid_exact_obyte_publication_window_expired',
+    ledger: 'invalid_exact_obyte_ledger_unavailable',
+    inputs: 'invalid_exact_obyte_inputs',
+    stale: 'invalid_exact_obyte_stale',
+    quoteExpired: 'invalid_exact_obyte_quote_expired',
+    payToAa: 'invalid_exact_obyte_payto_is_aa',
+    acceptedMismatch: 'invalid_payment_requirements',
+    version: 'invalid_x402_version',
+    payload: 'invalid_payload',
+};
+export const fail = (reason, message) => ({
+    ok: false,
+    reason,
+    message,
+});
+//# sourceMappingURL=reasons.js.map

package/dist/exact/reasons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reasons.js","sourceRoot":"","sources":["../../src/exact/reasons.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,OAAO,EAAE,oBAAoB;IAC7B,QAAQ,EAAE,yCAAyC;IACnD,QAAQ,EAAE,kCAAkC;IAC5C,OAAO,EAAE,gDAAgD;IACzD,MAAM,EAAE,wCAAwC;IAChD,MAAM,EAAE,4BAA4B;IACpC,KAAK,EAAE,2BAA2B;IAClC,YAAY,EAAE,mCAAmC;IACjD,OAAO,EAAE,iCAAiC;IAC1C,gBAAgB,EAAE,8BAA8B;IAChD,OAAO,EAAE,sBAAsB;IAC/B,OAAO,EAAE,iBAAiB;CAClB,CAAC;AAGX,MAAM,CAAC,MAAM,IAAI,GAAG,CAClB,MAAc,EACd,OAAe,EACiC,EAAE,CAAC,CAAC;IACpD,EAAE,EAAE,KAAK;IACT,MAAM;IACN,OAAO;CACR,CAAC,CAAC"}

package/dist/exact/requirements.d.ts

@@ -0,0 +1,37 @@
+import type { PaymentPayload, PaymentRequirements } from '@x402/core/types';
+import { type ObyteNetwork, type Verdict } from '@obbyx/obyte';
+import { z } from 'zod';
+export declare const EXACT_SCHEME = "exact";
+/**
+ * Scheme-specific `extra` of x402 PaymentRequirements for `exact` on Obyte.
+ *
+ * `binding` is computed by the seller per request (an HMAC over the quote and
+ * the request fingerprint, see `@obbyx/sdk`) and must be signed by the client
+ * inside the unit's data message. `quoteId`/`validUntil` bound the offer.
+ */
+export declare const exactExtraSchema: z.ZodObject<{
+    binding: z.ZodString;
+    quoteId: z.ZodString;
+    validUntil: z.ZodNumber;
+    paymentFlow: z.ZodOptional<z.ZodEnum<{
+        authorization: "authorization";
+        upfront: "upfront";
+    }>>;
+}, z.core.$strict>;
+export type ExactExtra = z.infer<typeof exactExtraSchema>;
+export interface ParsedExactRequirements {
+    readonly network: ObyteNetwork;
+    readonly asset: string;
+    readonly amount: bigint;
+    readonly payTo: string;
+    readonly maxTimeoutSeconds: number;
+    readonly extra: ExactExtra;
+}
+export declare function parseExactRequirements(req: PaymentRequirements): Verdict<ParsedExactRequirements>;
+/**
+ * x402 core does not compare the client's `accepted` requirements with the
+ * server's; a mismatch could let a client pay under different terms.
+ */
+export declare function acceptedMatches(payload: PaymentPayload, req: PaymentRequirements): boolean;
+export declare function canonical(value: unknown): string;
+//# sourceMappingURL=requirements.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"requirements.d.ts","sourceRoot":"","sources":["../../src/exact/requirements.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,OAAO,EAQb,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,YAAY,UAAU,CAAC;AAEpC;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;kBAclB,CAAC;AAEZ,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA8BjG;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAY1F;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQhD"}

package/dist/exact/requirements.js

@@ -0,0 +1,80 @@
+import { accept, getNetwork, isAddress, isAssetId, isObyteNetwork, parseAmount, reject, } from '@obbyx/obyte';
+import { z } from 'zod';
+export const EXACT_SCHEME = 'exact';
+/**
+ * Scheme-specific `extra` of x402 PaymentRequirements for `exact` on Obyte.
+ *
+ * `binding` is computed by the seller per request (an HMAC over the quote and
+ * the request fingerprint, see `@obbyx/sdk`) and must be signed by the client
+ * inside the unit's data message. `quoteId`/`validUntil` bound the offer.
+ */
+export const exactExtraSchema = z
+    .object({
+    binding: z.string().regex(/^[0-9a-f]{64}$/, 'binding must be 64 lowercase hex chars'),
+    quoteId: z
+        .string()
+        .min(8)
+        .max(64)
+        .regex(/^[A-Za-z0-9_-]+$/),
+    validUntil: z.number().int().positive(),
+    // x402 §6.1: Obyte supports the `upfront` flow (settle, then serve) and the
+    // default `authorization` flow; `escrow` and any asset transfer method
+    // (there is none on Obyte: the payer signs the transfer itself) are refused.
+    paymentFlow: z.enum(['authorization', 'upfront']).optional(),
+})
+    .strict();
+export function parseExactRequirements(req) {
+    if (req.scheme !== EXACT_SCHEME)
+        return reject('unsupported_scheme', 'Scheme is not exact');
+    if (!isObyteNetwork(req.network))
+        return reject('invalid_network', 'Not an Obyte network');
+    if (!isAssetId(req.asset))
+        return reject('invalid_payment_requirements', 'Invalid asset');
+    if (!isAddress(req.payTo))
+        return reject('invalid_payment_requirements', 'Invalid payTo');
+    if (!Number.isSafeInteger(req.maxTimeoutSeconds) || req.maxTimeoutSeconds <= 0) {
+        return reject('invalid_payment_requirements', 'Invalid maxTimeoutSeconds');
+    }
+    let amount;
+    try {
+        amount = parseAmount(req.amount);
+    }
+    catch {
+        return reject('invalid_payment_requirements', 'Invalid amount');
+    }
+    if (amount <= 0n)
+        return reject('invalid_payment_requirements', 'Amount must be positive');
+    const extra = exactExtraSchema.safeParse(req.extra);
+    if (!extra.success) {
+        return reject('invalid_payment_requirements', `Invalid extra: ${extra.error.issues[0]?.message}`);
+    }
+    return accept({
+        network: getNetwork(req.network),
+        asset: req.asset,
+        amount,
+        payTo: req.payTo,
+        maxTimeoutSeconds: req.maxTimeoutSeconds,
+        extra: extra.data,
+    });
+}
+/**
+ * x402 core does not compare the client's `accepted` requirements with the
+ * server's; a mismatch could let a client pay under different terms.
+ */
+export function acceptedMatches(payload, req) {
+    const a = payload.accepted;
+    return (a !== undefined &&
+        a.scheme === req.scheme &&
+        a.network === req.network &&
+        a.asset === req.asset &&
+        a.amount === req.amount &&
+        a.payTo === req.payTo &&
+        a.maxTimeoutSeconds === req.maxTimeoutSeconds &&
+        canonical(a.extra) === canonical(req.extra));
+}
+export function canonical(value) {
+    return JSON.stringify(value, (_k, v) => v && typeof v === 'object' && !Array.isArray(v)
+        ? Object.fromEntries(Object.entries(v).sort(([x], [y]) => x.localeCompare(y)))
+        : v);
+}
+//# sourceMappingURL=requirements.js.map

package/dist/exact/requirements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirements.js","sourceRoot":"","sources":["../../src/exact/requirements.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,MAAM,EACN,UAAU,EACV,SAAS,EACT,SAAS,EACT,cAAc,EACd,WAAW,EACX,MAAM,GACP,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC;AAEpC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,gBAAgB,EAAE,wCAAwC,CAAC;IACrF,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,EAAE,CAAC;SACP,KAAK,CAAC,kBAAkB,CAAC;IAC5B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACvC,4EAA4E;IAC5E,uEAAuE;IACvE,6EAA6E;IAC7E,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE;CAC7D,CAAC;KACD,MAAM,EAAE,CAAC;AAaZ,MAAM,UAAU,sBAAsB,CAAC,GAAwB;IAC7D,IAAI,GAAG,CAAC,MAAM,KAAK,YAAY;QAAE,OAAO,MAAM,CAAC,oBAAoB,EAAE,qBAAqB,CAAC,CAAC;IAC5F,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO,MAAM,CAAC,iBAAiB,EAAE,sBAAsB,CAAC,CAAC;IAC3F,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,8BAA8B,EAAE,eAAe,CAAC,CAAC;IAC1F,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,8BAA8B,EAAE,eAAe,CAAC,CAAC;IAC1F,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,GAAG,CAAC,iBAAiB,IAAI,CAAC,EAAE,CAAC;QAC/E,OAAO,MAAM,CAAC,8BAA8B,EAAE,2BAA2B,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,MAAc,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,8BAA8B,EAAE,gBAAgB,CAAC,CAAC;IAClE,CAAC;IACD,IAAI,MAAM,IAAI,EAAE;QAAE,OAAO,MAAM,CAAC,8BAA8B,EAAE,yBAAyB,CAAC,CAAC;IAC3F,MAAM,KAAK,GAAG,gBAAgB,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpD,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,MAAM,CACX,8BAA8B,EAC9B,kBAAkB,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CACnD,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;QACZ,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC;QAChC,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,MAAM;QACN,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,iBAAiB,EAAE,GAAG,CAAC,iBAAiB;QACxC,KAAK,EAAE,KAAK,CAAC,IAAI;KAClB,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,OAAuB,EAAE,GAAwB;IAC/E,MAAM,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC3B,OAAO,CACL,CAAC,KAAK,SAAS;QACf,CAAC,CAAC,MAAM,KAAK,GAAG,CAAC,MAAM;QACvB,CAAC,CAAC,OAAO,KAAK,GAAG,CAAC,OAAO;QACzB,CAAC,CAAC,KAAK,KAAK,GAAG,CAAC,KAAK;QACrB,CAAC,CAAC,MAAM,KAAK,GAAG,CAAC,MAAM;QACvB,CAAC,CAAC,KAAK,KAAK,GAAG,CAAC,KAAK;QACrB,CAAC,CAAC,iBAAiB,KAAK,GAAG,CAAC,iBAAiB;QAC7C,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAC5C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAU,EAAE,EAAE,CAC9C,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAC7C,CAAC,CAAC,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAC,CAA4B,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CACpF;QACH,CAAC,CAAC,CAAC,CACN,CAAC;AACJ,CAAC"}

package/dist/exact/store.d.ts

@@ -0,0 +1,133 @@
+import { DatabaseSync } from 'node:sqlite';
+import { ObbyxError } from '@obbyx/obyte';
+/**
+ * Settlement state machine storage for the `exact` scheme (ADR-0002, ADR-0005).
+ *
+ *   claimed → broadcasting → accepted → stable_good
+ *                  │             └────→ final_bad
+ *                  ├──→ rejected
+ *                  └──→ expired
+ *
+ * - One row per (network, unit). The row is created (claimed) BEFORE the unit
+ *   is broadcast (outbox), so a crash between broadcast and the next write is
+ *   recovered by re-reading non-terminal rows on startup.
+ * - Transitions are compare-and-set on the current state inside one
+ *   SQLite transaction; a lost race returns `false` instead of overwriting.
+ * - One facilitator process per database file: the connection takes an
+ *   exclusive lock at open, so a second process fails fast.
+ */
+export type SettlementState = 'claimed' | 'broadcasting' | 'accepted' | 'stable_good' | 'final_bad' | 'rejected' | 'expired';
+export declare const TERMINAL_STATES: ReadonlySet<SettlementState>;
+export interface SettlementRecord {
+    readonly key: string;
+    readonly network: string;
+    readonly unitHash: string;
+    readonly binding: string;
+    readonly payer: string;
+    readonly payTo: string;
+    readonly asset: string;
+    readonly amount: string;
+    readonly state: SettlementState;
+    /** Signed unit JSON; deleted (null) after a terminal state and retention. */
+    readonly unitJson: string | null;
+    /** After this time (unix s) an unpublished unit is never broadcast. */
+    readonly publishDeadline: number;
+    readonly attempts: number;
+    readonly lastError: string | null;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+export interface NewSettlement {
+    readonly key: string;
+    readonly network: string;
+    readonly unitHash: string;
+    readonly binding: string;
+    readonly payer: string;
+    readonly payTo: string;
+    readonly asset: string;
+    readonly amount: string;
+    readonly unitJson: string;
+    readonly publishDeadline: number;
+}
+export interface SettlementEvent {
+    readonly key: string;
+    readonly kind: string;
+    readonly from?: SettlementState | null;
+    readonly to?: SettlementState | null;
+    readonly data?: Record<string, unknown>;
+}
+/**
+ * Port for the `exact` settlement state machine (implemented with node:sqlite
+ * here, and with Prisma in apps/facilitator). All implementations must pass
+ * the shared contract tests: unique claim, compare-and-set transitions,
+ * single process per database.
+ */
+export interface SettlementStore {
+    get(key: string): Promise<SettlementRecord | undefined>;
+    claim(input: NewSettlement): Promise<{
+        created: boolean;
+        record: SettlementRecord;
+    }>;
+    transition(key: string, from: readonly SettlementState[], to: SettlementState, patch?: TransitionPatch): Promise<SettlementRecord | undefined>;
+    event(event: SettlementEvent): Promise<void>;
+    listActive(limit?: number): Promise<SettlementRecord[]>;
+    events(key: string): Promise<{
+        kind: string;
+        from: string | null;
+        to: string | null;
+        data: unknown;
+    }[]>;
+    pruneUnitBodies(olderThan: number): Promise<number>;
+    close(): Promise<void>;
+}
+export interface TransitionPatch {
+    readonly lastError?: string | null;
+    readonly incrementAttempts?: boolean;
+    readonly data?: Record<string, unknown>;
+}
+export declare class StoreLockedError extends ObbyxError {
+    constructor(path: string, cause: unknown);
+}
+export declare class SqliteSettlementStore implements SettlementStore {
+    private readonly db;
+    private readonly now;
+    /**
+     * @param path SQLite file, or `:memory:` for tests.
+     * @param now  Clock in unix seconds (injectable for tests).
+     */
+    constructor(path: string, now?: () => number);
+    close(): Promise<void>;
+    /** The exclusive connection, shared with other facilitator stores (e.g. BatchStore). */
+    get database(): DatabaseSync;
+    get(key: string): Promise<SettlementRecord | undefined>;
+    private getSync;
+    /**
+     * Inserts a new settlement in state `claimed` unless the key exists.
+     * Returns the stored record and whether this call created it.
+     */
+    claim(input: NewSettlement): Promise<{
+        created: boolean;
+        record: SettlementRecord;
+    }>;
+    /**
+     * Compare-and-set transition. Returns the new record, or `undefined` if the
+     * current state is not one of `from` (someone else moved it first).
+     */
+    transition(key: string, from: readonly SettlementState[], to: SettlementState, patch?: TransitionPatch): Promise<SettlementRecord | undefined>;
+    /** Records a non-transition event (e.g. a retry) in the payment journal. */
+    event(event: SettlementEvent): Promise<void>;
+    /** Non-terminal settlements, oldest first — resumed by the recovery worker. */
+    listActive(limit?: number): Promise<SettlementRecord[]>;
+    events(key: string): Promise<{
+        kind: string;
+        from: string | null;
+        to: string | null;
+        data: unknown;
+    }[]>;
+    /** Drops signed unit bodies of terminal settlements older than `olderThan` (unix s). */
+    pruneUnitBodies(olderThan: number): Promise<number>;
+    private insertEvent;
+    private mustGet;
+    private tx;
+}
+//# sourceMappingURL=store.d.ts.map

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

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

package/dist/exact/store.js

@@ -0,0 +1,212 @@
+import { DatabaseSync } from 'node:sqlite';
+import { ObbyxError } from '@obbyx/obyte';
+export const TERMINAL_STATES = new Set([
+    'stable_good',
+    'final_bad',
+    'rejected',
+    'expired',
+]);
+export class StoreLockedError extends ObbyxError {
+    constructor(path, cause) {
+        super('store_locked', `Database ${path} is in use by another facilitator process (one instance per database file)`, { cause, details: { path } });
+    }
+}
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS exact_settlements (
+  key TEXT PRIMARY KEY,
+  network TEXT NOT NULL,
+  unit_hash TEXT NOT NULL,
+  binding TEXT NOT NULL,
+  payer TEXT NOT NULL,
+  pay_to TEXT NOT NULL,
+  asset TEXT NOT NULL,
+  amount TEXT NOT NULL,
+  state TEXT NOT NULL,
+  unit_json TEXT,
+  publish_deadline INTEGER NOT NULL,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  last_error TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+) STRICT;
+CREATE INDEX IF NOT EXISTS exact_settlements_active ON exact_settlements(state)
+  WHERE state IN ('claimed', 'broadcasting', 'accepted');
+CREATE TABLE IF NOT EXISTS events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  ts INTEGER NOT NULL,
+  key TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  from_state TEXT,
+  to_state TEXT,
+  data TEXT
+) STRICT;
+CREATE INDEX IF NOT EXISTS events_key ON events(key);
+`;
+export class SqliteSettlementStore {
+    db;
+    now;
+    /**
+     * @param path SQLite file, or `:memory:` for tests.
+     * @param now  Clock in unix seconds (injectable for tests).
+     */
+    constructor(path, now = () => Math.floor(Date.now() / 1000)) {
+        this.now = now;
+        this.db = new DatabaseSync(path);
+        try {
+            this.db.exec('PRAGMA busy_timeout = 0');
+            this.db.exec('PRAGMA journal_mode = WAL');
+            this.db.exec('PRAGMA synchronous = FULL');
+            // Exclusive lock for the lifetime of the connection: a second process
+            // fails on its first write instead of racing us.
+            this.db.exec('PRAGMA locking_mode = EXCLUSIVE');
+            this.db.exec('BEGIN IMMEDIATE');
+            this.db.exec(SCHEMA);
+            this.db.exec('COMMIT');
+        }
+        catch (err) {
+            this.db.close();
+            if (isBusy(err))
+                throw new StoreLockedError(path, err);
+            throw err;
+        }
+    }
+    async close() {
+        this.db.close();
+    }
+    /** The exclusive connection, shared with other facilitator stores (e.g. BatchStore). */
+    get database() {
+        return this.db;
+    }
+    async get(key) {
+        return this.getSync(key);
+    }
+    getSync(key) {
+        const row = this.db.prepare('SELECT * FROM exact_settlements WHERE key = ?').get(key);
+        return row === undefined ? undefined : toRecord(row);
+    }
+    /**
+     * Inserts a new settlement in state `claimed` unless the key exists.
+     * Returns the stored record and whether this call created it.
+     */
+    async claim(input) {
+        return this.tx(() => {
+            const existing = this.getSync(input.key);
+            if (existing !== undefined)
+                return { created: false, record: existing };
+            const ts = this.now();
+            this.db
+                .prepare(`INSERT INTO exact_settlements
+            (key, network, unit_hash, binding, payer, pay_to, asset, amount, state, unit_json,
+             publish_deadline, attempts, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'claimed', ?, ?, 0, ?, ?)`)
+                .run(input.key, input.network, input.unitHash, input.binding, input.payer, input.payTo, input.asset, input.amount, input.unitJson, input.publishDeadline, ts, ts);
+            this.insertEvent({ key: input.key, kind: 'claimed', from: null, to: 'claimed' }, ts);
+            return { created: true, record: this.mustGet(input.key) };
+        });
+    }
+    /**
+     * Compare-and-set transition. Returns the new record, or `undefined` if the
+     * current state is not one of `from` (someone else moved it first).
+     */
+    async transition(key, from, to, patch = {}) {
+        return this.tx(() => {
+            const current = this.getSync(key);
+            if (current === undefined || !from.includes(current.state))
+                return undefined;
+            const ts = this.now();
+            this.db
+                .prepare(`UPDATE exact_settlements
+             SET state = ?, last_error = ?, attempts = attempts + ?, updated_at = ?
+           WHERE key = ? AND state = ?`)
+                .run(to, patch.lastError === undefined ? current.lastError : patch.lastError, patch.incrementAttempts === true ? 1 : 0, ts, key, current.state);
+            this.insertEvent({
+                key,
+                kind: 'transition',
+                from: current.state,
+                to,
+                ...(patch.data ? { data: patch.data } : {}),
+            }, ts);
+            return this.mustGet(key);
+        });
+    }
+    /** Records a non-transition event (e.g. a retry) in the payment journal. */
+    async event(event) {
+        this.insertEvent(event, this.now());
+    }
+    /** Non-terminal settlements, oldest first — resumed by the recovery worker. */
+    async listActive(limit = 100) {
+        const rows = this.db
+            .prepare(`SELECT * FROM exact_settlements
+          WHERE state IN ('claimed', 'broadcasting', 'accepted')
+          ORDER BY updated_at ASC LIMIT ?`)
+            .all(limit);
+        return rows.map(toRecord);
+    }
+    async events(key) {
+        const rows = this.db
+            .prepare('SELECT kind, from_state, to_state, data FROM events WHERE key = ? ORDER BY id')
+            .all(key);
+        return rows.map((r) => ({
+            kind: r.kind,
+            from: r.from_state,
+            to: r.to_state,
+            data: r.data === null ? null : JSON.parse(r.data),
+        }));
+    }
+    /** Drops signed unit bodies of terminal settlements older than `olderThan` (unix s). */
+    async pruneUnitBodies(olderThan) {
+        const res = this.db
+            .prepare(`UPDATE exact_settlements SET unit_json = NULL
+          WHERE unit_json IS NOT NULL AND updated_at < ?
+            AND state IN ('stable_good', 'final_bad', 'rejected', 'expired')`)
+            .run(olderThan);
+        return Number(res.changes);
+    }
+    insertEvent(event, ts) {
+        this.db
+            .prepare('INSERT INTO events (ts, key, kind, from_state, to_state, data) VALUES (?, ?, ?, ?, ?, ?)')
+            .run(ts, event.key, event.kind, event.from ?? null, event.to ?? null, event.data === undefined ? null : JSON.stringify(event.data));
+    }
+    mustGet(key) {
+        const record = this.getSync(key);
+        if (record === undefined)
+            throw new ObbyxError('store_inconsistent', `Missing settlement ${key}`);
+        return record;
+    }
+    tx(fn) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const result = fn();
+            this.db.exec('COMMIT');
+            return result;
+        }
+        catch (err) {
+            this.db.exec('ROLLBACK');
+            throw err;
+        }
+    }
+}
+function toRecord(row) {
+    return {
+        key: row.key,
+        network: row.network,
+        unitHash: row.unit_hash,
+        binding: row.binding,
+        payer: row.payer,
+        payTo: row.pay_to,
+        asset: row.asset,
+        amount: row.amount,
+        state: row.state,
+        unitJson: row.unit_json,
+        publishDeadline: row.publish_deadline,
+        attempts: row.attempts,
+        lastError: row.last_error,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function isBusy(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return /database is locked|SQLITE_BUSY/i.test(message);
+}
+//# sourceMappingURL=store.js.map

package/dist/exact/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/exact/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAqB1C,MAAM,CAAC,MAAM,eAAe,GAAiC,IAAI,GAAG,CAAC;IACnE,aAAa;IACb,WAAW;IACX,UAAU;IACV,SAAS;CACV,CAAC,CAAC;AAyEH,MAAM,OAAO,gBAAiB,SAAQ,UAAU;IAC9C,YAAY,IAAY,EAAE,KAAc;QACtC,KAAK,CACH,cAAc,EACd,YAAY,IAAI,4EAA4E,EAC5F,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,CAC7B,CAAC;IACJ,CAAC;CACF;AAoBD,MAAM,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8Bd,CAAC;AAEF,MAAM,OAAO,qBAAqB;IACf,EAAE,CAAe;IACjB,GAAG,CAAe;IAEnC;;;OAGG;IACH,YAAY,IAAY,EAAE,MAAoB,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;QAC/E,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,EAAE,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC;YACH,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;YACxC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;YAC1C,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;YAC1C,sEAAsE;YACtE,iDAAiD;YACjD,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;YAChD,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;YAChC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrB,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;YAChB,IAAI,MAAM,CAAC,GAAG,CAAC;gBAAE,MAAM,IAAI,gBAAgB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YACvD,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;IAED,wFAAwF;IACxF,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,EAAE,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAEO,OAAO,CAAC,GAAW;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE,CAAC,OAAO,CAAC,+CAA+C,CAAC,CAAC,GAAG,CAAC,GAAG,CACnE,CAAC;QAClB,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IACvD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,CAAC,KAAoB;QAC9B,OAAO,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE;YAClB,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACzC,IAAI,QAAQ,KAAK,SAAS;gBAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;YACxE,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACtB,IAAI,CAAC,EAAE;iBACJ,OAAO,CACN;;;qEAG2D,CAC5D;iBACA,GAAG,CACF,KAAK,CAAC,GAAG,EACT,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,OAAO,EACb,KAAK,CAAC,KAAK,EACX,KAAK,CAAC,KAAK,EACX,KAAK,CAAC,KAAK,EACX,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,QAAQ,EACd,KAAK,CAAC,eAAe,EACrB,EAAE,EACF,EAAE,CACH,CAAC;YACJ,IAAI,CAAC,WAAW,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;YACrF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5D,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,UAAU,CACd,GAAW,EACX,IAAgC,EAChC,EAAmB,EACnB,QAAyB,EAAE;QAE3B,OAAO,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE;YAClB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,OAAO,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC;gBAAE,OAAO,SAAS,CAAC;YAC7E,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACtB,IAAI,CAAC,EAAE;iBACJ,OAAO,CACN;;uCAE6B,CAC9B;iBACA,GAAG,CACF,EAAE,EACF,KAAK,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,EACnE,KAAK,CAAC,iBAAiB,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EACxC,EAAE,EACF,GAAG,EACH,OAAO,CAAC,KAAK,CACd,CAAC;YACJ,IAAI,CAAC,WAAW,CACd;gBACE,GAAG;gBACH,IAAI,EAAE,YAAY;gBAClB,IAAI,EAAE,OAAO,CAAC,KAAK;gBACnB,EAAE;gBACF,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC5C,EACD,EAAE,CACH,CAAC;YACF,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC,CAAC,CAAC;IACL,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,KAAK,CAAC,KAAsB;QAChC,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,+EAA+E;IAC/E,KAAK,CAAC,UAAU,CAAC,KAAK,GAAG,GAAG;QAC1B,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE;aACjB,OAAO,CACN;;0CAEkC,CACnC;aACA,GAAG,CAAC,KAAK,CAAqB,CAAC;QAClC,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,MAAM,CACV,GAAW;QAEX,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE;aACjB,OAAO,CAAC,+EAA+E,CAAC;aACxF,GAAG,CAAC,GAAG,CAKP,CAAC;QACJ,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACtB,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,IAAI,EAAE,CAAC,CAAC,UAAU;YAClB,EAAE,EAAE,CAAC,CAAC,QAAQ;YACd,IAAI,EAAE,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAa;SAC/D,CAAC,CAAC,CAAC;IACN,CAAC;IAED,wFAAwF;IACxF,KAAK,CAAC,eAAe,CAAC,SAAiB;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,EAAE;aAChB,OAAO,CACN;;6EAEqE,CACtE;aACA,GAAG,CAAC,SAAS,CAAC,CAAC;QAClB,OAAO,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAEO,WAAW,CAAC,KAAsB,EAAE,EAAU;QACpD,IAAI,CAAC,EAAE;aACJ,OAAO,CACN,0FAA0F,CAC3F;aACA,GAAG,CACF,EAAE,EACF,KAAK,CAAC,GAAG,EACT,KAAK,CAAC,IAAI,EACV,KAAK,CAAC,IAAI,IAAI,IAAI,EAClB,KAAK,CAAC,EAAE,IAAI,IAAI,EAChB,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAC7D,CAAC;IACN,CAAC;IAEO,OAAO,CAAC,GAAW;QACzB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,MAAM,KAAK,SAAS;YACtB,MAAM,IAAI,UAAU,CAAC,oBAAoB,EAAE,sBAAsB,GAAG,EAAE,CAAC,CAAC;QAC1E,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,EAAE,CAAI,EAAW;QACvB,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAChC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,EAAE,EAAE,CAAC;YACpB,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACvB,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YACzB,MAAM,GAAG,CAAC;QACZ,CAAC;IACH,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,GAAQ;IACxB,OAAO;QACL,GAAG,EAAE,GAAG,CAAC,GAAG;QACZ,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,QAAQ,EAAE,GAAG,CAAC,SAAS;QACvB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,KAAK,EAAE,GAAG,CAAC,MAAM;QACjB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,QAAQ,EAAE,GAAG,CAAC,SAAS;QACvB,eAAe,EAAE,GAAG,CAAC,gBAAgB;QACrC,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,SAAS,EAAE,GAAG,CAAC,UAAU;QACzB,SAAS,EAAE,GAAG,CAAC,UAAU;KAC1B,CAAC;AACJ,CAAC;AAED,SAAS,MAAM,CAAC,GAAY;IAC1B,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,OAAO,iCAAiC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACzD,CAAC"}