API Reference

interface ITransport {
  open(): Promise<void>
  close(): Promise<void>
  isConnected(): boolean
  exchange(apdu: Uint8Array): Promise<Uint8Array>
  lock(): Promise<void>
  unlock(): Promise<void>
}

interface TransportStatus {
  connected: boolean
  deviceName?: string
  deviceId?: string
}

type TransportEventType = 'connected' | 'disconnected' | 'error'

interface TransportEvent {
  type: TransportEventType
  error?: Error
}

type TransportEventHandler = (event: TransportEvent) => void

interface TransportInfo {
  type: string        // Registered name (e.g. 'webhid')
  name: string        // Display name (e.g. 'WebHID (USB)')
  available: boolean  // Whether it can be used
}

type TransportFactory = () => Promise<ITransport>

interface BtcMessageSignature {
  v: number       // BIP-137 header byte (see the table below)
  r: string       // R value (32 bytes hex)
  s: string       // S value (32 bytes hex)
  signature: string // Full signature (V || R || S, 65 bytes) in Base64
}

interface InputSigningPath {
  index: number   // Input index in the PSBT
  path: string    // BIP32 path (e.g. "84'/1'/0'/0/5")
}

interface XrpSignatureResult {
  signature: string  // Signature hex (Ed25519: 64B, secp256k1: variable-length DER)
}

type XrpCurve = 'ed25519' | 'secp256k1'

interface SignatureResult {
  v: number    // Recovery ID
  r: string    // R value (32 bytes hex, no 0x prefix)
  s: string    // S value (32 bytes hex, no 0x prefix)
}

interface DeviceInfo {
  connected: boolean
  path?: string
  vendorId?: number
  productId?: number
}

interface WcSession {
  topic: string
}

interface IWcSignClient {
  request<T>(params: {
    topic: string
    chainId: string
    request: { method: string; params: unknown }
  }): Promise<T>
}

interface WcTransportOptions {
  client: IWcSignClient
  session: WcSession
  chainId?: string  // Default: "eip155:1"
}

class BitcoinApp {
  static readonly sdkBuildId: string

  constructor(transport: ITransport)

  getAddress(testnet?: boolean): Promise<{ publicKey: string; address: string; chainCode: string }>

  getAddressWithPath(path: string): Promise<{ publicKey: string; address: string; chainCode: string }>

  getAccountXpub(coinType: number): Promise<{ publicKey: string; chainCode: string }>

  getExtendedPubkey(path: string, display?: boolean): Promise<BtcXpub>

  getMasterFingerprint(): Promise<string>  // hash160(master pubkey)[:4], 8-char hex (e.g. "631698e0")

  signMessage(message: string, path: string): Promise<BtcMessageSignature>

  signPsbt(psbt: Uint8Array | string): Promise<Uint8Array>

  signPsbtHex(psbt: string): Promise<string>

  signPsbtWithPaths(psbt: string, inputPaths: InputSigningPath[]): Promise<string>
}

// Build the APDU data for getExtendedPubkey (pure function). path is "m/84'/1'/0'" / "84'/1'/0'" / "m" (root)
function buildExtendedPubkeyRequest(path: string, display?: boolean): Uint8Array

// Parse the getExtendedPubkey response (a base58check string) (pure function).
// Checks that the answer is for requestedPath (depth, last level, version) and throws an Error if not
function parseExtendedPubkeyResponse(xpub: string, requestedPath: string): BtcXpub

const MAX_EXTENDED_PUBKEY_PATH_LEVELS = 10

type DeviceKind = 'openloop' | 'ledger'

class EthereumApp {
  static readonly sdkBuildId: string

  constructor(transport: ITransport)

  setKind(kind: DeviceKind): void

  getKind(): DeviceKind

  getAddress(path: string): Promise<{ publicKey: string; address: string }>

  getAddressWithChainCode(path: string): Promise<{ publicKey: string; address: string; chainCode: string }>

  signPersonalMessage(path: string, message: string, chainId?: number): Promise<SignatureResult>

