subxt 0.50.0

// Copyright 2019-2026 Parity Technologies (UK) Ltd.
// This file is dual-licensed as Apache-2.0 or GPL-3.0.
// see LICENSE for license details.

//! This module contains implementations for common transaction extensions, each
//! of which implements [`TransactionExtension`]. A tuple of these can be provided
//! to [`crate::Config::TransactionExtensions`] to select those that we want to
//! make available for a given chain.

use crate::config::transaction_extension_traits::TransactionExtension;
use crate::config::{ClientState, Config, HashFor};
use crate::error::TransactionExtensionError;
use crate::utils::Era;
use codec::{Compact, Encode};
use core::fmt::Debug;
use derive_where::derive_where;
use scale_decode::DecodeAsType;
use scale_encode::EncodeAsType;
use scale_info::PortableRegistry;

// Re-export this here because it's a nicer public interface, and "Params" isn't overly
// specific as a name otherwise.
pub use super::transaction_extension_traits::Params;

/// The [`VerifySignature`] extension. For V5 General transactions, this is how a signature
/// is provided. The signature is constructed by signing a payload which contains the
/// transaction call data as well as the encoded "additional" bytes for any extensions _after_
/// this one in the list.
pub struct VerifySignature<T: Config>(VerifySignatureDetails<T>);

impl<T: Config> TransactionExtension<T> for VerifySignature<T> {
    type Decoded = VerifySignatureDetails<T>;
    type Params = ();

    fn new(
        _client: &ClientState<T>,
        _params: Self::Params,
    ) -> Result<Self, TransactionExtensionError> {
        Ok(VerifySignature(VerifySignatureDetails::Disabled))
    }

    fn inject_signature(&mut self, account: &T::AccountId, signature: &T::Signature) {
        // The signature is not set through params, only here, once given by a user:
        self.0 = VerifySignatureDetails::Signed {
            signature: signature.clone(),
            account: account.clone(),
        }
    }
}

impl<T: Config> frame_decode::extrinsics::TransactionExtension<PortableRegistry>
    for VerifySignature<T>
{
    const NAME: &str = "VerifySignature";

    fn encode_value_to(
        &self,
        type_id: u32,
        type_resolver: &PortableRegistry,
        v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        self.0.encode_as_type_to(type_id, type_resolver, v)?;
        Ok(())
    }
    fn encode_value_for_signer_payload_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        // This extension is never encoded to the signer payload, and extensions
        // prior to this are ignored when creating said payload, so clear anything
        // we've seen so far.
        v.clear();
        Ok(())
    }
    fn encode_implicit_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        // We only use the "implicit" data for extensions _after_ this one
        // in the pipeline to form the signer payload. Thus, clear anything
        // we've seen so far.
        v.clear();
        Ok(())
    }
}

/// This allows a signature to be provided to the [`VerifySignature`] transaction extension.
// Dev note: this must encode identically to https://github.com/paritytech/polkadot-sdk/blob/fd72d58313c297a10600037ce1bb88ec958d722e/substrate/frame/verify-signature/src/extension.rs#L43
#[derive(EncodeAsType, DecodeAsType)]
#[decode_as_type(trait_bounds = "")]
#[encode_as_type(trait_bounds = "")]
pub enum VerifySignatureDetails<T: Config> {
    /// A signature has been provided.
    Signed {
        /// The signature.
        signature: T::Signature,
        /// The account that generated the signature.
        account: T::AccountId,
    },
    /// No signature was provided.
    Disabled,
}

/// The [`CheckMetadataHash`] transaction extension.
pub struct CheckMetadataHash {
    // Eventually we might provide or calculate the metadata hash here,
    // but for now we never provide a hash and so this is empty.
}

impl<T: Config> TransactionExtension<T> for CheckMetadataHash {
    type Decoded = CheckMetadataHashMode;
    type Params = ();

    fn new(
        _client: &ClientState<T>,
        _params: Self::Params,
    ) -> Result<Self, TransactionExtensionError> {
        Ok(CheckMetadataHash {})
    }
}

impl frame_decode::extrinsics::TransactionExtension<PortableRegistry> for CheckMetadataHash {
    const NAME: &str = "CheckMetadataHash";

    fn encode_value_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        // A single 0 byte in the TX payload indicates that the chain should
        // _not_ expect any metadata hash to exist in the signer payload.
        0u8.encode_to(v);
        Ok(())
    }
    fn encode_implicit_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        // We provide no metadata hash in the signer payload to align with the above.
        None::<()>.encode_to(v);
        Ok(())
    }
}

