跳到主要内容

EVM（eth-sign-request）

ur:eth-sign-requestur:eth-signatureEIP-155EIP-1559EIP-712

eth-sign-request​

键字段类型内容
1request-id37(bytes)16 个随机字节（接受 1–64 字节）
2sign-databytes要签名的内容，取决于数据类型（见下文）
3data-typeuint1、2、3 或 4
4chain-iduintEVM 链 ID。交易必须提供；其他请求也建议提供
5derivation-path304(crypto-keypath)完整路径，例如 m/44'/60'/0'/0/0，并带主指纹
6addressbytes (20)签名者地址的原始字节，而不是 0x 文本
7origintext向用户显示，例如 "BitTool Wallet"

数据类型​

data-typesign-data典型来源
1 交易未签名的 legacy 交易 RLP，带 EIP-155 链 ID：rlp([nonce, gasPrice, gas, to, value, data, chainId, 0, 0])在使用 legacy gas 的链上调用 eth_sendTransaction
4 类型化交易未签名的 EIP-2718 交易封装：0x02 ‖ rlp([...])（EIP-1559）或 0x01 ‖ rlp([...])（EIP-2930）eth_sendTransaction，大多数现代转账
3 个人消息原始消息字节，不带 "\x19Ethereum Signed Message:\n" 前缀，也不做哈希personal_sign
2 类型化数据UTF-8 编码的 EIP-712 JSON：{types, primaryType, domain, message}eth_signTypedData_v4

只发送原始字节，绝不发送哈希。BitTool Signer 会解析它要签名的内容，拒绝盲签 32 字节的摘要。

网络​

交易字节中的链 ID、键 4 中的链 ID 以及（类型化数据的）domain.chainId 必须全部一致，并且必须是以下之一：

链 ID网络链 ID网络
1Ethereum10OP Mainnet
56BNB Chain137Polygon PoS
42161Arbitrum One100Gnosis
8453Base43114Avalanche C-Chain

不支持的内容​

Blob 交易（type 3）、EIP-7702 交易（type 4）、不带链 ID 的未受保护 legacy 交易，以及对原始 32 字节哈希执行的 eth_sign。其他链 ID 的请求会被拒绝。

EIP-712 规则​

BitTool Signer 严格按照声明对类型化数据做哈希，并对值有严格要求，因为“显示的是一种值、哈希的却是另一种值”是一种典型的钓鱼手法：

  • bool 值必须是 JSON 的 true/false，不能是字符串。
  • 整数只有在不超过 253 − 1 时才能使用 JSON 数字；更大的值必须是不带前导零的十进制字符串，或 0x 十六进制字符串。
  • address 值为 0x + 40 位十六进制数字，大小写混合的地址必须带有有效的 EIP-55 校验和；bytesN 必须恰好为 N 字节。
  • message 必须恰好包含其类型所声明的字段：既不能缺少，也不能多出。
  • EIP712Domain 只能包含 name、version、chainId、verifyingContract 和 salt；域分隔符按声明的顺序计算。

已知结构会得到完整审核：ERC-2612 / DAI Permit、Permit2（single、batch、transfer-from）、Safe SafeTx，以及 NFT 市场订单（Seaport、LooksRare、Blur）。其他结构会逐字段显示，并标记为部分解码。

个人消息​

长度为 1 到 8,192 的任意字节。有效的 UTF-8 显示为文本；其他内容显示为十六进制，并标记为不透明。32 字节的消息会被标记为高风险，因为它很可能是用户无法读懂的哈希。

eth-signature​

eth-signature = {
  1: 37(request-id bytes),     ; copied from the request
  2: signature                 ; r (32) ‖ s (32) ‖ v (1 or more bytes)
}

该签名不是已签名的交易；交易由你的钱包组装。v 部分取决于数据类型：

data-typev长度
1 legacy 交易chainId × 2 + 35 + yParity（EIP-155），大端序，使用尽可能少的字节65 字节或更多
4 类型化交易yParity（0 或 1）65
2、3 消息27 + yParity65

