Web3 中级实战：基于智能合约与钱包登录构建可落地的去中心化会员积分系统

很多团队第一次做 Web3 会员体系时，都会想得很“纯”：用户连钱包、积分上链、所有逻辑都写进合约。但真做起来，问题马上就来了：

钱包地址是身份，但不是完整用户画像
所有积分变动都上链，Gas 成本很快失控
风控、活动规则、等级计算放到链上，升级困难
钱包登录看似简单，签名、防重放、会话绑定一不小心就出漏洞
业务方想要“可运营、可统计、可审计”，而不是只有一份链上余额

所以这篇文章我换一个更工程化的角度来讲：不是怎么“写一个积分合约”，而是怎么构建一个真正能落地的去中心化会员积分系统。

我们会围绕一套常见架构来展开：

钱包签名登录：用户用钱包证明身份
后端业务服务：处理活动、积分发放、风控、幂等
智能合约记账：作为可信积分账本或核心状态结算层
前端 DApp：展示会员等级、积分流水、权益领取

这套方式不是最“极客”的，但通常是最接近业务落地的。

背景与问题

传统会员系统的核心是三件事：

身份识别
积分累积与消耗
权益发放与等级管理

到了 Web3，这三件事会发生一些变化。

1. 身份不再是手机号，而是钱包地址

钱包地址天然适合做去中心化身份入口，但它有两个问题：

一个用户可能有多个钱包
钱包只能证明“我控制这个地址”，不能自动证明“我是某个业务用户”

所以实际系统里，往往会采用：

钱包地址作为主身份凭证
可选绑定邮箱/手机号/社交账号，作为辅助恢复与运营字段

2. 积分到底要不要全上链？

很多人卡在这里。我的建议很明确：

高价值、需要公开审计、需要跨应用流通的积分状态：上链
高频、低价值、复杂运营逻辑的积分计算过程：放后端

也就是说，链上做结算与可信记录，链下做计算与编排。

3. 会员系统不是“余额系统”那么简单

一个能用的会员积分系统，至少还要考虑：

发积分：购买、签到、邀请、完成任务
扣积分：兑换权益、核销商品
会员等级：Bronze / Silver / Gold / VIP
幂等控制：同一个订单不能重复加积分
风控：刷任务、批量钱包、机器人
审计：谁在什么时候因为什么规则得到多少积分

这就决定了：仅靠合约不够，必须有完整架构设计。

方案目标与架构边界

先明确这篇文章要实现的目标：

用户使用 MetaMask 等钱包登录
服务端校验签名，生成会话
管理员/业务服务基于业务事件为用户发积分
积分余额与关键流水记录在链上
前端可查询积分余额与会员等级
保留可升级、可运营、可审计的能力

不追求的目标

为了让方案能真正落地，我们先明确边界：

不做复杂 DAO 治理
不做跨链积分桥
不把所有运营规则都写进合约
不实现完整商城兑换系统，只保留扣积分接口

总体架构设计

先看整体分层。

flowchart LR
    U[用户钱包] --> F[前端 DApp]
    F -->|签名登录| B[业务后端 API]
    B -->|校验签名/生成会话| DB[(用户与活动数据库)]
    B -->|发积分/扣积分| S[积分服务]
    S -->|写链上交易| C[积分智能合约]
    F -->|读取余额/等级| C
    F -->|读取活动与流水| B

这个结构里有一个关键点：

登录走钱包签名，业务走后端编排，可信状态落到智能合约。

这样设计的好处是：

登录是去中心化的，不依赖密码
核心积分状态可审计
复杂业务规则可以灵活迭代
可以通过后端做幂等、风控、限流和审计

方案对比与取舍分析

方案 A：纯链上积分系统

所有发积分、扣积分、等级计算都写在智能合约。

优点：

透明、可审计
不依赖中心化后端计算

缺点：

成本高
升级难
规则复杂时开发和测试都很重
很多业务条件（订单支付状态、活动风控）本身就来自链下

适合：

小而简单的链上积分实验项目
强调完全公开规则的社区治理场景

