logos-storage-spec/specs/marketplace.md

title	name	status	tags	editor	contributors
CODEX-MARKETPLACE	Codex Storage Marketplace	raw	codex	Dmitriy <dryajov@status.im>	Mark <mark@codex.storage> Adam <adam@codex.storage> Eric <eric@codex.storage> Jimmy Debe <jimmy@status.im>

Abstract

Codex Marketplace and its interactions are defined by a smart contract deployed on an EVM-compatible blockchain. This specification describes these interactions for the various roles within the network.

The document is intended for implementors of Codex nodes.

Motivation

The Codex network aims to create a peer-to-peer storage engine with robust data durability, data persistence guarantees, and a comprehensive incentive structure.

The marketplace is a critical component of the Codex network, serving as a platform where all involved parties interact to ensure data persistence. It provides mechanisms to enforce agreements and facilitate data repair when storage providers, abbreviated to SP in this document, fail to fulfill their duties.

Implemented as a smart contract on an EVM-compatible blockchain, the marketplace enables various scenarios where nodes assume one or more roles to maintain a reliable persistence layer for users.

Semantics

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in 2119.

The marketplace contract manages storage requests, maintains the state of allocated storage slots, orchestrates SP node rewards, collaterals, and storage proofs. A node that wishes to participate in the Codex persistence layer MUST implement one or more roles described below.

Definitions

Terminology	Description
storage provider (SP)	A node in the Codex network that provides storage services to the marketplace.
validator	A node that assists in identifying missing storage proofs.
client	A node that interacts with other nodes in the Codex network to store, locate, and retrieve data.
storage request or request	A request created by a client node to persist data on the Codex network.
slot or storage slot	A space allocated by the storage request to store a piece of the request's dataset.
marketplace contract	A smart contract implementing the marketplace functionality.
token	ERC20-based token used within the Codex network.

Roles

A node can assume one of the three main roles in the network: the client, SP node, and validator.

A client is a potentially short-lived node in the network with the purpose of persisting its data in the Codex persistence layer.

An SP node is a long-lived node providing storage for clients in exchange for profit. To ensure a reliable, robust service for clients, SP nodes are required to periodically provide proofs that they are persisting the data.

A validator ensures that SP nodes have submitted valid proofs each period where the smart contract required a proof to be submitted for slots filled by the SP node. A validator may be a long-lived or short-lived node. This role does not get penalized if deciding not to be a long-lived node.

Storage Request Lifecycle

The diagram below depicts the lifecycle of a storage request:

Client Role

A node implementing the client role mediates the persistence of data within the Codex network.

A client has two primary responsibilities:

• Requesting storage from the network by sending a storage request to the smart contract.
• Withdrawing funds from the storage requests previously created by the client.

Creating Storage Requests

When a user prompts the client node to create a storage request, the client node SHOULD receive the input parameters for the storage request from the user.

To create a request to persist a dataset on the Codex network, client nodes MUST split the dataset into data chunks, (c_1, c_2, c_3, \ldots, c_{n}). The data chunks are then encoded with the erasure coding method and the provided input parameters.

The applied erasure coding method, used on data being persisted all SP nodes, MUST be the Reed-Solomon algorithm. When dataset is encoded with different algorithm, the dataset will be inaccessible.

After encoding, data chunks are distributed over a number of slots. The final slot roots and other metadata MUST be placed into a Manifest (TODO: Manifest RFC). The CID for the Manifest MUST then be used as the cid for the stored dataset.

After the dataset is prepared, a client node MUST call the smart contract function requestStorage(request), providing the desired request parameters in the request parameter. The request parameter is of type Request:

struct Request {
  address client;
  Ask ask;
  Content content;
  uint256 expiry;
  byte32 nonce;
}
  
struct Ask {
  uint256 reward;
  uint256 collateral;
  uint256 proofProbability;
  uint256 duration;
  uint64 slots;
  uint256 slotSize;
  uint64 maxSlotLoss; 
}

struct Content {
  string cid;
  byte32 merkleRoot;
}

