From 28182e31e8b3fa447f8deac033918c8abb5cf008 Mon Sep 17 00:00:00 2001 From: gigileungyingchi Date: Wed, 4 Sep 2024 14:22:31 +0200 Subject: [PATCH] Add documentations to contracts in evm-contract --- evm-contract/src/CarbonOffsetSettler.sol | 47 ++++++++++++--------- evm-contract/src/HoldingContract.sol | 44 +++++++++++++------ evm-contract/src/HoldingContractFactory.sol | 23 ++++++++-- 3 files changed, 77 insertions(+), 37 deletions(-) diff --git a/evm-contract/src/CarbonOffsetSettler.sol b/evm-contract/src/CarbonOffsetSettler.sol index 5e32825..f35d240 100644 --- a/evm-contract/src/CarbonOffsetSettler.sol +++ b/evm-contract/src/CarbonOffsetSettler.sol @@ -10,6 +10,9 @@ import "lib/openzeppelin-contracts/contracts/token/ERC721/IERC721Receiver.sol"; import "lib/openzeppelin-contracts-upgradeable/contracts/token/ERC721/IERC721Upgradeable.sol"; import "forge-std/console.sol"; +/** + * @notice This contract is to be used to purchase and offset carbon credits + */ contract CarbonOffsetSettler is OwnableUpgradeable, IERC721Receiver { address public constant NCT = 0xD838290e877E0188a4A44700463419ED96c16107; address public constant CERT = 0x5e377f16E4ec6001652befD737341a28889Af002; @@ -19,18 +22,15 @@ contract CarbonOffsetSettler is OwnableUpgradeable, IERC721Receiver { uint public tokenId; - // function initialize( - // address newholdingContract, - // address sunriseAdmin - // ) external { - // transferOwnership(sunriseAdmin); - // holdingContract = newholdingContract; - // } - - // function setHoldingContract(address newHoldingContract) external onlyOwner { - // holdingContract = newHoldingContract; - // } - + /** + * Retire carbon credits from specified project for a specified amount of USDC + * @param _tco2 Address of the project for which TCO2 will be retired + * @param _amountUSDC Amount of USDC to be used to buy carbon credits + * @param _entity Name of the entity who is performing the retirement + * @param _beneficiary Address of beneficiary, to whom the retirement will be accredited + * @param _beneficiaryName Name of beneficiary + * @param _msg Any message to be attached to the retirement certificate + */ function retire( address _tco2, uint256 _amountUSDC, @@ -72,7 +72,7 @@ contract CarbonOffsetSettler is OwnableUpgradeable, IERC721Receiver { ); } - /* + /** * @notice Called when new Toucan retirement certificate NFTs are minted. */ function onERC721Received( @@ -85,9 +85,10 @@ contract CarbonOffsetSettler is OwnableUpgradeable, IERC721Receiver { return IERC721Receiver.onERC721Received.selector; } - /* - * Given a specific TCO2 and amount, return the amount of xUSDC we would - * need to burn after fees. + /** + * Given a specific TCO2 and amount, return the amount of xUSDC we would need to burn after fees. + * @param _tco2 Address of the project for which TCO2 will be retired + * @param _amountToOffset Amount of TCO2 to offset */ function getUSDCNeeded( address _tco2, @@ -111,9 +112,10 @@ contract CarbonOffsetSettler is OwnableUpgradeable, IERC721Receiver { return expectedAmountsIn[0]; } - /* - * Given a specific TCO2 and amount, return the amount of xUSDC we would - * need to burn after fees. + /** + * Given a specific TCO2 and amount, return the amount of NCT we would need to burn after fees. + * @param _tco2 Address of the project for which TCO2 will be retired + * @param _amountToOffset Amount of TCO2 to offset */ function getExpectedNCT( address _tco2, @@ -135,8 +137,10 @@ contract CarbonOffsetSettler is OwnableUpgradeable, IERC721Receiver { return expectedAmountsIn[0]; } - /* - * Only support USDC <-> NCT routes + /** + * Find path for swapping; only support USDC <-> NCT routes + * @param _from Address of token to be swapped from + * @param _to Address of token to be swapped to */ function generatePath( address _from, @@ -150,6 +154,7 @@ contract CarbonOffsetSettler is OwnableUpgradeable, IERC721Receiver { /** * Swap USDC on contract into NCT. + * @param _amountUSDC Amount of USDC to swap for NCT tokans */ function swap(uint256 _amountUSDC) public returns (uint256) { IUniswapV2Router02 routerSushi = IUniswapV2Router02(SUSHI_ROUTER); diff --git a/evm-contract/src/HoldingContract.sol b/evm-contract/src/HoldingContract.sol index e477964..81bb13d 100644 --- a/evm-contract/src/HoldingContract.sol +++ b/evm-contract/src/HoldingContract.sol @@ -12,6 +12,15 @@ import "lib/openzeppelin-contracts-upgradeable/contracts/token/ERC721/IERC721Upg import "lib/openzeppelin-contracts/contracts/token/ERC721/IERC721Receiver.sol"; import "lib/openzeppelin-contracts/contracts/utils/Counters.sol"; +/** + * A holding contract that holds the bridged funds from a Solana account, use it to buy and retire TCO2, + * and send the retirement certificate back to the Solana address + * @param tco2 Address of the project for which TCO2 will be retired + * @param beneficiary Address of beneficiary, to whom the retirement will be accredited + * @param beneficiaryName Name of beneficiary + * @param SolanaAccountAddress Address of wallet in Solana to which the retirement certificate will be sent to + * @param retireContract Address of the deployed contract of CarbonOffsetSettler to be used to retire TCO2 + */ contract HoldingContract is OwnableUpgradeable, IERC721Receiver { // Logic contract address // address public logicContract; @@ -37,7 +46,13 @@ contract HoldingContract is OwnableUpgradeable, IERC721Receiver { // USDC token contract address public constant USDC = 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174; - // Event emitted when funds are used to offset emissions + /** + * Event emitted when funds are used to offset emissions + * @param tco2 Address of the project for which TCO2 will be retired + * @param beneficiary Address of beneficiary, to whom the retirement will be accredited + * @param beneficiaryName Name of beneficiary + * @param amount Amount of TCO2 offset + */ event Offset( address indexed tco2, address indexed beneficiary, @@ -49,8 +64,15 @@ contract HoldingContract is OwnableUpgradeable, IERC721Receiver { error InsufficientFunds(); error InvalidRetireContract(); - /* + /** + * To initialize a holding contract with a new set of parameters * @notice Initialize the proxy contract + * @param newTco2 Address of the project for which TCO2 will be retired + * @param newBeneficiary Address of beneficiary, to whom the retirement will be accredited + * @param newBeneficiaryName Name of beneficiary + * @param newSolanaAccountAddress Address of wallet in Solana to which the retirement certificate will be sent to + * @param newRetireContract Address of the deployed contract of CarbonOffsetSettler to be used to retire TCO2 + * @param owner Address of owner of the holding contract */ function initialize( address newTco2, @@ -70,22 +92,18 @@ contract HoldingContract is OwnableUpgradeable, IERC721Receiver { transferOwnership(owner); } - /* + /** * @notice Set the address of the CarbonOffsetSettler contract - * @param newRetireContract address of the CarbonOffsetSettler contract + * @param newRetireContract Address of the CarbonOffsetSettler contract */ function setRetireContract(address newRetireContract) external onlyOwner { if (newRetireContract == address(0)) revert InvalidRetireContract(); retireContract = newRetireContract; } - // function setFactoryContract(address newFactoryContract) external onlyOwner { - // factoryContract = newFactoryContract; - // } - // ------------------ Setting retirement details (admin-only, ensure valid values) ------------------ // - /* + /** * @notice Set the details for the beneficiary of the carbon offset * @param newBeneficiary address of the beneficiary (in case you're retiring for someone else) * @param newBeneficiaryName name of the beneficiary @@ -98,7 +116,7 @@ contract HoldingContract is OwnableUpgradeable, IERC721Receiver { beneficiaryName = newBeneficiaryName; } - /* + /** * @notice Set the address of the TCO2 token contract * @param newTco2 address of the TCO2 token contract */ @@ -118,7 +136,7 @@ contract HoldingContract is OwnableUpgradeable, IERC721Receiver { } // --------------------------------- Permissionless retiring --------------------------------------- // - /* + /** * @notice Offset carbon emissions by sending USDC to the CarbonOffsetSettler contract and using the funds to retire carbon tokens. * @param entity name of the entity that does the retirement (Sunrise Stake) * @param message retirement message @@ -158,7 +176,7 @@ contract HoldingContract is OwnableUpgradeable, IERC721Receiver { _bridgeNFT(tokenId); } - /* + /** * @dev Necessary to receive ERC721 transfers */ function onERC721Received( @@ -170,7 +188,7 @@ contract HoldingContract is OwnableUpgradeable, IERC721Receiver { return IERC721Receiver.onERC721Received.selector; } - /* + /** * @notice Set the Solana Account that receives the retirement certificate * @dev This is read out to calculate the associated token account for the Wormhole message * @param newSolanaAccountAddress address of the Solana Account diff --git a/evm-contract/src/HoldingContractFactory.sol b/evm-contract/src/HoldingContractFactory.sol index b1382ad..8b89dcc 100644 --- a/evm-contract/src/HoldingContractFactory.sol +++ b/evm-contract/src/HoldingContractFactory.sol @@ -6,6 +6,11 @@ import "src/HoldingContract.sol"; import "forge-std/console.sol"; import "lib/openzeppelin-contracts/contracts/access/Ownable.sol"; +/** + * @notice Factory to generate holding contracts + * @param implementationAddress + * @param proxies + */ contract HoldingContractFactory is Ownable { address public implementationAddress; address[] public proxies; @@ -16,12 +21,24 @@ contract HoldingContractFactory is Ownable { implementationAddress = newImplementationAddress; } + /** + * @notice Set the implementation address for a holding contract + * @param newImplementationAddress Address of the implementation of a holding contract + */ function setImplementationAddress( address newImplementationAddress ) external onlyOwner { implementationAddress = newImplementationAddress; } + /** + * Create a new holding contract + * @param salt Salt for determining the address of new holding contract + * @param newTco2 Address of the project for which TCO2 will be retired + * @param newBeneficiaryName Name of beneficiary + * @param newSolanaAccountAddress Address of wallet in Solana to which the retirement certificate will be sent to + * @param retireContract Address of the deployed contract of CarbonOffsetSettler to be used to retire TCO2 + */ function createContract( bytes32 salt, address newTco2, @@ -47,9 +64,9 @@ contract HoldingContractFactory is Ownable { } /** - * @dev Returns the address of the implementation given a particular salt - * @return The address of the implementation. - */ + * @dev Returns the address of the implementation given a particular salt + * @return The address of the implementation. + */ function getContractAddress( bytes32 salt, address deployer