Documentation.

01 — Get started

Download and install.

Pick the file for your system, install it and get past the first-launch warning.

Templar Wallet is an alpha and works only on Bitcoin testnet and Liquid testnet. The coins have no value.

What you need

You need internet to sync and to send: the app connects over TLS to Blockstream's public testnet servers. Opening a wallet and preparing a transaction also work offline.

You don't need an account, an API key or a node of your own.

Vault encryption uses a lot of memory: when you type the password you need at least 2 GB of free RAM.

macOS

The app is not notarized by Apple, so macOS blocks it with “Apple could not verify…” or says it is “damaged”. The cause is the quarantine flag the browser puts on downloaded files.

Method 1, from Terminal. It removes the quarantine and always works, even on macOS 26 Tahoe.

1. Open Terminal. Cmd+Space, type “Terminal”, Return.
2. Unlock the .dmg. Type xattr -d com.apple.quarantine and a space, drag the .dmg into the window and press Return. If it answers No such xattr, that's fine too.
3. Install. Open the .dmg, drag Templar Wallet to Applications and eject the disk.
4. Unlock the app and open it with these two commands. The -r matters: the quarantine is also on the files inside the app.

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

Method 2, up to macOS 15 Sequoia. Drag the app to Applications and open it: macOS blocks it. Close the warning with Done. Then System Settings → Privacy & Security → Open Anyway, and confirm with your Mac password or Touch ID.

Right-click → Open only works up to macOS 14 Sonoma. On Tahoe, if Open Anyway doesn't show up or the app is reported as “damaged”, use Method 1.

Do you also have the install-macos.sh script? Put it next to the .dmg and run bash install-macos.sh: it does Method 1 for you. If it finds an older version it replaces it, and it leaves your wallet data alone.

The first time you use Scan QR, macOS asks for camera access. Allow it, or the preview stays black.

Windows

The recommended file is the installer.

1. Run the setup. SmartScreen says “Windows protected your PC”: choose More info → Run anyway.
2. Choose who it's for. If it asks: Install for all users (needs an administrator) or Install for me only.
3. Select Destination Location. This is the program folder. Every update replaces it.
4. Select Wallet Data Location. This is where wallets, the encrypted vault and the cache live. The suggested folder is %APPDATA%\templar_wallet. It must be outside the program folder: updates don't touch it and it stays even if you uninstall.
5. Install. The desktop icon is optional and off by default (Create a desktop shortcut). Then Install.

The installer adds no services or drivers, and nothing starts with Windows. Only the installer, not the zip, registers the templar:// links of the protocol.

Portable version (zip). Right-click the zip → Extract All… into a real folder. Don't start the app from the zip preview: the data\ folder and the DLLs must sit next to the executable. Then double-click templar_wallet.exe. SmartScreen warns you the same way. Data goes to %APPDATA%\templar_wallet.

Missing VCRUNTIME140.dll or MSVCP140.dll? Install the Visual C++ Redistributable x64 and try again.

Linux

Extract the archive and start the program. Replace the names between < > with the real ones.

tar xzf <downloaded file>.tar.gz
./<extracted folder>/templar_wallet

The folder holds everything. Move it wherever you like, but keep it whole. If libraries are missing, on Debian and Ubuntu:

sudo apt install libgtk-3-0 libudev1 libegl1

On Fedora:

sudo dnf install gtk3 systemd-libs libglvnd-egl

