# Come scrivere, testare e distribuire il tuo primo smart contract su una testnet Ethereum

Published 2026-10-23 · Crypto.world Team · Crypto.world

> Una guida passo passo a Foundry: installare gli strumenti, scrivere e testare un piccolo smart contract in Solidity, conservare la chiave usata per la distribuzione in un keystore cifrato, ottenere ether di prova su Sepolia, distribuire lo smart contract, verificarne il codice sorgente e capire cosa cambia prima del passaggio alla mainnet.

## Cosa realizzerai e quali strumenti userai

I passaggi che seguono accompagnano chi sa programmare, ma non ha mai distribuito uno smart contract, da una cartella vuota a uno smart contract in esecuzione su una testnet Ethereum pubblica, con il codice sorgente verificato su un block explorer. Lo smart contract è volutamente semplice: una bacheca il cui testo può essere modificato soltanto da chi l’ha distribuita. Ogni comando è stato controllato il 23 ottobre 2026 sulla documentazione ufficiale di Foundry, Solidity ed ethereum.org e provato dall’inizio alla fine su un nodo locale.

:::callout-info **In un minuto:** Installa Foundry con foundryup, scrivi lo smart contract in src/ e i relativi test in test/, poi esegui forge test. Distribuiscilo su Sepolia, che ethereum.org definisce la testnet predefinita per lo sviluppo di applicazioni. Conserva la chiave usata per la distribuzione nel keystore cifrato di Foundry, mai nel repository o in un file .env. Verifica il codice sorgente con forge, poi controlla che sull’explorer risulti verificato. :::

Due insiemi di strumenti dominano lo sviluppo di smart contract su Ethereum. Foundry è un insieme di strumenti a riga di comando scritti in Rust: la sua documentazione descrive `forge` (per compilare, testare, distribuire e verificare), `cast` (per interagire con una blockchain), `anvil` (un nodo locale) e `chisel` (un ambiente REPL per Solidity). I test si scrivono in Solidity. Hardhat è un ambiente Node.js; la sua serie 3.x, arrivata alla versione 3.21.0 su npm al 22 ottobre 2026, richiede Node.js v22.13.0 o successivo, si inizializza con `npx hardhat --init` ed esegue test sia in Solidity sia in TypeScript.

Questa guida usa Foundry perché, così, chi è agli inizi deve imparare un solo linguaggio invece di due. Chi usa Hardhat può seguire la stessa sequenza: le sue Configuration Variables e il plugin hardhat-keystore svolgono il ruolo che, nei passaggi seguenti, spetta al keystore di Foundry.

## Installare Foundry e fissare la versione del compilatore

La pagina di installazione di Foundry indica un solo programma di installazione ufficiale: foundryup. Su Windows richiede Git Bash o WSL; PowerShell e Prompt dei comandi non sono supportati.

1. **Installa foundryup.** Il comando seguente scarica ed esegue lo script di installazione. Se preferisci leggere uno script prima di eseguirlo, salvalo con `curl -L https://foundry.paradigm.xyz -o install.sh`, aprilo e poi eseguilo con `bash install.sh`.

```
curl -L https://foundry.paradigm.xyz | bash
```

1. **Ricarica la shell.** Apri un nuovo terminale oppure esegui `source ~/.bashrc` (o `source ~/.zshrc`).
2. **Installa gli strumenti.** `foundryup` installa le ultime versioni stabili di forge, cast, anvil e chisel; secondo la documentazione, controlla l’hash SHA-256 di ogni download confrontandolo con l’attestazione della release su GitHub.

```
foundryup
forge --version
```

Al 23 ottobre 2026, l’attuale versione stabile è la v1.8.6, datata 21 ottobre 2026 nel registro delle modifiche di Foundry. In futuro la tua versione sarà più recente; esegui di nuovo `foundryup` per aggiornarla.

1. **Crea il progetto.** `forge init` crea un repository git con le cartelle `src/`, `test/` e `script/`, installa la libreria forge-std e aggiunge file Counter di esempio che puoi eliminare.

