← Tutti gli articoli

11 min di lettura

Come usare CardanoWall senza il sito web

Il sito web è una sola interfaccia, non l’intero prodotto. Puoi pubblicare e verificare record Label 309 tramite una CLI, gli SDK, un’API gateway, un’app desktop o un servizio gestito da te.

Puoi usare CardanoWall senza mai aprire il sito web. Gli stessi record di Proof of Existence si possono creare, pubblicare e verificare da uno strumento a riga di comando, da un SDK nel codice della tua applicazione, da un’API gateway, da un’app desktop o da un servizio che gestisci tu stesso. Il sito è una delle interfacce verso uno standard aperto — Label 309 — e ciò che conta davvero è lo standard.

È proprio in questa distinzione che sta tutto il senso. La Proof of Existence spesso non è un’azione umana isolata. Vive dentro una build pipeline, una routine di compliance, un sistema di provenienza per l’AI, un flusso di prove legali o un prodotto costruito da qualcun altro. Nessuno di questi casi dovrebbe richiedere che una persona clicchi attraverso un’unica interfaccia web.

Cosa fa davvero il sito web?

Il sito web rende la Proof of Existence accessibile. Ti offre un composer visuale, una vista su account e saldo, le pagine dei record, la gestione delle identità, un flusso di upload e una pubblicazione guidata. Per la maggior parte delle persone è il punto di partenza giusto.

Ma non dovrebbe essere l’unico modo di usare lo standard. Se una prova funziona solo quando una persona clicca attraverso un’interfaccia, non può diventare infrastruttura. Le aziende hanno bisogno di automazione. Gli sviluppatori hanno bisogno di API e SDK. I team operativi e di sicurezza hanno bisogno di flussi ripetibili e scriptabili. Alcuni utenti vogliono i propri record e file sulla propria macchina. Alcuni operatori vogliono gestire da soli l’intera pipeline.

L’app web è la porta d’ingresso. Non è l’intero edificio.

Quali sono gli altri modi di usarlo?

Ce ne sono diversi, e convergono tutti sullo stesso artefatto — un record Label 309 standard ancorato su Cardano che chiunque può verificare in modo indipendente:

  • l’app web di CardanoWall;
  • lo strumento a riga di comando open source cardanowall;
  • gli SDK ufficiali (TypeScript, Python, Rust) per il codice delle applicazioni;
  • un’API gateway Label 309, raggiungibile con un token per account;
  • CardanoWall Desktop, il client open source local-first;
  • un gateway che ospiti tu stesso;
  • un prodotto tuo costruito sopra un gateway.

L’interfaccia può cambiare. Il formato della prova no. Tutto questo codice è open source su github.com/cardanowall, con licenza Apache-2.0, e il testo della specifica è sotto CC-BY-4.0.

Quando conviene usare l’API gateway?

Usa l’API quando pubblicare o leggere le prove deve far parte di un sistema anziché essere un passaggio manuale. Per esempio:

  • un prodotto SaaS crea una prova per ogni documento dei clienti;
  • una build pipeline pubblica le prove della release dopo ogni build;
  • una piattaforma di AI ancora batch di output generati;
  • un sistema di compliance pubblica uno snapshot di controllo giornaliero;
  • un flusso di lavoro sigilla le prove per destinatari specifici;
  • una dashboard interna legge lo stato di pubblicazione e il saldo dell’account;
  • un’integrazione con un partner invia record senza toccare l’interfaccia di CardanoWall.

Il percorso via API permette al tuo software di chiamare direttamente un gateway, mentre tu mantieni la tua esperienza utente. L’app web e il worker di CardanoWall raggiungono il gateway attraverso esattamente questi endpoint pubblici — non esiste una porta privata, quindi tutto ciò che fa il prodotto di riferimento puoi farlo anche tu. Se vuoi approfondire, leggi costruisci sull’API di CardanoWall.

Come funzionano i token API e gli scope?

Un gateway distingue due tipi di credenziale, e tenerli separati è la cosa più importante da fare bene.

I token di account agiscono come uno dei tuoi utenti. Il tuo backend genera un token di breve durata per un account specifico, e la chiamata procede sotto quel token: richiedi un preventivo, carichi contenuto, pubblichi, leggi il saldo di quell’account. Sono questi i token — e le API key costruite sullo stesso modello — che hanno senso negli script, nei job di CI e nelle integrazioni. Sono volutamente ristretti. L’insieme attuale degli scope è piccolo e mirato:

  • poe:create — richiedere preventivi, caricare contenuto, pubblicare record;
  • poe:read — leggere i record e lo stato di pubblicazione;
  • inbox:read — leggere il bookmark cifrato di sincronizzazione della Inbox;
  • account:read — leggere il saldo dell’account.

