FreeBank

The desktop app for the FreeBank credit-creation drivechain (BIP 300/301, slot 130): it sets up and runs a FreeBank node beside an eCash node (its own, BitWindow's, or your own), shows its blocks and peers, and is its wallet. It runs on eCash beta or on easynet, a small test network where it sets everything up itself in minutes; a new computer starts there (v0.6.2). Beta's demo mode (v0.4.4 to v0.6.1), which ran with no eCash node through FreeBank's read-only gateway, has ended.

Install

Download from the releases page:

• Ubuntu 22.04+ / Debian 12+: freebank_<version>_amd64.deb. Double-click it and the software installer does the rest (or sudo apt install ./freebank_<version>_amd64.deb).
• Other Linux: the .AppImage. Make it executable (chmod +x), then run it.
• macOS (Apple Silicon and Intel): the .dmg. Drag FreeBank to Applications. The FreeBank node needs macOS 14 or later on Apple Silicon, and macOS 15 or later on Intel. This build is not notarised yet, so the first time macOS will refuse to open it: go to System Settings → Privacy & Security and choose Open Anyway.

Updates

From v0.2.4 on, FreeBank says when a new version is out (and Settings > App updates checks on request). The AppImage and the Mac app update themselves: Update and restart downloads the new version, checks it and opens it. They take an update only when the release's SHA256SUMS carries the release key's signature (below) and the package matches its line there: the same check FreeBank makes before installing the node. The .deb updates with Software Updater once FreeBank's apt repository is set up, or with the new .deb from the releases page. From v0.2.9 the app offers to set the repository up (once, and in Settings > App updates): a yes writes /etc/apt/sources.list.d/freebank.sources through the computer's password prompt, and nothing is added without it; apt purge freebank takes it out again. apt checks the repository's own signing key, which the release workflow holds, not the release key. From v0.2.6 a version reaches the apt repository only after its SHA256SUMS carries the release key's signature, checked again by the workflow that publishes it (.github/workflows/apt.yml).

Verify your download

Each release lists its files' SHA-256 hashes in SHA256SUMS. From v0.2.0 it is signed with the FreeBank release key (SHA256SUMS.sig), the same key that signs the FreeBank node's releases. The key's public half is below and is also published as a signing key on the maintainer's GitHub account (mblowes), so you can check it from two places:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAi2C9Lpi3gHPva6tlbLE+wdF1Cer3uUnmwZYr6SeRjR FreeBank release signing
fingerprint SHA256:1d0zm9Qb9ZtzDnQHH593fgjAkk7nPqMDG79XyWlyeeY

To verify (OpenSSH 8.1 or later):

echo 'freebank-release ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAi2C9Lpi3gHPva6tlbLE+wdF1Cer3uUnmwZYr6SeRjR' > allowed_signers
ssh-keygen -Y verify -f allowed_signers -I freebank-release -n file -s SHA256SUMS.sig < SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS

The packages are built by this repository's GitHub workflow from the tagged source, and GitHub records a signed build attestation for each. Check one with GitHub CLI 2.49 or later, logged in (gh auth login):

gh attestation verify freebank_<version>_amd64.deb --repo mbdrivechains/freebank-app

To review the source, and for what these checks do and don't prove, see VERIFY.md.

Model: your own node, your own keys

Your wallet lives in your own freebankd node, and the app runs it for you.

• A passphrase and 24 recovery words (v0.2.0). The words are standard BIP39 words. The node's wallet key comes from them by BIP85 (the HD-Seed WIF application, index 0), so a BIP85 tool can rebuild it without this app. The app keeps the words only encrypted with your passphrase, and never stores the passphrase.
• Your phone as a remote (v0.2.0). Pair it in Settings > Phone. From v0.6.0 it reaches this computer through public Nostr relays, so nobody hosts the link (phones paired before keep the relay at app.ecxfreebank.com until they pair again). Either way it is end-to-end encrypted: relays only pass sealed messages along. The phone has a daily sending limit, and bigger payments wait for you here. It shows your house notes and the houses, and sends, redeems or demands notes under the same limit (v0.2.5).
• Approve sends on my phone (v0.2.5, opt in). Once this computer's payments in a day come to more than an amount you set, your phone approves the next one with Face ID. It guards the app, not the node: someone with this computer and your wallet passphrase could still use the node directly.
• Your eCash in the app (v0.2.6). Two wallets of FreeBank's own in your eCash node (BitWindow's, or one you run), both from the same 24 words: your eCash wallet, which your passphrase opens for each payment, and a small bidding wallet for bidding on FreeBank blocks, holding only what you move into it. The eCash node only watches them: FreeBank checks and signs every payment itself.
• Several wallets (v0.2.6, with the FreeBank node v0.2.19): more wallets from the same words, or a wallet file you already have. Your phone always uses the main wallet.
• Join my bank (v0.2.8): invite someone with only a phone into a members-only house your wallet runs. This computer keeps a wallet for them, with their own recovery words, until they move their money to a computer of theirs; their phone reaches only that wallet. Custodial while kept here, and said so.
• Advanced: the app can also connect to your own node on another computer, over Tailscale.

