@ldgr/client 0.4.0 → 0.6.0

package/README.md

@@ -67,6 +67,57 @@ Settlement failures return `status: "failed"`; they do not have a transaction
 hash or fee because the ledger rejected them before appending a transaction.
 Transport and unexpected response errors still throw.
 
+## Confidential payments
+
+The product term is **confidential payments**. The compatibility-stable
+`silentPayments.send()` API accepts a reusable LDGR payment code and a
+`LocalLdgrWallet`. It signs and publishes the wallet's immutable sender-DH
+public key, fetches the asset nonce, derives a fresh one-time destination, and
+submits an ordinary transfer. A `NONCE_MISMATCH` causes one fresh derivation;
+an ambiguous transport failure retries the exact signed request instead.
+
+```ts
+import {
+  createLdgrClient,
+  deriveLocalSilentPaymentIdentity,
+  loadLocalWallet,
+} from "@ldgr/client";
+
+const client = createLdgrClient({ network: "testnet" });
+const senderWallet = await loadLocalWallet({
+  ledgerId: 0,
+  recoveryKey: await secretStore.read("ldgr-testnet-sender"),
+});
+// The receiver shares this code out of band; their recovery key never leaves
+// their own wallet.
+const receiver = deriveLocalSilentPaymentIdentity({
+  ledgerId: 0,
+  recoveryKey: await receiverSecretStore.read("ldgr-testnet-receiver"),
+});
+const result = await client.silentPayments.send({
+  wallet: senderWallet,
+  paymentCode: receiver.paymentCode,
+  asset: "t0",
+  amount: "2.50",
+});
+```
+
+If two byte-identical transport attempts both remain ambiguous,
+`SilentPaymentSubmissionUnknownError` exposes the exact `submission`. Pass it
+to `client.silentPayments.retry(error.submission)`; do not start a fresh send,
+which would use the next nonce and could duplicate a payment that already
+settled.
+
+`silentPayments.scan(after, limit)` returns a bounded ascending page, its raw
+ledger-sequence `nextAfter` checkpoint, and `moreAvailable`. Matching requires
+the receiver scan secret and belongs in wallet code such as
+`@ldgr/wallet-core`, never on a server that does not own the recovery key. This
+LDGR-specific construction is not BIP-352-compatible and remains experimental.
+Wallet discovery is available on both ledgers. The extension and Web Wallet
+display reusable codes; the Web Wallet also sends to them. Spending or
+consolidating confidential-payment outputs remains gated pending testnet-first
+operational testing and external cryptographic review.
+
 ```ts
 import { createLdgrClient } from "@ldgr/client";
 
@@ -90,6 +141,59 @@ transaction hash as the idempotency key. AMM quotes are estimates: pass an
 explicit minimum output in the signed swap payload and re-quote immediately
 before signing.
 
+## Widget and Checkout merchant verification
+
+Available in `@ldgr/client` **0.6.0**. These methods work on servers without
+DOM globals or wallet keys. Configure the client's network from your saved
+order and pass only the widget's identifiers as the submitted proof:
+
+```ts
+import { createLdgrClient } from "@ldgr/client";
+
+const order = await orders.load(orderId); // Your persisted server order.
+const client = createLdgrClient({ network: order.network });
+const payment = await client.payments.verifyPayment({
+  transactionHash: submitted.transactionHash,
+  checkoutSessionId: submitted.checkoutSessionId, // Optional for wallet payments.
+}, {
+  to: order.recipient,
+  asset: order.assetCode,
+  amount: order.grossAmount, // Exact decimal string, including Checkout's fee.
+  reference: order.publicReference,
+});
+
+if (payment.status === "confirmed") {
+  // In one database transaction: check order expiry, claim a unique
+  // (network, transactionHash), bind it to this order, and fulfil once.
+  await orders.fulfilOnce(order.id, order.network, payment.transactionHash);
+}
+```
+
+`verifyPayment` explicitly dispatches to Checkout when `checkoutSessionId` is
+provided; otherwise it requires a plain transfer. It never infers Checkout
+from arbitrary batch metadata or falls back after a session mismatch. Expected
+`to`, `asset`, gross decimal `amount`, and `reference` must come from your server,
+not from the browser. Amount comparisons use exact strings, never floating point.
+
+For a known Checkout session, use `payments.verifyCheckout(sessionId, {
+to, asset, amount, reference, transactionHash? })`. It checks the authoritative
+session ID, ledger, recipient, asset, gross amount, reference, paid state, and
+optional submitted hash. A confirmed result includes `sessionId`,
+`transactionHash`, `from`, `to`, `asset`, gross `amount`, `merchantAmount`, and
+`checkoutFee`. With the default fee, a gross `1` USDL receipt reports merchant
+`0.995` USDL and Checkout fee `0.005` USDL. Do not compare the net receipt with
+the gross order amount.
+
+Non-confirmed Checkout results are `pending`, `expired`, `not_found`, or
+`mismatch`. An expired funding instruction does not invalidate a paid receipt.
+Network/server errors and invalid arguments throw; callers must not fulfil on
+an error. `verifyTransfer` remains a strict plain-transfer verifier. It also
+checks that the response hash matches the requested hash.
+
+The SDK reads receipts; your service owns authentication, order persistence,
+order expiry rules, and atomic duplicate-payment protection. Browser SDK
+`getPaymentStatus` / `getCheckoutStatus` results are UX hints only.
+
 ## LDGR402 merchant verification
 
 For a persisted LDGR402 requirement and the browser's

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { type LdgrTransferResult, type SendTransferInput } from "./transfer";
-import { type Ldgr402Requirement, type LedgerId } from "@ldgr/protocol";
-import { type LdgrAccountTransactionPage, type LdgrClientOptions, type LdgrAsset, type Ldgr402Verification, type LdgrTransaction, type PaymentExpectation, type PaymentVerification, type SignedSubmission } from "./types";
+import { type Ldgr402Requirement } from "@ldgr/protocol";
+import { type LdgrAccountTransactionPage, type LdgrClientOptions, type LdgrAsset, type Ldgr402Verification, type LdgrTransaction, type PaymentExpectation, type PaymentVerification, type CheckoutPaymentExpectation, type CheckoutPaymentVerification, type MerchantPaymentExpectation, type MerchantPaymentVerification, type PaymentSubmission, type SignedSubmission, type SilentPaymentSendInput, type SilentPaymentScanPage, type WalletPublicKeyRecord, type WalletPublicKeyRegistration } from "./types";
 export declare function createLdgrClient(options: LdgrClientOptions): {
     ledger: {
         get: () => Promise<{
@@ -26,23 +26,8 @@ export declare function createLdgrClient(options: LdgrClientOptions): {
             readonly asset: string;
             readonly nextNonce: string;
         }>;
-        getWalletPublicKey: (address: string) => Promise<{
-            readonly address: string;
-            readonly publicKey: string;
-        }>;
-        registerWalletPublicKey: (address: string, registration: {
-            readonly version: 1;
-            readonly action: "wallet_key_register";
-            readonly chain: "ldgr-v1";
-            readonly ledgerId: LedgerId;
-            readonly from: string;
-            readonly publicKey: string;
-            readonly timestamp: string;
-            readonly signature: string;
-        }) => Promise<{
-            readonly address: string;
-            readonly publicKey: string;
-        }>;
+        getWalletPublicKey: (address: string) => Promise<WalletPublicKeyRecord>;
+        registerWalletPublicKey: (address: string, registration: WalletPublicKeyRegistration) => Promise<WalletPublicKeyRecord>;
         listTransactions(address: string, options?: {
             readonly before?: string;
             readonly asset?: string;
@@ -90,10 +75,17 @@ export declare function createLdgrClient(options: LdgrClientOptions): {
     };
     payments: {
         verifyTransfer: (transactionHash: string, expected: PaymentExpectation) => Promise<PaymentVerification>;
+        verifyCheckout: (sessionId: string, expected: CheckoutPaymentExpectation) => Promise<CheckoutPaymentVerification>;
+        verifyPayment: (submission: PaymentSubmission, expected: MerchantPaymentExpectation) => Promise<MerchantPaymentVerification>;
         verifyLdgr402: (proofHeader: string, requirementInput: Ldgr402Requirement, options?: {
             readonly nowMs?: number;
         }) => Promise<Ldgr402Verification>;
     };
+    silentPayments: {
+        scan: (after?: string, limit?: number) => Promise<SilentPaymentScanPage>;
+        send: (input: SilentPaymentSendInput) => Promise<LdgrTransferResult>;
+        retry(submission: SignedSubmission): Promise<LdgrTransferResult>;
+    };
     transfers: {
         send: (input: SendTransferInput) => Promise<LdgrTransferResult>;
     };
@@ -101,10 +93,10 @@ export declare function createLdgrClient(options: LdgrClientOptions): {
         readonly transactionHash?: string;
     }>(path: string, signed: SignedSubmission) => Promise<T>;
 };
-export { LdgrClientError } from "./types";
+export { LdgrClientError, SilentPaymentSubmissionUnknownError } from "./types";
 export { decodeMerchantLdgr402Payment, parseMerchantLdgr402Requirement } from "./ldgr402";
-export type { LdgrAccountTransaction, LdgrAccountTransactionPage, Ldgr402Requirement, Ldgr402Verification, LdgrAsset, LdgrClientOptions, LdgrNetwork, LdgrTransaction, PaymentExpectation, PaymentVerification, SignedSubmission } from "./types";
-export { createWebCryptoSigner, generateLocalWallet, loadLocalWallet } from "./signer";
-export type { LdgrSigner, LocalLdgrWallet } from "./signer";
+export type { CheckoutPaymentExpectation, CheckoutPaymentVerification, MerchantPaymentExpectation, MerchantPaymentVerification, PaymentSubmission, LdgrAccountTransaction, LdgrAccountTransactionPage, Ldgr402Requirement, Ldgr402Verification, LdgrAsset, LdgrClientOptions, LdgrNetwork, LdgrTransaction, PaymentExpectation, PaymentVerification, SignedSubmission, SilentPaymentScanPage, SilentPaymentScanRecord, SilentPaymentSendInput, WalletPublicKeyRecord, WalletPublicKeyRegistration } from "./types";
+export { createWebCryptoSigner, deriveLocalSilentPaymentIdentity, generateLocalWallet, loadLocalWallet } from "./signer";
+export type { LdgrSigner, LocalLdgrWallet, LocalSilentPaymentIdentity } from "./signer";
 export { buildTransferSubmission } from "./transfer";
 export type { BuildTransferSubmissionInput, LdgrTransferResult, SendTransferInput } from "./transfer";

package/dist/index.js

@@ -2,6 +2,15 @@
 import { resolveLdgrNetwork } from "@ldgr/protocol";
 
 // src/types.ts
+class SilentPaymentSubmissionUnknownError extends Error {
+  submission;
+  constructor(submission, cause) {
+    super("Could not confirm silent payment submission; retry this exact signed submission", { cause });
+    this.name = "SilentPaymentSubmissionUnknownError";
+    this.submission = submission;
+  }
+}
+
 class LdgrClientError extends Error {
   status;
   code;
@@ -77,6 +86,67 @@ function queryPath(path, query) {
   return encoded ? `${path}?${encoded}` : path;
 }
 
+// src/signer.ts
+import {
+  deriveAddress,
+  deriveSilentPaymentIdentity,
+  decodeEd25519RecoveryKey,
+  encodeEd25519RecoveryKey,
+  exportEd25519PublicKey,
+  generateEd25519KeyPair,
+  importEd25519PrivateSeed,
+  signCanonicalPayload
+} from "@ldgr/protocol";
+function encodeBase64Url(bytes) {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function deriveLocalSilentPaymentIdentity(input) {
+  const { privateSeed } = decodeEd25519RecoveryKey(input.recoveryKey);
+  const identity = deriveSilentPaymentIdentity(privateSeed, input.ledgerId);
+  return {
+    paymentCode: identity.paymentCode,
+    senderDhPublicKey: encodeBase64Url(identity.senderDhPublicKey),
+    receiverScanPublicKey: encodeBase64Url(identity.receiverScanPublicKey),
+    spendPublicKey: encodeBase64Url(identity.spendPublicKey)
+  };
+}
+async function createWebCryptoSigner(input) {
+  const publicKey = encodeBase64Url(await exportEd25519PublicKey(input.publicKey));
+  const address = await deriveAddress(input.publicKey, input.ledgerId);
+  return {
+    address,
+    publicKey,
+    ledgerId: input.ledgerId,
+    async sign(payload) {
+      if (payload.ledgerId !== input.ledgerId)
+        throw new TypeError("payload ledgerId does not match signer ledgerId");
+      if (payload.from !== address)
+        throw new TypeError("payload from does not match signer address");
+      if (payload.publicKey !== undefined && payload.publicKey !== publicKey) {
+        throw new TypeError("payload publicKey does not match signer publicKey");
+      }
+      return encodeBase64Url(await signCanonicalPayload(input.privateKey, { ...payload, publicKey }));
+    }
+  };
+}
+async function generateLocalWallet(input) {
+  const keyPair = await generateEd25519KeyPair();
+  const signer = await createWebCryptoSigner({ ...input, ...keyPair });
+  const privateKeyJwk = await globalThis.crypto.subtle.exportKey("jwk", keyPair.privateKey);
+  return {
+    ...signer,
+    recoveryKey: encodeEd25519RecoveryKey(privateKeyJwk)
+  };
+}
+async function loadLocalWallet(input) {
+  const { privateSeed } = decodeEd25519RecoveryKey(input.recoveryKey);
+  const keyPair = await importEd25519PrivateSeed(privateSeed);
+  return { ...await createWebCryptoSigner({ ...input, ...keyPair }), recoveryKey: input.recoveryKey };
+}
+
 // src/transfer.ts
 import {
   canonicalizeLedgerAddress,
@@ -127,6 +197,10 @@ async function buildTransferSubmission(input) {
 // src/index.ts
 import {
   decodeLdgr402Payment as decodeLdgr402Payment3,
+  decodeEd25519RecoveryKey as decodeEd25519RecoveryKey2,
+  decodeSilentPaymentCode,
+  deriveSilentPaymentIdentity as deriveSilentPaymentIdentity2,
+  deriveSilentPaymentSenderOutput,
   nativeAssetDefinitionForLedger,
   parseLdgr402Requirement as parseLdgr402Requirement3,
   resolveLdgrNetwork as resolveLdgrNetwork2,
@@ -147,60 +221,11 @@ function parseMerchantLdgr402Requirement(input, options = {}) {
 function decodeMerchantLdgr402Payment(headerValue) {
   return decodeLdgr402Payment(headerValue);
 }
-// src/signer.ts
-import {
-  deriveAddress,
-  decodeEd25519RecoveryKey,
-  encodeEd25519RecoveryKey,
-  exportEd25519PublicKey,
-  generateEd25519KeyPair,
-  importEd25519PrivateSeed,
-  signCanonicalPayload
-} from "@ldgr/protocol";
-function encodeBase64Url(bytes) {
-  let binary = "";
-  for (const byte of bytes)
-    binary += String.fromCharCode(byte);
-  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
-}
-async function createWebCryptoSigner(input) {
-  const publicKey = encodeBase64Url(await exportEd25519PublicKey(input.publicKey));
-  const address = await deriveAddress(input.publicKey, input.ledgerId);
-  return {
-    address,
-    publicKey,
-    ledgerId: input.ledgerId,
-    async sign(payload) {
-      if (payload.ledgerId !== input.ledgerId)
-        throw new TypeError("payload ledgerId does not match signer ledgerId");
-      if (payload.from !== address)
-        throw new TypeError("payload from does not match signer address");
-      if (payload.publicKey !== undefined && payload.publicKey !== publicKey) {
-        throw new TypeError("payload publicKey does not match signer publicKey");
-      }
-      return encodeBase64Url(await signCanonicalPayload(input.privateKey, { ...payload, publicKey }));
-    }
-  };
-}
-async function generateLocalWallet(input) {
-  const keyPair = await generateEd25519KeyPair();
-  const signer = await createWebCryptoSigner({ ...input, ...keyPair });
-  const privateKeyJwk = await globalThis.crypto.subtle.exportKey("jwk", keyPair.privateKey);
-  return {
-    ...signer,
-    recoveryKey: encodeEd25519RecoveryKey(privateKeyJwk)
-  };
-}
-async function loadLocalWallet(input) {
-  const { privateSeed } = decodeEd25519RecoveryKey(input.recoveryKey);
-  const keyPair = await importEd25519PrivateSeed(privateSeed);
-  return createWebCryptoSigner({ ...input, ...keyPair });
-}
 
 // src/index.ts
 function normalizedHash(transactionHash) {
   const hash = transactionHash.toLowerCase();
-  if (!/^[0-9a-f]{64}$/.test(hash))
+  if (hash.length !== 64 || !/^[0-9a-f]{64}$/.test(hash))
     throw new TypeError("transactionHash must be a 64-character hexadecimal hash");
   return hash;
 }
@@ -222,6 +247,18 @@ function paymentReference(metadata) {
 function transactionFields(transaction) {
   return typeof transaction.from === "string" && typeof transaction.to === "string" && typeof transaction.asset === "string" && typeof transaction.amount === "string" ? { from: transaction.from, to: transaction.to, asset: transaction.asset, amount: transaction.amount } : null;
 }
+function assertMerchantTerms(expected) {
+  if (typeof expected.to !== "string" || !expected.to)
+    throw new TypeError("to is required");
+  if (typeof expected.asset !== "string" || !expected.asset.trim())
+    throw new TypeError("asset is required");
+  if (typeof expected.reference !== "string" || !expected.reference || new TextEncoder().encode(expected.reference).byteLength > 128) {
+    throw new TypeError("reference must be 1 to 128 UTF-8 bytes");
+  }
+  if (typeof expected.amount !== "string" || !sameDecimalAmount(expected.amount, expected.amount) || !/[1-9]/.test(expected.amount)) {
+    throw new TypeError("amount must be a positive exact decimal string");
+  }
+}
 function isNonceMismatch(error) {
   return error instanceof LdgrClientError && error.code === "NONCE_MISMATCH";
 }
@@ -257,18 +294,65 @@ function createLdgrClient(options) {
       throw error;
     }
     const fields = transactionFields(transaction);
-    if (transaction.action !== "transfer" || fields === null || fields.to !== expected.to || fields.asset !== expectedAsset || !sameDecimalAmount(fields.amount, expected.amount) || expected.reference !== undefined && paymentReference(transaction.metadata) !== expected.reference) {
+    if (transaction.transactionHash !== hash || transaction.action !== "transfer" || fields === null || fields.to !== expected.to || fields.asset !== expectedAsset || !sameDecimalAmount(fields.amount, expected.amount) || expected.reference !== undefined && paymentReference(transaction.metadata) !== expected.reference) {
       return { status: "mismatch", transactionHash: hash };
     }
     return { status: "confirmed", transactionHash: hash, ...fields };
   };
-  const verifyLdgr402 = async (proofHeader, requirementInput, options2 = {}) => {
+  const verifyCheckout = async (sessionId, expected) => {
+    if (ledgerId === undefined)
+      throw new TypeError("network is required for Checkout verification");
+    if (sessionId.length !== 36 || !/^chk_[0-9a-f]{32}$/.test(sessionId))
+      throw new TypeError("Invalid Checkout session ID");
+    assertMerchantTerms(expected);
+    const asset = resolveAsset(expected.asset.trim());
+    const expectedHash = expected.transactionHash === undefined ? undefined : normalizedHash(expected.transactionHash);
+    let body;
+    try {
+      body = await transport.get(`/api/v1/checkout/sessions/${sessionId}`);
+    } catch (error) {
+      if (error instanceof LdgrClientError && error.status === 404)
+        return { status: "not_found", sessionId };
+      throw error;
+    }
+    const mismatch = { status: "mismatch", sessionId };
+    if (body === null || typeof body !== "object" || Array.isArray(body))
+      return mismatch;
+    const session = body;
+    if (session.id !== sessionId || session.ledgerId !== ledgerId || session.recipient !== expected.to || session.asset !== asset || typeof session.amount !== "string" || !sameDecimalAmount(session.amount, expected.amount) || session.paymentReference !== expected.reference)
+      return mismatch;
+    if (session.status === "open")
+      return { status: "pending", sessionId };
+    if (session.status === "expired")
+      return { status: "expired", sessionId };
+    if (session.status !== "paid" || typeof session.transactionHash !== "string" || session.transactionHash.length !== 64 || !/^[0-9a-f]{64}$/.test(session.transactionHash) || expectedHash !== undefined && session.transactionHash !== expectedHash || typeof session.guestAddress !== "string" || !session.guestAddress || typeof session.merchantAmount !== "string" || !sameDecimalAmount(session.merchantAmount, session.merchantAmount) || typeof session.checkoutFee !== "string" || !sameDecimalAmount(session.checkoutFee, session.checkoutFee))
+      return mismatch;
+    return {
+      status: "confirmed",
+      sessionId,
+      transactionHash: session.transactionHash,
+      from: session.guestAddress,
+      to: expected.to,
+      asset,
+      amount: session.amount,
+      merchantAmount: session.merchantAmount,
+      checkoutFee: session.checkoutFee
+    };
+  };
+  const verifyPayment = async (submission, expected) => {
+    if (ledgerId === undefined)
+      throw new TypeError("network is required for merchant payment verification");
+    assertMerchantTerms(expected);
+    const hash = normalizedHash(submission.transactionHash);
+    return submission.checkoutSessionId === undefined ? verifyTransfer(hash, expected) : verifyCheckout(submission.checkoutSessionId, { ...expected, transactionHash: hash });
+  };
+  const verifyLdgr402 = async (proofHeader, requirementInput, options = {}) => {
     const proof = decodeLdgr402Payment3(proofHeader);
     const requirement = parseLdgr402Requirement3(requirementInput, {
-      nowMs: options2.nowMs,
+      nowMs: options.nowMs,
       allowExpired: true
     });
-    const nowMs = options2.nowMs ?? Date.now();
+    const nowMs = options.nowMs ?? Date.now();
     if (ledgerId === undefined)
       throw new TypeError("network is required for LDGR402 verification");
     if (proof.ledgerId !== requirement.ledgerId || ledgerId !== requirement.ledgerId || proof.challenge !== requirement.challenge) {
@@ -323,9 +407,101 @@ function createLdgrClient(options) {
         try {
           return await submit();
         } catch (retryError) {
-          const failure2 = transferFailure(retryError);
-          if (failure2 !== undefined)
-            return failure2;
+          const failure = transferFailure(retryError);
+          if (failure !== undefined)
+            return failure;
+          throw retryError;
+        }
+      }
+      const failure = transferFailure(error);
+      if (failure !== undefined)
+        return failure;
+      throw error;
+    }
+  };
+  const sendSilentPayment = async (input) => {
+    if (ledgerId !== undefined && ledgerId !== input.wallet.ledgerId) {
+      throw new TypeError("signer ledgerId does not match client network");
+    }
+    const requestedAsset = input.asset.trim();
+    if (!requestedAsset)
+      throw new TypeError("asset is required");
+    const asset = resolvePublicAssetCode(requestedAsset, input.wallet.ledgerId);
+    decodeSilentPaymentCode(input.paymentCode, input.wallet.ledgerId);
+    const assetDefinition = asset === "dng" ? nativeAssetDefinitionForLedger(input.wallet.ledgerId) : await transport.get(`/api/v1/assets/${encodePathSegment(asset)}`);
+    const senderIdentity = deriveSilentPaymentIdentity2(decodeEd25519RecoveryKey2(input.wallet.recoveryKey).privateSeed, input.wallet.ledgerId);
+    const registrationPayload = {
+      version: 1,
+      action: "wallet_key_register",
+      chain: "ldgr-v1",
+      ledgerId: input.wallet.ledgerId,
+      from: input.wallet.address,
+      publicKey: input.wallet.publicKey,
+      senderDhPublicKey: deriveLocalSilentPaymentIdentity(input.wallet).senderDhPublicKey,
+      timestamp: String((input.now ?? Date.now)())
+    };
+    await transport.post(`/api/v1/wallets/${encodePathSegment(input.wallet.address)}/public-key`, { ...registrationPayload, signature: await input.wallet.sign(registrationPayload) });
+    const submit = async () => {
+      const nonce = await transport.get(`/api/v1/nonces/${encodePathSegment(input.wallet.address)}/${encodePathSegment(asset)}`);
+      if (!/^(0|[1-9][0-9]*)$/.test(nonce.nextNonce))
+        throw new TypeError("Ledger returned an invalid next nonce");
+      const output = deriveSilentPaymentSenderOutput({
+        senderDhPrivateKey: senderIdentity.senderDhPrivateKey,
+        paymentCode: input.paymentCode,
+        chain: "ldgr-v1",
+        ledgerId: input.wallet.ledgerId,
+        senderAddress: input.wallet.address,
+        action: "transfer",
+        asset,
+        nonce: BigInt(nonce.nextNonce),
+        outputIndex: 0
+      });
+      const submission = await buildTransferSubmission({
+        wallet: input.wallet,
+        asset,
+        assetDefinition,
+        amount: input.amount,
+        to: output.address,
+        nextNonce: nonce.nextNonce,
+        ...input.memo === undefined ? {} : { memo: input.memo },
+        ...input.metadata === undefined ? {} : { metadata: input.metadata },
+        ...input.now === undefined ? {} : { now: input.now }
+      });
+      const feeSponsor = input.buildFeeSponsor === undefined ? undefined : await input.buildFeeSponsor(submission);
+      const requestBody = {
+        ...submission,
+        ...feeSponsor === undefined ? {} : { feeSponsor },
+        submittedAtMs: Date.now()
+      };
+      let transaction;
+      try {
+        transaction = await transport.post("/api/v1/transfers", requestBody);
+      } catch (error) {
+        if (error instanceof LdgrClientError)
+          throw error;
+        try {
+          transaction = await transport.post("/api/v1/transfers", requestBody);
+        } catch (retryError) {
+          if (retryError instanceof LdgrClientError)
+            throw retryError;
+          throw new SilentPaymentSubmissionUnknownError(requestBody, retryError);
+        }
+      }
+      if (typeof transaction.transactionHash !== "string" || typeof transaction.fee !== "string" || typeof transaction.feeAsset !== "string") {
+        throw new TypeError("LDGR transfer response is missing transaction hash or fee");
+      }
+      return { status: "settled", transactionHash: transaction.transactionHash, fee: transaction.fee, feeAsset: transaction.feeAsset, transaction };
+    };
+    try {
+      return await submit();
+    } catch (error) {
+      if (isNonceMismatch(error)) {
+        try {
+          return await submit();
+        } catch (retryError) {
+          const failure = transferFailure(retryError);
+          if (failure !== undefined)
+            return failure;
           throw retryError;
         }
       }
@@ -346,10 +522,10 @@ function createLdgrClient(options) {
       getNextNonce: (address, asset) => transport.get(`/api/v1/nonces/${encodePathSegment(address)}/${encodePathSegment(resolveAsset(asset))}`),
       getWalletPublicKey: (address) => transport.get(`/api/v1/wallets/${encodePathSegment(address)}/public-key`),
       registerWalletPublicKey: (address, registration) => transport.post(`/api/v1/wallets/${encodePathSegment(address)}/public-key`, registration),
-      async listTransactions(address, options2 = {}) {
+      async listTransactions(address, options = {}) {
         const path = queryPath(`/api/v1/explorer/addresses/${encodePathSegment(address)}/transactions`, {
-          before: options2.before,
-          asset: options2.asset === undefined ? undefined : resolveAsset(options2.asset)
+          before: options.before,
+          asset: options.asset === undefined ? undefined : resolveAsset(options.asset)
         });
         try {
           return await transport.get(path);
@@ -401,19 +577,41 @@ function createLdgrClient(options) {
     usernames: {
       get: (name) => transport.get(`/api/v1/usernames/${encodePathSegment(name)}`),
       getPrimary: (address) => transport.get(`/api/v1/usernames/by-address/${encodePathSegment(address)}`),
-      listOwned: (address, options2) => transport.get(queryPath(`/api/v1/usernames/owned-by/${encodePathSegment(address)}`, options2 ?? {}))
+      listOwned: (address, options) => transport.get(queryPath(`/api/v1/usernames/owned-by/${encodePathSegment(address)}`, options ?? {}))
+    },
+    payments: { verifyTransfer, verifyCheckout, verifyPayment, verifyLdgr402 },
+    silentPayments: {
+      scan: (after = "0", limit) => transport.get(queryPath("/api/v1/silent-payments/scan", { after, limit })),
+      send: sendSilentPayment,
+      async retry(submission) {
+        try {
+          const transaction = await transport.post("/api/v1/transfers", submission);
+          if (typeof transaction.transactionHash !== "string" || typeof transaction.fee !== "string" || typeof transaction.feeAsset !== "string") {
+            throw new TypeError("LDGR transfer response is missing transaction hash or fee");
+          }
+          return { status: "settled", transactionHash: transaction.transactionHash, fee: transaction.fee, feeAsset: transaction.feeAsset, transaction };
+        } catch (error) {
+          const failure = transferFailure(error);
+          if (failure !== undefined)
+            return failure;
+          if (error instanceof LdgrClientError)
+            throw error;
+          throw new SilentPaymentSubmissionUnknownError(submission, error);
+        }
+      }
     },
-    payments: { verifyTransfer, verifyLdgr402 },
     transfers: { send: sendTransfer },
     submitSigned: (path, signed) => transport.post(path, { ...signed, submittedAtMs: Date.now() })
   };
 }
 export {
   LdgrClientError,
+  SilentPaymentSubmissionUnknownError,
   buildTransferSubmission,
   createLdgrClient,
   createWebCryptoSigner,
   decodeMerchantLdgr402Payment,
+  deriveLocalSilentPaymentIdentity,
   generateLocalWallet,
   loadLocalWallet,
   parseMerchantLdgr402Requirement

package/dist/signer.d.ts

@@ -9,6 +9,16 @@ export interface LocalLdgrWallet extends LdgrSigner {
     /** Store this only in the caller's chosen secret manager; it is never sent to LDGR. */
     readonly recoveryKey: string;
 }
+export interface LocalSilentPaymentIdentity {
+    readonly paymentCode: string;
+    readonly senderDhPublicKey: string;
+    readonly receiverScanPublicKey: string;
+    readonly spendPublicKey: string;
+}
+export declare function deriveLocalSilentPaymentIdentity(input: {
+    readonly recoveryKey: string;
+    readonly ledgerId: LedgerId;
+}): LocalSilentPaymentIdentity;
 export declare function createWebCryptoSigner(input: {
     readonly ledgerId: LedgerId;
     readonly privateKey: CryptoKey;
@@ -21,4 +31,4 @@ export declare function generateLocalWallet(input: {
 export declare function loadLocalWallet(input: {
     readonly recoveryKey: string;
     readonly ledgerId: LedgerId;
-}): Promise<LdgrSigner>;
+}): Promise<LocalLdgrWallet>;

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import type { AssetBridgePolicy, LdgrNetwork } from "@ldgr/protocol";
+import type { LocalLdgrWallet } from "./signer";
 export type LedgerId = 0 | 1;
 export type { LdgrNetwork } from "@ldgr/protocol";
 export type LdgrTransaction = {
@@ -63,6 +64,34 @@ export type PaymentVerification = {
     readonly status: "not_found" | "mismatch";
     readonly transactionHash: string;
 };
+/** Immutable merchant order terms; amount is the gross exact decimal amount. */
+export type MerchantPaymentExpectation = PaymentExpectation & {
+    readonly asset: string;
+    readonly reference: string;
+};
+export type CheckoutPaymentExpectation = MerchantPaymentExpectation & {
+    readonly transactionHash?: string;
+};
+/** Identifiers forwarded from a widget event, never trusted order terms. */
+export type PaymentSubmission = {
+    readonly transactionHash: string;
+    readonly checkoutSessionId?: string;
+};
+export type CheckoutPaymentVerification = {
+    readonly status: "confirmed";
+    readonly sessionId: string;
+    readonly transactionHash: string;
+    readonly from: string;
+    readonly to: string;
+    readonly asset: string;
+    readonly amount: string;
+    readonly merchantAmount: string;
+    readonly checkoutFee: string;
+} | {
+    readonly status: "pending" | "expired" | "not_found" | "mismatch";
+    readonly sessionId: string;
+};
+export type MerchantPaymentVerification = PaymentVerification | CheckoutPaymentVerification;
 export type Ldgr402Verification = PaymentVerification | {
     readonly status: "expired";
     readonly transactionHash: string;
@@ -75,6 +104,58 @@ export type SignedSubmission = {
     readonly feeSponsor?: unknown;
     readonly submittedAtMs?: number;
 };
+export type WalletPublicKeyRegistration = {
+    readonly version: 1;
+    readonly action: "wallet_key_register";
+    readonly chain: "ldgr-v1";
+    readonly ledgerId: LedgerId;
+    readonly from: string;
+    readonly publicKey: string;
+    /** Domain-separated X25519 public key used only by silent-payment senders. */
+    readonly senderDhPublicKey?: string;
+    readonly timestamp: string;
+    readonly signature: string;
+};
+export type WalletPublicKeyRecord = {
+    readonly address: string;
+    readonly publicKey: string;
+    readonly senderDhPublicKey?: string;
+};
+export type SilentPaymentScanRecord = {
+    readonly sequence: string;
+    readonly transactionHash: string;
+    readonly from: string;
+    readonly senderDhPublicKey: string;
+    readonly action: "transfer" | "transfer_batch";
+    readonly asset: string;
+    readonly nonce: string;
+    readonly outputs: readonly {
+        readonly to: string;
+        readonly amountAtomic: string;
+    }[];
+};
+export type SilentPaymentScanPage = {
+    readonly records: readonly SilentPaymentScanRecord[];
+    /** Raw committed-sequence checkpoint, including pages with no matching records. */
+    readonly nextAfter: string;
+    readonly moreAvailable: boolean;
+};
+export type SilentPaymentSendInput = {
+    readonly wallet: LocalLdgrWallet;
+    readonly paymentCode: string;
+    /** Public native id (`t0`/`t1`) or wire asset code. */
+    readonly asset: string;
+    readonly amount: string;
+    readonly memo?: string;
+    readonly metadata?: import("@ldgr/protocol").JsonValue;
+    readonly now?: () => number;
+    /** Recomputed for every signed attempt because it binds the exact payload. */
+    readonly buildFeeSponsor?: (submission: Pick<SignedSubmission, "payload" | "signature">) => Promise<unknown>;
+};
+export declare class SilentPaymentSubmissionUnknownError extends Error {
+    readonly submission: SignedSubmission;
+    constructor(submission: SignedSubmission, cause?: unknown);
+}
 export type LdgrClientOptions = {
     /** `testnet` / `0` or `mainnet` / `1`; required to use public native ids `t0` / `t1`. */
     readonly network?: LdgrNetwork;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ldgr/client",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -12,7 +12,7 @@
   "files": ["dist", "README.md"],
   "publishConfig": { "access": "public" },
   "engines": { "node": ">=20.19.0" },
-  "dependencies": { "@ldgr/protocol": "^0.4.0" },
+  "dependencies": { "@ldgr/protocol": "^0.5.0" },
   "scripts": {
     "build": "rm -rf dist && bun build src/index.ts --outdir dist --target node --format esm --packages external && tsc -p tsconfig.build.json",
     "prepack": "bun run build",