Just last week, somebody filed a bug against Tauri. Their app pointed a webview at an external URL via tauri::WebviewUrl::External, and invoke() started failing with "Origin header is not a valid URL." They were certain they'd configured everything correctly. The docs didn't help. The framework was just rejecting their commands.

The bug is real and the cause is specific: the embedded webview doesn't add an Origin header on cross-origin requests, and the Referer is empty, so Tauri's IPC scope checker can't verify the request came from an allowed origin and refuses to dispatch it. To debug it, you have to know what the IPC bridge actually does — not what invoke() looks like, but how the request travels from JavaScript through the OS-native webview into Rust and back.

Most Tauri tutorials show you invoke('hello') and stop. That's enough to ship a hello-world; it's not enough to debug #15190-class bugs, design a security boundary, or make architectural choices that survive contact with production. This post reads the Tauri 2 IPC bridge end to end, traces a real Bitcoin wallet's commands across it, and shows the security pattern that makes Tauri worth picking over Electron in the first place.

By the end you'll know:

• What invoke() actually does, with line references to the Tauri source
• How to design an IPC surface where private keys never leak to the frontend
• When Tauri 2's capability system blocks a command and when it doesn't
• The difference between the Tauri and Electron threat models, in one paragraph
• The five mistakes that bite real teams using Tauri in 2026

The example throughout is a Bitcoin wallet from my book Rust Blockchain: A Full-Stack Implementation Guide — 18 commands, two halves, a real working architecture you can clone and run. But the lessons generalize to any Tauri app: a password manager, an enterprise SSO dashboard, an ML inference UI. Anywhere a Rust backend has secrets and a webview UI shouldn't.

1. What Tauri IPC actually is

Tauri is a desktop-app shell. Your application's UI runs in the operating system's native webview (WebView2 on Windows, WKWebView on macOS, WebKitGTK on Linux). Your application's logic runs in a Rust process. The two halves live in the same OS process, but the boundary between them is enforced — JavaScript inside the webview can only reach Rust through commands that Rust has explicitly registered.

The mechanism for crossing that boundary is inter-process communication (IPC), even though it's technically intra-process. The naming is conventional, not literal.

A request from React to Rust looks like a remote procedure call:

1. React calls invoke('cmd_name', { arg: 'value' })
2. Tauri serializes the arguments to JSON
3. The message is delivered through the webview's host-bridge channel
4. Tauri dispatches to a Rust function registered with #[tauri::command]
5. The Rust function returns a Result<T, E>
6. Tauri serializes the result to JSON
7. React receives the resolved promise

That's the whole protocol. It looks like fetch, except there's no network — the bridge is a message channel inside one OS process — and the "server" is a Rust function that has memory-safe access to your filesystem, your secrets, and your databases.

The diagram above is the architecture for bitcoin-desktop-ui-tauri, the admin UI from Chapter 17 of the book. A React component asks useQuery() for the latest blockchain state. The query function calls commands.getBlockchainInfo(). That function wraps a single invoke() call. On the Rust side, a #[tauri::command] handler receives the call, asks Tauri's dependency injection for the shared AppState, builds an HTTP client (AdminClient) from the shared bitcoin-api crate, hits the blockchain API at :8080, and returns JSON. React gets the response. The component re-renders.

The whole roundtrip is about ~150 lines of Rust and TypeScript split across four files. We'll walk all four.

2. The IPC bridge under the hood

This section is the longest, because most existing Tauri content stops where this section begins. Read it once and you'll understand invoke() better than 95% of people shipping Tauri apps today.

2.1 Where the bridge lives in the source

The Tauri repository at github.com/tauri-apps/tauri contains the IPC implementation in two places:

