Chapter 1: Core Primitives

Every blockchain rests on a foundation of cryptographic primitives. In this chapter, we’ll build the core crate — the bedrock upon which everything else depends.

What We’re Building

By the end of this chapter, you’ll have implemented:

Module	Purpose
`hash.rs`	Blake3 hashing utilities
`crypto.rs`	Ed25519 signatures and addresses
`account.rs`	Account state representation
`transaction.rs`	Transaction types and signing
`block.rs`	Block and header structures
`merkle.rs`	Merkle tree for transaction proofs

1.1 Hashing with Blake3

Hashing is the heartbeat of a blockchain. We use it for:

Block identification
Transaction fingerprinting
Merkle tree construction
Address derivation

Why Blake3?

Official BLAKE3 Repository →

Algorithm	Speed	Security	Output
SHA-256	Moderate	Proven	32 bytes
Keccak-256	Moderate	Proven	32 bytes
Blake3	Very Fast	Modern	32 bytes

Blake3 is extremely fast (especially on modern CPUs with SIMD) while maintaining strong security properties. It’s based on the BLAKE2 design but optimized for parallelism and performance.

The Hash Type

We wrap the raw 32-byte array in a newtype for better ergonomics:

/// A 256-bit hash value.
pub type H256 = [u8; 32];

/// A wrapper type for H256 with Display and Debug formatting.
#[derive(Clone, Copy, PartialEq, Eq, Hash, Default, Serialize, Deserialize)]
pub struct Hash(pub H256);

impl Hash {
    /// The zero hash (all zeros).
    pub const ZERO: Self = Self([0u8; 32]);

    /// Convert to a hex string.
    pub fn to_hex(&self) -> String {
        hex::encode(self.0)
    }

    /// Parse from a hex string.
    pub fn from_hex(s: &str) -> Result<Self, hex::FromHexError> {
        let bytes = hex::decode(s)?;
        if bytes.len() != 32 {
            return Err(hex::FromHexError::InvalidStringLength);
        }
        let mut arr = [0u8; 32];
        arr.copy_from_slice(&bytes);
        Ok(Self(arr))
    }
}

Hashing Functions

/// Hash arbitrary data using Blake3.
pub fn hash(data: &[u8]) -> Hash {
    Hash(blake3::hash(data).into())
}

/// Hash multiple pieces of data by concatenating them.
pub fn hash_concat(parts: &[&[u8]]) -> Hash {
    let mut hasher = blake3::Hasher::new();
    for part in parts {
        hasher.update(part);
    }
    Hash(hasher.finalize().into())
}

1.2 Cryptographic Identities

Digital signatures let us prove ownership without revealing secrets. We use Ed25519 for its speed and compact 64-byte signatures.

Think of blockchain cryptography like a bank account:

Blockchain	Bank Equivalent
Private Key	Your signature + PIN (secret, never share!)
Public Key	Your ID card (proves who you are)
Address	Your account number (share to receive funds)
Signing a Transaction	Signing a check to authorize payment
Account	Your bank account (balance + transaction history)

The key difference: in a bank, the bank verifies your signature. On a blockchain, anyone can verify it using math — no trusted third party needed.

Why Ed25519 Over secp256k1?

Ethereum uses secp256k1 (the same curve as Bitcoin). So why does Minichain choose Ed25519?

The Two Main Signature Schemes

Feature	Ed25519	secp256k1 (Ethereum)
Signature Size	64 bytes	64-65 bytes
Public Key Size	32 bytes	33-65 bytes (compressed/uncompressed)
Speed	Very fast (~5-10x faster signing)	Moderate
Public Key Recovery	❌ No (needs explicit pubkey)	✅ Yes (from signature + message)
Security Level	~128 bits	~128 bits
Standardization	Modern (2011)	Older (Bitcoin-era)
Use Cases	SSH, TLS, Signal	Bitcoin, Ethereum, most blockchains

Key Trade-off: Public Key Recovery

The biggest difference is public key recovery:

secp256k1 (Ethereum):

// Ethereum can recover the signer's public key from just the signature
let signature = sign(message, private_key);
let public_key = recover_pubkey(signature, message); // ✓ Possible
let address = hash(public_key); // Derive address from recovered pubkey

Ed25519 (Minichain):

// Ed25519 requires the public key to verify
let signature = sign(message, private_key);
// Cannot recover public key from signature alone!
// Must store/provide public key explicitly for verification
verify(message, signature, public_key); // ✓ Requires pubkey

Why This Matters for Blockchain

Ethereum’s Advantage (secp256k1):

Transactions only need signature (not public key) → smaller
Block headers don’t need author field → simpler
Address is directly derived from signature

Minichain’s Choice (Ed25519):

Faster signing/verification (important for throughput)
Simpler implementation (no complex recovery algorithm)
Smaller public keys (32 bytes vs 33-65 bytes)
Modern cryptography (designed with side-channel resistance)

