TrUAPI

Introduction

TrUAPI is the protocol every Polkadot Product uses to talk to the Host running it. It is the only interface a Product has to the rest of the world. Every chain interaction, storage write, outbound request, signing operation, and Proof of Personhood proof crosses this boundary, and the Host on the other side enforces the sandbox.

In the Polkadot Triangle, three Hosts run Products. TrUAPI is the contract by which a Product talks to whichever Host is loading it. Most Product developers will never call TrUAPI directly. The Product SDK (the @parity/product-sdk family of packages) wraps it in typed methods. The methods you call still go through TrUAPI, and the Host validates and routes everything.

TrUAPI and its packages

TrUAPI is the name of the protocol specification maintained at paritytech/truapi. It ships as two layers of packages: @parity/truapi is the low-level generated protocol client (the wire), and the @parity/product-sdk family is the higher-level SDK most Products use. This reference uses "TrUAPI" for the protocol surface and names the @parity/product-sdk-* package in the Packages table that wraps each group.

This reference documents the protocol surface in three layers:

1. Conceptual model: Why the Host-Product boundary exists, what derived sub-accounts mean, and how the sandbox enforces isolation. See Sandbox and Sub-Accounts.
2. Operational properties: The protocol's versioning model and the packages that implement it. See Versioning and Packages.
3. Method groups: Eleven groups covering the capabilities a Product reaches for. One page per group is linked in The Eleven Method Groups. A few host-lifecycle methods sit outside these groups; see the note below.

Provisional

The complete per-method reference for TrUAPI remains provisional. The method-group pages below cover what each group is for and the conceptual contract; the exhaustive per-method signatures, parameter shapes, and return types will be added as the surface stabilizes.

Two Audiences

TrUAPI has two distinct readerships, and the per-method pages are written to serve both at once:

• Product developers: You build Products that call the TrUAPI surface. You need to know what each method does, what permissions gate it, what it returns, and how the Product SDK wraps it.
• Host developers: You build Hosts that implement the TrUAPI surface. You need to know what each method must guarantee, how to validate the Product's call, and how to enforce the sandbox at every entry point.

A Product developer can usually rely on the Product SDK (the @parity/product-sdk family of packages) and never call TrUAPI directly. A Host developer is reading the same pages to know what the SDK calls underneath, and what their Host has to honor.

The Eleven Method Groups

Group	Covers
TrUAPI Calls	The lifecycle calls Products use to identify themselves and the Host uses to introduce capabilities.
Permissions	Declaring, querying, and gating on Product capabilities.
Local Storage	The KvStore API for per-Product, per-device key-value persistence.
Account Management	Resolving per-Product sub-accounts and reading their state.
Signing	The mediated signing flow for building transactions and dispatching them through the paired App.
Chat	Room and bot registration, typed message publishing, custom message rendering.
Statement Store	Publishing and subscribing to gossip-distributed signed statements on People Chain.
Preimage	Off-chain content addressed by hash for on-chain operations to dereference.
Chain Interaction	Reading chain state and subscribing to changes through the Host.
Payment	Payment-flow primitives (general Balances transfers and the Pocket flow).
Entropy	Deterministic per-Product entropy derived from the user's root key (key-derivation, not randomness).

Methods outside the eleven groups

A small number of host-lifecycle methods in the TrUAPI v0.2 spec are not part of any of the eleven groups above — host_navigate_to, host_push_notification, and host_feature_supported. They are Host-environment hooks rather than Product capabilities, and are documented per-Host rather than in this protocol surface.

Cross-Host conformance is the target, not yet the guarantee

TrUAPI is specified as a single canonical surface, and the intent is that a Product runs unchanged across every Host. Today that holds between Polkadot Web and Polkadot Desktop, which share the TypeScript host-container (SCALE, host_* calls). The mobile Polkadot App — the canonical signer for transactions — currently exposes a hand-written JSON bridge whose method names differ from the spec and, in places, between iOS and Android. Treat "the same surface on every Host" as the conformance goal the spec defines, not a settled property of every shipping Host. See the cross-host conformance tracking in the SDK team's work.

High-Level Diagram

Provisional

The canonical TrUAPI architecture diagram showing the Host, the Product, the SDK layers in between, and the eleven method groups as a single map — is still being finalized. It will be embedded here and referenced from the section overview once confirmed.

Where to Go Next

• Sandbox and Sub-Accounts

  ---

  Why a Product gets a derived sub-account rather than the user's root identity, and why the Host API is the only egress.

  → Reference

• Versioning

  ---

  How TrUAPI versions evolve and what compatibility a Product can rely on across them.

  → Reference

• Packages

  ---

  The package map: which SDK package wraps which TrUAPI method group, and where the boundary between Product code and Host code lives.

  → Reference