Skip to content

feat(grpc): add gRPC server with Starknet API parity#408

Merged
kariy merged 24 commits intomainfrom
feat/grpc
Feb 5, 2026
Merged

feat(grpc): add gRPC server with Starknet API parity#408
kariy merged 24 commits intomainfrom
feat/grpc

Conversation

@kariy
Copy link
Member

@kariy kariy commented Jan 30, 2026

Add gRPC server alongside JSON-RPC for high-performance RPC access. Exposes Starknet read, write, and trace APIs via gRPC with reflection support. Enable with --grpc flag.

🤖 Generated with Claude Code

kariy and others added 8 commits January 30, 2026 18:27
Add gRPC server implementation for high-performance RPC access:

- Extend proto definitions with Write and Trace services
- Add type conversion modules for proto/internal types
- Implement StarknetApiProvider trait for handler abstraction
- Add gRPC server infrastructure with reflection support
- Integrate gRPC server into katana-node
- Add CLI options for gRPC configuration (--grpc, --grpc.port, etc.)
- Support gRPC configuration in config files

The gRPC server exposes the same Starknet APIs as JSON-RPC:
- Starknet (read): 24 methods
- StarknetWrite: 3 methods (add transactions)
- StarknetTrace: 3 methods (trace/simulate)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Replace standalone conversion functions with idiomatic Rust From and
TryFrom trait implementations for proto type conversions:

- Add From<Felt> for ProtoFelt and TryFrom<&ProtoFelt> for Felt
- Add From implementations for block, transaction, receipt, state, and
  trace response types
- Update handlers to use .into() and Felt::try_from() instead of
  explicit conversion functions
- Keep FeltVecExt and ProtoFeltVecExt traits for slice conversions
- Clean up unused imports

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Move conversion module into protos/types/conversion/
- Move protos module from inline in lib.rs to separate directory
- Update import paths in handlers

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Simplify the gRPC handler architecture by removing the intermediate
provider traits:

- Remove StarknetApiProvider, StarknetTraceApiProvider, and
  StarknetWriteApiProvider traits
- StarknetHandler now directly wraps StarknetApi<Pool, PP, PF>
- gRPC service implementations call StarknetApi methods directly
- Delete impls.rs (no longer needed)
- Update server.rs to take StarknetApi in start() method

This eliminates boilerplate while maintaining the same functionality.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Add clippy allow attributes for generated proto code (enum_variant_names, large_enum_variant)
- Add cfg(feature = "grpc") guards in exit.rs
- Fix format string inlining in chain_id handler
- Add result_large_err allow for gRPC Status returns
- Replace get().is_some/none() with contains_key() in CLI tests

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@kariy kariy marked this pull request as draft January 30, 2026 22:14
kariy and others added 5 commits January 30, 2026 22:19
Gate GrpcOptions and related code under both 'server' and 'grpc'
features in the CLI crate for better feature modularity.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add a unified gRPC client that provides access to all Starknet services
(read, write, trace) through a single interface with builder pattern
configuration.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
kariy and others added 11 commits February 2, 2026 16:12
- Add TryFrom implementations for proto -> RPC type conversions
  - BroadcastedInvokeTransaction (V1, V3)
  - BroadcastedDeclareTransaction (V2, V3)
  - BroadcastedDeployAccountTransaction (V1, V3)
  - ResourceBoundsMapping
  - ContractClass
- Add example client binary for testing gRPC endpoints

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Remove versioned wrapper types (V1/V2/V3) for broadcasted transactions
and use flat message structures that match the RPC types exactly.

This simplifies the proto definitions and conversion code by:
- Replacing BroadcastedInvokeTxnV1/V3 with a single BroadcastedInvokeTransaction
- Replacing BroadcastedDeclareTxnV2/V3 with a single BroadcastedDeclareTransaction
- Replacing BroadcastedDeployAccountTxnV1/V3 with a single BroadcastedDeployAccountTransaction
- Adding bidirectional conversions (RPC -> Proto and Proto -> RPC)
- Adding is_query field to match RPC type semantics

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add event type conversions and implement the get_events gRPC handler
by delegating to the underlying StarknetApi events method.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add type conversions for storage proof proto types and implement the
gRPC handler that delegates to the underlying RPC API's get_proofs method.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@kariy kariy marked this pull request as ready for review February 3, 2026 22:25
@codecov
Copy link

codecov bot commented Feb 3, 2026

Codecov Report

❌ Patch coverage is 9.23151% with 1878 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.43%. Comparing base (9bde0ae) to head (3dbecee).
⚠️ Report is 241 commits behind head on main.

Files with missing lines Patch % Lines
...es/grpc/src/protos/types/conversion/transaction.rs 0.00% 494 Missing ⚠️
crates/grpc/src/handlers/starknet.rs 0.00% 294 Missing ⚠️
crates/grpc/src/protos/types/conversion/block.rs 0.00% 244 Missing ⚠️
crates/grpc/src/client.rs 0.00% 223 Missing ⚠️
crates/grpc/src/protos/types/conversion/trace.rs 0.00% 155 Missing ⚠️
crates/grpc/src/protos/types/conversion/receipt.rs 0.00% 91 Missing ⚠️
crates/grpc/src/protos/types/conversion/trie.rs 0.00% 69 Missing ⚠️
crates/grpc/src/error.rs 0.00% 59 Missing ⚠️
crates/grpc/src/server.rs 0.00% 56 Missing ⚠️
crates/grpc/src/protos/types/conversion/state.rs 0.00% 53 Missing ⚠️
... and 9 more
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #408      +/-   ##
==========================================
- Coverage   73.32%   68.43%   -4.89%     
==========================================
  Files         209      266      +57     
  Lines       23132    31777    +8645     
==========================================
+ Hits        16961    21748    +4787     
- Misses       6171    10029    +3858     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@kariy kariy merged commit 3661d53 into main Feb 5, 2026
15 of 18 checks passed
@kariy kariy deleted the feat/grpc branch February 5, 2026 17:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant