bitcoin-wallet-connector 0.1.0

package/src/adapters/MockAddressWalletAdapter.ts

@@ -0,0 +1,199 @@
+import { hex } from "@scure/base"
+import { Script } from "@scure/btc-signer"
+import {
+  addressToScriptPubKeyHex,
+  getAddressType,
+} from "../utils/bitcoinAddressHelpers"
+import { BitcoinNetwork, isMainnet } from "../utils/bitcoinNetworkHelpers"
+import { BitcoinWalletAdapterError } from "../utils/error"
+import { checkNever } from "../utils/misc"
+import {
+  SignMessageResult,
+  WalletAdapter,
+  WalletAdapter_onAddressesChanged_callback,
+  WalletAdapterAddress,
+  WalletAdapterAddressPurpose,
+  WalletAdapterAddressType,
+  WalletAdapterBitcoinNetwork,
+} from "../WalletAdapters.types"
+
+const randomTapInternalKey =
+  "0000000000000000000000000000000000000000000000000000000000000000"
+
+const randomPublicKey =
+  "0000000000000000000000000000000000000000000000000000000000000000"
+
+const randomRedeemScript = hex.encode(
+  Script.encode(["OP_1", hex.decode(randomPublicKey), "OP_1", "CHECKMULTISIG"]),
+)
+
+export class MockAddressWalletAdapter implements WalletAdapter {
+  constructor(
+    private network: BitcoinNetwork,
+    private inner: WalletAdapter,
+    private addresses: Partial<{
+      bitcoin: Partial<WalletAdapterAddress> & { address: string }
+      ordinals: Partial<WalletAdapterAddress> & { address: string }
+    }>,
+  ) {}
+
+  async connect(): Promise<void> {
+    await this.inner.connect()
+  }
+
+  async disconnect(): Promise<void> {
+    await this.inner.disconnect()
+  }
+
+  async getAddresses(): Promise<WalletAdapterAddress[]> {
+    const addresses = await this.inner.getAddresses()
+
+    const getWalletAdapterAddress = (
+      addressName: string,
+      info: {
+        address: string
+        purposes: WalletAdapterAddressPurpose[]
+      },
+    ): WalletAdapterAddress => {
+      const addrType = getAddressType(this.network, info.address)
+
+      // prettier-ignore
+      const addressType =
+        addrType === "p2tr" ? WalletAdapterAddressType.P2TR :
+        addrType === "p2sh" ? WalletAdapterAddressType.P2SH_P2WPKH :
+        addrType === "p2wpkh" ? WalletAdapterAddressType.P2WPKH :
+        addrType === 'p2pkh' ? WalletAdapterAddressType.P2PKH :
+        addrType === 'p2wsh' ? undefined /* unsupported */ :
+        addrType === 'unknown' ? undefined :
+        (checkNever(addrType), undefined)
+
+      if (addressType == null) {
+        throw new BitcoinWalletAdapterError(
+          `[MockAddressWalletAdapter] Please provide a supported ${addressName} address`,
+        )
+      }
+
+      return {
+        network: isMainnet(this.network)
+          ? WalletAdapterBitcoinNetwork.MAINNET
+          : WalletAdapterBitcoinNetwork.TESTNET,
+        purposes: info.purposes,
+        addressType,
+        address: info.address,
+        scriptPubKey: addressToScriptPubKeyHex(this.network, info.address),
+        publicKey: randomPublicKey,
+        redeemScript: randomRedeemScript,
+        tapInternalKey: randomTapInternalKey,
+      }
+    }
+
+    let bitcoinAddress: undefined | WalletAdapterAddress
+    let ordinalsAddress: undefined | WalletAdapterAddress
+
+    if (this.addresses.bitcoin != null) {
+      bitcoinAddress = getWalletAdapterAddress("bitcoin", {
+        ...this.addresses.bitcoin,
+        purposes: [WalletAdapterAddressPurpose.Bitcoin],
+      })
+    }
+
+    if (this.addresses.ordinals != null) {
+      ordinalsAddress = getWalletAdapterAddress("ordinals", {
+        ...this.addresses.ordinals,
+        purposes: [
+          WalletAdapterAddressPurpose.Ordinals,
+          WalletAdapterAddressPurpose.BRC20,
+          WalletAdapterAddressPurpose.Runes,
+        ],
+      })
+    }
+
+    return addresses.flatMap(a => {
+      const result: WalletAdapterAddress[] = []
+      let restPurposes = a.purposes
+
+      if (
+        bitcoinAddress != null &&
+        restPurposes.includes(WalletAdapterAddressPurpose.Bitcoin)
+      ) {
+        result.push(bitcoinAddress)
+        restPurposes = restPurposes.filter(
+          p => p !== WalletAdapterAddressPurpose.Bitcoin,
+        )
+      }
+
+      if (
+        ordinalsAddress != null &&
+        restPurposes.includes(WalletAdapterAddressPurpose.Ordinals)
+      ) {
+        result.push(ordinalsAddress)
+        restPurposes = restPurposes.filter(
+          p => p !== WalletAdapterAddressPurpose.Ordinals,
+        )
+      }
+
+      if (restPurposes.length > 0) {
+        result.push({ ...a, purposes: restPurposes })
+      }
+
+      return result
+    })
+  }
+
+  async signMessage(
+    address: string,
+    message: string,
+  ): Promise<SignMessageResult> {
+    throw new BitcoinWalletAdapterError(
+      `[MockAddressWalletAdapter] it's a mock adapter, can't send inscription`,
+    )
+  }
+
+  get sendBitcoinFeeRateCapability(): "unavailable" | "available" | "required" {
+    return this.inner.sendBitcoinFeeRateCapability
+  }
+
+  get sendInscriptionFeeRateCapability():
+    | "unavailable"
+    | "available"
+    | "required" {
+    return this.inner.sendInscriptionFeeRateCapability
+  }
+
+  sendBitcoin(
+    fromAddress: string,
+    receiverAddress: string,
+    satoshiAmount: bigint,
+  ): Promise<{ txid: string }> {
+    throw new BitcoinWalletAdapterError(
+      `[MockAddressWalletAdapter] it's a mock adapter, can't send bitcoin`,
+    )
+  }
+
+  sendInscription(
+    fromAddress: string,
+    receiverAddress: string,
+    inscriptionId: string,
+  ): Promise<{ txid: string }> {
+    throw new BitcoinWalletAdapterError(
+      `[MockAddressWalletAdapter] it's a mock adapter, can't send inscription`,
+    )
+  }
+
+  signAndFinalizePsbt(psbtHex: string): Promise<{ signedPsbtHex: string }> {
+    throw new BitcoinWalletAdapterError(
+      `[MockAddressWalletAdapter] it's a mock adapter, can't sign transaction`,
+    )
+  }
+
+  onAddressesChanged(_callback: WalletAdapter_onAddressesChanged_callback): {
+    unsubscribe: () => void
+  } {
+    // Mock adapter doesn't support address change events
+    return {
+      unsubscribe: () => {
+        // No-op
+      },
+    }
+  }
+}

