How siyovush-hamidov/pow-blockchain works
Project type and purpose
• This is a Go-based Proof-of-Work blockchain implementation (“Node” binary) plus a CLI “Client” binary.
• It demonstrates basic blockchain fundamentals: mining, block validation, P2P gossip, and simple client-node interactions.
File structure
• Top-level “node” entry points:
• node.go, network.go, bc.go – together build the node executable.
• Top-level “client” entry points:
• mainClient.go, client.go – together build the client executable.
• Core packages:
• /blockchain – block data structures, PoW algorithm, chain state, transaction handling, persistence to <chain>.db.
• /network – P2P networking, peer discovery (addrlist.json), block/tx broadcast, simple RPC or HTTP endpoints.
• Support files:
• addrlist.json – initial peer addresses.
• Makefile – builds node and client.
• LICENSE, .gitignore, go.mod/go.sum – metadata.
Extract insights from the README
• Two runtime roles: “node” peers that mine and gossip, and a “client” that issues commands.
• Nodes communicate over ports (e.g., 8080, 9090), load addrlist.json, maintain local DB (chain1.db, chain2.db).
• Client connects to a node’s address using a key file and issues commands (balance, tx, print, etc.).
a. Node Application (container)
• Sub-components:
• Network Module (from /network) – handles P2P RPC, block/tx broadcast, peer management.
• Blockchain Module (from /blockchain and bc.go) – PoW mining, block validation, chain state.
• Local Storage – persistent chain DB (e.g., chain1.db).
• Config Loader – reads addrlist.json and user key.
b. Client Application (container)
• CLI Module – user input parser (client.go)
• Network Stub – makes RPC calls to Node.
c. External Entities
• Other Node Instances – peer nodes with the same internal structure.
• addrlist.json – initial peer list.
• User’s key files – credentials for signing transactions.
Relationships & interactions
• Client → Node.Network API: send user commands (balance query, submit transaction).
• Node.Network → Node.Blockchain: on transaction or block receipt, forward to blockchain module.
• Node.Blockchain → Local Storage: read/write blocks.
• Node.Network ↔ Peer Node.Network: gossip new blocks/transactions.
• Node.Config Loader → Network Module: seed peers from addrlist.json.
Architectural patterns & principles
• Separation of Concerns:
• Transport (network) vs Domain Logic (blockchain).
• CLI (client) vs Service (node).
• P2P Gossip Pattern: nodes form a mesh, broadcast messages.
• Modular packaging: two Go modules for core functionality, two main packages for binaries.
Relevant technologies & frameworks
• Language: Go (modules via go.mod).
• Persistence: simple file-based DB (<chain>.db files).
• Build: Makefile targets make build → compiles node and client.
• Configuration: JSON peer list (addrlist.json), CLI flags for ports & file paths.
Final checklist
• [ ] All major components (Client, Node.Network, Node.Blockchain, Storage) clearly labeled
• [ ] Multiple Node instances to indicate P2P topology
• [ ] Notation for config files and key files as external artifacts