WEB3 API聚合平台 - 项目技术与设计文档1. 项目概述 (Executive Summary)1.1. 项目愿景 (Vision)WEB3 API聚合平台 旨在成为 Web3 时代领先的去中心化API聚合与调用权市场。我们的愿景是打破传统API经济的中心化壁垒，将API调用权从僵化的订阅制中解放出来，使其成为一种可自由交易、可组合、可拥有的链上数字资产，从而构建一个更加开放、高效、公平的价值互联网。1.2. 解决的痛点 (Problem Statement)僵化的订阅模式: 用户被迫为未使用的API容量支付固定费用，而小型开发者难以提供灵活的付费选项。价值孤岛: API调用权被锁定在各个平台内部，无法形成流动的二级市场，其资产价值未被充分发掘。性能瓶颈: 现有的大多数区块链无法处理高并发、低延迟的微交易，阻碍了链上API经济的实现。1.3. 核心解决方案 (Core Solution)我们将API调用次数打包成 ERC-1155 标准的半同质化代币 (NFT)。API提供商 可以将其服务容量（如：1000次AI模型调用）铸造成“调用权包”NFT，并在我们的开放市场上架销售。用户/开发者 可以按需购买这些NFT，获得对应次数的API调用权。这些NFT是用户钱包中的真实资产，可以转售、赠送或集成到其他DeFi应用中。2. 技术选型与优势 (Technology Stack & Rationale)2.1. 区块链平台：Monad (Blockchain Platform: Monad)选择 Monad 是本项目的核心技术优势所在，其特性完美匹配我们的业务需求：超高吞吐量 (High Throughput): 能够处理海量用户同时购买和使用API产生的微交易，确保市场无延迟。并行执行 (Parallel Execution): 不同API的交易可以并行处理，互不干扰，从根本上解决了网络拥堵问题。完全EVM兼容 (Full EVM Compatibility): 允许我们使用成熟的以太坊工具链（Solidity, Hardhat, Ethers.js），极大加速了开发进程并保证了合约的安全性。2.2. 核心技术栈 (Core Tech Stack)智能合约: Solidity, OpenZeppelin Contracts, Hardhat后端: Node.js, Express.js, Ethers.js (v5/v6), JSON Web Tokens (JWT)前端: HTML, CSS, JavaScript (可根据需求采用React/Vue等现代框架)3. 系统架构 (System Architecture)3.1. 前端 (Frontend - UI Layer)职责: 纯粹的UI/UX层，负责数据展示和用户输入。核心交互:通过 window.ethereum 请求用户用钱包签名一条消息以进行身份验证。将签名发送到后端，换取JWT会话令牌并保存在本地。在所有后续API请求的 Authorization 头中附带此JWT。浏览和购买套餐包，与合约进行交互3.2. 后端 (Backend - Gateway Node)职责: 项目的业务逻辑中枢，连接Web2的流畅体验和Web3的价值结算。核心功能:用户认证: 提供 /api/login 端点，验证签名并颁发JWT。API代理: 提供 /api/call/{api_name} 端点。在调用外部API前，先通过合约的 balanceOf 检查用户的NFT余额，成功后再转发请求，并在成功后记录额度消耗（链下或链上）。3.3. 智能合约 (Smart Contract - On-Chain Logic)职责: 价值的最终记账层和所有权的核心保障。核心功能:定义和管理代表API调用权的ERC-1155 NFT。实现去中心化的市场逻辑，如上架和购买。通过 Ownable 和 Pausable 实现合约的安全管理。4. 智能合约设计 (GatewayERC1155_V2.sol)4.1. 合约标准与继承ERC1155.sol: 核心代币标准，支持同一合约内管理多种类型的代币（不同的API包）。Ownable.sol: 引入合约所有者角色，用于执行管理操作（如设置费用、暂停合约）。Pausable.sol: 允许所有者在紧急情况下暂停所有代币转移功能，作为安全开关。4.2. 核心状态变量// 描述一个上架商品的结构体 struct Listing {    address seller;         // 卖家地址    address treasury;       // 收款金库地址    uint256 pricePerUnit;   // 每个销售单位的价格 (以Wei为单位)    uint256 amountPerUnit;  // 每个销售单位包含的API调用次数 } ​ // 从 tokenId 映射到其上架信息 mapping(uint256 => Listing) public listings;4.3. 关键函数详解setListing(uint256 _tokenId, uint256 _pricePerUnit, uint256 _amountPerUnit, address _treasury)功能: 允许卖家（msg.sender）上架或更新一个API包的销售信息。权限: 任何人都可以调用，实现了无需许可的市场。buyPack(uint256 _tokenId, uint256 _units) external payable功能: 核心购买函数。流程:检查商品是否已上架。验证 msg.value 是否等于 listing.pricePerUnit * _units。验证卖家是否有足够的NFT库存 (balanceOf(seller, ...)).关键: 调用 safeTransferFrom 将NFT从卖家转移给买家 (msg.sender)。将 msg.value 的资金转入卖家的 treasury 地址。重要: 此函数依赖于卖家已预先调用 setApprovalForAll(address(this), true) 授权给本合约。unpause() / pause()功能: 仅限合约所有者调用，用于启动或暂停合约的代币转移功能。新部署的合约默认为暂停状态，必须由所有者调用 unpause() 后才能开始交易。