@sip-protocol/sdk 0.1.0 → 0.1.4

package/src/wallet/hardware/types.ts

@@ -0,0 +1,317 @@
+/**
+ * Hardware Wallet Types
+ *
+ * Type definitions for hardware wallet adapters (Ledger, Trezor).
+ */
+
+import type { ChainId, HexString } from '@sip-protocol/types'
+
+// ─── Device Types ───────────────────────────────────────────────────────────────
+
+/**
+ * Supported hardware wallet manufacturers
+ */
+export type HardwareWalletType = 'ledger' | 'trezor'
+
+/**
+ * Ledger device models
+ */
+export type LedgerModel = 'nanoS' | 'nanoSPlus' | 'nanoX' | 'stax' | 'flex'
+
+/**
+ * Trezor device models
+ */
+export type TrezorModel = 'one' | 'T' | 'safe3' | 'safe5'
+
+/**
+ * Hardware wallet connection status
+ */
+export type HardwareConnectionStatus =
+  | 'disconnected'
+  | 'connecting'
+  | 'connected'
+  | 'locked'
+  | 'app_closed'
+  | 'error'
+
+/**
+ * Transport type for device communication
+ */
+export type TransportType = 'usb' | 'bluetooth' | 'webusb' | 'webhid'
+
+// ─── Device Info ────────────────────────────────────────────────────────────────
+
+/**
+ * Hardware device information
+ */
+export interface HardwareDeviceInfo {
+  /** Device manufacturer */
+  manufacturer: HardwareWalletType
+  /** Device model */
+  model: string
+  /** Firmware version */
+  firmwareVersion?: string
+  /** Whether device is locked */
+  isLocked: boolean
+  /** Currently open app (if any) */
+  currentApp?: string
+  /** Device label/name (user-set) */
+  label?: string
+  /** Device ID (unique identifier) */
+  deviceId?: string
+}
+
+// ─── Derivation Paths ───────────────────────────────────────────────────────────
+
+/**
+ * Standard BIP44 derivation paths
+ */
+export const DerivationPath = {
+  /** Ethereum: m/44'/60'/0'/0/index */
+  ETHEREUM: "m/44'/60'/0'/0",
+  /** Ethereum (Ledger Live): m/44'/60'/index'/0/0 */
+  ETHEREUM_LEDGER_LIVE: "m/44'/60'",
+  /** Solana: m/44'/501'/0'/0' */
+  SOLANA: "m/44'/501'/0'/0'",
+  /** Bitcoin: m/84'/0'/0'/0 (native segwit) */
+  BITCOIN: "m/84'/0'/0'/0",
+  /** NEAR: m/44'/397'/0' */
+  NEAR: "m/44'/397'/0'",
+} as const
+
+/**
+ * Get derivation path for a chain
+ */
+export function getDerivationPath(chain: ChainId, accountIndex: number = 0): string {
+  switch (chain) {
+    case 'ethereum':
+      return `${DerivationPath.ETHEREUM}/${accountIndex}`
+    case 'solana':
+      return DerivationPath.SOLANA.replace("0'", `${accountIndex}'`)
+    case 'bitcoin':
+      return `${DerivationPath.BITCOIN}/${accountIndex}`
+    case 'near':
+      return DerivationPath.NEAR.replace("0'", `${accountIndex}'`)
+    default:
+      return `${DerivationPath.ETHEREUM}/${accountIndex}`
+  }
+}
+
+// ─── Configuration ──────────────────────────────────────────────────────────────
+
+/**
+ * Base hardware wallet configuration
+ */
+export interface HardwareWalletConfig {
+  /** Target chain */
+  chain: ChainId
+  /** Account index (default: 0) */
+  accountIndex?: number
+  /** Custom derivation path (overrides default) */
+  derivationPath?: string
+  /** Transport type preference */
+  transport?: TransportType
+  /** Connection timeout in ms (default: 30000) */
+  timeout?: number
+}
+
+/**
+ * Ledger-specific configuration
+ */
+export interface LedgerConfig extends HardwareWalletConfig {
+  /** Expected app name to be open on device */
+  appName?: string
+  /** Whether to use Ledger Live derivation path */
+  useLedgerLive?: boolean
+  /** Scramble key for transport */
+  scrambleKey?: string
+}
+
+/**
+ * Trezor-specific configuration
+ */
+export interface TrezorConfig extends HardwareWalletConfig {
+  /** Trezor Connect manifest URL */
+  manifestUrl?: string
+  /** Trezor Connect manifest email */
+  manifestEmail?: string
+  /** Trezor Connect manifest app name */
+  manifestAppName?: string
+  /** Whether to use popup for Trezor Connect */
+  popup?: boolean
+}
+
+// ─── Signing Requests ───────────────────────────────────────────────────────────
+
+/**
+ * Hardware wallet signing request
+ */
+export interface HardwareSignRequest {
+  /** Raw message to sign */
+  message: Uint8Array
+  /** Display message on device (if supported) */
+  displayMessage?: string
+  /** Whether this is a transaction (vs arbitrary message) */
+  isTransaction?: boolean
+}
+
+/**
+ * Ethereum transaction for hardware signing
+ */
+export interface HardwareEthereumTx {
+  /** Recipient address */
+  to: string
+  /** Value in wei (hex) */
+  value: HexString
+  /** Gas limit (hex) */
+  gasLimit: HexString
+  /** Gas price (hex) - for legacy tx */
+  gasPrice?: HexString
+  /** Max fee per gas (hex) - for EIP-1559 */
+  maxFeePerGas?: HexString
+  /** Max priority fee per gas (hex) - for EIP-1559 */
+  maxPriorityFeePerGas?: HexString
+  /** Transaction data (hex) */
+  data?: HexString
+  /** Nonce (hex) */
+  nonce: HexString
+  /** Chain ID */
+  chainId: number
+}
+
+/**
+ * Signature from hardware wallet
+ */
+export interface HardwareSignature {
+  /** r component */
+  r: HexString
+  /** s component */
+  s: HexString
+  /** v component (recovery id) */
+  v: number
+  /** Full signature (r + s + v) */
+  signature: HexString
+}
+
+// ─── Account Info ───────────────────────────────────────────────────────────────
+
+/**
+ * Account derived from hardware wallet
+ */
+export interface HardwareAccount {
+  /** Account address */
+  address: string
+  /** Public key (hex) */
+  publicKey: HexString
+  /** Derivation path used */
+  derivationPath: string
+  /** Account index */
+  index: number
+  /** Chain */
+  chain: ChainId
+}
+
+// ─── Transport Interfaces ───────────────────────────────────────────────────────
+
+/**
+ * Abstract transport interface for hardware communication
+ *
+ * This is implemented by actual transport libraries:
+ * - @ledgerhq/hw-transport-webusb
+ * - @ledgerhq/hw-transport-webhid
+ * - @trezor/connect-web
+ */
+export interface HardwareTransport {
+  /** Open connection to device */
+  open(): Promise<void>
+  /** Close connection */
+  close(): Promise<void>
+  /** Send APDU command (Ledger) */
+  send?(cla: number, ins: number, p1: number, p2: number, data?: Buffer): Promise<Buffer>
+  /** Check if transport is open */
+  isOpen?: boolean
+}
+
+// ─── Error Types ────────────────────────────────────────────────────────────────
+
+/**
+ * Hardware wallet error codes
+ */
+export const HardwareErrorCode = {
+  /** Device not found/connected */
+  DEVICE_NOT_FOUND: 'HARDWARE_DEVICE_NOT_FOUND',
+  /** Device is locked (requires PIN) */
+  DEVICE_LOCKED: 'HARDWARE_DEVICE_LOCKED',
+  /** Required app not open on device */
+  APP_NOT_OPEN: 'HARDWARE_APP_NOT_OPEN',
+  /** User rejected on device */
+  USER_REJECTED: 'HARDWARE_USER_REJECTED',
+  /** Transport/communication error */
+  TRANSPORT_ERROR: 'HARDWARE_TRANSPORT_ERROR',
+  /** Timeout waiting for device */
+  TIMEOUT: 'HARDWARE_TIMEOUT',
+  /** Unsupported operation */
+  UNSUPPORTED: 'HARDWARE_UNSUPPORTED',
+  /** Invalid derivation path */
+  INVALID_PATH: 'HARDWARE_INVALID_PATH',
+} as const
+
+export type HardwareErrorCodeType = typeof HardwareErrorCode[keyof typeof HardwareErrorCode]
+
+/**
+ * Hardware wallet error
+ */
+export class HardwareWalletError extends Error {
+  readonly code: HardwareErrorCodeType
+  readonly device?: HardwareWalletType
+  readonly details?: unknown
+
+  constructor(
+    message: string,
+    code: HardwareErrorCodeType,
+    device?: HardwareWalletType,
+    details?: unknown
+  ) {
+    super(message)
+    this.name = 'HardwareWalletError'
+    this.code = code
+    this.device = device
+    this.details = details
+  }
+}
+
+// ─── Utilities ──────────────────────────────────────────────────────────────────
+
+/**
+ * Check if browser supports WebUSB
+ */
+export function supportsWebUSB(): boolean {
+  return typeof navigator !== 'undefined' && 'usb' in navigator
+}
+
+/**
+ * Check if browser supports WebHID
+ */
+export function supportsWebHID(): boolean {
+  return typeof navigator !== 'undefined' && 'hid' in navigator
+}
+
+/**
+ * Check if browser supports Web Bluetooth
+ */
+export function supportsWebBluetooth(): boolean {
+  return typeof navigator !== 'undefined' && 'bluetooth' in navigator
+}
+
+/**
+ * Get available transport types
+ */
+export function getAvailableTransports(): TransportType[] {
+  const transports: TransportType[] = []
+
+  if (supportsWebUSB()) transports.push('webusb')
+  if (supportsWebHID()) transports.push('webhid')
+  if (supportsWebBluetooth()) transports.push('bluetooth')
+
+  return transports
+}