Questa è l’intera superficie programmatica, e i suoi scope sono ristretti di proposito. Un widget di dashboard in sola lettura ha bisogno soltanto di account:read. Un job di pubblicazione ha bisogno di poe:create. Nessuno dei due ha bisogno dell’altro. Non c’è, intenzionalmente, nessuno scope di decifratura lato server: sigillare e aprire sono operazioni che avvengono sul client, quindi le chiavi private dei destinatari non raggiungono mai un gateway e nessuna API key potrebbe mai autorizzare il server a leggere per te contenuto sigillato. Allo stesso modo, un job di CI non dovrebbe mai detenere l’Identity Seed di un utente, a meno che la firma locale non sia una scelta deliberata del tuo progetto, sotto i tuoi controlli — i seed e le chiavi private restano sul client per principio e non sono qualcosa che un gateway veda mai.

Le credenziali di operatore sono il secondo tipo, e non sono API key. Autorizzano il control plane — il provisioning degli account, l’applicazione degli aggiustamenti di saldo quando la tua fatturazione incassa, l’impostazione dei margini, la generazione dei token di account di cui sopra. Devono vivere solo su un backend fidato, mai in un browser, in un’app mobile o in uno script. Un token di account compromesso dovrebbe essere un fastidio di breve durata; una credenziale di operatore compromessa sarebbe un vero e proprio incidente.

La regola pratica: consegna ai client il token ristretto, limitato al singolo account, di cui hanno bisogno, e tieni l’autorità di operatore dietro al tuo backend.

Quando conviene usare la CLI?

Usa lo strumento a riga di comando quando una prova deve stare dentro uno script. Il binario cardanowall è indipendente dal gateway e raw-seed-first, il che lo rende perfetto per:

  • verificare un record in locale, senza aprire alcun sito web;
  • costruire e controllare prove Merkle su molti file;
  • firmare record;
  • inviare record dall’automazione;
  • sincronizzare la Inbox e tentare la decifratura dal terminale.

La CLI conta soprattutto perché tiene la Proof of Existence vicina ai sistemi che generano gli artefatti. Una build pipeline può calcolare l’hash dei propri output e pubblicare un record come parte della release. Un job di compliance può impegnarsi su un manifest giornaliero. Un utente locale può verificare un record offline. Il sito web è ottimo per le persone; la CLI è ottima per le operazioni ripetibili. Per pattern ed esempi, leggi usa la CLI nell’automazione.

Quando conviene usare un SDK?

Usa un SDK quando Label 309 deve far parte della tua applicazione. Gli SDK per TypeScript, Python e Rust aiutano a costruire record, calcolare l’hash del contenuto, verificare transazioni, firmare fuori dall’host, sigillare e decifrare payload, derivare un’identità da un seed e dialogare con qualsiasi gateway.

Avere tre SDK non è una questione di comodità: è interoperabilità. Sono gemelli byte-identici, validati contro gli stessi vettori di test canonici, così che un record pubblicato o firmato da uno si verifichi in modo identico sotto gli altri. È così che uno standard aperto resta uno standard aperto, invece di frammentarsi in formati «compatibili» tra loro incompatibili. Vale la pena evidenziare una proprietà utile: il verificatore standalone ha bisogno solo dei metadati della transazione, eventualmente dei byte del contenuto e di un explorer Cardano pubblico — nessun server dell’emittente sta nel percorso di fiducia.

Quando conviene usare Desktop invece del sito web?

Usa l’app desktop quando conta il possesso in locale. CardanoWall Desktop è un client open source, multipiattaforma e offline-first, costruito in Rust con Tauri sopra l’SDK Rust, e funziona come un client di posta: ti offre

  • vault dell’identità locali e cifrati;
  • accesso offline a tutto ciò che è già sincronizzato;
  • scoperta della Inbox sigillata e testo cifrato in cache sulla tua macchina;
  • ricerca locale sull’indice pubblico dei record;
  • più identità e la libertà di scegliere il provider del gateway.

Il sito web resta rapido e comodo, mentre l’app desktop è la sede migliore quando vuoi che i tuoi record, le tue identità e i file in cache risiedano in locale e continuino a funzionare anche senza rete. Per molti la risposta sarà entrambi. Trovi altri dettagli sul design in CardanoWall Desktop e prove offline.

Quando conviene ospitare in proprio un gateway?

Ospitalo in proprio quando vuoi gestire tu stesso la pipeline di pubblicazione — per compliance, struttura dei costi, volume, policy di gestione dei dati, controllo dell’infrastruttura o strategia di prodotto.

