Claim & Proof Lifecycle
This part of the documentation is just an INITIAL DRAFT and requires deep understanding of the Pocket Network protocol. It is currently aiming to just be a reference and not provide a coherent narrative that is easily accessible to all readers.
- Introduction
- Session Windows & On-Chain Parameters
- Session
- Claim
- Proof
- Proof Security
- Full Lifecycle
- Reference Diagrams
Introduction
The Claim & Proof lifecycle is a fundamental part of the Pocket Network protocol.
At a high-level, it is an adaptation of a well-known commit & reveal paradigm used
in various blockchain application such as ENS.
For the purpose of explaining the Claim & Proof lifecycle, we will remove
Gateways from the discussion and assume that Applications are directly
interacting with the Suppliers.
Session Windows & On-Chain Parameters
TODO(@bryanchriswhite): Add message distribution offsets/windows to this picture.
NB: Depicted with the default values (see below); x-axis is units are blocks.
| Parameter | Description | Default |
|---|---|---|
num_blocks_per_session | The number of blocks between the session start & end heights. Relays handled in these blocks are included in session N. It is positively correlated with the number of relays in (i.e. size of) each session tree for each session number (less other scaling factors; e.g. relaymining). | 4 |
grace_period_end_offset_blocks | The number of blocks after the session end height, at which the grace period ends. Valid relays from both sessions N and N +1 are accepted in these blocks. It is positively correlated to the amount of time gateways have to transition sending relays to suppliers in the next session. | 1 |
claim_window_open_offset_blocks | The number of blocks after the session end height, at which the claim window opens. Valid relays from both sessions N and N +1 are accepted in these blocks. Valid claims for session N will be rejected in these blocks. This parameter MUST NOT be less than grace_period_end_offset_blocks. It is positively correlated with the number of relays in (i.e. size of) each session tree for each session number (less other scaling factors; e.g. relaymining). | 1 |
claim_window_close_offset_blocks | The number of blocks after the claim window open height, at which the claim window closes. Valid claims for session N will be accepted in these blocks. It is negatively correlated with density of claim creation (and update) messages over blocks in a given session number. | 4 |
proof_window_open_offset_blocks | The number of blocks after the claim window close height, at which the proof window opens. Valid proofs for session N will be rejected in these block. It is positively correlated with the amount of time suppliers MUST persist the complete merkle trees for unproven sessions (proof path is revealed at earliest_supplier_proof_commit_height - 1). | 0 |
proof_window_close_offset_blocks | The number of blocks after the proof window open height, at which the proof window closes. Valid proofs for session N will be accepted in these blocks. It is negatively correlated with the density of proof submission messages over blocks in a given session number. | 4 |
References:
Claim Expiration
If a claim requires a proof (as determined by Probabilistic Proofs) and a Supplier fails
to submit a Proof before the Proof Window closes, the claim will expire and the Supplier will forfeit any
rewards for the work done.
Claims MUST expire (and therefore the proof window MUST close) for the following reasons:
- The mint & burn associated with a given claim's settlement MUST occur while the application stake is still locked and applications must be allowed to complete unstaking in finite time.
- Claim settlement SHOULD be limited to considering claims created within a rolling window of blocks to decouple settlement from a long-tail accumulation of unsettled claims.
- Proofs MUST be pruned to prevent network state bloat over time. Pruning proofs makes the number of proofs in network state at any given time a function of recent relay demand.
Session
A session is a necessary pre-requisite for the Claim & Proof lifecycle to work.
See Session for more details.
Session Duration
After a session is initiated, the majority of it is handled off-chain,
as Applications make RPC requests (relays) to the Supplier.
Session End
After a session ends, the Claim & Proof Lifecycle can be decomposed, at a high-level, into the following steps.
Claim
A Claim is a structure submitted on-chain by a Supplier claiming to have done
some amount of work in servicing relays for Application.
Exactly one claim exists for every (Application, Supplier, Session).
A Claim forces a Supplier to commit to have done sum work during a Session for
a certain Application. The sum in the root of the SMST is the amount of work
done. Each leaf has a different weight depending on the number of "compute units"
that were necessary to service that request.
Protobuf Types
| Type | Description |
|---|---|
Claim | A serialized version of the Claim is stored on-chain. |
MsgCreateClaim | Submitted by a Supplier to store a claim on-chain. |
CreateClaim Validation
When the network receives a MsgCreateClaim message, before the claim is persisted
on-chain, it MUST be validated:
References:
- Create claim message basic
validation (
MsgCreateClaim#ValidateBasic()) - Session header
validation (diagram /
msgServer#queryAndValidateSessionHeader()) - On-chain claim window
validation (diagram /
msgServer#validateClaimWindow())
Claim Window
After a Session ends, a Supplier has several blocks, a Claim Window, to submit
a CreateClaim transaction containing a Claim. If it is submitted too early
or too late, it will be rejected by the protocol.
If a Supplier fails to submit a Claim during the Claim Window, it will forfeit
any potential rewards it could earn in exchange for the work done.
See Session Windows & On-Chain Parameters for more details.
Proof
A Proof is a structure submitted on-chain by a Supplier containing a Merkle
Proof to a single pseudo-randomly selected leaf from the corresponding Claim.
At most one Proof exists for every Claim.
A Proof is necessary for the Claim to be validated so the Supplier can be
rewarded for the work done.
Protobuf Types
| Type | Description |
|---|---|
Proof | A serialized version of the Proof is stored on-chain. |
MsgSubmitProof | Submitted by a Supplier to store a proof on-chain. If the Proof is invalid, or if there is no corresponding Claim for the Proof, the transaction will be rejected. |
SubmitProof Validation
When the network receives a MsgSubmitProof message, before the proof is accepted
on-chain, it MUST be validated:
References:
- Proof basic
validation (diagram /
MsgSubmitProof#ValidateBasic()) - Session header
validation (diagram /
msgServer#queryAndValidateSessionHeader()) - Proof window
validation (diagram /
msgServer#validateProofWindow()) - Proven relay request
validation (diagram /
RelayRequest#ValidateBasic()) - Proven relay response
validation (diagram /
RelayResponse#ValidateBasic()) - Proof claim
validation (diagram /
msgServer#queryandValidateClaimForProof())
Proof Window
After the Proof Window opens, a Supplier has several blocks, a Proof Window,
to submit a SubmitProof transaction containing a Proof. If it is submitted too
early or too late, it will be rejected by the protocol.
If a proof is required (as determined by Probabilistic Proofs) and a Supplier fails to
submit a Proof during the Proof Window, the Claim will expire, and the supplier will forfeit rewards for the claimed
work done. See Claim Expiration for more.
See Session Windows & On-Chain Parameters for more details.
Proof Security
In addition to basic validation as part of processing SubmitProof to determine
whether or not the Proof should be stored on-chain, there are several additional
deep cryptographic validations needed:
Merkle Leaf Validation: Proof of the off-chainSupplier/Applicationinteraction during the Relay request & response.Merkle Proof Selection: Proof of the amount of work done by theSupplierduring theSession.
TODO: Link to tokenomics and data integrity checks for discussion once they are written.
Merkle Leaf Validation
The key components of every leaf in the Sparse Merkle Sum Trie are shown below.
After the leaf is validated, two things happen:
- The stake of
Applicationsigning theRelay Requestis decreased through burn - The account balance of the
Supplierowner is increased through mint
The validation on these signatures is done on-chain as part of Proof Validation.
Merkle Proof Selection
Before the leaf itself is validated, we need to make sure if there is a valid Merkle Proof for the associated pseudo-random path computed on-chain.
Since the path that needs to be proven uses an on-chain seed after the Claim
has been submitted, it is impossible to know the path in advance.
Assume a collision resistant hash function H that takes a the block header hash
as the seed and maps it to a path in the Merkle Trie key space.
Example: Example Sparse Merkle Sum Trie (SMST)
Below is an example of a Sparse Merkle Sum Trie where the paths can be at
most 5 bits (for example purposes).
Extension nodes are ommitted and shown via 0bxxxxx as part of the tree edges
Legend:
- 🟥 - Root node
- 🟦 - Inner node
- 🟩 - Leaf node
- 🟫 - Empty Node
- 🟨 - Included in Merkle Proof
- ⬚🟨 - Computed as Part of Merkle Proof
- ⬛ - Not used in the diagram node
Example 1: Path to leaf at full depth
Example 2: Path to leaf at partial depth
Example 3: Path to empty node
Full Lifecycle
The following diagram was taken from the Relay Mining whitepaper, and is an alternative view of the full lifecycle described above. It is here for reference purposes.