Move Subxt crate into a subfolder (#424)

* move into subfolder step 1

* Make folders a workspace again

* Move examples into their own workspace crate to make them more visible and easier to run

* clippy fix

* newline

* tweak releasing steps for folder move

* reference exampels more clearly in top level readme

subxt/src/client.rs

@@ -0,0 +1,302 @@
+// 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 futures::future;
+use sp_runtime::traits::Hash;
+pub use sp_runtime::traits::SignedExtension;
+
+use crate::{
+    error::BasicError,
+    events::EventsDecoder,
+    extrinsic::{
+        self,
+        SignedExtra,
+        Signer,
+        UncheckedExtrinsic,
+    },
+    rpc::{
+        Rpc,
+        RpcClient,
+        RuntimeVersion,
+        SystemProperties,
+    },
+    storage::StorageClient,
+    transaction::TransactionProgress,
+    AccountData,
+    Call,
+    Config,
+    Metadata,
+};
+use codec::Decode;
+use derivative::Derivative;
+use std::sync::Arc;
+
+/// ClientBuilder for constructing a Client.
+#[derive(Default)]
+pub struct ClientBuilder {
+    url: Option<String>,
+    client: Option<RpcClient>,
+    page_size: Option<u32>,
+}
+
+impl ClientBuilder {
+    /// Creates a new ClientBuilder.
+    pub fn new() -> Self {
+        Self {
+            url: None,
+            client: None,
+            page_size: None,
+        }
+    }
+
+    /// Sets the jsonrpsee client.
+    pub fn set_client<C: Into<RpcClient>>(mut self, client: C) -> Self {
+        self.client = Some(client.into());
+        self
+    }
+
+    /// Set the substrate rpc address.
+    pub fn set_url<P: Into<String>>(mut self, url: P) -> Self {
+        self.url = Some(url.into());
+        self
+    }
+
+    /// Set the page size.
+    pub fn set_page_size(mut self, size: u32) -> Self {
+        self.page_size = Some(size);
+        self
+    }
+
+    /// Creates a new Client.
+    pub async fn build<T: Config>(self) -> Result<Client<T>, BasicError> {
+        let client = if let Some(client) = self.client {
+            client
+        } else {
+            let url = self.url.as_deref().unwrap_or("ws://127.0.0.1:9944");
+            RpcClient::try_from_url(url).await?
+        };
+        let rpc = Rpc::new(client);
+        let (metadata, genesis_hash, runtime_version, properties) = future::join4(
+            rpc.metadata(),
+            rpc.genesis_hash(),
+            rpc.runtime_version(None),
+            rpc.system_properties(),
+        )
+        .await;
+        let metadata = metadata?;
+
+        let events_decoder = EventsDecoder::new(metadata.clone());
+
+        Ok(Client {
+            rpc,
+            genesis_hash: genesis_hash?,
+            metadata: Arc::new(metadata),
+            events_decoder,
+            properties: properties.unwrap_or_else(|_| Default::default()),
+            runtime_version: runtime_version?,
+            iter_page_size: self.page_size.unwrap_or(10),
+        })
+    }
+}
+
+/// Client to interface with a substrate node.
+#[derive(Derivative)]
+#[derivative(Clone(bound = ""))]
+pub struct Client<T: Config> {
+    rpc: Rpc<T>,
+    genesis_hash: T::Hash,
+    metadata: Arc<Metadata>,
+    events_decoder: EventsDecoder<T>,
+    properties: SystemProperties,
+    runtime_version: RuntimeVersion,
+    iter_page_size: u32,
+}
+
+impl<T: Config> std::fmt::Debug for Client<T> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("Client")
+            .field("rpc", &"<Rpc>")
+            .field("genesis_hash", &self.genesis_hash)
+            .field("metadata", &"<Metadata>")
+            .field("events_decoder", &"<EventsDecoder>")
+            .field("properties", &self.properties)
+            .field("runtime_version", &self.runtime_version)
+            .field("iter_page_size", &self.iter_page_size)
+            .finish()
+    }
+}
+
+impl<T: Config> Client<T> {
+    /// Returns the genesis hash.
+    pub fn genesis(&self) -> &T::Hash {
+        &self.genesis_hash
+    }
+
+    /// Returns the chain metadata.
+    pub fn metadata(&self) -> &Metadata {
+        &self.metadata
+    }
+
+    /// Returns the properties defined in the chain spec as a JSON object.
+    ///
+    /// # Note
+    ///
+    /// Many chains use this to define common properties such as `token_decimals` and `token_symbol`
+    /// required for UIs, but this is merely a convention. It is up to the library user to
+    /// deserialize the JSON into the appropriate type or otherwise extract the properties defined
+    /// in the target chain's spec.
+    pub fn properties(&self) -> &SystemProperties {
+        &self.properties
+    }
+
+    /// Returns the rpc client.
+    pub fn rpc(&self) -> &Rpc<T> {
+        &self.rpc
+    }
+
+    /// Create a client for accessing runtime storage
+    pub fn storage(&self) -> StorageClient<T> {
+        StorageClient::new(&self.rpc, &self.metadata, self.iter_page_size)
+    }
+
+    /// Convert the client to a runtime api wrapper for custom runtime access.
+    ///
+    /// The `subxt` proc macro will provide methods to submit extrinsics and read storage specific
+    /// to the target runtime.
+    pub fn to_runtime_api<R: From<Self>>(self) -> R {
+        self.into()
+    }
+
+    /// Returns the events decoder.
+    pub fn events_decoder(&self) -> &EventsDecoder<T> {
+        &self.events_decoder
+    }
+}
+
+/// A constructed call ready to be signed and submitted.
+pub struct SubmittableExtrinsic<'client, T: Config, X, A, C, E: Decode> {
+    client: &'client Client<T>,
+    call: C,
+    marker: std::marker::PhantomData<(X, A, E)>,
+}
+
+impl<'client, T, X, A, C, E> SubmittableExtrinsic<'client, T, X, A, C, E>
+where
+    T: Config,
+    X: SignedExtra<T>,
+    A: AccountData,
+    C: Call + Send + Sync,
+    E: Decode,
+{
+    /// Create a new [`SubmittableExtrinsic`].
+    pub fn new(client: &'client Client<T>, call: C) -> Self {
+        Self {
+            client,
+            call,
+            marker: Default::default(),
+        }
+    }
+
+    /// Creates and signs an extrinsic and submits it to the chain.
+    ///
+    /// Returns a [`TransactionProgress`], which can be used to track the status of the transaction
+    /// and obtain details about it, once it has made it into a block.
+    pub async fn sign_and_submit_then_watch(
+        self,
+        signer: &(dyn Signer<T, X> + Send + Sync),
+    ) -> Result<TransactionProgress<'client, T, E>, BasicError>
+    where
+        <<X as SignedExtra<T>>::Extra as SignedExtension>::AdditionalSigned:
+            Send + Sync + 'static,
+        <A as AccountData>::AccountId: From<<T as Config>::AccountId>,
+        <A as AccountData>::Index: Into<<T as Config>::Index>,
+    {
+        // Sign the call data to create our extrinsic.
+        let extrinsic = self.create_signed(signer, Default::default()).await?;
+
+        // Get a hash of the extrinsic (we'll need this later).
+        let ext_hash = T::Hashing::hash_of(&extrinsic);
+
+        // Submit and watch for transaction progress.
+        let sub = self.client.rpc().watch_extrinsic(extrinsic).await?;
+
+        Ok(TransactionProgress::new(sub, self.client, ext_hash))
+    }
+
+    /// Creates and signs an extrinsic and submits to the chain for block inclusion.
+    ///
+    /// Returns `Ok` with the extrinsic hash if it is valid extrinsic.
+    ///
+    /// # Note
+    ///
+    /// Success does not mean the extrinsic has been included in the block, just that it is valid
+    /// and has been included in the transaction pool.
+    pub async fn sign_and_submit(
+        self,
+        signer: &(dyn Signer<T, X> + Send + Sync),
+    ) -> Result<T::Hash, BasicError>
+    where
+        <<X as SignedExtra<T>>::Extra as SignedExtension>::AdditionalSigned:
+            Send + Sync + 'static,
+        <A as AccountData>::AccountId: From<<T as Config>::AccountId>,
+        <A as AccountData>::Index: Into<<T as Config>::Index>,
+    {
+        let extrinsic = self.create_signed(signer, Default::default()).await?;
+        self.client.rpc().submit_extrinsic(extrinsic).await
+    }
+
+    /// Creates a signed extrinsic.
+    pub async fn create_signed(
+        &self,
+        signer: &(dyn Signer<T, X> + Send + Sync),
+        additional_params: X::Parameters,
+    ) -> Result<UncheckedExtrinsic<T, X>, BasicError>
+    where
+        <<X as SignedExtra<T>>::Extra as SignedExtension>::AdditionalSigned:
+            Send + Sync + 'static,
+        <A as AccountData>::AccountId: From<<T as Config>::AccountId>,
+        <A as AccountData>::Index: Into<<T as Config>::Index>,
+    {
+        let account_nonce = if let Some(nonce) = signer.nonce() {
+            nonce
+        } else {
+            let account_storage_entry =
+                A::storage_entry(signer.account_id().clone().into());
+            let account_data = self
+                .client
+                .storage()
+                .fetch_or_default(&account_storage_entry, None)
+                .await?;
+            A::nonce(&account_data).into()
+        };
+        let call = self
+            .client
+            .metadata()
+            .pallet(C::PALLET)
+            .and_then(|pallet| pallet.encode_call(&self.call))?;
+
+        let signed = extrinsic::create_signed(
+            &self.client.runtime_version,
+            self.client.genesis_hash,
+            account_nonce,
+            call,
+            signer,
+            additional_params,
+        )
+        .await?;
+        Ok(signed)
+    }
+}

subxt/src/config.rs

@@ -0,0 +1,123 @@
+// 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::StorageEntry;
+use codec::{
+    Codec,
+    Encode,
+    EncodeLike,
+};
+use core::fmt::Debug;
+use sp_runtime::traits::{
+    AtLeast32Bit,
+    Extrinsic,
+    Hash,
+    Header,
+    MaybeSerializeDeserialize,
+    Member,
+    Verify,
+};
+
+/// Runtime types.
+// Note: the 'static bound isn't strictly required, but currently deriving TypeInfo
+// automatically applies a 'static bound to all generic types (including this one),
+// and so until that is resolved, we'll keep the (easy to satisfy) constraint here.
+pub trait Config: 'static {
+    /// Account index (aka nonce) type. This stores the number of previous
+    /// transactions associated with a sender account.
+    type Index: Parameter + Member + Default + AtLeast32Bit + Copy + scale_info::TypeInfo;
+
+    /// The block number type used by the runtime.
+    type BlockNumber: Parameter
+        + Member
+        + Default
+        + Copy
+        + core::hash::Hash
+        + core::str::FromStr;
+
+    /// The output of the `Hashing` function.
+    type Hash: Parameter
+        + Member
+        + MaybeSerializeDeserialize
+        + Ord
+        + Default
+        + Copy
+        + std::hash::Hash
+        + AsRef<[u8]>
+        + AsMut<[u8]>
+        + scale_info::TypeInfo;
+
+    /// The hashing system (algorithm) being used in the runtime (e.g. Blake2).
+    type Hashing: Hash<Output = Self::Hash>;
+
+    /// The user account identifier type for the runtime.
+    type AccountId: Parameter + Member;
+
+    /// The address type. This instead of `<frame_system::Trait::Lookup as StaticLookup>::Source`.
+    type Address: Codec + Clone + PartialEq;
+
+    /// The block header.
+    type Header: Parameter
+        + Header<Number = Self::BlockNumber, Hash = Self::Hash>
+        + serde::de::DeserializeOwned;
+
+    /// Signature type.
+    type Signature: Verify + Encode + Send + Sync + 'static;
+
+    /// Extrinsic type within blocks.
+    type Extrinsic: Parameter + Extrinsic + Debug + MaybeSerializeDeserialize;
+}
+
+/// Parameter trait copied from `substrate::frame_support`
+pub trait Parameter: Codec + EncodeLike + Clone + Eq + Debug {}
+impl<T> Parameter for T where T: Codec + EncodeLike + Clone + Eq + Debug {}
+
+/// Default set of commonly used types by Substrate runtimes.
+// Note: We only use this at the type level, so it should be impossible to
+// create an instance of it.
+pub enum DefaultConfig {}
+
+impl Config for DefaultConfig {
+    type Index = u32;
+    type BlockNumber = u32;
+    type Hash = sp_core::H256;
+    type Hashing = sp_runtime::traits::BlakeTwo256;
+    type AccountId = sp_runtime::AccountId32;
+    type Address = sp_runtime::MultiAddress<Self::AccountId, u32>;
+    type Header =
+        sp_runtime::generic::Header<Self::BlockNumber, sp_runtime::traits::BlakeTwo256>;
+    type Signature = sp_runtime::MultiSignature;
+    type Extrinsic = sp_runtime::OpaqueExtrinsic;
+}
+
+/// Trait to fetch data about an account.
+pub trait AccountData {
+    /// The runtime storage entry from which the account data can be fetched.
+    /// Usually generated by the `subxt` macro.
+    type StorageEntry: StorageEntry;
+
+    /// The type of the account id to fetch the account data for.
+    type AccountId;
+
+    /// The type of the account nonce returned from storage.
+    type Index;
+
+    /// Create a new storage entry key from the account id.
+    fn storage_entry(account_id: Self::AccountId) -> Self::StorageEntry;
+
+    /// Get the nonce from the storage entry value.
+    fn nonce(result: &<Self::StorageEntry as StorageEntry>::Value) -> Self::Index;
+}

subxt/src/error.rs

