diff --git a/proto/utxorpc/v1beta/cardano/cardano.proto b/proto/utxorpc/v1beta/cardano/cardano.proto index 24e54fa..2584373 100644 --- a/proto/utxorpc/v1beta/cardano/cardano.proto +++ b/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 // ================ diff --git a/proto/utxorpc/v1beta/query/query.proto b/proto/utxorpc/v1beta/query/query.proto index 8e83fa0..a1f7909 100644 --- a/proto/utxorpc/v1beta/query/query.proto +++ b/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