[Web3] 智能合约 09: 项目实战① FishCake EventFi

本文详解FishCake EventFi项目智能合约体系,涵盖NFT身份管理、活动挖矿、FCC代币经济模型、Booster NFT质押增益机制及赎回池设计。重点解析NftManager、FishcakeEventManager、StakingManager等核心合约逻辑,以及Go链下服务的事件监听、worker任务调度与API架构。项目基于BNB测试网部署,采用UUPS升级模式,强调权限分离、防重入、资金安全等Web3工程实践要点。

本系列封面

一.项目概况

主要功能

  • NFT 会员

  • 活动即挖矿

  • 质押年化收益

  • 钱包(不讲)

  • 代币经济模型

项目链接

  • 官方链接

  • https://fishcake.io/

  • https://fishcake.org/

  • https://www.fishcake.org/join APP 下载

  • 代码

  • 后端代码:https://github.com/FishcakeLab/fishcake-service

  • 合约代码:https://github.com/FishcakeLab/fishcake-contracts

  • APP:https://github.com/FishcakeLab/FishCake

  • H5: https://github.com/FishcakeLab/fishcake-web3

二.项目简介

FishCake 是一个 NFT 会员,集活动挖矿,代币经济模型,质押收益和钱包为一体化的一个项目

【图示 1】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

系统角色

  • 普通用户:未持有身份 NFT,可以发起和参与活动,但不能获得 FCC 活动奖励。

  • 个人用户:支付 8U Mint 个人身份 NFT。

  • 商家用户:支付 80U Mint 商家身份 NFT。

  • 活动发起人:可以是普通用户、个人用户或商家用户。

  • NFT 持有人:具备领取 FCC 活动奖励以及 Booster NFT 的资格。

FCC 初始分配

身份 NFT 业务流程

  • 用户连接钱包并选择身份类型。

  • 个人用户支付 8U,商家用户支付 80U。

  • 用户通过 NftManager Mint 对应身份 NFT。

  • NftManager 记录用户身份和 NFT 等级。

  • NFT 销售收入的 25% 进入 RedemptionPool 赎回池。

  • 用户获得活动奖励资格。

业务规则:

  • 没有 NFT 的用户也可以发起活动。

  • 没有 NFT 的用户不能获得 FCC 活动奖励。

  • 只有持有个人 NFT 或商家 NFT 的用户才能获得 FCC 奖励。

活动业务流程

  • 用户或商家成为活动发起人。

  • 发起人通过 FishcakeEventManager 创建活动。

  • 活动内容、开始时间、结束时间、空投规则和奖励规则被记录在链上。

  • 其他用户查看活动并参与。

  • 符合条件的参与者领取活动空投。

  • 活动结束后,由发起人或系统执行活动结算。

  • FishcakeEventManager 检查用户是否持有有效身份 NFT。

  • 符合条件的用户获得 FCC 奖励。

  • 系统根据用户参与活动的情况发放 Booster NFT。

其中,活动奖励主要来自分配给 FishcakeEventManager 的 30% FCC。

Booster NFT 与质押流程

  • 用户通过参与活动获得 Booster NFT。

  • 系统根据活动次数、贡献度或完成情况确定 Booster NFT 等级。

  • 用户将 FCC 存入 StakingManager 进行质押。

  • StakingManager 读取用户的 Booster NFT 等级。

  • 根据不同等级计算对应的收益权重。

  • Booster NFT 等级越高,收益系数越高。

  • 用户按照规则领取 FCC 质押收益。

质押奖励主要来自分配给 StakingManager 的 10% FCC。

FCC 购买流程

系统包含两类销售池:

  • InvestorSalePool:面向投资人或特定用户销售,获得总量的 10% FCC。

  • DirectSalePoolV1:面向普通用户直接销售 FCC。

基本流程:

  • 用户选择购买 FCC。

  • 用户支付 USDT。

  • 对应销售池按照价格计算 FCC 数量。

  • 销售池向用户发放 FCC。

  • 图中标注销售资金的 50% 进入 RedemptionPool。