@@ -0,0 +1,181 @@
+// 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::{
+    events::EventsDecodingError,
+    metadata::{
+        InvalidMetadataError,
+        MetadataError,
+    },
+};
+use core::fmt::Debug;
+use jsonrpsee::core::error::Error as RequestError;
+use sp_core::crypto::SecretStringError;
+use sp_runtime::transaction_validity::TransactionValidityError;
+
+/// An error that may contain some runtime error `E`
+pub type Error<E> = GenericError<RuntimeError<E>>;
+
+/// An error that will never contain a runtime error.
+pub type BasicError = GenericError<std::convert::Infallible>;
+
+/// The underlying error enum, generic over the type held by the `Runtime`
+/// variant. Prefer to use the [`Error<E>`] and [`BasicError`] aliases over
+/// using this type directly.
+#[derive(Debug, thiserror::Error)]
+pub enum GenericError<E> {
+    /// Io error.
+    #[error("Io error: {0}")]
+    Io(#[from] std::io::Error),
+    /// Codec error.
+    #[error("Scale codec error: {0}")]
+    Codec(#[from] codec::Error),
+    /// Rpc error.
+    #[error("Rpc error: {0}")]
+    Rpc(#[from] RequestError),
+    /// Serde serialization error
+    #[error("Serde json error: {0}")]
+    Serialization(#[from] serde_json::error::Error),
+    /// Secret string error.
+    #[error("Secret String Error")]
+    SecretString(SecretStringError),
+    /// Extrinsic validity error
+    #[error("Transaction Validity Error: {0:?}")]
+    Invalid(TransactionValidityError),
+    /// Invalid metadata error
+    #[error("Invalid Metadata: {0}")]
+    InvalidMetadata(#[from] InvalidMetadataError),
+    /// Invalid metadata error
+    #[error("Metadata: {0}")]
+    Metadata(#[from] MetadataError),
+    /// Runtime error.
+    #[error("Runtime error: {0:?}")]
+    Runtime(E),
+    /// Events decoding error.
+    #[error("Events decoding error: {0}")]
+    EventsDecoding(#[from] EventsDecodingError),
+    /// Transaction progress error.
+    #[error("Transaction error: {0}")]
+    Transaction(#[from] TransactionError),
+    /// Other error.
+    #[error("Other error: {0}")]
+    Other(String),
+}
+
+impl<E> GenericError<E> {
+    /// [`GenericError`] is parameterised over the type that it holds in the `Runtime`
+    /// variant. This function allows us to map the Runtime error contained within (if present)
+    /// to a different type.
+    pub fn map_runtime_err<F, NewE>(self, f: F) -> GenericError<NewE>
+    where
+        F: FnOnce(E) -> NewE,
+    {
+        match self {
+            GenericError::Io(e) => GenericError::Io(e),
+            GenericError::Codec(e) => GenericError::Codec(e),
+            GenericError::Rpc(e) => GenericError::Rpc(e),
+            GenericError::Serialization(e) => GenericError::Serialization(e),
+            GenericError::SecretString(e) => GenericError::SecretString(e),
+            GenericError::Invalid(e) => GenericError::Invalid(e),
+            GenericError::InvalidMetadata(e) => GenericError::InvalidMetadata(e),
+            GenericError::Metadata(e) => GenericError::Metadata(e),
+            GenericError::EventsDecoding(e) => GenericError::EventsDecoding(e),
+            GenericError::Transaction(e) => GenericError::Transaction(e),
+            GenericError::Other(e) => GenericError::Other(e),
+            // This is the only branch we really care about:
+            GenericError::Runtime(e) => GenericError::Runtime(f(e)),
+        }
+    }
+}
+
+impl BasicError {
+    /// Convert an [`BasicError`] into any
+    /// arbitrary [`Error<E>`].
+    pub fn into_error<E>(self) -> Error<E> {
+        self.map_runtime_err(|e| match e {})
+    }
+}
+
+impl<E> From<BasicError> for Error<E> {
+    fn from(err: BasicError) -> Self {
+        err.into_error()
+    }
+}
+
+impl<E> From<SecretStringError> for GenericError<E> {
+    fn from(error: SecretStringError) -> Self {
+        GenericError::SecretString(error)
+    }
+}
+
+impl<E> From<TransactionValidityError> for GenericError<E> {
+    fn from(error: TransactionValidityError) -> Self {
+        GenericError::Invalid(error)
+    }
+}
+
+impl<E> From<&str> for GenericError<E> {
+    fn from(error: &str) -> Self {
+        GenericError::Other(error.into())
+    }
+}
+
+impl<E> From<String> for GenericError<E> {
+    fn from(error: String) -> Self {
+        GenericError::Other(error)
+    }
+}
+
+/// This is used in the place of the `E` in [`GenericError<E>`] when we may have a
+/// Runtime Error. We use this wrapper so that it is possible to implement
+/// `From<Error<Infallible>` for `Error<RuntimeError<E>>`.
+///
+/// This should not be used as a type; prefer to use the alias [`Error<E>`] when referring
+/// to errors which may contain some Runtime error `E`.
+#[derive(Clone, Debug, PartialEq)]
+pub struct RuntimeError<E>(pub E);
+
+impl<E> RuntimeError<E> {
+    /// Extract the actual runtime error from this struct.
+    pub fn inner(self) -> E {
+        self.0
+    }
+}
+
+/// Module error.
+#[derive(Clone, Debug, Eq, thiserror::Error, PartialEq)]
+#[error("{error} from {pallet}")]
+pub struct PalletError {
+    /// The module where the error originated.
+    pub pallet: String,
+    /// The actual error code.
+    pub error: String,
+    /// The error description.
+    pub description: Vec<String>,
+}
+
+/// Transaction error.
+#[derive(Clone, Debug, Eq, thiserror::Error, PartialEq)]
+pub enum TransactionError {
+    /// The finality subscription expired (after ~512 blocks we give up if the
+    /// block hasn't yet been finalized).
+    #[error("The finality subscription expired")]
+    FinalitySubscriptionTimeout,
+    /// The block hash that the tranaction was added to could not be found.
+    /// This is probably because the block was retracted before being finalized.
+    #[error("The block containing the transaction can no longer be found (perhaps it was on a non-finalized fork?)")]
+    BlockHashNotFound,
+}

subxt/src/events.rs

@@ -0,0 +1,646 @@
+// 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::{
+    error::BasicError,
+    metadata::{
+        EventMetadata,
+        MetadataError,
+    },
+    Config,
+    Event,
+    Metadata,
+    PhantomDataSendSync,
+    Phase,
+};
+use bitvec::{
+    order::Lsb0,
+    vec::BitVec,
+};
+use codec::{
+    Codec,
+    Compact,
+    Decode,
+    Error as CodecError,
+    Input,
+};
+use derivative::Derivative;
+use scale_info::{
+    PortableRegistry,
+    TypeDef,
+    TypeDefPrimitive,
+};
+use sp_core::Bytes;
+
+/// Raw bytes for an Event
+#[derive(Debug)]
+#[cfg_attr(test, derive(PartialEq, Clone))]
+pub struct RawEvent {
+    /// The name of the pallet from whence the Event originated.
+    pub pallet: String,
+    /// The index of the pallet from whence the Event originated.
+    pub pallet_index: u8,
+    /// The name of the pallet Event variant.
+    pub variant: String,
+    /// The index of the pallet Event variant.
+    pub variant_index: u8,
+    /// The raw Event data
+    pub data: Bytes,
+}
+
+impl RawEvent {
+    /// Attempt to decode this [`RawEvent`] into a specific event.
+    pub fn as_event<E: Event>(&self) -> Result<Option<E>, CodecError> {
+        if self.pallet == E::PALLET && self.variant == E::EVENT {
+            Ok(Some(E::decode(&mut &self.data[..])?))
+        } else {
+            Ok(None)
+        }
+    }
+}
+
+/// Events decoder.
+#[derive(Derivative)]
+#[derivative(Clone(bound = ""), Debug(bound = ""))]
+pub struct EventsDecoder<T: Config> {
+    metadata: Metadata,
+    marker: PhantomDataSendSync<T>,
+}
+
+impl<T: Config> EventsDecoder<T> {
+    /// Creates a new `EventsDecoder`.
+    pub fn new(metadata: Metadata) -> Self {
+        Self {
+            metadata,
+            marker: Default::default(),
+        }
+    }
+
+    /// Decode events.
+    pub fn decode_events(
+        &self,
+        input: &mut &[u8],
+    ) -> Result<Vec<(Phase, RawEvent)>, BasicError> {
+        let compact_len = <Compact<u32>>::decode(input)?;
+        let len = compact_len.0 as usize;
+        log::debug!("decoding {} events", len);
+
+        let mut r = Vec::new();
+        for _ in 0..len {
+            // decode EventRecord
+            let phase = Phase::decode(input)?;
+            let pallet_index = input.read_byte()?;
+            let variant_index = input.read_byte()?;
+            log::debug!(
+                "phase {:?}, pallet_index {}, event_variant: {}",
+                phase,
+                pallet_index,
+                variant_index
+            );
+            log::debug!("remaining input: {}", hex::encode(&input));
+
+            let event_metadata = self.metadata.event(pallet_index, variant_index)?;
+
+            let mut event_data = Vec::<u8>::new();
+            let result = self.decode_raw_event(event_metadata, input, &mut event_data);
+            let raw = match result {
+                Ok(()) => {
+                    log::debug!("raw bytes: {}", hex::encode(&event_data),);
+
+                    let event = RawEvent {
+                        pallet: event_metadata.pallet().to_string(),
+                        pallet_index,
+                        variant: event_metadata.event().to_string(),
+                        variant_index,
+                        data: event_data.into(),
+                    };
+
+                    // topics come after the event data in EventRecord
+                    let topics = Vec::<T::Hash>::decode(input)?;
+                    log::debug!("topics: {:?}", topics);
+
+                    event
+                }
+                Err(err) => return Err(err),
+            };
+            r.push((phase.clone(), raw));
+        }
+        Ok(r)
+    }
+
+    fn decode_raw_event(
+        &self,
+        event_metadata: &EventMetadata,
+        input: &mut &[u8],
+        output: &mut Vec<u8>,
+    ) -> Result<(), BasicError> {
+        log::debug!(
+            "Decoding Event '{}::{}'",
+            event_metadata.pallet(),
+            event_metadata.event()
+        );
+        for arg in event_metadata.variant().fields() {
+            let type_id = arg.ty().id();
+            self.decode_type(type_id, input, output)?
+        }
+        Ok(())
+    }
+
+    fn decode_type(
+        &self,
+        type_id: u32,
+        input: &mut &[u8],
+        output: &mut Vec<u8>,
+    ) -> Result<(), BasicError> {
+        let all_bytes = *input;
+        // consume some bytes, moving the cursor forward:
+        decode_and_consume_type(type_id, &self.metadata.runtime_metadata().types, input)?;
+        // count how many bytes were consumed based on remaining length:
+        let consumed_len = all_bytes.len() - input.len();
+        // move those consumed bytes to the output vec unaltered:
+        output.extend(&all_bytes[0..consumed_len]);
+        Ok(())
+    }
+}
+
+// Given a type Id and a type registry, attempt to consume the bytes
+// corresponding to that type from our input.
+fn decode_and_consume_type(
+    type_id: u32,
+    types: &PortableRegistry,
+    input: &mut &[u8],
+) -> Result<(), BasicError> {
+    let ty = types
+        .resolve(type_id)
+        .ok_or(MetadataError::TypeNotFound(type_id))?;
+
+    fn consume_type<T: Codec>(input: &mut &[u8]) -> Result<(), BasicError> {
+        T::decode(input)?;
+        Ok(())
+    }
+
+    match ty.type_def() {
+        TypeDef::Composite(composite) => {
+            for field in composite.fields() {
+                decode_and_consume_type(field.ty().id(), types, input)?
+            }
+            Ok(())
+        }
+        TypeDef::Variant(variant) => {
+            let variant_index = u8::decode(input)?;
+            let variant = variant
+                .variants()
+                .iter()
+                .find(|v| v.index() == variant_index)
+                .ok_or_else(|| {
+                    BasicError::Other(format!("Variant {} not found", variant_index))
+                })?;
+            for field in variant.fields() {
+                decode_and_consume_type(field.ty().id(), types, input)?;
+            }
+            Ok(())
+        }
+        TypeDef::Sequence(seq) => {
+            let len = <Compact<u32>>::decode(input)?;
+            for _ in 0..len.0 {
+                decode_and_consume_type(seq.type_param().id(), types, input)?;
+            }
+            Ok(())
+        }
+        TypeDef::Array(arr) => {
+            for _ in 0..arr.len() {
+                decode_and_consume_type(arr.type_param().id(), types, input)?;
+            }
+            Ok(())
+        }
+        TypeDef::Tuple(tuple) => {
+            for field in tuple.fields() {
+                decode_and_consume_type(field.id(), types, input)?;
+            }
+            Ok(())
+        }
+        TypeDef::Primitive(primitive) => {
+            match primitive {
+                TypeDefPrimitive::Bool => consume_type::<bool>(input),
+                TypeDefPrimitive::Char => {
+                    Err(
+                        EventsDecodingError::UnsupportedPrimitive(TypeDefPrimitive::Char)
+                            .into(),
+                    )
+                }
+                TypeDefPrimitive::Str => consume_type::<String>(input),
+                TypeDefPrimitive::U8 => consume_type::<u8>(input),
+                TypeDefPrimitive::U16 => consume_type::<u16>(input),
+                TypeDefPrimitive::U32 => consume_type::<u32>(input),
+                TypeDefPrimitive::U64 => consume_type::<u64>(input),
+                TypeDefPrimitive::U128 => consume_type::<u128>(input),
+                TypeDefPrimitive::U256 => {
+                    Err(
+                        EventsDecodingError::UnsupportedPrimitive(TypeDefPrimitive::U256)
+                            .into(),
+                    )
+                }
+                TypeDefPrimitive::I8 => consume_type::<i8>(input),
+                TypeDefPrimitive::I16 => consume_type::<i16>(input),
+                TypeDefPrimitive::I32 => consume_type::<i32>(input),
+                TypeDefPrimitive::I64 => consume_type::<i64>(input),
+                TypeDefPrimitive::I128 => consume_type::<i128>(input),
+                TypeDefPrimitive::I256 => {
+                    Err(
+                        EventsDecodingError::UnsupportedPrimitive(TypeDefPrimitive::I256)
+                            .into(),
+                    )
+                }
+            }
+        }
+        TypeDef::Compact(compact) => {
+            let inner = types
+                .resolve(compact.type_param().id())
+                .ok_or(MetadataError::TypeNotFound(type_id))?;
+            let mut decode_compact_primitive = |primitive: &TypeDefPrimitive| {
+                match primitive {
+                    TypeDefPrimitive::U8 => consume_type::<Compact<u8>>(input),
+                    TypeDefPrimitive::U16 => consume_type::<Compact<u16>>(input),
+                    TypeDefPrimitive::U32 => consume_type::<Compact<u32>>(input),
+                    TypeDefPrimitive::U64 => consume_type::<Compact<u64>>(input),
+                    TypeDefPrimitive::U128 => consume_type::<Compact<u128>>(input),
+                    prim => {
+                        Err(EventsDecodingError::InvalidCompactPrimitive(prim.clone())
+                            .into())
+                    }
+                }
+            };
+            match inner.type_def() {
+                TypeDef::Primitive(primitive) => decode_compact_primitive(primitive),
+                TypeDef::Composite(composite) => {
+                    match composite.fields() {
+                        [field] => {
+                            let field_ty =
+                                types.resolve(field.ty().id()).ok_or_else(|| {
+                                    MetadataError::TypeNotFound(field.ty().id())
+                                })?;
+                            if let TypeDef::Primitive(primitive) = field_ty.type_def() {
+                                decode_compact_primitive(primitive)
+                            } else {
+                                Err(EventsDecodingError::InvalidCompactType(
+                                    "Composite type must have a single primitive field"
+                                        .into(),
+                                )
+                                .into())
+                            }
+                        }
+                        _ => {
+                            Err(EventsDecodingError::InvalidCompactType(
+                                "Composite type must have a single field".into(),
+                            )
+                            .into())
+                        }
+                    }
+                }
+                _ => {
+                    Err(EventsDecodingError::InvalidCompactType(
+                        "Compact type must be a primitive or a composite type".into(),
+                    )
+                    .into())
+                }
+            }
+        }
+        TypeDef::BitSequence(bitseq) => {
+            let bit_store_def = types
+                .resolve(bitseq.bit_store_type().id())
+                .ok_or(MetadataError::TypeNotFound(type_id))?
+                .type_def();
+
+            // We just need to consume the correct number of bytes. Roughly, we encode this
+            // as a Compact<u32> length, and then a slice of T of that length, where T is the
+            // bit store type. So, we ignore the bit order and only care that the bit store type
+            // used lines up in terms of the number of bytes it will take to encode/decode it.
+            match bit_store_def {
+                TypeDef::Primitive(TypeDefPrimitive::U8) => {
+                    consume_type::<BitVec<Lsb0, u8>>(input)
+                }
+                TypeDef::Primitive(TypeDefPrimitive::U16) => {
+                    consume_type::<BitVec<Lsb0, u16>>(input)
+                }
+                TypeDef::Primitive(TypeDefPrimitive::U32) => {
+                    consume_type::<BitVec<Lsb0, u32>>(input)
+                }
+                TypeDef::Primitive(TypeDefPrimitive::U64) => {
+                    consume_type::<BitVec<Lsb0, u64>>(input)
+                }
+                store => {
+                    return Err(EventsDecodingError::InvalidBitSequenceType(format!(
+                        "{:?}",
+                        store
+                    ))
+                    .into())
+                }
+            }
+        }
+    }
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum EventsDecodingError {
+    /// Unsupported primitive type
+    #[error("Unsupported primitive type {0:?}")]
+    UnsupportedPrimitive(TypeDefPrimitive),
+    /// Invalid compact type, must be an unsigned int.
+    #[error("Invalid compact primitive {0:?}")]
+    InvalidCompactPrimitive(TypeDefPrimitive),
+    /// Invalid compact type; error details in string.
+    #[error("Invalid compact composite type {0}")]
+    InvalidCompactType(String),
+    /// Invalid bit sequence type; bit store type or bit order type used aren't supported.
+    #[error("Invalid bit sequence type; bit store type {0} is not supported")]
+    InvalidBitSequenceType(String),
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{
+        Config,
+        DefaultConfig,
+        Phase,
+    };
+    use codec::Encode;
+    use frame_metadata::{
+        v14::{
+            ExtrinsicMetadata,
+            PalletEventMetadata,
+            PalletMetadata,
+            RuntimeMetadataLastVersion,
+        },
+        RuntimeMetadataPrefixed,
+    };
+    use scale_info::{
+        meta_type,
+        TypeInfo,
+    };
+    use std::convert::TryFrom;
+
+    type TypeId = scale_info::interner::UntrackedSymbol<std::any::TypeId>;
+
+    #[derive(Encode)]
+    pub struct EventRecord<E: Encode> {
+        phase: Phase,
+        pallet_index: u8,
+        event: E,
+        topics: Vec<<DefaultConfig as Config>::Hash>,
+    }
+
+    fn event_record<E: Encode>(pallet_index: u8, event: E) -> EventRecord<E> {
+        EventRecord {
+            phase: Phase::Finalization,
+            pallet_index,
+            event,
+            topics: vec![],
+        }
+    }
+
+    fn singleton_type_registry<T: scale_info::TypeInfo + 'static>(
+    ) -> (TypeId, PortableRegistry) {
+        let m = scale_info::MetaType::new::<T>();
+        let mut types = scale_info::Registry::new();
+        let id = types.register_type(&m);
+        let portable_registry: PortableRegistry = types.into();
+
+        (id, portable_registry)
+    }
+
+    fn pallet_metadata<E: TypeInfo + 'static>(pallet_index: u8) -> PalletMetadata {
+        let event = PalletEventMetadata {
+            ty: meta_type::<E>(),
+        };
+        PalletMetadata {
+            name: "Test",
+            storage: None,
+            calls: None,
+            event: Some(event),
+            constants: vec![],
+            error: None,
+            index: pallet_index,
+        }
+    }
+
+    fn init_decoder(pallets: Vec<PalletMetadata>) -> EventsDecoder<DefaultConfig> {
+        let extrinsic = ExtrinsicMetadata {
+            ty: meta_type::<()>(),
+            version: 0,
+            signed_extensions: vec![],
+        };
+        let v14 = RuntimeMetadataLastVersion::new(pallets, extrinsic, meta_type::<()>());
+        let runtime_metadata: RuntimeMetadataPrefixed = v14.into();
+        let metadata = Metadata::try_from(runtime_metadata).unwrap();
+        EventsDecoder::<DefaultConfig>::new(metadata)
+    }
+
+    fn decode_and_consume_type_consumes_all_bytes<
+        T: codec::Encode + scale_info::TypeInfo + 'static,
+    >(
+        val: T,
+    ) {
+        let (type_id, registry) = singleton_type_registry::<T>();
+        let bytes = val.encode();
+        let cursor = &mut &*bytes;
+
+        decode_and_consume_type(type_id.id(), &registry, cursor).unwrap();
+        assert_eq!(cursor.len(), 0);
+    }
+
+    #[test]
+    fn decode_single_event() {
+        #[derive(Clone, Encode, TypeInfo)]
+        enum Event {
+            A(u8),
+        }
+
+        let pallet_index = 0;
+        let pallet = pallet_metadata::<Event>(pallet_index);
+        let decoder = init_decoder(vec![pallet]);
+
+        let event = Event::A(1);
+        let encoded_event = event.encode();
+        let event_records = vec![event_record(pallet_index, event)];
+
+        let mut input = Vec::new();
+        event_records.encode_to(&mut input);
+
+        let events = decoder.decode_events(&mut &input[..]).unwrap();
+
+        assert_eq!(events[0].1.variant_index, encoded_event[0]);
+        assert_eq!(events[0].1.data.0, encoded_event[1..]);
+    }
+
+    #[test]
+    fn decode_multiple_events() {
+        #[derive(Clone, Encode, TypeInfo)]
+        enum Event {
+            A(u8),
+            B,
+            C { a: u32 },
+        }
+
+        let pallet_index = 0;
+        let pallet = pallet_metadata::<Event>(pallet_index);
+        let decoder = init_decoder(vec![pallet]);
+
+        let event1 = Event::A(1);
+        let event2 = Event::B;
+        let event3 = Event::C { a: 3 };
+
+        let encoded_event1 = event1.encode();
+        let encoded_event2 = event2.encode();
+        let encoded_event3 = event3.encode();
+
+        let event_records = vec![
+            event_record(pallet_index, event1),
+            event_record(pallet_index, event2),
+            event_record(pallet_index, event3),
+        ];
+
+        let mut input = Vec::new();
+        event_records.encode_to(&mut input);
+
+        let events = decoder.decode_events(&mut &input[..]).unwrap();
+
+        assert_eq!(events[0].1.variant_index, encoded_event1[0]);
+        assert_eq!(events[0].1.data.0, encoded_event1[1..]);
+
+        assert_eq!(events[1].1.variant_index, encoded_event2[0]);
+        assert_eq!(events[1].1.data.0, encoded_event2[1..]);
+
+        assert_eq!(events[2].1.variant_index, encoded_event3[0]);
+        assert_eq!(events[2].1.data.0, encoded_event3[1..]);
+    }
+
+    #[test]
+    fn compact_event_field() {
+        #[derive(Clone, Encode, TypeInfo)]
+        enum Event {
+            A(#[codec(compact)] u32),
+        }
+
+        let pallet_index = 0;
+        let pallet = pallet_metadata::<Event>(pallet_index);
+        let decoder = init_decoder(vec![pallet]);
+
+        let event = Event::A(u32::MAX);
+        let encoded_event = event.encode();
+        let event_records = vec![event_record(pallet_index, event)];
+
+        let mut input = Vec::new();
+        event_records.encode_to(&mut input);
+
+        let events = decoder.decode_events(&mut &input[..]).unwrap();
+
+        assert_eq!(events[0].1.variant_index, encoded_event[0]);
+        assert_eq!(events[0].1.data.0, encoded_event[1..]);
+    }
+
+    #[test]
+    fn compact_wrapper_struct_field() {
+        #[derive(Clone, Encode, TypeInfo)]
+        enum Event {
+            A(#[codec(compact)] CompactWrapper),
+        }
+
+        #[derive(Clone, codec::CompactAs, Encode, TypeInfo)]
+        struct CompactWrapper(u64);
+
+        let pallet_index = 0;
+        let pallet = pallet_metadata::<Event>(pallet_index);
+        let decoder = init_decoder(vec![pallet]);
+
+        let event = Event::A(CompactWrapper(0));
+        let encoded_event = event.encode();
+        let event_records = vec![event_record(pallet_index, event)];
+
+        let mut input = Vec::new();
+        event_records.encode_to(&mut input);
+
+        let events = decoder.decode_events(&mut &input[..]).unwrap();
+
+        assert_eq!(events[0].1.variant_index, encoded_event[0]);
+        assert_eq!(events[0].1.data.0, encoded_event[1..]);
+    }
+
+    #[test]
+    fn event_containing_explicit_index() {
+        #[derive(Clone, Encode, TypeInfo)]
+        #[repr(u8)]
+        #[allow(trivial_numeric_casts, clippy::unnecessary_cast)] // required because the Encode derive produces a warning otherwise
+        pub enum MyType {
+            B = 10u8,
+        }
+
+        #[derive(Clone, Encode, TypeInfo)]
+        enum Event {
+            A(MyType),
+        }
+
+        let pallet_index = 0;
+        let pallet = pallet_metadata::<Event>(pallet_index);
+        let decoder = init_decoder(vec![pallet]);
+
+        let event = Event::A(MyType::B);
+        let encoded_event = event.encode();
+        let event_records = vec![event_record(pallet_index, event)];
+
+        let mut input = Vec::new();
+        event_records.encode_to(&mut input);
+
+        // this would panic if the explicit enum item index were not correctly used
+        let events = decoder.decode_events(&mut &input[..]).unwrap();
+
+        assert_eq!(events[0].1.variant_index, encoded_event[0]);
+        assert_eq!(events[0].1.data.0, encoded_event[1..]);
+    }
+
+    #[test]
+    fn decode_bitvec() {
+        use bitvec::order::Msb0;
+
+        decode_and_consume_type_consumes_all_bytes(
+            bitvec::bitvec![Lsb0, u8; 0, 1, 1, 0, 1],
+        );
+        decode_and_consume_type_consumes_all_bytes(
+            bitvec::bitvec![Msb0, u8; 0, 1, 1, 0, 1, 0, 1, 0, 0],
+        );
+
+        decode_and_consume_type_consumes_all_bytes(
+            bitvec::bitvec![Lsb0, u16; 0, 1, 1, 0, 1],
+        );
+        decode_and_consume_type_consumes_all_bytes(
+            bitvec::bitvec![Msb0, u16; 0, 1, 1, 0, 1, 0, 1, 0, 0],
+        );
+
+        decode_and_consume_type_consumes_all_bytes(
+            bitvec::bitvec![Lsb0, u32; 0, 1, 1, 0, 1],
+        );
+        decode_and_consume_type_consumes_all_bytes(
+            bitvec::bitvec![Msb0, u32; 0, 1, 1, 0, 1, 0, 1, 0, 0],
+        );
+
+        decode_and_consume_type_consumes_all_bytes(
+            bitvec::bitvec![Lsb0, u64; 0, 1, 1, 0, 1],
+        );
+        decode_and_consume_type_consumes_all_bytes(
+            bitvec::bitvec![Msb0, u64; 0, 1, 1, 0, 1, 0, 1, 0, 0],
+        );
+    }
+}

subxt/src/extrinsic/extra.rs

@@ -0,0 +1,481 @@
+// 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::PhantomDataSendSync;
+use codec::{
+    Decode,
+    Encode,
+};
+use derivative::Derivative;
+use scale_info::TypeInfo;
+use sp_runtime::{
+    generic::Era,
+    traits::{
+        DispatchInfoOf,
+        SignedExtension,
+    },
+    transaction_validity::TransactionValidityError,
+};
+
+use crate::Config;
+
+/// Extra type.
+// pub type Extra<T> = <<T as Config>::Extra as SignedExtra<T>>::Extra;
+
+/// SignedExtra checks copied from substrate, in order to remove requirement to implement
+/// substrate's `frame_system::Trait`
+
+/// Ensure the runtime version registered in the transaction is the same as at present.
+///
+/// # Note
+///
+/// This is modified from the substrate version to allow passing in of the version, which is
+/// returned via `additional_signed()`.
+
+/// Ensure the runtime version registered in the transaction is the same as at present.
+#[derive(Derivative, Encode, Decode, TypeInfo)]
+#[derivative(
+    Clone(bound = ""),
+    PartialEq(bound = ""),
+    Debug(bound = ""),
+    Eq(bound = "")
+)]
+#[scale_info(skip_type_params(T))]
+pub struct CheckSpecVersion<T: Config>(
+    pub PhantomDataSendSync<T>,
+    /// Local version to be used for `AdditionalSigned`
+    #[codec(skip)]
+    pub u32,
+);
+
+impl<T: Config> SignedExtension for CheckSpecVersion<T> {
+    const IDENTIFIER: &'static str = "CheckSpecVersion";
+    type AccountId = T::AccountId;
+    type Call = ();
+    type AdditionalSigned = u32;
+    type Pre = ();
+    fn additional_signed(
+        &self,
+    ) -> Result<Self::AdditionalSigned, TransactionValidityError> {
+        Ok(self.1)
+    }
+    fn pre_dispatch(
+        self,
+        _who: &Self::AccountId,
+        _call: &Self::Call,
+        _info: &DispatchInfoOf<Self::Call>,
+        _len: usize,
+    ) -> Result<Self::Pre, TransactionValidityError> {
+        Ok(())
+    }
+}
+
+/// Ensure the transaction version registered in the transaction is the same as at present.
+///
+/// # Note
+///
+/// This is modified from the substrate version to allow passing in of the version, which is
+/// returned via `additional_signed()`.
+#[derive(Derivative, Encode, Decode, TypeInfo)]
+#[derivative(
+    Clone(bound = ""),
+    PartialEq(bound = ""),
+    Debug(bound = ""),
+    Eq(bound = "")
+)]
+#[scale_info(skip_type_params(T))]
+pub struct CheckTxVersion<T: Config>(
+    pub PhantomDataSendSync<T>,
+    /// Local version to be used for `AdditionalSigned`
+    #[codec(skip)]
+    pub u32,
+);
+
+impl<T: Config> SignedExtension for CheckTxVersion<T> {
+    const IDENTIFIER: &'static str = "CheckTxVersion";
+    type AccountId = T::AccountId;
+    type Call = ();
+    type AdditionalSigned = u32;
+    type Pre = ();
+    fn additional_signed(
+        &self,
+    ) -> Result<Self::AdditionalSigned, TransactionValidityError> {
+        Ok(self.1)
+    }
+    fn pre_dispatch(
+        self,
+        _who: &Self::AccountId,
+        _call: &Self::Call,
+        _info: &DispatchInfoOf<Self::Call>,
+        _len: usize,
+    ) -> Result<Self::Pre, TransactionValidityError> {
+        Ok(())
+    }
+}
+
+/// Check genesis hash
+///
+/// # Note
+///
+/// This is modified from the substrate version to allow passing in of the genesis hash, which is
+/// returned via `additional_signed()`.
+#[derive(Derivative, Encode, Decode, TypeInfo)]
+#[derivative(
+    Clone(bound = ""),
+    PartialEq(bound = ""),
+    Debug(bound = ""),
+    Eq(bound = "")
+)]
+#[scale_info(skip_type_params(T))]
+pub struct CheckGenesis<T: Config>(
+    pub PhantomDataSendSync<T>,
+    /// Local genesis hash to be used for `AdditionalSigned`
+    #[codec(skip)]
+    pub T::Hash,
+);
+
+impl<T: Config> SignedExtension for CheckGenesis<T> {
+    const IDENTIFIER: &'static str = "CheckGenesis";
+    type AccountId = T::AccountId;
+    type Call = ();
+    type AdditionalSigned = T::Hash;
+    type Pre = ();
+    fn additional_signed(
+        &self,
+    ) -> Result<Self::AdditionalSigned, TransactionValidityError> {
+        Ok(self.1)
+    }
+    fn pre_dispatch(
+        self,
+        _who: &Self::AccountId,
+        _call: &Self::Call,
+        _info: &DispatchInfoOf<Self::Call>,
+        _len: usize,
+    ) -> Result<Self::Pre, TransactionValidityError> {
+        Ok(())
+    }
+}
+
+/// Check for transaction mortality.
+///
+/// # Note
+///
+/// This is modified from the substrate version to allow passing in of the genesis hash, which is
+/// returned via `additional_signed()`. It assumes therefore `Era::Immortal` (The transaction is
+/// valid forever)
+#[derive(Derivative, Encode, Decode, TypeInfo)]
+#[derivative(
+    Clone(bound = ""),
+    PartialEq(bound = ""),
+    Debug(bound = ""),
+    Eq(bound = "")
+)]
+#[scale_info(skip_type_params(T))]
+pub struct CheckMortality<T: Config>(
+    /// The default structure for the Extra encoding
+    pub (Era, PhantomDataSendSync<T>),
+    /// Local genesis hash to be used for `AdditionalSigned`
+    #[codec(skip)]
+    pub T::Hash,
+);
+
+impl<T: Config> SignedExtension for CheckMortality<T> {
+    const IDENTIFIER: &'static str = "CheckMortality";
+    type AccountId = T::AccountId;
+    type Call = ();
+    type AdditionalSigned = T::Hash;
+    type Pre = ();
+    fn additional_signed(
+        &self,
+    ) -> Result<Self::AdditionalSigned, TransactionValidityError> {
+        Ok(self.1)
+    }
+    fn pre_dispatch(
+        self,
+        _who: &Self::AccountId,
+        _call: &Self::Call,
+        _info: &DispatchInfoOf<Self::Call>,
+        _len: usize,
+    ) -> Result<Self::Pre, TransactionValidityError> {
+        Ok(())
+    }
+}
+
+/// Nonce check and increment to give replay protection for transactions.
+#[derive(Derivative, Encode, Decode, TypeInfo)]
+#[derivative(
+    Clone(bound = ""),
+    PartialEq(bound = ""),
+    Debug(bound = ""),
+    Eq(bound = "")
+)]
+#[scale_info(skip_type_params(T))]
+pub struct CheckNonce<T: Config>(#[codec(compact)] pub T::Index);
+
+impl<T: Config> SignedExtension for CheckNonce<T> {
+    const IDENTIFIER: &'static str = "CheckNonce";
+    type AccountId = T::AccountId;
+    type Call = ();
+    type AdditionalSigned = ();
+    type Pre = ();
+    fn additional_signed(
+        &self,
+    ) -> Result<Self::AdditionalSigned, TransactionValidityError> {
+        Ok(())
+    }
+    fn pre_dispatch(
+        self,
+        _who: &Self::AccountId,
+        _call: &Self::Call,
+        _info: &DispatchInfoOf<Self::Call>,
+        _len: usize,
+    ) -> Result<Self::Pre, TransactionValidityError> {
+        Ok(())
+    }
+}
+
+/// Resource limit check.
+#[derive(Derivative, Encode, Decode, TypeInfo)]
+#[derivative(
+    Clone(bound = ""),
+    PartialEq(bound = ""),
+    Debug(bound = ""),
+    Eq(bound = "")
+)]
+#[scale_info(skip_type_params(T))]
+pub struct CheckWeight<T: Config>(pub PhantomDataSendSync<T>);
+
+impl<T: Config> SignedExtension for CheckWeight<T> {
+    const IDENTIFIER: &'static str = "CheckWeight";
+    type AccountId = T::AccountId;
+    type Call = ();
+    type AdditionalSigned = ();
+    type Pre = ();
+    fn additional_signed(
+        &self,
+    ) -> Result<Self::AdditionalSigned, TransactionValidityError> {
+        Ok(())
+    }
+    fn pre_dispatch(
+        self,
+        _who: &Self::AccountId,
+        _call: &Self::Call,
+        _info: &DispatchInfoOf<Self::Call>,
+        _len: usize,
+    ) -> Result<Self::Pre, TransactionValidityError> {
+        Ok(())
+    }
+}
+
+/// Require the transactor pay for themselves and maybe include a tip to gain additional priority
+/// in the queue.
+#[derive(Derivative, Encode, Decode, TypeInfo)]
+#[derivative(
+    Clone(bound = ""),
+    PartialEq(bound = ""),
+    Debug(bound = ""),
+    Eq(bound = ""),
+    Default(bound = "")
+)]
+#[scale_info(skip_type_params(T))]
+pub struct ChargeTransactionPayment<T: Config>(
+    #[codec(compact)] u128,
+    pub PhantomDataSendSync<T>,
+);
+
+impl<T: Config> SignedExtension for ChargeTransactionPayment<T> {
+    const IDENTIFIER: &'static str = "ChargeTransactionPayment";
+    type AccountId = T::AccountId;
+    type Call = ();
+    type AdditionalSigned = ();
+    type Pre = ();
+    fn additional_signed(
+        &self,
+    ) -> Result<Self::AdditionalSigned, TransactionValidityError> {
+        Ok(())
+    }
+    fn pre_dispatch(
+        self,
+        _who: &Self::AccountId,
+        _call: &Self::Call,
+        _info: &DispatchInfoOf<Self::Call>,
+        _len: usize,
+    ) -> Result<Self::Pre, TransactionValidityError> {
+        Ok(())
+    }
+}
+
+/// Require the transactor pay for themselves and maybe include a tip to gain additional priority
+/// in the queue.
+#[derive(Derivative, Encode, Decode, TypeInfo)]
+#[derivative(
+    Clone(bound = ""),
+    PartialEq(bound = ""),
+    Debug(bound = ""),
+    Eq(bound = ""),
+    Default(bound = "")
+)]
+#[scale_info(skip_type_params(T))]
+pub struct ChargeAssetTxPayment<T: Config> {
+    /// The tip for the block author.
+    #[codec(compact)]
+    pub tip: u128,
+    /// The asset with which to pay the tip.
+    pub asset_id: Option<u32>,
+    /// Marker for unused type parameter.
+    pub marker: PhantomDataSendSync<T>,
+}
+
+impl<T: Config> SignedExtension for ChargeAssetTxPayment<T> {
+    const IDENTIFIER: &'static str = "ChargeAssetTxPayment";
+    type AccountId = T::AccountId;
+    type Call = ();
+    type AdditionalSigned = ();
+    type Pre = ();
+    fn additional_signed(
+        &self,
+    ) -> Result<Self::AdditionalSigned, TransactionValidityError> {
+        Ok(())
+    }
+    fn pre_dispatch(
+        self,
+        _who: &Self::AccountId,
+        _call: &Self::Call,
+        _info: &DispatchInfoOf<Self::Call>,
+        _len: usize,
+    ) -> Result<Self::Pre, TransactionValidityError> {
+        Ok(())
+    }
+}
+
+/// Trait for implementing transaction extras for a runtime.
+pub trait SignedExtra<T: Config>: SignedExtension {
+    /// The type the extras.
+    type Extra: SignedExtension + Send + Sync;
+    /// The additional config parameters.
+    type Parameters: Default + Send + Sync;
+
+    /// Creates a new `SignedExtra`.
+    fn new(
+        spec_version: u32,
+        tx_version: u32,
+        nonce: T::Index,
+        genesis_hash: T::Hash,
+        additional_params: Self::Parameters,
+    ) -> Self;
+
+    /// Returns the transaction extra.
+    fn extra(&self) -> Self::Extra;
+}
+
+/// Default `SignedExtra` for substrate runtimes.
+#[derive(Derivative, Encode, Decode, TypeInfo)]
+#[derivative(
+    Clone(bound = ""),
+    PartialEq(bound = ""),
+    Debug(bound = ""),
+    Eq(bound = "")
+)]
+#[scale_info(skip_type_params(T))]
+pub struct DefaultExtraWithTxPayment<T: Config, X> {
+    spec_version: u32,
+    tx_version: u32,
+    nonce: T::Index,
+    genesis_hash: T::Hash,
+    marker: PhantomDataSendSync<X>,
+}
+
+impl<T, X> SignedExtra<T> for DefaultExtraWithTxPayment<T, X>
+where
+    T: Config,
+    X: SignedExtension<AccountId = T::AccountId, Call = ()> + Default,
+{
+    type Extra = (
+        CheckSpecVersion<T>,
+        CheckTxVersion<T>,
+        CheckGenesis<T>,
+        CheckMortality<T>,
+        CheckNonce<T>,
+        CheckWeight<T>,
+        X,
+    );
+    type Parameters = ();
+
+    fn new(
+        spec_version: u32,
+        tx_version: u32,
+        nonce: T::Index,
+        genesis_hash: T::Hash,
+        _params: Self::Parameters,
+    ) -> Self {
+        DefaultExtraWithTxPayment {
+            spec_version,
+            tx_version,
+            nonce,
+            genesis_hash,
+            marker: PhantomDataSendSync::new(),
+        }
+    }
+
+    fn extra(&self) -> Self::Extra {
+        (
+            CheckSpecVersion(PhantomDataSendSync::new(), self.spec_version),
+            CheckTxVersion(PhantomDataSendSync::new(), self.tx_version),
+            CheckGenesis(PhantomDataSendSync::new(), self.genesis_hash),
+            CheckMortality(
+                (Era::Immortal, PhantomDataSendSync::new()),
+                self.genesis_hash,
+            ),
+            CheckNonce(self.nonce),
+            CheckWeight(PhantomDataSendSync::new()),
+            X::default(),
+        )
+    }
+}
+
+impl<T, X: SignedExtension<AccountId = T::AccountId, Call = ()> + Default> SignedExtension
+    for DefaultExtraWithTxPayment<T, X>
+where
+    T: Config,
+    X: SignedExtension,
+{
+    const IDENTIFIER: &'static str = "DefaultExtra";
+    type AccountId = T::AccountId;
+    type Call = ();
+    type AdditionalSigned =
+        <<Self as SignedExtra<T>>::Extra as SignedExtension>::AdditionalSigned;
+    type Pre = ();
+
+    fn additional_signed(
+        &self,
+    ) -> Result<Self::AdditionalSigned, TransactionValidityError> {
+        self.extra().additional_signed()
+    }
+    fn pre_dispatch(
+        self,
+        _who: &Self::AccountId,
+        _call: &Self::Call,
+        _info: &DispatchInfoOf<Self::Call>,
+        _len: usize,
+    ) -> Result<Self::Pre, TransactionValidityError> {
+        Ok(())
+    }
+}
+
+/// A default `SignedExtra` configuration, with [`ChargeTransactionPayment`] for tipping.
+///
+/// Note that this must match the `SignedExtra` type in the target runtime's extrinsic definition.
+pub type DefaultExtra<T> = DefaultExtraWithTxPayment<T, ChargeTransactionPayment<T>>;

