BDB 主网签名接口说明

1. 适用范围与结论

• 有：在 BDBKEY App 内打开 H5/DApp 时，使用 window.ethereum.request({ method, params }) 发起连接、签名、发交易（与 MetaMask 类钱包一致）。
• 无：BDB 主网节点 不提供 代用户签名的 REST API；链上仅接受已签名的 eth_sendRawTransaction。
• 推荐环境：Discover / DApp 内置 WebView；默认选中网络即为 BDB Chain（chainId 20240606）。

2. BDB 主网参数（签名上下文）

交易与 typed data 中的 chainId 须与上表一致（EIP-155 / EIP-712 防重放）。 若 DApp 请求的链与钱包当前网络不一致，App 会提示切换网络或拒绝签名。

3. Provider 对象

页面加载后注入：

• window.ethereum — EIP-1193 Provider（request、on、emit、selectedAddress、chainId）
• window.web3.currentProvider — 与 window.ethereum 相同引用（兼容旧版 web3.js）
• window.AlphaWallet — 内部回调桥（DApp 一般无需直接调用）

连接示例（Ethers v6）

const provider = new ethers.BrowserProvider(window.ethereum);
const accounts = await provider.send("eth_requestAccounts", []);
const signer = await provider.getSigner();
const address = await signer.getAddress();
const network = await provider.getNetwork();
// network.chainId === 20240606n

切换到 BDB 主网

await window.ethereum.request({
  method: "wallet_switchEthereumChain",
  params: [{ chainId: "0x134d8de" }]
});
// 若返回 4902（链未添加），再 wallet_addEthereumChain，参数见 bdb-chain-integration.html

4. ethereum.request 方法一览

经钱包代理的 JSON-RPC（只读 / 估算）

以下方法不弹签名窗，由 App 转发到当前 DApp 上下文链的 RPC：

eth_blockNumber、eth_getBalance、eth_getTransactionCount、 eth_gasPrice、eth_estimateGas、eth_getCode、 eth_getStorageAt、eth_maxPriorityFeePerGas、eth_feeHistory、 eth_getBlockByNumber、eth_getBlockByHash

5. 消息签名

5.1 personal_sign（EIP-191，登录 / SIWE 常用）

const message = "Login to My DApp at " + Date.now();
const sig = await window.ethereum.request({
  method: "personal_sign",
  params: [message, userAddress]
});
// sig: 0x + r + s + v

服务端验签时使用与 Ethereum 相同的 personal_sign 规则（前缀 \x19Ethereum Signed Message:\n + 长度 + 消息体）。

5.2 EIP-712（eth_signTypedData_v4）

const typedData = {
  types: { EIP712Domain: [...], Mail: [...] },
  primaryType: "Mail",
  domain: { name: "...", version: "1", chainId: 20240606, verifyingContract: "0x..." },
  message: { ... }
};
const sig = await window.ethereum.request({
  method: "eth_signTypedData_v4",
  params: [userAddress, typedData]
});

domain.chainId 必须与 BDB 主网 20240606 一致，且与钱包当前网络匹配，否则 App 拒绝并提示网络不兼容。

5.3 用户界面流程

1. DApp 调用签名方法 → 底部 ActionSheetSignDialog 展示请求来源域名、消息摘要、签名地址。
2. 用户确认 → 若钱包启用密码/生物识别，则 AppPasswordPrompt 验证后本地签名。
3. 成功 → Promise resolve 为 0x 前缀签名；失败或关闭 → reject（见「取消与错误」）。

6. 交易签名与发送（eth_sendTransaction）

6.1 请求体字段

params[0] 支持 Ethereum 常见字段（hex 或 number，钱包会 normalize）：

6.2 行为说明

• 用户确认后：本地签名 → App 调用 RPC 广播 → 返回 交易哈希（不是仅返回 signed raw tx）。
• 原生转账典型 gas limit：21000；ERC20 转账约 144000（与 App 内 Send 一致）。

6.3 Ethers 示例

const tx = await signer.sendTransaction({
  to: "0xRecipient",
  value: ethers.parseEther("1.0"),
  chainId: 20240606
});
const receipt = await tx.wait();

7. BDB 主网 Gas 与手续费展示

• 链上原生 Gas 代币为 BDB（非 BNB）。
• App 在 BDB 链上 DApp 交易确认（ActionSheetDialog）默认使用 Legacy（type 0） 交易，即 gasPrice × gasLimit，避免节点返回 0 的 EIP-1559 字段导致手续费显示异常。
• 钱包内目标总手续费档位（估算展示）：约 0.02 / 0.025 / 0.03 BDB（慢 / 标准 / 快），与 BdbDexConfig 一致。

DApp 自行构造交易时，可调用代理 RPC 的 eth_gasPrice、eth_estimateGas，或让钱包在确认页覆盖/补全 Gas 参数。

8. 取消与错误

try {
  await window.ethereum.request({ method: "personal_sign", params: [msg, addr] });
} catch (e) {
  if (e.message === "cancelled") {
    // 用户拒绝
  }
}

建议在 UI 上将 cancelled 映射为用户可理解的「已取消签名」，勿当作链或 RPC 故障。

9. Provider 事件

window.ethereum.on("chainChanged", (chainId) => {
  console.log("chainChanged", chainId);
});
window.ethereum.on("accountsChanged", (accounts) => {
  console.log("accountsChanged", accounts);
});

10. WebView JavaScript 对话框

页面中的 alert、confirm、prompt 由 Web3JsDialogHelper 渲染为 App 风格弹窗（非系统 WebView 默认框）。

• confirm / prompt 取消 → 对应 JsResult.cancel()
• Activity 不可弹窗时（如后台）→ 直接 cancel，避免阻塞 WebView

与链上签名无关，但登录流程中若有 JS 对话框，行为与桌面浏览器「取消 = false / null」一致。

11. WalletConnect（可选）

通过 WalletConnect 连接时，支持的签名/交易 method 与上表一致，包括：

eth_sendTransaction、eth_signTransaction、 personal_sign、eth_sign、 eth_signTypedData / _v3 / _v4、 wallet_switchEthereumChain

用户在手机 App 上同样通过 ActionSheet 确认；拒绝时 WC 层返回「User rejected request」类错误。

12. Api V1 深链（系统浏览器，非 WebView Provider）

若从外部浏览器打开符合 AlphaWallet Api V1 规范的 HTTPS 链接，可唤起 BDBKEY 做有限操作（与 BDB 链无专用 path，但可在 redirect 回 DApp 后继续走主网逻辑）。

签名请求 query 参数（节选）：

• redirecturl — 完成后回跳 URL
• message — 待签消息
• address — 期望签名的账户（须与当前钱包匹配）
• metadata — JSON 字符串（展示用）

成功回跳时在 redirecturl 上追加 call=signpersonalmessage 与 signature=0x…。

13. 实现参考（维护者）

公链 JSON-RPC、代币地址、DEX 合约见 BDB Chain 公链接口对接说明。