The Triangle Ecosystem

What is the Triangle?

The shared system that lets small web apps run safely inside a Polkadot wallet.

The Triangle is Parity's architecture for products (small web apps / SPAs) that run inside a host (a Polkadot wallet app). It's called a triangle because of three roles that always show up together:

A product is not a normal Web2 website. It never asks the user to "connect wallet" or "log in", and it never opens its own RPC connection to a chain. Instead it talks to the host, and the host does those things on its behalf — with the user's keys and permission. This is the single most important idea in this whole document.

The mental model

Five layers. A request flows down; data flows back up.

flowchart TB
    P["🧩 Product (your SPA)
runs in iframe / webview sandbox"]
    PS["📦 Product SDK
@parity/product-sdk — ergonomic JS toolkit"]
    HA["📡 Host API
SCALE-encoded contract over postMessage"]
    HS["🏛️ Host SDK
host-side core (Rust: UserAgentKit, or JS)"]
    INFRA["⛓️ Chain · 🔑 Identity · ✍️ Signing · 💾 Storage"]
    P --> PS --> HA --> HS --> INFRA
    INFRA -. "results / subscriptions" .-> HS -.-> HA -.-> PS -.-> P
        

The 3 golden rules

If you remember nothing else, remember these.

Sandbox & the bridge

Why products can't just fetch() a node — and what they do instead.

The host loads your product into a sandbox — an iframe on web, or an embedded WebView on mobile/desktop. By default that sandbox has:

• ❌ no direct network access
• ❌ no persistent browser storage
• ❌ no access to keys or the blockchain
• ❌ no way to escape to the top-level page

The only channel out is a binary postMessage bridge speaking the Host API. This is a deliberate security boundary: a malicious or buggy product can't leak the user's IP, exfiltrate keys, or sign something the user didn't approve.

flowchart LR
    subgraph SB["🔒 Sandbox (iframe / webview)"]
      P["🧩 Product
+ Product SDK"]
    end
    subgraph HOST["🏛️ Host application"]
      direction TB
      BR["Host API handler
(host-container)"]
      ACC["🔑 Accounts / signing"]
      CH["⛓️ Chain connection
(smoldot light client)"]
      ST["💾 Scoped storage"]
    end
    P <-->|"SCALE postMessage
(the only way out)"| BR
    BR --> ACC
    BR --> CH
    BR --> ST
    CH --> NET(("Polkadot /
People / Bulletin"))
        

The Host API contract

A versioned, SCALE-encoded message protocol — the "TrUAPI".

The Host API is the wire contract between product and host. It's binary (SCALE-encoded), versioned per-method (v1 codecs), and organised into 10 domains totalling 55 methods in the canonical triangle-js-sdks implementation. The full method reference is below.

How a message flows

Each call has a requestId and a payload. Three communication patterns exist: request/response, subscription, and reverse subscription (host pushes to product). It always starts with a handshake.

sequenceDiagram
    participant P as 🧩 Product
    participant H as 🏛️ Host
    Note over P,H: 1 · Handshake (once)
    P->>H: host_handshake_request (random requestId)
    H-->>P: host_handshake_response
    Note over P,H: 2 · Request / response
    P->>H: {method}_request (requestId, payload)
    H-->>P: {method}_response (same requestId)
    Note over P,H: 3 · Subscription
    P->>H: {method}_start
    H-->>P: {method}_receive ...
    H-->>P: {method}_receive ...
    P->>H: {method}_stop
        

TrUAPI reference — every interface

All 55 methods, by domain. Source of truth: triangle-js-sdks/packages/host-api/src/protocol (v1 codecs).

This is the complete surface a product can ask the host for. You'll mostly use these through the Product SDK, but here's the raw contract. The host_ prefix = host capabilities, remote_ = chain/network-backed, product_ = host-driven callbacks into the product. Patterns:

🏠 Host / General 7

🔐 Permissions 2

💾 Local Storage 3

👤 Account Management & Identity 7

✍️ Signing & Transactions 6

⛓️ Chain Interaction 13

💬 Chat 6

📣 Statement Store 4

🗂️ Preimage 2

💰 Payments (Coinage) 4

Chain access flow

You use a normal PAPI client — it's just wired to the host underneath.

Here's the magic that keeps rule #1 painless: the Product SDK gives you a standard PAPI (polkadot-api) client backed by a custom JsonRpcProvider. That provider doesn't talk to a node — it translates every JSON-RPC chainHead_* call into a Host API method and sends it over the bridge.

sequenceDiagram
    participant App as 🧩 Your code
    participant PAPI as PAPI client
    participant Prov as createPapiProvider()
    participant Host as 🏛️ Host
    participant Chain as ⛓️ Chain
    App->>PAPI: query balance / subscribe to head
    PAPI->>Prov: chainHead_v1_storage(...)
    Prov->>Host: remote_chain_head_storage (over Host API)
    Host->>Chain: light-client / pooled RPC
    Chain-->>Host: storage value
    Host-->>Prov: response
    Prov-->>PAPI: JSON-RPC result
    PAPI-->>App: typed value
        

Chain methods the host exposes include remote_chain_head_storage, remote_chain_head_call, remote_chain_head_follow_subscribe, remote_chain_spec_genesis_hash, and remote_chain_transaction_broadcast. You rarely call these directly — the PAPI provider does it for you.

Signing a transaction

You build the call; the host holds the key and asks the user.

You never hold a private key. To submit a transaction you build the call with PAPI, hand it a signer that delegates to the host, and the host shows the user an approval prompt and returns a signed extrinsic.

sequenceDiagram
    participant App as 🧩 Your code
    participant Signer as Product SDK signer
    participant Host as 🏛️ Host
    participant User as 👤 User
    participant Chain as ⛓️ Chain
    App->>App: build tx with PAPI
    App->>Signer: signSubmitAndWatch(signer)
    Signer->>Host: host_create_transaction (account + payload)
    Host->>User: approve this transaction?
    User-->>Host: ✅ approve
    Host-->>Signer: signed extrinsic
    Signer->>Host: remote_chain_transaction_broadcast
    Host->>Chain: broadcast
    Chain-->>App: in block → finalized
        

The signer needs the ChainSubmit permission, which the SDK requests on connect. Without it the host rejects signing with PermissionDenied.

Product SDK vs. raw Triangle

Two SDK layers, two npm scopes. Here's which to reach for.

This is the part that confuses everyone, so let's be precise. There are two SDK layers, both published to npm, one stacked on the other:

flowchart TB
    A["🟣 @parity/product-sdk-*
chain-client · tx · signer · contracts · bulletin · statement-store"]
    B["🔵 @novasamatech/host-api-wrapper
thin ergonomic wrapper (was @novasamatech/product-sdk)"]
    C["🔵 @novasamatech/host-api
SCALE protocol · provider · transport"]
    D["🏛️ Host (mobile / desktop / web)"]
    A -->|peer dep| B --> C -->|postMessage| D
        

"But some things still need raw Triangle"

True. @parity/product-sdk covers the common cases cleanly, but the moment you need a capability it doesn't wrap yet — a brand-new Host API method, a host extension (window.host.ext.*), or fine-grained protocol control — you drop down to @novasamatech/host-api / host-api-wrapper directly. The @parity/product-sdk-host package centralizes that access so the rest of your code doesn't depend on Novasama packages directly.

Host vs. standalone (dev) mode

The SDK auto-detects whether it's running inside a host:

• Inside a host → real accounts, real signing prompts, host-routed chain. This is production.
• Standalone / dev → connect("dev") gives deterministic Alice/Bob dev accounts for local testing. No host needed.

Package map

What each @parity/product-sdk-* package does.

Your first product

The smallest thing that works.

One call sets up wallet, storage, chain and Bulletin. Notice: no RPC URL, no wallet-connect modal, no key handling.

import { createApp } from '@parity/product-sdk';

const app = await createApp({
  name: 'my-app',
  logLevel: 'info',
});

// 1 · Get the account from the host (no "connect wallet" UI)
const { accounts } = await app.wallet.connect();

// 2 · Scoped storage, no setup
await app.storage.set('key', 'value');

// 3 · Bulletin storage (decentralized) — may be null if disabled
if (app.bulletin) {
  const cid = await app.bulletin.upload('hello world');
}

From here you'd add a typed chain query, or build a transaction and submit it with the host-backed signer (the flow in Signing a transaction). The product-sdk-app-builder skill scaffolds a full project and picks the right packages for you.

The hosts

The apps that embed the host-sdk and run your product. Same Host API, three surfaces.

All hosts share the same host-sdk core (public name UserAgentKit, a cross-platform Rust SDK) and implement the same Host API — so a product that works in one should work in all three.

How the web host (dotli) resolves an app

1. Host reads the .dot subdomain from the URL.
2. smoldot light client resolves the dotNS name on Asset Hub (racing an HTTP gateway for speed).
3. Content is fetched P2P from Bulletin / IPFS, with a gateway fallback.
4. A Service Worker serves the app bundle into a sandboxed iframe.
5. The SPA talks back only through the host-container postMessage bridge.

Not the same thing: the Nova apps

The production polkadot-app-ios-v2 / polkadot-app-android-v2 (Nova) are currently-shipped Polkadot wallets, but they use a different, older architecture — they are not host-sdk / Triangle hosts. Use them as UX references only, not as an architecture template. Building the new Triangle mobile host is exactly why Project Bravo exists.

Example products & tools

Real things to read, run, and copy from.

Glossary

The words people throw around on day one.

All repositories & links

Where the code lives. Some repos are private — that's expected.