Documentazione.

01 — Inizia

Scarica e installa.

Scegli il file del tuo sistema, installalo e supera l'avviso del primo avvio.

Templar Wallet è un'alpha e lavora solo su Bitcoin testnet e Liquid testnet. Le monete non hanno valore.

Cosa serve

Per sincronizzare e inviare serve internet: l'app si collega in TLS ai server testnet pubblici di Blockstream. Aprire un wallet e preparare una transazione funziona anche offline.

Non servono account, chiavi API o un nodo tuo.

La cifratura del vault usa molta memoria: quando scrivi la password servono almeno 2 GB di RAM libera.

macOS

L'app non è notarizzata da Apple, quindi macOS la blocca con «Apple non è riuscita a verificare…» o dice che è «danneggiata». La causa è la quarantena che il browser mette sui file scaricati.

Metodo 1, dal Terminale. Toglie la quarantena e funziona sempre, anche su macOS 26 Tahoe.

1. Apri il Terminale. Cmd+Spazio, scrivi «Terminale», Invio.
2. Sblocca il .dmg. Scrivi xattr -d com.apple.quarantine e uno spazio, trascina il .dmg nella finestra e premi Invio. Se risponde No such xattr, va bene lo stesso.
3. Installa. Apri il .dmg, trascina Templar Wallet in Applicazioni ed espelli il disco.
4. Sblocca l'app e aprila con questi due comandi. La -r serve: la quarantena sta anche sui file dentro l'app.

   xattr -r -d com.apple.quarantine "/Applications/Templar Wallet.app"
   open "/Applications/Templar Wallet.app"

Metodo 2, fino a macOS 15 Sequoia. Trascina l'app in Applicazioni e aprila: macOS la blocca. Chiudi l'avviso con Fine. Poi Impostazioni di Sistema → Privacy e sicurezza → Apri comunque, e conferma con la password del Mac o Touch ID.

Il tasto destro → Apri funziona solo fino a macOS 14 Sonoma. Su Tahoe, se Apri comunque non compare o l'app risulta «danneggiata», usa il Metodo 1.

Hai anche lo script install-macos.sh? Mettilo accanto al .dmg e lancia bash install-macos.sh: fa il Metodo 1 da solo. Se trova una versione precedente la sostituisce, e non tocca i dati dei wallet.

La prima volta che usi Scan QR, macOS chiede l'accesso alla fotocamera. Concedilo, o l'anteprima resta nera.

Windows

Il file consigliato è l'installer. La procedura guidata è in inglese.

1. Avvia il setup. SmartScreen dice «Windows ha protetto il PC»: scegli Ulteriori informazioni → Esegui comunque.
2. Scegli per chi. Se te lo chiede: Install for all users (serve un amministratore) o Install for me only.
3. Select Destination Location. È la cartella del programma. Ogni aggiornamento la sostituisce.
4. Select Wallet Data Location. Qui stanno wallet, vault cifrato e cache. La proposta è %APPDATA%\templar_wallet. Deve stare fuori dalla cartella del programma: gli aggiornamenti non la toccano e resta anche se disinstalli.
5. Installa. L'icona sul desktop è facoltativa e spenta di serie (Create a desktop shortcut). Poi Install.

L'installer non aggiunge servizi né driver, e niente parte con Windows. Solo l'installer, non lo zip, registra i link templar:// del protocollo.

Versione portabile (zip). Tasto destro sullo zip → Estrai tutto… in una cartella vera. Non avviare l'app dall'anteprima dello zip: accanto all'eseguibile servono la cartella data\ e le DLL. Poi doppio clic su templar_wallet.exe. SmartScreen avvisa allo stesso modo. I dati vanno in %APPDATA%\templar_wallet.

Manca VCRUNTIME140.dll o MSVCP140.dll? Installa il Visual C++ Redistributable x64 e riprova.

Linux

Estrai l'archivio e avvia il programma. Al posto dei nomi tra < > metti quelli veri.

tar xzf <file scaricato>.tar.gz
./<cartella estratta>/templar_wallet

La cartella contiene tutto. Spostala dove vuoi, ma tienila intera. Se mancano librerie, su Debian e Ubuntu:

sudo apt install libgtk-3-0 libudev1 libegl1

Su Fedora:

sudo dnf install gtk3 systemd-libs libglvnd-egl

L'errore version `GLIBC_2.xx' not found vuol dire che la distribuzione è troppo vecchia. Segnalacelo, con il nome della distribuzione.

Voce nel menu, facoltativa. Registra anche i link templar://. Apri il terminale dentro la cartella estratta e lancia:

mkdir -p ~/.local/share/applications
sed -e "s|^Exec=.*|Exec=$PWD/templar_wallet %u|" \
    -e "s|^Icon=.*|Icon=$PWD/templar_wallet.png|" \
    dev.templarwallet.templar_wallet.desktop \
    > ~/.local/share/applications/dev.templarwallet.templar_wallet.desktop
update-desktop-database ~/.local/share/applications

Se sposti la cartella, rilancia i comandi dalla nuova posizione.

Aggiornare e disinstallare

Per aggiornare, installa la versione nuova sopra la vecchia. I dati e i wallet restano.

Sul computer la cartella dati resta anche dopo la disinstallazione. Dove si trova e come cancellarla: Problemi e segnalazioni.

Fonte: docs/INSTALLAZIONE.md e docs/guide.mdLeggi su GitHub

02 — Inizia

Verifica il download.

Un'impronta SHA-256 ti dice se il file che hai è quello pubblicato.

Le impronte stanno in SHA256SUMS.txt, allegato a ogni rilascio, una riga per ogni file. Il pacchetto dei tester lo contiene. Se accanto al tuo download c'è, controllalo prima di installare. Se l'impronta non coincide, il file è corrotto o non è quello pubblicato.

