跳到主要内容

WalletConnect 与 DApp

BitTool Signer 从不直接连接 DApp:它没有网络。WalletConnect 会话由你的钱包持有;当 DApp 向某个 BitTool Signer 账户请求签名时,你的钱包把请求转换为签名二维码,等待响应,再答复 DApp。BitTool Wallet 就是这样工作的。

你的钱包持有 WalletConnect 会话
BitTool Signer离线
  1. 1收到 DApp 的会话请求,例如 eip155:1 上的 personal_sign。
  2. 2向用户展示请求,必要时补全信息(nonce、gas、手续费),并固定要签名的确切字节。
  3. ur:eth-sign-request · ur:sol-sign-request · ur:tron-sign-request ▶
  4. 3解码、审核,并在用户输入钱包密码后签名。
  5. ◀ ur:eth-signature · ur:sol-signature · ur:tron-signature
  6. 4验证签名,如果方法要求则广播交易,并把 JSON-RPC 结果返回给 DApp。

WalletConnect 会话会超时,DApp 也可能放弃等待。请及时显示二维码,并允许用户取消;如果用户取消,请向 DApp 返回用户拒绝错误(EVM 链上为 4001)。

方法映射​

命名空间DApp 方法发给 BitTool Signer 的请求返回给 DApp 的结果
eip155personal_sign [message, address]eth-sign-request,data-type 3,消息字节0x 签名,65 字节,v = 27/28
eip155eth_signTypedData_v4 [address, typedData]data-type 2,类型化数据 JSON0x 签名,65 字节,v = 27/28
eip155eth_sendTransaction [tx]补全 nonce、gas 和手续费;data-type 4(EIP-1559)或 1(legacy)广播后返回交易哈希
eip155eth_signTransaction [tx]同上已签名的原始交易(不广播)
eip155eth_sign不支持:BitTool Signer 从不签署原始 32 字节哈希拒绝该请求
solanasolana_signMessage {message, pubkey}sol-sign-request,sign-type 2,解码后的消息字节Base58 格式的 { signature }
solanasolana_signTransaction {transaction}sign-type 1,交易的消息字节Base58 格式的 { signature }
solanasolana_signAndSendTransaction {transaction}sign-type 1广播后返回 { signature }
trontron_signMessage {address, message}tron-sign-request,data-type 2,消息字节v = 27/28 的 0x 签名
trontron_signTransaction {address, transaction}data-type 1,raw_data_hex 字节添加了 signature 的交易对象

会话中应提供的链 ID(CAIP-2):

链CAIP-2
EVMeip155:1、eip155:56、eip155:42161、eip155:8453、eip155:10、eip155:137、eip155:100、eip155:43114
Solana 主网solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
TRON 主网tron:0x2b6653dc

只提供用户已配对的账户,并且只提供 BitTool Signer 能够签名的网络。任何其他链 ID 上的 eth_sendTransaction 都会被签名器拒绝。

常见陷阱​

  • personal_sign 的参数顺序。规范是 [message, address],但有些 DApp 会发送 [address, message]。请识别出其中 20 字节的地址。对于字节内容,消息以十六进制(0x…)表示;作为 sign-data 时请传入解码后的字节,绝不要传十六进制文本。
  • 类型化数据以字符串形式传入。eth_signTypedData_v4 通常以字符串形式发送 JSON。请直接将其作为 UTF-8 字节传递,不要重新序列化,这样整数和地址的写法能与 DApp 原本的写法完全一致。如果必须重新序列化,请将大整数保留为字符串。
  • Solana:发送消息,而不是交易。solana_signTransaction 提供的是 Base64 编码、签名槽位为空的序列化交易。请将其反序列化,只发送消息字节。如果 DApp 构建的是使用地址查找表的 v0 交易,BitTool Signer 将无法签名。
  • Solana 消息编码。solana_signMessage 以 Base58 发送消息,请先将其解码为字节。
  • TRON 交易结构。不同 DApp 包装交易的方式不同:params.transaction.transaction、params.transaction 或 params 本身。取包含 raw_data_hex 的那个对象,检查 txID = SHA-256(raw_data),然后对 raw_data_hex 字节签名。
  • TRON 消息签名。签名器返回的恢复字节是 0/1;使用 TronWeb 的 DApp 期望 27/28。请给最后一个字节加上 27。

