@ldgr/client 0.4.0 → 0.5.0

package/README.md

@@ -67,6 +67,55 @@ 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.
 
+## Silent payments
+
+`silentPayments.send()` 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, while reusable-code display,
+first-party sending, and private-output spending remain gated pending testnet-first
+operational testing and external cryptographic review.
+
 ```ts
 import { createLdgrClient } from "@ldgr/client";
 

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 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;
@@ -94,6 +79,11 @@ export declare function createLdgrClient(options: LdgrClientOptions): {
             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 +91,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 { 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,55 +221,6 @@ 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) {
@@ -335,6 +360,98 @@ function createLdgrClient(options) {
       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 failure2 = transferFailure(retryError);
+          if (failure2 !== undefined)
+            return failure2;
+          throw retryError;
+        }
+      }
+      const failure = transferFailure(error);
+      if (failure !== undefined)
+        return failure;
+      throw error;
+    }
+  };
   return {
     ledger: {
       get: () => transport.get("/api/v1/ledger"),
@@ -404,16 +521,38 @@ function createLdgrClient(options) {
       listOwned: (address, options2) => transport.get(queryPath(`/api/v1/usernames/owned-by/${encodePathSegment(address)}`, options2 ?? {}))
     },
     payments: { verifyTransfer, 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);
+        }
+      }
+    },
     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 = {
@@ -75,6 +76,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.5.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",