@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, then use resolver.resolveCid(...) or resolver.resolveAndFetch(...) for the actual product load.
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 packages the reviewed Paseo relay and Paseo Asset Hub Smoldot specs from paseo-network/paseo-chain-specs. The default browser runtime-chain helpers apply these specs before falling back to the underlying @useragent-kit/sdk chain specs, so npm consumers can pick up newer checkpoints by updating this package instead of patching host code.

The refresh workflow is intentionally not a runtime network fetch. To update the vendored checkpoint, run:

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

The script fetches from the pinned upstream Paseo chain-spec revision unless PASEO_CHAIN_SPECS_REF is set, then regenerates the TypeScript wrapper used by the browser helper. Scheduled freshness checks pass --latest, which resolves upstream main to a concrete commit SHA before writing the wrapper. Review and commit the JSON plus generated TypeScript diffs before release.

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.