方案 B：纯链下积分系统 + 钱包登录

钱包只做登录，积分全存在数据库。

优点：

开发快
成本低
易于做复杂运营规则

缺点：

积分状态不透明
用户无法独立验证
迁移与跨应用扩展弱

适合：

Web2 向 Web3 过渡期项目
对链上可信要求不高的业务

方案 C：链下规则 + 链上结算账本

这就是本文主推方案。

优点：

成本与可信性比较平衡
后端可灵活处理业务规则
链上保留关键积分余额与流水事件
便于接入更多钱包与前端应用

缺点：

系统组件更多
需要处理后端签名、权限、幂等等工程问题

适合：

真实商业项目
有运营动作、活动中心、积分兑换的产品

核心原理

这一节把系统跑起来所依赖的几个关键机制讲清楚。

1. 钱包登录原理：签名而不是密码

钱包登录并不是“把钱包地址发给后端”就结束了，而是一个挑战-响应流程：

前端向后端申请一个 nonce
后端返回一段待签名消息
用户用钱包签名
前端把签名结果传回后端
后端恢复签名地址，校验是否匹配
校验通过后，后端签发 session / JWT

用时序图看更清楚：

sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant B as 后端
    participant W as 钱包

    U->>F: 点击钱包登录
    F->>B: 请求 nonce
    B-->>F: 返回待签名消息
    F->>W: 调用 signMessage
    W-->>F: 返回签名
    F->>B: 提交 address + signature
    B->>B: 恢复签名地址并校验 nonce
    B-->>F: 返回 JWT/Session

为什么一定要 nonce？

因为没有 nonce，就会有重放攻击：

攻击者截获一次旧签名
重复提交旧签名
后端如果只看“签名是否有效”，就会把旧签名当作新的登录凭证

所以正确做法是：

nonce 一次性使用
设置过期时间
登录成功后立即失效

2. 链上积分账本原理

在链上，积分系统本质上是一个受控记账合约。常见设计有三种：

mapping(address => uint256) 记录余额
通过事件记录积分变动明细
使用角色权限控制谁能发积分和扣积分

这里不直接把积分做成标准 ERC20，有几个现实原因：

很多会员积分不希望自由转账
业务更关心的是“会员权益”而不是“代币流通”
可以避免积分被二级市场交易引发监管与业务偏离

因此，更适合的是一个不可自由转让的受控积分合约。

3. 会员等级计算原理

等级通常有两种模式：

模式 A：实时链上判断

比如：

100 分以上是 Silver
500 分以上是 Gold

前端读取余额后本地判断，简单直接。

模式 B：链下定期计算 + 链上固化等级

适合更复杂的情况：

最近 90 天活跃度
消费金额折算
多任务权重
限时活动加成

这时建议：

链下计算等级
将最终等级写入链上或数据库
前端统一读取

对于中级实战项目，我更建议：

余额上链
等级先链下计算
等规则稳定后，再决定是否把等级也固化到链上

容量估算与设计建议

中级项目最容易忽略的是：不是能跑就行，还要估算规模。

假设：

10 万用户
日活 5000
每日积分变动 2 万次
每次变动都链上写入

如果在主网，这个成本通常不可接受。更现实的方式是：

智能合约设计

下面给出一个可运行的最小版积分合约。它具备这些能力：

记录积分余额
管理员发积分
管理员扣积分
发出积分变更事件
支持角色权限控制

使用 OpenZeppelin 的 AccessControl。

Solidity 合约

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

import "@openzeppelin/contracts/access/AccessControl.sol";

