PoC: gRPC server standardization by Mirko-von-Leipzig · Pull Request #1742 · 0xMiden/node

Mirko-von-Leipzig · 2026-03-03T13:37:16Z

Proof of concept for gRPC server implementations.

Each gRPC method gets its own trait (generated by build.rs):

trait <Method> {
    type Input;
    type Output;

    fn decode(request: proto::RequestType) -> tonic::Result<Self::Input>;

    fn encode(output: Self::Output) -> tonic::Result<proto::ResponseType>;

    async fn handle(&self, input: Self::Input) -> tonic::Result<Self::Output>;

    // Implementers can override the behaviour e.g. if its just a proxy shim, then we
    // can just do proxy_client.request(request).await
    async fn full(
        &self,
        request: proto::RequestType,
    ) -> tonic::Result<proto::ResponseType> {
        let input = Self::decode(request)?;
        let output = self.handle(input).await?;
        Self::encode(output)
    }
}

The implementation is not fully complete; I don't support the mempool subscription stream here for example. ~~The comments in the build.rs are also outdated and reference an initial implementation I had.~~

Some benefits of doing this, over implementing the tonic generated traits:

We can easily add instrumentation to encode and decode and handle in one location.
This lays the foundation for GrpcDecode and GrpcEncode traits as a follow-on, which I think will let us be more consistent with our errors here.
This will also let us do something like Server::public_facing and Server::internal, which changes how errors are encoded (i.e. hide internal errors for public facing).
Because each method is its own trait, we can implement one method per file.
Standard implementation of each method.

I've implemented the validator api as an example.

Looking for feedback if this is worth pursuing and cleaning up :) (imo yes, but maybe its not worth it).

drahnr · 2026-03-03T15:37:23Z

crates/proto/build.rs

+        return Ok(());
+    }
+
+    let status = Command::new("rustfmt")


we should try to avoid calling external funbi aries, particularly when it's impossible to pass on flags (i.e. which version / edition does it expect?)

I suggest to use something like prettyplease for generated code https://github.com/drahnr/expander/blob/master/src/lib.rs#L239-L246

I used prettyplease originally, and it gave notably worse output - and also worse dx because if you enter the generated file manually and hit save, your ide may autofmt it again.

I figured using rustfmt would be much better? I don't really care what version or edition it uses - its just to make it legible. It is actually possible to pass edition and other flags in; I removed it because I thought it added no value.

It will error if you're using a version that doesn't know about certain idioms, i.e. 2018 will bail on let Some(foo) = bar else {..};

drahnr · 2026-03-03T15:48:34Z

crates/validator/src/server/sign_block.rs

+            ))
+        })?;
+        Ok(signature)
+    }


Minor stylistic proposal: I find it a bit awkward to have many traits, I'd rather have a single, parameterized trait that uses a concrete type as parameter:

impl WireCodec for MySuperDuperInteraction { type Input = ..; type Output = ..; fn decode_input(grpc::input::Type) -> Result<Self::Input> { .. } fn encode_output(Self::Output) -> Result<grpc::output::Type> { .. } } impl GrpcInteraction<MySuperDuperInteraction> for ValidatorServer { async fn handle(&self, input: MySuperDuperInteraction::Input) -> tonic::Result<Self::Output> { .. }

Agree, we can achieve the same separation of concerns with fewer generated types

I'm not quite understanding why you think it will result in less types? You can either use more traits, and slightly less traits and many structs and impls. The trait variant is much less code, and less indirection imo.

But maybe I've missed an approach? @SantiagoPittella I don't quite follow your proc macro suggestion -- on what do you place the proc macro?

@drahnr I actually had your suggestion implemented here, in commit d9fd24.

But I agree simplifying would be great. Create a new thread in one of the files with a sketch of the code you want to generate, and we can hash it out

drahnr · 2026-03-03T15:55:08Z

crates/proto/build.rs

