erpc-sdk 0.11.0

Async multi-network Rust SDK for ERPC
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
use std::pin::Pin;

use futures_util::{Stream, StreamExt};
use percent_encoding::{NON_ALPHANUMERIC, utf8_percent_encode};
use serde::{Deserialize, Serialize};
use tokio_util::sync::CancellationToken;

use crate::{ErpcError, Result, rest::RestTransport, rpc::decode_json};

/// Binary encoding requested from the price API.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum PriceEncoding {
    /// Base64 text.
    Base64,
    /// Hexadecimal text.
    Hex,
}

impl PriceEncoding {
    const fn as_str(self) -> &'static str {
        match self {
            Self::Base64 => "base64",
            Self::Hex => "hex",
        }
    }
}

/// Asset category used to filter feed metadata.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum PriceAssetType {
    /// Crypto asset.
    Crypto,
    /// Equity.
    Equity,
    /// Foreign-exchange pair.
    Fx,
    /// Metal.
    Metal,
    /// Rates instrument.
    Rates,
}

impl PriceAssetType {
    const fn as_str(self) -> &'static str {
        match self {
            Self::Crypto => "crypto",
            Self::Equity => "equity",
            Self::Fx => "fx",
            Self::Metal => "metal",
            Self::Rates => "rates",
        }
    }
}

/// Price feed identifier and optional attributes.
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
pub struct PriceFeedMetadata {
    /// Optional feed attributes.
    pub attributes: Option<std::collections::HashMap<String, String>>,
    /// Feed identifier.
    pub id: String,
}

/// One published price point.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub struct PricePoint {
    /// Confidence interval as an integer string.
    pub conf: String,
    /// Decimal exponent.
    pub expo: i32,
    /// Price as an integer string.
    pub price: String,
    /// Unix publication time.
    pub publish_time: i64,
}

/// Optional timing and slot metadata.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub struct ParsedPriceMetadata {
    /// Previous publication time.
    pub prev_publish_time: Option<i64>,
    /// Proof availability time.
    pub proof_available_time: Option<i64>,
    /// Source slot.
    pub slot: Option<u64>,
}

/// Parsed update for one feed.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub struct ParsedPriceUpdate {
    /// Exponentially weighted moving-average price.
    pub ema_price: PricePoint,
    /// Feed identifier.
    pub id: String,
    /// Optional update metadata.
    pub metadata: Option<ParsedPriceMetadata>,
    /// Spot price.
    pub price: PricePoint,
}

/// Binary price update payload.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub struct BinaryUpdate {
    /// Encoded update values.
    pub data: Vec<String>,
    /// Encoding returned by the service.
    pub encoding: String,
}

/// Latest or historical price updates.
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
pub struct PriceUpdateResponse {
    /// Binary updates.
    pub binary: BinaryUpdate,
    /// Parsed updates when requested.
    pub parsed: Option<Vec<ParsedPriceUpdate>>,
}

/// Options shared by latest, historical, and streaming price updates.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct PriceUpdateOptions {
    /// Requested binary encoding.
    pub encoding: Option<PriceEncoding>,
    /// Feed identifiers. Repeated `ids[]` query keys are preserved.
    pub ids: Vec<String>,
    /// Ignore unrecognized feed identifiers.
    pub ignore_invalid_price_ids: Option<bool>,
    /// Include parsed values.
    pub parsed: Option<bool>,
}

/// Options for the server-sent-events price stream.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct PriceStreamOptions {
    /// Shared update options.
    pub update: PriceUpdateOptions,
    /// Allow messages to arrive out of order.
    pub allow_unordered: Option<bool>,
    /// Return benchmark feeds only.
    pub benchmarks_only: Option<bool>,
}

/// One publisher and its stake cap.
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
pub struct PublisherStakeCap {
    /// Stake cap.
    pub cap: f64,
    /// Publisher identifier.
    pub publisher: String,
}

/// Parsed publisher stake cap envelope.
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
pub struct ParsedPublisherStakeCaps {
    /// Publisher stake caps.
    pub publisher_stake_caps: Vec<PublisherStakeCap>,
}