First run (desktop)

A new computer starts on easynet (v0.6.2): FreeBank sets it all up in a few minutes, and the easynet faucet gives test coins (below). A computer that has run the app on beta stays on beta.

On a computer that already runs an eCash beta full node and its enforcer (the easiest way is BitWindow in full-node mode on eCash beta), FreeBank finds them, downloads and verifies the newest FreeBank node, asks for the name your blocks carry on the explorer, and starts the node. The Node tab then shows its height against the explorer and its peers. If the node is already running, the app just connects to it.

easynet (v0.5.0), a small public test network on eCash's rules with no value, needs none of that: choose it on the welcome screen or in Settings › Node & connection, and FreeBank downloads easynet's eCash node and enforcer, checks them against the hashes it knows, runs them and syncs in a few minutes. Each network keeps its own wallet, settings and node; switching restarts the app. On easynet, Receive's Get easynet coins (v0.6.1) asks the easynet faucet (https://faucet.ecxfreebank.com) for test coins, and payments link to FreeBank's easynet explorer, https://fbeasy.ecxfreebank.com.

Where FreeBank runs the eCash node and enforcer itself (v0.6.1), it watches them while the app is open: one that stops on its own is noted with what its log said and started again, once an hour at most, and Home says so.

On beta without BitWindow (v0.5.1), setup offers to run eCash beta's node and enforcer itself: it looks for a snapshot first (Ava Chow's at block 965,000, else hers at 935,000), shows the free space against the whole chain (about 890 GB), and can put the blocks on a bigger disk. "Stop and delete" stops it and deletes its chain at any point. Or it can use another computer's eCash node and enforcer, found by IP address or Tailscale name.

Features

Four tabs: Home (balance, Send, Receive, Deposit, Withdraw), Credit (notes, houses, pools, bills), eCash (wallet, bidding) and Node, with Settings behind the gear.

