logos-storage/logos-storage-contracts-eth
1
0
Fork 0
mirror of https://github.com/logos-storage/logos-storage-contracts-eth.git synced 2026-01-07 15:53:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: upgrade documentation and tweaks

Browse Source
This commit is contained in:
Adam Uhlíř 2025-06-26 09:58:38 +02:00
parent 17cb41726b
commit 5717ff0713
No known key found for this signature in database
GPG Key ID: 1D17A9E81F76155B
2 changed files with 85 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

0
License.md → LICENSE.md
View File

132
Readme.md → README.md
View File

@ -1,13 +1,10 @@
Codex Contracts # Codex Marketplace Contracts
================
An experimental implementation of the smart contracts that underlay the Codex An implementation of the smart contracts that underlay the Codex
storage network. Its goal is to experiment with the rules around the bidding storage network. Its goal is to facilitate storage marketplace
process, the storage contracts, the storage proofs and the host collateral. for the Codex's persistance layer.
Neither completeness nor correctness are guaranteed at this moment in time.
Running ## Running
-------
To run the tests, execute the following commands: 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 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`: To deploy the marketplace, you need to specify the network using `--network MY_NETWORK`:
@ -33,7 +44,8 @@ npm run deploy -- --network localhost
Hardhat uses [reconciliation](https://hardhat.org/ignition/docs/advanced/reconciliation) to recover from 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, 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): so we will need
to [clear the previous deployment](https://hardhat.org/ignition/docs/guides/modifications#clearing-an-existing-deployment-with-reset):
```bash ```bash
npm run deploy -- --network testnet --reset 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 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. 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:
``` 1. `Marketplace` smart contract
$ pip install certora-cli 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 <new module> --network <deployment 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 The Codex storage network depends on hosts offering storage to clients of the
network. The smart contracts in this repository handle interactions between 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) ---- | | <-- payment (5) ---- |
1. Client submits a request for storage, containing the size of the data that 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 it wants to store and the length of time it wants to store it
2. Client makes the data available to hosts 2. Client makes the data available to hosts
3. Hosts submit storage proofs to fill slots in the contract 3. Hosts submit storage proofs to fill slots in the contract
4. While the storage contract is active, host prove that they are still 4. While the storage contract is active, host prove that they are still
storing the data by responding to frequent random challenges storing the data by responding to frequent random challenges
5. At the end of the contract the hosts are paid 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 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 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 price of the contract. The payment is only released to the host upon successful
completion of the contract. completion of the contract.
Collateral ### Collateral
----------
To motivate a host to remain honest, it must put up some collateral before it is 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 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 Should a host be misbehaving, then its collateral may be reduced by a certain
percentage (slashed). percentage (slashed).
Proofs ### Proofs
------
Hosts are required to submit frequent proofs while a contract is active. These 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 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 out the lack of proof. If a host misses too many proofs, it results into a
slashing of its collateral. slashing of its collateral.
References ## References
----------
* [A marketplace for storage * [A marketplace for storage
durability](https://github.com/codex-storage/codex-research/blob/master/design/marketplace.md) durability](https://github.com/codex-storage/codex-research/blob/master/design/marketplace.md)
(design document) (design document)
* [Timing of Storage * [Timing of Storage
Proofs](https://github.com/codex-storage/codex-research/blob/master/design/storage-proof-timing.md) Proofs](https://github.com/codex-storage/codex-research/blob/master/design/storage-proof-timing.md)
(design document) (design document)
* [Codex Marketplace spec](https://github.com/codex-storage/codex-spec/blob/master/specs/marketplace.md)
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