@lombard.finance/sdk-common 3.1.0 → 3.4.0

package/dist/index.cjs

@@ -1 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=require("@bitcoin-js/tiny-secp256k1-asmjs"),r=require("bitcoinjs-lib");function i(t){const e=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(t){for(const o in t)if(o!=="default"){const c=Object.getOwnPropertyDescriptor(t,o);Object.defineProperty(e,o,c.get?c:{enumerable:!0,get:()=>t[o]})}}return e.default=t,Object.freeze(e)}const p=i(u),n={prod:"prod",testnet:"testnet",stage:"stage",dev:"dev"},s=n.prod;r.initEccLib(p);function a(t,e=n.prod){return console.info(`Getting output script for ${t} (${e})`),`0x${r.address.toOutputScript(t,e===n.prod?r.networks.bitcoin:r.networks.testnet).toString("hex")}`}exports.DEFAULT_ENV=s;exports.Env=n;exports.getOutputScript=a;
+"use strict";var u=Object.create;var s=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var d=Object.getOwnPropertyNames;var l=Object.getPrototypeOf,b=Object.prototype.hasOwnProperty;var S=(t,i,e,c)=>{if(i&&typeof i=="object"||typeof i=="function")for(let n of d(i))!b.call(t,n)&&n!==e&&s(t,n,{get:()=>i[n],enumerable:!(c=p(i,n))||c.enumerable});return t};var a=(t,i,e)=>(e=t!=null?u(l(t)):{},S(i||!t||!t.__esModule?s(e,"default",{value:t,enumerable:!0}):e,t));Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o={prod:"prod",testnet:"testnet",stage:"stage",dev:"dev",ibc:"ibc"},g=o.prod,y=["evm","bitcoin","solana","sui","starknet"];let r=null;const E=async()=>{try{const t=await import("bitcoinjs-lib"),i=await import("@bitcoinerlab/secp256k1");try{t.initEccLib(i)}catch(e){if(!/already initialized/i.test(String(e)))throw e}return t}catch(t){throw r=null,new Error(`Failed to initialize bitcoinjs-lib: ${t instanceof Error?t.message:String(t)}. Ensure bitcoinjs-lib and @bitcoinerlab/secp256k1 peer dependencies are installed.`)}},v=async()=>(r||(r=E()),r);async function w(t,i=o.prod){const e=await v();return`0x${e.address.toOutputScript(t,i===o.prod?e.networks.bitcoin:e.networks.testnet).toString("hex")}`}exports.DEFAULT_ENV=g;exports.Env=o;exports.ProviderKeys=y;exports.getOutputScript=w;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/env.ts","../src/providers.ts","../src/utils/bitcoin.ts","../src/utils/get-output-script.ts"],"sourcesContent":["export const Env = {\n  prod: 'prod',\n  testnet: 'testnet',\n  stage: 'stage',\n  dev: 'dev',\n  ibc: 'ibc',\n} as const;\n\nexport type Env = (typeof Env)[keyof typeof Env];\n\nexport const DEFAULT_ENV: Env = Env.prod;\n","import type { EIP1193Provider } from 'viem';\n\n/**\n * Provider interfaces shared between the core SDK and optional chain modules.\n */\nexport interface EvmProvider extends EIP1193Provider {}\n\nexport interface BtcProvider {\n  getAddresses(): Promise<string[]>;\n  signMessage(message: string): Promise<string>;\n  getNetwork?(): Promise<string>;\n}\n\nexport interface SolanaProvider {\n  signMessage(message: Uint8Array | string): Promise<{ signature: Uint8Array }>;\n  publicKey?: { toString(): string };\n  network?: string;\n}\n\nexport interface SuiProvider {\n  getWallet(): unknown;\n  getWalletAccount(): unknown;\n}\n\nexport interface StarknetProvider {\n  getProvider(): unknown;\n}\n\nexport type AnyProvider =\n  | EvmProvider\n  | BtcProvider\n  | SolanaProvider\n  | SuiProvider\n  | StarknetProvider;\n\nexport const ProviderKeys = [\n  'evm',\n  'bitcoin',\n  'solana',\n  'sui',\n  'starknet',\n] as const;\nexport type ProviderKey = (typeof ProviderKeys)[number];\n\nexport interface ProviderMap {\n  evm: EvmProvider;\n  bitcoin: BtcProvider;\n  solana: SolanaProvider;\n  sui: SuiProvider;\n  starknet: StarknetProvider;\n}\n\nexport type ProviderFor<TKey extends ProviderKey> = ProviderMap[TKey];\n","let bitcoinPromise: Promise<typeof import('bitcoinjs-lib')> | null = null;\n\nconst initBitcoin = async (): Promise<typeof import('bitcoinjs-lib')> => {\n  try {\n    const module = await import('bitcoinjs-lib');\n    const ecc = await import('@bitcoinerlab/secp256k1');\n    try {\n      module.initEccLib(ecc);\n    } catch (err) {\n      if (!/already initialized/i.test(String(err))) {\n        throw err;\n      }\n    }\n    return module;\n  } catch (err) {\n    // Reset promise so subsequent calls can retry\n    bitcoinPromise = null;\n    throw new Error(\n      `Failed to initialize bitcoinjs-lib: ${err instanceof Error ? err.message : String(err)}. ` +\n        'Ensure bitcoinjs-lib and @bitcoinerlab/secp256k1 peer dependencies are installed.',\n    );\n  }\n};\n\nexport const getBitcoin = async (): Promise<typeof import('bitcoinjs-lib')> => {\n  if (!bitcoinPromise) {\n    bitcoinPromise = initBitcoin();\n  }\n  return bitcoinPromise;\n};\n","import { Env } from '../env';\nimport { getBitcoin } from './bitcoin';\n\n/**\n * Get output script from address.\n *\n * @param address - The address.\n * @param env\n *\n * @returns The output script.\n */\nexport async function getOutputScript(\n  address: string,\n  env: Env = Env.prod,\n): Promise<`0x${string}`> {\n  const bitcoin = await getBitcoin();\n  const outputScriptBuf = bitcoin.address.toOutputScript(\n    address,\n    env === Env.prod ? bitcoin.networks.bitcoin : bitcoin.networks.testnet,\n  );\n  const outputScript = outputScriptBuf.toString('hex');\n  return `0x${outputScript}`;\n}\n"],"names":["Env","DEFAULT_ENV","ProviderKeys","bitcoinPromise","initBitcoin","module","ecc","err","getBitcoin","getOutputScript","address","env","bitcoin"],"mappings":"2hBAAO,MAAMA,EAAM,CACjB,KAAM,OACN,QAAS,UACT,MAAO,QACP,IAAK,MACL,IAAK,KACP,EAIaC,EAAmBD,EAAI,KCyBvBE,EAAe,CAC1B,MACA,UACA,SACA,MACA,UACF,ECzCA,IAAIC,EAAiE,KAErE,MAAMC,EAAc,SAAqD,CACvE,GAAI,CACF,MAAMC,EAAS,KAAM,QAAO,eAAe,EACrCC,EAAM,KAAM,QAAO,yBAAyB,EAClD,GAAI,CACFD,EAAO,WAAWC,CAAG,CACvB,OAASC,EAAK,CACZ,GAAI,CAAC,uBAAuB,KAAK,OAAOA,CAAG,CAAC,EAC1C,MAAMA,CAEV,CACA,OAAOF,CACT,OAASE,EAAK,CAEZ,MAAAJ,EAAiB,KACX,IAAI,MACR,uCAAuCI,aAAe,MAAQA,EAAI,QAAU,OAAOA,CAAG,CAAC,qFAAA,CAG3F,CACF,EAEaC,EAAa,UACnBL,IACHA,EAAiBC,EAAA,GAEZD,GCjBT,eAAsBM,EACpBC,EACAC,EAAWX,EAAI,KACS,CACxB,MAAMY,EAAU,MAAMJ,EAAA,EAMtB,MAAO,KALiBI,EAAQ,QAAQ,eACtCF,EACAC,IAAQX,EAAI,KAAOY,EAAQ,SAAS,QAAUA,EAAQ,SAAS,OAAA,EAE5B,SAAS,KAAK,CAC3B,EAC1B"}

package/dist/index.js

@@ -1,20 +1,44 @@
-import * as c from "@bitcoin-js/tiny-secp256k1-asmjs";
-import { initEccLib as i, address as u, networks as r } from "bitcoinjs-lib";
-const t = {
+const r = {
   prod: "prod",
   testnet: "testnet",
   stage: "stage",
-  dev: "dev"
-}, d = t.prod;
-i(c);
-function f(o, p = t.prod) {
-  return console.info(`Getting output script for ${o} (${p})`), `0x${u.toOutputScript(
-    o,
-    p === t.prod ? r.bitcoin : r.testnet
+  dev: "dev",
+  ibc: "ibc"
+}, p = r.prod, u = [
+  "evm",
+  "bitcoin",
+  "solana",
+  "sui",
+  "starknet"
+];
+let n = null;
+const o = async () => {
+  try {
+    const t = await import("bitcoinjs-lib"), e = await import("@bitcoinerlab/secp256k1");
+    try {
+      t.initEccLib(e);
+    } catch (i) {
+      if (!/already initialized/i.test(String(i)))
+        throw i;
+    }
+    return t;
+  } catch (t) {
+    throw n = null, new Error(
+      `Failed to initialize bitcoinjs-lib: ${t instanceof Error ? t.message : String(t)}. Ensure bitcoinjs-lib and @bitcoinerlab/secp256k1 peer dependencies are installed.`
+    );
+  }
+}, c = async () => (n || (n = o()), n);
+async function d(t, e = r.prod) {
+  const i = await c();
+  return `0x${i.address.toOutputScript(
+    t,
+    e === r.prod ? i.networks.bitcoin : i.networks.testnet
   ).toString("hex")}`;
 }
 export {
-  d as DEFAULT_ENV,
-  t as Env,
-  f as getOutputScript
+  p as DEFAULT_ENV,
+  r as Env,
+  u as ProviderKeys,
+  d as getOutputScript
 };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/env.ts","../src/providers.ts","../src/utils/bitcoin.ts","../src/utils/get-output-script.ts"],"sourcesContent":["export const Env = {\n  prod: 'prod',\n  testnet: 'testnet',\n  stage: 'stage',\n  dev: 'dev',\n  ibc: 'ibc',\n} as const;\n\nexport type Env = (typeof Env)[keyof typeof Env];\n\nexport const DEFAULT_ENV: Env = Env.prod;\n","import type { EIP1193Provider } from 'viem';\n\n/**\n * Provider interfaces shared between the core SDK and optional chain modules.\n */\nexport interface EvmProvider extends EIP1193Provider {}\n\nexport interface BtcProvider {\n  getAddresses(): Promise<string[]>;\n  signMessage(message: string): Promise<string>;\n  getNetwork?(): Promise<string>;\n}\n\nexport interface SolanaProvider {\n  signMessage(message: Uint8Array | string): Promise<{ signature: Uint8Array }>;\n  publicKey?: { toString(): string };\n  network?: string;\n}\n\nexport interface SuiProvider {\n  getWallet(): unknown;\n  getWalletAccount(): unknown;\n}\n\nexport interface StarknetProvider {\n  getProvider(): unknown;\n}\n\nexport type AnyProvider =\n  | EvmProvider\n  | BtcProvider\n  | SolanaProvider\n  | SuiProvider\n  | StarknetProvider;\n\nexport const ProviderKeys = [\n  'evm',\n  'bitcoin',\n  'solana',\n  'sui',\n  'starknet',\n] as const;\nexport type ProviderKey = (typeof ProviderKeys)[number];\n\nexport interface ProviderMap {\n  evm: EvmProvider;\n  bitcoin: BtcProvider;\n  solana: SolanaProvider;\n  sui: SuiProvider;\n  starknet: StarknetProvider;\n}\n\nexport type ProviderFor<TKey extends ProviderKey> = ProviderMap[TKey];\n","let bitcoinPromise: Promise<typeof import('bitcoinjs-lib')> | null = null;\n\nconst initBitcoin = async (): Promise<typeof import('bitcoinjs-lib')> => {\n  try {\n    const module = await import('bitcoinjs-lib');\n    const ecc = await import('@bitcoinerlab/secp256k1');\n    try {\n      module.initEccLib(ecc);\n    } catch (err) {\n      if (!/already initialized/i.test(String(err))) {\n        throw err;\n      }\n    }\n    return module;\n  } catch (err) {\n    // Reset promise so subsequent calls can retry\n    bitcoinPromise = null;\n    throw new Error(\n      `Failed to initialize bitcoinjs-lib: ${err instanceof Error ? err.message : String(err)}. ` +\n        'Ensure bitcoinjs-lib and @bitcoinerlab/secp256k1 peer dependencies are installed.',\n    );\n  }\n};\n\nexport const getBitcoin = async (): Promise<typeof import('bitcoinjs-lib')> => {\n  if (!bitcoinPromise) {\n    bitcoinPromise = initBitcoin();\n  }\n  return bitcoinPromise;\n};\n","import { Env } from '../env';\nimport { getBitcoin } from './bitcoin';\n\n/**\n * Get output script from address.\n *\n * @param address - The address.\n * @param env\n *\n * @returns The output script.\n */\nexport async function getOutputScript(\n  address: string,\n  env: Env = Env.prod,\n): Promise<`0x${string}`> {\n  const bitcoin = await getBitcoin();\n  const outputScriptBuf = bitcoin.address.toOutputScript(\n    address,\n    env === Env.prod ? bitcoin.networks.bitcoin : bitcoin.networks.testnet,\n  );\n  const outputScript = outputScriptBuf.toString('hex');\n  return `0x${outputScript}`;\n}\n"],"names":["Env","DEFAULT_ENV","ProviderKeys","bitcoinPromise","initBitcoin","module","ecc","err","getBitcoin","getOutputScript","address","env","bitcoin"],"mappings":"AAAO,MAAMA,IAAM;AAAA,EACjB,MAAM;AAAA,EACN,SAAS;AAAA,EACT,OAAO;AAAA,EACP,KAAK;AAAA,EACL,KAAK;AACP,GAIaC,IAAmBD,EAAI,MCyBvBE,IAAe;AAAA,EAC1B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;ACzCA,IAAIC,IAAiE;AAErE,MAAMC,IAAc,YAAqD;AACvE,MAAI;AACF,UAAMC,IAAS,MAAM,OAAO,eAAe,GACrCC,IAAM,MAAM,OAAO,yBAAyB;AAClD,QAAI;AACF,MAAAD,EAAO,WAAWC,CAAG;AAAA,IACvB,SAASC,GAAK;AACZ,UAAI,CAAC,uBAAuB,KAAK,OAAOA,CAAG,CAAC;AAC1C,cAAMA;AAAA,IAEV;AACA,WAAOF;AAAA,EACT,SAASE,GAAK;AAEZ,UAAAJ,IAAiB,MACX,IAAI;AAAA,MACR,uCAAuCI,aAAe,QAAQA,EAAI,UAAU,OAAOA,CAAG,CAAC;AAAA,IAAA;AAAA,EAG3F;AACF,GAEaC,IAAa,aACnBL,MACHA,IAAiBC,EAAA,IAEZD;ACjBT,eAAsBM,EACpBC,GACAC,IAAWX,EAAI,MACS;AACxB,QAAMY,IAAU,MAAMJ,EAAA;AAMtB,SAAO,KALiBI,EAAQ,QAAQ;AAAA,IACtCF;AAAA,IACAC,MAAQX,EAAI,OAAOY,EAAQ,SAAS,UAAUA,EAAQ,SAAS;AAAA,EAAA,EAE5B,SAAS,KAAK,CAC3B;AAC1B;"}

package/package.json

@@ -1,35 +1,42 @@
 {
   "name": "@lombard.finance/sdk-common",
-  "version": "3.1.0",
+  "version": "3.4.0",
   "exports": {
     ".": {
       "types": "./src/index.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
-    }
+    },
+    "./utils/*": "./src/utils/*.ts"
   },
   "license": "MIT",
   "type": "module",
   "types": "./src/index.ts",
-  "files": ["dist", "src"],
+  "files": [
+    "dist",
+    "src"
+  ],
   "engines": {
-    "node": ">= 22.14.0"
+    "node": ">= 18.0.0"
   },
   "scripts": {
     "build-docs": "rimraf ./sdk-docs && typedoc --out sdk-docs",
     "build": "yarn types && vite build",
-    "lint": "biome lint",
+    "lint": "eslint . --ext .js,.jsx,.ts,.tsx --max-warnings=0",
+    "format": "prettier --write \"src/**/*.{js,jsx,ts,tsx}\"",
+    "format:check": "prettier --check \"src/**/*.{js,jsx,ts,tsx}\"",
     "types": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@bitcoin-js/tiny-secp256k1-asmjs": "2.2.3",
-    "bitcoinjs-lib": "6.1.5"
+    "@bitcoinerlab/secp256k1": "^1.2.0",
+    "bitcoinjs-lib": "^6.1.5"
   },
   "devDependencies": {
-    "@bitcoin-js/tiny-secp256k1-asmjs": "2.2.3",
+    "@bitcoinerlab/secp256k1": "1.2.0",
+    "bitcoinjs-lib": "6.1.5",
     "rimraf": "^5",
     "typedoc": "^0.26.6",
     "typescript": "^5.4.5",
-    "bitcoinjs-lib": "6.1.5"
+    "vite": "^6.3.5"
   }
 }

package/src/env.ts

@@ -3,6 +3,7 @@ export const Env = {
   testnet: 'testnet',
   stage: 'stage',
   dev: 'dev',
+  ibc: 'ibc',
 } as const;
 
 export type Env = (typeof Env)[keyof typeof Env];

package/src/index.ts

@@ -1,2 +1,7 @@
 export * from './env';
+export * from './modules';
+export * from './providers';
 export * from './utils/get-output-script';
+
+// Chain services (what modules provide)
+export * from './services';

package/src/modules.ts

@@ -0,0 +1,108 @@
+import type { Env } from './env';
+import type { ProviderFor, ProviderKey } from './providers';
+
+/**
+ * Shared token for cross-module state
+ */
+export type SharedToken<T> = symbol & { __sharedToken?: T };
+
+/**
+ * Context provided to modules during registration
+ */
+export interface RegisterContext {
+  env: Env;
+  getProvider<TKey extends ProviderKey>(key: TKey): Promise<ProviderFor<TKey>>;
+  getShared<T>(token: SharedToken<T>): T | undefined;
+  setShared<T>(token: SharedToken<T>, value: T): void;
+}
+
+/**
+ * SDK Module - Generic module interface
+ *
+ * Base interface for all SDK modules. Modules are thin factories that
+ * instantiate services and register them with the SDK.
+ *
+ * Use this for non-chain-specific modules (e.g., apiModule).
+ *
+ * @template TId - Unique module identifier
+ * @template TService - Service interface the module provides
+ *
+ * @example
+ * ```typescript
+ * function apiModule(): SdkModule<'api', ApiService> {
+ *   return {
+ *     id: 'api',
+ *     register(ctx) {
+ *       return new ApiService(ctx.env);
+ *     },
+ *   };
+ * }
+ * ```
+ */
+export interface SdkModule<TId extends string = string, TService = unknown> {
+  /** Unique module identifier */
+  id: TId;
+  /** Provider keys required by this module */
+  requiresProviders?: ProviderKey[];
+  /** Factory function that creates the service */
+  register(ctx: RegisterContext): TService;
+}
+
+/**
+ * Chain Module - Module interface for blockchain-specific services
+ *
+ * Extension of SdkModule for chain-specific modules. Adds a `chain` field
+ * to identify the blockchain type.
+ *
+ * Use this for chain-specific modules (e.g., btcModule, evmModule, solanaModule).
+ *
+ * @template TChain - Chain type identifier (e.g., 'btc', 'evm', 'solana')
+ * @template TService - Service interface the module provides
+ *
+ * @example
+ * ```typescript
+ * function evmModule(): ChainModule<'evm', EvmService> {
+ *   return {
+ *     id: 'evm',
+ *     chain: 'evm',
+ *     register(ctx) {
+ *       return new EvmService(ctx.env);
+ *     },
+ *   };
+ * }
+ * ```
+ */
+export interface ChainModule<TChain extends string = string, TService = unknown>
+  extends SdkModule<TChain, TService> {
+  /** Chain type this module provides services for */
+  chain: TChain;
+}
+
+/**
+ * Any module type (either SdkModule or ChainModule)
+ */
+export type AnyModule =
+  | SdkModule<string, unknown>
+  | ChainModule<string, unknown>;
+
+/**
+ * Extract module ID type from a module
+ */
+export type ModuleId<TModule> =
+  TModule extends SdkModule<infer TId, unknown> ? TId : never;
+
+/**
+ * Extract service type from a module by ID
+ */
+export type ServiceOf<TModule extends SdkModule<string, unknown>, TId extends string> =
+  TModule extends SdkModule<TId, infer TService> ? TService : never;
+
+/**
+ * @deprecated Use ServiceOf instead
+ */
+export type CapabilitiesOf<
+  TModule extends ChainModule<string, unknown>,
+  TId extends string,
+> = TModule extends ChainModule<string, infer TCapabilities> & { id: TId }
+  ? TCapabilities
+  : never;

package/src/providers.ts

@@ -0,0 +1,53 @@
+import type { EIP1193Provider } from 'viem';
+
+/**
+ * Provider interfaces shared between the core SDK and optional chain modules.
+ */
+export interface EvmProvider extends EIP1193Provider {}
+
+export interface BtcProvider {
+  getAddresses(): Promise<string[]>;
+  signMessage(message: string): Promise<string>;
+  getNetwork?(): Promise<string>;
+}
+
+export interface SolanaProvider {
+  signMessage(message: Uint8Array | string): Promise<{ signature: Uint8Array }>;
+  publicKey?: { toString(): string };
+  network?: string;
+}
+
+export interface SuiProvider {
+  getWallet(): unknown;
+  getWalletAccount(): unknown;
+}
+
+export interface StarknetProvider {
+  getProvider(): unknown;
+}
+
+export type AnyProvider =
+  | EvmProvider
+  | BtcProvider
+  | SolanaProvider
+  | SuiProvider
+  | StarknetProvider;
+
+export const ProviderKeys = [
+  'evm',
+  'bitcoin',
+  'solana',
+  'sui',
+  'starknet',
+] as const;
+export type ProviderKey = (typeof ProviderKeys)[number];
+
+export interface ProviderMap {
+  evm: EvmProvider;
+  bitcoin: BtcProvider;
+  solana: SolanaProvider;
+  sui: SuiProvider;
+  starknet: StarknetProvider;
+}
+
+export type ProviderFor<TKey extends ProviderKey> = ProviderMap[TKey];

package/src/services/api.ts

@@ -0,0 +1,140 @@
+/**
+ * API Service
+ *
+ * Operations for Lombard backend API provided by apiModule() or built-in.
+ * Used by actions for deposit address generation and tracking.
+ */
+
+/**
+ * Destination chain ID (EVM numeric, Solana string, etc.)
+ */
+export type DestinationChainId = number | string;
+
+/**
+ * Deposit information returned from API
+ */
+export interface DepositInfo {
+  depositAddress: string;
+  blockHeight?: number;
+  isClaimed: boolean;
+  txid?: string;
+  amount?: string;
+}
+
+/**
+ * Parameters for generating a deposit address
+ */
+export interface GenerateDepositAddressParams {
+  /** Recipient address on destination chain */
+  address: string;
+  /** Destination chain ID */
+  chainId: DestinationChainId;
+  /** Authorization signature */
+  signature: string;
+  /**
+   * Token to mint (LBTC, BTCb, etc.)
+   * REQUIRED - determines which token contract address is used
+   */
+  token: string;
+  /** EIP-712 typed data (for EVM) */
+  eip712Data?: string;
+  /** Signature data (for stake and bake) */
+  signatureData?: string;
+  /** Public key (for non-EVM chains) */
+  pubKey?: string;
+  /** Partner ID for attribution */
+  partnerId?: string;
+  /** Referral code */
+  referrerCode?: string;
+}
+
+/**
+ * Parameters for getting an existing deposit address
+ */
+export interface GetDepositAddressParams {
+  address: string;
+  chainId: DestinationChainId;
+  /** Token to look up (LBTC, BTCb, etc.) - REQUIRED */
+  token: string;
+  partnerId?: string;
+}
+
+/**
+ * Fee signature storage parameters
+ */
+export interface StoreFeeSignatureParams {
+  address: string;
+  signature: string;
+  typedData: string;
+  /** Token address to distinguish LBTC vs BTC.b signatures */
+  tokenAddress?: string;
+}
+
+/**
+ * Fee signature retrieval parameters
+ */
+export interface GetFeeSignatureParams {
+  address: string;
+  chainId: number;
+  /** Token address to distinguish LBTC vs BTC.b signatures */
+  tokenAddress?: string;
+}
+
+/**
+ * Fee signature result
+ */
+export interface FeeSignatureResult {
+  hasSignature: boolean;
+  signature?: string;
+  typedData?: string;
+  expirationDate?: string;
+}
+
+/**
+ * Stake and bake signature storage parameters
+ */
+export interface StoreStakeAndBakeParams {
+  signature: string;
+  typedData: string;
+}
+
+/**
+ * API Service Interface
+ *
+ * Provides all Lombard backend API operations.
+ * Injected into contexts as `ctx.api`.
+ */
+export interface ApiService {
+  /**
+   * Generate a new BTC deposit address
+   */
+  generateDepositAddress(params: GenerateDepositAddressParams): Promise<string>;
+
+  /**
+   * Get existing deposit address for a recipient
+   * Returns undefined if no address exists
+   */
+  getDepositAddress(
+    params: GetDepositAddressParams,
+  ): Promise<string | undefined>;
+
+  /**
+   * Get deposits for an address
+   */
+  getDeposits(address: string): Promise<DepositInfo[]>;
+
+  /**
+   * Store network fee signature
+   */
+  storeFeeSignature(params: StoreFeeSignatureParams): Promise<void>;
+
+  /**
+   * Get stored network fee signature
+   */
+  getFeeSignature(params: GetFeeSignatureParams): Promise<FeeSignatureResult>;
+
+  /**
+   * Store stake and bake signature
+   */
+  storeStakeAndBakeSignature(params: StoreStakeAndBakeParams): Promise<void>;
+}

package/src/services/btc.ts

@@ -0,0 +1,24 @@
+/**
+ * BTC Chain Service
+ *
+ * Operations for Bitcoin blockchain provided by btcModule().
+ * Used by strategies for BTC deposit monitoring and address operations.
+ */
+
+/**
+ * Network mode for Bitcoin operations
+ */
+export type BtcNetworkMode = 'mainnet' | 'testnet';
+
+/**
+ * BTC Service Interface
+ *
+ * Provides Bitcoin-specific operations.
+ * Injected into BtcCoreContext as `ctx.btc`.
+ */
+export interface BtcService {
+  /**
+   * Get current block height from mempool
+   */
+  getCurrentBlockHeight(network: BtcNetworkMode): Promise<number>;
+}

package/src/services/evm.ts

@@ -0,0 +1,105 @@
+/**
+ * EVM Chain Service
+ *
+ * Operations for EVM-compatible blockchains provided by evmModule().
+ * Used by strategies for contract interactions and fee authorization.
+ */
+
+import type { EvmProvider } from '../providers';
+
+/**
+ * Chain ID type (numeric EVM chain identifier)
+ */
+export type EvmChainId = number;
+
+/**
+ * Fee authorization result
+ */
+export interface FeeAuthorizationResult {
+  signature: string;
+  typedData?: string;
+}
+
+/**
+ * Stored fee signature result (from resume flow)
+ */
+export interface StoredFeeSignature {
+  hasSignature: boolean;
+  signature?: string;
+  typedData?: string;
+  expirationDate?: string;
+  isDelayed?: boolean;
+}
+
+/**
+ * Network fee signing parameters
+ */
+export interface SignNetworkFeeParams {
+  fee: string;
+  account: string;
+  chainId: EvmChainId;
+  provider: EvmProvider;
+  /** Token to sign for (LBTC or BTCb). Defaults to LBTC for backwards compatibility. */
+  token?: string;
+}
+
+/**
+ * Network fee signing result
+ */
+export interface SignNetworkFeeResult {
+  signature: string;
+  typedData: string;
+}
+
+/**
+ * Stake and bake signing parameters
+ */
+export interface SignStakeAndBakeParams {
+  value: string;
+  account: string;
+  chainId: EvmChainId;
+  provider: EvmProvider;
+  vaultKey: string;
+  token: string;
+}
+
+/**
+ * EVM Service Interface
+ *
+ * Provides all EVM-specific operations.
+ * Injected into contexts as `ctx.evm`.
+ */
+export interface EvmService {
+  /**
+   * Get minting fee for a chain
+   * @param chainId - The chain ID
+   * @param token - Optional token (defaults to LBTC). Use 'BTCb' for BTC.b deposits.
+   */
+  getMintingFee(chainId: EvmChainId, token?: string): Promise<string>;
+
+  /**
+   * Sign network fee authorization (EIP-712)
+   */
+  signNetworkFee(params: SignNetworkFeeParams): Promise<SignNetworkFeeResult>;
+
+  /**
+   * Get stake and bake fee for a vault
+   */
+  getStakeAndBakeFee(chainId: EvmChainId, vaultKey: string): Promise<string>;
+
+  /**
+   * Sign stake and bake authorization
+   */
+  signStakeAndBake(
+    params: SignStakeAndBakeParams,
+  ): Promise<SignNetworkFeeResult>;
+
+  /**
+   * Sign LBTC destination address (for non-Ethereum EVM chains)
+   */
+  signLbtcDestination(params: {
+    chainId: EvmChainId;
+    address: string;
+    provider: EvmProvider;
+  }): Promise<{ signature: string }>;
+}

package/src/services/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Chain Services
+ *
+ * Interfaces for what modules provide to actions.
+ * Each chain module (btcModule, evmModule, solanaModule, etc.)
+ * returns a service implementing one of these interfaces.
+ *
+ * Service-First Pattern:
+ * - Service interfaces define the contract
+ * - Service implementation classes contain the logic
+ * - Modules are thin factories that instantiate services
+ */
+
+// Core services (provided by sdk)
+export * from './api';
+export * from './btc';
+export * from './evm';
+
+// External chain services (provided by sdk-solana, sdk-sui, etc.)
+export * from './solana';
+export * from './starknet';
+export * from './sui';

package/src/services/solana.ts

@@ -0,0 +1,31 @@
+/**
+ * Solana Chain Service
+ *
+ * Operations for Solana blockchain provided by solanaModule().
+ * Used by strategies that mint/send to Solana.
+ */
+export interface SolanaService {
+  /**
+   * Sign LBTC destination address for Solana minting
+   * Required to generate a BTC deposit address for Solana destination
+   */
+  signLbtcDestination(args: {
+    network: string;
+  }): Promise<{ signature: string }>;
+
+  /**
+   * Unstake LBTC on Solana to receive BTC
+   *
+   * Burns LBTC on Solana and releases BTC to the provided Bitcoin address.
+   *
+   * @param args.amount - Amount of LBTC to unstake in base units (satoshis)
+   * @param args.btcAddress - Bitcoin address to receive BTC
+   * @param args.network - Solana network ('mainnet-beta', 'devnet', 'testnet')
+   * @returns Transaction signature
+   */
+  unstake(args: {
+    amount: string;
+    btcAddress: string;
+    network: string;
+  }): Promise<{ txHash: string }>;
+}

package/src/services/starknet.ts

@@ -0,0 +1,31 @@
+/**
+ * Starknet Chain Service
+ *
+ * Operations for Starknet blockchain provided by starknetModule().
+ * Used by strategies that mint/send to Starknet.
+ */
+export interface StarknetService {
+  /**
+   * Sign LBTC destination address for Starknet minting
+   * Required to generate a BTC deposit address for Starknet destination
+   */
+  signLbtcDestination(args: {
+    chainId: string;
+  }): Promise<{ signature: string; pubKey: string }>;
+
+  /**
+   * Unstake LBTC on Starknet to receive BTC
+   *
+   * Burns LBTC on Starknet and releases BTC to the provided Bitcoin address.
+   *
+   * @param args.amount - Amount of LBTC to unstake (BTC decimal, e.g., "0.001")
+   * @param args.btcAddress - Bitcoin address to receive BTC
+   * @param args.env - Environment (prod, testnet, stage, dev)
+   * @returns Transaction hash
+   */
+  unstake(args: {
+    amount: string;
+    btcAddress: string;
+    env: string;
+  }): Promise<{ txHash: string }>;
+}

package/src/services/sui.ts

@@ -0,0 +1,33 @@
+/**
+ * Sui Chain Service
+ *
+ * Operations for Sui blockchain provided by suiModule().
+ * Used by strategies that mint/send to Sui.
+ */
+export interface SuiService {
+  /**
+   * Sign LBTC destination address for Sui minting
+   * Required to generate a BTC deposit address for Sui destination
+   */
+  signLbtcDestination(args: {
+    chainId: string;
+  }): Promise<{ signature: string }>;
+
+  /**
+   * Unstake LBTC on Sui to receive BTC
+   *
+   * Burns LBTC on Sui and releases BTC to the provided Bitcoin address.
+   *
+   * @param args.amount - Amount of LBTC to unstake (BTC decimal, e.g., "0.001")
+   * @param args.btcAddress - Bitcoin address to receive BTC
+   * @param args.chainId - Sui chain ID ('sui:mainnet', 'sui:testnet')
+   * @param args.env - Environment (prod, testnet, stage, dev)
+   * @returns Transaction digest (hash)
+   */
+  unstake(args: {
+    amount: string;
+    btcAddress: string;
+    chainId: string;
+    env: string;
+  }): Promise<{ txHash: string }>;
+}

package/src/utils/bitcoin.ts

@@ -0,0 +1,30 @@
+let bitcoinPromise: Promise<typeof import('bitcoinjs-lib')> | null = null;
+
+const initBitcoin = async (): Promise<typeof import('bitcoinjs-lib')> => {
+  try {
+    const module = await import('bitcoinjs-lib');
+    const ecc = await import('@bitcoinerlab/secp256k1');
+    try {
+      module.initEccLib(ecc);
+    } catch (err) {
+      if (!/already initialized/i.test(String(err))) {
+        throw err;
+      }
+    }
+    return module;
+  } catch (err) {
+    // Reset promise so subsequent calls can retry
+    bitcoinPromise = null;
+    throw new Error(
+      `Failed to initialize bitcoinjs-lib: ${err instanceof Error ? err.message : String(err)}. ` +
+        'Ensure bitcoinjs-lib and @bitcoinerlab/secp256k1 peer dependencies are installed.',
+    );
+  }
+};
+
+export const getBitcoin = async (): Promise<typeof import('bitcoinjs-lib')> => {
+  if (!bitcoinPromise) {
+    bitcoinPromise = initBitcoin();
+  }
+  return bitcoinPromise;
+};

package/src/utils/btc-address-type.ts

@@ -0,0 +1,22 @@
+import { address } from 'bitcoinjs-lib';
+
+export enum BtcAddressType {
+  p2tr = 'p2tr',
+  p2wpkh = 'p2wpkh',
+  p2wsh = 'p2wsh',
+}
+
+export function getBtcAddressType(btcAddress: string): BtcAddressType {
+  const { data, version } = address.fromBech32(btcAddress);
+
+  if (version === 0) {
+    if (data.length === 20) return BtcAddressType.p2wpkh;
+    if (data.length === 32) return BtcAddressType.p2wsh;
+  }
+
+  if (version === 1) {
+    if (data.length === 32) return BtcAddressType.p2tr;
+  }
+
+  throw new Error('Invalid BTC address');
+}

package/src/utils/err.ts

@@ -0,0 +1,85 @@
+import { AxiosError } from 'axios';
+
+/**
+ * Extract a readable error message from any error object
+ * @param error Error object to extract message from
+ * @returns A readable error message string
+ */
+export function extractErrorMessage(error: unknown): string {
+  // If error is already a string, return it
+  if (typeof error === 'string') {
+    return error;
+  }
+
+  // Check for data.message pattern (common in API error responses)
+  const hasDataMessage = (
+    err: unknown,
+  ): err is { data: { message: string } } => {
+    if (err === null || typeof err !== 'object') return false;
+    if (!('data' in err) || err.data === null || typeof err.data !== 'object')
+      return false;
+    if (!('message' in err.data)) return false;
+    return typeof err.data.message === 'string';
+  };
+
+  if (hasDataMessage(error)) {
+    return error.data.message;
+  }
+
+  // Handle standard Error objects and Axios errors
+  if (error instanceof Error) {
+    if ('isAxiosError' in error && error.isAxiosError) {
+      return extractAxiosErrorMessage(error as unknown as AxiosError);
+    }
+    return error.message;
+  }
+
+  // Handle generic objects with a message property
+  if (error !== null && typeof error === 'object') {
+    if ('message' in error && typeof error.message === 'string') {
+      return error.message;
+    }
+
+    // Try to convert object to a readable string
+    try {
+      return JSON.stringify(error);
+    } catch {
+      // If JSON.stringify fails, return a generic message
+      return 'Unknown error object';
+    }
+  }
+
+  return 'Unknown error';
+}
+
+/**
+ * Extract error message from an Axios error
+ * @param error Axios error object
+ * @returns Error message from the Axios error
+ */
+function extractAxiosErrorMessage(error: AxiosError): string {
+  if (error.response) {
+    const responseData = error.response.data;
+    if (responseData && typeof responseData === 'object') {
+      if (
+        'message' in responseData &&
+        responseData.message &&
+        typeof responseData.message === 'string'
+      ) {
+        return responseData.message;
+      }
+      try {
+        return JSON.stringify(responseData);
+      } catch {
+        return 'Error in API response';
+      }
+    }
+    return `HTTP error ${error.response.status}: ${error.response.statusText}`;
+  }
+
+  if (error.message) {
+    return error.message;
+  }
+
+  return 'Network error';
+}

package/src/utils/get-output-script.ts

@@ -1,8 +1,5 @@
-import * as ecc from '@bitcoin-js/tiny-secp256k1-asmjs';
-import { address as addressUtils, initEccLib, networks } from 'bitcoinjs-lib';
 import { Env } from '../env';
-
-initEccLib(ecc);
+import { getBitcoin } from './bitcoin';
 
 /**
  * Get output script from address.
@@ -12,15 +9,14 @@ initEccLib(ecc);
  *
  * @returns The output script.
  */
-export function getOutputScript(
+export async function getOutputScript(
   address: string,
   env: Env = Env.prod,
-): `0x${string}` {
-  console.info(`Getting output script for ${address} (${env})`);
-
-  const outputScriptBuf = addressUtils.toOutputScript(
+): Promise<`0x${string}`> {
+  const bitcoin = await getBitcoin();
+  const outputScriptBuf = bitcoin.address.toOutputScript(
     address,
-    env === Env.prod ? networks.bitcoin : networks.testnet,
+    env === Env.prod ? bitcoin.networks.bitcoin : bitcoin.networks.testnet,
   );
   const outputScript = outputScriptBuf.toString('hex');
   return `0x${outputScript}`;

package/src/utils/numbers.ts

@@ -0,0 +1,17 @@
+import BigNumber from 'bignumber.js';
+
+export function toBaseDenomination(
+  input: BigNumber.Value,
+  decimalPlaces: number,
+) {
+  return BigNumber(input)
+    .multipliedBy(BigNumber(10).pow(decimalPlaces))
+    .decimalPlaces(0, BigNumber.ROUND_HALF_UP);
+}
+
+export function fromBaseDenomination(
+  input: BigNumber.Value,
+  decimalPlaces: number,
+) {
+  return BigNumber(input).dividedBy(BigNumber(10).pow(decimalPlaces));
+}