This project harnesses Hardhat for the development of a comprehensive blockchain-based citizenship system. It encompasses smart contracts for issuing, managing citizenship as NFTs (Non-Fungible Tokens), a verifier for attestation-based eligibility checks, a commemorative edition contract for special citizenship tokens editions, and a State Department contract for managing citizenship claims based on eligibility criteria.
The project comprises four primary smart contracts:
- Citizenship Contract: An ERC721 token representing digital citizenship, featuring pausing, minting, burning, and token URI updates, governed by specific roles.
- Verifier Contract: Interacts with external attestation systems to verify user eligibility for citizenship based on predefined criteria. Specifically, it checks on-chain attestations made by Coinbase on the Base network, enabling a secure and decentralized mechanism for verifying user information against trusted attestations.
- Commemorative Edition Contract: Allows updating of token URIs for special editions, leveraging EIP-712 signed messages for secure, off-chain communication between parties, ensuring authenticity and integrity of the requests.
- State Department Contract: Manages the eligibility and claims for citizenship tokens based on the verification process handled by the Verifier Contract. It integrates directly with the Citizenship Contract to mint tokens for eligible users.
The system utilizes Access Control roles for managing permissions across different functionalities:
- Admin Role: Full access to the system, capable of setting other roles, updating fees, and pausing the system.
- Minter Role: Granted to the State Department Contract to mint new citizenship tokens upon successful verification.
- URI Updater Role: Specific to the Commemorative Edition Contract for updating token URIs securely.
The project includes a comprehensive suite of tests, demonstrating the functionality of each contract and the interactions between them. Testing leverages Hardhat's network forking feature to simulate real-world interactions on a local test network, ensuring thorough coverage and reliability.
- Set up the roles properly by granting the necessary permissions using the
grantRolefunction. - Use Hardhat's network forking to test against the Base Mainnet, allowing you to interact with deployed contracts such as the Coinbase attestation verifier without deploying to the main network.
- Ensure environment variables are correctly configured for network access and contract interactions.
Tests can be run using Hardhat commands, focusing on each contract's functionality and integration points:
npx hardhat testThis command runs all tests, verifying contract interactions, role-based access control, and integration logic.
- The Verifier Contract checks user eligibility for citizenship by verifying on-chain attestations from Coinbase on the Base network.
- Eligible users claim their citizenship through the State Department Contract, which mints a new citizenship token.
- Special editions of citizenship tokens can be issued through the Commemorative Edition Contract, with URI updates signed securely off-chain.
- The system is designed with extensibility and security in mind, ensuring that only eligible users can claim citizenship and that token metadata can be securely updated as needed.
To start working with these contracts, clone the repository, install dependencies, and follow the setup instructions to configure your environment. Ensure you have access to Alchemy or Infura for network access and have set up your .env file with the necessary API keys and secrets.
Made with love by Dennison Bertram and ChatGPT.
A Hardhat-based template for developing Solidity smart contracts, with sensible defaults.
- Hardhat: compile, run and test smart contracts
- TypeChain: generate TypeScript bindings for smart contracts
- Ethers: renowned Ethereum library and wallet implementation
- Solhint: code linter
- Solcover: code coverage
- Prettier Plugin Solidity: code formatter
Click the Use this template button at the top of the page to
create a new repository with this repo as the initial state.
This template builds upon the frameworks and libraries mentioned above, so for details about their specific features, please consult their respective documentations.
For example, for Hardhat, you can refer to the Hardhat Tutorial and the Hardhat Docs. You might be in particular interested in reading the Testing Contracts section.
This template comes with sensible default configurations in the following files:
├── .editorconfig
├── .eslintignore
├── .eslintrc.yml
├── .gitignore
├── .prettierignore
├── .prettierrc.yml
├── .solcover.js
├── .solhint.json
└── hardhat.config.ts
This template is IDE agnostic, but for the best user experience, you may want to use it in VSCode alongside Nomic Foundation's Solidity extension.
This template comes with GitHub Actions pre-configured. Your contracts will be linted and tested on every push and pull
request made to the main branch.
Note though that to make this work, you must use your INFURA_API_KEY and your MNEMONIC as GitHub secrets.
For more information on how to set up GitHub secrets, check out the docs.
You can edit the CI script in .github/workflows/ci.yml.
First, you need to install the dependencies:
bun installThen, you need to set up all the required Hardhat Configuration Variables. You might also want to install some that are optional.
To assist with the setup process, run bunx hardhat vars setup. To set a particular value, such as a BIP-39 mnemonic
variable, execute this:
bunx hardhat vars set MNEMONIC
? Enter value: ‣ here is where your twelve words mnemonic should be put my friendIf you do not already have a mnemonic, you can generate one using this website.
Compile the smart contracts with Hardhat:
bun run compileCompile the smart contracts and generate TypeChain bindings:
bun run typechainRun the tests with Hardhat:
bun run testLint the Solidity code:
bun run lint:solLint the TypeScript code:
bun run lint:tsGenerate the code coverage report:
bun run coverageSee the gas usage per unit test and average gas per method call:
REPORT_GAS=true bun run testDelete the smart contract artifacts, the coverage reports and the Hardhat cache:
bun run cleanDeploy the contracts to Hardhat Network:
bun run deploy:contractsDeploy a new instance of the Lock contract via a task:
bun run task:deployLock --unlock 100 --value 0.1If you use VSCode, you can get Solidity syntax highlighting with the hardhat-solidity extension.
GitPod is an open-source developer platform for remote development.
To view the coverage report generated by bun run coverage, just click Go Live from the status bar to turn the server
on/off.
npm i -g ganacheganache -s testThe
-s testpasses a seed to the local chain and makes it deterministic
Make sure to set the mnemonic in your .env file to that of the instance running with Ganache.
This project is licensed under MIT.