# tathack-tathva/blockchain-simulation architecture

> Architecture diagram of the GitHub repository tathack-tathva/blockchain-simulation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tathack-tathva/blockchain-simulation
- Repository: https://github.com/tathack-tathva/blockchain-simulation

## Overview

Blockchain App is a Python peer node for signed transactions, replicated chains, selectable consensus, contracts, and file references stored through IPFS. The user-facing workflow is to start a peer, connect and exchange chain/peer information, submit transactions or contract operations, and have peers validate and add blocks under PoW, PoS, or PoA. The README also documents persistent node data and malicious-node testing. The supplied source excerpts are partial; links for unsampled persistence and contract subsystems are therefore limited to documented capabilities.

Main entry points: [`consensus/pow/p2p.py`](https://github.com/tathack-tathva/blockchain-simulation/blob/main/consensus/pow/p2p.py) (PoW peer), [`consensus/pos/p2p.py`](https://github.com/tathack-tathva/blockchain-simulation/blob/main/consensus/pos/p2p.py) (PoS peer), [`consensus/poa/p2p.py`](https://github.com/tathack-tathva/blockchain-simulation/blob/main/consensus/poa/p2p.py) (PoA peer), [`ipfs/ipfs.py`](https://github.com/tathack-tathva/blockchain-simulation/blob/main/ipfs/ipfs.py) (IPFS wrapper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_node["Peer node"]
  node_launcher["Peer launcher<br/>[start_peer.py]"]
end

subgraph group_consensus["Consensus modes"]
  node_pow_peer["PoW peer<br/>[p2p.py]"]
  node_pos_peer["PoS peer<br/>[p2p.py]"]
  node_poa_peer["PoA peer<br/>[p2p.py]"]
  node_pow_data["PoW structures"]
  node_pos_data["PoS structures"]
  node_poa_data["PoA structures"]
  node_shared_data["Shared structures"]
end

subgraph group_contracts["Smart contracts"]
  node_contract_db[("Contract database<br/>[contracts_db.py]")]
  node_contract_api["Contract runtime<br/>[smart_contract.py]"]
  node_contract_exec["Secure executor<br/>[secure_executor.py]"]
  node_sandbox["Sandbox runner<br/>[sandbox_runner.py]"]
  node_gas["Gas meter<br/>[gas_meter.py]"]
end

subgraph group_integrations["External storage"]
  node_ipfs_wrap["IPFS wrapper<br/>[ipfs.py]"]
  node_ipfs_network(("IPFS network"))
  node_storage[("Node persistence<br/>[storage_manager.py]")]
end

node_user(("User"))
node_other_peers(("Other peers"))

node_user -->|"starts peer"| node_launcher
node_user -->|"uses PoW"| node_pow_peer
node_user -->|"uses PoS"| node_pos_peer
node_user -->|"uses PoA"| node_poa_peer
node_pow_peer -->|"uses structures"| node_pow_data
node_pos_peer -->|"uses structures"| node_pos_data
node_poa_peer -->|"uses structures"| node_poa_data
node_pow_data -->|"inherits common model"| node_shared_data
node_pos_data -->|"inherits common model"| node_shared_data
node_poa_data -->|"inherits common model"| node_shared_data
node_pow_peer -->|"exchanges messages"| node_other_peers
node_pos_peer -->|"exchanges messages"| node_other_peers
node_poa_peer -->|"exchanges messages"| node_other_peers
node_pow_peer -->|"calls file operations"| node_ipfs_wrap
node_pos_peer -->|"calls file operations"| node_ipfs_wrap
node_poa_peer -->|"calls file operations"| node_ipfs_wrap
node_ipfs_wrap -->|"adds or fetches files"| node_ipfs_network
node_pow_peer -->|"imports database"| node_contract_db
node_pos_peer -->|"imports database"| node_contract_db
node_contract_api -->|"measures execution"| node_gas
node_contract_exec -->|"runs in process"| node_sandbox

click node_launcher "https://github.com/tathack-tathva/blockchain-simulation/blob/main/start_peer.py"
click node_pow_peer "https://github.com/tathack-tathva/blockchain-simulation/blob/main/consensus/pow/p2p.py"
click node_pos_peer "https://github.com/tathack-tathva/blockchain-simulation/blob/main/consensus/pos/p2p.py"
click node_poa_peer "https://github.com/tathack-tathva/blockchain-simulation/blob/main/consensus/poa/p2p.py"
click node_pow_data "https://github.com/tathack-tathva/blockchain-simulation/blob/main/consensus/pow/blockchain_structures.py"
click node_pos_data "https://github.com/tathack-tathva/blockchain-simulation/blob/main/consensus/pos/blockchain_structures.py"
click node_poa_data "https://github.com/tathack-tathva/blockchain-simulation/blob/main/consensus/poa/blockchain_structures.py"
click node_shared_data "https://github.com/tathack-tathva/blockchain-simulation/blob/main/shared_blockchain_structures.py"
click node_contract_db "https://github.com/tathack-tathva/blockchain-simulation/blob/main/smart_contract/contracts_db.py"
click node_contract_api "https://github.com/tathack-tathva/blockchain-simulation/blob/main/smart_contract/smart_contract.py"
click node_contract_exec "https://github.com/tathack-tathva/blockchain-simulation/blob/main/smart_contract/secure_executor.py"
click node_sandbox "https://github.com/tathack-tathva/blockchain-simulation/blob/main/smart_contract/sandbox_runner.py"
click node_gas "https://github.com/tathack-tathva/blockchain-simulation/blob/main/smart_contract/gas_meter.py"
click node_ipfs_wrap "https://github.com/tathack-tathva/blockchain-simulation/blob/main/ipfs/ipfs.py"
click node_storage "https://github.com/tathack-tathva/blockchain-simulation/blob/main/storage/storage_manager.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_launcher,node_user toneBlue
class node_pow_peer,node_pos_peer,node_poa_peer,node_pow_data,node_pos_data,node_poa_data,node_shared_data toneAmber
class node_contract_db,node_contract_api,node_contract_exec,node_sandbox,node_gas toneMint
class node_ipfs_wrap,node_ipfs_network,node_storage toneRose
class node_other_peers toneIndigo
```

## Components

### Peer node

- [Peer launcher](https://github.com/tathack-tathva/blockchain-simulation/blob/main/start_peer.py): `start_peer.py`

### Consensus modes

- [PoW peer](https://github.com/tathack-tathva/blockchain-simulation/blob/main/consensus/pow/p2p.py): `consensus/pow/p2p.py`
- [PoS peer](https://github.com/tathack-tathva/blockchain-simulation/blob/main/consensus/pos/p2p.py): `consensus/pos/p2p.py`
- [PoA peer](https://github.com/tathack-tathva/blockchain-simulation/blob/main/consensus/poa/p2p.py): `consensus/poa/p2p.py`
- [PoW structures](https://github.com/tathack-tathva/blockchain-simulation/blob/main/consensus/pow/blockchain_structures.py): `consensus/pow/blockchain_structures.py`
- [PoS structures](https://github.com/tathack-tathva/blockchain-simulation/blob/main/consensus/pos/blockchain_structures.py): `consensus/pos/blockchain_structures.py`
- [PoA structures](https://github.com/tathack-tathva/blockchain-simulation/blob/main/consensus/poa/blockchain_structures.py): `consensus/poa/blockchain_structures.py`
- [Shared structures](https://github.com/tathack-tathva/blockchain-simulation/blob/main/shared_blockchain_structures.py): `shared_blockchain_structures.py`

### Smart contracts

- [Contract database](https://github.com/tathack-tathva/blockchain-simulation/blob/main/smart_contract/contracts_db.py): `smart_contract/contracts_db.py`
- [Contract runtime](https://github.com/tathack-tathva/blockchain-simulation/blob/main/smart_contract/smart_contract.py): `smart_contract/smart_contract.py`
- [Secure executor](https://github.com/tathack-tathva/blockchain-simulation/blob/main/smart_contract/secure_executor.py): `smart_contract/secure_executor.py`
- [Sandbox runner](https://github.com/tathack-tathva/blockchain-simulation/blob/main/smart_contract/sandbox_runner.py): `smart_contract/sandbox_runner.py`
- [Gas meter](https://github.com/tathack-tathva/blockchain-simulation/blob/main/smart_contract/gas_meter.py): `smart_contract/gas_meter.py`

### External storage

- [IPFS wrapper](https://github.com/tathack-tathva/blockchain-simulation/blob/main/ipfs/ipfs.py): `ipfs/ipfs.py`
- **IPFS network**
- [Node persistence](https://github.com/tathack-tathva/blockchain-simulation/blob/main/storage/storage_manager.py): `storage/storage_manager.py`

### Other components

- **User**
- **Other peers**

## Connections

- User → Peer launcher: starts peer
- User → PoW peer: uses PoW
- User → PoS peer: uses PoS
- User → PoA peer: uses PoA
- PoW peer → PoW structures: uses structures
- PoS peer → PoS structures: uses structures
- PoA peer → PoA structures: uses structures
- PoW structures → Shared structures: inherits common model
- PoS structures → Shared structures: inherits common model
- PoA structures → Shared structures: inherits common model
- PoW peer → Other peers: exchanges messages
- PoS peer → Other peers: exchanges messages
- PoA peer → Other peers: exchanges messages
- PoW peer → IPFS wrapper: calls file operations
- PoS peer → IPFS wrapper: calls file operations
- PoA peer → IPFS wrapper: calls file operations
- IPFS wrapper → IPFS network: adds or fetches files
- PoW peer → Contract database: imports database
- PoS peer → Contract database: imports database
- Contract runtime → Gas meter: measures execution
- Secure executor → Sandbox runner: runs in process