Architectural Consequence: Since Ed25519 can’t recover public keys, Minichain blocks must include an explicit author field (see section on author field below). This is a small overhead (~20 bytes per block) in exchange for faster cryptography.

Why Ethereum Chose secp256k1

Why Minichain Chooses Ed25519

For a learning blockchain, the advantages are clear:

Priority	Why Ed25519 Wins
Simplicity	No complex recovery algorithm to implement
Performance	5-10x faster signing (better for testing/development)
Modern best practices	Recommended by cryptographers for new systems
Small overhead	Explicit `author` field is only ~20 bytes per block

Implementation in Minichain

Minichain uses battle-tested Rust crates for cryptography:

For Ed25519 signatures:

Crate: ed25519-dalek version 2.1
What it provides: Fast, safe Ed25519 signing and verification
Why this crate: Industry standard, used by Signal, 1Password, and many Rust projects
Features: Side-channel resistant, no unsafe code, thoroughly audited

For hashing (Blake3):

Crate: blake3 version 1.5
What it provides: Cryptographic hash function (addresses, block hashes, Merkle trees)
Why this crate: Fastest secure hash, official reference implementation
Performance: ~10x faster than SHA-256, parallelizable

// From crates/core/Cargo.toml
[dependencies]
blake3 = "1.5"
ed25519-dalek = { version = "2.1", features = ["rand_core"] }

Both crates are maintained by respected cryptography teams and widely used in production systems.

Address Derivation

An address is derived from a public key:

Address Derivation

pub type AddressBytes = [u8; 20];

#[derive(Clone, Copy, PartialEq, Eq, Hash, Default, Serialize, Deserialize)]
pub struct Address(pub AddressBytes);

impl Address {
    pub const ZERO: Self = Self([0u8; 20]);

    pub fn to_hex(&self) -> String {
        format!("0x{}", hex::encode(self.0))
    }

    pub fn from_hex(s: &str) -> Result<Self, CryptoError> {
        let s = s.strip_prefix("0x").unwrap_or(s);
        let bytes = hex::decode(s).map_err(|_| CryptoError::InvalidAddress)?;
        // ... validation
    }
}

The Keypair

A Keypair bundles signing and verification capabilities:

pub struct Keypair {
    signing_key: SigningKey,
    pub public_key: PublicKey,
}

impl Keypair {
    /// Generate a new random keypair.
    pub fn generate() -> Self {
        let signing_key = SigningKey::generate(&mut OsRng);
        let verifying_key = signing_key.verifying_key();
        Self {
            signing_key,
            public_key: PublicKey(verifying_key),
        }
    }

    /// Get the address derived from the public key.
    pub fn address(&self) -> Address {
        self.public_key.to_address()
    }

    /// Sign a message.
    pub fn sign(&self, message: &[u8]) -> Signature {
        let sig = self.signing_key.sign(message);
        Signature(sig.to_bytes())
    }
}

Usage Example

// Generate a new identity
let keypair = Keypair::generate();
println!("Address: {}", keypair.address());

// Sign a message
let message = b"hello blockchain";
let signature = keypair.sign(message);

// Verify the signature
assert!(keypair.public_key.verify(message, &signature).is_ok());

1.3 Account State

An account represents an entity on the blockchain — either a user or a smart contract.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Account {
    /// Transaction count / sequence number.
    pub nonce: u64,
    /// Account balance in the Mini Coin.
    pub balance: u64,
    /// Hash of the contract bytecode (None for EOAs).
    pub code_hash: Option<Hash>,
    /// Root hash of the account's storage trie.
    pub storage_root: Hash,
}

// Externally Owned Account - controlled by a private key
let user = Account::new_user(1000);
assert!(user.is_eoa());
assert_eq!(user.code_hash, None);

// Contract account - has associated bytecode
let code_hash = hash(b"contract bytecode");
let contract = Account::new_contract(code_hash);
assert!(contract.is_contract());
assert_eq!(contract.code_hash, Some(code_hash));

Why Two Types of Accounts?

Core analogy (one you can say in one breath): An EOA is like a personal bank account you control directly, while a contract account is like an automated corporate account that can only move money according to pre-written rules.

🧑‍💼 EOA (Externally Owned Account)

Analogy: Your personal savings/checking account

You control it with your signature → like signing a cheque or authorizing a transaction with your PIN
Money moves only when you explicitly approve it
No internal logic — it just sends and receives money

Blockchain mapping:

Controlled by a private key
Can initiate transactions
No code, just balance + nonce

🏢 Contract Account

Analogy: A corporate bank account with standing instructions (or an automated escrow)

No human “signs” transactions directly
Money moves only when predefined rules are satisfied (e.g., “release funds after both parties approve”)
Cannot act on its own — it reacts when someone triggers it

Blockchain mapping:

Controlled by code
Cannot initiate transactions by itself
Executes logic when called

Why Do We Need Both?

One subtle but important point: A contract account never “decides” to send money — it only executes instructions when someone calls it.

Bank analogy: A corporate account won’t randomly transfer funds. Someone submits a request, and the bank checks the rules before executing it.

