@ldgr/client 0.3.0 → 0.5.0

package/README.md

@@ -35,6 +35,87 @@ console.log(serviceWallet.address); // safe to identify the service wallet
 This is for backend/Bun service wallets only. Websites should use
 `@ldgr/wallet-sdk` and an extension-confirmed customer wallet instead.
 
+## Send a native or user-issued asset
+
+`transfers.send()` resolves the asset metadata, fetches the current nonce,
+builds and signs the transfer, submits it to the selected network, and retries
+once if another process consumed the nonce first. Use
+`LEDRA_TESTNET_ASSET_ID` / `LEDRA_MAINNET_ASSET_ID` from `@ldgr/protocol` for
+the native asset or pass a user-token code.
+
+```ts
+import { createLdgrClient } from "@ldgr/client";
+import { LEDRA_MAINNET_ASSET_ID } from "@ldgr/protocol";
+
+const client = createLdgrClient({ network: "mainnet" });
+const result = await client.transfers.send({
+  wallet: serviceWallet,
+  asset: LEDRA_MAINNET_ASSET_ID,
+  amount: "2.50",
+  to: recipientAddress,
+  memo: "Order 1234",
+});
+
+if (result.status === "settled") {
+  console.log(result.transactionHash, result.fee, result.feeAsset);
+} else {
+  console.error(result.code, result.error);
+}
+```
+
+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,5 +1,6 @@
-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 LdgrTransferResult, type SendTransferInput } from "./transfer";
+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<{
@@ -25,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;
@@ -93,12 +79,22 @@ 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>;
+    };
     submitSigned: <T extends {
         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,31 +86,10 @@ function queryPath(path, query) {
   return encoded ? `${path}?${encoded}` : path;
 }
 
-// src/index.ts
-import {
-  decodeLdgr402Payment as decodeLdgr402Payment3,
-  parseLdgr402Requirement as parseLdgr402Requirement3,
-  resolveLdgrNetwork as resolveLdgrNetwork2,
-  resolvePublicAssetCode
-} from "@ldgr/protocol";
-// src/ldgr402.ts
-import {
-  decodeLdgr402Payment,
-  parseLdgr402Requirement
-} from "@ldgr/protocol";
-import { decodeLdgr402Payment as decodeLdgr402Payment2, encodeLdgr402Payment, parseLdgr402Payment, parseLdgr402Requirement as parseLdgr402Requirement2 } from "@ldgr/protocol";
-function parseMerchantLdgr402Requirement(input, options = {}) {
-  return parseLdgr402Requirement(input, {
-    nowMs: options.nowMs,
-    allowExpired: true
-  });
-}
-function decodeMerchantLdgr402Payment(headerValue) {
-  return decodeLdgr402Payment(headerValue);
-}
 // src/signer.ts
 import {
   deriveAddress,
+  deriveSilentPaymentIdentity,
   decodeEd25519RecoveryKey,
   encodeEd25519RecoveryKey,
   exportEd25519PublicKey,
@@ -115,6 +103,16 @@ function encodeBase64Url(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);
@@ -146,7 +144,82 @@ async function generateLocalWallet(input) {
 async function loadLocalWallet(input) {
   const { privateSeed } = decodeEd25519RecoveryKey(input.recoveryKey);
   const keyPair = await importEd25519PrivateSeed(privateSeed);
-  return createWebCryptoSigner({ ...input, ...keyPair });
+  return { ...await createWebCryptoSigner({ ...input, ...keyPair }), recoveryKey: input.recoveryKey };
+}
+
+// src/transfer.ts
+import {
+  canonicalizeLedgerAddress,
+  assertEncryptedMessageEnvelope,
+  formatAtomicAmount,
+  parseDecimalAmount
+} from "@ldgr/protocol";
+async function buildTransferSubmission(input) {
+  const recipient = canonicalizeLedgerAddress(input.to, input.wallet.ledgerId);
+  const amount = parseDecimalAmount(input.amount.trim(), input.assetDefinition);
+  if (amount < 0n || amount === 0n && (input.asset !== "dng" || input.encryptedMessage === undefined)) {
+    throw new RangeError("Amount must be greater than zero unless sending an encrypted Ledra message");
+  }
+  if (input.encryptedMessage !== undefined)
+    assertEncryptedMessageEnvelope(input.encryptedMessage);
+  if (!/^(0|[1-9][0-9]*)$/.test(input.nextNonce)) {
+    throw new TypeError("Ledger returned an invalid next nonce");
+  }
+  const memo = input.memo?.trim();
+  const payload = {
+    version: 1,
+    action: "transfer",
+    chain: "ldgr-v1",
+    ledgerId: input.wallet.ledgerId,
+    asset: input.asset,
+    from: input.wallet.address,
+    to: recipient,
+    amount,
+    nonce: BigInt(input.nextNonce),
+    timestamp: BigInt((input.now ?? Date.now)()),
+    publicKey: input.wallet.publicKey,
+    ...memo ? { memo } : {},
+    ...input.metadata === undefined ? {} : { metadata: input.metadata },
+    ...input.encryptedMessage === undefined ? {} : { encryptedMessage: input.encryptedMessage }
+  };
+  const signature = await input.wallet.sign(payload);
+  return {
+    payload: {
+      ...payload,
+      amount: formatAtomicAmount(amount, input.assetDefinition),
+      nonce: payload.nonce.toString(),
+      timestamp: payload.timestamp.toString()
+    },
+    signature
+  };
+}
+
+// src/index.ts
+import {
+  decodeLdgr402Payment as decodeLdgr402Payment3,
+  decodeEd25519RecoveryKey as decodeEd25519RecoveryKey2,
+  decodeSilentPaymentCode,
+  deriveSilentPaymentIdentity as deriveSilentPaymentIdentity2,
+  deriveSilentPaymentSenderOutput,
+  nativeAssetDefinitionForLedger,
+  parseLdgr402Requirement as parseLdgr402Requirement3,
+  resolveLdgrNetwork as resolveLdgrNetwork2,
+  resolvePublicAssetCode
+} from "@ldgr/protocol";
+// src/ldgr402.ts
+import {
+  decodeLdgr402Payment,
+  parseLdgr402Requirement
+} from "@ldgr/protocol";
+import { decodeLdgr402Payment as decodeLdgr402Payment2, encodeLdgr402Payment, parseLdgr402Payment, parseLdgr402Requirement as parseLdgr402Requirement2 } from "@ldgr/protocol";
+function parseMerchantLdgr402Requirement(input, options = {}) {
+  return parseLdgr402Requirement(input, {
+    nowMs: options.nowMs,
+    allowExpired: true
+  });
+}
+function decodeMerchantLdgr402Payment(headerValue) {
+  return decodeLdgr402Payment(headerValue);
 }
 
 // src/index.ts
@@ -174,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 isNonceMismatch(error) {
+  return error instanceof LdgrClientError && error.code === "NONCE_MISMATCH";
+}
+function transferFailure(error) {
+  if (!(error instanceof LdgrClientError) || error.status !== 400 && error.status !== 409)
+    return;
+  return {
+    status: "failed",
+    error: error.message,
+    ...error.code === undefined ? {} : { code: error.code }
+  };
+}
 function createLdgrClient(options) {
   const transport = createTransport(options);
   const ledgerId = options.network === undefined ? undefined : resolveLdgrNetwork2(options.network);
@@ -224,6 +309,149 @@ function createLdgrClient(options) {
       reference: requirement.challenge
     });
   };
+  const sendTransfer = 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);
+    const assetDefinition = asset === "dng" ? nativeAssetDefinitionForLedger(input.wallet.ledgerId) : await transport.get(`/api/v1/assets/${encodePathSegment(asset)}`);
+    const submit = async () => {
+      const nonce = await transport.get(`/api/v1/nonces/${encodePathSegment(input.wallet.address)}/${encodePathSegment(asset)}`);
+      const submission = await buildTransferSubmission({
+        ...input,
+        asset,
+        assetDefinition,
+        nextNonce: nonce.nextNonce
+      });
+      const transaction = await transport.post("/api/v1/transfers", {
+        ...submission,
+        submittedAtMs: Date.now()
+      });
+      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;
+    }
+  };
+  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"),
@@ -293,14 +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/transfer.d.ts

