@useragent-kit/smoldot

Optional browser helper package for @useragent-kit/sdk.

Use it when your web host wants the supported Smoldot lifecycle without copying the example wiring:

• owns the approved JS smoldot dependency
• vendors the reviewed Paseo relay and Asset Hub Smoldot chain specs used by the browser helpers
• prefers a shared runtime frame when available
• falls back to a local runtime-chain service in the current page
• exports createBrowserSmoldotRuntimeChainService() for hosts that still need the raw SmoldotRuntimeChainService while keeping the packaged dependency and browser policy in one place
• exports reusable browser-host persistence helpers that originally lived in examples/pwa, including:
  • BrowserProductAssetCache for IndexedDB-backed asset caching
  • PreloadedChainDbStore for saving browser chain DB snapshots, with databaseContent restore enabled by default for verified warm restart
  • createDotnsChainQueryReadinessTracker for DOTNS resolver warm paths that race waitUntilReady() with chain_getFinalizedHead and reuse the warmed finalized-head state across repeated resolves
  • createBrowserChainPersistenceLifecycle() for periodic persistence and flush-on-ready/pagehide flows, including awaited relay and parachain finalized DB snapshots when the host runtime supports them
  • primeHostedProductArchive() plus hosted-route builders for archive-backed ProductView priming
  • vendoredSmoldotChainSpecs() / withVendoredSmoldotChainSpecs() for hosts that want to inspect or explicitly apply the packaged chain-spec fallback

Use @useragent-kit/sdk directly when you need full control over runtime ownership and lifecycle.

Reusable browser host helpers

import {
  BrowserProductAssetCache,
  PreloadedChainDbStore,
  createBrowserChainPersistenceLifecycle,
  createSmoldotDotnsResolver,
  primeHostedProductArchive,
  createBrowserSmoldotRuntimeChainService,
} from "@useragent-kit/smoldot";
import { createChainBootstrapSdk, createDotnsSdk, createHostSdk } from "@useragent-kit/sdk";

const hostSdk = await createHostSdk();
const dotnsSdk = await createDotnsSdk();
const assetCache = await BrowserProductAssetCache.open();
const chainStore = await PreloadedChainDbStore.load();
const bootstrapSdk = await createChainBootstrapSdk({ chainStore });

const chainService = createBrowserSmoldotRuntimeChainService({
  sdk: bootstrapSdk,
  chainNames: ["PaseoAssetHub"],
});

const persistence = createBrowserChainPersistenceLifecycle({
  chainService,
  chainStore,
  chainNames: ["PaseoAssetHub"],
});

const cachedAssets = await assetCache.load("dotns:browse.dot");

if (cachedAssets != null) {
  await primeHostedProductArchive({
    productId: "browse.dot",
    assets: cachedAssets,
    sdk: hostSdk,
    routePrefix: "/__product__",
  });
}

await persistence.persistNow();

const resolver = createSmoldotDotnsResolver({
  sdk: dotnsSdk,
  chainService,
  chainName: "PaseoAssetHub",
});
resolver.prewarm();

These helpers intentionally stay below shell/router policy. They are suitable for hosts that want the same cache/persistence building blocks as examples/pwa without inheriting that example's UI or routing model.

Recommended DOTNS integration

For browser hosts that resolve .dot products through Smoldot:

1. Create one ChainBootstrapSdk with a PreloadedChainDbStore.
2. Create one SmoldotRuntimeChainService for the chains the host supports, usually at least PaseoAssetHub for DOTNS.
3. Create one SmoldotDotnsResolver for that service and keep it for the host runtime lifetime.
4. Call resolver.prewarm() as soon as the host knows it might need DOTNS. For user-controlled updates, call resolver.resolveAppRelease(...), compare its CID and display metadata with host-owned installation state, then call resolver.fetchCid(...) only after approval. Use resolver.resolveAndFetch(...) only when no approval boundary is required.
5. Keep createBrowserChainPersistenceLifecycle(...) running for the same chain names so Smoldot can save relay and parachain finalized DB snapshots in the background.

Do not create a fresh resolver for every product load. The resolver owns a DotnsChainQueryReadinessTracker, which caches the first finalized head, coalesces concurrent readiness requests, and avoids repeating the full connect -> waitUntilReady -> state_call sequence on every DOTNS lookup.

Vendored chain specs

@useragent-kit/smoldot currently embeds transitional copies of the Paseo specifications from the immutable truapi-provider network catalog. Browser and native UAK therefore consume the same relay identity, bootnodes, checkpoint, and parachain topology while callers migrate to the provider package.

The refresh command reproduces those copies and the generated TypeScript wrapper from the pinned provider revision:

pnpm --filter @useragent-kit/smoldot update:chain-specs

Set TRUAPI_PROVIDER_REF only when advancing the reviewed provider pin. Chain specification changes land in truapi-provider first; downstream scheduled checks reject drift rather than generating an independent checkpoint.

Why databaseContent restore is enabled by default

PreloadedChainDbStore always accepts and flushes Smoldot finalized DB snapshots. By default, PreloadedChainDbStore.load() restores those snapshots on the Smoldot databaseContent bootstrap path so top-level overwrite and restart paths can reuse verified state saved by the local Smoldot runtime. Hosts that need to compare against chain-spec-only startup can set restoreDatabaseContent: false.

The default is therefore:

• start from persisted finalized DB snapshots when available
• fall back to the shipped chain spec and its verified light-sync state when no persisted DB exists
• keep background persistence enabled so relay and parachain state stay warm for future overwrites

The DOTNS readiness fast path does not fetch trust anchors from a public RPC. chain_getFinalizedHead is sent through the same Smoldot-backed RuntimeChainService; it is used only to decide when the local light client can answer queries. The DOTNS state_call still goes through Smoldot.

Android and iOS

This package is the browser Smoldot integration package. The current Android and iOS host SDKs use the native host-mobile / host-chain product-resolution path, not this browser PreloadedChainDbStore or the JS Smoldot databaseContent restore hook.

No Android or iOS API update is required for this browser change. If native hosts later expose an equivalent persisted Smoldot DB restore path, they should follow the same policy: save verified finalized state in the background, restore that verified state by default when it improves restart performance, and allow hosts to disable restored DB content when comparing against chain-spec-only startup.