This repo is the single source of truth for the TrUAPI protocol. It vendors dotli as a git submodule at hosts/dotli/.
rust/crates/
truapi/ Rust trait + type definitions for protocol versions v0.1 and v0.2
(canonical), plus the runtime hosts implement (default `runtime`
feature); ships as WASM (browser/node); its `platform` module
holds the host syscall traits (storage, navigation, consent, ...),
its `stack` module resolves the Trinity stack the host runs, the
core's only chain configuration, from the descriptor its build
bundles, its `chain` module builds the core's own extrinsics through
`ExtrinsicService` and reads and writes contracts through
`EvmContractCaller` with signer-bound prepared transactions;
on native targets, its `durable` module follows presigned
transactions to a verdict over the core database and builds
deferred ones through their domain's submission policy, and its
`encrypted_storage` module holds the host store encrypted at
rest that keeps NFT receive key secrets; its `nft`
(purse records, item keys, the tracker of what they hold on
Asset Hub, and backup recovery after a reinstall) and `nft_purse`
(the NFT purses RFC over them) modules keep NFT purses in the
same database, transfer items as deferred durable transactions,
and receive cheques over the statement store; recovery reads the
seed's installations through `installation_registry` and scans
keys with the generic `gap_scan`, which coinage can reuse; its `public_profile` domain resolves and caches
profile records, and its `image_loader` reads the images they name
from Bulletin by CID and checks them; its `materials` module keeps
the materials renderer trees name in the same database, read from
Bulletin by its `bulletin_lookup` module, checked against Shaderlab's
material format and the tree limits, built into the shaders apps
compile (GLSL ES, and Metal through naga), and resolved per tree for
the apps to draw
truapi-codegen/ rustdoc JSON → TypeScript client + Rust dispatcher;
also links the truapi crate to emit the core marker
table as TypeScript, which rustdoc JSON does not carry
truapi-macros/ #[wire_trait(id = N)] and #[wire(id = N)] proc-macros;
#[sso_service] for truapi's inter-host SSO protocol
One implementation module per macro; lib.rs holds entry points
truapi-provider/ network provider backends (WebSocket RPC or smoldot light-client);
its `platform` module holds the chain-access traits, and its
`stack` module runs a Trinity stack's chains on the light client
from light specs the host hands over, checked against the descriptor
truapi-verifiable/ ring-VRF operations over `verifiable`; a lazily loaded WASM module in the browser
truapi-host-cli/ CLI pairing/signing hosts; Bun scripts share the container web API gates
trinity-stack/ Trinity stack descriptors (parse, verify, sign, links, reader state, when
a reader refreshes); no I/O, the caller fetches and
answers. `known-stacks.json` lists the known stacks' links; the
crate README says how to add one. `vectors/` is generated by
`tests/vectors.rs`: rerun with TRINITY_STACK_WRITE_VECTORS=1 after a
deliberate change
js/packages/
truapi/ @parity/truapi TS package; generated TS lives under ignored paths
truapi-host/ @parity/truapi-host: WASM-backed host runtime. Subpath entries:
`.` (shared host types), `/markers` (the core's
table of which log markers may leave the device),
`/web` (iframe + Web Worker), `/node` (worker
thread), `/worker-runtime`
(Worker entry), and the test host `/testing`
(createMockHost), `/testing/playwright` (fixture),
`/testing/server` (node server), `/testing/client`
(no-iframe client), `/testing/dev-accounts`,
`/testing/host-page`.
Two WASM bundles (gitignored) under dist/wasm/, built
via `make wasm`: `web/` is the production browser host
and `testing/` adds the `wasm-signing-host` and
`test-host` Cargo features the test host needs
truapi-debugger/ @parity/truapi-debugger (private, never published): the debugger.
Owns all decoding of the wire frames the Rust host tap
(truapi's DebugSink) streams out, and decodes
every frame by default (no denylist, no reveal toggle).
Holds the trace, envelope-decode, and value-decode
engines, the shared view model + renderers, and two
mounts over them: server.ts (standalone WS+HTTP app on
127.0.0.1:9231 that hosts dial into, `npm run serve`;
endpoints /, /op-list, /op, /view, /channels, /stats,
/traces, /frame) and in-app.ts (createInAppDebugger:
same-page host, no server, no dial). @parity/truapi has
no debug seam. Where the app ultimately lives is still
an open decision.
trinity-stack/ @parity/trinity-stack: the trinity-stack crate built to wasm/
by `npm run build:wasm`, plus read/publish; `/reader` keeps
stacks current from a project's build copies, and the
`trinity-stack` CLI writes those copies to `.trinity/`; its
bun tests run the crate's vectors
js/container/ Shared TS lockdown container for native web views and CLI dev; scripts reuse its web API gates
`npm run build` bundles it into ios/truapi-host/Sources/TrUAPIHost/Resources/
It owns the host connection and injects its frame channel as
`window.__HOST_API_TRANSPORT__`; products encode with their own SDK.
`npm run build:test-sdk` bundles the SDK that host test pages load
ios/truapi-provider/ TrUAPIProvider Swift package (chain transport over UniFFI);
second product of the root Package.swift, released on its
own tag (@parity/ios-provider@<v>) via its scripts/
android/truapi-host/ truapi-host-android AAR (bindings + Kotlin shell + per-ABI
cdylib), published to GitHub Packages by release-android;
include `@parity/android-host <version>` in the `release:`
PR title
android/truapi-provider/ truapi-provider-android AAR; bundles the cdylib the same way,
so consumers need no Rust toolchain
ios/truapi-host/ TrUAPIHost Swift package over the truapi UniFFI core;
SPM manifest at the repo root (Package.swift), rebuild via
ios/truapi-host/scripts/rebuild.sh
playground/ Next.js interactive playground; deploys to the truapi-playground dotNS label
hosts/ios/ iOS host app; resolves the core from this tree
hosts/android/ Android host app; resolves the core from this tree
hosts/imports.json source repository and imported revision per host,
read and updated by scripts/refresh-host-import.sh
hosts/dotli/ dotli submodule
stacks/ generated copies, which host builds bundle, of each signed known stack's
link and descriptor; `scripts/update-stacks.sh` writes them from
`rust/crates/trinity-stack/known-stacks.json`
docs/ design docs, RFCs, feature proposals
scripts/codegen.sh regenerate the TS client from the Rust crate
scripts/battery.sh run the generated battery against both headless CLI host roles,
plus the Pocket phase a Worker execution serves
scripts/cli-backends-e2e.ts
run the CLI on both chain backends (rpc, light-client) and
compare what each serves; `make e2e-cli-backends`
scripts/bundle-size.mjs measure the JS/WASM of the asset groups given (raw, gzip, brotli);
.github/actions/bundle-size takes them as `assets`, stores
main's snapshot and comments the comparison on PRs
scripts/refresh-host-import.sh
refresh a vendored host tree from its source repository
scripts/host-papp-fixtures.ts
print host-papp's encoding of the SSO messages the core
pins, from a triangle-js-sdks checkout
scripts/shaderlab-shader-fixtures.ts
print the shaders Shaderlab's compile step writes for the
core's material shader tests, from a shaderlab-spa checkout
scripts/truapi-host-installer.sh
one-liner installer for the prebuilt truapi-host CLI
scripts/build-cli-runner.ts
bundles the CLI runner and development container
scripts/cli-runner-package.test.ts
verifies the installed runner and development container
.github/consumers.json maps each released package to the repos notified by a bump issue
nightly-toolchain the dated nightly for rustfmt, CI clippy and rustdoc JSON; CI, the
scripts and the Makefile all read it
rust-toolchain.toml pins every other cargo command in the repo to stable
.github/registry-drift-exceptions.json
documents intentionally unpublished npm package versions
truapiholds the canonical protocol definitions and, behind its defaultruntimefeature, the host runtime. The protocol half builds without the runtime (--no-default-features), which is what codegen links and reads, so protocol modules never depend on runtime modules. The feature gates only the runtime block inlib.rs. Protocol types, their derives and their methods do not depend on it (UniFFI derives are native-only); what they need lives on the protocol side too. Syscall traits live in theplatformmodule, host-side runtime types in the runtime modules. The whole crate is one UniFFI namespace,truapi, so native bindings use protocol types directly. The published binaries keep theirtruapi_servernames (truapi_server.xcframework,dist/wasm/*/truapi_server*).- Treat concrete modules such as
truapi::v01as implementation details of the canonicaltruapicrate and its version-conversion impls. Everywhere else, import concrete protocol payload and error types fromtruapi::latest. This includes structs reused by host-internal APIs that are not exposed to products; if such a type is missing, re-export it throughtruapi::latestrather than importing a concrete protocol version. Runtime code may usetruapi::versioned::*for wire envelopes, but should unwrap them into latest payloads immediately. - Every runtime implementation of a TrUAPI trait method runs its entire body
inside
version(request).exec(...), provided byruntime/versioning.rs. The closure and internal helpers uselatestrequests, responses, stream items, and domain errors. The outer method returns versioned envelopes; the helper captures the request version and converts every result and subscription interruption, including early returns and?failures. Framework errors retain their variant and data. Normalize existing versioned internal sources immediately. Add missing canonical types totruapi::latest; do not match or constructV1/V2envelopes or convert individual return paths in handler logic. - Inter-host SSO uses
#[sso_service]as described in the macro guide. Keep per-variant pairing, dispatch, and correlation in that macro; do not add manual per-variant catalogs. Requests with a caller shareProductRequest<P>around canonical payloads; handler method names select request variants. Responses shareResponse<P>; handler signatures name their result payload and response variant. Transcript classification belongs in shared reply handling or the handler; request context carries only the call and signing session. - Native bindings expose canonical Rust domain and protocol types directly.
Add feature-gated UniFFI derives to those types and custom conversions for
unsupported leaf values instead of defining parallel
Native*mirrors. Boundary-specific native types are reserved for lifecycle or callback behavior that has no canonical value-type equivalent. truapi-host-cli's crate version tracksjs/packages/truapi/package.json, kept in sync byscripts/sync-release-versions.mjs. Arelease: @parity/truapi <version>therefore also publishes prebuilttruapi-hostbinaries through.github/workflows/release-cli.yml: one archive per target (aarch64-apple-darwin,x86_64-unknown-linux-musl,aarch64-unknown-linux-musl) plus a.sha256. Each archive includes the native binary, self-contained Bun runner and development container. Archives are uploaded to the@parity/truapi@<version>release, followed by thetruapi-host-cli-stablepointer thatscripts/truapi-host-installer.shand the CLI's own updater read, and then thetruapi-host-cli-v<version>tag that workflows pin.github/actions/install-truapi-hostto; that action installs the CLI version of the commit it is checked out at, so the tag installs its own release. Release asset URLs must percent-encode the tag (%40parity%2Ftruapi%40<version>).make cli-dist CLI_TARGET=<triple>reproduces one archive locally, andmake e2e-cli-updateinstalls and self-updates it against a loopback release server.- The browser core does not link
verifiable, whose ring prover compiles in 4.5 MiB of powers of tau.truapi-verifiableholds the four ring-VRF operations truapi uses (member, sign, alias, prove). Native builds link it; the browser core loads it as a separate WASM module,truapi_verifiable.jsandtruapi_verifiable_bg.wasmbeside the core's own files in each bundle (dist/wasm/web/ordist/wasm/testing/), in the background once a pairing session connects or when one of them first runs, throughtruapi/src/runtime/vrf.rs. Its loader names both files as literalnew URL(…, import.meta.url)specifiers, so bundlers such as Vite emit them.make wasmbuilds the module first and compiles its SHA-256 into both cores, which load no other. - The runtime's WASM artifacts live under
js/packages/truapi-host/dist/wasm/web/and are gitignored. Build them locally withmake wasm(rerun wheneverrust/crates/truapi/changes). CI compiles the crate forwasm32-unknown-unknownto guard the wasm bridge and its offline subxt surface, and the@parity/truapi-host (wasm bridge)job builds both bundles and runs the package's bun tests against them withREQUIRE_WASM=1, so a suite needing a bundle fails instead of skipping.release.ymlrebuilds the bundles for a@parity/truapi-hostrelease and publishes them in the package. - The UniFFI bindings and the container bundle are gitignored build outputs.
After changing UniFFI-exposed types or native bindings, run
./ios/truapi-host/scripts/rebuild.shto refresh them locally; when only the bindings changed,make uniffi && ./ios/truapi-host/scripts/sync-bindings.shdoes that part without Xcode. Because nothing is committed, CI regenerates rather than diffs: theios-bindingsjob proves every UniFFI-exposed type still has a binding representation, and thepackagejob inios-app.ymlcompiles the package and its test target against the iOS core the app jobs share, which is what catches a hand-written conformer that missed a new protocol requirement. On the Kotlin side theandroid-bindingsjob compilesTrUAPIHost.ktagainst freshly generated bindings, which catches the same class of drift;make android-checkdoes it locally. The embedding apps are compiled by neither. - Both compile gates are path-filtered from one place. The
changesjob inci.ymlevaluates.github/hosts.jsonwithscripts/ci-gates.pyinto a gate per host and per package (package_swift,package_kotlin,package_provider_kotlin), alongside its ownneeds_changesetandadds_changeset, and each gated job reads the output. Because neither binding set is committed, a package's list has to name every crate its bindings are generated from, since a protocol change leaves noios/orandroid/diff to key on. The iOS and Android apps areios-app.ymlandandroid-app.yml, whichci.ymlcalls on their host's gates;ios-main.ymlruns the iOS suite for a push to main, on path filtersci-gates.py --checkholds to the registry, and the label builds start fromon-label.yml. Every job inci.ymlis aggregated byci-status, which is the check worth requiring: a job skipped by its filter counts as a pass, so a gate cannot stall a PR it does not apply to.Changeset guardreads live PR titles and labels, so re-running failed jobs picks up aci:no-changesetopt-out.Release guardrejects npm version changes with unconsumed changesets on the merge result, including in the merge queue.registry-drift.ymlchecks default-branch manifests against npm daily and maintains one issue; explicit package-version exceptions live in.github/registry-drift-exceptions.json. Rust jobs cache through.github/actions/rust-cache, which saves only on main so every ref restores main's entries; release and publish jobs restore without saving. A composite action that needs a Rust cache calls Swatinem/rust-cache directly with the same main-onlysave-if, because a post step two composites deep loses its inputs and never saves.prune-caches.ymlruns after each CI and iOS app push to main and deletes Rust entries on main that a newer entry of the same key family supersedes, so aCargo.lockor toolchain change does not leave the old set holding cache space until eviction. Seedocs/RELEASE_PROCESS.mdfor label setup and release recovery. Hosts implementHostBridge, whose protocol extension defaults the optional callbacks;TrUAPIHostRuntimeand each product execution retain one. To publish, include@parity/ios-host <version>in therelease:PR title.release-ios.ymlrebuilds and simulator-tests the XCFramework, uploads it, then cuts the plain semver tag<version>whose commit carries the generated sources and a manifest pointing at that asset. That tag is the SwiftPM contract: consumers pinexact("<version>"), and a branch cannot be consumed directly because the generated sources are ignored there. The job clones and compiles the tag before pushing it, then opens a pull request against the release branch that pointsPackage.swiftat the new asset. Dispatchingrelease-iosmanually with a pre-release version cuts a tag for app-side testing of an unmerged change without touching any branch. When the title also names an npm package, the iOS job waits on that publish being confirmed on npm.publish.sh <version>is the manual fallback.Package.swiftreadsTRUAPI_USE_LOCAL_BINARYfrom the environment to build against the rebuilt XCFramework; the tag script refuses a manifest that pins the local binary.
- Treat every remote branch as shared unless told otherwise. Another contributor's commits and a reviewer's inline comments both live on it.
- Do not force push. To pick up work that landed on the base branch, merge it and resolve the conflicts.
- Before pushing to a branch that already exists,
git fetch originand look at the remote tip. A push whose result surprises you is a push that lost something. - If a rewrite is ever approved,
--force-with-leasealone does not protect the branch. It compares against the remote tracking ref, which the fetch above has just updated, so the lease passes for commits you never saw. Pass--force-if-includesas well, which additionally requires those commits to be part of what you are pushing. - Create a backup branch before an intentional rewrite. A rewrite drops review context even when it preserves every commit.
- Leave unrelated local changes alone. Do not stash, reset or check out over work you did not create.
Two ways to lose work that involve no pushing at all:
git checkout -- <path>discards uncommitted changes to that file with no prompt and no reflog entry to recover from.git checkout <ref> -- <path>also stages what it writes, so a latergit checkout -- <path>restores from the index and hands back the version from<ref>rather than the one you expected. Undo it withgit restore --source=HEAD --staged --worktree <path>.
- Say what a thing actually is. No invented shorthands, no jargon where a plain word exists.
- No em dashes in prose. Use a comma or a full stop.
- Plain engineering prose: no ornate phrasing, stock transitions, inflated claims, or private provenance. Say directly what changed, why it matters, and what the reader needs to do.
- Link to the document that owns a procedure instead of copying it.
- Title every pull request as a conventional commit, with
!for a breaking change. Load.claude/skills/semver-pr-title/SKILL.mdbefore opening or retitling one; it defines what breaking means here. CI blocks a title that does not parse, and amajorchangeset whose title lacks!. The nightly announcements read!to list breaking changes first.
- Load
.claude/skills/labels/SKILL.mdbefore labelling a pull request or an issue, and before adding or renaming a label. Pull requests get their size and first status automatically and carry no area; add aci:label only to get the build it runs. Labels are defined in.github/labels.yml, so never create one withgh labelor the web UI.docs/labels.mddescribes the system.
- Follow the Conventions section of
docs/design/host-telemetry.mdfor anything that sends telemetry from a host. Read it before adding an event, a log line or a metric, and before touching a sender. It covers which Sentry product a signal belongs in and how its level decides that, which field a captured event is queried on, why every captured event sets a fingerprint, and what the core's marker table decides. ItsAdding a signalsubsection shows what a host event looks like on each host, how a core log line is registered and raised, and how to check one in Sentry.
- Do not improve adjacent code, comments, or formatting unless asked. Do not refactor what is not broken.
- Match the conventions already in the file, even where you would have chosen differently.
Doc comments on pub items are required, per Code style. This is about the
rest.
- An inline comment is the exception, not the default. It earns its place only where the code cannot be made to speak for itself, and then it is brief and says why, never what.
- Code that is never committed is exempt: a throwaway probe, a scratch script, a mutation run. Anything that lands is read by people.
- Documentation explains contracts and non-obvious invariants, not a history of how the change was developed.
- A doc comment is a one-line
///summary, a blank///line, then a short body that states the contract, units and failure conditions. A summary with no body on a non-trivial item is a smell. - Item-level notes go in
///on the item. Use//only for line-local reasoning, since//does not show in rustdoc or IDE hover. - Do not repeat trait docs on impls.
- Every
pub modhas a//!block with its purpose and entry point. - Put identifiers in backticks and intra-doc links in brackets. Use
Self::for siblings. - A link target that exists only under some cfg is plain code, not a link, so the link does not break in the other configurations.
- After rewrapping doc prose, check line starts.
+,-and1.turn a line into a list item, and[x]:at the start of a paragraph is parsed as a link definition and dropped. - After API, rename or cfg changes, run
RUSTDOCFLAGS="-D warnings" cargo doc --no-depsfor each cfg and feature combination. Check, clippy and tests do not catch broken intra-doc links.
- Write so a reader needs no comment to follow it. No single-character names, no code golf.
- Review what you just wrote and simplify it. Fewer lines is better. If a fix feels hacky, redo it as though you had known at the start what you know now. Skip this for small obvious changes; do not over-engineer.
-
Do not alias primitive types.
type Counter = u64adds another name to remember without preventing a counter from being confused with any otheru64. Use the primitive directly, or a newtype when distinguishing values or enforcing construction rules provides actual type safety. -
Reuse canonical types, constants, and helpers. Do not introduce a second representation or a new dependency just to convert to and from the type the surrounding code already uses.
-
Keep one source of truth. If one field already determines a fact, do not carry a second field describing it and add checks to keep them synchronized. Fix the representation.
-
Add abstractions and derives for concrete needs, not possible future callers. Keep fields private where they protect invariants; do not add accessors that merely expose every implementation detail.
-
Keep dependencies in the workspace and inherit them from member crates.
-
Prefer safe operations.
-
Fix the underlying cause instead of suppressing a diagnostic or adding a fallback that hides an error.
-
Do not derive
Copy,Clone,Debug,PartialEqorEq, and do not require them as bounds, unless something uses them. RemovingCloneis the one change that can compile while changing behaviour:.clone()on a reference clones the reference. Check every.clone()call site first. -
Do not add a synthetic
Defaultto a type with no natural default. Construct the value at the boundary. -
Do not add
#[inline]to private or crate-internal functions. Use it only on small public items that need cross-crate inlining.
- Treat warnings as errors. Fix the cause of a lint and never silence it with
#[allow]or#[expect]. A silencer keeps the defect and makes it look intentional. The one exception is a signature fixed by a third-party trait, such as tungstenite's callback, where the lint cannot be fixed in our code; the allow then sits on that item with a comment naming the trait. - For cast lints, change the source type first, then widen the destination.
Prefer
try_fromoveras. - After a bulk regex edit, reread every signature it touched.
- Use a safe std API when one exists. Unsafe is a last resort.
- Write one unsafe operation per
unsafe {}block, each with its own// SAFETY:comment that states the invariant and why it holds. - Do not mark a function
unsafeif it can check its preconditions itself. - Cargo features are additive. A feature compiled in with no runtime opt-in behaves like the feature off, because Cargo unifies features across the build.
- Build modes that change behaviour or ABI go behind
--cfg(declared with check-cfg), not a cargo feature. - Production builds carry no debug-only behaviour.
Do not use scoped visibility modifiers such as pub(crate), pub(super), or
pub(in ...). Structure module hierarchies properly and expose the intended
interface through focused public re-exports. Per-item modifiers require
remembering the restriction on every type and item; a proper hierarchy
establishes the boundary once. Scoped modifiers also make it easy to work
around a poorly structured module tree instead of fixing it.
Keep implementation modules private. An item can be pub within a private
module without exposing it outside the crate. Re-export the items that belong
to the public interface. Do not make an entire module public to expose one
helper or to make a test compile. Prefer an inherent method when an operation
belongs to an existing type rather than adding another free-standing export.
- A test should encode why the behaviour matters, not just what the code does. Before changing an existing test, work out why it asserts what it asserts.
- A test that cannot fail when the logic changes is not a test. Check that it does.
- Prefer one
assert_eq!over a whole value to several assertions on individual fields. - Put unit tests in a
#[cfg(test)] mod tests;declaration backed by its own file (foo/tests.rs), not inline in the production file. - Test private behaviour from that submodule. A
cfg(test)hook in production code is a last resort; keep it minimal. - Give test fixtures and helpers the narrowest visibility that works.
- In the Android host (
hosts/android), build test doubles withmockkwhere possible, rather than hand-written fakes or Mockito. Instrumentation tests get it throughmockk-android.
Preserve the local style. Do not add semicolons to return, break or
continue where the file omits them, do not add braces to match arms or
if/else written without them, and do not move operators between the end of
one line and the start of the next, except where the repository formatter requires it. Format with make fmt; it uses the pinned nightly and includes the runtime module tree. Keep formatting limited to files you changed.
- Prefer
derive_more::Displayover a handwrittenfmt::Displayimplementation when the formatting is declarative. Use a manual implementation only when deriving cannot express the behavior cleanly.
- Every
pubRust item (functions, methods, types, traits, modules, constants) carries a doc comment (///or//!). Keep it short and focused on intent or invariants, not on what the signature already says. - Do not add code comments or doc comments that narrate migrations, compatibility shims, or historical changes. Comments should describe only the current code.
- Everything else about comments, including when an inline comment earns its place, is under Comments. Shared-branch hygiene, the scope of a change, tests, and editing existing Rust have their own sections above.
- Remove legacy compatibility code by default. Keep or add it only when explicitly requested.
- In Rust format strings, prefer inlined variables:
"log value: {value:?}"over"log value: {:?}", value. - For Rust modules, prefer
foo.rsplus an optionalfoo/directory for child modules. Do not introduce newfoo/mod.rsfiles unless preserving generated output or an existing external convention. - In runtime Rust code, prefer
core::overstd::for types that are available incore(core::pin::Pin,core::task::Poll,core::fmt, and similar). Keepstd::for std-only APIs, tests, and std-only programs such astruapi-codegen. - No
anyin TypeScript types: If a type can't be expressed cleanly, stop and ask the user whether to (a) refactor or import the right type or (b) add a scoped// eslint-disable-next-line @typescript-eslint/no-explicit-anyexception. Never silently leaveany. - Don't introduce typealias chains that just rename a public type from another crate (e.g.
pub type StorageError = crate::v01::HostLocalStorageReadError). Use the canonical name directly. A typealias is only worth its indirection when it captures a real abstraction. - After any code change, update
README.md(and this file if the layout changed) so the top-level docs reflect what the repo actually contains. Stale docs are a regression. When moving or removing docs,rgfor the old path and update or remove stale links in README files, agent notes, skills, comments, and design docs. - In codegen emitters, prefer
indoc::writedoc!/formatdoc!over chains ofwriteln!. A singlewritedoc!with a multi-line raw string keeps the emitted shape visible in source instead of fragmenting it across one-linewriteln!calls. Reservewriteln!for the genuinely-one-line case (a single import, a single statement inside a loop). - In PR descriptions, issue comments, and other artifacts that outlive the conversation: describe the resulting state, not the transition between commits. Avoid "previously X, now Y", "we removed", "the old shim is gone", "this PR replaces", those read as ephemeral history once the PR is squash-merged. Write what the system does after the change, not what each commit changed on the way there. (Commit messages are the place for transition narrative; they survive in
git logeven after the squash.)
- For architecture, event-flow, and debugging explanations, start with a short direct summary of the model before diving into long details. Prefer simple statements like "the host sends a dirty signal; the core re-reads and derives auth state" before listing each hop.
- Use diagrams only when they clarify ownership or message flow. Keep them layered and label what is per-tab, shared, host-owned, and core-owned.
# Check out the dotli submodule
git submodule update --init --recursive
# Build the TypeScript client (triggers tsc via `prepare`)
( cd js/packages/truapi && npm install )
# Install playground dependencies (picks up @parity/truapi via the file: link)
( cd playground && yarn install --frozen-lockfile )When the Rust trait surface changes, rerun:
./scripts/codegen.shThat will repopulate the ignored generated TS under js/packages/truapi/src/generated/,
js/packages/truapi/src/playground/codegen/, and playground/test/generated/examples/.
After regenerating, rebuild the client and refresh the playground's link copy:
( cd js/packages/truapi && npm run build )
( cd playground && rm -rf node_modules/@parity && yarn install )(yarn 1.x copies file: deps at install time, so the playground's node_modules/@parity/truapi is a snapshot.)
rustfmt and rustdoc JSON run on the dated nightly named in nightly-toolchain;
install it once with rustup toolchain install "$(cat nightly-toolchain)" --component rustfmt,clippy.
Move the date in that one file, and in truapi.rustNightly in
hosts/android/gradle.properties, which the Android build checks against it.
cargo build --workspace
make fmt-check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspacecd js/packages/truapi
npm run build
npm test # bun test suite (src/**/*.test.ts)The explorer is a standalone Vite/React site (no host needed). To run it locally, just start its own dev server and open the URL directly in a browser. Do not launch dotli for the explorer.
cd explorer
npx vite --base / --port 5181 # standalone site at http://localhost:5181/
npm run build # static export to dist/Use a port other than 5173 (dotli's conventional port) to avoid stale-tab confusion.
cd playground
yarn dev # Next.js dev server on :3000
yarn build # static export to out/
yarn lintThe fastest way to exercise the playground is truapi-host dev -- yarn dev
from playground/. Open http://localhost:3000 in any existing browser. The
layout's first blocking script loads the CLI bridge and shared container from
http://127.0.0.1:9955/bootstrap.js. Dev keeps the app server's assets and hot
reload and automatically approves confirmations. A source build needs the
container bundle generated by make headless or make cli-runner. On Unix, the
CLI owns the wrapped command's process group and cleans it up with a five-second
SIGTERM grace period.
The playground must otherwise be opened from inside a TrUAPI host. The fastest
local setup is to run dotli's preview server alongside the playground and open
http://localhost:5173/localhost:3000 in any browser. Use the
playground-local-stack
skill to bring both servers up in tmux (it handles the hosts/dotli/
submodule init + bun install and the per-pane cd discipline).
Alternatively, with a deployed Polkadot Desktop Host installed, navigate to
https://dot.li/localhost:3000 from within it.
Use make dev DEBUG=1 from the repo root for the local host stack. It prepares
the ignored WASM/build artifacts, verifies dotli can resolve
@parity/truapi-host, then starts dotli on :5173 and the playground on
:3000. Open http://localhost:5173/localhost:3000.
When automating with Playwright, block service workers for smoke tests unless
the test is explicitly about SW behavior. Stale host/product bundles can mask
runtime fixes. Use a fresh cache-busting query string on
http://localhost:5173/localhost:3000?..., collect pageerror and
console messages, and fail on unexpected page errors.
For interactive SSO checks, prefer a persistent headed Chrome profile and reuse the same browser context across checks. SSO pairing needs a real phone QR scan, and signing/resource-allocation flows may need web or mobile confirmation; if the human or companion app is unavailable, skip those methods and record the skip instead of treating it as a protocol failure. Non-interactive checks should still verify that the playground renders, the TrUAPI debug panel receives host/product events, generated examples can call non-confirmation methods, and logout/relogin does not restore a stale session.
The root make e2e-dotli target builds the local truapi-host binary and
drives the dotli/playground diagnosis through a non-interactive signing-host
CLI process. The CLI answers the QR-derived pairing deeplink, auto-approves
remote requests, stays alive for the SSO session, and is launched again to
verify same-account reconnect after host sign-out. It uses
an explicitly exported HOST_CLI_SIGNER_MNEMONIC when present. Without one,
it auto-manages a reusable isolated identity under .e2e-dotli/. Set
E2E_DOTLI_SIGNING_HOST_BASE_PATH to preserve and reuse signing-host state
while debugging. Use E2E_DOTLI_SMOKE=1 make e2e-dotli for the QR-only smoke
path.
For a fully automated local playground diagnosis run, use:
make e2e-dotlimake e2e-dotli starts dotli preview and the playground, signs out any
restored host session, signs in through the local signing-host CLI by extracting
the QR payload, runs the playground Diagnosis screen, auto-accepts host-side
Allow/Sign modals, and writes
playground/test-results/e2e-dotli/diagnosis-report.md.
Any CI job running the same target needs DOTLI_CHECKOUT_TOKEN for private
submodule checkout; without dotli access it should skip this integration gate
rather than fail unrelated checks.
A useful no-phone smoke assertion is:
E2E_DOTLI_SMOKE=1 make e2e-dotliFor manual debugging of that smoke path:
- Start
make dev DEBUG=1. - Open
http://localhost:5173/localhost:3000?debug=truapi&cachebust=<ts>with service workers blocked. - Wait for
globalThis.__truapi?.setLogLevel, call__truapi.setLogLevel("debug"), and confirm the console logs[truapi worker] logLevel=debug providers=0. - Click
#auth-button, wait for#auth-modal-backdrop.open, and confirm: the modal showsLogin with Polkadot Mobile,__truapi.getProviderCount()is greater than zero, worker frame/callback logs appear, and there are no page errors.
If make dev reports EADDRINUSE on :5173 or the playground moves from
:3000 to :3001, kill stale preview-server.ts / next dev processes and
restart the tmux session. Port drift causes false-negative local e2e results.
Useful debug signals:
__truapi.setLogLevel("debug");
sessionStorage.setItem("dotli:truapi-debug", "1");Reload after setting the debug-panel flag. Watch for unknown wire discriminant pair, missing
@parity/truapi-host imports, worker WASM instantiation failures, and
debug-panel traffic disappearing when the login popup opens.
Pushes to main trigger .github/workflows/deploy-playground.yml, which builds playground/ and publishes the static export via bulletin-deploy. Pass the bare dotNS label truapi-playground, never a suffixed name: dotNS attaches the top-level domain its network declares, so the live name is truapi-playground.paseo on Paseo Next v2. The deploy steps stay in this repo because bulletin-deploy ships its shared reusable workflow from a private repo that this public one cannot call.
Pushes to main also trigger .github/workflows/deploy-docs.yml, which publishes the explorer (at the Pages root), the playground (under /playground/), and the Rust API docs (under /cargo_doc/) to GitHub Pages.