@ldgr/client 0.2.0 → 0.3.0

package/README.md

@@ -57,3 +57,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,5 @@
-import { type LdgrClientOptions, type LdgrTransaction, type PaymentExpectation, type PaymentVerification, type SignedSubmission } from "./types";
+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,13 +25,38 @@ 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>;
     };
     transactions: {
         get: (transactionHash: string) => Promise<LdgrTransaction>;
     };
     amm: {
-        listPools: () => Promise<{
+        listPools: (cursor?: string, limit?: number) => Promise<{
             readonly pools: readonly Record<string, unknown>[];
+            readonly nextCursor?: string;
         }>;
         getPool: (poolId: string) => Promise<Record<string, unknown>>;
         getPoolByPair: (assetA: string, assetB: string) => Promise<Record<string, unknown>>;
@@ -62,13 +88,17 @@ 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>;
     };
     submitSigned: <T extends {
         readonly transactionHash?: string;
     }>(path: string, signed: SignedSubmission) => Promise<T>;
 };
 export { LdgrClientError } from "./types";
-export type { 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";

package/dist/index.js

@@ -78,7 +78,27 @@ function queryPath(path, query) {
 }
 
 // src/index.ts
-import { resolveLdgrNetwork as resolveLdgrNetwork2, resolvePublicAssetCode } from "@ldgr/protocol";
+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,
@@ -165,6 +185,45 @@ 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
+    });
+  };
   return {
     ledger: {
       get: () => transport.get("/api/v1/ledger"),
@@ -173,13 +232,31 @@ 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))}`)
     },
     transactions: {
       get: (transactionHash) => transport.get(`/api/v1/transactions/${normalizedHash(transactionHash)}`)
     },
     amm: {
-      listPools: () => transport.get("/api/v1/amm/pools"),
+      listPools: (cursor, limit) => transport.get(queryPath("/api/v1/amm/pools", { cursor, limit })),
       getPool: (poolId) => transport.get(`/api/v1/amm/pools/${encodePathSegment(poolId)}`),
       getPoolByPair: (assetA, assetB) => transport.get(`/api/v1/amm/pools/by-pair/${encodePathSegment(resolveAsset(assetA))}/${encodePathSegment(resolveAsset(assetB))}`),
       quoteSwap: (poolId, assetIn, amountIn) => transport.get(queryPath(`/api/v1/amm/pools/${encodePathSegment(poolId)}/quote`, { assetIn: resolveAsset(assetIn), amountIn })),
@@ -215,32 +292,16 @@ 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 },
+    submitSigned: (path, signed) => transport.post(path, { ...signed, submittedAtMs: Date.now() })
   };
 }
 export {
-  loadLocalWallet,
-  generateLocalWallet,
-  createWebCryptoSigner,
+  LdgrClientError,
   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/types.d.ts

@@ -1,4 +1,4 @@
-import type { LdgrNetwork } from "@ldgr/protocol";
+import type { AssetBridgePolicy, LdgrNetwork } from "@ldgr/protocol";
 export type LedgerId = 0 | 1;
 export type { LdgrNetwork } from "@ldgr/protocol";
 export type LdgrTransaction = {
@@ -12,6 +12,38 @@ export type LdgrTransaction = {
     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;
+    readonly displayName: string;
+    readonly ticker?: string;
+    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 = {
     readonly to: string;
     readonly asset?: string;
@@ -29,10 +61,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.0",
+  "version": "0.3.0",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -10,19 +10,16 @@
     }
   },
   "files": ["dist", "README.md"],
-  "publishConfig": {
-  "access": "public"
-},
-"engines": {
-"node": ">=20.19.0"
-},
-"dependencies": {
-"@ldgr/protocol": "^0.2.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",
-  "test": "bun test",
-  "typecheck": "tsc -p tsconfig.json"
-}
+  "publishConfig": { "access": "public" },
+  "engines": { "node": ">=20.19.0" },
+  "dependencies": { "@ldgr/protocol": "^0.3.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",
+    "test": "bun test",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  }
 }