The separation: Blockchain separates identity (EOA) from automation (contracts) — like separating a person from the company policies they operate under.

Nonce: Preventing Replay Attacks

The nonce field is critical for security.

Core analogy: A nonce is like a cheque number — the bank will only process each cheque number once, so you can’t reuse an old signed cheque to withdraw money again.

🧾 Cheque Number (Banking)

Every cheque has a unique, increasing number
The bank records the last used number
Reusing an old cheque = rejected
Skipping ahead is allowed, but going backward isn’t

🔢 Nonce (Blockchain)

Every account has a nonce (transaction counter)
Each transaction must use the next nonce
Replaying an old signed transaction = rejected
Ensures transactions execute once and in order

impl Account {
    pub fn increment_nonce(&mut self) {
        self.nonce = self.nonce.saturating_add(1);
    }
}

Every transaction must include the sender’s current nonce. This prevents:

Replay attacks — can’t resubmit the same transaction
Transaction ordering — nonces must be sequential

The nonce is part of the Account struct, which means every account’s nonce is included in the world state. The block’s state_root (covered later) is a cryptographic commitment to all account data, including nonces.

Why this matters for replay prevention:

// Account state (committed to by state_root)
pub struct Account {
    pub nonce: u64,        // ← This prevents replays
    pub balance: u64,
    pub code_hash: Option<Hash>,
    pub storage_root: Hash,
}

When a block is finalized with state_root = H, it cryptographically locks in:

Alice’s current nonce = 5
Bob’s current nonce = 12
All other account nonces

If someone tries to replay Alice’s transaction with nonce=5 in a future block, it will be rejected because Alice’s nonce has already moved to 6. The state_root in the block header proves what nonces were valid at that point in history.

Implementation: See crates/core/src/account.rs for the Account struct definition.

1.4 Transactions

A transaction is a signed request to change blockchain state.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Transaction {
    pub nonce: u64,              // Sender's nonce
    pub from: Address,           // Sender
    pub to: Option<Address>,     // Recipient (None = deploy)
    pub value: u64,              // Amount to transfer
    pub data: Vec<u8>,           // Calldata or bytecode
    pub gas_limit: u64,          // Max gas
    pub gas_price: u64,          // Price per gas unit
    pub signature: Signature,    // Ed25519 signature
}

Understanding Gas: `gas_limit` and `gas_price`

Core analogy: Gas is like a wire transfer fee — you set a maximum budget (gas_limit) and a rate you’re willing to pay (gas_price). The bank charges you only for the actual work done, up to your limit.

🏦 Wire Transfer Fee (Banking)

Fee cap: “I’ll pay up to $50 for this transfer”
Priority rate: Standard ( $5), Express ($ 15), Urgent ($30)
Actual charge: Bank charges based on complexity, but never exceeds your cap
If cap too low: Transfer is rejected (“insufficient fee budget”)

⛽ Gas (Blockchain)

gas_limit: Maximum gas units you’re willing to consume
gas_price: How much you pay per gas unit (higher = faster inclusion)
Actual cost: gas_used × gas_price (refund unused gas)
If limit too low: Transaction fails (“out of gas”), but fees are still consumed

Why Two Numbers? Why Not Just a Single Fee?

Question: Can’t we just say “I’ll pay $10 for this transaction” instead of gas_limit × gas_price?

The key insight: These two numbers measure different things.

Field	What It Measures	Who Controls It
`gas_limit`	Computation — how much work	The operation itself (deterministic)
`gas_price`	Priority — how fast you want it	You (market-driven)

🏦 Banking Analogy:

Think of it like shipping a package:

Weight/Size (gas_limit) = How big is your package? A letter vs a refrigerator need different resources.
Shipping Speed (gas_price) = Standard, Express, or Overnight? You choose based on urgency.

You can’t combine these into one number because:

A small package sent overnight (low gas, high price) costs differently than
A huge package sent standard (high gas, low price)

Why separation matters

Refunds work — You set gas_limit=100,000 but only use 21,000? You get 79,000 × gas_price back. A single fee = no refunds.
Predictable estimation — Gas for a transfer is always ~21,000. Gas for a complex contract call might be 500,000. You can estimate this before choosing your price.
Market flexibility — Network busy? Raise gas_price, not gas_limit. Your operation doesn’t need more computation, just faster inclusion.
Prevents overpaying — Single fee = you’d always pay maximum. Two numbers = pay only for actual work done.

Wait — Isn’t Gas Fixed for Simple Transfers?

Yes! For EOA → EOA transfers (no contract code), gas is always 21,000. It’s deterministic:

Verify signature → Check balance → Transfer value → Increment nonce

Same steps every time = same gas every time.

So why have gas_limit at all?

Transaction Type	Gas Usage
EOA → EOA transfer	Fixed: 21,000
Contract deployment	Variable: depends on bytecode size
Contract call	Variable: depends on code execution path