  signTransaction(path: string, rawTx: string): Promise<SignatureResult>

  signTypedData(
    path: string, domainSeparatorHash: string, messageHash: string, chainId?: number
  ): Promise<SignatureResult>

  signTypedDataStreaming(path: string, typedData: TypedDataLike, chainId?: number): Promise<SignatureResult>

  signAuthorization(path: string, authorizationRlp: string): Promise<SignatureResult>
}

class XrpApp {
  static readonly sdkBuildId: string

  constructor(transport: ITransport)

  getAddress(path: string, curve?: XrpCurve): Promise<{ publicKey: string; address: string }>

  signTransaction(path: string, txBlob: string, curve?: XrpCurve): Promise<XrpSignatureResult>
}

class SolanaApp {
  static readonly sdkBuildId: string

  constructor(transport: ITransport)

  getAddress(path: string): Promise<{ publicKey: string; address: string }>

  signTransaction(path: string, txBytes: Uint8Array): Promise<string>

  signOffchainMessage(path: string, messageBytes: Uint8Array): Promise<string>
}

class TronApp {
  static readonly sdkBuildId: string

  constructor(transport: ITransport)

  getAddress(path: string): Promise<{ publicKey: string; address: string }>

  getAddressWithChainCode(path: string): Promise<{ publicKey: string; address: string; chainCode: string }>

  signTransaction(path: string, rawDataHex: string): Promise<SignatureResult>

  signMessage(path: string, message: string): Promise<SignatureResult>
}

class OpenloopApp {
  constructor(transport: ITransport)

  /**
   * Sends GET_DEVICE_INFO (F0 A0) and returns identification + state + feature info.
   *
   * Return value:
   *   - Returns null for old Openloop firmware (before v0.91.13) and for
   *     devices that do not support the command
   *   - Also returns null when sending/receiving the APDU fails (including a
   *     device rejection or a communication error)
   *   - Also returns null when the response is shorter than 16 bytes or does
   *     not start with "OL"
   *   - Throws if acquiring the lock fails
   */
  getDeviceInfo(): Promise<OpenloopDeviceInfo | null>
}

interface OpenloopDeviceInfo {
  modelId: number              // Hardware SKU ID (e.g. 0x0001 = Openloop V1)
  hwRevision: number           // PCB revision
  mainFwVersion: { major: number; minor: number; patch: number }
  recoveryFwVersion: { major: number; minor: number; patch: number }
  state: number                // 16-bit state bitmask (raw value)
  stateBits: OpenloopDeviceState  // Decoded view of state
  features: number             // 16-bit feature bitmask (implementation detail, subject to change)
}

interface OpenloopDeviceState {
  walletProvisioned: boolean
  language: number            // 0=English, 1=Japanese, 2-7=reserved
  usbEnabled: boolean
  usbVidCompat: boolean       // false=Native (0x303A), true=Compatible (0x2C97)
  bleEnabled: boolean
  blePaired: boolean
  fidoEnabled: boolean
  pivEnabled: boolean
}

import { OpenloopApp, formatOpenloopState } from '@openloop/sdk-core'

const app = new OpenloopApp(transport)
const info = await app.getDeviceInfo()

if (info === null) {
  console.log('GET_DEVICE_INFO not supported (old firmware)')
} else {
  console.log(`Model: 0x${info.modelId.toString(16).padStart(4, '0')}`)
  console.log(`FW: ${info.mainFwVersion.major}.${info.mainFwVersion.minor}.${info.mainFwVersion.patch}`)
  console.log(`State: ${formatOpenloopState(info.stateBits)}`)
  if (!info.stateBits.walletProvisioned) {
    // Branch for when no wallet has been created
  }
}

import {
  accountPathOf, deriveAddresses, scanAccount, getFeeRate, selectUtxos,
  fetchPrevTx, buildPsbt, extractRawTx, broadcastTx, BtcError,
  type BtcNetwork, type BtcAccount,
} from '@openloop/sdk-core/bitcoin'

