ink_primitives/sol/

encodable.rs

// Copyright (C) ink! contributors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

use alloy_sol_types::utils::words_for_len;
use ink_prelude::vec::Vec;

use super::encoder::Encoder;

/// A Solidity ABI encodable representation for a type.
///
///
/// # Note
///
/// An analog of `Token` and `TokenSeq` with only encoding operations.
///
/// References:
///
/// - <https://github.com/alloy-rs/core/blob/49b7bce463cce6e987a8fb9a987acbf4ec4297a6/crates/sol-types/src/abi/token.rs#L54>
/// - <https://github.com/alloy-rs/core/blob/49b7bce463cce6e987a8fb9a987acbf4ec4297a6/crates/sol-types/src/abi/token.rs#L85>
//
// # Design Notes
//
// This trait allows us to encode using local abstractions, notably
// `TokenOrDefault`, `FixedSizeDefault` and `DynSizeDefault`, for which we can't implement
// `Token` nor `TokenSeq` because those are "sealed" traits in `alloy_sol_types`.
pub trait Encodable: private::Sealed {
    /// True for dynamic types.
    const DYNAMIC: bool;

    /// Number of words in the head.
    fn head_words(&self) -> usize;

    /// Number of words in the tail.
    fn tail_words(&self) -> usize;

    /// Total number of head and tails words.
    #[inline(always)]
    fn total_words(&self) -> usize {
        self.head_words() + self.tail_words()
    }

    /// Append head words to the encoder.
    fn head_append(&self, encoder: &mut Encoder);

    /// Append tail words to the encoder.
    fn tail_append(&self, encoder: &mut Encoder);

    /// Append both head and tail words to the encoder.
    fn encode(&self, encoder: &mut Encoder) {
        if <Self as Encodable>::DYNAMIC {
            // Head is the offset for dynamic types.
            let mut main_encoder = encoder.segment(self.head_words());
            Encodable::head_append(self, &mut main_encoder);
            // Only dynamic types have tails, which contain the "actual data".
            let mut tail_encoder = main_encoder.take_tail(self.tail_words());
            Encodable::tail_append(self, &mut tail_encoder);
        } else {
            // Head is the actual data for fixed size types.
            Encodable::head_append(self, encoder);
        }
    }
}

/// Either a `Token` based (i.e. "actual value") or "default value" (i.e.
/// `FixedSizeDefault` or `DynSizeDefault`) based representation.
#[derive(Debug)]
pub enum TokenOrDefault<T, D> {
    Token(T),
    Default(D),
}

/// A fixed-size type.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct FixedSizeDefault(usize);

impl FixedSizeDefault {
    /// Empty data.
    pub const EMPTY: Self = Self(0);

    /// A single word.
    pub const WORD: Self = Self(1);

    /// A fixed size number of words (e.g. for encoding `bytesN`).
    pub const fn words(size: usize) -> Self {
        Self(size)
    }
}

/// A dynamic type.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DynSizeDefault;

impl Encodable for FixedSizeDefault {
    const DYNAMIC: bool = false;

    fn head_words(&self) -> usize {
        // All the data is in the head.
        self.0
    }

    fn tail_words(&self) -> usize {
        // No tail words, because all the data is in the head, or it's empty.
        0
    }

    fn head_append(&self, encoder: &mut Encoder) {
        match self.0 {
            0 => (),
            n => {
                // Appends `n` empty words.
                encoder.fill(0, n);
            }
        }
    }

    fn tail_append(&self, _: &mut Encoder) {}
}

impl private::Sealed for FixedSizeDefault {}

impl Encodable for DynSizeDefault {
    const DYNAMIC: bool = true;

    fn head_words(&self) -> usize {
        // offset.
        1
    }

    fn tail_words(&self) -> usize {
        // length (i.e. zero), no "actual data".
        1
    }

    fn head_append(&self, encoder: &mut Encoder) {
        // Appends offset.
        encoder.append_offset();
    }

    fn tail_append(&self, encoder: &mut Encoder) {
        encoder.append_length(0);
    }
}

impl private::Sealed for DynSizeDefault {}

impl<T, D> Encodable for TokenOrDefault<T, D>
where
    T: Encodable,
    D: Encodable,
{
    const DYNAMIC: bool = T::DYNAMIC;

    fn head_words(&self) -> usize {
        match self {
            TokenOrDefault::Token(token) => token.head_words(),
            TokenOrDefault::Default(default) => default.head_words(),
        }
    }

    fn tail_words(&self) -> usize {
        match self {
            TokenOrDefault::Token(token) => token.tail_words(),
            TokenOrDefault::Default(default) => default.tail_words(),
        }
    }

    fn head_append(&self, encoder: &mut Encoder) {
        match self {
            TokenOrDefault::Token(token) => token.head_append(encoder),
            TokenOrDefault::Default(default) => default.head_append(encoder),
        }
    }

    fn tail_append(&self, encoder: &mut Encoder) {
        match self {
            TokenOrDefault::Token(token) => token.tail_append(encoder),
            TokenOrDefault::Default(default) => default.tail_append(encoder),
        }
    }
}

