Merge pull request #1214 from IntersectMBO/mgalazyn/fix/guard-utxo-whole-set

cardano-rpc: guard against fetching entire UTXO set.

Author: carbolymer

.changes/20260519_cardano_rpc_guard_utxo_whole_set.yml

@@ -0,0 +1,6 @@
+project: cardano-rpc
+pr: 1214
+kind:
+  - breaking
+description: |
+  gRPC: Guard against fetching the entire UTxO set. ReadUtxos now returns an empty response when no keys are provided. SearchUtxos now rejects predicates that cannot be narrowed to specific addresses with INVALID_ARGUMENT, instead of falling back to QueryUTxOWhole.

cardano-rpc/cardano-rpc.cabal

@@ -75,7 +75,7 @@ library
     aeson,
     base,
     bytestring,
-    cardano-api >=10.17,
+    cardano-api >=11.2,
     cardano-binary,
     cardano-ledger-api,
     cardano-ledger-conway,

cardano-rpc/src/Cardano/Rpc/Server/Internal/Error.hs

@@ -12,6 +12,7 @@
 module Cardano.Rpc.Server.Internal.Error
   ( throwEither
   , throwExceptT
+  , throwGrpcErrorWithMessage
   , RpcException (..)
   )
 where
@@ -21,6 +22,7 @@ import Cardano.Api
 import RIO
 
 import GHC.Stack
+import Network.GRPC.Spec (GrpcError, GrpcException (..))
 
 throwEither :: (Error e, HasCallStack, MonadIO m, Show e, Typeable e) => Either e a -> m a
 throwEither = withFrozenCallStack $ either (throwIO . RpcException) pure
@@ -39,3 +41,15 @@ instance Exception RpcException where
       [ show (prettyError e)
       , prettyCallStack callStack
       ]
+
+-- | Throw a 'GrpcException' with the given error code and message.
+-- grapesy converts this to proper gRPC trailers before it reaches 'serverTopLevel'.
+throwGrpcErrorWithMessage :: MonadIO m => GrpcError -> Text -> m a
+throwGrpcErrorWithMessage err message =
+  throwIO
+    GrpcException
+      { grpcError = err
+      , grpcErrorMessage = Just message
+      , grpcErrorDetails = Nothing
+      , grpcErrorMetadata = []
+      }

cardano-rpc/src/Cardano/Rpc/Server/Internal/UtxoRpc/Query.hs

@@ -74,35 +74,36 @@ readParamsMethod _req = do
 -- | Handle the @ReadUtxos@ RPC method.
 -- Looks up specific UTxO entries by their 'TxIn' keys and returns them
 -- along with the ledger tip.
+-- Returns an empty response when no keys are provided, matching other
+-- UTxO RPC implementations (Dolos, cardano-node-api, Dingo).
 readUtxosMethod
   :: MonadRpc e m
   => Proto UtxoRpc.ReadUtxosRequest
   -> m (Proto UtxoRpc.ReadUtxosResponse)
-readUtxosMethod req = do
-  utxoFilter <-
-    if not (null $ req ^. U5c.keys)
-      then QueryUTxOByTxIn . fromList <$> mapM txoRefToTxIn (req ^. U5c.keys)
-      else pure QueryUTxOWhole
-
-  nodeConnInfo <- grab
-  AnyCardanoEra era <- liftIO . throwExceptT $ determineEra nodeConnInfo
-  eon <- forEraInEon @Era era (error "Minimum Conway era required") pure
-
-  let target = VolatileTip
-  (utxo, chainPoint, blockNo, systemStart, eraHistory) <- liftIO . (throwEither =<<) $ executeLocalStateQueryExpr nodeConnInfo target $ do
-    utxo <- throwEither =<< throwEither =<< queryUtxo (convert eon) utxoFilter
-    chainPoint <- throwEither =<< queryChainPoint
-    blockNo <- throwEither =<< queryChainBlockNo
-    systemStart <- throwEither =<< querySystemStart
-    eraHistory <- throwEither =<< queryEraHistory
-    pure (utxo, chainPoint, blockNo, systemStart, eraHistory)
-
-  timestamp <- slotToTimestamp systemStart eraHistory chainPoint
-
-  pure $
-    defMessage
-      & U5c.ledgerTip .~ mkChainPointMsg chainPoint blockNo timestamp
-      & U5c.items .~ obtainCommonConstraints eon (utxoToUtxoRpcAnyUtxoData utxo)
+readUtxosMethod req
+  | null $ req ^. U5c.keys = pure defMessage
+  | otherwise = do
+      utxoFilter <- QueryUTxOByTxIn . fromList <$> mapM txoRefToTxIn (req ^. U5c.keys)
+
+      nodeConnInfo <- grab
+      AnyCardanoEra era <- liftIO . throwExceptT $ determineEra nodeConnInfo
+      eon <- forEraInEon @Era era (error "Minimum Conway era required") pure
+
+      let target = VolatileTip
+      (utxo, chainPoint, blockNo, systemStart, eraHistory) <- liftIO . (throwEither =<<) $ executeLocalStateQueryExpr nodeConnInfo target $ do
+        utxo <- throwEither =<< throwEither =<< queryUtxo (convert eon) utxoFilter
+        chainPoint <- throwEither =<< queryChainPoint
+        blockNo <- throwEither =<< queryChainBlockNo
+        systemStart <- throwEither =<< querySystemStart
+        eraHistory <- throwEither =<< queryEraHistory
+        pure (utxo, chainPoint, blockNo, systemStart, eraHistory)
+
+      timestamp <- slotToTimestamp systemStart eraHistory chainPoint
+
+      pure $
+        defMessage
+          & U5c.ledgerTip .~ mkChainPointMsg chainPoint blockNo timestamp
+          & U5c.items .~ obtainCommonConstraints eon (utxoToUtxoRpcAnyUtxoData utxo)
  where
   txoRefToTxIn :: MonadRpc e m => Proto UtxoRpc.TxoRef -> m TxIn
   txoRefToTxIn r = do
@@ -111,8 +112,8 @@ readUtxosMethod req = do
 
 -- | Handle the @SearchUtxos@ RPC method.
 -- Filters the UTxO set by a predicate and returns a paginated result.
--- When the predicate contains exact address matches, the query is narrowed
--- to those addresses; otherwise the entire UTxO set is fetched.
+-- The predicate must contain exact address matches so the query can be
+-- narrowed; broad predicates are rejected with @INVALID_ARGUMENT@.
 searchUtxosMethod
   :: MonadRpc e m
   => Proto UtxoRpc.SearchUtxosRequest
@@ -123,10 +124,12 @@ searchUtxosMethod req = do
       maxItems = req ^. U5c.maxItems
       startToken = req ^. U5c.maybe'startToken
 
-  -- Determine query strategy: use address-based query if possible, otherwise fetch whole UTxO
-  let utxoFilter = case mPredicate >>= extractAddressesFromPredicate of
-        Just addrs -> QueryUTxOByAddress addrs
-        _ -> QueryUTxOWhole
+  utxoFilter <- case mPredicate >>= extractAddressesFromPredicate of
+    Just addrs -> pure $ QueryUTxOByAddress addrs
+    Nothing ->
+      throwGrpcErrorWithMessage
+        GrpcInvalidArgument
+        "predicate too broad: must contain exact address match to avoid fetching the entire UTxO set"
 
   nodeConnInfo <- grab
   AnyCardanoEra era <- liftIO . throwExceptT $ determineEra nodeConnInfo