```
forge init noticeboard
cd noticeboard
rm src/Counter.sol test/Counter.t.sol script/Counter.s.sol
```

1. **Fissa la versione del compilatore.** Foundry rileva automaticamente una versione di Solidity dai file, a meno che tu non ne fissi una. Al 23 ottobre 2026, Solidity 0.8.38 è la versione più recente: il team di Solidity l’ha annunciata il 22 ottobre 2026 e docs.soliditylang.org offre un’edizione v0.8.38. Prima di iniziare, controlla l’elenco delle release su soliditylang.org/blog e scegli la versione indicata. Aggiungi una riga a `foundry.toml`:

```
[profile.default]
src = "src"
out = "out"
libs = ["lib"]
solc_version = "0.8.38"
```

La documentazione di Solidity spiega che una direttiva pragma come `^0.5.2` accetta qualsiasi compilatore successivo fino alla prossima release che introduce modifiche incompatibili, quindi «restano possibili release che correggono bug». Per uno smart contract che distribuirai e verificherai, una direttiva pragma con versione esatta, insieme a `solc_version`, fa sì che il bytecode testato, distribuito e verificato provenga da un solo compilatore.

## Scrivere lo smart contract

Crea `src/Noticeboard.sol`:

```
// SPDX-License-Identifier: MIT
pragma solidity 0.8.38;

/// @notice A one-line public notice that only the deployer can change.
contract Noticeboard {
address public immutable owner;
string public notice;

event NoticeChanged(address indexed by, string newNotice);

error NotOwner();

constructor() {
owner = msg.sender;
}

function setNotice(string calldata newNotice) external {
if (msg.sender != owner) revert NotOwner();
notice = newNotice;
emit NoticeChanged(msg.sender, newNotice);
}
}
```

Il costruttore viene eseguito una sola volta, al momento della distribuzione, e registra come `owner` chiunque abbia inviato la transazione di distribuzione; `immutable` significa che quel valore viene fissato nel codice distribuito e non può più cambiare. Dichiarando `owner` e `notice` come `public`, il compilatore genera funzioni di lettura, così chiunque può consultarli. `setNotice` è l’unica funzione che modifica i dati e, se viene chiamata da qualcun altro, annulla l’operazione restituendo l’errore personalizzato `NotOwner`.

Questo controllo è la forma più semplice di ciò che la guida alla sicurezza di ethereum.org chiama controllo degli accessi, il primo punto del suo elenco di linee guida. L’evento fornisce a explorer e app una voce di registro da mostrare ogni volta che l’avviso cambia. Compila lo smart contract una prima volta per confermare che il compilatore venga scaricato e che la compilazione riesca:

```
forge build
```

## Testare il contratto in locale

La documentazione di Foundry sui test stabilisce le convenzioni: i file di test terminano in `.t.sol`, i contratti di test ereditano da `Test` di forge-std, i nomi delle funzioni di test iniziano con `test` e `setUp()` viene eseguita prima di ogni test. Crea `test/Noticeboard.t.sol`:

```
// SPDX-License-Identifier: MIT
pragma solidity 0.8.38;

import {Test} from "forge-std/Test.sol";
import {Noticeboard} from "../src/Noticeboard.sol";

contract NoticeboardTest is Test {
Noticeboard board;
address stranger = makeAddr("stranger");

function setUp() public {
board = new Noticeboard();
}

function test_DeployerIsOwner() public view {
assertEq(board.owner(), address(this));
}

function test_OwnerCanSetNotice() public {
board.setNotice("hello, testnet");
assertEq(board.notice(), "hello, testnet");
}

function test_RevertWhen_CallerIsNotOwner() public {
vm.prank(stranger);
vm.expectRevert(Noticeboard.NotOwner.selector);
board.setNotice("not yours");
}

function test_EmitsNoticeChanged() public {
vm.expectEmit(address(board));
emit Noticeboard.NoticeChanged(address(this), "hello");
board.setNotice("hello");
}

function testFuzz_OwnerCanSetAnyNotice(string calldata text) public {
board.setNotice(text);
assertEq(board.notice(), text);
}
}
```