 fn generate_mod_rs(dst_dir: impl AsRef<Path>) -> std::io::Result<()> {
-    let mod_filepath = dst_dir.as_ref().join("mod.rs");
+    // I couldn't find any `codegen::` function for `mod <module>;`, so we generate it manually.
+    let mut modules = Vec::new();


There should be Module::new("we_are_here").get_or_new_module("foo")

SantiagoPittella · 2026-03-03T17:29:54Z

I like how methods can be added and implemented with this approach, but the code generation part is difficult to follow. I have some doubts about maintainability of this, though on the other hand I assume that this is not supposed to be changed frequently. This changes + an extensive explanation of the generation should do the trick IMO.

Cab probably achieve similar results without the codegen part, defining a single trait like GrpcMethod<M> + a proc macro:

  /// Marker trait for gRPC method descriptors.
  trait MethodDescriptor {
      type Request;
      type Response;
  }

  /// The standard decode -> handle -> encode pipeline.
  #[tonic::async_trait]
  trait GrpcMethod<M: MethodDescriptor>: Send + Sync {
      type Input;
      type Output;

      fn decode(request: M::Request) -> tonic::Result<Self::Input>;
      fn encode(output: Self::Output) -> tonic::Result<M::Response>;
      async fn handle(&self, input: Self::Input) -> tonic::Result<Self::Output>;

      async fn execute(&self, request: M::Request) -> tonic::Result<M::Response> {
          let input = Self::decode(request)?;
          let output = self.handle(input).await?;
          Self::encode(output)
      }
  }

Also, I'm not sure how streams will be accommodated into this pipeline.

sergerad · 2026-03-04T01:53:20Z

@Mirko-von-Leipzig I suppose this relates to this issue #1528 (comment)

Have you thought about how it might impact the ConversionError? Should we hold off on the ConversionError conversation while this poc is going on?

Mirko-von-Leipzig · 2026-03-04T06:23:33Z

@sergerad yeah this overlaps -- but I think we can begin working on that in parallel if we want. I've given some more thought to the API I'd like -- but I don't actually know how to achieve it. I'll write that down in the issue.

Mirko-von-Leipzig · 2026-03-04T07:09:23Z

Also, I'm not sure how streams will be accommodated into this pipeline.

We have a couple of options; it's not much more complex than the normal method - we just need to decide what to do with the stream type.

The tonic adds an associated stream type for each streaming method e.g.

trait tonic::BlockProducerApi {
    type MempoolSubscriptionStream: tonic::codegen::tokio_stream::Stream<
         Item = tonic::Result<MempoolEvent>
     > + Send + Sync + 'static;

     async fn mempool_subscription(request: ...) -> tonic::Result<Self::MempoolSubscriptonStream>);
}

Some options:

Hardcode the associated type to Pin<Box<dyn Stream>> and let the method return any stream
Have the method trait also contain an additional associated stream type which gets passed along

drahnr · 2026-03-10T12:17:13Z

I am in favor of splitting the concerns of type mapping to be split from the RPC endpoint, which would allow re-use of the encoding across types. I'd propose two new traits.

This is so boring it's hardly worth typing it out. The question to me is how we want to pass the in

pub trait WireCodecIn {
    type GrpcInput;
    fn decode_input(input: Self::GrpcInput) -> tonic::Result<Self>;
}
pub trait WireCodecOut {
    type GrpcOutput;
    fn encode_output(output: Self) -> tonic::Result<Self::GrpcOutput>;
}

pub trait GrpcInteraction<Input: WireCodecIn, Output: WireCodecOut> {
    async fn handle(&self, input: Input) -> tonic::Result<Output>;

    async fn full(&self, request: <M as WireCodecIn>::GrpcInput) -> tonic::Result<<M as WireCodecOut>::GrpcOutput> {
        let input = <Input as WireCodecIn>::decode_input(request)?;
        let output = self.handle(input).await?;
        <Output as WireCodecOut>::encode_output(output)
    }
}

pub struct RpcEndpointChicken;

impl GrpcInteraction<FetchEggs, SomeOrNone> for RpcEndpointChicken {
    async fn handle(&self, input: Input) -> tonic::Result<Output> {
    ..
    }
}

What I do like about it is the modularity and the potential to opt-in to custom impls of pieces of it.

drahnr · 2026-03-10T13:49:38Z

Re streaming:

I don't have a preference. Being able to inject input streams/mocking should be a concern, but I am not convince the protobuf layer is the right layer of mocking.

Mirko-von-Leipzig · 2026-03-10T13:52:25Z

I am in favor of splitting the concerns of type mapping to be split from the RPC endpoint, which would allow re-use of the encoding across types. I'd propose two new traits.

This is so boring it's hardly worth typing it out. The question to me is how we want to pass the in

pub trait WireCodecIn {
    type GrpcInput;
    fn decode_input(input: Self::GrpcInput) -> tonic::Result<Self>;
}
pub trait WireCodecOut {
    type GrpcOutput;
    fn encode_output(output: Self) -> tonic::Result<Self::GrpcOutput>;
}

pub trait GrpcInteraction<Input: WireCodecIn, Output: WireCodecOut> {
    async fn handle(&self, input: Input) -> tonic::Result<Output>;

