@ldgr/client 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# LDGR client
+
+`@ldgr/client` is the transport and verification SDK for backend services and
+trading systems. It reads authoritative LDGR Worker state, verifies exact
+payments, and submits envelopes signed by a caller-owned signer or KMS.
+
+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.
+
+`generateLocalWallet()` creates caller-owned key material for a service wallet
+and returns its recovery key exactly to the caller. Store it in your own secret
+manager or HSM integration; never log it or send it to LDGR.
+
+```ts
+import { createLdgrClient } from "@ldgr/client";
+
+const client = createLdgrClient({ apiBase: "https://tst.ldgr.ltd" });
+const payment = await client.payments.verifyTransfer(transactionHash, {
+  to: merchantAddress,
+  asset: "dng",
+  amount: "2.50",
+});
+```
+
+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.

package/dist/client.d.ts

@@ -0,0 +1,8 @@
+import { type LdgrClientOptions } from "./types";
+export type Transport = {
+    readonly get: <T>(path: string) => Promise<T>;
+    readonly post: <T>(path: string, body: unknown) => Promise<T>;
+};
+export declare function createTransport(options: LdgrClientOptions): Transport;
+export declare function encodePathSegment(value: string): string;
+export declare function queryPath(path: string, query: Record<string, string | number | undefined>): string;

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+import { type LdgrClientOptions, type LdgrTransaction, type PaymentExpectation, type PaymentVerification, type SignedSubmission } from "./types";
+export declare function createLdgrClient(options: LdgrClientOptions): {
+    ledger: {
+        get: () => Promise<{
+            readonly ledgerId: 0 | 1;
+        }>;
+        getProtocolConfig: () => Promise<Record<string, unknown>>;
+    };
+    accounts: {
+        listBalances: (address: string) => Promise<{
+            readonly address: string;
+            readonly balances: readonly {
+                readonly asset: string;
+                readonly amount: string;
+            }[];
+        }>;
+        getBalance: (address: string, asset: string) => Promise<{
+            readonly address: string;
+            readonly asset: string;
+            readonly amount: string;
+        }>;
+        getNextNonce: (address: string, asset: string) => Promise<{
+            readonly address: string;
+            readonly asset: string;
+            readonly nextNonce: string;
+        }>;
+    };
+    transactions: {
+        get: (transactionHash: string) => Promise<LdgrTransaction>;
+    };
+    amm: {
+        listPools: () => Promise<{
+            readonly pools: readonly Record<string, unknown>[];
+        }>;
+        getPool: (poolId: string) => Promise<Record<string, unknown>>;
+        getPoolByPair: (assetA: string, assetB: string) => Promise<Record<string, unknown>>;
+        quoteSwap: (poolId: string, assetIn: string, amountIn: string) => Promise<Record<string, unknown>>;
+        quoteRoute: (assetIn: string, assetOut: string, amountIn: string, maxHops?: 1 | 2 | 3) => Promise<Record<string, unknown>>;
+    };
+    subscriptions: {
+        getPlan: (planId: string) => Promise<Record<string, unknown>>;
+        listPlans: (merchant: string) => Promise<{
+            readonly plans: readonly Record<string, unknown>[];
+        }>;
+        getEntitlement: (input: {
+            readonly payer: string;
+            readonly planId?: string;
+            readonly merchant?: string;
+            readonly tier?: string;
+        }) => Promise<Record<string, unknown>>;
+    };
+    objects: {
+        get(objectId: string): Promise<Record<string, unknown> | null>;
+        getByKey(namespace: string, key: string): Promise<Record<string, unknown> | null>;
+    };
+    usernames: {
+        get: (name: string) => Promise<Record<string, unknown>>;
+        getPrimary: (address: string) => Promise<Record<string, unknown>>;
+        listOwned: (address: string, options?: {
+            readonly cursor?: string;
+            readonly limit?: number;
+        }) => Promise<Record<string, unknown>>;
+    };
+    payments: {
+        verifyTransfer(transactionHash: string, expected: PaymentExpectation): Promise<PaymentVerification>;
+    };
+    submitSigned: <T extends {
+        readonly transactionHash?: string;
+    }>(path: string, signed: SignedSubmission) => Promise<T>;
+};
+export { LdgrClientError } from "./types";
+export type { LdgrClientOptions, LdgrTransaction, PaymentExpectation, PaymentVerification, SignedSubmission } from "./types";
+export { createWebCryptoSigner, generateLocalWallet } from "./signer";
+export type { LdgrSigner, LocalLdgrWallet } from "./signer";

package/dist/index.js

