Embedded PezkuwiChain light client with RPC fallback (Zagros) (#30)

* Add pezkuwi-light: embedded PezkuwiChain light client binding

A JNI binding around the PezkuwiChain fork of smoldot (pezkuwichain/smoldot),
which verifies PezkuwiChain blocks under the chain's sovereign constants.
Upstream smoldot cannot.

The wallet reaches its chains through JSON-RPC WebSockets, so the light
client is served the same way: a WebSocket server bound to 127.0.0.1 on a
random port. Every path carries a random per-process token:
ws://127.0.0.1:<port>/<token>/<chain key>.
- A wrong token, a missing token or an unregistered chain is refused during
  the handshake with 404.
- Each connection adds its own smoldot chain instance. smoldot shares the
  sync between instances of the same chain.
- Each registered chain's finalized state is written to disk every minute,
  through a temporary file and a rename. The next start resumes from it.

Kotlin surface: PezkuwiLight.start(dir), addChain(key, spec, relayKey),
chainUrl(base, key). The module is not yet a dependency of the app.

Tested against the live Zagros testnet, with the relay chain and People
specs:
- dks.kurd resolves through NavnisanApi_resolve to the same bytes the full
  node returns.
- An unregistered name returns 0x00.
- The saved state lets a new client resolve.
- Reverting the token check turns the routing test red.

The library builds for arm, arm64, x86 and x86_64 with 16 KB aligned LOAD
segments (0x4000).

* pezkuwi-light: secure WebSockets and the app's resolver for peers

smoldot's DefaultPlatform cannot open wss connections and resolves names
through the system resolver. Where our domains are blocked, both fail: a
poisoned DNS answer decides where the client connects, and plain libp2p
TCP is recognisable on the wire.

PezkuwiPlatform replaces it:
- Opens /dns/<host>/tcp/<port>/wss over TLS, using rustls with the ring
  provider and the Mozilla roots, so a connection looks like any HTTPS
  WebSocket.
- Resolves every name through a Resolve trait. On Android this is the
  app's HostResolver, called over JNI, so the light client follows the
  same DNS policy as the rest of the app (EncryptedFirstDns: DoH first,
  system resolver last).
- Tries IPv4 before IPv6, and gives up on an address after 10 s.
- With setSecureOnly(true) it opens nothing but secure WebSockets. Peers
  found through the DHT advertise plain TCP too, and none of them is used.

The peer's identity is still checked end to end by libp2p Noise.

Tested against live Zagros with only the /wss boot nodes in the specs and
secure-only on: relay and People sync and dks.kurd resolves to the full
node's bytes. Nail: with secure-only on and the specs' plain TCP boot
nodes, nothing syncs and the test times out red.

* pezkuwi-light: measure a start from the saved database in its own process

An app launch resumes from the database in a fresh process. The in-process
warm measurement ran beside a client that was still syncing, so it did not
show that case.

The new ignored test resolves dks.kurd after a start from the database in
PEZKUWI_LIGHT_DB_DIR. On the first run, when no database exists yet, it
syncs and waits for a save.

The tests also log through env_logger, so RUST_LOG shows smoldot's own
timeline when a measurement needs explaining.

* Fall back to the embedded light client when every Zagros RPC node fails

ChainConnection stays on RPC first. A light client loads the peer-to-peer
nodes, and those nodes have a fixed number of light client slots, so RPC
is the default.

When every RPC node of a supported chain has failed in a row, the
connection moves to the light client, served at
ws://127.0.0.1:<port>/<token>/<genesis>. RPC is retried after one minute.
The wait doubles up to 15 minutes while RPC keeps failing. The connection
returns to RPC as soon as a retry connects. If the light client cannot
start, or its own connection fails, the connection stays on RPC.

LightFallbackPolicy holds these rules. Its tests cover each one, and five
mutations of the policy each turn a test red. ChainConnection handles RPC
node changes, socket states and a 15 s tick as one event stream, one event
at a time, so a node change and a fallback cannot race.

LightClients starts the client on first use. A wallet whose RPC answers
never runs it. LightClients registers Zagros and Zagros People, the
chains the fork can verify, from specifications bundled at build time
from pezkuwi-wallet-utils light-client/: the genesis state root, the /wss
boot nodes on 443 first, and the relay checkpoint. Peer names resolve
through EncryptedFirstDns, which CommonApi now exposes to the runtime
module.

* pezkuwi-light: strip in the cargo profile

The Android Gradle plugin packages a native library it cannot strip as it
is. With debug info, libpezkuwi_light.so is 147 MB per ABI. Stripped it is
8.6 MB.

The first CI build of this library ran out of disk: four targets with
debug info filled the runner. Stripping in the release profile, with debug
info off, fixes both:
- The library is 8.6 MB for arm64 and keeps its three JNI symbols.
- The build directory is 389 MB per target.

* Log the light client fallback's decisions

Each RPC failure the fallback sees, the light client URL it got, and each
RPC retry are logged under LightFallback. The first device run on a
blocked Zagros RPC showed no fallback and no trace of where it stopped.

bindings/pezkuwi-light/.gitignore

@@ -0,0 +1,2 @@
+/build
+/rust/target/

bindings/pezkuwi-light/build.gradle

@@ -0,0 +1,46 @@
+apply plugin: 'org.mozilla.rust-android-gradle.rust-android'
+apply from: '../../scripts/bundled-config.gradle'
+
+android {
+    namespace 'io.novafoundation.nova.pezkuwi_light'
+
+    ndkVersion "26.1.10909125"
+
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+}
+
+dependencies {
+    implementation kotlinDep
+
+    testImplementation jUnitDep
+}
+
+cargo {
+    module = "rust/"
+    libname = "pezkuwi_light"
+    targets = ["arm", "arm64", "x86", "x86_64"]
+    profile = "release"
+    pythonCommand = "python3"
+}
+
+tasks.matching { it.name.matches(/merge.*JniLibFolders/) }.configureEach {
+    it.inputs.dir(new File(buildDir, "rustJniLibs/android"))
+    it.dependsOn("cargoBuild")
+}
+
+// Chain specifications the light client starts from: genesis state root, boot nodes and, for the
+// relay chain, a checkpoint. A checkpoint is a trust anchor, so it reaches the client only with the
+// APK; pezkuwi-wallet-utils' light_client_specs.py writes them and signed/targets.json lists them.
+def lightClientSpecs = "https://raw.githubusercontent.com/pezkuwichain/pezkuwi-wallet-utils/master/light-client"
+def isLightClientSpec = { it instanceof Map && it.genesis?.stateRootHash && it.bootNodes }
+bundleConfigAsset("bundleZagrosLightSpec", "$lightClientSpecs/zagros.json", "light-client/zagros.json") {
+    isLightClientSpec(it) && it.lightSyncState
+}
+bundleConfigAsset("bundleZagrosPeopleLightSpec", "$lightClientSpecs/people-zagros.json", "light-client/people-zagros.json") {
+    isLightClientSpec(it) && it.relay_chain == "zagros"
+}

bindings/pezkuwi-light/consumer-rules.pro

@@ -0,0 +1,11 @@
+# JNI resolves these methods by name.
+-keep class io.novafoundation.nova.lightclient.PezkuwiLight {
+    native <methods>;
+}
+# Native code calls HostResolver.resolve by name.
+-keep interface io.novafoundation.nova.lightclient.HostResolver {
+    java.lang.String[] resolve(java.lang.String);
+}
+-keepclassmembers class * implements io.novafoundation.nova.lightclient.HostResolver {
+    java.lang.String[] resolve(java.lang.String);
+}

bindings/pezkuwi-light/proguard-rules.pro

@@ -0,0 +1,11 @@
+# JNI resolves these methods by name.
+-keep class io.novafoundation.nova.lightclient.PezkuwiLight {
+    native <methods>;
+}
+# Native code calls HostResolver.resolve by name.
+-keep interface io.novafoundation.nova.lightclient.HostResolver {
+    java.lang.String[] resolve(java.lang.String);
+}
+-keepclassmembers class * implements io.novafoundation.nova.lightclient.HostResolver {
+    java.lang.String[] resolve(java.lang.String);
+}

bindings/pezkuwi-light/rust/.cargo/config.toml

@@ -0,0 +1,11 @@
+[target.aarch64-linux-android]
+rustflags = ["-C", "link-arg=-z", "-C", "link-arg=max-page-size=16384"]
+
+[target.armv7-linux-androideabi]
+rustflags = ["-C", "link-arg=-z", "-C", "link-arg=max-page-size=16384"]
+
+[target.i686-linux-android]
+rustflags = ["-C", "link-arg=-z", "-C", "link-arg=max-page-size=16384"]
+
+[target.x86_64-linux-android]
+rustflags = ["-C", "link-arg=-z", "-C", "link-arg=max-page-size=16384"]

bindings/pezkuwi-light/rust/Cargo.toml

@@ -0,0 +1,44 @@
+[package]
+authors = ['PezkuwiChain']
+edition = '2021'
+license = 'Apache-2.0'
+name = "pezkuwi-light"
+version = "0.1.0"
+publish = false
+
+[dependencies]
+# PezkuwiChain fork of smoldot: upstream smoldot cannot verify PezkuwiChain blocks (sovereign
+# sr25519 and BABE VRF signing contexts, `TeyrchainHost` runtime API).
+smoldot-light = { git = "https://github.com/pezkuwichain/smoldot", rev = "182d996a3ae2a9b507a776fa307f2e6fc5d14f7a", default-features = false, features = ["std"] }
+smoldot = { git = "https://github.com/pezkuwichain/smoldot", rev = "182d996a3ae2a9b507a776fa307f2e6fc5d14f7a", default-features = false, features = ["std"] }
+rustls = { version = "0.23", default-features = false, features = ["ring", "std", "tls12", "logging"] }
+futures-rustls = { version = "0.26", default-features = false, features = ["ring", "tls12", "logging"] }
+webpki-roots = "0.26"
+pin-project = "1"
+async-tungstenite = { version = "0.28", default-features = false, features = ["handshake", "futures-03-sink"] }
+futures-util = { version = "0.3", default-features = false, features = ["sink", "std"] }
+smol = "2.0"
+jni = { version = "0.21", default-features = false }
+log = "0.4"
+rand = "0.8"
+hex = "0.4"
+serde_json = "1"
+
+[target.'cfg(target_os = "android")'.dependencies]
+android_logger = { version = "0.14", default-features = false }
+
+[dev-dependencies]
+env_logger = { version = "0.11", default-features = false, features = ["humantime"] }
+tungstenite = "0.24"
+
+# Stripped here, not left to the Android Gradle plugin: it packages a library it cannot strip as
+# it is, and with debug info this one is 147 MB per ABI instead of 8.6 MB.
+[profile.release]
+strip = true
+debug = false
+lto = true
+opt-level = "s"
+
+[lib]
+name = "pezkuwi_light"
+crate-type = ["cdylib", "rlib"]

bindings/pezkuwi-light/rust/src/engine.rs

@@ -0,0 +1,423 @@
+//! Embedded PezkuwiChain light client behind a loopback JSON-RPC WebSocket server.
+//!
+//! The wallet talks to its chains through `SocketService` (a JSON-RPC WebSocket client), so the
+//! light client is exposed the same way: `ws://127.0.0.1:<port>/<token>/<chain key>`. Every
+//! accepted connection adds its own smoldot chain instance; smoldot shares the underlying sync
+//! between instances of the same chain, so a connection costs a JSON-RPC frontend, not a sync.
+//!
+//! The port is bound to 127.0.0.1 only and every path carries a random token, so other apps on
+//! the device cannot drive the client without first learning the token from this process.
+
+use async_tungstenite::tungstenite::{
+    handshake::server::{ErrorResponse, Request, Response},
+    http::StatusCode,
+    Message,
+};
+use futures_util::{SinkExt as _, StreamExt as _};
+use crate::platform::{PezkuwiPlatform, Resolve};
+use smoldot_light::{
+    AddChainConfig, AddChainConfigJsonRpc, AddChainSuccess, ChainId,
+    Client, HandleRpcError, JsonRpcResponses,
+};
+use std::{
+    collections::HashMap,
+    fs, io,
+    net::{Ipv4Addr, SocketAddr, TcpListener, TcpStream},
+    num::NonZero,
+    path::PathBuf,
+    sync::{Arc, Mutex},
+    thread,
+    time::Duration,
+};
+
+type Platform = PezkuwiPlatform;
+
+/// How often the finalized state of each chain is written to disk, so that the next start
+/// resumes from it instead of syncing from the chain specification.
+const DATABASE_SAVE_INTERVAL: Duration = Duration::from_secs(60);
+const FIRST_DATABASE_SAVE: Duration = Duration::from_secs(20);
+
+/// Request id of the database export on a chain's own JSON-RPC frontend.
+const DATABASE_REQUEST_ID: &str = "pezkuwi-light-database";
+
+pub struct Engine {
+    inner: Arc<Inner>,
+    platform: PezkuwiPlatform,
+    port: u16,
+}
+
+struct Inner {
+    client: Mutex<Client<Platform>>,
+    chains: Mutex<HashMap<String, Registered>>,
+    executor: Arc<smol::Executor<'static>>,
+    token: String,
+    db_dir: PathBuf,
+}
+
+struct Registered {
+    spec: Arc<str>,
+    /// Instance added at registration. It keeps the chain synced while no connection is open and
+    /// serves the database export.
+    base: ChainId,
+    /// Base instance of the relay chain, for a teyrchain.
+    relay: Option<ChainId>,
+}
+
+#[derive(Debug)]
+pub enum Error {
+    UnknownRelayChain(String),
+    AlreadyRegistered(String),
+    AddChain(String),
+    Io(io::Error),
+}
+
+impl std::fmt::Display for Error {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Error::UnknownRelayChain(key) => write!(f, "relay chain {key} is not registered"),
+            Error::AlreadyRegistered(key) => write!(f, "chain {key} is already registered"),
+            Error::AddChain(err) => write!(f, "smoldot rejected the chain: {err}"),
+            Error::Io(err) => write!(f, "{err}"),
+        }
+    }
+}
+
+impl Engine {
+    /// Starts the light client and its loopback server. `db_dir` holds one finalized-state file
+    /// per chain key; `resolver` resolves the host names of peers.
+    pub fn start(db_dir: PathBuf, resolver: Arc<dyn Resolve>) -> Result<Engine, Error> {
+        fs::create_dir_all(&db_dir).map_err(Error::Io)?;
+        let listener =
+            TcpListener::bind(SocketAddr::from((Ipv4Addr::LOCALHOST, 0))).map_err(Error::Io)?;
+        let port = listener.local_addr().map_err(Error::Io)?.port();
+
+        let mut token = [0u8; 32];
+        rand::RngCore::fill_bytes(&mut rand::rngs::OsRng, &mut token);
+
+        let platform = PezkuwiPlatform::new(
+            env!("CARGO_PKG_NAME").into(),
+            env!("CARGO_PKG_VERSION").into(),
+            resolver,
+        );
+        let executor = Arc::new(smol::Executor::new());
+        let inner = Arc::new(Inner {
+            client: Mutex::new(Client::new(platform.clone())),
+            chains: Mutex::new(HashMap::new()),
+            executor: executor.clone(),
+            token: hex::encode(token),
+            db_dir,
+        });
+
+        let listener = smol::Async::new(listener).map_err(Error::Io)?;
+        executor.spawn(accept_loop(inner.clone(), listener)).detach();
+        thread::Builder::new()
+            .name("pezkuwi-light-rpc".into())
+            .spawn(move || smol::block_on(executor.run(futures_util::future::pending::<()>())))
+            .map_err(Error::Io)?;
+
+        Ok(Engine {
+            inner,
+            platform,
+            port,
+        })
+    }
+
+    /// Restricts new peer connections to secure WebSockets (`wss`), which look like any HTTPS
+    /// WebSocket on the wire. Off by default.
+    pub fn set_secure_only(&self, secure_only: bool) {
+        self.platform.set_secure_only(secure_only);
+    }
+
+    /// `ws://127.0.0.1:<port>/<token>`; a chain is reached at `<this>/<chain key>`.
+    pub fn base_url(&self) -> String {
+        format!("ws://127.0.0.1:{}/{}", self.port, self.inner.token)
+    }
+
+    /// Registers a chain under `key` and starts syncing it. A teyrchain names the key of its
+    /// already registered relay chain.
+    pub fn add_chain(&self, key: &str, spec: &str, relay_key: Option<&str>) -> Result<(), Error> {
+        let mut chains = self.inner.chains.lock().unwrap();
+        if chains.contains_key(key) {
+            return Err(Error::AlreadyRegistered(key.into()));
+        }
+        let relay = match relay_key {
+            Some(relay_key) => Some(
+                chains
+                    .get(relay_key)
+                    .ok_or_else(|| Error::UnknownRelayChain(relay_key.into()))?
+                    .base,
+            ),
+            None => None,
+        };
+
+        let database = fs::read_to_string(self.inner.database_path(key)).unwrap_or_default();
+        let AddChainSuccess {
+            chain_id,
+            json_rpc_responses,
+        } = self
+            .inner
+            .client
+            .lock()
+            .unwrap()
+            .add_chain(AddChainConfig {
+                user_data: (),
+                specification: spec,
+                database_content: &database,
+                potential_relay_chains: relay.into_iter(),
+                json_rpc: AddChainConfigJsonRpc::Enabled {
+                    max_pending_requests: NonZero::new(4).unwrap(),
+                    max_subscriptions: 0,
+                },
+            })
+            .map_err(|err| Error::AddChain(err.to_string()))?;
+
+        chains.insert(
+            key.into(),
+            Registered {
+                spec: spec.into(),
+                base: chain_id,
+                relay,
+            },
+        );
+        self.inner
+            .executor
+            .spawn(save_database(
+                self.inner.clone(),
+                key.to_owned(),
+                chain_id,
+                json_rpc_responses.expect("JSON-RPC is enabled"),
+            ))
+            .detach();
+        Ok(())
+    }
+}
+
+impl Inner {
+    fn database_path(&self, key: &str) -> PathBuf {
+        database_path(&self.db_dir, key)
+    }
+}
+
+fn database_path(db_dir: &std::path::Path, key: &str) -> PathBuf {
+    // Keys come from the app (genesis hashes); keep them from escaping the directory anyway.
+    let file: String = key
+        .chars()
+        .map(|c| if c.is_ascii_alphanumeric() { c } else { '_' })
+        .collect();
+    db_dir.join(format!("{file}.db"))
+}
+
+/// Constant-time comparison, so the token cannot be guessed byte by byte from timing.
+fn token_matches(token: &str, candidate: &str) -> bool {
+    let (a, b) = (token.as_bytes(), candidate.as_bytes());
+    a.len() == b.len() && a.iter().zip(b).fold(0u8, |acc, (x, y)| acc | (x ^ y)) == 0
+}
+
+async fn accept_loop(inner: Arc<Inner>, listener: smol::Async<TcpListener>) {
+    loop {
+        match listener.accept().await {
+            Ok((stream, _)) => inner.executor.spawn(serve(inner.clone(), stream)).detach(),
+            Err(err) => {
+                log::warn!("loopback accept failed: {err}");
+                smol::Timer::after(Duration::from_millis(100)).await;
+            }
+        }
+    }
+}
+
+/// Maps `/<token>/<key>` to a registered chain key, rejecting everything else during the
+/// WebSocket handshake.
+fn route(token: &str, is_registered: impl Fn(&str) -> bool, path: &str) -> Option<String> {
+    let (candidate, key) = path.strip_prefix('/')?.split_once('/')?;
+    (token_matches(token, candidate) && is_registered(key)).then(|| key.to_owned())
+}
+
+async fn serve(inner: Arc<Inner>, stream: smol::Async<TcpStream>) {
+    let mut routed = None;
+    let handshake = async_tungstenite::accept_hdr_async(stream, |request: &Request, response: Response| {
+        routed = route(
+            &inner.token,
+            |key| inner.chains.lock().unwrap().contains_key(key),
+            request.uri().path(),
+        );
+        if routed.is_some() {
+            Ok(response)
+        } else {
+            let mut rejection = ErrorResponse::new(None);
+            *rejection.status_mut() = StatusCode::NOT_FOUND;
+            Err(rejection)
+        }
+    })
+    .await;
+    let (Ok(socket), Some(key)) = (handshake, routed) else {
+        return;
+    };
+
+    let (chain_id, mut responses) = {
+        let chains = inner.chains.lock().unwrap();
+        let registered = &chains[&key];
+        let added = inner.client.lock().unwrap().add_chain(AddChainConfig {
+            user_data: (),
+            specification: &registered.spec,
+            // The base instance already holds the chain; smoldot shares it with this one.
+            database_content: "",
+            potential_relay_chains: registered.relay.into_iter(),
+            json_rpc: AddChainConfigJsonRpc::Enabled {
+                max_pending_requests: NonZero::new(128).unwrap(),
+                max_subscriptions: 1024,
+            },
+        });
+        match added {
+            Ok(success) => (success.chain_id, success.json_rpc_responses.expect("JSON-RPC is enabled")),
+            Err(err) => {
+                log::warn!("{key}: cannot open a connection instance: {err}");
+                return;
+            }
+        }
+    };
+
+    let (mut sink, mut source) = socket.split();
+    let (overflow_tx, overflow_rx) = smol::channel::unbounded::<String>();
+
+    let inbound = async {
+        while let Some(Ok(message)) = source.next().await {
+            let request = match message {
+                Message::Text(text) => text,
+                Message::Binary(bytes) => match String::from_utf8(bytes) {
+                    Ok(text) => text,
+                    Err(_) => continue,
+                },
+                Message::Close(_) => break,
+                _ => continue,
+            };
+            let refused = inner.client.lock().unwrap().json_rpc_request(request, chain_id);
+            if let Err(HandleRpcError::TooManyPendingRequests { json_rpc_request }) = refused {
+                if let Some(error) = busy_error(&json_rpc_request) {
+                    let _ = overflow_tx.send(error).await;
+                }
+            }
+        }
+    };
+    let outbound = async {
+        loop {
+            let response = futures_util::future::select(
+                Box::pin(responses.next()),
+                Box::pin(overflow_rx.recv()),
+            )
+            .await;
+            let text = match response {
+                futures_util::future::Either::Left((Some(text), _)) => text,
+                futures_util::future::Either::Right((Ok(text), _)) => text,
+                _ => break,
+            };
+            if sink.send(Message::Text(text)).await.is_err() {
+                break;
+            }
+        }
+    };
+    futures_util::future::select(Box::pin(inbound), Box::pin(outbound)).await;
+
+    let () = inner.client.lock().unwrap().remove_chain(chain_id);
+}
+
+/// JSON-RPC error for a request smoldot refused because its queue is full, so the caller gets an
+/// answer instead of waiting forever. Notifications (no id) get none.
+fn busy_error(request: &str) -> Option<String> {
+    let id = serde_json::from_str::<serde_json::Value>(request).ok()?.get("id")?.clone();
+    Some(
+        serde_json::json!({
+            "jsonrpc": "2.0",
+            "id": id,
+            "error": { "code": -32000, "message": "light client is busy, retry" },
+        })
+        .to_string(),
+    )
+}
+
+/// Periodically writes the chain's finalized state to disk through its base instance.
+async fn save_database(
+    inner: Arc<Inner>,
+    key: String,
+    chain_id: ChainId,
+    mut responses: JsonRpcResponses<Platform>,
+) {
+    let request = serde_json::json!({
+        "jsonrpc": "2.0",
+        "id": DATABASE_REQUEST_ID,
+        "method": "chainHead_unstable_finalizedDatabase",
+        "params": [],
+    })
+    .to_string();
+    let path = inner.database_path(&key);
+    let mut wait = FIRST_DATABASE_SAVE;
+    loop {
+        smol::Timer::after(wait).await;
+        wait = DATABASE_SAVE_INTERVAL;
+        if inner
+            .client
+            .lock()
+            .unwrap()
+            .json_rpc_request(request.clone(), chain_id)
+            .is_err()
+        {
+            continue;
+        }
+        while let Some(response) = responses.next().await {
+            let response: serde_json::Value = match serde_json::from_str(&response) {
+                Ok(value) => value,
+                Err(_) => continue,
+            };
+            if response.get("id").and_then(|id| id.as_str()) != Some(DATABASE_REQUEST_ID) {
+                continue;
+            }
+            if let Some(database) = response.get("result").and_then(|db| db.as_str()) {
+                if let Err(err) = write_atomically(&path, database) {
+                    log::warn!("{key}: cannot save the light client database: {err}");
+                }
+            }
+            break;
+        }
+    }
+}
+
+/// Writes through a temporary file and a rename, so a crash never leaves a torn database.
+fn write_atomically(path: &std::path::Path, contents: &str) -> io::Result<()> {
+    let temporary = path.with_extension("db.tmp");
+    fs::write(&temporary, contents)?;
+    fs::rename(&temporary, path)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn route_requires_the_token_and_a_registered_chain() {
+        let token = "ab".repeat(32);
+        let route = |path: &str| route(&token, |key| key == "people", path);
+        assert_eq!(route(&format!("/{token}/people")), Some("people".into()));
+        assert_eq!(route(&format!("/{token}/relay")), None);
+        assert_eq!(route(&format!("/{}/people", "ac".repeat(32))), None);
+        assert_eq!(route(&format!("/{}/people", &token[1..])), None);
+        assert_eq!(route(&format!("/{token}people")), None);
+        assert_eq!(route("/people"), None);
+        assert_eq!(route(&format!("{token}/people")), None);
+    }
+
+    #[test]
+    fn database_path_stays_inside_the_directory() {
+        assert_eq!(
+            database_path(std::path::Path::new("/data"), "../../etc/passwd"),
+            PathBuf::from("/data/______etc_passwd.db")
+        );
+    }
+
+    #[test]
+    fn busy_error_answers_the_request_id() {
+        let error = busy_error(r#"{"jsonrpc":"2.0","id":7,"method":"state_call","params":[]}"#).unwrap();
+        let error: serde_json::Value = serde_json::from_str(&error).unwrap();
+        assert_eq!(error["id"], 7);
+        assert_eq!(error["error"]["code"], -32000);
+        assert_eq!(busy_error(r#"{"jsonrpc":"2.0","method":"x"}"#), None);
+    }
+}

bindings/pezkuwi-light/rust/src/lib.rs

@@ -0,0 +1,170 @@
+//! JNI surface of the embedded PezkuwiChain light client. See [`engine`] for how it works.
+
+pub mod engine;
+pub mod platform;
+
+use engine::Engine;
+use jni::objects::{GlobalRef, JObject, JObjectArray, JString};
+use jni::sys::{jboolean, jstring, JNI_TRUE};
+use jni::{JNIEnv, JavaVM};
+use platform::Resolve;
+use std::{io, net::IpAddr, sync::Arc, sync::OnceLock};
+
+/// One light client per process: smoldot shares chains between its instances, and the app
+/// reaches it through a single loopback server.
+static ENGINE: OnceLock<Result<Engine, String>> = OnceLock::new();
+
+fn engine() -> Option<&'static Engine> {
+    ENGINE.get().and_then(|engine| engine.as_ref().ok())
+}
+
+fn throw(env: &mut JNIEnv, message: &str) {
+    let _ = env.throw_new("java/lang/IllegalStateException", message);
+}
+
+fn read_string(env: &mut JNIEnv, value: &JString) -> Option<String> {
+    env.get_string(value).ok().map(Into::into)
+}
+
+/// Resolves peer host names through the app's `HostResolver`, so the light client follows the
+/// app's DNS policy (DNS over HTTPS first).
+struct AppResolver {
+    vm: JavaVM,
+    resolver: GlobalRef,
+}
+
+impl Resolve for AppResolver {
+    fn resolve(&self, host: &str) -> io::Result<Vec<IpAddr>> {
+        // Blocking-pool threads are reused, so they stay attached instead of paying an attach
+        // per lookup.
+        let mut env = self
+            .vm
+            .attach_current_thread_permanently()
+            .map_err(|_| lookup_error(host, "cannot attach to the JVM"))?;
+        // The frame's own result must convert from `jni::errors::Error`; the lookup's outcome
+        // travels inside it.
+        env.with_local_frame(8, |env| -> jni::errors::Result<_> {
+            Ok(lookup(env, &self.resolver, host))
+        })
+        .unwrap_or_else(|_| Err(lookup_error(host, "JNI frame failed")))
+    }
+}
+
+fn lookup_error(host: &str, what: &str) -> io::Error {
+    io::Error::new(io::ErrorKind::Other, format!("{host}: {what}"))
+}
+
+/// Calls `String[] resolve(String)` on the app's resolver. A thrown exception (an unknown host)
+/// is cleared and reported as an error.
+fn lookup(env: &mut JNIEnv, resolver: &GlobalRef, host: &str) -> io::Result<Vec<IpAddr>> {
+    let failed = |what| lookup_error(host, what);
+    let name = env.new_string(host).map_err(|_| failed("invalid name"))?;
+    let answer = env.call_method(
+        resolver,
+        "resolve",
+        "(Ljava/lang/String;)[Ljava/lang/String;",
+        &[(&name).into()],
+    );
+    if env.exception_check().unwrap_or(false) {
+        let _ = env.exception_clear();
+        return Err(failed("no address"));
+    }
+    let answer: JObjectArray = answer
+        .and_then(|value| value.l())
+        .map_err(|_| failed("resolver failed"))?
+        .into();
+    let count = env.get_array_length(&answer).map_err(|_| failed("bad answer"))?;
+    let mut addresses = Vec::new();
+    for index in 0..count {
+        let element: JString = env
+            .get_object_array_element(&answer, index)
+            .map_err(|_| failed("bad answer"))?
+            .into();
+        if let Some(address) = read_string(env, &element).and_then(|text| text.parse().ok()) {
+            addresses.push(address);
+        }
+    }
+    Ok(addresses)
+}
+
+/// Starts the light client (once per process) and returns its loopback base URL.
+#[no_mangle]
+pub extern "system" fn Java_io_novafoundation_nova_lightclient_PezkuwiLight_start<'local>(
+    mut env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    database_dir: JString<'local>,
+    resolver: JObject<'local>,
+) -> jstring {
+    let Some(database_dir) = read_string(&mut env, &database_dir) else {
+        throw(&mut env, "invalid database directory");
+        return std::ptr::null_mut();
+    };
+    let resolver = match (env.get_java_vm(), env.new_global_ref(&resolver)) {
+        (Ok(vm), Ok(resolver)) => AppResolver { vm, resolver },
+        _ => {
+            throw(&mut env, "invalid resolver");
+            return std::ptr::null_mut();
+        }
+    };
+    let started = ENGINE.get_or_init(|| {
+        #[cfg(target_os = "android")]
+        android_logger::init_once(
+            android_logger::Config::default()
+                .with_max_level(log::LevelFilter::Info)
+                .with_tag("PezkuwiLight"),
+        );
+        Engine::start(database_dir.into(), Arc::new(resolver)).map_err(|err| err.to_string())
+    });
+    match started {
+        Ok(engine) => match env.new_string(engine.base_url()) {
+            Ok(url) => url.into_raw(),
+            Err(_) => std::ptr::null_mut(),
+        },
+        Err(err) => {
+            throw(&mut env, err);
+            std::ptr::null_mut()
+        }
+    }
+}
+
+/// Registers a chain under `key`; a teyrchain passes its relay chain's key.
+#[no_mangle]
+pub extern "system" fn Java_io_novafoundation_nova_lightclient_PezkuwiLight_addChain<'local>(
+    mut env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    key: JString<'local>,
+    chain_spec: JString<'local>,
+    relay_key: JString<'local>,
+) {
+    let Some(engine) = engine() else {
+        throw(&mut env, "light client is not started");
+        return;
+    };
+    let (Some(key), Some(chain_spec)) =
+        (read_string(&mut env, &key), read_string(&mut env, &chain_spec))
+    else {
+        throw(&mut env, "invalid chain key or specification");
+        return;
+    };
+    let relay_key = if relay_key.is_null() {
+        None
+    } else {
+        read_string(&mut env, &relay_key)
+    };
+    if let Err(err) = engine.add_chain(&key, &chain_spec, relay_key.as_deref()) {
+        throw(&mut env, &err.to_string());
+    }
+}
+
+/// Restricts new peer connections to secure WebSockets.
+#[no_mangle]
+pub extern "system" fn Java_io_novafoundation_nova_lightclient_PezkuwiLight_setSecureOnly<'local>(
+    mut env: JNIEnv<'local>,
+    _this: JObject<'local>,
+    secure_only: jboolean,
+) {
+    match engine() {
+        Some(engine) => engine.set_secure_only(secure_only == JNI_TRUE),
+        None => throw(&mut env, "light client is not started"),
+    }
+}

