讲解 program、Python/Java程序辅导
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 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
1. 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.
2. Deploy the contract to Optimism. Do NOT verify the contract.
3. 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.
4. 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:
1. Contract Code: The code of the deployed contract. It should be in a file called src/HumanResources.sol.
2. 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.
3. 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.
4. 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.
5. Test Suite: Include a full test suite for your contract (written in Solidity with Foundry). Tests
should be in the test directory.
6. 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
);
}
7