1. Metti i file insieme. Salva SHA256SUMS.txt nella cartella del file scaricato.
2. Apri un terminale in quella cartella. Il Terminale su macOS e Linux, PowerShell su Windows.
3. Lancia il comando del tuo sistema, qui sotto.

macOS e Linux:

shasum -a 256 -c SHA256SUMS.txt

Su Linux va bene anche sha256sum -c SHA256SUMS.txt. Accanto al tuo file deve comparire OK. Le righe dei file che non hai scaricato danno errore: ignorale.

Windows, in PowerShell:

Get-FileHash .\<nome del file> -Algorithm SHA256

Confronta il risultato con la riga di quel file in SHA256SUMS.txt. Maiuscole e minuscole non contano.

L'APK per Android puoi controllarlo allo stesso modo su un computer, prima di passarlo al telefono.

Quale versione hai

La versione giusta la mostrano l'installer di Windows, le informazioni app di Android e il Finder. Il Finder la scrive corta: per esempio 0.1.0.15 sta per 0.1.0-alpha.15.

Non guardare Settings → About: per un errore noto mostra sempre v0.1.0-alpha.1.

Fonte: docs/RELEASE_NOTES.mdLeggi su GitHub

03 — Inizia

Su Android.

Come installare Templar Wallet sul telefono e cosa cambia rispetto al computer.

Serve Android 7.0 o successivo. L'APK si installa a mano, fuori dal Play Store.

Su telefono o tablet scegli sempre l'APK arm64. Quello x86_64 serve solo agli emulatori Android su PC Intel o AMD. Non esiste una versione a 32 bit.

Installare l'APK

1. Porta l'APK sul telefono. Scaricalo dal telefono, oppure copialo con il cavo, un cloud o una chat.
2. Aprilo. Tocca il file nell'app File, o nella notifica del download.
3. Consenti l'installazione. La prima volta Android la blocca. Tocca Impostazioni, attiva Consenti da questa fonte e torna indietro.
4. Installa. Tocca Installa. Se Google Play Protect avvisa, scegli Altri dettagli → Installa comunque.
5. Apri l'app. Trovi Templar Wallet nel cassetto delle app.

L'avviso arriva perché l'APK non viene dal Play Store.

Cosa cambia sul telefono

Se qualcosa non va

• «App non installata». Sul telefono c'è già una versione firmata in modo diverso. Controlla di avere la frase di recupero su carta, poi disinstalla e riprova.
• «Camera unavailable». Tocca Try again, oppure Open app settings e consenti la fotocamera.
• Segnalare un problema. Su Android il log non si può esportare. Manda screenshot, i passi fatti e l'ora circa. Altro in Problemi.

Fonte: docs/ANDROID_PORT.mdLeggi su GitHub

04 — Inizia

Il primo wallet.

Crea un wallet, scrivi la frase su carta e ricevi le prime monete di test.

L'app è in inglese. Qui trovi pulsanti e schermate scritti come li vedi.

Al primo avvio scegli Create new wallet per crearne uno nuovo. Con Restore an existing wallet ne ripristini uno dalla frase di recupero.

Creare un wallet

Per un wallet a una chiave su questo dispositivo i passi sono 8. Sono 7 se la password dell'app esiste già.

1. What kind of wallet? One key è la strada più semplice. Several keys must agree (multisig) chiede più firme: vedi Multisig. Custom rules (policy) è segnato Coming soon e non si può scegliere. Somewhere else — just watch it segue un wallet che hai altrove: mostra saldo e storico, non può spendere.
2. Where do your keys live? On this computer (sul telefono On this device) oppure On a hardware wallet: vedi Hardware wallet.
3. Which coins? Bitcoin + Liquid aggiunge Liquid dalla stessa frase, senza niente in più da scrivere. Oppure Bitcoin only. Come rete si può scegliere solo Testnet.
4. Protect this app with a password. Solo la prima volta. Almeno 8 caratteri, scritti due volte. Poi Start setup.
5. Name & seed length. Dai un nome al wallet. 24 words è la scelta consigliata. 12 words è più comoda da copiare a mano.
6. Back up your seed. Le parole compaiono una volta sola, numerate. Scrivile su carta.
7. Verify your backup. L'app ti chiede tre parole. Poi Confirm & Finish.
8. Wallet created. Scegli Get receive address o Open Wallet.

La password dell'app

Serve quando la frase di recupero resta su questo dispositivo, e per ogni multisig. Cifra i dati salvati (Argon2id + XChaCha20-Poly1305). L'app la chiede a ogni avvio e prima delle azioni delicate. Una sola password vale per tutti i wallet.

Ne fanno a meno solo i wallet con la chiave su un hardware wallet e quelli watch-only, con Skip — don't encrypt wallet storage. Non è la passphrase BIP39 e non fa parte della frase di recupero.

La frase di recupero

Le 12 o 24 parole sono il wallet. Chi le ha può spendere.

• Su carta, non su uno schermo. Niente foto, file o chat.
• Nell'ordine esatto. Numera le parole mentre le scrivi.
• Due copie in due posti diversi.
• Mai dettarla a nessuno. Chi te la chiede sta rubando.

Le prime monete di test

Apri Receive, copia l'indirizzo e incollalo in un faucet. Le monete di test sono gratuite e non hanno valore.

• Bitcoin testnet: coinfaucet.eu/en/btc-testnet
• Liquid testnet: liquidtestnet.com/faucet o faucet.vulpem.com

La prima sincronizzazione Liquid è una scansione completa. Può volerci qualche minuto.

Aprire, cambiare, bloccare

Con almeno un wallet, l'app si apre sull'elenco Your Wallets. Ogni scheda dice tipo e monete, per esempio Software · BTC + Liquid. Un multisig mostra la soglia, per esempio 2-of-3. Da qui partono anche Restore e New Wallet.

