@ftptech/canton-agent-wallet 0.1.0

package/dist/relay-client.d.ts

@@ -0,0 +1,128 @@
+/**
+ * HTTP client for the facilitator's agent-wallet relay. The agent talks ONLY to
+ * this — plain HTTP, no Canton auth. The relay bridges to the participant using
+ * the validator token (onboarding + interactive submission) and proxies the
+ * public Scan registry resolves (the agent has no Scan access).
+ */
+export interface RelayPublicKey {
+    format: string;
+    keyData: string;
+    keySpec: string;
+}
+export interface RelaySignature {
+    format: string;
+    signature: string;
+    signingAlgorithmSpec: string;
+    signedBy: string;
+}
+export interface OnboardPrepareResult {
+    party: string;
+    publicKeyFingerprint: string;
+    onboardingTransactions: string[];
+    hashToSign: string;
+}
+export interface BalanceResult {
+    party: string;
+    amulet: number;
+    cc: string;
+    holdings: Array<{
+        cid: string;
+        amount: string;
+    }>;
+}
+export interface ResolveFactoryResult {
+    factoryId: string;
+    transferKind: string;
+    transferFactoryTemplateId: string;
+    instrumentId: {
+        admin: string;
+        id: string;
+    };
+    choiceContextData: unknown;
+    disclosedContracts: unknown[];
+}
+export interface ResolveAcceptResult {
+    choiceContextData: unknown;
+    disclosedContracts: unknown[];
+}
+export interface PendingResult {
+    party: string;
+    pending: Array<{
+        cid: string;
+        amount?: string;
+        sender?: string;
+    }>;
+}
+/** v1 (external-party-amulet-rules): everything the agent needs to BUILD an
+ *  `ExternalPartyAmuletRules_CreateTransferCommand` exercise. The agent pins
+ *  sender/receiver/amount/delegate to its OWN intent in verify-before-sign —
+ *  these refs widen nothing it will sign. */
+export interface ResolveTransferCommandResult {
+    externalPartyAmuletRules: {
+        contractId: string;
+        /** EPAR's OWN resolved templateId (matches createdEventBlob's package). */
+        templateId: string;
+        createdEventBlob: string;
+    };
+    /** Resolved templateId for the CreateTransferCommand EXERCISE target. */
+    exerciseTemplateId: string;
+    /** The facilitator/delegate party (relay-supplied; the agent ALSO pins this
+     *  to the 402's extra.facilitatorParty before signing). */
+    delegate: string;
+    /** Authoritative DSO party for the command's expectedDso field. */
+    expectedDso: string;
+    synchronizerId: string;
+    /** The agent's next-expected nonce (Daml Int as a string). */
+    nextNonce: string;
+}
+export interface TransferCommandCidResult {
+    party: string;
+    nonce: string;
+    transferCommandCid: string;
+}
+export declare class RelayClient {
+    private readonly opts;
+    constructor(opts: {
+        relayUrl: string;
+        apiKey?: string | undefined;
+    });
+    private headers;
+    private req;
+    onboardPrepare(b: {
+        publicKey: RelayPublicKey;
+        partyHint: string;
+    }): Promise<OnboardPrepareResult>;
+    onboardFinalize(b: {
+        onboardingTransactions: string[];
+        multiHashSignatures: RelaySignature[];
+    }): Promise<{
+        party: string;
+    }>;
+    submitPrepare(b: unknown): Promise<{
+        preparedTransaction: string;
+        hash: string;
+    }>;
+    submitExecute(b: unknown): Promise<{
+        updateId: string;
+    }>;
+    balance(party: string): Promise<BalanceResult>;
+    pending(party: string): Promise<PendingResult>;
+    resolveTransferFactory(b: {
+        sender: string;
+        receiver: string;
+        amount: string;
+        meta?: Record<string, string>;
+    }): Promise<ResolveFactoryResult>;
+    resolveAccept(b: {
+        instructionCid: string;
+    }): Promise<ResolveAcceptResult>;
+    /** v1: resolve the refs needed to build a CreateTransferCommand exercise. */
+    resolveTransferCommand(b: {
+        payerParty: string;
+    }): Promise<ResolveTransferCommandResult>;
+    /** v1: ACS-poll the relay for the cid of the just-created TransferCommand,
+     *  matched by (sender, nonce). The relay bounds the poll and returns 404 if it
+     *  never appears (surfaced here as a thrown relay error). */
+    transferCommandCid(party: string, nonce: string): Promise<TransferCommandCidResult>;
+}
+//# sourceMappingURL=relay-client.d.ts.map

