Website · Downloads · Getting started · Security · Roadmap
Northbound is a self-custodial lightweight desktop wallet for TrueNorth.
The desktop application is built with Rust and Dioxus. It creates addresses,
stores encrypted wallet secrets, and signs transactions on the user's device.
A separate Rust and Axum API reads public blockchain data from truenorthd and
broadcasts transactions that have already been signed by the wallet.
Northbound is an independent community project, not an official TrueNorth wallet. It has not received an independent security audit. Do not use it with significant funds.
- Create or restore a wallet with 12 recovery words.
- Keep multiple named wallets on one device, each with its own password.
- Encrypt the local wallet file with Argon2id and XChaCha20-Poly1305.
- Derive native TrueNorth P2QRH receiving and change addresses locally.
- Display balances and transaction history supplied by the wallet server.
- Construct and review the recipient, amount, and fee before signing.
- Sign P2QRH transactions locally and broadcast the signed transaction.
- Change the local wallet password without changing the recovery phrase.
Recovery words, private keys, passwords, and transaction signing remain in the desktop wallet. They are never sent to the Northbound server.
The current version relies on its configured server for address activity, UTXOs, transaction history, fee estimates, chain height, transaction status, validation, and broadcasting. A dishonest or unavailable server cannot sign a transaction, but it can hide or delay blockchain information, provide misleading history, suggest a poor fee, or refuse to broadcast.
See SECURITY.md for the current security boundary and ROADMAP.md for the planned move toward Electrum-style local verification.
| Directory | Purpose |
|---|---|
| wallet/ | Dioxus desktop wallet and local signing |
| server/ | Axum API backed by truenorthd |
| shared/ | JSON request and response types |
| indexer/ | SQLite chain index, pending snapshots, and wallet queries |
| truenorth-rpc/ | Shared daemon RPC transport and decoding |
| scripts/ | Local development and packaging helpers |
Use Wallets in the header to create, restore, switch, or remove wallets. Switching locks the current wallet. Open wallet folder opens the storage folder in Finder, Windows Explorer, or the Linux file manager.
Each wallet is an encrypted <name>.json file. Development wallets live in
.local/wallets/<network>/; release wallets use the operating system's local
data folder under io.github.nova9.northbound/wallets/<network>/.
The previous single wallet.json is not imported automatically; restore that
wallet with its recovery words. Removing a wallet permanently deletes its local
file after a backup confirmation and an exact name check. It does not move funds
or remove other copies of the file.
Install a Rust toolchain, then download a TrueNorth release and start a local regtest node:
./scripts/download-truenorth.sh
./scripts/regtest.sh startCreate and fund the development wallet, send coins, or stop the node:
./scripts/regtest.sh create-wallet funding
./scripts/regtest.sh get-address funding
./scripts/regtest.sh generate-coins funding 101
./scripts/regtest.sh send-coins funding <receiving-address> [amount]
./scripts/regtest.sh stopMining takes a Core wallet name and defaults to 101 blocks; sending
defaults to 10 NORTH. get-address generates a fresh receiving address for the
named wallet. Address, mining, and sending commands automatically load an
existing wallet when needed. Development
commands share the persistent data directory .local/truenorth/.
Run the server and wallet in separate terminals:
cargo run -p server
cargo run -p walletRun the automated tests:
cargo test --workspaceRun the P2QRH checks against an isolated TrueNorth Core regtest node:
./scripts/test-truenorth-integration.shDevelopment downloads and integration tests use the Core release pinned in
TRUENORTH_VERSION. All local regtest scripts use the shared
binaries in .local/truenorth-bin/<version>/<platform>/. The integration script
calls the downloader, reuses cached releases, and removes its temporary chain
on exit. Downloads are verified against the release's SHA-256 checksum.
To download another release without changing the project's selected version:
./scripts/download-truenorth.sh 30.5.2Versions with a v prefix are also accepted. Update TRUENORTH_VERSION to select
which release the development and integration scripts use. Deployment versions
under server/devops/ are managed independently.
See test conventions and commands for the shared unit-test layout
and isolated wallet, indexer, and server regtest suites.
The server starts the SQLite indexer,
follows reorganizations, and serves wallet data through indexed queries. It uses
.local/indexer/chain.sqlite by default; set TRUENORTH_INDEX_DATABASE to change
the path. Stop any standalone indexer writing that file before running the server.
GET /ready reports catch-up and freshness; wallet data returns a retryable error
until confirmed and pending snapshots are ready. Fee estimation, validation, and
broadcast remain connected directly to the daemon.
Run the complete indexed API checks with an isolated node:
./scripts/test-truenorth-integration.sh serverBuild the mainnet desktop wallet for the host OS:
./scripts/build-wallet.sh # Linux AppImage or macOS app
./scripts/build-windows.ps1 # Windows MSI, run in PowerShellPublishing a GitHub release, including a pre-release such as v0.1.0-rc.1,
runs the macOS, Windows, and Linux release workflows. Commit the workflows before creating
the tag. They build the mainnet wallet and attach these files with SHA-256
checksums to the release:
Northbound-<tag>-macos-arm64.zip: ad-hoc signed Apple Silicon app.Northbound-<tag>-windows-x64.msi: Windows x64 installer.Northbound-<tag>-linux-x64.AppImage: Linux x64 application.
Draft releases do not trigger builds. To build without publishing a release,
select macOS release build, Windows release build, or Linux release build
in Actions, then choose Run workflow;
download the files from that run's artifacts. Manual builds use
dev-<short-commit> in the filename.
macOS builds do not yet have an Apple Developer ID
signature or notarization.
Linux builds use Ubuntu 24.04. The workflow installs GTK/WebKitGTK dependencies
and checks that the packaged AppImage opens a window under Xvfb before uploading
it. This launch check does not replace testing wallet operations on a Linux desktop.
For local Ubuntu 24.04 builds, install the same packages listed in
the Linux workflow, Rust with the
llvm-tools-preview component, and Dioxus CLI 0.7.10, then run
./scripts/build-wallet.sh.
To launch a downloaded Linux package:
chmod +x Northbound-<tag>-linux-x64.AppImage
./Northbound-<tag>-linux-x64.AppImageIf FUSE is unavailable, run it with APPIMAGE_EXTRACT_AND_RUN=1.
Mainnet builds use the local server by default. Set the server URL explicitly when building a wallet that should connect to a hosted server:
NORTHBOUND_API_BASE_URL="https://wallet-api.example.com" \
cargo build -p wallet --release --no-default-features --features mainnetBuild and publish Docker images after setting DOCKERHUB_REPOSITORY:
./scripts/build-image.sh server [version]
./scripts/build-image.sh truenorthdThe server version defaults to its Cargo package version, including workspace
inheritance; the daemon version comes from server/devops/truenorthd/VERSION.txt.
Both commands push the built image.
APP_SLUG and DOCKER_PLATFORMS remain available as environment overrides.
Northbound is under active development. Before a general release, the project still needs broader TrueNorth regtest coverage, Linux desktop testing, signed release artifacts, independent review, and a clearly documented public server deployment.
Bug reports and technical review are welcome. Please report security problems privately and never include recovery words, private keys, passwords, or live RPC credentials.
Northbound is available under the MIT License, the same license used by TrueNorth Core.