git.delta.rocks / unique-network / refs/commits / c0989353baf4

--- a/crates/evm-coder/Cargo.toml
+++ b/crates/evm-coder/Cargo.toml
@@ -5,15 +5,21 @@
 edition = "2021"
 
 [dependencies]
-evm-coder-macros = { path = "../evm-coder-macros" }
+# evm-coder reexports those proc-macro
+evm-coder-procedural = { path = "./procedural" }
+# Evm uses primitive-types for H160, H256 and others
 primitive-types = { version = "0.11.1", default-features = false }
-hex-literal = "0.3.3"
+# Evm doesn't have reexports for log and others
 ethereum = { version = "0.12.0", default-features = false }
+# Error types for execution
 evm-core = { default-features = false, git = "https://github.com/uniquenetwork/evm", branch = "unique-polkadot-v0.9.27" }
-impl-trait-for-tuples = "0.2.1"
+# We have tuple-heavy code in solidity.rs
+impl-trait-for-tuples = "0.2.2"
 
 [dev-dependencies]
+# We want to assert some large binary blobs equality in tests
 hex = "0.4.3"
+hex-literal = "0.3.4"
 
 [features]
 default = ["std"]

--- a/crates/evm-coder/procedural/Cargo.toml
+++ b/crates/evm-coder/procedural/Cargo.toml
@@ -8,9 +8,12 @@
 proc-macro = true
 
 [dependencies]
+# Ethereum uses keccak (=sha3) for selectors
 sha3 = "0.10.1"
+# Value formatting
+hex = "0.4.3"
+Inflector = "0.11.4"
+# General proc-macro utilities
 quote = "1.0"
 proc-macro2 = "1.0"
 syn = { version = "1.0", features = ["full"] }
-hex = "0.4.3"
-Inflector = "0.11.4"

--- a/crates/evm-coder/procedural/src/lib.rs
+++ b/crates/evm-coder/procedural/src/lib.rs
@@ -21,8 +21,8 @@
 use quote::quote;
 use sha3::{Digest, Keccak256};
 use syn::{
-	DeriveInput, GenericArgument, Ident, ItemImpl, Pat, Path, PathArguments,
-	PathSegment, Type, parse_macro_input, spanned::Spanned,
+	DeriveInput, GenericArgument, Ident, ItemImpl, Pat, Path, PathArguments, PathSegment, Type,
+	parse_macro_input, spanned::Spanned,
 };
 
 mod solidity_interface;
@@ -199,58 +199,7 @@
 	Ident::new(&name, ident.span())
 }
 
-/// Derives call enum implementing [`evm_coder::Callable`], [`evm_coder::Weighted`]
-/// and [`evm_coder::Call`] from impl block
-///
-/// ## Macro syntax
-///
-/// `#[solidity_interface(name, is, inline_is, events)]`
-/// - *name*: used in generated code, and for Call enum name
-/// - *is*: used to provide call inheritance, not found methods will be delegated to all contracts
-/// specified in is/inline_is
-/// - *inline_is*: same as is, but selectors for passed contracts will be used by derived ERC165
-/// implementation
-///
-/// `#[weight(value)]`
-/// Can be added to every method of impl block, used for deriving [`evm_coder::Weighted`], which
-/// is used by substrate bridge
-/// - *value*: expression, which evaluates to weight required to call this method.
-/// This expression can use call arguments to calculate non-constant execution time.
-/// This expression should evaluate faster than actual execution does, and may provide worser case
-/// than one is called
-///
-/// `#[solidity_interface(rename_selector)]`
-/// - *rename_selector*: by default, selector name will be generated by transforming method name
-/// from snake_case to camelCase. Use this option, if other naming convention is required.
-/// I.e: method `token_uri` will be automatically renamed to `tokenUri` in selector, but name
-/// required by ERC721 standard is `tokenURI`, thus we need to specify `rename_selector = "tokenURI"`
-/// explicitly
-///
-/// Also, any contract method may have doc comments, which will be automatically added to generated
-/// solidity interface definitions
-///
-/// ## Example
-///
-/// ```ignore
-/// struct SuperContract;
-/// struct InlineContract;
-/// struct Contract;
-///
-/// #[derive(ToLog)]
-/// enum ContractEvents {
-///     Event(#[indexed] uint32),
-/// }
-///
-/// #[solidity_interface(name = MyContract, is(SuperContract), inline_is(InlineContract))]
-/// impl Contract {
-///     /// Multiply two numbers
-///     #[weight(200 + a + b)]
-///     #[solidity_interface(rename_selector = "mul")]
-///     fn mul(&mut self, a: uint32, b: uint32) -> Result<uint32> {
-///         Ok(a.checked_mul(b).ok_or("overflow")?)
-///     }
-/// }
-/// ```
+/// See documentation for this proc-macro reexported in `evm-coder` crate
 #[proc_macro_attribute]
 pub fn solidity_interface(args: TokenStream, stream: TokenStream) -> TokenStream {
 	let args = parse_macro_input!(args as solidity_interface::InterfaceInfo);
@@ -282,10 +231,7 @@
 	stream
 }
 
