Skip to content

Commit

Permalink
Add documentations to contracts in evm-contract
Browse files Browse the repository at this point in the history
  • Loading branch information
@gigileungyingchi
gigileungyingchi committed Sep 4, 2024
1 parent 7b549a5 commit 28182e3
Show file tree
Hide file tree
Showing 3 changed files with 77 additions and 37 deletions.
47 changes: 26 additions & 21 deletions evm-contract/src/CarbonOffsetSettler.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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,
Expand Down Expand Up @@ -72,7 +72,7 @@ contract CarbonOffsetSettler is OwnableUpgradeable, IERC721Receiver {
);
}

/*
/**
* @notice Called when new Toucan retirement certificate NFTs are minted.
*/
function onERC721Received(
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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);
Expand Down
44 changes: 31 additions & 13 deletions evm-contract/src/HoldingContract.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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,
Expand All @@ -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,
Expand All @@ -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
Expand All @@ -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
*/
Expand All @@ -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
Expand Down Expand Up @@ -158,7 +176,7 @@ contract HoldingContract is OwnableUpgradeable, IERC721Receiver {
_bridgeNFT(tokenId);
}

/*
/**
* @dev Necessary to receive ERC721 transfers
*/
function onERC721Received(
Expand All @@ -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
Expand Down
23 changes: 20 additions & 3 deletions evm-contract/src/HoldingContractFactory.sol
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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,
Expand All @@ -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
Expand Down

0 comments on commit 28182e3

Please sign in to comment.