ab_contracts_common/metadata/

decode.rs

use crate::MAX_TOTAL_METHOD_ARGS;
use crate::metadata::{ContractMetadataKind, MAX_METADATA_DEPTH};
use ab_io_type::metadata::{IoTypeDetails, IoTypeMetadataKind};
use core::mem::ManuallyDrop;
use derive_destructure2::destructure;

/// Metadata decoding error
#[derive(Debug, thiserror::Error)]
pub enum MetadataDecodingError<'metadata> {
    /// Not enough metadata to decode
    #[error("Not enough metadata to decode")]
    NotEnoughMetadata,
    /// Invalid first metadata byte
    #[error("Invalid first metadata byte")]
    InvalidFirstMetadataByte { byte: u8 },
    /// Multiple contracts found
    #[error("Multiple contracts found")]
    MultipleContractsFound,
    /// Expected contract or trait kind, found something else
    #[error("Expected contract or trait kind, found something else: {metadata_kind:?}")]
    ExpectedContractOrTrait { metadata_kind: ContractMetadataKind },
    /// Failed to decode state type name
    #[error("Failed to decode state type name")]
    FailedToDecodeStateTypeName,
    /// Invalid state I/O type
    #[error("Invalid state I/O type")]
    InvalidStateIoType,
    /// Unexpected method kind
    #[error("Unexpected method kind {method_kind:?} for container kind {container_kind:?}")]
    UnexpectedMethodKind {
        method_kind: MethodKind,
        container_kind: MethodsContainerKind,
    },
    /// Expected method kind, found something else
    #[error("Expected method kind, found something else: {metadata_kind:?}")]
    ExpectedMethodKind { metadata_kind: ContractMetadataKind },
    /// More arguments than `#[contract]` allows, see [`MAX_TOTAL_METHOD_ARGS`]
    #[error("Too many arguments: {number_of_arguments}")]
    TooManyArguments {
        /// Number of arguments in metadata, together with `self` in methods that have it
        number_of_arguments: u8,
    },
    /// `#[init]` method that doesn't end with the state, see [`ContractMetadataKind::Init`]
    #[error("`#[init]` method doesn't end with the state")]
    InitWithoutState,
    /// Expected argument kind, found something else
    #[error("Expected argument kind, found something else: {metadata_kind:?}")]
    ExpectedArgumentKind { metadata_kind: ContractMetadataKind },
    /// Unexpected argument kind
    #[error(
        "Unexpected argument kind {argument_kind:?} for method kind {method_kind:?} in container \
        kind {container_kind:?}"
    )]
    UnexpectedArgumentKind {
        argument_kind: ArgumentKind,
        method_kind: MethodKind,
        container_kind: MethodsContainerKind,
    },
    /// An argument out of the order that `#[contract]` generates, see
    /// [`ContractMetadataKind::Init`]
    #[error("Argument of kind {argument_kind:?} is out of order")]
    ArgumentOutOfOrder { argument_kind: ArgumentKind },
    /// Invalid argument I/O type
    #[error("Invalid argument I/O type of kind {argument_kind:?} for {argument_name:?}")]
    InvalidArgumentIoType {
        argument_name: &'metadata [u8],
        argument_kind: ArgumentKind,
    },
}

#[derive(Debug)]
pub enum MetadataItem<'a, 'metadata> {
    Contract {
        /// State type name as bytes.
        ///
        /// Expected to be UTF-8, but must be parsed before printed as text, which is somewhat
        /// costly.
        state_type_name: &'metadata [u8],
        state_type_details: IoTypeDetails,
        slot_type_details: IoTypeDetails,
        tmp_type_details: IoTypeDetails,
        num_methods: u8,
        decoder: MethodsMetadataDecoder<'a, 'metadata>,
    },
    Trait {
        /// Trait name as bytes.
        ///
        /// Expected to be UTF-8, but must be parsed before printed as text, which is somewhat
        /// costly.
        trait_name: &'metadata [u8],
        num_methods: u8,
        decoder: MethodsMetadataDecoder<'a, 'metadata>,
    },
}

