@meshconnect/uwc-bitcoin 0.2.4 → 0.3.0

package/src/adapters/wallet-standard.ts

@@ -0,0 +1,194 @@
+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
+
+  /**
+   * @param wallet The discovered `bitcoin:*` wallet.
+   * @param initialAccounts Optional already-authorized accounts to seed the
+   *   cache with. Passed on the SILENT restore path so the first
+   *   `signMessage`/`signPsbt` doesn't re-invoke `bitcoin:connect` (which some
+   *   wallets surface as UI) via `requireAccount`→`getAccounts`. Omit on a
+   *   fresh connect, where `getAccounts()` should call `bitcoin:connect` to
+   *   authorize.
+   */
+  constructor(
+    private readonly wallet: WalletStandardBitcoinWallet,
+    initialAccounts?: readonly WalletStandardBitcoinAccount[]
+  ) {
+    if (initialAccounts && initialAccounts.length > 0) {
+      this.accounts = initialAccounts
+    }
+  }
+
+  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) ??
+      // The cached set is from an earlier authorize; the wallet may have since
+      // switched accounts (its `accounts` update in place). Re-check the
+      // wallet's CURRENT accounts before failing — so signing the live account
+      // after a switch resolves without re-invoking `bitcoin:connect`.
+      this.wallet.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/bitcoin-namespace.test.ts

@@ -33,6 +33,28 @@ const ethereumNetwork: Network = {
   networkType: 'evm'
 }
 
+/** Same bip122 namespace as Bitcoin, but a different chain id. */
+const dogeNetwork: Network = {
+  internalId: 3,
+  id: 'bip122:1a91e3dace36e2be3bf030a65679fe82',
+  namespace: 'bip122',
+  name: 'Dogecoin',
+  logoUrl: '',
+  nativeCurrency: { name: 'Dogecoin', symbol: 'DOGE', decimals: 8 },
+  networkType: 'dogecoin'
+}
+
+/** Same bip122 namespace as Bitcoin, but a different chain id. */
+const litecoinNetwork: Network = {
+  internalId: 2,
+  id: 'bip122:12a765e31ffd4059bada1e25190f6e98',
+  namespace: 'bip122',
+  name: 'Litecoin',
+  logoUrl: '',
+  nativeCurrency: { name: 'Litecoin', symbol: 'LTC', decimals: 8 },
+  networkType: 'litecoin'
+}
+
 const account: BitcoinAccount = {
   address: 'bc1qexampleaddress',
   publicKey: '02aabbcc',
@@ -41,10 +63,12 @@ const account: BitcoinAccount = {
 
 const signature: SignatureType = { type: 'standard', signature: 'deadbeef' }
 
-/** Minimal fake adapter so the namespace's delegation can be asserted. */
+/** Full fake adapter so the namespace's delegation can be asserted. */
 const fakeAdapter = (): BitcoinTransportAdapter => ({
   getAccounts: vi.fn().mockResolvedValue([account]),
   signMessage: vi.fn().mockResolvedValue(signature),
+  signPsbt: vi.fn().mockResolvedValue('c2lnbmVk'),
+  sendTransfer: vi.fn().mockResolvedValue('txid-abc'),
   disconnect: vi.fn().mockResolvedValue(undefined)
 })
 
@@ -64,6 +88,32 @@ describe('assertBitcoinNetwork', () => {
       ethereumNetwork.id
     )
   })
+
+  it('throws a distinct error for a bip122 network that is not Bitcoin mainnet (Dogecoin)', () => {
+    expect(() => assertBitcoinNetwork(dogeNetwork, 'test')).toThrow(
+      WalletConnectorError
+    )
+    expect(() => assertBitcoinNetwork(dogeNetwork, 'test')).toThrow(
+      dogeNetwork.id
+    )
+    // Distinct from the namespace-mismatch message — callers must be able to
+    // tell "wrong namespace" apart from "right namespace, wrong chain".
+    expect(() => assertBitcoinNetwork(dogeNetwork, 'test')).toThrow(
+      /unsupported bip122 chain/
+    )
+    expect(() => assertBitcoinNetwork(ethereumNetwork, 'test')).not.toThrow(
+      /unsupported bip122 chain/
+    )
+  })
+
+  it('throws a distinct error for a bip122 network that is not Bitcoin mainnet (Litecoin)', () => {
+    expect(() => assertBitcoinNetwork(litecoinNetwork, 'test')).toThrow(
+      WalletConnectorError
+    )
+    expect(() => assertBitcoinNetwork(litecoinNetwork, 'test')).toThrow(
+      /unsupported bip122 chain/
+    )
+  })
 })
 
 describe('BitcoinNamespace', () => {
@@ -88,6 +138,17 @@ describe('BitcoinNamespace', () => {
     ).toThrow(WalletConnectorError)
   })
 
+  it('assertSupportedNetwork rejects other bip122 chains (Dogecoin, Litecoin)', () => {
+    expect(() =>
+      new BitcoinNamespace(fakeAdapter()).assertSupportedNetwork(dogeNetwork)
+    ).toThrow(WalletConnectorError)
+    expect(() =>
+      new BitcoinNamespace(fakeAdapter()).assertSupportedNetwork(
+        litecoinNetwork
+      )
+    ).toThrow(WalletConnectorError)
+  })
+
   it('delegates getAccounts to the adapter', async () => {
     const adapter = fakeAdapter()
     const result = await new BitcoinNamespace(adapter).getAccounts()
@@ -116,4 +177,34 @@ describe('BitcoinNamespace', () => {
       new BitcoinNamespace(noDisconnect).disconnect()
     ).resolves.toBeUndefined()
   })
+
+  it('delegates signPsbt to the adapter', async () => {
+    const adapter = fakeAdapter()
+    const request = { from: 'bc1qexampleaddress', psbt: 'cHNidA==' }
+    const result = await new BitcoinNamespace(adapter).signPsbt(request)
+    expect(adapter.signPsbt).toHaveBeenCalledWith(request)
+    expect(result).toBe('c2lnbmVk')
+  })
+
+  it('delegates sendTransfer to the adapter', async () => {
+    const adapter = fakeAdapter()
+    const request = { from: 'bc1qexampleaddress', to: 'bc1qdest', amount: 1000 }
+    const result = await new BitcoinNamespace(adapter).sendTransfer(request)
+    expect(adapter.sendTransfer).toHaveBeenCalledWith(request)
+    expect(result).toBe('txid-abc')
+  })
+
+  it('rejects when the adapter does not support signPsbt / sendTransfer', async () => {
+    const signOnly: BitcoinTransportAdapter = {
+      getAccounts: vi.fn(),
+      signMessage: vi.fn()
+    }
+    const ns = new BitcoinNamespace(signOnly)
+    await expect(
+      ns.signPsbt({ from: 'bc1q', psbt: 'x' })
+    ).rejects.toBeInstanceOf(WalletConnectorError)
+    await expect(
+      ns.sendTransfer({ from: 'bc1q', to: 'bc1q2', amount: 1 })
+    ).rejects.toBeInstanceOf(WalletConnectorError)
+  })
 })