package/dist/relay-client.d.ts.map

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

package/dist/relay-client.js

@@ -0,0 +1,67 @@
+export class RelayClient {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    headers() {
+        const h = { "content-type": "application/json" };
+        if (this.opts.apiKey)
+            h["x-agent-key"] = this.opts.apiKey;
+        return h;
+    }
+    async req(method, path, body) {
+        const url = this.opts.relayUrl.replace(/\/$/, "") + path;
+        const r = await fetch(url, {
+            method,
+            headers: this.headers(),
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        const text = await r.text();
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            /* leave undefined */
+        }
+        if (!r.ok) {
+            throw new Error(`relay ${method} ${path} -> ${r.status} ${text.slice(0, 200)}`);
+        }
+        return json;
+    }
+    onboardPrepare(b) {
+        return this.req("POST", "/v1/wallet/onboard/prepare", b);
+    }
+    onboardFinalize(b) {
+        return this.req("POST", "/v1/wallet/onboard/finalize", b);
+    }
+    submitPrepare(b) {
+        return this.req("POST", "/v1/wallet/submit/prepare", b);
+    }
+    submitExecute(b) {
+        return this.req("POST", "/v1/wallet/submit/execute", b);
+    }
+    balance(party) {
+        return this.req("GET", `/v1/wallet/${encodeURIComponent(party)}/balance`);
+    }
+    pending(party) {
+        return this.req("GET", `/v1/wallet/${encodeURIComponent(party)}/pending`);
+    }
+    resolveTransferFactory(b) {
+        return this.req("POST", "/v1/wallet/resolve/transfer-factory", b);
+    }
+    resolveAccept(b) {
+        return this.req("POST", "/v1/wallet/resolve/accept", b);
+    }
+    /** v1: resolve the refs needed to build a CreateTransferCommand exercise. */
+    resolveTransferCommand(b) {
+        return this.req("POST", "/v1/wallet/resolve/transfer-command", b);
+    }
+    /** v1: ACS-poll the relay for the cid of the just-created TransferCommand,
+     *  matched by (sender, nonce). The relay bounds the poll and returns 404 if it
+     *  never appears (surfaced here as a thrown relay error). */
+    transferCommandCid(party, nonce) {
+        return this.req("GET", `/v1/wallet/${encodeURIComponent(party)}/transfer-command?nonce=${encodeURIComponent(nonce)}`);
+    }
+}
+//# sourceMappingURL=relay-client.js.map

package/dist/relay-client.js.map

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

package/dist/relay-signer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * makeRelaySigner — a CantonSigner backed by the facilitator relay + the agent's
+ * self-custody key. It implements BOTH x402 transfer methods so the x402 client
+ * (`ExactCantonScheme`) can pick the right arm from the 402's advertised method:
+ *
+ *   - `signCip56Transfer` (cip56-transfer-factory): resolve the factory (+ its
+ *     disclosed contracts / choice context) via the relay, build
+ *     TransferFactory_Transfer, verify-before-sign, sign locally, execute.
+ *   - `signTransferCommand` (external-party-amulet-rules, v1 / mainnet-primary):
+ *     resolve the EPAR refs via the relay, build
+ *     ExternalPartyAmuletRules_CreateTransferCommand, verify-before-sign, sign
+ *     locally, execute, then read back the created TransferCommand cid.
+ *
+ * Method SELECTION is the x402 client's job: it calls `signTransferCommand` iff
+ * the 402's `extra.transferMethod === "external-party-amulet-rules"` and
+ * `signCip56Transfer` iff `=== "cip56-transfer-factory"` (see scheme.ts). In
+ * BOTH cases the relay only prepares + forwards; it never holds the key, so it
+ * can never move the agent's funds, and verify-before-sign + hash-binding keep
+ * the self-custody guarantee on each path.
+ */
+import type { CantonSigner } from "@ftptech/x402-canton-client";
+import type { AgentWallet } from "./store.js";
+import type { HashBindingOptions } from "./verify-prepared.js";
+export declare function makeRelaySigner(wallet: AgentWallet, opts?: {
+    apiKey?: string | undefined;
+    hashBinding?: HashBindingOptions;
+    /** Independently-trusted Amulet DSO (instrument admin / expectedDso) to pin
+     *  on both arms. Defaults to CANTON_AGENT_DSO_PARTY (see trusted-dso.ts).
+     *  Without it, a relay-prepared tx that carries the DSO outside the root
+     *  choice arg fails closed (the round-3 no-pin-fallback removal). */
+    trustedDso?: string;
+}): CantonSigner;
+//# sourceMappingURL=relay-signer.d.ts.map

package/dist/relay-signer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-signer.d.ts","sourceRoot":"","sources":["../src/relay-signer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAKhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE;IACJ,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC;;;yEAGqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;CAChB,GACL,YAAY,CAsCd"}

package/dist/relay-signer.js

@@ -0,0 +1,44 @@
+import { RelayClient } from "./relay-client.js";
+import { transfer, createTransferCommand } from "./tx.js";
+import { resolveHashBinding } from "./hash-binding.js";
+import { resolveTrustedDsoParty } from "./trusted-dso.js";
+export function makeRelaySigner(wallet, opts = {}) {
+    const relay = new RelayClient({ relayUrl: wallet.relayUrl, apiKey: opts.apiKey });
+    // Default to the env-resolved binding: the REAL conformant V2 hash recompute
+    // (canton-hash.ts) unless the operator explicitly sets the
+    // CANTON_AGENT_TRUST_RELAY_HASH escape hatch. A programmatic caller may pass a
+    // different `recomputeHash` instead.
+    const hashBinding = opts.hashBinding ?? resolveHashBinding();
+    // The network-constant Amulet DSO, resolved OUT-OF-BAND (never from the relay):
+    // pins the instrument admin / expectedDso so the foreign-party backstop can
+    // safely exclude the honest DSO that legitimately appears in the transfer's
+    // consequence. Without it, value-moving prepared bytes carrying the DSO outside
+    // the root choice arg are refused (fail-closed).
+    const trustedDso = opts.trustedDso ?? resolveTrustedDsoParty();
+    return {
+        party: wallet.party,
+        async signCip56Transfer(input) {
+            const updateId = await transfer(relay, wallet, {
+                receiver: input.receiver,
+                amount: input.amount,
+                ...(input.transferMeta ? { meta: input.transferMeta } : {}),
+                hashBinding,
+                ...(trustedDso !== undefined ? { expectInstrumentAdmin: trustedDso } : {}),
+            });
+            return { payerParty: wallet.party, updateId, transferInstructionCid: null };
+        },
+        async signTransferCommand(input) {
+            return createTransferCommand(relay, wallet, {
+                receiver: input.receiver,
+                amount: input.amount,
+                delegate: input.delegate,
+                synchronizerId: input.synchronizerId,
+                description: input.description,
+                ...(input.expiresAtMs !== undefined ? { expiresAtMs: input.expiresAtMs } : {}),
+                hashBinding,
+                ...(trustedDso !== undefined ? { expectedDso: trustedDso } : {}),
+            });
+        },
+    };
+}
+//# sourceMappingURL=relay-signer.js.map

package/dist/relay-signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-signer.js","sourceRoot":"","sources":["../src/relay-signer.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAI1D,MAAM,UAAU,eAAe,CAC7B,MAAmB,EACnB,OAQI,EAAE;IAEN,MAAM,KAAK,GAAG,IAAI,WAAW,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAClF,6EAA6E;IAC7E,2DAA2D;IAC3D,+EAA+E;IAC/E,qCAAqC;IACrC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,kBAAkB,EAAE,CAAC;IAC7D,gFAAgF;IAChF,4EAA4E;IAC5E,4EAA4E;IAC5E,gFAAgF;IAChF,iDAAiD;IACjD,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,sBAAsB,EAAE,CAAC;IAC/D,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,KAAK,CAAC,iBAAiB,CAAC,KAAK;YAC3B,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE;gBAC7C,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3D,WAAW;gBACX,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC3E,CAAC,CAAC;YACH,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,sBAAsB,EAAE,IAAI,EAAE,CAAC;QAC9E,CAAC;QACD,KAAK,CAAC,mBAAmB,CAAC,KAAK;YAC7B,OAAO,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE;gBAC1C,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,cAAc,EAAE,KAAK,CAAC,cAAc;gBACpC,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,GAAG,CAAC,KAAK,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC9E,WAAW;gBACX,GAAG,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACjE,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/store.d.ts

@@ -0,0 +1,15 @@
+export interface AgentWallet {
+    network: string;
+    relayUrl: string;
+    party: string;
+    publicKeySpkiB64: string;
+    privateKeyPkcs8Pem: string;
+    /** Participant-supplied multihash fingerprint (signedBy for signatures). */
+    publicKeyFingerprint: string;
+    createdAt: string;
+}
+export declare function walletPath(): string;
+export declare function walletExists(): boolean;
+export declare function loadWallet(): AgentWallet | null;
+export declare function saveWallet(w: AgentWallet): void;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,oBAAoB,EAAE,MAAM,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED,wBAAgB,UAAU,IAAI,WAAW,GAAG,IAAI,CAI/C;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,WAAW,GAAG,IAAI,CAM/C"}

package/dist/store.js

@@ -0,0 +1,33 @@
+/**
+ * Persistent, self-custody wallet store at ~/.canton-agent/wallet.json (0600).
+ *
+ * This file IS the wallet — the agent reuses the same one forever and never
+ * silently creates a second. It must be backed up; losing it loses the funds.
+ * Override the directory with CANTON_AGENT_HOME (used by tests + power users).
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, } from "node:fs";
+function dir() {
+    return process.env.CANTON_AGENT_HOME || join(homedir(), ".canton-agent");
+}
+export function walletPath() {
+    return join(dir(), "wallet.json");
+}
+export function walletExists() {
+    return existsSync(walletPath());
+}
+export function loadWallet() {
+    const p = walletPath();
+    if (!existsSync(p))
+        return null;
+    return JSON.parse(readFileSync(p, "utf8"));
+}
+export function saveWallet(w) {
+    const d = dir();
+    mkdirSync(d, { recursive: true, mode: 0o700 });
+    const p = walletPath();
+    writeFileSync(p, JSON.stringify(w, null, 2) + "\n", { mode: 0o600 });
+    chmodSync(p, 0o600); // enforce even if the file pre-existed with looser perms
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EACL,UAAU,EACV,SAAS,EACT,YAAY,EACZ,aAAa,EACb,SAAS,GACV,MAAM,SAAS,CAAC;AAajB,SAAS,GAAG;IACV,OAAO,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,eAAe,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,OAAO,IAAI,CAAC,GAAG,EAAE,EAAE,aAAa,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,OAAO,UAAU,CAAC,UAAU,EAAE,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,MAAM,CAAC,GAAG,UAAU,EAAE,CAAC;IACvB,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC,CAAgB,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,CAAc;IACvC,MAAM,CAAC,GAAG,GAAG,EAAE,CAAC;IAChB,SAAS,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/C,MAAM,CAAC,GAAG,UAAU,EAAE,CAAC;IACvB,aAAa,CAAC,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACrE,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,yDAAyD;AAChF,CAAC"}

package/dist/trusted-dso.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Resolve the agent's INDEPENDENTLY-TRUSTED Amulet DSO party (the instrument
+ * admin) from the environment, for the CLI / autopay / withdraw paths.
+ *
+ * WHY THIS EXISTS (self-custody, post round-3 fix). verify-before-sign pins the
+ * money-critical fields to caller intent and runs an all-nodes foreign-party
+ * backstop. The one party it reads-but-does-not-pin is the relay-supplied
+ * instrument admin / expectedDso (the DSO). The honest transfer choice's
+ * consequence (the created TransferCommand) legitimately carries that DSO as a
+ * payload party + signatory, OUTSIDE the root choice argument. To keep the
+ * backstop sound, an admin/dso value is excluded outside its root position ONLY
+ * when the caller pins it to an INDEPENDENTLY-TRUSTED value; otherwise a malicious
+ * relay could alias the unpinned admin/dso to an attacker and inject that same
+ * value as a consequence / node-metadata / input-contract party (the
+ * neutralization the round-3 fix closes by REMOVING the no-pin value-global
+ * fallback). Consequently a value-moving transfer whose prepared bytes carry the
+ * DSO outside the root now FAILS CLOSED unless this trusted pin is supplied.
+ *
+ * The Amulet DSO party is a NETWORK-WIDE CONSTANT (the same for every wallet on a
+ * given Canton network), so the operator can configure it out-of-band ONCE — it
+ * is NOT learned from the relay (anchoring on the relay's own resolve response
+ * would be circular and provide no security). Set CANTON_AGENT_DSO_PARTY to the
+ * network's Amulet DSO party id. When unset, value-moving transfers that carry
+ * the DSO outside the root refuse to sign (fail-closed, the secure default).
+ */
+/** The env var an operator sets to the network's Amulet DSO (instrument admin). */
+export declare const TRUSTED_DSO_PARTY_ENV = "CANTON_AGENT_DSO_PARTY";
+/**
+ * The independently-trusted DSO/instrument-admin party id, or undefined when the
+ * operator has not configured one. Trimmed; empty ⇒ undefined.
+ */
+export declare function resolveTrustedDsoParty(env?: NodeJS.ProcessEnv): string | undefined;
+//# sourceMappingURL=trusted-dso.d.ts.map

package/dist/trusted-dso.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trusted-dso.d.ts","sourceRoot":"","sources":["../src/trusted-dso.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,mFAAmF;AACnF,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAE9D;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CAGpB"}

package/dist/trusted-dso.js

@@ -0,0 +1,36 @@
+/**
+ * Resolve the agent's INDEPENDENTLY-TRUSTED Amulet DSO party (the instrument
+ * admin) from the environment, for the CLI / autopay / withdraw paths.
+ *
+ * WHY THIS EXISTS (self-custody, post round-3 fix). verify-before-sign pins the
+ * money-critical fields to caller intent and runs an all-nodes foreign-party
+ * backstop. The one party it reads-but-does-not-pin is the relay-supplied
+ * instrument admin / expectedDso (the DSO). The honest transfer choice's
+ * consequence (the created TransferCommand) legitimately carries that DSO as a
+ * payload party + signatory, OUTSIDE the root choice argument. To keep the
+ * backstop sound, an admin/dso value is excluded outside its root position ONLY
+ * when the caller pins it to an INDEPENDENTLY-TRUSTED value; otherwise a malicious
+ * relay could alias the unpinned admin/dso to an attacker and inject that same
+ * value as a consequence / node-metadata / input-contract party (the
+ * neutralization the round-3 fix closes by REMOVING the no-pin value-global
+ * fallback). Consequently a value-moving transfer whose prepared bytes carry the
+ * DSO outside the root now FAILS CLOSED unless this trusted pin is supplied.
+ *
+ * The Amulet DSO party is a NETWORK-WIDE CONSTANT (the same for every wallet on a
+ * given Canton network), so the operator can configure it out-of-band ONCE — it
+ * is NOT learned from the relay (anchoring on the relay's own resolve response
+ * would be circular and provide no security). Set CANTON_AGENT_DSO_PARTY to the
+ * network's Amulet DSO party id. When unset, value-moving transfers that carry
+ * the DSO outside the root refuse to sign (fail-closed, the secure default).
+ */
+/** The env var an operator sets to the network's Amulet DSO (instrument admin). */
+export const TRUSTED_DSO_PARTY_ENV = "CANTON_AGENT_DSO_PARTY";
+/**
+ * The independently-trusted DSO/instrument-admin party id, or undefined when the
+ * operator has not configured one. Trimmed; empty ⇒ undefined.
+ */
+export function resolveTrustedDsoParty(env = process.env) {
+    const v = (env[TRUSTED_DSO_PARTY_ENV] ?? "").trim();
+    return v.length > 0 ? v : undefined;
+}
+//# sourceMappingURL=trusted-dso.js.map

package/dist/trusted-dso.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trusted-dso.js","sourceRoot":"","sources":["../src/trusted-dso.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,mFAAmF;AACnF,MAAM,CAAC,MAAM,qBAAqB,GAAG,wBAAwB,CAAC;AAE9D;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,qBAAqB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACpD,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACtC,CAAC"}

package/dist/tx.d.ts

@@ -0,0 +1,102 @@
+import type { RelayClient } from "./relay-client.js";
+import type { AgentWallet } from "./store.js";
+import { type HashBindingOptions } from "./verify-prepared.js";
+/**
+ * Send CC from the agent to `receiver`. Returns the ledger updateId.
+ *
+ * `opts.expectInstrumentId` overrides the asset the verifier pins the prepared
+ * transfer to (defaults to Canton Coin / "Amulet"). It is CALLER INTENT, never
+ * taken from the relay.
+ */
+export declare function transfer(relay: RelayClient, wallet: AgentWallet, opts: {
+    receiver: string;
+    amount: string;
+    meta?: Record<string, string>;
+    expectInstrumentId?: string;
+    /** Optional, caller-intent synchronizer id to PREPARE on and to pin the
+     *  SIGNED Metadata.synchronizer_id to. When supplied, the relay cannot land
+     *  the agent's signature on a domain of its choosing. */
+    expectSynchronizerId?: string;
+    /** Optional, independently-trusted instrument admin (DSO) to pin. When
+     *  supplied it closes the unpinned-admin neutralization fully (the admin can
+     *  no longer be aliased to an attacker and smuggled in as a consequence
+     *  recipient). Omitted by default — the agent has no out-of-band DSO. */
+    expectInstrumentAdmin?: string;
+    /**
+     * How to bind the relay-returned hash to the validated bytes before signing.
+     * Defaults (when omitted) to fail-closed: a value-moving transfer refuses to
+     * sign unless a `recomputeHash` is supplied or `trustRelayHash` is explicitly
+     * set. See HashBindingOptions / verify-prepared.ts.
+     */
+    hashBinding?: HashBindingOptions;
+}): Promise<string>;
+/**
+ * v1 (external-party-amulet-rules) — create a Splice `TransferCommand` the
+ * facilitator will later settle (it pays the GS traffic fee). The agent signs
+ * only an INTENT here: no gas, no preapproval. Mirrors the cip56 `transfer`
+ * flow — resolve refs via relay → build the create exercise → VERIFY-before-sign
+ * over the EXACT prepared bytes → sign locally → execute via relay → read back
+ * the created cid (ACS-polled by the relay) — but produces the v1 payload the
+ * x402 client puts in PaymentPayload: `{transferCommandCid, payerParty, nonce}`.
+ *
+ * SECURITY: every money-critical field the verifier pins (sender == own party,
+ * receiver == merchant payTo, amount == required, delegate == facilitatorParty)
+ * is CALLER INTENT passed in `opts`, NOT taken from the relay's resolve
+ * response. The relay-resolved EPAR/exercise templateIds + expectedDso are used
+ * only to BUILD the exercise; they widen nothing the agent will sign. The cid
+ * returned by the relay moves no funds on its own — the facilitator independently
+ * re-validates sender/receiver/amount/delegate/nonce at /verify + /settle.
+ */
+export declare function createTransferCommand(relay: RelayClient, wallet: AgentWallet, opts: {
+    /** Merchant party id (PaymentRequirements.payTo). CALLER INTENT. */
+    receiver: string;
+    /** Atomic amount string (PaymentRequirements.amount). CALLER INTENT. */
+    amount: string;
+    /** Facilitator/delegate party (extra.facilitatorParty). CALLER INTENT —
+     *  pinned by exact equality at the prepared command's delegate position. */
+    delegate: string;
+    /** Synchronizer id (extra.synchronizerId). CALLER INTENT — used to pin the
+     *  prepare's synchronizer to the merchant-advertised one, never the relay's. */
+    synchronizerId: string;
+    /** JSON-encoded {paymentId, resourceUrl, merchantContractCid?, x402Version}
+     *  the facilitator's /verify matches against TransferCommand.description. */
+    description: string;
+    /** Command expiry (epoch ms). Defaults to now + 60s. */
+    expiresAtMs?: number;
+    /** Optional, independently-trusted DSO party. When supplied it is pinned to
+     *  the command's expectedDso AND closes the unpinned-DSO neutralization fully
+     *  (the DSO can no longer be aliased to an attacker and smuggled in as a
+     *  consequence recipient). Omitted by default — the agent has no out-of-band
+     *  DSO; the position-aware backstop + money-role check still apply. NOTE:
+     *  pinning to the relay's own `r.expectedDso` would be circular and is
+     *  deliberately NOT done — only an out-of-band value is a real anchor. */
+    expectedDso?: string;
+    /** Hash-binding policy; defaults to fail-closed (see HashBindingOptions). */
+    hashBinding?: HashBindingOptions;
+}): Promise<{
+    transferCommandCid: string;
+    payerParty: string;
+    nonce: number;
+    createUpdateId: string;
+}>;
+/**
+ * Accept every pending incoming transfer (e.g. the agent's initial funding).
+ *
+ * SECURITY: even though this path is funds-IN, it is NOT exempt from
+ * verify-before-sign. A malicious relay returning an OUTBOUND drain
+ * (CreateTransferCommand / TransferFactory_Transfer sending the agent's balance
+ * to an attacker) instead of the accept the agent built would otherwise be
+ * blind-signed. We pass `kind: "accept"`, which structurally proves the prepared
+ * transaction is a single `TransferInstruction_Accept` submitted by the agent —
+ * any outbound leg is rejected — and we bind the signed hash to those bytes
+ * (fail-closed by default, exactly like the other paths). `opts.hashBinding`
+ * lets a programmatic caller supply a participant-conformant recompute; the CLI
+ * resolves it from the environment (default fail-closed).
+ */
+export declare function claimAll(relay: RelayClient, wallet: AgentWallet, opts?: {
+    hashBinding?: HashBindingOptions;
+}): Promise<{
+    claimed: number;
+    updateIds: string[];
+}>;
+//# sourceMappingURL=tx.d.ts.map

package/dist/tx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tx.d.ts","sourceRoot":"","sources":["../src/tx.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAKL,KAAK,kBAAkB,EAIxB,MAAM,sBAAsB,CAAC;AAiI9B;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE;IACJ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;6DAEyD;IACzD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;6EAGyE;IACzE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC,GACA,OAAO,CAAC,MAAM,CAAC,CAkEjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE;IACJ,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf;gFAC4E;IAC5E,QAAQ,EAAE,MAAM,CAAC;IACjB;oFACgF;IAChF,cAAc,EAAE,MAAM,CAAC;IACvB;iFAC6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;8EAM0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC,GACA,OAAO,CAAC;IAAE,kBAAkB,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC,CAgHpG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,kBAAkB,CAAA;CAAO,GAC9C,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA8BnD"}