@ldgr/client 0.1.0 → 0.2.0

package/README.md

@@ -8,21 +8,51 @@ 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.
+## Service wallets and recovery keys
+
+`generateLocalWallet()` creates caller-owned key material for a service wallet.
+Save its recovery key directly to your secret manager exactly once, then use
+`loadLocalWallet()` on service startup to recreate the signer. The recovery key
+is bearer private-key material: never log, commit, pass it in arguments or
+browser storage, send it to LDGR, or use it for a customer wallet.
+
+```ts
+import { generateLocalWallet, loadLocalWallet } from "@ldgr/client";
+
+// Provision once. `secretStore` represents your secret-manager or HSM workflow.
+const created = await generateLocalWallet({ ledgerId: 1 });
+await secretStore.writeOnce("ldgr-service-wallet", created.recoveryKey);
+
+// On each service startup, recover the same signer without printing the key.
+const serviceWallet = await loadLocalWallet({
+  ledgerId: 1,
+  recoveryKey: await secretStore.read("ldgr-service-wallet"),
+});
+
+console.log(serviceWallet.address); // safe to identify the service wallet
+```
+
+This is for backend/Bun service wallets only. Websites should use
+`@ldgr/wallet-sdk` and an extension-confirmed customer wallet instead.
 
 ```ts
 import { createLdgrClient } from "@ldgr/client";
 
-const client = createLdgrClient({ apiBase: "https://tst.ldgr.ltd" });
+const client = createLdgrClient({ network: "testnet" });
 const payment = await client.payments.verifyTransfer(transactionHash, {
   to: merchantAddress,
-  asset: "dng",
+  asset: "t0",
   amount: "2.50",
 });
 ```
 
+Pass `network: "testnet" | "mainnet"` or the matching ledger id (`0` / `1`).
+The client selects `https://tst.ldgr.ltd` or `https://ldgr.ltd` by default; pass
+`apiBase` alongside `network` for a local deployment or proxy. Use public native
+asset id `t0` on testnet and `t1` on mainnet. Legacy `dng` remains accepted for
+compatibility, while raw authoritative transactions retain their signed wire
+code `dng`.
+
 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

package/dist/index.d.ts

