@avow-finance/verifier 0.0.0-stage → 0.1.0

package/dist/report.d.ts

@@ -0,0 +1,128 @@
+import { type AvowDomain, type ChargeKind, type ChargeReport, type HashSigner, type RailToken, type ReasonCode, type Signed } from '@avow-finance/spec';
+import { type Address, type Hex } from 'viem';
+import { type ChainReader } from './chain.js';
+import { type Disclosure } from './disclosure.js';
+/** A report stays valid for ten minutes at most, and never past the charge deadline. */
+export declare const REPORT_VALIDITY = 600n;
+export interface ReportConfig {
+    chainId: number;
+    /** The supplier's signing key, which signs the report and which the lock has to hold. */
+    signingKey: Address;
+    /** Tokens the supplier accepts, used to show the amount a report charges. */
+    acceptedTokens: readonly RailToken[];
+}
+export interface ReportDeps {
+    config: ReportConfig;
+    chain: ChainReader;
+}
+/** What a supplier hands the verifier to get a report of a charge to sign. */
+export interface ReportRequest {
+    lock: Address;
+    commitmentId: Hex;
+    kind: ChargeKind;
+    /** Base units of the lock's token. The most the terms let this kind of charge take when left out. */
+    amount?: bigint;
+    /** The keccak256 of the supplier's evidence for the charge. */
+    evidenceHash: Hex;
+    /** The chain's time, which the lock judges a report's timing by. */
+    now: bigint;
+    /** The report's nonce, a fresh random one when left out. */
+    nonce?: bigint;
+}
+export interface ReadyReport {
+    ok: true;
+    report: ChargeReport;
+    domain: AvowDomain;
+    /** The digest the supplier's signing key signs. */
+    digest: Hex;
+    /** The key that has to sign, the signing key the lock holds for the commitment. */
+    signingKey: Address;
+    /**
+     * Which of the commitment's reports this one is, 1 or 2. The lock's `reportCount` reaches it once
+     * the report lands, and passes it once a later report replaces a withdrawn one.
+     */
+    reportNumber: number;
+    /** What to show the person who approves the signature, before signing. */
+    disclosure: Disclosure;
+}
+export type PreparedReport = ReadyReport | {
+    ok: false;
+    reason: ReasonCode;
+};
+/**
+ * The supported way for a supplier to get a report of a charge to sign. A report asks the lock to
+ * charge the business's reserve, so this builds one only when the lock would take it, and refuses
+ * with the first reason that applies.
+ *
+ * 1. The lock comes from Avow's factory and holds the commitment with this supplier's signing key.
+ * 2. The commitment is accepted with no report open, and it has fewer than two reports.
+ * 3. Its terms carry a charge of the reported kind, and the amount, that charge's most when left
+ *    out, is above zero and within it.
+ * 4. The time is at or after that charge's earliest and before the charge deadline.
+ *
+ * What it returns is frozen, and `signReport` signs nothing else. The lock checks the signature
+ * and the same rules when the report lands, so it takes a correctly signed report however it was
+ * built.
+ *
+ * Throws when the chain reader is for another chain or the chain can't be read.
+ */
+export declare function prepareReport(request: ReportRequest, deps: ReportDeps): Promise<PreparedReport>;
+/**
+ * Signs a report with the supplier's signing key, once the person has seen its disclosure. It
+ * signs only the object `prepareReport` returned, which is frozen, so a copy or an edit of it
+ * throws. It also throws when the confirmation names another disclosure, or when the key isn't
+ * the signing key the lock holds for the commitment.
+ */
+export declare function signReport(prepared: ReadyReport, key: HashSigner, confirmation: {
+    disclosureId: Hex;
+}): Promise<Signed<ChargeReport>>;
+/**
+ * The lock's `report`, as the testnet lock declares it. The report's fields come from the spec's
+ * `REPORT_TYPES`, so the call carries the fields the signature covers, in the same order. Anyone
+ * can send it, since the lock checks the supplier's signing key signed the report, so a supplier
+ * can send it from any account that pays the fee.
+ */
+export declare const REPORT_ABI: readonly [{
+    readonly type: 'function';
+    readonly name: 'report';
+    readonly inputs: readonly [{
+        readonly name: 'm';
+        readonly type: 'tuple';
+        readonly components: readonly [{
+            readonly name: 'commitmentId';
+            readonly type: 'bytes32';
+        }, {
+            readonly name: 'side';
+            readonly type: 'uint8';
+        }, {
+            readonly name: 'kind';
+            readonly type: 'uint8';
+        }, {
+            readonly name: 'amount';
+            readonly type: 'uint256';
+        }, {
+            readonly name: 'evidenceHash';
+            readonly type: 'bytes32';
+        }, {
+            readonly name: 'nonce';
+            readonly type: 'uint256';
+        }, {
+            readonly name: 'expiry';
+            readonly type: 'uint64';
+        }];
+    }, {
+        readonly name: 'signature';
+        readonly type: 'bytes';
+    }];
+    readonly outputs: readonly [];
+    readonly stateMutability: 'nonpayable';
+}];
+/**
+ * The call that hands a signed report to its lock, with the fields exactly as they were signed, so
+ * the lock checks the same digest the supplier's key signed.
+ */
+export declare function reportCall(report: Signed<ChargeReport>): {
+    to: Address;
+    data: Hex;
+};
+//# sourceMappingURL=report.d.ts.map

