Claim & Proof Lifecycle

This part of the documentation is an INITIAL DRAFT and requires deep understanding of the Pocket Network protocol. It is intended as a reference and does not provide a fully coherent narrative for all readers.

Introduction

The Claim & Proof lifecycle is a fundamental part of the Pocket Network protocol.

At a high-level, it is an adaptation of the well-known commit & reveal paradigm used in various blockchain applications such as ENS.

For the purpose of explaining the Claim & Proof lifecycle, gateways are omitted and it is assumed that Applications interact directly with Suppliers.

Session Windows & Onchain Parameters

TODO(@bryanchriswhite): Add message distribution offsets/windows to this picture.

NB: Depicted with the default values (see below); x-axis 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 blocks. 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

• pocket.shared.Params / sharedtypes.Params

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:

1

Reason 1

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.

2

Reason 2

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.

3

Reason 3

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 prerequisite 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 offchain, 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 phases:

1

After Session: Recompute & Store

• Recompute SMST root & sum (compute units).

• Flush and store SMST to local disk.

2

Create Claim (Supplier)

• Supplier creates claim locally.

• Wait for the Claim Window to open.

• Submit CreateClaim transaction with root, sum, session info (app, supplier, service, etc.).

• Claim is stored onchain.

3

Submit Proof (Supplier)

• Wait for Proof Window to open.

• Retrieve seed (entropy) from onchain data (e.g., block hash).

• Generate Merkle proof for path in SMST based on seed.

• Submit SubmitProof transaction (session, merkle proof, leaf, etc.).

• Proof stored onchain.

4

Proof Validation & Settlement (Protocol)

• Retrieve onchain claims that need settlement.

• Retrieve corresponding onchain proofs for every claim.

• Validate leaf difficulty and Merkle proof, validate leaf signature.

• Burn application stake proportional to sum.

• Inflate supplier balance proportional to sum.

Claim

A Claim is a structure submitted onchain by a Supplier claiming to have done some amount of work in servicing relays for an 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" necessary to service that request.

Protobuf Types

Type	Description
Claim	A serialized version of the Claim is stored onchain.
MsgCreateClaim	Submitted by a Supplier to store a claim onchain.

CreateClaim Validation

When the network receives a MsgCreateClaim message, before the claim is persisted onchain, it MUST be validated:

• Validate_Claim

• Validate_Session_Header

• Validate_Claim_Window

• Validate_Basic

Common basic validation errors include:

• invalid supplier operator address

• session start height < 0

• empty session ID

• invalid service

References

