快速上手
本指南將帶你建立一個附有 連線錢包 按鈕的網頁來讀取使用者的 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) { // 串接你使用的 QR Code 函式庫(例如 qrcode.toCanvas)渲染 qrUri。 // 切勿在正式環境將配對 URI 寫入日誌或回報分析平台。 container.textContent = "請使用 QR Code 函式庫渲染 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,在桌面瀏覽器開啟頁面並點擊 連線錢包。 - 使用任意 QR Code 函式庫(如
qrcode)將qrUri渲染為 QR Code 並以 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;當使用者關閉 QR Code 視窗或主動取消時,請呼叫 showPairing 收到的 cancel 回呼函式。
驗證: 頁面正常顯示 SS58 位址。若顯示 未偵測到 D9 錢包內建提供者,代表目前未運行於 D9 錢包內建瀏覽器中,請改用 WalletConnect 通道。
- 工作階段生命週期:監聽帳戶切換與中斷連線
- 訊息簽署
- 交易與最終確認
- 登入認證 (SIWX)