package/dist/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EAEf,KAAK,UAAU,EACf,KAAK,YAAY,EAEjB,KAAK,UAAU,EACf,KAAK,SAAS,EAEd,KAAK,UAAU,EAEf,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,KAAK,OAAO,EAAsB,KAAK,GAAG,EAA+B,MAAM,MAAM,CAAA;AAC9F,OAAO,EAAE,KAAK,WAAW,EAAe,MAAM,YAAY,CAAA;AAC1D,OAAO,EAAE,KAAK,UAAU,EAAiC,MAAM,iBAAiB,CAAA;AAKhF,wFAAwF;AACxF,eAAO,MAAM,eAAe,OAAO,CAAA;AAEnC,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,yFAAyF;IACzF,UAAU,EAAE,OAAO,CAAA;IACnB,6EAA6E;IAC7E,cAAc,EAAE,SAAS,SAAS,EAAE,CAAA;CACrC;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,YAAY,CAAA;IACpB,KAAK,EAAE,WAAW,CAAA;CACnB;AAED,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAA;IACb,YAAY,EAAE,GAAG,CAAA;IACjB,IAAI,EAAE,UAAU,CAAA;IAChB,qGAAqG;IACrG,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,+DAA+D;IAC/D,YAAY,EAAE,GAAG,CAAA;IACjB,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAA;IACX,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,IAAI,CAAA;IACR,MAAM,EAAE,YAAY,CAAA;IACpB,MAAM,EAAE,UAAU,CAAA;IAClB,mDAAmD;IACnD,MAAM,EAAE,GAAG,CAAA;IACX,mFAAmF;IACnF,UAAU,EAAE,OAAO,CAAA;IACnB;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAA;IACpB,0EAA0E;IAC1E,UAAU,EAAE,UAAU,CAAA;CACvB;AAED,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAA;AAI5E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,cAAc,CAAC,CAqEzB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,WAAW,EACrB,GAAG,EAAE,UAAU,EACf,YAAY,EAAE;IAAE,YAAY,EAAE,GAAG,CAAA;CAAE,GAClC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAa/B;AAED;;;;;GAKG;AACH,eAAO,MAAM,UAAU;aAEnB,IAAI,EAAE,UAAU;aAChB,IAAI,EAAE,QAAQ;aACd,MAAM;iBACF,IAAI,EAAE,GAAG;iBAAE,IAAI,EAAE,OAAO;iBAAE,UAAU;;;;;;;;;;;;;;;;;;;;;;;iBACpC,IAAI,EAAE,WAAW;iBAAE,IAAI,EAAE,OAAO;;aAEpC,OAAO;aACP,eAAe,EAAE,YAAY;EAEvB,CAAA;AAEV;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,YAAY,CAAC,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,GAAG,CAAA;CAAE,CAUnF"}

package/dist/report.js

