Bitcoin

Bitcoin DApp 与 imToken 钱包交互开发者文档

钱包 Provider 注入

由于 Bitcoin 社区没有 Provider 的标准规范，imToken 参考了以太坊社区的 EIP-1193，通过向 window 对象注入 bitcoin 属性来实现。

具体实现如下:

window.bitcoin = new BitcoinProvider({
  requestTransport: ({ method, params }) => window.imToken.callApi(
    'bitcoin.request',
    {
      method,
      params
    }
  )
})

开发者可以通过 window.bitcoin 来访问钱包 Provider 提供的 API:

Schema

type WalletRpcSchema = [
  /**
   * @description Requests that the user provides an address to be identified by.
   * @example
   * provider.request({ method: 'btc_requestAccounts' }] })
   * // => ['tbc1...', 'tbc1...']
   */
  {
    Method: 'btc_requestAccounts'
    Parameters?: undefined
    ReturnType: string[]
  },
  /**
   * @description Returns the current network associated with the wallet.
   * @example
   * provider.request({ method: 'btc_getNetwork' })
   * // => 'signet'
   */
  {
    Method: 'btc_getNetwork'
    Parameters?: undefined
    ReturnType: Network
  },

  /**
   * @description Gets the public key of the connected wallet.
   * @example
   * provider.request({ method: 'btc_getPublicKey' }] })
   * // => 'publicKey...'
   */
  {
    Method: 'btc_getPublicKey'
    Parameters?: undefined
    ReturnType: string
  },

  /**
   * @description Returns the balance of an address in satoshis.
   * @example
   * provider.request({ method: 'btc_getBalance', params: ['tbc1...'] })
   * // => 1000
   */
  {
    Method: 'btc_getBalance'
    Parameters: [address: string]
    ReturnType: number
  },

  /**
   * @description Retrieves the unspent transaction outputs (UTXOs) for a given address and amount.
   * If the amount is provided, it will return UTXOs that cover the specified amount.
   * If the amount is not provided, it will return all available UTXOs for the address.
   * @example
   * provider.request({ method: 'btc_getUnspent', params: ['tbc1...', 100] })
   * // => [{ utxo }]
   */
  {
    Method: 'btc_getUnspent'
    Parameters: [address: string, amount: number]
    ReturnType: UTXO[]
  },

  /**
   * @description Signs the given PSBT in hex format.
   * @example
   * provider.request({ method: 'btc_signPsbt', params: ['0x...', true] })
   * // => '0x...'
   */
  {
    Method: 'btc_signPsbt'
    Parameters: [psbtHex: Hex, autoFinalize?: boolean]
    ReturnType: Hex
  },
  /**
   * @description Signs multiple PSBTs in hex format.
   * @example
   * provider.request({ method: 'btc_signPsbts', params: ['0x...', '0x...'] })
   * // => ['0x...', '0x...']
   */
  {
    Method: 'btc_signPsbts'
    Parameters: [psbtsHexes: Hex[]]
    ReturnType: Hex[]
  },
  /**
   * @description Signs a message using BIP-322.
   * @example
   * provider.request({ method: 'btc_signMessage', params: ['tb1...'] })
   * // => 'base64...'
   */
  {
    Method: 'btc_signMessage'
    Parameters: [
      message: string,
      type: 'bip322-simple' | 'bip322-full' | 'bip322-legacy'
    ]
    ReturnType: string 
  },
  /**
   * @description send raw transacion
   * @example
   * provider.request({ method: 'btc_sendRawTransaction', params: ['signature'] })
   * // => 'string'
   */
   {
     Method: 'btc_sendRawTransaction'
     Parameters: [signature: string]
     ReturnType: string
   },

  /**
   * @description Switch the wallet to the given network.
   * @example
   * provider.request({ method: 'btc_switchNetwork', params: ['signet'] })
   * // => null
   */
  {
    Method: 'btc_switchNetwork'
    Parameters: [network: Network]
    ReturnType: null
  }
]