• crates/tauri/src/ipc/ — the high-level command dispatch (the invoke() you call, the #[tauri::command] macro, Channel, InvokeBody, InvokeResolver)
• crates/tauri-runtime-wry/src/webview.rs — the wry-backed implementation of the message bus that talks to the actual platform webview

When you call invoke('cmd_get_balance', { addr: '1A1zP1...' }) in TypeScript, here's what happens:

Step 1 — JavaScript-side serialization. The @tauri-apps/api/core package's invoke function bundles the command name and the arguments object, then posts a message to the webview's host bridge. On Windows that's chrome.webview.postMessage. On macOS it's webkit.messageHandlers.ipc.postMessage. On Linux/GTK it's a custom URI scheme handler. Tauri abstracts these three platform mechanisms behind a single Webview::eval and Webview::on_window_event API so user code never has to think about them.

Step 2 — message arrives in Rust. The Tauri runtime receives the platform message and routes it to crates/tauri/src/ipc/invoke.rs, where the Invoke struct is constructed. This struct holds the command name (a string), the payload (a JSON value), and a resolver — the channel back to the webview that will eventually carry the response.

Step 3 — capability check. Before dispatching, the IPC layer consults the access control list (ACL) loaded from the capabilities/*.json files in your project. If the calling window's capability set doesn't include the requested command, the request is rejected with a permission error. We'll come back to this in §6.

Step 4 — argument deserialization. Tauri uses serde and the #[tauri::command]-generated wrapper code to deserialize the JSON payload into the typed parameters of your Rust function. Each parameter is matched by name to a key in the JSON object. Type mismatches become deserialization errors that propagate back to the JavaScript caller as Error objects, not panics.

Step 5 — your function runs. The Rust function executes. Async commands execute on tauri::async_runtime (Tokio underneath). The function can take a State<T> parameter, which Tauri's dependency injection populates from values you registered with tauri::Builder::manage().

Step 6 — result serialization and return. The function's return value (Result<T, E> where both T and E are serde::Serialize) is serialized back to JSON and posted through the resolver back to the JavaScript caller. The TypeScript invoke() Promise resolves with the decoded result, or rejects with the decoded error.

2.2 What this means for your application code

The Rust side of an IPC handler is genuinely small. From the book's admin UI, here is the canonical handler — cmd_get_blockchain_info, in bitcoin-desktop-ui-tauri/src-tauri/src/commands/blockchain.rs:

use crate::api::service::BitcoinApiService;
use tauri::State;
use serde_json::Value;

use crate::AppState;

#[tauri::command]
pub async fn cmd_get_blockchain_info(
    state: State<'_, AppState>,
) -> Result<Value, String> {
    let response = BitcoinApiService::get_blockchain_info(
        state.base_url.clone(),
        state.api_key.clone(),
    )
    .await?;

    serde_json::to_value(&response)
        .map_err(|e| e.to_string())
}

Three things to notice. First, the #[tauri::command] macro is doing a lot of work — it generates a wrapper that handles JSON deserialization, dispatches to your function, and serializes the result. You don't write any of that.

Second, the state: State<'_, AppState> parameter is dependency injection. You registered AppState once in main() via .manage(app_state), and Tauri populates this parameter on every call. No globals, no thread-local statics, no manual locking — it's the same idiomatic pattern as axum::extract::State or actix_web::web::Data.

Third, the function returns Result<serde_json::Value, String>. The String error type is conventional in Tauri because everything that crosses the bridge has to be Serialize, and String is the cheapest serializable error. Production code typically uses a custom error enum that derives Serialize, but the pattern is the same.

The TypeScript side is even smaller, in bitcoin-desktop-ui-tauri/src/commands.ts:

import { invoke } from '@tauri-apps/api/core';
import { BlockchainInfo, BlockSummary, ApiResponse } from './types';

export async function getBlockchainInfo(): Promise<ApiResponse<BlockchainInfo>> {
    return invoke<ApiResponse<BlockchainInfo>>('cmd_get_blockchain_info');
}

A one-line wrapper around invoke(). The string 'cmd_get_blockchain_info' is the same name the Rust function exports through tauri::generate_handler!. The TypeScript generic argument <ApiResponse<BlockchainInfo>> tells the compiler what shape the resolved value will have — but note this is a TypeScript-only assertion, not a runtime guarantee. If the Rust side returns a differently-shaped object, TypeScript won't notice until something reads a missing property at runtime.

We'll come back to this gap when we discuss tauri-specta.

2.3 The tauri::generate_handler! macro

Every command you want to expose has to be listed in a single tauri::generate_handler! call inside main(). The book's admin UI does this with all 22 of its commands:

fn main() {
    tauri::Builder::default()
        .manage(AppState {
            base_url: "http://127.0.0.1:8080".to_string(),
            api_key: std::env::var("BITCOIN_API_ADMIN_KEY")
                .unwrap_or_else(|_| "admin-secret".to_string()),
        })
        .invoke_handler(tauri::generate_handler![
            cmd_get_blockchain_info,
            cmd_get_latest_blocks,
            cmd_get_blocks,
            cmd_get_block_by_hash,
            cmd_get_mining_info,
            cmd_generate_to_address,
            cmd_get_health,
            cmd_get_liveness,
            cmd_get_readiness,
            cmd_get_mempool,
            cmd_get_mempool_transaction,
            cmd_get_transactions,
            cmd_get_address_transactions,
            cmd_create_wallet_admin,
            cmd_get_addresses_admin,
            cmd_get_wallet_info_admin,
            cmd_get_balance_admin,
            cmd_send_transaction_admin,
            cmd_set_base_url,
            cmd_set_api_key,
            cmd_get_config,
            cmd_check_connection,
        ])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Two gotchas worth flagging immediately:

• Calling invoke_handler more than once silently overwrites. Only the last call wins. If you split command registration across multiple files thinking each one will register its own handlers, only one set will actually be live. Pass every command to a single generate_handler! call.
• A command not listed in generate_handler! fails silently from the frontend. The Rust function still compiles; it's just unreachable through IPC. From JavaScript you get a generic "command not found" error at runtime, with no compile-time warning. The list above is a runtime contract — keep it audited.

2.4 Async, runtimes, and Send

Async commands run on tauri::async_runtime, which is a Tokio multi-threaded runtime under the hood. Two consequences follow.

First, everything in your async command's environment must be Send, because the runtime can move the future across worker threads at any .await point. Standard std::sync::MutexGuard is intentionally not Send (this is what protects you from cross-thread deadlocks in non-async code), so you cannot hold one across an .await. Use tokio::sync::Mutex, whose MutexGuard is Send. If you guess wrong, you get a runtime panic — there's no compile-time check that catches it.

Second, State<T> references and AppHandle work differently at .await boundaries. A State<'_, T> borrow is short-lived and shouldn't be held across an .await. If you need to own data across an await point, extract the data you need out of State before the first .await, or use AppHandle (which is Clone and owned) to access state inside async closures. The book's wallet uses both: synchronous reads use State, while long-running async tasks pass an owned AppHandle.

2.5 The ergonomic gap: stringly-typed invoke()

If you've made it this far, you've noticed something: the link between invoke('cmd_get_balance') and cmd_get_balance in Rust is a string. TypeScript doesn't know the command exists until the Promise resolves at runtime. There's no autocomplete on command names, no compile-time check that you spelled the command correctly, no signal that you passed the wrong argument shape.

This is where the community has done the work that the official docs haven't done, in the form of tauri-specta. It's a library that generates TypeScript bindings from your Rust commands at build time, using the Specta crate for type introspection. The same cmd_get_balance function, with #[tauri::command] augmented by #[specta::specta], becomes a typed export the TypeScript side can import:

import { commands } from './bindings'; // generated by tauri-specta

const balance: u64 = await commands.cmdGetBalance({ addr: '1A1zP1...' });

The compiler now knows the command exists, knows it takes an addr: string, and knows it resolves to a u64. Rename the Rust function and the TypeScript build breaks immediately. Ship the wrong argument shape and the TypeScript build breaks immediately. The Tauri 2 docs don't show this. Production teams use it almost universally.

If you take only one practical recommendation from this post, it's add tauri-specta to any Tauri 2 project as soon as you have more than ~five commands. The official invoke() is great for prototypes and tutorials. For real applications, the typed bindings are the difference between bugs at compile time and bugs at runtime.

3. Tauri vs Electron — design and security, not vibes

The "Tauri vs Electron" comparison appears in every Rust desktop discussion in 2026, and most of those comparisons are vibes-based. Here is the comparison grounded in design and security, with citations to each project's own documentation.

(Bundle and memory figures are widely-cited community measurements from 2026 comparative analyses; I'm not claiming these as my own benchmarks. They are useful as orders-of-magnitude context, not as precision numbers.)

The headline trade-off is this. Electron buys you the most mature desktop-app ecosystem in existence in exchange for shipping an entire copy of Chromium with every app and giving the JavaScript side default access to the user's filesystem. Tauri buys you a tenth of the bundle size and a permission system that's secure by default, in exchange for asking your team to write the backend in Rust and giving up most of npm.

Pick Electron when:

• Your team doesn't know Rust and doesn't have time to learn it
• The application doesn't hold secrets, doesn't need a small footprint, and ships only on desktop
• You depend on a Node.js library (or an Electron-specific plugin) that has no Rust equivalent
• Examples that match: VS Code, Slack, Discord, Atom

Pick Tauri when:

• Your application holds secrets — wallets, password managers, API keys, encryption keys
• Your application is positioned on lightweight or low-resource — productivity tools that compete with Electron incumbents (AppFlowy vs Notion is the canonical example)
• You need iOS or Android support from the same codebase
• Your business logic is already a Rust crate, and the desktop client is just the latest consumer (Spacedrive's spacedrive-core is the textbook case)
• Examples that match: Cap.so, AppFlowy, Spacedrive, Padloc, Hoppscotch

For the rest of this post we're firmly in Tauri territory: the example application holds private keys, has a strict threat model, and wants the smallest reasonable attack surface.

4. A working example: a Bitcoin wallet that keeps keys safe

This is where the post's example earns its keep. The book's bitcoin-wallet-ui-tauri crate is a Bitcoin wallet — 18 IPC commands, an encrypted SQLite database, and a strict invariant: private keys never cross the IPC boundary. The React UI never touches them. JavaScript can ask Rust to sign a transaction; it cannot ask Rust to hand over the key that does the signing.

This pattern generalizes beyond blockchain. A password manager has the same threat model. So does an enterprise dashboard that holds API tokens. So does an ML inference UI that holds proprietary model weights. The wallet is a concrete instance of a class of secret-holding desktop apps; once you understand its IPC surface, you understand all of them.

The diagram above shows the wallet's IPC surface. The left side is what React can ask for. The right side is what only Rust knows. The orange dashed bar between them is the IPC boundary, and the design choice is that nothing on the right side has a path to the left side, even in principle.

4.1 The wallet's state structure

The wallet's AppState looks like this:

use tauri::State;
use std::sync::RwLock;

#[derive(Clone, serde::Serialize, serde::Deserialize)]
pub struct WalletState {
    pub current_wallet: Option<String>,
    pub wallets: Vec<String>,
    pub database_password: String,
}

#[derive(Clone)]
pub struct AppState {
    pub wallet: RwLock<WalletState>,
    pub base_url: String,
}

Notice what WalletState doesn't contain. There is no private_key field. There is no seed_phrase field. There is no keypair. The struct that's available to IPC handlers via State<AppState> does not contain anything secret. Private keys live elsewhere — loaded from an encrypted SQLite database into a SecretKey value that's used inside a single function call and dropped before the function returns.

The database_password field is a deterministic hash of \(USER and \)HOME, so the same user on the same machine always unlocks the same wallet database — but the password itself is derived locally and never shipped to the frontend.

4.2 The 18 commands the wallet exposes

These are all 18 commands the wallet exposes across IPC, in the order they're registered with generate_handler!:

Look at what isn't in this list. There is no cmd_get_private_key. There is no cmd_export_seed_phrase. There is no cmd_decrypt_database. The IPC surface itself does not offer a path for keys to escape Rust. Even if a malicious npm package compromised the React UI tomorrow and an attacker had complete control of the JavaScript side, the worst they could do is ask Rust to sign things — they could not extract the keys to sign things on their own machine.

This is the security pattern. The IPC layer is your API surface; design it so that the operations you need are present and the operations that would leak secrets are intentionally absent.

4.3 Three IPC patterns the wallet demonstrates

Pattern 1 — synchronous query. A read-only command that takes no parameters or simple parameters and returns a value:

#[tauri::command]
pub async fn cmd_get_balance(
    state: State<'_, AppState>,
    addr: String,
) -> Result<u64, String> {
    let wallet = state.wallet.read().map_err(|e| e.to_string())?;
    // ... query the chain, sum UTXOs, return total
}

The TypeScript side calls it the same way as a fetch:

const balance: number = await invoke<number>('cmd_get_balance', { addr });

React Query wraps this with caching:

export function useBalance(addr: string | null) {
    return useQuery({
        queryKey: ['balance', addr],
        queryFn: () => addr ? commands.getBalance(addr) : Promise.resolve(0),
        enabled: !!addr,
        staleTime: 10000,  // balances refresh every 10s
    });
}

Pattern 2 — async write that mutates state. A command that changes something — broadcasts a transaction, creates a wallet — and that the rest of the UI needs to know about:

#[tauri::command]
pub async fn cmd_send_transaction(
    state: State<'_, AppState>,
    to: String,
    amount: u64,
) -> Result<String, String> {
    // build the tx, sign it (in place, with the key never leaving Rust),
    // broadcast to the network, return the txid
}

The React side uses useMutation and invalidates relevant cached reads on success:

const sendTx = useMutation({
    mutationFn: (vars: { to: string; amount: number }) =>
        commands.sendTransaction(vars.to, vars.amount),
    onSuccess: () => {
        queryClient.invalidateQueries({ queryKey: ['balance'] });
        queryClient.invalidateQueries({ queryKey: ['transaction-history'] });
    },
});

After a successful send, the cached balance is marked stale so the next render fetches fresh data. This is React Query's bread and butter — it's also the right design for any IPC bridge that needs to keep client-side caches consistent with server-side mutations.

Pattern 3 — security-bounded operation. This is the wallet's distinctive pattern. cmd_sign_transaction takes a transaction draft (recipient address, amount, fee), signs it inside Rust, and returns the signed bytes. The private key is loaded from the encrypted database, used inside a single function call, and dropped before the response is serialized back to the frontend.

#[tauri::command]
pub async fn cmd_sign_transaction(
    state: State<'_, AppState>,
    draft: TransactionDraft,
) -> Result<SignedTransaction, String> {
    let wallet = state.wallet.read().map_err(|e| e.to_string())?;
    let sk = load_secret_key(&wallet.database_password)?;
    let signed = sign_in_place(draft, &sk)?;
    // sk is dropped here, before the function returns
    Ok(signed)
}

The crucial observation: there is no path through this function that surfaces sk to the caller. The function returns SignedTransaction, which is just bytes — no key material in it. The IPC surface offers signing but does not offer key extraction. A malicious frontend can spam-call this function but cannot exfiltrate the underlying key.

This is the pattern that separates a Tauri-style desktop wallet from a browser extension wallet. In a browser extension, the "frontend" and the "backend" share the same JavaScript runtime, so isolating keys requires a much weaker form of process boundary. In Tauri, the IPC bridge is a hard boundary enforced by the operating system's webview, and the Rust side controls what crosses it.

4.4 The shared-crate architecture

One more architectural insight worth its own subsection. The book has four implementations of the wallet UI: a pure-Rust Iced version (Chapter 18), this Tauri-with-React version (Chapter 19), and a parallel admin UI in both frameworks (Chapters 16 and 17).

All four call the same underlying Rust crate: bitcoin-api, which exposes AdminClient and WalletClient types that talk to the blockchain over HTTP. The Tauri commands are thin wrappers — they receive State<AppState>, call into the bitcoin-api crate, and return JSON. The Iced UIs do the same calls from Message handlers. The framework choice is decoupled from the application logic.

Why does this matter? Because Tauri is a UI shell, not an application framework. If your team's business logic is already a reusable Rust crate, swapping the desktop shell from Electron to Tauri (or from one Rust UI framework to another) doesn't require refactoring anything except the layer that makes API calls. Spacedrive's open-source codebase demonstrates this at production scale: their spacedrive-core crate is a pure Rust library; the Tauri 2 desktop app, the CLI, and the Spacebot service are all thin consumers of that one crate.

If you're considering Tauri but worried about lock-in, this architecture pattern is your insurance policy. Keep the application logic in plain Rust crates; treat the Tauri layer as the desktop adapter; you can rip out the Tauri layer in a weekend if you ever need to.

5. The capability system: security at the IPC boundary

We promised in §2 that we'd come back to the capability system. Here it is.

In Tauri 1, every IPC command was reachable from every window by default. You opted out of dangerous APIs by editing an allowlist. Tauri 2 inverts this: nothing is reachable by default, and you grant access by declaring capabilities in JSON files under your project's capabilities/ directory.

A capability declaration is a small JSON document that names a window or webview, names the permissions it should have, and optionally scopes those permissions further (which filesystem paths, which HTTP endpoints, which IPC commands). When a window calls invoke(), the Tauri IPC layer consults the capabilities for that window before dispatch — if the requested command isn't covered by a capability grant, the call is rejected before the Rust handler is ever invoked.

For the wallet, a minimal capability file granting access only to the wallet commands looks something like this:

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "wallet-main",
  "description": "Capabilities for the main wallet window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    {
      "identifier": "wallet:allow-balance-and-history",
      "allow": [
        "cmd_get_balance",
        "cmd_get_addresses",
        "cmd_get_transaction_history",
        "cmd_send_transaction",
        "cmd_sign_transaction"
      ]
    }
  ]
}

The windows: ["main"] line means this capability only applies to the window labeled main. If your app has a tray-icon window or a notification overlay window, those windows have their own capability files with their own permission grants. Per-window scoping is the design feature that makes the capability system useful — you can give the main interactive window the broad permissions it needs while keeping the tray-icon window restricted to a single command.

Three things this design buys you:

A clear audit story. A security reviewer can read your capabilities/ directory and immediately see what each window can ask Rust to do. There is no hidden middleware, no ambient permissions. The capability file is the authorization policy.

Defense in depth. Even before the ACL check, the IPC surface itself is limited (we saw this in §4 with the wallet's commands). Even if a misconfigured capability accidentally grants too much, the only attack surface available is the commands you actually wrote. The capability layer is the second gate, not the only gate.

A red-team analysis you can write down. Suppose tomorrow a malicious npm package compromised your React build. The attacker now controls the JavaScript running in the webview. What can they do? The answer is: exactly what the capability file allows, no more. They can call cmd_send_transaction if cmd_send_transaction is in the allowlist. They cannot reach files outside the configured filesystem scope. They cannot make HTTP requests to arbitrary servers. They especially cannot extract private keys, because no command exists that would return one.

This story is impossible to write for an Electron app with the default configuration, because Electron's default is "the renderer process can do anything the main process can do." You can lock Electron down — contextIsolation, sandbox, nodeIntegration: false, custom IPC validators — but these are opt-in, ad hoc, and easy to misconfigure. Tauri 2's capability model is opt-in by inversion: secure by default, dangerous by explicit grant. For an application that holds secrets, this default is the entire reason to pick Tauri.

6. Five things that bit me

A practical section for readers who are about to ship Tauri 2 in production. These are the recurring pitfalls — drawn from the Tauri repo's issue tracker, Discord conversations, and the experience of building the book's two Tauri apps.

1. invoke_handler only registers the last call. If you call .invoke_handler(generate_handler![cmd_a]) and then .invoke_handler(generate_handler![cmd_b]), only cmd_b is registered. There is no compile-time warning. Pass every command to a single generate_handler! invocation. If the list gets unwieldy, group commands into modules and re-export them, but the final list lives in one macro call.

2. Standard MutexGuard is not Send — your async command won't compile or will panic. When you hold a std::sync::MutexGuard across an .await point, the Rust compiler refuses to make the future Send, and Tauri requires async-command futures to be Send. Use tokio::sync::Mutex and tokio::sync::RwLock, whose guards are Send. The book's wallet uses std::sync::RwLock for synchronous code and switches to Tokio's primitives whenever a lock is held across an await.

3. Event listeners need cleanup. Tauri's frontend event API (listen('event-name', handler)) registers a JavaScript callback for a Rust-emitted event. If the React component that registered the listener unmounts without calling the unlisten function, the callback stays alive — and if a new instance of the component mounts, you now have two callbacks reacting to the same event. The book's React hooks always store the unlisten promise and clean up in useEffect return:

useEffect(() => {
    const unlistenPromise = listen('block-mined', (event) => {
        // ...
    });
    return () => {
        unlistenPromise.then(fn => fn());
    };
}, []);

4. Setup-hook events fire before listeners attach. If you call app.emit('startup') from the Tauri setup hook in Rust, none of the React components are mounted yet, so the event has no listeners and is dropped. The pattern is to wait for a "ready" handshake from the frontend before emitting startup events. The frontend mounts, calls invoke('cmd_frontend_ready'), and the Rust side then emits the startup events with confidence.

5. The official invoke() is stringly-typed; production teams use tauri-specta. This was the recommendation in §2.5 and it's worth saying again as a pitfall. Without tauri-specta, every IPC call is a string lookup, every argument is unknown until you assert the type, and every rename of a Rust function is a runtime bug waiting to happen. Add tauri-specta early. The migration cost from invoke() to typed bindings is small if you do it before you have hundreds of invoke() call sites.

Bonus issue worth knowing about: Origin header handling on external URLs (issue #15190) is the bug we opened the post with. If you set the webview to an external URL via tauri::WebviewUrl::External, the embedded webview may not include an Origin header on IPC requests, and the scope checker rejects them. The current workaround is to use tauri::WebviewUrl::App with an internal HTML shim that loads the external content, or to disable origin checking for that specific window (which has security trade-offs of its own).

7. Where Tauri is heading

The Tauri team has been public about what comes after 2.x. Three directions worth knowing about:

Servo as an alternative webview engine. Tauri currently uses each platform's native webview, which means inheriting that webview's bugs and feature set. Servo — Mozilla's experimental Rust-native browser engine — is being actively developed as an alternative renderer. If it lands, you'll be able to ship Tauri apps that don't depend on the host operating system's webview, eliminating a class of cross-platform inconsistency bugs at the cost of bundling a (still much smaller than Chromium) browser engine. Watch Tauri Discussions and the Servo project for status updates.

WASI plugin architecture. Native Tauri plugins are written in Rust and compiled into the application binary. A WASI-based plugin model would let plugins ship as .wasm files that the Tauri runtime loads at startup, with capability constraints enforced by the WebAssembly sandbox. This unlocks third-party plugins that the user can install at runtime without recompiling their Tauri app.

Mobile maturity. Tauri 2.0 added iOS and Android targets, but the mobile experience still has rough edges: Xcode tooling integration is immature, many plugins don't yet support mobile, and the docs lag behind desktop. Expect the 2.x line to keep filling these gaps.

For the Bitcoin wallet specifically, the most interesting near-term direction is mobile. A Tauri-on-iOS Bitcoin wallet that shares its Rust core with the desktop wallet — same bitcoin-api crate, same signing logic, same secret handling — is a single-codebase mobile + desktop app of a kind that's been historically very expensive to build. The shared-crate architecture from §4.4 is what makes that affordable.

8. Summary

The five takeaways:

1. invoke() is a JSON-RPC over the platform webview's host bridge — you can read the implementation in crates/tauri/src/ipc/ and it's not much code. Understanding it makes debugging IPC bugs tractable.
2. Design your IPC surface so secrets never have a path out. The Bitcoin wallet's 18 commands include cmd_sign_transaction but not cmd_get_private_key. The capability system gates command access; the API surface itself bounds what's even askable.
3. Tauri is a UI shell, not an application framework. Keep your business logic in plain Rust crates. The framework choice becomes a swap, not a rewrite.
4. Use tauri-specta for any non-trivial app. The default invoke() is stringly-typed; production teams add tauri-specta for compile-time safety on every command call.
5. Tauri vs Electron is a threat-model question. If your app holds secrets, the capability-based opt-in permission model is the entire reason you'd pick Tauri. If your app doesn't hold secrets and you have an Electron-only npm dependency, Electron is fine.

If you want the working code that goes with this post — all 22 admin commands, all 18 wallet commands, the React frontends, the Rust backends, the capability files, and the Iced parallel implementations — clone the companion repository on GitHub. The wallet alone is ~1,400 lines of Rust and ~1,200 lines of TypeScript, and you can have it building locally in fifteen minutes.

If you want the long form — 33 chapters, 768 pages, taking the same blockchain from the Bitcoin whitepaper to a deployed Kubernetes cluster — that's the book.

Sources and further reading

Tauri primary sources

• Inter-Process Communication — official Tauri 2 IPC docs
• Calling Rust from the Frontend — #[tauri::command] reference
• Capabilities — capability declarations
• Permissions — permission identifiers and sets
• Security model overview — Tauri 2's security architecture
• State Management — State<T>, RwLock, tokio::sync choices
• Tauri 2.0 Stable Release announcement — what 2.0 changed

Tauri repo issues and discussions cited

• #15190 — Origin header bug with external URL
• #6889 — Custom protocol IPC break
• Discussion #5690 — IPC Improvements
• Discussion #5413 — Setup events not captured
• Discussion #5194 — Listen-twice prevention

Type safety

• tauri-specta repository
• tauri-specta documentation

Production examples

• Awesome-Tauri — curated Tauri apps and resources
• Spacedrive launch + architecture — the spacedrive-core shared-crate pattern at production scale

Comparative analyses

• Tauri vs Electron 2026 — PkgPulse
• Tauri vs Electron 2026 — Tech Insider
• Tauri v2 vs Electron, 6-month real-world experience

The book and its companion repository

• Rust Blockchain: A Full-Stack Implementation Guide — Amazon | Gumroad (PDF + EPUB) | Leanpub (pay what you want)
• github.com/bkunyiha/rust-blockchain — the companion source code, including both Tauri apps and the shared bitcoin-api crate

Available now on Amazon (paperback + Kindle + hardcover), Gumroad (PDF + EPUB), and Leanpub (pay what you want).

Free resource: Clone the Starter Template

The shape that works: four jobs, four submodules, four dozen lines of public API. That's the entire bitcoin/src/crypto/ directory in this reference implementation — wrapping libraries that have been audited harder than anything you could write yourself: ring (BoringSSL-backed) for SHA-256 and ECDSA, secp256k1 (the same library Bitcoin Core ships) for Schnorr and EC arithmetic, sha2 (pure Rust) for Taproot-style hashing, bs58 for address encoding.

This post walks through each of those four jobs — what the cryptography actually does, why the API is shaped the way it is, and the specific Rust idioms that make it harder to use the layer wrong than to use it right. By the end, if you've written some Rust but never touched cryptography, you should be able to read every line of this layer and know why each one exists.

The dependencies, for reference — these are the only crypto-related crates the layer pulls in:

# bitcoin/Cargo.toml (relevant excerpt)
[dependencies]
ring        = "0.17"   # SHA-256 + P-256 ECDSA (BoringSSL-backed)
secp256k1   = { version = "0.31", features = ["rand", "global-context"] }
                       # secp256k1 curve + Schnorr (libsecp256k1 wrapper)
sha2        = "0.10"   # Pure-Rust SHA-256 (used for taproot_hash)
bs58        = "0.5"    # Base58 / Base58Check encoding
rand        = "0.9"    # OS-backed RNG, supplied to sign_schnorr_with_rng

Four crates. Roughly three thousand lines of Rust on top of them. That's the entire perimeter of cryptographic code you need to keep correct.

The Four Jobs

A blockchain implementation needs cryptography to answer three practical questions: how to name things, how to prove authorization, and how to represent these ideas as bytes humans can copy/paste. Split that into four submodules:

The mod.rs is short on purpose — it defines what the rest of the codebase is allowed to call, and nothing else:

pub mod address;
pub mod hash;
pub mod keypair;
pub mod signature;

pub use address::{base58_decode, base58_encode};
pub use hash::{sha256_digest, taproot_hash};
pub use keypair::{get_schnorr_public_key, new_key_pair, new_schnorr_key_pair};
pub use signature::{
    ecdsa_p256_sha256_sign_digest,
    ecdsa_p256_sha256_sign_verify,
    schnorr_sign_digest,
    schnorr_sign_verify,
};

Because bitcoin/src/lib.rs re-exports the crypto module (pub use crypto::*;), call sites elsewhere in the crate look like crate::sha256_digest(bytes) — short, visible, easy to grep for, and with the cryptographic decisions still centralized in one place.

Hashing: The Workhorse

A hash function is a one-way compression function that turns any input bytes into a fixed 32-byte output ("digest"). In a blockchain, hashes do four jobs: they identify transactions, they link blocks together, they drive proof-of-work, and they let nodes agree on what they're looking at without having to compare megabytes of state.

A blockchain relies on five SHA-256 properties:

• Determinism: same input, same output — every node, every machine, forever.
• Preimage resistance: given h = SHA256(m), recovering m is computationally infeasible.
• Second-preimage resistance: given m, finding a different m' with the same hash is infeasible.
• Collision resistance: finding any two distinct inputs with the same hash is infeasible — the cost is ~2¹²⁸ hash evaluations, not 2²⁵⁶, because of the birthday paradox (the fastest collision attack only needs to search half the bits before two random outputs collide on average).
• Avalanche: flipping 1 input bit flips ~50% of output bits.

That last property is the one that does the heavy lifting for tamper-evidence. If a node receives a block claiming to be the Genesis but with one byte modified, the hash won't just be "close" to the expected hash — it will be utterly different, and the chain link from the next block won't point to it anymore.

The implementation is twelve lines:

use ring::digest::{Context, SHA256};

pub fn sha256_digest(data: &[u8]) -> Vec<u8> {
    let mut context = Context::new(&SHA256);
    context.update(data);
    let digest = context.finish();
    digest.as_ref().to_vec()
}

Reach for ring because it's a thin wrapper over BoringSSL — the same C cryptographic core that runs production traffic at Google. The Context API is incremental (you can call update repeatedly with chunks), which is useful for hashing large data without materializing it all in memory. The blockchain's hash sites don't need that, but the cost of supporting it is zero.

Where hashing shows up

The sha256_digest function gets called in three structurally important places:

Transaction IDs. A transaction's identity is the hash of its content. But there's a chicken-and-egg problem: the hash depends on the bytes, and the ID is one of the fields in the transaction. The fix is to hash a trimmed copy with the ID field cleared:

fn hash(&mut self) -> Result<Vec<u8>> {
    let tx_copy = Transaction {
        id: vec![],          // exclude from the bytes being hashed
        vin: self.vin.clone(),
        vout: self.vout.clone(),
    };
    Ok(sha256_digest(tx_copy.serialize()?.as_slice()))
}

Then store the result into the transaction's id field. The hash of any transaction is fully determined by its inputs and outputs — change any byte of either, and the ID changes.

Proof-of-work loops. PoW is "try nonces until the hash is below a target." It's just sha256_digest running in a loop, hammering through nonces:

loop {
    let candidate_bytes = serialize_header(&header_with_nonce);
    let hash = sha256_digest(&candidate_bytes);
    if hash_int(&hash) < target {            // big-endian compare against
        return (nonce, hash);                // a 256-bit difficulty target
    }
    nonce = nonce.wrapping_add(1);           // wrap on overflow, never panic
}

hash_int interprets the 32-byte digest as a 256-bit big-endian integer so it can be compared against the difficulty target — small numerical value means many leading zero bits, which means many failed hashes had to come before this one. wrapping_add(1) is the Rust-specific touch: integer overflow on nonce += 1 would panic in debug builds, which is fatal in a tight CPU loop. Wrapping arithmetic is well-defined and correct here because the absolute value of the nonce doesn't matter — only that it changes between attempts.

The asymmetry here is what makes PoW work: mining requires millions of hash evaluations on average; verification requires one. Every receiving node validates the same nonce-hash pair with a single sha256_digest call.

Block-level transaction commitment. A block needs a single fingerprint of all its transactions. Bitcoin uses a Merkle tree — a binary tree where each leaf is a transaction hash, each internal node is the hash of its two children concatenated, and the root is the single hash committing to every transaction in the block. The benefit of the tree shape is that you can prove a single transaction is in the block by showing only log₂(n) sibling hashes (the path from leaf to root), which is what light clients and SPV wallets rely on. A teaching codebase can get away with a simpler hash-of-concatenated-IDs:

pub fn hash_transactions(&self) -> Vec<u8> {
    let mut txhashs = vec![];
    for transaction in &self.transactions {
        txhashs.extend(transaction.get_id());
    }
    crate::sha256_digest(txhashs.as_slice())
}

This is one of the explicit simplifications worth flagging. It costs O(n) bytes to compute (vs. O(n) hashes for a Merkle tree, but with Merkle's per-tx inclusion proofs as the upgrade path). For a teaching codebase that's the right trade-off; for byte-for-byte Bitcoin compatibility, build a real Merkle root.

There's also a second SHA-256 entry point, taproot_hash, that uses the pure-Rust sha2 crate instead of ring. The output is identical — same algorithm, different implementation — and the split is historical: this codebase started with ring for general hashing, then added sha2 when Taproot-style address derivation got wired in and a no-C-dependency path was needed in the hot path. In production you'd probably consolidate; for a learning codebase, having both paths visible is instructive.

Note: Bitcoin Core uses double SHA-256 (SHA256(SHA256(x))) for many identifiers. This codebase uses single SHA-256 for clarity. That's consensus-relevant — for byte-for-byte Bitcoin compatibility, the hashing rules have to be aligned. Call it out explicitly rather than hiding it.

Signatures: Schnorr Over secp256k1

A digital signature is a mathematical proof that someone who knows a private key approved a specific sequence of bytes. Without revealing the key. It provides three things: authenticity ("the holder of this key authorized this message"), integrity ("if the message changes, verification fails"), and unforgeability ("you can't make a valid signature without the key").

Bitcoin historically used ECDSA over secp256k1. Modern Bitcoin (Taproot, BIP-340) uses Schnorr over the same curve. Schnorr signatures are smaller (always 64 bytes vs. ECDSA's variable 70–72), have provably stronger security under standard assumptions, and they support signature aggregation — multiple signers can produce one combined signature, which is what makes Taproot's spending paths so powerful.

For a new implementation, pick Schnorr as the primary path. ECDSA helpers can stick around for contrast (and to show how ring's API differs).

Signing

use secp256k1::{Keypair, Secp256k1, SecretKey};

pub fn schnorr_sign_digest(
    private_key: &[u8],
    message: &[u8],
) -> Result<Vec<u8>> {
    let secp = Secp256k1::new();

    let secret_key_array: [u8; 32] = private_key
        .try_into()
        .map_err(|_| BtcError::TransactionSignatureError(
            "Invalid private key length".to_string()
        ))?;
    let secret_key = SecretKey::from_byte_array(secret_key_array)?;

    let message_hash = sha256_digest(message);
    let keypair = Keypair::from_secret_key(&secp, &secret_key);
    let mut rng = rand::rng();
    let signature = secp.sign_schnorr_with_rng(
        &message_hash,
        &keypair,
        &mut rng,
    );

    Ok(signature.as_ref().to_vec())
}

A few things worth noticing in those twenty lines:

1. Length validation is enforced by the type system, not by an if statement. private_key.try_into() returns Result<[u8; 32], _> — if the slice isn't exactly 32 bytes, the error maps to a BtcError and the function returns early. There is no path through this function where a 31-byte or 33-byte input gets silently accepted.

2. The message is hashed inside the signing function. Schnorr conceptually signs a 32-byte digest, not arbitrary-length data. So always feed in SHA256(message). Callers can pass whatever bytes they want — for transactions, that's the trimmed-copy hash — and the function does the right thing.

3. Randomness is supplied at sign time. Schnorr is technically deterministic in the BIP-340 spec, but the secp256k1 crate's API takes an RNG and uses it to build a nonce. Pass rand::rng(), which delegates to the OS. Never seed your own RNG for cryptographic operations — the OS entropy pool is better than anything you can build in user space.

4. The signature is always 64 bytes, regardless of the message size or the key. Predictable output sizes simplify storage, serialization, and on-the-wire framing.

Verification

pub fn schnorr_sign_verify(
    public_key: &[u8],
    signature: &[u8],
    message: &[u8],
) -> bool {
    let secp = Secp256k1::new();

    let public_key_array: [u8; 33] = match public_key.try_into() {
        Ok(arr) => arr,
        Err(_) => return false,
    };
    let pk = match PublicKey::from_byte_array_compressed(public_key_array) {
        Ok(pk) => pk,
        Err(_) => return false,
    };

    // Schnorr verifies against an x-only (32-byte) public key,
    // not the 33-byte compressed form.
    let pk_bytes = pk.serialize();
    let xonly_array: [u8; 32] = match pk_bytes[1..33].try_into() {
        Ok(arr) => arr,
        Err(_) => return false,
    };
    let xonly_pk = match XOnlyPublicKey::from_byte_array(xonly_array) {
        Ok(pk) => pk,
        Err(_) => return false,
    };

    let message_hash = sha256_digest(message);

    let signature_array: [u8; 64] = match signature.try_into() {
        Ok(arr) => arr,
        Err(_) => return false,
    };
    let sig = schnorr::Signature::from_byte_array(signature_array);

    secp.verify_schnorr(&sig, &message_hash, &xonly_pk).is_ok()
}

The verifier's signature-input parsing is paranoid by design — every malformed input path returns false, never a panic. A malicious peer can ship a transaction with a 17-byte signature or a 5-byte public key, and the verification function will reject it cleanly without taking the node down. Returning false for a malformed signature is equivalent to "the signature doesn't verify," which is correct: an unparseable signature is not a valid signature.

The conversion from compressed (33-byte) to x-only (32-byte) public key is Schnorr-specific. Compressed public keys carry a 1-byte parity prefix (0x02 or 0x03) plus 32 bytes of X coordinate. Schnorr verification only needs the X coordinate — Y is implicit — so the prefix gets stripped.

How signing and verification thread through the transaction code

Signing and verifying transactions ties everything together. Both sides reconstruct the same trimmed copy of the transaction, hash it, then sign or verify against that hash. The trick is reconstruction: the verifier doesn't have the signer's draft, just the final transaction with signatures attached, but they can rebuild the exact bytes that were signed by clearing the signature fields and copying in each input's pub-key hash.

A short detour on field naming, because the next code listing reuses one field for two purposes and that's worth flagging up front. A TXInput has both a pub_key field and a signature field. During signing/verification, the input's pub_key field is briefly repurposed to hold the previous output's pub_key_hash so it gets included in the hashed bytes — this is a Bitcoin convention going back to the original whitepaper, and it's how the verifier knows which output's lock the signature was meant to satisfy. After hashing, the field gets cleared again so the bytes don't leak into later inputs' hashes within the same transaction.

The signing side, called once per input:

async fn sign(
    &mut self,
    blockchain: &BlockchainService,
    private_key: &[u8],
) -> Result<()> {
    let mut tx_copy = self.trimmed_copy();

    for (idx, vin) in self.vin.iter_mut().enumerate() {
        // 1. Find the previous transaction being spent from.
        let prev_tx = blockchain
            .find_transaction(vin.get_txid())
            .await?
            .ok_or_else(|| BtcError::TransactionNotFoundError(
                "Previous transaction not found".to_string(),
            ))?;

        // 2. Splice the prev-output's pub_key_hash into the trimmed copy.
        tx_copy.vin[idx].signature = vec![];
        tx_copy.vin[idx].pub_key   = prev_tx.vout[vin.vout].pub_key_hash.clone();
        tx_copy.id                 = tx_copy.hash()?;
        tx_copy.vin[idx].pub_key   = vec![];

        // 3. Sign the resulting transaction hash.
        let signature = schnorr_sign_digest(private_key, tx_copy.get_id())?;
        vin.signature = signature;
    }
    Ok(())
}

And the verifier, structurally identical:

pub async fn verify(&self, blockchain: &BlockchainService) -> Result<bool> {
    if self.is_coinbase() {
        return Ok(true);
    }

    let mut trimmed = self.trimmed_copy();

    for (idx, vin) in self.vin.iter().enumerate() {
        let prev_tx = blockchain
            .find_transaction(vin.get_txid())
            .await?
            .ok_or_else(|| BtcError::TransactionNotFoundError(
                "Previous transaction not found".to_string(),
            ))?;

        trimmed.vin[idx].signature = vec![];
        trimmed.vin[idx].pub_key   = prev_tx.vout[vin.vout].pub_key_hash.clone();
        trimmed.id                 = trimmed.hash()?;
        trimmed.vin[idx].pub_key   = vec![];

        if !schnorr_sign_verify(
            vin.get_pub_key(),
            vin.get_signature(),
            trimmed.get_id(),
        ) {
            return Ok(false);
        }
    }

    Ok(true)
}

A few worth-noticing details:

• is_coinbase() short-circuits to Ok(true). A coinbase transaction is the special transaction that creates new coins as the block's mining reward. It has no real inputs to spend from (the protocol-specified pseudo-input doesn't reference any previous output), so there's nothing to verify a signature against. The miner who built the block is implicitly authorized by the proof-of-work consumed.
• The return type is Result<bool>, not bool. The two possible outcomes are conceptually different: Ok(true) / Ok(false) mean "the signature was successfully checked and did/didn't verify"; Err(...) means "verification couldn't even be attempted because the previous transaction wasn't found in the local chain." The caller treats those very differently — a missing prev-tx is a sync issue, while a failed verification is a protocol violation.
• No ? inside the verification check. schnorr_sign_verify returns bool, so the code uses if !... rather than ?. This is intentional: a malformed signature is not an error in the program-flow sense, it's just an invalid input to a check that always answers true or false.

Notice how mechanical the verifier is. There is no oracle, no external trust, no shared secret. The verifier just replays the same byte-construction that the signer ran, and checks that the attached signature matches the resulting hash. Determinism is what gives the network consensus on which transactions are valid, even though the creation of those transactions is wildly distributed.

Keys: Generating Secrets and Deriving Their Public Halves

A private key on secp256k1 is, fundamentally, a 32-byte random number — specifically, an integer in the range [1, n) where n is the curve order, ~2²⁵⁶ − 2¹²⁸. Practically, that means almost every random 32-byte value is a valid private key (the exclusion zone near the top of the range and the value 0 together cover about 2¹²⁸ out of 2²⁵⁶ possible values, so the probability of generating an invalid key by chance is negligible). Generating one looks like this:

pub fn new_schnorr_key_pair() -> Result<Vec<u8>> {
    let mut secret_key_bytes = [0u8; 32];
    ring::rand::SystemRandom::new()
        .fill(&mut secret_key_bytes)
        .map_err(|e| BtcError::WalletKeyPairError(e.to_string()))?;

    // Round-trip through SecretKey to validate that the bytes
    // form a valid scalar (rejects 0 and any value above the curve order).
    let secret_key = SecretKey::from_byte_array(secret_key_bytes)
        .map_err(|e| BtcError::WalletKeyPairError(e.to_string()))?;

    Ok(secret_key.secret_bytes().to_vec())
}

Two operations, both important:

• SystemRandom::new().fill(...) asks the OS for cryptographically secure random bytes — /dev/urandom on Linux, BCryptGenRandom on Windows. The OS entropy pool aggregates timing jitter, hardware events, and (on modern CPUs) RDRAND instructions. Anything user-space can build is a downgrade.
• SecretKey::from_byte_array validates the candidate bytes. Not every 32-byte value is a valid secp256k1 scalar — zero is not (it would produce the point at infinity, which is the curve's "identity element" and doesn't represent a usable public key), and values ≥ the curve order would wrap around modulo n and silently degrade the security argument. The constructor rejects both, returning an error rather than silently corrupting the key.

The public key is derived by elliptic-curve scalar multiplication of the private key by the curve's generator point G. Mechanically: take a fixed publicly-known point on the curve (G), and "add it to itself" priv_key times following the curve's addition rule. That gives a new point on the curve — the public key. The addition rule is geometric (draw a line through two points, find the third intersection with the curve, reflect across the X-axis), but the implementation is pure integer arithmetic modulo the curve's prime field. Three things make this useful for cryptography:

1. Forward computation is fast. With double-and-add, computing priv_key · G takes ~256 doublings and ~128 additions — sub-millisecond.
2. Backward computation is intractable. Recovering priv_key from priv_key · G is the elliptic-curve discrete logarithm problem — there is no known algorithm faster than ~2¹²⁸ operations on secp256k1. That's the security foundation for every Bitcoin signature ever made.
3. The output is small. A point on the curve is just two coordinates, each 32 bytes. As shown in a moment, that compresses to 33 bytes total.

The Rust call is one line:

pub fn get_schnorr_public_key(private_key: &[u8]) -> Result<Vec<u8>> {
    let secp = Secp256k1::new();

    let secret_key_array: [u8; 32] = private_key
        .try_into()
        .map_err(|_| BtcError::WalletKeyPairError(
            "Invalid private key length".to_string()
        ))?;
    let secret_key = SecretKey::from_byte_array(secret_key_array)?;
    let public_key = PublicKey::from_secret_key(&secp, &secret_key);

    Ok(public_key.serialize().to_vec())
}

The output is a 33-byte compressed public key — a single prefix byte (0x02 if the Y coordinate is even, 0x03 if odd) followed by the 32-byte X coordinate. The Y coordinate is implied by the prefix and the curve equation, saving 32 bytes per key vs. the uncompressed form. Bitcoin standardized on compressed keys for exactly this reason: storage and bandwidth scale with the size of the key, and over millions of transactions the savings add up.

The full wallet creation flow chains three crypto operations into a typeable address:

Every arrow on that diagram is computationally cheap going right and infeasible going left — the same one-way property described in the discrete-log point above. Even if an attacker has your address, they can't work back to your public key (it's hashed); even if they had the public key, they couldn't work back to the private key (discrete log).

A note on ECDSA helpers

The crypto layer also exposes ECDSA signing and verification, but they're not on the active path:

pub fn ecdsa_p256_sha256_sign_digest(
    pkcs8: &[u8],
    message: &[u8],
) -> Result<Vec<u8>> {
    let rng = ring::rand::SystemRandom::new();
    let key_pair = EcdsaKeyPair::from_pkcs8(
        &ECDSA_P256_SHA256_FIXED_SIGNING,
        pkcs8,
        &rng,
    )?;
    let signature = key_pair.sign(&rng, message)?;
    Ok(signature.as_ref().to_vec())
}

Two things are different from the Schnorr path. First, the key is in PKCS#8 format — a standardized, slightly heavier wire format that includes algorithm metadata. Useful for interoperating with non-Bitcoin systems; unnecessary for a Bitcoin-style chain. Second, the curve is P-256 (secp256r1), not Bitcoin's secp256k1. They look similar — both 256-bit curves over a prime field — but they have different parameters and are not interchangeable. Real Bitcoin ECDSA would be ECDSA over secp256k1, which the secp256k1 crate also supports.

Keep the ECDSA helpers as a reference comparison point and as an entry hook for anyone who wants to wire secp256k1-flavored ECDSA in for legacy Bitcoin compatibility. They're a useful contrast: same conceptual operation (sign a message with a key), wildly different ergonomics.

Addresses: Bytes Humans Can Safely Copy/Paste

A wallet address isn't a key. It's a human-friendly encoding of a binary payload — usually version_byte || pub_key_hash || 4_byte_checksum — that's been serialized into a string a person can type or paste into a chat without losing characters.

Why not just use hex? Two reasons:

• Hex is verbose. A 25-byte payload becomes 50 hex characters. Base58 brings that down to ~34 characters.
• Hex has confusable characters. 0 vs O, 1 vs l vs I — easy to mistype, hard to spot. Base58 is the alphabet [A-HJ-NP-Za-km-z1-9] — no zero, no capital O, no capital I, no lowercase L. Anything that survives Base58 decoding looks unambiguous.

The encoding/decoding pair lives in crypto/address.rs and wraps the bs58 crate:

use bs58;

pub fn base58_encode(data: &[u8]) -> String {
    bs58::encode(data).into_string()
}

pub fn base58_decode(data: &str) -> Result<Vec<u8>> {
    Ok(bs58::decode(data)
        .into_vec()
        .map_err(|e| BtcError::Base58DecodeError(e.to_string()))?)
}

That's the whole module. The functions are tiny because the actual Base58 alphabet handling is in bs58 — the wrapper just provides the right error type at the boundary.

What about the checksum? In Bitcoin's full Base58Check format, the address is built as:

payload         = version_byte || pub_key_hash       (1 + 20-32 bytes)
checksum        = SHA256(SHA256(payload))[0..4]      (4 bytes)
address_bytes   = payload || checksum                (25-37 bytes)
address_string  = base58_encode(address_bytes)       (~34-44 chars)

The checksum gives you typo detection: if you mistype one character of an address, the recomputed checksum almost certainly won't match the four bytes embedded at the end, and the wallet rejects the address before it can send funds to a black hole. This is why Bitcoin addresses fail loudly on a typo instead of just sending money to nowhere.

The raw base58_encode / base58_decode exposed here are the building blocks. The full Base58Check assembly (version byte + checksum + concatenation) belongs in the wallet layer rather than the crypto layer, because the version byte choice depends on the address type (legacy P2PKH, SegWit, Taproot — each has its own version) and the crypto module shouldn't take a position on which one. Separation of concerns: the crypto module knows how to encode bytes; the wallet knows what bytes mean.

Security and Performance

The crypto layer doesn't run in a vacuum. Every node that processes a block does the same crypto work — and an active attacker controls the network, can send malformed inputs, and may be measuring timing to extract bits of your secrets. Five practices make the difference between "looks fine in tests" and "doesn't get owned in production":

Use the OS RNG. Always. ring::rand::SystemRandom for everything random in this layer. There is no scenario in a blockchain context where seeding your own PRNG is correct.

Validate inputs before they touch crypto state. Length checks in particular. The try_into::<[u8; N]>() pattern enforces this at the type level — there's literally no way past it with a wrong-sized slice. Use it everywhere bytes come in from outside the crate.

Return Result, never panic, on cryptographic operations. A panic on malformed input becomes a denial-of-service vector — any peer who can ship a 31-byte signature can crash the node. Every public function in crypto/ should return Result<T, BtcError> or bool. None of them should unwrap.

Trust the constant-time implementations the libraries give you. "Constant-time" means the runtime of an operation does not depend on the secret it's manipulating. The reason this matters: if your signature verification finishes faster when the first byte of the key happens to be zero, an attacker who can run thousands of verifications on a server (or measure power draw, or measure cache misses, or any other "side channel") can reconstruct the secret bit by bit. This is not theoretical — Bleichenbacher's RSA attacks and the various Lucky13/timing attacks against TLS were all exactly this. Both ring and secp256k1 (the C library libsecp256k1 underneath) are explicitly constant-time on the hot paths. Hand-rolling constant-time crypto is famously easy to get wrong — even comparing two byte slices with == is a timing leak. Delegate.

Treat private keys as toxic. No logging. No serialization in plaintext. No leaving them in memory longer than needed. In a production wallet, private keys live in an SQLCipher-encrypted SQLite database; in transit through the API they exist as Vec<u8> with deliberately minimal lifetime. Rust's ownership model helps — the borrow checker won't let you accidentally hand a &SecretKey to a logging facility — but discipline matters. For very high-value keys, zeroize on drop and hardware-backed key stores are the next steps up.

Performance, in round numbers

On a modern x86-64 server core, with the ring and secp256k1 libraries:

The bottleneck for transaction throughput is signature verification — at 2,000–4,000 verifications per second per core, a busy node spends most of its CPU on verify_schnorr. In practice, for high-throughput nodes you'd want batch verification (secp256k1 supports it natively) and you'd parallelize across cores with rayon. Both are off-the-shelf.

Try it Yourself

Drop this into a fresh cargo new --bin crypto_demo and add the four crates from the dependencies block at the top of this post. The whole sign-and-verify roundtrip is fewer than 30 lines:

use bitcoin::crypto::{
    sha256_digest,
    new_schnorr_key_pair,
    get_schnorr_public_key,
    schnorr_sign_digest,
    schnorr_sign_verify,
};

fn main() -> anyhow::Result<()> {
    // 1. Generate a fresh key pair
    let private_key = new_schnorr_key_pair()?;
    let public_key  = get_schnorr_public_key(&private_key)?;

    println!("priv: {} bytes  pub: {} bytes",
             private_key.len(), public_key.len());
    // → priv: 32 bytes  pub: 33 bytes

    // 2. Sign a message
    let message   = b"Hello, blockchain!";
    let signature = schnorr_sign_digest(&private_key, message)?;
    println!("sig: {} bytes", signature.len());        // → sig: 64 bytes

    // 3. Verify (happy path)
    let ok = schnorr_sign_verify(&public_key, &signature, message);
    assert!(ok, "valid signature must verify");

    // 4. Verify (tampered message — must fail)
    let tampered = b"Hello, blockchain?";
    let bad      = schnorr_sign_verify(&public_key, &signature, tampered);
    assert!(!bad, "tampered message must NOT verify");

    // 5. Show the avalanche effect on a 1-byte change
    println!("hash(orig)     = {:x?}", &sha256_digest(message)[..8]);
    println!("hash(tampered) = {:x?}", &sha256_digest(tampered)[..8]);
    Ok(())
}

Two things you'll observe:

1. The valid signature verifies; the tampered-message verification returns false cleanly — no panic, no error, just false. That's the API working as designed.
2. The hashes of the two messages share zero bytes in common despite a single character difference. That's the avalanche effect in action.

Key Takeaways

If you take five things away from this layer, take these:

Keep the cryptographic surface area small. Four submodules, ten public functions. Anyone reading the code can audit exactly what's exposed. Anyone adding a new cryptographic operation has to do it in one place. Cryptographic agility comes from a small, deliberate API, not from hiding choices behind wrappers.

Length validation through the type system, not through assertions. private_key.try_into::<[u8; 32]>() turns "is this the right length?" from a runtime question with a panic-on-wrong-answer into a compile-time-checked Result. Use it everywhere you accept bytes from outside the crate.

Sign and verify must reconstruct the same byte sequence. The trimmed-copy pattern works because both sides do the same thing in the same order. A single byte of disagreement — different field order, different encoding, an extra newline — and verification fails. Lock down your serialization choices and don't let them drift.

Trust audited libraries. Don't reinvent crypto. ring, secp256k1, and sha2 are the libraries to pick. They've been hammered on by people who specialize in finding cryptographic bugs. A cryptography layer should be mostly plumbing between them and the rest of the codebase, plus type-level guarantees that the plumbing can't leak. The actual hashing and signing bodies are someone else's problem, and that's a feature.

Performance is dominated by verification. Plan for it. Mining is parallel. Signing is per-user, slow but rare. Verification is per-transaction, must run on every node, and is where >80% of crypto time goes in a busy chain. Batch where you can. Parallelize where you must.

Explore the Source Code

The complete cryptography layer is open source:

Full repository: github.com/bkunyiha/rust-blockchain

Key files referenced in this post:

• crypto/mod.rs — module layout and public re-exports
• crypto/hash.rs — sha256_digest, taproot_hash
• crypto/signature.rs — Schnorr and ECDSA signing/verification
• crypto/keypair.rs — key generation and public-key derivation
• crypto/address.rs — Base58 encoding/decoding
• primitives/transaction.rs — Transaction::sign and Transaction::verify integration

This post is adapted from Rust Blockchain: A Full-Stack Implementation Guide — a 33-chapter book covering Axum, Iced, Tauri 2, Tokio, SQLCipher, Docker, and Kubernetes through one cohesive project.

Available now on Amazon (paperback + Kindle + hardcover), Gumroad (PDF + EPUB), and Leanpub (pay what you want).

Free resource: Clone the Starter Template

Follow buildwithrust.com for weekly posts on building production systems in Rust.

In 2008, Satoshi Nakamoto published a nine-page paper that described a peer-to-peer electronic cash system. The paper defined what the system should do — digital signatures for ownership, proof-of-work for consensus, a chain of hashes for immutability — but left how to turn those ideas into working code as an exercise for the reader.

We took that exercise seriously. We implemented the entire Bitcoin whitepaper in Rust — every core concept, from UTXO-based transactions to proof-of-work mining to Merkle tree commitments — as a working, runnable blockchain. This post walks through that translation: whitepaper concept → Rust data structure → working code.

If you've read the whitepaper and thought "okay, but how do I actually build this?", this is the post for you.

The Big Picture: How the Pieces Fit Together

Before diving into code, here's the full architecture. Every component maps to a specific whitepaper section:

The mapping from whitepaper concepts to Rust types:

The key insight: a blockchain is not a database of accounts and balances. It's a log of state transitions — each transaction consumes previously created outputs and creates new ones. Everything else exists to make that rule globally auditable.

Let's build each piece.

1. Transactions: The Chain of Digital Signatures

The Concept

The whitepaper defines an electronic coin as "a chain of digital signatures." Each owner transfers value by signing a hash of the previous transaction and the public key of the next owner. But what does "transfer value" actually mean in code?

Think of it like cash, not like a bank account. You don't have a "balance" — you have a collection of unspent outputs (like bills in your wallet). To pay someone, you hand over specific bills and get change back. A transaction is that exchange: it destroys the bills you're spending and creates new ones.

The Rust Types

This model translates into three types working together:

/// A spendable output: value locked to a public key hash.
/// Think of it as a "bill" in someone's wallet.
#[derive(Clone, Serialize, Deserialize)]
pub struct TXOutput {
    value: i32,
    pub_key_hash: Vec<u8>,   // the "lock" — who can spend this?
}

/// A claim on a previous output: "I'm spending this specific bill."
/// The signature proves you own the private key that matches the lock.
#[derive(Clone, Default, Serialize, Deserialize)]
pub struct TXInput {
    txid: Vec<u8>,            // which transaction created the output
    vout: usize,              // which output index in that transaction
    signature: Vec<u8>,       // proof of authorization (Schnorr signature)
    pub_key: Vec<u8>,         // the spender's public key
}

/// The atomic ledger transition: spend old outputs, create new ones.
/// A transaction is only valid if ALL inputs are unspent and ALL
/// signatures check out.
#[derive(Clone, Default, Serialize, Deserialize)]
pub struct Transaction {
    id: Vec<u8>,              // SHA-256 hash of the transaction data
    vin: Vec<TXInput>,        // inputs: which existing outputs we consume
    vout: Vec<TXOutput>,      // outputs: new spendable value we create
}

The relationship between these types:

Creating a Transaction

Here's what it looks like in practice — Alice sending coins to Bob:

pub async fn new_utxo_transaction(
    from: &WalletAddress,
    to: &WalletAddress,
    amount: i32,
    utxo_set: &UTXOSet,
) -> Result<Transaction> {
    let wallet = WalletService::new()?.get_wallet(from)?;
    let pub_key_hash = hash_pub_key(wallet.get_public_key());

    // Step 1: Find enough unspent outputs to cover the amount.
    // Like rifling through your wallet for enough bills.
    let (available, valid_outputs) = utxo_set
        .find_spendable_outputs(&pub_key_hash, amount)
        .await?;

    if available < amount {
        return Err(BtcError::NotEnoughFunds);
    }

    // Step 2: Build inputs — one per unspent output we're consuming.
    // Each input says "I'm spending output #vout from transaction txid."
    let mut inputs = vec![];
    for (txid_hex, out_indexes) in valid_outputs {
        let txid = HEXLOWER.decode(txid_hex.as_bytes())?;
        for index in out_indexes {
            inputs.push(TXInput {
                txid: txid.clone(),
                vout: index,
                signature: vec![],
                pub_key: wallet.get_public_key().to_vec(),
            });
        }
    }

    // Step 3: Build outputs — payment to recipient + change back to sender.
    // If we're spending 12 coins but only need to send 9, we create a
    // 3-coin "change" output back to ourselves.
    let mut outputs = vec![TXOutput::new(amount, to)?];
    if available > amount {
        outputs.push(TXOutput::new(available - amount, from)?);
    }

    // Step 4: Hash the transaction to produce its ID, then sign each input
    // with our private key to prove we're authorized to spend these outputs.
    let mut tx = Transaction { id: vec![], vin: inputs, vout: outputs };
    tx.id = tx.hash()?;
    tx.sign(utxo_set.get_blockchain(), wallet.get_pkcs8()).await?;
    Ok(tx)
}

Every spend references a specific prior output, proves authorization with a cryptographic signature, and creates new outputs that can be spent in the future. This is the whitepaper's "chain of digital signatures" made concrete.

2. Blocks: The Timestamp Server

The Concept

Transactions on their own aren't enough — we need a way to order them and agree on which transactions happened first (especially when someone tries to spend the same coins twice). The whitepaper solves this with a timestamp server that batches transactions into blocks and chains them together.

The Rust Types

#[derive(Clone, Serialize, Deserialize)]
pub struct BlockHeader {
    timestamp: i64,
    pre_block_hash: String,   // hash of the previous block (THE chain link)
    hash: String,             // this block's hash (computed via proof-of-work)
    nonce: i64,               // the value that makes the hash valid
    height: usize,            // position in the chain (block number)
}

#[derive(Clone, Serialize, Deserialize)]
pub struct Block {
    header: BlockHeader,
    transactions: Vec<Transaction>,
}

The pre_block_hash field is what makes this a chain. It's just one String — but that single field is what makes the entire history tamper-evident. Every block commits to the one before it, and through that, transitively commits to every block all the way back to genesis.

Building a Block

Block creation ties the header, transactions, and proof-of-work together:

impl Block {
    pub fn new_block(
        pre_block_hash: String,
        transactions: &[Transaction],
        height: usize,
    ) -> Block {
        let header = BlockHeader {
            timestamp: crate::current_timestamp(),
            pre_block_hash,
            hash: String::new(),      // empty — PoW will fill this in
            nonce: 0,                 // zero — PoW will find the right value
            height,
        };
        let mut block = Block {
            header,
            transactions: transactions.to_vec(),
        };

        // Mine the block — find a nonce that produces a valid hash.
        // This is the expensive part. Everything above is instant.
        let pow = ProofOfWork::new_proof_of_work(block.clone());
        let (nonce, hash) = pow.run();
        block.header.nonce = nonce;
        block.header.hash = hash;
        block
    }
}

Notice that hash starts empty and nonce starts at zero. The proof-of-work algorithm tries millions of nonce values until it finds one that produces a hash meeting the difficulty requirement. Until mining completes, the block isn't valid.

3. Proof-of-Work: Making History Immutable

The Concept

Here's the problem: if anyone can create blocks cheaply, an attacker could rewrite history by generating an alternative chain. Proof-of-work solves this by making block creation expensive — you have to burn CPU cycles finding a hash below a target threshold.

The Rust Implementation

pub struct ProofOfWork {
    block: Block,
    target: BigInt,       // the threshold — hash must be below this
}

const TARGET_BITS: i32 = 8;      // difficulty: 8 leading zero bits
const MAX_NONCE: i64 = i64::MAX;

impl ProofOfWork {
    pub fn new_proof_of_work(block: Block) -> ProofOfWork {
        // BigInt from the `num` crate — Rust's native integers can't hold
        // 256-bit numbers, so we use arbitrary-precision arithmetic.
        let mut target = BigInt::from(1);
        // Shift left (<<= 248) to create the target threshold.
        // 256 - 8 = 248, so target = 2^248.
        // Any hash < 2^248 starts with at least 8 zero bits.
        target.shl_assign(256 - TARGET_BITS);
        ProofOfWork { block, target }
    }

    /// Concatenate all block data + nonce into the bytes we hash.
    fn prepare_data(&self, nonce: i64) -> Vec<u8> {
        let pre_block_hash = self.block.get_pre_block_hash();
        let transactions_hash = self.block.hash_transactions();
        let timestamp = self.block.get_timestamp();

        let mut data_bytes = vec![];
        data_bytes.extend(pre_block_hash.as_bytes());  // chain link
        data_bytes.extend(transactions_hash);           // tx commitment
        data_bytes.extend(timestamp.to_be_bytes());     // when
        data_bytes.extend(TARGET_BITS.to_be_bytes());   // difficulty
        data_bytes.extend(nonce.to_be_bytes());          // the search variable
        data_bytes
    }

    /// The mining loop: try nonces until we find a valid hash.
    pub fn run(&self) -> (i64, String) {
        let mut nonce = 0;
        let mut hash = Vec::new();

        while nonce < MAX_NONCE {
            let data = self.prepare_data(nonce);
            hash = sha256_digest(data.as_slice());
            // Interpret the 32-byte hash as a positive 256-bit integer
            // so we can compare it numerically against the target.
            let hash_int = BigInt::from_bytes_be(Sign::Plus, hash.as_slice());

            if hash_int.lt(&self.target) {
                break;  // Found it! This hash is below the target.
            } else {
                nonce += 1;  // Nope. Try the next one.
            }
        }

        (nonce, HEXLOWER.encode(hash.as_slice()))
    }
}

The algorithm is a brute-force search. prepare_data() packs the block's identity — previous hash, transaction commitment, timestamp, difficulty, and the current nonce guess — into a byte vector. run() hashes that data, checks whether the result falls below the target, and increments the nonce if it doesn't.

Why this matters: to rewrite a historical block, an attacker would need to redo the proof-of-work for that block and every block after it, then outpace the honest network. Each additional block makes the attack exponentially harder.

Verification is the elegant part. Mining takes millions of attempts, but any node can verify the result with a single hash:

Mining:      try nonce 0, 1, 2, ... 891 → hash < target ✓  (expensive)
Verification: hash(block_data + 891)     → hash < target ✓  (one operation)

4. The UTXO Set: Preventing Double-Spending

The Concept

The whitepaper states that "the only way to confirm the absence of a transaction is to be aware of all transactions." In practice, we don't need the full transaction history — we just need to know which outputs haven't been spent yet. That's the UTXO set (Unspent Transaction Output set).

Think of it as a ledger of "bills that still exist." After processing a few blocks, the UTXO set might contain four entries: Alice owns a 5-coin output and a 7-coin output, Bob owns a 3-coin output, and a miner owns a 10-coin output. Alice's "balance" is just the sum of her entries (12 coins) — there's no balance field anywhere.

When Alice spends her 5-coin output, that entry is removed from the set and the new outputs her transaction creates are added. If anyone tries to reference that 5-coin output again — whether Alice herself or an attacker replaying the transaction — the lookup fails because it's gone from the set. One set membership check is the entire double-spending prevention mechanism.

The Rust Implementation

pub struct UTXOSet {
    blockchain: BlockchainService,
}

impl UTXOSet {
    /// Find outputs owned by this public key hash that we can spend,
    /// accumulating until we have enough to cover the requested amount.
    pub async fn find_spendable_outputs(
        &self,
        pub_key_hash: &[u8],
        amount: i32,
    ) -> Result<(i32, HashMap<String, Vec<usize>>)> {
        let mut unspent_outputs: HashMap<String, Vec<usize>> = HashMap::new();
        let mut accumulated = 0;

        // Open the "chainstate" tree in our sled database.
        // This is where we persist the UTXO set between restarts.
        let db = self.blockchain.get_db().await?;
        let utxo_tree = db.open_tree("chainstate")?;

        for item in utxo_tree.iter() {
            let (k, v) = item?;
            let txid_hex = HEXLOWER.encode(k.to_vec().as_slice());
            let (outputs, _): (Vec<TXOutput>, usize) =
                bincode::serde::decode_from_slice(&v, bincode::config::standard())?;

            for (index, out) in outputs.iter().enumerate() {
                // Three checks: do we own it, is it worth something,
                // and do we still need more?
                if out.is_locked_with_key(pub_key_hash)
                    && out.get_value() > 0
                    && accumulated < amount
                {
                    accumulated += out.get_value();
                    unspent_outputs
                        .entry(txid_hex.clone())
                        .or_default()
                        .push(index);
                }
            }
        }

        Ok((accumulated, unspent_outputs))
    }
}

The UTXO set is stored in a sled embedded database under the "chainstate" tree. When a block is accepted, we remove spent outputs and add newly created ones. When a transaction input references an output that isn't in the set, we reject it — that output was either already spent or never existed.

5. Merkle Trees: Committing to Transactions

The Concept

A block header needs to commit to its transactions without storing all of them. The whitepaper solves this with a Merkle tree — a binary tree of hashes where only the root is stored in the header. Change any transaction and the root changes, which changes the block hash, which invalidates the proof-of-work.

The Rust Implementation

Our implementation takes a simplified approach that preserves the essential commitment property:

impl Block {
    /// Compute a single hash that commits to all transactions in this block.
    /// If any transaction changes, this hash changes, which changes the
    /// block header hash, which invalidates the proof-of-work.
    pub fn hash_transactions(&self) -> Vec<u8> {
        let mut tx_hashes = vec![];
        for transaction in &self.transactions {
            tx_hashes.extend(transaction.get_id());
        }
        sha256_digest(tx_hashes.as_slice())
    }
}

We concatenate all transaction IDs and hash the result. A full binary Merkle tree (as shown in the diagram above) would hash pairs recursively, enabling compact inclusion proofs for lightweight (SPV) clients. Our simplified version doesn't support SPV proofs, but it preserves the critical property: the block header hash depends on every transaction in the block. Tamper with any transaction and the chain breaks.

6. The Genesis Block: Where It All Starts

Every blockchain needs a starting point — a block with no predecessor. This is the genesis block, and it's hardcoded into the software:

pub const GENESIS_BLOCK_PRE_BLOCK_HASH: &str = "None";

pub fn generate_genesis_block(transaction: &Transaction) -> Block {
    Block::new_block(
        GENESIS_BLOCK_PRE_BLOCK_HASH.to_string(),
        &[transaction.clone()],
        1,  // height 1 — the first block
    )
}

The genesis block's pre_block_hash is "None" — there's nothing before it. It contains a single coinbase transaction that creates the first coins in the system. From this point forward, every block links to the one before it, and every coin in circulation traces back through the transaction graph to a coinbase reward in some block's first transaction.

7. The Coinbase Transaction: Minting New Coins

The whitepaper describes the incentive mechanism: "the first transaction in a block is a special transaction that starts a new coin owned by the creator of the block." This is the coinbase transaction — the only way new coins enter circulation.

const SUBSIDY: i32 = 10;  // mining reward: 10 coins per block

impl Transaction {
    pub fn new_coinbase_tx(to: &WalletAddress) -> Result<Transaction> {
        // The output: pay SUBSIDY coins to the miner's address
        let txout = TXOutput::new(SUBSIDY, to)?;

        // Coinbase input is special — it creates coins from nothing.
        // No previous transaction to reference. The signature field
        // carries a unique ID instead (Bitcoin uses arbitrary data here;
        // we use a UUID).
        let tx_input = TXInput {
            signature: Uuid::new_v4().as_bytes().to_vec(),
            ..Default::default()  // txid and vout are zeroed
        };

        let mut tx = Transaction {
            id: vec![],
            vin: vec![tx_input],
            vout: vec![txout],
        };
        tx.id = tx.hash()?;
        Ok(tx)
    }
}

The coinbase transaction is unique in two ways: it has no real inputs (it creates value rather than transferring it), and it's always the first transaction in a block. Every miner includes one in the block they're trying to mine, paying the reward to their own address. This is how the whitepaper aligns miner incentives with network security — you get paid for doing the work that secures the chain.

8. Putting It All Together: The Node Pipeline

With all the pieces in place, here's the end-to-end data flow through a running node:

This is exactly the six-step protocol the whitepaper describes in Section 5. Notice how every piece we built maps to a specific step: incoming transactions are verified against the UTXOSet (§4) and held in the mempool. When the miner triggers, it collects those transactions, prepends a coinbase (§7), constructs a Block (§2), and runs ProofOfWork (§3). When a valid block arrives — either from our own miner or from a peer over the network — the node verifies the pre_block_hash chain link, re-checks the proof-of-work, validates every transaction signature, and atomically updates the UTXO set before extending the chain.

The order matters: the UTXO set update is the last step because it's the point of no return. Once spent outputs are removed, they can never be spent again. Everything before that step is validation — everything after it is commitment.

What We Simplified (and Why)

This is a teaching implementation, not a production Bitcoin node. We made deliberate simplifications to keep the code focused on whitepaper concepts:

None of these change the architecture. The whitepaper's core design — UTXO model, proof-of-work consensus, hash-linked blocks, digital signatures for authorization — is implemented faithfully. If you understand this code, you understand how Bitcoin works.

Key Takeaways

1. A blockchain is a log of state transitions, not a database of balances. Transactions consume outputs and create new ones. The UTXO set is derived state — like an index built from a log.

2. The whitepaper is surprisingly implementable. The core types fit in about 100 lines of Rust structs. The mining algorithm is under 50 lines. The hard part isn't the crypto — it's getting the state management right.

3. Proof-of-work is elegant. Expensive to produce, trivial to verify, and it makes history rewriting computationally impractical. One if hash_int < target check validates what may have taken millions of attempts to produce.

4. Rust is a natural fit for blockchain. Ownership semantics map cleanly to UTXO ownership. The type system catches whole categories of bugs at compile time. serde + bincode make serialization painless, and sled gives us an embedded database without leaving the Rust ecosystem.

5. The "chain" in blockchain is just one field. pre_block_hash in the block header links everything together. That single 32-byte hash is what makes the entire history tamper-evident.

Explore the Source Code

The complete implementation is open source:

Full repository: github.com/bkunyiha/rust-blockchain

Key files referenced in this post:

• block.rs — Block and BlockHeader structs, genesis block creation

• transaction.rs — Transaction, TXInput, TXOutput, coinbase creation

• pow.rs — Proof-of-work implementation

• utxo_set.rs — UTXO set management and spendable output queries

• hash.rs — SHA-256 hashing utilities

This post is adapted from Rust Blockchain: A Full-Stack Implementation Guide — a 33-chapter book covering Axum, Iced, Tauri 2, Tokio, SQLCipher, Docker, and Kubernetes through one cohesive project.

Available now on Amazon (paperback + Kindle + hardcover), Gumroad (PDF + EPUB), and Leanpub (pay what you want).

Free resource: Clone the Starter Template

Follow buildwithrust.com for weekly posts on building production systems in Rust.

We built a peer-to-peer networking layer for a Bitcoin-style blockchain node using Tokio, Rust's async runtime. The node accepts inbound TCP connections from peers, dispatches different message types to different subsystems, relays transactions and blocks across the network, runs proof-of-work mining that can be cancelled mid-computation, and shuts down gracefully on Ctrl+C — all concurrently, without any of these activities blocking the others.

This post walks through the concurrency patterns we used, with real code from the project. These patterns — select! for event multiplexing, spawn for per-connection isolation, atomic flags for cross-task coordination, and spawn_blocking for bridging sync and async worlds — transfer directly to any async Rust system that coordinates multiple independent subsystems.

What a Blockchain Node Must Do Concurrently

A blockchain node isn't a request-response server. It's a peer in a network where every participant is both client and server simultaneously. At any given moment, our node might be:

• Accepting inbound TCP connections from peers who want to announce new blocks or transactions

• Dispatching messages — routing each inbound packet to the right handler (chainstate, mempool, peer discovery)

• Relaying inventory — broadcasting transaction and block hashes to every connected peer

• Mining a block — running proof-of-work computation that could take seconds or minutes

• Cancelling mining — if a competing block arrives from a peer while we're still computing, we need to stop immediately

• Responding to API queries — the web UI and wallet apps ask for blockchain height, balances, and transaction history

• Shutting down cleanly — releasing the TCP port, flushing state, without corrupting the chain database

Each of these is a concurrent activity that can't block the others. Tokio gives us the primitives to express this, but the composition is where the real engineering happens.

The Mental Model: Async, Parallel, or Both?

Before diving into code, it's worth getting precise about terminology that even experienced developers conflate. These distinctions directly affect which Tokio primitives you reach for at each point in the blockchain node.

Concurrency vs Parallelism

Concurrency means multiple tasks make progress over the same time period. They might interleave on a single core (one runs while another waits for I/O), or they might truly execute simultaneously on separate cores.

Parallelism is a subset of concurrency where multiple tasks execute at the same instant on different CPU cores.

A blockchain node needs both. Network I/O (waiting for a peer to send a message) is concurrent but doesn't need parallelism — the CPU is idle during the wait, so interleaving is efficient. Mining (computing SHA-256 hashes in a tight loop) is CPU-bound and benefits from parallelism — it actually uses a core continuously.

Async Rust with Tokio gives you concurrency by default. Parallelism comes from Tokio's multi-threaded runtime, which schedules tasks across multiple OS threads. But here's the subtlety: a single async task is never parallel with itself. It runs on one thread at a time and can only be "elsewhere" when it's suspended at an .await point. True parallelism only happens between different tasks.

OS Threads vs Tokio Tasks

An OS thread has its own stack (typically 2–8 MB), is scheduled by the kernel, and context-switching between threads costs microseconds. Spawning 10,000 threads is impractical — the memory overhead alone would be 20–80 GB.

A Tokio task is a lightweight state machine (~few hundred bytes) scheduled cooperatively by the Tokio runtime. You can spawn hundreds of thousands without breaking a sweat. The trade-off: tasks must cooperate by yielding at .await points. An OS thread can be preempted mid-computation by the kernel; a Tokio task cannot.

In our blockchain node, each peer connection gets its own Tokio task (not its own OS thread). With 50 peers, that's 50 tasks multiplexed across 4–8 OS threads — efficient, lightweight, and the reason Tokio can handle thousands of connections where a thread-per-connection model would fall over.

The async model interleaves work from many peers onto a few threads. When Peer A's read suspends at .await (waiting for bytes), the worker thread immediately picks up work from another task. No CPU time is wasted waiting.

CPU-Bound vs IO-Bound Work

This distinction determines where you run each piece of work:

IO-bound work spends most of its time waiting — for network data, disk reads, database queries. This is where async/.await shines. While one task waits, the runtime schedules another. Our peer message handling, transaction relay, and block propagation are all IO-bound.

CPU-bound work keeps the processor busy continuously — hashing, encryption, proof-of-work computation. Async provides no benefit here because there's no waiting to interleave. Worse, a CPU-bound loop without .await points starves other tasks on the same worker thread.

// BAD: CPU-bound work directly on the async runtime.
// This loop never yields — no .await points — so the worker
// thread running this task can't service ANY other tasks
// (timers, accepts, channel reads) until mining finishes.
async fn mine_block_bad(header: &[u8], difficulty: u32) -> (u64, Vec<u8>) {
    let mut nonce = 0u64;
    loop {
        let hash = sha256(header, nonce);
        if leading_zeros(&hash) >= difficulty {
            return (nonce, hash);
        }
        nonce += 1;
        // No .await — this worker thread is monopolized
    }
}

// GOOD: Yield periodically so other tasks can run,
// OR move to spawn_blocking / a dedicated thread.
async fn mine_block_good(header: &[u8], difficulty: u32) -> (u64, Vec<u8>) {
    let mut nonce = 0u64;
    loop {
        // Check 10,000 nonces, then yield
        for _ in 0..10_000 {
            let hash = sha256(header, nonce);
            if leading_zeros(&hash) >= difficulty {
                return (nonce, hash);
            }
            nonce += 1;
        }
        // Yield to the runtime — other tasks get a chance to run
        tokio::task::yield_now().await;
    }
}

In our blockchain implementation, mining runs in an async context but internally yields periodically and checks the cancellation flag. The alternative (and arguably cleaner approach for pure CPU work) is tokio::task::spawn_blocking(), which we discuss later.

Cooperative Scheduling and the .await Contract

Tokio uses cooperative scheduling: tasks voluntarily yield control at .await points. Unlike OS threads, which the kernel can preempt at any instruction, Tokio tasks run uninterrupted between .awaits.

This has a crucial implication: the code between two .await points runs atomically from the runtime's perspective. If you hold a std::sync::MutexGuard across an .await, you're holding a lock while the task might be suspended for an unpredictable duration — and because MutexGuard is !Send, the compiler will actually prevent this in many cases. Tokio provides tokio::sync::Mutex, which is .await-aware and safe to hold across yield points, but it has its own costs (it's an async lock, so acquiring it may itself yield).

In our blockchain node, we're careful about this. The peer set (GLOBAL_NODES) uses std::sync::RwLock, not tokio::sync::RwLock, because we never hold the lock across an .await — every access is a quick read-or-write followed by an immediate drop. This is faster than the async alternative for short critical sections.

Send + 'static: Why tokio::spawn Has Bounds

Every tokio::spawn call requires the future to be Send + 'static. These bounds exist because of how the runtime works:

Send — the task might be started on one worker thread, suspended at an .await, and resumed on a different worker thread. Any data the task holds must be safe to move between threads. This is why you can't spawn a task that captures a Rc<T> (which is !Send) — you need Arc<T> instead.

'static — the spawned task has no guaranteed relationship with the spawner's lifetime. The spawner might complete while the task is still running (that's exactly what fire-and-forget means). So the task can't borrow from the spawner's stack — it must own all its data.

In practice, this means you'll clone data before spawning. When our node relays a transaction to peers (Pattern 3 below), we clone the NodeContext, copy the SocketAddr, and clone the transaction — because the spawned task must own everything it touches:

let context = self.clone();     // NodeContext is cheap to clone (Arc inside)
let addr_copy = *addr_from;     // Copy the SocketAddr (it's Copy)
let tx = utxo.clone();          // Clone the transaction data
tokio::spawn(async move {       // 'move' transfers ownership into the task
    let _ = context.submit_transaction_for_mining(&addr_copy, tx).await;
});

If you've ever fought the compiler over "borrowed value does not live long enough" in a tokio::spawn call, this is why. The fix is almost always: clone the data or wrap it in Arc. The cost of an Arc clone is a single atomic increment — negligible compared to the network I/O the task will perform.

The Wire Protocol: Gossip and Fetch

With the mental model in place, let's look at what messages actually flow through the system. Bitcoin's P2P protocol uses a three-step gossip-and-fetch strategy to minimize bandwidth:

Peers announce what they have by sharing only the hash (the gossip phase). If the receiver doesn't already have that hash, it requests the full object (the fetch phase). This avoids sending full blocks to peers that already have them.

In our implementation, every message on the wire is a variant of a single Rust enum:

#[derive(Debug, Serialize, Deserialize)]
pub enum Package {
    // Block and transaction relay
    Block { addr_from: SocketAddr, block: Vec<u8> },
    Tx { addr_from: SocketAddr, transaction: Vec<u8> },

    // Gossip-and-fetch protocol
    Inv { addr_from: SocketAddr, op_type: OpType, items: Vec<Vec<u8>> },
    GetData { addr_from: SocketAddr, op_type: OpType, id: Vec<u8> },
    GetBlocks { addr_from: SocketAddr },

    // Peer discovery and versioning
    Version { addr_from: SocketAddr, version: usize, best_height: usize },
    KnownNodes { addr_from: SocketAddr, nodes: Vec<SocketAddr> },

    // Admin operations (local queries, not part of P2P protocol)
    AdminNodeQuery { addr_from: SocketAddr, query_type: AdminNodeQueryType },
    // ...
}

This enum is the complete vocabulary of peer-to-peer communication. Every TCP message deserializes into one of these variants, and the dispatcher pattern-matches on it to route to the correct handler. The addr_from field on every variant lets the receiver know who sent the message — critical for relay logic that must avoid sending data back to its source.

Pattern 1: The Server Loop with tokio::select!

The first concurrency challenge is multiplexing two independent concerns: accepting new peer connections and listening for a shutdown signal. tokio::select! lets us race two futures against each other in a loop:

pub async fn run_with_shutdown(
    &self,
    addr: &SocketAddr,
    mut shutdown: tokio::sync::broadcast::Receiver<()>,
) {
    let listener = TcpListener::bind(addr)
        .await
        .expect("Failed to bind TCP listener");

    // Bootstrap: announce ourselves to the network
    if !addr.eq(&CENTRAL_NODE) {
        let height = self.node_context
            .get_blockchain_height().await
            .expect("Blockchain read error");
        send_version(&CENTRAL_NODE, height).await;
    }

    // Main event loop: accept connections OR shut down,
    // whichever happens first on each iteration.
    loop {
        tokio::select! {
            // Branch 1: shutdown signal arrived.
            // The broadcast channel fires when the operator
            // sends SIGINT or the orchestrator calls shutdown.
            _ = shutdown.recv() => {
                info!("Shutdown signal received");
                break;
            }

            // Branch 2: a new peer connected.
            // We accept and immediately spawn a dedicated
            // task to handle this peer's message stream.
            accept_result = listener.accept() => {
                match accept_result {
                    Ok((stream, _peer_addr)) => {
                        let ctx = self.node_context.clone();
                        tokio::spawn(async move {
                            if let Err(e) =
                                process_stream(ctx, stream).await
                            {
                                error!("Peer handler error: {}", e);
                            }
                        });
                    }
                    Err(e) => error!("Accept error: {}", e),
                }
            }
        }
    }
}

The key insight: tokio::select! doesn't poll both branches simultaneously — it awaits whichever completes first, executes that branch, and then loops. If a shutdown signal arrives while we're waiting for a connection, we break immediately. If a connection arrives while no shutdown has been requested, we handle it and loop back. This pattern ensures the node can shut down mid-accept without waiting for a timeout.

Cancellation Safety: Why select! Requires Care

There's a subtlety that bites many Tokio users: when one branch of select! completes, the other branches' futures are dropped. This is fine for listener.accept() and shutdown.recv() — both are cancellation-safe, meaning dropping them mid-await loses no data. But not all futures are safe to cancel this way.

Consider what would happen if instead of listener.accept(), one of our branches was stream.read_exact(&mut buf) — a partially-completed read. If the other branch wins the race, the read future gets dropped, and however many bytes were already read into buf are silently lost. The next time we call read_exact, we'd start from scratch, missing those bytes. This is the class of bugs that async Rust's cancellation model can produce.

The Tokio documentation marks each method's cancellation safety explicitly. When building your own select! loops, check each branch: accept() is safe, recv() is safe, but read_exact(), write_all(), and many buffered I/O operations are not. If you need a cancel-unsafe operation in a select! branch, wrap it in a tokio::spawn — spawned tasks are not cancelled when their JoinHandle is dropped, only when explicitly aborted.

Shutdown Signals: broadcast vs CancellationToken

Our implementation uses broadcast::Receiver<()> for shutdown coordination. This works, but the Tokio ecosystem has converged on a cleaner abstraction: CancellationToken from the tokio-util crate. Here's how the same server loop would look:

use tokio_util::sync::CancellationToken;

pub async fn run_with_shutdown(
    &self,
    addr: &SocketAddr,
    shutdown: CancellationToken,
) {
    let listener = TcpListener::bind(addr).await.unwrap();

    loop {
        tokio::select! {
            _ = shutdown.cancelled() => {
                info!("Shutdown signal received");
                break;
            }
            accept_result = listener.accept() => {
                // ... same as before
            }
        }
    }
}

CancellationToken has two advantages over broadcast channels. First, it's cheaply cloneable — you can hand a clone to every subsystem without worrying about channel capacity or lagged receivers. Second, it supports hierarchical cancellation: you can create child tokens that cancel when the parent cancels, but cancelling a child doesn't cancel the parent. This maps naturally to subsystem lifecycle — shutting down the mining loop shouldn't shut down the API server, but shutting down the entire node should shut down everything.

In production Tokio services, CancellationToken combined with tokio::signal::ctrl_c() is the standard pattern for graceful shutdown. Our broadcast channel approach is functionally equivalent for a single-level shutdown, but CancellationToken scales better as systems grow more complex.

Pattern 2: One Task Per Connection

Every accepted connection gets its own tokio::spawned task. This is the standard concurrent server pattern, but what happens inside that task is where things get interesting.

The message dispatcher reads a continuous stream of JSON messages from the TCP connection, deserializes each into a Package, and routes it:

pub async fn process_stream(
    node_context: NodeContext,
    stream: TcpStream,
) -> Result<()> {
    let reader = BufReader::new(stream);
    let mut deserializer =
        serde_json::Deserializer::from_reader(reader);

    loop {
        match serde_json::Value::deserialize(&mut deserializer) {
            Ok(value) => {
                match serde_json::from_value::<Package>(value) {
                    Ok(pkg) => {
                        // Route by variant — each arm calls into
                        // a different subsystem via NodeContext
                        if let Err(e) = match pkg {
                            Package::Tx { addr_from, transaction } => {
                                let tx = Transaction::deserialize(&transaction)?;
                                node_context
                                    .process_transaction(&addr_from, tx)
                                    .await
                                    .map(|_| ())
                            }
                            Package::Block { addr_from, block } => {
                                let blk = Block::deserialize(&block)?;
                                // Cancel any in-progress mining —
                                // a competing block just arrived
                                cancel_current_mining();
                                node_context.add_block(&blk).await
                            }
                            Package::Inv { addr_from, op_type, items } => {
                                handle_inv(
                                    &node_context, &addr_from,
                                    op_type, items
                                ).await
                            }
                            Package::GetData { addr_from, op_type, id } => {
                                handle_get_data(
                                    &node_context, &addr_from,
                                    op_type, id
                                ).await
                            }
                            Package::Version { addr_from, .. } => {
                                GLOBAL_NODES.add_node(addr_from).map(|_| ())
                            }
                            _ => Ok(()),
                        } {
                            error!("Handler error: {}", e);
                        }
                    }
                    Err(e) => {
                        error!("Deserialization error: {}", e);
                        break;
                    }
                }
            }
            // Peer disconnected cleanly
            Err(e) if e.is_eof() => break,
            // Malformed data — close the connection
            Err(e) => {
                error!("Stream read error: {}", e);
                break;
            }
        }
    }
    Ok(())
}

Notice the cancel_current_mining() call inside the Package::Block handler. When a peer sends us a new block, our own in-progress mining is now working on a stale tip. We set an atomic flag to abort the proof-of-work computation immediately. We'll look at the mining concurrency guard in detail later.

The match pkg { ... } block is the message router — the equivalent of a network protocol handler. Every incoming message has exactly one code path, and the compiler enforces exhaustiveness. If someone adds a new Package variant and forgets to handle it here, the code won't compile.

Pattern 3: Fire-and-Forget Broadcasting with tokio::spawn

When a transaction is accepted into the mempool, the node needs to announce it to all peers via INV messages. But this broadcast is not on the critical path — the caller (the API handler or peer connection) shouldn't wait for every peer to acknowledge the relay before returning.

This is where tokio::spawn shines as a fire-and-forget mechanism:

pub async fn process_transaction(
    &self,
    addr_from: &SocketAddr,
    utxo: Transaction,
) -> Result<String> {
    // 1. Duplicate check — fast, synchronous
    if transaction_exists_in_pool(&utxo) {
        return Err(BtcError::TransactionAlreadyExistsInMemoryPool(
            utxo.get_tx_id_hex(),
        ));
    }

    // 2. Accept into mempool (marks UTXO outputs as "in mempool"
    //    to prevent double-spending)
    add_to_memory_pool(utxo.clone(), &self.blockchain).await?;

    // 3. Background: relay to peers + maybe trigger mining.
    //    tokio::spawn detaches this work from the current task.
    //    The caller gets the txid back immediately — they don't
    //    wait for relay or mining to complete.
    let context = self.clone();
    let addr_copy = *addr_from;
    let tx = utxo.clone();
    tokio::spawn(async move {
        let _ = context
            .submit_transaction_for_mining(&addr_copy, tx)
            .await;
    });

    // Return the transaction ID to the caller while
    // relay and mining happen in the background
    Ok(utxo.get_tx_id_hex())
}

The let _ = inside the spawned task is deliberate. If relay fails (a peer is unreachable), we log it and move on. This is correct for a gossip protocol — if one peer doesn't receive the INV, another peer will relay it later. The alternative — propagating errors back to the caller — would mean a single unreachable peer could block transaction admission.

The same fire-and-forget pattern appears in block broadcasting after mining:

pub async fn broadcast_new_block(block: &Block) -> Result<()> {
    let my_addr = GLOBAL_CONFIG.get_node_addr();
    let nodes = GLOBAL_NODES.get_nodes()?;

    for node in nodes {
        if node.get_addr() != my_addr {
            let addr = node.get_addr();
            let hash = block.get_hash_bytes();
            // Each peer gets its own spawned task.
            // If peer 3 is slow, peers 1 and 2 still
            // get notified immediately.
            tokio::spawn(async move {
                send_inv(&addr, OpType::Block, &[hash]).await;
            });
        }
    }
    Ok(())
}

Each peer announcement runs in its own task. A slow or disconnected peer doesn't delay announcements to other peers. This is a common pattern in distributed systems: fan-out with independent failure domains.

When Fire-and-Forget Is Wrong

It's worth noting when this pattern is not appropriate. Fire-and-forget works for gossip because the protocol is self-healing — if peer B misses an INV from peer A, peer C will send it later. But for operations where you need confirmation (like writing to a database, sending an email, or completing a financial transaction), dropping the JoinHandle without awaiting it means you'll never know if the operation succeeded. For those cases, collect the handles and await them:

// When you need to know the results:
let mut handles = Vec::new();
for peer in &peers {
    let addr = peer.get_addr();
    let data = payload.clone();
    handles.push(tokio::spawn(async move {
        send_data(&addr, data).await
    }));
}

// Wait for all broadcasts and collect failures
let results = futures::future::join_all(handles).await;
let failures: Vec<_> = results.iter()
    .filter(|r| r.as_ref().map_or(true, |inner| inner.is_err()))
    .collect();
if !failures.is_empty() {
    warn!("{} peers failed to acknowledge", failures.len());
}

The choice between fire-and-forget and awaited fan-out is a design decision about your system's consistency requirements, not a technical limitation.

Pattern 4: Atomic Guards for Mining Concurrency

Mining is the most interesting concurrency challenge. Proof-of-work can run for seconds. During that time, a competing block might arrive from a peer, making our computation worthless. We also need to prevent two threads from mining the same block simultaneously (which could happen if multiple transactions trigger the mining threshold at nearly the same time).

We solve both problems with AtomicBool flags:

static MINING_IN_PROGRESS: AtomicBool = AtomicBool::new(false);
static MINING_CANCELLED: AtomicBool = AtomicBool::new(false);

pub async fn process_mine_block(
    txs: Vec<Transaction>,
    blockchain: &BlockchainService,
) -> Result<Block> {
    // Guard: prevent concurrent mining.
    // compare_exchange atomically checks "is it false?"
    // and sets it to true. If another thread already set it
    // to true, we get Err and bail out.
    if MINING_IN_PROGRESS
        .compare_exchange(false, true, Ordering::SeqCst, Ordering::SeqCst)
        .is_err()
    {
        return Err("Mining already in progress".into());
    }

    // Reset the cancellation flag before starting
    reset_mining_cancellation();

    let result = async {
        // Check if a competing block arrived between
        // the trigger and now
        if is_mining_cancelled() {
            return Err("Mining cancelled: new block received".into());
        }

        // Proof-of-work: this is the expensive part.
        // Internally, the PoW loop checks is_mining_cancelled()
        // periodically to abort early if a competing block arrives.
        let new_block = blockchain.mine_block(&txs).await?;

        // CRITICAL: Once mine_block() returns successfully, the block
        // is already in our local chain (tip updated, UTXO set modified).
        // We MUST broadcast it. If we cancel here, we create a permanent
        // fork — our chain has a block that no peer knows about.

        // Remove confirmed transactions from the mempool
        for tx in &txs {
            remove_from_memory_pool(tx.clone(), blockchain).await;
        }

        // Announce the new block hash to all peers
        broadcast_new_block(&new_block).await?;
        Ok(new_block)
    }
    .await;

    // Always release the mining lock, even on error.
    // Without this, a failed mining attempt would
    // permanently block all future mining.
    MINING_IN_PROGRESS.store(false, Ordering::SeqCst);
    result
}

Several things are worth unpacking here.

compare_exchange is not a mutex. A mutex would block the second caller until mining finishes. compare_exchange fails immediately — the second caller gets an error and moves on. This is correct behavior: if mining is already in progress with the current mempool contents, queuing a second mining attempt is wasteful.

The cancellation flag is checked at two points. Once before mining starts (to catch blocks that arrived during preparation), and periodically inside the PoW loop itself. When a peer sends us a Package::Block, the message handler calls cancel_current_mining(), which sets MINING_CANCELLED to true. The PoW loop checks this flag every N iterations and bails out early if set.

The "no cancel after creation" rule is critical. The comment in the code explains why: once mine_block() returns, the block has been written to our local chain. Our tip has advanced, our UTXO set has been updated. If we skip the broadcast, we create a fork — our chain has a block that no peer will ever request because they don't know its hash. This is a real distributed systems bug that wouldn't show up in unit tests but would cause chain divergence in production.

SeqCst ordering is the safe default. For two independent atomic flags that interact (in-progress and cancelled), sequential consistency ensures all threads see flag changes in the same order. Weaker orderings (Relaxed, Acquire/Release) could allow a thread to see the cancellation flag before the in-progress flag, leading to subtle race conditions. In practice, SeqCst has negligible performance overhead on x86 architectures (where all loads and stores are already strongly ordered), and the correctness guarantee is worth far more than any nanoseconds saved by weaker orderings.

A Deeper Look: Why Not tokio::sync::Mutex or CancellationToken?

You might wonder why we used raw AtomicBool flags instead of higher-level abstractions. There are three alternatives worth considering, each with trade-offs:

tokio::sync::Mutex<bool> would work, but it's overkill. A mutex provides mutual exclusion for a critical section — it says "only one task can enter this region at a time." Our mining guard doesn't need a critical section. It needs a non-blocking test: "is mining happening?" If yes, bail out immediately. compare_exchange expresses this intent directly without the overhead of lock acquisition.

CancellationToken (from tokio_util) would be a clean fit for the cancellation signal specifically. You'd create a new token before each mining attempt, pass it into the PoW loop, and call token.cancel() when a competing block arrives. The PoW loop would check token.is_cancelled() instead of our custom is_mining_cancelled() function. This is arguably better style — it's the ecosystem-standard way to express cooperative cancellation in Tokio — and it's what we'd use if we were starting fresh today.

tokio::sync::Notify could replace the cancellation flag with an async signal. The PoW loop would select! between the computation and notify.notified(). This integrates more naturally with async/await but makes the PoW loop itself async, which adds complexity for CPU-bound work.

We chose AtomicBool because it's the simplest primitive that solves the problem, requires no dependencies beyond std, and is obvious to anyone who's worked with concurrent code in any language. For a more complex cancellation protocol — say, with timeout deadlines or nested cancellation scopes — CancellationToken would be the better choice.

Pattern 5: The Coordination Façade

All of these concurrent subsystems — networking, mempool, mining, chainstate — need a single point of coordination. That's NodeContext:

#[derive(Clone, Debug)]
pub struct NodeContext {
    blockchain: BlockchainService,
}

It's deliberately small. NodeContext owns a single dependency (the blockchain service handle) and reaches into global state for everything else: the mempool (GLOBAL_MEMORY_POOL), the peer set (GLOBAL_NODES), the mining flags (MINING_IN_PROGRESS). This design means NodeContext is cheap to Clone — it's just an Arc under the hood — which matters because every spawned task needs its own copy.

The façade pattern shows up in the transaction lifecycle. What looks like a single operation from the outside is actually a multi-step pipeline across several subsystems:

The caller (the REST API handler or peer connection) sees one async fn call. Behind the façade, the node is coordinating mempool admission, peer relay, and mining — each with its own concurrency model. The mempool uses an RwLock for thread-safe access. The peer set uses its own RwLock. Mining uses atomic flags. The façade hides this complexity behind a clean interface.

The Trade-off We Made: Blocking I/O in Async Tasks

There's one deliberate architectural compromise in this codebase that's worth discussing because it reflects a trade-off many real-world Rust projects face.

Our message parsing uses serde_json::Deserializer::from_reader(), which requires a synchronous std::io::Read implementor. Tokio's TcpStream implements AsyncRead, not Read. So in the server loop, we convert the Tokio stream to a standard library stream:

// Inside the spawned task for each connection:
match stream.into_std() {
    Ok(std_stream) => {
        let _ = std_stream.set_nonblocking(false);
        process_stream(node_context, std_stream).await
    }
    // ...
}

This means each per-connection task uses blocking I/O on a Tokio worker thread. And this is where understanding Tokio's runtime architecture matters.

Why Blocking on a Worker Thread Is Dangerous (and When It's Not)

Tokio's multi-threaded runtime has a fixed pool of worker threads (by default, one per CPU core). Every tokio::spawned task runs on one of these workers. When a task blocks — calls a synchronous function that waits for I/O — it holds that worker thread hostage. No other task scheduled to that thread can make progress until the blocking call returns.

Alice Ryhl (a Tokio maintainer) puts it well: if you have 4 worker threads and 4 tasks are all blocking on synchronous I/O, your entire async runtime is frozen. Pending timers, pending accepts, pending channel reads — everything stops until one of those blocking calls finishes.

For our blockchain node, this is acceptable because the peer count is small (8–50 connections) and each connection spends most of its time waiting for the next message. With 4–8 CPU cores, we have enough workers to absorb a few blocked threads without starving the rest of the runtime.

But there's a better approach: tokio::task::spawn_blocking(). This API moves blocking work off the async worker pool onto a dedicated blocking thread pool that Tokio manages separately:

// Better: blocking I/O runs on the blocking thread pool,
// keeping async workers free for non-blocking tasks.
let ctx = self.node_context.clone();
let handle = tokio::runtime::Handle::current();
tokio::task::spawn_blocking(move || {
    // This closure runs on a dedicated blocking thread.
    // The async worker that spawned it is immediately
    // available for other tasks.
    // We use the captured handle to drive async calls
    // (like node_context.add_block().await) from within
    // the blocking context.
    handle.block_on(async {
        process_stream(ctx, std_stream).await
    })
});

spawn_blocking is the correct tool when you must call synchronous APIs from async code. It's used heavily in the Rust ecosystem for file I/O (std::fs), CPU-bound computation (hashing, compression), and synchronous database drivers. The blocking thread pool has a much larger default limit (512 threads) precisely because blocked threads don't consume CPU — they're just waiting.

The Fully Async Alternative

For a production node aiming at scale, the right path forward would eliminate the blocking from_reader entirely:

use tokio::io::{AsyncBufReadExt, BufReader};

// Async message framing: read one JSON message per line
async fn process_stream_async(
    node_context: NodeContext,
    stream: tokio::net::TcpStream,
) -> Result<()> {
    let reader = BufReader::new(stream);
    let mut lines = reader.lines();

    while let Some(line) = lines.next_line().await? {
        let pkg: Package = serde_json::from_str(&line)?;
        // ... dispatch pkg to handlers
    }
    Ok(())
}

This approach requires newline-delimited JSON (each message on one line), which is a minor protocol change. The benefit: zero blocking calls, all I/O is truly asynchronous, and the runtime can efficiently multiplex thousands of connections across a handful of worker threads. Libraries like tokio-serde and tokio-util's LengthDelimitedCodec provide battle-tested framing implementations.

We chose simplicity over scalability because a blockchain P2P network typically has 8–50 peers, not 10,000. The from_reader API is mature, battle-tested, and requires zero framing logic. For this use case, that trade-off is correct. For yours, it might not be — and that's a judgment call you should make deliberately rather than by default.

Putting It All Together: A Transaction's Journey

To see how all these patterns compose, trace a single transaction from arrival to mining:

Five patterns, one transaction flow. The server loop (select!) accepted the connection. The per-connection task deserialized and routed the message. Fire-and-forget spawning handled relay without blocking the caller. Atomic guards prevented concurrent mining. And the façade (NodeContext) coordinated it all behind a single async fn.

Key Takeaways

If you're building a concurrent system in Rust with Tokio — whether it's a blockchain node, a game server, or a distributed cache — here are the patterns that transferred:

tokio::select! is your event multiplexer, but respect cancellation safety. Use it whenever a loop needs to respond to multiple independent event sources. But check each branch: when one branch wins, the others are dropped. If a dropped future loses partially-completed work (like write_all that's written half the buffer), you have a bug. The Tokio docs mark each method's cancellation safety — read them.

tokio::spawn serves two roles — know which one you need. As an isolation boundary (one task per connection), it ensures one peer's slow response doesn't block another. As a fire-and-forget mechanism (broadcasting), it detaches background work from the critical path. But fire-and-forget is only safe when the operation is idempotent or self-healing (like gossip). For operations that must succeed, collect and await the JoinHandles.

Atomic flags beat mutexes for simple boolean coordination. When you need "is mining happening right now?" — not "wait until mining finishes" — AtomicBool with compare_exchange is lighter weight, non-blocking, and expresses intent more clearly than Mutex<bool>. For more complex cancellation scenarios, CancellationToken from tokio-util is the ecosystem standard.

Never block a Tokio worker thread without knowing the cost. If you must call synchronous APIs (file I/O, blocking database drivers, CPU-heavy computation), use tokio::task::spawn_blocking() to move the work off the async worker pool. Blocking a worker thread silently degrades the entire runtime's throughput. For a handful of connections it's survivable; at scale it's fatal.

Façades simplify async coordination. A thin struct that delegates to subsystems lets you change the concurrency model of any individual subsystem without affecting callers. NodeContext could switch its mempool from a global RwLock to an actor-based channel, and no caller would need to change.

Design for the concurrency you have, not the concurrency you imagine. We used blocking I/O in tokio::spawn tasks because our peer count is small and the simplicity gain was real. Premature optimization toward fully-async I/O would have added framing complexity for no measurable benefit. Know your system's actual concurrency profile, make the simplest choice that works, and document the scaling limit so future you knows when to revisit.

Explore the Source Code

The complete networking and node orchestration implementation is open source:

Full repository: github.com/bkunyiha/rust-blockchain

Key files:

• net_processing.rs — Message dispatcher and send primitives

• server.rs — TCP server loop with graceful shutdown

• miner.rs — Mining pipeline with atomic concurrency guards

• txmempool.rs — Transaction mempool admission and removal

• context.rs — NodeContext façade

This post is adapted from Rust Blockchain: A Full-Stack Implementation Guide — a 33-chapter book covering Axum, Iced, Tauri 2, Tokio, SQLCipher, Docker, and Kubernetes through one cohesive project.

Available now on Amazon (paperback + Kindle + hardcover), Gumroad (PDF + EPUB), and Leanpub (pay what you want).

Free resource: Clone the Starter Template

Follow buildwithrust.com for weekly posts on building production systems in Rust.

We built a complete REST API for a Bitcoin-style blockchain node using Axum, Rust's async web framework built on Tokio and Tower. The API handles wallet management, transaction submission, block queries, mining operations, and health monitoring — all with role-based authentication, CORS, rate limiting, and auto-generated OpenAPI documentation.

This post walks through the architecture and implementation patterns we used, with real code from the project. If you're building a REST API in Rust with Axum, these patterns transfer directly to any domain — not just blockchain.

What We're Building

The API serves as the primary interface to a blockchain node. Desktop clients (we built two — one in Iced, one in Tauri 2), web browsers, and programmatic clients all interact with the node through this single HTTP layer.

Here's the endpoint surface:

Every request passes through a middleware pipeline before reaching a handler. Let's start with the architecture.

Architecture Overview

The API follows a layered architecture where each component has a single responsibility. Routes map URLs to handlers. Handlers contain business logic. Middleware handles cross-cutting concerns. Models define request and response shapes. The server orchestrates everything.

bitcoin/src/web/
├── server.rs           # Server initialization + middleware stack
├── routes/
│   ├── api.rs          # API route definitions
│   └── web.rs          # Swagger UI + static files
├── handlers/
│   ├── blockchain.rs   # Block and chain queries
│   ├── wallet.rs       # Wallet creation + balance
│   ├── transaction.rs  # Transaction submission + history
│   ├── mining.rs       # Block generation
│   └── health.rs       # Liveness + readiness probes
├── middleware/
│   ├── auth.rs         # API key authentication
│   ├── cors.rs         # CORS configuration
│   ├── logging.rs      # Structured logging
│   └── rate_limit.rs   # Token bucket rate limiting
├── models/
│   ├── requests.rs     # Typed request bodies
│   ├── responses.rs    # Typed response envelopes
│   └── errors.rs       # Error types + HTTP mapping
└── openapi.rs          # Utoipa OpenAPI spec

This structure is intentionally flat. Every handler file maps to one domain. Every middleware file handles one concern. You can find any piece of code in seconds.

The Request Pipeline

Every HTTP request flows through the same sequence of middleware layers before reaching a handler. Understanding this pipeline is essential for debugging and extending the API.

The order matters. CORS runs first because browsers send preflight OPTIONS requests that should be handled before any authentication check. Error handling wraps everything inside it so that even middleware failures produce clean JSON responses. Authentication runs per-route (not globally) because health checks are public.

Server Setup

The server is configured through a WebServer struct that holds configuration and a shared reference to the blockchain node:

pub struct WebServer {
    config: WebServerConfig,
    node: Arc<NodeContext>,
}

#[derive(Debug, Clone)]
pub struct WebServerConfig {
    pub host: String,
    pub port: u16,
    pub enable_cors: bool,
    pub enable_rate_limiting: bool,
    pub rate_limit_requests_per_second: u32,
    pub rate_limit_burst_size: u32,
}

The Arc<NodeContext> is the key design decision. Every handler receives a reference-counted pointer to the same blockchain node. There's no global state, no mutex contention on the hot path, and the type system enforces that handlers can only read blockchain data through the NodeContext interface.

Building the application router combines routes and middleware in a single create_app() method:

pub fn create_app(
    &self,
) -> Result<Router, Box<dyn std::error::Error + Send + Sync>> {
    let app = Router::new()
        .merge(create_all_api_routes())
        .merge(create_wallet_only_routes())
        .merge(create_web_routes())
        .with_state(self.node.clone());

    let mut app = app;

    // Rate limiting (conditional)
    if self.config.enable_rate_limiting {
        let rl_config = RateLimitConfig::default();
        if let Some(manager) = build_rate_limiter_manager(&rl_config)? {
            app = app.layer(from_fn_with_state(
                manager,
                axum_rate_limiter::limiter::middleware,
            ));
        }
    }

    // CORS (conditional)
    if self.config.enable_cors {
        app = app.layer(cors::create_cors_layer());
    }

    // Compression + error handling (always on)
    app = app.layer(CompressionLayer::new());
    app = app.layer(axum::middleware::from_fn(handle_errors));

    Ok(app)
}

Three route sets are merged into one router: the main API endpoints, wallet-specific endpoints with their own auth, and web routes (Swagger UI). State is injected once with .with_state(), then middleware layers are applied conditionally based on configuration.

The server starts with graceful shutdown support — in-flight requests complete before the process exits:

pub async fn start_with_shutdown(
    &self,
) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let app = self.create_app()?;
    let addr = SocketAddr::from(([0, 0, 0, 0], self.config.port));

    let listener = tokio::net::TcpListener::bind(addr).await?;

    let shutdown_signal = async {
        tokio::signal::ctrl_c()
            .await
            .expect("Failed to install CTRL+C signal handler");
        tracing::info!("Shutdown signal received");
    };

    axum::serve(
        listener,
        app.into_make_service_with_connect_info::<SocketAddr>(),
    )
    .with_graceful_shutdown(shutdown_signal)
    .await?;

    Ok(())
}

The into_make_service_with_connect_info::<SocketAddr>() call preserves client IP addresses through the service layer — essential for per-IP rate limiting.

Route Organization

Routes are organized into four groups, each with appropriate authentication:

// Public API routes — full endpoint set, requires admin auth
pub fn create_api_routes() -> Router<Arc<NodeContext>> {
    Router::new()
        .route("/blockchain", get(blockchain::get_blockchain_info))
        .route("/blockchain/blocks", get(blockchain::get_blocks))
        .route("/blockchain/blocks/latest", get(blockchain::get_latest_blocks))
        .route("/blockchain/blocks/{hash}", get(blockchain::get_block_by_hash))
        .route("/wallet", post(wallet::create_wallet))
        .route("/wallet/{address}/balance", get(wallet::get_balance))
        .route("/transactions", post(transaction::send_transaction))
        .route("/transactions/mempool", get(transaction::get_mempool))
        .route("/mining/info", get(mining::get_mining_info))
        .route("/mining/generatetoaddress", post(mining::generate_to_address))
}

// Admin routes — nests API routes under /api/admin with admin auth
pub fn create_admin_api_routes() -> Router<Arc<NodeContext>> {
    Router::new()
        .nest("/api/admin", create_api_routes())
        .nest("/api/admin", create_monitor_api_routes())
        .layer(axum::middleware::from_fn(require_admin))
}

// Wallet routes — limited subset with wallet-level auth
pub fn create_wallet_only_routes() -> Router<Arc<NodeContext>> {
    let wallet_only = Router::new()
        .route("/wallet", post(wallet::create_wallet))
        .route("/transactions", post(transaction::send_transaction));

    Router::new()
        .nest("/api/wallet", wallet_only)
        .layer(axum::middleware::from_fn(require_wallet))
}

// Health checks — public, no auth
pub fn create_monitor_api_routes() -> Router<Arc<NodeContext>> {
    Router::new()
        .route("/health", get(health::health_check))
        .route("/health/live", get(health::liveness))
        .route("/health/ready", get(health::readiness))
}

The separation between admin and wallet routes is deliberate. Wallet applications get a limited-privilege API key that can only create wallets and submit transactions. Admin tools get a separate key with full access. This follows the principle of least privilege — a compromised wallet key can't dump the entire blockchain or trigger mining operations.

Handler Patterns

Every handler follows the same structure: extract inputs, process the request through NodeContext, and return a typed JSON response. Here's the blockchain info handler:

pub async fn get_blockchain_info(
    State(node): State<Arc<NodeContext>>,
) -> Result<Json<ApiResponse<BlockchainInfoResponse>>, StatusCode> {
    let height = node.get_blockchain_height().await
        .map_err(|e| {
            error!("Failed to get blockchain height: {}", e);
            StatusCode::INTERNAL_SERVER_ERROR
        })?;

    let last_block = node.blockchain().get_last_block().await
        .map_err(|e| {
            error!("Failed to get last block: {}", e);
            StatusCode::INTERNAL_SERVER_ERROR
        })?;

    let mempool_size = node.get_mempool_size()
        .map_err(|e| {
            error!("Failed to get mempool size: {}", e);
            StatusCode::INTERNAL_SERVER_ERROR
        })?;

    let info = BlockchainInfoResponse {
        height,
        difficulty: 1,
        total_blocks: height,
        mempool_size,
        last_block_hash: last_block.get_hash().to_string(),
        last_block_timestamp: chrono::Utc::now(),
    };

    Ok(Json(ApiResponse::success(info)))
}

The State(node) extractor gives the handler a reference to the blockchain node. Axum handles the extraction at compile time — if the type doesn't match what .with_state() provided, you get a compile error, not a runtime panic.

For endpoints that take path parameters, Axum can deserialize directly into custom types:

pub async fn get_balance(
    State(node): State<Arc<NodeContext>>,
    Path(address): Path<WalletAddress>,  // Custom type, not String
) -> Result<Json<ApiResponse<BalanceResponse>>, StatusCode> {
    let balance = node.get_balance(&address).await
        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;

    let utxo_set = UTXOSet::new(node.blockchain().clone());
    let utxo_count = utxo_set.utxo_count(&address).await
        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;

    Ok(Json(ApiResponse::success(BalanceResponse {
        address: address.as_string(),
        balance,
        utxo_count,
        updated_at: chrono::Utc::now(),
    })))
}

Path(address): Path<WalletAddress> extracts the {address} segment and deserializes it into a WalletAddress. If the path segment doesn't parse as a valid wallet address, Axum returns a 400 before the handler even runs.

For POST endpoints, the Json extractor handles request body deserialization:

pub async fn send_transaction(
    State(node): State<Arc<NodeContext>>,
    Json(request): Json<SendTransactionRequest>,
) -> Result<Json<ApiResponse<SendBitCoinResponse>>, StatusCode> {
    let txid = node.btc_transaction(
        &request.from_address,
        &request.to_address,
        request.amount
    ).await.map_err(|e| {
        error!("Failed to create transaction: {}", e);
        StatusCode::BAD_REQUEST
    })?;

    info!(txid = %txid, "Transaction submitted successfully");

    Ok(Json(ApiResponse::success(SendBitCoinResponse {
        txid,
        timestamp: chrono::Utc::now(),
    })))
}

A note on the error mapping: in this handler, btc_transaction failures typically indicate client errors (invalid address, insufficient funds), so BAD_REQUEST is reasonable. A production API with more error granularity would use a custom error enum that maps different failure modes to appropriate status codes — 400 for validation failures, 422 for business logic rejections, and 500 for system errors. We cover that pattern in the book's error handling chapter.

The pattern is consistent across every handler: extract, process, respond. This consistency makes the codebase predictable — once you've read one handler, you can read them all.

Authentication: Role-Based API Keys

Authentication is implemented as Axum middleware that checks the X-API-Key header and determines the caller's role:

pub async fn require_role(
    mut req: axum::http::Request<axum::body::Body>,
    required: Role,
    next: axum::middleware::Next,
) -> Result<axum::response::Response, StatusCode> {
    // Extract API key from header
    let key = req.headers().get("X-API-Key")
        .and_then(|h| h.to_str().ok());

    // Determine caller's role
    let caller_role = match key {
        Some(k) if is_admin_key(k) => Role::Admin,
        Some(k) if is_wallet_key(k) => Role::Wallet,
        _ => return Err(StatusCode::UNAUTHORIZED),
    };

    // Check authorization (admin can access wallet routes)
    let allowed = caller_role == required
        || (caller_role == Role::Admin && required == Role::Wallet);

    if !allowed {
        return Err(StatusCode::FORBIDDEN);
    }

    // Attach role to request extensions for downstream handlers
    req.extensions_mut().insert(caller_role);

    Ok(next.run(req).await)
}

The role hierarchy is simple: Admin has full access, Wallet has limited access, and unauthenticated users can only reach health checks. The req.extensions_mut().insert(caller_role) line attaches the resolved role to the request so handlers can inspect it if needed — for example, to filter response data based on privilege level.

Convenience wrappers make it clean to apply per-route:

pub async fn require_admin(
    req: axum::http::Request<axum::body::Body>,
    next: axum::middleware::Next,
) -> Result<axum::response::Response, StatusCode> {
    require_role(req, Role::Admin, next).await
}

pub async fn require_wallet(
    req: axum::http::Request<axum::body::Body>,
    next: axum::middleware::Next,
) -> Result<axum::response::Response, StatusCode> {
    require_role(req, Role::Wallet, next).await
}

Keys are validated against environment variables (BITCOIN_API_ADMIN_KEY and BITCOIN_API_WALLET_KEY), with development defaults as fallbacks. In production, you'd set strong keys and ideally use a key management service.

CORS: Development vs Production

CORS configuration is split into two modes. Development allows everything:

pub fn create_cors_layer() -> CorsLayer {
    CorsLayer::new()
        .allow_origin(Any)
        .allow_methods(Any)
        .allow_headers(Any)
        .expose_headers(Any)
        .max_age(std::time::Duration::from_secs(86400))
}

Production restricts to specific origins:

pub fn create_cors_layer_with_origins(origins: Vec<String>) -> CorsLayer {
    let mut cors = CorsLayer::new()
        .allow_methods(Any)
        .allow_headers(Any)
        .expose_headers(Any)
        .max_age(std::time::Duration::from_secs(86400));

    for origin in origins {
        if let Ok(parsed) = origin.parse::<axum::http::HeaderValue>() {
            cors = cors.allow_origin(parsed);
        }
    }

    cors
}

The 24-hour max_age caches preflight responses so browsers don't re-send OPTIONS requests for every API call. This matters for performance — our desktop clients make dozens of requests per second when polling for blockchain updates.

Rate Limiting: Token Bucket with Redis

Rate limiting uses a Redis-backed token bucket algorithm. Each client gets a bucket of tokens; every request consumes one. Tokens refill at a configured rate. When the bucket is empty, the server responds with 429 Too Many Requests.

Configuration lives in a TOML file, allowing per-endpoint tuning:

[rate_limiter]
redis_addr = "127.0.0.1:6379"
ip_whitelist = ["127.0.0.1"]

# Global per-IP limit: burst of 20 requests, refill 1 token every 6 seconds
[[rate_limiter.limiter]]
strategy = "ip"
global_bucket = { tokens_count = 20, add_tokens_every = 6 }

# Per-URL limits with tighter control on expensive endpoints
[[rate_limiter.limiter]]
strategy = "url"
global_bucket = { tokens_count = 60, add_tokens_every = 1 }
buckets_per_value = [
  { value = "/api/mining/generate", tokens_count = 2, add_tokens_every = 60 },
]

The mining endpoint gets only 2 requests per minute — generating blocks is CPU-intensive and should be throttled aggressively. General endpoints get 60 requests per second, which handles normal client polling comfortably.

Response Envelope: One Shape for Everything

Every API response uses the same generic envelope:

#[derive(Debug, Serialize, Deserialize, ToSchema)]
pub struct ApiResponse<T> {
    pub success: bool,
    pub data: Option<T>,
    pub error: Option<String>,
    pub timestamp: DateTime<Utc>,
}

impl<T> ApiResponse<T> {
    pub fn success(data: T) -> Self {
        Self {
            success: true,
            data: Some(data),
            error: None,
            timestamp: Utc::now(),
        }
    }

    pub fn error(error: String) -> Self {
        Self {
            success: false,
            data: None,
            error: Some(error),
            timestamp: Utc::now(),
        }
    }
}

Clients always know the shape of the response. Parse success first — if true, data is present and typed. If false, error explains what went wrong. The timestamp field is useful for debugging latency and cache staleness.

This consistency pays off in client code. Our Tauri desktop app has a single invoke() wrapper that handles the envelope:

const response = await invoke<ApiResponse<T>>('api_call', { params });
if (!response.success) throw new Error(response.error);
return response.data;

Error Handling: Safe for Clients, Detailed for Operators

The error handling middleware catches all errors and ensures clients never see stack traces or internal paths:

async fn handle_errors(
    request: axum::http::Request<axum::body::Body>,
    next: axum::middleware::Next,
) -> Result<axum::response::Response, StatusCode> {
    let response = next.run(request).await;

    if response.status().is_server_error() || response.status().is_client_error() {
        let (parts, body) = response.into_parts();
        let body_bytes = axum::body::to_bytes(body, usize::MAX)
            .await.unwrap_or_default();

        // Log the full error for operators
        tracing::error!(
            "[handle_errors]: Error response ({}): {}",
            parts.status,
            String::from_utf8_lossy(&body_bytes)
        );

        // Sanitize internal server errors for clients
        if parts.status == StatusCode::INTERNAL_SERVER_ERROR {
            let safe_error = ErrorResponse {
                error: "Internal Server Error".to_string(),
                message: "An unexpected error occurred".to_string(),
                status_code: 500,
                timestamp: chrono::Utc::now(),
            };
            return Ok(Json(ApiResponse::<()>::error(
                serde_json::to_string(&safe_error)
                    .unwrap_or_else(|_| "Unknown error".to_string()),
            )).into_response());
        }
    }

    Ok(response)
}

The split is intentional: operators see the full error context in logs (including the original error message, status code, and request context). Clients see a sanitized message that doesn't reveal anything about the internal architecture.

Health Checks: Three Endpoints, Three Purposes

We expose three health endpoints, each serving a different consumer:

// Full health check with metrics — for monitoring dashboards
pub async fn health_check(
    State(node): State<Arc<NodeContext>>,
) -> Result<Json<ApiResponse<HealthResponse>>, StatusCode> {
    let height = node.get_blockchain_height().await
        .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?;
    let connected_peers = node.get_peer_count().unwrap_or(0);

    Ok(Json(ApiResponse::success(HealthResponse {
        status: "healthy".to_string(),
        version: env!("CARGO_PKG_VERSION").to_string(),
        blockchain_height: height,
        connected_peers,
        // ... additional metrics
    })))
}

// Liveness probe — for Kubernetes "is the process alive?"
pub async fn liveness() -> Result<Json<ApiResponse<String>>, StatusCode> {
    Ok(Json(ApiResponse::success("alive".to_string())))
}

// Readiness probe — for Kubernetes "can this pod accept traffic?"
pub async fn readiness(
    State(node): State<Arc<NodeContext>>,
) -> Result<Json<ApiResponse<String>>, StatusCode> {
    match node.get_blockchain_height().await {
        Ok(_) => Ok(Json(ApiResponse::success("ready".to_string()))),
        Err(_) => Err(StatusCode::SERVICE_UNAVAILABLE),
    }
}

Kubernetes uses /health/live to decide whether to restart a pod and /health/ready to decide whether to route traffic to it. The full /health endpoint gives monitoring systems (Prometheus, Datadog, etc.) detailed metrics. This three-endpoint pattern is a production best practice that works well beyond blockchain — any service deployed to containers benefits from it.

OpenAPI: Documentation That Can't Drift

The API specification is generated from Rust types using Utoipa. Every response model derives ToSchema, and the OpenAPI definition references them directly:

#[derive(OpenApi)]
#[openapi(
    paths(
        health::health_check,
        blockchain::get_blockchain_info,
        wallet::create_wallet,
        transaction::send_transaction,
        mining::get_mining_info,
        // ... all endpoints
    ),
    components(schemas(
        BlockchainInfoResponse,
        WalletResponse,
        SendTransactionRequest,
        // ... all models
    )),
    tags(
        (name = "Health", description = "Health check endpoints"),
        (name = "Blockchain", description = "Blockchain data and queries"),
        (name = "Wallet", description = "Wallet management"),
        (name = "Transactions", description = "Transaction operations"),
        (name = "Mining", description = "Block generation"),
    ),
    info(
        title = "Blockchain API",
        version = "0.1.0",
        description = "A comprehensive blockchain node REST API"
    ),
)]
pub struct ApiDoc;

Swagger UI is served automatically at /swagger-ui:

pub fn create_swagger_ui() -> SwaggerUi {
    SwaggerUi::new("/swagger-ui")
        .url("/api-docs/openapi.json", ApiDoc::openapi())
}

Because the spec is generated from the same types the handlers use, it can't drift out of sync. If you add a field to BlockchainInfoResponse, it appears in the OpenAPI spec automatically. If you add a new endpoint, you add it to the paths() list and the compiler reminds you if you forget the schema. This is a significant advantage over maintaining a separate OpenAPI YAML file.

Structured Logging with Tracing

The tracing crate is initialized once at server startup — typically in main() with a subscriber that formats output as structured JSON in production or human-readable text in development:

tracing_subscriber::fmt()
    .with_env_filter(EnvFilter::from_default_env())  // RUST_LOG=info,bitcoin=debug
    .json()  // Structured JSON for production log aggregation
    .init();

With that in place, every handler logs operations with structured key-value pairs:

use tracing::{error, info, instrument};

// Structured logging with context
info!(
    txid = %txid,
    from = %from_address,
    to = %to_address,
    amount = amount,
    "Transaction submitted successfully"
);

// Error logging preserves full context
error!(
    error = %e,
    txid = %txid,
    from = %from_address,
    "Failed to process transaction"
);

// Spans automatically add context to all nested logs
#[instrument]
async fn process_transaction(txid: String) {
    info!("Processing transaction");
    // ↑ This log automatically includes txid from the span
}

Structured logs are queryable. In production, you can filter for all failed transactions, all requests from a specific address, or all operations that took longer than a threshold — without parsing log strings.

Request Validation with Derive Macros

Request models use the validator crate for declarative validation:

#[derive(Debug, Serialize, Deserialize, Validate, ToSchema)]
pub struct SendTransactionRequest {
    pub from_address: WalletAddress,
    pub to_address: WalletAddress,
    #[validate(range(min = 1, message = "Amount must be greater than 0"))]
    pub amount: i32,
}

#[derive(Debug, Serialize, Deserialize, Validate, ToSchema)]
pub struct BlockQuery {
    #[validate(range(min = 0, message = "Page must be 0 or greater"))]
    pub page: Option<u32>,
    #[validate(range(min = 1, max = 100, message = "Limit must be 1-100"))]
    pub limit: Option<u32>,
    pub hash: Option<String>,
}

Validation rules are declared next to the fields they constrain. The Validate derive macro generates a .validate() method that checks all rules at once. In a handler, you call it before processing:

pub async fn send_transaction(
    State(node): State<Arc<NodeContext>>,
    Json(request): Json<SendTransactionRequest>,
) -> Result<Json<ApiResponse<SendBitCoinResponse>>, StatusCode> {
    // Validate before processing
    request.validate().map_err(|_| StatusCode::BAD_REQUEST)?;

    // ... proceed with validated request
}

Combined with ToSchema, the validation constraints also appear in the OpenAPI documentation — clients can see the allowed ranges before making requests.

Putting It All Together

Here's a curl session that exercises the main endpoints:

# Health check (no auth required)
curl http://localhost:8080/api/admin/health

# Get blockchain info (admin auth)
curl -H "X-API-Key: admin-secret" \
     http://localhost:8080/api/admin/blockchain

# Create a wallet (wallet auth is sufficient)
curl -X POST \
     -H "X-API-Key: wallet-secret" \
     -H "Content-Type: application/json" \
     -d '{"name": "my-wallet"}' \
     http://localhost:8080/api/wallet/wallet

# Send a transaction
curl -X POST \
     -H "X-API-Key: wallet-secret" \
     -H "Content-Type: application/json" \
     -d '{"from_address": "...", "to_address": "...", "amount": 50}' \
     http://localhost:8080/api/wallet/transactions

# Mine a block (admin only)
curl -X POST \
     -H "X-API-Key: admin-secret" \
     -H "Content-Type: application/json" \
     -d '{"address": "...", "nblocks": 1}' \
     http://localhost:8080/api/admin/mining/generatetoaddress

# Interactive API docs
open http://localhost:8080/swagger-ui

Key Takeaways

After building this API, a few patterns stand out as universally applicable:

Use Axum's type system aggressively. Custom types for path parameters (WalletAddress instead of String), typed state extraction, and the ApiResponse<T> envelope catch entire categories of bugs at compile time. The initial investment in types pays off in fewer runtime errors and more self-documenting code.

Separate auth by route group, not globally. Health checks should always be public. Admin and wallet operations need different privilege levels. Axum's .layer() on nested routers makes this natural — you apply middleware where it belongs, not everywhere.

Rate limit by endpoint, not just by IP. A flat per-IP limit doesn't account for the fact that mining operations are 100x more expensive than health checks. Per-endpoint configuration lets you protect expensive operations without throttling cheap ones.

Generate documentation from code. Any documentation that exists separately from the implementation will drift. Utoipa's derive macros guarantee that the OpenAPI spec matches the actual types and endpoints. Swagger UI gives you interactive testing for free.

Three health endpoints, not one. Kubernetes needs liveness and readiness as separate signals. Monitoring dashboards need detailed metrics. One endpoint can't serve all three consumers well.

Explore the Source Code

The complete source code for the API layer is open source:

Full repository: github.com/bkunyiha/rust-blockchain

API source: bitcoin/src/web/

The same API serves both the Iced and Tauri desktop clients — you can see how they consume it in the Iced admin UI and Tauri admin UI.

This post is adapted from Rust Blockchain: A Full-Stack Implementation Guide — a 33-chapter book covering Axum, Iced, Tauri 2, Tokio, SQLCipher, Docker, and Kubernetes through one cohesive project.

Available now on Amazon (paperback + Kindle + hardcover), Gumroad (PDF + EPUB), and Leanpub (pay what you want).

Free resource: Clone the Starter Template

Follow buildwithrust.com for weekly posts on building production systems in Rust.

We built the same blockchain admin dashboard and wallet application twice — once with Iced (pure Rust, MVU architecture) and once with Tauri 2 (Rust backend + React frontend). Both apps connect to the same blockchain node, use the same API crate, and offer identical functionality. The only difference is the desktop framework.

This post walks through the architectural trade-offs we encountered, with real code from both implementations. If you're choosing between Iced and Tauri for a Rust desktop project, this should help you make an informed decision.

The Setup: One Blockchain, Two Desktop Clients

Both applications are admin dashboards for a Bitcoin-style blockchain built entirely in Rust. They let you inspect blocks, manage wallets, send transactions, check balances, and monitor node health. Behind the scenes, both talk to the same REST API via a shared bitcoin-api crate.

The difference is how they render UI and manage state.

Iced is a cross-platform GUI framework for Rust inspired by Elm. You write your entire application — state, logic, rendering — in Rust. There's no web layer, no JavaScript, no HTML. The framework provides widgets, layout primitives, and an event loop built around the Model-View-Update pattern.

Tauri 2 takes a different approach: your backend is Rust, your frontend is a web app (in our case, React + TypeScript), and the two communicate over an IPC bridge. Tauri uses the OS native webview rather than bundling Chromium, which keeps binaries small (5–24 MB vs Electron's 150+ MB).

Architecture at a Glance

How Each Framework Is Structured

Before comparing behavior, it helps to see how each project is organized on disk and how data flows through the system.

Iced Project Structure

Everything is Rust. The entire application compiles into a single binary with no bundled web runtime:

bitcoin-desktop-ui-iced/
  src/
    main.rs     # Entry point: boots Tokio runtime, launches Iced app
    runtime.rs  # Tokio bridge: spawn_on_tokio() helper
    types.rs    # Message enum (all events) + Menu enum (navigation)
    app.rs      # AdminApp struct (the single state container)
    update.rs   # update() function: Message -> state mutation + Tasks
    view.rs     # view() function: &Model -> UI elements (pure, no mutation)
    api.rs      # Async HTTP calls to the blockchain node REST API

Data flows in a strict loop. There are no callbacks, no event listeners, no shared mutable references between components — just one cycle that repeats for every user interaction.

Iced MVU event loop (single Rust binary):

  (view)
    |
    | Message
    v
  (update) ---- Task::perform() ---> [Tokio runtime]
    ^                                 |
    | new state                        | HTTP
    |                                  v
    +-------------------------- [Blockchain node]
                                 (REST API)

The key insight: view() never mutates state. It reads &Model and returns a description of the UI. When the user clicks something, Iced creates a Message, feeds it to update(), which mutates the model and optionally kicks off async work. When that async work completes, it produces another Message, and the cycle repeats.

Tauri Project Structure

Tauri splits the project into two halves — a Rust backend and a React frontend — connected by IPC:

bitcoin-desktop-ui-tauri/
  src-tauri/                   # --- RUST BACKEND ---
    src/
      main.rs                  # Tauri app builder: registers commands + state
      config/mod.rs            # ApiConfig: base_url + api_key (behind RwLock)
      models/mod.rs            # Shared types: WalletAddress, BlockSummary, etc.
      services/bitcoin_api.rs  # HTTP client wrapping the bitcoin-api crate
      commands/                # #[tauri::command] handlers (the IPC surface)
        blockchain.rs          #   get_blockchain_info, get_block, etc.
        wallet.rs              #   create_wallet, get_balance, etc.
        transactions.rs        #   send_transaction, get_history, etc.
        mining.rs              #   mine_block, get_mining_status
        health.rs              #   health_check
        settings.rs            #   get_config, update_config
  src/                         # --- REACT FRONTEND ---
    main.tsx                   # React app entry point
    App.tsx                    # Router setup + layout
    lib/commands.ts            # invoke() wrappers — typed bridge to Rust
    store/useAppStore.ts       # Zustand: UI state (theme, sidebar, wallet)
    hooks/                     # React Query hooks for each data domain
    components/                # Shared UI: DataCard, DataTable, Sidebar, etc.
    pages/                     # 18 page components across 5 sections

The data flow crosses a language boundary at the IPC bridge:

  [Page component]
    | \
    |  \--> [Zustand store] (UI state)
    |
    v
  [React Query]
    |
    | invoke('command')  (JSON over IPC)
    v
  [#[tauri::command] async fn]
    | \
    |  \--> [Read config (RwLock)]
    |
    v
  [Service layer] -- HTTP --> [Blockchain node]
    ^
    |
  Result<T> (JSON back to React Query)

The key insight: the IPC bridge is a serialization boundary. Every value that crosses it must be JSON-serializable. The React frontend calls invoke('command_name'), Tauri routes it to the matching #[tauri::command] Rust function, and the result comes back as a JavaScript object. The frontend never touches the Tokio runtime, the service layer, or the HTTP client — it only sees typed Promises.

State Management: One Struct vs Two Layers

This is where the philosophies diverge most sharply.

Iced: Everything in One Place

In Iced, your entire application state lives in a single Rust struct. Every field is visible, every mutation flows through a single update function, and the compiler enforces it all.

pub struct AdminApp {
    // Navigation: which screen the user is looking at right now
    menu: Menu,

    // Cached API responses — Option<T> because they start empty,
    // then get populated when async fetches complete
    blockchain_info: Option<BlockchainInfo>,
    wallet_addresses: Vec<WalletAddress>,
    selected_block: Option<Block>,

    // UI feedback: shows success/error messages in the status bar
    status_message: String,

    // Form inputs: every text field the user can type into
    // lives here as owned Strings, not in the widget itself
    form_fields: FormState,

    // ... every piece of state in the entire app, right here
    // in one struct. Nothing is hidden.
}

When the user clicks a button, Iced produces a Message — a variant of a Rust enum that represents every possible event in the application. That message flows to the update function, which pattern-matches on it and returns the next state plus any async tasks to run:

// The Message enum is the complete vocabulary of things that can happen.
// Adding a new feature means adding a new variant — the compiler then
// forces you to handle it everywhere.
enum Message {
    FetchBlockchainInfo,                        // User clicked "Refresh"
    BlockchainInfoLoaded(Result<BlockchainInfo, Error>), // API responded
    MenuChanged(Menu),                          // User navigated
    WalletSelected(String),                     // User picked a wallet
    // ... ~50 total variants across all screens
}

// update() is the brain of the application.
// It receives the current state (&mut self) and a Message,
// performs any synchronous state changes, and returns async
// work to do (if any). The return type Task<Message> means
// "when this async work finishes, feed the result back as
// another Message."
fn update(&mut self, message: Message) -> Task<Message> {
    match message {
        // Step 1: User clicks "Refresh" -> we kick off an API call.
        // spawn_on_tokio bridges Iced's sync update loop into
        // our Tokio runtime (see the Async section below).
        // Message::BlockchainInfoLoaded is the "callback" —
        // Iced will call update() again with that variant
        // when the future completes.
        Message::FetchBlockchainInfo => {
            Task::perform(
                spawn_on_tokio(api::get_blockchain_info()),
                Message::BlockchainInfoLoaded,
            )
        }

        // Step 2: API call finished -> store the result in our model.
        // Task::none() means "no further async work needed."
        // Iced will call view() next to re-render with the new data.
        Message::BlockchainInfoLoaded(result) => {
            self.blockchain_info = result.ok();
            Task::none()
        }

        // ... pattern continues for every interaction in the app
    }
}

Every possible event in the application has a name and a type. Nothing is implicit. If you forget to handle a variant, the compiler tells you. This is Iced's core trade-off: more code upfront, but the type system guarantees you've handled every case.

Tauri: Split by Concern

Tauri splits state into two layers. Ephemeral UI state (which menu is open, light/dark theme, toast notifications) lives in a Zustand store on the React side:

// Zustand store: lightweight, React-external state container.
// This holds UI-only concerns — things that don't come from the server.
// Zustand is chosen over React Context because it doesn't cause
// unnecessary re-renders of unrelated components.
const useAppStore = create<AppState>((set) => ({
  theme: 'dark',           // UI preference — persists across page navigations
  sidebarOpen: true,       // Layout state — not worth fetching from Rust
  activeWallet: null,      // Currently selected wallet address (string | null)

  // Actions: plain functions that call set() to update state.
  // Any React component can call these without prop drilling.
  setActiveWallet: (wallet) => set({ activeWallet: wallet }),
}));

Server state (blockchain info, wallet balances, transaction history) is managed by React Query, which handles caching, background refetching, and loading states automatically:

// React Query: manages everything that comes from the Rust backend.
// You declare WHAT data you need; React Query handles WHEN to fetch,
// WHEN to refetch, and WHAT to show while loading.
const { data, isLoading, error } = useQuery({
  queryKey: ['blockchain-info'],    // Cache key — React Query deduplicates
                                    // requests with the same key
  queryFn: () => commands.getBlockchainInfo(),  // The actual IPC call to Rust
  refetchInterval: 30_000,          // Auto-refresh every 30 seconds
                                    // (blockchain data changes as blocks are mined)
});
// At this point:
//   - isLoading = true on first load, false after
//   - data = the BlockchainInfo object from Rust, or undefined
//   - error = any error from the invoke() call
// React Query also gives you: isFetching, isStale, refetch(), and more

The Rust backend holds only shared configuration behind a RwLock:

pub struct AppState {
    pub api_config: ApiConfig,      // base_url + api_key for the blockchain node
    pub active_wallet: Option<String>, // Currently selected wallet (synced from frontend)
}

// Tauri manages this as shared state across all command handlers.
// RwLock allows multiple commands to READ config concurrently
// (e.g., 3 parallel queries from React Query), while only one
// can WRITE at a time (e.g., when the user updates settings).
// This is Tauri's State extractor — injected automatically into
// any command that declares it as a parameter.
State<RwLock<AppState>>

This is less unified than Iced's single-struct model, but each layer does what it's best at: React Query handles cache invalidation and refetch logic that would require manual wiring in Iced, while Zustand provides ergonomic UI state without the ceremony of message enums.

The Async Boundary: Two Very Different Approaches

Async is where Iced requires the most manual plumbing and where Tauri's two-language architecture actually simplifies things.

Iced: The Tokio Bridge

Iced's event loop is synchronous. The update function can't be async. To make API calls, you need to bridge into a Tokio runtime:

// Problem: Iced's update() is synchronous, but our API calls need Tokio.
// Solution: Boot a Tokio runtime on a separate thread at startup,
// then hand futures to it from the synchronous update loop.

// Global handle to the Tokio runtime. OnceCell ensures it's
// initialized exactly once and then available everywhere.
static RUNTIME: OnceCell<Runtime> = OnceCell::new();

fn init_runtime() {
    // Spawn a dedicated OS thread for the Tokio runtime.
    // This thread lives for the entire application lifetime.
    std::thread::spawn(|| {
        let rt = Runtime::new().unwrap();
        RUNTIME.set(rt).unwrap();
        // park() blocks this thread forever without consuming CPU.
        // The runtime stays alive because the Runtime object isn't dropped.
        std::thread::park();
    });
}

// This is the bridge between Iced's sync world and Tokio's async world.
// Call it from update() like:
//   Task::perform(spawn_on_tokio(api::get_balance(addr)), Message::BalanceLoaded)
//
// What happens:
//   1. update() calls spawn_on_tokio(some_future)
//   2. spawn_on_tokio sends that future to the Tokio runtime thread
//   3. Tokio executes it (HTTP call, database query, etc.)
//   4. The result comes back as the return value
//   5. Iced wraps it in Message::SomeLoaded and calls update() again
async fn spawn_on_tokio<F, T>(future: F) -> T
where
    F: Future<Output = T> + Send + 'static,
    T: Send + 'static,
{
    let handle = RUNTIME.get().unwrap().handle().clone();
    handle.spawn(future).await.unwrap()
}

Every API call follows the same round-trip:

User clicks "Refresh"
  -> update() receives Message::FetchBlockchainInfo
    -> Task::perform(spawn_on_tokio(api_call), Message::Loaded)
      -> Tokio runtime executes the HTTP request
        -> Result arrives as Message::BlockchainInfoLoaded(Ok(data))
          -> update() stores data in self.blockchain_info
            -> view() re-renders with new data

This is explicit and traceable, but it's boilerplate you write for every async operation.

Tauri: Just Write async fn

Tauri commands are natively async. No runtime bridging, no message round-trips:

// This attribute is all Tauri needs to expose a Rust function to JavaScript.
// Tauri handles: async runtime, JSON serialization, IPC routing, error conversion.
#[tauri::command]
async fn get_blockchain_info(
    // Tauri injects this automatically — it's the shared AppState
    // we registered in main.rs with .manage(RwLock::new(AppState::default()))
    state: State<'_, RwLock<AppState>>,
) -> Result<Value, String> {
    // Step 1: Acquire a read lock on shared config.
    // Multiple commands can read concurrently (RwLock allows many readers).
    let config = state.read().await;

    // Step 2: Create a service instance with the current API configuration.
    // This is the same bitcoin-api crate that Iced uses — identical HTTP calls.
    let service = BitcoinApiService::new(&config.api_config);

    // Step 3: Make the HTTP call and convert any error to a String.
    // Tauri will serialize the Ok value to JSON and send it across IPC.
    // The frontend receives it as a resolved Promise<BlockchainInfo>.
    service.get_blockchain_info()
        .await
        .map_err(|e| e.to_string())
}

On the frontend, the entire call is one line — invoke() handles IPC serialization, async execution, and error propagation:

// commands.ts — thin typed wrappers around Tauri's invoke().
// The string 'get_blockchain_info' must exactly match the Rust function name.
// The generic <BlockchainInfo> tells TypeScript what the Promise resolves to.
export async function getBlockchainInfo(): Promise<BlockchainInfo> {
  return invoke<BlockchainInfo>('get_blockchain_info');
}

// For commands that take arguments, pass them as an object:
export async function getBlock(hash: string): Promise<Block> {
  return invoke<Block>('get_block', { hash });
  // Tauri deserializes { hash } into the Rust function's parameters
}

The entire Iced pattern — Message::Fetch → spawn_on_tokio → Task::perform → Message::Loaded — collapses into one invoke() call that returns a Promise. That's not a minor ergonomic difference; across 22 commands in the admin UI alone, it eliminates roughly 44 message variants and their associated match arms.

The View Layer: Widgets vs JSX

Iced: Rust All the Way Down

Iced views are pure functions from &Model to Element<Message>. No mutation, no side effects — just a description of what the screen should look like:

// view() is a PURE function: it reads &self (immutable borrow) and
// returns a tree of UI elements. It never mutates state, never makes
// API calls, never has side effects. Iced calls it after every update().
//
// Each widget can produce a Message. For example, a button might produce
// Message::FetchBlockchainInfo when clicked. That message feeds back
// into update(), completing the MVU loop.
fn view(&self) -> Element<Message> {
    // Route to the correct screen based on current navigation state.
    // Each view_* method returns an Element<Message> — a subtree of widgets.
    let content = match self.menu {
        Menu::BlockchainInfo => self.view_blockchain_info(),
        Menu::WalletList => self.view_wallet_list(),
        Menu::Send => self.view_send_form(),
        // ... one arm per screen in the app
    };

    // Compose the layout: sidebar on the left, content in the center,
    // status bar at the bottom. column! stacks children vertically.
    // container wraps everything with padding and alignment.
    container(
        column![
            self.view_sidebar(),    // Navigation menu (produces MenuChanged messages)
            content,                // Active screen (produces screen-specific messages)
            self.view_status_bar(), // Shows self.status_message at the bottom
        ]
    ).into()
}

Styling is done through Iced's widget API. You compose layouts with row![] (horizontal), column![] (vertical), container (wrapper with padding/alignment), and apply spacing programmatically. It's powerful, but there's no CSS — if you want a specific visual treatment, you build it from widget primitives and theme overrides.

Tauri: React + Tailwind

The Tauri frontend is a standard React application. Pages are components, routing is React Router, and styling is Tailwind:

// A typical Tauri page component. This is standard React — nothing
// Tauri-specific except that commands.getBlockchainInfo() calls
// invoke() under the hood instead of fetch().
export function BlockchainInfoPage() {
  // useQuery handles the entire data lifecycle:
  //   1. First render: isLoading=true, fires queryFn
  //   2. queryFn calls invoke('get_blockchain_info') -> IPC -> Rust -> HTTP
  //   3. Result arrives: isLoading=false, data=BlockchainInfo object
  //   4. On re-mount or stale timeout: refetches silently in background
  const { data, isLoading } = useQuery({
    queryKey: ['blockchain-info'],
    queryFn: commands.getBlockchainInfo,
  });

  // Loading state — React Query gives you this for free.
  // In Iced, you'd need a boolean field in your model and
  // a Message variant to toggle it.
  if (isLoading) return <LoadingSpinner />;

  // Render the data using Tailwind utility classes.
  // p-6 = padding 1.5rem, space-y-4 = vertical gap between children.
  // DataCard is a shared component used across all pages.
  return (
    <div className="p-6 space-y-4">
      <h1 className="text-2xl font-bold">Blockchain Info</h1>
      <DataCard title="Height" value={data?.height} />
      <DataCard title="Difficulty" value={data?.difficulty} />
      {/* data?.height uses optional chaining — safe because
          React Query guarantees data exists when isLoading is false,
          but TypeScript doesn't know that without a type guard */}
    </div>
  );
}

