一份代码，怎样变成真正可用的 DApp？

DApp 不是“网页里加一个连接钱包按钮”。它由链上合约与用户界面共同组成； 合约像公开 API，但每次写入都要经过签名、网络传播、区块执行与状态确认。 ^[1]

Solidity 源码是给人读的；EVM 执行字节码；前端依靠 ABI 编码函数调用； 地址只在某一条链的状态空间中定位实例。编译就是把一份人类描述拆成不同消费者需要的产物。 ^[2]

为什么同一个 0x… 不能脱离网络理解？

每条链维护独立世界状态。一个私钥可以在多条 EVM 链上导出同一个 EOA 地址，但该地址的余额、 nonce、合约代码和存储互不相通。前端若只保存地址、不绑定 chainId，就可能把 Sepolia 的 ABI 配到主网地址，或者让用户在错误网络上签名。EIP-155 把 chainId 纳入交易签名，降低跨链重放风险， 但不会替前端检查地址配置。^[3]

LearningCounter 不收 ETH、不调用外部合约，只保留状态、权限、边界、事件与错误。 这让我们能把注意力放在交付链路上，而不是把“能部署”误当成“适合管理真实资产”。

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

contract LearningCounter {
    uint256 public constant MAX_COUNT = 1_000_000;
    uint256 public count;
    address public immutable owner;

    event CountChanged(
        address indexed actor,
        uint256 previous,
        uint256 current
    );

    error ZeroAmount();
    error CountLimitExceeded(
        uint256 current,
        uint256 requested,
        uint256 maximum
    );
    error NotOwner();

    constructor(uint256 initial) {
        if (initial > MAX_COUNT) {
            revert CountLimitExceeded(0, initial, MAX_COUNT);
        }
        owner = msg.sender;
        count = initial;
    }

    function increment() external {
        incrementBy(1);
    }

    function incrementBy(uint256 amount) public {
        if (amount == 0) revert ZeroAmount();
        if (amount > MAX_COUNT - count) {
            revert CountLimitExceeded(count, amount, MAX_COUNT);
        }

        uint256 previous = count;
        count = previous + amount;
        emit CountChanged(msg.sender, previous, count);
    }

    function reset(uint256 next) external {
        if (msg.sender != owner) revert NotOwner();
        if (next > MAX_COUNT) {
            revert CountLimitExceeded(count, next, MAX_COUNT);
        }

        uint256 previous = count;
        count = next;
        emit CountChanged(msg.sender, previous, next);
    }
}

从“函数能跑”升级到“不变量可陈述”

智能合约部署后难以随意替换，测试至少是安全底线。单元、集成、性质测试、静态分析、 人工复核各自看见不同问题；任何一个绿色勾都不能单独证明“没有漏洞”。 ^[4]

最小测试矩阵：每项需求都要有成功与失败证据

# 初始化当前 Hardhat 3 项目并查看模板
npx hardhat --init

# 每次从干净模拟网络运行测试
npx hardhat test

# 启动一个可供脚本和前端共同连接的持久本地节点
npx hardhat node

# 部署到正在运行的本地节点；状态持续到节点停止或重置
npx hardhat ignition deploy ignition/modules/LearningCounter.ts --network localhost

Sepolia 是当前普通合约和应用开发的默认测试网；Hoodi 主要服务协议升级、验证者与质押测试。 测试网 ETH 按设计没有现实价值，不应购买。^[5]

什么时候从本地进入 Sepolia？

当单元、边界与不变量测试稳定，本地前端已能重现完整读写流程，并且你已经能解释每个签名请求时， 才把同一构建产物送入 Sepolia。测试网的目标不是继续“试着改代码”，而是验证真实整合： 网络配置、部署密钥、RPC、钱包、地址、ABI、浏览器兼容、区块等待和错误反馈是否共同工作。

普通转账的 to 指向接收账户；合约创建交易没有普通接收方，输入数据包含 creation bytecode 与构造参数。成功收据会给出新合约地址。^[6]

部署前的四项输入

import { buildModule } from
  "@nomicfoundation/hardhat-ignition/modules";

export default buildModule(
  "LearningCounterModule",
  (m) => {
    const initial = m.getParameter("initial", 7n);
    const counter = m.contract(
      "LearningCounter",
      [initial],
    );
    return { counter };
  },
);

# 先在 Hardhat 模拟网络运行部署计划
npx hardhat ignition deploy ignition/modules/LearningCounter.ts

# 再对正在运行的 localhost 节点部署，供本地前端访问
npx hardhat ignition deploy ignition/modules/LearningCounter.ts --network localhost

# 本地闭环通过后，使用独立测试账户部署到 Sepolia
npx hardhat ignition deploy ignition/modules/LearningCounter.ts --network sepolia

源码验证究竟证明什么？

验证服务会用你提交的源码、编译器、设置、库地址与构造参数重新编译，再把结果与该地址的部署字节码比对。 匹配说明“这份可读源码能够重现链上代码”，方便独立检查；它不是安全审计，更不是业务逻辑正确证明。 ^[7]

