@meshconnect/uwc-bitcoin 0.2.2 → 0.2.4-snapshot.d9f6da2

package/src/adapter.ts

@@ -0,0 +1,49 @@
+import type {
+  BitcoinAccount,
+  BitcoinPsbtSignRequest,
+  BitcoinSendTransferRequest,
+  BitcoinSignMessageParams,
+  SignatureType,
+  TransactionResult
+} from '@meshconnect/uwc-types'
+
+/**
+ * The seam between the Bitcoin namespace module and a single transport.
+ *
+ * A concrete adapter is constructed by its transport bound to an
+ * already-connected provider/session — Wallet Standard `bitcoin:*` for the
+ * injected transport, WalletConnect bip122 for the WalletConnect transport —
+ * so the port carries no `connect`/provider argument: connecting is the
+ * transport's job. Each adapter converts between these transport-agnostic
+ * domain shapes and its wallet's native interface (e.g. hex/base64 strings ↔
+ * `Uint8Array`).
+ *
+ * `getAccounts` + `signMessage` are the always-present verify-flow methods.
+ * `signPsbt` and `sendTransfer` are optional because they map to distinct wallet
+ * paths — a Wallet Standard wallet signs a PSBT (Path B); a WalletConnect wallet
+ * does a high-level `sendTransfer` (Path A) — and not every adapter offers both.
+ */
+export interface BitcoinTransportAdapter {
+  /** Enumerate the bip122 accounts available on the connected session. */
+  getAccounts(): Promise<BitcoinAccount[]>
+
+  /** Sign a message with the given account. */
+  signMessage(params: BitcoinSignMessageParams): Promise<SignatureType>
+
+  /**
+   * Sign a PSBT (Path B). Returns the wallet-signed PSBT, base64-encoded — the
+   * wallet does NOT broadcast; finalizing + broadcasting is a separate step.
+   * Optional: only adapters whose wallet exposes PSBT signing implement it.
+   */
+  signPsbt?(request: BitcoinPsbtSignRequest): Promise<string>
+
+  /**
+   * High-level transfer (Path A): the wallet does coin selection, fee, signing,
+   * and broadcast, returning a txid. Optional: only adapters whose transport
+   * offers it (e.g. WalletConnect `sendTransfer`) implement it.
+   */
+  sendTransfer?(request: BitcoinSendTransferRequest): Promise<TransactionResult>
+
+  /** Release any session resources the adapter holds. Optional. */
+  disconnect?(): Promise<void>
+}

package/src/adapters/wallet-standard.test.ts