package/src/adapters/OkxWalletAdapter.impl.ts

@@ -0,0 +1,168 @@
+import { UserRejectError, BitcoinWalletAdapterError } from "../utils/error"
+import {
+  SignMessageResult,
+  WalletAdapter,
+  WalletAdapter_onAddressesChanged_callback,
+} from "../WalletAdapters.types"
+import {
+  UniSatEvents,
+  UnisatCompatibleProviderAPI,
+  UnisatCompatibleWalletAdapterImpl,
+} from "../utils/UnisatCompatibleWalletAdapterImpl"
+
+enum RpcErrorCode {
+  PARSE_ERROR = -32700,
+  INVALID_REQUEST = -32600,
+  METHOD_NOT_FOUND = -32601,
+  INVALID_PARAMS = -32602,
+  INTERNAL_ERROR = -32603,
+  SERVER_ERROR = -32000,
+  USER_REJECTION = 4001,
+  METHOD_NOT_SUPPORTED = 4002,
+}
+
+interface RpcError<TErrorData = unknown> {
+  code: number | RpcErrorCode
+  message: string
+  data?: TErrorData
+}
+
+interface OkxBitcoinProvider
+  extends UnisatCompatibleProviderAPI, Record<string, any> {
+  connect(): Promise<void>
+  on<K extends keyof UniSatEvents>(
+    event: K,
+    handler: (...args: UniSatEvents[K]) => void,
+  ): void
+  on(event: "accountChanged" | "networkChanged", handler: () => void): void
+  removeListener<K extends keyof UniSatEvents>(
+    event: K,
+    handler: (...args: UniSatEvents[K]) => void,
+  ): void
+  removeListener(
+    event: "accountChanged" | "networkChanged",
+    handler: () => void,
+  ): void
+}
+
+export class OkxWalletAdapterImpl
+  extends UnisatCompatibleWalletAdapterImpl
+  implements WalletAdapter
+{
+  private okxwallet: OkxBitcoinProvider
+  constructor(provider: OkxBitcoinProvider) {
+    /**
+     * OKX Provider API:
+     *
+     * https://web3.okx.com/zh-hans/build/dev-docs/sdks/chains/bitcoin/provider
+     */
+    super(provider, "OKX")
+    this.okxwallet = provider
+  }
+
+  async connect(): Promise<void> {
+    // if not authorized, okx wallet will pop up a window to ask user to authorize
+    // if authorized, okx wallet will do nothing
+    await this.okxwallet.connect()
+  }
+
+  async signMessage(
+    address: string,
+    message: string,
+  ): Promise<SignMessageResult> {
+    return handleRpcError(super.signMessage(address, message))
+  }
+
+  async sendBitcoin(
+    fromAddress: string,
+    receiverAddress: string,
+    satoshiAmount: bigint,
+    options?: { feeRate?: number },
+  ): Promise<{
+    txid: string
+  }> {
+    return handleRpcError(
+      super.sendBitcoin(fromAddress, receiverAddress, satoshiAmount, options),
+    )
+  }
+
+  async sendInscription(
+    fromAddress: string,
+    receiverAddress: string,
+    inscriptionId: string,
+    options?: { feeRate?: number },
+  ): Promise<{
+    txid: string
+  }> {
+    return handleRpcError(
+      super.sendInscription(
+        fromAddress,
+        receiverAddress,
+        inscriptionId,
+        options,
+      ),
+    )
+  }
+
+  async signAndFinalizePsbt(
+    psbtHex: string,
+    signIndices: [address: string, signIndex: number][],
+  ): Promise<{
+    signedPsbtHex: string
+  }> {
+    return handleRpcError(super.signAndFinalizePsbt(psbtHex, signIndices))
+  }
+
+  onAddressesChanged(callback: WalletAdapter_onAddressesChanged_callback): {
+    unsubscribe: () => void
+  } {
+    // OKX uses 'accountChanged' (no 's') and 'networkChanged' events
+    // https://web3.okx.com/build/dev-docs/sdks/chains/bitcoin/provider
+    if (this.okxwallet?.on && this.okxwallet?.removeListener) {
+      const handler = async (): Promise<void> => {
+        try {
+          const addresses = await this.getAddresses()
+          callback({ addresses })
+        } catch (error) {
+          console.warn("[OKX] Failed to get addresses on change:", error)
+        }
+      }
+
+      // Listen to account and network changes (OKX uses 'accountChanged' not 'accountsChanged')
+      this.okxwallet.on("accountChanged", handler)
+      this.okxwallet.on("networkChanged", handler)
+
+      return {
+        unsubscribe: () => {
+          this.okxwallet.removeListener("accountChanged", handler)
+          this.okxwallet.removeListener("networkChanged", handler)
+        },
+      }
+    } else {
+      // Fallback to parent implementation (polling)
+      return super.onAddressesChanged(callback)
+    }
+  }
+}
+
+export class OkxWalletAdapterError extends BitcoinWalletAdapterError {
+  constructor(rpcError: RpcError) {
+    super("OKX wallet error: " + rpcError.message, { cause: rpcError })
+  }
+}
+
+const handleRpcError = async <T>(promise: Promise<T>): Promise<T> => {
+  try {
+    return await promise
+  } catch (e: any) {
+    if (e instanceof UserRejectError) {
+      throw e
+    }
+
+    if (e.code === RpcErrorCode.USER_REJECTION) {
+      throw new UserRejectError()
+    }
+
+    throw new OkxWalletAdapterError(e)
+  }
+}