subxt/src/extrinsic/mod.rs

@@ -0,0 +1,89 @@
+// 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/>.
+
+//! Create signed or unsigned extrinsics.
+
+mod extra;
+mod signer;
+
+pub use self::{
+    extra::{
+        ChargeAssetTxPayment,
+        ChargeTransactionPayment,
+        CheckGenesis,
+        CheckMortality,
+        CheckNonce,
+        CheckSpecVersion,
+        CheckTxVersion,
+        CheckWeight,
+        DefaultExtra,
+        DefaultExtraWithTxPayment,
+        SignedExtra,
+    },
+    signer::{
+        PairSigner,
+        Signer,
+    },
+};
+
+use sp_runtime::traits::SignedExtension;
+
+use crate::{
+    error::BasicError,
+    rpc::RuntimeVersion,
+    Config,
+    Encoded,
+};
+
+/// UncheckedExtrinsic type.
+pub type UncheckedExtrinsic<T, X> = sp_runtime::generic::UncheckedExtrinsic<
+    <T as Config>::Address,
+    Encoded,
+    <T as Config>::Signature,
+    <X as SignedExtra<T>>::Extra,
+>;
+
+/// SignedPayload type.
+pub type SignedPayload<T, X> =
+    sp_runtime::generic::SignedPayload<Encoded, <X as SignedExtra<T>>::Extra>;
+
+/// Creates a signed extrinsic
+pub async fn create_signed<T, X>(
+    runtime_version: &RuntimeVersion,
+    genesis_hash: T::Hash,
+    nonce: T::Index,
+    call: Encoded,
+    signer: &(dyn Signer<T, X> + Send + Sync),
+    additional_params: X::Parameters,
+) -> Result<UncheckedExtrinsic<T, X>, BasicError>
+where
+    T: Config,
+    X: SignedExtra<T>,
+    <X::Extra as SignedExtension>::AdditionalSigned: Send + Sync,
+{
+    let spec_version = runtime_version.spec_version;
+    let tx_version = runtime_version.transaction_version;
+    let extra = X::new(
+        spec_version,
+        tx_version,
+        nonce,
+        genesis_hash,
+        additional_params,
+    );
+    let payload = SignedPayload::<T, X>::new(call, extra.extra())?;
+    let signed = signer.sign(payload).await?;
+    Ok(signed)
+}