-/// ## Syntax
-///
-/// `#[indexed]`
-/// Marks this field as indexed, so it will appear in [`ethereum::Log`] topics instead of data
+/// See documentation for this proc-macro reexported in `evm-coder` crate
 #[proc_macro_derive(ToLog, attributes(indexed))]
 pub fn to_log(value: TokenStream) -> TokenStream {
 	let input = parse_macro_input!(value as DeriveInput);

14// You should have received a copy of the GNU General Public License14// You should have received a copy of the GNU General Public License
15// along with Unique Network. If not, see <http://www.gnu.org/licenses/>.15// along with Unique Network. If not, see <http://www.gnu.org/licenses/>.
1616
17//! TODO: I misunterstood therminology, abi IS rlp encoded, so17//! Implementation of EVM RLP reader/writer
18//! this module should be replaced with rlp crate
1918
20#![allow(dead_code)]19#![allow(dead_code)]
2120
3231
33const ABI_ALIGNMENT: usize = 32;32const ABI_ALIGNMENT: usize = 32;
3433
34/// View into RLP data, which provides method to read typed items from it
35#[derive(Clone)]35#[derive(Clone)]
36pub struct AbiReader<'i> {36pub struct AbiReader<'i> {
37	buf: &'i [u8],37	buf: &'i [u8],
38	subresult_offset: usize,38	subresult_offset: usize,
39	offset: usize,39	offset: usize,
40}40}
41impl<'i> AbiReader<'i> {41impl<'i> AbiReader<'i> {
42	/// Start reading RLP buffer, assuming there is no padding bytes
42	pub fn new(buf: &'i [u8]) -> Self {43	pub fn new(buf: &'i [u8]) -> Self {
43		Self {44		Self {
44			buf,45			buf,
45			subresult_offset: 0,46			subresult_offset: 0,
46			offset: 0,47			offset: 0,
47		}48		}
48	}49	}
50	/// Start reading RLP buffer, parsing first 4 bytes as selector
49	pub fn new_call(buf: &'i [u8]) -> Result<(types::bytes4, Self)> {51	pub fn new_call(buf: &'i [u8]) -> Result<(types::bytes4, Self)> {
50		if buf.len() < 4 {52		if buf.len() < 4 {
51			return Err(Error::Error(ExitError::OutOfOffset));53			return Err(Error::Error(ExitError::OutOfOffset));
109		)111		)
110	}112	}
111113
114	/// Read [`H160`] at current position, then advance
112	pub fn address(&mut self) -> Result<H160> {115	pub fn address(&mut self) -> Result<H160> {
113		Ok(H160(self.read_padleft()?))116		Ok(H160(self.read_padleft()?))
114	}117	}
115118
119	/// Read [`bool`] at current position, then advance
116	pub fn bool(&mut self) -> Result<bool> {120	pub fn bool(&mut self) -> Result<bool> {
117		let data: [u8; 1] = self.read_padleft()?;121		let data: [u8; 1] = self.read_padleft()?;
118		match data[0] {122		match data[0] {
122		}126		}
123	}127	}
124128
129	/// Read [`[u8; 4]`] at current position, then advance
125	pub fn bytes4(&mut self) -> Result<[u8; 4]> {130	pub fn bytes4(&mut self) -> Result<[u8; 4]> {
126		self.read_padright()131		self.read_padright()
127	}132	}
128133
134	/// Read [`Vec<u8>`] at current position, then advance
129	pub fn bytes(&mut self) -> Result<Vec<u8>> {135	pub fn bytes(&mut self) -> Result<Vec<u8>> {
130		let mut subresult = self.subresult()?;136		let mut subresult = self.subresult()?;
131		let length = subresult.read_usize()?;137		let length = subresult.uint32()? as usize;
132		if subresult.buf.len() < subresult.offset + length {138		if subresult.buf.len() < subresult.offset + length {
133			return Err(Error::Error(ExitError::OutOfOffset));139			return Err(Error::Error(ExitError::OutOfOffset));
134		}140		}
135		Ok(subresult.buf[subresult.offset..subresult.offset + length].into())141		Ok(subresult.buf[subresult.offset..subresult.offset + length].into())
136	}142	}
143
144	/// Read [`string`] at current position, then advance
137	pub fn string(&mut self) -> Result<string> {145	pub fn string(&mut self) -> Result<string> {
138		string::from_utf8(self.bytes()?).map_err(|_| Error::Error(ExitError::InvalidRange))146		string::from_utf8(self.bytes()?).map_err(|_| Error::Error(ExitError::InvalidRange))
139	}147	}
140148
149	/// Read [`u8`] at current position, then advance
141	pub fn uint8(&mut self) -> Result<u8> {150	pub fn uint8(&mut self) -> Result<u8> {
142		Ok(self.read_padleft::<1>()?[0])151		Ok(self.read_padleft::<1>()?[0])
143	}152	}
144153
154	/// Read [`u32`] at current position, then advance
145	pub fn uint32(&mut self) -> Result<u32> {155	pub fn uint32(&mut self) -> Result<u32> {
146		Ok(u32::from_be_bytes(self.read_padleft()?))156		Ok(u32::from_be_bytes(self.read_padleft()?))
147	}157	}
148158
159	/// Read [`u128`] at current position, then advance
149	pub fn uint128(&mut self) -> Result<u128> {160	pub fn uint128(&mut self) -> Result<u128> {
150		Ok(u128::from_be_bytes(self.read_padleft()?))161		Ok(u128::from_be_bytes(self.read_padleft()?))
151	}162	}
152163
164	/// Read [`U256`] at current position, then advance
153	pub fn uint256(&mut self) -> Result<U256> {165	pub fn uint256(&mut self) -> Result<U256> {
154		let buf: [u8; 32] = self.read_padleft()?;166		let buf: [u8; 32] = self.read_padleft()?;
155		Ok(U256::from_big_endian(&buf))167		Ok(U256::from_big_endian(&buf))
156	}168	}
157169
170	/// Read [`u64`] at current position, then advance
158	pub fn uint64(&mut self) -> Result<u64> {171	pub fn uint64(&mut self) -> Result<u64> {
159		Ok(u64::from_be_bytes(self.read_padleft()?))172		Ok(u64::from_be_bytes(self.read_padleft()?))
160	}173	}
161174
175	/// Read [`usize`] at current position, then advance
176	#[deprecated = "dangerous, as usize may have different width in wasm and native execution"]
162	pub fn read_usize(&mut self) -> Result<usize> {177	pub fn read_usize(&mut self) -> Result<usize> {
163		Ok(usize::from_be_bytes(self.read_padleft()?))178		Ok(usize::from_be_bytes(self.read_padleft()?))
164	}179	}
165180
181	/// Slice recursive buffer, advance one word for buffer offset
166	fn subresult(&mut self) -> Result<AbiReader<'i>> {182	fn subresult(&mut self) -> Result<AbiReader<'i>> {
167		let offset = self.read_usize()?;183		let offset = self.uint32()? as usize;
168		if offset + self.subresult_offset > self.buf.len() {184		if offset + self.subresult_offset > self.buf.len() {
169			return Err(Error::Error(ExitError::InvalidRange));185			return Err(Error::Error(ExitError::InvalidRange));
170		}186		}
175		})191		})
176	}192	}
177193
194	/// Is this parser reached end of buffer?
178	pub fn is_finished(&self) -> bool {195	pub fn is_finished(&self) -> bool {
179		self.buf.len() == self.offset196		self.buf.len() == self.offset
180	}197	}
181}198}
182199
200/// Writer for RLP encoded data
183#[derive(Default)]201#[derive(Default)]
184pub struct AbiWriter {202pub struct AbiWriter {
185	static_part: Vec<u8>,203	static_part: Vec<u8>,
186	dynamic_part: Vec<(usize, AbiWriter)>,204	dynamic_part: Vec<(usize, AbiWriter)>,
187	had_call: bool,205	had_call: bool,
188}206}
189impl AbiWriter {207impl AbiWriter {
208	/// Initialize internal buffers for output data, assuming no padding required
190	pub fn new() -> Self {209	pub fn new() -> Self {
191		Self::default()210		Self::default()
192	}211	}
212	/// Initialize internal buffers, inserting method selector at beginning
193	pub fn new_call(method_id: u32) -> Self {213	pub fn new_call(method_id: u32) -> Self {
194		let mut val = Self::new();214		let mut val = Self::new();
195		val.static_part.extend(&method_id.to_be_bytes());215		val.static_part.extend(&method_id.to_be_bytes());
211			.extend(&[0; ABI_ALIGNMENT][0..ABI_ALIGNMENT - bytes.len()]);231			.extend(&[0; ABI_ALIGNMENT][0..ABI_ALIGNMENT - bytes.len()]);
212	}232	}
213233
234	/// Write [`H160`] to end of buffer
214	pub fn address(&mut self, address: &H160) {235	pub fn address(&mut self, address: &H160) {
215		self.write_padleft(&address.0)236		self.write_padleft(&address.0)
216	}237	}
217238
239	/// Write [`bool`] to end of buffer
218	pub fn bool(&mut self, value: &bool) {240	pub fn bool(&mut self, value: &bool) {
219		self.write_padleft(&[if *value { 1 } else { 0 }])241		self.write_padleft(&[if *value { 1 } else { 0 }])
220	}242	}
221243
244	/// Write [`u8`] to end of buffer
222	pub fn uint8(&mut self, value: &u8) {245	pub fn uint8(&mut self, value: &u8) {
223		self.write_padleft(&[*value])246		self.write_padleft(&[*value])
224	}247	}
225248
249	/// Write [`u32`] to end of buffer
226	pub fn uint32(&mut self, value: &u32) {250	pub fn uint32(&mut self, value: &u32) {
227		self.write_padleft(&u32::to_be_bytes(*value))251		self.write_padleft(&u32::to_be_bytes(*value))
228	}252	}
229253
254	/// Write [`u128`] to end of buffer
230	pub fn uint128(&mut self, value: &u128) {255	pub fn uint128(&mut self, value: &u128) {
231		self.write_padleft(&u128::to_be_bytes(*value))256		self.write_padleft(&u128::to_be_bytes(*value))
232	}257	}
233258
259	/// Write [`U256`] to end of buffer
234	pub fn uint256(&mut self, value: &U256) {260	pub fn uint256(&mut self, value: &U256) {
235		let mut out = [0; 32];261		let mut out = [0; 32];
236		value.to_big_endian(&mut out);262		value.to_big_endian(&mut out);
237		self.write_padleft(&out)263		self.write_padleft(&out)
238	}264	}
239265
266	/// Write [`usize`] to end of buffer
267	#[deprecated = "dangerous, as usize may have different width in wasm and native execution"]
240	pub fn write_usize(&mut self, value: &usize) {268	pub fn write_usize(&mut self, value: &usize) {
241		self.write_padleft(&usize::to_be_bytes(*value))269		self.write_padleft(&usize::to_be_bytes(*value))
242	}270	}
243271
272	/// Append recursive data, writing pending offset at end of buffer
244	pub fn write_subresult(&mut self, result: Self) {273	pub fn write_subresult(&mut self, result: Self) {
245		self.dynamic_part.push((self.static_part.len(), result));274		self.dynamic_part.push((self.static_part.len(), result));
246		// Empty block, to be filled later275		// Empty block, to be filled later
247		self.write_padleft(&[]);276		self.write_padleft(&[]);
248	}277	}
249278
250	pub fn memory(&mut self, value: &[u8]) {279	fn memory(&mut self, value: &[u8]) {
251		let mut sub = Self::new();280		let mut sub = Self::new();
252		sub.write_usize(&value.len());281		sub.uint32(&(value.len() as u32));
253		for chunk in value.chunks(ABI_ALIGNMENT) {282		for chunk in value.chunks(ABI_ALIGNMENT) {
254			sub.write_padright(chunk);283			sub.write_padright(chunk);
255		}284		}
256		self.write_subresult(sub);285		self.write_subresult(sub);
257	}286	}
258287
288	/// Append recursive [`str`] at end of buffer
259	pub fn string(&mut self, value: &str) {289	pub fn string(&mut self, value: &str) {
260		self.memory(value.as_bytes())290		self.memory(value.as_bytes())
261	}291	}
262292
293	/// Append recursive [`[u8]`] at end of buffer
263	pub fn bytes(&mut self, value: &[u8]) {294	pub fn bytes(&mut self, value: &[u8]) {
264		self.memory(value)295		self.memory(value)
265	}296	}
266297
298	/// Finish writer, concatenating all internal buffers
267	pub fn finish(mut self) -> Vec<u8> {299	pub fn finish(mut self) -> Vec<u8> {
268		for (static_offset, part) in self.dynamic_part {300		for (static_offset, part) in self.dynamic_part {
269			let part_offset = self.static_part.len() - self.had_call.then(|| 4).unwrap_or(0);301			let part_offset = self.static_part.len() - self.had_call.then(|| 4).unwrap_or(0);
278	}310	}
279}311}
280312
313/// [`AbiReader`] implements reading of many types, but it should
314/// be limited to types defined in spec
315///
316/// As this trait can't be made sealed,
317/// instead of having `impl AbiRead for T`, we have `impl AbiRead<T> for AbiReader`
281pub trait AbiRead<T> {318pub trait AbiRead<T> {
319	/// Read item from current position, advanding decoder
282	fn abi_read(&mut self) -> Result<T>;320	fn abi_read(&mut self) -> Result<T>;
283}321}
284322
318{356{
319	fn abi_read(&mut self) -> Result<Vec<R>> {357	fn abi_read(&mut self) -> Result<Vec<R>> {
320		let mut sub = self.subresult()?;358		let mut sub = self.subresult()?;
321		let size = sub.read_usize()?;359		let size = sub.uint32()? as usize;
322		sub.subresult_offset = sub.offset;360		sub.subresult_offset = sub.offset;
323		let mut out = Vec::with_capacity(size);361		let mut out = Vec::with_capacity(size);
324		for _ in 0..size {362		for _ in 0..size {
366impl_tuples! {A B C D E F G H I}404impl_tuples! {A B C D E F G H I}
367impl_tuples! {A B C D E F G H I J}405impl_tuples! {A B C D E F G H I J}
368406
407/// For questions about inability to provide custom implementations,
408/// see [`AbiRead`]
369pub trait AbiWrite {409pub trait AbiWrite {
410	/// Write value to end of specified encoder
370	fn abi_write(&self, writer: &mut AbiWriter);411	fn abi_write(&self, writer: &mut AbiWriter);
412	/// Specialization for [`crate::solidity_interface`] implementation,
413	/// see comment in `impl AbiWrite for ResultWithPostInfo`
371	fn to_result(&self) -> ResultWithPostInfo<AbiWriter> {414	fn to_result(&self) -> ResultWithPostInfo<AbiWriter> {
372		let mut writer = AbiWriter::new();415		let mut writer = AbiWriter::new();
373		self.abi_write(&mut writer);416		self.abi_write(&mut writer);
374		Ok(writer.into())417		Ok(writer.into())
375	}418	}
376}419}
377420
421/// This particular AbiWrite implementation should be split to another trait,
422/// which only implements `to_result`, but due to lack of specialization feature
423/// in stable Rust, we can't have blanket impl of this trait `for T where T: AbiWrite`,
424/// so here we abusing default trait methods for it
378impl<T: AbiWrite> AbiWrite for ResultWithPostInfo<T> {425impl<T: AbiWrite> AbiWrite for ResultWithPostInfo<T> {
379	// this particular AbiWrite implementation should be split to another trait,
380	// which only implements [`to_result`]
381	//
382	// But due to lack of specialization feature in stable Rust, we can't have
383	// blanket impl of this trait `for T where T: AbiWrite`, so here we abusing
384	// default trait methods for it
385	fn abi_write(&self, _writer: &mut AbiWriter) {426	fn abi_write(&self, _writer: &mut AbiWriter) {
386		debug_assert!(false, "shouldn't be called, see comment")427		debug_assert!(false, "shouldn't be called, see comment")
387	}428	}
432	fn abi_write(&self, _writer: &mut AbiWriter) {}473	fn abi_write(&self, _writer: &mut AbiWriter) {}
433}474}
434475
476/// Helper macros to parse reader into variables
477#[deprecated]
435#[macro_export]478#[macro_export]
436macro_rules! abi_decode {479macro_rules! abi_decode {
437	($reader:expr, $($name:ident: $typ:ident),+ $(,)?) => {480	($reader:expr, $($name:ident: $typ:ident),+ $(,)?) => {
441	}484	}
442}485}
486
487/// Helper macros to construct RLP-encoded buffer
488#[deprecated]
443#[macro_export]489#[macro_export]
444macro_rules! abi_encode {490macro_rules! abi_encode {
445	($($typ:ident($value:expr)),* $(,)?) => {{491	($($typ:ident($value:expr)),* $(,)?) => {{

--- a/crates/evm-coder/src/events.rs
+++ b/crates/evm-coder/src/events.rs
@@ -19,11 +19,23 @@
 
 use crate::types::*;
 
+/// Implementation of this trait should not be written manually,
+/// instead use [`crate::ToLog`] proc macros.
+///
+/// See also [`evm_coder_procedural::ToLog`], [solidity docs on events](https://docs.soliditylang.org/en/develop/contracts.html#events)
 pub trait ToLog {
+	/// Convert event to [`ethereum::Log`].
+	/// Because event by itself doesn't contains current contract
+	/// address, it should be specified manually.
 	fn to_log(&self, contract: H160) -> Log;
 }
 
+/// Only items implementing `ToTopic` may be used as `#[indexed]` field
+/// in [`crate::ToLog`] macro usage.
+///
+/// See also (solidity docs on events)[<https://docs.soliditylang.org/en/develop/contracts.html#events>]
 pub trait ToTopic {
+	/// Convert value to topic to be used in [`ethereum::Log`]
 	fn to_topic(&self) -> H256;
 }
 

--- a/crates/evm-coder/src/execution.rs
+++ b/crates/evm-coder/src/execution.rs
@@ -14,6 +14,8 @@
 // You should have received a copy of the GNU General Public License
 // along with Unique Network. If not, see <http://www.gnu.org/licenses/>.
 
+//! Contract execution related types
+
 #[cfg(not(feature = "std"))]
 use alloc::string::{String, ToString};
 use evm_core::{ExitError, ExitFatal};
@@ -22,10 +24,14 @@
 
 use crate::Weight;
 
+/// Execution error, should be convertible between EVM and Substrate.
 #[derive(Debug, Clone)]
 pub enum Error {
+	/// Non-fatal contract error occured
 	Revert(String),
+	/// EVM fatal error
 	Fatal(ExitFatal),
+	/// EVM normal error
 	Error(ExitError),
 }
 
@@ -38,9 +44,12 @@
 	}
 }
 
+/// To be used in [`crate::solidity_interface`] implementation.
 pub type Result<T> = core::result::Result<T, Error>;
 
+/// Static information collected from [`crate::weight`].
 pub struct DispatchInfo {
+	/// Statically predicted call weight
 	pub weight: Weight,
 }
 
@@ -55,16 +64,22 @@
 	}
 }
 
+/// Weight information that is only available post dispatch.
+/// Note: This can only be used to reduce the weight or fee, not increase it.
 #[derive(Default, Clone)]
 pub struct PostDispatchInfo {
+	/// Actual weight consumed by call
 	actual_weight: Option<Weight>,
 }
 
 impl PostDispatchInfo {
+	/// Calculate amount to be returned back to user
 	pub fn calc_unspent(&self, info: &DispatchInfo) -> Weight {
 		info.weight - self.calc_actual_weight(info)
 	}
 
+	/// Calculate actual cansumed weight, saturating to weight reported
+	/// pre-dispatch
 	pub fn calc_actual_weight(&self, info: &DispatchInfo) -> Weight {
 		if let Some(actual_weight) = self.actual_weight {
 			actual_weight.min(info.weight)
@@ -74,9 +89,12 @@
 	}
 }
 
+/// Wrapper for PostDispatchInfo and any user-provided data
 #[derive(Clone)]
 pub struct WithPostDispatchInfo<T> {
+	/// User provided data
 	pub data: T,
+	/// Info known after dispatch
 	pub post_info: PostDispatchInfo,
 }
 
@@ -89,5 +107,6 @@
 	}
 }
 
+/// Return type of items in [`crate::solidity_interface`] definition
 pub type ResultWithPostInfo<T> =
 	core::result::Result<WithPostDispatchInfo<T>, WithPostDispatchInfo<Error>>;

--- a/crates/evm-coder/src/lib.rs
+++ b/crates/evm-coder/src/lib.rs
@@ -14,22 +14,102 @@
 // You should have received a copy of the GNU General Public License
 // along with Unique Network. If not, see <http://www.gnu.org/licenses/>.
 
+#![doc = include_str!("../README.md")]
+#![deny(missing_docs)]
 #![cfg_attr(not(feature = "std"), no_std)]
 #[cfg(not(feature = "std"))]
 extern crate alloc;
 
 use abi::{AbiRead, AbiReader, AbiWriter};
-pub use evm_coder_macros::{event_topic, fn_selector, solidity_interface, solidity, weight, ToLog};
+pub use evm_coder_procedural::{event_topic, fn_selector};
 pub mod abi;
-pub mod events;
-pub use events::ToLog;
+pub use events::{ToLog, ToTopic};
 use execution::DispatchInfo;
 pub mod execution;
+
+/// Derives call enum implementing [`crate::Callable`], [`crate::Weighted`]
+/// and [`crate::Call`] from impl block.
+///
+/// ## Macro syntax
+///
+/// `#[solidity_interface(name, is, inline_is, events)]`
+/// - *name* - used in generated code, and for Call enum name
+/// - *is* - used to provide call inheritance, not found methods will be delegated to all contracts
+/// specified in is/inline_is
+/// - *inline_is* - same as is, but selectors for passed contracts will be used by derived ERC165
+/// implementation
+///
+/// `#[weight(value)]`
+/// Can be added to every method of impl block, used for deriving [`crate::Weighted`], which
+/// is used by substrate bridge.
+/// - *value*: expression, which evaluates to weight required to call this method.
+/// This expression can use call arguments to calculate non-constant execution time.
+/// This expression should evaluate faster than actual execution does, and may provide worser case
+/// than one is called.
+///
+/// `#[solidity_interface(rename_selector)]`
+/// - *rename_selector* - by default, selector name will be generated by transforming method name
+/// from snake_case to camelCase. Use this option, if other naming convention is required.
+/// I.e: method `token_uri` will be automatically renamed to `tokenUri` in selector, but name
+/// required by ERC721 standard is `tokenURI`, thus we need to specify `rename_selector = "tokenURI"`
+/// explicitly.
+///
+/// Both contract and contract methods may have doccomments, which will end up in a generated
+/// solidity interface file, thus you should use [solidity syntax](https://docs.soliditylang.org/en/latest/natspec-format.html) for writing documentation in this macro
+///
+/// ## Example
+///
+/// ```ignore
+/// struct SuperContract;
+/// struct InlineContract;
+/// struct Contract;
+///
+/// #[derive(ToLog)]
+/// enum ContractEvents {
+///     Event(#[indexed] uint32),
+/// }
+///
+/// /// @dev This contract provides function to multiply two numbers
+/// #[solidity_interface(name = MyContract, is(SuperContract), inline_is(InlineContract))]
+/// impl Contract {
+///     /// Multiply two numbers
+/// 	/// @param a First number
+/// 	/// @param b Second number
+/// 	/// @return uint32 Product of two passed numbers
+/// 	/// @dev This function returns error in case of overflow
+///     #[weight(200 + a + b)]
+///     #[solidity_interface(rename_selector = "mul")]
+///     fn mul(&mut self, a: uint32, b: uint32) -> Result<uint32> {
+///         Ok(a.checked_mul(b).ok_or("overflow")?)
+///     }
+/// }
+/// ```
+pub use evm_coder_procedural::solidity_interface;
+/// See [`solidity_interface`]
+pub use evm_coder_procedural::solidity;
+/// See [`solidity_interface`]
+pub use evm_coder_procedural::weight;
+
+/// Derives [`ToLog`] for enum
+///
+/// Selectors will be derived from variant names, there is currently no way to have custom naming
+/// for them
+///
+/// `#[indexed]`
+/// Marks this field as indexed, so it will appear in [`ethereum::Log`] topics instead of data
+pub use evm_coder_procedural::ToLog;
+
+// Api of those modules shouldn't be consumed directly, it is only exported for usage in proc macros
+#[doc(hidden)]
+pub mod events;
+#[doc(hidden)]
 pub mod solidity;
 
-/// Solidity type definitions
+/// Solidity type definitions (aliases from solidity name to rust type)
+/// To be used in [`solidity_interface`] definitions, to make sure there is no
+/// type conflict between Rust code and generated definitions
 pub mod types {
-	#![allow(non_camel_case_types)]
+	#![allow(non_camel_case_types, missing_docs)]
 
 	#[cfg(not(feature = "std"))]
 	use alloc::{vec::Vec};
@@ -54,6 +134,8 @@
 	pub type string = ::std::string::String;
 	pub type bytes = Vec<u8>;
 
+	/// Solidity doesn't have `void` type, however we have special implementation
+	/// for empty tuple return type
 	pub type void = ();
 
 	//#region Special types
@@ -63,36 +145,64 @@
 	pub type caller = address;
 	//#endregion
 
+	/// Ethereum typed call message, similar to solidity
+	/// `msg` object.
 	pub struct Msg<C> {
 		pub call: C,
+		/// Address of user, which called this contract.
 		pub caller: H160,
+		/// Payment amount to contract.
+		/// Contract should reject payment, if target call is not payable,
+		/// and there is no `receiver()` function defined.
 		pub value: U256,
 	}
 }
 
+/// Parseable EVM call, this trait should be implemented with [`solidity_interface`] macro
 pub trait Call: Sized {
+	/// Parse call buffer into typed call enum
 	fn parse(selector: types::bytes4, input: &mut AbiReader) -> execution::Result<Option<Self>>;
 }
 
+/// Intended to be used as `#[weight]` output type
+/// Should be same between evm-coder and substrate to avoid confusion
+///
+/// Isn't same thing as gas, some mapping is required between those types
 pub type Weight = u64;
 
+/// In substrate, we have benchmarking, which allows
+/// us to not rely on gas metering, but instead predict amount of gas to execute call
 pub trait Weighted: Call {
+	/// Predict weight of this call
 	fn weight(&self) -> DispatchInfo;
 }
 
+/// Type callable with ethereum message, may be implemented by [`solidity_interface`] macro
+/// on interface implementation, or for externally-owned real EVM contract
 pub trait Callable<C: Call> {
+	/// Call contract using specified call data
 	fn call(&mut self, call: types::Msg<C>) -> execution::ResultWithPostInfo<AbiWriter>;
 }
 
-/// Implementation is implicitly provided for all interfaces
+/// Implementation of ERC165 is implicitly generated for all interfaces in [`solidity_interface`],
+/// this structure holds parsed data for ERC165Call subvariant
+///
+/// Note: no [`Callable`] implementation is provided, call implementation is inlined into every
+/// implementing contract
 ///
-/// Note: no Callable implementation is provided
+/// See <https://eips.ethereum.org/EIPS/eip-165>
 #[derive(Debug)]
 pub enum ERC165Call {
-	SupportsInterface { interface_id: types::bytes4 },
+	/// ERC165 provides single method, which returns true, if contract
+	/// implements specified interface
+	SupportsInterface {
+		/// Requested interface
+		interface_id: types::bytes4,
+	},
 }
 
 impl ERC165Call {
+	/// ERC165 selector is provided by standard
 	pub const INTERFACE_ID: types::bytes4 = u32::to_be_bytes(0x01ffc9a7);
 }
 

--- a/crates/evm-coder/src/solidity.rs
+++ b/crates/evm-coder/src/solidity.rs
@@ -14,15 +14,15 @@
 // You should have received a copy of the GNU General Public License
 // along with Unique Network. If not, see <http://www.gnu.org/licenses/>.
 
-//! Implementation detail of [`evm_coder::solidity_interface`] macro code-generation
+//! Implementation detail of [`crate::solidity_interface`] macro code-generation.
+//! You should not rely on any public item from this module, as it is only intended to be used
+//! by procedural macro, API and output format may be changed at any time.
+//!
+//! Purpose of this module is to receive solidity contract definition in module-specified
+//! format, and then output string, representing interface of this contract in solidity language
 
 #[cfg(not(feature = "std"))]
-use alloc::{
-	string::String,
-	vec::Vec,
-	collections::BTreeMap,
-	format,
-};
+use alloc::{string::String, vec::Vec, collections::BTreeMap, format};
 #[cfg(feature = "std")]
 use std::collections::BTreeMap;
 use core::{
@@ -81,8 +81,10 @@
 
 pub trait SolidityTypeName: 'static {
 	fn solidity_name(writer: &mut impl fmt::Write, tc: &TypeCollector) -> fmt::Result;
+	/// "simple" types are stored inline, no `memory` modifier should be used in solidity
 	fn is_simple() -> bool;
 	fn solidity_default(writer: &mut impl fmt::Write, tc: &TypeCollector) -> fmt::Result;
+	/// Specialization
 	fn is_void() -> bool {
 		false
 	}
@@ -133,6 +135,10 @@
 }
 
 mod sealed {
+	/// Not every type should be directly placed in vec.
+	/// Vec encoding is not memory efficient, as every item will be padded
+	/// to 32 bytes.
+	/// Instead you should use specialized types (`bytes` in case of `Vec<u8>`)
 	pub trait CanBePlacedInVec {}
 }
 
@@ -427,7 +433,11 @@
 		for doc in self.docs {
 			writeln!(writer, "\t///{}", doc)?;
 		}
-		writeln!(writer, "\t/// @dev EVM selector for this function is: 0x{:0>8x},", self.selector)?;
+		writeln!(
+			writer,
+			"\t/// @dev EVM selector for this function is: 0x{:0>8x},",
+			self.selector
+		)?;
 		writeln!(writer, "\t///  or in textual repr: {}", self.selector_str)?;
 		write!(writer, "\tfunction {}(", self.name)?;
 		self.args.solidity_name(writer, tc)?;