contract MembershipPoints is AccessControl {
    bytes32 public constant OPERATOR_ROLE = keccak256("OPERATOR_ROLE");

    mapping(address => uint256) private _balances;

    event PointsIssued(
        address indexed to,
        uint256 amount,
        bytes32 indexed bizId,
        string reason
    );

    event PointsSpent(
        address indexed from,
        uint256 amount,
        bytes32 indexed bizId,
        string reason
    );

    constructor(address admin) {
        _grantRole(DEFAULT_ADMIN_ROLE, admin);
        _grantRole(OPERATOR_ROLE, admin);
    }

    function balanceOf(address user) external view returns (uint256) {
        return _balances[user];
    }

    function issuePoints(
        address to,
        uint256 amount,
        bytes32 bizId,
        string calldata reason
    ) external onlyRole(OPERATOR_ROLE) {
        require(to != address(0), "invalid address");
        require(amount > 0, "amount must > 0");

        _balances[to] += amount;
        emit PointsIssued(to, amount, bizId, reason);
    }

    function spendPoints(
        address from,
        uint256 amount,
        bytes32 bizId,
        string calldata reason
    ) external onlyRole(OPERATOR_ROLE) {
        require(from != address(0), "invalid address");
        require(amount > 0, "amount must > 0");
        require(_balances[from] >= amount, "insufficient points");

        _balances[from] -= amount;
        emit PointsSpent(from, amount, bizId, reason);
    }
}

设计说明

这里我有意保持合约简单，因为会员积分系统的复杂度，往往不在余额本身，而在：

权限谁来控制
业务事件如何映射为积分规则
如何防止重复发放
链下和链上如何对账

注意一点：bizId 很重要。它用来关联链下业务事件，例如：

订单号 hash
签到记录 ID hash
活动任务 ID hash

虽然合约本身没有防重逻辑，但通过事件和链下数据库，你可以完成审计和去重。

实战代码（可运行）

这一部分我们做一个最小可运行示例，包括：

Hardhat 合约部署
Node.js 后端实现钱包登录
前端调用钱包签名
后端调用合约发积分

一、项目结构

web3-membership/
├─ contracts/
│  └─ MembershipPoints.sol
├─ scripts/
│  └─ deploy.js
├─ server/
│  └─ app.js
├─ frontend/
│  └─ index.html
├─ hardhat.config.js
├─ package.json

二、安装依赖

npm init -y
npm install --save-dev hardhat @nomicfoundation/hardhat-toolbox
npm install express cors jsonwebtoken ethers dotenv
npm install @openzeppelin/contracts

初始化 Hardhat：

npx hardhat

选择一个基础 JavaScript 项目即可。

三、Hardhat 配置

require("@nomicfoundation/hardhat-toolbox");
require("dotenv").config();

module.exports = {
  solidity: "0.8.20",
  networks: {
    hardhat: {},
    sepolia: {
      url: process.env.RPC_URL || "",
      accounts: process.env.PRIVATE_KEY ? [process.env.PRIVATE_KEY] : [],
    },
  },
};

四、部署脚本

const hre = require("hardhat");

