@ftptech/x402-canton-core 0.1.0 → 0.1.1

package/dist/amount.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Canton Coin amount-unit conversion (x402-ENVELOPE upstream convention).
+ *
+ * The x402 v2 wire field `PaymentRequirements.maxAmountRequired` (this scheme's
+ * `amount`) travels in ATOMIC UNITS as an integer string, while the on-ledger
+ * Daml `Decimal` the Token Standard / TransferCommand uses is a fixed-scale
+ * decimal string. The conversion boundary is fixed across CIP-56 by the Daml
+ * `Decimal` scale: **1 CC = 10^10 atomic units** (10 decimal places).
+ *
+ * BACK-COMPAT (read this): the DEPLOYED v1 (external-party-amulet-rules, live on
+ * MainNet) and cip56 paths put a Daml **Decimal** string on the x402 wire today
+ * (e.g. `"0.0100000000"`), NOT atomic integer units — every deployed client
+ * signs the Decimal verbatim into the ledger and the facilitator compares it
+ * byte-for-byte. These helpers therefore exist so a deploy that OPTS IN to the
+ * atomic-on-wire convention can convert EXACTLY at the boundary; they do NOT
+ * change the default wire unit (see specs/scheme_exact_canton.upstream.md
+ * § Amount units). The maths is pure BigInt/string so the round-trip never
+ * drifts by 10^10 (the off-by-scale footgun) and never goes through float.
+ *
+ * Mirrors `packages/pay-proxy/src/spend-budget-store.ts`'s `toAtomic` (the same
+ * "compare as BigInt atomic, never Number()" guardrail) but adds the inverse and
+ * a strict integer-atomic parser, and lives in core so client + facilitator
+ * share one implementation.
+ */
+/** Daml Decimal scale for Canton Coin / Amulet — 10 fractional digits. */
+export declare const CC_ATOMIC_SCALE = 10;
+/**
+ * Convert a Daml Decimal CC string (e.g. `"0.1"`, `"1.0000000000"`) to integer
+ * atomic units as a decimal string (e.g. `"1000000000"`, `"10000000000"`).
+ *
+ * Fail-CLOSED: throws on a non-numeric value, a negative value, or a fractional
+ * part with MORE than `CC_ATOMIC_SCALE` significant digits (which would lose
+ * precision) — a malformed amount must never silently produce a wrong integer.
+ * Trailing zeros within the scale are fine (`"0.1"` and `"0.1000000000"` both
+ * → `"1000000000"`).
+ */
+export declare function decimalToAtomicCC(dec: string): string;
+/**
+ * Convert integer atomic units (decimal string, e.g. `"1"`, `"10000000000"`) to
+ * a fixed-scale Daml Decimal CC string with exactly `CC_ATOMIC_SCALE` fractional
+ * digits (e.g. `"0.0000000001"`, `"1.0000000000"`).
+ *
+ * Fail-CLOSED: throws on a non-integer / non-numeric / negative input. The
+ * output is the canonical fixed-scale form the Token Standard ledger uses, so
+ * `decimalToAtomicCC(atomicToDecimalCC(x)) === x` and
+ * `atomicToDecimalCC(decimalToAtomicCC(d))` is `d` normalized to 10 dp.
+ */
+export declare function atomicToDecimalCC(atomic: string): string;
+/** True iff this x402 scheme string carries the amount in ATOMIC integer units
+ *  on the wire ("exact" — the x402-ENVELOPE convention). The legacy
+ *  "exact-canton" (and anything else) carries a Daml Decimal. Mirrors
+ *  `schemeMatches`'s "exact" is canonical / "exact-canton" is legacy split. */
+export declare function schemeIsAtomic(scheme: string): boolean;
+/**
+ * Convert an x402 WIRE amount to the on-ledger Daml **Decimal** it denotes,
+ * keyed by the wire's scheme. Atomic scheme ("exact") => `atomicToDecimalCC`;
+ * legacy/Decimal scheme ("exact-canton", anything else) => passthrough (the wire
+ * value already IS the Decimal). Fail-CLOSED via the underlying converter (a
+ * non-integer atomic value, or a malformed Decimal at a later comparison,
+ * throws rather than silently mis-comparing). Use this at EVERY site that
+ * compares a wire amount against an on-ledger Decimal.
+ */
+export declare function wireAmountToLedgerDecimal(scheme: string, wireAmount: string): string;
+/**
+ * Inverse of `wireAmountToLedgerDecimal`: given an on-ledger Daml Decimal,
+ * produce the WIRE amount for the given scheme. Atomic scheme ("exact") =>
+ * `decimalToAtomicCC`; legacy/Decimal scheme => passthrough. Used by the client
+ * builder / signer seam when emitting under the atomic scheme.
+ */
+export declare function ledgerDecimalToWireAmount(scheme: string, decimal: string): string;
+/**
+ * Canonical VALUE-equality of two on-ledger Daml CC Decimal strings: compares
+ * by BigInt atomic units so "0.1" ≡ "0.1000000000" and a 10x/0.1x difference
+ * provably never folds. Fail-CLOSED: a malformed Decimal on either side throws
+ * (via `decimalToAtomicCC`), so a comparison can never silently pass on junk.
+ * This is the exactness guarantee the spec asks for at every amount-compare site
+ * (replaces a raw string `!==`).
+ */
+export declare function ledgerDecimalEquals(a: string, b: string): boolean;
+/**
+ * Non-throwing, FAIL-CLOSED variant of `ledgerDecimalEquals` for the
+ * facilitator amount-validation arms: returns `true` only when both inputs are
+ * well-formed Daml CC Decimals of equal value; a malformed/junk value on either
+ * side returns `false` (→ amount_mismatch) instead of throwing. Use this at the
+ * pure validator sites (validateTransferCommand / validateAllocation /
+ * validateCip56*) that must map to a discriminated reject, never a 5xx.
+ */
+export declare function ledgerDecimalsMatch(a: string, b: string): boolean;
+//# sourceMappingURL=amount.d.ts.map

package/dist/amount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amount.d.ts","sourceRoot":"","sources":["../src/amount.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,eAAe,KAAK,CAAC;AAIlC;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAsBrD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CASxD;AAwBD;;;+EAG+E;AAC/E,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,MAAM,CAER;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,MAAM,CAER;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAMjE"}

package/dist/amount.js

