# 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-chain`Supplier`

/`Application`

interaction during the Relay request & response.`Merkle Proof Selection`

: Proof of the amount of work done by the`Supplier`

during the`Session`

.

TODO_DOCUMENT: 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
`Application`

signing the`Relay Request`

is decreased through burn - The account balance of the
`Supplier`

owner 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.