difftreelog
feat generate solidity documentation
in: master
9 files changed
crates/evm-coder-macros/src/solidity_interface.rsdiffbeforeafterboth--- a/crates/evm-coder-macros/src/solidity_interface.rs
+++ b/crates/evm-coder-macros/src/solidity_interface.rs
@@ -6,7 +6,7 @@
use std::fmt::Write;
use syn::{
Expr, FnArg, GenericArgument, Generics, Ident, ImplItem, ImplItemMethod, ItemImpl, Lit, Meta,
- NestedMeta, PatType, Path, PathArguments, ReturnType, Type, spanned::Spanned,
+ MetaNameValue, NestedMeta, PatType, Path, PathArguments, ReturnType, Type, spanned::Spanned,
};
use crate::{
@@ -362,19 +362,28 @@
has_normal_args: bool,
mutability: Mutability,
result: Type,
+ docs: Vec<String>,
}
impl Method {
fn try_from(value: &ImplItemMethod) -> syn::Result<Self> {
let mut info = MethodInfo {
rename_selector: None,
};
+ let mut docs = Vec::new();
for attr in &value.attrs {
let ident = parse_ident_from_path(&attr.path, false)?;
if ident == "solidity" {
let args = attr.parse_meta().unwrap();
info = MethodInfo::from_meta(&args).unwrap();
} else if ident == "doc" {
- // TODO: Add docs to evm interfaces
+ let args = attr.parse_meta().unwrap();
+ let value = match args {
+ Meta::NameValue(MetaNameValue {
+ lit: Lit::Str(str), ..
+ }) => str.value(),
+ _ => unreachable!(),
+ };
+ docs.push(value);
}
}
let ident = &value.sig.ident;
@@ -457,6 +466,7 @@
has_normal_args,
mutability,
result: result.clone(),
+ docs,
})
}
fn expand_call_def(&self) -> proc_macro2::TokenStream {
@@ -570,10 +580,12 @@
.iter()
.filter(|a| !a.is_special())
.map(MethodArg::expand_solidity_argument);
+ let docs = self.docs.iter();
let selector = format!("{} {:0>8x}", self.selector_str, self.selector);
quote! {
SolidityFunction {
+ docs: &[#(#docs),*],
selector: #selector,
name: #camel_name,
mutability: #mutability,
@@ -704,6 +716,7 @@
use core::fmt::Write;
let interface = SolidityInterface {
name: #solidity_name,
+ selector: Self::interface_id(),
is: &["Dummy", "ERC165", #(
#solidity_is,
)* #(
crates/evm-coder-macros/src/to_log.rsdiffbeforeafterboth1use inflector::cases;2use syn::{Data, DeriveInput, Field, Fields, Ident, Variant, spanned::Spanned};3use std::fmt::Write;4use quote::quote;56use crate::{parse_ident_from_path, parse_ident_from_type, snake_ident_to_screaming};78struct EventField {9 name: Ident,10 camel_name: String,11 ty: Ident,12 indexed: bool,13}1415impl EventField {16 fn try_from(field: &Field) -> syn::Result<Self> {17 let name = field.ident.as_ref().unwrap();18 let ty = parse_ident_from_type(&field.ty, false)?;19 let mut indexed = false;20 for attr in &field.attrs {21 if let Ok(ident) = parse_ident_from_path(&attr.path, false) {22 if ident == "indexed" {23 indexed = true;24 }25 }26 }27 Ok(Self {28 name: name.to_owned(),29 camel_name: cases::camelcase::to_camel_case(&name.to_string()),30 ty: ty.to_owned(),31 indexed,32 })33 }34 fn expand_solidity_argument(&self) -> proc_macro2::TokenStream {35 let camel_name = &self.camel_name;36 let ty = &self.ty;37 let indexed = self.indexed;38 quote! {39 <SolidityEventArgument<#ty>>::new(#indexed, #camel_name)40 }41 }42}4344struct Event {45 name: Ident,46 name_screaming: Ident,47 fields: Vec<EventField>,48 selector: [u8; 32],49 selector_str: String,50}5152impl Event {53 fn try_from(variant: &Variant) -> syn::Result<Self> {54 let name = &variant.ident;55 let name_screaming = snake_ident_to_screaming(name);5657 let named = match &variant.fields {58 Fields::Named(named) => named,59 _ => {60 return Err(syn::Error::new(61 variant.fields.span(),62 "expected named fields",63 ))64 }65 };66 let mut fields = Vec::new();67 for field in &named.named {68 fields.push(EventField::try_from(field)?);69 }70 if fields.iter().filter(|f| f.indexed).count() > 3 {71 return Err(syn::Error::new(72 variant.fields.span(),73 "events can have at most 4 indexed fields (1 indexed field is reserved for event signature)"74 ));75 }76 let mut selector_str = format!("{}(", name);77 for (i, arg) in fields.iter().enumerate() {78 if i != 0 {79 write!(selector_str, ",").unwrap();80 }81 write!(selector_str, "{}", arg.ty).unwrap();82 }83 selector_str.push(')');84 let selector = crate::event_selector_str(&selector_str);8586 Ok(Self {87 name: name.to_owned(),88 name_screaming,89 fields,90 selector,91 selector_str,92 })93 }9495 fn expand_serializers(&self) -> proc_macro2::TokenStream {96 let name = &self.name;97 let name_screaming = &self.name_screaming;98 let fields = self.fields.iter().map(|f| &f.name);99100 let indexed = self.fields.iter().filter(|f| f.indexed).map(|f| &f.name);101 let plain = self.fields.iter().filter(|f| !f.indexed).map(|f| &f.name);102103 quote! {104 Self::#name {#(105 #fields,106 )*} => {107 topics.push(topic::from(Self::#name_screaming));108 #(109 topics.push(#indexed.to_topic());110 )*111 #(112 #plain.abi_write(&mut writer);113 )*114 }115 }116 }117118 fn expand_consts(&self) -> proc_macro2::TokenStream {119 let name_screaming = &self.name_screaming;120 let selector_str = &self.selector_str;121 let selector = &self.selector;122123 quote! {124 #[doc = #selector_str]125 const #name_screaming: [u8; 32] = [#(126 #selector,127 )*];128 }129 }130131 fn expand_solidity_function(&self) -> proc_macro2::TokenStream {132 let name = self.name.to_string();133 let args = self.fields.iter().map(EventField::expand_solidity_argument);134 quote! {135 SolidityEvent {136 name: #name,137 args: (138 #(139 #args,140 )*141 ),142 }143 }144 }145}146147pub struct Events {148 name: Ident,149 events: Vec<Event>,150}151152impl Events {153 pub fn try_from(data: &DeriveInput) -> syn::Result<Self> {154 let name = &data.ident;155 let en = match &data.data {156 Data::Enum(en) => en,157 _ => return Err(syn::Error::new(data.span(), "expected enum")),158 };159 let mut events = Vec::new();160 for variant in &en.variants {161 events.push(Event::try_from(variant)?);162 }163 Ok(Self {164 name: name.to_owned(),165 events,166 })167 }168 pub fn expand(&self) -> proc_macro2::TokenStream {169 let name = &self.name;170171 let consts = self.events.iter().map(Event::expand_consts);172 let serializers = self.events.iter().map(Event::expand_serializers);173 let solidity_name = self.name.to_string();174 let solidity_functions = self.events.iter().map(Event::expand_solidity_function);175176 quote! {177 impl #name {178 #(179 #consts180 )*181182 pub fn generate_solidity_interface(tc: &evm_coder::solidity::TypeCollector, is_impl: bool) {183 use evm_coder::solidity::*;184 use core::fmt::Write;185 let interface = SolidityInterface {186 name: #solidity_name,187 is: &[],188 functions: (#(189 #solidity_functions,190 )*),191 };192 let mut out = string::new();193 out.push_str("// Inline\n");194 let _ = interface.format(is_impl, &mut out, tc);195 tc.collect(out);196 }197 }198199 #[automatically_derived]200 impl ::evm_coder::events::ToLog for #name {201 fn to_log(&self, contract: address) -> ::ethereum::Log {202 use ::evm_coder::events::ToTopic;203 use ::evm_coder::abi::AbiWrite;204 let mut writer = ::evm_coder::abi::AbiWriter::new();205 let mut topics = Vec::new();206 match self {207 #(208 #serializers,209 )*210 }211 ::ethereum::Log {212 address: contract,213 topics,214 data: writer.finish(),215 }216 }217 }218 }219 }220}crates/evm-coder/src/solidity.rsdiffbeforeafterboth--- a/crates/evm-coder/src/solidity.rs
+++ b/crates/evm-coder/src/solidity.rs
@@ -84,6 +84,7 @@
solidity_type_name! {
uint8 => "uint8" true = "0",
uint32 => "uint32" true = "0",
+ uint64 => "uint64" true = "0",
uint128 => "uint128" true = "0",
uint256 => "uint256" true = "0",
address => "address" true = "0x0000000000000000000000000000000000000000",
@@ -376,6 +377,7 @@
Mutable,
}
pub struct SolidityFunction<A, R> {
+ pub docs: &'static [&'static str],
pub selector: &'static str,
pub name: &'static str,
pub args: A,
@@ -389,6 +391,12 @@
writer: &mut impl fmt::Write,
tc: &TypeCollector,
) -> fmt::Result {
+ for doc in self.docs {
+ writeln!(writer, "\t//{}", doc)?;
+ }
+ if !self.docs.is_empty() {
+ writeln!(writer, "\t//")?;
+ }
writeln!(writer, "\t// Selector: {}", self.selector)?;
write!(writer, "\tfunction {}(", self.name)?;
self.args.solidity_name(writer, tc)?;
@@ -449,6 +457,7 @@
}
pub struct SolidityInterface<F: SolidityFunctions> {
+ pub selector: u32,
pub name: &'static str,
pub is: &'static [&'static str],
pub functions: F,
@@ -461,6 +470,9 @@
out: &mut impl fmt::Write,
tc: &TypeCollector,
) -> fmt::Result {
+ if self.selector != 0 {
+ writeln!(out, "// Selector: {:0>8x}", self.selector)?;
+ }
if is_impl {
write!(out, "contract ")?;
} else {
pallets/fungible/src/stubs/UniqueFungible.soldiffbeforeafterboth--- a/pallets/fungible/src/stubs/UniqueFungible.sol
+++ b/pallets/fungible/src/stubs/UniqueFungible.sol
@@ -31,6 +31,7 @@
);
}
+// Selector: 942e8b22
contract ERC20 is Dummy, ERC165, ERC20Events {
// Selector: name() 06fdde03
function name() public view returns (string memory) {
pallets/nonfungible/src/erc.rsdiffbeforeafterboth--- a/pallets/nonfungible/src/erc.rs
+++ b/pallets/nonfungible/src/erc.rs
@@ -61,6 +61,7 @@
Ok(string::from_utf8_lossy(&self.token_prefix).into())
}
+ /// Returns token's const_metadata
#[solidity(rename_selector = "tokenURI")]
fn token_uri(&self, token_id: uint256) -> Result<string> {
let token_id: u32 = token_id.try_into().map_err(|_| "token id overflow")?;
@@ -79,6 +80,7 @@
Ok(index)
}
+ /// Not implemented
fn token_of_owner_by_index(&self, _owner: address, _index: uint256) -> Result<uint256> {
// TODO: Not implemetable
Err("not implemented".into())
@@ -103,6 +105,7 @@
.owner
.as_eth())
}
+ /// Not implemented
fn safe_transfer_from_with_data(
&mut self,
_from: address,
@@ -114,6 +117,7 @@
// TODO: Not implemetable
Err("not implemented".into())
}
+ /// Not implemented
fn safe_transfer_from(
&mut self,
_from: address,
@@ -159,6 +163,7 @@
Ok(())
}
+ /// Not implemented
fn set_approval_for_all(
&mut self,
_caller: caller,
@@ -169,11 +174,13 @@
Err("not implemented".into())
}
+ /// Not implemented
fn get_approved(&self, _token_id: uint256) -> Result<address> {
// TODO: Not implemetable
Err("not implemented".into())
}
+ /// Not implemented
fn is_approved_for_all(&self, _owner: address, _operator: address) -> Result<address> {
// TODO: Not implemetable
Err("not implemented".into())
@@ -197,6 +204,8 @@
Ok(false)
}
+ /// `token_id` should be obtained with `next_token_id` method,
+ /// unlike standard, you can't specify it manually
fn mint(&mut self, caller: caller, to: address, token_id: uint256) -> Result<bool> {
let caller = T::CrossAccountId::from_eth(caller);
let to = T::CrossAccountId::from_eth(to);
@@ -223,6 +232,8 @@
Ok(true)
}
+ /// `token_id` should be obtained with `next_token_id` method,
+ /// unlike standard, you can't specify it manually
#[solidity(rename_selector = "mintWithTokenURI")]
fn mint_with_token_uri(
&mut self,
@@ -257,6 +268,7 @@
Ok(true)
}
+ /// Not implemented
fn finish_minting(&mut self, _caller: caller) -> Result<bool> {
Err("not implementable".into())
}
pallets/nonfungible/src/stubs/UniqueNFT.soldiffbeforeafterboth--- a/pallets/nonfungible/src/stubs/UniqueNFT.sol
+++ b/pallets/nonfungible/src/stubs/UniqueNFT.sol
@@ -51,6 +51,17 @@
event MintingFinished();
}
+// Selector: 42966c68
+contract ERC721Burnable is Dummy, ERC165 {
+ // Selector: burn(uint256) 42966c68
+ function burn(uint256 tokenId) public {
+ require(false, stub_error);
+ tokenId;
+ dummy = 0;
+ }
+}
+
+// Selector: 58800161
contract ERC721 is Dummy, ERC165, ERC721Events {
// Selector: balanceOf(address) 70a08231
function balanceOf(address owner) public view returns (uint256) {
@@ -68,6 +79,8 @@
return 0x0000000000000000000000000000000000000000;
}
+ // Not implemented
+ //
// Selector: safeTransferFromWithData(address,address,uint256,bytes) 60a11672
function safeTransferFromWithData(
address from,
@@ -83,6 +96,8 @@
dummy = 0;
}
+ // Not implemented
+ //
// Selector: safeTransferFrom(address,address,uint256) 42842e0e
function safeTransferFrom(
address from,
@@ -117,6 +132,8 @@
dummy = 0;
}
+ // Not implemented
+ //
// Selector: setApprovalForAll(address,bool) a22cb465
function setApprovalForAll(address operator, bool approved) public {
require(false, stub_error);
@@ -125,6 +142,8 @@
dummy = 0;
}
+ // Not implemented
+ //
// Selector: getApproved(uint256) 081812fc
function getApproved(uint256 tokenId) public view returns (address) {
require(false, stub_error);
@@ -133,6 +152,8 @@
return 0x0000000000000000000000000000000000000000;
}
+ // Not implemented
+ //
// Selector: isApprovedForAll(address,address) e985e9c5
function isApprovedForAll(address owner, address operator)
public
@@ -147,45 +168,7 @@
}
}
-contract ERC721Burnable is Dummy, ERC165 {
- // Selector: burn(uint256) 42966c68
- function burn(uint256 tokenId) public {
- require(false, stub_error);
- tokenId;
- dummy = 0;
- }
-}
-
-contract ERC721Enumerable is Dummy, ERC165 {
- // Selector: tokenByIndex(uint256) 4f6ccce7
- function tokenByIndex(uint256 index) public view returns (uint256) {
- require(false, stub_error);
- index;
- dummy;
- return 0;
- }
-
- // Selector: tokenOfOwnerByIndex(address,uint256) 2f745c59
- function tokenOfOwnerByIndex(address owner, uint256 index)
- public
- view
- returns (uint256)
- {
- require(false, stub_error);
- owner;
- index;
- dummy;
- return 0;
- }
-
- // Selector: totalSupply() 18160ddd
- function totalSupply() public view returns (uint256) {
- require(false, stub_error);
- dummy;
- return 0;
- }
-}
-
+// Selector: 5b5e139f
contract ERC721Metadata is Dummy, ERC165 {
// Selector: name() 06fdde03
function name() public view returns (string memory) {
@@ -201,6 +184,8 @@
return "";
}
+ // Returns token's const_metadata
+ //
// Selector: tokenURI(uint256) c87b56dd
function tokenURI(uint256 tokenId) public view returns (string memory) {
require(false, stub_error);
@@ -210,6 +195,7 @@
}
}
+// Selector: 68ccfe89
contract ERC721Mintable is Dummy, ERC165, ERC721MintableEvents {
// Selector: mintingFinished() 05d2035b
function mintingFinished() public view returns (bool) {
@@ -218,6 +204,9 @@
return false;
}
+ // `token_id` should be obtained with `next_token_id` method,
+ // unlike standard, you can't specify it manually
+ //
// Selector: mint(address,uint256) 40c10f19
function mint(address to, uint256 tokenId) public returns (bool) {
require(false, stub_error);
@@ -227,6 +216,9 @@
return false;
}
+ // `token_id` should be obtained with `next_token_id` method,
+ // unlike standard, you can't specify it manually
+ //
// Selector: mintWithTokenURI(address,uint256,string) 50bb4e7f
function mintWithTokenURI(
address to,
@@ -241,6 +233,8 @@
return false;
}
+ // Not implemented
+ //
// Selector: finishMinting() 7d64bcb4
function finishMinting() public returns (bool) {
require(false, stub_error);
@@ -249,6 +243,40 @@
}
}
+// Selector: 780e9d63
+contract ERC721Enumerable is Dummy, ERC165 {
+ // Selector: tokenByIndex(uint256) 4f6ccce7
+ function tokenByIndex(uint256 index) public view returns (uint256) {
+ require(false, stub_error);
+ index;
+ dummy;
+ return 0;
+ }
+
+ // Not implemented
+ //
+ // Selector: tokenOfOwnerByIndex(address,uint256) 2f745c59
+ function tokenOfOwnerByIndex(address owner, uint256 index)
+ public
+ view
+ returns (uint256)
+ {
+ require(false, stub_error);
+ owner;
+ index;
+ dummy;
+ return 0;
+ }
+
+ // Selector: totalSupply() 18160ddd
+ function totalSupply() public view returns (uint256) {
+ require(false, stub_error);
+ dummy;
+ return 0;
+ }
+}
+
+// Selector: e562194d
contract ERC721UniqueExtensions is Dummy, ERC165 {
// Selector: transfer(address,uint256) a9059cbb
function transfer(address to, uint256 tokenId) public {
tests/src/eth/api/ContractHelpers.soldiffbeforeafterboth--- a/tests/src/eth/api/ContractHelpers.sol
+++ b/tests/src/eth/api/ContractHelpers.sol
@@ -12,6 +12,7 @@
function supportsInterface(bytes4 interfaceID) external view returns (bool);
}
+// Selector: 31acb1fe
interface ContractHelpers is Dummy, ERC165 {
// Selector: contractOwner(address) 5152b14c
function contractOwner(address contractAddress)
tests/src/eth/api/UniqueFungible.soldiffbeforeafterboth--- a/tests/src/eth/api/UniqueFungible.sol
+++ b/tests/src/eth/api/UniqueFungible.sol
@@ -22,6 +22,7 @@
);
}
+// Selector: 942e8b22
interface ERC20 is Dummy, ERC165, ERC20Events {
// Selector: name() 06fdde03
function name() external view returns (string memory);
tests/src/eth/api/UniqueNFT.soldiffbeforeafterboth--- a/tests/src/eth/api/UniqueNFT.sol
+++ b/tests/src/eth/api/UniqueNFT.sol
@@ -42,6 +42,13 @@
event MintingFinished();
}
+// Selector: 42966c68
+interface ERC721Burnable is Dummy, ERC165 {
+ // Selector: burn(uint256) 42966c68
+ function burn(uint256 tokenId) external;
+}
+
+// Selector: 58800161
interface ERC721 is Dummy, ERC165, ERC721Events {
// Selector: balanceOf(address) 70a08231
function balanceOf(address owner) external view returns (uint256);
@@ -49,6 +56,8 @@
// Selector: ownerOf(uint256) 6352211e
function ownerOf(uint256 tokenId) external view returns (address);
+ // Not implemented
+ //
// Selector: safeTransferFromWithData(address,address,uint256,bytes) 60a11672
function safeTransferFromWithData(
address from,
@@ -57,6 +66,8 @@
bytes memory data
) external;
+ // Not implemented
+ //
// Selector: safeTransferFrom(address,address,uint256) 42842e0e
function safeTransferFrom(
address from,
@@ -74,12 +85,18 @@
// Selector: approve(address,uint256) 095ea7b3
function approve(address approved, uint256 tokenId) external;
+ // Not implemented
+ //
// Selector: setApprovalForAll(address,bool) a22cb465
function setApprovalForAll(address operator, bool approved) external;
+ // Not implemented
+ //
// Selector: getApproved(uint256) 081812fc
function getApproved(uint256 tokenId) external view returns (address);
+ // Not implemented
+ //
// Selector: isApprovedForAll(address,address) e985e9c5
function isApprovedForAll(address owner, address operator)
external
@@ -87,25 +104,7 @@
returns (address);
}
-interface ERC721Burnable is Dummy, ERC165 {
- // Selector: burn(uint256) 42966c68
- function burn(uint256 tokenId) external;
-}
-
-interface ERC721Enumerable is Dummy, ERC165 {
- // Selector: tokenByIndex(uint256) 4f6ccce7
- function tokenByIndex(uint256 index) external view returns (uint256);
-
- // Selector: tokenOfOwnerByIndex(address,uint256) 2f745c59
- function tokenOfOwnerByIndex(address owner, uint256 index)
- external
- view
- returns (uint256);
-
- // Selector: totalSupply() 18160ddd
- function totalSupply() external view returns (uint256);
-}
-
+// Selector: 5b5e139f
interface ERC721Metadata is Dummy, ERC165 {
// Selector: name() 06fdde03
function name() external view returns (string memory);
@@ -113,17 +112,26 @@
// Selector: symbol() 95d89b41
function symbol() external view returns (string memory);
+ // Returns token's const_metadata
+ //
// Selector: tokenURI(uint256) c87b56dd
function tokenURI(uint256 tokenId) external view returns (string memory);
}
+// Selector: 68ccfe89
interface ERC721Mintable is Dummy, ERC165, ERC721MintableEvents {
// Selector: mintingFinished() 05d2035b
function mintingFinished() external view returns (bool);
+ // `token_id` should be obtained with `next_token_id` method,
+ // unlike standard, you can't specify it manually
+ //
// Selector: mint(address,uint256) 40c10f19
function mint(address to, uint256 tokenId) external returns (bool);
+ // `token_id` should be obtained with `next_token_id` method,
+ // unlike standard, you can't specify it manually
+ //
// Selector: mintWithTokenURI(address,uint256,string) 50bb4e7f
function mintWithTokenURI(
address to,
@@ -131,10 +139,30 @@
string memory tokenUri
) external returns (bool);
+ // Not implemented
+ //
// Selector: finishMinting() 7d64bcb4
function finishMinting() external returns (bool);
}
+// Selector: 780e9d63
+interface ERC721Enumerable is Dummy, ERC165 {
+ // Selector: tokenByIndex(uint256) 4f6ccce7
+ function tokenByIndex(uint256 index) external view returns (uint256);
+
+ // Not implemented
+ //
+ // Selector: tokenOfOwnerByIndex(address,uint256) 2f745c59
+ function tokenOfOwnerByIndex(address owner, uint256 index)
+ external
+ view
+ returns (uint256);
+
+ // Selector: totalSupply() 18160ddd
+ function totalSupply() external view returns (uint256);
+}
+
+// Selector: e562194d
interface ERC721UniqueExtensions is Dummy, ERC165 {
// Selector: transfer(address,uint256) a9059cbb
function transfer(address to, uint256 tokenId) external;