只读调用通常通过 eth_call 在节点上模拟执行，不写入区块，也无需用户签名； 写调用必须构造交易、估算 Gas、请求签名、广播并等待收据。 ^[8]

import { BrowserProvider, Contract } from "ethers";
import abi from "./LearningCounter.abi.json";

const SEPOLIA = 11155111n;
const address = deployments[SEPOLIA].LearningCounter;

const provider = new BrowserProvider(window.ethereum);
const network = await provider.getNetwork();
if (network.chainId !== SEPOLIA) {
  throw new Error("请切换到 Sepolia");
}

// READ：Provider 足够，不需要签名。
const readContract = new Contract(address, abi, provider);
const current = await readContract.count();

// WRITE：先显式请求账户，再取得 Signer。
await provider.send("eth_requestAccounts", []);
const signer = await provider.getSigner();
const writeContract = readContract.connect(signer);

const tx = await writeContract.incrementBy(3n);
showPending(tx.hash);

const receipt = await tx.wait();
if (!receipt || receipt.status !== 1) {
  throw new Error("交易已打包，但执行失败");
}

renderCount(await readContract.count());

前端配置必须按网络组织

export const deployments = {
  31337n: {
    name: "Localhost",
    LearningCounter: "0x5FbD…0aa3",
  },
  11155111n: {
    name: "Sepolia",
    LearningCounter: "0x7A93…42F1",
  },
} as const;

事件不是装饰，也不是所有数据的永久数据库

外部账户发送写交易时，Solidity 函数的返回值不会像普通 HTTP 响应那样直接送回前端。 前端通常通过收据中的日志、随后读取的状态或索引服务确认结果。事件适合描述可观察变化， 但合约自身不能像读取 storage 那样读取历史日志；事件字段与索引设计要服务真实查询需求。 ^[9]

一笔写交易可能在钱包阶段被拒绝，在 RPC 阶段广播失败，在 pending 阶段被替换， 被打包后因合约回滚得到失败收据，或成功后继续等待更强确定性。每一步都需要不同文案与恢复动作。

钱包事件也是状态变化

EIP-1193 规定 Provider 的请求接口及 chainChanged、accountsChanged 等事件。 前端不能在首次连接后永远假定网络和账户不变；变化发生时，应重建 Provider/Contract 状态或明确刷新， 并移除旧监听器。用户拒绝请求的标准错误码是 4001，属于预期分支。 ^[11]

链上代码不可轻易更改，因此开发阶段需要更高质量评估；但测试、静态分析、独立审查和形式化方法 都有边界。真正的纵深防御，是让同一错误必须穿过多层独立检查才能造成损失。 ^[12]

最危险的秘密，往往泄露在“只是配置”里

测试网能暴露整合问题，却没有同等资产诱因、流量、对手、费用压力和治理后果。 是否进入主网，应由资产规模、权限强度、升级模型、依赖关系和事件响应能力共同决定。

一份可交接的部署记录至少包含什么？

调试最有效的第一问不是“为什么报错”，而是“请求有没有到达正确链上的正确地址， 使用正确 ABI，以正确账户和参数执行？”沿边界逐层缩小范围，比反复重试更可靠。

为什么“错误信息为空”不等于合约没有回滚原因？

回滚数据可能在 RPC、钱包或库的不同层级被包装、裁剪或无法解码。若前端 ABI 缺少对应 custom error， 即使合约返回了结构化错误，库也可能只能显示原始数据。因此发布时应让 ABI 与部署字节码同源， 并在本地测试里覆盖每种预期错误，确认前端能把它转换成对用户有意义的解释。

ABI

Application Binary Interface；描述函数、参数、返回值、事件与错误如何编码和解码。

creation bytecode

创建交易中执行的初始化代码，结合构造参数生成最终 runtime bytecode 与初始存储。

runtime bytecode

部署成功后保存在合约地址、由后续调用实际执行的 EVM 字节码。

artifact

编译器或框架生成的构建产物，通常包含 ABI、字节码、metadata 与调试信息。

chainId

链的身份编号；用于网络配置，并进入现代签名交易的重放保护。

Provider

读取区块链状态、发送 RPC 请求、广播交易并观察网络的连接抽象；不必拥有私钥。

Signer

代表某账户授权并签署消息或交易的抽象；浏览器中通常由钱包控制。

eth_call

在指定区块状态上模拟消息调用，不创建链上交易，常用于读取和写交易预检。

receipt

交易被区块包含后的执行收据，包含 status、Gas 使用、日志与创建合约地址等信息。

confirmation

包含交易的区块之后又出现的区块数量；是应用等待策略，不等同于 PoS 协议 finality。

source verification

用给定源码和设置重编译并与部署字节码比对，不等于安全审计或形式化验证。

invariant

在所有允许状态与调用序列中都应成立的性质，例如 count 永不超过 MAX_COUNT。