@lombard.finance/sdk 3.7.4 → 4.0.0

package/src/shared/monitoring/depositMonitor.ts

@@ -0,0 +1,211 @@
+/**
+ * Deposit Monitor Utility
+ *
+ * Shared monitoring logic for tracking Bitcoin deposit confirmations
+ * and minting status. Used by BtcStake, BtcDeposit, and BtcStakeAndDeploy actions.
+ *
+ * @module shared/monitoring/depositMonitor
+ */
+
+import { StepStatus } from '../../core';
+import type { BtcService } from '../../modules/btcModule';
+
+/** Bitcoin network mode */
+export type NetworkMode = 'mainnet' | 'testnet';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Deposit information returned by fetch function
+ */
+export interface DepositInfo {
+  /** Block height where deposit was confirmed */
+  blockHeight?: number;
+  /** Whether LBTC has been minted/claimed */
+  isClaimed?: boolean;
+}
+
+/**
+ * Progress information emitted during monitoring
+ */
+export interface MonitorProgress {
+  /** Current confirmations */
+  confirmations: number;
+  /** Required confirmations for finality */
+  requiredConfirmations: number;
+  /** Whether deposit has enough confirmations */
+  hasEnoughConfirmations: boolean;
+  /** Whether LBTC has been claimed */
+  isClaimed: boolean;
+  /** Step statuses for UI */
+  steps: {
+    created: StepStatus;
+    verifying: StepStatus;
+    issuing: StepStatus;
+  };
+}
+
+/**
+ * Options for deposit monitoring
+ */
+export interface MonitorOptions {
+  /** Function to fetch deposit information */
+  fetchDeposit: () => Promise<DepositInfo | undefined>;
+  /** Bitcoin network mode */
+  network: NetworkMode;
+  /** BTC service for block height queries */
+  btcService: BtcService;
+  /** Number of confirmations required (default: 6) */
+  requiredConfirmations?: number;
+  /** Callback for progress updates */
+  onProgress?: (progress: MonitorProgress) => void;
+  /** Callback when deposit is fully claimed */
+  onComplete?: () => void;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Monitor Function
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Monitor a Bitcoin deposit for confirmations and minting
+ *
+ * This is a single-shot check. For continuous monitoring, call this
+ * function repeatedly with a timer/interval.
+ *
+ * @param options - Monitoring options
+ * @returns Progress information or undefined if deposit not found
+ *
+ * @example
+ * ```typescript
+ * const progress = await monitorDeposit({
+ *   fetchDeposit: async () => {
+ *     const deposits = await getDepositsByAddress({ address, env });
+ *     return deposits.find(d => d.depositAddress === myAddress);
+ *   },
+ *   network: 'mainnet',
+ *   btcService: ctx.btc,
+ *   onProgress: (p) => console.log(`${p.confirmations}/${p.requiredConfirmations}`),
+ *   onComplete: () => console.log('Deposit complete!'),
+ * });
+ * ```
+ */
+export async function monitorDeposit(
+  options: MonitorOptions,
+): Promise<MonitorProgress | undefined> {
+  const {
+    fetchDeposit,
+    network,
+    btcService,
+    requiredConfirmations = 6,
+    onProgress,
+    onComplete,
+  } = options;
+
+  // Fetch current deposit status
+  const deposit = await fetchDeposit();
+  if (!deposit) {
+    return undefined;
+  }
+
+  const blockHeight = deposit.blockHeight;
+  if (typeof blockHeight !== 'number') {
+    return undefined;
+  }
+
+  // Get current block height and calculate confirmations
+  const currentBlockHeight = await btcService.getCurrentBlockHeight(network);
+  const confirmations = Math.max(0, currentBlockHeight - blockHeight);
+  const hasEnoughConfirmations = confirmations >= requiredConfirmations;
+  const isClaimed = deposit.isClaimed ?? false;
+
+  // Build progress object
+  const progress: MonitorProgress = {
+    confirmations,
+    requiredConfirmations,
+    hasEnoughConfirmations,
+    isClaimed,
+    steps: {
+      created: StepStatus.COMPLETE,
+      verifying: hasEnoughConfirmations
+        ? StepStatus.COMPLETE
+        : StepStatus.PENDING,
+      issuing: isClaimed ? StepStatus.COMPLETE : StepStatus.PENDING,
+    },
+  };
+
+  // Emit callbacks
+  onProgress?.(progress);
+  if (isClaimed) {
+    onComplete?.();
+  }
+
+  return progress;
+}
+
+/**
+ * Create a polling monitor that checks deposit status at intervals
+ *
+ * @param options - Monitoring options
+ * @param intervalMs - Polling interval in milliseconds (default: 30000)
+ * @returns Stop function to cancel monitoring
+ *
+ * @example
+ * ```typescript
+ * const stop = createPollingMonitor({
+ *   fetchDeposit,
+ *   network: 'mainnet',
+ *   btcService: ctx.btc,
+ *   onProgress: updateUI,
+ *   onComplete: () => {
+ *     stop(); // Stop polling when complete
+ *     showSuccess();
+ *   },
+ * }, 30000);
+ *
+ * // Later: stop monitoring
+ * stop();
+ * ```
+ */
+export function createPollingMonitor(
+  options: MonitorOptions,
+  intervalMs = 30000,
+): () => void {
+  let stopped = false;
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+  const poll = async () => {
+    if (stopped) return;
+
+    try {
+      const progress = await monitorDeposit(options);
+
+      // Stop polling if claimed
+      if (progress?.isClaimed) {
+        stopped = true;
+        return;
+      }
+    } catch (error) {
+      // Continue polling on error
+      console.warn('Deposit monitor poll failed:', error);
+    }
+
+    // Schedule next poll
+    if (!stopped) {
+      timeoutId = setTimeout(poll, intervalMs);
+    }
+  };
+
+  // Start polling
+  poll();
+
+  // Return stop function
+  return () => {
+    stopped = true;
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+  };
+}

package/src/shared/monitoring/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Monitoring Utilities
+ *
+ * @module shared/monitoring
+ */
+
+export {
+  createPollingMonitor,
+  type DepositInfo,
+  monitorDeposit,
+  type MonitorOptions,
+  type MonitorProgress,
+  type NetworkMode,
+} from './depositMonitor';
+
+// Re-export existing utilities
+export {
+  createEventEmitter,
+  type EventEmitter,
+  type EventHandler,
+} from './createEventEmitter';
+export {
+  createProgressEmitter,
+  type ProgressEmitter,
+} from './createProgressEmitter';

package/src/shared/validation/index.ts

@@ -0,0 +1,411 @@
+/**
+ * Validation Schemas
+ *
+ * Centralized Zod schemas for validating SDK inputs.
+ * These provide type-safe, declarative validation with clear error messages.
+ *
+ * @module shared/validation
+ */
+
+import * as bitcoin from 'bitcoinjs-lib';
+import { z } from 'zod';
+
+import { MIN_STAKE_AMOUNT_BTC } from '../../common/constants';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Address Validation Helpers
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Validate a Bitcoin address using bitcoinjs-lib
+ * This validates the checksum for all address types:
+ * - Legacy P2PKH (1..., m..., n...)
+ * - P2SH (3..., 2...)
+ * - SegWit bech32 (bc1q..., tb1q...)
+ * - Taproot bech32m (bc1p..., tb1p...)
+ *
+ * @param address - The address to validate
+ * @returns true if valid, false otherwise
+ */
+export function isValidBitcoinAddress(address: string): boolean {
+  if (!address || typeof address !== 'string') {
+    return false;
+  }
+
+  // Bech32/Bech32m addresses (bc1..., tb1...)
+  if (address.startsWith('bc1') || address.startsWith('tb1')) {
+    try {
+      bitcoin.address.fromBech32(address);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // Legacy and P2SH addresses (base58check)
+  try {
+    bitcoin.address.fromBase58Check(address);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Validate a Solana address (base58 with proper structure)
+ * Solana addresses are ed25519 public keys encoded in base58
+ *
+ * Note: Unlike Bitcoin, Solana addresses don't have a built-in checksum.
+ * We validate that the address decodes to exactly 32 bytes.
+ *
+ * @param address - The address to validate
+ * @returns true if valid, false otherwise
+ */
+export function isValidSolanaAddress(address: string): boolean {
+  // Base58 character set (no 0, O, I, l)
+  const base58Regex = /^[1-9A-HJ-NP-Za-km-z]+$/;
+
+  if (!address || typeof address !== 'string') {
+    return false;
+  }
+
+  if (!base58Regex.test(address)) {
+    return false;
+  }
+
+  // Solana addresses are exactly 32 bytes when decoded
+  // In base58, this results in 32-44 characters
+  if (address.length < 32 || address.length > 44) {
+    return false;
+  }
+
+  // Validate the base58 decoding produces exactly 32 bytes
+  try {
+    const decoded = decodeBase58(address);
+    return decoded.length === 32;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Base58 decoder for validation purposes
+ * Based on the Bitcoin/Solana base58 alphabet
+ */
+function decodeBase58(str: string): Uint8Array {
+  const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+  const ALPHABET_MAP: Record<string, number> = {};
+  for (let i = 0; i < ALPHABET.length; i++) {
+    ALPHABET_MAP[ALPHABET[i]] = i;
+  }
+
+  if (str.length === 0) {
+    return new Uint8Array(0);
+  }
+
+  // Count leading zeros (represented by '1' in base58)
+  let leadingZeros = 0;
+  for (let i = 0; i < str.length && str[i] === '1'; i++) {
+    leadingZeros++;
+  }
+
+  // Decode the rest
+  const size = Math.ceil((str.length * Math.log(58)) / Math.log(256));
+  const bytes = new Uint8Array(size);
+
+  for (let i = leadingZeros; i < str.length; i++) {
+    const value = ALPHABET_MAP[str[i]];
+    if (value === undefined) {
+      throw new Error(`Invalid base58 character: ${str[i]}`);
+    }
+
+    let carry = value;
+    for (let j = size - 1; j >= 0; j--) {
+      carry += 58 * bytes[j];
+      bytes[j] = carry % 256;
+      carry = Math.floor(carry / 256);
+    }
+  }
+
+  // Find first non-zero byte
+  let firstNonZero = 0;
+  while (firstNonZero < bytes.length && bytes[firstNonZero] === 0) {
+    firstNonZero++;
+  }
+
+  // Combine leading zeros with decoded bytes
+  const result = new Uint8Array(leadingZeros + (bytes.length - firstNonZero));
+  result.fill(0, 0, leadingZeros);
+  result.set(bytes.subarray(firstNonZero), leadingZeros);
+
+  return result;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Amount Schemas
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Create an amount schema with configurable minimum
+ *
+ * @param minAmount - Minimum amount in human-readable format (e.g., 0.0002)
+ * @returns Zod schema for amount validation
+ */
+export function createAmountSchema(minAmount?: number) {
+  const baseSchema = z
+    .string({ message: 'Amount is required' })
+    .min(1, 'Amount is required')
+    .refine(val => val !== '0', {
+      message: 'Amount must be greater than 0',
+    })
+    .refine(
+      val => {
+        const num = Number.parseFloat(val);
+        return !Number.isNaN(num) && num > 0;
+      },
+      { message: 'Invalid amount format' },
+    );
+
+  if (minAmount !== undefined && minAmount > 0) {
+    return baseSchema.refine(
+      val => {
+        const num = Number.parseFloat(val);
+        return num >= minAmount;
+      },
+      { message: `Amount must be at least ${minAmount}` },
+    );
+  }
+
+  return baseSchema;
+}
+
+/**
+ * Amount validation (human-readable string, e.g., "0.1")
+ *
+ * Validates:
+ * - Non-empty string
+ * - Not "0"
+ * - Parses to positive number
+ *
+ * Used for both BTC and EVM amounts.
+ */
+export const amountSchema = createAmountSchema();
+
+/**
+ * BTC stake amount schema with minimum 0.0002 BTC
+ */
+export const btcStakeAmountSchema = createAmountSchema(MIN_STAKE_AMOUNT_BTC);
+
+/** @deprecated Use amountSchema instead */
+export const btcAmountSchema = amountSchema;
+
+/** Alias for EVM operations */
+export const evmAmountSchema = amountSchema;
+
+/**
+ * Satoshi amount validation (bigint or number)
+ */
+export const satoshiAmountSchema = z
+  .union([z.bigint(), z.number()])
+  .refine(val => val > 0, { message: 'Amount must be greater than 0' });
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Address Schemas
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * EVM address validation (0x + 40 hex chars)
+ */
+export const evmAddressSchema = z
+  .string({ message: 'Address is required' })
+  .regex(/^0x[a-fA-F0-9]{40}$/, 'Invalid EVM address format');
+
+/**
+ * Solana address validation (base58, exactly 32 bytes when decoded)
+ * Uses proper base58 decoding to verify the address structure
+ */
+export const solanaAddressSchema = z
+  .string({ message: 'Address is required' })
+  .refine(isValidSolanaAddress, { message: 'Invalid Solana address format' });
+
+/**
+ * Sui address validation (0x + 64 hex chars)
+ */
+export const suiAddressSchema = z
+  .string({ message: 'Address is required' })
+  .regex(/^0x[a-fA-F0-9]{64}$/, 'Invalid Sui address format');
+
+/**
+ * Starknet address validation (0x + 1-64 hex chars)
+ */
+export const starknetAddressSchema = z
+  .string({ message: 'Address is required' })
+  .regex(/^0x[a-fA-F0-9]{1,64}$/, 'Invalid Starknet address format');
+
+/**
+ * Bitcoin address validation with proper checksum verification
+ * Uses bitcoinjs-lib to validate all address formats:
+ * - Legacy P2PKH (1..., m..., n...)
+ * - P2SH (3..., 2...)
+ * - SegWit bech32 (bc1q..., tb1q...)
+ * - Taproot bech32m (bc1p..., tb1p...)
+ */
+export const bitcoinAddressSchema = z
+  .string({ message: 'Address is required' })
+  .refine(isValidBitcoinAddress, { message: 'Invalid Bitcoin address format' });
+
+/**
+ * Map of chain type to address schema
+ */
+export const addressSchemasByChainType = {
+  evm: evmAddressSchema,
+  solana: solanaAddressSchema,
+  sui: suiAddressSchema,
+  starknet: starknetAddressSchema,
+  bitcoin: bitcoinAddressSchema,
+} as const;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Common Schemas
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Referral code validation (optional string)
+ */
+export const referralCodeSchema = z.string().optional();
+
+/**
+ * Transaction hash validation (0x + 64 hex chars)
+ */
+export const txHashSchema = z
+  .string()
+  .regex(/^0x[a-fA-F0-9]{64}$/, 'Invalid transaction hash');
+
+// ═══════════════════════════════════════════════════════════════════════════
+// BTC Stake Schemas
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * BTC Stake prepare params schema (base - recipient validated separately per chain)
+ */
+export const btcStakePrepareBaseSchema = z.object({
+  amount: btcStakeAmountSchema,
+  recipient: z
+    .string({ message: 'Recipient is required' })
+    .min(1, 'Recipient is required'),
+  referralCode: referralCodeSchema,
+});
+
+/**
+ * Create a prepare schema with chain-specific address validation
+ */
+export function createBtcStakePrepareSchema(addressSchema: z.ZodString) {
+  return z.object({
+    amount: btcStakeAmountSchema,
+    recipient: addressSchema,
+    referralCode: referralCodeSchema,
+  });
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Type Exports
+// ═══════════════════════════════════════════════════════════════════════════
+
+export type Amount = z.infer<typeof amountSchema>;
+/** @deprecated Use Amount instead */
+export type BtcAmount = Amount;
+export type EvmAddress = z.infer<typeof evmAddressSchema>;
+export type SolanaAddress = z.infer<typeof solanaAddressSchema>;
+export type SuiAddress = z.infer<typeof suiAddressSchema>;
+export type StarknetAddress = z.infer<typeof starknetAddressSchema>;
+export type BitcoinAddress = z.infer<typeof bitcoinAddressSchema>;
+export type BtcStakePrepareParams = z.infer<typeof btcStakePrepareBaseSchema>;
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Validation Helpers
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { Chain } from '../../core';
+import { LombardError } from '../errors';
+
+/**
+ * Validation error handler configuration
+ */
+export interface ValidationErrorConfig {
+  /** Chain for address validation errors (optional) */
+  destChain?: Chain;
+}
+
+/**
+ * Validate prepare params with standard error handling
+ *
+ * This helper provides consistent Zod validation with LombardError mapping:
+ * - 'amount' field → LombardError.invalidAmount()
+ * - 'recipient' field → LombardError.invalidAddress()
+ * - Other fields → LombardError.invalidParameter()
+ *
+ * @example
+ * ```typescript
+ * private validatePrepareParams(params: PrepareParams) {
+ *   return validatePrepareParams(this.prepareSchema, params, {
+ *     destChain: this.params.destChain,
+ *   });
+ * }
+ * ```
+ */
+export function validatePrepareParams<T>(
+  schema: z.ZodSchema<T>,
+  params: unknown,
+  config: ValidationErrorConfig = {},
+): T {
+  const result = schema.safeParse(params);
+
+  if (!result.success) {
+    const firstIssue = result.error.issues[0];
+    const path = firstIssue?.path[0];
+    const message = firstIssue?.message ?? 'Invalid parameter';
+
+    if (path === 'amount') {
+      throw LombardError.invalidAmount(message);
+    }
+    if (path === 'recipient') {
+      throw LombardError.invalidAddress(
+        (params as Record<string, unknown>)?.recipient as string,
+        config.destChain,
+      );
+    }
+    throw LombardError.invalidParameter(String(path), message);
+  }
+
+  return result.data;
+}
+
+/**
+ * Validate and parse input, throwing error on failure
+ */
+export function validateOrThrow<T>(
+  schema: z.ZodSchema<T>,
+  data: unknown,
+  errorFactory: (message: string) => Error,
+): T {
+  const result = schema.safeParse(data);
+  if (!result.success) {
+    const firstIssue = result.error.issues[0];
+    throw errorFactory(firstIssue?.message ?? 'Validation failed');
+  }
+  return result.data;
+}
+
+/**
+ * Validate input, returning result object
+ */
+export function validate<T>(
+  schema: z.ZodSchema<T>,
+  data: unknown,
+): { success: true; data: T } | { success: false; error: z.ZodError } {
+  const result = schema.safeParse(data);
+  if (result.success) {
+    return { success: true, data: result.data };
+  }
+  return { success: false, error: result.error };
+}

package/src/stories/arg-types.ts

@@ -1,5 +1,6 @@
 import { Env } from '@lombard.finance/sdk-common';
 import { ArgTypes } from 'storybook/internal/types';
+
 import { ChainId } from '../common/chains';
 import { Token } from '../tokens/token-addresses';
 

package/src/stories/components/Badge.tsx

@@ -0,0 +1,27 @@
+import { type ReactNode } from 'react';
+
+interface BadgeProps {
+  children: ReactNode;
+  variant?:
+    | 'primary'
+    | 'secondary'
+    | 'success'
+    | 'danger'
+    | 'warning'
+    | 'info'
+    | 'light'
+    | 'dark';
+  className?: string;
+}
+
+/**
+ * Reusable badge component for displaying labels and tags
+ * Supports Bootstrap color variants
+ */
+export function Badge({
+  children,
+  variant = 'secondary',
+  className = '',
+}: BadgeProps) {
+  return <span className={`badge bg-${variant} ${className}`}>{children}</span>;
+}

package/src/stories/components/Button/Button.tsx

@@ -1,6 +1,8 @@
+import './Button.css';
+
 import React from 'react';
+
 import { Spinner } from '../Spinner';
-import './Button.css';
 
 export interface ButtonProps {
   disabled?: boolean;
@@ -16,7 +18,7 @@ export interface ButtonProps {
  * Execute action button
  */
 export const Button = ({
-  primary = true,
+  primary: _primary = true,
   size = 'medium',
   actionName,
   children,