Vai al contenuto
← Blockchain e smart contract · Lezione 12
Blockchain e smart contract · Lezione 12

Governance, multisig e timelock

Chi decide, quante approvazioni servono e quando una modifica diventa eseguibile.

Scarica e prepara il laboratorio

Prima di iniziare

Segui una decisione dalle approvazioni fino alla chiamata che modifica davvero il contratto.

Scarica e prepara i materiali del corso. Dalla cartella lezioniSmartContracts entra nel laboratorio:

cd lezioni/12-governance-owner-multisig-timelock

src/governance/GovernedEscrow.sol · src/governance/ToyMultisig.sol · src/governance/ToyTimelock.sol

Le demo sono facoltative e locali. Prima di eseguirle, prevedi il risultato; poi confronta le asserzioni del test con la spiegazione. I risultati riportati sono quelli attesi: un PASS può confermare anche un difetto intenzionale. Per vedere i comandi disponibili usa bash demo.sh help; per la suite ordinaria usa bash demo.sh check. Un filtro che seleziona zero test non verifica il comportamento.

ToyMultisig usa approvazioni on-chain dei chiamanti: il laboratorio non implementa raccolta e verifica di firme off-chain.

1. Un controllo corretto può proteggere un potere eccessivo

Nella lezione sull’access control abbiamo chiesto: un estraneo riesce a chiamare una funzione riservata? Oggi facciamo una domanda diversa: se la persona autorizzata sbaglia o perde la chiave, quanto può cambiare e quanto rapidamente?

onlyOwner può funzionare perfettamente e lasciare a una singola chiave il potere di cambiare commissioni, oracle o implementation. Il controllo del chiamante è necessario, ma non descrive da solo una governance adeguata.

Autorità: quale indirizzo può eseguire questa operazione?
Quorum: quante approvazioni distinte servono per decidere?
Tempo: quanto deve passare prima che la decisione sia eseguibile?

Un multisig risponde al quorum. Un timelock aggiunge una finestra temporale. Nessuno dei due decide automaticamente se la proposta sia economicamente corretta.

Anche due chiavi diverse possono essere controllate dalla stessa persona o compromesse dallo stesso dispositivo. Il contratto conta indirizzi; l’indipendenza operativa delle persone è una questione ulteriore.

2. Disegniamo i poteri prima dei modificatori

Osserva src/governance/GovernedEscrow.sol.

Qui owner può cambiare fee e oracle. Un ruolo di emergenza può mettere in pausa. L’owner può riaprire. Già questa separazione è una scelta: chi deve fermare rapidamente un’operazione non riceve anche il potere di riscrivere le regole o riavviare il sistema.

Azione Autorità nel contratto
Cambiare fee o oracle owner
Mettere in pausa emergencyPauser
Rimuovere la pausa owner
Accettare la proprietà proposta pendingOwner

Non memorizziamo soltanto i nomi dei ruoli. Per ogni funzione privilegiata seguiamo il chiamante ammesso e poi chiediamo chi controlla quell’indirizzo. Se owner è un altro contratto, dobbiamo continuare la catena.

3. Trasferimento in due fasi

Supponiamo che Alice sia owner e voglia trasferire il potere a Bob. In una procedura immediata un indirizzo sbagliato può far perdere il controllo. Qui Alice propone Bob, poi Bob deve accettare.

Durante l’attesa Alice è ancora owner. pendingOwner non è un secondo amministratore: è il candidato che può completare il trasferimento.

owner = Alice, pendingOwner = nessuno
Alice propone Bob
owner = Alice, pendingOwner = Bob
Bob accetta
owner = Bob, pendingOwner = nessuno
bash demo.sh trasferimento

Risultato atteso: due test PASS: il candidato deve accettare; il vecchio owner mantiene l’autorità fino all’accettazione.

Domanda: Se il nuovo owner deve essere un timelock, basta impostarlo come pendingOwner?

No. Serve anche l’accettazione effettuata dal timelock, attraverso il suo percorso di esecuzione. Il trasferimento non è completo finché il contratto applicativo non mostra il timelock come owner effettivo.

Le due fasi riducono errori operativi, ma non proteggono un trasferimento deliberatamente malevolo da parte dell’owner corrente. Non attribuiamo al meccanismo una garanzia che non offre.

4. Multisig: tre indirizzi, due approvazioni