impl<'a, 'metadata> MetadataItem<'a, 'metadata> {
    #[inline(always)]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    #[expect(
        clippy::rest_pattern_accessible_field,
        reason = "Do not need other fields"
    )]
    pub fn num_methods(&self) -> u8 {
        match self {
            MetadataItem::Contract { num_methods, .. }
            | MetadataItem::Trait { num_methods, .. } => *num_methods,
        }
    }

    #[inline(always)]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    #[expect(
        clippy::rest_pattern_accessible_field,
        reason = "Do not need other fields"
    )]
    pub fn into_decoder(self) -> MethodsMetadataDecoder<'a, 'metadata> {
        match self {
            MetadataItem::Contract { decoder, .. } | MetadataItem::Trait { decoder, .. } => decoder,
        }
    }
}

#[derive(Debug)]
pub struct MetadataDecoder<'metadata> {
    metadata: &'metadata [u8],
    found_contract: bool,
    found_something: bool,
}

impl<'metadata> MetadataDecoder<'metadata> {
    #[inline(always)]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    pub fn new(metadata: &'metadata [u8]) -> Self {
        Self {
            metadata,
            found_contract: false,
            found_something: false,
        }
    }

    /// The number of bytes left in the metadata that were not processed yet
    #[inline(always)]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    pub fn remaining_metadata_bytes(&self) -> usize {
        self.metadata.len()
    }

    // TODO: Helper method to decode all methods, ideally as a single iterator
    #[inline]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    pub fn decode_next<'a>(
        &'a mut self,
    ) -> Option<Result<MetadataItem<'a, 'metadata>, MetadataDecodingError<'metadata>>> {
        // Decode method kind
        let metadata_kind = *self.metadata.split_off_first()?;
        let Ok(metadata_kind) = ContractMetadataKind::try_from(metadata_kind) else {
            return Some(Err(MetadataDecodingError::InvalidFirstMetadataByte {
                byte: metadata_kind,
            }));
        };

        self.found_something = true;

        match metadata_kind {
            ContractMetadataKind::Contract => {
                if self.found_contract {
                    return Some(Err(MetadataDecodingError::MultipleContractsFound));
                }
                self.found_contract = true;

                Some(self.decode_contract())
            }
            ContractMetadataKind::Trait => Some(self.decode_trait()),
            // The rest are methods or arguments and can't appear here
            ContractMetadataKind::Init
            | ContractMetadataKind::UpdateStateless
            | ContractMetadataKind::UpdateStatefulRo
            | ContractMetadataKind::UpdateStatefulRw
            | ContractMetadataKind::ViewStateless
            | ContractMetadataKind::ViewStateful
            | ContractMetadataKind::EnvRo
            | ContractMetadataKind::EnvRw
            | ContractMetadataKind::TmpRo
            | ContractMetadataKind::TmpRw
            | ContractMetadataKind::SlotRo
            | ContractMetadataKind::SlotRw
            | ContractMetadataKind::Input
            | ContractMetadataKind::Output
            | ContractMetadataKind::Return => {
                Some(Err(MetadataDecodingError::ExpectedContractOrTrait {
                    metadata_kind,
                }))
            }
        }
    }

    #[inline(always)]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    fn decode_contract<'a>(
        &'a mut self,
    ) -> Result<MetadataItem<'a, 'metadata>, MetadataDecodingError<'metadata>> {
        // Decode state type name without moving the metadata cursor
        let state_type_name = IoTypeMetadataKind::type_name(self.metadata)
            .ok_or(MetadataDecodingError::FailedToDecodeStateTypeName)?;

        // Decode the recommended capacity of the state type
        let state_type_details;
        (state_type_details, self.metadata) =
            IoTypeMetadataKind::type_details::<MAX_METADATA_DEPTH>(self.metadata)
                .ok_or(MetadataDecodingError::InvalidStateIoType)?;

        // Decode the recommended capacity of the `#[slot]` type
        let slot_type_details;
        (slot_type_details, self.metadata) =
            IoTypeMetadataKind::type_details::<MAX_METADATA_DEPTH>(self.metadata)
                .ok_or(MetadataDecodingError::InvalidStateIoType)?;

        // Decode the recommended capacity of the `#[tmp]` type
        let tmp_type_details;
        (tmp_type_details, self.metadata) =
            IoTypeMetadataKind::type_details::<MAX_METADATA_DEPTH>(self.metadata)
                .ok_or(MetadataDecodingError::InvalidStateIoType)?;

        // Decode the number of methods
        let num_methods = *self
            .metadata
            .split_off_first()
            .ok_or(MetadataDecodingError::NotEnoughMetadata)?;

        Ok(MetadataItem::Contract {
            state_type_name,
            state_type_details,
            slot_type_details,
            tmp_type_details,
            num_methods,
            decoder: MethodsMetadataDecoder::new(
                &mut self.metadata,
                MethodsContainerKind::Contract,
                num_methods,
            ),
        })
    }

    #[inline(always)]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    fn decode_trait<'a>(
        &'a mut self,
    ) -> Result<MetadataItem<'a, 'metadata>, MetadataDecodingError<'metadata>> {
        // Decode trait name
        let trait_name_length = usize::from(
            *self
                .metadata
                .split_off_first()
                .ok_or(MetadataDecodingError::NotEnoughMetadata)?,
        );

        let trait_name = self
            .metadata
            .split_off(..trait_name_length)
            .ok_or(MetadataDecodingError::NotEnoughMetadata)?;

        // Decode the number of methods
        let num_methods = *self
            .metadata
            .split_off_first()
            .ok_or(MetadataDecodingError::NotEnoughMetadata)?;

        Ok(MetadataItem::Trait {
            trait_name,
            num_methods,
            decoder: MethodsMetadataDecoder::new(
                &mut self.metadata,
                MethodsContainerKind::Trait,
                num_methods,
            ),
        })
    }
}