@@ -0,0 +1,155 @@
+import { CHARGE_KINDS, digestOf, REPORT_TYPES, reportTypedData, } from '@avow-finance/spec';
+import { encodeFunctionData, isAddressEqual, isHex, size } from 'viem';
+import { MAX_REPORTS } from './chain.js';
+import { listedToken, reportDisclosure } from './disclosure.js';
+import { issue } from './issued.js';
+import { randomNonce } from './nonce.js';
+import { signWithKey } from './signing.js';
+/** A report stays valid for ten minutes at most, and never past the charge deadline. */
+export const REPORT_VALIDITY = 600n;
+const isBytes32 = (value) => isHex(value) && size(value) === 32;
+/**
+ * The supported way for a supplier to get a report of a charge to sign. A report asks the lock to
+ * charge the business's reserve, so this builds one only when the lock would take it, and refuses
+ * with the first reason that applies.
+ *
+ * 1. The lock comes from Avow's factory and holds the commitment with this supplier's signing key.
+ * 2. The commitment is accepted with no report open, and it has fewer than two reports.
+ * 3. Its terms carry a charge of the reported kind, and the amount, that charge's most when left
+ *    out, is above zero and within it.
+ * 4. The time is at or after that charge's earliest and before the charge deadline.
+ *
+ * What it returns is frozen, and `signReport` signs nothing else. The lock checks the signature
+ * and the same rules when the report lands, so it takes a correctly signed report however it was
+ * built.
+ *
+ * Throws when the chain reader is for another chain or the chain can't be read.
+ */
+export async function prepareReport(request, deps) {
+    const { config, chain } = deps;
+    if (chain.chainId !== config.chainId) {
+        throw new Error(`The chain reader is for chain ${chain.chainId}, not ${config.chainId}`);
+    }
+    const refuse = (reason) => ({ ok: false, reason });
+    if (!Object.hasOwn(CHARGE_KINDS, request.kind) ||
+        !isBytes32(request.commitmentId) ||
+        !isBytes32(request.evidenceHash) ||
+        (request.amount !== undefined && typeof request.amount !== 'bigint')) {
+        return refuse('message.invalid');
+    }
+    // The commitment on the lock, and the supplier's own signing key on it.
+    const lockInfo = await chain.lock(request.lock);
+    if (!lockInfo?.fromFactory)
+        return refuse('chain.lock_unknown');
+    const b = await chain.backing(request.lock, request.commitmentId, 'buyer');
+    if (!b || b.state === 'none')
+        return refuse('chain.reserve_missing');
+    if (!isAddressEqual(b.supplierSigner, config.signingKey))
+        return refuse('chain.supplier_mismatch');
+    // The lock takes a report only on an accepted commitment, one report at a time and two at most.
+    if (b.state !== 'accepted')
+        return refuse('report.not_reportable');
+    if (b.hasReport)
+        return refuse('report.open');
+    if (b.reportCount >= MAX_REPORTS)
+        return refuse('report.limit_reached');
+    // The charge the terms set for this kind, its most and its window.
+    const charge = b.charges.find((c) => c.kind === request.kind);
+    if (!charge)
+        return refuse('report.kind_not_allowed');
+    const amount = request.amount ?? charge.most;
+    if (amount <= 0n || amount > charge.most)
+        return refuse('report.amount_invalid');
+    if (request.now < charge.earliest)
+        return refuse('report.too_early');
+    if (request.now >= b.chargeDeadline)
+        return refuse('commitment.ended');
+    const latest = request.now + REPORT_VALIDITY;
+    const report = {
+        commitmentId: request.commitmentId,
+        side: 'buyer',
+        kind: request.kind,
+        amount,
+        evidenceHash: request.evidenceHash,
+        nonce: request.nonce ?? randomNonce(),
+        expiry: latest < b.chargeDeadline ? latest : b.chargeDeadline,
+    };
+    const d = { chainId: config.chainId, verifyingContract: request.lock };
+    const digest = digestOf(reportTypedData(report, d));
+    return issue({
+        ok: true,
+        report,
+        domain: d,
+        digest,
+        signingKey: config.signingKey,
+        reportNumber: b.reportCount + 1,
+        disclosure: reportDisclosure({
+            digest,
+            report,
+            lock: request.lock,
+            chainId: config.chainId,
+            account: lockInfo.account,
+            payee: b.payee,
+            token: listedToken(config.acceptedTokens, config.chainId, lockInfo.token),
+            chargeDeadline: b.chargeDeadline,
+            contestWindow: b.contestWindow,
+            day90SupplierShareBps: b.day90SupplierShareBps,
+            timing: lockInfo.timing,
+            reportCount: b.reportCount,
+        }),
+    });
+}
+/**
+ * Signs a report with the supplier's signing key, once the person has seen its disclosure. It
+ * signs only the object `prepareReport` returned, which is frozen, so a copy or an edit of it
+ * throws. It also throws when the confirmation names another disclosure, or when the key isn't
+ * the signing key the lock holds for the commitment.
+ */
+export function signReport(prepared, key, confirmation) {
+    return signWithKey({
+        prepared,
+        typedData: reportTypedData(prepared.report, prepared.domain),
+        message: prepared.report,
+        key,
+        confirmation,
+        names: {
+            message: 'report',
+            prepare: 'prepareReport',
+            signingKey: 'the signing key the lock holds for the commitment',
+        },
+    });
+}
+/**
+ * The lock's `report`, as the testnet lock declares it. The report's fields come from the spec's
+ * `REPORT_TYPES`, so the call carries the fields the signature covers, in the same order. Anyone
+ * can send it, since the lock checks the supplier's signing key signed the report, so a supplier
+ * can send it from any account that pays the fee.
+ */
+export const REPORT_ABI = [
+    {
+        type: 'function',
+        name: 'report',
+        inputs: [
+            { name: 'm', type: 'tuple', components: REPORT_TYPES.Report },
+            { name: 'signature', type: 'bytes' },
+        ],
+        outputs: [],
+        stateMutability: 'nonpayable',
+    },
+];
+/**
+ * The call that hands a signed report to its lock, with the fields exactly as they were signed, so
+ * the lock checks the same digest the supplier's key signed.
+ */
+export function reportCall(report) {
+    const d = { chainId: report.chainId, verifyingContract: report.lock };
+    return {
+        to: report.lock,
+        data: encodeFunctionData({
+            abi: REPORT_ABI,
+            functionName: 'report',
+            args: [reportTypedData(report.message, d).message, report.signature],
+        }),
+    };
+}
+//# sourceMappingURL=report.js.map