Osserva src/governance/ToyMultisig.sol.

Configuriamo Alice, Bob e Carol, con soglia due. La proposta contiene target, value e data: dove chiamare, quanti wei inviare e quale funzione eseguire con quali argomenti.

Il target è vincolato dalla proposta. Non approviamo una frase come “sistemare la fee”: approviamo una chiamata precisa.

submit crea la proposta, ma qui non conta come approvazione. Anche chi propone deve chiamare approve. Alice approva: siamo a uno. Alice prova ad approvare ancora: viene respinta. Bob approva: siamo a due. A quel punto un owner del multisig può eseguire la proposta.

bash demo.sh quorum

Risultato atteso: tre test PASS: una sola approvazione non basta, una doppia approvazione dello stesso owner è rifiutata, due approvazioni consentono l’esecuzione.

Il mapping approvedBy collega ogni proposta a ciascun approvatore. Senza questa distinzione, contare semplicemente le chiamate permetterebbe a una chiave di raggiungere da sola la soglia.

Prima della chiamata esterna execute segna la proposta come eseguita. Se il target fallisce, il multisig fa revert e anche quel flag torna indietro. Se il target riesce, la stessa proposta non deve poter essere eseguita di nuovo.

Domanda: Con due firme abbiamo anche due giorni di attesa?

No. Il quorum non introduce tempo. Dopo la seconda approvazione una proposta può diventare subito eseguibile. Per l’attesa serve un altro vincolo.

5. Timelock: una chiamata precisa, dopo un momento preciso

Osserva src/governance/ToyTimelock.sol.

Il proposer programma l’operazione. Il canceller può cancellarla. L’executor può eseguirla quando è pronta. Nel nostro modello il ruolo executor assegnato all’indirizzo zero apre l’esecuzione a chiunque: chi esegue non sceglie però una nuova operazione, perché deve rispettare quella già programmata.

L’identità dell’operazione è l’hash di target, value, data, predecessor e salt. Se cambiamo la fee nella calldata, stiamo parlando di un’altra operazione. Il salt permette di distinguere operazioni con altri parametri uguali. Il predecessor, se presente, impone che un’operazione precedente sia già conclusa.

Programmazione: lunedì 10:00
Delay:          48 ore
readyAt:        mercoledì 10:00

mercoledì 09:59:59 → troppo presto
mercoledì 10:00:00 → pronta
bash demo.sh tempo

Risultato atteso: due test PASS: prima del limite l’esecuzione è rifiutata; esattamente al limite è consentita.

Il controllo usa il timestamp della chain. Nella demo vm.warp ci porta sui confini senza attendere due giorni. Il timelock non invia da solo la transazione allo scadere: ready significa eseguibile, non già eseguita.

Domanda: Perché aspettare se la proposta è già approvata?

Per dare tempo a osservare una modifica e reagire secondo i meccanismi disponibili: cancellazione autorizzata, valutazione del rischio, eventuale uscita se il protocollo la consente. Il tempo è utile soltanto se qualcuno osserva e dispone di azioni efficaci.

6. Cancellazione e tentativi falliti

Unset → Waiting → Ready → Done
           │        │
           └────────┴──→ Cancelled

Il canceller può intervenire sia mentre aspettiamo sia quando l’operazione è pronta, purché non sia già conclusa. Un’operazione cancellata non diventa eseguibile solo perché è trascorso il tempo originario.

In questo modello si può riprogrammare un’identità cancellata. La nuova programmazione deve rispettare di nuovo il ritardo: cancellare non crea un lasciapassare per un’esecuzione immediata.

bash demo.sh cancellazione

Risultato atteso: due test PASS: un’operazione cancellata non viene eseguita; il fallimento del target lascia l’operazione Ready.

Nel secondo caso il timelock segna done prima della call, ma propaga il fallimento. Il revert annulla done, quindi resta pronta. Non significa che venga riprovata automaticamente o che convenga riprovarla senza leggere l’errore. Significa che il tentativo fallito non la consuma come se fosse riuscito.

Domanda: Il timelock rende ritardata qualsiasi decisione amministrativa?

Non automaticamente. In ToyTimelock l’admin può modificare immediatamente l’assegnazione dei ruoli. Il minimumDelay è immutabile e assegnare proposer o executor non elimina il ritardo di una nuova operazione; resta però un potere immediato sui soggetti che possono programmare, cancellare o eseguire. La mappa della governance deve includere anche l’admin del timelock.