package/src/bitcoin-namespace.ts

@@ -1,10 +1,14 @@
 import type {
   BitcoinAccount,
+  BitcoinPsbtSignRequest,
+  BitcoinSendTransferRequest,
   BitcoinSignMessageParams,
   Namespace,
   Network,
-  SignatureType
+  SignatureType,
+  TransactionResult
 } from '@meshconnect/uwc-types'
+import { bitcoinNetwork } from '@meshconnect/uwc-constants'
 import { WalletConnectorError } from '@meshconnect/uwc-types'
 import type { BitcoinTransportAdapter } from './adapter'
 
@@ -12,8 +16,13 @@ import type { BitcoinTransportAdapter } from './adapter'
 export const BITCOIN_NAMESPACE: Namespace = 'bip122'
 
 /**
- * Assert `network` is a bip122 network, else throw. Shared by the namespace
- * module and its transport adapters so the boundary check lives in one place.
+ * Assert `network` is the bip122 network this module actually supports
+ * (Bitcoin mainnet), else throw. Other bip122 chains (Dogecoin, Litecoin,
+ * etc.) share the namespace but differ in chain id — accepting them here
+ * would let a Bitcoin-only wallet silently return a Bitcoin address stamped
+ * with the wrong network id, so they must be rejected explicitly rather than
+ * only checking the namespace. Shared by the namespace module and its
+ * transport adapters so the boundary check lives in one place.
  */
 export function assertBitcoinNetwork(network: Network, method: string): void {
   if (network.namespace !== BITCOIN_NAMESPACE) {
@@ -22,6 +31,12 @@ export function assertBitcoinNetwork(network: Network, method: string): void {
       message: `${method}: expected a bip122 network but got "${network.id}"`
     })
   }