#[derive(Debug, Copy, Clone)]
pub enum MethodsContainerKind {
    Contract,
    Trait,
    Unknown,
}

#[derive(Debug)]
pub struct MethodsMetadataDecoder<'a, 'metadata> {
    metadata: &'a mut &'metadata [u8],
    container_kind: MethodsContainerKind,
    remaining: u8,
}

impl Drop for MethodsMetadataDecoder<'_, '_> {
    fn drop(&mut self) {
        while let Some(_method_metadata_decoder) = self.decode_next() {
            // Drain remaining methods if dropped early
        }
    }
}

impl<'a, 'metadata> MethodsMetadataDecoder<'a, 'metadata> {
    #[inline(always)]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    fn new(
        metadata: &'a mut &'metadata [u8],
        container_kind: MethodsContainerKind,
        num_methods: u8,
    ) -> Self {
        Self {
            metadata,
            container_kind,
            remaining: num_methods,
        }
    }

    /// Remaining methods in the decoder
    #[inline(always)]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    pub fn remaining_methods(&self) -> u8 {
        self.remaining
    }

    /// The number of bytes left in the metadata that were not processed yet
    #[inline(always)]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    pub fn remaining_metadata_bytes(&self) -> usize {
        self.metadata.len()
    }

    #[inline(always)]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    pub fn decode_next<'b>(&'b mut self) -> Option<MethodMetadataDecoder<'b, 'metadata>> {
        if self.remaining == 0 {
            return None;
        }

        self.remaining -= 1;

        Some(MethodMetadataDecoder::new(
            self.metadata,
            self.container_kind,
        ))
    }
}

#[derive(Debug, Copy, Clone)]
pub enum MethodKind {
    /// Corresponds to [`ContractMetadataKind::Init`]
    Init,
    /// Corresponds to [`ContractMetadataKind::UpdateStateless`]
    UpdateStateless,
    /// Corresponds to [`ContractMetadataKind::UpdateStatefulRo`]
    UpdateStatefulRo,
    /// Corresponds to [`ContractMetadataKind::UpdateStatefulRw`]
    UpdateStatefulRw,
    /// Corresponds to [`ContractMetadataKind::ViewStateless`]
    ViewStateless,
    /// Corresponds to [`ContractMetadataKind::ViewStateful`]
    ViewStateful,
}

impl MethodKind {
    #[inline(always)]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    pub fn has_self(&self) -> bool {
        match self {
            MethodKind::Init | MethodKind::UpdateStateless | MethodKind::ViewStateless => false,
            MethodKind::UpdateStatefulRo
            | MethodKind::UpdateStatefulRw
            | MethodKind::ViewStateful => true,
        }
    }
}

#[derive(Debug, Copy, Clone)]
pub struct MethodMetadataItem<'metadata> {
    /// Method name as bytes.
    ///
    /// Expected to be UTF-8, but must be parsed before printed as text, which is somewhat costly.
    pub method_name: &'metadata [u8],
    pub method_kind: MethodKind,
    /// Number of arguments in the metadata of the method, which is the number of items that
    /// [`ArgumentsMetadataDecoder::decode_next()`] returns. `self` is not one of them, since it is
    /// part of the method kind (see [`MethodKind::has_self()`]).
    pub num_arguments: u8,
}