@@ -0,0 +1,148 @@
+import { describe, it, expect, vi } from 'vitest'
+import { WalletConnectorError } from '@meshconnect/uwc-types'
+import {
+  WalletStandardBitcoinAdapter,
+  type WalletStandardBitcoinAccount,
+  type WalletStandardBitcoinWallet
+} from './wallet-standard'
+import { base64ToBytes, bytesToBase64, utf8ToBytes } from '../encoding'
+
+const wsAccount: WalletStandardBitcoinAccount = {
+  address: 'bc1qpayment',
+  publicKey: new Uint8Array([2, 0xaa, 0xbb, 0xcc]),
+  purpose: 'payment'
+}
+
+/** A fake `bitcoin:*` wallet with all three features wired via vi mocks. */
+const fakeWallet = (
+  overrides: Partial<WalletStandardBitcoinWallet['features']> = {}
+): WalletStandardBitcoinWallet => ({
+  name: 'Fake BTC Wallet',
+  accounts: [],
+  features: {
+    'bitcoin:connect': {
+      connect: vi.fn().mockResolvedValue({ accounts: [wsAccount] })
+    },
+    'bitcoin:signMessage': {
+      signMessage: vi.fn().mockResolvedValue([
+        {
+          signature: new Uint8Array([1, 2, 3]),
+          signedMessage: new Uint8Array()
+        }
+      ])
+    },
+    'bitcoin:signTransaction': {
+      signTransaction: vi
+        .fn()
+        .mockResolvedValue([{ psbt: new Uint8Array([9, 8, 7]) }])
+    },
+    ...overrides
+  }
+})
+
+describe('WalletStandardBitcoinAdapter', () => {
+  it('getAccounts connects and maps accounts to hex publicKey', async () => {
+    const wallet = fakeWallet()
+    const adapter = new WalletStandardBitcoinAdapter(wallet)
+
+    const accounts = await adapter.getAccounts()
+
+    expect(wallet.features['bitcoin:connect']!.connect).toHaveBeenCalledWith({
+      purposes: ['payment']
+    })
+    expect(accounts).toEqual([
+      { address: 'bc1qpayment', publicKey: '02aabbcc', purpose: 'payment' }
+    ])
+  })
+
+  it('signMessage encodes the message and returns a base64 standard signature', async () => {
+    const wallet = fakeWallet()
+    const adapter = new WalletStandardBitcoinAdapter(wallet)
+
+    const sig = await adapter.signMessage({
+      account: { address: 'bc1qpayment', publicKey: '02aabbcc' },
+      message: 'verify me'
+    })
+
+    const call = (
+      wallet.features['bitcoin:signMessage']!.signMessage as ReturnType<
+        typeof vi.fn
+      >
+    ).mock.calls[0][0]
+    expect(call.account).toBe(wsAccount)
+    expect(call.message).toEqual(utf8ToBytes('verify me'))
+    expect(sig).toEqual({
+      type: 'standard',
+      signature: bytesToBase64(new Uint8Array([1, 2, 3]))
+    })
+  })
+
+  it('signPsbt round-trips base64 <-> bytes and returns the signed PSBT', async () => {
+    const wallet = fakeWallet()
+    const adapter = new WalletStandardBitcoinAdapter(wallet)
+    const psbt = bytesToBase64(new Uint8Array([10, 20, 30]))
+
+    const signed = await adapter.signPsbt({ from: 'bc1qpayment', psbt })
+
+    const call = (
+      wallet.features['bitcoin:signTransaction']!.signTransaction as ReturnType<
+        typeof vi.fn
+      >
+    ).mock.calls[0][0]
+    expect(call.account).toBe(wsAccount)
+    expect(call.psbt).toEqual(base64ToBytes(psbt))
+    expect(signed).toBe(bytesToBase64(new Uint8Array([9, 8, 7])))
+  })
+
+  it('signPsbt maps inputsToSign accounts by address', async () => {
+    const wallet = fakeWallet()
+    const adapter = new WalletStandardBitcoinAdapter(wallet)
+    await adapter.getAccounts()
+
+    await adapter.signPsbt({
+      from: 'bc1qpayment',
+      psbt: bytesToBase64(new Uint8Array([1])),
+      inputsToSign: [
+        { address: 'bc1qpayment', signingIndexes: [0], sigHash: 'ALL' }
+      ]
+    })
+
+    const call = (
+      wallet.features['bitcoin:signTransaction']!.signTransaction as ReturnType<
+        typeof vi.fn
+      >
+    ).mock.calls[0][0]
+    expect(call.inputsToSign).toEqual([
+      { account: wsAccount, signingIndexes: [0], sigHash: 'ALL' }
+    ])
+  })
+
+  it('throws for an address with no connected account', async () => {
+    const wallet = fakeWallet()
+    const adapter = new WalletStandardBitcoinAdapter(wallet)
+
+    await expect(
+      adapter.signMessage({
+        account: { address: 'bc1qunknown', publicKey: '00' },
+        message: 'x'
+      })
+    ).rejects.toBeInstanceOf(WalletConnectorError)
+  })
+
+  it('throws when the wallet lacks the signTransaction feature', async () => {
+    const wallet = fakeWallet({ 'bitcoin:signTransaction': undefined })
+    const adapter = new WalletStandardBitcoinAdapter(wallet)
+
+    await expect(
+      adapter.signPsbt({
+        from: 'bc1qpayment',
+        psbt: bytesToBase64(new Uint8Array([1]))
+      })
+    ).rejects.toBeInstanceOf(WalletConnectorError)
+  })
+
+  it('does not implement sendTransfer (Wallet Standard has no high-level transfer)', () => {
+    const adapter = new WalletStandardBitcoinAdapter(fakeWallet())
+    expect(adapter.sendTransfer).toBeUndefined()
+  })
+})

