#
pezkuwi_sdk_docs/reference_docs/
extrinsic_encoding.rs

    1//! # Constructing and Signing Extrinsics
    2//!
    3//! Extrinsics are payloads that are stored in blocks which are responsible for altering the state
    4//! of a blockchain via the [_state transition
    5//! function_][crate::reference_docs::blockchain_state_machines].
    6//!
    7//! Bizinikiwi is configurable enough that extrinsics can take any format. In practice, runtimes
    8//! tend to use our [`pezsp_runtime::generic::UncheckedExtrinsic`] type to represent extrinsics,
    9//! because it's generic enough to cater for most (if not all) use cases. In Pezkuwi, this is
    10//! configured [here](https://github.com/pezkuwichain/pezkuwi-fellows/tree/main/runtimes/blob/94b2798b69ba6779764e20a50f056e48db78ebef/relay/pezkuwi/src/lib.rs#L1478)
    11//! at the time of writing.
    12//!
    13//! What follows is a description of how extrinsics based on this
    14//! [`pezsp_runtime::generic::UncheckedExtrinsic`] type are encoded into bytes. Specifically, we are
    15//! looking at how extrinsics with a format version of 5 are encoded. This version is itself a part
    16//! of the payload, and if it changes, it indicates that something about the encoding may have
    17//! changed.
    18//!
    19//! # Encoding an Extrinsic
    20//!
    21//! At a high level, all extrinsics compatible with [`pezsp_runtime::generic::UncheckedExtrinsic`]
    22//! are formed from concatenating some details together, as in the following pseudo-code:
    23//!
    24//! ```text
    25//! extrinsic_bytes = concat(
    26//!     compact_encoded_length,
    27//!     version_and_extrinsic_type,
    28//! 	maybe_extension_data,
    29//!     call_data
    30//! )
    31//! ```
    32//!
    33//! For clarity, the actual implementation in Bizinikiwi looks like this:
    34#![doc = docify::embed!("../../bizinikiwi/primitives/runtime/src/generic/unchecked_extrinsic.rs", unchecked_extrinsic_encode_impl)]
    35//!
    36//! Let's look at how each of these details is constructed:
    37//!
    38//! ## compact_encoded_length
    39//!
    40//! This is a [SCALE compact encoded][pezframe::deps::codec::Compact] integer which is equal to the
    41//! length, in bytes, of the rest of the extrinsic details.
    42//!
    43//! To obtain this value, we must encode and concatenate together the rest of the extrinsic details
    44//! first, and then obtain the byte length of these. We can then compact encode that length, and
    45//! prepend it to the rest of the details.
    46//!
    47//! ## version_and_maybe_signature
    48//!
    49//! If the extrinsic is _unsigned_, then `version_and_maybe_signature` will be just one byte
    50//! denoting the _transaction protocol version_, which is 4 (or `0b0000_0100`).
    51//!
    52//! If the extrinsic is _signed_ (all extrinsics submitted from users must be signed), then
    53//! `version_and_maybe_signature` is obtained by concatenating some details together, ie:
    54//!
    55//! ```text
    56//! version_and_maybe_signature = concat(
    57//!     version_and_signed,
    58//!     from_address,
    59//!     signature,
    60//!     transaction_extensions_extra,
    61//! )
    62//! ```
    63//!
    64//! Each of the details to be concatenated together is explained below:
    65//!
    66//! ## version_and_extrinsic_type
    67//!
    68//! This byte has 2 components:
    69//! - the 2 most significant bits represent the extrinsic type:
    70//!     - bare - `0b00`
    71//!     - signed - `0b10`
    72//!     - general - `0b01`
    73//! - the 6 least significant bits represent the extrinsic format version (currently 5)
    74//!
    75//! ### Bare extrinsics
    76//!
    77//! If the extrinsic is _bare_, then `version_and_extrinsic_type` will be just the _transaction
    78//! protocol version_, which is 5 (or `0b0000_0101`). Bare extrinsics do not carry any other
    79//! extension data, so `maybe_extension_data` would not be included in the payload and the
    80//! `version_and_extrinsic_type` would always be followed by the encoded call bytes.
    81//!
    82//! ### Signed extrinsics
    83//!
    84//! If the extrinsic is _signed_ (all extrinsics submitted from users used to be signed up until
    85//! version 4), then `version_and_extrinsic_type` is obtained by having a MSB of `1` on the
    86//! _transaction protocol version_ byte (which translates to `0b1000_0101`).
    87//!
    88//! Additionally, _signed_ extrinsics also carry with them address and signature information encoded
    89//! as follows:
    90//!
    91//! #### from_address
    92//!
    93//! This is the [SCALE encoded][pezframe::deps::codec] address of the sender of the extrinsic. The
    94//! address is the first generic parameter of [`pezsp_runtime::generic::UncheckedExtrinsic`], and so
    95//! can vary from chain to chain.
    96//!
    97//! The address type used on the Pezkuwi relay chain is
    98//! [`pezsp_runtime::MultiAddress<AccountId32>`], where `AccountId32` is defined
    99//! [here][`pezsp_core::crypto::AccountId32`]. When constructing a signed extrinsic to be submitted
    100//! to a Pezkuwi node, you'll always use the [`pezsp_runtime::MultiAddress::Id`] variant to wrap
    101//! your `AccountId32`.
    102//!
    103//! #### signature
    104//!
    105//! This is the [SCALE encoded][pezframe::deps::codec] signature. The signature type is configured via
    106//! the third generic parameter of [`pezsp_runtime::generic::UncheckedExtrinsic`], which determines
    107//! the shape of the signature and signing algorithm that should be used.
    108//!
    109//! The signature is obtained by signing the _signed payload_ bytes (see below on how this is
    110//! constructed) using the private key associated with the address and correct algorithm.
    111//!
    112//! The signature type used on the Pezkuwi relay chain is [`pezsp_runtime::MultiSignature`]; the
    113//! variants there are the types of signature that can be provided.
    114//!
    115//! ### General extrinsics
    116//!
    117//! If the extrinsic is _general_ (it doesn't carry a signature in the payload, only extension
    118//! data), then `version_and_extrinsic_type` is obtained by logical OR between the general
    119//! transaction type bits and the _transaction protocol version_ byte (which translates to
    120//! `0b0100_0101`).
    121//!
    122//! ### transaction_extensions_extra
    123//!
    124//! This is the concatenation of the [SCALE encoded][pezframe::deps::codec] bytes representing first a
    125//! single byte describing the extension version (this is bumped whenever a change occurs in the
    126//! transaction extension pipeline) followed by the bytes of each of the [_transaction
    127//! extensions_][pezsp_runtime::traits::TransactionExtension], and are configured by the fourth
    128//! generic parameter of [`pezsp_runtime::generic::UncheckedExtrinsic`]. Learn more about
    129//! transaction extensions [here][crate::reference_docs::transaction_extensions].
    130//!
    131//! When it comes to constructing an extrinsic, each transaction extension has two things that we
    132//! are interested in here:
    133//!
    134//! - The actual SCALE encoding of the transaction extension type itself; this is what will form our
    135//!   `transaction_extensions_extra` bytes.
    136//! - An `Implicit` type. This is SCALE encoded into the `transaction_extensions_implicit` data (see
    137//!   below).
    138//!
    139//! Either (or both) of these can encode to zero bytes.
    140//!
    141//! Each chain configures the set of transaction extensions that it uses in its runtime
    142//! configuration. At the time of writing, Pezkuwi configures them
    143//! [here](https://github.com/pezkuwichain/pezkuwi-fellows/tree/main/runtimes/blob/1dc04eb954eadf8aadb5d83990b89662dbb5a074/relay/pezkuwi/src/lib.rs#L1432C25-L1432C25).
    144//! Some of the common transaction extensions are defined
    145//! [here][pezframe::deps::pezframe_system#transaction-extensions].
    146//!
    147//! Information about exactly which transaction extensions are present on a chain and in what order
    148//! is also a part of the metadata for the chain. For V15 metadata, it can be [found
    149//! here][pezframe::deps::pezframe_support::__private::metadata::v15::ExtrinsicMetadata].
    150//!
    151//! ## call_data
    152//!
    153//! This is the main payload of the extrinsic, which is used to determine how the chain's state is
    154//! altered. This is defined by the second generic parameter of
    155//! [`pezsp_runtime::generic::UncheckedExtrinsic`].
    156//!
    157//! A call can be anything that implements [`Encode`][pezframe::deps::codec::Encode]. In FRAME-based
    158//! runtimes, a call is represented as an enum of enums, where the outer enum represents the FRAME
    159//! pezpallet being called, and the inner enum represents the call being made within that pezpallet,
    160//! and any arguments to it. Read more about the call enum
    161//! [here][crate::reference_docs::frame_runtime_types].
    162//!
    163//! FRAME `Call` enums are automatically generated, and end up looking something like this:
    164#![doc = docify::embed!("./src/reference_docs/extrinsic_encoding.rs", call_data)]
    165//!
    166//! In pseudo-code, this `Call` enum encodes equivalently to:
    167//!
    168//! ```text
    169//! call_data = concat(
    170//!     pezpallet_index,
    171//!     call_index,
    172//!     call_args
    173//! )
    174//! ```
    175//!
    176//! - `pezpallet_index` is a single byte denoting the index of the pezpallet that we are calling
    177//!   into, and is what the tag of the outermost enum will encode to.
    178//! - `call_index` is a single byte denoting the index of the call that we are making the pezpallet,
    179//!   and is what the tag of the inner enum will encode to.
    180//! - `call_args` are the SCALE encoded bytes for each of the arguments that the call expects, and
    181//!   are typically provided as values to the inner enum.
    182//!
    183//! Information about the pallets that exist for a chain (including their indexes), the calls
    184//! available in each pezpallet (including their indexes), and the arguments required for each call
    185//! can be found in the metadata for the chain. For V15 metadata, this information [is
    186//! here][pezframe::deps::pezframe_support::__private::metadata::v15::PalletMetadata].
    187//!
    188//! # The Signed Payload Format
    189//!
    190//! All _signed_ extrinsics submitted to a node from the outside world (also known as
    191//! _transactions_) need to be _signed_. The data that needs to be signed for some extrinsic is
    192//! called the _signed payload_, and its shape is described by the following pseudo-code:
    193//!
    194//! ```text
    195//! signed_payload = blake2_256(
    196//! 	concat(
    197//!     	call_data,
    198//!     	transaction_extensions_extra,
    199//!     	transaction_extensions_implicit,
    200//! 	)
    201//! )
    202//! ```
    203//!
    204//! The bytes representing `call_data` and `transaction_extensions_extra` can be obtained as
    205//! descibed above. `transaction_extensions_implicit` is constructed by SCALE encoding the
    206//! ["implicit" data][pezsp_runtime::traits::TransactionExtension::Implicit] for each transaction
    207//! extension that the chain is using, in order.
    208//!
    209//! Once we've concatenated those together, we hash the result using a Blake2 256bit hasher.
    210//!
    211//! The [`pezsp_runtime::generic::SignedPayload`] type takes care of assembling the correct payload
    212//! for us, given `call_data` and a tuple of transaction extensions.
    213//!
    214//! # The General Transaction Format
    215//!
    216//! A General transaction does not have a signature method hardcoded in the check logic of the
    217//! extrinsic, such as a traditionally signed transaction. Instead, general transactions should have
    218//! one or more extensions in the transaction extension pipeline that auhtorize origins in some way,
    219//! one of which could be the traditional signature check that happens for all signed transactions
    220//! in the [Checkable](pezsp_runtime::traits::Checkable) implementation of
    221//! [UncheckedExtrinsic](pezsp_runtime::generic::UncheckedExtrinsic). Therefore, it is up to each
    222//! extension to define the format of the payload it will try to check and authorize the right
    223//! origin type. For an example, look into the [authorization example pezpallet
    224//! extensions](pezpallet_example_authorization_tx_extension::extensions)
    225//!
    226//! # Example Encoding
    227//!
    228//! Using [`pezsp_runtime::generic::UncheckedExtrinsic`], we can construct and encode an extrinsic
    229//! as follows:
    230#![doc = docify::embed!("./src/reference_docs/extrinsic_encoding.rs", encoding_example)]
    231
    232#[docify::export]
    233pub mod call_data {
    234	use codec::{Decode, Encode};
    235	use pezsp_runtime::{traits::Dispatchable, DispatchResultWithInfo};
    236
    237	// The outer enum composes calls within
    238	// different pallets together. We have two
    239	// pallets, "PalletA" and "PalletB".
    240	#[derive(Encode, Decode, Clone)]
    241	pub enum Call {
    242		#[codec(index = 0)]
    243		PalletA(PalletACall),
    244		#[codec(index = 7)]
    245		PalletB(PalletBCall),
    246	}
    247
    248	// An inner enum represents the calls within
    249	// a specific pezpallet. "PalletA" has one call,
    250	// "Foo".
    251	#[derive(Encode, Decode, Clone)]
    252	pub enum PalletACall {
    253		#[codec(index = 0)]
    254		Foo(String),
    255	}
    256
    257	#[derive(Encode, Decode, Clone)]
    258	pub enum PalletBCall {
    259		#[codec(index = 0)]
    260		Bar(String),
    261	}
    262
    263	impl Dispatchable for Call {
    264		type RuntimeOrigin = ();
    265		type Config = ();
    266		type Info = ();
    267		type PostInfo = ();
    268		fn dispatch(self, _origin: Self::RuntimeOrigin) -> DispatchResultWithInfo<Self::PostInfo> {
    269			Ok(())
    270		}
    271	}
    272}
    273
    274#[docify::export]
    275pub mod encoding_example {
    276	use super::call_data::{Call, PalletACall};
    277	use crate::reference_docs::transaction_extensions::transaction_extensions_example;
    278	use codec::Encode;
    279	use pezsp_core::crypto::AccountId32;
    280	use pezsp_keyring::sr25519::Keyring;
    281	use pezsp_runtime::{
    282		generic::{SignedPayload, UncheckedExtrinsic},
    283		MultiAddress, MultiSignature,
    284	};
    285
    286	// Define some transaction extensions to use. We'll use a couple of examples
    287	// from the transaction extensions reference doc.
    288	type TransactionExtensions = (
    289		transaction_extensions_example::AddToPayload,
    290		transaction_extensions_example::AddToSignaturePayload,
    291	);
    292
    293	// We'll use `UncheckedExtrinsic` to encode our extrinsic for us. We set
    294	// the address and signature type to those used on Pezkuwi, use our custom
    295	// `Call` type, and use our custom set of `TransactionExtensions`.
    296	type Extrinsic = UncheckedExtrinsic<
    297		MultiAddress<AccountId32, ()>,
    298		Call,
    299		MultiSignature,
    300		TransactionExtensions,
    301	>;
    302
    303	pub fn encode_demo_extrinsic() -> Vec<u8> {
    304		// The "from" address will be our Alice dev account.
    305		let from_address = MultiAddress::<AccountId32, ()>::Id(Keyring::Alice.to_account_id());
    306
    307		// We provide some values for our expected transaction extensions.
    308		let transaction_extensions = (
    309			transaction_extensions_example::AddToPayload(1),
    310			transaction_extensions_example::AddToSignaturePayload,
    311		);
    312
    313		// Construct our call data:
    314		let call_data = Call::PalletA(PalletACall::Foo("Hello".to_string()));
    315
    316		// The signed payload. This takes care of encoding the call_data,
    317		// transaction_extensions_extra and transaction_extensions_implicit, and hashing
    318		// the result if it's > 256 bytes:
    319		let signed_payload = SignedPayload::new(call_data.clone(), transaction_extensions.clone());
    320
    321		// Sign the signed payload with our Alice dev account's private key,
    322		// and wrap the signature into the expected type:
    323		let signature = {
    324			let sig = Keyring::Alice.sign(&signed_payload.encode());
    325			MultiSignature::Sr25519(sig)
    326		};
    327
    328		// Now, we can build and encode our extrinsic:
    329		let ext = Extrinsic::new_signed(call_data, from_address, signature, transaction_extensions);
    330
    331		let encoded_ext = ext.encode();
    332		encoded_ext
    333	}
    334}