完整示例​

每个示例都展示了你的钱包从 DApp 收到的请求、与 BitTool Signer 之间的二维码往返,以及你返回的结果。所有示例都使用测试助记词;完整的链相关细节请参见 EVM、Solana 和 TRON 页面。

一次 Sign-In with Ethereum 登录。

DApp 请求(chainId eip155:1)
{
"method": "personal_sign",
"params": [
"0x6170702e6578616d706c652e6f72672077616e747320796f7520746f207369676e20696e207769746820796f757220457468657265756d206163636f756e743a0a3078393835384566464432333242343033334534376439303030334434314543333445636145646139340a0a5369676e20696e20746f204578616d706c65204170702e0a0a5552493a2068747470733a2f2f6170702e6578616d706c652e6f72670a56657273696f6e3a20310a436861696e2049443a20310a4e6f6e63653a203866336b326d39710a4973737565642041743a20323032362d31302d31385430393a33303a30302e3030305a",
"0x9858EfFD232B4033E47d90003D41EC34EcaEda94"
]
}

请求(你的钱包 → BitTool Signer)

eth-sign-request2 帧
UR:ETH-SIGN-REQUEST/1-2/LPADAOCFADFDCYCMDSCMFHHDOXOSADTPDAGDHECKNDDWKIFTGLJLLEBDCEDPFMGWHTAMAOHDWEHSJOJODMIHKSHSJNJOJZIHDMJLJPIOCXKTHSJTJYJKCXKKJLKPCXJYJLCXJKINIOJTCXINJTCXKTINJYISCXKKJLKPJPCXFEJYISIHJPIHKPJNCXHSIAIAJLKPJTJYFTBKDYKSESETECETFEIYFGFYEYEOEYFWEEDYEOEOFEEEEMIEESDYDYDYEOFYEEEHFEFXEOEEFEIAHSFEIEHSESEEBKBKGUINIOJTCXINJTCXJYJLCXFEKSHSJNJOJZIHCXFPJOJODMBKBKGOGMGAFTCXISCPDEGMOY
1 / 2
CBOR 字段
{
"1 request-id": {
"uuid (tag 37)": "5f1e9b2c7d3a4e6f8a0b1c2d3e4f5a06"
},
"2 sign-data": "6170702e6578616d706c652e6f72672077616e747320796f7520746f207369676e20696e207769746820796f757220457468657265756d206163636f756e743a0a3078393835384566464432333242343033334534376439303030334434314543333445636145646139340a0a5369676e20696e20746f204578616d706c65204170702e0a0a5552493a2068747470733a2f2f6170702e6578616d706c652e6f72670a56657273696f6e3a20310a436861696e2049443a20310a4e6f6e63653a203866336b326d39710a4973737565642041743a20323032362d31302d31385430393a33303a30302e3030305a",
"3 data-type": 3,
"4 chain-id": 1,
"5 derivation-path": {
"crypto-keypath (tag 304)": {
"1 components": [
44,
true,
60,
true,
0,
true,
0,
false,
0,
false
],
"2 source-fingerprint": 1942346250
}
},
"6 address": "9858effd232b4033e47d90003d41ec34ecaeda94",
"7 origin": "BitTool Wallet"
}
显示二维码文本和原始 CBOR
二维码文本 · ur:eth-sign-request
UR:ETH-SIGN-REQUEST/1-2/LPADAOCFADFDCYCMDSCMFHHDOXOSADTPDAGDHECKNDDWKIFTGLJLLEBDCEDPFMGWHTAMAOHDWEHSJOJODMIHKSHSJNJOJZIHDMJLJPIOCXKTHSJTJYJKCXKKJLKPCXJYJLCXJKINIOJTCXINJTCXKTINJYISCXKKJLKPJPCXFEJYISIHJPIHKPJNCXHSIAIAJLKPJTJYFTBKDYKSESETECETFEIYFGFYEYEOEYFWEEDYEOEOFEEEEMIEESDYDYDYEOFYEEEHFEFXEOEEFEIAHSFEIEHSESEEBKBKGUINIOJTCXINJTCXJYJLCXFEKSHSJNJOJZIHCXFPJOJODMBKBKGOGMGAFTCXISCPDEGMOY
UR:ETH-SIGN-REQUEST/2-2/LPAOAOCFADFDCYCMDSCMFHHDOXJYJYJOJKFTDLDLHSJOJODMIHKSHSJNJOJZIHDMJLJPIOBKHFIHJPJKINJLJTFTCXEHBKFXISHSINJTCXGAFYFTCXEHBKGLJLJTIAIHFTCXETIYEOJEEYJNESJSBKGAJKJKKPIHIECXFPJYFTCXEYDYEYENDPEHDYDPEHETGHDYESFTEODYFTDYDYDMDYDYDYHTAXAXAAADAHTAADDYOEADLECSDWYKCSFNYKAEYKAEWKAEWKAOCYJKSKTNBKAMGHMKHDWSZCCNDNFZEOVEKIMHAEFSFPWPEEWPPLTNMWATJTFWINJYGHJLJLJZCXHGHSJZJZIHJYCWTTFYJT
UR CBOR(十六进制)
a701d825505f1e9b2c7d3a4e6f8a0b1c2d3e4f5a060258ed6170702e6578616d706c652e6f72672077616e747320796f7520746f207369676e20696e207769746820796f757220457468657265756d206163636f756e743a0a3078393835384566464432333242343033334534376439303030334434314543333445636145646139340a0a5369676e20696e20746f204578616d706c65204170702e0a0a5552493a2068747470733a2f2f6170702e6578616d706c652e6f72670a56657273696f6e3a20310a436861696e2049443a20310a4e6f6e63653a203866336b326d39710a4973737565642041743a20323032362d31302d31385430393a33303a30302e3030305a0303040105d90130a2018a182cf5183cf500f500f400f4021a73c5da0a06549858effd232b4033e47d90003d41ec34ecaeda94076e426974546f6f6c2057616c6c6574