This is familiar territory for anyone who has built a web app. The npm ecosystem provides component libraries, form validation (react-hook-form + zod), charting, and every other UI concern you can think of. The trade-off is that you're now maintaining two languages and a serialization boundary between them.

Where It Gets Interesting: The Wallet

The wallet application is where architectural differences become most consequential, because it introduces local persistence via SQLCipher — an encrypted SQLite database.

Both implementations use the same deterministic key generation to derive the database password from the local username, home directory, and application name. Same function, same output, same database file. The Iced wallet and Tauri wallet can even read each other's databases.

But the data flow is different.

Iced wallet operations are multi-step message chains. Creating a wallet means: Message::CreateWallet → API call → Message::WalletCreated(Result) → persist to SQLCipher → Message::WalletSaved → refresh wallet list → Message::WalletsLoaded. Each step is an explicit enum variant.

Tauri wallet operations collapse that chain into a single command:

#[tauri::command]
async fn create_wallet(
    state: State<'_, RwLock<AppState>>,
) -> Result<WalletAddress, String> {
    let config = state.read().await;
    let service = BitcoinApiService::new(&config.api_config);

    // PHASE 1: Remote — ask the blockchain node to generate a new wallet address.
    // This is an HTTP POST to the node's REST API via the bitcoin-api crate.
    // The node generates a keypair and returns the public address.
    let address = service.create_wallet().await.map_err(|e| e.to_string())?;

    // PHASE 2: Local — persist the new address in the encrypted SQLCipher database.
    // This ensures the wallet survives app restarts. The database is encrypted
    // with a deterministic key derived from the local username + home directory,
    // so no password prompt is needed.
    database::save_wallet_address(&address).map_err(|e| e.to_string())?;

    // The frontend receives a single WalletAddress object.
    // It has no idea that two separate operations happened — one remote,
    // one local. If either fails, the ? operator short-circuits and the
    // frontend gets an Err(String) which React Query surfaces as error state.
    Ok(address)
}

On the React side, the mutation is equally concise:

// React Query mutation — handles the invoke() call + cache invalidation.
// When create_wallet succeeds, invalidateQueries forces the wallet list
// to refetch, so the new wallet appears immediately without a manual refresh.
const createWallet = useMutation({
  mutationFn: () => commands.createWallet(),
  onSuccess: () => {
    queryClient.invalidateQueries({ queryKey: ['wallets'] });
  },
});

The frontend sees one invoke() call, gets one result, and React Query handles cache invalidation. The two-phase nature (remote call + local save) is invisible to the UI layer.

This highlights a fundamental trade-off: Iced's message chain makes every step visible and debuggable at the type level, but it's verbose. Tauri's command encapsulation is concise, but the two-phase logic is hidden inside an opaque async function.

Parallel Data Loading

When the user selects a wallet, both apps need to fetch wallet info, balance, and transaction history simultaneously. The approaches reflect each framework's async model.

Iced uses Task::batch to fan out multiple async operations from a single message handler:

Message::WalletSelected(address) => {
    // Store the selected wallet in our model
    self.active_wallet = Some(address.clone());

    // Clear any stale data from the previously selected wallet
    self.wallet_info = None;
    self.balance = None;
    self.transactions = Vec::new();

    // Fire three API calls in parallel using Task::batch.
    // Each call runs independently on the Tokio runtime.
    // Each produces a different Message variant when it completes.
    // The UI will update incrementally as results arrive —
    // balance might render before transactions, for example.
    Task::batch([
        Task::perform(
            spawn_on_tokio(api::fetch_wallet_info(address.clone())),
            Message::WalletInfoLoaded,   // -> update() stores wallet metadata
        ),
        Task::perform(
            spawn_on_tokio(api::fetch_balance(address.clone())),
            Message::BalanceLoaded,      // -> update() stores balance amount
        ),
        Task::perform(
            spawn_on_tokio(api::fetch_transactions(address)),
            Message::TransactionsLoaded, // -> update() stores tx history
        ),
    ])
}

