La scolpitura delle tessere

Stato: v1 — giugno 2026 Riferimenti: protocollo (§3 metadati, §7 «generazione dell’immagine» — qui risolto)

Premessa

Il protocollo lascia aperto, in §7, un punto: «la generazione dell’immagine della tessera (linguaggio visivo, identità grafica derivata dai dati)». Questo documento lo chiude.

Una tessera nasce come scheletro oggettivo (le parti, le ore, il lato) ancorato on-chain dal detailsHash. Finora era solo dati. Le diamo ora un artefatto visivo: un SVG che contiene il testo dello scambio e una piccola elaborazione grafica derivata da quel testo. È il “ricordo” dello scambio reso oggetto da guardare.

Due principi guidano il design, e vanno tenuti insieme:

La tessera è un artefatto privato del proprietario. Sempre. L’immagine non è pubblica.
I colori sono una scelta dell’utente. L’identità grafica non è imposta dal Compratempo: è dell’utente, e può cambiarla.

1. La tessera come artefatto visivo

L’immagine è un SVG: leggero, vettoriale, auto-contenuto (nessuna risorsa esterna, nessuno script), e quindi embeddabile direttamente come data:image/svg+xml;base64,… nel campo image dei metadati ERC-721 (vedi protocollo §3).

Il linguaggio visivo è generativo e deterministico: il testo dello scambio decide come l’immagine è composta, ma non quali colori — quelli li sceglie l’utente (vedi §4). Stesso testo + stessi colori → stesso SVG, sempre. L’identità grafica «derivata dai dati» di §7 è esattamente questo: la grafica nasce dal contenuto.

Il testo reso comprende lo scheletro dello scambio (le parti, le ore date e ricevute, la descrizione) e — se il proprietario l’ha scritta — la sua memoria: una nota personale, sigillata alla chiusura dello scambio, che resta privata e vive solo dentro la sua tessera. La memoria fa parte del testo reso (concorre quindi a comporre l’immagine), ma non è un dato condiviso né ancorato — vedi la chiusura dello scambio per come e quando si scrive, e §6 per il suo rapporto con gli hash. Il suo gemello, il messaggio che ogni parte lascia all’altra, non sta nella tessera: vive nello scambio e non viene mai reso nell’SVG.

L’estetica della tessera non segue il design-system del Compratempo (la carta-crema editoriale). È un artefatto dell’utente: ha un linguaggio suo, libero.

2. gensvg: il motore generativo

La generazione dell’SVG è affidata a gensvg, una libreria generica e autonoma: «testo + 1-3 colori → SVG deterministico» (un hash SHA-256 del testo distribuisce i colori scelti su uno sfondo a regioni piene). gensvg non sa nulla del Compratempo: non conosce tessere, scambi, ore. È pensata per essere riusata da app diverse, ed è pubblicata come pacchetto open (@natign/gensvg su npm).

Il confine è netto e va rispettato:

In gensvg sta solo il motore generico. Zero concetti Compratempo.
Tutto il Compratempo-specifico — quale testo mettere nella tessera, da dove prendere i colori, come impacchettare i metadati ERC-721, la privacy — vive in compratempo-api, in un sottile strato che chiama gensvg.

Così domani un’altra app importa lo stesso gensvg e ci fa tutt’altro, e il Compratempo non ne è toccato.

3. Privacy: la tessera è privata

L’immagine, e i metadati che la accompagnano, non sono pubblici. Solo il proprietario della tessera li vede.

Perché la chain non è il problema

Quel che finisce on-chain non rivela il contenuto:

detailsHash è un hash dei metadati — un impegno crittografico, non il testo. Non è reversibile.
tokenURI è un puntatore (una URL con dentro un identificatore opaco). Non dice nulla dello scambio.

Quindi la privacy si gioca tutta off-chain, su chi può leggere ciò a cui il puntatore punta. Nessuna modifica al protocollo, nessun ridisegno del contratto.

Perché l’endpoint API (e non Arweave) rende possibile la privacy

Il protocollo (§3, §6) immaginava i metadati su Arweave — storage pubblico e permanente. Ma ciò che è su Arweave è pubblico per sempre: incompatibile con una tessera privata. L’implementazione punta perciò il tokenURI a un endpoint dell’API (/tessere/:proposalId/:side), non ad Arweave. È proprio questa scelta a rendere possibile la privacy: un endpoint può autenticare e autorizzare; un file su Arweave no.

Come

L’endpoint che serve metadati e immagine richiede autenticazione e autorizza solo il proprietario di quella faccia della tessera. Chiunque altro — incluso un wallet o un marketplace NFT generico — riceve un diniego (401/403).

