Bitcoin API

import {
  BitcoinApp,
  BTC_MAINNET_PATH,
  BTC_TESTNET_PATH,
  type BtcMessageSignature,
  type InputSigningPath,
} from '@openloop/sdk-core'

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

import { BitcoinApp } from '@openloop/sdk-core'

const btc = new BitcoinApp(transport)

async getAddress(testnet?: boolean): Promise<{
  publicKey: string   // 非圧縮公開鍵 (hex, 65 bytes)
  address: string     // bech32 アドレス ("bc1..." or "tb1...")
  chainCode: string   // チェーンコード (hex, 32 bytes)
}>

// Mainnet
const { address } = await btc.getAddress()
// address: "bc1q..."

// Testnet
const { address: testnetAddress } = await btc.getAddress(true)
// testnetAddress: "tb1q..."

async getAddressWithPath(path: string): Promise<{
  publicKey: string   // 非圧縮公開鍵 (hex, 65 bytes)
  address: string
  chainCode: string
}>

// 2番目のアカウントの最初のアドレス
const second = await btc.getAddressWithPath("84'/0'/1'/0/0")

// お釣り用アドレス
const change = await btc.getAddressWithPath("84'/0'/0'/1/0")

// "m/" プレフィックスも可
const sixth = await btc.getAddressWithPath("m/84'/0'/0'/0/5")

async getAccountXpub(coinType: number): Promise<{
  publicKey: string   // 圧縮公開鍵 (hex, 33 bytes)
  chainCode: string   // チェーンコード (hex, 32 bytes)
}>

const { publicKey, chainCode } = await btc.getAccountXpub(0)  // mainnet

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

interface BtcXpub {
  publicKey: string         // 圧縮公開鍵 (hex, 33 bytes)
  chainCode: string         // チェーンコード (hex, 32 bytes)
  parentFingerprint: number // 直前の親のフィンガープリント（master ではない）
  depth: number             // m からの段数
  xpub: string              // 直列化された文字列（"xpub…" / "tpub…"）
}

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

// Native SegWit・口座 0・testnet の拡張公開鍵（"m/84'/1'/0'"）
const xpub = await btc.getExtendedPubkey(accountPathOf({ script: 'p2wpkh', account: 0 }, 'testnet4'))
console.log(xpub.xpub.slice(0, 4), xpub.depth) // "tpub" 3

async getMasterFingerprint(): Promise<string>  // 8 文字の小文字 hex（ビッグエンディアン）、例: "631698e0"

const fp = await btc.getMasterFingerprint()  // 例: "631698e0"

// PSBT 入力 BIP32 派生に埋め込む（type 0x06）:
//   value = fingerprint(4B) ‖ path(4B LE × N)

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

const sig = await btc.signMessage('Hello, Bitcoin!', BTC_MAINNET_PATH)
console.log(sig.v)         // 39〜42（BTC_MAINNET_PATH は 84'）
console.log(sig.signature) // Base64 encoded signature

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

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

try {
  await btc.signPsbt('70736274ff...')
} catch (e) {
  if (e instanceof BtcError) {
    console.log(e.code) // 'psbt_too_large'
  }
}

async signPsbtHex(psbt: string): Promise<string>

const signedHex = await btc.signPsbtHex('70736274ff...')

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

const signedHex = await btc.signPsbtWithPaths('70736274ff...', [
  { index: 0, path: "84'/0'/0'/0/0" },
  { index: 1, path: "84'/0'/0'/0/3" },
  { index: 2, path: "84'/0'/0'/1/0" }, // お釣り
])

import { BitcoinApp, type ITransport } from '@openloop/sdk-core'
import {
  accountPathOf,
  createAddressCache,
  scanAccount,
  type BtcNetwork,
  type BtcAccount,
} from '@openloop/sdk-core/bitcoin'

declare const transport: ITransport // 接続済みの Transport

const btc = new BitcoinApp(transport)

// 端点は呼ぶ側が決めます（SDK は既定値を持ちません）
const net: BtcNetwork = {
  id: 'testnet4',
  esplora: ['https://mempool.space/testnet4/api'],
  feeEndpoints: ['https://mempool.space/testnet4/api'],
  timeoutMs: 15_000,
}
const acct: BtcAccount = { script: 'p2wpkh', account: 0 }

// 口座の拡張公開鍵はデバイスから 1 回だけ取る
const xpub = await btc.getExtendedPubkey(accountPathOf(acct, net.id))