Three tasks launch in parallel. Each completes independently and produces its own message. You see exactly what's happening and in what order.

Tauri achieves the same parallelism through React Query — multiple useQuery hooks on the same page fire their queries independently:

// React Query hooks declared in the same component.
// React Query automatically deduplicates and parallelizes these —
// all three invoke() calls fire simultaneously when the component mounts.
// Each has its own loading/error/data state, so the UI can show
// partial results as they arrive.

const walletInfo = useQuery({
  queryKey: ['wallet', address],   // Cache key includes the address, so
  queryFn: () => commands.getWalletInfo(address),  // switching wallets refetches
});

const balance = useQuery({
  queryKey: ['balance', address],
  queryFn: () => commands.getBalance(address),
  refetchInterval: 15_000,         // Balance changes when transactions confirm —
                                   // poll every 15s to stay current
});

const history = useQuery({
  queryKey: ['history', address],
  queryFn: () => commands.getTransactions(address),
});

Same result, less ceremony. React Query manages concurrency, caching, and refetching — but that logic is implicit in the framework rather than explicit in your code.

Side-by-Side: The Same Operation in Both Frameworks

To make the architectural difference concrete, here's the complete code path for one operation — "user clicks Refresh to load blockchain info" — in both frameworks.

Iced: 6 touch points across 4 files