`vm.prank` fa sì che la chiamata successiva provenga da un altro indirizzo: è così che il test verifica che un estraneo venga respinto. `vm.expectRevert` passa solo se la chiamata successiva fallisce con l’errore indicato. Una funzione di test che accetta parametri viene sottoposta a fuzz testing: Forge le fornisce input casuali, con 256 esecuzioni per impostazione predefinita. Esegui la suite:

```
forge test
```

Con Foundry 1.8.6 e solc 0.8.38, tutti e cinque i test passano. Se uno fallisce, `forge test -vvv` stampa una traccia della chiamata che ha causato il fallimento. La pagina di Foundry sulle buone pratiche suggerisce anche di eseguire `forge lint` e `forge fmt --check` prima di distribuire qualsiasi cosa.

## Creare una chiave per il deploy che non finisca mai nel repository

Un deploy è una transazione, quindi richiede un account con fondi e una chiave privata con cui firmarla. Creane una nuova da usare soltanto sulle testnet. La pagina di ethereum.org sulle reti avverte che «per ragioni di sicurezza, non è consigliabile riutilizzare gli account della mainnet sulle testnet o viceversa».

La pagina di Foundry sulle buone pratiche indica dove conservare la chiave: «Conservate le chiavi in forma cifrata, non come variabili d’ambiente in chiaro». Il suo keystore salva la chiave cifrata in `~/.foundry/keystores`, fuori dal progetto.

1. **Genera la chiave direttamente nel keystore.** Ti verrà chiesta una password e la chiave non verrà mai stampata. Il comando stampa il nuovo indirizzo.

```
cast wallet new deployer
cast wallet list
```

Se hai già una chiave destinata soltanto alle testnet, `cast wallet import deployer --interactive` te la chiede invece di riceverla dalla riga di comando, dove finirebbe nella cronologia della shell.

1. **Recupera l’indirizzo quando ti serve.** Il comando chiede la password del keystore.

```
cast wallet address --account deployer
```

1. **Metti in `.env` solo le impostazioni che non sono chiavi.** Ti servono due valori: un endpoint RPC per Sepolia (ottenuto tramite un account presso un fornitore di nodi, oppure un endpoint pubblico; nella guida al deploy di Foundry l’esempio usa `https://sepolia.drpc.org`) e una chiave API di Etherscan. Secondo la documentazione di Etherscan, una chiave gratuita, creata su etherscan.io/myapikey dopo la registrazione, funziona su tutte le chain supportate.

```
# .env (never commit this file)
SEPOLIA_RPC_URL=https://sepolia.drpc.org
ETHERSCAN_API_KEY=your_key_here
```

1. **Verifica che git lo ignori.** Il file `.gitignore` creato da `forge init` elenca già `.env`, `cache/` e `out/`; il comando qui sotto dovrebbe stampare la regola corrispondente. Includi nel commit un file `.env.example` con valori vuoti, così gli altri sapranno quali variabili impostare.

```
git check-ignore -v .env
```

Non copiare in nessuno di questi file la chiave privata stampata da `anvil`. La documentazione di Foundry avverte: «Non usate mai le chiavi predefinite di Anvil sulle reti pubbliche. Sono note a tutti».

## Scegliere Sepolia e ottenere ether di test senza cedere dati

ethereum.org indica due testnet pubbliche attualmente mantenute dagli sviluppatori dei client, Sepolia e Hoodi, e assegna loro scopi diversi. Sepolia è «la testnet predefinita consigliata per lo sviluppo di applicazioni»; Hoodi serve a testare la validazione, lo staking e gli aggiornamenti del protocollo. Holesky, una testnet più vecchia, è indicata come deprecata da settembre 2025. Chi sviluppa contratti dovrebbe quindi effettuare il deploy su Sepolia, con chain ID 11155111.

Gli ether di test non hanno valore, ma te ne servono comunque per pagare il gas. La sezione di ethereum.org dedicata a Sepolia elenca diversi faucet, ciascuno con condizioni diverse. Prima di usarne uno, controlla che cosa richiede:

1. **Fornisci un indirizzo, nient’altro.** A un faucet serve solo il tuo indirizzo pubblico. Se una pagina chiede una chiave privata, una frase seed o una firma del wallet che autorizzi a spendere, non è un faucet da usare.
2. **Fai attenzione alle verifiche del saldo sulla mainnet.** La pagina del faucet Sepolia di Alchemy, verificata il 23 ottobre 2026, richiede almeno 0,001 ETH e un po’ di attività su Ethereum Mainnet all’indirizzo destinatario. Soddisfare questi requisiti collegherebbe il tuo indirizzo sulla testnet a uno sulla mainnet, contrariamente al consiglio di non riutilizzarli riportato sopra.
3. **Preferisci i faucet che chiedono solo un’attività da svolgere o di attendere.** Il faucet PoW su sepolia-faucet.pk910.de, indicato da ethereum.org, ti chiede di inserire un indirizzo e di lasciare che il browser esegua un po’ di mining in cambio di ether di test.
4. **Verifica che siano arrivati.**

```
set -a; source .env; set +a
cast balance $(cast wallet address --account deployer) --ether --rpc-url "$SEPOLIA_RPC_URL"
```

`set -a` esporta tutte le variabili definite nel file, così forge e cast possono leggere `ETHERSCAN_API_KEY` dall’ambiente, come indicano le rispettive documentazioni.

## Simulare, distribuire su Sepolia e chiamare il contratto

Crea lo script di distribuzione `script/Deploy.s.sol`. Gli script terminano in `.s.sol` ed ereditano da `Script` di forge-std; le chiamate al livello di profondità corrente tra `vm.startBroadcast()` e `vm.stopBroadcast()`, escluse le chiamate ai cheatcode, creano transazioni che possono poi essere firmate e inviate onchain.

```
// SPDX-License-Identifier: MIT
pragma solidity 0.8.38;

import {Script, console} from "forge-std/Script.sol";
import {Noticeboard} from "../src/Noticeboard.sol";

contract DeployScript is Script {
function run() public {
vm.startBroadcast();
Noticeboard board = new Noticeboard();
vm.stopBroadcast();
console.log("Noticeboard deployed at:", address(board));
console.log("Chain ID:", block.chainid);
}
}
```

1. **Simula su Sepolia.** Senza `--broadcast`, forge esegue lo script sullo stato attuale della blockchain senza inviare nulla. Mostra l’indirizzo previsto e la stima del gas, poi termina con «SIMULAZIONE COMPLETATA. Per trasmettere queste transazioni, aggiungi --broadcast e le configurazioni dei wallet al comando precedente».

```
forge script script/Deploy.s.sol --account deployer --rpc-url "$SEPOLIA_RPC_URL"
```

1. **Distribuisci e verifica in un’unica esecuzione.** L’aggiunta di `--broadcast` invia la transazione, firmata con il keystore dopo che ne hai digitato la password; `--verify` invia il codice sorgente a Etherscan una volta confermata la distribuzione.

```
forge script script/Deploy.s.sol --account deployer --rpc-url "$SEPOLIA_RPC_URL" --broadcast --verify
```

1. **Trova il registro.** L’indirizzo è nel log e le transazioni sono salvate in `broadcast/Deploy.s.sol/11155111/run-latest.json`. Il `.gitignore` del template esclude da git i log locali (chain 31337) e quelli delle esecuzioni di prova, ma non quelli della testnet: quel file sarà quindi incluso in un commit. Contiene solo dati pubblici. L’URL RPC viene salvato in un file separato per i «valori sensibili» sotto `cache/`, che git ignora.
2. **Chiama il contratto.** Sostituisci l’indirizzo con il tuo.

```
cast call 0xYourContract "owner()(address)" --rpc-url "$SEPOLIA_RPC_URL"
cast send 0xYourContract "setNotice(string)" "hello, testnet" --account deployer --rpc-url "$SEPOLIA_RPC_URL"
cast call 0xYourContract "notice()(string)" --rpc-url "$SEPOLIA_RPC_URL"
```