// 口座を走査して UTXO と次のお釣りのアドレスを得る
const cache = createAddressCache()
const { utxos, nextChange } = await scanAccount(xpub, acct, net, { cache })

type BtcNetworkId = 'mainnet' | 'testnet3' | 'testnet4'
type BtcScript = 'p2pkh' | 'p2sh-p2wpkh' | 'p2wpkh'

interface BtcNetwork {
  id: BtcNetworkId
  esplora: string[]       // Esplora 互換 API のベース URL。最良のものから順に試す
  feeEndpoints: string[]  // `/v1/fees/recommended` を返す端点（mempool.space 互換）
  timeoutMs: number       // 1 回の呼び出しの時間切れ（ミリ秒）。本文の読み取りも含む
}

interface BtcAccount {
  script: BtcScript       // purpose（44' / 49' / 84'）を決める
  account: number         // 口座の番号（強化）
}

interface BtcUtxo {
  txid: string
  vout: number
  value: number           // sats
  address: string
  path: string            // 例: "m/84'/1'/0'/0/3"
  publicKey: string       // 圧縮公開鍵 (hex, 33 bytes)
  confirmed: boolean      // 1 確認未満は false
  blockHeight?: number
}

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

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

import { pathOf, accountPathOf } from '@openloop/sdk-core/bitcoin'

pathOf({ script: 'p2wpkh', account: 0 }, 'testnet4', 1, 3)   // "m/84'/1'/0'/1/3"
pathOf({ script: 'p2pkh', account: 1 }, 'mainnet', 0, 0)     // "m/44'/0'/1'/0/0"
accountPathOf({ script: 'p2sh-p2wpkh', account: 0 }, 'mainnet') // "m/49'/0'/0'"

function publicKeyToAddress(publicKey: string, script: BtcScript, net: BtcNetworkId): string

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

const compressed = '0279be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798'
publicKeyToAddress(compressed, 'p2wpkh', 'mainnet')       // "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4"
publicKeyToAddress(compressed, 'p2pkh', 'mainnet')        // "1BgGZ9tcN4rm9KBzDn7KprQz87SZ26SAMH"
publicKeyToAddress(compressed, 'p2sh-p2wpkh', 'testnet4') // "2NAUYAHhujozruyzpsFRP63mbrdaU5wnEpN"

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

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

const receive = deriveAddresses(xpub, acct, net.id, 0, 0, 5) // 受け取り 0〜4
console.log(receive[0].address, receive[0].path)             // "tb1q…" "m/84'/1'/0'/0/0"

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

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

try {
  const { kind } = validateAddress('tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx', 'mainnet')
  console.log(kind)
} catch (e) {
  if (e instanceof BtcError && e.code === 'network_mismatch') {
    console.log('別の網のアドレスです')
  }
}

function addressToScriptPubKey(address: string, net: BtcNetworkId): Uint8Array

function encodeSegwitAddress(hrp: string, version: number, program: Uint8Array): string
function decodeSegwitAddress(address: string): { hrp: string; version: number; program: Uint8Array }

function createAddressCache(): BtcAddressCache

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
}

cache.syncToDevice('device-A')
cache.set('tb1q…', { path: "m/84'/1'/0'/0/0", publicKey: '02…' })
cache.syncToDevice('device-B') // 持ち主が変わった → 全部捨てる
console.log(cache.size)        // 0

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

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

const path = findAddressPath(nextChange.address, xpub, acct, net.id, cache)
// "m/84'/1'/0'/1/0" など。見つからなければ null

function scanAccount(
  xpub: BtcXpub,
  acct: BtcAccount,
  net: BtcNetwork,
  opts?: {
    cache?: BtcAddressCache
    gapLimit?: number      // 既定 20
    concurrency?: number   // 既定 4（API_PARALLEL_LIMIT）
    knownUsed?: Array<{ chain: 0 | 1; index: number }>  // 呼ぶ側が「使われた」と知っている番号
  } & FetchDeps
): Promise<BtcScanResult>

interface BtcScanResult {
  used: Array<{ address: string; path: string }>  // 使われたことのあるアドレス（両方の列）
  utxos: BtcUtxo[]
  nextChange: { index: number; address: string; path: string; publicKey: string }
}

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

const { used, utxos, nextChange } = await scanAccount(xpub, acct, net, { cache, gapLimit: 20 })
const total = utxos.reduce((sum, u) => sum + u.value, 0)
console.log(`${used.length} 件のアドレスが使用済み、残高 ${total} sats`)
console.log('お釣りの次の宛先', nextChange.address, nextChange.path)

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