The the table below provides the description of the Request and the associated types attributes:

attribute	type	description
client	address	The Codex node requesting storage.
ask	Ask	Parameters of Request.
content	Content	The dataset that will be hosted with the storage request.
expiry	uint256	Timeout in seconds during which all the slots have to be filled, otherwise request will get cancelled. The final deadline timestamp is calculated at the moment the transaction is mined.
nonce	byte32	Random value to differentiate from other requests of same parameters. It SHOULD be a random byte array.
reward	uint256	Amount of tokens that will be awarded to SP nodes for finishing the storage request. It MUST be an amount of tokens offered per slot per second. The Ethereum address that submits the requestStorage() transaction MUST have approval for the transfer of at least an equivalent amount in tokens.
collateral	uint256	The amount of tokens that SP nodes MUST submit when they fill slots. Collateral is then slashed or forfeited if SP nodes fail to provide the service requested by the storage request (more information in the Slashing section). The Ethereum address that submits the fillSlot() transaction MUST have approval for the transfer of at least an amount required for collateral.
proofProbability	uint256	Determines the average frequency that a proof is required within a period: \frac{1}{proofProbability}. SP nodes are required to provide proofs of storage to the marketplace smart contract when challenged by the smart contract. To prevent hosts from only coming online when proofs are required, the frequency at which proofs are requested from SP nodes is stochastic and is influenced by the proofProbability parameter.
duration	uint256	Total duration of the storage request in seconds.
slots	uint64	The number of requested slots. The slots will all have the same size.
slotSize	uint256	Amount of storage per slot in bytes.
maxSlotLoss	uint64	Max slots that can be lost before data is considered to be lost.
cid	string	An identifier used to locate the Manifest representing the dataset. It MUST be a CIDv1, SHA-256 multihash and the data it represents SHOULD be discoverable in the network, otherwise the request will be eventually canceled.
merkleRoot	byte32	Merkle root of the dataset, used to verify storage proofs.

Renewal of Storage Requests

It should be noted that the marketplace does not support extending requests. It is REQUIRED that if the user wants to extend the duration of a request, a new request with the same CID must be created before the original request completes.

This ensures that the data will continue to persist in the network at the time when the new (or existing) SP nodes need to retrieve the complete dataset to fill the slots of the new request.

Withdrawing Funds

The client node SHOULD monitor the status of the requests it created. When a storage request enters the Cancelled state (this occurs when not all slots were filled before the expiry timeout), the client node SHOULD initiate the withdrawal of the remaining funds from the smart contract using the withdrawFunds(requestId) function.

• The request is considered Cancelled if no requestFulfilled(requestId) event is observed during the timeout specified by the value returned from the requestExpiresAt(requestId) function.
• The request is considered Failed when the RequestFailed(requestId) event is observed.
• The request is considered Finished after the interval specified by the value returned from the getRequestEnd(requestId) function.

Storage Provider Role

A Codex node acting as an SP node persists data across the network by hosting slots requested by clients in their storage requests.

The following tasks need to be considered when hosting a slot:

• Filling a slot
• Proving
• Repairing a slot
• Collecting request reward and collateral

Below is a diagram depicting states of a storage request including filling slots, proving, repair states:

                      ┌───────────┐                               
                      │ Cancelled │                               
                      └───────────┘                               
                            ▲                                     
                            │ Not all                             
                            │ Slots filled                        
                            │                                     
    ┌───────────┐    ┌──────┴─────────────┐           ┌─────────┐ 
    │ Submitted ├───►│ Slots Being Filled ├──────────►│ Started │ 
    └───────────┘    └────────────────────┘ All Slots └────┬────┘ 
                                            Filled         │      
                                                           │      
                                   ┌───────────────────────┘      
                           Proving ▼                              
    ┌────────────────────────────────────────────────────────────┐
    │                                                            │
    │                 Proof submitted                            │
    │       ┌─────────────────────────► All good                 │
    │       │                                                    │
    │ Proof required                                             │
    │       │                                                    │
    │       │         Proof missed                               │
    │       └─────────────────────────► After some time slashed  │
    │                                   eventually Slot freed    │
    │                                                            │
    └────────┬─┬─────────────────────────────────────────────────┘
             │ │                                      ▲           
             │ │                                      │           
             │ │ SP kicked out and Slot freed ┌───────┴────────┐  