package/dist/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,YAAY,EAGZ,QAAQ,EAGR,YAAY,EAEZ,eAAe,GAEhB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAgB,kBAAkB,EAAY,cAAc,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAC9F,OAAO,EAAoB,WAAW,EAAE,MAAM,YAAY,CAAA;AAC1D,OAAO,EAAmB,WAAW,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAChF,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAE1C,wFAAwF;AACxF,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAA;AAiDnC,MAAM,SAAS,GAAG,CAAC,KAAc,EAAgB,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAA;AAEtF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAsB,EACtB,IAAgB;IAEhB,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAA;IAC9B,IAAI,KAAK,CAAC,OAAO,KAAK,MAAM,CAAC,OAAO,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,iCAAiC,KAAK,CAAC,OAAO,SAAS,MAAM,CAAC,OAAO,EAAE,CAAC,CAAA;IAC1F,CAAC;IACD,MAAM,MAAM,GAAG,CAAC,MAAkB,EAAkB,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;IAC9E,IACE,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,IAAI,CAAC;QAC1C,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,CAAC;QAChC,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,CAAC;QAChC,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,EACpE,CAAC;QACD,OAAO,MAAM,CAAC,iBAAiB,CAAC,CAAA;IAClC,CAAC;IAED,wEAAwE;IACxE,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/C,IAAI,CAAC,QAAQ,EAAE,WAAW;QAAE,OAAO,MAAM,CAAC,oBAAoB,CAAC,CAAA;IAC/D,MAAM,CAAC,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,CAAA;IAC1E,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC,uBAAuB,CAAC,CAAA;IACpE,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,cAAc,EAAE,MAAM,CAAC,UAAU,CAAC;QAAE,OAAO,MAAM,CAAC,yBAAyB,CAAC,CAAA;IAElG,gGAAgG;IAChG,IAAI,CAAC,CAAC,KAAK,KAAK,UAAU;QAAE,OAAO,MAAM,CAAC,uBAAuB,CAAC,CAAA;IAClE,IAAI,CAAC,CAAC,SAAS;QAAE,OAAO,MAAM,CAAC,aAAa,CAAC,CAAA;IAC7C,IAAI,CAAC,CAAC,WAAW,IAAI,WAAW;QAAE,OAAO,MAAM,CAAC,sBAAsB,CAAC,CAAA;IAEvE,mEAAmE;IACnE,MAAM,MAAM,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7D,IAAI,CAAC,MAAM;QAAE,OAAO,MAAM,CAAC,yBAAyB,CAAC,CAAA;IACrD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,CAAA;IAC5C,IAAI,MAAM,IAAI,EAAE,IAAI,MAAM,GAAG,MAAM,CAAC,IAAI;QAAE,OAAO,MAAM,CAAC,uBAAuB,CAAC,CAAA;IAChF,IAAI,OAAO,CAAC,GAAG,GAAG,MAAM,CAAC,QAAQ;QAAE,OAAO,MAAM,CAAC,kBAAkB,CAAC,CAAA;IACpE,IAAI,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,cAAc;QAAE,OAAO,MAAM,CAAC,kBAAkB,CAAC,CAAA;IAEtE,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,eAAe,CAAA;IAC5C,MAAM,MAAM,GAAiB;QAC3B,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM;QACN,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,WAAW,EAAE;QACrC,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,cAAc;KAC9D,CAAA;IACD,MAAM,CAAC,GAAe,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,CAAC,IAAI,EAAE,CAAA;IAClF,MAAM,MAAM,GAAG,QAAQ,CAAC,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAA;IACnD,OAAO,KAAK,CAAC;QACX,EAAE,EAAE,IAAI;QACR,MAAM;QACN,MAAM,EAAE,CAAC;QACT,MAAM;QACN,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,YAAY,EAAE,CAAC,CAAC,WAAW,GAAG,CAAC;QAC/B,UAAU,EAAE,gBAAgB,CAAC;YAC3B,MAAM;YACN,MAAM;YACN,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC;YACzE,cAAc,EAAE,CAAC,CAAC,cAAc;YAChC,aAAa,EAAE,CAAC,CAAC,aAAa;YAC9B,qBAAqB,EAAE,CAAC,CAAC,qBAAqB;YAC9C,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,WAAW,EAAE,CAAC,CAAC,WAAW;SAC3B,CAAC;KACH,CAAC,CAAA;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CACxB,QAAqB,EACrB,GAAe,EACf,YAAmC;IAEnC,OAAO,WAAW,CAAC;QACjB,QAAQ;QACR,SAAS,EAAE,eAAe,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC;QAC5D,OAAO,EAAE,QAAQ,CAAC,MAAM;QACxB,GAAG;QACH,YAAY;QACZ,KAAK,EAAE;YACL,OAAO,EAAE,QAAQ;YACjB,OAAO,EAAE,eAAe;YACxB,UAAU,EAAE,mDAAmD;SAChE;KACF,CAAC,CAAA;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB;QACE,IAAI,EAAE,UAAU;QAChB,IAAI,EAAE,QAAQ;QACd,MAAM,EAAE;YACN,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,CAAC,MAAM,EAAE;YAC7D,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE;SACrC;QACD,OAAO,EAAE,EAAE;QACX,eAAe,EAAE,YAAY;KAC9B;CACO,CAAA;AAEV;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,MAA4B;IACrD,MAAM,CAAC,GAAe,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,iBAAiB,EAAE,MAAM,CAAC,IAAI,EAAE,CAAA;IACjF,OAAO;QACL,EAAE,EAAE,MAAM,CAAC,IAAI;QACf,IAAI,EAAE,kBAAkB,CAAC;YACvB,GAAG,EAAE,UAAU;YACf,YAAY,EAAE,QAAQ;YACtB,IAAI,EAAE,CAAC,eAAe,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC;SACrE,CAAC;KACH,CAAA;AACH,CAAC"}

