subxt-core crate (#1466)

* start migrating, broken * first iteration of updating * fmt and clippy * add Composite<u32> decoding via scale value patch * bump scale type gen versions * fix decoding with new scale decode * compiling with changed deps * core utils, condig, client, metadata * core crate compiling * signer crate no once lock * add core to no-std-tests, change imports * broken commit, start pulling everything together in subxt * port more things to subxt * events in core crate, extrinsics sadly much more difficult * almost all examples pass again * dynamic values fix in examples * fix no std issue and fmt * remove unused dependencies * fix lightclient impl * runtime version refactor * formatting and addressing nits * more comments addressed * update wasm example and no-std-signer tests * other nits and error impl on signer errors * fix feature flag * fix runtime version refactor * fix doc links * fix integration tests * fix feature flag gated client state * fix native feature in CI * fix lightclient utils * make imports more lean in subxt-core * integrate changes from subxt-core imports into subxt * other changes in subxt simplify imports more * fix and docs * doc false for cli * fix clippy * remove events block hash in tests * codegen no-std support in generated code * export alloc crate for no-std codegen * fix doc test * implement James comments * remove std traits, use core traits instead * address nits * remove unusued dep in no-std tests * fix Box import in no_std * sp-crypto-hashing instead of sp-core-hashing * bump scale-typegen, add no std codegen tests * fix some things * replace unmaintained derivative with derive_where to remove non-canonical warnings * fmt * remove unused dep * fix deps * update artifacts to fix type ID mismatches * bump to latest scale-typegen --------- Co-authored-by: James Wilson <james@jsdw.me>
2026-06-11 21:11:07 +00:00 · 2024-03-27 09:55:08 +01:00
parent 92c1ba7f66
commit a0cb14aa4f
106 changed files with 24329 additions and 26882 deletions
@@ -0,0 +1,22 @@
+// Copyright 2019-2023 Parity Technologies (UK) Ltd.
+// This file is dual-licensed as Apache-2.0 or GPL-3.0.
+// see LICENSE for license details.
+
+//! Types associated with accessing and working with storage items.
+
+mod storage_address;
+mod storage_key;
+pub mod utils;
+
+/// Types representing an address which describes where a storage
+/// entry lives and how to properly decode it.
+pub mod address {
+    pub use super::storage_address::{dynamic, Address, DynamicAddress, StorageAddress};
+    pub use super::storage_key::{StaticStorageKey, StorageHashers, StorageKey};
+}
+
+pub use storage_key::StorageKey;
+
+// For consistency with other modules, also expose
+// the basic address stuff at the root of the module.
+pub use storage_address::{dynamic, Address, DynamicAddress, StorageAddress};
@@ -0,0 +1,174 @@
+// Copyright 2019-2023 Parity Technologies (UK) Ltd.
+// This file is dual-licensed as Apache-2.0 or GPL-3.0.
+// see LICENSE for license details.
+
+use crate::{
+    dynamic::DecodedValueThunk,
+    error::{Error, MetadataError},
+    metadata::{DecodeWithMetadata, Metadata},
+    utils::Yes,
+};
+use derive_where::derive_where;
+
+use alloc::borrow::{Cow, ToOwned};
+use alloc::string::String;
+use alloc::vec::Vec;
+
+use super::{storage_key::StorageHashers, StorageKey};
+
+/// This represents a storage address. Anything implementing this trait
+/// can be used to fetch and iterate over storage entries.
+pub trait StorageAddress {
+    /// The target type of the value that lives at this address.
+    type Target: DecodeWithMetadata;
+    /// The keys type used to construct this address.
+    type Keys: StorageKey;
+    /// Can an entry be fetched from this address?
+    /// Set this type to [`Yes`] to enable the corresponding calls to be made.
+    type IsFetchable;
+    /// Can a default entry be obtained from this address?
+    /// Set this type to [`Yes`] to enable the corresponding calls to be made.
+    type IsDefaultable;
+    /// Can this address be iterated over?
+    /// Set this type to [`Yes`] to enable the corresponding calls to be made.
+    type IsIterable;
+
+    /// The name of the pallet that the entry lives under.
+    fn pallet_name(&self) -> &str;
+
+    /// The name of the entry in a given pallet that the item is at.
+    fn entry_name(&self) -> &str;
+
+    /// Output the non-prefix bytes; that is, any additional bytes that need
+    /// to be appended to the key to dig into maps.
+    fn append_entry_bytes(&self, metadata: &Metadata, bytes: &mut Vec<u8>) -> Result<(), Error>;
+
+    /// An optional hash which, if present, will be checked against
+    /// the node metadata to confirm that the return type matches what
+    /// we are expecting.
+    fn validation_hash(&self) -> Option<[u8; 32]> {
+        None
+    }
+}
+
+/// A concrete storage address. This can be created from static values (ie those generated
+/// via the `subxt` macro) or dynamic values via [`dynamic`].
+#[derive_where(Clone, Debug, Eq, Ord, PartialEq, PartialOrd; Keys)]
+pub struct Address<Keys: StorageKey, ReturnTy, Fetchable, Defaultable, Iterable> {
+    pallet_name: Cow<'static, str>,
+    entry_name: Cow<'static, str>,
+    keys: Keys,
+    validation_hash: Option<[u8; 32]>,
+    _marker: core::marker::PhantomData<(ReturnTy, Fetchable, Defaultable, Iterable)>,
+}
+
+/// A typical storage address constructed at runtime rather than via the `subxt` macro; this
+/// has no restriction on what it can be used for (since we don't statically know).
+pub type DynamicAddress<Keys> = Address<Keys, DecodedValueThunk, Yes, Yes, Yes>;
+
+impl<Keys: StorageKey> DynamicAddress<Keys> {
+    /// Creates a new dynamic address. As `Keys` you can use a `Vec<scale_value::Value>`
+    pub fn new(pallet_name: impl Into<String>, entry_name: impl Into<String>, keys: Keys) -> Self {
+        Self {
+            pallet_name: Cow::Owned(pallet_name.into()),
+            entry_name: Cow::Owned(entry_name.into()),
+            keys,
+            validation_hash: None,
+            _marker: core::marker::PhantomData,
+        }
+    }
+}
+
+impl<Keys, ReturnTy, Fetchable, Defaultable, Iterable>
+    Address<Keys, ReturnTy, Fetchable, Defaultable, Iterable>
+where
+    Keys: StorageKey,
+    ReturnTy: DecodeWithMetadata,
+{
+    /// Create a new [`Address`] using static strings for the pallet and call name.
+    /// This is only expected to be used from codegen.
+    #[doc(hidden)]
+    pub fn new_static(
+        pallet_name: &'static str,
+        entry_name: &'static str,
+        keys: Keys,
+        hash: [u8; 32],
+    ) -> Self {
+        Self {
+            pallet_name: Cow::Borrowed(pallet_name),
+            entry_name: Cow::Borrowed(entry_name),
+            keys,
+            validation_hash: Some(hash),
+            _marker: core::marker::PhantomData,
+        }
+    }
+}
+
+impl<Keys, ReturnTy, Fetchable, Defaultable, Iterable>
+    Address<Keys, ReturnTy, Fetchable, Defaultable, Iterable>
+where
+    Keys: StorageKey,
+    ReturnTy: DecodeWithMetadata,
+{
+    /// Do not validate this storage entry prior to accessing it.
+    pub fn unvalidated(self) -> Self {
+        Self {
+            validation_hash: None,
+            ..self
+        }
+    }
+
+    /// Return bytes representing the root of this storage entry (a hash of the pallet and entry name).
+    pub fn to_root_bytes(&self) -> Vec<u8> {
+        super::utils::storage_address_root_bytes(self)
+    }
+}
+
+impl<Keys, ReturnTy, Fetchable, Defaultable, Iterable> StorageAddress
+    for Address<Keys, ReturnTy, Fetchable, Defaultable, Iterable>
+where
+    Keys: StorageKey,
+    ReturnTy: DecodeWithMetadata,
+{
+    type Target = ReturnTy;
+    type Keys = Keys;
+    type IsFetchable = Fetchable;
+    type IsDefaultable = Defaultable;
+    type IsIterable = Iterable;
+
+    fn pallet_name(&self) -> &str {
+        &self.pallet_name
+    }
+
+    fn entry_name(&self) -> &str {
+        &self.entry_name
+    }
+
+    fn append_entry_bytes(&self, metadata: &Metadata, bytes: &mut Vec<u8>) -> Result<(), Error> {
+        let pallet = metadata.pallet_by_name_err(self.pallet_name())?;
+        let storage = pallet
+            .storage()
+            .ok_or_else(|| MetadataError::StorageNotFoundInPallet(self.pallet_name().to_owned()))?;
+        let entry = storage
+            .entry_by_name(self.entry_name())
+            .ok_or_else(|| MetadataError::StorageEntryNotFound(self.entry_name().to_owned()))?;
+
+        let hashers = StorageHashers::new(entry.entry_type(), metadata.types())?;
+        self.keys
+            .encode_storage_key(bytes, &mut hashers.iter(), metadata.types())?;
+        Ok(())
+    }
+
+    fn validation_hash(&self) -> Option<[u8; 32]> {
+        self.validation_hash
+    }
+}
+
+/// Construct a new dynamic storage lookup.
+pub fn dynamic<Keys: StorageKey>(
+    pallet_name: impl Into<String>,
+    entry_name: impl Into<String>,
+    storage_entry_keys: Keys,
+) -> DynamicAddress<Keys> {
+    DynamicAddress::new(pallet_name, entry_name, storage_entry_keys)
+}
@@ -0,0 +1,475 @@
+use super::utils::hash_bytes;
+use crate::{
+    error::{Error, MetadataError, StorageAddressError},
+    utils::{Encoded, Static},
+};
+use alloc::vec;
+use alloc::vec::Vec;
+use derive_where::derive_where;
+use scale_decode::visitor::IgnoreVisitor;
+use scale_encode::EncodeAsType;
+use scale_info::{PortableRegistry, TypeDef};
+use scale_value::Value;
+use subxt_metadata::{StorageEntryType, StorageHasher};
+
+/// A collection of storage hashers paired with the type ids of the types they should hash.
+/// Can be created for each storage entry in the metadata via [`StorageHashers::new()`].
+#[derive(Debug)]
+pub struct StorageHashers {
+    hashers_and_ty_ids: Vec<(StorageHasher, u32)>,
+}
+
+impl StorageHashers {
+    /// Creates new [`StorageHashers`] from a storage entry. Looks at the [`StorageEntryType`] and
+    /// assigns a hasher to each type id that makes up the key.
+    pub fn new(storage_entry: &StorageEntryType, types: &PortableRegistry) -> Result<Self, Error> {
+        let mut hashers_and_ty_ids = vec![];
+        if let StorageEntryType::Map {
+            hashers, key_ty, ..
+        } = storage_entry
+        {
+            let ty = types
+                .resolve(*key_ty)
+                .ok_or(MetadataError::TypeNotFound(*key_ty))?;
+
+            if let TypeDef::Tuple(tuple) = &ty.type_def {
+                if hashers.len() == 1 {
+                    // use the same hasher for all fields, if only 1 hasher present:
+                    let hasher = hashers[0];
+                    for f in tuple.fields.iter() {
+                        hashers_and_ty_ids.push((hasher, f.id));
+                    }
+                } else if hashers.len() < tuple.fields.len() {
+                    return Err(StorageAddressError::WrongNumberOfHashers {
+                        hashers: hashers.len(),
+                        fields: tuple.fields.len(),
+                    }
+                    .into());
+                } else {
+                    for (i, f) in tuple.fields.iter().enumerate() {
+                        hashers_and_ty_ids.push((hashers[i], f.id));
+                    }
+                }
+            } else {
+                if hashers.len() != 1 {
+                    return Err(StorageAddressError::WrongNumberOfHashers {
+                        hashers: hashers.len(),
+                        fields: 1,
+                    }
+                    .into());
+                }
+                hashers_and_ty_ids.push((hashers[0], *key_ty));
+            };
+        }
+
+        Ok(Self { hashers_and_ty_ids })
+    }
+
+    /// Creates an iterator over the storage hashers and type ids.
+    pub fn iter(&self) -> StorageHashersIter<'_> {
+        StorageHashersIter {
+            hashers: self,
+            idx: 0,
+        }
+    }
+}
+
+/// An iterator over all type ids of the key and the respective hashers.
+/// See [`StorageHashers::iter()`].
+#[derive(Debug)]
+pub struct StorageHashersIter<'a> {
+    hashers: &'a StorageHashers,
+    idx: usize,
+}
+
+impl<'a> StorageHashersIter<'a> {
+    fn next_or_err(&mut self) -> Result<(StorageHasher, u32), Error> {
+        self.next().ok_or_else(|| {
+            StorageAddressError::TooManyKeys {
+                expected: self.hashers.hashers_and_ty_ids.len(),
+            }
+            .into()
+        })
+    }
+}
+
+impl<'a> Iterator for StorageHashersIter<'a> {
+    type Item = (StorageHasher, u32);
+
+    fn next(&mut self) -> Option<Self::Item> {
+        let item = self.hashers.hashers_and_ty_ids.get(self.idx).copied()?;
+        self.idx += 1;
+        Some(item)
+    }
+}
+
+impl<'a> ExactSizeIterator for StorageHashersIter<'a> {
+    fn len(&self) -> usize {
+        self.hashers.hashers_and_ty_ids.len() - self.idx
+    }
+}
+
+/// This trait should be implemented by anything that can be used as one or multiple storage keys.
+pub trait StorageKey {
+    /// Encodes the storage key into some bytes
+    fn encode_storage_key(
+        &self,
+        bytes: &mut Vec<u8>,
+        hashers: &mut StorageHashersIter,
+        types: &PortableRegistry,
+    ) -> Result<(), Error>;
+
+    /// Attempts to decode the StorageKey given some bytes and a set of hashers and type IDs that they are meant to represent.
+    /// The bytes passed to `decode` should start with:
+    /// - 1. some fixed size hash (for all hashers except `Identity`)
+    /// - 2. the plain key value itself (for `Identity`, `Blake2_128Concat` and `Twox64Concat` hashers)
+    fn decode_storage_key(
+        bytes: &mut &[u8],
+        hashers: &mut StorageHashersIter,
+        types: &PortableRegistry,
+    ) -> Result<Self, Error>
+    where
+        Self: Sized + 'static;
+}
+
+/// Implement `StorageKey` for `()` which can be used for keyless storage entries,
+/// or to otherwise just ignore some entry.
+impl StorageKey for () {
+    fn encode_storage_key(
+        &self,
+        _bytes: &mut Vec<u8>,
+        hashers: &mut StorageHashersIter,
+        _types: &PortableRegistry,
+    ) -> Result<(), Error> {
+        _ = hashers.next_or_err();
+        Ok(())
+    }
+
+    fn decode_storage_key(
+        bytes: &mut &[u8],
+        hashers: &mut StorageHashersIter,
+        types: &PortableRegistry,
+    ) -> Result<Self, Error> {
+        let (hasher, ty_id) = match hashers.next_or_err() {
+            Ok((hasher, ty_id)) => (hasher, ty_id),
+            Err(_) if bytes.is_empty() => return Ok(()),
+            Err(err) => return Err(err),
+        };
+        consume_hash_returning_key_bytes(bytes, hasher, ty_id, types)?;
+        Ok(())
+    }
+}
+
+/// A storage key for static encoded values.
+/// The original value is only present at construction, but can be decoded from the contained bytes.
+#[derive_where(Clone, Debug, PartialOrd, PartialEq, Eq)]
+pub struct StaticStorageKey<K: ?Sized> {
+    bytes: Static<Encoded>,
+    _marker: core::marker::PhantomData<K>,
+}
+
+impl<K: codec::Encode + ?Sized> StaticStorageKey<K> {
+    /// Creates a new static storage key
+    pub fn new(key: &K) -> Self {
+        StaticStorageKey {
+            bytes: Static(Encoded(key.encode())),
+            _marker: core::marker::PhantomData,
+        }
+    }
+}
+
+impl<K: codec::Decode + ?Sized> StaticStorageKey<K> {
+    /// Decodes the encoded inner bytes into the type `K`.
+    pub fn decoded(&self) -> Result<K, Error> {
+        let decoded = K::decode(&mut self.bytes())?;
+        Ok(decoded)
+    }
+}
+
+impl<K: ?Sized> StaticStorageKey<K> {
+    /// Returns the scale-encoded bytes that make up this key
+    pub fn bytes(&self) -> &[u8] {
+        &self.bytes.0 .0
+    }
+}
+
+// Note: The ?Sized bound is necessary to support e.g. `StorageKey<[u8]>`.
+impl<K: ?Sized> StorageKey for StaticStorageKey<K> {
+    fn encode_storage_key(
+        &self,
+        bytes: &mut Vec<u8>,
+        hashers: &mut StorageHashersIter,
+        types: &PortableRegistry,
+    ) -> Result<(), Error> {
+        let (hasher, ty_id) = hashers.next_or_err()?;
+        let encoded_value = self.bytes.encode_as_type(&ty_id, types)?;
+        hash_bytes(&encoded_value, hasher, bytes);
+        Ok(())
+    }
+
+    fn decode_storage_key(
+        bytes: &mut &[u8],
+        hashers: &mut StorageHashersIter,
+        types: &PortableRegistry,
+    ) -> Result<Self, Error>
+    where
+        Self: Sized + 'static,
+    {
+        let (hasher, ty_id) = hashers.next_or_err()?;
+        let key_bytes = consume_hash_returning_key_bytes(bytes, hasher, ty_id, types)?;
+
+        // if the hasher had no key appended, we can't decode it into a `StaticStorageKey`.
+        let Some(key_bytes) = key_bytes else {
+            return Err(StorageAddressError::HasherCannotReconstructKey { ty_id, hasher }.into());
+        };
+
+        // Return the key bytes.
+        let key = StaticStorageKey {
+            bytes: Static(Encoded(key_bytes.to_vec())),
+            _marker: core::marker::PhantomData::<K>,
+        };
+        Ok(key)
+    }
+}
+
+impl StorageKey for Vec<scale_value::Value> {
+    fn encode_storage_key(
+        &self,
+        bytes: &mut Vec<u8>,
+        hashers: &mut StorageHashersIter,
+        types: &PortableRegistry,
+    ) -> Result<(), Error> {
+        for value in self.iter() {
+            let (hasher, ty_id) = hashers.next_or_err()?;
+            let encoded_value = value.encode_as_type(&ty_id, types)?;
+            hash_bytes(&encoded_value, hasher, bytes);
+        }
+        Ok(())
+    }
+
+    fn decode_storage_key(
+        bytes: &mut &[u8],
+        hashers: &mut StorageHashersIter,
+        types: &PortableRegistry,
+    ) -> Result<Self, Error>
+    where
+        Self: Sized + 'static,
+    {
+        let mut result: Vec<scale_value::Value> = vec![];
+        for (hasher, ty_id) in hashers.by_ref() {
+            match consume_hash_returning_key_bytes(bytes, hasher, ty_id, types)? {
+                Some(value_bytes) => {
+                    let value =
+                        scale_value::scale::decode_as_type(&mut &*value_bytes, &ty_id, types)?;
+                    result.push(value.remove_context());
+                }
+                None => {
+                    result.push(Value::unnamed_composite([]));
+                }
+            }
+        }
+
+        // We've consumed all of the hashers, so we expect to also consume all of the bytes:
+        if !bytes.is_empty() {
+            return Err(StorageAddressError::TooManyBytes.into());
+        }
+
+        Ok(result)
+    }
+}
+
+// Skip over the hash bytes (including any key at the end), returning bytes
+// representing the key if one exists, or None if the hasher has no key appended.
+fn consume_hash_returning_key_bytes<'a>(
+    bytes: &mut &'a [u8],
+    hasher: StorageHasher,
+    ty_id: u32,
+    types: &PortableRegistry,
+) -> Result<Option<&'a [u8]>, Error> {
+    // Strip the bytes off for the actual hash, consuming them.
+    let bytes_to_strip = hasher.len_excluding_key();
+    if bytes.len() < bytes_to_strip {
+        return Err(StorageAddressError::NotEnoughBytes.into());
+    }
+    *bytes = &bytes[bytes_to_strip..];
+
+    // Now, find the bytes representing the key, consuming them.
+    let before_key = *bytes;
+    if hasher.ends_with_key() {
+        scale_decode::visitor::decode_with_visitor(
+            bytes,
+            &ty_id,
+            types,
+            IgnoreVisitor::<PortableRegistry>::new(),
+        )
+        .map_err(|err| Error::Decode(err.into()))?;
+        // Return the key bytes, having advanced the input cursor past them.
+        let key_bytes = &before_key[..before_key.len() - bytes.len()];
+
+        Ok(Some(key_bytes))
+    } else {
+        // There are no key bytes, so return None.
+        Ok(None)
+    }
+}
+
+/// Generates StorageKey implementations for tuples
+macro_rules! impl_tuples {
+    ($($ty:ident $n:tt),+) => {{
+        impl<$($ty: StorageKey),+> StorageKey for ($( $ty ),+) {
+            fn encode_storage_key(
+                &self,
+                bytes: &mut Vec<u8>,
+                hashers: &mut StorageHashersIter,
+                types: &PortableRegistry,
+            ) -> Result<(), Error> {
+                $(    self.$n.encode_storage_key(bytes, hashers, types)?;    )+
+                Ok(())
+            }
+
+            fn decode_storage_key(
+                bytes: &mut &[u8],
+                hashers: &mut StorageHashersIter,
+                types: &PortableRegistry,
+            ) -> Result<Self, Error>
+            where
+                Self: Sized + 'static,
+            {
+                Ok( ( $(    $ty::decode_storage_key(bytes, hashers, types)?,    )+ ) )
+            }
+        }
+    }};
+}
+
+#[rustfmt::skip]
+const _: () = {
+    impl_tuples!(A 0, B 1);
+    impl_tuples!(A 0, B 1, C 2);
+    impl_tuples!(A 0, B 1, C 2, D 3);
+    impl_tuples!(A 0, B 1, C 2, D 3, E 4);
+    impl_tuples!(A 0, B 1, C 2, D 3, E 4, F 5);
+    impl_tuples!(A 0, B 1, C 2, D 3, E 4, F 5, G 6);
+    impl_tuples!(A 0, B 1, C 2, D 3, E 4, F 5, G 6, H 7);
+};
+
+#[cfg(test)]
+mod tests {
+
+    use codec::Encode;
+    use scale_info::{meta_type, PortableRegistry, Registry, TypeInfo};
+    use subxt_metadata::StorageHasher;
+
+    use crate::utils::Era;
+
+    use alloc::string::String;
+    use alloc::vec;
+    use alloc::vec::Vec;
+
+    use super::{StaticStorageKey, StorageKey};
+
+    struct KeyBuilder {
+        registry: Registry,
+        bytes: Vec<u8>,
+        hashers_and_ty_ids: Vec<(StorageHasher, u32)>,
+    }
+
+    impl KeyBuilder {
+        fn new() -> KeyBuilder {
+            KeyBuilder {
+                registry: Registry::new(),
+                bytes: vec![],
+                hashers_and_ty_ids: vec![],
+            }
+        }
+
+        fn add<T: TypeInfo + Encode + 'static>(mut self, value: T, hasher: StorageHasher) -> Self {
+            let id = self.registry.register_type(&meta_type::<T>()).id;
+
+            self.hashers_and_ty_ids.push((hasher, id));
+            for _i in 0..hasher.len_excluding_key() {
+                self.bytes.push(0);
+            }
+            value.encode_to(&mut self.bytes);
+            self
+        }
+
+        fn build(self) -> (PortableRegistry, Vec<u8>, Vec<(StorageHasher, u32)>) {
+            (self.registry.into(), self.bytes, self.hashers_and_ty_ids)
+        }
+    }
+
+    #[test]
+    fn storage_key_decoding_fuzz() {
+        let hashers = [
+            StorageHasher::Blake2_128,
+            StorageHasher::Blake2_128Concat,
+            StorageHasher::Blake2_256,
+            StorageHasher::Identity,
+            StorageHasher::Twox128,
+            StorageHasher::Twox256,
+            StorageHasher::Twox64Concat,
+        ];
+
+        let key_preserving_hashers = [
+            StorageHasher::Blake2_128Concat,
+            StorageHasher::Identity,
+            StorageHasher::Twox64Concat,
+        ];
+
+        type T4A = (
+            (),
+            StaticStorageKey<u32>,
+            StaticStorageKey<String>,
+            StaticStorageKey<Era>,
+        );
+        type T4B = (
+            (),
+            (StaticStorageKey<u32>, StaticStorageKey<String>),
+            StaticStorageKey<Era>,
+        );
+        type T4C = (
+            ((), StaticStorageKey<u32>),
+            (StaticStorageKey<String>, StaticStorageKey<Era>),
+        );
+
+        let era = Era::Immortal;
+        for h0 in hashers {
+            for h1 in key_preserving_hashers {
+                for h2 in key_preserving_hashers {
+                    for h3 in key_preserving_hashers {
+                        let (types, bytes, hashers_and_ty_ids) = KeyBuilder::new()
+                            .add((), h0)
+                            .add(13u32, h1)
+                            .add("Hello", h2)
+                            .add(era, h3)
+                            .build();
+
+                        let hashers = super::StorageHashers { hashers_and_ty_ids };
+                        let keys_a =
+                            T4A::decode_storage_key(&mut &bytes[..], &mut hashers.iter(), &types)
+                                .unwrap();
+
+                        let keys_b =
+                            T4B::decode_storage_key(&mut &bytes[..], &mut hashers.iter(), &types)
+                                .unwrap();
+
+                        let keys_c =
+                            T4C::decode_storage_key(&mut &bytes[..], &mut hashers.iter(), &types)
+                                .unwrap();
+
+                        assert_eq!(keys_a.1.decoded().unwrap(), 13);
+                        assert_eq!(keys_b.1 .0.decoded().unwrap(), 13);
+                        assert_eq!(keys_c.0 .1.decoded().unwrap(), 13);
+
+                        assert_eq!(keys_a.2.decoded().unwrap(), "Hello");
+                        assert_eq!(keys_b.1 .1.decoded().unwrap(), "Hello");
+                        assert_eq!(keys_c.1 .0.decoded().unwrap(), "Hello");
+                        assert_eq!(keys_a.3.decoded().unwrap(), era);
+                        assert_eq!(keys_b.2.decoded().unwrap(), era);
+                        assert_eq!(keys_c.1 .1.decoded().unwrap(), era);
+                    }
+                }
+            }
+        }
+    }
+}
@@ -0,0 +1,118 @@
+// Copyright 2019-2023 Parity Technologies (UK) Ltd.
+// This file is dual-licensed as Apache-2.0 or GPL-3.0.
+// see LICENSE for license details.
+
+//! these utility methods complement the [`StorageAddress`] trait, but
+//! aren't things that should ever be overridden, and so don't exist on
+//! the trait itself.
+
+use crate::error::MetadataError;
+use crate::metadata::{DecodeWithMetadata, MetadataExt};
+use alloc::vec::Vec;
+use subxt_metadata::PalletMetadata;
+use subxt_metadata::{StorageEntryMetadata, StorageHasher};
+
+use super::StorageAddress;
+use crate::{error::Error, metadata::Metadata};
+use alloc::borrow::ToOwned;
+
+/// Return the root of a given [`StorageAddress`]: hash the pallet name and entry name
+/// and append those bytes to the output.
+pub fn write_storage_address_root_bytes<Address: StorageAddress>(
+    addr: &Address,
+    out: &mut Vec<u8>,
+) {
+    out.extend(sp_crypto_hashing::twox_128(addr.pallet_name().as_bytes()));
+    out.extend(sp_crypto_hashing::twox_128(addr.entry_name().as_bytes()));
+}
+
+/// Outputs the [`storage_address_root_bytes`] as well as any additional bytes that represent
+/// a lookup in a storage map at that location.
+pub fn storage_address_bytes<Address: StorageAddress>(
+    addr: &Address,
+    metadata: &Metadata,
+) -> Result<Vec<u8>, Error> {
+    let mut bytes = Vec::new();
+    write_storage_address_root_bytes(addr, &mut bytes);
+    addr.append_entry_bytes(metadata, &mut bytes)?;
+    Ok(bytes)
+}
+
+/// Outputs a vector containing the bytes written by [`write_storage_address_root_bytes`].
+pub fn storage_address_root_bytes<Address: StorageAddress>(addr: &Address) -> Vec<u8> {
+    let mut bytes = Vec::new();
+    write_storage_address_root_bytes(addr, &mut bytes);
+    bytes
+}
+
+/// Take some SCALE encoded bytes and a [`StorageHasher`] and hash the bytes accordingly.
+pub fn hash_bytes(input: &[u8], hasher: StorageHasher, bytes: &mut Vec<u8>) {
+    match hasher {
+        StorageHasher::Identity => bytes.extend(input),
+        StorageHasher::Blake2_128 => bytes.extend(sp_crypto_hashing::blake2_128(input)),
+        StorageHasher::Blake2_128Concat => {
+            bytes.extend(sp_crypto_hashing::blake2_128(input));
+            bytes.extend(input);
+        }
+        StorageHasher::Blake2_256 => bytes.extend(sp_crypto_hashing::blake2_256(input)),
+        StorageHasher::Twox128 => bytes.extend(sp_crypto_hashing::twox_128(input)),
+        StorageHasher::Twox256 => bytes.extend(sp_crypto_hashing::twox_256(input)),
+        StorageHasher::Twox64Concat => {
+            bytes.extend(sp_crypto_hashing::twox_64(input));
+            bytes.extend(input);
+        }
+    }
+}
+
+/// Return details about the given storage entry.
+pub fn lookup_entry_details<'a>(
+    pallet_name: &str,
+    entry_name: &str,
+    metadata: &'a subxt_metadata::Metadata,
+) -> Result<(PalletMetadata<'a>, &'a StorageEntryMetadata), Error> {
+    let pallet_metadata = metadata.pallet_by_name_err(pallet_name)?;
+    let storage_metadata = pallet_metadata
+        .storage()
+        .ok_or_else(|| MetadataError::StorageNotFoundInPallet(pallet_name.to_owned()))?;
+    let storage_entry = storage_metadata
+        .entry_by_name(entry_name)
+        .ok_or_else(|| MetadataError::StorageEntryNotFound(entry_name.to_owned()))?;
+    Ok((pallet_metadata, storage_entry))
+}
+
+/// Validate a storage address against the metadata.
+pub fn validate_storage_address<Address: StorageAddress>(
+    address: &Address,
+    pallet: PalletMetadata<'_>,
+) -> Result<(), Error> {
+    if let Some(hash) = address.validation_hash() {
+        validate_storage(pallet, address.entry_name(), hash)?;
+    }
+    Ok(())
+}
+
+/// Validate a storage entry against the metadata.
+fn validate_storage(
+    pallet: PalletMetadata<'_>,
+    storage_name: &str,
+    hash: [u8; 32],
+) -> Result<(), Error> {
+    let Some(expected_hash) = pallet.storage_hash(storage_name) else {
+        return Err(MetadataError::IncompatibleCodegen.into());
+    };
+    if expected_hash != hash {
+        return Err(MetadataError::IncompatibleCodegen.into());
+    }
+    Ok(())
+}
+
+/// Given some bytes, a pallet and storage name, decode the response.
+pub fn decode_storage_with_metadata<T: DecodeWithMetadata>(
+    bytes: &mut &[u8],
+    metadata: &Metadata,
+    storage_metadata: &StorageEntryMetadata,
+) -> Result<T, Error> {
+    let return_ty = storage_metadata.entry_type().value_ty();
+    let val = T::decode_with_metadata(bytes, return_ty, metadata)?;
+    Ok(val)
+}