feat: add extensible QueryLedgerState RPC with stake pool distribution

proto/utxorpc/v1beta/cardano/cardano.proto

@@ -539,6 +539,46 @@ message UpdateDRepCert {
   Anchor anchor = 2;
 }
 
+// LEDGER-STATE QUERIES
+// ====================
+//
+// Cardano-specific queries that mirror the Ouroboros node-to-client
+// LocalStateQuery mini-protocol. The oneof envelope lets new queries be
+// added later without changing the chain-agnostic QueryService surface.
+
+// Envelope of a Cardano ledger-state query.
+message StateQuery {
+  oneof query {
+    GetStakePoolDistribution stake_pool_distribution = 1; // Active stake distribution across pools.
+  }
+}
+
+// Envelope of a Cardano ledger-state query result.
+message StateData {
+  oneof result {
+    StakePoolDistribution stake_pool_distribution = 1; // Result of a stake pool distribution query.
+  }
+}
+
+// Stake pool distribution query. Mirrors Ouroboros GetPoolDistr / GetFilteredPoolDistr.
+message GetStakePoolDistribution {
+  // If non-empty, restrict the result to the listed pool key hashes.
+  // If empty, return the distribution for every pool.
+  repeated bytes pool_keyhashes = 1;
+}
+
+// Per-pool stake share. Mirrors Ouroboros IndividualPoolStake.
+message PoolStakeShare {
+  bytes pool_keyhash = 1; // Pool key hash (pool id).
+  RationalNumber stake_fraction = 2; // Fraction of total active stake delegated to this pool.
+  bytes vrf_keyhash = 3; // Pool's VRF key hash, as reported by the node.
+}
+
+// Result of a stake pool distribution query.
+message StakePoolDistribution {
+  repeated PoolStakeShare pools = 1; // One entry per pool present in the snapshot.
+}
+
 // PATTERN MATCHING
 // ================
 

proto/utxorpc/v1beta/query/query.proto

@@ -72,6 +72,32 @@ message ReadParamsResponse {
   ChainPoint ledger_tip = 2; // The chain point that represent the ledger current position.
 }
 
+// An envelope that wraps a chain-specific ledger-state query.
+message AnyChainStateQuery {
+  oneof query {
+    utxorpc.v1beta.cardano.StateQuery cardano = 1; // A Cardano ledger-state query.
+  }
+}
+
+// An envelope that wraps a chain-specific ledger-state query result.
+message AnyChainStateData {
+  oneof result {
+    utxorpc.v1beta.cardano.StateData cardano = 1; // A Cardano ledger-state query result.
+  }
+}
+
+// Request to run a chain-specific ledger-state query against the current ledger snapshot.
+message ReadStateRequest {
+  AnyChainStateQuery query = 1; // The chain-specific query to evaluate.
+  google.protobuf.FieldMask field_mask = 2; // Field mask to selectively return fields.
+}
+
+// Response carrying the ledger-state query result.
+message ReadStateResponse {
+  AnyChainStateData result = 1; // The query result.
+  ChainPoint ledger_tip = 2; // Chain point representing the snapshot the query was evaluated against.
+}
+
 // An evenlope that holds an UTxO patterns from any of compatible chains
 message AnyUtxoPattern {
   oneof utxo_pattern {
@@ -175,6 +201,7 @@ service QueryService {
   rpc ReadTx(ReadTxRequest) returns (ReadTxResponse); // Get Txs by chain-specific criteria.
   rpc ReadGenesis(ReadGenesisRequest) returns (ReadGenesisResponse); // Get the genesis configuration
   rpc ReadEraSummary(ReadEraSummaryRequest) returns (ReadEraSummaryResponse); // Get the chain era summary
+  rpc ReadState(ReadStateRequest) returns (ReadStateResponse); // Run a chain-specific ledger-state query (e.g. stake pool distribution).
 
   // TODO: decide if we want to expand the scope
   // rpc DumpUtxos(ReadUtxosRequest) returns (stream ReadUtxosResponse); // Dump all available utxos