package/dist/signing.d.ts

@@ -0,0 +1,47 @@
+import { type AvowDomain, type AvowTypedData, type HashSigner, type Signed } from '@avow-finance/spec';
+import type { Address, Hex } from 'viem';
+import { type Disclosure } from './disclosure.js';
+/** What a prepare call returns for a message, which only that message's signing call signs. */
+export interface Prepared {
+    domain: AvowDomain;
+    /** The digest the message's signer signs. */
+    digest: Hex;
+    disclosure: Disclosure;
+}
+/** How a signing call's errors name its message and the prepare call that built it. */
+export interface SigningNames {
+    message: string;
+    prepare: string;
+}
+/**
+ * Checks a prepared message before anything signs it, and returns the digest to sign. It has to be
+ * the frozen object its prepare call returned, its digest and disclosure have to match its message,
+ * and the confirmation has to name that disclosure, so nothing is signed before a person has seen
+ * what it binds the signer to.
+ */
+export declare function checkPrepared(prepared: Prepared, typedData: AvowTypedData, confirmation: {
+    disclosureId: Hex;
+}, names: SigningNames): Hex;
+/** A signed message as it travels, under the domain its prepare call built it for. */
+export declare function signedMessage<T>(typedData: AvowTypedData, domain: AvowDomain, message: T, signature: Hex): Signed<T>;
+/**
+ * Signs a prepared message with one key's own signature, as the supplier's signing key signs an
+ * acceptance or a report. It signs only once `checkPrepared` passes, and throws when the signature
+ * isn't the one key the message has to come from.
+ */
+export declare function signWithKey<T>(args: {
+    prepared: Prepared & {
+        signingKey: Address;
+    };
+    typedData: AvowTypedData;
+    message: T;
+    key: HashSigner;
+    confirmation: {
+        disclosureId: Hex;
+    };
+    /** `signingKey` describes the key the message has to come from, for the error. */
+    names: SigningNames & {
+        signingKey: string;
+    };
+}): Promise<Signed<T>>;
+//# sourceMappingURL=signing.d.ts.map