• Sbloccare. Se compare Unlock wallet storage, scrivi la password in Vault passphrase e premi Unlock. Se li hai attivati, puoi usare Use Touch ID sul Mac o Use fingerprint su Android.
• Cambiare wallet. Sul computer, la doppia freccia accanto al nome del wallet riporta all'elenco. Sul telefono tocca il nome del wallet in alto.
• Bloccare. Sul computer Settings → Security → Lock now, sul telefono Settings → Lock now. Sul computer c'è anche il lucchetto in fondo alla barra laterale e nell'elenco dei wallet.

Ripristinare un wallet

1. Apri Restore Wallet. Dal benvenuto con Restore an existing wallet, dall'elenco con Restore.
2. Seed phrase. Scrivi le 12 o 24 parole, separate da uno spazio.
3. Wallet name e Coins. Dai un nome e scegli Bitcoin + Liquid o Bitcoin only.
4. Restore Wallet. Premi il pulsante.

Se la password dell'app non esiste ancora, prima si apre Encrypt wallet storage per crearla.

Fonte: docs/INSTALLAZIONE.mdLeggi su GitHub

05 — Usa il wallet

Ricevere e inviare.

Dove trovi le cose, come dai un indirizzo e come mandi una transazione.

La finestra

Su computer, a sinistra c'è la barra laterale. In cima trovi il wallet aperto: la doppia freccia torna all'elenco dei wallet.

• WALLET: Dashboard, Send, Receive, Activity, UTXOs. Un wallet watch-only non ha Send: può solo guardare.
• LIQUID: Liquid, LiquiDEX, Peg. Compare solo se il wallet ha Liquid. Peg compare solo se il wallet ha anche Bitcoin.
• SYSTEM: Wallet Info, Settings.

In fondo alla barra un pallino dice lo stato: Synced, Partial sync, Sync Error o Idle. Sotto ci sono Sync now e il tema chiaro o scuro. Quando l'archivio è aperto c'è anche il lucchetto Lock wallet storage, che lo richiude subito.

La Dashboard riassume il wallet: valore totale, grafico, filtri All / BTC / Liquid, valuta o sats, le schede Bitcoin e Liquid. L'occhio nasconde gli importi. Send e Receive stanno sotto il grafico. In alto a destra il badge TESTNET ti ricorda la rete.

Ricevere

Receive ti dà un indirizzo Bitcoin nuovo (Native SegWit), il suo QR e Copy address.

• New address ne crea un altro. Usane uno per pagamento: riusare un indirizzo lega i pagamenti tra loro.
• Previous addresses mostra gli ultimi 8. Show all apre l'elenco completo.
• Con il selettore in alto passi a Liquid. L'indirizzo è confidential: importi e asset restano nascosti sulla catena, e puoi riusarlo.
• Request an amount aggiunge un importo e una nota facoltativa. QR e link diventano un link di pagamento (BIP21) e il pulsante diventa Copy payment link. Share lo manda con le app del sistema.

Dopo aver incollato l'indirizzo altrove, controlla i primi e gli ultimi caratteri. Quando il pagamento è confermato, puoi dargli un nome con Tag nella schermata UTXOs.

Inviare

Send ha sei passi, uno per scelta. Niente viene firmato prima dell'ultimo.

1. Type. Standard transaction crea una transazione nuova. In un multisig si chiama Create a partial transaction. Cosign a transaction aggiunge la tua firma a una transazione preparata da altri: vedi Multisig.
2. Network. Bitcoin o Liquid Network, con il saldo disponibile. Su Liquid scegli anche l'asset.
3. Inputs. Automatic lascia scegliere al wallet. Manual coin control ti fa scegliere quali monete spendere. Su Liquid la scelta è solo automatica.
4. Outputs. Indirizzo e importo. Dal campo indirizzo puoi scansionare un QR (su macOS e Android), incollare o usare un indirizzo di questo wallet. MAX spende tutto, tolta la commissione. La freccia accanto all'unità passa alla valuta. Add output aggiunge un destinatario. Un link di pagamento compila indirizzo e importo insieme.
5. Fee. Slow, Normal, Fast o Custom (minimo 0,1 sat/vB). Su Liquid la commissione è fissa e minima: non c'è niente da impostare.
6. Review. Uno schema mostra ingressi e uscite: destinatario, resto (CHANGE, torna a te) e commissione, poi il totale. Nel caso più comune, Bitcoin con la chiave salvata nell'app, Review & sign apre Review transaction. Sign chiede la password dell'app, o Touch ID sul Mac se l'hai attivato. Broadcast manda la transazione in rete.

Negli altri casi il pulsante per firmare cambia. Su Liquid è Sign & send. In un multisig è Sign & continue: se servono altre firme, passi la transazione ai cofirmatari (vedi Multisig). Con un hardware wallet è Sign on device, con un dispositivo air-gap Export PSBT.

Fonte: src/templar_wallet/lib/features/Leggi su GitHub

06 — Usa il wallet

Attività, monete e Wallet Info.

Lo storico, le singole monete e le chiavi pubbliche del wallet.

Activity

Activity mette insieme lo storico Bitcoin e Liquid, diviso per giorno, con conferme, nota e controvalore. Puoi cercare per txid o per nota. I filtri All / Bitcoin / Liquid isolano una catena. L'occhio nasconde gli importi.

Apri una riga per il dettaglio: da lì copi il txid o premi View on Explorer.

UTXOs

Un wallet non ha «un saldo». Ha monete separate, gli UTXO. Vederle una per una ti fa scegliere quali spendere.

