Read the groups in order (1 → 6). Each group has a short description, code pointers, a 📖 What to read list (links to the hyperscale-rs repo), and a 10-question quiz. Pass threshold per quiz: 70%.
Group 1: First contact
Crates: production, node, mempool, types, core, messages
One-liner: How Hyperscale receives a transaction at the RPC and gets it into the right shards’ mempools.
- production: RPC handlers (submit tx), runner that dispatches to state machine and gossips to shards.
- node: NodeStateMachine routes events (e.g. SubmitTransaction, TransactionGossipReceived) and calls mempool/BFT/execution.
- mempool: Pool per validator, on_submit_transaction_arc, on_transaction_gossip_arc, involves_local_shard gating.
- types: RoutableTransaction, declared_reads / declared_writes, topology and shard helpers.
- core: Event, Action (e.g. BroadcastToShard, EmitTransactionStatus).
- messages: TransactionGossip, OutboundMessage, batching/serialization.
📖 What to read before the quiz:
- crates/production — RPC and runner (submit path, gossip)
- crates/node — NodeStateMachine, event routing
- crates/mempool —
on_submit_transaction_arc, on_transaction_gossip_arc, involves_local_shard gating
- crates/types — RoutableTransaction, declared_reads / declared_writes, topology
- crates/core — Event, Action (e.g. BroadcastToShard, EmitTransactionStatus)
- crates/messages — TransactionGossip, OutboundMessage
Quiz: Group 1 (10 questions)
Group 2: Sharding and routing
Crates: types, core, node
One-liner: Once a transaction is decomposed into NodeIds and each shard is responsible for a slice of state, these crates define who does what and where the tx is stored.
- types: shard_for_node, Topology, consensus_shards / provisioning_shards / all_shards_for_transaction, RoutableTransaction.
- core: Actions that are shard-aware (e.g. BroadcastToShard { shard, message }).
- node: Uses topology.involves_local_shard(tx) and routes events to the right sub-state machines.
📖 What to read before the quiz:
- crates/types —
shard_for_node, Topology, consensus_shards / provisioning_shards / all_shards_for_transaction, RoutableTransaction
- crates/core — shard-aware actions (e.g. BroadcastToShard)
- crates/node — routing by involves_local_shard, sub-state machines
Quiz: Group 2 (10 questions)
Group 3: Proposing and building blocks
Crates: bft, mempool, types, core
One-liner: How one validator becomes the proposer and assembles the next block from the mempool.
- bft: Proposer selection (height + round) % committee.len(), ProposalTimer, requesting ready_txs from mempool, BuildProposal action with parent state root and certificates.
- mempool: ready_transactions(max_count, pending_commit_tx_count, pending_commit_cert_count), retries / priority / others, in-flight limits.
- types: Block, BlockHeader, RoutableTransaction, certificate and deferral types.
- core: Action::BuildProposal, SetTimer / CancelTimer.
📖 What to read before the quiz:
- crates/bft — proposer selection, ProposalTimer, BuildProposal, ready_txs from mempool
- crates/mempool —
ready_transactions, retries / priority / others, in-flight limits
- crates/types — Block, BlockHeader, certificate and deferral types
- crates/core — BuildProposal, SetTimer / CancelTimer
Quiz: Group 3 (10 questions)
Group 4: Voting and committing
Crates: bft, types, core
One-liner: How validators agree on a block and when it is finally committed (votes and QCs).
- bft: Block verification (state root, tx root, parent QC), BlockVote, collection and VerifyAndBuildQuorumCertificate, 2-chain commit rule, BlockCommitted and chain advancement.
- types: QuorumCertificate, BlockVote, signing message format, BlockHeader.
- core: Action::VerifyQcSignature, VerifyAndBuildQuorumCertificate, PersistAndBroadcastVote, Event::BlockCommitted.
📖 What to read before the quiz:
- crates/bft — block verification, BlockVote, VerifyAndBuildQuorumCertificate, 2-chain commit rule, BlockCommitted
- crates/types — QuorumCertificate, BlockVote, BlockHeader, signing message format
- crates/core — VerifyQcSignature, VerifyAndBuildQuorumCertificate, PersistAndBroadcastVote, BlockCommitted
- guides/04-consensus-protocol.md — consensus protocol (votes, QC, commit)
Quiz: Group 4 (10 questions)
Group 5: Execution after commit
Crates: execution, engine, node, types, core
One-liner: Once a block is committed, who runs the transactions and how single-shard vs cross-shard paths diverge.
- execution: on_block_committed, split single-shard vs cross-shard, single-shard execution and StateVoteBlock, cross-shard registration and 2PC phases.
- engine: Radix Engine integration, execute_single_shard, execution output and state writes.
- node: Dispatches BlockCommitted to execution, handles TransactionExecuted and certificate feedback to BFT/mempool.
- types: StateVoteBlock, StateCertificate, TransactionCertificate, TransactionDecision.
- core: ExecuteTransactions, BroadcastStateVote, AggregateStateCertificate, EmitCommittedBlock.
📖 What to read before the quiz:
- crates/execution —
on_block_committed, single-shard vs cross-shard split, StateVoteBlock, 2PC registration
- crates/engine — Radix Engine, execute_single_shard, state writes
- crates/node — BlockCommitted → execution, TransactionExecuted, certificate feedback
- crates/types — StateVoteBlock, StateCertificate, TransactionCertificate, TransactionDecision
- crates/core — ExecuteTransactions, BroadcastStateVote, AggregateStateCertificate
Quiz: Group 5 (10 questions)
Group 6: Cross-shard (provisions and livelock)
Crates: provisions, execution, livelock, types, core
One-liner: How state moves between shards for cross-shard transactions and how Hyperscale avoids deadlock.
- provisions: ProvisionCoordinator, receiving and buffering StateProvision, quorum per source shard, VerifyAndAggregateProvisions, CommitmentProof.
- execution: Cross-shard 2PC phases (provision broadcast, reception, execution, vote aggregation, certificate collection), registration with provisions coordinator.
- livelock: Cycle detection, deferral, retry, TransactionDefer, TransactionAbort, integration with block proposal and execution.
- types: StateProvision, StateCertificate, CommitmentProof, CycleProof, defer/abort types.
- core: BroadcastStateProvision, BroadcastStateCertificate, VerifyAndAggregateProvisions, VerifyCycleProof.
📖 What to read before the quiz:
- crates/provisions — ProvisionCoordinator, StateProvision buffering, quorum, VerifyAndAggregateProvisions, CommitmentProof
- crates/execution — cross-shard 2PC phases, provision coordinator registration
- crates/livelock — cycle detection, TransactionDefer, TransactionAbort, retry
- crates/types — StateProvision, StateCertificate, CommitmentProof, CycleProof, defer/abort types
- crates/core — BroadcastStateProvision, VerifyAndAggregateProvisions, VerifyCycleProof
Quiz: Group 6 (10 questions)
Quick Test: Crates from Tx Submission to Cross-Shard Flow
This short quiz checks that you can map each stage of the transaction flow to the right crates. Pass threshold: 70%.
📖 What to read before the quiz: Complete the reading for Groups 1–6 above (first contact → sharding → proposing → voting → execution → cross-shard). The Quick Test covers the full path, so having read all six groups is enough.