图中的“购买代币”线路经过 FishcakeEventManager,建议实际实现时统一由销售池负责收款和发币,避免活动合约同时承担代币销售职责。

FCC 赎回流程

RedemptionPool 的资金来源包括:

  • NFT 销售收入的 25%。

  • FCC 销售收入的 50%。

  • 其他后续注入的赽回储备资金。

用户赎回时,按照图片中的公式计算:

赎回USDT数量=RedemptionPool的USDT余额×用户赎回FCC数量FCC总供应量赎回USDT数量= RedemptionPool的USDT余额 \times \frac{用户赎回FCC数量}{FCC总供应量}赎回USDT数量=RedemptionPool的USDT余额×FCC总供应量用户赎回FCC数量

对应代码逻辑:

usdtToken.balanceOf(address(this))
    * _amount
    / fishcakeCoin.totalSupply();

赎回流程:

  • 用户提交需要赎回的 FCC 数量。

  • 系统检查用户余额和授权额度。

  • 计算用户可以获得的 USDT。

  • 将用户提交的 FCC 销毁或转入回收地址。

  • RedemptionPool 向用户支付 USDT。

  • 更新赎回池余额和相关记录。

三.项目的架构设计

合约层面

  • Interface, Storage 和 logic 进行分离,继承和注意 slot 的处理

  • 能做为常量的千万不要是变量,能 imutable 的一定要修饰成 imutable

  • 注意权限的控制,权限分离,日常操作,资金操作,权限管理一定要分离

  • 合约是时间锁,代币锁

  • 合约升级模式----UUPS 或者透明代理都可以,这个项目用的是 UUPS

  • 注意常见的攻击手段

  • 那些合约设计成可升级的,那些合约设计成不可升级的需要严格注意

  • …

Go 服务层面

  • 架构清晰明了

  • 表结构设计,索引等等

  • 注意处理链上回滚

  • 主从数据库处理,多数据库表处理

  • Metrics 指标明确

  • …

项目整体架构设计

【图示 2】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

四.合约代码讲解

NFT 合约(NftManger)

  • createNFT—> Mint 商家和个人 NFT 的方法

  • Mint 的 NFT 的流程图

【图示 3】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

  • mintBoosterNFT

FishcakeEventManager

  • 发起活动:activityAdd

【图示 4】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

  • 活动空投:drop

【图示 5】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

【图示 6】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

StakinManager

FCC Staking 收益和 BoosterNFT 收益
固定 APR 结构(基础收益)

【配图 1】原文此处为图片示意,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

FCC Staking Booster

Booster NFT Mint 流程:官方空投用途(非公开Mint)

Fishcake 的 Booster NFT 是不可自由铸造的功能性NFT,只能由项目方根据Leaderboard或其他激励策略 按需Mint 给用户,确保公平与控制通胀。

等级

NFT 名称

基础 APR 加成
(2025 后使用减半)

发放 (根据leaderboard)

Tier 1

Legendary Tuna

+20% APR

当月ming = 1500FCC

Tier 2

Epic Salmon

+15% APR

当月mining ≥ 800 FCC

Tier 3

Rare Shrimp

+9% APR

当月mining =300FCC

Tier 4

Uncommon Fishcake

+5% APR

当月mining =60FCC

NFT Booster 使用原理
  • 原则:

  • 例效果(以 90 天为例):

  • USDT 空投奖励(代码里面看不出来)

代码逻辑梳理
  • depositIntoStaking

【图示 7】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

  • withdrawFromStakingWithAprIncome

【图示 8】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

销售合约

  • DirectSalePoolV1

【图示 9】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

  • InvestorSalePool

【图示 10】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

计算的逻辑

  • 按照 FCC 的数量计算

  • 按照 USDT 的数量计算

FCC 代币合约

  • 发币的逻辑