Ogni riquadro è una moneta, con la sua taglia e la sua quota del totale. In alto vedi quante monete hai, quante ne hai selezionate e il totale selezionato. A destra ci sono Consolidate e le viste Notes / List.

Un token non è mai DUST o WHALE per la sua quantità: 500 unità di una stablecoin non sono 500 sats.

• Una moneta appena arrivata è grigia, con la scritta Incoming. Non puoi selezionarla finché un blocco non la include.
• La i apre i dettagli: importo, taglia, conferme, outpoint, indirizzo e Open in explorer.
• Seleziona una o più monete e premi Tag per scrivere una nota. La nota ricompare quando scegli le monete da spendere.
• Consolidate unisce più monete in una. Funziona solo su Bitcoin e con almeno 2 monete. Costa una transazione, ma rende più economiche quelle dopo.

Wallet Info

In alto c'è l'identità del wallet: nome, rete, master fingerprint, percorso di derivazione e tipo di script. Sotto ci sono i descriptor pubblici. Ogni riga ha un pulsante per copiare e uno per il QR.

• For other apps: Copy descriptor bundle, Export JSON e Show QR esportano una copia watch-only per un altro programma. L'app nomina Sparrow, Specter, BlueWallet, Jade e SeedSigner.
• Se il wallet non ha ancora Liquid, la scheda Liquid Network offre Enable Liquid. Con un Jade il pulsante è Add Liquid from my Jade.
• L'XPUB m/84'/1'/0' è la chiave del wallet a firma singola. Non è una chiave da cofirmatario.
• Per entrare nel multisig di qualcun altro, un wallet a firma singola ha la scheda Use this wallet as a cosigner: la chiave Bitcoin (BIP48) e la chiave Liquid (BIP87), ognuna con copia e QR. Se le chiavi stanno su un hardware wallet, le leggi dal dispositivo nella procedura multisig. Vedi Multisig.

Fonte: CHANGELOG.mdLeggi su GitHub

07 — Usa il wallet

Sicurezza e impostazioni.

Come si blocca il wallet, cosa c'è in Settings e le abitudini che proteggono la frase.

Bloccare e sbloccare

Quando l'archivio è bloccato compare Unlock wallet storage. Scrivi la password dell'app e premi Unlock. Se hai attivato l'impronta, puoi usare anche Use Touch ID sul Mac o Use fingerprint su Android.

Per bloccare: il lucchetto in fondo alla barra laterale, oppure Lock now in Settings. Il blocco cancella dalla memoria le chiavi decifrate.

Auto-lock blocca da solo. Sul telefono conta il tempo in secondo piano. Su computer conta anche il tempo senza tastiera né mouse. Quando scatta, torni all'elenco dei wallet e serve di nuovo la password. Funziona solo se la password dell'app è impostata.

Su computer Lock now e Auto-lock sono in Settings → Security. Sul telefono sono nell'elenco di Settings.

Sblocco con l'impronta

Sul Mac: Settings → Security → Touch ID unlock. Il dito apre l'archivio all'avvio e dopo Lock now.

Sotto compare Also confirm with Touch ID, acceso di serie. Il dito sostituisce la password anche per firmare, condividere i dati del wallet e mostrare la frase. La password funziona sempre.

Su Android: Biometric unlock, nell'elenco di Settings. Il dito apre l'archivio. Per firmare e per mostrare la frase serve ancora la password.

Se cambi le impronte registrate nel sistema, lo sblocco si spegne da solo. Windows e Linux non hanno sblocco con l'impronta.

La sezione Security

Su computer è Settings → Security. Sul telefono le stesse voci stanno in Settings → Vault & backup.

Le sezioni di Settings

Su computer: Network & Sync, Squid Protocol, Security, Appearance, About.

Sul telefono un solo elenco: Wallet info · Biometric unlock · Auto-lock · Vault & backup · Lock now · Theme & units · Reduce effects · Nodes & explorers · Squid Protocol · Auto-sync · About.

• Network & Sync. Sincronizzazione all'avvio. Rete Liquid Testnet. Regtest serve solo a chi sviluppa con un nodo locale. Il server Bitcoin è fisso, gli explorer si possono cambiare. Tor è annunciato, non ancora pronto.
• Squid Protocol. Siti collegati e richieste di firma: vedi Templar Lend.
• Appearance. Nome e colore del wallet, valuta, BTC o sats, tema Dark, Light o System. In un multisig c'è Cosigner labels: nomi e colori delle chiavi, salvati solo su questo dispositivo. Language non ha ancora effetto: l'app è solo in inglese.
• About. Mostra per errore v0.1.0-alpha.1: la versione vera è la 0.1.0-alpha.15. Source code porta al repository GitHub.

Buone abitudini

• La frase sta su carta, controllata almeno una volta con Verify backup.
• La password dell'app non è la frase. Servono tutte e due.
• Controlla l'indirizzo prima di inviare, anche in testnet.
• Non firmare ciò che non capisci.
• Aggiorna con calma: prima il backup.

Fonte: docs/RELEASE_NOTES.mdLeggi su GitHub

08 — Avanzato

Multisig e co-firma.

Un multisig M-su-N spende solo quando M chiavi diverse hanno firmato.

Le chiavi possono stare su dispositivi o persone diverse. Templar prepara la transazione, raccoglie le firme e la trasmette.

Creare il wallet

1. Tipo. What kind of wallet? → Several keys must agree (multisig), poi Which coins?.
2. Password dell'app. Se non c'è ancora, l'app la chiede. Per un multisig è obbligatoria.
3. Soglia. In Choose your threshold scegli il nome, le firme richieste (M) e le chiavi totali (N, da 2 a 9). Con I hold one of these keys here acceso, l'app crea qui la tua chiave e te ne fa fare il backup. Spento, importi tutte le chiavi.
4. Chiavi. In Import the keys ogni chiave può avere nome, icona e colore. Poi scegli da dove arriva.
5. Crea. Review & create → Create Wallet.