因此，应将从第 64 字节到末尾的内容作为无符号大端整数读取为 v。例如，在 Avalanche（链 ID 43114）上，legacy 交易的 v 为 86263 或 86264，占三个字节，签名长度为 67 字节。总是把第 64 字节当作 v 的代码，在链 ID 大于等于 110 的任何链上都会出错。

完成签名的步骤：

  1. 检查请求 ID。
  2. 根据你预期的摘要（交易哈希、EIP-191 哈希或 EIP-712 哈希）恢复出签名者，并与已配对的地址进行比较。
  3. 对于交易，将 r、s 和奇偶值填入未签名交易，序列化，并在广播前检查交易哈希。

代码​

使用 ethers 和 Keystone 的 @keystonehq/bc-ur-registry-eth：

examples/evm.mjs
import { randomUUID } from 'node:crypto';
import { Transaction, Signature, getBytes } from 'ethers';
import { EthSignRequest, DataType, ETHSignature } from '@keystonehq/bc-ur-registry-eth';
import { URDecoder } from '@ngraveio/bc-ur';

export function buildEthRequest(tx, { path, masterFingerprint, address }) {
  const unsigned = Transaction.from(tx);                    // no signature yet
  const requestId = randomUUID();
  const request = EthSignRequest.constructETHRequest(
    Buffer.from(getBytes(unsigned.unsignedSerialized)),       // the bytes to sign, not a hash
    unsigned.type === 0 ? DataType.transaction : DataType.typedTransaction, // 1 or 4
    path,                                                     // "m/44'/60'/0'/0/0"
    masterFingerprint,                                        // "73c5da0a"
    requestId,
    Number(unsigned.chainId),
    address,
    'BitTool Wallet',                                         // origin, shown to the user
  );
  const encoder = request.toUREncoder(400);                   // fragment length in bytes
  const frames = [];
  for (let i = 0; i < encoder.fragmentsLength; i++) frames.push(encoder.nextPart().toUpperCase());
  return { unsigned, requestId, frames };
}
examples/evm.mjs
export function readEthSignature(frames, { unsigned, requestId, address }) {
  const decoder = new URDecoder();
  for (const frame of frames) decoder.receivePart(frame);
  if (!decoder.isSuccess()) throw new Error('Incomplete or invalid QR');
  const ur = decoder.resultUR();
  if (ur.type !== 'eth-signature') throw new Error(`Expected eth-signature, got ${ur.type}`);

  const response = ETHSignature.fromCBOR(ur.cbor);
  const id = response.getRequestId();
  if (!id || Buffer.from(id).toString('hex') !== requestId.replace(/-/g, '')) throw new Error('Signature is for another request');

  const sig = Buffer.from(response.getSignature());          // r (32) ‖ s (32) ‖ v (1+ bytes)
  const r = '0x' + sig.subarray(0, 32).toString('hex');
  const s = '0x' + sig.subarray(32, 64).toString('hex');
  const v = BigInt('0x' + sig.subarray(64).toString('hex'));
  const yParity = unsigned.type === 0 ? Number(v - unsigned.chainId * 2n - 35n) : Number(v);
  if (yParity !== 0 && yParity !== 1) throw new Error('Unexpected v');

  const signed = unsigned.clone();
  signed.signature = Signature.from({ r, s, yParity });
  if (signed.from !== address) throw new Error('Signed by an unexpected key');
  return signed.serialized;                                   // ready for eth_sendRawTransaction
}

测试向量​

全部来自测试助记词的 m/44'/60'/0'/0/0（0x9858EfFD232B4033E47d90003D41EC34EcaEda94）。

在 Ethereum 上发送 0.01 ETH，nonce 为 12，最高手续费 30 gwei，优先费 1 gwei。

请求（你的钱包 → BitTool Signer）