function poolAllocate() external onlyOwner {
    _beforeAllocation();
    _mint(fcPool.miningPool, (MaxTotalSupply * 3) / 10); // 30% of total supply
    _mint(fcPool.directSalePool, (MaxTotalSupply * 2) / 10); // 20% of total supply
    _mint(fcPool.investorSalePool, MaxTotalSupply / 10); // 10% of total supply
    _mint(fcPool.nftSalesRewardsPool, (MaxTotalSupply * 2) / 10); // 20% of total supply
    _mint(fcPool.ecosystemPool, MaxTotalSupply / 10); // 10% of total supply
    _mint(fcPool.foundationPool, MaxTotalSupply / 10); // 10% of total supply
    isAllocation = true;
}
  • 活动挖矿的:30%

  • directSalePool 直接销售:20%

  • investorSalePool 投资者销售:10%

  • nftSalesRewardsPool:NFT 销售 20%

  • ecosystemPool 生态池: 10%

  • foundationPool 基金会 10%

赎回池合约

赎回池资金锁定时间:uint256 public immutable unlockTime = block.timestamp + 1095 days; 其实是 3 年

用户赎回 USDT 的流程

【图示 11】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

FCC 转换成 USDT 的计算逻辑讲解:

usdtToken.balanceOf(address(this)) * _amount / fishcakeCoin.totalSupply();

例子:

  • 赎回池有 10000000 USDT

  • 总发行量是:10000000000 FCC

  • 用户 A 用 10000 FCC 赎回 USDT

  • 用户 B 用 10000 FCC 赎回 USDT

五. Go 代码的讲解

代码架构

【图示 12】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

合约事件监听

  • 参考前面讲过的代码,和其他项目是类似的,这里不再赘述

合约事件结合业务解析

  • 解析合约事件总体业务逻辑

【图示 13】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

  • 解析合约事件的详情

【图示 14】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

业务进程讲解

简介

Worker 一共有有 4 个人任务,分别承载区块数据的清理,系统空投和钱包创建空投的逻辑,交易的上链处理队列

  • clean_data_worker:清理 block_headers 的数据,清理之后只留下最新的 200000 条数据,这种处理方式有一定的问题,实际需要把数据进行分表处理,持久化历史数据。

  • drop_worker 和 system_drop_worker:第一次和活动合约交互的人会获得空投

  • submit_tx_worker:前端进行交易离线签名之后,发送后端 queue_tx 表,这个进程来将这些交易发送链上,并确保交易能够成功。

详细的业务流程
clean_data_worker

【图示 15】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

drop_worker 和 system_drop_worker

【图示 16】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

queue_tx

【图示 17】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

API 讲解

【图示 18】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

  • /v1/wallet/createWallet: 这个 API 是存在问题,他不管代币的空投是否成功,只是空投了,其他都不管,需要改进成为后台任务,获取交易的收据树,若失败需要再次空投。

代码总结

合约代码:https://github.com/FishcakeLab/fishcake-contracts

Go 服务代码:https://github.com/FishcakeLab/fishcake-service

代码经济模型:https://github.com/FishcakeLab/Fishcake-Tokenomics

Wallet 对接链上:https://github.com/dapplink-labs/wallet-chain-node

Dapplink-wallet-api: https://github.com/dapplink-external/dapplink-wallet-api

rpc 负载:https://github.com/FishcakeLab/fishcake-rpc

六. BNB 测试网运行测试

合约的部署

  • 地址准备

Successfully created new keypair.
Address:     0xd449306df27faB97ec0431F4558ab75966743983
Private key: 0xb857bcf6f3ee005a79eea257a4ab467a3488b5006fa4a9dbba7d54a9a41aafa5
  • 去 github 上 clone 代码
git clone git@github.com:FishcakeLab/fishcake-contracts.git

forge build 自动安全依赖和构建
  • 配置环境变量
export PRIVATE_KEY=0xb857bcf6f3ee005a79eea257a4ab467a3488b5006fa4a9dbba7d54a9a41aafa5
export BOOSTER_ADDRESS=0xd449306df27faB97ec0431F4558ab75966743983
  • 部署合约
