# contractdev **Repository Path**: andoridityu/contractdev ## Basic Information - **Project Name**: contractdev - **Description**: No description available - **Primary Language**: Unknown - **License**: AGPL-3.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-10-12 - **Last Updated**: 2025-10-13 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ZodiacNFT 合约项目 🚀 这是一个基于 Foundry 框架的 ZodiacNFT ERC1155 合约项目，包含完整的部署脚本、测试用例和验证工具。 ## 项目概述 ✨ 本项目实现了 ZodiacNFT 合约，这是一个基于 ERC1155 标准的 NFT 合约，具有以下特性： - 支持多代币类型的 NFT - 基于 OpenZeppelin AccessControl 的权限控制 - 支持铸造和销毁功能 - 支持元数据 URI 更新 - 完整的测试覆盖 ## 主要功能 🌟 - **ZodiacNFT 合约**: 基于 ERC1155 和 AccessControl 的 NFT 合约 - **部署脚本**: 完整的部署脚本和流程 - **测试套件**: 全面的单元测试覆盖所有核心功能 - **验证工具**: 支持多平台的合约验证脚本 - **Makefile 工作流**: 简化项目管理和操作的 Makefile ## 技术栈 🛠️ - [Foundry](https://getfoundry.sh/) - 智能合约开发工具链 - [Solidity](https://soliditylang.org/) - 智能合约编程语言 - [OpenZeppelin Contracts](https://openzeppelin.com/contracts/) - 安全的智能合约库 - [ERC1155](https://eips.ethereum.org/EIPS/eip-1155) - 多代币标准 ## 前置条件 📋 - [Foundry](https://getfoundry.sh/) - [Git](https://git-scm.com/) - [Make](https://www.gnu.org/software/make/) ## 快速开始 🏁 克隆仓库并初始化： ```bash git clone cd contractdev # 初始化项目环境 cp .env.example .env make init ``` 编辑 `.env` 文件以匹配您的网络配置和设置。 `make init` 命令会执行以下操作： 1. 检查是否已安装 Foundry 工具链，如果没有则自动安装 2. 检查依赖项是否已安装，如果没有则自动安装所有依赖项 3. 构建项目 如果您只想安装依赖项而不构建项目，可以使用： ```bash make install-deps ``` ### 依赖管理最佳实践 为了保持仓库的整洁，我们遵循以下依赖管理最佳实践： 1. **不提交依赖项**：[lib](file:///Users/mac/WebstormProjects/aragonpluginkafa/contractdev/lib/forge-std/scripts/vm.py#L409-L409) 目录已添加到 [.gitignore](file:///Users/mac/WebstormProjects/aragonpluginkafa/contractdev/.gitignore) 文件中，不会被提交到版本控制系统 2. **自动安装依赖**：其他开发者可以通过 `make init` 命令自动安装所有依赖项 3. **版本控制**：依赖项的版本通过 Git 子模块进行管理，版本信息保存在 `.gitmodules` 文件中 如果您需要手动安装依赖项，可以使用以下命令： ```bash # 使用Git子模块安装所有依赖项（推荐） make install-deps # 或者使用git命令直接安装 git submodule update --init --recursive ``` ### Git 子模块命令详解 本项目使用 Git 子模块来管理依赖项。以下是常用的 Git 子模块命令： #### 1. 克隆包含子模块的仓库 ```bash # 克隆仓库并初始化子模块 git clone --recurse-submodules # 或者分两步进行 git clone cd git submodule update --init --recursive ``` #### 2. 添加新的子模块 ```bash git submodule add # 例如：git submodule add https://github.com/foundry-rs/forge-std lib/forge-std ``` #### 3. 更新子模块 ```bash # 更新所有子模块到最新提交 git submodule update --remote # 更新特定子模块 git submodule update --remote ``` #### 4. 初始化子模块 ```bash # 初始化所有子模块 git submodule init # 初始化特定子模块 git submodule init ``` #### 5. 查看子模块状态 ```bash # 查看所有子模块的状态 git submodule status # 查看子模块的详细信息 git submodule foreach git status ``` #### 6. 删除子模块 ```bash # 1. 删除子模块条目 git submodule deinit # 2. 从工作目录删除子模块文件 rm -rf # 3. 从.git/modules目录删除子模块 rm -rf .git/modules/ # 4. 从.gitmodules文件中删除相关条目 git config -f .gitmodules --remove-section submodule. # 5. 从.git/config中删除相关条目 git config --remove-section submodule. # 6. 提交更改 git add .gitmodules git commit -m "Remove submodule " ``` 安装依赖项后，您需要在 `remappings.txt` 文件中添加相应的路径映射： ```txt # 在 remappings.txt 中添加映射 @organization/repo-name/=lib/repo-name/ ``` ## 项目结构 📁 ``` ├── src/ # 智能合约源代码 │ └── ZodiacNFT.sol # 主要的 ZodiacNFT 合约 ├── script/ # 部署和验证脚本 │ ├── DeployZodiacNFT.s.sol # 部署脚本 │ └── verify-zodiac-nft.sh # 验证脚本 ├── test/ # 测试文件 │ └── ZodiacNFT.t.sol # ZodiacNFT 测试套件 ├── lib/ # 依赖项（通常不提交到版本控制） ├── artifacts/ # 部署产物 ├── broadcast/ # 部署广播文件 └── foundry.toml # Foundry 配置文件 ``` > **注意**: `lib/` 目录通常不提交到版本控制系统中，以避免将第三方依赖代码提交到自己的代码仓库中。其他开发者克隆仓库后，可以通过 `make init` 命令自动安装所有依赖项。 ## Foundry 配置文件 (foundry.toml) 🔧 项目使用 [foundry.toml](file:///Users/mac/WebstormProjects/aragonpluginkafa/contractdev/foundry.toml) 文件来配置 Foundry 工具链的各种选项。主要配置项包括： ### 基本配置 - `src`: 源代码目录 - `out`: 编译输出目录 - `libs`: 依赖项目录 - `fs_permissions`: 文件系统权限配置 ### 编译配置 - `evm_version`: EVM 版本（默认为 cancun） - `optimizer`: 是否启用优化器 - `optimizer-runs`: 优化器运行次数 - `solc`: Solidity 编译器版本 - `via_ir`: 是否通过 IR 编译 ### 网络特定配置 项目支持多种网络配置，可以在 [foundry.toml](file:///Users/mac/WebstormProjects/aragonpluginkafa/contractdev/foundry.toml) 中配置不同的网络设置。 ### 自定义配置 您可以根据需要修改 [foundry.toml](file:///Users/mac/WebstormProjects/aragonpluginkafa/contractdev/foundry.toml) 文件来调整编译器设置、优化选项等。 ## 使用 Makefile 🎯 项目使用 Makefile 管理工作流，提供以下命令： ``` $ make Available targets: - make help 显示可用目标 - make init 检查依赖并提示安装（如果需要） - make clean 清理构建产物 测试生命周期: - make test 运行单元测试 - make test-fork 运行分叉测试（使用 RPC_URL） - make test-coverage 生成 HTML 覆盖率报告 部署目标: - make predeploy 模拟协议部署 - make deploy 部署协议，验证源代码并写入 ./artifacts 验证: - make verify-etherscan 在 Etherscan（兼容）浏览器上验证最后的部署 - make verify-blockscout 在 BlockScout 上验证最后的部署 - make verify-sourcify 在 Sourcify 上验证最后的部署 其他: - make refund 退还部署账户的剩余余额 ``` ## 使用 Forge 命令行工具 🔧 除了使用 Makefile，您也可以直接使用 Forge 命令行工具来执行各种操作： ### 编译合约 ```bash # 编译所有合约 forge build # 清理构建产物 forge clean # 重新编译（强制） forge build --force ``` ### 运行测试 ```bash # 运行所有测试 forge test # 运行测试并显示详细输出 forge test -vvv # 运行特定测试文件 forge test --match-path test/ZodiacNFT.t.sol # 运行特定测试函数 forge test --match-test test_Deployment # 生成测试覆盖率报告 forge coverage # 生成 HTML 覆盖率报告 forge coverage --report lcov && genhtml lcov.info -o report ``` ### 添加依赖项 ```bash # 安装新的依赖项 forge install / # 例如: forge install OpenZeppelin/openzeppelin-contracts # 使用特定版本 forge install /@ # 例如: forge install OpenZeppelin/openzeppelin-contracts@v4.9.5 # 安装但不提交到 git forge install / --no-commit # 查看已安装的依赖项 ls lib/ ``` 安装依赖项后，您需要在 `remappings.txt` 文件中添加相应的路径映射： ```txt # 在 remappings.txt 中添加映射 @organization/repo-name/=lib/repo-name/ ``` ### 管理依赖项版本 ```bash # 进入依赖目录并切换到特定版本 cd lib/ git checkout # 返回项目根目录 cd - # 提交版本更改 git add lib/ git commit -m "Use " ``` ### 部署合约 ```bash # 模拟部署（不实际发送交易） forge script script/DeployZodiacNFT.s.sol:DeployZodiacNFTScript --rpc-url $RPC_URL # 实际部署 forge script script/DeployZodiacNFT.s.sol:DeployZodiacNFTScript --rpc-url $RPC_URL --broadcast # 部署并验证合约 forge script script/DeployZodiacNFT.s.sol:DeployZodiacNFTScript --rpc-url $RPC_URL --broadcast --verify # 使用特定网络配置部署 forge script script/DeployZodiacNFT.s.sol:DeployZodiacNFTScript --network sepolia --broadcast --verify ``` ### 合约验证 ```bash # 验证已部署的合约 forge verify-contract src/ZodiacNFT.sol:ZodiacNFT --chain-id --etherscan-api-key $ETHERSCAN_API_KEY # 使用自定义验证器验证 forge verify-contract src/ZodiacNFT.sol:ZodiacNFT --verifier blockscout --verifier-url # 验证带有构造函数参数的合约 forge verify-contract src/ZodiacNFT.sol:ZodiacNFT --constructor-args $(cast abi-encode "constructor(address)" ) --etherscan-api-key $ETHERSCAN_API_KEY ``` ### 生成合约 ABI 和其他信息 ```bash # 生成合约 ABI（JSON 格式） forge inspect src/ZodiacNFT.sol:ZodiacNFT abi --json > ZodiacNFT.abi.json # 查看合约存储布局 forge inspect src/ZodiacNFT.sol:ZodiacNFT storage-layout # 查看合约 ABI（表格格式） forge inspect src/ZodiacNFT.sol:ZodiacNFT abi # 查看合约方法签名 forge inspect src/ZodiacNFT.sol:ZodiacNFT methods # 查看合约 bytecode forge inspect src/ZodiacNFT.sol:ZodiacNFT bytecode ``` ### 与已部署合约交互 ```bash # 查询合约状态 cast call "balanceOf(address,uint256)" --rpc-url $RPC_URL # 发送交易到合约 cast send "mint(address,uint256,uint256)" --rpc-url $RPC_URL --private-key $PRIVATE_KEY # 查询合约事件 cast logs --address --rpc-url $RPC_URL ``` ## ZodiacNFT 合约详解 🔍 ### 核心特性 1. **ERC1155 兼容**: 支持多代币类型的 NFT 2. **权限控制**: 基于 OpenZeppelin AccessControl 实现角色管理 3. **铸造功能**: 支持铸造新的 NFT（仅限 MINTER_ROLE） 4. **销毁功能**: 支持销毁 NFT（仅限 MINTER_ROLE） 5. **URI 管理**: 支持更新元数据 URI（仅限 DEFAULT_ADMIN_ROLE） ### 角色权限 - `DEFAULT_ADMIN_ROLE`: 可以授予和撤销角色 - `MINTER_ROLE`: 可以铸造和销毁 NFT 初始管理员同时拥有这两个角色。 ## 部署 ZodiacNFT 🚀 ### 环境变量配置 在 `.env` 文件中配置以下变量： ```bash DEPLOYMENT_PRIVATE_KEY=your_private_key_here NETWORK_NAME=sepolia RPC_URL=https://sepolia.infura.io/v3/YOUR_INFURA_KEY ZODIAC_NFT_INITIAL_ADMIN=0xYourAdminAddressHere # 合约验证配置（可选） VERIFIER=etherscan VERIFIER_URL=https://api-sepolia.etherscan.io/api VERIFIER_API_KEY=your_etherscan_api_key ``` ### 部署命令 ```bash # 模拟部署 make predeploy # 实际部署 make deploy ``` ## 测试 💡 运行测试： ```bash # 运行单元测试 make test # 生成覆盖率报告 make test-coverage ``` 测试覆盖以下功能： - 合约部署 - 管理员铸造和销毁 - 授权用户铸造和销毁 - 权限控制验证 - URI 更新功能 - 接口支持验证 ## 合约验证 ✅ 部署后可以使用以下命令验证合约： ```bash # 验证合约（使用 Etherscan 或兼容的浏览器） make verify-etherscan # 验证合约（使用 Blockscout） make verify-blockscout # 验证合约（使用 Sourcify） make verify-sourcify ``` ## 安全 🔒 如果您发现安全问题，请通过以下方式联系我们： 安全联系邮箱: sirt@aragon.org 请不要在公共问题跟踪器上报告安全问题。 ## 许可证 📄 本项目采用 MIT 许可证。 ## 支持 💬 如需支持，请在仓库中提交问题或联系项目维护者。