/// Is metadata checking enabled or disabled?
// Dev note: The "Disabled" and "Enabled" variant names match those that the
// transaction extension will be encoded with, in order that DecodeAsType will work
// properly.
#[derive(Copy, Clone, Debug, DecodeAsType)]
pub enum CheckMetadataHashMode {
    /// No hash was provided in the signer payload.
    Disabled,
    /// A hash was provided in the signer payload.
    Enabled,
}

impl CheckMetadataHashMode {
    /// Is metadata checking enabled or disabled for this transaction?
    pub fn is_enabled(&self) -> bool {
        match self {
            CheckMetadataHashMode::Disabled => false,
            CheckMetadataHashMode::Enabled => true,
        }
    }
}

/// The [`CheckSpecVersion`] transaction extension.
pub struct CheckSpecVersion(u32);

impl<T: Config> TransactionExtension<T> for CheckSpecVersion {
    type Decoded = ();
    type Params = ();

    fn new(
        client: &ClientState<T>,
        _params: Self::Params,
    ) -> Result<Self, TransactionExtensionError> {
        Ok(CheckSpecVersion(client.spec_version))
    }
}

impl frame_decode::extrinsics::TransactionExtension<PortableRegistry> for CheckSpecVersion {
    const NAME: &str = "CheckSpecVersion";

    fn encode_value_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        _v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        Ok(())
    }
    fn encode_implicit_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        self.0.encode_to(v);
        Ok(())
    }
}

/// The [`CheckNonce`] transaction extension.
pub struct CheckNonce(u64);

impl<T: Config> TransactionExtension<T> for CheckNonce {
    type Decoded = u64;
    type Params = CheckNonceParams;

    fn new(
        _client: &ClientState<T>,
        params: Self::Params,
    ) -> Result<Self, TransactionExtensionError> {
        Ok(CheckNonce(params.0.unwrap_or(0)))
    }
}

impl frame_decode::extrinsics::TransactionExtension<PortableRegistry> for CheckNonce {
    const NAME: &str = "CheckNonce";

    fn encode_value_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        Compact(self.0).encode_to(v);
        Ok(())
    }
    fn encode_implicit_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        _v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        Ok(())
    }
}

/// Configure the nonce used.
#[derive(Debug, Clone, Default)]
pub struct CheckNonceParams(Option<u64>);

impl CheckNonceParams {
    /// Retrieve the nonce from the chain and use that.
    pub fn from_chain() -> Self {
        Self(None)
    }
    /// Manually set an account nonce to use.
    pub fn with_nonce(nonce: u64) -> Self {
        Self(Some(nonce))
    }
}

impl<T: Config> Params<T> for CheckNonceParams {
    fn inject_account_nonce(&mut self, nonce: u64) {
        if self.0.is_none() {
            self.0 = Some(nonce)
        }
    }
}

/// The [`CheckTxVersion`] transaction extension.
pub struct CheckTxVersion(u32);

impl<T: Config> TransactionExtension<T> for CheckTxVersion {
    type Decoded = ();
    type Params = ();

    fn new(
        client: &ClientState<T>,
        _params: Self::Params,
    ) -> Result<Self, TransactionExtensionError> {
        Ok(CheckTxVersion(client.transaction_version))
    }
}

impl frame_decode::extrinsics::TransactionExtension<PortableRegistry> for CheckTxVersion {
    const NAME: &str = "CheckTxVersion";

    fn encode_value_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        _v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        Ok(())
    }
    fn encode_implicit_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        self.0.encode_to(v);
        Ok(())
    }
}

/// The [`CheckGenesis`] transaction extension.
pub struct CheckGenesis<T: Config>(HashFor<T>);

impl<T: Config> TransactionExtension<T> for CheckGenesis<T> {
    type Decoded = ();
    type Params = ();

    fn new(
        client: &ClientState<T>,
        _params: Self::Params,
    ) -> Result<Self, TransactionExtensionError> {
        Ok(CheckGenesis(client.genesis_hash))
    }
}

impl<T: Config> frame_decode::extrinsics::TransactionExtension<PortableRegistry>
    for CheckGenesis<T>
{
    const NAME: &str = "CheckGenesis";

    fn encode_value_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        _v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        Ok(())
    }
    fn encode_implicit_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        self.0.encode_to(v);
        Ok(())
    }
}

/// The [`CheckMortality`] transaction extension.
pub struct CheckMortality<T: Config> {
    params: CheckMortalityParamsInner<T>,
    genesis_hash: HashFor<T>,
}

impl<T: Config> TransactionExtension<T> for CheckMortality<T> {
    type Decoded = Era;
    type Params = CheckMortalityParams<T>;