package/src/adapters/OkxWalletAdapter.ts

@@ -0,0 +1,37 @@
+import type {
+  WalletAdapter,
+  WalletAdapterStatic,
+} from "../WalletAdapters.types"
+import type { UnisatCompatibleProviderAPI } from "../utils/UnisatCompatibleWalletAdapterImpl"
+import { createAvailability } from "../utils/createAdapterAvailability"
+
+const adapterId = "okxwallet.bitcoin"
+
+const metadata = {
+  name: "OKX Wallet",
+  iconUrl: import("../_/okx.png").then(m => m.default),
+  websiteUrl: "https://web3.okx.com/",
+  downloadUrl: "https://web3.okx.com/download",
+}
+
+const availability = createAvailability<
+  UnisatCompatibleProviderAPI,
+  WalletAdapter
+>({
+  getPrecondition: () => {
+    const provider = (window as any).okxwallet?.bitcoin as
+      | UnisatCompatibleProviderAPI
+      | undefined
+    return provider == null ? null : { value: provider }
+  },
+  initializer: async provider => {
+    const { OkxWalletAdapterImpl } = await import("./OkxWalletAdapter.impl")
+    return new OkxWalletAdapterImpl(provider as any)
+  },
+})
+
+export const OkxWalletAdapter: WalletAdapterStatic<WalletAdapter> = {
+  adapterId,
+  metadata,
+  getAdapter: () => availability,
+}