// TODO: Would be nice to also collect fingerprint at the end
#[derive(Debug, destructure)]
pub struct MethodMetadataDecoder<'a, 'metadata> {
    metadata: &'a mut &'metadata [u8],
    container_kind: MethodsContainerKind,
}

impl Drop for MethodMetadataDecoder<'_, '_> {
    fn drop(&mut self) {
        let metadata_before = *self.metadata;

        // Decode implicitly
        if MethodMetadataDecoder::new(self.metadata, self.container_kind)
            .decode_next()
            .is_err()
        {
            // Restore original metadata if decoding failed so it fails decoding later, this is
            // a compromise to avoid panics on `drop`
            *self.metadata = metadata_before;
        }
    }
}

impl<'a, 'metadata> MethodMetadataDecoder<'a, 'metadata> {
    #[inline(always)]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    pub fn new(metadata: &'a mut &'metadata [u8], container_kind: MethodsContainerKind) -> Self {
        Self {
            metadata,
            container_kind,
        }
    }

    /// The number of bytes left in the metadata that were not processed yet
    #[inline(always)]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    pub fn remaining_metadata_bytes(&self) -> usize {
        self.metadata.len()
    }

    #[inline]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    pub fn decode_next(
        self,
    ) -> Result<
        (
            ArgumentsMetadataDecoder<'a, 'metadata>,
            MethodMetadataItem<'metadata>,
        ),
        MetadataDecodingError<'metadata>,
    > {
        let (metadata, container_kind) = self.destructure();

        // Decode method kind
        let metadata_kind = *metadata
            .split_off_first()
            .ok_or(MetadataDecodingError::NotEnoughMetadata)?;
        let metadata_kind = ContractMetadataKind::try_from(metadata_kind).map_err(|()| {
            MetadataDecodingError::InvalidFirstMetadataByte {
                byte: metadata_kind,
            }
        })?;

        let method_kind = match metadata_kind {
            ContractMetadataKind::Init => MethodKind::Init,
            ContractMetadataKind::UpdateStateless => MethodKind::UpdateStateless,
            ContractMetadataKind::UpdateStatefulRo => MethodKind::UpdateStatefulRo,
            ContractMetadataKind::UpdateStatefulRw => MethodKind::UpdateStatefulRw,
            ContractMetadataKind::ViewStateless => MethodKind::ViewStateless,
            ContractMetadataKind::ViewStateful => MethodKind::ViewStateful,
            // The rest are not methods and can't appear here
            ContractMetadataKind::Contract
            | ContractMetadataKind::Trait
            | ContractMetadataKind::EnvRo
            | ContractMetadataKind::EnvRw
            | ContractMetadataKind::TmpRo
            | ContractMetadataKind::TmpRw
            | ContractMetadataKind::SlotRo
            | ContractMetadataKind::SlotRw
            | ContractMetadataKind::Input
            | ContractMetadataKind::Output
            | ContractMetadataKind::Return => {
                return Err(MetadataDecodingError::ExpectedMethodKind { metadata_kind });
            }
        };

        let method_allowed = match container_kind {
            MethodsContainerKind::Contract | MethodsContainerKind::Unknown => match method_kind {
                MethodKind::Init
                | MethodKind::UpdateStateless
                | MethodKind::UpdateStatefulRo
                | MethodKind::UpdateStatefulRw
                | MethodKind::ViewStateless
                | MethodKind::ViewStateful => true,
            },
            MethodsContainerKind::Trait => match method_kind {
                MethodKind::Init
                | MethodKind::UpdateStatefulRo
                | MethodKind::UpdateStatefulRw
                | MethodKind::ViewStateful => false,
                MethodKind::UpdateStateless | MethodKind::ViewStateless => true,
            },
        };

        if !method_allowed {
            return Err(MetadataDecodingError::UnexpectedMethodKind {
                method_kind,
                container_kind,
            });
        }

        // Decode method name
        let method_name_length = usize::from(
            *metadata
                .split_off_first()
                .ok_or(MetadataDecodingError::NotEnoughMetadata)?,
        );

        let method_name = metadata
            .split_off(..method_name_length)
            .ok_or(MetadataDecodingError::NotEnoughMetadata)?;

        // Decode the number of arguments
        let num_arguments = *metadata
            .split_off_first()
            .ok_or(MetadataDecodingError::NotEnoughMetadata)?;

        // `self` is not in metadata, but counts towards `MAX_TOTAL_METHOD_ARGS` in methods with it
        let number_of_arguments = num_arguments.saturating_add(u8::from(method_kind.has_self()));
        if number_of_arguments > MAX_TOTAL_METHOD_ARGS {
            return Err(MetadataDecodingError::TooManyArguments {
                number_of_arguments,
            });
        }

        // The state is the last argument of `#[init]`, the arguments decoder checks its kind
        if matches!(method_kind, MethodKind::Init) && num_arguments == 0 {
            return Err(MetadataDecodingError::InitWithoutState);
        }

        let decoder = ArgumentsMetadataDecoder {
            metadata,
            method_kind,
            container_kind,
            remaining: num_arguments,
            next_position: ArgumentPosition::Env,
        };
        let item = MethodMetadataItem {
            method_name,
            method_kind,
            num_arguments,
        };

        Ok((decoder, item))
    }
}

