Simplify the TrUAPI spec surface

[filvecchiato]

Problem

Adding a TrUAPI function requires touching three places:

1. rust/crates/truapi/src/api/*.rs — trait method with &self, CallContext, async_trait
2. rust/crates/truapi/src/v01/*.rs — concrete types
3. rust/crates/truapi/src/versioned/*.rs — versioned_type! wrappers

The trait signatures mix protocol information with runtime concerns, and there's no way to tell request-response from subscription by reading the code.

Proposal

Simplify the spec surface to carry only protocol information:

#[wire(request_id = 12)]
fn host_derive_entropy(key: Vec) -> Result<Entropy, DeriveEntropyError>

#[wire(request_id = 120)]
fn remote_preimage_lookup_subscribe(key: PreimageKey) -> Subscription<Option, PreimageLookupError>

• Result<T, E> = request-response
• Subscription<T, E> = subscription (marker type for codegen)
• No &self, CallContext, async_trait, CallError — generated by codegen for the runtime
• Wire IDs stay explicit and manually assigned (stable across renames, required by other implementors)

Auto-generated from the spec

• Runtime boilerplate (&self, CallContext, async_trait, CallError)
• Versioned wrappers (versioned_type! enums)
• TS client (SCALE codecs, Result wrapping, Observable for subscriptions)
• Explorer/playground metadata

Migration

1. Prototype the simplified surface for one group
2. Extend codegen to produce the current /api traits and /versioned wrappers from it
3. Migrate remaining groups
4. Add contributor guide: "How to add a new TrUAPI function"

[filvecchiato]

cc: @TorstenStueber @pgherveou

[pgherveou]

Just skimming through from my phone. Will review property later.

This is not a great idea, you won't be able to be backward compatible if you compute the id from the hash

IDs (currently #[wire(request_id = N)]) are not part of the spec. They are derived deterministically from the fully qualified function name (e.g. signing.create_transaction), ensuring:

This is not really true

Stability: renaming a function intentionally changes its wire ID (it's a breaking change anyway)

[TorstenStueber]

I actually think that using Rust as an instrument to define the functions and types is more convenient than using JSON or YAML. First: it is more readable and compact and, second, type checking ensures that all referenced types are fully defined.

I mean we could do something as simple as:

fn host_derive_entropy(key: Vec<u8>) -> Result<Entropy, DeriveEntropyError>

fn remote_preimage_lookup_subscribe(key: PreimageKey) -> Subscription<Option<PreimageValue>>

So a TrUAPI function of the kind request-response has the form

fn name(arg: Type, ...) -> ReturnType

and a function of kind subscription has the form

fn name(arg: Type, ...) -> Subscription<ReceiveType>

where:

• ReturnType can also be a tuple, but as far as I can tell all request-response function return a single value of type Result<...,...>
• Subscription is a just defined as struct Subscription<T> (PhantomData<T>); and used only as a marker for the codegen that this is function of subscription type

That's all we need and it conveys all the information we need. Additionally we could allow doc comments before every function that adds extra semantic information, docs or examples (the way you already do in rust/crates/truapi/src/api/).

[pgherveou]

Since the end game is to also have a Rust core runtime, I think the extra verbosity is also justified.

the three-layer split (api / v01 / versioned)

You could have them all in one file, but that will quickly become quite messy, as it grows.
However we decide to represent this, we need to define the different versions. Having them defined in Rust directly help us define additional derive attributes, that will help organise the Rust runtime when it's operational.

Manual wire IDs are error-prone. #[wire(request_id = 30)] is hand-assigned and has no relation to the spec

It should though, if the specs don't define the request_id, how would implemntors know which one to use, We could derive it automatically based on order, but we need to support legacy here

I actually think that using Rust as an instrument to define the functions and types is more convenient than using JSON or YAML. First: it is more readable and compact and, second, type checking ensures that all referenced types are fully defined.

I mean we could do something as simple as:

fn host_derive_entropy(key: Vec<u8>) -> Result<Entropy, DeriveEntropyError>

fn remote_preimage_lookup_subscribe(key: PreimageKey) -> Subscription<Option<PreimageValue>>

So a TrUAPI function of the kind request-response has the form

fn name(arg: Type, ...) -> ReturnType

and a function of kind subscription has the form

fn name(arg: Type, ...) -> Subscription<ReceiveType>

where:

• ReturnType can also be a tuple, but as far as I can tell all request-response function return a single value of type Result<...,...>
• Subscription is a just defined as struct Subscription<T> (PhantomData<T>); and used only as a marker for the codegen that this is function of subscription type

That's all we need and it conveys all the information we need. Additionally we could allow doc comments before every function that adds extra semantic information, docs or examples (the way you already do in rust/crates/truapi/src/api/).

If the Rust API is going to become the source of truth for the runtime, I don't see much benefits trying to hide types behind alias, It makes things slightly more verbose to type, but I think the spec verbosity mostly come from Claude generated prose, more so than the code definitions

[filvecchiato]

@pgherveou @TorstenStueber Took into consideration all the comments and updated the body of the issue. LMK what you think, I think now its a fair option to simplify the readability of the repo

[TorstenStueber]

we need to define the different versions

I assume you don't mean TrUAPI versions but the wire format version tags (you agree that they are different?)

I argued that this can be auto-generated but it also surely makes sense to make this explicit.

If the Rust API is going to become the source of truth for the runtime, I don't see much benefits trying to hide types behind alias, It makes things slightly more verbose to type, but I think the spec verbosity mostly come from Claude generated prose, more so than the code definitions

What is "the Rust API"? Do you mean the spec or any generated code?

@pgherveou @TorstenStueber Took into consideration all the comments and updated the body of the issue. LMK what you think, I think now its a fair option to simplify the readability of the repo

@filvecchiato looks good.

[pgherveou]

I assume you don't mean TrUAPI versions but the wire format version tags (you agree that they are different?)

I meant the different versioned struct

What is "the Rust API"? Do you mean the spec or any generated code?

I mean the Rust traits

Do we really think that we need one more level of codegen, for the sake of writing RFC in a slightly simpler format?