package/dist/signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.d.ts","sourceRoot":"","sources":["../src/signing.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EACf,KAAK,aAAa,EAElB,KAAK,UAAU,EAGf,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAA;AAC3B,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,MAAM,CAAA;AAExC,OAAO,EAAE,KAAK,UAAU,EAAgB,MAAM,iBAAiB,CAAA;AAG/D,+FAA+F;AAC/F,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,UAAU,CAAA;IAClB,6CAA6C;IAC7C,MAAM,EAAE,GAAG,CAAA;IACX,UAAU,EAAE,UAAU,CAAA;CACvB;AAED,uFAAuF;AACvF,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,aAAa,EACxB,YAAY,EAAE;IAAE,YAAY,EAAE,GAAG,CAAA;CAAE,EACnC,KAAK,EAAE,YAAY,GAClB,GAAG,CAqBL;AAED,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,CAAC,EAC7B,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,CAAC,EACV,SAAS,EAAE,GAAG,GACb,MAAM,CAAC,CAAC,CAAC,CASX;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE;IACzC,QAAQ,EAAE,QAAQ,GAAG;QAAE,UAAU,EAAE,OAAO,CAAA;KAAE,CAAA;IAC5C,SAAS,EAAE,aAAa,CAAA;IACxB,OAAO,EAAE,CAAC,CAAA;IACV,GAAG,EAAE,UAAU,CAAA;IACf,YAAY,EAAE;QAAE,YAAY,EAAE,GAAG,CAAA;KAAE,CAAA;IACnC,kFAAkF;IAClF,KAAK,EAAE,YAAY,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAA;CAC7C,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAOrB"}

package/dist/signing.js

@@ -0,0 +1,51 @@
+import { digestOf, isKeySignature, MESSAGE_VERSIONS, } from '@avow-finance/spec';
+import { same } from './authorization.js';
+import { disclosureId } from './disclosure.js';
+import { wasIssued } from './issued.js';
+/**
+ * Checks a prepared message before anything signs it, and returns the digest to sign. It has to be
+ * the frozen object its prepare call returned, its digest and disclosure have to match its message,
+ * and the confirmation has to name that disclosure, so nothing is signed before a person has seen
+ * what it binds the signer to.
+ */
+export function checkPrepared(prepared, typedData, confirmation, names) {
+    if (!wasIssued(prepared)) {
+        throw new Error(`Sign only the ${names.message} ${names.prepare} returned, as it returned it`);
+    }
+    const digest = digestOf(typedData);
+    const { disclosure } = prepared;
+    if (!same(digest, prepared.digest) ||
+        !same(disclosure.digest, digest) ||
+        !same(disclosureId(disclosure), disclosure.id)) {
+        throw new Error(`The ${names.message} or its disclosure changed after ${names.prepare} built them`);
+    }
+    if (!same(confirmation?.disclosureId, disclosure.id)) {
+        throw new Error(`Show the person this ${names.message}'s disclosure, and pass its id back once they confirm it`);
+    }
+    return digest;
+}
+/** A signed message as it travels, under the domain its prepare call built it for. */
+export function signedMessage(typedData, domain, message, signature) {
+    return {
+        type: typedData.primaryType,
+        schemaVersion: MESSAGE_VERSIONS[typedData.primaryType],
+        chainId: domain.chainId,
+        lock: domain.verifyingContract,
+        message,
+        signature,
+    };
+}
+/**
+ * Signs a prepared message with one key's own signature, as the supplier's signing key signs an
+ * acceptance or a report. It signs only once `checkPrepared` passes, and throws when the signature
+ * isn't the one key the message has to come from.
+ */
+export async function signWithKey(args) {
+    const digest = checkPrepared(args.prepared, args.typedData, args.confirmation, args.names);
+    const signature = await args.key.sign({ hash: digest });
+    if (!isKeySignature(digest, signature, args.prepared.signingKey)) {
+        throw new Error(`The key that signed isn't ${args.names.signingKey}`);
+    }
+    return signedMessage(args.typedData, args.prepared.domain, args.message, signature);
+}
+//# sourceMappingURL=signing.js.map

