How phamnguyengiabao-dev/group2_hcmus_blockchain works
This repository is a deterministic Layer-1 blockchain simulator with a companion dashboard for inspecting simulation logs. The main workflow loads a scenario, initializes deterministic time and simulated networking, runs validator consensus through proposal, voting and finalization, and records events and ledger state. The dashboard loads scenario configuration and JSONL logs, derives chain and event views, and presents them interactively. The README and source index support the major subsystem links; unsampled module behavior is represented only where the index or README documents the relationship.
Main entry points: consensus.py Consensus state · block.py Blocks · scenario.py Scenario runner · vote.py Votes
Components 31
Simulation orchestration
- Scenario runner
src/scenario.py - Scenario configs
config - Logical scheduler
src/scheduler.py - Simulated network
src/network.py - Fault injector
src/fault_injector.py - Legacy runner
src/scenario_runner.py
Consensus protocol
- Consensus state
src/consensus.py - Message router
src/router.py - Peer gossip
src/gossip.py - Transactions
src/transaction.py - Blocks
src/block.py - Block validation
src/block_validator.py - Candidate block store
src/block_store.py - Votes
src/vote.py - Vote aggregation
src/vote_set.py - Validator identities
src/identity.py - Block executor
src/executor.py
Protocol foundations
- Cryptography
src/crypto.py - Canonical encoding
src/encoding.py - Key-value state
src/state.py
Logs and ledger
- Finalized ledger
src/ledger.py - Event log
src/event_log.py - Run summary
src/summary.py
Dashboard
- Dashboard app
dashboard/app.py - Dashboard layout
dashboard/layout.py - Dashboard callbacks
dashboard/callbacks.py - Log and config loader
dashboard/data_loader.py - Charts
dashboard/charts.py - UI components
dashboard/components.py
Other components
- Scenario operator
- Dashboard user
Connections 48
- Scenario operator → Scenario runner: runs scenario
README.md - Scenario configs → Scenario runner: configures
README.md - Scenario runner → Logical scheduler: seeds
README.md - Scenario runner → Simulated network: initializes
README.md - Scenario runner → Fault injector: initializes
README.md - Scenario runner → Event log: records events
README.md - Fault injector → Logical scheduler: draws randomness
src/fault_injector.py - Simulated network → Logical scheduler: queues deliveries
src/network.py - Simulated network → Event log: writes events
src/network.py - Consensus state → Simulated network: sends messages
src/consensus.py - Consensus state → Transactions: proposes transactions
src/consensus.py - Consensus state → Blocks: creates proposals
src/consensus.py - Consensus state → Candidate block store: uses candidate store
src/consensus.py - Consensus state → Votes: creates votes
src/consensus.py - Consensus state → Vote aggregation: aggregates votes
src/consensus.py - Consensus state → Block executor: executes blocks
src/consensus.py - Consensus state → Finalized ledger: finalizes chain
src/consensus.py - Consensus state → Validator identities: uses validators
src/consensus.py - Message router → Block validation: validates headers
src/router.py - Message router → Blocks: handles blocks
src/router.py - Message router → Votes: validates votes
src/router.py - Message router → Event log: logs rejections
src/router.py - Peer gossip → Simulated network: sends peer data
src/gossip.py - Peer gossip → Blocks: gossips blocks
src/gossip.py - Peer gossip → Votes: gossips votes
src/gossip.py - Peer gossip → Vote aggregation: checks vote data
src/gossip.py - Transactions → Cryptography: verifies signatures
src/transaction.py - Transactions → Canonical encoding: encodes fields
src/transaction.py - Blocks → Cryptography: hashes and signs
src/block.py - Blocks → Canonical encoding: encodes headers
src/block.py - Blocks → Key-value state: checks state hash
src/block.py - Blocks → Transactions: validates body transactions
src/block.py - Block validation → Blocks: validates headers
src/block_validator.py - Block validation → Cryptography: verifies signatures
src/block_validator.py - Votes → Cryptography: signs and verifies
src/vote.py - Votes → Canonical encoding: encodes votes
src/vote.py - Vote aggregation → Votes: aggregates votes
src/vote_set.py - Block executor → Key-value state: updates state
src/executor.py - Block executor → Transactions: applies transactions
src/executor.py - Key-value state → Cryptography: hashes commitment
src/state.py - Key-value state → Canonical encoding: encodes map
src/state.py - Finalized ledger → Blocks: stores headers
src/ledger.py - Finalized ledger → Key-value state: snapshots state
src/ledger.py - Legacy runner → Event log: writes events
src/scenario_runner.py - Run summary → Scenario runner: summarizes run
src/summary.py - Dashboard user → Dashboard app: opens dashboard
dashboard/app.py - Dashboard app → Dashboard layout: loads layout
dashboard/app.py - Dashboard app → Dashboard callbacks: registers callbacks
dashboard/app.py