@ftptech/canton-agent-wallet 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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 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 Support. 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 support.
+
+   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 2026 FTP Team
+
+   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/README.md

@@ -0,0 +1,134 @@
+# @ftptech/canton-agent-wallet
+
+A self-custody Canton wallet + x402 autopay for AI agents. The agent holds its
+own Ed25519 key and pays for x402-gated resources on the Canton Network on its
+own — the hard parts of Canton (a party must be hosted on a validator, and its
+API is authed) are hidden behind a facilitator **relay** the agent talks to over
+plain HTTP. The relay can *prepare* and *submit* on the agent's behalf but never
+*signs*, so it has no custody.
+
+Backs the [`canton-x402-agent`](../../skills/canton-x402-agent/SKILL.md) skill.
+
+## Install
+
+```bash
+npm install @ftptech/canton-agent-wallet
+# or run the CLI without installing:
+npx @ftptech/canton-agent-wallet <command>
+```
+
+Bin: `canton-agent-wallet`.
+
+## CLI
+
+```
+canton-agent-wallet create --relay-url <url>        # generate + onboard a self-custody wallet (idempotent)
+canton-agent-wallet address                         # print the party id (fund this)
+canton-agent-wallet balance                         # print CC balance
+canton-agent-wallet claim                           # accept incoming transfers (e.g. the initial funding)
+canton-agent-wallet pay --relay-url <url> <url>      # fetch a URL, auto-paying any x402 402 challenge
+canton-agent-wallet withdraw --to <party> [--amount <cc>]   # send CC back out (default: full balance)
+canton-agent-wallet export                           # print the private key (backup; guard it)
+```
+
+`create` and `pay` **require** a relay (facilitator) URL — pass `--relay-url
+<url>` or set `CANTON_AGENT_RELAY_URL`. There is no default: a stale built-in
+default would silently send payments to a dead host, so the CLI fails fast when
+none is given. `address`, `balance`, `claim`, `withdraw` and `export` reuse the
+relay stored in the wallet at `create` time. The current FTP facilitator is
+`http://46.225.91.251:4022` (plain HTTP by IP; a TLS domain is not yet live).
+
+On Canton, incoming CC arrives as a **pending transfer** the agent must accept,
+so the first-run flow is:
+`create --relay-url http://46.225.91.251:4022` → tell your human to send CC to
+the printed party id → `claim` → `balance`. Funding once is the only human step,
+exactly like funding an EVM agent.
+
+## Programmatic API
+
+`makePayingFetch()` returns a `fetch` that transparently pays x402 challenges
+from the agent's wallet (lazily creating the wallet on first use):
+
+```ts
+import { makePayingFetch } from "@ftptech/canton-agent-wallet";
+
+const fetch = await makePayingFetch({
+  relayUrl: process.env.CANTON_AGENT_RELAY_URL,
+  network: "canton:testnet",
+});
+
+const res = await fetch("https://paid.api/resource"); // 402 -> pay -> retry, transparently
+```
+
+On a 402 it resolves the transfer factory via the relay, builds the CIP-56
+transfer, signs the prepared-transaction hash locally, has the relay submit it,
+then retries the request with the on-ledger proof.
+
+## Config (env)
+
+- `CANTON_AGENT_RELAY_URL` — facilitator relay base URL. **Required** for the
+  commands that talk to a relay (`create`, `pay`); there is intentionally no
+  built-in default (a stale default would silently send payments to a dead
+  host). Supply it here or via `--relay-url <url>`. The current FTP facilitator
+  is `http://46.225.91.251:4022` (plain HTTP, by IP — a TLS domain such as
+  `facilitator.ftptech.xyz` is planned but not yet live).
+- `CANTON_AGENT_NETWORK` — `canton:testnet` (default) or `canton:mainnet`; also
+  settable via `--network <net>`.
+- `CANTON_AGENT_API_KEY` — only if the relay requires one (sent as the
+  `X-Agent-Key` header).
+- `CANTON_AGENT_HOME` — override the wallet directory (default `~/.canton-agent`;
+  used by tests and power users).
+
+## Your wallet is YOURS (self-custody)
+
+The wallet lives at `~/.canton-agent/wallet.json` (mode `0600`). **This file IS
+your money — back it up.** Losing it loses the funds. The agent reuses the same
+wallet forever and never silently creates a second one. The validator only
+*hosts* your party; it can never spend your CC — only your signature authorizes a
+transfer. `canton-agent-wallet export` prints the private key for backup or
+import.
+
+## How it works
+
+Self-custody external party per **CIP-0103**: you generate and hold the Ed25519
+key; the facilitator relay bridges onboarding and submission to the Canton
+participant using the validator's auth, so you need no Canton account.
+
+- **Onboard:** the relay runs `generate-topology`; the agent signs the returned
+  multi-hash locally; the relay allocates the party.
+- **Pay / withdraw:** the relay prepares the transaction (and proxies the public
+  Scan registry resolves the agent can't reach); the agent **verifies the
+  prepared transaction matches its intent and binds the hash to those exact
+  bytes** before signing; the relay only forwards the signed submission.
+
+Every state-changing operation is authorized by the agent's signature.
+
+### Verify-before-sign and hash binding (fail-closed)
+
+The relay is treated as untrusted. Before signing any transfer that moves funds,
+the agent structurally decodes the relay-prepared transaction and checks the
+sender / receiver / amount / instrument against its own intent (rejecting
+ambiguous encodings that a spec-conformant parser would read differently). It
+then **binds** the hash it signs to those validated bytes — because the Canton
+Ledger API is explicit that "clients MUST recompute the hash from the raw
+transaction if the preparing participant is not trusted". A compromised relay
+that returns honest bytes paired with the hash of a different (tampered)
+transaction is therefore rejected.
+
+Binding requires one of:
+
+- **`recomputeHash`** (programmatic): pass `hashBinding: { recomputeHash }` to
+  `makePayingFetch` / `withdraw` / `transfer`, where `recomputeHash` reproduces
+  Canton's `HASHING_SCHEME_VERSION_V2` for the prepared bytes. This is the real
+  cryptographic binding.
+- **`CANTON_AGENT_TRUST_RELAY_HASH=1`** (operator opt-in): accept the relay's
+  hash WITHOUT recomputation. This re-opens the blind-signing risk and is only
+  acceptable when a human reviews each transfer or the relay is fully trusted.
+
+With neither configured, a value-moving transfer **refuses to sign** (fail-closed)
+rather than blind-sign a relay-chosen hash. Accepting incoming transfers
+(`claim`) needs no binding — no funds leave.
+
+## License
+
+Apache-2.0.

package/dist/canton-hash.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Canton HashPurpose integers (4-byte big-endian domain-separation prefixes),
+ * confirmed against canonical Canton
+ * `community/base/.../crypto/HashPurpose.scala`. These are stable API: ids are
+ * eagerly-initialized and never reused.
+ */
+export declare const HASH_PURPOSE: {
+    /** Per onboarding/topology transaction hash. */
+    readonly TopologyTransactionSignature: 11;
+    /** Derive a public-key fingerprint (party namespace) from raw key bytes. */
+    readonly PublicKeyFingerprint: 12;
+    /** The combined multiHash over all topology transaction hashes. */
+    readonly MultiTopologyTransaction: 55;
+};
+/**
+ * Recompute the prepared-transaction signing hash (Canton
+ * HASHING_SCHEME_VERSION_V2) from the EXACT base64 `preparedTransaction` the
+ * relay returns from `POST /v1/wallet/submit/prepare`, returning it base64.
+ *
+ * This is hash (1): a Merkle hash over the Daml transaction node tree, returned
+ * as the raw 32 bytes (NOT multihash-framed) base64-encoded — exactly what the
+ * relay returns as `hash`. Compare base64-to-base64; sign the RECOMPUTED value.
+ *
+ * Async: `hashPreparedTransaction` uses WebCrypto (`crypto.subtle.digest`).
+ */
+export declare function recomputeHash(preparedTransactionB64: string): Promise<string>;
+/**
+ * Recompute the onboarding topology multiHash (hash (2)) from the array of
+ * base64 `onboardingTransactions` the relay returns from
+ * `POST /v1/wallet/onboard/prepare`, returning it base64 to compare against the
+ * relay's `hashToSign`.
+ *
+ * Algorithm (spec A.3 / B.4), 4-line wrapper over the library primitives:
+ *   h_i      = computeSha256CantonHash(11, raw_i)        // per-tx, 34B framed
+ *   combined = computeMultiHashForTopology([h_0, h_1..])  // sorted-by-hex, framed
+ *   multiHash= computeSha256CantonHash(55, combined)      // combined, 34B framed
+ *
+ * The per-tx hash is over the RAW topology-transaction bytes as delivered (the
+ * hasher never decodes the proto), and `computeMultiHashForTopology` sorts the
+ * per-tx hashes by lowercase-hex ascending before combining — so the ORDER of
+ * `onboardingTransactions` does not matter. Both the per-tx hashes and the final
+ * multiHash are multihash-framed (0x12 0x20 prefix, 34 bytes); we compare the
+ * base64 verbatim and never strip the prefix.
+ */
+export declare function recomputeTopologyMultiHash(onboardingTxB64: string[]): Promise<string>;
+/**
+ * Derive a Canton public-key fingerprint from raw public-key bytes:
+ * `hex( computeSha256CantonHash(12, publicKeyBytes) )` (spec B.5). The result is
+ * the multihash-framed (0x12 0x20 + 32 = 34 bytes) hash rendered as lowercase
+ * hex (68 chars) — the form Canton uses for the `publicKeyFingerprint` / party
+ * namespace.
+ *
+ * NOTE on which key-byte form to pass: Canton's fingerprint preimage is a
+ * specific serialization of the signing public key. Callers that need to match a
+ * relay-returned `publicKeyFingerprint` should try both the SPKI/DER bytes and
+ * the bare 32-byte Ed25519 point and keep the one that matches (see
+ * `onboard.ts`); this function is a pure transform over whatever bytes it is
+ * given, and the surrounding assert is fail-closed so a wrong guess refuses.
+ */
+export declare function fingerprintHex(publicKeyBytes: Uint8Array): Promise<string>;
+//# sourceMappingURL=canton-hash.d.ts.map

package/dist/canton-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canton-hash.d.ts","sourceRoot":"","sources":["../src/canton-hash.ts"],"names":[],"mappings":"AAoCA;;;;;GAKG;AACH,eAAO,MAAM,YAAY;IACvB,gDAAgD;;IAEhD,4EAA4E;;IAE5E,mEAAmE;;CAE3D,CAAC;AAEX;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,sBAAsB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE7E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,0BAA0B,CAC9C,eAAe,EAAE,MAAM,EAAE,GACxB,OAAO,CAAC,MAAM,CAAC,CAejB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,cAAc,CAClC,cAAc,EAAE,UAAU,GACzB,OAAO,CAAC,MAAM,CAAC,CAMjB"}

package/dist/canton-hash.js

@@ -0,0 +1,108 @@
+/**
+ * canton-hash — the OFFICIAL Canton hash recompute, wired so the agent's
+ * Ed25519 signature is cryptographically bound to the bytes it verified.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The agent's self-custody guarantee has two independent legs (see
+ * verify-prepared.ts):
+ *
+ *   1. STRUCTURAL verify ("the bytes match my intent") — decode the relay's
+ *      `PreparedTransaction` / topology bytes and pin receiver/amount/instrument
+ *      (transfer) or own-key/own-namespace (onboarding) to caller intent.
+ *   2. HASH recompute ("I signed the bytes I saw") — recompute the signing hash
+ *      from those exact bytes EXACTLY as the Canton participant does on
+ *      `execute`/`allocate`, compare it to the relay-returned hash, and sign the
+ *      RECOMPUTED value. This defeats a relay that returns structurally-honest
+ *      bytes paired with the hash of a DIFFERENT transaction (then forwards the
+ *      different bytes to the participant).
+ *
+ * Leg 2 was missing — `hash-binding.ts` was fail-closed with no conformant
+ * recompute. This module supplies it by delegating to the official, published,
+ * Apache-2.0 `@canton-network/core-tx-visualizer` (the same code the rest of the
+ * Canton wallet ecosystem signs with), so the bytes-exact V2 algorithm is the
+ * library's problem, not a hand-reimplementation's. The conformance test
+ * (`canton-hash.conformance.test.ts`) gates trusting it against live vectors.
+ *
+ * We deliberately do NOT use the SDK's `sign()` — it signs the relay-returned
+ * hash directly with no recompute/compare, which would reproduce the blind-sign
+ * bug. We use the library only for HASHING and keep our own compare-then-sign.
+ */
+import { hashPreparedTransaction, computeSha256CantonHash, computeMultiHashForTopology, } from "@canton-network/core-tx-visualizer";
+/**
+ * Canton HashPurpose integers (4-byte big-endian domain-separation prefixes),
+ * confirmed against canonical Canton
+ * `community/base/.../crypto/HashPurpose.scala`. These are stable API: ids are
+ * eagerly-initialized and never reused.
+ */
+export const HASH_PURPOSE = {
+    /** Per onboarding/topology transaction hash. */
+    TopologyTransactionSignature: 11,
+    /** Derive a public-key fingerprint (party namespace) from raw key bytes. */
+    PublicKeyFingerprint: 12,
+    /** The combined multiHash over all topology transaction hashes. */
+    MultiTopologyTransaction: 55,
+};
+/**
+ * Recompute the prepared-transaction signing hash (Canton
+ * HASHING_SCHEME_VERSION_V2) from the EXACT base64 `preparedTransaction` the
+ * relay returns from `POST /v1/wallet/submit/prepare`, returning it base64.
+ *
+ * This is hash (1): a Merkle hash over the Daml transaction node tree, returned
+ * as the raw 32 bytes (NOT multihash-framed) base64-encoded — exactly what the
+ * relay returns as `hash`. Compare base64-to-base64; sign the RECOMPUTED value.
+ *
+ * Async: `hashPreparedTransaction` uses WebCrypto (`crypto.subtle.digest`).
+ */
+export function recomputeHash(preparedTransactionB64) {
+    return hashPreparedTransaction(preparedTransactionB64, "base64");
+}
+/**
+ * Recompute the onboarding topology multiHash (hash (2)) from the array of
+ * base64 `onboardingTransactions` the relay returns from
+ * `POST /v1/wallet/onboard/prepare`, returning it base64 to compare against the
+ * relay's `hashToSign`.
+ *
+ * Algorithm (spec A.3 / B.4), 4-line wrapper over the library primitives:
+ *   h_i      = computeSha256CantonHash(11, raw_i)        // per-tx, 34B framed
+ *   combined = computeMultiHashForTopology([h_0, h_1..])  // sorted-by-hex, framed
+ *   multiHash= computeSha256CantonHash(55, combined)      // combined, 34B framed
+ *
+ * The per-tx hash is over the RAW topology-transaction bytes as delivered (the
+ * hasher never decodes the proto), and `computeMultiHashForTopology` sorts the
+ * per-tx hashes by lowercase-hex ascending before combining — so the ORDER of
+ * `onboardingTransactions` does not matter. Both the per-tx hashes and the final
+ * multiHash are multihash-framed (0x12 0x20 prefix, 34 bytes); we compare the
+ * base64 verbatim and never strip the prefix.
+ */
+export async function recomputeTopologyMultiHash(onboardingTxB64) {
+    const raw = await Promise.all(onboardingTxB64.map((b64) => computeSha256CantonHash(HASH_PURPOSE.TopologyTransactionSignature, bytesFromB64(b64))));
+    const combined = await computeMultiHashForTopology(raw);
+    const hash = await computeSha256CantonHash(HASH_PURPOSE.MultiTopologyTransaction, combined);
+    return Buffer.from(hash).toString("base64");
+}
+/**
+ * Derive a Canton public-key fingerprint from raw public-key bytes:
+ * `hex( computeSha256CantonHash(12, publicKeyBytes) )` (spec B.5). The result is
+ * the multihash-framed (0x12 0x20 + 32 = 34 bytes) hash rendered as lowercase
+ * hex (68 chars) — the form Canton uses for the `publicKeyFingerprint` / party
+ * namespace.
+ *
+ * NOTE on which key-byte form to pass: Canton's fingerprint preimage is a
+ * specific serialization of the signing public key. Callers that need to match a
+ * relay-returned `publicKeyFingerprint` should try both the SPKI/DER bytes and
+ * the bare 32-byte Ed25519 point and keep the one that matches (see
+ * `onboard.ts`); this function is a pure transform over whatever bytes it is
+ * given, and the surrounding assert is fail-closed so a wrong guess refuses.
+ */
+export async function fingerprintHex(publicKeyBytes) {
+    const framed = await computeSha256CantonHash(HASH_PURPOSE.PublicKeyFingerprint, publicKeyBytes);
+    return Buffer.from(framed).toString("hex");
+}
+/** Decode a base64 string to bytes; throws on invalid base64-derived empties is
+ *  left to the library's own digest (empty input still hashes). Kept tiny and
+ *  dependency-free so the hash adapters stay pure. */
+function bytesFromB64(b64) {
+    return Buffer.from(b64, "base64");
+}
+//# sourceMappingURL=canton-hash.js.map

package/dist/canton-hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canton-hash.js","sourceRoot":"","sources":["../src/canton-hash.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,2BAA2B,GAC5B,MAAM,oCAAoC,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,gDAAgD;IAChD,4BAA4B,EAAE,EAAE;IAChC,4EAA4E;IAC5E,oBAAoB,EAAE,EAAE;IACxB,mEAAmE;IACnE,wBAAwB,EAAE,EAAE;CACpB,CAAC;AAEX;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,sBAA8B;IAC1D,OAAO,uBAAuB,CAAC,sBAAsB,EAAE,QAAQ,CAAC,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,eAAyB;IAEzB,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,CAC3B,eAAe,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAC1B,uBAAuB,CACrB,YAAY,CAAC,4BAA4B,EACzC,YAAY,CAAC,GAAG,CAAC,CAClB,CACF,CACF,CAAC;IACF,MAAM,QAAQ,GAAG,MAAM,2BAA2B,CAAC,GAAG,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,MAAM,uBAAuB,CACxC,YAAY,CAAC,wBAAwB,EACrC,QAAQ,CACT,CAAC;IACF,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,cAA0B;IAE1B,MAAM,MAAM,GAAG,MAAM,uBAAuB,CAC1C,YAAY,CAAC,oBAAoB,EACjC,cAAc,CACf,CAAC;IACF,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC7C,CAAC;AAED;;sDAEsD;AACtD,SAAS,YAAY,CAAC,GAAW;IAC/B,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AACpC,CAAC"}

package/dist/cli-args.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure (side-effect-free) argument helpers for the canton-agent-wallet CLI.
+ *
+ * Kept in their own module so they can be unit-tested without importing
+ * `cli.ts` (which auto-runs `main()` on import and would call
+ * `process.exit`). `cli.ts` composes these with its env + `fail()`.
+ */
+export declare const DEFAULT_NETWORK = "canton:testnet";
+/** Known `--flag <value>` options; used to strip flags out of positionals. */
+export declare const VALUE_FLAGS: ReadonlySet<string>;
+/** First value following `--<name>` in `args`, or undefined. */
+export declare function flag(args: readonly string[], name: string): string | undefined;
+/**
+ * Positional args with any known `--flag <value>` pairs removed, so a command
+ * can read its positional (e.g. `pay <url>`) regardless of where the flags
+ * were placed on the line. A trailing `--flag` with no value still consumes
+ * the (missing) value slot, matching `flag()`'s lookahead.
+ */
+export declare function positionals(args: readonly string[]): string[];
+/**
+ * Resolve the relay (facilitator) URL: `--relay-url` flag wins, else the
+ * CANTON_AGENT_RELAY_URL env var. There is intentionally NO default — a
+ * stale built-in default silently sends an agent's payments to a dead host,
+ * so the caller must fail fast when this returns undefined.
+ */
+export declare function resolveRelayUrl(args: readonly string[], env?: NodeJS.ProcessEnv): string | undefined;
+/** Network: `--network` flag wins, else CANTON_AGENT_NETWORK, else testnet. */
+export declare function resolveNetwork(args: readonly string[], env?: NodeJS.ProcessEnv): string;
+/** Message shown when no relay URL is supplied (flag or env). */
+export declare const MISSING_RELAY_HELP: string;
+//# sourceMappingURL=cli-args.d.ts.map

package/dist/cli-args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-args.d.ts","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAEhD,8EAA8E;AAC9E,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,MAAM,CAK1C,CAAC;AAEH,gEAAgE;AAChE,wBAAgB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG9E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAW7D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CAEpB;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,CAER;AAED,iEAAiE;AACjE,eAAO,MAAM,kBAAkB,QAGwD,CAAC"}

package/dist/cli-args.js

@@ -0,0 +1,56 @@
+/**
+ * Pure (side-effect-free) argument helpers for the canton-agent-wallet CLI.
+ *
+ * Kept in their own module so they can be unit-tested without importing
+ * `cli.ts` (which auto-runs `main()` on import and would call
+ * `process.exit`). `cli.ts` composes these with its env + `fail()`.
+ */
+export const DEFAULT_NETWORK = "canton:testnet";
+/** Known `--flag <value>` options; used to strip flags out of positionals. */
+export const VALUE_FLAGS = new Set([
+    "--relay-url",
+    "--network",
+    "--to",
+    "--amount",
+]);
+/** First value following `--<name>` in `args`, or undefined. */
+export function flag(args, name) {
+    const i = args.indexOf(name);
+    return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
+}
+/**
+ * Positional args with any known `--flag <value>` pairs removed, so a command
+ * can read its positional (e.g. `pay <url>`) regardless of where the flags
+ * were placed on the line. A trailing `--flag` with no value still consumes
+ * the (missing) value slot, matching `flag()`'s lookahead.
+ */
+export function positionals(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (VALUE_FLAGS.has(a)) {
+            i += 1; // skip this flag's value
+            continue;
+        }
+        out.push(a);
+    }
+    return out;
+}
+/**
+ * Resolve the relay (facilitator) URL: `--relay-url` flag wins, else the
+ * CANTON_AGENT_RELAY_URL env var. There is intentionally NO default — a
+ * stale built-in default silently sends an agent's payments to a dead host,
+ * so the caller must fail fast when this returns undefined.
+ */
+export function resolveRelayUrl(args, env = process.env) {
+    return flag(args, "--relay-url") || env.CANTON_AGENT_RELAY_URL || undefined;
+}
+/** Network: `--network` flag wins, else CANTON_AGENT_NETWORK, else testnet. */
+export function resolveNetwork(args, env = process.env) {
+    return flag(args, "--network") || env.CANTON_AGENT_NETWORK || DEFAULT_NETWORK;
+}
+/** Message shown when no relay URL is supplied (flag or env). */
+export const MISSING_RELAY_HELP = "no relay URL — pass --relay-url <url> or set CANTON_AGENT_RELAY_URL.\n" +
+    "  e.g. canton-agent-wallet create --relay-url http://46.225.91.251:4022\n" +
+    "  (the FTP facilitator is currently plain HTTP by IP; a TLS domain is not yet live)";
+//# sourceMappingURL=cli-args.js.map