Provider API

请求用户账户

• 方法: btc_requestAccounts

• 参数: 无

• 返回: string[]

示例:

const accounts = await window.bitcoin.request({
    method: 'btc_requestAccounts'
})
// 返回: ['tbc1...', 'tbc1...']

获取当前网络

• 方法: btc_getNetwork

• 参数: 无

• 返回: Network

示例:

const network = await window.bitcoin.request({
    method: 'btc_getNetwork' 
})
// 返回: 'signet'

获取公钥

• 方法: btc_getPublicKey

• 参数: 无

• 返回: string

示例:

const publicKey = await window.bitcoin.request({
    method: 'btc_getPublicKey' 
})
// 返回: 'publicKey...'

获取余额

• 方法: btc_getBalance

• 参数: [address: string]

• 返回: number (单位为聪)

示例:

const balance = await window.bitcoin.request({
    method: 'btc_getBalance', 
    params: ['tbc1...'] 
})
// 返回: 1000

获取未花费交易 UTXO

• 方法: btc_getUnspent

• 参数: [address: string, amount: number]

• 返回: UTXO[]

示例:

const utxos = await window.bitcoin.request({ 
    method: 'btc_getUnspent', 
    params: ['tbc1...', 100] 
})
// 返回: [{ utxo }]

签名 PSBT

• 方法: btc_signPsbt

• 参数: [psbtHex: Hex, autoFinalize?: boolean]

• 返回: Hex

示例:

const signedPsbt = await window.bitcoin.request({
    method: 'btc_signPsbt', 
    params: ['0x...', true ]
})
// 返回: '0x...'

批量签名 PSBT

暂未支持

• 方法: btc_signPsbts

• 参数: [psbtsHexes: Hex[]]

• 返回: Hex[]

示例:

const signedPsbts = await window.bitcoin.request({
    method: 'btc_signPsbts', 
    params: ['0x...', '0x...'] 
})
// 返回: ['0x...', '0x...']

签名消息

仅支持 bip322-simple

• 方法: btc_signMessage

• 参数: [message: string, type: 'bip322-simple' | 'bip322-full' | 'bip322-legacy']

• 返回: string (Base64 编码)

示例:

const signature = await window.bitcoin.request({
    method: 'btc_signMessage', 
    params: ['Hello, World!', 'bip322-simple'] 
})
// 返回: 'base64...'

发送签名结果

• 方法: btc_sendRawTransaction

• 参数: [signature: string]

• 返回: string

示例:

const signature = await window.bitcoin.request({
    method: 'btc_sendRawTransaction', 
    params: ['signature']
})
// 返回: '...'

切换网络

暂不支持

• 方法: btc_switchNetwork

• 参数: [network: Network]

• 返回: null

示例:

await window.bitcoin.request({
    method: 'btc_switchNetwork', 
    params: ['signet'] 
})
// 返回: null

其他方法

获取钱包名称和 icon

const walletName = window.bitcoin.getName(); // => imToken
const walletIcon = window.bitcoin.getIcon(); // => base64 icon

事件监听

Provider 继承自 EventEmitter，可以使用标准的事件监听方法。

event types

type ProviderEventMap = {
  accountsChanged(accounts: string[]): void
  networkChanged(network: Network): void
  connect(connectInfo: ProviderConnectInfo): void
  disconnect(error: ProviderRpcError): void
  message(message: ProviderMessage): void
}

type ProviderEvents = {
  on<TEvent extends keyof ProviderEventMap>(
    event: TEvent,
    listener: ProviderEventMap[TEvent]
  ): void
  removeListener<TEvent extends keyof ProviderEventMap>(
    event: TEvent,
    listener: ProviderEventMap[TEvent]
  ): void
}

版本兼容

imToken 从 2.15.4 才开始 注入 bitcoin provider