ogmios_client/
query_ledger_state.rs

1//! Queries that start with `queryLedgerState/`.
2
3use crate::{
4	ByNameParamsBuilder, OgmiosClient, OgmiosClientError, OgmiosParams,
5	types::{OgmiosBytesSize, OgmiosUtxo, OgmiosValue, SlotLength, TimeSeconds},
6};
7use serde::Deserialize;
8
9/// Trait that defines the methods for querying the Cardano ledger state.
10pub trait QueryLedgerState {
11	#[allow(async_fn_in_trait)]
12	/// Returns the slot number of the most recent block in the blockchain.
13	async fn get_tip(&self) -> Result<OgmiosTip, OgmiosClientError>;
14
15	#[allow(async_fn_in_trait)]
16	/// Returns a list of era summaries.
17	async fn era_summaries(&self) -> Result<Vec<EraSummary>, OgmiosClientError>;
18
19	#[allow(async_fn_in_trait)]
20	/// Parameters:
21	/// - `addresses`: bech32 address to query
22	async fn query_utxos(&self, addresses: &[String])
23	-> Result<Vec<OgmiosUtxo>, OgmiosClientError>;
24
25	#[allow(async_fn_in_trait)]
26	/// Returns the current protocol parameters.
27	async fn query_protocol_parameters(
28		&self,
29	) -> Result<ProtocolParametersResponse, OgmiosClientError>;
30}
31
32/// Trait that defines the methods for querying a single UTXO by transaction hash and output index.
33pub trait QueryUtxoByUtxoId {
34	#[allow(async_fn_in_trait)]
35	/// Query for a single UTXO by transaction hash and output index.
36	/// Warning: it does not return datum, datumHash, nor script fields.
37	/// Parameters:
38	/// - `tx`: query for output of this transaction
39	/// - `index`: query for output with this index
40	async fn query_utxo_by_id(
41		&self,
42		utxo: sidechain_domain::UtxoId,
43	) -> Result<Option<OgmiosUtxo>, OgmiosClientError>;
44}
45
46impl<T: OgmiosClient> QueryLedgerState for T {
47	async fn get_tip(&self) -> Result<OgmiosTip, OgmiosClientError> {
48		self.request("queryLedgerState/tip", OgmiosParams::empty_positional()).await
49	}
50
51	async fn era_summaries(&self) -> Result<Vec<EraSummary>, OgmiosClientError> {
52		self.request("queryLedgerState/eraSummaries", OgmiosParams::empty_positional())
53			.await
54	}
55
56	async fn query_utxos(
57		&self,
58		addresses: &[String],
59	) -> Result<Vec<OgmiosUtxo>, OgmiosClientError> {
60		let params = ByNameParamsBuilder::new().insert("addresses", addresses)?.build();
61		self.request("queryLedgerState/utxo", params).await
62	}
63
64	async fn query_protocol_parameters(
65		&self,
66	) -> Result<ProtocolParametersResponse, OgmiosClientError> {
67		self.request("queryLedgerState/protocolParameters", OgmiosParams::empty_by_name())
68			.await
69	}
70}
71
72impl<T: OgmiosClient> QueryUtxoByUtxoId for T {
73	async fn query_utxo_by_id(
74		&self,
75		utxo: sidechain_domain::UtxoId,
76	) -> Result<Option<OgmiosUtxo>, OgmiosClientError> {
77		let reference = serde_json::json!({
78			"transaction": {"id": hex::encode(utxo.tx_hash.0)},
79			"index": utxo.index.0,
80		});
81		let params =
82			ByNameParamsBuilder::new().insert("outputReferences", vec![reference])?.build();
83		// Expect at most one output, because it is a single output reference query.
84		let utxos: Vec<OgmiosUtxo> = self.request("queryLedgerState/utxo", params).await?;
85		Ok(utxos.first().cloned())
86	}
87}
88
89#[derive(Clone, Debug, Deserialize, Eq, PartialEq)]
90#[serde(rename_all = "camelCase")]
91/// Represents a summary of a known era.
92pub struct EraSummary {
93	/// The start boundary of the era.
94	pub start: EpochBoundary,
95	/// The end boundary of the era.
96	pub end: EpochBoundary,
97	/// The parameters of the era.
98	pub parameters: EpochParameters,
99}
100
101#[derive(Clone, Debug, Deserialize, Eq, PartialEq)]
102/// Represents the boundary of an epoch.
103pub struct EpochBoundary {
104	pub time: TimeSeconds,
105	pub slot: u64,
106	pub epoch: u32,
107}
108
109#[derive(Clone, Debug, Deserialize, Eq, PartialEq)]
110#[serde(rename_all = "camelCase")]
111/// Represents the parameters of an epoch.
112pub struct EpochParameters {
113	/// The length of the epoch in slots.
114	pub epoch_length: u32,
115	/// The length of a slot in milliseconds.
116	pub slot_length: SlotLength,
117	/// Number of slots from the tip of the ledger in which it is guaranteed that no hard fork can take place.
118	pub safe_zone: u32,
119}
120
121#[derive(Clone, Debug, Deserialize, PartialEq, Default)]
122#[serde(rename_all = "camelCase")]
123/// Represents the cost of reference scripts.
124pub struct ReferenceScriptsCosts {
125	/// The base cost of a reference script.
126	pub base: f64,
127}
128
129#[derive(Clone, Debug, Deserialize, PartialEq, Default)]
130#[serde(rename_all = "camelCase")]
131/// Represents the protocol parameters.
132pub struct ProtocolParametersResponse {
133	/// Additional transaction fee per byte of data (in lovelace). Also called minFeeA.
134	pub min_fee_coefficient: u32,
135	/// Base transaction fee (in lovelace). Also called minFeeB.
136	pub min_fee_constant: OgmiosValue,
137	/// Amount of lovelace required to register a stake pool.
138	pub stake_pool_deposit: OgmiosValue,
139	/// Amount of lovelace required to register a stake credential.
140	pub stake_credential_deposit: OgmiosValue,
141	/// Maximum size limit for the value field in transaction outputs.
142	pub max_value_size: OgmiosBytesSize,
143	/// Maximum size limit for the transaction body.
144	pub max_transaction_size: OgmiosBytesSize,
145	/// Additional transaction fee per byte of output data (in lovelace). Also called coinsPerUTxOWord or coinsPerUTxOByte
146	pub min_utxo_deposit_coefficient: u64,
147	/// Pricing for Plutus script execution resources.
148	pub script_execution_prices: ScriptExecutionPrices,
149	/// Cost models for different Plutus language versions.
150	pub plutus_cost_models: PlutusCostModels,
151	/// Maximum number of collateral inputs that can be included in a transaction.
152	pub max_collateral_inputs: u32,
153	/// Percentage of fee that is used as collateral for a failed transaction.
154	pub collateral_percentage: u32,
155	/// Cost of reference scripts.
156	pub min_fee_reference_scripts: ReferenceScriptsCosts,
157}
158
159#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Default)]
160/// Represents the pricing for Plutus script execution resources.
161pub struct ScriptExecutionPrices {
162	#[serde(deserialize_with = "crate::types::parse_fraction_ratio_u64")]
163	/// Fee per memory unit.
164	pub memory: fraction::Ratio<u64>,
165	#[serde(deserialize_with = "crate::types::parse_fraction_ratio_u64")]
166	/// Fee per CPU unit.
167	pub cpu: fraction::Ratio<u64>,
168}
169
170#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Default)]
171/// Represents the cost models for different Plutus language versions.
172pub struct PlutusCostModels {
173	#[serde(rename = "plutus:v1")]
174	/// Cost model for Plutus v1.
175	pub plutus_v1: Vec<i128>,
176	#[serde(rename = "plutus:v2")]
177	/// Cost model for Plutus v2.
178	pub plutus_v2: Vec<i128>,
179	#[serde(rename = "plutus:v3")]
180	/// Cost model for Plutus v3.
181	pub plutus_v3: Vec<i128>,
182}
183
184#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Default)]
185/// Represents the tip of the ledger.
186pub struct OgmiosTip {
187	/// The slot number of the most recent block in the blockchain.
188	pub slot: u64,
189}
ogmios_client/query_ledger_state.rs

ogmios_client/
query_ledger_state.rs
