From 8a5f3f3db4304967bba52ed9f6400dcbb8992c09 Mon Sep 17 00:00:00 2001 From: Gas <86567384+gas1cent@users.noreply.github.com> Date: Wed, 17 Apr 2024 10:39:52 +0400 Subject: [PATCH] docs: natspec and documentation improvements (#41) Co-authored-by: moebius <132487952+0xmoebius@users.noreply.github.com> --- docs/src/content/intro/README.md | 36 ++++++------ docs/src/content/modules/README.md | 23 ++++++++ docs/src/content/modules/response.md | 1 + .../response/bonded_response_module.md | 2 + natspec-smells.config.js | 9 +++ package.json | 2 +- .../extensions/AccountingExtension.sol | 6 ++ solidity/contracts/libraries/MerkleLib.sol | 4 +- .../modules/dispute/BondEscalationModule.sol | 4 ++ .../modules/dispute/CircuitResolverModule.sol | 5 +- .../BondEscalationResolutionModule.sol | 3 + .../periphery/SparseMerkleTreeL32Verifier.sol | 11 ++-- solidity/interfaces/ITreeVerifier.sol | 6 ++ .../extensions/IAccountingExtension.sol | 4 ++ .../modules/dispute/IBondEscalationModule.sol | 55 ++++++++++++------- .../modules/dispute/IBondedDisputeModule.sol | 12 ++-- .../dispute/ICircuitResolverModule.sol | 10 ++-- .../modules/resolution/IArbitratorModule.sol | 9 ++- .../IBondEscalationResolutionModule.sol | 33 +++++++---- .../resolution/IERC20ResolutionModule.sol | 10 +++- .../IPrivateERC20ResolutionModule.sol | 14 ++++- .../response/IBondedResponseModule.sol | 2 +- .../dispute/BondEscalationModule.t.sol | 1 - .../BondEscalationResolutionModule.t.sol | 2 - .../SparseMerkleTreeL32Verifier.t.sol | 1 - yarn.lock | 8 +-- 26 files changed, 184 insertions(+), 89 deletions(-) create mode 100644 natspec-smells.config.js diff --git a/docs/src/content/intro/README.md b/docs/src/content/intro/README.md index 43ff8c5e..53c968ce 100644 --- a/docs/src/content/intro/README.md +++ b/docs/src/content/intro/README.md @@ -20,25 +20,25 @@ Prophet presents a versatile and fully adaptable optimistic oracle solution, tra ## Deployments -The addresses of the contracts deployed on Optimism Goerli are listed below. - -| Contract | Goerli | +*The addresses of the contracts deployed on Optimism Sepolia will be listed here.* + ## Licensing diff --git a/docs/src/content/modules/README.md b/docs/src/content/modules/README.md index a55ecc05..18e5bdb9 100644 --- a/docs/src/content/modules/README.md +++ b/docs/src/content/modules/README.md @@ -1 +1,24 @@ # Modules + +Here you can find the list and the details of each module available in Prophet +- [Request](./request.md) +- [Response](./response.md) +- [Dispute](./dispute.md) +- [Resolution](./resolution.md) +- [Finality](./finality.md) + +## Common Parts + +You can notice that many modules follow the same structure. This is because they all inherit from the `IModule` interface which defines the common functions and modifiers that all modules should have. + +- `moduleName` is required to properly show the module in Prophet UI. +- `RequestParameters` is which parameters are required for the request to be processed with the module. +- `decodeRequestData` decodes the ABI encoded parameters using the `RequestParameters` struct and returns them as a list. This is useful for both on-chain and off-chain components. + +## Best Practices + +When building a module, keep in mind these tips to make the module predictable and easier to work with: + +1. Always process the release and refund of the bond within the same module where the bonding initially occurs. This approach enhances composability and allows developers to concentrate on the logic specific to their module. +1. Typically, a module is designed to function independently. However, there are instances where multiple modules are developed in a manner that necessitates their joint use. For an example take a look at [SparseMerkleTreeModule](./request/sparse_merkle_tree_request_module.md) and [RootVerificationModule](./dispute/root_verification_module.md). +1. When feasible, avoid requiring users to interact directly with the module. Instead, route all calls via the oracle. diff --git a/docs/src/content/modules/response.md b/docs/src/content/modules/response.md index 84840ce6..57ebce9b 100644 --- a/docs/src/content/modules/response.md +++ b/docs/src/content/modules/response.md @@ -16,5 +16,6 @@ A Response module should take care of the following: - Setting the rules for the responses, such as validations or deadlines - Handling the rewards for proposing a valid response - Applying the `onlyOracle` modifier to the hooks to secure them +- Releasing the bond if the response ended up being unutilized, meaning it's not accepted nor disputed While developing a Response module, keep in mind that the criteria that is too narrow might result in a lack of responses, while criteria that is too broad might result in a large number of invalid responses. diff --git a/docs/src/content/modules/response/bonded_response_module.md b/docs/src/content/modules/response/bonded_response_module.md index 97bf1c6b..fd313859 100644 --- a/docs/src/content/modules/response/bonded_response_module.md +++ b/docs/src/content/modules/response/bonded_response_module.md @@ -12,6 +12,7 @@ The Bonded Response Module is a contract that allows users to propose a response - `decodeRequestData`: Decodes request parameters. - `propose`: Proposes a response for a request, bonding the proposer's tokens. A response cannot be proposed after the deadline or if an undisputed response has already been proposed. +- `releaseUnutilizedResponse`: Releases the proposer funds if the response is valid and it has not been used to finalize the request. - `finalizeRequest`: Finalizes the request, paying the proposer of the final response. ### Request Parameters @@ -25,3 +26,4 @@ The Bonded Response Module is a contract that allows users to propose a response - **Early finalization**: It is possible for pre-dispute modules to atomically calculate the correct response on-chain, decide on the result of a dispute and finalize the request before its deadline. - **Dispute window**: Prevents proposers from submitting a response 1 block before the deadline and finalizing it in the next block, leaving disputers no time to dispute the response. +- **Unutilized response**: A correct response that has not been used to finalize the request. Consider what happens when the first response to a request is disputed maliciously and someone sends a second response with the same content. In that case if the second response isn't disputed and the first one comes back from the dispute and is accepted as the final response, the second proposer should be able to get his bond back. diff --git a/natspec-smells.config.js b/natspec-smells.config.js new file mode 100644 index 00000000..a7eeb9c9 --- /dev/null +++ b/natspec-smells.config.js @@ -0,0 +1,9 @@ +/** +* List of supported options: https://github.com/defi-wonderland/natspec-smells?tab=readme-ov-file#options +*/ + +/** @type {import('@defi-wonderland/natspec-smells').Config} */ +module.exports = { + include: 'solidity/**/*.sol', + exclude: 'solidity/(test|scripts)/**/*' +}; diff --git a/package.json b/package.json index 479a1bf3..016c690e 100644 --- a/package.json +++ b/package.json @@ -38,7 +38,7 @@ "package.json": "sort-package-json" }, "dependencies": { - "@defi-wonderland/prophet-core-contracts": "0.0.0-f88b32e2", + "@defi-wonderland/prophet-core-contracts": "0.0.0-4d4a4487", "@openzeppelin/contracts": "4.9.5", "solmate": "https://github.com/transmissions11/solmate.git#bfc9c25865a274a7827fea5abf6e4fb64fc64e6c" }, diff --git a/solidity/contracts/extensions/AccountingExtension.sol b/solidity/contracts/extensions/AccountingExtension.sol index 36849b07..544e5c27 100644 --- a/solidity/contracts/extensions/AccountingExtension.sol +++ b/solidity/contracts/extensions/AccountingExtension.sol @@ -33,12 +33,18 @@ contract AccountingExtension is IAccountingExtension { /** * @notice Checks that the caller is an allowed module used in the request. + * @param _requestId The request ID. */ modifier onlyAllowedModule(bytes32 _requestId) { if (!ORACLE.allowedModule(_requestId, msg.sender)) revert AccountingExtension_UnauthorizedModule(); _; } + /** + * @notice Checks if the user is either the requester or a proposer, or a disputer. + * @param _requestId The request ID. + * @param _user The address to check. + */ modifier onlyParticipant(bytes32 _requestId, address _user) { if (!ORACLE.isParticipant(_requestId, _user)) revert AccountingExtension_UnauthorizedUser(); _; diff --git a/solidity/contracts/libraries/MerkleLib.sol b/solidity/contracts/libraries/MerkleLib.sol index be7a5f09..b448b7d4 100644 --- a/solidity/contracts/libraries/MerkleLib.sol +++ b/solidity/contracts/libraries/MerkleLib.sol @@ -60,9 +60,7 @@ library MerkleLib { // ============= Structs ============== /** - * @notice Struct representing incremental merkle tree. Contains current - * branch and the number of inserted leaves in the tree. - * + * @notice Struct representing incremental merkle tree. Contains current branch and the number of inserted leaves in the tree. */ struct Tree { bytes32[TREE_DEPTH] branch; diff --git a/solidity/contracts/modules/dispute/BondEscalationModule.sol b/solidity/contracts/modules/dispute/BondEscalationModule.sol index b5283907..1e453b90 100644 --- a/solidity/contracts/modules/dispute/BondEscalationModule.sol +++ b/solidity/contracts/modules/dispute/BondEscalationModule.sol @@ -282,6 +282,10 @@ contract BondEscalationModule is Module, IBondEscalationModule { /** * @notice Checks the necessary conditions for pledging + * @param _disputeId The ID of the dispute to pledge for or against + * @param _request The request data + * @param _dispute The dispute data + * @param _forDispute Whether the pledge is for or against the dispute * @return _params The decoded parameters for the request */ function _pledgeChecks( diff --git a/solidity/contracts/modules/dispute/CircuitResolverModule.sol b/solidity/contracts/modules/dispute/CircuitResolverModule.sol index bb305518..7a62ddae 100644 --- a/solidity/contracts/modules/dispute/CircuitResolverModule.sol +++ b/solidity/contracts/modules/dispute/CircuitResolverModule.sol @@ -8,10 +8,11 @@ import {IOracle} from '@defi-wonderland/prophet-core-contracts/solidity/interfac import {ICircuitResolverModule} from '../../../interfaces/modules/dispute/ICircuitResolverModule.sol'; contract CircuitResolverModule is Module, ICircuitResolverModule { - constructor(IOracle _oracle) Module(_oracle) {} - + /// @notice Keeps track of the correct responses to requests mapping(bytes32 _requestId => bytes _correctResponse) internal _correctResponses; + constructor(IOracle _oracle) Module(_oracle) {} + /// @inheritdoc IModule function moduleName() external pure returns (string memory _moduleName) { return 'CircuitResolverModule'; diff --git a/solidity/contracts/modules/resolution/BondEscalationResolutionModule.sol b/solidity/contracts/modules/resolution/BondEscalationResolutionModule.sol index f58c234b..4ce18f4a 100644 --- a/solidity/contracts/modules/resolution/BondEscalationResolutionModule.sol +++ b/solidity/contracts/modules/resolution/BondEscalationResolutionModule.sol @@ -193,6 +193,8 @@ contract BondEscalationResolutionModule is Module, IBondEscalationResolutionModu /** * @notice Pledges for or against a dispute * + * @param _request The request being disputed + * @param _dispute The dispute to vote for or against * @param _pledgeAmount The amount to pledge * @param _pledgingFor Whether the pledger is pledging for or against the dispute */ @@ -314,6 +316,7 @@ contract BondEscalationResolutionModule is Module, IBondEscalationResolutionModu * @param _disputeId The ID of the dispute * @param _amountToRelease The amount to release * @param _resolution The resolution of the dispute + * @param _params The request parameters */ function _claimPledge( bytes32 _requestId, diff --git a/solidity/contracts/periphery/SparseMerkleTreeL32Verifier.sol b/solidity/contracts/periphery/SparseMerkleTreeL32Verifier.sol index 90447280..8c599180 100644 --- a/solidity/contracts/periphery/SparseMerkleTreeL32Verifier.sol +++ b/solidity/contracts/periphery/SparseMerkleTreeL32Verifier.sol @@ -8,16 +8,13 @@ import {MerkleLib} from '../libraries/MerkleLib.sol'; contract SparseMerkleTreeL32Verifier is ITreeVerifier { using MerkleLib for MerkleLib.Tree; + /// @notice The depth of the Merkle tree uint256 internal constant _TREE_DEPTH = 32; - MerkleLib.Tree internal _tempTree; - constructor() {} + /// @notice A temporary tree created and cleaned up in the calculateRoot function + MerkleLib.Tree internal _tempTree; - /** - * @notice Calculates the Merkle root hash given a set of Merkle tree branches and merkle tree leaves count. - * @param _treeData The encoded Merkle tree data parameters for the tree verifier. - * @return _calculatedRoot The calculated Merkle root hash. - */ + /// @inheritdoc ITreeVerifier function calculateRoot( bytes memory _treeData, bytes32[] memory _leavesToInsert diff --git a/solidity/interfaces/ITreeVerifier.sol b/solidity/interfaces/ITreeVerifier.sol index 612d8b7e..7544b8cc 100644 --- a/solidity/interfaces/ITreeVerifier.sol +++ b/solidity/interfaces/ITreeVerifier.sol @@ -2,6 +2,12 @@ pragma solidity ^0.8.19; interface ITreeVerifier { + /** + * @notice Calculates the Merkle root hash given a set of Merkle tree branches and merkle tree leaves count. + * @param _treeData The encoded Merkle tree data parameters for the tree verifier. + * @param _leavesToInsert The array of leaves to insert into the Merkle tree. + * @return _calculatedRoot The calculated Merkle root hash. + */ function calculateRoot( bytes memory _treeData, bytes32[] memory _leavesToInsert diff --git a/solidity/interfaces/extensions/IAccountingExtension.sol b/solidity/interfaces/extensions/IAccountingExtension.sol index f4b062c8..223b55a0 100644 --- a/solidity/interfaces/extensions/IAccountingExtension.sol +++ b/solidity/interfaces/extensions/IAccountingExtension.sol @@ -32,6 +32,7 @@ interface IAccountingExtension { /** * @notice A payment between users has been made + * @param _requestId The ID of the request * @param _beneficiary The user receiving the tokens * @param _payer The user who is getting its tokens transferred * @param _token The address of the token being transferred @@ -43,6 +44,7 @@ interface IAccountingExtension { /** * @notice User's funds have been bonded + * @param _requestId The ID of the request * @param _bonder The user who is getting its tokens bonded * @param _token The address of the token being bonded * @param _amount The amount of `_token` bonded @@ -51,6 +53,7 @@ interface IAccountingExtension { /** * @notice User's funds have been released + * @param _requestId The ID of the request * @param _beneficiary The user who is getting its tokens released * @param _token The address of the token being released * @param _amount The amount of `_token` released @@ -90,6 +93,7 @@ interface IAccountingExtension { /** * @notice Returns the interface for the Oracle contract + * @return _oracle The Oracle address */ function ORACLE() external view returns (IOracle _oracle); diff --git a/solidity/interfaces/modules/dispute/IBondEscalationModule.sol b/solidity/interfaces/modules/dispute/IBondEscalationModule.sol index f8c946a0..175a984f 100644 --- a/solidity/interfaces/modules/dispute/IBondEscalationModule.sol +++ b/solidity/interfaces/modules/dispute/IBondEscalationModule.sol @@ -110,13 +110,18 @@ interface IBondEscalationModule is IDisputeModule { /** * @notice Enum holding all the possible statuses of a dispute going through the bond escalation mechanism. + * @param None Dispute is not going through the bond escalation mechanism. + * @param Active Dispute is going through the bond escalation mechanism. + * @param Escalated Dispute is going through the bond escalation mechanism and has been escalated. + * @param DisputerLost An escalated dispute has been settled and the disputer lost. + * @param DisputerWon An escalated dispute has been settled and the disputer won. */ enum BondEscalationStatus { - None, // Dispute is not going through the bond escalation mechanism. - Active, // Dispute is going through the bond escalation mechanism. - Escalated, // Dispute is going through the bond escalation mechanism and has been escalated. - DisputerLost, // An escalated dispute has been settled and the disputer lost. - DisputerWon // An escalated dispute has been settled and the disputer won. + None, + Active, + Escalated, + DisputerLost, + DisputerWon } /*/////////////////////////////////////////////////////////////// @@ -126,14 +131,14 @@ interface IBondEscalationModule is IDisputeModule { /** * @notice Parameters of the request as stored in the module * - * @param _accountingExtension Address of the accounting extension associated with the given request - * @param _bondToken Address of the token associated with the given request - * @param _bondSize Amount to bond to dispute or propose an answer for the given request - * @param _numberOfEscalations Maximum allowed escalations or pledges for each side during the bond escalation process - * @param _bondEscalationDeadline Timestamp at which bond escalation process finishes when pledges are not tied - * @param _tyingBuffer Number of seconds to extend the bond escalation process to allow the losing + * @param accountingExtension Address of the accounting extension associated with the given request + * @param bondToken Address of the token associated with the given request + * @param bondSize Amount to bond to dispute or propose an answer for the given request + * @param maxNumberOfEscalations Maximum allowed escalations or pledges for each side during the bond escalation process + * @param bondEscalationDeadline Timestamp at which bond escalation process finishes when pledges are not tied + * @param tyingBuffer Number of seconds to extend the bond escalation process to allow the losing * party to tie if at the end of the initial deadline the pledges weren't tied. - * @param _disputeWindow Number of seconds disputers have to challenge the proposed response since its creation. + * @param disputeWindow Number of seconds disputers have to challenge the proposed response since its creation. */ struct RequestParameters { IBondEscalationAccounting accountingExtension; @@ -204,7 +209,9 @@ interface IBondEscalationModule is IDisputeModule { * @dev If this is the first dispute of the request and the bond escalation window is not over, * it will start the bond escalation process. This function must be called through the Oracle. * - * @param _response The response being disputed. + * @param _request The request data. + * @param _response The response being disputed. + * @param _dispute The dispute created by the oracle. */ function disputeResponse( IOracle.Request calldata _request, @@ -216,9 +223,10 @@ interface IBondEscalationModule is IDisputeModule { * @notice Updates the status of a given disputeId and pays the proposer and disputer accordingly. If this * dispute has gone through the bond escalation mechanism, then it will pay the winning pledgers as well. * - * @param _disputeId The ID of the dispute to update the status for. - * @param _dispute The full dispute object. - * + * @param _disputeId The ID of the dispute to update the status for. + * @param _request The request data. + * @param _response The disputed response. + * @param _dispute The dispute data. */ function onDisputeStatusChange( bytes32 _disputeId, @@ -230,7 +238,9 @@ interface IBondEscalationModule is IDisputeModule { /** * @notice Bonds funds in favor of a given dispute during the bond escalation process. * - * @dev This function must be called directly through this contract. + * @param _request The request data. + * @param _dispute The dispute data. + * * @dev If the bond escalation is not tied at the end of its deadline, a tying buffer is added * to avoid scenarios where one of the parties breaks the tie very last second. * During the tying buffer, the losing party can only tie, and once the escalation is tied @@ -241,8 +251,10 @@ interface IBondEscalationModule is IDisputeModule { /** * @notice Pledges funds against a given disputeId during its bond escalation process. * - * @dev Must be called directly through this contract. Will revert if the disputeId is not going through - * the bond escalation process. + * @param _request The request data. + * @param _dispute The dispute data. + * + * @dev Will revert if the disputeId is not going through the bond escalation process. * @dev If the bond escalation is not tied at the end of its deadline, a tying buffer is added * to avoid scenarios where one of the parties breaks the tie very last second. * During the tying buffer, the losing party can only tie, and once the escalation is tied @@ -253,7 +265,10 @@ interface IBondEscalationModule is IDisputeModule { /** * @notice Settles the bond escalation process of a given requestId. * - * @dev Must be called directly through this contract. + * @param _request The request data. + * @param _response The response data. + * @param _dispute The dispute data. + * * @dev Can only be called if after the deadline + tyingBuffer window is over, the pledges weren't tied */ function settleBondEscalation( diff --git a/solidity/interfaces/modules/dispute/IBondedDisputeModule.sol b/solidity/interfaces/modules/dispute/IBondedDisputeModule.sol index 3b9ecef7..cfe2ff61 100644 --- a/solidity/interfaces/modules/dispute/IBondedDisputeModule.sol +++ b/solidity/interfaces/modules/dispute/IBondedDisputeModule.sol @@ -20,10 +20,10 @@ interface IBondedDisputeModule is IDisputeModule { //////////////////////////////////////////////////////////////*/ /** - * @notice Parameters of the request as stored in the module - * @param ipfsHash The hash of the CID from IPFS - * @param requestModule The address of the request module - * @param responseModule The address of the response module + * @notice Parameters of the request as stored in the module + * @param accountingExtension The address of the accounting extension + * @param bondToken The address of the bond token + * @param bondSize The size of the bond */ struct RequestParameters { IAccountingExtension accountingExtension; @@ -61,7 +61,9 @@ interface IBondedDisputeModule is IDisputeModule { * * @dev According to the result of the dispute, bonds are released to the proposer or paid to the disputer * @param _disputeId The ID of the dispute being updated - * @param _dispute The dispute object + * @param _request The request a dispute has been submitted for + * @param _response The response that is being disputed + * @param _dispute The dispute that has changed status */ function onDisputeStatusChange( bytes32 _disputeId, diff --git a/solidity/interfaces/modules/dispute/ICircuitResolverModule.sol b/solidity/interfaces/modules/dispute/ICircuitResolverModule.sol index 54b2e400..5db18b0c 100644 --- a/solidity/interfaces/modules/dispute/ICircuitResolverModule.sol +++ b/solidity/interfaces/modules/dispute/ICircuitResolverModule.sol @@ -36,11 +36,11 @@ interface ICircuitResolverModule is IDisputeModule { /** * @notice Parameters of the request as stored in the module * - * @return callData The encoded data forwarded to the verifier - * @return verifier The address of the verifier contract - * @return accountingExtension The address of the accounting extension - * @return bondToken The address of the bond token - * @return bondSize The size of the bond + * @param callData The encoded data forwarded to the verifier + * @param verifier The address of the verifier contract + * @param accountingExtension The address of the accounting extension + * @param bondToken The address of the bond token + * @param bondSize The size of the bond */ struct RequestParameters { bytes callData; diff --git a/solidity/interfaces/modules/resolution/IArbitratorModule.sol b/solidity/interfaces/modules/resolution/IArbitratorModule.sol index 74d182a2..28544801 100644 --- a/solidity/interfaces/modules/resolution/IArbitratorModule.sol +++ b/solidity/interfaces/modules/resolution/IArbitratorModule.sol @@ -35,11 +35,14 @@ interface IArbitratorModule is IResolutionModule { /** * @notice Available status of the arbitration process + * @param Unknown The arbitration process has not started (default) + * @param Active The arbitration process is active + * @param Resolved The The arbitration process is finished */ enum ArbitrationStatus { - Unknown, // The arbitration process has not started (default) - Active, // The arbitration process is active - Resolved // The arbitration process is resolved + Unknown, + Active, + Resolved } /*/////////////////////////////////////////////////////////////// diff --git a/solidity/interfaces/modules/resolution/IBondEscalationResolutionModule.sol b/solidity/interfaces/modules/resolution/IBondEscalationResolutionModule.sol index 3df7dd1d..f7582e5e 100644 --- a/solidity/interfaces/modules/resolution/IBondEscalationResolutionModule.sol +++ b/solidity/interfaces/modules/resolution/IBondEscalationResolutionModule.sol @@ -157,12 +157,12 @@ interface IBondEscalationResolutionModule is IResolutionModule { /** * @notice Parameters of the request as stored in the module * - * @param _accountingExtension The accounting extension to use for this request. - * @param _token The token to use for this request. - * @param _percentageDiff The percentage difference between the for and against pledges that triggers the change in voting turns. This value should be between 1 and 100. - * @param _pledgeThreshold The amount of pledges that must be reached to achieve quorum and start triggering voting turns. - * @param _timeUntilDeadline The amount of time in seconds past the start time of the escalation until the resolution process is over. - * @param _timeToBreakInequality The amount of time the pledgers have to break the pledge inequality once the percentage difference has been surpassed. + * @param accountingExtension The accounting extension to use for this request. + * @param bondToken The token to use for this request. + * @param percentageDiff The percentage difference between the for and against pledges that triggers the change in voting turns. This value should be between 1 and 100. + * @param pledgeThreshold The amount of pledges that must be reached to achieve quorum and start triggering voting turns. + * @param timeUntilDeadline The amount of time in seconds past the start time of the escalation until the resolution process is over. + * @param timeToBreakInequality The amount of time the pledgers have to break the pledge inequality once the percentage difference has been surpassed. */ struct RequestParameters { IBondEscalationAccounting accountingExtension; @@ -176,8 +176,8 @@ interface IBondEscalationResolutionModule is IResolutionModule { /** * @notice The inequality status and its last update time of a given dispute. * - * @param _inequalityStatus The current status of the inequality. - * @param _time The time at which the inequality was last updated. + * @param inequalityStatus The current status of the inequality. + * @param time The time at which the inequality was last updated. */ struct InequalityData { InequalityStatus inequalityStatus; @@ -187,10 +187,10 @@ interface IBondEscalationResolutionModule is IResolutionModule { /** * @notice The bond escalation progress and the balance of pledges for and against a given dispute. * - * @param _resolution The current resolution of the dispute. - * @param _startTime The time at which the dispute was escalated. - * @param _pledgesFor The amount of pledges in favor of the dispute. - * @param _pledgesAgainst The amount of pledges against the dispute. + * @param resolution The current resolution of the dispute. + * @param startTime The time at which the dispute was escalated. + * @param pledgesFor The amount of pledges in favor of the dispute. + * @param pledgesAgainst The amount of pledges against the dispute. */ struct Escalation { Resolution resolution; @@ -272,6 +272,9 @@ interface IBondEscalationResolutionModule is IResolutionModule { /** * @notice Allows users to pledge in favor of a given dispute. This means the user believes the proposed answer is * incorrect and therefore wants the disputer to win his dispute. + * + * @param _request The request data + * @param _dispute The dispute data * @param _pledgeAmount The amount of pledges to pledge. */ function pledgeForDispute( @@ -283,6 +286,9 @@ interface IBondEscalationResolutionModule is IResolutionModule { /** * @notice Allows users to pledge against a given dispute. This means the user believes the proposed answer is * correct and therefore wants the disputer to lose his dispute. + * + * @param _request The request data + * @param _dispute The dispute data * @param _pledgeAmount The amount of pledges to pledge. */ function pledgeAgainstDispute( @@ -294,6 +300,9 @@ interface IBondEscalationResolutionModule is IResolutionModule { /** * @notice Allows user to claim his corresponding pledges after a dispute is resolved. * + * @param _request The request data + * @param _dispute The dispute data + * * @dev Winning pledgers will claim their pledges along with their reward. In case of no resolution, users can * claim their pledges back. Losing pledgers will go to the rewards of the winning pledgers. */ diff --git a/solidity/interfaces/modules/resolution/IERC20ResolutionModule.sol b/solidity/interfaces/modules/resolution/IERC20ResolutionModule.sol index 96d0c38c..e586f6a4 100644 --- a/solidity/interfaces/modules/resolution/IERC20ResolutionModule.sol +++ b/solidity/interfaces/modules/resolution/IERC20ResolutionModule.sol @@ -38,6 +38,9 @@ interface IERC20ResolutionModule is IResolutionModule { /** * @notice Emitted when the voter gets back their bond + * @param _voter The voter who has claimed their bond + * @param _disputeId The id of the dispute + * @param _amount The amount of tokens claimed */ event VoteClaimed(address _voter, bytes32 _disputeId, uint256 _amount); @@ -81,6 +84,7 @@ interface IERC20ResolutionModule is IResolutionModule { /** * @notice Parameters of the request as stored in the module + * @param accountingExtension The accounting extension to bond and release funds * @param votingToken The token used to vote * @param minVotesForQuorum The minimum amount of votes to win the dispute * @param timeUntilDeadline The time until the voting phase ends @@ -135,8 +139,10 @@ interface IERC20ResolutionModule is IResolutionModule { /** * @notice Casts a vote in favor of a dispute * - * @param _request The request for which the dispute was created - * @param _dispute The dispute for which the vote is being cast + * @param _disputeId The id of the dispute + * @param _request The request for which the dispute was created + * @param _response The disputed response + * @param _dispute The dispute for which the vote is being cast */ function startResolution( bytes32 _disputeId, diff --git a/solidity/interfaces/modules/resolution/IPrivateERC20ResolutionModule.sol b/solidity/interfaces/modules/resolution/IPrivateERC20ResolutionModule.sol index d5236e0c..27c3389c 100644 --- a/solidity/interfaces/modules/resolution/IPrivateERC20ResolutionModule.sol +++ b/solidity/interfaces/modules/resolution/IPrivateERC20ResolutionModule.sol @@ -97,7 +97,7 @@ interface IPrivateERC20ResolutionModule is IResolutionModule { /** * @notice Parameters of the request as stored in the module * @param accountingExtension The accounting extension used to bond and release tokens - * @param token The token used to vote + * @param votingToken The token used to vote * @param minVotesForQuorum The minimum amount of votes to win the dispute * @param committingTimeWindow The amount of time to commit votes from the escalation of the dispute * @param revealingTimeWindow The amount of time to reveal votes from the committing phase @@ -115,7 +115,6 @@ interface IPrivateERC20ResolutionModule is IResolutionModule { * @param startTime The timestamp at which the dispute was escalated * @param totalVotes The total amount of votes cast for the dispute */ - struct Escalation { uint256 startTime; uint256 totalVotes; @@ -151,6 +150,9 @@ interface IPrivateERC20ResolutionModule is IResolutionModule { * @notice Starts the committing phase for a dispute * @dev Only callable by the Oracle * @param _disputeId The id of the dispute to start resolution of + * @param _request The request data + * @param _response The disputed response + * @param _dispute The dispute being resolved */ function startResolution( bytes32 _disputeId, @@ -162,6 +164,8 @@ interface IPrivateERC20ResolutionModule is IResolutionModule { /** * @notice Stores a commitment for a vote cast by a voter * @dev Committing multiple times and overwriting a previous commitment is allowed + * @param _request The request data + * @param _dispute The dispute being voted on * @param _commitment The commitment computed from the provided data and the user's address */ function commitVote( @@ -173,6 +177,8 @@ interface IPrivateERC20ResolutionModule is IResolutionModule { /** * @notice Reveals a vote cast by a voter * @dev The user must have previously approved the module to transfer the tokens + * @param _request The request data + * @param _dispute The dispute being voted on * @param _numberOfVotes The amount of votes being revealed * @param _salt The salt used to compute the commitment */ @@ -187,6 +193,9 @@ interface IPrivateERC20ResolutionModule is IResolutionModule { * @notice Resolves a dispute by tallying the votes and executing the winning outcome * @dev Only callable by the Oracle * @param _disputeId The id of the dispute being resolved + * @param _request The request data + * @param _response The disputed response + * @param _dispute The dispute being resolved */ function resolveDispute( bytes32 _disputeId, @@ -206,6 +215,7 @@ interface IPrivateERC20ResolutionModule is IResolutionModule { * @notice Computes a valid commitment for the revealing phase * @param _disputeId The id of the dispute being voted on * @param _numberOfVotes The amount of votes being cast + * @param _salt Random data used to hash the commitment * @return _commitment The commitment computed from the provided data and the user's address */ function computeCommitment( diff --git a/solidity/interfaces/modules/response/IBondedResponseModule.sol b/solidity/interfaces/modules/response/IBondedResponseModule.sol index 74073cd2..c8128f4e 100644 --- a/solidity/interfaces/modules/response/IBondedResponseModule.sol +++ b/solidity/interfaces/modules/response/IBondedResponseModule.sol @@ -114,7 +114,7 @@ interface IBondedResponseModule is IResponseModule { ) external; /** - * @notice Releases the proposer fund if the response is valid and it has not been used to finalize the request + * @notice Releases the proposer funds if the response is valid and it has not been used to finalize the request * * @param _request The finalized request * @param _response The unutilized response diff --git a/solidity/test/unit/modules/dispute/BondEscalationModule.t.sol b/solidity/test/unit/modules/dispute/BondEscalationModule.t.sol index 115347b4..02f7b83d 100644 --- a/solidity/test/unit/modules/dispute/BondEscalationModule.t.sol +++ b/solidity/test/unit/modules/dispute/BondEscalationModule.t.sol @@ -55,7 +55,6 @@ contract ForTest_BondEscalationModule is BondEscalationModule { /** * @title Bonded Response Module Unit tests */ - contract BaseTest is Test, Helpers { // The target contract ForTest_BondEscalationModule public bondEscalationModule; diff --git a/solidity/test/unit/modules/resolution/BondEscalationResolutionModule.t.sol b/solidity/test/unit/modules/resolution/BondEscalationResolutionModule.t.sol index 8824bad7..4f669c1e 100644 --- a/solidity/test/unit/modules/resolution/BondEscalationResolutionModule.t.sol +++ b/solidity/test/unit/modules/resolution/BondEscalationResolutionModule.t.sol @@ -21,7 +21,6 @@ import {IBondEscalationAccounting} from '../../../../interfaces/extensions/IBond /** * @dev Harness to set an entry in the requestData mapping, without triggering setup request hooks */ - contract ForTest_BondEscalationResolutionModule is BondEscalationResolutionModule { constructor(IOracle _oracle) BondEscalationResolutionModule(_oracle) {} @@ -59,7 +58,6 @@ contract ForTest_BondEscalationResolutionModule is BondEscalationResolutionModul /** * @title Bonded Escalation Resolution Module Unit tests */ - contract BaseTest is Test, Helpers { // The target contract ForTest_BondEscalationResolutionModule public module; diff --git a/solidity/test/unit/periphery/SparseMerkleTreeL32Verifier.t.sol b/solidity/test/unit/periphery/SparseMerkleTreeL32Verifier.t.sol index cad8d385..572553c9 100644 --- a/solidity/test/unit/periphery/SparseMerkleTreeL32Verifier.t.sol +++ b/solidity/test/unit/periphery/SparseMerkleTreeL32Verifier.t.sol @@ -32,7 +32,6 @@ contract SparseMerkleTreeL32Verifier_UnitTest is Test { /** * @notice Deploy the target */ - function setUp() public { sparseMerkleTreeL32Verifier = new ForTest_SparseMerkleTreeL32Verifier(); } diff --git a/yarn.lock b/yarn.lock index f0c625af..1f51733f 100644 --- a/yarn.lock +++ b/yarn.lock @@ -192,10 +192,10 @@ dependencies: "@jridgewell/trace-mapping" "0.3.9" -"@defi-wonderland/prophet-core-contracts@0.0.0-f88b32e2": - version "0.0.0-f88b32e2" - resolved "https://registry.yarnpkg.com/@defi-wonderland/prophet-core-contracts/-/prophet-core-contracts-0.0.0-f88b32e2.tgz#dfe362e055eeee33486b3ceca369ef31df57be86" - integrity sha512-aeruTSUdJkbJhEEwZfBHHQm5RoVtsUrDUxqE8eliTarKhIThfyVVL05CjK2jp1GmNaJ0moN4fPbhDckt0Xn02Q== +"@defi-wonderland/prophet-core-contracts@0.0.0-4d4a4487": + version "0.0.0-4d4a4487" + resolved "https://registry.yarnpkg.com/@defi-wonderland/prophet-core-contracts/-/prophet-core-contracts-0.0.0-4d4a4487.tgz#a794df6bc6d61287710778fbb73d2bde30094238" + integrity sha512-wE7Y1EDlmZQwqyxfuQ7z+DcKWyNxkXTLWBV8vt0PSY/Z8o6yUBhLe/NXYAEjrCJc4yPjQbqfADYRTmATN3w8YQ== "@defi-wonderland/solidity-utils@0.0.0-3e9c8e8b": version "0.0.0-3e9c8e8b"