Ogni riga di codice,
spiegata in italiano

Questa è una nota di copyright. Indica che il codice è scritto e mantenuto dagli sviluppatori di Bitcoin Core dal 2009 (anno della nascita di Bitcoin) fino al 2023.

La licenza MIT è una licenza open source molto permissiva. Significa che chiunque può usare, copiare, modificare e distribuire questo codice liberamente, anche per scopi commerciali, a patto di mantenere questa nota.

#ifndef significa "se non è definito". Insieme alla riga successiva, questo è un header guard: evita che questo file venga caricato due volte nello stesso programma, il che causerebbe errori.

#define "marca" il file come già caricato. La prossima volta che il compilatore vede #ifndef BITCOIN_CHAIN_H, sa che è già stato incluso e lo salta.

#include importa un altro file di codice. uint256.h definisce il tipo di dato che rappresenta un numero a 256 bit — usato per gli hash SHA-256 di Bitcoin. Un hash a 256 bit è un numero con 78 cifre decimali.

Importa un file per fare operazioni aritmetiche su numeri a 256 bit (addizione, confronto, ecc.). Necessario per confrontare le difficoltà di mining.

class crea un tipo di dato personalizzato. CBlockIndex è la struttura che rappresenta un singolo blocco nella blockchain. La "C" davanti è una convenzione del codice Bitcoin per indicare una "classe". Tutto ciò che è racchiuso tra le parentesi graffe { } appartiene a questa classe.

public: significa che le variabili e funzioni che seguono sono accessibili da qualsiasi parte del programma. È il contrario di private:, che nasconde i dati all'esterno.

phashBlock è il hash di questo blocco — la sua "impronta digitale" univoca a 256 bit. Come un'impronta digitale umana, è unica per ogni blocco. Se cambi anche solo un byte nel blocco, l'hash cambia completamente. Il tipo uint256 è un intero senza segno da 256 bit.

pprev è un puntatore al blocco precedente. La * indica che è un puntatore (una freccia che punta a un altro oggetto in memoria). Questo è esattamente ciò che crea la "catena" nella blockchain: ogni blocco tiene un riferimento diretto al blocco che lo precede.

nHeight è l'altezza del blocco — cioè la sua posizione nella catena, partendo da 0 (il blocco Genesis). Il blocco #0 è quello creato da Satoshi Nakamoto il 3 gennaio 2009. Al 2024, l'altezza supera i 820.000 blocchi.

nTime è il timestamp del blocco — l'ora esatta in cui il blocco è stato minato, espresso come numero di secondi trascorsi dalla mezzanotte del 1 gennaio 1970 (Unix timestamp). int64_t è un intero a 64 bit, sufficiente per rappresentare date fino all'anno 292 miliardi.

nBits rappresenta la difficoltà di mining di questo blocco, in formato compresso. La difficoltà determina quanto deve essere piccolo l'hash per essere accettato dalla rete. Si ricalibra ogni 2016 blocchi (~2 settimane) per mantenere un tempo medio di 10 minuti per blocco.

nNonce è il numero casuale che i miner modificano milioni di volte al secondo per trovare un hash valido. "Nonce" sta per "number used once". È il campo che i miner cambiano durante il mining finché non trovano un hash che inizia con abbastanza zeri.

Questa è una funzione (metodo) chiamata GetBlockTime. Restituisce (int64_t) il tempo del blocco. La parola const garantisce che questa funzione non modifica nulla — legge solo. Le funzioni sono blocchi di codice riutilizzabili che fanno una cosa specifica.

return restituisce un valore alla parte del programma che ha chiamato questa funzione. Il (int64_t) è un cast: converte nTime (che era uint32_t) nel tipo int64_t, garantendo che non ci siano problemi con numeri grandi o negativi.

La parentesi graffa chiusa } segna la fine della funzione GetBlockTime. Tutto il codice tra la { di apertura e questa } appartiene a quella funzione.

IsValid() è una funzione che restituisce un bool (booleano: vero o falso). Verifica se questo blocco è valido secondo le regole del protocollo Bitcoin: formato corretto, difficoltà rispettata, transazioni valide, ecc. Il ; finale indica che questa è solo la dichiarazione — il corpo della funzione è definito altrove.

Questa funzione verifica la Proof of Work (prova di lavoro) — il meccanismo fondamentale di Bitcoin. Controlla che l'hash del blocco sia effettivamente minore del target di difficoltà. Riceve l'hash calcolato e il valore di difficoltà (nBits).

Crea una variabile bnTarget di tipo arith_uint256 che conterrà il valore target: il numero massimo che l'hash del blocco deve avere per essere valido. Più basso è il target, più difficile è il mining.

SetCompact decomprime nBits nel numero target completo a 256 bit. Bitcoin usa una rappresentazione compressa (4 byte) per la difficoltà per risparmiare spazio nell'header del blocco.

Questo è il controllo centrale del mining. Converte l'hash in un numero e lo confronta con il target. Se l'hash è maggiore del target, il blocco non è valido. I miner cercano un hash che sia minore del target. Statisticamente, un hash su X miliardi soddisfa questa condizione.

Se l'hash è troppo grande (mining non valido), la funzione restituisce false — blocco rifiutato. Questo è il meccanismo che rende impossibile falsificare un blocco senza rifarlo il lavoro computazionale.

Se arriviamo a questa riga, significa che l'hash è valido (minore del target). La funzione restituisce true: il blocco ha superato il controllo della Proof of Work e può essere aggiunto alla blockchain.