+  if (network.id !== bitcoinNetwork.id) {
+    throw new WalletConnectorError({
+      type: 'unknown',
+      message: `${method}: unsupported bip122 chain "${network.id}" — only Bitcoin mainnet ("${bitcoinNetwork.id}") is supported`
+    })
+  }
 }
 
 /**
@@ -65,8 +80,36 @@ export class BitcoinNamespace {
     return this.adapter.signMessage(params)
   }
 
+  /**
+   * Sign a PSBT (Path B). Returns the wallet-signed PSBT (base64); finalizing +
+   * broadcasting is a separate step. Rejects if the active adapter's wallet
+   * does not support PSBT signing.
+   */
+  async signPsbt(request: BitcoinPsbtSignRequest): Promise<string> {
+    if (!this.adapter.signPsbt) throw this.unsupported('signPsbt')
+    return this.adapter.signPsbt(request)
+  }
+
+  /**
+   * High-level transfer (Path A): the wallet signs and broadcasts, returning a
+   * txid. Rejects if the active adapter's transport does not offer it.
+   */
+  async sendTransfer(
+    request: BitcoinSendTransferRequest
+  ): Promise<TransactionResult> {
+    if (!this.adapter.sendTransfer) throw this.unsupported('sendTransfer')
+    return this.adapter.sendTransfer(request)
+  }
+
   /** Release any session resources the adapter holds. */
   async disconnect(): Promise<void> {
     await this.adapter.disconnect?.()
   }
+
+  private unsupported(method: string): WalletConnectorError {
+    return new WalletConnectorError({
+      type: 'unknown',
+      message: `BitcoinNamespace.${method}: the active adapter does not support it`
+    })
+  }
 }

package/src/encoding.ts

@@ -0,0 +1,47 @@
+/**
+ * Minimal encoding helpers for the boundary between our transport-agnostic
+ * domain shapes (hex/base64 strings, JSON-safe) and the Wallet Standard
+ * `bitcoin:*` interface (raw `Uint8Array`). Uses only Web-standard APIs
+ * (`TextEncoder`, `atob`/`btoa`) so `uwc-bitcoin` stays dependency-free.
+ */
+
+export function utf8ToBytes(text: string): Uint8Array {
+  return new TextEncoder().encode(text)
+}
+
+export function bytesToHex(bytes: Uint8Array): string {
+  let hex = ''
+  for (const byte of bytes) hex += byte.toString(16).padStart(2, '0')
+  return hex
+}
+
+export function bytesToBase64(bytes: Uint8Array): string {
+  let binary = ''
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary)
+}
+
+export function base64ToBytes(base64: string): Uint8Array {
+  const binary = atob(base64)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)
+  return bytes
+}
+
+export function hexToBytes(hex: string): Uint8Array {
+  const clean = /^0x/i.test(hex) ? hex.slice(2) : hex
+  if (clean.length % 2 !== 0) {
+    throw new Error('hexToBytes: odd-length hex string')
+  }
+  // Validate before parsing: `parseInt` on a non-hex pair yields NaN, which a
+  // Uint8Array silently coerces to 0 — so bad input would corrupt data (a PSBT
+  // or public key) instead of failing fast. Reject it.
+  if (!/^[0-9a-fA-F]*$/.test(clean)) {
+    throw new Error('hexToBytes: non-hex characters')
+  }
+  const bytes = new Uint8Array(clean.length / 2)
+  for (let i = 0; i < bytes.length; i++) {
+    bytes[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16)
+  }
+  return bytes
+}

package/src/index.ts

@@ -4,3 +4,11 @@ export {
   BITCOIN_NAMESPACE
 } from './bitcoin-namespace'
 export type { BitcoinTransportAdapter } from './adapter'
+export { WalletStandardBitcoinAdapter } from './adapters/wallet-standard'
+export type {
+  WalletStandardBitcoinWallet,
+  WalletStandardBitcoinAccount
+} from './adapters/wallet-standard'
+export { OkxBitcoinAdapter } from './adapters/okx'
+export type { OkxBitcoinProvider } from './adapters/okx'
+export { bytesToHex, hexToBytes } from './encoding'