subxt/src/extrinsic/signer.rs

@@ -0,0 +1,132 @@
+// 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/>.
+
+//! A library to **sub**mit e**xt**rinsics to a
+//! [substrate](https://github.com/paritytech/substrate) node via RPC.
+
+use super::{
+    SignedExtra,
+    SignedPayload,
+    UncheckedExtrinsic,
+};
+use crate::Config;
+use codec::Encode;
+use sp_core::Pair;
+use sp_runtime::traits::{
+    IdentifyAccount,
+    SignedExtension,
+    Verify,
+};
+
+/// Extrinsic signer.
+#[async_trait::async_trait]
+pub trait Signer<T: Config, E: SignedExtra<T>> {
+    /// Returns the account id.
+    fn account_id(&self) -> &T::AccountId;
+
+    /// Optionally returns a nonce.
+    fn nonce(&self) -> Option<T::Index>;
+
+    /// Takes an unsigned extrinsic and returns a signed extrinsic.
+    ///
+    /// Some signers may fail, for instance because the hardware on which the keys are located has
+    /// refused the operation.
+    async fn sign(
+        &self,
+        extrinsic: SignedPayload<T, E>,
+    ) -> Result<UncheckedExtrinsic<T, E>, String>;
+}
+
+/// Extrinsic signer using a private key.
+#[derive(Clone, Debug)]
+pub struct PairSigner<T: Config, E, P: Pair> {
+    account_id: T::AccountId,
+    nonce: Option<T::Index>,
+    signer: P,
+    marker: std::marker::PhantomData<E>,
+}
+
+impl<T, E, P> PairSigner<T, E, P>
+where
+    T: Config,
+    E: SignedExtra<T>,
+    T::Signature: From<P::Signature>,
+    <T::Signature as Verify>::Signer:
+        From<P::Public> + IdentifyAccount<AccountId = T::AccountId>,
+    P: Pair,
+{
+    /// Creates a new `Signer` from a `Pair`.
+    pub fn new(signer: P) -> Self {
+        let account_id =
+            <T::Signature as Verify>::Signer::from(signer.public()).into_account();
+        Self {
+            account_id,
+            nonce: None,
+            signer,
+            marker: Default::default(),
+        }
+    }
+
+    /// Sets the nonce to a new value.
+    pub fn set_nonce(&mut self, nonce: T::Index) {
+        self.nonce = Some(nonce);
+    }
+
+    /// Increment the nonce.
+    pub fn increment_nonce(&mut self) {
+        self.nonce = self.nonce.map(|nonce| nonce + 1u32.into());
+    }
+
+    /// Returns the signer.
+    pub fn signer(&self) -> &P {
+        &self.signer
+    }
+}
+
+#[async_trait::async_trait]
+impl<T, E, P> Signer<T, E> for PairSigner<T, E, P>
+where
+    T: Config,
+    E: SignedExtra<T>,
+    T::AccountId: Into<T::Address> + 'static,
+    <<E as SignedExtra<T>>::Extra as SignedExtension>::AdditionalSigned:
+        Send + Sync + 'static,
+    P: Pair + 'static,
+    P::Signature: Into<T::Signature> + 'static,
+{
+    fn account_id(&self) -> &T::AccountId {
+        &self.account_id
+    }
+
+    fn nonce(&self) -> Option<T::Index> {
+        self.nonce
+    }
+
+    async fn sign(
+        &self,
+        extrinsic: SignedPayload<T, E>,
+    ) -> Result<UncheckedExtrinsic<T, E>, String> {
+        let signature = extrinsic.using_encoded(|payload| self.signer.sign(payload));
+        let (call, extra, _) = extrinsic.deconstruct();
+        let extrinsic = UncheckedExtrinsic::<T, E>::new_signed(
+            call,
+            self.account_id.clone().into(),
+            signature.into(),
+            extra,
+        );
+        Ok(extrinsic)
+    }
+}

subxt/src/lib.rs

@@ -0,0 +1,243 @@
+// 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/>.
+
+//! A library to **sub**mit e**xt**rinsics to a
+//! [substrate](https://github.com/paritytech/substrate) node via RPC.
+
+#![deny(
+    bad_style,
+    const_err,
+    improper_ctypes,
+    missing_docs,
+    non_shorthand_field_patterns,
+    no_mangle_generic_items,
+    overflowing_literals,
+    path_statements,
+    patterns_in_fns_without_body,
+    private_in_public,
+    unconditional_recursion,
+    unused_allocation,
+    unused_comparisons,
+    unused_parens,
+    while_true,
+    trivial_casts,
+    trivial_numeric_casts,
+    unused_extern_crates,
+    clippy::all
+)]
+#![allow(clippy::type_complexity)]
+
+pub use frame_metadata::StorageHasher;
+pub use subxt_macro::subxt;
+
+pub use bitvec;
+pub use codec;
+pub use sp_core;
+pub use sp_runtime;
+
+use codec::{
+    Decode,
+    DecodeAll,
+    Encode,
+};
+use core::fmt::Debug;
+use derivative::Derivative;
+
+mod client;
+mod config;
+mod error;
+mod events;
+pub mod extrinsic;
+mod metadata;
+pub mod rpc;
+pub mod storage;
+mod subscription;
+mod transaction;
+
+pub use crate::{
+    client::{
+        Client,
+        ClientBuilder,
+        SubmittableExtrinsic,
+    },
+    config::{
+        AccountData,
+        Config,
+        DefaultConfig,
+    },
+    error::{
+        BasicError,
+        Error,
+        PalletError,
+        TransactionError,
+    },
+    events::{
+        EventsDecoder,
+        RawEvent,
+    },
+    extrinsic::{
+        DefaultExtra,
+        DefaultExtraWithTxPayment,
+        PairSigner,
+        SignedExtra,
+        Signer,
+        UncheckedExtrinsic,
+    },
+    metadata::{
+        Metadata,
+        MetadataError,
+        PalletMetadata,
+    },
+    rpc::{
+        BlockNumber,
+        ReadProof,
+        RpcClient,
+        SystemProperties,
+    },
+    storage::{
+        KeyIter,
+        StorageEntry,
+        StorageEntryKey,
+        StorageMapKey,
+    },
+    subscription::{
+        EventStorageSubscription,
+        EventSubscription,
+        FinalizedEventStorageSubscription,
+    },
+    transaction::{
+        TransactionEvents,
+        TransactionInBlock,
+        TransactionProgress,
+        TransactionStatus,
+    },
+};
+
+/// Call trait.
+pub trait Call: Encode {
+    /// Pallet name.
+    const PALLET: &'static str;
+    /// Function name.
+    const FUNCTION: &'static str;
+
+    /// Returns true if the given pallet and function names match this call.
+    fn is_call(pallet: &str, function: &str) -> bool {
+        Self::PALLET == pallet && Self::FUNCTION == function
+    }
+}
+
+/// Event trait.
+pub trait Event: Decode {
+    /// Pallet name.
+    const PALLET: &'static str;
+    /// Event name.
+    const EVENT: &'static str;
+
+    /// Returns true if the given pallet and event names match this event.
+    fn is_event(pallet: &str, event: &str) -> bool {
+        Self::PALLET == pallet && Self::EVENT == event
+    }
+}
+
+/// Wraps an already encoded byte vector, prevents being encoded as a raw byte vector as part of
+/// the transaction payload
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct Encoded(pub Vec<u8>);
+
+impl codec::Encode for Encoded {
+    fn encode(&self) -> Vec<u8> {
+        self.0.to_owned()
+    }
+}
+
+/// A phase of a block's execution.
+#[derive(Clone, Debug, Eq, PartialEq, Decode, Encode)]
+pub enum Phase {
+    /// Applying an extrinsic.
+    ApplyExtrinsic(u32),
+    /// Finalizing the block.
+    Finalization,
+    /// Initializing the block.
+    Initialization,
+}
+
+/// A wrapper for any type `T` which implement encode/decode in a way compatible with `Vec<u8>`.
+///
+/// [`WrapperKeepOpaque`] stores the type only in its opaque format, aka as a `Vec<u8>`. To
+/// access the real type `T` [`Self::try_decode`] needs to be used.
+#[derive(Derivative, Encode, Decode)]
+#[derivative(
+    Debug(bound = ""),
+    Clone(bound = ""),
+    PartialEq(bound = ""),
+    Eq(bound = ""),
+    Default(bound = "")
+)]
+pub struct WrapperKeepOpaque<T> {
+    data: Vec<u8>,
+    _phantom: PhantomDataSendSync<T>,
+}
+
+impl<T: Decode> WrapperKeepOpaque<T> {
+    /// Try to decode the wrapped type from the inner `data`.
+    ///
+    /// Returns `None` if the decoding failed.
+    pub fn try_decode(&self) -> Option<T> {
+        T::decode_all(&self.data[..]).ok()
+    }
+
+    /// Returns the length of the encoded `T`.
+    pub fn encoded_len(&self) -> usize {
+        self.data.len()
+    }
+
+    /// Returns the encoded data.
+    pub fn encoded(&self) -> &[u8] {
+        &self.data
+    }
+
+    /// Create from the given encoded `data`.
+    pub fn from_encoded(data: Vec<u8>) -> Self {
+        Self {
+            data,
+            _phantom: PhantomDataSendSync::new(),
+        }
+    }
+}
+
+/// A version of [`std::marker::PhantomData`] that is also Send and Sync (which is fine
+/// because regardless of the generic param, it is always possible to Send + Sync this
+/// 0 size type).
+#[derive(Derivative, Encode, Decode, scale_info::TypeInfo)]
+#[derivative(
+    Clone(bound = ""),
+    PartialEq(bound = ""),
+    Debug(bound = ""),
+    Eq(bound = ""),
+    Default(bound = "")
+)]
+#[scale_info(skip_type_params(T))]
+#[doc(hidden)]
+pub struct PhantomDataSendSync<T>(core::marker::PhantomData<T>);
+
+impl<T> PhantomDataSendSync<T> {
+    pub(crate) fn new() -> Self {
+        Self(core::marker::PhantomData)
+    }
+}
+
+unsafe impl<T> Send for PhantomDataSendSync<T> {}
+unsafe impl<T> Sync for PhantomDataSendSync<T> {}

