快速上手
本指南将带你创建一个带 连接钱包 按钮的网页以读取用户的 D9 账户。该方案同时兼容 D9 钱包内置浏览器以及通过 WalletConnect 访问的桌面端与移动端浏览器。
前置条件: 本地已安装 Node.js 与 npm,手机端已安装 D9 钱包。
1. 创建项目
Section titled “1. 创建项目”npm create vite@latest my-d9-dapp -- --template vanilla-tscd my-d9-dappnpm installnpm install --save-exact @d9-network/dapp-connector@0.2.0 effect@4.0.52. 配置环境变量
Section titled “2. 配置环境变量”新建 .env.local,填入主网端点中的主网配置:
VITE_D9_RPC_URL=wss://rpc-hermes.d9network.comVITE_D9_GENESIS_HASH=0xc3140da27f348abd94a638e9ca7ee7e9005caf5f2b451044c9487905ea5e0991VITE_D9_RELAY_URL=wss://relay.d9network.comVITE_D9_PROJECT_ID=d9-wallet-publicVITE_D9_WALLET_SCHEME=d9wallet新建 src/config.ts 读取并校验这些变量:
function required(name: string): string { const value = import.meta.env[name]?.trim(); if (!value) throw new Error(`缺少环境变量: ${name}`); return value;}
export const d9Config = { rpcUrl: required("VITE_D9_RPC_URL"), expectedGenesisHash: required("VITE_D9_GENESIS_HASH"), relayUrl: required("VITE_D9_RELAY_URL"), projectId: required("VITE_D9_PROJECT_ID"), walletScheme: required("VITE_D9_WALLET_SCHEME"),};3. 创建钱包运行时
Section titled “3. 创建钱包运行时”新建 src/wallet.ts。在应用根部初始化一次并在其他模块中复用:
import { ManagedRuntime } from "effect";import { D9DAppConnector } from "@d9-network/dapp-connector";import { d9Config } from "./config";
export const walletLayer = D9DAppConnector.layer({ dappName: "My D9 DApp", walletConnect: { projectId: d9Config.projectId, relayUrl: d9Config.relayUrl, metadata: { name: "My D9 DApp", description: "My D9 decentralized application", url: window.location.origin, icons: [`${window.location.origin}/icon.png`], }, },});
export const walletRuntime = ManagedRuntime.make(walletLayer);4. 编写连接函数
Section titled “4. 编写连接函数”新建 src/connect.ts。transport: "auto" 会在检测到内置钱包时优先走注入通道,否则自动切换为 WalletConnect:
import { Effect } from "effect";import { D9DAppConnector } from "@d9-network/dapp-connector";import { buildD9WalletConnectAppLink } from "@d9-network/dapp-connector/protocol";import { d9Config } from "./config";import { walletRuntime } from "./wallet";
export async function connectWallet( showPairing: (qrUri: string, deepLink: string, cancel: () => Promise<void>) => void,) { return walletRuntime.runPromise( Effect.gen(function* () { const connector = yield* D9DAppConnector; const start = yield* connector.connect({ transport: "auto", requiredMethods: ["d9_signMessage", "d9_signTransaction"], });
if (start.transport === "walletconnect") { if (start.uri) { const deepLink = buildD9WalletConnectAppLink(start.uri, d9Config.walletScheme); showPairing(start.uri, deepLink, () => walletRuntime.runPromise(start.cancel)); } yield* start.approval; }
return yield* connector.getAccounts; }), );}5. 绑定到界面按钮
Section titled “5. 绑定到界面按钮”替换 src/main.ts。请仅在用户点击事件中调用 connectWallet,浏览器与移动钱包均要求由明确的用户交互触发唤起。
import { connectWallet } from "./connect";
const app = document.querySelector<HTMLDivElement>("#app")!;const button = document.createElement("button");const status = document.createElement("p");const qrContainer = document.createElement("div");button.textContent = "连接钱包";app.replaceChildren(button, status, qrContainer);
function renderPairingQr(qrUri: string, container: HTMLElement) { // 接入你使用的二维码库(例如 qrcode.toCanvas)渲染 qrUri。 // 切勿在生产环境将配对 URI 输出至日志或上报分析平台。 container.textContent = "请使用二维码库渲染 WalletConnect 配对码"; void qrUri;}
button.addEventListener("click", async () => { try { const accounts = await connectWallet((qrUri, deepLink, cancel) => { renderPairingQr(qrUri, qrContainer); const link = document.createElement("a"); link.href = deepLink; link.textContent = "打开 D9 钱包"; const cancelBtn = document.createElement("button"); cancelBtn.textContent = "取消"; cancelBtn.onclick = () => void cancel(); status.replaceChildren(link, " ", cancelBtn); }); qrContainer.replaceChildren(); status.textContent = accounts.map((account) => account.address).join(", "); } catch (error) { qrContainer.replaceChildren(); status.textContent = String(error); }});- 运行
npm run dev,在桌面浏览器打开页面并点击 连接钱包。 - 使用任意二维码库(如
qrcode)将qrUri渲染为二维码并用 D9 钱包扫码(切勿将配对 URI 写入日志或分析平台)。 - 在钱包中确认授权,页面即会显示已授权的 SS58 地址。
在手机浏览器中可直接点击 打开 D9 钱包 唤起应用;在 D9 钱包内置浏览器中则会直接弹出授权确认。如遇异常,请查阅问题排查。
指定单一连接通道
Section titled “指定单一连接通道”如果不希望使用 transport: "auto",可将 src/connect.ts 中 Effect.gen 的函数体替换为以下任一实现。
仅使用内置浏览器(注入式 PAPI):
const connector = yield* D9DAppConnector;const isAvailable = yield* connector.papi.isAvailable;if (!isAvailable) { throw new Error("未检测到 D9 钱包内置提供者");}yield* connector.papi.connect();return yield* connector.getAccounts;仅使用 WalletConnect(外部浏览器):
const connector = yield* D9DAppConnector;const start = yield* connector.walletConnect.connect({ requiredMethods: ["d9_signMessage", "d9_signTransaction"],});if (start.uri) { const deepLink = buildD9WalletConnectAppLink(start.uri, d9Config.walletScheme); showPairing(start.uri, deepLink, () => walletRuntime.runPromise(start.cancel));}yield* start.approval;return yield* connector.getAccounts;当用户关闭二维码弹窗或主动取消时,请调用 showPairing 接收到的 cancel 回调。
验证: 页面正常显示 SS58 地址。若提示 未检测到 D9 钱包内置提供者,说明当前未运行在 D9 钱包内置浏览器中,请改用 WalletConnect 通道。
- 会话生命周期:监听账户切换与断开连接
- 消息签名
- 交易与最终确认
- 登录认证 (SIWX)