interface BtcAddressStats {
  txCount: number   // 取引の数（確定＋未確定）。0 より大きければ「使われた」
  funded: number    // 受け取った額の合計（sats・確定＋未確定）
  spent: number     // 使った額の合計（sats・確定＋未確定）。残高は funded - spent
}

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

import { fetchUtxos, deriveAddresses } from '@openloop/sdk-core/bitcoin'

const firstFive = deriveAddresses(xpub, acct, net.id, 0, 0, 5)
const found = await fetchUtxos(firstFive, net)

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

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

const prevTxHex = await fetchPrevTx(utxos[0].txid, net)

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

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

const feeRate = await getFeeRate(net) // 例: 5

function selectUtxos(
  utxos: BtcUtxo[],
  opts: {
    to: BtcRecipient[]            // { address: string; value: number }[]。1 件以上
    feeRate: number               // sat/vB
    script: BtcScript             // 入力の型（1 つの口座の中は同じ型）
    net: BtcNetworkId
    excluded?: Iterable<string>   // 使用済みの印 "txid:vout"
    changeAddress?: string        // お釣りの宛先。出力の大きさの見積りに使う
  }
): BtcSelection

interface BtcSelection {
  inputs: BtcUtxo[]
  fee: number      // 実際に払う手数料（sats）= 入力合計 − 出力合計
  change: number   // お釣り（sats）。0 ならお釣りの出力を作らない
  vbytes: number   // 見積もった大きさ（vB）
}

import { selectUtxos, getFeeRate } from '@openloop/sdk-core/bitcoin'

const sel = selectUtxos(utxos, {
  to: [{ address: 'tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx', value: 20_000 }],
  feeRate: await getFeeRate(net),
  script: acct.script,
  net: net.id,
  excluded: new Set<string>(),
  changeAddress: nextChange.address,
})
console.log(sel.inputs.length, sel.fee, sel.change, sel.vbytes)

function estimateVbytes(numInputs: number, script: BtcScript, outputVbytes: number[]): number

import { estimateVbytes, OUTPUT_VBYTES } from '@openloop/sdk-core/bitcoin'

// P2WPKH 入力 2 本、P2WPKH 宛 1 件 + お釣り 1 件
estimateVbytes(2, 'p2wpkh', [OUTPUT_VBYTES.p2wpkh, OUTPUT_VBYTES.p2wpkh]) // 209

function buildPsbt(args: {
  script: BtcScript
  net: BtcNetworkId
  inputs: BtcPsbtInput[]
  to: Array<{ address: string; value: number }>
  change?: BtcChangeOutput   // お釣りの出力を作らないときは渡さない
}): BtcPsbt

interface BtcPsbtInput extends BtcUtxo {
  prevTxHex?: string         // Legacy（'p2pkh'）のときだけ必須
}
interface BtcChangeOutput {  // scanAccount の nextChange に value を足した形
  address: string
  path: string
  publicKey: string
  value: number
}
interface BtcPsbt {
  psbtHex: string
  paths: Array<{ index: number; path: string }>   // signPsbtWithPaths にそのまま渡せる
}

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

const to = [{ address: 'tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx', value: 20_000 }]
const { psbtHex, paths } = buildPsbt({
  script: acct.script,
  net: net.id,
  inputs: sel.inputs,
  to,
  change: sel.change > 0 ? { ...nextChange, value: sel.change } : undefined,
})

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

const legacyAcct: BtcAccount = { script: 'p2pkh', account: 0 }
const withPrev = await Promise.all(
  sel.inputs.map(async u => ({ ...u, prevTxHex: await fetchPrevTx(u.txid, net) }))
)
const legacy = buildPsbt({
  script: legacyAcct.script,
  net: net.id,
  inputs: withPrev,
  to: [{ address: 'tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx', value: 20_000 }],
})

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

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

const { rawTxHex, txid } = extractRawTx(signedHex)

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

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

const sentTxid = await broadcastTx(rawTxHex, net, txid)

class BtcError extends OpenloopError {
  readonly code: BtcErrorCode
}

type BtcErrorCode =
  | 'bad_argument' | 'invalid_address' | 'network_mismatch'
  | 'fetch_failed' | 'bad_response'
  | 'prev_tx_too_large' | 'fee_rate_out_of_range'
  | 'insufficient' | 'insufficient_unconfirmed' | 'fee_too_high' | 'fee_exceeds_amount'
  | 'psbt_too_large' | 'bad_psbt' | 'broadcast_rejected'