type BtcNetworkId = 'mainnet' | 'testnet3' | 'testnet4'

interface BtcNetwork {
  id: BtcNetworkId
  esplora: string[]       // Esplora-compatible endpoints, tried in order (best first)
  feeEndpoints: string[]  // Endpoints that serve `/v1/fees/recommended` (mempool.space compatible)
  timeoutMs: number       // Time limit for one call (ms). The SDK has no default
}

type BtcScript = 'p2pkh' | 'p2sh-p2wpkh' | 'p2wpkh'   // purpose 44' / 49' / 84'

interface BtcAccount {
  script: BtcScript
  account: number         // Account number (below the hardened boundary 0x80000000)
}

interface BtcXpub {       // Extended public key received from the device (the return value of BitcoinApp.getExtendedPubkey)
  publicKey: string       // 33-byte compressed public key (hex)
  chainCode: string       // 32 bytes (hex)
  parentFingerprint: number  // Fingerprint of the immediate parent (not the master)
  depth: number           // Number of levels from m
  xpub: string            // The serialized string (xpub… / tpub…)
}

interface BtcUtxo {
  txid: string
  vout: number
  value: number           // sats
  address: string
  path: string            // In the form "m/84'/1'/0'/0/3"
  publicKey: string       // 33-byte compressed public key (hex)
  confirmed: boolean      // false below 1 confirmation
  blockHeight?: number
}

interface BtcAddressCache {
  get(address: string): { path: string; publicKey: string } | undefined
  set(address: string, entry: { path: string; publicKey: string }): void
  syncToDevice(deviceId: string | null): void
  readonly size: number
  clear(): void
}

type BtcAddressKind = 'p2pkh' | 'p2sh' | 'p2wpkh' | 'p2wsh' | 'p2tr'

interface BtcRecipient { address: string; value: number }   // value is in sats

interface BtcSelection {
  inputs: BtcUtxo[]
  fee: number             // Fee actually paid (sats) = total inputs − total outputs
  change: number          // Change (sats). 0 means no change output is created
  vbytes: number          // Estimated size (vB)
}

interface BtcScanResult {
  used: Array<{ address: string; path: string }>   // Addresses that have been used (both the receive and change chains)
  utxos: BtcUtxo[]
  nextChange: { index: number; address: string; path: string; publicKey: string }  // The next unused address to use for change
}

interface BtcPsbtInput extends BtcUtxo {
  prevTxHex?: string      // Required only for P2PKH: the raw hex of the previous transaction
}

interface BtcChangeOutput {
  address: string
  path: string
  publicKey: string
  value: number
}

interface BtcPsbt {
  psbtHex: string
  paths: Array<{ index: number; path: string }>   // The form to pass to BitcoinApp.signPsbtWithPaths
}

interface FetchDeps {     // Lookup settings that tests can replace
  fetchImpl?: typeof fetch
  retryDelayMs?: number   // Default 1000
  retryCount?: number     // Default 3 (attempts per URL)
}

function pathOf(acct: BtcAccount, net: BtcNetworkId, change: 0 | 1, index: number): string

function accountPathOf(acct: BtcAccount, net: BtcNetworkId): string

function deriveAddresses(
  xpub: BtcXpub,
  acct: BtcAccount,
  net: BtcNetworkId,
  change: 0 | 1,
  from: number,
  count: number
): Array<{ address: string; path: string; publicKey: string }>

function validateAddress(address: string, net: BtcNetworkId): { kind: BtcAddressKind }

function scanAccount(
  xpub: BtcXpub,
  acct: BtcAccount,
  net: BtcNetwork,
  opts?: {
    cache?: BtcAddressCache
    gapLimit?: number       // Default 20 (an integer ≥ 1)
    concurrency?: number    // Default 4 (an integer ≥ 1)
    knownUsed?: Array<{ chain: 0 | 1; index: number }>  // Indexes the caller already knows were used
  } & FetchDeps
): Promise<BtcScanResult>