package/src/adapters/wallet-standard.ts

@@ -0,0 +1,172 @@
+import type {
+  BitcoinAccount,
+  BitcoinPsbtSignRequest,
+  BitcoinSignMessageParams,
+  SignatureType
+} from '@meshconnect/uwc-types'
+import { WalletConnectorError } from '@meshconnect/uwc-types'
+import type { BitcoinTransportAdapter } from '../adapter'
+import {
+  base64ToBytes,
+  bytesToBase64,
+  bytesToHex,
+  utf8ToBytes
+} from '../encoding'
+
+/**
+ * The subset of the Wallet Standard `bitcoin:*` interface this adapter drives.
+ * Structural (no `@wallet-standard/*` dependency); grounded on the community
+ * bitcoin-wallet-standard interface that MetaMask exposes. (OKX signs BTC too,
+ * but via a legacy injected provider, not Wallet Standard — it needs a separate
+ * adapter, not this one.)
+ * @see https://github.com/ExodusMovement/bitcoin-wallet-standard
+ */
+export interface WalletStandardBitcoinAccount {
+  address: string
+  publicKey: Uint8Array
+  purpose?: 'payment' | 'ordinals'
+}
+
+interface BitcoinConnectFeature {
+  connect(input: {
+    purposes: ('payment' | 'ordinals')[]
+  }): Promise<{ accounts: WalletStandardBitcoinAccount[] }>
+}
+
+interface BitcoinSignMessageFeature {
+  signMessage(input: {
+    account: WalletStandardBitcoinAccount
+    message: Uint8Array
+    protocol?: 'ecdsa' | 'bip322'
+  }): Promise<{ signature: Uint8Array; signedMessage: Uint8Array }[]>
+}
+
+interface BitcoinSignTransactionFeature {
+  signTransaction(input: {
+    account: WalletStandardBitcoinAccount
+    psbt: Uint8Array
+    inputsToSign?: {
+      account: WalletStandardBitcoinAccount
+      signingIndexes: number[]
+      sigHash?: string
+    }[]
+  }): Promise<{ psbt: Uint8Array }[]>
+}
+
+/** The handle the injected transport passes in (a discovered `bitcoin:*` wallet). */
+export interface WalletStandardBitcoinWallet {
+  name: string
+  accounts: readonly WalletStandardBitcoinAccount[]
+  features: Record<string, unknown> & {
+    'bitcoin:connect'?: BitcoinConnectFeature
+    'bitcoin:signMessage'?: BitcoinSignMessageFeature
+    'bitcoin:signTransaction'?: BitcoinSignTransactionFeature
+  }
+}
+
+/**
+ * Wallet Standard (`bitcoin:*`) transport adapter — the injected path for
+ * wallets that speak Wallet Standard (verified: MetaMask). The injected
+ * transport discovers the wallet and hands it here; this adapter performs the
+ * bip122-specific operations against it, converting hex/base64 ↔ `Uint8Array`
+ * at the boundary.
+ *
+ * `sendTransfer` is intentionally not implemented — Wallet Standard has no
+ * high-level transfer; that is the WalletConnect adapter's path.
+ */
+export class WalletStandardBitcoinAdapter implements BitcoinTransportAdapter {
+  private accounts: readonly WalletStandardBitcoinAccount[] | null = null
+
+  constructor(private readonly wallet: WalletStandardBitcoinWallet) {}
+
+  async getAccounts(): Promise<BitcoinAccount[]> {
+    const connect = this.wallet.features['bitcoin:connect']
+    // The wallet exposes accounts only after `bitcoin:connect`; fall back to any
+    // it already lists (a wallet without the connect feature).
+    this.accounts = connect
+      ? (await connect.connect({ purposes: ['payment'] })).accounts
+      : this.wallet.accounts
+
+    return this.accounts.map(account => ({
+      address: account.address,
+      publicKey: bytesToHex(account.publicKey),
+      ...(account.purpose ? { purpose: account.purpose } : {})
+    }))
+  }
+
+  async signMessage(params: BitcoinSignMessageParams): Promise<SignatureType> {
+    const feature = this.wallet.features['bitcoin:signMessage']
+    if (!feature) {
+      throw this.unsupported('signMessage')
+    }
+    const account = await this.requireAccount(params.account.address)
+    const [result] = await feature.signMessage({
+      account,
+      message: utf8ToBytes(params.message),
+      ...(params.protocol ? { protocol: params.protocol } : {})
+    })
+    if (!result) {
+      throw new WalletConnectorError({
+        type: 'unknown',
+        message: 'wallet-standard bitcoin: signMessage returned no signature'
+      })
+    }
+    return { type: 'standard', signature: bytesToBase64(result.signature) }
+  }
+
+  async signPsbt(request: BitcoinPsbtSignRequest): Promise<string> {
+    const feature = this.wallet.features['bitcoin:signTransaction']
+    if (!feature) {
+      throw this.unsupported('signPsbt')
+    }
+    const account = await this.requireAccount(request.from)
+    const inputsToSign = request.inputsToSign
+      ? await Promise.all(
+          request.inputsToSign.map(async input => ({
+            account: await this.requireAccount(input.address),
+            signingIndexes: input.signingIndexes,
+            ...(input.sigHash ? { sigHash: input.sigHash } : {})
+          }))
+        )
+      : undefined
+    const [result] = await feature.signTransaction({
+      account,
+      psbt: base64ToBytes(request.psbt),
+      ...(inputsToSign ? { inputsToSign } : {})
+    })
+    if (!result) {
+      throw new WalletConnectorError({
+        type: 'unknown',
+        message: 'wallet-standard bitcoin: signTransaction returned no PSBT'
+      })
+    }
+    return bytesToBase64(result.psbt)
+  }
+
+  disconnect(): Promise<void> {
+    this.accounts = null
+    return Promise.resolve()
+  }
+
+  /** Look up the wallet-native account for an address, connecting first if needed. */
+  private async requireAccount(
+    address: string
+  ): Promise<WalletStandardBitcoinAccount> {
+    if (!this.accounts) await this.getAccounts()
+    const account = this.accounts?.find(a => a.address === address)
+    if (!account) {
+      throw new WalletConnectorError({
+        type: 'unknown',
+        message: `wallet-standard bitcoin: no connected account for "${address}"`
+      })
+    }
+    return account
+  }
+
+  private unsupported(method: string): WalletConnectorError {
+    return new WalletConnectorError({
+      type: 'unknown',
+      message: `wallet-standard bitcoin: this wallet does not support ${method}`
+    })
+  }
+}

