Gestisci il tuo gateway

Verificare un record Label 309 non richiede nulla a nessuno: né account, né server, né chiavi. La pubblicazione è l'altra metà: mette una transazione su Cardano, e questo ha un costo. Il gateway è il tassello che lo paga. Custodisce il wallet Cardano finanziato che ancora il record (e un wallet Arweave per i file sigillati), costruisce e invia la transazione, la segue fino alla conferma e restituisce i record per la verifica in autonomia.

Nella maggior parte dei casi punti l'SDK o la CLI al gateway di qualcun altro. Ma l'intero backend è open source, label-309-gateway, un unico binario Rust più Postgres, così puoi gestirne uno tuo. Mettine in piedi uno in privato per le tue app, oppure gestiscine uno come servizio a pagamento per gli altri: è multi-tenant per definizione, con molti account e molte API key sotto un'unica istanza. Questa guida ti accompagna da zero fino al primo preventivo con prezzo, usando il Docker Compose di riferimento.

Prima di iniziare

Ti servono Docker e Docker Compose e un host con qualche gigabyte di spazio libero su disco. Tutto ciò che segue punta alla preprod di Cardano, l'assetto più sicuro per avviare un deployment. Il passaggio a mainnet è una scelta deliberata che fai più avanti, una volta che il deployment è finanziato e verificato.

Prendi il codice e scrivi la configurazione

Clona il repository e lavora dalla cartella deploy/, dove si trova il docker-compose.yml di riferimento. Copia la configurazione di esempio e adattala al tuo deployment: rete, fascia di fee, storage e prezzi:

git clone https://github.com/cardanowall/label-309-gateway
cd label-309-gateway/deploy
cp ../gateway.example.toml gateway.toml

L'esempio è commentato e punta già alla preprod, quindi si avvia così com'è per una prima prova.

Crea il keyring

Ogni chiave di firma usata dal gateway risiede in un unico file keyring cifrato con age. Crealo, poi aggiungi una chiave Cardano (preprod), una chiave Arweave e una chiave per il wrapping dei webhook. Questi passaggi keyring eseguono direttamente il binario gateway: il keyring va creato su una macchina fidata, copiando poi nel container soltanto il suo file cifrato, quindi per questo unico passaggio procurati una build di release dal repository.

mkdir -p secrets
printf '%s' 'a-strong-passphrase' > secrets/gateway-keyring-passphrase
export GATEWAY_KEYRING_PASSPHRASE="$(cat secrets/gateway-keyring-passphrase)"

gateway keyring init             --path secrets/gateway-keyring.age
gateway keyring add-cardano      --path secrets/gateway-keyring.age --network preprod
gateway keyring add-arweave      --path secrets/gateway-keyring.age
gateway keyring add-webhook-wrap --path secrets/gateway-keyring.age
chmod 600 secrets/*

Ogni passaggio add- stampa l'indirizzo appena creato. Finanzia i due indirizzi stampati: l'indirizzo Cardano paga le fee di ancoraggio, mentre l'indirizzo Arweave alimenta i crediti di storage per i file sigillati. Poi imposta la password del database che il compose legge:

echo 'POSTGRES_PASSWORD=a-strong-db-password' > .env

Mettilo in funzione

Prima prepara l'operatore. Questo comando applica le migrazioni e stampa il segreto root una sola volta: conservalo in un posto sicuro, è la credenziale principale del control plane:

docker compose run --rm gateway operator bootstrap --label acme

Poi avvia Postgres e il gateway:

docker compose up -d

Registra un wallet, un account e una chiave

Il compose non pubblica di proposito alcuna porta sull'host: il data plane e il control plane condividono un unico socket, quindi esporlo esporrebbe anche il control plane. Pilota il control plane da dentro il container. Apri una shell:

docker compose exec gateway sh

Puntalo al control plane locale con il segreto root stampato da bootstrap, poi registra il wallet Cardano finanziato (l'indirizzo stampato da keyring add-cardano), crea un account, accreditalo e genera una API key del data plane con gli scope per pubblicare:

export GATEWAY_CONTROL_URL=http://127.0.0.1:8080/control/v1
export GATEWAY_CONTROL_TOKEN='ctl_…the root secret from bootstrap…'

gateway admin wallet register primary addr_test1… preprod
gateway admin account create
gateway admin account fund <account_id> 10000000 "starter credit"   # $10
gateway admin key create <account_id> poe:create,poe:read,account:read

key create stampa la API key che pilota il data plane. Questa, insieme all'URL di base, è tutto ciò che serve a un'app.

Ottieni il tuo primo preventivo

Per raggiungere il data plane dall'host durante la configurazione, togli il commento dalla mappatura ports di loopback (127.0.0.1:8080:8080) in docker-compose.yml ed esegui di nuovo docker compose up -d: solo loopback, mai 0.0.0.0. Poi blocca un prezzo con la API key che hai appena generato:

curl -sS -X POST http://127.0.0.1:8080/api/v1/poe/quote \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"record_bytes":256,"recipient_count":0,"file_bytes_total":0}'

La risposta contiene un quote_id valido per 15 minuti e il dettaglio dei costi. Una chiamata di pubblicazione consuma quel quote_id in modo atomico insieme all'addebito sul balance: la stessa struttura in due passaggi, blocca un prezzo, poi invia, usata nelle guide dell'SDK. Il tuo gateway è attivo.

Come proseguire

Il binario in esecuzione espone il proprio riferimento API interattivo: il data plane su /api/v1/docs e il control plane su /control/v1/docs, entrambi resi completamente offline. Due documenti nel repository approfondiscono l'argomento: il runbook per operatori copre il finanziamento, le credenziali, la logica dei movimenti di denaro e l'operatività quotidiana, mentre la guida per gli integratori spiega come costruirci sopra un prodotto.

Il data plane del tuo gateway è esattamente ciò che le guide dell'SDK e della CLI intendono per URL di base. Sostituisci https://your-gateway.example con l'indirizzo che ora controlli, distribuisci le API key e pubblica la tua prima PoE attraverso un backend che è interamente tuo.