wip

Author: carbolymer

CLAUDE.md

@@ -0,0 +1,21 @@
+# Claude Code notes
+
+## Rules
+- Never manually edit generated code (e.g. proto-lens output in `gen/`). Use nix dev shell to run code generation tools (e.g. `nix develop --command bash -c "cd cardano-rpc && buf generate proto"`)
+- Never modify the nix store
+
+## cardano-rpc patterns
+- `Proto msg` is a grapesy newtype wrapper. Internal functions should use plain proto-lens types, not `Proto`-wrapped. Use `getProto`/`fmap getProto` only at the RPC handler boundary.
+- RIO hides many Prelude functions. `sortBy` is NOT re-exported by RIO -- import from `Data.List`. Check RIO re-exports before assuming standard functions are in scope.
+- RIO's `^.` works with proto-lens van Laarhoven lenses. No need for `lens-family` dependency.
+- Use `toList` (from `GHC.IsList`) instead of deprecated `valueToList` for `Value`.
+
+## Mistakes and wrong assumptions (lessons learned)
+- Assumed generated code could be patched by hand -- WRONG. Always use the project's code generation pipeline.
+- Assumed proto-lens types would be used wrapped in `Proto` everywhere -- WRONG. `Proto` is only at the gRPC handler boundary. Internal logic uses raw proto-lens types.
+- Assumed RIO re-exports all of `Data.List` -- WRONG. `sortBy`, `on`, and others need explicit imports.
+- Assumed I needed `lens-family` for proto-lens field access -- WRONG. RIO's `^.` (from `microlens`) is compatible with proto-lens van Laarhoven lenses.
+- Used deprecated `valueToList` instead of checking for the current API (`toList` via `GHC.IsList`).
+- Left redundant `IsEra` constraint on `matchesTxOutputPattern` -- should check if constraints are actually needed before adding them.
+- Wrote lambdas where infix notation was cleaner (`\sub -> f sub x` vs `` `f` x ``). hlint caught this.
+- Minimize nix build round-trips: verify types, imports, and constraints carefully before building.

cardano-rpc/cardano-rpc.cabal

@@ -70,6 +70,7 @@ library
     bytestring,
     cardano-api >=10.17,
     cardano-binary,
+    cardano-crypto-class,
     cardano-ledger-api,
     cardano-ledger-conway,
     cardano-ledger-core,

cardano-rpc/gen/Proto/Utxorpc/V1beta/Query/Query.hs