function addressStats(
  address: string,
  net: BtcNetwork,
  deps?: FetchDeps
): Promise<BtcAddressStats>

interface BtcAddressStats {
  txCount: number   // Number of transactions (confirmed + unconfirmed). Greater than 0 means "used"
  funded: number    // Total received (sats, confirmed + unconfirmed)
  spent: number     // Total spent (sats, confirmed + unconfirmed). Balance is funded - spent
}

function fetchUtxos(
  addresses: Array<{ address: string; path: string; publicKey: string }>,
  net: BtcNetwork,
  deps?: FetchDeps
): Promise<BtcUtxo[]>

function fetchPrevTx(txid: string, net: BtcNetwork, deps?: FetchDeps): Promise<string>

function getFeeRate(net: BtcNetwork, deps?: FetchDeps): Promise<number>

function selectUtxos(
  utxos: BtcUtxo[],
  opts: {
    to: BtcRecipient[]
    feeRate: number
    script: BtcScript
    net: BtcNetworkId
    excluded?: Iterable<string>   // Spent markers "txid:vout"
    changeAddress?: string        // If omitted, change is counted as the same type as the inputs
  }
): BtcSelection

function buildPsbt(args: {
  script: BtcScript
  net: BtcNetworkId
  inputs: BtcPsbtInput[]
  to: Array<{ address: string; value: number }>
  change?: BtcChangeOutput    // Omit when no change output is created
}): BtcPsbt

function extractRawTx(signedPsbtHex: string): { rawTxHex: string; txid: string }

function broadcastTx(
  rawTxHex: string,
  net: BtcNetwork,
  expectedTxid?: string,
  deps?: FetchDeps
): Promise<string>

function createAddressCache(): BtcAddressCache

function findAddressPath(
  address: string,
  xpub: BtcXpub,
  acct: BtcAccount,
  net: BtcNetworkId,
  cache?: BtcAddressCache,
  opts?: { maxIndex?: number; step?: number }   // Defaults 200 / 20
): string | null

// Build the address of the given type from a compressed public key (hex, with or without 0x)
function publicKeyToAddress(publicKey: string, script: BtcScript, net: BtcNetworkId): string

// Estimate the transaction size (vB). outputVbytes is an array of OUTPUT_VBYTES values
function estimateVbytes(numInputs: number, script: BtcScript, outputVbytes: number[]): number

// Convert a recipient address to a scriptPubKey (with the same checks as validateAddress)
function addressToScriptPubKey(address: string, net: BtcNetworkId): Uint8Array

// Build and parse witness addresses (bech32 / bech32m)
function encodeSegwitAddress(hrp: string, version: number, program: Uint8Array): string
function decodeSegwitAddress(address: string): { hrp: string; version: number; program: Uint8Array }

// Fee rate (sat/vB)
const MIN_FEE_RATE_SAT_VB = 1
const MAX_FEE_RATE_SAT_VB = 5000

// Fee guards
const MAX_ABSOLUTE_FEE_SATS = 10_000_000        // 0.1 BTC
const MAX_FEE_FRACTION = 1.0                    // Upper limit of fee / send amount (100%)
const FEE_FRACTION_MIN_AMOUNT_SATS = 1_000_000  // The ratio guard is not applied to sends below this amount

// Construction
const DUST_SATS = 546                           // Change below this is not made into an output
const MAX_PREV_TX_BYTES = 4096                  // Upper limit of a previous transaction's size (the device limit)
const RBF_SEQUENCE = 0xfffffffd                 // sequence of every input

// Reading back a signed PSBT
const PSBT_RESPONSE_CHUNK_SIZE = 250            // Bytes per chunk
const PSBT_MAX_RESPONSE_CHUNKS = 256            // Number of chunks (the index is one byte, APDU P1)
const MAX_SIGNED_PSBT_BYTES = 64000             // 250 × 256