async function main() {
  const [deployer] = await hre.ethers.getSigners();

  const MembershipPoints = await hre.ethers.getContractFactory("MembershipPoints");
  const contract = await MembershipPoints.deploy(deployer.address);

  await contract.waitForDeployment();
  const address = await contract.getAddress();

  console.log("MembershipPoints deployed to:", address);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

执行部署：

npx hardhat run scripts/deploy.js --network hardhat

如果部署到测试网：

npx hardhat run scripts/deploy.js --network sepolia

五、后端：钱包登录与发积分接口

这个后端示例做三件事：

获取登录 nonce
校验签名并返回 JWT
使用服务端钱包调用合约发积分

require("dotenv").config();
const express = require("express");
const cors = require("cors");
const jwt = require("jsonwebtoken");
const { ethers } = require("ethers");

const app = express();
app.use(cors());
app.use(express.json());

const JWT_SECRET = process.env.JWT_SECRET || "dev-secret";
const RPC_URL = process.env.RPC_URL || "http://127.0.0.1:8545";
const PRIVATE_KEY = process.env.PRIVATE_KEY || "";
const CONTRACT_ADDRESS = process.env.CONTRACT_ADDRESS || "";

const provider = new ethers.JsonRpcProvider(RPC_URL);
const signer = new ethers.Wallet(PRIVATE_KEY, provider);

const abi = [
  "function issuePoints(address to,uint256 amount,bytes32 bizId,string reason) external",
  "function balanceOf(address user) external view returns (uint256)"
];
const contract = new ethers.Contract(CONTRACT_ADDRESS, abi, signer);

// 演示用内存存储，生产环境请改数据库/Redis
const nonces = new Map();

app.get("/auth/nonce", (req, res) => {
  const address = (req.query.address || "").toLowerCase();
  if (!ethers.isAddress(address)) {
    return res.status(400).json({ error: "invalid address" });
  }

  const nonce = `${Date.now()}-${Math.random()}`;
  const message = `欢迎登录会员积分系统\n地址: ${address}\nNonce: ${nonce}`;
  nonces.set(address, { nonce, message, createdAt: Date.now() });

  res.json({ message });
});

app.post("/auth/verify", async (req, res) => {
  try {
    const { address, signature } = req.body;
    const lowerAddress = (address || "").toLowerCase();

    if (!ethers.isAddress(lowerAddress)) {
      return res.status(400).json({ error: "invalid address" });
    }

    const record = nonces.get(lowerAddress);
    if (!record) {
      return res.status(400).json({ error: "nonce not found" });
    }

    if (Date.now() - record.createdAt > 5 * 60 * 1000) {
      nonces.delete(lowerAddress);
      return res.status(400).json({ error: "nonce expired" });
    }

    const recovered = ethers.verifyMessage(record.message, signature).toLowerCase();
    if (recovered !== lowerAddress) {
      return res.status(401).json({ error: "invalid signature" });
    }

    nonces.delete(lowerAddress);

    const token = jwt.sign({ address: lowerAddress }, JWT_SECRET, { expiresIn: "2h" });
    res.json({ token });
  } catch (err) {
    console.error(err);
    res.status(500).json({ error: "verify failed" });
  }
});

function authMiddleware(req, res, next) {
  const auth = req.headers.authorization || "";
  const token = auth.replace("Bearer ", "");
  try {
    const payload = jwt.verify(token, JWT_SECRET);
    req.user = payload;
    next();
  } catch (e) {
    res.status(401).json({ error: "unauthorized" });
  }
}

app.post("/points/issue", authMiddleware, async (req, res) => {
  try {
    const { to, amount, bizId, reason } = req.body;

    if (!ethers.isAddress(to)) {
      return res.status(400).json({ error: "invalid to address" });
    }

    const parsedAmount = BigInt(amount);
    const bytes32BizId = ethers.id(bizId);

    const tx = await contract.issuePoints(to, parsedAmount, bytes32BizId, reason || "manual issue");
    const receipt = await tx.wait();

    res.json({
      success: true,
      txHash: receipt.hash
    });
  } catch (err) {
    console.error(err);
    res.status(500).json({ error: "issue points failed" });
  }
});

app.get("/points/:address", async (req, res) => {
  try {
    const address = req.params.address;
    if (!ethers.isAddress(address)) {
      return res.status(400).json({ error: "invalid address" });
    }

    const balance = await contract.balanceOf(address);
    res.json({ address, balance: balance.toString() });
  } catch (err) {
    console.error(err);
    res.status(500).json({ error: "query failed" });
  }
});

app.listen(3001, () => {
  console.log("server listening on http://localhost:3001");
});

`.env` 示例

RPC_URL=http://127.0.0.1:8545
PRIVATE_KEY=你的部署钱包私钥
CONTRACT_ADDRESS=部署后的合约地址
JWT_SECRET=replace-this-secret

启动后端：

node server/app.js

六、前端：MetaMask 登录与查询积分

下面是一个最小 HTML 页面，可以直接运行。

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8" />
  <title>会员积分系统</title>
</head>
<body>
  <h2>Web3 会员积分系统 Demo</h2>
  <button id="connectBtn">连接钱包并登录</button>
  <button id="queryBtn">查询积分</button>
  <pre id="output"></pre>

  <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/ethers.umd.min.js"></script>
  <script>
    const output = document.getElementById("output");
    let currentAddress = "";
    let token = "";

    function log(msg) {
      output.textContent += msg + "\n";
    }

    document.getElementById("connectBtn").onclick = async () => {
      if (!window.ethereum) {
        alert("请安装 MetaMask");
        return;
      }

      const provider = new ethers.BrowserProvider(window.ethereum);
      const signer = await provider.getSigner();
      currentAddress = await signer.getAddress();

      log("当前地址: " + currentAddress);

      const nonceResp = await fetch(`http://localhost:3001/auth/nonce?address=${currentAddress}`);
      const { message } = await nonceResp.json();

      const signature = await signer.signMessage(message);

      const verifyResp = await fetch("http://localhost:3001/auth/verify", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          address: currentAddress,
          signature
        })
      });

      const verifyData = await verifyResp.json();
      token = verifyData.token || "";

      if (token) {
        log("登录成功，拿到 JWT");
      } else {
        log("登录失败: " + JSON.stringify(verifyData));
      }
    };

    document.getElementById("queryBtn").onclick = async () => {
      if (!currentAddress) {
        alert("请先登录");
        return;
      }

      const resp = await fetch(`http://localhost:3001/points/${currentAddress}`);
      const data = await resp.json();
      log("积分余额: " + JSON.stringify(data));
    };
  </script>
