TrustMeBroChain

TrustMeBroChain is a small Rust command-line project that demonstrates a minimal blockchain flow:

• a genesis block funds an initial account
• users stage transfers in a mempool
• mining batches pending transfers into proof-of-work blocks
• each mined block also includes a fixed mining reward
• the final chain can be revalidated by recomputing every block hash

The project is intentionally compact. It is useful as a learning exercise for hashes, block linkage, basic mempool handling, and simple balance accounting.

Current Behavior

When the program starts, it creates a genesis block that credits pi with 1000 units.

The interactive loop accepts these commands:

• send <from> <to> <amt>: queue a transaction if the sender has enough available balance
• mine: mine up to 3 queued transactions plus a miner reward transaction
• print: print every block and the computed balances
• exit: leave the CLI and print whether the full chain is valid

Mining uses SHA-256 and a fixed difficulty of 2, meaning each block hash must start with two leading zeroes.

Example Session

$ cargo run

Commands: send <from> <to> <amt> | mine | print | exit
send pi alice 125
tx added

Commands: send <from> <to> <amt> | mine | print | exit
mine
block mined

Commands: send <from> <to> <amt> | mine | print | exit
print

Project Layout

• src/main.rs: full application logic, CLI loop, mining, balance computation, validation, and unit tests
• Cargo.toml: crate manifest

Internal Model

Transactions

Each transaction contains:

• sender
• receiver
• amount

SYSTEM is a reserved sender used for the genesis allocation and miner reward transactions.

Blocks

Each block stores:

• prev_hash: the previous block hash
• nonce: the proof-of-work counter
• hash: the mined hash for the block contents
• transactions: the transactions included in the block

The block hash is derived from:

1. the previous hash
2. the nonce
3. every transaction field in order

If any field changes later, validation fails because the recomputed hash no longer matches the stored hash.

Validation Rules

is_valid checks the following:

1. the genesis block hash matches its contents
2. the genesis block also satisfies the configured difficulty
3. every later block points to the previous block hash
4. every later block hash matches a fresh recomputation
5. every later block satisfies the configured difficulty

Mempool Rules

Before this update, a sender could overspend by submitting multiple pending transactions before mining. That happened because validation looked only at confirmed chain balance.

The current implementation fixes that by calculating an available_balance:

• start from the confirmed chain balance
• subtract the sender's pending outgoing mempool transfers
• add the sender's pending incoming mempool transfers

The CLI also rejects zero-value transfers.

Running Locally

Build

cargo build

Run

cargo run

Limitations

This is still a demo, not a production blockchain. Important limitations:

• all state is in memory only
• there is no networking or peer consensus
• there are no digital signatures or account authentication
• transaction ordering is FIFO from the mempool
• mining reward and difficulty are hard-coded
• the CLI uses unwrap() for standard input and last-block access