// Size estimates (vB)
const INPUT_VBYTES = { 'p2pkh': 148, 'p2sh-p2wpkh': 91, 'p2wpkh': 68 }
const OUTPUT_VBYTES = { p2wpkh: 31, p2tr: 43, p2wsh: 43, p2pkh: 34, p2sh: 32 }
const TX_OVERHEAD_VBYTES = 10.5

// Paths
const PURPOSE_OF_SCRIPT = { 'p2pkh': 44, 'p2sh-p2wpkh': 49, 'p2wpkh': 84 }
const COIN_TYPE_OF_NETWORK = { mainnet: 0, testnet3: 1, testnet4: 1 }

// Endpoint requests (the defaults of FetchDeps)
const API_RETRY_COUNT = 3            // Attempts per URL
const API_RETRY_DELAY_MS = 1000      // Interval between attempts (ms)
const API_PARALLEL_LIMIT = 4         // Number of lookups run at the same time

type BtcErrorCode =
  | 'bad_argument'              // Invalid argument (path, index, network/type combination, length). A caller mistake
  | 'invalid_address'           // Cannot be read as a recipient address (checksum, characters, length)
  | 'network_mismatch'          // Readable, but not an address of the current network
  | 'fetch_failed'              // Could not query the endpoints (all endpoints failed)
  | 'bad_response'              // An endpoint's answer is invalid (hash mismatch, wrong txid, etc.)
  | 'prev_tx_too_large'         // The previous transaction exceeds the device limit (4,096 B)
  | 'fee_rate_out_of_range'     // Fee rate out of range
  | 'insufficient'              // Insufficient balance
  | 'insufficient_unconfirmed'  // Sufficient if unconfirmed UTXOs are counted
  | 'fee_too_high'              // The fee exceeds the absolute cap
  | 'fee_exceeds_amount'        // The fee exceeds the send amount
  | 'psbt_too_large'            // The signed PSBT exceeds what can be read back (64,000 B)
  | 'bad_psbt'                  // Cannot be read as a PSBT
  | 'broadcast_rejected'        // The broadcast was not accepted

class BtcError extends OpenloopError {
  static readonly sdkBuildId: string
  name: string  // 'BtcError'
  readonly code: BtcErrorCode
  constructor(code: BtcErrorCode, message: string)
}

import { BitcoinApp } from '@openloop/sdk-core'
import {
  accountPathOf, scanAccount, getFeeRate, selectUtxos, buildPsbt,
  extractRawTx, broadcastTx, createAddressCache,
  type BtcNetwork, type BtcAccount,
} from '@openloop/sdk-core/bitcoin'

const net: BtcNetwork = {
  id: 'testnet3',
  esplora: ['https://blockstream.info/testnet/api', 'https://mempool.space/testnet/api'],
  feeEndpoints: ['https://mempool.space/testnet/api'],
  timeoutMs: 15_000,
}
const acct: BtcAccount = { script: 'p2wpkh', account: 0 }
const cache = createAddressCache()

const btc = new BitcoinApp(transport)

// 1. Get the account's extended public key ("m/84'/1'/0'") and tell the cache which device owns it
const xpub = await btc.getExtendedPubkey(accountPathOf(acct, net.id))
cache.syncToDevice(await btc.getMasterFingerprint())

// 2. Scan to get the UTXOs and the next change address
const { utxos, nextChange } = await scanAccount(xpub, acct, net, { cache })

// 3. Fetch the fee rate and choose the UTXOs to spend
const feeRate = await getFeeRate(net)
const to = [{ address: 'tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx', value: 50_000 }]
const sel = selectUtxos(utxos, { to, feeRate, script: acct.script, net: net.id, changeAddress: nextChange.address })

// 4. Build the PSBT, sign it on the device, extract the transaction, and broadcast it
const { psbtHex, paths } = buildPsbt({
  script: acct.script,
  net: net.id,
  inputs: sel.inputs,
  to,
  change: sel.change > 0 ? { ...nextChange, value: sel.change } : undefined,
})
const signedPsbtHex = await btc.signPsbtWithPaths(psbtHex, paths)
const { rawTxHex, txid } = extractRawTx(signedPsbtHex)
await broadcastTx(rawTxHex, net, txid)