La prima chiamata dovrebbe restituire l’indirizzo del tuo deployer. Se vuoi fare una prova senza usare alcun faucet, avvia `anvil` in un secondo terminale, invia al deployer un po’ degli ether di test locali di Anvil e indirizza gli stessi comandi a `http://127.0.0.1:8545`.

## Verificare il codice sorgente su un block explorer

ethereum.org definisce la verifica del codice sorgente come il confronto tra il codice sorgente di un contratto e «il bytecode compilato usato durante la creazione del contratto». Finché non viene effettuata, un explorer mostra solo il bytecode, più difficile da comprendere del codice sorgente.

Se `--verify` non è riuscito o l’hai saltato, verifica separatamente l’indirizzo del contratto distribuito. Il primo comando usa Etherscan e richiede `ETHERSCAN_API_KEY` nell’ambiente; `--watch` attende il risultato. Il secondo usa Sourcify, che non richiede alcuna chiave.

```
forge verify-contract 0xYourContract src/Noticeboard.sol:Noticeboard --chain sepolia --watch
forge verify-contract 0xYourContract src/Noticeboard.sol:Noticeboard --chain sepolia --verifier sourcify
```

Poi apri sepolia.etherscan.io da un segnalibro o digitandone l’indirizzo, cerca l’indirizzo del contratto e controlla che la scheda Contract mostri il tuo codice sorgente. I due servizi non verificano la stessa cosa. ethereum.org spiega che Etherscan non confronta l’hash dei metadati alla fine del bytecode, quindi le corrispondenze che rileva sono «corrispondenze parziali», mentre una «corrispondenza completa» conferma anche che i metadati di compilazione corrispondono.

Il problema più comune è una mancata corrispondenza: secondo la documentazione di Etherscan, sia «il codice sorgente sia le impostazioni del compilatore» devono «corrispondere esattamente alle condizioni della distribuzione». Aver fissato in precedenza la versione del compilatore evita la maggior parte di questi problemi. Un contratto con argomenti del costruttore richiede anche che siano codificati secondo l’ABI con `--constructor-args`; Noticeboard non ne richiede perché non accetta argomenti.

## Cosa cambia prima del mainnet

Su una testnet, un bug costa un nuovo deployment e un po’ di ether di test gratuito. Sul mainnet, il codice distribuito continua a funzionare così com’è scritto, e la guida alla sicurezza di ethereum.org ne indica la conseguenza:

> Di solito il codice di un contratto già distribuito non può essere modificato per correggere falle di sicurezza, mentre gli asset rubati dagli smart contract sono estremamente difficili da tracciare e, a causa dell’immutabilità, perlopiù irrecuperabili. — ethereum.org, Sicurezza degli smart contract

Esistono meccanismi di aggiornamento come i proxy, ma ethereum.org osserva che implementarli può richiedere tempo e spesso l’approvazione di diverse parti, il che «non fa che dare agli aggressori più tempo per causare ulteriori danni». Prima di distribuire sul mainnet un contratto che custodirà valore, segui le verifiche descritte nelle guide ufficiali:

1. **Revisione indipendente.** ethereum.org suggerisce di commissionare un audit e, separatamente, una bug bounty, avvertendo però di non considerare gli audit «una soluzione miracolosa»: non individueranno ogni bug.
2. **La checklist di sviluppo.** Secondo la stessa guida: codice sotto controllo di versione, ogni modifica sottoposta tramite una pull request con almeno un revisore indipendente, strumenti di analisi statica eseguiti prima dell’unione delle modifiche e una build senza errori né avvisi del compilatore.
3. **Test oltre agli unit test.** ethereum.org raccomanda di affiancare agli unit test test basati sulle proprietà, come il fuzzing; le buone pratiche di Foundry aggiungono di eseguire `forge test -vvvv` almeno una volta e di verificare il controllo degli accessi e i casi limite.
4. **Bug del compilatore.** La documentazione di Solidity avverte che anche un codice privo di bug può risentire di un bug del compilatore e mantiene un elenco dei bug noti. Controlla quell’elenco e gli avvisi di sicurezza sul blog di Solidity per la versione che hai fissato.
5. **Limitare il valore a rischio.** La documentazione di Solidity raccomanda di limitare la quantità di ether custodita da un contratto, così da ridurre le perdite causate da un bug nel codice, nel compilatore o nella piattaforma.
6. **Chiavi.** La documentazione di Foundry associa allo sviluppo locale le chiavi di Anvil, alle testnet un keystore cifrato e al mainnet un hardware wallet, da usare con `--ledger` al posto di `--account`.
7. **Impostazioni esatte.** Come indica la checklist di Foundry precedente alla distribuzione, verifica i deployment sul mainnet usando la stessa versione del compilatore e le stesse impostazioni con cui hai eseguito i test.