subxt/src/metadata.rs

@@ -0,0 +1,302 @@
+// 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 std::{
+    collections::HashMap,
+    convert::TryFrom,
+};
+
+use codec::Error as CodecError;
+
+use frame_metadata::{
+    PalletConstantMetadata,
+    RuntimeMetadata,
+    RuntimeMetadataLastVersion,
+    RuntimeMetadataPrefixed,
+    StorageEntryMetadata,
+    META_RESERVED,
+};
+
+use crate::{
+    Call,
+    Encoded,
+};
+use scale_info::{
+    form::PortableForm,
+    Type,
+    Variant,
+};
+
+/// Metadata error.
+#[derive(Debug, thiserror::Error)]
+pub enum MetadataError {
+    /// Module is not in metadata.
+    #[error("Pallet {0} not found")]
+    PalletNotFound(String),
+    /// Pallet is not in metadata.
+    #[error("Pallet index {0} not found")]
+    PalletIndexNotFound(u8),
+    /// Call is not in metadata.
+    #[error("Call {0} not found")]
+    CallNotFound(&'static str),
+    /// Event is not in metadata.
+    #[error("Pallet {0}, Event {0} not found")]
+    EventNotFound(u8, u8),
+    /// Event is not in metadata.
+    #[error("Pallet {0}, Error {0} not found")]
+    ErrorNotFound(u8, u8),
+    /// Storage is not in metadata.
+    #[error("Storage {0} not found")]
+    StorageNotFound(&'static str),
+    /// Storage type does not match requested type.
+    #[error("Storage type error")]
+    StorageTypeError,
+    /// Default error.
+    #[error("Failed to decode default: {0}")]
+    DefaultError(CodecError),
+    /// Failure to decode constant value.
+    #[error("Failed to decode constant value: {0}")]
+    ConstantValueError(CodecError),
+    /// Constant is not in metadata.
+    #[error("Constant {0} not found")]
+    ConstantNotFound(&'static str),
+    /// Type is not in metadata.
+    #[error("Type {0} missing from type registry")]
+    TypeNotFound(u32),
+}
+
+/// Runtime metadata.
+#[derive(Clone, Debug)]
+pub struct Metadata {
+    metadata: RuntimeMetadataLastVersion,
+    pallets: HashMap<String, PalletMetadata>,
+    events: HashMap<(u8, u8), EventMetadata>,
+}
+
+impl Metadata {
+    /// Returns a reference to [`PalletMetadata`].
+    pub fn pallet(&self, name: &'static str) -> Result<&PalletMetadata, MetadataError> {
+        self.pallets
+            .get(name)
+            .ok_or_else(|| MetadataError::PalletNotFound(name.to_string()))
+    }
+
+    /// Returns the metadata for the event at the given pallet and event indices.
+    pub fn event(
+        &self,
+        pallet_index: u8,
+        event_index: u8,
+    ) -> Result<&EventMetadata, MetadataError> {
+        let event = self
+            .events
+            .get(&(pallet_index, event_index))
+            .ok_or(MetadataError::EventNotFound(pallet_index, event_index))?;
+        Ok(event)
+    }
+
+    /// Resolve a type definition.
+    pub fn resolve_type(&self, id: u32) -> Option<&Type<PortableForm>> {
+        self.metadata.types.resolve(id)
+    }
+
+    /// Return the runtime metadata.
+    pub fn runtime_metadata(&self) -> &RuntimeMetadataLastVersion {
+        &self.metadata
+    }
+}
+
+/// Metadata for a specific pallet.
+#[derive(Clone, Debug)]
+pub struct PalletMetadata {
+    index: u8,
+    name: String,
+    calls: HashMap<String, u8>,
+    storage: HashMap<String, StorageEntryMetadata<PortableForm>>,
+    constants: HashMap<String, PalletConstantMetadata<PortableForm>>,
+}
+
+impl PalletMetadata {
+    /// Get the name of the pallet.
+    pub fn name(&self) -> &str {
+        &self.name
+    }
+
+    /// Encode a call based on this pallet metadata.
+    pub fn encode_call<C>(&self, call: &C) -> Result<Encoded, MetadataError>
+    where
+        C: Call,
+    {
+        let fn_index = self
+            .calls
+            .get(C::FUNCTION)
+            .ok_or(MetadataError::CallNotFound(C::FUNCTION))?;
+        let mut bytes = vec![self.index, *fn_index];
+        bytes.extend(call.encode());
+        Ok(Encoded(bytes))
+    }
+
+    /// Return [`StorageEntryMetadata`] given some storage key.
+    pub fn storage(
+        &self,
+        key: &'static str,
+    ) -> Result<&StorageEntryMetadata<PortableForm>, MetadataError> {
+        self.storage
+            .get(key)
+            .ok_or(MetadataError::StorageNotFound(key))
+    }
+
+    /// Get a constant's metadata by name.
+    pub fn constant(
+        &self,
+        key: &'static str,
+    ) -> Result<&PalletConstantMetadata<PortableForm>, MetadataError> {
+        self.constants
+            .get(key)
+            .ok_or(MetadataError::ConstantNotFound(key))
+    }
+}
+
+#[derive(Clone, Debug)]
+pub struct EventMetadata {
+    pallet: String,
+    event: String,
+    variant: Variant<PortableForm>,
+}
+
+impl EventMetadata {
+    /// Get the name of the pallet from which the event was emitted.
+    pub fn pallet(&self) -> &str {
+        &self.pallet
+    }
+
+    /// Get the name of the pallet event which was emitted.
+    pub fn event(&self) -> &str {
+        &self.event
+    }
+
+    /// Get the type def variant for the pallet event.
+    pub fn variant(&self) -> &Variant<PortableForm> {
+        &self.variant
+    }
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum InvalidMetadataError {
+    #[error("Invalid prefix")]
+    InvalidPrefix,
+    #[error("Invalid version")]
+    InvalidVersion,
+    #[error("Type {0} missing from type registry")]
+    MissingType(u32),
+    #[error("Type {0} was not a variant/enum type")]
+    TypeDefNotVariant(u32),
+}
+
+impl TryFrom<RuntimeMetadataPrefixed> for Metadata {
+    type Error = InvalidMetadataError;
+
+    fn try_from(metadata: RuntimeMetadataPrefixed) -> Result<Self, Self::Error> {
+        if metadata.0 != META_RESERVED {
+            return Err(InvalidMetadataError::InvalidPrefix)
+        }
+        let metadata = match metadata.1 {
+            RuntimeMetadata::V14(meta) => meta,
+            _ => return Err(InvalidMetadataError::InvalidVersion),
+        };
+
+        let get_type_def_variant = |type_id: u32| {
+            let ty = metadata
+                .types
+                .resolve(type_id)
+                .ok_or(InvalidMetadataError::MissingType(type_id))?;
+            if let scale_info::TypeDef::Variant(var) = ty.type_def() {
+                Ok(var)
+            } else {
+                Err(InvalidMetadataError::TypeDefNotVariant(type_id))
+            }
+        };
+        let pallets = metadata
+            .pallets
+            .iter()
+            .map(|pallet| {
+                let calls = pallet.calls.as_ref().map_or(Ok(HashMap::new()), |call| {
+                    let type_def_variant = get_type_def_variant(call.ty.id())?;
+                    let calls = type_def_variant
+                        .variants()
+                        .iter()
+                        .map(|v| (v.name().clone(), v.index()))
+                        .collect();
+                    Ok(calls)
+                })?;
+
+                let storage = pallet.storage.as_ref().map_or(HashMap::new(), |storage| {
+                    storage
+                        .entries
+                        .iter()
+                        .map(|entry| (entry.name.clone(), entry.clone()))
+                        .collect()
+                });
+
+                let constants = pallet
+                    .constants
+                    .iter()
+                    .map(|constant| (constant.name.clone(), constant.clone()))
+                    .collect();
+
+                let pallet_metadata = PalletMetadata {
+                    index: pallet.index,
+                    name: pallet.name.to_string(),
+                    calls,
+                    storage,
+                    constants,
+                };
+
+                Ok((pallet.name.to_string(), pallet_metadata))
+            })
+            .collect::<Result<_, _>>()?;
+
+        let pallet_events = metadata
+            .pallets
+            .iter()
+            .filter_map(|pallet| {
+                pallet.event.as_ref().map(|event| {
+                    let type_def_variant = get_type_def_variant(event.ty.id())?;
+                    Ok((pallet, type_def_variant))
+                })
+            })
+            .collect::<Result<Vec<_>, _>>()?;
+        let events = pallet_events
+            .iter()
+            .flat_map(|(pallet, type_def_variant)| {
+                type_def_variant.variants().iter().map(move |var| {
+                    let key = (pallet.index, var.index());
+                    let value = EventMetadata {
+                        pallet: pallet.name.clone(),
+                        event: var.name().clone(),
+                        variant: var.clone(),
+                    };
+                    (key, value)
+                })
+            })
+            .collect();
+
+        Ok(Self {
+            metadata,
+            pallets,
+            events,
+        })
+    }
+}

subxt/src/rpc.rs

@@ -0,0 +1,661 @@
+// 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/>.
+
+//! RPC types and client for interacting with a substrate node.
+
+// jsonrpsee subscriptions are interminable.
+// Allows `while let status = subscription.next().await {}`
+// Related: https://github.com/paritytech/subxt/issues/66
+#![allow(irrefutable_let_patterns)]
+
+use std::{
+    collections::HashMap,
+    sync::Arc,
+};
+
+use crate::{
+    error::BasicError,
+    storage::StorageKeyPrefix,
+    subscription::{
+        EventStorageSubscription,
+        FinalizedEventStorageSubscription,
+        SystemEvents,
+    },
+    Config,
+    Metadata,
+};
+use codec::{
+    Decode,
+    Encode,
+};
+use core::{
+    convert::TryInto,
+    marker::PhantomData,
+};
+use frame_metadata::RuntimeMetadataPrefixed;
+use jsonrpsee::{
+    core::{
+        client::{
+            Client,
+            ClientT,
+            Subscription,
+            SubscriptionClientT,
+        },
+        to_json_value,
+        DeserializeOwned,
+        Error as RpcError,
+        JsonValue,
+    },
+    http_client::{
+        HttpClient,
+        HttpClientBuilder,
+    },
+    ws_client::WsClientBuilder,
+};
+use serde::{
+    Deserialize,
+    Serialize,
+};
+use sp_core::{
+    storage::{
+        StorageChangeSet,
+        StorageData,
+        StorageKey,
+    },
+    Bytes,
+    U256,
+};
+use sp_runtime::generic::{
+    Block,
+    SignedBlock,
+};
+
+/// A number type that can be serialized both as a number or a string that encodes a number in a
+/// string.
+///
+/// We allow two representations of the block number as input. Either we deserialize to the type
+/// that is specified in the block type or we attempt to parse given hex value.
+///
+/// The primary motivation for having this type is to avoid overflows when using big integers in
+/// JavaScript (which we consider as an important RPC API consumer).
+#[derive(Copy, Clone, Serialize, Deserialize, Debug, PartialEq)]
+#[serde(untagged)]
+pub enum NumberOrHex {
+    /// The number represented directly.
+    Number(u64),
+    /// Hex representation of the number.
+    Hex(U256),
+}
+
+/// RPC list or value wrapper.
+#[derive(Serialize, Deserialize, Debug, PartialEq)]
+#[serde(untagged)]
+pub enum ListOrValue<T> {
+    /// A list of values of given type.
+    List(Vec<T>),
+    /// A single value of given type.
+    Value(T),
+}
+
+/// Alias for the type of a block returned by `chain_getBlock`
+pub type ChainBlock<T> =
+    SignedBlock<Block<<T as Config>::Header, <T as Config>::Extrinsic>>;
+
+/// Wrapper for NumberOrHex to allow custom From impls
+#[derive(Serialize)]
+pub struct BlockNumber(NumberOrHex);
+
+impl From<NumberOrHex> for BlockNumber {
+    fn from(x: NumberOrHex) -> Self {
+        BlockNumber(x)
+    }
+}
+
+impl From<u32> for BlockNumber {
+    fn from(x: u32) -> Self {
+        NumberOrHex::Number(x.into()).into()
+    }
+}
+
+/// Arbitrary properties defined in the chain spec as a JSON object.
+pub type SystemProperties = serde_json::Map<String, serde_json::Value>;
+
+/// Possible transaction status events.
+///
+/// # Note
+///
+/// This is copied from `sp-transaction-pool` to avoid a dependency on that crate. Therefore it
+/// must be kept compatible with that type from the target substrate version.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub enum SubstrateTransactionStatus<Hash, BlockHash> {
+    /// Transaction is part of the future queue.
+    Future,
+    /// Transaction is part of the ready queue.
+    Ready,
+    /// The transaction has been broadcast to the given peers.
+    Broadcast(Vec<String>),
+    /// Transaction has been included in block with given hash.
+    InBlock(BlockHash),
+    /// The block this transaction was included in has been retracted.
+    Retracted(BlockHash),
+    /// Maximum number of finality watchers has been reached,
+    /// old watchers are being removed.
+    FinalityTimeout(BlockHash),
+    /// Transaction has been finalized by a finality-gadget, e.g GRANDPA
+    Finalized(BlockHash),
+    /// Transaction has been replaced in the pool, by another transaction
+    /// that provides the same tags. (e.g. same (sender, nonce)).
+    Usurped(Hash),
+    /// Transaction has been dropped from the pool because of the limit.
+    Dropped,
+    /// Transaction is no longer valid in the current state.
+    Invalid,
+}
+
+/// This contains the runtime version information necessary to make transactions, as obtained from
+/// the RPC call `state_getRuntimeVersion`,
+#[derive(Debug, Clone, PartialEq, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct RuntimeVersion {
+    /// Version of the runtime specification. A full-node will not attempt to use its native
+    /// runtime in substitute for the on-chain Wasm runtime unless all of `spec_name`,
+    /// `spec_version` and `authoring_version` are the same between Wasm and native.
+    pub spec_version: u32,
+
+    /// All existing dispatches are fully compatible when this number doesn't change. If this
+    /// number changes, then `spec_version` must change, also.
+    ///
+    /// This number must change when an existing dispatchable (module ID, dispatch ID) is changed,
+    /// either through an alteration in its user-level semantics, a parameter
+    /// added/removed/changed, a dispatchable being removed, a module being removed, or a
+    /// dispatchable/module changing its index.
+    ///
+    /// It need *not* change when a new module is added or when a dispatchable is added.
+    pub transaction_version: u32,
+
+    /// The other fields present may vary and aren't necessary for `subxt`; they are preserved in
+    /// this map.
+    #[serde(flatten)]
+    pub other: HashMap<String, serde_json::Value>,
+}
+
+/// Rpc client wrapper.
+/// This is workaround because adding generic types causes the macros to fail.
+#[derive(Clone)]
+pub enum RpcClient {
+    /// JSONRPC client WebSocket transport.
+    WebSocket(Arc<Client>),
+    /// JSONRPC client HTTP transport.
+    // NOTE: Arc because `HttpClient` is not clone.
+    Http(Arc<HttpClient>),
+}
+
+impl RpcClient {
+    /// Create a new [`RpcClient`] from the given URL.
+    ///
+    /// Infers the protocol from the URL, supports:
+    ///     - Websockets (`ws://`, `wss://`)
+    ///     - Http (`http://`, `https://`)
+    pub async fn try_from_url(url: &str) -> Result<Self, RpcError> {
+        if url.starts_with("ws://") || url.starts_with("wss://") {
+            let client = WsClientBuilder::default()
+                .max_notifs_per_subscription(4096)
+                .build(url)
+                .await?;
+            Ok(RpcClient::WebSocket(Arc::new(client)))
+        } else {
+            let client = HttpClientBuilder::default().build(&url)?;
+            Ok(RpcClient::Http(Arc::new(client)))
+        }
+    }
+
+    /// Start a JSON-RPC request.
+    pub async fn request<'a, T: DeserializeOwned + std::fmt::Debug>(
+        &self,
+        method: &str,
+        params: &[JsonValue],
+    ) -> Result<T, RpcError> {
+        let params = Some(params.into());
+        log::debug!("request {}: {:?}", method, params);
+        let data = match self {
+            RpcClient::WebSocket(inner) => inner.request(method, params).await,
+            RpcClient::Http(inner) => inner.request(method, params).await,
+        };
+        log::debug!("response: {:?}", data);
+        data
+    }
+
+    /// Start a JSON-RPC Subscription.
+    pub async fn subscribe<'a, T: DeserializeOwned>(
+        &self,
+        subscribe_method: &str,
+        params: &[JsonValue],
+        unsubscribe_method: &str,
+    ) -> Result<Subscription<T>, RpcError> {
+        let params = Some(params.into());
+        match self {
+            RpcClient::WebSocket(inner) => {
+                inner
+                    .subscribe(subscribe_method, params, unsubscribe_method)
+                    .await
+            }
+            RpcClient::Http(_) => {
+                Err(RpcError::Custom(
+                    "Subscriptions not supported on HTTP transport".to_owned(),
+                ))
+            }
+        }
+    }
+}
+
+impl From<Client> for RpcClient {
+    fn from(client: Client) -> Self {
+        RpcClient::WebSocket(Arc::new(client))
+    }
+}
+
+impl From<Arc<Client>> for RpcClient {
+    fn from(client: Arc<Client>) -> Self {
+        RpcClient::WebSocket(client)
+    }
+}
+
+impl From<HttpClient> for RpcClient {
+    fn from(client: HttpClient) -> Self {
+        RpcClient::Http(Arc::new(client))
+    }
+}
+
+impl From<Arc<HttpClient>> for RpcClient {
+    fn from(client: Arc<HttpClient>) -> Self {
+        RpcClient::Http(client)
+    }
+}
+
+/// ReadProof struct returned by the RPC
+///
+/// # Note
+///
+/// This is copied from `sc-rpc-api` to avoid a dependency on that crate. Therefore it
+/// must be kept compatible with that type from the target substrate version.
+#[derive(Debug, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ReadProof<Hash> {
+    /// Block hash used to generate the proof
+    pub at: Hash,
+    /// A proof used to prove that storage entries are included in the storage trie
+    pub proof: Vec<Bytes>,
+}
+
+/// Client for substrate rpc interfaces
+pub struct Rpc<T: Config> {
+    /// Rpc client for sending requests.
+    pub client: RpcClient,
+    marker: PhantomData<T>,
+}
+
+impl<T: Config> Clone for Rpc<T> {
+    fn clone(&self) -> Self {
+        Self {
+            client: self.client.clone(),
+            marker: PhantomData,
+        }
+    }
+}
+
+impl<T: Config> Rpc<T> {
+    /// Create a new [`Rpc`]
+    pub fn new(client: RpcClient) -> Self {
+        Self {
+            client,
+            marker: PhantomData,
+        }
+    }
+
+    /// Fetch a storage key
+    pub async fn storage(
+        &self,
+        key: &StorageKey,
+        hash: Option<T::Hash>,
+    ) -> Result<Option<StorageData>, BasicError> {
+        let params = &[to_json_value(key)?, to_json_value(hash)?];
+        let data = self.client.request("state_getStorage", params).await?;
+        Ok(data)
+    }
+
+    /// Returns the keys with prefix with pagination support.
+    /// Up to `count` keys will be returned.
+    /// If `start_key` is passed, return next keys in storage in lexicographic order.
+    pub async fn storage_keys_paged(
+        &self,
+        prefix: Option<StorageKeyPrefix>,
+        count: u32,
+        start_key: Option<StorageKey>,
+        hash: Option<T::Hash>,
+    ) -> Result<Vec<StorageKey>, BasicError> {
+        let prefix = prefix.map(|p| p.to_storage_key());
+        let params = &[
+            to_json_value(prefix)?,
+            to_json_value(count)?,
+            to_json_value(start_key)?,
+            to_json_value(hash)?,
+        ];
+        let data = self.client.request("state_getKeysPaged", params).await?;
+        Ok(data)
+    }
+
+    /// Query historical storage entries
+    pub async fn query_storage(
+        &self,
+        keys: Vec<StorageKey>,
+        from: T::Hash,
+        to: Option<T::Hash>,
+    ) -> Result<Vec<StorageChangeSet<T::Hash>>, BasicError> {
+        let params = &[
+            to_json_value(keys)?,
+            to_json_value(from)?,
+            to_json_value(to)?,
+        ];
+        self.client
+            .request("state_queryStorage", params)
+            .await
+            .map_err(Into::into)
+    }
+
+    /// Query historical storage entries
+    pub async fn query_storage_at(
+        &self,
+        keys: &[StorageKey],
+        at: Option<T::Hash>,
+    ) -> Result<Vec<StorageChangeSet<T::Hash>>, BasicError> {
+        let params = &[to_json_value(keys)?, to_json_value(at)?];
+        self.client
+            .request("state_queryStorageAt", params)
+            .await
+            .map_err(Into::into)
+    }
+
+    /// Fetch the genesis hash
+    pub async fn genesis_hash(&self) -> Result<T::Hash, BasicError> {
+        let block_zero = Some(ListOrValue::Value(NumberOrHex::Number(0)));
+        let params = &[to_json_value(block_zero)?];
+        let list_or_value: ListOrValue<Option<T::Hash>> =
+            self.client.request("chain_getBlockHash", params).await?;
+        match list_or_value {
+            ListOrValue::Value(genesis_hash) => {
+                genesis_hash.ok_or_else(|| "Genesis hash not found".into())
+            }
+            ListOrValue::List(_) => Err("Expected a Value, got a List".into()),
+        }
+    }
+
+    /// Fetch the metadata
+    pub async fn metadata(&self) -> Result<Metadata, BasicError> {
+        let bytes: Bytes = self.client.request("state_getMetadata", &[]).await?;
+        let meta: RuntimeMetadataPrefixed = Decode::decode(&mut &bytes[..])?;
+        let metadata: Metadata = meta.try_into()?;
+        Ok(metadata)
+    }
+
+    /// Fetch system properties
+    pub async fn system_properties(&self) -> Result<SystemProperties, BasicError> {
+        Ok(self.client.request("system_properties", &[]).await?)
+    }
+
+    /// Fetch system chain
+    pub async fn system_chain(&self) -> Result<String, BasicError> {
+        Ok(self.client.request("system_chain", &[]).await?)
+    }
+
+    /// Fetch system name
+    pub async fn system_name(&self) -> Result<String, BasicError> {
+        Ok(self.client.request("system_name", &[]).await?)
+    }
+
+    /// Fetch system version
+    pub async fn system_version(&self) -> Result<String, BasicError> {
+        Ok(self.client.request("system_version", &[]).await?)
+    }
+
+    /// Get a header
+    pub async fn header(
+        &self,
+        hash: Option<T::Hash>,
+    ) -> Result<Option<T::Header>, BasicError> {
+        let params = &[to_json_value(hash)?];
+        let header = self.client.request("chain_getHeader", params).await?;
+        Ok(header)
+    }
+
+    /// Get a block hash, returns hash of latest block by default
+    pub async fn block_hash(
+        &self,
+        block_number: Option<BlockNumber>,
+    ) -> Result<Option<T::Hash>, BasicError> {
+        let block_number = block_number.map(ListOrValue::Value);
+        let params = &[to_json_value(block_number)?];
+        let list_or_value = self.client.request("chain_getBlockHash", params).await?;
+        match list_or_value {
+            ListOrValue::Value(hash) => Ok(hash),
+            ListOrValue::List(_) => Err("Expected a Value, got a List".into()),
+        }
+    }
+
+    /// Get a block hash of the latest finalized block
+    pub async fn finalized_head(&self) -> Result<T::Hash, BasicError> {
+        let hash = self.client.request("chain_getFinalizedHead", &[]).await?;
+        Ok(hash)
+    }
+
+    /// Get a Block
+    pub async fn block(
+        &self,
+        hash: Option<T::Hash>,
+    ) -> Result<Option<ChainBlock<T>>, BasicError> {
+        let params = &[to_json_value(hash)?];
+        let block = self.client.request("chain_getBlock", params).await?;
+        Ok(block)
+    }
+
+    /// Get proof of storage entries at a specific block's state.
+    pub async fn read_proof(
+        &self,
+        keys: Vec<StorageKey>,
+        hash: Option<T::Hash>,
+    ) -> Result<ReadProof<T::Hash>, BasicError> {
+        let params = &[to_json_value(keys)?, to_json_value(hash)?];
+        let proof = self.client.request("state_getReadProof", params).await?;
+        Ok(proof)
+    }
+
+    /// Fetch the runtime version
+    pub async fn runtime_version(
+        &self,
+        at: Option<T::Hash>,
+    ) -> Result<RuntimeVersion, BasicError> {
+        let params = &[to_json_value(at)?];
+        let version = self
+            .client
+            .request("state_getRuntimeVersion", params)
+            .await?;
+        Ok(version)
+    }
+
+    /// Subscribe to System Events that are imported into blocks.
+    ///
+    /// *WARNING* these may not be included in the finalized chain, use
+    /// `subscribe_finalized_events` to ensure events are finalized.
+    pub async fn subscribe_events(
+        &self,
+    ) -> Result<EventStorageSubscription<T>, BasicError> {
+        let keys = Some(vec![StorageKey::from(SystemEvents::new())]);
+        let params = &[to_json_value(keys)?];
+
+        let subscription = self
+            .client
+            .subscribe("state_subscribeStorage", params, "state_unsubscribeStorage")
+            .await?;
+        Ok(EventStorageSubscription::Imported(subscription))
+    }
+
+    /// Subscribe to finalized events.
+    pub async fn subscribe_finalized_events(
+        &self,
+    ) -> Result<EventStorageSubscription<T>, BasicError> {
+        Ok(EventStorageSubscription::Finalized(
+            FinalizedEventStorageSubscription::new(
+                self.clone(),
+                self.subscribe_finalized_blocks().await?,
+            ),
+        ))
+    }
+
+    /// Subscribe to blocks.
+    pub async fn subscribe_blocks(&self) -> Result<Subscription<T::Header>, BasicError> {
+        let subscription = self
+            .client
+            .subscribe("chain_subscribeNewHeads", &[], "chain_unsubscribeNewHeads")
+            .await?;
+
+        Ok(subscription)
+    }
+
+    /// Subscribe to finalized blocks.
+    pub async fn subscribe_finalized_blocks(
+        &self,
+    ) -> Result<Subscription<T::Header>, BasicError> {
+        let subscription = self
+            .client
+            .subscribe(
+                "chain_subscribeFinalizedHeads",
+                &[],
+                "chain_unsubscribeFinalizedHeads",
+            )
+            .await?;
+        Ok(subscription)
+    }
+
+    /// Create and submit an extrinsic and return corresponding Hash if successful
+    pub async fn submit_extrinsic<X: Encode>(
+        &self,
+        extrinsic: X,
+    ) -> Result<T::Hash, BasicError> {
+        let bytes: Bytes = extrinsic.encode().into();
+        let params = &[to_json_value(bytes)?];
+        let xt_hash = self
+            .client
+            .request("author_submitExtrinsic", params)
+            .await?;
+        Ok(xt_hash)
+    }
+
+    /// Create and submit an extrinsic and return a subscription to the events triggered.
+    pub async fn watch_extrinsic<X: Encode>(
+        &self,
+        extrinsic: X,
+    ) -> Result<Subscription<SubstrateTransactionStatus<T::Hash, T::Hash>>, BasicError>
+    {
+        let bytes: Bytes = extrinsic.encode().into();
+        let params = &[to_json_value(bytes)?];
+        let subscription = self
+            .client
+            .subscribe(
+                "author_submitAndWatchExtrinsic",
+                params,
+                "author_unwatchExtrinsic",
+            )
+            .await?;
+        Ok(subscription)
+    }
+
+    /// Insert a key into the keystore.
+    pub async fn insert_key(
+        &self,
+        key_type: String,
+        suri: String,
+        public: Bytes,
+    ) -> Result<(), BasicError> {
+        let params = &[
+            to_json_value(key_type)?,
+            to_json_value(suri)?,
+            to_json_value(public)?,
+        ];
+        self.client.request("author_insertKey", params).await?;
+        Ok(())
+    }
+
+    /// Generate new session keys and returns the corresponding public keys.
+    pub async fn rotate_keys(&self) -> Result<Bytes, BasicError> {
+        Ok(self.client.request("author_rotateKeys", &[]).await?)
+    }
+
+    /// Checks if the keystore has private keys for the given session public keys.
+    ///
+    /// `session_keys` is the SCALE encoded session keys object from the runtime.
+    ///
+    /// Returns `true` iff all private keys could be found.
+    pub async fn has_session_keys(
+        &self,
+        session_keys: Bytes,
+    ) -> Result<bool, BasicError> {
+        let params = &[to_json_value(session_keys)?];
+        Ok(self.client.request("author_hasSessionKeys", params).await?)
+    }
+
+    /// Checks if the keystore has private keys for the given public key and key type.
+    ///
+    /// Returns `true` if a private key could be found.
+    pub async fn has_key(
+        &self,
+        public_key: Bytes,
+        key_type: String,
+    ) -> Result<bool, BasicError> {
+        let params = &[to_json_value(public_key)?, to_json_value(key_type)?];
+        Ok(self.client.request("author_hasKey", params).await?)
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    #[test]
+    fn test_deser_runtime_version() {
+        let val: RuntimeVersion = serde_json::from_str(
+            r#"{
+            "specVersion": 123,
+            "transactionVersion": 456,
+            "foo": true,
+            "wibble": [1,2,3]
+        }"#,
+        )
+        .expect("deserializing failed");
+
+        let mut m = std::collections::HashMap::new();
+        m.insert("foo".to_owned(), serde_json::json!(true));
+        m.insert("wibble".to_owned(), serde_json::json!([1, 2, 3]));
+
+        assert_eq!(
+            val,
+            RuntimeVersion {
+                spec_version: 123,
+                transaction_version: 456,
+                other: m
+            }
+        );
+    }
+}

