From abc967b448cc3ea0daa5f9b6161bb9a1fcbb6377 Mon Sep 17 00:00:00 2001 From: PacificYield <173040337+PacificYield@users.noreply.github.com> Date: Mon, 6 Jan 2025 11:30:45 +0100 Subject: [PATCH] docs: updates --- docs/finance/ConfidentialVestingWallet.md | 170 +++++++++++ .../finance/ConfidentialVestingWalletCliff.md | 60 ++++ docs/governance/CompoundTimelock.md | 38 +-- docs/governance/ConfidentialERC20Votes.md | 99 +++---- docs/governance/ConfidentialGovernorAlpha.md | 270 +++++++++--------- docs/governance/ICompoundTimelock.md | 2 + docs/governance/IConfidentialERC20Votes.md | 10 +- docs/token/ERC20/ConfidentialERC20.md | 80 +++--- docs/token/ERC20/ConfidentialERC20Wrapped.md | 118 ++++++++ docs/token/ERC20/ConfidentialWETH.md | 117 ++++++++ docs/token/ERC20/IConfidentialERC20.md | 216 +++++++++++--- docs/token/ERC20/IConfidentialERC20Wrapped.md | 95 ++++++ .../extensions/ConfidentialERC20Mintable.md | 25 +- .../extensions/ConfidentialERC20WithErrors.md | 64 ++--- .../ConfidentialERC20WithErrorsMintable.md | 23 +- docs/utils/EncryptedErrors.md | 225 +++++++++++++-- docs/utils/TFHEErrors.md | 9 + hardhat.config.ts | 1 + package.json | 2 +- 19 files changed, 1244 insertions(+), 380 deletions(-) create mode 100644 docs/finance/ConfidentialVestingWallet.md create mode 100644 docs/finance/ConfidentialVestingWalletCliff.md create mode 100644 docs/token/ERC20/ConfidentialERC20Wrapped.md create mode 100644 docs/token/ERC20/ConfidentialWETH.md create mode 100644 docs/token/ERC20/IConfidentialERC20Wrapped.md create mode 100644 docs/utils/TFHEErrors.md diff --git a/docs/finance/ConfidentialVestingWallet.md b/docs/finance/ConfidentialVestingWallet.md new file mode 100644 index 0000000..688a1bc --- /dev/null +++ b/docs/finance/ConfidentialVestingWallet.md @@ -0,0 +1,170 @@ +## ConfidentialVestingWallet + +This contract offers a simple vesting wallet for [ConfidentialERC20](../token/ERC20/IConfidentialERC20.md) tokens. This +is based on the +[VestingWallet.sol contract written by OpenZeppelin](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/release-v5.1/contracts/finance/VestingWallet.sol). + +_Default implementation is a linear vesting curve. To use with the native asset, it is necessary to wrap the native +asset to a ConfidentialERC20-like token._ + +### ConfidentialERC20Released + +```solidity +event ConfidentialERC20Released(address token) +``` + +Emitted when tokens are released to the beneficiary address. + +#### Parameters + +| Name | Type | Description | +| ----- | ------- | ------------------------------------ | +| token | address | Address of the token being released. | + +### BENEFICIARY + +```solidity +address BENEFICIARY +``` + +Beneficiary address. + +### DURATION + +```solidity +uint128 DURATION +``` + +Duration (in seconds). + +### END_TIMESTAMP + +```solidity +uint128 END_TIMESTAMP +``` + +End timestamp. + +### START_TIMESTAMP + +```solidity +uint128 START_TIMESTAMP +``` + +Start timestamp. + +### \_EUINT64_ZERO + +```solidity +euint64 _EUINT64_ZERO +``` + +Constant for zero using TFHE. + +_Since it is expensive to compute 0, it is stored instead._ + +### \_amountReleased + +```solidity +mapping(address => euint64) _amountReleased +``` + +Total encrypted amount released (to the beneficiary). + +### constructor + +```solidity +constructor(address beneficiary_, uint128 startTimestamp_, uint128 duration_) internal +``` + +#### Parameters + +| Name | Type | Description | +| ---------------- | ------- | ---------------------- | +| beneficiary\_ | address | Beneficiary address. | +| startTimestamp\_ | uint128 | Start timestamp. | +| duration\_ | uint128 | Duration (in seconds). | + +### release + +```solidity +function release(address token) public virtual +``` + +Release the tokens that have already vested. + +_Anyone can call this function but the beneficiary receives the tokens._ + +### released + +```solidity +function released(address token) public view virtual returns (euint64 amountReleased) +``` + +Return the encrypted amount of total tokens released. + +_It is only reencryptable by the owner._ + +#### Return Values + +| Name | Type | Description | +| -------------- | ------- | -------------------------------- | +| amountReleased | euint64 | Total amount of tokens released. | + +### \_releasable + +```solidity +function _releasable(address token) internal virtual returns (euint64 releasableAmount) +``` + +Calculate the amount of tokens that can be released. + +#### Return Values + +| Name | Type | Description | +| ---------------- | ------- | ------------------ | +| releasableAmount | euint64 | Releasable amount. | + +### \_vestedAmount + +```solidity +function _vestedAmount(address token, uint128 timestamp) internal virtual returns (euint64 vestedAmount) +``` + +Calculate the amount of tokens that has already vested. + +#### Parameters + +| Name | Type | Description | +| --------- | ------- | ------------------ | +| token | address | | +| timestamp | uint128 | Current timestamp. | + +#### Return Values + +| Name | Type | Description | +| ------------ | ------- | -------------- | +| vestedAmount | euint64 | Vested amount. | + +### \_vestingSchedule + +```solidity +function _vestingSchedule(euint64 totalAllocation, uint128 timestamp) internal virtual returns (euint64 vestedAmount) +``` + +Return the vested amount based on a linear vesting schedule. + +_It must be overriden for non-linear schedules._ + +#### Parameters + +| Name | Type | Description | +| --------------- | ------- | -------------------------------- | +| totalAllocation | euint64 | Total allocation that is vested. | +| timestamp | uint128 | Current timestamp. | + +#### Return Values + +| Name | Type | Description | +| ------------ | ------- | -------------- | +| vestedAmount | euint64 | Vested amount. | diff --git a/docs/finance/ConfidentialVestingWalletCliff.md b/docs/finance/ConfidentialVestingWalletCliff.md new file mode 100644 index 0000000..9b62909 --- /dev/null +++ b/docs/finance/ConfidentialVestingWalletCliff.md @@ -0,0 +1,60 @@ +## ConfidentialVestingWalletCliff + +This contract offers a simple vesting wallet with a cliff for [ConfidentialERC20](../token/ERC20/IConfidentialERC20.md) +tokens. This is based on the +[VestingWalletCliff.sol contract written by OpenZeppelin](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/release-v5.1/contracts/finance/VestingWalletCliff.sol). + +_This implementation is a linear vesting curve with a cliff. To use with the native asset, it is necessary to wrap the +native asset to a ConfidentialERC20-like token._ + +### InvalidCliffDuration + +```solidity +error InvalidCliffDuration(uint128 cliffSeconds, uint128 durationSeconds) +``` + +Returned if the cliff duration is greater than the vesting duration. + +### CLIFF + +```solidity +uint128 CLIFF +``` + +Cliff timestamp. + +### constructor + +```solidity +constructor(address beneficiary_, uint128 startTimestamp_, uint128 duration_, uint128 cliffSeconds_) internal +``` + +#### Parameters + +| Name | Type | Description | +| ---------------- | ------- | ---------------------- | +| beneficiary\_ | address | Beneficiary address. | +| startTimestamp\_ | uint128 | Start timestamp. | +| duration\_ | uint128 | Duration (in seconds). | +| cliffSeconds\_ | uint128 | Cliff (in seconds). | + +### \_vestingSchedule + +```solidity +function _vestingSchedule(euint64 totalAllocation, uint128 timestamp) internal virtual returns (euint64) +``` + +Return the vested amount based on a linear vesting schedule with a cliff. + +#### Parameters + +| Name | Type | Description | +| --------------- | ------- | -------------------------------- | +| totalAllocation | euint64 | Total allocation that is vested. | +| timestamp | uint128 | Current timestamp. | + +#### Return Values + +| Name | Type | Description | +| ------------ | ------- | -------------- | +| vestedAmount | euint64 | Vested amount. | diff --git a/docs/governance/CompoundTimelock.md b/docs/governance/CompoundTimelock.md index 78e1d3c..d82c341 100644 --- a/docs/governance/CompoundTimelock.md +++ b/docs/governance/CompoundTimelock.md @@ -1,11 +1,11 @@ -# CompoundTimelock +## CompoundTimelock This contract allows the admin to set a delay period before executing transactions. Transactions must be queued before execution. No transaction can be executed during this period, which offers time to verify the validity of pending transactions. It also has a grace period to allow for transactions not to be executed after a specific period following the queuing. -## GRACE_PERIOD +### GRACE_PERIOD ```solidity uint256 GRACE_PERIOD @@ -13,7 +13,7 @@ uint256 GRACE_PERIOD See {ICompoundTimelock-GRACE_PERIOD}. -## MINIMUM_DELAY +### MINIMUM_DELAY ```solidity uint256 MINIMUM_DELAY @@ -21,7 +21,7 @@ uint256 MINIMUM_DELAY Minimum delay that can be set in the `setDelay` function. -## MAXIMUM_DELAY +### MAXIMUM_DELAY ```solidity uint256 MAXIMUM_DELAY @@ -29,7 +29,7 @@ uint256 MAXIMUM_DELAY Maximum delay that can be set in the `setDelay` function. -## admin +### admin ```solidity address admin @@ -37,7 +37,7 @@ address admin Admin address. -## pendingAdmin +### pendingAdmin ```solidity address pendingAdmin @@ -47,7 +47,7 @@ Pending admin address. _The transer of the admin is a two-step process._ -## delay +### delay ```solidity uint256 delay @@ -55,7 +55,7 @@ uint256 delay See {ICompoundTimelock-delay}. -## queuedTransactions +### queuedTransactions ```solidity mapping(bytes32 => bool) queuedTransactions @@ -63,26 +63,26 @@ mapping(bytes32 => bool) queuedTransactions Return whether the transaction is queued based on its hash. -## constructor +### constructor ```solidity constructor(address admin_, uint256 delay_) public ``` -### Parameters +#### Parameters | Name | Type | Description | | ------- | ------- | --------------------- | | admin\_ | address | Admin address. | | delay\_ | uint256 | Delay (in timestamp). | -## receive +### receive ```solidity receive() external payable ``` -## setDelay +### setDelay ```solidity function setDelay(uint256 delay_) public @@ -92,13 +92,13 @@ Set the delay. _This transaction must be queued._ -### Parameters +#### Parameters | Name | Type | Description | | ------- | ------- | --------------------- | | delay\_ | uint256 | Delay (in timestamp). | -## acceptAdmin +### acceptAdmin ```solidity function acceptAdmin() public @@ -106,7 +106,7 @@ function acceptAdmin() public See {ICompoundTimelock-acceptAdmin}. -## setPendingAdmin +### setPendingAdmin ```solidity function setPendingAdmin(address pendingAdmin_) public @@ -116,13 +116,13 @@ Set the pending admin. _This transaction must be queued._ -### Parameters +#### Parameters | Name | Type | Description | | -------------- | ------- | ---------------------- | | pendingAdmin\_ | address | Pending admin address. | -## queueTransaction +### queueTransaction ```solidity function queueTransaction(address target, uint256 value, string signature, bytes data, uint256 eta) public returns (bytes32) @@ -130,7 +130,7 @@ function queueTransaction(address target, uint256 value, string signature, bytes See {ICompoundTimelock-queueTransaction}. -## cancelTransaction +### cancelTransaction ```solidity function cancelTransaction(address target, uint256 value, string signature, bytes data, uint256 eta) public @@ -138,7 +138,7 @@ function cancelTransaction(address target, uint256 value, string signature, byte See {ICompoundTimelock-cancelTransaction}. -## executeTransaction +### executeTransaction ```solidity function executeTransaction(address target, uint256 value, string signature, bytes data, uint256 eta) public payable returns (bytes) diff --git a/docs/governance/ConfidentialERC20Votes.md b/docs/governance/ConfidentialERC20Votes.md index 9e27aaf..55d3bf1 100644 --- a/docs/governance/ConfidentialERC20Votes.md +++ b/docs/governance/ConfidentialERC20Votes.md @@ -1,13 +1,14 @@ # ConfidentialERC20Votes -This contract inherits ConfidentialERC20, EIP712, and Ownable2Step. This is based on the Comp.sol contract written by -Compound Labs. see: compound-finance/compound-protocol/blob/master/contracts/Governance/Comp.sol. It is a governance -token used to delegate votes, which can be used by contracts such as ConfidentialGovernorAlpha.sol. It uses encrypted -votes to delegate the voting power associated with an account's balance. +This contract inherits [ConfidentialERC20](../token/ERC20/ConfidentialERC20.md), EIP712, and Ownable2Step. This is based +on the +[Comp.sol contract written by Compound Labs](https://github.com/compound-finance/compound-protocol/blob/master/contracts/Governance/Comp.sol). +It is a governance token used to delegate votes, which can be used by contracts such as ConfidentialGovernorAlpha. It +uses encrypted votes to delegate the voting power associated with an account's balance. _The delegation of votes leaks information about the account's encrypted balance to the `delegatee`._ -## BlockNumberEqualOrHigherThanCurrentBlock +### BlockNumberEqualOrHigherThanCurrentBlock ```solidity error BlockNumberEqualOrHigherThanCurrentBlock() @@ -17,7 +18,7 @@ Returned if the `blockNumber` is higher or equal to the (current) `block.number` _It is returned in requests to access votes._ -## GovernorInvalid +### GovernorInvalid ```solidity error GovernorInvalid() @@ -25,7 +26,7 @@ error GovernorInvalid() Returned if the `msg.sender` is not the `governor` contract. -## SignatureExpired +### SignatureExpired ```solidity error SignatureExpired() @@ -33,7 +34,7 @@ error SignatureExpired() Returned if the signature has expired. -## SignatureNonceInvalid +### SignatureNonceInvalid ```solidity error SignatureNonceInvalid() @@ -41,7 +42,7 @@ error SignatureNonceInvalid() Returned if the signature's nonce is invalid. -## SignatureVerificationFail +### SignatureVerificationFail ```solidity error SignatureVerificationFail() @@ -51,7 +52,7 @@ Returned if the signature's verification has failed. _See {SignatureChecker} for potential reasons._ -## DelegateChanged +### DelegateChanged ```solidity event DelegateChanged(address delegator, address fromDelegate, address toDelegate) @@ -59,15 +60,7 @@ event DelegateChanged(address delegator, address fromDelegate, address toDelegat Emitted when an `account` (i.e. `delegator`) changes its delegate. -## DelegateVotesChanged - -```solidity -event DelegateVotesChanged(address delegate) -``` - -Emitted when a `delegate` account's vote balance changes. - -## NewGovernor +### NewGovernor ```solidity event NewGovernor(address governor) @@ -77,7 +70,7 @@ Emitted when the governor contract that can reencrypt votes changes. _WARNING: it can be set to a malicious contract, which could reencrypt all user votes._ -## NonceIncremented +### NonceIncremented ```solidity event NonceIncremented(address account, uint256 newNonce) @@ -85,19 +78,17 @@ event NonceIncremented(address account, uint256 newNonce) Emitted when the account cancels a signature. -## Checkpoint +### Checkpoint A checkpoint for marking number of votes from a given block. _In Compound's implementation, `fromBlock` is defined as uint32 to allow tight-packing. However, in this implementations `votes` is uint256-based. `fromBlock`'s type is set to uint256, which simplifies the codebase._ -### Parameters +#### Parameters -| Name | Type | Description | -| --------- | ------- | -------------------------------------------- | -| fromBlock | uint256 | Block from where the checkpoint applies. | -| votes | euint64 | Total number of votes for the account power. | +| Name | Type | Description | +| ---- | ---- | ----------- | ```solidity struct Checkpoint { @@ -106,7 +97,7 @@ struct Checkpoint { } ``` -## DELEGATION_TYPEHASH +### DELEGATION_TYPEHASH ```solidity bytes32 DELEGATION_TYPEHASH @@ -114,7 +105,7 @@ bytes32 DELEGATION_TYPEHASH The EIP-712 typehash for the `Delegation` struct. -## governor +### governor ```solidity address governor @@ -124,7 +115,7 @@ The smart contract that can access encrypted votes. _The contract is expected to be a governor contract._ -## delegates +### delegates ```solidity mapping(address => address) delegates @@ -132,7 +123,7 @@ mapping(address => address) delegates A record of each account's `delegate`. -## nonces +### nonces ```solidity mapping(address => uint256) nonces @@ -140,7 +131,7 @@ mapping(address => uint256) nonces A record of states for signing/validating signatures. -## numCheckpoints +### numCheckpoints ```solidity mapping(address => uint32) numCheckpoints @@ -148,7 +139,7 @@ mapping(address => uint32) numCheckpoints The number of checkpoints for an `account`. -## \_checkpoints +### \_checkpoints ```solidity mapping(address => mapping(uint32 => struct ConfidentialERC20Votes.Checkpoint)) _checkpoints @@ -156,13 +147,13 @@ mapping(address => mapping(uint32 => struct ConfidentialERC20Votes.Checkpoint)) A record of votes \_checkpoints for an `account` using incremental indices. -## constructor +### constructor ```solidity constructor(address owner_, string name_, string symbol_, string version_, uint64 totalSupply_) internal ``` -### Parameters +#### Parameters | Name | Type | Description | | ------------- | ------- | ---------------------------- | @@ -172,7 +163,7 @@ constructor(address owner_, string name_, string symbol_, string version_, uint6 | version\_ | string | Version (e.g. "0.1", "1.0"). | | totalSupply\_ | uint64 | Total supply to mint. | -## delegate +### delegate ```solidity function delegate(address delegatee) public virtual @@ -180,13 +171,13 @@ function delegate(address delegatee) public virtual Delegate votes from `msg.sender` to `delegatee`. -### Parameters +#### Parameters | Name | Type | Description | | --------- | ------- | --------------------------------- | | delegatee | address | The address to delegate votes to. | -## delegateBySig +### delegateBySig ```solidity function delegateBySig(address delegator, address delegatee, uint256 nonce, uint256 expiry, bytes signature) public virtual @@ -197,7 +188,7 @@ Delegate votes from signatory to `delegatee`. _Signature can be either 64-byte or 65-byte long if it is from an EOA. Else, it must adhere to ERC1271. See {https://eips.ethereum.org/EIPS/eip-1271}_ -### Parameters +#### Parameters | Name | Type | Description | | --------- | ------- | ------------------------------------------------------------ | @@ -207,7 +198,7 @@ _Signature can be either 64-byte or 65-byte long if it is from an EOA. Else, it | expiry | uint256 | The time at which to expire the signature. | | signature | bytes | The signature. | -## incrementNonce +### incrementNonce ```solidity function incrementNonce() public virtual @@ -217,7 +208,7 @@ Increment the nonce. _This function enables the sender to cancel a signature._ -## getPriorVotesForGovernor +### getPriorVotesForGovernor ```solidity function getPriorVotesForGovernor(address account, uint256 blockNumber) public virtual returns (euint64 votes) @@ -225,7 +216,7 @@ function getPriorVotesForGovernor(address account, uint256 blockNumber) public v See {IConfidentialERC20Votes-getPriorVotesForGovernor}. -## getCurrentVotes +### getCurrentVotes ```solidity function getCurrentVotes(address account) public view virtual returns (euint64 votes) @@ -233,19 +224,19 @@ function getCurrentVotes(address account) public view virtual returns (euint64 v Get current votes of account. -### Parameters +#### Parameters | Name | Type | Description | | ------- | ------- | --------------- | | account | address | Account address | -### Return Values +#### Return Values | Name | Type | Description | | ----- | ------- | -------------------------- | | votes | euint64 | Current (encrypted) votes. | -## getPriorVotes +### getPriorVotes ```solidity function getPriorVotes(address account, uint256 blockNumber) public view virtual returns (euint64 votes) @@ -255,20 +246,20 @@ Get the prior number of votes for an account as of a block number. _Block number must be a finalized block or else this function will revert._ -### Parameters +#### Parameters | Name | Type | Description | | ----------- | ------- | -------------------------------------------- | | account | address | Account address. | | blockNumber | uint256 | The block number to get the vote balance at. | -### Return Values +#### Return Values | Name | Type | Description | | ----- | ------- | -------------------------------------------------- | | votes | euint64 | Number of votes the account as of the given block. | -## setGovernor +### setGovernor ```solidity function setGovernor(address newGovernor) public virtual @@ -276,31 +267,31 @@ function setGovernor(address newGovernor) public virtual Set a governor contract. -### Parameters +#### Parameters | Name | Type | Description | | ----------- | ------- | ------------------------------------------------------ | | newGovernor | address | New governor contract that can reencrypt/access votes. | -## \_delegate +### \_delegate ```solidity function _delegate(address delegator, address delegatee) internal virtual ``` -## \_getPriorVote +### \_getPriorVote ```solidity -function _getPriorVote(address account, uint256 blockNumber) internal view returns (euint64 votes) +function _getPriorVote(address account, uint256 blockNumber) internal view virtual returns (euint64 votes) ``` -## \_moveDelegates +### \_moveDelegates ```solidity function _moveDelegates(address srcRep, address dstRep, euint64 amount) internal virtual ``` -## \_transfer +### \_transfer ```solidity function _transfer(address from, address to, euint64 amount, ebool isTransferable) internal virtual @@ -308,7 +299,7 @@ function _transfer(address from, address to, euint64 amount, ebool isTransferabl _Original restrictions to transfer from/to address(0) are removed since they are inherited._ -## \_writeCheckpoint +### \_writeCheckpoint ```solidity function _writeCheckpoint(address delegatee, uint32 nCheckpoints, euint64 newVotes) internal virtual diff --git a/docs/governance/ConfidentialGovernorAlpha.md b/docs/governance/ConfidentialGovernorAlpha.md index 3d853b2..3c63a40 100644 --- a/docs/governance/ConfidentialGovernorAlpha.md +++ b/docs/governance/ConfidentialGovernorAlpha.md @@ -1,15 +1,16 @@ -# ConfidentialGovernorAlpha +## ConfidentialGovernorAlpha -This is based on the GovernorAlpha.sol contract written by Compound Labs. see: -compound-finance/compound-protocol/blob/master/contracts/Governance/GovernorAlpha.sol This decentralized governance -system allows users to propose and vote on changes to the protocol. The contract is responsible for: +This is based on the GovernorAlpha.sol contract written by Compound Labs. This decentralized governance system allows +users to propose and vote on changes to the protocol. -- Proposal: A new proposal is made to introduce a change. -- Voting: Users can vote on the proposal, either in favor or against it. -- Quorum: A minimum number of votes (quorum) must be reached for the proposal to pass. -- Execution: Once a proposal passes, it is executed and takes effect on the protocol. +The contract is responsible for: -## LengthAboveMaxOperations +- **Proposal**: A new proposal is made to introduce a change. +- **Voting**: Users can vote on the proposal, either in favor or against it. +- **Quorum**: A minimum number of votes (quorum) must be reached for the proposal to pass. +- **Execution**: Once a proposal passes, it is executed and takes effect on the protocol. + +### LengthAboveMaxOperations ```solidity error LengthAboveMaxOperations() @@ -17,7 +18,7 @@ error LengthAboveMaxOperations() Returned if proposal contains too many changes. -## LengthIsNull +### LengthIsNull ```solidity error LengthIsNull() @@ -25,7 +26,7 @@ error LengthIsNull() Returned if the array length is equal to 0. -## LengthsDoNotMatch +### LengthsDoNotMatch ```solidity error LengthsDoNotMatch() @@ -33,7 +34,15 @@ error LengthsDoNotMatch() Returned if array lengths are not equal. -## ProposalActionsAlreadyQueued +### MaxDecryptionDelayTooHigh + +```solidity +error MaxDecryptionDelayTooHigh() +``` + +Returned if the maximum decryption delay is higher than 1 day. + +### ProposalActionsAlreadyQueued ```solidity error ProposalActionsAlreadyQueued() @@ -41,7 +50,7 @@ error ProposalActionsAlreadyQueued() Returned if proposal's actions have already been queued. -## ProposalStateInvalid +### ProposalStateInvalid ```solidity error ProposalStateInvalid() @@ -51,7 +60,7 @@ Returned if the proposal state is invalid for this operation. _It is returned for any proposal state not matching the expected state to conduct the operation._ -## ProposalStateNotActive +### ProposalStateNotActive ```solidity error ProposalStateNotActive() @@ -59,7 +68,7 @@ error ProposalStateNotActive() Returned if the proposal's state is active but `block.number` > `endBlock`. -## ProposalStateStillActive +### ProposalStateStillActive ```solidity error ProposalStateStillActive() @@ -67,7 +76,7 @@ error ProposalStateStillActive() Returned if the proposal state is still active. -## ProposerHasAnotherProposal +### ProposerHasAnotherProposal ```solidity error ProposerHasAnotherProposal() @@ -75,7 +84,7 @@ error ProposerHasAnotherProposal() Returned if the proposer has another proposal in progress. -## VoterHasAlreadyVoted +### VoterHasAlreadyVoted ```solidity error VoterHasAlreadyVoted() @@ -83,7 +92,7 @@ error VoterHasAlreadyVoted() Returned if the voter has already cast a vote for this proposal. -## ProposalActive +### ProposalActive ```solidity event ProposalActive(uint256 id) @@ -91,7 +100,7 @@ event ProposalActive(uint256 id) Emitted when a proposal is now active. -## ProposalCanceled +### ProposalCanceled ```solidity event ProposalCanceled(uint256 id) @@ -99,7 +108,7 @@ event ProposalCanceled(uint256 id) Emitted when a proposal has been canceled. -## ProposalCreated +### ProposalCreated ```solidity event ProposalCreated(uint256 id, address proposer, address[] targets, uint256[] values, string[] signatures, bytes[] calldatas, uint256 startBlock, uint256 endBlock, string description) @@ -107,15 +116,16 @@ event ProposalCreated(uint256 id, address proposer, address[] targets, uint256[] Emitted when a new proposal is created. -## ProposalDefeated +### ProposalDefeated ```solidity event ProposalDefeated(uint256 id) ``` -Emitted when a proposal is defeated either by lack of votes or by more votes against. +Emitted when a proposal is defeated either by (1) number of `for` votes inferior to the quorum, (2) the number of `for` +votes equal or inferior to `against` votes. -## ProposalExecuted +### ProposalExecuted ```solidity event ProposalExecuted(uint256 id) @@ -123,7 +133,7 @@ event ProposalExecuted(uint256 id) Emitted when a proposal has been executed in the Timelock. -## ProposalQueued +### ProposalQueued ```solidity event ProposalQueued(uint256 id, uint256 eta) @@ -131,23 +141,25 @@ event ProposalQueued(uint256 id, uint256 eta) Emitted when a proposal has been queued in the Timelock. -## ProposalRejected +### ProposalRejected ```solidity event ProposalRejected(uint256 id) ``` -Emitted when a proposal has been rejected since the number of votes is lower than the required threshold. +Emitted when a proposal has been rejected since the number of votes of the proposer is lower than the required +threshold. -## ProposalSucceeded +### ProposalSucceeded ```solidity event ProposalSucceeded(uint256 id) ``` -Emitted when a proposal has been rejected since the number of votes is lower than the required threshold. +Emitted when a proposal has succeeded since the number of `for` votes is higher than quorum and strictly higher than +`against` votes. -## VoteCast +### VoteCast ```solidity event VoteCast(address voter, uint256 proposalId) @@ -155,25 +167,14 @@ event VoteCast(address voter, uint256 proposalId) Emitted when a vote has been cast on a proposal. -## ProposalState +### ProposalState Possible states that a proposal may be in. -### Parameters +#### Parameters -| Name | Description | -| ---------------------------- | ------------------------------------------------------------------------------------------- | -| Pending | Proposal does not exist. | -| PendingThresholdVerification | Proposal is created but token threshold verification is pending. | -| Rejected | Proposal was rejected as the proposer did not meet the token threshold. | -| Active | Proposal is active and voters can cast their votes. | -| PendingResults | Proposal is not active and the result decryption is in progress. | -| Canceled | Proposal has been canceled by the proposer or by this contract's owner. | -| Defeated | Proposal has been defeated (either not reaching the quorum or `againstVotes` > `forVotes`). | -| Succeeded | Proposal has succeeded (`forVotes` > `againstVotes`). | -| Queued | Proposal has been queued in the `Timelock`. | -| Expired | Proposal has expired (@dev This state exists only in read-only functions). | -| Executed | Proposal has been executed in the `Timelock`. | +| Name | Type | Description | +| ---- | ---- | ----------- | ```solidity enum ProposalState { @@ -191,25 +192,12 @@ enum ProposalState { } ``` -## Proposal +### Proposal -### Parameters +#### Parameters -| Name | Type | Description | -| --------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| proposer | address | Proposal creator. | -| state | ConfidentialGovernorAlpha.ProposalState | State of the proposal. | -| eta | uint256 | The timestamp that the proposal will be available for execution, it is set automatically once the vote succeeds. | -| targets | address[] | The ordered list of target addresses for calls to be made. | -| values | uint256[] | The ordered list of values (i.e. `msg.value`) to be passed to the calls to be made. | -| signatures | string[] | The ordered list of function signatures to be called. | -| calldatas | calldatas | The ordered list of calldata to be passed to each call. | -| startBlock | startBlock | The block at which voting begins: holders must delegate their votes prior to this block. | -| endBlock | endBlock | The block at which voting ends: votes must be cast prior to this block. ----------- | -| forVotes | forVotes | Current encrypted number of votes for to this proposal.----------- | -| againstVotes | againstVotes | Current encrypted number of votes in opposition to this proposal.----------- | -| forVotesDecrypted | forVotesDecrypted | For votes once decrypted by the gateway.----------- | -| againstVotesDecrypted | againstVotesDecrypted | Against votes once decrypted by the gateway.----------- | +| Name | Type | Description | +| ---- | ---- | ----------- | ```solidity struct Proposal { @@ -229,23 +217,12 @@ struct Proposal { } ``` -## ProposalInfo +### ProposalInfo -### Parameters +#### Parameters -| Name | Type | Description | -| ------------ | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| proposer | address | Proposal creator. | -| state | ConfidentialGovernorAlpha.ProposalState | State of the proposal. | -| eta | uint256 | The timestamp that the proposal will be available for execution, it is set automatically once the vote succeeds. | -| targets | address[] | The ordered list of target addresses for calls to be made. | -| values | uint256[] | The ordered list of values (i.e. `msg.value`) to be passed to the calls to be made. | -| signatures | string[] | The ordered list of function signatures to be called. | -| calldatas | calldatas | The ordered list of calldata to be passed to each call. | -| startBlock | startBlock | The block at which voting begins: holders must delegate their votes prior to this block. | -| endBlock | endBlock | The block at which voting ends: votes must be cast prior to this block. ----------- | -| forVotes | forVotesDecrypted | For votes once decrypted by the gateway.----------- | -| againstVotes | againstVotesDecrypted | Against votes once decrypted by the gateway.----------- | +| Name | Type | Description | +| ---- | ---- | ----------- | ```solidity struct ProposalInfo { @@ -263,17 +240,14 @@ struct ProposalInfo { } ``` -## Receipt +### Receipt Ballot receipt record for a voter. -### Parameters +#### Parameters -| Name | Type | Description | -| -------- | ------- | ----------------------------------------------- | -| hasVoted | bool | Whether or not a vote has been cast. | -| support | ebool | Whether or not the voter supports the proposal. | -| support | euint64 | The number of votes cast by the voter. | +| Name | Type | Description | +| ---- | ---- | ----------- | ```solidity struct Receipt { @@ -283,7 +257,7 @@ struct Receipt { } ``` -## PROPOSAL_MAX_OPERATIONS +### PROPOSAL_MAX_OPERATIONS ```solidity uint256 PROPOSAL_MAX_OPERATIONS @@ -293,7 +267,7 @@ The maximum number of actions that can be included in a proposal. _It is 10 actions per proposal._ -## PROPOSAL_THRESHOLD +### PROPOSAL_THRESHOLD ```solidity uint256 PROPOSAL_THRESHOLD @@ -303,7 +277,7 @@ The number of votes required for a voter to become a proposer. _It is set at 100,000, which is 1% of the total supply of the ConfidentialERC20Votes token._ -## QUORUM_VOTES +### QUORUM_VOTES ```solidity uint64 QUORUM_VOTES @@ -313,7 +287,7 @@ The number of votes in support of a proposal required in order for a quorum to b _It is set at 400,000, which is 4% of the total supply of the ConfidentialERC20Votes token._ -## VOTING_DELAY +### VOTING_DELAY ```solidity uint256 VOTING_DELAY @@ -321,7 +295,15 @@ uint256 VOTING_DELAY The delay before voting on a proposal may take place once proposed. It is 1 block. -## VOTING_PERIOD +### MAX_DECRYPTION_DELAY + +```solidity +uint256 MAX_DECRYPTION_DELAY +``` + +The maximum decryption delay for the Gateway to callback with the decrypted value. + +### VOTING_PERIOD ```solidity uint256 VOTING_PERIOD @@ -331,7 +313,7 @@ The duration of voting on a proposal, in blocks _It is recommended to be set at 3 days in blocks (i.e 21,600 for 12-second blocks)._ -## CONFIDENTIAL_ERC20_VOTES +### CONFIDENTIAL_ERC20_VOTES ```solidity contract IConfidentialERC20Votes CONFIDENTIAL_ERC20_VOTES @@ -339,7 +321,7 @@ contract IConfidentialERC20Votes CONFIDENTIAL_ERC20_VOTES ConfidentialERC20Votes governance token. -## TIMELOCK +### TIMELOCK ```solidity contract ICompoundTimelock TIMELOCK @@ -347,7 +329,7 @@ contract ICompoundTimelock TIMELOCK Compound Timelock. -## proposalCount +### proposalCount ```solidity uint256 proposalCount @@ -355,7 +337,7 @@ uint256 proposalCount The total number of proposals made. It includes all proposals, including the ones that were rejected/canceled/defeated. -## latestProposalIds +### latestProposalIds ```solidity mapping(address => uint256) latestProposalIds @@ -363,7 +345,7 @@ mapping(address => uint256) latestProposalIds The latest proposal for each proposer. -## \_accountReceiptForProposalId +### \_accountReceiptForProposalId ```solidity mapping(uint256 => mapping(address => struct ConfidentialGovernorAlpha.Receipt)) _accountReceiptForProposalId @@ -371,7 +353,7 @@ mapping(uint256 => mapping(address => struct ConfidentialGovernorAlpha.Receipt)) Ballot receipt for an account for a proposal id. -## \_proposals +### \_proposals ```solidity mapping(uint256 => struct ConfidentialGovernorAlpha.Proposal) _proposals @@ -379,7 +361,7 @@ mapping(uint256 => struct ConfidentialGovernorAlpha.Proposal) _proposals The official record of all proposals that have been created. -## \_requestIdToProposalId +### \_requestIdToProposalId ```solidity mapping(uint256 => uint256) _requestIdToProposalId @@ -389,25 +371,29 @@ Returns the proposal id associated with the request id from the Gateway. _This mapping is used for decryption._ -## constructor +### constructor ```solidity -constructor(address owner_, address timelock_, address confidentialERC20Votes_, uint256 votingPeriod_) internal +constructor(address owner_, address timelock_, address confidentialERC20Votes_, uint256 votingPeriod_, uint256 maxDecryptionDelay_) internal ``` -_Do not use a small value in production such as 5 or 20 to avoid security issues unless for testing purpose. It should -by at least a few days,. For instance, 3 days would have a votingPeriod = 21,600 blocks if 12s per block._ +_Do not use a small value in production such as 5 or 20 to avoid security issues unless for testing purposes. It should +by at least a few days. For instance, 3 days would have a votingPeriod = 21,600 blocks if 12s per block. Do not use a +small value in production to avoid security issues if the response cannot be processed because the block time is higher +than the delay. The current implementation expects the Gateway to always return a decrypted value within the delay +specified, as long as it is sufficient enough._ -### Parameters +#### Parameters -| Name | Type | Description | -| ------------------------ | ------- | ----------------------------- | -| owner\_ | address | Owner address. | -| timelock\_ | address | Timelock contract. | -| confidentialERC20Votes\_ | address | ConfidentialERC20Votes token. | -| votingPeriod\_ | uint256 | Voting period. | +| Name | Type | Description | +| ------------------------ | ------- | ----------------------------------------- | +| owner\_ | address | Owner address. | +| timelock\_ | address | Timelock contract. | +| confidentialERC20Votes\_ | address | ConfidentialERC20Votes token. | +| votingPeriod\_ | uint256 | Voting period. | +| maxDecryptionDelay\_ | uint256 | Maximum delay for the Gateway to decrypt. | -## cancel +### cancel ```solidity function cancel(uint256 proposalId) public virtual @@ -418,13 +404,13 @@ Cancel the proposal. _Only this contract's owner or the proposer can cancel. In the original GovernorAlpha, the proposer can cancel only if her votes are still above the threshold._ -### Parameters +#### Parameters | Name | Type | Description | | ---------- | ------- | ------------ | | proposalId | uint256 | Proposal id. | -## castVote +### castVote ```solidity function castVote(uint256 proposalId, einput value, bytes inputProof) public virtual @@ -432,7 +418,7 @@ function castVote(uint256 proposalId, einput value, bytes inputProof) public vir Cast a vote. -### Parameters +#### Parameters | Name | Type | Description | | ---------- | ------- | ---------------- | @@ -440,7 +426,7 @@ Cast a vote. | value | einput | Encrypted value. | | inputProof | bytes | Input proof. | -## castVote +### castVote ```solidity function castVote(uint256 proposalId, ebool support) public virtual @@ -448,14 +434,14 @@ function castVote(uint256 proposalId, ebool support) public virtual Cast a vote. -### Parameters +#### Parameters | Name | Type | Description | | ---------- | ------- | ------------------------------------------------------- | | proposalId | uint256 | Proposal id. | | support | ebool | Support (true ==> `forVotes`, false ==> `againstVotes`) | -## execute +### execute ```solidity function execute(uint256 proposalId) public payable virtual @@ -465,7 +451,7 @@ Execute the proposal id. _Anyone can execute a proposal once it has been queued and the delay in the timelock is sufficient._ -## propose +### propose ```solidity function propose(address[] targets, uint256[] values, string[] signatures, bytes[] calldatas, string description) public virtual returns (uint256 proposalId) @@ -473,7 +459,7 @@ function propose(address[] targets, uint256[] values, string[] signatures, bytes Start a new proposal. -### Parameters +#### Parameters | Name | Type | Description | | ----------- | --------- | --------------------------------------- | @@ -483,13 +469,13 @@ Start a new proposal. | calldatas | bytes[] | Calldatas. | | description | string | Plain text description of the proposal. | -### Return Values +#### Return Values | Name | Type | Description | | ---------- | ------- | ------------ | | proposalId | uint256 | Proposal id. | -## queue +### queue ```solidity function queue(uint256 proposalId) public virtual @@ -499,13 +485,13 @@ Queue a new proposal. _It can be done only if the proposal has succeeded. Anyone can queue a proposal._ -### Parameters +#### Parameters | Name | Type | Description | | ---------- | ------- | ------------ | | proposalId | uint256 | Proposal id. | -## requestVoteDecryption +### requestVoteDecryption ```solidity function requestVoteDecryption(uint256 proposalId) public virtual @@ -515,13 +501,13 @@ Request the vote results to be decrypted. _Anyone can request the decryption of the vote._ -### Parameters +#### Parameters | Name | Type | Description | | ---------- | ------- | ------------ | | proposalId | uint256 | Proposal id. | -## callbackInitiateProposal +### callbackInitiateProposal ```solidity function callbackInitiateProposal(uint256 requestId, bool canInitiate) public virtual @@ -529,14 +515,14 @@ function callbackInitiateProposal(uint256 requestId, bool canInitiate) public vi _Only callable by the gateway._ -### Parameters +#### Parameters | Name | Type | Description | | ----------- | ------- | -------------------------------------- | | requestId | uint256 | Request id (from the Gateway) | | canInitiate | bool | Whether the proposal can be initiated. | -## callbackVoteDecryption +### callbackVoteDecryption ```solidity function callbackVoteDecryption(uint256 requestId, uint256 forVotesDecrypted, uint256 againstVotesDecrypted) public virtual @@ -544,7 +530,7 @@ function callbackVoteDecryption(uint256 requestId, uint256 forVotesDecrypted, ui _Only callable by the gateway. If `forVotesDecrypted` == `againstVotesDecrypted`, proposal is defeated._ -### Parameters +#### Parameters | Name | Type | Description | | --------------------- | ------- | -------------- | @@ -552,7 +538,7 @@ _Only callable by the gateway. If `forVotesDecrypted` == `againstVotesDecrypted` | forVotesDecrypted | uint256 | For votes. | | againstVotesDecrypted | uint256 | Against votes. | -## acceptTimelockAdmin +### acceptTimelockAdmin ```solidity function acceptTimelockAdmin() public virtual @@ -560,7 +546,7 @@ function acceptTimelockAdmin() public virtual _Only callable by `owner`._ -## executeSetTimelockPendingAdmin +### executeSetTimelockPendingAdmin ```solidity function executeSetTimelockPendingAdmin(address newPendingAdmin, uint256 eta) public virtual @@ -568,14 +554,14 @@ function executeSetTimelockPendingAdmin(address newPendingAdmin, uint256 eta) pu _Only callable by `owner`._ -### Parameters +#### Parameters | Name | Type | Description | | --------------- | ------- | -------------------------------------------------- | | newPendingAdmin | address | Address of the new pending admin for the timelock. | | eta | uint256 | Eta for executing the transaction in the timelock. | -## queueSetTimelockPendingAdmin +### queueSetTimelockPendingAdmin ```solidity function queueSetTimelockPendingAdmin(address newPendingAdmin, uint256 eta) public virtual @@ -583,14 +569,14 @@ function queueSetTimelockPendingAdmin(address newPendingAdmin, uint256 eta) publ _Only callable by `owner`._ -### Parameters +#### Parameters | Name | Type | Description | | --------------- | ------- | -------------------------------------------------- | | newPendingAdmin | address | Address of the new pending admin for the timelock. | | eta | uint256 | Eta for queuing the transaction in the timelock. | -## getProposalInfo +### getProposalInfo ```solidity function getProposalInfo(uint256 proposalId) public view virtual returns (struct ConfidentialGovernorAlpha.ProposalInfo proposalInfo) @@ -600,19 +586,19 @@ Returns proposal information for a proposal id. _It returns decrypted `forVotes`/`againstVotes`. These are only available after the decryption._ -### Parameters +#### Parameters | Name | Type | Description | | ---------- | ------- | ------------ | | proposalId | uint256 | Proposal id. | -### Return Values +#### Return Values | Name | Type | Description | | ------------ | --------------------------------------------- | --------------------- | | proposalInfo | struct ConfidentialGovernorAlpha.ProposalInfo | Proposal information. | -## getReceipt +### getReceipt ```solidity function getReceipt(uint256 proposalId, address account) public view virtual returns (bool, ebool, euint64) @@ -620,28 +606,28 @@ function getReceipt(uint256 proposalId, address account) public view virtual ret Returns the vote receipt information for the account for a proposal id. -### Parameters +#### Parameters | Name | Type | Description | | ---------- | ------- | ---------------- | | proposalId | uint256 | Proposal id. | | account | address | Account address. | -### Return Values +#### Return Values -| Name | Type | Description | -| ---- | ------- | -------------------------------------------------------------------------------- | -| [0] | bool | hasVoted Whether the account has voted. | -| [1] | ebool | support The support for the account (true ==> vote for, false ==> vote against). | -| [2] | euint64 | votes The number of votes cast. | +| Name | Type | Description | +| -------- | ------- | ------------------------------------------------------------------------ | +| hasVoted | bool | Whether the account has voted. | +| support | ebool | The support for the account (true ==> vote for, false ==> vote against). | +| votes | euint64 | The number of votes cast. | -## \_castVote +### \_castVote ```solidity function _castVote(address voter, uint256 proposalId, ebool support) internal virtual ``` -## \_queueOrRevert +### \_queueOrRevert ```solidity function _queueOrRevert(address target, uint256 value, string signature, bytes data, uint256 eta) internal virtual diff --git a/docs/governance/ICompoundTimelock.md b/docs/governance/ICompoundTimelock.md index 8c2414a..9bb6a94 100644 --- a/docs/governance/ICompoundTimelock.md +++ b/docs/governance/ICompoundTimelock.md @@ -1,5 +1,7 @@ ## ICompoundTimelock +_The CompoundTimelock inherits this interface._ + ### DelayBelowMinimumDelay ```solidity diff --git a/docs/governance/IConfidentialERC20Votes.md b/docs/governance/IConfidentialERC20Votes.md index e1e3262..e719734 100644 --- a/docs/governance/IConfidentialERC20Votes.md +++ b/docs/governance/IConfidentialERC20Votes.md @@ -1,8 +1,8 @@ -# IConfidentialERC20Votes +## IConfidentialERC20Votes -_The ConfidentialGovernorAlpha relies on this interface._ +_Governor contracts use this interface to build a logic using votes._ -## getPriorVotesForGovernor +### getPriorVotesForGovernor ```solidity function getPriorVotesForGovernor(address account, uint256 blockNumber) external returns (euint64 votes) @@ -13,14 +13,14 @@ Determine the prior number of votes for an account as of a block number. _Block number must be a finalized block or else this function will revert. This function can change the state since the governor needs access in the ACL contract._ -### Parameters +#### Parameters | Name | Type | Description | | ----------- | ------- | -------------------------------------------- | | account | address | Account address. | | blockNumber | uint256 | The block number to get the vote balance at. | -### Return Values +#### Return Values | Name | Type | Description | | ----- | ------- | --------------------------------------------------------- | diff --git a/docs/token/ERC20/ConfidentialERC20.md b/docs/token/ERC20/ConfidentialERC20.md index 2ec08e3..cfef3fc 100644 --- a/docs/token/ERC20/ConfidentialERC20.md +++ b/docs/token/ERC20/ConfidentialERC20.md @@ -1,4 +1,4 @@ -# ConfidentialERC20 +## ConfidentialERC20 This contract implements an encrypted ERC20-like token with confidential balances using Zama's FHE (Fully Homomorphic Encryption) library. @@ -6,7 +6,15 @@ Encryption) library. _It supports standard ERC20 functions such as transferring tokens, minting, and setting allowances, but uses encrypted data types. The total supply is not encrypted._ -## \_totalSupply +### \_PLACEHOLDER + +```solidity +uint256 _PLACEHOLDER +``` + +Used as a placeholder in `Approval` & `Transfer` events to comply with the official EIP20. + +### \_totalSupply ```solidity uint64 _totalSupply @@ -14,7 +22,7 @@ uint64 _totalSupply Total supply. -## \_name +### \_name ```solidity string _name @@ -22,7 +30,7 @@ string _name Name. -## \_symbol +### \_symbol ```solidity string _symbol @@ -30,7 +38,7 @@ string _symbol Symbol. -## \_balances +### \_balances ```solidity mapping(address => euint64) _balances @@ -38,7 +46,7 @@ mapping(address => euint64) _balances A mapping from `account` address to an encrypted `balance`. -## \_allowances +### \_allowances ```solidity mapping(address => mapping(address => euint64)) _allowances @@ -46,28 +54,20 @@ mapping(address => mapping(address => euint64)) _allowances A mapping of the form mapping(account => mapping(spender => allowance)). -## TFHESenderNotAllowed - -```solidity -error TFHESenderNotAllowed() -``` - -Error when the `sender` is not allowed to access a value. - -## constructor +### constructor ```solidity constructor(string name_, string symbol_) internal ``` -### Parameters +#### Parameters | Name | Type | Description | | -------- | ------ | ------------------ | | name\_ | string | Name of the token. | | symbol\_ | string | Symbol. | -## approve +### approve ```solidity function approve(address spender, einput encryptedAmount, bytes inputProof) public virtual returns (bool) @@ -75,7 +75,7 @@ function approve(address spender, einput encryptedAmount, bytes inputProof) publ See {IConfidentialERC20-approve}. -## approve +### approve ```solidity function approve(address spender, euint64 amount) public virtual returns (bool) @@ -83,7 +83,7 @@ function approve(address spender, euint64 amount) public virtual returns (bool) See {IConfidentialERC20-approve}. -## transfer +### transfer ```solidity function transfer(address to, einput encryptedAmount, bytes inputProof) public virtual returns (bool) @@ -91,7 +91,7 @@ function transfer(address to, einput encryptedAmount, bytes inputProof) public v See {IConfidentialERC20-transfer}. -## transfer +### transfer ```solidity function transfer(address to, euint64 amount) public virtual returns (bool) @@ -99,7 +99,7 @@ function transfer(address to, euint64 amount) public virtual returns (bool) See {IConfidentialERC20-transfer}. -## transferFrom +### transferFrom ```solidity function transferFrom(address from, address to, einput encryptedAmount, bytes inputProof) public virtual returns (bool) @@ -107,7 +107,7 @@ function transferFrom(address from, address to, einput encryptedAmount, bytes in See {IConfidentialERC20-transferFrom}. -## transferFrom +### transferFrom ```solidity function transferFrom(address from, address to, euint64 amount) public virtual returns (bool) @@ -115,7 +115,7 @@ function transferFrom(address from, address to, euint64 amount) public virtual r See {IConfidentialERC20-transferFrom}. -## allowance +### allowance ```solidity function allowance(address owner, address spender) public view virtual returns (euint64) @@ -123,7 +123,7 @@ function allowance(address owner, address spender) public view virtual returns ( See {IConfidentialERC20-allowance}. -## balanceOf +### balanceOf ```solidity function balanceOf(address account) public view virtual returns (euint64) @@ -131,7 +131,7 @@ function balanceOf(address account) public view virtual returns (euint64) See {IConfidentialERC20-balanceOf}. -## decimals +### decimals ```solidity function decimals() public view virtual returns (uint8) @@ -139,7 +139,7 @@ function decimals() public view virtual returns (uint8) See {IConfidentialERC20-decimals}. -## name +### name ```solidity function name() public view virtual returns (string) @@ -147,7 +147,7 @@ function name() public view virtual returns (string) See {IConfidentialERC20-name}. -## symbol +### symbol ```solidity function symbol() public view virtual returns (string) @@ -155,7 +155,7 @@ function symbol() public view virtual returns (string) See {IConfidentialERC20-symbol}. -## totalSupply +### totalSupply ```solidity function totalSupply() public view virtual returns (uint64) @@ -163,45 +163,53 @@ function totalSupply() public view virtual returns (uint64) See {IConfidentialERC20-totalSupply}. -## \_approve +### \_approve ```solidity function _approve(address owner, address spender, euint64 amount) internal virtual ``` -## \_unsafeMint +### \_unsafeMint + +```solidity +function _unsafeMint(address account, uint64 amount) internal virtual +``` + +_It does not incorporate any overflow check. It must be implemented by the function calling it._ + +### \_unsafeMintNoEvent ```solidity -function _unsafeMint(address account, euint64 amount) internal virtual +function _unsafeMintNoEvent(address account, uint64 amount) internal virtual ``` _It does not incorporate any overflow check. It must be implemented by the function calling it._ -## \_transfer +### \_transfer ```solidity function _transfer(address from, address to, euint64 amount, ebool isTransferable) internal virtual ``` -## \_transferNoEvent +### \_transferNoEvent ```solidity function _transferNoEvent(address from, address to, euint64 amount, ebool isTransferable) internal virtual ``` -## \_updateAllowance +### \_updateAllowance ```solidity function _updateAllowance(address owner, address spender, euint64 amount) internal virtual returns (ebool) ``` -## \_allowance +### \_allowance ```solidity function _allowance(address owner, address spender) internal view virtual returns (euint64) ``` -## \_isSenderAllowedForAmount +### \_isSenderAllowedForAmount ```solidity function _isSenderAllowedForAmount(euint64 amount) internal view virtual diff --git a/docs/token/ERC20/ConfidentialERC20Wrapped.md b/docs/token/ERC20/ConfidentialERC20Wrapped.md new file mode 100644 index 0000000..8281b1a --- /dev/null +++ b/docs/token/ERC20/ConfidentialERC20Wrapped.md @@ -0,0 +1,118 @@ +## ConfidentialERC20Wrapped + +This contract allows users to wrap/unwrap trustlessly ERC20 tokens to [ConfidentialERC20](./IConfidentialERC20.md) +tokens. + +_This implementation does not support tokens with rebase functions or tokens with a fee on transfer. All ERC20 tokens +must have decimals superior or equal to 6 decimals._ + +### MaxDecryptionDelayTooHigh + +```solidity +error MaxDecryptionDelayTooHigh() +``` + +Returned if the maximum decryption delay is higher than 1 day. + +### ERC20_TOKEN + +```solidity +contract IERC20Metadata ERC20_TOKEN +``` + +ERC20 token that is wrapped. + +### isAccountRestricted + +```solidity +mapping(address => bool) isAccountRestricted +``` + +Tracks whether the account can move funds. + +### unwrapRequests + +```solidity +mapping(uint256 => struct IConfidentialERC20Wrapped.UnwrapRequest) unwrapRequests +``` + +Tracks the unwrap request to a unique request id. + +### constructor + +```solidity +constructor(address erc20_, uint256 maxDecryptionDelay_) internal +``` + +_The name/symbol are autogenerated. For instance, "Wrapped Ether" --> "Confidential Wrapped Ether" "WETH" --> "WETHc". +Do not use a small value in production to avoid security issues if the response cannot be processed because the block +time is higher than the delay. The current implementation expects the Gateway to always return a decrypted value within +the delay specified, as long as it is sufficient enough._ + +#### Parameters + +| Name | Type | Description | +| -------------------- | ------- | ------------------------------------------ | +| erc20\_ | address | Address of the ERC20 token to wrap/unwrap. | +| maxDecryptionDelay\_ | uint256 | Maximum delay for the Gateway to decrypt. | + +### unwrap + +```solidity +function unwrap(uint64 amount) public virtual +``` + +Unwrap ConfidentialERC20 tokens to standard ERC20 tokens. + +#### Parameters + +| Name | Type | Description | +| ------ | ------ | ----------------- | +| amount | uint64 | Amount to unwrap. | + +### wrap + +```solidity +function wrap(uint256 amount) public virtual +``` + +Wrap ERC20 tokens to an encrypted format. + +#### Parameters + +| Name | Type | Description | +| ------ | ------- | --------------- | +| amount | uint256 | Amount to wrap. | + +### callbackUnwrap + +```solidity +function callbackUnwrap(uint256 requestId, bool canUnwrap) public virtual +``` + +Callback function for the gateway. + +#### Parameters + +| Name | Type | Description | +| --------- | ------- | ---------------------------- | +| requestId | uint256 | Request id. | +| canUnwrap | bool | Whether it can be unwrapped. | + +### \_canTransferOrUnwrap + +```solidity +function _canTransferOrUnwrap(address account) internal virtual +``` + +### \_transferNoEvent + +```solidity +function _transferNoEvent(address from, address to, euint64 amount, ebool isTransferable) internal virtual +``` + +### \_unsafeBurn + +```solidity +function _unsafeBurn(address account, uint64 amount) internal +``` diff --git a/docs/token/ERC20/ConfidentialWETH.md b/docs/token/ERC20/ConfidentialWETH.md new file mode 100644 index 0000000..b748fa0 --- /dev/null +++ b/docs/token/ERC20/ConfidentialWETH.md @@ -0,0 +1,117 @@ +## ConfidentialWETH + +This contract allows users to wrap/unwrap trustlessly ETH (or other native tokens) to +[ConfidentialERC20](./IConfidentialERC20.md) tokens. + +### ETHTransferFail + +```solidity +error ETHTransferFail() +``` + +Returned if ETH transfer fails. + +### MaxDecryptionDelayTooHigh + +```solidity +error MaxDecryptionDelayTooHigh() +``` + +Returned if the maximum decryption delay is higher than 1 day. + +### isAccountRestricted + +```solidity +mapping(address => bool) isAccountRestricted +``` + +Tracks whether the account can move funds. + +### unwrapRequests + +```solidity +mapping(uint256 => struct IConfidentialERC20Wrapped.UnwrapRequest) unwrapRequests +``` + +Tracks the unwrap request to a unique request id. + +### constructor + +```solidity +constructor(uint256 maxDecryptionDelay_) internal +``` + +Deposit/withdraw ethers (or other native tokens). + +_The name/symbol are autogenerated. Do not use a small value in production to avoid security issues if the response +cannot be processed because the block time is higher than the delay. The current implementation expects the Gateway to +always return a decrypted value within the delay specified, as long as it is sufficient enough._ + +#### Parameters + +| Name | Type | Description | +| -------------------- | ------- | ----------------------------------------- | +| maxDecryptionDelay\_ | uint256 | Maximum delay for the Gateway to decrypt. | + +### receive + +```solidity +receive() external payable +``` + +Receive function calls wrap(). + +### unwrap + +```solidity +function unwrap(uint64 amount) public virtual +``` + +Unwrap ConfidentialERC20 tokens to ether (or other native tokens). + +#### Parameters + +| Name | Type | Description | +| ------ | ------ | ----------------- | +| amount | uint64 | Amount to unwrap. | + +### wrap + +```solidity +function wrap() public payable virtual +``` + +Wrap ether (or other native token) to an encrypted format. + +### callbackUnwrap + +```solidity +function callbackUnwrap(uint256 requestId, bool canUnwrap) public virtual +``` + +Callback function for the gateway. + +#### Parameters + +| Name | Type | Description | +| --------- | ------- | ---------------------------- | +| requestId | uint256 | Request id. | +| canUnwrap | bool | Whether it can be unwrapped. | + +### \_canTransferOrUnwrap + +```solidity +function _canTransferOrUnwrap(address account) internal virtual +``` + +### \_transferNoEvent + +```solidity +function _transferNoEvent(address from, address to, euint64 amount, ebool isTransferable) internal virtual +``` + +### \_unsafeBurn + +```solidity +function _unsafeBurn(address account, uint64 amount) internal +``` diff --git a/docs/token/ERC20/IConfidentialERC20.md b/docs/token/ERC20/IConfidentialERC20.md index 04c8f56..7dd7ea3 100644 --- a/docs/token/ERC20/IConfidentialERC20.md +++ b/docs/token/ERC20/IConfidentialERC20.md @@ -1,131 +1,263 @@ -# IConfidentialERC20 +## IConfidentialERC20 Interface that defines ERC20-like tokens with encrypted balances. -## Approval +### Approval ```solidity -event Approval(address owner, address spender) +event Approval(address owner, address spender, uint256 placeholder) ``` Emitted when the allowance of a `spender` for an `owner` is set by a call to {approve}. -## Transfer +#### Parameters + +| Name | Type | Description | +| ----------- | ------- | ---------------- | +| owner | address | Owner address. | +| spender | address | Spender address. | +| placeholder | uint256 | Placeholder. | + +### Transfer ```solidity -event Transfer(address from, address to) +event Transfer(address from, address to, uint256 errorId) ``` Emitted when tokens are moved from one account (`from`) to another (`to`). -## ReceiverAddressNull - -```solidity -error ReceiverAddressNull() -``` +#### Parameters -Returned when receiver is address(0). +| Name | Type | Description | +| ---------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| from | address | Sender address. | +| to | address | Receiver address. | +| transferId | uint256 | If the implementation does not support error handling, it must be set to a default placeholder (typically equal to max(uint256). However, it must be set to a transferId if the implementation supports encrypted error handling. | -## SenderAddressNull +### approve ```solidity -error SenderAddressNull() +function approve(address spender, einput encryptedAmount, bytes inputProof) external returns (bool) ``` -Returned when sender is address(0). +Set the `encryptedAmount` as the allowance of `spender` over the caller's tokens. -## approve +#### Parameters -```solidity -function approve(address spender, einput encryptedAmount, bytes inputProof) external returns (bool) -``` +| Name | Type | Description | +| --------------- | ------- | ----------------- | +| spender | address | Spender address. | +| encryptedAmount | einput | Encrypted amount. | +| inputProof | bytes | Input proof. | -Sets the `encryptedAmount` as the allowance of `spender` over the caller's tokens. +#### Return Values -## approve +| Name | Type | Description | +| --------- | ---- | -------------------- | +| isSuccess | bool | Whether it succeeds. | + +### approve ```solidity function approve(address spender, euint64 amount) external returns (bool) ``` -Sets the `amount` as the allowance of `spender` over the caller's tokens. +Set the `amount` as the allowance of `spender` over the caller's tokens. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | ----------------- | +| spender | address | Spender address. | +| amount | euint64 | Encrypted amount. | -## transfer +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ------------------------------ | +| [0] | bool | isSuccess Whether it succeeds. | + +### transfer ```solidity function transfer(address to, einput encryptedAmount, bytes inputProof) external returns (bool) ``` -Transfers an encrypted amount from the message sender address to the `to` address. +Transfer an encrypted amount from the message sender address to the `to` address. + +#### Parameters + +| Name | Type | Description | +| --------------- | ------- | ----------------- | +| to | address | Receiver address. | +| encryptedAmount | einput | Encrypted amount. | +| inputProof | bytes | Input proof. | + +#### Return Values + +| Name | Type | Description | +| --------- | ---- | -------------------- | +| isSuccess | bool | Whether it succeeds. | -## transfer +### transfer ```solidity function transfer(address to, euint64 amount) external returns (bool) ``` -Transfers an amount from the message sender address to the `to` address. +Transfer an amount from the message sender address to the `to` address. -## transferFrom +#### Parameters + +| Name | Type | Description | +| ------ | ------- | ----------------- | +| to | address | Receiver address. | +| amount | euint64 | Encrypted amount. | + +#### Return Values + +| Name | Type | Description | +| --------- | ---- | -------------------- | +| isSuccess | bool | Whether it succeeds. | + +### transferFrom ```solidity function transferFrom(address from, address to, euint64 amount) external returns (bool) ``` -Transfers `amount` tokens using the caller's allowance. +Transfer `amount` tokens using the caller's allowance. + +#### Parameters -## transferFrom +| Name | Type | Description | +| ------ | ------- | ----------------- | +| from | address | Sender address. | +| to | address | Receiver address. | +| amount | euint64 | Encrypted amount. | + +#### Return Values + +| Name | Type | Description | +| --------- | ---- | -------------------- | +| isSuccess | bool | Whether it succeeds. | + +### transferFrom ```solidity function transferFrom(address from, address to, einput encryptedAmount, bytes inputProof) external returns (bool) ``` -Transfers `encryptedAmount` tokens using the caller's allowance. +Transfer `encryptedAmount` tokens using the caller's allowance. + +#### Parameters + +| Name | Type | Description | +| --------------- | ------- | ----------------- | +| from | address | Sender address. | +| to | address | Receiver address. | +| encryptedAmount | einput | Encrypted amount. | +| inputProof | bytes | Input proof. | + +#### Return Values -## allowance +| Name | Type | Description | +| --------- | ---- | -------------------- | +| isSuccess | bool | Whether it succeeds. | + +### allowance ```solidity function allowance(address owner, address spender) external view returns (euint64) ``` -Returns the remaining number of tokens that `spender` is allowed to spend on behalf of the caller. +Return the remaining number of tokens that `spender` is allowed to spend on behalf of the `owner`. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | ---------------- | +| owner | address | Owner address. | +| spender | address | Spender address. | -## balanceOf +#### Return Values + +| Name | Type | Description | +| --------- | ------- | ------------------------------------------------------- | +| allowance | euint64 | Allowance handle of the spender on behalf of the owner. | + +### balanceOf ```solidity -function balanceOf(address wallet) external view returns (euint64) +function balanceOf(address account) external view returns (euint64) ``` -Returns the balance handle of the caller. +Return the balance handle of the `account`. + +#### Parameters -## decimals +| Name | Type | Description | +| ------- | ------- | ---------------- | +| account | address | Account address. | + +#### Return Values + +| Name | Type | Description | +| ------- | ------- | -------------------------------- | +| balance | euint64 | Balance handle of the `account`. | + +### decimals ```solidity function decimals() external view returns (uint8) ``` -Returns the number of decimals. +Return the number of decimals. -## name +#### Return Values + +| Name | Type | Description | +| -------- | ----- | ---------------------------- | +| decimals | uint8 | Number of decimals (e.g. 6). | + +### name ```solidity function name() external view returns (string) ``` -Returns the name of the token. +Return the name of the token. + +#### Return Values -## symbol +| Name | Type | Description | +| ---- | ------ | ------------------------------------- | +| name | string | Name of the token (e.g. "TestToken"). | + +### symbol ```solidity function symbol() external view returns (string) ``` -Returns the symbol of the token, usually a shorter version of the name. +Return the symbol of the token. + +#### Return Values + +| Name | Type | Description | +| ------ | ------ | ---------------------------------- | +| symbol | string | Symbol of the token (e.g. "TEST"). | -## totalSupply +### totalSupply ```solidity function totalSupply() external view returns (uint64) ``` -Returns the total supply of the token. +Return the total supply of the token. + +#### Return Values + +| Name | Type | Description | +| ----------- | ------ | -------------------------- | +| totalSupply | uint64 | Total supply of the token. | diff --git a/docs/token/ERC20/IConfidentialERC20Wrapped.md b/docs/token/ERC20/IConfidentialERC20Wrapped.md new file mode 100644 index 0000000..5ceeeaf --- /dev/null +++ b/docs/token/ERC20/IConfidentialERC20Wrapped.md @@ -0,0 +1,95 @@ +## IConfidentialERC20Wrapped + +Interface that defines events, errors, and structs for contracts that wrap native assets or ERC20 tokens. + +### AmountTooHigh + +```solidity +error AmountTooHigh() +``` + +Returned if the amount is greater than 2\*\*64. + +### CannotTransferOrUnwrap + +```solidity +error CannotTransferOrUnwrap() +``` + +Returned if user cannot transfer or mint. + +### Unwrap + +```solidity +event Unwrap(address account, uint64 amount) +``` + +Emitted when token is unwrapped. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | ------------------------------------------- | +| account | address | Address of the account that unwraps tokens. | +| amount | uint64 | Amount to unwrap. | + +### UnwrapFailNotEnoughBalance + +```solidity +event UnwrapFailNotEnoughBalance(address account, uint64 amount) +``` + +Emitted if unwrap fails due to lack of funds. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | -------------------------------------------- | +| account | address | Address of the account that tried to unwrap. | +| amount | uint64 | Amount to unwrap. | + +### UnwrapFailTransferFail + +```solidity +event UnwrapFailTransferFail(address account, uint64 amount) +``` + +Emitted if unwrap fails due to fail transfer. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | -------------------------------------------- | +| account | address | Address of the account that tried to unwrap. | +| amount | uint64 | Amount to unwrap. | + +### Wrap + +```solidity +event Wrap(address account, uint64 amount) +``` + +Emitted when token is wrapped. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | ----------------------------------------- | +| account | address | Address of the account that wraps tokens. | +| amount | uint64 | Amount to wrap. | + +### UnwrapRequest + +This struct keeps track of the unwrap request information. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | + +```solidity +struct UnwrapRequest { + address account; + uint64 amount; +} +``` diff --git a/docs/token/ERC20/extensions/ConfidentialERC20Mintable.md b/docs/token/ERC20/extensions/ConfidentialERC20Mintable.md index 33fcf96..492d9bb 100644 --- a/docs/token/ERC20/extensions/ConfidentialERC20Mintable.md +++ b/docs/token/ERC20/extensions/ConfidentialERC20Mintable.md @@ -1,10 +1,10 @@ -# ConfidentialERC20Mintable +## ConfidentialERC20Mintable -This contract inherits ConfidentialERC20. +This contract inherits [ConfidentialERC20](../ConfidentialERC20.md). -_It allows an owner to mint tokens. Mint amounts are public._ +_It allows an owner to mint tokens. Mint amounts are not encrypted._ -## Mint +### Mint ```solidity event Mint(address to, uint64 amount) @@ -12,13 +12,13 @@ event Mint(address to, uint64 amount) Emitted when `amount` tokens are minted to one account (`to`). -## constructor +### constructor ```solidity constructor(string name_, string symbol_, address owner_) internal ``` -### Parameters +#### Parameters | Name | Type | Description | | -------- | ------- | ------------------ | @@ -26,16 +26,17 @@ constructor(string name_, string symbol_, address owner_) internal | symbol\_ | string | Symbol. | | owner\_ | address | Owner address. | -## mint +### mint ```solidity -function mint(uint64 amount) public virtual +function mint(address to, uint64 amount) public virtual ``` Mint tokens. -### Parameters +#### Parameters -| Name | Type | Description | -| ------ | ------ | ------------------------- | -| amount | uint64 | Amount of tokens to mint. | +| Name | Type | Description | +| ------ | ------- | -------------------------- | +| to | address | Address to mint tokens to. | +| amount | uint64 | Amount of tokens to mint. | diff --git a/docs/token/ERC20/extensions/ConfidentialERC20WithErrors.md b/docs/token/ERC20/extensions/ConfidentialERC20WithErrors.md index 55a095a..8643974 100644 --- a/docs/token/ERC20/extensions/ConfidentialERC20WithErrors.md +++ b/docs/token/ERC20/extensions/ConfidentialERC20WithErrors.md @@ -1,28 +1,18 @@ -# ConfidentialERC20WithErrors +## ConfidentialERC20WithErrors This contract implements an encrypted ERC20-like token with confidential balances using Zama's FHE (Fully Homomorphic Encryption) library. -It supports standard ERC20 functions such as transferring tokens, minting, and setting allowances, but uses encrypted -data types. The total supply is not encrypted. It also supports error handling for encrypted errors. +_It supports standard ERC20 functions such as transferring tokens, minting, and setting allowances, but uses encrypted +data types. The total supply is not encrypted. It also supports error handling for encrypted errors._ -## TransferWithErrorHandling - -```solidity -event TransferWithErrorHandling(address from, address to, uint256 transferId) -``` - -Emitted when tokens are moved from one account (`from`) to another (`to`). - -## ErrorCodes +### ErrorCodes Error codes allow tracking (in the storage) whether a transfer worked. -| Name | Description | -| --------------------- | ------------------------------------------------------------------------------------------------ | -| NO_ERROR | The transfer worked as expected. | -| UNSUFFICIENT_BALANCE | The transfer failed because the from balances were strictly inferior to the amount to transfer. | -| UNSUFFICIENT_APPROVAL | The transfer failed because the sender allowance was strictly lower than the amount to transfer. | +\_NO_ERROR: the transfer worked as expected. UNSUFFICIENT_BALANCE: the transfer failed because the from balances were +strictly inferior to the amount to transfer. UNSUFFICIENT_APPROVAL: the transfer failed because the sender allowance +wasstrictly lower than the amount to transfer. ```solidity enum ErrorCodes { @@ -32,28 +22,20 @@ enum ErrorCodes { } ``` -## \_errorCodeForTransferId - -```solidity -mapping(uint256 => euint8) _errorCodeForTransferId -``` - -A mapping from transferId to the error code. - -## constructor +### constructor ```solidity constructor(string name_, string symbol_) internal ``` -### Parameters +#### Parameters | Name | Type | Description | | -------- | ------ | ------------------ | | name\_ | string | Name of the token. | | symbol\_ | string | Symbol. | -## transfer +### transfer ```solidity function transfer(address to, euint64 amount) public virtual returns (bool) @@ -61,7 +43,7 @@ function transfer(address to, euint64 amount) public virtual returns (bool) See {IConfidentialERC20-transfer}. -## transferFrom +### transferFrom ```solidity function transferFrom(address from, address to, euint64 amount) public virtual returns (bool) @@ -69,22 +51,34 @@ function transferFrom(address from, address to, euint64 amount) public virtual r See {IConfidentialERC20-transferFrom}. -## getErrorCodeForTransferId +### getErrorCodeForTransferId ```solidity function getErrorCodeForTransferId(uint256 transferId) public view virtual returns (euint8 errorCode) ``` -Returns the error code corresponding to `transferId`. +Return the error for a transfer id. + +#### Parameters + +| Name | Type | Description | +| ---------- | ------- | ------------------------------------------------------ | +| transferId | uint256 | Transfer id. It can be read from the `Transfer` event. | + +#### Return Values + +| Name | Type | Description | +| --------- | ------ | --------------------- | +| errorCode | euint8 | Encrypted error code. | -## \_transferWithErrorCode +### \_transfer ```solidity -function _transferWithErrorCode(address from, address to, euint64 amount, ebool isTransferable, euint8 errorCode) internal virtual +function _transfer(address from, address to, euint64 amount, ebool isTransferable) internal ``` -## \_updateAllowanceWithErrorCode +### \_updateAllowance ```solidity -function _updateAllowanceWithErrorCode(address owner, address spender, euint64 amount) internal virtual returns (ebool isTransferable, euint8 errorCode) +function _updateAllowance(address owner, address spender, euint64 amount) internal virtual returns (ebool isTransferable) ``` diff --git a/docs/token/ERC20/extensions/ConfidentialERC20WithErrorsMintable.md b/docs/token/ERC20/extensions/ConfidentialERC20WithErrorsMintable.md index d576929..2c1205a 100644 --- a/docs/token/ERC20/extensions/ConfidentialERC20WithErrorsMintable.md +++ b/docs/token/ERC20/extensions/ConfidentialERC20WithErrorsMintable.md @@ -1,10 +1,10 @@ -# ConfidentialERC20WithErrorsMintable +## ConfidentialERC20WithErrorsMintable -This contract inherits ConfidentialERC20WithErrors. +This contract inherits [ConfidentialERC20WithErrors](./ConfidentialERC20WithErrors.md). _It allows an owner to mint tokens. Mint amounts are public._ -## Mint +### Mint ```solidity event Mint(address to, uint64 amount) @@ -12,13 +12,13 @@ event Mint(address to, uint64 amount) Emitted when `amount` tokens are minted to one account (`to`). -## constructor +### constructor ```solidity constructor(string name_, string symbol_, address owner_) internal ``` -### Parameters +#### Parameters | Name | Type | Description | | -------- | ------- | ------------------ | @@ -26,16 +26,17 @@ constructor(string name_, string symbol_, address owner_) internal | symbol\_ | string | Symbol. | | owner\_ | address | Owner address. | -## mint +### mint ```solidity -function mint(uint64 amount) public virtual +function mint(address to, uint64 amount) public virtual ``` Mint tokens. -### Parameters +#### Parameters -| Name | Type | Description | -| ------ | ------ | ------------------------- | -| amount | uint64 | Amount of tokens to mint. | +| Name | Type | Description | +| ------ | ------- | -------------------------- | +| to | address | Address to mint tokens to. | +| amount | uint64 | Amount of tokens to mint. | diff --git a/docs/utils/EncryptedErrors.md b/docs/utils/EncryptedErrors.md index 0b92d73..7c6e36c 100644 --- a/docs/utils/EncryptedErrors.md +++ b/docs/utils/EncryptedErrors.md @@ -1,56 +1,235 @@ -## EncryptedErrors +# EncryptedErrors This abstract contract is used for error handling in the fhEVM. Error codes are encrypted in the constructor inside the -`errorCodes` mapping. +`_errorCodeDefinitions` mapping. -_`errorCodes[0]` should always refer to the `NO_ERROR` code, by default._ +_`_errorCodeDefinitions[0]` should always refer to the `NO_ERROR` code, by default._ -### TotalNumberErrorsEqualToZero +### ErrorIndexInvalid ```solidity -error TotalNumberErrorsEqualToZero() +error ErrorIndexInvalid() ``` -The total number of errors is equal to zero. +Returned if the error index is invalid. -### \_errorCodes +### ErrorIndexIsNull ```solidity -mapping(uint8 => euint8) _errorCodes +error ErrorIndexIsNull() ``` -Mapping of error codes. +Returned if the error index is null. -_It does not use arrays they are more expensive than mappings._ +### TotalNumberErrorCodesEqualToZero + +```solidity +error TotalNumberErrorCodesEqualToZero() +``` + +Returned if the total number of errors is equal to zero. ### constructor ```solidity -constructor(uint8 totalNumberErrors_) internal +constructor(uint8 totalNumberErrorCodes_) internal +``` + +Sets the non-null value for `_TOTAL_NUMBER_ERROR_CODES` corresponding to the total number of errors. + +_`totalNumberErrorCodes_` must be non-null (`_errorCodeDefinitions[0]`corresponds to the`NO_ERROR` +code)._ + +#### Parameters + +| Name | Type | Description | +| ----------------------- | ----- | --------------------------------- | +| totalNumberErrorCodes\_ | uint8 | Total number of different errors. | + +### \_errorChangeIf + +```solidity +function _errorChangeIf(ebool condition, uint8 indexCode, euint8 errorCode) internal virtual returns (euint8 newErrorCode) ``` -Sets the non-null value for `numErrors` corresponding to the total number of errors. +Computes an encrypted error code, result will be either a reencryption of `_errorCodeDefinitions[indexCode]` if +`condition` is an encrypted `true` or of `errorCode` otherwise. -_`numErrors` must be non-null (`errorCodes[0]` corresponds to the `NO_ERROR` code)._ +_` indexCode` must be below the total number of error codes._ #### Parameters -| Name | Type | Description | -| ------------------- | ----- | --------------------------------- | -| totalNumberErrors\_ | uint8 | total number of different errors. | +| Name | Type | Description | +| --------- | ------ | --------------------------------------------------- | +| condition | ebool | Encrypted boolean used in the select operator. | +| indexCode | uint8 | | +| errorCode | euint8 | Selected error code if `condition` encrypts `true`. | + +#### Return Values + +| Name | Type | Description | +| ------------ | ------ | ---------------------------------------------------------- | +| newErrorCode | euint8 | New reencrypted error code depending on `condition` value. | -### getTotalNumberErrors +### \_errorChangeIfNot ```solidity -function getTotalNumberErrors() external view returns (uint8 totalNumberErrors) +function _errorChangeIfNot(ebool condition, uint8 indexCode, euint8 errorCode) internal virtual returns (euint8 newErrorCode) ``` -Returns the total number of errors. +Does the opposite of `changeErrorIf`, i.e result will be either a reencryption of `_errorCodeDefinitions[indexCode]` if +`condition` is an encrypted `false` or of `errorCode` otherwise. + +_`indexCode` must be below the total number of error codes._ + +#### Parameters + +| Name | Type | Description | +| --------- | ------ | -------------------------------------------------------- | +| condition | ebool | The encrypted boolean used in the `TFHE.select`. | +| indexCode | uint8 | | +| errorCode | euint8 | The selected error code if `condition` encrypts `false`. | + +#### Return Values + +| Name | Type | Description | +| ------------ | ------ | ---------------------------------------------- | +| newErrorCode | euint8 | New error code depending on `condition` value. | + +### \_errorDefineIf + +```solidity +function _errorDefineIf(ebool condition, uint8 indexCode) internal virtual returns (euint8 errorCode) +``` + +Computes an encrypted error code, result will be either a reencryption of `_errorCodeDefinitions[indexCode]` if +`condition` is an encrypted `true` or of `NO_ERROR` otherwise. + +_`indexCode` must be non-null and below the total number of defined error codes._ + +#### Parameters + +| Name | Type | Description | +| --------- | ----- | ---------------------------------------------------------------- | +| condition | ebool | Encrypted boolean used in the select operator. | +| indexCode | uint8 | Index of the selected error code if `condition` encrypts `true`. | + +#### Return Values + +| Name | Type | Description | +| --------- | ------ | ------------------------------------------------------ | +| errorCode | euint8 | Reencrypted error code depending on `condition` value. | + +### \_errorDefineIfNot + +```solidity +function _errorDefineIfNot(ebool condition, uint8 indexCode) internal virtual returns (euint8 errorCode) +``` + +Does the opposite of `defineErrorIf`, i.e result will be either a reencryption of `_errorCodeDefinitions[indexCode]` if +`condition` is an encrypted `false` or of `NO_ERROR` otherwise. + +_`indexCode` must be non-null and below the total number of defined error codes._ + +#### Parameters + +| Name | Type | Description | +| --------- | ----- | ----------------------------------------------------------------- | +| condition | ebool | Encrypted boolean used in the select operator. | +| indexCode | uint8 | Index of the selected error code if `condition` encrypts `false`. | + +#### Return Values + +| Name | Type | Description | +| --------- | ------ | ------------------------------------------------------ | +| errorCode | euint8 | Reencrypted error code depending on `condition` value. | + +### \_errorSave + +```solidity +function _errorSave(euint8 errorCode) internal virtual returns (uint256 errorId) +``` + +Saves `errorCode` in storage, in the `_errorCodesEmitted` mapping. + +#### Parameters + +| Name | Type | Description | +| --------- | ------ | -------------------------------------------- | +| errorCode | euint8 | Encrypted error code to be saved in storage. | + +#### Return Values + +| Name | Type | Description | +| ------- | ------- | ---------------------------------------------------------------------- | +| errorId | uint256 | The `errorId` key in `_errorCodesEmitted` where `errorCode` is stored. | + +### \_errorGetCodeDefinition + +```solidity +function _errorGetCodeDefinition(uint8 indexCodeDefinition) internal view virtual returns (euint8 errorCode) +``` + +Returns the trivially encrypted error code at index `indexCodeDefinition`. + +#### Parameters + +| Name | Type | Description | +| ------------------- | ----- | --------------------------------------------- | +| indexCodeDefinition | uint8 | Index of the requested error code definition. | + +#### Return Values + +| Name | Type | Description | +| --------- | ------ | --------------------------------------------------------------------------------- | +| errorCode | euint8 | Encrypted error code located at `indexCodeDefinition` in `_errorCodeDefinitions`. | + +### \_errorGetCodeEmitted + +```solidity +function _errorGetCodeEmitted(uint256 errorId) internal view virtual returns (euint8 errorCode) +``` + +Returns the encrypted error code which was stored in `_errorCodesEmitted` at key `errorId`. + +_`errorId` must be a valid id, i.e below the error counter._ + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | --------------------------------------------------------- | +| errorId | uint256 | Requested key stored in the `_errorCodesEmitted` mapping. | + +#### Return Values + +| Name | Type | Description | +| --------- | ------ | -------------------------------------------------- | +| errorCode | euint8 | Encrypted error code located at the `errorId` key. | + +### \_errorGetCounter + +```solidity +function _errorGetCounter() internal view virtual returns (uint256 countErrors) +``` + +Returns the total counter of emitted of error codes. + +#### Return Values + +| Name | Type | Description | +| ----------- | ------- | ------------------------- | +| countErrors | uint256 | Number of errors emitted. | + +### \_errorGetNumCodesDefined + +```solidity +function _errorGetNumCodesDefined() internal view virtual returns (uint8 totalNumberErrorCodes) +``` -_It does not count `NO_ERROR` as one of the errors._ +Returns the total number of the possible error codes defined. #### Return Values -| Name | Type | Description | -| ----------------- | ----- | ----------------------- | -| totalNumberErrors | uint8 | total number of errors. | +| Name | Type | Description | +| --------------------- | ----- | --------------------------------------------------- | +| totalNumberErrorCodes | uint8 | Total number of the different possible error codes. | diff --git a/docs/utils/TFHEErrors.md b/docs/utils/TFHEErrors.md new file mode 100644 index 0000000..790bb2a --- /dev/null +++ b/docs/utils/TFHEErrors.md @@ -0,0 +1,9 @@ +# TFHEErrors + +### TFHESenderNotAllowed + +```solidity +error TFHESenderNotAllowed() +``` + +Returned when the `sender` is not allowed to access a value. diff --git a/hardhat.config.ts b/hardhat.config.ts index 9c1ac97..2c11d29 100644 --- a/hardhat.config.ts +++ b/hardhat.config.ts @@ -6,6 +6,7 @@ import { HardhatUserConfig, extendProvider } from "hardhat/config"; import { task } from "hardhat/config"; import type { NetworkUserConfig } from "hardhat/types"; import { resolve } from "path"; +import "solidity-docgen"; import CustomProvider from "./CustomProvider"; import { setCodeMocked } from "./test/mockedSetup"; diff --git a/package.json b/package.json index 126238b..b9e8454 100644 --- a/package.json +++ b/package.json @@ -81,7 +81,7 @@ "clean": "rimraf ./fhevmTemp ./artifacts ./cache ./coverage ./types ./coverage.json && pnpm typechain", "compile": "cross-env TS_NODE_TRANSPILE_ONLY=true hardhat compile", "deploy:contracts": "hardhat deploy", - "docgen": "hardhat docgen", + "docgen": "hardhat docgen && prettier --write \"docs/**/*.{md,}\"", "lint": "npm run lint:sol && npm run lint:ts && npm run prettier:check", "lint:sol": "solhint --max-warnings 10 \"contracts/**/*.sol\"", "lint:ts": "eslint --ignore-path ./.eslintignore --ext .js,.ts .",