# Project #1: Simple Registry ## Objectives * Users (identified by an address) can claim a name, which is recorded on-chain. * Once a name has been claimed, no other user can claim it. * A name owner can release a name. * A user can claim any number of names. ## Blueprint * A mapping to serve as a registry. * Function to register names. * Function to release ownership of a name. * Events to announce state changes for each function. ### Base Code {% code title="SimpleNameRegister.sol" %} ```solidity // SPDX-License-Identifier: UNLICENSED pragma solidity ^0.8.13; /** @title An on-chain name registry @author Calnix @notice A registed name can be released, availing to be registered by another user */ contract SimpleNameRegister { /// @notice Map a name to an address to identify current holder mapping (string => address) public holder; /// @notice Emit event when a name is registered event Register(address indexed holder, string name); /// @notice Emit event when a name is released event Release(address indexed holder, string name); /// @notice User can register an available name /// @param name The string to register function register(string calldata name) external { require(holder[name] == address(0), "Already registered!"); holder[name] = msg.sender; emit Register(msg.sender, name); } /// @notice Holder can release a name, making it available /// @param name The string to release function release(string calldata name) external { require(holder[name] == msg.sender, "Not your name!"); delete holder[name]; emit Release(msg.sender, name); } } ``` {% endcode %} #### 1. Mapping: associating names to their respective owner's address ```solidity mapping (string => address) public holder; ``` * initialized as a public state variable. * solidity will automatically create a getter function for it, which we can use to pass a name as parameter to check ownership. * If there is no owner, the address returned will be `0x0000000000000000000000000000000000000000` #### 2. Function to allow a user to register their ownership of a name ```solidity function register(string calldata name) external { require(holder[name] == address(0), "Already registered!"); holder[name] = msg.sender; emit Register(msg.sender, name); } ``` * require statement checks if the name passed is available to be claimed. * If available, passed name is mapped to the address of the `msg.sender` via the mapping `holder` * event `Registered` emitted each time a name is registered. #### 3. Function to allow a user to relinquish their ownership of a name ```solidity function release(string calldata name) external { require(holder[name] == msg.sender, "Not your name!"); delete holder[name]; emit Release(msg.sender, name); } ``` * require statement checks if the name passed is indeed registered to the function caller (msg.sender) * If so, we reset the mapped address of the name to the zero address. * *mappings can be seen as hash tables which are virtually initialized such that every possible key exists and is mapped to default values.* * *the default value for address type will be* `0x0000000000000000000000000000000000000000` or `address(0)` * event `Release`emitted each time a name is relinquished. ## Events Events allow us to “print” information on the blockchain in a way that is more searchable and gas efficient than just saving to public storage variables in our smart contracts. {% hint style="info" %} For more on events: {% endhint %} ### **Problem:** * A single address could be the owner of multiple names. * It would be useful if the end-user could simply supply their address to check which are the names registered to them. * Achieving this one to many structure on-chain would not be gas efficient. ### **Solution: Using Events** * Run a background task that subscribes to events from the contract. * This background task will listen to events as they are emitted and track the list of addresses for each owner via some centralized database. * Website front-end can read from this database and reflect accordingly. ## Testing Testing in Solidity is somewhat different from other frameworks like brownie, as they would be done in Solidity. Essentially we deploy a test contract containing our test functions. {% tabs %} {% tab title="Linear Test Approach" %} ```solidity // SPDX-License-Identifier: UNLICENSED pragma solidity ^0.8.13; import "ds-test/test.sol"; import 'src/SimpleNameRegister.sol'; interface CheatCodes { function prank(address) external; function expectRevert(bytes calldata) external; function startPrank(address) external; function stopPrank() external; } contract SimpleNameRegisterTest is DSTest { // declare state var. SimpleNameRegister simpleNameRegister; CheatCodes cheats; address adversary; function setUp() public { simpleNameRegister = new SimpleNameRegister(); cheats = CheatCodes(HEVM_ADDRESS); adversary = 0xE6A2e85916802210147e366D4431f5ca4dD51a78; } // user can register an available name function testRegisterName(string memory _testString) public { simpleNameRegister.registerName(_testString); bool success = (address(this) == simpleNameRegister.nameOwner(_testString)); assertTrue(success); } // user can register an available name and relinquish it function testRelinquishName(string memory _testString) public { simpleNameRegister.registerName(_testString); simpleNameRegister.relinquishName(_testString); bool success = (simpleNameRegister.nameOwner(_testString) == address(0)); assertTrue(success); } // user cannot relinquish a name that does not belong to them function testRelinquishAsNotOwner(string memory _testString) public { simpleNameRegister.registerName(_testString); cheats.startPrank(adversary); cheats.expectRevert(bytes("The provided name does not belong to you!")); simpleNameRegister.relinquishName(_testString); cheats.stopPrank(); } // user cannot register a name that already has an owner function testRegisterUnavailableName(string memory _testString) public { simpleNameRegister.registerName(_testString); cheats.startPrank(adversary); cheats.expectRevert(bytes("The provided name has already been registered!")); simpleNameRegister.registerName(_testString); cheats.stopPrank(); } } ``` {% endtab %} {% tab title="State Inheritance Approach" %} ```solidity pragma solidity ^0.8.13; import "ds-test/test.sol"; import 'src/SimpleNameRegister.sol'; import "forge-std/console2.sol"; interface CheatCodes { function prank(address) external; function expectRevert(bytes calldata) external; function label(address addr, string calldata label) external; } abstract contract StateZero is DSTest { SimpleNameRegister public simpleNameRegister; CheatCodes cheats; address user; function setUp() public virtual { simpleNameRegister = new SimpleNameRegister(); cheats = CheatCodes(HEVM_ADDRESS); user = 0x0000000000000000000000000000000000000001; cheats.label(user, "user"); } } contract StateZeroTest is StateZero { function testCannotRelease(string memory testString) public { console2.log("Cannot release a name that you do not hold"); cheats.prank(user); cheats.expectRevert(bytes("Not your name!")); simpleNameRegister.release(testString); } function testRegister(string memory testString) public { console2.log("User registers a name"); cheats.prank(user); simpleNameRegister.register(testString); bool success = (user == simpleNameRegister.holder(testString)); assertTrue(success); } } abstract contract StateRegistered is StateZero { address adversary; string name; function setUp() public override { super.setUp(); adversary = 0xE6A2e85916802210147e366D4431f5ca4dD51a78; cheats.label(adversary, "adversary"); // state transition name = 'whale'; cheats.prank(user); simpleNameRegister.register(name); } } contract StateRegisteredTest is StateRegistered { function testAdversaryCannotRegisterName() public { console2.log("Adversary cannot register name belonging to User"); cheats.prank(adversary); cheats.expectRevert(bytes("Already registered!")); simpleNameRegister.register(name); } function testAdversaryCannotReleaseName() public { console2.log("Adversary cannot release name belonging to User"); cheats.prank(adversary); cheats.expectRevert(bytes("Not your name!")); simpleNameRegister.release(name); } function testUserCannotRegisterOwnedName() public { console2.log("User cannot register a name that he already holds"); cheats.prank(user); cheats.expectRevert(bytes("Already registered!")); simpleNameRegister.register(name); } function testUserRelease() public { console2.log("User releases name that he holds"); cheats.prank(user); simpleNameRegister.release(name); bool success = (address(0) == simpleNameRegister.holder(name)); assertTrue(success); } } ``` {% endtab %} {% endtabs %} #### function setUp() The setup function is invoked before each test case is run. Serves to setup the necessary variables and conditions for your test functions to operate. * deploy a fresh instance of SimpleNameRegister before each test function is ran via `simpleNameRegister = new SimpleNameRegister()` * `address adversary` will be used in test 3 & 4 {% hint style="info" %} Each test is run as independent cases -> changes made in a prior test function will not spill out of scope into a following test function (See more: ) {% endhint %} {% hint style="info" %} For more about CheatCodes: [https://app.gitbook.com/s/Tgomzlmn9NrxUY0OQ3cD/foundry/testing#cheatcodes](/eth-dev/foundry/testing.md#cheatcodes) {% endhint %} ### Linear vs State Inheritance Approach ## Deployment ```bash forge create src/SimpleNameRegister.sol:SimpleNameRegister --private-key ${PRIVATE_KEY_EDGE} --rpc-url ${ETH_RPC_URL} ``` * Forge can deploy only one contract at a time. * Solidity files may contain multiple contracts. `:MyContract` above specifies which contract to deploy from the `src/MyContract.sol` file ### Verifying ```bash forge verify-contract --chain-id ${KOVAN_CHAINID} --compiler-version v0.8.13+commit.abaa5c0e ${CONTRACT_ADDRESS} src/SimpleNameRegister.sol:SimpleNameRegister ${ETHERSCAN_API_KEY} --num-of-optimizations 200 ``` {% hint style="info" %} `Set --num-of-optimizations 200` If not set on deployment, foundry defaults to 200. So make sure you pass `--num-of-optimizations 200` if you left the default compilation settings {% endhint %} ### Check verification ```bash forge verify-check --chain-id ${KOVAN_CHAINID} ${GUID} ${ETHERSCAN_API_KEY} ``` Running the above three commands manually, each time can be bothersome. To that end, create a new file 'MakeFile' in the project root directory if one does not exist. {% tabs %} {% tab title="Makefile" %} ```bash # include .env file and export its env vars (-include to ignore error if it does not exist) include .env deploy: forge create src/SimpleNameRegister.sol:SimpleNameRegister --private-key ${PRIVATE_KEY_EDGE} --rpc-url ${ETH_RPC_URL} verify: forge verify-contract --chain-id ${KOVAN_CHAINID} --compiler-version v0.8.13+commit.abaa5c0e ${CONTRACT_ADDRESS} src/SimpleNameRegister.sol:SimpleNameRegister ${ETHERSCAN_API_KEY} --num-of-optimizations 200 --flatten verify-check: forge verify-check --chain-id ${KOVAN_CHAINID} ${GUID} ${ETHERSCAN_API_KEY} ``` Now you will only need to run: * make deploy * make verify * make verify-check {% hint style="danger" %} Be sure to update the contract address and GUID values in .env for each deployment as they would change. Note:\ For make verify, the --flatten flag may ONLY be necessary on a window machine. If verification fails, try without it.\ \ If it still fails, its in god's hands now. {% endhint %} {% endtab %} {% tab title=".env" %} ```bash export PRIVATE_KEY_EDGE = 0x1232141356361...42414 export ETH_RPC_URL = https://kovan.infura.io/v3/b2a555d8b6e64178bbb736aabaf93a1a export ETHERSCAN_API_KEY = I5CK8CJ7FZ6BWQ6YGFD4U3E7CFTNWQJ3A3 export Contract = src/SimpleNameRegister.sol:SimpleNameRegister export KOVAN_CHAINID = 42 export CONTRACT_ADDRESS = 0xa155f6b896d1a22b2c18cb6229e4e0760176199b export GUID = dyrsthjrhefssx6epi91ky8dxdun69ufbmz5rgqt6dzxzcgt4w ``` {% endtab %} {% endtabs %} {% hint style="info" %} Installing make on windows:\ {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://calnix.gitbook.io/eth-dev/learning-solidity/project-1-simple-registry.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.