Add sequence diagrams for core protocol flows#180
Open
mudigal wants to merge 11 commits into
Open
Conversation
Mermaid sequence diagrams documenting the core protocol flows: - Client-initiated checkpoint (signature collection + consensus) - Provider-initiated checkpoint (leader election + grace period) - Challenge creation (both on-chain and off-chain modes) - Challenge response (two-layer MMR + Merkle proof) - Challenge timeout and automatic slashing
Four-phase diagram covering provider discovery, off-chain term negotiation with provider signature, single atomic on-chain extrinsic (Layer 0 bucket + storage agreement + S3 registry entry), and UI completion. Includes events, storage items, payment calculation, and replay protection details.
Registration: on-chain registration with stake locking, settings update (two transactions), provider node startup sequence (keyfile loading, chain sync, multiaddr sync, HTTP server), and adding stake. Deregistration: two-step exit flow (announce cooldown >= ChallengeTimeout, then complete to return stake), cancellation flow, and security rationale for why instant exit is not allowed.
Write flow: client auth (sr25519), provider URL resolution from chain, 256 KiB chunking, content-addressed storage, balanced Merkle tree construction, MMR commit, S3 index update. Includes replica sync background flow (peak fetching, recursive subtree pull, on-chain confirm_replica_sync with payment). Read flow: provider resolution, auth, S3 index lookup, DFS Merkle tree traversal to collect chunks, truncation, response. Includes Rust SDK verified download path and multi-provider topology diagram showing how primaries, replicas, and clients interact.
Add prerequisite section: client must configure_checkpoint_window and fund_checkpoint_pool before provider checkpoints work sustainably. Add setup sequence diagram, cost breakdown table, budget estimation example, and note on disabling. Makes clear this is a client cost.
Expand the Two Challenge Modes section with detailed analysis: - challenge_checkpoint recommended as the robust production path - challenge_offchain limitations: requires client to retain commit response, defeated by client-side data loss, fragmented across multi-device/multi-user-agent scenarios where each device gets different MMR roots and signatures, point-in-time snapshots that don't track subsequent writes from other devices
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/sequence_diagrams/challenge_checkpoint(recommended) andchallenge_offchain(limited by client-side state loss and multi-device fragmentation)fund_checkpoint_poolwith cost breakdownDiagrams added
provider-registration.mdprovider-deregistration.mds3-bucket-creation.mds3-write-flow.mds3-read-flow.mdcheckpoint-client-initiated.mdcheckpoint-provider-initiated.mdchallenge-creation.mdchallenge-response.mdchallenge-timeout-slashing.mdTest plan
🤖 Generated with Claude Code