bindings/pezkuwi-light/rust/src/platform.rs

@@ -0,0 +1,423 @@
+//! smoldot platform for the wallet: secure WebSockets and an app-supplied name resolver.
+//!
+//! smoldot's own `DefaultPlatform` cannot open `wss` connections and resolves names through the
+//! system resolver. Where our domains are blocked, both fail: a poisoned DNS answer decides where
+//! the client connects, and plain libp2p TCP is recognisable on the wire. This platform:
+//! - opens `/dns/<host>/tcp/<port>/wss` over TLS (rustls, Mozilla roots), so a connection looks
+//!   like any HTTPS WebSocket;
+//! - resolves every name through [`Resolve`], which the app backs with its DNS-over-HTTPS
+//!   resolver, so the light client and the rest of the app follow one DNS policy;
+//! - can be restricted to secure WebSockets only ([`PezkuwiPlatform::set_secure_only`]).
+//!
+//! The peer's identity is still checked end to end by libp2p Noise, so neither the TLS terminator
+//! in front of a node nor a CDN can alter what the client verifies.
+
+use futures_util::{future, AsyncRead, AsyncWrite, FutureExt as _};
+use smoldot_light::platform::{
+    with_buffers, Address, ConnectionType, LogLevel, MultiStreamAddress,
+    MultiStreamWebRtcConnection, PlatformRef, SubstreamDirection,
+};
+use std::{
+    borrow::Cow,
+    future::Future,
+    fmt::{self, Write as _},
+    io,
+    net::{self, SocketAddr},
+    panic,
+    pin::Pin,
+    sync::{
+        atomic::{AtomicBool, Ordering},
+        Arc,
+    },
+    thread,
+    time::{Duration, Instant, UNIX_EPOCH},
+};
+
+/// Resolves a host name to addresses. Called on a blocking thread.
+pub trait Resolve: Send + Sync + 'static {
+    fn resolve(&self, host: &str) -> io::Result<Vec<net::IpAddr>>;
+}
+
+/// The operating system's resolver, for tests and hosts without an app resolver.
+pub struct SystemResolver;
+
+impl Resolve for SystemResolver {
+    fn resolve(&self, host: &str) -> io::Result<Vec<net::IpAddr>> {
+        use std::net::ToSocketAddrs as _;
+        Ok((host, 0).to_socket_addrs()?.map(|addr| addr.ip()).collect())
+    }
+}
+
+/// Bound on each TCP connection attempt, so an address that silently drops packets does not hold
+/// a connection slot.
+const CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
+
+#[derive(Clone)]
+pub struct PezkuwiPlatform(Arc<Shared>);
+
+struct Shared {
+    client_name: String,
+    client_version: String,
+    executor: Arc<smol::Executor<'static>>,
+    resolver: Arc<dyn Resolve>,
+    tls: futures_rustls::TlsConnector,
+    secure_only: AtomicBool,
+}
+
+// smoldot requires `UnwindSafe`. A panic inside a task is caught at the task boundary
+// (`spawn_task`), and nothing here is left half-updated across it: the resolver is called
+// through `&self`, and the TLS configuration is immutable.
+impl panic::UnwindSafe for PezkuwiPlatform {}
+impl panic::RefUnwindSafe for PezkuwiPlatform {}
+
+impl PezkuwiPlatform {
+    pub fn new(client_name: String, client_version: String, resolver: Arc<dyn Resolve>) -> Self {
+        let executor = Arc::new(smol::Executor::new());
+        let threads = thread::available_parallelism().map_or(2, |n| n.get().min(4));
+        for n in 0..threads {
+            let executor = executor.clone();
+            thread::Builder::new()
+                .name(format!("pezkuwi-light-{n}"))
+                .spawn(move || smol::block_on(executor.run(future::pending::<()>())))
+                .expect("cannot spawn a light client thread");
+        }
+
+        let roots = rustls::RootCertStore {
+            roots: webpki_roots::TLS_SERVER_ROOTS.to_vec(),
+        };
+        let tls = rustls::ClientConfig::builder_with_provider(Arc::new(
+            rustls::crypto::ring::default_provider(),
+        ))
+        .with_safe_default_protocol_versions()
+        .expect("ring supports the default protocol versions")
+        .with_root_certificates(roots)
+        .with_no_client_auth();
+
+        PezkuwiPlatform(Arc::new(Shared {
+            client_name,
+            client_version,
+            executor,
+            resolver,
+            tls: futures_rustls::TlsConnector::from(Arc::new(tls)),
+            secure_only: AtomicBool::new(false),
+        }))
+    }
+
+    /// Restricts new connections to secure WebSockets. Open connections are kept.
+    pub fn set_secure_only(&self, secure_only: bool) {
+        self.0.secure_only.store(secure_only, Ordering::Relaxed);
+    }
+}
+
+/// A connected byte stream: plain TCP, WebSocket, or WebSocket over TLS.
+pub trait Socket: AsyncRead + AsyncWrite + Send {}
+impl<T: AsyncRead + AsyncWrite + Send> Socket for T {}
+
+type BoxedSocket = Pin<Box<dyn Socket>>;
+type Connecting = future::BoxFuture<'static, io::Result<BoxedSocket>>;
+
+#[pin_project::pin_project]
+pub struct Stream(#[pin] with_buffers::WithBuffers<Connecting, BoxedSocket, Instant>);
+
+/// Where to connect and what to speak once connected.
+struct Target {
+    host: Host,
+    port: u16,
+    websocket: Option<WebSocket>,
+}
+
+enum Host {
+    Ip(net::IpAddr),
+    Name(String),
+}
+
+struct WebSocket {
+    /// `Host` header value.
+    authority: String,
+    /// TLS server name, for `wss`.
+    tls_name: Option<String>,
+}
+
+fn target(address: Address) -> Target {
+    match address {
+        Address::TcpIp { ip, port } => Target {
+            host: Host::Ip(ip),
+            port,
+            websocket: None,
+        },
+        Address::TcpDns { hostname, port } => Target {
+            host: Host::Name(hostname.into()),
+            port,
+            websocket: None,
+        },
+        Address::WebSocketIp { ip, port } => {
+            Target {
+                host: Host::Ip(ip),
+                port,
+                websocket: Some(WebSocket {
+                    authority: SocketAddr::from((ip, port)).to_string(),
+                    tls_name: None,
+                }),
+            }
+        }
+        Address::WebSocketDns {
+            hostname,
+            port,
+            secure,
+        } => Target {
+            host: Host::Name(hostname.into()),
+            port,
+            websocket: Some(WebSocket {
+                authority: if (secure && port == 443) || (!secure && port == 80) {
+                    hostname.into()
+                } else {
+                    format!("{hostname}:{port}")
+                },
+                tls_name: secure.then(|| hostname.into()),
+            }),
+        },
+    }
+}
+
+/// IPv4 first: a resolver may return IPv6 addresses on a network without an IPv6 route, and a
+/// dead route would otherwise cost a full connect timeout before every connection.
+fn ordered(mut addresses: Vec<net::IpAddr>) -> Vec<net::IpAddr> {
+    let mut seen = std::collections::HashSet::new();
+    addresses.retain(|address| seen.insert(*address));
+    addresses.sort_by_key(|address| address.is_ipv6());
+    addresses
+}
+
+async fn connect_tcp(shared: Arc<Shared>, host: Host, port: u16) -> io::Result<smol::net::TcpStream> {
+    let addresses = match host {
+        Host::Ip(address) => vec![address],
+        Host::Name(name) => {
+            let resolver = shared.resolver.clone();
+            ordered(smol::unblock(move || resolver.resolve(&name)).await?)
+        }
+    };
+    let mut last_error = io::Error::new(io::ErrorKind::NotFound, "the name has no address");
+    for address in addresses {
+        let attempt = smol::net::TcpStream::connect(SocketAddr::from((address, port)));
+        let timeout = async {
+            smol::Timer::after(CONNECT_TIMEOUT).await;
+            Err(io::Error::new(io::ErrorKind::TimedOut, "connect timed out"))
+        };
+        match future::select(Box::pin(attempt), Box::pin(timeout)).await.factor_first().0 {
+            Ok(socket) => {
+                let _ = socket.set_nodelay(true);
+                return Ok(socket);
+            }
+            Err(err) => last_error = err,
+        }
+    }
+    Err(last_error)
+}
+
+async fn connect(shared: Arc<Shared>, target: Target) -> io::Result<BoxedSocket> {
+    let tcp = connect_tcp(shared.clone(), target.host, target.port).await?;
+    let Some(websocket) = target.websocket else {
+        return Ok(Box::pin(tcp));
+    };
+    match &websocket.tls_name {
+        None => websocket_handshake(tcp, &websocket.authority).await,
+        Some(name) => {
+            let name = rustls::pki_types::ServerName::try_from(name.clone())
+                .map_err(|err| io::Error::new(io::ErrorKind::InvalidInput, err))?;
+            let tls = shared.tls.connect(name, tcp).await?;
+            websocket_handshake(tls, &websocket.authority).await
+        }
+    }
+}
+
+async fn websocket_handshake<T>(socket: T, authority: &str) -> io::Result<BoxedSocket>
+where
+    T: AsyncRead + AsyncWrite + Send + Unpin + 'static,
+{
+    let connection = smoldot::libp2p::websocket::websocket_client_handshake(
+        smoldot::libp2p::websocket::Config {
+            tcp_socket: socket,
+            host: authority,
+            url: "/",
+        },
+    )
+    .await?;
+    Ok(Box::pin(connection))
+}
+
+impl PlatformRef for PezkuwiPlatform {
+    type Delay = future::Map<smol::Timer, fn(Instant) -> ()>;
+    type Instant = Instant;
+    type MultiStream = std::convert::Infallible;
+    type Stream = Stream;
+    type StreamConnectFuture = future::Ready<Self::Stream>;
+    type MultiStreamConnectFuture = future::Pending<MultiStreamWebRtcConnection<Self::MultiStream>>;
+    type ReadWriteAccess<'a> = with_buffers::ReadWriteAccess<'a, Instant>;
+    type StreamUpdateFuture<'a> = future::BoxFuture<'a, ()>;
+    type StreamErrorRef<'a> = &'a io::Error;
+    type NextSubstreamFuture<'a> = future::Pending<Option<(Self::Stream, SubstreamDirection)>>;
+
+    fn now_from_unix_epoch(&self) -> Duration {
+        UNIX_EPOCH.elapsed().expect("the clock is set after 1970")
+    }
+
+    fn now(&self) -> Instant {
+        Instant::now()
+    }
+
+    fn fill_random_bytes(&self, buffer: &mut [u8]) {
+        rand::RngCore::fill_bytes(&mut rand::thread_rng(), buffer);
+    }
+
+    fn sleep(&self, duration: Duration) -> Self::Delay {
+        smol::Timer::after(duration).map(drop as fn(Instant))
+    }
+
+    fn sleep_until(&self, when: Instant) -> Self::Delay {
+        smol::Timer::at(when).map(drop as fn(Instant))
+    }
+
+    fn spawn_task(&self, _task_name: Cow<str>, task: impl Future<Output = ()> + Send + 'static) {
+        self.0
+            .executor
+            .spawn(panic::AssertUnwindSafe(task).catch_unwind().map(drop))
+            .detach();
+    }
+
+    fn log<'a>(
+        &self,
+        log_level: LogLevel,
+        log_target: &'a str,
+        message: &'a str,
+        key_values: impl Iterator<Item = (&'a str, &'a dyn fmt::Display)>,
+    ) {
+        let level = match log_level {
+            LogLevel::Error => log::Level::Error,
+            LogLevel::Warn => log::Level::Warn,
+            LogLevel::Info => log::Level::Info,
+            LogLevel::Debug => log::Level::Debug,
+            LogLevel::Trace => log::Level::Trace,
+        };
+        if !log::log_enabled!(target: log_target, level) {
+            return;
+        }
+        let mut line = String::from(message);
+        for (n, (key, value)) in key_values.enumerate() {
+            let _ = write!(line, "{}{key}={value}", if n == 0 { "; " } else { ", " });
+        }
+        log::log!(target: log_target, level, "{line}");
+    }
+
+    fn client_name(&self) -> Cow<'_, str> {
+        Cow::Borrowed(&self.0.client_name)
+    }
+
+    fn client_version(&self) -> Cow<'_, str> {
+        Cow::Borrowed(&self.0.client_version)
+    }
+
+    fn supports_connection_type(&self, connection_type: ConnectionType) -> bool {
+        match connection_type {
+            ConnectionType::WebSocketDns { secure: true, .. } => true,
+            ConnectionType::TcpIpv4
+            | ConnectionType::TcpIpv6
+            | ConnectionType::TcpDns
+            | ConnectionType::WebSocketIpv4 { .. }
+            | ConnectionType::WebSocketIpv6 { .. }
+            | ConnectionType::WebSocketDns { secure: false, .. } => {
+                !self.0.secure_only.load(Ordering::Relaxed)
+            }
+            // WebRTC needs a multi-stream implementation, which a native client has no use for.
+            _ => false,
+        }
+    }
+
+    fn connect_stream(&self, address: Address) -> Self::StreamConnectFuture {
+        let connecting: Connecting = Box::pin(connect(self.0.clone(), target(address)));
+        future::ready(Stream(with_buffers::WithBuffers::new(connecting)))
+    }
+
+    fn connect_multistream(&self, _address: MultiStreamAddress) -> Self::MultiStreamConnectFuture {
+        unreachable!("no multi-stream connection type is supported")
+    }
+
+    fn open_out_substream(&self, connection: &mut Self::MultiStream) {
+        match *connection {}
+    }
+
+    fn next_substream<'a>(
+        &self,
+        connection: &'a mut Self::MultiStream,
+    ) -> Self::NextSubstreamFuture<'a> {
+        match *connection {}
+    }
+
+    fn read_write_access<'a>(
+        &self,
+        stream: Pin<&'a mut Self::Stream>,
+    ) -> Result<Self::ReadWriteAccess<'a>, &'a io::Error> {
+        stream.project().0.read_write_access(Instant::now())
+    }
+
+    fn wait_read_write_again<'a>(&self, stream: Pin<&'a mut Self::Stream>) -> Self::StreamUpdateFuture<'a> {
+        Box::pin(
+            stream
+                .project()
+                .0
+                .wait_read_write_again(|when| smol::Timer::at(when).map(drop)),
+        )
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn platform() -> PezkuwiPlatform {
+        PezkuwiPlatform::new("test".into(), "0".into(), Arc::new(SystemResolver))
+    }
+
+    #[test]
+    fn secure_only_admits_nothing_but_secure_websockets() {
+        let platform = platform();
+        let plain = [
+            ConnectionType::TcpIpv4,
+            ConnectionType::TcpIpv6,
+            ConnectionType::TcpDns,
+            ConnectionType::WebSocketIpv4 { remote_is_localhost: false },
+            ConnectionType::WebSocketIpv6 { remote_is_localhost: false },
+            ConnectionType::WebSocketDns { secure: false, remote_is_localhost: false },
+        ];
+        let secure = ConnectionType::WebSocketDns { secure: true, remote_is_localhost: false };
+        assert!(platform.supports_connection_type(secure));
+        assert!(plain.iter().all(|kind| platform.supports_connection_type(*kind)));
+
+        platform.set_secure_only(true);
+        assert!(platform.supports_connection_type(secure));
+        assert!(plain.iter().all(|kind| !platform.supports_connection_type(*kind)));
+    }
+
+    #[test]
+    fn websocket_targets_carry_the_right_host_header_and_tls_name() {
+        let wss = target(Address::WebSocketDns { hostname: "node.example", port: 443, secure: true });
+        let ws = wss.websocket.unwrap();
+        assert_eq!((ws.authority.as_str(), ws.tls_name.as_deref()), ("node.example", Some("node.example")));
+
+        let wss = target(Address::WebSocketDns { hostname: "node.example", port: 8443, secure: true });
+        assert_eq!(wss.websocket.unwrap().authority, "node.example:8443");
+
+        let ws = target(Address::WebSocketDns { hostname: "node.example", port: 30335, secure: false });
+        let ws = ws.websocket.unwrap();
+        assert_eq!((ws.authority.as_str(), ws.tls_name), ("node.example:30335", None));
+
+        assert!(target(Address::TcpDns { hostname: "node.example", port: 30333 }).websocket.is_none());
+    }
+
+    #[test]
+    fn ipv4_is_tried_before_ipv6() {
+        let v6: net::IpAddr = "2001:db8::1".parse().unwrap();
+        let v4: net::IpAddr = "192.0.2.1".parse().unwrap();
+        let other: net::IpAddr = "192.0.2.2".parse().unwrap();
+        assert_eq!(ordered(vec![v6, v4, other, v4]), vec![v4, other, v6]);
+    }
+}

