rpc/events: Add subscription events from the chainHead methods

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

subxt/src/rpc/mod.rs

@@ -59,6 +59,8 @@ mod rpc;
 mod rpc_client;
 mod rpc_client_t;
 
+pub mod subscription_events;
+
 // Expose the `Rpc` struct and any associated types.
 pub use rpc::*;
 

subxt/src/rpc/subscription_events.rs

@@ -0,0 +1,127 @@
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
+// This file is dual-licensed as Apache-2.0 or GPL-3.0.
+// see LICENSE for license details.
+
+//! Events generated as a result of the subscription methods.
+
+use crate::rpc::RuntimeVersion;
+use serde::Deserialize;
+
+/// The operation could not be processed due to an error.
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ErrorEvent {
+    /// Reason of the error.
+    pub error: String,
+}
+
+/// The runtime specification of the current block.
+///
+/// This event is generated for:
+///   - the first announced block by the follow subscription
+///   - blocks that suffered a change in runtime compared with their parents
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RuntimeVersionEvent {
+    /// The runtime version.
+    pub spec: RuntimeVersion,
+}
+
+/// The runtime event generated if the `follow` subscription
+/// has set the `runtime_updates` flag.
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+#[serde(tag = "type")]
+pub enum RuntimeEvent {
+    /// The runtime version of this block.
+    Valid(RuntimeVersionEvent),
+    /// The runtime could not be obtained due to an error.
+    Invalid(ErrorEvent),
+}
+
+/// Contain information about the latest finalized block.
+///
+/// # Note
+///
+/// This is the first event generated by the `follow` subscription
+/// and is submitted only once.
+///
+/// If the `runtime_updates` flag is set, then this event contains
+/// the `RuntimeEvent`, otherwise the `RuntimeEvent` is not present.
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Initialized<Hash> {
+    /// The hash of the latest finalized block.
+    pub finalized_block_hash: Hash,
+    /// The runtime version of the finalized block.
+    ///
+    /// # Note
+    ///
+    /// This is present only if the `runtime_updates` flag is set for
+    /// the `follow` subscription.
+    pub finalized_block_runtime: Option<RuntimeEvent>,
+}
+
+/// Indicate a new non-finalized block.
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct NewBlock<Hash> {
+    /// The hash of the new block.
+    pub block_hash: Hash,
+    /// The parent hash of the new block.
+    pub parent_block_hash: Hash,
+    /// The runtime version of the new block.
+    ///
+    /// # Note
+    ///
+    /// This is present only if the `runtime_updates` flag is set for
+    /// the `follow` subscription.
+    pub new_runtime: Option<RuntimeEvent>,
+}
+
+/// Indicate the block hash of the new best block.
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct BestBlockChanged<Hash> {
+    /// The block hash of the new best block.
+    pub best_block_hash: Hash,
+}
+
+/// Indicate the finalized and pruned block hashes.
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Finalized<Hash> {
+    /// Block hashes that are finalized.
+    pub finalized_block_hashes: Vec<Hash>,
+    /// Block hashes that are pruned (removed).
+    pub pruned_block_hashes: Vec<Hash>,
+}
+
+/// The event generated by the `chainHead_follow` method.
+///
+/// The events are generated in the following order:
+/// 1. Initialized - generated only once to signal the
+///      latest finalized block
+/// 2. NewBlock - a new block was added.
+/// 3. BestBlockChanged - indicate that the best block
+///      is now the one from this event. The block was
+///      announced priorly with the `NewBlock` event.
+/// 4. Finalized - State the finalized and pruned blocks.
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+#[serde(tag = "event")]
+pub enum FollowEvent<Hash> {
+    /// The latest finalized block.
+    ///
+    /// This event is generated only once.
+    Initialized(Initialized<Hash>),
+    /// A new non-finalized block was added.
+    NewBlock(NewBlock<Hash>),
+    /// The best block of the chain.
+    BestBlockChanged(BestBlockChanged<Hash>),
+    /// A list of finalized and pruned blocks.
+    Finalized(Finalized<Hash>),
+    /// The subscription is dropped and no further events
+    /// will be generated.
+    Stop,
+}