@ldgr/client 0.5.0 → 0.6.1

package/README.md

@@ -8,6 +8,22 @@ It does not create a hosted wallet, persist a private key, or replace the
 browser extension. Use `@ldgr/wallet-sdk` when a website needs an explicit
 user confirmation in the LDGR extension.
 
+## Contract reads
+
+Version `0.6.1` publishes `getLedraContract`, `getMilestoneEscrow`,
+`getAtomicOffer`, and `getClaimDistribution`, together with their typed mutation
+methods. It requires `@ldgr/protocol@^0.5.1` for the corresponding payload types.
+Version `0.6.0` does not include these methods. Upgrade the installed client and
+restart consumers before using these contract APIs.
+
+## Primary usernames
+
+`client.usernames.findPrimary(address)` returns the primary username record or
+`null` when the address has no active primary username. It uses the optional
+lookup endpoint (`?optional=true`); lookup and transport failures still throw.
+`client.usernames.getPrimary(address)` keeps the required lookup behavior and
+throws on the endpoint's default 404 when no primary username exists.
+
 ## Service wallets and recovery keys
 
 `generateLocalWallet()` creates caller-owned key material for a service wallet.
@@ -67,9 +83,10 @@ 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
+## Confidential payments
 
-`silentPayments.send()` accepts a reusable LDGR payment code and a
+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;
@@ -112,8 +129,9 @@ 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
+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
@@ -139,6 +157,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
@@ -159,3 +230,67 @@ if (verification.status === "confirmed") {
 requirements, and verifies the exact settled transfer through the
 authoritative Worker. The merchant still owns challenge persistence and
 idempotent fulfillment.
+
+## Caller-signed atomic offers
+
+`getAtomicOffer(contractId)` reads the authoritative fixed-counterparty offer.
+`openAtomicOffer`, `acceptAtomicOffer`, `cancelAtomicOffer` and `refundAtomicOffer`
+submit typed caller-signed envelopes and return canonical terms plus the committed
+action's `transactionHash`. The four submission types are exported as
+`AtomicOfferOpenSubmission`, `AtomicOfferAcceptSubmission`,
+`AtomicOfferCancelSubmission` and `AtomicOfferRefundSubmission`.
+
+```ts
+const offer = await client.getAtomicOffer(contractId);
+const receipt = await client.acceptAtomicOffer(callerSignedAcceptance);
+```
+
+Sign the protocol's canonical payload using bigint atomic amounts, then transport
+each traded amount as an exact decimal string using that asset's registry
+decimals. `maxFeeAtomic` is an atomic integer string; nonce, timestamp and expiry
+are integer strings. Preserve exact asset codes, signature, fields and original
+open payload hash. These methods forward the supplied envelope unchanged and do
+not sign, resolve aliases, replace nonces or automatically retry. A timeout leaves
+the submission status unknown: read the offer or retry the identical signed
+submission. Exact committed retries return the original action hash, even if a
+later action changed the offer's status.
+
+This is the protocol/API/client foundation. First-party wallet provider methods,
+confirmation screens, offer-detail pages and a Utilities builder are deferred.
+
+## Caller-signed milestone escrow
+
+`getMilestoneEscrow(contractId)` reads the canonical prepaid escrow.
+`openMilestoneEscrow(signed)`, `releaseMilestoneEscrow(signed)` and
+`refundMilestoneEscrow(signed)` submit typed caller-signed envelopes unchanged.
+Opening `amount` and every `milestones[].amount` are exact decimal strings in
+the escrow asset. Nonce, timestamp, expiry and native `maxFeeAtomic` are integer
+strings; release `milestoneIndex` is a zero-based integer number. Every action
+uses the actual escrow asset and its payer nonce lane.
+
+Only the payer can release the next step before expiry or refund the residual
+at or after expiry. Records include `releasedMilestones`, `releasedAmount`,
+`remainingAmount` and `refundedAmount`; released payments remain final.
+These methods never sign or rebuild submissions and never retry automatically.
+After an ambiguous submission, reconcile canonical state and preserve the exact
+signed envelope when retrying.
+
+## Caller-signed claim distributions
+
+`getClaimDistribution(contractId)` reads the canonical prepaid distribution.
+`openClaimDistribution(signed)`, `claimClaimDistribution(signed)` and
+`refundClaimDistribution(signed)` forward typed caller-signed envelopes unchanged.
+Opening `amount` and `allocations[].amount` are exact asset decimal strings over
+HTTP; sign their protocol equivalents as bigint atomic amounts. Nonce, timestamp,
+expiry and opening `maxFeeAtomic` use integer strings. Every action uses the exact
+distribution asset and the signing account's nonce lane.
+
+Opening allocates the total to 1–64 unique recipients other than the funder.
+Each recipient can claim its complete zero-based `claimIndex` once before expiry,
+in any order. Claims and refunds require the original `openPayloadHash`; only the
+funder can refund unclaimed funds at or after expiry. Opening pays a capped native
+fee; settlement is fee-free and supports known inactive assets. Records expose
+per-allocation `claimed` flags, `claimedAllocations`, `claimedAmount`,
+`remainingAmount` and `refundedAmount`. Mutations return the committed
+`transactionHash`. These methods never sign, replace nonces or automatically
+retry: preserve the exact signed envelope after an unknown outcome.

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 import { type LdgrClientOptions } from "./types";
 export type Transport = {
     readonly get: <T>(path: string) => Promise<T>;
+    readonly getOptional: <T>(path: string) => Promise<T | null>;
     readonly post: <T>(path: string, body: unknown) => Promise<T>;
 };
 export declare function createTransport(options: LdgrClientOptions): Transport;

package/dist/index.d.ts

@@ -1,6 +1,14 @@
+import type { LedraContractDeploySubmission, LedraContractInvokeSubmission, LedraContractRefundSubmission } from "./types";
+export type { LedraContractDeploySubmission, LedraContractInvokeSubmission, LedraContractRefundSubmission, LdgrLedraContract, LdgrLedraContractMutation } from "./types";
+import type { ClaimDistributionOpenSubmission, ClaimDistributionClaimSubmission, ClaimDistributionRefundSubmission, LdgrClaimDistribution, LdgrClaimDistributionMutation } from "./types";
+export type { ClaimDistributionOpenSubmission, ClaimDistributionClaimSubmission, ClaimDistributionRefundSubmission, LdgrClaimDistribution, LdgrClaimDistributionMutation } from "./types";
+import type { MilestoneEscrowOpenSubmission, MilestoneEscrowReleaseSubmission, MilestoneEscrowRefundSubmission, LdgrMilestoneEscrow, LdgrMilestoneEscrowMutation } from "./types";
+export type { MilestoneEscrowOpenSubmission, MilestoneEscrowReleaseSubmission, MilestoneEscrowRefundSubmission, LdgrMilestoneEscrow, LdgrMilestoneEscrowMutation } from "./types";
+import type { AtomicOfferOpenSubmission, AtomicOfferAcceptSubmission, AtomicOfferCancelSubmission, AtomicOfferRefundSubmission, LdgrAtomicOffer, LdgrAtomicOfferMutation } from "./types";
+export type { AtomicOfferOpenSubmission, AtomicOfferAcceptSubmission, AtomicOfferCancelSubmission, AtomicOfferRefundSubmission, LdgrAtomicOffer, LdgrAtomicOfferMutation } 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";
+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<{
@@ -8,6 +16,23 @@ export declare function createLdgrClient(options: LdgrClientOptions): {
         }>;
         getProtocolConfig: () => Promise<Record<string, unknown>>;
     };
+    getClaimDistribution: (contractId: string) => Promise<LdgrClaimDistribution>;
+    openClaimDistribution: (signed: ClaimDistributionOpenSubmission) => Promise<LdgrClaimDistributionMutation>;
+    claimClaimDistribution: (signed: ClaimDistributionClaimSubmission) => Promise<LdgrClaimDistributionMutation>;
+    refundClaimDistribution: (signed: ClaimDistributionRefundSubmission) => Promise<LdgrClaimDistributionMutation>;
+    getLedraContract: (id: string) => Promise<import("@ldgr/protocol").LedraContractRecord>;
+    deployLedraContract: (signed: LedraContractDeploySubmission) => Promise<import("@ldgr/protocol").LedraContractMutation>;
+    invokeLedraContract: (signed: LedraContractInvokeSubmission) => Promise<import("@ldgr/protocol").LedraContractMutation>;
+    refundLedraContract: (signed: LedraContractRefundSubmission) => Promise<import("@ldgr/protocol").LedraContractMutation>;
+    getMilestoneEscrow: (contractId: string) => Promise<LdgrMilestoneEscrow>;
+    openMilestoneEscrow: (signed: MilestoneEscrowOpenSubmission) => Promise<LdgrMilestoneEscrowMutation>;
+    releaseMilestoneEscrow: (signed: MilestoneEscrowReleaseSubmission) => Promise<LdgrMilestoneEscrowMutation>;
+    refundMilestoneEscrow: (signed: MilestoneEscrowRefundSubmission) => Promise<LdgrMilestoneEscrowMutation>;
+    getAtomicOffer: (contractId: string) => Promise<LdgrAtomicOffer>;
+    openAtomicOffer: (signed: AtomicOfferOpenSubmission) => Promise<LdgrAtomicOfferMutation>;
+    acceptAtomicOffer: (signed: AtomicOfferAcceptSubmission) => Promise<LdgrAtomicOfferMutation>;
+    cancelAtomicOffer: (signed: AtomicOfferCancelSubmission) => Promise<LdgrAtomicOfferMutation>;
+    refundAtomicOffer: (signed: AtomicOfferRefundSubmission) => Promise<LdgrAtomicOfferMutation>;
     accounts: {
         listBalances: (address: string) => Promise<{
             readonly address: string;
@@ -68,6 +93,7 @@ export declare function createLdgrClient(options: LdgrClientOptions): {
     usernames: {
         get: (name: string) => Promise<Record<string, unknown>>;
         getPrimary: (address: string) => Promise<Record<string, unknown>>;
+        findPrimary: (address: string) => Promise<Record<string, unknown> | null>;
         listOwned: (address: string, options?: {
             readonly cursor?: string;
             readonly limit?: number;
@@ -75,6 +101,8 @@ 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>;
@@ -93,7 +121,7 @@ export declare function createLdgrClient(options: LdgrClientOptions): {
 };
 export { LdgrClientError, SilentPaymentSubmissionUnknownError } from "./types";
 export { decodeMerchantLdgr402Payment, parseMerchantLdgr402Requirement } from "./ldgr402";
-export type { LdgrAccountTransaction, LdgrAccountTransactionPage, Ldgr402Requirement, Ldgr402Verification, LdgrAsset, LdgrClientOptions, LdgrNetwork, LdgrTransaction, PaymentExpectation, PaymentVerification, SignedSubmission, SilentPaymentScanPage, SilentPaymentScanRecord, SilentPaymentSendInput, WalletPublicKeyRecord, WalletPublicKeyRegistration } from "./types";
+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";

package/dist/index.js

@@ -41,7 +41,7 @@ function assertApiPath(path) {
     throw new TypeError("path must be an /api/v1/ relative path");
   }
 }
-async function parseJson(response) {
+async function parseJson(response, allowNull = false) {
   const body = await response.json().catch(() => {
     return;
   });
@@ -50,6 +50,8 @@ async function parseJson(response) {
     const code = typeof body?.code === "string" ? body.code : undefined;
     throw new LdgrClientError(response.status, message, code);
   }
+  if (body === null && allowNull)
+    return body;
   if (body === undefined || body === null || typeof body !== "object") {
     throw new TypeError("LDGR response must be a JSON object");
   }
@@ -60,12 +62,13 @@ function createTransport(options) {
   const request = options.fetch ?? globalThis.fetch;
   if (typeof request !== "function")
     throw new TypeError("fetch is required");
-  const call = async (path, init) => {
+  const call = async (path, init, allowNull = false) => {
     assertApiPath(path);
-    return parseJson(await request(`${apiBase}${path}`, init));
+    return parseJson(await request(`${apiBase}${path}`, init), allowNull);
   };
   return {
     get: (path) => call(path),
+    getOptional: (path) => call(path, undefined, true),
     post: (path, body) => call(path, {
       method: "POST",
       headers: { "content-type": "application/json" },
@@ -225,7 +228,7 @@ function decodeMerchantLdgr402Payment(headerValue) {
 // 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;
 }
@@ -247,6 +250,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";
 }
@@ -282,18 +297,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) {
@@ -348,9 +410,9 @@ 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;
         }
       }
@@ -440,9 +502,9 @@ 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;
         }
       }
@@ -457,16 +519,33 @@ function createLdgrClient(options) {
       get: () => transport.get("/api/v1/ledger"),
       getProtocolConfig: () => transport.get("/api/v1/protocol/config")
     },
+    getClaimDistribution: (contractId) => transport.get(`/api/v1/contracts/claim-distributions/${encodePathSegment(contractId)}`),
+    openClaimDistribution: (signed) => transport.post("/api/v1/contracts/claim-distributions", signed),
+    claimClaimDistribution: (signed) => transport.post(`/api/v1/contracts/claim-distributions/${encodePathSegment(signed.payload.contractId)}/claim`, signed),
+    refundClaimDistribution: (signed) => transport.post(`/api/v1/contracts/claim-distributions/${encodePathSegment(signed.payload.contractId)}/refund`, signed),
+    getLedraContract: (id) => transport.get(`/api/v1/contracts/programs/${encodePathSegment(id)}`),
+    deployLedraContract: (signed) => transport.post("/api/v1/contracts/programs", signed),
+    invokeLedraContract: (signed) => transport.post(`/api/v1/contracts/programs/${encodePathSegment(signed.payload.contractId)}/invoke`, signed),
+    refundLedraContract: (signed) => transport.post(`/api/v1/contracts/programs/${encodePathSegment(signed.payload.contractId)}/refund`, signed),
+    getMilestoneEscrow: (contractId) => transport.get(`/api/v1/contracts/milestone-escrows/${encodePathSegment(contractId)}`),
+    openMilestoneEscrow: (signed) => transport.post("/api/v1/contracts/milestone-escrows", signed),
+    releaseMilestoneEscrow: (signed) => transport.post(`/api/v1/contracts/milestone-escrows/${encodePathSegment(signed.payload.contractId)}/release`, signed),
+    refundMilestoneEscrow: (signed) => transport.post(`/api/v1/contracts/milestone-escrows/${encodePathSegment(signed.payload.contractId)}/refund`, signed),
+    getAtomicOffer: (contractId) => transport.get(`/api/v1/contracts/atomic-offers/${encodePathSegment(contractId)}`),
+    openAtomicOffer: (signed) => transport.post("/api/v1/contracts/atomic-offers", signed),
+    acceptAtomicOffer: (signed) => transport.post(`/api/v1/contracts/atomic-offers/${encodePathSegment(signed.payload.contractId)}/accept`, signed),
+    cancelAtomicOffer: (signed) => transport.post(`/api/v1/contracts/atomic-offers/${encodePathSegment(signed.payload.contractId)}/cancel`, signed),
+    refundAtomicOffer: (signed) => transport.post(`/api/v1/contracts/atomic-offers/${encodePathSegment(signed.payload.contractId)}/refund`, signed),
     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))}`),
       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);
@@ -518,9 +597,10 @@ 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 ?? {}))
+      findPrimary: (address) => transport.getOptional(`/api/v1/usernames/by-address/${encodePathSegment(address)}?optional=true`),
+      listOwned: (address, options) => transport.get(queryPath(`/api/v1/usernames/owned-by/${encodePathSegment(address)}`, options ?? {}))
     },
-    payments: { verifyTransfer, verifyLdgr402 },
+    payments: { verifyTransfer, verifyCheckout, verifyPayment, verifyLdgr402 },
     silentPayments: {
       scan: (after = "0", limit) => transport.get(queryPath("/api/v1/silent-payments/scan", { after, limit })),
       send: sendSilentPayment,

package/dist/types.d.ts

@@ -1,4 +1,7 @@
-import type { AssetBridgePolicy, LdgrNetwork } from "@ldgr/protocol";
+import type { LedraContractDeployPayload, LedraContractInvokePayload, LedraContractRefundPayload, LedraContractRecord, LedraContractMutation } from '@ldgr/protocol';
+import type { ClaimDistributionOpenPayload, ClaimDistributionClaimPayload, ClaimDistributionRefundPayload } from "@ldgr/protocol";
+import type { MilestoneEscrowOpenPayload, MilestoneEscrowReleasePayload, MilestoneEscrowRefundPayload } from "@ldgr/protocol";
+import type { AssetBridgePolicy, LdgrNetwork, AtomicOfferOpenPayload, AtomicOfferAcceptPayload, AtomicOfferCancelPayload, AtomicOfferRefundPayload } from "@ldgr/protocol";
 import type { LocalLdgrWallet } from "./signer";
 export type LedgerId = 0 | 1;
 export type { LdgrNetwork } from "@ldgr/protocol";
@@ -64,6 +67,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;
@@ -76,6 +107,38 @@ export type SignedSubmission = {
     readonly feeSponsor?: unknown;
     readonly submittedAtMs?: number;
 };
+/** HTTP amounts are exact decimals; nonce/time/cap fields are integer strings. */
+type AtomicOfferWire<T> = {
+    readonly [K in keyof T]: T[K] extends bigint ? string : T[K];
+};
+type AtomicOfferSubmission<T> = Omit<SignedSubmission, "payload" | "feeSponsor"> & {
+    readonly payload: AtomicOfferWire<T>;
+};
+export type AtomicOfferOpenSubmission = AtomicOfferSubmission<AtomicOfferOpenPayload>;
+export type AtomicOfferAcceptSubmission = AtomicOfferSubmission<AtomicOfferAcceptPayload>;
+export type AtomicOfferCancelSubmission = AtomicOfferSubmission<AtomicOfferCancelPayload>;
+export type AtomicOfferRefundSubmission = AtomicOfferSubmission<AtomicOfferRefundPayload>;
+export type LdgrAtomicOffer = {
+    readonly contractId: string;
+    readonly template: "atomic_offer_v1";
+    readonly maker: string;
+    readonly taker: string;
+    readonly offeredAsset: string;
+    readonly offeredAmount: string;
+    readonly requestedAsset: string;
+    readonly requestedAmount: string;
+    readonly expiresAt: string;
+    readonly status: "open" | "accepted" | "cancelled" | "refunded";
+    readonly expired: boolean;
+    readonly openPayloadHash: string;
+    readonly reference?: string;
+    readonly createdTransactionHash: string;
+    readonly latestTransactionHash: string;
+    readonly terminalTransactionHash?: string;
+};
+export type LdgrAtomicOfferMutation = LdgrAtomicOffer & {
+    readonly transactionHash: string;
+};
 export type WalletPublicKeyRegistration = {
     readonly version: 1;
     readonly action: "wallet_key_register";
@@ -133,7 +196,8 @@ export type LdgrClientOptions = {
     readonly network?: LdgrNetwork;
     /** Defaults to the canonical public origin when `network` is supplied. */
     readonly apiBase?: string;
-    readonly fetch?: typeof globalThis.fetch;
+    /** A Fetch-compatible function; runtime-specific helper properties are not required. */
+    readonly fetch?: (...args: Parameters<typeof globalThis.fetch>) => ReturnType<typeof globalThis.fetch>;
 };
 export type LdgrClientErrorBody = {
     readonly error?: unknown;
@@ -144,3 +208,76 @@ export declare class LdgrClientError extends Error {
     readonly code: string | undefined;
     constructor(status: number, message: string, code: string | undefined);
 }
+/** Atomic payload amounts become exact asset decimals over HTTP, including nested steps. */
+type ContractSignedWire<T> = T extends bigint ? string : T extends readonly (infer U)[] ? readonly ContractSignedWire<U>[] : T extends object ? {
+    readonly [K in keyof T]: ContractSignedWire<T[K]>;
+} : T;
+type ContractSignedSubmission<T> = Omit<SignedSubmission, "payload" | "feeSponsor"> & {
+    readonly payload: ContractSignedWire<T>;
+};
+export type MilestoneEscrowOpenSubmission = ContractSignedSubmission<MilestoneEscrowOpenPayload>;
+export type MilestoneEscrowReleaseSubmission = ContractSignedSubmission<MilestoneEscrowReleasePayload>;
+export type MilestoneEscrowRefundSubmission = ContractSignedSubmission<MilestoneEscrowRefundPayload>;
+export type LdgrMilestoneEscrow = {
+    readonly contractId: string;
+    readonly template: "milestone_escrow_v1";
+    readonly payer: string;
+    readonly beneficiary: string;
+    readonly asset: string;
+    readonly amount: string;
+    readonly milestones: readonly {
+        readonly label: string;
+        readonly amount: string;
+    }[];
+    readonly releasedMilestones: number;
+    readonly releasedAmount: string;
+    readonly remainingAmount: string;
+    readonly refundedAmount: string;
+    readonly expiresAt: string;
+    readonly expired: boolean;
+    readonly status: "open" | "completed" | "refunded";
+    readonly openPayloadHash: string;
+    readonly reference?: string;
+    readonly createdTransactionHash: string;
+    readonly latestTransactionHash: string;
+    readonly terminalTransactionHash?: string;
+};
+export type LdgrMilestoneEscrowMutation = LdgrMilestoneEscrow & {
+    readonly transactionHash: string;
+};
+/** Atomic payload amounts become exact asset decimals over HTTP, including nested steps. */
+export type ClaimDistributionOpenSubmission = ContractSignedSubmission<ClaimDistributionOpenPayload>;
+export type ClaimDistributionClaimSubmission = ContractSignedSubmission<ClaimDistributionClaimPayload>;
+export type ClaimDistributionRefundSubmission = ContractSignedSubmission<ClaimDistributionRefundPayload>;
+export type LdgrClaimDistribution = {
+    readonly contractId: string;
+    readonly template: "claim_distribution_v1";
+    readonly funder: string;
+    readonly asset: string;
+    readonly amount: string;
+    readonly allocations: readonly {
+        readonly to: string;
+        readonly amount: string;
+        readonly claimed: boolean;
+    }[];
+    readonly claimedAllocations: number;
+    readonly claimedAmount: string;
+    readonly remainingAmount: string;
+    readonly refundedAmount: string;
+    readonly expiresAt: string;
+    readonly expired: boolean;
+    readonly status: "open" | "completed" | "refunded";
+    readonly openPayloadHash: string;
+    readonly reference?: string;
+    readonly createdTransactionHash: string;
+    readonly latestTransactionHash: string;
+    readonly terminalTransactionHash?: string;
+};
+export type LdgrClaimDistributionMutation = LdgrClaimDistribution & {
+    readonly transactionHash: string;
+};
+export type LedraContractDeploySubmission = ContractSignedSubmission<LedraContractDeployPayload>;
+export type LedraContractInvokeSubmission = ContractSignedSubmission<LedraContractInvokePayload>;
+export type LedraContractRefundSubmission = ContractSignedSubmission<LedraContractRefundPayload>;
+export type LdgrLedraContract = LedraContractRecord;
+export type LdgrLedraContractMutation = LedraContractMutation;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ldgr/client",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -12,14 +12,14 @@
   "files": ["dist", "README.md"],
   "publishConfig": { "access": "public" },
   "engines": { "node": ">=20.19.0" },
-  "dependencies": { "@ldgr/protocol": "^0.5.0" },
+  "dependencies": { "@ldgr/protocol": "^0.5.1" },
   "scripts": {
-    "build": "rm -rf dist && bun build src/index.ts --outdir dist --target node --format esm --packages external && tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && bun build src/index.ts --outdir dist --target node --format esm --packages external && tsrs -p tsconfig.build.json",
     "prepack": "bun run build",
     "test": "bun test",
-    "typecheck": "tsc -p tsconfig.json"
+    "typecheck": "tsrs --noEmit -p tsconfig.json && tsrs --noEmit -p test/tsconfig.json"
   },
   "devDependencies": {
-    "typescript": "^7.0.2"
+    "tsrs": "0.20.0-ts7.1.0-beta"
   }
 }