subxt/src/storage.rs

@@ -0,0 +1,306 @@
+// 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/>.
+
+//! For querying runtime storage.
+
+use codec::{
+    Decode,
+    Encode,
+};
+use sp_core::storage::{
+    StorageChangeSet,
+    StorageData,
+    StorageKey,
+};
+pub use sp_runtime::traits::SignedExtension;
+pub use sp_version::RuntimeVersion;
+use std::marker::PhantomData;
+
+use crate::{
+    error::BasicError,
+    metadata::{
+        Metadata,
+        MetadataError,
+    },
+    rpc::Rpc,
+    Config,
+    StorageHasher,
+};
+
+/// Storage entry trait.
+pub trait StorageEntry {
+    /// Pallet name.
+    const PALLET: &'static str;
+    /// Storage name.
+    const STORAGE: &'static str;
+    /// Type of the storage entry value.
+    type Value: Decode;
+    /// Get the key data for the storage.
+    fn key(&self) -> StorageEntryKey;
+}
+
+/// The prefix of the key to a [`StorageEntry`]
+pub struct StorageKeyPrefix(Vec<u8>);
+
+impl StorageKeyPrefix {
+    /// Create the storage key prefix for a [`StorageEntry`]
+    pub fn new<T: StorageEntry>() -> Self {
+        let mut bytes = sp_core::twox_128(T::PALLET.as_bytes()).to_vec();
+        bytes.extend(&sp_core::twox_128(T::STORAGE.as_bytes())[..]);
+        Self(bytes)
+    }
+
+    /// Convert the prefix into a [`StorageKey`]
+    pub fn to_storage_key(self) -> StorageKey {
+        StorageKey(self.0)
+    }
+}
+
+/// Storage key.
+pub enum StorageEntryKey {
+    /// Plain key.
+    Plain,
+    /// Map key(s).
+    Map(Vec<StorageMapKey>),
+}
+
+impl StorageEntryKey {
+    /// Construct the final [`sp_core::storage::StorageKey`] for the storage entry.
+    pub fn final_key(&self, prefix: StorageKeyPrefix) -> sp_core::storage::StorageKey {
+        let mut bytes = prefix.0;
+        if let Self::Map(map_keys) = self {
+            for map_key in map_keys {
+                bytes.extend(Self::hash(&map_key.hasher, &map_key.value))
+            }
+        }
+        sp_core::storage::StorageKey(bytes)
+    }
+
+    fn hash(hasher: &StorageHasher, bytes: &[u8]) -> Vec<u8> {
+        match hasher {
+            StorageHasher::Identity => bytes.to_vec(),
+            StorageHasher::Blake2_128 => sp_core::blake2_128(bytes).to_vec(),
+            StorageHasher::Blake2_128Concat => {
+                // copied from substrate Blake2_128Concat::hash since StorageHasher is not public
+                sp_core::blake2_128(bytes)
+                    .iter()
+                    .chain(bytes)
+                    .cloned()
+                    .collect()
+            }
+            StorageHasher::Blake2_256 => sp_core::blake2_256(bytes).to_vec(),
+            StorageHasher::Twox128 => sp_core::twox_128(bytes).to_vec(),
+            StorageHasher::Twox256 => sp_core::twox_256(bytes).to_vec(),
+            StorageHasher::Twox64Concat => {
+                sp_core::twox_64(bytes)
+                    .iter()
+                    .chain(bytes)
+                    .cloned()
+                    .collect()
+            }
+        }
+    }
+}
+
+/// Storage key for a Map.
+pub struct StorageMapKey {
+    value: Vec<u8>,
+    hasher: StorageHasher,
+}
+
+impl StorageMapKey {
+    /// Create a new [`StorageMapKey`] with the encoded data and the hasher.
+    pub fn new<T: Encode>(value: &T, hasher: StorageHasher) -> Self {
+        Self {
+            value: value.encode(),
+            hasher,
+        }
+    }
+}
+
+/// Client for querying runtime storage.
+pub struct StorageClient<'a, T: Config> {
+    rpc: &'a Rpc<T>,
+    metadata: &'a Metadata,
+    iter_page_size: u32,
+}
+
+impl<'a, T: Config> Clone for StorageClient<'a, T> {
+    fn clone(&self) -> Self {
+        Self {
+            rpc: self.rpc,
+            metadata: self.metadata,
+            iter_page_size: self.iter_page_size,
+        }
+    }
+}
+
+impl<'a, T: Config> StorageClient<'a, T> {
+    /// Create a new [`StorageClient`]
+    pub fn new(rpc: &'a Rpc<T>, metadata: &'a Metadata, iter_page_size: u32) -> Self {
+        Self {
+            rpc,
+            metadata,
+            iter_page_size,
+        }
+    }
+
+    /// Fetch the value under an unhashed storage key
+    pub async fn fetch_unhashed<V: Decode>(
+        &self,
+        key: StorageKey,
+        hash: Option<T::Hash>,
+    ) -> Result<Option<V>, BasicError> {
+        if let Some(data) = self.rpc.storage(&key, hash).await? {
+            Ok(Some(Decode::decode(&mut &data.0[..])?))
+        } else {
+            Ok(None)
+        }
+    }
+
+    /// Fetch the raw encoded value under the raw storage key.
+    pub async fn fetch_raw(
+        &self,
+        key: StorageKey,
+        hash: Option<T::Hash>,
+    ) -> Result<Option<StorageData>, BasicError> {
+        self.rpc.storage(&key, hash).await
+    }
+
+    /// Fetch a StorageKey with an optional block hash.
+    pub async fn fetch<F: StorageEntry>(
+        &self,
+        store: &F,
+        hash: Option<T::Hash>,
+    ) -> Result<Option<F::Value>, BasicError> {
+        let prefix = StorageKeyPrefix::new::<F>();
+        let key = store.key().final_key(prefix);
+        self.fetch_unhashed::<F::Value>(key, hash).await
+    }
+
+    /// Fetch a StorageKey that has a default value with an optional block hash.
+    pub async fn fetch_or_default<F: StorageEntry>(
+        &self,
+        store: &F,
+        hash: Option<T::Hash>,
+    ) -> Result<F::Value, BasicError> {
+        if let Some(data) = self.fetch(store, hash).await? {
+            Ok(data)
+        } else {
+            let pallet_metadata = self.metadata.pallet(F::PALLET)?;
+            let storage_metadata = pallet_metadata.storage(F::STORAGE)?;
+            let default = Decode::decode(&mut &storage_metadata.default[..])
+                .map_err(MetadataError::DefaultError)?;
+            Ok(default)
+        }
+    }
+
+    /// Query historical storage entries
+    pub async fn query_storage(
+        &self,
+        keys: Vec<StorageKey>,
+        from: T::Hash,
+        to: Option<T::Hash>,
+    ) -> Result<Vec<StorageChangeSet<T::Hash>>, BasicError> {
+        self.rpc.query_storage(keys, from, to).await
+    }
+
+    /// Fetch up to `count` keys for a storage map in lexicographic order.
+    ///
+    /// Supports pagination by passing a value to `start_key`.
+    pub async fn fetch_keys<F: StorageEntry>(
+        &self,
+        count: u32,
+        start_key: Option<StorageKey>,
+        hash: Option<T::Hash>,
+    ) -> Result<Vec<StorageKey>, BasicError> {
+        let prefix = StorageKeyPrefix::new::<F>();
+        let keys = self
+            .rpc
+            .storage_keys_paged(Some(prefix), count, start_key, hash)
+            .await?;
+        Ok(keys)
+    }
+
+    /// Returns an iterator of key value pairs.
+    pub async fn iter<F: StorageEntry>(
+        &self,
+        hash: Option<T::Hash>,
+    ) -> Result<KeyIter<'a, T, F>, BasicError> {
+        let hash = if let Some(hash) = hash {
+            hash
+        } else {
+            self.rpc
+                .block_hash(None)
+                .await?
+                .expect("didn't pass a block number; qed")
+        };
+        Ok(KeyIter {
+            client: self.clone(),
+            hash,
+            count: self.iter_page_size,
+            start_key: None,
+            buffer: Default::default(),
+            _marker: PhantomData,
+        })
+    }
+}
+
+/// Iterates over key value pairs in a map.
+pub struct KeyIter<'a, T: Config, F: StorageEntry> {
+    client: StorageClient<'a, T>,
+    _marker: PhantomData<F>,
+    count: u32,
+    hash: T::Hash,
+    start_key: Option<StorageKey>,
+    buffer: Vec<(StorageKey, StorageData)>,
+}
+
+impl<'a, T: Config, F: StorageEntry> KeyIter<'a, T, F> {
+    /// Returns the next key value pair from a map.
+    pub async fn next(&mut self) -> Result<Option<(StorageKey, F::Value)>, BasicError> {
+        loop {
+            if let Some((k, v)) = self.buffer.pop() {
+                return Ok(Some((k, Decode::decode(&mut &v.0[..])?)))
+            } else {
+                let keys = self
+                    .client
+                    .fetch_keys::<F>(self.count, self.start_key.take(), Some(self.hash))
+                    .await?;
+
+                if keys.is_empty() {
+                    return Ok(None)
+                }
+
+                self.start_key = keys.last().cloned();
+
+                let change_sets = self
+                    .client
+                    .rpc
+                    .query_storage_at(&keys, Some(self.hash))
+                    .await?;
+                for change_set in change_sets {
+                    for (k, v) in change_set.changes {
+                        if let Some(v) = v {
+                            self.buffer.push((k, v));
+                        }
+                    }
+                }
+                debug_assert_eq!(self.buffer.len(), keys.len());
+            }
+        }
+    }
+}