forge script ./script/DeployerScript.sol:DeployerScript --rpc-url https://bsc-testnet.bnbchain.org  --broadcast
  • 部署之后得到的地址
No files changed, compilation skipped
Script ran successfully.

== Logs ==
  Deploying contracts with account: 0xd449306df27faB97ec0431F4558ab75966743983
  "商家地址" \
  "https://example.com" \
  "https://x.com/example" \
  1 \
  --rpc-url "https://go.getblock.io/40740512324a466bb572c9f6455c274f" \
  --private-key "$PRIVATE_KEY"

发活动

RPC_URL='https://go.getblock.io/40740512324a466bb572c9f6455c274f'
EVENT_MANAGER='0xA7f5734cC2e5c3D0F10783f41467499284706C85'
USDT='0x32295C8a779cDA5F71E99Bb6605cE115511a3332'
DEADLINE=$(($(date +%s) + 600))
TOTAL_DROP_AMTS=1000000000

cast send "$USDT" 'approve(address,uint256)' "$EVENT_MANAGER" "$TOTAL_DROP_AMTS" --rpc-url "$RPC_URL" --private-key "$PRIVATE_KEY"

cast send "$EVENT_MANAGER" 'activityAdd(string,string,string,uint256,uint256,uint8,uint256,uint256,uint256,address)' 'FishCake深圳活动' '参与线下活动领取奖励' '22.543096,114.057865' "$DEADLINE" 1000000000 1 100 0 10000000 "$USDT" --rpc-url "$RPC_URL" --private-key "$PRIVATE_KEY"

链下服务的启动

  • 克隆代码
git clone git@github.com:FishcakeLab/fishcake-service.git

go mod tidy
  • 编译代码
make
  • 配置启动配置文件
migrations: "./migrations"

# Polygon RPC(用公共节点即可,读区块够用)

polygon_rpc: "https://go.getblock.io/40740512324a466bb572c9f6455c274f"

rpc_url: "tw-wallet-chain-account:80"
polygon_chain_id: "137"

http_host: "127.0.0.1"
http_port: 8189

db_host: "127.0.0.1"
db_port: 5432
db_name: "fishcakes9"
db_user: "guoshijiang"
db_password: ""

metrics_host: "127.0.0.1"
metrics_port: 9090

# 同步起始区块

start_block: 124371300
event_start_block: 124371300

# 三个合约地址(都用合法的格式即可)
contracts:
    - "0x2282F52bf0a13BfD1b0135209303a4A7b23bB0AA"
    - "0xA7f5734cC2e5c3D0F10783f41467499284706C85"
    - "0xF818C5667520Be9CBBdB7831864F5286Ffbdb14d"

# 阿里云配置(本地无调用逻辑时填假值防空指针)
ali_config:
    region_id: "cn-hangzhou"
    access_key: "FAKE_ACCESS_KEY"
    access_secret: "FAKE_ACCESS_SECRET"

# 合约依赖映射(都填上有效格式地址即可)
  • 执行 migrate 生成数据库
./fishcake migrate
  • 启动扫链服务
./fishcake index
  • 启动 api 服务
./fishcake api
  • 测试 API
        "businessName": "FishCake深圳活动",
        "activityContent": "参与线下活动领取奖励",
        "latitudeLongitude": "22.543096,114.057865",
        "activityCreateTime": 1786416159,
        "activityDeadline": 1786416745,
        "dropType": 1,
        "dropNumber": 100,
        "minDropAmt": 0,
        "maxDropAmt": 10000000,
        "tokenContractAddr": "0x32295C8a779cDA5F71E99Bb6605cE115511a3332",
        "activityStatus": 1,
        "alreadyDropNumber": 0,
        "basicDeadline": 0,
        "proDeadline": 1789007404,
        "returnAmount": 0,
        "minedAmount": 0,
        "isExpired": false
      }
    ],
    "total": 1
  },
  "code": "0000"
}
  • 启动钱包的功能一定链接到:https://github.com/dapplink-labs/wallet-chain-account