interface FetchDeps {
  fetchImpl?: typeof fetch   // 既定: 実行環境の globalThis.fetch
  retryDelayMs?: number      // 再試行の間隔（ミリ秒）。既定 API_RETRY_DELAY_MS（1000）
  retryCount?: number        // 1 つの URL への試行回数。既定 API_RETRY_COUNT（3）
}

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

const fetchImpl: typeof fetch = (url, init) => fetch(url, init) // 例: 計測や代理の差し込み
const rate = await getFeeRate(net, { fetchImpl, retryCount: 1, retryDelayMs: 0 })

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

const net: BtcNetwork = {
  id: 'testnet4',
  esplora: ['https://mempool.space/testnet4/api'],
  feeEndpoints: ['https://mempool.space/testnet4/api'],
  timeoutMs: 15_000,
}
const acct: BtcAccount = { script: 'p2wpkh', account: 0 }

async function send(transport: ITransport, toAddress: string, sats: number): Promise<string> {
  const btc = new BitcoinApp(transport)

  validateAddress(toAddress, net.id)                           // 宛先と網の確認

  const xpub = await btc.getExtendedPubkey(accountPathOf(acct, net.id))
  const cache = createAddressCache()
  const { utxos, nextChange } = await scanAccount(xpub, acct, net, { cache })

  const sel = selectUtxos(utxos, {
    to: [{ address: toAddress, value: sats }],
    feeRate: await getFeeRate(net),
    script: acct.script,
    net: net.id,
    changeAddress: nextChange.address,
  })

  const { psbtHex, paths } = buildPsbt({
    script: acct.script,
    net: net.id,
    inputs: sel.inputs,
    to: [{ address: toAddress, value: sats }],
    change: sel.change > 0 ? { ...nextChange, value: sel.change } : undefined,
  })

  const signedHex = await btc.signPsbtWithPaths(psbtHex, paths) // デバイスで確認・承認
  const { rawTxHex, txid } = extractRawTx(signedHex)
  return broadcastTx(rawTxHex, net, txid)
}

async function main(transport: ITransport) {
  try {
    const txid = await send(transport, 'tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx', 20_000)
    console.log('ブロードキャストしました', txid)
  } catch (e) {
    if (e instanceof BtcError) {
      console.log(e.code, e.message) // 例: 'insufficient'
    } else {
      throw e // ApduError（拒否など）・TransportError
    }
  }
}

function verifyBtcMessage(message: string, sig: BtcMessageSignature, identity: string): VerifyResult

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

const message = 'Hello, Bitcoin!'
const sig = await btc.signMessage(message, BTC_MAINNET_PATH)
const { address } = await btc.getAddress()
const result = verifyBtcMessage(message, sig, address)
console.log(result.ok) // true

function verifyBtcPsbt(signedPsbtHex: string): VerifyResult

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

const signedHex = await btc.signPsbtHex('70736274ff...')
const result = verifyBtcPsbt(signedHex)
console.log(result.ok)

import * as bitcoin from 'bitcoinjs-lib'
import { BitcoinApp, BTC_MAINNET_PATH, type ITransport } from '@openloop/sdk-core'

async function signWithBitcoinjs(transport: ITransport): Promise<string> {
  const btc = new BitcoinApp(transport)

  // アドレス取得
  const { address } = await btc.getAddress()

  // PSBT 作成
  const psbt = new bitcoin.Psbt({ network: bitcoin.networks.bitcoin })
  psbt.addInput({
    hash: '7d067b4a697a09d2c3cff7d4d9506c9955e93bff41bf82d439da7d030382bc3e',
    index: 0,
    witnessUtxo: {
      script: bitcoin.address.toOutputScript(address, bitcoin.networks.bitcoin),
      value: 50000,
    },
  })
  psbt.addOutput({
    address: 'bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4',
    value: 40000,
  })

  // PSBT をデバイスで署名
  const psbtHex = psbt.toHex()
  const signedHex = await btc.signPsbtWithPaths(psbtHex, [
    { index: 0, path: BTC_MAINNET_PATH },
  ])

  // 署名済み PSBT（最終化済み）を読み込み、ブロードキャスト用 raw transaction を取り出す
  const signedPsbt = bitcoin.Psbt.fromHex(signedHex)
  return signedPsbt.extractTransaction().toHex()
}