内置浏览器 DApp 发现与连接
适用范围与授权边界
本文说明 InvisiPay 内置浏览器中的注入式 EVM provider 接入。发现 provider、允许网站读取账户、应用账号登录、解锁钱包和授权签名是不同能力,详见账户与签名边界。连接成功不授予任意签名或自动支付,也不证明某条链已部署隐私能力。
这里不承诺外部桌面 WalletConnect、浏览器扩展、多账户同时授权、跨设备会话同步或任意签名方法。下面是发现与连接示例,不是方法支持清单,也不调用交易或签名。发布版本与账户类型的能力仍须在实际环境中验证。
发现 provider:先监听,再请求
使用 EIP-6963 的发现握手:先监听 eip6963:announceProvider,再发出 eip6963:requestProvider。钱包可以主动公告,也可回应后续请求;不要只读一次 window.ethereum,也不要假定第一个公告就是用户要用的钱包。重复公告不能重复创建同一个候选。
公告中的 name、icon、rdns 与 uuid 不是钱包身份认证。不要按名字、反向域名或 isMetaMask 自动选择、授信或请求账户;由用户明确选择,并在钱包自己的界面核对来源。文字使用 textContent,不执行公告内容;示例不渲染图标。需要图标时实施独立校验,不把 SVG 内容注入 DOM 或用作可执行对象。标准中的 UUID 用于当前发现会话的区分,不应硬编码旧示例值或用它证明品牌。
window.ethereum 可作为明确标示的兼容候选,但不能自动覆盖用户已选 provider;其存在也不证明身份或授权。若没有候选,提示用户在支持的内置浏览器打开或重新触发发现,不自动转入另一种未核验连接通道。
账户授权与会话归属
- 用户在钱包列表主动选择后,才调用该 provider 的
eth_requestAccounts。等待授权期间禁重复触发;不要在发现事件、定时器或页面重渲染时弹授权。 - 用户可在钱包中选择本次授权账户,也可拒绝。
eth_accounts用于读取当前可见账户,未获站点授权时应按空列表处理,不把其他站点的地址或缓存地址当作本次授权。 - 授权后读取
eth_accounts与eth_chainId,校验结果及所选部署;不把“有地址”当作钱包已解锁、可签名或后端登录成功。 - 内置浏览器按 origin 管理站点会话,当前范围是一站点一个授权账户。重访站点可能恢复已有授权,但必须重新读取当前账户与链;不要为每次刷新强制弹窗,也不要承诺会话跨设备恢复。
- 账户属于该站点会话,不应从首页当前活跃账户推断。浏览器网络也应从 provider 实时读取,不以首页“全部网络”或会话保存的历史链号代替。
不同标签或页面导航不能共用一份未绑定来源的待处理授权。切换站点、账户、网络或组件销毁后,作废旧查询与旧确认;迟到的 Promise 不能把旧结果写入新页面。连接只暴露获授权信息,后续动作仍要单独检查权限。
最小发现与连接示例
准备以下页面元素,在它们创建后执行 JavaScript。钱包按钮的名字仅用于不可信展示,不按名字过滤 InvisiPay;示例中的数量上限只是防止公告无限增长,不是产品支持上限。
<div id="wallets" aria-label="Discovered wallets"></div>
<button id="cancel" type="button">Stop locally</button>
<pre id="status" role="status"></pre>
const list = document.querySelector("#wallets");
const status = document.querySelector("#status");
const cancel = document.querySelector("#cancel");
const seen = new WeakSet();
let count = 0, generation = 0, revision = 0;
let active = null, busy = false, disposed = false;
let unbind = () => {};
const address = (x) => typeof x === "string" && /^0x[0-9a-f]{40}$/i.test(x);
const chain = (x) => typeof x === "string" && /^0x[0-9a-f]+$/i.test(x);
const show = (text) => { status.textContent = text; };
function invalidated() {
revision++;
// Clear account-dependent state, balances and unsigned previews here too.
show("Context changed. Recheck the account and network before continuing.");
}
async function connect(provider) {
if (disposed || busy) return; // One outstanding wallet prompt at a time.
unbind();
active = provider;
const owner = ++generation;
const current = () => !disposed && generation === owner && active === provider;
const changed = () => { if (current()) invalidated(); };
provider.on("accountsChanged", changed);
provider.on("chainChanged", changed);
provider.on("disconnect", changed);
unbind = () => {
provider.removeListener("accountsChanged", changed);
provider.removeListener("chainChanged", changed);
provider.removeListener("disconnect", changed);
};
busy = true;
show("Check the request in your wallet.");
try {
await provider.request({ method: "eth_requestAccounts" });
if (!current()) return;
// Read again after approval: the wallet may have emitted change events.
const snapshot = revision;
const [accounts, chainId] = await Promise.all([
provider.request({ method: "eth_accounts" }),
provider.request({ method: "eth_chainId" }),
]);
if (!current() || revision !== snapshot) return;
if (!Array.isArray(accounts) || !accounts.every(address) || !chain(chainId)) {
throw new Error("Invalid provider response");
}
if (accounts.length === 0) {
show("No authorized account. Connect again only when you choose to.");
return;
}
// No signing, transfers, backend login or chain-support inference here.
show(JSON.stringify({ accounts, chainId }, null, 2));
} catch (error) {
if (!current()) return;
const messages = {
4001: "Request rejected or cancelled. No automatic retry.",
4100: "Not authorized. Check the wallet before trying again.",
4200: "Method unsupported. Check this wallet version.",
4900: "Provider disconnected. Check connectivity.",
4901: "Requested network unavailable. Check the browser network.",
};
show(messages[error?.code] ?? "Connection result unavailable. Check the wallet.");
} finally {
busy = false;
}
}
function announced(event) {
if (disposed || count >= 32) return; // Bound untrusted announcement volume.
const detail = event.detail;
const provider = detail?.provider;
if (!provider || typeof provider !== "object" || seen.has(provider) ||
typeof provider.request !== "function" || typeof provider.on !== "function" ||
typeof provider.removeListener !== "function") return;
seen.add(provider);
count++;
const label = typeof detail.info?.name === "string"
? detail.info.name.slice(0, 80) : "Injected wallet";
const button = document.createElement("button");
button.type = "button";
button.textContent = `${label} (unverified provider)`;
button.addEventListener("click", () => { void connect(provider); });
list.append(button); // Do not render the announced icon or HTML.
}
cancel.addEventListener("click", () => {
generation++;
active = null;
unbind();
unbind = () => {};
show("Stopped locally. Dismiss any wallet prompt; no new request until it settles.");
// Keep busy while request() is pending. This does not cancel the wallet RPC.
});
window.addEventListener("eip6963:announceProvider", announced);
window.dispatchEvent(new Event("eip6963:requestProvider"));
window.addEventListener("pagehide", () => {
disposed = true;
generation++;
active = null;
unbind();
window.removeEventListener("eip6963:announceProvider", announced);
}, { once: true });
这段代码只显示经过基本格式检查的连接快照;生产集成还需在本地状态中验证允许的链与部署,并将余额、表单和预览绑定到同一账户/网络版本。事件到来后示例会使旧快照失效,不自动重新弹连接或执行资金动作。生产页面可在失效后重读非弹窗状态,但必须保留同样的过期结果保护。
事件与失效处理
按 EIP-1193 处理 provider 事件,并在替换 provider 或组件卸载时移除原监听器:
| 事件 | 页面处理 |
|---|---|
accountsChanged | 账户可见列表改变;空数组按无授权账户处理。清除旧账户的余额、收款目标与未签预览,再核对当前状态 |
chainChanged | 链号改变;作废旧链上的估值、请求与确认。核对新链是否受当前功能支持,不继续执行旧交易草稿 |
disconnect | provider 连接不可用;清除可操作状态,提示核对网络,不把它当作链上退款或撤销 |
connect(若收到) | 仅表示 provider 链连接恢复;仍需读取账户授权,不当作用户登录或签名授权 |
账户事件不等于允许网站选择任意账户;网络事件也不是网页自动切链或添加网络能力的保证。多标签环境下只更新对应 provider 与页面的状态,不能将另一标签的确认结果写入当前标签。
拒绝、取消与失败
| 结果 | 应如何处理 |
|---|---|
4001 | 常见拒绝/取消结果;保留可重试入口,但只在用户再次选择时发起,不自动重弹 |
4100 | 账户或请求未授权;核对站点授权和钱包状态,不绕过验证 |
4200 | 方法不支持;停止该方法,不用另一签名方法静默替代 |
4900/4901 | provider 或目标网络不可用;核对连接和当前浏览器网络 |
| 空账户、非预期返回值或未知错误 | 不显示已连接成功,不从本地缓存补造授权;提示核对钱包后再决定下一步 |
这些错误码是标准语义,具体取消路径可能返回其他错误,不能据此推断资金是否变化。拒绝一次新的连接请求也不证明此前授权的会话已经撤销,应另行核对当前账户访问状态。网页的“停止”等本地取消仅使结果失效,不保证关闭钱包授权面板或撤销 RPC;超时同样不是钱包已取消的证明。不要对未知结果自动重试资产请求。
站点断开只清理该连接能力,不撤销链上代币授权。若另一个资金流程已经广播,关闭页面或取消界面不能撤回交易;按交易状态与恢复核对原操作。
接入检查
验证重复发现、用户选择、未授权空账户、拒绝/取消、账户与链变化、旧请求迟到、同 origin 重访及不同 origin 隔离。不要仅凭连接演示通过就宣称支持 eth_sign、结构化签名、自动切链、外部账户签名或所有交易方法;每种方法都需独立的能力与授权核验。私钥、助记词、完整隐私凭证和解锁材料不进入网页日志。