Use canonical types over the native FFI by pgherveou · Pull Request #345 · paritytech/truapi

pgherveou · 2026-08-05T14:20:32Z

Note

Follow-up to the discussion in #330 (comment): the native FFI surface uses the canonical protocol types directly. No mirrored copies, no restated declarations to keep in sync.

Summary

truapi and truapi-platform carry a feature-gated uniffi dependency and derive uniffi::Record/uniffi::Enum directly on the types that cross the native FFI: the user-confirmation review tree, navigate decisions, device/remote permissions, push notifications, feature queries, auth state, and the permission admin API. Each type is defined exactly once.
truapi-server enables the uniffi features for non-wasm builds only and re-exports the library crates' scaffolding so library-mode bindgen sees their metadata.
[u8; 32] fields keep their canonical shape: a version-neutral Bytes32 alias plus uniffi::custom_type! passes them as plain bytes (Data in Swift, ByteArray in Kotlin). No newtype, no call-site changes, wire format untouched by construction.
Host-thrown callback errors are thin namespace-local wrappers around the canonical payload enums (uniffi's Kotlin backend requires callback error types to live in the crate declaring the callback interface).
DerivationIndex's variants are renamed Left/Right → Index/Raw. The wire is unchanged (SCALE encodes the Either discriminant by position, confirmed by the golden wire-equality tests), but the generated TypeScript client's discriminant strings change with it — a breaking @parity/truapi API change for web products matching on tag. dotli does not reference the type; the playground and this repo's tests are updated.
Everything else in the generated TypeScript client keeps its exact shape; the wire format is byte-identical throughout.

Bindings and packaging

Bindings span three uniffi namespaces (truapi, truapi_platform, truapi_server). Swift: the generated sources compile together into the TrUAPIHost module, each C FFI namespace is a systemLibrary target, and the xcframework ships all three headers. Kotlin: per-namespace packages with cross-imports. Hosts see the canonical shapes, e.g. UserConfirmationReview.signPayload(SignPayloadReview) and DerivationIndex.index/.raw.

Host integration references

iOS: paritytech/polkadot-app-ios-v2#1323 is the draft integration PR. It builds, passes all 23 focused bridge tests, and launches in an iOS 18.3.1 simulator with the XCFramework published as @parity/ios-host@0.4.0.
Android: pg/truapi-canonical-reviews adapts the Android host to these bindings. Its :bindings:truapi-host module compiles the Rust core from a TrUAPI checkout via truapi.dir. Verified on Linux: :app:assembleVanillaDebug builds and the ConfirmationReviewMappingTest suite passes.

iOS binary release

Package.swift consumes @parity/ios-host@0.4.0 with checksum a3029c071ef37e876ae51e45c177eab09cb976f9dbd729b93a2191d6ca8331be.
useLocalBinary remains false in the committed manifest; local rebuilt XCFrameworks are opt-in for development only.

Verification

cargo build --workspace --all-targets --all-features, cargo +nightly fmt --check, cargo clippy --workspace --all-targets --all-features -- -D warnings, cargo test --workspace --all-features
cargo check --target wasm32-unknown-unknown -p truapi-server (uniffi features stay off for wasm)
make uniffi / make uniffi-kotlin generate cleanly; ./scripts/codegen.sh leaves the committed generated Rust untouched; @parity/truapi passes tsc and all bun tests including golden wire-equality; the Android app builds end to end.

iOS release automation

Release commits may declare @parity/ios-host <version> alongside the npm targets. The trusted post-CI release workflow rebuilds the XCFramework on an arm64 macOS runner, rejects stale generated outputs, and runs the Swift package tests in an iOS simulator before publishing.
The workflow publishes @parity/ios-host@<version> from the pinned release SHA and makes a normal Package.swift follow-up commit only after the asset is live. A compare-before-write guard prevents a delayed run from overwriting a newer manifest.

…eview

…igning

…uapi into feat/signing-host-ring-vrf

Use codec-derived runtime payloads and metadata-aware storage projections so field ordering and variant encoding stay aligned with chain types. Derive SSO message labels once and keep normal transcript events at debug.

Native executors need dispatch futures that can move across Tokio worker threads. Keep concise async signatures while teaching rustdoc codegen to unwrap async-trait futures.

HostDevicePermissionRequest, RemotePermission, HostPushNotificationRequest, and HostFeatureSupportedRequest derive uniffi in truapi and cross the FFI directly; their Native* mirrors and From conversions are deleted, and NativePermissionAuthorizationRequest (which genuinely flattens the RemotePermissionRequest wrapper) now wraps the canonical inner types. AuthState, SessionUiInfo, HostTheme, and the authorization mirrors keep reshaping and stay. Bytes32 moves from the v01 root to the crate root: the [u8; 32] conversion is version-neutral and applies to every protocol version. The Kotlin and Swift host shells and the hosts/android app consume the canonical names from the uniffi.truapi namespace; enum entries are unchanged.

v01::ThemeVariant and truapi_platform::PermissionAuthorizationStatus derive uniffi and cross the FFI directly; the HostTheme and NativePermissionAuthorizationStatus mirrors and their From conversions are deleted, with unchanged enum entries for hosts. The error mirrors (HostStorageError, HostRejection, HostNavigateRejection) stay: uniffi 0.29's Kotlin backend cannot lower cross-namespace types on the callback error path (each package defines its own RustBuffer JNA class, and the generated vtable glue mixes them), so callback error types must live in the crate that declares the callback interface.

…r FFI truapi_platform::AuthState, SessionUiInfo, and PermissionAuthorizationRequest (with the canonical nested RemotePermissionRequest wrapper, matching the review tree's nesting) derive uniffi and cross the FFI directly; their native mirrors and From conversions are deleted. truapi-platform registers its own Bytes32 custom type so SessionUiInfo's 32-byte fields pass as plain bytes. What stays hand-written in native.rs is by design: NativeRuntimeConfig (flat pre-validation config input), NativePairingDeeplinkScheme (native-only), and the error types (uniffi's Kotlin backend cannot lower cross-namespace callback error types).

HostStorageError and HostNavigateRejection carry v01::HostLocalStorageReadError and v01::HostNavigateToError as their single variant payload instead of restating the variants, so the error content is defined once in truapi (which gains Display and uniffi derives on those enums). The wrapper enums stay in truapi-server because uniffi's Kotlin backend requires callback error types to be namespace-local; payload fields cross namespaces fine since they serialize through the shared byte buffer rather than the vtable's RustBuffer lowering.

The variants keep their wire positions (SCALE encodes the Either discriminant by index, confirmed by the golden wire-equality tests), so the protocol is unchanged. The generated TypeScript client's discriminant strings change from "Left"/"Right" to "Index"/"Raw", which is a breaking API change for web products; Swift and Kotlin hosts see .index/.raw. Also drops a stale native/reviews.rs that a merge resurrected without any module reference.

socket-security · 2026-08-06T22:59:04Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	cargo/uniffi@0.29.5 ⏵ 0.32.0

View full report

ERussel

Can you, please:

ios/truapi-host/rebuild.sh
ios/truapi-host/publish.sh 0.4.0
Commit changed Package.swift

pgherveou · 2026-08-07T16:36:52Z

@parity/ios-host@0.4.0 is live with the rebuilt XCFramework:

release: https://github.com/paritytech/truapi/releases/tag/%40parity%2Fios-host%400.4.0
checksum: a3029c071ef37e876ae51e45c177eab09cb976f9dbd729b93a2191d6ca8331be
manifest/release-workflow note: e0c92d15

The uploaded asset was downloaded independently and its checksum matches Package.swift.

ERussel

Thank you!

Brings the branch up to `aa878d1f`, so the PR is mergeable again. One conflict, in `host_core.rs`, between two additions to the same region: this branch's native-only `impl SigningHostRuntime` carrying the renewal entry points, and `ConnectionAdapters` from the Chat integration (#326). Both are kept; neither references the other. The rest of main merged cleanly, including the FFI type rename (#345), Extrinsic V5 signing (#333), and RFC-0026 chain discovery (#354, #358). Verified on the merge result: `cargo +nightly fmt --check`, `clippy --workspace --all-targets --all-features -D warnings`, 683 workspace tests, and `cargo check --target wasm32-unknown-unknown -p truapi-server`.

pgherveou and others added 30 commits July 17, 2026 19:07

feat(core): implement ring-vrf signing

ddf0786

Merge branch 'main' into feat/signing-host-ring-vrf

d59fdb1

Merge branch 'main' into feat/signing-host-ring-vrf

5911457

update

01513f9

analyse and fix diff with ~/github/polkadot-app-android-v2/

bc2a5fe

fixup

1aed8f4

fixes

5489b13

fix(core): align host compatibility

132f667

Merge main into feat/signing-host-ring-vrf

7c96e27

ci: refresh generated fixture and licenses

5dd8ef1

fix(sso-responder): bound the replay-dedup set to cap memory

6868f0b

chore(codegen): refresh stale host-callbacks golden

f7999e3

fix(signing-host): name the beneficiary product in the allocation review

eaaa22b

chore(codegen): refresh host-callbacks golden for ResourceAllocationR…

d8168ad

…eview

fix(signing-host): use a dedicated review for statement-store proof s…

0bed52d

…igning

Clippy / fmt

16009a1

Merge branch 'feat/signing-host-ring-vrf' of github.com:paritytech/tr…

a4e8e40

…uapi into feat/signing-host-ring-vrf

fix(server): align runtime SCALE codecs

103431c

Use codec-derived runtime payloads and metadata-aware storage projections so field ordering and variant encoding stay aligned with chain types. Derive SSO message labels once and keep normal transcript events at debug.

update

0e7e96e

refactor(api): adopt Send async traits

fa9f1fb

Native executors need dispatch futures that can move across Tokio worker threads. Keep concise async signatures while teaching rustdoc codegen to unwrap async-trait futures.

feat(ios): integrate the shared Rust runtime core

bd69991

fix(playground): run account proof diagnosis

8aebcf3

feat(ios): dispatch native frames across Tokio workers

2da2e8b

refactor(native): share the Tokio bridge runtime

f29b3c2

refactor(native): clarify shared executor naming

f57a7da

make host callbacks async

aa65521

merge conflict

86e0bc7

fix conflicts

b11449d

Merge branch 'main' into rus-ios-integration

3b56a85

make callbacks interface type instead of scale encoded

3e43747

pgherveou changed the title ~~Experimental: derive uniffi on the canonical review types~~ Experimental: canonical types over the native FFI Aug 6, 2026

pgherveou added 3 commits August 6, 2026 07:02

pgherveou changed the title ~~Experimental: canonical types over the native FFI~~ Use canonical types over the native FFI Aug 6, 2026

pgherveou marked this pull request as ready for review August 6, 2026 09:40

pgherveou requested a review from a team August 6, 2026 09:40

pgherveou and others added 4 commits August 6, 2026 09:50

fix

441aa4d

chore(codegen): refresh host callbacks golden

4a85ac2

fix(bindings): upgrade UniFFI to 0.32

8680e64

pgherveou and others added 3 commits August 7, 2026 06:19

fix(codegen): update derivation index examples

efc274f

docs(bindings): explain native error wrappers

cb9a268

revert: do not vendor Android host app

b2987a6

ERussel approved these changes Aug 7, 2026

View reviewed changes

Comment thread hosts/android Outdated

ERussel reviewed Aug 7, 2026

View reviewed changes

build(ios): publish host XCFramework 0.4.0

e0c92d1

ERussel approved these changes Aug 7, 2026

View reviewed changes

pgherveou enabled auto-merge August 7, 2026 16:38

ci(ios): publish host binaries from releases

2ae681d

valentinfernandez1 approved these changes Aug 7, 2026

View reviewed changes

pgherveou added this pull request to the merge queue Aug 7, 2026

Merged via the queue into main with commit 2e236de Aug 7, 2026
14 checks passed

pgherveou deleted the pg/uniffi-remote-review-types branch August 7, 2026 17:25

replghost mentioned this pull request Aug 7, 2026

feat: land RFC-0024 ring VRF key management #360

Open

Navigation Menu

Uh oh!

Use canonical types over the native FFI - #345

Use canonical types over the native FFI#345
pgherveou merged 65 commits into
mainfrom
pg/uniffi-remote-review-types

pgherveou commented Aug 5, 2026 •

edited

Loading

Uh oh!

socket-security Bot commented Aug 6, 2026 •

edited

Loading

Uh oh!

Uh oh!

ERussel left a comment

Uh oh!

pgherveou commented Aug 7, 2026

Uh oh!

ERussel left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

pgherveou commented Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Bindings and packaging

Host integration references

iOS binary release

Verification

iOS release automation

Uh oh!

socket-security Bot commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

ERussel left a comment

Choose a reason for hiding this comment

Uh oh!

pgherveou commented Aug 7, 2026

Uh oh!

ERussel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

pgherveou commented Aug 5, 2026 •

edited

Loading

socket-security Bot commented Aug 6, 2026 •

edited

Loading