Principles of Distributed Ledgers

Principles of Distributed Ledgers: Coursework Objective The objective of this coursework is to develop a Solidity contract, HumanResources, which implements a human resources (HR) payment system and to deploy it on Optimism. This contract will enable a human resources manager to manage employee registrations, terminations, and allow employees to withdraw their salary. Key Goals • Implement role-based access control and enforce functions to be callable only by the HR manager or registered employees. • Allow to register and terminate employees. • Enable employees to withdraw salaries in USDC or ETH based on their preference. • Use an oracle to get the current ETH price and an AMM to perform swaps from USDC to ETH for salary disbursement in ETH. Instructions Your task is to build the HumanResources contract that implements the given IHumanResources interface and deploy it to Optimism. You are free to use any Solidity library you want, and to interact with any other contract on Optimism. However, you must ensure that you follow the specifications very carefully. The correctness of the contract will be graded automatically, so failure to follow the specifications will result in deducted marks. Project Specifications Assumptions • The HumanResources contract will hold USDC only. This USDC will be sent by the HR manager using a normal transfer. • There are two versions of USDC on Optimism (USDC and USDC.e). In this coursework, we exclu sively use the USDC version deployed at this address: 0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85. • For the purpose of this coursework, we assume 1 USD = 1 USDC 1

