cardano-rpc | Add UTxO RPC: Update cardano.proto & query.proto with definitions for readUtxos

Author: carbolymer

cardano-rpc/proto/utxorpc/v1alpha/cardano/cardano.proto

@@ -2,6 +2,131 @@ syntax = "proto3";
 
 package utxorpc.v1alpha.cardano;
 
+// Purpose of the redeemer in a transaction.
+enum RedeemerPurpose {
+  REDEEMER_PURPOSE_UNSPECIFIED = 0;
+  REDEEMER_PURPOSE_SPEND = 1;
+  REDEEMER_PURPOSE_MINT = 2;
+  REDEEMER_PURPOSE_CERT = 3;
+  REDEEMER_PURPOSE_REWARD = 4;
+  REDEEMER_PURPOSE_VOTE = 5;
+  REDEEMER_PURPOSE_PROPOSE = 6;
+}
+
+// Redeemer information for a Plutus script.
+message Redeemer {
+  RedeemerPurpose purpose = 1; // Purpose of the redeemer.
+  PlutusData payload = 2; // Plutus data associated with the redeemer.
+  uint32 index = 3; // Index of the redeemer.
+  ExUnits ex_units = 4; // Execution units consumed by the redeemer.
+  bytes original_cbor = 5; // Original cbor-encoded data as seen on-chain
+}
+
+// Represents a transaction output in the Cardano blockchain.
+message TxOutput {
+  bytes address = 1; // Address receiving the output.
+  uint64 coin = 2; // Amount of ADA in the output.
+  repeated MultiAsset assets = 3; // Additional native (non-ADA) assets in the output.
+  Datum datum = 4; // Plutus data associated with the output.
+  Script script = 5; // Script associated with the output.
+}
+
+message Datum {
+  bytes hash = 1; // Hash of this datum as seen on-chain
+  PlutusData payload = 2; // Parsed Plutus data payload
+  bytes original_cbor = 3; // Original cbor-encoded data as seen on-chain
+}
+
+// Represents a custom asset in the Cardano blockchain.
+message Asset {
+  bytes name = 1; // Name of the custom asset.
+  uint64 output_coin = 2; // Quantity of the custom asset in case of an output.
+  int64 mint_coin = 3; // Quantity of the custom asset in case of a mint.
+}
+
+// Represents a multi-asset group in the Cardano blockchain.
+message MultiAsset {
+  bytes policy_id = 1; // Policy ID governing the custom assets.
+  repeated Asset assets = 2; // List of custom assets.
+  Redeemer redeemer = 3; // Redeemer for the Plutus script.
+}
+
+// Represents a native script in Cardano.
+message NativeScript {
+  oneof native_script {
+    bytes script_pubkey = 1; // Script based on an address key hash.
+    NativeScriptList script_all = 2; // Script that requires all nested scripts to be satisfied.
+    NativeScriptList script_any = 3; // Script that requires any of the nested scripts to be satisfied.
+    ScriptNOfK script_n_of_k = 4; // Script that requires k out of n nested scripts to be satisfied.
+    uint64 invalid_before = 5; // Slot number before which the script is invalid.
+    uint64 invalid_hereafter = 6; // Slot number after which the script is invalid.
+  }
+}
+
+// Represents a list of native scripts.
+message NativeScriptList {
+  repeated NativeScript items = 1; // List of native scripts.
+}
+
+// Represents a "k out of n" native script.
+message ScriptNOfK {
+  uint32 k = 1; // The number of required satisfied scripts.
+  repeated NativeScript scripts = 2; // List of native scripts.
+}
+
+// Represents a constructor for Plutus data in Cardano.
+message Constr {
+  uint32 tag = 1;
+  uint64 any_constructor = 2;
+  repeated PlutusData fields = 3;
+}
+
+// Represents a big integer for Plutus data in Cardano.
+message BigInt {
+  oneof big_int {
+    int64 int = 1;
+    bytes big_u_int = 2;
+    bytes big_n_int = 3;
+  }
+}
+
+// Represents a key-value pair for Plutus data in Cardano.
+message PlutusDataPair {
+  PlutusData key = 1; // Key of the pair.
+  PlutusData value = 2; // Value of the pair.
+}
+
+// Represents a Plutus data item in Cardano.
+message PlutusData {
+  oneof plutus_data {
+    Constr constr = 2; // Constructor.
+    PlutusDataMap map = 3; // Map of Plutus data.
+    BigInt big_int = 4; // Big integer.
+    bytes bounded_bytes = 5; // Bounded bytes.
+    PlutusDataArray array = 6; // Array of Plutus data.
+  }
+}
+
+// Represents a map of Plutus data in Cardano.
+message PlutusDataMap {
+  repeated PlutusDataPair pairs = 1; // List of key-value pairs.
+}
+
+// Represents an array of Plutus data in Cardano.
+message PlutusDataArray {
+  repeated PlutusData items = 1; // List of Plutus data items.
+}
+
+// Represents a script in Cardano.
+message Script {
+  oneof script {
+    NativeScript native = 1; // Native script.
+    bytes plutus_v1 = 2; // Plutus V1 script.
+    bytes plutus_v2 = 3; // Plutus V2 script.
+    bytes plutus_v3 = 4; // Plutus V3 script.
+  }
+}
+
 // Represents a rational number as a fraction.
 message RationalNumber {
   int32 numerator = 1;
@@ -73,3 +198,4 @@ message PParams {
   uint64 drep_deposit = 30; // The drep deposit.
   uint64 drep_inactivity_period = 31; // The drep inactivity period.
 }
+

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

@@ -15,6 +15,12 @@ message ChainPoint {
   uint64 timestamp = 4; // Block ms timestamp
 }
 
+// Represents a reference to a transaction output
+message TxoRef {
+  bytes hash = 1; // Tx hash.
+  uint32 index = 2; // Output index.
+}
+
 // Request to get the chain parameters
 message ReadParamsRequest {
   google.protobuf.FieldMask field_mask = 1; // Field mask to selectively return fields in the parsed response.
@@ -33,7 +39,29 @@ message ReadParamsResponse {
   ChainPoint ledger_tip = 2; // The chain point that represent the ledger current position.
 }
 
+// An evenlope that holds an UTxO from any of compatible chains
+message AnyUtxoData {
+  bytes native_bytes = 1; // Original bytes as defined by the chain
+  TxoRef txo_ref = 2; // Hash of the previous transaction.
+  oneof parsed_state {
+    utxorpc.v1alpha.cardano.TxOutput cardano = 3; // A cardano UTxO
+  }
+}
+
+// Request to get specific UTxOs
+message ReadUtxosRequest {
+  repeated TxoRef keys = 1; // List of keys UTxOs.
+  google.protobuf.FieldMask field_mask = 2; // Field mask to selectively return fields.
+}
+
+// Response containing the UTxOs associated with the requested addresses.
+message ReadUtxosResponse {
+  repeated AnyUtxoData items = 1; // List of UTxOs.
+  ChainPoint ledger_tip = 2; // The chain point that represent the ledger current position.
+}
+
 // Service definition for querying the state of the chain.
 service QueryService {
   rpc ReadParams(ReadParamsRequest) returns (ReadParamsResponse); // Get overall chain state.
+  rpc ReadUtxos(ReadUtxosRequest) returns (ReadUtxosResponse); // Read specific UTxOs by reference.
 }