Blockchain basics, from zero

Before looking at the code, we need five ideas. If you understand these, the rest of the guide is just "where each idea lives in the project". No prior blockchain knowledge is assumed.

1 · Hash functions

A hash function takes any input (text, file, anything) and produces a fixed-length "fingerprint" — for SHA-256, always 64 hex characters. Two properties matter here:

• Deterministic: same input always gives the same hash.
• Avalanche effect: change one bit of the input and the hash changes completely.
• One-way: you can't go from hash back to input (brute force only).

X-Change uses hashes everywhere: transaction hashes, block hashes, Merkle roots, address derivation, and the proposer lottery. Each is just SHA-256 (or SHA3-256) of a string.

2 · Public-key cryptography (ed25519)

A keypair is two linked values:

• Secret key — a random 32-byte number you keep private. It can sign messages.
• Public key — derived from the secret key. Anyone can use it to verify a signature, but cannot forge one.

In X-Change every user has an ed25519 keypair. Their blockchain address is derived from the public key:

1// address = "0x" + hex(sha3-256(pubkey)[..20])
2export function deriveAddress(rawPubkey: Uint8Array): string {
3  return "0x" + bytesToHex(sha3(rawPubkey).subarray(0, 20));
4}

3 · Blocks and the chain

A block is a bundle of transactions plus some metadata. Each block stores the hash of the previous block — that link is what makes it a chain and why it's nearly impossible to rewrite history.

In X-Change a block looks like this:

1pub struct Block {
2    pub index: i64,          // block number, starts at 0 (genesis)
3    pub hash: String,        // sha256 of the fields below
4    pub prev_hash: String,   // hash of the previous block  <-- THE LINK
5    pub merkle_root: String, // one hash summarising all tx hashes
6    pub proposer: String,    // who produced this block
7    pub tx_hashes: Vec<String>,
8    pub created_at: i64,     // unix milliseconds
9}

A new block is produced every 3 seconds on a timer. Its hash is:

1fn compute_hash(&self) -> String {
2    let raw = format!(
3        "{}|{}|{}|{}|{}|{}",
4        self.index, self.prev_hash, self.merkle_root,
5        self.proposer, self.tx_hashes.join(","), self.created_at
6    );
7    sha256hex(raw.as_bytes())
8}

Merkle trees: summarise a list of transactions

Instead of storing every transaction hash separately, blocks store one Merkle root — hashes are combined in pairs, level by level, until one hash remains. If any transaction is altered, the root changes and the block is invalid.

4 · Consensus: who produces the block?

A blockchain needs a rule for deciding which block is the "real" next one, otherwise two nodes could disagree. Proof of Stake (PoS) says: the more coins you have locked up (staked), the more often you get to propose blocks — and the more you have to lose if you misbehave.

X-Change implements a deterministic, stake-weighted lottery:

1// seed = sha256("proposer|{height}|{total_stake}")
2// pick  = first 16 hex chars of seed as a number, mod total stake
3// walk validators by cumulative stake; the one you land on is the proposer
4pub fn select_proposer(validators: &[(String, i64)], height: i64) -> Option<String> { ... }

Because the seed depends only on height and total stake, every node computes the same proposer for a given height. No voting, no messages — just a hash.

5 · A signed transaction

A transaction moves value from one address to another. To prove the sender actually owns the from address, they sign a canonical message with their secret key. The node re-derives the message, checks the signature, and also checks the sender has enough balance and a matching nonce (a per-account counter that stops the same transaction being replayed).

Once validated, the transaction goes into the mempool (a waiting room). The next block produced includes it, and it's marked confirmed.

Recap — the five ideas

Now you're ready. Everything else is "where each of these five ideas lives in the code". Start with the Architecture → Architecture Overview, then dive into the Backend → Backend.