Ogni chiave viene controllata prima dell'uso. Una chiave con percorso mainnet viene rifiutata.

In Dashboard la scheda Keys mostra un anello, una fetta per chiave nel suo colore, e la regola Any M of N keys can sign.

Bitcoin e Liquid insieme

Un solo wallet, due catene. Ogni cofirmatario dà due chiavi: quella Bitcoin (BIP48) e la Cosigner Liquid key (BIP87). Se la chiave è in questa app o su un Jade, l'app legge da sola anche la seconda.

• Una chiave Ledger, Trezor, Coldcard o KeepKey rende il wallet solo Bitcoin. Tra gli hardware wallet, solo il Jade firma su Liquid.
• Un multisig solo Bitcoin non si allarga a Liquid. Ricrealo con le stesse chiavi: stessi indirizzi Bitcoin, stessi fondi.
• Le stesse chiavi danno lo stesso wallet Liquid su ogni dispositivo.

Per entrare nel multisig di un altro, apri un tuo wallet a chiave singola: Wallet info → Use this wallet as a cosigner. Ci sono le due chiavi, ognuna con copia e QR. Si possono condividere: nessuna delle due può spendere.

Per seguire un multisig senza firmare: Somewhere else — just watch it → Build from cosigner keys.

Avviare una spesa

1. Prepara. Send → Create a partial transaction, poi firma con la tua chiave.
2. Fai girare. Si apre Co-signatures needed. Il grafico SIGNATURE QUORUM ha una fetta per chiave e dice chi ha già firmato. La transazione esce come QR animato, con Copy PSBT o con Save .psbt file (Share .psbt sul telefono).
3. Raccogli. Paste signed copy → Add signature. Oppure Scan signed QR (su macOS e Android) o il file firmato. Ogni copia si unisce alle altre, non le sostituisce. Una copia senza firme nuove viene rifiutata, con il motivo.
4. Trasmetti. Al quorum: Review & Broadcast → Review signed transaction → Broadcast.

Su Liquid la transazione è un PSET. I passi sono gli stessi, QR compreso.

Una chiave segnata come USB hardware wallet firma dal computer: Sign with USB hardware wallet → Sign on device. Vedi Hardware wallet.

Firmare la spesa di un altro

1. Apri. Send → Cosign a transaction. In WHICH CHAIN? scegli Bitcoin o Liquid.
2. Carica. Paste, File o Scan QR (su macOS e Android), poi Load & Inspect.
3. Controlla. Importi e indirizzi. Se qualcosa non torna, Decline.
4. Firma. Sign & Export. Su computer c'è anche Sign with device.
5. Restituisci. Show QR, Copy PSBT o il file. Su Liquid il pulsante dice Copy PSET.

Fonte: docs/guides/LIQUID_MULTISIG.mdLeggi su GitHub

09 — Avanzato

Hardware wallet.

La chiave resta sul dispositivo: Templar prepara il pagamento, il dispositivo lo approva.

È facoltativo. Se usi solo wallet software, salta questo capitolo.

Quali dispositivi

Su Windows e Linux, se HWI manca, la schermata del dispositivo mostra il riquadro HWI toolkit required. Install HWI scarica la versione ufficiale e ne controlla lo SHA-256. Per Ledger e Jade non serve.

Prima di collegarlo

• Ledger. Sbloccalo, apri l'app Bitcoin Testnet (non «Bitcoin») e chiudi Ledger Live.
• Jade. Firmware aggiornato e testnet attiva, da Options → Settings → Device → Enable Testnet. Via USB chiudi Blockstream Green, perché la porta la usa un'app alla volta. Tieni il computer online: serve per lo sblocco con il PIN.
• Jade via QR. Sbloccalo prima con l'app di Blockstream: Templar non fa da tramite per il PIN.

Creare il wallet

1. Dove stanno le chiavi. Alla domanda Where do your keys live? scegli On a hardware wallet.
2. Cavo o fotocamera. Alla domanda How does your device connect? scegli By cable (USB) o By camera (air-gapped QR). Su Android c'è solo la fotocamera.
3. Segui i passi. Via USB: Connect your device → Confirm what this device will hold → Name your wallet. Via QR: Choose your device → Export descriptor → Paste descriptor & name. Alla fine Pairing summary mostra lo stato di ogni rete e i controlli fatti.

Firmare un invio

• Via USB. In Send premi Sign on device. L'app accetta solo il dispositivo con l'impronta di questo wallet. Prima il dispositivo ti fa confermare un indirizzo del wallet. Poi mostra uscite e commissione, e tu approvi lì.
• Via QR. Premi Export PSBT e l'app mostra la transazione come QR animato. Inquadralo con il dispositivo e approva. Riporta la copia firmata con Scan signed QR, con un file .psbt o incollandola. Prima di Broadcast l'app ti mostra cosa paga davvero. Solo Bitcoin.

La scansione dei QR c'è su macOS e Android. Su Windows e Linux i pulsanti di scansione non compaiono: incolla la copia o carica il file.

Liquid: solo Jade via USB

Jade è l'unico hardware wallet che firma Liquid, e solo via cavo. Se scegli Bitcoin + Liquid, la creazione guidata te lo ricorda: For Liquid, the device must be a Blockstream Jade. Con altri dispositivi il wallet nasce solo Bitcoin.

Hai creato un wallet Jade solo Bitcoin? Apri Wallet Info e premi Add Liquid from my Jade. Templar apre il Jade solo quando firmi, così tra un invio e l'altro Blockstream Green può usarlo.

Linux: permessi USB