impl<T, D> private::Sealed for TokenOrDefault<T, D> {}

/// A Solidity ABI word (i.e. 32 bytes).
//
// # Design Notes
//
// We need this wrapper because an implementation of `Encodable` for `[u8; 32]` would
// conflict with one for `[T; N]`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(transparent)]
pub struct Word(pub [u8; 32]);

// Analog of `WordToken` but with `T` bound being `Encodable` instead of `Token`.
//
// Ref: <https://github.com/alloy-rs/core/blob/49b7bce463cce6e987a8fb9a987acbf4ec4297a6/crates/sol-types/src/abi/token.rs#L185>
impl Encodable for Word {
    const DYNAMIC: bool = false;

    fn head_words(&self) -> usize {
        // All the data is in the head.
        1
    }

    fn tail_words(&self) -> usize {
        // No tail words, because all the data is in the head.
        0
    }

    fn head_append(&self, encoder: &mut Encoder) {
        // Appends the data.
        encoder.append_word(self.0);
    }

    fn tail_append(&self, _: &mut Encoder) {}
}

impl private::Sealed for Word {}

// Analog of `FixedSeqToken` but with `T` bound being `Encodable` instead of `Token` and
// `TokenSeq`.
//
// Ref: <https://github.com/alloy-rs/core/blob/49b7bce463cce6e987a8fb9a987acbf4ec4297a6/crates/sol-types/src/abi/token.rs#L253>
impl<T, const N: usize> Encodable for [T; N]
where
    T: Encodable,
{
    const DYNAMIC: bool = T::DYNAMIC;

    fn head_words(&self) -> usize {
        if Self::DYNAMIC {
            // offset.
            1
        } else {
            // elements.
            self.iter().map(T::total_words).sum()
        }
    }

    fn tail_words(&self) -> usize {
        if Self::DYNAMIC {
            // elements.
            self.iter().map(T::total_words).sum()
        } else {
            0
        }
    }

    fn head_append(&self, encoder: &mut Encoder) {
        if Self::DYNAMIC {
            // Appends offset.
            encoder.append_offset();
        } else {
            // Appends "actual data".
            for inner in self {
                inner.head_append(encoder);
            }
        }
    }

    fn tail_append(&self, encoder: &mut Encoder) {
        // Appends "actual data" to the tail for dynamic elements.
        if Self::DYNAMIC {
            encode_sequence(self, encoder);
        }
    }
}

impl<T, const N: usize> private::Sealed for [T; N] {}

// Analog of `DynSeqToken` but with `T` bound being `Encodable` instead of `Token` and
// `TokenSeq`.
//
// Ref: <https://github.com/alloy-rs/core/blob/49b7bce463cce6e987a8fb9a987acbf4ec4297a6/crates/sol-types/src/abi/token.rs#L366>
impl<T> Encodable for Vec<T>
where
    T: Encodable,
{
    const DYNAMIC: bool = true;

    fn head_words(&self) -> usize {
        // offset.
        1
    }

    fn tail_words(&self) -> usize {
        // length + elements.
        1 + self.iter().map(T::total_words).sum::<usize>()
    }

    fn head_append(&self, encoder: &mut Encoder) {
        // Adds offset.
        encoder.append_offset();
    }

    fn tail_append(&self, encoder: &mut Encoder) {
        // Appends length.
        encoder.append_length(self.len());

        // Appends "actual data".
        encode_sequence(self, encoder);
    }
}

impl<T> private::Sealed for Vec<T> {}

// Analog of `PackedSeqToken` but with `T` bound being `Encodable` instead of `Token`.
//
// Ref: <https://github.com/alloy-rs/core/blob/49b7bce463cce6e987a8fb9a987acbf4ec4297a6/crates/sol-types/src/abi/token.rs#L466>
impl Encodable for &[u8] {
    const DYNAMIC: bool = true;

    fn head_words(&self) -> usize {
        // offset.
        1
    }

    fn tail_words(&self) -> usize {
        // length + data words.
        1 + words_for_len(self.len())
    }

    fn head_append(&self, encoder: &mut Encoder) {
        // Adds offset.
        encoder.append_offset();
    }

    fn tail_append(&self, encoder: &mut Encoder) {
        // Appends length + "actual data".
        encoder.append_length(self.len());
        encoder.append_bytes(self);
    }
}

impl private::Sealed for &[u8] {}