Un gateway self-hosted pubblica comunque record Label 309 standard; la differenza è che sei tu a gestire il servizio che fa i preventivi, carica, invia, conferma, indicizza e tiene la contabilità delle pubblicazioni. Il gateway è un singolo binario Rust open source più Postgres, con un suo costruttore di transazioni Cardano che costruisce, invia, conferma, gestisce le riorganizzazioni della catena e rimborsa automaticamente in caso di fallimento permanente.

L’hosting in proprio non è «gratis». Paghi comunque i costi sottostanti di Cardano e Arweave, e ti assumi la responsabilità operativa di farlo funzionare. Ciò che elimini è qualsiasi dipendenza da un gateway CardanoWall ospitato per pubblicare. Leggi gestisci il tuo gateway e cos’è un gateway Label 309?.

Posso costruire un mio prodotto su un gateway?

Sì — ed è esattamente per questa separazione che il gateway è un layer a sé, distinto dall’app web. Puoi costruire un prodotto di notarizzazione, un portale di prove, un archivio di compliance, uno strumento di pubblicazione, un servizio di provenienza per l’AI o una dashboard interna sopra un gateway Label 309.

Il gateway possiede il piano di base: catena, storage, pricing, l’indice condiviso dei record on-chain, i saldi e lo stato di pubblicazione. Il tuo prodotto possiede il piano del fornitore: utenti, fatturazione, UI, flussi di lavoro, notifiche, supporto e qualunque significato specifico del prodotto tu voglia dare ai record. Questo permette a molti più prodotti di condividere un unico standard di prova, senza che ogni team debba diventare un operatore di transazioni e storage Cardano. La guida passo passo è in costruisci su un gateway Label 309.

Posso verificare senza CardanoWall, del tutto?

È proprio questo l’obiettivo, ed è la ragione più forte per cui esiste tutto il resto. La verifica non deve dipendere dal sito web di CardanoWall. Chiunque dovrebbe poter leggere i metadati della transazione, ricostruire il record Label 309, validarne la struttura, controllare eventuali firme del record, ricalcolare l’hash del contenuto e — con la chiave giusta — decifrare in locale un record sigillato.

Una prova che può verificare un solo sito web è una prova debole. Sono gli SDK aperti, una CLI aperta e una specifica aperta a rendere una prova Label 309 verificabile da chiunque, inclusi i terzi che non toccano mai CardanoWall. Se vuoi farlo da solo, parti da verifica un record Label 309.

E il pricing?

Cambiare interfaccia non elimina il costo sottostante. Che tu pubblichi dal sito web, dall’app desktop, dalla CLI, dall’API o dal tuo prodotto, qualcuno paga comunque le commissioni reali di transazione su Cardano più lo storage eventualmente usato per file o testo cifrato. Un gateway ospitato aggiunge un margine per coprire operazioni, finanziamento, infrastruttura e supporto, quindi il prezzo è cost-pass-through più quel margine.

Se usi il gateway ospitato di CardanoWall, ne usi il modello di saldo prepagato e di pricing. Se ospiti in proprio, gestisci e finanzi direttamente il tuo gateway. In entrambi i casi, lo standard rende portabile il record — non rende gratuiti le blockchain o lo storage. Il ragionamento è spiegato in perché pubblicare ha un prezzo.

Un limite importante

Una prova Label 309 mostra che byte specifici esistevano entro un momento pubblico specifico e che da allora non sono cambiati. Non dimostra chi ha creato il contenuto, chi lo possiede, se è vero o se qualcuno ne detiene i diritti. Un record sigillato mantiene il proprio testo in chiaro leggibile solo ai detentori della chiave previsti, ma non può garantire l’anonimato e non può impedire a un destinatario di divulgare il testo in chiaro una volta che lo ha decifrato. Tieni a mente questo confine, da qualunque interfaccia tu pubblichi.

In breve

CardanoWall non è soltanto un sito web. Il sito è l’interfaccia umana più facile; il gateway è il layer di pubblicazione; la CLI e gli SDK sono le superfici per gli sviluppatori; l’app desktop è il client locale, offline-first; l’hosting in proprio è il percorso dell’operatore. Producono tutti la stessa cosa: un record Label 309 standard, verificabile al di fuori dell’interfaccia che lo ha creato.

Scegli l’interfaccia adatta al lavoro. Usa il sito web per le persone, la CLI per gli script, gli SDK per i prodotti, l’API per i sistemi e un gateway self-hosted quando ti serve indipendenza dal fornitore o controllo operativo.

Per approfondire

developersapigatewayself-hosting