</body>
</html>

到这里，最小闭环已经有了：

钱包登录
后端验签
查询链上积分

七、调用发积分接口

可以用 curl 或 Postman 测试。

curl -X POST http://localhost:3001/points/issue \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer 你的JWT" \
  -d '{
    "to":"0x你的钱包地址",
    "amount":"100",
    "bizId":"order-10001",
    "reason":"首单奖励"
  }'

调用成功后，再查询积分余额即可看到变化。

积分发放业务流设计

实际项目中，发积分一般不是手工调用接口，而是来自业务事件。

flowchart TD
    A[用户完成业务行为] --> B[业务系统产生事件]
    B --> C[积分规则引擎]
    C --> D{是否满足发放条件}
    D -- 否 --> E[记录不发放原因]
    D -- 是 --> F[生成业务幂等ID]
    F --> G[写入积分任务表]
    G --> H[链上发积分]
    H --> I[记录交易哈希与状态]
    I --> J[前端展示余额与流水]

这里的关键工程点有两个：

1. 幂等 ID

例如：

订单奖励：order:{orderId}
邀请奖励：invite:{inviteUserId}:{taskId}
签到奖励：checkin:{user}:{date}

这样即使消息重复消费，也不会重复发积分。

2. 任务状态机

积分发放任务建议至少有这些状态：

PENDING
SUBMITTED
CONFIRMED
FAILED

如果不做状态机，线上排查会非常痛苦。这个坑我自己踩过：交易发出去了，但数据库还停在“处理中”，结果运营以为没发成功，手工补发一次，直接重复奖励。

常见坑与排查

下面这些问题非常常见，而且很多不是“代码不会写”，而是“系统边界没想清楚”。

1. 钱包签名成功，但后端验签失败

可能原因

前后端签名消息内容不一致
地址大小写处理不一致
使用了 signTypedData，后端却按 verifyMessage 校验
nonce 已过期或已被消费

排查方式

先把以下内容都打印出来：

console.log({
  address,
  message: record.message,
  signature,
  recovered: ethers.verifyMessage(record.message, signature)
});

建议

登录场景统一使用 signMessage
前后端消息模板固定，不要前端本地拼接
nonce 必须由服务端生成

2. 调用发积分接口时报权限错误

如果合约报 AccessControl 相关错误，通常说明：

服务端使用的私钥地址不是 OPERATOR_ROLE
部署后没有给对应地址授权

如果需要额外授权，可以在合约中调用 grantRole，或者部署时传入正确 admin 地址。

3. 查询余额没问题，但前端看不到最新变化

可能原因

交易还未确认
RPC 节点延迟
前端读的是旧网络
前端地址和实际登录地址不是同一个

我常用的排查顺序

先看交易 hash 是否成功上链
再用区块浏览器查事件
确认前端连接的 chainId
手动调用 balanceOf 验证合约状态

