mirror of
https://github.com/logos-storage/logos-storage-contracts-eth.git
synced 2026-01-03 22:03:08 +00:00
docs: upgrade documentation and tweaks
This commit is contained in:
Adam Uhlíř
parent
17cb41726b
commit
5717ff0713
@ -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 <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
|
||||
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)
|
||||
Loading…
x
Reference in New Issue
Block a user