From b14027142e9bb966d158f2ed851e53d553913db0 Mon Sep 17 00:00:00 2001 From: masapr <40862722+masapr@users.noreply.github.com> Date: Fri, 10 Feb 2023 13:50:46 +0100 Subject: [PATCH] Function renamings in `state` api interface + improved documentation (#448) * rename key_hash to storage_key * rename parameters storage_prefix -> pallet, storage_key_name -> key * cargo fmt * renamings in state * rename key -> storage_item * rename get_storage_map_key_prefix -> get_storage_key_prefix * more namings in state.rs * added comments * added missing renames in metadata.rs * renamings and comments after code review --- examples/examples/get_storage.rs | 4 +- examples/examples/staking_batch_payout.rs | 5 +- node-api/src/metadata.rs | 44 ++--- src/api/rpc_api/events.rs | 2 +- src/api/rpc_api/frame_system.rs | 2 +- src/api/rpc_api/state.rs | 189 +++++++++++++--------- testing/examples/state_tests.rs | 12 +- 7 files changed, 137 insertions(+), 121 deletions(-) diff --git a/examples/examples/get_storage.rs b/examples/examples/get_storage.rs index f87bf175e..58ee6a926 100644 --- a/examples/examples/get_storage.rs +++ b/examples/examples/get_storage.rs @@ -36,7 +36,7 @@ async fn main() { let mut api = Api::<_, _, PlainTipExtrinsicParams, Runtime>::new(client).unwrap(); // get some plain storage value - let result: u128 = api.get_storage_value("Balances", "TotalIssuance", None).unwrap().unwrap(); + let result: u128 = api.get_storage("Balances", "TotalIssuance", None).unwrap().unwrap(); println!("[+] TotalIssuance is {}", result); let proof = api.get_storage_value_proof("Balances", "TotalIssuance", None).unwrap(); @@ -71,7 +71,7 @@ async fn main() { println!("Retrieving value for key {:?}", storage_key); // We're expecting account info as return value because we fetch added a prefix of "System" + "Account". let storage_data: AccountInfo = - api.get_storage_by_key_hash(storage_key.clone(), None).unwrap().unwrap(); + api.get_storage_by_key(storage_key.clone(), None).unwrap().unwrap(); println!("Retrieved data {:?}", storage_data); } } diff --git a/examples/examples/staking_batch_payout.rs b/examples/examples/staking_batch_payout.rs index 9be275d24..d2aee1427 100644 --- a/examples/examples/staking_batch_payout.rs +++ b/examples/examples/staking_batch_payout.rs @@ -59,8 +59,7 @@ async fn main() { let validator_stash = AccountId32::from_ss58check("5GNJqTPyNqANBkUVMN1LPPrxXnFouWXoe2wNSmmEoLctxiZY").unwrap(); - let active_era: ActiveEraInfo = - api.get_storage_value("Staking", "ActiveEra", None).unwrap().unwrap(); + let active_era: ActiveEraInfo = api.get_storage("Staking", "ActiveEra", None).unwrap().unwrap(); println!("{:?}", active_era); let current_era_index = active_era.index; @@ -150,7 +149,7 @@ pub fn get_last_reward_received_for( let ledger_storage_key = api.metadata().storage_map_key("Staking", "Ledger", account).unwrap(); let claimed_rewards: Vec = - match api.get_storage_by_key_hash::(ledger_storage_key, None) { + match api.get_storage_by_key::(ledger_storage_key, None) { Ok(Some(ledger)) => ledger.claimed_rewards, _ => Vec::new(), }; diff --git a/node-api/src/metadata.rs b/node-api/src/metadata.rs index ba8ea021d..1c72b7561 100644 --- a/node-api/src/metadata.rs +++ b/node-api/src/metadata.rs @@ -455,50 +455,40 @@ impl TryFrom for Metadata { impl Metadata { pub fn storage_value_key( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, + pallet: &'static str, + storage_item: &'static str, ) -> Result { - Ok(self - .pallet(storage_prefix)? - .storage(storage_key_name)? - .get_value(storage_prefix)? - .key()) + Ok(self.pallet(pallet)?.storage(storage_item)?.get_value(pallet)?.key()) } pub fn storage_map_key( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, + pallet: &'static str, + storage_item: &'static str, map_key: K, ) -> Result { - Ok(self - .pallet(storage_prefix)? - .storage(storage_key_name)? - .get_map::(storage_prefix)? - .key(map_key)) + Ok(self.pallet(pallet)?.storage(storage_item)?.get_map::(pallet)?.key(map_key)) } pub fn storage_map_key_prefix( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, + pallet: &'static str, + storage_item: &'static str, ) -> Result { - self.pallet(storage_prefix)? - .storage(storage_key_name)? - .get_map_prefix(storage_prefix) + self.pallet(pallet)?.storage(storage_item)?.get_map_prefix(pallet) } pub fn storage_double_map_key( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, - first: K, - second: Q, + pallet: &'static str, + storage_item: &'static str, + first_double_map_key: K, + second_double_map_key: Q, ) -> Result { Ok(self - .pallet(storage_prefix)? - .storage(storage_key_name)? - .get_double_map::(storage_prefix)? - .key(first, second)) + .pallet(pallet)? + .storage(storage_item)? + .get_double_map::(pallet)? + .key(first_double_map_key, second_double_map_key)) } } diff --git a/src/api/rpc_api/events.rs b/src/api/rpc_api/events.rs index 83d7c7e48..0bea952f4 100644 --- a/src/api/rpc_api/events.rs +++ b/src/api/rpc_api/events.rs @@ -53,7 +53,7 @@ where fn fetch_events_from_block(&self, block_hash: Runtime::Hash) -> Result> { let key = crate::storage_key("System", "Events"); let event_bytes = self - .get_opaque_storage_by_key_hash(key, Some(block_hash))? + .get_opaque_storage_by_key(key, Some(block_hash))? .ok_or(Error::BlockNotFound)?; let events = Events::::new(self.metadata().clone(), Default::default(), event_bytes); diff --git a/src/api/rpc_api/frame_system.rs b/src/api/rpc_api/frame_system.rs index 4bfd2dc5b..f6136d917 100644 --- a/src/api/rpc_api/frame_system.rs +++ b/src/api/rpc_api/frame_system.rs @@ -56,7 +56,7 @@ where )?; info!("storage key is: 0x{}", hex::encode(&storagekey)); - self.get_storage_by_key_hash(storagekey, None) + self.get_storage_by_key(storagekey, None) } fn get_account_data( diff --git a/src/api/rpc_api/state.rs b/src/api/rpc_api/state.rs index 08cbb1b7a..7d709cad7 100644 --- a/src/api/rpc_api/state.rs +++ b/src/api/rpc_api/state.rs @@ -26,45 +26,60 @@ use serde::de::DeserializeOwned; /// Generic interface to substrate storage. pub trait GetStorage { - fn get_storage_value( + /// Retrieve the storage value. + /// + /// `at_block`: the state is queried at this block, set to `None` to get the state from the latest known block. + fn get_storage( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, + pallet: &'static str, + storage_item: &'static str, at_block: Option, ) -> Result>; + /// Retrieve the storage value from a map for the given `map_key`. + /// + /// `at_block`: the state is queried at this block, set to `None` to get the state from the latest known block. fn get_storage_map( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, + pallet: &'static str, + storage_item: &'static str, map_key: K, at_block: Option, ) -> Result>; + /// Retrieve the key prefix for a storage map. This is the prefix needed for get_storage_keys_paged(). fn get_storage_map_key_prefix( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, + pallet: &'static str, + storage_item: &'static str, ) -> Result; + /// Retrieve the storage value from a double map for the given keys: `first_double_map_key` and `second_double_map_key`. + /// + /// `at_block`: the state is queried at this block, set to `None` to get the state from the latest known block. fn get_storage_double_map( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, - first: K, - second: Q, + pallet: &'static str, + storage_item: &'static str, + first_double_map_key: K, + second_double_map_key: Q, at_block: Option, ) -> Result>; - fn get_storage_by_key_hash( + /// Retrieve the storage value from the given `storage_key`. + /// + /// `at_block`: the state is queried at this block, set to `None` to get the state from the latest known block. + fn get_storage_by_key( &self, - key: StorageKey, + storage_key: StorageKey, at_block: Option, ) -> Result>; - /// Returns the keys with prefix with pagination support. + /// Retrieve 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. + /// + /// `at_block`: the state is queried at this block, set to `None` to get the state from the latest known block. fn get_storage_keys_paged( &self, prefix: Option, @@ -73,36 +88,51 @@ pub trait GetStorage { at_block: Option, ) -> Result>; - fn get_opaque_storage_by_key_hash( + /// Retrieve the raw storage for the given `storage_key`. + /// + /// `at_block`: the state is queried at this block, set to `None` to get the state from the latest known block. + fn get_opaque_storage_by_key( &self, - key: StorageKey, + storage_key: StorageKey, at_block: Option, ) -> Result>>; + /// Retrieve the storage proof of the corresponding storage value. + /// + /// `at_block`: the state is queried at this block, set to `None` to get the state from the latest known block. fn get_storage_value_proof( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, + pallet: &'static str, + storage_item: &'static str, at_block: Option, ) -> Result>>; + /// Retrieve the storage proof of the corresponding storage map value. + /// + /// `at_block`: the state is queried at this block, set to `None` to get the state from the latest known block. fn get_storage_map_proof( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, + pallet: &'static str, + storage_item: &'static str, map_key: K, at_block: Option, ) -> Result>>; + /// Retrieve the storage proof of the corresponding storage double map value. + /// + /// `at_block`: the state is queried at this block, set to `None` to get the state from the latest known block. fn get_storage_double_map_proof( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, - first: K, - second: Q, + pallet: &'static str, + storage_item: &'static str, + first_double_map_key: K, + second_double_map_key: Q, at_block: Option, ) -> Result>>; + /// Retrieve the proof of the corresponding storage entries. + /// + /// `at_block`: the state is queried at this block, set to `None` to get the state from the latest known block. fn get_storage_proof_by_keys( &self, keys: Vec, @@ -121,65 +151,63 @@ where Runtime: FrameSystemConfig, Params: ExtrinsicParams, { - fn get_storage_value( + fn get_storage( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, + pallet: &'static str, + storage_item: &'static str, at_block: Option, ) -> Result> { - let storagekey = self.metadata().storage_value_key(storage_prefix, storage_key_name)?; + let storagekey = self.metadata().storage_value_key(pallet, storage_item)?; info!("storage key is: 0x{}", hex::encode(&storagekey)); - self.get_storage_by_key_hash(storagekey, at_block) + self.get_storage_by_key(storagekey, at_block) } fn get_storage_map( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, + pallet: &'static str, + storage_item: &'static str, map_key: K, at_block: Option, ) -> Result> { - let storagekey = - self.metadata() - .storage_map_key::(storage_prefix, storage_key_name, map_key)?; + let storagekey = self.metadata().storage_map_key::(pallet, storage_item, map_key)?; info!("storage key is: 0x{}", hex::encode(&storagekey)); - self.get_storage_by_key_hash(storagekey, at_block) + self.get_storage_by_key(storagekey, at_block) } fn get_storage_map_key_prefix( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, + pallet: &'static str, + storage_item: &'static str, ) -> Result { self.metadata() - .storage_map_key_prefix(storage_prefix, storage_key_name) + .storage_map_key_prefix(pallet, storage_item) .map_err(|e| e.into()) } fn get_storage_double_map( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, - first: K, - second: Q, + pallet: &'static str, + storage_item: &'static str, + first_double_map_key: K, + second_double_map_key: Q, at_block: Option, ) -> Result> { let storagekey = self.metadata().storage_double_map_key::( - storage_prefix, - storage_key_name, - first, - second, + pallet, + storage_item, + first_double_map_key, + second_double_map_key, )?; info!("storage key is: 0x{}", hex::encode(&storagekey)); - self.get_storage_by_key_hash(storagekey, at_block) + self.get_storage_by_key(storagekey, at_block) } - fn get_storage_by_key_hash( + fn get_storage_by_key( &self, - key: StorageKey, + storage_key: StorageKey, at_block: Option, ) -> Result> { - let s = self.get_opaque_storage_by_key_hash(key, at_block)?; + let s = self.get_opaque_storage_by_key(storage_key, at_block)?; match s { Some(storage) => Ok(Some(Decode::decode(&mut storage.as_slice())?)), None => Ok(None), @@ -188,85 +216,86 @@ where fn get_storage_keys_paged( &self, - prefix: Option, + storage_key_prefix: Option, count: u32, start_key: Option, at_block: Option, ) -> Result> { - let storage = self - .client() - .request("state_getKeysPaged", rpc_params![prefix, count, start_key, at_block])?; + let storage = self.client().request( + "state_getKeysPaged", + rpc_params![storage_key_prefix, count, start_key, at_block], + )?; Ok(storage) } - fn get_opaque_storage_by_key_hash( + fn get_opaque_storage_by_key( &self, - key: StorageKey, + storage_key: StorageKey, at_block: Option, ) -> Result>> { let storage: Option = - self.client().request("state_getStorage", rpc_params![key, at_block])?; + self.client().request("state_getStorage", rpc_params![storage_key, at_block])?; Ok(storage.map(|storage_data| storage_data.0)) } fn get_storage_value_proof( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, + pallet: &'static str, + storage_item: &'static str, at_block: Option, ) -> Result>> { - let storagekey = self.metadata().storage_value_key(storage_prefix, storage_key_name)?; + let storagekey = self.metadata().storage_value_key(pallet, storage_item)?; info!("storage key is: 0x{}", hex::encode(&storagekey)); self.get_storage_proof_by_keys(vec![storagekey], at_block) } fn get_storage_map_proof( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, + pallet: &'static str, + storage_item: &'static str, map_key: K, at_block: Option, ) -> Result>> { - let storagekey = - self.metadata() - .storage_map_key::(storage_prefix, storage_key_name, map_key)?; + let storagekey = self.metadata().storage_map_key::(pallet, storage_item, map_key)?; info!("storage key is: 0x{}", hex::encode(&storagekey)); self.get_storage_proof_by_keys(vec![storagekey], at_block) } fn get_storage_double_map_proof( &self, - storage_prefix: &'static str, - storage_key_name: &'static str, - first: K, - second: Q, + pallet: &'static str, + storage_item: &'static str, + first_double_map_key: K, + second_double_map_key: Q, at_block: Option, ) -> Result>> { - let storagekey = self.metadata().storage_double_map_key::( - storage_prefix, - storage_key_name, - first, - second, + let storage_key = self.metadata().storage_double_map_key::( + pallet, + storage_item, + first_double_map_key, + second_double_map_key, )?; - info!("storage key is: 0x{}", hex::encode(&storagekey)); - self.get_storage_proof_by_keys(vec![storagekey], at_block) + info!("storage key is: 0x{}", hex::encode(&storage_key)); + self.get_storage_proof_by_keys(vec![storage_key], at_block) } fn get_storage_proof_by_keys( &self, - keys: Vec, + storage_keys: Vec, at_block: Option, ) -> Result>> { - let proof = self.client().request("state_getReadProof", rpc_params![keys, at_block])?; + let proof = self + .client() + .request("state_getReadProof", rpc_params![storage_keys, at_block])?; Ok(proof) } fn get_keys( &self, - key: StorageKey, + storage_key: StorageKey, at_block: Option, ) -> Result>> { - let keys = self.client().request("state_getKeys", rpc_params![key, at_block])?; + let keys = self.client().request("state_getKeys", rpc_params![storage_key, at_block])?; Ok(keys) } diff --git a/testing/examples/state_tests.rs b/testing/examples/state_tests.rs index 6ce5e63ef..b41afef98 100644 --- a/testing/examples/state_tests.rs +++ b/testing/examples/state_tests.rs @@ -49,11 +49,9 @@ async fn main() { // Tests let _total_issuance: Balance = - api.get_storage_value("Balances", "TotalIssuance", None).unwrap().unwrap(); - let _total_issuance: Balance = api - .get_storage_value("Balances", "TotalIssuance", Some(block_hash)) - .unwrap() - .unwrap(); + api.get_storage("Balances", "TotalIssuance", None).unwrap().unwrap(); + let _total_issuance: Balance = + api.get_storage("Balances", "TotalIssuance", Some(block_hash)).unwrap().unwrap(); let _account_info: AccountData = api.get_storage_map("System", "Account", &alice, None).unwrap().unwrap(); let _era_stakers: ErasStakers = api @@ -69,9 +67,9 @@ async fn main() { assert_eq!(storage_key_prefix.0, storage_key.0[..prefix_len]); let _account_data: AccountData = - api.get_storage_by_key_hash(storage_key.clone(), None).unwrap().unwrap(); + api.get_storage_by_key(storage_key.clone(), None).unwrap().unwrap(); let account_data_opaque = - api.get_opaque_storage_by_key_hash(storage_key.clone(), None).unwrap().unwrap(); + api.get_opaque_storage_by_key(storage_key.clone(), None).unwrap().unwrap(); let _account_data = AccountData::decode(&mut account_data_opaque.as_slice()).unwrap(); let _value_proof = api.get_storage_value_proof("Balances", "TotalIssuance", None).unwrap().unwrap();