Ethereum compatibility: The 21,000 gas for EOA → EOA transfers matches Ethereum’s standard. This is hardcoded in Minichain’s executor:

// From crates/chain/src/executor.rs
fn execute_transfer(&self, tx: &Transaction)
    -> Result<(bool, u64, Option<Address>, Option<String>)> {
    let to = tx.to.expect("transfer must have recipient");

    // Transfer value
    if tx.value > 0 {
        self.state.transfer(&tx.from, &to, tx.value)?;
    }

    // Transfer uses 21,000 gas
    Ok((true, 21_000, None, None))
}

This constant ensures predictable costs for simple transfers across both chains.

The Transaction struct handles all types. For simple transfers, gas_limit = 21,000 is just a formality. For contract interactions, it’s crucial — the same function might use 50,000 or 500,000 gas depending on inputs and state.

Why Gas Exists

Problem	How Gas Solves It
Infinite loops in contracts	Execution stops when gas runs out
Spam transactions	Every operation costs money
Resource fairness	Users pay for computation they consume
Miner/validator incentives	Gas fees reward block producers

Quick Reference

Field	What It Means	Banking Equivalent
`gas_limit`	Max gas you’ll spend	Fee budget cap
`gas_price`	Cost per gas unit	Priority/speed tier
`gas_used`	Actual gas consumed	Actual fee charged
`gas_limit × gas_price`	Max possible cost	Worst-case fee

Transaction Types

A blockchain supports three fundamental operations, all using the same Transaction struct.

Why Three Types? The Human-Machine Perspective

Every blockchain transaction is initiated by a human (EOA). Machines (contracts) cannot act on their own — they only react when triggered. This gives us a natural categorization:

From	To	Type	What Happens
Human	Human	Transfer	Money moves, nothing else
Human	New Machine	Deploy	A new autonomous program is born
Human	Existing Machine	Call	The machine wakes up and executes its code

Notice what’s missing: Machine → Anyone as an initiating transaction. Contracts can send funds or call other contracts, but only during execution of a human-initiated transaction. A contract sitting idle will never “decide” to do something.

This isn’t a limitation — it’s a fundamental design choice. Two parallels from computing:

1. The Browser Event Loop

JavaScript in your browser doesn’t run continuously. It sits idle, waiting:

[idle] → user clicks button → [execute handler] → [idle] → user types → [execute handler] → [idle]

The code exists, but it only runs in response to human input. A webpage can’t decide “I’ll submit this form at 3 AM” without a human first setting that up.

“But what about setTimeout?” — Good question. setTimeout(() => doSomething(), 5000) seems autonomous, but:

A human loaded the page (initiating the runtime)
A human’s action (or page load) executed the code that scheduled the timeout
The browser must stay open — close it, and the timeout dies
There’s a persistent runtime (the browser process) actively watching the clock

Blockchains have no persistent runtime. There’s no daemon thinking “is it time yet?” between blocks. The chain only “wakes up” when someone submits a transaction. setTimeout works because the browser is always running in the background; contracts have no background.

2. CPU and I/O

A CPU doesn’t spontaneously read from disk. It executes instructions, and those instructions must originate from somewhere — ultimately, a human pressing the power button, launching a program, or triggering an action. Even “scheduled tasks” were scheduled by a human.

Contracts work the same way:

[idle] → human sends transaction → [execute code] → [idle] → human sends transaction → [execute code]

A contract might want to do something (e.g., “release funds after 30 days”), but it cannot wake itself up. Someone must send a transaction to trigger the check. This is why “keeper” services exist — humans (or bots run by humans) that poke contracts to execute time-sensitive logic.

Why this matters

Transfer (Human → Human): The simplest case. No code runs. Just update two balances. This is like handing cash to a friend — no intermediary, no rules, just value moving.
Deploy (Human → New Machine): You’re creating an autonomous agent that will live on the blockchain forever. It’s not sending money to someone — it’s bringing something into existence. That’s why to is None — there’s no recipient yet; you’re creating one.
Call (Human → Existing Machine): You’re waking up a sleeping program. The machine reads your input (data), possibly accepts your payment (value), executes its logic, and may trigger a chain reaction (calling other machines, sending funds, updating storage).

One Struct, Three Interpretations

Rather than three separate structs, we use one struct with different interpretations:

to = None → Deployment (no recipient — you’re creating one)
to = EOA → Transfer (recipient has no code)
to = Contract → Call (recipient has code, execute it)

This keeps the protocol simple while supporting all use cases:

// 1. Value Transfer
let transfer = Transaction::transfer(from, to, 1000, nonce, gas_price);

// 2. Contract Deployment (to = None)
let deploy = Transaction::deploy(from, bytecode, nonce, gas_limit, gas_price);

// 3. Contract Call
let call = Transaction::call(from, contract, calldata, value, nonce, gas_limit, gas_price);

1️⃣ Value Transfer (EOA → EOA)

Banking analogy: A simple bank transfer — move money from your account to someone else’s.