@@ -0,0 +1,216 @@
+// src/types.ts
+class LdgrClientError extends Error {
+  status;
+  code;
+  constructor(status, message, code) {
+    super(message);
+    this.name = "LdgrClientError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+// src/client.ts
+function normalizeApiBase(apiBase) {
+  const normalized = apiBase.trim().replace(/\/$/, "");
+  if (!/^https?:\/\//.test(normalized))
+    throw new TypeError("apiBase must be an absolute HTTP(S) URL");
+  return normalized;
+}
+function assertApiPath(path) {
+  if (!path.startsWith("/api/v1/") || path.includes("//") || path.includes("..")) {
+    throw new TypeError("path must be an /api/v1/ relative path");
+  }
+}
+async function parseJson(response) {
+  const body = await response.json().catch(() => {
+    return;
+  });
+  if (!response.ok) {
+    const message = typeof body?.error === "string" ? body.error : `LDGR request failed (${response.status})`;
+    const code = typeof body?.code === "string" ? body.code : undefined;
+    throw new LdgrClientError(response.status, message, code);
+  }
+  if (body === undefined || body === null || typeof body !== "object") {
+    throw new TypeError("LDGR response must be a JSON object");
+  }
+  return body;
+}
+function createTransport(options) {
+  const apiBase = normalizeApiBase(options.apiBase);
+  const request = options.fetch ?? globalThis.fetch;
+  if (typeof request !== "function")
+    throw new TypeError("fetch is required");
+  const call = async (path, init) => {
+    assertApiPath(path);
+    return parseJson(await request(`${apiBase}${path}`, init));
+  };
+  return {
+    get: (path) => call(path),
+    post: (path, body) => call(path, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body)
+    })
+  };
+}
+function encodePathSegment(value) {
+  return encodeURIComponent(value);
+}
+function queryPath(path, query) {
+  const search = new URLSearchParams;
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined)
+      search.set(key, String(value));
+  }
+  const encoded = search.toString();
+  return encoded ? `${path}?${encoded}` : path;
+}
+// src/signer.ts
+import {
+  deriveAddress,
+  encodeEd25519RecoveryKey,
+  exportEd25519PublicKey,
+  generateEd25519KeyPair,
+  signCanonicalPayload
+} from "@ldgr/protocol";
+function encodeBase64Url(bytes) {
+  let binary = "";
+  for (const byte of bytes)
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+async function createWebCryptoSigner(input) {
+  const publicKey = encodeBase64Url(await exportEd25519PublicKey(input.publicKey));
+  const address = await deriveAddress(input.publicKey, input.ledgerId);
+  return {
+    address,
+    publicKey,
+    ledgerId: input.ledgerId,
+    async sign(payload) {
+      if (payload.ledgerId !== input.ledgerId)
+        throw new TypeError("payload ledgerId does not match signer ledgerId");
+      if (payload.from !== address)
+        throw new TypeError("payload from does not match signer address");
+      if (payload.publicKey !== undefined && payload.publicKey !== publicKey) {
+        throw new TypeError("payload publicKey does not match signer publicKey");
+      }
+      return encodeBase64Url(await signCanonicalPayload(input.privateKey, { ...payload, publicKey }));
+    }
+  };
+}
+async function generateLocalWallet(input) {
+  const keyPair = await generateEd25519KeyPair();
+  const signer = await createWebCryptoSigner({ ...input, ...keyPair });
+  const privateKeyJwk = await globalThis.crypto.subtle.exportKey("jwk", keyPair.privateKey);
+  return {
+    ...signer,
+    recoveryKey: encodeEd25519RecoveryKey(privateKeyJwk)
+  };
+}
+
+// src/index.ts
+function normalizedHash(transactionHash) {
+  const hash = transactionHash.toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(hash))
+    throw new TypeError("transactionHash must be a 64-character hexadecimal hash");
+  return hash;
+}
+function sameDecimalAmount(actual, expected) {
+  const normalize = (value) => {
+    if (!/^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/.test(value))
+      return null;
+    const [whole, fraction = ""] = value.split(".");
+    return `${whole}.${fraction.replace(/0+$/, "") || "0"}`;
+  };
+  return normalize(actual) !== null && normalize(actual) === normalize(expected);
+}
+function paymentReference(metadata) {
+  if (metadata === null || typeof metadata !== "object" || Array.isArray(metadata))
+    return;
+  const value = metadata.paymentReference;
+  return typeof value === "string" ? value : undefined;
+}
+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 createLdgrClient(options) {
+  const transport = createTransport(options);
+  return {
+    ledger: {
+      get: () => transport.get("/api/v1/ledger"),
+      getProtocolConfig: () => transport.get("/api/v1/protocol/config")
+    },
+    accounts: {
+      listBalances: (address) => transport.get(`/api/v1/balances/${encodePathSegment(address)}`),
+      getBalance: (address, asset) => transport.get(`/api/v1/balances/${encodePathSegment(address)}/${encodePathSegment(asset)}`),
+      getNextNonce: (address, asset) => transport.get(`/api/v1/nonces/${encodePathSegment(address)}/${encodePathSegment(asset)}`)
+    },
+    transactions: {
+      get: (transactionHash) => transport.get(`/api/v1/transactions/${normalizedHash(transactionHash)}`)
+    },
+    amm: {
+      listPools: () => transport.get("/api/v1/amm/pools"),
+      getPool: (poolId) => transport.get(`/api/v1/amm/pools/${encodePathSegment(poolId)}`),
+      getPoolByPair: (assetA, assetB) => transport.get(`/api/v1/amm/pools/by-pair/${encodePathSegment(assetA)}/${encodePathSegment(assetB)}`),
+      quoteSwap: (poolId, assetIn, amountIn) => transport.get(queryPath(`/api/v1/amm/pools/${encodePathSegment(poolId)}/quote`, { assetIn, amountIn })),
+      quoteRoute: (assetIn, assetOut, amountIn, maxHops) => transport.get(queryPath("/api/v1/amm/routes/quote", { assetIn, assetOut, amountIn, maxHops }))
+    },
+    subscriptions: {
+      getPlan: (planId) => transport.get(`/api/v1/subscription-plans/${encodePathSegment(planId)}`),
+      listPlans: (merchant) => transport.get(queryPath("/api/v1/subscription-plans", { merchant })),
+      getEntitlement: (input) => transport.get(queryPath("/api/v1/subscriptions/entitlement", input))
+    },
+    objects: {
+      async get(objectId) {
+        try {
+          return await transport.get(`/api/v1/objects/${encodePathSegment(objectId)}`);
+        } catch (error) {
+          if (error instanceof LdgrClientError && error.status === 404)
+            return null;
+          throw error;
+        }
+      },
+      async getByKey(namespace, key) {
+        try {
+          return await transport.get(`/api/v1/objects/keys/${encodePathSegment(namespace)}/${encodePathSegment(key)}`);
+        } catch (error) {
+          if (error instanceof LdgrClientError && error.status === 404)
+            return null;
+          throw error;
+        }
+      }
+    },
+    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 ?? {}))
+    },
+    payments: {
+      async verifyTransfer(transactionHash, expected) {
+        const hash = normalizedHash(transactionHash);
+        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);
+        const expectedAsset = (expected.asset ?? "dng").trim() || "dng";
+        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)
+  };
+}
+export {
+  generateLocalWallet,
+  createWebCryptoSigner,
+  createLdgrClient,
+  LdgrClientError
+};

