OP_RETURN e Timestamping On-Chain: Guida Tecnica per Sviluppatori con BTCPay Server

Quando si parla di tracciabilità blockchain, il termine OP_RETURN ricorre spesso ma raramente viene spiegato in dettaglio. In questa guida tecnica vediamo esattamente cos'è, come funziona, e come integrarlo nei tuoi sistemi tramite BTCPay Server e Bitcoin RPC.

Cos'è OP_RETURN

OP_RETURN è un opcode dello scripting language Bitcoin che permette di includere fino a 80 byte di dati arbitrari in una transazione, rendendola provably unspendable (nessun output può essere speso). Questo la rende ideale per il timestamping: i dati vengono scritti permanentemente nella blockchain senza "sporcare" l'UTXO set.

Proprietà chiave:

• Immutabilità: una volta confermata, la transazione non può essere alterata
• Timestamp proof-of-work: il blocco che include la transazione ha un timestamp garantito dalla difficoltà di mining
• Verifica pubblica: chiunque può leggere i dati OP_RETURN da qualsiasi block explorer
• Costo minimo: una transazione OP_RETURN costa pochi satoshi (tipicamente 200–500 sat)

Il Flusso di Timestamping: Passo per Passo

1. Genera l'Hash del Documento

Il primo passo è calcolare l'hash SHA-256 del documento o dataset che vuoi ancorare. L'hash è un'impronta digitale univoca di 32 byte: qualsiasi modifica al documento, anche di un singolo bit, produce un hash completamente diverso.

# Python
import hashlib

def hash_document(filepath):
    sha256 = hashlib.sha256()
    with open(filepath, 'rb') as f:
        for chunk in iter(lambda: f.read(4096), b''):
            sha256.update(chunk)
    return sha256.hexdigest()

doc_hash = hash_document('lotto_produzione_2026_07_27.pdf')
print(doc_hash)
# es: a3f8c2d1e4b7a9f0c3d6e8b2a5f1c4d7e0b3a6f9c2d5e8b1a4f7c0d3e6b9a2f5

2. Costruisci la Transazione OP_RETURN via Bitcoin RPC

Con un Bitcoin full node attivo (integrato in BTCPay Server), puoi inviare la transazione direttamente via RPC:

# Crea un output OP_RETURN con l'hash del documento
bitcoin-cli createrawtransaction \
  '[{"txid":"INPUT_TXID","vout":0}]' \
  '[{"data":"a3f8c2d1e4b7a9f0c3d6e8b2a5f1c4d7e0b3a6f9c2d5e8b1a4f7c0d3e6b9a2f5"}]'

# Firma e invia
bitcoin-cli signrawtransactionwithwallet RAW_TX_HEX
bitcoin-cli sendrawtransaction SIGNED_TX_HEX

3. Integrazione con BTCPay Server API

BTCPay Server espone API REST che permettono di gestire il wallet e inviare transazioni senza accedere direttamente al nodo Bitcoin:

# Crea un pagamento con metadata OP_RETURN tramite BTCPay API
curl -X POST https://btcpay.tuodominio.it/api/v1/stores/{storeId}/payment-requests \
  -H 'Authorization: token YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": "0.00001",
    "currency": "BTC",
    "metadata": {
      "documentHash": "a3f8c2d1e4b7a9f0...",
      "lottoId": "LOTTO-2026-07-27-001",
      "fase": "produzione",
      "operatore": "mario.rossi@azienda.it"
    }
  }'

4. Workflow n8n Completo

Il workflow n8n che automatizza l'intero processo:

Trigger: BTCPay Webhook (invoice.settled)
  → Node HTTP: scarica documento dal gestionale
  → Node Function: calcola SHA-256
  → Node HTTP: invia a Bitcoin RPC (createrawtransaction)
  → Node HTTP: signrawtransaction
  → Node HTTP: sendrawtransaction
  → Node Postgres: salva {txid, hash, lotto, timestamp}
  → Node HTTP: notifica Telegram/Email con TXID
  → Node HTTP: aggiorna ERP con riferimento on-chain

Verifica dell'Ancoraggio

Chiunque può verificare che un documento non sia stato alterato in tre passi:

1. Calcola l'hash SHA-256 del documento ricevuto
2. Cerca il TXID su un block explorer pubblico (mempool.space, blockstream.info)
3. Confronta l'hash nel campo OP_RETURN con quello calcolato: se coincidono, il documento è autentico e il timestamp è certificato dalla blockchain

# Verifica via bitcoin-cli
bitcoin-cli getrawtransaction TXID true | jq '.vout[] | select(.scriptPubKey.type=="nulldata") | .scriptPubKey.asm'

Best Practice per la Produzione

• Usa sempre SHA-256 doppio (SHA-256d) per coerenza con lo standard Bitcoin
• Includi metadati strutturati nell'hash: non solo il documento, ma anche lotto ID, data, operatore — in formato JSON canonico prima dell'hashing
• Conserva il TXID nel tuo database interno come riferimento immutabile all'ancoraggio on-chain
• Usa fee dinamiche per garantire la conferma entro 1-3 blocchi nei momenti di alta congestione della mempool
• Testa su Testnet prima di andare in produzione: le transazioni OP_RETURN su testnet sono gratuite
• Multi-WAN failover sul nodo BTCPay per garantire disponibilità continua del servizio di timestamping

Costi Operativi Reali

Un ancoraggio OP_RETURN tipico richiede una transazione da ~250 byte. Con fee di 10 sat/vbyte (fee bassa, conferma in ~1 ora):

• Costo per ancoraggio: ~2.500 satoshi ≈ 0,02€ (a BTC = 80.000€)
• 100 ancoraggi/giorno: ~2€/giorno, ~60€/mese
• Confronto con soluzioni SaaS di timestamping: 50–500€/mese per volumi equivalenti

Il risparmio è netto, con il vantaggio aggiuntivo della sovranità totale: nessun vendor intermedio, nessun rischio di shutdown del servizio.

Risorse e Prossimi Passi

Leggi anche:

• Tracciabilità DOP/IGP con Bitcoin e BTCPay Server
• BTCPay Server vs ERP tradizionali per la tracciabilità
• Panoramica: Tracciabilità della Filiera con BTCPay Server

Contattaci per supporto nell'implementazione del timestamping on-chain nella tua infrastruttura.