/// Latest publisher stake caps.
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
pub struct PublisherStakeCapsResponse {
    /// Binary response.
    pub binary: BinaryUpdate,
    /// Parsed response when requested.
    pub parsed: Option<Vec<ParsedPublisherStakeCaps>>,
}

/// Parsed server-sent event from the price stream.
#[derive(Clone, Debug, PartialEq)]
pub struct PriceStreamEvent {
    /// Price update carried by `data` lines.
    pub data: PriceUpdateResponse,
    /// Optional SSE event name.
    pub event: Option<String>,
    /// Optional SSE event identifier.
    pub id: Option<String>,
}

/// Boxed asynchronous stream returned by [`PriceClient::stream_price_updates`].
pub type PriceStream = Pin<Box<dyn Stream<Item = Result<PriceStreamEvent>> + Send>>;

/// Price metadata, updates, publisher caps, and streaming API.
#[derive(Clone)]
pub struct PriceClient {
    transport: RestTransport,
}

impl PriceClient {
    pub(crate) const fn new(transport: RestTransport) -> Self {
        Self { transport }
    }

    /// Searches price feed metadata.
    pub async fn get_price_feeds(
        &self,
        query_text: Option<&str>,
        asset_type: Option<PriceAssetType>,
    ) -> Result<Vec<PriceFeedMetadata>> {
        self.get_price_feeds_with(query_text, asset_type, None)
            .await
    }

    /// Searches price feed metadata with cancellation.
    pub async fn get_price_feeds_with(
        &self,
        query_text: Option<&str>,
        asset_type: Option<PriceAssetType>,
        cancellation: Option<&CancellationToken>,
    ) -> Result<Vec<PriceFeedMetadata>> {
        let mut query = Vec::new();
        if let Some(value) = query_text {
            query.push(("query".to_owned(), value.to_owned()));
        }
        if let Some(value) = asset_type {
            query.push(("asset_type".to_owned(), value.as_str().to_owned()));
        }
        self.transport
            .get("/v2/price_feeds", query, cancellation)
            .await
    }

    /// Gets latest price updates.
    pub async fn get_latest_price_updates(
        &self,
        options: &PriceUpdateOptions,
    ) -> Result<PriceUpdateResponse> {
        self.get_latest_price_updates_with(options, None).await
    }

    /// Gets latest price updates with cancellation.
    pub async fn get_latest_price_updates_with(
        &self,
        options: &PriceUpdateOptions,
        cancellation: Option<&CancellationToken>,
    ) -> Result<PriceUpdateResponse> {
        self.transport
            .get(
                "/v2/updates/price/latest",
                update_query(options),
                cancellation,
            )
            .await
    }

    /// Gets price updates at a Unix publication time.
    pub async fn get_price_updates_at_timestamp(
        &self,
        publish_time: impl std::fmt::Display,
        options: &PriceUpdateOptions,
    ) -> Result<PriceUpdateResponse> {
        self.get_price_updates_at_timestamp_with(publish_time, options, None)
            .await
    }

    /// Gets price updates at a Unix publication time with cancellation.
    pub async fn get_price_updates_at_timestamp_with(
        &self,
        publish_time: impl std::fmt::Display,
        options: &PriceUpdateOptions,
        cancellation: Option<&CancellationToken>,
    ) -> Result<PriceUpdateResponse> {
        let publish_time = publish_time.to_string();
        let segment = utf8_percent_encode(&publish_time, NON_ALPHANUMERIC);
        let path = format!("/v2/updates/price/{segment}");
        self.transport
            .get(&path, update_query(options), cancellation)
            .await
    }

    /// Gets latest publisher stake caps.
    pub async fn get_latest_publisher_stake_caps(
        &self,
        encoding: Option<PriceEncoding>,
        parsed: Option<bool>,
    ) -> Result<PublisherStakeCapsResponse> {
        self.get_latest_publisher_stake_caps_with(encoding, parsed, None)
            .await
    }

    /// Gets latest publisher stake caps with cancellation.
    pub async fn get_latest_publisher_stake_caps_with(
        &self,
        encoding: Option<PriceEncoding>,
        parsed: Option<bool>,
        cancellation: Option<&CancellationToken>,
    ) -> Result<PublisherStakeCapsResponse> {
        let mut query = Vec::new();
        if let Some(value) = encoding {
            query.push(("encoding".to_owned(), value.as_str().to_owned()));
        }
        if let Some(value) = parsed {
            query.push(("parsed".to_owned(), value.to_string()));
        }
        self.transport
            .get(
                "/v2/updates/publisher_stake_caps/latest",
                query,
                cancellation,
            )
            .await
    }