package/src/adapters/UnisatWalletAdapter.impl.ts

@@ -0,0 +1,32 @@
+import {
+  UnisatCompatibleProviderAPI,
+  UnisatCompatibleWalletAdapterImpl,
+} from "../utils/UnisatCompatibleWalletAdapterImpl"
+import { WalletAdapter } from "../WalletAdapters.types"
+
+/**
+ * Derivation path (Native SegWit) (BIP-84): m/84'/0'/0'/0/address_index
+ * Derivation path (Nested SegWit) (BIP-49): m/49'/0'/0'/0/address_index
+ * Derivation path (Taproot) (BIP-86): m/86'/0'/0'/0/address_index
+ * Derivation path (Taproot) (BIP-44): m/44'/0'/0'/0/address_index
+ * Derivation path (Legacy) (BIP-44): m/44'/0'/0'/0/address_index
+ */
+export class UnisatWalletAdapterImpl
+  extends UnisatCompatibleWalletAdapterImpl
+  implements WalletAdapter
+{
+  constructor(provider: UnisatCompatibleProviderAPI) {
+    /**
+     * UniSat Provider API:
+     *
+     * https://docs.unisat.io/dev/unisat-developer-service/unisat-wallet
+     */
+    super(provider, "UniSat")
+  }
+
+  sendBitcoinFeeRateCapability = "required" as const
+
+  // The default fee rate of unisat is not aligned with mempool.space, so
+  // sometimes the tx will be rejected by mempool due to uneligible network fee.
+  sendInscriptionFeeRateCapability = "unavailable" as const
+}

package/src/adapters/UnisatWalletAdapter.ts

@@ -0,0 +1,50 @@
+import { createAvailability } from "../utils/createAdapterAvailability"
+import type { UnisatCompatibleProviderAPI } from "../utils/UnisatCompatibleWalletAdapterImpl"
+import type {
+  WalletAdapter,
+  WalletAdapterMetadata,
+  WalletAdapterStatic,
+} from "../WalletAdapters.types"
+
+/**
+ * Derivation path (Native SegWit) (BIP-84): m/84'/0'/0'/0/address_index
+ * Derivation path (Nested SegWit) (BIP-49): m/49'/0'/0'/0/address_index
+ * Derivation path (Taproot) (BIP-86): m/86'/0'/0'/0/address_index
+ * Derivation path (Taproot) (BIP-44): m/44'/0'/0'/0/address_index
+ * Derivation path (Legacy) (BIP-44): m/44'/0'/0'/0/address_index
+ */
+
+const adapterId = "unisat"
+
+const metadata: WalletAdapterMetadata = {
+  name: "UniSat",
+  /**
+   * https://next-cdn.unisat.io/_/2025-v965/UniSat%20Logo.zip
+   */
+  iconUrl: import("../_/unisat.svg").then(m => m.default),
+  websiteUrl: "https://unisat.io/",
+  downloadUrl: "https://unisat.io/download",
+}
+
+const availability = createAvailability<
+  UnisatCompatibleProviderAPI,
+  WalletAdapter
+>({
+  getPrecondition: () => {
+    const provider = (window as any).unisat as
+      | UnisatCompatibleProviderAPI
+      | undefined
+    return provider == null ? null : { value: provider }
+  },
+  initializer: async provider => {
+    const { UnisatWalletAdapterImpl } =
+      await import("./UnisatWalletAdapter.impl")
+    return new UnisatWalletAdapterImpl(provider)
+  },
+})
+
+export const UnisatWalletAdapter: WalletAdapterStatic<WalletAdapter> = {
+  adapterId,
+  metadata,
+  getAdapter: () => availability,
+}

