Il software
Questo sito gira su bitmentor, con licenza GNU AGPLv3 (altre licenze, come MIT, su richiesta agli autori): github.com/mammadori/bitmentor. Se la tua città vuole fare la stessa cosa, il codice è lì: è il nostro lascito. Nome, colori, storia e pagine stanno in una cartella, e si cambiano senza toccare il codice.
Prova adesso con la tua città: scrivi il nome, guarda il sito cambiare, scarica la tua cartella pronta.
Scelte di progetto
Il server non vede le parole di recupero e non può spendere. Non esistono chiavi che spendono, da nessuna parte del sistema.
Il server non vede nemmeno le vendite. La cassa sta nel telefono o nel computer del negozio: chiede la fattura direttamente all'indirizzo Lightning del negoziante, controlla il pagamento con il suo wallet e tiene lo storico lì, con le copie che scarica lui. L'on-chain è una funzione sperimentale, spenta finché la comunità non la accende (la Valley la tiene accesa): chi la vuole mette la sua chiave pubblica nella cassa, e gli indirizzi nascono lì.
Un negozio con indirizzo Lightning incassa anche se il server si spegne: l'indirizzo è del suo wallet, e un QR dell'indirizzo stampato a parte continua a funzionare. Il cartello del sito no: il suo QR apre la pagina del negozio, che sta sul server.
La sospensione toglie un negozio dalla mappa e non gli tocca la cassa. Chi gestisce il sito non ha modo di bloccare gli incassi di nessuno.
Cosa c'è dentro
| Parte | Tecnologia |
|---|---|
| Sito e pannello | Django, Postgres, Caddy |
| Cassa | Nel browser: chiede la fattura all'indirizzo Lightning del negozio (LNURL-pay) e controlla il pagamento con LUD-21 verify |
| Incasso senza custodia | Qualunque indirizzo Lightning che risponda a LUD-21 verify dal suo dominio e al browser; per un negozio piccolo, un wallet non custodial su Spark (quali abbiamo provato) |
| On-chain | Sperimentale, spento di default: sul telefono o sul computer della cassa, chiave pubblica estesa o indirizzo fisso |
| Login | LNURL-auth, oppure link via email |
| Mappa | Leaflet, OpenStreetMap, nessuna chiave |
| Dati aperti | NIP-05, negozi ed eventi firmati su Nostr, /shops.json |
Sul server non ci sono un nodo Bitcoin né un server di pagamento: niente da sincronizzare, niente canali, niente chiavi API dei wallet. Le vendite restano sul telefono o sul computer della cassa.
Installazione
| Cosa ti serve | Per provarlo | Per un sito vero |
|---|---|---|
| Software | Python 3.14 | Linux con Docker |
| Macchina | Il tuo computer | Una sola: 1 o 2 CPU, 2 GB di RAM |
| Rete | Niente | Un nome a dominio che punta lì, porte 80 e 443 aperte |
Per provarlo (5 minuti)
Sul tuo computer, con una comunità di esempio e negozi inventati:
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
export SECRET_KEY=prova DEBUG=1 && .venv/bin/python manage.py migrate && .venv/bin/python manage.py demo_data
.venv/bin/python manage.py runserver
Per un sito vero (una macchina)
Basta una macchina sola, con quello che dice la tabella: Caddy si prende da solo i certificati.
git clone https://github.com/mammadori/bitmentor.git && cd bitmentor && cp -r examples/community ../la-mia-comunita
cp .env.example .env && for k in SECRET_KEY POSTGRES_PASSWORD WEB_DB_PASSWORD; do sed -i "s/^$k=.*/$k=$(openssl rand -hex 32)/" .env; done && chmod 600 .env
Nel .env scrivi il nome con SITE_HOST, il percorso della tua comunità con COMMUNITY_DIR e il tuo indirizzo IP in DEV_ALLOWED_IPS. Poi:
docker compose up -d
Si parte sulla signet, e chi può vedere il sito
Si parte sulla signet, la rete di prova, dove tutto funziona uguale e i satoshi non valgono niente; la mainnet è un passo dopo.
Il sito parte in modalità development: lo vedono solo gli indirizzi scritti in DEV_ALLOWED_IPS. SITE_MODE=production lo apre a tutti e funziona solo su mainnet. manage.py preflight dice cosa manca ancora, dall'email alla mainnet. Per aggiornare: git pull && docker compose up -d --build.
Da lì in poi i commercianti fanno da soli: ognuno scrive l'indirizzo Lightning del suo wallet. Se arrivi da un altro sistema, manage.py import_shops file.json porta dentro l'elenco dei negozi. Le funzioni facoltative, da Telegram a Nostr, si accendono dal .env o da community.yml; le due sperimentali, l'on-chain alla cassa e l'invio a OpenStreetMap, restano spente finché la comunità non le accende. Quali wallet suggerire ai negozi lo dice docs/wallets.md. L'elenco delle funzioni è nel README, con le istruzioni passo passo e la versione con immagini e CI per chi è in tanti.
La tua comunità
community.yml nome, contatti, lingue, itinerario, eventi
theme/ font, colori, logo, immagini
pages/<lingua>/ pagine in Markdown, con i dati vivi
templates/ testata e piè di pagina, se li vuoi diversi
data/ i tuoi numeri
Questa cartella è l'unica cosa diversa tra una comunità e l'altra. La Valley nella tua città te ne prepara una, nel tuo browser.
Dati aperti
/shops.json: i negozi, riusabili da chiunque./theme/docs/registro.csv: il registro per anno./theme/docs/registro-mesi.csv: il registro per mese./.well-known/nostr.json: identità NIP-05 della comunità./sitemap.xml.
Blossom: i file per impronta
I file del sito (foto, documenti, la copia del sito) si possono chiedere anche per la loro impronta SHA-256, come fa un server Blossom in sola lettura: https://bitcoinvalley.eu/blossom/<sha256>.
Chiunque può controllare che i byte tornino con l'impronta e tenerne una copia sul proprio server Blossom; chi vuole copiarli tutti parte da /blossom/list, l'elenco con impronta, dimensione e indirizzo di ogni file. Non si carica niente e non si chiede il permesso.
È il pezzo tecnico dell'immortalità digitale: un file che qualcuno ha copiato resta raggiungibile, con la stessa impronta, anche da un altro indirizzo. Dura finché qualcuno lo tiene: il sito mette a disposizione i file, le copie le fa chi vuole.
Non fidarti, controlla
Il PDF del testo di Satoshi che trovi qui è lo stesso inciso nella blockchain. Con un tuo nodo:
seq 0 947 | (while read -r n; do bitcoin-cli gettxout 54e48e5f5c656b26c3bca14a8c95aa583d07ebe84dde3b7dd4a78f4e4186e713 $n | jq -r '.scriptPubKey.asm' | awk '{print $2 $3 $4}'; done) | tr -d '\n' | cut -c 17-368600 | xxd -r -p | sha256sum
Deve uscire b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553, come per il nostro file.
I conti del registro si rifanno così:
awk -F, 'NR>1{s+=$2} END{print s}' registro-mesi.csv
Fa 5143.
Il sito stesso si porta via: una copia intera, con le impronte e la firma, da rimettere su ovunque.