New Event Subscription API (#442)

* Add reworked event types

* first pass implementing event subscriptions

* make clear that some methods are private

* comment tidy

* use Events in transaction stuff

* align transaction and event APIs

* remove __private_ prefixes; they are ugly

* fix examples and remove old events and subscription code

* better comments on hidden event functions

* re-add find_first_event; it's used a bunch in tests and examples

* cargo check --all-targets now passes

* Fix up existing event tests

* cargo fmt

* change todo to note

* clippy and doc niggles

* revert to find_first_event

* Add specific subscription related tests

* cargo fmt

* Update tests and add/fix examples

* cargo fmt

* add a little to subscribe_all_events example

* cargo fmt

* move an example comment

* easy access to root mod for more clarity

* add a couple of tests to ensure that events properly decoded until naff bytes

* Simplify EventSubscription Stream impl a little

* Address some PR feedback

subxt/tests/integration/events.rs

@@ -0,0 +1,139 @@
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
+// This file is part of subxt.
+//
+// subxt is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// subxt is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with subxt.  If not, see <http://www.gnu.org/licenses/>.
+
+use crate::{
+    node_runtime::{
+        balances,
+        system,
+    },
+    pair_signer,
+    test_context,
+};
+use futures::StreamExt;
+use sp_keyring::AccountKeyring;
+use subxt::Signer;
+
+// Check that we can subscribe to non-finalized block events.
+#[async_std::test]
+async fn non_finalized_block_subscription() -> Result<(), subxt::BasicError> {
+    env_logger::try_init().ok();
+    let ctx = test_context().await;
+
+    let mut event_sub = ctx.api.events().subscribe().await?;
+
+    // Wait for the next set of events, and check that the
+    // associated block hash is not finalized yet.
+    let events = event_sub.next().await.unwrap()?;
+    let event_block_hash = events.block_hash();
+    let finalized_hash = ctx.api.client.rpc().finalized_head().await?;
+
+    assert_ne!(event_block_hash, finalized_hash);
+    Ok(())
+}
+
+// Check that we can subscribe to finalized block events.
+#[async_std::test]
+async fn finalized_block_subscription() -> Result<(), subxt::BasicError> {
+    env_logger::try_init().ok();
+    let ctx = test_context().await;
+
+    let mut event_sub = ctx.api.events().subscribe_finalized().await?;
+
+    // Wait for the next set of events, and check that the
+    // associated block hash is the one we just finalized.
+    // (this can be a bit slow as we have to wait for finalization)
+    let events = event_sub.next().await.unwrap()?;
+    let event_block_hash = events.block_hash();
+    let finalized_hash = ctx.api.client.rpc().finalized_head().await?;
+
+    assert_eq!(event_block_hash, finalized_hash);
+    Ok(())
+}
+
+// Check that our subscription actually keeps producing events for
+// a few blocks.
+#[async_std::test]
+async fn subscription_produces_events_each_block() -> Result<(), subxt::BasicError> {
+    env_logger::try_init().ok();
+    let ctx = test_context().await;
+
+    let mut event_sub = ctx.api.events().subscribe().await?;
+
+    for i in 0..3 {
+        let events = event_sub
+            .next()
+            .await
+            .expect("events expected each block")?;
+        let success_event = events
+            .find_first_event::<system::events::ExtrinsicSuccess>()
+            .expect("decode error");
+        // Every now and then I get no bytes back for the first block events;
+        // I assume that this might be the case for the genesis block, so don't
+        // worry if no event found (but we should have no decode errors etc either way).
+        if i > 0 && success_event.is_none() {
+            let n = events.len();
+            panic!("Expected an extrinsic success event on iteration {i} (saw {n} other events)")
+        }
+    }
+
+    Ok(())
+}
+
+// Check that our subscription receives events, and we can filter them based on
+// it's Stream impl, and ultimately see the event we expect.
+#[async_std::test]
+async fn balance_transfer_subscription() -> Result<(), subxt::BasicError> {
+    env_logger::try_init().ok();
+    let ctx = test_context().await;
+
+    // Subscribe to balance transfer events, ignoring all else.
+    let event_sub = ctx.api.events().subscribe().await?.filter_map(|events| {
+        async move {
+            let events = events.ok()?;
+            events
+                .find_first_event::<balances::events::Transfer>()
+                .ok()?
+        }
+    });
+
+    // Calling `.next()` on the above borrows it, and the `filter_map`
+    // means it's no longer `Unpin`, so we pin it on the stack:
+    futures::pin_mut!(event_sub);
+
+    // Make a transfer:
+    let alice = pair_signer(AccountKeyring::Alice.pair());
+    let bob = AccountKeyring::Bob.to_account_id();
+    ctx.api
+        .tx()
+        .balances()
+        .transfer(bob.clone().into(), 10_000)
+        .sign_and_submit_then_watch(&alice)
+        .await?;
+
+    // Wait for the next balance transfer event in our subscription stream
+    // and check that it lines up:
+    let event = event_sub.next().await.unwrap();
+    assert_eq!(
+        event,
+        balances::events::Transfer {
+            from: alice.account_id().clone(),
+            to: bob.clone(),
+            amount: 10_000
+        }
+    );
+
+    Ok(())
+}

subxt/tests/integration/frame/balances.rs

@@ -31,9 +31,7 @@ use sp_core::{
 };
 use sp_keyring::AccountKeyring;
 use subxt::{
-    DefaultConfig,
     Error,
-    EventSubscription,
     Signer,
 };
 
@@ -189,38 +187,6 @@ async fn transfer_error() {
     }
 }
 
