diff --git a/docusaurus/docs/protocol/primitives/claim_and_proof_lifecycle.md b/docusaurus/docs/protocol/primitives/claim_and_proof_lifecycle.md index 83c83080e..aaeb7376b 100644 --- a/docusaurus/docs/protocol/primitives/claim_and_proof_lifecycle.md +++ b/docusaurus/docs/protocol/primitives/claim_and_proof_lifecycle.md @@ -147,7 +147,45 @@ You can find the definition for the [CreateClaim Transaction here](https://githu ### CreateClaim Validation -_TODO_DOCUMENT(@bryanchriswhite, @Olshansk): Update this section once [msg_server_create_claim.go](https://github.com/pokt-network/poktroll/blob/main/proto/poktroll/x/proof/keeper/msg_server_create_claim.go) is fully implemented._ +When the network receives a [`MsgCreateClaim`](#TODO_link_to_MsgCreateClaim) message, before the claim is persisted +on-chain, it MUST be validated: + +```mermaid +stateDiagram-v2 + +[*] --> Validate_Claim +state Validate_Claim { + [*] --> Validate_Basic + + state Validate_Basic { + state if_session_start_gt_0 <> + state if_session_id_empty <> + state if_service_invalid <> + state if_supplier_addr_valid <> + + [*] --> if_supplier_addr_valid + if_supplier_addr_valid --> Basic_Validation_Error: invalid supplier address + if_supplier_addr_valid --> if_session_start_gt_0 + if_session_start_gt_0 --> Basic_Validation_Error: session start height < 0 + if_session_start_gt_0 --> if_session_id_empty + if_session_id_empty --> Basic_Validation_Error: empty session ID + if_session_id_empty --> if_service_invalid + if_service_invalid --> Basic_Validation_Error: invalid service + if_service_invalid --> [*] + } + + Validate_Basic --> Validate_Session_Header + Validate_Session_Header + Validate_Session_Header --> Validate_Claim_Window + Validate_Claim_Window -->[*] +} +Validate_Claim --> [*] +``` + +#### References: +- Create claim message basic validation ([`MsgCreateClaim#ValidateBasic()`](https://github.com/pokt-network/poktroll/blob/main/x/proof/types/message_create_claim.go)) +- Session header validation ([diagram](#session-header-validation) / [`msgServer#queryAndValidateSessionHeader()`](https://github.com/pokt-network/poktroll/blob/main/x/proof/keeper/session.go)) +- On-chain claim window validation ([diagram](#TODO) / [`msgServer#validateClaimWindow()`](https://github.com/pokt-network/poktroll/blob/main/x/proof/keeper/session.go)) ### Claim Window @@ -187,7 +225,61 @@ You can find the definition for the [SubmitProof Transaction here](https://githu ### SubmitProof Validation -_TODO_DOCUMENT(@bryanchriswhite, @Olshansk): Update this section once [msg_server_submit_proof.go](https://github.com/pokt-network/poktroll/blob/main/proto/poktroll/x/proof/keeper/msg_server_submit_proof.go) is fully implemented._ +When the network receives a [`MsgSubmitProof`](#TODO_link_to_MsgSubmitProof) message, before the proof is accepted +on-chain, it MUST be validated: + +```mermaid +stateDiagram-v2 +[*] --> Validate_Proof +state Validate_Proof { + [*] --> Proof_Validate_Basic + Proof_Validate_Basic --> Validate_Session_Header + Validate_Session_Header --> Validate_Proof_Window + Validate_Proof_Window --> Unpack_Proven_Relay + + state Unpack_Proven_Relay { + state if_closest_proof_malformed <> + state if_relay_valid <> + + [*] --> if_closest_proof_malformed + if_closest_proof_malformed --> Closest_Proof_Unmarshal_Error: cannot unmarshal closest proof + if_closest_proof_malformed --> if_relay_valid + if_relay_valid --> Relay_Unmarshal_Error: cannot unmarshal relay + if_relay_valid --> [*] + } + +Unpack_Proven_Relay --> Validate_Proven_Relay + +state Validate_Proven_Relay { + [*] --> Validate_Relay_Request + Validate_Relay_Request --> Validate_Relay_Response + Validate_Relay_Response --> [*] +} + +state if_closest_proof_path_valid <> +state if_relay_difficulty_sufficient <> + +Validate_Proven_Relay --> if_closest_proof_path_valid +if_closest_proof_path_valid --> Closest_Proof_Path_Verification_Error: incorrect closest Merkle proof path +if_closest_proof_path_valid --> if_relay_difficulty_sufficient +if_relay_difficulty_sufficient --> Relay_Difficulty_Error: insufficient relay difficulty +if_relay_difficulty_sufficient --> Validate_Claim_For_Proof + +state if_closest_proof_valid <> + Validate_Claim_For_Proof --> if_closest_proof_valid + if_closest_proof_valid --> Closest_Proof_Verification_Error: incorrect closest Merkle proof + if_closest_proof_valid --> [*] +} +Validate_Proof --> [*] +``` + +#### References: +- Proof basic validation ([diagram](#proof-basic-validation) / [`MsgSubmitProof#ValidateBasic()`](https://github.com/pokt-network/poktroll/blob/main/x/proof/types/message_submit_proof.go)) +- Session header validation ([diagram](#session-header-validation) / [`msgServer#queryAndValidateSessionHeader()`](https://github.com/pokt-network/poktroll/blob/main/x/proof/keeper/session.go)) +- Proof window validation ([diagram](#TODO) / [`msgServer#validateProofWindow()`](https://github.com/pokt-network/poktroll/blob/main/x/proof/keeper/session.go)) +- Proven relay request validation ([diagram](#proof-submission-relay-request-validation) / [`RelayRequest#ValidateBasic()`](https://github.com/pokt-network/poktroll/blob/main/x/service/types/relay.go)) +- Proven relay response validation ([diagram](#proof-submission-relay-response-validation) / [`RelayResponse#ValidateBasic()`](https://github.com/pokt-network/poktroll/blob/main/x/service/types/relay.go)) +- Proof claim validation ([diagram](#proof-submission-claim-validation) / [`msgServer#queryandValidateClaimForProof()`](https://github.com/pokt-network/poktroll/blob/main/x/proof/keeper/msg_server_submit_proof.go)) ### Proof Window @@ -502,3 +594,228 @@ sequenceDiagram W ->> -A: Token Burn (Decrease Application Stake) end ``` + +## Reference Diagrams + +### Session Header Validation + +```mermaid +stateDiagram-v2 + +[*] --> Validate_Session_Header + + +state Validate_Session_Header { + [*] --> Get_Session + state if_get_session_error <> + state if_session_id_mismatch <> + state if_supplier_found <> + Get_Session --> if_get_session_error + if_get_session_error --> Session_Header_Validation_Error: get session error + if_get_session_error --> if_session_id_mismatch + if_session_id_mismatch --> Session_Header_Validation_Error: claim & on-chain session ID mismatch + if_session_id_mismatch --> if_supplier_found + if_supplier_found --> Session_Header_Validation_Error: claim supplier not in session + if_supplier_found --> [*] +} + +Validate_Session_Header --> [*] +``` + +### Proof Basic Validation + +```mermaid +stateDiagram-v2 + + [*] --> Proof_Validate_Basic + + state Proof_Validate_Basic { + state if_supplier_addr_valid <> + state if_app_addr_valid <> + state if_service_id_empty <> + state if_proof_empty <> + [*] --> if_supplier_addr_valid + if_supplier_addr_valid --> Basic_Validation_error: invalid supplier address + if_supplier_addr_valid --> if_app_addr_valid + if_app_addr_valid --> Basic_Validation_error: invalid app address + if_app_addr_valid --> if_service_id_empty + if_service_id_empty --> Basic_Validation_error: empty service ID + if_service_id_empty --> if_proof_empty + if_proof_empty --> Basic_Validation_error: empty merkle proof + if_proof_empty --> [*] + } + + Proof_Validate_Basic --> [*] +``` + +### Proof Submission Relay Request Validation + +```mermaid +stateDiagram-v2 + +[*] --> Validate_Relay_Request +state Validate_Relay_Request { + + [*] --> Validate_Relay_Request_Basic + + state Validate_Relay_Request_Basic { + state if_request_valid <> + state if_request_signature_empty <> + [*] --> Validate_Relay_Request_Session_Header* + Validate_Relay_Request_Session_Header* --> if_request_valid + if_request_valid --> Relay_Request_Validation_Error: invalid relay request session header + if_request_valid --> if_request_signature_empty + if_request_signature_empty --> Relay_Request_Validation_Error: invalid relay request ring signature + if_request_signature_empty --> [*] + } + + Validate_Relay_Request_Basic --> Compare_Relay_Request_Session_Header + + state Compare_Relay_Request_Session_Header { + state if_req_session_header_mismatch <> + [*] --> Compare_Session_Header_To_Proof(Relay_Request) + Compare_Session_Header_To_Proof(Relay_Request) --> if_req_session_header_mismatch + if_req_session_header_mismatch --> Relay_Request_&_Proof_Session_Mismatch_Error + if_req_session_header_mismatch --> [*] + } + + Compare_Relay_Request_Session_Header --> Validate_Relay_Request_Signature + + state Validate_Relay_Request_Signature { + state if_request_meta_empty <> + state if_ring_sig_empty <> + state if_ring_sig_malformed <> + state if_app_addr_empty <> + state if_ring_valid <> + state if_ring_mismatch <> + state if_ring_sig_valid <> + + [*] --> if_request_meta_empty + if_request_meta_empty --> Relay_Request_Signature_Error: empty relay request metadata + if_request_meta_empty --> if_ring_sig_empty + if_ring_sig_empty --> Relay_Request_Signature_Error: empty application ring (request) signature + if_ring_sig_empty --> if_ring_sig_malformed + if_ring_sig_malformed --> Relay_Request_Signature_Error: malformed application ring (request) signature + if_ring_sig_malformed --> if_app_addr_empty + if_app_addr_empty --> Relay_Request_Signature_Error: empty application address + if_app_addr_empty --> if_ring_valid + if_ring_valid --> Relay_Request_Signature_Error: cannot construct application ring + if_ring_valid --> if_ring_mismatch + if_ring_mismatch --> Relay_Request_Signature_Error: wrong application ring + if_ring_mismatch --> if_ring_sig_valid + if_ring_sig_valid --> Relay_Request_Signature_Error: invalid application ring (request) signature + if_ring_sig_valid --> [*] + } + + Validate_Relay_Request_Signature --> [*] + +} +Validate_Relay_Request --> [*] +``` + +### Proof Submission Relay Response Validation + +```mermaid +stateDiagram-v2 + +[*] --> Validate_Relay_Response +state Validate_Relay_Response { + + [*] --> Validate_Relay_Response_Basic + + state Validate_Relay_Response_Basic { + state if_response_valid <> + state if_supplier_signature_empty <> + state if_response_meta_empty <> + [*] --> if_response_meta_empty + if_response_meta_empty --> Relay_Response_Validation_Error: empty relay resopnse metadata + if_response_meta_empty --> Validate_Relay_Response_Session_Header* + Validate_Relay_Response_Session_Header* --> if_response_valid + if_response_valid --> Relay_Response_Validation_Error: invalid relay response session header + if_response_valid --> if_supplier_signature_empty + if_supplier_signature_empty --> Relay_Response_Validation_Error: empty supplier (response) signature + if_supplier_signature_empty --> [*] + } + + Validate_Relay_Response_Basic --> Compare_Relay_Response_Session_Header + + state Compare_Relay_Response_Session_Header { + state if_res_session_header_mismatch <> + [*] --> Compare_Session_Header_To_Proof(Relay_Response) + Compare_Session_Header_To_Proof(Relay_Response) --> if_res_session_header_mismatch + if_res_session_header_mismatch --> Relay_Response_&_Proof_Session_Mismatch_Error + if_res_session_header_mismatch --> [*] + } + + Compare_Relay_Response_Session_Header --> Validate_Relay_Response_Signature + + state Validate_Relay_Response_Signature { + state if_supplier_pubkey_exists <> + state if_supplier_sig_malformed <> + + [*] --> if_supplier_pubkey_exists + if_supplier_pubkey_exists --> Relay_Response_Signature_Error: no supplier public key on-chain + if_supplier_pubkey_exists --> if_supplier_sig_malformed + if_supplier_sig_malformed --> Relay_Response_Signature_Error: cannot unmarshal supplier (response) signature + } + + Validate_Relay_Response_Signature --> [*] + +} +Validate_Relay_Response --> [*] +``` + +### Proof Session Header Comparison + +```mermaid +stateDiagram-v2 + +[*] --> Compare_Session_Header_To_Proof +state Compare_Session_Header_To_Proof { + state if_app_addr_mismatch <> + state if_service_id_mismatch <> + state if_session_start_mismatch <> + state if_session_end_mismatch <> + state if_session_id_mismatch <> + [*] --> if_app_addr_mismatch + if_app_addr_mismatch --> Session_Header_Mismatch_Error: proof msg application address mismatch + if_app_addr_mismatch --> if_service_id_mismatch + if_service_id_mismatch --> Session_Header_Mismatch_Error: proof msg service ID mismatch + if_service_id_mismatch --> if_session_start_mismatch + if_session_start_mismatch -->Session_Header_Mismatch_Error: proof msg session start mismatch + if_session_start_mismatch --> if_session_end_mismatch + if_session_end_mismatch --> Session_Header_Mismatch_Error: proof msg session end mismatch + if_session_end_mismatch --> if_session_id_mismatch + if_session_id_mismatch --> Session_Header_Mismatch_Error: proof msg session ID mismatch + if_session_id_mismatch --> [*] +} +Compare_Session_Header_To_Proof --> [*] +``` + +### Proof Submission Claim Validation + +```mermaid +stateDiagram-v2 + + [*] --> Validate_Claim_For_Proof + state Validate_Claim_For_Proof { + state if_claim_found <> + state if_proof_session_start_mismatch <> + state if_proof_session_end_mismatch <> + state if_proof_app_addr_mismatch <> + state if_proof_service_mismatch <> + + [*] --> if_claim_found + if_claim_found --> Claim_Validation_Error: claim not found + if_claim_found --> if_proof_session_start_mismatch + if_proof_session_start_mismatch --> Claim_Validation_Error: proof session start mismatch + if_proof_session_start_mismatch --> if_proof_session_end_mismatch + if_proof_session_end_mismatch --> Claim_Validation_Error: proof session end mismatch + if_proof_session_end_mismatch --> if_proof_app_addr_mismatch + if_proof_app_addr_mismatch --> Claim_Validation_Error: proof application address mismatch + if_proof_app_addr_mismatch --> if_proof_service_mismatch + if_proof_service_mismatch --> Claim_Validation_Error: proof service ID mismatch + if_proof_service_mismatch --> [*] + } + Validate_Claim_For_Proof --> [*] +``` diff --git a/docusaurus/docs/protocol/primitives/relay_mining.md b/docusaurus/docs/protocol/primitives/relay_mining.md index 300c24a31..52179cf7a 100644 --- a/docusaurus/docs/protocol/primitives/relay_mining.md +++ b/docusaurus/docs/protocol/primitives/relay_mining.md @@ -19,9 +19,165 @@ the [relay mining paper](https://arxiv.org/abs/2305.10672) as a reference for wr tl;dr Modulate on-chain difficulty up (similar to Bitcoin) so we can accommodate surges in relays and have no upper limit on the number of relays per session. -Relay Mining is the only solution in Web3 to incentivizing read-only requests -and solving for the problem of high volume: `how can we scale to billions or trillions +Relay Mining is the only solution in Web3 to incentivize read-only requests +and solve for the problem of high volume: `how can we scale to billions or trillions of relays per session`. This complements the design of [Probabilistic Proofs](./probabilistic_proofs.md) to solve for all scenarios. + +## Relay Sessions + +[Sessions](./session) effectively group relays into time-wise batches. During each session, +`Application`s and/or `Gateway`s can submit relays to one or more of the `Supplier`s +in the current session for servicing. + +### Sovereign Application + +An `Application` can act as a "soverign application" (i.e. its own `Gateway`). +In this case, the ring used to sign relay requests is constructed only from +the `Application`'s public key. + +```mermaid +--- +title: Sovereign Application - RPC Request/Response & Claim/Proof +--- +sequenceDiagram + +actor user as User +participant app as Gateway (Sovereign Application) +participant pokt as Pokt Network +participant sup as Supplier +participant rpc as RPC Server + +app-)pokt: Stake for service(s) +sup-)pokt: Stake for service(s) + +loop Session N + +loop Every relay request + +Note over user,rpc: Ref: RPC Request/Response Relay (Sovereign Application) + +end +end + + +break Wait for session N grace period to end + sup->>sup: Persist unclaimed & unproven session trees +end + +loop Session N+GracePeriod+1 + +loop Every application session from session N + +Note over pokt,sup: ref: Supplier Claim/Proof + +end + +end +``` +> **See**: [Legend > Sequence Diagram](#sequence-diagram) + +### Delegated Application + +An `Application` can also be delegated to one or more `Gateway`s. In this case +the ring used to sign relay requests is constructed from the `Application`'s +public key and the public keys of the all `Gateway`s it is delegated to at the +start of the session in question. + +```mermaid +--- +title: Delegated Application - RPC Request/Response & Claim/Proof +--- +sequenceDiagram + + actor user as User + actor app as Application (Delegated to Gateway) + participant gw as Gateway + participant pokt as Pokt Network + participant sup as Supplier + participant rpc as RPC Server + + +%% par Staking & Delegation + gw-)pokt: Stake + app-)pokt: Stake for service(s) + app-)pokt: Delegate to gateway(s) + sup-)pokt: Stake for service(s) +%% end + + loop Session N + + pokt--xpokt: Store current ring state for application + + gw-xpokt: Construct ring for signing (query application & delegates' public keys) + sup-xpokt: Construct ring for verifying (query application & delegates' public keys) + + loop Every Request + + Note over user,rpc: ref: RPC Request/Response Relay (Delegated Application) + + end + + end + +break Wait for session grace period to end +sup->>sup: + sup->>sup: Persist unclaimed & unproven session trees +end + +loop Session+GracePeriod+1 + +loop Every application session from session N + +Note over pokt,sup: ref: Supplier Claim/Proof + +end + +pokt--xpokt: Delete ring state for application + +end + +``` +> **See**: [Legend > Sequence Diagram](#sequence-diagram) + +## Legend + +### Sequence Diagram +```mermaid +--- +title: Sequence Diagram Legend +--- +sequenceDiagram + + actor proto_part as Protocol Participant + participant proto_actor as Protocol Actor + + proto_part->>+proto_actor: Protocol participant sends a synchronous <> to protocol actor + proto_actor--)-proto_part: Protocol actor returns a synchronous <> to protocol participant + + loop Looped sequence + + proto_part-)+proto_actor: Protocol participant sends an asynchronous <> to protocol actor + proto_actor--)-proto_part: Protocol actor returns an asynchronous <> to protocol participant + + Note over proto_part,proto_actor: ref: Interaction (other seq. diagram) + + proto_part--xproto_actor: An action of protocol participant updates on-chain state of protocol actor + proto_part-xproto_actor: An action of protocol participant references on-chain state of protocol actor + + break Time gap + proto_actor->>proto_actor: Protocol actor performs some independent action + end + + end +``` + +## Reference Diagrams + +### RPC Request/Response Relay (Sovereign Application) + +### RPC Request/Response Relay (Delegated Application) + +### diff --git a/docusaurus/yarn.lock b/docusaurus/yarn.lock index 2794e179d..0da659ab6 100644 --- a/docusaurus/yarn.lock +++ b/docusaurus/yarn.lock @@ -1810,10 +1810,15 @@ dependencies: "@types/mdx" "^2.0.0" -"@node-rs/jieba-darwin-arm64@1.10.0": +"@node-rs/jieba-linux-x64-gnu@1.10.0": version "1.10.0" - resolved "https://registry.npmjs.org/@node-rs/jieba-darwin-arm64/-/jieba-darwin-arm64-1.10.0.tgz" - integrity sha512-IhR5r+XxFcfhVsF93zQ3uCJy8ndotRntXzoW/JCyKqOahUo/ITQRT6vTKHKMyD9xNmjl222OZonBSo2+mlI2fQ== + resolved "https://registry.npmjs.org/@node-rs/jieba-linux-x64-gnu/-/jieba-linux-x64-gnu-1.10.0.tgz" + integrity sha512-rS5Shs8JITxJjFIjoIZ5a9O+GO21TJgKu03g2qwFE3QaN5ZOvXtz+/AqqyfT4GmmMhCujD83AGqfOGXDmItF9w== + +"@node-rs/jieba-linux-x64-musl@1.10.0": + version "1.10.0" + resolved "https://registry.npmjs.org/@node-rs/jieba-linux-x64-musl/-/jieba-linux-x64-musl-1.10.0.tgz" + integrity sha512-BvSiF2rR8Birh2oEVHcYwq0WGC1cegkEdddWsPrrSmpKmukJE2zyjcxaOOggq2apb8fIRsjyeeUh6X3R5AgjvA== "@node-rs/jieba@^1.6.0": version "1.10.0" @@ -4616,11 +4621,6 @@ fs.realpath@^1.0.0: resolved "https://registry.npmjs.org/fs.realpath/-/fs.realpath-1.0.0.tgz" integrity sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw== -fsevents@~2.3.2: - version "2.3.3" - resolved "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz" - integrity sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw== - function-bind@^1.1.2: version "1.1.2" resolved "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz"