TrUAPI

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.

The protocol that lets product webviews talk to their Polkadot host.

TrUAPI (Triangle User-Agent Programming Interface) is the API surface that hosts like the Polkadot Desktop Browser expose to the products that run inside them. One Rust crate defines the contract, a code generator produces a typed TypeScript client, and hosts and products implement against the same shared types.

Try it

Browse the published Rust API docs at paritytech.github.io/truapi.

The interactive playground lets you browse every method, edit request payloads, and call or subscribe to them live against a connected host. It also drives an end-to-end Diagnosis that produces a per-host pass/fail report (playground/README.md → Diagnosis). The explorer aggregates those reports into a cross-host Compatibility matrix (explorer/README.md → Host compatibility matrix).

Live: truapi-playground.dot.li (open from inside the Polkadot Desktop Browser)

Usage

@parity/truapi is the low-level generated protocol client. Product apps should normally use a higher-level product SDK, such as paritytech/product-sdk, while SDK and host-integration layers can depend on this package directly.

npm install @parity/truapi

import {
  createClient,
  createMessagePortProvider,
  createTransport,
} from "@parity/truapi";

const transport = createTransport(createMessagePortProvider(port));
const truapi = createClient(transport);

const result = await truapi.accountManagement.accountGet({
  productAccountId: { dotNsIdentifier: "my-product.dot", derivationIndex: { tag: "Left", value: 0 } },
});

See js/packages/truapi/README.md for the full client reference.

Repository layout

rust/crates/
  truapi/                Rust traits, versioned envelopes, and latest payload re-exports
  truapi-codegen/        rustdoc JSON to TypeScript client + Rust dispatcher
  truapi-macros/         #[wire(id = N)] proc-macro
  truapi-platform/       Host syscall traits used by truapi-server (storage, navigation, consent, ...)
  truapi-server/         Host runtime: dispatcher, typed SCALE logic, chain signing, WASM surface
js/packages/
  truapi/                  @parity/truapi TypeScript client
  truapi-host/            @parity/truapi-host: WASM-backed host runtime; entries `.`
                          (shared host types), `/web` (iframe + Web Worker),
                          `/worker-runtime`
ios/truapi-host/           Swift host adapter package over the truapi-server UniFFI core
android/truapi-host/       Kotlin host adapter package over the truapi-server UniFFI core
playground/                Interactive Next.js playground (truapi-playground.dot)
hosts/dotli/               dotli host, vendored as a submodule
hosts/ios/                 polkadot-app-ios-v2, vendored as a submodule (build/test against the core)
hosts/android/             polkadot-app-android-v2, vendored as a submodule (build/test against the core)
docs/                      Design docs, RFCs, feature proposals
scripts/codegen.sh         Regenerate the TS client from the Rust source
scripts/battery.sh         Run the generated battery against both headless CLI host roles

JS Host SDKs

JS hosts integrate the Rust core through @parity/truapi-host, a single package with tree-shakeable subpath entries:

• @parity/truapi-host (the . entry) exposes shared host runtime types and generated callback contracts.
• @parity/truapi-host/web wires the WASM provider into a browser host: the iframe MessageChannel handshake (createIframeHost) plus createWebWorkerProvider.
• @parity/truapi-host/worker-runtime is the Web Worker entrypoint so the WASM core can run off the page main thread.

How it works

1. The protocol is defined as Rust traits in rust/crates/truapi/, with each method tagged #[wire(id = N)] for a stable byte-level dispatch table. Every method's doc comment must carry a ```ts example, which codegen extracts into the playground's EXAMPLE tab; the build fails if any method is missing one.
2. truapi-codegen reads rustdoc JSON for that crate and generates the TypeScript client under git-ignored paths in js/packages/truapi/.
3. Higher-level SDKs wrap the typed client; the transport encodes SCALE frames and ships them over MessagePort (or postMessage in iframe mode) to the host.
4. The host decodes the frame, dispatches to the matching trait method, encodes the response, and ships it back.

Wire ids are append-only: existing ids never change, so deployed products stay compatible across protocol revisions.

Develop

Common tasks are wrapped in the top-level Makefile. Run make help for the full list.

make setup    # submodules + JS dependencies
make build    # Rust workspace + TypeScript client + @parity/truapi-host
make test     # Rust + TypeScript client + @parity/truapi-host tests
make check    # full suite: build, fmt, clippy, test, TS tests, playground build + lint
make wasm     # rebuild truapi-server WASM artifacts under js/packages/truapi-host/dist/wasm/

CI regenerates the shared bindings before building and testing both npm packages, so generated client and host callback changes are checked together.

The native truapi-host utility can run pairing and signing hosts against the real SSO transport for local end-to-end work. Both roles provide a transcript-based terminal UI with commands such as /product and /script; the signing host also provides /pair and a non-interactive exec form for automation. See the truapi-host-cli guide for setup, controls, and examples.

scripts/battery.sh drives that CLI from source over every code-generated example and writes both committed compatibility reports: explorer/diagnosis-reports/signing-host-cli.md from a direct signing-host run, and pairing-host-cli.md from a pairing host that the script pairs with a signing host it starts itself.

scripts/battery.sh                  # both phases
scripts/battery.sh --signing-host   # direct phase only
scripts/battery.sh --pairing-host   # paired phase only

To run the playground locally:

cd playground
yarn dev

Open https://dot.li/localhost:3000 inside the Polkadot Desktop Host. See playground/README.md for deployment.

Regenerate the TypeScript client

When the Rust trait surface changes:

make codegen      # regenerate the TS client and refresh the playground snapshot
make playground   # rebuild the playground against the refreshed snapshot

This repopulates the ignored generated TS under js/packages/truapi/, including the playground metadata. make dev and make e2e-dotli run this generation step unconditionally before starting their local stacks. The full make e2e-dotli diagnosis builds and launches the local truapi-host signing-host CLI to answer dotli's pairing QR and auto-approve remote signing requests. It does not require the external signer-bot service. When HOST_CLI_SIGNER_MNEMONIC is absent, the CLI manages a reusable isolated test identity under .e2e-dotli/. Set E2E_DOTLI_SIGNING_HOST_BASE_PATH to use a different state directory while debugging.

Protocol versions

• v0.1: initial protocol version.
• v0.2: See docs/design/releases/v0.2.md for the rationale behind each change.
• v0.3: current protocol version.

Deploy

Pushes to main build and deploy:

• The playground to truapi-playground.dot via .github/workflows/deploy-playground.yml.
• The Rust API docs to https://paritytech.github.io/truapi via .github/workflows/deploy-docs.yml.

Release

See docs/RELEASE_PROCESS.md for how to ship @parity/truapi, @parity/truapi-host, or both packages to npm.

Contributing

See CONTRIBUTING.md for issue reports, feature proposals, and the RFC process.

License

MIT