#[derive(Debug, Copy, Clone)]
pub enum ArgumentKind {
    /// Corresponds to [`ContractMetadataKind::EnvRo`]
    EnvRo,
    /// Corresponds to [`ContractMetadataKind::EnvRw`]
    EnvRw,
    /// Corresponds to [`ContractMetadataKind::TmpRo`]
    TmpRo,
    /// Corresponds to [`ContractMetadataKind::TmpRw`]
    TmpRw,
    /// Corresponds to [`ContractMetadataKind::SlotRo`]
    SlotRo,
    /// Corresponds to [`ContractMetadataKind::SlotRw`]
    SlotRw,
    /// Corresponds to [`ContractMetadataKind::Input`]
    Input,
    /// Corresponds to [`ContractMetadataKind::Output`]
    Output,
    /// Corresponds to [`ContractMetadataKind::Return`]
    Return,
}

/// Position of an argument in the order that `#[contract]` generates, see
/// [`ContractMetadataKind::Init`]
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd)]
enum ArgumentPosition {
    Env,
    Tmp,
    Slots,
    Inputs,
    Outputs,
    Return,
    /// After the return value, where no argument can be
    End,
}

#[derive(Debug)]
pub struct ArgumentMetadataItem<'metadata> {
    /// Argument name as bytes.
    ///
    /// Expected to be UTF-8, but must be parsed before printed as text, which is somewhat costly.
    pub argument_name: &'metadata [u8],
    pub argument_kind: ArgumentKind,
    /// Exceptions:
    /// * `None` for `#[env]`, `#[tmp]` and `#[slot]`
    /// * `None` for the last `#[output]` or return type otherwise in `#[init]` (see
    ///   [`ContractMetadataKind::Init`] for details)
    pub type_details: Option<IoTypeDetails>,
}

#[derive(Debug)]
pub struct ArgumentsMetadataDecoder<'a, 'metadata> {
    metadata: &'a mut &'metadata [u8],
    method_kind: MethodKind,
    container_kind: MethodsContainerKind,
    remaining: u8,
    /// The earliest position that the next argument can have
    next_position: ArgumentPosition,
}

impl Drop for ArgumentsMetadataDecoder<'_, '_> {
    fn drop(&mut self) {
        let metadata_before = *self.metadata;
        while let Some(maybe_argument_metadata_item) = self.decode_next() {
            if maybe_argument_metadata_item.is_err() {
                // Restore original metadata if decoding failed so it fails decoding later, this is
                // a compromise to avoid panics on `drop`
                *self.metadata = metadata_before;
                break;
            }
        }
    }
}

