gRPC: Add gRPC interface to cardano-node with tests in cardano-testnet by carbolymer · Pull Request #6273 · IntersectMBO/cardano-node

carbolymer · 2025-07-04T15:37:47Z

Description

This PR adds an experimental gRPC endpoint to cardano-node. The gRPC endpoint implements UTXORPC schema. For now the following methods are supported:

Query
- ReadParams
- ReadUtxos
Submit
- SubmitTx

The gRPC endpoint is disabled by default, can be enabled by CLI flag or by configuration option.

Support for enabling gRPC endpoint is added into cardano-testnet.

Things necessary to do before the merge:

Release cardano-cli to remove SRP
Release cardano-rpc to remove SRP

Checklist

Commit sequence broadly makes sense and commits have useful messages
New tests are added if needed and existing tests are updated. These may include:
- golden tests
- property tests
- roundtrip tests
- integration tests
  See Runnings tests for more details
Any changes are noted in the CHANGELOG.md for affected package
The version bounds in .cabal files are updated
CI passes. See note on CI. The following CI checks are required:
- Code is linted with hlint. See .github/workflows/check-hlint.yml to get the hlint version
- Code is formatted with stylish-haskell. See .github/workflows/stylish-haskell.yml to get the stylish-haskell version
- Code builds on Linux, MacOS and Windows for ghc-9.6 and ghc-9.12
Self-reviewed the diff

Note on CI

If your PR is from a fork, the necessary CI jobs won't trigger automatically for security reasons.
You will need to get someone with write privileges. Please contact IOG node developers to do this
for you.

Copilot

Pull request overview

Copilot reviewed 33 out of 34 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

cardano-node/src/Cardano/Node/Configuration/POM.hs:316

AdjustFilePaths for PartialNodeConfiguration only rewrites pncProtocolConfig and pncSocketConfig, but the new pncRpcConfig can also contain file paths (e.g. RpcSocketPath). This means relative RPC socket paths in configuration.yaml won’t be made relative to the config directory, unlike other path fields. Extend adjustFilePaths here to include pncRpcConfig (and any nested File fields via the new AdjustFilePaths instances).

instance AdjustFilePaths PartialNodeConfiguration where
  adjustFilePaths f x =
    x { pncProtocolConfig = adjustFilePaths f (pncProtocolConfig x)
      , pncSocketConfig   = adjustFilePaths f (pncSocketConfig x)
      }

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-12T15:51:10Z

cardano-node/src/Cardano/Node/Tracing/Tracers/Rpc.hs

+  ( Object
+  , Value (..)
+  , (.=)
+  )


This new module doesn’t follow the repository’s stylish-haskell formatting conventions (e.g. imports aren’t aligned/indented like other tracer modules). This is likely to fail the formatting CI check; please run stylish-haskell (or apply the repo formatter) on this file.

Suggested change

( Object

, Value (..)

, (.=)

)

( Object

, Value (..)

, (.=)

)

Copilot · 2026-03-12T15:51:10Z

.github/ISSUE_TEMPLATE/config.yml

+  - name: Cardano gRPC Issues
+    url: https://github.com/IntersectMBO/cardano-api/issues
+    about: Report gRPC endpoint related issues here


The new “Cardano gRPC Issues” contact link points to the same URL as “Cardano API Issues” (cardano-api/issues). If gRPC issues should be tracked elsewhere (e.g. cardano-node or cardano-rpc), update the URL; otherwise this extra entry is redundant and may confuse reporters.

Suggested change

- name: Cardano gRPC Issues

url: https://github.com/IntersectMBO/cardano-api/issues

about: Report gRPC endpoint related issues here

Copilot · 2026-03-12T15:51:11Z

cardano-testnet/changelog.d/20260220_120000_mgalazyn_add_grpc_interface.md

+
+- Added `--enable-grpc` flag to `cardano-testnet` to enable the gRPC interface (via `cardano-rpc`) when starting a testnet.
+- Added `cardanoEnableRpc` field to `CardanoTestnetOptions` (default `False`).
+- Added `nodeRpcSocketPath` helper to `Testnet.Types` for deriving the gRPC socket path from a node's socket path.


The PR changes the cardano-testnet CLI flag name from --nodeLoggingFormat to --node-logging-format (see updated golden help + parser), which is a user-facing breaking change. The changelog fragment currently doesn’t mention this rename; please add a bullet under “Added”/“Changed” documenting the flag rename (and any compatibility/aliasing, if supported).

