@integraledger/lcp-binding-canton-x402 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# @integraledger/lcp-binding-canton-x402
+
+## 0.9.0
+
+First release. Welds an ATR hash into a Canton Coin settlement over x402's `exact` scheme for Canton:
+the seller advertises `PaymentRequirements.extra.memo`, the payer echoes it into the transfer metadata
+under `x402.memo`, and the facilitator rejects `invalid_exact_canton_memo_mismatch` on a mismatch
+(scheme safety check 12). A §8.3.1 Native Field binding, conforms to LCP v1.38.
+
+Split out of `@integraledger/lcp-binding-canton` rather than replacing it: x402's exact-Canton scheme
+settles Canton Coin only, so the `LcpAnchor` overlay remains the carrier for every other Canton
+deployment. One chain, two carriers, two rails — `canton` and `canton:x402`.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,14 @@
+Integra Protocol
+Copyright 2026 Integra Ledger
+
+This product includes software developed by Integra Ledger (https://integraledger.com).
+
+"Integra", "Integra Ledger", and the Integra logo are trademarks of Integra Ledger.
+Trademark use is not granted by the Apache License 2.0 (see Section 6).
+
+The Legal Context Protocol is co-stewarded by Integra Ledger and AAA-ICDR. This repository is a
+reference implementation of the standard's open layer; the specification itself is published at
+https://legalcontextprotocol.org/standard and is not part of this distribution.
+
+The vendored submodule under lib/commerce-payments is Coinbase's AuthCaptureEscrow and carries its own
+MIT licence at lib/commerce-payments/LICENSE.md. It is not covered by the Apache License above.

package/README.md

@@ -0,0 +1,119 @@
+# @integraledger/lcp-binding-canton-x402
+
+Welds an ATR hash into a Canton Coin settlement over x402's `exact` scheme.
+
+```bash
+npm install @integraledger/lcp-binding-canton-x402
+```
+
+| | |
+|---|---|
+| **Chain** | Canton — **Canton Coin only**, see below |
+| **Pattern** | `native-field` (LCP §8.3.1) |
+| **Protocol** | `x402` — the carrier is x402's, not Canton's own |
+| **Carrier** | `PaymentRequirements.extra.memo`, echoed into the transfer metadata under `x402.memo` |
+| **Surface** | `createCantonX402Adapter` returning a rail-native adapter over a `CantonX402Reader` port — **not** `binding-core`'s `WeldAdapter`, whose shape is EVM's |
+
+## The carrier
+
+x402's `exact` scheme for Canton defines a seller-set memo:
+
+> `extra.memo` (optional): Seller-defined UTF-8 string, max 256 bytes. When present, the client MUST
+> include it in the transfer's metadata.
+
+and its facilitator safety checks make it binding:
+
+> **Memo.** If `paymentRequirements.extra.memo` is set, the transfer metadata MUST carry the identical
+> value under `x402.memo`. Reject with `invalid_exact_canton_memo_mismatch`.
+
+So the seller names the value, the payer must echo it into the transfer that moves the money, and a third
+party refuses to relay the payment if the two disagree. One transaction settles each payment, so the
+weld, the value and the settlement are the same on-ledger event.
+
+```ts
+import {
+  CANTON_X402_MANIFEST,
+  createCantonX402Adapter,
+  makeCantonX402Reader,
+} from "@integraledger/lcp-binding-canton-x402";
+
+declare const atrHash: string;
+declare const updateId: string;
+
+const adapter = createCantonX402Adapter(CANTON_X402_MANIFEST);
+
+// SELLER, at proposal time — merge into the x402 PaymentRequirements you already emit.
+const extra = adapter.propose(atrHash); // { memo: "0x…" }
+
+// VERIFIER, after settlement — one update carries the weld and the asset it is attached to.
+const reader = makeCantonX402Reader({
+  jsonLedgerUrl: "https://participant.example",
+  bearerJwt: process.env["CANTON_READER_JWT"] ?? "",
+});
+const settled = await adapter.observe({ updateId }, reader);
+// { ok: true, value: { state: "settled", atrHash, receiver, amount, instrumentId } }
+```
+
+## Which Canton binding do I want?
+
+There are two, because Canton has two carriers and a manifest can honestly describe one.
+
+**This one, when you settle through x402.** The scheme covers **Canton Coin only** — `asset: "CC"`,
+instrument fixed to `Amulet`, via `transfer-factory`, relayed by a facilitator. Within that, it wins on
+every axis:
+
+| | `LcpAnchor` overlay | `extra.memo` (this package) |
+|---|---|---|
+| Same transaction as the payment | no — a separate contract create | **yes** |
+| Weld enforced by | nobody | **the facilitator, before relaying** |
+| `assetBinding` | `none` — recovery never saw what settled | **`carried`** — receiver, amount, instrument |
+| Needs a Daml package deployed | yes | **no** |
+
+**[`@integraledger/lcp-binding-canton`](../binding-canton#readme) for everything else** — any instrument,
+any synchronizer, DvP and fund and bond workflows, deployments with no facilitator and no x402 at all.
+There is no native field to ride there, so an overlay contract genuinely is the only carrier, and that
+package now ships the `lcp-anchor` Daml template so it can be deployed.
+
+An earlier release said Canton *"cannot"* be bound with a native field, because "Daml has no native
+arbitrary-bytes carrier on a transaction". That was false, and this package is the correction — but the
+overlay is an overlay by **choice**, not obsolete.
+
+## What it still costs, stated plainly
+
+**Not zero-party recoverable, and the carrier move did not change that.** Canton is a privacy ledger: a
+transfer and its metadata are visible only to the transaction's stakeholders, so a reader needs a JWT
+authenticating one of them. §8.3 asks whether an auditor can reconstruct the atrHash from the settlement
+reference **alone, without trusting either party to produce records** — on Canton they cannot, whichever
+carrier is used. No private key is needed; a party's cooperation is.
+
+**Not forward-indexable.** A participant's update stream is one participant's view, not a chain-global
+index, and the memo is a metadata value rather than an indexed key. `enumerate` scans one party's visible
+transfers and says so.
+
+**Scoped to x402.** The manifest declares `protocol: "x402"` because the field, its 256-byte ceiling and
+its enforcement are all x402's. A Canton Coin payment settled outside x402 does not get this carrier — and
+an absent `protocol` would have been a positive claim of protocol-neutrality this binding cannot make.
+
+## Requirement ids
+
+This package's source and its messages cite short ids — `ATA-3`, `RCS-5`, `CMP-6` and their kin.
+**They are not LCP clause numbers.** LCP is cited by section (`§8.3.1`, `§C.2`); anything shaped `XXX-n`
+comes from Integra's functional specification of what a complete agent transaction requires, the fourteen
+families below. Nothing in this package's behaviour depends on them, and where an id and an LCP section
+disagree the section governs.
+
+| | | | |
+|---|---|---|---|
+| `IDN` identity | `ASP` authority to spend | `ATA` authority to accept terms | `TRM` the terms record |
+| `RCS` recourse | `PAY` payment and settlement | `WLD` the transactional weld | `OFR` offer integrity |
+| `FRC` fraud, risk, and compliance | `OPS` commercial operations | `DSC` discovery and reputation | `ORC` orchestration |
+| `CMP` composition | `PRS` persistence and verification infrastructure | | |
+
+---
+
+**Requires Node >= 24.** Part of the
+[Legal Context Protocol open layer](https://github.com/IntegraLedger/integra-protocol) — see the
+[documentation](https://github.com/IntegraLedger/integra-protocol/blob/main/docs/developer/index.md)
+and the
+[package index](https://github.com/IntegraLedger/integra-protocol/blob/main/docs/developer/reference.md).
+Apache-2.0.

package/dist/adapter.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The Canton adapter — thin I/O over an injected participant-reader port. It is a **Canton-native
+ * surface**, NOT binding-core's `WeldAdapter`: that port is EVM-shaped (`SettlementRef` is a `0x`-hex tx
+ * hash, `ChainReader` speaks `eth_getLogs`), whereas a Canton settlement is a ledger update read via the
+ * Daml JSON Ledger API over HTTP.
+ *
+ * **THE CARRIER.** x402's `exact` scheme for Canton: the seller advertises `PaymentRequirements.extra.memo`,
+ * the payer MUST echo it into the transfer's metadata under `x402.memo`, and the facilitator MUST reject
+ * `invalid_exact_canton_memo_mismatch` if the two disagree. One transaction settles each payment (scheme
+ * §Protocol Flow): the payer signs a `TransferFactory_Transfer` naming the merchant as receiver and does
+ * NOT submit it; the facilitator relays the signed submission and pays the traffic fee; the merchant's
+ * standing `TransferPreapproval` resolves it `direct`.
+ *
+ * So the weld, the value and the settlement are one on-ledger event, and `recover` reads all three off a
+ * single update. The `LcpAnchor` overlay this replaced pointed at a SEPARATE contract — which is exactly
+ * why it could bind no asset: the thing it referenced was not the thing that moved the money.
+ *
+ * `recover` refuses rather than throwing: an update under audit may be any transaction on the party's
+ * stream, and "this is not an LCP settlement" is an answer, not an error. `propose` throws, because a
+ * seller advertising a malformed memo is a wiring defect and the facilitator would reject the payment.
+ */
+import type { BindingManifest, Outcome } from "@integraledger/lcp-binding-core";
+/**
+ * A Canton settlement reference — the ledger update id of the transfer the facilitator relayed.
+ *
+ * One id, because one transaction settles each payment.
+ */
+export interface CantonX402SettlementRef {
+    updateId: string;
+}
+/**
+ * A settled `TransferFactory_Transfer` as one participant sees it.
+ *
+ * The asset fields are carried rather than decoded and discarded, and that is what lets the manifest
+ * declare `assetBinding: "carried"` honestly: the axis asks whether a CONSUMER can reach the asset the
+ * weld is attached to, not merely whether the chain recorded it.
+ */
+export interface CantonX402TransferView {
+    /** The transfer's on-ledger metadata map. The memo rides `x402.memo` (scheme safety check 12). */
+    meta: Readonly<Record<string, string>>;
+    /** Receiving party id — the merchant's `payTo` in the scheme's `PaymentRequirements`. */
+    receiver: string;
+    /** Atomic units as an integer string (1 CC = 1e10 units), exactly as the ledger records it. */
+    amount: string;
+    /** The Canton Coin instrument identifier `{ admin, id }`. */
+    instrumentId: {
+        admin: string;
+        id: string;
+    };
+}
+/** What a settled LCP transfer yields: the weld, and the asset it is welded to. */
+export interface CantonX402Settlement {
+    state: "settled";
+    atrHash: `0x${string}`;
+    receiver: string;
+    amount: string;
+    instrumentId: {
+        admin: string;
+        id: string;
+    };
+}
+/**
+ * Reads the participant's update stream over the Daml JSON Ledger API. Injected so the adapter is pure
+ * and testable; a live implementation wraps a participant URL and a party bearer JWT.
+ */
+export interface CantonX402Reader {
+    /** One settled transfer by ledger update id, or `null` if the participant has no such update. */
+    transferView(updateId: string): Promise<CantonX402TransferView | null>;
+    /** Update ids of transfers visible to `party`, most recent first. A participant view, not an index. */
+    transfersFor(party: string, limit?: number): Promise<string[]>;
+}
+/** The Canton x402 rail's surface. `propose` returns an `extra` fragment for the SELLER to merge into its
+ *  `PaymentRequirements` — this rail's weld is committed by the seller and echoed by the payer, unlike the
+ *  memo rails where the payer chooses the value. Its reach is exactly x402's `exact` Canton scheme, which
+ *  settles Canton Coin only; anything else on Canton needs `@integraledger/lcp-binding-canton`'s overlay. */
+export interface CantonX402Adapter {
+    manifest: BindingManifest;
+    /**
+     * The `extra` fragment the seller merges into its x402 `PaymentRequirements`, committing it to the memo
+     * the payer must echo. Throws on a malformed atrHash.
+     */
+    propose(atrHash: string): {
+        readonly memo: string;
+    };
+    /** Recover the atrHash from a settled transfer, or a `verification-failure` Refusal if none binds. */
+    recover(ref: CantonX402SettlementRef, reader: CantonX402Reader): Promise<Outcome<`0x${string}`>>;
+    /** Report the `settled` transition, with the asset the weld is attached to. */
+    observe(ref: CantonX402SettlementRef, reader: CantonX402Reader): Promise<Outcome<CantonX402Settlement>>;
+    /** Scan one party's visible transfers for `atrHash` — a participant view, never a global index. */
+    enumerate(atrHash: string, party: string, reader: CantonX402Reader, limit?: number): Promise<CantonX402SettlementRef[]>;
+}
+/** Config for a live Daml JSON Ledger API participant reader. */
+export interface CantonX402ReaderConfig {
+    /** JSON Ledger API base URL — e.g. `https://164.92.95.184.nip.io`. */
+    jsonLedgerUrl: string;
+    /** Bearer JWT authenticating the reading party on the participant. */
+    bearerJwt: string;
+}
+/**
+ * A live `CantonX402Reader` over the Daml JSON Ledger API, PURE `fetch` — no Daml SDK.
+ *
+ * Fails LOUD on a non-2xx response or a Daml `errors[]` envelope; an absent update surfaces as `null`,
+ * because a reference the participant cannot see is a value the caller must classify, not a transport
+ * failure. No package id is required — the memo rides the CIP-56 token-standard transfer, so unlike the
+ * overlay this replaced there is no deployment-specific DAR to deploy or configure.
+ */
+export declare function makeCantonX402Reader(cfg: CantonX402ReaderConfig): CantonX402Reader;
+/** Construct the Canton x402 adapter. **The manifest is injected, not baked in** — pass this package's own
+ *  `CANTON_X402_MANIFEST`; a manifest whose `rail` is not `"canton:x402"` throws, because an adapter over
+ *  another rail's manifest would publish that rail's claims as its own. Nothing has to be deployed first:
+ *  the memo rides the token-standard transfer, so there is no DAR here. This is the package's entry point. */
+export declare function createCantonX402Adapter(manifest: BindingManifest): CantonX402Adapter;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AAIhF;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,kGAAkG;IAClG,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvC,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;IACjB,+FAA+F;IAC/F,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,YAAY,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED,mFAAmF;AACnF,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iGAAiG;IACjG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAAC;IACvE,uGAAuG;IACvG,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAChE;AAED;;;6GAG6G;AAC7G,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,eAAe,CAAC;IAC1B;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACpD,sGAAsG;IACtG,OAAO,CACL,GAAG,EAAE,uBAAuB,EAC5B,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC,CAAC,CAAC;IACnC,+EAA+E;IAC/E,OAAO,CACL,GAAG,EAAE,uBAAuB,EAC5B,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC;IAC1C,mGAAmG;IACnG,SAAS,CACP,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,gBAAgB,EACxB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;CACvC;AAED,iEAAiE;AACjE,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,sBAAsB,GAC1B,gBAAgB,CA4ClB;AAED;;;8GAG8G;AAC9G,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,eAAe,GACxB,iBAAiB,CA4FnB"}

package/dist/adapter.js

@@ -0,0 +1,122 @@
+import { atrHashEquals, isAtrHash } from "@integraledger/lcp-kernel";
+import { readTransferMemoAtrHash, x402MemoRequirement } from "./memo.js";
+/**
+ * A live `CantonX402Reader` over the Daml JSON Ledger API, PURE `fetch` — no Daml SDK.
+ *
+ * Fails LOUD on a non-2xx response or a Daml `errors[]` envelope; an absent update surfaces as `null`,
+ * because a reference the participant cannot see is a value the caller must classify, not a transport
+ * failure. No package id is required — the memo rides the CIP-56 token-standard transfer, so unlike the
+ * overlay this replaced there is no deployment-specific DAR to deploy or configure.
+ */
+export function makeCantonX402Reader(cfg) {
+    if (cfg.jsonLedgerUrl.length === 0)
+        throw new Error("makeCantonX402Reader: jsonLedgerUrl is empty");
+    if (cfg.bearerJwt.length === 0)
+        throw new Error("makeCantonX402Reader: bearerJwt is empty");
+    async function ledgerCall(path, body) {
+        const res = await fetch(`${cfg.jsonLedgerUrl}${path}`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${cfg.bearerJwt}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Daml ${path} HTTP ${res.status}: ${text}`);
+        }
+        const envelope = (await res.json());
+        if (envelope.errors !== undefined && envelope.errors.length > 0)
+            throw new Error(`Daml ${path} errors: ${envelope.errors.join("; ")}`);
+        if (envelope.result === undefined)
+            throw new Error(`Daml ${path} returned no result`);
+        return envelope.result;
+    }
+    return {
+        async transferView(updateId) {
+            const result = await ledgerCall("/v1/updates/transfer", { updateId });
+            return result ?? null;
+        },
+        async transfersFor(party, limit) {
+            return ledgerCall("/v1/updates/transfers", {
+                party,
+                ...(limit !== undefined ? { limit } : {}),
+            });
+        },
+    };
+}
+/** Construct the Canton x402 adapter. **The manifest is injected, not baked in** — pass this package's own
+ *  `CANTON_X402_MANIFEST`; a manifest whose `rail` is not `"canton:x402"` throws, because an adapter over
+ *  another rail's manifest would publish that rail's claims as its own. Nothing has to be deployed first:
+ *  the memo rides the token-standard transfer, so there is no DAR here. This is the package's entry point. */
+export function createCantonX402Adapter(manifest) {
+    // Fail-fast: an adapter constructed over another rail's manifest would report that rail's claims as
+    // this one's. The EVM adapters bake their module const in; the injectable factories refuse instead.
+    // Stryker disable next-line all: the guard runs during test-module load (the repository's
+    // test suite constructs the adapter at describe scope), so its mutants are 'static' — outside the vitest
+    // runner's per-test attribution and unkillable by any test that in fact kills them behaviorally
+    // (each rail pins both arms: valid manifest constructs, wrong rail throws by message).
+    if (manifest.rail !== "canton:x402")
+        throw new Error(`createCantonX402Adapter: manifest.rail "${manifest.rail}" is not "canton:x402"`);
+    // Closure helper (not `this`) so the returned methods stay destructure-safe.
+    async function readSettlement(ref, reader) {
+        const view = await reader.transferView(ref.updateId);
+        if (view === null)
+            return {
+                refused: true,
+                haltClass: "verification-failure",
+                code: "canton/no-such-update",
+                detail: `the participant has no transfer at updateId ${ref.updateId}`,
+            };
+        const atrHash = readTransferMemoAtrHash(view.meta);
+        if (atrHash === null)
+            return {
+                refused: true,
+                haltClass: "verification-failure",
+                code: "canton/no-lcp-memo",
+                detail: `the transfer at updateId ${ref.updateId} carries no well-formed atrHash under x402.memo`,
+            };
+        return {
+            ok: true,
+            value: {
+                state: "settled",
+                atrHash,
+                receiver: view.receiver,
+                amount: view.amount,
+                instrumentId: view.instrumentId,
+            },
+        };
+    }
+    return {
+        manifest,
+        propose(atrHash) {
+            return x402MemoRequirement(atrHash);
+        },
+        async recover(ref, reader) {
+            const settlement = await readSettlement(ref, reader);
+            return "refused" in settlement
+                ? settlement
+                : { ok: true, value: settlement.value.atrHash };
+        },
+        observe(ref, reader) {
+            return readSettlement(ref, reader);
+        },
+        async enumerate(atrHash, party, reader, limit) {
+            // Fail-fast, like propose: a malformed atrHash can never match a decoded memo, and the silent []
+            // it would produce is indistinguishable from "this party has no settlements".
+            if (!isAtrHash(atrHash))
+                throw new Error(`enumerate: atrHash must be a 0x-prefixed 32-byte value, got "${atrHash}"`);
+            const updateIds = await reader.transfersFor(party, limit);
+            const out = [];
+            for (const updateId of updateIds) {
+                const view = await reader.transferView(updateId);
+                const found = view === null ? null : readTransferMemoAtrHash(view.meta);
+                if (found !== null && atrHashEquals(found, atrHash))
+                    out.push({ updateId });
+            }
+            return out;
+        },
+    };
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAuFzE;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAA2B;IAE3B,IAAI,GAAG,CAAC,aAAa,CAAC,MAAM,KAAK,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAClE,IAAI,GAAG,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAE9D,KAAK,UAAU,UAAU,CAAI,IAAY,EAAE,IAAa;QACtD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,GAAG,CAAC,aAAa,GAAG,IAAI,EAAE,EAAE;YACrD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,GAAG,CAAC,SAAS,EAAE;aACzC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;SAC3B,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;YAC9C,MAAM,IAAI,KAAK,CAAC,QAAQ,IAAI,SAAS,GAAG,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC,CAAC;QAC9D,CAAC;QACD,MAAM,QAAQ,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAsC,CAAC;QACzE,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;YAC7D,MAAM,IAAI,KAAK,CAAC,QAAQ,IAAI,YAAY,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACxE,IAAI,QAAQ,CAAC,MAAM,KAAK,SAAS;YAC/B,MAAM,IAAI,KAAK,CAAC,QAAQ,IAAI,qBAAqB,CAAC,CAAC;QACrD,OAAO,QAAQ,CAAC,MAAM,CAAC;IACzB,CAAC;IAED,OAAO;QACL,KAAK,CAAC,YAAY,CAChB,QAAgB;YAEhB,MAAM,MAAM,GAAG,MAAM,UAAU,CAC7B,sBAAsB,EACtB,EAAE,QAAQ,EAAE,CACb,CAAC;YACF,OAAO,MAAM,IAAI,IAAI,CAAC;QACxB,CAAC;QACD,KAAK,CAAC,YAAY,CAAC,KAAa,EAAE,KAAc;YAC9C,OAAO,UAAU,CAAW,uBAAuB,EAAE;gBACnD,KAAK;gBACL,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC1C,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;8GAG8G;AAC9G,MAAM,UAAU,uBAAuB,CACrC,QAAyB;IAEzB,oGAAoG;IACpG,oGAAoG;IACpG,0FAA0F;IAC1F,yGAAyG;IACzG,gGAAgG;IAChG,uFAAuF;IACvF,IAAI,QAAQ,CAAC,IAAI,KAAK,aAAa;QACjC,MAAM,IAAI,KAAK,CACb,2CAA2C,QAAQ,CAAC,IAAI,wBAAwB,CACjF,CAAC;IAEJ,6EAA6E;IAC7E,KAAK,UAAU,cAAc,CAC3B,GAA4B,EAC5B,MAAwB;QAExB,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACrD,IAAI,IAAI,KAAK,IAAI;YACf,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,SAAS,EAAE,sBAAsB;gBACjC,IAAI,EAAE,uBAAuB;gBAC7B,MAAM,EAAE,+CAA+C,GAAG,CAAC,QAAQ,EAAE;aACtE,CAAC;QACJ,MAAM,OAAO,GAAG,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnD,IAAI,OAAO,KAAK,IAAI;YAClB,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,SAAS,EAAE,sBAAsB;gBACjC,IAAI,EAAE,oBAAoB;gBAC1B,MAAM,EAAE,4BAA4B,GAAG,CAAC,QAAQ,iDAAiD;aAClG,CAAC;QACJ,OAAO;YACL,EAAE,EAAE,IAAI;YACR,KAAK,EAAE;gBACL,KAAK,EAAE,SAAS;gBAChB,OAAO;gBACP,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,YAAY,EAAE,IAAI,CAAC,YAAY;aAChC;SACF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,QAAQ;QAER,OAAO,CAAC,OAAe;YACrB,OAAO,mBAAmB,CAAC,OAAO,CAAC,CAAC;QACtC,CAAC;QAED,KAAK,CAAC,OAAO,CACX,GAA4B,EAC5B,MAAwB;YAExB,MAAM,UAAU,GAAG,MAAM,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YACrD,OAAO,SAAS,IAAI,UAAU;gBAC5B,CAAC,CAAC,UAAU;gBACZ,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACpD,CAAC;QAED,OAAO,CACL,GAA4B,EAC5B,MAAwB;YAExB,OAAO,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACrC,CAAC;QAED,KAAK,CAAC,SAAS,CACb,OAAe,EACf,KAAa,EACb,MAAwB,EACxB,KAAc;YAEd,iGAAiG;YACjG,8EAA8E;YAC9E,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;gBACrB,MAAM,IAAI,KAAK,CACb,gEAAgE,OAAO,GAAG,CAC3E,CAAC;YACJ,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAC1D,MAAM,GAAG,GAA8B,EAAE,CAAC;YAC1C,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;gBACjC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;gBACjD,MAAM,KAAK,GAAG,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACxE,IAAI,KAAK,KAAK,IAAI,IAAI,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC;oBACjD,GAAG,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;YAC3B,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/constants.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Canton / Daml constants for the LCP transfer-memo binding.
+ *
+ * **Canton has a native arbitrary-bytes carrier, and this binding uses it.** x402's `exact` scheme for
+ * Canton defines `PaymentRequirements.extra.memo` — "Seller-defined UTF-8 string, max 256 bytes. When
+ * present, the client MUST include it in the transfer's metadata" — and its facilitator rule 12 rejects
+ * `invalid_exact_canton_memo_mismatch` when the transfer metadata does not carry the identical value under
+ * `x402.memo`. Seller-committed, payer-echoed, facilitator-verified, and riding the same transaction as
+ * the value.
+ *
+ * Daml is often said to have no native arbitrary-bytes carrier — no memo, no metadata label, no nonce. That
+ * is true of the LEDGER's own primitives and false of a payment settled through x402, which is why this
+ * rail exists beside `@integraledger/lcp-binding-canton`'s overlay contract rather than instead of it.
+ */
+/**
+ * The transfer-metadata key the facilitator compares against `extra.memo`. The host's, read exactly: a
+ * metadata map carrying our value under a different key is a transfer no facilitator checked.
+ */
+export declare const CANTON_X402_MEMO_KEY = "x402.memo";
+/** The scheme's stated ceiling for `extra.memo`. A canonical atrHash is 66 UTF-8 bytes. */
+export declare const CANTON_X402_MEMO_MAX_BYTES = 256;
+/** The three Canton environments this binding ships constants for. */
+export type CantonX402Network = "sandbox" | "devnet" | "mainnet";
+/** Per-network constants. Same shape as the overlay rail's and for the same reason: a Canton participant
+ *  node is a deployment's own, so there is no endpoint to pin here. */
+export interface CantonX402NetworkConfig {
+    network: CantonX402Network;
+    /** Explorer base for a contract link (Daml Sandbox has no public explorer — Navigator stand-in). */
+    explorerBase: string;
+    /** CAIP-2-style identifier — Canton has no canonical namespace yet (informal, like Cardano's). */
+    caip2: string;
+}
+/** The constants for one environment. Which Canton rail you want is the real choice: this one only reaches
+ *  payments settled through x402's Canton-Coin scheme, and `@integraledger/lcp-binding-canton`'s overlay
+ *  covers everything else. */
+export declare function getCantonX402Config(network: CantonX402Network): CantonX402NetworkConfig;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;GAGG;AACH,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAEhD,2FAA2F;AAC3F,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C,sEAAsE;AACtE,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEjE;uEACuE;AACvE,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,oGAAoG;IACpG,YAAY,EAAE,MAAM,CAAC;IACrB,kGAAkG;IAClG,KAAK,EAAE,MAAM,CAAC;CACf;AAoBD;;8BAE8B;AAC9B,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,iBAAiB,GACzB,uBAAuB,CAIzB"}