@atcn/subledger 1.4.1 → 1.5.1

package/dist/rails.js

@@ -0,0 +1,242 @@
+import { secp256k1 } from "@noble/curves/secp256k1";
+import { sha256 } from "@noble/hashes/sha2";
+import { keccak_256 } from "@noble/hashes/sha3";
+import { bytesToHex, concatBytes, hexToBytes, utf8ToBytes } from "@noble/hashes/utils";
+const refuse = (code, detail) => ({ ok: false, code, detail });
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isHex64 = (value) => typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+const isCurrency = (value) => typeof value === "string" && /^[A-Z]{3}$/.test(value);
+const isAmount = (value) => Number.isSafeInteger(value) && value >= 0;
+// ---------- A2A-SE escrow attestations ----------
+export const A2A_SE_RELEASE_SCHEME = "urn:a2a-se:escrow-release-attestation:v1";
+export const A2A_SE_REFUND_SCHEME = "urn:a2a-se:escrow-refund-attestation:v1";
+/** Python's json.dumps(value, sort_keys=True, separators=(",", ":")), which A2A-SE hashes: keys by code point, non-ASCII escaped. */
+export function pythonCanonicalJson(value) {
+    if (value === null || typeof value === "boolean")
+        return String(value);
+    if (typeof value === "number") {
+        if (!Number.isSafeInteger(value))
+            throw new Error(`number ${value} is not an integer; A2A-SE records carry integers only`);
+        return String(value);
+    }
+    if (typeof value === "string")
+        return asciiJsonString(value);
+    if (Array.isArray(value))
+        return `[${value.map(pythonCanonicalJson).join(",")}]`;
+    if (isObject(value)) {
+        const keys = Object.keys(value).sort(byCodePoint);
+        return `{${keys.map((key) => `${asciiJsonString(key)}:${pythonCanonicalJson(value[key])}`).join(",")}}`;
+    }
+    throw new Error(`${typeof value} cannot be serialized`);
+}
+function asciiJsonString(value) {
+    return JSON.stringify(value).replace(/[\u007f-\uffff]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+function byCodePoint(a, b) {
+    const left = Array.from(a, (c) => c.codePointAt(0));
+    const right = Array.from(b, (c) => c.codePointAt(0));
+    for (let i = 0; i < Math.min(left.length, right.length); i++)
+        if (left[i] !== right[i])
+            return left[i] - right[i];
+    return left.length - right.length;
+}
+const leafHash = (canonical) => bytesToHex(sha256(concatBytes(new Uint8Array([0]), utf8ToBytes(canonical))));
+const nodeHash = (left, right) => bytesToHex(sha256(concatBytes(new Uint8Array([1]), hexToBytes(left), hexToBytes(right))));
+/**
+ * A record from GET /v1/exchange/escrow/{escrow_id}/attestations: { leaf_index, data_hash, merkle_root, proof, schema_id,
+ * payload }. The payload's leaf hash must be data_hash, and folding the proof must give merkle_root. A2A-SE attestations
+ * are not signed; the anchor is the Merkle root of the exchange's append-only log, which the reader should compare with
+ * the root the exchange publishes.
+ */
+export const a2aSeImporter = {
+    rail: "a2a-se",
+    schemes: [A2A_SE_RELEASE_SCHEME, A2A_SE_REFUND_SCHEME],
+    verify({ scheme, record }) {
+        const { payload, data_hash, merkle_root, proof, schema_id } = record;
+        if (schema_id !== scheme)
+            return refuse("malformed", `schema_id ${String(schema_id)} is not the declared scheme ${scheme}`);
+        if (!isObject(payload) || !isObject(payload.header) || payload.header.schema_id !== scheme)
+            return refuse("malformed", "payload.header.schema_id must be the declared scheme");
+        if (!isHex64(data_hash) || !isHex64(merkle_root) || !Array.isArray(proof))
+            return refuse("malformed", "data_hash, merkle_root and proof are required");
+        let canonical;
+        try {
+            canonical = pythonCanonicalJson(payload);
+        }
+        catch (error) {
+            return refuse("malformed", error.message);
+        }
+        if (leafHash(canonical) !== data_hash)
+            return refuse("data_hash_mismatch", "the payload does not hash to data_hash");
+        let computed = data_hash;
+        for (const step of proof) {
+            if (!isObject(step) || !isHex64(step.sibling_hash) || (step.side !== "left" && step.side !== "right"))
+                return refuse("malformed", "each proof step needs sibling_hash and side");
+            computed = step.side === "left" ? nodeHash(step.sibling_hash, computed) : nodeHash(computed, step.sibling_hash);
+        }
+        if (computed !== merkle_root)
+            return refuse("merkle_proof_invalid", "the proof does not lead from data_hash to merkle_root");
+        const settlement = payload.settlement;
+        const amount = scheme === A2A_SE_RELEASE_SCHEME ? payload.amount_paid : payload.amount_returned;
+        if (!isObject(settlement) || typeof settlement.escrow_id !== "string" || !isCurrency(settlement.currency) || !isAmount(amount)) {
+            return refuse("malformed", "settlement.escrow_id, settlement.currency and the amount are required");
+        }
+        return {
+            ok: true,
+            rail: "a2a-se",
+            anchor: `A2A-SE log leaf ${String(record.leaf_index)} under Merkle root ${merkle_root} (unsigned; compare the root with the one the exchange publishes)`,
+            facts: {
+                type: scheme === A2A_SE_RELEASE_SCHEME ? "payment_reported" : "refund",
+                amount_minor: amount,
+                currency: settlement.currency,
+                rail_ref: settlement.escrow_id,
+                job_ref: typeof settlement.task_id === "string" ? settlement.task_id : null,
+                occurred_at: typeof settlement.occurred_at === "string" ? settlement.occurred_at : null,
+            },
+        };
+    },
+};
+// ---------- x402 exact (EVM) payments ----------
+export const X402_EXACT_EVM_SCHEME = "x402:exact-evm:v2";
+/** USD stablecoins, by CAIP-2 network and token address (lowercase). ATCN records them as USD cents at 1:1. */
+export const X402_USD_ASSETS = {
+    "eip155:84532:0x036cbd53842c5426634e7929541ec2318f3dcf7e": { name: "USDC", decimals: 6 },
+    "eip155:8453:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913": { name: "USDC", decimals: 6 },
+};
+const keccakText = (text) => keccak_256(utf8ToBytes(text));
+const word = (value) => hexToBytes(value.toString(16).padStart(64, "0"));
+const addressWord = (address) => word(BigInt(address));
+const TRANSFER_TYPEHASH = keccakText("TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)");
+const DOMAIN_TYPEHASH = keccakText("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)");
+/** The EIP-712 digest a payer signs for an EIP-3009 transferWithAuthorization (the x402 "exact" EVM scheme). */
+export function eip3009Digest(authorization, domain) {
+    const domainSeparator = keccak_256(concatBytes(DOMAIN_TYPEHASH, keccakText(domain.name), keccakText(domain.version), word(domain.chainId), addressWord(domain.verifyingContract)));
+    const structHash = keccak_256(concatBytes(TRANSFER_TYPEHASH, addressWord(authorization.from), addressWord(authorization.to), word(BigInt(authorization.value)), word(BigInt(authorization.validAfter)), word(BigInt(authorization.validBefore)), hexToBytes(authorization.nonce.slice(2))));
+    return keccak_256(concatBytes(new Uint8Array([0x19, 0x01]), domainSeparator, structHash));
+}
+/** The address that made a 65-byte (r, s, v) secp256k1 signature over a digest. */
+export function recoverAddress(digest, signature) {
+    const bytes = hexToBytes(signature.slice(2));
+    const v = bytes[64];
+    const point = secp256k1.Signature.fromCompact(bytes.slice(0, 64))
+        .addRecoveryBit(v >= 27 ? v - 27 : v)
+        .recoverPublicKey(digest);
+    return `0x${bytesToHex(keccak_256(point.toRawBytes(false).slice(1)).slice(-20))}`;
+}
+/**
+ * A settled x402 payment: { requirements, payload, settlement } as the client and facilitator exchanged them. The payer's
+ * EIP-3009 authorization signature must recover its `from` address and authorize exactly the required amount to payTo.
+ * The facilitator's settlement response supplies success and the transaction hash; on-chain inclusion is not checked
+ * offline.
+ */
+export const x402Importer = {
+    rail: "x402",
+    schemes: [X402_EXACT_EVM_SCHEME],
+    verify({ record }) {
+        const { requirements, payload, settlement } = record;
+        if (!isObject(requirements) || !isObject(payload) || !isObject(settlement) || !isObject(payload.authorization) || typeof payload.signature !== "string") {
+            return refuse("malformed", "requirements, payload.authorization, payload.signature and settlement are required");
+        }
+        const authorization = payload.authorization;
+        const extra = isObject(requirements.extra) ? requirements.extra : {};
+        const network = String(requirements.network);
+        const chain = /^eip155:(\d+)$/.exec(network);
+        const hexFields = [authorization.from, authorization.to, String(requirements.asset), String(requirements.payTo)];
+        if (requirements.scheme !== "exact" || !chain || typeof extra.name !== "string" || typeof extra.version !== "string" || !hexFields.every((f) => /^0x[0-9a-fA-F]{40}$/.test(f))) {
+            return refuse("malformed", "requirements must be the exact scheme on an eip155 network, with extra.name, extra.version and EVM addresses");
+        }
+        if (!/^0x[0-9a-fA-F]{64}$/.test(authorization.nonce) || !/^0x[0-9a-fA-F]{130}$/.test(payload.signature))
+            return refuse("malformed", "nonce must be 32 bytes and signature 65 bytes, hex");
+        if (authorization.to.toLowerCase() !== String(requirements.payTo).toLowerCase() || authorization.value !== String(requirements.amount)) {
+            return refuse("malformed", "the authorization must pay exactly the required amount to payTo");
+        }
+        let signer;
+        try {
+            signer = recoverAddress(eip3009Digest(authorization, { name: extra.name, version: extra.version, chainId: BigInt(chain[1]), verifyingContract: String(requirements.asset) }), payload.signature);
+        }
+        catch {
+            return refuse("signature_invalid", "the authorization signature cannot be recovered");
+        }
+        if (signer !== authorization.from.toLowerCase())
+            return refuse("signature_invalid", `the authorization was signed by ${signer}, not the payer ${authorization.from}`);
+        if (settlement.success !== true || typeof settlement.transaction !== "string" || settlement.transaction === "" || settlement.network !== network) {
+            return refuse("settlement_not_successful", "the facilitator did not report a successful settlement on the required network");
+        }
+        const asset = X402_USD_ASSETS[`${network}:${String(requirements.asset)}`.toLowerCase()];
+        const perCent = asset ? 10n ** BigInt(asset.decimals - 2) : 0n;
+        if (!asset || BigInt(authorization.value) % perCent !== 0n)
+            return refuse("unsupported_asset", `no whole-cent USD conversion for ${String(requirements.asset)} on ${network}`);
+        return {
+            ok: true,
+            rail: "x402",
+            anchor: `payer ${authorization.from} signed the EIP-3009 authorization; transaction ${settlement.transaction} as reported by the facilitator (on-chain inclusion not checked offline)`,
+            facts: { type: "payment_reported", amount_minor: Number(BigInt(authorization.value) / perCent), currency: "USD", rail_ref: settlement.transaction, job_ref: authorization.nonce, occurred_at: null },
+        };
+    },
+};
+// ---------- Registry, consistency and the closure report ----------
+export const RAIL_IMPORTERS = [a2aSeImporter, x402Importer];
+export function verifyRailAttestation(attestation, importers = RAIL_IMPORTERS) {
+    const importer = importers.find((i) => i.schemes.includes(attestation.scheme));
+    return importer ? importer.verify(attestation) : refuse("unsupported_scheme", `no importer for scheme ${attestation.scheme}`);
+}
+/** Why a financial event's rail attestation does not support it, or null when it verifies and agrees with the event. */
+export function railAttestationProblem(event) {
+    if (!event.rail_attestation)
+        return null;
+    const result = verifyRailAttestation(event.rail_attestation);
+    if (!result.ok)
+        return { code: result.code, detail: result.detail };
+    const { facts } = result;
+    const mismatches = [
+        facts.type !== event.type ? `type ${event.type} (the rail recorded ${facts.type})` : null,
+        facts.amount_minor !== event.amount_minor ? `amount ${event.amount_minor} (the rail recorded ${facts.amount_minor})` : null,
+        facts.currency !== event.currency ? `currency ${event.currency} (the rail recorded ${facts.currency})` : null,
+        facts.rail_ref !== event.provider_reference ? `provider_reference ${String(event.provider_reference)} (the rail recorded ${facts.rail_ref})` : null,
+    ].filter((m) => m !== null);
+    return mismatches.length > 0 ? { code: "attestation_mismatch", detail: `the event does not match its rail attestation: ${mismatches.join("; ")}` } : null;
+}
+/** The closure's rail_attestations: one entry per event whose embedded attestation verifies and agrees with it; null when none carry one. */
+export function buildRailAttestationReport(events) {
+    const attested = events.filter((e) => e.record.rail_attestation);
+    if (attested.length === 0)
+        return null;
+    return attested.flatMap(({ record }) => {
+        const result = verifyRailAttestation(record.rail_attestation);
+        if (!result.ok || railAttestationProblem(record) !== null)
+            return [];
+        return [{ financial_event_id: record.financial_event_id, scheme: record.rail_attestation.scheme, rail: result.rail, rail_ref: result.facts.rail_ref, anchor: result.anchor, assurance: ["rail_attested"] }];
+    });
+}
+/**
+ * Buyer side: the financial event body for a rail record, after verifying it. Throws RailAttestationError with the
+ * refusal code when it does not verify. Matching uses the job reference the rail recorded unless `match` is given.
+ */
+export function financialEventFromRailAttestation(attestation, options) {
+    const result = verifyRailAttestation(attestation);
+    if (!result.ok)
+        throw new RailAttestationError(result.code, result.detail);
+    const { facts } = result;
+    const eventDate = facts.occurred_at ?? options.eventDate;
+    if (!eventDate)
+        throw new RailAttestationError("malformed", "the rail recorded no time; pass eventDate");
+    return {
+        type: facts.type,
+        source: options.source,
+        source_event_id: `${attestation.scheme}:${facts.rail_ref}`,
+        provider_reference: facts.rail_ref,
+        amount_minor: facts.amount_minor,
+        currency: facts.currency,
+        event_date: eventDate,
+        normalized_status: facts.type === "refund" ? "refunded" : "reported_paid",
+        match: options.match ?? (facts.job_ref ? { provider_job_ref: facts.job_ref } : {}),
+        rail_attestation: attestation,
+    };
+}
+export class RailAttestationError extends Error {
+    code;
+    constructor(code, detail) {
+        super(`${code}: ${detail}`);
+        this.code = code;
+    }
+}

package/dist/response.d.ts

@@ -18,6 +18,8 @@ export interface StatementInput {
     issued_at?: string;
     expires_at?: string;
     refs?: AttestationRef[];
+    /** Schema 1.5: "witness" when an independent witness signs that it observed the run. */
+    role?: "witness";
 }
 /** Builds the statement a provider responds with. Field order is irrelevant: the signature covers canonical JSON. */
 export declare function buildResponseStatement(input: StatementInput): ResponseStatement;

package/dist/response.js

@@ -17,6 +17,7 @@ export function buildResponseStatement(input) {
         ...(input.issued_at !== undefined ? { issued_at: input.issued_at } : {}),
         ...(input.expires_at !== undefined ? { expires_at: input.expires_at } : {}),
         ...(input.refs !== undefined ? { refs: input.refs } : {}),
+        ...(input.role !== undefined ? { role: input.role } : {}),
     };
 }
 export function statementDigest(statement) {

package/dist/rollup.d.ts

@@ -47,7 +47,7 @@ export interface Rollup {
         fx_rates: string[];
     };
 }
-/** +1 adds to buyer cost, -1 reduces it, 0 carries no cost (quotes, payment reports, reversals, rates). */
+/** +1 adds to buyer cost, -1 reduces it, 0 carries no cost (quotes, estimates, holds, payment reports, reversals, rates). */
 export declare function costSign(type: FinancialEventType): 1 | -1 | 0;
 export declare function emptyTotals(): Totals;
 /** True when an event counts as the buyer's own expense rather than reported downstream cost (acceptance 25). */

package/dist/rollup.js

@@ -1,4 +1,4 @@
-/** +1 adds to buyer cost, -1 reduces it, 0 carries no cost (quotes, payment reports, reversals, rates). */
+/** +1 adds to buyer cost, -1 reduces it, 0 carries no cost (quotes, estimates, holds, payment reports, reversals, rates). */
 export function costSign(type) {
     if (type === "invoice" || type === "charge" || type === "fee" || type === "adjustment")
         return 1;
@@ -71,6 +71,8 @@ export function computeRollup(input) {
             }
             continue;
         }
+        if (event.type === "estimate" || event.type === "hold")
+            continue;
         if (event.type === "payment_reported") {
             t.reported_paid += event.amount_minor;
             continue;
@@ -117,11 +119,14 @@ export function computeRollup(input) {
         }
     }
     // Children before parents: deepest first, so each subtree total is final when added to its parent.
+    // A parent outside the task or a parent cycle ends the walk; the verifier's lineage check reports both.
     const depth = (id) => {
         let d = 0;
         let current = nodes.get(id);
-        while (current.parent_id) {
+        const seen = new Set([id]);
+        while (current.parent_id && nodes.has(current.parent_id) && !seen.has(current.parent_id)) {
             d += 1;
+            seen.add(current.parent_id);
             current = nodes.get(current.parent_id);
         }
         return d;
@@ -131,8 +136,9 @@ export function computeRollup(input) {
         const node = nodes.get(id);
         addInto(node.total, node.direct);
         addInto(node.total, node.descendant);
-        if (node.parent_id)
-            addInto(nodes.get(node.parent_id).descendant, node.total);
+        const parent = node.parent_id ? nodes.get(node.parent_id) : undefined;
+        if (parent)
+            addInto(parent.descendant, node.total);
     }
     return {
         root_task_id: input.root.task_id,