在 MAGNE 測試網上開發 DApp

為開發者提供的指南，說明如何使用 Ethers.js 在 MAGNE L1 及 M Hash L2 測試網上開發去中心化應用程式。

1 概覽

僅限測試網 — 本指南僅適用於測試網 DApp 開發。MAGNE L1 測試網及 M Hash L2 測試網為 EVM 相容環境。測試網代幣不具貨幣價值。網路參數可能隨測試進展而變動。

  • 支援標準以太坊開發工具及函式庫
  • 支援 Ethers.js、Wagmi、Viem 及其他 Web3 函式庫
  • 相容於 MetaMask、WalletConnect 及其他錢包
  • 可使用 React、Vue 或原生 JavaScript 建置前端 UI

DApp 架構

前端 UI

使用 React、Vue 或原生 HTML/JS 建置使用者介面

錢包連接

MetaMask、WalletConnect 或其他 Web3 錢包

RPC 提供者

使用 Ethers.js 或 viem 與區塊鏈互動

智慧合約

您在測試網上部署的合約

交易追蹤

透過區塊瀏覽器追蹤確認狀態

網路常數

JavaScript 設定

export const MAGNE_L1_TESTNET = {
  chainId: '0x' + (20250810).toString(16),
  chainName: "MAGNE L1 Testnet",
  nativeCurrency: {
    name: "MHA",
    symbol: "MHA",
    decimals: 18
  },
  rpcUrls: ["https://rpc.testnet.magicalhash.com"],
  blockExplorerUrls: ["https://explorer.testnet.magicalhash.com"]
};

export const M_HASH_L2_TESTNET = {
  chainId: '0x' + (20250827).toString(16),
  chainName: "M Hash L2 Testnet",
  nativeCurrency: {
    name: "MHA",
    symbol: "MHA",
    decimals: 18
  },
  rpcUrls: ["https://l2-rpc.testnet.magicalhash.com"],
  blockExplorerUrls: ["https://l2-explorer.testnet.magicalhash.com"]
};

錢包連接範例

請求帳戶存取權

import { ethers } from 'ethers';

const provider = new ethers.BrowserProvider(window.ethereum);

async function connectWallet() {
  try {
    const accounts = await provider.send("eth_requestAccounts", []);
    console.log("Connected:", accounts[0]);
    return accounts[0];
  } catch (error) {
    console.error("Connection rejected:", error.message);
  }
}

切換網路

async function switchToL1() {
  try {
    await window.ethereum.request({
      method: 'wallet_switchEthereumChain',
      params: [{ chainId: '0x' + (20250810).toString(16) }],
    });
  } catch (switchError) {
    console.error("Switch failed:", switchError.message);
  }
}

async function addNetwork() {
  try {
    await window.ethereum.request({
      method: 'wallet_addEthereumChain',
      params: [MAGNE_L1_TESTNET],
    });
  } catch (addError) {
    console.error("Add network failed:", addError.message);
  }
}

提示：請先呼叫 switchToL1。若因找不到網路而失敗，請呼叫 addNetwork 將網路新增至錢包。

讀取合約範例

import { ethers } from 'ethers';

const CONTRACT_ADDRESS = "your_deployed_contract_address";
const ABI = [
  "function message() view returns (string)",
  "function setMessage(string newMessage)"
];

async function readContract() {
  const provider = new ethers.BrowserProvider(window.ethereum);
  const signer = await provider.getSigner();
  const contract = new ethers.Contract(CONTRACT_ADDRESS, ABI, signer);

  try {
    const message = await contract.message();
    console.log("Current message:", message);
    return message;
  } catch (error) {
    console.error("Read failed:", error.message);
  }
}

寫入合約範例

async function writeContract(newMessage) {
  const provider = new ethers.BrowserProvider(window.ethereum);
  const signer = await provider.getSigner();
  const contract = new ethers.Contract(CONTRACT_ADDRESS, ABI, signer);

  try {
    const tx = await contract.setMessage(newMessage);
    console.log("Transaction sent:", tx.hash);

    // 等待確認
    const receipt = await tx.wait();
    console.log("Confirmed:", receipt.hash);

    return receipt;
  } catch (error) {
    if (error.message.includes("user rejected")) {
      console.log("Transaction rejected by user");
    } else {
      console.error("Transaction failed:", error.message);
    }
  }
}

使用者流程：呼叫寫入函數時，錢包會提示使用者審查並核准交易。若使用者不認同該操作，可以拒絕。

交易追蹤

追蹤交易狀態

function getExplorerUrl(chainId, txHash) {
  const explorers = {
    20250810: "https://explorer.testnet.magicalhash.com",
    20250827: "https://l2-explorer.testnet.magicalhash.com"
  };
  return `${explorers[chainId]}/tx/${txHash}`;
}

async function trackTransaction(tx) {
  console.log(`View on explorer: ${getExplorerUrl(20250810, tx.hash)}`);

  // 等待 1 次確認
  const receipt = await tx.wait(1);
  if (receipt.status === 1) {
    console.log("Transaction successful!");
  } else {
    console.log("Transaction failed!");
  }
}

UI / UX 注意事項

  • 顯示網路名稱 — 在 UI 中顯示目前網路（MAGNE L1 或 M Hash L2），讓使用者知道所在位置
  • 顯示測試網警告 — 清楚顯示橫幅提示目前為測試網環境
  • 顯示交易狀態 — 呈現待處理、已確認或失敗等狀態
  • 提供瀏覽器連結 — 提供區塊瀏覽器上交易及合約頁面的連結
  • 優雅處理錢包拒絕 — 當使用者拒絕交易時，應妥善處理
  • 處理網路不符 — 提示使用者切換至正確的網路
  • 顯示 Gas 估算 — 在確認前顯示預估交易費用

安全注意事項

⚠️ 安全要求

請勿向使用者要求助記詞或私鑰。正規的 DApp 無需這些憑證。

請勿將私鑰儲存在前端程式碼、localStorage 或 cookies 中。

請使用專用測試錢包進行所有測試網開發。

測試網代幣不具貨幣價值。

智慧合約及 DApp 範例僅供測試及教育用途。在正式環境使用前，請務必審計程式碼。

疑難排解

錢包未偵測到

請確認使用者已安裝 Web3 錢包（如 MetaMask、Rabby 等）。請檢查 window.ethereum 是否可用。

選錯網路

請使用正確的 chainId 呼叫 wallet_switchEthereumChain。若網路錯誤，請向使用者顯示提示以切換網路。

使用者拒絕請求

請妥善處理拒絕情況。可透過 error.message.includes("user rejected") 來識別此情況。

RPC 逾時

請檢查您的網路連線。請嘗試重新整理頁面。若持續發生，RPC 可能正在維護中。

找不到合約地址

請確認合約已部署至正確的網路。請檢查錢包中連接的網路是否符合預期。

交易待處理

請在區塊瀏覽器中查看待處理狀態。L2 交易通常比 L1 更快確認。

Gas 估算失敗

這通常表示交易可能會失敗。請檢查合約狀態、參數及錢包餘額。

開發者資源

開發者文件 連接錢包 部署合約 網路狀態