Se compare il riquadro Device permissions needed, premi Fix device permissions: chiede la password una volta sola. Poi scollega e ricollega il dispositivo. La prima volta esci anche dalla sessione e rientra.

Fonte: docs/guides/HARDWARE_TESTING.mdLeggi su GitHub

10 — Avanzato

Liquid: asset, LiquiDEX e Peg.

Cosa fa la parte Liquid del wallet, oltre a ricevere e inviare.

Liquid è una sidechain di Bitcoin. Ha un blocco ogni minuto, transazioni confidenziali e asset che chiunque può emettere.

Queste schermate compaiono solo se il wallet ha Liquid. Per aggiungerlo a un wallet software: Wallet Info → Liquid Network → Enable Liquid. Usa la stessa frase di recupero, non c'è altro da annotare. Per un Jade vedi Hardware wallet.

Gli asset

La schermata Liquid elenca gli asset che hai, per esempio L-BTC. Il dettaglio di un asset mostra l'Asset ID con il pulsante Copy ID e, quando sono noti, Ticker, Precision e Domain.

• Issue Asset crea un asset nuovo.
• Reissue emette altre unità di un asset di cui hai il token di riemissione.
• Burn distrugge unità dell'asset. Non si torna indietro.

Emettere un asset

1. Define asset. Nome, ticker, precisione (da 0 a 8) e dominio, tutti obbligatori. Sono permanenti: dopo l'emissione non si cambiano.
2. Initial supply. Quante unità emettere. Attiva Create reissuance token se vuoi poterne emettere altre più avanti. Senza token l'offerta resta fissa per sempre. Se perdi il token, non puoi più riemettere.
3. Review & sign. Rileggi tutto e premi Sign & Issue.
4. Il risultato. L'app mostra Asset ID, TxID e, se l'hai creato, l'ID del token di riemissione. Se compare Domain proof required, pubblica sul tuo dominio il file indicato: serve a registrare l'asset nell'explorer di Liquid testnet.

LiquiDEX

Un order book di swap atomici: due persone si scambiano asset in una sola transazione. Make offer pubblica una proposta, Take la accetta, Import proposal carica una proposta ricevuta. Le offerte segnate MAINNET · VIEW ONLY si possono solo guardare: il wallet firma solo su testnet.

Peg

Peg-in porta BTC su Liquid come L-BTC. Peg-out fa il contrario. L'indirizzo di destinazione è già compilato con uno di questo wallet.

Il peg ha bisogno di una parte Bitcoin. In un wallet solo Liquid il Peg non si può usare.

Fonte: docs/INSTALLAZIONE.mdLeggi su GitHub

11 — Avanzato

Collegare Templar Lend.

Templar Wallet firma i passi dei tuoi prestiti su un sito Templar Lend. Le chiavi restano nel wallet.

Il sito costruisce le transazioni del prestito. Templar te le mostra e firma solo dopo la tua conferma. A trasmetterle in rete è il sito, mai il wallet.

Nell'app il protocollo si chiama Templar Lend. I link iniziano con templar://.

Prima di iniziare

• Installa nel modo giusto. Su Windows usa l'installer: lo zip portabile non registra i link templar://. Su macOS basta copiare l'app in Applicazioni dal .dmg. Su Linux servono i comandi qui sotto.
• Imposta la password dell'app. Te la chiede prima di ogni firma. Su Mac, con Touch ID attivo, può bastare il dito.
• Usa un wallet software con Liquid attivo. Hardware, watch-only e multisig non si collegano ancora.
• Usa la rete del sito. Il wallet parte su Liquid Testnet. La rete si cambia in Settings › Network & Sync › Liquid network. Il cambio chiude il wallet aperto: riaprilo e sincronizza.

Solo Linux. Da un terminale aperto nella cartella estratta, questi comandi creano la voce nel menu e registrano i link templar://. Se sposti la cartella, ripetili.

mkdir -p ~/.local/share/applications
sed -e "s|^Exec=.*|Exec=$PWD/templar_wallet %u|" \
    -e "s|^Icon=.*|Icon=$PWD/templar_wallet.png|" \
    dev.templarwallet.templar_wallet.desktop \
    > ~/.local/share/applications/dev.templarwallet.templar_wallet.desktop
update-desktop-database ~/.local/share/applications
xdg-mime default dev.templarwallet.templar_wallet.desktop x-scheme-handler/templar

Collegare il wallet

1. Parti dal sito. Nella pagina Wallet premi «Collega Templar Wallet».
2. Templar si apre. Compare la schermata Connect wallet. Se l'archivio dei wallet è bloccato, prima ti chiede la password dell'app.
3. Scegli il wallet. Templar propone solo quelli adatti.
4. Leggi cosa riceve il sito. Una vista watch-only di Liquid: vede saldo e storico, non può spendere. La chiave escrow m/2121'/1'/0', un conto a parte usato solo nei contratti di prestito. Un indirizzo di ricezione e il nome del wallet.
5. Conferma. Spunta la frase, premi Share with … e inserisci la password dell'app.
6. Torna al sito. Compare Wallet connected. Open in browser ti riporta alla pagina, che si aggiorna da sola.

Firmare un passo del prestito

La firma serve quando il prestito si apre, per le rate e il rimborso, in caso di default e di liquidazione.

1. Apri la richiesta. Nella pagina del prestito premi «Firma con Templar Wallet».
2. Confronta le due colonne. A sinistra What … says: ruolo, importi e durata come li racconta il sito. A destra What "…" reads: quello che il wallet legge nella transazione stessa.
3. Firma. Spunta «I compared the site's summary with the wallet's reading…», premi Sign and send to … e inserisci la password.
4. Fatto. Compare Signature sent. Quando tutte le parti hanno firmato, il sito trasmette la transazione. La pagina del prestito ne mostra l'id.