@@ -170,6 +170,7 @@ message ReadTxResponse {
 service QueryService {
   rpc ReadParams(ReadParamsRequest) returns (ReadParamsResponse); // Get overall chain state.
   rpc ReadUtxos(ReadUtxosRequest) returns (ReadUtxosResponse); // Read specific UTxOs by reference.
+  rpc SearchUtxos(SearchUtxosRequest) returns (SearchUtxosResponse); // Search for UTxO based on a pattern.
 
   // TODO: decide if we want to expand the scope
   // rpc DumpUtxos(ReadUtxosRequest) returns (stream ReadUtxosResponse); // Dump all available utxos

cardano-rpc/proto/utxorpc/v1beta/query/query.proto

@@ -56,6 +56,7 @@ methodsUtxoRpc
 methodsUtxoRpc =
   Method (mkNonStreaming $ wrapInSpan TraceRpcQueryParamsSpan . readParamsMethod)
     . Method (mkNonStreaming $ wrapInSpan TraceRpcQueryReadUtxosSpan . readUtxosMethod)
+    . Method (mkNonStreaming $ wrapInSpan TraceRpcQuerySearchUtxosSpan . searchUtxosMethod)
     $ NoMoreMethods
 
 methodsUtxoRpcSubmit

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

@@ -27,6 +27,8 @@ data TraceRpcQuery
     TraceRpcQueryParamsSpan TraceSpanEvent
   | -- | Span trace marking ReadUtxos query
     TraceRpcQueryReadUtxosSpan TraceSpanEvent
+  | -- | Span trace marking SearchUtxos query
+    TraceRpcQuerySearchUtxosSpan TraceSpanEvent
   deriving Show
 
 instance Pretty TraceRpc where
@@ -53,6 +55,8 @@ instance Pretty TraceRpcQuery where
     TraceRpcQueryParamsSpan (SpanEnd _) -> "Finished query params method"
     TraceRpcQueryReadUtxosSpan (SpanBegin _) -> "Started query read UTXO method"
     TraceRpcQueryReadUtxosSpan (SpanEnd _) -> "Finished query read UTXO method"
+    TraceRpcQuerySearchUtxosSpan (SpanBegin _) -> "Started query search UTXO method"
+    TraceRpcQuerySearchUtxosSpan (SpanEnd _) -> "Finished query search UTXO method"
 
 instance Error TraceRpcQuery where
   prettyError = pretty

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

@@ -11,6 +11,7 @@
 module Cardano.Rpc.Server.Internal.UtxoRpc.Query
   ( readParamsMethod
   , readUtxosMethod
+  , searchUtxosMethod
   )
 where
 
@@ -26,8 +27,11 @@ import Cardano.Rpc.Server.Internal.UtxoRpc.Type
 import RIO hiding (toList)
 
 import Data.Default
+import Data.List (sortBy)
 import Data.ProtoLens (defMessage)
+import Data.Text qualified as T
 import GHC.IsList
+import Network.GRPC.Common.Protobuf (getProto)
 import Network.GRPC.Spec
 
 readParamsMethod
@@ -63,9 +67,6 @@ readUtxosMethod req = do
   utxoFilter <-
     if not (null $ req ^. U5c.keys)
       then QueryUTxOByTxIn . fromList <$> mapM txoRefToTxIn (req ^. U5c.keys)
-      -- TODO: reimplement this part as SearchUtxosRequest
-      -- \| Just addressesProto <- req ^. U5c.maybe'cardanoAddresses ->
-      --     QueryUTxOByAddress . fromList <$> mapM readAddress (addressesProto ^. U5c.items)
       else pure QueryUTxOWhole
 
   nodeConnInfo <- grab
@@ -89,7 +90,69 @@ readUtxosMethod req = do
     txId' <- throwEither $ deserialiseFromRawBytes AsTxId $ r ^. U5c.hash
     pure $ TxIn txId' (TxIx . fromIntegral $ r ^. U5c.index)
 
--- TODO: reimplement this part as SearchUtxosRequest
--- readAddress :: MonadRpc e m => ByteString -> m AddressAny
--- readAddress =
---   throwEither . first stringException . P.runParser parseAddressAny <=< throwEither . T.decodeUtf8'
+searchUtxosMethod
+  :: MonadRpc e m
+  => Proto UtxoRpc.SearchUtxosRequest
+  -> m (Proto UtxoRpc.SearchUtxosResponse)
+searchUtxosMethod req = do
+  let mPredicate = fmap getProto $ req ^. U5c.maybe'predicate
+      maxItems = req ^. U5c.maxItems
+      startToken = req ^. U5c.startToken
+
+  -- Determine query strategy: use address-based query if possible, otherwise fetch whole UTxO
+  let utxoFilter = case mPredicate >>= extractAddressesFromPredicate of
+        Just addrs | not (null addrs) -> QueryUTxOByAddress addrs
+        _ -> 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) <- liftIO . (throwEither =<<) $ executeLocalStateQueryExpr nodeConnInfo target $ do
+    utxo <- throwEither =<< throwEither =<< queryUtxo (convert eon) utxoFilter
+    chainPoint <- throwEither =<< queryChainPoint
+    blockNo <- throwEither =<< queryChainBlockNo
+    pure (utxo, chainPoint, blockNo)
+
+  -- Apply predicate filtering on the result
+  let filtered = case mPredicate of
+        Nothing -> toList utxo
+        Just p ->
+          filter (\(_txIn, txOut) -> obtainCommonConstraints eon (matchesUtxoPredicate p txOut)) (toList utxo)
+
+  -- Sort by TxIn for deterministic pagination
+  let sorted = sortBy (compare `on` fst) filtered
+
+  -- Apply pagination: skip past start_token, then take max_items
+  let afterToken = case startToken of
+        t | T.null t -> sorted
+        _ -> dropWhile (\(txIn, _) -> encodeTxInToken txIn <= startToken) sorted
+      limit = if maxItems > 0 then fromIntegral maxItems else 100 -- default page size
+      page = take limit afterToken
+      nextTok =
+        if length page >= limit && length afterToken > limit
+          then case lastMaybe page of
+            Just (lastTxIn, _) -> encodeTxInToken lastTxIn
+            Nothing -> ""
+          else ""
+
+  pure $
+    defMessage
+      & U5c.ledgerTip .~ mkChainPointMsg chainPoint blockNo
+      & U5c.items .~ obtainCommonConstraints eon (map (uncurry txInTxOutToAnyUtxoData) page)
+      & U5c.nextToken .~ nextTok
+ where
+  txInTxOutToAnyUtxoData :: IsEra era => TxIn -> TxOut CtxUTxO era -> Proto UtxoRpc.AnyUtxoData
+  txInTxOutToAnyUtxoData txIn txOut =
+    defMessage
+      & U5c.txoRef .~ inject txIn
+      & U5c.cardano .~ txOutToUtxoRpcTxOutput txOut
+
+  encodeTxInToken :: TxIn -> T.Text
+  encodeTxInToken (TxIn txId (TxIx ix)) =
+    serialiseToRawBytesHexText txId <> "#" <> T.pack (show ix)
+
+  lastMaybe :: [a] -> Maybe a
+  lastMaybe [] = Nothing
+  lastMaybe xs = Just (last xs)