// --- types.rs: Define the event ---
enum Message {
    FetchBlockchainInfo,                                // 1. Event name
    BlockchainInfoLoaded(Result<BlockchainInfo, Error>), // 2. Completion event
    // ...
}

// --- api.rs: Define the async call ---
pub async fn get_blockchain_info() -> Result<BlockchainInfo, Error> {
    let client = AdminClient::new(&base_url, &api_key);  // 3. HTTP call
    client.get_blockchain_info().await
}

// --- update.rs: Wire the event to the async call ---
Message::FetchBlockchainInfo => {                         // 4. Dispatch
    Task::perform(
        spawn_on_tokio(api::get_blockchain_info()),
        Message::BlockchainInfoLoaded,
    )
}
Message::BlockchainInfoLoaded(result) => {                // 5. Handle result
    self.blockchain_info = result.ok();
    Task::none()
}

// --- view.rs: Render a button that produces the event ---
button("Refresh")                                         // 6. UI trigger
    .on_press(Message::FetchBlockchainInfo)

Tauri: 3 touch points across 3 files

// --- commands/blockchain.rs: Define the command ---
#[tauri::command]
async fn get_blockchain_info(                             // 1. Command handler
    state: State<'_, RwLock<AppState>>,
) -> Result<Value, String> {
    let config = state.read().await;
    let service = BitcoinApiService::new(&config.api_config);
    service.get_blockchain_info().await.map_err(|e| e.to_string())
}