eth-sign-request1 帧
UR:ETH-SIGN-REQUEST/OSADTPDAGDHECKNDDWKIFTGLJLLEBDCEDPFMGWHTADAOHDEHAOWSADBNLRFRNYSGAELPAMZTCNPSAELFGMAYMWAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEUEPMLTCNLNWZJLSEAEAELARTAXAAAAADAHTAADDYOEADLECSDWYKCSFNYKAEYKAEWKAEWKAOCYJKSKTNBKAMGHMKHDWSZCCNDNFZEOVEKIMHAEFSFPWPEEWPPLTNMWATJTFWINJYGHJLJLJZCXHGHSJZJZIHJYKEBDYTMH
CBOR 字段
{
  "1 request-id": {
    "uuid (tag 37)": "5f1e9b2c7d3a4e6f8a0b1c2d3e4f5a01"
  },
  "2 sign-data": "02ef010c843b9aca008506fc23ac0082520894000000000000000000000000000000000000dead872386f26fc1000080c0",
  "3 data-type": 4,
  "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/OSADTPDAGDHECKNDDWKIFTGLJLLEBDCEDPFMGWHTADAOHDEHAOWSADBNLRFRNYSGAELPAMZTCNPSAELFGMAYMWAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEAEUEPMLTCNLNWZJLSEAEAELARTAXAAAAADAHTAADDYOEADLECSDWYKCSFNYKAEYKAEWKAEWKAOCYJKSKTNBKAMGHMKHDWSZCCNDNFZEOVEKIMHAEFSFPWPEEWPPLTNMWATJTFWINJYGHJLJLJZCXHGHSJZJZIHJYKEBDYTMH
UR CBOR（十六进制）
a701d825505f1e9b2c7d3a4e6f8a0b1c2d3e4f5a0102583102ef010c843b9aca008506fc23ac0082520894000000000000000000000000000000000000dead872386f26fc1000080c00304040105d90130a2018a182cf5183cf500f500f400f4021a73c5da0a06549858effd232b4033e47d90003d41ec34ecaeda94076e426974546f6f6c2057616c6c6574

响应（BitTool Signer → 你的钱包）

解码后的响应 · ur:eth-signature
{
  "request-id": {
    "uuid": "5f1e9b2c7d3a4e6f8a0b1c2d3e4f5a01"
  },
  "signature": "6d11ee93f7876a78ea19f4f9c8e551e4522b6deb8349a6572d076b4e67ceb4416db3f690b339bf658a5c8d2ad2f75cdf3252f07f940a821f65bb6cb91e9782a101"
}
显示二维码文本和原始 CBOR
二维码文本 · ur:eth-signature
UR:ETH-SIGNATURE/OEADTPDAGDHECKNDDWKIFTGLJLLEBDCEDPFMGWHTADAOHDFPJNBYWYMUYLLTIMKSWDCFWKYTSPVWGYVEGMDNJNWMLSGAOLHGDPATJEGLIOTOQZFPJNQDYNMHQDESRSIHLEHHLGDRTDYLHHUREYGMWTLBMWBKLFCTIHRKJZRHCKMSLFOYADCWJNLUAY
UR CBOR（十六进制）
a201d825505f1e9b2c7d3a4e6f8a0b1c2d3e4f5a010258416d11ee93f7876a78ea19f4f9c8e551e4522b6deb8349a6572d076b4e67ceb4416db3f690b339bf658a5c8d2ad2f75cdf3252f07f940a821f65bb6cb91e9782a101

由你的钱包组装

signedTxHex
0x02f872010c843b9aca008506fc23ac0082520894000000000000000000000000000000000000dead872386f26fc1000080c001a06d11ee93f7876a78ea19f4f9c8e551e4522b6deb8349a6572d076b4e67ceb441a06db3f690b339bf658a5c8d2ad2f75cdf3252f07f940a821f65bb6cb91e9782a1
txHash
0xd7e69271cce78ffdf924b78126b93fb3cdf4f797f7e216bcb6702c8d97b47ea3

Safe（多签）所有者​

要将 BitTool Signer 用作 Safe 的一个所有者，请从该所有者已配对的地址，以 EIP-712（数据类型 2）方式签署 SafeTx；键 6 是所有者的地址，而不是 Safe 的地址。BitTool Signer 会解码 CALL/DELEGATECALL、MultiSend、所有者/模块/守卫（guard）变更以及 gas 退款参数，并提高危险操作的风险等级。收集、排序和提交所有者签名由你的钱包负责。