import { fetchPrevTx, type BtcPsbtInput } from '@openloop/sdk-core/bitcoin'

const inputs: BtcPsbtInput[] = await Promise.all(
  sel.inputs.map(async (u) => ({ ...u, prevTxHex: await fetchPrevTx(u.txid, net) }))
)

import { BtcError } from '@openloop/sdk-core/bitcoin'

try {
  // …the flow above…
} catch (e) {
  if (e instanceof BtcError) {
    const code = e.code
    if (code === 'insufficient_unconfirmed') {
      // Tell the user: "You can send once the incoming funds confirm"
    }
  }
}

import { verifyPersonalSign } from '@openloop/sdk-core/verify'

const result = await verifyPersonalSign(message, sig, address)
// result: { recovered: string; expected?: string; ok: boolean }

// Return value (of every function)
interface VerifyResult {
  recovered: string   // The recovered signer (EVM: the address). For ed25519 verification, a string describing the result
  expected?: string
  ok: boolean
}

class OpenloopError extends Error {
  name: string  // 'OpenloopError'
}

class ApduError extends OpenloopError {
  name: string  // 'ApduError'
  readonly statusWord: number
  constructor(statusWord: number)
}

type TransportErrorCode =
  | 'not-supported'   // The runtime cannot talk to the device
  | 'not-found'       // No matching device / the selection was cancelled
  | 'not-connected'   // No connection is open
  | 'timeout'         // The response did not arrive in time
  | 'disconnected'    // Disconnected while in use
  | 'io'              // Anything else

class TransportError extends OpenloopError {
  name: string  // 'TransportError'
  readonly code: TransportErrorCode        // Added in v0.6.0
  stale?: boolean
  busy?: boolean
  noResponse?: boolean
  sent?: number
  awaited?: boolean
  constructor(message: string, code?: TransportErrorCode)  // Defaults to 'io'
}

class OpenloopSDK {
  static readonly sdkBuildId: string

  static registerTransport(type: string, config: {
    factory: TransportFactory
    name: string
    isAvailable: () => boolean | Promise<boolean>
  }): void

  static discover(): Promise<TransportInfo[]>

  static connect(opts?: { transport?: string }): Promise<ITransport>

  static getRegisteredTransports(): string[]

  static clearTransports(): void
}

class WcTransport implements ITransport {
  constructor(options: WcTransportOptions)
  open(): Promise<void>
  close(): Promise<void>
  isConnected(): boolean
  lock(): Promise<void>
  unlock(): Promise<void>
  exchange(apdu: Uint8Array): Promise<Uint8Array>
}

const OPENLOOP_VENDOR_ID  = 0x303a   // Espressif VID
const OPENLOOP_PRODUCT_ID = 0x8341   // Openloop PID
const LEDGER_VENDOR_ID    = 0x2c97   // Ledger SAS VID
const LEDGER_PRODUCT_ID   = 0x1011   // Nano S compatible
const LEDGER_USAGE_PAGE   = 0xffa0   // Ledger HID usage page (APDU transport)

const BTC_MAINNET_PATH  = "84'/0'/0'/0/0"
const BTC_TESTNET_PATH  = "84'/1'/0'/0/0"
const DEFAULT_ETH_PATH  = "44'/60'/0'/0/0"
const DEFAULT_XRP_PATH  = "44'/144'/0'/0'/0'"
const DEFAULT_SOL_PATH  = "44'/501'/0'/0'"
const DEFAULT_TRON_PATH = "44'/195'/0'/0/0"

const BLE_SERVICE_UUID      = '13d63400-2c97-0004-0000-4c6564676572'
const BLE_NOTIFY_UUID       = '13d63400-2c97-0004-0001-4c6564676572'
const BLE_WRITE_UUID        = '13d63400-2c97-0004-0002-4c6564676572'
const BLE_DEVICE_NAME_PREFIX = 'Openloop'
const BLE_DEFAULT_MTU       = 155