package/src/adapters/walletconnect.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect, vi } from 'vitest'
+import { WalletConnectorError } from '@meshconnect/uwc-types'
+import { WalletConnectBitcoinAdapter } from './walletconnect'
+
+const ACCOUNT = 'bc1qsender'
+
+describe('WalletConnectBitcoinAdapter', () => {
+  it('getAccounts calls getAccountAddresses and maps intention -> purpose', async () => {
+    const request = vi.fn().mockResolvedValue([
+      { address: 'bc1qpay', publicKey: '02aa', intention: 'payment' },
+      { address: 'bc1qord', intention: 'ordinal' }
+    ])
+    const adapter = new WalletConnectBitcoinAdapter(ACCOUNT, request)
+
+    const accounts = await adapter.getAccounts()
+
+    expect(request).toHaveBeenCalledWith('getAccountAddresses', {
+      account: ACCOUNT
+    })
+    expect(accounts).toEqual([
+      { address: 'bc1qpay', publicKey: '02aa', purpose: 'payment' },
+      { address: 'bc1qord', publicKey: '', purpose: 'ordinals' }
+    ])
+  })
+
+  it('signMessage passes account + address + raw message and wraps the signature', async () => {
+    const request = vi.fn().mockResolvedValue({ signature: 'sigbase64' })
+    const adapter = new WalletConnectBitcoinAdapter(ACCOUNT, request)
+
+    const sig = await adapter.signMessage({
+      account: { address: 'bc1qpay', publicKey: '02aa' },
+      message: 'verify me',
+      protocol: 'bip322'
+    })
+
+    expect(request).toHaveBeenCalledWith('signMessage', {
+      account: ACCOUNT,
+      message: 'verify me',
+      address: 'bc1qpay',
+      protocol: 'bip322'
+    })
+    expect(sig).toEqual({ type: 'standard', signature: 'sigbase64' })
+  })
+
+  it('signPsbt flattens inputsToSign per index and maps SIGHASH to numbers', async () => {
+    const request = vi.fn().mockResolvedValue({ psbt: 'signedpsbt' })
+    const adapter = new WalletConnectBitcoinAdapter(ACCOUNT, request)
+
+    const signed = await adapter.signPsbt({
+      from: 'bc1qpay',
+      psbt: 'cHNidP8=',
+      inputsToSign: [
+        {
+          address: 'bc1qpay',
+          signingIndexes: [0, 2],
+          sigHash: 'ALL|ANYONECANPAY'
+        }
+      ]
+    })
+
+    expect(request).toHaveBeenCalledWith('signPsbt', {
+      account: ACCOUNT,
+      psbt: 'cHNidP8=',
+      signInputs: [
+        { address: 'bc1qpay', index: 0, sighashTypes: [0x81] },
+        { address: 'bc1qpay', index: 2, sighashTypes: [0x81] }
+      ],
+      broadcast: false
+    })
+    expect(signed).toBe('signedpsbt')
+  })
+
+  it('signPsbt rejects when inputsToSign is missing (WC has no sign-all mode)', async () => {
+    const adapter = new WalletConnectBitcoinAdapter(ACCOUNT, vi.fn())
+    await expect(
+      adapter.signPsbt({ from: 'bc1qpay', psbt: 'cHNidP8=' })
+    ).rejects.toBeInstanceOf(WalletConnectorError)
+  })
+
+  it('sendTransfer maps to recipientAddress + amount string and returns the txid', async () => {
+    const request = vi.fn().mockResolvedValue({ txid: 'deadbeef' })
+    const adapter = new WalletConnectBitcoinAdapter(ACCOUNT, request)
+
+    const txid = await adapter.sendTransfer({
+      from: 'bc1qpay',
+      to: 'bc1qdest',
+      amount: 100000n
+    })
+
+    expect(request).toHaveBeenCalledWith('sendTransfer', {
+      account: ACCOUNT,
+      recipientAddress: 'bc1qdest',
+      amount: '100000'
+    })
+    expect(txid).toBe('deadbeef')
+  })
+})