Field	Value	Meaning
`to`	Recipient address	Who receives the money
`value`	Amount	How much to send
`data`	Empty (`[]`)	No instructions needed
`gas_limit`	21,000 (fixed)	Always the same

What happens:

1. Verify signature ✓
2. Check sender.balance ≥ value + gas_fees ✓
3. sender.balance -= value
4. recipient.balance += value
5. sender.nonce += 1

2️⃣ Contract Deployment

Banking analogy: Opening a new automated escrow account with specific rules. You’re not sending money to someone — you’re creating a new rule-based account.

Field	Value	Meaning
`to`	`None`	No recipient — signals deployment
`value`	Usually 0	Initial balance for contract (optional)
`data`	Bytecode	The contract’s compiled code
`gas_limit`	Variable	Depends on bytecode size + initialization

What happens:

1. Verify signature ✓
2. Compute contract address = hash(sender, nonce)
3. Create new account at that address
4. Store bytecode in contract account
5. Execute constructor (initialization code)
6. sender.nonce += 1

Key insight: The contract address is deterministic — you can know it before deploying!

3️⃣ Contract Call

Banking analogy: Triggering a standing instruction on a corporate account. You send a request (and optionally money), and the account’s pre-programmed rules execute.

Field	Value	Meaning
`to`	Contract address	Which contract to interact with
`value`	Optional	Send money along with the call
`data`	Calldata	Function selector + encoded arguments
`gas_limit`	Variable	Depends on what the code does

What happens:

1. Verify signature ✓
2. Load contract code from `to` address
3. Execute code with `data` as input
4. Code may: read/write storage, send funds, call other contracts
5. If success: state changes persist
6. If failure: all changes reverted (but gas still consumed!)

Quick Comparison

	Transfer	Deploy	Call
`to`	Recipient	`None`	Contract
`data`	Empty	Bytecode	Calldata
`value`	Amount	Initial balance	Payment to contract
Gas	Fixed (21k)	Variable	Variable
Creates account?	No*	Yes	No
Executes code?	No	Constructor only	Yes

*Transfer creates recipient account if it doesn’t exist (with zero code)

Signing Transactions

We sign the hash of the transaction data (excluding the signature itself):

impl Transaction {
    pub fn signing_hash(&self) -> Hash {
        // Serialize everything except signature
        let unsigned = UnsignedTransaction { /* ... */ };
        let encoded = bincode::serialize(&unsigned).unwrap();
        hash(&encoded)
    }

    pub fn sign(&mut self, keypair: &Keypair) {
        let hash = self.signing_hash();
        self.signature = keypair.sign_hash(&hash);
    }
}

Contract Address Derivation

When deploying a contract, the address is deterministic:

pub fn contract_address(&self) -> Option<Address> {
    if !self.is_deploy() {
        return None;
    }
    // Address = hash(sender || nonce)[0..20]
    let mut data = Vec::new();
    data.extend_from_slice(&self.from.0);
    data.extend_from_slice(&self.nonce.to_le_bytes());
    let h = hash(&data);
    // First 20 bytes
    Some(Address(h.0[..20].try_into().unwrap()))
}

Notice the formula: address = hash(sender + nonce) — the bytecode is not included.

“Does this mean identical contracts get the same address?” — No!

Scenario	Result
Same person deploys same contract twice	Different addresses (nonce increments)
Two people deploy identical contracts	Different addresses (different senders)

You can deploy unlimited copies of the same logic — each gets a unique address. This is intentional:

Multiple instances — Deploy 10 token contracts with same code, different state
No race conditions — Two people deploying identical code don’t collide

Ethereum’s CREATE2 is an alternative that does include bytecode:

address = hash(0xff + sender + salt + hash(bytecode))

This gives deterministic addresses for the same code (useful for cross-chain deployments). Our implementation uses the simpler CREATE formula.

1.5 Blocks

A block packages transactions into an ordered, tamper-evident unit.

Block Header

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct BlockHeader {
    pub height: u64,
    pub timestamp: u64,
    pub prev_hash: Hash,
    pub merkle_root: Hash,
    pub state_root: Hash,
    pub author: Address,
    pub difficulty: u64,
    pub nonce: u64,
}

Need of `height` and `timestamp`

Straightforward — block number (0-indexed from genesis) and Unix timestamp when the block was produced.

`prev_hash` — The Chain Link

Hash of the previous block’s header. This is what makes it a chain — each block cryptographically commits to its parent. Tamper with any historical block → all subsequent hashes change → immediately detectable.

`merkle_root` — Transaction Commitment

A block can contain hundreds of transactions, but we represent them with a single 32-byte hash:

Merkle Tree Structure

Change any transaction → the root changes. This is a merkle tree — we’ll cover it in detail in section 1.6.

`state_root` — World State Commitment and the need of it.

While merkle_root commits to the inputs (transactions), state_root commits to the outputs (resulting world state after execution).