七.项目实施过程中会遇到的问题

实际过程做回到 RPC 单节点问题,单节点会挂,一般会使用节点负载

RPC 节点在大一些公司,一般都是自建,自建之后做负载;在小一点的公司或者团队,用第三方的节点

自建节点

【图示 19】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

使用第三方节点

一般购买多家服务商的节点 alchemy, ankr, getblock, google 和 infura

【图示 20】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

在 FishCake,实际负载是 alchemy 和 ankr

链上交易失败的问题

  • 失败的交易重发,或者使用补偿任务单独处理

八.总结

大家可以启动项目,测试钱包的空投,钱包创建之后,提交钱包会获得 FCC 空投,第一次和活动合约进行交互,可以获得空投。

可以去感受一个 BoosterNFT 和 Staking 相关的功能,要深入一下,尤其是需要使用类似项目进行包装的小伙伴。

  • Mint 个人 NFT 花费 8U, mint NFT 完成之后获得是 100 FCC

  • Mint 上海 NFT 花费是 80, mint NFT 完成之后获得是 1000 FCC

  • Mint 的 USDT 有 25% 进入赎回池,75% 留在当前的 NFT 合约

  • Mint NFT 的有效期是 30 天

  • 用户传入用 mint NFT 的类别

【图示 21】原文此处为流程图/白板图示,因平台导出限制未能搬运。

源文档: https://w2z1amg2x5.sg.larksuite.com/docx/JU54d2cyVoGS3dxUM8Wlf3Qtgyf

等级

等级

NFT 名称

NFT 名称

基础 APR 加成
(2025 后使用减半)

基础 APR 加成

(2025 后使用减半)

发放 (根据leaderboard)

发放 (根据leaderboard)

Tier 1

Tier 1

Legendary Tuna

Legendary Tuna

+20% APR

+20% APR

当月ming = 1500FCC

当月ming = 1500FCC

Tier 2

Tier 2

Epic Salmon

Epic Salmon

+15% APR

+15% APR

当月mining ≥ 800 FCC

当月mining ≥ 800 FCC

Tier 3

Tier 3

Rare Shrimp

Rare Shrimp

+9% APR

+9% APR

当月mining =300FCC

当月mining =300FCC

Tier 4

Tier 4

Uncommon Fishcake

Uncommon Fishcake

+5% APR

+5% APR

当月mining =60FCC

当月mining =60FCC

  • Booster NFT 可一次性绑定到一笔质押;Booster NFT 属于额外的质押收益,如果没有 Booster NFT,只能获得固定的收益

  • 使用后该 Booster NFT 标记为“已使用”,不能重复。

  • 基础 APR: 9%

  • 使用 Epic Booster(+15% 年化)

  • 实际收益 %:{(9%+15%)/ 365} * 90 = 5.92%

  • 根据 leadboard 的榜单前 n 质押, 随机抽取 5-10 名幸运用瓜分 1000U,按照质押量

  • x >= 5000000 万 FCC;1 FCC = 0.06 USDT

  • 250_000 <= x < 50万 FCC; 1 FCC = 0.07 USDT

  • 100_000 <= x < 250_000 ;1 FCC = 0.08USDT

  • 16_666 <= x < 100_000 ;1 FCC = 0.09USDT

  • < 16_666; t FCC = 0.1USDT

  • X >= 100_000; 1 FCC = 0.06 USDT

  • 10_000 <= X < 100_000; 1 FCC = 0.07 USDT

  • 5_000 <= X < 10_000; 1 FCC = 0.08USDT

  • X < 1_000; 1 FCC = 0.09USDT

  • 10000000 * 10000 / 10000000000 = 10 USDT

  • 动作完成之后

  • USDT:9999990

  • FCC: 9999990000

  • 9999990 * 10000 / 9999990000 = 10 USDT

评论
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付:10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

OxYGC

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值