跳转到内容

快速上手

本指南将带你创建一个带 连接钱包 按钮的网页以读取用户的 D9 账户。该方案同时兼容 D9 钱包内置浏览器以及通过 WalletConnect 访问的桌面端与移动端浏览器。

前置条件: 本地已安装 Node.js 与 npm,手机端已安装 D9 钱包。

终端窗口
npm create vite@latest my-d9-dapp -- --template vanilla-ts
cd my-d9-dapp
npm install
npm install --save-exact @d9-network/dapp-connector@0.2.0 effect@4.0.5

新建 .env.local,填入主网端点中的主网配置:

终端窗口
VITE_D9_RPC_URL=wss://rpc-hermes.d9network.com
VITE_D9_GENESIS_HASH=0xc3140da27f348abd94a638e9ca7ee7e9005caf5f2b451044c9487905ea5e0991
VITE_D9_RELAY_URL=wss://relay.d9network.com
VITE_D9_PROJECT_ID=d9-wallet-public
VITE_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"),
};

新建 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);

新建 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;
}),
);
}

替换 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);
}
});
  1. 运行 npm run dev,在桌面浏览器打开页面并点击 连接钱包。
  2. 使用任意二维码库(如 qrcode)将 qrUri 渲染为二维码并用 D9 钱包扫码(切勿将配对 URI 写入日志或分析平台)。
  3. 在钱包中确认授权,页面即会显示已授权的 SS58 地址。

在手机浏览器中可直接点击 打开 D9 钱包 唤起应用;在 D9 钱包内置浏览器中则会直接弹出授权确认。如遇异常,请查阅问题排查。

如果不希望使用 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 通道。