git.delta.rocks / unique-network / refs/commits / 0257bf04211b

1//! # A module for custom signature support.2//!3//! ## Overview4//! This module allows you to create arbitrary signatures for types and functions in compile time.5//!6//! ### Type signatures7//! To create the desired type signature, you need to create your own trait with the `SIGNATURE` constant.8//! Then in the implementation, for the required type, use the macro [`make_signature`]9//! #### Example10//! ```11//! use std::str::from_utf8;12//! use evm_coder::make_signature;13//! use evm_coder::custom_signature::{14//! 	SignatureUnit,15//! 	SIGNATURE_SIZE_LIMIT16//! };17//!18//! // Create trait for our signature19//! trait SoliditySignature {20//!		const SIGNATURE: SignatureUnit;21//!22//!		fn name() -> &'static str {23//!			from_utf8(&Self::SIGNATURE.data[..Self::SIGNATURE.len]).expect("bad utf-8")24//!		}25//!	}26//!27//! // Make signatures for some types28//!	impl SoliditySignature for u8 {29//!		make_signature!(new fixed("uint8"));30//!	}31//!	impl SoliditySignature for u32 {32//!		make_signature!(new fixed("uint32"));33//!	}34//!	impl<T: SoliditySignature> SoliditySignature for Vec<T> {35//!		make_signature!(new nameof(T) fixed("[]"));36//!	}37//!	impl<A: SoliditySignature, B: SoliditySignature> SoliditySignature for (A, B) {38//!		make_signature!(new fixed("(") nameof(A) fixed(",") nameof(B) fixed(")"));39//!	}40//!	impl<A: SoliditySignature> SoliditySignature for (A,) {41//!		make_signature!(new fixed("(") nameof(A) fixed(",") shift_left(1) fixed(")"));42//!	}43//!44//! assert_eq!(u8::name(), "uint8");45//! assert_eq!(<Vec<u8>>::name(), "uint8[]");46//! assert_eq!(<(u32, u8)>::name(), "(uint32,uint8)");47//! ```48//!49//! ### Function signatures50//! To create a function signature, the macro [`make_signature`] is also used, which accepts51//! settings for the function format [`SignaturePreferences`] and function parameters [`SignatureUnit`]52//! #### Example53//! ```54//! use core::str::from_utf8;55//! use evm_coder::{56//!		make_signature,57//!		custom_signature::{58//!			SIGNATURE_SIZE_LIMIT, SignatureUnit, SignaturePreferences, FunctionSignature,59//!		},60//!	};61//! // Trait for our signature62//! trait SoliditySignature {63//!		const SIGNATURE: SignatureUnit;64//!65//!		fn name() -> &'static str {66//!			from_utf8(&Self::SIGNATURE.data[..Self::SIGNATURE.len]).expect("bad utf-8")67//!		}68//!	}69//!70//! // Make signatures for some types71//!	impl SoliditySignature for u8 {72//!		make_signature!(new fixed("uint8"));73//!	}74//!	impl<T: SoliditySignature> SoliditySignature for Vec<T> {75//!		make_signature!(new nameof(T) fixed("[]"));76//!	}77//!78//! // Function signature settings79//! const SIGNATURE_PREFERENCES: SignaturePreferences = SignaturePreferences {80//!		open_name: Some(SignatureUnit::new("some_funk")),81//!		open_delimiter: Some(SignatureUnit::new("(")),82//!		param_delimiter: Some(SignatureUnit::new(",")),83//!		close_delimiter: Some(SignatureUnit::new(")")),84//!		close_name: None,85//!	};86//!87//! // Create functions signatures88//! fn make_func_without_args() {89//!		const SIG: FunctionSignature = make_signature!(90//!			new fn(SIGNATURE_PREFERENCES),91//!		);92//!		let name = SIG.as_str();93//!		similar_asserts::assert_eq!(name, "some_funk()");94//!	}95//!96//! fn make_func_with_3_args() {97//!		const SIG: FunctionSignature = make_signature!(98//!			new fn(SIGNATURE_PREFERENCES),99//!			(<u8>::SIGNATURE),100//!			(<u8>::SIGNATURE),101//!			(<Vec<u8>>::SIGNATURE),102//!		);103//!		let name = SIG.as_str();104//!		similar_asserts::assert_eq!(name, "some_funk(uint8,uint8,uint8[])");105//!	}106//! ```107use core::str::from_utf8;108109/// The maximum length of the signature.110pub const SIGNATURE_SIZE_LIMIT: usize = 256;111112/// Function signature formatting preferences.113#[derive(Debug)]114pub struct SignaturePreferences {115	/// The name of the function before the list of parameters: `*some*(param1,param2)func`116	pub open_name: Option<SignatureUnit>,117	/// Opening separator: `some*(*param1,param2)func`118	pub open_delimiter: Option<SignatureUnit>,119	/// Parameters separator: `some(param1*,*param2)func`120	pub param_delimiter: Option<SignatureUnit>,121	/// Closinging separator: `some(param1,param2*)*func`122	pub close_delimiter: Option<SignatureUnit>,123	/// The name of the function after the list of parameters: `some(param1,param2)*func*`124	pub close_name: Option<SignatureUnit>,125}126127/// Constructs and stores the signature of the function.128#[derive(Debug)]129pub struct FunctionSignature {130	/// Storage for function signature.131	pub unit: SignatureUnit,132	preferences: SignaturePreferences,133}134135impl FunctionSignature {136	/// Start constructing the signature. It is written to the storage137	/// [`SignaturePreferences::open_name`] and [`SignaturePreferences::open_delimiter`].138	pub const fn new(preferences: SignaturePreferences) -> FunctionSignature {139		let mut dst = [0_u8; SIGNATURE_SIZE_LIMIT];140		let mut dst_offset = 0;141		if let Some(ref name) = preferences.open_name {142			crate::make_signature!(@copy(name.data, dst, name.len, dst_offset));143		}144		if let Some(ref delimiter) = preferences.open_delimiter {145			crate::make_signature!(@copy(delimiter.data, dst, delimiter.len, dst_offset));146		}147		FunctionSignature {148			unit: SignatureUnit {149				data: dst,150				len: dst_offset,151			},152			preferences,153		}154	}155156	/// Add a function parameter to the signature. It is written to the storage157	/// `param` [`SignatureUnit`] and [`SignaturePreferences::param_delimiter`].158	pub const fn add_param(159		signature: FunctionSignature,160		param: SignatureUnit,161	) -> FunctionSignature {162		let mut dst = signature.unit.data;163		let mut dst_offset = signature.unit.len;164		crate::make_signature!(@copy(param.data, dst, param.len, dst_offset));165		if let Some(ref delimiter) = signature.preferences.param_delimiter {166			crate::make_signature!(@copy(delimiter.data, dst, delimiter.len, dst_offset));167		}168		FunctionSignature {169			unit: SignatureUnit {170				data: dst,171				len: dst_offset,172			},173			..signature174		}175	}176177	/// Complete signature construction. It is written to the storage178	/// [`SignaturePreferences::close_delimiter`] and [`SignaturePreferences::close_name`].179	pub const fn done(signature: FunctionSignature, owerride: bool) -> FunctionSignature {180		let mut dst = signature.unit.data;181		let mut dst_offset = signature.unit.len - if owerride { 1 } else { 0 };182		if let Some(ref delimiter) = signature.preferences.close_delimiter {183			crate::make_signature!(@copy(delimiter.data, dst, delimiter.len, dst_offset));184		}185		if let Some(ref name) = signature.preferences.close_name {186			crate::make_signature!(@copy(name.data, dst, name.len, dst_offset));187		}188		FunctionSignature {189			unit: SignatureUnit {190				data: dst,191				len: dst_offset,192			},193			..signature194		}195	}196197	/// Represent the signature as `&str'.198	pub fn as_str(&self) -> &str {199		from_utf8(&self.unit.data[..self.unit.len]).expect("bad utf-8")200	}201}202203/// Storage for the signature or its elements.204#[derive(Debug)]205pub struct SignatureUnit {206	/// Signature data.207	pub data: [u8; SIGNATURE_SIZE_LIMIT],208	/// The actual size of the data.209	pub len: usize,210}211212impl SignatureUnit {213	/// Create a signature from `&str'.214	pub const fn new(name: &'static str) -> SignatureUnit {215		let mut signature = [0_u8; SIGNATURE_SIZE_LIMIT];216		let name = name.as_bytes();217		let name_len = name.len();218		let mut dst_offset = 0;219		crate::make_signature!(@copy(name, signature, name_len, dst_offset));220		SignatureUnit {221			data: signature,222			len: name_len,223		}224	}225}226227/// ### Macro to create signatures of types and functions.228///229/// Format for creating a type of signature:230/// ```ignore231/// make_signature!(new fixed("uint8")); // Simple type232/// make_signature!(new fixed("(") nameof(u8) fixed(",") nameof(u8) fixed(")")); // Composite type233/// ```234/// Format for creating a function of the function:235/// ```ignore236/// const SIG: FunctionSignature = make_signature!(237///		new fn(SIGNATURE_PREFERENCES),238///		(u8::SIGNATURE),239///		(<(u8,u8)>::SIGNATURE),240///	);241/// ```242#[macro_export]243macro_rules! make_signature {244	(new fn($func:expr)$(,)+) => {245		{246			let fs = FunctionSignature::new($func);247			let fs = FunctionSignature::done(fs, false);248			fs249		}250	};251	(new fn($func:expr), $($tt:tt,)*) => {252		{253			let fs = FunctionSignature::new($func);254			let fs = make_signature!(@param; fs, $($tt),*);255			fs256		}257	};258259	(@param; $func:expr) => {260		FunctionSignature::done($func, true)261	};262	(@param; $func:expr, $param:expr) => {263		make_signature!(@param; FunctionSignature::add_param($func, $param))264	};265	(@param; $func:expr, $param:expr, $($tt:tt),*) => {266		make_signature!(@param; FunctionSignature::add_param($func, $param), $($tt),*)267	};268269    (new $($tt:tt)*) => {270        const SIGNATURE: SignatureUnit = SignatureUnit {271			data: {272				let mut out = [0u8; SIGNATURE_SIZE_LIMIT];273				let mut dst_offset = 0;274				make_signature!(@data(out, dst_offset); $($tt)*);275				out276			},277			len: {0 + make_signature!(@size; $($tt)*)},278        };279    };280281    (@size;) => {282        0283    };284    (@size; fixed($expr:expr) $($tt:tt)*) => {285        $expr.len() + make_signature!(@size; $($tt)*)286    };287    (@size; nameof($expr:ty) $($tt:tt)*) => {288		<$expr>::SIGNATURE.len + make_signature!(@size; $($tt)*)289    };290	(@size; shift_left($expr:expr) $($tt:tt)*) => {291		make_signature!(@size; $($tt)*) - $expr292	};293294    (@data($dst:ident, $dst_offset:ident);) => {};295    (@data($dst:ident, $dst_offset:ident); fixed($expr:expr) $($tt:tt)*) => {296        {297            let data = $expr.as_bytes();298			let data_len = data.len();299			make_signature!(@copy(data, $dst, data_len, $dst_offset));300        }301        make_signature!(@data($dst, $dst_offset); $($tt)*)302    };303    (@data($dst:ident, $dst_offset:ident); nameof($expr:ty) $($tt:tt)*) => {304        {305            make_signature!(@copy(&<$expr>::SIGNATURE.data, $dst, <$expr>::SIGNATURE.len, $dst_offset));306        }307        make_signature!(@data($dst, $dst_offset); $($tt)*)308    };309	(@data($dst:ident, $dst_offset:ident); shift_left($expr:expr) $($tt:tt)*) => {310        $dst_offset -= $expr;311        make_signature!(@data($dst, $dst_offset); $($tt)*)312    };313314	(@copy($src:expr, $dst:expr, $src_len:expr, $dst_offset:ident)) => {315		{316			let mut src_offset = 0;317			let src_len: usize = $src_len;318			while src_offset < src_len {319				$dst[$dst_offset] = $src[src_offset];320				$dst_offset += 1;321				src_offset += 1;322			}323		}324	}325}326327#[cfg(test)]328mod test {329	use core::str::from_utf8;330331	use super::{SIGNATURE_SIZE_LIMIT, SignatureUnit, FunctionSignature, SignaturePreferences};332333	trait Name {334		const SIGNATURE: SignatureUnit;335336		fn name() -> &'static str {337			from_utf8(&Self::SIGNATURE.data[..Self::SIGNATURE.len]).expect("bad utf-8")338		}339	}340341	impl Name for u8 {342		make_signature!(new fixed("uint8"));343	}344	impl Name for u32 {345		make_signature!(new fixed("uint32"));346	}347	impl<T: Name> Name for Vec<T> {348		make_signature!(new nameof(T) fixed("[]"));349	}350	impl<A: Name, B: Name> Name for (A, B) {351		make_signature!(new fixed("(") nameof(A) fixed(",") nameof(B) fixed(")"));352	}353	impl<A: Name> Name for (A,) {354		make_signature!(new fixed("(") nameof(A) fixed(",") shift_left(1) fixed(")"));355	}356357	struct MaxSize();358	impl Name for MaxSize {359		const SIGNATURE: SignatureUnit = SignatureUnit {360			data: [b'!'; SIGNATURE_SIZE_LIMIT],361			len: SIGNATURE_SIZE_LIMIT,362		};363	}364365	const SIGNATURE_PREFERENCES: SignaturePreferences = SignaturePreferences {366		open_name: Some(SignatureUnit::new("some_funk")),367		open_delimiter: Some(SignatureUnit::new("(")),368		param_delimiter: Some(SignatureUnit::new(",")),369		close_delimiter: Some(SignatureUnit::new(")")),370		close_name: None,371	};372373	#[test]374	fn simple() {375		assert_eq!(u8::name(), "uint8");376		assert_eq!(u32::name(), "uint32");377	}378379	#[test]380	fn vector_of_simple() {381		assert_eq!(<Vec<u8>>::name(), "uint8[]");382		assert_eq!(<Vec<u32>>::name(), "uint32[]");383	}384385	#[test]386	fn vector_of_vector() {387		assert_eq!(<Vec<Vec<u8>>>::name(), "uint8[][]");388	}389390	#[test]391	fn tuple_of_simple() {392		assert_eq!(<(u32, u8)>::name(), "(uint32,uint8)");393	}394395	#[test]396	fn tuple_of_tuple() {397		assert_eq!(398			<((u32, u8), (u8, u32))>::name(),399			"((uint32,uint8),(uint8,uint32))"400		);401	}402403	#[test]404	fn vector_of_tuple() {405		assert_eq!(<Vec<(u32, u8)>>::name(), "(uint32,uint8)[]");406	}407408	#[test]409	fn tuple_of_vector() {410		assert_eq!(<(Vec<u32>, u8)>::name(), "(uint32[],uint8)");411	}412413	#[test]414	fn complex() {415		assert_eq!(416			<(Vec<u32>, (u32, Vec<u8>))>::name(),417			"(uint32[],(uint32,uint8[]))"418		);419	}420421	#[test]422	fn max_size() {423		assert_eq!(<MaxSize>::name(), "!".repeat(SIGNATURE_SIZE_LIMIT));424	}425426	// This test must NOT compile with "index out of bounds"!427	// #[test]428	// fn over_max_size() {429	// 	assert_eq!(430	// 		<Vec<MaxSize>>::name(),431	// 		"!".repeat(SIGNATURE_SIZE_LIMIT) + "[]"432	// 	);433	// }434435	#[test]436	fn make_func_without_args() {437		const SIG: FunctionSignature = make_signature!(438			new fn(SIGNATURE_PREFERENCES),439		);440		let name = SIG.as_str();441		similar_asserts::assert_eq!(name, "some_funk()");442	}443444	#[test]445	fn make_func_with_1_args() {446		const SIG: FunctionSignature = make_signature!(447			new fn(SIGNATURE_PREFERENCES),448			(<u8>::SIGNATURE),449		);450		let name = SIG.as_str();451		similar_asserts::assert_eq!(name, "some_funk(uint8)");452	}453454	#[test]455	fn make_func_with_2_args() {456		const SIG: FunctionSignature = make_signature!(457			new fn(SIGNATURE_PREFERENCES),458			(u8::SIGNATURE),459			(<Vec<u32>>::SIGNATURE),460		);461		let name = SIG.as_str();462		similar_asserts::assert_eq!(name, "some_funk(uint8,uint32[])");463	}464465	#[test]466	fn make_func_with_3_args() {467		const SIG: FunctionSignature = make_signature!(468			new fn(SIGNATURE_PREFERENCES),469			(<u8>::SIGNATURE),470			(<u32>::SIGNATURE),471			(<Vec<u32>>::SIGNATURE),472		);473		let name = SIG.as_str();474		similar_asserts::assert_eq!(name, "some_funk(uint8,uint32,uint32[])");475	}476477	#[test]478	fn make_slice_from_signature() {479		const SIG: FunctionSignature = make_signature!(480			new fn(SIGNATURE_PREFERENCES),481			(<u8>::SIGNATURE),482			(<u32>::SIGNATURE),483			(<Vec<u32>>::SIGNATURE),484		);485		const NAME: [u8; SIG.unit.len] = {486			let mut name: [u8; SIG.unit.len] = [0; SIG.unit.len];487			let mut i = 0;488			while i < SIG.unit.len {489				name[i] = SIG.unit.data[i];490				i += 1;491			}492			name493		};494		similar_asserts::assert_eq!(&NAME, b"some_funk(uint8,uint32,uint32[])");495	}496497	#[test]498	fn shift() {499		assert_eq!(<(u32,)>::name(), "(uint32)");500	}501}