响应(BitTool Signer → 你的钱包)

解码后的响应 · ur:eth-signature
{
"request-id": {
"uuid": "5f1e9b2c7d3a4e6f8a0b1c2d3e4f5a06"
},
"signature": "23c5ba3f5d247b4c81d55b7c44a3951a14c82e70f17ef2c19abea893c4e5bef05795a7261ac2bd9da29be2dfef529327e1b0724580fccac106bed3d007854f6b1b"
}
显示二维码文本和原始 CBOR
二维码文本 · ur:eth-signature
UR:ETH-SIGNATURE/OEADTPDAGDHECKNDDWKIFTGLJLLEBDCEDPFMGWHTAMAOHDFPCNSKRDFHHLDKKGGSLYTLHPKEFYOTMDCYBBSPDMJOWNKBWZSENYRNPDMUSSVWRNWTHGMDOSDSCYSARYNTOENDVOURWSGMMUDIVYPFJPFELAZTSGSEAMRNTETIATLPGWJECWWNKEFGEH
UR CBOR(十六进制)
a201d825505f1e9b2c7d3a4e6f8a0b1c2d3e4f5a0602584123c5ba3f5d247b4c81d55b7c44a3951a14c82e70f17ef2c19abea893c4e5bef05795a7261ac2bd9da29be2dfef529327e1b0724580fccac106bed3d007854f6b1b

由你的钱包组装

walletConnectResult
0x23c5ba3f5d247b4c81d55b7c44a3951a14c82e70f17ef2c19abea893c4e5bef05795a7261ac2bd9da29be2dfef529327e1b0724580fccac106bed3d007854f6b1b
返回给 DApp 的 JSON-RPC 结果
0x23c5ba3f5d247b4c81d55b7c44a3951a14c82e70f17ef2c19abea893c4e5bef05795a7261ac2bd9da29be2dfef529327e1b0724580fccac106bed3d007854f6b1b

展示请求​

用户需要确认两次:一次在你的钱包中,一次在 BitTool Signer 中。请让两个界面的内容保持一致。展示 DApp 的名称和 URL、网络,以及与 BitTool Signer 即将展示的相同的解码内容:金额、收款方、spender,消息则展示全文。对于未知的合约调用,请标记为未知,而不要猜测;BitTool Signer 同样会将其标记为未解码。