7. Emergenza: fermare e riaprire non sono lo stesso potere

Se rileviamo un attacco, aspettare due giorni per fermare nuove azioni può essere inaccettabile. Diamo al pauser un potere rapido e ristretto: fermare. Riaprire e cambiare configurazione restano all’owner.

In questo laboratorio la pausa blocca sensitiveAction ma lascia disponibile exit. È una scelta esplicita della specifica. Non assumiamo che ogni protocollo possa sempre preservare ogni uscita durante un incidente.

bash demo.sh pausa

Risultato atteso: due test PASS: il pauser ferma ma non configura o riavvia; la pausa blocca l’azione protetta e conserva il percorso di uscita.

Qui sensitiveAction ed exit incrementano contatori: non movimentano realmente fondi. La demo prova quali percorsi rimangono accessibili. Per dimostrare il recupero dei fondi servirebbe verificare anche contabilità, liquidità e trasferimenti effettivi.

Domanda: Un ruolo che può solo mettere in pausa è innocuo?

No. Può compromettere la disponibilità. Abbiamo limitato il tipo di danno che può fare, non cancellato ogni rischio.

8. Colleghiamo davvero i componenti

Alice + Bob
    ↓ due approvazioni
ToyMultisig
    ↓ schedule di una specifica operazione
ToyTimelock
    ↓ attesa di 48 ore, poi execute
GovernedEscrow.setFee(...)
    owner effettivo = ToyTimelock

Le approvazioni autorizzano il multisig a programmare. La programmazione fa partire l’attesa. Dopo l’attesa un executor invia la transazione di esecuzione. Nell’ultima chiamata l’Escrow vede il timelock come msg.sender.

Se l’Escrow avesse ancora il multisig come owner, il multisig potrebbe chiamare direttamente setFee, saltando il timelock. Avere un timelock distribuito da qualche parte non significa che il potere debba passarci.

bash demo.sh flusso

Risultato atteso: due test PASS: due approvatori programmano e il timelock esegue dopo il ritardo; il proposer non può aggirare l’ownership del timelock.

Questa è la prova di sistema: seguiamo tutti i passaggi fino al contratto che applica la modifica. I test dei singoli componenti non sostituiscono la verifica del collegamento.

9. Esercizio con risposta

Il team dice: “Abbiamo un multisig e un timelock, quindi tutti gli upgrade aspettano 48 ore”. Quali dati chiediamo?

Prova a rispondere prima di leggere la soluzione:

Chiediamo chi possiede effettivamente il potere di upgrade; chi può programmare e cancellare; chi amministra quei ruoli; quale ritardo è configurato; se esistono funzioni alternative che cambiano l’implementation. Infine seguiamo una proposta dalla sua approvazione fino alla scrittura del nuovo indirizzo.

Ora compromettiamo soltanto il pauser. Può cambiare la fee?

Risposta: Non attraverso i permessi mostrati. Può fermare il percorso protetto; il ripristino appartiene all’owner. Questo separa contenimento dell’emergenza e decisione di ripartenza.

Ora approvano Alice e Bob, ma nessuno esegue dopo due giorni. La fee cambia?

Risposta: No. Pronta non significa eseguita: serve la transazione finale.

Una governance si legge come una catena di poteri. Per ogni modifica seguiamo chi la decide, chi la programma, chi può fermarla e quale indirizzo arriva al controllo finale. Nella prossima lezione tradurremo requisiti come questi in test capaci di distinguere un comportamento corretto da uno soltanto plausibile.

Esercizio autonomo: disegna una governance con upgrade ritardato e pausa immediata. Indica anche chi amministra i ruoli e chi compare come msg.sender nella chiamata finale.

Materiali e approfondimenti

La spiegazione segue gli esempi guidati. Per consultare il codice completo, i test e i dettagli tecnici usa questi materiali:

I laboratori sono progetti autonomi: prima di riutilizzare una regola, rileggi la specifica della lezione. Materiali aggiornati al 16 ottobre 2026.

Tengo corsi di programmazione, analisi dati e intelligenza artificiale per aziende ed enti di formazione, in aula e da remoto. Scopri come insegno e quali materiali uso a lezione.