// --- lib/commands.ts: Typed invoke wrapper ---
export async function getBlockchainInfo() {               // 2. IPC bridge
  return invoke<BlockchainInfo>('get_blockchain_info');
}

// --- pages/BlockchainInfoPage.tsx: UI + data in one place ---
const { data, isLoading, refetch } = useQuery({           // 3. Fetch + render
  queryKey: ['blockchain-info'],
  queryFn: commands.getBlockchainInfo,
});
// ...
<button onClick={() => refetch()}>Refresh</button>

The Iced version is more code, but every step is named and typed. The Tauri version is more concise, but the async lifecycle (loading states, error handling, caching) is managed by React Query rather than your own code.

When to Choose Which

After building both implementations side-by-side, here's our take:

Choose Iced when:

• You want a single-language codebase with no JavaScript dependency

• Compile-time type safety across the entire application matters to you

• You prefer explicit, auditable control flow over implicit framework behavior

• Your team is strong in Rust but less experienced with web frontends

• Binary size is a priority (Iced produces smaller executables)

Choose Tauri 2 when:

• You want to leverage the React/npm ecosystem for UI

• Your team has frontend web experience alongside Rust skills

• You need rapid UI iteration (hot reload, CSS utilities, component libraries)

• Async operations are central to your app and you want ergonomic handling