subxt/src/subscription.rs

@@ -0,0 +1,358 @@
+// 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::{
+    error::BasicError,
+    events::{
+        EventsDecoder,
+        RawEvent,
+    },
+    rpc::Rpc,
+    Config,
+    Event,
+    Phase,
+};
+use jsonrpsee::core::{
+    client::Subscription,
+    DeserializeOwned,
+};
+use sp_core::{
+    storage::{
+        StorageChangeSet,
+        StorageKey,
+    },
+    twox_128,
+};
+use sp_runtime::traits::Header;
+use std::collections::VecDeque;
+
+/// Event subscription simplifies filtering a storage change set stream for
+/// events of interest.
+pub struct EventSubscription<'a, T: Config> {
+    block_reader: BlockReader<'a, T>,
+    block: Option<T::Hash>,
+    extrinsic: Option<usize>,
+    event: Option<(&'static str, &'static str)>,
+    events: VecDeque<RawEvent>,
+    finished: bool,
+}
+
+enum BlockReader<'a, T: Config> {
+    Decoder {
+        subscription: EventStorageSubscription<T>,
+        decoder: &'a EventsDecoder<T>,
+    },
+    /// Mock event listener for unit tests
+    #[cfg(test)]
+    Mock(Box<dyn Iterator<Item = (T::Hash, Result<Vec<(Phase, RawEvent)>, BasicError>)>>),
+}
+
+impl<'a, T: Config> BlockReader<'a, T> {
+    async fn next(
+        &mut self,
+    ) -> Option<(T::Hash, Result<Vec<(Phase, RawEvent)>, BasicError>)> {
+        match self {
+            BlockReader::Decoder {
+                subscription,
+                decoder,
+            } => {
+                let change_set = subscription.next().await?;
+                let events: Result<Vec<_>, _> = change_set
+                    .changes
+                    .into_iter()
+                    .filter_map(|(_key, change)| {
+                        Some(decoder.decode_events(&mut change?.0.as_slice()))
+                    })
+                    .collect();
+
+                let flattened_events = events.map(|x| x.into_iter().flatten().collect());
+                Some((change_set.block, flattened_events))
+            }
+            #[cfg(test)]
+            BlockReader::Mock(it) => it.next(),
+        }
+    }
+}
+
+impl<'a, T: Config> EventSubscription<'a, T> {
+    /// Creates a new event subscription.
+    pub fn new(
+        subscription: EventStorageSubscription<T>,
+        decoder: &'a EventsDecoder<T>,
+    ) -> Self {
+        Self {
+            block_reader: BlockReader::Decoder {
+                subscription,
+                decoder,
+            },
+            block: None,
+            extrinsic: None,
+            event: None,
+            events: Default::default(),
+            finished: false,
+        }
+    }
+
+    /// Only returns events contained in the block with the given hash.
+    pub fn filter_block(&mut self, block: T::Hash) {
+        self.block = Some(block);
+    }
+
+    /// Only returns events from block emitted by extrinsic with index.
+    pub fn filter_extrinsic(&mut self, block: T::Hash, ext_index: usize) {
+        self.block = Some(block);
+        self.extrinsic = Some(ext_index);
+    }
+
+    /// Filters events by type.
+    pub fn filter_event<Ev: Event>(&mut self) {
+        self.event = Some((Ev::PALLET, Ev::EVENT));
+    }
+
+    /// Gets the next event.
+    pub async fn next(&mut self) -> Option<Result<RawEvent, BasicError>> {
+        loop {
+            if let Some(raw_event) = self.events.pop_front() {
+                return Some(Ok(raw_event))
+            }
+            if self.finished {
+                return None
+            }
+            // always return None if subscription has closed
+            let (received_hash, events) = self.block_reader.next().await?;
+            if let Some(hash) = self.block.as_ref() {
+                if &received_hash == hash {
+                    self.finished = true;
+                } else {
+                    continue
+                }
+            }
+
+            match events {
+                Err(err) => return Some(Err(err)),
+                Ok(raw_events) => {
+                    for (phase, raw) in raw_events {
+                        if let Some(ext_index) = self.extrinsic {
+                            if !matches!(phase, Phase::ApplyExtrinsic(i) if i as usize == ext_index)
+                            {
+                                continue
+                            }
+                        }
+                        if let Some((module, variant)) = self.event {
+                            if raw.pallet != module || raw.variant != variant {
+                                continue
+                            }
+                        }
+                        self.events.push_back(raw);
+                    }
+                }
+            }
+        }
+    }
+}
+
+pub(crate) struct SystemEvents(StorageKey);
+
+impl SystemEvents {
+    pub(crate) fn new() -> Self {
+        let mut storage_key = twox_128(b"System").to_vec();
+        storage_key.extend(twox_128(b"Events").to_vec());
+        log::debug!("Events storage key {:?}", hex::encode(&storage_key));
+        Self(StorageKey(storage_key))
+    }
+}
+
+impl From<SystemEvents> for StorageKey {
+    fn from(key: SystemEvents) -> Self {
+        key.0
+    }
+}
+
+/// Event subscription to only fetch finalized storage changes.
+pub struct FinalizedEventStorageSubscription<T: Config> {
+    rpc: Rpc<T>,
+    subscription: Subscription<T::Header>,
+    storage_changes: VecDeque<StorageChangeSet<T::Hash>>,
+    storage_key: StorageKey,
+}
+
+impl<T: Config> FinalizedEventStorageSubscription<T> {
+    /// Creates a new finalized event storage subscription.
+    pub fn new(rpc: Rpc<T>, subscription: Subscription<T::Header>) -> Self {
+        Self {
+            rpc,
+            subscription,
+            storage_changes: Default::default(),
+            storage_key: SystemEvents::new().into(),
+        }
+    }
+
+    /// Gets the next change_set.
+    pub async fn next(&mut self) -> Option<StorageChangeSet<T::Hash>> {
+        loop {
+            if let Some(storage_change) = self.storage_changes.pop_front() {
+                return Some(storage_change)
+            }
+            let header: T::Header =
+                read_subscription_response("HeaderSubscription", &mut self.subscription)
+                    .await?;
+            self.storage_changes.extend(
+                self.rpc
+                    .query_storage_at(&[self.storage_key.clone()], Some(header.hash()))
+                    .await
+                    .ok()?,
+            );
+        }
+    }
+}
+
+/// Wrapper over imported and finalized event subscriptions.
+pub enum EventStorageSubscription<T: Config> {
+    /// Events that are InBlock
+    Imported(Subscription<StorageChangeSet<T::Hash>>),
+    /// Events that are Finalized
+    Finalized(FinalizedEventStorageSubscription<T>),
+}
+
+impl<T: Config> EventStorageSubscription<T> {
+    /// Gets the next change_set from the subscription.
+    pub async fn next(&mut self) -> Option<StorageChangeSet<T::Hash>> {
+        match self {
+            Self::Imported(event_sub) => {
+                read_subscription_response("StorageChangeSetSubscription", event_sub)
+                    .await
+            }
+            Self::Finalized(event_sub) => event_sub.next().await,
+        }
+    }
+}
+
+async fn read_subscription_response<T>(
+    sub_name: &str,
+    sub: &mut Subscription<T>,
+) -> Option<T>
+where
+    T: DeserializeOwned,
+{
+    match sub.next().await {
+        Some(Ok(next)) => Some(next),
+        Some(Err(e)) => {
+            log::error!("Subscription {} failed: {:?} dropping", sub_name, e);
+            None
+        }
+        None => None,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::DefaultConfig;
+    use sp_core::H256;
+
+    fn named_event(event_name: &str) -> RawEvent {
+        RawEvent {
+            data: sp_core::Bytes::from(Vec::new()),
+            pallet: event_name.to_string(),
+            variant: event_name.to_string(),
+            pallet_index: 0,
+            variant_index: 0,
+        }
+    }
+
+    #[async_std::test]
+    /// test that filters work correctly, and are independent of each other
+    async fn test_filters() {
+        let mut events = vec![];
+        // create all events
+        for block_hash in [H256::from([0; 32]), H256::from([1; 32])] {
+            for phase in [
+                Phase::Initialization,
+                Phase::ApplyExtrinsic(0),
+                Phase::ApplyExtrinsic(1),
+                Phase::Finalization,
+            ] {
+                for event in [named_event("a"), named_event("b")] {
+                    events.push((block_hash, phase.clone(), event))
+                }
+            }
+        }
+        // set variant index so we can uniquely identify the event
+        events.iter_mut().enumerate().for_each(|(idx, event)| {
+            event.2.variant_index = idx as u8;
+        });
+
+        let half_len = events.len() / 2;
+
+        for block_filter in [None, Some(H256::from([1; 32]))] {
+            for extrinsic_filter in [None, Some(1)] {
+                for event_filter in [None, Some(("b", "b"))] {
+                    let mut subscription: EventSubscription<DefaultConfig> =
+                        EventSubscription {
+                            block_reader: BlockReader::Mock(Box::new(
+                                vec![
+                                    (
+                                        events[0].0,
+                                        Ok(events
+                                            .iter()
+                                            .take(half_len)
+                                            .map(|(_, phase, event)| {
+                                                (phase.clone(), event.clone())
+                                            })
+                                            .collect()),
+                                    ),
+                                    (
+                                        events[half_len].0,
+                                        Ok(events
+                                            .iter()
+                                            .skip(half_len)
+                                            .map(|(_, phase, event)| {
+                                                (phase.clone(), event.clone())
+                                            })
+                                            .collect()),
+                                    ),
+                                ]
+                                .into_iter(),
+                            )),
+                            block: block_filter,
+                            extrinsic: extrinsic_filter,
+                            event: event_filter,
+                            events: Default::default(),
+                            finished: false,
+                        };
+                    let mut expected_events = events.clone();
+                    if let Some(hash) = block_filter {
+                        expected_events.retain(|(h, _, _)| h == &hash);
+                    }
+                    if let Some(idx) = extrinsic_filter {
+                        expected_events.retain(|(_, phase, _)| matches!(phase, Phase::ApplyExtrinsic(i) if *i as usize == idx));
+                    }
+                    if let Some(name) = event_filter {
+                        expected_events.retain(|(_, _, event)| event.pallet == name.0);
+                    }
+
+                    for expected_event in expected_events {
+                        assert_eq!(
+                            subscription.next().await.unwrap().unwrap(),
+                            expected_event.2
+                        );
+                    }
+                    assert!(subscription.next().await.is_none());
+                }
+            }
+        }
+    }
+}

subxt/src/transaction.rs

@@ -0,0 +1,499 @@
+// 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 std::task::Poll;
+
+use crate::PhantomDataSendSync;
+use codec::Decode;
+use sp_core::storage::StorageKey;
+use sp_runtime::traits::Hash;
+pub use sp_runtime::traits::SignedExtension;
+pub use sp_version::RuntimeVersion;
+
+use crate::{
+    client::Client,
+    error::{
+        BasicError,
+        Error,
+        RuntimeError,
+        TransactionError,
+    },
+    rpc::SubstrateTransactionStatus,
+    subscription::SystemEvents,
+    Config,
+    Phase,
+};
+use derivative::Derivative;
+use futures::{
+    Stream,
+    StreamExt,
+};
+use jsonrpsee::core::{
+    client::Subscription as RpcSubscription,
+    Error as RpcError,
+};
+
+/// This struct represents a subscription to the progress of some transaction, and is
+/// returned from [`crate::SubmittableExtrinsic::sign_and_submit_then_watch()`].
+#[derive(Derivative)]
+#[derivative(Debug(bound = ""))]
+pub struct TransactionProgress<'client, T: Config, E: Decode> {
+    sub: Option<RpcSubscription<SubstrateTransactionStatus<T::Hash, T::Hash>>>,
+    ext_hash: T::Hash,
+    client: &'client Client<T>,
+    _error: PhantomDataSendSync<E>,
+}
+
+// The above type is not `Unpin` by default unless the generic param `T` is,
+// so we manually make it clear that Unpin is actually fine regardless of `T`
+// (we don't care if this moves around in memory while it's "pinned").
+impl<'client, T: Config, E: Decode> Unpin for TransactionProgress<'client, T, E> {}
+
+impl<'client, T: Config, E: Decode> TransactionProgress<'client, T, E> {
+    /// Instantiate a new [`TransactionProgress`] from a custom subscription.
+    pub fn new(
+        sub: RpcSubscription<SubstrateTransactionStatus<T::Hash, T::Hash>>,
+        client: &'client Client<T>,
+        ext_hash: T::Hash,
+    ) -> Self {
+        Self {
+            sub: Some(sub),
+            client,
+            ext_hash,
+            _error: PhantomDataSendSync::new(),
+        }
+    }
+
+    /// Return the next transaction status when it's emitted. This just delegates to the
+    /// [`futures::Stream`] implementation for [`TransactionProgress`], but allows you to
+    /// avoid importing that trait if you don't otherwise need it.
+    pub async fn next_item(
+        &mut self,
+    ) -> Option<Result<TransactionStatus<'client, T, E>, BasicError>> {
+        self.next().await
+    }
+
+    /// Wait for the transaction to be in a block (but not necessarily finalized), and return
+    /// an [`TransactionInBlock`] instance when this happens, or an error if there was a problem
+    /// waiting for this to happen.
+    ///
+    /// **Note:** consumes `self`. If you'd like to perform multiple actions as the state of the
+    /// transaction progresses, use [`TransactionProgress::next_item()`] instead.
+    ///
+    /// **Note:** transaction statuses like `Invalid` and `Usurped` are ignored, because while they
+    /// may well indicate with some probability that the transaction will not make it into a block,
+    /// there is no guarantee that this is true. Thus, we prefer to "play it safe" here. Use the lower
+    /// level [`TransactionProgress::next_item()`] API if you'd like to handle these statuses yourself.
+    pub async fn wait_for_in_block(
+        mut self,
+    ) -> Result<TransactionInBlock<'client, T, E>, BasicError> {
+        while let Some(status) = self.next_item().await {
+            match status? {
+                // Finalized or otherwise in a block! Return.
+                TransactionStatus::InBlock(s) | TransactionStatus::Finalized(s) => {
+                    return Ok(s)
+                }
+                // Error scenarios; return the error.
+                TransactionStatus::FinalityTimeout(_) => {
+                    return Err(TransactionError::FinalitySubscriptionTimeout.into())
+                }
+                // Ignore anything else and wait for next status event:
+                _ => continue,
+            }
+        }
+        Err(RpcError::Custom("RPC subscription dropped".into()).into())
+    }
+
+    /// Wait for the transaction to be finalized, and return a [`TransactionInBlock`]
+    /// instance when it is, or an error if there was a problem waiting for finalization.
+    ///
+    /// **Note:** consumes `self`. If you'd like to perform multiple actions as the state of the
+    /// transaction progresses, use [`TransactionProgress::next_item()`] instead.
+    ///
+    /// **Note:** transaction statuses like `Invalid` and `Usurped` are ignored, because while they
+    /// may well indicate with some probability that the transaction will not make it into a block,
+    /// there is no guarantee that this is true. Thus, we prefer to "play it safe" here. Use the lower
+    /// level [`TransactionProgress::next_item()`] API if you'd like to handle these statuses yourself.
+    pub async fn wait_for_finalized(
+        mut self,
+    ) -> Result<TransactionInBlock<'client, T, E>, BasicError> {
+        while let Some(status) = self.next_item().await {
+            match status? {
+                // Finalized! Return.
+                TransactionStatus::Finalized(s) => return Ok(s),
+                // Error scenarios; return the error.
+                TransactionStatus::FinalityTimeout(_) => {
+                    return Err(TransactionError::FinalitySubscriptionTimeout.into())
+                }
+                // Ignore and wait for next status event:
+                _ => continue,
+            }
+        }
+        Err(RpcError::Custom("RPC subscription dropped".into()).into())
+    }
+
+    /// Wait for the transaction to be finalized, and for the transaction events to indicate
+    /// that the transaction was successful. Returns the events associated with the transaction,
+    /// as well as a couple of other details (block hash and extrinsic hash).
+    ///
+    /// **Note:** consumes self. If you'd like to perform multiple actions as progress is made,
+    /// use [`TransactionProgress::next_item()`] instead.
+    ///
+    /// **Note:** transaction statuses like `Invalid` and `Usurped` are ignored, because while they
+    /// may well indicate with some probability that the transaction will not make it into a block,
+    /// there is no guarantee that this is true. Thus, we prefer to "play it safe" here. Use the lower
+    /// level [`TransactionProgress::next_item()`] API if you'd like to handle these statuses yourself.
+    pub async fn wait_for_finalized_success(
+        self,
+    ) -> Result<TransactionEvents<T>, Error<E>> {
+        let evs = self.wait_for_finalized().await?.wait_for_success().await?;
+        Ok(evs)
+    }
+}
+
+impl<'client, T: Config, E: Decode> Stream for TransactionProgress<'client, T, E> {
+    type Item = Result<TransactionStatus<'client, T, E>, BasicError>;
+
+    fn poll_next(
+        mut self: std::pin::Pin<&mut Self>,
+        cx: &mut std::task::Context<'_>,
+    ) -> std::task::Poll<Option<Self::Item>> {
+        let sub = match self.sub.as_mut() {
+            Some(sub) => sub,
+            None => return Poll::Ready(None),
+        };
+
+        sub.poll_next_unpin(cx)
+            .map_err(|e| e.into())
+            .map_ok(|status| {
+                match status {
+                    SubstrateTransactionStatus::Future => TransactionStatus::Future,
+                    SubstrateTransactionStatus::Ready => TransactionStatus::Ready,
+                    SubstrateTransactionStatus::Broadcast(peers) => {
+                        TransactionStatus::Broadcast(peers)
+                    }
+                    SubstrateTransactionStatus::InBlock(hash) => {
+                        TransactionStatus::InBlock(TransactionInBlock::new(
+                            hash,
+                            self.ext_hash,
+                            self.client,
+                        ))
+                    }
+                    SubstrateTransactionStatus::Retracted(hash) => {
+                        TransactionStatus::Retracted(hash)
+                    }
+                    SubstrateTransactionStatus::Usurped(hash) => {
+                        TransactionStatus::Usurped(hash)
+                    }
+                    SubstrateTransactionStatus::Dropped => TransactionStatus::Dropped,
+                    SubstrateTransactionStatus::Invalid => TransactionStatus::Invalid,
+                    // Only the following statuses are actually considered "final" (see the substrate
+                    // docs on `TransactionStatus`). Basically, either the transaction makes it into a
+                    // block, or we eventually give up on waiting for it to make it into a block.
+                    // Even `Dropped`/`Invalid`/`Usurped` transactions might make it into a block eventually.
+                    //
+                    // As an example, a transaction that is `Invalid` on one node due to having the wrong
+                    // nonce might still be valid on some fork on another node which ends up being finalized.
+                    // Equally, a transaction `Dropped` from one node may still be in the transaction pool,
+                    // and make it into a block, on another node. Likewise with `Usurped`.
+                    SubstrateTransactionStatus::FinalityTimeout(hash) => {
+                        self.sub = None;
+                        TransactionStatus::FinalityTimeout(hash)
+                    }
+                    SubstrateTransactionStatus::Finalized(hash) => {
+                        self.sub = None;
+                        TransactionStatus::Finalized(TransactionInBlock::new(
+                            hash,
+                            self.ext_hash,
+                            self.client,
+                        ))
+                    }
+                }
+            })
+    }
+}
+
+//* Dev note: The below is adapted from the substrate docs on `TransactionStatus`, which this
+//* enum was adapted from (and which is an exact copy of `SubstrateTransactionStatus` in this crate).
+//* Note that the number of finality watchers is, at the time of writing, found in the constant
+//* `MAX_FINALITY_WATCHERS` in the `sc_transaction_pool` crate.
+//*
+/// Possible transaction statuses returned from our [`TransactionProgress::next_item()`] call.
+///
+/// These status events can be grouped based on their kinds as:
+///
+/// 1. Entering/Moving within the pool:
+///    - `Future`
+///    - `Ready`
+/// 2. Inside `Ready` queue:
+///    - `Broadcast`
+/// 3. Leaving the pool:
+///    - `InBlock`
+///    - `Invalid`
+///    - `Usurped`
+///    - `Dropped`
+/// 4. Re-entering the pool:
+///    - `Retracted`
+/// 5. Block finalized:
+///    - `Finalized`
+///    - `FinalityTimeout`
+///
+/// The events will always be received in the order described above, however
+/// there might be cases where transactions alternate between `Future` and `Ready`
+/// pool, and are `Broadcast` in the meantime.
+///
+/// Note that there are conditions that may cause transactions to reappear in the pool:
+///
+/// 1. Due to possible forks, the transaction that ends up being included
+///    in one block may later re-enter the pool or be marked as invalid.
+/// 2. A transaction that is `Dropped` at one point may later re-enter the pool if
+///    some other transactions are removed.
+/// 3. `Invalid` transactions may become valid at some point in the future.
+///    (Note that runtimes are encouraged to use `UnknownValidity` to inform the
+///    pool about such cases).
+/// 4. `Retracted` transactions might be included in a future block.
+///
+/// The stream is considered finished only when either the `Finalized` or `FinalityTimeout`
+/// event is triggered. You are however free to unsubscribe from notifications at any point.
+/// The first one will be emitted when the block in which the transaction was included gets
+/// finalized. The `FinalityTimeout` event will be emitted when the block did not reach finality
+/// within 512 blocks. This either indicates that finality is not available for your chain,
+/// or that finality gadget is lagging behind.
+#[derive(Derivative)]
+#[derivative(Debug(bound = ""))]
+pub enum TransactionStatus<'client, T: Config, E: Decode> {
+    /// The transaction is part of the "future" queue.
+    Future,
+    /// The transaction is part of the "ready" queue.
+    Ready,
+    /// The transaction has been broadcast to the given peers.
+    Broadcast(Vec<String>),
+    /// The transaction has been included in a block with given hash.
+    InBlock(TransactionInBlock<'client, T, E>),
+    /// The block this transaction was included in has been retracted,
+    /// probably because it did not make it onto the blocks which were
+    /// finalized.
+    Retracted(T::Hash),
+    /// A block containing the transaction did not reach finality within 512
+    /// blocks, and so the subscription has ended.
+    FinalityTimeout(T::Hash),
+    /// The transaction has been finalized by a finality-gadget, e.g GRANDPA.
+    Finalized(TransactionInBlock<'client, T, E>),
+    /// The transaction has been replaced in the pool by another transaction
+    /// that provides the same tags. (e.g. same (sender, nonce)).
+    Usurped(T::Hash),
+    /// The transaction has been dropped from the pool because of the limit.
+    Dropped,
+    /// The transaction is no longer valid in the current state.
+    Invalid,
+}
+
+impl<'client, T: Config, E: Decode> TransactionStatus<'client, T, E> {
+    /// A convenience method to return the `Finalized` details. Returns
+    /// [`None`] if the enum variant is not [`TransactionStatus::Finalized`].
+    pub fn as_finalized(&self) -> Option<&TransactionInBlock<'client, T, E>> {
+        match self {
+            Self::Finalized(val) => Some(val),
+            _ => None,
+        }
+    }
+
+    /// A convenience method to return the `InBlock` details. Returns
+    /// [`None`] if the enum variant is not [`TransactionStatus::InBlock`].
+    pub fn as_in_block(&self) -> Option<&TransactionInBlock<'client, T, E>> {
+        match self {
+            Self::InBlock(val) => Some(val),
+            _ => None,
+        }
+    }
+}
+
+/// This struct represents a transaction that has made it into a block.
+#[derive(Derivative)]
+#[derivative(Debug(bound = ""))]
+pub struct TransactionInBlock<'client, T: Config, E: Decode> {
+    block_hash: T::Hash,
+    ext_hash: T::Hash,
+    client: &'client Client<T>,
+    _error: PhantomDataSendSync<E>,
+}
+
+impl<'client, T: Config, E: Decode> TransactionInBlock<'client, T, E> {
+    pub(crate) fn new(
+        block_hash: T::Hash,
+        ext_hash: T::Hash,
+        client: &'client Client<T>,
+    ) -> Self {
+        Self {
+            block_hash,
+            ext_hash,
+            client,
+            _error: PhantomDataSendSync::new(),
+        }
+    }
+
+    /// Return the hash of the block that the transaction has made it into.
+    pub fn block_hash(&self) -> T::Hash {
+        self.block_hash
+    }
+
+    /// Return the hash of the extrinsic that was submitted.
+    pub fn extrinsic_hash(&self) -> T::Hash {
+        self.ext_hash
+    }
+
+    /// Fetch the events associated with this transaction. If the transaction
+    /// was successful (ie no `ExtrinsicFailed`) events were found, then we return
+    /// the events associated with it. If the transaction was not successful, or
+    /// something else went wrong, we return an error.
+    ///
+    /// **Note:** If multiple `ExtrinsicFailed` errors are returned (for instance
+    /// because a pallet chooses to emit one as an event, which is considered
+    /// abnormal behaviour), it is not specified which of the errors is returned here.
+    /// You can use [`TransactionInBlock::fetch_events`] instead if you'd like to
+    /// work with multiple "error" events.
+    ///
+    /// **Note:** This has to download block details from the node and decode events
+    /// from them.
+    pub async fn wait_for_success(&self) -> Result<TransactionEvents<T>, Error<E>> {
+        let events = self.fetch_events().await?;
+
+        // Try to find any errors; return the first one we encounter.
+        for ev in events.as_slice() {
+            if &ev.pallet == "System" && &ev.variant == "ExtrinsicFailed" {
+                let dispatch_error = E::decode(&mut &*ev.data)?;
+                return Err(Error::Runtime(RuntimeError(dispatch_error)))
+            }
+        }
+
+        Ok(events)
+    }
+
+    /// Fetch all of the events associated with this transaction. This succeeds whether
+    /// the transaction was a success or not; it's up to you to handle the error and
+    /// success events however you prefer.
+    ///
+    /// **Note:** This has to download block details from the node and decode events
+    /// from them.
+    pub async fn fetch_events(&self) -> Result<TransactionEvents<T>, BasicError> {
+        let block = self
+            .client
+            .rpc()
+            .block(Some(self.block_hash))
+            .await?
+            .ok_or(BasicError::Transaction(TransactionError::BlockHashNotFound))?;
+
+        let extrinsic_idx = block.block.extrinsics
+            .iter()
+            .position(|ext| {
+                let hash = T::Hashing::hash_of(ext);
+                hash == self.ext_hash
+            })
+            // If we successfully obtain the block hash we think contains our
+            // extrinsic, the extrinsic should be in there somewhere..
+            .ok_or(BasicError::Transaction(TransactionError::BlockHashNotFound))?;
+
+        let raw_events = self
+            .client
+            .rpc()
+            .storage(
+                &StorageKey::from(SystemEvents::new()),
+                Some(self.block_hash),
+            )
+            .await?
+            .map(|s| s.0)
+            .unwrap_or_else(Vec::new);
+
+        let events = self
+            .client
+            .events_decoder()
+            .decode_events(&mut &*raw_events)?
+            .into_iter()
+            .filter(move |(phase, _raw)| {
+                phase == &Phase::ApplyExtrinsic(extrinsic_idx as u32)
+            })
+            .map(|(_phase, event)| event)
+            .collect();
+
+        Ok(TransactionEvents {
+            block_hash: self.block_hash,
+            ext_hash: self.ext_hash,
+            events,
+        })
+    }
+}
+
+/// This represents the events related to our transaction.
+/// We can iterate over the events, or look for a specific one.
+#[derive(Derivative)]
+#[derivative(Debug(bound = ""))]
+pub struct TransactionEvents<T: Config> {
+    block_hash: T::Hash,
+    ext_hash: T::Hash,
+    events: Vec<crate::RawEvent>,
+}
+
+impl<T: Config> TransactionEvents<T> {
+    /// Return the hash of the block that the transaction has made it into.
+    pub fn block_hash(&self) -> T::Hash {
+        self.block_hash
+    }
+
+    /// Return the hash of the extrinsic.
+    pub fn extrinsic_hash(&self) -> T::Hash {
+        self.ext_hash
+    }
+
+    /// Return a slice of the returned events.
+    pub fn as_slice(&self) -> &[crate::RawEvent] {
+        &self.events
+    }
+
+    /// Find all of the events matching the event type provided as a generic parameter. This
+    /// will return an error if a matching event is found but cannot be properly decoded.
+    pub fn find_events<Ev: crate::Event>(&self) -> Result<Vec<Ev>, BasicError> {
+        self.events
+            .iter()
+            .filter_map(|e| e.as_event::<Ev>().map_err(Into::into).transpose())
+            .collect()
+    }
+
+    /// Find the first event that matches the event type provided as a generic parameter. This
+    /// will return an error if a matching event is found but cannot be properly decoded.
+    ///
+    /// Use [`TransactionEvents::find_events`], or iterate over [`TransactionEvents`] yourself
+    /// if you'd like to handle multiple events of the same type.
+    pub fn find_first_event<Ev: crate::Event>(&self) -> Result<Option<Ev>, BasicError> {
+        self.events
+            .iter()
+            .filter_map(|e| e.as_event::<Ev>().transpose())
+            .next()
+            .transpose()
+            .map_err(Into::into)
+    }
+
+    /// Find an event. Returns true if it was found.
+    pub fn has_event<Ev: crate::Event>(&self) -> Result<bool, BasicError> {
+        Ok(self.find_first_event::<Ev>()?.is_some())
+    }
+}
+
+impl<T: Config> std::ops::Deref for TransactionEvents<T> {
+    type Target = [crate::RawEvent];
+    fn deref(&self) -> &Self::Target {
+        &self.events
+    }
+}