package/src/adapters/walletconnect.ts

@@ -0,0 +1,126 @@
+import type {
+  BitcoinAccount,
+  BitcoinPsbtSignRequest,
+  BitcoinSendTransferRequest,
+  BitcoinSigHash,
+  BitcoinSignMessageParams,
+  SignatureType,
+  TransactionResult
+} from '@meshconnect/uwc-types'
+import { WalletConnectorError } from '@meshconnect/uwc-types'
+import type { BitcoinTransportAdapter } from '../adapter'
+
+/**
+ * Issues a WalletConnect JSON-RPC request for a bip122 method. The WalletConnect
+ * transport binds this to its live `SignClient` + session topic + chainId, e.g.
+ * `(method, params) => signClient.request({ topic, chainId, request: { method, params } })`.
+ * Kept as a plain function so `uwc-bitcoin` needs no `@walletconnect/*` dependency.
+ */
+export type BitcoinWalletConnectRequest = (
+  method: string,
+  params: Record<string, unknown>
+) => Promise<unknown>
+
+/** Maps a SIGHASH flag to its numeric value (Bitcoin Core encoding). */
+const SIGHASH_VALUES: Record<BitcoinSigHash, number> = {
+  ALL: 0x01,
+  NONE: 0x02,
+  SINGLE: 0x03,
+  'ALL|ANYONECANPAY': 0x81,
+  'NONE|ANYONECANPAY': 0x82,
+  'SINGLE|ANYONECANPAY': 0x83
+}
+
+interface WcAccountAddress {
+  address: string
+  publicKey?: string
+  path?: string
+  intention?: string
+}
+
+/**
+ * WalletConnect (bip122) transport adapter — the Path A / mobile path (Trust
+ * Wallet, …). The WalletConnect transport pairs the session and constructs this
+ * adapter bound to the connected account's first external address plus a
+ * `request` function; this adapter maps our domain shapes onto the Reown/CAIP-2
+ * bip122 JSON-RPC methods (`getAccountAddresses`, `signMessage`, `signPsbt`,
+ * `sendTransfer`).
+ *
+ * Wire format follows the Reown Bitcoin RPC reference (what wallets implement
+ * over WalletConnect) — all-JSON strings, `account` on every request. NOTE:
+ * untested end-to-end; grounded on the spec, not a live wallet.
+ */
+export class WalletConnectBitcoinAdapter implements BitcoinTransportAdapter {
+  /**
+   * @param account The connected account's first external address — the
+   *   `account` parameter every bip122 method requires.
+   * @param request Issues the bound WalletConnect JSON-RPC request.
+   */
+  constructor(
+    private readonly account: string,
+    private readonly request: BitcoinWalletConnectRequest
+  ) {}
+
+  async getAccounts(): Promise<BitcoinAccount[]> {
+    const result = (await this.request('getAccountAddresses', {
+      account: this.account
+    })) as WcAccountAddress[]
+    return result.map(entry => ({
+      address: entry.address,
+      // WalletConnect wallets MAY omit the public key; empty when absent.
+      publicKey: entry.publicKey ?? '',
+      ...(entry.intention === 'ordinal'
+        ? { purpose: 'ordinals' as const }
+        : entry.intention === 'payment'
+          ? { purpose: 'payment' as const }
+          : {})
+    }))
+  }
+
+  async signMessage(params: BitcoinSignMessageParams): Promise<SignatureType> {
+    const result = (await this.request('signMessage', {
+      account: this.account,
+      message: params.message,
+      address: params.account.address,
+      ...(params.protocol ? { protocol: params.protocol } : {})
+    })) as { signature: string }
+    return { type: 'standard', signature: result.signature }
+  }
+
+  async signPsbt(request: BitcoinPsbtSignRequest): Promise<string> {
+    if (!request.inputsToSign?.length) {
+      throw new WalletConnectorError({
+        type: 'unknown',
+        message:
+          'walletconnect bitcoin: signPsbt requires inputsToSign (the WC signPsbt method has no "sign all" mode)'
+      })
+    }
+    const signInputs = request.inputsToSign.flatMap(input =>
+      input.signingIndexes.map(index => ({
+        address: input.address,
+        index,
+        ...(input.sigHash
+          ? { sighashTypes: [SIGHASH_VALUES[input.sigHash]] }
+          : {})
+      }))
+    )
+    const result = (await this.request('signPsbt', {
+      account: this.account,
+      psbt: request.psbt,
+      signInputs,
+      broadcast: false
+    })) as { psbt: string }
+    return result.psbt
+  }
+
+  async sendTransfer(
+    request: BitcoinSendTransferRequest
+  ): Promise<TransactionResult> {
+    const result = (await this.request('sendTransfer', {
+      account: this.account,
+      recipientAddress: request.to,
+      amount: request.amount.toString()
+    })) as { txid: string }
+    return result.txid
+  }
+}