bindings/pezkuwi-light/rust/tests/loopback.rs

@@ -0,0 +1,233 @@
+//! End-to-end tests of the loopback server.
+//!
+//! The Zagros test syncs the live testnet, so it is ignored by default. Run it with the chain
+//! specifications of the relay chain and People:
+//!
+//! ```sh
+//! PEZKUWI_LIGHT_RELAY_SPEC=zagros.json PEZKUWI_LIGHT_PEOPLE_SPEC=people-zagros.json \
+//!     cargo test --release -- --ignored --nocapture
+//! ```
+
+use pezkuwi_light::{engine::Engine, platform::SystemResolver};
+use std::{
+    net::TcpStream,
+    sync::Arc,
+    time::{Duration, Instant},
+};
+use tungstenite::{stream::MaybeTlsStream, Message, WebSocket};
+
+type Socket = WebSocket<MaybeTlsStream<TcpStream>>;
+
+fn temporary_dir(name: &str) -> std::path::PathBuf {
+    let dir = std::env::temp_dir().join(format!("pezkuwi-light-{name}-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    dir
+}
+
+fn start(db_dir: std::path::PathBuf) -> Engine {
+    // RUST_LOG=... shows smoldot's own timeline when a measurement needs explaining.
+    let _ = env_logger::builder().format_timestamp_millis().is_test(true).try_init();
+    Engine::start(db_dir, Arc::new(SystemResolver)).unwrap()
+}
+
+/// Connects to the loopback server; a read that waits longer than a sync can take fails the test
+/// instead of hanging it.
+fn connect(url: String) -> Socket {
+    let (socket, _) = tungstenite::connect(url).unwrap();
+    if let MaybeTlsStream::Plain(stream) = socket.get_ref() {
+        stream.set_read_timeout(Some(Duration::from_secs(180))).unwrap();
+    }
+    socket
+}
+
+fn rpc(socket: &mut Socket, id: u64, method: &str, params: serde_json::Value) {
+    let request = serde_json::json!({"jsonrpc": "2.0", "id": id, "method": method, "params": params});
+    socket.send(Message::Text(request.to_string())).unwrap();
+}
+
+fn next_json(socket: &mut Socket) -> serde_json::Value {
+    loop {
+        if let Message::Text(text) = socket.read().unwrap() {
+            return serde_json::from_str(&text).unwrap();
+        }
+    }
+}
+
+fn answer(socket: &mut Socket, id: u64) -> serde_json::Value {
+    loop {
+        let message = next_json(socket);
+        if message["id"] == id {
+            return message;
+        }
+    }
+}
+
+/// `Vec<u8>` SCALE encoding: compact length, then the bytes.
+fn scale_bytes(bytes: &[u8]) -> String {
+    assert!(bytes.len() < 64, "single-byte compact length only");
+    format!("0x{:02x}{}", (bytes.len() as u8) << 2, hex::encode(bytes))
+}
+
+#[test]
+fn a_path_without_the_token_is_refused() {
+    let engine = start(temporary_dir("refused"));
+    let base = engine.base_url();
+    let (_, token) = base.rsplit_once('/').unwrap();
+    let wrong = format!("{}{}", &token[..token.len() - 1], if token.ends_with('0') { '1' } else { '0' });
+    let port = base.split(':').nth(2).unwrap().split('/').next().unwrap();
+
+    for url in [
+        format!("ws://127.0.0.1:{port}/{wrong}/relay"),
+        format!("ws://127.0.0.1:{port}/relay"),
+        // The token is right but no chain is registered under the key.
+        format!("{base}/relay"),
+    ] {
+        match tungstenite::connect(&url) {
+            Err(tungstenite::Error::Http(response)) => assert_eq!(response.status(), 404, "{url}"),
+            other => panic!("{url} was not refused: {:?}", other.map(|_| ())),
+        }
+    }
+}
+
+#[test]
+#[ignore = "syncs the live Zagros testnet; needs PEZKUWI_LIGHT_RELAY_SPEC and PEZKUWI_LIGHT_PEOPLE_SPEC"]
+fn resolves_kurd_names_on_zagros_people() {
+    let relay = std::fs::read_to_string(std::env::var("PEZKUWI_LIGHT_RELAY_SPEC").unwrap()).unwrap();
+    let people = std::fs::read_to_string(std::env::var("PEZKUWI_LIGHT_PEOPLE_SPEC").unwrap()).unwrap();
+    let db_dir = temporary_dir("zagros");
+    let started = Instant::now();
+
+    let engine = start(db_dir.clone());
+    engine.add_chain("relay", &relay, None).unwrap();
+    engine.add_chain("people", &people, Some("relay")).unwrap();
+    assert!(engine.add_chain("people", &people, Some("relay")).is_err());
+
+    let mut socket = connect(format!("{}/people", engine.base_url()));
+    rpc(&mut socket, 1, "chain_subscribeFinalizedHeads", serde_json::json!([]));
+    loop {
+        if next_json(&mut socket).pointer("/params/result/number").is_some() {
+            break;
+        }
+    }
+    println!("first verified People head after {:.1}s", started.elapsed().as_secs_f64());
+    let synced_at = std::time::SystemTime::now();
+
+    // Registered on Zagros People by the Meclis grant of 2026-10-31: Governance-owned, active,
+    // official. The full node answers the same bytes.
+    rpc(&mut socket, 2, "state_call", serde_json::json!(["NavnisanApi_resolve", scale_bytes(b"dks.kurd")]));
+    let resolved = answer(&mut socket, 2)["result"].as_str().unwrap().to_owned();
+    assert!(
+        resolved.starts_with("0x0195c0de27b9a054a3a68cf2bb26abf99071ad46c2485295bb4120185a811a042f"),
+        "{resolved}"
+    );
+
+    rpc(&mut socket, 3, "state_call", serde_json::json!(["NavnisanApi_resolve", scale_bytes(b"yok-boyle-bir-ad.kurd")]));
+    assert_eq!(answer(&mut socket, 3)["result"], "0x00");
+
+    // A second connection to the same chain shares the sync and answers at once.
+    let mut second = connect(format!("{}/people", engine.base_url()));
+    let asked = Instant::now();
+    rpc(&mut second, 4, "state_call", serde_json::json!(["NavnisanApi_resolve", scale_bytes(b"dks.kurd")]));
+    assert_eq!(answer(&mut second, 4)["result"].as_str().unwrap(), resolved);
+    println!("second connection answered in {:.2}s", asked.elapsed().as_secs_f64());
+
+    // The finalized state is saved for the next start: a save made after the first verified
+    // head, from which a new client resumes.
+    let deadline = Instant::now() + Duration::from_secs(150);
+    for file in ["relay.db", "people.db"] {
+        let path = db_dir.join(file);
+        while std::fs::metadata(&path).and_then(|m| m.modified()).map_or(true, |at| at < synced_at) {
+            assert!(Instant::now() < deadline, "{file} was not saved after the sync");
+            std::thread::sleep(Duration::from_millis(500));
+        }
+        println!("{file}: {} bytes", std::fs::metadata(&path).unwrap().len());
+    }
+
+    let restarted = Instant::now();
+    let warm = start(db_dir);
+    warm.add_chain("relay", &relay, None).unwrap();
+    warm.add_chain("people", &people, Some("relay")).unwrap();
+    let mut socket = connect(format!("{}/people", warm.base_url()));
+    rpc(&mut socket, 5, "state_call", serde_json::json!(["NavnisanApi_resolve", scale_bytes(b"dks.kurd")]));
+    assert_eq!(answer(&mut socket, 5)["result"].as_str().unwrap(), resolved);
+    println!("warm start resolved after {:.1}s", restarted.elapsed().as_secs_f64());
+}
+
+/// Replaces a specification's boot nodes.
+fn with_boot_nodes(spec: &str, boot_nodes: &[&str]) -> String {
+    let mut spec: serde_json::Value = serde_json::from_str(spec).unwrap();
+    spec["bootNodes"] = serde_json::json!(boot_nodes);
+    spec.to_string()
+}
+
+#[test]
+#[ignore = "syncs the live Zagros testnet; needs PEZKUWI_LIGHT_RELAY_SPEC and PEZKUWI_LIGHT_PEOPLE_SPEC"]
+fn syncs_zagros_over_secure_websockets_only() {
+    // The `/wss` boot nodes of 2026-10-31: nginx on 443 in front of each node's WebSocket port.
+    let relay = with_boot_nodes(
+        &std::fs::read_to_string(std::env::var("PEZKUWI_LIGHT_RELAY_SPEC").unwrap()).unwrap(),
+        &[
+            "/dns/zagros-bootnode-0.pezkuwichain.io/tcp/443/wss/p2p/12D3KooWHKMr39ubvsigZXdVJzr7nnMp5YTzMywKuTzPDo3Xf1tZ",
+            "/dns/zagros-bootnode-1.pezkuwichain.io/tcp/443/wss/p2p/12D3KooWH6tzPuoFeyf8n6gNmus9Q3CdEGEVUvbduUnPTqJcLRLC",
+        ],
+    );
+    let people = with_boot_nodes(
+        &std::fs::read_to_string(std::env::var("PEZKUWI_LIGHT_PEOPLE_SPEC").unwrap()).unwrap(),
+        &["/dns/zagros-people-bootnode.pezkuwichain.io/tcp/443/wss/p2p/12D3KooWLnDS5p5bvMzfco2BR4arKRbtpqoZwRvLKgCdzgVpuEQG"],
+    );
+    let started = Instant::now();
+    let engine = start(temporary_dir("wss"));
+    // Peers found through the DHT advertise plain TCP too; none of them may be used.
+    engine.set_secure_only(true);
+    engine.add_chain("relay", &relay, None).unwrap();
+    engine.add_chain("people", &people, Some("relay")).unwrap();
+
+    let mut socket = connect(format!("{}/people", engine.base_url()));
+    rpc(&mut socket, 1, "state_call", serde_json::json!(["NavnisanApi_resolve", scale_bytes(b"dks.kurd")]));
+    let resolved = answer(&mut socket, 1)["result"].as_str().unwrap().to_owned();
+    assert!(
+        resolved.starts_with("0x0195c0de27b9a054a3a68cf2bb26abf99071ad46c2485295bb4120185a811a042f"),
+        "{resolved}"
+    );
+    println!("resolved over wss only after {:.1}s", started.elapsed().as_secs_f64());
+}
+
+/// Measures a start from a saved database in a process of its own, as an app launch is. The first
+/// run with an empty `PEZKUWI_LIGHT_DB_DIR` syncs and waits for a save; later runs resume from it.
+#[test]
+#[ignore = "syncs the live Zagros testnet; needs PEZKUWI_LIGHT_RELAY_SPEC, PEZKUWI_LIGHT_PEOPLE_SPEC and PEZKUWI_LIGHT_DB_DIR"]
+fn resolves_after_a_start_from_the_saved_database() {
+    let relay = std::fs::read_to_string(std::env::var("PEZKUWI_LIGHT_RELAY_SPEC").unwrap()).unwrap();
+    let people = std::fs::read_to_string(std::env::var("PEZKUWI_LIGHT_PEOPLE_SPEC").unwrap()).unwrap();
+    let db_dir = std::path::PathBuf::from(std::env::var("PEZKUWI_LIGHT_DB_DIR").unwrap());
+    let warm = db_dir.join("people.db").exists();
+    let started = Instant::now();
+
+    let engine = start(db_dir.clone());
+    engine.add_chain("relay", &relay, None).unwrap();
+    engine.add_chain("people", &people, Some("relay")).unwrap();
+    let mut socket = connect(format!("{}/people", engine.base_url()));
+    rpc(&mut socket, 1, "state_call", serde_json::json!(["NavnisanApi_resolve", scale_bytes(b"dks.kurd")]));
+    let resolved = answer(&mut socket, 1)["result"].as_str().unwrap().to_owned();
+    assert!(
+        resolved.starts_with("0x0195c0de27b9a054a3a68cf2bb26abf99071ad46c2485295bb4120185a811a042f"),
+        "{resolved}"
+    );
+    println!(
+        "{} start resolved after {:.1}s",
+        if warm { "warm" } else { "cold" },
+        started.elapsed().as_secs_f64()
+    );
+
+    if !warm {
+        let synced_at = std::time::SystemTime::now();
+        let deadline = Instant::now() + Duration::from_secs(150);
+        for file in ["relay.db", "people.db"] {
+            let path = db_dir.join(file);
+            while std::fs::metadata(&path).and_then(|m| m.modified()).map_or(true, |at| at < synced_at) {
+                assert!(Instant::now() < deadline, "{file} was not saved after the sync");
+                std::thread::sleep(Duration::from_millis(500));
+            }
+        }
+    }
+}

bindings/pezkuwi-light/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest />

bindings/pezkuwi-light/src/main/java/io/novafoundation/nova/lightclient/HostResolver.kt

@@ -0,0 +1,13 @@
+package io.novafoundation.nova.lightclient
+
+/**
+ * Resolves the host names of light client peers, so they follow the app's DNS policy.
+ *
+ * Called from native threads, never the main thread. Throw (for example
+ * [java.net.UnknownHostException]) when the name has no address.
+ */
+fun interface HostResolver {
+
+    /** Addresses of [host] as IP literals, IPv4 or IPv6. */
+    fun resolve(host: String): Array<String>
+}

bindings/pezkuwi-light/src/main/java/io/novafoundation/nova/lightclient/PezkuwiLight.kt

@@ -0,0 +1,43 @@
+package io.novafoundation.nova.lightclient
+
+import java.io.File
+
+/**
+ * Embedded PezkuwiChain light client (smoldot fork `pezkuwichain/smoldot`).
+ *
+ * Every answer is verified against finalized block headers, so it does not depend on trusting
+ * an RPC node. The client is reached like any JSON-RPC node, over a WebSocket bound to
+ * 127.0.0.1 whose path carries a random per-process token: `chainUrl(start(dir), key)`.
+ */
+object PezkuwiLight {
+
+    init {
+        System.loadLibrary("pezkuwi_light")
+    }
+
+    /**
+     * Starts the light client once per process and returns its loopback base URL. Later calls
+     * return the same URL. [databaseDir] keeps each chain's finalized state between starts;
+     * [resolver] resolves the host names of peers.
+     */
+    fun start(databaseDir: File, resolver: HostResolver): String = start(databaseDir.absolutePath, resolver)
+
+    /**
+     * Registers [chainSpec] under [key] and starts syncing it. A teyrchain names the [key] its
+     * relay chain was registered under, which must come first.
+     *
+     * @throws IllegalStateException if the client is not started, the key is taken, or smoldot
+     * rejects the specification
+     */
+    external fun addChain(key: String, chainSpec: String, relayChainKey: String?)
+
+    /**
+     * Restricts new peer connections to secure WebSockets (`wss`, normally on port 443), which
+     * look like any HTTPS WebSocket on the wire. Open connections are kept.
+     */
+    external fun setSecureOnly(secureOnly: Boolean)
+
+    fun chainUrl(baseUrl: String, key: String): String = "$baseUrl/$key"
+
+    private external fun start(databaseDir: String, resolver: HostResolver): String
+}

common/src/main/java/io/novafoundation/nova/common/di/CommonApi.kt

@@ -15,6 +15,7 @@ import io.novafoundation.nova.common.data.network.AppLinksProvider
 import io.novafoundation.nova.common.data.network.HttpExceptionHandler
 import io.novafoundation.nova.common.data.network.NetworkApiCreator
 import io.novafoundation.nova.common.data.network.coingecko.CoinGeckoLinkParser
+import io.novafoundation.nova.common.data.network.dns.EncryptedFirstDns
 import io.novafoundation.nova.common.data.network.rpc.SocketSingleRequestExecutor
 import io.novafoundation.nova.common.data.providers.deviceid.DeviceIdProvider
 import io.novafoundation.nova.common.data.repository.AssetsIconModeRepository
@@ -167,6 +168,8 @@ interface CommonApi {
 
     fun provideEncryptedPreferences(): EncryptedPreferences
 
+    fun encryptedFirstDns(): EncryptedFirstDns
+
     fun provideIconGenerator(): IconGenerator
 
     fun provideClipboardManager(): ClipboardManager

runtime/build.gradle

@@ -57,6 +57,7 @@ dependencies {
 
     implementation project(":bindings:metadata_shortener")
     implementation project(":bindings:sr25519-bizinikiwi")
+    implementation project(":bindings:pezkuwi-light")
 
     implementation gsonDep
     implementation substrateSdkDep

runtime/src/main/java/io/novafoundation/nova/runtime/di/ChainRegistryModule.kt

@@ -6,6 +6,7 @@ import dagger.Module
 import dagger.Provides
 import io.novafoundation.nova.common.BuildConfig
 import io.novafoundation.nova.common.data.network.NetworkApiCreator
+import io.novafoundation.nova.common.data.network.dns.EncryptedFirstDns
 import io.novafoundation.nova.common.data.network.rpc.BulkRetriever
 import io.novafoundation.nova.common.data.storage.Preferences
 import io.novafoundation.nova.common.di.scope.ApplicationScope
@@ -25,6 +26,7 @@ import io.novafoundation.nova.runtime.multiNetwork.connection.ConnectionPool
 import io.novafoundation.nova.runtime.multiNetwork.connection.ConnectionSecrets
 import io.novafoundation.nova.runtime.multiNetwork.connection.Web3ApiPool
 import io.novafoundation.nova.runtime.multiNetwork.connection.autobalance.NodeAutobalancer
+import io.novafoundation.nova.runtime.multiNetwork.connection.light.LightClients
 import io.novafoundation.nova.runtime.multiNetwork.connection.autobalance.strategy.NodeSelectionStrategyProvider
 import io.novafoundation.nova.runtime.multiNetwork.connection.node.healthState.NodeHealthStateTesterFactory
 import io.novafoundation.nova.runtime.multiNetwork.runtime.AsyncChainSyncDispatcher
@@ -179,16 +181,25 @@ class ChainRegistryModule {
             .build()
     )
 
+    @Provides
+    @ApplicationScope
+    fun provideLightClients(
+        context: Context,
+        encryptedFirstDns: EncryptedFirstDns,
+    ) = LightClients(context, encryptedFirstDns)
+
     @Provides
     @ApplicationScope
     fun provideChainConnectionFactory(
         socketProvider: Provider<SocketService>,
         externalRequirementsFlow: MutableStateFlow<ChainConnection.ExternalRequirement>,
         nodeAutobalancer: NodeAutobalancer,
+        lightClients: LightClients,
     ) = ChainConnectionFactory(
         externalRequirementsFlow,
         nodeAutobalancer,
         socketProvider,
+        lightClients,
     )
 
     @Provides

runtime/src/main/java/io/novafoundation/nova/runtime/di/RuntimeDependencies.kt

@@ -3,6 +3,7 @@ package io.novafoundation.nova.runtime.di
 import android.content.Context
 import com.google.gson.Gson
 import io.novafoundation.nova.common.data.network.NetworkApiCreator
+import io.novafoundation.nova.common.data.network.dns.EncryptedFirstDns
 import io.novafoundation.nova.common.data.repository.AssetsIconModeRepository
 import io.novafoundation.nova.common.data.storage.Preferences
 import io.novafoundation.nova.common.interfaces.FileProvider
@@ -32,4 +33,6 @@ interface RuntimeDependencies {
     fun chainAssetDao(): ChainAssetDao
 
     fun assetsIconModeService(): AssetsIconModeRepository
+
+    fun encryptedFirstDns(): EncryptedFirstDns
 }

runtime/src/main/java/io/novafoundation/nova/runtime/multiNetwork/connection/ChainConnection.kt

@@ -5,6 +5,8 @@ import io.novafoundation.nova.common.utils.LOG_TAG
 import io.novafoundation.nova.common.utils.share
 import io.novafoundation.nova.runtime.multiNetwork.chain.model.Chain
 import io.novafoundation.nova.runtime.multiNetwork.connection.autobalance.NodeAutobalancer
+import io.novafoundation.nova.runtime.multiNetwork.connection.light.LightClients
+import io.novafoundation.nova.runtime.multiNetwork.connection.light.LightFallbackPolicy
 import io.novasama.substrate_sdk_android.wsrpc.SocketService
 import io.novasama.substrate_sdk_android.wsrpc.interceptor.WebSocketResponseInterceptor
 import io.novasama.substrate_sdk_android.wsrpc.interceptor.WebSocketResponseInterceptor.ResponseDelivery
@@ -14,6 +16,7 @@ import io.novasama.substrate_sdk_android.wsrpc.state.SocketStateMachine.State
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.cancel
+import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.MutableSharedFlow
 import kotlinx.coroutines.flow.MutableStateFlow
@@ -21,6 +24,7 @@ import kotlinx.coroutines.flow.SharingStarted
 import kotlinx.coroutines.flow.distinctUntilChanged
 import kotlinx.coroutines.flow.filter
 import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.flow.flow
 import kotlinx.coroutines.flow.launchIn
 import kotlinx.coroutines.flow.map
 import kotlinx.coroutines.flow.mapNotNull
@@ -28,12 +32,14 @@ import kotlinx.coroutines.flow.merge
 import kotlinx.coroutines.flow.onEach
 import kotlinx.coroutines.flow.shareIn
 import kotlinx.coroutines.flow.stateIn
+import kotlinx.coroutines.flow.transform
 import javax.inject.Provider
 
 class ChainConnectionFactory(
     private val externalRequirementFlow: Flow<ChainConnection.ExternalRequirement>,
     private val nodeAutobalancer: NodeAutobalancer,
     private val socketServiceProvider: Provider<SocketService>,
+    private val lightClients: LightClients,
 ) {
 
     suspend fun create(chain: Chain): ChainConnection {
@@ -41,7 +47,8 @@ class ChainConnectionFactory(
             socketService = socketServiceProvider.get(),
             externalRequirementFlow = externalRequirementFlow,
             nodeAutobalancer = nodeAutobalancer,
-            initialChain = chain
+            initialChain = chain,
+            lightClients = lightClients.takeIf { it.supports(chain.id) },
         )
 
         connection.setup()
@@ -58,6 +65,11 @@ private const val BLUST_RATE_LIMIT_ERROR_CODE = -32097
 
 private const val ON_FINALITY_RATE_LIMIT_ERROR_CODE = -32029
 
+/** How often a connection on the light client checks whether to retry RPC. */
+private const val LIGHT_FALLBACK_TICK_MILLIS = 15_000L
+
+private const val LIGHT_FALLBACK_TAG = "LightFallback"
+
 private val RATE_LIMIT_ERROR_CODES = listOf(
     INFURA_ERROR_CODE,
     ALCHEMY_ERROR_CODE,
@@ -71,6 +83,7 @@ class ChainConnection internal constructor(
     private val externalRequirementFlow: Flow<ExternalRequirement>,
     private val nodeAutobalancer: NodeAutobalancer,
     initialChain: Chain,
+    private val lightClients: LightClients? = null,
 ) : CoroutineScope by CoroutineScope(Dispatchers.Default),
     WebSocketResponseInterceptor {
 
@@ -94,11 +107,14 @@ class ChainConnection internal constructor(
         .distinctUntilChanged()
         .share(SharingStarted.Eagerly)
 
-    val currentUrl = nodeAutobalancer.connectionUrlFlow(
+    private val rpcUrl = nodeAutobalancer.connectionUrlFlow(
         chainId = initialChain.id,
         changeConnectionEventFlow = nodeChangeSignal,
         availableNodesFlow = availableNodes,
-    ).share(SharingStarted.Eagerly)
+    )
+
+    val currentUrl = (lightClients?.let { rpcUrl.withLightFallback(it) } ?: rpcUrl)
+        .share(SharingStarted.Eagerly)
 
     suspend fun setup() {
         socketService.setInterceptor(this)
@@ -138,15 +154,7 @@ class ChainConnection internal constructor(
         socketService.stop()
     }
 
-    private suspend fun actualUrl(): String? {
-        return when (val stateSnapshot = state.first()) {
-            is State.WaitingForReconnect -> stateSnapshot.url
-            is State.Connecting -> stateSnapshot.url
-            is State.Connected -> stateSnapshot.url
-            State.Disconnected -> null
-            is State.Paused -> stateSnapshot.url
-        }
-    }
+    private suspend fun actualUrl(): String? = state.first().urlOrNull()
 
     private fun Flow<State>.nodeChangeEvents(): Flow<Unit> {
         return mapNotNull { stateValue ->
@@ -156,6 +164,86 @@ class ChainConnection internal constructor(
 
     private fun State.needsAutobalance() = this is State.WaitingForReconnect && attempt > 1
 
+    private sealed interface FallbackEvent {
+        class Rpc(val node: NodeWithSaturatedUrl?) : FallbackEvent
+        class Socket(val state: State) : FallbackEvent
+        object Tick : FallbackEvent
+    }
+
+    /**
+     * Moves the connection to the light client once every RPC node has failed in a row, and back
+     * to RPC when a retry connects (see [LightFallbackPolicy]). Events are handled one at a time,
+     * in the order they arrive.
+     */
+    private fun Flow<NodeWithSaturatedUrl?>.withLightFallback(lightClients: LightClients): Flow<NodeWithSaturatedUrl?> {
+        Log.d(LIGHT_FALLBACK_TAG, "${chain.value.name}: light client fallback armed")
+        val policy = LightFallbackPolicy()
+        var latestRpc: NodeWithSaturatedUrl? = null
+        var light: NodeWithSaturatedUrl? = null
+        val ticks = flow {
+            while (true) {
+                delay(LIGHT_FALLBACK_TICK_MILLIS)
+                emit(FallbackEvent.Tick)
+            }
+        }
+        val rpcNodeCount = { chain.value.nodes.nodes.count { it.connectionType == Chain.Node.ConnectionType.WSS } }
+
+        return merge(map(FallbackEvent::Rpc), state.map(FallbackEvent::Socket), ticks).transform { event ->
+            when (event) {
+                is FallbackEvent.Rpc -> {
+                    latestRpc = event.node
+                    if (policy.source == LightFallbackPolicy.Source.RPC) emit(event.node)
+                }
+
+                is FallbackEvent.Socket -> {
+                    val onLight = light != null && event.state.urlOrNull() == light?.saturatedUrl
+                    if (event.state is State.Connected && !onLight) policy.onRpcConnected()
+
+                    if (event.state.needsAutobalance()) {
+                        Log.d(LIGHT_FALLBACK_TAG, "${chain.value.name}: ${event.state} failed, source ${policy.source}, on light $onLight")
+                        if (onLight) {
+                            policy.onLightUnavailable(rpcNodeCount())
+                            emit(latestRpc)
+                        } else if (policy.onRpcFailure(rpcNodeCount(), System.currentTimeMillis())) {
+                            val url = lightClients.url(chain.value.id)
+                            Log.d(LIGHT_FALLBACK_TAG, "${chain.value.name}: light client url $url")
+                            if (url == null) {
+                                policy.onLightUnavailable(rpcNodeCount())
+                            } else {
+                                Log.d(LIGHT_FALLBACK_TAG, "Every RPC node of ${chain.value.name} failed, using the light client")
+                                light = lightClientNode(url).also { emit(it) }
+                            }
+                        }
+                    }
+                }
+
+                FallbackEvent.Tick -> if (policy.onTick(rpcNodeCount(), System.currentTimeMillis())) {
+                    Log.d(LIGHT_FALLBACK_TAG, "${chain.value.name}: retrying RPC")
+                    emit(latestRpc)
+                }
+            }
+        }
+    }
+
+    private fun lightClientNode(url: String) = NodeWithSaturatedUrl(
+        node = Chain.Node(
+            chainId = chain.value.id,
+            unformattedUrl = url,
+            name = "Light client",
+            orderId = Int.MAX_VALUE,
+            isCustom = false,
+        ),
+        saturatedUrl = url,
+    )
+
+    private fun State.urlOrNull(): String? = when (this) {
+        is State.WaitingForReconnect -> url
+        is State.Connecting -> url
+        is State.Connected -> url
+        State.Disconnected -> null
+        is State.Paused -> url
+    }
+
     override fun onRpcResponseReceived(rpcResponse: RpcResponse): ResponseDelivery {
         val error = rpcResponse.error
 

runtime/src/main/java/io/novafoundation/nova/runtime/multiNetwork/connection/light/LightClients.kt

@@ -0,0 +1,76 @@
+package io.novafoundation.nova.runtime.multiNetwork.connection.light
+
+import android.content.Context
+import android.util.Log
+import io.novafoundation.nova.common.utils.LOG_TAG
+import io.novafoundation.nova.lightclient.HostResolver
+import io.novafoundation.nova.lightclient.PezkuwiLight
+import io.novafoundation.nova.runtime.multiNetwork.chain.model.ChainId
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import kotlinx.coroutines.withContext
+import okhttp3.Dns
+import java.io.File
+
+/**
+ * The embedded light client (`bindings/pezkuwi-light`) for the chains it can verify.
+ *
+ * Started on first use, so a wallet whose RPC nodes answer never runs it. Chain specifications
+ * come from the APK (`light-client/` assets, built from pezkuwi-wallet-utils): the genesis state
+ * root, boot nodes and, for a relay chain, a checkpoint. Peer host names resolve through [dns],
+ * the app's DNS-over-HTTPS-first resolver.
+ */
+class LightClients(
+    private val context: Context,
+    private val dns: Dns,
+) {
+
+    private class LightChain(val asset: String, val relay: ChainId?)
+
+    private val chains = mapOf(
+        ZAGROS to LightChain("light-client/zagros.json", relay = null),
+        ZAGROS_PEOPLE to LightChain("light-client/people-zagros.json", relay = ZAGROS),
+    )
+
+    private val mutex = Mutex()
+    private var baseUrl: String? = null
+    private val registered = mutableSetOf<ChainId>()
+
+    fun supports(chainId: ChainId): Boolean = chainId in chains
+
+    /** Loopback JSON-RPC URL of [chainId], or null when the light client cannot serve it. */
+    suspend fun url(chainId: ChainId): String? = mutex.withLock {
+        withContext(Dispatchers.IO) {
+            runCatching {
+                if (!supports(chainId)) return@runCatching null
+                val base = baseUrl ?: PezkuwiLight.start(File(context.filesDir, DATABASE_DIR), resolver()).also { baseUrl = it }
+                register(chainId)
+                PezkuwiLight.chainUrl(base, chainId)
+            }.onFailure {
+                Log.w(LOG_TAG, "Light client unavailable for $chainId", it)
+            }.getOrNull()
+        }
+    }
+
+    private fun register(chainId: ChainId) {
+        if (chainId in registered) return
+        val chain = chains.getValue(chainId)
+        chain.relay?.let(::register)
+
+        val spec = context.assets.open(chain.asset).bufferedReader().use { it.readText() }
+        PezkuwiLight.addChain(chainId, spec, chain.relay)
+        registered += chainId
+    }
+
+    private fun resolver() = HostResolver { host ->
+        dns.lookup(host).mapNotNull { it.hostAddress }.toTypedArray()
+    }
+
+    private companion object {
+        const val ZAGROS: ChainId = "1b0b4727bbb5e44ed587d1056b4ad537ffb330034509a58866a088d77e792cd5"
+        const val ZAGROS_PEOPLE: ChainId = "c72b38f36affaeb2661018b201c2be02e8c09fc699640525d39200a10fd77878"
+
+        const val DATABASE_DIR = "light-client"
+    }
+}

runtime/src/main/java/io/novafoundation/nova/runtime/multiNetwork/connection/light/LightFallbackPolicy.kt

@@ -0,0 +1,69 @@
+package io.novafoundation.nova.runtime.multiNetwork.connection.light
+
+/**
+ * When a chain's connection moves from its RPC nodes to the embedded light client, and back.
+ *
+ * RPC comes first: a light client puts load on the peer-to-peer nodes that RPC does not, and
+ * those nodes have a fixed number of light client slots. Once every RPC node has failed in a row,
+ * the light client takes over. RPC is retried after [initialBackoffMillis], doubling up to
+ * [maxBackoffMillis] while it keeps failing, and takes back the connection once it connects.
+ *
+ * Not thread-safe: one connection feeds it its events in order.
+ */
+class LightFallbackPolicy(
+    private val initialBackoffMillis: Long = 60_000,
+    private val maxBackoffMillis: Long = 15 * 60_000,
+) {
+
+    enum class Source { RPC, LIGHT }
+
+    var source = Source.RPC
+        private set
+
+    private var consecutiveRpcFailures = 0
+    private var backoffMillis = initialBackoffMillis
+    private var rpcRetryAt: Long? = null
+
+    /** An RPC node failed. True when the light client should take over now. */
+    fun onRpcFailure(rpcNodeCount: Int, nowMillis: Long): Boolean {
+        if (source != Source.RPC) return false
+
+        consecutiveRpcFailures++
+        if (consecutiveRpcFailures < rpcNodeCount.coerceAtLeast(1)) return false
+
+        source = Source.LIGHT
+        rpcRetryAt = nowMillis + backoffMillis
+        backoffMillis = (backoffMillis * 2).coerceAtMost(maxBackoffMillis)
+        return true
+    }
+
+    fun onRpcConnected() {
+        source = Source.RPC
+        consecutiveRpcFailures = 0
+        backoffMillis = initialBackoffMillis
+        rpcRetryAt = null
+    }
+
+    /**
+     * True when RPC should be tried again now. One more RPC failure then hands the connection
+     * straight back to the light client, without walking every node again.
+     */
+    fun onTick(rpcNodeCount: Int, nowMillis: Long): Boolean {
+        val retryAt = rpcRetryAt ?: return false
+        if (source != Source.LIGHT || nowMillis < retryAt) return false
+
+        returnToRpc(rpcNodeCount)
+        return true
+    }
+
+    /** The light client could not start or its connection failed: RPC is all there is. */
+    fun onLightUnavailable(rpcNodeCount: Int) {
+        if (source == Source.LIGHT) returnToRpc(rpcNodeCount)
+    }
+
+    private fun returnToRpc(rpcNodeCount: Int) {
+        source = Source.RPC
+        consecutiveRpcFailures = (rpcNodeCount - 1).coerceAtLeast(0)
+        rpcRetryAt = null
+    }
+}

runtime/src/test/java/io/novafoundation/nova/runtime/multiNetwork/connection/light/LightFallbackPolicyTest.kt

@@ -0,0 +1,94 @@
+package io.novafoundation.nova.runtime.multiNetwork.connection.light
+
+import io.novafoundation.nova.runtime.multiNetwork.connection.light.LightFallbackPolicy.Source
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class LightFallbackPolicyTest {
+
+    private val minute = 60_000L
+    private val policy = LightFallbackPolicy(initialBackoffMillis = minute, maxBackoffMillis = 4 * minute)
+
+    @Test
+    fun `light client takes over only after every RPC node failed in a row`() {
+        assertFalse(policy.onRpcFailure(rpcNodeCount = 3, nowMillis = 0))
+        assertFalse(policy.onRpcFailure(rpcNodeCount = 3, nowMillis = 0))
+        assertEquals(Source.RPC, policy.source)
+
+        assertTrue(policy.onRpcFailure(rpcNodeCount = 3, nowMillis = 0))
+        assertEquals(Source.LIGHT, policy.source)
+    }
+
+    @Test
+    fun `a connected RPC node resets the count`() {
+        policy.onRpcFailure(rpcNodeCount = 2, nowMillis = 0)
+        policy.onRpcConnected()
+
+        assertFalse(policy.onRpcFailure(rpcNodeCount = 2, nowMillis = 0))
+        assertTrue(policy.onRpcFailure(rpcNodeCount = 2, nowMillis = 0))
+    }
+
+    @Test
+    fun `a single RPC node hands over on its first failure`() {
+        assertTrue(policy.onRpcFailure(rpcNodeCount = 1, nowMillis = 0))
+    }
+
+    @Test
+    fun `RPC is retried after the backoff and one more failure returns to the light client`() {
+        policy.onRpcFailure(rpcNodeCount = 3, nowMillis = 0)
+        policy.onRpcFailure(rpcNodeCount = 3, nowMillis = 0)
+        policy.onRpcFailure(rpcNodeCount = 3, nowMillis = 0)
+
+        assertFalse(policy.onTick(rpcNodeCount = 3, nowMillis = minute - 1))
+        assertTrue(policy.onTick(rpcNodeCount = 3, nowMillis = minute))
+        assertEquals(Source.RPC, policy.source)
+
+        assertTrue(policy.onRpcFailure(rpcNodeCount = 3, nowMillis = minute))
+        assertEquals(Source.LIGHT, policy.source)
+    }
+
+    @Test
+    fun `the backoff doubles while RPC keeps failing, up to the maximum`() {
+        var now = 0L
+        policy.onRpcFailure(rpcNodeCount = 1, nowMillis = now)
+
+        for (expectedWait in listOf(minute, 2 * minute, 4 * minute, 4 * minute)) {
+            assertFalse(policy.onTick(rpcNodeCount = 1, nowMillis = now + expectedWait - 1))
+            now += expectedWait
+            assertTrue(policy.onTick(rpcNodeCount = 1, nowMillis = now))
+            assertTrue(policy.onRpcFailure(rpcNodeCount = 1, nowMillis = now))
+        }
+    }
+
+    @Test
+    fun `a connected RPC retry resets the backoff`() {
+        policy.onRpcFailure(rpcNodeCount = 1, nowMillis = 0)
+        policy.onTick(rpcNodeCount = 1, nowMillis = minute)
+        policy.onRpcFailure(rpcNodeCount = 1, nowMillis = minute)
+        policy.onTick(rpcNodeCount = 1, nowMillis = 3 * minute)
+        policy.onRpcConnected()
+
+        assertTrue(policy.onRpcFailure(rpcNodeCount = 1, nowMillis = 10 * minute))
+        assertFalse(policy.onTick(rpcNodeCount = 1, nowMillis = 11 * minute - 1))
+        assertTrue(policy.onTick(rpcNodeCount = 1, nowMillis = 11 * minute))
+    }
+
+    @Test
+    fun `an unavailable light client leaves the connection on RPC`() {
+        policy.onRpcFailure(rpcNodeCount = 2, nowMillis = 0)
+        policy.onRpcFailure(rpcNodeCount = 2, nowMillis = 0)
+        policy.onLightUnavailable(rpcNodeCount = 2)
+
+        assertEquals(Source.RPC, policy.source)
+        assertFalse(policy.onTick(rpcNodeCount = 2, nowMillis = 10 * minute))
+    }
+
+    @Test
+    fun `no failure is counted while on the light client`() {
+        policy.onRpcFailure(rpcNodeCount = 1, nowMillis = 0)
+        assertFalse(policy.onRpcFailure(rpcNodeCount = 1, nowMillis = 0))
+        assertEquals(Source.LIGHT, policy.source)
+    }
+}

settings.gradle

@@ -38,6 +38,7 @@ include ':feature-buy-api'
 include ':feature-buy-impl'
 include ':bindings:hydra-dx-math'
 include ':bindings:sr25519-bizinikiwi'
+include ':bindings:pezkuwi-light'
 include ':feature-proxy-impl'
 include ':feature-proxy-api'
 include ':feature-push-notifications'