feat: add hermes client (#2931)

Author: keyvankhademi

.github/workflows/ci-hermes-client-rust.yml

@@ -0,0 +1,35 @@
+name: "Hermes Client Rust Test Suite"
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    paths:
+      - .github/workflows/ci-hermes-client-rust.yml
+      - apps/hermes/client/rust/**
+
+jobs:
+  lazer-rust-test-suite:
+    name: Hermes Client Rust Test Suite
+    runs-on: ubuntu-22.04
+    defaults:
+      run:
+        working-directory: apps/hermes/client/rust/
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - uses: actions-rust-lang/setup-rust-toolchain@v1
+      - name: install taplo
+        run: cargo install --locked [email protected]
+      - name: check Cargo.toml formatting
+        run: find . -name Cargo.toml -exec taplo fmt --check --diff {} \;
+      - name: Format check
+        run: cargo fmt --all -- --check
+        if: success() || failure()
+      - name: Clippy check
+        run: cargo clippy -p pyth-hermes-client --all-targets -- --deny warnings
+        if: success() || failure()
+      - name: test
+        run: cargo test -p pyth-hermes-client
+        if: success() || failure()

.github/workflows/publish-rust-hermes-client.yml

@@ -0,0 +1,18 @@
+name: Publish Rust package pyth-lazer-client to crates.io
+
+on:
+  push:
+    tags:
+      - rust-pyth-hermes-client-v*
+jobs:
+  publish-pyth-hermes-client:
+    name: Publish Rust package pyth-hermes-client to crates.io
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v2
+
+      - run: cargo publish --token ${CARGO_REGISTRY_TOKEN}
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+        working-directory: "apps/hermes/client/rust"

Cargo.lock

@@ -6,6 +6,7 @@ members = [
     "apps/fortuna",
     "apps/pyth-lazer-agent",
     "apps/quorum",
+    "apps/hermes/client/rust",
     "lazer/publisher_sdk/rust",
     "lazer/sdk/rust/client",
     "lazer/sdk/rust/protocol",

Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "pyth-hermes-client"
+version = "0.0.1"
+edition = "2021"
+description = "A Rust client for Pyth Hermes"
+license = "Apache-2.0"
+
+[dependencies]
+pyth-sdk = { version = "0.8.0" }
+tokio = { version = "1", features = ["full"] }
+tokio-tungstenite = { version = "0.20", features = ["native-tls"] }
+futures-util = "0.3"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+anyhow = "1.0"
+tracing = "0.1"
+url = "2.4"
+derive_more = { version = "1.0.0", features = ["from"] }
+backoff = { version = "0.4.0", features = ["futures", "tokio"] }
+ttl_cache = "0.5.1"
+
+
+[dev-dependencies]
+bincode = "1.3.3"
+ed25519-dalek = { version = "2.1.1", features = ["rand_core"] }
+hex = "0.4.3"
+libsecp256k1 = "0.7.1"
+bs58 = "0.5.1"
+alloy-primitives = "0.8.19"
+tracing-subscriber = { version = "0.3.19", features = ["env-filter", "json"] }

apps/hermes/client/rust/Cargo.toml

@@ -0,0 +1,78 @@
+use std::time::Duration;
+
+use pyth_hermes_client::{
+    backoff::HermesExponentialBackoffBuilder,
+    client::HermesClientBuilder,
+    ws_connection::{HermesClientMessageSubscribe, HermesClientMessageUnsubscribe},
+};
+use tokio::pin;
+use tracing::level_filters::LevelFilter;
+use tracing_subscriber::EnvFilter;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            EnvFilter::builder()
+                .with_default_directive(LevelFilter::INFO.into())
+                .from_env()?,
+        )
+        .json()
+        .init();
+
+    // Create and start the client
+    let mut client = HermesClientBuilder::default()
+        // Optionally override the default endpoints
+        .with_endpoints(vec!["wss://hermes.pyth.network/ws".parse()?])
+        // Optionally set the number of connections
+        .with_num_connections(4)
+        // Optionally set the backoff strategy
+        .with_backoff(HermesExponentialBackoffBuilder::default().build())
+        // Optionally set the timeout for each connection
+        .with_timeout(Duration::from_secs(5))
+        // Optionally set the channel capacity for responses
+        .with_channel_capacity(1000)
+        .build()?;
+
+    let stream = client.start().await?;
+    pin!(stream);
+
+    let subscribe_request = HermesClientMessageSubscribe {
+        ids: vec!["2b89b9dc8fdf9f34709a5b106b472f0f39bb6ca9ce04b0fd7f2e971688e2e53b".to_string()],
+        verbose: true,
+        binary: true,
+        allow_out_of_order: false,
+        ignore_invalid_price_ids: false,
+    };
+
+    client.subscribe(subscribe_request).await?;
+
+    println!("Subscribed to price feeds. Waiting for updates...");
+
+    // Process the first few updates
+    let mut count = 0;
+    while let Some(msg) = stream.recv().await {
+        // The stream gives us base64-encoded binary messages. We need to decode, parse, and verify them.
+
+        println!("Received message: {msg:#?}");
+        println!();
+
+        count += 1;
+        if count >= 50 {
+            break;
+        }
+    }
+
+    // Unsubscribe example
+
+    client
+        .unsubscribe(HermesClientMessageUnsubscribe {
+            ids: vec![
+                "2b89b9dc8fdf9f34709a5b106b472f0f39bb6ca9ce04b0fd7f2e971688e2e53b".to_string(),
+            ],
+        })
+        .await?;
+    println!("Unsubscribed from price feeds.");
+
+    Ok(())
+}

apps/hermes/client/rust/examples/subscribe_price_feeds.rs

@@ -0,0 +1,118 @@
+//! Exponential backoff implementation for Pyth Lazer client.
+//!
+//! This module provides a wrapper around the [`backoff`] crate's exponential backoff functionality,
+//! offering a simplified interface tailored for Pyth Lazer client operations.
+
+use std::time::Duration;
+
+use backoff::{
+    default::{INITIAL_INTERVAL_MILLIS, MAX_INTERVAL_MILLIS, MULTIPLIER, RANDOMIZATION_FACTOR},
+    ExponentialBackoff, ExponentialBackoffBuilder,
+};
+
+/// A wrapper around the backoff crate's exponential backoff configuration.
+///
+/// This struct encapsulates the parameters needed to configure exponential backoff
+/// behavior and can be converted into the backoff crate's [`ExponentialBackoff`] type.
+#[derive(Debug)]
+pub struct HermesExponentialBackoff {
+    /// The initial retry interval.
+    initial_interval: Duration,
+    /// The randomization factor to use for creating a range around the retry interval.
+    ///
+    /// A randomization factor of 0.5 results in a random period ranging between 50% below and 50%
+    /// above the retry interval.
+    randomization_factor: f64,
+    /// The value to multiply the current interval with for each retry attempt.
+    multiplier: f64,
+    /// The maximum value of the back off period. Once the retry interval reaches this
+    /// value it stops increasing.
+    max_interval: Duration,
+}
+
+impl From<HermesExponentialBackoff> for ExponentialBackoff {
+    fn from(val: HermesExponentialBackoff) -> Self {
+        ExponentialBackoffBuilder::default()
+            .with_initial_interval(val.initial_interval)
+            .with_randomization_factor(val.randomization_factor)
+            .with_multiplier(val.multiplier)
+            .with_max_interval(val.max_interval)
+            .with_max_elapsed_time(None)
+            .build()
+    }
+}
+
+/// Builder for [`PythLazerExponentialBackoff`].
+///
+/// Provides a fluent interface for configuring exponential backoff parameters
+/// with sensible defaults from the backoff crate.
+#[derive(Debug)]
+pub struct HermesExponentialBackoffBuilder {
+    initial_interval: Duration,
+    randomization_factor: f64,
+    multiplier: f64,
+    max_interval: Duration,
+}
+
+impl Default for HermesExponentialBackoffBuilder {
+    fn default() -> Self {
+        Self {
+            initial_interval: Duration::from_millis(INITIAL_INTERVAL_MILLIS),
+            randomization_factor: RANDOMIZATION_FACTOR,
+            multiplier: MULTIPLIER,
+            max_interval: Duration::from_millis(MAX_INTERVAL_MILLIS),
+        }
+    }
+}
+
+impl HermesExponentialBackoffBuilder {
+    /// Creates a new builder with default values.
+    pub fn new() -> Self {
+        Default::default()
+    }
+
+    /// Sets the initial retry interval.
+    ///
+    /// This is the starting interval for the first retry attempt.
+    pub fn with_initial_interval(&mut self, initial_interval: Duration) -> &mut Self {
+        self.initial_interval = initial_interval;
+        self
+    }
+
+    /// Sets the randomization factor to use for creating a range around the retry interval.
+    ///
+    /// A randomization factor of 0.5 results in a random period ranging between 50% below and 50%
+    /// above the retry interval. This helps avoid the "thundering herd" problem when multiple
+    /// clients retry at the same time.
+    pub fn with_randomization_factor(&mut self, randomization_factor: f64) -> &mut Self {
+        self.randomization_factor = randomization_factor;
+        self
+    }
+
+    /// Sets the value to multiply the current interval with for each retry attempt.
+    ///
+    /// A multiplier of 2.0 means each retry interval will be double the previous one.
+    pub fn with_multiplier(&mut self, multiplier: f64) -> &mut Self {
+        self.multiplier = multiplier;
+        self
+    }
+
+    /// Sets the maximum value of the back off period.
+    ///
+    /// Once the retry interval reaches this value it stops increasing, providing
+    /// an upper bound on the wait time between retries.
+    pub fn with_max_interval(&mut self, max_interval: Duration) -> &mut Self {
+        self.max_interval = max_interval;
+        self
+    }
+
+    /// Builds the [`PythLazerExponentialBackoff`] configuration.
+    pub fn build(&self) -> HermesExponentialBackoff {
+        HermesExponentialBackoff {
+            initial_interval: self.initial_interval,
+            randomization_factor: self.randomization_factor,
+            multiplier: self.multiplier,
+            max_interval: self.max_interval,
+        }
+    }
+}