package/src/adapters/XverseWalletAdapter.impl.ts

@@ -0,0 +1,150 @@
+import { hex } from "@scure/base"
+import {
+  addressToScriptPubKey,
+  getRedeemScriptOf_P2SH_P2WPKH_publicKey,
+} from "../utils/bitcoinAddressHelpers"
+import { getBitcoinNetwork } from "../utils/bitcoinNetworkHelpers"
+import { checkNever } from "../utils/misc"
+import {
+  WalletAdapter,
+  WalletAdapterAddressPurpose,
+  WalletAdapterAddressType,
+  WalletAdapterBitcoinNetwork,
+} from "../WalletAdapters.types"
+import {
+  XverseCompatibleWalletAdapterImpl,
+  XverseCompatibleWalletAdapterImplAddress,
+} from "../utils/XverseCompatibleWalletAdapterImpl"
+import { XVERSE_PROVIDER_ID } from "./XverseWalletAdapter"
+
+declare global {
+  interface Window {
+    btc_providers?: import("sats-connect").Provider[]
+  }
+}
+
+export type XverseWalletAdapterAddresses =
+  XverseCompatibleWalletAdapterImplAddress
+
+/**
+ * Derivation path (BIP-49): m/49'/0'/0'/0/ address_index
+ */
+
+export class XverseWalletAdapterImpl
+  extends XverseCompatibleWalletAdapterImpl
+  implements WalletAdapter
+{
+  constructor() {
+    super({
+      walletDisplayName: "Xverse",
+      getProviderId: async () => {
+        return XVERSE_PROVIDER_ID
+      },
+      parseAddresses: async ({ sdk, network: xverseNetwork, addresses }) => {
+        // prettier-ignore
+        const network =
+          xverseNetwork === sdk.BitcoinNetworkType.Mainnet ? WalletAdapterBitcoinNetwork.MAINNET :
+          xverseNetwork === sdk.BitcoinNetworkType.Testnet ? WalletAdapterBitcoinNetwork.TESTNET :
+          xverseNetwork === sdk.BitcoinNetworkType.Testnet4 ? WalletAdapterBitcoinNetwork.TESTNET :
+          xverseNetwork === sdk.BitcoinNetworkType.Signet ? WalletAdapterBitcoinNetwork.UNKNOWN :
+          xverseNetwork === sdk.BitcoinNetworkType.Regtest ? WalletAdapterBitcoinNetwork.UNKNOWN :
+          (checkNever(xverseNetwork), WalletAdapterBitcoinNetwork.UNKNOWN)
+
+        const bitcoinNetwork = getBitcoinNetwork(
+          network === WalletAdapterBitcoinNetwork.MAINNET
+            ? "mainnet"
+            : "testnet",
+        )
+
+        return addresses.flatMap((a): XverseWalletAdapterAddresses[] => {
+          const purposes: WalletAdapterAddressPurpose[] = []
+          switch (a.purpose) {
+            case sdk.AddressPurpose.Ordinals:
+              purposes.push(
+                WalletAdapterAddressPurpose.Ordinals,
+                WalletAdapterAddressPurpose.BRC20,
+                WalletAdapterAddressPurpose.Runes,
+              )
+              break
+            case sdk.AddressPurpose.Payment:
+              purposes.push(WalletAdapterAddressPurpose.Bitcoin)
+              break
+          }
+
+          const scriptPubKey = hex.encode(
+            addressToScriptPubKey(bitcoinNetwork, a.address),
+          )
+
+          switch (a.addressType) {
+            case sdk.AddressType.stacks:
+              return []
+            case sdk.AddressType.p2pkh:
+              return [
+                {
+                  purposes,
+                  network,
+                  addressType: WalletAdapterAddressType.P2PKH,
+                  address: a.address,
+                  scriptPubKey,
+                  publicKey: a.publicKey,
+                },
+              ]
+            case sdk.AddressType.p2wpkh:
+              return [
+                {
+                  purposes,
+                  network,
+                  addressType: WalletAdapterAddressType.P2WPKH,
+                  address: a.address,
+                  scriptPubKey,
+                  publicKey: a.publicKey,
+                },
+              ]
+            case sdk.AddressType.p2tr: {
+              const tapInternalKey: string = a.publicKey
+              return [
+                {
+                  purposes,
+                  network,
+                  addressType: WalletAdapterAddressType.P2TR,
+                  address: a.address,
+                  scriptPubKey,
+                  publicKey: a.publicKey,
+                  tapInternalKey,
+                },
+              ]
+            }
+            case sdk.AddressType.p2sh: {
+              const redeemScript = hex.encode(
+                getRedeemScriptOf_P2SH_P2WPKH_publicKey(
+                  bitcoinNetwork,
+                  hex.decode(a.publicKey),
+                ),
+              )
+              return [
+                {
+                  purposes,
+                  network,
+                  addressType: WalletAdapterAddressType.P2SH_P2WPKH,
+                  address: a.address,
+                  scriptPubKey,
+                  publicKey: a.publicKey,
+                  redeemScript,
+                },
+              ]
+            }
+            case sdk.AddressType.p2wsh:
+              // not supported
+              return []
+            case sdk.AddressType.starknet:
+            case sdk.AddressType.spark:
+              return []
+            default:
+              checkNever(a.addressType)
+              return []
+          }
+        })
+      },
+    })
+  }
+}