Qualunque sia la rete, concludi ogni deployment con la stessa verifica: esegui `cast code 0xYourContract --rpc-url "$SEPOLIA_RPC_URL"` e accertati che restituisca bytecode anziché `0x`; poi apri l’indirizzo sull’explorer e verifica che la scheda Contract mostri il tuo codice sorgente verificato.

## Fonti

1. [Foundry docs: Installation](https://www.getfoundry.sh/introduction/installation) getfoundry.sh
2. [Foundry docs: Testing](https://www.getfoundry.sh/forge/testing) getfoundry.sh
3. [Foundry docs: Deploying Contracts](https://www.getfoundry.sh/guides/deploying-contracts) getfoundry.sh
4. [Foundry docs: Best Practices](https://www.getfoundry.sh/best-practices) getfoundry.sh
5. [Foundry reference: forge verify-contract](https://www.getfoundry.sh/reference/forge/verify-contract) getfoundry.sh
6. [Foundry reference: cast wallet new](https://www.getfoundry.sh/reference/cast/wallet/new) getfoundry.sh
7. [Foundry changelog (v1.8.6, 21 October 2026)](https://www.getfoundry.sh/changelog) getfoundry.sh
8. [Solidity blog: Solidity 0.8.38 Release Announcement](https://www.soliditylang.org/blog/2026/10/22/solidity-0.8.38-release-announcement/) soliditylang.org
9. [Solidity docs v0.8.38: Layout of a Solidity Source File (version pragma)](https://docs.soliditylang.org/en/v0.8.38/layout-of-source-files.html) docs.soliditylang.org
10. [Solidity docs v0.8.38: Security Considerations](https://docs.soliditylang.org/en/v0.8.38/security-considerations.html) docs.soliditylang.org
11. [ethereum.org: Networks (testnets, faucets)](https://ethereum.org/developers/docs/networks/) ethereum.org
12. [ethereum.org: Smart contract security](https://ethereum.org/developers/docs/smart-contracts/security/) ethereum.org
13. [ethereum.org: Verifying smart contracts](https://ethereum.org/developers/docs/smart-contracts/verifying/) ethereum.org
14. [Etherscan docs: Set Up Your API Key](https://docs.etherscan.io/set-up-your-api-key) docs.etherscan.io
15. [Etherscan docs: Common Verification Errors](https://docs.etherscan.io/contract-verification/common-verification-errors) docs.etherscan.io
16. [Sourcify docs: Verify via Foundry](https://docs.sourcify.dev/docs/verify-via-foundry) docs.sourcify.dev
17. [Hardhat docs: Getting started (Hardhat 3)](https://hardhat.org/docs/getting-started) hardhat.org
18. [Alchemy Sepolia faucet page (eligibility requirements)](https://www.alchemy.com/faucets/ethereum-sepolia) alchemy.com
19. [Sepolia PoW Faucet (linked from ethereum.org)](https://sepolia-faucet.pk910.de/) sepolia-faucet.pk910.de
20. [Sepolia Resources (chain ID 11155111)](https://sepolia.dev/) sepolia.dev

## Esplora

[Altri articoli](https://crypto.world/it/implementation)

---

Canonical: https://crypto.world/it/implementation/how-to-write-test-deploy-first-smart-contract-ethereum-testnet