4. 重复发积分

这个是会员系统最容易造成业务事故的问题。

典型场景

消息队列重复投递
用户连续点击
后端超时重试
交易成功但应用层没正确记录

解决思路

每次发积分都带唯一 bizId
数据库层面对 bizId 建唯一索引
链下任务表记录交易状态
不要只依赖前端“防重复点击”

5. 本地测试一切正常，上测试网就卡住

常见原因

RPC 不稳定
Gas 设置太低
账户余额不足
区块确认慢
合约地址配错网络

建议

明确区分 env 配置
每个网络单独维护 CONTRACT_ADDRESS
后端日志里打印 chainId、发送者地址、交易 hash

安全最佳实践

Web3 会员系统的攻击面不只在合约，也在登录、后端和运营侧。

1. 登录安全

必做项

nonce 一次性使用
nonce 设置过期时间
JWT 设置较短有效期
服务端记录登录行为日志
对签名消息增加域名/用途说明

更规范一点的消息可以这样写：

欢迎登录 xxx 会员积分系统
Domain: example.com
Address: 0x...
Nonce: ...
Issued At: ...
Purpose: Login

这样用户在钱包里看到签名内容时，也更容易理解自己在签什么。

2. 合约权限最小化

积分系统合约最好至少区分：

DEFAULT_ADMIN_ROLE
OPERATOR_ROLE

并且：

admin 不直接用于日常发积分
operator 使用专门服务地址
高权限地址最好走多签

如果你的项目已经有一定规模，我强烈建议管理员权限放到多签钱包，而不是某个工程师个人 EOΑ 地址。

3. 防刷与风控

钱包登录不是天然抗刷。一个脚本就能批量生成钱包。

所以实际风控要结合：

设备指纹
IP 频率限制
行为节奏检测
链上画像
黑名单地址
同一业务事件的唯一性约束

Web3 不代表不要风控，只是风控维度变了。

4. 敏感接口必须服务端控制

发积分、扣积分、等级调整，不应该由前端直接调用管理员合约权限。

正确做法是：

前端只调用业务 API
后端做规则校验和权限判断
后端再用服务钱包提交交易

否则一旦管理员私钥泄漏到前端，基本就是事故预定。

性能最佳实践

会员积分系统的性能瓶颈往往在三处：

链上写入成本
查询吞吐
事件对账与状态同步

1. 读写分离

写

后端统一写链
业务事件异步化
批量上链或延迟结算

读

余额可直接读链
流水、活动记录从数据库或索引服务读
不要让前端每次都从创世块扫事件

2. 事件索引服务

如果你需要展示积分流水，建议使用：

自建监听服务
The Graph
或轻量级区块事件同步器

因为直接在前端按区块范围拉事件，随着时间推移会越来越慢。

可以把链上事件同步到数据库：

tx_hash
block_number
user_address
amount
biz_id
reason
event_type

这样查询速度和分页能力都会更好。

3. 批量结算

对于高频积分行为，建议做聚合：

同一用户一天签到奖励合并结算
同一活动内多个小任务统一发放
低价值行为先链下累计，达到阈值再上链

这在成本上非常有效。

4. 等级计算缓存

如果等级规则复杂，不要每次页面打开都实时计算。

更好的方式是：

定时任务计算
写入缓存或数据库
页面直接读取结果
在关键事件后增量更新

一个更完整的状态模型建议

如果你准备把这个系统做成产品，而不是 Demo，我建议把数据模型至少拆成下面几类：

classDiagram
    class User {
      +address: string
      +walletType: string
      +createdAt: datetime
      +status: string
    }

    class LoginNonce {
      +address: string
      +nonce: string
      +expiredAt: datetime
      +used: bool
    }

    class PointsJob {
      +jobId: string
      +bizId: string
      +address: string
      +amount: number
      +status: string
      +txHash: string
    }

    class PointsLedger {
      +address: string
      +changeType: string
      +amount: number
      +bizId: string
      +txHash: string
      +createdAt: datetime
    }

    class MemberLevel {
      +address: string
      +level: string
      +updatedAt: datetime
    }

    User --> LoginNonce
    User --> PointsJob
    User --> PointsLedger
    User --> MemberLevel