package/dist/signing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.js","sourceRoot":"","sources":["../src/signing.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,QAAQ,EAER,cAAc,EACd,gBAAgB,GAEjB,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAA;AACzC,OAAO,EAAmB,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAgBvC;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAkB,EAClB,SAAwB,EACxB,YAAmC,EACnC,KAAmB;IAEnB,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,iBAAiB,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAA;IAChG,CAAC;IACD,MAAM,MAAM,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAA;IAClC,MAAM,EAAE,UAAU,EAAE,GAAG,QAAQ,CAAA;IAC/B,IACE,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC;QAC9B,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC;QAChC,CAAC,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC,EAAE,CAAC,EAC9C,CAAC;QACD,MAAM,IAAI,KAAK,CACb,OAAO,KAAK,CAAC,OAAO,oCAAoC,KAAK,CAAC,OAAO,aAAa,CACnF,CAAA;IACH,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,YAAY,EAAE,UAAU,CAAC,EAAE,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CACb,wBAAwB,KAAK,CAAC,OAAO,0DAA0D,CAChG,CAAA;IACH,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,aAAa,CAC3B,SAAwB,EACxB,MAAkB,EAClB,OAAU,EACV,SAAc;IAEd,OAAO;QACL,IAAI,EAAE,SAAS,CAAC,WAAW;QAC3B,aAAa,EAAE,gBAAgB,CAAC,SAAS,CAAC,WAAW,CAAC;QACtD,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,IAAI,EAAE,MAAM,CAAC,iBAAiB;QAC9B,OAAO;QACP,SAAS;KACV,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAI,IAQpC;IACC,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;IAC1F,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAA;IACvD,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,CAAA;IACvE,CAAC;IACD,OAAO,aAAa,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAA;AACrF,CAAC"}

package/dist/tempo.d.ts