• You're building something visually complex where CSS and web layout shine

Choose both when:

• You're writing a book about desktop development in Rust and want to give readers the full picture

Neither framework is objectively better. Iced trades ecosystem breadth for language unity and type-level guarantees. Tauri trades language unity for ergonomics and access to the web platform. The right choice depends on your team, your project, and what you value most.

What We Learned

Building the same application twice was instructive in ways we didn't expect. The Message enum in Iced, which initially felt like boilerplate, became a comprehensive protocol of everything the application can do — a property that's genuinely valuable for debugging and reasoning about state. Meanwhile, Tauri's invoke() pattern, which felt like it was hiding complexity, turned out to produce code that was easier to onboard new contributors to.

The most surprising finding: the backend code was nearly identical. Both apps use the same bitcoin-api crate, the same SQLCipher database schema, and the same deterministic key derivation. The framework choice only affects the presentation layer and the plumbing between it and the business logic. If you design your Rust backend as a clean service layer, you can put any frontend on top of it.

Explore the Source Code

The complete source code for both implementations is open source. You can clone the repo and run either application locally:

Full repository: github.com/bkunyiha/rust-blockchain

Iced implementations:

• Desktop Admin UI (Iced)

• Wallet UI (Iced)

Tauri implementations:

• Desktop Admin UI (Tauri)

• Wallet UI (Tauri)

Compare the two approaches side-by-side in the same workspace — both consume the shared bitcoin-api crate, so the backend boundary is identical.

This post is adapted from Rust Blockchain: A Full-Stack Implementation Guide — a 33-chapter book covering Axum, Iced, Tauri 2, Tokio, SQLCipher, Docker, and Kubernetes through one cohesive project.

Available now on Amazon (paperback + Kindle + hardcover), Gumroad (PDF + EPUB), and Leanpub (pay what you want).

Free resource: Clone the Starter Template

Follow buildwithrust.com for weekly posts on building production systems in Rust.

Tags: rust, blockchain, iced, tauri, desktop-development, framework-comparison