    async fn full(&self, request: <M as WireCodecIn>::GrpcInput) -> tonic::Result<<M as WireCodecOut>::GrpcOutput> {
        let input = <Input as WireCodecIn>::decode_input(request)?;
        let output = self.handle(input).await?;
        <Output as WireCodecOut>::encode_output(output)
    }
}

pub struct RpcEndpointChicken;

impl GrpcInteraction<FetchEggs, SomeOrNone> for RpcEndpointChicken {
    async fn handle(&self, input: Input) -> tonic::Result<Output> {
    ..
    }
}

What I do like about it is the modularity and the potential to opt-in to custom impls of pieces of it.

I had pretty much exactly that here, in commit d9fd24.

The intention is to have the codec stuff reuseable, but having tried it out I think having the GrpcInteraction is more harmful than helpful. Given trait GrpcInteraction<T> vs trait T, I much prefer the latter (more traits, less marker structs).

drahnr · 2026-03-10T13:59:17Z

I am a sucker for marker structs, so I'd favor the above, focusing on the pattern across RPC calls, plugging types.
Otherwise I think we should merge this rather sooner than later.

SantiagoPittella · 2026-03-10T18:05:53Z

I am a sucker for marker structs, so I'd favor the above, focusing on the pattern across RPC calls, plugging types.
Otherwise I think we should merge this rather sooner than later.

Agree.

Also, this is a great fit for the GrpcError macro that I introduced some time ago to avoid the manual .map_err(|err| tonic::Status::invalid_argument(...)) calls. This should help reduce impls.

We could do something like:

  trait SignBlock {
      type Input;
      type Output;
      type Error: Into<tonic::Status>; 

      fn decode(request: proto::ProposedBlock) -> Result<Self::Input, Self::Error>;
      fn encode(output: Self::Output) -> tonic::Result<proto::BlockSignature>;
      async fn handle(&self, input: Self::Input) -> Result<Self::Output, Self::Error>;

      async fn full(&self, request: proto::ProposedBlock) -> tonic::Result<proto::BlockSignature> {
          let input = Self::decode(request).map_err(Into::into)?;
          let output = self.handle(input).await.map_err(Into::into)?;
          Self::encode(output)
      }
  }

Mirko-von-Leipzig · 2026-03-11T12:33:13Z

Re: marker structs - I also like them; which is why the first attempt used them. However after toying with it for a while I had some realisations.

imo the strength of marker structs is that you can define one main trait and then get a bunch of stuff for free with the generic markers. So you can define a struct and get the trait impl for free with much less boilerplate. This advantage doesn't really apply here though, because we're code generating it all.

The marker structs have some downsides:

more complex codegen code
more complex trait usage i.e. trait ServiceTrait: MethodA vs trait ServiceTrait: Method<a> where A: ....
you can't override the trait impls because you only have access to the marker
more code in general
you can't document the methods
- we can codegen docs for trait MethodA, but not for Method<A>

As a summary: we use generics + markers to reduce code duplication and boilerplate as a form of codegen. However, we've already got actual codegen to do this.

I was sort of on the fence before, but I'm almost solidly against this now 😅

Regarding the codec stuff.. I think we definitely want a trait GrpcEncode and trait GrpcDecode. But that will be much more work and may take a while so I'd avoid coupling that with the method trait. The encode and decode methods can evolve to simply call the type codecs directly once we have them.

Mirko-von-Leipzig added 14 commits February 27, 2026 12:29

gRPC server traits and codec

aef29db

WIP codegen

ddeb861

Some codegen use

9f4e039

Appears to work

6aa707f

Simplify

8ede1f4

Partial stream success

bc349ae

Compiles

3768fa1

Validator::Status

b6a94f1

Validator::SignBlock

f47f69e

Validator::SubmitProvenTransaction

ae37306

Add unstable feature flag

d9fd247

Simplify API to traits

637b18a

Use new simpler traits

b63c28e

Lints

d9c7df9

Mirko-von-Leipzig requested review from SantiagoPittella, drahnr and sergerad March 3, 2026 13:37

Mirko-von-Leipzig added 2 commits March 3, 2026 15:58

Improve build docs

03d1841

#[allow(clippy::unit_arg)]

7b31bf4

Mirko-von-Leipzig force-pushed the mirko/grpc-servers branch from 179fae4 to 7b31bf4 Compare March 3, 2026 14:13

drahnr reviewed Mar 3, 2026

View reviewed changes

Conversation

Mirko-von-Leipzig commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

drahnr Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Mirko-von-Leipzig Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

drahnr Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

drahnr Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SantiagoPittella Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Mirko-von-Leipzig Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

Mirko-von-Leipzig Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

drahnr Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

SantiagoPittella commented Mar 3, 2026

Uh oh!

sergerad commented Mar 4, 2026

Uh oh!

Mirko-von-Leipzig commented Mar 4, 2026

Uh oh!

Mirko-von-Leipzig commented Mar 4, 2026

Uh oh!

drahnr commented Mar 10, 2026 • edited by Mirko-von-Leipzig Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

drahnr commented Mar 10, 2026

Uh oh!

Mirko-von-Leipzig commented Mar 10, 2026

Uh oh!

drahnr commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

SantiagoPittella commented Mar 10, 2026

Uh oh!

Mirko-von-Leipzig commented Mar 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Mirko-von-Leipzig commented Mar 3, 2026 •

edited

Loading

drahnr Mar 3, 2026 •

edited

Loading

drahnr Mar 3, 2026 •

edited

Loading

drahnr commented Mar 10, 2026 •

edited by Mirko-von-Leipzig

Loading

drahnr commented Mar 10, 2026 •

edited

Loading