    /// Connects to the price server-sent-events stream.
    pub async fn stream_price_updates(
        &self,
        options: &PriceStreamOptions,
        cancellation: Option<CancellationToken>,
    ) -> Result<PriceStream> {
        let mut query = update_query(&options.update);
        if let Some(value) = options.allow_unordered {
            query.push(("allow_unordered".to_owned(), value.to_string()));
        }
        if let Some(value) = options.benchmarks_only {
            query.push(("benchmarks_only".to_owned(), value.to_string()));
        }
        let response = self
            .transport
            .get_response("/v2/updates/price/stream", query, cancellation.as_ref())
            .await?;
        let mut bytes = response.bytes_stream();
        let output = async_stream::stream! {
            let mut buffer = String::new();
            loop {
                let next = if let Some(token) = &cancellation {
                    tokio::select! {
                        () = token.cancelled() => {
                            yield Err(ErpcError::Aborted);
                            break;
                        }
                        next = bytes.next() => next,
                    }
                } else {
                    bytes.next().await
                };
                let Some(chunk) = next else { break };
                if let Ok(chunk) = chunk {
                    buffer.push_str(&String::from_utf8_lossy(&chunk));
                } else {
                    yield Err(ErpcError::Transport("Unable to read ERPC stream".to_owned()));
                    break;
                }
                while let Some((boundary, separator_length)) = sse_boundary(&buffer) {
                    let block = buffer[..boundary].to_owned();
                    buffer.drain(..boundary + separator_length);
                    match parse_sse_block(&block) {
                        Ok(Some(event)) => yield Ok(event),
                        Ok(None) => {}
                        Err(error) => {
                            yield Err(error);
                            return;
                        }
                    }
                }
            }
            if !buffer.is_empty() {
                match parse_sse_block(&buffer) {
                    Ok(Some(event)) => yield Ok(event),
                    Ok(None) => {}
                    Err(error) => yield Err(error),
                }
            }
        };
        Ok(Box::pin(output))
    }
}

fn update_query(options: &PriceUpdateOptions) -> Vec<(String, String)> {
    let mut query: Vec<_> = options
        .ids
        .iter()
        .map(|id| ("ids[]".to_owned(), id.clone()))
        .collect();
    if let Some(value) = options.encoding {
        query.push(("encoding".to_owned(), value.as_str().to_owned()));
    }
    if let Some(value) = options.parsed {
        query.push(("parsed".to_owned(), value.to_string()));
    }
    if let Some(value) = options.ignore_invalid_price_ids {
        query.push(("ignore_invalid_price_ids".to_owned(), value.to_string()));
    }
    query
}

fn sse_boundary(buffer: &str) -> Option<(usize, usize)> {
    match (buffer.find("\n\n"), buffer.find("\r\n\r\n")) {
        (Some(left), Some(right)) if left <= right => Some((left, 2)),
        (Some(_) | None, Some(right)) => Some((right, 4)),
        (Some(left), None) => Some((left, 2)),
        (None, None) => None,
    }
}

fn parse_sse_block(block: &str) -> Result<Option<PriceStreamEvent>> {
    let mut data = Vec::new();
    let mut event = None;
    let mut id = None;
    for line in block.lines() {
        if line.is_empty() || line.starts_with(':') {
            continue;
        }
        let (field, raw) = line.split_once(':').unwrap_or((line, ""));
        let value = raw.strip_prefix(' ').unwrap_or(raw);
        match field {
            "data" => data.push(value),
            "event" => event = Some(value.to_owned()),
            "id" => id = Some(value.to_owned()),
            _ => {}
        }
    }
    if data.is_empty() {
        return Ok(None);
    }
    let response = decode_json(&data.join("\n")).map_err(|_| {
        ErpcError::InvalidResponse("ERPC returned malformed stream data".to_owned())
    })?;
    Ok(Some(PriceStreamEvent {
        data: response,
        event,
        id,
    }))
}