/// Similar to `TokenSeq::encode_sequence` implementations for `FixedSeqToken` and
/// `DynSeqToken` but with `T` bound being `Encodable` instead of `Token`.
///
/// References:
/// - <https://github.com/alloy-rs/core/blob/49b7bce463cce6e987a8fb9a987acbf4ec4297a6/crates/sol-types/src/abi/token.rs#L305>
/// - <https://github.com/alloy-rs/core/blob/49b7bce463cce6e987a8fb9a987acbf4ec4297a6/crates/sol-types/src/abi/token.rs#L409>
fn encode_sequence<T>(tokens: &[T], encoder: &mut Encoder)
where
    T: Encodable,
{
    if T::DYNAMIC {
        let head_words = tokens.iter().map(T::head_words).sum();
        let mut main_encoder = encoder.segment(head_words);
        for inner in tokens {
            inner.head_append(&mut main_encoder);
            let mut tail_encoder = main_encoder.take_tail(inner.tail_words());
            inner.tail_append(&mut tail_encoder);
        }
    } else {
        tokens.iter().for_each(|inner| inner.head_append(encoder));
    }
}

/// A Solidity ABI encodable representation of function parameters.
///
/// # Note
///
/// This trait is only implemented for tuples which also implement [`Encodable`].
pub trait EncodableParams: private::Sealed {
    /// Encode the function parameters into the encoder.
    fn encode_params(&self, encoder: &mut Encoder);
}

/// Generates `EncodableParams` implementation body for an n-ary tuple where n >= 1.
// NOTE: operation is a noop for unit (i.e. `()`).
macro_rules! impl_encodable_params {
    ($source: ident, $encoder: ident => ($($ty:ident),+$(,)*)) => {
        let ($($ty,)+) = $source;

        if Self::DYNAMIC {
            let head_words = 0 $( + $ty.head_words() )+;
            let mut main_encoder = $encoder.segment(head_words);

            $(
                $ty.head_append(&mut main_encoder);
                if $ty::DYNAMIC {
                    let mut tail_encoder = main_encoder.take_tail($ty.tail_words());
                    $ty.tail_append(&mut tail_encoder);
                }
            )+
        } else {
            $( $ty.head_append($encoder); )+
        }
    };
}

/// Similar to tuple implementations for `T: Token` and `T: TokenSeq` but with
/// `T: Encodable` as the bound.
///
/// Ref: <https://github.com/alloy-rs/core/blob/49b7bce463cce6e987a8fb9a987acbf4ec4297a6/crates/sol-types/src/abi/token.rs#L521>
// `impl-trait-for-tuples` doesn't support using `||` as a separator needed for
// `Encodable::DYNAMIC`, so we fallback to a declarative macro.
macro_rules! impl_encodable {
    ($($ty:ident),+) => {
        #[allow(non_snake_case)]
        impl<$($ty: Encodable,)+> Encodable for ($($ty,)+) {
            const DYNAMIC: bool = $(<$ty as Encodable>::DYNAMIC )||+;

            #[inline]
            fn head_words(&self) -> usize {
                if Self::DYNAMIC {
                    // offset
                    1
                } else {
                    // elements
                    let ($($ty,)+) = self;
                    0 $( + $ty.total_words() )+
                }
            }

            #[inline]
            fn tail_words(&self) -> usize {
                if Self::DYNAMIC {
                    // elements
                    let ($($ty,)+) = self;
                    0 $( + $ty.total_words() )+
                } else {
                    0
                }
            }

            #[inline]
            fn head_append(&self, encoder: &mut Encoder) {
                if Self::DYNAMIC {
                    encoder.append_offset();
                } else {
                    let ($($ty,)+) = self;
                    $(
                        $ty.head_append(encoder);
                    )+
                }
            }

            #[inline]
            fn tail_append(&self, encoder: &mut Encoder) {
                if Self::DYNAMIC {
                    impl_encodable_params!(self, encoder => ($($ty,)+));
                }
            }
        }

        #[allow(non_snake_case)]
        impl<$($ty: Encodable,)+> EncodableParams for ($($ty,)+) {
            fn encode_params(&self, encoder: &mut Encoder) {
                impl_encodable_params!(self, encoder => ($($ty,)+));
            }
        }

        impl<$($ty: Encodable,)+> private::Sealed for ($($ty,)+) {}
    };
}

impl_all_tuples!(@nonempty impl_encodable);

// Similar to optimized `Token` and `TokenSeq` implementation for `()`, but for
// `Encodable`.
//
// Ref: <https://github.com/alloy-rs/core/blob/49b7bce463cce6e987a8fb9a987acbf4ec4297a6/crates/sol-types/src/abi/token.rs#L616>
impl Encodable for () {
    const DYNAMIC: bool = false;

    #[inline]
    fn head_words(&self) -> usize {
        0
    }

    #[inline]
    fn tail_words(&self) -> usize {
        0
    }

    #[inline]
    fn head_append(&self, _: &mut Encoder) {}

    #[inline]
    fn tail_append(&self, _: &mut Encoder) {}

    #[inline]
    fn encode(&self, _: &mut Encoder) {}
}

impl EncodableParams for () {
    fn encode_params(&self, _: &mut Encoder) {}
}

impl private::Sealed for () {}

pub(super) mod private {
    /// Seals implementations of `Encodable`.
    pub trait Sealed {}
}