Before Block 5:                     After Block 5:
┌────────────────────────┐          ┌────────────────────────┐
│ Alice: 100 Mini Coins │          │ Alice: 70 Mini Coins │  ← sent 30
│ Bob:   50 Mini Coins │  ──────►  │ Bob:   80 Mini Coins │  ← received 30
│ Contract X: ...        │  [txs]   │ Contract X: ...       │
└────────────────────────┘          └────────────────────────┘
        ↓                                  ↓
   state_root_4                       state_root_5

Use Case	How state_root Helps
Consensus	Nodes must agree on the result, not just the transactions. Same txs must produce same state_root, or something’s wrong.
Light clients	Ask “What’s Alice’s balance?” → get merkle proof against state_root. No need to download all accounts.
State sync	New node downloads current state, verifies against latest state_root. No need to replay all history from genesis.
Detecting bugs	If two nodes get different state_roots from same transactions → non-determinism bug (serious!).
Replay protection	Commits to all account nonces. Once a block is finalized, you can prove what nonces were valid at that height.

The key insight: merkle_root proves “these transactions were included.” state_root proves “executing them produced this exact world state.”

Since state_root is a cryptographic commitment to all accounts (including their nonces), it indirectly proves the replay-protection state at any given block height.

Example scenario:

Block 100: state_root = 0xabc...
  └─ Alice: { nonce: 5, balance: 1000, ... }

Block 101: state_root = 0xdef...
  └─ Alice: { nonce: 6, balance: 900, ... }  ← nonce incremented

Anyone can verify:

At block 100, Alice’s valid nonce was 5
At block 101, Alice’s valid nonce is 6
Trying to replay a transaction with nonce=5 after block 100? Rejected!

The state_root in each block header cryptographically commits to these nonce values, making historical replay attacks provably invalid. See the Nonce section for how nonces prevent replays.

Is it built the same way as merkle_root?

Both are merkle roots, but the underlying structure differs:

	`merkle_root`	`state_root`
Data	List of transactions	Map of address → account
Structure	Simple merkle tree	Merkle Patricia Trie
Access	Sequential (all txs)	Key-value lookup (by address)
Updates	Build fresh each block	Incremental (only changed accounts)

Transactions are a list — simple merkle tree works. Accounts are a key-value map with millions of entries — needs a trie (prefix tree) for efficient lookups and partial updates.

Why this matters: No need to replay history!

Without state_root, answering “What’s Alice’s balance?” would require:

Start at genesis → replay Block 1 → replay Block 2 → ... → replay Block 1,000,000
"Alice has 70 Mini Coins"

With state_root, you just:

Look up Alice in current state trie → verify proof against state_root
"Alice has 70 Mini Coins" ✓

The entire history is “compressed” into the latest state. You don’t trace back — you look up directly.

We’ll explore the state trie implementation in Chapter 2: Storage.

`author` — Block Producer

In a single-authority PoA, you might wonder: “We know who the authority is, why store author?”

Single authority: Technically redundant — every block is signed by the same authority.

Multiple rotating authorities:

Authorities = [Alice, Bob, Carol]
Block 0 → Alice's turn
Block 1 → Bob's turn
Block 2 → Carol's turn

Even here, you could derive author from height % num_authorities. But explicit author helps when:

Scenario	Why author is useful
Authority skips slot	If Bob is offline, Alice produces block 1 instead. Can’t derive from height.
Dynamic authority set	Authorities added/removed over time. History needs to record who actually signed.
Self-describing blocks	Block makes sense without external context (which authority set was active at that height?).

Also: Ed25519 requires it. Unlike secp256k1 (Ethereum), you can’t recover the public key from an Ed25519 signature. So we need author to look up the correct public key for verification. (See Why Ed25519 Over secp256k1? for a detailed comparison.)

We’ll decide between single vs rotating authorities when implementing the consensus layer in Chapter 5.

`difficulty` and `nonce` — PoW Artifacts

These fields are Proof of Work concepts that don’t really apply to PoA:

In PoW (Bitcoin, old Ethereum):

difficulty = how hard the mining puzzle is
nonce = the value miners iterate to solve: hash(block + nonce) < target

Miners burn electricity trying billions of nonces until they find a valid hash. Higher difficulty = more attempts needed.

In PoA: No puzzle. The authority just signs. Both fields are meaningless.

So why include them?

Some PoA chains repurpose difficulty:

Chain	Repurposed meaning
Clique (Geth)	`2` = in-turn validator, `1` = out-of-turn (helps fork choice)
Aura (Parity)	Step number in rotation

For minichain: We keep them as placeholders for now. A truly minimal PoA chain could remove both — we may do so once we finalize the consensus design in Chapter 5.

Block Size: How Many Transactions Fit?

A block can’t grow forever — we need limits. Different blockchains use different approaches:

Approach	How It Works	Used By
Byte size	Raw data limit (e.g., 1MB)	Bitcoin
Gas limit	Total computation budget per block	Ethereum
Transaction count	Direct cap on number of txs	Some chains

Why gas limit is the best fit for smart contract chains:

