@ldgr/client 0.1.1 → 0.2.1

package/README.md

@@ -8,9 +8,32 @@ 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";

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { type LdgrClientOptions, type LdgrTransaction, type PaymentExpectation, type PaymentVerification, type SignedSubmission } from "./types";
+import { type LdgrClientOptions, type LdgrAsset, type LdgrTransaction, type PaymentExpectation, type PaymentVerification, type SignedSubmission } from "./types";
 export declare function createLdgrClient(options: LdgrClientOptions): {
     ledger: {
         get: () => Promise<{
@@ -25,12 +25,16 @@ export declare function createLdgrClient(options: LdgrClientOptions): {
             readonly nextNonce: string;
         }>;
     };
+    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>>;
@@ -69,6 +73,6 @@ export declare function createLdgrClient(options: LdgrClientOptions): {
     }>(path: string, signed: SignedSubmission) => Promise<T>;
 };
 export { LdgrClientError } from "./types";
-export type { LdgrClientOptions, LdgrNetwork, LdgrTransaction, PaymentExpectation, PaymentVerification, SignedSubmission } from "./types";
-export { createWebCryptoSigner, generateLocalWallet } from "./signer";
+export type { 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

@@ -82,9 +82,11 @@ import { resolveLdgrNetwork as resolveLdgrNetwork2, resolvePublicAssetCode } fro
 // src/signer.ts
 import {
   deriveAddress,
+  decodeEd25519RecoveryKey,
   encodeEd25519RecoveryKey,
   exportEd25519PublicKey,
   generateEd25519KeyPair,
+  importEd25519PrivateSeed,
   signCanonicalPayload
 } from "@ldgr/protocol";
 function encodeBase64Url(bytes) {
@@ -121,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) {
@@ -168,11 +175,14 @@ function createLdgrClient(options) {
       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))}`)
     },
+    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 })),
@@ -231,6 +241,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,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,16 @@ export type LdgrTransaction = {
     readonly transactionHash: string;
     readonly [key: string]: unknown;
 };
+/** 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;
+    readonly [key: string]: unknown;
+};
 export type PaymentExpectation = {
     readonly to: string;
     readonly asset?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ldgr/client",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "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.1.1"
-},
-"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.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"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
 }