Suggested change

- Added `nodeRpcSocketPath` helper to `Testnet.Types` for deriving the gRPC socket path from a node's socket path.

- Added `nodeRpcSocketPath` helper to `Testnet.Types` for deriving the gRPC socket path from a node's socket path.

- Renamed `cardano-testnet` CLI flag `--nodeLoggingFormat` to `--node-logging-format`.

Copilot · 2026-03-12T15:51:11Z

cardano-testnet/test/cardano-testnet-test/Cardano/Testnet/Test/Rpc/Transaction.hs

+import qualified Cardano.Rpc.Proto.Api.UtxoRpc.Query as U5c hiding (cardano, items, tx)
+import qualified Cardano.Rpc.Proto.Api.UtxoRpc.Query as UtxoRpc
+import qualified Cardano.Rpc.Proto.Api.UtxoRpc.Submit as U5c
+import qualified Cardano.Rpc.Proto.Api.UtxoRpc.Submit as UtxoRpc


U5c is used as the qualified alias for both ...UtxoRpc.Query and ...UtxoRpc.Submit, and the Query import also hides identifiers (cardano, items, tx) that are referenced later in the module (e.g. U5c.values . U5c.cardano, utxosResponse ^. U5c.items, U5c.tx). As written this won’t compile (hidden names out of scope / ambiguous qualified imports). Use distinct qualifiers (e.g. Query/Submit) or remove the incorrect hiding and consistently reference the intended module alias.

Suggested change

import qualified Cardano.Rpc.Proto.Api.UtxoRpc.Query as U5c hiding (cardano, items, tx)

import qualified Cardano.Rpc.Proto.Api.UtxoRpc.Query as UtxoRpc

import qualified Cardano.Rpc.Proto.Api.UtxoRpc.Submit as U5c

import qualified Cardano.Rpc.Proto.Api.UtxoRpc.Submit as UtxoRpc

import qualified Cardano.Rpc.Proto.Api.UtxoRpc.Query as U5c

import qualified Cardano.Rpc.Proto.Api.UtxoRpc.Query as UtxoRpcQuery

import qualified Cardano.Rpc.Proto.Api.UtxoRpc.Submit as U5cSubmit

import qualified Cardano.Rpc.Proto.Api.UtxoRpc.Submit as UtxoRpcSubmit

Copilot · 2026-03-12T15:51:11Z

cardano-node/src/Cardano/Node/Configuration/POM.hs

+{- HLINT ignore "Functor law" -}
+


This file adds a top-level {- HLINT ignore "Functor law" -} directive, but there are no Functor instances in this module. This suppression is likely stale/unnecessary and makes it easier to miss real Functor-law violations introduced later. Consider removing it, or scoping the suppression to the specific declaration/expression that triggers hlint (if any).

Suggested change

{- HLINT ignore "Functor law" -}

Jimbo4350

Minor comments but I would solicit feedback from @jasagredo regarding the configuration change. Will approve after that is discussed.

Jimbo4350 · 2026-03-12T16:49:47Z

cardano-node/src/Cardano/Node/Configuration/POM.hs

       , pncResponderCoreAffinityPolicy :: !(Last ResponderCoreAffinityPolicy)
+
+         -- gRPC
+       , pncRpcConfig :: !PartialRpcConfig


Same here regarding the configuration being moved to consensus.

Jimbo4350 · 2026-03-12T16:50:05Z

cardano-node/src/Cardano/Node/Configuration/POM.hs

       , ncResponderCoreAffinityPolicy :: ResponderCoreAffinityPolicy
+
+         -- gRPC
+       , ncRpcConfig :: RpcConfig


Hmm. @jasagredo is working on moving the cardano node configuration machinery to ouroboros-consensus. To prevent future pain I would run this change by him.

Jimbo4350 · 2026-03-12T16:52:35Z

cardano-testnet/test/cardano-testnet-golden/files/golden/help/cardano.cli

 Usage: cardano-testnet cardano [--num-pool-nodes COUNT]
  [--max-lovelace-supply WORD64]
-  [--nodeLoggingFormat LOGGING_FORMAT]
+  [--node-logging-format LOGGING_FORMAT]


Jimbo4350 · 2026-03-12T16:53:25Z

cardano-node/src/Cardano/Node/Tracing/Tracers/Rpc.hs

+    mconcat $
+      ("reason" .= prettyShow tr)
+        : case tr of
+          TraceRpcFatalError _ -> ["kind" .= String "FatalError"]


Where can one see the reason for the fatal error?

Jimbo4350 · 2026-03-12T18:39:03Z

cardano-testnet/src/Testnet/Start/Types.hs

  , cardanoEnableNewEpochStateLogging :: Bool -- ^ if epoch state logging is enabled
  , cardanoEnableTxGenerator :: TxGeneratorSupport -- ^ Options regarding support for the tx-generator on the testnet (config generation, execution, etc.)
  , cardanoOutputDir :: UserProvidedEnv -- ^ The output directory where to store files, sockets, and so on. If unset, a temporary directory is used.
+  , cardanoEnableRpc :: Bool


I don't like this for boolean blindness reasons. Please define a sum type.

Jimbo4350 · 2026-03-12T18:46:03Z

cardano-testnet/test/cardano-testnet-test/Cardano/Testnet/Test/Rpc/Query.hs

+  ---------------------------
+  -- Test readParams response
+  ---------------------------
+  pparamsResponse ^. U5c.ledgerTip . U5c.slot === slot


How flaky is this test?

Jimbo4350 · 2026-03-12T18:48:16Z

cardano-testnet/test/cardano-testnet-test/Cardano/Testnet/Test/Rpc/Query.hs

+import qualified Hedgehog.Extras.Test.Base as H
+import qualified Hedgehog.Extras.Test.TestWatchdog as H
+
+hprop_rpc_query_pparams :: Property


Can you add a comment describing what this property is testing and a command we can use to run only this property.

Jimbo4350 · 2026-03-12T18:50:25Z

cardano-testnet/test/cardano-testnet-test/Cardano/Testnet/Test/Rpc/Transaction.hs

+
+import           RIO (ByteString, threadDelay)
+
+hprop_rpc_transaction :: Property


Same here, a comment describing what this tests along with a command to run just this property.

Jimbo4350 · 2026-03-12T18:53:04Z

cardano-testnet/test/cardano-testnet-test/Cardano/Testnet/Test/Rpc/Transaction.hs

+
+  txBody <- H.leftFail $ createTransactionBody sbe content
+
+  let signedTx = signShelleyTransaction sbe txBody [wit0]


I see we are using the "old" api. Fine for this PR but I'd like you to migrate to the new api if possible in a follow up PR.

Jimbo4350 · 2026-03-12T18:55:53Z

cardano-testnet/test/cardano-testnet-test/Cardano/Testnet/Test/Rpc/Transaction.hs

+        loop
+
+    utxos <-
+      Rpc.nonStreaming conn (Rpc.rpc @(Rpc.Protobuf UtxoRpc.QueryService "readUtxos")) def -- & # U5c.keys .~ [T.encodeUtf8 addrTxt1]


Left over comment?

carbolymer self-assigned this Jul 4, 2025

carbolymer changed the title ~~cardano-rpc | Add gRPC interface to cardano-node, add tests to cardano-testnet~~ cardano-rpc | Add gRPC interface to cardano-node with tests in cardano-testnet Jul 4, 2025

carbolymer force-pushed the mgalazyn/feature/add-grpc-interface branch 2 times, most recently from 864cf20 to 12bae80 Compare July 10, 2025 15:37

This was linked to issues Jul 11, 2025

gRPC: UTxORPC SubmitTx method of submit service #6246

Closed

gRPC: Command-line and configuration flags for cardano-rpc settings in cardano-node #6247

Open

carbolymer force-pushed the mgalazyn/feature/add-grpc-interface branch from 0004d02 to 2c89086 Compare July 23, 2025 14:20

carbolymer mentioned this pull request Jul 24, 2025

cardano-rpc | Add UTxO RPC: submitTx method IntersectMBO/cardano-api#905

Merged

3 tasks

carbolymer force-pushed the mgalazyn/feature/add-grpc-interface branch 3 times, most recently from aaab28c to eab2ed1 Compare July 25, 2025 16:57

palas force-pushed the mgalazyn/feature/add-grpc-interface branch 4 times, most recently from 4d19d4c to 98d8073 Compare August 3, 2025 20:00

carbolymer force-pushed the mgalazyn/feature/add-grpc-interface branch from 12d7ab5 to 73c37e6 Compare September 4, 2025 16:45

carbolymer force-pushed the mgalazyn/feature/add-grpc-interface branch from 8cbf3f2 to 0ec9ea7 Compare October 2, 2025 12:29

carbolymer added this to DevTools roadmap Nov 13, 2025

carbolymer changed the title ~~cardano-rpc | Add gRPC interface to cardano-node with tests in cardano-testnet~~ gRPC: Add gRPC interface to cardano-node with tests in cardano-testnet Nov 13, 2025

This was linked to issues Nov 13, 2025

gRPC: UTxORPC ReadParams method of query service #6251

Closed

gRPC: UTxORPC readUtxos method of query service #6363

Closed

carbolymer removed this from DevTools roadmap Nov 13, 2025

carbolymer linked an issue Nov 13, 2025 that may be closed by this pull request

gRPC: Integration of gRPC metrics into cardano-node tracing and monitoring system #6254

Open

carbolymer removed a link to an issue Nov 13, 2025

gRPC: Integration of gRPC metrics into cardano-node tracing and monitoring system #6254

Open

carbolymer linked an issue Nov 13, 2025 that may be closed by this pull request

gRPC: Integration of gRPC logging into cardano-node tracing system #6365

Open

carbolymer force-pushed the mgalazyn/feature/add-grpc-interface branch 2 times, most recently from 7c29f29 to ebf5f8b Compare November 17, 2025 08:33

carbolymer force-pushed the mgalazyn/feature/add-grpc-interface branch 2 times, most recently from a8564a9 to 5d772e5 Compare November 28, 2025 20:50

carbolymer force-pushed the mgalazyn/feature/add-grpc-interface branch from 5d772e5 to 450a849 Compare January 7, 2026 18:51

carbolymer force-pushed the mgalazyn/feature/add-grpc-interface branch 7 times, most recently from 86ec635 to 9984a35 Compare February 24, 2026 17:13

carbolymer requested a review from Copilot February 24, 2026 17:13

Copilot started reviewing on behalf of carbolymer February 24, 2026 17:14 View session

This comment was marked as outdated.

Sign in to view

carbolymer force-pushed the mgalazyn/feature/add-grpc-interface branch 4 times, most recently from 7b30930 to 8e67434 Compare February 26, 2026 14:55

carbolymer changed the title ~~WIP: gRPC: Add gRPC interface to cardano-node with tests in cardano-testnet~~ gRPC: Add gRPC interface to cardano-node with tests in cardano-testnet Mar 2, 2026

carbolymer force-pushed the mgalazyn/feature/add-grpc-interface branch 3 times, most recently from 2ea442d to 8f6a3b7 Compare March 9, 2026 16:26

Add cardano-rpc cabal dependency

fdb32ef

This comment was marked as outdated.

Sign in to view

carbolymer added 2 commits March 12, 2026 13:49

Add cardano-rpc configuration to node configuration file

ed7e9fe

Add cardano-rpc tracing

25eb12e

This comment was marked as outdated.

Sign in to view

carbolymer added 4 commits March 12, 2026 15:06

Add cardano-rpc to node startup

5dc4415

Add cardano-rpc support in cardano-testnet

3ecd6ca

Add cardano-rpc tests in cardano-testnet

fd1d06c

Add cardano-testnet changelog entry

247556e

Copilot AI reviewed Mar 12, 2026

View reviewed changes

Jimbo4350 mentioned this pull request Mar 12, 2026

cardano-testnet: Replace eon-based era witnesses with Exp.IsEra/Era #6487

Open

Jimbo4350 reviewed Mar 12, 2026

View reviewed changes

	- name: Cardano gRPC Issues
	url: https://github.com/IntersectMBO/cardano-api/issues
	about: Report gRPC endpoint related issues here

	- Added `nodeRpcSocketPath` helper to `Testnet.Types` for deriving the gRPC socket path from a node's socket path.
	- Added `nodeRpcSocketPath` helper to `Testnet.Types` for deriving the gRPC socket path from a node's socket path.
	- Renamed `cardano-testnet` CLI flag `--nodeLoggingFormat` to `--node-logging-format`.


		import RIO (ByteString, threadDelay)

		hprop_rpc_transaction :: Property


		txBody <- H.leftFail $ createTransactionBody sbe content

		let signedTx = signShelleyTransaction sbe txBody [wit0]

Conversation

carbolymer commented Jul 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Note on CI

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 12, 2026

Choose a reason for hiding this comment

Uh oh!

Jimbo4350 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Jimbo4350 Mar 12, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

carbolymer commented Jul 4, 2025 •

edited

Loading

Jimbo4350 Mar 12, 2026 •

edited

Loading