@ldgr/client 0.6.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.
@@ -214,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,3 +1,11 @@
+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 CheckoutPaymentExpectation, type CheckoutPaymentVerification, type MerchantPaymentExpectation, type MerchantPaymentVerification, type PaymentSubmission, type SignedSubmission, type SilentPaymentSendInput, type SilentPaymentScanPage, type WalletPublicKeyRecord, type WalletPublicKeyRegistration } from "./types";
@@ -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;

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" },
@@ -516,6 +519,23 @@ 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))}`),
@@ -577,6 +597,7 @@ function createLdgrClient(options) {
     usernames: {
       get: (name) => transport.get(`/api/v1/usernames/${encodePathSegment(name)}`),
       getPrimary: (address) => transport.get(`/api/v1/usernames/by-address/${encodePathSegment(address)}`),
+      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, verifyCheckout, verifyPayment, verifyLdgr402 },

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";
@@ -104,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";
@@ -161,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;
@@ -172,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.6.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"
   }
 }