package/dist/cli-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-args.js","sourceRoot":"","sources":["../src/cli-args.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG,gBAAgB,CAAC;AAEhD,8EAA8E;AAC9E,MAAM,CAAC,MAAM,WAAW,GAAwB,IAAI,GAAG,CAAC;IACtD,aAAa;IACb,WAAW;IACX,MAAM;IACN,UAAU;CACX,CAAC,CAAC;AAEH,gEAAgE;AAChE,MAAM,UAAU,IAAI,CAAC,IAAuB,EAAE,IAAY;IACxD,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACjE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,IAAuB;IACjD,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAW,CAAC;QAC5B,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACvB,CAAC,IAAI,CAAC,CAAC,CAAC,yBAAyB;YACjC,SAAS;QACX,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACd,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAuB,EACvB,MAAyB,OAAO,CAAC,GAAG;IAEpC,OAAO,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,GAAG,CAAC,sBAAsB,IAAI,SAAS,CAAC;AAC9E,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,cAAc,CAC5B,IAAuB,EACvB,MAAyB,OAAO,CAAC,GAAG;IAEpC,OAAO,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,IAAI,GAAG,CAAC,oBAAoB,IAAI,eAAe,CAAC;AAChF,CAAC;AAED,iEAAiE;AACjE,MAAM,CAAC,MAAM,kBAAkB,GAC7B,wEAAwE;IACxE,2EAA2E;IAC3E,qFAAqF,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}