• Create claim message basic validation (MsgCreateClaim#ValidateBasic())

• Session header validation (diagram / msgServer#queryAndValidateSessionHeader())

• Onchain claim window validation (diagram / msgServer#validateClaimWindow())

Claim Window

After a Session ends, a Supplier has several blocks (the Claim Window) to submit a CreateClaim transaction containing a Claim. If submitted too early or too late, it will be rejected.

If a Supplier fails to submit a Claim during the Claim Window, it forfeits potential rewards for the work done.

See Session Windows & Onchain Parameters for details.

Proof

A Proof is a structure submitted onchain 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 onchain.
MsgSubmitProof	Submitted by a Supplier to store a proof onchain. 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 onchain, it MUST be validated:

• Validate_Proof

  • incorrect closest Merkle proof path

  • insufficient relay difficulty

  • incorrect closest Merkle proof

• Proof_Validate_Basic

• Validate_Session_Header

• Validate_Proof_Window

• Closest_Proof_Path_Verification_Error

• Relay_Difficulty_Error

• Validate_Claim_For_Proof

• Closest_Proof_Verification_Error

• Unpack_Proven_Relay

  • cannot unmarshal closest proof

  • cannot unmarshal relay

• Closest_Proof_Unmarshal_Error

• Relay_Unmarshal_Error

• Validate_Proven_Relay

  • Validate_Relay_Request

  • Validate_Relay_Response

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 (the Proof Window) to submit a SubmitProof transaction containing a Proof. If submitted too early or too late, it will be rejected.

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. See Claim Expiration.

See Session Windows & Onchain Parameters for details.

Proof Security

In addition to basic validation as part of processing SubmitProof, there are deeper cryptographic validations:

1. Merkle Leaf Validation: Proof of the offchain Supplier / Application interaction during the Relay request & response.

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

Key components of every leaf in the Sparse Merkle Sum Trie (SMST):

• Signed Relay Request (Relay Request Data, ApplicationSignature, Metadata, Session, Weight)

• Signed Relay Response (Relay Response Data, SupplierSignature)

• Sparse Merkle Sum Trie Leaf

After the leaf is validated onchain as part of Proof Validation:

• The stake of the Application signing the Relay Request is decreased through burn.

• The account balance of the Supplier owner is increased through mint.

Merkle Proof Selection

Before the leaf itself is validated, there must be a valid Merkle proof for the pseudo-random path computed onchain. Because the path uses an onchain seed after the Claim has been submitted, it cannot be known in advance.

Assume a collision resistant hash function H that takes the block header hash as the seed and maps it to a path in the Merkle Trie key space.

Example: Sparse Merkle Sum Trie (SMST)

Below is an illustrative SMST example where paths are at most 5 bits. Extension nodes are omitted 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 diagram omitted here — refer to original source for visual.)

Example 1: Path to leaf at full depth (path = 0b11111)

(Example diagram omitted here — refer to original source for visual.)

Example 2: Path to leaf at partial depth (path = 0b01100)

(Example diagram omitted here — refer to original source for visual.)

Example 3: Path to empty node (path = 0b100xx -> 0b10000)

(Example diagram omitted here — refer to original source for visual.)

Full Lifecycle

The following diagram (from the Relay Mining whitepaper) provides an alternate view of the full lifecycle for reference.

(Reference diagram omitted — see the Relay Mining whitepaper for original.)

Reference Diagrams

The following reference validations describe various checks performed during claim & proof processing.

Session Header Validation

• Validate_Session_Header

  • get session error

  • claim & onchain session ID mismatch

  • claim supplier not in session

  • Get_Session

  • Session_Header_Validation_Error

Proof Basic Validation

• Proof_Validate_Basic

  • invalid supplier operator address

  • invalid app address

  • empty service ID

  • empty merkle proof

  • Basic_Validation_error

Proof Submission Relay Request Validation

• Validate_Relay_Request

  • Validate_Relay_Request_Basic

    • invalid relay request session header

    • invalid relay request ring signature

  • Validate_Relay_Request_Session_Header*

  • Relay_Request_Validation_Error

  • Compare_Relay_Request_Session_Header

  • Compare_Session_Header_To_Proof(Relay_Request)

  • Relay_Request_&_Proof_Session_Mismatch_Error

  • Validate_Relay_Request_Signature

    • empty relay request metadata

    • empty application ring (request) signature

    • malformed application ring (request) signature

    • empty application address

    • cannot construct application ring

    • wrong application ring

    • invalid application ring (request) signature

  • Relay_Request_Signature_Error

Proof Submission Relay Response Validation

• Validate_Relay_Response

  • Validate_Relay_Response_Basic

    • empty relay response metadata

    • invalid relay response session header

    • empty supplier (response) signature

  • Relay_Response_Validation_Error

  • Validate_Relay_Response_Session_Header*

  • Compare_Relay_Response_Session_Header

  • Compare_Session_Header_To_Proof(Relay_Response)

  • Relay_Response_&_Proof_Session_Mismatch_Error

  • Validate_Relay_Response_Signature

    • no supplier public key onchain

    • cannot unmarshal supplier (response) signature

  • Relay_Response_Signature_Error

Proof Session Header Comparison

• Compare_Session_Header_To_Proof

  • proof msg application address mismatch

  • proof msg service ID mismatch

  • proof msg session start mismatch

  • proof msg session end mismatch

  • proof msg session ID mismatch

  • Session_Header_Mismatch_Error

Proof Submission Claim Validation

• Validate_Claim_For_Proof

  • claim not found

  • proof session start mismatch

  • proof session end mismatch

  • proof application address mismatch

  • proof service ID mismatch

  • Claim_Validation_Error

Additional References (in-source)

• Session; Claim; Proof diagrams and code references linked throughout the document (proto definitions and message validation functions) are retained inline where present in the original content.