From 5717ff071336befba4b8c7b80758588e93e4fb6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adam=20Uhl=C3=AD=C5=99?= Date: Thu, 26 Jun 2025 09:58:38 +0200 Subject: [PATCH] docs: upgrade documentation and tweaks --- License.md => LICENSE.md | 0 Readme.md => README.md | 148 ++++++++++++++++++++++----------------- 2 files changed, 85 insertions(+), 63 deletions(-) rename License.md => LICENSE.md (100%) rename Readme.md => README.md (50%) diff --git a/License.md b/LICENSE.md similarity index 100% rename from License.md rename to LICENSE.md diff --git a/Readme.md b/README.md similarity index 50% rename from Readme.md rename to README.md index 7466796..78380c0 100644 --- a/Readme.md +++ b/README.md @@ -1,13 +1,10 @@ -Codex Contracts -================ +# Codex Marketplace Contracts -An experimental implementation of the smart contracts that underlay the Codex -storage network. Its goal is to experiment with the rules around the bidding -process, the storage contracts, the storage proofs and the host collateral. -Neither completeness nor correctness are guaranteed at this moment in time. +An implementation of the smart contracts that underlay the Codex +storage network. Its goal is to facilitate storage marketplace +for the Codex's persistance layer. -Running -------- +## Running To run the tests, execute the following commands: @@ -22,8 +19,22 @@ To start a local Ethereum node with the contracts deployed, execute: npm start -Deployment ----------- +### Running the prover + +To run the formal verification rules using Certora, first, make sure you have Java (JDK >= 11.0) installed on your +machine, and then install the Certora CLI + +``` +$ pip install certora-cli +``` + +Once that is done the `certoraRun` command can be used to send CVL specs to the prover. + +You can run Certora's specs with the provided `npm` script: + + npm run verify + +## Deployment To deploy the marketplace, you need to specify the network using `--network MY_NETWORK`: @@ -31,9 +42,10 @@ To deploy the marketplace, you need to specify the network using `--network MY_N npm run deploy -- --network localhost ``` -Hardhat uses [reconciliation](https://hardhat.org/ignition/docs/advanced/reconciliation) to recover from -errors or resume a previous deployment. In our case, we will likely redeploy a new contract every time, -so we will need to [clear the previous deployment](https://hardhat.org/ignition/docs/guides/modifications#clearing-an-existing-deployment-with-reset): +Hardhat uses [reconciliation](https://hardhat.org/ignition/docs/advanced/reconciliation) to recover from +errors or resume a previous deployment. In our case, we will likely redeploy a new contract every time, +so we will need +to [clear the previous deployment](https://hardhat.org/ignition/docs/guides/modifications#clearing-an-existing-deployment-with-reset): ```bash npm run deploy -- --network testnet --reset @@ -46,26 +58,53 @@ instead of deploying a new one. When deploying to other network then Hardhat localhost's, you have to specify the Proxy's owner address using the env. variable `PROXY_ADMIN_ADDRESS`. This account then can perform upgrades to the contract. -The deployment files are kept under version control [as recommended by Hardhat](https://hardhat.org/ignition/docs/advanced/versioning), except the build files, which are 18 MB. +The deployment files are kept under version +control [as recommended by Hardhat](https://hardhat.org/ignition/docs/advanced/versioning), except the build files, +which are 18 MB. -Running the prover ------------------- +## Smart contracts overview -To run the formal verification rules using Certora, first, make sure you have Java (JDK >= 11.0) installed on your machine, and then install the Certora CLI +This contract suite deploys two smart contracts: -``` -$ pip install certora-cli -``` +1. `Marketplace` smart contract +2. `Vault` smart contract -Once that is done the `certoraRun` command can be used to send CVL specs to the prover. +The `Marketplace` smart contract implements the storage marketplace logic. Its internal logic is divided into +multiple abstract subcontracts that focus on specific pieces like `Periods`, `Proofs`, `SlotReservations`, and so on, +which are all bundled at the top level of the `Marketplace` contract itself. -You can run Certora's specs with the provided `npm` script: +The `Vault` smart contract is a specialized contract designed to safely keep users' funds. It is utilized by the +`Marketplace` contract to delegate all funds' safe-keeping to it. There are several mechanisms in the `Vault` contract +that should prevent a complete "grab & run" of all the funds in case an exploit is found in the `Marketplace` smart +contract. - npm run verify +### Upgradability +The `Marketplace` contract employs the contract's upgradability pattern using [ +`TransparentUpgradeableProxy`](https://docs.openzeppelin.com/contracts/5.x/api/proxy#TransparentUpgradeableProxy), which +allows replacing the underlying implementation while preserving the contract address and its storage. The upgrade can be +performed only by the account that is specified during the initial deployment through the `PROXY_ADMIN_ADDRESS` +environment variable. This capability is dedicated to emergency upgrades, as described in +our [Codex Contract Deployment, Upgrades and Security](https://github.com/codex-storage/codex-research/blob/master/design/contract-deployment.md) +document. -Overview --------- +The steps to perform an emergency upgrade are: + +1. Create a new `Marketplace` contract that will incorporate the changes. Name it, for example, `MarketplaceV2`. + - The original `Marketplace` and its abstract subcontracts should not be edited once deployed. + - If you need to make changes in one of the abstract subcontracts, also create a new version copy like `PeriodsV2`. + - **Do not modify any storage variables in the contract!** The upgrade mechanism is not designed for this. +2. Create a new Ignition deployment script that will perform the upgrade. + - Take inspiration from the `marketplace-test-upgrade` module, which performs the upgrade in our test suite. + - The upgrading transaction needs to originate from the account that was specified as `PROXY_ADMIN_ADDRESS` in the + initial deployment. +3. Deploy the upgrade with `hardhat ignition deploy --network `. + +Once the new feature upgrade is planned, the first step when drafting this new version is to reconcile all +the upgrade's changes (if there were any) back into the `Marketplace` contract and any modified subcontract +on the new feature branch. + +## Marketplace overview The Codex storage network depends on hosts offering storage to clients of the network. The smart contracts in this repository handle interactions between @@ -91,16 +130,18 @@ When all goes well, the client and hosts perform the following steps: | | | <-- payment (5) ---- | - 1. Client submits a request for storage, containing the size of the data that - it wants to store and the length of time it wants to store it - 2. Client makes the data available to hosts - 3. Hosts submit storage proofs to fill slots in the contract - 4. While the storage contract is active, host prove that they are still - storing the data by responding to frequent random challenges - 5. At the end of the contract the hosts are paid +1. Client submits a request for storage, containing the size of the data that + it wants to store and the length of time it wants to store it +2. Client makes the data available to hosts +3. Hosts submit storage proofs to fill slots in the contract +4. While the storage contract is active, host prove that they are still + storing the data by responding to frequent random challenges +5. At the end of the contract the hosts are paid -Contracts ---------- +For full overview +see [Codex Marketplace specification](https://github.com/codex-storage/codex-spec/blob/master/specs/marketplace.md). + +### Storage Contracts A storage contract contains of a number of slots. Each of these slots represents an agreement with a storage host to store a part of the data. Hosts that want to @@ -116,8 +157,7 @@ When a new storage contract is created the client immediately pays the entire price of the contract. The payment is only released to the host upon successful completion of the contract. -Collateral ----------- +### Collateral To motivate a host to remain honest, it must put up some collateral before it is allowed to participate in storage contracts. The collateral may not be withdrawn @@ -126,8 +166,7 @@ as long as a host is participating in an active storage contract. Should a host be misbehaving, then its collateral may be reduced by a certain percentage (slashed). -Proofs ------- +### Proofs Hosts are required to submit frequent proofs while a contract is active. These proofs ensure with a high probability that hosts are still holding on to the @@ -145,29 +184,12 @@ When that time has expired without seeing a proof, validators are able to point out the lack of proof. If a host misses too many proofs, it results into a slashing of its collateral. -References ----------- +## References - * [A marketplace for storage - durability](https://github.com/codex-storage/codex-research/blob/master/design/marketplace.md) - (design document) - * [Timing of Storage - Proofs](https://github.com/codex-storage/codex-research/blob/master/design/storage-proof-timing.md) - (design document) - -To Do ------ - - * Contract repair - - Allow another host to take over a slot in the contract when the original - host missed too many proofs. - - * Reward validators - - A validator that points out missed proofs should be compensated for its - vigilance and for the gas costs of invoking the smart contract. - - * Analysis and optimization of gas usage - -[echidna]: https://github.com/crytic/echidna +* [A marketplace for storage + durability](https://github.com/codex-storage/codex-research/blob/master/design/marketplace.md) + (design document) +* [Timing of Storage + Proofs](https://github.com/codex-storage/codex-research/blob/master/design/storage-proof-timing.md) + (design document) +* [Codex Marketplace spec](https://github.com/codex-storage/codex-spec/blob/master/specs/marketplace.md)