-#[async_std::test]
-async fn transfer_subscription() {
-    env_logger::try_init().ok();
-    let alice = pair_signer(AccountKeyring::Alice.pair());
-    let bob = AccountKeyring::Bob.to_account_id();
-    let bob_addr = bob.clone().into();
-    let cxt = test_context().await;
-    let sub = cxt.client().rpc().subscribe_events().await.unwrap();
-    let decoder = cxt.client().events_decoder();
-    let mut sub = EventSubscription::<DefaultConfig>::new(sub, decoder);
-    sub.filter_event::<balances::events::Transfer>();
-
-    cxt.api
-        .tx()
-        .balances()
-        .transfer(bob_addr, 10_000)
-        .sign_and_submit_then_watch(&alice)
-        .await
-        .unwrap();
-
-    let raw = sub.next().await.unwrap().unwrap();
-    let event = balances::events::Transfer::decode(&mut &raw.data[..]).unwrap();
-    assert_eq!(
-        event,
-        balances::events::Transfer {
-            from: alice.account_id().clone(),
-            to: bob.clone(),
-            amount: 10_000
-        }
-    );
-}
-
 #[async_std::test]
 async fn transfer_implicit_subscription() {
     env_logger::try_init().ok();

subxt/tests/integration/frame/contracts.rs

@@ -18,6 +18,7 @@ use sp_keyring::AccountKeyring;
 
 use crate::{
     node_runtime::{
+        self,
         contracts::{
             calls::TransactionApi,
             events,
@@ -150,8 +151,10 @@ impl ContractsTestContext {
         &self,
         contract: AccountId,
         input_data: Vec<u8>,
-    ) -> Result<TransactionProgress<'_, DefaultConfig, DispatchError>, Error<DispatchError>>
-    {
+    ) -> Result<
+        TransactionProgress<'_, DefaultConfig, DispatchError, node_runtime::Event>,
+        Error<DispatchError>,
+    > {
         log::info!("call: {:?}", contract);
         let result = self
             .contracts_tx()

subxt/tests/integration/frame/staking.rs

@@ -180,7 +180,7 @@ async fn chill_works_for_controller_only() -> Result<(), Error<DispatchError>> {
         .await?
         .wait_for_finalized_success()
         .await?
-        .has_event::<staking::events::Chilled>()?;
+        .has::<staking::events::Chilled>()?;
     assert!(is_chilled);
 
     Ok(())

subxt/tests/integration/frame/sudo.rs

@@ -48,7 +48,7 @@ async fn test_sudo() -> Result<(), subxt::Error<DispatchError>> {
         .await?
         .wait_for_finalized_success()
         .await?
-        .has_event::<sudo::events::Sudid>()?;
+        .has::<sudo::events::Sudid>()?;
 
     assert!(found_event);
     Ok(())
@@ -74,7 +74,7 @@ async fn test_sudo_unchecked_weight() -> Result<(), subxt::Error<DispatchError>>
         .await?
         .wait_for_finalized_success()
         .await?
-        .has_event::<sudo::events::Sudid>()?;
+        .has::<sudo::events::Sudid>()?;
 
     assert!(found_event);
     Ok(())

subxt/tests/integration/frame/system.rs

@@ -56,7 +56,7 @@ async fn tx_remark_with_event() -> Result<(), subxt::Error<DispatchError>> {
         .await?
         .wait_for_finalized_success()
         .await?
-        .has_event::<system::events::Remarked>()?;
+        .has::<system::events::Remarked>()?;
 
     assert!(found_event);
     Ok(())

subxt/tests/integration/main.rs

@@ -20,7 +20,9 @@ mod utils;
 #[cfg(test)]
 mod client;
 #[cfg(test)]
+mod events;
+#[cfg(test)]
 mod frame;
 
-pub use test_runtime::node_runtime;
-pub use utils::*;
+use test_runtime::node_runtime;
+use utils::*;

subxt/tests/integration/utils/context.rs

@@ -14,7 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with subxt.  If not, see <http://www.gnu.org/licenses/>.
 
-pub use crate::{
+pub(crate) use crate::{
     node_runtime,
     TestNodeProcess,
 };