All good     │ ├─────────────────────────────►│ Repair process │  
Time ran out │ │                              └────────────────┘  
             │ │                                                  
             │ │ Too many Slots freed         ┌────────┐          
             │ └─────────────────────────────►│ Failed │          
             ▼                                └────────┘          
       ┌──────────┐                                               
       │ Finished │                                               
       └──────────┘                                               

Filling Slots

When a new request is created, the StorageRequested(requestId, ask, expiry) event is emitted with the following properties:

• requestId - the ID of the request.
• ask - the specification of the request parameters. For details, see the definition of the Request type in the Creating Storage Requests section above.
• expiry - a Unix timestamp specifying when the request will be canceled if all slots are not filled by then.

Based on the emitted parameters and node's operator configuration, SP nodes decide whether it participate in the request by attempting to fill its slot(s). Note that one SP node can fill more than one slot. If the SP node decides to ignore the request, no further action is required. However, if the SP node decides to fill a slot, it MUST follow the remaining steps described below.

An SP node MUST decide which slot, specified by the slot index, it wants to fill. The SP node MAY attempt to fill more than one slot. To fill a slot, the SP node MUST first download the slot data using the CID of the manifest (TODO: Manifest RFC) and the slot index. The CID is specified in request.content.cid, which can be retrieved from the smart contract using getRequest(requestId). Then, the node MUST generate a proof over the downloaded data (TODO: Proving RFC).

When the proof is ready, the SP node MUST make a transaction calling fillSlot() on the smart contract with the following REQUIRED parameters:

• requestId - the ID of the request.
• slotIndex - the slot index that the node wants to fill.
• proof - the Groth16Proof proof structure, generated over the slot data.
• collateral - The amount of tokens required to fill a slot

The Ethereum address, of the SP node from which the transaction originates, MUST have approval for the transfer of at least the amount of required tokens.

If the proof delivered by the SP node is invalid or the slot was already filled by another SP node, then the transaction will revert. Otherwise, a SlotFilled(requestId, slotIndex) event is emitted. If the transaction is successful, the SP node SHOULD transition into the proving state, where it will need to submit proof of data possession when challenged by the smart contract.

It should be noted that if the SP node observes a SlotFilled event for the slot it is currently downloading the dataset for or generating the proof for, it means that the slot has been filled by another node in the meantime. In response, the SP node SHOULD stop its current operation and attempt to fill a different, unfilled slot.

Proving

Once an SP node fills a slot, it MUST submit proofs to the smart contract when a challenge is issued by the contract. SP nodes SHOULD detect that a proof is required for the current period using the isProofRequired(slotId) function, or that it will be required using the willProofBeRequired(slotId) function in the case that the pointer is in downtime.

Once an SP node knows it has to provide a proof, it MUST get the proof challenge using getChallenge(slotId) which then MUST be incorporated into the proof generation, as described in Proving RFC (TODO: Proving RFC).

When the proof is generated, it MUST be submitted by calling the submitProof(slotId, proof) smart contract function.

Slashing

There is a slashing scheme orchestrated by the smart contract to incentivize correct behavior and proper proof submissions by SP nodes. This scheme is configured at the smart contract level and applies uniformly to all participants in the network. The configuration of the slashing scheme can be obtained via the getConfig() contract call.

The slashing works as follows:

• An SP node MAY miss up to config.collateral.slashCriterion proofs before being slashed.
• It is then slashed by config.collateral.slashPercentage of the originally required collateral (hence the slashing amount is always the same for a given request).
• If the number of slashes exceeds config.collateral.maxNumberOfSlashes, the slot is freed, the remaining collateral is burned, and the slot is offered to other nodes for repair. The smart contract also emits the SlotFreed(requestId, slotIndex) event.