package/src/adapters/XverseWalletAdapter.ts

@@ -0,0 +1,37 @@
+import type {
+  WalletAdapter,
+  WalletAdapterStatic,
+} from "../WalletAdapters.types"
+import { createAvailability } from "../utils/createAdapterAvailability"
+
+export const XVERSE_PROVIDER_ID = "XverseProviders.BitcoinProvider"
+
+const metadata = {
+  name: "Xverse",
+  iconUrl: import("../_/xverse.png").then(m => m.default),
+  websiteUrl: "https://xverse.app/",
+  downloadUrl: "https://www.xverse.app/download",
+}
+
+const availability = createAvailability<
+  import("sats-connect").Provider,
+  WalletAdapter
+>({
+  getPrecondition: () => {
+    const provider = (window.btc_providers ?? []).find(
+      p => p.id === XVERSE_PROVIDER_ID,
+    )
+    return provider == null ? null : { value: provider }
+  },
+  initializer: async () => {
+    const { XverseWalletAdapterImpl } =
+      await import("./XverseWalletAdapter.impl")
+    return new XverseWalletAdapterImpl()
+  },
+})
+
+export const XverseWalletAdapter: WalletAdapterStatic<WalletAdapter> = {
+  adapterId: XVERSE_PROVIDER_ID,
+  metadata,
+  getAdapter: () => availability,
+}

package/src/adapters/index.ts

@@ -0,0 +1,7 @@
+export { BitgetWalletAdapter } from "./BitgetWalletAdapter"
+export { LeatherWalletAdapter } from "./LeatherWalletAdapter"
+export { MagicEdenWalletAdapterFactory } from "./MagicEdenWalletAdapter"
+export { OkxWalletAdapter } from "./OkxWalletAdapter"
+export { UnisatWalletAdapter } from "./UnisatWalletAdapter"
+export { XverseWalletAdapter } from "./XverseWalletAdapter"
+export { MockAddressWalletAdapter } from "./MockAddressWalletAdapter"

package/src/env.d.ts

@@ -0,0 +1,9 @@
+declare module "*.png" {
+  const content: string
+  export default content
+}
+
+declare module "*.svg" {
+  const content: string
+  export default content
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./BitcoinWalletAdapterConnector"
+export * from "./WalletAdapters.types"
+export * from "./adapters"