In fondo alla colonna trovi commissione, rete e firme già raccolte. Sotto le due colonne, il riquadro Request mostra il Request id.

Settings › Squid Protocol

Ci arrivi anche con un tocco dal pannello Liquid della Dashboard.

• Status: la rete per cui il wallet è pronto, e Change network.
• Open a request: incolla un link templar:// o, dove c'è la fotocamera, inquadrane il QR. È la via di riserva quando il sito non apre Templar.
• Connected sites: chi vede un tuo wallet in sola lettura, e cosa ha ricevuto.
• Signing history: le ultime 50 richieste, con l'esito. Clear history la svuota.
• Preferred wallet for Squid requests: il wallet che risponde alle richieste e viene proposto per primo. Password e spunta servono comunque.
• How it works: il riassunto in tre passi.

Se il link non apre il wallet

1. Copia il link. Sul sito, tasto destro sul pulsante e copia l'indirizzo del link.
2. Incollalo in Templar. In Settings › Squid Protocol › Open a request, poi premi Open.

Perché Templar si apra da solo: su Windows reinstalla con l'installer, su Linux esegui i comandi di Prima di iniziare.

Messaggi che puoi vedere

Sono tutti previsti e nessuno mette a rischio le monete.

Limiti di questa alpha

• Si collegano solo i wallet software.
• Il wallet non mette d'accordo le due colonne da solo: il confronto tocca a te.
• Il wallet non ha schermate per i prestiti e non usa la mainnet.
• Un sito remoto deve usare https.
• La cronologia delle firme è solo di questo dispositivo. I prestiti stanno sul sito e sulla blockchain.
• La registrazione dei link su Windows e Linux non è ancora stata provata da chi sviluppa il wallet. Incollare il link funziona sempre.
• Su Android il collegamento con i siti non è ancora pronto.

La rete Regtest serve solo a chi sviluppa con un nodo locale.

Fonte: docs/guides/PROTOCOL_CONNECTOR.md · per chi prova: docs/guide.mdLeggi su GitHub

12 — Aiuto

Problemi e segnalazioni.

I problemi più comuni, dove stanno i dati e come mandarci una segnalazione utile.

Installazione e avvio

Nell'uso

Dove stanno i dati

La cartella in uso si vede in Settings › Security › Storage. Su Android la sezione si chiama Vault & backup.

Ripartire da zero

Chiudi l'app. Poi, su macOS:

rm -rf ~/Library/Containers/dev.templarwallet.templarWallet

Su Linux:

rm -rf ~/.local/share/templar_wallet ~/.config/templar_wallet.json

Su Windows, in PowerShell:

Remove-Item -Recurse -Force "$env:APPDATA\templar_wallet"
Remove-Item -Force "$env:APPDATA\templar_wallet.json"

Su Android: Impostazioni del telefono › App › Templar Wallet › Spazio di archiviazione › Cancella dati.

Segnalare un problema

Il repository è pubblico: apri una segnalazione nelle Issues su GitHub. Se no, scrivi a chi ti ha mandato la build o nel gruppo dei tester. Indica:

• sistema operativo e versione;
• quale build hai installato, dal nome del file scaricato: About nell'app mostra per errore v0.1.0-alpha.1;
• cosa stavi facendo, cosa ti aspettavi e cosa è successo;
• uno screenshot, se puoi.

Per un problema con Templar Lend aggiungi la rete Liquid, il riferimento del prestito, il Request id e uno screenshot della schermata di firma con tutte e due le colonne.

Allega il log

Su computer il log è logs/templar.log nella cartella dati, più templar.log.1 se c'è. Per copiarlo sulla Scrivania, su macOS:

cp ~/Library/Containers/dev.templarwallet.templarWallet/Data/Library/Application\ Support/templar_wallet/logs/templar.log ~/Desktop/

Su Linux:

cp ~/.local/share/templar_wallet/logs/templar.log ~/Desktop/

Su Windows il log sta in %APPDATA%\templar_wallet\logs, o nella cartella scelta nell'installer. Su Android non si può esportare: manda screenshot, i passi fatti e l'ora approssimativa del problema.

Per vedere gli errori mentre accadono, su macOS avvia l'app dal Terminale:

"/Applications/Templar Wallet.app/Contents/MacOS/templar_wallet"

Su Linux avvia ./templar_wallet da un terminale aperto nella cartella estratta. Su Windows l'app non scrive nulla sulla console: copia il testo esatto dell'errore o fai uno screenshot.

Limiti noti

• Solo testnet, nessun percorso verso la mainnet.
• App solo in inglese. About mostra una versione sbagliata.
• Scansione dei QR con la fotocamera solo su macOS e Android. Paste e File funzionano ovunque.
• Niente USB su Android. Con un hardware wallet, Liquid funziona solo con Jade via USB.
• Trezor, Coldcard, KeepKey e BitBox02 richiedono HWI su Windows e Linux. Su macOS non funzionano.
• Nessuna schermata per alzare la commissione (RBF) di una transazione già inviata.
• La password dell'app non si può cambiare né togliere.
• LiquiDEX è sperimentale. Il Peg è simulato.
• I wallet con regole personalizzate (policy) non sono ancora disponibili.
• Una sola istanza dell'app per volta.
• Niente notarizzazione Apple, niente certificato Authenticode, APK fuori dal Play Store: al primo avvio macOS, Windows e Android mostrano un avviso.

Fonte: docs/INSTALLAZIONE.mdLeggi su GitHub

13 — Sviluppatori

Codice sorgente e build.

Cosa c'è nel repository e come compilare Templar Wallet da te.

Cosa c'è dentro

La documentazione nel repository

Parti da docs/README.md: dice dove trovi cosa.

Prima di compilare