The error version `GLIBC_2.xx' not found means the distribution is too old. Let us know, with the name of the distribution.

Menu entry, optional. It also registers the templar:// links. Open a terminal inside the extracted folder and run:

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

If you move the folder, run the commands again from the new location.

Updating and uninstalling

To update, install the new version over the old one. Your data and wallets stay.

On a computer the data folder stays even after you uninstall. Where it is and how to delete it: Problems and reports.

Source: docs/INSTALLAZIONE.md and docs/guide.mdRead on GitHub

02 — Get started

Verify the download.

A SHA-256 checksum tells you whether the file you have is the one that was published.

The checksums are in SHA256SUMS.txt, attached to every release, one line per file. The testers' package includes it. If there is one next to your download, check it before installing. If the checksum doesn't match, the file is corrupt or is not the one that was published.

1. Put the files together. Save SHA256SUMS.txt in the same folder as the downloaded file.
2. Open a terminal in that folder. Terminal on macOS and Linux, PowerShell on Windows.
3. Run the command for your system, below.

macOS and Linux:

shasum -a 256 -c SHA256SUMS.txt

On Linux sha256sum -c SHA256SUMS.txt works too. OK must appear next to your file. The lines for files you didn't download show an error: ignore them.

Windows, in PowerShell:

Get-FileHash .\<file name> -Algorithm SHA256

Compare the result with that file's line in SHA256SUMS.txt. Upper and lower case don't matter.

You can check the Android APK the same way on a computer, before you move it to the phone.

Which version you have

The right version is shown by the Windows installer, Android's app info and the Finder. The Finder writes it short: for example 0.1.0.15 stands for 0.1.0-alpha.15.

Don't look at Settings → About: because of a known bug it always shows v0.1.0-alpha.1.

Source: docs/RELEASE_NOTES.mdRead on GitHub

03 — Get started

On Android.

How to install Templar Wallet on your phone and what's different from the computer.

You need Android 7.0 or later. The APK is installed by hand, outside the Play Store.

On a phone or tablet always pick the arm64 APK. The x86_64 one is only for Android emulators on Intel or AMD PCs. There is no 32-bit version.

Installing the APK

1. Get the APK onto the phone. Download it on the phone, or copy it over with a cable, a cloud drive or a chat.
2. Open it. Tap the file in the Files app, or in the download notification.
3. Allow the install. The first time, Android blocks it. Tap Settings, turn on Allow from this source and go back.
4. Install. Tap Install. If Google Play Protect warns you, choose More details → Install anyway.
5. Open the app. You'll find Templar Wallet in the app drawer.

The warning shows up because the APK doesn't come from the Play Store.

What's different on the phone

If something goes wrong

• “App not installed”. The phone already has a version signed differently. Check that you have the recovery phrase on paper, then uninstall and try again.
• “Camera unavailable”. Tap Try again, or Open app settings and allow the camera.
• Reporting a problem. On Android the log can't be exported. Send screenshots, the steps you took and roughly what time it was. More in Problems.

Source: docs/ANDROID_PORT.mdRead on GitHub

04 — Get started

Your first wallet.

Create a wallet, write the phrase on paper and receive your first test coins.

Buttons and screens are named here exactly as you see them in the app.

On first launch choose Create new wallet to make a new one. Restore an existing wallet brings one back from its recovery phrase.

Creating a wallet

A one-key wallet on this device takes 8 steps. It takes 7 if the app password already exists.

1. What kind of wallet? One key is the simplest path. Several keys must agree (multisig) asks for more than one signature: see Multisig. Custom rules (policy) is marked Coming soon and can't be picked. Somewhere else — just watch it follows a wallet you keep elsewhere: it shows balance and history, it can't spend.
2. Where do your keys live? On this computer (on the phone, On this device) or On a hardware wallet: see Hardware wallets.
3. Which coins? Bitcoin + Liquid adds Liquid from the same phrase, with nothing extra to write down. Or Bitcoin only. The only network you can pick is Testnet.
4. Protect this app with a password. Only the first time. At least 8 characters, typed twice. Then Start setup.
5. Name & seed length. Give the wallet a name. 24 words is the recommended choice. 12 words is easier to copy by hand.
6. Back up your seed. The words appear only once, numbered. Write them on paper.
7. Verify your backup. The app asks you for three words. Then Confirm & Finish.
8. Wallet created. Choose Get receive address or Open Wallet.

The app password

You need it when the recovery phrase stays on this device, and for every multisig. It encrypts the stored data (Argon2id + XChaCha20-Poly1305). The app asks for it at every start and before sensitive actions. One password covers all your wallets.

Only wallets whose key is on a hardware wallet, and watch-only wallets, can go without it, with Skip — don't encrypt wallet storage. It is not the BIP39 passphrase and it is not part of the recovery phrase.

The recovery phrase

The 12 or 24 words are the wallet. Whoever has them can spend.

• On paper, not on a screen. No photos, files or chats.
• In the exact order. Number the words as you write them.
• Two copies in two different places.
• Never read it out to anyone. Whoever asks for it is trying to steal.

Your first test coins

Open Receive, copy the address and paste it into a faucet. Test coins are free and have no value.

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

The first Liquid sync is a full scan. It can take a few minutes.

Opening, switching, locking

Once you have at least one wallet, the app opens on the Your Wallets list. Each card shows type and coins, for example Software · BTC + Liquid. A multisig shows its threshold, for example 2-of-3. Restore and New Wallet also start from here.

• Unlocking. If Unlock wallet storage appears, type the password in Vault passphrase and press Unlock. If you turned them on, you can use Use Touch ID on the Mac or Use fingerprint on Android.
• Switching wallets. On a computer, the double arrow next to the wallet name takes you back to the list. On the phone, tap the wallet name at the top.
• Locking. On a computer Settings → Security → Lock now, on the phone Settings → Lock now. On a computer there's also the padlock at the bottom of the sidebar and in the wallet list.

Restoring a wallet

1. Open Restore Wallet. From the welcome screen with Restore an existing wallet, from the list with Restore.
2. Seed phrase. Type the 12 or 24 words, separated by a space.
3. Wallet name and Coins. Give it a name and choose Bitcoin + Liquid or Bitcoin only.
4. Restore Wallet. Press the button.

If the app password doesn't exist yet, Encrypt wallet storage opens first so you can create it.

Source: docs/INSTALLAZIONE.mdRead on GitHub

05 — Use the wallet

Receiving and sending.

Where things are, how to give out an address and how to send a transaction.

The window

On a computer, the sidebar is on the left. The open wallet sits at the top: the double arrow goes back to the wallet list.

• WALLET: Dashboard, Send, Receive, Activity, UTXOs. A watch-only wallet has no Send: it can only watch.
• LIQUID: Liquid, LiquiDEX, Peg. Shows up only if the wallet has Liquid. Peg shows up only if the wallet also has Bitcoin.
• SYSTEM: Wallet Info, Settings.

At the bottom of the sidebar a dot shows the status: Synced, Partial sync, Sync Error or Idle. Below it are Sync now and the light or dark theme. When the storage is open there's also the Lock wallet storage padlock, which closes it right away.

The Dashboard sums up the wallet: total value, chart, All / BTC / Liquid filters, currency or sats, the Bitcoin and Liquid cards. The eye hides the amounts. Send and Receive are under the chart. At the top right the TESTNET badge reminds you of the network.

Receiving

Receive gives you a new Bitcoin address (Native SegWit), its QR and Copy address.

• New address makes another one. Use one per payment: reusing an address links the payments together.
• Previous addresses shows the last 8. Show all opens the full list.
• The switch at the top moves you to Liquid. The address is confidential: amounts and assets stay hidden on the chain, and you can reuse it.
• Request an amount adds an amount and an optional note. The QR and the link become a payment link (BIP21) and the button becomes Copy payment link. Share sends it through your system's apps.

After you paste the address somewhere else, check the first and last characters. Once the payment is confirmed, you can name it with Tag on the UTXOs screen.

Sending

Send has six steps, one per choice. Nothing is signed before the last one.

1. Type. Standard transaction creates a new transaction. In a multisig it's called Create a partial transaction. Cosign a transaction adds your signature to a transaction someone else prepared: see Multisig.
2. Network. Bitcoin or Liquid Network, with the available balance. On Liquid you also pick the asset.
3. Inputs. Automatic lets the wallet choose. Manual coin control lets you choose which coins to spend. On Liquid the choice is automatic only.
4. Outputs. Address and amount. From the address field you can scan a QR (on macOS and Android), paste, or use an address from this wallet. MAX spends everything, minus the fee. The arrow next to the unit switches to your currency. Add output adds a recipient. A payment link fills in address and amount together.
5. Fee. Slow, Normal, Fast or Custom (minimum 0.1 sat/vB). On Liquid the fee is fixed and tiny: there's nothing to set.
6. Review. A diagram shows inputs and outputs: recipient, change (CHANGE, it comes back to you) and fee, then the total. In the most common case, Bitcoin with the key stored in the app, Review & sign opens Review transaction. Sign asks for the app password, or Touch ID on the Mac if you turned it on. Broadcast sends the transaction to the network.

In the other cases the sign button changes. On Liquid it's Sign & send. In a multisig it's Sign & continue: if more signatures are needed, you pass the transaction to the cosigners (see Multisig). With a hardware wallet it's Sign on device, with an air-gapped device Export PSBT.

Source: src/templar_wallet/lib/features/Read on GitHub

06 — Use the wallet

Activity, coins and Wallet Info.

The history, the individual coins and the wallet's public keys.

Activity

Activity brings the Bitcoin and Liquid history together, grouped by day, with confirmations, note and value in your currency. You can search by txid or by note. The All / Bitcoin / Liquid filters isolate one chain. The eye hides the amounts.

Open a row for the details: from there you can copy the txid or press View on Explorer.

UTXOs

A wallet doesn't have “a balance”. It has separate coins, the UTXOs. Seeing them one by one lets you choose which to spend.

Each tile is a coin, with its size and its share of the total. At the top you see how many coins you have, how many you've selected and the selected total. On the right are Consolidate and the Notes / List views.

A token is never DUST or WHALE because of its quantity: 500 units of a stablecoin are not 500 sats.

• A coin that just arrived is grey, labelled Incoming. You can't select it until a block includes it.
• The i opens the details: amount, size, confirmations, outpoint, address and Open in explorer.
• Select one or more coins and press Tag to write a note. The note shows up again when you choose which coins to spend.
• Consolidate merges several coins into one. It works only on Bitcoin and with at least 2 coins. It costs one transaction, but makes the later ones cheaper.

Wallet Info

At the top is the wallet's identity: name, network, master fingerprint, derivation path and script type. Below are the public descriptors. Each row has a button to copy it and one for the QR.

• For other apps: Copy descriptor bundle, Export JSON and Show QR export a watch-only copy for another program. The app names Sparrow, Specter, BlueWallet, Jade and SeedSigner.
• If the wallet doesn't have Liquid yet, the Liquid Network card offers Enable Liquid. With a Jade the button is Add Liquid from my Jade.
• The XPUB m/84'/1'/0' is the key of the single-signature wallet. It is not a cosigner key.
• To join someone else's multisig, a single-signature wallet has the Use this wallet as a cosigner card: the Bitcoin key (BIP48) and the Liquid key (BIP87), each with copy and QR. If your keys are on a hardware wallet, you read them from the device during the multisig setup. See Multisig.

Source: CHANGELOG.mdRead on GitHub

07 — Use the wallet

Security and settings.

How the wallet locks, what's in Settings and the habits that protect the phrase.

Locking and unlocking

When the storage is locked, Unlock wallet storage appears. Type the app password and press Unlock. If you turned on fingerprint unlock, you can also use Use Touch ID on the Mac or Use fingerprint on Android.

To lock: the padlock at the bottom of the sidebar, or Lock now in Settings. Locking wipes the decrypted keys from memory.

Auto-lock locks by itself. On the phone it counts the time in the background. On a computer it also counts the time with no keyboard or mouse use. When it kicks in, you're back at the wallet list and need the password again. It works only if the app password is set.

On a computer, Lock now and Auto-lock are in Settings → Security. On the phone they're in the Settings list.

Fingerprint unlock

On the Mac: Settings → Security → Touch ID unlock. Your finger opens the storage at startup and after Lock now.

Below it appears Also confirm with Touch ID, on by default. Your finger then also replaces the password for signing, sharing wallet data and showing the phrase. The password always works.

On Android: Biometric unlock, in the Settings list. Your finger opens the storage. To sign and to show the phrase you still need the password.

If you change the fingerprints registered in the system, the unlock turns itself off. Windows and Linux have no fingerprint unlock.

The Security section

On a computer it's Settings → Security. On the phone the same items are in Settings → Vault & backup.

The Settings sections

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

On the phone, a single list: Wallet info · Biometric unlock · Auto-lock · Vault & backup · Lock now · Theme & units · Reduce effects · Nodes & explorers · Squid Protocol · Auto-sync · About.

• Network & Sync. Sync at startup. Liquid network Testnet. Regtest is only for developers with a local node. The Bitcoin server is fixed, the explorers can be changed. Tor is announced, not ready yet.
• Squid Protocol. Connected sites and signing requests: see Templar Lend.
• Appearance. Wallet name and color, currency, BTC or sats, theme Dark, Light or System. In a multisig there's Cosigner labels: names and colors of the keys, saved only on this device. Language has no effect yet: the app is in English only.
• About. Shows v0.1.0-alpha.1 by mistake: the real version is 0.1.0-alpha.15. Source code leads to the GitHub repository.

Good habits

• The phrase is on paper, checked at least once with Verify backup.
• The app password is not the phrase. You need both.
• Check the address before you send, even on testnet.
• Don't sign what you don't understand.
• Take your time with updates: backup first.

Source: docs/RELEASE_NOTES.mdRead on GitHub

08 — Advanced

Multisig and co-signing.

An M-of-N multisig spends only when M different keys have signed.

The keys can sit on different devices or with different people. Templar prepares the transaction, collects the signatures and broadcasts it.

Creating the wallet

1. Type. What kind of wallet? → Several keys must agree (multisig), then Which coins?.
2. App password. If there isn't one yet, the app asks for it. A multisig requires it.
3. Threshold. In Choose your threshold you pick the name, the signatures required (M) and the total keys (N, from 2 to 9). With I hold one of these keys here on, the app creates your key here and has you back it up. With it off, you import all the keys.
4. Keys. In Import the keys each key can have a name, an icon and a color. Then choose where it comes from.
5. Create. Review & create → Create Wallet.

Every key is checked before use. A key with a mainnet path is rejected.

In the Dashboard the Keys card shows a ring, one slice per key in its color, and the rule Any M of N keys can sign.

Bitcoin and Liquid together

One wallet, two chains. Each cosigner gives two keys: the Bitcoin one (BIP48) and the Cosigner Liquid key (BIP87). If the key is in this app or on a Jade, the app reads the second one by itself.

• A Ledger, Trezor, Coldcard or KeepKey key makes the wallet Bitcoin only. Among hardware wallets, only the Jade signs on Liquid.
• A Bitcoin-only multisig can't be extended to Liquid. Create it again with the same keys: same Bitcoin addresses, same funds.
• The same keys give the same Liquid wallet on every device.

To join someone else's multisig, open one of your single-key wallets: Wallet info → Use this wallet as a cosigner. The two keys are there, each with copy and QR. You can share them: neither of them can spend.

To follow a multisig without signing: Somewhere else — just watch it → Build from cosigner keys.

Starting a spend

1. Prepare. Send → Create a partial transaction, then sign with your key.
2. Pass it around. Co-signatures needed opens. The SIGNATURE QUORUM chart has one slice per key and shows who has already signed. The transaction goes out as an animated QR, with Copy PSBT or with Save .psbt file (Share .psbt on the phone).
3. Collect. Paste signed copy → Add signature. Or Scan signed QR (on macOS and Android), or the signed file. Each copy merges with the others, it doesn't replace them. A copy with no new signatures is rejected, and the app tells you why.
4. Broadcast. At quorum: Review & Broadcast → Review signed transaction → Broadcast.

On Liquid the transaction is a PSET. The steps are the same, QR included.

A key marked as USB hardware wallet signs from the computer: Sign with USB hardware wallet → Sign on device. See Hardware wallets.

Signing someone else's spend

1. Open. Send → Cosign a transaction. In WHICH CHAIN? choose Bitcoin or Liquid.
2. Load. Paste, File or Scan QR (on macOS and Android), then Load & Inspect.
3. Check. Amounts and addresses. If something doesn't add up, Decline.
4. Sign. Sign & Export. On a computer there's also Sign with device.
5. Hand it back. Show QR, Copy PSBT or the file. On Liquid the button says Copy PSET.

Source: docs/guides/LIQUID_MULTISIG.mdRead on GitHub

09 — Advanced

Hardware wallets.

The key stays on the device: Templar prepares the payment, the device approves it.

This is optional. If you only use software wallets, skip this chapter.

Which devices

On Windows and Linux, if HWI is missing, the device screen shows the HWI toolkit required panel. Install HWI downloads the official version and checks its SHA-256. Ledger and Jade don't need it.

Before you plug it in

• Ledger. Unlock it, open the Bitcoin Testnet app (not “Bitcoin”) and close Ledger Live.
• Jade. Up-to-date firmware and testnet turned on, from Options → Settings → Device → Enable Testnet. Over USB, close Blockstream Green: only one app at a time can use the port. Keep the computer online: PIN unlock needs it.
• Jade via QR. Unlock it first with Blockstream's app: Templar doesn't relay the PIN.

Creating the wallet

1. Where the keys live. When asked Where do your keys live? choose On a hardware wallet.
2. Cable or camera. When asked How does your device connect? choose By cable (USB) or By camera (air-gapped QR). On Android there's only the camera.
3. Follow the steps. Via USB: Connect your device → Confirm what this device will hold → Name your wallet. Via QR: Choose your device → Export descriptor → Paste descriptor & name. At the end, Pairing summary shows the status of each network and the checks that were run.

Signing a payment

• Via USB. In Send press Sign on device. The app accepts only the device with this wallet's fingerprint. First the device has you confirm one of the wallet's addresses. Then it shows outputs and fee, and you approve there.
• Via QR. Press Export PSBT and the app shows the transaction as an animated QR. Scan it with the device and approve. Bring the signed copy back with Scan signed QR, with a .psbt file or by pasting it. Before Broadcast the app shows you what it really pays. Bitcoin only.

QR scanning is there on macOS and Android. On Windows and Linux the scan buttons don't appear: paste the copy or load the file.

Liquid: Jade via USB only

Jade is the only hardware wallet that signs Liquid, and only by cable. If you choose Bitcoin + Liquid, the setup reminds you: For Liquid, the device must be a Blockstream Jade. With other devices the wallet starts out Bitcoin only.

Did you create a Bitcoin-only Jade wallet? Open Wallet Info and press Add Liquid from my Jade. Templar opens the Jade only when you sign, so Blockstream Green can use it between one payment and the next.

Linux: USB permissions

If the Device permissions needed panel appears, press Fix device permissions: it asks for your password once. Then unplug the device and plug it back in. The first time, also log out and log back in.

Source: docs/guides/HARDWARE_TESTING.mdRead on GitHub

10 — Advanced

Liquid: assets, LiquiDEX and Peg.

What the Liquid side of the wallet does, beyond receiving and sending.

Liquid is a Bitcoin sidechain. It has a block every minute, confidential transactions and assets that anyone can issue.

These screens appear only if the wallet has Liquid. To add it to a software wallet: Wallet Info → Liquid Network → Enable Liquid. It uses the same recovery phrase, so there's nothing else to write down. For a Jade, see Hardware wallets.

Assets

The Liquid screen lists the assets you hold, for example L-BTC. An asset's detail shows the Asset ID with the Copy ID button and, when they're known, Ticker, Precision and Domain.

• Issue Asset creates a new asset.
• Reissue issues more units of an asset whose reissuance token you hold.
• Burn destroys units of the asset. There's no going back.

Issuing an asset

1. Define asset. Name, ticker, precision (0 to 8) and domain, all required. They're permanent: after issuance they can't be changed.
2. Initial supply. How many units to issue. Turn on Create reissuance token if you want to be able to issue more later. Without a token the supply stays fixed forever. If you lose the token, you can't reissue anymore.
3. Review & sign. Read everything again and press Sign & Issue.
4. The result. The app shows the Asset ID, the TxID and, if you created one, the reissuance token ID. If Domain proof required appears, publish the file it shows on your domain: it's needed to register the asset in the Liquid testnet explorer.

LiquiDEX

An order book of atomic swaps: two people exchange assets in a single transaction. Make offer publishes a proposal, Take accepts one, Import proposal loads a proposal you received. Offers marked MAINNET · VIEW ONLY can only be viewed: the wallet signs only on testnet.

Peg

Peg-in moves BTC to Liquid as L-BTC. Peg-out does the opposite. The destination address is already filled in with one from this wallet.

The peg needs a Bitcoin side. In a Liquid-only wallet, Peg can't be used.

Source: docs/INSTALLAZIONE.mdRead on GitHub

11 — Advanced

Connecting Templar Lend.

Templar Wallet signs the steps of your loans on a Templar Lend site. The keys stay in the wallet.

The site builds the loan transactions. Templar shows them to you and signs only after you confirm. The site broadcasts them, never the wallet.

In the app the protocol is called Templar Lend. The links start with templar://.

Before you start

• Install it the right way. On Windows use the installer: the portable zip doesn't register templar:// links. On macOS, copying the app to Applications from the .dmg is enough. On Linux you need the commands below.
• Set the app password. The app asks for it before every signature. On a Mac with Touch ID turned on, your finger may be enough.
• Use a software wallet with Liquid turned on. Hardware, watch-only and multisig wallets can't connect yet.
• Use the site's network. The wallet starts on Liquid Testnet. You change the network in Settings › Network & Sync › Liquid network. Changing it closes the open wallet: reopen it and sync.

Linux only. From a terminal opened in the extracted folder, these commands create the menu entry and register templar:// links. If you move the folder, run them again.

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

Connecting the wallet

1. Start from the site. On the Wallet page press “Connect Templar Wallet”.
2. Templar opens. The Connect wallet screen appears. If the wallet storage is locked, it asks for the app password first.
3. Choose the wallet. Templar only offers the ones that fit.
4. Read what the site receives. A watch-only view of Liquid: it sees balance and history, it can't spend. The escrow key m/2121'/1'/0', a separate account used only in loan contracts. A receive address and the wallet name.
5. Confirm. Tick the sentence, press Share with … and enter the app password.
6. Go back to the site. Wallet connected appears. Open in browser takes you back to the page, which updates by itself.

Signing a loan step

A signature is needed when the loan opens, for installments and repayment, and in case of default and liquidation.

1. Open the request. On the loan page press “Sign with Templar Wallet”.
2. Compare the two columns. On the left, What … says: role, amounts and duration as the site tells them. On the right, What "…" reads: what the wallet reads in the transaction itself.
3. Sign. Tick “I compared the site's summary with the wallet's reading…”, press Sign and send to … and enter the password.
4. Done. Signature sent appears. When every party has signed, the site broadcasts the transaction. The loan page shows its id.

At the bottom of the column you'll find the fee, the network and the signatures collected so far. Under the two columns, the Request box shows the Request id.

Settings › Squid Protocol

You can also get there with one tap from the Liquid panel of the Dashboard.

• Status: the network the wallet is ready for, and Change network.
• Open a request: paste a templar:// link or, where there's a camera, scan its QR. It's the fallback when the site doesn't open Templar.
• Connected sites: who sees one of your wallets read-only, and what they received.
• Signing history: the last 50 requests, with the outcome. Clear history empties it.
• Preferred wallet for Squid requests: the wallet that answers requests and is offered first. The password and the tick are still needed.
• How it works: the summary in three steps.

If the link doesn't open the wallet

1. Copy the link. On the site, right-click the button and copy the link address.
2. Paste it into Templar. In Settings › Squid Protocol › Open a request, then press Open.

To make Templar open by itself: on Windows reinstall with the installer, on Linux run the commands in Before you start.

Messages you may see

They're all expected, and none of them puts your coins at risk.

Limits of this alpha

• Only software wallets connect.
• The wallet doesn't reconcile the two columns by itself: the comparison is up to you.
• The wallet has no loan screens and doesn't use mainnet.
• A remote site must use https.
• The signing history is kept on this device only. The loans live on the site and on the blockchain.
• The wallet's developers haven't tested link registration on Windows and Linux yet. Pasting the link always works.
• On Android, connecting to sites isn't ready yet.

The Regtest network is only for developers with a local node.

Source: docs/guides/PROTOCOL_CONNECTOR.md · for testers: docs/guide.mdRead on GitHub

12 — Help

Problems and reports.

The most common problems, where the data lives and how to send us a useful report.

Installing and starting

While using it

Where the data lives

You can see the folder in use in Settings › Security › Storage. On Android the section is called Vault & backup.

Starting from scratch

Close the app. Then, on macOS:

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

On Linux:

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

On Windows, in PowerShell:

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

On Android: the phone's Settings › Apps › Templar Wallet › Storage › Clear data.

Reporting a problem

The repository is public: open an issue in the Issues on GitHub. If you don't, write to whoever sent you the build or in the testers' group. Include:

• operating system and version;
• which build you installed, from the name of the downloaded file: About in the app shows v0.1.0-alpha.1 by mistake;
• what you were doing, what you expected and what happened;
• a screenshot, if you can.

For a problem with Templar Lend, add the Liquid network, the loan reference, the Request id and a screenshot of the signing screen showing both columns.

Attach the log

On a computer the log is logs/templar.log in the data folder, plus templar.log.1 if it's there. To copy it to the Desktop, on macOS:

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

On Linux:

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

On Windows the log is in %APPDATA%\templar_wallet\logs, or in the folder chosen in the installer. On Android it can't be exported: send screenshots, the steps you took and roughly when the problem happened.

To see errors as they happen, on macOS start the app from Terminal:

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

On Linux, start ./templar_wallet from a terminal opened in the extracted folder. On Windows the app writes nothing to the console: copy the exact error text or take a screenshot.

Known limits

• Testnet only, no path to mainnet.
• The app is in English only. About shows the wrong version.
• Camera QR scanning only on macOS and Android. Paste and File work everywhere.
• No USB on Android. With a hardware wallet, Liquid works only with a Jade over USB.
• Trezor, Coldcard, KeepKey and BitBox02 need HWI on Windows and Linux. They don't work on macOS.
• No screen to raise the fee (RBF) of a transaction already sent.
• The app password can't be changed or removed.
• LiquiDEX is experimental. The Peg is simulated.
• Wallets with custom rules (policy) aren't available yet.
• One instance of the app at a time.
• No Apple notarization, no Authenticode certificate, an APK from outside the Play Store: on first launch macOS, Windows and Android show a warning.

Source: docs/INSTALLAZIONE.mdRead on GitHub

13 — Developers

Source code and builds.

What's in the repository and how to build Templar Wallet yourself.

What's inside

The documentation in the repository

Start from docs/README.md: it tells you where to find what.

Before you build

The app is made of two pieces that travel together: the Rust library and the Flutter package. If the library is missing at startup, the release app stops on an error screen.

Each system is built on that system: Flutter desktop doesn't cross-compile. You need:

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

The commands run from the repository root, where Cargo.toml is. The first Rust build compiles about 500 crates and takes a few minutes.

macOS

You need Xcode with the command line tools (xcode-select --install).

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

Nothing else is needed: an Xcode Run Script phase builds libwallet_ffi.dylib and puts it inside the app.

Want your build to run on Intel Macs too? Add the targets first: rustup target add x86_64-apple-darwin aarch64-apple-darwin.

For a DMG, run ./scripts/make_dmg.sh from the root. The file ends up in dist/.

Linux

On Debian or Ubuntu, 22.04 or later, install the packages:

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

Then build, copy the library next to the executable and run:

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

You ship the whole bundle/ folder. The computer it runs on needs GTK 3, and a glibc no older than the one on the computer that built it.

Fedora and more details: LinuxBuild.md.

Windows

Install these first:

• Visual Studio 2022 with the Desktop development with C++ workload. VS Code alone is not enough.
• Git for Windows.
• Rust with rustup-init.exe, toolchain stable-x86_64-pc-windows-msvc.

You don't need OpenSSL. In PowerShell, from the repository root:

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 must show Visual Studio in green.

You ship the whole Release\ folder. On a PC without Visual Studio you may also need the VC++ Redistributable.

The installer is built with Inno Setup 6, from the root:

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

More details: WindowsBuild.md.

With a single script

On Linux and Windows one script does everything, with the same steps as the automatic build.

The Linux script works inside an Ubuntu 22.04 image, whatever distribution you use. More details: HELPER_BUILDS.md.

Android

You need the Android SDK with NDK 28.2.13676358, and Flutter with the Android toolchain.

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

You get one APK per architecture in src/templar_wallet/build/app/outputs/flutter-apk/: app-arm64-v8a-release.apk for phones, app-x86_64-release.apk for the emulator.

USB hardware wallets are left out on Android: to sign off the phone there's QR. For now the release build is also signed with the debug key.

Tests and development

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

The Rust tests run offline, in about ten seconds. With flutter run choose -d macos, -d linux or -d windows.

These environment variables change some choices at startup, without rebuilding:

Automatic builds

The build-desktop workflow runs on every push to a build-* branch, on every v* tag, or by hand. The tests run first: a broken build never reaches the packages.

macOS and Android are built on the project's Mac. Linux (Ubuntu 22.04) and Windows on GitHub's runners: when the free minutes run out, the scripts take over. With a v* tag the packages land in a draft release.

Local protocol demo

Optional. It runs on regtest, a private chain on your computer. In the protocol repository, run:

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

The first time, up downloads elementsd.

1. Open the site. It answers at http://127.0.0.1:8087.
2. Switch Templar to regtest. Go to Settings › Network & Sync › Liquid network, choose Regtest and press Apply. The open wallet closes: reopen it and sync.
3. Get test coins. Still in the protocol repository: cargo run -p squid-ops -- fund <address> 1.0, with a Liquid regtest address from Templar.
4. Connect the wallet. On the site press Connect Templar Wallet. If the link doesn't open the app, paste it into Settings › Squid Protocol › Open a request. The rest works as in Connecting Templar Lend.

Sources: README.md, docs/build/, docs/guides/PROTOCOL_CONNECTOR.mdRead on GitHub