这几个模型一旦建清楚，很多问题就会简单很多：

登录问题查 LoginNonce
发积分问题查 PointsJob
对账问题查 PointsLedger
等级展示查 MemberLevel

什么时候不适合上链？

这点也要说清楚，不是所有会员积分都适合做 Web3 方案。

如果你的业务满足以下条件，先不要急着上链：

积分只用于站内折扣，且用户根本不关心可验证性
每天积分变动量极大，高频低价值
没有钱包用户基础
业务规则变化极快，每周都在改
合规边界尚不明确

这时更合理的路径是：

先做钱包登录
再做链下积分
最后把关键权益或高价值凭证上链

也就是说，Web3 化可以分阶段，不必一步到位。

总结

如果你想搭建一个可落地的 Web3 去中心化会员积分系统，我建议抓住三个关键词：

钱包签名登录
链下规则编排
链上可信结算

这套架构的核心价值不在于“所有东西都上链”，而在于：

用户身份是可自证的
核心积分状态是可审计的
业务规则是可运营、可升级的

最后给几个可直接执行的建议：

先做最小闭环
- 钱包登录
- 查询积分
- 发积分
- 扣积分
不要一开始就把复杂等级规则写进合约
- 先链下计算
- 规则稳定后再考虑链上固化
幂等一定先做
- bizId 唯一
- 数据库唯一索引
- 任务状态机完整
优先部署到低成本 EVM 网络或 L2
- 不要直接拿主网做高频积分实验
把安全边界画清楚
- 前端负责签名与展示
- 后端负责规则与权限
- 合约负责可信记账

如果你已经会写基本合约，也理解钱包签名流程，那么把这篇文章里的结构照着做一遍，基本就能搭出一个真正有产品雏形的 Web3 会员积分系统。真正的难点，不是“合约怎么写”，而是怎样在可信、成本、灵活性之间找到平衡点。这也是中级 Web3 工程实践和玩具 Demo 的分水岭。

《Web3 中级实战：基于智能合约与钱包登录构建可落地的去中心化会员积分系统》

Web3 中级实战：基于智能合约与钱包登录构建可落地的去中心化会员积分系统

背景与问题

1. 身份不再是手机号，而是钱包地址

2. 积分到底要不要全上链？

3. 会员系统不是“余额系统”那么简单

方案目标与架构边界

不追求的目标

总体架构设计

方案对比与取舍分析

方案 A：纯链上积分系统

方案 B：纯链下积分系统 + 钱包登录

方案 C：链下规则 + 链上结算账本

核心原理

1. 钱包登录原理：签名而不是密码

为什么一定要 nonce？

2. 链上积分账本原理

3. 会员等级计算原理

模式 A：实时链上判断

模式 B：链下定期计算 + 链上固化等级

容量估算与设计建议

推荐落地策略

智能合约设计

Solidity 合约

设计说明

实战代码（可运行）

一、项目结构

二、安装依赖

三、Hardhat 配置

四、部署脚本

五、后端：钱包登录与发积分接口

.env 示例

六、前端：MetaMask 登录与查询积分

七、调用发积分接口

积分发放业务流设计

1. 幂等 ID

2. 任务状态机

常见坑与排查

1. 钱包签名成功，但后端验签失败

可能原因

排查方式

建议

2. 调用发积分接口时报权限错误

3. 查询余额没问题，但前端看不到最新变化

可能原因

我常用的排查顺序

4. 重复发积分

典型场景

解决思路

5. 本地测试一切正常，上测试网就卡住

常见原因

建议

安全最佳实践

1. 登录安全

必做项

2. 合约权限最小化

3. 防刷与风控

4. 敏感接口必须服务端控制

性能最佳实践

1. 读写分离

写

读

2. 事件索引服务

3. 批量结算

4. 等级计算缓存

一个更完整的状态模型建议

什么时候不适合上链？

总结

`.env` 示例