L'app è fatta di due pezzi che viaggiano insieme: la libreria Rust e il pacchetto Flutter. Se all'avvio la libreria manca, l'app di release si ferma su una schermata di errore.

Ogni sistema si compila su quel sistema: Flutter desktop non fa cross-compilazione. Ti servono:

• Rust stable (edition 2021), da rustup.rs.
• Flutter 3.44.1 stable, con Dart ^3.12.0.

I comandi partono dalla radice del repository, dove c'è Cargo.toml. La prima build Rust compila circa 500 crate e richiede alcuni minuti.

macOS

Serve Xcode con gli strumenti da riga di comando (xcode-select --install).

cd src/templar_wallet
flutter pub get
flutter build macos --release
open build/macos/Build/Products/Release/templar_wallet.app

Non serve altro: una fase Run Script di Xcode compila libwallet_ffi.dylib e la mette nell'app.

Vuoi che la tua build giri anche sui Mac Intel? Prima aggiungi i target: rustup target add x86_64-apple-darwin aarch64-apple-darwin.

Per un DMG lancia ./scripts/make_dmg.sh dalla radice. Il file finisce in dist/.

Linux

Su Debian o Ubuntu, dalla 22.04 in poi, installa i pacchetti:

sudo apt update
sudo apt install -y build-essential clang cmake ninja-build pkg-config \
    libgtk-3-dev libssl-dev libudev-dev curl git unzip xz-utils zip
flutter config --enable-linux-desktop

Poi compila, copia la libreria accanto all'eseguibile e avvia:

cargo build --release -p wallet-ffi
cd src/templar_wallet
flutter pub get
flutter build linux --release
cp ../../target/release/libwallet_ffi.so build/linux/x64/release/bundle/lib/
./build/linux/x64/release/bundle/templar_wallet

Si distribuisce tutta la cartella bundle/. Sul computer di arrivo serve GTK 3, e una glibc non più vecchia di quella del computer che ha compilato.

Fedora e altri dettagli: LinuxBuild.md.

Windows

Installa prima:

• Visual Studio 2022 con il carico di lavoro Desktop development with C++. VS Code da solo non basta.
• Git for Windows.
• Rust con rustup-init.exe, toolchain stable-x86_64-pc-windows-msvc.

OpenSSL non serve. In PowerShell, dalla radice del repository:

flutter config --enable-windows-desktop
flutter doctor
cargo build --release -p wallet-ffi
cd src\templar_wallet
flutter pub get
flutter build windows --release
Copy-Item ..\..\target\release\wallet_ffi.dll build\windows\x64\runner\Release\
.\build\windows\x64\runner\Release\templar_wallet.exe

flutter doctor deve mostrare Visual Studio in verde.

Si distribuisce tutta la cartella Release\. Su un PC senza Visual Studio può servire anche il VC++ Redistributable.

L'installer si crea con Inno Setup 6, dalla radice:

ISCC.exe /DMyAppVersion=<versione> packaging\windows\templar-wallet.iss

Altri dettagli: WindowsBuild.md.

Con uno script solo

Su Linux e Windows uno script fa tutto, con gli stessi passi della build automatica.

Lo script Linux lavora in un'immagine Ubuntu 22.04, qualunque distribuzione tu usi. Altri dettagli: HELPER_BUILDS.md.

Android

Serve l'SDK Android con l'NDK 28.2.13676358 e Flutter con la toolchain Android.

rustup target add aarch64-linux-android x86_64-linux-android
cargo install cargo-ndk
./scripts/build_android.sh --release

Esce un APK per architettura in src/templar_wallet/build/app/outputs/flutter-apk/: app-arm64-v8a-release.apk per i telefoni, app-x86_64-release.apk per l'emulatore.

Su Android restano fuori gli hardware wallet USB: per firmare fuori dal telefono c'è il QR. Per ora anche la release è firmata con la chiave di debug.

Test e sviluppo

cargo test -p templar-core -p wallet-ffi
cargo clippy --workspace -- -W clippy::all
cargo fmt --all
cd src/templar_wallet
flutter analyze --no-fatal-infos
flutter test
flutter run -d macos

I test Rust girano offline, in una decina di secondi. Con flutter run scegli -d macos, -d linux o -d windows.

Queste variabili d'ambiente cambiano alcune scelte all'avvio, senza ricompilare:

Build automatiche

Il workflow build-desktop parte a ogni push su un ramo build-*, a ogni tag v* o a mano. Prima girano i test: una build rotta non arriva ai pacchetti.

macOS e Android si compilano sul Mac del progetto. Linux (Ubuntu 22.04) e Windows sui runner di GitHub: quando i minuti gratuiti finiscono, si usano gli script. Con un tag v* i pacchetti finiscono in una release in bozza.

Demo locale del protocollo

Facoltativa. Gira su regtest, una catena privata sul tuo computer. Nel repository del protocollo lancia:

cargo run -p squid-ops -- up
set -a; . data/regtest/regtest.env; set +a
cargo run -p squid-lend-server

La prima volta up scarica elementsd.

1. Apri il sito. Risponde su http://127.0.0.1:8087.
2. Passa Templar su regtest. Vai in Settings › Network & Sync › Liquid network, scegli Regtest e premi Apply. Il wallet aperto si chiude: riaprilo e sincronizza.
3. Ricevi monete di prova. Sempre nel repository del protocollo: cargo run -p squid-ops -- fund <indirizzo> 1.0, con un indirizzo Liquid regtest di Templar.
4. Collega il wallet. Sul sito premi Collega Templar Wallet. Se il link non apre l'app, incollalo in Settings › Squid Protocol › Open a request. Il resto funziona come in Collegare Templar Lend.

Fonti: README.md, docs/build/, docs/guides/PROTOCOL_CONNECTOR.mdLeggi su GitHub