@polkadot-apps/host

Host container detection and storage access for Polkadot Desktop and Mobile environments.

Install

pnpm add @polkadot-apps/host
# or
npm install @polkadot-apps/host
Copy

Peer Dependencies

@novasamatech/product-sdk is an optional peer dependency. When available, it is used as the primary container detection mechanism. The package works without it by falling back to manual environment checks.

pnpm add @novasamatech/product-sdk
Copy

Quick Start

import { isInsideContainer, getHostLocalStorage, getHostProvider } from "@polkadot-apps/host";

if (await isInsideContainer()) {
  const storage = await getHostLocalStorage();
  await storage?.writeString("last-visit", new Date().toISOString());
}

// Get a host-routed chain provider (returns null outside a container)
const provider = await getHostProvider("0xabc...", wsProvider) ?? wsProvider;
Copy

Container Detection

isInsideContainer determines whether the current page is running inside the Polkadot Desktop or Mobile shell.

import { isInsideContainer } from "@polkadot-apps/host";

const hosted = await isInsideContainer();
// true when running inside Polkadot Desktop/Mobile, false otherwise
Copy

Detection Signals

The function checks the following signals, in order:

1. product-sdk sandboxProvider -- If @novasamatech/product-sdk is installed, its sandbox provider is used as the authoritative check.
2. __HOST_WEBVIEW_MARK__ -- A global flag injected by the mobile WebView shell.
3. __HOST_API_PORT__ -- A global variable set by the desktop host process.
4. iframe detection -- Checks whether the page is embedded in an iframe, which may indicate a container context.

The function returns true as soon as any signal matches.

Host localStorage

When running inside a container, getHostLocalStorage returns a HostLocalStorage object that bridges to the host application's persistent storage. Outside a container it returns null.

import { getHostLocalStorage } from "@polkadot-apps/host";

const storage = await getHostLocalStorage();

if (storage) {
  // String values
  await storage.writeString("theme", "dark");
  const theme = await storage.readString("theme"); // "dark"

  // Structured data (serialized as JSON)
  await storage.writeJSON("preferences", { locale: "en", currency: "DOT" });
  const prefs = await storage.readJSON("preferences");

  // Clear all host storage
  await storage.clear();
} else {
  // Not inside a container -- fall back to window.localStorage
}
Copy

Host Provider

When running inside a Polkadot container, getHostProvider wraps chain connections through the host's shared connection pool, enabling efficient routing and resource sharing.

import { getHostProvider } from "@polkadot-apps/host";
import { getWsProvider } from "polkadot-api/ws-provider/web";

const ws = getWsProvider("wss://rpc.example.com");
const provider = await getHostProvider("0xabc...", ws);

if (provider) {
  // Inside container — connections route through the host
  const client = createClient(provider);
} else {
  // Outside container — use WebSocket directly
  const client = createClient(ws);
}
Copy

Statement Store

When running inside a container, getStatementStore returns a statement store client that communicates through the host's native binary protocol — bypassing JSON-RPC entirely.

import { getStatementStore } from "@polkadot-apps/host";

const store = await getStatementStore();

if (store) {
  // Inside container — subscribe, createProof, submit go through host API
  store.subscribe(topics, (statements) => { /* ... */ });
} else {
  // Outside container — fall back to direct WebSocket
}
Copy

This is used internally by @polkadot-apps/statement-store for its host-first transport strategy.

Chain Config

Shared bulletin chain endpoint configuration, used by both @polkadot-apps/chain-client and @polkadot-apps/statement-store:

import { BULLETIN_RPCS, DEFAULT_BULLETIN_ENDPOINT } from "@polkadot-apps/host";

// BULLETIN_RPCS.paseo → ["wss://paseo-bulletin-rpc.polkadot.io"]
// DEFAULT_BULLETIN_ENDPOINT → "wss://paseo-bulletin-rpc.polkadot.io"
Copy

API

Types

interface HostLocalStorage {
  /** Read a string value by key. */
  readString(key: string): Promise<string | null>;

  /** Write a string value. */
  writeString(key: string, value: string): Promise<void>;

  /** Read and deserialize a JSON value. */
  readJSON<T = unknown>(key: string): Promise<T | null>;

  /** Serialize and write a JSON value. */
  writeJSON<T = unknown>(key: string, value: T): Promise<void>;

  /** Clear all stored values. */
  clear(): Promise<void>;
}
Copy

License

Apache-2.0