@@ -0,0 +1,42 @@
+import { type AssetDefinition, type JsonValue } from "@ldgr/protocol";
+import type { LdgrSigner } from "./signer";
+import type { LdgrTransaction } from "./types";
+export type BuildTransferSubmissionInput = {
+    readonly wallet: LdgrSigner;
+    readonly asset: string;
+    readonly assetDefinition: AssetDefinition;
+    readonly amount: string;
+    readonly to: string;
+    readonly nextNonce: string;
+    readonly memo?: string;
+    readonly metadata?: JsonValue;
+    readonly encryptedMessage?: string;
+    readonly now?: () => number;
+};
+export type SendTransferInput = {
+    readonly wallet: LdgrSigner;
+    /** Public native id (`t0`/`t1`) or wire asset code. */
+    readonly asset: string;
+    readonly amount: string;
+    readonly to: string;
+    readonly memo?: string;
+    readonly metadata?: JsonValue;
+    readonly encryptedMessage?: string;
+    readonly now?: () => number;
+};
+export type LdgrTransferResult = {
+    readonly status: "settled";
+    readonly transactionHash: string;
+    readonly fee: string;
+    readonly feeAsset: string;
+    readonly transaction: LdgrTransaction;
+} | {
+    readonly status: "failed";
+    /** Settlement failures happen before append, so there is no hash or fee. */
+    readonly error: string;
+    readonly code?: string;
+};
+export declare function buildTransferSubmission(input: BuildTransferSubmissionInput): Promise<{
+    readonly payload: Record<string, unknown>;
+    readonly signature: string;
+}>;

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 = {
@@ -7,6 +8,8 @@ export type LdgrTransaction = {
     readonly to?: string;
     readonly asset?: string;
     readonly amount?: string;
+    readonly fee?: string;
+    readonly feeAsset?: string;
     readonly metadata?: unknown;
     readonly sequence?: string;
     readonly transactionHash: string;
@@ -73,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.3.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.3.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",