# Guida upgrade su reti reali (fondi dei clienti) > Documento operativo Griffin / Lendzy. > Usa questa guida quando il protocollo ha (o avrà) liquidità e token di valore reale. > Aggiornato 2026-08-31. Solo testo narrativo, senza tabelle. **Copie:** repo frontend in `docs/GUIDA-UPGRADE-RETI-REALI.md`; admin panel in `GUIDA-UPGRADE-RETI-REALI.md`; in Guida admin cerca «reti reali». --- ## Mentalità: soldi dei clienti Ogni modifica può bloccare rimborsi o prelievi, far liquidare in modo sbagliato, far vedere indirizzi o ABI vecchi sul sito, oppure lasciare posizioni liquidabili senza bot automatico. Prima di toccare qualsiasi cosa identifica il tipo di modifica (sezioni seguenti). Non improvvisare su mainnet: ripeti su Sepolia lo stesso ordine di passi. Fai una cosa alla volta: non mescolare diamondCut, cambio fee e redeploy UI nello stesso minuto. Nella maggior parte dei casi le liquidazioni devono restare possibili: lascia il keeper acceso e spegnilo solo se l’upgrade tocca la liquidazione. Comunica con Avviso frontend (data e ora) prima di interventi visibili. Dopo verifica in sola lettura, poi riapri; non «sperare che funzioni». Tieni un piano di rollback (manifest precedente, cartella `out/` precedente, facet previous). Usa il wallet owner solo da macchina fidata; niente seed in chiaro; in futuro preferisci un multisig. --- ## Classifica la modifica (obbligatorio) **Tipo A — solo interfaccia.** Testi, CSS, FAQ. Rischio fondi basso. Lascia il keeper acceso. Niente pause. Usa Soft. **Tipo B — frontend con indirizzi o ABI.** Nuovo manifest o variabili `NEXT_PUBLIC_*`. Rischio alto se sbagli. Keeper acceso, niente pause, Soft più verify. Un ABI sbagliato può far firmare calldata errati. **Tipo C — parametri on-chain.** CDY, fee, whitelist, oracle, margin call. Rischio medio-alto. Keeper acceso (serve se i prezzi si muovono). Soft e avviso se il cambio è percepibile. Un parametro per volta. **Tipo D — diamondCut su facet «normale».** Offers senza liquidate, getter admin, fee facet. Rischio alto. Preferisci keeper acceso. Valuta la pause. Hard con keeper ON. **Tipo E — diamondCut su posizioni, liquidate o storage.** PositionsFacet, funzioni liquidate, layout storage. Rischio critico. Spegnere il keeper per pochi minuti. Valuta pause. Hard con spegnimento keeper. Se non sei sicuro tra D ed E, tratta come E. **Tipo F — nuovo liquidator, OracleSwap o fondi flash.** Deploy liquidator o cambio indirizzi keeper. Critico. Keeper spento finché verify non passa. Hard con spegnimento. Non attivare `LIQUIDATION_WRITE` troppo presto. **Tipo G — pool factory o nuova implementation.** Critico per le pool nuove. Attenzione al keeper Pool. Hard. Le pool vecchie non migrano da sole: documenta factory nuova e deprecated. **Tipo H — indexer, API, RPC, history.** Rischio soprattutto UX. Keeper acceso. Soft. Non fare un diamondCut «per sistemare» un CORS. **Tipo I — keeper, cron Netlify, secrets.** Critico se attivi write troppo presto. Rollout graduale. Soft più checklist. Dual gate: switch Admin e `LIQUIDATION_WRITE` devono essere entrambi veri. **Tipo J — emergenza.** Exploit sospetto, oracle rotto. Rischio massimo. Keeper e pause caso per caso. Soft o Hard più banner critico. Niente upgrade frettolosi senza almeno un review del diff. --- ## Cosa tenere d’occhio sempre Sul contratto, conferma se stai toccando LTV+, Leverage+ o Pool: non confonderli nel panel. Il diamondCut è una sola transazione atomica: dopo il cut la logica nuova è subito attiva. Non riordinare i campi di storage esistenti; solo append o gap. Su Leverage la pause blocca anche liquidate; su LTV liquidatePosition può restare disponibile. Il keeper spento spegne solo il bot automatico. Le liquidazioni manuali restano permissionless, salvo pause su Leverage. In produzione tieni il keeper preferibilmente sempre acceso. Spegnilo solo per tipo E o F, e per pochi minuti. Sul frontend, `NEXT_PUBLIC_*` è bake-time: dopo un cambio di env o indirizzi serve build e redeploy. Il manifest in `public/deploy/manifest.json` deve coincidere con la chain. L’avviso utenti sta in Admin → Aggiornamenti → Avviso frontend. In operatività, Hard salva snapshot keeper sotto `server/data/release-snapshots/`. Salva anche in locale manifest, ABI, `out/` precedente e hash della tx di cut. Usa `npm run release-safety` e, dopo, la fase post-upgrade con verify. --- ## Checklist prima di intervenire Classifica il tipo A–J. Scrivi in una riga cosa cambia e perché. Prepara il rollback. Controlla wallet owner e chainId. Non cambiare RPC a metà intervento. Se usi l’API, verifica health dell’indexer. Prepara testo e data/ora dell’avviso se l’utente può notare l’intervento. Nessun altro admin in scrittura on-chain in parallelo. Stesso ordine di passi già provato su Sepolia. --- ## Procedure passo dopo passo **Tipo A (solo UI).** Soft opzionale e avviso solo se downtime percepito. Build, deploy Netlify, smoke su Market, Pools, Portfolio e connect wallet. Chiudi soft e spegni avviso. Non toccare `.env` per caso. **Tipo B (indirizzi o ABI).** Soft e avviso di aggiornamento interfaccia. Aggiorna manifest e env. Rigenera ABI se serve. `release-safety` in pre-deploy. Build e deploy. Controlla che gli address in UI coincidano con l’explorer. Leggi un’offerta o una posizione senza importi grandi. Chiudi soft. **Tipo C (parametri).** Soft e avviso se tassi o asset nuovi. SIWE e OWNER sul Diamond giusto. Un parametro per volta; dopo ogni tx aggiorna la Dashboard e confronta. Se tocchi oracle, monitora le liquidabili un quarto d’ora o mezz’ora. Non spegnere il keeper. Chiudi soft. **Tipo D (cut normale).** Annuncia data e ora. Hard con keeper acceso. `release-safety`. Forge diamondCut su un Diamond alla volta. Annota hash e nuovo address facet. Aggiorna documentazione deploy e manifest. Sync ABI admin se serve. Post-upgrade con verify. Smoke di letture on-chain. Rebuild UI se necessario. Chiudi Hard. Attenzione ai selector: un Replace sbagliato toglie funzioni. **Tipo E (cut liquidazioni o storage).** Avviso: eventuali liquidazioni solo manuali se spegni il bot. Hard e spegni keeper. Eventuale pause su Leverage. Pre-upgrade safety. Un solo cut. Verify immediato in sola lettura. Riattiva keeper uno alla volta (LTV, Leverage, Pool). Unpause se serve. Chiudi Hard (non riaccende i keeper). Monitora da una a ventiquattro ore. Poi rebuild UI se ABI cambiati. Finestra keeper spento in minuti, non in ore. **Tipo F (liquidator o flash).** Hard e spegni keeper. Deploy. Aggiorna indirizzi in Admin senza attivare. Env Netlify con write falso. Fondi flash come da guide liquidazione. Verify read-only. Accendi prima solo LTV, poi gli altri. `LIQUIDATION_WRITE=true` solo con switch ON e verify ok. Chiudi Hard. **Tipo G (pool factory).** Soft o Hard a seconda del TVL attivo. Documenta factory nuova contro deprecated. Rebuild UI. Verify discovery Pool prima di `poolEnabled`. **Tipo H (API o RPC).** Soft e avviso se market o portfolio non caricano. Health da Admin → RPC e API. Keeper acceso. Niente cut «per CORS». **Tipo I (cron e secrets).** Non attivare write su rete reale senza fondi flash, verify e switch espliciti. Ordine: deploy contratti, config Admin spenta, env Netlify, verify, switch uno alla volta, poi write true. **Tipo J (emergenza).** Banner critico subito. Valuta keeper e pause (pause Leverage ferma anche quelle liquidazioni). Niente fix frettolosi senza review. Di’ agli utenti cosa non fare. Dopo il fix, disciplina da tipo E e monitoring lungo. --- ## Giornata tipo per upgrade contratti (D o E) Il giorno prima annuncia la finestra oraria nell’Avviso frontend. Un’ora prima apri Soft o Hard e ricontrolla owner e rete. Al momento zero: release-safety; se E o F spegni i keeper; diamondCut; verify; aggiorna manifest, ABI e docs; se E o F riaccendi i keeper a partire da LTV; unpause se usata. A quindici minuti: smoke UI e letture posizioni. A due ore: liquidabili e log cron. A ventiquattro ore: togli avviso se stabile e chiudi Hard. --- ## Cosa non fare con fondi clienti Non spegnere i keeper per abitudine. Non lasciarli spenti per ore o giorni. Non mettere in pause Leverage se ti servono liquidazioni vive lì. Non ridispiegare l’UI senza rebuild dopo un cambio env. Non attivare `LIQUIDATION_WRITE` prima del verify. Non cambiare oracle e facet di liquidazione nello stesso intervento. Non usare l’owner da browser o estensioni dubbie. Non forzare la chiusura Hard ignorando fail critici senza annotare il perché. Non aggiornare LTV e Leverage in parallelo senza necessità. Non inventare a memoria un layout storage «compatibile»: confronta con il codice deployato. --- ## Rollback Frontend: ridispiega `out/` precedente. Parametro on-chain: reimposta il valore vecchio. Facet sbagliata: Replace verso la facet Previous in `DIAMOND-CONTRATTI-DEPLOY.md`. Indirizzi keeper: snapshot Admin o checkbox Parametri. Liquidator nuovo: switch off e ripristina l’address precedente in Admin e Netlify. --- ## Strumenti Soft, Hard e Avviso frontend stanno in Admin → Aggiornamenti / Release. Pause e unpause in Emergency. Keeper in Parametri. La CLI `release-safety` è nel repo lendzy3.0. Le guide liquidazione sono `docs/GUIDA-LIQUIDAZIONE-*.md`. Il registry contratti è `DIAMOND-CONTRATTI-DEPLOY.md`. La sintesi Soft/Hard è `GUIDA-AGGIORNAMENTI-PRODUZIONE.md`. --- ## Dopo ogni upgrade Controlla che non ci siano spike di revert sulle tx utente. Le posizioni liquidabili devono avere un conteggio sensato e, se il keeper è acceso, devono essere prese. CDY e oracle non devono sparire a zero. Portfolio e API senza errori di massa. In audit devono comparire cut, pause, keeper e banner. --- ## Sintesi Classifica, comunica, spegni solo ciò che serve, modifica una cosa, verifica, riapri gradualmente, monitora. Con i soldi dei clienti la fretta costa più del tempo della checklist.