@@ -0,0 +1,70 @@
+import { type ObservedTransfer, type Side } from '@avow-finance/spec';
+import { type Address, type Client, type Hex, type Log } from 'viem';
+import type { AgentKeyInfo, ChainReader, ContestOnChain, LockedBacking, ObservedContest } from './chain.js';
+import type { PinnedLockReader } from './dependency.js';
+/**
+ * Reads an agent key from Tempo's keychain: whether it's revoked, when it expires, and the
+ * mandate hash bound into it. The keychain logs that hash as a witness in the transaction that
+ * authorized the key, and Moderato's public RPC searches logs only over short block ranges, so the
+ * caller names that transaction. Its receipt comes from the chain, so naming it proves nothing on
+ * its own: the key and the witness must both appear in it.
+ */
+export declare function readAgentKey(client: Client, account: Address, key: Address, authorizedIn: Hex): Promise<AgentKeyInfo | null>;
+/**
+ * Reads the log at one index of one transaction. The log counts as a payment only when a TIP-20
+ * token emitted it and it decodes as that token's `TransferWithMemo` event, and the caller checks
+ * that the token is the one the reference names and one it accepts. The receipt is final only
+ * when its block is at or below the chain's finalized block and is the chain's block at that
+ * height, so a receipt from a block that lost a reorg never reads as final.
+ */
+export declare function readTransfer(client: Client, chainId: number, transactionHash: Hex, logIndex: number): Promise<ObservedTransfer | null>;
+/**
+ * Reads what a lock holds for one side of a commitment, or null when it holds nothing. It reads
+ * only the lock, so it needs no factory, and the caller decides whether the lock is Avow's. Given
+ * a block number it reads the lock as of that block, and a node that doesn't have the block yet
+ * refuses the read.
+ */
+export declare function readBacking(client: Client, lock: Address, commitmentId: Hex, side: 'buyer' | 'supplier', options?: {
+    blockNumber?: bigint;
+}): Promise<LockedBacking | null>;
+/**
+ * The contest of one side of a commitment among one transaction's logs, from the `Paused` event the
+ * lock logged with a contest as its cause, or null when there's none. Only a log the lock itself
+ * wrote counts, since any contract can write one shaped like it. A transaction can carry calls to
+ * several commitments, so the event has to name this commitment and side.
+ */
+export declare function contestInLogs(logs: readonly Log[], lock: Address, commitmentId: Hex, side: Side): ObservedContest | null;
+/**
+ * Reads the contest of one side of a commitment that one transaction carried to a lock, from the
+ * transaction's receipt, with whether its block is final as `readTransfer` judges it, and the
+ * report it named as the lock held it at that block. It returns null when the chain has no such
+ * transaction, when the transaction failed, or when it holds no contest of that side from that
+ * lock, and throws when the node can't answer, so an outage never reads as a missing contest.
+ *
+ * The lock's record is read as of the end of the contest's block, so a withdrawal and a new report
+ * later in that same block would show the new report. The lock takes a contest only when it names
+ * the latest report, so the record shows the contested report unless both happened in that block.
+ */
+export declare function readContest(client: Client, lock: Address, commitmentId: Hex, side: Side, transactionHash: Hex): Promise<ContestOnChain | null>;
+export interface TempoReaderOptions {
+    /** The factory the supplier trusts. Only a lock it created counts as Avow's. */
+    factory: Address;
+    /** The chain's id, the client's own chain when left out. */
+    chainId?: number;
+}
+/**
+ * Reads the locks one factory created on Tempo, every read as of a block named by number, for the
+ * check of a booking another booking relies on. The latest finalized block is the one pinned, so
+ * no later block can change what it shows, and a node that doesn't have a block refuses the read.
+ * The pinned block carries its timestamp, so the check can refuse a node that has fallen behind.
+ * The caller trusts the node the client talks to, so it uses one it chose.
+ */
+export declare function tempoLockReader(client: Client, options: TempoReaderOptions): PinnedLockReader;
+/**
+ * Reads Tempo directly: the lock's settings and its record of a commitment, the agent key in the
+ * keychain, and account signatures through Tempo's own signature verifier. A lock counts as
+ * Avow's only when the factory the supplier pinned says it created it, since any contract can name
+ * a factory. The supplier trusts the node the client talks to, so it uses one it chose.
+ */
+export declare function tempoChainReader(client: Client, options: TempoReaderOptions): ChainReader;
+//# sourceMappingURL=tempo.d.ts.map

package/dist/tempo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tempo.d.ts","sourceRoot":"","sources":["../src/tempo.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,gBAAgB,EAGrB,KAAK,IAAI,EAEV,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,KAAK,OAAO,EAEZ,KAAK,MAAM,EACX,KAAK,GAAG,EAER,KAAK,GAAG,EAIT,MAAM,MAAM,CAAA;AAGb,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,cAAc,EACd,aAAa,EAEb,eAAe,EAChB,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAMvD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,OAAO,EACZ,YAAY,EAAE,GAAG,GAChB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAiC9B;AA8CD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,GAAG,EACpB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAyBlC;AAaD;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,YAAY,EAAE,GAAG,EACjB,IAAI,EAAE,OAAO,GAAG,UAAU,EAC1B,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GACrC,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAkD/B;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,GAAG,EAAE,EACpB,IAAI,EAAE,OAAO,EACb,YAAY,EAAE,GAAG,EACjB,IAAI,EAAE,IAAI,GACT,eAAe,GAAG,IAAI,CAkBxB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,YAAY,EAAE,GAAG,EACjB,IAAI,EAAE,IAAI,EACV,eAAe,EAAE,GAAG,GACnB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAkBhC;AAED,MAAM,WAAW,kBAAkB;IACjC,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAA;IAChB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AASD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,gBAAgB,CAqC7F;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAsDzF"}