If, at any time, the number of freed slots exceeds the value specified by the request.ask.maxSlotLoss parameter, the dataset is considered lost, and the request is deemed failed. The collateral of all SP nodes that hosted the slots associated with the storage request is burned, and the RequestFailed(requestId) event is emitted.

Repair

When a slot is freed due to too many missed proofs, which SHOULD be detected by listening to the SlotFreed(requestId, slotIndex) event, an SP node can decide whether to participate in repairing the slot. Similar to filling a slot, the node SHOULD consider the operator's configuration when making this decision. The SP node that originally hosted the slot but failed to comply with proving requirements MAY also participate in the repair. However, by refilling the slot, the SP node will not recover its original collateral and must submit new collateral using the fillSlot() call.

The repair process is similar to filling slots. If the original slot dataset is no longer present in the network, the SP node MAY use erasure coding to reconstruct the dataset. Reconstructing the original slot dataset requires retrieving other pieces of the dataset stored in other slots belonging to the request. For this reason, the node that successfully repairs a slot is entitled to an additional reward. (TODO: Implementation)

The repair process proceeds as follows:

1. The SP node observes the SlotFreed event and decides to repair the slot.
2. The SP node MUST download the chunks of data required to reconstruct the freed slot's data. The node MUST use the Reed-Solomon algorithm to reconstruct the missing data.
3. The SP node MUST generate proof over the reconstructed data.
4. The SP node MUST call the fillSlot() smart contract function with the same parameters and collateral allowance as described in the Filling Slots section.

Collecting Funds

An SP node SHOULD monitor the requests and the associated slots it hosts.

When a storage request enters the Cancelled, Finished, or Failed state, the SP node SHOULD call the freeSlot(slotId) smart contract function.

The aforementioned storage request states (Cancelled, Finished, and Failed) can be detected as follows:

• A storage request is considered Cancelled if no RequestFulfilled(requestId) event is observed within the time indicated by the expiry request parameter. Note that a RequestCancelled event may also be emitted, but the node SHOULD NOT rely on this event to assert the request expiration, as the RequestCancelled event is not guaranteed to be emitted at the time of expiry.
• A storage request is considered Finished when the time indicated by the value returned from the getRequestEnd(requestId) function has elapsed.
• A node concludes that a storage request has Failed upon observing the RequestFailed(requestId) event.

For each of the states listed above, different funds are handled as follows:

• In the Cancelled state, the collateral is returned along with a proportional payout based on the time the node actually hosted the dataset before the expiry was reached.
• In the Finished state, the full reward for hosting the slot, along with the collateral, is collected.
• In the Failed state, no funds are collected. The reward is returned to the client, and the collateral is burned. The slot is removed from the list of slots and is no longer included in the list of slots returned by the mySlots() function.

Validator Role

In a blockchain, a contract cannot change its state without a transaction and gas initiating the state change. Therefore, our smart contract requires an external trigger to periodically check and confirm that a storage proof has been delivered by the SP node. This is where the validator role is essential.

The validator role is fulfilled by nodes that help to verify that SP nodes have submitted the required storage proofs.

It is the smart contract that checks if the proof requested from an SP node has been delivered. The validator only triggers the decision-making function in the smart contract. To incentivize validators, they receive a reward each time they correctly mark a proof as missing.

Each time a validator observes the SlotFilled event, it SHOULD add the slot reported in the SlotFilled event to the validator's list of watched slots. Then, after the end of each period, a validator has up to config.proofs.timeout seconds (a configuration parameter retrievable with getConfig()) to validate all the slots. If a slot lacks the required proof, the validator SHOULD call the markProofAsMissing(slotId, period) function on the smart contract. This function validates the correctness of the claim, and if right, will send a reward to the validator.

If validating all the slots observed by the validator is not feasible within the specified timeout, the validator MAY choose to validate only a subset of the observed slots.

Copyright

Copyright and related rights waived via CC0.

References

1. Reed-Solomon algorithm
2. CIDv1
3. multihash
4. Proof-of-Data-Possession
5. Codex market implementation