package/dist/signer.d.ts

@@ -0,0 +1,19 @@
+import { type LedgerId } from "@ldgr/protocol";
+export interface LdgrSigner {
+    readonly address: string;
+    readonly publicKey: string;
+    readonly ledgerId: LedgerId;
+    sign(payload: Record<string, unknown>): Promise<string>;
+}
+export interface LocalLdgrWallet extends LdgrSigner {
+    /** Store this only in the caller's chosen secret manager; it is never sent to LDGR. */
+    readonly recoveryKey: string;
+}
+export declare function createWebCryptoSigner(input: {
+    readonly ledgerId: LedgerId;
+    readonly privateKey: CryptoKey;
+    readonly publicKey: CryptoKey;
+}): Promise<LdgrSigner>;
+export declare function generateLocalWallet(input: {
+    readonly ledgerId: LedgerId;
+}): Promise<LocalLdgrWallet>;

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export type LedgerId = 0 | 1;
+export type LdgrTransaction = {
+    readonly action: string;
+    readonly from?: string;
+    readonly to?: string;
+    readonly asset?: string;
+    readonly amount?: string;
+    readonly metadata?: unknown;
+    readonly sequence?: string;
+    readonly transactionHash: string;
+    readonly [key: string]: unknown;
+};
+export type PaymentExpectation = {
+    readonly to: string;
+    readonly asset?: string;
+    readonly amount: string;
+    readonly reference?: string;
+};
+export type PaymentVerification = {
+    readonly status: "confirmed";
+    readonly transactionHash: string;
+    readonly from: string;
+    readonly to: string;
+    readonly asset: string;
+    readonly amount: string;
+} | {
+    readonly status: "not_found" | "mismatch";
+    readonly transactionHash: string;
+};
+export type SignedSubmission = {
+    readonly payload: Record<string, unknown>;
+    readonly signature: string;
+    readonly feeSponsor?: unknown;
+};
+export type LdgrClientOptions = {
+    readonly apiBase: string;
+    readonly fetch?: typeof globalThis.fetch;
+};
+export type LdgrClientErrorBody = {
+    readonly error?: unknown;
+    readonly code?: unknown;
+};
+export declare class LdgrClientError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    constructor(status: number, message: string, code: string | undefined);
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@ldgr/client",
+  "version": "0.1.0",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "publishConfig": {
+  "access": "public"
+},
+"engines": {
+"node": ">=20.19.0"
+},
+"dependencies": {
+"@ldgr/protocol": "^0.1.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"
+}
+}