package/src/wallet/index.ts

@@ -84,6 +84,46 @@ export type {
   MockEthereumAdapterConfig,
 } from './ethereum'
 
+// Hardware wallet adapters
+export {
+  // Types
+  type HardwareWalletType,
+  type LedgerModel,
+  type TrezorModel,
+  type HardwareConnectionStatus,
+  type TransportType,
+  type HardwareDeviceInfo,
+  type HardwareWalletConfig,
+  type LedgerConfig,
+  type TrezorConfig,
+  type HardwareSignRequest,
+  type HardwareEthereumTx,
+  type HardwareSignature,
+  type HardwareAccount,
+  type HardwareTransport,
+  type HardwareErrorCodeType,
+  type MockHardwareConfig,
+  HardwareErrorCode,
+  HardwareWalletError,
+  DerivationPath,
+  getDerivationPath,
+  supportsWebUSB,
+  supportsWebHID,
+  supportsWebBluetooth,
+  getAvailableTransports,
+  // Ledger
+  LedgerWalletAdapter,
+  createLedgerAdapter,
+  // Trezor
+  TrezorWalletAdapter,
+  createTrezorAdapter,
+  // Mocks
+  MockLedgerAdapter,
+  MockTrezorAdapter,
+  createMockLedgerAdapter,
+  createMockTrezorAdapter,
+} from './hardware'
+
 // Re-export types from types package for convenience
 export type {
   // Core types

package/src/zcash/shielded-service.ts

@@ -369,11 +369,14 @@ export class ZcashShieldedService {
       )
     }
 