@@ -69,6 +69,6 @@ export declare function createLdgrClient(options: LdgrClientOptions): {
     }>(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 { LdgrClientOptions, LdgrNetwork, LdgrTransaction, PaymentExpectation, PaymentVerification, SignedSubmission } from "./types";
+export { createWebCryptoSigner, generateLocalWallet, loadLocalWallet } from "./signer";
 export type { LdgrSigner, LocalLdgrWallet } from "./signer";

package/dist/index.js

@@ -1,3 +1,6 @@
+// src/client.ts
+import { resolveLdgrNetwork } from "@ldgr/protocol";
+
 // src/types.ts
 class LdgrClientError extends Error {
   status;
@@ -17,6 +20,13 @@ function normalizeApiBase(apiBase) {
     throw new TypeError("apiBase must be an absolute HTTP(S) URL");
   return normalized;
 }
+function apiBaseForOptions(options) {
+  if (options.apiBase !== undefined)
+    return normalizeApiBase(options.apiBase);
+  if (options.network === undefined)
+    throw new TypeError("apiBase is required when network is not provided");
+  return resolveLdgrNetwork(options.network) === 0 ? "https://tst.ldgr.ltd" : "https://ldgr.ltd";
+}
 function assertApiPath(path) {
   if (!path.startsWith("/api/v1/") || path.includes("//") || path.includes("..")) {
     throw new TypeError("path must be an /api/v1/ relative path");
@@ -37,7 +47,7 @@ async function parseJson(response) {
   return body;
 }
 function createTransport(options) {
-  const apiBase = normalizeApiBase(options.apiBase);
+  const apiBase = apiBaseForOptions(options);
   const request = options.fetch ?? globalThis.fetch;
   if (typeof request !== "function")
     throw new TypeError("fetch is required");
@@ -66,12 +76,17 @@ function queryPath(path, query) {
   const encoded = search.toString();
   return encoded ? `${path}?${encoded}` : path;
 }
+
+// src/index.ts
+import { resolveLdgrNetwork as resolveLdgrNetwork2, resolvePublicAssetCode } from "@ldgr/protocol";
 // src/signer.ts
 import {
   deriveAddress,
+  decodeEd25519RecoveryKey,
   encodeEd25519RecoveryKey,
   exportEd25519PublicKey,
   generateEd25519KeyPair,
+  importEd25519PrivateSeed,
   signCanonicalPayload
 } from "@ldgr/protocol";
 function encodeBase64Url(bytes) {
@@ -108,6 +123,11 @@ async function generateLocalWallet(input) {
     recoveryKey: encodeEd25519RecoveryKey(privateKeyJwk)
   };
 }
+async function loadLocalWallet(input) {
+  const { privateSeed } = decodeEd25519RecoveryKey(input.recoveryKey);
+  const keyPair = await importEd25519PrivateSeed(privateSeed);
+  return createWebCryptoSigner({ ...input, ...keyPair });
+}
 
 // src/index.ts
 function normalizedHash(transactionHash) {
@@ -136,6 +156,15 @@ function transactionFields(transaction) {
 }
 function createLdgrClient(options) {
   const transport = createTransport(options);
+  const ledgerId = options.network === undefined ? undefined : resolveLdgrNetwork2(options.network);
+  const resolveAsset = (asset) => {
+    if (ledgerId !== undefined)
+      return resolvePublicAssetCode(asset, ledgerId);
+    if (/^t[01]$/i.test(asset.trim())) {
+      throw new TypeError("network is required when using public native asset ids t0 or t1");
+    }
+    return asset;
+  };
   return {
     ledger: {
       get: () => transport.get("/api/v1/ledger"),
@@ -143,8 +172,8 @@ function createLdgrClient(options) {
     },
     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)}`)
+      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))}`)
     },
     transactions: {
       get: (transactionHash) => transport.get(`/api/v1/transactions/${normalizedHash(transactionHash)}`)
@@ -152,9 +181,9 @@ function createLdgrClient(options) {
     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 }))
+      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 })),
+      quoteRoute: (assetIn, assetOut, amountIn, maxHops) => transport.get(queryPath("/api/v1/amm/routes/quote", { assetIn: resolveAsset(assetIn), assetOut: resolveAsset(assetOut), amountIn, maxHops }))
     },
     subscriptions: {
       getPlan: (planId) => transport.get(`/api/v1/subscription-plans/${encodePathSegment(planId)}`),
@@ -189,6 +218,7 @@ function createLdgrClient(options) {
     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}`);
@@ -198,7 +228,6 @@ function createLdgrClient(options) {
           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 };
         }
@@ -209,6 +238,7 @@ function createLdgrClient(options) {
   };
 }
 export {
+  loadLocalWallet,
   generateLocalWallet,
   createWebCryptoSigner,
   createLdgrClient,

package/dist/signer.d.ts

@@ -17,3 +17,8 @@ export declare function createWebCryptoSigner(input: {
 export declare function generateLocalWallet(input: {
     readonly ledgerId: LedgerId;
 }): Promise<LocalLdgrWallet>;
+/** Restores a caller-owned signer from canonical LDGR recovery material. */
+export declare function loadLocalWallet(input: {
+    readonly recoveryKey: string;
+    readonly ledgerId: LedgerId;
+}): Promise<LdgrSigner>;

package/dist/types.d.ts

@@ -1,4 +1,6 @@
+import type { LdgrNetwork } from "@ldgr/protocol";
 export type LedgerId = 0 | 1;
+export type { LdgrNetwork } from "@ldgr/protocol";
 export type LdgrTransaction = {
     readonly action: string;
     readonly from?: string;
@@ -33,7 +35,10 @@ export type SignedSubmission = {
     readonly feeSponsor?: unknown;
 };
 export type LdgrClientOptions = {
-    readonly apiBase: string;
+    /** `testnet` / `0` or `mainnet` / `1`; required to use public native ids `t0` / `t1`. */
+    readonly network?: LdgrNetwork;
+    /** Defaults to the canonical public origin when `network` is supplied. */
+    readonly apiBase?: string;
     readonly fetch?: typeof globalThis.fetch;
 };
 export type LdgrClientErrorBody = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ldgr/client",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -17,7 +17,7 @@
 "node": ">=20.19.0"
 },
 "dependencies": {
-"@ldgr/protocol": "^0.1.0"
+"@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",