Limit Type	Problem
Max transactions	1000 complex contract calls could take minutes to execute
Max bytes	Small bytecode can still have expensive infinite loops
Max gas	Directly limits computation time, regardless of tx count or size

With a block gas limit, the math becomes predictable:

BLOCK_GAS_LIMIT = 30,000,000

Block can fit:
├─ ~1,428 simple transfers (21,000 gas each)
├─ OR ~60 complex contract calls (500,000 gas each)
└─ OR any mix where total_gas ≤ 30M

The block producer’s algorithm:

while let Some(tx) = mempool.next_by_gas_price() {
    if block.total_gas() + tx.gas_limit <= BLOCK_GAS_LIMIT {
        block.add(tx);
    }
}

Higher gas_price = picked first. This is why fees spike when the network is busy — users outbid each other for limited block space.

When you submit a transaction, it doesn’t go directly into a block. It enters the mempool (memory pool) — a waiting room for pending transactions.

User submits tx → [Mempool] → Block producer picks txs → [Block]
                     ↑
            Other pending txs waiting here

Message Queue Analogy:

If you’ve used RabbitMQ, Kafka, or AWS SQS, the mempool works similarly:

Message Queue	Blockchain Mempool
Producer submits job	User submits transaction
Queue holds pending jobs	Mempool holds pending txs
Worker picks jobs (FIFO or priority)	Block producer picks txs (by `gas_price`)
Job gets processed	Transaction gets included in block
Acknowledgment	Transaction confirmed on-chain

The key difference: in a message queue, workers typically process jobs FIFO (first-in-first-out). In a mempool, it’s a priority queue — whoever pays the highest gas_price jumps the line.

What if the mempool is nearly empty?

Unlike message queues that might wait for a batch to fill, blockchains are time-driven, not fullness-driven:

Block interval = 12 seconds

├─ Mempool has 1000 txs? → Produce block with top txs up to gas limit
├─ Mempool has 5 txs?    → Produce block with those 5 txs
└─ Mempool is empty?     → Produce empty block (still valid!)

Think of it like a scheduled bus: the bus leaves at 9:00 AM whether it’s packed or has one passenger. Waiting for a “full” bus would make arrival times unpredictable.

Why not wait for a full block?

Liveness — users expect predictable confirmation times
Consensus — fixed intervals simplify block timing and validation
Empty blocks are cheap — a block with no transactions still advances the chain, updates timestamps, and maintains heartbeat

Why do we need it?

Blocks aren’t instant — transactions arrive continuously, but blocks are produced periodically (e.g., every 12 seconds)
Prioritization — producers pick highest gas_price first, so the mempool must be sortable
Validation staging — basic checks (valid signature, sufficient balance) happen before entering the mempool
Network propagation — nodes share their mempools so transactions reach block producers

Without a mempool: You’d need to produce a block for every single transaction — no batching, no prioritization, extremely inefficient.

We’ll implement the mempool in Chapter 5 as part of the chain orchestration layer.

The Chain of Blocks

Each block references its parent via prev_hash:

┌─────────┐    ┌─────────┐    ┌─────────┐
│ Block 0 │◄───│ Block 1 │◄───│ Block 2 │
│ Genesis │    │         │    │         │
└─────────┘    └─────────┘    └─────────┘
prev_hash=0    prev_hash=     prev_hash=
               hash(Block0)   hash(Block1)

Genesis Block

The genesis block is special — it has no parent:

impl Block {
    pub fn genesis(authority: Address) -> Self {
        Self {
            header: BlockHeader {
                height: 0,
                timestamp: BlockHeader::current_timestamp(),
                prev_hash: Hash::ZERO,  // No parent!
                merkle_root: Hash::ZERO,
                state_root: Hash::ZERO,
                author: authority,
                difficulty: 1,
                nonce: 0,
            },
            transactions: Vec::new(),
            signature: Signature::default(),
        }
    }
}

Block Signing (PoA)

In Proof of Authority, the designated authority signs each block:

impl Block {
    pub fn sign(&mut self, keypair: &Keypair) {
        let hash = self.header.hash();
        self.signature = keypair.sign_hash(&hash);
    }

    pub fn verify_signature(&self, public_key: &PublicKey) -> bool {
        let hash = self.header.hash();
        public_key.verify(hash.as_bytes(), &self.signature).is_ok()
    }
}

1.6 Merkle Trees

A merkle tree lets us summarize many items into a single hash, with efficient proofs.

Merkle Tree Structure

Here’s how a 4-transaction merkle tree is constructed:

Transactions:           T0          T1          T2          T3
                        │           │           │           │
                        ↓           ↓           ↓           ↓
Leaf Hashes:         H(T0)       H(T1)       H(T2)       H(T3)
                        │           │           │           │
                        └────┬──────┘           └────┬──────┘
                             │                       │
                             ↓                       ↓
Branch Hashes:           H(H(T0)+H(T1))         H(H(T2)+H(T3))
                             │                       │
                             └───────────┬───────────┘
                                         │
                                         ↓