Il prezzo, accettato consapevolmente: gli strumenti NFT generici non riescono a renderizzare la tessera. È coerente — le tessere sono soulbound (non asset di mercato), sono possessi privati, visibili solo dentro il Compratempo, al proprietario.

Regola ferrea: l’SVG non va mai messo dentro la stringa tokenURI on-chain (sarebbe esposizione pubblica permanente). È sempre derivato a lettura e servito solo dall’endpoint protetto.

4. I colori: una scelta dell’utente

I colori vengono dalla palette del profilo dell’utente: «i miei colori». Una scelta deliberata, fatta una volta, che vale per tutte le sue tessere. La mia tessera = i miei colori — la faccia che appartiene al proponente usa la palette del proponente, quella della controparte usa la palette della controparte. Il mosaico di una persona acquista così una coerenza cromatica sua.

Palette ampia (fino a 7), tessera sobria (≤ 3)

La palette di profilo contiene fino a 7 colori: è il guardaroba cromatico della persona. gensvg, però, accetta al massimo 3 colori per immagine. Il legame fra i due è la firma del nostro linguaggio visivo: ogni tessera pesca dal guardaroba un sottoinsieme di ≤ 3 colori, in modo deterministico dal proprio contenuto (lo stesso testo che in gensvg decide la distribuzione decide anche quali dei tuoi colori usare). Così, con un’unica palette personale, tessere diverse mostrano accostamenti diversi — varietà dentro i tuoi colori, mai colori che non hai scelto. La selezione è stabile (stesso contenuto → stesso sottoinsieme) e quindi compatibile col «live» qui sotto.

I colori sono applicati live, alla resa: se cambi la tua palette, tutto il tuo mosaico si ri-tinge. Questo è sicuro perché i colori stanno fuori da ogni hash (vedi §6): ri-colorare non altera né l’SVG come identità di contenuto né l’ancora on-chain. La tessera è un artefatto che «riveste», non un’immagine congelata.

Quando un utente non ha ancora scelto una palette, si usa un default (la scolpitura è automatica e non può attendere una scelta). Il default è configurabile.

(Una scelta dei colori per singola tessera, distinta dal profilo, è una possibilità futura — non parte di questo design.)

5. La preview prima di scolpire

La scolpitura on-chain è irreversibile. Prima di confermarla, l’utente può vedere l’anteprima della tessera che otterrà.

È possibile perché l’SVG è derivato: la proposta (che esiste prima della scolpitura) contiene già lo scheletro, e la palette è quella del profilo di chi guarda. Si rende quindi lo stesso SVG che si otterrebbe scolpendo. Il flusso diventa: scegli la palette → vedi l’anteprima → confermi.

6. Rapporto con gli hash

Né l’immagine né i colori entrano negli hash dello scambio:

detailsHash (firmato dalle parti, ancorato on-chain) resta l’hash dello scheletro oggettivo dei metadati. SVG, palette e memoria non vi entrano → le tessere già scolpite restano valide, e ri-tingere non rompe nulla.
Anche gensvg, per costruzione, tiene i colori fuori dal proprio hash: a parità di testo, cambiare i colori non cambia il “fingerprint” del contenuto.
La memoria del proprietario è invece parte del testo reso (concorre quindi all’hash interno di gensvg, che governa la composizione), ma resta fuori dal detailsHash: non è un dato condiviso. Essendo sigillata alla chiusura, è fissa — a differenza dei colori, che restano «live».

Questa separazione è ciò che permette i colori «live» (§4) senza intaccare l’integrità garantita dal protocollo.

7. «Rendi oro»: un’annotazione privata

«Rendere oro» una tessera è un gesto del solo proprietario, il cui effetto vede solo lui. Non pubblica nulla, non cambia l’SVG. È un’evidenziazione — un bordo sovrapposto — nella vista mosaico del proprietario.

Resta un’annotazione privata e reversibile sul mosaico. La sua resa visiva vive nella vista mosaico (vedi §8), non nell’artefatto della tessera.

8. Cosa resta fuori (passi successivi)

La vista mosaico visuale. Oggi il mosaico è testuale; la griglia che mostra le tessere come immagini — e disegna il bordo oro sulle tessere «rese oro» — è il passo successivo, da affrontare dopo aver visto la resa dell’SVG.
Colori per singola tessera. L’override per-tessera, distinto dalla palette di profilo, resta una porta aperta.

Questo documento risolve il punto lasciato aperto in protocollo §7. Lo scheletro on-chain e le garanzie del protocollo restano invariati: qui si definisce solo come quello scheletro diventa un’immagine, e perché quell’immagine è dell’utente e privata.