1. Contract Setup and Role Management • Define the contract HumanResources that implements IHumanResources (see below). Do not modify the given IHumanResources interface. • The contract should have an hrManager. Only this address should be able to register and terminate employees. This address should be set when the contract is created and should not be modifiable by anyone. • Use the NotAuthorized error when an unauthorized user tries to call restricted functions.
2. Registering and Managing Employees • registerEmployee: – Register employees with an address and a weeklyUsdSalary in USD, scaled with 18 deci mals. – Emit the EmployeeRegistered event. – If the employee is already registered, revert with EmployeeAlreadyRegistered. – If an employee was terminated and is re-registered, his salary shall start accumulating again from the point at which he is registered again. • terminateEmployee: – Allow only the HR Manager to terminate an employee’s contract. – The employee’s salary accumulation should stop upon termination. – Emit the EmployeeTerminated event. – If the employee is not registered, revert with EmployeeNotRegistered.
3. Salary Accumulation and Withdrawal • Accrual Logic: – Salary accrues continuously based on the weekly USD salary. For example, after 2 days, 2/7ths of the weekly salary is available for withdrawal. – We do not consider weekends and non-working hours in this coursework. The salary should be accumulated linearly with time. • withdrawSalary: – Allows employees to withdraw their accumulated salary in their preferred currency (USDC or ETH). – When in ETH mode and a withdrawal is initiated, swap the appropriate amount of USDC to ETH. The swap can use wrapped ETH (WETH)1 , but the salary must be paid in ETH, not in WETH. The ETH should be sent in a re-entrancy safe manner (this will be covered in depth in lecture 8). – Use an oracle to 代写Principles of Distributed Ledgers get the current ETH price and protect against AMM price manipulation. – Emit the SalaryWithdrawn event with isEth indicating the currency withdrawn. 1WETH is an ERC20 representation of ETH. The WETH smart contract allows anyone to lock ETH and mint WETH, an ERC20 token representation, where 1 WETH = 1 ETH. One may also redeem 1 ETH for 1 WETH token. The WETH address on Optimism is: 0x4200000000000000000000000000000000000006 2 – Note: USDC has six decimals. Hence, when performing calculations between USDC and other assets (e.g., ETH), be careful to scale the values appropriately. • Currency Switching: – Employees can call switchCurrency to toggle between receiving salary in USDC and ETH. – The current pending salary shall be withdrawn automatically when this is called. – The default currency shall be USDC. – Emit the CurrencySwitched event whenever an employee toggles their preferred currency.
4. Using AMMs and Oracles We do not enforce any AMM or oracle for this coursework but we recommend using Uniswap as the AMM and Chainlink as the oracle. • Chainlink Integration (Oracle): – The Chainlink feed for ETH/USD on Optimism can be found at the following address: 0x13e3Ee699D1909E989722E753853AE30b17e08c5. The interface of this contract can be found here: AggregatorV3Interface.sol. – For the purpose of this coursework, you do not need to follow best practices such as checking for the time of the latest price update • Uniswap Integration (AMM): – We recommend using the Uniswap swap router that can be found here for Optimism: 0xE592427A0AEce92De3Edee1F18E0157C05861564. The interface of this contract can be here: IV3SwapRouter.sol. – Ensure that the swap is protected against front-running and excessive slippage. The most common way to protect against front-running slippage is to pass a minimum amount out to the swap function used. For this coursework, if the ETH returned from the swap is under 2% less that what would be expected at the current price, the function should revert.
5. Views and Employee Information • salaryAvailable: – Returns the available salary for an employee in the preferred currency (USDC or ETH). The amount must be scaled with the correct number of decimals for the currency. • hrManager: – Returns the HR manager’s address. • getActiveEmployeeCount: – Returns the count of currently active (non-terminated) employees. • getEmployeeInfo: – Returns the employee’s weeklyUsdSalary, employedSince timestamp (the time at which the employee was registered, or re-registered after a termination), and terminatedAt times tamp if terminated, or zero if the employee is active (either non-terminated or re-registered). – If the employee does not exist, the function shall not revert but all returned values must be zero. 3
6. Deployment to Optimism
7. Claim some ETH from the faucet. Make sure that you have control over the address that receives the ETH. NOTE: the faucet has been reset so that everyone can claim again.
8. Deploy the contract to Optimism. Do NOT verify the contract.
9. Register the contract address you deployed by calling the submit function of this contract: 0xbe41d42e2d1373120b24dd27a5465d8ef48b9d34. IMPORTANT: use the same address you used when claiming ETH in step 1 to call the submit function, since it is what we will use to identify your submission.
10. You can re-submit as many times as you want. Your latest submission (until the deadline) will be used to run the tests. Testing Requirements Your submission should include a suite of tests covering all the functions in the interface for both success and failure cases (e.g., unauthorized user calling). To test integration with external contracts, you will need to use fork testing and use contracts deployed on Optimism. Fork testing can be slow, so we recommend explicitly setting the block number to make subsequent calls faster. Submission Requirements The submission should be a single zip file that follows the regular Foundry project structure. Please do not nest the project when zipping it (i.e., README.md and other foundry files should be at the root of the zip file). The commands forge build and forge test MUST work when ran after unzipping the submission. The submission must contain at least the following content:
11. Contract Code: The code of the deployed contract. It should be in a file called src/HumanResources.sol.
12. Other code: Any other code required to compile and test the application. This includes but is not limited to foundry.toml and the content of the lib directory.
13. Deployment Address: Provide the address of the deployed contract on Optimism. It should be written in a file called deployed-address.txt, placed in the root folder, that only contains this address.
14. Transaction hash: Submit the transaction hash of calling the submit function described in 6 above. It should be written in a file called submit-transaction.txt, placed in the root folder, that only contains this transaction hash.
15. Test Suite: Include a full test suite for your contract (written in Solidity with Foundry). Tests should be in the test directory.
16. Documentation: Brief documentation explaining how your contract implements each function in the IHumanResources interface and a summary of how the AMM and the oracle are integrated. The documentation should be in a README.md file placed in the root folder. You are free to add other relevant files to the submission but please do not include your .git folder or other files that are not relevant to it. 4 Evaluation Criteria Your contract will be evaluated based on the following criteria: • Correctness: Does the contract meet all the interface requirements and handle edge cases? • Security: Is access control properly implemented? Are error messages used appropriately? • Integration: Does the contract integrate correctly with the AMM and the oracle? • Code Quality: Is the code readable, maintainable, and well-documented? • Testing: Does the test suite thoroughly cover different scenarios and edge cases? IMPORTANT The correctness, security, and integration parts of the grade will be given by testing your deployed contract against our test suite. If your contract is not deployed correctly or does not implement the provided interface, you will not get any points for this part. 5 Solidity Interface The same interface is also available here to make copy-pasting easier. IHumanResources.sol // SPDX - License - Identifier : GPL -3.0 pragma solidity ^0.8.24; /// @notice This interface defines the functions that the HumanResources contract must implement /// The contract must be able to register employees , terminate them , and allow employees to withdraw their salary /// The contract will be funded using only USDC but will pay the employees in USDC or ETH interface IHumanResources { /// @notice This error is raised if a user tries to call a function they are not authorized to call error NotAuthorized () ; /// @notice This error is raised if a user tries to register an employee that is already registered error EmployeeAlreadyRegistered () ; /// @notice This error is raised if a user tries to terminate an employee that is not registered error EmployeeNotRegistered () ; /// @notice This event is emitted when an employee is registered event EmployeeRegistered ( address indexed employee , uint256 weeklyUsdSalary ); /// @notice This event is emitted when an employee is terminated event EmployeeTerminated ( address indexed employee ); /// @notice This event is emitted when an employee withdraws their salary /// @param amount must be the amount in the currency the employee prefers ( USDC or ETH ) scaled correctly event SalaryWithdrawn ( address indexed employee , bool isEth , uint256 amount ); /// @notice This event is emitted when an employee switches the currency in which they receive the salary event CurrencySwitched ( address indexed employee , bool isEth ); /// HR manager functions /// Only the address returned by the ‘hrManager ‘ below is able to call these functions /// If anyone else tries to call them , the transaction must revert with the ‘ NotAuthorized ‘ error above /// Registers an employee in the HR system /// @param employee address of the employee /// @param weeklyUsdSalary salary of the employee in USD scaled with 18 decimals function registerEmployee ( address employee , uint256 weeklyUsdSalary ) external ; /// Terminates the contract of a given an employee . /// The salary of the employee will stop being accumulated . /// @param employee address of the employee function terminateEmployee ( address employee ) external ; /// Employee functions /// These are only be callabale by employees 6 /// If anyone else tries to call them , the transaction shall revert with the ‘ NotAuthorized ‘ error above /// Only the ‘withdrawSalary ‘ can be called by non - active (i.e. terminated ) employees /// Withdraws the salary of the employee /// This sends either USDC or ETH to the employee , depending on the employee ’s preference /// The salary accumulates with time ( regardless of nights , weekends , and other non working hours ) according to the employee weekly salary /// This means that after 2 days , the employee will be able to withdraw 2/7 th of his weekly salary function withdrawSalary () external ; /// Switches the currency in which the employee receives the salary /// By default , the salary is paid in USDC /// If the employee calls this function , the salary will be paid in ETH /// If he calls it again , the salary will be paid in USDC again /// When the salary is paid in ETH , the contract will swap the amount to be paid from USDC to ETH /// When this function is called , the current accumulated salary should be withdrawn automatically ( emitting the ‘SalaryWithdrawn ‘ event ) function switchCurrency () external ; // Views /// Returns the salary available for withdrawal for a given employee /// This returns the amount in the currency the employee prefers ( USDC or ETH ) /// The amount must be scaled with the correct number of decimals for the currency /// @param employee the address of the employee function salaryAvailable ( address employee ) external view returns ( uint256 ); /// Returns the address of the HR manager function hrManager () external view returns ( address ); /// Returns the number of active employees registered in the HR system function getActiveEmployeeCount () external view returns ( uint256 ); /// Returns information about an employee /// If the employee does not exist , the function does not revert but all values returned must be 0 /// @param employee the address of the employee /// @return weeklyUsdSalary the weekly salary of the employee in USD , scaled with 18 decimals /// @return employedSince the timestamp at which the employee was registered /// @return terminatedAt the timestamp at which the employee was terminated (or 0 if the employee is still active ) function getEmployeeInfo ( address employee ) external view returns ( uint256 weeklyUsdSalary , uint256 employedSince , uint256 terminatedAt

WX：codinghelp