Merkle Root:                      H(Branch0+Branch1)
                                (stored in block header)

Proof that T1 is in the block:

To prove T1 exists without providing T0, T2, T3:

Prover sends:
  1. T1 (the transaction data)
  2. H(T0)           ← Sibling hash
  3. H(T2+T3)        ← Uncle hash

Verifier computes:
  Step 1: H(T1) → get transaction hash
  Step 2: H(T0) + H(T1) → compute H(T0,T1)
  Step 3: H(T0,T1) + H(T2,T3) → compute Root
  Step 4: Compare with block header's merkle_root

If match → T1 is in the block ✓

Computing the Root

pub fn merkle_root(hashes: &[Hash]) -> Hash {
    if hashes.is_empty() {
        return Hash::ZERO;
    }
    if hashes.len() == 1 {
        return hashes[0];
    }

    let mut current_level: Vec<Hash> = hashes.to_vec();

    while current_level.len() > 1 {
        let mut next_level = Vec::new();
        for chunk in current_level.chunks(2) {
            let combined = if chunk.len() == 2 {
                hash_concat(&[chunk[0].as_ref(), chunk[1].as_ref()])
            } else {
                // Odd number: hash with itself
                hash_concat(&[chunk[0].as_ref(), chunk[0].as_ref()])
            };
            next_level.push(combined);
        }
        current_level = next_level;
    }

    current_level[0]
}

Why Merkle Trees?

Integrity — Any change to any transaction changes the root
Efficiency — Prove inclusion in O(log n) space
Light clients — Verify transactions without full block data

Merkle Proofs

pub struct MerkleProof {
    pub leaf: Hash,           // The item being proven
    pub siblings: Vec<Hash>,  // Sibling hashes on path to root
    pub directions: Vec<bool>, // Left or right at each level
}

To verify: reconstruct the path from leaf to root using siblings.

Summary

We’ve built the cryptographic foundation:

Component	What It Does
`Hash`	256-bit Blake3 digest
`Address`	160-bit identity derived from public key
`Keypair`	Ed25519 key pair for signing
`Account`	User or contract state
`Transaction`	Signed state change request
`Block`	Ordered batch of transactions
`MerkleTree`	Efficient transaction commitment

Tests Passing

$ cargo test -p minichain-core

running 47 tests
test account::tests::test_new_user_account ... ok
test crypto::tests::test_sign_and_verify ... ok
test block::tests::test_genesis_block ... ok
test merkle::tests::test_merkle_proof_valid ... ok
# ... all 47 tests pass

What’s Next?

With our primitives in place, we’re ready to build the storage layer in Chapter 2, where we’ll persist accounts, blocks, and contract state using sled.

Chapter 1: Core Primitives

What We’re Building

1.1 Hashing with Blake3

Why Blake3?

The Hash Type

Hashing Functions

1.2 Cryptographic Identities

Why Ed25519 Over secp256k1?

The Two Main Signature Schemes

Key Trade-off: Public Key Recovery

Why This Matters for Blockchain

Why Ethereum Chose secp256k1

Why Minichain Chooses Ed25519

Implementation in Minichain

Address Derivation

The Keypair

Usage Example

1.3 Account State

Two Types of Accounts

Why Two Types of Accounts?

🧑‍💼 EOA (Externally Owned Account)

🏢 Contract Account

Why Do We Need Both?

Nonce: Preventing Replay Attacks

🧾 Cheque Number (Banking)

🔢 Nonce (Blockchain)

1.4 Transactions

Understanding Gas: gas_limit and gas_price

🏦 Wire Transfer Fee (Banking)

⛽ Gas (Blockchain)

Why Two Numbers? Why Not Just a Single Fee?

Why separation matters

Wait — Isn’t Gas Fixed for Simple Transfers?

Why Gas Exists

Quick Reference

Transaction Types

Why Three Types? The Human-Machine Perspective

Why this matters

One Struct, Three Interpretations

1️⃣ Value Transfer (EOA → EOA)

2️⃣ Contract Deployment

3️⃣ Contract Call

Quick Comparison

Signing Transactions

Contract Address Derivation

1.5 Blocks

Block Header

Need of height and timestamp

prev_hash — The Chain Link

merkle_root — Transaction Commitment

state_root — World State Commitment and the need of it.

author — Block Producer

difficulty and nonce — PoW Artifacts

Block Size: How Many Transactions Fit?

The Chain of Blocks

Genesis Block

Block Signing (PoA)

1.6 Merkle Trees

Merkle Tree Structure

Computing the Root

Why Merkle Trees?

Merkle Proofs

Summary

Tests Passing

What’s Next?

Understanding Gas: `gas_limit` and `gas_price`

Need of `height` and `timestamp`

`prev_hash` — The Chain Link

`merkle_root` — Transaction Commitment

`state_root` — World State Commitment and the need of it.

`author` — Block Producer

`difficulty` and `nonce` — PoW Artifacts