docs: revise documentation (#27)

* docs: remove`WETH` from summary * docs: update the getting started page * docs: add discord link * docs: delete an extra page * docs: review the framework page * docs: review oracle description * docs: review Module documentation * docs: update module descriptions * docs: review all modules * docs: review extensions * docs: sequential resolution module * docs: remove sequential resolution from docs * docs: wording improvements Co-authored-by: moebius <[email protected]> --------- Co-authored-by: moebius <[email protected]>
defi-wonderland · Dec 8, 2023 · e8aec63 · e8aec63
1 parent 33cee33
commit e8aec63
Show file tree

Hide file tree

Showing 29 changed files with 126 additions and 166 deletions.
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -35,7 +35,6 @@
     - [BondEscalationResolutionModule](content/modules/resolution/bond_escalation_resolution_module.md)
     - [ERC20ResolutionModule](content/modules/resolution/erc20_resolution_module.md)
     - [PrivateERC20ResolutionModule](content/modules/resolution/private_erc20_resolution_module.md)
-    - [SequentialResolutionModule](content/modules/resolution/sequential_resolution_module.md)
 
   - [Finality](content/modules/finality.md)
     - [CallbackModule](content/modules/finality/callback_module.md)
@@ -56,8 +55,6 @@
 
 - [Interfaces]()
     - [❱ core](solidity/interfaces/core/README.md)
-      - [❱ external](solidity/interfaces/core/external/README.md)
-        - [IWETH9](solidity/interfaces/core/external/IWETH9.sol/interface.IWETH9.md)
       - [❱ modules](solidity/interfaces/core/modules/README.md)
         - [❱ dispute](solidity/interfaces/core/modules/dispute/README.md)
           - [IDisputeModule](solidity/interfaces/core/modules/dispute/IDisputeModule.sol/interface.IDisputeModule.md)

diff --git a/docs/src/content/core/module.md b/docs/src/content/core/module.md
@@ -1,26 +1,14 @@
 # Module
 
-See [IModule.sol](/solidity/interfaces/IModule.sol/interface.IModule.md) for more details.
+See [IModule.sol](/solidity/interfaces/core/IModule.sol/interface.IModule.md) for more details.
 
-## 1. Introduction
+`Module` is an abstract contract that defines common functions and modifiers. A module is supposed to inherit the abstract contract and implement specific logic in one of the hooks, for example `finalizeRequest`. All public functions in the contract are callable only by the oracle, and there are internal functions ensuring the integrity of the data being passed around, such as `_validateResponse` and `_validateDispute`.
 
-`Module` is an abstract contract that defines common functions and modifiers. A module is supposed to inherit the abstract contract and implement specific logic in one of the hooks, for example `_afterSetupRequest`.
+In addition to the abstract contact, we've created interfaces for each type of module:
+- [IRequestModule](/solidity/interfaces/core/modules/request/IRequestModule.sol/interface.IRequestModule.md)
+- [IResponseModule](/solidity/interfaces/core/modules/response/IResponseModule.sol/interface.IResponseModule.md)
+- [IDisputeModule](/solidity/interfaces/core/modules/dispute/IDisputeModule.sol/interface.IDisputeModule.md)
+- [IResolutionModule](/solidity/interfaces/core/modules/resolution/IResolutionModule.sol/interface.IResolutionModule.md)
+- [IFinalityModule](/solidity/interfaces/core/modules/finality/IFinalityModule.sol/interface.IFinalityModule.md)
 
-## 2. Contract Details
-
-### Key Methods
-
-All public functions in the abstract contract are callable only by the oracle.
-
-- `setupRequest` is a hook executed on request creation. Apart from saving the request data in the module, it can run can run validations, bond funds or perform any other action specified in the `_afterSetupRequest` function.
-- `finalizeRequest` is a hook executed on request finalization. It's vital to remember that there are [2 ways of finalizing a request](oracle.md#finalization) and this function must handle both of them.
-
-## 3. Key Mechanisms & Concepts
-
-### Request Data
-
-The `requestData` is a mapping that associates each request's unique identifier (`requestId`) with its corresponding parameters. This mapping is public, allowing for the data of any request to be accessed using its ID.
-
-## 4. Gotchas
-
-It's worth noting that if a module does not implement a hook, it will still be called by the oracle.
+Each of them inherits the `IModule` interface and adds additional functions specific to the module type.
diff --git a/docs/src/content/core/oracle.md b/docs/src/content/core/oracle.md
@@ -1,6 +1,6 @@
 # Oracle
 
-See [IOracle.sol](/solidity/interfaces/IOracle.sol/interface.IOracle.md) for more details.
+See [IOracle.sol](/solidity/interfaces/core/IOracle.sol/interface.IOracle.md) for more details.
 
 ## 1. Introduction
 
@@ -18,34 +18,35 @@ The Oracle does not handle any transfers, utilizing the extensions for that func
 ### Key Methods
 
 - `createRequest`: Creates a new request.
+- `createRequests`: Creates multiple requests at once.
 - `proposeResponse`: Proposes a response to a request.
 - `disputeResponse`: Disputes a response to a request.
-- `deleteResponse`: Deletes a response to a request.
 - `escalateDispute`: Escalates a dispute to the next level.
+- `resolveDispute`: Stores the resolution outcome and changes the dispute status.
 - `updateDisputeStatus`: Updates the status of a dispute.
 - `finalize`: Finalizes a request.
 
 ## 3. Key Mechanisms & Concepts
 
-### Request vs Full Request vs New Request
+### Stored data
 
-The oracle defines 3 structures representing a request:
+The oracle keeps almost no data in storage, instead relying on events to help off-chain agents track the state of requests, responses and disputes.
+
+### Request, response, dispute IDs
+The IDs are calculated as keccak256 hash of the request, response or dispute data. This allows for easy verification of the data integrity and uniqueness.
 
-- `Request` which is stored in `_requests` mapping. It includes the addresses of the modules and additional information like the requester address and the creation and finalization timestamps. It can be retrieved with `getRequest` function.
-- `FullRequest` unlike the Request struct, this one also includes the data used to configure the modules. `getFullRequest` function can be used to retrieve it.
-- `NewRequest` is a struct used in `createRequest`. It lacks the timestamps and the requester address, which are set by the oracle, but includes the modules data.
 
 ### Finalization
 The oracle supports 2 ways of finalizing a request.
 
-1. In case there is a non-disputed response, the request can be finalized by calling `finalize` function and providing the response ID. The oracle will call `finalizeRequest` on the modules and mark the request as finalized. Generally the `finalizeRequest` hook will issue the reward to the proposer.
+1. In case there is a non-disputed response, the request can be finalized by calling `finalize` function and providing the final response. The oracle will call `finalizeRequest` on the modules and mark the request as finalized. Usually the `finalizeRequest` hook will issue the reward to the proposer.
 
-2. If no responses have been submitted, or they're all disputed, the request can be finalized by calling `finalize` function without a response ID. The same hook will be executed in all modules, refunding the requester and marking the request as finalized.
+2. If no responses have been submitted, or they're all disputed, the request can be finalized by calling `finalize` function with a response that has its request ID set to 0. The same hook will be executed in all modules, refunding the requester and marking the request as finalized.
 
 ## 4. Gotchas
 
 ### Request misconfiguration
 
-Due to the modular and open nature of the framework, the oracle does not have any rules or validations, and a request is deemed correct unless it reverts on creation (`setupRequest`). It’s the requester’s responsibility to choose sensible parameters and avoid the request being unattractive to proposers and disputers, impossible to answer or finalize.
+Due to the modular and open nature of the framework, the oracle does not have any rules or validations, and a request is deemed correct unless it reverts on creation (`createRequest` hook). It’s the requester’s responsibility to choose sensible parameters and avoid the request being unattractive to proposers and disputers, impossible to answer or finalize.
 
 The same can be said about engaging with a request. Off-chain validation must be done prior to proposing or disputing any response to avoid the loss of funds. We strongly encourage keeping a list of trusted modules and extensions and avoid interactions with unverified ones.
diff --git a/docs/src/content/extensions/accounting.md b/docs/src/content/extensions/accounting.md
@@ -10,23 +10,23 @@ The Accounting Extension is a contract that allows users to deposit and bond fun
 
 ### Key Methods
 
-- `deposit(IERC20 _token, uint256 _amount)`: This function allows a user to deposit a specific amount of a token into the accounting extension. If ETH is being deposited, it is wrapped to WETH.
-- `withdraw(IERC20 _token, uint256 _amount)`: By calling this function, a user can withdraw a specific amount of a token from the accounting extension.
-- `bond(address _bonder, bytes32 _requestId, IERC20 _token, uint256 _amount)`: This function allows a user to lock a specific amount of a token for a specific request. The tokens stay in the accounting extension and will not be withdrawable until they are released by a module.
-- `release(address _bonder, bytes32 _requestId, IERC20 _token, uint256 _amount)`: This function allows a module to release a specific amount of a token that was previously bonded to a request. The tokens will be moved back to the user's balance.
-- `pay(bytes32 _requestId, address _payer, address _receiver, IERC20 _token, uint256 _amount)`: Transfers a specific amount of a bonded token from the payer to the receiver. This function can only be called by a module.
+- `deposit`: Allows a user to deposit a specific amount of a token into the accounting extension. If ETH is being deposited, it is wrapped to WETH.
+- `withdraw`: By calling this function, a user can withdraw a specific amount of a token from the accounting extension.
+- `bond`: Allows a user to lock a specific amount of a token for a specific request. The tokens stay in the accounting extension and will not be withdrawable until they are released by a module.
+- `release`: Allows a module to release a specific amount of a token that was previously bonded to a request. The tokens will be moved back to the user's balance.
+- `pay`: Transfers a specific amount of a bonded token from the payer to the receiver. This function can only be called by a module.
 
 ## 3. Key Mechanisms & Concepts
 
-- Deposits: Users can deposit tokens into the Accounting Extension. These deposits are tracked in a mapping that associates each user's address with their balance of each token. Deposits can be made in any ERC20 token, including wrapped Ether (WETH).
+- **Deposits**: Users can deposit tokens into the Accounting Extension. These deposits are tracked in a mapping that associates each user's address with their balance of each token. Deposits can be made in any ERC20 token, including wrapped Ether (WETH).
 
-- Withdrawals: Users can withdraw their deposited tokens at any time, provided they have sufficient balance. The withdrawal operation reduces the user's balance in the Accounting Extension and transfers the tokens back to the user's address. Locked tokens can't be withdrawn until they're released by a module.
+- **Withdrawals**: Users can withdraw their deposited tokens at any time, provided they have sufficient balance. The withdrawal operation reduces the user's balance in the Accounting Extension and transfers the tokens back to the user's address. Locked tokens can't be withdrawn until they're released by a module.
 
-- Bonding: Users can lock their tokens up for to be allowed to participate in a request. Tokens stay in the accounting extension but they cannot be withdrawn until the request is finalized or the tokens are released.
+- **Bonding**: Users can lock their tokens up to be allowed to participate in a request. Tokens stay in the accounting extension but they cannot be withdrawn until the request is finalized or the tokens are released.
 
-- Payments: The Accounting Extension allows for payments to be made from one user to another. This usually means rewards for correct proposers and disputers and slashing malicious actors. It's done by unlocking and transferring the bonded tokens from the payer to the receiver's balance. Payments can only be initiated by modules.
+- **Payments**: The Accounting Extension allows for payments to be made from one user to another. This usually means rewards for correct proposers and disputers and slashing malicious actors. It's done by unlocking and transferring the bonded tokens from the payer to the receiver's balance. Payments can only be initiated by modules.
 
-- Releasing Bonds: Bonds can be released by allowed modules, which moves the bonded tokens back to the user's balance, making them available for withdrawal or bonding to a different request.
+- **Releasing Bonds**: Bonds can be released by allowed modules, which moves the bonded tokens back to the user's balance, making them available for withdrawal or bonding to a different request.
 
 ## 4. Gotchas
 

diff --git a/docs/src/content/extensions/bond_escalation_accounting.md b/docs/src/content/extensions/bond_escalation_accounting.md
@@ -10,12 +10,12 @@ The `BondEscalationAccounting` contract is an extension that allows users to dep
 
 ### Key Methods
 
-- `deposit`: This function allows a user to deposit a specific amount of a token into the accounting extension. If ETH is being deposited, it is wrapped to WETH.
+- `deposit`: Allows a user to deposit a specific amount of a token into the accounting extension. If ETH is being deposited, it is wrapped to WETH.
 - `withdraw`: By calling this function, a user can withdraw a specific amount of a token from the accounting extension.
-- `pledge`: This function allows a user to pledge a certain amount of tokens for a specific dispute. The pledged tokens are deducted from the user's balance and added to the total pledges for the dispute.
-- `settleBondEscalation`: This function unlocks the rewards for the winners.
+- `pledge`: Allows a user to pledge a certain amount of tokens for a specific dispute. The pledged tokens are deducted from the user's balance and added to the total pledges for the dispute.
+- `onSettleBondEscalation`: Unlocks the rewards for the winners.
 - `claimEscalationReward`: Calculates and transfers the caller's part of the reward to them.
-- `releasePledge`: This function allows a module to release a user's tokens.
+- `releasePledge`: Allows a module to release a user's tokens.
 
 ## 3. Key Mechanisms & Concepts
 

diff --git a/docs/src/content/intro/README.md b/docs/src/content/intro/README.md
@@ -3,11 +3,11 @@
 Prophet presents a versatile and fully adaptable optimistic oracle solution, transcending the boundaries of conventional dispute resolution modules. With its emphasis on complete control and modularity across all aspects of the system, Prophet is an open-source public good for the Optimism community.
 
 ## Useful links
-- Explorer [https://prophet.tech/](https://prophet.tech/)
-- Discord
-- Documentation [https://docs.prophet.tech](https://docs.prophet.tech)
-- SDK Documentation
-- Dune Dashboard
+- [Explorer](https://prophet.tech/)
+- [Discord](https://discord.gg/hhvA9CuQRR)
+- [Documentation](https://docs.prophet.tech)
+<!-- - SDK Documentation -->
+- [Dune Dashboard](https://dune.com/defi_wonderland/prophet-metrics)
 
 ### Repositories
 - [Core Contracts](https://github.com/defi-wonderland/prophet-core)
@@ -17,7 +17,26 @@ Prophet presents a versatile and fully adaptable optimistic oracle solution, tra
 - [SDK](https://github.com/defi-wonderland/prophet-sdk)
 
 ## Deployments
-<!-- TODO: List all contracts here -->
+The addresses of the contracts deployed on Optimism Goerli are listed below.
+
+| Contract | Goerli |
+| -------- | ------ |
+| [Oracle](/solidity/interfaces/core/IOracle.sol/interface.IOracle.md) | [`0x0000000000000000000000000000000000000000`](https://goerli-optimism.etherscan.io/address/0x0000000000000000000000000000000000000000) |
+| [AccountingExtension](/solidity/interfaces/extensions/IAccountingExtension.sol/interface.IAccountingExtension.md) | [`0x0000000000000000000000000000000000000000`](https://goerli-optimism.etherscan.io/address/0x0000000000000000000000000000000000000000) |
+| [BondEscalationAccounting](/solidity/interfaces/extensions/IBondEscalationAccounting.sol/interface.IBondEscalationAccounting.md) | [`0x0000000000000000000000000000000000000000`](https://goerli-optimism.etherscan.io/address/0x0000000000000000000000000000000000000000) |
+| [HttpRequestModule](/solidity/interfaces/modules/request/IHttpRequestModule.sol/interface.IHttpRequestModule.md) | [`0x0000000000000000000000000000000000000000`](https://goerli-optimism.etherscan.io/address/0x0000000000000000000000000000000000000000) |
+| [ContractCallRequestModule](/solidity/interfaces/modules/request/IContractCallRequestModule.sol/interface.IContractCallRequestModule.md) | [`0x0000000000000000000000000000000000000000`](https://goerli-optimism.etherscan.io/address/0x0000000000000000000000000000000000000000) |
+| [SparseMerkleTreeRequestModule](/solidity/interfaces/modules/request/ISparseMerkleTreeRequestModule.sol/interface.ISparseMerkleTreeRequestModule.md) | [`0x0000000000000000000000000000000000000000`](https://goerli-optimism.etherscan.io/address/0x0000000000000000000000000000000000000000) |
+| [BondedResponseModule](/solidity/interfaces/modules/response/IBondedResponseModule.sol/interface.IBondedResponseModule.md) | [`0x0000000000000000000000000000000000000000`](https://goerli-optimism.etherscan.io/address/0x0000000000000000000000000000000000000000) |
+| [BondedDisputeModule](/solidity/interfaces/modules/dispute/IBondedDisputeModule.sol/interface.IBondedDisputeModule.md) | [`0x0000000000000000000000000000000000000000`](https://goerli-optimism.etherscan.io/address/0x0000000000000000000000000000000000000000) |
+| [BondEscalationModule](/solidity/interfaces/modules/dispute/IBondEscalationModule.sol/interface.IBondEscalationModule.md) | [`0x0000000000000000000000000000000000000000`](https://goerli-optimism.etherscan.io/address/0x0000000000000000000000000000000000000000) |
+| [CircuitResolverModule](/solidity/interfaces/modules/dispute/ICircuitResolverModule.sol/interface.ICircuitResolverModule.md) | [`0x0000000000000000000000000000000000000000`](https://goerli-optimism.etherscan.io/address/0x0000000000000000000000000000000000000000) |
+| [RootVerificationModule](/solidity/interfaces/modules/dispute/IRootVerificationModule.sol/interface.IRootVerificationModule.md) | [`0x0000000000000000000000000000000000000000`](https://goerli-optimism.etherscan.io/address/0x0000000000000000000000000000000000000000) |
+| [ArbitratorModule](/solidity/interfaces/modules/resolution/IArbitratorModule.sol/interface.IArbitratorModule.md) | [`0x0000000000000000000000000000000000000000`](https://goerli-optimism.etherscan.io/address/0x0000000000000000000000000000000000000000) |
+| [BondEscalationResolutionModule](/solidity/interfaces/modules/resolution/IBondEscalationResolutionModule.sol/interface.IBondEscalationResolutionModule.md) | [`0x0000000000000000000000000000000000000000`](https://goerli-optimism.etherscan.io/address/0x0000000000000000000000000000000000000000) |
+| [ERC20ResolutionModule](/solidity/interfaces/modules/resolution/IERC20ResolutionModule.sol/interface.IERC20ResolutionModule.md) | [`0x0000000000000000000000000000000000000000`](https://goerli-optimism.etherscan.io/address/0x0000000000000000000000000000000000000000) |
+| [PrivateERC20ResolutionModule](/solidity/interfaces/modules/resolution/IPrivateERC20ResolutionModule.sol/interface.IPrivateERC20ResolutionModule.md) | [`0x0000000000000000000000000000000000000000`](https://goerli-optimism.etherscan.io/address/0x0000000000000000000000000000000000000000) |
+<!-- | [SequentialResolutionModule](/solidity/interfaces/modules/resolution/SequentialResolutionModule.sol/interface.SequentialResolutionModule.md) | [`0x0000000000000000000000000000000000000000`](https://goerli-optimism.etherscan.io/address/0x0000000000000000000000000000000000000000) | -->
 
 ## Licensing