@ldgr/client 0.2.1 → 0.4.0

package/README.md

@@ -35,6 +35,38 @@ 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.
+
 ```ts
 import { createLdgrClient } from "@ldgr/client";
 
@@ -57,3 +89,24 @@ Only fulfil an order after `payment.status === "confirmed"`, and store the
 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.
+
+## LDGR402 merchant verification
+
+For a persisted LDGR402 requirement and the browser's
+`LDGR402-Payment` header, use the protocol-aware verifier:
+
+```ts
+const verification = await client.payments.verifyLdgr402(
+  request.headers.get("LDGR402-Payment") ?? "",
+  expectedRequirement,
+);
+
+if (verification.status === "confirmed") {
+  // Atomically fulfill the challenge using verification.transactionHash.
+}
+```
+
+`verifyLdgr402` checks the proof's ledger and challenge, rejects expired
+requirements, and verifies the exact settled transfer through the
+authoritative Worker. The merchant still owns challenge persistence and
+idempotent fulfillment.

package/dist/index.d.ts

@@ -1,4 +1,6 @@
-import { type LdgrClientOptions, type LdgrAsset, type LdgrTransaction, type PaymentExpectation, type PaymentVerification, type SignedSubmission } from "./types";
+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";
 export declare function createLdgrClient(options: LdgrClientOptions): {
     ledger: {
         get: () => Promise<{
@@ -24,6 +26,27 @@ 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;
+        }>;
+        listTransactions(address: string, options?: {
+            readonly before?: string;
+            readonly asset?: string;
+        }): Promise<LdgrAccountTransactionPage>;
     };
     assets: {
         get: (asset: string) => Promise<LdgrAsset>;
@@ -66,13 +89,22 @@ export declare function createLdgrClient(options: LdgrClientOptions): {
         }) => Promise<Record<string, unknown>>;
     };
     payments: {
-        verifyTransfer(transactionHash: string, expected: PaymentExpectation): Promise<PaymentVerification>;
+        verifyTransfer: (transactionHash: string, expected: PaymentExpectation) => Promise<PaymentVerification>;
+        verifyLdgr402: (proofHeader: string, requirementInput: Ldgr402Requirement, options?: {
+            readonly nowMs?: number;
+        }) => Promise<Ldgr402Verification>;
+    };
+    transfers: {
+        send: (input: SendTransferInput) => Promise<LdgrTransferResult>;
     };
     submitSigned: <T extends {
         readonly transactionHash?: string;
     }>(path: string, signed: SignedSubmission) => Promise<T>;
 };
 export { LdgrClientError } from "./types";
-export type { LdgrAsset, LdgrClientOptions, LdgrNetwork, LdgrTransaction, PaymentExpectation, PaymentVerification, SignedSubmission } 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 { buildTransferSubmission } from "./transfer";
+export type { BuildTransferSubmissionInput, LdgrTransferResult, SendTransferInput } from "./transfer";

package/dist/index.js

@@ -77,8 +77,76 @@ function queryPath(path, query) {
   return encoded ? `${path}?${encoded}` : path;
 }
 
+// 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 { resolveLdgrNetwork as resolveLdgrNetwork2, resolvePublicAssetCode } from "@ldgr/protocol";
+import {
+  decodeLdgr402Payment as decodeLdgr402Payment3,
+  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/signer.ts
 import {
   deriveAddress,
@@ -154,6 +222,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);
@@ -165,6 +245,96 @@ function createLdgrClient(options) {
     }
     return asset;
   };
+  const verifyTransfer = async (transactionHash, expected) => {
+    const hash = normalizedHash(transactionHash);
+    const expectedAsset = resolveAsset((expected.asset ?? "dng").trim() || "dng");
+    let transaction;
+    try {
+      transaction = await transport.get(`/api/v1/payments/v0.1/transactions/${hash}`);
+    } catch (error) {
+      if (error instanceof LdgrClientError && error.status === 404)
+        return { status: "not_found", transactionHash: hash };
+      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) {
+      return { status: "mismatch", transactionHash: hash };
+    }
+    return { status: "confirmed", transactionHash: hash, ...fields };
+  };
+  const verifyLdgr402 = async (proofHeader, requirementInput, options2 = {}) => {
+    const proof = decodeLdgr402Payment3(proofHeader);
+    const requirement = parseLdgr402Requirement3(requirementInput, {
+      nowMs: options2.nowMs,
+      allowExpired: true
+    });
+    const nowMs = options2.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) {
+      return { status: "mismatch", transactionHash: proof.transactionHash };
+    }
+    if (requirement.expiresAt <= nowMs) {
+      return { status: "expired", transactionHash: proof.transactionHash, challenge: requirement.challenge };
+    }
+    return verifyTransfer(proof.transactionHash, {
+      to: requirement.recipient,
+      asset: requirement.asset,
+      amount: requirement.amount,
+      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;
+    }
+  };
   return {
     ledger: {
       get: () => transport.get("/api/v1/ledger"),
@@ -173,7 +343,22 @@ function createLdgrClient(options) {
     accounts: {
       listBalances: (address) => transport.get(`/api/v1/balances/${encodePathSegment(address)}`),
       getBalance: (address, asset) => transport.get(`/api/v1/balances/${encodePathSegment(address)}/${encodePathSegment(resolveAsset(asset))}`),
-      getNextNonce: (address, asset) => transport.get(`/api/v1/nonces/${encodePathSegment(address)}/${encodePathSegment(resolveAsset(asset))}`)
+      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 = {}) {
+        const path = queryPath(`/api/v1/explorer/addresses/${encodePathSegment(address)}/transactions`, {
+          before: options2.before,
+          asset: options2.asset === undefined ? undefined : resolveAsset(options2.asset)
+        });
+        try {
+          return await transport.get(path);
+        } catch (error) {
+          if (error instanceof LdgrClientError && error.status === 404)
+            return { transactions: [] };
+          throw error;
+        }
+      }
     },
     assets: {
       get: (asset) => transport.get(`/api/v1/assets/${encodePathSegment(resolveAsset(asset))}`)
@@ -218,32 +403,18 @@ function createLdgrClient(options) {
       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 ?? {}))
     },
-    payments: {
-      async verifyTransfer(transactionHash, expected) {
-        const hash = normalizedHash(transactionHash);
-        const expectedAsset = resolveAsset((expected.asset ?? "dng").trim() || "dng");
-        let transaction;
-        try {
-          transaction = await transport.get(`/api/v1/payments/v0.1/transactions/${hash}`);
-        } catch (error) {
-          if (error instanceof LdgrClientError && error.status === 404)
-            return { status: "not_found", transactionHash: hash };
-          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) {
-          return { status: "mismatch", transactionHash: hash };
-        }
-        return { status: "confirmed", transactionHash: hash, ...fields };
-      }
-    },
-    submitSigned: (path, signed) => transport.post(path, signed)
+    payments: { verifyTransfer, verifyLdgr402 },
+    transfers: { send: sendTransfer },
+    submitSigned: (path, signed) => transport.post(path, { ...signed, submittedAtMs: Date.now() })
   };
 }
 export {
-  loadLocalWallet,
-  generateLocalWallet,
-  createWebCryptoSigner,
+  LdgrClientError,
+  buildTransferSubmission,
   createLdgrClient,
-  LdgrClientError
+  createWebCryptoSigner,
+  decodeMerchantLdgr402Payment,
+  generateLocalWallet,
+  loadLocalWallet,
+  parseMerchantLdgr402Requirement
 };

package/dist/ldgr402.d.ts

@@ -0,0 +1,10 @@
+import { type Ldgr402Requirement } from "@ldgr/protocol";
+export type { Ldgr402Requirement } from "@ldgr/protocol";
+export { decodeLdgr402Payment, encodeLdgr402Payment, parseLdgr402Payment, parseLdgr402Requirement } from "@ldgr/protocol";
+export type { Ldgr402ParseOptions, Ldgr402Payment } from "@ldgr/protocol";
+export type Ldgr402VerificationOptions = {
+    readonly nowMs?: number;
+};
+export declare function parseMerchantLdgr402Requirement(input: unknown, options?: Ldgr402VerificationOptions): Ldgr402Requirement;
+export declare function decodeMerchantLdgr402Payment(headerValue: string): import("@ldgr/protocol").Ldgr402Payment;
+export type { Ldgr402Verification } from "./types";

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

@@ -7,11 +7,30 @@ 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;
     readonly [key: string]: unknown;
 };
+export type LdgrAccountTransaction = {
+    readonly sequence: string;
+    readonly action: string;
+    readonly asset: string;
+    readonly from: string;
+    readonly to?: string;
+    readonly amount?: string;
+    readonly fee?: string;
+    readonly transactionHash: string;
+    readonly serverTimestamp: string;
+    readonly metadata?: unknown;
+    readonly encryptedMessage?: string;
+};
+export type LdgrAccountTransactionPage = {
+    readonly transactions: readonly LdgrAccountTransaction[];
+    readonly nextBefore?: string;
+};
 /** Public asset metadata used to format user-facing balances and transfer amounts. */
 export type LdgrAsset = {
     readonly code: string;
@@ -20,6 +39,11 @@ export type LdgrAsset = {
     readonly decimals: number;
     readonly active: boolean;
     readonly bridgePolicy: AssetBridgePolicy;
+    /** Optional operator-registered token logo. */
+    readonly iconUri?: string;
+    /** Ops-set display-only verification state. */
+    readonly verified?: boolean;
+    readonly verificationKind?: "official" | "partner";
     readonly [key: string]: unknown;
 };
 export type PaymentExpectation = {
@@ -39,10 +63,17 @@ export type PaymentVerification = {
     readonly status: "not_found" | "mismatch";
     readonly transactionHash: string;
 };
+export type Ldgr402Verification = PaymentVerification | {
+    readonly status: "expired";
+    readonly transactionHash: string;
+    readonly challenge: string;
+};
+export type { Ldgr402Requirement } from "@ldgr/protocol";
 export type SignedSubmission = {
     readonly payload: Record<string, unknown>;
     readonly signature: string;
     readonly feeSponsor?: unknown;
+    readonly submittedAtMs?: number;
 };
 export type LdgrClientOptions = {
     /** `testnet` / `0` or `mainnet` / `1`; required to use public native ids `t0` / `t1`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ldgr/client",
-  "version": "0.2.1",
+  "version": "0.4.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.2.0" },
+  "dependencies": { "@ldgr/protocol": "^0.4.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",
@@ -20,6 +20,6 @@
     "typecheck": "tsc -p tsconfig.json"
   },
   "devDependencies": {
-    "typescript": "^5.9.3"
+    "typescript": "^7.0.2"
   }
 }