impl<'metadata> ArgumentsMetadataDecoder<'_, 'metadata> {
    /// Get a wrapped value that does not automatically drain the metadata on `drop`.
    ///
    /// The default behavior is to automatically drain the metadata on `drop` such that
    /// contract/trait or method metadata decoding progresses successfully, even when the caller
    /// doesn't care about arguments. This, however, generates more code and causes difficulties for
    /// LLVM when it tries to optimize the code and especially when trying to prove the lack of
    /// panics. Usually this method is not needed, but if you are having difficulties with
    /// `no-panic` and either decoding a single method or drain arguments explicitly, you can use
    /// this helper method to work around compiler limitations.
    pub fn without_auto_drain(self) -> ManuallyDrop<Self> {
        ManuallyDrop::new(self)
    }

    /// The number of bytes left in the metadata that were not processed yet
    #[inline(always)]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    pub fn remaining_metadata_bytes(&self) -> usize {
        self.metadata.len()
    }

    /// Decode the next argument, returning `None` after [`MethodMetadataItem::num_arguments`]
    /// items, errors included.
    ///
    /// Arguments are returned in the order that `#[contract]` generates them in, which
    /// [`ContractMetadataKind::Init`] describes. An argument out of that order is rejected with
    /// [`MetadataDecodingError::ArgumentOutOfOrder`]. The last argument of `#[init]` is always its
    /// state, otherwise [`MetadataDecodingError::InitWithoutState`] is returned.
    #[inline]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    pub fn decode_next<'a>(
        &'a mut self,
    ) -> Option<Result<ArgumentMetadataItem<'metadata>, MetadataDecodingError<'metadata>>> {
        if self.remaining == 0 {
            return None;
        }

        self.remaining -= 1;

        Some(self.decode_argument())
    }

    #[inline(always)]
    #[cfg_attr(feature = "no-panic", no_panic::no_panic)]
    fn decode_argument<'a>(
        &'a mut self,
    ) -> Result<ArgumentMetadataItem<'metadata>, MetadataDecodingError<'metadata>> {
        // Decode method kind
        let metadata_kind = *self
            .metadata
            .split_off_first()
            .ok_or(MetadataDecodingError::NotEnoughMetadata)?;
        let metadata_kind = ContractMetadataKind::try_from(metadata_kind).map_err(|()| {
            MetadataDecodingError::InvalidFirstMetadataByte {
                byte: metadata_kind,
            }
        })?;

        let argument_kind = match metadata_kind {
            ContractMetadataKind::EnvRo => ArgumentKind::EnvRo,
            ContractMetadataKind::EnvRw => ArgumentKind::EnvRw,
            ContractMetadataKind::TmpRo => ArgumentKind::TmpRo,
            ContractMetadataKind::TmpRw => ArgumentKind::TmpRw,
            ContractMetadataKind::SlotRo => ArgumentKind::SlotRo,
            ContractMetadataKind::SlotRw => ArgumentKind::SlotRw,
            ContractMetadataKind::Input => ArgumentKind::Input,
            ContractMetadataKind::Output => ArgumentKind::Output,
            ContractMetadataKind::Return => ArgumentKind::Return,
            // The rest are not arguments and can't appear here
            ContractMetadataKind::Contract
            | ContractMetadataKind::Trait
            | ContractMetadataKind::Init
            | ContractMetadataKind::UpdateStateless
            | ContractMetadataKind::UpdateStatefulRo
            | ContractMetadataKind::UpdateStatefulRw
            | ContractMetadataKind::ViewStateless
            | ContractMetadataKind::ViewStateful => {
                return Err(MetadataDecodingError::ExpectedArgumentKind { metadata_kind });
            }
        };

        let argument_allowed = match self.method_kind {
            MethodKind::Init
            | MethodKind::UpdateStateless
            | MethodKind::UpdateStatefulRo
            | MethodKind::UpdateStatefulRw => match argument_kind {
                ArgumentKind::EnvRo
                | ArgumentKind::EnvRw
                | ArgumentKind::TmpRo
                | ArgumentKind::TmpRw
                | ArgumentKind::SlotRo
                | ArgumentKind::SlotRw
                | ArgumentKind::Input
                | ArgumentKind::Output
                | ArgumentKind::Return => true,
            },
            MethodKind::ViewStateless | MethodKind::ViewStateful => match argument_kind {
                ArgumentKind::EnvRo
                | ArgumentKind::SlotRo
                | ArgumentKind::Input
                | ArgumentKind::Output
                | ArgumentKind::Return => true,
                ArgumentKind::EnvRw
                | ArgumentKind::TmpRo
                | ArgumentKind::TmpRw
                | ArgumentKind::SlotRw => false,
            },
        };

        // `#[tmp]` and `#[slot]` types are defined by a contract, so methods of traits have none
        let argument_allowed_in_container = match self.container_kind {
            MethodsContainerKind::Contract | MethodsContainerKind::Unknown => true,
            MethodsContainerKind::Trait => match argument_kind {
                ArgumentKind::EnvRo
                | ArgumentKind::EnvRw
                | ArgumentKind::Input
                | ArgumentKind::Output
                | ArgumentKind::Return => true,
                ArgumentKind::TmpRo
                | ArgumentKind::TmpRw
                | ArgumentKind::SlotRo
                | ArgumentKind::SlotRw => false,
            },
        };

        if !argument_allowed || !argument_allowed_in_container {
            return Err(MetadataDecodingError::UnexpectedArgumentKind {
                argument_kind,
                method_kind: self.method_kind,
                container_kind: self.container_kind,
            });
        }

        // The position of the argument and the earliest position of the next one. `#[env]`,
        // `#[tmp]` and the return value appear at most once, so the next argument must come after
        // them.
        let (position, next_position) = match argument_kind {
            ArgumentKind::EnvRo | ArgumentKind::EnvRw => {
                (ArgumentPosition::Env, ArgumentPosition::Tmp)
            }
            ArgumentKind::TmpRo | ArgumentKind::TmpRw => {
                (ArgumentPosition::Tmp, ArgumentPosition::Slots)
            }
            ArgumentKind::SlotRo | ArgumentKind::SlotRw => {
                (ArgumentPosition::Slots, ArgumentPosition::Slots)
            }
            ArgumentKind::Input => (ArgumentPosition::Inputs, ArgumentPosition::Inputs),
            ArgumentKind::Output => (ArgumentPosition::Outputs, ArgumentPosition::Outputs),
            ArgumentKind::Return => (ArgumentPosition::Return, ArgumentPosition::End),
        };
        if position < self.next_position {
            return Err(MetadataDecodingError::ArgumentOutOfOrder { argument_kind });
        }
        self.next_position = next_position;

        let last_argument = self.remaining == 0;
        // The last argument of `#[init]` is the state, see `ContractMetadataKind::Init` for details
        if matches!(self.method_kind, MethodKind::Init)
            && last_argument
            && !matches!(argument_kind, ArgumentKind::Output | ArgumentKind::Return)
        {
            return Err(MetadataDecodingError::InitWithoutState);
        }

        let (argument_name, type_details) = match argument_kind {
            ArgumentKind::EnvRo | ArgumentKind::EnvRw => ("env".as_bytes(), None),
            ArgumentKind::TmpRo
            | ArgumentKind::TmpRw
            | ArgumentKind::SlotRo
            | ArgumentKind::SlotRw
            | ArgumentKind::Input
            | ArgumentKind::Output
            | ArgumentKind::Return => {
                // Decode argument name
                let argument_name_length = usize::from(
                    *self
                        .metadata
                        .split_off_first()
                        .ok_or(MetadataDecodingError::NotEnoughMetadata)?,
                );
                let argument_name = self
                    .metadata
                    .split_off(..argument_name_length)
                    .ok_or(MetadataDecodingError::NotEnoughMetadata)?;

                let recommended_capacity = match argument_kind {
                    ArgumentKind::EnvRo
                    | ArgumentKind::EnvRw
                    | ArgumentKind::TmpRo
                    | ArgumentKind::TmpRw
                    | ArgumentKind::SlotRo
                    | ArgumentKind::SlotRw => None,
                    ArgumentKind::Input => {
                        let decoded =
                            IoTypeMetadataKind::type_details::<MAX_METADATA_DEPTH>(self.metadata);
                        let recommended_capacity;
                        (recommended_capacity, *self.metadata) =
                            decoded.ok_or(MetadataDecodingError::InvalidArgumentIoType {
                                argument_name,
                                argument_kind,
                            })?;

                        Some(recommended_capacity)
                    }
                    ArgumentKind::Output | ArgumentKind::Return => {
                        // May be skipped for `#[init]`, see `ContractMetadataKind::Init` for
                        // details
                        if matches!((self.method_kind, last_argument), (MethodKind::Init, true)) {
                            None
                        } else {
                            let decoded = IoTypeMetadataKind::type_details::<MAX_METADATA_DEPTH>(
                                self.metadata,
                            );
                            let recommended_capacity;
                            (recommended_capacity, *self.metadata) =
                                decoded.ok_or(MetadataDecodingError::InvalidArgumentIoType {
                                    argument_name,
                                    argument_kind,
                                })?;

                            Some(recommended_capacity)
                        }
                    }
                };

                (argument_name, recommended_capacity)
            }
        };

        Ok(ArgumentMetadataItem {
            argument_name,
            argument_kind,
            type_details,
        })
    }
}