    fn new(
        client: &ClientState<T>,
        params: Self::Params,
    ) -> Result<Self, TransactionExtensionError> {
        // If a user has explicitly configured the transaction to be mortal for n blocks, but we get
        // to this stage and no injected information was able to turn this into MortalFromBlock{..},
        // then we hit an error as we are unable to construct a mortal transaction here.
        if matches!(&params.0, CheckMortalityParamsInner::MortalForBlocks(_)) {
            return Err(TransactionExtensionError::custom(
                "CheckMortality: We cannot construct an offline extrinsic with only the number of blocks it is mortal for. Use mortal_from_unchecked instead.",
            ));
        }

        Ok(CheckMortality {
            // if nothing has been explicitly configured, we will have a mortal transaction
            // valid for 32 blocks if block info is available.
            params: params.0,
            genesis_hash: client.genesis_hash,
        })
    }
}

impl<T: Config> frame_decode::extrinsics::TransactionExtension<PortableRegistry>
    for CheckMortality<T>
{
    const NAME: &str = "CheckMortality";

    fn encode_value_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        match &self.params {
            CheckMortalityParamsInner::MortalFromBlock {
                for_n_blocks,
                from_block_n,
                ..
            } => {
                Era::mortal(*for_n_blocks, *from_block_n).encode_to(v);
            }
            _ => {
                // Note: if we see `CheckMortalityInner::MortalForBlocks`, then it means the user has
                // configured a block to be mortal for N blocks, but the current block was never injected,
                // so we don't know where to start from and default back to building an immortal tx.
                Era::Immortal.encode_to(v);
            }
        }
        Ok(())
    }
    fn encode_implicit_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        match &self.params {
            CheckMortalityParamsInner::MortalFromBlock {
                from_block_hash, ..
            } => {
                from_block_hash.encode_to(v);
            }
            _ => {
                self.genesis_hash.encode_to(v);
            }
        }
        Ok(())
    }
}

/// Parameters to configure the [`CheckMortality`] transaction extension.
pub struct CheckMortalityParams<T: Config>(CheckMortalityParamsInner<T>);

enum CheckMortalityParamsInner<T: Config> {
    /// The transaction will be immortal.
    Immortal,
    /// The transaction is mortal for N blocks. This must be "upgraded" into
    /// [`CheckMortalityParamsInner::MortalFromBlock`] to ultimately work.
    MortalForBlocks(u64),
    /// The transaction is mortal for N blocks, but if it cannot be "upgraded",
    /// then it will be set to immortal instead. This is the default if unset.
    MortalForBlocksOrImmortalIfNotPossible(u64),
    /// The transaction is mortal and all of the relevant information is provided.
    MortalFromBlock {
        for_n_blocks: u64,
        from_block_n: u64,
        from_block_hash: HashFor<T>,
    },
}

impl<T: Config> Default for CheckMortalityParams<T> {
    fn default() -> Self {
        // default to being mortal for 32 blocks if possible, else immortal:
        CheckMortalityParams(CheckMortalityParamsInner::MortalForBlocksOrImmortalIfNotPossible(32))
    }
}

impl<T: Config> CheckMortalityParams<T> {
    /// Configure a transaction that will be mortal for the number of blocks given.
    pub fn mortal(for_n_blocks: u64) -> Self {
        Self(CheckMortalityParamsInner::MortalForBlocks(for_n_blocks))
    }

    /// Configure a transaction that will be mortal for the number of blocks given,
    /// and from the block details provided. Prefer to use [`CheckMortalityParams::mortal()`]
    /// where possible, which prevents the block number and hash from being misaligned.
    pub fn mortal_from_unchecked(
        for_n_blocks: u64,
        from_block_n: u64,
        from_block_hash: HashFor<T>,
    ) -> Self {
        Self(CheckMortalityParamsInner::MortalFromBlock {
            for_n_blocks,
            from_block_n,
            from_block_hash,
        })
    }
    /// An immortal transaction.
    pub fn immortal() -> Self {
        Self(CheckMortalityParamsInner::Immortal)
    }
}

impl<T: Config> Params<T> for CheckMortalityParams<T> {
    fn inject_block(&mut self, from_block_n: u64, from_block_hash: HashFor<T>) {
        match &self.0 {
            CheckMortalityParamsInner::MortalForBlocks(n)
            | CheckMortalityParamsInner::MortalForBlocksOrImmortalIfNotPossible(n) => {
                self.0 = CheckMortalityParamsInner::MortalFromBlock {
                    for_n_blocks: *n,
                    from_block_n,
                    from_block_hash,
                }
            }
            _ => {
                // Don't change anything if explicit Immortal or explicit block set.
            }
        }
    }
}

/// The [`ChargeAssetTxPayment`] transaction extension.
#[derive(DecodeAsType)]
#[derive_where(Clone, Debug; T::AssetId)]
#[decode_as_type(trait_bounds = "T::AssetId: DecodeAsType")]
pub struct ChargeAssetTxPayment<T: Config> {
    tip: Compact<u128>,
    asset_id: Option<T::AssetId>,
}

