Where is the documentation for `assimilate_storage` function?

This post was flagged by the community and is temporarily hidden.

fn assimilate_storage is part of BuildStorage trait defined in primitives

/// Complex storage builder stuff.
#[cfg(feature = "std")]
pub trait BuildStorage {
	/// Build the storage out of this builder.
	fn build_storage(&self) -> Result<sp_core::storage::Storage, String> {
		let mut storage = Default::default();
		self.assimilate_storage(&mut storage)?;
		Ok(storage)
	}
	/// Assimilate the storage for this module into pre-existing overlays.
	fn assimilate_storage(&self, storage: &mut sp_core::storage::Storage) -> Result<(), String>;
}

You can find an implementation for it in the chain_spec module in the client.

impl<G: RuntimeGenesis, E> BuildStorage for ChainSpec<G, E> {
	fn assimilate_storage(&self, storage: &mut Storage) -> Result<(), String> {
		match self.genesis.resolve()? {
			Genesis::Runtime(gc) => gc.assimilate_storage(storage),
			Genesis::Raw(RawGenesis { top: map, children_default: children_map }) => {
				storage.top.extend(map.into_iter().map(|(k, v)| (k.0, v.0)));
				children_map.into_iter().for_each(|(k, v)| {
					let child_info = ChildInfo::new_default(k.0.as_slice());
					storage
						.children_default
						.entry(k.0)
						.or_insert_with(|| StorageChild { data: Default::default(), child_info })
						.data
						.extend(v.into_iter().map(|(k, v)| (k.0, v.0)));
				});
				Ok(())
			},
			// The `StateRootHash` variant exists as a way to keep note that other clients support
			// it, but Substrate itself isn't capable of loading chain specs with just a hash at the
			// moment.
			Genesis::StateRootHash(_) => Err("Genesis storage in hash format not supported".into()),
		}
	}
}

At the same time, fn assimilate_storage is part of the trait GenesisBuild defined in frame-support pallet.

/// A trait to define the build function of a genesis config, T and I are placeholder for pallet
/// trait and pallet instance.
#[cfg(feature = "std")]
pub trait GenesisBuild<T, I = ()>: Default + sp_runtime::traits::MaybeSerializeDeserialize {
	/// The build function is called within an externalities allowing storage APIs.
	/// Thus one can write to storage using regular pallet storages.
	fn build(&self);

	/// Build the storage using `build` inside default storage.
	fn build_storage(&self) -> Result<sp_runtime::Storage, String> {
		let mut storage = Default::default();
		self.assimilate_storage(&mut storage)?;
		Ok(storage)
	}

	/// Assimilate the storage for this module into pre-existing overlays.
	fn assimilate_storage(&self, storage: &mut sp_runtime::Storage) -> Result<(), String> {
		sp_state_machine::BasicExternalities::execute_with_storage(storage, || {
			self.build();
			Ok(())
		})
	}
}

You can see this one being used as part of the implementation of GenesisConfigin frame-system pallet.

/// Direct implementation of `GenesisBuild::assimilate_storage`.
///
/// Kept in order not to break dependency.
pub fn assimilate_storage<T: Config>(
	&self,
	storage: &mut sp_runtime::Storage,
) -> Result<(), String> {
	<Self as GenesisBuild<T>>::assimilate_storage(self, storage)
}

EDIT: I see you have your reasons, just would like to point out that this would make a nice stack exchange post.

1 Like

Would appreciate if you move both the question and the answer to StackExchange.

1 Like

Done :wink: https://substrate.stackexchange.com/questions/6742/where-can-i-find-documentation-for-assimilate-storage-function/6743#6743

Hope it can help someone.

For me, the only documentation is:

/// Assimilate the storage for this module into pre-existing overlays.

Implementation is not documentation.

Use case in an other trait is not documentation either.

So the answer to my question is:

There is no documentation for substrate traits methods, substrate users should figure out what they do by reading implementation and use cases.

I encourage reading Why Free Software Needs Free Documentation - GNU Project - Free Software Foundation.

gnu

1 Like