Expand description
Pallet storing metadata for Partner Chain block producers.
§Purpose of this pallet
This pallet enables Partner Chain block producers to provide information about themselves that can then be displayed by chain explorers and other tools to potential delegators looking for pools to delegate to.
§Usage - PC Builders
PC Builders wishing to include this pallet in their runtime should first define a BlockProducerMetadata
type for their runtime to use, eg.
use sidechain_domain::byte_string::BoundedString;
use sp_core::{Encode, ConstU32, Decode, MaxEncodedLen};
type MaxNameLength = ConstU32<64>;
type MaxDescriptionLength = ConstU32<512>;
type MaxUrlLength = ConstU32<256>;
#[derive(Encode, Decode, MaxEncodedLen)]
pub struct BlockProducerMetadata {
pub name: BoundedString<MaxNameLength>,
pub description: BoundedString<MaxDescriptionLength>,
pub logo_url: BoundedString<MaxUrlLength>
}This type can be arbitrary to allow PC Builders to include any data that would be relevant to their chain. However, care should be taken to keep its size to minimum to avoid inflating on-chain storage size by eg. linking to off-chain storage for bulkier data:
pub struct BlockProducerMetadataType {
pub url: BoundedString<MaxUrlLength>,
pub hash: SizedByteString<32>,
}Once the metadata type is defined, the pallet can be added to the runtime and should be configured. This requires providing types used in the runtime along with logic to get the:
- Partner Chain’s genesis UTXO
- starting timestamp of the current slot
For example, a chain that uses pallet_timestamp for its consensus may define a configuration like this:
impl pallet_block_producer_metadata::Config for Runtime {
type WeightInfo = pallet_block_producer_metadata::weights::SubstrateWeight<Runtime>;
type BlockProducerMetadata = BlockProducerMetadata;
type Currency = Balances;
type HoldAmount = MetadataHoldAmount;
type RuntimeHoldReason = RuntimeHoldReason;
fn genesis_utxo() -> sidechain_domain::UtxoId {
Sidechain::genesis_utxo()
}
fn current_time() -> u64 {
pallet_timestamp::Now::<Runtime>::get()
}
}where the SLOT_DURATION constant is the same as was passed to the Aura configuration, and Sidechain
is the pallet_sidechain.
Note here, that we are using weights already provided with the pallet in the example. These weights were
generated for a setup identical to the example. Chains that use different implementations of current_time
should use their own benchmarks.
Currency, HoldAmount, and RuntimeHoldReason types are required to configure the deposit mechanism
for occupying storage.
At this point, the pallet is ready to be used.
§Signing command
To ensure that only the block producer is able to update their own metadata, a signature is required by the
pallet’s extrinsic. To make it easy for PC Builders to provide their users with a signing utility, the
cli_commands crate includes a command for signing the appropriate message. Consult the crate’s own
documentation for more details.
§Benchmarking
See documentation of benchmarking module.
§RPC
See documentation of pallet_block_producer_metadata_rpc crate.
§Usage - PC Users
This pallet exposes two extrinsics: upsert_metadata and delete_metadata for current or prospective block producers to add or
update their metadata. These extrinsics requires a valid signature, which the user should prepare using the
sign-block-producer-metadata command provided by the chain’s node. This command returns the signature
and the metadata encoded as hex bytes (in case of upsert).
When metadata is inserted for the first time, a deposit is held from the caller’s account. This account becomes the owner of the metadata and is the only one allowed to update or delete it. Updates to existing metadata do not require additional deposits. Deleting metadata will release the deposit to the account that originally provided it.
After the signature has been obtained, the user should submit the upsert_metadata extrinsic (eg. using PolkadotJS) providing:
- metadata value: when using PolkadotJS UI, care must be taken to submit the same values that were passed to the CLI
- signature: returned by the CLI
- cross-chain public key: corresponding to the private key used for signing with the CLI
- valid-before: timestamp returned by the CLI. This value can not be changed and defines the time range during which the signature is valid.
Re-exports§
pub use pallet::*;