You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add the host-contract-and-core-impl design series, the dotli
architecture/rust-core proposals, and the local e2e testing notes. README
and CLAUDE.md describe the full repo layout: the Rust crate set, the host
packages (WASM, Android, iOS), and the codegen/binding workflows.
truapi-host/ TrUAPIHost Swift Package (sources + UniFFI Swift bindings)
28
+
playground/ Next.js interactive playground; deploys to truapi-playground.dot
29
+
hosts/dotli/ dotli submodule
30
+
docs/ design docs, RFCs, feature proposals
31
+
scripts/codegen.sh regenerate the TS client from the Rust crate
20
32
```
21
33
34
+
### Crate + binding invariants
35
+
36
+
-`truapi` is canonical; runtime crates re-export rather than redefine. New
37
+
syscall traits and host-side runtime types live in `truapi-platform` and
38
+
`truapi-server`, not in `truapi`. Any additions to `truapi` itself are limited
39
+
to additive `Display` impls.
40
+
- All types exposed by `truapi-platform` and `truapi-server` come from
41
+
`truapi::versioned::*` and `truapi::v01::*`. The runtime crates re-export
42
+
rather than redefine.
43
+
-`truapi-server` WASM artifacts live under
44
+
`js/packages/truapi-host-wasm/dist/wasm/{web,node}/` and are gitignored.
45
+
Build them locally with `make wasm` (rerun whenever
46
+
`rust/crates/truapi-server/` changes); CI builds the bundle fresh from the
47
+
Rust source on every run.
48
+
- UniFFI bindings under `android/truapi-host/` and `ios/truapi-host/` are generated from the
49
+
`truapi-server` cdylib via `make uniffi`. The generated Swift modulemap may
50
+
need a one-time relocation into `Sources/truapi_serverFFI/include/`, the
51
+
`make uniffi` target prints a reminder.
52
+
22
53
## Code style
23
54
24
55
- Every `pub` Rust item (functions, methods, types, traits, modules, constants) carries a doc comment (`///` or `//!`).
@@ -116,6 +147,87 @@ submodule init + `bun install` and the per-pane `cd` discipline).
116
147
Alternatively, with a deployed Polkadot Desktop Host installed, navigate to
117
148
`https://dot.li/localhost:3000` from within it.
118
149
150
+
#### Local dotli + playground E2E notes
151
+
152
+
Use `make dev DEBUG=1` from the repo root for the local host stack. It prepares
153
+
the ignored WASM/build artifacts, verifies dotli can resolve
154
+
`@parity/truapi-host-wasm`, then starts dotli on `:5173` and the playground on
155
+
`:3000`. Open `http://localhost:5173/localhost:3000`.
156
+
157
+
When automating with Playwright, block service workers for smoke tests unless
158
+
the test is explicitly about SW behavior. Stale host/product bundles can mask
159
+
runtime fixes. Use a fresh cache-busting query string on
160
+
`http://localhost:5173/localhost:3000?...`, collect `pageerror` and
161
+
`console` messages, and fail on unexpected page errors.
162
+
163
+
For interactive SSO checks, prefer a persistent headed Chrome profile and reuse
164
+
the same browser context across checks. SSO pairing needs a real phone QR scan,
165
+
and signing/resource-allocation flows may need web or mobile confirmation; if
166
+
the human or companion app is unavailable, skip those methods and record the
167
+
skip instead of treating it as a protocol failure. Non-interactive checks should
168
+
still verify that the playground renders, the TrUAPI debug panel receives
169
+
host/product events, generated examples can call non-confirmation methods, and
170
+
logout/relogin does not restore a stale session.
171
+
172
+
The dotli Playwright e2e suite under `hosts/dotli/apps/host/tests/e2e/`
173
+
pairs through the signer-bot service. It requires `SIGNER_BOT_SVC_TOKEN`;
174
+
`SIGNER_BOT_BASE_URL` and `SIGNER_BOT_NETWORK` default to dotli CI's
175
+
`https://signing-bot-dev.novasama-tech.org/` and `paseo-next-v2`. Without the
176
+
token, do not treat the full suite as locally runnable. Use
177
+
`E2E_DOTLI_SMOKE=1 make e2e-dotli` for the no-phone QR smoke path.
178
+
179
+
For a fully automated local playground diagnosis run, use:
180
+
181
+
```bash
182
+
SIGNER_BOT_SVC_TOKEN=... \
183
+
make e2e-dotli
184
+
```
185
+
186
+
`make e2e-dotli` starts dotli preview and the playground, signs out any
187
+
restored host session, signs in through signer-bot by extracting the QR payload,
188
+
runs the playground Diagnosis screen, auto-accepts host-side Allow/Sign modals,
189
+
and writes `hosts/dotli/test-results/e2e-dotli/diagnosis-report.md`.
190
+
191
+
Root CI runs the same target when it can read the private dotli submodule. It
192
+
needs `DOTLI_CHECKOUT_TOKEN` for submodule checkout; without that token, the
193
+
job warns and skips dotli e2e rather than failing unrelated PR checks. With
194
+
dotli access but without `SIGNER_BOT_SVC_TOKEN`, CI runs the no-phone smoke
195
+
path only.
196
+
197
+
A useful no-phone smoke assertion is:
198
+
199
+
```bash
200
+
E2E_DOTLI_SMOKE=1 make e2e-dotli
201
+
```
202
+
203
+
For manual debugging of that smoke path:
204
+
205
+
1. Start `make dev DEBUG=1`.
206
+
2. Open `http://localhost:5173/localhost:3000?debug=truapi&cachebust=<ts>` with
207
+
service workers blocked.
208
+
3. Wait for `globalThis.__truapi?.setLogLevel`, call
209
+
`__truapi.setLogLevel("debug")`, and confirm the console logs
210
+
`[truapi worker] logLevel=debug providers=0`.
211
+
4. Click `#auth-button`, wait for `#auth-modal-backdrop.open`, and confirm:
212
+
the modal shows `Login with Polkadot Mobile`, `__truapi.getProviderCount()`
213
+
is greater than zero, worker frame/callback logs appear, and there are no
214
+
page errors.
215
+
216
+
If `make dev` reports `EADDRINUSE` on `:5173` or the playground moves from
217
+
`:3000` to `:3001`, kill stale `preview-server.ts` / `next dev` processes and
218
+
restart the tmux session. Port drift causes false-negative local e2e results.
219
+
220
+
Useful debug signals:
221
+
222
+
```bash
223
+
localStorage.setItem("truapi:logLevel", "debug")
224
+
sessionStorage.setItem("dotli:truapi-debug", "1")
225
+
```
226
+
227
+
Reload after setting them. Watch for `Unknown wire discriminant`, missing
228
+
`@parity/truapi-host-wasm` imports, worker WASM instantiation failures, and
229
+
debug-panel traffic disappearing when the login popup opens.
230
+
119
231
## Deployment
120
232
121
233
Pushes to `main` trigger `.github/workflows/deploy-playground.yml`, which builds `playground/` and publishes the static export to `truapi-playground.dot` via `bulletin-deploy`.
scripts/codegen.sh Regenerate the TS client from the Rust source
66
76
```
67
77
78
+
### Native + JS host SDKs
79
+
80
+
JS hosts integrate the Rust core through [`@parity/truapi-host-wasm`](js/packages/truapi-host-wasm),
81
+
a single package with tree-shakeable subpath entries (the separate
82
+
`@parity/truapi-host`, with no shared core, is for hosts that bring their own runtime):
83
+
84
+
-`@parity/truapi-host-wasm` (the `.` entry) ships the `truapi-server` WASM bundle, the
85
+
`Provider` factories that drive it, the dispatcher adapter, and `createNodeWasmProvider`.
86
+
-`@parity/truapi-host-wasm/web` wires the WASM provider into a browser host: the iframe
87
+
MessageChannel handshake (`createIframeHost`) plus `createWebWorkerProvider`.
88
+
-`@parity/truapi-host-wasm/electron` wraps an Electron `MessagePortMain` as a `Provider`.
89
+
-`@parity/truapi-host-wasm/worker-runtime` is the Web Worker entrypoint so the WASM core can
90
+
run off the page main thread.
91
+
92
+
Native shells sit one level under `android/` and `ios/` and ship as versioned packages from git tags:
93
+
94
+
-[`android/truapi-host/`](android/truapi-host) builds the `io.parity:truapi-host-android` Maven artifact (AAR + POM + sources jar). Distributed via JitPack as `com.github.paritytech.truapi:truapi-host:<tag>`.
95
+
-[`ios/truapi-host/`](ios/truapi-host) is a Swift Package consumed via `.package(url:)` or `.package(path:)`.
96
+
97
+
The nested layout leaves room for additional packages alongside (e.g. `android/widgets/`, `ios/something-else/`) without re-shaping the top-level directories.
98
+
99
+
Both link the `truapi-server` cdylib via UniFFI-generated bindings. The bindings are regenerated from the same Rust source via `make uniffi`.
100
+
68
101
## How it works
69
102
70
103
1. The protocol is defined as Rust traits in [`rust/crates/truapi/`](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.
@@ -80,9 +113,11 @@ Common tasks are wrapped in the top-level `Makefile`. Run `make help` for the fu
0 commit comments