+    // Get fee from operation result, fall back to params.fee or estimate
+    const fee = operation.result.fee ?? params.fee ?? this.estimateFee(1)
+
     return {
       txid: operation.result.txid,
       operationId,
       amount: params.amount,
-      fee: params.fee ?? 0, // TODO: Get actual fee from operation
+      fee,
       to: params.to,
       from: fromAddress,
       timestamp: Math.floor(Date.now() / 1000),
@@ -561,6 +564,61 @@ export class ZcashShieldedService {
     return this.client.isTestnet
   }
 
+  // ─── Fee Estimation ──────────────────────────────────────────────────────────
+
+  /**
+   * ZIP-317 fee constants (in ZEC)
+   * @see https://zips.z.cash/zip-0317
+   */
+  private static readonly ZIP317_MARGINAL_FEE = 0.00005 // 5000 zatoshis per logical action
+  private static readonly ZIP317_GRACE_ACTIONS = 2 // First 2 actions are free
+  private static readonly ZIP317_P2PKH_STANDARD_INPUT_SIZE = 150
+  private static readonly ZIP317_P2PKH_STANDARD_OUTPUT_SIZE = 34
+
+  /**
+   * Estimate transaction fee based on ZIP-317 conventional fee
+   *
+   * The ZIP-317 fee is calculated as:
+   * fee = marginal_fee * max(grace_actions, logical_actions)
+   *
+   * For shielded transactions:
+   * - Each Sapling spend = 1 logical action
+   * - Each Sapling output = 1 logical action
+   * - Each Orchard action = 1 logical action (covers both spend and output)
+   *
+   * @param recipients - Number of recipients (outputs)
+   * @param inputs - Estimated number of input notes (default: 1)
+   * @returns Estimated fee in ZEC
+   *
+   * @example
+   * ```typescript
+   * // Estimate fee for 1 recipient
+   * const fee = service.estimateFee(1)
+   *
+   * // Estimate fee for 3 recipients with 2 input notes
+   * const fee = service.estimateFee(3, 2)
+   * ```
+   */
+  estimateFee(recipients: number = 1, inputs: number = 1): number {
+    // For shielded transactions, logical actions = inputs + outputs
+    // Plus 1 for change output in most cases
+    const logicalActions = inputs + recipients + 1
+
+    // ZIP-317: fee = marginal_fee * max(grace_actions, logical_actions)
+    const billableActions = Math.max(ZcashShieldedService.ZIP317_GRACE_ACTIONS, logicalActions)
+
+    return billableActions * ZcashShieldedService.ZIP317_MARGINAL_FEE
+  }
+
+  /**
+   * Get minimum fee for a shielded transaction
+   *
+   * @returns Minimum fee in ZEC (ZIP-317 with grace actions)
+   */
+  getMinimumFee(): number {
+    return ZcashShieldedService.ZIP317_GRACE_ACTIONS * ZcashShieldedService.ZIP317_MARGINAL_FEE
+  }
+
   // ─── Helpers ─────────────────────────────────────────────────────────────────
 
   /**