@@ -0,0 +1,155 @@
+/**
+ * Canton Coin amount-unit conversion (x402-ENVELOPE upstream convention).
+ *
+ * The x402 v2 wire field `PaymentRequirements.maxAmountRequired` (this scheme's
+ * `amount`) travels in ATOMIC UNITS as an integer string, while the on-ledger
+ * Daml `Decimal` the Token Standard / TransferCommand uses is a fixed-scale
+ * decimal string. The conversion boundary is fixed across CIP-56 by the Daml
+ * `Decimal` scale: **1 CC = 10^10 atomic units** (10 decimal places).
+ *
+ * BACK-COMPAT (read this): the DEPLOYED v1 (external-party-amulet-rules, live on
+ * MainNet) and cip56 paths put a Daml **Decimal** string on the x402 wire today
+ * (e.g. `"0.0100000000"`), NOT atomic integer units — every deployed client
+ * signs the Decimal verbatim into the ledger and the facilitator compares it
+ * byte-for-byte. These helpers therefore exist so a deploy that OPTS IN to the
+ * atomic-on-wire convention can convert EXACTLY at the boundary; they do NOT
+ * change the default wire unit (see specs/scheme_exact_canton.upstream.md
+ * § Amount units). The maths is pure BigInt/string so the round-trip never
+ * drifts by 10^10 (the off-by-scale footgun) and never goes through float.
+ *
+ * Mirrors `packages/pay-proxy/src/spend-budget-store.ts`'s `toAtomic` (the same
+ * "compare as BigInt atomic, never Number()" guardrail) but adds the inverse and
+ * a strict integer-atomic parser, and lives in core so client + facilitator
+ * share one implementation.
+ */
+/** Daml Decimal scale for Canton Coin / Amulet — 10 fractional digits. */
+export const CC_ATOMIC_SCALE = 10;
+const SCALE_FACTOR = 10n ** BigInt(CC_ATOMIC_SCALE);
+/**
+ * Convert a Daml Decimal CC string (e.g. `"0.1"`, `"1.0000000000"`) to integer
+ * atomic units as a decimal string (e.g. `"1000000000"`, `"10000000000"`).
+ *
+ * Fail-CLOSED: throws on a non-numeric value, a negative value, or a fractional
+ * part with MORE than `CC_ATOMIC_SCALE` significant digits (which would lose
+ * precision) — a malformed amount must never silently produce a wrong integer.
+ * Trailing zeros within the scale are fine (`"0.1"` and `"0.1000000000"` both
+ * → `"1000000000"`).
+ */
+export function decimalToAtomicCC(dec) {
+    if (typeof dec !== "string") {
+        throw new Error(`invalid CC decimal amount: ${JSON.stringify(dec)}`);
+    }
+    const m = /^(\d+)(?:\.(\d+))?$/.exec(dec.trim());
+    if (!m) {
+        throw new Error(`invalid CC decimal amount: ${JSON.stringify(dec)}`);
+    }
+    const whole = m[1] ?? "0";
+    const fracRaw = m[2] ?? "";
+    // Reject any significant digit past the scale (lossy). Trailing zeros that
+    // exceed the scale are NOT significant, so trim them before the length check.
+    const fracTrimmed = fracRaw.replace(/0+$/, "");
+    if (fracTrimmed.length > CC_ATOMIC_SCALE) {
+        throw new Error(`CC decimal amount ${JSON.stringify(dec)} has more than ${CC_ATOMIC_SCALE} ` +
+            `fractional digits — converting to atomic units would lose precision`);
+    }
+    const frac = fracRaw.slice(0, CC_ATOMIC_SCALE).padEnd(CC_ATOMIC_SCALE, "0");
+    const atomic = BigInt(whole) * SCALE_FACTOR + BigInt(frac || "0");
+    return atomic.toString();
+}
+/**
+ * Convert integer atomic units (decimal string, e.g. `"1"`, `"10000000000"`) to
+ * a fixed-scale Daml Decimal CC string with exactly `CC_ATOMIC_SCALE` fractional
+ * digits (e.g. `"0.0000000001"`, `"1.0000000000"`).
+ *
+ * Fail-CLOSED: throws on a non-integer / non-numeric / negative input. The
+ * output is the canonical fixed-scale form the Token Standard ledger uses, so
+ * `decimalToAtomicCC(atomicToDecimalCC(x)) === x` and
+ * `atomicToDecimalCC(decimalToAtomicCC(d))` is `d` normalized to 10 dp.
+ */
+export function atomicToDecimalCC(atomic) {
+    if (typeof atomic !== "string" || !/^\d+$/.test(atomic.trim())) {
+        throw new Error(`invalid CC atomic amount: ${JSON.stringify(atomic)}`);
+    }
+    const v = BigInt(atomic.trim());
+    const whole = v / SCALE_FACTOR;
+    const frac = v % SCALE_FACTOR;
+    const fracStr = frac.toString().padStart(CC_ATOMIC_SCALE, "0");
+    return `${whole.toString()}.${fracStr}`;
+}
+/* ------------------------------------------------------------------------- *
+ * Unit-by-scheme boundary (x402-ENVELOPE atomic-by-scheme, BACK-COMPAT).
+ *
+ * The amount unit on the x402 WIRE is keyed by the x402 scheme string on the
+ * SAME object the amount lives on (PaymentRequirements.scheme /
+ * PaymentPayload.scheme):
+ *
+ *   - scheme "exact-canton" (LEGACY, the live emitted wire today) => the wire
+ *     `amount` is a Daml **Decimal** string (e.g. "0.0100000000"), UNCHANGED
+ *     from deployed behavior. Every deployed v1/cip56/allocation client signs
+ *     this Decimal verbatim into the ledger and the facilitator compares it.
+ *   - scheme "exact" (x402-ENVELOPE, post-deploy emit flip) => the wire
+ *     `amount` is ATOMIC integer units (1 CC = 10^10), and the on-ledger Daml
+ *     Decimal is derived EXACTLY via the BigInt converters above.
+ *
+ * The on-ledger Daml `transferLeg.amount` / `TransferCommand.amount` /
+ * `Holding.amount` is ALWAYS a fixed-scale Decimal. These two functions are the
+ * SINGLE place the scheme->unit decision is made, so every comparison site
+ * (facilitator verify arms, selectServerRequirements, client builder,
+ * verify-before-sign) converts identically — the off-by-10^10 firewall.
+ * ------------------------------------------------------------------------- */
+/** True iff this x402 scheme string carries the amount in ATOMIC integer units
+ *  on the wire ("exact" — the x402-ENVELOPE convention). The legacy
+ *  "exact-canton" (and anything else) carries a Daml Decimal. Mirrors
+ *  `schemeMatches`'s "exact" is canonical / "exact-canton" is legacy split. */
+export function schemeIsAtomic(scheme) {
+    return scheme === "exact";
+}
+/**
+ * Convert an x402 WIRE amount to the on-ledger Daml **Decimal** it denotes,
+ * keyed by the wire's scheme. Atomic scheme ("exact") => `atomicToDecimalCC`;
+ * legacy/Decimal scheme ("exact-canton", anything else) => passthrough (the wire
+ * value already IS the Decimal). Fail-CLOSED via the underlying converter (a
+ * non-integer atomic value, or a malformed Decimal at a later comparison,
+ * throws rather than silently mis-comparing). Use this at EVERY site that
+ * compares a wire amount against an on-ledger Decimal.
+ */
+export function wireAmountToLedgerDecimal(scheme, wireAmount) {
+    return schemeIsAtomic(scheme) ? atomicToDecimalCC(wireAmount) : wireAmount;
+}
+/**
+ * Inverse of `wireAmountToLedgerDecimal`: given an on-ledger Daml Decimal,
+ * produce the WIRE amount for the given scheme. Atomic scheme ("exact") =>
+ * `decimalToAtomicCC`; legacy/Decimal scheme => passthrough. Used by the client
+ * builder / signer seam when emitting under the atomic scheme.
+ */
+export function ledgerDecimalToWireAmount(scheme, decimal) {
+    return schemeIsAtomic(scheme) ? decimalToAtomicCC(decimal) : decimal;
+}
+/**
+ * Canonical VALUE-equality of two on-ledger Daml CC Decimal strings: compares
+ * by BigInt atomic units so "0.1" ≡ "0.1000000000" and a 10x/0.1x difference
+ * provably never folds. Fail-CLOSED: a malformed Decimal on either side throws
+ * (via `decimalToAtomicCC`), so a comparison can never silently pass on junk.
+ * This is the exactness guarantee the spec asks for at every amount-compare site
+ * (replaces a raw string `!==`).
+ */
+export function ledgerDecimalEquals(a, b) {
+    return decimalToAtomicCC(a) === decimalToAtomicCC(b);
+}
+/**
+ * Non-throwing, FAIL-CLOSED variant of `ledgerDecimalEquals` for the
+ * facilitator amount-validation arms: returns `true` only when both inputs are
+ * well-formed Daml CC Decimals of equal value; a malformed/junk value on either
+ * side returns `false` (→ amount_mismatch) instead of throwing. Use this at the
+ * pure validator sites (validateTransferCommand / validateAllocation /
+ * validateCip56*) that must map to a discriminated reject, never a 5xx.
+ */
+export function ledgerDecimalsMatch(a, b) {
+    try {
+        return ledgerDecimalEquals(a, b);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=amount.js.map

package/dist/amount.js.map

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

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./types.js";
 export * from "./caip2.js";
 export * from "./encoding.js";
+export * from "./amount.js";
+export * from "./resource-url.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,4 +1,6 @@
 export * from "./types.js";
 export * from "./caip2.js";
 export * from "./encoding.js";
+export * from "./amount.js";
+export * from "./resource-url.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC"}

package/dist/resource-url.d.ts

@@ -0,0 +1,11 @@
+/** Lowercase-hex unsalted SHA-256 of the exact UTF-8 URL string. */
+export declare function hashResourceUrl(url: string): string;
+/**
+ * True when an on-ledger `x402.resourceUrl` stamp binds to the expected URL —
+ * accepting BOTH the new hashed form `H(url)` and the legacy plaintext `url`
+ * (back-compat with deployed plaintext-stamping clients). Callers only invoke
+ * this when a stamp is PRESENT; an absent stamp is tolerated by the caller
+ * (the documented residual), exactly as before.
+ */
+export declare function resourceUrlMatchesStamp(stamp: string, expectedUrl: string): boolean;
+//# sourceMappingURL=resource-url.d.ts.map

package/dist/resource-url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-url.d.ts","sourceRoot":"","sources":["../src/resource-url.ts"],"names":[],"mappings":"AAsBA,oEAAoE;AACpE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAEnF"}

package/dist/resource-url.js

@@ -0,0 +1,36 @@
+/**
+ * Resource-URL on-ledger privacy stamp (x402-ENVELOPE upstream convention,
+ * PR #2634 review point 7).
+ *
+ * The client binds the payment to the gated resource by stamping the resource
+ * URL into the on-ledger Transfer/allocation `meta["x402.resourceUrl"]`, which
+ * the facilitator's /verify reproduces and compares (the binding guarantee that
+ * stops a transfer for resource A unlocking resource B). Committing the
+ * PLAINTEXT URL on-ledger is a privacy concern — it identifies which API the
+ * agent is paying for, visible to every stakeholder + in Scan. The convention
+ * is therefore to stamp an UNSALTED SHA-256 hash (lowercase hex of the digest of
+ * the exact UTF-8 URL string) instead of the plaintext, preserving the binding
+ * while hiding the URL.
+ *
+ * BACK-COMPAT: the facilitator MUST accept EITHER the stamped plaintext URL OR
+ * its hash (compare the on-ledger value against both `url` and
+ * `hashResourceUrl(url)`), so deployed clients that still stamp plaintext keep
+ * verifying while new clients stamp the hash. Absence stays tolerated (existing
+ * behavior). See `resourceUrlMatchesStamp`.
+ */
+import { createHash } from "node:crypto";
+/** Lowercase-hex unsalted SHA-256 of the exact UTF-8 URL string. */
+export function hashResourceUrl(url) {
+    return createHash("sha256").update(url, "utf8").digest("hex");
+}
+/**
+ * True when an on-ledger `x402.resourceUrl` stamp binds to the expected URL —
+ * accepting BOTH the new hashed form `H(url)` and the legacy plaintext `url`
+ * (back-compat with deployed plaintext-stamping clients). Callers only invoke
+ * this when a stamp is PRESENT; an absent stamp is tolerated by the caller
+ * (the documented residual), exactly as before.
+ */
+export function resourceUrlMatchesStamp(stamp, expectedUrl) {
+    return stamp === expectedUrl || stamp === hashResourceUrl(expectedUrl);
+}
+//# sourceMappingURL=resource-url.js.map

package/dist/resource-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-url.js","sourceRoot":"","sources":["../src/resource-url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,oEAAoE;AACpE,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa,EAAE,WAAmB;IACxE,OAAO,KAAK,KAAK,WAAW,IAAI,KAAK,KAAK,eAAe,CAAC,WAAW,CAAC,CAAC;AACzE,CAAC"}

package/dist/types.d.ts

@@ -8,23 +8,99 @@
  */
 /** CAIP-2-style Canton network identifier. */
 export type CantonNetwork = `canton:devnet` | `canton:mainnet` | `canton:${string}`;
+/** x402 scheme discriminator. The x402-ENVELOPE upstream convention (PR #2634
+ *  review) is that the scheme NAME is `"exact"` and Canton is a NETWORK of the
+ *  exact scheme (CAIP-2 `canton:*`). The codebase historically used
+ *  `"exact-canton"`; BOTH are accepted on input for back-compat (deployed
+ *  facilitator + resource-server middleware string-check `"exact-canton"`).
+ *  New emitters MAY use `"exact"` once the facilitator accept-both is deployed;
+ *  see `schemeMatches` for the equivalence used in requirement matching. */
+export type ExactScheme = "exact" | "exact-canton";
+/** True when two scheme strings refer to the same exact scheme — `"exact"` and
+ *  the legacy `"exact-canton"` are equivalent. Used so a new client emitting
+ *  `"exact"` still matches a merchant `accepts[]` configured with the legacy
+ *  `"exact-canton"` (and vice-versa). */
+export declare function schemeMatches(a: string, b: string): boolean;
+/**
+ * Extra-block reader helpers (x402-ENVELOPE accept-both). Prefer the new
+ * upstream key, fall back to the legacy one. Used everywhere the facilitator /
+ * client reads `extra.feePayer`/`facilitatorParty` or
+ * `extra.assetTransferMethod`/`transferMethod`, so a request carrying EITHER
+ * shape resolves identically.
+ */
+export declare function extraFeePayer(extra: {
+    feePayer?: string;
+    facilitatorParty?: string;
+}): string | undefined;
+export declare function extraMethod(extra: {
+    assetTransferMethod?: string;
+    transferMethod?: string;
+}): string | undefined;
+/**
+ * PaymentPayload payer reader (phdargen / upstream-maintainer naming, accept-both).
+ * The x402 payment payload's payer-party field is `payer` — aligning with the
+ * `payer` field on `SettleResponse` / `VerifyResponse`. The codebase historically
+ * used `payerParty`, and the DEPLOYED v1 MainNet facilitator still reads
+ * `payerParty` off the wire, so BOTH keys are accepted on input: prefer the new
+ * `payer`, fall back to the legacy `payerParty`. Mirrors `extraFeePayer`. New
+ * emitters set BOTH (see `client/src/scheme.ts`); every reader of the wire payer
+ * resolves via this helper so a payload carrying EITHER shape resolves identically.
+ */
+export declare function payloadPayer(p: {
+    payer?: string;
+    payerParty?: string;
+}): string | undefined;
+/** True when two `asset` symbols denote the same instrument. The x402-ENVELOPE
+ *  convention is the symbol `"CC"`; `"canton-coin"` (legacy) is the same thing.
+ *  The structured `"<admin>::Amulet"` form is also treated as Canton Coin. Any
+ *  other value matches only by exact string equality (multi-asset tokens). */
+export declare function assetMatches(a: string, b: string): boolean;
 /** Which on-ledger primitive carries the actual CC movement.
  *  external-party-amulet-rules (v1): the facilitator submits
  *  TransferCommand_Send and pays the Global Synchronizer traffic fee.
  *  cip56-transfer-factory: the payer submits TransferFactory_Transfer and
- *  pays; the facilitator only verifies. A deploy advertises one via
- *  CANTON_X402_PRIMARY_METHOD; both are handled at verify/settle. */
-export type CantonTransferMethod = "external-party-amulet-rules" | "cip56-transfer-factory";
-/** Canton-specific `extra` block in 402 PaymentRequirements. */
+ *  pays; the facilitator only verifies.
+ *  allocation-api (CIP-56 DVP, PRIMARY end-state): the payer LOCKS funds via
+ *  AllocationFactory_Allocate (naming the facilitator as settlement.executor),
+ *  then the facilitator submits Allocation_ExecuteTransfer and pays the GS
+ *  traffic fee — facilitator-sponsored gas AND no nonce AND no per-merchant
+ *  preapproval. A deploy advertises one via CANTON_X402_PRIMARY_METHOD; all
+ *  are handled at verify/settle. The three branches are independent + additive
+ *  (see specs/scheme_exact_canton.upstream.md § Method Coexistence). */
+export type CantonTransferMethod = "external-party-amulet-rules" | "cip56-transfer-factory" | "allocation-api" | "allocation-direct";
+/** Canton-specific `extra` block in 402 PaymentRequirements.
+ *
+ * x402-ENVELOPE upstream convention renames (PR #2634 review):
+ *   - `facilitatorParty` → `feePayer`        (the party that pays GS traffic)
+ *   - `transferMethod`   → `assetTransferMethod` (allocation value
+ *                           "allocation-api")
+ *   - `synchronizerId`   may be SOURCED FROM /supported (AmuletRules.domain_id)
+ *                         instead of stamped in `extra`.
+ *
+ * BACK-COMPAT: the OLD keys (`facilitatorParty`, `transferMethod`,
+ * `synchronizerId`) stay first-class so every deployed v1/cip56 reader compiles
+ * and runs unchanged; the NEW keys (`feePayer`, `assetTransferMethod`) are
+ * ADDED as optional siblings. New emitters set BOTH the canonical old field
+ * (kept for the deployed facilitator that only reads old) AND the new alias.
+ * Read via `extraFeePayer` / `extraMethod` (prefer new, fall back to old). The
+ * discriminator stays the `transferMethod` literal so the union narrows. */
 export type CantonPaymentRequirementsExtra = {
     transferMethod: "external-party-amulet-rules";
     facilitatorParty: string;
+    /** x402-ENVELOPE name for the GS-traffic fee payer (alias of
+     *  facilitatorParty). Optional so deployed 402s without it still type. */
+    feePayer?: string;
+    /** x402-ENVELOPE name for the method discriminator (alias of
+     *  transferMethod). */
+    assetTransferMethod?: "external-party-amulet-rules";
     synchronizerId: string;
     merchantContractCid?: string;
     memo?: string;
 } | {
     transferMethod: "cip56-transfer-factory";
     facilitatorParty: string;
+    feePayer?: string;
+    assetTransferMethod?: "cip56-transfer-factory";
     synchronizerId: string;
     transferFactoryCid: string;
     /** Hash-prefixed templateId of the factory contract, same form
@@ -36,12 +112,100 @@ export type CantonPaymentRequirementsExtra = {
         id: string;
     };
     memo?: string;
+} | {
+    /** CIP-56 DVP Allocation method (PRIMARY end-state). The payer LOCKS
+     *  funds via AllocationFactory_Allocate naming the facilitator as
+     *  settlement.executor; the facilitator then submits
+     *  Allocation_ExecuteTransfer (sponsored gas). See
+     *  specs/scheme_exact_canton.upstream.md. */
+    transferMethod: "allocation-api";
+    /** The facilitator's own party id. Also bound as settlement.executor. */
+    facilitatorParty: string;
+    /** x402-ENVELOPE fee payer (alias of facilitatorParty). */
+    feePayer?: string;
+    /** x402-ENVELOPE method discriminator name (= "allocation-api"). */
+    assetTransferMethod?: "allocation-api";
+    synchronizerId: string;
+    /** The Allocation factory cid the client exercises
+     *  AllocationFactory_Allocate against (resolved from the registry's
+     *  POST /registry/allocation-instruction/v1/allocation-factory). */
+    allocationFactoryCid: string;
+    /** Hash-prefixed templateId of the AllocationFactory (informational;
+     *  the resolved factoryId comes back in the registry response). */
+    allocationFactoryTemplateId: string;
+    instrumentId: {
+        admin: string;
+        id: string;
+    };
+    /** The party that will submit Allocation_ExecuteTransfer. For the
+     *  sponsored flow this EQUALS facilitatorParty and is bound during
+     *  verification (settlement.executor == facilitatorParty). */
+    executor: string;
+    /** Relative deadline (seconds from now) the client uses to compute
+     *  the SettlementInfo.allocateBefore absolute time. */
+    allocateBeforeSeconds: number;
+    /** Relative deadline (seconds from now) for SettlementInfo.settleBefore.
+     *  MUST be strictly after allocateBefore. */
+    settleBeforeSeconds: number;
+    memo?: string;
+} | {
+    /** CIP-56 DVP "2-tx DIRECT" Allocation method (Design B). The payer LOCKS
+     *  funds via AllocationFactory_Allocate naming the MERCHANT (payTo) as
+     *  transferLeg.receiver AND the facilitator as settlement.executor; the
+     *  facilitator then settles in ONE tx via DirectSettlementConsent_Execute,
+     *  which runs Allocation_ExecuteTransfer paying the merchant DIRECTLY. The
+     *  `extra` shape is identical to "allocation-api" (same factory + executor +
+     *  deadlines + instrument); only the discriminator differs, so the client
+     *  builds the SAME AllocationFactory_Allocate exercise (receiver=merchant)
+     *  and the facilitator routes to the direct settle path. See daml/x402-direct.
+     */
+    transferMethod: "allocation-direct";
+    /** The facilitator's own party. Also bound as settlement.executor. */
+    facilitatorParty: string;
+    /** x402-ENVELOPE fee payer (alias of facilitatorParty). */
+    feePayer?: string;
+    /** x402-ENVELOPE method discriminator name (= "allocation-direct"). */
+    assetTransferMethod?: "allocation-direct";
+    synchronizerId: string;
+    /** The Allocation factory cid the client exercises
+     *  AllocationFactory_Allocate against (resolved from the registry's
+     *  POST /registry/allocation-instruction/v1/allocation-factory). */
+    allocationFactoryCid: string;
+    /** Hash-prefixed templateId of the AllocationFactory (informational;
+     *  the resolved factoryId comes back in the registry response). */
+    allocationFactoryTemplateId: string;
+    instrumentId: {
+        admin: string;
+        id: string;
+    };
+    /** The party that will submit DirectSettlementConsent_Execute. For the
+     *  sponsored flow this EQUALS facilitatorParty and is bound during
+     *  verification (settlement.executor == facilitatorParty). */
+    executor: string;
+    /** Relative deadline (seconds from now) the client uses to compute
+     *  the SettlementInfo.allocateBefore absolute time. */
+    allocateBeforeSeconds: number;
+    /** Relative deadline (seconds from now) for SettlementInfo.settleBefore.
+     *  MUST be strictly after allocateBefore. */
+    settleBeforeSeconds: number;
+    memo?: string;
 };
-/** Canton-specific `payload` block in PaymentPayload. */
+/** Canton-specific `payload` block in PaymentPayload.
+ *
+ * PAYER FIELD (phdargen / upstream-maintainer naming, accept-both): the
+ * payer-party field is `payer` — aligning with `SettleResponse`/`VerifyResponse`
+ * `payer`. The legacy `payerParty` stays accepted on input because the DEPLOYED
+ * v1 MainNet facilitator reads `payerParty` off the wire. BOTH are optional here;
+ * a well-formed payload carries AT LEAST ONE (validate-body.ts enforces it), and
+ * new emitters set BOTH (`payer` primary + `payerParty` legacy). Read via
+ * `payloadPayer` (prefer `payer`, fall back to `payerParty`). */
 export type CantonPaymentPayload = {
     transferMethod: "external-party-amulet-rules";
     transferCommandCid: string;
-    payerParty: string;
+    /** Payer party id (phdargen naming, primary). */
+    payer?: string;
+    /** Legacy payer party id (deployed-facilitator compat). Read via payloadPayer. */
+    payerParty?: string;
     nonce: number;
     signatureProof?: string;
     /** updateId of the TransferCommand_Create transaction (relay path only).
@@ -50,7 +214,10 @@ export type CantonPaymentPayload = {
     createUpdateId?: string;
 } | {
     transferMethod: "cip56-transfer-factory";
-    payerParty: string;
+    /** Payer party id (phdargen naming, primary). */
+    payer?: string;
+    /** Legacy payer party id (deployed-facilitator compat). Read via payloadPayer. */
+    payerParty?: string;
     /** Canton ledger updateId of the TransferFactory_Transfer exercise.
      *  Required when the registry returned
      *  TransferInstructionResult_Completed (settlement already on-ledger;
@@ -60,6 +227,62 @@ export type CantonPaymentPayload = {
      *  TransferInstructionResult_Pending; /settle waits for it. */
     transferInstructionCid?: string;
     signatureProof?: string;
+} | {
+    transferMethod: "allocation-api";
+    /** Payer party id (phdargen naming, primary). */
+    payer?: string;
+    /** Legacy payer party id (deployed-facilitator compat). Read via payloadPayer. */
+    payerParty?: string;
+    /** Contract id of the live Allocation (the _Completed case — Amulet
+     *  creates it synchronously). This is the proof the facilitator verifies
+     *  (participant ACS read) and then executes. */
+    allocationCid?: string;
+    /** Contract id of a still-pending AllocationInstruction (the _Pending
+     *  case). Track A is sync-only: the facilitator rejects a pending-only
+     *  payload with invalid_exact_canton_allocation_pending. */
+    allocationInstructionCid?: string;
+    /** Design A — the X402Escrow cid the facilitator exercises
+     *  X402Escrow_Settle on; present for the escrow flow. When set, the
+     *  standard /settle settles via the EscrowService's ATOMIC settleAtomic
+     *  (v0.3.0: ONE X402Escrow_Settle tx that runs Allocation_ExecuteTransfer
+     *  AND forwards facilitator->merchant in the same transaction) instead of
+     *  the direct Allocation_ExecuteTransfer (which fails the 3-party auth).
+     *  Absent → the plain sponsored allocation execute path. */
+    escrowCid?: string;
+    /** Optional Ed25519 proof over the prepared-tx hash of the
+     *  AllocationFactory_Allocate exercise. */
+    signatureProof?: string;
+} | {
+    /** CIP-56 DVP "2-tx DIRECT" (Design B). The payer LOCKED funds via
+     *  AllocationFactory_Allocate with transferLeg.receiver = the MERCHANT
+     *  (payTo) and settlement.executor = the facilitator; the facilitator then
+     *  settles in ONE tx via DirectSettlementConsent_Execute (no escrow, no
+     *  forward, no facilitator custody). See daml/x402-direct. */
+    transferMethod: "allocation-direct";
+    /** Payer party id (phdargen naming, primary). */
+    payer?: string;
+    /** Legacy payer party id (deployed-facilitator compat). Read via payloadPayer. */
+    payerParty?: string;
+    /** Contract id of the live Allocation (the _Completed case — Amulet creates
+     *  it synchronously). receiver == merchant. This is the proof the facilitator
+     *  verifies (participant ACS read) and then executes via the consent. */
+    allocationCid?: string;
+    /** Contract id of a still-pending AllocationInstruction (the _Pending case).
+     *  Track A is sync-only: the facilitator rejects a pending-only payload with
+     *  invalid_exact_canton_allocation_pending. */
+    allocationInstructionCid?: string;
+    /** Optional: the standing DirectSettlementConsent {sender, merchant} cid the
+     *  facilitator exercises DirectSettlementConsent_Execute on. When ABSENT the
+     *  facilitator RESOLVES it from its own ACS (the {sender, merchant} pair) and,
+     *  if none exists, MINTS it from the standing SenderConsent + MerchantConsent
+     *  (facilitator-alone, once-total onboarding). Supplying it is an O(1)
+     *  fast-path; the cid moves no funds on its own — the consent's on-ledger
+     *  choice pins receiver==merchant / sender==consent.sender / executor==
+     *  facilitator and re-validates every term. */
+    directConsentCid?: string;
+    /** Optional Ed25519 proof over the prepared-tx hash of the
+     *  AllocationFactory_Allocate exercise. */
+    signatureProof?: string;
 };
 /** Resource being paid for. Echoed from the server's 402 PAYMENT-REQUIRED
  *  header into every PaymentPayload per x402 v2. */
@@ -73,7 +296,7 @@ export type FacilitatorRequest = {
     x402Version: 2;
     paymentPayload: {
         x402Version: 2;
-        scheme: "exact-canton";
+        scheme: ExactScheme;
         network: CantonNetwork;
         resource: X402ResourceInfo;
         accepted: PaymentRequirements;
@@ -108,10 +331,14 @@ export type SettleResponse = {
 export type SupportedResponse = {
     kinds: Array<{
         x402Version: 1 | 2;
-        scheme: "exact-canton";
+        scheme: ExactScheme;
         network: CantonNetwork;
         extra?: {
             transferMethods: CantonTransferMethod[];
+            /** x402-ENVELOPE: the Global Synchronizer id (AmuletRules.domain_id) the
+             *  facilitator settles on. Advertised here so a 402 `extra` MAY omit
+             *  `synchronizerId` and the client sources it from /supported. */
+            synchronizerId?: string;
         };
     }>;
     extensions: string[];
@@ -119,7 +346,7 @@ export type SupportedResponse = {
 };
 /** PaymentRequirements entry as advertised in an `accepts[]` array. */
 export type PaymentRequirements = {
-    scheme: "exact-canton";
+    scheme: ExactScheme;
     network: CantonNetwork;
     amount: string;
     asset: string;
@@ -128,7 +355,7 @@ export type PaymentRequirements = {
     extra: CantonPaymentRequirementsExtra;
 };
 /** Canton-specific x402 error codes. Prefix `invalid_exact_canton_*`. */
-export type CantonErrorCode = "invalid_exact_canton_transfer_command_not_found" | "invalid_exact_canton_amount_mismatch" | "invalid_exact_canton_asset_mismatch" | "invalid_exact_canton_expired" | "invalid_exact_canton_nonce_reuse" | "invalid_exact_canton_payer_mismatch" | "invalid_exact_canton_merchant_mismatch" | "invalid_exact_canton_signature" | "invalid_exact_canton_resource_url_mismatch" | "invalid_exact_canton_merchant_not_registered" | "invalid_exact_canton_counter_not_ready" | "invalid_exact_canton_transfer_instruction_not_found" | "invalid_exact_canton_transfer_completed_not_visible" | "invalid_exact_canton_transfer_instruction_pending" | "invalid_exact_canton_instrument_id_mismatch" | "invalid_exact_canton_transfer_factory_not_found" | "invalid_exact_canton_missing_proof" | "invalid_exact_canton_holding_locked" | "invalid_exact_canton_payment_already_settled" | "unexpected_canton_ledger_error";
+export type CantonErrorCode = "invalid_exact_canton_transfer_command_not_found" | "invalid_exact_canton_amount_mismatch" | "invalid_exact_canton_asset_mismatch" | "invalid_exact_canton_expired" | "invalid_exact_canton_nonce_reuse" | "invalid_exact_canton_payer_mismatch" | "invalid_exact_canton_merchant_mismatch" | "invalid_exact_canton_signature" | "invalid_exact_canton_merchant_not_registered" | "invalid_exact_canton_counter_not_ready" | "invalid_exact_canton_transfer_instruction_not_found" | "invalid_exact_canton_transfer_completed_not_visible" | "invalid_exact_canton_transfer_instruction_pending" | "invalid_exact_canton_instrument_id_mismatch" | "invalid_exact_canton_transfer_factory_not_found" | "invalid_exact_canton_missing_proof" | "invalid_exact_canton_holding_locked" | "invalid_exact_canton_payment_already_settled" | "invalid_exact_canton_executor_mismatch" | "invalid_exact_canton_allocation_pending" | "invalid_exact_canton_allocation_not_found" | "invalid_exact_canton_allocation_factory_not_found" | "invalid_exact_canton_execute_failed" | "invalid_exact_canton_insufficient_balance" | "invalid_exact_canton_self_payment" | "invalid_exact_canton_direct_disabled" | "unexpected_canton_ledger_error";
 /**
  * Pick the server's OWN PaymentRequirements entry that a client claims to
  * be paying against — defeating client tampering of price / recipient.
@@ -149,9 +376,13 @@ export type CantonErrorCode = "invalid_exact_canton_transfer_command_not_found"
  * the facilitator with the client's numbers.
  *
  * Matching is on the money-critical fields only: scheme, network, amount,
- * asset, payTo, and extra.{transferMethod, facilitatorParty,
- * synchronizerId, instrumentId}. `maxTimeoutSeconds` / `memo` / discovery
- * cids are not part of the price contract.
+ * asset, payTo, and extra.{method, feePayer, synchronizerId, instrumentId}.
+ * `maxTimeoutSeconds` / `memo` / discovery cids are not part of the price
+ * contract. x402-ENVELOPE accept-both (PR #2634): scheme `"exact"` ≡
+ * `"exact-canton"`, asset `"CC"` ≡ `"canton-coin"` ≡ `"<admin>::Amulet"`, the
+ * method/feePayer fields are read via the new (assetTransferMethod/feePayer) or
+ * legacy (transferMethod/facilitatorParty) key, and synchronizerId is only
+ * enforced when BOTH sides carry it (it may be sourced from /supported).
  */
 export declare function selectServerRequirements(accepts: PaymentRequirements[], clientAccepted: unknown): PaymentRequirements | null;
 /**
@@ -160,8 +391,9 @@ export declare function selectServerRequirements(accepts: PaymentRequirements[],
  * configures an `asset` of the structured `<admin>::<id>` form that disagrees
  * with `extra.instrumentId`, the mismatch is silent and the instrumentId wins.
  * Catch it at middleware setup instead. `asset` may also be a symbolic value
- * such as "canton-coin" (see PaymentRequirements.asset) — only the `::` form is
- * cross-checked. Throws on a mismatch; no-op when consistent or not applicable.
+ * such as "CC" / "canton-coin" (see PaymentRequirements.asset) — only the `::`
+ * form is cross-checked. Throws on a mismatch; no-op when consistent or not
+ * applicable.
  */
 export declare function assertAssetInstrumentConsistency(req: PaymentRequirements): void;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -6,6 +6,54 @@
  * `extra` (server side) and `payload` (client side); the envelope is
  * standard x402 v2.
  */
+import { ledgerDecimalEquals, wireAmountToLedgerDecimal } from "./amount.js";
+/** True when two scheme strings refer to the same exact scheme — `"exact"` and
+ *  the legacy `"exact-canton"` are equivalent. Used so a new client emitting
+ *  `"exact"` still matches a merchant `accepts[]` configured with the legacy
+ *  `"exact-canton"` (and vice-versa). */
+export function schemeMatches(a, b) {
+    if (a === b)
+        return true;
+    const norm = (s) => (s === "exact-canton" ? "exact" : s);
+    return norm(a) === norm(b);
+}
+/**
+ * Extra-block reader helpers (x402-ENVELOPE accept-both). Prefer the new
+ * upstream key, fall back to the legacy one. Used everywhere the facilitator /
+ * client reads `extra.feePayer`/`facilitatorParty` or
+ * `extra.assetTransferMethod`/`transferMethod`, so a request carrying EITHER
+ * shape resolves identically.
+ */
+export function extraFeePayer(extra) {
+    return extra.feePayer ?? extra.facilitatorParty;
+}
+export function extraMethod(extra) {
+    return extra.assetTransferMethod ?? extra.transferMethod;
+}
+/**
+ * PaymentPayload payer reader (phdargen / upstream-maintainer naming, accept-both).
+ * The x402 payment payload's payer-party field is `payer` — aligning with the
+ * `payer` field on `SettleResponse` / `VerifyResponse`. The codebase historically
+ * used `payerParty`, and the DEPLOYED v1 MainNet facilitator still reads
+ * `payerParty` off the wire, so BOTH keys are accepted on input: prefer the new
+ * `payer`, fall back to the legacy `payerParty`. Mirrors `extraFeePayer`. New
+ * emitters set BOTH (see `client/src/scheme.ts`); every reader of the wire payer
+ * resolves via this helper so a payload carrying EITHER shape resolves identically.
+ */
+export function payloadPayer(p) {
+    return p.payer ?? p.payerParty;
+}
+/** True when two `asset` symbols denote the same instrument. The x402-ENVELOPE
+ *  convention is the symbol `"CC"`; `"canton-coin"` (legacy) is the same thing.
+ *  The structured `"<admin>::Amulet"` form is also treated as Canton Coin. Any
+ *  other value matches only by exact string equality (multi-asset tokens). */
+export function assetMatches(a, b) {
+    if (a === b)
+        return true;
+    const CC = new Set(["CC", "canton-coin"]);
+    const isCC = (s) => CC.has(s) || /::Amulet$/.test(s);
+    return isCC(a) && isCC(b);
+}
 /**
  * Pick the server's OWN PaymentRequirements entry that a client claims to
  * be paying against — defeating client tampering of price / recipient.
@@ -26,33 +74,84 @@
  * the facilitator with the client's numbers.
  *
  * Matching is on the money-critical fields only: scheme, network, amount,
- * asset, payTo, and extra.{transferMethod, facilitatorParty,
- * synchronizerId, instrumentId}. `maxTimeoutSeconds` / `memo` / discovery
- * cids are not part of the price contract.
+ * asset, payTo, and extra.{method, feePayer, synchronizerId, instrumentId}.
+ * `maxTimeoutSeconds` / `memo` / discovery cids are not part of the price
+ * contract. x402-ENVELOPE accept-both (PR #2634): scheme `"exact"` ≡
+ * `"exact-canton"`, asset `"CC"` ≡ `"canton-coin"` ≡ `"<admin>::Amulet"`, the
+ * method/feePayer fields are read via the new (assetTransferMethod/feePayer) or
+ * legacy (transferMethod/facilitatorParty) key, and synchronizerId is only
+ * enforced when BOTH sides carry it (it may be sourced from /supported).
  */
 export function selectServerRequirements(accepts, clientAccepted) {
     if (typeof clientAccepted !== "object" || clientAccepted === null) {
         return null;
     }
     const c = clientAccepted;
+    // x402-ENVELOPE accept-both: read the extra via the alias helpers so a client
+    // sending EITHER the new (feePayer/assetTransferMethod) or old
+    // (facilitatorParty/transferMethod) shape matches a server `accepts[]`
+    // configured in EITHER shape.
     const cExtra = (c.extra ?? {});
+    const cMethod = extraMethod(cExtra);
+    const cFeePayer = extraFeePayer(cExtra);
     for (const r of accepts) {
         const rExtra = r.extra;
-        if (r.scheme !== c.scheme)
+        // scheme: "exact" ≡ "exact-canton" (a new client vs an old merchant config).
+        if (typeof r.scheme !== "string" ||
+            typeof c.scheme !== "string" ||
+            !schemeMatches(r.scheme, c.scheme))
             continue;
         if (r.network !== c.network)
             continue;
-        if (r.amount !== c.amount)
-            continue;
-        if (r.asset !== c.asset)
+        // amount: unit-by-scheme + canonical-decimal compare. The server-configured
+        // wire amount `r.amount` and the client-claimed wire amount `c.amount` may
+        // legitimately be in DIFFERENT units when scheme `"exact"` (atomic) and the
+        // legacy `"exact-canton"` (Decimal) are accept-both equivalent: a raw
+        // `r.amount !== c.amount` would then wrongly reject an honest cross-scheme
+        // match, OR (worse) let a crafted atomic value string-coincide with a
+        // Decimal. Normalize BOTH sides to the on-ledger Daml Decimal keyed by their
+        // OWN scheme, then compare by BigInt atomic units (folds "0.1" ≡
+        // "0.1000000000", and a 10x/0.1x amount provably cannot match). Fail-closed:
+        // a malformed amount throws in the converter rather than passing. This is the
+        // matching authority and MUST agree byte-exactly with the facilitator's
+        // wireAmountToLedgerDecimal comparisons.
+        {
+            let rDec;
+            let cDec;
+            try {
+                rDec = wireAmountToLedgerDecimal(r.scheme, r.amount);
+                cDec = wireAmountToLedgerDecimal(c.scheme, c.amount);
+            }
+            catch {
+                continue; // malformed amount on either side → no match (fail-closed).
+            }
+            let amountEq;
+            try {
+                amountEq = ledgerDecimalEquals(rDec, cDec);
+            }
+            catch {
+                continue;
+            }
+            if (!amountEq)
+                continue;
+        }
+        // asset: "CC" ≡ "canton-coin" ≡ "<admin>::Amulet" (symbolic equivalence).
+        if (typeof r.asset !== "string" ||
+            typeof c.asset !== "string" ||
+            !assetMatches(r.asset, c.asset))
             continue;
         if (r.payTo !== c.payTo)
             continue;
-        if (rExtra.transferMethod !== cExtra.transferMethod)
+        if (extraMethod(rExtra) !== cMethod)
             continue;
-        if (rExtra.facilitatorParty !== cExtra.facilitatorParty)
+        if (extraFeePayer(rExtra) !== cFeePayer)
             continue;
-        if (rExtra.synchronizerId !== cExtra.synchronizerId)
+        // synchronizerId: x402-ENVELOPE allows omitting it from `extra` (sourced from
+        // /supported). Mirror the instrumentId pattern — only enforce equality when
+        // BOTH sides carry it; if either omits it, do not reject on this field.
+        if (rExtra.synchronizerId !== undefined &&
+            cExtra.synchronizerId !== undefined &&
+            rExtra.synchronizerId !== cExtra.synchronizerId)
             continue;
         // instrumentId (CIP-56): if either side carries it, both must match.
         const rInst = rExtra.instrumentId;
@@ -73,8 +172,9 @@ export function selectServerRequirements(accepts, clientAccepted) {
  * configures an `asset` of the structured `<admin>::<id>` form that disagrees
  * with `extra.instrumentId`, the mismatch is silent and the instrumentId wins.
  * Catch it at middleware setup instead. `asset` may also be a symbolic value
- * such as "canton-coin" (see PaymentRequirements.asset) — only the `::` form is
- * cross-checked. Throws on a mismatch; no-op when consistent or not applicable.
+ * such as "CC" / "canton-coin" (see PaymentRequirements.asset) — only the `::`
+ * form is cross-checked. Throws on a mismatch; no-op when consistent or not
+ * applicable.
  */
 export function assertAssetInstrumentConsistency(req) {
     const inst = req.extra.instrumentId;

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AA4KH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAA8B,EAC9B,cAAuB;IAEvB,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;QAClE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,CAAC,GAAG,cAA8C,CAAC;IACzD,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAK3B,CAAC;IACH,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,CAAC,CAAC,KAKhB,CAAC;QACF,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;YAAE,SAAS;QACpC,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO;YAAE,SAAS;QACtC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;YAAE,SAAS;QACpC,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK;YAAE,SAAS;QAClC,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,KAAK;YAAE,SAAS;QAClC,IAAI,MAAM,CAAC,cAAc,KAAK,MAAM,CAAC,cAAc;YAAE,SAAS;QAC9D,IAAI,MAAM,CAAC,gBAAgB,KAAK,MAAM,CAAC,gBAAgB;YAAE,SAAS;QAClE,IAAI,MAAM,CAAC,cAAc,KAAK,MAAM,CAAC,cAAc;YAAE,SAAS;QAC9D,qEAAqE;QACrE,MAAM,KAAK,GAAG,MAAM,CAAC,YAAY,CAAC;QAClC,MAAM,KAAK,GAAG,MAAM,CAAC,YAAY,CAAC;QAClC,IAAI,KAAK,IAAI,KAAK,EAAE,CAAC;YACnB,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK;gBAAE,SAAS;YAC/B,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,EAAE,KAAK,KAAK,CAAC,EAAE;gBAAE,SAAS;QACrE,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,gCAAgC,CAC9C,GAAwB;IAExB,MAAM,IAAI,GACR,GAAG,CAAC,KACL,CAAC,YAAY,CAAC;IACf,IAAI,CAAC,IAAI;QAAE,OAAO;IAClB,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,sCAAsC;IAC7E,MAAM,QAAQ,GAAG,GAAG,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,EAAE,EAAE,CAAC;IAC7C,IAAI,GAAG,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,+BAA+B,GAAG,CAAC,KAAK,mBAAmB;YACzD,wBAAwB,QAAQ,sCAAsC;YACtE,qEAAqE;YACrE,0DAA0D,CAC7D,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ftptech/x402-canton-core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Shared types and helpers for the Canton x402 stack",
   "license": "Apache-2.0",
   "author": "FTP team",