• Connect to a freebankd node via RPC (local / Tailscale / custom)
• Balance and every amount in sECX (ECX on FreeBank; ECX is the eCash chain's coin), the only unit while gold is switched off; transaction history
• Send with Max, a speed choice and the fee shown before you confirm; a receipt with the transaction id and its confirmations up to 3; Speed up while a payment waits; History with CSV export
• Receive with QR codes; coins still arriving show on Home
• Deposit (v0.3.0): at par from the app's eCash wallet, built and signed by the app (FreeBank keeps 0.00001 of each for the block that credits it), with Max and the deposits in flight; or from another eCash wallet (BitWindow)
• Withdraw (v0.3.0): at par through the peg, to the app's eCash wallet or a pasted address, behind a warning (months on mainnet; probably never on the beta), cancellable until it joins a bundle
• Money changer (v0.3.0, Settings › Node & connection): sell sECX for ECX fast, or buy it below par, from a changer whose signed quotes the app checks against its pinned key; you trust it with one order at a time
• Wallet (Settings): passphrase, recovery words, back up, restore from a file or from the words, change passphrase; your wallets (more from the same words, or a wallet file), with a switcher in the header
• Security (Settings): the wallet's passphrase, the node's ports, old unencrypted backups, file permissions and the node program's signature, with red items on Home until fixed
• Phone remote: pair a phone, set its daily limit, allow or refuse bigger payments here; notes and houses on the phone; approve this computer's bigger payments on the phone; invite someone into your house and Scan to pay
• Wallets kept for others (Settings › Phone): the phones invited into your house, their wallets, moving home
• Keep the node running after you close the app
• Notes — hold / mint / send / redeem / demand, per issuing house
• Houses — directory, registration, reserve attestation; open, members-only or redeem-only houses and their members (node v0.2.19)
• Tokens: your house's mint — record its keyset on chain and approve the batch locks it makes, with the house's keys kept here (node v0.2.21; the mint runs on its own server)
• Automatic updates, opt in — Settings › App updates: a signed release fetched, checked and put in place by itself; it runs from the next start
• — the Edinburgh exchange: start or join a round, see each house's net, fund, sign; only the nets are paid, at par (node v0.2.22)

Quick Start

Prerequisites

# Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Node.js 20+
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
# Tauri CLI + Linux webview deps
cargo install tauri-cli
sudo apt install libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf

Development

git clone https://github.com/mbdrivechains/freebank-app.git
cd freebank-app
npm install
cargo tauri dev        # desktop, hot reload
# or, browser/PWA:
npm run dev            # then open http://localhost:5173

Build Release

npx tauri build        # -> src-tauri/target/release/bundle/  (always via the tauri CLI: it bundles the front end)

Releases are built by .github/workflows/release.yml on a vX.Y.Z tag: Linux (.deb, AppImage) on Ubuntu 22.04, one universal macOS app (Apple Silicon and Intel), and a GitHub Release with checksums.

Connect to a node

The wallet needs a running freebankd node with RPC enabled:

# main (RPC 8454); the app reads the node's cookie file, so no password is needed locally
freebankd -daemon

# to reach it from another computer, bind RPC to the Tailscale interface and allow only that client
# (the Security panel then shows RPC as reachable from the network, on purpose):
#   -rpcbind=<tailscale-ip> -rpcallowip=<client-tailscale-ip>

The FreeBank node has two networks — main (RPC 8454) and regtest (RPC 18457); easynet has a build of its own (freebank-easynet, RPC 28454), which the app installs there. Then enter the host/port/credentials in the connect screen.

Browser (PWA) mode + CORS

A browser page can't send RPC directly (CORS). For local development, run the bundled CORS proxy on this computer; it listens on 127.0.0.1 only, answers only the dev origin, and passes on the login the page sends rather than adding one:

python3 proxy.py --rpc-port 8454

Architecture

┌─────────────────────────────────────────┐
│         Svelte Frontend (+ PWA)         │
│ Connect · Notes · Houses · Pools · Bills│
└─────────────────┬───────────────────────┘
     Tauri IPC    │    or  direct fetch (PWA + CORS proxy)
┌─────────────────▼───────────────────────┐
│        Rust Backend (FreeBankClient)    │
│         JSON-RPC client (reqwest)       │
└─────────────────┬───────────────────────┘
                  │ JSON-RPC (local / Tailscale / Tor)
┌─────────────────▼───────────────────────┐
│      freebankd  (drivechain slot 130)   │
│  keys · notes · houses · pools · bills  │
└─────────────────────────────────────────┘

Report a problem

In the app: Settings, then Help. Choose a problem, an idea or a security problem, and either:

• Send to FreeBank: no account needed. The app sends your text, and if you leave the box ticked, the app's version, your system and the node's version. Nothing else: no addresses, balances or logs. Only the FreeBank team reads it.
• Open on GitHub: opens a prefilled issue in your browser for you to check and post. Issues are public.

Security problems go privately: see SECURITY.md.

License

MIT, see LICENSE.