const WALLETCONNECT_PROJECT_ID = 'b3d610140c2d0d39f50150a030c7c985'

const SUPPORTED_BIP122_CHAINS = [
  'bip122:000000000019d6689c085ae165831e93', // Bitcoin Mainnet
  'bip122:000000000933ea01ad0ee984209779ba', // Bitcoin Testnet3
] as const

const SUPPORTED_EVM_CHAINS = [
  'eip155:1',         // Ethereum Mainnet
  'eip155:11155111',  // Sepolia Testnet
] as const

const SUPPORTED_SOLANA_CHAINS = [
  'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp', // Mainnet Beta
  'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1',  // Devnet
] as const

const SUPPORTED_TRON_CHAINS = [
  'tron:0x2b6653dc',  // TRON Mainnet
  'tron:0x94a9059e',  // TRON Shasta Testnet
] as const

const SUPPORTED_BIP122_METHODS = [
  'signPsbt', 'getAccountAddresses', 'signMessage', 'sendTransfer',
] as const

const SUPPORTED_EVM_METHODS = [
  'eth_sendTransaction', 'eth_signTransaction', 'eth_sign',
  'personal_sign', 'eth_signTypedData', 'eth_signTypedData_v3',
  'eth_signTypedData_v4', 'wallet_getCapabilities',
] as const

const SUPPORTED_SOLANA_METHODS = [
  'solana_signTransaction', 'solana_signAllTransactions',
  'solana_signAndSendTransaction', 'solana_signMessage',
] as const

const SUPPORTED_TRON_METHODS = [
  'tron_signTransaction', 'tron_signMessage',
] as const

const SUPPORTED_EVENTS = ['chainChanged', 'accountsChanged'] as const

const APDU = {
  // Class bytes
  CLA_ETHEREUM: 0xe0,
  CLA_OPENLOOP: 0xf0,         // Openloop proprietary (chain_id-aware signing, PSBT)
  CLA_V2: 0xe1,               // Ledger Bitcoin v2 protocol (extended public key retrieval)

  // Shared INS (Ethereum / TRON / XRP; routed automatically by the BIP44 coin_type)
  INS_GET_PUBLIC_KEY: 0x02,    // Get address / public key
  INS_SIGN_TX: 0x04,           // Sign a transaction
  INS_SIGN_MESSAGE: 0x08,      // personal_sign (EIP-191) / TRON message
  INS_SIGN_EIP712: 0x0c,       // EIP-712 Typed Data
  INS_EIP712_STRUCT_DEF: 0x1a, // EIP-712 streaming: type definitions (P2=0x00 struct name / 0xFF field)
  INS_EIP712_STRUCT_IMPL: 0x1c, // EIP-712 streaming: values (P2=0x00 root / 0x0F array / 0xFF field)
  INS_SIGN_AUTHORIZATION: 0x34, // EIP-7702

  // Bitcoin extended public key (CLA_V2)
  INS_V2_GET_EXTENDED_PUBKEY: 0x00, // Get the extended public key for any path

  // Bitcoin PSBT (Openloop proprietary)
  INS_BTC_SIGN_PSBT: 0x70,          // Send a PSBT
  INS_BTC_GET_SIGNED_PSBT: 0x71,    // Get the signed PSBT
  INS_BTC_GET_WALLET_PUBLIC_KEY: 0x40, // Get the BTC public key / address
  INS_BTC_GET_ACCOUNT_XPUB: 0x72,   // Get the account xpub
  INS_BTC_SIGN_MESSAGE: 0x73,       // Sign a BTC message

  // Solana (Ledger Solana compatible)
  INS_SOL_GET_PUBKEY: 0x05,         // Get the Ed25519 public key
  INS_SOL_SIGN_MESSAGE: 0x06,       // Sign a transaction / message
  INS_SOL_SIGN_OFFCHAIN_MSG: 0x07,  // Sign an off-chain message
} as const

const SDK_BUILD_ID: string   // e.g. "@openloop/sdk-core@0.7.0"