impl<T: Config> ChargeAssetTxPayment<T> {
    /// Tip to the extrinsic author in the native chain token.
    pub fn tip(&self) -> u128 {
        self.tip.0
    }

    /// Tip to the extrinsic author using the asset ID given.
    pub fn asset_id(&self) -> Option<&T::AssetId> {
        self.asset_id.as_ref()
    }
}

impl<T: Config> TransactionExtension<T> for ChargeAssetTxPayment<T> {
    type Decoded = Self;
    type Params = ChargeAssetTxPaymentParams<T>;

    fn new(
        _client: &ClientState<T>,
        params: Self::Params,
    ) -> Result<Self, TransactionExtensionError> {
        Ok(ChargeAssetTxPayment {
            tip: Compact(params.tip),
            asset_id: params.asset_id,
        })
    }
}

impl<T: Config> frame_decode::extrinsics::TransactionExtension<PortableRegistry>
    for ChargeAssetTxPayment<T>
{
    const NAME: &str = "ChargeAssetTxPayment";

    fn encode_value_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        (self.tip, &self.asset_id).encode_to(v);
        Ok(())
    }
    fn encode_implicit_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        _v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        Ok(())
    }
}

/// Parameters to configure the [`ChargeAssetTxPayment`] transaction extension.
#[cfg_attr(test, derive_where(PartialEq; T::AssetId))]
#[derive_where(Debug)]
pub struct ChargeAssetTxPaymentParams<T: Config> {
    tip: u128,
    asset_id: Option<T::AssetId>,
}

impl<T: Config> Default for ChargeAssetTxPaymentParams<T> {
    fn default() -> Self {
        ChargeAssetTxPaymentParams {
            tip: Default::default(),
            asset_id: Default::default(),
        }
    }
}

impl<T: Config> ChargeAssetTxPaymentParams<T> {
    /// Don't provide a tip to the extrinsic author.
    pub fn no_tip() -> Self {
        ChargeAssetTxPaymentParams {
            tip: 0,
            asset_id: None,
        }
    }
    /// Tip the extrinsic author in the native chain token.
    pub fn tip(tip: u128) -> Self {
        ChargeAssetTxPaymentParams {
            tip,
            asset_id: None,
        }
    }
    /// Tip the extrinsic author using the asset ID given.
    pub fn tip_of(tip: u128, asset_id: T::AssetId) -> Self {
        ChargeAssetTxPaymentParams {
            tip,
            asset_id: Some(asset_id),
        }
    }
}

impl<T: Config> Params<T> for ChargeAssetTxPaymentParams<T> {}

/// The [`ChargeTransactionPayment`] transaction extension.
#[derive(Clone, Debug, DecodeAsType)]
pub struct ChargeTransactionPayment {
    tip: Compact<u128>,
}

impl ChargeTransactionPayment {
    /// Tip to the extrinsic author in the native chain token.
    pub fn tip(&self) -> u128 {
        self.tip.0
    }
}

impl<T: Config> TransactionExtension<T> for ChargeTransactionPayment {
    type Decoded = Self;
    type Params = ChargeTransactionPaymentParams;

    fn new(
        _client: &ClientState<T>,
        params: Self::Params,
    ) -> Result<Self, TransactionExtensionError> {
        Ok(ChargeTransactionPayment {
            tip: Compact(params.tip),
        })
    }
}

impl frame_decode::extrinsics::TransactionExtension<PortableRegistry> for ChargeTransactionPayment {
    const NAME: &str = "ChargeTransactionPayment";

    fn encode_value_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        self.tip.encode_to(v);
        Ok(())
    }
    fn encode_implicit_to(
        &self,
        _type_id: u32,
        _type_resolver: &PortableRegistry,
        _v: &mut Vec<u8>,
    ) -> Result<(), frame_decode::extrinsics::TransactionExtensionError> {
        Ok(())
    }
}

/// Parameters to configure the [`ChargeTransactionPayment`] transaction extension.
#[cfg_attr(test, derive(PartialEq))]
#[derive(Default, Debug)]
pub struct ChargeTransactionPaymentParams {
    tip: u128,
}

impl ChargeTransactionPaymentParams {
    /// Don't provide a tip to the extrinsic author.
    pub fn no_tip() -> Self {
        ChargeTransactionPaymentParams { tip: 0 }
    }
    /// Tip the extrinsic author in the native chain token.
    pub fn tip(tip: u128) -> Self {
        ChargeTransactionPaymentParams { tip }
    }
}

impl<T: Config> Params<T> for ChargeTransactionPaymentParams {}