@ldgr/client 0.1.1 → 0.2.0

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

@@ -70,5 +70,5 @@ export declare function createLdgrClient(options: LdgrClientOptions): {
 };
 export { LdgrClientError } from "./types";
 export type { LdgrClientOptions, LdgrNetwork, LdgrTransaction, PaymentExpectation, PaymentVerification, SignedSubmission } from "./types";
-export { createWebCryptoSigner, generateLocalWallet } from "./signer";
+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) {
@@ -231,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ldgr/client",
-  "version": "0.1.1",
+  "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.1"
+"@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",