The software
This site runs on bitmentor, under the GNU AGPLv3 licence (other licences, such as MIT, on request from the authors): github.com/mammadori/bitmentor. If your town wants to do the same, the code is there: it's our legacy. Name, colours, history and pages live in a folder, and can be changed without touching the code.
Try it now with your town: type the name, watch the site change, download your folder ready to go.
Design choices
The server never sees the recovery words and cannot spend. There are no spending keys anywhere in the system.
The server doesn't even see the sales. The till lives on the shop's phone or computer: it requests the invoice directly from the shopkeeper's Lightning address, checks the payment with their wallet and keeps the history there, with the copies the shopkeeper downloads. On-chain is an experimental feature, off until the community switches it on (the Valley keeps it on): whoever wants it puts their public key in the till, and the addresses are created there.
A shop with a Lightning address gets paid even if the server goes down: the address belongs to its wallet, and a QR code of the address printed separately goes on working. The site's sign doesn't: its QR code opens the shop's page, which lives on the server.
Suspension takes a shop off the map and leaves its till alone. Whoever runs the site has no way of blocking anyone's takings.
What's inside
| Part | Technology |
|---|---|
| Site and panel | Django, Postgres, Caddy |
| Till | In the browser: it requests the invoice from the shop's Lightning address (LNURL-pay) and checks the payment with LUD-21 verify |
| Non-custodial takings | Any Lightning address that answers LUD-21 verify from its own domain and to the browser; for a small shop, a self-custodial wallet on Spark (which ones we've tried) |
| On-chain | Experimental, off by default: on the till's phone or computer, extended public key or fixed address |
| Login | LNURL-auth, or a link by email |
| Map | Leaflet, OpenStreetMap, no key |
| Open data | NIP-05, shops and events signed on Nostr, /shops.json |
There is no Bitcoin node and no payment server on the server: nothing to sync, no channels, no wallet API keys. Sales stay on the till's phone or computer.
Installation
| What you need | To try it | For a real site |
|---|---|---|
| Software | Python 3.14 | Linux with Docker |
| Machine | Your own computer | Just one: 1 or 2 CPUs, 2 GB of RAM |
| Network | Nothing | A domain name pointing to it, ports 80 and 443 open |
To try it (5 minutes)
On your own computer, with an example community and made-up shops:
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
For a real site (one machine)
One machine is enough, with what the table says: Caddy fetches the certificates by itself.
git clone https://github.com/mammadori/bitmentor.git && cd bitmentor && cp -r examples/community ../my-community
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
In .env write the name with SITE_HOST, your community's path with COMMUNITY_DIR and your IP address in DEV_ALLOWED_IPS. Then:
docker compose up -d
You start on signet, and who can see the site
You start on signet, the test network, where everything works the same and the coins are worth nothing; mainnet is a step later.
The site starts in development mode: only the addresses listed in DEV_ALLOWED_IPS can see it. SITE_MODE=production opens it to everyone and works only on mainnet. manage.py preflight tells you what's still missing, from email to mainnet. To update: git pull && docker compose up -d --build.
From then on the merchants manage by themselves: each one enters the Lightning address of their own wallet. If you're coming from another system, manage.py import_shops file.json brings in the list of shops. Optional features, from Telegram to Nostr, are switched on from .env or from community.yml; the two experimental ones, on-chain at the till and uploading to OpenStreetMap, stay off until the community switches them on. Which wallets to suggest to shops is in docs/wallets.md. The list of features is in the README, with step-by-step instructions and the version with images and CI for larger setups.
Your community
community.yml name, contacts, languages, route, events
theme/ fonts, colours, logo, images
pages/<language>/ pages in Markdown, with live data
templates/ header and footer, if you want them different
data/ your numbers
This folder is the only thing that differs from one community to the next. The Valley in your town prepares one for you, in your browser.
Open data
/shops.json: the shops, reusable by anyone./theme/docs/registro.csv: the ledger by year./theme/docs/registro-mesi.csv: the ledger by month./.well-known/nostr.json: the community's NIP-05 identity./sitemap.xml.
Blossom: files by fingerprint
The site's files (photos, documents, the copy of the site) can also be requested by their SHA-256 fingerprint, as a read-only Blossom server does: https://bitcoinvalley.eu/blossom/<sha256>.
Anyone can check that the bytes match the fingerprint and keep a copy on their own Blossom server; if you want to copy them all, start from /blossom/list, the list with the fingerprint, size and address of every file. Nothing is uploaded and nobody's permission is needed.
It's the technical piece of digital immortality: a file someone has copied stays reachable, with the same fingerprint, even from another address. It lasts as long as someone keeps it: the site makes the files available, and whoever wants to makes the copies.
Don't trust, verify
The PDF of Satoshi's text you'll find here is the same one etched into the blockchain. With your own node:
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
The output should be b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553, as for our file.
The ledger's sums can be redone like this:
awk -F, 'NR>1{s+=$2} END{print s}' registro-mesi.csv
That comes to 5143.
The site itself can be taken away: a whole copy, with its fingerprints and signature, to put back up anywhere.