// Build an APDU command (ISO 7816-4). The Short form is chosen automatically for data of 255 bytes or less:
// [CLA][INS][P1][P2][Lc][Data...], and the Extended form for 256 bytes or more:
// [CLA][INS][P1][P2][0x00][Lc_HI][Lc_LO][Data...]
function buildApdu(cla: number, ins: number, p1: number, p2: number, data?: Uint8Array): Uint8Array

// Convert a BIP32 path to a buffer: [element count (1 byte)][each element 4 bytes big-endian]. "m/" is optional, ' marks hardened. Elements are not validated
function pathToBuffer(path: string): Uint8Array

// Convert a BIP32 path to an array of elements (hardened adds 0x80000000). Example: "84'/0'/0'/0/0" -> [0x80000054, 0x80000000, 0x80000000, 0, 0]. Elements are not validated
function pathToElements(path: string): number[]

// Concatenate Uint8Arrays
function concat(...arrays: Uint8Array[]): Uint8Array

// Convert a hex string to a Uint8Array (with or without the 0x prefix). Length and characters are not validated
function hexToBytes(hex: string): Uint8Array

// Convert a Uint8Array to a hex string (no 0x prefix)
function bytesToHex(bytes: Uint8Array): string

// Base58 encode/decode (no checksum). decode throws an Error on an invalid character
function base58Encode(bytes: Uint8Array): string
function base58Decode(str: string): Uint8Array

// Format an OpenloopDeviceState as a one-line string for logs
// Example: "wallet=N lang=0 USB(native) ble=off FIDO PIV"
function formatOpenloopState(s: OpenloopDeviceState): string

const BIP32_VERSION_XPUB = 0x0488b21e   // Mainnet (xpub…)
const BIP32_VERSION_TPUB = 0x043587cf   // Test networks (tpub…)

interface ExtendedPublicKey {
  version: number          // BIP32_VERSION_XPUB or BIP32_VERSION_TPUB
  depth: number
  parentFingerprint: number
  childNumber: number      // This key's own child number (includes 0x80000000 if hardened)
  chainCode: string        // 32 bytes (hex)
  publicKey: string        // 33-byte compressed public key (hex)
}

// Derive a non-hardened child (index is an integer below 0x80000000) from the parent's compressed public key (hex) and chain code (hex)
function deriveChildPublicKey(
  parentPubkey: string, parentChainCode: string, index: number
): { publicKey: string; chainCode: string }

// Parse a serialized extended public key. Throws an Error for anything other than xpub / tpub, a point not on the curve, or a private key
function decodeExtendedPubkey(serialized: string): ExtendedPublicKey

// base58check (with a 4-byte checksum). decode always verifies the checksum
function base58CheckDecode(str: string): Uint8Array
function base58CheckEncode(payload: Uint8Array): string

interface TypedDataLike {
  domain: Record<string, unknown>
  types: Record<string, Array<{ name: string; type: string }>>
  primaryType: string
  message: Record<string, unknown>
}

// Stream the EIP-712 data itself to the device, field by field, and sign it (the implementation behind EthereumApp.signTypedDataStreaming)
function signTypedDataStreaming(
  transport: ITransport, path: string, td: TypedDataLike, chainId: number
): Promise<SignatureResult>

// Whether the payload has the EIP-3009 form (TransferWithAuthorization / ReceiveWithAuthorization)
function isEip3009(td: TypedDataLike): boolean

// Wrap a message in the Solana off-chain message format. If format is omitted, it is 0
// when every byte is printable ASCII (0x20–0x7E) and 1 otherwise
function wrapSolanaOffchainMessage(message: Uint8Array, formatOverride?: 0 | 1 | 2): Uint8Array

// Whether data starts with the Solana off-chain message signing domain
function isSolanaOffchainMessageWrapped(data: Uint8Array): boolean

// The signing domain (16 bytes: 0xFF + "solana offchain")
const SOLANA_OFFCHAIN_SIGNING_DOMAIN: Uint8Array