Ethereum EIPs

404

Page not found :(

The requested page could not be found.

All

Living

Number	Title	Author
1	EIP Purpose and Guidelines	Martin Becze <mb@ethereum.org>, Hudson Jameson <hudson@ethereum.org>, et al.

Final

Number	Title	Author
20	Token Standard	Fabian Vogelsteller <fabian@ethereum.org>, Vitalik Buterin <vitalik.buterin@ethereum.org>
55	Mixed-case checksum address encoding	Vitalik Buterin <vitalik.buterin@ethereum.org>, Alex Van de Sande <avsa@ethereum.org>
137	Ethereum Domain Name Service - Specification	Nick Johnson <arachnid@notdot.net>
162	Initial ENS Hash Registrar	Maurelian, Nick Johnson <nick@ethereum.org>, Alex Van de Sande <avsa@ethereum.org>
165	Standard Interface Detection	Christian Reitwießner <chris@ethereum.org>, Nick Johnson <nick@ethereum.org>, Fabian Vogelsteller <fabian@lukso.network>, Jordi Baylina <jordi@baylina.cat>, Konrad Feldmeier <konrad.feldmeier@brainbot.com>, William Entriken <github.com@phor.net>
173	Contract Ownership Standard	Nick Mudge (@mudgen), Dan Finlay <dan@danfinlay.com>
181	ENS support for reverse resolution of Ethereum addresses	Nick Johnson <arachnid@notdot.net>
190	Ethereum Smart Contract Packaging Standard	Piper Merriam (@pipermerriam), Tim Coulter (@tcoulter), Denis Erfurt (@mhhf), RJ Catalano (@VoR0220), Iuri Matias (@iurimatias)
191	Signed Data Standard	Martin Holst Swende (@holiman), Nick Johnson <arachnid@notdot.net>
223	Token with transaction handling model	Dexaran (@Dexaran) <dexaran@ethereumclassic.org>
600	Ethereum purpose allocation for Deterministic Wallets	Nick Johnson (@arachnid), Micah Zoltu (@micahzoltu)
601	Ethereum hierarchy for deterministic wallets	Nick Johnson (@arachnid), Micah Zoltu (@micahzoltu)
681	URL Format for Transaction Requests	Daniel A. Nagy (@nagydani)
721	Non-Fungible Token Standard	William Entriken (@fulldecent), Dieter Shirley <dete@axiomzen.co>, Jacob Evans <jacob@dekz.net>, Nastassia Sachs <nastassia.sachs@protonmail.com>
777	Token Standard	Jacques Dafflon <mail@0xjac.com>, Jordi Baylina <jordi@baylina.cat>, Thomas Shababi <tom@truelevel.io>
820	Pseudo-introspection Registry Contract	Jordi Baylina <jordi@baylina.cat>, Jacques Dafflon <jacques@dafflon.tech>
1046	tokenURI Interoperability	Tommy Nicholas (@tomasienrbc), Matt Russo (@mateosu), John Zettler (@JohnZettler), Matt Condon (@shrugs), Gavin John (@Pandapip1)
1155	Multi Token Standard	Witek Radomski <witek@enjin.io>, Andrew Cooke <ac0dem0nk3y@gmail.com>, Philippe Castonguay (@phabc) <pc@horizongames.net>, James Therien <james@turing-complete.com>, Eric Binet <eric@enjin.io>, Ronan Sandford (@wighawag) <wighawag@gmail.com>
1167	Minimal Proxy Contract	Peter Murray (@yarrumretep), Nate Welch (@flygoing), Joe Messerman (@JAMesserman)
1271	Standard Signature Validation Method for Contracts	Francisco Giordano (@frangio), Matt Condon (@shrugs), Philippe Castonguay (@PhABC), Amir Bandeali (@abandeali1), Jorge Izquierdo (@izqui), Bertrand Masius (@catageek)
1328	WalletConnect URI Format	ligi (@ligi), Pedro Gomes (@pedrouid)
1363	Payable Token	Vittorio Minacori (@vittominacori)
1820	Pseudo-introspection Registry Contract	Jordi Baylina <jordi@baylina.cat>, Jacques Dafflon <mail@0xjac.com>
1967	Proxy Storage Slots	Santiago Palladino (@spalladino), Francisco Giordano (@frangio), Hadrien Croubois (@Amxx)
2098	Compact Signature Representation	Richard Moore (@ricmoo), Nick Johnson <nick@ethereum.org>
2135	Consumable Interface (Tickets, etc)	Zainan Victor Zhou (@xinbenlv)
2309	ERC-721 Consecutive Transfer Extension	Sean Papanikolas (@pizzarob)
2535	Diamonds, Multi-Facet Proxy	Nick Mudge (@mudgen)
2612	Permit Extension for EIP-20 Signed Approvals	Martin Lundfall (@Mrchico)
2678	Revised Ethereum Smart Contract Packaging Standard (EthPM v3)	g. nicholas d’andrea (@gnidan), Piper Merriam (@pipermerriam), Nick Gheorghita (@njgheorghita), Christian Reitwiessner (@chriseth), Ben Hauser (@iamdefinitelyahuman), Bryant Eisenbach (@fubuloubu)
2771	Secure Protocol for Native Meta Transactions	Ronan Sandford (@wighawag), Liraz Siri (@lirazsiri), Dror Tirosh (@drortirosh), Yoav Weiss (@yoavw), Alex Forshtat (@forshtat), Hadrien Croubois (@Amxx), Sachin Tomar (@tomarsachin2271), Patrick McCorry (@stonecoldpat), Nicolas Venturo (@nventuro), Fabian Vogelsteller (@frozeman), Gavin John (@Pandapip1)
2981	NFT Royalty Standard	Zach Burks (@vexycats), James Morgan (@jamesmorgan), Blaine Malone (@blmalone), James Seibel (@seibelj)
3156	Flash Loans	Alberto Cuesta Cañada (@alcueca), Fiona Kobayashi (@fifikobayashi), fubuloubu (@fubuloubu), Austin Williams (@onewayfunction)
3448	MetaProxy Standard	pinkiebell (@pinkiebell)
3475	Abstract Storage Bonds	Yu Liu (@yuliu-debond), Varun Deshpande (@dr-chain), Cedric Ngakam (@drikssy), Dhruv Malik (@dhruvmalik007), Samuel Gwlanold Edoumou (@Edoumou), Toufic Batrice (@toufic0710)
3525	Semi-Fungible Token	Will Wang (@will42w), Mike Meng <myan@solv.finance>, Yi Cai (@YeeTsai) <yee.tsai@gmail.com>, Ryan Chow <ryanchow@solv.finance>, Zhongxin Wu (@Nerverwind), AlvisDu (@AlvisDu)
3643	T-REX - Token for Regulated EXchanges	Joachim Lebrun (@Joachim-Lebrun), Tony Malghem (@TonyMalghem), Kevin Thizy (@Nakasar), Luc Falempin (@lfalempin), Adam Boudjemaa (@Aboudjem)
3668	CCIP Read—Secure offchain data retrieval	Nick Johnson (@arachnid)
4361	Sign-In with Ethereum	Wayne Chang (@wyc), Gregory Rocco (@obstropolos), Brantly Millegan (@brantlymillegan), Nick Johnson (@Arachnid), Oliver Terbu (@awoie)
4400	EIP-721 Consumable Extension	Daniel Ivanov (@Daniel-K-Ivanov), George Spasov (@Perseverance)
4519	Non-Fungible Tokens Tied to Physical Assets	Javier Arcenegui (@Hardblock-IMSE-CNM), Rosario Arjona (@RosarioArjona), Roberto Román <roman@imse-cnm.csic.es>, Iluminada Baturone (@lumi2018)
4626	Tokenized Vaults	Joey Santoro (@joeysantoro), t11s (@transmissions11), Jet Jadeja (@JetJadeja), Alberto Cuesta Cañada (@alcueca), Señor Doggo (@fubuloubu)
4804	Web3 URL to EVM Call Message Translation	Qi Zhou (@qizhou), Chao Pi (@pichaoqkc), Sam Wilson (@SamWilsn)
4834	Hierarchical Domains	Gavin John (@Pandapip1)
4906	EIP-721 Metadata Update Extension	Anders (@0xanders), Lance (@LanceSnow), Shrug <shrug@emojidao.org>, Nathan <nathan.gang@gemini.com>
4907	Rental NFT, an Extension of EIP-721	Anders (@0xanders), Lance (@LanceSnow), Shrug <shrug@emojidao.org>
4910	Royalty Bearing NFTs	Andreas Freund (@Therecanbeonlyone1969)
4955	Vendor Metadata Extension for NFTs	Ignacio Mazzara (@nachomazzara)
5006	Rental NFT, NFT User Extension	Lance (@LanceSnow), Anders (@0xanders), Shrug <shrug@emojidao.org>
5007	Time NFT, ERC-721 Time Extension	Anders (@0xanders), Lance (@LanceSnow), Shrug <shrug@emojidao.org>
5023	Shareable Non-Fungible Token	Jarno Marttila (@yaruno), Martin Moravek (@mmartinmo)
5169	Client Script URI for Token Contracts	James (@JamesSmartCell), Weiwu (@weiwu-zhang)
5192	Minimal Soulbound NFTs	Tim Daubenschütz (@TimDaub), Anders (@0xanders)
5202	Blueprint contract format	Charles Cooper (@charles-cooper), Edward Amor (@skellet0r)
5219	Contract Resource Requests	Gavin John (@Pandapip1)
5267	Retrieval of EIP-712 domain	Francisco Giordano (@frangio)
5313	Light Contract Ownership	William Entriken (@fulldecent)
5375	NFT Author Information and Consent	Samuele Marro (@samuelemarro), Luca Donno (@lucadonnoh)
5380	ERC-721 Entitlement Extension	Gavin John (@Pandapip1), Tim Daubenschütz (@TimDaub)
5484	Consensual Soulbound Tokens	Buzz Cai (@buzzcai)
5489	NFT Hyperlink Extension	IronMan_CH (@coderfengyun)
5507	Refundable Tokens	elie222 (@elie222), Gavin John (@Pandapip1)
5521	Referable NFT	Saber Yu (@OniReimu), Qin Wang <qin.wang@data61.csiro.au>, Shange Fu <shange.fu@monash.edu>, Yilin Sai <yilin.sai@data61.csiro.au>, Shiping Chen <shiping.chen@data61.csiro.au>, Sherry Xu <xiwei.xu@data61.csiro.au>, Jiangshan Yu <jiangshan.yu@monash.edu>
5528	Refundable Fungible Token	StartfundInc (@StartfundInc)
5564	Stealth Addresses	Toni Wahrstätter (@nerolation), Matt Solomon (@mds1), Ben DiFrancesco (@apbendi), Vitalik Buterin (@vbuterin)
5570	Digital Receipt Non-Fungible Tokens	Sean Darcy (@darcys22)
5585	ERC-721 NFT Authorization	Veega Labs (@VeegaLabsOfficial), Sean NG (@ngveega), Tiger (@tiger0x), Fred (@apan826), Fov Cao (@fovcao)
5606	Multiverse NFTs	Gaurang Torvekar (@gaurangtorvekar), Khemraj Adhawade (@akhemraj), Nikhil Asrani (@nikhilasrani)
5615	ERC-1155 Supply Extension	Gavin John (@Pandapip1)
5625	NFT Metadata JSON Schema dStorage Extension	Gavin Fu (@gavfu), Leo Wang (@wanglie1986), Bova Chen (@appoipp), Guang Han (@pangwa), Brian Wu (@wuhaixian1984)
5646	Token State Fingerprint	Naim Ashhab (@ashhanai)
5679	Token Minting and Burning	Zainan Victor Zhou (@xinbenlv)
5725	Transferable Vesting NFT	Apeguru (@Apegurus), Marco De Vries <marco@paladinsec.co>, Mario <mario@paladinsec.co>, DeFiFoFum (@DeFiFoFum), Elliott Green (@elliott-green)
5732	Commit Interface	Zainan Victor Zhou (@xinbenlv), Matt Stam (@mattstam)
5750	General Extensibility for Method Behaviors	Zainan Victor Zhou (@xinbenlv)
5773	Context-Dependent Multi-Asset Tokens	Bruno Škvorc (@Swader), Cicada (@CicadaNCR), Steven Pineda (@steven2308), Stevan Bogosavljevic (@stevyhacker), Jan Turk (@ThunderDeliverer)
6059	Parent-Governed Nestable Non-Fungible Tokens	Bruno Škvorc (@Swader), Cicada (@CicadaNCR), Steven Pineda (@steven2308), Stevan Bogosavljevic (@stevyhacker), Jan Turk (@ThunderDeliverer)
6066	Signature Validation Method for NFTs	Jack Boyuan Xu (@boyuanx)
6093	Custom errors for commonly-used tokens	Ernesto García (@ernestognw), Francisco Giordano (@frangio), Hadrien Croubois (@Amxx)
6105	No Intermediary NFT Trading Protocol	5660-eth (@5660-eth), Silvere Heraudeau (@lambdalf-dev), Martin McConnell (@offgridgecko), Abu <team10kuni@gmail.com>, Wizard Wang
6147	Guard of NFT/SBT, an Extension of ERC-721	5660-eth (@5660-eth), Wizard Wang
6150	Hierarchical NFTs	Keegan Lee (@keeganlee), msfew <msfew@hyperoracle.io>, Kartin <kartin@hyperoracle.io>, qizhou (@qizhou)
6220	Composable NFTs utilizing Equippable Parts	Bruno Škvorc (@Swader), Cicada (@CicadaNCR), Steven Pineda (@steven2308), Stevan Bogosavljevic (@stevyhacker), Jan Turk (@ThunderDeliverer)
6239	Semantic Soulbound Tokens	Jessica Chang (@JessicaChg)
6381	Public Non-Fungible Token Emote Repository	Bruno Škvorc (@Swader), Steven Pineda (@steven2308), Stevan Bogosavljevic (@stevyhacker), Jan Turk (@ThunderDeliverer)
6454	Minimal Transferable NFT detection interface	Bruno Škvorc (@Swader), Francesco Sullo (@sullof), Steven Pineda (@steven2308), Stevan Bogosavljevic (@stevyhacker), Jan Turk (@ThunderDeliverer)
6492	Signature Validation for Predeploy Contracts	Ivo Georgiev (@Ivshti), Agustin Aguilar (@Agusx1211)
6538	Stealth Meta-Address Registry	Matt Solomon (@mds1), Toni Wahrstätter (@nerolation), Ben DiFrancesco (@apbendi), Vitalik Buterin (@vbuterin), Gary Ghayrat (@garyghayrat)
6672	Multi-redeemable NFTs	RE:DREAMER Lab <dev@redreamer.io>, Archie Chang (@ArchieR7) <archie@redreamer.io>, Kai Yu (@chihkaiyu) <kai@redreamer.io>, Yonathan Randyanto (@Randyanto) <randy@redreamer.io>, Boyu Chu (@chuboyu) <boyu@redreamer.io>, Boxi Li (@boxi79) <boxi@redreamer.io>, Jason Cheng (@JasonCheng0729) <jason@redreamer.io>
6808	Fungible Key Bound Token	Mihai Onila (@MihaiORO), Nick Zeman (@NickZCZ), Narcis Cotaie (@NarcisCRO)
6809	Non-Fungible Key Bound Token	Mihai Onila (@MihaiORO), Nick Zeman (@NickZCZ), Narcis Cotaie (@NarcisCRO)
6909	Minimal Multi-Token Interface	JT Riley (@jtriley2p), Dillon (@d1ll0n), Sara (@snreynolds), Vectorized (@Vectorized), Neodaoist (@neodaoist)
6982	Efficient Default Lockable Tokens	Francesco Sullo (@sullof), Alexe Spataru (@urataps)
7007	Verifiable AI-Generated Content Token	Cathie So (@socathie), Xiaohang Yu (@xhyumiracle), Conway (@0x1cc), Lee Ting Ting (@tina1998612), Kartin <kartin@hyperoracle.io>
7053	Interoperable Digital Media Indexing	Bofu Chen (@bafu), Tammy Yang (@tammyyang)
7066	Lockable Extension for ERC-721	Piyush Chittara (@piyush-chittara), StreamNFT (@streamnft-tech), Srinivas Joshi (@SrinivasJoshi)
7092	Financial Bonds	Samuel Gwlanold Edoumou (@Edoumou)
7160	ERC-721 Multi-Metadata Extension	0xG (@0xGh), Marco Peyfuss (@mpeyfuss)
7201	Namespaced Storage Layout	Francisco Giordano (@frangio), Hadrien Croubois (@Amxx), Ernesto García (@ernestognw), Eric Lau (@ericglau)
7208	On-Chain Data Containers	Rachid Ajaja (@abrajaja), Matthijs de Vries (@sudomati), Alexandros Athanasopulos (@Xaleee), Pavel Rubin (@pash7ka), Sebastian Galimberti Romano (@galimba), Daniel Berbesi (@berbex), Apostolos Mavropoulos (@ApostolosMavro), Barbara Marcano (@Barbara-Marcano), Daniel Ortega (@xdaniortega)
7231	Identity-aggregated NFT	Chloe Gu <chloe@carv.io>, Navid X. (@xuxinlai2002), Victor Yu <victor@carv.io>, Archer H.
7291	Purpose bound money	Orchid-Dev (@proj-orchid-straitsx), Victor Liew (@alcedo), Wong Tse Jian (@wongtsejian), Jacob Shan (@Jacobshan429), Chin Sin Ong (@chinsinong), Praveen Kumar (@veenkumarr)
7401	Parent-Governed Non-Fungible Tokens Nesting	Bruno Škvorc (@Swader), Cicada (@CicadaNCR), Steven Pineda (@steven2308), Stevan Bogosavljevic (@stevyhacker), Jan Turk (@ThunderDeliverer)
7409	Public Non-Fungible Tokens Emote Repository	Bruno Škvorc (@Swader), Steven Pineda (@steven2308), Stevan Bogosavljevic (@stevyhacker), Jan Turk (@ThunderDeliverer)
7432	Non-Fungible Token Roles	Ernani São Thiago (@ernanirst), Daniel Lima (@karacurt)
7439	Prevent ticket touting	LeadBest Consulting Group <service@getoken.io>, Sandy Sung (@sandy-sung-lb), Mars Peng <mars.peng@getoken.io>, Taien Wang <taien.wang@getoken.io>
7528	ETH (Native Asset) Address Convention	Joey Santoro (@joeysantoro)
7535	Native Asset ERC-4626 Tokenized Vault	Joey Santoro (@joeysantoro)
7540	Asynchronous ERC-4626 Tokenized Vaults	Jeroen Offerijns (@hieronx), Alina Sinelnikova (@ilinzweilin), Vikram Arun (@vikramarun), Joey Santoro (@joeysantoro), Farhaan Ali (@0xfarhaan), João Martins (@0xTimepunk)
7575	Multi-Asset ERC-4626 Vaults	Jeroen Offerijns (@hieronx), Alina Sinelnikova (@ilinzweilin), Vikram Arun (@vikramarun), Joey Santoro (@joeysantoro), Farhaan Ali (@0xfarhaan)
7578	Physical Asset Redemption	Lee Vidor (@V1d0r), David Tan <david@emergentx.org>, Lee Smith <lee@emergentx.org>, Gabriel Stoica (@gabrielstoica)
7588	Blob Transactions Metadata JSON Schema	Gavin Fu (@gavfu), Leo Wang (@wanglie1986), Bova Chen (@appoipp), Aiden X (@4ever9)
7627	Secure Messaging Protocol	Chen Liaoyuan (@chenly) <cly@kip.pro>
7631	Dual Nature Token Pair	vectorized (@vectorized), Thomas (@0xth0mas), Quit (@quitcrypto), Michael Amadi (@AmadiMichael), cygaar (@cygaar), Harrison (@pop-punk)
7634	Limited Transfer Count NFT	Qin Wang (@qinwang-git), Saber Yu (@OniReimu), Shiping Chen <shiping.chen@data61.csiro.au>
7656	Generalized Contract-Linked Services	Francesco Sullo (@sullof)
7734	Decentralized Identity Verification (DID)	Anushka Yadav (@64anushka) <64anushka@gmail.com>
7743	Multi-Owner Non-Fungible Tokens (MO-NFT)	Cheng Qian (@jamesavechives) <james.walstonn@gmail.com>
7751	Wrapping of bubbled up reverts	Daniel Gretzke (@gretzke), Sara Reynolds (@snreynolds), Alice Henshaw (@hensha256), Marko Veniger <marko.veniger@tenderly.co>, Hadrien Croubois (@Amxx)
7786	Cross-Chain Messaging Gateway	Francisco Giordano (@frangio), Hadrien Croubois (@Amxx), Ernesto García (@ernestognw), CJ Cobb (@cjcobb23), Sergey Gorbunov (@sergeynog), joxes (@Joxess)
7818	Expirable ERC-20	sirawt (@MASDXI), ADISAKBOONMARK (@ADISAKBOONMARK)
7820	Access Control Registry	Shubham Khandelwal (@shubh-ta), Anushka Yadav (@anushka642000)
7837	Diffusive Tokens	Cheng Qian (@jamesavechives) <james.walstonn@gmail.com>
7857	AI Agents NFT with Private Metadata	Ming Wu (@sparkmiw), Jason Zeng (@zenghbo), Wei Wu (@Wilbert957), Michael Heinrich (@michaelomg)
7858	Expirable NFTs and SBTs	sirawt (@MASDXI), ADISAKBOONMARK (@ADISAKBOONMARK), parametprame (@parametprame), Nacharoen (@najaroen)
7878	Bequeathable Contracts	Wamith Mockbill (@wamith)
7893	DeFi Protocol Solvency Proof Mechanism	Sean Luis Guada Rodríguez (@SeanLuis) <seanluis47@gmail.com>
7908	HD wallet In Treasury Management	Xiaoyu Liu (@elizabethxiaoyu) <jiushi.lxy@antgroup.com>, Yuxiang Fu (@tmac4096) <kunfu.fyx@antgroup.com>, Yanyi Liang <eason.lyy@antgroup.com>, Hao Zou (@BruceZH0915) <situ.zh@antgroup.com>, Siyuan Zheng (@andrewcoder666) <zhengsiyuan.zsy@antgroup.com>, yuanshanhshan (@xunayuan) <yuanshanshan.yss@antgroup.com>
7913	Signature Verifiers	Hadrien Croubois (@Amxx), Ernesto García (@ernestognw), Francisco Giordano (@frangio), Aryeh Greenberg (@arr00)
7950	Encode chain id with transaction hash	Lauri Peltonen (@microbecode)
7994	Purpose-Bound ERC-20 with Conditional Unlock	Anushka Yadav (@64anushka), Akash Kothawade (@akash3927), Atishek Singh (@atisheksingh)
8001	Agent Coordination Framework	Kwame Bryan (@KBryan)
8034	Referable NFT Royalties	Ruiqiang Li (@richard-620) <richard.620.research@gmail.com>, Qin Wang <qin.wang@data61.csiro.au>, Shiping Chen <shiping.chen@data61.csiro.au>, Saber Yu (@OniReimu), Brian Yecies <byecies@uow.edu.au>, John Le <johnle@uow.edu.au>
8042	Diamond Storage	Nick Mudge (@mudgen)
8063	Groups - Membership Tokens	Cheng Qian (@jamesavechives) <contact@deakee.com>

Last Call

Number	Review ends	Title	Author
1191	2019-11-18	Add chain id to mixed-case checksum address encoding	Juliano Rizzo (@juli)
2266	2020-12-31	Atomic Swap-based American Call Option Contract Standard	Runchao Han <runchao.han@monash.edu>, Haoyu Lin <chris.haoyul@gmail.com>, Jiangshan Yu <jiangshan.yu@monash.edu>
5008	2023-08-15	ERC-721 Nonce Extension	Anders (@0xanders), Lance (@LanceSnow), Shrug <shrug@emojidao.org>
5114	2023-09-19	Soulbound Badge	Micah Zoltu (@MicahZoltu)
5164	2023-11-15	Cross-Chain Execution	Brendan Asselstine (@asselstine), Pierrick Turelier (@PierrickGT), Chris Whinfrey (@cwhinfrey)
5216	2022-11-12	ERC-1155 Allowance Extension	Iván Mañús (@ivanmmurciaua), Juan Carlos Cantó (@EscuelaCryptoES)
5453	2023-09-27	Endorsement - Permit for Any Functions	Zainan Victor Zhou (@xinbenlv)
5496	2022-11-29	Multi-privilege Management NFT Extension	Jeremy Z (@wnft)
6224	2025-07-31	Contracts Dependencies Registry	Artem Chystiakov (@arvolear)
6357	2023-11-10	Single-contract Multi-delegatecall	Gavin John (@Pandapip1)
7744	2025-07-29	Code Index	Tim Pechersky (@peersky) <t@peersky.xyz>
7746	2025-07-29	Composable Security Middleware Hooks	Tim Pechersky (@peersky)
7943	2026-01-30	uRWA - Universal Real World Asset Interface	Dario Lo Buglio (@xaler5), Tino Martinez Molina (@tinom9), Mihai Colceriu (@mihaic195)

Review

Number	Title	Author
1185	Storage of DNS Records in ENS	Jim McDonald (@mcdee)
1202	Voting Interface	Zainan Victor Zhou (@xinbenlv), ERC-1202 Working Group <erc1202@googlegroups.com>
2333	BLS12-381 Key Generation	Carl Beekhuizen (@CarlBeek) <carl@ethereum.org>
2334	BLS12-381 Deterministic Account Hierarchy	Carl Beekhuizen (@CarlBeek) <carl@ethereum.org>
2335	BLS12-381 Keystore	Carl Beekhuizen (@CarlBeek) <carl@ethereum.org>
4337	Account Abstraction Using Alt Mempool	Vitalik Buterin (@vbuterin), Yoav Weiss (@yoavw), Dror Tirosh (@drortirosh), Shahaf Nacson (@shahafn), Alex Forshtat (@forshtat), Kristof Gazso (@kristofgazso), Tjaden Hess (@tjade273)
4824	Common Interfaces for DAOs	Joshua Tan (@thelastjosh), Isaac Patka (@ipatka), Ido Gershtein <ido@daostack.io>, Eyal Eithcowich <eyal@deepdao.io>, Michael Zargham (@mzargham), Sam Furter (@nivida)
4973	Account-bound Tokens	Tim Daubenschütz (@TimDaub)
5247	Smart Contract Executable Proposal Interface	Zainan Victor Zhou (@xinbenlv)
5269	ERC Detection and Discovery	Zainan Victor Zhou (@xinbenlv)
5289	Ethereum Notary Interface	Gavin John (@Pandapip1)
5485	Jurisdiction, Accreditation, and Enforcement	Zainan Victor Zhou (@xinbenlv)
5568	Well-Known Format for Required Actions	Gavin John (@Pandapip1)
5639	Delegation Registry	foobar (@0xfoobar), Wilkins Chung (@wwhchung) <wilkins@manifold.xyz>, ryley-o (@ryley-o), Jake Rockland (@jakerockland), andy8052 (@andy8052)
5982	Role-based Access Control	Zainan Victor Zhou (@xinbenlv)
6065	Real Estate Token	Alex (@Alex-Klasma), Ben Fusek (@bfusek), Daniel Fallon-Cyr (@dfalloncyr)
6120	Universal Token Router	Derion (@derion-io), Zergity (@Zergity), Ngo Quang Anh (@anhnq82), BerlinP (@BerlinP), Khanh Pham (@blackskin18), Hal Blackburn (@h4l)
6315	ERC-2771 Namespaced Account Abstraction	Gavin John (@Pandapip1)
6358	Cross-Chain Token States Synchronization	Shawn Zheng (@xiyu1984), Jason Cheng <chengjingxx@gmail.com>, George Huang (@virgil2019), Kay Lin (@kay404)
6366	Permission Token	Chiro (@chiro-hiro), Victor Dusart (@vdusart)
6372	Contract clock	Hadrien Croubois (@Amxx), Francisco Giordano (@frangio)
6551	Non-fungible Token Bound Accounts	Jayden Windle (@jaydenwindle), Benny Giang <bg@futureprimitive.xyz>, Steve Jang, Druzy Downs (@druzydowns), Raymond Huynh (@huynhr), Alanah Lam <alanah@futureprimitive.xyz>, Wilkins Chung (@wwhchung) <wilkins@manifold.xyz>, Paul Sullivan (@sullivph) <paul.sullivan@manifold.xyz>, Auryn Macmillan (@auryn-macmillan), Jan-Felix Schwarz (@jfschwarz), Anton Bukov (@k06a), Mikhail Melnik (@ZumZoom), Josh Weintraub (@jhweintraub) <jhweintraub@gmail.com>, Rob Montgomery (@RobAnon) <rob@revest.finance>, vectorized (@vectorized), Víctor Martínez (@vnmrtz), Adrián Pajares (@0xadrii)
6596	Cultural and Historical Asset Token	Phillip Pon <phillip@artifactlabs.com>, Gary Liu <gary@artifactlabs.com>, Henry Chan <henry@artifactlabs.com>, Joey Liu <joey@artifactlabs.com>, Lauren Ho <lauren@artifactlabs.com>, Jeff Leung <jeff@artifactlabs.com>, Brian Liang <brian@artifactlabs.com>, Joyce Li <joyce@artifactlabs.com>, Avir Mahtani <avir@artifactlabs.com>, Antoine Cote (@acote88), David Leung (@dhl)
6617	Bit Based Permission	Chiro (@chiro-hiro), Victor Dusart (@vdusart)
6734	L2 Token List	Kelvin Fichter (@smartcontracts), Andreas Freund (@Therecanbeonlyone1969), Pavel Sinelnikov (@psinelnikov)
6735	L2 Aliasing of EVM-based Addresses	Kelvin Fichter (@smartcontracts), Andreas Freund (@Therecanbeonlyone1969)
6956	Asset-bound Non-Fungible Tokens	Thomas Bergmueller (@tbergmueller), Lukas Meyer (@ibex-technology)
6997	ERC-721 with transaction validation step.	Eduard López i Fina (@eduardfina)
7015	NFT Creator Attribution	indreams (@strollinghome)
7144	ERC-20 with transaction validation step.	Eduard López i Fina (@eduardfina)
7246	Encumber - Splitting Ownership & Guarantees	Coburn Berry (@coburncoburn), Mykel Pereira (@mykelp), Scott Silver (@scott-silver)
7399	⚡ Flash Loans ⚡	Alberto Cuesta Cañada (@alcueca), Michael Amadi (@AmadiMichaels), Devtooligan (@devtooligan), Ultrasecr.eth (@ultrasecreth), Sam Bacha (@sambacha)
7417	Token Converter	Dexaran (@Dexaran) <dexaran@ethereumclassic.org>
7518	Dynamic Compliant Interop Security Token	Abhinav (@abhinav-d3v) <abhinav@zoniqx.com>, Prithvish Baidya (@d4mr) <pbaidya@zoniqx.com>, Rajat Kumar (@rajatwasan) <rwasan@zoniqx.com>, Prasanth Kalangi <pkalangi@zoniqx.com>
7531	Staked ERC-721 Ownership Recognition	Francesco Sullo (@sullof)
7586	Interest Rate Swaps	Samuel Gwlanold Edoumou (@Edoumou)
7590	ERC-20 Holder Extension for NFTs	Steven Pineda (@steven2308), Jan Turk (@ThunderDeliverer)
7628	ERC-721 Ownership Shares Extension	Chen Liaoyuan (@chenly) <cly@kip.pro>
7673	Distinguishable base256emoji Addresses	William Morriss (@wjmelements)
7674	Temporary Approval Extension for ERC-20	Xenia Shape (@byshape), Mikhail Melnik (@ZumZoom), Hadrien Croubois (@Amxx)
7677	Paymaster Web Service Capability	Lukas Rosario (@lukasrosario), Dror Tirosh (@drortirosh), Wilson Cusack (@wilsoncusack), Kristof Gazso (@kristofgazso), Hazim Jumali (@hazim-j)
7750	Decentralized Employment System	James Savechives (@jamesavechives) <james.walstonn@gmail.com>
7758	Transfer With Authorization	Peter Jihoon Kim (@petejkim), Kevin Britz (@kbrizzle), David Knott (@DavidLKnott), Dongri Jin (@dongri)
7776	Transparent Financial Statements	Ignacio Ceaglio (@Nachoxt17) <ignacioceaglio@gmail.com>
7777	Governance for Human Robot Societies	OpenMind, Jan Liphardt <jan@openmind.org>, Shaohong Zhong (@ShaohongZ), Boyuan Chen (@bchen-dev), Paige Xu <paige@openmind.org>, James Ball <james.ball@nethermind.io>, Thamer Dridi <thamer.dridi@nethermind.io>
7812	ZK Identity Registry	Artem Chystiakov (@arvolear) <artem@rarilabs.com>, Oleksandr Kurbatov <oleksandr@rarilabs.com>, Yaroslav Panasenko <yaroslav@rarilabs.com>, Michael Elliot (@michaelelliot) <mike@zkpassport.id>, Vitalik Buterin (@vbuterin)
7813	Store, Table-Based Introspectable Storage	alvarius (@alvrs), dk1a (@dk1a), frolic (@frolic), ludens (@ludns), vdrg (@vdrg), yonada <yonada@proton.me>
7829	Data Asset NFT	Allen Dong (@Allen2730), Lonika Zhang <lonika@memolabs.net>, Steven He <steven@memolabs.net>
7832	Sustainable collaborative NFT collections	Gustavo Lobo (@gflobo)
7866	Decentralised User Profiles	Kumar Anirudha (@anistark)
7936	Versioned Proxy Contract Interface	Raphina Liu (@Stamp9), Monica Jin (@mokita-j), Martin Monperrus (@monperrus)
7945	Confidential Transactions Supported Token	Siyuan Zheng (@andrewcoder666) <zhengsiyuan.zsy@antgroup.com>, Zhe Han (@iampkuhz) <hanzhe.hz@ant-intl.com>, Xiaoyu Liu (@elizabethxiaoyu) <jiushi.lxy@antgroup.com>, Wenwei Ma (@madyinglight) <huiwei.mww@antgroup.com>, Jun Meng Tan (@chadxeth) <junmeng.t@antgroup.com>, Yuxiang Fu (@tmac4096) <kunfu.fyx@antgroup.com>, Kecheng Gao (@thanks-v-me-50) <gaokecheng.gkc@antgroup.com>, Alwin Ng Jun Wei (@alwinngjw) <alwin.ng@antgroup.com>, Chenxin Wang (@3235773541) <wcx465603@antgroup.com>, Xiang Gao (@GaoYiRu) <gaoxiang.gao@antgroup.com>, yuanshanhshan (@xunayuan) <yuanshanshan.yss@antgroup.com>, Hao Zou (@BruceZH0915) <situ.zh@antgroup.com>, Yanyi Liang <eason.lyy@antgroup.com>, Yuehua Zhang (@astroyhzcc) <ruoying.zyh@antgroup.com>
8019	Minimal Wallet-Managed Auto-Login for SIWE	Ivo Georgiev (@Ivshti), Vijay Krishnavanshi (@vijaykrishnavanshi)
8111	Bound Signatures	William Morriss (@wjmelements)
8126	AI Agent Verification	Leigh Cronian (@cybercentry) <leigh.cronian@cybercentry.co.uk>, Chris Johnson <chris@virtuals.io>
8161	Transferable Tokenized Vault Requests	Cain O'Sullivan (@cosullivan), Jeroen Offerijns (@hieronx)
8167	Modular Dispatch Proxies	William Morriss (@wjmelements), Radek Svarz (@radeksvarz)

Draft

Number	Title	Author
725	General data key/value store and execution	Fabian Vogelsteller (@frozeman), Tyler Yasaka (@tyleryasaka)
838	ABI specification for REVERT reason string	Federico Bond (@federicobond), Renan Rodrigues de Souza (@RenanSouza2)
998	Composable Non-Fungible Token	Matt Lockyer <mattdlockyer@gmail.com>, Nick Mudge <nick@perfectabstractions.com>, Jordan Schalm <jordan.schalm@gmail.com>, sebastian echeverry <sebastian.echeverry@robotouniverse.com>, Zainan Victor Zhou (@xinbenlv)
3009	Transfer With Authorization	Peter Jihoon Kim (@petejkim), Kevin Britz (@kbrizzle), David Knott (@DavidLKnott)
3770	Chain-specific addresses	Lukas Schor (@lukasschor), Richard Meissner (@rmeissner), Pedro Gomes (@pedrouid), ligi <ligi@ligi.de>
4883	Composable SVG NFT	Andrew B Coathup (@abcoathup), Alex (@AlexPartyPanda), Damian Martinelli (@damianmarti), blockdev (@0xbok), Austin Griffith (@austintgriffith)
4972	Name-Owned Account	Shu Dong (@dongshu2013), Qi Zhou (@qizhou), Zihao Chen (@zihaoccc)
5115	SY Token	Vu Nguyen (@mrenoon), Long Vuong (@UncleGrandpa925), Anton Buenavista (@ayobuenavista)
5173	NFT Future Rewards (nFR)	Yale ReiSoleil (@longnshort), dRadiant (@dRadiant), D Wang, PhD <david@iob.fi>
5189	Account Abstraction via Endorsed Operations	Agustín Aguilar (@agusx1211), Philippe Castonguay (@phabc), Michael Standen (@ScreamingHawk)
5516	Soulbound Multi-owner Tokens	Lucas Martín Grasso Ramos (@LucasGrasso), Matias Arazi (@MatiArazi)
5573	Sign-In with Ethereum Capabilities, ReCaps	Oliver Terbu (@awoie), Jacob Ward (@cobward), Charles Lehner (@clehner), Sam Gbafa (@skgbafa), Wayne Chang (@wyc), Charles Cunningham (@chunningham)
5604	NFT Lien	Zainan Victor Zhou (@xinbenlv), Allen Zhou <allen@ubiloan.io>, Alex Qin <alex@ubiloan.io>
5630	New approach for encryption / decryption	Firn Protocol (@firnprotocol), Fried L. Trout, Weiji Guo (@weijiguo)
5700	Bindable Token Interface	Leeren (@leeren)
5727	Semi-Fungible Soulbound Token	Austin Zhu (@AustinZhu), Terry Chen <terry.chen@phaneroz.io>
5791	Physical Backed Tokens	2pmflow (@2pmflow), locationtba (@locationtba), Cameron Robertson (@ccamrobertson), cygaar (@cygaar), Brian Weick (@bweick), vectorized (@vectorized), djdabs (@djdabs)
6123	Smart Derivative Contract	Christian Fries (@cfries), Peter Kohl-Landgraf (@pekola), Alexandros Korpis (@kourouta)
6170	Cross-Chain Messaging Interface	Sujith Somraaj (@sujithsomraaj)
6229	Tokenized Vaults with Lock-in Period	Anderson Chen (@Ankarrr), Martinet Lee <martinetlee@gmail.com>, Anton Cheng <antonassocareer@gmail.com>
6327	Elastic Signature	George (@JXRow)
6604	Abstract Token	Chris Walker (@cr-walker) <chris@ckwalker.com>
6662	AA Account Metadata For Authentication	Shu Dong (@dongshu2013), Zihao Chen (@zihaoccc), Peter Chen (@pette1999)
6682	NFT Flashloans	out.eth (@outdoteth)
6785	ERC-721 Utilities Information Extension	Otniel Nicola (@OT-kthd), Bogdan Popa (@BogdanKTHD)
6786	Registry for royalties payment for NFTs	Otniel Nicola (@OT-kthd), Bogdan Popa (@BogdanKTHD)
6787	Order Book DEX with Two Phase Withdrawal	Jessica (@qizheng09), Roy (@royshang), Jun (@SniperUsopp)
6806	ERC-721 Holding Time Tracking	Saitama (@saitama2009), Combo <combo@1combo.io>, Luigi <luigi@1combo.io>
6821	Support ENS Name for Web3 URL	Qi Zhou (@qizhou), Qiang Zhu (@qzhodl)
6823	Token Mapping Slot Retrieval Extension	qdqd (@qd-qd) <qdqdqdqdqd@protonmail.com>
6860	Web3 URL to EVM Call Message Translation	Qi Zhou (@qizhou), Chao Pi (@pichaoqkc), Sam Wilson (@SamWilsn), Nicolas Deschildre (@nand2)
6864	Upgradable Fungible Token	Jeff Huang (@jeffishjeff)
6865	On-Chain EIP-712 Visualization	Abderrahmen Hanafi (@a6-dou)
6900	Modular Smart Contract Accounts	Adam Egyed (@adamegyed), Fangting Liu (@trinity-0111), Jay Paik (@jaypaik), Yoav Weiss (@yoavw), Huawei Gu (@huaweigu), Daniel Lim (@dlim-circle), Ruben Koch (@0xrubes), David Philipson (@dphilipson), Howy Ho (@howydev), Nikita Belenkov (@nikita-quantstamp), zer0dot (@zer0dot), David Kim (@PowerStream3604)
6932	Subscription-Based Token	360 Core <hello@360coreinc.com>, Robin Rajput (@0xRobinR)
6944	ERC-5219 Resolve Mode	Gavin John (@Pandapip1), Qi Zhou (@qizhou)
6960	Dual Layer Token	Adam Boudjemaa (@aboudjem), Mohamad Hammoud (@mohamadhammoud), Nawar Hisso (@nawar-hisso), Khawla Hassan (@khawlahssn), Mohammad Zakeri Rad (@zakrad), Ashish Sood <soodgen@gmail.com>
6981	Reserved Ownership Accounts	Paul Sullivan (@sullivph) <paul.sullivan@manifold.xyz>, Wilkins Chung (@wwchung) <wilkins@manifold.xyz>, Kartik Patel (@Slokh) <kartik@manifold.xyz>
7085	NFT Relationship Enhancement	Guang (@xg1990)
7087	MIME type for Web3 URL in Auto Mode	Qi Zhou (@qizhou), Nicolas Deschildre (@nand2)
7093	Social Recovery Interface	John Zhang (@johnz1019), Davis Xiang (@xcshuan), Kyle Xu (@kylexyxu), George Zhang (@odysseus0)
7196	Simple token, Simplified ERC-20	Xiang (@wenzhenxiang), Ben77 (@ben2077), Mingshi S. (@newnewsms)
7204	Contract wallet management token	Xiang (@wenzhenxiang), Ben77 (@ben2077), Mingshi S. (@newnewsms)
7254	Token Revenue Sharing	Quy Phan (@quyphandang), Quy Phan <quy.phan@cryptoviet.info>
7272	Ethereum Access Token	Chris Chung (@0xpApaSmURf), Raphael Roullet (@ra-phael)
7280	NFT Metadata Extension like JSON-LD	Yohei Nishikubo (@yoheinishikubo)
7303	Token-Controlled Token Circulation	Ko Fujimura (@kofujimura)
7390	Vanilla Options for ERC-20 Tokens	Ewan Humbert (@Xeway) <xeway@protonmail.com>, Lassi Maksimainen (@mlalma) <lassi.maksimainen@gmail.com>
7405	Portable Smart Contract Accounts	Aaron Yee (@aaronyee-eth)
7406	Multi-Namespace Onchain Registry	Mengshi Zhang (@MengshiZhang), Zihao Chen (@zihaoccc)
7410	ERC-20 Update Allowance By Spender	Mohammad Zakeri Rad (@zakrad), Adam Boudjemaa (@aboudjem), Mohamad Hammoud (@mohamadhammoud)
7412	On-Demand Off-Chain Data Retrieval	Noah Litvin (@noahlitvin), db (@dbeal-eth)
7425	Tokenized Reserve	Jimmy Debe (@jimstir)
7444	Time Locks Maturity	Thanh Trinh (@thanhtrinh2003) <thanh@revest.finance>, Joshua Weintraub (@jhweintraub) <josh@revest.finance>, Rob Montgomery (@RobAnon) <rob@revest.finance>
7484	Registry Extension for ERC-7579	Konrad Kopp (@kopy-kat), zeroknots (@zeroknots)
7496	NFT Dynamic Traits	Adam Montgomery (@montasaurus), Ryan Ghods (@ryanio), 0age (@0age), James Wenzel (@emo-eth), Stephan Min (@stephankmin)
7498	NFT Redeemables	Ryan Ghods (@ryanio), 0age (@0age), Adam Montgomery (@montasaurus), Stephan Min (@stephankmin)
7506	Trusted Hint Registry	Philipp Bolte (@strumswell), Dennis von der Bey (@DennisVonDerBey), Lauritz Leifermann (@lleifermann)
7507	Multi-User NFT Extension	Ming Jiang (@minkyn), Zheng Han (@hanbsd), Fan Yang (@fayang)
7508	Dynamic On-Chain Token Attributes Repository	Steven Pineda (@steven2308), Jan Turk (@ThunderDeliverer)
7509	Entity Component System	Rickey (@HelloRickey)
7510	Cross-Contract Hierarchical NFT	Ming Jiang (@minkyn), Zheng Han (@hanbsd), Fan Yang (@fayang)
7511	Minimal Proxy Contract with PUSH0	0xAA (@AmazingAng), vectorized (@Vectorized), 0age (@0age)
7512	Onchain Representation for Audits	Richard Meissner - Safe (@rmeissner), Robert Chen - OtterSec (@chen-robert), Matthias Egli - ChainSecurity (@MatthiasEgli), Jan Kalivoda - Ackee Blockchain (@jaczkal), Michael Lewellen - OpenZeppelin (@cylon56), Shay Zluf - Hats Finance (@shayzluf), Alex Papageorgiou - Omniscia (@alex-ppg)
7513	Smart NFT - A Component for Intent-Centric	MJ Tseng (@TsengMJ) <tsngmj@gmail.com>, Clay (@Clay2018) <clay.uw@outlook.com>, Jeffery.c <jeffery.c@a3sprotocol.xyz>, Johnny.c <johnny.c@a3sprotocol.xyz>
7517	Content Consent for AI/ML Data Mining	Bofu Chen (@bafu), Tammy Yang (@tammyyang)
7521	General Intents for Smart Contract Wallets	Stephen Monn (@pixelcircuits), Bikem Bengisu (@supiket)
7522	OIDC ZK Verifier for AA Account	Shu Dong (@dongshu2013) <shu@hexlink.io>, Yudao Yan <dean@dauth.network>, Song Z <s@misfit.id>, Kai Chen <kai@dauth.network>
7524	PLUME Signature in Wallets	Yush G (@Divide-By-0) <aayushg@mit.edu>, Kobi Gurkan (@kobigurk), Richard Liu (@rrrliu), Vivek Bhupatiraju (@vb7401), Barry Whitehat (@barryWhiteHat)
7527	Token Bound Function Oracle AMM	Elaine Zhang (@lanyinzly) <lz8aj@virginia.edu>, Jerry <jerrymindflow@gmail.com>, Amandafanny <amandafanny200@gmail.com>, Shouhao Wong (@wangshouh) <wongshouhao@outlook.com>, 0xPoet <0xpoets@gmail.com>
7529	Contract Discovery and eTLD+1 Association	Todd Chapman (@tthebc01), Charlie Sibbach <charlie@cwsoftware.com>, Sean Sing (@seansing)
7533	Public Cross Port	George (@JXRow), Zisu (@lazy1523)
7538	Multiplicative Tokens	Gavin John (@Pandapip1)
7546	Upgradeable Clone for Scalable Contracts	Shogo Ochiai (@shogochiai) <shogo.ochiai@pm.me>, Kai Hiroi (@KaiHiroi) <kai.hiroi@pm.me>
7548	Open IP Protocol built on NFTs	Combo <combo@1combo.io>, Saitama (@saitama2009), CT29 <CT29@1combo.io>, Luigi <luigi@1combo.io>
7555	Single Sign-On for Account Discovery	Alexander Müller (@alexmmueller), Gregory Markou (@GregTheGreek), Willem Olding (@Wollum), Belma Gutlic (@morrigan), Marin Petrunić (@mpetrunic), Pedro Gomes (@pedrouid)
7561	Simple NFT, Simplified ERC-721	Xiang (@wenzhenxiang), Ben77 (@ben2077), Mingshi S. (@newnewsms)
7562	Account Abstraction Validation Scope Rules	Yoav Weiss (@yoavw), Dror Tirosh (@drortirosh), Alex Forshtat (@forshtat), Shahaf Nacson (@shahafn)
7564	Contract wallet management NFT	Xiang (@wenzhenxiang), Ben77 (@ben2077), Mingshi S. (@newnewsms)
7565	Perpetual Contract NFTs as Collateral	Hyoungsung Kim (@HyoungsungKim) <hyougnsung@keti.re.kr>, Yong-Suk Park <yspark@keti.re.kr>, Hyun-Sik Kim <hskim@keti.re.kr>
7566	Multiplayer Game Communication	Rickey (@HelloRickey)
7572	Contract-level metadata via `contractURI()`	Devin Finzer (@dfinzer), Alex Atallah (@alexanderatallah), Ryan Ghods (@ryanio)
7573	Conditional-upon-Transfer-Decryption for DvP	Christian Fries (@cfries), Peter Kohl-Landgraf (@pekola)
7579	Minimal Modular Smart Accounts	zeroknots (@zeroknots), Konrad Kopp (@kopy-kat), Taek Lee (@leekt), Fil Makarov (@filmakarov), Elim Poon (@yaonam), Lyu Min (@rockmin216)
7580	Advertisement Tracking Interface	wart (@wartstone)
7582	Modular Accounts with Delegated Validation	Shivanshi Tyagi (@nerderlyne), Ross Campbell (@z0r0z)
7585	MixHash and Public Data Storage Proofs	Liu Zhicong (@waterflier), William Entriken (@fulldecent), Wei Qiushi (@weiqiushi), Si Changjun (@photosssa)
7589	Semi-Fungible Token Roles	Ernani São Thiago (@ernanirst), Daniel Lima (@karacurt)
7595	Collateralized NFT	571nKY (@571nKY), Cosmos (@Cosmos4k), f4t50 (@f4t50), Harpocrates (@harpocrates555)
7597	Signature Validation Extension for Permit	Yvonne Zhang (@yvonnezhangc), Aloysius Chan (@circle-aloychan)
7598	Use contract signature for signed transfer	Yvonne Zhang (@yvonnezhangc), Aloysius Chan (@circle-aloychan)
7603	ERC-1155 Multi-Asset extension	Haru (@haruu8)
7604	ERC-1155 Permit Approvals	calvbore (@calvbore), emiliolanzalaco (@emiliolanzalaco)
7613	Puppet Proxy Contract	Igor Żuk (@CodeSandwich)
7615	Atomic Push-based Data Feed Among Contracts	Elaine Zhang (@lanyinzly) <lz8aj@virginia.edu>, Jerry <jerrymindflow@gmail.com>, Amandafanny <amandafanny200@gmail.com>, Shouhao Wong (@wangshouh) <wongshouhao@outlook.com>, Doris Che (@Cheyukj) <dorischeyy@gmail.com>, Henry Yuan (@onehumanbeing) <hy2878@nyu.edu>
7617	Chunk support for ERC-5219 mode in Web3 URL	Qi Zhou (@qizhou), Nicolas Deschildre (@nand2)
7618	Content encoding in ERC-5219 mode Web3 URL	Qi Zhou (@qizhou), Nicolas Deschildre (@nand2)
7621	Basket Token	Dominic Ryder <dom@alvara.xyz>, Michael Ryder <mike@alvara.xyz>, Callum Mitchell-Clark (@AlvaraProtocol) <cal@alvara.xyz>
7629	ERC-20/ERC-721 Unified Token Interface	0xZeus1111 (@0xZeus1111), Nvuwa (@Nvuwa)
7632	Interfaces for Named Token	Zainan Victor Zhou (@xinbenlv)
7638	Batch Calls Encoding in SCA	George (@JXRow), Zisu (@lazy1523)
7641	Intrinsic RevShare Token	Conway (@0x1cc), Cathie So (@socathie), Xiaohang Yu (@xhyumiracle), Suning Yao (@fewwwww), Kartin <kartin@hyperoracle.io>
7644	ERC-721 Name Registry Extension	Chen Liaoyuan (@chenly)
7649	Bonding curve-embedded liquidity for NFTs	Arif Khan <arif@alethea.ai>, Ahmad Matyana <ahmad@alethea.ai>, Basil Gorin (@vgorin), Vijay Bhayani (@unblocktechie)
7651	Fractionally Represented Non-Fungible Token	Acme (@0xacme), Calder (@caldereth)
7652	ERC-721 Guarantee Extension	Liu.C.Dao (@CDao) <iunknow@163.com>, Sam <1047180870@qq.com>
7654	Request Method Types	Rickey (@HelloRickey)
7662	AI Agent NFTs	Greg Marlin (@marleymarl)
7679	UserOperation Builder	Derek Chiang (@derekchiang), Garvit Khatri (@plusminushalf), Fil Makarov (@filmakarov), Kristof Gazso (@kristofgazso), Derek Rein (@arein), Tomas Rocchi (@tomiir), bumblefudge (@bumblefudge)
7681	Dual Nature Multi Token Protocol	Sennett Lau (@sennett-lau)
7682	Auxiliary Funds Capability	Lukas Rosario (@lukasrosario), Wilson Cusack (@wilsoncusack), Alex Donesky (@adonesky1)
7683	Cross Chain Intents	Mark Toda (@marktoda), Matt Rice (@mrice32), Nick Pai (@nicholaspai)
7694	Solana Storage Router	Avneet Singh (@sshmatrix), 0xc0de4c0ffee (@0xc0de4c0ffee)
7695	Ownership Delegation and Context for ERC-721	Duc Tho Tran (@ducthotran2010)
7699	ERC-20 Transfer Reference Extension	Radek Svarz (@radeksvarz)
7700	Cross-chain Storage Router Protocol	Avneet Singh (@sshmatrix), 0xc0de4c0ffee (@0xc0de4c0ffee), Nick Johnson (@arachnid), Makoto Inoue (@makoto)
7710	Smart Contract Delegation	Ryan McPeck (@McOso), Dan Finlay (@DanFinlay), Rob Dawson (@rojotek), Derek Chiang (@derekchiang)
7715	Request Permissions from Wallets	Luka Isailovic (@lukaisailovic), Derek Rein (@arein), Dan Finlay (@danfinlay), Derek Chiang (@derekchiang), Fil Makarov (@filmakarov), Pedro Gomes (@pedrouid), Conner Swenberg (@ilikesymmetry), Lukas Rosario (@lukasrosario), Idris Bowman (@V00D00-child), Jeff Smale (@jeffsmale90)
7720	Deferred Token Transfer	Chen Liaoyuan (@chenly) <cly@kip.pro>
7721	Lockable Extension for ERC-1155	Piyush Chittara (@piyush-chittara)
7722	Opaque Token	Ivica Aračić (@ivica7), Ante Bešlić (@ethSplit), Mirko Katanić (@mkatanic), SWIAT
7726	Common Quote Oracle	alcueca (@alcueca), ruvaag (@ruvaag), totomanov (@totomanov), r0ohafza (@r0ohafza)
7729	Token with Metadata	msfew (@fewwwww)
7730	Structured Data Clear Signing Format	Laurent Castillo (@lcastillo-ledger), Derek Rein (@arein), Pierre Aoun (@paoun-ledger), Arik Galansky (@arikg), Bartosz Rozwarski (@llbartekll), Kaan Uzdogan (@kuzdogan), Fredrik (@Fredrik0x)
7738	Permissionless Script Registry	Victor Zhang (@zhangzhongnan928), James Brown (@JamesSmartCell)
7739	Readable Typed Signatures for Smart Accounts	vectorized (@vectorized), Sihoon Lee (@push0ebp), Francisco Giordano (@frangio), Hadrien Croubois (@Amxx), Ernesto García (@ernestognw), Im Juno (@junomonster), howydev (@howydev), Atarpara (@Atarpara), 0xcuriousapple (@0xcuriousapple)
7741	Authorize Operator	Jeroen Offerijns (@hieronx), João Martins (@0xTimepunk)
7754	Tamperproof Extension Wallets API (TWIST)	Erik Marks (@remarks), Guillaume Grosbois (@uni-guillaume)
7760	Minimal Upgradeable Proxies	Atarpara (@Atarpara), JT Riley (@jtriley-eth), Thomas (@0xth0mas), xiaobaiskill (@xiaobaiskill), Vectorized (@Vectorized)
7765	Privileged Non-Fungible Tokens Tied To RWA	frank (@frankmint2024) <frank@mintchain.io>
7766	Signature Aggregation for ERC-4337	Vitalik Buterin (@vbuterin), Yoav Weiss (@yoavw), Dror Tirosh (@drortirosh), Shahaf Nacson (@shahafn), Alex Forshtat (@forshtat)
7769	JSON-RPC API for ERC-4337	Vitalik Buterin (@vbuterin), Yoav Weiss (@yoavw), Dror Tirosh (@drortirosh), Shahaf Nacson (@shahafn), Alex Forshtat (@forshtat)
7770	Fractional Reserve Token	Yaron Velner (@yaronvel)
7774	Cache invalidation in ERC-5219 mode Web3 URL	Nicolas Deschildre (@nand2), Sam Wilson (@SamWilsn)
7779	Interoperable Delegated Accounts	David Kim (@PowerStream3604), Richard Meissner (@rmeissner), Akshay Patel (@akshay-ap), Joshua Kim (@LightningHun), Fangting (@trinity-0111), Yoav Weiss (@yoavw)
7780	Validation Module Extension for ERC-7579	zeroknots (@zeroknots), Konrad Kopp (@kopy-kat), Taek Lee (@leekt), Fil Makarov (@filmakarov)
7785	Onchain registration of chain identifiers	Marco Stronati (@paracetamolo), Jeff Lau (@jefflau)
7787	Soulbound Degradable Governance	Guilherme Neves (@0xneves), Rafael Castaneda <rafaelcastaneda@gmail.com>
7794	Grant Registry	Guilherme Neves (@0xneves)
7795	Wallet Call Token Capabilities	Agustín Aguilar (@agusx1211), Michael Standen (@ScreamingHawk), Peter Kieltyka (@pkieltyka), William Hua (@attente), Philippe Castonguay (@PhABC)
7796	Conditional send transaction RPC	Dror Tirosh (@drortirosh), Yoav Weiss (@yoavw), Alex Forshtat (@forshtat), Shahaf Nacson (@shahafn)
7802	Token With Mint/Burn Access Across Chains	skeletor (@skeletor-spaceman), parti (@0xParticle), joxes (@Joxess), ng (@0xng), agus duha (@agusduha), disco (@0xDiscotech), gotzen <gotzen@defi.sucks>, 0age <0age@uniswap.org>, Mark Tyneway <mark@oplabs.co>, Zain Bacchus <zain@oplabs.co>, Matt Solomon <msolomon@oplabs.co>, Maurelian <maurelian@protonmail.ch>, Blaine Malone (@blmalone)
7803	EIP-712 Extensions for Account Abstraction	Francisco Giordano (@frangio)
7806	Minimal intent-centric EOA smart account	hellohanchen (@hellohanchen)
7811	Wallet Asset Discovery	Luka Isailovic (@lukaisailovic), Konrad Kopp (@kopy-kat), Derek Rein (@arein), Chris Smith (@chris13524)
7821	Minimal Batch Executor Interface	Vectorized (@Vectorized), Jake Moxey (@jxom), Hadrien Croubois (@Amxx)
7827	JSON Contract with Value Version Control	lex-clinic (@lex-clinic)
7828	Interoperable Names	Sam Kaufman (@SampkaML), Marco Stronati (@paracetamolo), Yuliya Alexiev (@yuliyaalexiev), Jeff Lau (@jefflau), Sam Wilson (@samwilsn), Vitalik Buterin (@vbuterin), Teddy (@0xteddybear), Joxes (@Joxess), Racu (@0xRacoon), Skeletor Spaceman (@0xskeletor-spaceman), TiTi (@0xtiti), Gori (@0xGorilla), Ardy (@0xArdy), Onizuka (@onizuka-wl), Lumi (@oxlumi), Moebius (@0xmoebius), Thomas Clowes (@clowestab), Prem Makeig (@nxt3d), Mono (@0xMonoAx), Orca (@0xrcinus)
7831	Multi-Chain Addressing	Sam Wilson (@SamWilsn) <sam@binarycake.ca>
7836	Wallet Call Preparation API	Lukas Rosario (@lukasrosario), Conner Swenberg (@ilikesymmetry), Adam Hodges (@ajhodges), Paaras Bhandari (@paarasbhandari), Jake Moxey (@jxom)
7841	Cross-chain Message Format and Mailbox	Ellie Davidson (@elliedavidson), Alex Xiong (@alxiong), Philippe Camacho (@philippecamacho), and Ben Fisch (@benafisch)
7845	Universal Orchestrator RPC	Kieran Goodary (@IAmKio), Pillar Wallet (@pillarwallet), Luke Wickens (@lbw33), Rana Khoury (@RanaBug)
7846	Wallet Connection API	Conner Swenberg (@ilikesymmetry), Jake Moxey (@jxom), Lukas Rosario (@lukasrosario)
7847	Social Media NFTs	Nick Juntilla (@nickjuntilla) <nick@ownerfy.com>
7856	Chain-Specific Payment Requests	Jack Chuma (@jackchuma)
7861	ERC-721 Verifiable Credential Extension	Valerio Massimo Camaiani (@vmc-crossmint)
7871	Wallet Signing API	Lukas Rosario (@lukasrosario), Jake Moxey (@jxom), Cody Crozier (@wcrozier12), Conner Swenberg (@ilikesymmetry)
7876	Ethereum Network Configuration for DApps	Bogdan Gusiev (@bogdan), Sergey Bomko (@aquiladev)
7884	Operation Router	Lucas Picollo (@pikonha), Alex Netto (@alextnetto), Nick Johnson (@arachnid)
7887	Cancelation for ERC-7540 Tokenized Vaults	Jeroen Offerijns (@hieronx), Vikram Arun (@vikramarun)
7888	Crosschain Broadcaster	Henry Arneson (@godzillaba), Chris Buckland (@yahgwai)
7891	Splitting and Merging of NFTs	Nitin Bhagat (@nitin312) <bhagatnitin312@gmail.com>, JongWook Bae <bae@cwnu.ac.kr>, Su-Hyun Lee <sleepl@changwon.ac.kr>
7895	API for Hierarchical Accounts	Wilson Cusack (@wilsoncusack), Jake Feldman (@jakefeldman), Montana Wong (@montycheese), Felix Zhang (@fan-zhang-sv), Jake Moxey (@jxom)
7902	Wallet Capabilities for Account Abstraction	Yoav Weiss (@yoavw), Alex Forshtat (@forshtat), Dror Tirosh (@drortirosh), Shahaf Nacson (@shahafn)
7920	Composite EIP-712 Signatures	Sola Ogunsakin (@sola92)
7929	PermaLink Asset Bound Token	Mihai Onila (@MihaiORO), Nick Zeman (@NickZCZ), Narcis Cotaie (@NarcisCRO)
7930	Interoperable Addresses	Teddy (@0xteddybear), Joxes (@0xJoxess), Nick Johnson (@Arachnid), Francisco Giordano (@frangio), Skeletor Spaceman (@skeletor-spaceman), Racu (@0xRacoon), TiTi (@0xtiti), Gori (@0xGorilla), Ardy (@0xArdy), Onizuka (@onizuka-wl), Sam Kaufman (@SampkaML), Marco Stronati (@paracetamolo), Yuliya Alexiev (@yuliyaalexiev), Jeff Lau (@jefflau), Sam Wilson (@samwilsn), Vitalik Buterin (@vbuterin), Thomas Clowes (@clowestab), Mono (@0xMonoAx), Prem Makeig (@nxt3d), Orca (@0xrcinus)
7946	Unidirectional Wallet Uplink aka UWULink	Moody Salem (@moodysalem), Tina Zheng (@tinaszheng)
7947	Account Abstraction Recovery Interface	Artem Chystiakov (@arvolear) <artem@rarilabs.com>
7955	Permissionless CREATE2 Factory	Nicholas Rodrigues Lordello (@nlordell), Richard Meissner (@rmeissner), Valentin Seehausen (@vseehausen)
7962	Key Hash Based Tokens	Alex Tian (@dugubuyan), Zhixiong Pan (@nake13), Geoffrey (@stbrahms) <geoffrey@datadance.ai>, liyingxuan (@LiYingxuan) <liyingxuan@datadance.ai>
7964	Crosschain EIP-712 Signatures	Ernesto García (@ernestognw)
7965	Proof-based Broadcast in ERC-7786 Gateways	Ernesto García (@ernestognw)
7968	Owner-Authorized Token Transfer Protocol	Julius Lauterbach (@Julius278)
7969	DomainKeys Identified Mail (DKIM) Registry	Mike Fu (@fumeng00mike), Matthew Yu (@0xknon), Ernesto García (@ernestognw)
7984	Confidential Fungible Token	Aryeh Greenberg (@arr00), Ernesto García (@ernestognw), Hadrien Croubois (@Amxx), Ghazi Ben Amor (@GBAZama), Clement Danjou (@immortal-tofu), Joseph Andre Turk (@jatZama), Silas Davis (@silasdavis), Nicolas Pasquier (@npasquie)
7985	Gateway Attributes for Message Control	Ernesto García (@ernestognw), Kalman Lajko (@LajkoKalman), Valera Grinenko (@0xValera)
7988	Minimal Avatar Smart Wallet (MASW)	0xMostafas (@MostafaS) <0xmostafas@proton.me>
7992	Verifiable ML Model Inference (ZKML)	Aryaethn (@aryaethn)
7996	Contract Feature Detection	raffy.eth (@adraffy)
8000	Operator contract for non delegated EOAs	Marcelo Morgado (@marcelomorgado), Manoj Patidar (@patidarmanoj10)
8002	Simplified Payment Verification Gateway	Artem Chystiakov (@arvolear), Oleh Komendant (@Hrom131)
8004	Trustless Agents	Marco De Rossi (@MarcoMetaMask), Davide Crapis (@dcrapis) <davide@ethereum.org>, Jordan Ellis <jordanellis@google.com>, Erik Reppel <erik.reppel@coinbase.com>
8017	Payout Race	Kyle Thornton (@kyle) <kyle@cowrie.io>
8023	Multi-step Contract Ownership	David Kim (@PowerStream3604)
8033	Agent Council Oracles	Rohan Parikh (@phiraml), Jon Michael Ross (@jonmross)
8041	Fixed-Supply Agent NFT Collections	Prem Makeig (@nxt3d)
8048	Onchain Metadata for Token Registries	Prem Makeig (@nxt3d), Rafael Abuawad (@rafael-abuawad)
8049	Contract-Level Onchain Metadata	Prem Makeig (@nxt3d), Rafael Abuawad (@rafael-abuawad)
8056	Scaled UI Amount Extension for ERC-20 Tokens	Chris Ridmann (@cridmann) <chris@superstate.co>, Daniel Gretzke (@gretzke), Gilbert Shih <chung.shih@robinhood.com>, Tino Martinez Molina (@tinom9)
8065	Zero Knowledge Token Wrapper	Jiahui Cui (@doublespending), 0xZPL (@0xZPL)
8074	Self-Describing Bytes via EIP-712 Selectors	Andrew Richardson (@awrichar)
8092	Associated Accounts	Steve Katzman (@stevieraykatz), Amie Corso (@amiecorso), Stephan Cilliers (@stephancill)
8106	RWA Event-based Compliance Framework	Andrew Wang (@wz14) <zhuowangy2k@outlook.com>, Jack Yin (@0xjackey) <0xjackey@gmail.com>
8107	ENS Trust Registry for Agent Coordination	Kwame Bryan (@KBryan)
8110	Domain Architecture for Diamonds	Hoang (@0x76agabond)
8113	Series Accounting for Incentivized Vaults	Yash Saraswat (@0xpanicError)
8117	Anti-Poisoning Compact EVM Address Format	Zainan Victor Zhou (@xinbenlv)
8119	Parameterized Storage Keys	Prem Makeig (@nxt3d)
8121	Cross-Chain Function Calls via Hooks	Prem Makeig (@nxt3d)
8122	Minimal Agent Registry	Prem Makeig (@nxt3d)
8127	Human Readable Token Identifiers	Prem Makeig (@nxt3d)
8152	Content-Addressable Logic Modules (CALM)	Radek Svarz (@radeksvarz), Nick Mudge (@mudgen)
8153	Facet-Based Diamonds	Nick Mudge (@mudgen)
8183	Agentic Commerce	Davide Crapis (@dcrapis), Bryan Lim (@ai-virtual-b), Tay Weixiong (@twx-virtuals), Chooi Zuhwa (@Zuhwa)
8196	AI Agent Authenticated Wallet	Leigh Cronian (@cybercentry) <leigh.cronian@cybercentry.co.uk>
8199	Sandboxed Smart Wallet	David Kim (@PowerStream3604)

Stagnant

Number	Title	Author
205	ENS support for contract ABIs	Nick Johnson <nick@ethereum.org>
634	Storage of text records in ENS	Richard Moore (@ricmoo)
801	Canary Standard	ligi <ligi@ligi.de>
823	Token Exchange Standard	Kashish Khullar <kkhullar7@gmail.com>
831	URI Format for Ethereum	ligi (@ligi)
884	DGCL Token	Dave Sag <davesag@gmail.com>
897	DelegateProxy	Jorge Izquierdo <jorge@aragon.one>, Manuel Araoz <manuel@zeppelin.solutions>
900	Simple Staking Interface	Dean Eigenmann <dean@tokenate.io>, Jorge Izquierdo <jorge@aragon.one>
902	Token Validation	Brooklyn Zelenka (@expede), Tom Carchrae (@carchrae), Gleb Naumenko (@naumenkogs)
918	Mineable Token Standard	Jay Logelin <jlogelin@alumni.harvard.edu>, Infernal_toast <admin@0xbitcoin.org>, Michael Seiler <mgs33@cornell.edu>, Brandon Grill <bg2655@columbia.edu>
926	Address metadata registry	Nick Johnson <nick@ethereum.org>
927	Generalised authorisations	Nick Johnson <nick@ethereum.org>
1056	Ethereum Lightweight Identity	Pelle Braendgaard <pelle.braendgaard@consensys.net>, Joel Torstensson <oed@consensys.net>
1062	Formalize IPFS hash into ENS(Ethereum Name Service) resolver	Phyrex Tsai <phyrex@portal.network>, Portal Network Team
1066	Status Codes	Brooklyn Zelenka (@expede), Tom Carchrae (@carchrae), Gleb Naumenko (@naumenkogs)
1077	Gas relay for contract calls	Alex Van de Sande <avsa@ethereum.org>, Ricardo Guilherme Schmidt (@3esmit)
1078	Universal login / signup using ENS subdomains	Alex Van de Sande <avsa@ethereum.org>
1080	Recoverable Token	Bradley Leatherwood <bradleat@inkibra.com>
1081	Standard Bounties	Mark Beylin <mark.beylin@consensys.net>, Kevin Owocki <kevin.owocki@consensys.net>, Ricardo Guilherme Schmidt (@3esmit)
1129	Standardised DAPP announcements	Jan Turk (@ThunderDeliverer)
1132	Extending ERC20 with token locking capability	nitika-goel <nitika@govblocks.io>
1175	Wallet & shop standard for all tokens (erc20)	Jet Lim (@Nitro888)
1178	Multi-class Token Standard	Albert Chon <achon@stanford.edu>
1203	ERC-1203 Multi-Class Token Standard (ERC-20 Extension)	Jeff Huang <jeffishjeff@gmail.com>, Min Zu <crawlregister@gmail.com>
1207	DAuth Access Delegation Standard	Xiaoyu Wang (@wxygeek), Bicong Wang (@Wangbicong)
1261	Membership Verification Token (MVT)	Chaitanya Potti (@chaitanyapotti), Partha Bhattacharya (@pb25193)
1319	Smart Contract Package Registry Interface	Piper Merriam <piper@ethereum.org>, Christopher Gewecke <christophergewecke@gmail.com>, g. nicholas d'andrea <nick.dandrea@consensys.net>, Nick Gheorghita (@njgheorghita)
1337	Subscriptions on the blockchain	Kevin Owocki <kevin@gitcoin.co>, Andrew Redden <andrew@blockcrushr.com>, Scott Burke <scott@blockcrushr.com>, Kevin Seagraves <k.s.seagraves@gmail.com>, Luka Kacil <luka.kacil@gmail.com>, Štefan Šimec <stefan.simec@gmail.com>, Piotr Kosiński (@kosecki123), ankit raj <tradeninja7@gmail.com>, John Griffin <john@atchai.com>, Nathan Creswell <nathantr@gmail.com>
1386	Attestation management contract	Weiwu Zhang <a@colourful.land>, James Sangalli <j.l.sangalli@gmail.com>
1387	Merkle Tree Attestations with Privacy enabled	Weiwu Zhang <a@colourful.land>, James Sangalli <j.l.sangalli@gmail.com>
1388	Attestation Issuers Management List	Weiwu Zhang <a@colourful.land>, James Sangalli <j.l.sangalli@gmail.com>
1417	Poll Standard	Chaitanya Potti (@chaitanyapotti), Partha Bhattacharya (@pb25193)
1438	dApp Components (avatar) & Universal Wallet	Jet Lim (@Nitro888)
1444	Localized Messaging with Signal-to-Text	Brooklyn Zelenka (@expede), Jennifer Cooper (@jenncoop)
1450	ERC-1450 A compatible security token for issuing and trading SEC-compliant securities	John Shiple (@johnshiple), Howard Marks <howard@startengine.com>, David Zhang <david@startengine.com>
1462	Base Security Token	Maxim Kupriianov <mk@atlant.io>, Julian Svirsky <js@atlant.io>
1484	Digital Identity Aggregator	Anurag Angara <anurag.angara@gmail.com>, Andy Chorlian <andychorlian@gmail.com>, Shane Hampton <shanehampton1@gmail.com>, Noah Zinsmeister <noahwz@gmail.com>
1491	Human Cost Accounting Standard (Like Gas but for humans)	Iamnot Chris (@cohabo)
1504	Upgradable Smart Contract	Kaidong Wu <wukd94@pku.edu.cn>, Chuqiao Ren <cr025@bucknell.edu>, Ruthia He <rujiahe@gmail.com>, Yun Ma <mayun@pku.edu.cn>, Xuanzhe Liu <liuxuanzhe@pku.edu.cn>
1523	Standard for Insurance Policies as ERC-721 Non Fungible Tokens	Christoph Mussenbrock (@christoph2806)
1577	contenthash field for ENS	Dean Eigenmann <dean@ens.domains>, Nick Johnson <nick@ens.domains>
1581	Non-wallet usage of keys derived from BIP-32 trees	Michele Balistreri (@bitgamma)
1592	Address and ERC20-compliant transfer rules	Cyril Lapinte <cyril.lapinte@mtpelerin.com>, Laurent Aapro <laurent.aapro@mtpelerin.com>
1613	Gas stations network	Yoav Weiss <yoav@tabookey.com>, Dror Tirosh <dror@tabookey.com>, Alex Forshtat <alex@tabookey.com>
1616	Attribute Registry Standard	0age (@0age), Santiago Palladino (@spalladino), Leo Arias (@elopio), Alejo Salles (@fiiiu), Stephane Gosselin (@thegostep)
1620	Money Streaming	Paul Berg (@PaulRBerg)
1633	Re-Fungible Token Standard (RFT)	Billy Rennekamp (@okwme), Dan Long <dan@artblx.com>, Kiryl Yermakou <kiryl@artblx.com>, Nate van der Ende <nate@artblx.com>
1710	URL Format for Web3 Browsers	Bruno Barbieri (@brunobar79)
1753	Smart Contract Interface for Licences	Lucas Cullen (@BitcoinBrisbane), Kai Yeung (@CivicKai), Anna Crowley <annaelizabethcrowley@gmail.com>, Caroline Marshall <caroline.marshall888@gmail.com>, Katrina Donaghy <katrina@civicledger.com>
1761	Scoped Approval Interface	Witek Radomski <witek@enjin.io>, Andrew Cooke <ac0dem0nk3y@gmail.com>, James Therien <james@enjin.io>, Eric Binet <eric@enjin.io>
1775	App Keys, application specific wallet accounts	Vincent Eli (@Bunjin), Dan Finlay (@DanFinlay)
1812	Ethereum Verifiable Claims	Pelle Braendgaard (@pelle)
1822	Universal Upgradeable Proxy Standard (UUPS)	Gabriel Barros <gabriel@terminal.co>, Patrick Gallagher <blockchainbuddha@gmail.com>
1844	ENS Interface Discovery	Nick Johnson (@arachnid)
1900	dType - Decentralized Type System for EVM	Loredana Cirstea (@loredanacirstea), Christian Tzurcanu (@ctzurcanu)
1921	dType Functions Extension	Loredana Cirstea (@loredanacirstea), Christian Tzurcanu (@ctzurcanu)
1922	zk-SNARK Verifier Standard	Michael Connor <michael.connor@uk.ey.com>, Chaitanya Konda <chaitanya.konda@uk.ey.com>, Duncan Westland <duncan.westland@uk.ey.com>
1923	zk-SNARK Verifier Registry Standard	Michael Connor <michael.connor@uk.ey.com>, Chaitanya Konda <chaitanya.konda@uk.ey.com>, Duncan Westland <duncan.westland@uk.ey.com>
1948	Non-fungible Data Token	Johann Barbie (@johannbarbie), Ben Bollen <ben@ost.com>, pinkiebell (@pinkiebell)
1973	Scalable Rewards	Lee Raj (@lerajk), Qin Jian (@qinjian)
1996	Holdable Token	Julio Faura <julio@adhara.io>, Fernando Paris <fer@io.builders>, Daniel Lehrner <daniel@io.builders>
2009	Compliance Service	Daniel Lehrner <daniel@io.builders>
2018	Clearable Token	Julio Faura <julio@adhara.io>, Fernando Paris <fer@io.builders>, Daniel Lehrner <daniel@io.builders>
2019	Fundable Token	Fernando Paris <fer@io.builders>, Julio Faura <julio@adhara.io>, Daniel Lehrner <daniel@io.builders>
2020	E-Money Standard Token	Julio Faura <julio@adhara.io>, Fernando Paris <fer@io.builders>, Daniel Lehrner <daniel@io.builders>
2021	Payoutable Token	Fernando Paris <fer@io.builders>, Julio Faura <julio@adhara.io>, Daniel Lehrner <daniel@io.builders>
2157	dType Storage Extension - Decentralized Type System for EVM	Loredana Cirstea (@loredanacirstea), Christian Tzurcanu (@ctzurcanu)
2193	dType Alias Extension - Decentralized Type System	Loredana Cirstea (@loredanacirstea), Christian Tzurcanu (@ctzurcanu)
2304	Multichain address resolution for ENS	Nick Johnson <nick@ens.domains>
2386	Ethereum 2 Hierarchical Deterministic Walletstore	Jim McDonald <Jim@mcdee.net>
2390	Geo-ENS	James Choncholas (@james-choncholas)
2400	Transaction Receipt URI	Ricardo Guilherme Schmidt (@3esmit), Eric Dvorsak (@yenda)
2470	Singleton Factory	Ricardo Guilherme Schmidt (@3esmit)
2477	Token Metadata Integrity	Kristijan Sedlak (@xpepermint), William Entriken <github.com@phor.net>, Witek Radomski <witek@enjin.io>
2494	Baby Jubjub Elliptic Curve	Barry WhiteHat (@barryWhiteHat), Marta Bellés (@bellesmarta), Jordi Baylina (@jbaylina)
2520	Multiple contenthash records for ENS	Filip Štamcar (@filips123)
2525	ENSLogin	Hadrien Croubois (@amxx)
2544	ENS Wildcard Resolution	Nick Johnson (@arachnid), 0age (@0age)
2569	Saving and Displaying Image Onchain for Universal Tokens	Hua Zhang (@dgczhh), Yuefei Tan (@whtyfhas), Derek Zhou (@zhous), Ran Xing (@lemontreeran)
2615	Non-Fungible Token with mortgage and rental functions	Kohshi Shiba <kohshi.shiba@gmail.com>
2645	Hierarchical Deterministic Wallet for Layer-2	Tom Brand <tom@starkware.co>, Louis Guthmann <louis@starkware.co>
2680	Ethereum 2 wallet layout	Jim McDonald <Jim@mcdee.net>
2746	Rules Engine Standard	Aaron Kendall (@jaerith), Juan Blanco (@juanfranblanco)
2767	Contract Ownership Governance	Soham Zemse (@zemse), Nick Mudge (@mudgen)
2770	Meta-Transactions Forwarder Contract	Alex Forshtat (@forshtat), Dror Tirosh (@drortirosh)
2848	My Own Messages (MOM)	Giuseppe Bertone (@Neurone)
2876	Deposit contract and address standard	Jonathan Underwood (@junderw)
2917	Staking Reward Calculation	Tony Carson <tony.carsonn@gmail.com>, Mehmet Sabir Kiraz <m.kiraz@gmail.com>, Süleyman Kardaş <skardas@gmail.com>
2942	EthPM URI Specification	Nick Gheorghita (@njgheorghita), Piper Merriam (@pipermerriam), g. nicholas d'andrea (@gnidan), Benjamin Hauser (@iamdefinitelyahuman)
2980	Swiss Compliant Asset Token	Gianluca Perletti (@Perlets9), Alan Scarpellini (@alanscarpellini), Roberto Gorini (@robertogorini), Manuel Olivi (@manvel79)
3000	Optimistic enactment governance standard	Jorge Izquierdo (@izqui), Fabien Marino (@bonustrack)
3005	Batched meta transactions	Matt (@defifuture)
3135	Exclusive Claimable Token	Zhenyu Sun (@Ungigdu)
3224	Described Data	Richard Moore (@ricmoo), Nick Johnson (@arachnid)
3234	Batch Flash Loans	Alberto Cuesta Cañada (@albertocuestacanada), Fiona Kobayashi (@fifikobayashi), fubuloubu (@fubuloubu), Austin Williams (@onewayfunction)
3386	ERC-721 and ERC-1155 to ERC-20 Wrapper	Calvin Koder (@ashrowz)
3440	ERC-721 Editions Standard	Nathan Ginnever (@nginnever)
3450	Standardized Shamir Secret Sharing Scheme for BIP-39 Mnemonics	Daniel Streit (@danielstreit)
3561	Trust Minimized Upgradeability Proxy	Sam Porter (@SamPorter1984)
3569	Sealed NFT Metadata Standard	Sean Papanikolas (@pizzarob)
3589	Assemble assets into NFTs	Zhenyu Sun (@Ungigdu), Xinqi Yang (@xinqiyang)
3722	Poster	Auryn Macmillan (@auryn-macmillan)
3754	A Vanilla Non-Fungible Token Standard	Simon Tian (@simontianx)
3772	Compressed Integers	Soham Zemse (@zemse)
4341	Ordered NFT Batch Standard	Simon Tian (@simontianx)
4353	Interface for Staked Tokens in NFTs	Rex Creed (@aug2uag), Dane Scarborough <dane@nftapps.us>
4393	Micropayments for NFTs and Multi Tokens	Jules Lai (@julesl23)
4430	Described Transactions	Richard Moore (@ricmoo), Nick Johnson (@arachnid)
4494	Permit for ERC-721 NFTs	Simon Fremaux (@dievardump), William Schwab (@wschwab)
4521	721/20-compatible transfer	Ross Campbell (@z0r0z)
4524	Safer ERC-20	William Schwab (@wschwab)
4527	QR Code transmission protocol for wallets	Aaron Chen (@aaronisme), Sora Lee (@soralit), ligi (@ligi), Dan Miller (@danjm), AndreasGassmann (@andreasgassmann), xardass (@xardass), Lixin Liu (@BitcoinLixin)
4546	Wrapped Deposits	Justice Hudson (@jchancehud)
4671	Non-Tradable Tokens Standard	Omar Aflak (@omaraflak), Pol-Malo Le Bris, Marvin Martin (@MarvinMartin24)
4675	Multi-Fractional Non-Fungible Tokens	David Kim (@powerstream3604)
4799	Non-Fungible Token Ownership Designation Standard	David Buckman (@davidbuckman), Isaac Buckman (@isaacbuckman)
4885	Subscription NFTs and Multi Tokens	Jules Lai (@julesl23)
4886	Proxy Ownership Register	Omnus Sunmo (@omnus)
4931	Generic Token Upgrade Standard	John Peterson (@John-peterson-coinbase), Roberto Bayardo (@roberto-bayardo), David Núñez (@cygnusv)
4944	Contract with Exactly One Non-fungible Token	Víctor Muñoz (@victormunoz), Josep Lluis de la Rosa (@peplluis7), Andres El-Fakdi (@Bluezfish)
4950	Entangled Tokens	Víctor Muñoz (@victormunoz), Josep Lluis de la Rosa (@peplluis7), Easy Innova (@easyinnova)
4974	Ratings	Daniel Tedesco (@dtedesco1)
4987	Held token interface	Devin Conley (@devinaconley)
5005	Zodiac Modular Accounts	Auryn Macmillan (@auryn-macmillan), Kei Kreutler (@keikreutler)
5018	Filesystem-like Interface for Contracts	Qi Zhou (@qizhou)
5050	Interactive NFTs with Modular Environments	Alexi (@alexi)
5058	Lockable Non-Fungible Tokens	Tyler (@radiocaca), Alex (@gojazdev), John (@sfumato00)
5094	URL Format for Ethereum Network Switching	Luc van Kampen (@lucemans), Jakob Helgesson (@svemat01), Joshua Hendrix (@thejoshuahendrix)
5095	Principal Token	Julian Traversa (@JTraversa), Robert Robbins (@robrobbins), Alberto Cuesta Cañada (@alcueca)
5131	SAFE Authentication For ENS	Wilkins Chung (@wwhchung) <wilkins@manifold.xyz>, Jalil Wahdatehagh (@jwahdatehagh), Cry (@crydoteth), Sillytuna (@sillytuna), Cyberpnk (@CyberpnkWin)
5139	Remote Procedure Call Provider Lists	Sam Wilson (@SamWilsn)
5143	Slippage Protection for Tokenized Vault	Hadrien Croubois (@amxx)
5185	NFT Updatable Metadata Extension	Christophe Le Bars (@clbrge)
5187	Extend EIP-1155 with rentable usage rights	DerivStudio (@DerivStudio)
5218	NFT Rights Management	James Grimmelmann (@grimmelm), Yan Ji (@iseriohn), Tyler Kell (@relyt29)
5252	Account-bound Finance	Hyungsuk Kang (@hskang9), Viktor Pernjek (@smuxx)
5298	ENS Trust to hold NFTs under ENS name	Zainan Victor Zhou (@xinbenlv)
5334	EIP-721 User And Expires And Level Extension	Yan (@yan253319066)
5409	EIP-1155 Non-Fungible Token extension	Ronan Sandford (@wighawag)
5437	Security Contact Interface	Zainan Zhou (@xinbenlv)
5501	Rental & Delegation NFT - EIP-721 Extension	Jan Smrža (@smrza), David Rábel (@rabeles11), Tomáš Janča <tomas.janca@jtbstorage.eu>, Jan Bureš (@JohnyX89), DOBBYLABS (@DOBBYLABS)
5505	EIP-1155 asset backed NFT extension	liszechung (@liszechung)
5539	Revocation List Registry	Philipp Bolte (@strumswell), Lauritz Leifermann (@lleifermann), Dennis von der Bey (@DennisVonDerBey)
5553	Representing IP and its Royalty Structure	Roy Osherove (@royosherove)
5554	NFT Legal Use, Repurposing, and Remixing	Isaac Patka (@ipatka), COALA Licensing Taskforce <info@coala.org>
5559	Cross Chain Write Deferral Protocol	Paul Gauvreau (@0xpaulio), Nick Johnson (@arachnid)
5560	Redeemable NFTs	Olivier Fernandez (@fernandezOli), Frédéric Le Coidic (@FredLC29), Julien Béranger (@julienbrg)
5633	Composable Soulbound NFT, EIP-1155 Extension	HonorLabs (@honorworldio)
5635	NFT Licensing Agreements	Timi (@0xTimi), 0xTriple7 (@ysqi)
5643	Subscription NFTs	cygaar (@cygaar)
5719	Signature replacement interface	Agustin Aguilar (@Agusx1211)
5744	Latent Fungible Token	Cozy Finance (@cozyfinance), Tony Sheng (@tonysheng), Matt Solomon (@mds1), David Laprade (@davidlaprade), Payom Dousti (@payomdousti), Chad Fleming (@chad-js), Franz Chen (@Dendrimer)
5753	Lockable Extension for EIP-721	Filipp Makarov (@filmakarov)
5805	Voting with delegation	Hadrien Croubois (@Amxx), Francisco Giordano (@frangio)
5827	Auto-renewable allowance extension	zlace (@zlace0x), zhongfu (@zhongfu), edison0xyz (@edison0xyz)
5850	Complex Numbers stored in `bytes32` types	Paul Edge (@genkifs)
5851	On-Chain Verifiable Credentials	Yu Liu (@yuliu-debond), Junyi Zhong (@Jooeys)
5883	Token Transfer by Social Recovery	Erhard Dinhobl (@mrqc), Kevin Riedl (@wsdt)
5902	Smart Contract Event Hooks	Simon Brown (@orbmis)
6047	ERC-721 Balance indexing via Transfer event	Zainan Victor Zhou (@xinbenlv)
6268	Untransferability Indicator for EIP-1155	Yuki Aoki (@yuki-js)
6353	Charity token	Aubay <blockchain-team@aubay.com>, BOCA Jeabby (@bjeabby1507), EL MERSHATI Laith (@lth-elm), KEMP Elia (@eliakemp)
6384	Human-readable offline signatures	Tal Be'ery <tal@zengo.com>, RoiV (@DeVaz1)
6464	Multi-operator, per-token ERC-721 approvals.	Cristian Espinoza (@crisgarner), Simon Fremaux (@dievardump), David Huber (@cxkoda), and Arran Schlosberg (@aschlosberg)
6506	P2P Escrowed Governance Incentives	Josh Weintraub (@jhweintraub)

Withdrawn

Number	Title	Author
67	URI Scheme with Metadata, Value and Bytecode	Alex Van de Sande (@alexvansande)
875	Simpler NFT standard with batching and native atomic swaps	Weiwu Zhang <a@colourful.land>, James Sangalli <j.l.sangalli@gmail.com>
1123	Revised Ethereum Smart Contract Packaging Standard	g. nicholas d’andrea (@gnidan), Piper Merriam (@pipermerriam), Nick Gheorghita (@njgheorghita), Danny Ryan (@djrtwo)
1154	Oracle Interface	Alan Lu (@cag)
1538	Transparent Contract Standard	Nick Mudge <nick@perfectabstractions.com>
7897	Wallet-Linked Services for Smart Accounts	Francesco Sullo (@sullof)
8109	Diamonds, Simplified	Nick Mudge (@mudgen)

Ethereum EIPs A feed of all EIPs {{ site.url }} {{ site.time | date_to_rfc822 }} {% assign eips = site.pages | sort: 'eip' %} {% for eip in eips %} {{ eip.title | xml_escape }} {{ eip.type | xml_escape }}/{{ eip.category | xml_escape }} {% if eip.discussions-to %} {{ eip.discussions-to | xml_escape }} {% endif %} {{ eip.content | xml_escape }} {{ eip.created | date_to_rfc822 }} {{ site.url }}{{ eip.url }} {{ site.url }}{{ eip.url }} {% endfor %}

Core

{% assign eips=site.pages|where:"type","Standards Track"|where:"category","Core" %} {% include eiptable.html eips=eips %}

Ethereum EIPs - Last Call Review All EIPs which are in the "last call" status, please help review these and provide your feedback! {{ site.url }} {{ site.time | date_to_rfc822 }} {% assign eips = site.pages | sort: 'eip' %} {% for eip in eips %} {% if eip.category == "ERC" %} {% if eip.status == "Last Call" %} {% capture description %}

EIP #{{ eip.eip }} - {{eip.title }} is in Last Call status. It is authored by {{ eip.author }} and was originally created {{ eip.created }}. It is in the {{ eip.category }} category of type {{ eip.type }}. Please review and note any changes that should block acceptance.

{% if eip.discussions-to %}

The author has requested that discussions happen at the following URL: {{ eip.discussions-to }}

{% endif %}

{{ eip.content }} {% endcapture %} {{ eip.title | xml_escape }} {{ description | xml_escape }} {{ eip.created | date_to_rfc822 }} {{ site.url }}/{{ eip.url }} {{ site.url }}/{{ eip.url }} {% endif %} {% endif %} {% endfor %}

ERC

{% assign eips=site.pages|where:"type","Standards Track"|where:"category","ERC" %} {% include eiptable.html eips=eips %}

Ethereum ERCs All updates for ERCs {{ site.url }} {{ site.time | date_to_rfc822 }} {% assign eips = site.pages | sort: 'eip' %} {% for eip in eips %} {% if eip.category == "ERC" %} {% capture description %}

EIP #{{ eip.eip }} - {{eip.title }} is in the {{ eip.category }} category of type {{ eip.type }} and was just updated.

{% if eip.discussions-to %}

The author has requested that discussions happen at the following URL: {{ eip.discussions-to }}

{% endif %}

Home

EIPs

Ethereum Improvement Proposals (EIPs) describe standards for the Ethereum platform, including core protocol specifications, client APIs, and contract standards. Network upgrades are discussed separately in the Ethereum Project Management repository.

Contributing

First review EIP-1. Then clone the repository and add your EIP to it. There is a template EIP here. Then submit a Pull Request to Ethereum's EIPs repository.

EIP status terms

Idea - An idea that is pre-draft. This is not tracked within the EIP Repository.
Draft - The first formally tracked stage of an EIP in development. An EIP is merged by an EIP Editor into the EIP repository when properly formatted.
Review - An EIP Author marks an EIP as ready for and requesting Peer Review.
Last Call - This is the final review window for an EIP before moving to FINAL. An EIP editor will assign Last Call status and set a review end date (`last-call-deadline`), typically 14 days later. If this period results in necessary normative changes it will revert the EIP to Review.
Final - This EIP represents the final standard. A Final EIP exists in a state of finality and should only be updated to correct errata and add non-normative clarifications.
Stagnant - Any EIP in Draft or Review if inactive for a period of 6 months or greater is moved to Stagnant. An EIP may be resurrected from this state by Authors or EIP Editors through moving it back to Draft.
Withdrawn - The EIP Author(s) have withdrawn the proposed EIP. This state has finality and can no longer be resurrected using this EIP number. If the idea is pursued at later date it is considered a new proposal.
Living - A special status for EIPs that are designed to be continually updated and not reach a state of finality. This includes most notably EIP-1.

EIP Types

EIPs are separated into a number of types, and each has its own list of EIPs.

Standard Track ({{site.pages|where:"type","Standards Track"|size}})

Describes any change that affects most or all Ethereum implementations, such as a change to the network protocol, a change in block or transaction validity rules, proposed application standards/conventions, or any change or addition that affects the interoperability of applications using Ethereum. Furthermore Standard EIPs can be broken down into the following categories.

Core ({{site.pages|where:"type","Standards Track"|where:"category","Core"|size}})

Improvements requiring a consensus fork (e.g. EIP-5, EIP-211), as well as changes that are not necessarily consensus critical but may be relevant to “core dev” discussions (for example, the PoA algorithm for testnets described in EIP-225).

Networking ({{site.pages|where:"type","Standards Track"|where:"category","Networking"|size}})

Includes improvements around devp2p (EIP-8) and Light Ethereum Subprotocol, as well as proposed improvements to network protocol specifications of whisper and swarm.

Interface ({{site.pages|where:"type","Standards Track"|where:"category","Interface"|size}})

Includes improvements around client API/RPC specifications and standards, and also certain language-level standards like method names (EIP-6) and contract ABIs. The label “interface” aligns with the interfaces repo and discussion should primarily occur in that repository before an EIP is submitted to the EIPs repository.

ERC ({{site.pages|where:"type","Standards Track"|where:"category","ERC"|size}})

Application-level standards and conventions, including contract standards such as token standards (EIP-20), name registries (EIP-137), URI schemes (EIP-681), library/package formats (EIP-190), and account abstraction (EIP-4337).

Meta ({{site.pages|where:"type","Meta"|size}})

Describes a process surrounding Ethereum or proposes a change to (or an event in) a process. Process EIPs are like Standards Track EIPs but apply to areas other than the Ethereum protocol itself. They may propose an implementation, but not to Ethereum's codebase; they often require community consensus; unlike Informational EIPs, they are more than recommendations, and users are typically not free to ignore them. Examples include procedures, guidelines, changes to the decision-making process, and changes to the tools or environment used in Ethereum development. Any meta-EIP is also considered a Process EIP.

Informational ({{site.pages|where:"type","Informational"|size}})

Describes a Ethereum design issue, or provides general guidelines or information to the Ethereum community, but does not propose a new feature. Informational EIPs do not necessarily represent Ethereum community consensus or a recommendation, so users and implementers are free to ignore Informational EIPs or follow their advice.

Informational

{% assign eips=site.pages|where:"type","Informational" %} {% include eiptable.html eips=eips %}

Interface

{% assign eips=site.pages|where:"type","Standards Track"|where:"category","Interface" %} {% include eiptable.html eips=eips %}

Ethereum EIPs - Last Call Review All EIPs which are in the two-week "last call" status, please help review these and provide your feedback! {{ site.url }} {{ site.time | date_to_rfc822 }} {% assign eips = site.pages | sort: 'eip' %} {% for eip in eips %} {% if eip.status == "Last Call" %} {% capture description %}

{% if eip.discussions-to %}

The author has requested that discussions happen at the following URL: {{ eip.discussions-to }}

{% endif %}

Networking

{% assign eips=site.pages|where:"type","Standards Track"|where:"category","Networking" %} {% include eiptable.html eips=eips %}

Ethereum EIPs - Last Call Review All EIPs which are in the two-week "last call" status, please help review these and provide your feedback! {{ site.url }} {{ site.time | date_to_rfc822 }} {% assign eips = site.pages | sort: 'eip' %} {% for eip in eips %} {% unless eip.category == "ERC" %} {% if eip.status == "Last Call" %} {% capture description %}

{% if eip.discussions-to %}

The author has requested that discussions happen at the following URL: {{ eip.discussions-to }}

{% endif %}

Ethereum EIPs All EIPs that are not ERCs {{ site.url }} {{ site.time | date_to_rfc822 }} {% assign eips = site.pages | sort: 'eip' %} {% for eip in eips %} {% unless eip.category == "ERC" %} {% if eip.status == "Last Call" %} {% capture description %}

{% if eip.discussions-to %}

The author has requested that discussions happen at the following URL: {{ eip.discussions-to }}

{% endif %}

$content-width: 1152px; @import 'minima'; .site-header { .wrapper { display: flex; flex-direction: column; align-items: center; } } .page-content { a.anchor-link { width: 16px; height: 16px; display: inline-block; margin-left: -22px; &:hover { background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' class='anchor-link-icon' viewBox='0 0 16 16' version='1.1' width='16' height='16' aria-hidden='true'%3E%3Cpath fill-rule='evenodd' d='M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z'%3E%3C/path%3E%3C/svg%3E"); } } } .footer-col-wrapper { color: #111; } .table-borderless, .table-borderless * { border-style : hidden !important; // !important To override Jekyll styling background-color: rgba(0,0,0,0) !important; } table.preamble > tbody > tr > :not(:first-child) { width: 100%; } table.preamble > tbody > tr > :first-child { white-space: nowrap; } a, a:link { color: #726E97; text-decoration: none; } a:visited { color: #8E6680; } a:hover, a:active { color: #7F557D; text-decoration: underline; } .site-footer, .site-footer * { box-sizing: content-box !important; // !important To override bootstrap styling } .no-underline { text-decoration: none !important; // !important To override previous styling } .badge:hover { filter: brightness(75%); transition: all 0.25s ease; } h1 { vertical-align: middle; } h1 a { height: 1em; display: inline-block; vertical-align: baseline; } .inline-svg { display: inline-block; vertical-align: bottom; fill: currentColor; width: 1.5ex; height: 100%; object-fit: cover; } @media print { header, footer { display: none; } } // This will make ALL tables scrollable .page-content table { display: inline-block; width: auto !important; /* shrink-to-fit its contents */ max-width: 100%; /* never exceed the width of its container */ overflow-x: auto; -webkit-overflow-scrolling: touch; } // Fix text overflow in EIP content .home { max-width: 100%; overflow-x: hidden; // Target all content that could overflow p, li, td, div { word-wrap: break-word; overflow-wrap: break-word; word-break: break-word; } // Specifically handle URLs in links a { word-wrap: break-word; overflow-wrap: break-word; word-break: break-all; display: inline-block; max-width: 100%; } // Handle code blocks that might contain long strings pre { overflow-x: auto; max-width: 100%; } // Inline code should wrap code { word-wrap: break-word; overflow-wrap: break-word; } } // Specifically target lists (where references usually are) .home ul, .home ol { max-width: 100%; padding-right: 20px; // Give some breathing room li { word-wrap: break-word; overflow-wrap: break-word; word-break: break-word; // Extra aggressive breaking for URLs a { word-break: break-all; hyphens: auto; } } } // makes an exception to code inside tables allowing them to expand the table's width since it has overflow scrolling .page-content table code { white-space: nowrap; word-break: normal; overflow-wrap: normal; }

@import "minima";

Contributors

## Contributors * Andrew Redden (@androolloyd) * Patrick Gallagher (@pi0neerpat) * Leo Alt (@leonardoalt) * Santiago Palladino (@spalladino) * William Entriken (@fulldecent) * Gonçalo Sá (@GNSPS) * Brian Burns (@Droopy78) * Ramesh Nair(@hiddentao) * Jules Goddard (@JulesGoddard) * Micah Zoltu (@MicahZoltu) * Sam Wilson (@SamWilsn) * William Morriss (@wjmelements) * Zachary (@Remscar) * Patrick Collins (@PatrickAlphaC) * Hadrien Croubois (@Amxx) * (@farreldarian) * Kelvin Schoofs (@SchoofsKelvin) * (@0xpApaSmURf) * Nathan Sala (@nataouze) * Anders Torbjornsen (@anders-torbjornsen) * (@Pandapip1) * Xavier Iturralde (@xibot) * Coder Dan (@cinnabarhorse) * GldnXross (@gldnxross) * Christian Reitwiessner (@chriseth) * Timidan (@Timidan) * cyotee doge (@cyotee) * Glory Praise Emmanuel (@emmaglorypraise) * Ed Zynda (@ezynda3) * Arthur Nesbitt (@nesbitta) * Cliff Hall (@cliffhall) * Tyler Scott Ward (@tylerscottward) * Troy Murray (@DannyDesert) * Dan Finlay (@danfinlay) * Theodore Georgas (@tgeorgas) * Aditya Palepu (@apalepu23) * Ronan Sandford (@wighawag) * Markus Waas (@gorgos) * Blessing Emah (@BlessingEmah) * Andrew Edwards * Ashwin Yardi (@ashwinYardi) * Marco Castignoli (@marcocastignoli) * Blaine Bublitz (@phated) * Bearded * Nick Barry (@ItsNickBarry) * (@Vectorized) * Rachit Srivastava (@rachit2501) * Neeraj Kashyap (@zomglings) * Zac Denham (@zdenham) * JA (@ubinatus) * Carter Carlson (@cartercarlson) * James Sayer (@jamessayer98) * Arpit Temani (@temaniarpit27) * Parv Garg (@parv3213) * Publius (@publiuss) * Guy Hance (@guyhance) * Payn (@Ayuilos) * Luis Schliesske (@gitpusha) * Hilmar Orth (@hilmarx) * Matthieu Marie Joseph (@Gauddel) * David Uzochukwu (@davidpius95) * TJ VanSlooten (@tjvsx) * 0xFluffyBeard (@0xFluffyBeard) * Florian Pfeiffer (@FlorianPfeifferKanaloaNetwork) * Mick de Graaf(@MickdeGraaf) * Alessio Delmonti (@Alexintosh) * Neirenoir (@Neirenoir) * Evert Kors (@Evert0x) * Patrick Kim (@pakim249CAL) * Ersan YAKIT (@ersanyakit) * Matias Arazi (@MatiArazi) * Lucas Grasso Ramos (@LucasGrasso) * Nikolay Angelov (@NikolayAngelov) * John Reynolds (@gweiworld) * Viraz Malhotra (@viraj124) * Kemal Emre Ballı (@emrbli) * Zack Peng (@zackpeng)

Metadata standards

# Metadata standards This documentation consists of various JSON schemas (examples or standards) that can be referenced by the reader of this EIP for implementing EIP-3475 bonds storage. ## 1. Description metadata: ```json [ { "title": "defining the title information", "_type": "explaining the type of the title information added", "description": "little description about the information stored in the bond", } ] ``` Example: adding details in bonds describing the local jurisdiction of the bonds where it's issued: ```json { "title": "localisation", "_type": "string", "description": "jurisdiction law codes compatibility" "values": ["fr ", "de", "ch"] } ``` The 'values' field defined above can also be ISO codes or other hex standard representation. ## 2. Nonce metadata: - **Information defining the state of the bond** ```json [ { "title": "maturity", "_type": "uint", "description": "Lorem ipsum...", "values": [0, 0, 0] } ] ``` ## 3. Class metadata: ```json [ { "title": "symbol", "_type": "string", "description": "Lorem ipsum...", "values": ["Class symbol 1", "Class symbol 2", "Class symbol 3"], }, { "title": "issuer", "_type": "string", "description": "Lorem ipsum...", "values": ["Issuer name 1", "Issuer name 2", "Issuer name 3"], }, { "title": "issuer_address", "_type": "address", "description": "Lorem ipsum...", "values":["Address 1.", "Address 2", "Address 3"] }, { "title": "class_type", "_type": "string", "description": "Lorem ipsum...", "values": ["Class Type 1", "Class Type 2", "Class Type 3"] }, { "title": "token_address", "_type": "address", "description": "Lorem ipsum...", "values":["Address 1.", "Address 2", "Address 3"] }, { "title": "period", "_type": "uint", "description": "Lorem ipsum...", "values": [0, 0, 0] } ] ``` ## Examples of other standards: - ISO-20022 standard is the recently adopted standard by banks for communicating financial operators (Banks, trading intermediaries, underwriters) that also include bond operations.

Bundler Full Sequence Diagram

# Bundler Full Sequence Diagram ```plantuml title UserOperations mempool flow actor Alice actor Bob participant "Bundler RPC" participant "Ethereum RPC" participant "UserOp Mempool" group Alice Submits UserOp note right of Alice: create UserOp Alice->"Bundler RPC": ""eth_sendUserOperation"" "Bundler RPC"->"Ethereum RPC": First Validation\ntrace view call to:\n""handleOps([userOpA]"") "Bundler RPC"->"UserOp Mempool": add ""UserOp"" to mempool end ||| group Bob Submits UserOp note right of Bob: create UserOp Bob->"Bundler RPC": ""eth_sendUserOperation"" "Bundler RPC"->"Ethereum RPC": First Validation\ntrace view call to\n""handleOps([userOpB]"") "Bundler RPC"->"UserOp Mempool": add ""UserOp"" to mempool end ||| group Build Bundle "Bundler RPC"->"UserOp Mempool": fetch pending ""UserOps"" return ""[UserOpA, UserOpB]"" ||| loop for each UserOp "Bundler RPC"->"Ethereum RPC": Second Validation\ntrace view call to:\n""handleOps([userOp])"" ||| end note right of "Bundler RPC": create bundle ""[UserOpA, UserOpB]"" "Bundler RPC"->"Ethereum RPC": Third Validation\ntrace view call to:\n""handleOps([UserOpA, UserOpB])"" ||| "Bundler RPC"->"Ethereum RPC": submit transaction\n""handleOps([UserOpA, UserOpB])"" ||| end ``` # Bundle Sequence Diagram (Without factory) ```plantuml @startuml autonumber participant "EntryPoint" as ep participant "Account A" as account participant "Account B" as account2 [->ep++ #gold: ""handleOps(userOps[])"": group Validations ||| ep->account++ #blue: ""validateUserOp"" return ""deposit"" ||| ep->ep: deduct ""Account_A"" deposit ||| ep->account2++ #green: ""validateUserOp"" return ""deposit"" ||| ep->ep: deduct ""Account_B"" deposit ||| end group Executions ||| ep->account++ #blue: ""executeUserOp"" deactivate account ep->ep: refund ""Account_A"" ||| ep->account2++ #green: ""executeUserOp"" deactivate account2 ep->ep: refund ""Account_B"" ||| end ep-->[: ""compensate(beneficiary)"" hide footbox ``` # Bundle Sequence Diagram (with Paymaster) ```plantuml @startuml autonumber participant "EntryPoint" as ep participant "Account" as account participant "Paymaster" as pm [->ep++ #gold: ""handleOps(userOps[])"": group Validation ||| ep->account++ #blue: ""validateUserOp"" deactivate account ep->pm++ #gray: ""validatePaymasterUserOp"" deactivate pm ep->ep: deduct ""Paymaster"" deposit ||| end group Execution ||| ep->account++ #blue: ""executeUserOp"" deactivate account ep->pm++ #gray: ""postOp"" deactivate pm ep->ep: refund paymaster ||| end ep-->[: ""compensate(beneficiary)"" hide footbox ``` # Bundle Sequence Diagram (with Factory) ```plantuml @startuml autonumber participant "EntryPoint" as ep participant "Factory" as fact participant "Account" as account participant "Account2" as account2 [->ep++ #gold: handleOps(userOps[]): group Validations ep->fact++ #gray: create (initCode) fact->o account: create return account ep->account++ #blue: validateUserOp return deposit ep->ep: deduct account deposit ep->account2++ #green: validateUserOp return deposit ep->ep: deduct account2 deposit end group Executions ep->account++ #blue: exec deactivate account ep->ep: refund account1 ep->account2++ #green: exec deactivate account2 ep->ep: refund account2 end ep-->[: compensate(beneficiary) hide footbox ```

SemVer Authors

SemVer Authors ============== The following people have modified the Semantic Versioning 2.0.0 specification: - Tom Preston-Werner - Phil Haack - Haacked - isaacs - Thijs Schreijer - jeffhandley - Alexandr Tovmach - Adam Ralph - Eddie Garmon - Jeff Handley - Krzysztof Piasecki - Doug Beck - Gert de Pagter - Guillermo Calvo - Iulian Onofrei - Ivan Bessarabov - Jo Liss - Johanan Liebermann - Joseph Donahue - Konstantin - Kristian Glass - Mark Amery - OGINO Masanori - Oguz Bilgic - Slipp Douglas - Thomas Schraitle - Tim Vergenz - Todd Reed - Tristram Oaten - Wincent Colaiuta - alexandrtovmach - wolf99

Semantic Versioning 2.0.0

Semantic Versioning 2.0.0 ============================== Summary ------- Given a version number MAJOR.MINOR.PATCH, increment the: 1. MAJOR version when you make incompatible API changes, 1. MINOR version when you add functionality in a backwards compatible manner, and 1. PATCH version when you make backwards compatible bug fixes. Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. Introduction ------------ In the world of software management there exists a dreaded place called "dependency hell." The bigger your system grows and the more packages you integrate into your software, the more likely you are to find yourself, one day, in this pit of despair. In systems with many dependencies, releasing new package versions can quickly become a nightmare. If the dependency specifications are too tight, you are in danger of version lock (the inability to upgrade a package without having to release new versions of every dependent package). If dependencies are specified too loosely, you will inevitably be bitten by version promiscuity (assuming compatibility with more future versions than is reasonable). Dependency hell is where you are when version lock and/or version promiscuity prevent you from easily and safely moving your project forward. As a solution to this problem, we propose a simple set of rules and requirements that dictate how version numbers are assigned and incremented. These rules are based on but not necessarily limited to pre-existing widespread common practices in use in both closed and open-source software. For this system to work, you first need to declare a public API. This may consist of documentation or be enforced by the code itself. Regardless, it is important that this API be clear and precise. Once you identify your public API, you communicate changes to it with specific increments to your version number. Consider a version format of X.Y.Z (Major.Minor.Patch). Bug fixes not affecting the API increment the patch version, backwards compatible API additions/changes increment the minor version, and backwards incompatible API changes increment the major version. We call this system "Semantic Versioning." Under this scheme, version numbers and the way they change convey meaning about the underlying code and what has been modified from one version to the next. Semantic Versioning Specification (SemVer) ------------------------------------------ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). 1. Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it SHOULD be precise and comprehensive. 1. A normal version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers, and MUST NOT contain leading zeroes. X is the major version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically. For instance: 1.9.0 -> 1.10.0 -> 1.11.0. 1. Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. 1. Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable. 1. Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes. 1. Patch version Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior. 1. Minor version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated. It MAY be incremented if substantial new functionality or improvements are introduced within the private code. It MAY include patch level changes. Patch version MUST be reset to 0 when minor version is incremented. 1. Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API. It MAY also include minor and patch level changes. Patch and minor versions MUST be reset to 0 when major version is incremented. 1. A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.--. 1. Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3----117B344092BD. 1. Precedence refers to how versions are compared to each other when ordered. 1. Precedence MUST be calculated by separating the version into major, minor, patch and pre-release identifiers in that order (Build metadata does not figure into precedence). 1. Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Major, minor, and patch versions are always compared numerically. Example: 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1. 1. When major, minor, and patch are equal, a pre-release version has lower precedence than a normal version: Example: 1.0.0-alpha < 1.0.0. 1. Precedence for two pre-release versions with the same major, minor, and patch version MUST be determined by comparing each dot separated identifier from left to right until a difference is found as follows: 1. Identifiers consisting of only digits are compared numerically. 1. Identifiers with letters or hyphens are compared lexically in ASCII sort order. 1. Numeric identifiers always have lower precedence than non-numeric identifiers. 1. A larger set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal. Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0. Backus–Naur Form Grammar for Valid SemVer Versions -------------------------------------------------- ``` ::= | "-" | "+" | "-" "+" ::= "." "." ::= ::= ::=

::= "0" | | ::= | ::= |

MIT License Copyright (c) 2023 Authentic Vision GmbH Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Appendix: Interoperability Analysis

## Appendix: Interoperability Analysis We provide a cherrypicked list of possible points of contact between ERC-7208 and other tokenization standards and proposals. **ERC-1400 (Security Token Standard)**: This ERC provides a suite of standard interfaces for issuing/redeeming security tokens, managing their ownership and transfer restrictions, and providing transparency to token holders on how different subsets of their token balance behave with respect to transfer restrictions, rights and obligations. ERC-7208 can enhance ERC-1400 by offering a dynamic and flexible data management architecture. **Data Objects** enable the storage and modification of on-chain data for security tokens, such as compliance information or ownership details. Assets already issued under ERC-1400 can be wrapped into a **Vault Data Object** and exposed through any **Data Manager** interface (including **ERC-3643**). Additionally, ERC-7208 enablesthe fractionalization of ERC-1400 assets. If the asset is issued through an ERC-1400 **Data Manager** with native **Data Object** storage, the integration could lead to more versatile and transparent security token offerings, as a custom Identity Management logic can be embedded within the assets. **EIP-2981 (Royalties)**: ERC-7208 can complement EIP-2981 as a **Data Manager** by providing a flexible way to handle royalties. **Data Objects** can store and manage the low-level storage of royalty information dynamically, independently from the interface used by the end user. This enables a complex royalty structure that can change over time or respond to predefined conditions, like embedding compliance checks and simultaneously exposing multiple interfaces for fractional ownership of the underlying asset. For instance, by leveraging ERC-7208, an individual royalty-based NFT can be traded in a compliant manner, concurrently under both an ERC-721 interface as well as an ERC-20 through the use of **Data Managers** that delegate their internal storage onto the **Data Object**. **ERC-3643 (Security Tokens)**: ERC-3643 defines a *Security Token interface for Regulated Exchanges* based on ERC-20 token standard. The ERC-7208 can be used for wrapping many tokens (irrespective of their ERC) and adapting their logic to the ERC-3643. Additionally, a **Data Object** storing native ERC-3643 asset data can be used for improving the compliance logic and enabling the trading of underlying securities simultaneously through multiple interfaces that respond to different regulatory frameworks. Moreover, the separation of the storage enables the logic to implement functionalities that were not initially a part of the original ERC-3643, such as identity-based recovery of assets, role-based access control, the introduction of cross-chain support, etc. **ERC-4337 (Account Abstraction)**: ERC-7208 can provide a standardized method to store and manage the complex data structures required by abstracted accounts. This can include user preferences, access control lists, recovery options, and other customizable account features. The mutable states of abstracted accounts can be efficiently handled using **Data Objects**. This, in turn, improves the adaptability and security of abstracted accounts. Additionally, an ERC-7208 implementation supporting meta-transactions and **Data Points** separated by chain-id can be developed to fully abstract account management across blockchains. **EIP-4626 (Tokenized Vaults)**: Tokenized Vaults inherit from a single ERC-20 and ERC-2612 for approvals via EIP-712 secp256k1 signatures. ERC-7208 can enhance EIP-4626 by providing a more dynamic data layer for tokenized vaults. **Data Objects** store information about the assets in the vault, conditions for access, or other relevant data, enabling more nuanced interactions with tokenized vaults. Additionally, the **Data Point** can store more than a single ERC-20, greatly increasing the capabilities of Tokenized Vaults. **ERC-4907 (Shared Ownership)**: The integration of ERC-4907 as a **Data Manager** with ERC-7208 **Data Point** storage can enhance the rental experience by allowing for additional rental-related data directly on-chain, such as rental terms, user permissions, and other customizable settings which would be self-contained within **Data Points** and therefore automatically updated as metadata. ERC-4907's rental mechanism complements ERC-7208's ability to manage mutable on-chain data. By combining these two, NFTs can not only be rented out for specific periods but also have their traits or states dynamically managed and updated during the rental period. This combination enhances security and compliance in NFT transactions, particularly for *Real World Asset Tokenization*. Rental agreements, regulatory compliance, intellectual property, and user rights can be embedded within Data Objects to ensure that the NFT usage adheres to predefined rules. **ERC-7540 (Asynchronous ERC-4626 Tokenized Vaults)**: ERC-7540 vaults's are focused on asynchronous deposit and redemption. Integrating ERC-7540, either by Wrapping into a **Data Object** or by exposing an ERC-7208 **Data Manager**, will facilitate more complex financial products. DeFi products like undercollateralized loans, insurance products, or tokenized stocks often require operations to be handled in a non-instantaneous manner. However, the nature of these products requires adhering to regulatory compliance and identity management solutions. This can easily be achieved by implementing the use of on-chain adapters that enhance the logic while keeping the data secure.

```mermaid flowchart LR redeemer(["redeemer"]) --"redeemDelegations"--> Delegation_Manager(["Delegation Manager"]) Delegation_Manager -.->|validate delegation w/ Action| Delegation_Manager Delegation_Manager --"execute delegated action"--> Delegator(["Delegator"]) Delegator --"executes CALL using Action"--> Target(["Target"]) classDef action stroke:#333,stroke-width:2px,stroke-dasharray: 5, 5; classDef entity fill:#af,stroke:#333,stroke-width:2px; class redeemer,Delegator,Delegation_Manager,Target entity; ```

ERC-7738 Script Registry Contracts, deployment and test harness scripts

# ERC-7738 Script Registry Contracts, deployment and test harness scripts This folder contains sample (and actual deployed) ERC-7738 registry contracts and tapp scripts ## Test suite - Init hardhat in this directory ```bash npm install --save-dev hardhat ``` - Run the test harness ```bash npx hardhat test ``` # Test a script on the registry ## Deploy Example Token Deploy a test token, let's use a simple ERC-721 with a custom mint function: ```Solidity // SPDX-License-Identifier: MIT // Compatible with OpenZeppelin Contracts ^5.0.0 pragma solidity ^0.8.20; import "@openzeppelin/contracts/token/ERC721/ERC721.sol"; import "@openzeppelin/contracts/access/Ownable.sol"; contract MyToken is ERC721, Ownable { uint256 private _tokenId; constructor() ERC721("MyToken", "MTK") Ownable(msg.sender) { _tokenId = 1; } function mint() public { _safeMint(msg.sender, _tokenId); _tokenId++; } } ``` Deploy this NFT using eg Remix and make a note of the contract address. ## Create Simple TokenScript, emulate and Deploy First install the TokenScript CLI tool 1. Install the TokenScript build tool (see [TokenScript Quickstart](https://launchpad-doc.vercel.app/quick-start/tokenscript-cli/quick-start-tokenscript-cli)) ```bash npm install -g @tokenscript/cli ``` Here is a minimal example minting tokenscript object file: [Basic NFT TokenScript](/assets/erc-7738/tokenscript/examples/tokenscript.xml). 2. Copy or clone this code to a directory, ensure it is called tokenscript.xml. 3. Locate the following line in the TokenScript: ```xml CONTRACT_ADDRESS ``` Replace the ChainId and CONTRACT_ADDRESS with the contract you deployed in the previous step. 4. Use Emulation to test (in the same directory as you put the examples/tokenscript.xml file): ```bash tokenscript emulate ``` This will let you test the TokenScript functionality before deploying on the registry. The generated page will allow you to mint new tokens. 5. Upload the TokenScript to an FTP or IPFS and make a note of the URL or IPFS hash. ## Add script to the registry 1. Open the registry page: [Holesky Registry Page](https://viewer-staging.tokenscript.org/?chain=17000&contract=0x0077380bCDb2717C9640e892B9d5Ee02Bb5e0682&scriptId=7738_2) [Sepolia Registry Page](https://viewer-staging.tokenscript.org/?chain=11155111&contract=0x0077380bCDb2717C9640e892B9d5Ee02Bb5e0682&scriptId=7738_1) [Base Sepolia Registry Page](https://viewer-staging.tokenscript.org/?chain=84532&contract=0x0077380bCDb2717C9640e892B9d5Ee02Bb5e0682&scriptId=7738_2) Click on the onboarding button "Set ScriptURI". Set the contract address and scriptURI in the card. 2. Test onboarding. Switch wallets, go to the token page of your token (eg for Holesky): `https://viewer-staging.tokenscript.org/?chain=17000&contract=` This will open the TokenScript for your deployed contract. Click on the Mint onboarding button to generate new Tokens. ## Deploy your own registry on a testnet For this test we will use Holesky, but you can also use Sepolia, or any testnet on which the ENS contracts has been deployed. Add some test eth on 2 wallets (0.1 -> 0.5 depending on gas price on the testnet) Create a .env file which contains the following three keys: ``` PRIVATE_KEY_DEPLOY = "0x" PRIVATE_KEY_2DEPLOY = "0x" PRIVATE_KEY_ENS = "0x" ``` Create an ENS domain on Holesky using the PRIVATE_KEY_ENS wallet. Obtain a `.eth` domain, not `.box` or any other. Go to the ENS app https://app.ens.domains/ and obtain a new ENS using your Holesky. Using the app, unwrap the domain. Click on "More" then "Unwrap". Now, use the script to transfer ownership of the ENS to where the ENSAssigner contract will be written: 1. Add the ENS name to your .env file (don't add the .eth suffix). ``` ENS_NAME="" ``` eg, if the domain you picked was "kilkennycat.eth": ``` ENS_NAME="kilkennycat" ``` 2. Run the script (note this script changes ownership of the domain to the ENSAssigner contract that will soon be deployed) ```bash npx hardhat run ./scripts/changeENSOwner.ts --network holesky ``` Now, ensure the change ownership transaction is written (check the console log of first deployment), and run the deploy script: ```bash npx hardhat run ./scripts/deploy.ts --network holesky ``` Congrats your registry is deployed. Now to issue a bootstrap script for the registry. ## Generate TokenScript and upload to IPFS 1. Open the `./tokenscript` folder in your favourite editor, and find the `tokenscript.xml` file. 2. Locate the Origin contract definition line: ```xml ``` 3. Edit the contract network and address on the line below this. 4. Build the TokenScript object file (use commandline from the ./) ```bash tokenscript build ``` 5. Upload the `tokenscript.tsml` file in the `./tokenscript/out` directory to IPFS, or your publicly accessible FTP. ## Set the TokenScript entry on the Script Registry Set the tokenscript for your registry via a script entry on the registry contract itself, using the script itself. This is akin to 'bootstrapping' your registry. You could just as easily accomplish this by using an `ethers.js` script or verifying the contract on `https://etherscan.io` and then using etherscan's write menu. use the tokenscript CLI `emulate` feature: ```bash tokenscript emulate ``` This will automatically open an emulator browser page. Connect your Ethereum wallet which is holding the key you used to deploy the registry contract. Now use the 'Onboarding card' which is defined in the TokenScript xml - click the `Set ScriptURI` button. This will open the card defined in `./onboard.html`. This card invites you to set the contract address - which in this case is your registry contract - and the URI of the Tokenscript TSML you uploaded in step 5. (eg `ipfs://QmRaVBN4NBevk1j4HHfCLrMjjLrYNnsnJS2caJs9smYAtq`). Once you click on the `Set Script URI` button your wallet will ask permission to call the `setScriptURI(address contractAddress, string[] uri)` function. ## Test your registry 1. switch to a new directory and clone the tokenscript viewer repo: ```bash git clone https://github.com/SmartTokenLabs/tokenscript-engine.git ``` ```bash cd ./tokenscript-engine/javascript/tokenscript-viewer ``` 2. update the registry contract address: open `javascript/engine-js/src/repo/sources/RegistryScriptURI.ts` and change `const REGISTRY_7738` to your deployed registry address. 3. Add your Infura API key to the .env (you will have to create the .env file): ``` INFURA_API_KEY=1234567890ABCDEF1234567890ABCDEF ``` 4. Install dependencies and run ```bash npm i ``` ```bash npm run start ``` 4. On the opened webpage, open your deployed registry script: `http://localhost:3333/?chain=17000&contract=` 5. Set the ScriptURI for the NFT contract you deployed in the first step, by clicking the "Set ScriptURI" button from your deployed tokenscript. Set the NFT contract address and URI path you uploaded to. 6. (Optional) Set a name and icon for the registry script, by clicking on the 'Set Name' and 'Set Icon' buttons on the token that is now displayed. 7. Use the script served from your new registry: `http://localhost:3333/?chain=17000&contract=`

EIP-3525

# EIP-3525 ## Demonstration only The code included in this directory is ONLY for the purpose of demonstrating how to implement this proposal, it is not a full-featured implementation ready for production. So please DO NOT use the code here for purposes other than study.

# ERC721 Consumable Extension [![License: CC0-1.0](https://img.shields.io/badge/License-CC0-yellow.svg)](https://creativecommons.org/publicdomain/zero/1.0/)

This project provides a reference implementation of the proposed `ERC721Consumer` OPTIONAL extension. ## Install In order to install the required dependencies you need to execute: ```shell npm install ``` ## Compile In order to compile the solidity contracts you need to execute: ```shell npx hardhat compile ``` ## Tests ```shell npx hardhat test ```

#EIP4519 Proof of Concept - Firmware This firmware is designed for a device using an ESP32 as a smart asset associated with an EIP4519 SmartNFT. The device has two operation modes: registration mode and application mode. ##Registration mode In this mode, the device generates 51 bytes with the TRNG of the ESP32 core. Those bytes are used for the initial values of a CTR-DRBG PRNG to generate the private key of the Ethereum account. Only the address of this account is shared. The UART port is needed for communications with this device. The commands in this mode are: >‘0’ – Check if the device is ready. >‘1’ – Share the address of the account. >‘2’ – Save the initial values of CTR-DRBG PRNG in an EEPROM and changes the operation mode. ##Application Mode The device reads the EEPROM to obtain the initial values of the CTR-DRBG PRNG and recover the Ethereum account. The device connects to a WiFi station. With Infura, the device checks the state of its associated SmartNFT registered on an EIP4519 Smart Contract and also checks if the device must be engaged with the owner or the user. The UART port is needed for communications with this device. The commands in this mode are: >'Z'+OWNER/USER_ADDRESS – The device checks if the address must be authenticated and generates a nonce. >'Y'+SIGN_D+'#'+NONCE_D – The device checks the signature, signs NONCE_D, and sends the signature. >'Y'+SIGNED_PK+'#'+PK – The device checks the signature, generates the shared key, and sends the transaction to the EIP4519 Smart Contract. >'C' – The EEPROM is cleared, only for debug process. >'R' – The device is restarted to refresh the SmartNFT state, only for debug process.

Proof of concept of an implementation of an Smart Non Fungible Token

# Proof of concept of an implementation of an Smart Non Fungible Token This proof of concept is launch in the Ethereum Kovan Testnet with the address 0x7eB5A03E7ED70ABf70fee48965D0411d37F335aC. Use the proposal Non Fungible Token binding assets with SmartNFT and define the user management of the assets.

Multi-Fractional Non-Fungible Token

# Multi-Fractional Non-Fungible Token Solidity Implementation of Multi-Fractional Non-Fungible Token. ## Problem Trying to solve Before, ERC20 Token contract should be deployed every time when fractionalizing a specific NFT. To solve this problem, this standard proposes a token standard to cover multiple fractionalized nft in a contract without having to deploy each time. Issue : https://github.com/ethereum/EIPs/issues/4674 PR : https://github.com/ethereum/EIPs/pull/4675 ## How to use ``` contracts/ helper/ interface/ math/ MFNFT.sol NFT.sol ERC20Token.sol ``` ### Contracts ``MFNFT.sol`` : Multi-Fractional Non-Fungible Token Contract ``NFT.sol`` : Non-Fungible Token Contract ``ERC20Token.sol`` : Sample ERC-20 Token Contract ``helper/Verifier.sol`` : Contract that verifies the ownership of NFT before fractionalization ``math/SafeMath.sol`` : Openzeppelin SafeMath Library ``interface/IERC20.sol`` : ERC-20 Token Interface ``interface/IERC721.sol`` : ERC-721 Token Interface ``interface/IMFNFT`` : MFNFT Token Interface ### Install & Test Installation ``` npm install ``` Test ``` npx hardhat test ``` Coverage ``` npx hardhat coverage ```

EIP-4907

# EIP-4907 EIP-4907 is an extension of ERC-721. It proposes an additional role **user** and a valid duration indicator **expires**. It allows users and developers manage the use right more simple and efficient. ### Tools * [Visual Studio Code](https://code.visualstudio.com/) * [Solidity](https://marketplace.visualstudio.com/items?itemName=JuanBlanco.solidity) - Solidity support for Visual Studio code * [Truffle](https://truffleframework.com/) - the most popular development framework for Ethereum ### Install ``` npm install ``` ### Test ``` truffle test ``` ### Additional Resources * [Official Truffle Documentation](http://truffleframework.com/docs/) for complete and detailed guides, tips, and sample code.

EIP-5007

# EIP-5007 This standard is an extension of [ERC-721](../../EIPS/eip-721.md). It proposes some additional functions (`startTime`, `endTime`) to help with on-chain time management. ## Tools * [Truffle](https://truffleframework.com/) - a development framework for Ethereum ## Install ``` npm install truffle -g npm install ``` ## Test ``` truffle test ```

EIP-5218 Reference Implementations

# EIP-5218 Reference Implementations This is the source code for a reference implementation of EIP-5218. ## Build and Test The repo expects a Foundry build system, optionally using visual studio code for editing. You can run the test suite with: ```bash forge test -vvvvv ```

EIP 5252 implementation

# EIP 5252 implementation This project is a reference implementation of EIP-5252. Try running some of the following tasks: ```shell npx hardhat help npx hardhat test GAS_REPORT=true npx hardhat test npx hardhat node npx hardhat run scripts/deploy.ts ```

EIP-5725: Transferrable Vesting NFT - Reference Implementation

# EIP-5725: Transferrable Vesting NFT - Reference Implementation This repository serves as a reference implementation for **EIP-5725 Transferrable Vesting NFT Standard**. A Non-Fungible Token (NFT) standard used to vest ERC-20 tokens over a vesting release curve. ## Contents - [EIP-5725 Specification](/assets/erc-5725/contracts/IERC5725.sol): Interface and definitions for the EIP-5725 specification. - [ERC-5725 Implementation (abstract)](/assets/erc-5725/contracts/ERC5725.sol): ERC-5725 contract which can be extended to implement the specification. - [VestingNFT Implementation](/assets/erc-5725/contracts/reference/LinearVestingNFT.sol): Full ERC-5725 implementation using cliff vesting curve. - [LinearVestingNFT Implementation](/assets/erc-5725/contracts/reference/VestingNFT.sol): Full ERC-5725 implementation using linear vesting curve.

SDC Solidity implementation

# SDC Solidity implementation ## Description The reference SDC implementation can be unit tested with Hardhat to understand the trade process logic. ### Compile and run tests with Hardhat We provide the essential steps to compile the contracts and run the provided unit tests. ### Provided Contracts and Tests #### Interfaces - `contracts/ISDC.sol` - Interface contract (aggregation of `ISDCTrade`, `ISDCSettlement`, `IAsyncTransferCallback`) - `contracts/ISDCTrade.sol` - Interface related to trade incept/confirm/terminate - `contracts/ISDCSettlement.sol` - Interface related to settlement initiate/perform/after - `contracts/IAsyncTransferCallback.sol` - Interface related to transfer. - `contracts/IAsyncTransfer.sol` - Interface (extending the ERC-20) for settlement tokens used in `SDCPledgedBalance`. #### Implementations - `contracts/SDCSingleTrade.sol` - SDC abstract contract for an OTC Derivative (single trade case only) - `contracts/SDCSingleTradePledgedBalance.sol` - SDC full implementation for an OTC Derivative (single trade case only) - `contracts/ERC20Settlement.sol` - Mintable settlement token contract implementing `IERC20Settlement` for unit tests #### Tests - `test/SDCTests.js` - Unit tests for the life-cycle of the sdc implementation ### Compile and run tests with Hardhat Install dependencies: ```shell npm i ``` Compile: ```shell npx hardhat compile ``` Run all tests: ```shell npx hardhat test ``` ### Configuration files - `package.js` - Javascript package definition. - `hardhat.config.js` - Hardhat config. ### Used javascript-based testing libraries for solidity - `ethereum-waffle`: Waffle is a Solidity testing library. It allows you to write tests for your contracts with JavaScript. - `chai`: Chai is an assertion library and provides functions like expect. - `ethers`: This is a popular Ethereum client library. It allows you to interface with blockchains that implement the Ethereum API. - `solidity-coverage`: This library gives you coverage reports on unit tests with the help of Istanbul. ## Version history / release notes ### 0.8.0 - Re-introduced the method `afterSettlement` that can be used to check pre-conditions of the next settlement cycle, e.g., triggered by a time-oracle. - Added the event `SettlementAwaitingInitiation` which should be issued when the trade goes active and when `afterSettlement` veryfied that the trade is ready for the next settlement.

Example implementation of EIP-6358

# Example implementation of EIP-6358 ## Prerequisites - truffle >= v5.7.9 - node >= v18.12.1 - npm >= 8.19.2 - npx >= 8.19.2 ## Installation ``` npm install ``` Add the configuration file `truffle-config.js` into the directory `./`. The file `truffle-config.js` can be generated by executing the command in an $empty directory$: ``` npx truffle init ``` **Note that:** - type `N` when asked `Overwrite contracts?` - type `N` when asked `Overwrite migrations?` - type `N` when asked `Overwrite test?` After `truffle-config.js` is generated, then: - Uncommnet the content of `development`, like this: ``` development: { host: "127.0.0.1", // Localhost (default: none) port: 8545, // Standard Ethereum port (default: none) network_id: "*", // Any network (default: none) }, ``` ## Compilation ``` touch .secret npx truffle compile ``` ## Unit test ### Launch local testnet ``` npx ganache -s 0 ``` ### Test Open another terminate ``` npx truffle test ```

ERC-6604

ERC-6604 ======== * [`AbstractERC20.sol`](/assets/erc-6604/contracts/AbstractERC20.sol) * [`AbstractToken.sol`](/assets/erc-6604/contracts/AbstractToken.sol) * [`GenericEIP712.sol`](/assets/erc-6604/contracts/GenericEIP712.sol) * [`IAbstractToken.sol`](/assets/erc-6604/contracts/IAbstractToken.sol)

# ERC6786 Royalty Debt Registry

This project provides a reference implementation of the proposed `ERC-6786 Royalty Debt Registry`. ## Install In order to install the required dependencies you need to execute: ```shell npm install ``` ## Compile In order to compile the solidity contracts you need to execute: ```shell npx hardhat compile ``` ## Tests ```shell npx hardhat test ```

EIP-6808 implementation

# EIP-6808 implementation This project is a reference implementation of EIP-6808. Try running some of the following tasks: ```shell npm i truffle compile truffle test ```

EIP 6809 implementation

# EIP 6809 implementation This project is a reference implementation of EIP-6809. Try running some of the following tasks: ```shell npm i truffle compile truffle test ```

ERCxxxx Reference implementation

# ERCxxxx Reference implementation This reference implementation is [MIT](/assets/erc-6956/LICENSE) licensed and can therefore be freely used in any project. ## Getting started From this directory, run ``` npm install && npx hardhat test ```

EIP 6982 implementation

# EIP 6982 implementation As a reference implementation of EIP-6982 we use the Nduja Labs ERC721Lockable contract. To run the tests, run the following commands: ```shell npm i -g pnpm pnpm i pnpm test ```

ERC-7007 Reference Implementation

# ERC-7007 Reference Implementation This is a WIP implementation of ERC-7007 based on the discussions in the [EIP-7007 issue thread](https://github.com/ethereum/EIPs/issues/7007). ## Setup Run `npm install` in the root directory. ## Testing Try running some of the following tasks: ```shell npx hardhat help npx hardhat test REPORT_GAS=true npx hardhat test ``` ## Metadata Standard ```json { "title": "AIGC Metadata", "type": "object", "properties": { "name": { "type": "string", "description": "Identifies the asset to which this NFT represents" }, "description": { "type": "string", "description": "Describes the asset to which this NFT represents" }, "image": { "type": "string", "description": "A URI pointing to a resource with mime type image/* representing the asset to which this NFT represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive." }, "prompt": { "type": "string", "description": "Identifies the prompt from which this AIGC NFT generated" }, "seed": { "type": "uint256", "description": "Identifies the seed from which this AIGC NFT generated" }, "aigc_type": { "type": "string", "description": "image/video/audio..." }, "aigc_data": { "type": "string", "description": "A URI pointing to a resource with mime type image/* representing the asset to which this AIGC NFT represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive." } } } ```

Reference implementation of ERC-7208 and usage examples

PBM Solidity implementation

# PBM Solidity implementation ## Description We provide a list of sample PBM implementation for reference. ### Provided Contracts and Tests - `contracts/preloaded-pbm/XXXX.sol` - PBMRC1 implementation contract to demonstrate preloaded PBMs - `contracts/non-preloaded-pbm/XXXX.sol` - Interface contract - `contracts/XXXX.sol` - Interface contract - `contracts/ERC20.sol` - ERC20 token contract for unit tests - `test/XXXXX.js` - Unit tests for livecycle of the PBM implementation ### Used javascript based testing libraries for solidity - `hardhat`: hardhat allows for testing of contracts with JavaScript via Mocha as the test runner - `chai`: Chai is an assertion library and provides functions like expect. - `ethers`: This is a popular Ethereum client library. It allows you to interface with blockchains that implement the Ethereum API. ### Compile and run tests with hardhat We provide the essential steps to compile the contracts and run provided unit tests Check that you have the latest version of npm and node via `npm -version` and `node -v` (should be a LTS version for hardhat support) 1. Check out project 2. Go to folder and initialise a new npm project: `npm init -y`. A basic `package.json` file should occur 3. Install Hardhat as local solidity dev environment: `npx hardhat` 4. Select following option: Create an empty hardhat.config.js 5. Install Hardhat as a development dependency: `npm install --save-dev hardhat` 6. Install further testing dependencies: `npm install --save-dev @nomiclabs/hardhat-waffle @nomiclabs/hardhat-ethers ethereum-waffle chai ethers solidity-coverage` 7. Install open zeppelin contracts: `npm install @openzeppelin/contracts` 8. add plugins to hardhat.config.ts: ``` require("@nomiclabs/hardhat-waffle"); require('solidity-coverage'); ``` 9. Adding commands to `package.json`: ``` "scripts": { "build": "hardhat compile", "test:light": "hardhat test", "test": "hardhat coverage" }, ``` 9. run `npm run build` 10. run `npm run test`

Ethereum Entity Component System

# Ethereum Entity Component System World contracts are containers for entities, component contracts, and system contracts. Its core principle is to establish the relationship between entities and component contracts, and different entities will attach different components. And use the system contract to dynamically change the data of the entity in the component. Usual workflow when building ECS-based programs 1. Implement the `IWorld` interface to create a world contract. 2. Call `createEntity()` of the world contract to create an entity. 3. Implement the `IComponent` interface to create a Component contract. 4. Call `registerComponent()` of the world contract to register the component contract. 5. Call `addComponent()` of the world contract to attach the component to the entity. 6. Create a system contract, which is a contract without interface restrictions, and you can define any function in the system contract. 7. Call `registerSystem()` of the world contract to register the system contract. 8. Run the system. - [`System.sol`](/assets/erc-7509/System.sol) - [`Types.sol`](/assets/erc-7509/Types.sol) - [`World.sol`](/assets/erc-7509/World.sol) - [`Component.sol`](/assets/erc-7509/Component.sol)

DvP Solidity implementation

# DvP Solidity implementation ## Description The interfaces in this proposal model a functional transaction scheme to establish a secure *delivery-versus-payment* across two blockchains, where a) no intermediary is required and b) one of the two chains can securely interact with a stateless "decryption oracle". Here, *delivery-versus-payment* refers to the exchange of, e.g., an asset against a payment; however, the concept is generic to make a transfer of one token on one chain (e.g., the payment) conditional to the successful transfer of another token on another chain (e.g., the asset). The scheme is realized by two smart contracts, one on each chain. One smart contract implements the `ILockingContract` interface on one chain (e.g. the "asset chain"), and another smart contract implements the `IDecryptionContract` interface on the other chain (e.g., the "payment chain"). The smart contract implementing `ILockingContract` locks a token (e.g., the asset) on its chain until a key is presented to encrypt to one of two given values. The smart contract implementing `IDecryptionContract`, decrypts one of two keys (via the decryption oracle) conditional to the success or failure of the token transfer (e.g., the payment). A stateless decryption oracle is attached to the chain running `IDecryptionContract` for the decryption. ### Provided Contracts #### DvP - `contracts/ILockingContract.sol` - Contract locking transfer with given encrypted keys or hashes. - `contracts/IDecryptionContract.sol` - Contract performing conditional upon transfer decryption (possibly based on an external oracle). #### Decryption Oracle - `contracts/IKeyDecryptionOracle.sol` - Interface implemented by a decryption oracle proxy contract. - `contracts/IKeyDecryptionOracleCallback.sol` - Interface to be implemented by a callback receiving the decrypted key. ### Documentation - `doc/DvP-Seq-Diag.png` - Sequence diagram of the DvP - `doc/multi-party-dvp.svg` - Sequence diagram of a multi-party-dvp.

ERC7641: Intrinsic RevShare Token

# ERC7641: Intrinsic RevShare Token An ERC-20 extension that integrates a revenue-sharing mechanism, ensuring tokens intrinsically represent a share of a communal revenue pool

References for ERC-7746

# References for ERC-7746 In this directory you can find a reference implementation of the ILayer interface and a sample MockERC20 contract. In this test, a [Protected.sol](/assets/erc-7746/test/Protected.sol) contract is protected by a [RateLimitLayer.sol](/assets/erc-7746/test/RateLimitLayer.sol) layer. The RateLimitLayer implements the ILayer interface and enforces a rate which client has configured. The Drainer simulates a vulnerable contract that acts in a malicious way. In the `test.ts` The Drainer contract is trying to drain the funds from the Protected contract. It is assumed that Protected contract has bug that allows partial unauthorized access to the state. The RateLimitLayer is configured to allow only 10 transactions per block from same sender. The test checks that the Drainer contract is not able to drain the funds from the Protected contract.

ERC-7818

# ERC-7818 This is reference implementation of ERC-7818 ## Implementation Describe #### Sliding Window Algorithm to look for expiration balance This contract creates an abstract implementation that adopts the `Sliding Window Algorithm` to maintain a window over a period of time (block height). This efficient approach allows for the look back and calculation of `usable balances` for each account within that window period. With this approach, the contract does not require a variable acting as a `counter` or a `state` to keep updating the latest state, nor does it need any interaction calls to keep updating the current period, which is an effortful and costly design.

#### `epoch` and `list` for storing data in vertical and horizontal way ```solidity // skipping struct Epoch { uint256 totalBalance; mapping(uint256 => uint256) blockBalances; SortedList.List list; } // skipping // O(n→) fot traversal each epoch. // O(n↓) for traversal each element in list. mapping(uint256 => mapping(address => Epoch))) private _balances; mapping(uint256 => uint256) private _worldStateBalance; ``` With `epoch` it provides an abstract loop in a horizontal way more efficient for calculating the usable balance of the account because it provides `totalBalance` which acts as suffix balance, so you don't need to get to iterate or traversal over the `list` in vertical to calculate the entire balance if the `epoch` can presume not to expire. The `_worldStateBalance` mapping tracks the total token balance across all accounts that minted tokens within a particular block. This structure allows the contract to trace expired balances easily. By consolidating balance data for each block. #### Buffering 1 `epoch` rule for ensuring safety In this design, the buffering slot is the critical element that requires careful calculation to ensure accurate handling of balances nearing expiration. By incorporating this buffer, the contract guarantees that any expiring balance is correctly accounted for within the sliding window mechanism, ensuring reliability and preventing premature expiration or missed balances. #### First-In-First-Out (FIFO) priority to enforce token expiration rules Enforcing `FIFO` priority ensures that tokens nearing expiration are processed before newer ones, aligning with the token lifecycle and expiration rules. This method eliminates the need for additional `off-chain` computation and ensures that all token processing occurs efficiently `on-chain`, fully compliant with the ERC20 interface. A **sorted** list is integral to this approach. Each `epoch` maintains its own list, sorted by token creation which is can be `block.timestamp` or `blocknumber`, preventing any overlap with other `epoch`. This separation ensures that tokens in one `epoch` do not interfere with the balance handling in another. The contract can then independently manage token expirations within each `epoch`, minimizing computation while maintaining accuracy and predictability in processing balances. --- #### Token Receipt and Transaction Likelihood across various blocktime Assuming each year contains 4 `epoch`, which aligns with familiar time-based divisions like a year being divided into four quarters, the following table presents various scenarios based on block time and token receipt intervals. It illustrates the potential transaction frequency and likelihood of receiving tokens within a given period. | Block Time (ms) | Receive Token Every (ms) | Index/Epoch | Frequency | Likelihood | | --------------- | ------------------------ | ----------- | ------------------- | ------------- | | 100 | 100 | 78,892,315 | 864,000 _times/day_ | Very Unlikely | | 500 | 500 | 15,778,463 | 172,800 _times/day_ | Very Unlikely | | 1000 | 1000 | 7,889,231 | 86,400 _times/day_ | Very Unlikely | | 1000 | 28,800,000 | 273 | 3 _times/day_ | Unlikely | | 1000 | 86,400,000 | 91 | 1 _times/day_ | Possible | | 5000 | 86,400,000 | 18 | 1 _times/month_ | Very Likely | | 10000 | 86,400,000 | 9 | 3 _times/month_ | Very Likely | > [!IMPORTANT] > - Transactions per day are assumed based on loyalty point earnings. > - Likelihood varies depending on the use case; for instance, gaming use cases may have higher transaction volumes than the given estimates. ## Security Considerations in The Reference Implementation - Solidity Division Rounding Down This implementation contract may encounter scenarios where the calculated expiration block is shorter than the actual expiration block. However, contract mitigates this risk by enforcing valid block times within the defined limits of `MINIMUM_BLOCK_TIME` and `MAXIMUM_BLOCK_TIME`. ## Usage #### Install Dependencies ```bash yarn install ``` #### Compile the Contract Compile the reference implementation ```bash yarn compile ``` #### Run Tests Execute the provided test suite to verify the contract's functionality and integrity ```bash yarn test ``` ### Cleaning Build Artifacts To clean up compiled files and artifacts generated during testing or deployment ```bash yarn clean ```

ERC-7858

# ERC-7858 This is reference implementation of ERC-7858 ## Implementation Describe ### Per-Token Expiry Default `ERC7858` is each token has its own independent start and end date, stored using `block.timestamp` or `block.number`. This provides flexibility, allowing tokens to expire at different dates/blocks. ### Epoch-based Expiry `ERC7858Epoch` similar to ERC-7818, this method enforces a shared lifetime duration for all tokens, ensuring they expire simultaneously. This can be useful for fixed-term subscriptions or time-based access control. ## Usage #### Install Dependencies ```bash yarn install ``` #### Compile the Contract Compile the reference implementation ```bash yarn compile ``` #### Run Tests Execute the provided test suite to verify the contract's functionality and integrity ```bash yarn test ``` ### Cleaning Build Artifacts To clean up compiled files and artifacts generated during testing or deployment ```bash yarn clean ```

ERC-7943 uRWA Minimal Package

# ERC-7943 uRWA Minimal Package ## Install dependencies ```bash forge install OpenZeppelin/openzeppelin-contracts forge install foundry-rs/forge-std ``` ## Build ```bash forge build ``` ## Test ```bash forge test -vv ``` ## Gas report ```bash forge test --gas-report ``` ## Coverage ```bash forge coverage ```

Groups reference implementation assets - After creating the Ethereum Magicians discussion, update `discussions-to` in `ERCS/erc-8063.md` with the live URL. - Contracts: - `IERC8063.sol`: interface - `ERC8063.sol`: minimal implementation - `ERC8063ERC20.sol`: optional ERC-20 compatibility implementation (decimals=0)

{% if page.xsl %}{% endif %}Jekyll{{ site.time | date_to_xmlschema }}{{ page.url | absolute_url | xml_escape }}{% assign title = site.title | default: site.name %}{% if page.collection != "posts" %}{% assign collection = page.collection | capitalize %}{% assign title = title | append: " | " | append: collection %}{% endif %}{% if page.category %}{% assign category = page.category | capitalize %}{% assign title = title | append: " | " | append: category %}{% endif %}{% if title %}{{ title | smartify | xml_escape }}{% endif %}{% if site.description %}{{ site.description | xml_escape }}{% endif %}{% if site.author %}{{ site.author.name | default: site.author | xml_escape }}{% if site.author.email %}{{ site.author.email | xml_escape }}{% endif %}{% if site.author.uri %}{{ site.author.uri | xml_escape }}{% endif %}{% endif %}{% if page.tags %}{% assign posts = site.tags[page.tags] %}{% else %}{% assign posts = site[page.collection] %}{% endif %}{% if page.category %}{% assign posts = posts | where: "category", page.category %}{% endif %}{% unless site.show_drafts %}{% assign posts = posts | where_exp: "post", "post.draft != true" %}{% endunless %}{% assign posts = posts | sort: "date" | reverse %}{% assign posts_limit = site.feed.posts_limit | default: 10 %}{% for post in posts limit: posts_limit %}{% assign post_title = post.title | smartify | strip_html | normalize_whitespace | xml_escape %}{{ post_title }}{{ post.date | date_to_xmlschema }}{{ post.last_modified_at | default: post.date | date_to_xmlschema }}{{ post.id | absolute_url | xml_escape }}{% assign excerpt_only = post.feed.excerpt_only | default: site.feed.excerpt_only %}{% unless excerpt_only %}{{ post.content | strip | xml_escape }}{% endunless %}{% assign post_author = post.author | default: post.authors[0] | default: site.author %}{% assign post_author = site.data.authors[post_author] | default: post_author %}{% assign post_author_email = post_author.email | default: nil %}{% assign post_author_uri = post_author.uri | default: nil %}{% assign post_author_name = post_author.name | default: post_author %}{{ post_author_name | default: "" | xml_escape }}{% if post_author_email %}{{ post_author_email | xml_escape }}{% endif %}{% if post_author_uri %}{{ post_author_uri | xml_escape }}{% endif %}{% if post.category %}{% elsif post.categories %}{% for category in post.categories %}{% endfor %}{% endif %}{% for tag in post.tags %}{% endfor %}{% if post.excerpt and post.excerpt != empty %}

{{ post.excerpt | strip_html | normalize_whitespace | xml_escape }}

{% endif %}{% assign post_image = post.image.path | default: post.image %}{% if post_image %}{% unless post_image contains "://" %}{% assign post_image = post_image | absolute_url %}{% endunless %}{% endif %}{% endfor %}

EIP Purpose and Guidelines

Tue, 27 Oct 2015 00:00:00 +0000

Token Standard

Thu, 19 Nov 2015 00:00:00 +0000

## Simple Summary A standard interface for tokens. ## Abstract The following standard allows for the implementation of a standard API for tokens within smart contracts. This standard provides basic functionality to transfer tokens, as well as allow tokens to be approved so they can be spent by another on-chain third party. ## Motivation A standard interface allows any tokens on Ethereum to be re-used by other applications: from wallets to decentralized exchanges. ## Specification ## Token ### Methods **NOTES**: - The following specifications use syntax from Solidity `0.4.17` (or above) - Callers MUST handle `false` from `returns (bool success)`. Callers MUST NOT assume that `false` is never returned! #### name Returns the name of the token - e.g. `"MyToken"`. OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present. ``` js function name() public view returns (string) ``` #### symbol Returns the symbol of the token. E.g. "HIX". OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present. ``` js function symbol() public view returns (string) ``` #### decimals Returns the number of decimals the token uses - e.g. `8`, means to divide the token amount by `100000000` to get its user representation. OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present. ``` js function decimals() public view returns (uint8) ``` #### totalSupply Returns the total token supply. ``` js function totalSupply() public view returns (uint256) ``` #### balanceOf Returns the account balance of another account with address `_owner`. ``` js function balanceOf(address _owner) public view returns (uint256 balance) ``` #### transfer Transfers `_value` amount of tokens to address `_to`, and MUST fire the `Transfer` event. The function SHOULD `throw` if the message caller's account balance does not have enough tokens to spend. *Note* Transfers of 0 values MUST be treated as normal transfers and fire the `Transfer` event. ``` js function transfer(address _to, uint256 _value) public returns (bool success) ``` #### transferFrom Transfers `_value` amount of tokens from address `_from` to address `_to`, and MUST fire the `Transfer` event. The `transferFrom` method is used for a withdraw workflow, allowing contracts to transfer tokens on your behalf. This can be used for example to allow a contract to transfer tokens on your behalf and/or to charge fees in sub-currencies. The function SHOULD `throw` unless the `_from` account has deliberately authorized the sender of the message via some mechanism. *Note* Transfers of 0 values MUST be treated as normal transfers and fire the `Transfer` event. ``` js function transferFrom(address _from, address _to, uint256 _value) public returns (bool success) ``` #### approve Allows `_spender` to withdraw from your account multiple times, up to the `_value` amount. If this function is called again it overwrites the current allowance with `_value`. **NOTE**: To prevent attack vectors like the one [described here](https://docs.google.com/document/d/1YLPtQxZu1UAvO9cZ1O2RPXBbT0mooh4DYKjA_jp-RLM/) and discussed [here](https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729), clients SHOULD make sure to create user interfaces in such a way that they set the allowance first to `0` before setting it to another value for the same spender. THOUGH The contract itself shouldn't enforce it, to allow backwards compatibility with contracts deployed before ``` js function approve(address _spender, uint256 _value) public returns (bool success) ``` #### allowance Returns the amount which `_spender` is still allowed to withdraw from `_owner`. ``` js function allowance(address _owner, address _spender) public view returns (uint256 remaining) ``` ### Events #### Transfer MUST trigger when tokens are transferred, including zero value transfers. A token contract which creates new tokens SHOULD trigger a Transfer event with the `_from` address set to `0x0` when tokens are created. ``` js event Transfer(address indexed _from, address indexed _to, uint256 _value) ``` #### Approval MUST trigger on any successful call to `approve(address _spender, uint256 _value)`. ``` js event Approval(address indexed _owner, address indexed _spender, uint256 _value) ``` ## Implementation There are already plenty of ERC20-compliant tokens deployed on the Ethereum network. Different implementations have been written by various teams that have different trade-offs: from gas saving to improved security. #### Example implementations are available at - [OpenZeppelin implementation](../assets/eip-20/OpenZeppelin-ERC20.sol) - [ConsenSys implementation](../assets/eip-20/Consensys-EIP20.sol) ## History Historical links related to this standard: - Original proposal from Vitalik Buterin: https://github.com/ethereum/wiki/wiki/Standardized_Contract_APIs/499c882f3ec123537fc2fccd57eaa29e6032fe4a - Reddit discussion: https://www.reddit.com/r/ethereum/comments/3n8fkn/lets_talk_about_the_coin_standard/ - Original Issue #20: https://github.com/ethereum/EIPs/issues/20 ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Mixed-case checksum address encoding

Thu, 14 Jan 2016 00:00:00 +0000

# Specification Code: ``` python import eth_utils def checksum_encode(addr): # Takes a 20-byte binary address as input hex_addr = addr.hex() checksummed_buffer = "" # Treat the hex address as ascii/utf-8 for keccak256 hashing hashed_address = eth_utils.keccak(text=hex_addr).hex() # Iterate over each character in the hex address for nibble_index, character in enumerate(hex_addr): if character in "0123456789": # We can't upper-case the decimal digits checksummed_buffer += character elif character in "abcdef": # Check if the corresponding hex digit (nibble) in the hash is 8 or higher hashed_address_nibble = int(hashed_address[nibble_index], 16) if hashed_address_nibble > 7: checksummed_buffer += character.upper() else: checksummed_buffer += character else: raise eth_utils.ValidationError( f"Unrecognized hex character {character!r} at position {nibble_index}" ) return "0x" + checksummed_buffer def test(addr_str): addr_bytes = eth_utils.to_bytes(hexstr=addr_str) checksum_encoded = checksum_encode(addr_bytes) assert checksum_encoded == addr_str, f"{checksum_encoded} != expected {addr_str}" test("0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed") test("0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359") test("0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB") test("0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb") ``` In English, convert the address to hex, but if the `i`th digit is a letter (ie. it's one of `abcdef`) print it in uppercase if the `4*i`th bit of the hash of the lowercase hexadecimal address is 1 otherwise print it in lowercase. # Rationale Benefits: - Backwards compatible with many hex parsers that accept mixed case, allowing it to be easily introduced over time - Keeps the length at 40 characters - On average there will be 15 check bits per address, and the net probability that a randomly generated address if mistyped will accidentally pass a check is 0.0247%. This is a ~50x improvement over ICAP, but not as good as a 4-byte check code. # Implementation In javascript: ```js const createKeccakHash = require('keccak') function toChecksumAddress (address) { address = address.toLowerCase().replace('0x', '') var hash = createKeccakHash('keccak256').update(address).digest('hex') var ret = '0x' for (var i = 0; i < address.length; i++) { if (parseInt(hash[i], 16) >= 8) { ret += address[i].toUpperCase() } else { ret += address[i] } } return ret } ``` ``` > toChecksumAddress('0xfb6916095ca1df60bb79ce92ce3ea74c37c5d359') '0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359' ``` Note that the input to the Keccak256 hash is the lowercase hexadecimal string (i.e. the hex address encoded as ASCII): ``` var hash = createKeccakHash('keccak256').update(Buffer.from(address.toLowerCase(), 'ascii')).digest() ``` # Test Cases ``` # All caps 0x52908400098527886E0F7030069857D2E4169EE7 0x8617E340B3D01FA5F11F306F4090FD50E238070D # All Lower 0xde709f2102306220921060314715629080e2fb77 0x27b1fdb04752bbc536007a920d24acb045561c26 # Normal 0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed 0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359 0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB 0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb ```

URI Scheme with Metadata, Value and Bytecode

Wed, 17 Feb 2016 00:00:00 +0000

## Abstract This proposal (inspired by BIP 21) defines a format for encoding a transaction into a URI, including a recipient, number of ethers (possibly zero), and optional bytecode. ## Motivation Imagine these scenarios: * An exchange or a instant converter like ShapeShift wants to create a single Ethereum address for payments that will be converted into credit in their internal system or output bitcoin to an address. * A store wants to show a QR code to a client that will pop up a payment for exactly 12.34 ethers, which contains metadata on the product being bought. * A betting site wants to provide a link that the user can click on his site and it will open a default Ethereum wallet and execute a specific contract with given parameters. * A dapp in Mist wants to simply ask the user to sign a transaction with a specific ABI in a single call. In all these scenarios, the provider wants to internally set up a transaction, with a recipient, an associated number of ethers (or none) and optional bytecode, all without requiring any fuss from the end user that is expected simply to choose a sender and authorise the transaction. Currently implementations for this are wonky: ShapeShift creates tons of temporary addresses and uses an internal system to check which one correspond to which metadata, there isn't any standard way for stores that want payment in ether to put specific metadata about price on the call and any app implementing contracts will have to use different solutions depending on the client they are targeting. The proposal goes beyond address, and also includes optional bytecode and value. Of course this would make the link longer, but it should not be something visible to the user. Instead it should be shown as a visual code (QR or otherwise), a link, or some other way to pass the information. If properly implemented in all wallets, this should make execution of contracts directly from wallets much simpler as the wallet client only needs to put the bytecode obtained by reading the QR code. ## Specification If we follow the bitcoin standard, the result would be: ``` ethereum:

[?value=][?gas=][?data=] ``` Other data could be added, but ideally the client should take them from elsewhere in the blockchain, so instead of having a `label` or a `message` to be displayed to the users, these should be read from an identity system or metadata on the transaction itself. ### Example 1 Clicking this link would open a transaction that would try to send _5 unicorns_ to address _deadbeef_. The user would then simply approve, based on each wallet UI. ``` ethereum:0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7?gas=100000&data=0xa9059cbb00000000000000000000000000000000000000000000000000000000deadbeef0000000000000000000000000000000000000000000000000000000000000005 ``` #### Without Bytecode Alternatively, the bytecode could be generated by the client and the request would be in plain text: ``` ethereum:

[?value=][?gas=][?function=nameOfFunction(param)] ``` ### Example 2 This is the same function as above, to send 5 unicorns from he sender to _deadbeef_, but now with a more readable function, which the client converts to bytecode. ``` ethereum:0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7?gas=100000&function=transfer(address 0xdeadbeef, uint 5) ``` ## Rationale TODO ## Security Considerations TODO ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Ethereum Domain Name Service - Specification

Mon, 04 Apr 2016 00:00:00 +0000

# Abstract This draft EIP describes the details of the Ethereum Name Service, a proposed protocol and ABI definition that provides flexible resolution of short, human-readable names to service and resource identifiers. This permits users and developers to refer to human-readable and easy to remember names, and permits those names to be updated as necessary when the underlying resource (contract, content-addressed data, etc) changes. The goal of domain names is to provide stable, human-readable identifiers that can be used to specify network resources. In this way, users can enter a memorable string, such as 'vitalik.wallet' or 'www.mysite.swarm', and be directed to the appropriate resource. The mapping between names and resources may change over time, so a user may change wallets, a website may change hosts, or a swarm document may be updated to a new version, without the domain name changing. Further, a domain need not specify a single resource; different record types allow the same domain to reference different resources. For instance, a browser may resolve 'mysite.swarm' to the IP address of its server by fetching its A (address) record, while a mail client may resolve the same address to a mail server by fetching its MX (mail exchanger) record. # Motivation Existing [specifications](https://github.com/ethereum/wiki/wiki/Registrar-ABI) and [implementations](https://ethereum.gitbooks.io/frontier-guide/content/registrar_services.html) for name resolution in Ethereum provide basic functionality, but suffer several shortcomings that will significantly limit their long-term usefulness: - A single global namespace for all names with a single 'centralised' resolver. - Limited or no support for delegation and sub-names/sub-domains. - Only one record type, and no support for associating multiple copies of a record with a domain. - Due to a single global implementation, no support for multiple different name allocation systems. - Conflation of responsibilities: Name resolution, registration, and whois information. Use-cases that these features would permit include: - Support for subnames/sub-domains - eg, live.mysite.tld and forum.mysite.tld. - Multiple services under a single name, such as a DApp hosted in Swarm, a Whisper address, and a mail server. - Support for DNS record types, allowing blockchain hosting of 'legacy' names. This would permit an Ethereum client such as Mist to resolve the address of a traditional website, or the mail server for an email address, from a blockchain name. - DNS gateways, exposing ENS domains via the Domain Name Service, providing easier means for legacy clients to resolve and connect to blockchain services. The first two use-cases, in particular, can be observed everywhere on the present-day internet under DNS, and we believe them to be fundamental features of a name service that will continue to be useful as the Ethereum platform develops and matures. The normative parts of this document does not specify an implementation of the proposed system; its purpose is to document a protocol that different resolver implementations can adhere to in order to facilitate consistent name resolution. An appendix provides sample implementations of resolver contracts and libraries, which should be treated as illustrative examples only. Likewise, this document does not attempt to specify how domains should be registered or updated, or how systems can find the owner responsible for a given domain. Registration is the responsibility of registrars, and is a governance matter that will necessarily vary between top-level domains. Updating of domain records can also be handled separately from resolution. Some systems, such as swarm, may require a well defined interface for updating domains, in which event we anticipate the development of a standard for this. # Specification ## Overview The ENS system comprises three main parts: - The ENS registry - Resolvers - Registrars The registry is a single contract that provides a mapping from any registered name to the resolver responsible for it, and permits the owner of a name to set the resolver address, and to create subdomains, potentially with different owners to the parent domain. Resolvers are responsible for performing resource lookups for a name - for instance, returning a contract address, a content hash, or IP address(es) as appropriate. The resolver specification, defined here and extended in other EIPs, defines what methods a resolver may implement to support resolving different types of records. Registrars are responsible for allocating domain names to users of the system, and are the only entities capable of updating the ENS; the owner of a node in the ENS registry is its registrar. Registrars may be contracts or externally owned accounts, though it is expected that the root and top-level registrars, at a minimum, will be implemented as contracts. Resolving a name in ENS is a two-step process. First, the ENS registry is called with the name to resolve, after hashing it using the procedure described below. If the record exists, the registry returns the address of its resolver. Then, the resolver is called, using the method appropriate to the resource being requested. The resolver then returns the desired result. For example, suppose you wish to find the address of the token contract associated with 'beercoin.eth'. First, get the resolver: ```javascript var node = namehash("beercoin.eth"); var resolver = ens.resolver(node); ``` Then, ask the resolver for the address for the contract: ```javascript var address = resolver.addr(node); ``` Because the `namehash` procedure depends only on the name itself, this can be precomputed and inserted into a contract, removing the need for string manipulation, and permitting O(1) lookup of ENS records regardless of the number of components in the raw name. ## Name Syntax ENS names must conform to the following syntax:

<domain> ::= <label> | <domain> "." <label>
<label> ::= any valid string label per [UTS46](https://unicode.org/reports/tr46/)

In short, names consist of a series of dot-separated labels. Each label must be a valid normalised label as described in [UTS46](https://unicode.org/reports/tr46/) with the options `transitional=false` and `useSTD3AsciiRules=true`. For Javascript implementations, a [library](https://www.npmjs.com/package/idna-uts46) is available that normalises and checks names. Note that while upper and lower case letters are allowed in names, the UTS46 normalisation process case-folds labels before hashing them, so two names with different case but identical spelling will produce the same namehash. Labels and domains may be of any length, but for compatibility with legacy DNS, it is recommended that labels be restricted to no more than 64 characters each, and complete ENS names to no more than 255 characters. For the same reason, it is recommended that labels do not start or end with hyphens, or start with digits. ## namehash algorithm Before being used in ENS, names are hashed using the 'namehash' algorithm. This algorithm recursively hashes components of the name, producing a unique, fixed-length string for any valid input domain. The output of namehash is referred to as a 'node'. Pseudocode for the namehash algorithm is as follows: ``` def namehash(name): if name == '': return '\0' * 32 else: label, _, remainder = name.partition('.') return sha3(namehash(remainder) + sha3(label)) ``` Informally, the name is split into labels, each label is hashed. Then, starting with the last component, the previous output is concatenated with the label hash and hashed again. The first component is concatenated with 32 '0' bytes. Thus, 'mysite.swarm' is processed as follows: ``` node = '\0' * 32 node = sha3(node + sha3('swarm')) node = sha3(node + sha3('mysite')) ``` Implementations should conform to the following test vectors for namehash: namehash('') = 0x0000000000000000000000000000000000000000000000000000000000000000 namehash('eth') = 0x93cdeb708b7545dc668eb9280176169d1c33cfd8ed6f04690a0bcc88a93fc4ae namehash('foo.eth') = 0xde9b09fd7c5f901e23a3f19fecc54828e9c848539801e86591bd9801b019f84f ## Registry specification The ENS registry contract exposes the following functions: ```solidity function owner(bytes32 node) constant returns (address); ``` Returns the owner (registrar) of the specified node. ```solidity function resolver(bytes32 node) constant returns (address); ``` Returns the resolver for the specified node. ```solidity function ttl(bytes32 node) constant returns (uint64); ``` Returns the time-to-live (TTL) of the node; that is, the maximum duration for which a node's information may be cached. ```solidity function setOwner(bytes32 node, address owner); ``` Transfers ownership of a node to another registrar. This function may only be called by the current owner of `node`. A successful call to this function logs the event `Transfer(bytes32 indexed, address)`. ```solidity function setSubnodeOwner(bytes32 node, bytes32 label, address owner); ``` Creates a new node, `sha3(node, label)` and sets its owner to `owner`, or updates the node with a new owner if it already exists. This function may only be called by the current owner of `node`. A successful call to this function logs the event `NewOwner(bytes32 indexed, bytes32 indexed, address)`. ```solidity function setResolver(bytes32 node, address resolver); ``` Sets the resolver address for `node`. This function may only be called by the owner of `node`. A successful call to this function logs the event `NewResolver(bytes32 indexed, address)`. ```solidity function setTTL(bytes32 node, uint64 ttl); ``` Sets the TTL for a node. A node's TTL applies to the 'owner' and 'resolver' records in the registry, as well as to any information returned by the associated resolver. ## Resolver specification Resolvers may implement any subset of the record types specified here. Where a record types specification requires a resolver to provide multiple functions, the resolver MUST implement either all or none of them. Resolvers MUST specify a fallback function that throws. Resolvers have one mandatory function: ```solidity function supportsInterface(bytes4 interfaceID) constant returns (bool) ``` The `supportsInterface` function is documented in [EIP-165](./eip-165.md), and returns true if the resolver implements the interface specified by the provided 4 byte identifier. An interface identifier consists of the XOR of the function signature hashes of the functions provided by that interface; in the degenerate case of single-function interfaces, it is simply equal to the signature hash of that function. If a resolver returns `true` for `supportsInterface()`, it must implement the functions specified in that interface. `supportsInterface` must always return true for `0x01ffc9a7`, which is the interface ID of `supportsInterface` itself. Currently standardised resolver interfaces are specified in the table below. The following interfaces are defined: | Interface name | Interface hash | Specification | | --- | --- | --- | | `addr` | 0x3b3b57de | [Contract address](#addr) | | `name` | 0x691f3431 | #181 | | `ABI` | 0x2203ab56 | #205 | | `pubkey` | 0xc8690233 | #619 | EIPs may define new interfaces to be added to this registry. ### Contract Address Interface Resolvers wishing to support contract address resources must provide the following function: ```solidity function addr(bytes32 node) constant returns (address); ``` If the resolver supports `addr` lookups but the requested node does not have an addr record, the resolver MUST return the zero address. Clients resolving the `addr` record MUST check for a zero return value, and treat this in the same manner as a name that does not have a resolver specified - that is, refuse to send funds to or interact with the address. Failure to do this can result in users accidentally sending funds to the 0 address. Changes to an address MUST trigger the following event: ```solidity event AddrChanged(bytes32 indexed node, address a); ``` # Appendix A: Registry Implementation ```solidity contract ENS { struct Record { address owner; address resolver; uint64 ttl; } mapping(bytes32=>Record) records; event NewOwner(bytes32 indexed node, bytes32 indexed label, address owner); event Transfer(bytes32 indexed node, address owner); event NewResolver(bytes32 indexed node, address resolver); modifier only_owner(bytes32 node) { if(records[node].owner != msg.sender) throw; _ } function ENS(address owner) { records[0].owner = owner; } function owner(bytes32 node) constant returns (address) { return records[node].owner; } function resolver(bytes32 node) constant returns (address) { return records[node].resolver; } function ttl(bytes32 node) constant returns (uint64) { return records[node].ttl; } function setOwner(bytes32 node, address owner) only_owner(node) { Transfer(node, owner); records[node].owner = owner; } function setSubnodeOwner(bytes32 node, bytes32 label, address owner) only_owner(node) { var subnode = sha3(node, label); NewOwner(node, label, owner); records[subnode].owner = owner; } function setResolver(bytes32 node, address resolver) only_owner(node) { NewResolver(node, resolver); records[node].resolver = resolver; } function setTTL(bytes32 node, uint64 ttl) only_owner(node) { NewTTL(node, ttl); records[node].ttl = ttl; } } ``` # Appendix B: Sample Resolver Implementations ### Built-in resolver The simplest possible resolver is a contract that acts as its own name resolver by implementing the contract address resource profile: ```solidity contract DoSomethingUseful { // Other code function addr(bytes32 node) constant returns (address) { return this; } function supportsInterface(bytes4 interfaceID) constant returns (bool) { return interfaceID == 0x3b3b57de || interfaceID == 0x01ffc9a7; } function() { throw; } } ``` Such a contract can be inserted directly into the ENS registry, eliminating the need for a separate resolver contract in simple use-cases. However, the requirement to 'throw' on unknown function calls may interfere with normal operation of some types of contract. ### Standalone resolver A basic resolver that implements the contract address profile, and allows only its owner to update records: ```solidity contract Resolver { event AddrChanged(bytes32 indexed node, address a); address owner; mapping(bytes32=>address) addresses; modifier only_owner() { if(msg.sender != owner) throw; _ } function Resolver() { owner = msg.sender; } function addr(bytes32 node) constant returns(address) { return addresses[node]; } function setAddr(bytes32 node, address addr) only_owner { addresses[node] = addr; AddrChanged(node, addr); } function supportsInterface(bytes4 interfaceID) constant returns (bool) { return interfaceID == 0x3b3b57de || interfaceID == 0x01ffc9a7; } function() { throw; } } ``` After deploying this contract, use it by updating the ENS registry to reference this contract for a name, then calling `setAddr()` with the same node to set the contract address it will resolve to. ### Public resolver Similar to the resolver above, this contract only supports the contract address profile, but uses the ENS registry to determine who should be allowed to update entries: ```solidity contract PublicResolver { event AddrChanged(bytes32 indexed node, address a); event ContentChanged(bytes32 indexed node, bytes32 hash); ENS ens; mapping(bytes32=>address) addresses; modifier only_owner(bytes32 node) { if(ens.owner(node) != msg.sender) throw; _ } function PublicResolver(address ensAddr) { ens = ENS(ensAddr); } function addr(bytes32 node) constant returns (address ret) { ret = addresses[node]; } function setAddr(bytes32 node, address addr) only_owner(node) { addresses[node] = addr; AddrChanged(node, addr); } function supportsInterface(bytes4 interfaceID) constant returns (bool) { return interfaceID == 0x3b3b57de || interfaceID == 0x01ffc9a7; } function() { throw; } } ``` # Appendix C: Sample Registrar Implementation This registrar allows users to register names at no cost if they are the first to request them. ```solidity contract FIFSRegistrar { ENS ens; bytes32 rootNode; function FIFSRegistrar(address ensAddr, bytes32 node) { ens = ENS(ensAddr); rootNode = node; } function register(bytes32 subnode, address owner) { var node = sha3(rootNode, subnode); var currentOwner = ens.owner(node); if(currentOwner != 0 && currentOwner != msg.sender) throw; ens.setSubnodeOwner(rootNode, subnode, owner); } } ```

Initial ENS Hash Registrar

Tue, 25 Oct 2016 00:00:00 +0000

## Contents - Abstract - Motivations - Specification - Initial restrictions - Name format for hash registration - Auctioning names - Deeds - Deployment and Upgrade process - Registrar Interface - Rationale - Not committing to a permanent registrar at the outset - Valid names >= 7 characters - Restricting TLD to `.eth` - Holding ether as collateral - Prior work ## Abstract This ERC describes the implementation, as deployed to the main ethereum network on 2017-05-04, of a registrar contract to govern the allocation of names in the Ethereum Name Service (ENS). The corresponding source code is [here](https://github.com/ethereum/ens/blob/mainnet/contracts/HashRegistrarSimplified.sol). For more background, refer to [EIP-137](./eip-137.md). > Registrars are responsible for allocating domain names to users of the system, and are the only entities capable of updating the ENS; the owner of a node in the ENS registry is its registrar. Registrars may be contracts or externally owned accounts, though it is expected that the root and top-level registrars, at a minimum, will be implemented as contracts. > > \- EIP 137 A well designed and governed registrar is essential to the success of the ENS described in EIP 137, but is described separately in this document as it is external to the core ENS protocol. In order to maximize utility and adoption of a new namespace, the registrar should mitigate speculation and "name squatting", however the best approach for mitigation is unclear. Thus an "initial" registrar is proposed, which implements a simple approach to name allocation. During the initial period, the available namespace will be significantly restricted to the `.eth` top level domain, and subdomain shorter than 7 characters in length disallowed. This specification largely describes @alexvandesande and @arachnid's [hash registrar implementation](https://github.com/ethereum/ens/blob/mainnet/contracts/HashRegistrarSimplified.sol) in order to facilitate discussion. The intent is to replace the Initial Registrar contract with a permanent registrar contract. The Permanent Registrar will increase the available namespace, and incorporate lessons learned from the performance of the Initial Registrar. This upgrade is expected to take place within approximately 2 years of initial deployment. ## Motivations The following factors should be considered in order to optimize for adoption of the ENS, and good governance of the Initial Registrar's namespace. **Upgradability:** The Initial Registrar should be safely upgradeable, so that knowledge gained during its deployment can be used to replace it with an improved and permanent registrar. **Effective allocation:** Newly released namespaces often create a land grab situation, resulting in many potentially valuable names being purchased but unused, with the hope of re-selling at a profit. This reduces the availability of the most useful names, in turn decreasing the utility of the name service to end users. Achieving an effective allocation may or may not require human intervention for dispute resolution and other forms of curation. The Initial Registrar should not aim to create to most effective possible allocation, but instead limit the cost of misallocation in the long term. **Security:** The registrar will hold a balance of ether without an explicit limit. It must be designed securely. **Simplicity:** The ENS specification itself emphasizes a separation of concerns, allowing the most essential element, the registry to be as simple as possible. The interim registrar in turn should be as simple as possible while still meeting its other design goals. **Adoption:** Successful standards become more successful due to network effects. The registrar should consider what strategies will encourage the adoption of the ENS in general, and the namespace it controls in particular. ## Specification ### Initial restrictions The Initial Registrar is expected to be in service for approximately two years, prior to upgrading. This should be sufficient time to learn, observe, and design an updated system. During the initial two year period, the available name space will be restricted to the `.eth` TLD. This restriction is enforced by the owner of the ENS root node who should not assign any nodes other than `.eth` to the Initial Registrar. The ENS's root node should be controlled by multiple parties using a multisig contract. The Initial Registrar will also prohibit registration of names 6 characters or less in length. ### Name format for hash registration Names submitted to the initial registrar must be hashed using Ethereum's sha3 function. Note that the hashes submitted to the registrar are the hash of the subdomain label being registered, not the namehash as defined in EIP 137. For example, in order to register `abcdefg.eth`, one should submit `sha3('abcdefg')`, not `sha3(sha3(0, 'eth'), 'abcdefg')`. ### Auctioning names The registrar will allocate the available names through a Vickrey auction: > A Vickrey auction is a type of sealed-bid auction. Bidders submit written bids without knowing the bid of the other people in the auction. The highest bidder wins but the price paid is the second-highest bid. This type of auction... gives bidders an incentive to bid their true value. > > \- [Vickrey Auction, Wikipedia](https://en.wikipedia.org/wiki/Vickrey_auction) The auction lifecycle of a name has 5 possible states, or Modes. 1. **Not-yet-available:** The majority of names will be initially unavailable for auction, and will become available some time during the 8 weeks after launch. 2. **Open:** The earliest availability for a name is determined by the most significant byte of its sha3 hash. `0x00` would become available immediately, `0xFF` would become available after 8 weeks, and the availability of other names is distributed accordingly. Once a name is available, it is possible to start an auction on it. 3. **Auction:** Once the auction for a name has begun, there is a 72 hour bidding period. Bidders must submit a payment of ether, along with sealed bids as a hash of `sha3(bytes32 hash, address owner, uint value, bytes32 salt)`. The bidder may obfuscate the true bid value by sending a greater amount of ether. 4. **Reveal:** After the bidding period, a 48 hour reveal period commences. During this time, bidders must reveal the true parameters of their sealed bid. As bids are revealed, ether payments are returned according to the schedule of "refund ratios" outlined in the table below. If no bids are revealed, the name will return to the Open state. 5. **Owned:** After the reveal period has finished, the winning bidder must submit a transaction to finalize the auction, which then calls the ENS's `setSubnodeOwner` function, recording the winning bidder's address as the owner of the hash of the name. The following table outlines important parameters which define the Registrar's auction mechanism. #### Registrar Parameters | Name | Description | Value | |--------------------|----------------------------------------------------------------------------------------------------|------------| | totalAuctionLength | The full time period from start of auction to end of the reveal period. | 5 days | | revealPeriod | The length of the time period during which bidding is no longer allowed, and bids must be revealed. | 48 hours | | launchLength | The time period during which all names will become available for auction. | 8 weeks | | minPrice | The minimum amount of ether which must be locked up in exchange for ownership of a name. | 0.01 ether | ### Deeds The Initial Registrar contract does not hold a balance itself. All ether sent to the Registrar will be held in a separate `Deed` contracts. A deed contract is first created and funded when a sealed bid is submitted. After an auction is completed and a hash is registered, the deed for the winning bid is held in exchange for ownership of the hash. Non-winning bids are refunded. A deed for an owned name may be transferred to another account by its owner, thus transferring ownership and control of the name. After 1 year of registration, the owner of a hash may choose to relinquish ownership and have the value of the deed returned to them. Deeds for non-winning bids can be closed by various methods, at which time any ether held will either be returned to the bidder, burnt, or sent to someone else as a reward for actions which help the registrar. The following table outlines what portion of the balance held in a deed contract will be returned upon closure, and to whom. The remaining balance will be burnt. #### Refund schedule | Reason for Deed closure | Refund Recipient | Refund Percentage | | --- | --- | --- | | A valid non-winning bid is revealed. | Bidder | 99.5% | | A bid submitted after the auction period is revealed. | Bidder | 99.5% | | An otherwise valid bid is revealed on an owned name. ¹ | Bidder | 0.5% | | An expired sealed bid is cancelled. ² | Canceler | 0.5% | | A registered hash is reported as invalid. ³ | Reporter | 50% | | A registered hash is reported as invalid. ³ | Owner | 50% | ##### Notes: 1. This incentivizes all bids to be revealed in time. If bids could be revealed late, an extortion attack on the current highest bidder could be made by threatening to reveal a new second highest bid. 2. A bid which remains sealed after more than 2 weeks and 5 days may be cancelled by anyone to collect a small reward. 2. Since names are hashed before auctioning and registration, the Initial Registrar is unable to enforce character length restrictions independently. A reward is therefore provided for reporting invalid names. ### Deployment and Upgrade process The Initial Registrar requires the ENS's address as a constructor, and should be deployed after the ENS. The multisig account owning the root node in the ENS should then set the Initial Registrar's address as owner of the `eth` node. The Initial Registrar is expected to be replaced by a Permanent Registrar approximately 2 years after deployment. The following process should be used for the upgrade: 1. The Permanent Registrar contract will be deployed. 2. The multisig account owning the root node in the ENS will assign ownership of the `.eth` node to the Permanent Registrar. 3. Owners of hashes in the Initial Registrar will be responsible for registering their deeds to the Permanent Registrar. A couple options are considered here: 1. Require owners to transfer their ownership prior to a cutoff date in order to maintain ownership and/or continue name resolution services. 2. Have the Permanent Registrar query the Initial Registrar for ownership if it is lacking an entry. ### Planned deactivation In order to limit dependence on the Initial Registrar, new auctions will stop after 4 years, and all ether held in deeds after 8 years will become unreachable. ### Registrar Interface `function state(bytes32 _hash) constant returns (Mode)` - Implements a state machine returning the current state of a name `function entries(bytes32 _hash) constant returns (Mode, address, uint, uint, uint)` - Returns the following information regarding a registered name: * state * deed address * registration date * balance of the deed * highest value bid at auction `function getAllowedTime(bytes32 _hash) constant returns (uint timestamp)` - Returns the time at which the hash will no longer be in the initial `not-yet-available` state. `function isAllowed(bytes32 _hash, uint _timestamp) constant returns (bool allowed)` - Takes a hash and a time, returns true if and only if it has passed the initial `not-yet-available` state. `function startAuction(bytes32 _hash);` - Moves the state of a hash from Open to Auction. Throws if state is not Open. `function startAuctions(bytes32[] _hashes);` - Starts multiple auctions on an array of hashes. This enables someone to open up an auction for a number of dummy hashes when they are only really interested in bidding for one. This will increase the cost for an attacker to simply bid blindly on all new auctions. Dummy auctions that are open but not bid on are closed after a week. `function shaBid(bytes32 hash, address owner, uint value, bytes32 salt) constant returns (bytes32 sealedBid);` - Takes the parameters of a bid, and returns the sealedBid hash value required to participate in the bidding for an auction. This obfuscates the parameters in order to mimic the mechanics of placing a bid in an envelope. `function newBid(bytes32 sealedBid);` - Bids are sent by sending a message to the main contract with a sealedBid hash and an amount of ether. The hash contains information about the bid, including the bidded name hash, the bid value, and a random salt. Bids are not tied to any one auction until they are revealed. The value of the bid itself can be masqueraded by sending more than the value of your actual bid. This is followed by a 48h reveal period. Bids revealed after this period will be burned and the ether unrecoverable. Since this is an auction, it is expected that most public hashes, like known domains and common dictionary words, will have multiple bidders pushing the price up. `function startAuctionsAndBid(bytes32[] hashes, bytes32 sealedBid)` - A utility function allowing a call to `startAuctions` followed by `newBid` in a single transaction. `function unsealBid(bytes32 _hash, address _owner, uint _value, bytes32 _salt);` - Once the bidding period is completed, there is a reveal period during with the properties of a bid are submitted to reveal them. The registrar hashes these properties using the `shaBid()` function above to verify that they match a pre-existing sealed bid. If the unsealedBid is the new best bid, the old best bid is returned to its bidder. `function cancelBid(bytes32 seal);` - Cancels an unrevealed bid according to the rules described in the notes on the refund schedule above. `function finalizeAuction(bytes32 _hash);` After the registration date has passed, this function can be called to finalize the auction, which then calls the ENS function `setSubnodeOwner()` updating the ENS record to set the winning bidder as owner of the node. `function transfer(bytes32 _hash, address newOwner);` - Update the owner of the ENS node corresponding to the submitted hash to a new owner. This function must be callable only by the current owner. `function releaseDeed(bytes32 _hash);` - After some time, the owner can release the property and get their ether back. `function invalidateName(string unhashedName);` - Since registration is done on the hash of a name, the registrar itself cannot validate names. This function can be used to report a name which is 6 characters long or less. If it has been registered, the submitter will earn 10% of the deed value. We are purposefully handicapping the simplified registrar as a way to force it into being restructured in a few years. `function eraseNode(bytes32[] labels)` - Allows anyone to delete the owner and resolver records for a subdomain of a name that is not currently owned in the registrar. For instance, to zero `foo.bar.eth` on a registrar that owns `.eth`, pass an array containing `[sha3('foo'), sha3('bar')]`. `function transferRegistrars(bytes32 _hash) onlyOwner(_hash);` - Used during the upgrade process to a permanent registrar. If this registrar is no longer the owner of the its root node in the ENS, this function will transfers the deed to the current owner, which should be a new registrar. This function throws if this registrar still owns its root node. ## Rationale ### Starting with a temporary registrar Anticipating and designing for all the potential issues of name allocation names is unlikely to succeed. This approach chooses not to be concerned with getting it perfect, but allows us to observe and learn with training wheels on, and implement improvements before expanding the available namespace to shorter names or another TLD. ### Valid names >= 7 characters Preserving the shortest, and often most valuable, domain names for the upgraded registrar provides the opportunity to implement processes for dispute resolution (assuming they are found to be necessary). ### Delayed release of names A slower release allows for extra time to identify, and address any issues which may arise after launch. ### Restricting TLD to `.eth` Choosing a single TLD helps to maximize network effects by focusing on one namespace. A three letter TLD is a pattern made familiar by it's common usage in internet domain names. This familiarity significantly increases the potential of the ENS to be integrated into pre-existing DNS systems, and reserved as a [special-use domain name](https://www.iana.org/assignments/special-use-domain-names/special-use-domain-names.xhtml#special-use-domain). A recent precedent for this is the [reservation of the `.onion` domain](https://tools.ietf.org/html/rfc7686). ### Holding ether as collateral This approach is simpler than the familiar model of requiring owners to make recurring payments to retain ownership of a domain name. It also makes the initial registrar a revenue neutral service. ## Prior work This document borrows heavily from several sources: - [EIP-137](./eip-137.md) outlines the initial implementation of the Registry Contract (ENS.sol) and associated Resolver contracts. - [ERC-26](https://github.com/ethereum/EIPs/issues/26) was the first ERC to propose a name service at the contract layer - @alexvandesande's current implementation of the [HashRegistrar](https://github.com/ethereum/ens/blob/mainnet/contracts/HashRegistrarSimplified.sol) ### Edits: - 2016-10-26 Added link Alex's design in abstract - 2016-11-01 change 'Planned deactivation' to h3' - 2017-03-13 Update timelines for bidding and reveal periods ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Standard Interface Detection

Tue, 23 Jan 2018 00:00:00 +0000

## Simple Summary Creates a standard method to publish and detect what interfaces a smart contract implements. ## Abstract Herein, we standardize the following: 1. How interfaces are identified 2. How a contract will publish the interfaces it implements 3. How to detect if a contract implements ERC-165 4. How to detect if a contract implements any given interface ## Motivation For some "standard interfaces" like [the ERC-20 token interface](./eip-20.md), it is sometimes useful to query whether a contract supports the interface and if yes, which version of the interface, in order to adapt the way in which the contract is to be interacted with. Specifically for ERC-20, a version identifier has already been proposed. This proposal standardizes the concept of interfaces and standardizes the identification (naming) of interfaces. ## Specification ### How Interfaces are Identified For this standard, an *interface* is a set of [function selectors as defined by the Ethereum ABI](https://solidity.readthedocs.io/en/develop/abi-spec.html#function-selector). This a subset of [Solidity's concept of interfaces](https://solidity.readthedocs.io/en/develop/abi-spec.html) and the `interface` keyword definition which also defines return types, mutability and events. We define the interface identifier as the XOR of all function selectors in the interface. This code example shows how to calculate an interface identifier: ```solidity pragma solidity ^0.4.20; interface Solidity101 { function hello() external pure; function world(int) external pure; } contract Selector { function calculateSelector() public pure returns (bytes4) { Solidity101 i; return i.hello.selector ^ i.world.selector; } } ``` Note: interfaces do not permit optional functions, therefore, the interface identity will not include them. ### How a Contract will Publish the Interfaces it Implements A contract that is compliant with ERC-165 shall implement the following interface (referred as `ERC165.sol`): ```solidity pragma solidity ^0.4.20; interface ERC165 { /// @notice Query if a contract implements an interface /// @param interfaceID The interface identifier, as specified in ERC-165 /// @dev Interface identification is specified in ERC-165. This function /// uses less than 30,000 gas. /// @return `true` if the contract implements `interfaceID` and /// `interfaceID` is not 0xffffffff, `false` otherwise function supportsInterface(bytes4 interfaceID) external view returns (bool); } ``` The interface identifier for this interface is `0x01ffc9a7`. You can calculate this by running `bytes4(keccak256('supportsInterface(bytes4)'));` or using the `Selector` contract above. Therefore the implementing contract will have a `supportsInterface` function that returns: - `true` when `interfaceID` is `0x01ffc9a7` (EIP165 interface) - `false` when `interfaceID` is `0xffffffff` - `true` for any other `interfaceID` this contract implements - `false` for any other `interfaceID` This function must return a bool and use at most 30,000 gas. Implementation note, there are several logical ways to implement this function. Please see the example implementations and the discussion on gas usage. ### How to Detect if a Contract Implements ERC-165 1. The source contract makes a `STATICCALL` to the destination address with input data: `0x01ffc9a701ffc9a700000000000000000000000000000000000000000000000000000000` and gas 30,000. This corresponds to `contract.supportsInterface(0x01ffc9a7)`. 2. If the call fails or return false, the destination contract does not implement ERC-165. 3. If the call returns true, a second call is made with input data `0x01ffc9a7ffffffff00000000000000000000000000000000000000000000000000000000`. 4. If the second call fails or returns true, the destination contract does not implement ERC-165. 5. Otherwise it implements ERC-165. ### How to Detect if a Contract Implements any Given Interface 1. If you are not sure if the contract implements ERC-165, use the above procedure to confirm. 2. If it does not implement ERC-165, then you will have to see what methods it uses the old-fashioned way. 3. If it implements ERC-165 then just call `supportsInterface(interfaceID)` to determine if it implements an interface you can use. ## Rationale We tried to keep this specification as simple as possible. This implementation is also compatible with the current Solidity version. ## Backwards Compatibility The mechanism described above (with `0xffffffff`) should work with most of the contracts previous to this standard to determine that they do not implement ERC-165. Also [the ENS](./eip-137.md) already implements this EIP. ## Test Cases Following is a contract that detects which interfaces other contracts implement. From @fulldecent and @jbaylina. ```solidity pragma solidity ^0.4.20; contract ERC165Query { bytes4 constant InvalidID = 0xffffffff; bytes4 constant ERC165ID = 0x01ffc9a7; function doesContractImplementInterface(address _contract, bytes4 _interfaceId) external view returns (bool) { uint256 success; uint256 result; (success, result) = noThrowCall(_contract, ERC165ID); if ((success==0)||(result==0)) { return false; } (success, result) = noThrowCall(_contract, InvalidID); if ((success==0)||(result!=0)) { return false; } (success, result) = noThrowCall(_contract, _interfaceId); if ((success==1)&&(result==1)) { return true; } return false; } function noThrowCall(address _contract, bytes4 _interfaceId) constant internal returns (uint256 success, uint256 result) { bytes4 erc165ID = ERC165ID; assembly { let x := mload(0x40) // Find empty storage location using "free memory pointer" mstore(x, erc165ID) // Place signature at beginning of empty storage mstore(add(x, 0x04), _interfaceId) // Place first argument directly next to signature success := staticcall( 30000, // 30k gas _contract, // To addr x, // Inputs are stored at location x 0x24, // Inputs are 36 bytes long x, // Store output over input (saves space) 0x20) // Outputs are 32 bytes long result := mload(x) // Load the result } } } ``` ## Implementation This approach uses a `view` function implementation of `supportsInterface`. The execution cost is 586 gas for any input. But contract initialization requires storing each interface (`SSTORE` is 20,000 gas). The `ERC165MappingImplementation` contract is generic and reusable. ```solidity pragma solidity ^0.4.20; import "./ERC165.sol"; contract ERC165MappingImplementation is ERC165 { /// @dev You must not set element 0xffffffff to true mapping(bytes4 => bool) internal supportedInterfaces; function ERC165MappingImplementation() internal { supportedInterfaces[this.supportsInterface.selector] = true; } function supportsInterface(bytes4 interfaceID) external view returns (bool) { return supportedInterfaces[interfaceID]; } } interface Simpson { function is2D() external returns (bool); function skinColor() external returns (string); } contract Lisa is ERC165MappingImplementation, Simpson { function Lisa() public { supportedInterfaces[this.is2D.selector ^ this.skinColor.selector] = true; } function is2D() external returns (bool){} function skinColor() external returns (string){} } ``` Following is a `pure` function implementation of `supportsInterface`. The worst-case execution cost is 236 gas, but increases linearly with a higher number of supported interfaces. ```solidity pragma solidity ^0.4.20; import "./ERC165.sol"; interface Simpson { function is2D() external returns (bool); function skinColor() external returns (string); } contract Homer is ERC165, Simpson { function supportsInterface(bytes4 interfaceID) external view returns (bool) { return interfaceID == this.supportsInterface.selector || // ERC165 interfaceID == this.is2D.selector ^ this.skinColor.selector; // Simpson } function is2D() external returns (bool){} function skinColor() external returns (string){} } ``` With three or more supported interfaces (including ERC165 itself as a required supported interface), the mapping approach (in every case) costs less gas than the pure approach (at worst case). ## Version history * PR 1640, finalized 2019-01-23 -- This corrects the noThrowCall test case to use 36 bytes rather than the previous 32 bytes. The previous code was an error that still silently worked in Solidity 0.4.x but which was broken by new behavior introduced in Solidity 0.5.0. This change was discussed at [#1640](https://github.com/ethereum/EIPs/pull/1640). * EIP 165, finalized 2018-04-20 -- Original published version. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Contract Ownership Standard

Thu, 07 Jun 2018 00:00:00 +0000

## Abstract This specification defines standard functions for owning or controlling a contract. An implementation allows reading the current owner (`owner() returns (address)`) and transferring ownership (`transferOwnership(address newOwner)`) along with a standardized event for when ownership is changed (`OwnershipTransferred(address indexed previousOwner, address indexed newOwner)`). ## Motivation Many smart contracts require that they be owned or controlled in some way. For example to withdraw funds or perform administrative actions. It is so common that the contract interface used to handle contract ownership should be standardized to allow compatibility with user interfaces and contracts that manage contracts. Here are some examples of kinds of contracts and applications that can benefit from this standard: 1. Exchanges that buy/sell/auction ethereum contracts. This is only widely possible if there is a standard for getting the owner of a contract and transferring ownership. 2. Contract wallets that hold the ownership of contracts and that can transfer the ownership of contracts. 3. Contract registries. It makes sense for some registries to only allow the owners of contracts to add/remove their contracts. A standard must exist for these contract registries to verify that a contract is being submitted by the owner of it before accepting it. 4. User interfaces that show and transfer ownership of contracts. ## Specification Every ERC-173 compliant contract must implement the `ERC173` interface. Contracts should also implement `ERC165` for the ERC-173 interface. ```solidity /// @title ERC-173 Contract Ownership Standard /// Note: the ERC-165 identifier for this interface is 0x7f5828d0 interface ERC173 /* is ERC165 */ { /// @dev This emits when ownership of a contract changes. event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); /// @notice Get the address of the owner /// @return The address of the owner. function owner() view external returns(address); /// @notice Set the address of the new owner of the contract /// @dev Set _newOwner to address(0) to renounce any ownership. /// @param _newOwner The address of the new owner of the contract function transferOwnership(address _newOwner) external; } interface ERC165 { /// @notice Query if a contract implements an interface /// @param interfaceID The interface identifier, as specified in ERC-165 /// @dev Interface identification is specified in ERC-165. /// @return `true` if the contract implements `interfaceID` and /// `interfaceID` is not 0xffffffff, `false` otherwise function supportsInterface(bytes4 interfaceID) external view returns (bool); } ``` The `owner()` function may be implemented as `pure` or `view`. The `transferOwnership(address _newOwner)` function may be implemented as `public` or `external`. To renounce any ownership of a contract set `_newOwner` to the zero address: `transferOwnership(address(0))`. If this is done then a contract is no longer owned by anybody. The OwnershipTransferred event should be emitted when a contract is created. ## Rationale Key factors influencing the standard: - Keeping the number of functions in the interface to a minimum to prevent contract bloat. - Backwards compatibility with existing contracts. - Simplicity - Gas efficient Several ownership schemes were considered. The scheme chosen in this standard was chosen because of its simplicity, low gas cost and backwards compatibility with existing contracts. Here are other schemes that were considered: 1. **Associating an Ethereum Name Service (ENS) domain name with a contract.** A contract's `owner()` function could look up the owner address of a particular ENS name and use that as the owning address of the contract. Using this scheme a contract could be transferred by transferring the ownership of the ENS domain name to a different address. Short comings to this approach are that it is not backwards compatible with existing contracts and requires gas to make external calls to ENS related contracts to get the owner address. 2. **Associating an ERC721-based non-fungible token (NFT) with a contract.** Ownership of a contract could be tied to the ownership of an NFT. The benefit of this approach is that the existing ERC721-based infrastructure could be used to sell/buy/auction contracts. Short comings to this approach are additional complexity and infrastructure required. A contract could be associated with a particular NFT but the NFT would not track that it had ownership of a contract unless it was programmed to track contracts. In addition handling ownership of contracts this way is not backwards compatible. This standard does not exclude the above ownership schemes or other schemes from also being implemented in the same contract. For example a contract could implement this standard and also implement the other schemes so that ownership could be managed and transferred in multiple ways. This standard does provide a simple ownership scheme that is backwards compatible, is light-weight and simple to implement, and can be widely adopted and depended on. This standard can be (and has been) extended by other standards to add additional ownership functionality. ## Security Considerations If the address returned by `owner()` is an externally owned account then its private key must not be lost or compromised. ## Backwards Compatibility Many existing contracts already implement this standard. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

ENS support for reverse resolution of Ethereum addresses

Thu, 01 Dec 2016 00:00:00 +0000

# Abstract This EIP specifies a TLD, registrar, and resolver interface for reverse resolution of Ethereum addresses using ENS. This permits associating a human-readable name with any Ethereum blockchain address. Resolvers can be certain that the reverse record was published by the owner of the Ethereum address in question. # Motivation While name services are mostly used for forward resolution - going from human-readable identifiers to machine-readable ones - there are many use-cases in which reverse resolution is useful as well: - Applications that allow users to monitor accounts benefit from showing the name of an account instead of its address, even if it was originally added by address. - Attaching metadata such as descriptive information to an address allows retrieving this information regardless of how the address was originally discovered. - Anyone can configure a name to resolve to an address, regardless of ownership of that address. Reverse records allow the owner of an address to claim a name as authoritative for that address. # Specification Reverse ENS records are stored in the ENS hierarchy in the same fashion as regular records, under a reserved domain, `addr.reverse`. To generate the ENS name for a given account's reverse records, convert the account to hexadecimal representation in lower-case, and append `addr.reverse`. For instance, the ENS registry's address at `0x112234455c3a32fd11230c42e7bccd4a84e02010` has any reverse records stored at `112234455c3a32fd11230c42e7bccd4a84e02010.addr.reverse`. Note that this means that contracts wanting to do dynamic reverse resolution of addresses will need to perform hex encoding in the contract. ## Registrar The owner of the `addr.reverse` domain will be a registrar that permits the caller to take ownership of the reverse record for their own address. It provides the following methods: ### function claim(address owner) returns (bytes32 node) When called by account `x`, instructs the ENS registry to transfer ownership of the name `hex(x) + '.addr.reverse'` to the provided address, and return the namehash of the ENS record thus transferred. Allowing the caller to specify an owner other than themselves for the relevant node facilitates contracts that need accurate reverse ENS entries delegating this to their creators with a minimum of code inside their constructor: reverseRegistrar.claim(msg.sender) ### function claimWithResolver(address owner, address resolver) returns (bytes32 node) When called by account `x`, instructs the ENS registry to set the resolver of the name `hex(x) + '.addr.reverse'` to the specified resolver, then transfer ownership of the name to the provided address, and return the namehash of the ENS record thus transferred. This method facilitates setting up a custom resolver and owner in fewer transactions than would be required if calling `claim`. ### function setName(string name) returns (bytes32 node) When called by account `x`, sets the resolver for the name `hex(x) + '.addr.reverse'` to a default resolver, and sets the name record on that name to the specified name. This method facilitates setting up simple reverse records for users in a single transaction. ## Resolver interface A new resolver interface is defined, consisting of the following method: function name(bytes32 node) constant returns (string); Resolvers that implement this interface must return a valid ENS name for the requested node, or the empty string if no name is defined for the requested node. The interface ID of this interface is 0x691f3431. Future EIPs may specify more record types appropriate to reverse ENS records. # Appendix 1: Registrar implementation This registrar, written in Solidity, implements the specifications outlined above. pragma solidity ^0.4.10; import "./AbstractENS.sol"; contract Resolver { function setName(bytes32 node, string name) public; } /** * @dev Provides a default implementation of a resolver for reverse records, * which permits only the owner to update it. */ contract DefaultReverseResolver is Resolver { AbstractENS public ens; mapping(bytes32=>string) public name; /** * @dev Constructor * @param ensAddr The address of the ENS registry. */ function DefaultReverseResolver(AbstractENS ensAddr) { ens = ensAddr; } /** * @dev Only permits calls by the reverse registrar. * @param node The node permission is required for. */ modifier owner_only(bytes32 node) { require(msg.sender == ens.owner(node)); _; } /** * @dev Sets the name for a node. * @param node The node to update. * @param _name The name to set. */ function setName(bytes32 node, string _name) public owner_only(node) { name[node] = _name; } } contract ReverseRegistrar { // namehash('addr.reverse') bytes32 constant ADDR_REVERSE_NODE = 0x91d1777781884d03a6757a803996e38de2a42967fb37eeaca72729271025a9e2; AbstractENS public ens; Resolver public defaultResolver; /** * @dev Constructor * @param ensAddr The address of the ENS registry. * @param resolverAddr The address of the default reverse resolver. */ function ReverseRegistrar(AbstractENS ensAddr, Resolver resolverAddr) { ens = ensAddr; defaultResolver = resolverAddr; } /** * @dev Transfers ownership of the reverse ENS record associated with the * calling account. * @param owner The address to set as the owner of the reverse record in ENS. * @return The ENS node hash of the reverse record. */ function claim(address owner) returns (bytes32 node) { return claimWithResolver(owner, 0); } /** * @dev Transfers ownership of the reverse ENS record associated with the * calling account. * @param owner The address to set as the owner of the reverse record in ENS. * @param resolver The address of the resolver to set; 0 to leave unchanged. * @return The ENS node hash of the reverse record. */ function claimWithResolver(address owner, address resolver) returns (bytes32 node) { var label = sha3HexAddress(msg.sender); node = sha3(ADDR_REVERSE_NODE, label); var currentOwner = ens.owner(node); // Update the resolver if required if(resolver != 0 && resolver != ens.resolver(node)) { // Transfer the name to us first if it's not already if(currentOwner != address(this)) { ens.setSubnodeOwner(ADDR_REVERSE_NODE, label, this); currentOwner = address(this); } ens.setResolver(node, resolver); } // Update the owner if required if(currentOwner != owner) { ens.setSubnodeOwner(ADDR_REVERSE_NODE, label, owner); } return node; } /** * @dev Sets the `name()` record for the reverse ENS record associated with * the calling account. First updates the resolver to the default reverse * resolver if necessary. * @param name The name to set for this address. * @return The ENS node hash of the reverse record. */ function setName(string name) returns (bytes32 node) { node = claimWithResolver(this, defaultResolver); defaultResolver.setName(node, name); return node; } /** * @dev Returns the node hash for a given account's reverse records. * @param addr The address to hash * @return The ENS node hash. */ function node(address addr) constant returns (bytes32 ret) { return sha3(ADDR_REVERSE_NODE, sha3HexAddress(addr)); } /** * @dev An optimised function to compute the sha3 of the lower-case * hexadecimal representation of an Ethereum address. * @param addr The address to hash * @return The SHA3 hash of the lower-case hexadecimal encoding of the * input address. */ function sha3HexAddress(address addr) private returns (bytes32 ret) { addr; ret; // Stop warning us about unused variables assembly { let lookup := 0x3031323334353637383961626364656600000000000000000000000000000000 let i := 40 loop: i := sub(i, 1) mstore8(i, byte(and(addr, 0xf), lookup)) addr := div(addr, 0x10) i := sub(i, 1) mstore8(i, byte(and(addr, 0xf), lookup)) addr := div(addr, 0x10) jumpi(loop, i) ret := sha3(0, 40) } } } ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Ethereum Smart Contract Packaging Standard

Tue, 10 Jan 2017 00:00:00 +0000

# Abstract This ERC proposes a specification for Ethereum smart contract packages. The specification was collaboratively developed by the following Ethereum development framework maintainers. * Tim Coulter (Truffle) * Denis Erfurt (Dapple) * Piper Merriam (Populus) * RJ Catalano (Eris PM) * Iuri Matias (Embark) # Motivation Packaging is a core piece of modern software development which is missing from the Ethereum ecosystem. The lack of packaging limits the ability for developers to reuse code which negatively affects productivity and security. A key example of this is the ERC20 standard. There are a few well audited reusable token contracts available but most developers end up writing their own because of the difficulty in finding and reusing existing code. A packaging standard should have the following positive effects on the ecosystem: * Greater overall productivity caused by the ability to reuse existing code. * Increased security caused by the ability to reuse existing well audited implementations of common patterns (ERC20, crowdfunding, etc). Smart contract packaging should also have a direct positive effect on the end user. Wallet software will be able to consume a released package and generate an interface for interacting with any deployed contracts included within that package. With the advent of [ENS](./eip-137.md) all of the pieces will be in place for a wallet to take a human readable name and present the user with an interface for interacting with the underlying application. # Specification The full specification for this standard is maintained separately in the repository [epm/epm-spec](https://github.com/ethpm/epm-spec). This EIP refers to the `1.0.0` version of the specification: [https://github.com/ethpm/epm-spec/tree/v1.0.0](https://github.com/ethpm/epm-spec/tree/v1.0.0) The specification contains details for a single document referred to as a *"Release Lockfile"*. * Release Lockfile Specification: [https://github.com/ethpm/epm-spec/blob/v1.0.0/release-lockfile.spec.md](https://github.com/ethpm/epm-spec/blob/v1.0.0/release-lockfile.spec.md). * JSON Schema for Release Lockfile: [https://github.com/ethpm/epm-spec/blob/v1.0.0/spec/release-lockfile.spec.json](https://github.com/ethpm/epm-spec/blob/v1.0.0/spec/release-lockfile.spec.json) > These documents have not been inlined into this ERC to ensure that there is a single source of truth for the specification. # Use Cases This specification covers the following types of smart contract packages. 1. Packages with contracts intended to be used as base contract such as the common `owned` pattern. 2. Packages with contracts that are ready to use as-is such as an ERC20 token contract. 3. Packages with deployed contracts such as libraries or services. Full explanations and examples of these use cases can be found in the [`README.md`](https://github.com/ethpm/epm-spec/blob/v1.0.0/README.md#use-cases) from the `epm/epm-spec` repository. # Package Managers The *Release Lockfile* is intended for consumption by package management software. Specific care was made to ensure that all of the following functionality can be implemented by package managers. ## Deterministic builds Ensures that a package will always resolve to the same set of dependencies and source files. Both source files and dependencies are content addressed to ensure that the referenced resources cannot change. ## Bytecode verification Contains the appropriate information for a package manager to inspect a deployed contract and verify that its bytecode matches the bytecode that results from compilation and linking of the package source code. ## Multi-chain deploys Supports deployments across multiple chains, allowing a package to define addresses on both the public mainnet and testnet. ## Trusted packages Allows for packages which exclude source code or other elements which would be needed for verification of the contract bytecode. This allows for minimalistic packages to be created for special situations where the package manager will not be performing verification. # Framework support and integration Support for ERC190 is either implemented or in progress for the following: * [Truffle](https://truffleframework.com/) * [Populus](https://populus.readthedocs.io/en/latest/) * [Dapple](https://dapple.readthedocs.io/en/master/) * [Eris PM](https://github.com/eris-ltd/eris-cli) * [Embark](https://github.com/iurimatias/embark-framework) * [Browser Solidity](https://github.com/ethereum/remix-ide/issues/386)

Signed Data Standard

Wed, 20 Jan 2016 00:00:00 +0000

# Abstract This ERC proposes a specification about how to handle signed data in Ethereum contracts. # Motivation Several multisignature wallet implementations have been created which accepts `presigned` transactions. A `presigned` transaction is a chunk of binary `signed_data`, along with signature (`r`, `s` and `v`). The interpretation of the `signed_data` has not been specified, leading to several problems: * Standard Ethereum transactions can be submitted as `signed_data`. An Ethereum transaction can be unpacked, into the following components: `RLP` (hereby called `RLPdata`), `r`, `s` and `v`. If there are no syntactical constraints on `signed_data`, this means that `RLPdata` can be used as a syntactically valid `presigned` transaction. * Multisignature wallets have also had the problem that a `presigned` transaction has not been tied to a particular `validator`, i.e a specific wallet. Example: 1. Users `A`, `B` and `C` have the `2/3`-wallet `X` 2. Users `A`, `B` and `D` have the `2/3`-wallet `Y` 3. User `A` and `B` submit `presigned` transactions to `X`. 4. Attacker can now reuse their presigned transactions to `X`, and submit to `Y`. ## Specification We propose the following format for `signed_data` ``` 0x19 <1 byte version> . ``` The initial `0x19` byte is intended to ensure that the `signed_data` is not valid RLP. > For a single byte whose value is in the [0x00, 0x7f] range, that byte is its own RLP encoding. That means that any `signed_data` cannot be one RLP-structure, but a 1-byte `RLP` payload followed by something else. Thus, any EIP-191 `signed_data` can never be an Ethereum transaction. Additionally, `0x19` has been chosen because since ethereum/go-ethereum#2940 , the following is prepended before hashing in personal_sign: ``` "\x19Ethereum Signed Message:\n" + len(message). ``` Using `0x19` thus makes it possible to extend the scheme by defining a version `0x45` (`E`) to handle these kinds of signatures. ### Registry of version bytes | Version byte | EIP | Description | ------------ | -------------- | ----------- | `0x00` | [191][eip-191] | Data with intended validator | `0x01` | [712][eip-712] | Structured data | `0x45` | [191][eip-191] | `personal_sign` messages #### Version `0x00` ``` 0x19 <0x00> ``` The version `0x00` has `` for the version specific data. In the case of a Multisig wallet that perform an execution based on a passed signature, the validator address is the address of the Multisig itself. The data to sign could be any arbitrary data. #### Version `0x01` The version `0x01` is for structured data as defined in [EIP-712] #### Version `0x45` (E) ``` 0x19 <0x45 (E)> ``` The version `0x45` (E) has `` for the version-specific data. The data to sign can be any arbitrary data. > NB: The `E` in `Ethereum Signed Message` refers to the version byte 0x45. The character `E` is `0x45` in hexadecimal which makes the remainder, `thereum Signed Message:\n + len(message)`, the version-specific data. [EIP-191]: ./eip-191.md [EIP-712]: ./eip-712.md ### Example The following snippets has been written in Solidity 0.8.0. #### Version `0x00` ```solidity function signatureBasedExecution(address target, uint256 nonce, bytes memory payload, uint8 v, bytes32 r, bytes32 s) public payable { // Arguments when calculating hash to validate // 1: byte(0x19) - the initial 0x19 byte // 2: byte(0) - the version byte // 3: address(this) - the validator address // 4-6 : Application specific data bytes32 hash = keccak256(abi.encodePacked(byte(0x19), byte(0), address(this), msg.value, nonce, payload)); // recovering the signer from the hash and the signature addressRecovered = ecrecover(hash, v, r, s); // logic of the wallet // if (addressRecovered == owner) executeOnTarget(target, payload); } ``` ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

ENS support for contract ABIs

Mon, 06 Feb 2017 00:00:00 +0000

## Simple Summary This EIP proposes a mechanism for storing ABI definitions in ENS, for easy lookup of contract interfaces by callers. ## Abstract ABIs are important metadata required for interacting with most contracts. At present, they are typically supplied out-of-band, which adds an additional burden to interacting with contracts, particularly on a one-off basis or where the ABI may be updated over time. The small size of ABIs permits an alternative solution, storing them in ENS, permitting name lookup and ABI discovery via the same process. ABIs are typically quite compact; the largest in-use ABI we could find, that for the DAO, is 9450 bytes uncompressed JSON, 6920 bytes uncompressed CBOR, and 1128 bytes when the JSON form is compressed with zlib. Further gains on CBOR encoding are possible using a CBOR extension that permits eliminating repeated strings, which feature extensively in ABIs. Most ABIs, however, are far shorter than this, consisting of only a few hundred bytes of uncompressed JSON. This EIP defines a resolver profile for retrieving contract ABIs, as well as encoding standards for storing ABIs for different applications, allowing the user to select between different representations based on their need for compactness and other considerations such as onchain access. ## Specification ### ABI encodings In order to allow for different tradeoffs between onchain size and accessibility, several ABI encodings are defined. Each ABI encoding is defined by a unique constant with only a single bit set, allowing for the specification of 256 unique encodings in a single uint. The currently recognised encodings are: | ID | Description | |----|----------------------| | 1 | JSON | | 2 | zlib-compressed JSON | | 4 | CBOR | | 8 | URI | This table may be extended in future through the EIP process. Encoding type 1 specifies plaintext JSON, uncompressed; this is the standard format in which ABIs are typically encoded, but also the bulkiest, and is not easily parseable onchain. Encoding type 2 specifies zlib-compressed JSON. This is significantly smaller than uncompressed JSON, and is straightforward to decode offchain. However, it is impracticalfor onchain consumers to use. Encoding type 4 is [CBOR](https://cbor.io/). CBOR is a binary encoding format that is a superset of JSON, and is both more compact and easier to parse in limited environments such as the EVM. Consumers that support CBOR are strongly encouraged to also support the [stringref extension](http://cbor.schmorp.de/stringref) to CBOR, which provides significant additional reduction in encoded size. Encoding type 8 indicates that the ABI can be found elsewhere, at the specified URI. This is typically the most compact of the supported forms, but also adds external dependencies for implementers. The specified URI may use any schema, but HTTP, IPFS, and Swarm are expected to be the most common. ### Resolver profile A new resolver interface is defined, consisting of the following method: function ABI(bytes32 node, uint256 contentType) constant returns (uint256, bytes); The interface ID of this interface is 0x2203ab56. contentType is a bitfield, and is the bitwise OR of all the encoding types the caller will accept. Resolvers that implement this interface must return an ABI encoded using one of the requested formats, or `(0, "")` if they do not have an ABI for this function, or do not support any of the requested formats. The `abi` resolver profile is valid on both forward and reverse records. ### ABI lookup process When attempting to fetch an ABI based on an ENS name, implementers should first attempt an ABI lookup on the name itself. If that lookup returns no results, they should attempt a reverse lookup on the Ethereum address the name resolves to. Implementers should support as many of the ABI encoding formats as practical. ## Rationale Storing ABIs onchain avoids the need to introduce additional dependencies for applications wishing to fetch them, such as swarm or HTTP access. Given the typical compactness of ABIs, we believe this is a worthwhile tradeoff in many cases. The two-step resolution process permits different names to provide different ABIs for the same contract, such as in the case where it's useful to provide a minimal ABI to some callers, as well as specifying ABIs for contracts that did not specify one of their own. The fallback to looking up an ABI on the reverse record permits contracts to specify their own canonical ABI, and prevents the need for duplication when multiple names reference the same contract without the need for different ABIs. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Token with transaction handling model

Wed, 03 May 2017 00:00:00 +0000

## Abstract The following describes an interface and logic for fungible tokens that supports a `tokenReceived` callback to notify contract recipients when tokens are received. This makes tokens behave identical to ether. ## Motivation This token introduces a communication model for contracts that can be utilized to straighten the behavior of contracts that interact with such tokens. Specifically, this proposal: 1. Informs receiving contracts of incoming token transfers, as opposed to [ERC-20](./eip-20.md) where the recipient of a token transfer gets no notification. 2. Is more gas-efficient when depositing tokens to contracts. 3. Allows for `_data` recording for financial transfers. ## Specification Contracts intending to receive these tokens MUST implement `tokenReceived`. Token transfers to contracts not implementing `tokenReceived` as described below MUST revert. ### Token contract #### Token Methods ##### `totalSupply` ```solidity function totalSupply() view returns (uint256) ``` Returns the total supply of the token. The functionality of this method is identical to that of ERC-20. ##### `name` ```solidity function name() view returns (string memory) ``` Returns the name of the token. The functionality of this method is identical to that of ERC-20. OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present. ##### `symbol` ```solidity function symbol() view returns (string memory) ``` Returns the symbol of the token. The functionality of this method is identical to that of ERC-20. OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present. ##### `decimals` ```solidity function decimals() view returns (uint8) ``` Returns the number of decimals of the token. The functionality of this method is identical to that of ERC-20. OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present. ##### `balanceOf` ```solidity function balanceOf(address _owner) view returns (uint256) ``` Returns the account balance of another account with address `_owner`. The functionality of this method is identical to that of ERC-20. ##### `transfer(address, uint)` ```solidity function transfer(address _to, uint _value) returns (bool) ``` This function must transfer tokens, and if `_to` is a contract, it must call the `tokenReceived(address, uint256, bytes calldata)` function of `_to`. If the `tokenReceived` function is not implemented in `_to` (recipient contract), then the transaction must fail and the transfer of tokens must be reverted. If `_to` is an externally owned address, then the transaction must be sent without executing `tokenReceived` in `_to`. `_data` can be attached to this token transaction, but it requires more gas. `_data` can be empty. The `tokenReceived` function of `_to` MUST be called after all other operations to avoid re-entrancy attacks. NOTE: If `transfer` function is `payable` and ether was deposited then the amount of deposited ether MUST be delivered to `_to` address alongside tokens. If ether was sent alongside tokens in this way then ether MUST be delivered first, then token balances must be updated, then `tokenReceived` function MUST be called in `_to` if it is a contract. ##### `transfer(address, uint, bytes)` ```solidity function transfer(address _to, uint _value, bytes calldata _data) returns (bool) ``` This function must transfer tokens and invoke the function `tokenReceived (address, uint256, bytes)` in `_to`, if `_to` is a contract. If the `tokenReceived` function is not implemented in `_to` (recipient contract), then the transaction must fail and the transfer of tokens must not occur. If `_to` is an externally owned address (determined by the code size being zero), then the transaction must be sent without executing `tokenReceived` in `_to`. `_data` can be attached to this token transaction, but it requires more gas. `_data` can be empty. NOTE: A possible way to check whether the `_to` is a contract or an address is to assemble the code of `_to`. If there is no code in `_to`, then this is an externally owned address, otherwise it's a contract. If `transfer` function is `payable` and ether was deposited then the amount of deposited ether MUST be delivered to `_to` address alongside tokens. The `tokenReceived` function of `_to` MUST be called after all other operations to avoid re-entrancy attacks. #### Events ##### `Transfer` ```solidity event Transfer(address indexed _from, address indexed _to, uint256 _value, bytes _data) ``` Triggered when tokens are transferred. Compatible with and similar to the ERC-20 `Transfer` event. ### [ERC-223](./eip-223.md) Token Receiver #### Receiver Methods ```solidity function tokenReceived(address _from, uint _value, bytes calldata _data) returns (bytes4) ``` A function for handling token transfers, which is called from the token contract, when a token holder sends tokens. `_from` is the address of the sender of the token, `_value` is the amount of incoming tokens, and `_data` is attached data similar to `msg.data` of ether transactions. It works by analogy with the fallback function of Ether transactions and returns nothing. NOTE: `msg.sender` will be a token-contract inside the `tokenReceived` function. It may be important to filter which tokens were sent (by token-contract address). The token sender (the person who initiated the token transaction) will be `_from` inside the `tokenReceived` function. The `tokenReceived` function must return `0x8943ec02` after handling an incoming token transfer. The `tokenReceived` function call can be handled by the fallback function of the recipient contact (and in this case it may not return the magic value 0x8943ec02). IMPORTANT: This function must be named `tokenReceived` and take parameters `address`, `uint256`, `bytes` to match the function signature `0x8943ec02`. This function can be manually called by a EOA. ## Rationale This standard introduces a communication model by enforcing the `transfer` to execute a handler function in the destination address. This is an important security consideration as it is required that the receiver explicitly implements the token handling function. In cases where the receiver does not implements such function the transfer MUST be reverted. This standard sticks to the push transaction model where the transfer of assets is initiated on the senders side and handled on the receivers side. As the result, ERC-223 transfers are more gas-efficient while dealing with depositing to contracts as ERC-223 tokens can be deposited with just one transaction while ERC-20 tokens require at least two calls (one for `approve` and the second that will invoke `transferFrom`). - [ERC-20](./eip-20.md) deposit: `approve` ~46 gas, `transferFrom` ~75K gas - ERC-223 deposit: `transfer` and handling on the receivers side ~54K gas This standard introduces the ability to correct user errors by allowing to handle ANY transactions on the recipients side and reject incorrect or improper transfers. This tokens utilize ONE transferring method for both types of interactions with contracts and externally owned addresses which can simplify the user experience and allow to avoid possible user mistakes. One downside of the commonly used [ERC-20](./eip-20.md) standard that ERC-223 is intended to solve is that [ERC-20](./eip-20.md) implements two methods of token transferring: (1) `transfer` function and (2) `approve + transferFrom` pattern. Transfer function of [ERC-20](./eip-20.md) standard does not notify the receiver and therefore if any tokens are sent to a contract with the `transfer` function then the receiver will not recognize this transfer and the tokens can become stuck in the receivers address without any possibility of recovering them. [ERC-20](./eip-20.md) standard places the burden of determining the transferring method on the user and if the incorrect method is chosen the user can lose the transferred tokens. ERC-223 automatically determines the transferring method, preventing the user from losing tokens due to choosing wrong method. ERC-223 is intended to simplify the interaction with contracts that are intended to work with tokens. ERC-223 utilizes a "deposit" pattern, similar to that of plain Ether. An ERC-223 deposit to a contract is a simple call of the `transfer` function. This is one transaction as opposed to two step process of `approve + transferFrom` depositing. This standard allows payloads to be attached to transactions using the `bytes calldata _data` parameter, which can encode a second function call in the destination address, similar to how `msg.data` does in an ether transaction, or allow for public logging on chain should it be necessary for financial transactions. ## Backwards Compatibility The interface of this token is similar to that of ERC-20 and most functions serve the same purpose as their analogues in ERC-20. `transfer(address, uint256, bytes calldata)` function is not backwards compatible with ERC-20 interface. ERC-20 tokens can be delivered to a non-contract address with `transfer` function. ERC-20 tokens can be deposited to a contract address with `approve` + `transferFrom` pattern. Depositing ERC-20 tokens to the contract address with `transfer` function will always result in token deposit not being recognized by the recipient contract. Here is an example of the contract code that handles ERC-20 token deposit. The following contract can accepts `tokenA` deposits. It is impossible to prevent deposits of non-tokenA to this contract. If tokenA is deposited with `transfer` function then it will result in a loss of tokens for the depositor because the balance of the user will be decreased in the contract of tokenA but the value of `deposits` variable in the `ERC20Receiver` will not be increased i.e. the deposit will not be credited. As of 5/9/2023 **$201M worth of 50 examined ERC-20 tokens are already lost** in this way on Ethereum mainnet. ```solidity contract ERC20Receiver { address tokenA; mapping (address => uint256) deposits; function deposit(uint _value, address _token) public { require(_token == tokenA); IERC20(_token).transferFrom(msg.sender, address(this), _value); deposits[msg.sender] += _value; } } ``` ERC-223 tokens must be delivered to non-contract address or contract address in the same way with `transfer` function. Here is an example of the contract code that handles ERC-223 token deposit. The following contract can filter tokens and only accepts `tokenA`. Other ERC-223 tokens would be rejected. ```solidity contract ERC223Receiver { address tokenA; mapping (address => uint256) deposits; function tokenReceived(address _from, uint _value, bytes memory _data) public returns (bytes4) { require(msg.sender == tokenA); deposits[_from] += _value; return 0x8943ec02; } } ``` ## Security Considerations This token utilizes the model similar to plain ether behavior. Therefore replay issues must be taken into account. ### Reference Implementation ```solidity pragma solidity ^0.8.19; library Address { /** * @dev Returns true if `account` is a contract. * * This test is non-exhaustive, and there may be false-negatives: during the * execution of a contract's constructor, its address will be reported as * not containing a contract. * * > It is unsafe to assume that an address for which this function returns * false is an externally-owned account (EOA) and not a contract. */ function isContract(address account) internal view returns (bool) { // This method relies in extcodesize, which returns 0 for contracts in // construction, since the code is only stored at the end of the // constructor execution. uint256 size; // solhint-disable-next-line no-inline-assembly assembly { size := extcodesize(account) } return size > 0; } } abstract contract IERC223Recipient { /** * @dev Standard ERC-223 receiving function that will handle incoming token transfers. * * @param _from Token sender address. * @param _value Amount of tokens. * @param _data Transaction metadata. */ function tokenReceived(address _from, uint _value, bytes memory _data) public virtual returns (bytes4); } /** * @title Reference implementation of the ERC223 standard token. */ contract ERC223Token { /** * @dev Event that is fired on successful transfer. */ event Transfer(address indexed from, address indexed to, uint value, bytes data); string private _name; string private _symbol; uint8 private _decimals; uint256 private _totalSupply; mapping(address => uint256) private balances; // List of user balances. /** * @dev Sets the values for {name} and {symbol}, initializes {decimals} with * a default value of 18. * * To select a different value for {decimals}, use {_setupDecimals}. * * All three of these values are immutable: they can only be set once during * construction. */ constructor(string memory new_name, string memory new_symbol, uint8 new_decimals) { _name = new_name; _symbol = new_symbol; _decimals = new_decimals; } /** * @dev Returns the name of the token. */ function name() public view returns (string memory) { return _name; } /** * @dev Returns the symbol of the token, usually a shorter version of the * name. */ function symbol() public view returns (string memory) { return _symbol; } /** * @dev Returns the number of decimals used to get its user representation. * For example, if `decimals` equals `2`, a balance of `505` tokens should * be displayed to a user as `5,05` (`505 / 10 ** 2`). * * Tokens usually opt for a value of 18, imitating the relationship between * Ether and Wei. This is the value {ERC223} uses, unless {_setupDecimals} is * called. * * NOTE: This information is only used for _display_ purposes: it in * no way affects any of the arithmetic of the contract, including * {IERC223-balanceOf} and {IERC223-transfer}. */ function decimals() public view returns (uint8) { return _decimals; } /** * @dev See {IERC223-totalSupply}. */ function totalSupply() public view returns (uint256) { return _totalSupply; } /** * @dev See {IERC223-standard}. */ function standard() public view returns (string memory) { return "223"; } /** * @dev Returns balance of the `_owner`. * * @param _owner The address whose balance will be returned. * @return balance Balance of the `_owner`. */ function balanceOf(address _owner) public view returns (uint256) { return balances[_owner]; } /** * @dev Transfer the specified amount of tokens to the specified address. * Invokes the `tokenFallback` function if the recipient is a contract. * The token transfer fails if the recipient is a contract * but does not implement the `tokenFallback` function * or the fallback function to receive funds. * * @param _to Receiver address. * @param _value Amount of tokens that will be transferred. * @param _data Transaction metadata. */ function transfer(address _to, uint _value, bytes calldata _data) public returns (bool success) { // Standard function transfer similar to ERC20 transfer with no _data . // Added due to backwards compatibility reasons . balances[msg.sender] = balances[msg.sender] - _value; balances[_to] = balances[_to] + _value; if(Address.isContract(_to)) { IERC223Recipient(_to).tokenReceived(msg.sender, _value, _data); } emit Transfer(msg.sender, _to, _value, _data); return true; } /** * @dev Transfer the specified amount of tokens to the specified address. * This function works the same with the previous one * but doesn't contain `_data` param. * Added due to backwards compatibility reasons. * * @param _to Receiver address. * @param _value Amount of tokens that will be transferred. */ function transfer(address _to, uint _value) public returns (bool success) { bytes memory _empty = hex"00000000"; balances[msg.sender] = balances[msg.sender] - _value; balances[_to] = balances[_to] + _value; if(Address.isContract(_to)) { IERC223Recipient(_to).tokenReceived(msg.sender, _value, _empty); } emit Transfer(msg.sender, _to, _value, _empty); return true; } } ``` ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Ethereum purpose allocation for Deterministic Wallets

Thu, 13 Apr 2017 00:00:00 +0000

m / purpose' / subpurpose' / EIP'

Apostrophe in the path indicates that BIP32 hardened derivation is used. Each level has a special meaning, described in the chapters below. ### Purpose Purpose is set to 43, as documented in [this proposed change to BIP43](https://github.com/bitcoin/bips/pull/523). The purpose field indicates that this path is for a non-bitcoin cryptocurrency. Hardened derivation is used at this level. ### Subpurpose Subpurpose is set to 60, the SLIP-44 code for Ethereum. Hardened derivation is used at this level. ### EIP EIP is set to the EIP number specifying the remainder of the BIP32 derivation path. This permits new Ethereum-focused applications of deterministic wallets without needing to interface with the BIP process. Hardened derivation is used at this level. ## Rationale The existing convention is to use the 'Ethereum' coin type, leading to paths starting with `m/44'/60'/*`. Because this still assumes a UTXO-based coin, we contend that this is a poor fit, resulting in standardisation, usability, and security compromises. As a result, we are making the above proposal to define an entirely new hierarchy for Ethereum-based chains. ## Backwards Compatibility The introduction of another derivation path requires existing software to add support for this scheme in addition to any existing schemes. Given the already confused nature of wallet derivation paths in Ethereum, we anticipate this will cause relatively little additional disruption, and has the potential to improve matters significantly in the long run. ## Test Cases TBD ## Implementation None yet. ## References [This discussion on derivation paths](https://github.com/ethereum/EIPs/issues/84) ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Ethereum hierarchy for deterministic wallets

Thu, 13 Apr 2017 00:00:00 +0000

## Abstract This EIP defines a logical hierarchy for deterministic wallets based on [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki), the purpose scheme defined in [BIP43](https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki) and eip-draft-ethereum-purpose. This EIP is a particular application of eip-draft-ethereum-purpose. ## Motivation At present, different Ethereum clients and wallets use different derivation paths; a summary of them can be found [here](https://github.com/ethereum/EIPs/issues/84#issuecomment-292324521). Some of these paths violate BIP44, the standard defining derivation paths starting with `m/44'/`. This creates confusion and incompatibility between wallet implementations, in some cases making funds from one wallet inaccessible on another, and in others requiring prompting users manually for a derivation path, which hinders usability. Further, BIP44 was designed with UTXO-based blockchains in mind, and is a poor fit for Ethereum, which uses an accounts abstraction instead. As an alternative, we propose a deterministic wallet hierarchy better tailored to Ethereum's unique requirements. ## Specification We define the following 4 levels in BIP32 path:

m / purpose' / subpurpose' / EIP' / wallet'

Apostrophe in the path indicates that BIP32 hardened derivation is used. Each level has a special meaning, described in the chapters below. ### Purpose Purpose is a constant set to 43, indicating the key derivation is for a non-bitcoin cryptocurrency. Hardened derivation is used at this level. ### Subpurpose Subpurpose is set to 60, the SLIP-44 code for Ethereum. Hardened derivation is used at this level. ### EIP EIP is set to the EIP number specifying the remainder of the BIP32 derivation path. For paths following this EIP specification, the number assigned to this EIP is used. Hardened derivation is used at this level. ### Wallet This component of the path splits the wallet into different user identities, allowing a single wallet to have multiple public identities. Accounts are numbered from index 0 in sequentially increasing manner. This number is used as child index in BIP32 derivation. Hardened derivation is used at this level. Software should prevent a creation of an account if a previous account does not have a transaction history (meaning its address has not been used before). Software needs to discover all used accounts after importing the seed from an external source. ## Rationale The existing convention is to use the 'Ethereum' coin type, leading to paths starting with `m/44'/60'/*`. Because this still assumes a UTXO-based coin, we contend that this is a poor fit, resulting in standardisation, usability, and security compromises. As a result, we are making the above proposal to define an entirely new hierarchy for Ethereum-based chains. ## Backwards Compatibility The introduction of another derivation path requires existing software to add support for this scheme in addition to any existing schemes. Given the already confused nature of wallet derivation paths in Ethereum, we anticipate this will cause relatively little additional disruption, and has the potential to improve matters significantly in the long run. For applications that utilise mnemonics, the authors expect to submit another EIP draft that describes a method for avoiding backwards compatibility concerns when transitioning to this new derivation path. ## Test Cases TBD ## Implementation None yet. ## References [This discussion on derivation paths](https://github.com/ethereum/EIPs/issues/84) ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Storage of text records in ENS

Wed, 17 May 2017 00:00:00 +0000

## Abstract This EIP defines a resolver profile for ENS that permits the lookup of arbitrary key-value text data. This allows ENS name holders to associate e-mail addresses, URLs and other informational data with a ENS name. ## Motivation There is often a desire for human-readable metadata to be associated with otherwise machine-driven data; used for debugging, maintenance, reporting and general information. In this EIP we define a simple resolver profile for ENS that permits ENS names to associate arbitrary key-value text. ## Specification ### Resolver Profile A new resolver interface is defined, consisting of the following method: ```solidity interface IERC634 { /// @notice Returns the text data associated with a key for an ENS name /// @param node A nodehash for an ENS name /// @param key A key to lookup text data for /// @return The text data function text(bytes32 node, string key) view returns (string text); } ``` The [EIP-165](./eip-165.md) interface ID of this interface is `0x59d1d43c`. The `text` data may be any arbitrary UTF-8 string. If the key is not present, the empty string must be returned. ### Global Keys Global Keys must be made up of lowercase letters, numbers and the hyphen (-). - **avatar** - a URL to an image used as an avatar or logo - **description** - A description of the name - **display** - a canonical display name for the ENS name; this MUST match the ENS name when its case is folded, and clients should ignore this value if it does not (e.g. `"ricmoo.eth"` could set this to `"RicMoo.eth"`) - **email** - an e-mail address - **keywords** - A list of comma-separated keywords, ordered by most significant first; clients that interpresent this field may choose a threshold beyond which to ignore - **mail** - A physical mailing address - **notice** - A notice regarding this name - **location** - A generic location (e.g. `"Toronto, Canada"`) - **phone** - A phone number as an E.164 string - **url** - a website URL ### Service Keys Service Keys must be made up of a *reverse dot notation* for a namespace which the service owns, for example, DNS names (e.g. `.com`, `.io`, etc) or ENS name (i.e. `.eth`). Service Keys must contain at least one dot. This allows new services to start using their own keys without worrying about colliding with existing services and also means new services do not need to update this document. The following services are common, which is why recommendations are provided here, but ideally a service would declare its own key. - **com.github** - a GitHub username - **com.peepeth** - a Peepeth username - **com.linkedin** - a LinkedIn username - **com.twitter** - a Twitter username - **io.keybase** - a Keybase username - **org.telegram** - a Telegram username This technique also allows for a service owner to specify a hierarchy for their keys, such as: - **com.example.users** - **com.example.groups** - **com.example.groups.public** - **com.example.groups.private** ### Legacy Keys The following keys were specified in earlier versions of this EIP, which is still in draft. Their use is not likely very wide, but applications attempting maximal compatibility may wish to query these keys as a fallback if the above replacement keys fail. - **vnd.github** - a GitHub username (renamed to `com.github`) - **vnd.peepeth** - a peepeth username (renamced to `com.peepeth`) - **vnd.twitter** - a twitter username (renamed to `com.twitter`) ## Rationale ### Application-specific vs general-purpose record types Rather than define a large number of specific record types (each for generally human-readable data) such as `url` and `email`, we follow an adapted model of DNS's `TXT` records, which allow for a general keys and values, allowing future extension without adjusting the resolver, while allowing applications to use custom keys for their own purposes. ## Backwards Compatibility Not applicable. ## Security Considerations None. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

URL Format for Transaction Requests

Tue, 01 Aug 2017 00:00:00 +0000

## Simple Summary A standard way of representing various transactions, especially payment requests in ether and [ERC-20](./eip-20.md) tokens as URLs. ## Abstract URLs embedded in QR-codes, hyperlinks in web-pages, emails or chat messages provide for robust cross-application signaling between very loosely coupled applications. A standardized URL format for payment requests allows for instant invocation of the user's preferred wallet application (even if it is a webapp or a swarm đapp), with the correct parameterization of the payment transaction only to be confirmed by the (authenticated) user. ## Motivation The convenience of representing payment requests by standard URLs has been a major factor in the wide adoption of Bitcoin. Bringing a similarly convenient mechanism to Ethereum would speed up its acceptance as a payment platform among end-users. In particular, URLs embedded in broadcast Intents are the preferred way of launching applications on the Android operating system and work across practically all applications. Desktop web browsers have a standardized way of defining protocol handlers for URLs with specific protocol specifications. Other desktop applications typically launch the web browser upon encountering a URL. Thus, payment request URLs could be delivered through a very broad, ever growing selection of channels. This specification supersedes the defunct ERC-67, which is a URL format for representing arbitrary transactions in a low-level fashion. This ERC focuses specifically on the important special case of payment requests, while allowing for other, ABI-specified transactions. ## Specification ### Syntax Payment request URLs contain "ethereum" in their schema (protocol) part and are constructed as follows: request = schema_prefix target_address [ "@" chain_id ] [ "/" function_name ] [ "?" parameters ] schema_prefix = "ethereum" ":" [ "pay-" ] target_address = ethereum_address chain_id = 1*DIGIT function_name = STRING ethereum_address = ( "0x" 40*HEXDIG ) / ENS_NAME parameters = parameter *( "&" parameter ) parameter = key "=" value key = "value" / "gas" / "gasLimit" / "gasPrice" / TYPE value = number / ethereum_address / STRING number = [ "-" / "+" ] *DIGIT [ "." 1*DIGIT ] [ ( "e" / "E" ) [ 1*DIGIT ] ] Where `TYPE` is a standard ABI type name, as defined in [Ethereum Contract ABI specification](https://solidity.readthedocs.io/en/develop/abi-spec.html). `STRING` is a URL-encoded unicode string of arbitrary length, where delimiters and the percentage symbol (`%`) are mandatorily hex-encoded with a `%` prefix. Note that a `number` can be expressed in *scientific notation*, with a multiplier of a power of 10. Only integer numbers are allowed, so the exponent MUST be greater or equal to the number of decimals after the point. If *key* in the parameter list is `value`, `gasLimit`, `gasPrice` or `gas` then *value* MUST be a `number`. Otherwise, it must correspond to the `TYPE` string used as *key*. For the syntax of ENS_NAME, please consult [ERC-137](./eip-137.md) defining Ethereum Name Service. ### Semantics `target_address` is mandatory and denotes either the beneficiary of native token payment (see below) or the contract address with which the user is asked to interact. `chain_id` is optional and contains the decimal chain ID, such that transactions on various test- and private networks can be requested. If no `chain_id` is present, the client's current network setting remains effective. If `function_name` is missing, then the URL is requesting payment in the native token of the blockchain, which is ether in our case. The amount is specified in `value` parameter, in the atomic unit (i.e. wei). The use of scientific notation is strongly encouraged. For example, requesting 2.014 ETH to address `0xfb6916095ca1df60bb79Ce92ce3ea74c37c5d359` would look as follows: [ethereum:0xfb6916095ca1df60bb79Ce92ce3ea74c37c5d359?value=2.014e18](ethereum:0xfb6916095ca1df60bb79Ce92ce3ea74c37c5d359?value=2.014e18) Requesting payments in [ERC-20](./eip-20.md) tokens involves a request to call the `transfer` function of the token contract with an `address` and a `uint256` typed parameter, containing the *beneficiary address* and the *amount in atomic units*, respectively. For example, requesting a Unicorn to address `0x8e23ee67d1332ad560396262c48ffbb01f93d052` looks as follows: [ethereum:0x89205a3a3b2a69de6dbf7f01ed13b2108b2c43e7/transfer?address=0x8e23ee67d1332ad560396262c48ffbb01f93d052&uint256=1](ethereum:0x89205a3a3b2a69de6dbf7f01ed13b2108b2c43e7/transfer?address=0x8e23ee67d1332ad560396262c48ffbb01f93d052&uint256=1) If using ENS names instead of hexadecimal addresses, the resolution is up to the payer, at any time between receiving the URL and sending the transaction. Hexadecimal addresses always take precedence over ENS names, i. e. even if there exists a matching ENS name consisting of `0x` followed by 40 hexadecimal digits, it should never be resolved. Instead, the hexadecimal address should be used directly. Note that the indicated amount is only a suggestion (as are all the supplied arguments) which the user is free to change. With no indicated amount, the user should be prompted to enter the amount to be paid. Similarly `gasLimit` and `gasPrice` are suggested user-editable values for *gas limit* and *gas price*, respectively, for the requested transaction. It is acceptable to abbreviate `gasLimit` as `gas`, the two are treated synonymously. ## Rationale The proposed format is chosen to resemble `bitcoin:` URLs as closely as possible, as both users and application programmers are already familiar with that format. In particular, this motivated the omission of the unit, which is often used in Ethereum ecosystem. Handling different orders of magnitude is facilitated by the exponent so that amount values can be expressed in their nominal units, just like in the case of `bitcoin:`. The use of scientific notation is strongly encouraged when expressing monetary value in ether or [ERC-20](./eip-20.md) tokens. For better human readability, the exponent should be the decimal value of the nominal unit: 18 for ether or the value returned by `decimals()` of the token contract for [ERC-20](./eip-20.md) tokens. Additional parameters may be added, if popular use cases requiring them emerge in practice. The `0x` prefix before ethereum addresses specified as hexadecimal numbers is following established practice and also unambiguously distinguishes hexadecimal addresses from ENS names consisting of 40 alphanumeric characters. Future upgrades that are partially or fully incompatible with this proposal must use a prefix other than `pay-` that is separated by a dash (`-`) character from whatever follows it. ## Backwards Compatibility In the fairly common case of only indicating the recipient address in a request for payment in ether, this specification is compatible with the superseded ERC-67. ## Security Considerations Since irreversible transactions can be initiated with parameters from such URLs, the integrity and authenticity of these URLs are of great importance. In particular, changing either the recipient address or the amount transferred can be a profitable attack. Users should only use URLs received from authenticated sources with adequate integrity protection. To prevent malicious redirection of payments using ENS, hexadecimal interpretation of Ethereum addresses must have precedence over ENS lookups. Client software may alert the user if an ENS address is visually similar to a hexadecimal address or even outright reject such addresses as likely phishing attacks. In order to make sure that the amount transacted is the same as the amount intended, the amount communicated to the human user should be easily verifiable by inspection, including the order of magnitude. In case of [ERC-20](./eip-20.md) token payments, if the payer client has access to the blockchain or some other trusted source of information about the token contract, the interface should display the amount in the units specified in the token contract. Otherwise, it should be displayed as expressed in the URL, possibly alerting the user to the uncertainty of the nominal unit. To facilitate human inspection of the amount, the use of scientific notation with an exponent corresponding to the nominal unit of the transacted token (e.g. 18 in case of ether) is advisable. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Non-Fungible Token Standard

Wed, 24 Jan 2018 00:00:00 +0000

## Simple Summary A standard interface for non-fungible tokens, also known as deeds. ## Abstract The following standard allows for the implementation of a standard API for NFTs within smart contracts. This standard provides basic functionality to track and transfer NFTs. We considered use cases of NFTs being owned and transacted by individuals as well as consignment to third party brokers/wallets/auctioneers ("operators"). NFTs can represent ownership over digital or physical assets. We considered a diverse universe of assets, and we know you will dream up many more: - Physical property — houses, unique artwork - Virtual collectibles — unique pictures of kittens, collectible cards - "Negative value" assets — loans, burdens and other responsibilities In general, all houses are distinct and no two kittens are alike. NFTs are *distinguishable* and you must track the ownership of each one separately. ## Motivation A standard interface allows wallet/broker/auction applications to work with any NFT on Ethereum. We provide for simple ERC-721 smart contracts as well as contracts that track an *arbitrarily large* number of NFTs. Additional applications are discussed below. This standard is inspired by the ERC-20 token standard and builds on two years of experience since EIP-20 was created. EIP-20 is insufficient for tracking NFTs because each asset is distinct (non-fungible) whereas each of a quantity of tokens is identical (fungible). Differences between this standard and EIP-20 are examined below. ## Specification The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. **Every ERC-721 compliant contract must implement the `ERC721` and `ERC165` interfaces** (subject to "caveats" below): ```solidity pragma solidity ^0.4.20; /// @title ERC-721 Non-Fungible Token Standard /// @dev See https://eips.ethereum.org/EIPS/eip-721 /// Note: the ERC-165 identifier for this interface is 0x80ac58cd. interface ERC721 /* is ERC165 */ { /// @dev This emits when ownership of any NFT changes by any mechanism. /// This event emits when NFTs are created (`from` == 0) and destroyed /// (`to` == 0). Exception: during contract creation, any number of NFTs /// may be created and assigned without emitting Transfer. At the time of /// any transfer, the approved address for that NFT (if any) is reset to none. event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId); /// @dev This emits when the approved address for an NFT is changed or /// reaffirmed. The zero address indicates there is no approved address. /// When a Transfer event emits, this also indicates that the approved /// address for that NFT (if any) is reset to none. event Approval(address indexed _owner, address indexed _approved, uint256 indexed _tokenId); /// @dev This emits when an operator is enabled or disabled for an owner. /// The operator can manage all NFTs of the owner. event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved); /// @notice Count all NFTs assigned to an owner /// @dev NFTs assigned to the zero address are considered invalid, and this /// function throws for queries about the zero address. /// @param _owner An address for whom to query the balance /// @return The number of NFTs owned by `_owner`, possibly zero function balanceOf(address _owner) external view returns (uint256); /// @notice Find the owner of an NFT /// @dev NFTs assigned to zero address are considered invalid, and queries /// about them do throw. /// @param _tokenId The identifier for an NFT /// @return The address of the owner of the NFT function ownerOf(uint256 _tokenId) external view returns (address); /// @notice Transfers the ownership of an NFT from one address to another address /// @dev Throws unless `msg.sender` is the current owner, an authorized /// operator, or the approved address for this NFT. Throws if `_from` is /// not the current owner. Throws if `_to` is the zero address. Throws if /// `_tokenId` is not a valid NFT. When transfer is complete, this function /// checks if `_to` is a smart contract (code size > 0). If so, it calls /// `onERC721Received` on `_to` and throws if the return value is not /// `bytes4(keccak256("onERC721Received(address,address,uint256,bytes)"))`. /// @param _from The current owner of the NFT /// @param _to The new owner /// @param _tokenId The NFT to transfer /// @param data Additional data with no specified format, sent in call to `_to` function safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes data) external payable; /// @notice Transfers the ownership of an NFT from one address to another address /// @dev This works identically to the other function with an extra data parameter, /// except this function just sets data to "". /// @param _from The current owner of the NFT /// @param _to The new owner /// @param _tokenId The NFT to transfer function safeTransferFrom(address _from, address _to, uint256 _tokenId) external payable; /// @notice Transfer ownership of an NFT -- THE CALLER IS RESPONSIBLE /// TO CONFIRM THAT `_to` IS CAPABLE OF RECEIVING NFTS OR ELSE /// THEY MAY BE PERMANENTLY LOST /// @dev Throws unless `msg.sender` is the current owner, an authorized /// operator, or the approved address for this NFT. Throws if `_from` is /// not the current owner. Throws if `_to` is the zero address. Throws if /// `_tokenId` is not a valid NFT. /// @param _from The current owner of the NFT /// @param _to The new owner /// @param _tokenId The NFT to transfer function transferFrom(address _from, address _to, uint256 _tokenId) external payable; /// @notice Change or reaffirm the approved address for an NFT /// @dev The zero address indicates there is no approved address. /// Throws unless `msg.sender` is the current NFT owner, or an authorized /// operator of the current owner. /// @param _approved The new approved NFT controller /// @param _tokenId The NFT to approve function approve(address _approved, uint256 _tokenId) external payable; /// @notice Enable or disable approval for a third party ("operator") to manage /// all of `msg.sender`'s assets /// @dev Emits the ApprovalForAll event. The contract MUST allow /// multiple operators per owner. /// @param _operator Address to add to the set of authorized operators /// @param _approved True if the operator is approved, false to revoke approval function setApprovalForAll(address _operator, bool _approved) external; /// @notice Get the approved address for a single NFT /// @dev Throws if `_tokenId` is not a valid NFT. /// @param _tokenId The NFT to find the approved address for /// @return The approved address for this NFT, or the zero address if there is none function getApproved(uint256 _tokenId) external view returns (address); /// @notice Query if an address is an authorized operator for another address /// @param _owner The address that owns the NFTs /// @param _operator The address that acts on behalf of the owner /// @return True if `_operator` is an approved operator for `_owner`, false otherwise function isApprovedForAll(address _owner, address _operator) external view returns (bool); } interface ERC165 { /// @notice Query if a contract implements an interface /// @param interfaceID The interface identifier, as specified in ERC-165 /// @dev Interface identification is specified in ERC-165. This function /// uses less than 30,000 gas. /// @return `true` if the contract implements `interfaceID` and /// `interfaceID` is not 0xffffffff, `false` otherwise function supportsInterface(bytes4 interfaceID) external view returns (bool); } ``` A wallet/broker/auction application MUST implement the **wallet interface** if it will accept safe transfers. ```solidity /// @dev Note: the ERC-165 identifier for this interface is 0x150b7a02. interface ERC721TokenReceiver { /// @notice Handle the receipt of an NFT /// @dev The ERC721 smart contract calls this function on the recipient /// after a `transfer`. This function MAY throw to revert and reject the /// transfer. Return of other than the magic value MUST result in the /// transaction being reverted. /// Note: the contract address is always the message sender. /// @param _operator The address which called `safeTransferFrom` function /// @param _from The address which previously owned the token /// @param _tokenId The NFT identifier which is being transferred /// @param _data Additional data with no specified format /// @return `bytes4(keccak256("onERC721Received(address,address,uint256,bytes)"))` /// unless throwing function onERC721Received(address _operator, address _from, uint256 _tokenId, bytes _data) external returns(bytes4); } ``` The **metadata extension** is OPTIONAL for ERC-721 smart contracts (see "caveats", below). This allows your smart contract to be interrogated for its name and for details about the assets which your NFTs represent. ```solidity /// @title ERC-721 Non-Fungible Token Standard, optional metadata extension /// @dev See https://eips.ethereum.org/EIPS/eip-721 /// Note: the ERC-165 identifier for this interface is 0x5b5e139f. interface ERC721Metadata /* is ERC721 */ { /// @notice A descriptive name for a collection of NFTs in this contract function name() external view returns (string _name); /// @notice An abbreviated name for NFTs in this contract function symbol() external view returns (string _symbol); /// @notice A distinct Uniform Resource Identifier (URI) for a given asset. /// @dev Throws if `_tokenId` is not a valid NFT. URIs are defined in RFC /// 3986. The URI may point to a JSON file that conforms to the "ERC721 /// Metadata JSON Schema". function tokenURI(uint256 _tokenId) external view returns (string); } ``` This is the "ERC721 Metadata JSON Schema" referenced above. ```json { "title": "Asset Metadata", "type": "object", "properties": { "name": { "type": "string", "description": "Identifies the asset to which this NFT represents" }, "description": { "type": "string", "description": "Describes the asset to which this NFT represents" }, "image": { "type": "string", "description": "A URI pointing to a resource with mime type image/* representing the asset to which this NFT represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive." } } } ``` The **enumeration extension** is OPTIONAL for ERC-721 smart contracts (see "caveats", below). This allows your contract to publish its full list of NFTs and make them discoverable. ```solidity /// @title ERC-721 Non-Fungible Token Standard, optional enumeration extension /// @dev See https://eips.ethereum.org/EIPS/eip-721 /// Note: the ERC-165 identifier for this interface is 0x780e9d63. interface ERC721Enumerable /* is ERC721 */ { /// @notice Count NFTs tracked by this contract /// @return A count of valid NFTs tracked by this contract, where each one of /// them has an assigned and queryable owner not equal to the zero address function totalSupply() external view returns (uint256); /// @notice Enumerate valid NFTs /// @dev Throws if `_index` >= `totalSupply()`. /// @param _index A counter less than `totalSupply()` /// @return The token identifier for the `_index`th NFT, /// (sort order not specified) function tokenByIndex(uint256 _index) external view returns (uint256); /// @notice Enumerate NFTs assigned to an owner /// @dev Throws if `_index` >= `balanceOf(_owner)` or if /// `_owner` is the zero address, representing invalid NFTs. /// @param _owner An address where we are interested in NFTs owned by them /// @param _index A counter less than `balanceOf(_owner)` /// @return The token identifier for the `_index`th NFT assigned to `_owner`, /// (sort order not specified) function tokenOfOwnerByIndex(address _owner, uint256 _index) external view returns (uint256); } ``` ### Caveats The 0.4.20 Solidity interface grammar is not expressive enough to document the ERC-721 standard. A contract which complies with ERC-721 MUST also abide by the following: - Solidity issue #3412: The above interfaces include explicit mutability guarantees for each function. Mutability guarantees are, in order weak to strong: `payable`, implicit nonpayable, `view`, and `pure`. Your implementation MUST meet the mutability guarantee in this interface and you MAY meet a stronger guarantee. For example, a `payable` function in this interface may be implemented as nonpayable (no state mutability specified) in your contract. We expect a later Solidity release will allow your stricter contract to inherit from this interface, but a workaround for version 0.4.20 is that you can edit this interface to add stricter mutability before inheriting from your contract. - Solidity issue #3419: A contract that implements `ERC721Metadata` or `ERC721Enumerable` SHALL also implement `ERC721`. ERC-721 implements the requirements of interface ERC-165. - Solidity issue #2330: If a function is shown in this specification as `external` then a contract will be compliant if it uses `public` visibility. As a workaround for version 0.4.20, you can edit this interface to switch to `public` before inheriting from your contract. - Solidity issues #3494, #3544: Use of `this.*.selector` is marked as a warning by Solidity, a future version of Solidity will not mark this as an error. *If a newer version of Solidity allows the caveats to be expressed in code, then this EIP MAY be updated and the caveats removed, such will be equivalent to the original specification.* ## Rationale There are many proposed uses of Ethereum smart contracts that depend on tracking distinguishable assets. Examples of existing or planned NFTs are LAND in Decentraland, the eponymous punks in CryptoPunks, and in-game items using systems like DMarket or EnjinCoin. Future uses include tracking real-world assets, like real-estate (as envisioned by companies like Ubitquity or Propy). It is critical in each of these cases that these items are not "lumped together" as numbers in a ledger, but instead each asset must have its ownership individually and atomically tracked. Regardless of the nature of these assets, the ecosystem will be stronger if we have a standardized interface that allows for cross-functional asset management and sales platforms. **"NFT" Word Choice** "NFT" was satisfactory to nearly everyone surveyed and is widely applicable to a broad universe of distinguishable digital assets. We recognize that "deed" is very descriptive for certain applications of this standard (notably, physical property). *Alternatives considered: distinguishable asset, title, token, asset, equity, ticket* **NFT Identifiers** Every NFT is identified by a unique `uint256` ID inside the ERC-721 smart contract. This identifying number SHALL NOT change for the life of the contract. The pair `(contract address, uint256 tokenId)` will then be a globally unique and fully-qualified identifier for a specific asset on an Ethereum chain. While some ERC-721 smart contracts may find it convenient to start with ID 0 and simply increment by one for each new NFT, callers SHALL NOT assume that ID numbers have any specific pattern to them, and MUST treat the ID as a "black box". Also note that NFTs MAY become invalid (be destroyed). Please see the enumeration functions for a supported enumeration interface. The choice of `uint256` allows a wide variety of applications because UUIDs and sha3 hashes are directly convertible to `uint256`. **Transfer Mechanism** ERC-721 standardizes a safe transfer function `safeTransferFrom` (overloaded with and without a `bytes` parameter) and an unsafe function `transferFrom`. Transfers may be initiated by: - The owner of an NFT - The approved address of an NFT - An authorized operator of the current owner of an NFT Additionally, an authorized operator may set the approved address for an NFT. This provides a powerful set of tools for wallet, broker and auction applications to quickly use a *large* number of NFTs. The transfer and accept functions' documentation only specify conditions when the transaction MUST throw. Your implementation MAY also throw in other situations. This allows implementations to achieve interesting results: - **Disallow transfers if the contract is paused** — prior art, CryptoKitties deployed contract, line 611 - **Blocklist certain address from receiving NFTs** — prior art, CryptoKitties deployed contract, lines 565, 566 - **Disallow unsafe transfers** — `transferFrom` throws unless `_to` equals `msg.sender` or `countOf(_to)` is non-zero or was non-zero previously (because such cases are safe) - **Charge a fee to both parties of a transaction** — require payment when calling `approve` with a non-zero `_approved` if it was previously the zero address, refund payment if calling `approve` with the zero address if it was previously a non-zero address, require payment when calling any transfer function, require transfer parameter `_to` to equal `msg.sender`, require transfer parameter `_to` to be the approved address for the NFT - **Read only NFT registry** — always throw from `safeTransferFrom`, `transferFrom`, `approve` and `setApprovalForAll` Failed transactions will throw, a best practice identified in ERC-223, ERC-677, ERC-827 and OpenZeppelin's implementation of SafeERC20.sol. ERC-20 defined an `allowance` feature, this caused a problem when called and then later modified to a different amount, as on OpenZeppelin issue \#438. In ERC-721, there is no allowance because every NFT is unique, the quantity is none or one. Therefore we receive the benefits of ERC-20's original design without problems that have been later discovered. Creation of NFTs ("minting") and destruction of NFTs ("burning") is not included in the specification. Your contract may implement these by other means. Please see the `event` documentation for your responsibilities when creating or destroying NFTs. We questioned if the `operator` parameter on `onERC721Received` was necessary. In all cases we could imagine, if the operator was important then that operator could transfer the token to themself and then send it -- then they would be the `from` address. This seems contrived because we consider the operator to be a temporary owner of the token (and transferring to themself is redundant). When the operator sends the token, it is the operator acting on their own accord, NOT the operator acting on behalf of the token holder. This is why the operator and the previous token owner are both significant to the token recipient. *Alternatives considered: only allow two-step ERC-20 style transaction, require that transfer functions never throw, require all functions to return a boolean indicating the success of the operation.* **ERC-165 Interface** We chose Standard Interface Detection (ERC-165) to expose the interfaces that a ERC-721 smart contract supports. A future EIP may create a global registry of interfaces for contracts. We strongly support such an EIP and it would allow your ERC-721 implementation to implement `ERC721Enumerable`, `ERC721Metadata`, or other interfaces by delegating to a separate contract. **Gas and Complexity** (regarding the enumeration extension) This specification contemplates implementations that manage a few and *arbitrarily large* numbers of NFTs. If your application is able to grow then avoid using for/while loops in your code (see CryptoKitties bounty issue \#4). These indicate your contract may be unable to scale and gas costs will rise over time without bound. We have deployed a contract, XXXXERC721, to Testnet which instantiates and tracks 340282366920938463463374607431768211456 different deeds (2^128). That's enough to assign every IPV6 address to an Ethereum account owner, or to track ownership of nanobots a few micron in size and in aggregate totalling half the size of Earth. You can query it from the blockchain. And every function takes less gas than querying the ENS. This illustration makes clear: the ERC-721 standard scales. *Alternatives considered: remove the asset enumeration function if it requires a for-loop, return a Solidity array type from enumeration functions.* **Privacy** Wallets/brokers/auctioneers identified in the motivation section have a strong need to identify which NFTs an owner owns. It may be interesting to consider a use case where NFTs are not enumerable, such as a private registry of property ownership, or a partially-private registry. However, privacy cannot be attained because an attacker can simply (!) call `ownerOf` for every possible `tokenId`. **Metadata Choices** (metadata extension) We have required `name` and `symbol` functions in the metadata extension. Every token EIP and draft we reviewed (ERC-20, ERC-223, ERC-677, ERC-777, ERC-827) included these functions. We remind implementation authors that the empty string is a valid response to `name` and `symbol` if you protest to the usage of this mechanism. We also remind everyone that any smart contract can use the same name and symbol as *your* contract. How a client may determine which ERC-721 smart contracts are well-known (canonical) is outside the scope of this standard. A mechanism is provided to associate NFTs with URIs. We expect that many implementations will take advantage of this to provide metadata for each NFT. The image size recommendation is taken from Instagram, they probably know much about image usability. The URI MAY be mutable (i.e. it changes from time to time). We considered an NFT representing ownership of a house, in this case metadata about the house (image, occupants, etc.) can naturally change. Metadata is returned as a string value. Currently this is only usable as calling from `web3`, not from other contracts. This is acceptable because we have not considered a use case where an on-blockchain application would query such information. *Alternatives considered: put all metadata for each asset on the blockchain (too expensive), use URL templates to query metadata parts (URL templates do not work with all URL schemes, especially P2P URLs), multiaddr network address (not mature enough)* **Community Consensus** A significant amount of discussion occurred on the original ERC-721 issue, additionally we held a first live meeting on Gitter that had good representation and well advertised (on Reddit, in the Gitter #ERC channel, and the original ERC-721 issue). Thank you to the participants: - [@ImAllInNow](https://github.com/imallinnow) Rob from DEC Gaming / Presenting Michigan Ethereum Meetup Feb 7 - [@Arachnid](https://github.com/arachnid) Nick Johnson - [@jadhavajay](https://github.com/jadhavajay) Ajay Jadhav from AyanWorks - [@superphly](https://github.com/superphly) Cody Marx Bailey - XRAM Capital / Sharing at hackathon Jan 20 / UN Future of Finance Hackathon. - [@fulldecent](https://github.com/fulldecent) William Entriken A second event was held at ETHDenver 2018 to discuss distinguishable asset standards (notes to be published). We have been very inclusive in this process and invite anyone with questions or contributions into our discussion. However, this standard is written only to support the identified use cases which are listed herein. ## Backwards Compatibility We have adopted `balanceOf`, `totalSupply`, `name` and `symbol` semantics from the ERC-20 specification. An implementation may also include a function `decimals` that returns `uint8(0)` if its goal is to be more compatible with ERC-20 while supporting this standard. However, we find it contrived to require all ERC-721 implementations to support the `decimals` function. Example NFT implementations as of February 2018: - CryptoKitties -- Compatible with an earlier version of this standard. - CryptoPunks -- Partially ERC-20 compatible, but not easily generalizable because it includes auction functionality directly in the contract and uses function names that explicitly refer to the assets as "punks". - Auctionhouse Asset Interface -- The author needed a generic interface for the Auctionhouse ÐApp (currently ice-boxed). His "Asset" contract is very simple, but is missing ERC-20 compatibility, `approve()` functionality, and metadata. This effort is referenced in the discussion for EIP-173. Note: "Limited edition, collectible tokens" like Curio Cards and Rare Pepe are *not* distinguishable assets. They're actually a collection of individual fungible tokens, each of which is tracked by its own smart contract with its own total supply (which may be `1` in extreme cases). The `onERC721Received` function specifically works around old deployed contracts which may inadvertently return 1 (`true`) in certain circumstances even if they don't implement a function (see Solidity DelegateCallReturnValue bug). By returning and checking for a magic value, we are able to distinguish actual affirmative responses versus these vacuous `true`s. ## Test Cases 0xcert ERC-721 Token includes test cases written using Truffle. ## Implementations 0xcert ERC721 -- a reference implementation - MIT licensed, so you can freely use it for your projects - Includes test cases - Active bug bounty, you will be paid if you find errors Su Squares -- an advertising platform where you can rent space and place images - Complete the Su Squares Bug Bounty Program to seek problems with this standard or its implementation - Implements the complete standard and all optional interfaces ERC721ExampleDeed -- an example implementation - Implements using the OpenZeppelin project format XXXXERC721, by William Entriken -- a scalable example implementation - Deployed on testnet with 1 billion assets and supporting all lookups with the metadata extension. This demonstrates that scaling is NOT a problem. ## References **Standards** 1. [ERC-20](./eip-20.md) Token Standard. 1. [ERC-165](./eip-165.md) Standard Interface Detection. 1. [ERC-173](./eip-173.md) Owned Standard. 1. [ERC-223](https://github.com/ethereum/EIPs/issues/223) Token Standard. 1. [ERC-677](https://github.com/ethereum/EIPs/issues/677) `transferAndCall` Token Standard. 1. [ERC-827](https://github.com/ethereum/EIPs/issues/827) Token Standard. 1. Ethereum Name Service (ENS). https://ens.domains 1. Instagram -- What's the Image Resolution? https://help.instagram.com/1631821640426723 1. JSON Schema. https://json-schema.org/ 1. Multiaddr. https://github.com/multiformats/multiaddr 1. RFC 2119 Key words for use in RFCs to Indicate Requirement Levels. https://www.ietf.org/rfc/rfc2119.txt **Issues** 1. The Original ERC-721 Issue. https://github.com/ethereum/eips/issues/721 1. Solidity Issue \#2330 -- Interface Functions are External. https://github.com/ethereum/solidity/issues/2330 1. Solidity Issue \#3412 -- Implement Interface: Allow Stricter Mutability. https://github.com/ethereum/solidity/issues/3412 1. Solidity Issue \#3419 -- Interfaces Can't Inherit. https://github.com/ethereum/solidity/issues/3419 1. Solidity Issue \#3494 -- Compiler Incorrectly Reasons About the `selector` Function. https://github.com/ethereum/solidity/issues/3494 1. Solidity Issue \#3544 -- Cannot Calculate Selector of Function Named `transfer`. https://github.com/ethereum/solidity/issues/3544 1. CryptoKitties Bounty Issue \#4 -- Listing all Kitties Owned by a User is `O(n^2)`. https://github.com/axiomzen/cryptokitties-bounty/issues/4 1. OpenZeppelin Issue \#438 -- Implementation of `approve` method violates ERC20 standard. https://github.com/OpenZeppelin/zeppelin-solidity/issues/438 1. Solidity DelegateCallReturnValue Bug. https://solidity.readthedocs.io/en/develop/bugs.html#DelegateCallReturnValue **Discussions** 1. Reddit (announcement of first live discussion). https://www.reddit.com/r/ethereum/comments/7r2ena/friday_119_live_discussion_on_erc_nonfungible/ 1. Gitter #EIPs (announcement of first live discussion). https://gitter.im/ethereum/EIPs?at=5a5f823fb48e8c3566f0a5e7 1. ERC-721 (announcement of first live discussion). https://github.com/ethereum/eips/issues/721#issuecomment-358369377 1. ETHDenver 2018. https://ethdenver.com **NFT Implementations and Other Projects** 1. CryptoKitties. https://www.cryptokitties.co 1. 0xcert ERC-721 Token. https://github.com/0xcert/ethereum-erc721 1. Su Squares. https://tenthousandsu.com 1. Decentraland. https://decentraland.org 1. CryptoPunks. https://www.larvalabs.com/cryptopunks 1. DMarket. https://www.dmarket.io 1. Enjin Coin. https://enjincoin.io 1. Ubitquity. https://www.ubitquity.io 1. Propy. https://tokensale.propy.com 1. CryptoKitties Deployed Contract. https://etherscan.io/address/0x06012c8cf97bead5deae237070f9587f8e7a266d#code 1. Su Squares Bug Bounty Program. https://github.com/fulldecent/su-squares-bounty 1. XXXXERC721. https://github.com/fulldecent/erc721-example 1. ERC721ExampleDeed. https://github.com/nastassiasachs/ERC721ExampleDeed 1. Curio Cards. https://mycuriocards.com 1. Rare Pepe. https://rarepepewallet.com 1. Auctionhouse Asset Interface. https://github.com/dob/auctionhouse/blob/master/contracts/Asset.sol 1. [OpenZeppelin `SafeERC20.sol` Implementation](../assets/eip-721/SafeERC20.sol). ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

General data key/value store and execution

Mon, 02 Oct 2017 00:00:00 +0000

## Abstract The following describes two standards that allow for a generic data storage in a smart contract and a generic execution through a smart contract. These can be used separately or in conjunction and can serve as building blocks for smart contract accounts, upgradable metadata, and other means. ## Motivation The initial motivation came out of the need to create a smart contract account system that's flexible enough to be viable long-term but also defined enough to be standardized. They are a generic set of two standardized building blocks to be used in all forms of smart contracts. This standard consists of two sub-standards, a generic data key/value store (`ERC725Y`) and a generic execute function (`ERC725X`). Both of these in combination allow for a very flexible and long-lasting account system. The account version of `ERC725` is standardized under `LSP0-ERC725Account`. These standards (`ERC725` X and Y) can also be used separately as `ERC725Y` can be used to enhance NFTs and Token metadata or other types of smart contracts. `ERC725X` allows for a generic execution through a smart contract, functioning as an account or actor. ## Specification ### Ownership This contract is controlled by a single owner. The owner can be a smart contract or an external account. This standard requires [ERC-173](./eip-173.md) and SHOULD implement the functions: - `owner() view` - `transferOwnership(address newOwner)` And the event: - `OwnershipTransferred(address indexed previousOwner, address indexed newOwner)` --- ### `ERC725X` **`ERC725X`** interface id according to [ERC-165](./eip-165.md): `0x7545acac`. Smart contracts implementing the `ERC725X` standard MUST implement the [ERC-165](./eip-165.md) `supportsInterface(..)` function and MUST support the `ERC165` and `ERC725X` interface ids. ### `ERC725X` Methods Smart contracts implementing the `ERC725X` standard SHOULD implement all of the functions listed below: #### execute ```solidity function execute(uint256 operationType, address target, uint256 value, bytes memory data) external payable returns(bytes memory) ``` Function Selector: `0x44c028fe` Executes a call on any other smart contracts or address, transfers the blockchains native token, or deploys a new smart contract. _Parameters:_ - `operationType`: the operation type used to execute. - `target`: the smart contract or address to call. `target` will be unused if a contract is created (operation types 1 and 2). - `value`: the amount of native tokens to transfer (in Wei). - `data`: the call data, or the creation bytecode of the contract to deploy. _Requirements:_ - MUST only be called by the current owner of the contract. - MUST revert when the execution or the contract creation fails. - `target` SHOULD be address(0) in case of contract creation with `CREATE` and `CREATE2` (operation types 1 and 2). - `value` SHOULD be zero in case of `STATICCALL` or `DELEGATECALL` (operation types 3 and 4). _Returns:_ `bytes` , the returned data of the called function, or the address of the contract deployed (operation types 1 and 2). **Triggers Event:** [ContractCreated](#contractcreated), [Executed](#executed) The following `operationType` COULD exist: - `0` for `CALL` - `1` for `CREATE` - `2` for `CREATE2` - `3` for `STATICCALL` - `4` for `DELEGATECALL` - **NOTE** This is a potentially dangerous operation type Others may be added in the future. #### data parameter - For operationType, `CALL`, `STATICCALL` and `DELEGATECALL` the data field can be random bytes or an abi-encoded function call. - For operationType, `CREATE` the `data` field is the creation bytecode of the contract to deploy appended with the constructor argument(s) abi-encoded. - For operationType, `CREATE2` the `data` field is the creation bytecode of the contract to deploy appended with: 1. the constructor argument(s) abi-encoded 2. a `bytes32` salt. ``` data = + + ``` > See [EIP-1014: Skinny CREATE2](./eip-1014.md) for more information. #### executeBatch ```solidity function executeBatch(uint256[] memory operationsType, address[] memory targets, uint256[] memory values, bytes[] memory datas) external payable returns(bytes[] memory) ``` Function Selector: `0x31858452` Executes a batch of calls on any other smart contracts, transfers the blockchain native token, or deploys a new smart contract. _Parameters:_ - `operationsType`: the list of operations type used to execute. - `targets`: the list of addresses to call. `targets` will be unused if a contract is created (operation types 1 and 2). - `values`: the list of native token amounts to transfer (in Wei). - `datas`: the list of call data, or the creation bytecode of the contract to deploy. _Requirements:_ - Parameters array MUST have the same length. - MUST only be called by the current owner of the contract. - MUST revert when the execution or the contract creation fails. - `target` SHOULD be address(0) in case of contract creation with `CREATE` and `CREATE2` (operation types 1 and 2). - `value` SHOULD be zero in case of `STATICCALL` or `DELEGATECALL` (operation types 3 and 4). _Returns:_ `bytes[]` , array list of returned data of the called function, or the address(es) of the contract deployed (operation types 1 and 2). **Triggers Event:** [ContractCreated](#contractcreated), [Executed](#executed) on each call iteration ### `ERC725X` Events #### Executed ```solidity event Executed(uint256 indexed operationType, address indexed target, uint256 indexed value, bytes4 data); ``` MUST be triggered when `execute` creates a new call using the `operationType` `0`, `3`, `4`. #### ContractCreated ```solidity event ContractCreated(uint256 indexed operationType, address indexed contractAddress, uint256 indexed value, bytes32 salt); ``` MUST be triggered when `execute` creates a new contract using the `operationType` `1`, `2`. --- ### `ERC725Y` **`ERC725Y`** interface id according to [ERC-165](./eip-165.md): `0x629aa694`. Smart contracts implementing the `ERC725Y` standard MUST implement the [ERC-165](./eip-165.md) `supportsInterface(..)` function and MUST support the `ERC165` and `ERC725Y` interface ids. ### `ERC725Y` Methods Smart contracts implementing the `ERC725Y` standard MUST implement all of the functions listed below: #### getData ```solidity function getData(bytes32 dataKey) external view returns(bytes memory) ``` Function Selector: `0x54f6127f` Gets the data set for the given data key. _Parameters:_ - `dataKey`: the data key which value to retrieve. _Returns:_ `bytes` , The data for the requested data key. #### getDataBatch ```solidity function getDataBatch(bytes32[] memory dataKeys) external view returns(bytes[] memory) ``` Function Selector: `0xdedff9c6` Gets array of data at multiple given data keys. _Parameters:_ - `dataKeys`: the data keys which values to retrieve. _Returns:_ `bytes[]` , array of data values for the requested data keys. #### setData ```solidity function setData(bytes32 dataKey, bytes memory dataValue) external ``` Function Selector: `0x7f23690c` Sets data as bytes in the storage for a single data key. _Parameters:_ - `dataKey`: the data key which value to set. - `dataValue`: the data to store. _Requirements:_ - MUST only be called by the current owner of the contract. **Triggers Event:** [DataChanged](#datachanged) #### setDataBatch ```solidity function setDataBatch(bytes32[] memory dataKeys, bytes[] memory dataValues) external ``` Function Selector: `0x97902421` Sets array of data at multiple data keys. MUST only be called by the current owner of the contract. _Parameters:_ - `dataKeys`: the data keys which values to set. - `dataValues`: the array of bytes to set. _Requirements:_ - Array parameters MUST have the same length. - MUST only be called by the current owner of the contract. **Triggers Event:** [DataChanged](#datachanged) ### `ERC725Y` Events #### DataChanged ```solidity event DataChanged(bytes32 indexed dataKey, bytes dataValue) ``` MUST be triggered when a data key was successfully set. ### `ERC725Y` Data keys Data keys, are the way to retrieve values via `getData()`. These `bytes32` values can be freely chosen, or defined by a standard. A common way to define data keys is the hash of a word, e.g. `keccak256('ERCXXXMyNewKeyType')` which results in: `0x6935a24ea384927f250ee0b954ed498cd9203fc5d2bf95c735e52e6ca675e047` The `LSP2-ERC725JSONSchema` standard is a more explicit `ERC725Y` data key standard, that defines key types and value types, and their encoding and decoding. ## Rationale The generic way of storing data keys with values was chosen to allow upgradability over time. Stored data values can be changed over time. Other smart contract protocols can then interpret this data in new ways and react to interactions from a `ERC725` smart contract differently. The data stored in an `ERC725Y` smart contract is not only readable/writable by off-chain applications, but also by other smart contracts. Function overloading was used to allow for the retrievable of single and multiple keys, to keep gas costs minimal for both use cases. ## Backwards Compatibility All contracts since `ERC725v2` from 2018/19 should be compatible with the current version of the standard. Mainly interface ID and Event parameters have changed, while `getData(bytes32[])` and `setData(bytes32[], bytes[])` was added as an efficient way to set/get multiple keys at once. The same applies to execution, as `execute(..[])` was added as an efficient way to batch calls. From 2023 onward, overloading was removed from `ERC-725` (including `ERC725-X` and `ERC725-Y`). This is because, while overloading is accommodated in Solidity, it isn't broadly supported across most blockchain languages. In order to make the standard language-independent, it was decided to shift from overloading to simply attach the term "Batch" to the functions that accept an array as parameters. ## Reference Implementation Reference implementations can be found in [`ERC725.sol`](../assets/eip-725/ERC725.sol). ## Security Considerations This contract allows generic executions, therefore special care needs to be taken to prevent re-entrancy attacks and other forms of call chain attacks. When using the operation type `4` for `delegatecall`, it is important to consider that the called contracts can alter the state of the calling contract and also change owner variables and `ERC725Y` data storage entries at will. Additionally calls to `selfdestruct` are possible and other harmful state-changing operations. ### Solidity Interfaces ```solidity // SPDX-License-Identifier: CC0-1.0 pragma solidity >=0.5.0 <0.7.0; // ERC165 identifier: `0x7545acac` interface IERC725X /* is ERC165, ERC173 */ { event Executed(uint256 indexed operationType, address indexed target, uint256 indexed value, bytes4 data); event ContractCreated(uint256 indexed operationType, address indexed contractAddress, uint256 indexed value, bytes32 salt); function execute(uint256 operationType, address target, uint256 value, bytes memory data) external payable returns(bytes memory); function executeBatch(uint256[] memory operationsType, address[] memory targets, uint256[] memory values, bytes memory datas) external payable returns(bytes[] memory); } // ERC165 identifier: `0x629aa694` interface IERC725Y /* is ERC165, ERC173 */ { event DataChanged(bytes32 indexed dataKey, bytes dataValue); function getData(bytes32 dataKey) external view returns(bytes memory); function getDataBatch(bytes32[] memory dataKeys) external view returns(bytes[] memory); function setData(bytes32 dataKey, bytes memory dataValue) external; function setDataBatch(bytes32[] memory dataKeys, bytes[] memory dataValues) external; } interface IERC725 /* is IERC725X, IERC725Y */ { } ``` ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Token Standard

Mon, 20 Nov 2017 00:00:00 +0000

## Simple Summary This EIP defines standard interfaces and behaviors for token contracts. ## Abstract This standard defines a new way to interact with a token contract while remaining backward compatible with [ERC-20]. It defines advanced features to interact with tokens. Namely, *operators* to send tokens on behalf of another address—contract or regular account—and send/receive *hooks* to offer token holders more control over their tokens. It takes advantage of [ERC-1820] to find out whether and where to notify contracts and regular addresses when they receive tokens as well as to allow compatibility with already-deployed contracts. ## Motivation This standard tries to improve upon the widely used [ERC-20] token standard. The main advantages of this standard are: 1. Uses the same philosophy as Ether in that tokens are sent with `send(dest, value, data)`. 2. Both contracts and regular addresses can control and reject which token they send by registering a `tokensToSend` hook. (Rejection is done by `revert`ing in the hook function.) 3. Both contracts and regular addresses can control and reject which token they receive by registering a `tokensReceived` hook. (Rejection is done by `revert`ing in the hook function.) 4. The `tokensReceived` hook allows to send tokens to a contract and notify it in a single transaction, unlike [ERC-20] which requires a double call (`approve`/`transferFrom`) to achieve this. 5. The holder can "authorize" and "revoke" operators which can send tokens on their behalf. These operators are intended to be verified contracts such as an exchange, a cheque processor or an automatic charging system. 6. Every token transaction contains `data` and `operatorData` bytes fields to be used freely to pass data from the holder and the operator, respectively. 7. It is backward compatible with wallets that do not contain the `tokensReceived` hook function by deploying a proxy contract implementing the `tokensReceived` hook for the wallet. ## Specification ### ERC777Token (Token Contract) ``` solidity interface ERC777Token { function name() external view returns (string memory); function symbol() external view returns (string memory); function totalSupply() external view returns (uint256); function balanceOf(address holder) external view returns (uint256); function granularity() external view returns (uint256); function defaultOperators() external view returns (address[] memory); function isOperatorFor( address operator, address holder ) external view returns (bool); function authorizeOperator(address operator) external; function revokeOperator(address operator) external; function send(address to, uint256 amount, bytes calldata data) external; function operatorSend( address from, address to, uint256 amount, bytes calldata data, bytes calldata operatorData ) external; function burn(uint256 amount, bytes calldata data) external; function operatorBurn( address from, uint256 amount, bytes calldata data, bytes calldata operatorData ) external; event Sent( address indexed operator, address indexed from, address indexed to, uint256 amount, bytes data, bytes operatorData ); event Minted( address indexed operator, address indexed to, uint256 amount, bytes data, bytes operatorData ); event Burned( address indexed operator, address indexed from, uint256 amount, bytes data, bytes operatorData ); event AuthorizedOperator( address indexed operator, address indexed holder ); event RevokedOperator(address indexed operator, address indexed holder); } ``` The token contract MUST implement the above interface. The implementation MUST follow the specifications described below. The token contract MUST register the `ERC777Token` interface with its own address via [ERC-1820]. > This is done by calling the `setInterfaceImplementer` function on the [ERC-1820] registry > with the token contract address as both the address and the implementer > and the `keccak256` hash of `ERC777Token` (`0xac7fbab5f54a3ca8194167523c6753bfeb96a445279294b6125b68cce2177054`) > as the interface hash. If the contract has a switch to enable or disable ERC-777 functions, every time the switch is triggered, the token MUST register or unregister the `ERC777Token` interface for its own address accordingly via ERC1820. Unregistering implies calling the `setInterfaceImplementer` with the token contract address as the address, the `keccak256` hash of `ERC777Token` as the interface hash and `0x0` as the implementer. (See [Set An Interface For An Address][erc1820-set] in [ERC-1820] for more details.) When interacting with the token contract, all amounts and balances MUST be unsigned integers. I.e. internally, all values are stored as a denomination of 1E-18 of a token. The display denomination—to display any amount to the end user—MUST be 10¹⁸ of the internal denomination. In other words, the internal denomination is similar to a wei and the display denomination is similar to an ether. It is equivalent to an [ERC-20]'s `decimals` function returning `18`. E.g. if a token contract returns a balance of `500,000,000,000,000,000` (0.5×10¹⁸) for a user, the user interface MUST show `0.5` tokens to the user. If the user wishes to send `0.3` tokens, the contract MUST be called with an amount of `300,000,000,000,000,000` (0.3×10¹⁸). User Interfaces which are generated programmatically from the ABI of the token contract MAY use and display the internal denomination. But this MUST be made clear, for example by displaying the `uint256` type. #### **View Functions** The `view` functions detailed below MUST be implemented. **`name` function** ``` solidity function name() external view returns (string memory) ``` Get the name of the token, e.g., `"MyToken"`. > **identifier:** `06fdde03` > **returns:** Name of the token. **`symbol` function** ``` solidity function symbol() external view returns (string memory) ``` Get the symbol of the token, e.g., `"MYT"`. > **identifier:** `95d89b41` > **returns:** Symbol of the token. **`totalSupply` function** ``` solidity function totalSupply() external view returns (uint256) ``` Get the total number of minted tokens. *NOTE*: The total supply MUST be equal to the sum of the balances of all addresses—as returned by the `balanceOf` function. *NOTE*: The total supply MUST be equal to the sum of all the minted tokens as defined in all the `Minted` events minus the sum of all the burned tokens as defined in all the `Burned` events. > **identifier:** `18160ddd` > **returns:** Total supply of tokens currently in circulation. **`balanceOf` function** ``` solidity function balanceOf(address holder) external view returns (uint256) ``` Get the balance of the account with address `holder`. The balance MUST be zero (`0`) or higher. > **identifier:** `70a08231` > **parameters** > `holder`: Address for which the balance is returned. > > **returns:** Amount of tokens held by `holder` in the token contract. **`granularity` function** ``` solidity function granularity() external view returns (uint256) ``` Get the smallest part of the token that's not divisible. In other words, the granularity is the smallest amount of tokens (in the internal denomination) which MAY be minted, sent or burned at any time. The following rules MUST be applied regarding the *granularity*: - The *granularity* value MUST be set at creation time. - The *granularity* value MUST NOT be changed, ever. - The *granularity* value MUST be greater than or equal to `1`. - All balances MUST be a multiple of the granularity. - Any amount of tokens (in the internal denomination) minted, sent or burned MUST be a multiple of the *granularity* value. - Any operation that would result in a balance that's not a multiple of the *granularity* value MUST be considered invalid, and the transaction MUST `revert`. *NOTE*: Most tokens SHOULD be fully partition-able. I.e., this function SHOULD return `1` unless there is a good reason for not allowing any fraction of the token. > **identifier:** `556f0dc7` > **returns:** The smallest non-divisible part of the token. *NOTE*: [`defaultOperators`][defaultOperators] and [`isOperatorFor`][isOperatorFor] are also `view` functions, defined under the [operators] for consistency. *[ERC-20] compatibility requirement*: The decimals of the token MUST always be `18`. For a *pure* ERC-777 token the [ERC-20] `decimals` function is OPTIONAL, and its existence SHALL NOT be relied upon when interacting with the token contract. (The decimal value of `18` is implied.) For an [ERC-20] compatible token, the `decimals` function is REQUIRED and MUST return `18`. (In [ERC-20], the `decimals` function is OPTIONAL. If the function is not present, the `decimals` value is not clearly defined and may be assumed to be `0`. Hence for compatibility reasons, `decimals` MUST be implemented for [ERC-20] compatible tokens.) #### **Operators** An `operator` is an address which is allowed to send and burn tokens on behalf of some *holder*. When an address becomes an *operator* for a *holder*, an `AuthorizedOperator` event MUST be emitted. The `AuthorizedOperator`'s `operator` (topic 1) and `holder` (topic 2) MUST be the addresses of the *operator* and the *holder* respectively. When a *holder* revokes an *operator*, a `RevokedOperator` event MUST be emitted. The `RevokedOperator`'s `operator` (topic 1) and `holder` (topic 2) MUST be the addresses of the *operator* and the *holder* respectively. *NOTE*: A *holder* MAY have multiple *operators* at the same time. The token MAY define *default operators*. A *default operator* is an implicitly authorized *operator* for all *holders*. `AuthorizedOperator` events MUST NOT be emitted when defining the *default operators*. The rules below apply to *default operators*: - The token contract MUST define *default operators* at creation time. - The *default operators* MUST be invariants. I.e., the token contract MUST NOT add or remove *default operators* ever. - `AuthorizedOperator` events MUST NOT be emitted when defining *default operators*. - A *holder* MUST be allowed to revoke a *default operator* (unless the *holder* is the *default operator* in question). - A *holder* MUST be allowed to re-authorize a previously revoked *default operator*. - When a *default operator* is explicitly authorized or revoked for a specific *holder*, an `AuthorizedOperator` or `RevokedOperator` event (respectively) MUST be emitted. The following rules apply to any *operator*: - An address MUST always be an *operator* for itself. Hence an address MUST NOT ever be revoked as its own *operator*. - If an address is an *operator* for a *holder*, `isOperatorFor` MUST return `true`. - If an address is not an *operator* for a *holder*, `isOperatorFor` MUST return `false`. - The token contract MUST emit an `AuthorizedOperator` event with the correct values when a *holder* authorizes an address as its *operator* as defined in the [`AuthorizedOperator` Event][authorizedoperator]. - The token contract MUST emit a `RevokedOperator` event with the correct values when a *holder* revokes an address as its *operator* as defined in the [`RevokedOperator` Event][revokedoperator]. *NOTE*: A *holder* MAY authorize an already authorized *operator*. An `AuthorizedOperator` MUST be emitted each time. *NOTE*: A *holder* MAY revoke an already revoked *operator*. A `RevokedOperator` MUST be emitted each time. **`AuthorizedOperator` event** ``` solidity event AuthorizedOperator(address indexed operator, address indexed holder) ``` Indicates the authorization of `operator` as an *operator* for `holder`. *NOTE*: This event MUST NOT be emitted outside of an *operator* authorization process. > **parameters** > `operator`: Address which became an *operator* of `holder`. > `holder`: Address of a *holder* which authorized the `operator` address as an *operator*. **`RevokedOperator` event** ``` solidity event RevokedOperator(address indexed operator, address indexed holder) ``` Indicates the revocation of `operator` as an *operator* for `holder`. *NOTE*: This event MUST NOT be emitted outside of an *operator* revocation process. > **parameters** > `operator`: Address which was revoked as an *operator* of `holder`. > `holder`: Address of a *holder* which revoked the `operator` address as an *operator*. The `defaultOperators`, `authorizeOperator`, `revokeOperator` and `isOperatorFor` functions described below MUST be implemented to manage *operators*. Token contracts MAY implement other functions to manage *operators*. **`defaultOperators` function** ``` solidity function defaultOperators() external view returns (address[] memory) ``` Get the list of *default operators* as defined by the token contract. *NOTE*: If the token contract does not have any *default operators*, this function MUST return an empty list. > **identifier:** `06e48538` > **returns:** List of addresses of all the *default operators*. **`authorizeOperator` function** ``` solidity function authorizeOperator(address operator) external ``` Set a third party `operator` address as an *operator* of `msg.sender` to send and burn tokens on its behalf. *NOTE*: The *holder* (`msg.sender`) is always an *operator* for itself. This right SHALL NOT be revoked. Hence this function MUST `revert` if it is called to authorize the holder (`msg.sender`) as an *operator* for itself (i.e. if `operator` is equal to `msg.sender`). > **identifier:** `959b8c3f` > **parameters** > `operator`: Address to set as an *operator* for `msg.sender`. **`revokeOperator` function** ``` solidity function revokeOperator(address operator) external ``` Remove the right of the `operator` address to be an *operator* for `msg.sender` and to send and burn tokens on its behalf. *NOTE*: The *holder* (`msg.sender`) is always an *operator* for itself. This right SHALL NOT be revoked. Hence this function MUST `revert` if it is called to revoke the holder (`msg.sender`) as an *operator* for itself (i.e., if `operator` is equal to `msg.sender`). > **identifier:** `fad8b32a` > **parameters** > `operator`: Address to rescind as an *operator* for `msg.sender`. **`isOperatorFor` function** ``` solidity function isOperatorFor( address operator, address holder ) external view returns (bool) ``` Indicate whether the `operator` address is an *operator* of the `holder` address. > **identifier:** `d95b6371` > **parameters** > `operator`: Address which may be an *operator* of `holder`. > `holder`: Address of a *holder* which may have the `operator` address as an *operator*. > > **returns:** `true` if `operator` is an *operator* of `holder` and `false` otherwise. *NOTE*: To know which addresses are *operators* for a given *holder*, one MUST call `isOperatorFor` with the *holder* for each *default operator* and parse the `AuthorizedOperator`, and `RevokedOperator` events for the *holder* in question. #### **Sending Tokens** When an *operator* sends an `amount` of tokens from a *holder* to a *recipient* with the associated `data` and `operatorData`, the token contract MUST apply the following rules: - Any authorized *operator* MAY send tokens to any *recipient* (except to `0x0`). - The balance of the *holder* MUST be decreased by the `amount`. - The balance of the *recipient* MUST be increased by the `amount`. - The balance of the *holder* MUST be greater or equal to the `amount`—such that its resulting balance is greater or equal to zero (`0`) after the send. - The token contract MUST emit a `Sent` event with the correct values as defined in the [`Sent` Event][sent]. - The *operator* MAY include information in the `operatorData`. - The token contract MUST call the `tokensToSend` hook of the *holder* if the *holder* registers an `ERC777TokensSender` implementation via [ERC-1820]. - The token contract MUST call the `tokensReceived` hook of the *recipient* if the *recipient* registers an `ERC777TokensRecipient` implementation via [ERC-1820]. - The `data` and `operatorData` MUST be immutable during the entire send process—hence the same `data` and `operatorData` MUST be used to call both hooks and emit the `Sent` event. The token contract MUST `revert` when sending in any of the following cases: - The *operator* address is not an authorized operator for the *holder*. - The resulting *holder* balance or *recipient* balance after the send is not a multiple of the *granularity* defined by the token contract. - The *recipient* is a contract, and it does not implement the `ERC777TokensRecipient` interface via [ERC-1820]. - The address of the *holder* or the *recipient* is `0x0`. - Any of the resulting balances becomes negative, i.e. becomes less than zero (`0`). - The `tokensToSend` hook of the *holder* `revert`s. - The `tokensReceived` hook of the *recipient* `revert`s. The token contract MAY send tokens from many *holders*, to many *recipients*, or both. In this case: - The previous send rules MUST apply to all the *holders* and all the *recipients*. - The sum of all the balances incremented MUST be equal to the total sent `amount`. - The sum of all the balances decremented MUST be equal to the total sent `amount`. - A `Sent` event MUST be emitted for every *holder* and *recipient* pair with the corresponding amount for each pair. - The sum of all the amounts from the `Sent` event MUST be equal to the total sent `amount`. *NOTE*: Mechanisms such as applying a fee on a send is considered as a send to multiple *recipients*: the intended *recipient* and the fee *recipient*. *NOTE*: Movements of tokens MAY be chained. For example, if a contract upon receiving tokens sends them further to another address. In this case, the previous send rules apply to each send, in order. *NOTE*: Sending an amount of zero (`0`) tokens is valid and MUST be treated as a regular send. *Implementation Requirement*: - The token contract MUST call the `tokensToSend` hook *before* updating the state. - The token contract MUST call the `tokensReceived` hook *after* updating the state. I.e., `tokensToSend` MUST be called first, then the balances MUST be updated to reflect the send, and finally `tokensReceived` MUST be called *afterward*. Thus a `balanceOf` call within `tokensToSend` returns the balance of the address *before* the send and a `balanceOf` call within `tokensReceived` returns the balance of the address *after* the send. *NOTE*: The `data` field contains information provided by the *holder*—similar to the data field in a regular ether send transaction. The `tokensToSend()` hook, the `tokensReceived()`, or both MAY use the information to decide if they wish to reject the transaction. *NOTE*: The `operatorData` field is analogous to the `data` field except it SHALL be provided by the *operator*. The `operatorData` MUST only be provided by the *operator*. It is intended more for logging purposes and particular cases. (Examples include payment references, cheque numbers, countersignatures and more.) In most of the cases the recipient would ignore the `operatorData`, or at most, it would log the `operatorData`. **`Sent` event** ``` solidity event Sent( address indexed operator, address indexed from, address indexed to, uint256 amount, bytes data, bytes operatorData ) ``` Indicate a send of `amount` of tokens from the `from` address to the `to` address by the `operator` address. *NOTE*: This event MUST NOT be emitted outside of a send or an [ERC-20] transfer process. > **parameters** > `operator`: Address which triggered the send. > `from`: *Holder* whose tokens were sent. > `to`: Recipient of the tokens. > `amount`: Number of tokens sent. > `data`: Information provided by the *holder*. > `operatorData`: Information provided by the *operator*. The `send` and `operatorSend` functions described below MUST be implemented to send tokens. Token contracts MAY implement other functions to send tokens. **`send` function** ``` solidity function send(address to, uint256 amount, bytes calldata data) external ``` Send the `amount` of tokens from the address `msg.sender` to the address `to`. The *operator* and the *holder* MUST both be the `msg.sender`. > **identifier:** `9bd9bbc6` > **parameters** > `to`: Recipient of the tokens. > `amount`: Number of tokens to send. > `data`: Information provided by the *holder*. **`operatorSend` function** ``` solidity function operatorSend( address from, address to, uint256 amount, bytes calldata data, bytes calldata operatorData ) external ``` Send the `amount` of tokens on behalf of the address `from` to the address `to`. *Reminder*: If the *operator* address is not an authorized operator of the `from` address, then the send process MUST `revert`. *NOTE*: `from` and `msg.sender` MAY be the same address. I.e., an address MAY call `operatorSend` for itself. This call MUST be equivalent to `send` with the addition that the *operator* MAY specify an explicit value for `operatorData` (which cannot be done with the `send` function). > **identifier:** `62ad1b83` > **parameters** > `from`: *Holder* whose tokens are being sent. > `to`: Recipient of the tokens. > `amount`: Number of tokens to send. > `data`: Information provided by the *holder*. > `operatorData`: Information provided by the *operator*. #### **Minting Tokens** Minting tokens is the act of producing new tokens. [ERC-777] intentionally does not define specific functions to mint tokens. This intent comes from the wish not to limit the use of the [ERC-777] standard as the minting process is generally specific for every token. Nonetheless, the rules below MUST be respected when minting for a *recipient*: - Tokens MAY be minted for any *recipient* address (except `0x0`). - The total supply MUST be increased by the amount of tokens minted. - The balance of `0x0` MUST NOT be decreased. - The balance of the *recipient* MUST be increased by the amount of tokens minted. - The token contract MUST emit a `Minted` event with the correct values as defined in the [`Minted` Event][minted]. - The token contract MUST call the `tokensReceived` hook of the *recipient* if the *recipient* registers an `ERC777TokensRecipient` implementation via [ERC-1820]. - The `data` and `operatorData` MUST be immutable during the entire mint process—hence the same `data` and `operatorData` MUST be used to call the `tokensReceived` hook and emit the `Minted` event. The token contract MUST `revert` when minting in any of the following cases: - The resulting *recipient* balance after the mint is not a multiple of the *granularity* defined by the token contract. - The *recipient* is a contract, and it does not implement the `ERC777TokensRecipient` interface via [ERC-1820]. - The address of the *recipient* is `0x0`. - The `tokensReceived` hook of the *recipient* `revert`s. *NOTE*: The initial token supply at the creation of the token contract MUST be considered as minting for the amount of the initial supply to the address(es) receiving the initial supply. This means one or more `Minted` events must be emitted and the `tokensReceived` hook of the recipient(s) MUST be called. *[ERC-20] compatibility requirement*: While a `Sent` event MUST NOT be emitted when minting, if the token contract is [ERC-20] backward compatible, a `Transfer` event with the `from` parameter set to `0x0` SHOULD be emitted as defined in the [ERC-20] standard. The token contract MAY mint tokens for multiple *recipients* at once. In this case: - The previous mint rules MUST apply to all the *recipients*. - The sum of all the balances incremented MUST be equal to the total minted amount. - A `Minted` event MUST be emitted for every *recipient* with the corresponding amount for each *recipient*. - The sum of all the amounts from the `Minted` event MUST be equal to the total minted `amount`. *NOTE*: Minting an amount of zero (`0`) tokens is valid and MUST be treated as a regular mint. *NOTE*: While during a send or a burn, the data is provided by the *holder*, it is inapplicable for a mint. In this case the data MAY be provided by the token contract or the *operator*, for example to ensure a successful minting to a *holder* expecting specific data. *NOTE*: The `operatorData` field contains information provided by the *operator*—similar to the data field in a regular ether send transaction. The `tokensReceived()` hooks MAY use the information to decide if it wish to reject the transaction. **`Minted` event** ``` solidity event Minted( address indexed operator, address indexed to, uint256 amount, bytes data, bytes operatorData ) ``` Indicate the minting of `amount` of tokens to the `to` address by the `operator` address. *NOTE*: This event MUST NOT be emitted outside of a mint process. > **parameters** > `operator`: Address which triggered the mint. > `to`: Recipient of the tokens. > `amount`: Number of tokens minted. > `data`: Information provided for the *recipient*. > `operatorData`: Information provided by the *operator*. #### **Burning Tokens** Burning tokens is the act of destroying existing tokens. [ERC-777] explicitly defines two functions to burn tokens (`burn` and `operatorBurn`). These functions facilitate the integration of the burning process in wallets and dapps. However, the token contract MAY prevent some or all *holders* from burning tokens for any reason. The token contract MAY also define other functions to burn tokens. The rules below MUST be respected when burning the tokens of a *holder*: - Tokens MAY be burned from any *holder* address (except `0x0`). - The total supply MUST be decreased by the amount of tokens burned. - The balance of `0x0` MUST NOT be increased. - The balance of the *holder* MUST be decreased by amount of tokens burned. - The token contract MUST emit a `Burned` event with the correct values as defined in the [`Burned` Event][burned]. - The token contract MUST call the `tokensToSend` hook of the *holder* if the *holder* registers an `ERC777TokensSender` implementation via [ERC-1820]. - The `operatorData` MUST be immutable during the entire burn process—hence the same `operatorData` MUST be used to call the `tokensToSend` hook and emit the `Burned` event. The token contract MUST `revert` when burning in any of the following cases: - The *operator* address is not an authorized operator for the *holder*. - The resulting *holder* balance after the burn is not a multiple of the *granularity* defined by the token contract. - The balance of *holder* is inferior to the amount of tokens to burn (i.e., resulting in a negative balance for the *holder*). - The address of the *holder* is `0x0`. - The `tokensToSend` hook of the *holder* `revert`s. *[ERC-20] compatibility requirement*: While a `Sent` event MUST NOT be emitted when burning; if the token contract is [ERC-20] enabled, a `Transfer` event with the `to` parameter set to `0x0` SHOULD be emitted. The [ERC-20] standard does not define the concept of burning tokens, but this is a commonly accepted practice. The token contract MAY burn tokens for multiple *holders* at once. In this case: - The previous burn rules MUST apply to each *holders*. - The sum of all the balances decremented MUST be equal to the total burned amount. - A `Burned` event MUST be emitted for every *holder* with the corresponding amount for each *holder*. - The sum of all the amounts from the `Burned` event MUST be equal to the total burned `amount`. *NOTE*: Burning an amount of zero (`0`) tokens is valid and MUST be treated as a regular burn. *NOTE*: The `data` field contains information provided by the holder—similar to the data field in a regular ether send transaction. The `tokensToSend()` hook, the `tokensReceived()`, or both MAY use the information to decide if they wish to reject the transaction. *NOTE*: The `operatorData` field is analogous to the `data` field except it SHALL be provided by the *operator*. **`Burned` event** ``` solidity event Burned( address indexed operator, address indexed from, uint256 amount, bytes data, bytes operatorData ); ``` Indicate the burning of `amount` of tokens from the `from` address by the `operator` address. *NOTE*: This event MUST NOT be emitted outside of a burn process. > **parameters** > `operator`: Address which triggered the burn. > `from`: *Holder* whose tokens were burned. > `amount`: Number of tokens burned. > `data`: Information provided by the *holder*. > `operatorData`: Information provided by the *operator*. The `burn` and `operatorBurn` functions described below MUST be implemented to burn tokens. Token contracts MAY implement other functions to burn tokens. **`burn` function** ``` solidity function burn(uint256 amount, bytes calldata data) external ``` Burn the `amount` of tokens from the address `msg.sender`. The *operator* and the *holder* MUST both be the `msg.sender`. > **identifier:** `fe9d9303` > **parameters** > `amount`: Number of tokens to burn. > `data`: Information provided by the *holder*. **`operatorBurn` function** ``` solidity function operatorBurn( address from, uint256 amount, bytes calldata data, bytes calldata operatorData ) external ``` Burn the `amount` of tokens on behalf of the address `from`. *Reminder*: If the *operator* address is not an authorized operator of the `from` address, then the burn process MUST `revert`. > **identifier:** `fc673c4f` > **parameters** > `from`: *Holder* whose tokens will be burned. > `amount`: Number of tokens to burn. > `data`: Information provided by the *holder*. > `operatorData`: Information provided by the *operator*. *NOTE*: The *operator* MAY pass any information via `operatorData`. The `operatorData` MUST only be provided by the *operator*. *NOTE*: `from` and `msg.sender` MAY be the same address. I.e., an address MAY call `operatorBurn` for itself. This call MUST be equivalent to `burn` with the addition that the *operator* MAY specify an explicit value for `operatorData` (which cannot be done with the `burn` function). #### **`ERC777TokensSender` And The `tokensToSend` Hook** The `tokensToSend` hook notifies of any request to decrement the balance (send and burn) for a given *holder*. Any address (regular or contract) wishing to be notified of token debits from their address MAY register the address of a contract implementing the `ERC777TokensSender` interface described below via [ERC-1820]. > This is done by calling the `setInterfaceImplementer` function on the [ERC-1820] registry > with the *holder* address as the address, > the `keccak256` hash of `ERC777TokensSender` > (`0x29ddb589b1fb5fc7cf394961c1adf5f8c6454761adf795e67fe149f658abe895`) as the interface hash, > and the address of the contract implementing the `ERC777TokensSender` as the implementer. ``` solidity interface ERC777TokensSender { function tokensToSend( address operator, address from, address to, uint256 amount, bytes calldata userData, bytes calldata operatorData ) external; } ``` *NOTE*: A regular address MAY register a different address—the address of a contract—implementing the interface on its behalf. A contract MAY register either its address or the address of another contract but said address MUST implement the interface on its behalf. **`tokensToSend`** ``` solidity function tokensToSend( address operator, address from, address to, uint256 amount, bytes calldata userData, bytes calldata operatorData ) external ``` Notify a request to send or burn (if `to` is `0x0`) an `amount` tokens from the `from` address to the `to` address by the `operator` address. *NOTE*: This function MUST NOT be called outside of a burn, send or [ERC-20] transfer process. > **identifier:** `75ab9782` > **parameters** > `operator`: Address which triggered the balance decrease (through sending or burning). > `from`: *Holder* whose tokens were sent. > `to`: Recipient of the tokens for a send (or `0x0` for a burn). > `amount`: Number of tokens the *holder* balance is decreased by. > `data`: Information provided by the *holder*. > `operatorData`: Information provided by the *operator*. The following rules apply when calling the `tokensToSend` hook: - The `tokensToSend` hook MUST be called for every send and burn processes. - The `tokensToSend` hook MUST be called *before* the state is updated—i.e. *before* the balance is decremented. - `operator` MUST be the address which triggered the send or burn process. - `from` MUST be the address of the *holder* whose tokens are sent or burned. - `to` MUST be the address of the *recipient* which receives the tokens for a send. - `to` MUST be `0x0` for a burn. - `amount` MUST be the number of tokens the *holder* sent or burned. - `data` MUST contain the extra information (if any) provided to the send or the burn process. - `operatorData` MUST contain the extra information provided by the address which triggered the decrease of the balance (if any). - The *holder* MAY block a send or burn process by `revert`ing. (I.e., reject the withdrawal of tokens from its account.) *NOTE*: Multiple *holders* MAY use the same implementation of `ERC777TokensSender`. *NOTE*: An address can register at most one implementation at any given time for all [ERC-777] tokens. Hence the `ERC777TokensSender` MUST expect to be called by different token contracts. The `msg.sender` of the `tokensToSend` call is expected to be the address of the token contract. *[ERC-20] compatibility requirement*: This hook takes precedence over [ERC-20] and MUST be called (if registered) when calling [ERC-20]'s `transfer` and `transferFrom` event. When called from a `transfer`, `operator` MUST be the same value as the `from`. When called from a `transferFrom`, `operator` MUST be the address which issued the `transferFrom` call. #### **`ERC777TokensRecipient` And The `tokensReceived` Hook** The `tokensReceived` hook notifies of any increment of the balance (send and mint) for a given *recipient*. Any address (regular or contract) wishing to be notified of token credits to their address MAY register the address of a contract implementing the `ERC777TokensRecipient` interface described below via [ERC-1820]. > This is done by calling the `setInterfaceImplementer` function on the [ERC-1820] registry > with the *recipient* address as the address, > the `keccak256` hash of `ERC777TokensRecipient` > (`0xb281fc8c12954d22544db45de3159a39272895b169a852b314f9cc762e44c53b`) as the interface hash, > and the address of the contract implementing the `ERC777TokensRecipient` as the implementer. ``` solidity interface ERC777TokensRecipient { function tokensReceived( address operator, address from, address to, uint256 amount, bytes calldata data, bytes calldata operatorData ) external; } ``` If the *recipient* is a contract, which has not registered an `ERC777TokensRecipient` implementation; then the token contract: - MUST `revert` if the `tokensReceived` hook is called from a mint or send call. - SHOULD continue processing the transaction if the `tokensReceived` hook is called from an ERC-20 `transfer` or `transferFrom` call. *NOTE*: A regular address MAY register a different address—the address of a contract—implementing the interface on its behalf. A contract MUST register either its address or the address of another contract but said address MUST implement the interface on its behalf. **`tokensReceived`** ``` solidity function tokensReceived( address operator, address from, address to, uint256 amount, bytes calldata data, bytes calldata operatorData ) external ``` Notify a send or mint (if `from` is `0x0`) of `amount` tokens from the `from` address to the `to` address by the `operator` address. *NOTE*: This function MUST NOT be called outside of a mint, send or [ERC-20] transfer process. > **identifier:** `0023de29` > **parameters** > `operator`: Address which triggered the balance increase (through sending or minting). > `from`: *Holder* whose tokens were sent (or `0x0` for a mint). > `to`: Recipient of the tokens. > `amount`: Number of tokens the *recipient* balance is increased by. > `data`: Information provided by the *holder*. > `operatorData`: Information provided by the *operator*. The following rules apply when calling the `tokensReceived` hook: - The `tokensReceived` hook MUST be called for every send and mint processes. - The `tokensReceived` hook MUST be called *after* the state is updated—i.e. *after* the balance is incremented. - `operator` MUST be the address which triggered the send or mint process. - `from` MUST be the address of the *holder* whose tokens are sent for a send. - `from` MUST be `0x0` for a mint. - `to` MUST be the address of the *recipient* which receives the tokens. - `amount` MUST be the number of tokens the *recipient* sent or minted. - `data` MUST contain the extra information (if any) provided to the send or the mint process. - `operatorData` MUST contain the extra information provided by the address which triggered the increase of the balance (if any). - The *holder* MAY block a send or mint process by `revert`ing. (I.e., reject the reception of tokens.) *NOTE*: Multiple *holders* MAY use the same implementation of `ERC777TokensRecipient`. *NOTE*: An address can register at most one implementation at any given time for all [ERC-777] tokens. Hence the `ERC777TokensRecipient` MUST expect to be called by different token contracts. The `msg.sender` of the `tokensReceived` call is expected to be the address of the token contract. *[ERC-20] compatibility requirement*: This hook takes precedence over [ERC-20] and MUST be called (if registered) when calling [ERC-20]'s `transfer` and `transferFrom` event. When called from a `transfer`, `operator` MUST be the same value as the `from`. When called from a `transferFrom`, `operator` MUST be the address which issued the `transferFrom` call. #### **Note On Gas Consumption** Dapps and wallets SHOULD first estimate the gas required when sending, minting, or burning tokens—using [`eth_estimateGas`][eth_estimateGas]—to avoid running out of gas during the transaction. ### Logo | **Image** | ![beige logo] | ![white logo] | ![light grey logo] | ![dark grey logo] | ![black logo] | |----------:|:-------------:|:-------------:|:------------------:|:-----------------:|:-------------:| | **Color** | beige | white | light grey | dark grey | black | | **Hex** | `#C99D66` | `#FFFFFF` | `#EBEFF0` | `#3C3C3D` | `#000000` | The logo MAY be used, modified and adapted to promote valid [ERC-777] token implementations and [ERC-777] compliant technologies such as wallets and dapps. [ERC-777] token contract authors MAY create a specific logo for their token based on this logo. The logo MUST NOT be used to advertise, promote or associate in any way technology—such as tokens—which is not [ERC-777] compliant. The logo for the standard can be found in the [`/assets/eip-777/logo`][logos] folder in `SVG` and `PNG` formats. The `PNG` version of the logo offers a few sizes in pixels. If needed, other sizes MAY be created by converting from `SVG` into `PNG`. ## Rationale The principal intent for this standard is to solve some of the shortcomings of [ERC-20] while maintaining backward compatibility with [ERC-20], and avoiding the problems and vulnerabilities of [EIP-223]. Below are the rationales for the decisions regarding the main aspects of the standards. *NOTE*: Jacques Dafflon ([0xjac]), one of the authors of the standard, conjointly wrote his [master thesis] on the standard, which goes in more details than could reasonably fit directly within the standard, and can provide further clarifications regarding certain aspects or decisions. ### Lifecycle More than just sending tokens, [ERC-777] defines the entire lifecycle of a token, starting with the minting process, followed by the sending process and terminating with the burn process. Having a lifecycle clearly defined is important for consistency and accuracy, especially when value is derived from scarcity. In contrast when looking at some [ERC-20] tokens, a discrepancy can be observed between the value returned by the `totalSupply` and the actual circulating supply, as the standard does not clearly define a process to create and destroy tokens. ### Data The mint, send and burn processes can all make use of a `data` and `operatorData` fields which are passed to any movement (mint, send or burn). Those fields may be empty for simple use cases, or they may contain valuable information related to the movement of tokens, similar to information attached to a bank transfer by the sender or the bank itself. The use of a `data` field is equally present in other standard proposals such as [EIP-223], and was requested by multiple members of the community who reviewed this standard. ### Hooks In most cases, [ERC-20] requires two calls to safely transfer tokens to a contract without locking them. A call from the sender, using the `approve` function and a call from the recipient using `transferFrom`. Furthermore, this requires extra communication between the parties which is not clearly defined. Finally, holders can get confused between `transfer` and `approve`/`transferFrom`. Using the former to transfer tokens to a contract will most likely result in locked tokens. Hooks allow streamlining of the sending process and offer a single way to send tokens to any recipient. Thanks to the `tokensReceived` hook, contracts are able to react and prevent locking tokens upon reception. #### **Greater Control For Holders** The `tokensReceived` hook also allows holders to reject the reception of some tokens. This gives greater control to holders who can accept or reject incoming tokens based on some parameters, for example located in the `data` or `operatorData` fields. Following the same intentions and based on suggestions from the community, the `tokensToSend` hook was added to give control over and prevent the movement of outgoing tokens. #### **[ERC-1820] Registry** The [ERC-1820] Registry allows holders to register their hooks. Other alternatives were examined beforehand to link hooks and holders. The first was for hooks to be defined at the sender's or recipient's address. This approach is similar to [EIP-223] which proposes a `tokenFallback` function on recipient contracts to be called when receiving tokens, but improves on it by relying on [ERC-165] for interface detection. While straightforward to implement, this approach imposes several limitations. In particular, the sender and recipient must be contracts in order to provide their implementation of the hooks. Preventing externally owned addresses to benefit from hooks. Existing contracts have a strong probability not to be compatible, as they undoubtedly were unaware and do not define the new hooks. Consequently existing smart contract infrastructure such as multisig wallets which potentially hold large amounts of ether and tokens would need to be migrated to new updated contracts. The second approach considered was to use [ERC-672] which offered pseudo-introspection for addresses using reverse-ENS. However, this approach relied heavily on ENS, on top of which reverse lookup would need to be implemented. Analysis of this approach promptly revealed a certain degree of complexity and security concerns which would transcend the benefits of approach. The third solution—used in this standard—is to rely on a unique registry where any address can register the addresses of contracts implementing the hooks on its behalf. This approach has the advantage that externally owned accounts and contracts can benefit from hooks, including existing contracts which can rely on hooks deployed on proxy contracts. The decision was made to keep this registry in a separate EIP, as to not over complicate this standard. More importantly, the registry is designed in a flexible fashion, such that other EIPs and smart contract infrastructures can benefit from it for their own use cases, outside the realm of [ERC-777] and tokens. The first proposal for this registry was [ERC-820]. Unfortunately, issues emanating from upgrades in the Solidity language to versions 0.5 and above resulted in a bug in a separated part of the registry, which required changes. This was discovered right after the last call period. Attempts made to avoid creating a separate EIP, such as [ERC-820a], were rejected. Hence the standard for the registry used for [ERC-777] became [ERC-1820]. [ERC-1820] and [ERC-820] are functionally equivalent. [ERC-1820] simply contains the fix for newer versions of Solidity. ### Operators The standard defines the concept of operators as any address which moves tokens. While intuitively every address moves its own tokens, separating the concepts of holder and operator allows for greater flexibility. Primarily, this originates from the fact that the standard defines a mechanism for holders to let other addresses become their operators. Moreover, unlike the approve calls in [ERC-20] where the role of an approved address is not clearly defined, [ERC-777] details the intent of and interactions with operators, including an obligation for operators to be approved, and an irrevocable right for any holder to revoke operators. #### **Default Operators** Default operators were added based on community demand for pre-approved operators. That is operators which are approved for all holders by default. For obvious security reasons, the list of default operators is defined at the token contract creation time, and cannot be changed. Any holder still has the right to revoke default operators. One of the obvious advantages of default operators is to allow ether-less movements of tokens. Default operators offer other usability advantages, such as allowing token providers to offer functionality in a modular way, and to reduce the complexity for holders to use features provided through operators. ## Backward Compatibility This EIP does not introduce backward incompatibilities and is backward compatible with the older [ERC-20] token standard. This EIP does not use `transfer` and `transferFrom` and uses `send` and `operatorSend` to avoid confusion and mistakes when deciphering which token standard is being used. This standard allows the implementation of [ERC-20] functions `transfer`, `transferFrom`, `approve` and `allowance` alongside to make a token fully compatible with [ERC-20]. The token MAY implement `decimals()` for backward compatibility with [ERC-20]. If implemented, it MUST always return `18`. Therefore a token contract MAY implement both [ERC-20] and [ERC-777] in parallel. The specification of the `view` functions (such as `name`, `symbol`, `balanceOf`, `totalSupply`) and internal data (such as the mapping of balances) overlap without problems. Note however that the following functions are mandatory in [ERC-777] and MUST be implemented: `name`, `symbol` `balanceOf` and `totalSupply` (`decimals` is not part of the [ERC-777] standard). The state-modifying functions from both standards are decoupled and can operate independently from each other. Note that [ERC-20] functions SHOULD be limited to only being called from old contracts. If the token implements [ERC-20], it MUST register the `ERC20Token` interface with its own address via [ERC-1820]. This is done by calling the `setInterfaceImplementer` function on the ERC-1820 registry with the token contract address as both the address and the implementer and the `keccak256` hash of `ERC20Token` (`0xaea199e31a596269b42cdafd93407f14436db6e4cad65417994c2eb37381e05a`) as the interface hash. If the contract has a switch to enable or disable ERC-20 functions, every time the switch is triggered, the token MUST register or unregister the `ERC20Token` interface for its own address accordingly via ERC1820. Unregistering implies calling the `setInterfaceImplementer` with the token contract address as the address, the `keccak256` hash of `ERC20Token` as the interface hash and `0x0` as the implementer. (See [Set An Interface For An Address][erc1820-set] in [ERC-1820] for more details.) The difference for new contracts implementing [ERC-20] is that `tokensToSend` and `tokensReceived` hooks take precedence over [ERC-20]. Even with an [ERC-20] `transfer` and `transferFrom` call, the token contract MUST check via [ERC-1820] if the `from` and the `to` address implement `tokensToSend` and `tokensReceived` hook respectively. If any hook is implemented, it MUST be called. Note that when calling [ERC-20] `transfer` on a contract, if the contract does not implement `tokensReceived`, the `transfer` call SHOULD still be accepted even if this means the tokens will probably be locked. The table below summarizes the different actions the token contract MUST take when sending, minting and transferring token via [ERC-777] and [ERC-20]:

ERC1820	`to` address	ERC777 Sending And Minting	ERC20 `transfer`/`transferFrom`
`ERC777TokensRecipient` registered	regular address	MUST call `tokensReceived`
`ERC777TokensRecipient` registered	contract	MUST call `tokensReceived`
`ERC777TokensRecipient` not registered	regular address	continue
`ERC777TokensRecipient` not registered	contract	MUST `revert`	SHOULD continue¹

> 1. > The transaction SHOULD continue for clarity as ERC20 is not aware of hooks. > However, this can result in accidentally locked tokens. > If avoiding accidentally locked tokens is paramount, the transaction MAY revert. There is no particular action to take if `tokensToSend` is not implemented. The movement MUST proceed and only be canceled if another condition is not respected such as lack of funds or a `revert` in `tokensReceived` (if present). During a send, mint and burn, the respective `Sent`, `Minted` and `Burned` events MUST be emitted. Furthermore, if the token contract declares that it implements `ERC20Token` via [ERC-1820], the token contract SHOULD emit a `Transfer` event for minting and burning and MUST emit a `Transfer` event for sending (as specified in the [ERC-20] standard). During an [ERC-20]'s `transfer` or `transferFrom` functions, a valid `Sent` event MUST be emitted. Hence for any movement of tokens, two events MAY be emitted: an [ERC-20] `Transfer` and an [ERC-777] `Sent`, `Minted` or `Burned` (depending on the type of movement). Third-party developers MUST be careful not to consider both events as separate movements. As a general rule, if an application considers the token as an ERC20 token, then only the `Transfer` event MUST be taken into account. If the application considers the token as an ERC777 token, then only the `Sent`, `Minted` and `Burned` events MUST be considered. ## Test Cases The [repository with the reference implementation][0xjac/ERC777] contains all the [tests][ref tests]. ## Implementation The GitHub repository [0xjac/ERC777] contains the [reference implementation]. The reference implementation is also available via [npm][npm/erc777] and can be installed with `npm install erc777`. ## Copyright Copyright and related rights waived via [CC0](/LICENSE). [operators]: #operators [ERC-20]: ./eip-20.md [ERC-165]: ./eip-165.md [ERC-672]: https://github.com/ethereum/EIPs/issues/672 [ERC-777]: ./eip-777.md [ERC-820]: ./eip-820.md [ERC-820a]: https://github.com/ethereum/EIPs/pull/1758 [ERC-1820]: ./eip-1820.md [erc1820-set]: ./eip-1820.md#set-an-interface-for-an-address [0xjac]: https://github.com/0xjac [0xjac/ERC777]: https://github.com/0xjac/ERC777 [master thesis]: https://github.com/0xjac/master-thesis [npm/erc777]: https://www.npmjs.com/package/erc777 [ref tests]: https://github.com/0xjac/ERC777/blob/master/test/ReferenceToken.test.js [reference implementation]: https://github.com/0xjac/ERC777/blob/master/contracts/examples/ReferenceToken.sol [EIP-223]: https://github.com/ethereum/EIPs/issues/223 [eth_estimateGas]: https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_estimategas [authorizedoperator]: #authorizedoperator [revokedoperator]: #revokedoperator [isOperatorFor]: #isOperatorFor [defaultOperators]: #defaultOperators [sent]: #sent [minted]: #minted [burned]: #burned [logos]: https://github.com/ethereum/EIPs/tree/master/assets/eip-777/logo [beige logo]: ../assets/eip-777/logo/png/ERC-777-logo-beige-48px.png [white logo]: ../assets/eip-777/logo/png/ERC-777-logo-white-48px.png [light grey logo]: ../assets/eip-777/logo/png/ERC-777-logo-light_grey-48px.png [dark grey logo]: ../assets/eip-777/logo/png/ERC-777-logo-dark_grey-48px.png [black logo]: ../assets/eip-777/logo/png/ERC-777-logo-black-48px.png

Canary Standard

Sat, 16 Dec 2017 00:00:00 +0000

## Simple Summary A standard interface for canary contracts. ## Abstract The following standard allows the implementation of canaries within contracts. This standard provides basic functionality to check if a canary is alive, keeping the canary alive and optionally manage feeders. ## Motivation The canary can e.g. be used as a [warrant canary](https://en.wikipedia.org/wiki/Warrant_canary). A standard interface allows other applications to easily interface with canaries on Ethereum - e.g. for visualizing the state, automated alarms, applications to feed the canary or contracts (e.g. insurance) that use the state. ## Specification ### Methods #### isAlive() Returns if the canary was fed properly to signal e.g. that no warrant was received. ``` js function isAlive() constant returns (bool alive) ``` #### getBlockOfDeath() Returns the block the canary died. Throws if the canary is alive. ``` js function getBlockOfDeath() constant returns (uint256 block) ``` #### getType() Returns the type of the canary: * `1` = Simple (just the pure interface as defined in this ERC) * `2` = Single feeder (as defined in ERC-TBD) * `3` = Single feeder with bad food (as defined in ERC-TBD) * `4` = Multiple feeders (as defined in ERC-TBD) * `5` = Multiple mandatory feeders (as defined in ERC-TBD) * `6` = IOT (as defined in ERC-TBD) `1` might also be used for a special purpose contract that does not need a special type but still wants to expose the functions and provide events as defined in this ERC. ``` js function getType() constant returns (uint8 type) ``` ### Events #### RIP MUST trigger when the contract is called the first time after the canary died. ``` js event RIP() ``` ## Implementation TODO ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Pseudo-introspection Registry Contract

Fri, 05 Jan 2018 00:00:00 +0000

> :information_source: **[ERC-1820] has superseded [ERC-820].** :information_source: > [ERC-1820] fixes the incompatibility in the [ERC-165] logic which was introduced by the Solidty 0.5 update. > Have a look at the [official announcement][erc1820-annoucement], and the comments about the [bug][erc820-bug] and the [fix][erc820-fix]. > Apart from this fix, [ERC-1820] is functionally equivalent to [ERC-820]. > > :warning: [ERC-1820] MUST be used in lieu of [ERC-820]. :warning: ## Simple Summary This standard defines a universal registry smart contract where any address (contract or regular account) can register which interface it supports and which smart contract is responsible for its implementation. This standard keeps backward compatibility with [ERC-165]. ## Abstract This standard defines a registry where smart contracts and regular accounts can publish which functionalities they implement---either directly or through a proxy contract. Anyone can query this registry to ask if a specific address implements a given interface and which smart contract handles its implementation. This registry MAY be deployed on any chain and shares the same address on all chains. Interfaces with zeroes (`0`) as the last 28 bytes are considered [ERC-165] interfaces, and this registry SHALL forward the call to the contract to see if it implements the interface. This contract also acts as an [ERC-165] cache to reduce gas consumption. ## Motivation There have been different approaches to define pseudo-introspection in Ethereum. The first is [ERC-165] which has the limitation that it cannot be used by regular accounts. The second attempt is [ERC-672] which uses reverse [ENS]. Using reverse [ENS] has two issues. First, it is unnecessarily complicated, and second, [ENS] is still a centralized contract controlled by a multisig. This multisig theoretically would be able to modify the system. This standard is much simpler than [ERC-672], and it is *fully* decentralized. This standard also provides a *unique* address for all chains. Thus solving the problem of resolving the correct registry address for different chains. ## Specification ### [ERC-820] Registry Smart Contract > This is an exact copy of the code of the [ERC820 registry smart contract]. ``` solidity /* ERC820 Pseudo-introspection Registry Contract * This standard defines a universal registry smart contract where any address * (contract or regular account) can register which interface it supports and * which smart contract is responsible for its implementation. * * Written in 2018 by Jordi Baylina and Jacques Dafflon * * To the extent possible under law, the author(s) have dedicated all copyright * and related and neighboring rights to this software to the public domain * worldwide. This software is distributed without any warranty. * * You should have received a copy of the CC0 Public Domain Dedication along * with this software. If not, see * . * * ███████╗██████╗ ██████╗ █████╗ ██████╗ ██████╗ * ██╔════╝██╔══██╗██╔════╝██╔══██╗╚════██╗██╔═████╗ * █████╗ ██████╔╝██║ ╚█████╔╝ █████╔╝██║██╔██║ * ██╔══╝ ██╔══██╗██║ ██╔══██╗██╔═══╝ ████╔╝██║ * ███████╗██║ ██║╚██████╗╚█████╔╝███████╗╚██████╔╝ * ╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚════╝ ╚══════╝ ╚═════╝ * * ██████╗ ███████╗ ██████╗ ██╗███████╗████████╗██████╗ ██╗ ██╗ * ██╔══██╗██╔════╝██╔════╝ ██║██╔════╝╚══██╔══╝██╔══██╗╚██╗ ██╔╝ * ██████╔╝█████╗ ██║ ███╗██║███████╗ ██║ ██████╔╝ ╚████╔╝ * ██╔══██╗██╔══╝ ██║ ██║██║╚════██║ ██║ ██╔══██╗ ╚██╔╝ * ██║ ██║███████╗╚██████╔╝██║███████║ ██║ ██║ ██║ ██║ * ╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚═╝╚══════╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ * */ pragma solidity 0.4.24; // IV is value needed to have a vanity address starting with `0x820`. // IV: 9513 /// @dev The interface a contract MUST implement if it is the implementer of /// some (other) interface for any address other than itself. interface ERC820ImplementerInterface { /// @notice Indicates whether the contract implements the interface `interfaceHash` for the address `addr` or not. /// @param interfaceHash keccak256 hash of the name of the interface /// @param addr Address for which the contract will implement the interface /// @return ERC820_ACCEPT_MAGIC only if the contract implements `interfaceHash` for the address `addr`. function canImplementInterfaceForAddress(bytes32 interfaceHash, address addr) external view returns(bytes32); } /// @title ERC820 Pseudo-introspection Registry Contract /// @author Jordi Baylina and Jacques Dafflon /// @notice This contract is the official implementation of the ERC820 Registry. /// @notice For more details, see https://eips.ethereum.org/EIPS/eip-820 contract ERC820Registry { /// @notice ERC165 Invalid ID. bytes4 constant INVALID_ID = 0xffffffff; /// @notice Method ID for the ERC165 supportsInterface method (= `bytes4(keccak256('supportsInterface(bytes4)'))`). bytes4 constant ERC165ID = 0x01ffc9a7; /// @notice Magic value which is returned if a contract implements an interface on behalf of some other address. bytes32 constant ERC820_ACCEPT_MAGIC = keccak256(abi.encodePacked("ERC820_ACCEPT_MAGIC")); mapping (address => mapping(bytes32 => address)) interfaces; mapping (address => address) managers; mapping (address => mapping(bytes4 => bool)) erc165Cached; /// @notice Indicates a contract is the `implementer` of `interfaceHash` for `addr`. event InterfaceImplementerSet(address indexed addr, bytes32 indexed interfaceHash, address indexed implementer); /// @notice Indicates `newManager` is the address of the new manager for `addr`. event ManagerChanged(address indexed addr, address indexed newManager); /// @notice Query if an address implements an interface and through which contract. /// @param _addr Address being queried for the implementer of an interface. /// (If `_addr == 0` then `msg.sender` is assumed.) /// @param _interfaceHash keccak256 hash of the name of the interface as a string. /// E.g., `web3.utils.keccak256('ERC777Token')`. /// @return The address of the contract which implements the interface `_interfaceHash` for `_addr` /// or `0x0` if `_addr` did not register an implementer for this interface. function getInterfaceImplementer(address _addr, bytes32 _interfaceHash) external view returns (address) { address addr = _addr == 0 ? msg.sender : _addr; if (isERC165Interface(_interfaceHash)) { bytes4 erc165InterfaceHash = bytes4(_interfaceHash); return implementsERC165Interface(addr, erc165InterfaceHash) ? addr : 0; } return interfaces[addr][_interfaceHash]; } /// @notice Sets the contract which implements a specific interface for an address. /// Only the manager defined for that address can set it. /// (Each address is the manager for itself until it sets a new manager.) /// @param _addr Address to define the interface for. (If `_addr == 0` then `msg.sender` is assumed.) /// @param _interfaceHash keccak256 hash of the name of the interface as a string. /// For example, `web3.utils.keccak256('ERC777TokensRecipient')` for the `ERC777TokensRecipient` interface. /// @param _implementer Contract address implementing _interfaceHash for _addr. function setInterfaceImplementer(address _addr, bytes32 _interfaceHash, address _implementer) external { address addr = _addr == 0 ? msg.sender : _addr; require(getManager(addr) == msg.sender, "Not the manager"); require(!isERC165Interface(_interfaceHash), "Must not be a ERC165 hash"); if (_implementer != 0 && _implementer != msg.sender) { require( ERC820ImplementerInterface(_implementer) .canImplementInterfaceForAddress(_interfaceHash, addr) == ERC820_ACCEPT_MAGIC, "Does not implement the interface" ); } interfaces[addr][_interfaceHash] = _implementer; emit InterfaceImplementerSet(addr, _interfaceHash, _implementer); } /// @notice Sets the `_newManager` as manager for the `_addr` address. /// The new manager will be able to call `setInterfaceImplementer` for `_addr`. /// @param _addr Address for which to set the new manager. /// @param _newManager Address of the new manager for `addr`. function setManager(address _addr, address _newManager) external { require(getManager(_addr) == msg.sender, "Not the manager"); managers[_addr] = _newManager == _addr ? 0 : _newManager; emit ManagerChanged(_addr, _newManager); } /// @notice Get the manager of an address. /// @param _addr Address for which to return the manager. /// @return Address of the manager for a given address. function getManager(address _addr) public view returns(address) { // By default the manager of an address is the same address if (managers[_addr] == 0) { return _addr; } else { return managers[_addr]; } } /// @notice Compute the keccak256 hash of an interface given its name. /// @param _interfaceName Name of the interface. /// @return The keccak256 hash of an interface name. function interfaceHash(string _interfaceName) external pure returns(bytes32) { return keccak256(abi.encodePacked(_interfaceName)); } /* --- ERC165 Related Functions --- */ /* --- Developed in collaboration with William Entriken. --- */ /// @notice Updates the cache with whether the contract implements an ERC165 interface or not. /// @param _contract Address of the contract for which to update the cache. /// @param _interfaceId ERC165 interface for which to update the cache. function updateERC165Cache(address _contract, bytes4 _interfaceId) external { interfaces[_contract][_interfaceId] = implementsERC165InterfaceNoCache(_contract, _interfaceId) ? _contract : 0; erc165Cached[_contract][_interfaceId] = true; } /// @notice Checks whether a contract implements an ERC165 interface or not. /// The result may be cached, if not a direct lookup is performed. /// @param _contract Address of the contract to check. /// @param _interfaceId ERC165 interface to check. /// @return `true` if `_contract` implements `_interfaceId`, false otherwise. function implementsERC165Interface(address _contract, bytes4 _interfaceId) public view returns (bool) { if (!erc165Cached[_contract][_interfaceId]) { return implementsERC165InterfaceNoCache(_contract, _interfaceId); } return interfaces[_contract][_interfaceId] == _contract; } /// @notice Checks whether a contract implements an ERC165 interface or not without using nor updating the cache. /// @param _contract Address of the contract to check. /// @param _interfaceId ERC165 interface to check. /// @return `true` if `_contract` implements `_interfaceId`, false otherwise. function implementsERC165InterfaceNoCache(address _contract, bytes4 _interfaceId) public view returns (bool) { uint256 success; uint256 result; (success, result) = noThrowCall(_contract, ERC165ID); if (success == 0 || result == 0) { return false; } (success, result) = noThrowCall(_contract, INVALID_ID); if (success == 0 || result != 0) { return false; } (success, result) = noThrowCall(_contract, _interfaceId); if (success == 1 && result == 1) { return true; } return false; } /// @notice Checks whether the hash is a ERC165 interface (ending with 28 zeroes) or not. /// @param _interfaceHash The hash to check. /// @return `true` if the hash is a ERC165 interface (ending with 28 zeroes), `false` otherwise. function isERC165Interface(bytes32 _interfaceHash) internal pure returns (bool) { return _interfaceHash & 0x00000000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF == 0; } /// @dev Make a call on a contract without throwing if the function does not exist. function noThrowCall(address _contract, bytes4 _interfaceId) internal view returns (uint256 success, uint256 result) { bytes4 erc165ID = ERC165ID; assembly { let x := mload(0x40) // Find empty storage location using "free memory pointer" mstore(x, erc165ID) // Place signature at beginning of empty storage mstore(add(x, 0x04), _interfaceId) // Place first argument directly next to signature success := staticcall( 30000, // 30k gas _contract, // To addr x, // Inputs are stored at location x 0x08, // Inputs are 8 bytes long x, // Store output over input (saves space) 0x20 // Outputs are 32 bytes long ) result := mload(x) // Load the result } } } ``` ### Deployment Transaction Below is the raw transaction which MUST be used to deploy the smart contract on any chain. ``` 0xf90a2a8085174876e800830c35008080b909d7608060405234801561001057600080fd5b506109b7806100206000396000f30060806040526004361061008d5763ffffffff7c010000000000000000000000000000000000000000000000000000000060003504166329965a1d81146100925780633d584063146100bf5780635df8122f146100fc57806365ba36c114610123578063a41e7d5114610155578063aabbb8ca14610183578063b7056765146101a7578063f712f3e8146101e9575b600080fd5b34801561009e57600080fd5b506100bd600160a060020a036004358116906024359060443516610217565b005b3480156100cb57600080fd5b506100e0600160a060020a0360043516610512565b60408051600160a060020a039092168252519081900360200190f35b34801561010857600080fd5b506100bd600160a060020a036004358116906024351661055e565b34801561012f57600080fd5b506101436004803560248101910135610655565b60408051918252519081900360200190f35b34801561016157600080fd5b506100bd600160a060020a0360043516600160e060020a0319602435166106e3565b34801561018f57600080fd5b506100e0600160a060020a036004351660243561076d565b3480156101b357600080fd5b506101d5600160a060020a0360043516600160e060020a0319602435166107e7565b604080519115158252519081900360200190f35b3480156101f557600080fd5b506101d5600160a060020a0360043516600160e060020a03196024351661089c565b6000600160a060020a0384161561022e5783610230565b335b90503361023c82610512565b600160a060020a03161461029a576040805160e560020a62461bcd02815260206004820152600f60248201527f4e6f7420746865206d616e616765720000000000000000000000000000000000604482015290519081900360640190fd5b6102a38361091c565b156102f8576040805160e560020a62461bcd02815260206004820152601960248201527f4d757374206e6f74206265206120455243313635206861736800000000000000604482015290519081900360640190fd5b600160a060020a038216158015906103195750600160a060020a0382163314155b156104a15760405160200180807f4552433832305f4143434550545f4d414749430000000000000000000000000081525060130190506040516020818303038152906040526040518082805190602001908083835b6020831061038d5780518252601f19909201916020918201910161036e565b51815160209384036101000a6000190180199092169116179052604080519290940182900382207f249cb3fa000000000000000000000000000000000000000000000000000000008352600483018a9052600160a060020a0388811660248501529451909650938816945063249cb3fa936044808401945091929091908290030181600087803b15801561042057600080fd5b505af1158015610434573d6000803e3d6000fd5b505050506040513d602081101561044a57600080fd5b5051146104a1576040805160e560020a62461bcd02815260206004820181905260248201527f446f6573206e6f7420696d706c656d656e742074686520696e74657266616365604482015290519081900360640190fd5b600160a060020a03818116600081815260208181526040808320888452909152808220805473ffffffffffffffffffffffffffffffffffffffff19169487169485179055518692917f93baa6efbd2244243bfee6ce4cfdd1d04fc4c0e9a786abd3a41313bd352db15391a450505050565b600160a060020a03808216600090815260016020526040812054909116151561053c575080610559565b50600160a060020a03808216600090815260016020526040902054165b919050565b3361056883610512565b600160a060020a0316146105c6576040805160e560020a62461bcd02815260206004820152600f60248201527f4e6f7420746865206d616e616765720000000000000000000000000000000000604482015290519081900360640190fd5b81600160a060020a031681600160a060020a0316146105e557806105e8565b60005b600160a060020a03838116600081815260016020526040808220805473ffffffffffffffffffffffffffffffffffffffff19169585169590951790945592519184169290917f605c2dbf762e5f7d60a546d42e7205dcb1b011ebc62a61736a57c9089d3a43509190a35050565b60008282604051602001808383808284378201915050925050506040516020818303038152906040526040518082805190602001908083835b602083106106ad5780518252601f19909201916020918201910161068e565b6001836020036101000a038019825116818451168082178552505050505050905001915050604051809103902090505b92915050565b6106ed82826107e7565b6106f85760006106fa565b815b600160a060020a03928316600081815260208181526040808320600160e060020a031996909616808452958252808320805473ffffffffffffffffffffffffffffffffffffffff19169590971694909417909555908152600284528181209281529190925220805460ff19166001179055565b60008080600160a060020a038516156107865784610788565b335b91506107938461091c565b156107b85750826107a4828261089c565b6107af5760006107b1565b815b92506107df565b600160a060020a038083166000908152602081815260408083208884529091529020541692505b505092915050565b60008080610815857f01ffc9a70000000000000000000000000000000000000000000000000000000061093e565b9092509050811580610825575080155b1561083357600092506107df565b61084585600160e060020a031961093e565b909250905081158061085657508015155b1561086457600092506107df565b61086e858561093e565b90925090506001821480156108835750806001145b1561089157600192506107df565b506000949350505050565b600160a060020a0382166000908152600260209081526040808320600160e060020a03198516845290915281205460ff1615156108e4576108dd83836107e7565b90506106dd565b50600160a060020a03808316600081815260208181526040808320600160e060020a0319871684529091529020549091161492915050565b7bffffffffffffffffffffffffffffffffffffffffffffffffffffffff161590565b6040517f01ffc9a7000000000000000000000000000000000000000000000000000000008082526004820183905260009182919060208160088189617530fa9051909690955093505050505600a165627a7a723058204fc4461c9d5a247b0eafe0f9c508057bc0ad72bc24668cb2a35ea65850e10d3100291ba08208208208208208208208208208208208208208208208208208208208208200a00820820820820820820820820820820820820820820820820820820820820820 ``` The strings of `820`'s at the end of the transaction are the `r` and `s` of the signature. From this deterministic pattern (generated by a human), anyone can deduce that no one knows the private key for the deployment account. ### Deployment Method This contract is going to be deployed using the keyless deployment method---also known as [Nick]'s method---which relies on a single-use address. (See [Nick's article] for more details). This method works as follows: 1. Generate a transaction which deploys the contract from a new random account. - This transaction MUST NOT use [EIP-155] in order to work on any chain. - This transaction MUST have a relatively high gas price to be deployed on any chain. In this case, it is going to be 100 Gwei. 2. Set the `v`, `r`, `s` of the transaction signature to the following values: ``` v: 27 r: 0x8208208208208208208208208208208208208208208208208208208208208200 s: 0x0820820820820820820820820820820820820820820820820820820820820820 ``` Those `r` and `s` values---made of a repeating pattern of `820`'s---are predictable "random numbers" generated deterministically by a human. > The values of `r` and `s` must be 32 bytes long each---or 64 characters in hexadecimal. Since `820` is 3 characters long and 3 is not a divisor of 64, but it is a divisor of 63, the `r` and `s` values are padded with one extra character. > The `s` value is prefixed with a single zero (`0`). The `0` prefix also guarantees that `s < secp256k1n ÷ 2 + 1`. > The `r` value, cannot be prefixed with a zero, as the transaction becomes invalid. Instead it is suffixed with a zero (`0`) which still respects the condition `s < secp256k1n`. 3. We recover the sender of this transaction, i.e., the single-use deployment account. > Thus we obtain an account that can broadcast that transaction, but we also have the warranty that nobody knows the private key of that account. 4. Send exactly 0.08 ethers to this single-use deployment account. 5. Broadcast the deployment transaction. This operation can be done on any chain, guaranteeing that the contract address is always the same and nobody can use that address with a different contract. ### Single-use Registry Deployment Account ``` 0xE6C244a1C10Aa0085b0cf92f04cdaD947C2988b8 ``` This account is generated by reverse engineering it from its signature for the transaction. This way no one knows the private key, but it is known that it is the valid signer of the deployment transaction. > To deploy the registry, 0.08 ethers MUST be sent to this account *first*. ### Registry Contract Address ``` 0x820b586C8C28125366C998641B09DCbE7d4cBF06 ``` The contract has the address above for every chain on which it is deployed.

Raw metadata of ./contracts/ERC820Registry.sol

```json { "compiler": { "version": "0.4.24+commit.e67f0147" }, "language": "Solidity", "output": { "abi": [ { "constant": false, "inputs": [ { "name": "_addr", "type": "address" }, { "name": "_interfaceHash", "type": "bytes32" }, { "name": "_implementer", "type": "address" } ], "name": "setInterfaceImplementer", "outputs": [], "payable": false, "stateMutability": "nonpayable", "type": "function" }, { "constant": true, "inputs": [ { "name": "_addr", "type": "address" } ], "name": "getManager", "outputs": [ { "name": "", "type": "address" } ], "payable": false, "stateMutability": "view", "type": "function" }, { "constant": false, "inputs": [ { "name": "_addr", "type": "address" }, { "name": "_newManager", "type": "address" } ], "name": "setManager", "outputs": [], "payable": false, "stateMutability": "nonpayable", "type": "function" }, { "constant": true, "inputs": [ { "name": "_interfaceName", "type": "string" } ], "name": "interfaceHash", "outputs": [ { "name": "", "type": "bytes32" } ], "payable": false, "stateMutability": "pure", "type": "function" }, { "constant": false, "inputs": [ { "name": "_contract", "type": "address" }, { "name": "_interfaceId", "type": "bytes4" } ], "name": "updateERC165Cache", "outputs": [], "payable": false, "stateMutability": "nonpayable", "type": "function" }, { "constant": true, "inputs": [ { "name": "_addr", "type": "address" }, { "name": "_interfaceHash", "type": "bytes32" } ], "name": "getInterfaceImplementer", "outputs": [ { "name": "", "type": "address" } ], "payable": false, "stateMutability": "view", "type": "function" }, { "constant": true, "inputs": [ { "name": "_contract", "type": "address" }, { "name": "_interfaceId", "type": "bytes4" } ], "name": "implementsERC165InterfaceNoCache", "outputs": [ { "name": "", "type": "bool" } ], "payable": false, "stateMutability": "view", "type": "function" }, { "constant": true, "inputs": [ { "name": "_contract", "type": "address" }, { "name": "_interfaceId", "type": "bytes4" } ], "name": "implementsERC165Interface", "outputs": [ { "name": "", "type": "bool" } ], "payable": false, "stateMutability": "view", "type": "function" }, { "anonymous": false, "inputs": [ { "indexed": true, "name": "addr", "type": "address" }, { "indexed": true, "name": "interfaceHash", "type": "bytes32" }, { "indexed": true, "name": "implementer", "type": "address" } ], "name": "InterfaceImplementerSet", "type": "event" }, { "anonymous": false, "inputs": [ { "indexed": true, "name": "addr", "type": "address" }, { "indexed": true, "name": "newManager", "type": "address" } ], "name": "ManagerChanged", "type": "event" } ], "devdoc": { "author": "Jordi Baylina and Jacques Dafflon", "methods": { "getInterfaceImplementer(address,bytes32)": { "params": { "_addr": "Address being queried for the implementer of an interface. (If `_addr == 0` then `msg.sender` is assumed.)", "_interfaceHash": "keccak256 hash of the name of the interface as a string. E.g., `web3.utils.keccak256('ERC777Token')`." }, "return": "The address of the contract which implements the interface `_interfaceHash` for `_addr` or `0x0` if `_addr` did not register an implementer for this interface." }, "getManager(address)": { "params": { "_addr": "Address for which to return the manager." }, "return": "Address of the manager for a given address." }, "implementsERC165Interface(address,bytes4)": { "params": { "_contract": "Address of the contract to check.", "_interfaceId": "ERC165 interface to check." }, "return": "`true` if `_contract` implements `_interfaceId`, false otherwise." }, "implementsERC165InterfaceNoCache(address,bytes4)": { "params": { "_contract": "Address of the contract to check.", "_interfaceId": "ERC165 interface to check." }, "return": "`true` if `_contract` implements `_interfaceId`, false otherwise." }, "interfaceHash(string)": { "params": { "_interfaceName": "Name of the interface." }, "return": "The keccak256 hash of an interface name." }, "setInterfaceImplementer(address,bytes32,address)": { "params": { "_addr": "Address to define the interface for. (If `_addr == 0` then `msg.sender` is assumed.)", "_implementer": "Contract address implementing _interfaceHash for _addr.", "_interfaceHash": "keccak256 hash of the name of the interface as a string. For example, `web3.utils.keccak256('ERC777TokensRecipient')` for the `ERC777TokensRecipient` interface." } }, "setManager(address,address)": { "params": { "_addr": "Address for which to set the new manager.", "_newManager": "Address of the new manager for `addr`." } }, "updateERC165Cache(address,bytes4)": { "params": { "_contract": "Address of the contract for which to update the cache.", "_interfaceId": "ERC165 interface for which to update the cache." } } }, "title": "ERC820 Pseudo-introspection Registry Contract" }, "userdoc": { "methods": { "getInterfaceImplementer(address,bytes32)": { "notice": "Query if an address implements an interface and through which contract." }, "getManager(address)": { "notice": "Get the manager of an address." }, "implementsERC165Interface(address,bytes4)": { "notice": "Checks whether a contract implements an ERC165 interface or not. The result may be cached, if not a direct lookup is performed." }, "implementsERC165InterfaceNoCache(address,bytes4)": { "notice": "Checks whether a contract implements an ERC165 interface or not without using nor updating the cache." }, "interfaceHash(string)": { "notice": "Compute the keccak256 hash of an interface given its name." }, "setInterfaceImplementer(address,bytes32,address)": { "notice": "Sets the contract which implements a specific interface for an address. Only the manager defined for that address can set it. (Each address is the manager for itself until it sets a new manager.)" }, "setManager(address,address)": { "notice": "Sets the `_newManager` as manager for the `_addr` address. The new manager will be able to call `setInterfaceImplementer` for `_addr`." }, "updateERC165Cache(address,bytes4)": { "notice": "Updates the cache with whether the contract implements an ERC165 interface or not." } } } }, "settings": { "compilationTarget": { "./contracts/ERC820Registry.sol": "ERC820Registry" }, "evmVersion": "byzantium", "libraries": {}, "optimizer": { "enabled": true, "runs": 200 }, "remappings": [] }, "sources": { "./contracts/ERC820Registry.sol": { "content": "/* ERC820 Pseudo-introspection Registry Contract\n * This standard defines a universal registry smart contract where any address\n * (contract or regular account) can register which interface it supports and\n * which smart contract is responsible for its implementation.\n *\n * Written in 2018 by Jordi Baylina and Jacques Dafflon\n *\n * To the extent possible under law, the author(s) have dedicated all copyright\n * and related and neighboring rights to this software to the public domain\n * worldwide. This software is distributed without any warranty.\n *\n * You should have received a copy of the CC0 Public Domain Dedication along\n * with this software. If not, see\n * .\n *\n * ███████╗██████╗ ██████╗ █████╗ ██████╗ ██████╗\n * ██╔════╝██╔══██╗██╔════╝██╔══██╗╚════██╗██╔═████╗\n * █████╗ ██████╔╝██║ ╚█████╔╝ █████╔╝██║██╔██║\n * ██╔══╝ ██╔══██╗██║ ██╔══██╗██╔═══╝ ████╔╝██║\n * ███████╗██║ ██║╚██████╗╚█████╔╝███████╗╚██████╔╝\n * ╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚════╝ ╚══════╝ ╚═════╝\n *\n * ██████╗ ███████╗ ██████╗ ██╗███████╗████████╗██████╗ ██╗ ██╗\n * ██╔══██╗██╔════╝██╔════╝ ██║██╔════╝╚══██╔══╝██╔══██╗╚██╗ ██╔╝\n * ██████╔╝█████╗ ██║ ███╗██║███████╗ ██║ ██████╔╝ ╚████╔╝\n * ██╔══██╗██╔══╝ ██║ ██║██║╚════██║ ██║ ██╔══██╗ ╚██╔╝\n * ██║ ██║███████╗╚██████╔╝██║███████║ ██║ ██║ ██║ ██║\n * ╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚═╝╚══════╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝\n *\n */\npragma solidity 0.4.24;\n// IV is value needed to have a vanity address starting with `0x820`.\n// IV: 9513\n\n/// @dev The interface a contract MUST implement if it is the implementer of\n/// some (other) interface for any address other than itself.\ninterface ERC820ImplementerInterface {\n /// @notice Indicates whether the contract implements the interface `interfaceHash` for the address `addr` or not.\n /// @param interfaceHash keccak256 hash of the name of the interface\n /// @param addr Address for which the contract will implement the interface\n /// @return ERC820_ACCEPT_MAGIC only if the contract implements `interfaceHash` for the address `addr`.\n function canImplementInterfaceForAddress(bytes32 interfaceHash, address addr) external view returns(bytes32);\n}\n\n\n/// @title ERC820 Pseudo-introspection Registry Contract\n/// @author Jordi Baylina and Jacques Dafflon\n/// @notice This contract is the official implementation of the ERC820 Registry.\n/// @notice For more details, see https://eips.ethereum.org/EIPS/eip-820\ncontract ERC820Registry {\n /// @notice ERC165 Invalid ID.\n bytes4 constant INVALID_ID = 0xffffffff;\n /// @notice Method ID for the ERC165 supportsInterface method (= `bytes4(keccak256('supportsInterface(bytes4)'))`).\n bytes4 constant ERC165ID = 0x01ffc9a7;\n /// @notice Magic value which is returned if a contract implements an interface on behalf of some other address.\n bytes32 constant ERC820_ACCEPT_MAGIC = keccak256(abi.encodePacked(\"ERC820_ACCEPT_MAGIC\"));\n\n mapping (address => mapping(bytes32 => address)) interfaces;\n mapping (address => address) managers;\n mapping (address => mapping(bytes4 => bool)) erc165Cached;\n\n /// @notice Indicates a contract is the `implementer` of `interfaceHash` for `addr`.\n event InterfaceImplementerSet(address indexed addr, bytes32 indexed interfaceHash, address indexed implementer);\n /// @notice Indicates `newManager` is the address of the new manager for `addr`.\n event ManagerChanged(address indexed addr, address indexed newManager);\n\n /// @notice Query if an address implements an interface and through which contract.\n /// @param _addr Address being queried for the implementer of an interface.\n /// (If `_addr == 0` then `msg.sender` is assumed.)\n /// @param _interfaceHash keccak256 hash of the name of the interface as a string.\n /// E.g., `web3.utils.keccak256('ERC777Token')`.\n /// @return The address of the contract which implements the interface `_interfaceHash` for `_addr`\n /// or `0x0` if `_addr` did not register an implementer for this interface.\n function getInterfaceImplementer(address _addr, bytes32 _interfaceHash) external view returns (address) {\n address addr = _addr == 0 ? msg.sender : _addr;\n if (isERC165Interface(_interfaceHash)) {\n bytes4 erc165InterfaceHash = bytes4(_interfaceHash);\n return implementsERC165Interface(addr, erc165InterfaceHash) ? addr : 0;\n }\n return interfaces[addr][_interfaceHash];\n }\n\n /// @notice Sets the contract which implements a specific interface for an address.\n /// Only the manager defined for that address can set it.\n /// (Each address is the manager for itself until it sets a new manager.)\n /// @param _addr Address to define the interface for. (If `_addr == 0` then `msg.sender` is assumed.)\n /// @param _interfaceHash keccak256 hash of the name of the interface as a string.\n /// For example, `web3.utils.keccak256('ERC777TokensRecipient')` for the `ERC777TokensRecipient` interface.\n /// @param _implementer Contract address implementing _interfaceHash for _addr.\n function setInterfaceImplementer(address _addr, bytes32 _interfaceHash, address _implementer) external {\n address addr = _addr == 0 ? msg.sender : _addr;\n require(getManager(addr) == msg.sender, \"Not the manager\");\n\n require(!isERC165Interface(_interfaceHash), \"Must not be a ERC165 hash\");\n if (_implementer != 0 && _implementer != msg.sender) {\n require(\n ERC820ImplementerInterface(_implementer)\n .canImplementInterfaceForAddress(_interfaceHash, addr) == ERC820_ACCEPT_MAGIC,\n \"Does not implement the interface\"\n );\n }\n interfaces[addr][_interfaceHash] = _implementer;\n emit InterfaceImplementerSet(addr, _interfaceHash, _implementer);\n }\n\n /// @notice Sets the `_newManager` as manager for the `_addr` address.\n /// The new manager will be able to call `setInterfaceImplementer` for `_addr`.\n /// @param _addr Address for which to set the new manager.\n /// @param _newManager Address of the new manager for `addr`.\n function setManager(address _addr, address _newManager) external {\n require(getManager(_addr) == msg.sender, \"Not the manager\");\n managers[_addr] = _newManager == _addr ? 0 : _newManager;\n emit ManagerChanged(_addr, _newManager);\n }\n\n /// @notice Get the manager of an address.\n /// @param _addr Address for which to return the manager.\n /// @return Address of the manager for a given address.\n function getManager(address _addr) public view returns(address) {\n // By default the manager of an address is the same address\n if (managers[_addr] == 0) {\n return _addr;\n } else {\n return managers[_addr];\n }\n }\n\n /// @notice Compute the keccak256 hash of an interface given its name.\n /// @param _interfaceName Name of the interface.\n /// @return The keccak256 hash of an interface name.\n function interfaceHash(string _interfaceName) external pure returns(bytes32) {\n return keccak256(abi.encodePacked(_interfaceName));\n }\n\n /* --- ERC165 Related Functions --- */\n /* --- Developed in collaboration with William Entriken. --- */\n\n /// @notice Updates the cache with whether the contract implements an ERC165 interface or not.\n /// @param _contract Address of the contract for which to update the cache.\n /// @param _interfaceId ERC165 interface for which to update the cache.\n function updateERC165Cache(address _contract, bytes4 _interfaceId) external {\n interfaces[_contract][_interfaceId] = implementsERC165InterfaceNoCache(_contract, _interfaceId) ? _contract : 0;\n erc165Cached[_contract][_interfaceId] = true;\n }\n\n /// @notice Checks whether a contract implements an ERC165 interface or not.\n /// The result may be cached, if not a direct lookup is performed.\n /// @param _contract Address of the contract to check.\n /// @param _interfaceId ERC165 interface to check.\n /// @return `true` if `_contract` implements `_interfaceId`, false otherwise.\n function implementsERC165Interface(address _contract, bytes4 _interfaceId) public view returns (bool) {\n if (!erc165Cached[_contract][_interfaceId]) {\n return implementsERC165InterfaceNoCache(_contract, _interfaceId);\n }\n return interfaces[_contract][_interfaceId] == _contract;\n }\n\n /// @notice Checks whether a contract implements an ERC165 interface or not without using nor updating the cache.\n /// @param _contract Address of the contract to check.\n /// @param _interfaceId ERC165 interface to check.\n /// @return `true` if `_contract` implements `_interfaceId`, false otherwise.\n function implementsERC165InterfaceNoCache(address _contract, bytes4 _interfaceId) public view returns (bool) {\n uint256 success;\n uint256 result;\n\n (success, result) = noThrowCall(_contract, ERC165ID);\n if (success == 0 || result == 0) {\n return false;\n }\n\n (success, result) = noThrowCall(_contract, INVALID_ID);\n if (success == 0 || result != 0) {\n return false;\n }\n\n (success, result) = noThrowCall(_contract, _interfaceId);\n if (success == 1 && result == 1) {\n return true;\n }\n return false;\n }\n\n /// @notice Checks whether the hash is a ERC165 interface (ending with 28 zeroes) or not.\n /// @param _interfaceHash The hash to check.\n /// @return `true` if the hash is a ERC165 interface (ending with 28 zeroes), `false` otherwise.\n function isERC165Interface(bytes32 _interfaceHash) internal pure returns (bool) {\n return _interfaceHash & 0x00000000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF == 0;\n }\n\n /// @dev Make a call on a contract without throwing if the function does not exist.\n function noThrowCall(address _contract, bytes4 _interfaceId)\n internal view returns (uint256 success, uint256 result)\n {\n bytes4 erc165ID = ERC165ID;\n\n assembly {\n let x := mload(0x40) // Find empty storage location using \"free memory pointer\"\n mstore(x, erc165ID) // Place signature at beginning of empty storage\n mstore(add(x, 0x04), _interfaceId) // Place first argument directly next to signature\n\n success := staticcall(\n 30000, // 30k gas\n _contract, // To addr\n x, // Inputs are stored at location x\n 0x08, // Inputs are 8 bytes long\n x, // Store output over input (saves space)\n 0x20 // Outputs are 32 bytes long\n )\n\n result := mload(x) // Load the result\n }\n }\n}\n", "keccak256": "0x8eecce3912a15087b3f5845d5a74af7712c93d0a8fcd6f2d40f07ed5032022ab" } }, "version": 1 } ```

### Interface Name Any interface name is hashed using `keccak256` and sent to `getInterfaceImplementer()`. If the interface is part of a standard, it is best practice to explicitly state the interface name and link to this published [ERC-820] such that other people don't have to come here to look up these rules. For convenience, the registry provides a function to compute the hash on-chain: ``` solidity function interfaceHash(string _interfaceName) public pure returns(bytes32) ``` Compute the keccak256 hash of an interface given its name. > **identifier:** `65ba36c1` > **parameters** > `_interfaceName`: Name of the interface. > **returns:** The `keccak256` hash of an interface name. #### **Approved ERCs** If the interface is part of an approved ERC, it MUST be named `ERC###XXXXX` where `###` is the number of the ERC and XXXXX should be the name of the interface in CamelCase. The meaning of this interface SHOULD be defined in the specified ERC. Examples: - `keccak256("ERC20Token")` - `keccak256("ERC777Token")` - `keccak256("ERC777TokensSender")` - `keccak256("ERC777TokensRecipient")` #### **[ERC-165] Compatible Interfaces** > The compatibility with [ERC-165], including the [ERC165 Cache], has been designed and developed with [William Entriken]. Any interface where the last 28 bytes are zeroes (`0`) SHALL be considered an [ERC-165] interface. **[ERC-165] Lookup** Anyone can explicitly check if a contract implements an [ERC-165] interface using the registry by calling one of the two functions below: ``` solidity function implementsERC165Interface(address _contract, bytes4 _interfaceId) public view returns (bool) ``` Checks whether a contract implements an [ERC-165] interface or not. *NOTE*: The result is cached. If the cache is out of date, it MUST be updated by calling `updateERC165Cache`. (See [ERC165 Cache] for more details.) > **identifier:** `f712f3e8` > **parameters** > `_contract`: Address of the contract to check. > `_interfaceId`: [ERC-165] interface to check. > **returns:** `true` if `_contract` implements `_interfaceId`, false otherwise. ``` solidity function implementsERC165InterfaceNoCache(address _contract, bytes4 _interfaceId) public view returns (bool) ``` Checks whether a contract implements an [ERC-165] interface or not without using nor updating the cache. > **identifier:** `b7056765` > **parameters** > `_contract`: Address of the contract to check. > `_interfaceId`: [ERC-165] interface to check. > **returns:** `true` if `_contract` implements `_interfaceId`, false otherwise. **[ERC-165] Cache** Whether a contract implements an [ERC-165] interface or not can be cached manually to save gas. If a contract dynamically changes its interface and relies on the [ERC-165] cache of the [ERC-820] registry, the cache MUST be updated manually---there is no automatic cache invalidation or cache update. Ideally the contract SHOULD automatically update the cache when changing its interface. However anyone MAY update the cache on the contract's behalf. The cache update MUST be done using the `updateERC165Cache` function: ``` solidity function updateERC165Cache(address _contract, bytes4 _interfaceId) public ``` > **identifier:** `a41e7d51` > **parameters** > `_contract`: Address of the contract for which to update the cache. > `_interfaceId`: [ERC-165] interface for which to update the cache. #### **Private User-defined Interfaces** This scheme is extensible. You MAY make up your own interface name and raise awareness to get other people to implement it and then check for those implementations. Have fun but please, you MUST not conflict with the reserved designations above. ### Set An Interface For An Address For any address to set a contract as the interface implementation, it must call the following function of the [ERC-820] registry: ``` solidity function setInterfaceImplementer(address _addr, bytes32 _interfaceHash, address _implementer) public ``` Sets the contract which implements a specific interface for an address. Only the `manager` defined for that address can set it. (Each address is the manager for itself, see the [manager] section for more details.) *NOTE*: If `_addr` and `_implementer` are two different addresses, then: - The `_implementer` MUST implement the `ERC820ImplementerInterface` (detailed below). - Calling `canImplementInterfaceForAddress` on `_implementer` with the given `_addr` and `_interfaceHash` MUST return the `ERC820_ACCEPT_MAGIC` value. *NOTE*: The `_interfaceHash` MUST NOT be an [ERC-165] interface---it MUST NOT end with 28 zeroes (`0`). *NOTE*: The `_addr` MAY be `0`, then `msg.sender` is assumed. This default value simplifies interactions via multisigs where the data of the transaction to sign is constant regardless of the address of the multisig instance. > **identifier:** `29965a1d` > **parameters** > `_addr`: Address to define the interface for (if `_addr == 0` them `msg.sender`: is assumed) > `_interfaceHash`: `keccak256` hash of the name of the interface as a string, for example `web3.utils.keccak256('ERC777TokensRecipient')` for the ERC777TokensRecipient interface. > `_implementer`: Contract implementing `_interfaceHash` for `_addr`. ### Get An Implementation Of An Interface For An Address Anyone MAY query the [ERC-820] Registry to obtain the address of a contract implementing an interface on behalf of some address using the `getInterfaceImplementer` function. ``` solidity function getInterfaceImplementer(address _addr, bytes32 _interfaceHash) public view returns (address) ``` Query if an address implements an interface and through which contract. *NOTE*: If the last 28 bytes of the `_interfaceHash` are zeroes (`0`), then the first 4 bytes are considered an [ERC-165] interface and the registry SHALL forward the call to the contract at `_addr` to see if it implements the [ERC-165] interface (the first 4 bytes of `_interfaceHash`). The registry SHALL also cache [ERC-165] queries to reduce gas consumption. Anyone MAY call the `erc165UpdateCache` function to update whether a contract implements an interface or not. *NOTE*: The `_addr` MAY be `0`, then `msg.sender` is assumed. This default value is consistent with the behavior of the `setInterfaceImplementer` function and simplifies interactions via multisigs where the data of the transaction to sign is constant regardless of the address of the multisig instance. > **identifier:** `aabbb8ca` > **parameters** > `_addr`: Address being queried for the implementer of an interface. (If `_addr == 0` them `msg.sender` is assumed.) > `_interfaceHash`: keccak256 hash of the name of the interface as a string. E.g. `web3.utils.keccak256('ERC777Token')` > **returns:** The address of the contract which implements the interface `_interfaceHash` for `_addr` or `0x0` if `_addr` did not register an implementer for this interface. ### Interface Implementation (`ERC820ImplementerInterface`) ``` solidity interface ERC820ImplementerInterface { /// @notice Indicates whether the contract implements the interface `interfaceHash` for the address `addr`. /// @param addr Address for which the contract will implement the interface /// @param interfaceHash keccak256 hash of the name of the interface /// @return ERC820_ACCEPT_MAGIC only if the contract implements `ìnterfaceHash` for the address `addr`. function canImplementInterfaceForAddress(bytes32 interfaceHash, address addr) public view returns(bytes32); } ``` Any contract being registered as the implementation of an interface for a given address MUST implement said interface. In addition if it implements an interface on behalf of a different address, the contract MUST implement the `ERC820ImplementerInterface` shown above. ``` solidity function canImplementInterfaceForAddress(bytes32 interfaceHash, address addr) view public returns(bytes32); ``` Indicates whether a contract implements an interface (`interfaceHash`) for a given address (`addr`). If a contract implements the interface (`interfaceHash`) for a given address (`addr`), it MUST return `ERC820_ACCEPT_MAGIC` when called with the `addr` and the `interfaceHash`. If it does not implement the `interfaceHash` for a given address (`addr`), it MUST NOT return `ERC820_ACCEPT_MAGIC`. > **identifier:** `f0083250` > **parameters** > `interfaceHash`: Hash of the interface which is implemented > `addr`: Address for which the interface is implemented > **returns:** `ERC820_ACCEPT_MAGIC` only if the contract implements `ìnterfaceHash` for the address `addr`. The special value `ERC820_ACCEPT_MAGIC` is defined as the `keccka256` hash of the string `"ERC820_ACCEPT_MAGIC"`. ``` solidity bytes32 constant ERC820_ACCEPT_MAGIC = keccak256("ERC820_ACCEPT_MAGIC"); ``` > The reason to return `ERC820_ACCEPT_MAGIC` instead of a boolean is to prevent cases where a contract fails to implement the `canImplementInterfaceForAddress` but implements a fallback function which does not throw. In this case, since `canImplementInterfaceForAddress` does not exist, the fallback function is called instead, executed without throwing and returns `1`. Thus making it appear as if `canImplementInterfaceForAddress` returned `true`. ### Manager The manager of an address (regular account or a contract) is the only entity allowed to register implementations of interfaces for the address. By default, any address is its own manager. The manager can transfer its role to another address by calling `setManager` on the registry contract with the address for which to transfer the manager and the address of the new manager. **`setManager` Function** ``` solidity function setManager(address _addr, address _newManager) public ``` Sets the `_newManager` as manager for the `_addr` address. The new manager will be able to call `setInterfaceImplementer` for `_addr`. If `_newManager` is `0x0`, the manager is reset to `_addr` itself as the manager. > **identifier:** `5df8122f` > **parameters** > `_addr`: Address for which to set the new manager. > `_newManager`: The address of the new manager for `_addr`. (Pass `0x0` to reset the manager to `_addr`.) **`getManager` Function** ``` solidity function getManager(address _addr) public view returns(address) ``` Get the manager of an address. > **identifier:** `3d584063` > **parameters** > `_addr`: Address for which to return the manager. > **returns:** Address of the manager for a given address. ## Rationale This standards offers a way for any type of address (externally owned and contracts) to implement an interface and potentially delegate the implementation of the interface to a proxy contract. This delegation to a proxy contract is necessary for externally owned accounts and useful to avoid redeploying existing contracts such as multisigs and DAOs. The registry can also act as a [ERC-165] cache in order to save gas when looking up if a contract implements a specific [ERC-165] interface. This cache is intentionally kept simple, without automatic cache update or invalidation. Anyone can easily and safely update the cache for any interface and any contract by calling the `updateERC165Cache` function. The registry is deployed using a keyless deployment method relying on a single-use deployment address to ensure no one controls the registry, thereby ensuring trust. ## Backward Compatibility This standard is backward compatible with [ERC-165], as both methods MAY be implemented without conflicting with each other. ## Test Cases Please check the [jbaylina/ERC820] repository for the full test suite. ## Implementation The implementation is available in the repo: [jbaylina/ERC820]. ## Copyright Copyright and related rights waived via [CC0](/LICENSE). [EIP-155]: ./eip-155.md [ERC-165]: ./eip-165.md [ERC-672]: https://github.com/ethereum/EIPs/issues/672 [ERC-820]: ./eip-820.md [ERC820 registry smart contract]: https://github.com/jbaylina/ERC820/blob/master/contracts/ERC820Registry.sol [manager]: #manager [lookup]: #get-an-implementation-of-an-interface-for-an-address [ERC165 Cache]: #erc165-cache [Nick's article]: https://medium.com/@weka/how-to-send-ether-to-11-440-people-187e332566b7 [jbaylina/ERC820]: https://github.com/jbaylina/ERC820 [Nick]: https://github.com/Arachnid/ [William Entriken]: https://github.com/fulldecent [ENS]: https://ens.domains/ [ERC-1820]: ./eip-1820.md [erc1820-annoucement]: https://github.com/ethereum/EIPs/issues/820#issuecomment-464109166 [erc820-bug]: https://github.com/ethereum/EIPs/issues/820#issuecomment-452465748 [erc820-fix]: https://github.com/ethereum/EIPs/issues/820#issuecomment-454021564

Token Exchange Standard

Sat, 06 Jan 2018 00:00:00 +0000

## Simple Summary A standard for token contracts, providing token exchange services thereby facilitating cross token payments. ## Abstract The following standard provides functionally to make payments in the form of any other registered tokens, as well as allow token contracts to store any other tokens in an existing token contract. This standard allows ERC20 token holders to exchange their token with another ERC20 token and use the exchanged tokens to make payments. After a successful payment, the former specified ERC20 tokens, will be stored within the ERC20 token contract they are exchanged with. This proposal uses the term target contract which is used to denote the contract to the token with whom we want to exchange our tokens. ## Motivation Existing token standards do not provide functionality to exchange tokens. Existing token converters reduce the total supply of an existing token, which in the sense destroys the currency. Token converters do not solve this problem and hence discourages creation of new tokens. This solution does not destroy the existing token but in essence preserve them in the token contract that they are exchanged with, which in turn increases the market value of the latter. ## Specification ### Sender Interface This interface must be inherited by a ERC20 token contract that wants to exchange its tokens with another token. #### Storage Variables ##### exchnagedWith This mapping stores the number of tokens exchanged with another token, along with the latter’s address. Every time more tokens are exchanged the integer value is incremented consequently. This mapping acts as a record to denote which target contract holds our tokens. ```solidity mapping ( address => uint ) private exchangedWith; ``` ##### exchangedBy This mapping stores the address of the person who initiated the exchange and the amount of tokens exchanged. ```solidity mapping ( address => uint ) private exhangedBy; ``` #### Methods NOTE: Callers MUST handle false from returns (bool success). Callers MUST NOT assume that false is never returned! ##### exchangeToken This function calls the intermediate exchange service contract that handles the exchanges. This function takes the address of the target contract and the amount we want to exchange as parameters and returns boolean `success` and `creditedAmount`. ```solidity function exchangeToken(address _targetContract, uint _amount) public returns(bool success, uint creditedAmount) ``` ##### exchangeAndSpend This function calls an intermediate exchange service contract that handles exchange and expenditure. This function takes the address of the target contract, the amount we want to spend in terms of target contract tokens and address of the receiver as parameters and returns boolean `success`. ```solidity function exchangeAndSpend(address _targetContract, uint _amount,address _to) public returns(bool success) ``` ##### __exchangerCallback This function is called by the exchange service contract to our token contract to deduct calculated amount from our balance. It takes the address of the targert contract , the address of the person who exchanged the tokens and amount to be deducted from exchangers account as parameters and returns boolean `success`. NOTE: It is required that only the exchange service contract has the authority to call this function. ```solidity function __exchangerCallback(address _targetContract,address _exchanger, uint _amount) public returns(bool success) ``` #### Events ##### Exchange This event logs any new exchanges that have taken place. ```solidity event Exchange(address _from, address _ targetContract, uint _amount) ``` ##### ExchangeSpent This event logs any new exchange that have taken place and have been spent immediately. ```solidity event ExchangeSpent(address _from, address _targetContract, address _to, uint _amount) ``` ### Receiver Interface This interface must be inherited by a ERC20 token contract that wants to receive exchanged tokens. #### Storage Variables ##### exchangesRecieved This mapping stores the number of tokens received in terms of another token, along with its address. Every time more tokens are exchanged the integer value is incremented consequently. This mapping acts as a record to denote which tokens do this contract holds apart from its own. ```solidity mapping ( address => uint ) private exchnagesReceived; ``` #### Methods NOTE: Callers MUST handle false from returns (bool success). Callers MUST NOT assume that false is never returned! ##### __targetExchangeCallback This function is called by the intermediate exchange service contract. This function should add `_amount` tokens of the target contract to the exchangers address for exchange to be completed successfully. NOTE: It is required that only the exchange service contract has the authority to call this function. ```solidity function __targetExchangeCallback (uint _to, uint _amount) public returns(bool success) ``` ##### __targetExchangeAndSpendCallback This function is called by the intermediate exchange service contract. This function should add `_amount` tokens of the target contract to the exchangers address and transfer it to the `_to` address for the exchange and expenditure to be completed successfully. NOTE: It is required that only the exchange service contract has the authority to call this function. ```solidity function __targetExchangeAndSpendCallback (address _from, address _to, uint _amount) public returns(bool success) ``` #### Events ##### Exchange This event logs any new exchanges that have taken place. ```solidity event Exchange(address _from, address _with, uint _amount) ``` ##### ExchangeSpent This event logs any new exchange that have taken place and have been spent immediately. ```solidity event ExchangeSpent(address _from, address _ targetContract, address _to, uint _amount) ``` ### Exchange Service Contract This is an intermediate contract that provides a gateway for exchanges and expenditure. This contract uses oracles to get the authenticated exchange rates. #### Storage Variables ##### registeredTokens This array stores all the tokens that are registered for exchange. Only register tokens can participate in exchanges. ```solidity address[] private registeredTokens; ``` #### Methods ##### registerToken This function is called by the owner of the token contract to get it’s tokens registered. It takes the address of the token as the parameter and return boolean `success`. NOTE: Before any exchange it must be ensured that the token is registered. ```solidity function registerToken(address _token) public returns(bool success) ``` ##### exchangeToken This function is called by the token holder who wants to exchange his token with the `_targetContract` tokens. This function queries the exchange rate, calculates the converted amount, calls `__exchangerCallback` and calls the `__targetExchangeCallback`. It takes address of the target contract and amount to exchange as parameter and returns boolean `success` and amount credited. ```solidity function exchangeToken(address _targetContract, uint _amount, address _from) public returns(bool success, uint creditedAmount) ``` ##### exchangeAndSpend This function is called by the token holder who wants to exchange his token with the `_targetContract` tokens. This function queries the exchange rate, calculates the converted amount, calls `__exchangerCallback` and calls the `__targetExchangeAndSpendCallback`. It takes address of the target contract and amount to exchange as parameter and returns boolean `success` and amount credited. ```solidity function exchangeAndSpend(address _targetContract, uint _amount, address _from, address _to) public returns(bool success) ``` #### Events ##### Exchanges This event logs any new exchanges that have taken place. ```solidity event Exchange( address _from, address _by, uint _value ,address _target ) ``` ##### ExchangeAndSpent This event logs any new exchange that have taken place and have been spent immediately. ```solidity event ExchangeAndSpent ( address _from, address _by, uint _value ,address _target ,address _to) ``` ### Diagramatic Explanation #### Exchanging Tokens ![token-exchange-standard-visual-representation-1](../assets/eip-823/eip-823-token-exchange-standard-visual-representation-1.png) NOTE: After the successful exchange the contract on right owns some tokens of the contract on the left. #### Exchanging And Spending Tokens ![token-exchange-standard-visual-representation-2](../assets/eip-823/eip-823-token-exchange-standard-visual-representation-2.png) NOTE: After the successful exchange the contract on right owns some tokens of the contract on the left. ## Rationale Such a design provides a consistent exchange standard applicable to all ERC20 tokens that follow it. The primary advantage for of this strategy is that the exchanged tokens will not be lost. They can either be spent or preserved. Token convert face a major drawback of destroying tokens after conversion. This mechanism treats tokens like conventional currency where tokens are not destroyed but are stored. ## Backward Compatibility This proposal is fully backward compatible. Tokens extended by this proposal should also be following ERC20 standard. The functionality of ERC20 standard should not be affected by this proposal but will provide additional functionality to it. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

URI Format for Ethereum

Mon, 15 Jan 2018 00:00:00 +0000

## Abstract URIs embedded in QR-codes, hyperlinks in web-pages, emails or chat messages provide for robust cross-application signaling between very loosely coupled applications. A standardized URI format allows for instant invocation of the user's preferred wallet application. ## Specification ### Syntax Ethereum URIs contain "ethereum" or "eth" in their schema (protocol) part and are constructed as follows: request = "eth" [ "ereum" ] ":" [ prefix "-" ] payload prefix = STRING payload = STRING ### Semantics `prefix` is optional and defines the use-case for this URI. If no prefix is given: "pay-" is assumed to be concise and ensure backward compatibility to [EIP-67](./eip-67.md). When the prefix is omitted, the payload must start with `0x`. Also prefixes must not start with `0x`. So starting with `0x` can be used as a clear signal that there is no prefix. `payload` is mandatory and the content depends on the prefix. Structuring of the content is defined in the ERC for the specific use-case and not in the scope of this document. One example is [EIP-681](./eip-681) for the pay- prefix. ## Rationale The need for this ERC emerged when refining EIP-681. We need a container that does not carry the weight of the use-cases. EIP-67 was the first attempt on defining Ethereum-URIs. This ERC tries to keep backward compatibility and not break existing things. This means EIP-67 URIs should still be valid and readable. Only if the prefix feature is used, EIP-67 parsers might break. No way was seen to avoid this and innovate on the same time. This is also the reason this open prefix approach was chosen to being able to adopt to future use-cases and not block the whole "ethereum:" scheme for a limited set of use-cases that existed at the time of writing this. ## Security Considerations There are no known security considerations at this time. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

ABI specification for REVERT reason string

Thu, 20 Aug 2020 00:00:00 +0000

## Abstract This proposal specifies how to encode potential error conditions in the JSON ABI of a smart contract. A high-level language could then provide a syntax for declaring and throwing these errors. The compiler will encode these errors in the reason parameter of the REVERT opcode in a way that can be easily reconstructed by libraries such as web3. ## Motivation It's important to provide clear feedback to users (and developers) about what went wrong with their Ethereum transactions. The REVERT opcode is a step in the right direction, as it allows smart contract developers to encode a message describing the failure in the reason parameter. There is an implementation under review in Solidity that accepts a string, thus providing a low-level interface to this parameter. However, standardizing a method for passing errors from this parameter back to clients will bring many benefits to both users and developers. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. ## Specification To conform to this specification, compilers producing JSON ABIs SHOULD include error declarations alongside functions and events. Each error object MUST contain the keys name (string) and arguments (same types as the function’s inputs list). The value of type MUST be "error". Example: ``` { "type": "error", "name": "InsufficientBalance", "arguments": [ { "name": "amount", "type": "uint256" } ] } ``` A selector for this error can be computed from its signature (InsufficientBalance() for the example above) in the same way that it's currently done for public functions and events. This selector MUST be included in the reason string so that clients can perform a lookup. Any arguments for the error are RLP encoded in the same way as return values from functions. The exact format in which both the selector and the arguments are encoded is to be defined. The Solidity implementation mentioned above leaves room for expansion by prefixing the free-form string with uint256(0). A high-level language like Solidity can then implement a syntax like this: ``` contract MyToken { error InsufficientFunds(uint256 amount); function transfer(address _to, uint256 _amount) { if (balances[msg.sender] <= _amount) throw InsufficientFunds(_amount); ... } ... } ``` ### Possible extensions 1. A NatSpec comment above the error declaration can be used to provide a default error message. Arguments to the error can be interpolated in the message string with familiar NatSpec syntax. ``` /// @notice You don't have enough funds to transfer `amount`. error InsufficientFunds(uint256 amount); ``` 2. A function may declare to its callers which errors it can throw. A list of these errors must be included in the JSON ABI item for that function, under the `errors` key. Example: ``` function transfer(address _to, uint256 _amount) throws(InsufficientFunds); ``` Special consideration should be given to error overloading if we want to support a similar syntax in the future, as errors with same name but different arguments will produce a different selector. ## Rationale Needs discussion. ## Backwards Compatibility Apps and tools that have not implemented this spec can ignore the encoded reason string when it's not prefixed by zero. ## Security Considerations Needs discussion. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Simpler NFT standard with batching and native atomic swaps

Thu, 08 Feb 2018 00:00:00 +0000

## Summary A simple non fungible token standard that allows batching tokens into lots and settling p2p atomic transfers in one transaction. You can test out an example implementation on rinkeby here: https://rinkeby.etherscan.io/address/0xffab5ce7c012bc942f5ca0cd42c3c2e1ae5f0005 and view the repo here: https://github.com/alpha-wallet/ERC-Example ## Purpose While other standards allow the user to transfer a non-fungible token, they require one transaction per token, this is heavy on gas and partially responsible for clogging the ethereum network. There are also few definitions for how to do a simple atomic swap. ## Rinkeby example This standard has been implemented in an example contract on rinkeby: https://rinkeby.etherscan.io/address/0xffab5ce7c012bc942f5ca0cd42c3c2e1ae5f0005 ## Specification ### function name() constant returns (string name) returns the name of the contract e.g. CarLotContract ### function symbol() constant returns (string symbol) Returns a short string of the symbol of the in-fungible token, this should be short and generic as each token is non-fungible. ### function balanceOf(address _owner) public view returns (uint256[] balance) Returns an array of the users balance. ### function transfer(address _to, uint256[] _tokens) public; Transfer your unique tokens to an address by adding an array of the token indices. This compares favourable to ERC721 as you can transfer a bulk of tokens in one go rather than one at a time. This has a big gas saving as well as being more convenient. ### function transferFrom(address _from, address _to, uint256[] _tokens) public; Transfer a variable amount of tokens from one user to another. This can be done from an authorised party with a specified key e.g. contract owner. ## Optional functions ### function totalSupply() constant returns (uint256 totalSupply); Returns the total amount of tokens in the given contract, this should be optional as assets might be allocated and issued on the fly. This means that supply is not always fixed. ### function ownerOf(uint256 _tokenId) public view returns (address _owner); Returns the owner of a particular token, I think this should be optional as not every token contract will need to track the owner of a unique token and it costs gas to loop and map the token id owners each time the balances change. ### function trade(uint256 expiryTimeStamp, uint256[] tokenIndices, uint8 v, bytes32 r, bytes32 s) public payable A function which allows a user to sell a batch of non-fungible tokens without paying for the gas fee (only the buyer has to) in a p2p atomic swap. This is achieved by signing an attestation containing the amount of tokens to sell, the contract address, an expiry timestamp, the price and a prefix containing the ERC spec name and chain id. A buyer can then pay for the deal in one transaction by attaching the appropriate ether to satisfy the deal. This design is also more efficient as it allows orders to be done offline until settlement as opposed to creating orders in a smart contract and updating them. The expiry timestamp protects the seller against people using old orders. This opens up the gates for a p2p atomic swap but should be optional to this standard as some may not have use for it. Some protections need to be added to the message such as encoding the chain id, contract address and the ERC spec name to prevent replays and spoofing people into signing message that allow a trade. ## Interface ```solidity contract ERC165 { /// @notice Query if a contract implements an interface /// @param interfaceID The interface identifier, as specified in ERC-165 /// @dev Interface identification is specified in ERC-165. This function /// uses less than 30,000 gas. /// @return `true` if the contract implements `interfaceID` and /// `interfaceID` is not 0xffffffff, `false` otherwise function supportsInterface(bytes4 interfaceID) external view returns (bool); } interface ERC875 /* is ERC165 */ { event Transfer(address indexed _from, address indexed _to, uint256[] tokenIndices); function name() constant public returns (string name); function symbol() constant public returns (string symbol); function balanceOf(address _owner) public view returns (uint256[] _balances); function transfer(address _to, uint256[] _tokens) public; function transferFrom(address _from, address _to, uint256[] _tokens) public; } //If you want the standard functions with atomic swap trading added interface ERC875WithAtomicSwapTrading is ERC875 { function trade( uint256 expiryTimeStamp, uint256[] tokenIndices, uint8 v, bytes32 r, bytes32 s ) public payable; } ``` ## Example implementation Please visit this [repo](https://github.com/alpha-wallet/ERC875) to see an example implementation ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

DGCL Token

Wed, 14 Feb 2018 00:00:00 +0000

# Delaware General Corporations Law (DGCL) compatible share token Ref: [proposing-an-eip-for-DGCL-tokens](https://forum.ethereum.org/discussion/17200/proposing-an-eip-for-regulation-a-Tokens) ## Simple Summary An `ERC-20` compatible token that conforms to [Delaware State Senate, 149th General Assembly, Senate Bill No. 69: An act to Amend Title 8 of the Delaware Code Relating to the General Corporation Law](https://legis.delaware.gov/json/BillDetail/GenerateHtmlDocument?legislationId=25730&legislationTypeId=1&docTypeId=2&legislationName=SB69), henceforth referred to as 'The Act'. ## Abstract The recently amended 'Title 8 of the Delaware Code Relating to the General Corporation Law' now explicitly allows for the use of blockchains to maintain corporate share registries. This means it is now possible to create a tradable `ERC-20` token where each token represents a share issued by a Delaware corporation. Such a token must conform to the following principles over and above the `ERC-20` standard. 1. Token owners must have their identity verified. 2. The token contract must provide the following three functions of a `Corporations Stock ledger` (Ref: Section 224 of The Act): 1. Reporting: It must enable the corporation to prepare the list of shareholders specified in Sections 219 and 220 of The Act. 2. It must record the information specified in Sections 156, 159, 217(a) and 218 of The Act: - Partly paid shares - Total amount paid - Total amount to be paid 3. Transfers of shares as per section 159 of The Act: It must record transfers of shares as governed by Article 8 of subtitle I of Title 6. 3. Each token MUST correspond to a single share, each of which would be paid for in full, so there is no need to record information concerning partly paid shares, and there are no partial tokens. 4. There must be a mechanism to allow a shareholder who has lost their private key, or otherwise lost access to their tokens to have their address `cancelled` and the tokens re-issued to a new address. ## Motivation 1. Delaware General Corporation Law requires that shares issued by a Delaware corporation be recorded in a share registry. 2. The share registry can be represented by an `ERC-20` token contract that is compliant with Delaware General Corporation Law. 3. This standard can cover equity issued by any Delaware corporation, whether private or public. By using a `DGCL` compatible token, a firm may be able to raise funds via IPO, conforming to Delaware Corporations Law, but bypassing the need for involvement of a traditional Stock Exchange. There are currently no token standards that conform to the `DGCL` rules. `ERC-20` tokens do not support KYC/AML rules required by the General Corporation Law, and do not provide facilities for the exporting of lists of shareholders. ### What about ERC-721? The proposed standard could easily be used to enhance `ERC-721`, adding features for associating tokens with assets such as share certificates. While the `ERC-721` token proposal allows for some association of metadata with an Ethereum address, its uses are _not completely aligned_ with The Act, and it is not, in its current form, fully `ERC-20` compatible. ## Specification The `ERC-20` token provides the following basic features: contract ERC20 { function totalSupply() public view returns (uint256); function balanceOf(address who) public view returns (uint256); function transfer(address to, uint256 value) public returns (bool); function allowance(address owner, address spender) public view returns (uint256); function transferFrom(address from, address to, uint256 value) public returns (bool); function approve(address spender, uint256 value) public returns (bool); event Approval(address indexed owner, address indexed spender, uint256 value); event Transfer(address indexed from, address indexed to, uint256 value); } This will be extended as follows: /** * An `ERC20` compatible token that conforms to Delaware State Senate, * 149th General Assembly, Senate Bill No. 69: An act to Amend Title 8 * of the Delaware Code Relating to the General Corporation Law. * * Implementation Details. * * An implementation of this token standard SHOULD provide the following: * * `name` - for use by wallets and exchanges. * `symbol` - for use by wallets and exchanges. * * The implementation MUST take care not to allow unauthorised access to * share-transfer functions. * * In addition to the above the following optional `ERC20` function MUST be defined. * * `decimals` — MUST return `0` as each token represents a single share and shares are non-divisible. * * @dev Ref https://github.com/ethereum/EIPs/pull/884 */ contract ERC884 is ERC20 { /** * This event is emitted when a verified address and associated identity hash are * added to the contract. * @param addr The address that was added. * @param hash The identity hash associated with the address. * @param sender The address that caused the address to be added. */ event VerifiedAddressAdded( address indexed addr, bytes32 hash, address indexed sender ); /** * This event is emitted when a verified address and associated identity hash are * removed from the contract. * @param addr The address that was removed. * @param sender The address that caused the address to be removed. */ event VerifiedAddressRemoved(address indexed addr, address indexed sender); /** * This event is emitted when the identity hash associated with a verified address is updated. * @param addr The address whose hash was updated. * @param oldHash The identity hash that was associated with the address. * @param hash The hash now associated with the address. * @param sender The address that caused the hash to be updated. */ event VerifiedAddressUpdated( address indexed addr, bytes32 oldHash, bytes32 hash, address indexed sender ); /** * This event is emitted when an address is cancelled and replaced with * a new address. This happens in the case where a shareholder has * lost access to their original address and needs to have their share * reissued to a new address. This is the equivalent of issuing replacement * share certificates. * @param original The address being superseded. * @param replacement The new address. * @param sender The address that caused the address to be superseded. */ event VerifiedAddressSuperseded( address indexed original, address indexed replacement, address indexed sender ); /** * Add a verified address, along with an associated verification hash to the contract. * Upon successful addition of a verified address, the contract must emit * `VerifiedAddressAdded(addr, hash, msg.sender)`. * It MUST throw if the supplied address or hash are zero, or if the address has already been supplied. * @param addr The address of the person represented by the supplied hash. * @param hash A cryptographic hash of the address holder's verified information. */ function addVerified(address addr, bytes32 hash) public; /** * Remove a verified address, and the associated verification hash. If the address is * unknown to the contract then this does nothing. If the address is successfully removed, this * function must emit `VerifiedAddressRemoved(addr, msg.sender)`. * It MUST throw if an attempt is made to remove a verifiedAddress that owns tokens. * @param addr The verified address to be removed. */ function removeVerified(address addr) public; /** * Update the hash for a verified address known to the contract. * Upon successful update of a verified address the contract must emit * `VerifiedAddressUpdated(addr, oldHash, hash, msg.sender)`. * If the hash is the same as the value already stored then * no `VerifiedAddressUpdated` event is to be emitted. * It MUST throw if the hash is zero, or if the address is unverified. * @param addr The verified address of the person represented by the supplied hash. * @param hash A new cryptographic hash of the address holder's updated verified information. */ function updateVerified(address addr, bytes32 hash) public; /** * Cancel the original address and reissue the tokens to the replacement address. * Access to this function MUST be strictly controlled. * The `original` address MUST be removed from the set of verified addresses. * Throw if the `original` address supplied is not a shareholder. * Throw if the `replacement` address is not a verified address. * Throw if the `replacement` address already holds tokens. * This function MUST emit the `VerifiedAddressSuperseded` event. * @param original The address to be superseded. This address MUST NOT be reused. */ function cancelAndReissue(address original, address replacement) public; /** * The `transfer` function MUST NOT allow transfers to addresses that * have not been verified and added to the contract. * If the `to` address is not currently a shareholder then it MUST become one. * If the transfer will reduce `msg.sender`'s balance to 0 then that address * MUST be removed from the list of shareholders. */ function transfer(address to, uint256 value) public returns (bool); /** * The `transferFrom` function MUST NOT allow transfers to addresses that * have not been verified and added to the contract. * If the `to` address is not currently a shareholder then it MUST become one. * If the transfer will reduce `from`'s balance to 0 then that address * MUST be removed from the list of shareholders. */ function transferFrom(address from, address to, uint256 value) public returns (bool); /** * Tests that the supplied address is known to the contract. * @param addr The address to test. * @return true if the address is known to the contract. */ function isVerified(address addr) public view returns (bool); /** * Checks to see if the supplied address is a shareholder. * @param addr The address to check. * @return true if the supplied address owns a token. */ function isHolder(address addr) public view returns (bool); /** * Checks that the supplied hash is associated with the given address. * @param addr The address to test. * @param hash The hash to test. * @return true if the hash matches the one supplied with the address in `addVerified`, or `updateVerified`. */ function hasHash(address addr, bytes32 hash) public view returns (bool); /** * The number of addresses that hold tokens. * @return the number of unique addresses that hold tokens. */ function holderCount() public view returns (uint); /** * By counting the number of token holders using `holderCount` * you can retrieve the complete list of token holders, one at a time. * It MUST throw if `index >= holderCount()`. * @param index The zero-based index of the holder. * @return the address of the token holder with the given index. */ function holderAt(uint256 index) public view returns (address); /** * Checks to see if the supplied address was superseded. * @param addr The address to check. * @return true if the supplied address was superseded by another address. */ function isSuperseded(address addr) public view returns (bool); /** * Gets the most recent address, given a superseded one. * Addresses may be superseded multiple times, so this function needs to * follow the chain of addresses until it reaches the final, verified address. * @param addr The superseded address. * @return the verified address that ultimately holds the share. */ function getCurrentFor(address addr) public view returns (address); } ### Securities Exchange Commission Requirements The Securities Exchange Commission (SEC) has additional requirements as to how a crowdsale ought to be run and what information must be made available to the general public. This information is however out of scope from this standard, though the standard does support the requirements. For example: The SEC requires a crowdsale's website display the amount of money raised in US Dollars. To support this a crowdsale contract minting these tokens must maintain a USD to ETH conversion rate (via Oracle or some other mechanism) and must record the conversion rate used at time of minting. Also, depending on the type of raise, the SEC (or other statutory body) can apply limits to the number of shareholders allowed. To support this the standard provides the `holderCount` and `isHolder` functions which a crowdsale can invoke to check that limits have not been exceeded. ### Use of the Identity `hash` value Implementers of a crowdsale, in order to comply with The Act, must be able to produce an up-to-date list of the names and addresses of all shareholders. It is not desirable to include those details in a public blockchain, both for reasons of privacy, and also for reasons of economy. Storing arbitrary string data on the blockchain is strongly discouraged. Implementers should maintain an off-chain private database that records the owner's name, residential address, and Ethereum address. The implementer must then be able to extract the name and address for any address, and hash the name + address data and compare that hash to the hash recorded in the contract using the `hasHash` function. The specific details of this system are left to the implementer. It is also desirable that the implementers offer a REST API endpoint along the lines of GET https:////:ethereumAddress -> [true|false] to enable third party auditors to verify that a given Ethereum address is known to the implementers as a verified address. How the implementers verify a person's identity is up to them and beyond the scope of this standard. ### Handling users who have lost access to their addresses A traditional share register is typically managed by a Transfer Agent who is authorised to maintain the register accurately, and to handle shareholder enquiries. A common request is for share certificates to be reissued in the case where the shareholder has lost or destroyed their original. Token implementers can handle that via the `cancelAndReissue` function, which must perform the various changes to ensure that the old address now points to the new one, and that cancelled addresses are not then reused. ### Permissions management It is not desirable that anyone can add, remove, update, or supersede verified addresses. How access to these functions is controlled is outside of the scope of this standard. ## Rationale The proposed standard offers as minimal an extension as possible over the existing `ERC-20` standard in order to conform to the requirements of The Act. Rather than return a `bool` for successful or unsuccessful completion of state-changing functions such as `addVerified`, `removeVerified`, and `updateVerified`, we have opted to require that implementations `throw` (preferably by using the [forthcoming `require(condition, 'fail message')` syntax](https://github.com/ethereum/solidity/issues/1686#issuecomment-328181514)). ## Backwards Compatibility The proposed standard is designed to maintain compatibility with `ERC-20` tokens with the following provisos: 1. The `decimals` function MUST return `0` as the tokens MUST NOT be divisible, 2. The `transfer` and `transferFrom` functions MUST NOT allow transfers to non-verified addresses, and MUST maintain a list of shareholders. 3. Shareholders who transfer away their remaining tokens must be pruned from the list of shareholders. Proviso 1 will not break compatibility with modern wallets or exchanges as they all appear to use that information if available. Proviso 2 will cause transfers to fail if an attempt is made to transfer tokens to a non-verified address. This is implicit in the design and implementers are encouraged to make this abundantly clear to market participants. We appreciate that this will make the standard unpalatable to some exchanges, but it is an SEC requirement that shareholders of a corporation provide verified names and addresses. Proviso 3 is an implementation detail. ## Test Cases and Reference Implementation Test cases and a reference implementation are available at [github.com/davesag/ERC884-reference-implementation](https://github.com/davesag/ERC884-reference-implementation). ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

DelegateProxy

Wed, 21 Feb 2018 00:00:00 +0000

## Simple Summary Proxy contracts are being increasingly used as both as an upgradeability mechanism and a way to save gas when deploying many instances of a particular contract. This standard proposes a set of interfaces for proxies to signal how they work and what their main implementation is. ## Abstract Using proxies that delegate their own logic to another contract is becoming an increasingly popular technique for both smart contract upgradeability and creating cheap clone contracts. We don't believe there is value in standardizing any particular implementation of a DelegateProxy, given its simplicity, but we believe there is a lot of value in agreeing on an interface all proxies use that allows for a standard way to operate with proxies. ## Implementations - **aragonOS**: [AppProxyUpgradeable](https://github.com/aragon/aragonOS/blob/master/contracts/apps/AppProxyUpgradeable.sol), [AppProxyPinned](https://github.com/aragon/aragonOS/blob/master/contracts/apps/AppProxyPinned.sol) and [KernelProxy](https://github.com/aragon/aragonOS/blob/master/contracts/kernel/KernelProxy.sol) - **zeppelinOS**: [Proxy](https://github.com/zeppelinos/labs/blob/2da9e859db81a61f2449d188e7193788ca721c65/upgradeability_ownership/contracts/Proxy.sol) ## Standardized interface ```solidity interface ERCProxy { function proxyType() public pure returns (uint256 proxyTypeId); function implementation() public view returns (address codeAddr); } ``` ### Code address (`implementation()`) The returned code address is the address the proxy would delegate calls to at that moment in time, for that message. ### Proxy Type (`proxyType()`) Checking the proxy type is the way to check whether a contract is a proxy at all. When a contract fails to return to this method or it returns 0, it can be assumed that the contract is not a proxy. It also allows for communicating a bit more of information about how the proxy operates. It is a pure function, therefore making it effectively constant as it cannot return a different value depending on state changes. - **Forwarding proxy** (`id = 1`): The proxy will always forward to the same code address. The following invariant should always be true: once the proxy returns a non-zero code address, that code address should never change. - **Upgradeable proxy** (`id = 2`): The proxy code address can be changed depending on some arbitrary logic implemented either at the proxy level or in its forwarded logic. ## Benefits - **Source code verification**: right now when checking the code of a proxy in explorers like Etherscan, it just shows the code in the proxy itself but not the actual code of the contract. By standardizing this construct, they will be able to show both the actual ABI and code for the contract. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Simple Staking Interface

Thu, 22 Feb 2018 00:00:00 +0000

## Abstract The following standard describes a common staking interface allowing for easy to use staking systems. The interface is kept simple allowing for various use cases to be implemented. This standard describes the common functionality for staking as well as providing information on stakes. ## Motivation As we move to more token models, having a common staking interface which is familiar to users can be useful. The common interface can be used by a variety of applications, this common interface could be beneficial especially to things like Token curated registries which have recently gained popularity. ## Specification ```solidity interface Staking { event Staked(address indexed user, uint256 amount, uint256 total, bytes data); event Unstaked(address indexed user, uint256 amount, uint256 total, bytes data); function stake(uint256 amount, bytes data) public; function stakeFor(address user, uint256 amount, bytes data) public; function unstake(uint256 amount, bytes data) public; function totalStakedFor(address addr) public view returns (uint256); function totalStaked() public view returns (uint256); function token() public view returns (address); function supportsHistory() public pure returns (bool); // optional function lastStakedFor(address addr) public view returns (uint256); function totalStakedForAt(address addr, uint256 blockNumber) public view returns (uint256); function totalStakedAt(uint256 blockNumber) public view returns (uint256); } ``` ### stake Stakes a certain amount of tokens, this MUST transfer the given amount from the user. *The data field can be used to add signalling information in more complex staking applications* MUST trigger ```Staked``` event. ### stakeFor Stakes a certain amount of tokens, this MUST transfer the given amount from the caller. *The data field can be used to add signalling information in more complex staking applications* MUST trigger ```Staked``` event. ### unstake Unstakes a certain amount of tokens, this SHOULD return the given amount of tokens to the user, if unstaking is currently not possible the function MUST revert. *The data field can be used to remove signalling information in more complex staking applications* MUST trigger ```Unstaked``` event. ### totalStakedFor Returns the current total of tokens staked for an address. ### totalStaked Returns the current total of tokens staked. ### token Address of the token being used by the staking interface. ### supportsHistory MUST return true if the optional history functions are implemented, otherwise false. ### lastStakedFor ***OPTIONAL:** As not all staking systems require a complete history, this function is optional.* Returns last block address staked at. ### totalStakedForAt ***OPTIONAL:** As not all staking systems require a complete history, this function is optional.* Returns total amount of tokens staked at block for address. ### totalStakedAt ***OPTIONAL:** As not all staking systems require a complete history, this function is optional.* Returns the total tokens staked at block. ## Implementation - [Stakebank](https://github.com/HarbourProject/stakebank) - [Aragon](https://github.com/aragon/aragon-apps/pull/101) - [PoS Staking](https://github.com/maticnetwork/contracts/blob/master/contracts/StakeManager.sol) - [BasicStakeContract](https://github.com/codex-protocol/contract.erc-900) ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Token Validation

Wed, 14 Feb 2018 00:00:00 +0000

# Simple Summary A protocol for services providing token ownership and transfer validation. # Abstract This standard provides a registry contract method for authorizing token transfers. By nature, this covers both initially issuing tokens to users (ie: transfer from contract to owner), transferring tokens between users, and token spends. # Motivation The tokenization of assets has wide application, not least of which is financial instruments such as securities and security tokens. Most jurisdictions have placed legal constraints on what may be traded, and who can hold such tokens which are regarded as securities. Broadly this includes KYC and AML validation, but may also include time-based spend limits, total volume of transactions, and so on. Regulators and sanctioned third-party compliance agencies need some way to link off-chain compliance information such as identity and residency to an on-chain service. The application of this design is broader than legal regulation, encompassing all manner of business logic permissions for the creation, management, and trading of tokens. Rather than each token maintaining its own whitelist (or other mechanism), it is preferable to share on-chain resources, rules, lists, and so on. There is also a desire to aggregate data and rules spread across multiple validators, or to apply complex behaviours (ex. switching logic, gates, state machines) to apply distributed data to an application. # Specification ## `TokenValidator` ```solidity interface TokenValidator { function check( address _token, address _subject ) public returns(byte statusCode) function check( address _token, address _from, address _to, uint256 _amount ) public returns (byte statusCode) } ``` ### Methods #### `check`/2 `function check(address _token, address _subject) public returns (byte _resultCode)` > parameters > * `_token`: the token under review > * `_subject`: the user or contract to check > > *returns* an ERC1066 status code #### `check`/4 `function check(address token, address from, address to, uint256 amount) public returns (byte resultCode)` > parameters > * `_token`: the token under review > * `_from`: in the case of a transfer, who is relinquishing token ownership > * `_to`: in the case of a transfer, who is accepting token ownership > * `_amount`: The number of tokens being transferred > > *returns* an ERC1066 status code ## `ValidatedToken` ```solidity interface ValidatedToken { event Validation( address indexed subject, byte indexed result ) event Validation( address indexed from, address indexed to, uint256 value, byte indexed statusCode ) } ``` ### Events #### `Validation`/2 `event Validation(address indexed subject, byte indexed resultCode)` This event MUST be fired on return from a call to a `TokenValidator.check/2`. > parameters > * `subject`: the user or contract that was checked > * `statusCode`: an ERC1066 status code #### `Validation`/4 ```solidity event Validation( address indexed from, address indexed to, uint256 amount, byte indexed statusCode ) ``` This event MUST be fired on return from a call to a `TokenValidator.check/4`. > parameters > * `from`: in the case of a transfer, who is relinquishing token ownership > * `to`: in the case of a transfer, who is accepting token ownership > * `amount`: The number of tokens being transferred > * `statusCode`: an ERC1066 status code # Rationale This proposal includes a financial permissions system on top of any financial token. This design is not a general roles/permission system. In any system, the more you know about the context where a function will be called, the more powerful your function can be. By restricting ourselves to token transfers (ex. ERC20 or EIP-777), we can make assumptions about the use cases our validators will need to handle, and can make the API both small, useful, and extensible. The events are fired by the calling token. Since `Validator`s may aggregate or delegate to other `Validator`s, it would generate a lot of useless events were it the `Validator`'s responsibility. This is also the reason why we include the `token` in the `call/4` arguments: a `Validator` cannot rely on `msg.sender` to determine the token that the call is concerning. We have also seen a similar design from [R-Token](https://github.com/harborhq/r-token) that uses an additional field: `spender`. While there are potential use cases for this, it's not widely used enough to justify passing a dummy value along with every call. Instead, such a call would look more like this: ```solidity function approve(address spender, uint amount) public returns (bool success) { if (validator.check(this, msg.sender, spender, amount) == okStatusCode) { allowed[msg.sender][spender] = amount; Approval(msg.sender, spender, amount); return true; } else { return false; } } ``` A second `check/2` function is also required, that is more general-purpose, and does not specify a transfer amount or recipient. This is intended for general checks, such as checking roles (admin, owner, &c), or if a user is on a simple whitelist. We have left the decision to make associated `Validator` addresses public, private, or hardcoded up to the implementer. The proposed design does not include a centralized registry. It also does not include an interface for a `Validated` contract. A token may require one or many `Validator`s for different purposes, requiring different validations for different, or just a single `Validator`. The potential use cases are too varied to provide a single unified set of methods. We have provided a set of example contracts [here](https://github.com/Finhaven/ValidatedToken/) that may be inherited from for common use cases. The status codes in the `byte` returns are unspecified. Any status code scheme may be used, though a general status code proposal is fortcoming. By only defining the validation check, this standard is widely compatible with ERC-20, EIP-721, EIP-777, future token standards, centralized and decentralized exchanges, and so on. # Implementation [Reference implementation](https://github.com/expede/validated-token/) # Copyright Copyright and related rights waived via [CC0](/LICENSE).

Mineable Token Standard

Wed, 07 Mar 2018 00:00:00 +0000

### Simple Summary A specification for a standardized Mineable Token that uses a Proof of Work algorithm for distribution. ### Abstract This specification describes a method for initially locking tokens within a token contract and slowly dispensing them with a mint() function which acts like a faucet. This mint() function uses a Proof of Work algorithm in order to minimize gas fees and control the distribution rate. Additionally, standardization of mineable tokens will give rise to standardized CPU and GPU token mining software, token mining pools and other external tools in the token mining ecosystem. ### Motivation Token distribution via the ICO model and its derivatives is susceptible to illicit behavior by human actors. Furthermore, new token projects are centralized because a single entity must handle and control all of the initial coins and all of the raised ICO money. By distributing tokens via an 'Initial Mining Offering' (or IMO), the ownership of the token contract no longer belongs with the deployer at all and the deployer is 'just another user.' As a result, investor risk exposure utilizing a mined token distribution model is significantly diminished. This standard is intended to be standalone, allowing maximum interoperability with ERC20, ERC721, and others. ### Specification #### Interface The general behavioral specification includes a primary function that defines the token minting operation, an optional merged minting operation for issuing multiple tokens, getters for challenge number, mining difficulty, mining target and current reward, and finally a Mint event, to be emitted upon successful solution validation and token issuance. At a minimum, contracts must adhere to this interface (save the optional merge operation). It is recommended that contracts interface with the more behaviorally defined Abstract Contract described below, in order to leverage a more defined construct, allowing for easier external implementations via overridden phased functions. (see 'Abstract Contract' below) ``` solidity interface ERC918 { function mint(uint256 nonce) public returns (bool success); function getAdjustmentInterval() public view returns (uint); function getChallengeNumber() public view returns (bytes32); function getMiningDifficulty() public view returns (uint); function getMiningTarget() public view returns (uint); function getMiningReward() public view returns (uint); function decimals() public view returns (uint8); event Mint(address indexed from, uint rewardAmount, uint epochCount, bytes32 newChallengeNumber); } ``` #### Abstract Contract (Optional) The Abstract Contract adheres to the EIP918 Interface and extends behavioral definition through the introduction of 4 internal phases of token mining and minting: hash, reward, epoch and adjust difficulty, all called during the mint() operation. This construct provides a balance between being too general for use while providing ample room for multiple mined implementation types. ### Fields #### adjustmentInterval The amount of time between difficulty adjustments in seconds. ``` solidity bytes32 public adjustmentInterval; ``` #### challengeNumber The current challenge number. It is expected that a new challenge number is generated after a new reward is minted. ``` solidity bytes32 public challengeNumber; ``` #### difficulty The current mining difficulty which should be adjusted via the \_adjustDifficulty minting phase ``` solidity uint public difficulty; ``` #### tokensMinted Cumulative counter of the total minted tokens, usually modified during the \_reward phase ``` solidity uint public tokensMinted; ``` #### epochCount Number of 'blocks' mined ``` solidity uint public epochCount; ``` ### Mining Operations #### mint Returns a flag indicating a successful hash digest verification, and reward allocation to msg.sender. In order to prevent MiTM attacks, it is recommended that the digest include a recent Ethereum block hash and msg.sender's address. Once verified, the mint function calculates and delivers a mining reward to the sender and performs internal accounting operations on the contract's supply. The mint operation exists as a public function that invokes 4 separate phases, represented as functions hash, \_reward, \_newEpoch, and \_adjustDifficulty. In order to create the most flexible implementation while adhering to a necessary contract protocol, it is recommended that token implementors override the internal methods, allowing the base contract to handle their execution via mint. This externally facing function is called by miners to validate challenge digests, calculate reward, populate statistics, mutate epoch variables and adjust the solution difficulty as required. Once complete, a Mint event is emitted before returning a boolean success flag. ``` solidity contract AbstractERC918 is EIP918Interface { // the amount of time between difficulty adjustments uint public adjustmentInterval; // generate a new challenge number after a new reward is minted bytes32 public challengeNumber; // the current mining target uint public miningTarget; // cumulative counter of the total minted tokens uint public tokensMinted; // number of blocks per difficulty readjustment uint public blocksPerReadjustment; //number of 'blocks' mined uint public epochCount; /* * Externally facing mint function that is called by miners to validate challenge digests, calculate reward, * populate statistics, mutate epoch variables and adjust the solution difficulty as required. Once complete, * a Mint event is emitted before returning a success indicator. **/ function mint(uint256 nonce) public returns (bool success) { require(msg.sender != address(0)); // perform the hash function validation hash(nonce); // calculate the current reward uint rewardAmount = _reward(); // increment the minted tokens amount tokensMinted += rewardAmount; epochCount = _epoch(); //every so often, readjust difficulty. Don't readjust when deploying if(epochCount % blocksPerReadjustment == 0){ _adjustDifficulty(); } // send Mint event indicating a successful implementation emit Mint(msg.sender, rewardAmount, epochCount, challengeNumber); return true; } } ``` ##### *Mint Event* Upon successful verification and reward the mint method dispatches a Mint Event indicating the reward address, the reward amount, the epoch count and newest challenge number. ``` solidity event Mint(address indexed from, uint reward_amount, uint epochCount, bytes32 newChallengeNumber); ``` #### hash Public interface function hash, meant to be overridden in implementation to define hashing algorithm and validation. Returns the validated digest ``` solidity function hash(uint256 nonce) public returns (bytes32 digest); ``` #### \_reward Internal interface function \_reward, meant to be overridden in implementation to calculate and allocate the reward amount. The reward amount must be returned by this method. ``` solidity function _reward() internal returns (uint); ``` #### \_newEpoch Internal interface function \_newEpoch, meant to be overridden in implementation to define a cutpoint for mutating mining variables in preparation for the next phase of mine. ``` solidity function _newEpoch(uint256 nonce) internal returns (uint); ``` #### \_adjustDifficulty Internal interface function \_adjustDifficulty, meant to be overridden in implementation to adjust the difficulty (via field difficulty) of the mining as required ``` solidity function _adjustDifficulty() internal returns (uint); ``` #### getAdjustmentInterval The amount of time, in seconds, between difficulty adjustment operations. ``` solidity function getAdjustmentInterval() public view returns (uint); ``` #### getChallengeNumber Recent ethereum block hash, used to prevent pre-mining future blocks. ``` solidity function getChallengeNumber() public view returns (bytes32); ``` #### getMiningDifficulty The number of digits that the digest of the PoW solution requires which typically auto adjusts during reward generation. ``` solidity function getMiningDifficulty() public view returns (uint) ``` #### getMiningReward Return the current reward amount. Depending on the algorithm, typically rewards are divided every reward era as tokens are mined to provide scarcity. ``` solidity function getMiningReward() public view returns (uint) ``` ### Example mining function A general mining function written in python for finding a valid nonce for keccak256 mined token, is as follows: ``` python def generate_nonce(): myhex = b'%064x' % getrandbits(32*8) return codecs.decode(myhex, 'hex_codec') def mine(challenge, public_address, difficulty): while True: nonce = generate_nonce() hash1 = int(sha3.keccak_256(challenge+public_address+nonce).hexdigest(), 16) if hash1 < difficulty: return nonce, hash1 ``` Once the nonce and hash1 are found, these are used to call the mint() function of the smart contract to receive a reward of tokens. ### Merged Mining Extension (Optional) In order to provide support for merge mining multiple tokens, an optional merged mining extension can be implemented as part of the ERC918 standard. It is important to note that the following function will only properly work if the base contracts use tx.origin instead of msg.sender when applying rewards. If not the rewarded tokens will be sent to the calling contract and not the end user. ``` solidity /** * @title ERC-918 Mineable Token Standard, optional merged mining functionality * @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-918.md * */ contract ERC918Merged is AbstractERC918 { /* * @notice Externally facing merge function that is called by miners to validate challenge digests, calculate reward, * populate statistics, mutate state variables and adjust the solution difficulty as required. Additionally, the * merge function takes an array of target token addresses to be used in merged rewards. Once complete, * a Mint event is emitted before returning a success indicator. * * @param _nonce the solution nonce **/ function merge(uint256 _nonce, address[] _mineTokens) public returns (bool) { for (uint i = 0; i < _mineTokens.length; i++) { address tokenAddress = _mineTokens[i]; ERC918Interface(tokenAddress).mint(_nonce); } } /* * @notice Externally facing merge function kept for backwards compatibility with previous definition * * @param _nonce the solution nonce * @param _challenge_digest the keccak256 encoded challenge number + message sender + solution nonce **/ function merge(uint256 _nonce, bytes32 _challenge_digest, address[] _mineTokens) public returns (bool) { //the challenge digest must match the expected bytes32 digest = keccak256( abi.encodePacked(challengeNumber, msg.sender, _nonce) ); require(digest == _challenge_digest, "Challenge digest does not match expected digest on token contract [ ERC918Merged.mint() ]"); return merge(_nonce, _mineTokens); } } ``` ### Delegated Minting Extension (Optional) In order to facilitate a third party minting submission paradigm, such as the case of miners submitting solutions to a pool operator and/or system, a delegated minting extension can be used to allow pool accounts submit solutions on the behalf of a user, so the miner can avoid directly paying Ethereum transaction costs. This is performed by an off chain mining account packaging and signing a standardized mint solution packet and sending it to a pool or 3rd party to be submitted. The ERC918 Mineable Mint Packet Metadata should be prepared using following schema: ``` solidity { "title": "Mineable Mint Packet Metadata", "type": "object", "properties": { "nonce": { "type": "string", "description": "Identifies the target solution nonce", }, "origin": { "type": "string", "description": "Identifies the original user that mined the solution nonce", }, "signature": { "type": "string", "description": "The signed hash of tightly packed variables sha3('delegatedMintHashing(uint256,address)')+nonce+origin_account", } } } ``` The preparation of a mineable mint packet on a JavaScript client would appear as follows: ``` solidity function prepareDelegatedMintTxn(nonce, account) { var functionSig = web3.utils.sha3("delegatedMintHashing(uint256,address)").substring(0,10) var data = web3.utils.soliditySha3( functionSig, nonce, account.address ) var sig = web3.eth.accounts.sign(web3.utils.toHex(data), account.privateKey ) // prepare the mint packet var packet = {} packet.nonce = nonce packet.origin = account.address packet.signature = sig.signature // deliver resulting JSON packet to pool or third party var mineableMintPacket = JSON.stringify(packet, null, 4) /* todo: send mineableMintPacket to submitter */ ... } ``` Once the packet is prepared and formatted it can then be routed to a third party that will submit the transaction to the contract's delegatedMint() function, thereby paying for the transaction gas and receiving the resulting tokens. The pool/third party must then manually payback the minted tokens minus fees to the original minter. The following code sample exemplifies third party packet relaying: ``` solidity //received by minter var mineableMintPacket = ... var packet = JSON.parse(mineableMintPacket) erc918MineableToken.delegatedMint(packet.nonce, packet.origin, packet.signature) ``` The Delegated Mint Extension expands upon ERC918 realized as a sub-contract: ``` js import 'openzeppelin-solidity/contracts/contracts/cryptography/ECDSA.sol'; contract ERC918DelegatedMint is AbstractERC918, ECDSA { /** * @notice Hash (keccak256) of the payload used by delegatedMint * @param _nonce the golden nonce * @param _origin the original minter * @param _signature the original minter's elliptical curve signature */ function delegatedMint(uint256 _nonce, address _origin, bytes _signature) public returns (bool success) { bytes32 hashedTx = delegatedMintHashing(_nonce, _origin); address minter = recover(hashedTx, _signature); require(minter == _origin, "Origin minter address does not match recovered signature address [ AbstractERC918.delegatedMint() ]"); require(minter != address(0), "Invalid minter address recovered from signature [ ERC918DelegatedMint.delegatedMint() ]"); success = mintInternal(_nonce, minter); } /** * @notice Hash (keccak256) of the payload used by delegatedMint * @param _nonce the golden nonce * @param _origin the original minter */ function delegatedMintHashing(uint256 _nonce, address _origin) public pure returns (bytes32) { /* "0x7b36737a": delegatedMintHashing(uint256,address) */ return toEthSignedMessageHash(keccak256(abi.encodePacked( bytes4(0x7b36737a), _nonce, _origin))); } } ``` ### Mineable Token Metadata (Optional) In order to provide for richer and potentially mutable metadata for a particular Mineable Token, it is more viable to offer an off-chain reference to said data. This requires the implementation of a single interface method 'metadataURI()' that returns a JSON string encoded with the string fields symbol, name, description, website, image, and type. Solidity interface for Mineable Token Metadata: ``` solidity /** * @title ERC-918 Mineable Token Standard, optional metadata extension * @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-918.md * */ interface ERC918Metadata is AbstractERC918 { /** * @notice A distinct Uniform Resource Identifier (URI) for a mineable asset. */ function metadataURI() external view returns (string); } ``` Mineable Token Metadata JSON schema definition: ``` solidity { "title": "Mineable Token Metadata", "type": "object", "properties": { "symbol": { "type": "string", "description": "Identifies the Mineable Token's symbol", }, "name": { "type": "string", "description": "Identifies the Mineable Token's name", }, "description": { "type": "string", "description": "Identifies the Mineable Token's long description", }, "website": { "type": "string", "description": "Identifies the Mineable Token's homepage URI", }, "image": { "type": "string", "description": "Identifies the Mineable Token's image URI", }, "type": { "type": "string", "description": "Identifies the Mineable Token's hash algorithm ( ie.keccak256 ) used to encode the solution", } } } ``` ### Rationale The solidity keccak256 algorithm does not have to be used, but it is recommended since it is a cost effective one-way algorithm to perform in the EVM and simple to perform in solidity. The nonce is the solution that miners try to find and so it is part of the hashing algorithm. A challengeNumber is also part of the hash so that future blocks cannot be mined since it acts like a random piece of data that is not revealed until a mining round starts. The msg.sender address is part of the hash so that a nonce solution is valid only for a particular Ethereum account and so the solution is not susceptible to man-in-the-middle attacks. This also allows pools to operate without being easily cheated by the miners since pools can force miners to mine using the pool's address in the hash algorithm. The economics of transferring electricity and hardware into mined token assets offers a flourishing community of decentralized miners the option to be involved in the Ethereum token economy directly. By voting with hash power, an economically pegged asset to real-world resources, miners are incentivized to participate in early token trade to revamp initial costs, providing a bootstrapped stimulus mechanism between miners and early investors. One community concern for mined tokens has been around energy use without a function for securing a network. Although token mining does not secure a network, it serves the function of securing a community from corruption as it offers an alternative to centralized ICOs. Furthermore, an initial mining offering may last as little as a week, a day, or an hour at which point all of the tokens would have been minted. ### Backwards Compatibility Earlier versions of this standard incorporated a redundant 'challenge_digest' parameter on the mint() function that hash-encoded the packed variables challengeNumber, msg.sender and nonce. It was decided that this could be removed from the standard to help minimize processing and thereby gas usage during mint operations. However, in the name of interoperability with existing mining programs and pool software the following contract can be added to the inheritance tree: ``` solidity /** * @title ERC-918 Mineable Token Standard, optional backwards compatibility function * @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-918.md * */ contract ERC918BackwardsCompatible is AbstractERC918 { /* * @notice Externally facing mint function kept for backwards compatibility with previous mint() definition * @param _nonce the solution nonce * @param _challenge_digest the keccak256 encoded challenge number + message sender + solution nonce **/ function mint(uint256 _nonce, bytes32 _challenge_digest) public returns (bool success) { //the challenge digest must match the expected bytes32 digest = keccak256( abi.encodePacked(challengeNumber, msg.sender, _nonce) ); require(digest == _challenge_digest, "Challenge digest does not match expected digest on token contract [ AbstractERC918.mint() ]"); success = mint(_nonce); } } ``` ### Test Cases (Test cases for an implementation are mandatory for EIPs that are affecting consensus changes. Other EIPs can choose to include links to test cases if applicable.) ### Implementation Simple Example: https://github.com/0xbitcoin/EIP918-Mineable-Token/blob/master/contracts/SimpleERC918.sol Complex Examples: https://github.com/0xbitcoin/EIP918-Mineable-Token/blob/master/contracts/0xdogeExample.sol https://github.com/0xbitcoin/EIP918-Mineable-Token/blob/master/contracts/0xdogeExample2.sol https://github.com/0xbitcoin/EIP918-Mineable-Token/blob/master/contracts/0xBitcoinBase.sol 0xBitcoin Token Contract: https://etherscan.io/address/0xb6ed7644c69416d67b522e20bc294a9a9b405b31 MVI OpenCL Token Miner https://github.com/mining-visualizer/MVis-tokenminer/releases PoWAdv Token Contract: https://etherscan.io/address/0x1a136ae98b49b92841562b6574d1f3f5b0044e4c ### Copyright Copyright and related rights waived via [CC0](/LICENSE).

Address metadata registry

Mon, 12 Mar 2018 00:00:00 +0000

## Abstract This EIP specifies a registry for address metadata, permitting both contracts and external accounts to supply metadata about themselves to onchain and offchain callers. This permits use-cases such as generalised authorisations, providing token acceptance settings, and claims registries. ## Motivation An increasing set of use cases require storage of metadata associated with an address; see for instance EIP 777 and EIP 780, and the ENS reverse registry in EIP 181. Presently each use-case defines its own specialised registry. To prevent a proliferation of special-purpose registry contracts, we instead propose a single standardised registry using an extendable architecture that allows future standards to implement their own metadata standards. ## Specification The metadata registry has the following interface: ```solidity interface AddressMetadataRegistry { function provider(address target) view returns(address); function setProvider(address _provider); } ``` `setProvider` specifies the metadata registry to be associated with the caller's address, while `provider` returns the address of the metadata registry for the supplied address. The metadata registry will be compiled with an agreed-upon version of Solidity and deployed using the trustless deployment mechanism to a fixed address that can be replicated across all chains. ## Provider specification Providers may implement any subset of the metadata record types specified here. Where a record types specification requires a provider to provide multiple functions, the provider MUST implement either all or none of them. Providers MUST throw if called with an unsupported function ID. Providers have one mandatory function: ```solidity function supportsInterface(bytes4 interfaceID) constant returns (bool) ``` The `supportsInterface` function is documented in [EIP-165](./eip-165.md), and returns true if the provider implements the interface specified by the provided 4 byte identifier. An interface identifier consists of the XOR of the function signature hashes of the functions provided by that interface; in the degenerate case of single-function interfaces, it is simply equal to the signature hash of that function. If a provider returns `true` for `supportsInterface()`, it must implement the functions specified in that interface. `supportsInterface` must always return true for `0x01ffc9a7`, which is the interface ID of `supportsInterface` itself. The first argument to all provider functions MUST be the address being queried; this facilitates the creation of multi-user provider contracts. Currently standardised provider interfaces are specified in the table below. | Interface name | Interface hash | Specification | | --- | --- | --- | EIPs may define new interfaces to be added to this registry. ## Rationale There are two obvious approaches for a generic metadata registry: the indirection approach employed here, or a generalised key/value store. While indirection incurs the cost of an additional contract call, and requires providers to change over time, it also provides for significantly enhanced flexibility over a key/value store; for that reason we selected this approach. ## Backwards Compatibility There are no backwards compatibility concerns. ## Implementation The canonical implementation of the metadata registry is as follows: ```solidity contract AddressMetadataRegistry { mapping(address=>address) public provider; function setProvider(address _provider) { provider[msg.sender] = _provider; } } ``` ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Generalised authorisations

Mon, 12 Mar 2018 00:00:00 +0000

## Abstract This EIP specifies a generic authorisation mechanism, which can be used to implement a variety of authorisation patterns, replacing approvals in ERC20, operators in ERC777, and bespoke authorisation patterns in a variety of other types of contract. ## Motivation Smart contracts commonly need to provide an interface that allows a third-party caller to perform actions on behalf of a user. The most common example of this is token authorisations/operators, but other similar situations exist throughout the ecosystem, including for instance authorising operations on ENS domains. Typically each standard reinvents this system for themselves, leading to a large number of incompatible implementations of the same basic pattern. Here, we propose a generic method usable by all such contracts. The pattern implemented here is inspired by [ds-auth](https://github.com/dapphub/ds-auth) and by OAuth. ## Specification The generalised authorisation interface is implemented as a metadata provider, as specified in EIP 926. The following mandatory function is implemented: ```solidity function canCall(address owner, address caller, address callee, bytes4 func) view returns(bool); ``` Where: - `owner` is the owner of the resource. If approved the function call is treated as being made by this address. - `caller` is the address making the present call. - `callee` is the address of the contract being called. - `func` is the 4-byte signature of the function being called. For example, suppose Alice authorises Bob to transfer tokens on her behalf. When Bob does so, Alice is the `owner`, Bob is the `caller`, the token contract is the `callee`, and the function signature for the transfer function is `func`. As this standard uses EIP 926, the authorisation flow is as follows: 1. The callee contract fetches the provider for the `owner` address from the metadata registry contract, which resides at a well-known address. 2. The callee contract calls `canCall()` with the parameters described above. If the function returns false, the callee reverts execution. Commonly, providers will wish to supply a standardised interface for users to set and unset their own authorisations. They SHOULD implement the following interface: ```solidity function authoriseCaller(address owner, address caller, address callee, bytes4 func); function revokeCaller(address owner, address caller, address callee, bytes4 func); ``` Arguments have the same meaning as in `canCall`. Implementing contracts MUST ensure that `msg.sender` is authorised to call `authoriseCaller` or `revokeCaller` on behalf of `owner`; this MUST always be true if `owner == msg.sender`. Implementing contracts SHOULD use the standard specified here to determine if other callers may provide authorisations as well. Implementing contracts SHOULD treat a `func` of 0 as authorising calls to all functions on `callee`. If `authorised` is `false` and `func` is 0, contracts need only clear any blanket authorisation; individual authorisations may remain in effect. ## Backwards Compatibility There are no backwards compatibility concerns. ## Implementation Example implementation TBD. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Composable Non-Fungible Token

Sat, 07 Jul 2018 00:00:00 +0000

## Abstract An extension of the [ERC-721 standard](./eip-721.md) to enable ERC-721 tokens to own other ERC-721 tokens and [ERC-20](./eip-20.md) tokens. An extension of the [ERC-20](./eip-20.md) and `ERC-223 https://github.com/ethereum/EIPs/issues/223` standards to enable ERC-20 and `ERC-223` tokens to be owned by ERC-721 tokens. This specification covers four different kinds of composable tokens: 1. [`ERC998ERC721` top-down composable tokens that receive, hold and transfer ERC-721 tokens](#erc-721-top-down-composable) 2. [`ERC998ERC20` top-down composable tokens that receive, hold and transfer ERC-20 tokens](#erc-20-top-down-composable) 3. [`ERC998ERC721` bottom-up composable tokens that attach themselves to other ERC-721 tokens.](#erc-721-bottom-up-composable) 4. [`ERC998ERC20` bottom-up composable tokens that attach themselves to ERC-721 tokens.](#erc-20-bottom-up-composable) which map to 1. An `ERC998ERC721` top-down composable is an ERC-721 token with additional functionality for owning other ERC-721 tokens. 2. An `ERC998ERC20` top-down composable is an ERC-721 token with additional functionality for owning ERC-20 tokens. 3. An `ERC998ERC721` bottom-up composable is an ERC-721 token with additional functionality for being owned by an ERC-721 token. 4. An `ERC998ERC20` bottom-up composable is an ERC-20 token with additional functionality for being owned by an ERC-721 token. A top-down composable contract stores and keeps track of child tokens for each of its tokens. A bottom-up composable contract stores and keeps track of a parent token for each its tokens. With composable tokens it is possible to compose lists or trees of ERC-721 and ERC-20 tokens connected by ownership. Any such structure will have a single owner address at the root of the structure that is the owner of the entire composition. The entire composition can be transferred with one transaction by changing the root owner. Different composables, top-down and bottom-up, have their advantages and disadvantages which are explained in the [Rational section](#rationale). It is possible for a token to be one or more kinds of composable token. A non-fungible token is compliant and Composable of this EIP if it implements one or more of the following interfaces: * `ERC998ERC721TopDown` * `ERC998ERC20TopDown` * `ERC998ERC721BottomUp` * `ERC998ERC20BottomUp` ## Specification ### ERC-721 `ERC998ERC721` top-down, `ERC998ERC20` top-down, and `ERC998ERC721` bottom-up composable contracts must implement the [ERC-721 interface](./eip-721.md). ### ERC-20 `ERC998ERC20` bottom-up composable contracts must implement the [ERC-20 interface](./eip-20.md). ### [ERC-165](./eip-165.md) The [ERC-165 standard](./eip-165.md) must be applied to each [ERC-998](./eip-998.md) interface that is used. ### Authentication Authenticating whether a user or contract can execute some action works the same for both `ERC998ERC721` top-down and `ERC998ERC721` bottom-up composables. A `rootOwner` refers to the owner address at the top of a tree of composables and ERC-721 tokens. Authentication within any composable is done by finding the rootOwner and comparing it to `msg.sender`, the return result of `getApproved(tokenId)` and the return result of `isApprovedForAll(rootOwner, msg.sender)`. If a match is found then authentication passes, otherwise authentication fails and the contract throws. Here is an example of authentication code: ```solidity address rootOwner = address(rootOwnerOf(_tokenId)); require(rootOwner == msg.sender || isApprovedForAll(rootOwner,msg.sender) || getApproved(tokenId) == msg.sender; ``` The `approve(address _approved, uint256 _tokenId)` and `getApproved(uint256 _tokenId)` ERC-721 functions are implemented specifically for the rootOwner. This enables a tree of composables to be transferred to a new rootOwner without worrying about which addresses have been approved in child composables, because any prior approves can only be used by the prior rootOwner. Here are example implementations: ```solidity function approve(address _approved, uint256 _tokenId) external { address rootOwner = address(rootOwnerOf(_tokenId)); require(rootOwner == msg.sender || isApprovedForAll(rootOwner,msg.sender)); rootOwnerAndTokenIdToApprovedAddress[rootOwner][_tokenId] = _approved; emit Approval(rootOwner, _approved, _tokenId); } function getApproved(uint256 _tokenId) public view returns (address) { address rootOwner = address(rootOwnerOf(_tokenId)); return rootOwnerAndTokenIdToApprovedAddress[rootOwner][_tokenId]; } ``` ### Traversal The rootOwner of a composable is gotten by calling `rootOwnerOf(uint256 _tokenId)` or `rootOwnerOfChild(address _childContract, uint256 _childTokenId)`. These functions are used by top-down and bottom-up composables to traverse up the tree of composables and ERC-721 tokens to find the rootOwner. `ERC998ERC721` top-down and bottom-up composables are interoperable with each other. It is possible for a top-down composable to own a bottom-up composable or for a top-down composable to own an ERC-721 token that owns a bottom-up token. In any configuration calling `rootOwnerOf(uint256 _tokenID)` on a composable will return the root owner address at the top of the ownership tree. It is important to get the traversal logic of `rootOwnerOf` right. The logic for `rootOwnerOf` is the same whether or not a composable is bottom-up or top-down or both. Here is the logic: ``` Logic for rootOwnerOf(uint256 _tokenId) If the token is a bottom-up composable and has a parent token then call rootOwnerOf for the parent token. If the call was successful then the returned address is the rootOwner. Otherwise call rootOwnerOfChild for the parent token. If the call was successful then the returned address is the rootOwner. Otherwise get the owner address of the token and that is the rootOwner. Otherwise call rootOwnerOfChild for the token If the call was successful then the returned address is the rootOwner. Otherwise get the owner address of the token and that is the rootOwner. ``` Calling `rootOwnerOfChild` for a token means the following logic: ```solidity // Logic for calling rootOwnerOfChild for a tokenId address tokenOwner = ownerOf(tokenId); address childContract = address(this); bytes32 rootOwner = ERC998ERC721(tokenOwner).rootOwnerOfChild(childContract, tokenId); ``` But understand that the real call to `rootOwnerOfChild` should be made with assembly so that the code can check if the call failed and so that the `staticcall` opcode is used to ensure that no state is modified. Tokens/contracts that implement the above authentication and traversal functionality are "composable aware". ### Composable Transfer Function Parameter Format Composable functions that make transfers follow the same parameter format: **from:to:what**. For example the `getChild(address _from, uint256 _tokenId, address _childContract, uint256 _childTokenId)` composable function transfers an ERC-721 token from an address to a top-down composable. The `_from` parameter is the **from**, the `_tokenId` parameter is the **to** and the `address _childContract, uint256 _childTokenId` parameters are the **what**. Another example is the `safeTransferChild(uint256 _fromTokenId, address _to, address _childContract, uint256 _childTokenId)` function. The `_fromTokenId` is the **from**, the `_to` is the **to** and the `address _childContract, address _childTokenId` parameters are the **what**. ### transferFrom/safeTransferFrom Functions Do Not Transfer Tokens Owned By Tokens In bottom-up and top-down composable contracts the `transferFrom` and `safeTransferFrom` functions must throw if they are called directly to transfer a token that is owned by another token. The reason for this is that these functions do not explicitly specify which token owns a token to be transferred. [See the rational section for more information about this.](#explicit-transfer-parameters) `transferFrom/safeTransferFrom` functions must be used to transfer tokens that are owned by an address. ### ERC-721 Top-Down Composable ERC-721 top-down composables act as containers for ERC-721 tokens. ERC-721 top-down composables are ERC-721 tokens that can receive, hold and transfer ERC-721 tokens. There are two ways to transfer a ERC-721 token to a top-down composable: 1. Use the `function safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes data)` function. The `_to` argument is the top-down composable contract address. The `bytes data` argument holds the integer value of the top-down composable tokenId that the ERC-721 token is transferred to. 2. Call `approve` in the ERC-721 token contract for the top-down composable contract. Then call `getChild` in the composable contract. The first ways is for ERC-721 contracts that have a `safeTransferFrom` function. The second way is for contracts that do not have this function such as cryptokitties. Here is an example of transferring ERC-721 token 3 from an address to top-down composable token 6: ```solidity uint256 tokenId = 6; bytes memory tokenIdBytes = new bytes(32); assembly { mstore(add(tokenIdBytes, 32), tokenId) } ERC721(contractAddress).safeTransferFrom(userAddress, composableAddress, 3, tokenIdBytes); ``` Every ERC-721 top-down composable compliant contract must implement the `ERC998ERC721TopDown` interface. The `ERC998ERC721TopDownEnumerable` and `ERC998ERC20TopDownEnumerable` interfaces are optional. ```solidity pragma solidity ^0.4.24; /// @title `ERC998ERC721` Top-Down Composable Non-Fungible Token /// @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-998.md /// Note: the ERC-165 identifier for this interface is 0xcde244d9 interface ERC998ERC721TopDown { /// @dev This emits when a token receives a child token. /// @param _from The prior owner of the token. /// @param _toTokenId The token that receives the child token. event ReceivedChild( address indexed _from, uint256 indexed _toTokenId, address indexed _childContract, uint256 _childTokenId ); /// @dev This emits when a child token is transferred from a token to an address. /// @param _fromTokenId The parent token that the child token is being transferred from. /// @param _to The new owner address of the child token. event TransferChild( uint256 indexed _fromTokenId, address indexed _to, address indexed _childContract, uint256 _childTokenId ); /// @notice Get the root owner of tokenId. /// @param _tokenId The token to query for a root owner address /// @return rootOwner The root owner at the top of tree of tokens and ERC-998 magic value. function rootOwnerOf(uint256 _tokenId) public view returns (bytes32 rootOwner); /// @notice Get the root owner of a child token. /// @param _childContract The contract address of the child token. /// @param _childTokenId The tokenId of the child. /// @return rootOwner The root owner at the top of tree of tokens and ERC-998 magic value. function rootOwnerOfChild( address _childContract, uint256 _childTokenId ) public view returns (bytes32 rootOwner); /// @notice Get the parent tokenId of a child token. /// @param _childContract The contract address of the child token. /// @param _childTokenId The tokenId of the child. /// @return parentTokenOwner The parent address of the parent token and ERC-998 magic value /// @return parentTokenId The parent tokenId of _tokenId function ownerOfChild( address _childContract, uint256 _childTokenId ) external view returns ( bytes32 parentTokenOwner, uint256 parentTokenId ); /// @notice A token receives a child token /// @param _operator The address that caused the transfer. /// @param _from The owner of the child token. /// @param _childTokenId The token that is being transferred to the parent. /// @param _data Up to the first 32 bytes contains an integer which is the receiving parent tokenId. function onERC721Received( address _operator, address _from, uint256 _childTokenId, bytes _data ) external returns(bytes4); /// @notice Transfer child token from top-down composable to address. /// @param _fromTokenId The owning token to transfer from. /// @param _to The address that receives the child token /// @param _childContract The ERC-721 contract of the child token. /// @param _childTokenId The tokenId of the token that is being transferred. function transferChild( uint256 _fromTokenId, address _to, address _childContract, uint256 _childTokenId ) external; /// @notice Transfer child token from top-down composable to address. /// @param _fromTokenId The owning token to transfer from. /// @param _to The address that receives the child token /// @param _childContract The ERC-721 contract of the child token. /// @param _childTokenId The tokenId of the token that is being transferred. function safeTransferChild( uint256 _fromTokenId, address _to, address _childContract, uint256 _childTokenId ) external; /// @notice Transfer child token from top-down composable to address. /// @param _fromTokenId The owning token to transfer from. /// @param _to The address that receives the child token /// @param _childContract The ERC-721 contract of the child token. /// @param _childTokenId The tokenId of the token that is being transferred. /// @param _data Additional data with no specified format function safeTransferChild( uint256 _fromTokenId, address _to, address _childContract, uint256 _childTokenId, bytes _data ) external; /// @notice Transfer bottom-up composable child token from top-down composable to other ERC-721 token. /// @param _fromTokenId The owning token to transfer from. /// @param _toContract The ERC-721 contract of the receiving token /// @param _toTokenId The receiving token /// @param _childContract The bottom-up composable contract of the child token. /// @param _childTokenId The token that is being transferred. /// @param _data Additional data with no specified format function transferChildToParent( uint256 _fromTokenId, address _toContract, uint256 _toTokenId, address _childContract, uint256 _childTokenId, bytes _data ) external; /// @notice Get a child token from an ERC-721 contract. /// @param _from The address that owns the child token. /// @param _tokenId The token that becomes the parent owner /// @param _childContract The ERC-721 contract of the child token /// @param _childTokenId The tokenId of the child token function getChild( address _from, uint256 _tokenId, address _childContract, uint256 _childTokenId ) external; } ``` #### `rootOwnerOf` 1 ```solidity /// @notice Get the root owner of tokenId. /// @param _tokenId The token to query for a root owner address /// @return rootOwner The root owner at the top of tree of tokens and ERC-998 magic value. function rootOwnerOf(uint256 _tokenId) public view returns (bytes32 rootOwner); ``` This function traverses token owners until the root owner address of `_tokenId` is found. The first 4 bytes of rootOwner contain the ERC-998 magic value `0xcd740db5`. The last 20 bytes contain the root owner address. The magic value is returned because this function may be called on contracts when it is unknown if the contracts have a `rootOwnerOf` function. The magic value is used in such calls to ensure a valid return value is received. If it is unknown whether a contract has the `rootOwnerOf` function then the first four bytes of the `rootOwner` return value must be compared to `0xcd740db5`. `0xcd740db5` is equal to: ```solidity this.rootOwnerOf.selector ^ this.rootOwnerOfChild.selector ^ this.tokenOwnerOf.selector ^ this.ownerOfChild.selector; ``` Here is an example of a value returned by `rootOwnerOf`. `0xcd740db50000000000000000e5240103e1ff986a2c8ae6b6728ffe0d9a395c59` #### rootOwnerOfChild ```solidity /// @notice Get the root owner of a child token. /// @param _childContract The contract address of the child token. /// @param _childTokenId The tokenId of the child. /// @return rootOwner The root owner at the top of tree of tokens and ERC-998 magic value. function rootOwnerOfChild( address _childContract, uint256 _childTokenId ) public view returns (bytes32 rootOwner); ``` This function traverses token owners until the root owner address of the supplied child token is found. The first 4 bytes of rootOwner contain the ERC-998 magic value `0xcd740db5`. The last 20 bytes contain the root owner address. The magic value is returned because this function may be called on contracts when it is unknown if the contracts have a `rootOwnerOf` function. The magic value is used in such calls to ensure a valid return value is received. If it is unknown whether a contract has the `rootOwnerOfChild` function then the first four bytes of the `rootOwner` return value must be compared to `0xcd740db5`. #### ownerOfChild ```solidity /// @notice Get the parent tokenId of a child token. /// @param _childContract The contract address of the child token. /// @param _childTokenId The tokenId of the child. /// @return parentTokenOwner The parent address of the parent token and ERC-998 magic value /// @return parentTokenId The parent tokenId of _tokenId function ownerOfChild( address _childContract, uint256 _childTokenId ) external view returns ( address parentTokenOwner, uint256 parentTokenId ); ``` This function is used to get the parent tokenId of a child token and get the owner address of the parent token. The first 4 bytes of parentTokenOwner contain the ERC-998 magic value `0xcd740db5`. The last 20 bytes contain the parent token owner address. The magic value is returned because this function may be called on contracts when it is unknown if the contracts have a `ownerOfChild` function. The magic value is used in such calls to ensure a valid return value is received. If it is unknown whether a contract has the `ownerOfChild` function then the first four bytes of the `parentTokenOwner` return value must be compared to `0xcd740db5`. #### `onERC721Received` ```solidity /// @notice A token receives a child token /// @param _operator The address that caused the transfer. /// @param _from The prior owner of the child token. /// @param _childTokenId The token that is being transferred to the parent. /// @param _data Up to the first 32 bytes contains an integer which is the receiving parent tokenId. function onERC721Received( address _operator, address _from, uint256 _childTokenId, bytes _data ) external returns(bytes4); ``` This is a function defined in the ERC-721 standard. This function is called in an ERC-721 contract when `safeTransferFrom` is called. The `bytes _data` argument contains an integer value from 1 to 32 bytes long that is the parent tokenId that an ERC-721 token is transferred to. The `onERC721Received` function is how a top-down composable contract is notified that an ERC-721 token has been transferred to it and what tokenId in the top-down composable is the parent tokenId. The return value for `onERC721Received` is the magic value `0x150b7a02` which is equal to `bytes4(keccak256(abi.encodePacked("onERC721Received(address,address,uint256,bytes)")))`. #### transferChild ```solidity /// @notice Transfer child token from top-down composable to address. /// @param _fromTokenId The owning token to transfer from. /// @param _to The address that receives the child token /// @param _childContract The ERC-721 contract of the child token. /// @param _childTokenId The tokenId of the token that is being transferred. function transferChild( uint256 _fromTokenId, address _to, address _childContract, uint256 _childTokenId ) external; ``` This function authenticates `msg.sender` and transfers a child token from a top-down composable to a different address. This function makes this call within it: ```solidity ERC721(_childContract).transferFrom(this, _to, _childTokenId); ``` #### safeTransferChild 1 ```solidity /// @notice Transfer child token from top-down composable to address. /// @param _fromTokenId The owning token to transfer from. /// @param _to The address that receives the child token /// @param _childContract The ERC-721 contract of the child token. /// @param _childTokenId The tokenId of the token that is being transferred. function safeTransferChild( uint256 _fromTokenId, address _to, address _childContract, uint256 _childTokenId ) external; ``` This function authenticates `msg.sender` and transfers a child token from a top-down composable to a different address. This function makes this call within it: ```solidity ERC721(_childContract).safeTransferFrom(this, _to, _childTokenId); ``` #### safeTransferChild 2 ```solidity /// @notice Transfer child token from top-down composable to address or other top-down composable. /// @param _fromTokenId The owning token to transfer from. /// @param _to The address that receives the child token /// @param _childContract The ERC721 contract of the child token. /// @param _childTokenId The tokenId of the token that is being transferred. /// @param _data Additional data with no specified format, can be used to specify tokenId to transfer to function safeTransferChild( uint256 _fromTokenId, address _to, address _childContract, uint256 _childTokenId, bytes _data ) external; ``` This function authenticates `msg.sender` and transfers a child token from a top-down composable to a different address or to a different top-down composable. A child token is transferred to a different top-down composable if the `_to` address is a top-down composable contract and `bytes _data` is supplied an integer representing the parent tokenId. This function makes this call within it: ```solidity ERC721(_childContract).safeTransferFrom(this, _to, _childTokenId, _data); ``` #### transferChildToParent ```solidity /// @notice Transfer bottom-up composable child token from top-down composable to other ERC-721 token. /// @param _fromTokenId The owning token to transfer from. /// @param _toContract The ERC-721 contract of the receiving token /// @param _toToken The receiving token /// @param _childContract The bottom-up composable contract of the child token. /// @param _childTokenId The token that is being transferred. /// @param _data Additional data with no specified format function transferChildToParent( uint256 _fromTokenId, address _toContract, uint256 _toTokenId, address _childContract, uint256 _childTokenId, bytes _data ) external ``` This function authenticates `msg.sender` and transfers a child bottom-up composable token from a top-down composable to a different ERC-721 token. This function can only be used when the child token is a bottom-up composable token. It is designed to transfer a bottom-up composable token from a top-down composable to an ERC-721 token (bottom-up style) in one transaction. This function makes this call within it: ```solidity ERC998ERC721BottomUp(_childContract).transferToParent( address(this), _toContract, _toTokenId, _childTokenId, _data ); ``` #### getChild ```solidity /// @notice Get a child token from an ERC-721 contract. /// @param _from The address that owns the child token. /// @param _tokenId The token that becomes the parent owner /// @param _childContract The ERC-721 contract of the child token /// @param _childTokenId The tokenId of the child token function getChild( address _from, uint256 _tokenId, address _childContract, uint256 _childTokenId ) external; ``` This function is used to transfer an ERC-721 token when its contract does not have a `safeTransferChild(uint256 _fromTokenId, address _to, address _childContract, uint256 _childTokenId, bytes _data)` function. A transfer with this function is done in two steps: 1. The owner of the ERC-721 token calls `approve` or `setApprovalForAll` in the ERC-721 contract for the top-down composable contract. 2. The owner of the ERC-721 token calls `getChild` in the top-down composable contract for the ERC-721 token. The `getChild` function must authenticate that `msg.sender` is the owner of the ERC-721 token in the ERC-721 contract or is approved or an operator of the ERC-721 token in the ERC-721 contract. #### ERC-721 Top-Down Composable Enumeration Optional interface for top-down composable enumeration: ```solidity /// @dev The ERC-165 identifier for this interface is 0xa344afe4 interface ERC998ERC721TopDownEnumerable { /// @notice Get the total number of child contracts with tokens that are owned by tokenId. /// @param _tokenId The parent token of child tokens in child contracts /// @return uint256 The total number of child contracts with tokens owned by tokenId. function totalChildContracts(uint256 _tokenId) external view returns(uint256); /// @notice Get child contract by tokenId and index /// @param _tokenId The parent token of child tokens in child contract /// @param _index The index position of the child contract /// @return childContract The contract found at the tokenId and index. function childContractByIndex( uint256 _tokenId, uint256 _index ) external view returns (address childContract); /// @notice Get the total number of child tokens owned by tokenId that exist in a child contract. /// @param _tokenId The parent token of child tokens /// @param _childContract The child contract containing the child tokens /// @return uint256 The total number of child tokens found in child contract that are owned by tokenId. function totalChildTokens( uint256 _tokenId, address _childContract ) external view returns(uint256); /// @notice Get child token owned by tokenId, in child contract, at index position /// @param _tokenId The parent token of the child token /// @param _childContract The child contract of the child token /// @param _index The index position of the child token. /// @return childTokenId The child tokenId for the parent token, child token and index function childTokenByIndex( uint256 _tokenId, address _childContract, uint256 _index ) external view returns (uint256 childTokenId); } ``` ### ERC-20 Top-Down Composable ERC-20 top-down composables act as containers for ERC-20 tokens. ERC-20 top-down composables are ERC-721 tokens that can receive, hold and transfer ERC-20 tokens. There are two ways to transfer ERC-20 tokens to an ERC-20 Top-Down Composable: 1. Use the `transfer(address _to, uint256 _value, bytes _data);` function from the `ERC-223` contract. The `_to` argument is the ERC-20 top-down composable contract address. The `_value` argument is how many ERC-20 tokens to transfer. The `bytes` argument holds the integer value of the top-down composable tokenId that receives the ERC-20 tokens. 2. Call `approve` in the ERC-20 contract for the ERC-20 top-down composable contract. Then call `getERC20(address _from, uint256 _tokenId, address _erc20Contract, uint256 _value)` from the ERC-20 top-down composable contract. The first way is for ERC-20 contracts that support the `ERC-223` standard. The second way is for contracts that do not. ERC-20 top-down composables implement the following interface: ```solidity /// @title `ERC998ERC20` Top-Down Composable Non-Fungible Token /// @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-998.md /// Note: the ERC-165 identifier for this interface is 0x7294ffed interface ERC998ERC20TopDown { /// @dev This emits when a token receives ERC-20 tokens. /// @param _from The prior owner of the token. /// @param _toTokenId The token that receives the ERC-20 tokens. /// @param _erc20Contract The ERC-20 contract. /// @param _value The number of ERC-20 tokens received. event ReceivedERC20( address indexed _from, uint256 indexed _toTokenId, address indexed _erc20Contract, uint256 _value ); /// @dev This emits when a token transfers ERC-20 tokens. /// @param _tokenId The token that owned the ERC-20 tokens. /// @param _to The address that receives the ERC-20 tokens. /// @param _erc20Contract The ERC-20 contract. /// @param _value The number of ERC-20 tokens transferred. event TransferERC20( uint256 indexed _fromTokenId, address indexed _to, address indexed _erc20Contract, uint256 _value ); /// @notice A token receives ERC-20 tokens /// @param _from The prior owner of the ERC-20 tokens /// @param _value The number of ERC-20 tokens received /// @param _data Up to the first 32 bytes contains an integer which is the receiving tokenId. function tokenFallback(address _from, uint256 _value, bytes _data) external; /// @notice Look up the balance of ERC-20 tokens for a specific token and ERC-20 contract /// @param _tokenId The token that owns the ERC-20 tokens /// @param _erc20Contract The ERC-20 contract /// @return The number of ERC-20 tokens owned by a token from an ERC-20 contract function balanceOfERC20( uint256 _tokenId, address _erc20Contract ) external view returns(uint256); /// @notice Transfer ERC-20 tokens to address /// @param _tokenId The token to transfer from /// @param _value The address to send the ERC-20 tokens to /// @param _erc20Contract The ERC-20 contract /// @param _value The number of ERC-20 tokens to transfer function transferERC20( uint256 _tokenId, address _to, address _erc20Contract, uint256 _value ) external; /// @notice Transfer ERC-20 tokens to address or ERC-20 top-down composable /// @param _tokenId The token to transfer from /// @param _value The address to send the ERC-20 tokens to /// @param _erc223Contract The `ERC-223` token contract /// @param _value The number of ERC-20 tokens to transfer /// @param _data Additional data with no specified format, can be used to specify tokenId to transfer to function transferERC223( uint256 _tokenId, address _to, address _erc223Contract, uint256 _value, bytes _data ) external; /// @notice Get ERC-20 tokens from ERC-20 contract. /// @param _from The current owner address of the ERC-20 tokens that are being transferred. /// @param _tokenId The token to transfer the ERC-20 tokens to. /// @param _erc20Contract The ERC-20 token contract /// @param _value The number of ERC-20 tokens to transfer function getERC20( address _from, uint256 _tokenId, address _erc20Contract, uint256 _value ) external; } ``` #### tokenFallback ```solidity /// @notice A token receives ERC-20 tokens /// @param _from The prior owner of the ERC-20 tokens /// @param _value The number of ERC-20 tokens received /// @param _data Up to the first 32 bytes contains an integer which is the receiving tokenId. function tokenFallback(address _from, uint256 _value, bytes _data) external; ``` This function comes from the `ERC-223` which is an extension of the ERC-20 standard. This function is called on the receiving contract from the sending contract when ERC-20 tokens are transferred. This function is how the ERC-20 top-down composable contract gets notified that one of its tokens received ERC-20 tokens. Which token received ERC-20 tokens is specified in the `_data` parameter. #### `balanceOfERC20` ```solidity /// @notice Look up the balance of ERC-20 tokens for a specific token and ERC-20 contract /// @param _tokenId The token that owns the ERC-20 tokens /// @param _erc20Contract The ERC-20 contract /// @return The number of ERC-20 tokens owned by a token from an ERC-20 contract function balanceOfERC20( uint256 _tokenId, address _erc20Contract ) external view returns(uint256); ``` Gets the balance of ERC-20 tokens owned by a token from a specific ERC-20 contract. #### `transferERC20` ```solidity /// @notice Transfer ERC-20 tokens to address /// @param _tokenId The token to transfer from /// @param _value The address to send the ERC-20 tokens to /// @param _erc20Contract The ERC-20 contract /// @param _value The number of ERC-20 tokens to transfer function transferERC20( uint256 _tokenId, address _to, address _erc20Contract, uint256 _value ) external; ``` This is used to transfer ERC-20 tokens from a token to an address. This function calls `ERC20(_erc20Contract).transfer(_to, _value)`; This function must authenticate `msg.sender`. #### `transferERC223` ```solidity /// @notice Transfer ERC-20 tokens to address or ERC-20 top-down composable /// @param _tokenId The token to transfer from /// @param _value The address to send the ERC-20 tokens to /// @param _erc223Contract The `ERC-223` token contract /// @param _value The number of ERC-20 tokens to transfer /// @param _data Additional data with no specified format, can be used to specify tokenId to transfer to function transferERC223( uint256 _tokenId, address _to, address _erc223Contract, uint256 _value, bytes _data ) external; ``` This function is from the `ERC-223`. It is used to transfer ERC-20 tokens from a token to an address or to another token by putting an integer token value in the `_data` argument. This function must authenticate `msg.sender`. #### `getERC20` ```solidity /// @notice Get ERC-20 tokens from ERC-20 contract. /// @param _from The current owner address of the ERC-20 tokens that are being transferred. /// @param _tokenId The token to transfer the ERC-20 tokens to. /// @param _erc20Contract The ERC-20 token contract /// @param _value The number of ERC-20 tokens to transfer function getERC20( address _from, uint256 _tokenId, address _erc20Contract, uint256 _value ) external; ``` This function is used to transfer ERC-20 tokens to an ERC-20 top-down composable when an ERC-20 contract does not have a `transferERC223(uint256 _tokenId, address _to, address _erc223Contract, uint256 _value, bytes _data)` function. Before this function can be used the ERC-20 top-down composable contract address must be approved in the ERC-20 contract to transfer the ERC-20 tokens. This function must authenticate that `msg.sender` equals `_from` or has been approved in the ERC-20 contract. #### ERC-20 Top-Down Composable Enumeration Optional interface for top-down composable enumeration: ```solidity /// @dev The ERC-165 identifier for this interface is 0xc5fd96cd interface ERC998ERC20TopDownEnumerable { /// @notice Get the number of ERC-20 contracts that token owns ERC-20 tokens from /// @param _tokenId The token that owns ERC-20 tokens. /// @return uint256 The number of ERC-20 contracts function totalERC20Contracts(uint256 _tokenId) external view returns(uint256); /// @notice Get an ERC-20 contract that token owns ERC-20 tokens from by index /// @param _tokenId The token that owns ERC-20 tokens. /// @param _index The index position of the ERC-20 contract. /// @return address The ERC-20 contract function erc20ContractByIndex( uint256 _tokenId, uint256 _index ) external view returns(address); } ``` ### ERC-721 Bottom-Up Composable ERC-721 bottom-up composables are ERC-721 tokens that attach themselves to other ERC-721 tokens. ERC-721 bottom-up composable contracts store the owning address of a token and the parent tokenId if any. ```solidity /// @title `ERC998ERC721` Bottom-Up Composable Non-Fungible Token /// @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-998.md /// Note: the ERC-165 identifier for this interface is 0xa1b23002 interface ERC998ERC721BottomUp { /// @dev This emits when a token is transferred to an ERC-721 token /// @param _toContract The contract the token is transferred to /// @param _toTokenId The token the token is transferred to /// @param _tokenId The token that is transferred event TransferToParent( address indexed _toContract, uint256 indexed _toTokenId, uint256 _tokenId ); /// @dev This emits when a token is transferred from an ERC-721 token /// @param _fromContract The contract the token is transferred from /// @param _fromTokenId The token the token is transferred from /// @param _tokenId The token that is transferred event TransferFromParent( address indexed _fromContract, uint256 indexed _fromTokenId, uint256 _tokenId ); /// @notice Get the root owner of tokenId. /// @param _tokenId The token to query for a root owner address /// @return rootOwner The root owner at the top of tree of tokens and ERC-998 magic value. function rootOwnerOf(uint256 _tokenId) external view returns (bytes32 rootOwner); /// @notice Get the owner address and parent token (if there is one) of a token /// @param _tokenId The tokenId to query. /// @return tokenOwner The owner address of the token /// @return parentTokenId The parent owner of the token and ERC-998 magic value /// @return isParent True if parentTokenId is a valid parent tokenId and false if there is no parent tokenId function tokenOwnerOf( uint256 _tokenId ) external view returns ( bytes32 tokenOwner, uint256 parentTokenId, bool isParent ); /// @notice Transfer token from owner address to a token /// @param _from The owner address /// @param _toContract The ERC-721 contract of the receiving token /// @param _toToken The receiving token /// @param _data Additional data with no specified format function transferToParent( address _from, address _toContract, uint256 _toTokenId, uint256 _tokenId, bytes _data ) external; /// @notice Transfer token from a token to an address /// @param _fromContract The address of the owning contract /// @param _fromTokenId The owning token /// @param _to The address the token is transferred to. /// @param _tokenId The token that is transferred /// @param _data Additional data with no specified format function transferFromParent( address _fromContract, uint256 _fromTokenId, address _to, uint256 _tokenId, bytes _data ) external; /// @notice Transfer a token from a token to another token /// @param _fromContract The address of the owning contract /// @param _fromTokenId The owning token /// @param _toContract The ERC-721 contract of the receiving token /// @param _toToken The receiving token /// @param _tokenId The token that is transferred /// @param _data Additional data with no specified format function transferAsChild( address _fromContract, uint256 _fromTokenId, address _toContract, uint256 _toTokenId, uint256 _tokenId, bytes _data ) external; } ``` #### `rootOwnerOf` ```solidity /// @notice Get the root owner of tokenId. /// @param _tokenId The token to query for a root owner address /// @return rootOwner The root owner at the top of tree of tokens and ERC-998 magic value. function rootOwnerOf(uint256 _tokenId) public view returns (bytes32 rootOwner); ``` This function traverses token owners until the root owner address of `_tokenId` is found. The first 4 bytes of rootOwner contain the ERC-998 magic value `0xcd740db5`. The last 20 bytes contain the root owner address. The magic value is returned because this function may be called on contracts when it is unknown if the contracts have a `rootOwnerOf` function. The magic value is used in such calls to ensure a valid return value is received. If it is unknown whether a contract has the `rootOwnerOf` function then the first four bytes of the `rootOwner` return value must be compared to `0xcd740db5`. `0xcd740db5` is equal to: ```solidity this.rootOwnerOf.selector ^ this.rootOwnerOfChild.selector ^ this.tokenOwnerOf.selector ^ this.ownerOfChild.selector; ``` Here is an example of a value returned by `rootOwnerOf`. `0xcd740db50000000000000000e5240103e1ff986a2c8ae6b6728ffe0d9a395c59` #### tokenOwnerOf ```solidity /// @notice Get the owner address and parent token (if there is one) of a token /// @param _tokenId The tokenId to query. /// @return tokenOwner The owner address of the token and ERC-998 magic value. /// @return parentTokenId The parent owner of the token /// @return isParent True if parentTokenId is a valid parent tokenId and false if there is no parent tokenId function tokenOwnerOf( uint256 _tokenId ) external view returns ( bytes32 tokenOwner, uint256 parentTokenId, bool isParent ); ``` This function is used to get the owning address and parent tokenId of a token if there is one stored in the contract. If `isParent` is true then `tokenOwner` is the owning ERC-721 contract address and `parentTokenId` is a valid parent tokenId. If `isParent` is false then `tokenOwner` is a user address and `parentTokenId` does not contain a valid parent tokenId and must be ignored. The first 4 bytes of `tokenOwner` contain the ERC-998 magic value `0xcd740db5`. The last 20 bytes contain the token owner address. The magic value is returned because this function may be called on contracts when it is unknown if the contracts have a `tokenOwnerOf` function. The magic value is used in such calls to ensure a valid return value is received. If it is unknown whether a contract has the `rootOwnerOf` function then the first four bytes of the `tokenOwner` return value must be compared to `0xcd740db5`. #### transferToParent ```solidity /// @notice Transfer token from owner address to a token /// @param _from The owner address /// @param _toContract The ERC-721 contract of the receiving token /// @param _toToken The receiving token /// @param _data Additional data with no specified format function transferToParent( address _from, address _toContract, uint256 _toTokenId, uint256 _tokenId, bytes _data ) external; ``` This function is used to transfer a token from an address to a token. `msg.sender` must be authenticated. This function must check that `_toToken` exists in `_toContract` and throw if not. #### transferFromParent ```solidity /// @notice Transfer token from a token to an address /// @param _fromContract The address of the owning contract /// @param _fromTokenId The owning token /// @param _to The address the token is transferred to. /// @param _tokenId The token that is transferred /// @param _data Additional data with no specified format function transferFromParent( address _fromContract, uint256 _fromTokenId, address _to, uint256 _tokenId, bytes _data ) external; ``` This function is used to transfer a token from a token to an address. `msg.sender` must be authenticated. This function must check that `_fromContract` and `_fromTokenId` own `_tokenId` and throw not. #### transferAsChild ```solidity /// @notice Transfer a token from a token to another token /// @param _fromContract The address of the owning contract /// @param _fromTokenId The owning token /// @param _toContract The ERC-721 contract of the receiving token /// @param _toToken The receiving token /// @param _tokenId The token that is transferred /// @param _data Additional data with no specified format function transferAsChild( address _fromContract, uint256 _fromTokenId, address _toContract, uint256 _toTokenId, uint256 _tokenId, bytes _data ) external; ``` This function is used to transfer a token from a token to another token. `msg.sender` must be authenticated. This function must check that `_toToken` exists in `_toContract` and throw if not. This function must check that `_fromContract` and `_fromTokenId` own `_tokenId` and throw if not. #### ERC-721 Bottom-Up Composable Enumeration Optional interface for bottom-up composable enumeration: ```solidity /// @dev The ERC-165 identifier for this interface is 0x8318b539 interface ERC998ERC721BottomUpEnumerable { /// @notice Get the number of ERC-721 tokens owned by parent token. /// @param _parentContract The contract the parent ERC-721 token is from. /// @param _parentTokenId The parent tokenId that owns tokens // @return uint256 The number of ERC-721 tokens owned by parent token. function totalChildTokens( address _parentContract, uint256 _parentTokenId ) external view returns (uint256); /// @notice Get a child token by index /// @param _parentContract The contract the parent ERC-721 token is from. /// @param _parentTokenId The parent tokenId that owns the token /// @param _index The index position of the child token /// @return uint256 The child tokenId owned by the parent token function childTokenByIndex( address _parentContract, uint256 _parentTokenId, uint256 _index ) external view returns (uint256); } ``` ### ERC-20 Bottom-Up Composable ERC-20 bottom-up composables are ERC-20 tokens that attach themselves to ERC-721 tokens, or are owned by a user address like standard ERC-20 tokens. When owned by an ERC-721 token, ERC-20 bottom-up composable contracts store the owning address of a token and the parent tokenId. ERC-20 bottom-up composables add several methods to the ERC-20 and `ERC-223` interfaces allowing for querying the balance of parent tokens, and transferring tokens to, from, and between parent tokens. This functionality can be implemented by adding one additional mapping to track balances of tokens, in addition to the standard mapping for tracking user address balances. ```solidity /// @dev This mapping tracks standard ERC20/`ERC-223` ownership, where an address owns /// a particular amount of tokens. mapping(address => uint) userBalances; /// @dev This additional mapping tracks ERC-998 ownership, where an ERC-721 token owns /// a particular amount of tokens. This tracks contractAddres => tokenId => balance mapping(address => mapping(uint => uint)) nftBalances; ``` The complete interface is below. ```solidity /// @title `ERC998ERC20` Bottom-Up Composable Fungible Token /// @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-998.md /// Note: The ERC-165 identifier for this interface is 0xffafa991 interface ERC998ERC20BottomUp { /// @dev This emits when a token is transferred to an ERC-721 token /// @param _toContract The contract the token is transferred to /// @param _toTokenId The token the token is transferred to /// @param _amount The amount of tokens transferred event TransferToParent( address indexed _toContract, uint256 indexed _toTokenId, uint256 _amount ); /// @dev This emits when a token is transferred from an ERC-721 token /// @param _fromContract The contract the token is transferred from /// @param _fromTokenId The token the token is transferred from /// @param _amount The amount of tokens transferred event TransferFromParent( address indexed _fromContract, uint256 indexed _fromTokenId, uint256 _amount ); /// @notice Get the balance of a non-fungible parent token /// @param _tokenContract The contract tracking the parent token /// @param _tokenId The ID of the parent token /// @return amount The balance of the token function balanceOfToken( address _tokenContract, uint256 _tokenId ) external view returns (uint256 amount); /// @notice Transfer tokens from owner address to a token /// @param _from The owner address /// @param _toContract The ERC-721 contract of the receiving token /// @param _toToken The receiving token /// @param _amount The amount of tokens to transfer function transferToParent( address _from, address _toContract, uint256 _toTokenId, uint256 _amount ) external; /// @notice Transfer token from a token to an address /// @param _fromContract The address of the owning contract /// @param _fromTokenId The owning token /// @param _to The address the token is transferred to /// @param _amount The amount of tokens to transfer function transferFromParent( address _fromContract, uint256 _fromTokenId, address _to, uint256 _amount ) external; /// @notice Transfer token from a token to an address, using `ERC-223` semantics /// @param _fromContract The address of the owning contract /// @param _fromTokenId The owning token /// @param _to The address the token is transferred to /// @param _amount The amount of tokens to transfer /// @param _data Additional data with no specified format, can be used to specify the sender tokenId function transferFromParentERC223( address _fromContract, uint256 _fromTokenId, address _to, uint256 _amount, bytes _data ) external; /// @notice Transfer a token from a token to another token /// @param _fromContract The address of the owning contract /// @param _fromTokenId The owning token /// @param _toContract The ERC-721 contract of the receiving token /// @param _toToken The receiving token /// @param _amount The amount tokens to transfer function transferAsChild( address _fromContract, uint256 _fromTokenId, address _toContract, uint256 _toTokenId, uint256 _amount ) external; } ``` #### balanceOfToken ```solidity /// @notice Get the balance of a non-fungible parent token /// @param _tokenContract The contract tracking the parent token /// @param _tokenId The ID of the parent token /// @return amount The balance of the token function balanceOfToken( address _tokenContract, uint256 _tokenId ) external view returns (uint256 amount); ``` This function returns the balance of a non-fungible token. It mirrors the standard ERC-20 method `balanceOf`, but accepts the address of the parent token's contract, and the parent token's ID. This method behaves identically to `balanceOf`, but checks for ownership by ERC-721 tokens rather than user addresses. #### `transferToParent` ```solidity /// @notice Transfer tokens from owner address to a token /// @param _from The owner address /// @param _toContract The ERC-721 contract of the receiving token /// @param _toToken The receiving token /// @param _amount The amount of tokens to transfer function transferToParent( address _from, address _toContract, uint256 _toTokenId, uint256 _amount ) external; ``` This function transfers an amount of tokens from a user address to an ERC-721 token. This function MUST ensure that the recipient contract implements ERC-721 using the ERC-165 `supportsInterface` function. This function SHOULD ensure that the recipient token actually exists, by calling `ownerOf` on the recipient token's contract, and ensuring it neither throws nor returns the zero address. This function MUST emit the `TransferToParent` event upon a successful transfer (in addition to the standard ERC-20 `Transfer` event!). This function MUST throw if the `_from` account balance does not have enough tokens to spend. #### `transferFromParent` ```solidity /// @notice Transfer token from a token to an address /// @param _fromContract The address of the owning contract /// @param _fromTokenId The owning token /// @param _to The address the token is transferred to /// @param _amount The amount of tokens to transfer function transferFromParent( address _fromContract, uint256 _fromTokenId, address _to, uint256 _amount ) external; ``` This function transfers an amount of tokens from an ERC-721 token to an address. This function MUST emit the `TransferFromParent` event upon a successful transfer (in addition to the standard ERC-20 `Transfer` event!). This function MUST throw if the balance of the sender ERC-721 token is less than the `_amount` specified. This function MUST verify that the `msg.sender` owns the sender ERC-721 token, and MUST throw otherwise. #### `transferFromParentERC223` ```solidity /// @notice Transfer token from a token to an address, using `ERC-223` semantics /// @param _fromContract The address of the owning contract /// @param _fromTokenId The owning token /// @param _to The address the token is transferred to /// @param _amount The amount of tokens to transfer /// @param _data Additional data with no specified format, can be used to specify the sender tokenId function transferFromParentERC223( address _fromContract, uint256 _fromTokenId, address _to, uint256 _amount, bytes _data ) external; ``` This function transfers an amount of tokens from an ERC-721 token to an address. This function has identical requirements to `transferFromParent`, except that it additionally MUST invoke `tokenFallback` on the recipient address, if the address is a contract, as specified by `ERC-223`. #### transferAsChild 1 ```solidity /// @notice Transfer a token from a token to another token /// @param _fromContract The address of the owning contract /// @param _fromTokenId The owning token /// @param _toContract The ERC-721 contract of the receiving token /// @param _toToken The receiving token /// @param _amount The amount tokens to transfer function transferAsChild( address _fromContract, uint256 _fromTokenId, address _toContract, uint256 _toTokenId, uint256 _amount ) external; ``` This function transfers an amount of tokens from an ERC-721 token to another ERC-721 token. This function MUST emit BOTH the `TransferFromParent` and `TransferToParent` events (in addition to the standard ERC-20 `Transfer` event!). This function MUST throw if the balance of the sender ERC-721 token is less than the `_amount` specified. This function MUST verify that the `msg.sender` owns the sender ERC-721 token, and MUST throw otherwise. This function MUST ensure that the recipient contract implements ERC-721 using the ERC-165 `supportsInterface` function. This function SHOULD ensure that the recipient token actually exists, by calling `ownerOf` on the recipient token's contract, and ensuring it neither throws nor returns the zero address. ### Notes For backwards-compatibility, implementations MUST emit the standard ERC-20 `Transfer` event when a transfer occurs, regardless of whether the sender and recipient are addresses or ERC-721 tokens. In the case that either sender or recipient are tokens, the corresponding parameter in the `Transfer` event SHOULD be the contract address of the token. Implementations MUST implement all ERC-20 and `ERC-223` functions in addition to the functions specified in this interface. ## Rationale Two different kinds of composable (top-down and bottom-up) exist to handle different use cases. A regular ERC-721 token cannot own a top-down composable, but it can own a bottom-up composable. A bottom-up composable cannot own a regular ERC-721 but a top-down composable can own a regular ERC-721 token. Having multiple kinds of composables enable different token ownership possibilities. ### Which Kind of Composable To Use? If you want to transfer regular ERC-721 tokens to non-fungible tokens, then use top-down composables. If you want to transfer non-fungible tokens to regular ERC-721 tokens then use bottom-up composables. ### Explicit Transfer Parameters Every ERC-998 transfer function includes explicit parameters to specify the prior owner and the new owner of a token. Explicitly providing **from** and **to** is done intentionally to avoid situations where tokens are transferred in unintended ways. Here is an example of what could occur if **from** was not explicitly provided in transfer functions: > An exchange contract is an approved operator in a specific composable contract for user A, user B and user C. > > User A transfers token 1 to user B. At the same time the exchange contract transfers token 1 to user C (with the implicit intention to transfer from user A). User B gets token 1 for a minute before it gets incorrectly transferred to user C. The second transfer should have failed but it didn't because no explicit **from** was provided to ensure that token 1 came from user A. ## Backwards Compatibility Composables are designed to work with ERC-721, `ERC-223` and ERC-20 tokens. Some older ERC-721 contracts do not have a `safeTransferFrom` function. The `getChild` function can still be used to transfer a token to an ERC-721 top-down composable. If an ERC-20 contract does not have the `ERC-223` function `transfer(address _to, uint _value, bytes _data)` then the `getERC20` function can still be used to transfer ERC-20 tokens to an ERC-20 top-down composable. ## Reference Implementation An implementation can be found here: `https://github.com/mattlockyer/composables-998` ## Security Considerations Needs discussion. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

tokenURI Interoperability

Fri, 13 Apr 2018 00:00:00 +0000

## Abstract [ERC-721](./eip-721.md) introduced a `tokenURI` function for non-fungible tokens to handle miscellaneous metadata such as: - thumbnail image - title - description - special asset properties - etc. This ERC adds a `tokenURI` function to [ERC-20](./eip-20.md), and extends [ERC-721](./eip-721.md) and [ERC-1155](./eip-1155.md) to enable interoperability between all three types of token URI. ## Motivation See the note about the metadata extension in [ERC-721](./eip-721.md#rationale). The same arguments apply to ERC-20. Being able to use similar mechanisms to extract metadata for ERC-20, ERC-721, ERC-1155, and future standards is useful for determining: - What type of token a contract is (if any); - How to display a token to a user, either in an asset listing page or on a dedicated token page; and - Determining the capabilities of the token ## Specification The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174. ### Interoperability Metadata The following TypeScript interface is used in later sections: ```typescript /** * Interoperability metadata. * This can be extended by other proposals. * * All fields MUST be optional. * **Not every field has to be a boolean.** Any optional JSON-serializable object can be used by extensions. */ interface InteroperabilityMetadata { /** * This MUST be true if this is ERC-1046 Token Metadata, otherwise, this MUST be omitted. * Setting this to true indicates to wallets that the address should be treated as an ERC-20 token. **/ erc1046?: boolean | undefined; /** * This MUST be true if this is ERC-721 Token Metadata, otherwise, this MUST be omitted. * Setting this to true indicates to wallets that the address should be treated as an ERC-721 token. **/ erc721?: boolean | undefined; /** * This MUST be true if this is ERC-1155 Token Metadata, otherwise, this MUST be omitted. * Setting this to true indicates to wallets that the address should be treated as an ERC-1155 token. **/ erc1155?: boolean | undefined; } ``` ### ERC-20 Extension #### ERC-20 Interface Extension Compliant contracts MUST implement the following Solidity interface: ```solidity pragma solidity ^0.8.0; /// @title ERC-20 Metadata Extension interface ERC20TokenMetadata /* is ERC20 */ { /// @notice Gets an ERC-721-like token URI /// @dev The resolved data MUST be in JSON format and support ERC-1046's ERC-20 Token Metadata Schema function tokenURI() external view returns (string); } ``` #### ERC-20 Token Metadata Schema The resolved JSON of the `tokenURI` described in the ERC-20 Interface Extension section MUST conform to the following TypeScript interface: ```typescript /** * Asset Metadata */ interface ERC20TokenMetadata { /** * Interoperability, to differentiate between different types of tokens and their corresponding URIs. **/ interop: InteroperabilityMetadata; /** * The name of the ERC-20 token. * If the `name()` function is present in the ERC-20 token and returns a nonempty string, these MUST be the same value. */ name?: string; /** * The symbol of the ERC-20 token. * If the `symbol()` function is present in the ERC-20 token and returns a nonempty string, these MUST be the same value. */ symbol?: string; /** * The decimals of the ERC-20 token. * If the `decimals()` function is present in the ERC-20 token, these MUST be the same value. * Defaults to 18 if neither this parameter nor the ERC-20 `decimals()` function are present. */ decimals?: number; /** * Provides a short one-paragraph description of the ERC-20 token, without any markup or newlines. */ description?: string; /** * A URI pointing to a resource with mime type `image/*` that represents this token. * If the image is a bitmap, it SHOULD have a width between 320 and 1080 pixels * The image SHOULD have an aspect ratio between 1.91:1 and 4:5 inclusive. */ image?: string; /** * One or more URIs each pointing to a resource with mime type `image/*` that represents this token. * If an image is a bitmap, it SHOULD have a width between 320 and 1080 pixels * Images SHOULD have an aspect ratio between 1.91:1 and 4:5 inclusive. */ images?: string[]; /** * One or more URIs each pointing to a resource with mime type `image/*` that represent an icon for this token. * If an image is a bitmap, it SHOULD have a width between 320 and 1080 pixels, and MUST have a height equal to its width * Images MUST have an aspect ratio of 1:1, and use a transparent background */ icons?: string[]; } ``` ### ERC-721 Extension #### Extension to the ERC-721 Metadata Schema Contracts that implement ERC-721 and use its token metadata URI SHOULD to use the following TypeScript extension to the metadata URI: ```typescript interface ERC721TokenMetadataInterop extends ERC721TokenMetadata { /** * Interoperability, to avoid confusion between different token URIs **/ interop: InteroperabilityMetadata; } ``` ### ERC-1155 Extension #### ERC-1155 Interface Extension [ERC-1155](./eip-1155.md)-compliant contracts using the metadata extension SHOULD implement the following Solidity interface: ```solidity pragma solidity ^0.8.0; /// @title ERC-1155 Metadata URI Interoperability Extension interface ERC1155TokenMetadataInterop /* is ERC1155 */ { /// @notice Gets an ERC-1046-compliant ERC-1155 token URI /// @param tokenId The token ID to get the URI of /// @dev The resolved data MUST be in JSON format and support ERC-1046's Extension to the ERC-1155 Token Metadata Schema /// This MUST be the same URI as the `uri(tokenId)` function, if present. function tokenURI(uint256 tokenId) external view returns (string); } ``` #### Extension to the ERC-1155 Metadata Schema Contracts that implement ERC-1155 and use its token metadata URI are RECOMMENDED to use the following extension to the metadata URI. Contracts that implement the interface described in the ERC-1155 Interface Extension section MUST use the following TypeScript extension: ```typescript interface ERC1155TokenMetadataInterop extends ERC1155TokenMetadata { /** * Interoperability, to avoid confusion between different token URIs **/ interop: InteroperabilityMetadata; } ``` ### Miscellaneous Recommendations To save gas, it is RECOMMENDED for compliant contracts not to implement the `name()`, `symbol()`, or `decimals()` functions, and instead to only include them in the metadata URI. Additionally, for ERC-20 tokens, if the decimals is `18`, then it is NOT RECOMMENDED to include the `decimals` field in the metadata. ## Rationale This ERC makes adding metadata to ERC-20 tokens more straightforward for developers, with minimal to no disruption to the overall ecosystem. Using the same parameter name makes it easier to reuse code. Additionally, the recommendations not to use ERC-20's `name`, `symbol`, and `decimals` functions save gas. Built-in interoperability is useful as otherwise it might not be easy to differentiate the type of the token. Interoperability could be done using [ERC-165](./eip-165.md), but static calls are time-inefficient for wallets and websites, and is generally inflexible. Instead, including interoperability data in the token URI increases flexibility while also giving a performance increase. ## Backwards Compatibility This EIP is fully backwards compatible as its implementation simply extends the functionality of ERC-20 tokens and is optional. Additionally, it makes backward compatible recommendations for ERC-721 and ERC-1155 tokens. ## Security Considerations ### Server-Side Request Forgery (SSRF) Wallets should be careful about making arbitrary requests to URLs. As such, it is recommended for wallets to sanitize the URI by whitelisting specific schemes and ports. A vulnerable wallet could be tricked into, for example, modifying data on a locally-hosted redis database. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Ethereum Lightweight Identity

Thu, 03 May 2018 00:00:00 +0000

## Simple Summary A registry for key and attribute management of lightweight blockchain identities. ## Abstract This ERC describes a standard for creating and updating identities with a limited use of blockchain resources. An identity can have an unlimited number of `delegates` and `attributes` associated with it. Identity creation is as simple as creating a regular key pair ethereum account, which means that it's free (no gas costs) and all ethereum accounts are valid identities. Furthermore this ERC is fully [DID compliant](https://w3c-ccg.github.io/did-spec/). ## Motivation As we have been developing identity systems for the last couple of years at uPort it has become apparent that the cost of identity creation is a large issue. The previous Identity proposal [ERC-725](./eip-725.md) faces this exact issue. Our requirements when creating this ERC is that identity creation should be free, and should be possible to do in an offline environment (e.g. refugee scenario). However it must also be possible to rotate keys without changing the primary identifier of the identity. The identity system should be fit to use off-chain as well as on-chain. ## Definitions * `Identifier`: a piece of data that uniquely identifies the identity, an ethereum address * `delegate`: an address that is delegated for a specific time to perform some sort of function on behalf of an identity * `delegateType`: the type of a delegate, is determined by a protocol or application higher up Examples: * `did-jwt` * `raiden` * `attribute`: a piece of data associated with the identity ## Specification This ERC specifies a contract called `EthereumDIDRegistry` that is deployed once and can then be commonly used by everyone. ### Identity ownership By default an identity is owned by itself, meaning whoever controls the ethereum account with that address. The owner can be updated to a new key pair account or to a multisig account etc. #### identityOwner Returns the owner of the given identity. ```js function identityOwner(address identity) public view returns(address); ``` #### changeOwner Sets the owner of the given identity to another ethereum account. ```js function changeOwner(address identity, address newOwner) public; ``` #### changeOwnerSigned Same as above but with raw signature. ```js function changeOwnerSigned(address identity, uint8 sigV, bytes32 sigR, bytes32 sigS, address newOwner) public; ``` ### Delegate management Delegates can be used both on- and off-chain. They all have a `delegateType` which can be used to specify the purpose of the delegate. #### validDelegate Returns true if the given `delegate` is a delegate with type `delegateType` of `identity`. ```js function validDelegate(address identity, bytes32 delegateType, address delegate) public view returns(bool); ``` #### addDelegate Adds a new delegate with the given type. `validity` indicates the number of seconds that the delegate will be valid for, after which it will no longer be a delegate of `identity`. ```js function addDelegate(address identity, bytes32 delegateType, address delegate, uint validity) public; ``` #### addDelegateSigned Same as above but with raw signature. ```js function addDelegateSigned(address identity, uint8 sigV, bytes32 sigR, bytes32 sigS, bytes32 delegateType, address delegate, uint validity) public; ``` #### revokeDelegate Revokes the given `delegate` for the given `identity`. ```js function revokeDelegate(address identity, bytes32 delegateType, address delegate) public; ``` #### revokeDelegateSigned Same as above but with raw signature. ```js function revokeDelegateSigned(address identity, uint8 sigV, bytes32 sigR, bytes32 sigS, bytes32 delegateType, address delegate) public; ``` ### Attribute management Attributes contain simple data about the identity. They can be managed only by the owner of the identity. #### setAttribute Sets an attribute with the given `name` and `value`, valid for `validity` seconds. ```js function setAttribute(address identity, bytes32 name, bytes value, uint validity) public; ``` #### setAttributeSigned Same as above but with raw signature. ```js function setAttributeSigned(address identity, uint8 sigV, bytes32 sigR, bytes32 sigS, bytes32 name, bytes value, uint validity) public; ``` #### revokeAttribute Revokes an attribute. ```js function revokeAttribute(address identity, bytes32 name, bytes value) public; ``` #### revokeAttributeSigned Same as above but with raw signature. ```js function revokeAttributeSigned(address identity, uint8 sigV, bytes32 sigR, bytes32 sigS, bytes32 name, bytes value) public; ``` ### Events #### DIDOwnerChanged MUST be triggered when `changeOwner` or `changeOwnerSigned` was successfully called. ```js event DIDOwnerChanged( address indexed identity, address owner, uint previousChange ); ``` #### DIDDelegateChanged MUST be triggered when a change to a delegate was successfully made. ```js event DIDDelegateChanged( address indexed identity, bytes32 delegateType, address delegate, uint validTo, uint previousChange ); ``` #### DIDAttributeChanged MUST be triggered when a change to an attribute was successfully made. ```js event DIDAttributeChanged( address indexed identity, bytes32 name, bytes value, uint validTo, uint previousChange ); ``` ### Efficient lookup of events through linked identity events Contract Events are a useful feature for storing data from smart contracts exclusively for off-chain use. Unfortunately current ethereum implementations provide a very inefficient lookup mechanism. By using linked events that always link to the previous block with a change for the identity, we can solve this problem with much improved performance. Each identity has its previously changed block stored in the `changed` mapping. 1. Lookup `previousChange` block for identity 2. Lookup all events for given identity address using web3, but only for the `previousChange` block 3. Do something with the event 4. Find `previousChange` from the event and repeat Example code: ```js const history = [] previousChange = await didReg.changed(identity) while (previousChange) { const filter = await didReg.allEvents({topics: [identity], fromBlock: previousChange, toBlock: previousChange}) const events = await getLogs(filter) previousChange = undefined for (let event of events) { history.unshift(event) previousChange = event.args.previousChange } } ``` ### Building a DID document for an identity The primary owner key should be looked up using `identityOwner(identity)`. This should be the first of the publicKeys listed. Iterate through the `DIDDelegateChanged` events to build a list of additional keys and authentication sections as needed. The list of delegateTypes to include is still to be determined. Iterate through `DIDAttributeChanged` events for service entries, encryption public keys and other public names. The attribute names are still to be determined. ## Rationale For on-chain interactions Ethereum has a built in account abstraction that can be used regardless of whether the account is a smart contract or a key pair. Any transaction has a `msg.sender` as the verified send of the transaction. Since each Ethereum transaction has to be funded, there is a growing trend of on-chain transactions that are authenticated via an externally created signature and not by the actual transaction originator. This allows 3rd party funding services or receiver pays without any fundamental changes to the underlying Ethereum architecture. These kinds of transactions have to be signed by an actual key pair and thus can not be used to represent smart contract based Ethereum accounts. We propose a way of a Smart Contract or regular key pair delegating signing for various purposes to externally managed key pairs. This allows a smart contract to be represented both on-chain as well as off-chain or in payment channels through temporary or permanent delegates. ## Backwards Compatibility All ethereum accounts are valid identities (and DID compatible) using this standard. This means that any wallet provider that uses key pair accounts already supports the bare minimum of this standard, and can implement `delegate` and `attribute` functionality by simply using the `ethr-did` referenced below. As the **DID Auth** standard solidifies it also means that all of these wallets will be compatible with the [DID decentralized login system](https://github.com/decentralized-identity). ## Implementation [ethr-did-registry](https://github.com/uport-project/ethr-did-registry/blob/develop/contracts/EthereumDIDRegistry.sol) (`EthereumDIDRegistry` contract implementation) [ethr-did-resolver](https://github.com/uport-project/ethr-did-resolver) (DID compatible resolver) [ethr-did](https://github.com/uport-project/ethr-did) (javascript library for using the identity) ### Deployment The address for the `EthereumDIDRegistry` is `0xdca7ef03e98e0dc2b855be647c39abe984fcf21b` on Mainnet, Ropsten, Rinkeby and Kovan. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Formalize IPFS hash into ENS(Ethereum Name Service) resolver

Wed, 02 May 2018 00:00:00 +0000

## Simple Summary To specify the mapping protocol between resources stored on IPFS and ENS(Ethereum Naming Service). ## Abstract The following standard details the implementation of how to combine the IPFS cryptographic hash unique fingerprint with ENS public resolver. This standard provides a functionality to get and set IPFS online resources to ENS resolver. We think that this implementation is not only aim to let more developers and communities to provide more use cases, but also leverage the human-readable features to gain more user adoption accessing decentralized resources. We considered the IPFS ENS resolver mapping standard a cornerstone for building future Web3.0 service. ## Motivation To build a fully decentralized web service, it’s necessary to have a decentralized file storage system. Here comes the IPFS, for three following advantages : - Address large amounts of data, and has unique cryptographic hash for every record. - Since IPFS is also based on peer to peer network, it can be really helpful to deliver large amounts of data to users, in a safer way and lower the millions of cost for the bandwidth. - IPFS stores files in high efficient way via tracking version history for every file, and removing the duplications across the network. Those features makes perfect match for integrating into ENS, and these make users can easily access content through ENS, and show up in the normal browser. ## Specification The condition now is that the IPFS file fingerprint using base58 and in the meantime, the Ethereum uses hex in API to encode the binary data. So that need a way to process the condition requires not only we need to transfer from IPFS to Ethereum, but also need to convert it back. To solve these requirements, we can use binary buffer bridging that gap. When mapping the IPFS base58 string to ENS resolver, first we convert the Base58 to binary buffer, turn the buffer to hex encrypted format, and save to the contract. Once we want to get the IPFS resources address represented by the specific ENS, we can first find the mapping information stored as hex format before, extract the hex format to binary buffer, and finally turn that to IPFS Base58 address string. ## Rationale To implement the specification, need two methods from ENS public resolver contract, when we want to store IPFS file fingerprint to contract, convert the Base58 string identifier to the hex format and invoke the `setMultihash` method below : ```solidity function setMultihash(bytes32 node, bytes hash) public only_owner(node); ``` Whenever users need to visit the ENS content, we call the `multihash` method to get the IPFS hex data, transfer to the Base58 format, and return the IPFS resources to use. ```solidity function multihash(bytes32 node) public view returns (bytes); ``` ## Test Cases To implement the way to transfer from base58 to hex format and the reverse one, using the ‘multihashes’ library to deal with the problem. The library link : [https://www.npmjs.com/package/multihashes](https://www.npmjs.com/package/multihashes) To implement the method transfer from IPFS(Base58) to hex format : ```javascript import multihash from 'multihashes' export const toHex = function(ipfsHash) { let buf = multihash.fromB58String(ipfsHash); return '0x' + multihash.toHexString(buf); } ``` To implement the method transfer from hex format to IPFS(Base58) : ```javascript import multihash from 'multihashes' export const toBase58 = function(contentHash) { let hex = contentHash.substring(2) let buf = multihash.fromHexString(hex); return multihash.toB58String(buf); } ``` ## Implementation The use case can be implemented as browser extension. Users can easily download the extension, and easily get decentralized resources by just typing the ENS just like we normally type the DNS to browser the website. Solve the current pain for normal people can not easily visit the total decentralized website. The workable implementation repository : [https://github.com/PortalNetwork/portal-network-browser-extension](https://github.com/PortalNetwork/portal-network-browser-extension) ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Status Codes

Sat, 05 May 2018 00:00:00 +0000

## Simple Summary Broadly applicable status codes for smart contracts. ## Abstract This standard outlines a common set of status codes in a similar vein to HTTP statuses. This provides a shared set of signals to allow smart contracts to react to situations autonomously, expose localized error messages to users, and so on. The current state of the art is to either `revert` on anything other than a clear success (ie: require human intervention), or return a low-context `true` or `false`. Status codes are similar-but-orthogonal to `revert`ing with a reason, but aimed at automation, debugging, and end-user feedback (including translation). _They are fully compatible with both `revert` and `revert`-with-reason._ As is the case with HTTP, having a standard set of known codes has many benefits for developers. They remove friction from needing to develop your own schemes for every contract, makes inter-contract automation easier, and makes it easier to broadly understand which of the finite states your request produced. Importantly, it makes it much easier to distinguish between expected errors states, truly exceptional conditions that require halting execution, normal state transitions, and various success cases. ## Motivation ### Semantic Density HTTP status codes are widely used for this purpose. BEAM languages use atoms and tagged tuples to signify much the same information. Both provide a lot of information both to the programmer (debugging for instance), and to the program that needs to decide what to do next. Status codes convey a much richer set of information [than Booleans](https://existentialtype.wordpress.com/2011/03/15/boolean-blindness/), and are able to be reacted to autonomously unlike arbitrary strings. ### User Experience (UX) _End users get little to no feedback, and there is no translation layer._ Since ERC1066 status codes are finite and known in advance, we can leverage [ERC-1444](./eip-1444.md) to provide global, human-readable sets of status messages. These may also be translated into any language, differing levels of technical detail, added as `revert` messages, natspecs, and so on. Status codes convey a much richer set of information than Booleans, and are able to be reacted to autonomously unlike arbitrary strings. ### Developer Experience (DX) _Developers currently have very little context exposed by their smart contracts._ At time of writing, other than stepping through EVM execution and inspecting memory dumps directly, it is very difficult to understand what is happening during smart contract execution. By returning more context, developers can write well-decomposed tests and assert certain codes are returned as an expression of where the smart contract got to. This includes status codes as bare values, `event`s, and `revert`s. Having a fixed set of codes also makes it possible to write common helper functions to react in common ways to certain signals. This can live off- or on-chain library, lowering the overhead in building smart contracts, and helping raise code quality with trusted shared components. We also see a desire for this [in transactions](./eip-658.md), and there's no reason that these status codes couldn't be used by the EVM itself. ### Smart Contract Autonomy _Smart contracts don’t know much about the result of a request beyond pass/fail; they can be smarter with more context._ Smart contracts are largely intended to be autonomous. While each contract may define a specific interface, having a common set of semantic codes can help developers write code that can react appropriately to various situations. While clearly related, status codes are complementary to `revert`-with-reason. Status codes are not limited to rolling back the transaction, and may represent known error states without halting execution. They may also represent off-chain conditions, supply a string to revert, signal time delays, and more. All of this enables contracts to share a common vocabulary of state transitions, results, and internal changes, without having to deeply understand custom status enums or the internal business logic of collaborator contracts. ## Specification ### Format Codes are returned either on their own, or as the first value of a multiple return. ```solidity // Status only function isInt(uint num) public pure returns (byte status) { return hex"01"; } // Status and value uint8 private counter; function safeIncrement(uint8 interval) public returns (byte status, uint8 newCounter) { uint8 updated = counter + interval; if (updated >= counter) { counter = updated; return (hex"01", updated); } else { return (hex"00", counter); } } ``` ### Code Table Codes break nicely into a 16x16 matrix, represented as a 2-digit hex number. The high nibble represents the code's kind or "category", and the low nibble contains the state or "reason". We present them below as separate tables per range for explanatory and layout reasons. **NB: Unspecified codes are _not_ free for arbitrary use, but rather open for further specification.** #### `0x0*` Generic General codes. These double as bare "reasons", since `0x01 == 1`. | Code | Description | |--------|-----------------------------------------| | `0x00` | Failure | | `0x01` | Success | | `0x02` | Awaiting Others | | `0x03` | Accepted | | `0x04` | Lower Limit or Insufficient | | `0x05` | Receiver Action Requested | | `0x06` | Upper Limit | | `0x07` | [reserved] | | `0x08` | Duplicate, Unnecessary, or Inapplicable | | `0x09` | [reserved] | | `0x0A` | [reserved] | | `0x0B` | [reserved] | | `0x0C` | [reserved] | | `0x0D` | [reserved] | | `0x0E` | [reserved] | | `0x0F` | Informational or Metadata | #### `0x1*` Permission & Control Also used for common state machine actions (ex. "stoplight" actions). | Code | Description | |--------|---------------------------------------------------| | `0x10` | Disallowed or Stop | | `0x11` | Allowed or Go | | `0x12` | Awaiting Other's Permission | | `0x13` | Permission Requested | | `0x14` | Too Open / Insecure | | `0x15` | Needs Your Permission or Request for Continuation | | `0x16` | Revoked or Banned | | `0x17` | [reserved] | | `0x18` | Not Applicable to Current State | | `0x19` | [reserved] | | `0x1A` | [reserved] | | `0x1B` | [reserved] | | `0x1C` | [reserved] | | `0x1D` | [reserved] | | `0x1E` | [reserved] | | `0x1F` | Permission Details or Control Conditions | #### `0x2*` Find, Inequalities & Range This range is broadly intended for finding and matching. Data lookups and order matching are two common use cases. | Code | Description | |--------|-------------------------------------| | `0x20` | Not Found, Unequal, or Out of Range | | `0x21` | Found, Equal or In Range | | `0x22` | Awaiting Match | | `0x23` | Match Request Sent | | `0x24` | Below Range or Underflow | | `0x25` | Request for Match | | `0x26` | Above Range or Overflow | | `0x27` | [reserved] | | `0x28` | Duplicate, Conflict, or Collision | | `0x29` | [reserved] | | `0x2A` | [reserved] | | `0x2B` | [reserved] | | `0x2C` | [reserved] | | `0x2D` | [reserved] | | `0x2E` | [reserved] | | `0x2F` | Matching Meta or Info | #### `0x3*` Negotiation & Governance Negotiation, and very broadly the flow of such transactions. Note that "other party" may be more than one actor (not necessarily the sender). | Code | Description | |--------|-----------------------------------------| | `0x30` | Sender Disagrees or Nay | | `0x31` | Sender Agrees or Yea | | `0x32` | Awaiting Ratification | | `0x33` | Offer Sent or Voted | | `0x34` | Quorum Not Reached | | `0x35` | Receiver's Ratification Requested | | `0x36` | Offer or Vote Limit Reached | | `0x37` | [reserved] | | `0x38` | Already Voted | | `0x39` | [reserved] | | `0x3A` | [reserved] | | `0x3B` | [reserved] | | `0x3C` | [reserved] | | `0x3D` | [reserved] | | `0x3E` | [reserved] | | `0x3F` | Negotiation Rules or Participation Info | #### `0x4*` Availability & Time Service or action availability. | Code | Description | |--------|------------------------------------------------------| | `0x40` | Unavailable | | `0x41` | Available | | `0x42` | Paused | | `0x43` | Queued | | `0x44` | Not Available Yet | | `0x45` | Awaiting Your Availability | | `0x46` | Expired | | `0x47` | [reserved] | | `0x48` | Already Done | | `0x49` | [reserved] | | `0x4A` | [reserved] | | `0x4B` | [reserved] | | `0x4C` | [reserved] | | `0x4D` | [reserved] | | `0x4E` | [reserved] | | `0x4F` | Availability Rules or Info (ex. time since or until) | #### `0x5*` Tokens, Funds & Finance Special token and financial concepts. Many related concepts are included in other ranges. | Code | Description | |--------|---------------------------------| | `0x50` | Transfer Failed | | `0x51` | Transfer Successful | | `0x52` | Awaiting Payment From Others | | `0x53` | Hold or Escrow | | `0x54` | Insufficient Funds | | `0x55` | Funds Requested | | `0x56` | Transfer Volume Exceeded | | `0x57` | [reserved] | | `0x58` | Funds Not Required | | `0x59` | [reserved] | | `0x5A` | [reserved] | | `0x5B` | [reserved] | | `0x5C` | [reserved] | | `0x5D` | [reserved] | | `0x5E` | [reserved] | | `0x5F` | Token or Financial Information | #### `0x6*` TBD Currently unspecified. (Full range reserved) #### `0x7*` TBD Currently unspecified. (Full range reserved) #### `0x8*` TBD Currently unspecified. (Full range reserved) #### `0x9*` TBD Currently unspecified. (Full range reserved) #### `0xA*` Application-Specific Codes Contracts may have special states that they need to signal. This proposal only outlines the broadest meanings, but implementers may have very specific meanings for each, as long as they are coherent with the broader definition. | Code | Description | |--------|----------------------------------------| | `0xA0` | App-Specific Failure | | `0xA1` | App-Specific Success | | `0xA2` | App-Specific Awaiting Others | | `0xA3` | App-Specific Acceptance | | `0xA4` | App-Specific Below Condition | | `0xA5` | App-Specific Receiver Action Requested | | `0xA6` | App-Specific Expiry or Limit | | `0xA7` | [reserved] | | `0xA8` | App-Specific Inapplicable Condition | | `0xA9` | [reserved] | | `0xAA` | [reserved] | | `0xAB` | [reserved] | | `0xAC` | [reserved] | | `0xAD` | [reserved] | | `0xAE` | [reserved] | | `0xAF` | App-Specific Meta or Info | #### `0xB*` TBD Currently unspecified. (Full range reserved) #### `0xC*` TBD Currently unspecified. (Full range reserved) #### `0xD*` TBD Currently unspecified. (Full range reserved) #### `0xE*` Encryption, Identity & Proofs Actions around signatures, cryptography, signing, and application-level authentication. The meta code `0xEF` is often used to signal a payload describing the algorithm or process used. | Code | Description | |--------|-------------------------------------| | `0xE0` | Decrypt Failure | | `0xE1` | Decrypt Success | | `0xE2` | Awaiting Other Signatures or Keys | | `0xE3` | Signed | | `0xE4` | Unsigned or Untrusted | | `0xE5` | Signature Required | | `0xE6` | Known to be Compromised | | `0xE7` | [reserved] | | `0xE8` | Already Signed or Not Encrypted | | `0xE9` | [reserved] | | `0xEA` | [reserved] | | `0xEB` | [reserved] | | `0xEC` | [reserved] | | `0xED` | [reserved] | | `0xEE` | [reserved] | | `0xEF` | Cryptography, ID, or Proof Metadata | #### `0xF*` Off-Chain For off-chain actions. Much like th `0x0*: Generic` range, `0xF*` is very general, and does little to modify the reason. Among other things, the meta code `0xFF` may be used to describe what the off-chain process is. | Code | Description | |--------|-----------------------------------| | `0xF0` | Off-Chain Failure | | `0xF1` | Off-Chain Success | | `0xF2` | Awaiting Off-Chain Process | | `0xF3` | Off-Chain Process Started | | `0xF4` | Off-Chain Service Unreachable | | `0xF5` | Off-Chain Action Required | | `0xF6` | Off-Chain Expiry or Limit Reached | | `0xF7` | [reserved] | | `0xF8` | Duplicate Off-Chain Request | | `0xF9` | [reserved] | | `0xFA` | [reserved] | | `0xFB` | [reserved] | | `0xFC` | [reserved] | | `0xFD` | [reserved] | | `0xFE` | [reserved] | | `0xFF` | Off-Chain Info or Meta | ### As a Grid | | `0x0*` General | `0x1*` Permission & Control | `0x2*` Find, Inequalities & Range | `0x3*` Negotiation & Governance | `0x4*` Availability & Time | `0x5*` Tokens, Funds & Finance | `0x6*` TBD | `0x7*` TBD | `0x8*` TBD | `0x9*` TBD | `0xA*` Application-Specific Codes | `0xB*` TBD | `0xC*` TBD | `0xD*` TBD | `0xE*` Encryption, Identity & Proofs | `0xF*` Off-Chain | |--------|------------------------------------------------|----------------------------------------------------------|--------------------------------------------|------------------------------------------------|-------------------------------------------------------------|----------------------------------------|-------------------|-------------------|-------------------|-------------------|-----------------------------------------------|-------------------|-------------------|-------------------|--------------------------------------------|------------------------------------------| | `0x*0` | `0x00` Failure | `0x10` Disallowed or Stop | `0x20` Not Found, Unequal, or Out of Range | `0x30` Sender Disagrees or Nay | `0x40` Unavailable | `0x50` Transfer Failed | `0x60` [reserved] | `0x70` [reserved] | `0x80` [reserved] | `0x90` [reserved] | `0xA0` App-Specific Failure | `0xB0` [reserved] | `0xC0` [reserved] | `0xD0` [reserved] | `0xE0` Decrypt Failure | `0xF0` Off-Chain Failure | | `0x*1` | `0x01` Success | `0x11` Allowed or Go | `0x21` Found, Equal or In Range | `0x31` Sender Agrees or Yea | `0x41` Available | `0x51` Transfer Successful | `0x61` [reserved] | `0x71` [reserved] | `0x81` [reserved] | `0x91` [reserved] | `0xA1` App-Specific Success | `0xB1` [reserved] | `0xC1` [reserved] | `0xD1` [reserved] | `0xE1` Decrypt Success | `0xF1` Off-Chain Success | | `0x*2` | `0x02` Awaiting Others | `0x12` Awaiting Other's Permission | `0x22` Awaiting Match | `0x32` Awaiting Ratification | `0x42` Paused | `0x52` Awaiting Payment From Others | `0x62` [reserved] | `0x72` [reserved] | `0x82` [reserved] | `0x92` [reserved] | `0xA2` App-Specific Awaiting Others | `0xB2` [reserved] | `0xC2` [reserved] | `0xD2` [reserved] | `0xE2` Awaiting Other Signatures or Keys | `0xF2` Awaiting Off-Chain Process | | `0x*3` | `0x03` Accepted | `0x13` Permission Requested | `0x23` Match Request Sent | `0x33` Offer Sent or Voted | `0x43` Queued | `0x53` Hold or Escrow | `0x63` [reserved] | `0x73` [reserved] | `0x83` [reserved] | `0x93` [reserved] | `0xA3` App-Specific Acceptance | `0xB3` [reserved] | `0xC3` [reserved] | `0xD3` [reserved] | `0xE3` Signed | `0xF3` Off-Chain Process Started | | `0x*4` | `0x04` Lower Limit or Insufficient | `0x14` Too Open / Insecure | `0x24` Below Range or Underflow | `0x34` Quorum Not Reached | `0x44` Not Available Yet | `0x54` Insufficient Funds | `0x64` [reserved] | `0x74` [reserved] | `0x84` [reserved] | `0x94` [reserved] | `0xA4` App-Specific Below Condition | `0xB4` [reserved] | `0xC4` [reserved] | `0xD4` [reserved] | `0xE4` Unsigned or Untrusted | `0xF4` Off-Chain Service Unreachable | | `0x*5` | `0x05` Receiver Action Required | `0x15` Needs Your Permission or Request for Continuation | `0x25` Request for Match | `0x35` Receiver's Ratification Requested | `0x45` Awaiting Your Availability | `0x55` Funds Requested | `0x65` [reserved] | `0x75` [reserved] | `0x85` [reserved] | `0x95` [reserved] | `0xA5` App-Specific Receiver Action Requested | `0xB5` [reserved] | `0xC5` [reserved] | `0xD5` [reserved] | `0xE5` Signature Required | `0xF5` Off-Chain Action Required | | `0x*6` | `0x06` Upper Limit | `0x16` Revoked or Banned | `0x26` Above Range or Overflow | `0x36` Offer or Vote Limit Reached | `0x46` Expired | `0x56` Transfer Volume Exceeded | `0x66` [reserved] | `0x76` [reserved] | `0x86` [reserved] | `0x96` [reserved] | `0xA6` App-Specific Expiry or Limit | `0xB6` [reserved] | `0xC6` [reserved] | `0xD6` [reserved] | `0xE6` Known to be Compromised | `0xF6` Off-Chain Expiry or Limit Reached | | `0x*7` | `0x07` [reserved] | `0x17` [reserved] | `0x27` [reserved] | `0x37` [reserved] | `0x47` [reserved] | `0x57` [reserved] | `0x67` [reserved] | `0x77` [reserved] | `0x87` [reserved] | `0x97` [reserved] | `0xA7` [reserved] | `0xB7` [reserved] | `0xC7` [reserved] | `0xD7` [reserved] | `0xE7` [reserved] | `0xF7` [reserved] | | `0x*8` | `0x08` Duplicate, Unnecessary, or Inapplicable | `0x18` Not Applicable to Current State | `0x28` Duplicate, Conflict, or Collision | `0x38` Already Voted | `0x48` Already Done | `0x58` Funds Not Required | `0x68` [reserved] | `0x78` [reserved] | `0x88` [reserved] | `0x98` [reserved] | `0xA8` App-Specific Inapplicable Condition | `0xB8` [reserved] | `0xC8` [reserved] | `0xD8` [reserved] | `0xE8` Already Signed or Not Encrypted | `0xF8` Duplicate Off-Chain Request | | `0x*9` | `0x09` [reserved] | `0x19` [reserved] | `0x29` [reserved] | `0x39` [reserved] | `0x49` [reserved] | `0x59` [reserved] | `0x69` [reserved] | `0x79` [reserved] | `0x89` [reserved] | `0x99` [reserved] | `0xA9` [reserved] | `0xB9` [reserved] | `0xC9` [reserved] | `0xD9` [reserved] | `0xE9` [reserved] | `0xF9` [reserved] | | `0x*A` | `0x0A` [reserved] | `0x1A` [reserved] | `0x2A` [reserved] | `0x3A` [reserved] | `0x4A` [reserved] | `0x5A` [reserved] | `0x6A` [reserved] | `0x7A` [reserved] | `0x8A` [reserved] | `0x9A` [reserved] | `0xAA` [reserved] | `0xBA` [reserved] | `0xCA` [reserved] | `0xDA` [reserved] | `0xEA` [reserved] | `0xFA` [reserved] | | `0x*B` | `0x0B` [reserved] | `0x1B` [reserved] | `0x2B` [reserved] | `0x3B` [reserved] | `0x4B` [reserved] | `0x5B` [reserved] | `0x6B` [reserved] | `0x7B` [reserved] | `0x8B` [reserved] | `0x9B` [reserved] | `0xAB` [reserved] | `0xBB` [reserved] | `0xCB` [reserved] | `0xDB` [reserved] | `0xEB` [reserved] | `0xFB` [reserved] | | `0x*C` | `0x0C` [reserved] | `0x1C` [reserved] | `0x2C` [reserved] | `0x3C` [reserved] | `0x4C` [reserved] | `0x5C` [reserved] | `0x6C` [reserved] | `0x7C` [reserved] | `0x8C` [reserved] | `0x9C` [reserved] | `0xAC` [reserved] | `0xBC` [reserved] | `0xCC` [reserved] | `0xDC` [reserved] | `0xEC` [reserved] | `0xFC` [reserved] | | `0x*D` | `0x0D` [reserved] | `0x1D` [reserved] | `0x2D` [reserved] | `0x3D` [reserved] | `0x4D` [reserved] | `0x5D` [reserved] | `0x6D` [reserved] | `0x7D` [reserved] | `0x8D` [reserved] | `0x9D` [reserved] | `0xAD` [reserved] | `0xBD` [reserved] | `0xCD` [reserved] | `0xDD` [reserved] | `0xED` [reserved] | `0xFD` [reserved] | | `0x*E` | `0x0E` [reserved] | `0x1E` [reserved] | `0x2E` [reserved] | `0x3E` [reserved] | `0x4E` [reserved] | `0x5E` [reserved] | `0x6E` [reserved] | `0x7E` [reserved] | `0x8E` [reserved] | `0x9E` [reserved] | `0xAE` [reserved] | `0xBE` [reserved] | `0xCE` [reserved] | `0xDE` [reserved] | `0xEE` [reserved] | `0xFE` [reserved] | | `0x*F` | `0x0F` Informational or Metadata | `0x1F` Permission Details or Control Conditions | `0x2F` Matching Meta or Info | `0x3F` Negotiation Rules or Participation Info | `0x4F` Availability Rules or Info (ex. time since or until) | `0x5F` Token or Financial Information | `0x6F` [reserved] | `0x7F` [reserved] | `0x8F` [reserved] | `0x9F` [reserved] | `0xAF` App-Specific Meta or Info | `0xBF` [reserved] | `0xCF` [reserved] | `0xDF` [reserved] | `0xEF` Cryptography, ID, or Proof Metadata | `0xFF` Off-Chain Info or Meta | ### Example Function Change ```solidity uint256 private startTime; mapping(address => uint) private counters; // Before function increase() public returns (bool _available) { if (now < startTime && counters[msg.sender] == 0) { return false; }; counters[msg.sender] += 1; return true; } // After function increase() public returns (byte _status) { if (now < start) { return hex"44"; } // Not yet available if (counters[msg.sender] == 0) { return hex"10"; } // Not authorized counters[msg.sender] += 1; return hex"01"; // Success } ``` ### Example Sequence Diagrams ``` 0x03 = Waiting 0x31 = Other Party (ie: not you) Agreed 0x41 = Available 0x44 = Not Yet Available Exchange AwesomeCoin DEX TraderBot + + + | | buy(AwesomeCoin) | | | <------------------------+ | buy() | | | <---------------------+ | | | | | Status [0x44] | | +---------------------> | Status [0x44] | | +------------------------> | | | | | | isDoneYet() | | | <------------------------+ | | | | | Status [0x44] | | +------------------------> | | | | | | | | Status [0x41] | | +---------------------> | | | | | | buy() | | | <---------------------+ | | | | | | | | Status [0x31] | | +---------------------> | Status [0x31] | | +------------------------> | | | | | | | | | | | | | + + + ``` ``` 0x01 = Generic Success 0x10 = Disallowed 0x11 = Allowed Token Validation Buyer RegulatedToken TokenValidator IDChecker SpendLimiter + + + + + | buy() | | | | +------------------------> | check() | | | | +-----------------------> | check() | | | | +-----------------------> | | | | | | | | | | Status [0x10] | | | | Status [0x10] | <-----------------------+ | | revert() | <-----------------------+ | | | <------------------------+ | | | | | | | | +---------------------------+ | | | | | | | | | | | Updates ID with provider | | | | | | | | | | | +---------------------------+ | | | | | | | | | | buy() | | | | +------------------------> | check() | | | | +-----------------------> | check() | | | | +-----------------------> | | | | | | | | | | Status [0x11] | | | | | <-----------------------+ | | | | | | | | | | check() | | | +-------------------------------------------> | | | | | | | | | | Status [0x11] | | | Status [0x11] | <-------------------------------------------+ | Status [0x01] | <-----------------------+ | | | <------------------------+ | | | | | | | | | | | | | | | | | | + + + + + ``` ## Rationale ### Encoding Status codes are encoded as a `byte`. Hex values break nicely into high and low nibbles: `category` and `reason`. For instance, `0x01` stands for general success (ie: `true`) and `0x00` for general failure (ie: `false`). As a general approach, all even numbers are blocking conditions (where the receiver does not have control), and odd numbers are nonblocking (the receiver is free to continue as they wish). This aligns both a simple bit check with the common encoding of Booleans. `bytes1` is very lightweight, portable, easily interoperable with `uint8`, cast from `enum`s, and so on. #### Alternatives Alternate schemes include `bytes32` and `uint8`. While these work reasonably well, they have drawbacks. `uint8` feels even more similar to HTTP status codes, and enums don't require as much casting. However does not break as evenly as a square table (256 doesn't look as nice in base 10). Packing multiple codes into a single `bytes32` is nice in theory, but poses additional challenges. Unused space may be interpreted as `0x00 Failure`, you can only efficiently pack four codes at once, and there is a challenge in ensuring that code combinations are sensible. Forcing four codes into a packed representation encourages multiple status codes to be returned, which is often more information than strictly necessarily. This can lead to paradoxical results (ex `0x00` and `0x01` together), or greater resources allocated to interpreting 256⁴ (4.3 billion) permutations. ### Multiple Returns While there may be cases where packing a byte array of status codes may make sense, the simplest, most forwards-compatible method of transmission is as the first value of a multiple return. Familiarity is also a motivating factor. A consistent position and encoding together follow the principle of least surprise. It is both viewable as a "header" in the HTTP analogy, or like the "tag" in BEAM tagged tuples. ### Human Readable Developers should not be required to memorize 256 codes. However, they break nicely into a table. Cognitive load is lowered by organizing the table into categories and reasons. `0x10` and `0x11` belong to the same category, and `0x04` shares a reason with `0x24` While this repository includes helper enums, we have found working directly in the hex values to be quite natural. Status code `0x10` is just as comfortable as HTTP 401, for example. #### Localizations One commonly requested application of this spec is human-readable translations of codes. This has been moved to its own proposal: [ERC-1444](./eip-1444.md), primarily due to a desire to keep both specs focused. ### Extensibility The `0xA` category is reserved for application-specific statuses. In the case that 256 codes become insufficient, `bytes1` may be embedded in larger byte arrays. ### EVM Codes The EVM also returns a status code in transactions; specifically `0x00` and `0x01`. This proposal both matches the meanings of those two codes, and could later be used at the EVM level. ### Empty Space Much like how HTTP status codes have large unused ranges, there are totally empty sections in this proposal. The intent is to not impose a complete set of codes up front, and to allow users to suggest uses for these spaces as time progresses. ### Beyond Errors This spec is intended to be much more than a set of common errors. One design goal is to enable easier contract-to-contract communication, protocols built on top of status codes, and flows that cross off-chain. Many of these cases include either expected kinds of exception state (as opposed to true errors), neutral states, time logic, and various successes. Just like how HTTP 200 has a different meaning from HTTP 201, ERC-1066 status codes can relay information between contract beyond simply pass or fail. They can be thought of as the edges in a graph that has smart contracts as nodes. ### Fully `revert`able _This spec is fully compatible with `revert`-with-reason and does not intend to supplant it in any way._ Both by reverting with a common code, the developer can determine what went wrong from a set of known error states. Further, by leveraging ERC-1066 and a translation table (such as in ERC-1444) in conjunction, developers and end users alike can receive fully automated human-readable error messages in the language and phrasing of their choice. ### Nibble Order Nibble order makes no difference to the machine, and is purely mnemonic. This design was originally in opposite order, but changed it for a few convenience factors. Since it's a different scheme from HTTP, it may feel strange initially, but becomes very natural after a couple hours of use. #### Short Forms Generic is `0x0*`, general codes are consistent with their integer representations ```solidity hex"1" == hex"01" == 1 // with casting ``` #### Contract Categories Many applications will always be part of the same category. For instance, validation will generally be in the `0x10` range. ```solidity contract Whitelist { mapping(address => bool) private whitelist; uint256 private deadline; byte constant private prefix = hex"10"; check(address _, address _user) returns (byte _status) { if (now >= deadline) { return prefix | 5; } if (whitelist[_user]) { return prefix | 1; } return prefix; } } ``` #### Helpers This above also means that working with app-specific enums is slightly easier, and also saves gas (fewer operations required). ```solidity enum Sleep { Awake, Asleep, BedOccupied, WindingDown } // From the helper library function appCode(Sleep _state) returns (byte code) { return byte(160 + _state); // 160 = 0xA0 } // Versus function appCode(Sleep _state) returns (byte code) { return byte((16 * _state) + 10); // 10 = 0xA } ``` ## Implementation Reference cases and helper libraries (Solidity and JS) can be found at: * [Source Code](https://github.com/fission-suite/fission-codes/) * [Package on npm](https://www.npmjs.com/package/fission-codes/) ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Gas relay for contract calls

Fri, 04 May 2018 00:00:00 +0000

## Simple Summary A standard interface for gas abstraction in top of smart contracts. Allows users to offer [EIP-20] token for paying the gas used in a call. ## Abstract A main barrier for the adoption of DApps is the requirement of multiple tokens for executing in chain actions. Allowing users to sign messages to show intent of execution, but allowing a third party relayer to execute them can circumvent this problem, while ETH will always be required for ethereum transactions, it's possible for smart contract to take [EIP-191] signatures and forward a payment incentive to an untrusted party with ETH for executing the transaction. ## Motivation Standardizing a common format for them, as well as a way in which the user allows the transaction to be paid in tokens, gives app developers a lot of flexibility and can become the main way in which app users interact with the Blockchain. ## Specification ### Methods #### executeGasRelay Executes `_execData` with current `lastNonce()` and pays `msg.sender` the gas used in specified `_gasToken`. ```solidity function executeGasRelay(bytes calldata _execData, uint256 _gasPrice, uint256 _gasLimit, address _gasToken, address _gasRelayer, bytes calldata _signature) external; ``` ### executeGasRelayMsg Returns the `executeGasRelay` message used for signing messages.. ```solidity function executeGasRelayMsg(uint256 _nonce, bytes memory _execData, uint256 _gasPrice, uint256 _gasLimit, address _gasToken, address _gasRelayer) public pure returns (bytes memory); ``` #### executeGasRelayERC191Msg Returns the [EIP-191] of `executeGasRelayMsg` used for signing messages and for verifying the execution. ```solidity function executeGasRelayERC191Msg(uint256 _nonce, bytes memory _execData, uint256 _gasPrice, uint256 _gasLimit, address _gasToken, address _gasRelayer) public view returns (bytes memory); ``` #### lastNonce Returns the current nonce for the gas relayed messages. ```solidity function lastNonce() public returns (uint nonce); ``` ### Signed Message The signed message require the following fields: * Nonce: A nonce *or* a timestamp; * Execute Data: the bytecode to be executed by the account contract; * Gas Price: The gas price (paid in the selected token); * Gas Limit: The gas reserved to the relayed execution; * Gas Token: A token in which the gas will be paid (leave 0 for ether); * Gas Relayer: the beneficiary of gas refund for this call (leave 0 for `block.coinbase`) . #### Signing the message The message **MUST** be signed as [EIP-191] standard, and the called contract **MUST** also implement [EIP-1271] which must validate the signed messages. Messages **MUST** be signed by the owner of the account contract executing. If the owner is a contract, it must implement [EIP-1271] interface and forward validation to it. In order to be compliant, the transaction **MUST** request to sign a "messageHash" that is a concatenation of multiple fields. The fields **MUST** be constructed as this method: The first and second fields are to make it [EIP-191] compliant. Starting a transaction with `byte(0x19)` ensure the signed data from being a [valid ethereum transaction](https://github.com/ethereum/wiki/wiki/RLP). The second argument is a version control byte. The third being the validator address (the account contract address) according to version 0 of [EIP-191]. The remaining arguments being the application specific data for the gas relay: chainID as per [EIP-1344], execution nonce, execution data, agreed gas Price, gas limit of gas relayed call, gas token to pay back and gas relayer authorized to receive the reward. The [EIP-191] message must be constructed as follows: ```solidity keccak256( abi.encodePacked( byte(0x19), //ERC-191 - the initial 0x19 byte byte(0x0), //ERC-191 - the version byte address(this), //ERC-191 - version data (validator address) chainID, bytes4( keccak256("executeGasRelay(uint256,bytes,uint256,uint256,address,address)") ), _nonce, _execData, _gasPrice, _gasLimit, _gasToken, _gasRelayer ) ) ``` ## Rationale User pain points: * users don't want to think about ether * users don't want to think about backing up private keys or seed phrases * users want to be able to pay for transactions using what they already have on the system, be apple pay, xbox points or even a credit card * Users don’t want to sign a new transaction at every move * Users don’t want to download apps/extensions (at least on the desktop) to connect to their apps App developer pain points: * Many apps use their own token and would prefer to use those as the main accounting * Apps want to be able to have apps in multiple platforms without having to share private keys between devices or have to spend transaction costs moving funds between them * Token developers want to be able for their users to be able to move funds and pay fees in the token * While the system provides fees and incentives for miners, there are no inherent business model for wallet developers (or other apps that initiate many transactions) Using signed messages, specially combined with an account contract that holds funds, and multiple disposable ether-less keys that can sign on its behalf, solves many of these pain points. ### Multiple signatures More than one signed transaction with the same parameter can be executed by this function at the same time, by passing all signatures in the `messageSignatures` field. That field will split the signature in multiple 72 character individual signatures and evaluate each one. This is used for cases in which one action might require the approval of multiple parties, in a single transaction. If multiple signatures are required, then all signatures should then be *ordered by account* and the account contract should implement signatures checks locally (`JUMP`) on [EIP-1271] interface which might forward (`STATIC_CALL`) the [EIP-1271] signature check to owner contract. ### Keep track of nonces: Note that `executeGasRelay` function does not take a `_nonce` as parameter. The contract knows what is the current nonce, and can only execute the transactions in order, therefore there is no reason Nonces work similarly to normal ethereum transactions: a transaction can only be executed if it matches the last nonce + 1, and once a transaction has occurred, the `lastNonce` will be updated to the current one. This prevents transactions to be executed out of order or more than once. Contracts may accept transactions without nonce (nonce = 0). The contract then must keep the full hash of the transaction to prevent it from being replayed. This would allows contracts to have more flexibilities as you can sign a transaction that can be executed out of order or not at all, but it uses more memory for each transaction. It can be used, for instance, for transactions that the user wants to schedule in the future but cannot know its future nonce, or transactions that are made for state channel contracts that are not guaranteed to be executed or are only executed when there's some dispute. ### Execute transaction After signature validation, the evaluation of `_execBytes` is up to the account contract implementation, it's role of the wallet to properly use the account contract and it's gas relay method. A common pattern is to expose an interface which can be only called by the contract itself. The `_execBytes` could entirely forward the call in this way, as example: `address(this).call.gas(_gasLimit)(_execData);` Where `_execData` could call any method of the contract itself, for example: - `call(address to, uint256 value, bytes data)`: allow any type of ethereum call be performed; - `create(uint256 value, bytes deployData)`: allows create contract - `create2(uint256 value, bytes32 salt, bytes deployData)`: allows create contract with deterministic address - `approveAndCall(address token, address to, uint256 value, bytes data)`: allows safe approve and call of an ERC20 token. - `delegatecall(address codeBase, bytes data)`: allows executing code stored on other contract - `changeOwner(address newOwner)`: Some account contracts might allow change of owner - `foo(bytes bar)`: Some account contracts might have custom methods of any format. The standardization of account contracts is not scope of this ERC, and is presented here only for illustration on possible implementations. Using a self call to evaluate `_execBytes` is not mandatory, depending on the account contract logic, the evaluation could be done locally. ### Gas accounting and refund The implementing contract must keep track of the gas spent. One way to do it is to first call `gasLeft()` at the beginning of the function and then after executing the desired action and compare the difference. The contract then will make a token transfer (or ether, if `tokenAddress` is nil) in the value of `gasSpent * gasPrice` to the `_gasRelayer`, that is the account that deployed the message. If `_gasRelayer` is zero, then the funds **MUST** go to `block.coinbase`. If there are not enough funds, or if the total surpasses `gasLimit` then the transaction **MUST** revert. If the executed transaction fails internally, nonces should still be updated and gas needs to be paid. Contracts are not obligated to support ether or any other token they don’t want and can be implemented to only accept refunds in a few tokens of their choice. ### Usage examples This scheme opens up a great deal of possibilities on interaction as well as different experiments on business models: * Apps can create individual identities contract for their users which holds the actual funds and then create a different private key for each device they log into. Other apps can use the same identity and just ask to add permissioned public keys to manage the device, so that if one individual key is lost, no ether is lost. * An app can create its own token and only charge their users in its internal currency for any ethereum transaction. The currency units can be rounded so it looks more similar to actual amount of transactions: a standard transaction always costs 1 token, a very complex transaction costs exactly 2, etc. Since the app is the issuer of the transactions, they can do their own Sybil verifications and give a free amount of currency units to new users to get them started. * A game company creates games with a traditional monthly subscription, either by credit card or platform-specific microtransactions. Private keys never leave the device and keep no ether and only the public accounts are sent to the company. The game then signs transactions on the device with gas price 0, sends them to the game company which checks who is an active subscriber and batches all transactions and pays the ether themselves. If the company goes bankrupt, the gamers themselves can set up similar subscription systems or just increase the gas price. End result is a **ethereum based game in which gamers can play by spending apple, google or xbox credits**. * A standard token is created that doesn’t require its users to have ether, and instead allows tokens to be transferred by paying in tokens. A wallet is created that signs messages and send them via whisper to the network, where other nodes can compete to download the available transactions, check the current gas price, and select those who are paying enough tokens to cover the cost. **The result is a token that the end users never need to keep any ether and can pay fees in the token itself.** * A DAO is created with a list of accounts of their employees. Employees never need to own ether, instead they sign messages, send them to whisper to a decentralized list of relayers which then deploy the transactions. The DAO contract then checks if the transaction is valid and sends ether to the deployers. Employees have an incentive not to use too many of the companies resources because they’re identifiable. The result is that the users of the DAO don't need to keep ether, and **the contract ends up paying for it's own gas usage**. ## Backwards Compatibility There is no issues with backwards compatibility, however for future upgrades, as `_execData` contains arbitrary data evaluated by the account contract, it's up to the contract to handle properly this data and therefore contracts can gas relay any behavior with the current interface. ## Test Cases TBD ## Implementation One initial implementation of such a contract can be found at [Status.im account-contracts repository](https://github.com/status-im/account-contracts/blob/develop/contracts/account/AccountGasAbstract.sol) Other version is implemented as Gnosis Safe variant in: https://github.com/status-im/safe-contracts ### Similar implementations The idea of using signed messages as executable intent has been around for a while and many other projects are taking similar approaches, which makes it a great candidate for a standard that guarantees interoperability: * [EIP-877](https://github.com/ethereum/EIPs/pull/877) An attempt of doing the same but with a change in the protocol * [Status](https://github.com/status-im/ideas/issues/73) * [Aragon](https://github.com/aragonlabs/pay-protocol) (this might not be the best link to show their work in this area) * [Token Standard Functions for Preauthorized Actions](https://github.com/ethereum/EIPs/issues/662) * [Token Standard Extension 865](https://github.com/ethereum/EIPs/issues/865) * [Iuri Matias: Transaction Relay](https://github.com/iurimatias/TransactionRelay) * [uPort: Meta transactions](https://github.com/uport-project/uport-identity#send-a-meta-tx) * [uPort: safe Identities](https://github.com/uport-project/uport-identity/blob/develop/docs/txRelay.md) * [Gnosis safe contracts](https://github.com/gnosis/safe-contracts) Swarm city uses a similar proposition for etherless transactions, called [Gas Station Service](https://github.com/swarmcity/SCLabs-gasstation-service), but it's a different approach. Instead of using signed messages, a traditional ethereum transaction is signed on an etherless account, the transaction is then sent to a service that immediately sends the exact amount of ether required and then publishes the transaction. ## Security Considerations Deployers of transactions (relayers) should be able to call untrusted contracts, which provides no guarantees that the contract they are interacting with correctly implements the standard and they will be reimbursed for gas. To prevent being fooled by bad implementations, relayers must **estimate the outcome of a transaction**, and only include/sign transactions which have a desired outcome. Is also interest of relayers to maintaining a private reputation of contracts they interact with, as well as keep track of which tokens and for which `gasPrice` they’re willing to deploy transactions. ## Copyright Copyright and related rights waived via [CC0](/LICENSE). ## References * [Universal Logins talk at UX Unconf, Toronto](https://www.youtube.com/watch?v=qF2lhJzngto) [EIP-20]: ./eip-20.md [EIP-191]: ./eip-191.md [EIP-1271]: ./eip-1271.md [EIP-1344]: ./eip-1344.md

Universal login / signup using ENS subdomains

Fri, 04 May 2018 00:00:00 +0000

## Abstract This presents a method to replace the usual signup/login design pattern with a minimal ethereum native scheme, that doesn’t require passwords, backing up private keys nor typing seed phrases. From the user's point of view it will be very similar to patterns they’re already used to with second factor authentication (without relying in a central server), but for dapp developers it requires a new way to think about ethereum transactions. ## Simple Summary The unique identifier of the user is a contract that implements both Identity and the Executable Signed Messages ERCs. The user should not need to provide this address directly, only a ENS name pointing to it. These types of contracts are indirectly controlled by private keys that can sign messages indicating intents, which are then deployed to the contract by a third party (or a decentralized network of deployers). In this context, therefore, a device "logging into" an app using an identity, means that the device will generate a private key locally and then request an authorization to add that key as one of the signers of that identity, with a given set of permissions. Since that private key is only used for signing messages, it is not required to hold ether, tokens or assets, and if lost, it can be simply be replaced by a new one – the user's funds are kept on the identity contract. In this context, ethereum accounts are used in a manner more similar to auth tokens, rather than unique keys. The login process is as follows: #### 1) Request a name from the user The first step of the process is to request from the user the ENS name that points to their identity. If the user doesn’t have a login set up, the app should–if they have an integrated identity manager–provide an option to provide a subdomain or a name they own. **UX Note:** there are many ways to provide this interface, the app can ask if they want to signup/login before hand or simply directly ask them to type the name. Note that since it’s trivial to verify if a username exists, your app should adapt to it gracefully and not require the user to type their name twice. If they ask to signup and provide a name that exists then ask them if they want to login using that name, or similarly if they ask to connect to an existing name but type a non-existent name show them a nice alert and ask them if they want to create that name now. Don’t force them to type the same name twice in two different fields. #### 2.a) Create a new identity If the user doesn’t have an identity, the app should provide the option to create one for them. Each app must have one or more domains they control which they can create immediate subdomains on demand. The app therefore will make these actions on the background: 1. Generate a private key which it will keep saved locally on the device or browser, the safest way possible. 2. Create (or set up) an identity contract which supports both ERC720 and ERC1077 3. Register the private key created on step 1 as the *only* admin key of the contract (the app must not add any app-controlled key, except as a recovery option - see 5) 4. Register the requested subdomain and transfer its ownership to the contract (while the app controls the main domain and may keep the option to reassign them at will, the ownership of the subdomain itself should belong to the identity, therefore allowing them to transfer it) 5. (Optionally) Register a recovery method on the contract, which allows the user to regain access to the contract in case the main key is lost. All those steps can be designed to be set up in a single ethereum transaction. Since this step is not free, the app reserves the right to charge for registering users, or require the user to be verified in a sybil resistant manner of the app’s choosing (captcha, device ID registration, proof of work, etc) The user shouldn’t be forced to wait for transaction confirmation times. Instead, have an indicator somewhere on the app that shows the progress and then allow the user to interact with your app normally. It’s unlikely that they’ll need the identity in the first few minutes and if something goes wrong (username gets registered at the same time), you can then ask the user for an action. **Implementation note:** in order to save gas, some of these steps can be done in advance. The app can automatically deploy a small number of contracts when the gas price is low, and set up all their main variables to be 0xFFFFFF...FFFFF. These should be considered ‘vacant’ and when the user registers one, they will get a gas discount for freeing up space on the chain. This has the added benefit of allowing the user a choice in contract address/icon. #### 2.b) Connect to an existing identity If the user wants to connect with an existing identity, then the first thing the app needs to understand is what level of privilege it’s going to ask for: **Manager** the higher level, allows the key to initiate or sign transactions that change the identity itself, like adding or removing keys. An app should only require this level if it integrates an identity manager. Depending on how the identity is set up, it might require signature from more keys before these transactions can be deployed. **Action** this level allows the key to initiate or sign transactions on address other than itself. It can move funds, ether, assets etc. An app should only require this level of privilege if it’s a general purpose wallet or browser for sending ethereum transactions. Depending on how the identity is set up, it might require signature from more keys before these transactions can be deployed. **Encryption** the lower level has no right to initiate any transactions, but it can be used to represent the user in specific instances or off-chain signed messages. It’s the ideal level of privilege for games, chat or social media apps, as they can be used to sign moves, send messages, etc. If a game requires actual funds (say, to start a game with funds in stake) then it should still use the encryption level, and then require the main wallet/browser of the user to sign messages using the ethereum URI standard. Once the desired level is known, the app must take these steps: 1. **Generate a private key** which it will keep saved locally on the device or browser, the safest way possible. 2. **Query ens** to figure the existing address of the identity 3. **Generate the bytecode** for a transaction calling the function `addKey(PUBLICKEY,LEVEL)`. 4. **Broadcast a transaction request on a whisper channel** or some other decentralized network of peers. Details on this step require further discussions 1. **If web3 is available** then attempt calling web3.eth.sendTransaction. This can be automatic or prompted by user action. 1. **Attempt calling a URI** if the app supports [URL format for transaction requests EIP](./eip-681.md) then attempt calling this. This can be automatic or prompted by user action. 1. **Show a QR code**: with an EIP681 formatted URL. That QR code can be clickable to attempt to retry the other options, but it should be done last: if step 1 works, the user should receive a notification on their compatible device and won't need to use the QR code. Here's an example of a EIP681 compatible address to add a public key generated locally in the app: `ethereum:bob.example.eth?function=addKey(address='0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef',uint=1)` If adding the new key requires multiple signatures, or if the app receiving that request exclusiveky deals with executable signed messages and has no ether on itself, then it should follow the steps in the next section on how to request transactions. As before, the user shouldn’t be forced to wait for transaction confirmation times. Instead, have an indicator somewhere on the app the shows the progress and then allow the user to interact with your app normally. #### 3) Request transactions After step 2, the end result should be that your app should have the identity address of the user, their main ens name and a private key, whose public account is listed on the identity as one of their keys, with roles being either manager, action or encryption. Now it can start using that information to sign and execute transactions. **Not all transactions need to be on chain**, actually most common uses of signed messages should be off chain. If you have a chat app, for instance, you can use the local key for signing messages and sending it to the other parties, and they can just query the identity contract to see if that key actually comes from the user. If you have a game with funds at stake, only the first transaction moving funds and setting up the initial game needs to be executed by the identity: at each turn the players can sign a hash of the current state of the board and at the end, the last two plays can be used to determine the winner. Notice that keys can be revoked at any time, so your app should take that in consideration, for instance saving all keys at the start of the game. Keys that only need this lower level of privilege, should be set at level 4 (encryption). Once you decided you actually need an on-chain transaction, follow these steps: 1. **Figure out the TO, FROM, VALUE and DATA**. These are the basics of any ethereum transaction. `from` is the compatible contract you want the transaction to be deployed from. 2. **Check the privilege level you need:** if the `to` and `from` fields are the same contract, ie, if the transaction requires the identity to act upon itself (for instance, when adding or removing a key) then you need level 1 (management), otherwise it's 2 (action). Verify if the key your app owns correspond to the required level. 3. **Verify how many keys are required** by calling `requiredSignatures(uint level)` on the target contract 4. **Figure out gasLimit**: Estimate the gas cost of the desired transaction, and add a margin (recommended: add 100k gas) 5. **Figure out gasToken and gasPrice**: Check the current gas price considering network congestions and the market price of the token the user is going to pay with. Leave gasToken as 0 for ether. Leave gasPrice as 0 if you are deploying it yourself and subsidizing the costs elsewhere. 6. **Sign an executable signed transaction** by following that standard. After having all the signed executable message, we need to deploy it to the chain. If the transaction only requires a single signature, then the app provider can deploy it themselves. Send the transaction to the `from` address and attempt to call the function `executeSigned`, using the parameters and signature you just collected. If the transaction need to collect more signatures or the app doesn't have a deployable server, the app should follow these steps: 1. **Broadcast the transaction on a whisper channel** or some other decentralized network of peers. Details on this step require further discussions 2. **If web3 is available** then attempt calling web3.eth.personal_sign. This can be automatic or prompted by user action. 3. **Show a QR code**: with the signed transaction and the new data to be signed. That QR code can be clickable to attempt to retry the other options, but it should be done last: if step 1 works, the user should receive a notification on their compatible device and won't need to use the QR code. The goal is to keep broadcasting signatures via whisper until a node that is willing to deploy them is able to collect all messages. Once you've followed the above steps, watch the transaction pool to any transaction to that address and then take the user to your app. Once you seen the desired transaction, you can stop showing the QR code and proceed with the app, while keeping some indication that the transaction is in progress. Subscribe to the event `ExecutedSigned` of the desired contract: once you see the transaction with the nonce, you can call it a success. If you see a different transaction with the same or higher nonce (or timestamp) then you consider the transaction permanently failed and restart the process. ### Implementation No working examples of this implementation exists, but many developers have expressed interest in adopting it. This section will be edited in the future to reflect that. ### Conclusion and future improvements This scheme would allow much more lighter apps, that don’t require holding ether, and can keep unlocked private keys on the device to be able to send messages and play games without requesting user prompt every time. More work is needed to standardize common decentralized messaging protocols as well as open source tools for deployment nodes, in order to create a decentralized and reliable layer for message deployment. ### References * [Universal Logins talk at UX Unconf, Toronto](https://www.youtube.com/watch?v=qF2lhJzngto) ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Recoverable Token

Wed, 02 May 2018 00:00:00 +0000

## Simple Summary A standard interface for tokens that support chargebacks, theft prevention, and lost & found resolutions. ## Abstract The following standard allows for the implementation of a standard API for tokens extending ERC-20 or ERC-791. This standard provides basic functionality to recover stolen or lost accounts, as well as provide for the chargeback of tokens. ## Motivation To mitigate the effects of reasonably provable token or asset loss or theft and to help resolve other conflicts. Ethereum's protocol should not be modified because of loss, theft, or conflicts, but it is possible to solve these problems in the smart contract layer. ## Specification ## RecoverableToken ### Methods #### claimLost Reports the `lostAccount` address as being lost. MUST trigger the `AccountClaimedLost` event. After the time configured in `getLostAccountRecoveryTimeInMinutes` the implementer MUST provide a mechanism for determining the correct owner of the tokens held and moving the tokens to a new account. Account recoveries must trigger the `AccountRecovered` event. ``` js function claimLost(address lostAccount) returns (bool success) ``` #### cancelLostClaim Reports the `msg.sender`'s account as being not being lost. MUST trigger the `AccountClaimedLostCanceled` event. MUST fail if an account recovery process has already begun. Otherwise, this method MUST stop a dispute from being started to recover funds. ``` js function claimLost() returns (bool success) ``` #### reportStolen Reports the current address as being stolen. MUST trigger the `AccountFrozen` event. Successful calls MUST result in the `msg.sender`'s tokens being frozen. The implementer MUST provide a mechanism for determining the correct owner of the tokens held and moving the tokens to a new account. Account recoveries must trigger the `AccountRecovered` event. ``` js function reportStolen() returns (bool success) ``` #### chargeback Requests a reversal of transfer on behalf of `msg.sender`. The implementer MUST provide a mechanism for determining the correct owner of the tokens disputed and moving the tokens to the correct account. MUST comply with sender's chargeback window as value configured by `setPendingTransferTimeInMinutes`. ``` js function chargeback(uint256 pendingTransferNumber) returns (bool success) ``` #### getPendingTransferTimeInMinutes Get the time an account has to chargeback a transfer. ``` js function getPendingTransferTime(address account) view returns (uint256 minutes) ``` #### setPendingTransferTimeInMinutes Sets the time `msg.sender`'s account has to chargeback a transfer. MUST NOT change the time if the account has any pending transfers. ``` js function setPendingTransferTime(uint256 minutes) returns (bool success) ``` #### getLostAccountRecoveryTimeInMinutes Get the time account has to wait before a lost account dispute can start. ``` js function getLostAccountRecoveryTimeInMinutes(address account) view returns (uint256 minutes) ``` #### setLostAccountRecoveryTimeInMinutes Sets the time `msg.sender`'s account has to sit before a lost account dispute can start. MUST NOT change the time if the account has open disputes. ``` js function setLostAccountRecoveryTimeInMinutes(uint256 minutes) returns (bool success) ``` ### Events #### AccountRecovered The recovery of an account that was lost or stolen. ``` js event AccountClaimedLost(address indexed account, address indexed newAccount) ``` #### AccountClaimedLostCanceled An account claimed as being lost. ``` js event AccountClaimedLost(address indexed account) ``` #### AccountClaimedLost An account claimed as being lost. ``` js event AccountClaimedLost(address indexed account) ``` #### PendingTransfer A record of a transfer pending. ``` js event PendingTransfer(address indexed from, address indexed to, uint256 value, uint256 pendingTransferNumber) ``` #### ChargebackRequested A record of a chargeback being requested. ``` js event ChargebackRequested(address indexed from, address indexed to, uint256 value, uint256 pendingTransferNumber) ``` #### Chargeback A record of a transfer being reversed. ``` js event Chargeback(address indexed from, address indexed to, uint256 value, uint256 indexed pendingTransferNumber) ``` #### AccountFrozen A record of an account being frozen. MUST trigger when an account is frozen. ``` js event AccountFrozen(address indexed reported) ``` ## Rationale * A recoverable token standard can provide configurable safety for users or contracts who desire this safety. * Implementations of this standard will give users the ability to select a dispute resolution process on an opt-in basis and benefit the community by decreasing the necessity of consideration of token recovery actions. ## Implementation Pending. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Standard Bounties

Mon, 14 May 2018 00:00:00 +0000

## Simple Summary A standard contract and interface for issuing bounties on Ethereum, usable for any type of task, paying in any ERC20 token or in ETH. ## Abstract In order to encourage cross-platform interoperability of bounties on Ethereum, and for easier reputational tracking, StandardBounties can facilitate the administration of funds in exchange for deliverables corresponding to a completed task, in a publicly auditable and immutable fashion. ## Motivation In the absence of a standard for bounties on Ethereum, it would be difficult for platforms to collaborate and share the bounties which users create (thereby recreating the walled gardens which currently exist on Web2.0 task outsourcing platforms). A standardization of these interactions across task types also makes it far easier to track various reputational metrics (such as how frequently you pay for completed submissions, or how frequently your work gets accepted). ## Specification After studying bounties as they've existed for thousands of years (and after implementing and processing over 300 of them on main-net in beta), we've discovered that there are 3 core steps to every bounty: - a bounty is **issued**: an `issuer` specifies the requirements for the task, describing the desired outcome, and how much they would be willing to pay for the completion of that task (denoted in one or several tokens). - a bounty is **fulfilled**: a bounty `fulfiller` may see the bounty, complete the task, and produce a deliverable which is itself the desired outcome of the task, or simply a record that it was completed. Hashes of these deliverables should be stored immutably on-chain, to serve as proof after the fact. - a fulfillment is **accepted**: a bounty `issuer` or `arbiter` may select one or more submissions to be accepted, thereby releasing payment to the bounty fulfiller(s), and transferring ownership over the given deliverable to the `issuer`. To implement these steps, a number of functions are needed: - `initializeBounty(address _issuer, address _arbiter, string _data, uint _deadline)`: This is used when deploying a new StandardBounty contract, and is particularly useful when applying the proxy design pattern, whereby bounties cannot be initialized in their constructors. Here, the data string should represent an IPFS hash, corresponding to a JSON object which conforms to the schema (described below). - `fulfillBounty(address[] _fulfillers, uint[] _numerators, uint _denomenator, string _data)`: This is called to submit a fulfillment, submitting a string representing an IPFS hash which contains the deliverable for the bounty. Initially fulfillments could only be submitted by one individual at a time, however users consistently told us they desired to be able to collaborate on fulfillments, thereby allowing the credit for submissions to be shared by several parties. The lines along which eventual payouts are split are determined by the fractions of the submission credited to each fulfiller (using the array of numerators and single denominator). Here, a bounty platform may also include themselves as a collaborator to collect a small fee for matching the bounty with fulfillers. - `acceptFulfillment(uint _fulfillmentId, StandardToken[] _payoutTokens, uint[] _tokenAmounts)`: This is called by the `issuer` or the `arbiter` to pay out a given fulfillment, using an array of tokens, and an array of amounts of each token to be split among the contributors. This allows for the bounty payout amount to move as it needs to be based on incoming contributions (which may be transferred directly to the contract address). It also allows for the easy splitting of a given bounty's balance among several fulfillments, if the need should arise. - `drainBounty(StandardToken[] _payoutTokens)`: This may be called by the `issuer` to drain a bounty of it's funds, if the need should arise. - `changeBounty(address _issuer, address _arbiter, string _data, uint _deadline)`: This may be called by the `issuer` to change the `issuer`, `arbiter`, `data`, and `deadline` fields of their bounty. - `changeIssuer(address _issuer)`: This may be called by the `issuer` to change to a new `issuer` if need be - `changeArbiter(address _arbiter)`: This may be called by the `issuer` to change to a new `arbiter` if need be - `changeData(string _data)`: This may be called by the `issuer` to change just the `data` - `changeDeadline(uint _deadline)`: This may be called by the `issuer` to change just the `deadline` Optional Functions: - `acceptAndFulfill(address[] _fulfillers, uint[] _numerators, uint _denomenator, string _data, StandardToken[] _payoutTokens, uint[] _tokenAmounts)`: During the course of the development of this standard, we discovered the desire for fulfillers to avoid paying gas fees on their own, entrusting the bounty's `issuer` to make the submission for them, and at the same time accept it. This is useful since it still immutably stores the exchange of tokens for completed work, but avoids the need for new bounty fulfillers to have any ETH to pay for gas costs in advance of their earnings. - `changeMasterCopy(StandardBounty _masterCopy)`: For `issuer`s to be able to change the masterCopy which their proxy contract relies on, if the proxy design pattern is being employed. - `refundableContribute(uint[] _amounts, StandardToken[] _tokens)`: While non-refundable contributions may be sent to a bounty simply by transferring those tokens to the address where it resides, one may also desire to contribute to a bounty with the option to refund their contribution, should the bounty never receive a correct submission which is paid out. `refundContribution(uint _contributionId)`: If a bounty hasn't yet paid out to any correct submissions and is past it's deadline, those individuals who employed the `refundableContribute` function may retrieve their funds from the contract. **Schemas** Persona Schema: ``` { name: // optional - A string representing the name of the persona email: // optional - A string representing the preferred contact email of the persona githubUsername: // optional - A string representing the github username of the persona address: // required - A string web3 address of the persona } ``` Bounty issuance `data` Schema: ``` { payload: { title: // A string representing the title of the bounty description: // A string representing the description of the bounty, including all requirements issuer: { // persona for the issuer of the bounty }, funders:[ // array of personas of those who funded the issue. ], categories: // an array of strings, representing the categories of tasks which are being requested tags: // an array of tags, representing various attributes of the bounty created: // the timestamp in seconds when the bounty was created tokenSymbol: // the symbol for the token which the bounty pays out tokenAddress: // the address for the token which the bounty pays out (0x0 if ETH) // ------- add optional fields here ------- sourceFileName: // A string representing the name of the file sourceFileHash: // The IPFS hash of the file associated with the bounty sourceDirectoryHash: // The IPFS hash of the directory which can be used to access the file webReferenceURL: // The link to a relevant web reference (ie github issue) }, meta: { platform: // a string representing the original posting platform (ie 'gitcoin') schemaVersion: // a string representing the version number (ie '0.1') schemaName: // a string representing the name of the schema (ie 'standardSchema' or 'gitcoinSchema') } } ``` Bounty `fulfillment` data Schema: ``` { payload: { description: // A string representing the description of the fulfillment, and any necessary links to works sourceFileName: // A string representing the name of the file being submitted sourceFileHash: // A string representing the IPFS hash of the file being submitted sourceDirectoryHash: // A string representing the IPFS hash of the directory which holds the file being submitted fulfillers: { // personas for the individuals whose work is being submitted } // ------- add optional fields here ------- }, meta: { platform: // a string representing the original posting platform (ie 'gitcoin') schemaVersion: // a string representing the version number (ie '0.1') schemaName: // a string representing the name of the schema (ie 'standardSchema' or 'gitcoinSchema') } } ``` ## Rationale The development of this standard began a year ago, with the goal of encouraging interoperability among bounty implementations on Ethereum. The initial version had significantly more restrictions: a bounty's `data` could not be changed after issuance (it seemed unfair for bounty `issuer`s to change the requirements after work is underway), and the bounty payout could not be changed (all funds needed to be deposited in the bounty contract before it could accept submissions). The initial version was also far less extensible, and only allowed for fixed payments to a given set of fulfillments. This new version makes it possible for funds to be split among several correct submissions, for submissions to be shared among several contributors, and for payouts to not only be in a single token as before, but in as many tokens as the `issuer` of the bounty desires. These design decisions were made after the 8+ months which Gitcoin, the Bounties Network, and Status Open Bounty have been live and meaningfully facilitating bounties for repositories in the Web3.0 ecosystem. ## Test Cases Tests for our implementation can be found here: https://github.com/Bounties-Network/StandardBounties/tree/develop/test ## Implementation A reference implementation can be found here: https://github.com/Bounties-Network/StandardBounties/blob/develop/contracts/StandardBounty.sol **Although this code has been tested, it has not yet been audited or bug-bountied, so we cannot make any assertions about it's correctness, nor can we presently encourage it's use to hold funds on the Ethereum mainnet.** ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Revised Ethereum Smart Contract Packaging Standard

Fri, 01 Jun 2018 00:00:00 +0000

This ERC has been abandoned in favor of the EthPM V3 smart contract packaging standard defined in [ERC-2678](./eip-2678.md) Simple Summary ============== A data format describing a smart contract software package. Abstract ========== This EIP defines a data format for *package manifest* documents, representing a package of one or more smart contracts, optionally including source code and any/all deployed instances across multiple networks. Package manifests are minified JSON objects, to be distributed via content addressable storage networks, such as IPFS. This document presents a natural language description of a formal specification for version **2** of this format. Motivation ========== This standard aims to encourage the Ethereum development ecosystem towards software best practices around code reuse. By defining an open, community-driven package data format standard, this effort seeks to provide support for package management tools development by offering a general-purpose solution that has been designed with observed common practices in mind. As version 2 of this specification, this standard seeks to address a number of areas of improvement found for the previous version (defined in [EIP-190](./eip-190.md)). This version: - Generalizes storage URIs to represent any content addressable URI scheme, not only IPFS. - Renames *release lockfile* to *package manifest*. - Adds support for languages other than Solidity by generalizing the compiler information format. - Redefines link references to be more flexible, to represent arbitrary gaps in bytecode (besides only addresses), in a more straightforward way. - Forces format strictness, requiring that package manifests contain no extraneous whitespace, and sort object keys in alphabetical order, to prevent hash mismatches.

Specification ============= This document defines the specification for an EthPM package manifest. A package manifest provides metadata about a [Package](#term-package), and in most cases should provide sufficient information about the packaged contracts and its dependencies to do bytecode verification of its contracts. > **Note** > > A [hosted > version](https://ethpm.github.io/ethpm-spec) of this > specification is available via GitHub Pages. This EIP and the hosted > HTML document were both autogenerated from the same documentation > source. Guiding Principles ------------------ This specification makes the following assumptions about the document lifecycle. 1. Package manifests are intended to be generated programmatically by package management software as part of the release process. 2. Package manifests will be consumed by package managers during tasks like installing package dependencies or building and deploying new releases. 3. Package manifests will typically **not** be stored alongside the source, but rather by package registries *or* referenced by package registries and stored in something akin to IPFS. Conventions ----------- ### RFC2119 The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119. - ### Prefixed vs Unprefixed A [prefixed](#term-prefixed) hexadecimal value begins with `0x`. [Unprefixed](#term-unprefixed) values have no prefix. Unless otherwise specified, all hexadecimal values **should** be represented with the `0x` prefix.

Prefixed	`0xdeadbeef`
Unprefixed	`deadbeef`

Document Format --------------- The canonical format is a single JSON object. Packages **must** conform to the following serialization rules. - The document **must** be tightly packed, meaning no linebreaks or extra whitespace. - The keys in all objects must be sorted alphabetically. - Duplicate keys in the same object are invalid. - The document **must** use [UTF-8](https://en.wikipedia.org/wiki/UTF-8) encoding. - The document **must** not have a trailing newline. Document Specification ---------------------- The following fields are defined for the package. Custom fields **may** be included. Custom fields **should** be prefixed with `x-` to prevent name collisions with future versions of the specification.

See Also	Formalized (JSON-Schema) version of this specification: package.spec.json
Jump To	Definitions

### EthPM Manifest Version: `manifest_version` The `manifest_version` field defines the specification version that this document conforms to. Packages **must** include this field.

Required	Yes
Key	`manifest_version`
Type	String
Allowed Values	`2`

### Package Name: `package_name` The `package_name` field defines a human readable name for this package. Packages **must** include this field. Package names **must** begin with a lowercase letter and be comprised of only lowercase letters, numeric characters, and the dash character `-`. Package names **must** not exceed 214 characters in length.

Required	Yes
Key	`package_name`
Type	String
Format	must match the regular expression `^[a-zA-Z][a-zA-Z0-9_]{0,255}$`

### Package Meta: `meta` The `meta` field defines a location for metadata about the package which is not integral in nature for package installation, but may be important or convenient to have on-hand for other reasons. This field **should** be included in all Packages.

Required	No
Key	`meta`
Type	Package Meta Object

### Version: `version` The `version` field declares the version number of this release. This value **must** be included in all Packages. This value **should** conform to the [semver](https://semver.org/) version numbering specification.

Required	Yes
Key	`version`
Type	String

### Sources: `sources` The `sources` field defines a source tree that **should** comprise the full source tree necessary to recompile the contracts contained in this release. Sources are declared in a key/value mapping.

Key	`sources`
Type	Object (String: String)
Format	See Below.

#### Format Keys **must** be relative filesystem paths beginning with a `./`. Paths **must** resolve to a path that is within the current working directory. Values **must** conform to *one of* the following formats. - Source string. - [Content Addressable URI](#term-content-addressable-uri). When the value is a source string the key should be interpreted as a file path. - If the resulting document is a directory the key should be interpreted as a directory path. - If the resulting document is a file the key should be interpreted as a file path. ### Contract Types: `contract_types` The `contract_types` field holds the [Contract Types](#term-contract-type) which have been included in this release. [Packages](#term-package) **should** only include contract types that can be found in the source files for this package. Packages **should not** include contract types from dependencies. Packages **should not** include abstract contracts in the contract types section of a release.

Key

contract_types

Type

Object (String: Contract Type Object)

Format

Keys must be valid Contract Aliases.

Values must conform to the Contract Type Object definition.

### Deployments: `deployments` The `deployments` field holds the information for the chains on which this release has [Contract Instances](#term-contract-instance) as well as the [Contract Types](#term-contract-type) and other deployment details for those deployed contract instances. The set of chains defined by the `*BIP122 URI <#bip122-uris>*` keys for this object **must** be unique.

Key	`deployments`
Type	Object (String: Object(String: Contract Instance Object))
Format	See Below.

#### Format Keys **must** be a valid BIP122 URI chain definition. Values **must** be objects which conform to the following format. - Keys **must** be valid [Contract Instance Names](#term-contract-instance-name). - Values **must** be a valid [Contract Instance Object](#contract-instance-object). ### Build Dependencies: `build_dependencies` The `build_dependencies` field defines a key/value mapping of Ethereum [Packages](#term-package) that this project depends on.

Required	No
Key	`build_dependencies`
Type	Object (String: String)
Format	Keys must be valid package names matching the regular expression `[a-z][-a-z0-9]{0,213}`. Values must be valid IPFS URIs which resolve to a valid package.

Definitions ----------- Definitions for different objects used within the Package. All objects allow custom fields to be included. Custom fields **should** be prefixed with `x-` to prevent name collisions with future versions of the specification.

### The *Link Reference* Object A [Link Reference](#term-link-reference) object has the following key/value pairs. All link references are assumed to be associated with some corresponding [Bytecode](#term-bytecode). #### Offsets: `offsets` The `offsets` field is an array of integers, corresponding to each of the start positions where the link reference appears in the bytecode. Locations are 0-indexed from the beginning of the bytes representation of the corresponding bytecode. This field is invalid if it references a position that is beyond the end of the bytecode.

Required	Yes
Type	Array

#### Length: `length` The `length` field is an integer which defines the length in bytes of the link reference. This field is invalid if the end of the defined link reference exceeds the end of the bytecode.

Required	Yes
Type	Integer

#### Name: `name` The `name` field is a string which **must** be a valid [Identifier](#term-identifier). Any link references which **should** be linked with the same link value **should** be given the same name.

Required	No
Type	String
Format	must conform to the Identifier format.

### The *Link Value* Object Describes a single [Link Value](#term-link-value). A **Link Value object** is defined to have the following key/value pairs.

#### Offsets: `offsets` The `offsets` field defines the locations within the corresponding bytecode where the `value` for this link value was written. These locations are 0-indexed from the beginning of the bytes representation of the corresponding bytecode.

Required	Yes
Type	Integer
Format	See Below.

**Format** Array of integers, where each integer **must** conform to all of the following. - greater than or equal to zero - strictly less than the length of the unprefixed hexadecimal representation of the corresponding bytecode. #### Type: `type` The `type` field defines the `value` type for determining what is encoded when [linking](#term-linking) the corresponding bytecode.

Required

Yes

Type

String

Allowed Values

"literal" for bytecode literals

"reference" for named references to a particular Contract Instance

#### Value: `value` The `value` field defines the value which should be written when [linking](#term-linking) the corresponding bytecode.

Required	Yes
Type	String
Format	Determined based on `type`, see below.

**Format** For static value *literals* (e.g. address), value **must** be a *byte string* To reference the address of a [Contract Instance](#term-contract-instance) from the current package the value should be the name of that contract instance. - This value **must** be a valid contract instance name. - The chain definition under which the contract instance that this link value belongs to must contain this value within its keys. - This value **may not** reference the same contract instance that this link value belongs to. To reference a contract instance from a [Package](#term-package) from somewhere within the dependency tree the value is constructed as follows. - Let `[p1, p2, .. pn]` define a path down the dependency tree. - Each of `p1, p2, pn` **must** be valid package names. - `p1` **must** be present in keys of the `build_dependencies` for the current package. - For every `pn` where `n > 1`, `pn` **must** be present in the keys of the `build_dependencies` of the package for `pn-1`. - The value is represented by the string `::<...>::` where all of ``, ``, `` are valid package names and `` is a valid [Contract Name](#term-contract-name). - The `` value **must** be a valid [Contract Instance Name](#term-contract-instance-name). - Within the package of the dependency defined by ``, all of the following must be satisfiable: - There **must** be *exactly* one chain defined under the `deployments` key which matches the chain definition that this link value is nested under. - The `` value **must** be present in the keys of the matching chain. ### The *Bytecode* Object A bytecode object has the following key/value pairs. #### Bytecode: `bytecode` The `bytecode` field is a string containing the `0x` prefixed hexadecimal representation of the bytecode.

Required	Yes
Type	String
Format	`0x` prefixed hexadecimal.

#### Link References: `link_references` The `link_references` field defines the locations in the corresponding bytecode which require [linking](#term-linking).

Required	No
Type	Array
Format	All values must be valid Link Reference objects. See also below.

**Format** This field is considered invalid if *any* of the [Link References](#term-link-reference) are invalid when applied to the corresponding `bytecode` field, *or* if any of the link references intersect. Intersection is defined as two link references which overlap. #### Link Dependencies: `link_dependencies` The `link_dependencies` defines the [Link Values](#term-link-value) that have been used to link the corresponding bytecode.

Required	No
Type	Array
Format	All values must be valid Link Value objects. See also below.

**Format** Validation of this field includes the following: - Two link value objects **must not** contain any of the same values for `offsets`. - Each [link value object](#link-value-object) **must** have a corresponding [link reference object](#link-reference-object) under the `link_references` field. - The length of the resolved `value` **must** be equal to the `length` of the corresponding [Link Reference](#term-link-reference).

### The *Package Meta* Object The *Package Meta* object is defined to have the following key/value pairs. #### Authors: `authors` The `authors` field defines a list of human readable names for the authors of this package. Packages **may** include this field.

Required	No
Key	`authors`
Type	Array (String)

#### License: `license` The `license` field declares the license under which this package is released. This value **should** conform to the [SPDX](https://en.wikipedia.org/wiki/Software_Package_Data_Exchange) format. Packages **should** include this field.

Required	No
Key	`license`
Type	String

#### Description: `description` The `description` field provides additional detail that may be relevant for the package. Packages **may** include this field.

Required	No
Key	`description`
Type	String

#### Keywords: `keywords` The `keywords` field provides relevant keywords related to this package.

Required	No
Key	`keywords`
Type	List of Strings

#### Links: `links` The `links` field provides URIs to relevant resources associated with this package. When possible, authors **should** use the following keys for the following common resources. - `website`: Primary website for the package. - `documentation`: Package Documentation - `repository`: Location of the project source code.

Key	`links`
Type	Object (String: String)

### The *Contract Type* Object A *Contract Type* object is defined to have the following key/value pairs. #### Contract Name: `contract_name` The `contract_name` field defines the [Contract Name](#term-contract-name) for this [Contract Type](#term-contract-type).

Required	If the Contract Name and Contract Alias are not the same.
Type	String
Format	must be a valid Contract Name.

#### Deployment Bytecode: `deployment_bytecode` The `deployment_bytecode` field defines the bytecode for this [Contract Type](#term-contract-type).

Required	No
Type	Object
Format	must conform to the Bytecode Object format.

#### Runtime Bytecode: `runtime_bytecode` The `runtime_bytecode` field defines the unlinked `0x`-prefixed runtime portion of [Bytecode](#term-bytecode) for this [Contract Type](#term-contract-type).

Required	No
Type	Object
Format	must conform to the Bytecode Object format.

#### ABI: `abi`

Required	No
Type	List
Format	must conform to the Ethereum Contract ABI JSON format.

#### Natspec: `natspec`

Required	No
Type	Object
Format	The union of the UserDoc and DevDoc formats.

#### Compiler: `compiler`

Required	No
Type	Object
Format	must conform to the Compiler Information object format.

### The *Contract Instance* Object A **Contract Instance Object** represents a single deployed [Contract Instance](#term-contract-instance) and is defined to have the following key/value pairs. #### Contract Type: `contract_type` The `contract_type` field defines the [Contract Type](#term-contract-type) for this [Contract Instance](#term-contract-instance). This can reference any of the contract types included in this [Package](#term-package) *or* any of the contract types found in any of the package dependencies from the `build_dependencies` section of the [Package Manifest](#term-package-manifest).

Required	Yes
Type	String
Format	See Below.

**Format** Values for this field **must** conform to *one of* the two formats herein. To reference a contract type from this Package, use the format ``. - The `` value **must** be a valid [Contract Alias](#term-contract-alias). - The value **must** be present in the keys of the `contract_types` section of this Package. To reference a contract type from a dependency, use the format `:`. - The `` value **must** be present in the keys of the `build_dependencies` of this Package. - The `` value **must** be a valid [Contract Alias](#term-contract-alias). - The resolved package for `` must contain the `` value in the keys of the `contract_types` section. #### Address: `address` The `address` field defines the [Address](#term-address) of the [Contract Instance](#term-contract-instance).

Required	Yes
Type	String
Format	Hex encoded `0x` prefixed Ethereum address matching the regular expression `0x[0-9a-fA-F]{40}`.

#### Transaction: `transaction` The `transaction` field defines the transaction hash in which this [Contract Instance](#term-contract-instance) was created.

Required	No
Type	String
Format	`0x` prefixed hex encoded transaction hash.

#### Block: `block` The `block` field defines the block hash in which this the transaction which created this *contract instance* was mined.

Required	No
Type	String
Format	`0x` prefixed hex encoded block hash.

#### Runtime Bytecode: `runtime_bytecode` The `runtime_bytecode` field defines the runtime portion of bytecode for this [Contract Instance](#term-contract-instance). When present, the value from this field supersedes the `runtime_bytecode` from the [Contract Type](#term-contract-type) for this [Contract Instance](#term-contract-instance).

Required	No
Type	Object
Format	must conform to the Bytecode Object format.

Every entry in the `link_references` for this bytecode **must** have a corresponding entry in the `link_dependencies` section. #### Compiler: `compiler` The `compiler` field defines the compiler information that was used during compilation of this [Contract Instance](#term-contract-instance). This field **should** be present in all [Contract Types](#term-contract-type) which include `bytecode` or `runtime_bytecode`.

Required	No
Type	Object
Format	must conform to the Compiler Information Object format.

### The *Compiler Information* Object The `compiler` field defines the compiler information that was used during compilation of this [Contract Instance](#term-contract-instance). This field **should** be present in all contract instances that locally declare `runtime_bytecode`. A *Compiler Information* object is defined to have the following key/value pairs. #### Name `name` The `name` field defines which compiler was used in compilation.

Required	Yes
Key	`name`
Type	String

#### Version: `version` The `version` field defines the version of the compiler. The field **should** be OS agnostic (OS not included in the string) and take the form of either the stable version in [semver](https://semver.org/) format or if built on a nightly should be denoted in the form of `-` ex: `0.4.8-commit.60cc1668`.

Required	Yes
Key	`version`
Type	String

#### Settings: `settings` The `settings` field defines any settings or configuration that was used in compilation. For the `"solc"` compiler, this **should** conform to the [Compiler Input and Output Description](https://solidity.readthedocs.io/en/latest/using-the-compiler.html#compiler-input-and-output-json-description).

Required	No
Key	`settings`
Type	Object

### BIP122 URIs BIP122 URIs are used to define a blockchain via a subset of the [BIP-122](https://github.com/bitcoin/bips/blob/master/bip-0122.mediawiki) spec. blockchain:///block/ The `` represents the blockhash of the first block on the chain, and `` represents the hash of the latest block that’s been reliably confirmed (package managers should be free to choose their desired level of confirmations). Rationale ========= The following use cases were considered during the creation of this specification.

owned	A package which contains contracts which are not meant to be used by themselves but rather as base contracts to provide functionality to other contracts through inheritance.
transferable	A package which has a single dependency.
standard-token	A package which contains a reusable contract.
safe-math-lib	A package which contains deployed instance of one of the package contracts.
piper-coin	A package which contains a deployed instance of a reusable contract from a dependency.
escrow	A package which contains a deployed instance of a local contract which is linked against a deployed instance of a local library.
wallet	A package with a deployed instance of a local contract which is linked against a deployed instance of a library from a dependency.
wallet-with-send	A package with a deployed instance which links against a deep dependency.

Each use case builds incrementally on the previous one. A full listing of [Use Cases](https://ethpm.github.io/ethpm-spec/use-cases.html) can be found on the hosted version of this specification. Glossary ==========

ABI --- The JSON representation of the application binary interface. See the official [specification](https://solidity.readthedocs.io/en/develop/abi-spec.html) for more information.

Address ------- A public identifier for an account on a particular chain

Bytecode -------- The set of EVM instructions as produced by a compiler. Unless otherwise specified this should be assumed to be hexadecimal encoded, representing a whole number of bytes, and [prefixed](#term-prefixed) with `0x`. Bytecode can either be linked or unlinked. (see [Linking](#term-linking))

Unlinked Bytecode

The hexadecimal representation of a contract’s EVM instructions that contains sections of code that requires linking for the contract to be functional.

The sections of code which are unlinked must be filled in with zero bytes.

Example: 0x606060405260e06000730000000000000000000000000000000000000000634d536f

Linked Bytecode

The hexadecimal representation of a contract’s EVM instructions which has had all Link References replaced with the desired Link Values.

Example: 0x606060405260e06000736fe36000604051602001526040518160e060020a634d536f

Chain Definition ---------------- This definition originates from [BIP122 URI](https://github.com/bitcoin/bips/blob/master/bip-0122.mediawiki). A URI in the format `blockchain:///block/` - `chain_id` is the unprefixed hexadecimal representation of the genesis hash for the chain. - `block_hash` is the unprefixed hexadecimal representation of the hash of a block on the chain. A chain is considered to match a chain definition if the genesis block hash matches the `chain_id` and the block defined by `block_hash` can be found on that chain. It is possible for multiple chains to match a single URI, in which case all chains are considered valid matches

Content Addressable URI ----------------------- Any URI which contains a cryptographic hash which can be used to verify the integrity of the content found at the URI. The URI format is defined in RFC3986 It is **recommended** that tools support IPFS and Swarm.

Contract Alias -------------- This is a name used to reference a specific [Contract Type](#term-contract-type). Contract aliases **must** be unique within a single [Package](#term-package). The contract alias **must** use *one of* the following naming schemes: - `` - `[]` The `` portion **must** be the same as the [Contract Name](#term-contract-name) for this contract type. The `[]` portion **must** match the regular expression `\[[-a-zA-Z0-9]{1,256}]`.

Contract Instance ----------------- A contract instance a specific deployed version of a [Contract Type](#term-contract-type). All contract instances have an [Address](#term-address) on some specific chain.

Contract Instance Name ---------------------- A name which refers to a specific [Contract Instance](#term-contract-instance) on a specific chain from the deployments of a single [Package](#term-package). This name **must** be unique across all other contract instances for the given chain. The name must conform to the regular expression `[a-zA-Z][a-zA-Z0-9_]{0,255}` In cases where there is a single deployed instance of a given [Contract Type](#term-contract-type), package managers **should** use the [Contract Alias](#term-contract-alias) for that contract type for this name. In cases where there are multiple deployed instances of a given contract type, package managers **should** use a name which provides some added semantic information as to help differentiate the two deployed instances in a meaningful way.

Contract Name ------------- The name found in the source code that defines a specific [Contract Type](#term-contract-type). These names **must** conform to the regular expression `[a-zA-Z][-a-zA-Z0-9_]{0,255}`. There can be multiple contracts with the same contract name in a projects source files.

Contract Type ------------- Refers to a specific contract in the package source. This term can be used to refer to an abstract contract, a normal contract, or a library. Two contracts are of the same contract type if they have the same bytecode. Example: contract Wallet { ... } A deployed instance of the `Wallet` contract would be of type `Wallet`.

Identifier ---------- Refers generally to a named entity in the [Package](#term-package). A string matching the regular expression `[a-zA-Z][-_a-zA-Z0-9]{0,255}`

Link Reference -------------- A location within a contract’s bytecode which needs to be linked. A link reference has the following properties.

`offset`	Defines the location within the bytecode where the link reference begins.
`length`	Defines the length of the reference.
`name`	(optional.) A string to identify the reference

Link Value ---------- A link value is the value which can be inserted in place of a [Link Reference](#term-link-reference)

Linking ------- The act of replacing [Link References](#term-link-reference) with [Link Values](#term-link-value) within some [Bytecode](#term-bytecode).

Package ------- Distribution of an application’s source or compiled bytecode along with metadata related to authorship, license, versioning, et al. For brevity, the term **Package** is often used metonymously to mean [Package Manifest](#term-package-manifest).

Package Manifest ---------------- A machine-readable description of a package (See [Specification](#package-specification) for information about the format for package manifests.)

Prefixed -------- [Bytecode](#term-bytecode) string with leading `0x`.

Example

0xdeadbeef

Unprefixed ---------- Not [Prefixed](#term-prefixed).

Example

deadbeef

Backwards Compatibility ======================= This specification supports backwards compatibility by use of the [manifest\_version](#manifest-version) property. This specification corresponds to version `2` as the value for that field. Implementations =============== This submission aims to coincide with development efforts towards widespread implementation in commonly-used development tools. The following tools are known to have begun or are nearing completion of a supporting implementation. - [Truffle](https://trufflesuite.com/) - [Populus](https://populus.readthedocs.io/en/latest/) - [Embark](https://embark.status.im/) Full support in implementation **may** require [Further Work](#further-work), specified below. Further Work ============ This EIP addresses only the data format for package descriptions. Excluded from the scope of this specification are: - Package registry interface definition - Tooling integration, or how packages are stored on disk. These efforts **should** be considered separate, warranting future dependent EIP submssions. Acknowledgements ================ The authors of this document would like to thank the original authors of [EIP-190](./eip-190.md), [ETHPrize](http://ethprize.io/) for their funding support, all community [contributors](https://github.com/ethpm/ethpm-spec/graphs/contributors), and the Ethereum community at large. Copyright ========= Copyright and related rights waived via [CC0](/LICENSE).

Standardised DAPP announcements

Thu, 31 May 2018 00:00:00 +0000

## Simple Summary Standardisation of announcements in DAPPs and services on Ethereum network. This ERC provides proposed mechanics to increase the quality of service provided by DAPP developers and service providers, by setting a framework for announcements. Be it transitioning to a new smart contract or just freezing the service for some reason. ## Abstract The proposed ERC defines format on how to post announcements about the service as well as how to remove them. It also defines mechanics on posting permissions and human friendly interface. ## Motivation Currently there are no guidelines on how to notify the users of the service status in the DAPPs. This is especially obvious in ERC20 and it's derivates. If the service is impeded by any reason it is good practice to have some sort of guidelines on how to announce that to the user. The standardisation would also provide traceability of the service's status. ## Specification ### Structures #### Announcer Stores information about the announcement maker. The `allowedToPost` stores posting permissions and is used for modifiers limiting announcement posting only to authorised entities. The `name` is used for human friendly identifier of the author to be stored. ``` js struct Announcer{ bool allowedToPost; string name; } ``` #### Announcement Stores information about the individual announcement. The human friendly author identifier is stored in `author`. Ethereum address associated with the author is stored in `authorAddress`. The announcement itself is stored in `post`. ``` js struct Announcement{ string author; address authorAddress; string post; } ``` ### Methods #### the number of announcements Returns the number of announcements currently active. OPTIONAL - this method can be used to provide quicker information for the UI, but could also be retrieved from `numberOfMessages` variable. ``` js function theNumberOfAnnouncements() public constant returns(uint256 _numberOfAnnouncements) ``` #### read posts Returns the specified announcement as well as human friendly poster identificator (name or nickname). ``` js function readPosts(uint256 _postNumber) public constant returns(string _author, string _post) ``` #### give posting permission Sets posting permissions of the address `_newAnnouncer` to `_postingPrivileges` and can also be used to revoke those permissions. The `_posterName` is human friendly author identificator used in the announcement data. ``` js function givePostingPermission(address _newAnnouncer, bool _postingPrivileges, string _posterName) public onlyOwner returns(bool success) ``` #### can post Checks if the entity that wants to post an announcement has the posting privilieges. ``` js modifier canPost{ require(posterData[msg.sender].allowedToPost); _; } ``` #### post announcement Lets user post announcements, but only if they have their posting privileges set to `true`. The announcement is sent in `_message` variable. ``` js function postAnnouncement(string _message) public canPost ``` #### remove announcement Removes an announcement with `_messageNumber` announcement identifier and rearranges the mapping so there are no empty slots. The `_removalReason` is used to update users if the issue that caused the announcement is resolved or what are the next steps from the service provider / DAPP development team. ``` js function removeAnnouncement(uint256 _messageNumber, string _removalReason) public ``` ### Events #### New announcement MUST trigger when new announcement is created. Every time there is a new announcement it should be advertised in this event. It holds the information about author `author` and the announcement istelf `message`. ``` js event NewAnnouncement(string author, string message) ``` #### Removed announcement MUST trigger when an announcement is removed. Every time an announcement is removed it should be advertised in this event. It holds the information about author `author`, the announcement itself `message`, the reason for removal or explanation of the solution `reason` and the address of the entity that removed the announcement `remover`. ``` js event RemovedAnnouncement(string author, string message, string reason, address remover); ``` ## Rationale The proposed solution was designed with UX in mind . It provides mechanics that serve to present the announcements in the user friendly way. It is meant to be deployed as a Solidity smart contract on Ethereum network. ## Test Cases The proposed version is deployed on Ropsten testnet all of the information can be found [here](https://ropsten.etherscan.io/address/0xb04f67172b9733837e59ebaf03d277279635c8e6#readContract). ## Implementation ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Extending ERC20 with token locking capability

Sun, 03 Jun 2018 00:00:00 +0000

## Simple Summary An extension to the ERC20 standard with methods for time-locking of tokens within a contract. ## Abstract This proposal provides basic functionality to time-lock tokens within an ERC20 smart contract for multiple utilities without the need of transferring tokens to an external escrow smart contract. It also allows fetching balance of locked and transferable tokens. Time-locking can also be achieved via staking (#900), but that requires transfer of tokens to an escrow contract / stake manager, resulting in the following six concerns: 1. additional trust on escrow contract / stake manager 2. additional approval process for token transfer 3. increased ops costs due to gas requirements in transfers 4. tough user experience as the user needs to claim the amount back from external escrows 5. inability for the user to track their true token balance / token activity 6. inability for the user to utilize their locked tokens within the token ecosystem. ## Motivation dApps often require tokens to be time-locked against transfers for letting members 1) adhere to vesting schedules and 2) show skin in the game to comply with the underlying business process. I realized this need while building Nexus Mutual and GovBlocks. In [Nexus Mutual](https://nexusmutual.io), claim assessors are required to lock their tokens before passing a vote for claims assessment. This is important as it ensures assessors’ skin in the game. The need here was that once a claim assessor locks his tokens for ‘n’ days, he should be able to cast multiple votes during that period of ‘n’ days, which is not feasible with staking mechanism. There are other scenarios like skills/identity verification or participation in gamified token curated registries where time-locked tokens are required as well. In [GovBlocks](https://govblocks.io), I wanted to allow dApps to lock member tokens for governance, while still allowing members to use those locked tokens for other activities within the dApp business. This is also the case with DGX governance model where they’ve proposed quarterly token locking for participation in governance activities of DGX. In addition to locking functionality, I have proposed a `Lock()` and `Unlock()` event, just like the `Transfer()` event , to track token lock and unlock status. From token holder’s perspective, it gets tough to manage token holdings if certain tokens are transferred to another account for locking, because whenever `balanceOf()` queries are triggered on token holder’s account – the result does not include locked tokens. A `totalBalanceOf()` function intends to solve this problem. The intention with this proposal is to enhance the ERC20 standard with token-locking capability so that dApps can time-lock tokens of the members without having to transfer tokens to an escrow / stake manager and at the same time allow members to use the locked tokens for multiple utilities. ## Specification I’ve extended the ERC20 interface with the following enhancements: ### Locking of tokens ```solidity /** * @dev Locks a specified amount of tokens against an address, * for a specified reason and time * @param _reason The reason to lock tokens * @param _amount Number of tokens to be locked * @param _time Lock time in seconds */ function lock(bytes32 _reason, uint256 _amount, uint256 _time) public returns (bool) ``` ### Fetching number of tokens locked under each utility ```solidity /** * @dev Returns tokens locked for a specified address for a * specified reason * * @param _of The address whose tokens are locked * @param _reason The reason to query the lock tokens for */ tokensLocked(address _of, bytes32 _reason) view returns (uint256 amount) ``` ### Fetching number of tokens locked under each utility at a future timestamp ```solidity /** * @dev Returns tokens locked for a specified address for a * specified reason at a specific time * * @param _of The address whose tokens are locked * @param _reason The reason to query the lock tokens for * @param _time The timestamp to query the lock tokens for */ function tokensLockedAtTime(address _of, bytes32 _reason, uint256 _time) public view returns (uint256 amount) ``` ### Fetching number of tokens held by an address ```solidity /** * @dev @dev Returns total tokens held by an address (locked + transferable) * @param _of The address to query the total balance of */ function totalBalanceOf(address _of) view returns (uint256 amount) ``` ### Extending lock period ```solidity /** * @dev Extends lock for a specified reason and time * @param _reason The reason to lock tokens * @param _time Lock extension time in seconds */ function extendLock(bytes32 _reason, uint256 _time) public returns (bool) ``` ### Increasing number of tokens locked ```solidity /** * @dev Increase number of tokens locked for a specified reason * @param _reason The reason to lock tokens * @param _amount Number of tokens to be increased */ function increaseLockAmount(bytes32 _reason, uint256 _amount) public returns (bool) ``` ### Fetching number of unlockable tokens under each utility ```solidity /** * @dev Returns unlockable tokens for a specified address for a specified reason * @param _of The address to query the unlockable token count of * @param _reason The reason to query the unlockable tokens for */ function tokensUnlockable(address _of, bytes32 _reason) public view returns (uint256 amount) ``` ### Fetching number of unlockable tokens ```solidity /** * @dev Gets the unlockable tokens of a specified address * @param _of The address to query the unlockable token count of */ function getUnlockableTokens(address _of) public view returns (uint256 unlockableTokens) ``` ### Unlocking tokens ```solidity /** * @dev Unlocks the unlockable tokens of a specified address * @param _of Address of user, claiming back unlockable tokens */ function unlock(address _of) public returns (uint256 unlockableTokens) ``` ### Lock event recorded in the token contract `event Locked(address indexed _of, uint256 indexed _reason, uint256 _amount, uint256 _validity)` ### Unlock event recorded in the token contract `event Unlocked(address indexed _of, uint256 indexed _reason, uint256 _amount)` ## Test Cases Test cases are available at [https://github.com/nitika-goel/lockable-token](https://github.com/nitika-goel/lockable-token). ## Implementation - Complete implementation available at https://github.com/nitika-goel/lockable-token - [GovBlocks](https://govblocks.io) Project specific implementation available at https://github.com/somish/govblocks-protocol/blob/Locking/contracts/GBTStandardToken.sol ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Oracle Interface

Wed, 13 Jun 2018 00:00:00 +0000

## Simple Summary A standard interface for oracles. ## Abstract In order for ethereum smart contracts to interact with off-chain systems, oracles must be used. These oracles report values which are normally off-chain, allowing smart contracts to react to the state of off-chain systems. A distinction and a choice is made between push and pull based oracle systems. Furthermore, a standard interface for oracles is described here, allowing different oracle implementations to be interchangeable. ## Motivation The Ethereum ecosystem currently has many different oracle implementations available, but they do not provide a unified interface. Smart contract systems would be locked into a single set of oracle implementations, or they would require developers to write adapters/ports specific to the oracle system chosen in a given project. Beyond naming differences, there is also the issue of whether or not an oracle report-resolving transaction _pushes_ state changes by calling affected contracts, or changes the oracle state allowing dependent contracts to _pull_ the updated value from the oracle. These differing system semantics could introduce inefficiencies when adapting between them. Ultimately, the value in different oracle systems comes from their underlying resolution mechanics, and points where these systems are virtually identical should be standardized. These oracles may be used for answering questions about "real-world events", where each ID can be correlated with a specification of a question and its answers (so most likely for prediction markets, basically). Another use case could be for decision-making processes, where the results given by the oracle represent decisions made by the oracle (e.g. futarchies). DAOs may require their use in decision making processes. Both the ID and the results are intentionally unstructured so that things like time series data (via splitting the ID) and different sorts of results (like one of a few, any subset of up to 256, or some value in a range with up to 256 bits of granularity) can be represented. ## Specification

Oracle: An entity which reports data to the blockchain.
Oracle consumer: A smart contract which receives data from an oracle.
ID: A way of indexing the data which an oracle reports. May be derived from or tied to a question for which the data provides the answer.
Result: Data associated with an id which is reported by an oracle. This data oftentimes will be the answer to a question tied to the id. Other equivalent terms that have been used include: answer, data, outcome.
Report: A pair (ID, result) which an oracle sends to an oracle consumer.

```solidity interface OracleConsumer { function receiveResult(bytes32 id, bytes result) external; } ``` `receiveResult` MUST revert if the `msg.sender` is not an oracle authorized to provide the `result` for that `id`. `receiveResult` MUST revert if `receiveResult` has been called with the same `id` before. `receiveResult` MAY revert if the `id` or `result` cannot be handled by the consumer. Consumers MUST coordinate with oracles to determine how to encode/decode results to and from `bytes`. For example, `abi.encode` and `abi.decode` may be used to implement a codec for results in Solidity. `receiveResult` SHOULD revert if the consumer receives a unexpected result format from the oracle. The oracle can be any Ethereum account. ## Rationale The specs are currently very similar to what is implemented by ChainLink (which can use any arbitrarily-named callback) and Oraclize (which uses `__callback`). With this spec, the oracle _pushes_ state to the consumer, which must react accordingly to the updated state. An alternate _pull_-based interface can be prescribed, as follows: ### Alternate Pull-based Interface Here are alternate specs loosely based on Gnosis prediction market contracts v1. Reality Check also exposes a similar endpoint (`getFinalAnswer`). ```solidity interface Oracle { function resultFor(bytes32 id) external view returns (bytes result); } ``` `resultFor` MUST revert if the result for an `id` is not available yet. `resultFor` MUST return the same result for an `id` after that result is available. ### Push vs Pull Note that push-based interfaces may be adapted into pull-based interfaces. Simply deploy an oracle consumer which stores the result received and implements `resultFor` accordingly. Similarly, every pull-based system can be adapted into a push-based system: just add a method on the oracle smart contract which takes an oracle consumer address and calls `receiveResult` on that address. In both cases, an additional transaction would have to be performed, so the choice to go with push or pull should be based on the dominant use case for these oracles. In the simple case where a single account has the authority to decide the outcome of an oracle question, there is no need to deploy an oracle contract and store the outcome on that oracle contract. Similarly, in the case where the outcome comes down to a vote, existing multisignature wallets can be used as the authorized oracle. #### Multiple Oracle Consumers In the case that many oracle consumers depend on a single oracle result and all these consumers expect the result to be pushed to them, the push and pull adaptations mentioned before may be combined if the pushing oracle cannot be trusted to send the same result to every consumer (in a sense, this forwards the trust to the oracle adaptor implementation). In a pull-based system, each of the consumers would have to be called to pull the result from the oracle contract, but in the proposed push-based system, the adapted oracle would have to be called to push the results to each of the consumers. Transaction-wise, both systems are roughly equivalent in efficiency in this scenario, but in the push-based system, there's a need for the oracle consumers to store the results again, whereas in the pull-based system, the consumers may continue to refer to the oracle for the results. Although this may be somewhat less efficient, requiring the consumers to store the results can also provide security guarantees, especially with regards to result immutability. #### Result Immutability In both the proposed specification and the alternate specification, results are immutable once they are determined. This is due to the expectation that typical consumers will require results to be immutable in order to determine a resulting state consistently. With the proposed push-based system, the consumer enforces the result immutability requirement, whereas in the alternate pull-based system, either the oracle would have to be trusted to implement the spec correctly and enforce the immutability requirement, or the consumer would also have to handle result immutability. For data which mutates over time, the `id` field may be structured to specify "what" and "when" for the data (using 128 bits to specify "when" is still safe for many millennia). ## Implementation * [Tidbit](https://github.com/levelkdev/tidbit) tracks this EIP. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Multi Token Standard

Sun, 17 Jun 2018 00:00:00 +0000

## Simple Summary A standard interface for contracts that manage multiple token types. A single deployed contract may include any combination of fungible tokens, non-fungible tokens or other configurations (e.g. semi-fungible tokens). ## Abstract This standard outlines a smart contract interface that can represent any number of fungible and non-fungible token types. Existing standards such as ERC-20 require deployment of separate contracts per token type. The ERC-721 standard's token ID is a single non-fungible index and the group of these non-fungibles is deployed as a single contract with settings for the entire collection. In contrast, the ERC-1155 Multi Token Standard allows for each token ID to represent a new configurable token type, which may have its own metadata, supply and other attributes. The `_id` argument contained in each function's argument set indicates a specific token or token type in a transaction. ## Motivation Tokens standards like ERC-20 and ERC-721 require a separate contract to be deployed for each token type or collection. This places a lot of redundant bytecode on the Ethereum blockchain and limits certain functionality by the nature of separating each token contract into its own permissioned address. With the rise of blockchain games and platforms like Enjin Coin, game developers may be creating thousands of token types, and a new type of token standard is needed to support them. However, ERC-1155 is not specific to games and many other applications can benefit from this flexibility. New functionality is possible with this design such as transferring multiple token types at once, saving on transaction costs. Trading (escrow / atomic swaps) of multiple tokens can be built on top of this standard and it removes the need to "approve" individual token contracts separately. It is also easy to describe and mix multiple fungible or non-fungible token types in a single contract. ## Specification The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. **Smart contracts implementing the ERC-1155 standard MUST implement all of the functions in the `ERC1155` interface.** **Smart contracts implementing the ERC-1155 standard MUST implement the ERC-165 `supportsInterface` function and MUST return the constant value `true` if `0xd9b67a26` is passed through the `interfaceID` argument.** ```solidity pragma solidity ^0.5.9; /** @title ERC-1155 Multi Token Standard @dev See https://eips.ethereum.org/EIPS/eip-1155 Note: The ERC-165 identifier for this interface is 0xd9b67a26. */ interface ERC1155 /* is ERC165 */ { /** @dev Either `TransferSingle` or `TransferBatch` MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "Safe Transfer Rules" section of the standard). The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender). The `_from` argument MUST be the address of the holder whose balance is decreased. The `_to` argument MUST be the address of the recipient whose balance is increased. The `_id` argument MUST be the token type being transferred. The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). */ event TransferSingle(address indexed _operator, address indexed _from, address indexed _to, uint256 _id, uint256 _value); /** @dev Either `TransferSingle` or `TransferBatch` MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see "Safe Transfer Rules" section of the standard). The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender). The `_from` argument MUST be the address of the holder whose balance is decreased. The `_to` argument MUST be the address of the recipient whose balance is increased. The `_ids` argument MUST be the list of tokens being transferred. The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in _ids) the holder balance is decreased by and match what the recipient balance is increased by. When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). */ event TransferBatch(address indexed _operator, address indexed _from, address indexed _to, uint256[] _ids, uint256[] _values); /** @dev MUST emit when approval for a second party/operator address to manage all tokens for an owner address is enabled or disabled (absence of an event assumes disabled). */ event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved); /** @dev MUST emit when the URI is updated for a token ID. URIs are defined in RFC 3986. The URI MUST point to a JSON file that conforms to the "ERC-1155 Metadata URI JSON Schema". */ event URI(string _value, uint256 indexed _id); /** @notice Transfers `_value` amount of an `_id` from the `_from` address to the `_to` address specified (with safety call). @dev Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard). MUST revert if `_to` is the zero address. MUST revert if balance of holder for token `_id` is lower than the `_value` sent. MUST revert on any other error. MUST emit the `TransferSingle` event to reflect the balance change (see "Safe Transfer Rules" section of the standard). After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). @param _from Source address @param _to Target address @param _id ID of the token type @param _value Transfer amount @param _data Additional data with no specified format, MUST be sent unaltered in call to `onERC1155Received` on `_to` */ function safeTransferFrom(address _from, address _to, uint256 _id, uint256 _value, bytes calldata _data) external; /** @notice Transfers `_values` amount(s) of `_ids` from the `_from` address to the `_to` address specified (with safety call). @dev Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section of the standard). MUST revert if `_to` is the zero address. MUST revert if length of `_ids` is not the same as length of `_values`. MUST revert if any of the balance(s) of the holder(s) for token(s) in `_ids` is lower than the respective amount(s) in `_values` sent to the recipient. MUST revert on any other error. MUST emit `TransferSingle` or `TransferBatch` event(s) such that all the balance changes are reflected (see "Safe Transfer Rules" section of the standard). Balance changes and events MUST follow the ordering of the arrays (_ids[0]/_values[0] before _ids[1]/_values[1], etc). After the above conditions for the transfer(s) in the batch are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call the relevant `ERC1155TokenReceiver` hook(s) on `_to` and act appropriately (see "Safe Transfer Rules" section of the standard). @param _from Source address @param _to Target address @param _ids IDs of each token type (order and length must match _values array) @param _values Transfer amounts per token type (order and length must match _ids array) @param _data Additional data with no specified format, MUST be sent unaltered in call to the `ERC1155TokenReceiver` hook(s) on `_to` */ function safeBatchTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external; /** @notice Get the balance of an account's tokens. @param _owner The address of the token holder @param _id ID of the token @return The _owner's balance of the token type requested */ function balanceOf(address _owner, uint256 _id) external view returns (uint256); /** @notice Get the balance of multiple account/token pairs @param _owners The addresses of the token holders @param _ids ID of the tokens @return The _owner's balance of the token types requested (i.e. balance for each (owner, id) pair) */ function balanceOfBatch(address[] calldata _owners, uint256[] calldata _ids) external view returns (uint256[] memory); /** @notice Enable or disable approval for a third party ("operator") to manage all of the caller's tokens. @dev MUST emit the ApprovalForAll event on success. @param _operator Address to add to the set of authorized operators @param _approved True if the operator is approved, false to revoke approval */ function setApprovalForAll(address _operator, bool _approved) external; /** @notice Queries the approval status of an operator for a given owner. @param _owner The owner of the tokens @param _operator Address of authorized operator @return True if the operator is approved, false if not */ function isApprovedForAll(address _owner, address _operator) external view returns (bool); } ``` ### ERC-1155 Token Receiver **Smart contracts MUST implement all of the functions in the `ERC1155TokenReceiver` interface to accept transfers. See "Safe Transfer Rules" for further detail.** **Smart contracts MUST implement the ERC-165 `supportsInterface` function and signify support for the `ERC1155TokenReceiver` interface to accept transfers. See "ERC1155TokenReceiver ERC-165 rules" for further detail.** ```solidity pragma solidity ^0.5.9; /** Note: The ERC-165 identifier for this interface is 0x4e2312e0. */ interface ERC1155TokenReceiver { /** @notice Handle the receipt of a single ERC1155 token type. @dev An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeTransferFrom` after the balance has been updated. This function MUST return `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` (i.e. 0xf23a6e61) if it accepts the transfer. This function MUST revert if it rejects the transfer. Return of any other value than the prescribed keccak256 generated value MUST result in the transaction being reverted by the caller. @param _operator The address which initiated the transfer (i.e. msg.sender) @param _from The address which previously owned the token @param _id The ID of the token being transferred @param _value The amount of tokens being transferred @param _data Additional data with no specified format @return `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` */ function onERC1155Received(address _operator, address _from, uint256 _id, uint256 _value, bytes calldata _data) external returns(bytes4); /** @notice Handle the receipt of multiple ERC1155 token types. @dev An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeBatchTransferFrom` after the balances have been updated. This function MUST return `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` (i.e. 0xbc197c81) if it accepts the transfer(s). This function MUST revert if it rejects the transfer(s). Return of any other value than the prescribed keccak256 generated value MUST result in the transaction being reverted by the caller. @param _operator The address which initiated the batch transfer (i.e. msg.sender) @param _from The address which previously owned the token @param _ids An array containing ids of each token being transferred (order and length must match _values array) @param _values An array containing amounts of each token being transferred (order and length must match _ids array) @param _data Additional data with no specified format @return `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` */ function onERC1155BatchReceived(address _operator, address _from, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external returns(bytes4); } ``` ### Safe Transfer Rules To be more explicit about how the standard `safeTransferFrom` and `safeBatchTransferFrom` functions MUST operate with respect to the `ERC1155TokenReceiver` hook functions, a list of scenarios and rules follows. #### Scenarios **_Scenario#1 :_** The recipient is not a contract. * `onERC1155Received` and `onERC1155BatchReceived` MUST NOT be called on an EOA (Externally Owned Account). **_Scenario#2 :_** The transaction is not a mint/transfer of a token. * `onERC1155Received` and `onERC1155BatchReceived` MUST NOT be called outside of a mint or transfer process. **_Scenario#3 :_** The receiver does not implement the necessary `ERC1155TokenReceiver` interface function(s). * The transfer MUST be reverted with the one caveat below. - If the token(s) being sent are part of a hybrid implementation of another standard, that particular standard's rules on sending to a contract MAY now be followed instead. See "Backwards Compatibility" section. **_Scenario#4 :_** The receiver implements the necessary `ERC1155TokenReceiver` interface function(s) but returns an unknown value. * The transfer MUST be reverted. **_Scenario#5 :_** The receiver implements the necessary `ERC1155TokenReceiver` interface function(s) but throws an error. * The transfer MUST be reverted. **_Scenario#6 :_** The receiver implements the `ERC1155TokenReceiver` interface and is the recipient of one and only one balance change (e.g. `safeTransferFrom` called). * The balances for the transfer MUST have been updated before the `ERC1155TokenReceiver` hook is called on a recipient contract. * The transfer event MUST have been emitted to reflect the balance changes before the `ERC1155TokenReceiver` hook is called on the recipient contract. * One of `onERC1155Received` or `onERC1155BatchReceived` MUST be called on the recipient contract. * The `onERC1155Received` hook SHOULD be called on the recipient contract and its rules followed. - See "onERC1155Received rules" for further rules that MUST be followed. * The `onERC1155BatchReceived` hook MAY be called on the recipient contract and its rules followed. - See "onERC1155BatchReceived rules" for further rules that MUST be followed. **_Scenario#7 :_** The receiver implements the `ERC1155TokenReceiver` interface and is the recipient of more than one balance change (e.g. `safeBatchTransferFrom` called). * All balance transfers that are referenced in a call to an `ERC1155TokenReceiver` hook MUST be updated before the `ERC1155TokenReceiver` hook is called on the recipient contract. * All transfer events MUST have been emitted to reflect current balance changes before an `ERC1155TokenReceiver` hook is called on the recipient contract. * `onERC1155Received` or `onERC1155BatchReceived` MUST be called on the recipient as many times as necessary such that every balance change for the recipient in the scenario is accounted for. - The return magic value for every hook call MUST be checked and acted upon as per "onERC1155Received rules" and "onERC1155BatchReceived rules". * The `onERC1155BatchReceived` hook SHOULD be called on the recipient contract and its rules followed. - See "onERC1155BatchReceived rules" for further rules that MUST be followed. * The `onERC1155Received` hook MAY be called on the recipient contract and its rules followed. - See "onERC1155Received rules" for further rules that MUST be followed. **_Scenario#8 :_** You are the creator of a contract that implements the `ERC1155TokenReceiver` interface and you forward the token(s) onto another address in one or both of `onERC1155Received` and `onERC1155BatchReceived`. * Forwarding should be considered acceptance and then initiating a new `safeTransferFrom` or `safeBatchTransferFrom` in a new context. - The prescribed keccak256 acceptance value magic for the receiver hook being called MUST be returned after forwarding is successful. * The `_data` argument MAY be re-purposed for the new context. * If forwarding fails the transaction MAY be reverted. - If the contract logic wishes to keep the ownership of the token(s) itself in this case it MAY do so. **_Scenario#9 :_** You are transferring tokens via a non-standard API call i.e. an implementation specific API and NOT `safeTransferFrom` or `safeBatchTransferFrom`. * In this scenario all balance updates and events output rules are the same as if a standard transfer function had been called. - i.e. an external viewer MUST still be able to query the balance via a standard function and it MUST be identical to the balance as determined by `TransferSingle` and `TransferBatch` events alone. * If the receiver is a contract the `ERC1155TokenReceiver` hooks still need to be called on it and the return values respected the same as if a standard transfer function had been called. - However while the `safeTransferFrom` or `safeBatchTransferFrom` functions MUST revert if a receiving contract does not implement the `ERC1155TokenReceiver` interface, a non-standard function MAY proceed with the transfer. - See "Implementation specific transfer API rules". #### Rules **_safeTransferFrom rules:_** * Caller must be approved to manage the tokens being transferred out of the `_from` account (see "Approval" section). * MUST revert if `_to` is the zero address. * MUST revert if balance of holder for token `_id` is lower than the `_value` sent to the recipient. * MUST revert on any other error. * MUST emit the `TransferSingle` event to reflect the balance change (see "TransferSingle and TransferBatch event rules" section). * After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see "onERC1155Received rules" section). - The `_data` argument provided by the sender for the transfer MUST be passed with its contents unaltered to the `onERC1155Received` hook function via its `_data` argument. **_safeBatchTransferFrom rules:_** * Caller must be approved to manage all the tokens being transferred out of the `_from` account (see "Approval" section). * MUST revert if `_to` is the zero address. * MUST revert if length of `_ids` is not the same as length of `_values`. * MUST revert if any of the balance(s) of the holder(s) for token(s) in `_ids` is lower than the respective amount(s) in `_values` sent to the recipient. * MUST revert on any other error. * MUST emit `TransferSingle` or `TransferBatch` event(s) such that all the balance changes are reflected (see "TransferSingle and TransferBatch event rules" section). * The balance changes and events MUST occur in the array order they were submitted (_ids[0]/_values[0] before _ids[1]/_values[1], etc). * After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size > 0). If so, it MUST call `onERC1155Received` or `onERC1155BatchReceived` on `_to` and act appropriately (see "onERC1155Received and onERC1155BatchReceived rules" section). - The `_data` argument provided by the sender for the transfer MUST be passed with its contents unaltered to the `ERC1155TokenReceiver` hook function(s) via their `_data` argument. **_TransferSingle and TransferBatch event rules:_** * `TransferSingle` SHOULD be used to indicate a single balance transfer has occurred between a `_from` and `_to` pair. - It MAY be emitted multiple times to indicate multiple balance changes in the transaction, but note that `TransferBatch` is designed for this to reduce gas consumption. - The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender). - The `_from` argument MUST be the address of the holder whose balance is decreased. - The `_to` argument MUST be the address of the recipient whose balance is increased. - The `_id` argument MUST be the token type being transferred. - The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). See "Minting/creating and burning/destroying rules". - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). See "Minting/creating and burning/destroying rules". * `TransferBatch` SHOULD be used to indicate multiple balance transfers have occurred between a `_from` and `_to` pair. - It MAY be emitted with a single element in the list to indicate a singular balance change in the transaction, but note that `TransferSingle` is designed for this to reduce gas consumption. - The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender). - The `_from` argument MUST be the address of the holder whose balance is decreased for each entry pair in `_ids` and `_values`. - The `_to` argument MUST be the address of the recipient whose balance is increased for each entry pair in `_ids` and `_values`. - The `_ids` array argument MUST contain the ids of the tokens being transferred. - The `_values` array argument MUST contain the number of token to be transferred for each corresponding entry in `_ids`. - `_ids` and `_values` MUST have the same length. - When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address). See "Minting/creating and burning/destroying rules". - When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). See "Minting/creating and burning/destroying rules". * The total value transferred from address `0x0` minus the total value transferred to `0x0` observed via the `TransferSingle` and `TransferBatch` events MAY be used by clients and exchanges to determine the "circulating supply" for a given token ID. * To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the `TransferSingle` event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. * All `TransferSingle` and `TransferBatch` events MUST be emitted to reflect all the balance changes that have occurred before any call(s) to `onERC1155Received` or `onERC1155BatchReceived`. - To make sure event order is correct in the case of valid re-entry (e.g. if a receiver contract forwards tokens on receipt) state balance and events balance MUST match before calling an external contract. **_onERC1155Received rules:_** - The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender). * The `_from` argument MUST be the address of the holder whose balance is decreased. - `_from` MUST be 0x0 for a mint. * The `_id` argument MUST be the token type being transferred. * The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by. * The `_data` argument MUST contain the information provided by the sender for the transfer with its contents unaltered. - i.e. it MUST pass on the unaltered `_data` argument sent via the `safeTransferFrom` or `safeBatchTransferFrom` call for this transfer. * The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` - If the return value is `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. * The recipient contract MAY reject an increase of its balance by calling revert. - If the recipient contract throws/reverts the transaction MUST be reverted. * If the return value is anything other than `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))` the transaction MUST be reverted. * `onERC1155Received` (and/or `onERC1155BatchReceived`) MAY be called multiple times in a single transaction and the following requirements must be met: - All callbacks represent mutually exclusive balance changes. - The set of all calls to `onERC1155Received` and `onERC1155BatchReceived` describes all balance changes that occurred during the transaction in the order submitted. * A contract MAY skip calling the `onERC1155Received` hook function if the transfer operation is transferring the token to itself. **_onERC1155BatchReceived rules:_** - The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender). * The `_from` argument MUST be the address of the holder whose balance is decreased. - `_from` MUST be 0x0 for a mint. * The `_ids` argument MUST be the list of tokens being transferred. * The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in `_ids`) the holder balance is decreased by and match what the recipient balance is increased by. * The `_data` argument MUST contain the information provided by the sender for the transfer with its contents unaltered. - i.e. it MUST pass on the unaltered `_data` argument sent via the `safeBatchTransferFrom` call for this transfer. * The recipient contract MAY accept an increase of its balance by returning the acceptance magic value `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` - If the return value is `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` the transfer MUST be completed or MUST revert if any other conditions are not met for success. * The recipient contract MAY reject an increase of its balance by calling revert. - If the recipient contract throws/reverts the transaction MUST be reverted. * If the return value is anything other than `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` the transaction MUST be reverted. * `onERC1155BatchReceived` (and/or `onERC1155Received`) MAY be called multiple times in a single transaction and the following requirements must be met: - All callbacks represent mutually exclusive balance changes. - The set of all calls to `onERC1155Received` and `onERC1155BatchReceived` describes all balance changes that occurred during the transaction in the order submitted. * A contract MAY skip calling the `onERC1155BatchReceived` hook function if the transfer operation is transferring the token(s) to itself. **_ERC1155TokenReceiver ERC-165 rules:_** * The implementation of the ERC-165 `supportsInterface` function SHOULD be as follows: ```solidity function supportsInterface(bytes4 interfaceID) external view returns (bool) { return interfaceID == 0x01ffc9a7 || // ERC-165 support (i.e. `bytes4(keccak256('supportsInterface(bytes4)'))`). interfaceID == 0x4e2312e0; // ERC-1155 `ERC1155TokenReceiver` support (i.e. `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")) ^ bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))`). } ``` * The implementation MAY differ from the above but: - It MUST return the constant value `true` if `0x01ffc9a7` is passed through the `interfaceID` argument. This signifies ERC-165 support. - It MUST return the constant value `true` if `0x4e2312e0` is passed through the `interfaceID` argument. This signifies ERC-1155 `ERC1155TokenReceiver` support. - It MUST NOT consume more than 10,000 gas. - This keeps it below the ERC-165 requirement of 30,000 gas, reduces the gas reserve needs and minimises possible side-effects of gas exhaustion during the call. **_Implementation specific transfer API rules:_** * If an implementation specific API function is used to transfer ERC-1155 token(s) to a contract, the `safeTransferFrom` or `safeBatchTransferFrom` (as appropriate) rules MUST still be followed if the receiver implements the `ERC1155TokenReceiver` interface. If it does not the non-standard implementation SHOULD revert but MAY proceed. * An example: 1. An approved user calls a function such as `function myTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values);`. 2. `myTransferFrom` updates the balances for `_from` and `_to` addresses for all `_ids` and `_values`. 3. `myTransferFrom` emits `TransferBatch` with the details of what was transferred from address `_from` to address `_to`. 4. `myTransferFrom` checks if `_to` is a contract address and determines that it is so (if not, then the transfer can be considered successful). 5. `myTransferFrom` calls `onERC1155BatchReceived` on `_to` and it reverts or returns an unknown value (if it had returned `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))` the transfer can be considered successful). 6. At this point `myTransferFrom` SHOULD revert the transaction immediately as receipt of the token(s) was not explicitly accepted by the `onERC1155BatchReceived` function. 7. If however `myTransferFrom` wishes to continue it MUST call `supportsInterface(0x4e2312e0)` on `_to` and if it returns the constant value `true` the transaction MUST be reverted, as it is now known to be a valid receiver and the previous acceptance step failed. - NOTE: You could have called `supportsInterface(0x4e2312e0)` at a previous step if you wanted to gather and act upon that information earlier, such as in a hybrid standards scenario. 8. If the above call to `supportsInterface(0x4e2312e0)` on `_to` reverts or returns a value other than the constant value `true` the `myTransferFrom` function MAY consider this transfer successful. - __NOTE__: this MAY result in unrecoverable tokens if sent to an address that does not expect to receive ERC-1155 tokens. * The above example is not exhaustive but illustrates the major points (and shows that most are shared with `safeTransferFrom` and `safeBatchTransferFrom`): - Balances that are updated MUST have equivalent transfer events emitted. - A receiver address has to be checked if it is a contract and if so relevant `ERC1155TokenReceiver` hook function(s) have to be called on it. - Balances (and events associated) that are referenced in a call to an `ERC1155TokenReceiver` hook MUST be updated (and emitted) before the `ERC1155TokenReceiver` hook is called. - The return values of the `ERC1155TokenReceiver` hook functions that are called MUST be respected if they are implemented. - Only non-standard transfer functions MAY allow tokens to be sent to a recipient contract that does NOT implement the necessary `ERC1155TokenReceiver` hook functions. `safeTransferFrom` and `safeBatchTransferFrom` MUST revert in that case (unless it is a hybrid standards implementation see "Backwards Compatibility"). **_Minting/creating and burning/destroying rules:_** * A mint/create operation is essentially a specialized transfer and MUST follow these rules: - To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the `TransferSingle` event from `0x0` to `0x0`, with the token creator as `_operator`, and a `_value` of 0. - The "TransferSingle and TransferBatch event rules" MUST be followed as appropriate for the mint(s) (i.e. singles or batches) however the `_from` argument MUST be set to `0x0` (i.e. zero address) to flag the transfer as a mint to contract observers. - __NOTE:__ This includes tokens that are given an initial balance in the contract. The balance of the contract MUST also be able to be determined by events alone meaning initial contract balances (for eg. in construction) MUST emit events to reflect those balances too. * A burn/destroy operation is essentially a specialized transfer and MUST follow these rules: - The "TransferSingle and TransferBatch event rules" MUST be followed as appropriate for the burn(s) (i.e. singles or batches) however the `_to` argument MUST be set to `0x0` (i.e. zero address) to flag the transfer as a burn to contract observers. - When burning/destroying you do not have to actually transfer to `0x0` (that is impl specific), only the `_to` argument in the event MUST be set to `0x0` as above. * The total value transferred from address `0x0` minus the total value transferred to `0x0` observed via the `TransferSingle` and `TransferBatch` events MAY be used by clients and exchanges to determine the "circulating supply" for a given token ID. * As mentioned above mint/create and burn/destroy operations are specialized transfers and so will likely be accomplished with custom transfer functions rather than `safeTransferFrom` or `safeBatchTransferFrom`. If so the "Implementation specific transfer API rules" section would be appropriate. - Even in a non-safe API and/or hybrid standards case the above event rules MUST still be adhered to when minting/creating or burning/destroying. * A contract MAY skip calling the `ERC1155TokenReceiver` hook function(s) if the mint operation is transferring the token(s) to itself. In all other cases the `ERC1155TokenReceiver` rules MUST be followed as appropriate for the implementation (i.e. safe, custom and/or hybrid). ##### A solidity example of the keccak256 generated constants for the various magic values (these MAY be used by implementation): ```solidity bytes4 constant public ERC1155_ERC165 = 0xd9b67a26; // ERC-165 identifier for the main token standard. bytes4 constant public ERC1155_ERC165_TOKENRECEIVER = 0x4e2312e0; // ERC-165 identifier for the `ERC1155TokenReceiver` support (i.e. `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)")) ^ bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))`). bytes4 constant public ERC1155_ACCEPTED = 0xf23a6e61; // Return value from `onERC1155Received` call if a contract accepts receipt (i.e `bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))`). bytes4 constant public ERC1155_BATCH_ACCEPTED = 0xbc197c81; // Return value from `onERC1155BatchReceived` call if a contract accepts receipt (i.e `bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))`). ``` ### Metadata The URI value allows for ID substitution by clients. If the string `{id}` exists in any URI, clients MUST replace this with the actual token ID in hexadecimal form. This allows for a large number of tokens to use the same on-chain string by defining a URI once, for that large number of tokens. * The string format of the substituted hexadecimal ID MUST be lowercase alphanumeric: `[0-9a-f]` with no 0x prefix. * The string format of the substituted hexadecimal ID MUST be leading zero padded to 64 hex characters length if necessary. Example of such a URI: `https://token-cdn-domain/{id}.json` would be replaced with `https://token-cdn-domain/000000000000000000000000000000000000000000000000000000000004cce0.json` if the client is referring to token ID 314592/0x4CCE0. #### Metadata Extensions The optional `ERC1155Metadata_URI` extension can be identified with the [ERC-165 Standard Interface Detection](./eip-165.md). If the optional `ERC1155Metadata_URI` extension is included: * The ERC-165 `supportsInterface` function MUST return the constant value `true` if `0x0e89341c` is passed through the `interfaceID` argument. * _Changes_ to the URI MUST emit the `URI` event if the change can be expressed with an event (i.e. it isn't dynamic/programmatic). - An implementation MAY emit the `URI` event during a mint operation but it is NOT mandatory. An observer MAY fetch the metadata uri at mint time from the `uri` function if it was not emitted. * The `uri` function SHOULD be used to retrieve values if no event was emitted. * The `uri` function MUST return the same value as the latest event for an `_id` if it was emitted. * The `uri` function MUST NOT be used to check for the existence of a token as it is possible for an implementation to return a valid string even if the token does not exist. ```solidity pragma solidity ^0.5.9; /** Note: The ERC-165 identifier for this interface is 0x0e89341c. */ interface ERC1155Metadata_URI { /** @notice A distinct Uniform Resource Identifier (URI) for a given token. @dev URIs are defined in RFC 3986. The URI MUST point to a JSON file that conforms to the "ERC-1155 Metadata URI JSON Schema". @return URI string */ function uri(uint256 _id) external view returns (string memory); } ``` #### ERC-1155 Metadata URI JSON Schema This JSON schema is loosely based on the "ERC721 Metadata JSON Schema", but includes optional formatting to allow for ID substitution by clients. If the string `{id}` exists in any JSON value, it MUST be replaced with the actual token ID, by all client software that follows this standard. * The string format of the substituted hexadecimal ID MUST be lowercase alphanumeric: `[0-9a-f]` with no 0x prefix. * The string format of the substituted hexadecimal ID MUST be leading zero padded to 64 hex characters length if necessary. ```json { "title": "Token Metadata", "type": "object", "properties": { "name": { "type": "string", "description": "Identifies the asset to which this token represents" }, "decimals": { "type": "integer", "description": "The number of decimal places that the token amount should display - e.g. 18, means to divide the token amount by 1000000000000000000 to get its user representation." }, "description": { "type": "string", "description": "Describes the asset to which this token represents" }, "image": { "type": "string", "description": "A URI pointing to a resource with mime type image/* representing the asset to which this token represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive." }, "properties": { "type": "object", "description": "Arbitrary properties. Values may be strings, numbers, object or arrays." } } } ``` An example of an ERC-1155 Metadata JSON file follows. The properties array proposes some SUGGESTED formatting for token-specific display properties and metadata. ```json { "name": "Asset Name", "description": "Lorem ipsum...", "image": "https:\/\/s3.amazonaws.com\/your-bucket\/images\/{id}.png", "properties": { "simple_property": "example value", "rich_property": { "name": "Name", "value": "123", "display_value": "123 Example Value", "class": "emphasis", "css": { "color": "#ffffff", "font-weight": "bold", "text-decoration": "underline" } }, "array_property": { "name": "Name", "value": [1,2,3,4], "class": "emphasis" } } } ``` ##### Localization Metadata localization should be standardized to increase presentation uniformity across all languages. As such, a simple overlay method is proposed to enable localization. If the metadata JSON file contains a `localization` attribute, its content MAY be used to provide localized values for fields that need it. The `localization` attribute should be a sub-object with three attributes: `uri`, `default` and `locales`. If the string `{locale}` exists in any URI, it MUST be replaced with the chosen locale by all client software. ##### JSON Schema ```json { "title": "Token Metadata", "type": "object", "properties": { "name": { "type": "string", "description": "Identifies the asset to which this token represents", }, "decimals": { "type": "integer", "description": "The number of decimal places that the token amount should display - e.g. 18, means to divide the token amount by 1000000000000000000 to get its user representation." }, "description": { "type": "string", "description": "Describes the asset to which this token represents" }, "image": { "type": "string", "description": "A URI pointing to a resource with mime type image/* representing the asset to which this token represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive." }, "properties": { "type": "object", "description": "Arbitrary properties. Values may be strings, numbers, object or arrays.", }, "localization": { "type": "object", "required": ["uri", "default", "locales"], "properties": { "uri": { "type": "string", "description": "The URI pattern to fetch localized data from. This URI should contain the substring `{locale}` which will be replaced with the appropriate locale value before sending the request." }, "default": { "type": "string", "description": "The locale of the default data within the base JSON" }, "locales": { "type": "array", "description": "The list of locales for which data is available. These locales should conform to those defined in the Unicode Common Locale Data Repository (http://cldr.unicode.org/)." } } } } } ``` ##### Localized Sample Base URI: ```json { "name": "Advertising Space", "description": "Each token represents a unique Ad space in the city.", "localization": { "uri": "ipfs://QmWS1VAdMD353A6SDk9wNyvkT14kyCiZrNDYAad4w1tKqT/{locale}.json", "default": "en", "locales": ["en", "es", "fr"] } } ``` es.json: ```json { "name": "Espacio Publicitario", "description": "Cada token representa un espacio publicitario único en la ciudad." } ``` fr.json: ```json { "name": "Espace Publicitaire", "description": "Chaque jeton représente un espace publicitaire unique dans la ville." } ``` ### Approval The function `setApprovalForAll` allows an operator to manage one's entire set of tokens on behalf of the approver. To permit approval of a subset of token IDs, an interface such as [ERC-1761 Scoped Approval Interface](./eip-1761.md) is suggested. The counterpart `isApprovedForAll` provides introspection into any status set by `setApprovalForAll`. An owner SHOULD be assumed to always be able to operate on their own tokens regardless of approval status, so should SHOULD NOT have to call `setApprovalForAll` to approve themselves as an operator before they can operate on them. ## Rationale ### Metadata Choices The `symbol` function (found in the ERC-20 and ERC-721 standards) was not included as we do not believe this is a globally useful piece of data to identify a generic virtual item / asset and are also prone to collisions. Short-hand symbols are used in tickers and currency trading, but they aren't as useful outside of that space. The `name` function (for human-readable asset names, on-chain) was removed from the standard to allow the Metadata JSON to be the definitive asset name and reduce duplication of data. This also allows localization for names, which would otherwise be prohibitively expensive if each language string was stored on-chain, not to mention bloating the standard interface. While this decision may add a small burden on implementers to host a JSON file containing metadata, we believe any serious implementation of ERC-1155 will already utilize JSON Metadata. ### Upgrades The requirement to emit `TransferSingle` or `TransferBatch` on balance change implies that a valid implementation of ERC-1155 redeploying to a new contract address MUST emit events from the new contract address to replicate the deprecated contract final state. It is valid to only emit a minimal number of events to reflect only the final balance and omit all the transactions that led to that state. The event emit requirement is to ensure that the current state of the contract can always be traced only through events. To alleviate the need to emit events when changing contract address, consider using the proxy pattern, such as described in [EIP-2535](./eip-2535.md). This will also have the added benefit of providing a stable contract address for users. ### Design decision: Supporting non-batch The standard supports `safeTransferFrom` and `onERC1155Received` functions because they are significantly cheaper for single token-type transfers, which is arguably a common use case. ### Design decision: Safe transfers only The standard only supports safe-style transfers, making it possible for receiver contracts to depend on `onERC1155Received` or `onERC1155BatchReceived` function to be always called at the end of a transfer. ### Guaranteed log trace As the Ethereum ecosystem continues to grow, many dapps are relying on traditional databases and explorer API services to retrieve and categorize data. The ERC-1155 standard guarantees that event logs emitted by the smart contract will provide enough data to create an accurate record of all current token balances. A database or explorer may listen to events and be able to provide indexed and categorized searches of every ERC-1155 token in the contract. ### Approval The function `setApprovalForAll` allows an operator to manage one's entire set of tokens on behalf of the approver. It enables frictionless interaction with exchange and trade contracts. Restricting approval to a certain set of token IDs, quantities or other rules MAY be done with an additional interface or an external contract. The rationale is to keep the ERC-1155 standard as generic as possible for all use-cases without imposing a specific approval scheme on implementations that may not need it. Standard token approval interfaces can be used, such as the suggested [ERC-1761 Scoped Approval Interface](./eip-1761.md) which is compatible with ERC-1155. ## Backwards Compatibility There have been requirements during the design discussions to have this standard be compatible with existing standards when sending to contract addresses, specifically ERC-721 at time of writing. To cater for this scenario, there is some leeway with the revert logic should a contract not implement the `ERC1155TokenReceiver` as per "Safe Transfer Rules" section above, specifically "Scenario#3 : The receiver does not implement the necessary `ERC1155TokenReceiver` interface function(s)". Hence in a hybrid ERC-1155 contract implementation an extra call MUST be made on the recipient contract and checked before any hook calls to `onERC1155Received` or `onERC1155BatchReceived` are made. Order of operation MUST therefore be: 1. The implementation MUST call the function `supportsInterface(0x4e2312e0)` on the recipient contract, providing at least 10,000 gas. 2. If the function call succeeds and the return value is the constant value `true` the implementation proceeds as a regular ERC-1155 implementation, with the call(s) to the `onERC1155Received` or `onERC1155BatchReceived` hooks and rules associated. 3. If the function call fails or the return value is NOT the constant value `true` the implementation can assume the recipient contract is not an `ERC1155TokenReceiver` and follow its other standard's rules for transfers. *__Note that a pure implementation of a single standard is recommended__* rather than a hybrid solution, but an example of a hybrid ERC-1155/ERC-721 contract is linked in the references section under implementations. An important consideration is that even if the tokens are sent with another standard's rules the *__ERC-1155 transfer events MUST still be emitted.__* This is so the balances can still be determined via events alone as per ERC-1155 standard rules. ## Usage This standard can be used to represent multiple token types for an entire domain. Both fungible and non-fungible tokens can be stored in the same smart-contract. ### Batch Transfers The `safeBatchTransferFrom` function allows for batch transfers of multiple token IDs and values. The design of ERC-1155 makes batch transfers possible without the need for a wrapper contract, as with existing token standards. This reduces gas costs when more than one token type is included in a batch transfer, as compared to single transfers with multiple transactions. Another advantage of standardized batch transfers is the ability for a smart contract to respond to the batch transfer in a single operation using `onERC1155BatchReceived`. It is RECOMMENDED that clients and wallets sort the token IDs and associated values (in ascending order) when posting a batch transfer, as some ERC-1155 implementations offer significant gas cost savings when IDs are sorted. See [Horizon Games - Multi-Token Standard](https://github.com/horizon-games/multi-token-standard) "packed balance" implementation for an example of this. ### Batch Balance The `balanceOfBatch` function allows clients to retrieve balances of multiple owners and token IDs with a single call. ### Enumerating from events In order to keep storage requirements light for contracts implementing ERC-1155, enumeration (discovering the IDs and values of tokens) must be done using event logs. It is RECOMMENDED that clients such as exchanges and blockchain explorers maintain a local database containing the token ID, Supply, and URI at the minimum. This can be built from each TransferSingle, TransferBatch, and URI event, starting from the block the smart contract was deployed until the latest block. ERC-1155 contracts must therefore carefully emit `TransferSingle` or `TransferBatch` events in any instance where tokens are created, minted, transferred or destroyed. ### Non-Fungible Tokens The following strategies are examples of how you MAY mix fungible and non-fungible tokens together in the same contract. The standard does NOT mandate how an implementation must do this. ##### Split ID bits The top 128 bits of the uint256 `_id` parameter in any ERC-1155 function MAY represent the base token ID, while the bottom 128 bits MAY represent the index of the non-fungible to make it unique. Non-fungible tokens can be interacted with using an index based accessor into the contract/token data set. Therefore to access a particular token set within a mixed data contract and a particular non-fungible within that set, `_id` could be passed as ``. To identify a non-fungible set/category as a whole (or a fungible) you COULD just pass in the base id via the `_id` argument as ``. If your implementation uses this technique this naturally means the index of a non-fungible SHOULD be 1-based. Inside the contract code the two pieces of data needed to access the individual non-fungible can be extracted with uint128(~0) and the same mask shifted by 128. ```solidity uint256 baseTokenNFT = 12345 << 128; uint128 indexNFT = 50; uint256 baseTokenFT = 54321 << 128; balanceOf(msg.sender, baseTokenNFT); // Get balance of the base token for non-fungible set 12345 (this MAY be used to get balance of the user for all of this token set if the implementation wishes as a convenience). balanceOf(msg.sender, baseTokenNFT + indexNFT); // Get balance of the token at index 50 for non-fungible set 12345 (should be 1 if user owns the individual non-fungible token or 0 if they do not). balanceOf(msg.sender, baseTokenFT); // Get balance of the fungible base token 54321. ``` Note that 128 is an arbitrary number, an implementation MAY choose how they would like this split to occur as suitable for their use case. An observer of the contract would simply see events showing balance transfers and mints happening and MAY track the balances using that information alone. For an observer to be able to determine type (non-fungible or fungible) from an ID alone they would have to know the split ID bits format on a implementation by implementation basis. The [ERC-1155 Reference Implementation](https://github.com/enjin/erc-1155) is an example of the split ID bits strategy. ##### Natural Non-Fungible tokens Another simple way to represent non-fungibles is to allow a maximum value of 1 for each non-fungible token. This would naturally mirror the real world, where unique items have a quantity of 1 and fungible items have a quantity greater than 1. ## References **Standards** - [ERC-721 Non-Fungible Token Standard](./eip-721.md) - [ERC-165 Standard Interface Detection](./eip-165.md) - [ERC-1538 Transparent Contract Standard](./eip-1538.md) - [JSON Schema](https://json-schema.org/) - [RFC 2119 Key words for use in RFCs to Indicate Requirement Levels](https://www.ietf.org/rfc/rfc2119.txt) **Implementations** - [ERC-1155 Reference Implementation](https://github.com/enjin/erc-1155) - [Horizon Games - Multi-Token Standard](https://github.com/horizon-games/multi-token-standard) - [Enjin Coin](https://enjincoin.io) ([GitHub](https://github.com/enjin)) - [The Sandbox - Dual ERC-1155/721 Contract](https://github.com/pixowl/thesandbox-contracts/tree/master/src/Asset) **Articles & Discussions** - [GitHub - Original Discussion Thread](https://github.com/ethereum/EIPs/issues/1155) - [ERC-1155 - The Crypto Item Standard](https://blog.enjincoin.io/erc-1155-the-crypto-item-standard-ac9cf1c5a226) - [Here Be Dragons - Going Beyond ERC-20 and ERC-721 To Reduce Gas Cost by ~80%](https://medium.com/horizongames/going-beyond-erc20-and-erc721-9acebd4ff6ef) - [Blockonomi - Ethereum ERC-1155 Token Perfect for Online Games, Possibly More](https://blockonomi.com/erc1155-gaming-token/) - [Beyond Gaming - Exploring the Utility of ERC-1155 Token Standard!](https://blockgeeks.com/erc-1155-token/) - [ERC-1155: A new standard for The Sandbox](https://medium.com/sandbox-game/erc-1155-a-new-standard-for-the-sandbox-c95ee1e45072) ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Minimal Proxy Contract

Fri, 22 Jun 2018 00:00:00 +0000

## Simple Summary To simply and cheaply clone contract functionality in an immutable way, this standard specifies a minimal bytecode implementation that delegates all calls to a known, fixed address. ## Abstract By standardizing on a known minimal bytecode redirect implementation, this standard allows users and third party tools (e.g. Etherscan) to (a) simply discover that a contract will always redirect in a known manner and (b) depend on the behavior of the code at the destination contract as the behavior of the redirecting contract. Specifically, tooling can interrogate the bytecode at a redirecting address to determine the location of the code that will run - and can depend on representations about that code (verified source, third-party audits, etc). This implementation forwards all calls and 100% of the gas to the implementation contract and then relays the return value back to the caller. In the case where the implementation reverts, the revert is passed back along with the payload data (for revert with message). ## Motivation This standard supports use-cases wherein it is desirable to clone exact contract functionality with a minimum of side effects (e.g. memory slot stomping) and with low gas cost deployment of duplicate proxies. ## Specification The exact bytecode of the standard clone contract is this: `363d3d373d3d3d363d73bebebebebebebebebebebebebebebebebebebebe5af43d82803e903d91602b57fd5bf3` wherein the bytes at indices 10 - 29 (inclusive) are replaced with the 20 byte address of the master functionality contract. A reference implementation of this can be found at the [optionality/clone-factory](https://github.com/optionality/clone-factory) github repo. ## Rationale The goals of this effort have been the following: - inexpensive deployment (low gas to deploy clones) - support clone initialization in creation transaction (through factory contract model) - simple clone bytecode to encourage directly bytecode interrogation (see CloneProbe.sol in the clone-factory project) - dependable, locked-down behavior - this is not designed to handle upgradability, nor should it as the representation we are seeking is stronger. - small operational overhead - adds a single call cost to each call - handles error return bubbling for revert messages ## Backwards Compatibility There are no backwards compatibility issues. There may be some systems that are using earlier versions of the proxy contract bytecode. They will not be compliant with this standard. ## Test Cases Test cases include: - invocation with no arguments - invocation with arguments - invocation with fixed length return values - invocation with variable length return values - invocation with revert (confirming reverted payload is transferred) Tests for these cases are included in the reference implementation project. ## Implementation Deployment bytecode is not included in this specification. One approach is defined in the proxy-contract reference implementation. ### Standard Proxy The disassembly of the standard deployed proxy contract code (from r2 and edited to include stack visualization) ``` | 0x00000000 36 calldatasize cds | 0x00000001 3d returndatasize 0 cds | 0x00000002 3d returndatasize 0 0 cds | 0x00000003 37 calldatacopy | 0x00000004 3d returndatasize 0 | 0x00000005 3d returndatasize 0 0 | 0x00000006 3d returndatasize 0 0 0 | 0x00000007 36 calldatasize cds 0 0 0 | 0x00000008 3d returndatasize 0 cds 0 0 0 | 0x00000009 73bebebebebe. push20 0xbebebebe 0xbebe 0 cds 0 0 0 | 0x0000001e 5a gas gas 0xbebe 0 cds 0 0 0 | 0x0000001f f4 delegatecall suc 0 | 0x00000020 3d returndatasize rds suc 0 | 0x00000021 82 dup3 0 rds suc 0 | 0x00000022 80 dup1 0 0 rds suc 0 | 0x00000023 3e returndatacopy suc 0 | 0x00000024 90 swap1 0 suc | 0x00000025 3d returndatasize rds 0 suc | 0x00000026 91 swap2 suc 0 rds | 0x00000027 602b push1 0x2b 0x2b suc 0 rds | ,=< 0x00000029 57 jumpi 0 rds | | 0x0000002a fd revert | `-> 0x0000002b 5b jumpdest 0 rds \ 0x0000002c f3 return ``` NOTE: as an effort to reduce gas costs as much as possible, the above bytecode depends on EIP-211 specification that `returndatasize` returns zero prior to any calls within the call-frame. `returndatasize` uses 1 less gas than `dup*`. ### Vanity Address Optimization Proxy deployment can be further optimized by installing the master contract at a vanity contract deployment address with leading zero-bytes. By generating a master contract vanity address that includes Z leading 0 bytes in its address, you can shorten the proxy bytecode by replacing the `push20` opcode with `pushN` (where N is 20 - Z) followed by the N non-zero address bytes. The revert jump address is decremented by Z in this case. Here is an example where Z = 4: ``` | 0x00000000 36 calldatasize cds | 0x00000001 3d returndatasize 0 cds | 0x00000002 3d returndatasize 0 0 cds | 0x00000003 37 calldatacopy | 0x00000004 3d returndatasize 0 | 0x00000005 3d returndatasize 0 0 | 0x00000006 3d returndatasize 0 0 0 | 0x00000007 36 calldatasize cds 0 0 0 | 0x00000008 3d returndatasize 0 cds 0 0 0 | 0x00000009 6fbebebebebe. push16 0xbebebebe 0xbebe 0 cds 0 0 0 | 0x0000001a 5a gas gas 0xbebe 0 cds 0 0 0 | 0x0000001b f4 delegatecall suc 0 | 0x0000001c 3d returndatasize rds suc 0 | 0x0000001d 82 dup3 0 rds suc 0 | 0x0000001e 80 dup1 0 0 rds suc 0 | 0x0000001f 3e returndatacopy suc 0 | 0x00000020 90 swap1 0 suc | 0x00000021 3d returndatasize rds 0 suc | 0x00000022 91 swap2 suc 0 rds | 0x00000023 6027 push1 0x27 0x27 suc 0 rds | ,=< 0x00000025 57 jumpi 0 rds | | 0x00000026 fd revert | `-> 0x00000027 5b jumpdest 0 rds \ 0x00000028 f3 return ``` This saves 4 bytes of proxy contract size (savings on each deployment) and has zero impact on runtime gas costs. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Wallet & shop standard for all tokens (erc20)

Thu, 21 Jun 2018 00:00:00 +0000

# All tokens go to heaven ## Simple Summary Make wallets and shops created from certified contracts make erc20 tokens easy to use for commerce. ![wallet](../assets/eip-1175/wallet.png) ## Abstract The mutual trust between the wallet and the shop created by the authenticated contract allows you to pay for and purchase items at a simple process. ## Motivation New standards with improvements have been released, but the majority of tokens currently being developed are erc20 tokens. So I felt I needed a proposal to use old tokens in commerce. To use various erc20 tokens for trading, you need a custom contract. However, a single wallet with a variety of tokens, and a mutually trusted store, can make transactions that are simple and efficient. The erc20 token is traded through two calls, `approve (address _spender, uint256 _value)` and `transferFrom (address _from, address _to, uint256 _value)`, but when using the wallet contract, `paySafe (address _shop, uint256 _item)`will be traded only in one call. And if you only reuse the store interface, you can also trade using `payUnsafe (address _shop, uint256 _item)`. ## Specification ![workflow](../assets/eip-1175/workflow.png) ## WalletCenter ### Methods #### createWallet Create wallet contract and add to list. Returns the address of new wallet. ``` js function createWallet() public returns (address _wallet) ``` #### isWallet Returns true or false value for test this address is a created by createWallet. ``` js function isWallet(address _wallet) public constant returns (bool) ``` #### createShop Create Shop contract and add to list. Returns the address of new Shop with erc20 token address. ``` js function createShop(address _erc20) public returns (address _shop) ``` #### isShop Returns true or false value for test this address is a created by createWallet. ``` js function isShop(address _shop) public constant returns (bool) ``` ### Events #### Wallet Search for my wallet. ``` js event Wallet(address indexed _owner, address indexed _wallet) ``` #### Shop Search for my shop. ``` js event Shop(address indexed _owner, address indexed _shop, address indexed _erc20) ``` ## Wallet Wallet must be created by wallet center. ### Methods #### balanceOf Returns the account balance of Wallet. ``` js function balanceOf(address _erc20) public constant returns (uint256 balance) ``` #### withdrawal withdrawal `_value` amount of `_erc20` token to `_owner`. ``` js function withdrawal(address _erc20, uint256 _value) onlyOwner public returns (bool success) ``` #### paySafe Pay for safe shop (created by contract) item with item index `_item`. ``` js function paySafe(address _shop, uint256 _item) onlyOwner onlyShop(_shop) public payable returns (bool success) ``` #### payUnsafe Pay for unsafe shop (did not created by contract) item with item index `_item`. ``` js function payUnsafe(address _shop, uint256 _item) onlyOwner public payable returns (bool success) ``` #### payCancel Cancel pay and refund. (only weekly model) ``` js function payCancel(address _shop, uint256 _item) onlyOwner public returns (bool success) ``` #### refund Refund from shop with item index `_item`. ``` js function refund(uint256 _item, uint256 _value) public payable returns (bool success) ``` ### Events #### Pay ``` js event Pay(address indexed _shop, uint256 indexed _item, uint256 indexed _value) ``` #### Refund ``` js event Refund(address indexed _shop, uint256 indexed _item, uint256 indexed _value) ``` ## Shop Shop is created by wallet center or not. but Shop that created by wallet center is called safe shop. ### Methods #### balanceOf Returns the account balance of Shop. ``` js function balanceOf(address _erc20) public constant returns (uint256 balance) ``` #### withdrawal withdrawal `_value` amount of `_erc20` token to `_owner`. ``` js function withdrawal(address _erc20, uint256 _value) onlyOwner public returns (bool success) ``` #### pay Pay from buyer with item index `_item`. ``` js function pay(uint256 _item) onlyWallet(msg.sender) public payable returns (bool success) ``` #### refund refund token to `_to`. ``` js function refund(address _buyer, uint256 _item, uint256 _value) onlyWallet(_buyer) onlyOwner public payable returns (bool success) ``` #### resister Listing item for sell. ``` js function resister(uint8 _category, uint256 _price, uint256 _stock) onlyOwner public returns (uint256 _itemId) ``` #### update Update item state for sell. (change item `_price` or add item `_stock`) ``` js function update(uint256 _item, uint256 _price, uint256 _stock) onlyOwner public ``` #### price Get token address and price from buyer with item index `_item`. ``` js function price(uint256 _item) public constant returns (address _erc20, uint256 _value) ``` #### canBuy `_who` can Buy `_item`. ``` js function canBuy(address _who, uint256 _item) public constant returns (bool _canBuy) ``` #### isBuyer `_who` is buyer of `_item`. ``` js function isBuyer(address _who, uint256 _item) public constant returns (bool _buyer) ``` #### info Set shop information bytes. ``` js function info(bytes _msgPack) ``` #### upVote Up vote for this shop. ``` js function upVote() ``` #### dnVote Down vote for this shop. ``` js function dnVote() ``` #### about Get shop token, up vote and down vote. ``` js function about() view returns (address _erc20, uint256 _up, uint256 _down) ``` #### infoItem Set item information bytes. ``` js function infoItem(uint256 _item, bytes _msgPack) ``` #### upVoteItem Up vote for this item. ``` js function upVoteItem(uint256 _item) ``` #### dnVoteItem Down vote for this item. ``` js function dnVoteItem(uint256 _item) ``` #### aboutItem Get Item price, up vote and down vote. ``` js function aboutItem(uint256 _item) view returns (uint256 _price, uint256 _up, uint256 _down) ``` ### Events #### Pay ``` js event Pay(address indexed _buyer, uint256 indexed _item, uint256 indexed _value) ``` #### Refund ``` js event Refund(address indexed _to, uint256 indexed _item, uint256 indexed _value) ``` #### Item ``` js event Item(uint256 indexed _item, uint256 _price) ``` #### Info ``` js event Info(bytes _msgPack) ``` #### InfoItem ``` js event InfoItem(uint256 indexed _item, bytes _msgPack) ``` ## Implementation Sample token contract address is [0x393dd70ce2ae7b30501aec94727968c517f90d52](https://ropsten.etherscan.io/address/0x393dd70ce2ae7b30501aec94727968c517f90d52) WalletCenter contract address is [0x1fe0862a4a8287d6c23904d61f02507b5044ea31](https://ropsten.etherscan.io/address/0x1fe0862a4a8287d6c23904d61f02507b5044ea31) WalletCenter create shop contract address is [0x59117730D02Ca3796121b7975796d479A5Fe54B0](https://ropsten.etherscan.io/address/0x59117730D02Ca3796121b7975796d479A5Fe54B0) WalletCenter create wallet contract address is [0x39da7111844df424e1d0a0226183533dd07bc5c6](https://ropsten.etherscan.io/address/0x39da7111844df424e1d0a0226183533dd07bc5c6) ## Appendix ``` js pragma solidity ^0.4.24; contract ERC20Interface { function totalSupply() public constant returns (uint); function balanceOf(address tokenOwner) public constant returns (uint balance); function allowance(address tokenOwner, address spender) public constant returns (uint remaining); function transfer(address to, uint tokens) public returns (bool success); function approve(address spender, uint tokens) public returns (bool success); function transferFrom(address from, address to, uint tokens) public returns (bool success); event Transfer(address indexed from, address indexed to, uint tokens); event Approval(address indexed tokenOwner, address indexed spender, uint tokens); } contract SafeMath { function safeAdd(uint a, uint b) public pure returns (uint c) { c = a + b; require(c >= a); } function safeSub(uint a, uint b) public pure returns (uint c) { require(b <= a); c = a - b; } function safeMul(uint a, uint b) public pure returns (uint c) { c = a * b; require(a == 0 || c / a == b); } function safeDiv(uint a, uint b) public pure returns (uint c) { require(b > 0); c = a / b; } } contract _Base { address internal owner; address internal walletCenter; modifier onlyOwner { require(owner == msg.sender); _; } modifier onlyWallet(address _addr) { require(WalletCenter(walletCenter).isWallet(_addr)); _; } modifier onlyShop(address _addr) { require(WalletCenter(walletCenter).isShop(_addr)); _; } function balanceOf(address _erc20) public constant returns (uint256 balance) { if(_erc20==address(0)) return address(this).balance; return ERC20Interface(_erc20).balanceOf(this); } function transfer(address _to, address _erc20, uint256 _value) internal returns (bool success) { require((_erc20==address(0)?address(this).balance:ERC20Interface(_erc20).balanceOf(this))>=_value); if(_erc20==address(0)) _to.transfer(_value); else ERC20Interface(_erc20).approve(_to,_value); return true; } function withdrawal(address _erc20, uint256 _value) public returns (bool success); event Pay(address indexed _who, uint256 indexed _item, uint256 indexed _value); event Refund(address indexed _who, uint256 indexed _item, uint256 indexed _value); event Prize(address indexed _who, uint256 indexed _item, uint256 indexed _value); } contract _Wallet is _Base { constructor(address _who) public { owner = _who; walletCenter = msg.sender; } function pay(address _shop, uint256 _item) private { require(_Shop(_shop).canBuy(this,_item)); address _erc20; uint256 _value; (_erc20,_value) = _Shop(_shop).price(_item); transfer(_shop,_erc20,_value); _Shop(_shop).pay(_item); emit Pay(_shop,_item,_value); } function paySafe(address _shop, uint256 _item) onlyOwner onlyShop(_shop) public payable returns (bool success) { pay(_shop,_item); return true; } function payUnsafe(address _shop, uint256 _item) onlyOwner public payable returns (bool success) { pay(_shop,_item); return true; } function payCancel(address _shop, uint256 _item) onlyOwner public returns (bool success) { _Shop(_shop).payCancel(_item); return true; } function refund(address _erc20, uint256 _item, uint256 _value) public payable returns (bool success) { require((_erc20==address(0)?msg.value:ERC20Interface(_erc20).allowance(msg.sender,this))==_value); if(_erc20!=address(0)) ERC20Interface(_erc20).transferFrom(msg.sender,this,_value); emit Refund(msg.sender,_item,_value); return true; } function prize(address _erc20, uint256 _item, uint256 _value) public payable returns (bool success) { require((_erc20==address(0)?msg.value:ERC20Interface(_erc20).allowance(msg.sender,this))==_value); if(_erc20!=address(0)) ERC20Interface(_erc20).transferFrom(msg.sender,this,_value); emit Prize(msg.sender,_item,_value); return true; } function withdrawal(address _erc20, uint256 _value) onlyOwner public returns (bool success) { require((_erc20==address(0)?address(this).balance:ERC20Interface(_erc20).balanceOf(this))>=_value); if(_erc20==address(0)) owner.transfer(_value); else ERC20Interface(_erc20).transfer(owner,_value); return true; } } contract _Shop is _Base, SafeMath{ address erc20; constructor(address _who, address _erc20) public { owner = _who; walletCenter = msg.sender; erc20 = _erc20; } struct item { uint8 category; // 0 = disable, 1 = non Stock, non Expire, 2 = can Expire (after 1 week), 3 = stackable uint256 price; uint256 stockCount; mapping(address=>uint256) customer; } uint index; mapping(uint256=>item) items; function pay(uint256 _item) onlyWallet(msg.sender) public payable returns (bool success) { require(canBuy(msg.sender, _item)); require((erc20==address(0)?msg.value:ERC20Interface(erc20).allowance(msg.sender,this))==items[_item].price); if(erc20!=address(0)) ERC20Interface(erc20).transferFrom(msg.sender,this,items[_item].price); if(items[_item].category==1 || items[_item].category==2 && now > safeAdd(items[_item].customer[msg.sender], 1 weeks)) items[_item].customer[msg.sender] = now; else if(items[_item].category==2 && now < safeAdd(items[_item].customer[msg.sender], 1 weeks) ) items[_item].customer[msg.sender] = safeAdd(items[_item].customer[msg.sender], 1 weeks); else if(items[_item].category==3) { items[_item].customer[msg.sender] = safeAdd(items[_item].customer[msg.sender],1); items[_item].stockCount = safeSub(items[_item].stockCount,1); } emit Pay(msg.sender,_item,items[_item].customer[msg.sender]); return true; } function payCancel(uint256 _item) onlyWallet(msg.sender) public returns (bool success) { require (items[_item].category==2&&safeAdd(items[_item].customer[msg.sender],2 weeks)>now&&balanceOf(erc20)>=items[_item].price); items[_item].customer[msg.sender] = safeSub(items[_item].customer[msg.sender],1 weeks); transfer(msg.sender, erc20, items[_item].price); _Wallet(msg.sender).refund(erc20,_item,items[_item].price); emit Refund(msg.sender,_item,items[_item].price); return true; } function refund(address _to, uint256 _item) onlyWallet(_to) onlyOwner public payable returns (bool success) { require(isBuyer(_to,_item)&&items[_item].category>0&&(items[_item].customer[_to]>0||(items[_item].category==2&&safeAdd(items[_item].customer[_to],2 weeks)>now))); require((erc20==address(0)?address(this).balance:ERC20Interface(erc20).balanceOf(this))>=items[_item].price); if(items[_item].category==1) items[_item].customer[_to] = 0; else if(items[_item].category==2) items[_item].customer[_to] = safeSub(items[_item].customer[_to],1 weeks); else items[_item].customer[_to] = safeSub(items[_item].customer[_to],1); transfer(_to, erc20, items[_item].price); _Wallet(_to).refund(erc20,_item,items[_item].price); emit Refund(_to,_item,items[_item].price); return true; } event Item(uint256 indexed _item, uint256 _price); function resister(uint8 _category, uint256 _price, uint256 _stock) onlyOwner public returns (uint256 _itemId) { require(_category>0&&_category<4); require(_price>0); items[index] = item(_category,_price,_stock); index = safeAdd(index,1); emit Item(index,_price); return safeSub(index,1); } function update(uint256 _item, uint256 _price, uint256 _stock) onlyOwner public { require(items[_item].category>0); require(_price>0); uint256 temp = items[_item].price; items[_item].price = _price; items[_item].stockCount = safeAdd(items[_item].stockCount,_stock); if(temp!=items[_item].price) emit Item(index,items[_item].price); } function price(uint256 _item) public constant returns (address _erc20, uint256 _value) { return (erc20,items[_item].price); } function canBuy(address _who, uint256 _item) public constant returns (bool _canBuy) { return (items[_item].category>0) && !(items[_item].category==1&&items[_item].customer[_who]>0) && (items[_item].stockCount>0); } function isBuyer(address _who, uint256 _item) public constant returns (bool _buyer) { return (items[_item].category==1&&items[_item].customer[_who]>0)||(items[_item].category==2&&safeAdd(items[_item].customer[_who],1 weeks)>now)||(items[_item].category==3&&items[_item].customer[_who]>0); } uint lastWithdrawal; function withdrawal(address _erc20, uint256 _value) onlyOwner public returns (bool success) { require(safeAdd(lastWithdrawal,1 weeks)<=now); require((_erc20==address(0)?address(this).balance:ERC20Interface(_erc20).balanceOf(this))>=_value); if(_erc20==address(0)) owner.transfer(_value); else ERC20Interface(_erc20).transfer(owner,_value); lastWithdrawal = now; return true; } } contract WalletCenter { mapping(address=>bool) public wallet; event Wallet(address indexed _owner, address indexed _wallet); function createWallet() public returns (address _wallet) { _wallet = new _Wallet(msg.sender); wallet[_wallet] = true; emit Wallet(msg.sender,_wallet); return _wallet; } function isWallet(address _wallet) public constant returns (bool) { return wallet[_wallet]; } mapping(address=>bool) public shop; event Shop(address indexed _owner, address indexed _shop, address indexed _erc20); function createShop(address _erc20) public returns (address _shop) { _shop = new _Shop(msg.sender,_erc20); shop[_shop] = true; emit Shop(msg.sender,_shop,_erc20); return _shop; } function isShop(address _shop) public constant returns (bool) { return shop[_shop]; } } ``` ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Multi-class Token Standard

Fri, 22 Jun 2018 00:00:00 +0000

## Simple Summary A standard interface for multi-class fungible tokens. ## Abstract This standard allows for the implementation of a standard API for multi-class fungible tokens (henceforth referred to as "MCFTs") within smart contracts. This standard provides basic functionality to track and transfer ownership of MCFTs. ## Motivation Currently, there is no standard to support tokens that have multiple classes. In the real world, there are many situations in which defining distinct classes of the same token would be fitting (e.g. distinguishing between preferred/common/restricted shares of a company). Yet, such nuance cannot be supported in today's token standards. An ERC-20 token contract defines tokens that are all of one class while an ERC-721 token contract creates a class (defined by token_id) for each individual token. The ERC-1178 token standard proposes a new standard for creating multiple classes of tokens within one token contract. > Aside: In theory, while it is possible to implement tokens with classes using the properties of token structs in ERC-721 tokens, gas costs of implementing this in practice are prohibitive for any non-trivial application. ## Specification ### ERC-20 Compatibility (partial) **name** ```solidity function name() constant returns (string name) ``` *OPTIONAL - It is recommended that this method is implemented for enhanced usability with wallets and exchanges, but interfaces and other contracts MUST NOT depend on the existence of this method.* Returns the name of the aggregate collection of MCFTs managed by this contract. - e.g. `"My Company Tokens"`. **class name** ```solidity function className(uint256 classId) constant returns (string name) ``` *OPTIONAL - It is recommended that this method is implemented for enhanced usability with wallets and exchanges, but interfaces and other contracts MUST NOT depend on the existence of this method.* Returns the name of the class of MCFT managed by this contract. - e.g. `"My Company Preferred Shares Token"`. **symbol** ```solidity function symbol() constant returns (string symbol) ``` *OPTIONAL - It is recommend that this method is implemented for enhanced usability with wallets and exchanges, but interfaces and other contracts MUST NOT depend on the existence of this method.* Returns a short string symbol referencing the entire collection of MCFT managed in this contract. e.g. "MUL". This symbol SHOULD be short (3-8 characters is recommended), with no whitespace characters or new-lines and SHOULD be limited to the uppercase latin alphabet (i.e. the 26 letters used in English). **totalSupply** ```solidity function totalSupply() constant returns (uint256 totalSupply) ``` Returns the total number of all MCFTs currently tracked by this contract. **individualSupply** ```solidity function individualSupply(uint256 _classId) constant returns (uint256 individualSupply) ``` Returns the total number of MCFTs of class `_classId` currently tracked by this contract. **balanceOf** ```solidity function balanceOf(address _owner, uint256 _classId) constant returns (uint256 balance) ``` Returns the number of MCFTs of token class `_classId` assigned to address `_owner`. **classesOwned** ```solidity function classesOwned(address _owner) constant returns (uint256[] classes) ``` Returns an array of `_classId`'s of MCFTs that address `_owner` owns in the contract. > NOTE: returning an array is supported by `pragma experimental ABIEncoderV2` ## Basic Ownership **approve** ```solidity function approve(address _to, uint256 _classId, uint256 quantity) ``` Grants approval for address `_to` to take possession `quantity` amount of the MCFT with ID `_classId`. This method MUST `throw` if `balanceOf(msg.sender, _classId) < quantity`, or if `_classId` does not represent an MCFT class currently tracked by this contract, or if `msg.sender == _to`. Only one address can "have approval" at any given time for a given address and `_classId`. Calling `approve` with a new address and `_classId` revokes approval for the previous address and `_classId`. Calling this method with 0 as the `_to` argument clears approval for any address and the specified `_classId`. Successful completion of this method MUST emit an `Approval` event (defined below) unless the caller is attempting to clear approval when there is no pending approval. In particular, an Approval event MUST be fired if the `_to` address is zero and there is some outstanding approval. Additionally, an Approval event MUST be fired if `_to` is already the currently approved address and this call otherwise has no effect. (i.e. An `approve()` call that "reaffirms" an existing approval MUST fire an event.) **transfer** ```solidity function transfer(address _to, uint256 _classId, uint256 quantity) ``` Assigns the ownership of `quantity` MCFT's with ID `_classId` to `_to` if and only if `quantity == balanceOf(msg.sender, _classId)`. A successful transfer MUST fire the `Transfer` event (defined below). This method MUST transfer ownership to `_to` or `throw`, no other outcomes can be possible. Reasons for failure include (but are not limited to): * `msg.sender` is not the owner of `quantity` amount of tokens of `_classId`'s. * `_classId` does not represent an MCFT class currently tracked by this contract A conforming contract MUST allow the current owner to "transfer" a token to themselves, as a way of affirming ownership in the event stream. (i.e. it is valid for `_to == msg.sender` if `balanceOf(msg.sender, _classId) >= balance`.) This "no-op transfer" MUST be considered a successful transfer, and therefore MUST fire a `Transfer` event (with the same address for `_from` and `_to`). ## Advanced Ownership and Exchange ```solidity function approveForToken(uint256 classIdHeld, uint256 quantityHeld, uint256 classIdWanted, uint256 quantityWanted) ``` Allows holder of one token to allow another individual (or the smart contract itself) to approve the exchange of their tokens of one class for tokens of another class at their specified exchange rate (see sample implementation for more details). This is equivalent to posting a bid in a marketplace. ```solidity function exchange(address to, uint256 classIdPosted, uint256 quantityPosted, uint256 classIdWanted, uint256 quantityWanted) ``` Allows an individual to fill an existing bid (see above function) and complete the exchange of their tokens of one class for another. In the sample implementation, this function call should fail unless the callee has already approved the contract to transfer their tokens. Of course, it is possible to create an implementation where calling this function implicitly assumes approval and the transfer is completed in one step. ```solidity transferFrom(address from, address to, uint256 classId) ``` Allows a third party to initiate a transfer of tokens from `from` to `to` assuming the approvals have been granted. ## Events **Transfer** This event MUST trigger when MCFT ownership is transferred via any mechanism. Additionally, the creation of new MCFTs MUST trigger a Transfer event for each newly created MCFTs, with a `_from` address of 0 and a `_to` address matching the owner of the new MCFT (possibly the smart contract itself). The deletion (or burn) of any MCFT MUST trigger a Transfer event with a `_to` address of 0 and a `_from` address of the owner of the MCFT (now former owner!). NOTE: A Transfer event with `_from == _to` is valid. See the `transfer()` documentation for details. ```solidity event Transfer(address indexed _from, address indexed _to, uint256 _classId) ``` **Approval** This event MUST trigger on any successful call to `approve(_to, _classId, quantity)` (unless the caller is attempting to clear approval when there is no pending approval). ```solidity event Approval(address indexed _owner, address indexed _approved, uint256 _classId) ``` ## Rationale ### Current Limitations The design of this project was motivated when I tried to create different classes of fungible ERC-721 tokens (an oxymoron) but ran into gas limits from having to create each tokens individually and maintain them in an efficient data structure for access. Using the maximum gas amount one can send with a transaction on Metamask (a popular web wallet), I was only able to create around 46 ERC-721 tokens before exhausting all gas. This experience motivated the creation of the multi-class fungible token standard. ## Backwards Compatibility Adoption of the MCFT standard proposal would not pose backwards compatibility issues as it defines a new standard for token creation. This standard follows the semantics of ERC-721 as closely as possible, but can't be entirely compatible with it due to the fundamental differences between multi-class fungible and non-fungible tokens. For example, the `ownerOf`, `takeOwnership`, and `tokenOfOwnerByIndex` methods in the ERC-721 token standard cannot be implemented in this standard. Furthermore, the function arguments to `balanceOf`, `approve`, and `transfer` differ as well. ## Implementation A sample implementation can be found [here](https://github.com/achon22/ERC-1178/blob/master/erc1178-sample.sol) ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Storage of DNS Records in ENS

Tue, 26 Jun 2018 00:00:00 +0000

## Abstract This EIP defines a resolver profile for ENS that provides features for storage and lookup of DNS records. This allows ENS to be used as a store of authoritative DNS information. ## Motivation ENS is a highly desirable store for DNS information. It provides the distributed authority of DNS without conflating ownership and authoritative serving of information. With ENS, the owner of a domain has full control over their own DNS records. Also, ENS has the ability (through smart contracts) for a domain's subdomains to be irrevocably assigned to another entity. ## Specification The resolver profile to support DNS on ENS follows the resolver specification as defined in [ERC-137](./eip-137.md). Traditionally, DNS is a zone-based system in that all of the records for a zone are kept together in the same file. This has the benefit of simplicity and atomicity of zone updates, but when transposed to ENS can result in significant gas costs for simple changes. As a result, the resolver works on the basis of record sets. A record set is uniquely defined by the tuple `(domain, name, resource record type)`, for example the tuple `(example.com, www.example.com, A)` defines the record set of `A` records for the name `www.example.com` in the domain `example.com`. A record set can contain 0 or more values, for example if `www.example.com` has `A` records `1.2.3.4` and `5.6.7.8` then the aforementioned tuple will have two values. The choice to work at the level of record sets rather than zones means that this specification cannot completely support some features of DNS, such as zone transfers and DNSSEC. It would be possible to build a different resolver profile that works at the zone level, however it would be very expensive to carry out updates and so is not considered further for this EIP. The DNS resolver interface consists of two functions to set DNS information and two functions to query DNS information. ### setDNSRecords(bytes32 node, bytes data) `setDNSRecords()` sets, updates or clears 1 or more DNS records for a given node. It has function signature `0x0af179d7`. The arguments for the function are as follows: - node: the namehash of the fully-qualified domain in ENS for which to set the records. Namehashes are defined in [ERC-137](./eip-137.md) - data: 1 or more DNS records in DNS wire format. Any record that is supplied without a value will be cleared. Note that all records in the same RRset should be contiguous within the data; if not then the later RRsets will overwrite the earlier one(s) ### clearDNSZone(bytes32 node) `clearDNSZone()` removes all DNS records for the domain. It has function signature `0xad5780af`. Although it is possible to clear records individually with `setDNSRecords()` as described above this requires the owner to know all of the records that have been set (as the resolver has no methods to iterate over the records for a given domain), and might require multiple transactions. `clearDNSZone()` removes all zone information in a single operation. The arguments for the function is as follows: - node: the namehash of the fully-qualified domain in ENS for which to clear the records. Namehashes are defined in [ERC-137](./eip-137.md) ### dnsRecords(bytes32 node, bytes32 name, uint16 resource) view returns (bytes) `dnsRecords()` obtains the DNS records for a given node, name and resource. It has function signature `0x2461e851`. The arguments for the function are as follows: - node: the namehash of the fully-qualified domain in ENS for which to set the records. Namehashes are defined in [ERC-137](./eip-137.md) - name: the `keccak256()` hash of the name of the record in DNS wire format. - resource: the resource record ID. Resource record IDs are defined in RFC1035 and subsequent RFCs. The function returns all matching records in DNS wire format. If there are no records present the function will return nothing. ### hasDNSRecords(bytes32 node, bytes32 name) view returns (bool) `hasDNSRecords()` reports if there are any records for the provided name in the domain. It has function signature `0x4cbf6ba4`. This function is needed by DNS resolvers when working with wildcard resources as defined in RFC4592. The arguments for the function are as follows: - node: the namehash of the fully-qualified domain in ENS for which to set the records. Namehashes are defined in [ERC-137](./eip-137.md) - name: the `keccak256()` hash of the name of the record in DNS wire format. The function returns `true` if there are any records for the provided node and name, otherwise `false`. ## Rationale DNS is a federated system of naming, and the higher-level entities control availability of everything beneath them (_e.g._ `.org` controls the availability of `ethereum.org`). A decentralized version of DNS would not have this constraint, and allow lookups directly for any domain with relevant records within ENS. ## Backwards Compatibility Not applicable. ## Reference Implementation The reference implementation of the DNS resolver is as follows: ```solidity pragma solidity ^0.7.4; import "../ResolverBase.sol"; import "@ensdomains/dnssec-oracle/contracts/RRUtils.sol"; abstract contract DNSResolver is ResolverBase { using RRUtils for *; using BytesUtils for bytes; bytes4 constant private DNS_RECORD_INTERFACE_ID = 0xa8fa5682; bytes4 constant private DNS_ZONE_INTERFACE_ID = 0x5c47637c; // DNSRecordChanged is emitted whenever a given node/name/resource's RRSET is updated. event DNSRecordChanged(bytes32 indexed node, bytes name, uint16 resource, bytes record); // DNSRecordDeleted is emitted whenever a given node/name/resource's RRSET is deleted. event DNSRecordDeleted(bytes32 indexed node, bytes name, uint16 resource); // DNSZoneCleared is emitted whenever a given node's zone information is cleared. event DNSZoneCleared(bytes32 indexed node); // DNSZonehashChanged is emitted whenever a given node's zone hash is updated. event DNSZonehashChanged(bytes32 indexed node, bytes lastzonehash, bytes zonehash); // Zone hashes for the domains. // A zone hash is an ERC-1577 content hash in binary format that should point to a // resource containing a single zonefile. // node => contenthash mapping(bytes32=>bytes) private zonehashes; // Version the mapping for each zone. This allows users who have lost // track of their entries to effectively delete an entire zone by bumping // the version number. // node => version mapping(bytes32=>uint256) private versions; // The records themselves. Stored as binary RRSETs // node => version => name => resource => data mapping(bytes32=>mapping(uint256=>mapping(bytes32=>mapping(uint16=>bytes)))) private records; // Count of number of entries for a given name. Required for DNS resolvers // when resolving wildcards. // node => version => name => number of records mapping(bytes32=>mapping(uint256=>mapping(bytes32=>uint16))) private nameEntriesCount; /** * Set one or more DNS records. Records are supplied in wire-format. * Records with the same node/name/resource must be supplied one after the * other to ensure the data is updated correctly. For example, if the data * was supplied: * a.example.com IN A 1.2.3.4 * a.example.com IN A 5.6.7.8 * www.example.com IN CNAME a.example.com. * then this would store the two A records for a.example.com correctly as a * single RRSET, however if the data was supplied: * a.example.com IN A 1.2.3.4 * www.example.com IN CNAME a.example.com. * a.example.com IN A 5.6.7.8 * then this would store the first A record, the CNAME, then the second A * record which would overwrite the first. * * @param node the namehash of the node for which to set the records * @param data the DNS wire format records to set */ function setDNSRecords(bytes32 node, bytes calldata data) external authorised(node) { uint16 resource = 0; uint256 offset = 0; bytes memory name; bytes memory value; bytes32 nameHash; // Iterate over the data to add the resource records for (RRUtils.RRIterator memory iter = data.iterateRRs(0); !iter.done(); iter.next()) { if (resource == 0) { resource = iter.dnstype; name = iter.name(); nameHash = keccak256(abi.encodePacked(name)); value = bytes(iter.rdata()); } else { bytes memory newName = iter.name(); if (resource != iter.dnstype || !name.equals(newName)) { setDNSRRSet(node, name, resource, data, offset, iter.offset - offset, value.length == 0); resource = iter.dnstype; offset = iter.offset; name = newName; nameHash = keccak256(name); value = bytes(iter.rdata()); } } } if (name.length > 0) { setDNSRRSet(node, name, resource, data, offset, data.length - offset, value.length == 0); } } /** * Obtain a DNS record. * @param node the namehash of the node for which to fetch the record * @param name the keccak-256 hash of the fully-qualified name for which to fetch the record * @param resource the ID of the resource as per https://en.wikipedia.org/wiki/List_of_DNS_record_types * @return the DNS record in wire format if present, otherwise empty */ function dnsRecord(bytes32 node, bytes32 name, uint16 resource) public view returns (bytes memory) { return records[node][versions[node]][name][resource]; } /** * Check if a given node has records. * @param node the namehash of the node for which to check the records * @param name the namehash of the node for which to check the records */ function hasDNSRecords(bytes32 node, bytes32 name) public view returns (bool) { return (nameEntriesCount[node][versions[node]][name] != 0); } /** * Clear all information for a DNS zone. * @param node the namehash of the node for which to clear the zone */ function clearDNSZone(bytes32 node) public authorised(node) { versions[node]++; emit DNSZoneCleared(node); } /** * setZonehash sets the hash for the zone. * May only be called by the owner of that node in the ENS registry. * @param node The node to update. * @param hash The zonehash to set */ function setZonehash(bytes32 node, bytes calldata hash) external authorised(node) { bytes memory oldhash = zonehashes[node]; zonehashes[node] = hash; emit DNSZonehashChanged(node, oldhash, hash); } /** * zonehash obtains the hash for the zone. * @param node The ENS node to query. * @return The associated contenthash. */ function zonehash(bytes32 node) external view returns (bytes memory) { return zonehashes[node]; } function supportsInterface(bytes4 interfaceID) virtual override public pure returns(bool) { return interfaceID == DNS_RECORD_INTERFACE_ID || interfaceID == DNS_ZONE_INTERFACE_ID || super.supportsInterface(interfaceID); } function setDNSRRSet( bytes32 node, bytes memory name, uint16 resource, bytes memory data, uint256 offset, uint256 size, bool deleteRecord) private { uint256 version = versions[node]; bytes32 nameHash = keccak256(name); bytes memory rrData = data.substring(offset, size); if (deleteRecord) { if (records[node][version][nameHash][resource].length != 0) { nameEntriesCount[node][version][nameHash]--; } delete(records[node][version][nameHash][resource]); emit DNSRecordDeleted(node, name, resource); } else { if (records[node][version][nameHash][resource].length == 0) { nameEntriesCount[node][version][nameHash]++; } records[node][version][nameHash][resource] = rrData; emit DNSRecordChanged(node, name, resource, rrData); } } } ``` ## Security Considerations Security of this solution would be dependent on security of the records within the ENS domain. This degenenrates to the security of the key(s) which have authority over that domain. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Add chain id to mixed-case checksum address encoding

Sun, 18 Mar 2018 00:00:00 +0000

## Simple Summary This EIP extends [EIP-55](./eip-55.md) by optionally adding a chain id defined by [EIP-155](./eip-155.md) to the checksum calculation. ## Abstract The [EIP-55](./eip-55.md) was created to prevent users from losing funds by sending them to invalid addresses. This EIP extends [EIP-55](./eip-55.md) to protect users from losing funds by sending them to addresses that are valid but that where obtained from a client of another network.For example, if this EIP is implemented, a wallet can alert the user that is trying to send funds to an Ethereum Testnet address from an Ethereum Mainnet wallet. ## Motivation The motivation of this proposal is to provide a mechanism to allow software to distinguish addresses from different Ethereum based networks. This proposal is necessary because Ethereum addresses are hashes of public keys and do not include any metadata. By extending the [EIP-55](./eip-55.md) checksum algorithm it is possible to achieve this objective. ## Specification Convert the address using the same algorithm defined by [EIP-55](./eip-55.md) but if a registered chain id is provided, add it to the input of the hash function. If the chain id passed to the function belongs to a network that opted for using this checksum variant, prefix the address with the chain id and the `0x` separator before calculating the hash. Then convert the address to hexadecimal, but if the ith digit is a letter (ie. it's one of `abcdef`) print it in uppercase if the 4*ith bit of the calculated hash is 1 otherwise print it in lowercase. ## Rationale Benefits: - By means of a minimal code change on existing libraries, users are protected from losing funds by mixing addresses of different Ethereum based networks. ## Implementation ```python #!/usr/bin/python3 from sha3 import keccak_256 import random """ addr (str): Hexadecimal address, 40 characters long with 2 characters prefix chainid (int): chain id from EIP-155 """ def eth_checksum_encode(addr, chainid=1): adopted_eip1191 = [30, 31] hash_input = str(chainid) + addr.lower() if chainid in adopted_eip1191 else addr[2:].lower() hash_output = keccak_256(hash_input.encode('utf8')).hexdigest() aggregate = zip(addr[2:].lower(),hash_output) out = addr[:2] + ''.join([c.upper() if int(a,16) >= 8 else c for c,a in aggregate]) return out ``` ## Test Cases ```python eth_mainnet = [ "0x27b1fdb04752bbc536007a920d24acb045561c26", "0x3599689E6292b81B2d85451025146515070129Bb", "0x42712D45473476b98452f434e72461577D686318", "0x52908400098527886E0F7030069857D2E4169EE7", "0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed", "0x6549f4939460DE12611948b3f82b88C3C8975323", "0x66f9664f97F2b50F62D13eA064982f936dE76657", "0x8617E340B3D01FA5F11F306F4090FD50E238070D", "0x88021160C5C792225E4E5452585947470010289D", "0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb", "0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB", "0xde709f2102306220921060314715629080e2fb77", "0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359", ] rsk_mainnet = [ "0x27b1FdB04752BBc536007A920D24ACB045561c26", "0x3599689E6292B81B2D85451025146515070129Bb", "0x42712D45473476B98452f434E72461577d686318", "0x52908400098527886E0F7030069857D2E4169ee7", "0x5aaEB6053f3e94c9b9a09f33669435E7ef1bEAeD", "0x6549F4939460DE12611948B3F82B88C3C8975323", "0x66F9664f97f2B50F62d13EA064982F936de76657", "0x8617E340b3D01Fa5f11f306f4090fd50E238070D", "0x88021160c5C792225E4E5452585947470010289d", "0xD1220A0Cf47c7B9BE7a2e6ba89F429762E7B9adB", "0xDBF03B407c01E7CD3cBea99509D93F8Dddc8C6FB", "0xDe709F2102306220921060314715629080e2FB77", "0xFb6916095cA1Df60bb79ce92cE3EA74c37c5d359", ] rsk_testnet = [ "0x27B1FdB04752BbC536007a920D24acB045561C26", "0x3599689e6292b81b2D85451025146515070129Bb", "0x42712D45473476B98452F434E72461577D686318", "0x52908400098527886E0F7030069857D2e4169EE7", "0x5aAeb6053F3e94c9b9A09F33669435E7EF1BEaEd", "0x6549f4939460dE12611948b3f82b88C3c8975323", "0x66f9664F97F2b50f62d13eA064982F936DE76657", "0x8617e340b3D01fa5F11f306F4090Fd50e238070d", "0x88021160c5C792225E4E5452585947470010289d", "0xd1220a0CF47c7B9Be7A2E6Ba89f429762E7b9adB", "0xdbF03B407C01E7cd3cbEa99509D93f8dDDc8C6fB", "0xDE709F2102306220921060314715629080e2Fb77", "0xFb6916095CA1dF60bb79CE92ce3Ea74C37c5D359", ] test_cases = {30 : rsk_mainnet, 31 : rsk_testnet, 1 : eth_mainnet} for chainid, cases in test_cases.items(): for addr in cases: assert ( addr == eth_checksum_encode(addr,chainid) ) ``` ## Usage ### Usage Table | Network | Chain id | Supports this EIP | |-|-|-| | RSK Mainnet | 30 | Yes | | RSK Testnet | 31 | Yes | ### Implementation Table | Project | EIP Usage | Implementation | |-|-|-| | MyCrypto | Yes | [JavaScript](https://github.com/MyCryptoHQ/MyCrypto/blob/develop/common/utils/formatters.ts#L126) | | MyEtherWallet | Yes | [JavaScript](https://github.com/MyEtherWallet/MyEtherWallet/blob/73c4a24f8f67c655749ac990c5b62efd92a2b11a/src/helpers/addressUtils.js#L22) | | Ledger | Yes | [C](https://github.com/LedgerHQ/ledger-app-eth/blob/master/src_common/ethUtils.c#L203) | | Trezor | Yes | [Python](https://github.com/trezor/trezor-core/blob/270bf732121d004a4cd1ab129adaccf7346ff1db/src/apps/ethereum/get_address.py#L32) and [C](https://github.com/trezor/trezor-crypto/blob/4153e662b60a0d83c1be15150f18483a37e9092c/address.c#L62) | | Web3.js | Yes | [JavaScript](https://github.com/ethereum/web3.js/blob/aaf26c8806bc9fb60cf6dcb6658104963c6c7fc7/packages/web3-utils/src/Utils.js#L140) | | EthereumJS-util | Yes | [JavaScript](https://github.com/ethereumjs/ethereumjs-util/pull/204/commits/cdf0b3c996b05ac5b1f758f17ea9f9ed1847c1eb) | | ENS address-encoder | Yes | [TypeScript](https://github.com/ensdomains/address-encoder/commit/5bf53b13fa014646ea28c9e5f937361dc9b40590) | ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Voting Interface

Sun, 08 Jul 2018 00:00:00 +0000

## Abstract This EIP defines an API for implementing voting with smart contracts. This standard provides functionality for voting, viewing vote results, and setting voting status. ## Motivation Voting is one of the earliest examples of EVM programming and is also a key part of DAO and organizational governance processes. We expect many DAOs will ultimately need to leverage voting as an important part of their governance. By creating a voting standard for smart contracts and tokens, we can have the following benefits: ### Benefits of having a standard 1. Allow general UIs and applications to be built on top of a standardized voting interface so that more users can participate, and encourage more dApps and DAOs to think about their governance. 2. Allow delegated voting, smart-contract voting, and automatic voting. 3. Allow voting results to be recorded on-chain in a standard way, and allow DAOs and dApps to honor the voting results programmatically. 4. Allow compatibility with token standards such as [ERC-20](./eip-20.md) and newer standards such as [ERC-777](./eip-777.md), as well as item standards such as [ERC-721](./eip-721.md). 5. Create massive potential for interoperability within Ethereum ecosystems and other systems. 6. Allow setting voting deadlines, determining single or multiple options, and requiring voting order. (The trade-off is interface complexity; we might need an [ERC-20](./eip-20.md)-style approach first and later an [ERC-777](./eip-777.md)-style approach for advanced voting.) 7. Record voting weights based on token amounts. 8. Possibly allow trustworthy, privacy-safe voting and anonymous voting (with the voter address not being associated with the vote they cast, given a list of randomized or obfuscated voting options). 9. Possibly allow rewards based on voting participation or voting results. ### Non-Goal / Out of Scope 1. **Delegation**: We intentionally leave delegation out of scope. A separate EIP could be proposed to address this particular use case. 2. **Eligibility or Weights**: Some implementations may want voting weights or voting eligibility to be configurable. For example, OpenZeppelin's implementation of GovernorBravo uses snapshots. Weight calculations such as quadratic voting are also outside the scope of this EIP. This EIP is intended to be flexible enough for current and future voting-weight calculations. 3. **Proposal**: We intentionally leave proposals out of scope. Proposals are identified by `proposalId`, but the information included in a proposal, whether it is on-chain or off-chain, and whether it is executable are all left out of this proposal. A separate EIP could be proposed to address this particular use case. See one such proposal: [ERC-5247](./eip-5247.md). 4. **Signature Aggregations / Endorsement**: When implementing contracts want to allow users to submit their vote or vote approval offline and have another account generate the transaction, signature aggregations or endorsements are outside the scope of this EIP. A separate EIP could be proposed to address this particular use case. See one such proposal here: [ERC-5453](./eip-5453.md). ### Use-cases 1. Decide on issuing a new token, issuing more tokens, or issuing a sub-token. 2. Decide on creating a new item under [ERC-721](./eip-721.md). 3. Decide on electing a certain person or smart contract to be the delegated leader for a project or subproject. 4. Decide on audit-result ownership that allows migration of a smart-contract proxy address. ## Specification 1. Compliant contracts MUST implement the `IERC1202Core` below ```solidity interface IERC1202Core { event VoteCast( address indexed voter, uint256 indexed proposalId, uint8 support, uint256 weight, string reason, bytes extraParams ); function castVote( uint256 proposalId, uint8 support, uint256 weight, string calldata reasonUri, bytes calldata extraParams ) external payable returns; function castVoteFrom( address from, uint256 proposalId, uint8 support, uint256 weight, string calldata reasonUri, bytes calldata extraParams ) external payable returns; function execute(uint256 proposalId, bytes memory extraParams) payable external; } ``` 2. Compliant contracts MAY implement the `IERC1202MultiVote` Interface. If the intention is for multi-options to be supported, e.g. for ranked-choices or variant weights voting, Compliant contracts MUST implement `IERC1202MultiVote` Interface. ```solidity interface IERC1202MultiVote { event MultiVoteCast( address indexed voter, uint256 indexed proposalId, uint8[] support, uint256[] weight, string reason, bytes extraParams ); function castMultiVote( uint256 proposalId, uint8[] support, uint256[] weight, string calldata reasonUri, bytes calldata extraParams ) external payable; } ``` 3. The compliant contract SHOULD implement the [ERC-5269](./eip-5269.md) interface. ### Getting Info: Voting Period, Eligibility, Weight ```solidity interface IERC1202Info { function votingPeriodFor(uint256 proposalId) external view returns (uint256 startPointOfTime, uint256 endPointOfTime); function eligibleVotingWeight(uint256 proposalId, address voter) external view returns (uint256); } ``` ## Rationale We made the following design decisions, and here are the rationales. ### Granularity and Anonymity We created a `view` function, `ballotOf`, primarily to make it easier for people to check the vote from a certain address. This has the following assumptions: - It is possible to check someone's vote directly given an address. If implementers do not want to make this so easy, they can simply reject all calls to this function. We want to make sure that we support both anonymous and non-anonymous voting. However, since all calls to a smart contract are logged in block history, there is not much secrecy unless cryptographic techniques are used. I am not sufficiently cryptography-savvy to comment on that possibility. Please see "Second Feedback Questions 2018" for a related topic. - It assumes that each individual address can vote for only one decision. Users can distribute their available voting power at a more granular level. If implementers want to allow this, they can ask the user to create another wallet address and grant that new address a certain amount of power. For example, in token-based voting where voting weight is determined by the amount of tokens held by a voter, a voter who wants to distribute their voting power across two different options (or option sets) can transfer some of the tokens to the new account and cast votes from both accounts. ### Weights We assume votes have `weight`, which can be checked by calling `eligibleVotingWeight(proposalId, address voter)`, and that the weight distribution is either determined internally or set by the constructor. ## Backwards Compatibility 1. The `support` options are chosen to be `uint8` for the purpose of being backward-compatible with GovernorBravo. This can be increased in the future. ## Security Considerations We expect the voting standard to be used in connection with other contracts such as token distributions, actions conducted by consensus or on behalf of an entity, multi-signature wallets, and similar systems. The major security consideration is ensuring that the standard interface is used only for performing downstream actions or receiving upstream input (vote casting). We expect future audit tools to be based on standard interfaces. It is also important to note, as discussed in this standard, that for the sake of simplicity this EIP is kept in a very basic form. It can be extended to support many different implementation variations. Such variations might contain different assumptions about the behavior and interpretation of actions. One example is: what does it mean if someone votes multiple times through `vote`? - Would that mean the voter is increasing their weight? - Would that mean they vote for multiple options in the meantime? - Does the latter vote override the previous vote? Because of the flexible nature of voting, we expect that many subsequent standards will need to be created as extensions of this EIP. We suggest that any extension or implementation of this standard be thoroughly audited before being included in large-scale or high-asset-volume applications. The third consideration is non-triviality. Some voting applications assume **_anonymity_**, **_randomness_**, **_time-based deadline_**, **_ordering_**, etc. These requirements are known to be non-trivial to achieve on Ethereum. We suggest that any applications or organizations rely on audited and time-proven shared libraries when these requirements need to be enforced in their applications. The fourth consideration is potential abuse. When voting is standardized and put on-chain, it is possible to write another contract that rewards a voter for voting in a certain way. This creates potential issues of bribery and conflict-of-interest abuse that were previously hard to implement. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

ERC-1203 Multi-Class Token Standard (ERC-20 Extension)

Sun, 01 Jul 2018 00:00:00 +0000

## Simple Summary A standard interface for multi-class tokens (MCTs). ## Abstract The following standard allows for the implementation of a standard API for MCTs within smart contracts. This standard provides basic functionality to track, transfer, and convert MCTs. ## Motivation This standard is heavily inspired by ERC-20 Token Standard and ERC-721 Non-Fungible Token Standard. However, whereas these standards are chiefly concerned with representation of items/value in a single class, fungible or note, this proposed standard focus on that of a more complexed, multi-class system. It is fair to think of MCTs as a hybrid of fungible tokens (FT) and non-fungible tokens (NFTs), that is tokens are fungible within the same class but non-fungible with that from a different class. And conversions between classes may be optionally supported. MCTs are useful in representing various structures with heterogeneous components, such as: - **Abstract Concepts:** A company may have different classes of stocks (e.g. senior preferred, junior preferred, class A common, class B common) that together make up its outstanding equities. A shareholder's position of such company composites of zero or more shares in each class. - **Virtual Items:** A sandbox computer game may have many types of resources (e.g. rock, wood, berries, cows, meat, knife, etc.) that together make up that virtual world. A player's inventory has any combination and quantity of these resources - **Physical Items:** A supermarket may have many SKUs it has available for purchase (e.g. eggs, milk, beef jerky, beer, etc.). Things get added or removed from a shopper's cart as it moves down the aisle. It's sometimes possible, especially with regard to abstract concepts or virtual items, to convert from one class to another, at a specified conversion ratio. When it comes to physical items, such conversion essentially is the implementation of bartering. Though it might generally be easier to introduce a common intermediary class, i.e. money. ## Specification ```solidity contract ERC20 { function totalSupply() public view returns (uint256); function balanceOf(address _owner) public view returns (uint256); function transfer(address _to, uint256 _value) public returns (bool); function approve(address _spender, uint256 _value) public returns (bool); function allowance(address _owner, address _spender) public view returns (uint256); function transferFrom(address _from, address _to, uint256 _value) public returns (bool); event Transfer(address indexed _from, address indexed _to, uint256 _value); event Approval(address indexed _owner, address indexed _spender, uint256 _value); } contract ERC1203 is ERC20 { function totalSupply(uint256 _class) public view returns (uint256); function balanceOf(address _owner, uint256 _class) public view returns (uint256); function transfer(address _to, uint256 _class, uint256 _value) public returns (bool); function approve(address _spender, uint256 _class, uint256 _value) public returns (bool); function allowance(address _owner, address _spender, uint256 _class) public view returns (uint256); function transferFrom(address _from, address _to, uint256 _class, uint256 _value) public returns (bool); function fullyDilutedTotalSupply() public view returns (uint256); function fullyDilutedBalanceOf(address _owner) public view returns (uint256); function fullyDilutedAllowance(address _owner, address _spender) public view returns (uint256); function convert(uint256 _fromClass, uint256 _toClass, uint256 _value) public returns (bool); event Transfer(address indexed _from, address indexed _to, uint256 _class, uint256 _value); event Approval(address indexed _owner, address indexed _spender, uint256 _class, uint256 _value); event Convert(uint256 indexed _fromClass, uint256 indexed _toClass, uint256 _value); } ``` ### ERC-20 Methods and Events (fully compatible) Please see [ERC-20 Token Standard](./eip-20.md) for detailed specifications. Do note that these methods and events only work on the "default" class of an MCT. ```solidity function totalSupply() public view returns (uint256); function balanceOf(address _owner) public view returns (uint256); function transfer(address _to, uint256 _value) public returns (bool); function approve(address _spender, uint256 _value) public returns (bool); function allowance(address _owner, address _spender) public view returns (uint256); function transferFrom(address _from, address _to, uint256 _value) public returns (bool); event Transfer(address indexed _from, address indexed _to, uint256 _value); event Approval(address indexed _owner, address indexed _spender, uint256 _value); ``` ### Tracking and Transferring **totalSupply** Returns the total number of tokens in the specified `_class` ```solidity function totalSupply(uint256 _class) public view returns (uint256); ``` **balanceOf** Returns the number of tokens of a specified `_class` that the `_owner` has ```solidity function balanceOf(address _owner, uint256 _class) public view returns (uint256); ``` **transfer** Transfer `_value` tokens of `_class` to address specified by `_to`, return `true` if successful ```solidity function transfer(address _to, uint256 _class, uint256 _value) public returns (bool); ``` **approve** Grant `_spender` the right to transfer `_value` tokens of `_class`, return `true` if successful ```solidity function approve(address _spender, uint256 _class, uint256 _value) public returns (bool); ``` **allowance** Return the number of tokens of `_class` that `_spender` is authorized to transfer on the behalf of `_owner` ```solidity function allowance(address _owner, address _spender, uint256 _class) public view returns (uint256); ``` **transferFrom** Transfer `_value` tokens of `_class` from address specified by `_from` to address specified by `_to` as previously approved, return `true` if successful ```solidity function transferFrom(address _from, address _to, uint256 _class, uint256 _value) public returns (bool); ``` **Transfer** Triggered when tokens are transferred or created, including zero value transfers ```solidity event Transfer(address indexed _from, address indexed _to, uint256 _class, uint256 _value); ``` **Approval** Triggered on successful `approve` ```solidity event Approval(address indexed _owner, address indexed _spender, uint256 _class, uint256 _value); ``` ### Conversion and Dilution **fullyDilutedTotalSupply** Return the total token supply as if all converted to the lowest common denominator class ```solidity function fullyDilutedTotalSupply() public view returns (uint256); ``` **fullyDilutedBalanceOf** Return the total token owned by `_owner` as if all converted to the lowest common denominator class ```solidity function fullyDilutedBalanceOf(address _owner) public view returns (uint256); ``` **fullyDilutedAllowance** Return the total token `_spender` is authorized to transfer on behalf of `_owner` as if all converted to the lowest common denominator class ```solidity function fullyDilutedAllowance(address _owner, address _spender) public view returns (uint256); ``` **convert** Convert `_value` of `_fromClass` to `_toClass`, return `true` if successful ```solidity function convert(uint256 _fromClass, uint256 _toClass, uint256 _value) public returns (bool); ``` **Conversion** Triggered on successful `convert` ```solidity event Conversion(uint256 indexed _fromClass, uint256 indexed _toClass, uint256 _value); ``` ## Rationale This standard purposely extends ERC-20 Token Standard so that new MCTs following or existing ERC-20 tokens extending this standard are fully compatible with current wallets and exchanges. In addition, new methods and events are kept as closely to ERC-20 conventions as possible for ease of adoption. We have considered alternative implementations to support the multi-class structure, as discussed below, and we found current token standards incapable or inefficient in deal with such structures. **Using multiple ERC-20 tokens** It is certainly possible to create an ERC-20 token for each class, and a separate contract to coordinate potential conversions, but the short coming in this approach is clearly evident. The rationale behind this standard is to have a single contract to manage multiple classes of tokens. **Shoehorning ERC-721 token** Treating each token as unique, the non-fungible token standard offers maximum representational flexibility arguably at the expense of convenience. The main challenge of using ERC-721 to represent multi-class token is that separate logic is required to keep track of which tokens belongs to which class, a hacky and unnecessary endeavor. **Using ERC-1178 token** We came across ERC-1178 as we were putting final touches on our own proposal. The two ERCs look very similar on the surface but we believe there're a few key advantages this one has over ERC-1178. - ERC-1178 offers no backward compatibility whereas this proposal is an extension of ERC-20 and therefore fully compatible with all existing wallets and exchanges - By the same token, existing ERC-20 contracts can extend themselves to adopt this standard and support additional classes without affecting their current behaviors - This proposal introduces the concept of cross class conversion and dilution, making each token class integral part of a whole system rather than many silos ## Backwards Compatibility This EIP is fully compatible with the mandatory methods of ERC20 Token Standard so long as the implementation includes a "lowest common denominator" class, which may be class B common/gold coin/money in the abstract/virtual/physical examples above respectively. Where it is not possible to implement such class, then the implementation should specify a default class for tracking or transferring unless otherwise specified, e.g. US dollar is transferred unless other currency is explicitly specified. We find it contrived to require the optional methods of ERC20 Token Standard, `name()`, `symbol()`, and `decimals()`, but developers are certainly free to implement these as they wish. ## Test Cases The repository at [jeffishjeff/ERC-1203](https://github.com/jeffishjeff/ERC-1203) contains the [sample test cases](https://github.com/jeffishjeff/ERC-1203/blob/master/token.test.js). ## Implementation The repository at [jeffishjeff/ERC-1203](https://github.com/jeffishjeff/ERC-1203) contains the [sample implementation](https://github.com/jeffishjeff/ERC-1203/blob/master/token.sol). ## References - ERC-20 Token Standard. ./eip-20.md - ERC-721 Non-Fungible Token Standard. ./eip-721.md - ERC-1178 Multi-class Token Standard. ./eip-1178.md ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

DAuth Access Delegation Standard

Tue, 10 Jul 2018 00:00:00 +0000

DAuth Access Delegation Standard ===== ## Simple Summary DAuth is a standard interface for accessing authorization delegation between smart contracts and users. ## Abstract The DAuth protocol defines a set of standard API allowing identity delegations between smart contracts without the user's private key. Identity delegations include accessing and operating a user's data and assets contained in the delegated contracts. ## Motivation The inspiration for designing DAuth comes from OAuth protocol that is extensively used in web applications. But unlike the centralized authorization of OAuth, DAuth works in a distributed manner, thus providing much more reliability and generality. ## Specification ![Rationale](../assets/eip-1207/rationale.png) **Resource owner**: the authorizer **Resource contract**: the contract providing data and operators **API**: the resource contract APIs that the grantee contract can invoke **Client contract**: the grantee contract using authorization to access and operate the data **Grantee request**: the client contract calls the resource contract with the authorizer authorization **AuthInfo** ``` js struct AuthInfo { string[] funcNames; uint expireAt; } ``` Required - The struct contains user authorization information * `funcNames`: a list of function names callable by the granted contract * `expireAt`: the authorization expire timestamp in seconds **userAuth** ``` js mapping(address => mapping(address => AuthInfo)) userAuth; ``` Required - userAuth maps (authorizer address, grantee contract address) pair to the user’s authorization AuthInfo object **callableFuncNames** ``` js string[] callableFuncNames; ``` Required - All methods that are allowed other contracts to call * The callable function MUST verify the grantee’s authorization **updateCallableFuncNames** ``` js function updateCallableFuncNames(string _invokes) public returns (bool success); ``` Optional - Update the callable function list for the client contract by the resource contract's administrator * `_invokes`: the invoke methods that the client contract can call * return: Whether the callableFuncNames is updated or not * This method MUST return success or throw, no other outcomes can be possible **verify** ``` js function verify(address _authorizer, string _invoke) internal returns (bool success); ``` Required - check the invoke method authority for the client contract * `_authorizer`: the user address that the client contract agents * `_invoke`: the invoke method that the client contract wants to call * return: Whether the grantee request is authorized or not * This method MUST return success or throw, no other outcomes can be possible **grant** ``` js function grant(address _grantee, string _invokes, uint _expireAt) public returns (bool success); ``` Required - delegate a client contract to access the user's resource * `_grantee`: the client contract address * `_invokes`: the callable methods that the client contract can access. It is a string which contains all function names split by spaces * `_expireAt`: the authorization expire timestamp in seconds * return: Whether the grant is successful or not * This method MUST return success or throw, no other outcomes can be possible * A successful grant MUST fire the Grant event(defined below) **regrant** ``` js function regrant(address _grantee, string _invokes, uint _expireAt) public returns (bool success); ``` Optional - alter a client contract's delegation **revoke** ``` js function revoke(address _grantee) public returns (bool success); ``` Required - delete a client contract's delegation * `_grantee`: the client contract address * return: Whether the revoke is successful or not * A successful revoke MUST fire the Revoke event(defined below). **Grant** ``` js event Grant(address _authorizer, address _grantee, string _invokes, uint _expireAt); ``` * This event MUST trigger when the authorizer grant a new authorization when `grant` or `regrant` processes successfully **Revoke** ``` js event Revoke(address _authorizer, address _grantee); ``` * This event MUST trigger when the authorizer revoke a specific authorization successfully **Callable Resource Contract Functions** All public or external functions that are allowed the grantee to call MUST use overload to implement two functions: The First one is the standard method that the user invokes directly, the second one is the grantee methods of the same function name with one more authorizer address parameter. Example: ``` js function approve(address _spender, uint256 _value) public returns (bool success) { return _approve(msg.sender, _spender, _value); } function approve(address _spender, uint256 _value, address _authorizer) public returns (bool success) { verify(_authorizer, "approve"); return _approve(_authorizer, _spender, _value); } function _approve(address sender, address _spender, uint256 _value) internal returns (bool success) { allowed[sender][_spender] = _value; emit Approval(sender, _spender, _value); return true; } ``` ## Rationale **Current Limitations** The current design of many smart contracts only considers the user invokes the smart contract functions by themselves using the private key. However, in some case, the user wants to delegate other client smart contracts to access and operate their data or assets in the resource smart contract. There isn’t a common protocol to provide a standard delegation approach. **Rationale** On the Ethereum platform, all storage is transparent and the `msg.sender` is reliable. Therefore, the DAuth don't need an `access_token` like OAuth. DAuth just recodes the users' authorization for the specific client smart contract's address. It is simple and reliable on the Ethereum platform. ## Backwards Compatibility This EIP introduces no backward compatibility issues. In the future, the new version protocol has to keep these interfaces. ## Implementation Following is the DAuth Interface implementation. Furthermore, the example implementations of EIP20 Interface and ERC-DAuth Interface are also provided. Developers can easily implement their own contracts with ERC-DAuth Interface and other EIP. * ERC-DAuth Interface implementation is available at: https://github.com/DIA-Network/ERC-DAuth/blob/master/ERC-DAuth-Interface.sol * Example implementation with EIP20 Interface and ERC-DAuth Interface is available at: https://github.com/DIA-Network/ERC-DAuth/blob/master/eip20-dauth-example/EIP20DAuth.sol ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Membership Verification Token (MVT)

Sat, 14 Jul 2018 00:00:00 +0000

## Simple Summary A standard interface for Membership Verification Token(MVT). ## Abstract The following standard allows for the implementation of a standard API for Membership Verification Token within smart contracts(called entities). This standard provides basic functionality to track membership of individuals in certain on-chain ‘organizations’. This allows for several use cases like automated compliance, and several forms of governance and membership structures. We considered use cases of MVTs being assigned to individuals which are non-transferable and revocable by the owner. MVTs can represent proof of recognition, proof of membership, proof of right-to-vote and several such otherwise abstract concepts on the blockchain. The following are some examples of those use cases, and it is possible to come up with several others: - Voting: Voting is inherently supposed to be a permissioned activity. So far, onchain voting systems are only able to carry out voting with coin balance based polls. This can now change and take various shapes and forms. - Passport issuance, social benefit distribution, Travel permit issuance, Drivers licence issuance are all applications which can be abstracted into membership, that is belonging of an individual to a small set, recognized by some authority as having certain entitlements, without needing any individual specific information(right to welfare, freedom of movement, authorization to operate vehicles, immigration) - Investor permissioning: Making regulatory compliance a simple on chain process. Tokenization of securities, that are streamlined to flow only to accredited addresses, tracing and certifying on chain addresses for AML purposes. - Software licencing: Software companies like game developers can use the protocol to authorize certain hardware units(consoles) to download and use specific software(games) In general, an individual can have different memberships in their day to day life. The protocol allows for the creation of software that puts everything all at one place. Their identity can be verified instantly. Imagine a world where you don't need to carry a wallet full of identity cards (Passport, gym membership, SSN, Company ID etc) and organizations can easily keep track of all its members. Organizations can easily identify and disallow fake identities. Attributes are a huge part of ERC-1261 which help to store identifiable information regarding its members. Polls can make use of attributes to calculate the voterbase. E.g: Users should belong to USA entity and not belong to Washington state attribute to be a part of a poll. There will exist a mapping table that maps attribute headers to an array of all possible attributes. This is done in order to subdivide entities into subgroups which are exclusive and exhaustive. For example, header: blood group alphabet Array: [ o, a, b, ab ] header: blood group sign Array: [ +, - ] NOT an example of exclusive exhaustive: Header: video subscription Array: [ Netflix, HBO, Amazon ] Because a person is not necessitated to have EXACTLY one of the elements. He or she may have none or more than one. ## Motivation A standard interface allows any user, applications to work with any MVT on Ethereum. We provide for simple ERC-1261 smart contracts. Additional applications are discussed below. This standard is inspired from the fact that voting on the blockchain is done with token balance weights. This has been greatly detrimental to the formation of flexible governance systems on the blockchain, despite the tremendous governance potential that blockchains offer. The idea was to create a permissioning system that allows organizations to vet people once into the organization on the blockchain, and then gain immense flexibility in the kind of governance that can be carried out. We have also reviewed other Membership EIPs including EIP-725/735 Claim Registry. A significant difference between #735 claims and #1261 MVTs is information ownership. In #735 the Claim Holder owns any claims made about themselves. The problem with this is that there is no way for a Claim Issuer to revoke or alter a claim once it has been issued. While #735 does specify a removeClaim method, a malicious implementation could simply ignore that method call, because they own the claim. Imagine that SafeEmploy™, a background checking company, issues a claim about Timmy. The claim states that Timmy has never been convicted of any felonies. Timmy makes some bad decisions, and now that claim is no longer true. SafeEmploy™ executes removeClaim, but Timmy's #735 contract just ignores it, because Timmy wants to stay employed (and is crypto-clever). #1261 MVTs do not have this problem. Ownership of a badge/claim is entirely determined by the contract issuing the badges, not the one receiving them. The issuer is free to remove or change those badges as they see fit. **Trade-off between trustlessness and usability:** To truly understand the value of the protocol, it is important to understand the trade-off we are treading on. The MVT contract allows the creator to revoke the token, and essentially confiscate the membership of the member in question. To some, this might seem like an unacceptable flaw, however this is a design choice, and not a flaw. The choice may seem to place a great amount of trust in the individuals who are managing the entity contract(entity owners). If the interests of the entity owner conflict with the interests of the members, the owner may resort to addition of fake addresses(to dominate consensus) or evicting members(to censor unfavourable decisions). At first glance this appears to be a major shortcomings, because the blockchain space is used to absolute removal of authority in most cases. Even the official definition of a dapp requires the absence of any party that manages the services provided by the application. However, the trust in entity owners is not misplaced, if it can be ensured that the interests of entity owners are aligned with the interests of members. Another criticism of such a system would be that the standard edge of blockchain intermediation - “you cannot bribe the system if you don’t know who to bribe” - no longer holds. It is possible to bribe an entity owner into submission, and get them to censor or fake votes. There are several ways to respond to this argument. First of all, all activities, such as addition of members, and removal of members can be tracked on the blockchain and traces of such activity cannot be removed. It is not difficult to build analytics tools to detect malicious activity(adding 100 fake members suddenly who vote in the direction/sudden removal of a number of members voting in a certain direction). Secondly, the entity owners’ power is limited to the addition and removal of members. This means that they cannot tamper any votes. They can only alter the counting system to include fake voters or remove real voters. Any sensible auditor can identify the malicious/victim addresses and create an open source audit tool to find out the correct results. The biggest loser in this attack will be the entity owner, who has a reputation to lose. Finally, one must understand why we are taking a step away from trustlessness in this trade-off. The answer is usability. Introducing a permissioning system expands the scope of products and services that can be delivered through the blockchain, while leveraging other aspects of the blockchain(cheap, immutable, no red-tape, secure). Consider the example of the driver licence issuing agency using the ERC-1300 standard. This is a service that simply cannot be deployed in a completely trustless environment. The introduction of permissioned systems expanded the scope of services on the blockchain to cover this particular service. Sure, they have the power to revoke a person’s licence for no reason. But will they? Who stands to lose the most, if the agency acts erratically? The agency itself. Now consider the alternative, the way licences(not necessarily only drivers licence, but say shareholder certificates and so on) are issued, the amount of time consumed, the complete lack of transparency. One could argue that if the legacy systems providing these services really wanted to carry out corruption and nepotism in the execution of these services, the present systems make it much easier to do so. Also, they are not transparent, meaning that there is no way to even detect if they act maliciously. All that being said, we are very excited to share our proposal with the community and open up to suggestions in this space. ## Specification The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. **Every ERC-1261 compliant contract must implement the `ERC1261`, `ERC173` and `ERC165` interfaces** (subject to "caveats" below): ```solidity /// @title ERC-1261 MVT Standard /// @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1261.md /// The constructor should define the attribute set for this MVT. /// Note: the ERC-165 identifier for this interface is 0x1d8362cf. interface IERC1261 {/* is ERC173, ERC165 */ /// @dev This emits when a token is assigned to a member. event Assigned(address indexed _to, uint[] attributeIndexes); /// @dev This emits when a membership is revoked. event Revoked(address indexed _to); /// @dev This emits when a user forfeits his membership event Forfeited(address indexed _to); /// @dev This emits when a membership request is accepted event ApprovedMembership(address indexed _to, uint[] attributeIndexes); /// @dev This emits when a membership is requested by an user event RequestedMembership(address indexed _to); /// @dev This emits when data of a member is modified. /// Doesn't emit when a new membership is created and data is assigned. event ModifiedAttributes(address indexed _to, uint attributeIndex, uint attributeValueIndex); /// @notice Adds a new attribute (key, value) pair to the set of pre-existing attributes. /// @dev Adds a new attribute at the end of the array of attributes and maps it to `values`. /// Contract can set a max number of attributes and throw if limit is reached. /// @param _name Name of the attribute which is to be added. /// @param values List of values of the specified attribute. function addAttributeSet(bytes32 _name, bytes32[] calldata values) external; /// @notice Modifies the attribute value of a specific attribute for a given `_to` address. /// @dev Use appropriate checks for whether a user/admin can modify the data. /// Best practice is to use onlyOwner modifier from ERC173. /// @param _to The address whose attribute is being modified. /// @param _attributeIndex The index of attribute which is being modified. /// @param _modifiedValueIndex The index of the new value which is being assigned to the user attribute. function modifyAttributeByIndex(address _to, uint _attributeIndex, uint _modifiedValueIndex) external; /// @notice Requests membership from any address. /// @dev Throws if the `msg.sender` already has the token. /// The individual `msg.sender` can request for a membership if some existing criteria are satisfied. /// When a membership is requested, this function emits the RequestedMembership event. /// dev can store the membership request and use `approveRequest` to assign membership later /// dev can also oraclize the request to assign membership later /// @param _attributeIndexes the attribute data associated with the member. /// This is an array which contains indexes of attributes. function requestMembership(uint[] calldata _attributeIndexes) external payable; /// @notice User can forfeit his membership. /// @dev Throws if the `msg.sender` already doesn't have the token. /// The individual `msg.sender` can revoke his/her membership. /// When the token is revoked, this function emits the Revoked event. function forfeitMembership() external payable; /// @notice Owner approves membership from any address. /// @dev Throws if the `_user` doesn't have a pending request. /// Throws if the `msg.sender` is not an owner. /// Approves the pending request /// Make oraclize callback call this function /// When the token is assigned, this function emits the `ApprovedMembership` and `Assigned` events. /// @param _user the user whose membership request will be approved. function approveRequest(address _user) external; /// @notice Owner discards membership from any address. /// @dev Throws if the `_user` doesn't have a pending request. /// Throws if the `msg.sender` is not an owner. /// Discards the pending request /// Make oraclize callback call this function if criteria are not satisfied /// @param _user the user whose membership request will be discarded. function discardRequest(address _user) external; /// @notice Assigns membership of an MVT from owner address to another address. /// @dev Throws if the member already has the token. /// Throws if `_to` is the zero address. /// Throws if the `msg.sender` is not an owner. /// The entity assigns the membership to each individual. /// When the token is assigned, this function emits the Assigned event. /// @param _to The address to which the token is assigned. /// @param _attributeIndexes The attribute data associated with the member. /// This is an array which contains indexes of attributes. function assignTo(address _to, uint[] calldata _attributeIndexes) external; /// @notice Only Owner can revoke the membership. /// @dev This removes the membership of the user. /// Throws if the `_from` is not an owner of the token. /// Throws if the `msg.sender` is not an owner. /// Throws if `_from` is the zero address. /// When transaction is complete, this function emits the Revoked event. /// @param _from The current owner of the MVT. function revokeFrom(address _from) external; /// @notice Queries whether a member is a current member of the organization. /// @dev MVT's assigned to the zero address are considered invalid, and this /// function throws for queries about the zero address. /// @param _to An address for whom to query the membership. /// @return Whether the member owns the token. function isCurrentMember(address _to) external view returns (bool); /// @notice Gets the value collection of an attribute. /// @dev Returns the values of attributes as a bytes32 array. /// @param _name Name of the attribute whose values are to be fetched /// @return The values of attributes. function getAttributeExhaustiveCollection(bytes32 _name) external view returns (bytes32[] memory); /// @notice Returns the list of all past and present members. /// @dev Use this function along with isCurrentMember to find wasMemberOf() in Js. /// It can be calculated as present in getAllMembers() and !isCurrentMember(). /// @return List of addresses who have owned the token and currently own the token. function getAllMembers() external view returns (address[]); /// @notice Returns the count of all current members. /// @dev Use this function in polls as denominator to get percentage of members voted. /// @return Count of current Members. function getCurrentMemberCount() external view returns (uint); /// @notice Returns the list of all attribute names. /// @dev Returns the names of attributes as a bytes32 array. /// AttributeNames are stored in a bytes32 Array. /// Possible values for each attributeName are stored in a mapping(attributeName => attributeValues). /// AttributeName is bytes32 and attributeValues is bytes32[]. /// Attributes of a particular user are stored in bytes32[]. /// Which has a single attributeValue for each attributeName in an array. /// Use web3.toAscii(data[0]).replace(/\u0000/g, "") to convert to string in JS. /// @return The names of attributes. function getAttributeNames() external view returns (bytes32[] memory); /// @notice Returns the attributes of `_to` address. /// @dev Throws if `_to` is the zero address. /// Use web3.toAscii(data[0]).replace(/\u0000/g, "") to convert to string in JS. /// @param _to The address whose current attributes are to be returned. /// @return The attributes associated with `_to` address. function getAttributes(address _to) external view returns (bytes32[]); /// @notice Returns the `attribute` stored against `_to` address. /// @dev Finds the index of the `attribute`. /// Throws if the attribute is not present in the predefined attributes. /// Returns the attributeValue for the specified `attribute`. /// @param _to The address whose attribute is requested. /// @param _attributeIndex The attribute Index which is required. /// @return The attribute value at the specified name. function getAttributeByIndex(address _to, uint _attributeIndex) external view returns (bytes32); } interface ERC173 /* is ERC165 */ { /// @dev This emits when ownership of a contract changes. event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); /// @notice Get the address of the owner /// @return The address of the owner. function owner() external view; /// @notice Set the address of the new owner of the contract /// @param _newOwner The address of the new owner of the contract function transferOwnership(address _newOwner) external; } interface ERC165 { /// @notice Query if a contract implements an interface /// @param interfaceID The interface identifier, as specified in ERC-165 /// @dev Interface identification is specified in ERC-165. This function /// uses less than 30,000 gas. /// @return `true` if the contract implements `interfaceID` and /// `interfaceID` is not 0xffffffff, `false` otherwise function supportsInterface(bytes4 interfaceID) external view returns (bool); } ``` The **metadata extension** is OPTIONAL for ERC-1261 smart contracts (see "caveats", below). This allows your smart contract to be interrogated for its name and for details about the organization which your MV tokens represent. ```solidity /// @title ERC-1261 MVT Standard, optional metadata extension /// @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1261.md interface ERC1261Metadata /* is ERC1261 */ { /// @notice A descriptive name for a collection of MVTs in this contract function name() external view returns (string _name); /// @notice An abbreviated name for MVTs in this contract function symbol() external view returns (string _symbol); } ``` This is the "ERC1261 Metadata JSON Schema" referenced above. ```json { "title": "Organization Metadata", "type": "object", "properties": { "name": { "type": "string", "description": "Identifies the organization to which this MVT represents" }, "description": { "type": "string", "description": "Describes the organization to which this MVT represents" } } } ``` ### Caveats The 0.4.24 Solidity interface grammar is not expressive enough to document the ERC-1261 standard. A contract which complies with ERC-1261 MUST also abide by the following: - Solidity issue #3412: The above interfaces include explicit mutability guarantees for each function. Mutability guarantees are, in order weak to strong: `payable`, implicit nonpayable, `view`, and `pure`. Your implementation MUST meet the mutability guarantee in this interface and you MAY meet a stronger guarantee. For example, a `payable` function in this interface may be implemented as nonpayble (no state mutability specified) in your contract. We expect a later Solidity release will allow your stricter contract to inherit from this interface, but a workaround for version 0.4.24 is that you can edit this interface to add stricter mutability before inheriting from your contract. - Solidity issue #3419: A contract that implements `ERC1261Metadata` SHALL also implement `ERC1261`. - Solidity issue #2330: If a function is shown in this specification as `external` then a contract will be compliant if it uses `public` visibility. As a workaround for version 0.4.24, you can edit this interface to switch to `public` before inheriting from your contract. - Solidity issues #3494, #3544: Use of `this.*.selector` is marked as a warning by Solidity, a future version of Solidity will not mark this as an error. _If a newer version of Solidity allows the caveats to be expressed in code, then this EIP MAY be updated and the caveats removed, such will be equivalent to the original specification._ ## Rationale There are many potential uses of Ethereum smart contracts that depend on tracking membership. Examples of existing or planned MVT systems are Vault, a DAICO platform, and Stream, a security token framework. Future uses include the implementation of direct democracy, in-game memberships and badges, licence and travel document issuance, electronic voting machine trails, software licencing and many more. **MVT Word Choice:** Since the tokens are non transferable and revocable, they function like membership cards. Hence the word membership verification token. **Transfer Mechanism** MVTs can't be transferred. This is a design choice, and one of the features that distinguishes this protocol. Any member can always ask the issuer to revoke the token from an existing address and assign to a new address. One can think of the set of MVTs as identifying a user, and you cannot split the user into parts and have it be the same user, but you can transfer a user to a new private key. **Assign and Revoke mechanism** The assign and revoke functions' documentation only specify conditions when the transaction MUST throw. Your implementation MAY also throw in other situations. This allows implementations to achieve interesting results: - **Disallow additional memberships after a condition is met** — Sample contract available on GitHub - **Blacklist certain address from receiving MV tokens** — Sample contract available on GitHub - **Disallow additional memberships after a certain time is reached** — Sample contract available on GitHub - **Charge a fee to user of a transaction** — require payment when calling `assign` and `revoke` so that condition checks from external sources can be made **ERC-173 Interface** We chose Standard Interface for Ownership (ERC-173) to manage the ownership of a ERC-1261 contract. A future EIP/ Zeppelin may create a multi-ownable implementation for ownership. We strongly support such an EIP and it would allow your ERC-1261 implementation to implement `ERC1261Metadata`, or other interfaces by delegating to a separate contract. **ERC-165 Interface** We chose Standard Interface Detection (ERC-165) to expose the interfaces that a ERC-1261 smart contract supports. A future EIP may create a global registry of interfaces for contracts. We strongly support such an EIP and it would allow your ERC-1261 implementation to implement `ERC1261Metadata`, or other interfaces by delegating to a separate contract. **Gas and Complexity** (regarding the enumeration extension) This specification contemplates implementations that manage a few and _arbitrarily large_ numbers of MVTs. If your application is able to grow then avoid using for/while loops in your code. These indicate your contract may be unable to scale and gas costs will rise over time without bound **Privacy** Personal information: The protocol does not put any personal information on to the blockchain, so there is no compromise of privacy in that respect. Membership privacy: The protocol by design, makes it public which addresses are/aren’t members. Without making that information public, it would not be possible to independently audit governance activity or track admin(entity owner) activity. **Metadata Choices** (metadata extension) We have required `name` and `symbol` functions in the metadata extension. Every token EIP and draft we reviewed (ERC-20, ERC-223, ERC-677, ERC-777, ERC-827) included these functions. We remind implementation authors that the empty string is a valid response to `name` and `symbol` if you protest to the usage of this mechanism. We also remind everyone that any smart contract can use the same name and symbol as _your_ contract. How a client may determine which ERC-1261 smart contracts are well-known (canonical) is outside the scope of this standard. A mechanism is provided to associate MVTs with URIs. We expect that many implementations will take advantage of this to provide metadata for each MVT system. The URI MAY be mutable (i.e. it changes from time to time). We considered an MVT representing membership of a place, in this case metadata about the organization can naturally change. Metadata is returned as a string value. Currently this is only usable as calling from `web3`, not from other contracts. This is acceptable because we have not considered a use case where an on-blockchain application would query such information. _Alternatives considered: put all metadata for each asset on the blockchain (too expensive), use URL templates to query metadata parts (URL templates do not work with all URL schemes, especially P2P URLs), multiaddr network address (not mature enough)_ **Community Consensus** We have been very inclusive in this process and invite anyone with questions or contributions into our discussion. However, this standard is written only to support the identified use cases which are listed herein. ## Backwards Compatibility We have adopted `name` and `symbol` semantics from the ERC-20 specification. Example MVT implementations as of July 2018: - Membership Verification Token(https://github.com/chaitanyapotti/MembershipVerificationToken) ## Test Cases Membership Verification Token ERC-1261 Token includes test cases written using Truffle. ## Implementations Membership Verification Token ERC1261 -- a reference implementation - MIT licensed, so you can freely use it for your projects - Includes test cases - Also available as a npm package - npm i membershipverificationtoken ## References **Standards** 1. ERC-20 Token Standard. ./eip-20.md 1. ERC-165 Standard Interface Detection. ./eip-165.md 1. ERC-725/735 Claim Registry ./eip-725.md 1. ERC-173 Owned Standard. ./eip-173.md 1. JSON Schema. https://json-schema.org/ 1. Multiaddr. https://github.com/multiformats/multiaddr 1. RFC 2119 Key words for use in RFCs to Indicate Requirement Levels. https://www.ietf.org/rfc/rfc2119.txt **Issues** 1. The Original ERC-1261 Issue. https://github.com/ethereum/eips/issues/1261 1. Solidity Issue \#2330 -- Interface Functions are Axternal. https://github.com/ethereum/solidity/issues/2330 1. Solidity Issue \#3412 -- Implement Interface: Allow Stricter Mutability. https://github.com/ethereum/solidity/issues/3412 1. Solidity Issue \#3419 -- Interfaces Can't Inherit. https://github.com/ethereum/solidity/issues/3419 **Discussions** 1. Gitter #EIPs (announcement of first live discussion). https://gitter.im/ethereum/EIPs?at=5b5a1733d2f0934551d37642 1. ERC-1261 (announcement of first live discussion). https://github.com/ethereum/eips/issues/1261 **MVT Implementations and Other Projects** 1. Membership Verification Token ERC-1261 Token. https://github.com/chaitanyapotti/MembershipVerificationToken ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Standard Signature Validation Method for Contracts

Wed, 25 Jul 2018 00:00:00 +0000

## Abstract Externally Owned Accounts (EOA) can sign messages with their associated private keys, but currently contracts cannot. We propose a standard way for any contracts to verify whether a signature on a behalf of a given contract is valid. This is possible via the implementation of a `isValidSignature(hash, signature)` function on the signing contract, which can be called to validate a signature. ## Motivation There are and will be many contracts that want to utilize signed messages for validation of rights-to-move assets or other purposes. In order for these contracts to be able to support non Externally Owned Accounts (i.e., contract owners), we need a standard mechanism by which a contract can indicate whether a given signature is valid or not on its behalf. One example of an application that requires signatures to be provided would be decentralized exchanges with off-chain orderbook, where buy/sell orders are signed messages. In these applications, EOAs sign orders, signaling their desire to buy/sell a given asset and giving explicit permissions to the exchange smart contracts to conclude a trade via a signature. When it comes to contracts however, regular signatures are not possible since contracts do not possess a private key, hence this proposal. ## Specification The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). ```javascript pragma solidity ^0.5.0; contract ERC1271 { // bytes4(keccak256("isValidSignature(bytes32,bytes)") bytes4 constant internal MAGICVALUE = 0x1626ba7e; /** * @dev Should return whether the signature provided is valid for the provided hash * @param _hash Hash of the data to be signed * @param _signature Signature byte array associated with _hash * * MUST return the bytes4 magic value 0x1626ba7e when function passes. * MUST NOT modify state (using STATICCALL for solc < 0.5, view modifier for solc > 0.5) * MUST allow external calls */ function isValidSignature( bytes32 _hash, bytes memory _signature) public view returns (bytes4 magicValue); } ``` `isValidSignature` can call arbitrary methods to validate a given signature, which could be context dependent (e.g. time based or state based), EOA dependent (e.g. signers authorization level within smart wallet), signature scheme Dependent (e.g. ECDSA, multisig, BLS), etc. This function should be implemented by contracts which desire to sign messages (e.g. smart contract wallets, DAOs, multisignature wallets, etc.) Applications wanting to support contract signatures should call this method if the signer is a contract. ## Rationale We believe the name of the proposed function to be appropriate considering that an *authorized* signers providing proper signatures for a given data would see their signature as "valid" by the signing contract. Hence, a signed action message is only valid when the signer is authorized to perform a given action on the behalf of a smart wallet. Two arguments are provided for simplicity of separating the hash signed from the signature. A bytes32 hash is used instead of the unhashed message for simplicity, since contracts could expect a certain hashing function that is not standard, such as with [EIP-712](./eip-712.md). `isValidSignature()` should not be able to modify states in order to prevent `GasToken` minting or similar attack vectors. Again, this is to simplify the implementation surface of the function for better standardization and to allow off-chain contract queries. The specific return value is expected to be returned instead of a boolean in order to have stricter and simpler verification of a signature. ## Backwards Compatibility This EIP is backward compatible with previous work on signature validation since this method is specific to contract based signatures and not EOA signatures. ## Reference Implementation Example implementation of a signing contract: ```solidity /** * @notice Verifies that the signer is the owner of the signing contract. */ function isValidSignature( bytes32 _hash, bytes calldata _signature ) external override view returns (bytes4) { // Validate signatures if (recoverSigner(_hash, _signature) == owner) { return 0x1626ba7e; } else { return 0xffffffff; } } /** * @notice Recover the signer of hash, assuming it's an EOA account * @dev Only for EthSign signatures * @param _hash Hash of message that was signed * @param _signature Signature encoded as (bytes32 r, bytes32 s, uint8 v) */ function recoverSigner( bytes32 _hash, bytes memory _signature ) internal pure returns (address signer) { require(_signature.length == 65, "SignatureValidator#recoverSigner: invalid signature length"); // Variables are not scoped in Solidity. uint8 v = uint8(_signature[64]); bytes32 r = _signature.readBytes32(0); bytes32 s = _signature.readBytes32(32); // EIP-2 still allows signature malleability for ecrecover(). Remove this possibility and make the signature // unique. Appendix F in the Ethereum Yellow paper (https://ethereum.github.io/yellowpaper/paper.pdf), defines // the valid range for s in (281): 0 < s < secp256k1n ÷ 2 + 1, and for v in (282): v ∈ {27, 28}. Most // signatures from current libraries generate a unique signature with an s-value in the lower half order. // // If your library generates malleable signatures, such as s-values in the upper range, calculate a new s-value // with 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141 - s1 and flip v from 27 to 28 or // vice versa. If your library also generates signatures with 0/1 for v instead 27/28, add 27 to v to accept // these malleable signatures as well. // // Source OpenZeppelin // https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/cryptography/ECDSA.sol if (uint256(s) > 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0) { revert("SignatureValidator#recoverSigner: invalid signature 's' value"); } if (v != 27 && v != 28) { revert("SignatureValidator#recoverSigner: invalid signature 'v' value"); } // Recover ECDSA signer signer = ecrecover(_hash, v, r, s); // Prevent signer from being 0x0 require( signer != address(0x0), "SignatureValidator#recoverSigner: INVALID_SIGNER" ); return signer; } ``` Example implementation of a contract calling the isValidSignature() function on an external signing contract ; ```solidity function callERC1271isValidSignature( address _addr, bytes32 _hash, bytes calldata _signature ) external view { bytes4 result = IERC1271Wallet(_addr).isValidSignature(_hash, _signature); require(result == 0x1626ba7e, "INVALID_SIGNATURE"); } ``` ## Security Considerations Since there are no gas-limit expected for calling the isValidSignature() function, it is possible that some implementation will consume a large amount of gas. It is therefore important to not hardcode an amount of gas sent when calling this method on an external contract as it could prevent the validation of certain signatures. Note also that each contract implementing this method is responsible to ensure that the signature passed is indeed valid, otherwise catastrophic outcomes are to be expected. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Smart Contract Package Registry Interface

Mon, 13 Aug 2018 00:00:00 +0000

## Simple Summary A standard interface for smart contract package registries. ## Abstract This EIP specifies an interface for publishing to and retrieving assets from smart contract package registries. It is a companion EIP to [1123](./eip-1123.md) which defines a standard for smart contract package manifests. ## Motivation The goal is to establish a framework that allows smart contract publishers to design and deploy code registries with arbitrary business logic while exposing a set of common endpoints that tooling can use to retrieve assets for contract consumers. A clear standard would help the existing EthPM Package Registry evolve from a centralized, single-project community resource into a decentralized multi-registry system whose constituents are bound together by the proposed interface. In turn, these registries could be ENS name-spaced, enabling installation conventions familiar to users of `npm` and other package managers. **Examples** ```shell $ ethpm install packages.zeppelin.eth/Ownership ``` ```javascript const SimpleToken = await web3.packaging .registry('packages.ethpm.eth') .getPackage('simple-token') .getVersion('^1.1.5'); ``` ## Specification The specification describes a small read/write API whose components are mandatory. It allows registries to manage versioned releases using the conventions of [semver](https://semver.org/) without imposing this as a requirement. It assumes registries will share the following structure and conventions: + a **registry** is a deployed contract which manages a collection of **packages**. + a **package** is a collection of **releases** + a **package** is identified by a unique string name and unique bytes32 **packageId** within a given **registry** + a **release** is identified by a `bytes32` **releaseId** which must be unique for a given package name and release version string pair. + a **releaseId** maps to a set of data that includes a **manifestURI** string which describes the location of an [EIP 1123 package manifest](./eip-1123.md). This manifest contains data about the release including the location of its component code assets. + a **manifestURI** is a URI as defined by [RFC3986](https://tools.ietf.org/html/rfc3986) which can be used to retrieve the contents of the package manifest. In addition to validation against RFC3986, each **manifestURI** must also contain a hash of the content as specified in the [EIP-1123](./eip-1123.md). ### Examples **Package Names / Release Versions** ```shell "simple-token" # package name "1.0.1" # version string ``` **Release IDs** Implementations are free to choose any scheme for generating a **releaseId**. A common approach would be to hash the strings together as below: ```solidity // Hashes package name and a release version string function generateReleaseId(string packageName, string version) public view returns (bytes32 releaseId) { return keccak256(abi.encodePacked(packageName, version)); } ``` Implementations **must** expose this id generation logic as part of their public `read` API so tooling can easily map a string based release query to the registry's unique identifier for that release. **Manifest URIs** Any IPFS or Swarm URI meets the definition of **manifestURI**. Another example is content on GitHub addressed by its SHA-1 hash. The Base64 encoded content at this hash can be obtained by running: ```shell $ curl https://api.github.com/repos/:owner/:repo/git/blobs/:file_sha # Example $ curl https://api.github.com/repos/rstallman/hello/git/blobs/ce013625030ba8dba906f756967f9e9ca394464a ``` The string "hello" can have its GitHub SHA-1 hash independently verified by comparing it to the output of: ```shell $ printf "blob 6\000hello\n" | sha1sum > ce013625030ba8dba906f756967f9e9ca394464a ``` ### Write API Specification The write API consists of a single method, `release`. It passes the registry the package name, a version identifier for the release, and a URI specifying the location of a manifest which details the contents of the release. ```solidity function release(string packageName, string version, string manifestURI) public returns (bytes32 releaseId); ``` ### Events #### VersionRelease MUST be triggered when `release` is successfully called. ```solidity event VersionRelease(string packageName, string version, string manifestURI) ``` ### Read API Specification The read API consists of a set of methods that allows tooling to extract all consumable data from a registry. ```solidity // Retrieves a slice of the list of all unique package identifiers in a registry. // `offset` and `limit` enable paginated responses / retrieval of the complete set. (See note below) function getAllPackageIds(uint offset, uint limit) public view returns ( bytes32[] packageIds, uint pointer ); // Retrieves the unique string `name` associated with a package's id. function getPackageName(bytes32 packageId) public view returns (string packageName); // Retrieves the registry's unique identifier for an existing release of a package. function getReleaseId(string packageName, string version) public view returns (bytes32 releaseId); // Retrieves a slice of the list of all release ids for a package. // `offset` and `limit` enable paginated responses / retrieval of the complete set. (See note below) function getAllReleaseIds(string packageName, uint offset, uint limit) public view returns ( bytes32[] releaseIds, uint pointer ); // Retrieves package name, release version and URI location data for a release id. function getReleaseData(bytes32 releaseId) public view returns ( string packageName, string version, string manifestURI ); // Retrieves the release id a registry *would* generate for a package name and version pair // when executing a release. function generateReleaseId(string packageName, string version) public view returns (bytes32 releaseId); // Returns the total number of unique packages in a registry. function numPackageIds() public view returns (uint totalCount); // Returns the total number of unique releases belonging to the given packageName in a registry. function numReleaseIds(string packageName) public view returns (uint totalCount); ``` **Pagination** `getAllPackageIds` and `getAllReleaseIds` support paginated requests because it's possible that the return values for these methods could become quite large. The methods should return a `pointer` that points to the next available item in a list of all items such that a caller can use it to pick up from where the previous request left off. (See [here](https://mixmax.com/blog/api-paging-built-the-right-way) for a discussion of the merits and demerits of various pagination strategies.) The `limit` parameter defines the maximum number of items a registry should return per request. ## Rationale The proposal hopes to accomplish the following: + Define the smallest set of inputs necessary to allow registries to map package names to a set of release versions while allowing them to use any versioning schema they choose. + Provide the minimum set of getter methods needed to retrieve package data from a registry so that registry aggregators can read all of their data. + Define a standard query that synthesizes a release identifier from a package name and version pair so that tooling can resolve specific package version requests without needing to query a registry about all of a package's releases. Registries may offer more complex `read` APIs that manage requests for packages within a semver range or at `latest` etc. This EIP is agnostic about how tooling or registries might implement these. It recommends that registries implement [EIP-165](./eip-165.md) and avail themselves of resources to publish more complex interfaces such as [EIP-926](./eip-926.md). ## Backwards Compatibility No existing standard exists for package registries. The package registry currently deployed by EthPM would not comply with the standard since it implements only one of the method signatures described in the specification. ## Implementation A reference implementation of this proposal is in active development at the EthPM organization on GitHub [here](https://github.com/ethpm/escape-truffle). ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

WalletConnect URI Format

Wed, 15 Aug 2018 00:00:00 +0000

## Abstract This standard defines how the data to connect some application and a wallet can be encoded with a URI. This URI can then be shown either as a QR code or as a link. ## Specification ### Syntax WalletConnect request URI with the following parameters: request = "wc" ":" topic [ "@" version ][ "?" parameters ] topic = STRING version = 1*DIGIT parameters = parameter *( "&" parameter ) parameter = key "=" value key = STRING value = STRING ### Semantics Required parameters are dependent on the WalletConnect protocol version: For WalletConnect v1.0 protocol (`version`=`1`) the parameters are: - `key` - symmetric key used for encryption - `bridge` - url of the bridge server for relaying messages For WalletConnect v2.0 protocol (`version`=`2`) the parameters are: - `symKey` - symmetric key used for encrypting messages over relay - `methods` - jsonrpc methods supported for pairing topic - `relay-protocol` - transport protocol for relaying messages - `relay-data` - (optional) transport data for relaying messages - `expiryTimestamp` - (optional) unix epoch in seconds when pairing expires ### Example ``` # 1.0 wc:8a5e5bdc-a0e4-4702-ba63-8f1a5655744f@1?bridge=https%3A%2F%2Fbridge.walletconnect.org&key=41791102999c339c844880b23950704cc43aa840f3739e365323cda4dfa89e7a # 2.0 wc:7f6e504bfad60b485450578e05678ed3e8e8c4751d3c6160be17160d63ec90f9@2?relay-protocol=irn&symKey=587d5484ce2a2a6ee3ba1962fdd7e8588e06200c46823bd18fbd67def96ad303&methods=[wc_sessionPropose],[wc_authRequest,wc_authBatchRequest]"&expiryTimestamp=1705934757 ``` ## Rationale This proposal moves away from the JSON format used in the alpha version of the WalletConnect protocol because it suffered from very inefficient parsing of the intent of the QR code, thereby making it easier to create better QR code parsers APIs for wallets to implement. Also by using a URI instead of JSON inside the QR-Code the Android Intent system can be leveraged. ## Backwards Compatibility Versioning is required as part of the syntax for this URI specification to allow the WalletConnect protocol to evolve and allow backwards-compatibility whenever a new version is introduced. ## Security Considerations URIs should be shared between user devices or applications and no sensitive data is shared within the URI that could compromise the communication or would allow control of the user's private keys. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Subscriptions on the blockchain

Wed, 01 Aug 2018 00:00:00 +0000

## Simple Summary Monthly subscriptions are a key monetization channel for legacy web, and arguably they are the most healthy monetization channel for businesses on the legacy web (especially when compared to ad/surveillance) based models. They are arguably more healthy than a token based economic system (depending upon the vesting model of the ICO) because ##### For a user: * you don't have to read a complex whitepaper to use a dapps utility (as opposed to utility tokens) * you don't have to understand the founder's vesting schedules * you can cancel anytime ##### For a Service Provider: * since you know your subscriber numbers, churn numbers, conversion rate, you get consistent cash flow, and accurate projections * you get to focus on making your customers happy * enables you to remove speculators from your ecosystem For these reasons, we think it's imperative to create a standard way to do 'subscriptions' on Ethereum. ## Abstract To enable replay-able transactions users sign a concatenated bytes hash that is composed of the input data needed to execute the transaction. This data is stored off chain by the recipient of the payment and is transmitted to the customers smart contract for execution alongside a provided signature. ## Motivation Recurring payments are the bedrock of SaSS and countless other businesses, a robust specification for defining this interaction will enable a broad spectrum of revenue generation and business models. ## Specification #### Enum Contract EIP-1337 Contracts should be compiled with a contract that references all the enumerations that are required for operation ```SOLIDITY /// @title Enum - Collection of enums /// Original concept from Richard Meissner - Gnosis safe contracts contract Enum { enum Operation { Call, DelegateCall, Create, ERC20, ERC20Approve } enum SubscriptionStatus { ACTIVE, PAUSED, CANCELLED, EXPIRED } enum Period { INIT, DAY, WEEK, MONTH } } ``` #### EIP-165 EIP-1337 compliant contracts support EIP-165 announcing what interfaces they support ```SOLIDITY interface ERC165 { /** * @notice Query if a contract implements an interface * @param interfaceID The interface identifier, as specified in ERC-165 * @dev Interface identification is specified in ERC-165. This function * uses less than 30,000 gas. * @return `true` if the contract implements `interfaceID` and * `interfaceID` is not 0xffffffff, `false` otherwise **/ function supportsInterface(bytes4 interfaceID) external view returns (bool); } ``` #### Public View Functions ###### isValidSubscription ```SOLIDITY /** @dev Checks if the subscription is valid. * @param bytes subscriptionHash is the identifier of the customer's subscription with its relevant details. * @return success is the result of whether the subscription is valid or not. **/ function isValidSubscription( uint256 subscriptionHash ) public view returns ( bool success ) ``` ###### getSubscriptionStatus ```SOLIDITY /** @dev returns the value of the subscription * @param bytes subscriptionHash is the identifier of the customer's subscription with its relevant details. * @return status is the enumerated status of the current subscription, 0 expired, 1 active, 2 paused, 3 cancelled **/ function getSubscriptionStatus( uint256 subscriptionHash ) public view returns ( uint256 status, uint256 nextWithdraw ) ``` ###### getSubscriptionHash ```SOLIDITY /** @dev returns the hash of cocatenated inputs to the address of the contract holding the logic., * the owner would sign this hash and then provide it to the party for execution at a later date, * this could be viewed like a cheque, with the exception that unless you specifically * capture the hash on chain a valid signature will be executable at a later date, capturing the hash lets you modify the status to cancel or expire it. * @param address recipient the address of the person who is getting the funds. * @param uint256 value the value of the transaction * @param bytes data the data the user is agreeing to * @param uint256 txGas the cost of executing one of these transactions in gas(probably safe to pad this) * @param uint256 dataGas the cost of executing the data portion of the transaction(delegate calls etc) * @param uint 256 gasPrice the agreed upon gas cost of Execution of this subscription(cost incurment is up to implementation, ie, sender or receiver) * @param address gasToken address of the token in which gas will be compensated by, address(0) is ETH, only works in the case of an enscrow implementation) * @param bytes meta dynamic bytes array with 4 slots, 2 required, 2 optional // address refundAddress / uint256 period / uint256 offChainID / uint256 expiration (uinx timestamp) * @return bytes32, return the hash input arguments concatenated to the address of the contract that holds the logic. **/ function getSubscriptionHash( address recipient, uint256 value, bytes data, Enum.Operation operation, uint256 txGas, uint256 dataGas, uint256 gasPrice, address gasToken, bytes meta ) public view returns ( bytes32 subscriptionHash ) ``` ###### getModifyStatusHash ```SOLIDITY /** @dev returns the hash of concatenated inputs that the owners user would sign with their public keys * @param address recipient the address of the person who is getting the funds. * @param uint256 value the value of the transaction * @return bytes32 returns the hash of concatenated inputs with the address of the contract holding the subscription hash **/ function getModifyStatusHash( bytes32 subscriptionHash Enum.SubscriptionStatus status ) public view returns ( bytes32 modifyStatusHash ) ``` #### Public Functions ###### modifyStatus ```SOLIDITY /** @dev modifys the current subscription status * @param uint256 subscriptionHash is the identifier of the customer's subscription with its relevant details. * @param Enum.SubscriptionStatus status the new status of the subscription * @param bytes signatures of the requested method being called * @return success is the result of the subscription being paused **/ function modifyStatus( uint256 subscriptionHash, Enum.SubscriptionStatus status, bytes signatures ) public returns ( bool success ) ``` ###### executeSubscription ```SOLIDITY /** @dev returns the hash of cocatenated inputs to the address of the contract holding the logic., * the owner would sign this hash and then provide it to the party for execution at a later date, * this could be viewed like a cheque, with the exception that unless you specifically * capture the hash on chain a valid signature will be executable at a later date, capturing the hash lets you modify the status to cancel or expire it. * @param address recipient the address of the person who is getting the funds. * @param uint256 value the value of the transaction * @param bytes data the data the user is agreeing to * @param uint256 txGas the cost of executing one of these transactions in gas(probably safe to pad this) * @param uint256 dataGas the cost of executing the data portion of the transaction(delegate calls etc) * @param uint 256 gasPrice the agreed upon gas cost of Execution of this subscription(cost incurment is up to implementation, ie, sender or receiver) * @param address gasToken address of the token in which gas will be compensated by, address(0) is ETH, only works in the case of an enscrow implementation) * @param bytes meta dynamic bytes array with 4 slots, 2 required, 2 optional // address refundAddress / uint256 period / uint256 offChainID / uint256 expiration (uinx timestamp) * @param bytes signatures signatures concatenated that have signed the inputs as proof of valid execution * @return bool success something to note that a failed execution will still pay the issuer of the transaction for their gas costs. **/ function executeSubscription( address to, uint256 value, bytes data, Enum.Operation operation, uint256 txGas, uint256 dataGas, uint256 gasPrice, address gasToken, bytes meta, bytes signatures ) public returns ( bool success ) ``` ## Rationale Merchants who accept credit-cards do so by storing a token that is retrieved from a third party processor(stripe, paypal, etc), this token is used to grant access to pull payment from the cx's credit card provider and move funds to the merchant account. Having users sign input data acts in a similliar fashion and enables that merchant to store the signature of the concatenated bytes hash and input data used to generate the hash and pass them off to the contract holding the subscription logic, thus enabling a workflow that is similliar to what exists in the present day legacy web. ## Backwards Compatibility N/A ## Test Cases TBD ## Implementation TBD ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Payable Token

Thu, 30 Aug 2018 00:00:00 +0000

## Simple Summary Defines a token interface for [ERC-20](./eip-20.md) tokens that supports executing recipient code after `transfer` or `transferFrom`, or spender code after `approve`. ## Abstract Standard functions a token contract and contracts working with tokens can implement to make a token Payable. `transferAndCall` and `transferFromAndCall` will call an `onTransferReceived` on a `ERC1363Receiver` contract. `approveAndCall` will call an `onApprovalReceived` on a `ERC1363Spender` contract. ## Motivation There is no way to execute code after a [ERC-20](./eip-20.md) transfer or approval (i.e. making a payment), so to make an action it is required to send another transaction and pay GAS twice. This proposal wants to make token payments easier and working without the use of any other listener. It allows to make a callback after a transfer or approval in a single transaction. There are many proposed uses of Ethereum smart contracts that can accept [ERC-20](./eip-20.md) payments. Examples could be * to create a token payable crowdsale * selling services for tokens * paying invoices * making subscriptions For these reasons it was named as **"Payable Token"**. Anyway you can use it for specific utilities or for any other purposes who require the execution of a callback after a transfer or approval received. This proposal has been inspired by the [ERC-721](./eip-721.md) `onERC721Received` and `ERC721TokenReceiver` behaviours. ## Specification Implementing contracts **MUST** implement the [ERC-1363](./eip-1363.md) interface as well as the [ERC-20](./eip-20.md) and [ERC-165](./eip-165.md) interfaces. ```solidity pragma solidity ^0.8.0; interface ERC1363 /* is ERC20, ERC165 */ { /* * Note: the ERC-165 identifier for this interface is 0xb0202a11. * 0xb0202a11 === * bytes4(keccak256('transferAndCall(address,uint256)')) ^ * bytes4(keccak256('transferAndCall(address,uint256,bytes)')) ^ * bytes4(keccak256('transferFromAndCall(address,address,uint256)')) ^ * bytes4(keccak256('transferFromAndCall(address,address,uint256,bytes)')) ^ * bytes4(keccak256('approveAndCall(address,uint256)')) ^ * bytes4(keccak256('approveAndCall(address,uint256,bytes)')) */ /** * @notice Transfer tokens from `msg.sender` to another address and then call `onTransferReceived` on receiver * @param to address The address which you want to transfer to * @param value uint256 The amount of tokens to be transferred * @return true unless throwing */ function transferAndCall(address to, uint256 value) external returns (bool); /** * @notice Transfer tokens from `msg.sender` to another address and then call `onTransferReceived` on receiver * @param to address The address which you want to transfer to * @param value uint256 The amount of tokens to be transferred * @param data bytes Additional data with no specified format, sent in call to `to` * @return true unless throwing */ function transferAndCall(address to, uint256 value, bytes memory data) external returns (bool); /** * @notice Transfer tokens from one address to another and then call `onTransferReceived` on receiver * @param from address The address which you want to send tokens from * @param to address The address which you want to transfer to * @param value uint256 The amount of tokens to be transferred * @return true unless throwing */ function transferFromAndCall(address from, address to, uint256 value) external returns (bool); /** * @notice Transfer tokens from one address to another and then call `onTransferReceived` on receiver * @param from address The address which you want to send tokens from * @param to address The address which you want to transfer to * @param value uint256 The amount of tokens to be transferred * @param data bytes Additional data with no specified format, sent in call to `to` * @return true unless throwing */ function transferFromAndCall(address from, address to, uint256 value, bytes memory data) external returns (bool); /** * @notice Approve the passed address to spend the specified amount of tokens on behalf of msg.sender * and then call `onApprovalReceived` on spender. * @param spender address The address which will spend the funds * @param value uint256 The amount of tokens to be spent * @return true unless throwing */ function approveAndCall(address spender, uint256 value) external returns (bool); /** * @notice Approve the passed address to spend the specified amount of tokens on behalf of msg.sender * and then call `onApprovalReceived` on spender. * @param spender address The address which will spend the funds * @param value uint256 The amount of tokens to be spent * @param data bytes Additional data with no specified format, sent in call to `spender` * @return true unless throwing */ function approveAndCall(address spender, uint256 value, bytes memory data) external returns (bool); } interface ERC20 { function totalSupply() external view returns (uint256); function balanceOf(address account) external view returns (uint256); function transfer(address recipient, uint256 amount) external returns (bool); function transferFrom(address sender, address recipient, uint256 amount) external returns (bool); function allowance(address owner, address spender) external view returns (uint256); function approve(address spender, uint256 amount) external returns (bool); event Transfer(address indexed from, address indexed to, uint256 value); event Approval(address indexed owner, address indexed spender, uint256 value); } interface ERC165 { function supportsInterface(bytes4 interfaceId) external view returns (bool); } ``` A contract that wants to accept token payments via `transferAndCall` or `transferFromAndCall` **MUST** implement the following interface: ```solidity /** * @title ERC1363Receiver interface * @dev Interface for any contract that wants to support `transferAndCall` or `transferFromAndCall` * from ERC1363 token contracts. */ interface ERC1363Receiver { /* * Note: the ERC-165 identifier for this interface is 0x88a7ca5c. * 0x88a7ca5c === bytes4(keccak256("onTransferReceived(address,address,uint256,bytes)")) */ /** * @notice Handle the receipt of ERC1363 tokens * @dev Any ERC1363 smart contract calls this function on the recipient * after a `transfer` or a `transferFrom`. This function MAY throw to revert and reject the * transfer. Return of other than the magic value MUST result in the * transaction being reverted. * Note: the token contract address is always the message sender. * @param operator address The address which called `transferAndCall` or `transferFromAndCall` function * @param from address The address which are token transferred from * @param value uint256 The amount of tokens transferred * @param data bytes Additional data with no specified format * @return `bytes4(keccak256("onTransferReceived(address,address,uint256,bytes)"))` * unless throwing */ function onTransferReceived(address operator, address from, uint256 value, bytes memory data) external returns (bytes4); } ``` A contract that wants to accept token payments via `approveAndCall` **MUST** implement the following interface: ```solidity /** * @title ERC1363Spender interface * @dev Interface for any contract that wants to support `approveAndCall` * from ERC1363 token contracts. */ interface ERC1363Spender { /* * Note: the ERC-165 identifier for this interface is 0x7b04a2d0. * 0x7b04a2d0 === bytes4(keccak256("onApprovalReceived(address,uint256,bytes)")) */ /** * @notice Handle the approval of ERC1363 tokens * @dev Any ERC1363 smart contract calls this function on the recipient * after an `approve`. This function MAY throw to revert and reject the * approval. Return of other than the magic value MUST result in the * transaction being reverted. * Note: the token contract address is always the message sender. * @param owner address The address which called `approveAndCall` function * @param value uint256 The amount of tokens to be spent * @param data bytes Additional data with no specified format * @return `bytes4(keccak256("onApprovalReceived(address,uint256,bytes)"))` * unless throwing */ function onApprovalReceived(address owner, uint256 value, bytes memory data) external returns (bytes4); } ``` ## Rationale The choice to use `transferAndCall`, `transferFromAndCall` and `approveAndCall` derives from the [ERC-20](./eip-20.md) naming. They want to highlight that they have the same behaviours of `transfer`, `transferFrom` and `approve` with the addition of a callback on receiver or spender. ## Backwards Compatibility This proposal has been inspired also by [ERC-223](https://github.com/ethereum/EIPs/issues/223) and [ERC-677](https://github.com/ethereum/EIPs/issues/677) but it uses the [ERC-721](./eip-721.md) approach, so it doesn't override the [ERC-20](./eip-20.md) `transfer` and `transferFrom` methods and defines the interfaces IDs to be implemented maintaining the [ERC-20](./eip-20.md) backwards compatibility. ## Security Considerations The `approveAndCall` and `transferFromAndCall` methods can be affected by the same issue of the standard [ERC-20](./eip-20.md) `approve` and `transferFrom` method. Changing an allowance with the `approveAndCall` methods brings the risk that someone may use both the old and the new allowance by unfortunate transaction ordering. One possible solution to mitigate this race condition is to first reduce the spender's allowance to 0 and set the desired value afterwards ([EIP-20#issuecomment-263524729](https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729)). ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Attestation management contract

Sat, 08 Sep 2018 00:00:00 +0000

### Introduction Very often, we will need to use Attestations like "Alice lives in Australia" on the blockchain; that is issued by a valid issuer off chain for privacy reasons and is revokable inside a smart contract. An issuer can create a smart contract where he revokes multiple attestations in one go by building a bloom filter of all the hashes of the revoked attestations. An issuer can also put the validation method in their smart contract that can be called by other smart contracts who need to validate attestations issued by them. This allows each attestor to update their attestation format separately. ### Purpose This ERC provides an interface for attestation issuers to manage their attestation signing keys and the attestations that are issued off chain for actions such as revocation and validation. In our draft implementation we include functions to hold cryptographic attestations, change the issuing contracts of attestations, revoke attestations and verify the authenticity of a cryptographic attestation. ### Example use cases Let's say that our friend, Alice, wants to buy a bottle of wine to consume with her friends. She wants to do the order online and have it delivered to her home address whilst paying for it with Ether. Alice has a cryptographic attestation from her local road and maritime services who attests to her age, date of birth, country of residence and ability to drive. Alice is able to split up this attestation (see merkle tree attestations ERC [here](https://github.com/alpha-wallet/blockchain-attestation/blob/master/ethereum/lib/MerkleTreeAttestation.sol)) and provides only the leaf that states she is over the age of 21. Alice goes to buy the wine through the wine vendors smart contract and feeds in the merkle tree attestation proving that she is above 21 and can thus buy the wine, whilst attaching the appropriate amount of ether to complete the purchase. The issuer smart contract is able to validate her attestation, check that the issuer contract is valid and capable of performing such an attestation to her age. In this case it would have to be from someone like a driver's licence authority, as attestations to age from a school ID are not of a high enough capacity. The wine vendors smart contract validates the attestation, checks the payment amount is correct and credits Alice with the wine tokens she needs to complete the sale and deliver the wine. When the wine vendor shows up to her apartment with the wine, there is no need to prove her age again. ### Draft interface ```solidity /* each attestation issuer should provide their own verify() for the * attestations they issued. There are two reasons for this. First, we * need to leave room for new attestation methods other than the * Merkle Tree format we are recommending. Second, the validity of the * attestation may depend on the context that only the attestor * knows. For example, a ticket as an attestation issued on a * successful redemption of an American Express credit */ contract Issuer { struct Attestation { bytes32[] merklePath; bool valid; uint8 v; bytes32 r; bytes32 s; address attestor; address recipient; bytes32 salt; bytes32 key; bytes32 val; }` /* Verify the authenticity of an attestation */ function verify(Attestation attestation); function addattestorKey(address newAttestor, string capacity, uint expiry); /* this should call the revoke first */ function replaceKey(address attestorToReplace, string capacity, uint expiry, address newAttestor); /* this revokes a single key */ function removeKey(address attestor); /* if the key exists with such capacity and isn't revoked or expired */ function validateKey(address attestor, string capacity) returns (bool); /* revoke an attestation by replace the bloom filter, this helps preserve privacy */ function revokeAttestations(Bloomfilter b); } ``` Please click [here](https://github.com/alpha-wallet/blockchain-attestation/blob/master/ethereum/example-james-squire/james-squire.sol) to see a draft implementation of this interface ### Related ERC's #1388 #1387

Merkle Tree Attestations with Privacy enabled

Sat, 08 Sep 2018 00:00:00 +0000

### Introduction It's often needed that an Ethereum smart contract must verify a claim (I live in Australia) attested by a valid attester. For example, an ICO contract might require that the participant, Alice, lives in Australia before she participates. Alice's claim of residency could come from a local Justice of the Peace who could attest that "Alice is a resident of Australia in NSW". Unlike previous attempts, we assume that the attestation is signed and issued off the blockchain in a Merkle Tree format. Only a part of the Merkle tree is revealed by Alice at each use. Therefore we avoid the privacy problem often associated with issuing attestations on chain. We also assume that Alice has multiple signed Merkle Trees for the same factual claim to avoid her transactions being linkable. ## Purpose This ERC provides an interface and reference implementation for smart contracts that need users to provide an attestation and validate it. ### Draft implementation ```solidity contract MerkleTreeAttestationInterface { struct Attestation { bytes32[] merklePath; bool valid; uint8 v; bytes32 r; bytes32 s; address attester; address recipient; bytes32 salt; bytes32 key; bytes32 val; } function validate(Attestation attestation) public returns(bool); } ``` ### Relevant implementation examples [Here](https://github.com/alpha-wallet/blockchain-attestation/blob/master/ethereum/lib/MerkleTreeAttestation.sol) is an example implementation of the MerkleTreeAttestationInterface [Here](https://github.com/alpha-wallet/blockchain-attestation/blob/master/ethereum/example-james-squire/james-squire.sol) is an example service which would use such a merkle tree attestation ### Related ERC's #1388 #1386

Attestation Issuers Management List

Sat, 08 Sep 2018 00:00:00 +0000

### Introduction In smart contracts, we will need methods to handle cryptographic attestations to a users identifier or abilities. Let's say we have a real estate agent, KiwiRealtors, that provides an "expression of interest" function though a smart contract and requires the users to provide an attestation that they are a resident of New Zealand or Australia, as a legal requirement. This has actually happened in the New Zealand property market and it is the perfect example of a need to handle such attestations. However, it is not practical for a smart contract to explicitly trust an attestation issuer. There are multiple issuers who can provide an attestation to a person's residency - a local Justice of the Peace, the land title office, local police, passport authority etc. We envision a model where the effort to manage the list of qualified issuers is practically outsourced to a list. Anyone can publish a list of issuers. Only the most trusted and carefully maintained lists gets popular use. ### Purpose This ERC provides a smart contract interface for anyone to manage a list of attestation issuers. A smart contract would explicitly trust a list, and therefore all attestations issued by the issuers on the list. ### Draft implementation ```solidity /* The purpose of this contract is to manage the list of attestation * issuer contracts and their capacity to fulfill requirements */ contract ManagedListERC { /* a manager is the steward of a list. Only he/she/it can change the * list by removing/adding attestation issuers to the list. * An issuer in the list is represented by their contract * addresses, not by the attestation signing keys managed by such a * contract. */ struct List { string name; string description; // short description of what the list entails string capacity; // serves as a filter for the attestation signing keys /* if a smart contract specifies a list, only attestation issued * by issuers on that list is accepted. Furthermore, if that * list has a non-empty capacity, only attestations signed by a * signing key with that capacity is accepted. */ address[] issuerContracts; // all these addresses are contracts, no signing capacity uint expiry; } // find which list the sender is managing, then add an issuer to it function addIssuer(address issuerContractAddress) public; //return false if the list identified by the sender doesn't have this issuer in the list function removeIssuer(address issuerContractAddress, List listToRemoveIssuerFrom) public returns(bool); /* called by services, e.g. Kiwi Properties or James Squire */ /* loop through all issuer's contract and execute validateKey() on * every one of them in the hope of getting a hit, return the * contract address of the first hit. Note that there is an attack * method for one issuer to claim to own the key of another which * is mitigated by later design. */ //loop through the issuers array, calling validate on the signingKeyOfAttestation function getIssuerCorrespondingToAttestationKey(bytes32 list_id, address signingKeyOfAttestation) public returns (address); /* for simplicity we use sender's address as the list ID, * accepting these consequences: a) if one user wish to maintain * several lists with different capacity, he or she must use a * different sender address for each. b) if the user replaced the * sender's key, either because he or she suspects the key is * compromised or that it is lost and reset through special means, * then the list is still identified by the first sender's * address. */ function createList(List list) public; /* replace list manager's key with the new key */ function replaceListIndex(List list, address manager) public returns(bool); } ``` Click [here](https://github.com/alpha-wallet/blockchain-attestation/blob/master/ethereum/trustlist/ManagedList.sol) to see an example implementation of this ERC ### Related ERC's #1387 #1386

Poll Standard

Sun, 16 Sep 2018 00:00:00 +0000

## Note to Readers 1. We have created a couple of implementations of polls for varied use cases. Please refer to them [here](https://github.com/chaitanyapotti/Voting) ## Simple Summary A standard interface for Polls to be used with EIP-1261 (MVT). ## Abstract The following standard allows for the implementation of a standard API for polls to be used with MVTs (refer [EIP-1261](./eip-1261.md)). The standard provides basic functionality to vote, unvote, tally votes, get voter turnout, and a lot more. The poll standard attempts to modularize blockchain voting by breaking down a poll into 4 crucial building blocks: voterbase qualification, vote weight calculation, vote consequences, and vote tallying. By creating a common interface for polls that have different kinds of building blocks, the poll standard makes it possible to make interactive front end applications which can seamlessly get data from a poll contract in order to bring transparency into consensus and decision making on the blockchain. We considered the usage of polls with MVTs because MVTs serve as a permissioning mechanism. The manual permissioning of polls allows for vote weightage functions to take up several shapes and forms. Hence the voterbase function applies several logical checks on the vote sender to confirm that they are member(see EIP 1261) of a certain entity or combination of entities. For the specification of the nature of voting, we define the vote weight function. The vote weight function decides how much of vote share each voter will receive and this can be based on several criteria, some of which are listed below in this article. There are certain kinds of polls that enforce certain consequences on the voter, for example a poll may require a voter to lock in a certain amount of tokens, or require the voter to pay a small fee. These on-chain consequences can be coded into the consequence module of the poll standard. Finally, the last module is where the votes are added. A ballot for each candidate is updated whenever relevant, depending on the vote value, and the corresponding NoV count(number of voters). This module is common for most polls, and is the most straightforward. Polls may be time bound, ie. having a finish time, after which no votes are recorded, or be unbound, such that there is no finish time. The following are some examples of specific polls which leverage the flexibility of the poll standard, and it is possible to come up with several others: - Plurality Voting: The simplest form of voting is when you want all eligible voters to have one vote per person. This is the simplest to code, as the vote weight is 1, and there is no vote consequence. The only relevant module here is the voterbase, which can be categorized by one or more MVT contracts. - Token proportional voting: This kind of a poll is actually possible without the use of a voterbase function, because the vote weight function having token proportionality automatically rules out addresses which don't hold the appropriate ERC - 20/ ERC - 777 token. However the voterbase function may be leveraged to further permission the system and give voting rights only to a fixed subset of token holders. - Capped Token Proportional Voting: This is a modified version of the previous example, where each voter is given proportional vote share only until a certain limit of token ownership. After exceeding that limit, holding more coins does not add more vote share. This format leverages the voterbase module effectively, disallowing people from spreading their coins across multiple addresses by allowing the admin to control which addresses can vote. - Delegated Voting: Certain polls may allow voters to delegate their votes to other voters. This is known as delegated voting or liquid democracy. For such a poll, a complicated vote weight function is needed, and a data structure concerning the voterbase is also required. A consequence of voting here would be that a user cannot delegate, and a consequence of delegating is that a user cannot vote. Sample implementation of polls contains an example of this vote scheme. - Karma Based Voting: A certain form of poll may be based on weightage from digital respect. This digital respect would be like a simple upvote from one member of voterbase to another. A mapping of mappings along with an appropriate vote weight function can serve this purpose. Sample implementation has an example. - Quadratic voting: A system where each vote is associated with a fee, and the fee is proportional to the square of the vote weight that the voter wants. This can be designed by applying a vote weight based on the transaction message, and then charging a fee in the vote consequence module. The poll standard is intended to be a smart contract standard that makes poll deployment flexible, transparent and accessible. ## Motivation A standard interface allows any user or applications to work with any Poll contract on Ethereum. We provide for simple ERC-1417 smart contracts. Additional applications are discussed below. This standard is inspired by the lack of governance tools in the blockchain space. Whenever there is a consensus collection exercise, someone goes ahead and deploys some kind of poll, and there is no standard software for accessing the data on the poll. For an end user who is not a developer, this is a real problem. The poll, which might be fully transparent, appears to be completely opaque to a common user who does not understand blockchain. In order for developers to build applications for interacting with and accessing poll data, and for poll deployers to have ready application level support, there must be a standardization of poll interfaces. This realization happened while conducting market research on DAICOs. The first ever DAICO, Abyss, had far from optimal user experience, and abysmal transparency. Since then, we have been working on a poll standard. During the process, we came across EIP 1202, the voting standard, and found that the discussion there had already diverged from our thoughts to an extent that it made sense to publish a separate proposal altogether. Some of the benefits brought by the poll standard - EIP 1417 aims to offer some additional benefits. 1. Modularization: EIP 1417 modularizes the code present in the poll standard into 4 major building blocks based on functionality. These are: voterbase logic, vote weight calculation, vote consequence processing, and tallying module. This makes it easy for developers to change parts of a poll without disrupting other parts, and also helps people understand better, code written in the same format by other people. 2. Permissioning: Permissioning is an important aspect of polls, and is missing in most poll proposals so far, on the blockchain. For some reason, most blockchain based polls seem to consider token holding as the only way to permission a poll. However this hampers flexibility, and hence our poll standard is leveraging EIP 1261 in order to clear the permissioning hurdle. Not only does it allow for more creative poll structures in terms of vote weightage, but even improves the flexibility in permissioning by allowing developers to combine several entities and read attributes from entities. 3. Flexibility: The vote weight module of the poll standard can be used effectively to design various kinds of poll contracts which function differently and are suited to different environments. Some examples are quadratic voting, karma voting, delegated voting, token based voting, and one person one vote systems. These schemes are possible due to the separation of voterbase creation and vote weight calculation. 4. NoV Counts: Several weighted polls have struggled to provide proper transparency because they only show the final result without enough granularity. This is because they do not store the number of voters that have voted for each proposal, and only store the total accrued vote for each option. EIP 1417 solves this by additionally recording number of voters(NoV) in each proposal. This NoV count is redundant in the case of one person one vote, but elsewhere, it is helpful in figuring out concentration of power. This ensures that malicious parties can be traced to a larger extent. 5. Event Logging: The poll standard logs an event during a successful vote, unsuccessful vote, and a successful unvote. This is being done so that in the event of a malicious admin removing real members or adding fake members, communities can build tools in order to perform advanced audits and simulate results in the absence of the malicious attack. Such advanced features are completely absent in most polls, and hence, it is hard to investigate such polls. 6. Pollscan.io: The Electus foundation is working on a web based application for accessing and interacting with poll data on the blockchain, it will be deployed on the domain name www.pollscan.io in the coming months. All that being said, we are very excited to share our proposal with the community and open up to suggestions in this space. ### Benefits 1. Building applications (pollscan.io) on top of a standardized voting interface enables transparency and encourage more DAO/DAICO's to act responsibly in terms of governance 2. Create Action contracts which take actions programmatically based on the result of a poll 3. Allow the compatibility with token standard such as [ERC-20](./eip-20.md) or (./eip-777.md)) and membership standard such as [EIP-1261](./eip-1261.md) 4. Flexibility allows for various voting schemes including but not limited to modern schemes such as PLCR Voting ### Use-cases: Polls are useful in any context of collective decision making, which include but aren't limited to: 1. Governing public resources, like ponds, playgrounds, streets etc 2. Maintaining fiscal policy in a transparent consensus driven manner 3. Governing crowdfunded projects - refer DAICO, Vitalik Buterin 4. Implementation of Futarchy 5. Decision making in political parties, and municipal corporations 6. Governing expenditure of a cryptocurrency community ## Specification The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. **Every ERC-1417 compliant contract must implement the `ERC1417` and `ERC165` interfaces** (subject to "caveats" below): ```solidity /// @title ERC-1417 Poll Standard /// @dev See https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1417.md /// Note: the ERC-165 identifier for this interface is 0x4fad898b. interface IPoll { /// @dev This emits when a person tries to vote without permissions. Useful for auditing purposes. /// E.g.: To prevent an admin to revoke permissions; calculate the result had they not been removed. /// @param _from User who tried to vote /// @param _to the index of the proposal he voted to /// @param voteWeight the weight of his vote event TriedToVote(address indexed _from, uint8 indexed _to, uint voteWeight); /// @dev This emits when a person votes successfully /// @param _from User who successfully voted /// @param _to the index of the proposal he voted to /// @param voteWeight the weight of his vote event CastVote(address indexed _from, uint8 indexed _to, uint voteWeight); /// @dev This emits when a person revokes his vote /// @param _from User who successfully unvoted /// @param _to the index of the proposal he unvoted /// @param voteWeight the weight of his vote event RevokedVote(address indexed _from, uint8 indexed _to, uint voteWeight); /// @notice Handles the vote logic /// @dev updates the appropriate data structures regarding the vote. /// stores the proposalId against the user to allow for unvote /// @param _proposalId the index of the proposal in the proposals array function vote(uint8 _proposalId) external; /// @notice Handles the unvote logic /// @dev updates the appropriate data structures regarding the unvote function revokeVote() external; /// @notice gets the proposal names /// @dev limit the proposal count to 32 (for practical reasons), loop and generate the proposal list /// @return the list of names of proposals function getProposals() external view returns (bytes32[]); /// @notice returns a boolean specifying whether the user can vote /// @dev implement logic to enable checks to determine whether the user can vote /// if using eip-1261, use protocol addresses and interface (IERC1261) to enable checking with attributes /// @param _to the person who can vote/not /// @return a boolean as to whether the user can vote function canVote(address _to) external view returns (bool); /// @notice gets the vote weight of the proposalId /// @dev returns the current cumulative vote weight of a proposal /// @param _proposalId the index of the proposal in the proposals array /// @return the cumulative vote weight of the specified proposal function getVoteTally(uint _proposalId) external view returns (uint); /// @notice gets the no. of voters who voted for the proposal /// @dev use a struct to keep a track of voteWeights and voterCount /// @param _proposalId the index of the proposal in the proposals array /// @return the voter count of the people who voted for the specified proposal function getVoterCount(uint _proposalId) external view returns (uint); /// @notice calculates the vote weight associated with the person `_to` /// @dev use appropriate logic to determine the vote weight of the individual /// For sample implementations, refer to end of the eip /// @param _to the person whose vote weight is being calculated /// @return the vote weight of the individual function calculateVoteWeight(address _to) external view returns (uint); /// @notice gets the leading proposal at the current time /// @dev calculate the leading proposal at the current time /// For practical reasons, limit proposal count to 32. /// @return the index of the proposal which is leading function winningProposal() external view returns (uint8); /// @notice gets the name of the poll e.g.: "Admin Election for Autumn 2018" /// @dev Set the name in the constructor of the poll /// @return the name of the poll function getName() external view returns (bytes32); /// @notice gets the type of the Poll e.g.: Token (XYZ) weighted poll /// @dev Set the poll type in the constructor of the poll /// @return the type of the poll function getPollType() external view returns (bytes32); /// @notice gets the logic to be used in a poll's `canVote` function /// e.g.: "XYZ Token | US & China(attributes in erc-1261) | Developers(attributes in erc-1261)" /// @dev Set the Voterbase logic in the constructor of the poll /// @return the voterbase logic function getVoterBaseLogic() external view returns (bytes32); /// @notice gets the start time for the poll /// @dev Set the start time in the constructor of the poll as Unix Standard Time /// @return start time as Unix Standard Time function getStartTime() external view returns (uint); /// @notice gets the end time for the poll /// @dev Set the end time in the constructor of the poll as Unix Time or specify duration in constructor /// @return end time as Unix Standard Time function getEndTime() external view returns (uint); /// @notice returns the list of entity addresses (eip-1261) used for perimissioning purposes. /// @dev addresses list can be used along with IERC1261 interface to define the logic inside `canVote()` function /// @return the list of addresses of entities function getProtocolAddresses() external view returns (address[]); /// @notice gets the vote weight against all proposals /// @dev limit the proposal count to 32 (for practical reasons), loop and generate the vote tally list /// @return the list of vote weights against all proposals function getVoteTallies() external view returns (uint[]); /// @notice gets the no. of people who voted against all proposals /// @dev limit the proposal count to 32 (for practical reasons), loop and generate the vote count list /// @return the list of voter count against all proposals function getVoterCounts() external view returns (uint[]); /// @notice For single proposal polls, returns the total voterbase count. /// For multi proposal polls, returns the total vote weight against all proposals /// this is used to calculate the percentages for each proposal /// @dev limit the proposal count to 32 (for practical reasons), loop and generate the voter base denominator /// @return an integer which specifies the above mentioned amount function getVoterBaseDenominator() external view returns (uint); } ``` ### Caveats The 0.4.24 Solidity interface grammar is not expressive enough to document the ERC-1417 standard. A contract which complies with ERC-1417 MUST also abide by the following: - Solidity issue #3412: The above interfaces include explicit mutability guarantees for each function. Mutability guarantees are, in order weak to strong: `payable`, implicit nonpayable, `view`, and `pure`. Your implementation MUST meet the mutability guarantee in this interface and you MAY meet a stronger guarantee. For example, a `payable` function in this interface may be implemented as nonpayble (no state mutability specified) in your contract. We expect a later Solidity release will allow your stricter contract to inherit from this interface, but a workaround for version 0.4.24 is that you can edit this interface to add stricter mutability before inheriting from your contract. - Solidity issue #2330: If a function is shown in this specification as `external` then a contract will be compliant if it uses `public` visibility. As a workaround for version 0.4.24, you can edit this interface to switch to `public` before inheriting from your contract. _If a newer version of Solidity allows the caveats to be expressed in code, then this EIP MAY be updated and the caveats removed, such will be equivalent to the original specification._ ## Rationale As the poll standard is built with the intention of creating a system that allows for more transparency and accessibility of governance data, the design choices in the poll standard are driven by this motivator. In this section we go over some of the major design choices, and why these choices were made: 1. Event logging: The logic behind maintaining event logs in the cases of: - Cast Vote - Unvote - Failed Vote is to ensure that in the event of a manipulated voterbase, simple off chain checks can be performed to audit the integrity of the poll result. 2. No poll finish trigger: There was a consideration of adding functions in the poll which execute after completion of the poll to carry out some pre-decided logic. However this was deemed to be unnecessary - because such an action can be deployed in a separate contract which simply reads the result of a given poll, and against the spirit of modularity, because no actions can be created after the poll has been deployed. Also, such functions would not be able to combine the results of polls, and definitely would not fit into polls that do not have an end time. 3. Allow for unbound polls: The poll standard, unlike other voting standard proposals, does not force polls to have an end time. This becomes relevant in some cases where the purpose of a poll is to have a live register of ongoing consensus. Some other use cases come into picture when you want to deploy a set of action contracts which read from the poll, and want to be able to execute the action contract whenever a poll reaches a certain threshold, rather than waiting for the end of the poll. 4. Modularization: There have been opinions in the Ethereum community that there cannot exist a voting standard, because voting contracts can be of various types, and have several shapes and forms. However we disagree, and make the case that modularization is the solution. While different polls may need different logic, they all need consistent end points. All polls need to give out results along with headcounts, all polls should have event logs, all polls should be examinable with frontend tools, and so on. The poll standard is not a statement saying “all polls should be token based” or any such specific system. However the poll standard is a statement saying that all polls should have a common access and modification protocol - this will enable more apps to include governance without having to go through the trouble of making customers start using command line. Having explained our rationale, we are looking forward to hearing from the community some thoughts on how this can be made more useful or powerful. **Gas and Complexity** (regarding the enumeration for proposal count) This specification contemplates implementations that contain a sample of 32 proposals (max up to blockgaslimit). If your application is able to grow and needs more than 32 proposals, then avoid using for/while loops in your code. These indicate your contract may be unable to scale and gas costs will rise over time without bound **Privacy** Personal information: The standard does not put any personal information on to the blockchain, so there is no compromise of privacy in that respect. **Community Consensus** We have been very inclusive in this process and invite anyone with questions or contributions into our discussion. However, this standard is written only to support the identified use cases which are listed herein. ## Test Cases Voting Standard includes test cases written using Truffle. ## Implementations Voting Standard -- a reference implementation - MIT licensed, so you can freely use it for your projects - Includes test cases - Also available as a npm package - npm i electusvoting ## References **Standards** - [EIP-20: ERC-20 Token Standard (a.k.a. ERC-20)](./eip-20.md) - [EIP-165: Standard Interface Detection](./eip-165.md) - [EIP-721: Non-Fungible Token Standard(a.k.a. ERC-721)](./eip-721.md) - [ERC-1261 MV Token Standard](./eip-1261.md) - [RFC 2119 Key words for use in RFCs to Indicate Requirement Levels](https://www.ietf.org/rfc/rfc2119.txt) **Issues** 1. The Original ERC-1417 Issue. https://github.com/ethereum/eips/issues/1417 1. Solidity Issue \#2330 -- Interface Functions are Axternal. https://github.com/ethereum/solidity/issues/2330 1. Solidity Issue \#3412 -- Implement Interface: Allow Stricter Mutability. https://github.com/ethereum/solidity/issues/3412 1. Solidity Issue \#3419 -- Interfaces Can't Inherit. https://github.com/ethereum/solidity/issues/3419 **Discussions** 1. ERC-1417 (announcement of first live discussion). https://github.com/ethereum/eips/issues/1417 **Voting Implementations and Other Projects** - [Voting Implementations](https://github.com/chaitanyapotti/Voting) ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

dApp Components (avatar) & Universal Wallet

Fri, 21 Sep 2018 00:00:00 +0000

## Simple Summary Contracts are open source based. And most developers use the public contracts at the start of the project to modify or simply include them. This is project-oriented centralized development and I think it is a waste of resources. Therefore, we propose to make dApp or contracts component-ready for use in other services. ## Abstract There have been suggestions for modified tokens based on erc20, but since many tokens have already been built on erc20, it is necessary to increase the utilization of already developed erc20 tokens. Therefore, we propose a universal wallet that can use erc20 tokens universally. We also propose a component dApp that allows you to create and save your avatar (& social badge system), and use it immediately in other services. All of the dApps suggested in this document are based on decentralized development and use that anyone can create and participate in. ## Motivation While many projects are under development in an open source way, they are simply adding and deploy with open sources to their projects. This means that you are developing a centralized service that uses your own dApp-generated information on your own. In order to improve the block chain ecosystem, all resources created by dApp and placed in the public block chain must be reusable in another dApp. This means that you can enhance your service by exchanging the generated information with other dApp. Likewise, ERC20 Tokens require Universal Wallet standards to be easy to use for direct transactions. ### Seeds for improvement of the blockchain ecosystem. - Synergy - With other dApps and resources. - Enhanced interface - For ERC20 tokens. - Easy & Decentralized - Everyone should be able to add to their services easily, without censorship. #### The following avatar store, badge system, and universal wallet are kind of examples about component dApp. ![intro](../assets/eip-1438/intro.png) ## Specification ### 1. Avatar #### 1.1. Avatar Shop - The avatar store is created after ERC20 currency is set. - You can customize asset category & viewer script. #### 1.2. Upload asset & user data The avatar's information & assets are stored in the event log part of the block chain. - Assets are SVG format. (compressed with gzip) - avatar information data is json (compressed with msgpack) ![avatar](../assets/eip-1438/avatar.png) ** The avatar assets from [Avataaars](https://github.com/fangpenlin/avataaars) developed by [Fang-Pen Lin](https://twitter.com/fangpenlin), the original avatar is designed by [Pablo Stanley](https://twitter.com/pablostanley). ### 2. Universal Wallet ![wallet](../assets/eip-1438/wallet.png) #### 2.1. ERC20 interface ``` js contract ERC20Interface { function totalSupply() public constant returns (uint); function balanceOf(address tokenOwner) public constant returns (uint balance); function allowance(address tokenOwner, address spender) public constant returns (uint remaining); function transfer(address to, uint tokens) public returns (bool success); function approve(address spender, uint tokens) public returns (bool success); function transferFrom(address from, address to, uint tokens) public returns (bool success); event Transfer(address indexed from, address indexed to, uint tokens); event Approval(address indexed tokenOwner, address indexed spender, uint tokens); } ``` #### 2.2. Fixed ERC20 contract for receive approval and execute function in one call ``` js function approveAndCall(address spender, uint tokens, bytes data) public returns (bool success) { allowed[msg.sender][spender] = tokens; emit Approval(msg.sender, spender, tokens); ApproveAndCallFallBack(spender).receiveApproval(msg.sender, tokens, this, data); return true; } ``` #### 2.3. And ApproveAndCallFallBack contract for Fixed ERC20. However, many ERC20 tokens are not prepared. ``` js contract ApproveAndCallFallBack { function receiveApproval(address from, uint256 tokens, address token, bytes data) public; } ``` #### 2.4. Universal Wallet We propose a Universal Wallet to solve this problem. ``` js contract UniversalWallet is _Base { constructor(bytes _msgPack) _Base(_msgPack) public {} function () public payable {} //------------------------------------------------------- // erc20 interface //------------------------------------------------------- function balanceOf(address _erc20) public constant returns (uint balance) { if(_erc20==address(0)) return address(this).balance; return _ERC20Interface(_erc20).balanceOf(this); } function transfer(address _erc20, address _to, uint _tokens) onlyOwner public returns (bool success) { require(balanceOf(_erc20)>=_tokens); if(_erc20==address(0)) _to.transfer(_tokens); else return _ERC20Interface(_erc20).transfer(_to,_tokens); return true; } function approve(address _erc20, address _spender, uint _tokens) onlyOwner public returns (bool success) { require(_erc20 != address(0)); return _ERC20Interface(_erc20).approve(_spender,_tokens); } //------------------------------------------------------- // pay interface //------------------------------------------------------- function pay(address _store, uint _tokens, uint256[] _options) onlyOwner public { address erc20 = _ApproveAndCallFallBack(_store).erc20(); address spender = _ApproveAndCallFallBack(_store).spender(); if(erc20 == address(0)) { transfer(erc20,spender,_tokens); _ApproveAndCallFallBack(_store).receiveApproval(_options); } else { _ERC20Interface(erc20).approve(spender,_tokens); _ApproveAndCallFallBack(_store).receiveApproval(_options); } } function pay(address _store, uint _tokens, bytes _msgPack) onlyOwner public { address erc20 = _ApproveAndCallFallBack(_store).erc20(); address spender = _ApproveAndCallFallBack(_store).spender(); if(erc20 == address(0)) { transfer(erc20,spender,_tokens); _ApproveAndCallFallBack(_store).receiveApproval(_msgPack); } else { _ERC20Interface(erc20).approve(spender,_tokens); _ApproveAndCallFallBack(_store).receiveApproval(_msgPack); } } } ``` ## Test Cases - https://www.nitro888.com - https://github.com/Nitro888/nitro888.github.io - https://github.com/Nitro888/dApp-Alliance ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Localized Messaging with Signal-to-Text

Sun, 23 Sep 2018 00:00:00 +0000

## Simple Summary A method of converting machine codes to human-readable text in any language and phrasing. ## Abstract An on-chain system for providing user feedback by converting machine-efficient codes into human-readable strings in any language or phrasing. The system does not impose a list of languages, but rather lets users create, share, and use the localizated text of their choice. ## Motivation There are many cases where an end user needs feedback or instruction from a smart contract. Directly exposing numeric codes does not make for good UX or DX. If Ethereum is to be a truly global system usable by experts and lay persons alike, systems to provide feedback on what happened during a transaction are needed in as many languages as possible. Returning a hard-coded string (typically in English) only serves a small segment of the global population. This standard proposes a method to allow users to create, register, share, and use a decentralized collection of translations, enabling richer messaging that is more culturally and linguistically diverse. There are several machine efficient ways of representing intent, status, state transition, and other semantic signals including booleans, enums and [ERC-1066 codes](./eip-1066.md). By providing human-readable messages for these signals, the developer experience is enhanced by returning easier to consume information with more context (ex. `revert`). End user experience is enhanced by providing text that can be propagated up to the UI. ## Specification ### Contract Architecture Two types of contract: `LocalizationPreferences`, and `Localization`s. The `LocalizationPreferences` contract functions as a proxy for `tx.origin`. ```diagram +--------------+ | | +------> | Localization | | | | | +--------------+ | | +-----------+ +-------------------------+ | +--------------+ | | | | <------+ | | | Requestor | <------> | LocalizationPreferences | <-------------> | Localization | | | | | <------+ | | +-----------+ +-------------------------+ | +--------------+ | | | +--------------+ | | | +------> | Localization | | | +--------------+ ``` ### `Localization` A contract that holds a simple mapping of codes to their text representations. ```solidity interface Localization { function textFor(bytes32 _code) external view returns (string _text); } ``` #### `textFor` Fetches the localized text representation. ```solidity function textFor(bytes32 _code) external view returns (string _text); ``` ### `LocalizationPreferences` A proxy contract that allows users to set their preferred `Localization`. Text lookup is delegated to the user's preferred contract. A fallback `Localization` with all keys filled MUST be available. If the user-specified `Localization` has not explicitly set a loalization (ie. `textFor` returns `""`), the `LocalizationPreferences` MUST redelegate to the fallback `Localization`. ```solidity interface LocalizationPreferences { function set(Localization _localization) external returns (bool); function textFor(bytes32 _code) external view returns (bool _wasFound, string _text); } ``` #### `set` Registers a user's preferred `Localization`. The registering user SHOULD be considered `tx.origin`. ```solidity function set(Localization _localization) external; ``` #### `textFor` Retrieve text for a code found at the user's preferred `Localization` contract. The first return value (`bool _wasFound`) represents if the text is available from that `Localization`, or if a fallback was used. If the fallback was used in this context, the `textFor`'s first return value MUST be set to `false`, and is `true` otherwise. ```solidity function textFor(bytes32 _code) external view returns (bool _wasFound, string _text); ``` ### String Format All strings MUST be encoded as [UTF-8](https://www.ietf.org/rfc/rfc3629.txt). ```solidity "Špeĉiäl chârãçtérs are permitted" "As are non-Latin characters: アルミ缶の上にあるみかん。" "Emoji are legal: 🙈🙉🙊🎉" "Feel free to be creative: (ﾉ◕ヮ◕)ﾉ*:･ﾟ✧" ``` ### Templates Template strings are allowed, and MUST follow the [ANSI C `printf`](https://pubs.opengroup.org/onlinepubs/009696799/utilities/printf.html) conventions. ```solidity "Satoshi's true identity is %s" ``` Text with 2 or more arguments SHOULD use the POSIX parameter field extension. ```solidity "Knock knock. Who's there? %1$s. %1$s who? %2$s!" ``` ## Rationale ### `bytes32` Keys `bytes32` is very efficient since it is the EVM's base word size. Given the enormous number of elements (card(A) > 1.1579 × 10⁷⁷), it can embed nearly any practical signal, enum, or state. In cases where an application's key is longer than `bytes32`, hashing that long key can map that value into the correct width. Designs that use datatypes with small widths than `bytes32` (such as `bytes1` in [ERC-1066](./eip-1066.md)) can be directly embedded into the larger width. This is a trivial one-to-one mapping of the smaller set into the larger one. ### Local vs Globals and Singletons This spec has opted to not _force_ a single global registry, and rather allow any contract and use case deploy their own system. This allows for more flexibility, and does not restrict the community for opting to use singleton `LocalizationPreference` contracts for common use cases, share `Localization`s between different proxys, delegate translations between `Localization`s, and so on. There are many practical uses of agreed upon singletons. For instance, translating codes that aim to be fairly universal and integrated directly into the broader ecosystem (wallets, frameworks, debuggers, and the like) will want to have a single `LocalizationPreference`. Rather the dispersing several `LocalizationPreference`s for different use cases and codes, one could imagine a global "registry of registries". While this approach allows for a unified lookups of all translations in all use cases, it is antithetical to the spirit of decentralization and freedom. Such a system also increases the lookup complexity, places an onus on getting the code right the first time (or adding the overhead of an upgradable contract), and need to account for use case conflicts with a "unified" or centralized numbering system. Further, lookups should be lightweight (especially in cases like looking up revert text). For these reasons, this spec chooses the more decentralized, lightweight, free approach, at the cost of on-chain discoverability. A registry could still be compiled, but would be difficult to enforce, and is out of scope of this spec. ### Off Chain Storage A very viable alternative is to store text off chain, with a pointer to the translations on-chain, and emit or return a `bytes32` code for another party to do the lookup. It is difficult to guarantee that off-chain resources will be available, and requires coordination from some other system like a web server to do the code-to-text matching. This is also not compatible with `revert` messages. ### ASCII vs UTF-8 vs UTF-16 UTF-8 is the most widely used encoding at time of writing. It contains a direct embedding of ASCII, while providing characters for most natural languages, emoji, and special characters. Please see the [UTF-8 Everywhere Manifesto](https://utf8everywhere.org/) for more information. ### When No Text is Found Returning a blank string to the requestor fully defeats the purpose of a localization system. The two options for handling missing text are: 1. A generic "text not found" message in the preferred language 2. The actual message, in a different language #### Generic Option This designed opted to not use generic fallback text. It does not provide any useful information to the user other than to potentially contact the `Localization` maintainer (if one even exists and updating is even possible). #### Fallback Option The design outlined in this proposal is to providing text in a commonly used language (ex. English or Mandarin). First, this is the language that will be routed to if the user has yet to set a preference. Second, there is a good chance that a user may have _some_ proficiency with the language, or at least be able to use an automated translation service. Knowing that the text fell back via `textFor`s first return field boolean is _much_ simpler than attempting language detection after the fact. This information is useful for certain UI cases. for example where there may be a desire to explain why localization fell back. ### Decentralized Text Crowdsourcing In order for Ethereum to gain mass adoption, users must be able to interact with it in the language, phrasing, and level of detail that they are most comfortable with. Rather than imposing a fixed set of translations as in a traditional, centralized application, this EIP provides a way for anyone to create, curate, and use translations. This empowers the crowd to supply culturally and linguistically diverse messaging, leading to broader and more distributed access to information. ### `printf`-style Format Strings C-style `printf` templates have been the de facto standard for some time. They have wide compatibility across most languages (either in standard or third-party libraries). This makes it much easier for the consuming program to interpolate strings with low developer overhead. #### Parameter Fields The POSIX parameter field extension is important since languages do not share a common word order. Parameter fields enable the reuse and rearrangement of arguments in different localizations. ```solidity ("%1$s is an element with the atomic number %2$d!", "Mercury", 80); // => "Mercury is an element with the atomic number 80!" ``` #### Simplified Localizations Localization text does not require use of all parameters, and may simply ignore values. This can be useful for not exposing more technical information to users that would otherwise find it confusing. ```ruby #!/usr/bin/env ruby sprintf("%1$s é um elemento", "Mercurio", 80) # => "Mercurio é um elemento" ``` ```clojure #!/usr/bin/env clojure (format "Element #%2$s" "Mercury" 80) ;; => Element #80 ``` ### Interpolation Strategy Please note that it is highly advisable to return the template string _as is_, with arguments as multiple return values or fields in an `event`, leaving the actual interpolation to be done off chain. ```solidity event AtomMessage { bytes32 templateCode; bytes32 atomCode; uint256 atomicNumber; } ``` ```javascript #!/usr/bin/env node var printf = require('printf'); const { returnValues: { templateCode, atomCode, atomicNumber } } = eventResponse; const template = await AppText.textFor(templateCode); // => "%1$s ist ein Element mit der Ordnungszahl %2$d!" const atomName = await PeriodicTableText.textFor(atomCode); // => "Merkur" printf(template, atomName, 80); // => "Merkur ist ein Element mit der Ordnungszahl 80!" ``` ### Unspecified Behaviour This spec does not specify: * Public or private access to the default `Localization` * Who may set text * Deployer * `onlyOwner` * Anyone * Whitelisted users * and so on * When text is set * `constructor` * Any time * Write to empty slots, but not overwrite existing text * and so on These are intentionally left open. There are many cases for each of these, and restricting any is fully beyond the scope of this proposal. ## Implementation ```solidity pragma solidity ^0.4.25; contract Localization { mapping(bytes32 => string) private dictionary_; constructor() public {} // Currently overwrites anything function set(bytes32 _code, string _message) external { dictionary_[_code] = _message; } function textFor(bytes32 _code) external view returns (string _message) { return dictionary_[_code]; } } contract LocalizationPreference { mapping(address => Localization) private registry_; Localization public defaultLocalization; bytes32 private empty_ = keccak256(abi.encodePacked("")); constructor(Localization _defaultLocalization) public { defaultLocalization = _defaultLocalization; } function set(Localization _localization) external returns (bool) { registry_[tx.origin] = _localization; return true; } function get(bytes32 _code) external view returns (bool, string) { return get(_code, tx.origin); } // Primarily for testing function get(bytes32 _code, address _who) public view returns (bool, string) { string memory text = getLocalizationFor(_who).textFor(_code); if (keccak256(abi.encodePacked(text)) != empty_) { return (true, text); } else { return (false, defaultLocalization.textFor(_code)); } } function getLocalizationFor(address _who) internal view returns (Localization) { if (Localization(registry_[_who]) == Localization(0)) { return Localization(defaultLocalization); } else { return Localization(registry_[tx.origin]); } } } ``` ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

ERC-1450 A compatible security token for issuing and trading SEC-compliant securities

Tue, 25 Sep 2018 00:00:00 +0000

# ERC-1450 - A compatible security token for issuing and trading SEC-compliant securities ## Simple Summary `ERC-1450` is an `ERC-20` compatible token that enables issuing tokens representing securities that are required to comply with one or more of the following [Securities Act Regulations: Regulation Crowdfunding, Regulation D, and Regulation A](https://www.sec.gov/smallbusiness/exemptofferings). ## Abstract `ERC-1450` facilitates the recording of ownership and transfer of securities sold in compliance with the [Securities Act Regulations CF, D and A](https://www.sec.gov/smallbusiness/exemptofferings). The issuance and trading of securities is subject to the Securities Exchange Commission (SEC) and specific U.S. state blue sky laws and regulations. `ERC-1450` manages securities ownership during issuance and trading. The Issuer is the only role that should create a `ERC-1450` and assign the RTA. The RTA is the only role that is allowed to execute `ERC-1450`’s `mint`, `burnFrom`, and `transferFrom` functions. No role is allowed to execute `ERC-1450`’s `transfer` function. ## Motivation With the advent of the [JOBS Act](https://www.sec.gov/spotlight/jobs-act.shtml) in 2012 and the launch of Regulation Crowdfunding and the amendments to Regulation A and Regulation D in 2016, there has been an expansion in the exemptions available to Issuers and Investors to sell and purchase securities that have not been "registered" with the SEC under the Securities Act of 1933. There are currently no token standards that expressly facilitate conformity to securities law and related regulations. ERC-20 tokens do not support the regulated roles of Funding Portal, Broker Dealer, RTA, and Investor and do not support the [Bank Secrecy Act/USA Patriot Act KYC and AML requirements](https://www.occ.treas.gov/topics/compliance-bsa/bsa/index-bsa.html). Other improvements (notably [EIP-1404 (Simple Restricted Token Standard)](https://github.com/ethereum/EIPs/issues/1404) have tried to tackle KYC and AML regulatory requirement. This approach is novel because the RTA is solely responsible for performing KYC and AML and should be solely responsible for `transferFrom`, `mint`, and `burnFrom`. ## Specification `ERC-1450` extends `ERC-20`. ### `ERC-1450` `ERC-1450` requires that only the Issuer can create a token representing the security that only the RTA manages. Instantiating the `ERC-1450` requires the `Owned` and `IssuerControlled` modifiers, and only the Issuer should execute the `ERC-1450` constructor for a compliant token. `ERC-1450` extends the general `Ownable` modifier to describe a specific subset of owners that automate and decentralize compliance through the contract modifiers `Owned` and `IssuerControlled` and the function modifiers `onlyOwner` and `onlyIssuerTransferAgent`. The `Owned` contract modifier instantiates the `onlyOwner` modifier for functions. The `IssuerControlled` modifier instantiates the `onlyIssuerTransferAgent` modifier for functions. `ERC-1450` must prevent anyone from executing the `transfer`, `allowance`, and `approve` functions and/or implement these functions to always fail. `ERC-1450` updates the `transferFrom`, `mint`, and `burnFrom` functions. `transferFrom`, `mint`, and `burnFrom` may only be executed by the RTA and are restricted with the `onlyIssuerTransferAgent` modifier. Additionally, `ERC-1450` defines the functions `transferOwnership`, `setTransferAgent`, `setPhysicalAddressOfOperation`, and `isTransferAgent`. Only the issuer may call the `transferOwnership`, `setTransferAgent`, and `setPhysicalAddressOfOperation` functions. Anyone may call the `isTransferAgent` function. ### Issuers and RTAs For compliance reasons, the `ERC-1450` constructor must specify the issuer (the `owner`), the RTA (`transferAgent`), the security’s `name`, and the security’s `symbol`. #### Issuer Owned `ERC-1450` must specify the `owner` in its constructor, apply the `Owned` modifier, and instantiate the `onlyOwner` modifier to enable specific functions to permit only the Issuer’s `owner` address to execute them. `ERC-1450` also defines the function `transferOwnership` which transfers ownership of the Issuer to the new `owner`’s address and can only be called by the `owner`. `transferOwnership` triggers the `OwnershipTransferred` event. #### Issuer Controlled `IssuerControlled` maintains the Issuer’s ownership of their securities by owning the contract and enables the Issuer to set and update the RTA for the Issuer’s securities. `ERC-1450`‘s constructor must have an `IssuerControlled` modifier with the issuer specified in its `ERC-1450` constructor. `IssuerControlled` instantiates the `onlyIssuerTransferAgent` modifier for `ERC-1450` to enable specific functions (`setPhysicalAddressOfOperation` and `setTransferAgent`) to permit only the Issuer to execute these functions. #### Register Transfer Agent Controlled `ERC-1450` defines the `setTransferAgent` function (to change the RTA) and `setPhysicalAddressOfOperation` function (to change the Issuer’s address) and must restrict execution to the Issuer’s owner with the `onlyOwner` modifier. `setTransferAgent` must emit the `TransferAgentUpdated` event. `setPhysicalAddressOfOperation` must emit the `PhysicalAddressOfOperationUpdated` event. `ERC-1450` must specify the `transferAgent` in its constructor and instantiate the `onlyIssuerTransferAgent` modifier to enable specific functions (`transferFrom`, `mint`, and `burnFrom`) to permit only the Issuer’s `transferAgent` address to execute them. `ERC-1450` also defines the public function `isTransferAgent` to lookup and identify the Issuer’s RTA. #### Securities `ERC-1450` updates the `transferFrom`, `mint`, and `burnFrom` functions by applying the `onlyIssuerTransferAgent` to enable the issuance, re-issuance, and trading of securities. ### ERC-20 Extension `ERC-20` tokens provide the following functionality: ```solidity contract ERC20 { function totalSupply() public view returns (uint256); function balanceOf(address who) public view returns (uint256); function transfer(address to, uint256 value) public returns (bool); function allowance(address owner, address spender) public view returns (uint256); function transferFrom(address from, address to, uint256 value) public returns (bool); function approve(address spender, uint256 value) public returns (bool); event Approval(address indexed owner, address indexed spender, uint256 value); event Transfer(address indexed from, address indexed to, uint256 value); } ``` `ERC-20` is extended as follows: ```solidity /** * ERC-1450 is an ERC-20 compatible token that facilitates compliance with one or more of Securities Act Regulations CF, D and A. * * Implementations of the ERC-1450 standard must define the following optional ERC-20 * fields: * * name - The name of the security * symbol - The symbol of the security * * Implementations of the ERC-1450 standard must specify the following constructor * arguments: * * _owner - the address of the owner * _transferAgent - the address of the transfer agent * _name - the name of the security * _symbol - the symbol of the security * * Implementations of the ERC-1450 standard must implement the following contract * modifiers: * * Owned - Only the address of the security’s issuer is permitted to execute the * token’s constructor. This modifier also sets up the onlyOwner function modifier. * IssuerControlled - This modifier sets up the onlyIssuerTransferAgent function modifier. * * Implementations of the ERC-1450 standard must implement the following function * modifiers: * * onlyOwner - Only the address of the security’s issuer is permitted to execute the * functions transferOwnership, setTransferAgent, and setPhysicalAddressOfOperation. * onlyIssuerTransferAgent - Only the address of the issuer’s Registered Transfer * Agent is permitted to execute the functions transferFrom, mint, and burnFrom. * * Implementations of the ERC-1450 standard must implement the following required ERC-20 * event to always fail: * * Approval - Should never be called as the functions that emit this event must be * implemented to always fail. * * Implementations of the ERC-1450 standard must implement the following required * ERC-20 functions to always fail: * * transfer - Not a legal, regulated call for transferring securities because * the token holder initiates the token transfer. The function must be implemented to * always fail. * allowance - Not a legal, regulated call for transferring securities because * the token holder may not allow third parties to initiate token transfers. The * function must be implemented to always fail. * approve - Not a legal, regulated call for transferring securities because * the token holder may not allow third parties to initiate token transfers. The * function must be implemented to always fail. * * Implementations of the ERC-1450 standard must implement the following optional * ERC-20 function: * decimals - Must return '0' because securities are indivisible entities. * * Implementations of the ERC-1450 standard must implement the following functions: * * mint - Only the address of the issuer's Registered Transfer Agent may create new * securities. * burnFrom - Only the address of the issuer’s Registered Transfer Agent may burn or * destroy securities. */ Contract ERC-1450 is Owned, IssuerControlled { /** * The constructor must implement a modifier (Owned) that creates the onlyOwner modifier * to allow only the address of the issuer (the owner) to execute the transferOwnership, * setTransferAgent, and setPhysicalAddressOfOperation functions. The construct must also * implement a modifier (TransferAgentControlled) that creates the onlyIssuerTransferAgent * modifier to allow only the address of the issuer’s Registered Transfer Agent to execute * the functions transferFrom, mint, and burnFrom). */ constructor(address _owner, address _transferAgent, string _name, string _symbol) Owned(_issuer) TransferAgentControlled(_transferAgent) public; /** * Specify that only the owner (issuer) may execute a function. * * onlyOwner requires the msg.sender to be the owner’s address. */ modifier onlyOwner(); /** * Specify that only the issuer’s transferAgent may execute a function. * * onlyIssuerTransferAgent requires the msg.sender to be the transferAgent’s address. */ modifier onlyIssuerTransferAgent(); /** * Transfer ownership of a security from one issuer to another issuer. * * transferOwnership must implement the onlyOwner modifier to only allow the * address of the issuer’s owner to transfer ownership. * transferOwnership requires the _newOwner address to be the address of the new * issuer. */ function transferOwnership(address _newOwner) public onlyOwner; /** * Triggered after transferOwnership is executed. */ event OwnershipTransferred() /** * Sets the transfer agent for the security. * * setTransferAgent must implement the onlyOwner modifier to only allow the * address of the issuer’s specify the security’s transfer agent. * setTransferAgent requires the _newTransferAgent address to be the address of the * new transfer agent. */ function setTransferAgent(address _newTransferAgent) public onlyOwner; /** * Triggered after setTransferAgent is executed. */ event TransferAgentUpdated(address indexed previousTransferAgent, address indexed newTransferAgent); /** * Sets the issuers physical address of operation. * * setPhysicalAddressOfOperation must implement the onlyOwner modifier to only allow * the address of the issuer’s owner to transfer ownership. * setPhysicalAddressOfOperation requires the _newPhysicalAddressOfOperation address * to be the new address of the issuer. */ function setPhysicalAddressOfOperation(string _newPhysicalAddressOfOperation) public onlyOwner; /** * Triggered after setPhysicalAddressOfOperation is executed. */ event PhysicalAddressOfOperationUpdated(string previousPhysicalAddressOfOperation, string newPhysicalAddressOfOperation); /** * Look up the security’s transfer agent. * * isTransferAgent is a public function. * isTransferAgent requires the _lookup address to determine if that address * is the security’s transfer agent. */ function isTransferAgent(address _lookup) public view returns (bool); /** * transfer is not a legal, regulated call and must be implemented to always fail. */ transfer(address to, uint tokens) public returns (bool success); /** * Approval does not have to be implemented. This event should never be triggered as * the functions that emit this even are not legal, regulated calls. */ event Approval(address indexed tokenOwner, address indexed spender, uint tokens); /** * allowance is not a legal, regulated call and must be implemented to always fail. */ allowance(address tokenOwner, address spender) public constant returns (uint remaining); /** * approve is not a legal, regulated call and must be implemented to always fail. */ approve(address spender, uint tokens) public returns (bool success); /** * Transfer securities. * * transferFrom must implement the onlyIssuerTransferAgent modifier to only allow the * address of the issuer’s Registered Transfer Agent to transfer `ERC-1450`s. * transferFrom requires the _from address to have _value tokens. * transferFrom requires that the _to address must not be 0 because securities must * not destroyed in this manner. */ function transferFrom(address _from, address _to, uint256 _value) public onlyIssuerTransferAgent returns (bool); /** * Create new securities. * * mint must implement the onlyIssuerTransferAgent modifier to only allow the address * of the issuer’s Registered Transfer Agent to mint `ERC-1450` tokens. * mint requires that the _to address must not be 0 because securities must * not destroyed in this manner. * mint must add _value tokens to the _to address and increase the totalSupply by * _value. * mint must emit the Transfer event. */ function mint(address _to, uint256 _value) public onlyIssuerTransferAgent returns (bool); /** * Burn or destroy securities. * * burnFrom must implement the onlyIssuerTransferAgent modifier to only allow the * address of the issuer’s Registered Transfer Agent to burn `ERC-1450`s. * burnFrom requires the _from address to have _value tokens. * burnFrom must subtract _value tokens from the _from address and decrease the * totalSupply by _value. * burnFrom must emit the Transfer event. */ function burnFrom(address _who, uint256 _value) public onlyIssuerTransferAgent returns (bool); } ``` ### Securities Exchange Commission Requirements The SEC has very strict requirements as to the specific roles that are allowed to perform specific actions. Specifically, only the RTA may `mint` and `transferFrom` securities. Implementers must maintain off-chain services and databases that record and track the Investor’s name, physical address, Ethereum address, and security ownership amount. The implementers and the SEC must be able to access the Investor’s private information on an as needed basis. Issuers and the RTA must be able to produce a current list of all Investors, including the names, addresses, and security ownership levels for every security at any given moment. Issuers and the RTA must be able to re-issue securities to Investors for a variety of regulated reasons. Private Investor information must never be publicly exposed on a public blockchain. ### Managing Investor Information Special care and attention must be taken to ensure that the personally identifiable information of Investors is never exposed or revealed to the public. ### Issuers who lost access to their address or private keys There is no recourse if the Issuer loses access to their address to an existing instance of their securities. Special care and efforts must be made by the Issuer to secure and safely store their address and associated private key. The Issuer can reassign ownership to another Issuer but not in the case where the Issuer loses their private key. If the Issuer loses access, the Issuer’s securities must be rebuilt using off-chain services. The Issuer must create (and secure) a new address. The RTA can read the existing Issuer securities, and the RTA can `mint` Investor securities accordingly under a new `ERC-1450` smart contract. ### Registered Transfer Agents who lost access to their address or private keys If the RTA loses access, the RTA can create a new Ethereum address, and the Issuer can execute the `setTransferAgent` function to reassign the RTA. ### Handling Investors (security owners) who lost access to their addresses or private keys Investors may “lose” their credentials for a number of reasons: they simply “lost” their credentials, they were hacked or the victim of fraud, they committed securities-related fraud, or a life event (like death) occurred. Because the RTA manages the Issuer’s securities, the RTA may authorize ownership related changes of securities (as long as they are properly notarized and verified). If an Investor (or, say, the Investor’s heir) loses their credentials, the Investor must go through a notarized process to notify the RTA of the situation and supply a new Investor address. From there, the RTA can `mint` the “lost” securities to the new Investor address and `burnFrom` the old Investor address (because the RTA knows all Investors’ addresses). ## Rationale The are currently no token standards that facilitate compliance with SEC regulations. The closest token is [ERC-884 (Delaware General Corporations Law (DGCL) compatible share token)](./eip-884.md) which states that SEC requirements are out of scope. [EIP-1404 (Simple Restricted Token Standard)](https://github.com/ethereum/EIPs/issues/1404) does not go far enough to address SEC requirements around re-issuing securities to Investors. ## Backwards Compatibility `ERC-1450` maintains compatibility with ERC-20 tokens with the following stipulations: * `function allowance(address tokenOwner, address spender) public constant returns (uint remaining);` * Must be implemented to always fail because allowance is not a legal, regulated call for a security. * `function transfer(address to, uint tokens) public returns (bool success);` * As the token holder initiates the transfer, must be implemented to always fail because transfer is not a legal, regulated call for a security. * `function approve(address spender, uint tokens) public returns (bool success);` * Must be implemented to always fail because approve is not a legal, regulated call for a security * `function transferFrom(address from, address to, uint tokens) public returns (bool success);` * Must be implemented so that only the Issuer’s RTA can perform this action * `event Approval(address indexed tokenOwner, address indexed spender, uint tokens);` * Does not have to be implemented. Approval should never be called as the functions that emit this event must be implemented to always fail ## Test Cases Test cases are available at [https://github.com/StartEngine/ldgr_smart_contracts/tree/master/test](https://github.com/StartEngine/ldgr_smart_contracts/tree/master/test). ## Implementations A reference implementation is available at [https://github.com/StartEngine/ldgr_smart_contracts](https://github.com/StartEngine/ldgr_smart_contracts). ## Copyright Waiver Copyright and related rights waived via [CC0](/LICENSE).

Base Security Token

Mon, 01 Oct 2018 00:00:00 +0000

## Simple Summary An extension to ERC-20 standard token that provides compliance with securities regulations and legal enforceability. ## Abstract This EIP defines a minimal set of additions to the default token standard such as [ERC-20](./eip-20.md), that allows for compliance with domestic and international legal requirements. Such requirements include KYC (Know Your Customer) and AML (Anti Money Laundering) regulations, and the ability to lock tokens for an account, and restrict them from transfer due to a legal dispute. Also the ability to attach additional legal documentation, in order to set up a dual-binding relationship between the token and off-chain legal entities. The scope of this standard is being kept as narrow as possible to avoid restricting potential use-cases of this base security token. Any additional functionality and limitations not defined in this standard may be enforced on per-project basis. ## Motivation There are several security token standards that have been proposed recently. Examples include [ERC-1400](https://github.com/ethereum/EIPs/issues/1411), also [ERC-1450](https://eips.ethereum.org/EIPS/eip-1450). We have concerns about each of them, mostly because the scope of each of these EIPs contains many project-specific or market-specific details. Since many EIPs are coming from the respective backing companies, they capture many niche requirements that are excessive for a general case. For instance, ERC-1411 uses dependency on [ERC-1410](https://github.com/ethereum/eips/issues/1410) but it falls out of the "security tokens" scope. Also its dependency on [ERC-777](./eip-777.md) will block the adoption for a quite period of time before ERC-777 is finalized, but the integration guidelines for existing ERC-20 workflows are not described in that EIP, yet. Another attempt to make a much simpler base standard [ERC-1404](https://github.com/ethereum/EIPs/issues/1404) is missing a few important points, specifically it doesn't provide enough granularity to distinguish between different ERC-20 transfer functions such as `transfer` and `transferFrom`. It also doesn't provide a way to bind legal documentation to the issued tokens. What we propose in this EIP is a simple and very modular solution for creating a base security token for the widest possible scope of applications, so it can be used by other issuers to build upon. The issuers should be able to add more restrictions and policies to the token, using the functions and implementation proposed below, but they must not be limited in any way while using this ERC. ## Specification The ERC-20 token provides the following basic features: ```solidity contract ERC20 { function totalSupply() public view returns (uint256); function balanceOf(address who) public view returns (uint256); function transfer(address to, uint256 value) public returns (bool); function allowance(address owner, address spender) public view returns (uint256); function transferFrom(address from, address to, uint256 value) public returns (bool); function approve(address spender, uint256 value) public returns (bool); event Approval(address indexed owner, address indexed spender, uint256 value); event Transfer(address indexed from, address indexed to, uint256 value); } ``` This will be extended as follows: ```solidity interface BaseSecurityToken /* is ERC-20 */ { // Checking functions function checkTransferAllowed (address from, address to, uint256 value) public view returns (byte); function checkTransferFromAllowed (address from, address to, uint256 value) public view returns (byte); function checkMintAllowed (address to, uint256 value) public view returns (byte); function checkBurnAllowed (address from, uint256 value) public view returns (byte); // Documentation functions function attachDocument(bytes32 _name, string _uri, bytes32 _contentHash) external; function lookupDocument(bytes32 _name) external view returns (string, bytes32); } ``` ### Transfer Checking Functions We introduce four new functions that should be used to check that the actions are allowed for the provided inputs. The implementation details of each function are left for the token issuer, it is the issuer's responsibility to add all necessary checks that will validate an operation in accordance with KYC/AML policies and legal requirements set for a specific token asset. Each function must return a status code from the common set of Ethereum status codes (ESC), according to [ERC-1066](./eip-1066.md). Localization of these codes is out of the scope of this proposal and may be optionally solved by adopting [ERC-1444](./eip-1444.md) on the application level. If the operation is allowed by a checking function, the return status code must be `0x11` (Allowed) or an issuer-specific code with equivalent but more precise meaning. If the operation is not allowed by a checking function, the status must be `0x10` (Disallowed) or an issuer-specific code with equivalent but more precise meaning. Upon an internal error, the function must return the most relevant code from the general code table or an issuer-specific equivalent, example: `0xF0` (Off-Chain Failure). **For [ERC-20](./eip-20.md) based tokens,** * It is required that transfer function must be overridden with logic that checks the corresponding checkTransferAllowed return status code. * It is required that `transferFrom` function must be overridden with logic that checks the corresponding `checkTransferFromAllowed` return status code. * It is required that `approve` function must be overridden with logic that checks the corresponding `checkTransferFromAllowed` return status code. * Other functions such as `mint` and `burn` must be overridden, if they exist in the token implementation, they should check `checkMintAllowed` and `checkBurnAllowed` status codes accordingly. **For [ERC-777](./eip-777.md) based tokens,** * It is required that `send` function must be overridden with logic that checks the corresponding return status codes: - `checkTransferAllowed` return status code, if transfer happens on behalf of the tokens owner; - `checkTransferFromAllowed` return status code, if transfer happens on behalf of an operator (i.e. delegated transfer). * It is required that `burn` function must be overridden with logic that checks the corresponding `checkBurnAllowed` return status code. * Other functions, such as `mint` must be overridden, if they exist in the token implementation, e.g. if the security token is mintable. `mint` function must call `checkMintAllowed` ad check it return status code. For both cases, * It is required for guaranteed compatibility with ERC-20 and ERC-777 wallets that each checking function returns `0x11` (Allowed) if not overridden with the issuer's custom logic. * It is required that all overridden checking functions must revert if the action is not allowed or an error occurred, according to the returned status code. Inside checker functions the logic is allowed to use any feature available on-chain: perform calls to registry contracts with whitelists/blacklists, use built-in checking logic that is defined on the same contract, or even run off-chain queries through an oracle. ### Documentation Functions We also introduce two new functions that should be used for document management purposes. Function `attachDocument` adds a reference pointing to an off-chain document, with specified name, URI and contents hash. The hashing algorithm is not specified within this standard, but the resulting hash must not be longer than 32 bytes. Function `lookupDocument` gets the referenced document by its name. * It is not required to use documentation functions, they are optional and provided as a part of a legal framework. * It is required that if `attachDocument` function has been used, the document reference must have a unique name, overwriting the references under same name is not allowed. All implementations must check if the reference under the given name is already existing. ## Rationale This EIP targets both ERC-20 and ERC-777 based tokens, although the most emphasis is given to ERC-20 due to its widespread adoption. However, this extension is designed to be compatible with the forthcoming ERC-777 standard, as well. All checking functions are named with prefixes `check` since they return check status code, not booleans, because that is important to facilitate the debugging and tracing process. It is responsibility of the issuer to implement the logic that will handle the return codes appropriately. Some handlers will simply throw errors, other handlers would log information for future process mining. More rationale for status codes can be seen in [ERC-1066](./eip-1066.md). We require two different transfer validation functions: `checkTransferAllowed` and `checkTransferFromAllowed` since the corresponding `transfer` and `transferFrom` are usually called in different contexts. Some token standards such as [ERC-1450](./eip-1450.md) explicitly disallow use of `transfer`, while allowing only `transferFrom`. There might be also different complex scenarios, where `transfer` and `transferFrom` should be treated differently. ERC-777 is relying on its own `send` for transferring tokens, so it is reasonable to switch between checker functions based on its call context. We decided to omit the `checkApprove` function since it would be used in exactly the same context as `checkTransferFromAllowed`. In many cases it is required not only regulate securities transfers, but also restrict burn and `mint` operations, and additional checker functions have been added for that. The documentation functions that we propose here are a must-have tool to create dual-bindings with off-chain legal documents, a great example of this can be seen in [Neufund's Employee Incentive Options Plan](https://medium.com/@ZoeAdamovicz/37376fd0384a) legal framework that implements full legal enforceability: the smart contract refers to printed ESOP Terms & Conditions Document, which itself refers back to smart contract. This is becoming a widely adopted practice even in cases where there are no legal requirements to reference the documents within the security token. However they're almost always required, and it's a good way to attach useful documentation of various types. ## Backwards Compatibility This EIP is fully backwards compatible as its implementation extends the functionality of ERC-20 and ERC-777 tokens. ## Implementation * https://github.com/AtlantPlatform/BaseSecurityToken ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Digital Identity Aggregator

Fri, 12 Oct 2018 00:00:00 +0000

## Simple Summary A protocol for aggregating digital identity information that's broadly interoperable with existing, proposed, and hypothetical future digital identity standards. ## Abstract This EIP proposes an identity management and aggregation framework on the Ethereum blockchain. It allows entities to claim an `Identity` via a singular `Identity Registry` smart contract, associate it with Ethereum addresses in a variety of meaningful ways, and use it to interact with smart contracts. This enables arbitrarily complex identity-related functionality. Notably (among other features) ERC-1484 `Identities`: are self-sovereign, can natively support [ERC-725](./eip-725.md) and [ERC-1056](./eip-1056.md) identities, are [DID compliant](https://github.com/NoahZinsmeister/ERC-1484/blob/master/best-practices/DID-Method.md), and can be fully powered by [meta-transactions](https://github.com/NoahZinsmeister/ERC-1484/tree/master/contracts/examples/Providers/MetaTransactions). ## Motivation Emerging identity standards and related frameworks proposed by the Ethereum community (including ERCs/EIPs [725](./eip-725.md), [735](https://github.com/ethereum/EIPs/issues/735), [780](https://github.com/ethereum/EIPs/issues/780), [1056](./eip-1056.md), etc.) define and instrumentalize digital identity in a variety of ways. As existing approaches mature, new standards emerge, and isolated, non-standard approaches to identity develop, coordinating on identity will become increasingly burdensome for blockchain users and developers, and involve the unnecessary duplication of work. The proliferation of on-chain identity solutions can be traced back to the fact that each codifies a notion of identity and links it to specific aspects of Ethereum (claims protocols, per-identity smart contracts, signature verification schemes, etc.). This proposal eschews that approach, instead introducing a protocol layer in between the Ethereum network and individual identity applications. This solves identity management and interoperability challenges by enabling any identity-driven application to leverage an un-opinionated identity management protocol. ## Definitions - `Identity Registry`: A single smart contract which is the hub for all `Identities`. The primary responsibility of the `Registry` is to define and enforce the rules of a global namespace for `Identities`, which are individually denominated by Ethereum Identification Numbers (EINs). - `Identity`: A data structure containing all the core information relevant to an identity, namely: a `Recovery Address`, an `Associated Addresses` set, a `Providers` set, and a `Resolvers` set. `Identities` are denominated by EINs (incrementing `uint` identifiers starting at 1), which are unique but otherwise uninformative. Each `Identity` is a Solidity struct: ```solidity struct Identity { address recoveryAddress; AddressSet.Set associatedAddresses; AddressSet.Set providers; AddressSet.Set resolvers; } ``` - `Associated Address`: An Ethereum address publicly associated with an `Identity`. In order for an address to become an `Associated Address`, an `Identity` must either transact from or produce an appropriately signed message from the candidate address and an existing `Associated Address`, indicating intent to associate. An `Associated Address` can be removed from an `Identity` by transacting/producing a signature indicating intent to disassociate. A given address may only be an `Associated Address` for one `Identity` at any given time. - `Provider`: An Ethereum address (typically but not by definition a smart contract) authorized to act on behalf of `Identities` who have authorized them to do so. This includes but is not limited to managing the `Associated Address`, `Provider`, and `Resolver` sets for an `Identity`. `Providers` exist to facilitate user adoption by making it easier to manage `Identities`. - `Resolver`: A smart contract containing arbitrary information pertaining to `Identities`. A resolver may implement an identity standard, such as ERC-725, or may consist of a smart contract leveraging or declaring identifying information about `Identities`. These could be simple attestation structures or more sophisticated financial dApps, social media dApps, etc. Each `Resolver` added to an `Identity` makes the `Identity` more informative. - `Recovery Address`: An Ethereum address (either an account or smart contract) that can be used to recover lost `Identities` as outlined in the [Recovery](#recovery) section. - `Destruction`: In the event of irrecoverable loss of control of an `Identity`, `Destruction` is a contingency measure to permanently disable the `Identity`. It removes all `Associated Addresses`, `Providers`, and optionally `Resolvers` while preserving the `Identity`. Evidence of the existence of the `Identity` persists, while control over the `Identity` is nullified. ## Specification A digital identity in this proposal can be viewed as an omnibus account, containing more information about an identity than any individual identity application could. This omnibus identity is resolvable to an unlimited number of sub-identities called `Resolvers`. This allows an atomic entity, the `Identity`, to be resolvable to abstract data structures, the `Resolvers`. `Resolvers` recognize `Identities` by any of their `Associated Addresses`, or by their `EIN`. The protocol revolves around claiming an `Identity` and managing `Associated Addresses`, `Providers` and `Resolvers`. Identities can delegate much or all of this responsibility to one or more `Providers`, or perform it directly from an `Associated Address`. `Associated Addresses`/`Providers` may add and remove `Resolvers` and `Providers` indiscriminately. `Associated Addresses` may only be added or removed with the appropriate permission. ### Identity Registry The `Identity Registry` contains functionality to create new `Identities` and for existing `Identities` to manage their `Associated Addresses`, `Providers`, and `Resolvers`. It is important to note that this registry fundamentally requires transactions for every aspect of building out an `Identity`. However, recognizing the importance of accessibility to dApps and identity applications, we empower `Providers` to build out `Identities` on the behalf of users, without requiring users to pay gas costs. An example of this pattern, often referred to as a meta transactions, can be [seen in the reference implementation](https://github.com/NoahZinsmeister/ERC-1484/tree/master/contracts/examples/Providers/MetaTransactions). Due to the fact that multiple addresses can be associated with a given identity (though not the reverse), `Identities` are denominated by `EIN`. This `uint` identifier can be encoded in QR format or mapped to more user-friendly formats, such as a `string`, in registries at the `Provider` or `Resolver` level. ### Address Management The address management function consists of trustlessly connecting multiple user-owned `Associated Addresses` to an `Identity`. It does not give special status to any particular `Associated Address`, rather leaving this (optional) specification to identity applications built on top of the protocol - for instance, `management`, `action`, `claim` and `encryption` keys denominated in the ERC-725 standard, or `identifiers` and `delegates` as denominated in ERC-1056. This allows a user to access common identity data from multiple wallets while still: - retaining the ability to interact with contracts outside of their identity - taking advantage of address-specific permissions established at the application layer of a user's identity. Trustlessness in the address management function is achieved through a robust permissioning scheme. To add an `Associated Address` to an `Identity`, implicit permission from a transaction sender or explicit permission from a signature is required from 1) an address already within the registry and 2) an address to be claimed. Importantly, the transaction need not come from any particular address, as long as permission is established, which allows not only users but third parties (companies, governments, etc.) to bear the overhead of managing identities. To prevent a compromised `Associated Address` from unilaterally removing other `Associated Addresses`, it's only possible to remove an `Associated Address` by transacting or producing a signature from it. All signatures required in ERC-1484 are designed per the [ERC-191](./eip-191.md) v0 specification. To avoid replay attacks, all signatures must include a timestamp within a rolling lagged window of the current `block.timestamp`. For more information, see this [best practices document](https://github.com/NoahZinsmeister/ERC-1484/blob/master/best-practices/VerifyingSignatures.md) in the reference implementation. ### Provider Management While the protocol allows users to directly call identity management functions, it also aims to be more robust and future-proof by allowing `Providers`, typically smart contracts, to perform identity management functions on a user's behalf. A `Provider` set by an `Identity` can perform address management and resolver management functions by passing a user's `EIN` in function calls. ### Resolver Management A `Resolver` is any smart contract that encodes information which resolves to an `Identity`. We remain agnostic about the specific information that can be encoded in a resolver and the functionality that this enables. The existence of `Resolvers` is primarily what makes this ERC an identity *protocol* rather than an identity *application*. `Resolvers` resolve abstract data in smart contracts to an atomic entity, the `Identity`. ### Recovery If users lose control over an `Associated Address`, the `Recovery Address` provides a fallback mechanism. Upon `Identity` creation, a `Recovery Address` is passed as a parameter by the creator. Recovery functionality is triggered in three scenarios: **1. Changing Recovery Address**: If a recovery key is lost, an `Associated Address`/`Provider` can [triggerRecoveryAddressChange](#triggerrecoveryaddresschange)/[triggerRecoveryAddressChangeFor](#triggerrecoveryaddresschangefor). To prevent malicious behavior from someone who has gained control of an `Associated Address` or `Provider` and is changing the `Recovery Address` to one under their control, this action triggers a 14 day challenge period during which the old `Recovery Address` may reject the change by [triggering recovery](#triggerrecovery). If the `Recovery Address` does not reject the change within 14 days, the `Recovery Address` is changed. **2. Recovery**: Recovery occurs when a user recognizes that an `Associated Address` or the `Recovery Address` belonging to the user is lost or stolen. In this instance the `Recovery Address` must call [triggerRecovery](#triggerrecovery). This removes all `Associated Addresses` and `Providers` from the corresponding `Identity` and replaces them with an address passed in the function call. The `Identity` and associated `Resolvers` maintain integrity. The user is now responsible for adding the appropriate un-compromised addresses back to their `Identity`. *Importantly, the `Recovery Address` can be a user-controlled wallet or another address, such as a multisig wallet or smart contract. This allows for arbitrarily sophisticated recovery logic! This includes the potential for recovery to be fully compliant with standards such as [DID](https://decentralized.id/).* **3. Destruction** The Recovery scheme offers considerable power to a `Recovery Address`; accordingly, `Destruction` is a nuclear option to combat malicious control over an `Identity` when a `Recovery Address` is compromised. If a malicious actor compromises a user's `Recovery Address` and triggers recovery, any address removed in the `Recovery` process can call [triggerDestruction](#triggerdestruction) within 14 days to permanently disable the `Identity`. The user would then need to create a new `Identity`, and would be responsible for engaging in recovery schemes for any identity applications built in the `Resolver` or `Provider` layers. #### Alternative Recovery Considerations We considered many possible alternatives when devising the Recovery process outlined above. We ultimately selected the scheme that was most un-opinionated, modular, and consistent with the philosophy behind the `Associated Address`, `Provider`, and `Resolver` components. Still, we feel that it is important to highlight some of the other recovery options we considered, to provide a rationale as to how we settled on what we did. **High Level Concerns** Fundamentally, a Recovery scheme needs to be resilient to a compromised address taking control of a user's `Identity`. A secondary concern is preventing a compromised address from maliciously destroying a user's identity due to off-chain utility, which is not an optimal scenario, but is strictly better than if they've gained control. **Alternative 1: Nuclear Option** This approach would allow any `Associated Address` to destroy an `Identity` whenever another `Associated Address` is compromised. While this may seem severe, we strongly considered it because this ERC is an identity *protocol*, not an identity *application*. This means that though a user's compromised `Identity` is destroyed, they should still have recourse to whatever restoration mechanisms are available in each of their actual identities at the `Resolver` and/or `Provider` level. We ultimately dismissed this approach for two main reasons: - It is not robust in cases where a user has only one `Associated Address` - It would increase the frequency of recovery requests to identity applications due to its unforgiving nature. **Alternative 2: Unilateral Address Removal via Providers** This would allow `Associated Addresses`/`Providers` to remove `Associated Addresses` without a signature from said address. This implementation would allow `Providers` to include arbitrarily sophisticated schemes for removing a rogue address - for instance, multi-sig requirements, centralized off-chain verification, user controlled master addresses, deferral to a jurisdictional contract, and more. To prevent a compromised `Associated Address` from simply setting a malicious `Provider` to remove un-compromised addresses, it would have required a waiting period between when a `Provider` is set and when they would be able to remove an `Associated Address`. We dismissed this approach because we felt it placed too high of a burden on `Providers`. If a `Provider` offered a sophisticated range of functionality to a user, but post-deployment a threat was found in the Recovery logic of the provider, `Provider`-specific infrastructure would need to be rebuilt. We also considered including a flag that would allow a user to decide whether or not a `Provider` may remove `Associated Addresses` unilaterally. Ultimately, we concluded that only allowing removal of `Associated Addresses` via the `Recovery Address` enables equally sophisticated recovery logic while separating the functionality from `Providers`, leaving less room for users to relinquish control to potentially flawed implementations. ## Rationale We find that at a protocol layer, identities should not rely on specific claim or attestation structures, but should instead be a part of a trustless framework upon which arbitrarily sophisticated claim and attestation structures may be built. The main criticism of existing identity solutions is that they're overly restrictive. We aim to limit requirements, keep identities modular and future-proof, and remain un-opinionated regarding any functionality a particular identity component may have. This proposal gives users the option to interact on the blockchain using an robust `Identity` rather than just an address. ## Implementation **The reference implementation for ERC-1484 may be found in [NoahZinsmeister/ERC-1484](https://github.com/NoahZinsmeister/ERC-1484).** #### identityExists Returns a `bool` indicating whether or not an `Identity` denominated by the passed `EIN` exists. ```solidity function identityExists(uint ein) public view returns (bool); ``` #### hasIdentity Returns a `bool` indicating whether or not the passed `_address` is associated with an `Identity`. ```solidity function hasIdentity(address _address) public view returns (bool); ``` #### getEIN Returns the `EIN` associated with the passed `_address`. Throws if the address is not associated with an `EIN`. ```solidity function getEIN(address _address) public view returns (uint ein); ``` #### isAssociatedAddressFor Returns a `bool` indicating whether or not the passed `_address` is associated with the passed `EIN`. ```solidity function isAssociatedAddressFor(uint ein, address _address) public view returns (bool); ``` #### isProviderFor Returns a `bool` indicating whether or not the passed `provider` has been set by the passed `EIN`. ```solidity function isProviderFor(uint ein, address provider) public view returns (bool); ``` #### isResolverFor Returns a `bool` indicating whether or not the passed `resolver` has been set by the passed `EIN`. ```solidity function isResolverFor(uint ein, address resolver) public view returns (bool); ``` #### getIdentity Returns the `recoveryAddress`, `associatedAddresses`, `providers` and `resolvers` of the passed `EIN`. ```solidity function getIdentity(uint ein) public view returns ( address recoveryAddress, address[] memory associatedAddresses, address[] memory providers, address[] memory resolvers ); ``` #### createIdentity Creates an `Identity`, setting the `msg.sender` as the sole `Associated Address`. Returns the `EIN` of the new `Identity`. ```solidity function createIdentity(address recoveryAddress, address[] memory providers, address[] memory resolvers) public returns (uint ein); ``` Triggers event: [IdentityCreated](#identitycreated) #### createIdentityDelegated Performs the same logic as `createIdentity`, but can be called by any address. This function requires a signature from the `associatedAddress` to ensure their consent. ```solidity function createIdentityDelegated( address recoveryAddress, address associatedAddress, address[] memory providers, address[] memory resolvers, uint8 v, bytes32 r, bytes32 s, uint timestamp ) public returns (uint ein); ``` Triggers event: [IdentityCreated](#identitycreated) #### addAssociatedAddress Adds the `addressToAdd` to the `EIN` of the `approvingAddress`. The `msg.sender` must be either of the `approvingAddress` or the `addressToAdd`, and the signature must be from the other one. ```solidity function addAssociatedAddress( address approvingAddress, address addressToAdd, uint8 v, bytes32 r, bytes32 s, uint timestamp ) public ``` Triggers event: [AssociatedAddressAdded](#associatedaddressadded) #### addAssociatedAddressDelegated Adds the `addressToAdd` to the `EIN` of the `approvingAddress`. Requires signatures from both the `approvingAddress` and the `addressToAdd`. ```solidity function addAssociatedAddressDelegated( address approvingAddress, address addressToAdd, uint8[2] memory v, bytes32[2] memory r, bytes32[2] memory s, uint[2] memory timestamp ) public ``` Triggers event: [AssociatedAddressAdded](#associatedaddressadded) #### removeAssociatedAddress Removes the `msg.sender` as an `Associated Address` from its `EIN`. ```solidity function removeAssociatedAddress() public; ``` Triggers event: [AssociatedAddressRemoved](#associatedaddressremoved) #### removeAssociatedAddressDelegated Removes the `addressToRemove` from its associated `EIN`. Requires a signature from the `addressToRemove`. ```solidity function removeAssociatedAddressDelegated(address addressToRemove, uint8 v, bytes32 r, bytes32 s, uint timestamp) public; ``` Triggers event: [AssociatedAddressRemoved](#associatedaddressremoved) #### addProviders Adds an array of `Providers` to the `Identity` of the `msg.sender`. ```solidity function addProviders(address[] memory providers) public; ``` Triggers event: [ProviderAdded](#provideradded) #### addProvidersFor Performs the same logic as `addProviders`, but must be called by a `Provider`. ```solidity function addProvidersFor(uint ein, address[] memory providers) public; ``` Triggers event: [ProviderAdded](#provideradded) #### removeProviders Removes an array of `Providers` from the `Identity` of the `msg.sender`. ```solidity function removeProviders(address[] memory providers) public; ``` Triggers event: [ProviderRemoved](#providerremoved) #### removeProvidersFor Performs the same logic as `removeProviders`, but is called by a `Provider`. ```solidity function removeProvidersFor(uint ein, address[] memory providers) public; ``` Triggers event: [ProviderRemoved](#providerremoved) #### addResolvers Adds an array of `Resolvers` to the `EIN` of the `msg.sender`. ```solidity function addResolvers(address[] memory resolvers) public; ``` Triggers event: [ResolverAdded](#resolveradded) #### addResolversFor Performs the same logic as `addResolvers`, but must be called by a `Provider`. ```solidity function addResolversFor(uint ein, address[] memory resolvers) public; ``` Triggers event: [ResolverAdded](#resolveradded) #### removeResolvers Removes an array of `Resolvers` from the `EIN` of the `msg.sender`. ```solidity function removeResolvers(address[] memory resolvers) public; ``` Triggers event: [ResolverRemoved](#resolverremoved) #### removeResolversFor Performs the same logic as `removeResolvers`, but must be called by a `Provider`. ```solidity function removeResolversFor(uint ein, address[] memory resolvers) public; ``` Triggers event: [ResolverRemoved](#resolverremoved) #### triggerRecoveryAddressChange Initiates a change in the current `recoveryAddress` for the `EIN` of the `msg.sender`. ```solidity function triggerRecoveryAddressChange(address newRecoveryAddress) public; ``` Triggers event: [RecoveryAddressChangeTriggered](#recoveryaddresschangetriggered) #### triggerRecoveryAddressChangeFor Initiates a change in the current `recoveryAddress` for a given `EIN`. ```solidity function triggerRecoveryAddressChangeFor(uint ein, address newRecoveryAddress) public; ``` Triggers event: [RecoveryAddressChangeTriggered](#recoveryaddresschangetriggered) #### triggerRecovery Triggers `EIN` recovery from the current `recoveryAddress`, or the old `recoveryAddress` if changed within the last 2 weeks. ```solidity function triggerRecovery(uint ein, address newAssociatedAddress, uint8 v, bytes32 r, bytes32 s, uint timestamp) public; ``` Triggers event: [RecoveryTriggered](#recoverytriggered) #### triggerDestruction Triggers destruction of an `EIN`. This renders the `Identity` permanently unusable. ```solidity function triggerDestruction(uint ein, address[] memory firstChunk, address[] memory lastChunk, bool clearResolvers) public; ``` Triggers event: [IdentityDestroyed](#identitydestroyed) ### Events #### IdentityCreated MUST be triggered when an `Identity` is created. ```solidity event IdentityCreated( address indexed initiator, uint indexed ein, address recoveryAddress, address associatedAddress, address[] providers, address[] resolvers, bool delegated ); ``` #### AssociatedAddressAdded MUST be triggered when an address is added to an `Identity`. ```solidity event AssociatedAddressAdded( address indexed initiator, uint indexed ein, address approvingAddress, address addedAddress, bool delegated ); ``` #### AssociatedAddressRemoved MUST be triggered when an address is removed from an `Identity`. ```solidity event AssociatedAddressRemoved(address indexed initiator, uint indexed ein, address removedAddress, bool delegated); ``` #### ProviderAdded MUST be triggered when a provider is added to an `Identity`. ```solidity event ProviderAdded(address indexed initiator, uint indexed ein, address provider, bool delegated); ``` #### ProviderRemoved MUST be triggered when a provider is removed. ```solidity event ProviderRemoved(address indexed initiator, uint indexed ein, address provider, bool delegated); ``` #### ResolverAdded MUST be triggered when a resolver is added. ```solidity event ResolverAdded(address indexed initiator, uint indexed ein, address resolvers, bool delegated); ``` #### ResolverRemoved MUST be triggered when a resolver is removed. ```solidity event ResolverRemoved(address indexed initiator, uint indexed ein, address resolvers, bool delegated); ``` #### RecoveryAddressChangeTriggered MUST be triggered when a recovery address change is triggered. ```solidity event RecoveryAddressChangeTriggered( address indexed initiator, uint indexed ein, address oldRecoveryAddress, address newRecoveryAddress, bool delegated ); ``` #### RecoveryTriggered MUST be triggered when recovery is triggered. ```solidity event RecoveryTriggered( address indexed initiator, uint indexed ein, address[] oldAssociatedAddresses, address newAssociatedAddress ); ``` #### IdentityDestroyed MUST be triggered when an `Identity` is destroyed. ```solidity event IdentityDestroyed(address indexed initiator, uint indexed ein, address recoveryAddress, bool resolversReset); ``` ### Solidity Interface ```solidity interface IdentityRegistryInterface { function isSigned(address _address, bytes32 messageHash, uint8 v, bytes32 r, bytes32 s) external pure returns (bool); // Identity View Functions ///////////////////////////////////////////////////////////////////////////////////////// function identityExists(uint ein) external view returns (bool); function hasIdentity(address _address) external view returns (bool); function getEIN(address _address) external view returns (uint ein); function isAssociatedAddressFor(uint ein, address _address) external view returns (bool); function isProviderFor(uint ein, address provider) external view returns (bool); function isResolverFor(uint ein, address resolver) external view returns (bool); function getIdentity(uint ein) external view returns ( address recoveryAddress, address[] memory associatedAddresses, address[] memory providers, address[] memory resolvers ); // Identity Management Functions /////////////////////////////////////////////////////////////////////////////////// function createIdentity(address recoveryAddress, address[] calldata providers, address[] calldata resolvers) external returns (uint ein); function createIdentityDelegated( address recoveryAddress, address associatedAddress, address[] calldata providers, address[] calldata resolvers, uint8 v, bytes32 r, bytes32 s, uint timestamp ) external returns (uint ein); function addAssociatedAddress( address approvingAddress, address addressToAdd, uint8 v, bytes32 r, bytes32 s, uint timestamp ) external; function addAssociatedAddressDelegated( address approvingAddress, address addressToAdd, uint8[2] calldata v, bytes32[2] calldata r, bytes32[2] calldata s, uint[2] calldata timestamp ) external; function removeAssociatedAddress() external; function removeAssociatedAddressDelegated(address addressToRemove, uint8 v, bytes32 r, bytes32 s, uint timestamp) external; function addProviders(address[] calldata providers) external; function addProvidersFor(uint ein, address[] calldata providers) external; function removeProviders(address[] calldata providers) external; function removeProvidersFor(uint ein, address[] calldata providers) external; function addResolvers(address[] calldata resolvers) external; function addResolversFor(uint ein, address[] calldata resolvers) external; function removeResolvers(address[] calldata resolvers) external; function removeResolversFor(uint ein, address[] calldata resolvers) external; // Recovery Management Functions /////////////////////////////////////////////////////////////////////////////////// function triggerRecoveryAddressChange(address newRecoveryAddress) external; function triggerRecoveryAddressChangeFor(uint ein, address newRecoveryAddress) external; function triggerRecovery(uint ein, address newAssociatedAddress, uint8 v, bytes32 r, bytes32 s, uint timestamp) external; function triggerDestruction( uint ein, address[] calldata firstChunk, address[] calldata lastChunk, bool resetResolvers ) external; // Events ////////////////////////////////////////////////////////////////////////////////////////////////////////// event IdentityCreated( address indexed initiator, uint indexed ein, address recoveryAddress, address associatedAddress, address[] providers, address[] resolvers, bool delegated ); event AssociatedAddressAdded( address indexed initiator, uint indexed ein, address approvingAddress, address addedAddress ); event AssociatedAddressRemoved(address indexed initiator, uint indexed ein, address removedAddress); event ProviderAdded(address indexed initiator, uint indexed ein, address provider, bool delegated); event ProviderRemoved(address indexed initiator, uint indexed ein, address provider, bool delegated); event ResolverAdded(address indexed initiator, uint indexed ein, address resolvers); event ResolverRemoved(address indexed initiator, uint indexed ein, address resolvers); event RecoveryAddressChangeTriggered( address indexed initiator, uint indexed ein, address oldRecoveryAddress, address newRecoveryAddress ); event RecoveryTriggered( address indexed initiator, uint indexed ein, address[] oldAssociatedAddresses, address newAssociatedAddress ); event IdentityDestroyed(address indexed initiator, uint indexed ein, address recoveryAddress, bool resolversReset); } ``` ## Backwards Compatibility `Identities` established under this standard consist of existing Ethereum addresses; accordingly, there are no backwards compatibility issues. Deployed, non-upgradeable smart contracts that wish to become `Resolvers` for `Identities` will need to write wrapper contracts that resolve addresses to `EIN`-denominated `Identities`. ## Additional References - [ERC-1484 Reference Implementation](https://github.com/NoahZinsmeister/ERC-1484) - [ERC-191 Signatures](./eip-191.md) - [ERC-725 Identities](./eip-725.md) - [ERC-1056 Identities](./eip-1056.md) ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Human Cost Accounting Standard (Like Gas but for humans)

Fri, 12 Oct 2018 00:00:00 +0000

## Simple Summary A standard interface for Human Capital Accounting tokens. ## Abstract The following standard allows for the implementation of a standard API for HUCAP tokens within smart contracts. This standard provides basic functionality to discover, track and transfer the motivational hierarchy of human resources. While blockchain architecture has succeeded in the financialisation of integrity by way of transparency; correspondingly real world outcomes will be proportional to the degree of individualisation of capital by way of knowledge. ## Motivation The Ethereum protocol architecture has a deterministic world-view bounded to the random reality of the human domain that supplies the intentions and logic. The yellow paper formally defines the EVM as a state machine with only deterministic parameters and state transition operators. Oracle requests to another on-chain contract, and/or off-chain HTTP lookups still make for multiple deterministic transactions. A standard interface that allows the appraisal of individual capabilities concurrently with output and the overall knowledge-base will reduce market search costs and increase the autonomous insertion of mindful innovation into the blockchain ecosystem. We provide for simple smart contracts to define and track an arbitrarily large number of HUCAP assets. Additional applications are discussed below. The Belief-Desire-Intention model is a plan-theoretic framework for establishing means-end coherence in agent based modelling system. The blockchain's cryptographic security architecture reliably scales to a blockchain based PKI web-of-trust hierarchies. ERC-20 token standard allows any tokens on Ethereum to be re-used by other applications: from wallets to decentralized exchanges. ERC-721 token standard allows wallet/broker/auction applications to work with any NFT on Ethereum. ERC-1155 Crypto Item standard allows a smart contract interface where one can represent any number of ERC-20 and ERC-721 assets in a single contract. This standard is inspired by the belief–desire–intention (BDI) model of human practical reasoning developed by Michael Bratman as a way of explaining future-directed intention. A BDI agent is a particular type of bounded rational software agent, imbued with particular mental attitudes, viz: Beliefs, Desires and Intentions (BDI). The model identifies commitment as the distinguishing factor between desire and intention, and a noteworthy property that leads to (1) temporal persistence in plans and in the sense of explicit reference to time, (2) further plans being made on the basis of those to which it is already committed, (3) hierarchical nature of plans, since the overarching plan remains in effect while subsidiary plans are being executed. The BDI software model is an attempt to solve a problem of plans and planning choice and the execution thereof. The complement of which tenders a sufficient metric for indicating means-end coherence and ascribing cost baselines to such outcomes. ## Specification #### Main Interface ```solidity pragma solidity ^0.4.25; pragma experimental ABIEncoderV2; /** @title ERC-**** Human Capital Accounting Standard @dev See https://github.com/freeworkculture/kazini/issues/11 Note: the ERC-165 identifier for this interface is 0xf23a6e61. */ interface IERC_HUCAP { /** @notice Compute the index value of an Agents BDI in the ecosystem. @param _address Set the stance of an agent @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function updateIndex() internal returns (bool); /** @notice Get the active/inactive and states of an Agent in the ecosystem. @param _address Set the stance of an agent @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function iam() view public returns (bool iam_, IERC_HUCAP_TYPES.IS state_); /** @notice Fetch the bdi index value of an Agent in the ecosystem. @param _address Set the stance of an agent @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function index() view public returns (uint8 index_); /** @notice Count of Public Keys in key ring of an Agent in the ecosystem. @param _address Set the stance of an agent @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function ringLength() view public returns (uint ringlength_); /** @notice Get the PGP Public Key Id of an Agent in the ecosystem. @param "" Set the stance of an agent @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function keyId() view public returns (bytes32 KEYID_); /** @notice Get the merit data of an Agent in the ecosystem. @param "" Set the stance of an agent @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function merits() view public returns ( uint experience_, bytes32 reputation_, bytes32 talent_, uint8 index_, bytes32 hash_); /** @notice Get the accreditation of an Agent in the ecosystem. @param "" Set the stance of an agent @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function kbase() view public returns (IERC_HUCAP_TYPES.KBase kbase_); /** @notice Get the desire of an Agent in the ecosystem. @param _desire Pro-attitude @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function desire(bytes1 _desire) view external returns (bytes32); /** @notice Get the intention of an Agent in the ecosystem. @param _intention Conduct-controlling pro-attitude @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function intention(bool _intention) view external returns (bytes32); /** @notice Cycle the intention of an Agent in the ecosystem. @param _intention Conduct-controlling pro-attitude @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function flipIntention() external returns (bool); /** @notice Get the user data of an Agent in the ecosystem. @param "" Conduct-controlling pro-attitude @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function getDoer() view external returns ( bytes32 fPrint, bool iam_, bytes32 email, bytes32 fName, bytes32 lName, uint age, bytes32 data_); /** @notice Get the belief data of an Agent in the ecosystem. @param _kbase Source address @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function getBelief(IERC_HUCAP_TYPES.KBase _kbase) view external returns ( bytes32 country_, bytes32 cAuthority_, bytes32 score_); /** @notice Get the desire data of an Agent in the ecosystem. @param _desire Pro-attitides @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function getDesire(bytes1 _desire) view external returns (bytes32,bool); /** @notice Get the intention of an Agent in the ecosystem. @param _intention Conduct-controlling pro-attitude @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function getIntention(bool _intention) view external returns (IERC_HUCAP_TYPES.IS,bytes32,uint256); /** @notice Sign the Public Key of an Agent in the ecosystem. @param _address Address of key to sign, must belong to an Agent @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function sign(address _address) public onlyOwner returns (uint, bool signed); /** @notice Sign the Public Key of an Agent in the ecosystem. @param "" internal helper function to add key in keyring @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function sign() external onlyDoer returns (uint, bool signed); /** @notice Revoke the Public Key of an Agent in the ecosystem. @param _address Address of key to revoke, must belong to an Agent @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function revoke(address _address) external onlyDoer returns (uint, bool revoked); /** @notice Revoke the Public Key of an Agent in the ecosystem. @param "" internal helper function to remove key from keyring @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function revoke() external onlyDoer returns (uint, bool revoked); /** @notice Set the trust level for a Public Key of an Agent in the ecosystem. @param _level Degree of trust @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function trust(Trust _level) returns (bool); /** @notice Increment the number of keys in the keyring of an Agent in the ecosystem. @param _keyd Target key @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function incSigns(bytes32 _keyd) external ProxyKey returns (uint); /** @notice Decrement the number of keys in the keyring of an Agent in the ecosystem. @param _keyd Target key @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function decSigns(bytes32 _keyd) external ProxyKey returns (uint); /** @notice Set the knowledge credentials of an Agent in the ecosystem. @param _kbase Level of accreditation @param _country Source country @param _cAuthority Accreditation authority @param _score Accreditation @param _year Year of Accreditation @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function setbdi( KBase _kbase, bytes32 _country, bytes32 _cAuthority, bytes32 _score, uint _year ) external ProxyBDI returns (bool qualification_); /** @notice Set the SNA metrics of an Agent in the ecosystem @param _refMSD Minimum shortest distance @param _refRank Rank of target key @param _refSigned No of keys signed I have signed @param _refSigs No. of keys that have signed my key @param _refTrust Degree of tructThrows on any error rather than return a false flag to minimize user errors @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function setbdi( uint _refMSD, uint _refRank, uint _refSigned, uint _refSigs, bytes32 _refTrust ) external ProxyBDI returns (bool reputation_); /** @notice Set the talents of an Agent in the ecosystem @param _talent Agent's talent @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function setbdi(bytes32 _talent) external ProxyBDI returns (bool talent_); /** @notice Set the desires of an Agent in the ecosystem @param _desire Pro-attitude @param _goal A goal is an instatiated pro-attitude @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function setbdi(bytes1 _desire, Desire _goal) public onlyDoer returns (bool); /** @notice Set the intention of an Agent in the ecosystem @param _service Conducting-controlling pro-attitude @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function setbdi(Intention _service) public onlyDoer returns (bool); /** @notice Set the targeted intention of an Agent in the ecosystem. @param _intention Conduct-controlling pro-attitude @param _state Agent stance @dev For the purpose of Throws on any error rather than return a false flag to minimize user errors */ function intention(bool _intention, IERC_HUCAP_TYPES.IS _state) external returns (IERC_HUCAP_TYPES.IS); /* End of interface IERC_HUCAP */ } ``` #### User Defined Types Extension Interface ```solidity interface IERC_HUCAP_TYPES { /* Enums*/ // Weights 1, 2, 4, 8, 16, 32, 64, 128 256 enum KBase {PRIMARY,SECONDARY,TERTIARY,CERTIFICATION,DIPLOMA,LICENSE,BACHELOR,MASTER,DOCTORATE} enum IS { CLOSED, CREATOR, CURATOR, ACTIVE, INACTIVE, RESERVED, PROVER } /* Structus */ struct Clearance { bytes32 Zero; bytes32 Unknown; bytes32 Generic; bytes32 Poor; bytes32 Casual; bytes32 Partial; bytes32 Complete; bytes32 Ultimate; } /* End of interface IERC_HUCAP_TYPES */ } ``` #### Web-of-trust Extension Interface ```solidity pragma solidity ^0.4.25; pragma experimental ABIEncoderV2; interface IERC_HUCAP_KEYSIGNING_EXTENSION { bytes32 constant public _InterfaceId_ERC165_ = "CREATOR 0.0118 XOR OF ALL FUNCTIONS IN THE INTERFACE"; // Complies to ERC165 // KEY MASKING TABLE // bytes32 constant public MASK = 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff; // bytes32 constant public KEYID = 0xffffffffffffffffffffffffffffffffff90EBAC34FC40EAC30FC9CB464A2E56; // EXAMPLE PGP PUBLIC KEY ID // bytes32 constant public KEY_CERTIFICATION = 0x01ffffffffffffff << 192; // “C” Key Certification // bytes32 constant public SIGN_DATA = 0x02ffffffffffffff << 192; // “S” Sign Data // bytes32 constant public ENCRYPT_COMMUNICATIONS = 0x04ffffffffffffff << 192; // “E” Encrypt Communications // Clearance constant public Trust = 0x03ff << 192; // Trust: Unknown // BYTES32 Value with // Public Key Id, masking // Key Certification masking // Split Key masking // Generic masking // Ordinary masking // Trust.Unknown masking // bytes32 constant public DOER = 0x11ff10ff100f03ffff00ffffffffffffffff90EBAC34FC40EAC30FC9CB464A2E56; bytes32 constant public KEY_CERTIFICATION = 0x01ffffffffffffff << 192; // “C” Key Certification bytes32 constant public SIGN_DATA = 0x02ffffffffffffff << 192; // “S” Sign Data bytes32 constant public ENCRYPT_COMMUNICATIONS = 0x04ffffffffffffff << 192; // “E” Encrypt Communications bytes32 constant public ENCRYPT_STORAGE = 0x08ffffffffffffff << 192; // “E” Encrypt Storage bytes32 constant public SPLIT_KEY = 0x10ffffffffffffff << 192; // Split key bytes32 constant public AUTHENTICATION = 0x20ffffffffffffff << 192; // “A” Authentication bytes32 constant public MULTI_SIGNATURE = 0x80ffffffffffffff << 192; // Held by more than one person bytes32 constant public TRUST_AMOUNT = 0xffffffffffff00ff << 192; bytes32 constant public BINARY_DOCUMENT = 0xffff00ffffffffff << 192; // 0x00: Signature of a binary document. bytes32 constant public CANONICAL_DOCUMENT = 0xffff01ffffffffff << 192; // 0x01: Signature of a canonical text document. bytes32 constant public STANDALONE_SIGNATURE = 0xffff02ffffffffff << 192; // 0x02: Standalone signature. bytes32 constant public GENERIC = 0xffff10ffffffffff << 192; // 0x10: Generic certification of a User ID and Public-Key packet. bytes32 constant public PERSONA = 0xffff11ffffffffff << 192; // 0x11: Persona certification of a User ID and Public-Key packet. bytes32 constant public CASUAL = 0xffff12ffffffffff << 192; // 0x12: Casual certification of a User ID and Public-Key packet. bytes32 constant public POSITIVE = 0xffff13ffffffffff << 192; // 0x13: Positive certification of a User ID and Public-Key packet. bytes32 constant public SUBKEY_BINDING = 0xffff18ffffffffff << 192; // 0x18: Subkey Binding Signature bytes32 constant public PRIMARY_KEY_BINDING = 0xffff19ffffffffff << 192; // 0x19: Primary Key Binding Signature bytes32 constant public DIRECTLY_ON_KEY = 0xffff1Fffffffffff << 192; // 0x1F: Signature directly on a key bytes32 constant public KEY_REVOCATION = 0xffff20ffffffffff << 192; // 0x20: Key revocation signature bytes32 constant public SUBKEY_REVOCATION = 0xffff28ffffffffff << 192; // 0x28: Subkey revocation signature bytes32 constant public CERTIFICATION_REVOCATION = 0xffff30ffffffffff << 192; // 0x30: Certification revocation signature bytes32 constant public TIMESTAMP = 0xffff40ffffffffff << 192; // 0x40: Timestamp signature. bytes32 constant public THIRD_PARTY_CONFIRMATION = 0xffff50ffffffffff << 192; // 0x50: Third-Party Confirmation signature. bytes32 constant public ORDINARY = 0xffffffff100fffff << 192; bytes32 constant public INTRODUCER = 0xffffffff010fffff << 192; bytes32 constant public ISSUER = 0xffffffff001fffff << 192; // EDGES MASKING TABLE Clearance internal TRUST = Clearance({ Zero: 0x01ff << 192, Unknown: 0x03ff << 192, Generic: 0x07ff << 192, Poor: 0xF0ff << 192, Casual: 0xF1ff << 192, Partial: 0xF3ff << 192, Complete: 0xF7ff << 192, Ultimate: 0xFFff << 192 }); /** /// @notice Cycle through state transition of an Agent in the ecosystem. /// @param _address toggle on/off a doer agent // @dev `anybody` can retrieve the talent data in the contract */ function flipTo(address _address) external onlyOwner returns (IS); /** /// @notice Turn Agent in the ecosystem to on/off. /// @param _address toggle on/off a doer agent // @dev `anybody` can retrieve the talent data in the contract */ function toggle(address _address) external onlyOwner returns (bool); /** /// @notice Set the trust level of an Agent in the ecosystem. /// @param _level toggle on/off a doer agent // @dev `anybody` can retrieve the talent data in the contract */ function trust(Trust _level) returns (bytes32 Trust); event LogCall(address indexed from, address indexed to, address indexed origin, bytes _data); /* End of interface IERC_HUCAP_KEYSIGNING_EXTENSION */ } ``` #### Human Capital Accounting Extension Interface ```solidity pragma solidity ^0.4.25; pragma experimental ABIEncoderV2; interface IERC_HUCAP_TRACKUSERS_EXTENSION { /// @notice Instantiate an Agent in the ecosystem with default data. /// @param _address initialise a doer agent // @dev `anybody` can retrieve the talent data in the contract function initAgent(Doers _address) external onlyControlled returns (bool); /// @notice Get the data by uuid of an Agent in the ecosystem. /// @param _uuid Get the address of a unique uid // @dev `anybody` can retrieve the talent data in the contract function getAgent(bytes32 _uuid) view external returns (address); /// @notice Get the data of all Talents in the ecosystem. /// @param _address Query if address belongs to an agent // @dev `anybody` can retrieve the talent data in the contract function iam(address _address) view public returns (bool); /// @notice Get the data of all Talents in the ecosystem. /// @param _address Query if address belongs to a doer // @dev `anybody` can retrieve the talent data in the contract function isDoer(address _address) view public returns (IS); /// @notice Get the number of doers that can be spawned by a Creators. /// The query condition of the contract // @dev `anybody` can retrieve the count data in the contract function getAgent(address _address) view public returns (bytes32 keyid_, IS state_, bool active_, uint myDoers_); /// @notice Get the data of all Talents in the ecosystem. /// @param _talent The talent whose frequency is being queried // @dev `anybody` can retrieve the talent data in the contract function getTalents(bytes32 _talent) view external returns (uint talentK_, uint talentI_, uint talentR_, uint talentF_); /// @notice Increment a kind of talent in the ecosystem. /// @param The talent whose frequency is being queried // @dev `anybody` can retrieve the talent data in the contract function incTalent() payable public onlyDoer returns (bool); /// @notice Decrement a kind of talent in the ecosystem.. /// @param The talent whose frequency is being queried // @dev `anybody` can retrieve the talent data in the contract function decTalent() payable public onlyDoer returns (bool); /// @notice Set the Public-Key Id of an Agent in the ecosystem. /// @param _address Set the Public-key Id of an agent // @dev `anybody` can retrieve the talent data in the contract function setAgent(address _address, bytes32 _keyId) external onlyControlled returns (bytes32); /// @notice Transition the states of an Agent in the ecosystem. /// @param _address Set the stance of an agent // @dev `anybody` can retrieve the talent data in the contract function setAgent(address _address, IS _state) external onlyControlled returns (IS); /// @notice Set the active status of an Agent in the ecosystem. /// @param _address Toggle the true/false status of an agent // @dev `anybody` can retrieve the talent data in the contract function setAgent(address _address, bool _active) external onlyControlled returns (bool); /// @notice Set the data of all Intentions of Agents in the ecosystem. /// @param _serviceId Track number of offers available // @dev `anybody` can retrieve the talent data in the contract function setAllPromises(bytes32 _serviceId) external onlyControlled; /* End of interface IERC_HUCAP_TRACKUSERS_EXTENSION */ } ``` ## Rationale [WIP] ## Backwards Compatibility [WIP] ## Test Cases [WIP] ## Implementation [WIP] ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Upgradable Smart Contract

Wed, 17 Oct 2018 00:00:00 +0000

## Simple Summary A standard interface/guideline that makes a smart contract upgradable. ## Abstract Ethereum smart contracts have suffered a number of security issues in the past few years. The cost of fixing such a bug in smart contract is significant; for example, the consequences of The DAO attack in June 2016 caused tremendous financial loss and the hard fork of Ethereum blockchain. The following standard makes it possible to upgrade a standard API within smart contracts. This standard provides basic functionalities to upgrade the operations of the contract without data migration. To ensure the decentralization/community interests, it also contains a voting mechanism to control the upgrading process. ## Motivation Smart contract is immutable after deployment. If any security risk is identified or program bug is detected, developers always have to destruct the old contract, deploy a new one and potentially migrate the data (hard fork) to the new contract. In some cases, deploying a smart contract with bugs and potential security vulnerabilities can cause a significant amount of financial loss. We propose this upgradable contract to fix the current situation. With the upgradable contract, developers can deploy a new version of smart contract after previous deployment and retain the data at the same time. For example, after an ERC20-compliant token contract is deployed, the users exploit a vulnerability in the source code. Without the support of upgradable contract, developers have to fix this issue by deploy a new, secured contract otherwise the attackers would take advantage of the security hole, which may cause a tremendous financial loss. A challenge is how to migrate data from the old contract to a new one. With the upgradable contract below, this will become relatively easy as developers only have to upgrade the Handler contract to fix bugs while the Data contract will remain the same. ## Specification The upgradable contract consists of three parts: - **Handler contract** (implements **Handler interface**) defines operations and provides services. This contract can be upgraded; - **Data contract** keeps the resources (data) and is controlled by the Handler contract; - **Upgrader contract (optional)** deals with the voting mechanism and upgrades the Handler contract. The voters are pre-defined by the contract owner. > The following codes are exact copies of the [ERC-1504 Upgradable Smart Contract.](https://gist.github.com/swordghost/77c96a972106af6ec6ccea9c2d66e768) ### Handler contract and Handler interface Functions of the Handler contract vary with requirements, so developers would better design interfaces for Handler contracts to limit them and make sure external applications are always supported. Below is the specification of Handler interface. In the Handler interface we define the following actions: - Initialize the Data contract; - Register the Upgrader contract address; - Destruct the Handler contract after upgrading is done; - Verify the current Handler is the working one → it should always return true. Developers have to define their business-related functions as well. ```solidity /// Handler interface. /// Handler defines business related functions. /// Use the interface to ensure that your external services are always supported. /// Because of function live(), we design IHandler as an abstract contract rather than a true interface. contract IHandler { /// Initialize the data contarct. /// @param _str value of exmStr of Data contract. /// @param _int value of exmInt of Data contract. /// @param _array value of exmArray of Data contract. function initialize (string _str, uint256 _int, uint16 [] _array) public; /// Register Upgrader contract address. /// @param _upgraderAddr address of the Upgrader contract. function registerUpgrader (address _upgraderAddr) external; /// Upgrader contract calls this to check if it is registered. /// @return if the Upgrader contract is registered. function isUpgraderRegistered () external view returns(bool); /// Handler has been upgraded so the original one has to self-destruct. function done() external; /// Check if the Handler contract is a working Handler contract. /// It is used to prove the contract is a Handler contract. /// @return always true. function live() external pure returns(bool) { return true; } /** Functions - define functions here */ /** Events - add events here */ } ``` The process of deploying a Handler contract: 1. Deploy Data contract; 2. Deploy a Handler contract at a given address specified in the Data contract; 3. Register the Handler contract address by calling setHandler() in the Data contract, or use an Upgrader contract to switch the Handler contract, which requires that Data contract is initialized; 4. Initialize Data contract if haven’t done it already. ### Data Contract Below is the specification of Data contract. There are three parts in the Data contract: - **Administrator Data**: owner’s address, Handler contract’s address and a boolean indicating whether the contract is initialized or not; - **Upgrader Data**: Upgrader contract’s address, upgrade proposal’s submission timestamp and proposal’s time period; - **Resource Data**: all other resources that the contract needs to keep and manage. ```solidity /// Data Contract contract DataContract { /** Management data */ /// Owner and Handler contract address private owner; address private handlerAddr; /// Ready? bool private valid; /** Upgrader data */ address private upgraderAddr; uint256 private proposalBlockNumber; uint256 private proposalPeriod; /// Upgrading status of the Handler contract enum UpgradingStatus { /// Can be upgraded Done, /// In upgrading InProgress, /// Another proposal is in progress Blocked, /// Expired Expired, /// Original Handler contract error Error } /** Data resources - define variables here */ /** Modifiers */ /// Check if msg.sender is the Handler contract. It is used for setters. /// If fail, throw PermissionException. modifier onlyHandler; /// Check if msg.sender is not permitted to call getters. It is used for getters (if necessary). /// If fail, throw GetterPermissionException. modifier allowedAddress; /// Check if the contract is working. /// It is used for all functions providing services after initialization. /// If fail, throw UninitializationException. modifier ready; /** Management functions */ /// Initializer. Just the Handler contract can call it. /// @param _str default value of this.exmStr. /// @param _int default value of this.exmInt. /// @param _array default value of this.exmArray. /// exception PermissionException msg.sender is not the Handler contract. /// exception ReInitializationException contract has been initialized. /// @return if the initialization succeeds. function initialize (string _str, uint256 _int, uint16 [] _array) external onlyHandler returns(bool); /// Set Handler contract for the contract. Owner must set one to initialize the Data contract. /// Handler can be set by owner or Upgrader contract. /// @param _handlerAddr address of a deployed Handler contract. /// @param _originalHandlerAddr address of the original Handler contract, only used when an Upgrader contract want to set the Handler contract. /// exception PermissionException msg.sender is not the owner nor a registered Upgrader contract. /// exception UpgraderException Upgrader contract does not provide a right address of the original Handler contract. /// @return if Handler contract is successfully set. function setHandler (address _handlerAddr, address _originalHandlerAddr) external returns(bool); /** Upgrader contract functions */ /// Register an Upgrader contract in the contract. /// If a proposal has not been accepted until proposalBlockNumber + proposalPeriod, it can be replaced by a new one. /// @param _upgraderAddr address of a deployed Upgrader contract. /// exception PermissionException msg.sender is not the owner. /// exception UpgraderConflictException Another Upgrader contract is working. /// @return if Upgrader contract is successfully registered. function startUpgrading (address _upgraderAddr) public returns(bool); /// Getter of proposalPeriod. /// exception UninitializationException uninitialized contract. /// exception GetterPermissionException msg.sender is not permitted to call the getter. /// @return this.proposalPeriod. function getProposalPeriod () public view isReady allowedAddress returns(uint256); /// Setter of proposalPeriod. /// @param _proposalPeriod new value of this.proposalPeriod. /// exception UninitializationException uninitialized contract. /// exception PermissionException msg.sender is not the owner. /// @return if this.proposalPeriod is successfully set. function setProposalPeriod (uint256 _proposalPeriod) public isReady returns(bool); /// Return upgrading status for Upgrader contracts. /// @param _originalHandlerAddr address of the original Handler contract. /// exception UninitializationException uninitialized contract. /// @return Handler contract's upgrading status. function canBeUpgraded (address _originalHandlerAddr) external view isReady returns(UpgradingStatus); /// Check if the contract has been initialized. /// @return if the contract has been initialized. function live () external view returns(bool); /** Getters and setters of data resources: define functions here */ } ``` ### Upgrader Contract (Optional) Handler contract can be upgraded by calling setHandler() of Data contract. If the owner wants to collect ideas from users, an Upgrader contract will help him/her manage voting and upgrading. Below is the specification of Upgrader contract: - The Upgrader contract has the ability to take votes from the registered voters. - The contract owner is able to add voters any time before the proposal expires; - Voter can check the current status of the proposal (succeed or expired). - Developers are able to delete this Upgrader contract by calling done() any time after deployment. The Upgrader contract works as follows: 1. Verify the Data contract, its corresponding Handler contract and the new Handler contract have all been deployed; 2. Deploy an Upgrader contract using Data contract address, previous Handler contract address and new Handler contract address; 3. Register upgrader address in the new Handler contract first, then the original handler and finally the Data contract; 4. Call startProposal() to start the voting process; 5. Call getResolution() before the expiration; 6. Upgrading succeed or proposal is expired. Note: - Function done() can be called at any time to let upgrader destruct itself. - Function status() can be called at any time to show caller status of the upgrader. ```solidity /// Handler upgrader contract Upgrader { // Data contract DataContract public data; // Original Handler contract IHandler public originalHandler; // New Handler contract address public newHandlerAddr; /** Marker */ enum UpgraderStatus { Preparing, Voting, Success, Expired, End } UpgraderStatus public status; /// Check if the proposal is expired. /// If so, contract would be marked as expired. /// exception PreparingUpgraderException proposal has not been started. /// exception ReupgradingException upgrading has been done. /// exception ExpirationException proposal is expired. modifier notExpired { require(status != UpgraderStatus.Preparing, "Invalid proposal!"); require(status != UpgraderStatus.Success, "Upgrading has been done!"); require(status != UpgraderStatus.Expired, "Proposal is expired!"); if (data.canBeUpgraded(address(originalHandler)) != DataContract.UpgradingStatus.InProgress) { status = UpgraderStatus.Expired; require(false, "Proposal is expired!"); } _; } /// Start voting. /// Upgrader must do upgrading check, namely checking if Data contract and 2 Handler contracts are ok. /// exception RestartingException proposal has been already started. /// exception PermissionException msg.sender is not the owner. /// exception UpgraderConflictException another upgrader is working. /// exception NoPreparationException original or new Handler contract is not prepared. function startProposal () external; /// Anyone can try to get resolution. /// If voters get consensus, upgrade the Handler contract. /// If expired, self-destruct. /// Otherwise, do nothing. /// exception PreparingUpgraderException proposal has not been started. /// exception ExpirationException proposal is expired. /// @return status of proposal. function getResolution() external returns(UpgraderStatus); /// Destruct itself. /// exception PermissionException msg.sender is not the owner. function done() external; /** Other voting mechanism related variables and functions */ } ``` ### Caveats Since the Upgrader contract in [ERC-1504](./eip-1504.md) has a simple voting mechanism, it is prone to all the limitations that the voting contract is facing: - The administrator can only be the owner of data and Handler contracts. Furthermore, only the administrator has the power to add voters and start a proposal. - It requires voters to be constantly active, informative and attentive to make a upgrader succeed. - The voting will only be valid in a given time period. If in a given time period the contract cannot collect enough “yes” to proceed, the proposal will be marked expired. ## Rationale ### Data Contract and Handler Contract A smart contract is actually a kind of software, which provides some kind of services. From the perspective of software engineering, a service consists of **resources** that abstract the data and **operations** that abstract the process logic on the data. The requirement of upgrading is mostly on the logic part. Therefore, in order to make a smart contract upgradable, we divide it into two parts: 1. Data contract keeps the resources; 2. Handler contract contains operations. The Handler contract can be upgraded in the future while the Data contract is permanent. Handler contract can manipulate the variables in Data contract through the getter and setter functions provided by Data contract. ### Upgrader Contract and Voting Mechanism In order to prevent centralization and protect the interests of the community and stakeholders, we also design a voting mechanism in the Upgrader contract. Upgrader contract contains addresses of Data contract and two Handler contracts, and collects votes from pre-defined voters to upgrade the Handler contract when the pre-set condition is fulfilled. For simplicity, the upgradable contract comes with a very minimal version of the voting mechanism. If the contract owner wants to implement a more complex voting mechanism, he/she can modify the existing voting mechanism to incorporate upgradability. The expiration mechanism (see modifier notExpried in Upgrader contract and related functions in Data contract) and upgrading check (see function startProposal() in Upgrader contract) to the contract are mandatory. ### Gas and Complexity (regarding the enumeration extension) Using an upgrader will cost some gas. If the Handler contract is upgraded by the owner, it just costs gas that a contract call will cost, which is usually significantly lower than creating and deploying a new contract. Although upgrading contract may take some efforts and gas, it is a much less painful than deprecating the insecure contract/creating a new contract or hard fork (e.g. DAO attack). Contract creation requires a significant amount of effort and gas. One of the advantages of upgradable contracts is that the contract owners don’t have to create new contracts; instead, they only need to upgrade parts of contract that cause issues, which is less expensive compared to data loss and blockchain inconsistency. In other words, upgradable contracts make Data contract more scalable and flexible. ### Community Consensus Thank you to those who helped on review and revise the proposal: - [@lsankar4033](https://github.com/lsankar4033) from MIT - more The proposal is initiated and developed by the team Renaissance and the Research Group of Blockchain System @ Center for Operating System at Peking University. We have been very inclusive in this process and invite anyone with questions or contributions into our discussion. However, this standard is written only to support the identified use cases which are listed herein. ## Implementations 1. [Renaissance](https://www.renaissance.app) - a protocol that connect creators and fans financially 2. [ERC-1504](./eip-1504.md) - a reference implementation ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Standard for Insurance Policies as ERC-721 Non Fungible Tokens

Wed, 10 Oct 2018 00:00:00 +0000

## Simple Summary A standard interface for insurance policies, based on ERC 721. ## Abstract The following standard allows for the implementation of a standard API for insurance policies within smart contracts. Insurance policies are financial assets which are unique in some aspects, as they are connected to a customer, a specific risk, or have other unique properties like premium, period, carrier, underwriter etc. Nevertheless, there are many potential applications where insurance policies can be traded, transferred or otherwise treated as an asset. The ERC 721 standard already provides the standard and technical means to handle policies as a specific class of non fungible tokens. insurance In this proposal, we define a minimum metadata structure with properties which are common to the greatest possible class of policies. ## Motivation For a decentralized insurance protocol, a standard for insurance policies is crucial for interoperability of the involved services and application. It allows policies to be bundled, securitized, traded in a uniform and flexible way by many independent actors like syndicates, brokers, and insurance companies. ## Specification The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119. An ERC-1523 compliant insurance policy is a non-fungible token which **MUST adhere to the ERC-721 token standard** and **MUST implement theERC721Metadata and the ERC721Enumerable interface**: ```solidity /// @title ERC-1523 Insurance Policy Standard /// Note: the ERC-165 identifier for this interface is 0x5a04be32 interface ERC1523 /* is ERC721, ERC721Metadata, ERC721Enumerable */ { } ``` The implementor MAY choose values for the ```name``` and ```symbol```. The **policy metadata extension** is **RECOMMENDED** for ERC-1523 smart contracts. This allows your smart contract to be interrogated for policy metadata. ```solidity /// @title ERC-1523 Insurance Policy Standard, optional policy metadata extension /// @dev See ... /// Note: the ERC-165 identifier for this interface is 0x5a04be32 interface ERC1523PolicyMetadata /* is ERC1523 */ { /// @notice Metadata string for a given property. /// Properties are identified via hash of their property path. /// e.g. the property "name" in the ERC721 Metadata JSON Schema has the path /properties/name /// and the property path hash is the keccak256() of this property path. /// this allows for efficient addressing of arbitrary properties, as the set of properties is potentially unlimited. /// @dev Throws if `_propertyPathHash` is not a valid property path hash. function policyMetadata(uint256 _tokenId, bytes32 _propertyPathHash) external view returns (string _property); } ``` In analogy to the “ERC721 Metadata JSON Schema”, the tokenURI **MUST** point to a JSON file with the following properties: ```json { "title": "Asset Metadata", "type": "object", "properties": { "name": { "type": "string", "description": "Identifies the asset to which this NFT represents", }, "description": { "type": "string", "description": "Describes the asset to which this NFT represents", }, \[additional parameters according to the following table\] } } ``` ### Additional parameters for the metadata JSON Schema | Parameter | Type | Mandatory | Description | | ------------- | ------------- | ----------| ---------------------------------------------------------------------------------- | | carrier | string | yes | Describes the carrier which takes the primary risk | | risk | string | yes | Describes the risk | | status | string | yes | Describes the status of the policy, e.g. applied for, underwritten, expired | | parameters | string | no | Describes further parameters characterizing the risk | | terms | string | no | Describes legal terms & conditions which apply for this policy | | premium | string | no | A string representation of the premium, **MAY** contain currency denominator | | sum_insured | string | no | A string representation of the sum insured, **MAY** contain currency denominator | Parameters which are mandatory **MUST** be included in the metadata JSON. Other parameters **MAY** be included. However, the proposed optional parameters **SHOULD** be used for the intended purpose, so e.g. if the premium amount would be included in the metadata, the parameter name **SHOULD** be "premium". All parameters **MAY** be plain text or **MAY** also be URIs pointing to resources which contain the respective information, and which **MAY** be protected by an authentication mechanism. ## Rationale Insurance policies form an important class of financial assets, and it is natural to express those assets as a class of non-fungible tokens which adhere to the established ERC-721 standard. We propose a standard for the accompanying metadata structures which are needed to uniquely define an insurance policy. Standardization is key because we expect decentralized insurance to receive widespread adoption and it is crucial to establish a unified standard to enable composability and the creation of universal toolsets. We therefore propose a standardized naming scheme for the different parameters describing an insurance policy. We propose three mandatory parameters which need to be included in every NFT and further parameters which **MAY** be used, and for which we only standardize the naming conventions. ### Mandatory parameters While policies can have a multitude of possible properties, it is common that policies are issued by some entity, which is basically the entity responsible for paying out claims. Second, an insurance policy is typically related to a specific risk. Some risks are unique, but there are cases where many policies share the same risk (e.g. all flight delay policies for the same flight). In general, the relation of policies to risks is a many-to-one relation with the special case of a one-to-one relation. Third, a policy has a lifecycle of different statuses. Therefore the NFT We believe that those four properties are necessary to describe a policy. For many applications, those properties may be even sufficient. ### Optional parameters Most policies need more parameters to characterize the risk and other features, like premium, period etc. The naming conventions are listed in the above table. However, any implementation **MAY** chose to implement more properties. ### On-chain vs. off-chain metadata For some applications it will be sufficient to store the metadata in an off-chain repository or database which can be addressed by the tokenURI resource locator. For more advanced applications, it can be desirable to have metadata available on-chain. Therefore, we require that the ```tokenURI``` **MUST** point to a JSON with the above structure, while the implementation of the ```policyMetadata``` function is **OPTIONAL**. ## Backwards Compatibility ## Test Cases ## Implementation ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Transparent Contract Standard

Wed, 31 Oct 2018 00:00:00 +0000

Replaced by [EIP-2535 Diamond Standard](./eip-2535.md). ## Simple Summary This standard provides a contract architecture that makes upgradeable contracts flexible, unlimited in size, and transparent. A transparent contract publicly documents the full history of all changes made to it. All changes to a transparent contract are reported in a standard format. ## Abstract A transparent contract is a proxy contract design pattern that provides the following: 1. A way to add, replace and remove multiple functions of a contract atomically (at the same time). 1. Standard events to show what functions are added, replaced and removed from a contract, and why the changes are made. 2. A standard way to query a contract to discover and retrieve information about all functions exposed by it. 3. Solves the 24KB maximum contract size limitation, making the maximum contract size of a transparent contract practically unlimited. This standard makes the worry about contract size a thing of the past. 4. Enables an upgradeable contract to become immutable in the future if desired. ## Motivation A fundamental benefit of Ethereum contracts is that their code is immutable, thereby acquiring trust by trustlessness. People do not have to trust others if it is not possible for a contract to be changed. However, a fundamental problem with trustless contracts that cannot be changed is that they cannot be changed. #### Bugs Bugs and security vulnerabilities are unwittingly written into immutable contracts that ruin them. #### Improvements Immutable, trustless contracts cannot be improved, resulting in increasingly inferior contracts over time. Contract standards evolve, new ones come out. People, groups and organizations learn over time what people want and what is better and what should be built next. Contracts that cannot be improved not only hold back the authors that create them, but everybody who uses them. #### Upgradeable Contracts vs. Centralized Private Database Why have an upgradeable contract instead of a centralized, private, mutable database? Here are some reasons: 1. Because of the openness of storage data and verified code, it is possible to show a provable history of trustworthiness. 2. Because of the openness, bad behavior can be spotted and reported when it happens. 3. Independent security and domain experts can review the change history of contracts and vouch for their history of trustworthiness. 4. It is possible for an upgradeable contract to become immutable and trustless. 5. An upgradeable contract can have parts of it that are not upgradeable and so are partially immutable and trustless. #### Immutability In some cases immutable, trustless contracts are the right fit. This is the case when a contract is only needed for a short time or it is known ahead of time that there will never be any reason to change or improve it. ### Middle Ground Transparent contracts provide a middle ground between immutable trustless contracts that can't be improved and upgradeable contracts that can't be trusted. ### Purposes 1. Create upgradeable contracts that earn trust by showing a provable history of trustworthiness. 2. Document the development of contracts so their development and change is provably public and can be understood. 3. Create upgradeable contracts that can become immutable in the future if desired. 4. Create contracts that are not limited by a max size. ### Benefits & Use Cases This standard is for use cases that benefit from the following: 1. The ability to add, replace or remove multiple functions of a contract atomically (at the same time). 2. Each time a function is added, replaced or removed, it is documented with events. 3. Build trust over time by showing all changes made to a contract. 4. Unlimited contract size. 5. The ability to query information about functions currently supported by the contract. 6. One contract address that provides all needed functionality and never needs to be replaced by another contract address. 7. The ability for a contract to be upgradeable for a time, and then become immutable. 8. Add trustless guarantees to a contract with "unchangeable functions". ### New Software Possibilities This standard enables a form of contract version control software to be written. Software and user interfaces can be written to filter the `FunctionUpdate` and `CommitMessage` events of a contract address. Such software can show the full history of changes of any contract that implements this standard. User interfaces and software can also use this standard to assist or automate changes of contracts. ## Specification > **Note:** The solidity `delegatecall` opcode enables a contract to execute a function from another contract, but it is executed as if the function was from the calling contract. Essentially `delegatecall` enables a contract to "borrow" another contract's function. Functions executed with `delegatecall` affect the storage variables of the calling contract, not the contract where the functions are defined. ### General Summary A transparent contract delegates or forwards function calls to it to other contracts using `delegatecode`. A transparent contract has an `updateContract` function that enables multiple functions to be added, replaced or removed. An event is emitted for every function that is added, replaced or removed so that all changes to a contract can be tracked in a standard way. A transparent contract is a contract that implements and complies with the design points below. ### Terms 1. In this standard a **delegate contract** is a contract that a transparent contract fallback function forwards function calls to using `delegatecall`. 2. In this standard an **unchangeable function** is a function that is defined directly in a transparent contract and so cannot be replaced or removed. ### Design Points A contract is a transparent contract if it implements the following design points: 1. A transparent contract is a contract that contains a fallback function, a constructor, and zero or more unchangeable functions that are defined directly within it. 2. The constructor of a transparent contract associates the `updateContract` function with a contract that implements the ERC1538 interface. The `updateContract` function can be an "unchangeable function" that is defined directly in the transparent contract or it can be defined in a delegate contract. Other functions can also be associated with contracts in the constructor. 3. After a transparent contract is deployed functions are added, replaced and removed by calling the `updateContract` function. 4. The `updateContract` function associates functions with contracts that implement those functions, and emits the `CommitMessage` and `FunctionUpdate` events that document function changes. 5. The `FunctionUpdate` event is emitted for each function that is added, replaced or removed. The `CommitMessage` event is emitted one time for each time the `updateContract` function is called and is emitted after any `FunctionUpdate` events are emitted. 6. The `updateContract` function can take a list of multiple function signatures in its `_functionSignatures` parameter and so add/replace/remove multiple functions at the same time. 7. When a function is called on a transparent contract it executes immediately if it is an "unchangeable function". Otherwise the fallback function is executed. The fallback function finds the delegate contract associated with the function and executes the function using `delegatecall`. If there is no delegate contract for the function then execution reverts. 8. The source code of a transparent contract and all delegate contracts used by it are publicly viewable and verified. The transparent contract address is the address that users interact with. The transparent contract address never changes. Only delegate addresses can change by using the `updateContracts` function. Typically some kind of authentication is needed for adding/replacing/removing functions from a transparent contract, **however the scheme for authentication or ownership is not part of this standard**. ### Example Here is an example of an implementation of a transparent contract. Please note that the example below is an **example only. It is not the standard**. A contract is a transparent contract when it implements and complies with the design points listed above. ```solidity pragma solidity ^0.5.7; contract ExampleTransparentContract { // owner of the contract address internal contractOwner; event OwnershipTransferred(address indexed previousOwner, address indexed newOwner); // maps functions to the delegate contracts that execute the functions // funcId => delegate contract mapping(bytes4 => address) internal delegates; // maps each function signature to its position in the funcSignatures array. // signature => index+1 mapping(bytes => uint256) internal funcSignatureToIndex; event CommitMessage(string message); event FunctionUpdate(bytes4 indexed functionId, address indexed oldDelegate, address indexed newDelegate, string functionSignature); // this is an example of an "unchangeable function". // return the delegate contract address for the supplied function signature function delegateAddress(string calldata _functionSignature) external view returns(address) { require(funcSignatureToIndex[bytes(_functionSignature)] != 0, "Function signature not found."); return delegates[bytes4(keccak256(bytes(_functionSignature)))]; } // add a function using the updateContract function // this is an internal helper function function addFunction(address _erc1538Delegate, address contractAddress, string memory _functionSignatures, string memory _commitMessage) internal { // 0x03A9BCCF == bytes4(keccak256("updateContract(address,string,string)")) bytes memory funcdata = abi.encodeWithSelector(0x03A9BCCF, contractAddress, _functionSignatures, _commitMessage); bool success; assembly { success := delegatecall(gas, _erc1538Delegate, add(funcdata, 0x20), mload(funcdata), funcdata, 0) } require(success, "Adding a function failed"); } constructor(address _erc1538Delegate) public { contractOwner = msg.sender; emit OwnershipTransferred(address(0), msg.sender); // adding ERC1538 updateContract function bytes memory signature = "updateContract(address,string,string)"; bytes4 funcId = bytes4(keccak256(signature)); delegates[funcId] = _erc1538Delegate; emit FunctionUpdate(funcId, address(0), _erc1538Delegate, string(signature)); emit CommitMessage("Added ERC1538 updateContract function at contract creation"); // associate "unchangeable functions" with this transparent contract address // prevents function selector clashes with delegate contract functions // uses the updateContract function string memory functions = "delegateAddress(string)"; addFunction(_erc1538Delegate, address(this), functions, "Associating unchangeable functions"); // adding ERC1538Query interface functions functions = "functionByIndex(uint256)functionExists(string)delegateAddresses()delegateFunctionSignatures(address)functionById(bytes4)functionBySignature(string)functionSignatures()totalFunctions()"; // "0x01234567891011121314" is an example address of an ERC1538Query delegate contract addFunction(_erc1538Delegate, 0x01234567891011121314, functions, "Adding ERC1538Query functions"); // additional functions could be added at this point } // Making the fallback function payable makes it work for delegate contract functions // that are payable and not payable. function() external payable { // Delegate every function call to a delegate contract address delegate = delegates[msg.sig]; require(delegate != address(0), "Function does not exist."); assembly { let ptr := mload(0x40) calldatacopy(ptr, 0, calldatasize) let result := delegatecall(gas, delegate, ptr, calldatasize, 0, 0) let size := returndatasize returndatacopy(ptr, 0, size) switch result case 0 {revert(ptr, size)} default {return (ptr, size)} } } } ``` As can be seen in the above example, every function call is delegated to a delegate contract, unless the function is defined directly in the transparent contract (making it an unchangeable function). The constructor function adds the `updateContract` function to the transparent contract, which is then used to add other functions to the transparent contract. Each time a function is added to a transparent contract the events `CommitMessage` and `FunctionUpdate` are emitted to document exactly what functions where added or replaced and why. The delegate contract that implements the `updateContract` function implements the following interface: ### ERC1538 Interface ```solidity pragma solidity ^0.5.7; /// @title ERC1538 Transparent Contract Standard /// @dev Required interface /// Note: the ERC-165 identifier for this interface is 0x61455567 interface ERC1538 { /// @dev This emits when one or a set of functions are updated in a transparent contract. /// The message string should give a short description of the change and why /// the change was made. event CommitMessage(string message); /// @dev This emits for each function that is updated in a transparent contract. /// functionId is the bytes4 of the keccak256 of the function signature. /// oldDelegate is the delegate contract address of the old delegate contract if /// the function is being replaced or removed. /// oldDelegate is the zero value address(0) if a function is being added for the /// first time. /// newDelegate is the delegate contract address of the new delegate contract if /// the function is being added for the first time or if the function is being /// replaced. /// newDelegate is the zero value address(0) if the function is being removed. event FunctionUpdate( bytes4 indexed functionId, address indexed oldDelegate, address indexed newDelegate, string functionSignature ); /// @notice Updates functions in a transparent contract. /// @dev If the value of _delegate is zero then the functions specified /// in _functionSignatures are removed. /// If the value of _delegate is a delegate contract address then the functions /// specified in _functionSignatures will be delegated to that address. /// @param _delegate The address of a delegate contract to delegate to or zero /// to remove functions. /// @param _functionSignatures A list of function signatures listed one after the other /// @param _commitMessage A short description of the change and why it is made /// This message is passed to the CommitMessage event. function updateContract(address _delegate, string calldata _functionSignatures, string calldata _commitMessage) external; } ``` ### Function Signatures String Format The text format for the `_functionSignatures` parameter is simply a string of function signatures. For example: `"myFirstFunction()mySecondFunction(string)"` This format is easy to parse and is concise. Here is an example of calling the `updateContract` function that adds the ERC721 standard functions to a transparent contract: ```javascript functionSignatures = "approve(address,uint256)balanceOf(address)getApproved(uint256)isApprovedForAll(address,address)ownerOf(uint256)safeTransferFrom(address,address,uint256)safeTransferFrom(address,address,uint256,bytes)setApprovalForAll(address,bool)transferFrom(address,address,uint256)" tx = await transparentContract.updateContract(erc721Delegate.address, functionSignatures, "Adding ERC721 functions"); ``` ### Removing Functions Functions are removed by passing `address(0)` as the first argument to the `updateContract` function. The list of functions that are passed in are removed. ### Source Code Verification The transparent contract source code and the source code for the delegate contracts should be verified in a provable way by a third party source such as etherscan.io. ### Function Selector Clash A function selector clash occurs when a function is added to a contract that hashes to the same four-byte hash as an existing function. This is unlikely to occur but should be prevented in the implementation of the `updateContract` function. See the [reference implementation of ERC1538](https://github.com/mudgen/transparent-contracts-erc1538) to see an example of how function clashes can be prevented. ### ERC1538Query Optionally, the function signatures of a transparent contract can be stored in an array in the transparent contract and queried to get what functions the transparent contract supports and what their delegate contract addresses are. The following is an optional interface for querying function information from a transparent contract: ```solidity pragma solidity ^0.5.7; interface ERC1538Query { /// @notice Gets the total number of functions the transparent contract has. /// @return The number of functions the transparent contract has, /// not including the fallback function. function totalFunctions() external view returns(uint256); /// @notice Gets information about a specific function /// @dev Throws if `_index` >= `totalFunctions()` /// @param _index The index position of a function signature that is stored in an array /// @return The function signature, the function selector and the delegate contract address function functionByIndex(uint256 _index) external view returns( string memory functionSignature, bytes4 functionId, address delegate ); /// @notice Checks to see if a function exists /// @param The function signature to check /// @return True if the function exists, false otherwise function functionExists(string calldata _functionSignature) external view returns(bool); /// @notice Gets all the function signatures of functions supported by the transparent contract /// @return A string containing a list of function signatures function functionSignatures() external view returns(string memory); /// @notice Gets all the function signatures supported by a specific delegate contract /// @param _delegate The delegate contract address /// @return A string containing a list of function signatures function delegateFunctionSignatures(address _delegate) external view returns(string memory); /// @notice Gets the delegate contract address that supports the given function signature /// @param The function signature /// @return The delegate contract address function delegateAddress(string calldata _functionSignature) external view returns(address); /// @notice Gets information about a function /// @dev Throws if no function is found /// @param _functionId The id of the function to get information about /// @return The function signature and the contract address function functionById(bytes4 _functionId) external view returns( string memory signature, address delegate ); /// @notice Get all the delegate contract addresses used by the transparent contract /// @return An array of all delegate contract addresses function delegateAddresses() external view returns(address[] memory); } ``` See the [reference implementation of ERC1538](https://github.com/mudgen/transparent-contracts-erc1538) to see how this is implemented. The text format for the list of function signatures returned from the `delegateFunctionSignatures` and `functionSignatures` functions is simply a string of function signatures. Here is an example of such a string: `"approve(address,uint256)balanceOf(address)getApproved(uint256)isApprovedForAll(address,address)ownerOf(uint256)safeTransferFrom(address,address,uint256)safeTransferFrom(address,address,uint256,bytes)setApprovalForAll(address,bool)transferFrom(address,address,uint256)"` ### How To Deploy A Transparent Contract 1. Create and deploy to a blockchain a contract that implements the ERC1538 interface. You can skip this step if there is already such a contract deployed to the blockchain. 2. Create your transparent contract with a fallback function as given above. Your transparent contract also needs a constructor that adds the `updateContract` function. 3. Deploy your transparent contract to a blockchain. Pass in the address of the ERC1538 delegate contract to your constructor if it requires it. See the [reference implementation](https://github.com/mudgen/transparent-contracts-erc1538) for examples of these contracts. ### Wrapper Contract for Delegate Contracts that Depend on Other Delegate Contracts In some cases some delegate contracts may need to call external/public functions that reside in other delegate contracts. A convenient way to solve this problem is to create a contract that contains empty implementations of functions that are needed and import and extend this contract in delegate contracts that call functions from other delegate contracts. This enables delegate contracts to compile without having to provide implementations of the functions that are already given in other delegate contracts. This is a way to save gas, prevent reaching the max contract size limit, and prevent duplication of code. This strategy was given by @amiromayer. [See his comment for more information.](https://github.com/ethereum/EIPs/issues/1538#issuecomment-451985155) Another way to solve this problem is to use assembly to call functions provided by other delegate contracts. ### Decentralized Authority It is possible to extend this standard to add consensus functionality such as an approval function that multiple different people call to approve changes before they are submitted with the `updateContract` function. Changes only go into effect when the changes are fully approved. The `CommitMessage` and ` FunctionUpdate` events should only be emitted when changes go into effect. ## Security > This standard refers to **owner(s)** as one or more individuals that have the power to add/replace/remove functions of an upgradeable contract. ### General The owners(s) of an upgradeable contract have the ability to alter, add or remove data from the contract's data storage. Owner(s) of a contract can also execute any arbitrary code in the contract on behalf of any address. Owners(s) can do these things by adding a function to the contract that they call to execute arbitrary code. This is an issue for upgradeable contracts in general and is not specific to transparent contracts. >**Note:** The design and implementation of contract ownership is **not** part of this standard. The examples given in this standard and in the reference implementation are just **examples** of how it could be done. ### Unchangeable Functions "Unchangeable functions" are functions defined in a transparent contract itself and not in a delegate contract. The owner(s) of a transparent contract are not able to replace these functions. The use of unchangeable functions is limited because in some cases they can still be manipulated if they read or write data to the storage of the transparent contract. Data read from the transparent contract's storage could have been altered by the owner(s) of the contract. Data written to the transparent contract's storage can be undone or altered by the owner(s) of the contract. In some cases unchangeble functions add trustless guarantees to a transparent contract. ### Transparency Contracts that implement this standard emit an event every time a function is added, replaced or removed. This enables people and software to monitor the changes to a contract. If any bad acting function is added to a contract then it can be seen. To comply with this standard all source code of a transparent contract and delegate contracts must be publicly available and verified. Security and domain experts can review the history of change of any transparent contract to detect any history of foul play. ## Rationale ### String of Function Signatures Instead of bytes4[] Array of Function Selectors The `updateContract` function takes a `string` list of functions signatures as an argument instead of a `bytes4[]` array of function selectors for three reasons: 1. Passing in function signatures enables the implementation of `updateContract` to prevent selector clashes. 2. A major part of this standard is to make upgradeable contracts more transparent by making it easier to see what has changed over time and why. When a function is added, replaced or removed its function signature is included in the FunctionUpdate event that is emitted. This makes it relatively easy to write software that filters the events of a contract to display to people what functions have been added/removed and changed over time without needing access to the source code or ABI of the contract. If only four-byte function selectors were provided this would not be possible. 3. By looking at the source code of a transparent contract it is not possible to see all the functions that it supports. This is why the ERC1538Query interface exists, so that people and software have a way to look up and examine or show all functions currently supported by a transparent contract. Function signatures are used so that ERC1538Query functions can show them. ### Gas Considerations Delegating function calls does have some gas overhead. This is mitigated in two ways: 1. Delegate contracts can be small, reducing gas costs. Because it costs more gas to call a function in a contract with many functions than a contract with few functions. 2. Because transparent contracts do not have a max size limitation it is possible to add gas optimizing functions for use cases. For example someone could use a transparent contract to implement the ERC721 standard and implement batch transfer functions from the [ERC1412 standard](https://github.com/ethereum/EIPs/issues/1412) to help reduce gas (and make batch transfers more convenient). ### Storage The standard does not specify how data is stored or organized by a transparent contract. But here are some suggestions: **Inherited Storage** 1. The storage variables of a transparent contract consist of the storage variables defined in the transparent contract source code and the source code of delegate contracts that have been added. 2. A delegate contract can use any storage variable that exists in a transparent contract as long as it defines within it all the storage variables that exist, in the order that they exist, up to and including the ones being used. 3. A delegate contract can create new storage variables as long as it has defined, in the same order, all storage variables that exist in the transparent contract. Here is a simple way inherited storage could be implemented: 1. Create a storage contract that contains the storage variables that your transparent contract and delegate contracts will use. 2. Make your delegate contracts inherit the storage contract. 3. If you want to add a new delegate contract that adds new storage variables then create a new storage contract that adds the new storage variables and inherits from the old storage contract. Use your new storage contract with your new delegate contract. 4. Repeat steps 2 or 3 for every new delegate contract. **Unstructured Storage** Assembly is used to store and read data at specific storage locations. An advantage to this approach is that previously used storage locations don't have to be defined or mentioned in a delegate contract if they aren't used by it. **Eternal Storage** Data can be stored using a generic API based on the type of data. [See ERC930 for more information.](https://github.com/ethereum/EIPs/issues/930) ### Becoming Immutable It is possible to make a transparent contract become immutable. This is done by calling the `updateContract` function to remove the `updateContract` function. With this gone it is no longer possible to add, replace and remove functions. ### Versions of Functions Software or a user can verify what version of a function is called by getting the delegate contract address of the function. This can be done by calling the `delegateAddress` function from the ERC1538Query interface if it is implemented. This function takes a function signature as an argument and returns the delegate contract address where it is implemented. ### Best Practices, Tools and More Information > More information, tools, tutorials and best practices concerning transparent contracts need to be developed and published. Below is a growing list of articles concerning transparent contracts and their use. If you have an article about transparent contracts you would like to share then please submit a comment to this issue about it to get it added. [ERC1538: Future Proofing Smart Contracts and Tokens](https://coinjournal.net/erc1538-future-proofing-smart-contacts-and-tokens/) [The ERC1538 improving towards the “transparent contract” standard](https://www.crypto-economy.net/en/ethereum-eth-erc1538-transparent-contract-standard/) ### Inspiration This standard was inspired by ZeppelinOS's implementation of [Upgradeability with vtables](https://github.com/zeppelinos/labs/tree/master/upgradeability_with_vtable). This standard was also inspired by the design and implementation of the [Mokens contract](https://etherscan.io/address/0xc1eab49cf9d2e23e43bcf23b36b2be14fc2f8838#code) from the [Mokens project](https://github.com/Mokens/MIPs/blob/master/MIPS/mip-2-Goals-and-Objectives.md). The Mokens contract has been [upgraded to implement this standard](https://etherscan.io/address/0x0ac5637fe62ec14fd9e237a81a9679d4adef701f#code). ## Backwards Compatibility This standard makes a contract compatible with future standards and functionality because new functions can be added and existing functions can be replaced or removed. This standard future proofs a contract. ## Implementation A reference implementation of this standard is given in the [transparent-contracts-erc1538](https://github.com/mudgen/transparent-contracts-erc1538) repository. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

contenthash field for ENS

Tue, 13 Nov 2018 00:00:00 +0000

## Abstract This EIP introduces the new `contenthash` field for ENS resolvers, allowing for a better defined system of mapping names to network and content addresses. Additionally the `content` and `multihash` fields are deprecated. ## Motivation Multiple applications including [Metamask](https://metamask.io/) and mobile clients such as [Status](https://status.im) have begun resolving ENS names to content hosted on distributed systems such as [IPFS](https://ipfs.io/) and [Swarm](https://swarm-guide.readthedocs.io). Due to the various ways content can be stored and addressed, a standard is required so these applications know how to resolve names and that domain owners know how their content will be resolved. The `contenthash` field allows for easy specification of network and content addresses in ENS. ## Specification The field `contenthash` is introduced, which permits a wide range of protocols to be supported by ENS names. Resolvers supporting this field MUST return `true` when the `supportsInterface` function is called with argument `0xbc1c58d1`. The fields `content` and `multihash` are deprecated. The value returned by `contenthash` MUST be represented as a machine-readable [multicodec](https://github.com/multiformats/multicodec). The format is specified as follows: ``` ``` protoCodes and their meanings are specified in the [multiformats/multicodec](https://github.com/multiformats/multicodec) repository. The encoding of the value depends on the content type specified by the protoCode. Values with protocodes of 0xe3 and 0xe4 represent IPFS and Swarm content; these values are encoded as v1 [CIDs](https://github.com/multiformats/cid) without a base prefix, meaning their value is formatted as follows: ```

``` When resolving a `contenthash`, applications MUST use the protocol code to determine what type of address is encoded, and resolve the address appropriately for that protocol, if supported. ### Example #### IPFS Input data: ``` storage system: IPFS (0xe3) CID version: 1 (0x01) content type: dag-pb (0x70) hash function: sha2-256 (0x12) hash length: 32 bytes (0x20) hash: 29f2d17be6139079dc48696d1f582a8530eb9805b561eda517e22a892c7e3f1f ``` Binary format: ``` 0xe3010170122029f2d17be6139079dc48696d1f582a8530eb9805b561eda517e22a892c7e3f1f ``` Text format: ``` ipfs://QmRAQB6YaCyidP37UdDnjFY5vQuiBrcqdyoW1CuDgwxkD4 ``` ### Swarm Input data: ``` storage system: Swarm (0xe4) CID version: 1 (0x01) content type: swarm-manifest (0xfa) hash function: keccak256 (0x1b) hash length: 32 bytes (0x20) hash: d1de9994b4d039f6548d191eb26786769f580809256b4685ef316805265ea162 ``` Binary format: ``` 0xe40101fa011b20d1de9994b4d039f6548d191eb26786769f580809256b4685ef316805265ea162 ``` Text format: ``` bzz://d1de9994b4d039f6548d191eb26786769f580809256b4685ef316805265ea162 ``` Example usage with swarm hash: ``` $ swarm hash ens contenthash d1de9994b4d039f6548d191eb26786769f580809256b4685ef316805265ea162 > e40101fa011b20d1de9994b4d039f6548d191eb26786769f580809256b4685ef316805265ea162 ``` ### Fallback In order to support names that have an IPFS or Swarm hash in their `content` field, a grace period MUST be implemented offering those name holders time to update their names. If a resolver does not support the `multihash` interface, it MUST be checked whether they support the `content` interface. If they do, the value of that field SHOULD be treated in a context dependent fashion and resolved. This condition MUST be enforced until at least March 31st, 2019. ### Implementation To support `contenthash`, a new resolver has been developed and can be found [here](https://github.com/ensdomains/resolvers/blob/master/contracts/PublicResolver.sol), you can also find this smart contract deployed on: * Mainnet : [0xd3ddccdd3b25a8a7423b5bee360a42146eb4baf3](https://etherscan.io/address/0xd3ddccdd3b25a8a7423b5bee360a42146eb4baf3) * Ropsten : [0xde469c7106a9fbc3fb98912bb00be983a89bddca](https://ropsten.etherscan.io/address/0xde469c7106a9fbc3fb98912bb00be983a89bddca) There are also implementations in multiple languages to encode and decode `contenthash`: * [JavaScript](https://github.com/pldespaigne/content-hash) * [Python](https://github.com/filips123/ContentHashPy) ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Non-wallet usage of keys derived from BIP-32 trees

Tue, 13 Nov 2018 00:00:00 +0000

## Abstract BIP32 defines a way to generate hierarchical trees of keys which can be derived from a common master key. BIP32 and [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) defines the usage of these keys as wallets. In this EIP we describe the usage of such keys outside the scope of the blockchain defining a logical tree for key usage which can coexist (and thus share the same master) with existing BIP44 compatible wallets. ## Motivation Applications interacting with the blockchain often make use of additional, non-blockchain technologies to perform the task they are designed for. For privacy and security sensitive mechanisms, sets of keys are needed. Reusing keys used for wallets can prove to be insecure, while keeping completely independent keys make backup and migration of the full set of credentials more complex. Defining a separate (from BIP44 compliant wallets) derivation branch allows combining the security of independent keys with the convenience of having a single piece of information which needs to be backup or migrated. ## Specification ### Path levels We define the following levels in BIP32 path: ```m / purpose' / coin_type' / subpurpose' / key_type' / key_index``` Apostrophe in the path indicates that BIP32 hardened derivation is used. This structure follows the [BIP43](https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki) recommendations and its [amendments for non-Bitcoin usage](https://github.com/bitcoin/bips/pull/523/files). Each level has a special meaning, described in the chapters below. ### Purpose/Coin Type/Subpurpose This part is constant and set to ```m / 43' / 60' / 1581'```, meaning BIP 43 -> Ethereum -> This EIP. All subtrees under this prefix are the scope of this EIP. ### Key type Describes the purpose for which the key is being used. Key types should be generic. "Instant messaging" is a good example whereas "Whisper" is not. The reason is that you want to be able to use the same identity across different services. Key types are defined at: TBD Hardened derivation is used at this level. ### Key index The key index is a field of variable length identifying a specific key. In its simplest case, it is a number from 0 to 2^31-1. If a larger identifier is desired (for example representing a hash or a GUID), the value must be split across several BIP32 nesting levels, most significant bit first and left aligned, bit-padded with 0s if needed. All levels, except the last one must used hardened key derivation. The last level must use public derivation. This means that every level can carry 31-bit of the identifier to represent. As an example, let's assume we have a key with key type 4' and a key_index representing a 62-bit ID represented as hexadecimal 0x2BCDEFFEDCBAABCD the complete keypath would be ```m / 43' / 60' / 1581' / 4' / ‭1469833213‬' / ‭1555737549‬ ```. If you are using random identifiers, it might be convenient to generate a conventional GUID, for example 128-bit just fix the value of the most significant bit of each 32-bit word to 1 for all of them, except the last one which will be 0. ## Rationale The structure proposed above follows the BIP43 generic structure and is similar to the widely adopted BIP44 specification. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Address and ERC20-compliant transfer rules

Fri, 09 Nov 2018 00:00:00 +0000

## Simple Summary We propose a standard and an interface to define transfer rules, in the context of ERC20 tokens and possibly beyond. A rule can act based on sender, destination and amount, and is triggered (and rejects the transfer) according to any required business logic. To ease rule reusability and composition, we also propose an interface and base implementation for a rule engine. ## Abstract This standard proposal should answer the following challenges: - Enable integration of rules with interacting platforms such as exchanges, decentralized wallets and DApps. - Externale code and storage, improve altogether reusability, gas costs and contracts' memory footprint. - Highlight contract behavior and its evolution, in order to ease user interaction with such contract. If these challenges are answered, this proposal will provide a unified basis for transfer rules and hopefully address the transfer restriction needs of other EIPs as well, e.g. [EIP-902](./eip-902.md), [EIP-1066](./eip-1066.md) and [EIP-1175](./eip-1175.md). This document proposes specifications for a standard of **transfer rules** and interfaces to both the rules and the rule engine, which was made to be inherited by a token, but may have a much broader scope in the authors' opinion. The last section of this document illustrates the proposal with a rule template and links to rule implementations. ## Motivation ERC20 was designed as a standard interface allowing any token on Ethereum to be handled by other applications: from wallets to decentralized exchanges. This has been extremely powerful, but future developments in the industry of tokenization are bringing new challenges. For example it is already hard to know exactly why an ERC20 transfer failed, and it will become even harder when many tokens add their own transfer rules to the mix; we propose that it should be trivial to determine before a tx is sent, whether the transfer should turn out valid or invalid, and why (unless conditions change in the meantime obviously). On the other hand, if the rules were changed, it should also be easily detected, so that the interacting party knows it must adjust its expectations or model. ## Specification We define below an interface for a rule. Rules are meant to be as simple as possible, to limit gas expenditure, since that logic will be executed on every transfer. Another reason for keeping rules simple and short, and strive for atomicity, is to facilitate both composition and interpretation of rejected transfers. By knowing which rule was triggered, we obtain a clear picture of the reason for rejection. The engine we propose executes all the rules defined by its owner, on every transfer and it is easy to add and remove rules individually, although we have chosen to use quite a raw rule update method, to save on deployment costs, which are often tight when it comes to token smart contracts. Rules are deployed on the blockchain as individual smart contracts, and called upon by the rule engine they were attached to. But any third party, for example an exchange preparing a cashout for a customer, can very cheaply query the rule engine of the token, or a single rule directly, to verify the validity of a transfer before execution, so as to never get a rejected transaction. ## Rule interface `IRule` interface should provide a way to validate if an address or a transfer is valid. If one of these two methods is not applicable, it can simply be made to return true systematically. If any parameter of `isTransferValid` is not needed, its name should be commented out with `/* */`. ```js pragma solidity ^0.4.25; interface IRule { function isAddressValid(address _address) external view returns (bool); function isTransferValid(address _from, address _to, uint256 _amount) external view returns (bool); } ``` ## WithRules interface `WithRules` interface describes the integration of rules to a rule engine. Developers may choose to not implement this interface if their code will only deal with one rule, or if it is not desirable to update the rules. The rules ordering must be thought through carefully. Rules which are cheaper to validate or have a higher chance to break should be put first to reduce global gas expenditure, then business logic should guide the ordering of rules. That is why rules for a given context should be defined as a whole and not individually. ```js pragma solidity ^0.4.25; import "./IRule.sol"; interface IWithRules { function ruleLength() public view returns (uint256); function rule(uint256 _ruleId) public view returns (IRule); function validateAddress(address _address) public view returns (bool); function validateTransfer(address _from, address _to, uint256 _amount) public view returns (bool); function defineRules(IRule[] _rules) public; event RulesDefined(uint256 count); } ``` ## WithRules implementation We also propose a simple implementation of the rule engine, available [here](https://github.com/MtPelerin/MtPelerin-protocol/blob/master/contracts/rule/WithRules.sol). It has been kept minimal both to save on gas costs on each transfer, and to reduce the deployment cost overhead for the derived smart contract. On top of implementing the interface above, this engine also defines two modifiers (`whenAddressRulesAreValid`and `whenTransferRulesAreValid`), which can be used throughout the token contract to restrict `transfer()`, `transferFrom` and any other function that needs to respect either a simple whitelist or complex transfer rules. ## Integration To use rules within a token is as easy as having the token inherit from WithRules, then writing rules according to the IRule interface and deploying each rule individually. The token owner can then use `defineRules()` to attach all rules in the chosen order, within a single transaction. Below is a template for a rule. ```solidity import "../interface/IRule.sol"; contract TemplateRule is IRule { // state vars for business logic constructor(/* arguments for init */) public { // initializations } function isAddressValid(address _from) public view returns (bool) { boolean isValid; // business logic return isValid; } function isTransferValid( address _from, address _to, uint256 _amount) public view returns (bool) { boolean isValid; // business logic return isValid; } } ``` *** Notes *** The MPS (Mt Pelerin's Share) token is the current live implementation of this standard. Other implementations may be written with different trade-offs: from gas savings to improved security. #### Example of rules implementations - [YesNo rule](https://github.com/MtPelerin/MtPelerin-protocol/tree/master/contracts/rule/YesNoRule.sol): Trivial rule used to demonstrate both a rule and the rule engine. - [Freeze rule](https://github.com/MtPelerin/MtPelerin-protocol/tree/master/contracts/rule/FreezeRule.sol): This rule allows to prevent any transfer of tokens to or from chosen addresses. A smart blacklist. - [Lock rule](https://github.com/MtPelerin/MtPelerin-protocol/tree/master/contracts/rule/LockRule.sol): Define a global transfer policy preventing either sending or receiving tokens within a period of time. Exceptions may be granted to some addresses by the token admin. A smart whitelist. - [User Kyc Rule](https://github.com/MtPelerin/MtPelerin-protocol/tree/master/contracts/rule/UserKycRule.sol): Rule example relying on an existing whitelist to assert transfer and addresses validity. It is a good example of a rule that completely externalizes it's tasks. #### Example implementations are available at - [Mt Pelerin Bridge protocol rules implementation](https://github.com/MtPelerin/MtPelerin-protocol/tree/master/contracts/rule) - [Mt Pelerin Token with rules](https://github.com/MtPelerin/MtPelerin-protocol/blob/master/contracts/token/component/TokenWithRules.sol) ## History Historical links related to this standard: - The first regulated tokenized share issued by Mt Pelerin (MPS token) is using an early version of this proposal: https://www.mtpelerin.com/blog/world-first-tokenized-shares The rule engine was updated several times, after the token issuance and during the tokensale, to match changing business and legal requirements, showcasing the solidity and flexibility of the rule engine. ## Copyright Copyright and related rights waived via [CC0](/LICENSE). External references outside this repository will have their own specific copyrights.

Gas stations network

Sun, 18 Nov 2018 00:00:00 +0000

## Simple Summary Make smart contracts (e.g. dapps) accessible to non-ether users by allowing contracts to accept "[collect-calls](https://en.wikipedia.org/wiki/Collect_call)", paying for incoming calls. Let contracts "listen" on publicly accessible channels (e.g. web URL or a whisper address). Incentivize nodes to run "gas stations" to facilitate this. Require no network changes, and minimal contract changes. ## Abstract Communicating with dapps currently requires paying ETH for gas, which limits dapp adoption to ether users. Therefore, contract owners may wish to pay for the gas to increase user acquisition, or let their users pay for gas with fiat money. Alternatively, a 3rd party may wish to subsidize the gas costs of certain contracts. Solutions such as described in [EIP-1077](./eip-1077.md) could allow transactions from addresses that hold no ETH. The gas stations network is an [EIP-1077](./eip-1077.md) compliant effort to solve the problem by creating an incentive for nodes to run gas stations, where gasless transactions can be "fueled up". It abstracts the implementation details from both the dapp maintainer and the user, making it easy to convert existing dapps to accept "collect-calls". The network consists of a single public contract trusted by all participating dapp contracts, and a decentralized network of relay nodes (gas stations) incentivized to listen on non-ether interfaces such as web or whisper, pay for transactions and get compensated by that contract. The trusted contract can be verified by anyone, and the system is otherwise trustless. Gas stations cannot censor transactions as long as there's at least one honest gas station. Attempts to undermine the system can be proven on-chain and offenders can be penalized. ## Motivation * Increase user adoption of smart contracts by: * Removing the user hassle of acquiring ETH. Transactions are still paid by ETH but costs can be borne by the dapp or paid by the user through other means. * Removing the need to interact directly with the blockchain, while maintaining decentralization and censorship-resistance. Contracts can "listen" on multiple public channels, and users can interact with the contracts through common protocols that are generally permitted even in restrictive environments. * Ethereum nodes get a revenue source without requiring mining equipment. The entire network benefits from having more nodes. * No protocol changes required. The gas station network is self-organized via a smart contract, and dapps interact with the network by implementing an interface. ## Specification The system consists of a `RelayHub` singleton contract, participating contracts inheriting the `RelayRecipient` contract, a decentralized network of `Relay` nodes, a.k.a. Gas Stations, and user applications (e.g. mobile or web) interacting with contracts via relays. Roles of the `RelayHub`: * Maintain a list of active relays. Senders select a `Relay` from this list for each transaction. The selection process is discussed below. * Mediate all communication between relays and contracts. * Provide contracts with trusted versions of the real msg.sender and msg.data. * Hold ETH stakes placed by relays. A minimum stake size is enforced. Stake can be withdrawn after a relay unregisters and waits for a cooldown period. * Hold ETH prepayments made by contracts and use them to compensate relays. * Penalize provably-offensive relays by giving their stakes to an address providing the proof, thus keeping relays honest. * Provide a free way for relays to know whether they'll be compensated for a future transaction. Roles of a `Relay` node: * Maintain a hot wallet with a small amount of ETH, to pay for gas. * Provide a public interface for user apps to send gasless transactions via channels such as https or whisper. * Publish it's public interfaces and its price (as a multiplier of the actual transaction gas cost) in `RelayHub`. * Optionally monitor reverted transactions of other relays through RelayHub, catching offending relays and claiming their stakes. This can be done by anyone, not just a relay. Implementing a `RelayRecipient` contract: * Know the address of `RelayHub` and trust it to provide information about the transaction. * Maintain a small balance of ETH gas prepayment deposit in `RelayHub`. Can be paid directly by the `RelayRecipient` contract, or by the dapp's owner on behalf of the `RelayRecipient` address. The dapp owner is responsible for ensuring sufficient balance for the next transactions, and can stop depositing if something goes wrong, thus limiting the potential for abuse of system bugs. In DAO usecases it will be up to the DAO logic to maintain a sufficient deposit. * Use `getSender()` and `getMessageData()` instead of `msg.sender` and `msg.data`, everywhere. `RelayRecipient` provides these functions and gets the information from `RelayHub`. * Implement a `acceptRelayedCall(address relay, address from, bytes memory encodedFunction, uint gasPrice, uint transactionFee, bytes memory approval)` view function that returns **zero** if and only if it is willing to accept a transaction and pay for it. `acceptRelayedCall` is called by `RelayHub` as a view function when a `Relay` inquires it, and also during the actual transaction. Transactions are reverted if **non-zero**, and `Relay` only gets compensated for transactions (whether successful or reverted) if `acceptRelayedCall` returns **zero**. Some examples of `acceptRelayedCall()` implementations: * Whitelist of trusted dapp members. * Balance sheet of registered users, maintained by the dapp owner. Users pay the dapp with a credit card or other non-ETH means, and are credited in the `RelayRecipient` balance sheet. Users can never cost the dapp more than they were credited for. * A dapp can provide off-chain a signed message called `approval` to a transaction sender and validate it. * Whitelist of known transactions used for onboarding new users. This allows certain anonymous calls and is subject to Sybil attacks. Therefore it should be combined with a restricted gasPrice, and a whitelist of trusted relays, to reduce the incentive for relays to create bogus transactions and rob the dapp's prepaid gas deposit. Dapps allowing anonymous onboarding transactions might benefit from registering their own `Relay` and accepting anonymous transactions only from that `Relay`, whereas other transactions can be accepted from any relay. Alternatively, dapps may use the balance sheet method for onboarding as well, by applying the methods suggested in the attacks/mitigations section below. * Implement `preRelayedCall(address relay, address from, bytes memory encodedFunction, uint transactionFee) returns (bytes32)`. This method is called before a transaction is relayed. By default, it does nothing. * Implement `postRelayedCall(ddress relay, address from, bytes memory encodedFunction, bool success, uint usedGas, uint transactionFee, bytes32 preRetVal)`. This method is called after a transaction is relayed. By default, it does nothing. These two methods can be used to charge the user in dapp-specific manner. Glossary of terms used in the processes below: * `RelayHub` - the RelayHub singleton contract, used by everyone. * `Recipient` - a contract implementing `RelayRecipient`, accepting relayed transactions from the RelayHub contract and paying for the incoming transactions. * `Sender` - an external address with a valid key pair but no ETH to pay for gas. * `Relay` - a node holding ETH in an external address, listed in RelayHub and relaying transactions from Senders to RelayHub for a fee. ![Sequence Diagram](../assets/eip-1613/sequence.png) The process of registering/refreshing a `Relay`: * Relay starts listening as a web app (or on some other communication channel). * If starting for the first time (no key yet), generate a key pair for Relay's address. * If Relay's address doesn't hold sufficient funds for gas (e.g. because it was just generated), Relay stays inactive until its owner funds it. * Relay's owner funds it. * Relay's owner sends the required stake to `RelayHub` by calling `RelayHub.stake(address relay, uint unstakeDelay)`. * `RelayHub` puts the `owner` and `unstake delay` in the relays map, indexed by `relay` address. * Relay calls `RelayHub.registerRelay(uint transactionFee, string memory url)` with the relay's `transaction fee` (as a multiplier on transaction gas cost), and a URL for incoming transactions. * `RelayHub` ensures that Relay has a sufficient stake. * `RelayHub` puts the `transaction fee` in the relays map. * `RelayHub` emits an event, `RelayAdded(Relay, owner, transactionFee, relayStake, unstakeDelay, url)`. * Relay starts a timer to perform a `keepalive` transaction every 6000 blocks. * `Relay` goes to sleep and waits for signing requests. The process of sending a relayed transaction: * `Sender` selects a live `Relay` from RelayHub's list by looking at `RelayAdded` events from `RelayHub`, and sorting based on its own criteria. Selection may be based on a mix of: * Relay published transaction fees. * Relay stake size and lock-up time. * Recent relay transactions (visible through `TransactionRelayed` events from `RelayHub`). * Optionally, reputation/blacklist/whitelist held by the sender app itself, or its backend, on per-app basis (not part of the gas stations network). * Sender prepares the transaction with Sender's address, the recipient address, the actual transaction data, Relay's transaction fee, gas price, gas limit, its current nonce from `RelayHub.nonces`, RelayHub's address, and Relay's address, and then signs it. * Sender verifies that `RelayHub.balances[recipient]` holds enough ETH to pay Relay's fee. * Sender verifies that `Relay.balance` has enough eth to send the transaction * Sender reads the Relay's current `nonce` value and decides on the `max_nonce` parameter. * Sender sends the signed transaction amd metadata to Relay's web interface. * `Relay` wraps the transaction with a transaction to `RelayHub`, with zero ETH value. * `Relay` signs the wrapper transaction with its key in order to pay for gas. * `Relay` verifies that: * The transaction's recipient contract will accept this transaction when submitted, by calling `RelayHub.canRelay()`, a view function, which checks the recipient's `acceptRelayedCall`, also a view function, stating whether it's willing to accept the charges). * The transaction nonce matches `RelayHub.nonces[sender]`. * The relay address in the transaction matches Relay's address. * The transaction's recipient has enough ETH deposited in `RelayHub` to pay the transaction fee. * Relay has enough ETH to pay for the gas required by the transaction. * Value of `max_nonce` is higher than current Relay's `nonce` * If any of Relay's checks fail, it returns an error to sender, and doesn't proceed. * Relay submits the signed wrapped transaction to the blockchain. * Relay immediately returns the signed wrapped transaction to the sender. This step is discussed below, in attacks/mitigations. * `Sender` receives the wrapped transaction and verifies that: * It's a valid relay call to `RelayHub`. from Relay's address. * The transaction's ethereum nonce matches Relay's current nonce. * The transaction's ethereum nonce is lower than or equal to `max_nonce`. * `Relay` is sufficiently funded to pay for it. * The wrapped transaction is valid and signed by `sender`. * Recipient contract has sufficient funds in `RelayHub.balances` to pay for Relay's fee as stated in the transaction. * If any of sender's checks fails, it goes back to selecting a new Relay. Sender may also file a report on the unresponsive relay to its backend or save it locally, to down-sort this relay in future transactions. * `Sender` may also submit the raw wrapped transaction to the blockchain without paying for gas, through any Ethereum node. This submission is likely ignored because an identical transaction is already in the network's pending transactions, but no harm in putting it twice, to ensure that it happens. This step is not strictly necessary, for reasons discussed below in attacks/mitigations, but may speed things up. * `Sender` monitors the blockchain, waiting for the transaction to be mined. The transaction was verified, with Relay's current nonce, so mining must be successful unless Relay submitted another (different) transaction with the same nonce. If mining fails due to such attack, sender may call `RelayHub.penalizeRepeatedNonce` through another relay, to collect his reward and burn the remainder of the offending relay's stake, and then go back to selecting a new Relay for the transaction. See discussion in the attacks/mitigations section below. * `RelayHub` receives the transaction: * Records `gasleft()` as `initialGas` for later payment. * Verifies the transaction is sent from a registered relay. * Verifies that the signature of the internal transaction matches its stated origin (sender's key). * Verifies that the relay address written in the transaction matches msg.sender. * Verifies that the transaction's `nonce` matches the stated origin's nonce in `RelayHub.nonces`. * Calls recipient's `acceptRelayedCall` function, asking whether it's going to accept the transaction. If not, the `TransactionRelayed` will be emitted with status `CanRelayFailed`, and `chargeOrCanRelayStatus` will contain the return value of `acceptRelayedCall`. In this case, Relay doesn't get paid, as it was its responsibility to check `RelayHub.canRelay` before releasing the transaction. * Calls recipient's `preRelayedCall` function. If this call reverts the `TransactionRelayed` will be emitted with status `PreRelayedFailed`. * Sends the transaction to the recipient. If this call reverts the `TransactionRelayed` will be emitted with status `RelayedCallFailed`. When passing gas to `call()`, enough gas is preserved by `RelayHub`, for post-call handling. Recipient may run out of gas, but `RelayHub` never does. `RelayHub` also sends sender's address at the end of `msg.data`, so `RelayRecipient.getSender()` will be able to extract the real sender, and trust it because the transaction came from the known `RelayHub` address. * Recipient contract handles the transaction. * `RelayHub` calls recipient's `postRelayedCall`. * `RelayHub` checks call's return value of call, and emits `TransactionRelayed(address relay, address from, address to, bytes4 selector, uint256 status, uint256 chargeOrCanRelayStatus)`. * `RelayHub` increases `RelayHub.nonces[sender]`. * `RelayHub` transfers ETH balance from recipient to `Relay.owner`, to pay the transaction fee, based on the measured transaction cost. Note on relay payment: The relay gets paid for actual gas used, regardless of whether the recipient reverted. The only case where the relay sustains a loss, is if `canRelay` returns non-zero, since the relay was responsible to verify this view function prior to submitting. Any other revert is caught and paid for. See attacks/mitigations below. * `Relay` keeps track of transactions it sent, and waits for `TransactionRelayed` events to see the charge. If a transaction reverts and goes unpaid, which means the recipient's `acceptRelayedCall()` function was inconsistent, `Relay` refuses service to that recipient for a while (or blacklists it indefinitely, if it happens often). See attacks/mitigations below. The process of winding a `Relay` down: * Relay's owner (the address that initially funded it) calls `RelayHub.removeRelayByOwner(Relay)`. * `RelayHub` ensures that the sender is indeed Relay's owner, then removes `Relay`, and emits `RelayRemoved(Relay)`. * `RelayHub` starts the countdown towards releasing the owner's stake. * `Relay` receives its `RelayRemoved` event. * `Relay` sends all its remaining ETH to its owner. * `Relay` shuts down. * Once the owner's unstake delay is over, owner calls `RelayHub.unstake()`, and withdraws the stake. ## Rationale The rationale for the gas stations network design is a combination of two sets of requirements: Easy adoption, and robustness. For easy adoption, the design goals are: * No network changes. * Minimal changes to contracts, apps and frameworks. The robustness requirement translates to decentralization and attack resistance. The gas stations network is decentralized, and we have to assume that any entity may attack other entities in the system. Specifically we've considered the following types of attacks: * Denial-of-service attacks against individual senders, i.e. transactions censorship. * Denial-of-service and financial attacks against individual relays. * Denial-of-service and financial attacks against individual contracts. * Denial-of-service attacks against the entire network, either by attacking existing entities, or by introducing any number of malicious entities. #### Attacks and mitigations ##### Attack: Relay attempts to censor a transaction by not signing it, or otherwise ignoring a user request. Relay is expected to return the signed transaction to the sender, immediately. Sender doesn't need to wait for the transaction to be mined, and knows immediately whether it's request has been served. If a relay doesn't return a signed transaction within a couple of seconds, sender cancels the operation, drops the connection, and switches to another relay. It also marks Relay as unresponsive in its private storage to avoid using it in the near future. Therefore, the maximal damage a relay can cause with such attack, is a one-time delay of a couple of seconds. After a while, senders will avoid it altogether. ##### Attack: Relay attempts to censor a transaction by signing it, returning it to the sender, but never putting it on the blockchain. This attack will backfire and not censor the transaction. The sender can submit the transaction signed by Relay to the blockchain as a raw transaction through any node, so the transaction does happen, but Relay may be unaware and therefore be stuck with a bad nonce which will break its next transaction. ##### Attack: Relay attempts to censor a transaction by signing it, but publishing a different transaction with the same nonce. Reusing the nonce is the only DoS performed by a Relay, that cannot be detected within a couple of seconds during the http request. It will only be detected when the malicious transaction with the same nonce gets mined and triggers the `RelayHub.TransactionRelayed` event. However, the attack will backfire and cost Relay its entire stake. Sender has a signed transaction from Relay with nonce N, and also gets a mined transaction from the blockchain with nonce N, also signed by Relay. This proves that Relay performed a DoS attack against the sender. The sender calls `RelayHub.penalizeRepeatedNonce(bytes transaction1, bytes transaction2)`, which verifies the attack, confiscates Relay's stake, and sends half of it to the sender who delivered the `penalizeRepeatedNonce` call. The other half of the stake is burned by sending it to `address(0)`. Burning is done to prevent cheating relays from effectively penalizing themselves and getting away without any loss. The sender then proceeds to select a new relay and send the original transaction. The result of such attack is a delay of a few blocks in sending the transaction (until the attack is detected) but the relay gets removed and loses its entire stake. Scaling such attack would be prohibitively expensive, and actually quite profitable for senders and honest relays. ##### Attack: Relay attempts to censor a transaction by signing it, but using a nonce higher than it's current nonce. In this attack, the Relay did create and return a perfectly valid transaction, but it will not be mined until this Relay fills the gap in the nonce with 'missing' transactions. This may delay the relaying of some transactions indefinitely. In order to mitigate that, the sender includes a `max_nonce` parameter with it's signing request. It is suggested to be higher by 2-3 from current nonce, to allow the relay process several transactions. When the sender receives a transaction signed by a Relay he validates that the nonce used is valid, and if it is not, the client will ignore the given relay and use other relays to relay given transaction. Therefore, there will be no actual delay introduced by such attack. ##### Attack: Dapp attempts to burn relays funds by implementing an inconsistent acceptRelayedCall() and using multiple sender addresses to generate expensive transactions, thus performing a DoS attack on relays and reducing their profitability. In this attack, a contract sets an inconsistent acceptRelayedCall (e.g. return zero for even blocks, nonzero for odd blocks), and uses it to exhaust relay resources through unpaid transactions. Relays can easily detect it after the fact. If a transaction goes unpaid, the relay knows that the recipient contract's acceptRelayedCall has acted inconsistently, because the relay has verified its view function before sending the transaction. It might be the result of a rare race condition where the contract's state has changed between the view call and the transaction, but if it happens too frequently, relays will blacklist this contract and refuse to serve transactions to it. Each offending contract can only cause a small damage (e.g. the cost of 2-3 transactions) to a relay, before getting blacklisted. Relays may also look at recipients' history on the blockchain, looking for past unpaid transactions (reverted by RelayHub without pay), and denying service to contracts with a high failure rate. If a contract caused this minor loss to a few relays, all relays will stop serving it, so it can't cause further damage. This attack doesn't scale because the cost of creating a malicious contract is in the same order of magnitude as the damage it can cause to the network. Causing enough damage to exhaust the resources of all relays, would be prohibitively expensive. The attack can be made even more impractical by setting RelayHub to require a stake from dapps before they can be served, and enforcing an unstaking delay, so that attackers will have to raise a vast amount of ETH in order to simultaneously create enough malicious contracts and attack relays. This protection is probably an overkill, since the attack doesn't scale regardless. ##### Attack: User attempts to rob dapps by registering its own relay and sending expensive transactions to dapps. If a malicious sender repeatedly abuses a recipient by sending meaningless/reverted transactions and causing the recipient to pay a relay for nothing, it is the recipient's responsibility to blacklist that sender and have its acceptRelayedCall function return nonzero for that sender. Collect calls are generally not meant for anonymous senders unknown to the recipient. Dapps that utilize the gas station networks should have a way to blacklist malicious users in their system and prevent Sybil attacks. A simple method that mitigates such Sybil attack, is that the dapp lets users buy credit with a credit card, and credit their account in the dapp contract, so acceptRelayedCall() only returns zero for users that have enough credit, and deduct the amount paid to the relay from the user's balance, whenever a transaction is relayed for the user. With this method, the attacker can only burn its own resources, not the dapp's. A variation of this method, for free dapps (that don't charge the user, and prefer to pay for their users transactions) is to require a captcha during user creation in their web interface, or to login with a Google/Facebook account, which limits the rate of the attack to the attacker's ability to open many Google/Facebook accounts. Only a user that passed that process is given credit in RelayRecipient. The rate of such Sybil attack would be too low to cause any real damage. ##### Attack: Attacker attempts to reduce network availability by registering many unreliable relays. Registering a relay requires placing a stake in RelayHub, and the stake can only be withdrawn after the relay is unregistered and a long cooldown period has passed, e.g. a month. Each unreliable relay can only cause a couple of seconds delay to senders, once, and then it gets blacklisted by them, as described in the first attack above. After it caused this minor delay and got blacklisted, the attacker must wait a month before reusing the funds to launch another unreliable relay. Simultaneously bringing up a number of unreliable relays, large enough to cause a noticeable network delay, would be prohibitively expensive due to the required stake, and even then, all those relays will get blacklisted within a short time. ##### Attack: Attacker attempts to replay a relayed transaction. Transactions include a nonce. RelayHub maintains a nonce (counter) for each sender. Transactions with bad nonces get reverted by RelayHub. Each transaction can only be relayed once. ##### Attack: User does not execute the raw transaction received from the Relayer, therefore blocking the execution of all further transactions signed by this relayer The user doesn't really have to execute the raw transaction. It's enough that the user can. The relationship between relay and sender is mutual distrust. The process described above incentivizes the relay to execute the transaction, so the user doesn't need to wait for actual mining to know that the transaction has been executed. Once relay returns the signed transaction, which should happen immediately, the relay is incentivized to also execute it on chain, so that it can advance its nonce and serve the next transaction. The user can (but doesn't have to) also execute the transaction. To understand why the attack isn't viable, consider the four possible scenarios after the signed transaction was returned to the sender: 1. Relay executes the transaction, and the user doesn't. In this scenario the transaction is executed, so no problem. This is the case described in this attack. 2. Relay doesn't execute the transaction, but the user does. Similarly to 1, the transaction is executed, so no problem. 3. Both of them execute the transaction. The transactions are identical in the pending transactions pool, so the transaction gets executed once. No problem. 4. None of them execute the transaction. In this case the transaction doesn't get executed, but the relay is stuck. It can't serve the next transaction with the next nonce, because its nonce hasn't been advanced on-chain. It also can't serve the next transaction with the current nonce, as this can be proven by the user, having two different transactions signed by the same relay, with the same nonce. The user could use this to take the relay's nonce. So the relay is stuck unless it executes the transaction. As this matrix shows, the relay is __always__ incentivized to execute the transaction, once it returned it to the user, in order to end up in #1 or #3, and avoid the risk of #4. It's just a way to commit the relay to do its work, without requiring the user to wait for on-chain confirmation. ## Backwards Compatibility The gas stations network is implemented as smart contracts and external entities, and does not require any network changes. Dapps adding gas station network support remain backwards compatible with their existing apps/users. The added methods apply on top of the existing ones, so no changes are required for existing apps. ## Implementation A working implementation of the [**gas stations network**](https://github.com/tabookey-dev/tabookey-gasless) is being developed by **TabooKey**. It consists of `RelayHub`, `RelayRecipient`, `web3 hooks`, an implementation of a gas station inside `geth`, and sample dapps using the gas stations network. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Attribute Registry Standard

Fri, 23 Nov 2018 00:00:00 +0000

## Simple Summary EIP-1616 provides a basic interface for querying a registry for attribute metadata assigned to Ethereum accounts. ## Abstract This EIP contains the following core ideas: 1. Instead of relying directly on the reputation of a claims issuer to assess the veracity of a given claim, trust can be brought up to the level of a registry curator. This registry which we call an "**Attribute Registry**" allows for reduced complexity in implementation since a party needing to verify an attribute can now work with a trusted claims aggregator instead of relying on individual claim providers. 2. Claims are abstracted as standard "attributes" which represent metadata assigned to an account, with claims decoupled from the issuing party. Attributes are registered as a flat `uint256 -> uint256` key-value pair on each account, with the important property that **each attribute type has one canonical value per address**. This property allows for composability of attribute registries and advanced attribute formation. 3. There is a generic method for determining the set of attribute keys or IDs made available by the registry. The standard does not specify requirements or recommendations for how attributes and their values are managed, or what additional metadata may be associated with attributes. It is likely that a standard set of attribute names and metadata schema could be proposed in a separate EIP. Potential advanced uses of attribute registries include: * Encoding complex boolean expressions which combine multiple attributes into a single uint256 key, which is then parsed and evaluated by the registry logic. * Using values associated with an attribute to query additional on-chain or off-chain metadata. * Resolving attribute values by calling into separate attribute registries or other contracts, delegating authority without changing the interface of the registry. ## Motivation This EIP is motivated by the need for contracts and external accounts to be able to verify information about a given address from a single trusted source **without concerning themselves with the particular details of how the information was obtained**, and to do so in as simple a manner as possible. It is also motivated by the desire to promote broad **cross-compatibility and composability** between attribute registries, a property which is amplified by both the simplicity of the interface as well as by the guarantees on uniqueness provided by the proposed standard. Existing EIPs for assigning metadata to an account include EIP-735 and EIP-780, which both allow for multiple claims to be issued on the same address for any given claim topic. This forces verifiers of said metadata to assess the veracity of each claim, taking into account the relative reputation of each claim issuer. It also prescribes a methodology for adding and removing claims, which may not be appropriate for all use cases. This EIP proposes a light-weight abstraction layer for a standard account metadata registry interface. This abstraction layer can sit on top of claims registries like EIP-735 and EIP-780 or others as the attribute registry curator selects trusted data sources. ## Specification The Attribute Registry interface contains four functions, outlined as follows: ```solidity /** * @title EIP-1616 Attribute Registry Standard interface. EIP-165 ID: 0x5f46473f */ interface AttributeRegistryInterface { function hasAttribute(address account, uint256 attributeTypeID) external view returns (bool); function getAttributeValue(address account, uint256 attributeTypeID) external view returns (uint256); function countAttributeTypes() external view returns (uint256); function getAttributeTypeID(uint256 index) external view returns (uint256); } ``` Contracts that comply with the Attribute Registry EIP MUST implement the above interface. As an additional requirement, the ERC-165 interface MUST be included: ```solidity /** * @title EIP-165 interface. EIP-165 ID: 0x01ffc9a7 */ interface EIP-165 { /** * @notice EIP-165 support. Attribute Registry interface ID is 0x5f46473f. * @param _interfaceID The interface identifier, as specified in EIP-165 * @return True for 0x01ffc9a7 & 0x5f46473f, false for unsupported interfaces. */ function supportsInterface(bytes4 _interfaceID) external view returns (bool); } ``` The implementation MUST follow the specifications described below. ### View Functions The view functions detailed below MUST be implemented. #### `hasAttribute` function ```solidity function hasAttribute(address account, uint256 attributeTypeID) external view returns (bool) ``` Check if an attribute has been assigned to a given account on the registry and is currently valid. _**NOTE**_: This function MUST return either true or false - i.e. calling this function MUST NOT cause the caller to revert. Implementations that wish to call into another contract during execution of this function MUST catch any `revert` and instead return `false`. _**NOTE**_: This function MUST return two equal values when performing two directly consecutive function calls with identical `account` and `attributeTypeID` parameters, regardless of differences in the caller's address, the transaction origin, or other out-of-band information. #### `getAttributeValue` function ```solidity function getAttributeValue(address account, uint256 attributeTypeID) external view returns (uint256) ``` Retrieve the `uint256` value of an attribute on a given account on the registry, assuming the attribute is currently valid. _**NOTE**_: This function MUST revert if a directly preceding or subsequent function call to `hasAttribute` with identical `account` and `attributeTypeID` parameters would return false. _**NOTE**_: This function MUST return two equal values when performing two directly consecutive function calls with identical `account` and `attributeTypeID` parameters, regardless of differences in the caller's address, the transaction origin, or other out-of-band information. #### `countAttributeTypes` function ```solidity function countAttributeTypes() external view returns (uint256) ``` Retrieve the total number of valid attribute types defined on the registry. Used alongside `getAttributeTypeID` to determine all of the attribute types that are available on the registry. _**NOTE**_: This function MUST return a positive integer value - i.e. calling this function MUST NOT cause the caller to revert. _**NOTE**_: This function MUST return a value that encompasses all indexes of attribute type IDs whereby a call to `hasAttribute` on some address with an attribute type ID at the given index would return `true`. #### `getAttributeTypeID` function ```solidity function getAttributeTypeID(uint256 index) external view returns (uint256) ``` Retrieve an ID of an attribute type defined on the registry by index. Used alongside `countAttributeTypes` to determine all of the attribute types that are available on the registry. _**NOTE**_: This function MUST revert if the provided `index` value falls outside of the range of the value returned from a directly preceding or subsequent function call to `countAttributeTypes`. It MUST NOT revert if the provided `index` value falls inside said range. _**NOTE**_: This function MUST return an `attributeTypeID` value on *some* index if the same `attributeTypeID` value would cause a given call to `hasAttribute` to return `true` when passed as a parameter. ## Rationale This standard extends the applicability of metadata assignment to those use cases that are not adequately represented by EIP-735, EIP-780, or similar proposals. Namely, it enforces the constraint of one attribute value per attribute ID per address, as opposed to one value per ID per address *per issuer*. Aside from the prescribed attribute value, attribute properties are deliberately omitted from the standard. While many attribute registries will require additional metadata on attributes at both the instance and the class level, reliable and flexible interoperability between highly variable registry extensions is facilitated more effectively by enforcing a widely-applicable base layer for attributes. ## Backwards Compatibility There are no backwards compatibility concerns. ## Test Cases Targeted test cases with 100% code coverage can be found at [this repository](https://github.com/0age/AttributeRegistry). See [here](https://github.com/TPL-protocol/tpl-contracts) for tests on a more complex contract that implements the application registry interface. ## Implementation The basic implementation that follows can be found at [this repository](https://github.com/0age/AttributeRegistry) (see [here](https://github.com/TPL-protocol/tpl-contracts/blob/master/contracts/BasicJurisdiction.sol#L399) for an example of a more complex implementing contract): ```solidity pragma solidity ^0.4.25; /** * @title Attribute Registry interface. EIP-165 ID: 0x5f46473f */ interface AttributeRegistryInterface { /** * @notice Check if an attribute of the type with ID `attributeTypeID` has * been assigned to the account at `account` and is currently valid. * @param account address The account to check for a valid attribute. * @param attributeTypeID uint256 The ID of the attribute type to check for. * @return True if the attribute is assigned and valid, false otherwise. * @dev This function MUST return either true or false - i.e. calling this * function MUST NOT cause the caller to revert. */ function hasAttribute( address account, uint256 attributeTypeID ) external view returns (bool); /** * @notice Retrieve the value of the attribute of the type with ID * `attributeTypeID` on the account at `account`, assuming it is valid. * @param account address The account to check for the given attribute value. * @param attributeTypeID uint256 The ID of the attribute type to check for. * @return The attribute value if the attribute is valid, reverts otherwise. * @dev This function MUST revert if a directly preceding or subsequent * function call to `hasAttribute` with identical `account` and * `attributeTypeID` parameters would return false. */ function getAttributeValue( address account, uint256 attributeTypeID ) external view returns (uint256); /** * @notice Count the number of attribute types defined by the registry. * @return The number of available attribute types. * @dev This function MUST return a positive integer value - i.e. calling * this function MUST NOT cause the caller to revert. */ function countAttributeTypes() external view returns (uint256); /** * @notice Get the ID of the attribute type at index `index`. * @param index uint256 The index of the attribute type in question. * @return The ID of the attribute type. * @dev This function MUST revert if the provided `index` value falls outside * of the range of the value returned from a directly preceding or subsequent * function call to `countAttributeTypes`. It MUST NOT revert if the provided * `index` value falls inside said range. */ function getAttributeTypeID(uint256 index) external view returns (uint256); } /** * @title A simple example of an Attribute Registry implementation. */ contract AttributeRegistry is AttributeRegistryInterface { // This particular implementation just defines two attribute types. enum Affiliation { Whitehat, Blackhat } // Top-level information about attribute types held in a static array. uint256[2] private _attributeTypeIDs; // The number of attributes currently issued tracked in a static array. uint256[2] private _issuedAttributeCounters; // Issued attributes held in a nested mapping by account & attribute type. mapping(address => mapping(uint256 => bool)) private _issuedAttributes; // Issued attribute values held in a nested mapping by account & type. mapping(address => mapping(uint256 => uint256)) private _issuedAttributeValues; /** * @notice The constructor function, defines the two attribute types available * on this particular registry. */ constructor() public { // Set the attribute type IDs for whitehats (8008) and blackhats (1337). _attributeTypeIDs = [8008, 1337]; } /** * @notice Assign a "whitehat" attribute type to `msg.sender`. * @dev The function may not be called by accounts with a "blackhat" attribute * type already assigned. This function is arbitrary and not part of the * Attribute Registry specification. */ function joinWhitehats() external { // Get the index of the blackhat attribute type on the attribute registry. uint256 blackhatIndex = uint256(Affiliation.Blackhat); // Get the attribute type ID of the blackhat attribute type. uint256 blackhatAttributeTypeID = _attributeTypeIDs[blackhatIndex]; // Do not allow the whitehat attribute to be set if blackhat is already set. require( !_issuedAttributes[msg.sender][blackhatAttributeTypeID], "no blackhats allowed!" ); // Get the index of the whitehat attribute type on the attribute registry. uint256 whitehatIndex = uint256(Affiliation.Whitehat); // Get the attribute type ID of the whitehat attribute type. uint256 whitehatAttributeTypeID = _attributeTypeIDs[whitehatIndex]; // Mark the attribute as issued on the given address. _issuedAttributes[msg.sender][whitehatAttributeTypeID] = true; // Calculate the new number of total whitehat attributes. uint256 incrementCounter = _issuedAttributeCounters[whitehatIndex] + 1; // Set the attribute value to the new total assigned whitehat attributes. _issuedAttributeValues[msg.sender][whitehatAttributeTypeID] = incrementCounter; // Update the value of the counter for total whitehat attributes. _issuedAttributeCounters[whitehatIndex] = incrementCounter; } /** * @notice Assign a "blackhat" attribute type to `msg.sender`. * @dev The function may be called by any account, but assigned "whitehat" * attributes will be removed. This function is arbitrary and not part of the * Attribute Registry specification. */ function joinBlackhats() external { // Get the index of the blackhat attribute type on the attribute registry. uint256 blackhatIndex = uint256(Affiliation.Blackhat); // Get the attribute type ID of the blackhat attribute type. uint256 blackhatAttributeTypeID = _attributeTypeIDs[blackhatIndex]; // Mark the attribute as issued on the given address. _issuedAttributes[msg.sender][blackhatAttributeTypeID] = true; // Calculate the new number of total blackhat attributes. uint256 incrementCounter = _issuedAttributeCounters[blackhatIndex] + 1; // Set the attribute value to the new total assigned blackhat attributes. _issuedAttributeValues[msg.sender][blackhatAttributeTypeID] = incrementCounter; // Update the value of the counter for total blackhat attributes. _issuedAttributeCounters[blackhatIndex] = incrementCounter; // Get the index of the whitehat attribute type on the attribute registry. uint256 whitehatIndex = uint256(Affiliation.Whitehat); // Get the attribute type ID of the whitehat attribute type. uint256 whitehatAttributeTypeID = _attributeTypeIDs[whitehatIndex]; // Determine if a whitehat attribute type has been assigned. if (_issuedAttributes[msg.sender][whitehatAttributeTypeID]) { // If so, delete the attribute. delete _issuedAttributes[msg.sender][whitehatAttributeTypeID]; // Delete the attribute value as well. delete _issuedAttributeValues[msg.sender][whitehatAttributeTypeID]; // Set the attribute value to the new total assigned whitehat attributes. uint256 decrementCounter = _issuedAttributeCounters[whitehatIndex] - 1; // Update the value of the counter for total whitehat attributes. _issuedAttributeCounters[whitehatIndex] = decrementCounter; } } /** * @notice Get the total number of assigned whitehat and blackhat attributes. * @return Array with counts of assigned whitehat and blackhat attributes. * @dev This function is arbitrary and not part of the Attribute Registry * specification. */ function totalHats() external view returns (uint256[2]) { // Return the array containing counter values. return _issuedAttributeCounters; } /** * @notice Check if an attribute of the type with ID `attributeTypeID` has * been assigned to the account at `account` and is currently valid. * @param account address The account to check for a valid attribute. * @param attributeTypeID uint256 The ID of the attribute type to check for. * @return True if the attribute is assigned and valid, false otherwise. * @dev This function MUST return either true or false - i.e. calling this * function MUST NOT cause the caller to revert. */ function hasAttribute( address account, uint256 attributeTypeID ) external view returns (bool) { // Return assignment status of attribute by account and attribute type ID return _issuedAttributes[account][attributeTypeID]; } /** * @notice Retrieve the value of the attribute of the type with ID * `attributeTypeID` on the account at `account`, assuming it is valid. * @param account address The account to check for the given attribute value. * @param attributeTypeID uint256 The ID of the attribute type to check for. * @return The attribute value if the attribute is valid, reverts otherwise. * @dev This function MUST revert if a directly preceding or subsequent * function call to `hasAttribute` with identical `account` and * `attributeTypeID` parameters would return false. */ function getAttributeValue( address account, uint256 attributeTypeID ) external view returns (uint256 value) { // Revert if attribute with given account & attribute type ID is unassigned require( _issuedAttributes[account][attributeTypeID], "could not find a value with the provided account and attribute type ID" ); // Return the attribute value. return _issuedAttributeValues[account][attributeTypeID]; } /** * @notice Count the number of attribute types defined by the registry. * @return The number of available attribute types. * @dev This function MUST return a positive integer value - i.e. calling * this function MUST NOT cause the caller to revert. */ function countAttributeTypes() external view returns (uint256) { // Return the length of the attribute type IDs array. return _attributeTypeIDs.length; } /** * @notice Get the ID of the attribute type at index `index`. * @param index uint256 The index of the attribute type in question. * @return The ID of the attribute type. * @dev This function MUST revert if the provided `index` value falls outside * of the range of the value returned from a directly preceding or subsequent * function call to `countAttributeTypes`. It MUST NOT revert if the provided * `index` value falls inside said range. */ function getAttributeTypeID(uint256 index) external view returns (uint256) { // Revert if the provided index is out of range. require( index < _attributeTypeIDs.length, "provided index is outside of the range of defined attribute type IDs" ); // Return the attribute type ID at the given index in the array. return _attributeTypeIDs[index]; } } ``` ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Money Streaming

Sat, 24 Nov 2018 00:00:00 +0000

## Simple Summary Money streaming represents the idea of continuous payments over a finite period of time. Block numbers are used as a proxy of time to continuously update balances. ## Abstract The following describes a standard whereby time is measured using block numbers and streams are mappings in a master contract. 1. A provider sets up a money streaming contract. 2. A prospective payer can interact with the contract and start the stream right away by depositing the funds required for the chosen period. 3. The payee is able to withdraw money from the contract based on its ongoing solvency. That is: `payment rate * (current block height - starting block height)` 4. The stream terms (payment rate, length, metadata) can be updated at any time if both parties pledge their signatures. 5. The stream can be stopped at any point in time by any party without on-chain consensus. 6. If the stream period ended and it was not previously stopped by any party, the payee is entitled to withdraw all the deposited funds. ## Motivation This standardised interface aims to change the way we think about long-term financial commitments. Thanks to blockchains, payments need not be sent in chunks (e.g. monthly salaries), as there is much less overhead in paying-as-you-go. Money as a function of time would better align incentives in a host of scenarios. ### Use Cases This is just a preliminary list of use cases. There are other spooky ideas interesting to explore, such as time-dependent disincetivisation, but, for brevity, we have not included them here. - Salaries - Subscriptions - Consultancies - CDPs - Rent - Parking ### Crowdsales [RICOs](https://github.com/lukso-network/rico), or Reversible ICOs, were introduced at Devcon4 by @frozeman. The idea is to endow investors with more power and safety guarantees by allowing them to "reverse" the investment based on the evolution of the project. We previously discussed a similar concept called SICOs, or Streamable ICOs, in this research [thread](https://ethresear.ch/t/chronos-a-quirky-application-proposal-for-plasma/2928/14?u=paulrberg). Instead of investing a lump sum and giving the money away to the project developers, funds are held in a smart contract which allocates money based on the passage of time. Project developers can withdraw funds as the stream stays active, while investors have the power to get back a significant percentage of their initial commitment if the project halts. ## Specification ### Structs The structure of a `stream` should be as follows: - `stream` - `sender`: the `address` of the entity funding the stream - `recipient`: the `address` where the money is being delivered to - `tokenAddress`: the `address` of the ERC20 token used as payment asset - `balance`: the total funds left in the stream - `timeframe`: as defined below - `rate`: as defined below ```solidity struct Stream { address sender; address recipient; address tokenAddress; uint256 balance; Timeframe timeframe; Rate rate; } ``` - `timeframe` - `start`: the starting block number of the stream - `stop`: the stopping block number of the stream ```solidity struct Timeframe { uint256 start; uint256 stop; } ``` - `rate` - `payment`: how much money moves from `sender` to `recipient` - `interval`: how often `payment` moves from `sender` to `recipient` ```solidity struct Rate { uint256 payment; uint256 interval; } ``` --- ### Methods #### balanceOf Returns available funds for the given stream id and address. ```solidity function balanceOf(uint256 _streamId, address _addr) ``` #### getStream Returns the full stream data, if the id points to a valid stream. ```solidity function getStream(uint256 _streamId) returns (address sender, address recipient, address tokenAddress, uint256 balance, uint256 startBlock, uint256 stopBlock, uint256 payment, uint256 interval) ``` #### create Creates a new stream between `msg.sender` and `_recipient`. MUST allow senders to create multiple streams in parallel. SHOULD not accept Ether and only use ERC20-compatible tokens. **Triggers Event**: [LogCreate](#logcreate) ```solidity function create(address _recipient, address _tokenAddress, uint256 _startBlock, uint256 _stopBlock, uint256 _payment, uint256 _interval) ``` #### withdraw Withdraws all or a fraction of the available funds. MUST allow only the recipient to perform this action. **Triggers Event**: [LogWithdraw](#logwithdraw) ```solidity function withdraw(uint256 _streamId, uint256 _funds) ``` #### redeem Redeems the stream by distributing the funds to the sender and the recipient. SHOULD allow any party to redeem the stream. **Triggers Event**: [LogRedeem](#logredeem) ```solidity function redeem(uint256 _streamId) ``` #### confirmUpdate Signals one party's willingness to update the stream SHOULD allow any party to do this but MUST NOT be executed without consent from all involved parties. **Triggers Event**: [LogConfirmUpdate](#logconfirmupdate) **Triggers Event**: [LogExecuteUpdate](#logexecuteupdate) when the last involved party calls this function ```solidity function update(uint256 _streamId, address _tokenAddress, uint256 _stopBlock, uint256 _payment, uint256 _interval) ``` #### revokeUpdate Revokes an update proposed by one of the involved parties. MUST allow any party to do this. **Triggers Event**: [LogRevokeUpdate](#logrevokeupdate) ```solidity function confirmUpdate(uint256 _streamId, address _tokenAddress, uint256 _stopBlock, uint256 _payment, uint256 _interval) ``` --- ### Events #### LogCreate MUST be triggered when `create` is successfully called. ```solidity event LogCreate(uint256 indexed _streamId, address indexed _sender, address indexed _recipient, address _tokenAddress, uint256 _startBlock, uint256 _stopBlock, uint256 _payment, uint256 _interval) ``` #### LogWithdraw MUST be triggered when `withdraw` is successfully called. ```solidity event LogWithdraw(uint256 indexed _streamId, address indexed _recipient, uint256 _funds) ``` #### LogRedeem MUST be triggered when `redeem` is successfully called. ```solidity event LogRedeem(uint256 indexed _streamId, address indexed _sender, address indexed _recipient, uint256 _senderBalance, uint256 _recipientBalance) ``` #### LogConfirmUpdate MUST be triggered when `confirmUpdate` is successfully called. ```solidity event LogConfirmUpdate(uint256 indexed _streamId, address indexed _confirmer, address _newTokenAddress, uint256 _newStopBlock, uint256 _newPayment, uint256 _newInterval); ``` #### LogRevokeUpdate MUST be triggered when `revokeUpdate` is successfully called. ```solidity event LogRevokeUpdate(uint256 indexed _streamId, address indexed revoker, address _newTokenAddress, uint256 _newStopBlock, uint256 _newPayment, uint256 _newInterval) ``` #### LogExecuteUpdate MUST be triggered when an update is approved by all involved parties. ```solidity event LogExecuteUpdate(uint256 indexed _newStreamId, address indexed _sender, address indexed _recipient, address _newTokenAddress, uint256 _newStopBlock, uint256 _newPayment, uint256 _newInterval) ``` ## Rationale This specification was designed to serve as an entry point to the quirky concept of money as a function of time and it is definitely not set in stone. Several other designs, including payment channels and Plasma chains were also considered, but they were eventually deemed dense in assumptions unnecessary for an initial version. Block times are a reasonable, trustless proxy for time on the blockchain. Between 2016 and 2018, the Ethereum block time average value [hovered](https://etherscan.io/chart/blocktime) around 14 seconds, excluding the last two quarters of 2017. Mathematically speaking, it would be ideal to have a standard deviation as close to 0 as possible, but that is not how things work in the real world. This has huge implications on the feasibility of this ERC which we shall investigate below. ### GCD When setting up a stream, a payer and a payee may want to make the total streaming duration a multiple of the "greatest common denominator" (GCD) of the chain they operate on; that is, the average block time. This is not imperative in the smart contracts per se, but there needs to be an off-chain process to map streams to real world time units in order to create a sound and fair payment mechanism. ### Block Times Because there is uncertainty regarding block times, streams may not be settled on the blockchain as initially planned. Let `$d` be the total streaming duration measured in seconds, `$t` the average block time before the stream started and `$t'` the actual average block time over `$d` after the stream started. We distinguish two undesirable scenarios: 1. `$t` < `$t'`: the payee will get their funds *later* than expected 2. `$t` > `$t'`: the payee will get their funds *sooner* than expected If the combined error delta is smaller than the payment rate (fifth parameter of the `create` method, measured in wei), there is no problem at all. Conversely, we stumble upon trust issues because real-world time frames do not correspond to the stream terms. For instance, if an employee is normally entitled to withdraw all the funds from the stream at the end of the month, but block times cause case 1 from above to occur, the employee is in a financial disadvantage because their continuous effort is not compensated as promised. Limiting the problem scope only to Ethereum, we propose two remedies: 1. Consensus on calling the `update` function to correct the stream terms. This might sound preposterous, but in most cases the stakes are low and stream participants are involved in long-term financial commitments. There is a high disincentive to refuse to cooperate. 2. Autonomously fix significant error deltas. In theory, we could achieve this using previous blocks' timestamps, "checkpointing" the stream once in a predefined number of blocks. This is still an area of active research because of potentially high overheads in gas costs. Nonetheless, it is important to note that this is still a major improvement on the traditional model where absolute trust is required. ### Sidechains It could be more efficient to implement this standard on independent sidechains like [POA Network](https://poa.network) or [xDai](https://medium.com/poa-network/poa-network-partners-with-makerdao-on-xdai-chain-the-first-ever-usd-stable-blockchain-65a078c41e6a) - thanks to their rather predictable nature. Admittedly, security is traded for scalability, but proper cryptoeconomic stakes could alleviate potential problems. Furthermore, it is intriguing to explore the prospect of stream-specific sidechains. ### Oracles The proposed specification uses block numbers to proxy time, but this need not be the only method. Albeit it would imply different trust assumptions, oracles could be used to provide a feed of timestamps. Coupled with the aforementioned idea of stream-specific sidechains, oracles could efficiently solve the problems outlined in [Block Times](#block-times). ### Multi-Hop Streams Future or upgraded versions of this standard may describe "multi-hop" streams. If: 1. There is a stream between A and B 2. There is another stream between B and C There could be a way to avoid running two different streams in parallel. That is, a fraction or all of the funds being streamed from A to B could be automatically wired to C. An interesting use case for this is taxes. Instead of manually moving money around, proactively calculating how much you owe and then transfer it, a stream could atomically perform those operations for you. ## Implementation - [ChronosProtocol WIP implementation](https://github.com/ChronosProtocol/monorepo) ## Additional References - [Chronos Protocol Ethresear.ch Plasma Proposal](https://ethresear.ch/t/chronos-a-quirky-application-proposal-for-plasma/2928?u=paulrberg) - [Chronos Protocol White Paper](http://chronosprotocol.org/chronos-white-paper.pdf) - [Flipper: Streaming Salaries @ CryptoLife Hackathon](https://devpost.com/software/flipper-3gvl4b) - [SICOs or Streamed ICOs](https://ethresear.ch/t/chronos-a-quirky-application-proposal-for-plasma/2928/14?u=paulrberg) - [RICOs or Reversible ICOs](https://twitter.com/feindura/status/1058057076306518017) - [Andreas Antonopoulos' Keynote on Bitcoin, Lightning and Money Streaming](https://www.youtube.com/watch?v=gF_ZQ_eijPs) ## Final Notes Many thanks to @mmilton41 for countless brainstorming sessions. We have been doing research on the topic of money streaming for quite a while within the context of @ChronosProtocol. In August this year, we published the first version of our white paper describing a Plasma approach. However, in the meantime, we realised that it would be much more [fun](https://twitter.com/PaulRBerg/status/1056595919116910592) and easier to start small on Ethereum itself and sidechains like [xDai](https://blockscout.com/poa/dai). ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Re-Fungible Token Standard (RFT)

Sun, 18 Nov 2018 00:00:00 +0000

## Simple Summary [ERC-20](./eip-20.md) extension for proportional ownership of an [ERC-721](./eip-721.md) token. ## Abstract The intention of this proposal, the Re-Fungible Token Standard, is to extend the ERC-20 Token Standard and utilize ERC-165 Standard Interface Detection in order to represent the shared ownership of an ERC-721 Non-Fungible Token. The ERC-20 Token Standard was modified as little as possible in order to allow this new class of token to operate in all of the ways and locations which are familiar to assets that follow the original ERC-20 specification. While there are many possible variations of this specification that would enable many different capabilities and scenarios for shared ownership, this proposal is focused on the minimal commonalities to enable as much flexibility as possible for various further extensions. This proposal makes it possible to verify, from the contract level or from an external query, whether a fungible token represents a form of shared ownership of a non-fungible token. The inclusion of ERC-165 makes it possible to verify, from the contract level or from an external query, whether a non-fungible token is owned by ERC-20 token representing shared ownership. ## Motivation Shared ownership occurs across many industries and for many reasons. As more assets are registered, regulated and/or represented by the ERC-721 Non-Fungible Token Standard there will be more instances where the need for shared ownership of these assets will arise. For example, ARTBLX Inc. is working towards facilitating a protocol for collective ownership of physical, digital and conceptual artworks. The fungible tokens created from this process will have a value attached to the non-fungible tokens which they represent. This will be useful for price discovery of the underlying asset, liquidity for shared owners and as a new class of asset which can be used as collateral for loans or other financial instruments like stable coins. Providing an interface to this special class of fungible tokens is necessary to allow third parties to recognize them as a special class of fungible token and to recognize when a non-fungible token is collectively owned. This might be useful in the case of a wallet who would want to utilize the metadata of the underlying NFT to show additional info next to an RFT, or on an exchange who might want to make that sort of info similarly available, or an NFT marketplace who may want to direct customers to a relevant exchange who wish to purchase shares in a NFT which is owned by an RFT. Anywhere an ERC-20 is applicable it would be useful for a user to know whether that token represents a shared NFT, and what attributes that NFT may have. ## Specification At a minimum, third parties need two things: 1) to be able to distinguish re-fungible tokens from other token standards and 2) to determine when a non-fungible token is collectively owned. These two scenarios can be encountered from the perspective of initial contact with the non-fungible token or from the perspective of initial contact with the re-fungible token. #### Initial Contact with the Re-Fungible Token In order for a third party to confirm which non-fungible token is owned by the re-fungible token there needs to be a pointer from the RFT contract to the NFT contract and the relevant token id. This is possible with two public getters named `parentToken()` and `parentTokenId()`. The first getter returns a variable of type `address` and designates the contract address of the Non-Fungible Token contract. The second getter returns a variable of type `uint256` and designates the token ID of the Non-Fungible Token. With these getters, the identity of the Non-Fungible Token can be determined. Below is an example of the Re-Fungible Token Standard interface that includes these getter functions: ```solidity pragma solidity ^0.4.20; /// @dev Note: the ERC-165 identifier for this interface is 0x5755c3f2. interface RFT /* is ERC20, ERC165 */ { function parentToken() external view returns(address _parentToken); function parentTokenId() external view returns(uint256 _parentTokenId); } ``` The validity of this claim can be confirmed from another contract (on-chain) or from interacting with an RPC endpoint (off-chain). Below is an example of the on-chain scenario: ```solidity pragma solidity ^0.4.20; import './RFT.sol'; import './ERC721.sol'; contract ConfirmRFT { function confirmRFT(address _RFT) external view returns(bool) { address _NFT = RFT(_RFT).parentToken(); // returns address of NFT contract uint256 _tokenId = RFT(_RFT).parentTokenId(); // returns id of ID of NFT return NFT(_NFT).supportsInterface(0x80ac58cd) && // confirm it is ERC-721 NFT(_NFT).ownerOf(_tokenId) == _RFT; // confirm the owner of the NFT is the RFT contract address } } ``` Below is an off-chain example using an instance of web3.js in javascript: ```javascript async function confirmRFT(web3) { const ERC721ABI = [...] // abi for ERC721 const RFTABI = [...] // abi for RFT const RFTAddress = '0x0123456789abcdef0123456789abcdef' // address for the deployed RFT const RFTContract = new web3.eth.Contract(RFTABI, RFTAddress) // deployed RFT contract instance const ERC721Address = await RFTcontract.methods.parentToken().call() // returns address of NFT contract const ERC721TokenId = await RFTcontract.methods.parentTokenId().call() // returns id of ID of NFT const ERC721Contract = new web3.eth.Contract(ERC721ABI, ERC721Address) // deployed ERC721 (as reported by RFT) const isERC721 = await ERC721Contract.methods.supportsInterface('0x80ac58cd').call() // confirm it is ERC-721 const ownerOfAddress = await ERC721Contract.methods.ownerOf(ERC721TokenId).call() // get the owner of the NFT return ERC721Response.toLowerCase() === RFTAddress.toLowerCase() // confirm the owner of the NFT is the RFT contract } ``` #### Initial Contact with the Non-Fungible Token When checking the owner of a specific non-fungible token it's important to be able to determine whether owner is in fact a re-fungible token contract. This is possible by utilizing ERC-165 Standard Interface Detection. In order to comply with that standard a contract must include the following getter function which returns `true` when passed the `bytes4` parameter `0x01ffc9a7`: ``` function supportsInterface(bytes4 interfaceID) external view returns (bool); ``` After establishing support for this interface it becomes useful in determining whether the contract adheres to the Re-Fungible Token Standard. To do so the `supportsInterface(bytes4 interfaceID)` getter function must return `true` when passed the `bytes4` parameter `0x5755c3f2` which is the result of `bytes4(keccak256('parentToken()')) ^ bytes4(keccak256('parentTokenId()'))` or `parentToken.selector ^ parentTokenId.selector`. This could be achieved with the following code: ```solidity pragma solidity ^0.4.20; import "./ERC20.sol"; /// @dev Note: the ERC-165 identifier for this interface is 0x5755c3f2. interface RFT is ERC20 /*, ERC165 */ { function supportsInterface(bytes4 interfaceID) external view returns(bool) { return interfaceID == this.supportsInterface.selector || // ERC165 interfaceID == this.parentToken.selector || // parentToken() interfaceID == this.parentTokenId.selector || // parentTokenId() interfaceID == this.parentToken.selector ^ this.parentTokenId.selector; // RFT } function parentToken() external view returns(address _parentToken); function parentTokenId() external view returns(uint256 _parentTokenId); } ``` The flow of actually checking the status of a non-fungible token owner as a re-fungible token contract can be done from another contract (on-chain) as well as with an RPC endpoint (off-chain). Below is an example of the on-chain scenario: ```solidity pragma solidity ^0.4.20; import './RFT.sol'; import './ERC721.sol'; contract ConfirmRFT { function confirmRFT(address _NFT, uint256 _tokenId) external view returns(bool) { address _RFT = ERC721(_NFT).ownerOf(_tokenId); // get the owner of the NFT return RFT(_RFT).supportsInterface(0x01ffc9a7) && // confirm it supports ERC-165 RFT(_RFT).supportsInterface(0x5755c3f2) // confirm it is RFT } } ``` Below is an off-chain example using web3.js in javascript: ```javascript async function confirmRFT(web3) { const ERC721ABI = [...] // abi for ERC721 const RFTABI = [...] // abi for RFT const ERC721Address = '0x0123456789abcdef0123456789abcdef' // address for the deployed NFT const ERC721TokenId = '7' // token Id of the NFT const ERC721Contract = new web3.eth.Contract(ERC721ABI, ERC721Address) // deployed ERC721 const RFTAddress = await ERC721Contract.methods.ownerOf(ERC721TokenId).call() // owner address of the NFT const RFTContract = new web3.eth.Contract(RFTABI, RFTAddress) // deployed RFT contract instance const isERC165 = await RFTContract.methods.supportsInterface('0x01ffc9a7').call() // confirm it is ERC-165 return isERC165 && await RFTContract.methods.supportsInterface('0x5755c3f2').call() // confirm it is RFT } ``` ## Rationale Most of the decisions made around the design of this standard were done in the hopes of keeping it as flexible as possible for as many use cases as possible. This includes making the standard 100% backwards compatible with ERC-20 Token Standard and able to interact with any previously deployed or future ERC-721 non-fungible token. This allows for each project to determine their own system for minting, burning and governing their re-fungible tokens depending on their specific use case. ## Backwards Compatibility The Re-Fungible Token Standard is 100% backwards compatible with ERC-20 Token Standard. It is a small extension to the original specification and meant to be further extended for more specific use cases. Keeping the standard compatible with ERC-20 is important to allow for this token to benefit from the ecosystem that has grown around supporting the ubiquitous ERC-20 Token Standard. The Re-Fungible Token Standard is intended to interact with the ERC-721 Non-Fungible Token Standard. It is kept purposefully agnostic to extensions beyond the standard in order to allow specific projects to design their own token relationships such as governance over, rights to or permissions on each non-fungible token relative to the respective re-fungible token owners. ## Implementation ```solidity pragma solidity ^0.4.20; /// @dev Note: the ERC-165 identifier for this interface is 0x5755c3f2. interface RFT /* is ERC20, ERC165 */ { function parentToken() external view returns(address _parentToken); function parentTokenId() external view returns(uint256 _parentTokenId); } ``` ## Security Considerations TBD ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

URL Format for Web3 Browsers

Sun, 13 Jan 2019 00:00:00 +0000

## Simple Summary A standard way of representing web3 browser URLs for decentralized applications. ## Abstract Since most normal web browsers (specifically on mobile devices) can not run decentralized applications correctly because of the lack of web3 support, it is necessary to differentiate them from normal urls, so they can be opened in web3 browsers if available. ## Motivation Lots of dApps that are trying to improve their mobile experience are currently (deep)linking to specific mobile web3 browsers which are currently using their own url scheme. In order to make the experience more seamless, dApps should still be able to recommend a specific mobile web3 browser via [deferred deeplinking](https://en.wikipedia.org/wiki/Deferred_deep_linking) but by having a standard url format, if the user already has a web3 browser installed that implements this standard, it will be automatically linked to it. There is also a compatibility problem with the current `ethereum:` url scheme described in [EIP-831](./eip-831.md) where any ethereum related app (wallets, identity management, etc) already registered it and because of iOS unpredictable behavior for multiple apps handling a single url scheme, users can end up opening an `ethereum:` link in an app that doesn not include a web3 browser and will not be able to handle the deeplink correctly. ## Specification ### Syntax Web3 browser URLs contain "dapp" in their schema (protocol) part and are constructed as follows: request = "dapp" ":" [chain_id "@"] dapp_url chain_id = 1*DIGIT dapp_url = URI ### Semantics `chain_id` is optional and it is a parameter for the browser to automatically select the corresponding chain ID as specified in [EIP-155](./eip-155.md) before opening the dApp. `dapp_url` is a valid [RFC3986](https://www.ietf.org/rfc/rfc3986.txt) URI This a complete example url: `dapp:1@peepeth.com/brunobar79?utm_source=github` which will open the web3 browser, select `mainnet` (chain_id = 1) and then navigate to: `https://peepeth.com/brunobar79?utm_source=github` ## Rationale The proposed format attempts to solve the problem of vendor specific protocols for web3 browsers, avoiding conflicts with the existing 'ethereum:' URL scheme while also adding an extra feature: `chain_id` which will help dApps to be accessed with the right network preselected, optionally extracting away that complexity from end users. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Smart Contract Interface for Licences

Wed, 06 Feb 2019 00:00:00 +0000

## Abstract This Ethereum Improvement Proposal (EIP) proposes an Ethereum standard for the issuance of licences, permits and grants (Licences). A Licence is a limited and temporary authority, granted to a natural (e.g. you) or legal person (e.g. a corporation), to do something that would otherwise be unlawful pursuant to a legal framework. A public Licence is granted by the government, directly (e.g. by the New South Wales Department of Primary Industries, Australia) or indirectly (e.g. by an agent operating under the government’s authority), and derives its authority from legislation, though this is often practically achieved via delegated legislation such as regulations. This can be contrasted to a private licence – for example, the licence you grant to a visitor who comes onto your property. A Licence has the following properties: * granted personally to the licencee (Licencee), though it may be transferrable to another person or company; * conferring a temporary right to the Licencee to own, use or do something that would otherwise be prohibited, without conferring any property interest in the underlying thing. For example, you may be granted a licence to visit a national park without acquiring any ownership in or over the park itself; * allowing the government authority responsible for the Licence to amend, revoke, renew, suspend or deny the issuance of the Licence, or to impose conditions or penalties for non-compliance; and * usually issued only after the payment of a fee or the meeting of some criteria. Additionally, a Licence may be granted in respect of certain information. For example, a Licence may be issued in respect of a vehicle registration number and attaching to that specific registered vehicle. ## Motivation Governments are responsible for the issuance and management of Licences. However, maintaining and sharing this data can be complicated and inefficient. The granting of Licences usually requires the filing of paper-based application forms, manual oversight of applicable legislation and data entry into registries, as well as the issuance of paper based Licences. If individuals wish to sight information on Licence registries, they often need to be present at the government office and complete further paper-based enquiry forms in order to access that data (if available publicly). This EIP seeks to define a standard that will allow for the granting and/or management of Licences via Ethereum smart contracts. The motivation is, in essence, to address the inefficiencies inherent in current licencing systems. ## Specification ### Methods **NOTES**: - The following specifications use syntax from Solidity `0.4.17` (or above) - Callers MUST handle `false` from `returns (bool success)`. Callers MUST NOT assume that `false` is never returned! #### name Returns the name of the permit - e.g. `"MyPermit"`. ``` js function name() public view returns (string); ``` #### totalSupply Returns the total permit supply. ``` js function totalSupply() public view returns (uint256); ``` #### grantAuthority Adds an ethereum address to a white list of addresses that have authority to modify a permit. ``` js function grantAuthority(address who) public; ``` #### revokeAuthority Removes an ethereum address from a white list of addresses that have authority to modify a permit. ``` js function revokeAuthority(address who) public; ``` #### hasAuthority Checks to see if the address has authority to grant or revoke permits. ``` js function hasAuthority(address who) public view; ``` #### issue Issues an ethereum address a permit between the specified date range. ``` js function issue(address who, uint256 validFrom, uint256 validTo) public; ``` #### revoke Revokes a permit from an ethereum address. ``` js function revoke(address who) public; ``` #### hasValid Checks to see if an ethereum address has a valid permit. ``` js function hasValid(address who) external view returns (bool); ``` #### purchase Allows a user to self procure a licence. ``` js function purchase(uint256 validFrom, uint256 validTo) external payable; ``` ## Rationale The use of smart contracts to apply for, renew, suspend and revoke Licences will free up much needed government resources and allow for the more efficient management of Licences. The EIP also seeks to improve the end user experience of the Licence system. In an era of open government, there is also an increased expectation that individuals will be able to easily access Licence registries, and that the process will be transparent and fair. By creating an EIP, we hope to increase the use of Ethereum based and issued Licences, which will address these issues. The Ethereum blockchain is adaptable to various Licences and government authorities. It will also be easily translatable into other languages and can be used by other governmental authorities across the world. Moreover, a blockchain will more effectively protect the privacy of Licence-holders’ data, particularly at a time of an ever-increasing volume of government data breaches. The EIP has been developed following the review of a number of licensing regulations at the national and state level in Australia. The review allowed the identification of the common licence requirements and criteria for incorporation into the EIP. We have included these in the proposed standard but seek feedback on whether these criteria are sufficient and universal. ## Test Cases A real world example of a Licence is a permit required to camp in a national park in Australia (e.g. Kakadu national park in the Northern Territory of Australia) under the Environment Protection and Biodiversity Conservation Regulations 2000 (Cth) (EPBC Act) and the Environment Protection and Biodiversity Conservation Regulations 2000 (the Regulations). Pursuant to the EPBC Act and the Regulations, the Director of National Parks oversees a camping permit system, which is intended to help regulate certain activities in National Parks. Permits allowing access to National Parks can be issued to legal or natural persons if the applicant has met certain conditions. The current digital portal and application form to camp at Kakadu National Park (the Application) can be accessed at: https://www.environment.gov.au/system/files/resources/b3481ed3-164b-4e72-a9f8-91fc987d90e7/files/kakadu-camping-permit-form-19jan2015-pdf.pdf The user must provide the following details when making an Application: * The full name and contact details of each person to whom the permit is to be issued; * If the applicant is a company or other incorporated body: o the name, business address and postal address of the company or incorporated body; o if the applicant is a company— * the full name of each of the directors of the company; * the full name and contact details of the person completing the application form; * the ACN or ABN of the company or other incorporated body (if applicable); * Details of the proposed camping purpose (e.g. private camping, school group, etc.); * A start date and duration for the camping (up to the maximum duration allowed by law); * Number of campers (up to the maximum allowed by law); * All other required information not essential to the issuance of the Licence (e.g. any particular medical needs of the campers); and * Fees payable depending on the site, duration and number of campers. The Regulations also set out a number of conditions that must be met by licensees when the permit has been issued. The Regulations allow the Director of National Parks to cancel, renew or transfer the licence. The above workflow could be better performed by way of a smart contract. The key criteria required as part of this process form part of the proposed Ethereum standard. We have checked this approach by also considering the issuance of a Commercial Fishing Licence under Part 8 “Licensing and other commercial fisheries management” of the Fisheries Management (General) Regulation 2010 (NSW) (Fisheries Regulations) made pursuant to the Fisheries Management Act 1994 (NSW) (Fisheries Act). ## Implementation The issuance and ownership of a Licence can be digitally represented on the Ethereum blockchain. Smart contracts can be used to embed regulatory requirements with respect to the relevant Licence in the blockchain. The Licence would be available electronically in the form of a token. This might be practically represented by a QR code, for example, displaying the current Licence information. The digital representation of the Licence would be stored in a digital wallet, typically an application on a smartphone or tablet computer. The proposed standard allows issuing authorities or regulators to amend, revoke or deny Licences from time to time, with the result of their determinations reflected in the Licence token in near real-time. Licence holders will therefore be notified almost instantly of any amendments, revocations or issues involving their Licence. ## Interface ### Solidity Example ```solidity interface EIP1753 { function grantAuthority(address who) external; function revokeAuthority(address who) external; function hasAuthority(address who) external view returns (bool); function issue(address who, uint256 from, uint256 to) external; function revoke(address who) external; function hasValid(address who) external view returns (bool); function purchase(uint256 validFrom, uint256 validTo) external payable; } pragma solidity ^0.5.3; contract EIP is EIP1753 { string public name = "Kakadu National Park Camping Permit"; uint256 public totalSupply; address private _owner; mapping(address => bool) private _authorities; mapping(address => Permit) private _holders; struct Permit { address issuer; uint256 validFrom; uint256 validTo; } constructor() public { _owner = msg.sender; } function grantAuthority(address who) public onlyOwner() { _authorities[who] = true; } function revokeAuthority(address who) public onlyOwner() { delete _authorities[who]; } function hasAuthority(address who) public view returns (bool) { return _authorities[who] == true; } function issue(address who, uint256 start, uint256 end) public onlyAuthority() { _holders[who] = Permit(_owner, start, end); totalSupply += 1; } function revoke(address who) public onlyAuthority() { delete _holders[who]; } function hasValid(address who) external view returns (bool) { return _holders[who].validFrom > now && _holders[who].validTo < now; } function purchase(uint256 validFrom, uint256 validTo) external payable { require(msg.value == 1 ether, "Incorrect fee"); issue(msg.sender, validFrom, validTo); } modifier onlyOwner() { require(msg.sender == _owner, "Only owner can perform this function"); _; } modifier onlyAuthority() { require(hasAuthority(msg.sender), "Only an authority can perform this function"); _; } } ``` ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Scoped Approval Interface

Mon, 18 Feb 2019 00:00:00 +0000

## Simple Summary A standard interface to permit restricted approval in token contracts by defining "scopes" of one or more Token IDs. ## Abstract This interface is designed for use with token contracts that have an "ID" domain, such as ERC-1155 or ERC-721. This enables restricted approval of one or more Token IDs to a specific "scope". When considering a smart contract managing tokens from multiple different domains, it makes sense to limit approvals to those domains. Scoped approval is a generalization of this idea. Implementors can define scopes as needed. Sample use cases for scopes: * A company may represent its fleet of vehicles on the blockchain and it could create a scope for each regional office. * Game developers could share an [ERC-1155](./eip-1155.md) contract where each developer manages tokens under a specified scope. * Tokens of different value could be split into separate scopes. High-value tokens could be kept in smaller separate scopes while low-value tokens might be kept in a shared scope. Users would approve the entire low-value token scope to a third-party smart contract, exchange, or other application without concern about losing their high-value tokens in the event of a problem. ## Motivation It may be desired to restrict approval in some applications. Restricted approval can prevent losses in cases where users do not audit the contracts they're approving. No standard API is supplied to manage scopes as this is implementation specific. Some implementations may opt to offer a fixed number of scopes, or assign a specific set of scopes to certain types. Other implementations may open up scope configuration to its users and offer methods to create scopes and assign IDs to them. # Specification ```solidity pragma solidity ^0.5.2; /** Note: The ERC-165 identifier for this interface is 0x30168307. */ interface ScopedApproval { /** @dev MUST emit when approval changes for scope. */ event ApprovalForScope(address indexed _owner, address indexed _operator, bytes32 indexed _scope, bool _approved); /** @dev MUST emit when the token IDs are added to the scope. By default, IDs are in no scope. The range is inclusive: _idStart, _idEnd, and all IDs in between have been added to the scope. _idStart must be lower than or equal to _idEnd. */ event IdsAddedToScope(uint256 indexed _idStart, uint256 indexed _idEnd, bytes32 indexed _scope); /** @dev MUST emit when the token IDs are removed from the scope. The range is inclusive: _idStart, _idEnd, and all IDs in between have been removed from the scope. _idStart must be lower than or equal to _idEnd. */ event IdsRemovedFromScope(uint256 indexed _idStart, uint256 indexed _idEnd, bytes32 indexed _scope); /** @dev MUST emit when a scope URI is set or changes. URIs are defined in RFC 3986. The URI MUST point a JSON file that conforms to the "Scope Metadata JSON Schema". */ event ScopeURI(string _value, bytes32 indexed _scope); /** @notice Returns the number of scopes that contain _id. @param _id The token ID @return The number of scopes containing the ID */ function scopeCountForId(uint256 _id) public view returns (uint32); /** @notice Returns a scope that contains _id. @param _id The token ID @param _scopeIndex The scope index to query (valid values are 0 to scopeCountForId(_id)-1) @return The Nth scope containing the ID */ function scopeForId(uint256 _id, uint32 _scopeIndex) public view returns (bytes32); /** @notice Returns a URI that can be queried to get scope metadata. This URI should return a JSON document containing, at least the scope name and description. Although supplying a URI for every scope is recommended, returning an empty string "" is accepted for scopes without a URI. @param _scope The queried scope @return The URI describing this scope. */ function scopeUri(bytes32 _scope) public view returns (string memory); /** @notice Enable or disable approval for a third party ("operator") to manage the caller's tokens in the specified scope. @dev MUST emit the ApprovalForScope event on success. @param _operator Address to add to the set of authorized operators @param _scope Approval scope (can be identified by calling scopeForId) @param _approved True if the operator is approved, false to revoke approval */ function setApprovalForScope(address _operator, bytes32 _scope, bool _approved) external; /** @notice Queries the approval status of an operator for a given owner, within the specified scope. @param _owner The owner of the Tokens @param _operator Address of authorized operator @param _scope Scope to test for approval (can be identified by calling scopeForId) @return True if the operator is approved, false otherwise */ function isApprovedForScope(address _owner, address _operator, bytes32 _scope) public view returns (bool); } ``` ## Scope Metadata JSON Schema This schema allows for localization. `{id}` and `{locale}` should be replaced with the appropriate values by clients. ```json { "title": "Scope Metadata", "type": "object", "required": ["name"], "properties": { "name": { "type": "string", "description": "Identifies the scope in a human-readable way.", }, "description": { "type": "string", "description": "Describes the scope to allow users to make informed approval decisions.", }, "localization": { "type": "object", "required": ["uri", "default", "locales"], "properties": { "uri": { "type": "string", "description": "The URI pattern to fetch localized data from. This URI should contain the substring `{locale}` which will be replaced with the appropriate locale value before sending the request." }, "default": { "type": "string", "description": "The locale of the default data within the base JSON" }, "locales": { "type": "array", "description": "The list of locales for which data is available. These locales should conform to those defined in the Unicode Common Locale Data Repository (http://cldr.unicode.org/)." } } } } } ``` ### Localization Metadata localization should be standardized to increase presentation uniformity across all languages. As such, a simple overlay method is proposed to enable localization. If the metadata JSON file contains a `localization` attribute, its content may be used to provide localized values for fields that need it. The `localization` attribute should be a sub-object with three attributes: `uri`, `default` and `locales`. If the string `{locale}` exists in any URI, it MUST be replaced with the chosen locale by all client software. ## Rationale The initial design was proposed as an extension to ERC-1155: [Discussion Thread - Comment 1](https://github.com/ethereum/EIPs/issues/1155#issuecomment-459505728). After some discussion: [Comment 2](https://github.com/ethereum/EIPs/issues/1155#issuecomment-460603439) and suggestions by the community to implement this approval mechanism in an external contract [Comment 3](https://github.com/ethereum/EIPs/issues/1155#issuecomment-461758755), it was decided that as an interface standard, this design would allow many different token standards such as ERC-721 and ERC-1155 to implement scoped approvals without forcing the system into all implementations of the tokens. ### Metadata JSON The Scope Metadata JSON Schema was added in order to support human-readable scope names and descriptions in more than one language. ## References **Standards** - [ERC-1155 Multi Token Standard](./eip-1155.md) - [ERC-165 Standard Interface Detection](./eip-165.md) - [JSON Schema](https://json-schema.org/) **Implementations** - [Enjin Coin](https://enjincoin.io) ([github](https://github.com/enjin)) **Articles & Discussions** - [GitHub - Original Discussion Thread](https://github.com/ethereum/EIPs/issues/1761) - [GitHub - ERC-1155 Discussion Thread](https://github.com/ethereum/EIPs/issues/1155) ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

App Keys, application specific wallet accounts

Wed, 20 Feb 2019 00:00:00 +0000

## Simple Summary Among others cryptographic applications, scalability and privacy solutions for ethereum blockchain require that an user performs a significant amount of signing operations. It may also require her to watch some state and be ready to sign data automatically (e.g. sign a state or contest a withdraw). The way wallets currently implement accounts poses several obstacles to the development of a complete web3.0 experience both in terms of UX, security and privacy. This proposal describes a standard and api for a new type of wallet accounts that are derived specifically for a each given application. We propose to call them `app keys`. They allow to isolate the accounts used for each application, thus potentially increasing privacy. They also allow to give more control to the applications developers over account management and signing delegation. For these app keys, wallets can have a more permissive level of security (e.g. not requesting user's confirmation) while keeping main accounts secure. Finally wallets can also implement a different behavior such as allowing to sign transactions without broadcasting them. This new accounts type can allow to significantly improve UX and permit new designs for applications of the crypto permissionned web. ## Abstract In a wallet, an user often holds most of her funds in her main accounts. These accounts require a significant level of security and should not be delegated in any way, this significantly impacts the design of cryptographic applications if a user has to manually confirm every action. Also often an user uses the same accounts across apps, which is a privacy and potentially also a security issue. We introduce here a new account type, app keys, which permits signing delegation and accounts isolation across applications for privacy and security. In this EIP, we provide a proposal on how to uniquely identify and authenticate each application, how to derive a master account (or app key) unique for the domain from an user private key (her root private key or any other private key of an account derived or not from her root one). This EIP aims at becoming a standard on how to derive keys specific to each application that can be regenerated from scratch without further input from the user if she restores her wallet and uses again the application for which this key was derived. These app keys can then be endowed a different set of permissions (through the requestPermission model introduced in [EIP-2255](./eip-2255.md)). This will potentially allow an user to partly trust some apps to perform some crypto operations on their behalf without compromising any security with respect to her main accounts. ## Motivation Wallets developers have agreed on an HD derivation path for ethereum accounts using BIP32, BIP44, SLIP44, [(see the discussion here)](https://github.com/ethereum/EIPs/issues/84). Web3 wallets have implemented in a roughly similar way the rpc eth api. [EIP-1102](./eip-1102.md) introduced privacy through non automatic opt-in of a wallet account into an app increasing privacy. However several limitations remain in order to allow for proper design and UX for crypto permissioned apps. Most of GUI based current wallets don't allow to: * being able to automatically and effortlessly use different keys / accounts for each apps, * being able to sign some app's action without prompting the user with the same level of security as sending funds from their main accounts, * being able to use throwable keys to improve anonymity, * effortlessly signing transactions for an app without broadcasting these while still being able to perform other transaction signing as usual from their main accounts, * All this while being fully restorable using the user's mnemonic or hardware wallet and the HD Path determined uniquely by the app's ens name. We try to overcome these limitations by introducing a new account's type, app keys, made to be used along side the existing main accounts. These new app keys can permit to give more power and flexibility to the crypto apps developers. This can allow to improve a lot the UX of crypto dapps and to create new designs that were not possible before leveraging the ability to create and handle many accounts, to presign messages and broadcast them later. These features were not compatible with the level of security we were requesting for main accounts that hold most of an user's funds. ## Specification ### Applications An app is a website (or other) that would like to request from a wallet to access a cryptographic key specifically derived for this usage. It can be any form of cryptography/identity relying application, Ethereum based but not only. Once connected to a wallet, an application can request to access an account derived exclusively for that application using the following algorithm. ### Private App Key generation algorithm We now propose an algorithm to generate application keys that: - are uniquely defined, with respect to the account that the user selected to generate these keys, - and thus can be isolated when changing the user account, allowing persona management (see next section), - are specific to each application, - can be fully restored from the user master seed mnemonic and the applications' names. #### Using different accounts as personas We allow the user to span a different set of application keys by changing the account selected to generate each key. Thus from the same master seed mnemonic, an user can use each of her account index to generate an alternative set of application keys. One can describe this as using different personas. This would allow potentially an user to fully isolate her interaction with a given app across personas. One can use this for instance to create a personal and business profile for a given's domain both backup up from the same mnemonic, using 2 different accounts to generate these. The app or domain, will not be aware that it is the same person and mnemonic behind both. If an application interacts with several main accounts of an user, one of these accounts, a master account can be used as persona and the others as auxiliary accounts. This EIP is agnostic about the way one generates the private keys used to span different app keys spaces. However for compatibility purposes and for clean disambiguation between personas and cryptocurrency accounts, a new EIP, distinct from this one but to be used alongside, will be proposed soon introducing clean persona generation and management. #### Applications' Unique Identifiers Each application is uniquely defined and authenticated by its origin, a domain string. It can be a Domain Name Service (DNS) name or, in the future, an Ethereum Name Service (ENS) name or IPFS hash. For Ipfs or swam origins, but we could probably use the ipfs or swarm addresses as origin or we could require those to be pointed at through an ENS entry and use the ENS address as origin, although this would mean that the content it refers to could change. It would thus allow for different security and updatibility models. We will probably require for protocol prefixes when using an ENS domain to point to an IPFS address: `ens://ipfs.snap.eth` #### Private App Key generation algorithm Using the domain name of an application, we generate a private key for each application (and per main account) : `const appKeyPrivKey = keccak256(privKey + originString)` where `+` is concatenation, `privKey` is the private key of the user's account selected to span the application key and `originString` represents the origin url from which the permission call to access the application key is originated from. This is exposed as an RPC method to allow any domain to request its own app key associated with the current requested account (if available): ``` const appKey = await provider.send({ method: 'wallet_getAppKeyForAccount', params: [address1] }); ``` See here for an implementation: https://github.com/MetaMask/eth-simple-keyring/blob/master/index.js#L169 #### App keys and Hierarchical Deterministic keys The app keys generated using the algorithm described in the previous section will not be BIP32 compliant. Therefore apps will not be able to create several app keys or use non-hardening and extended public keys techniques directly. They get a single private key (per origin, per persona). Yet they can use this as initial entropy to span a new HD tree and generate addresses that can be either hardened or not. Thus we should not be losing use cases. ## Rationale ### Sharing application keys across domains: While this does not explicit cover cases of sharing these app keys between pages on its own, this need can be met by composition: Since a domain would get a unique key per persona, and because domains can intercommunicate, one domain (app) could request another domain (signer) to perform its cryptographic operation on some data, with its appKey as a seed, potentially allowing new signing strategies to be added as easily as new websites. This could also pass it to domains that are loading specific signing strategies. This may sound dangerous at first, but if a domain represents a static hash of a trusted cryptographic function implementation, it could be as safe as calling any audited internal dependency. ### Privacy and the funding trail If all an application needs to do with its keys is to sign messages and it does not require funding, then this EIP allows for privacy through the use of distinct keys for each application with a simple deterministic standard compatible across wallets. However if these application keys require funding, there can be trail and the use of app keys would not fully solve the privacy problem there. Mixers or anonymous ways of funding an ethereum address (ring signatures) along with this proposal would guarantee privacy. Even if privacy is not solved fully without this anonymous funding method, we still need a way to easily create and restore different accounts/addresses for each application ## Backwards Compatibility From a wallet point of view, there does not seem to be compatibility issues since these are separate accounts from those that were used previously by wallets and they are supposed to be used along-side in synergy. However, for applications that associated in some way their users to their main accounts may want to reflect on if and how they would like to leverage the power offered by `app keys` to migrate to them and leverage on the new app designs they permit. ## Implementation Here is an early implementation of app keys for standard (non HW) MetaMask accounts. https://github.com/MetaMask/eth-simple-keyring/blob/6d12bd9d73adcccbe0b0c7e32a99d279085e2934/index.js#L139-L152 See here for a fork of MetaMask that implements app keys along side plugins: https://github.com/MetaMask/metamask-snaps-beta https://github.com/MetaMask/metamask-snaps-beta/wiki/Plugin-API ## Example use cases * signing transactions without broadcasting them https://github.com/MetaMask/metamask-extension/issues/3475 * token contract https://github.com/ethereum/EIPs/issues/85 * default account for dapps https://ethereum-magicians.org/t/default-accounts-for-dapps/904 * non wallet/crypto accounts [EIP1581: Non-wallet usage of keys derived from BIP32 trees](./eip-1581.md) * state channel application * privacy solution * non custodian cross cryptocurrency exchange... ## Acknowledgements MetaMask team, Christian Lundkvist, Counterfactual team, Liam Horne, Erik Bryn, Richard Moore, Jeff Coleman. ## References ### HD and mnemonics #### BIPs * [BIP32: Hierarchical Deterministic Wallets:](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) * [BIP39: Mnemonic code for generating deterministic keys:](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) * [SLIP44: Registered coin types for BIP44](https://github.com/satoshilabs/slips/blob/master/slip-0044.md) #### Derivation path for eth * [Issue 84](https://github.com/ethereum/EIPs/issues/84) * [Issue 85](https://github.com/ethereum/EIPs/issues/85) * [EIP600 Ethereum purpose allocation for Deterministic Wallets](./eip-600.md) * [EIP601 Ethereum hierarchy for deterministic wallets](./eip-601.md) ### Previous proposals and discussions related to app keys * [Meta: we should value privacy more](https://ethereum-magicians.org/t/meta-we-should-value-privacy-more/2475) * [EIP1102: Opt-in account exposure](./eip-1102.md) * [EIP1581: Non-wallet usage of keys derived from BIP-32 trees](./eip-1581.md) * [EIP1581: discussion](https://ethereum-magicians.org/t/non-wallet-usage-of-keys-derived-from-bip-32-trees/1817/4) * [SLIP13: Authentication using deterministic hierarchy](https://github.com/satoshilabs/slips/blob/master/slip-0013.md) ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Ethereum Verifiable Claims

Sun, 03 Mar 2019 00:00:00 +0000

# Ethereum Verifiable Claims ## Simple Summary Reusable Verifiable Claims using [EIP 712 Signed Typed Data](./eip-712.md). ## Abstract A new method for Off-Chain Verifiable Claims built on [EIP-712](./eip-712.md). These Claims can be issued by any user with a EIP 712 compatible web3 provider. Claims can be stored off chain and verified on-chain by Solidity Smart Contracts, State Channel Implementations or off-chain libraries. ## Motivation Reusable Off-Chain Verifiable Claims provide an important piece of integrating smart contracts with real world organizational requirements such as meeting regulatory requirements such as KYC, GDPR, Accredited Investor rules etc. [ERC-735](https://github.com/ethereum/EIPs/issues/735) and [ERC-780](https://github.com/ethereum/EIPs/issues/780) provide methods of making claims that live on chain. This is useful for some particular use cases, where some claim about an address must be verified on chain. In most cases though it is both dangerous and in some cases illegal (according to EU GDPR rules for example) to record Identity Claims containing Personal Identifying Information (PII) on an immutable public database such as the Ethereum blockchain. The W3C [Verifiable Claims Data Model and Representations](https://www.w3.org/TR/verifiable-claims-data-model/) as well as uPorts [Verification Message Spec](https://developer.uport.me/messages/verification) are proposed off-chain solutions. While built on industry standards such as [JSON-LD](https://json-ld.org) and [JWT](https://jwt.io) neither of them are easy to integrate with the Ethereum ecosystem. [EIP-712](./eip-712.md) introduces a new method of signing off chain Identity data. This provides both a data format based on Solidity ABI encoding that can easily be parsed on-chain an a new JSON-RPC call that is easily supported by existing Ethereum wallets and Web3 clients. This format allows reusable off-chain Verifiable Claims to be cheaply issued to users, who can present them when needed. ## Prior Art Verified Identity Claims such as those proposed by [uPort](https://developer.uport.me/messages/verification) and [W3C Verifiable Claims Working Group](https://www.w3.org/2017/vc/WG/) form an important part of building up reusable identity claims. [ERC-735](https://github.com/ethereum/EIPs/issues/735) and [ERC-780](https://github.com/ethereum/EIPs/issues/780) provide on-chain storage and lookups of Verifiable Claims. ## Specification ### Claims Claims can be generalized like this: > Issuer makes the claim that Subject is something or has some attribute and value. Claims should be deterministic, in that the same claim signed multiple times by the same signer. ### Claims data structure Each claim should be typed based on its specific use case, which EIP 712 lets us do effortlessly. But there are 3 minimal attributes required of the claims structure. * `subject` the subject of the claim as an `address` (who the claim is about) * `validFrom` the time in seconds encoded as a `uint256` of start of validity of claim. In most cases this would be the time of issuance, but some claims may be valid in the future or past. * `validTo` the time in seconds encoded as a `uint256` of when the validity of the claim expires. If you intend for the claim not to expire use `0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff`. The basic minimal claim data structure as a Solidity struct: ```solidity struct [CLAIM TYPE] { address subject; uint256 validFrom; uint256 validTo; } ``` The CLAIM TYPE is the actual name of the claim. While not required, in most cases use the taxonomy developed by [schema.org](https://schema.org/docs/full.html) which is also commonly used in other Verifiable Claims formats. Example claim that issuer knows a subject: ```solidity struct Know { address subject; uint256 validFrom; uint256 validTo; } ``` ### Presenting a Verifiable Claim #### Verifying Contract When defining Verifiable Claims formats a Verifying Contract should be created with a public `verify()` view function. This makes it very easy for other smart contracts to verify a claim correctly. It also provides a convenient interface for web3 and state channel apps to verify claims securely. ```solidity function verifyIssuer(Know memory claim, uint8 v, bytes32 r, bytes32 s) public returns (address) { bytes32 digest = keccak256( abi.encodePacked( "\x19\x01", DOMAIN_SEPARATOR, hash(claim) ) ); require( (claim.validFrom >= block.timestamp) && (block.timestamp < claim.validTo) , "invalid issuance timestamps"); return ecrecover(digest, v, r, s); } ``` #### Calling a SmartContract function Verifiable Claims can be presented to a solidity function call as it’s struct together with the `v`, `r` and `s` signature components. ```solidity function vouch(Know memory claim, uint8 v, bytes32 r, bytes32 s) public returns (bool) { address issuer = verifier.verifyIssuer(claim, v, r, s); require(issuer !== '0x0'); knows[issuer][claim.subject] = block.number; return true; } ``` #### Embedding a Verifiable Claim in another Signed Typed Data structure The Claim struct should be embedded in another struct together with the `v`, `r` and `s` signature parameters. ```solidity struct Know { address subject; uint256 validFrom; uint256 validTo; } struct VerifiableReference { Know delegate; uint8 v; bytes32 r; bytes32 s; } struct Introduction { address recipient; VerifiableReference issuer; } ``` Each Verifiable Claim should be individually verified together with the parent Signed Typed Data structure. Verifiable Claims issued to different EIP 712 Domains can be embedded within each other. #### State Channels This proposal will not show how to use Eth Verifiable Claims as part of a specific State Channel method. Any State Channel based on EIP712 should be able to include the embeddable Verifiable Claims as part of its protocol. This could be useful for exchanging private Identity Claims between the parties for regulatory reasons, while ultimately not posting them to the blockchain on conclusion of a channel. ### Key Delegation In most simple cases the issuer of a Claim is the signer of the data. There are cases however where signing should be delegated to an intermediary key. KeyDelegation can be used to implement off chain signing for smart contract based addresses, server side key rotation as well as employee permissions in complex business use cases. #### ERC1056 Signing Delegation [ERC-1056](./eip-1056.md) provides a method for addresses to assign delegate signers. One of the primary use cases for this is that a smart contract can allow a key pair to sign on its behalf for a certain period. It also allows server based issuance tools to institute key rotation. To support this an additional `issuer` attribute can be added to the Claim Type struct. In this case the verification code should lookup the EthereumDIDRegistry to see if the signer of the data is an allowed signing delegate for the `issuer` The following is the minimal struct for a Claim containing an issuer: ```solidity struct [CLAIM TYPE] { address subject; address issuer; uint256 validFrom; uint256 validTo; } ``` If the `issuer` is specified in the struct In addition to performing the standard ERC712 verification the verification code MUST also verify that the signing address is a valid `veriKey` delegate for the address specified in the issuer. ```solidity registry.validDelegate(issuer, 'veriKey', recoveredAddress) ``` #### Embedded Delegation Proof There may be applications, in particularly where organizations want to allow delegates to issue claims about specific domains and types. For this purpose instead of the `issuer` we allow a special claim to be embedded following this same format: ```solidity struct Delegate { address issuer; address subject; uint256 validFrom; uint256 validTo; } struct VerifiableDelegate { Delegate delegate; uint8 v; bytes32 r; bytes32 s; } struct [CLAIM TYPE] { address subject; VerifiedDelegate issuer; uint256 validFrom; uint256 validTo; } ``` Delegates should be created for specific EIP 712 Domains and not be reused across Domains. Implementers of new EIP 712 Domains can add further data to the `Delegate` struct to allow finer grained application specific rules to it. ### Claim Types #### Binary Claims A Binary claim is something that doesn’t have a particular value. It either is issued or not. Examples: * subject is a Person * subject is my owner (eg. Linking an ethereum account to an owner identity) Example: ```solidity struct Person { address issuer; address subject; uint256 validFrom; uint256 validTo; } ``` This is exactly the same as the minimal claim above with the CLAIM TYPE set to [Person](https://schema.org/Person). ### Value Claims Value claims can be used to make a claim about the subject containing a specific readable value. **WARNING**: Be very careful about using Value Claims as part of Smart Contract transactions. Identity Claims containing values could be a GDPR violation for the business or developer encouraging a user to post it to a public blockchain. Examples: * subject’s name is Alice * subjects average account balance is 1234555 Each value should use the `value` field to indicate the value. A Name Claim ```solidity struct Name { address issuer; address subject; string name; uint256 validFrom; uint256 validTo; } ``` Average Balance ```solidity struct AverageBalance { address issuer; address subject; uint256 value; uint256 validFrom; uint256 validTo; } ``` ### Hashed Claims Hashed claims can be used to make a claim about the subject containing the hash of a claim value. Hashes should use ethereum standard `keccak256` hashing function. **WARNING**: Be very careful about using Hashed Claims as part of Smart Contract transactions. Identity Claims containing hashes of known values could be a GDPR violation for the business or developer encouraging a user to post it to a public blockchain. Examples: - [ ] hash of subject’s name is `keccak256(“Alice Torres”)` - [ ] hash of subject’s email is `keccak256(“alice@example.com”)` Each value should use the `keccak256 ` field to indicate the hashed value. Question. The choice of using this name is that we can easily add support for future algorithms as well as maybe zkSnark proofs. A Name Claim ```solidity struct Name { address issuer; address subject; bytes32 keccak256; uint256 validFrom; uint256 validTo; } ``` Email Claim ```solidity struct Email { address issuer; address subject; bytes32 keccak256; uint256 validFrom; uint256 validTo; } ``` ### EIP 712 Domain The EIP 712 Domain specifies what kind of message that is to be signed and is used to differentiate between signed data types. The content MUST contain the following: ```solidity { name: "EIP1???Claim", version: 1, chainId: 1, // for mainnet verifyingContract: 0x // TBD salt: ... } ``` #### Full Combined format for EIP 712 signing: Following the EIP 712 standard we can combine the Claim Type with the EIP 712 Domain and the claim itself (in the `message`) attribute. Eg: ```solidity { "types": { "EIP712Domain": [ { "name": "name", "type": "string" }, { "name": "version", "type": "string" }, { "name": "chainId", "type": "uint256" }, { "name": "verifyingContract", "type": "address" } ], "Email": [ { "name": "subject", "type": "address" }, { "name": "keccak256", "type": "bytes32" }, { "name": "validFrom", "type": "uint256" }, { "name": "validTo", "type": "uint256" } ] }, "primaryType": "Email", "domain": { "name": "EIP1??? Claim", "version": "1", "chainId": 1, "verifyingContract": "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC" }, "message": { "subject": "0x5792e817336f41de1d8f54feab4bc200624a1d9d", "value": "9c8465d9ae0b0bc167dee7f62880034f59313100a638dcc86a901956ea52e280", "validFrom": "0x0000000000000000000000000000000000000000000000000001644b74c2a0", "validTo": "0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff" } } ``` ### Revocation Both Issuers and Subjects should be allowed to revoke Verifiable Claims. Revocations can be handled through a simple on-chain registry. The ultimate rules of who should be able to revoke a claim is determined by the Verifying contract. The `digest` used for revocation is the EIP712 Signed Typed Data digest. ```solidity contract RevocationRegistry { mapping (bytes32 => mapping (address => uint)) public revocations; function revoke(bytes32 digest) public returns (bool) { revocations[digest][msg.sender] = block.number; return true; } function revoked(address party, bytes32 digest) public view returns (bool) { return revocations[digest][party] > 0; } } ``` A verifying contract can query the Revocation Registry as such: ```solidity bytes32 digest = keccak256( abi.encodePacked( "\x19\x01", DOMAIN_SEPARATOR, hash(claim) ) ); require(valid(claim.validFrom, claim.validTo), "invalid issuance timestamps"); address issuer = ecrecover(digest, v, r, s); require(!revocations.revoked(issuer, digest), "claim was revoked by issuer"); require(!revocations.revoked(claim.subject, digest), "claim was revoked by subject"); ``` ### Creation of Verifiable Claims Domains Creating specific is Verifiable Claims Domains is out of the scope of this EIP. The Example Code has a few examples. EIP’s or another process could be used to standardize specific important Domains that are universally useful across the Ethereum world. ## Rationale Signed Typed Data provides a strong foundation for Verifiable Claims that can be used in many different kinds of applications built on both Layer 1 and Layer 2 of Ethereum. ### Rationale for using not using a single EIP 712 Domain EIP712 supports complex types and domains in itself, that we believe are perfect building blocks for building Verifiable Claims for specific purposes. The Type and Domain of a Claim is itself an important part of a claim and ensures that Verifiable Claims are used for the specific purposes required and not misused. EIP712 Domains also allow rapid experimentation, allowing taxonomies to be built up by the community. ## Test Cases There is a repo with a few example verifiers and consuming smart contracts written in Solidity: **Example Verifiers** * [Verifier for very simple IdVerification Verifiable Claims containing minimal Personal Data](https://github.com/uport-project/eip712-claims-experiments/blob/master/contracts/IdentityClaimsVerifier.sol) * [Verifier for OwnershipProofs signed by a users wallet](https://github.com/uport-project/eip712-claims-experiments/blob/master/contracts/OwnershipProofVerifier.sol) **Example Smart Contracts** * [KYCCoin.sol](https://github.com/uport-project/eip712-claims-experiments/blob/master/contracts/KYCCoin.sol) - Example Token allows reusable IdVerification claims issued by trusted verifiers and users to whitelist their own addresses using OwnershipProofs * [ConsortiumAgreement.sol](https://github.com/uport-project/eip712-claims-experiments/blob/master/contracts/ConsortiumAgreements.sol) - Example Consortium Agreement smart contract. Consortium Members can issue Delegated Claims to employees or servers to interact on their behalf. **Shared Registries** * [RevocationRegistry.sol](https://github.com/uport-project/eip712-claims-experiments/blob/master/contracts/RevocationRegistry.sol) ## Copyright Copyright and related rights waived via [CC0](/LICENSE).

Pseudo-introspection Registry Contract

Mon, 04 Mar 2019 00:00:00 +0000

> :information_source: **[ERC-1820] has superseded [ERC-820].** :information_source: > [ERC-1820] fixes the incompatibility in the [ERC-165] logic which was introduced by the Solidity 0.5 update. > Have a look at the [official announcement][erc1820-annoucement], and the comments about the [bug][erc820-bug] and the [fix][erc820-fix]. > Apart from this fix, [ERC-1820] is functionally equivalent to [ERC-820]. > > :warning: [ERC-1820] MUST be used in lieu of [ERC-820]. :warning: ## Simple Summary This standard defines a universal registry smart contract where any address (contract or regular account) can register which interface it supports and which smart contract is responsible for its implementation. This standard keeps backward compatibility with [ERC-165]. ## Abstract This standard defines a registry where smart contracts and regular accounts can publish which functionality they implement---either directly or through a proxy contract. Anyone can query this registry to ask if a specific address implements a given interface and which smart contract handles its implementation. This registry MAY be deployed on any chain and shares the same address on all chains. Interfaces with zeroes (`0`) as the last 28 bytes are considered [ERC-165] interfaces, and this registry SHALL forward the call to the contract to see if it implements the interface. This contract also acts as an [ERC-165] cache to reduce gas consumption. ## Motivation There have been different approaches to define pseudo-introspection in Ethereum. The first is [ERC-165] which has the limitation that it cannot be used by regular accounts. The second attempt is [ERC-672] which uses reverse [ENS]. Using reverse [ENS] has two issues. First, it is unnecessarily complicated, and second, [ENS] is still a centralized contract controlled by a multisig. This multisig theoretically would be able to modify the system. This standard is much simpler than [ERC-672], and it is *fully* decentralized. This standard also provides a *unique* address for all chains. Thus solving the problem of resolving the correct registry address for different chains. ## Specification ### [ERC-1820] Registry Smart Contract > This is an exact copy of the code of the [ERC1820 registry smart contract]. ``` solidity /* ERC1820 Pseudo-introspection Registry Contract * This standard defines a universal registry smart contract where any address (contract or regular account) can * register which interface it supports and which smart contract is responsible for its implementation. * * Written in 2019 by Jordi Baylina and Jacques Dafflon * * To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to * this software to the public domain worldwide. This software is distributed without any warranty. * * You should have received a copy of the CC0 Public Domain Dedication along with this software. If not, see * . * * ███████╗██████╗ ██████╗ ██╗ █████╗ ██████╗ ██████╗ * ██╔════╝██╔══██╗██╔════╝███║██╔══██╗╚════██╗██╔═████╗ * █████╗ ██████╔╝██║ ╚██║╚█████╔╝ █████╔╝██║██╔██║ * ██╔══╝ ██╔══██╗██║ ██║██╔══██╗██╔═══╝ ████╔╝██║ * ███████╗██║ ██║╚██████╗ ██║╚█████╔╝███████╗╚██████╔╝ * ╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚════╝ ╚══════╝ ╚═════╝ * * ██████╗ ███████╗ ██████╗ ██╗███████╗████████╗██████╗ ██╗ ██╗ * ██╔══██╗██╔════╝██╔════╝ ██║██╔════╝╚══██╔══╝██╔══██╗╚██╗ ██╔╝ * ██████╔╝█████╗ ██║ ███╗██║███████╗ ██║ ██████╔╝ ╚████╔╝ * ██╔══██╗██╔══╝ ██║ ██║██║╚════██║ ██║ ██╔══██╗ ╚██╔╝ * ██║ ██║███████╗╚██████╔╝██║███████║ ██║ ██║ ██║ ██║ * ╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚═╝╚══════╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ * */ pragma solidity 0.5.3; // IV is value needed to have a vanity address starting with '0x1820'. // IV: 53759 /// @dev The interface a contract MUST implement if it is the implementer of /// some (other) interface for any address other than itself. interface ERC1820ImplementerInterface { /// @notice Indicates whether the contract implements the interface 'interfaceHash' for the address 'addr' or not. /// @param interfaceHash keccak256 hash of the name of the interface /// @param addr Address for which the contract will implement the interface /// @return ERC1820_ACCEPT_MAGIC only if the contract implements 'interfaceHash' for the address 'addr'. function canImplementInterfaceForAddress(bytes32 interfaceHash, address addr) external view returns(bytes32); } /// @title ERC1820 Pseudo-introspection Registry Contract /// @author Jordi Baylina and Jacques Dafflon /// @notice This contract is the official implementation of the ERC1820 Registry. /// @notice For more details, see https://eips.ethereum.org/EIPS/eip-1820 contract ERC1820Registry { /// @notice ERC165 Invalid ID. bytes4 constant internal INVALID_ID = 0xffffffff; /// @notice Method ID for the ERC165 supportsInterface method (= `bytes4(keccak256('supportsInterface(bytes4)'))`). bytes4 constant internal ERC165ID = 0x01ffc9a7; /// @notice Magic value which is returned if a contract implements an interface on behalf of some other address. bytes32 constant internal ERC1820_ACCEPT_MAGIC = keccak256(abi.encodePacked("ERC1820_ACCEPT_MAGIC")); /// @notice mapping from addresses and interface hashes to their implementers. mapping(address => mapping(bytes32 => address)) internal interfaces; /// @notice mapping from addresses to their manager. mapping(address => address) internal managers; /// @notice flag for each address and erc165 interface to indicate if it is cached. mapping(address => mapping(bytes4 => bool)) internal erc165Cached; /// @notice Indicates a contract is the 'implementer' of 'interfaceHash' for 'addr'. event InterfaceImplementerSet(address indexed addr, bytes32 indexed interfaceHash, address indexed implementer); /// @notice Indicates 'newManager' is the address of the new manager for 'addr'. event ManagerChanged(address indexed addr, address indexed newManager); /// @notice Query if an address implements an interface and through which contract. /// @param _addr Address being queried for the implementer of an interface. /// (If '_addr' is the zero address then 'msg.sender' is assumed.) /// @param _interfaceHash Keccak256 hash of the name of the interface as a string. /// E.g., 'web3.utils.keccak256("ERC777TokensRecipient")' for the 'ERC777TokensRecipient' interface. /// @return The address of the contract which implements the interface '_interfaceHash' for '_addr' /// or '0' if '_addr' did not register an implementer for this interface. function getInterfaceImplementer(address _addr, bytes32 _interfaceHash) external view returns (address) { address addr = _addr == address(0) ? msg.sender : _addr; if (isERC165Interface(_interfaceHash)) { bytes4 erc165InterfaceHash = bytes4(_interfaceHash); return implementsERC165Interface(addr, erc165InterfaceHash) ? addr : address(0); } return interfaces[addr][_interfaceHash]; } /// @notice Sets the contract which implements a specific interface for an address. /// Only the manager defined for that address can set it. /// (Each address is the manager for itself until it sets a new manager.) /// @param _addr Address for which to set the interface. /// (If '_addr' is the zero address then 'msg.sender' is assumed.) /// @param _interfaceHash Keccak256 hash of the name of the interface as a string. /// E.g., 'web3.utils.keccak256("ERC777TokensRecipient")' for the 'ERC777TokensRecipient' interface. /// @param _implementer Contract address implementing '_interfaceHash' for '_addr'. function setInterfaceImplementer(address _addr, bytes32 _interfaceHash, address _implementer) external { address addr = _addr == address(0) ? msg.sender : _addr; require(getManager(addr) == msg.sender, "Not the manager"); require(!isERC165Interface(_interfaceHash), "Must not be an ERC165 hash"); if (_implementer != address(0) && _implementer != msg.sender) { require( ERC1820ImplementerInterface(_implementer) .canImplementInterfaceForAddress(_interfaceHash, addr) == ERC1820_ACCEPT_MAGIC, "Does not implement the interface" ); } interfaces[addr][_interfaceHash] = _implementer; emit InterfaceImplementerSet(addr, _interfaceHash, _implementer); } /// @notice Sets '_newManager' as manager for '_addr'. /// The new manager will be able to call 'setInterfaceImplementer' for '_addr'. /// @param _addr Address for which to set the new manager. /// @param _newManager Address of the new manager for 'addr'. (Pass '0x0' to reset the manager to '_addr'.) function setManager(address _addr, address _newManager) external { require(getManager(_addr) == msg.sender, "Not the manager"); managers[_addr] = _newManager == _addr ? address(0) : _newManager; emit ManagerChanged(_addr, _newManager); } /// @notice Get the manager of an address. /// @param _addr Address for which to return the manager. /// @return Address of the manager for a given address. function getManager(address _addr) public view returns(address) { // By default the manager of an address is the same address if (managers[_addr] == address(0)) { return _addr; } else { return managers[_addr]; } } /// @notice Compute the keccak256 hash of an interface given its name. /// @param _interfaceName Name of the interface. /// @return The keccak256 hash of an interface name. function interfaceHash(string calldata _interfaceName) external pure returns(bytes32) { return keccak256(abi.encodePacked(_interfaceName)); } /* --- ERC165 Related Functions --- */ /* --- Developed in collaboration with William Entriken. --- */ /// @notice Updates the cache with whether the contract implements an ERC165 interface or not. /// @param _contract Address of the contract for which to update the cache. /// @param _interfaceId ERC165 interface for which to update the cache. function updateERC165Cache(address _contract, bytes4 _interfaceId) external { interfaces[_contract][_interfaceId] = implementsERC165InterfaceNoCache( _contract, _interfaceId) ? _contract : address(0); erc165Cached[_contract][_interfaceId] = true; } /// @notice Checks whether a contract implements an ERC165 interface or not. // If the result is not cached a direct lookup on the contract address is performed. // If the result is not cached or the cached value is out-of-date, the cache MUST be updated manually by calling // 'updateERC165Cache' with the contract address. /// @param _contract Address of the contract to check. /// @param _interfaceId ERC165 interface to check. /// @return True if '_contract' implements '_interfaceId', false otherwise. function implementsERC165Interface(address _contract, bytes4 _interfaceId) public view returns (bool) { if (!erc165Cached[_contract][_interfaceId]) { return implementsERC165InterfaceNoCache(_contract, _interfaceId); } return interfaces[_contract][_interfaceId] == _contract; } /// @notice Checks whether a contract implements an ERC165 interface or not without using nor updating the cache. /// @param _contract Address of the contract to check. /// @param _interfaceId ERC165 interface to check. /// @return True if '_contract' implements '_interfaceId', false otherwise. function implementsERC165InterfaceNoCache(address _contract, bytes4 _interfaceId) public view returns (bool) { uint256 success; uint256 result; (success, result) = noThrowCall(_contract, ERC165ID); if (success == 0 || result == 0) { return false; } (success, result) = noThrowCall(_contract, INVALID_ID); if (success == 0 || result != 0) { return false; } (success, result) = noThrowCall(_contract, _interfaceId); if (success == 1 && result == 1) { return true; } return false; } /// @notice Checks whether the hash is a ERC165 interface (ending with 28 zeroes) or not. /// @param _interfaceHash The hash to check. /// @return True if '_interfaceHash' is an ERC165 interface (ending with 28 zeroes), false otherwise. function isERC165Interface(bytes32 _interfaceHash) internal pure returns (bool) { return _interfaceHash & 0x00000000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF == 0; } /// @dev Make a call on a contract without throwing if the function does not exist. function noThrowCall(address _contract, bytes4 _interfaceId) internal view returns (uint256 success, uint256 result) { bytes4 erc165ID = ERC165ID; assembly { let x := mload(0x40) // Find empty storage location using "free memory pointer" mstore(x, erc165ID) // Place signature at beginning of empty storage mstore(add(x, 0x04), _interfaceId) // Place first argument directly next to signature success := staticcall( 30000, // 30k gas _contract, // To addr x, // Inputs are stored at location x 0x24, // Inputs are 36 (4 + 32) bytes long x, // Store output over input (saves space) 0x20 // Outputs are 32 bytes long ) result := mload(x) // Load the result } } } ``` ### Deployment Transaction Below is the raw transaction which MUST be used to deploy the smart contract on any chain. ``` 0xf90a388085174876e800830c35008080b909e5608060405234801561001057600080fd5b506109c5806100206000396000f3fe608060405234801561001057600080fd5b50600436106100a5576000357c010000000000000000000000000000000000000000000000000000000090048063a41e7d5111610078578063a41e7d51146101d4578063aabbb8ca1461020a578063b705676514610236578063f712f3e814610280576100a5565b806329965a1d146100aa5780633d584063146100e25780635df8122f1461012457806365ba36c114610152575b600080fd5b6100e0600480360360608110156100c057600080fd5b50600160a060020a038135811691602081013591604090910135166102b6565b005b610108600480360360208110156100f857600080fd5b5035600160a060020a0316610570565b60408051600160a060020a039092168252519081900360200190f35b6100e06004803603604081101561013a57600080fd5b50600160a060020a03813581169160200135166105bc565b6101c26004803603602081101561016857600080fd5b81019060208101813564010000000081111561018357600080fd5b82018360208201111561019557600080fd5b803590602001918460018302840111640100000000831117156101b757600080fd5b5090925090506106b3565b60408051918252519081900360200190f35b6100e0600480360360408110156101ea57600080fd5b508035600160a060020a03169060200135600160e060020a0319166106ee565b6101086004803603604081101561022057600080fd5b50600160a060020a038135169060200135610778565b61026c6004803603604081101561024c57600080fd5b508035600160a060020a03169060200135600160e060020a0319166107ef565b604080519115158252519081900360200190f35b61026c6004803603604081101561029657600080fd5b508035600160a060020a03169060200135600160e060020a0319166108aa565b6000600160a060020a038416156102cd57836102cf565b335b9050336102db82610570565b600160a060020a031614610339576040805160e560020a62461bcd02815260206004820152600f60248201527f4e6f7420746865206d616e616765720000000000000000000000000000000000604482015290519081900360640190fd5b6103428361092a565b15610397576040805160e560020a62461bcd02815260206004820152601a60248201527f4d757374206e6f7420626520616e204552433136352068617368000000000000604482015290519081900360640190fd5b600160a060020a038216158015906103b85750600160a060020a0382163314155b156104ff5760405160200180807f455243313832305f4143434550545f4d4147494300000000000000000000000081525060140190506040516020818303038152906040528051906020012082600160a060020a031663249cb3fa85846040518363ffffffff167c01000000000000000000000000000000000000000000000000000000000281526004018083815260200182600160a060020a0316600160a060020a031681526020019250505060206040518083038186803b15801561047e57600080fd5b505afa158015610492573d6000803e3d6000fd5b505050506040513d60208110156104a857600080fd5b5051146104ff576040805160e560020a62461bcd02815260206004820181905260248201527f446f6573206e6f7420696d706c656d656e742074686520696e74657266616365604482015290519081900360640190fd5b600160a060020a03818116600081815260208181526040808320888452909152808220805473ffffffffffffffffffffffffffffffffffffffff19169487169485179055518692917f93baa6efbd2244243bfee6ce4cfdd1d04fc4c0e9a786abd3a41313bd352db15391a450505050565b600160a060020a03818116600090815260016020526040812054909116151561059a5750806105b7565b50600160a060020a03808216600090815260016020526040902054165b919050565b336105c683610570565b600160a060020a031614610624576040805160e560020a62461bcd02815260206004820152600f60248201527f4e6f7420746865206d616e616765720000000000000000000000000000000000604482015290519081900360640190fd5b81600160a060020a031681600160a060020a0316146106435780610646565b60005b600160a060020a03838116600081815260016020526040808220805473ffffffffffffffffffffffffffffffffffffffff19169585169590951790945592519184169290917f605c2dbf762e5f7d60a546d42e7205dcb1b011ebc62a61736a57c9089d3a43509190a35050565b600082826040516020018083838082843780830192505050925050506040516020818303038152906040528051906020012090505b92915050565b6106f882826107ef565b610703576000610705565b815b600160a060020a03928316600081815260208181526040808320600160e060020a031996909616808452958252808320805473ffffffffffffffffffffffffffffffffffffffff19169590971694909417909555908152600284528181209281529190925220805460ff19166001179055565b600080600160a060020a038416156107905783610792565b335b905061079d8361092a565b156107c357826107ad82826108aa565b6107b85760006107ba565b815b925050506106e8565b600160a060020a0390811660009081526020818152604080832086845290915290205416905092915050565b6000808061081d857f01ffc9a70000000000000000000000000000000000000000000000000000000061094c565b909250905081158061082d575080155b1561083d576000925050506106e8565b61084f85600160e060020a031961094c565b909250905081158061086057508015155b15610870576000925050506106e8565b61087a858561094c565b909250905060018214801561088f5750806001145b1561089f576001925050506106e8565b506000949350505050565b600160a060020a0382166000908152600260209081526040808320600160e060020a03198516845290915281205460ff1615156108f2576108eb83836107ef565b90506106e8565b50600160a060020a03808316600081815260208181526040808320600160e060020a0319871684529091529020549091161492915050565b7bffffffffffffffffffffffffffffffffffffffffffffffffffffffff161590565b6040517f01ffc9a7000000000000000000000000000000000000000000000000000000008082526004820183905260009182919060208160248189617530fa90519096909550935050505056fea165627a7a72305820377f4a2d4301ede9949f163f319021a6e9c687c292a5e2b2c4734c126b524e6c00291ba01820182018201820182018201820182018201820182018201820182018201820a01820182018201820182018201820182018201820182018201820182018201820 ``` The strings of `1820`'s at the end of the transaction are the `r` and `s` of the signature. From this deterministic pattern (generated by a human), anyone can deduce that no one knows the private key for the deployment account. ### Deployment Method This contract is going to be deployed using the keyless deployment method---also known as [Nick]'s method---which relies on a single-use address. (See [Nick's article] for more details). This method works as follows: 1. Generate a transaction which deploys the contract from a new random account. - This transaction MUST NOT use [EIP-155] in order to work on any chain. - This transaction MUST have a relatively high gas price to be deployed on any chain. In this case, it is going to be 100 Gwei. 2. Set the `v`, `r`, `s` of the transaction signature to the following values: ``` v: 27, r: 0x1820182018201820182018201820182018201820182018201820182018201820' s: 0x1820182018201820182018201820182018201820182018201820182018201820' ``` Those `r` and `s` values---made of a repeating pattern of `1820`'s---are predictable "random numbers" generated deterministically by a human. 3. We recover the sender of this transaction, i.e., the single-use deployment account. > Thus we obtain an account that can broadcast that transaction, but we also have the warranty that nobody knows the private key of that account. 4. Send exactly 0.08 ether to this single-use deployment account. 5. Broadcast the deployment transaction. This operation can be done on any chain, guaranteeing that the contract address is always the same and nobody can use that address with a different contract. ### Single-use Registry Deployment Account ``` 0xa990077c3205cbDf861e17Fa532eeB069cE9fF96 ``` This account is generated by reverse engineering it from its signature for the transaction. This way no one knows the private key, but it is known that it is the valid signer of the deployment transaction. > To deploy the registry, 0.08 ether MUST be sent to this account *first*. ### Registry Contract Address ``` 0x1820a4B7618BdE71Dce8cdc73aAB6C95905faD24 ``` The contract has the address above for every chain on which it is deployed.

Raw metadata of ./contracts/ERC1820Registry.sol

```json { "compiler": { "version": "0.5.3+commit.10d17f24" }, "language": "Solidity", "output": { "abi": [ { "constant": false, "inputs": [ { "name": "_addr", "type": "address" }, { "name": "_interfaceHash", "type": "bytes32" }, { "name": "_implementer", "type": "address" } ], "name": "setInterfaceImplementer", "outputs": [], "payable": false, "stateMutability": "nonpayable", "type": "function" }, { "constant": true, "inputs": [ { "name": "_addr", "type": "address" } ], "name": "getManager", "outputs": [ { "name": "", "type": "address" } ], "payable": false, "stateMutability": "view", "type": "function" }, { "constant": false, "inputs": [ { "name": "_addr", "type": "address" }, { "name": "_newManager", "type": "address" } ], "name": "setManager", "outputs": [], "payable": false, "stateMutability": "nonpayable", "type": "function" }, { "constant": true, "inputs": [ { "name": "_interfaceName", "type": "string" } ], "name": "interfaceHash", "outputs": [ { "name": "", "type": "bytes32" } ], "payable": false, "stateMutability": "pure", "type": "function" }, { "constant": false, "inputs": [ { "name": "_contract", "type": "address" }, { "name": "_interfaceId", "type": "bytes4" } ], "name": "updateERC165Cache", "outputs": [], "payable": false, "stateMutability": "nonpayable", "type": "function" }, { "constant": true, "inputs": [ { "name": "_addr", "type": "address" }, { "name": "_interfaceHash", "type": "bytes32" } ], "name": "getInterfaceImplementer", "outputs": [ { "name": "", "type": "address" } ], "payable": false, "stateMutability": "view", "type": "function" }, { "constant": true, "inputs": [ { "name": "_contract", "type": "address" }, { "name": "_interfaceId", "type": "bytes4" } ], "name": "implementsERC165InterfaceNoCache", "outputs": [ { "name": "", "type": "bool" } ], "payable": false, "stateMutability": "view", "type": "function" }, { "constant": true, "inputs": [ { "name": "_contract", "type": "address" }, { "name": "_interfaceId", "type": "bytes4" } ], "name": "implementsERC165Interface", "outputs": [ { "name": "", "type": "bool" } ], "payable": false, "stateMutability": "view", "type": "function" }, { "anonymous": false, "inputs": [ { "indexed": true, "name": "addr", "type": "address" }, { "indexed": true, "name": "interfaceHash", "type": "bytes32" }, { "indexed": true, "name": "implementer", "type": "address" } ], "name": "InterfaceImplementerSet", "type": "event" }, { "anonymous": false, "inputs": [ { "indexed": true, "name": "addr", "type": "address" }, { "indexed": true, "name": "newManager", "type": "address" } ], "name": "ManagerChanged", "type": "event" } ], "devdoc": { "author": "Jordi Baylina and Jacques Dafflon", "methods": { "getInterfaceImplementer(address,bytes32)": { "params": { "_addr": "Address being queried for the implementer of an interface. (If '_addr' is the zero address then 'msg.sender' is assumed.)", "_interfaceHash": "Keccak256 hash of the name of the interface as a string. E.g., 'web3.utils.keccak256(\"ERC777TokensRecipient\")' for the 'ERC777TokensRecipient' interface." }, "return": "The address of the contract which implements the interface '_interfaceHash' for '_addr' or '0' if '_addr' did not register an implementer for this interface." }, "getManager(address)": { "params": { "_addr": "Address for which to return the manager." }, "return": "Address of the manager for a given address." }, "implementsERC165Interface(address,bytes4)": { "params": { "_contract": "Address of the contract to check.", "_interfaceId": "ERC165 interface to check." }, "return": "True if '_contract' implements '_interfaceId', false otherwise." }, "implementsERC165InterfaceNoCache(address,bytes4)": { "params": { "_contract": "Address of the contract to check.", "_interfaceId": "ERC165 interface to check." }, "return": "True if '_contract' implements '_interfaceId', false otherwise." }, "interfaceHash(string)": { "params": { "_interfaceName": "Name of the interface." }, "return": "The keccak256 hash of an interface name." }, "setInterfaceImplementer(address,bytes32,address)": { "params": { "_addr": "Address for which to set the interface. (If '_addr' is the zero address then 'msg.sender' is assumed.)", "_implementer": "Contract address implementing '_interfaceHash' for '_addr'.", "_interfaceHash": "Keccak256 hash of the name of the interface as a string. E.g., 'web3.utils.keccak256(\"ERC777TokensRecipient\")' for the 'ERC777TokensRecipient' interface." } }, "setManager(address,address)": { "params": { "_addr": "Address for which to set the new manager.", "_newManager": "Address of the new manager for 'addr'. (Pass '0x0' to reset the manager to '_addr'.)" } }, "updateERC165Cache(address,bytes4)": { "params": { "_contract": "Address of the contract for which to update the cache.", "_interfaceId": "ERC165 interface for which to update the cache." } } }, "title": "ERC1820 Pseudo-introspection Registry Contract" }, "userdoc": { "methods": { "getInterfaceImplementer(address,bytes32)": { "notice": "Query if an address implements an interface and through which contract." }, "getManager(address)": { "notice": "Get the manager of an address." }, "implementsERC165InterfaceNoCache(address,bytes4)": { "notice": "Checks whether a contract implements an ERC165 interface or not without using nor updating the cache." }, "interfaceHash(string)": { "notice": "Compute the keccak256 hash of an interface given its name." }, "setInterfaceImplementer(address,bytes32,address)": { "notice": "Sets the contract which implements a specific interface for an address. Only the manager defined for that address can set it. (Each address is the manager for itself until it sets a new manager.)" }, "setManager(address,address)": { "notice": "Sets '_newManager' as manager for '_addr'. The new manager will be able to call 'setInterfaceImplementer' for '_addr'." }, "updateERC165Cache(address,bytes4)": { "notice": "Updates the cache with whether the contract implements an ERC165 interface or not." } }, "notice": "This contract is the official implementation of the ERC1820 Registry.For more details, see https://eips.ethereum.org/EIPS/eip-1820" } }, "settings": { "compilationTarget": { "./contracts/ERC1820Registry.sol": "ERC1820Registry" }, "evmVersion": "byzantium", "libraries": {}, "optimizer": { "enabled": true, "runs": 200 }, "remappings": [] }, "sources": { "./contracts/ERC1820Registry.sol": { "content": "/* ERC1820 Pseudo-introspection Registry Contract\n * This standard defines a universal registry smart contract where any address (contract or regular account) can\n * register which interface it supports and which smart contract is responsible for its implementation.\n *\n * Written in 2019 by Jordi Baylina and Jacques Dafflon\n *\n * To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to\n * this software to the public domain worldwide. This software is distributed without any warranty.\n *\n * You should have received a copy of the CC0 Public Domain Dedication along with this software. If not, see\n * .\n *\n * ███████╗██████╗ ██████╗ ██╗ █████╗ ██████╗ ██████╗\n * ██╔════╝██╔══██╗██╔════╝███║██╔══██╗╚════██╗██╔═████╗\n * █████╗ ██████╔╝██║ ╚██║╚█████╔╝ █████╔╝██║██╔██║\n * ██╔══╝ ██╔══██╗██║ ██║██╔══██╗██╔═══╝ ████╔╝██║\n * ███████╗██║ ██║╚██████╗ ██║╚█████╔╝███████╗╚██████╔╝\n * ╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚════╝ ╚══════╝ ╚═════╝\n *\n * ██████╗ ███████╗ ██████╗ ██╗███████╗████████╗██████╗ ██╗ ██╗\n * ██╔══██╗██╔════╝██╔════╝ ██║██╔════╝╚══██╔══╝██╔══██╗╚██╗ ██╔╝\n * ██████╔╝█████╗ ██║ ███╗██║███████╗ ██║ ██████╔╝ ╚████╔╝\n * ██╔══██╗██╔══╝ ██║ ██║██║╚════██║ ██║ ██╔══██╗ ╚██╔╝\n * ██║ ██║███████╗╚██████╔╝██║███████║ ██║ ██║ ██║ ██║\n * ╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚═╝╚══════╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝\n *\n */\npragma solidity 0.5.3;\n// IV is value needed to have a vanity address starting with '0x1820'.\n// IV: 53759\n\n/// @dev The interface a contract MUST implement if it is the implementer of\n/// some (other) interface for any address other than itself.\ninterface ERC1820ImplementerInterface {\n /// @notice Indicates whether the contract implements the interface 'interfaceHash' for the address 'addr' or not.\n /// @param interfaceHash keccak256 hash of the name of the interface\n /// @param addr Address for which the contract will implement the interface\n /// @return ERC1820_ACCEPT_MAGIC only if the contract implements 'interfaceHash' for the address 'addr'.\n function canImplementInterfaceForAddress(bytes32 interfaceHash, address addr) external view returns(bytes32);\n}\n\n\n/// @title ERC1820 Pseudo-introspection Registry Contract\n/// @author Jordi Baylina and Jacques Dafflon\n/// @notice This contract is the official implementation of the ERC1820 Registry.\n/// @notice For more details, see https://eips.ethereum.org/EIPS/eip-1820\ncontract ERC1820Registry {\n /// @notice ERC165 Invalid ID.\n bytes4 constant internal INVALID_ID = 0xffffffff;\n /// @notice Method ID for the ERC165 supportsInterface method (= `bytes4(keccak256('supportsInterface(bytes4)'))`).\n bytes4 constant internal ERC165ID = 0x01ffc9a7;\n /// @notice Magic value which is returned if a contract implements an interface on behalf of some other address.\n bytes32 constant internal ERC1820_ACCEPT_MAGIC = keccak256(abi.encodePacked(\"ERC1820_ACCEPT_MAGIC\"));\n\n /// @notice mapping from addresses and interface hashes to their implementers.\n mapping(address => mapping(bytes32 => address)) internal interfaces;\n /// @notice mapping from addresses to their manager.\n mapping(address => address) internal managers;\n /// @notice flag for each address and erc165 interface to indicate if it is cached.\n mapping(address => mapping(bytes4 => bool)) internal erc165Cached;\n\n /// @notice Indicates a contract is the 'implementer' of 'interfaceHash' for 'addr'.\n event InterfaceImplementerSet(address indexed addr, bytes32 indexed interfaceHash, address indexed implementer);\n /// @notice Indicates 'newManager' is the address of the new manager for 'addr'.\n event ManagerChanged(address indexed addr, address indexed newManager);\n\n /// @notice Query if an address implements an interface and through which contract.\n /// @param _addr Address being queried for the implementer of an interface.\n /// (If '_addr' is the zero address then 'msg.sender' is assumed.)\n /// @param _interfaceHash Keccak256 hash of the name of the interface as a string.\n /// E.g., 'web3.utils.keccak256(\"ERC777TokensRecipient\")' for the 'ERC777TokensRecipient' interface.\n /// @return The address of the contract which implements the interface '_interfaceHash' for '_addr'\n /// or '0' if '_addr' did not register an implementer for this interface.\n function getInterfaceImplementer(address _addr, bytes32 _interfaceHash) external view returns (address) {\n address addr = _addr == address(0) ? msg.sender : _addr;\n if (isERC165Interface(_interfaceHash)) {\n bytes4 erc165InterfaceHash = bytes4(_interfaceHash);\n return implementsERC165Interface(addr, erc165InterfaceHash) ? addr : address(0);\n }\n return interfaces[addr][_interfaceHash];\n }\n\n /// @notice Sets the contract which implements a specific interface for an address.\n /// Only the manager defined for that address can set it.\n /// (Each address is the manager for itself until it sets a new manager.)\n /// @param _addr Address for which to set the interface.\n /// (If '_addr' is the zero address then 'msg.sender' is assumed.)\n /// @param _interfaceHash Keccak256 hash of the name of the interface as a string.\n /// E.g., 'web3.utils.keccak256(\"ERC777TokensRecipient\")' for the 'ERC777TokensRecipient' interface.\n /// @param _implementer Contract address implementing '_interfaceHash' for '_addr'.\n function setInterfaceImplementer(address _addr, bytes32 _interfaceHash, address _implementer) external {\n address addr = _addr == address(0) ? msg.sender : _addr;\n require(getManager(addr) == msg.sender, \"Not the manager\");\n\n require(!isERC165Interface(_interfaceHash), \"Must not be an ERC165 hash\");\n if (_implementer != address(0) && _implementer != msg.sender) {\n require(\n ERC1820ImplementerInterface(_implementer)\n .canImplementInterfaceForAddress(_interfaceHash, addr) == ERC1820_ACCEPT_MAGIC,\n \"Does not implement the interface\"\n );\n }\n interfaces[addr][_interfaceHash] = _implementer;\n emit InterfaceImplementerSet(addr, _interfaceHash, _implementer);\n }\n\n /// @notice Sets '_newManager' as manager for '_addr'.\n /// The new manager will be able to call 'setInterfaceImplementer' for '_addr'.\n /// @param _addr Address for which to set the new manager.\n /// @param _newManager Address of the new manager for 'addr'. (Pass '0x0' to reset the manager to '_addr'.)\n function setManager(address _addr, address _newManager) external {\n require(getManager(_addr) == msg.sender, \"Not the manager\");\n managers[_addr] = _newManager == _addr ? address(0) : _newManager;\n emit ManagerChanged(_addr, _newManager);\n }\n\n /// @notice Get the manager of an address.\n /// @param _addr Address for which to return the manager.\n /// @return Address of the manager for a given address.\n function getManager(address _addr) public view returns(address) {\n // By default the manager of an address is the same address\n if (managers[_addr] == address(0)) {\n return _addr;\n } else {\n return managers[_addr];\n }\n }\n\n /// @notice Compute the keccak256 hash of an interface given its name.\n /// @param _interfaceName Name of the interface.\n /// @return The keccak256 hash of an interface name.\n function interfaceHash(string calldata _interfaceName) external pure returns(bytes32) {\n return keccak256(abi.encodePacked(_interfaceName));\n }\n\n /* --- ERC165 Related Functions --- */\n /* --- Developed in collaboration with William Entriken. --- */\n\n /// @notice Updates the cache with whether the contract implements an ERC165 interface or not.\n /// @param _contract Address of the contract for which to update the cache.\n /// @param _interfaceId ERC165 interface for which to update the cache.\n function updateERC165Cache(address _contract, bytes4 _interfaceId) external {\n interfaces[_contract][_interfaceId] = implementsERC165InterfaceNoCache(\n _contract, _interfaceId) ? _contract : address(0);\n erc165Cached[_contract][_interfaceId] = true;\n }\n\n /// @notice Checks whether a contract implements an ERC165 interface or not.\n // If the result is not cached a direct lookup on the contract address is performed.\n // If the result is not cached or the cached value is out-of-date, the cache MUST be updated manually by calling\n // 'updateERC165Cache' with the contract address.\n /// @param _contract Address of the contract to check.\n /// @param _interfaceId ERC165 interface to check.\n /// @return True if '_contract' implements '_interfaceId', false otherwise.\n function implementsERC165Interface(address _contract, bytes4 _interfaceId) public view returns (bool) {\n if (!erc165Cached[_contract][_interfaceId]) {\n return implementsERC165InterfaceNoCache(_contract, _interfaceId);\n }\n return interfaces[_contract][_interfaceId] == _contract;\n }\n\n /// @notice Checks whether a contract implements an ERC165 interface or not without using nor updating the cache.\n /// @param _contract Address of the contract to check.\n /// @param _interfaceId ERC165 interface to check.\n /// @return True if '_contract' implements '_interfaceId', false otherwise.\n function implementsERC165InterfaceNoCache(address _contract, bytes4 _interfaceId) public view returns (bool) {\n uint256 success;\n uint256 result;\n\n (success, result) = noThrowCall(_contract, ERC165ID);\n if (success == 0 || result == 0) {\n return false;\n }\n\n (success, result) = noThrowCall(_contract, INVALID_ID);\n if (success == 0 || result != 0) {\n return false;\n }\n\n (success, result) = noThrowCall(_contract, _interfaceId);\n if (success == 1 && result == 1) {\n return true;\n }\n return false;\n }\n\n /// @notice Checks whether the hash is a ERC165 interface (ending with 28 zeroes) or not.\n /// @param _interfaceHash The hash to check.\n /// @return True if '_interfaceHash' is an ERC165 interface (ending with 28 zeroes), false otherwise.\n function isERC165Interface(bytes32 _interfaceHash) internal pure returns (bool) {\n return _interfaceHash & 0x00000000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF == 0;\n }\n\n /// @dev Make a call on a contract without throwing if the function does not exist.\n function noThrowCall(address _contract, bytes4 _interfaceId)\n internal view returns (uint256 success, uint256 result)\n {\n bytes4 erc165ID = ERC165ID;\n\n assembly {\n let x := mload(0x40) // Find empty storage location using \"free memory pointer\"\n mstore(x, erc165ID) // Place signature at beginning of empty storage\n mstore(add(x, 0x04), _interfaceId) // Place first argument directly next to signature\n\n success := staticcall(\n 30000, // 30k gas\n _contract, // To addr\n x, // Inputs are stored at location x\n 0x24, // Inputs are 36 (4 + 32) bytes long\n x, // Store output over input (saves space)\n 0x20 // Outputs are 32 bytes long\n )\n\n result := mload(x) // Load the result\n }\n }\n}\n", "keccak256": "0x64025ecebddb6e126a5075c1fd6c01de2840492668e2909cef7157040a9d1945" } }, "version": 1 } ```

### Interface Name Any interface name is hashed using `keccak256` and sent to `getInterfaceImplementer()`. If the interface is part of a standard, it is best practice to explicitly state the interface name and link to this published [ERC-1820] such that other people don't have to come here to look up these rules. For convenience, the registry provides a function to compute the hash on-chain: ``` solidity function interfaceHash(string _interfaceName) public pure returns(bytes32) ``` Compute the keccak256 hash of an interface given its name. > **identifier:** `65ba36c1` > **parameters** > `_interfaceName`: Name of the interface. > **returns:** The `keccak256` hash of an interface name. #### **Approved ERCs** If the interface is part of an approved ERC, it MUST be named `ERC###XXXXX` where `###` is the number of the ERC and XXXXX should be the name of the interface in CamelCase. The meaning of this interface SHOULD be defined in the specified ERC. Examples: - `keccak256("ERC20Token")` - `keccak256("ERC777Token")` - `keccak256("ERC777TokensSender")` - `keccak256("ERC777TokensRecipient")` #### **[ERC-165] Compatible Interfaces** > The compatibility with [ERC-165], including the [ERC165 Cache], has been designed and developed with [William Entriken]. Any interface where the last 28 bytes are zeroes (`0`) SHALL be considered an [ERC-165] interface. **[ERC-165] Lookup** Anyone can explicitly check if a contract implements an [ERC-165] interface using the registry by calling one of the two functions below: ``` solidity function implementsERC165Interface(address _contract, bytes4 _interfaceId) public view returns (bool) ``` Checks whether a contract implements an [ERC-165] interface or not. If the result is not cached a direct lookup on the contract address is performed. *NOTE*: If the result is not cached or the cached value is out-of-date, the cache MUST be updated manually by calling `updateERC165Cache` with the contract address. (See [ERC165 Cache] for more details.) > **identifier:** `f712f3e8` > **parameters** > `_contract`: Address of the contract to check. > `_interfaceId`: [ERC-165] interface to check. > **returns:** `true` if `_contract` implements `_interfaceId`, `false` otherwise. ``` solidity function implementsERC165InterfaceNoCache(address _contract, bytes4 _interfaceId) public view returns (bool) ``` Checks whether a contract implements an [ERC-165] interface or not without using nor updating the cache. > **identifier:** `b7056765` > **parameters** > `_contract`: Address of the contract to check. > `_interfaceId`: [ERC-165] interface to check. > **returns:** `true` if `_contract` implements `_interfaceId`, false otherwise. **[ERC-165] Cache** Whether a contract implements an [ERC-165] interface or not can be cached manually to save gas. If a contract dynamically changes its interface and relies on the [ERC-165] cache of the [ERC-1820] registry, the cache MUST be updated manually---there is no automatic cache invalidation or cache update. Ideally the contract SHOULD automatically update the cache when changing its interface. However anyone MAY update the cache on the contract's behalf. The cache update MUST be done using the `updateERC165Cache` function: ``` solidity function updateERC165Cache(address _contract, bytes4 _interfaceId) external ``` > **identifier:** `a41e7d51` > **parameters** > `_contract`: Address of the contract for which to update the cache. > `_interfaceId`: [ERC-165] interface for which to update the cache. #### **Private User-defined Interfaces** This scheme is extensible. You MAY make up your own interface name and raise awareness to get other people to implement it and then check for those implementations. Have fun but please, you MUST not conflict with the reserved designations above. ### Set An Interface For An Address For any address to set a contract as the interface implementation, it must call the following function of the [ERC-1820] registry: ``` solidity function setInterfaceImplementer(address _addr, bytes32 _interfaceHash, address _implementer) external ``` Sets the contract which implements a specific interface for an address. Only the `manager` defined for that address can set it. (Each address is the manager for itself, see the [manager] section for more details.) *NOTE*: If `_addr` and `_implementer` are two different addresses, then: - The `_implementer` MUST implement the `ERC1820ImplementerInterface` (detailed below). - Calling `canImplementInterfaceForAddress` on `_implementer` with the given `_addr` and `_interfaceHash` MUST return the `ERC1820_ACCEPT_MAGIC` value. *NOTE*: The `_interfaceHash` MUST NOT be an [ERC-165] interface---it MUST NOT end with 28 zeroes (`0`). *NOTE*: The `_addr` MAY be `0`, then `msg.sender` is assumed. This default value simplifies interactions via multisigs where the data of the transaction to sign is constant regardless of the address of the multisig instance. > **identifier:** `29965a1d` > **parameters** > `_addr`: Address for which to set the interface. (If `_addr` is the zero address then `msg.sender` is assumed.) > `_interfaceHash`: Keccak256 hash of the name of the interface as a string, for example `web3.utils.keccak256('ERC777TokensRecipient')` for the ERC777TokensRecipient interface. > `_implementer`: Contract implementing `_interfaceHash` for `_addr`. ### Get An Implementation Of An Interface For An Address Anyone MAY query the [ERC-1820] Registry to obtain the address of a contract implementing an interface on behalf of some address using the `getInterfaceImplementer` function. ``` solidity function getInterfaceImplementer(address _addr, bytes32 _interfaceHash) external view returns (address) ``` Query if an address implements an interface and through which contract. *NOTE*: If the last 28 bytes of the `_interfaceHash` are zeroes (`0`), then the first 4 bytes are considered an [ERC-165] interface and the registry SHALL forward the call to the contract at `_addr` to see if it implements the [ERC-165] interface (the first 4 bytes of `_interfaceHash`). The registry SHALL also cache [ERC-165] queries to reduce gas consumption. Anyone MAY call the `erc165UpdateCache` function to update whether a contract implements an interface or not. *NOTE*: The `_addr` MAY be `0`, then `msg.sender` is assumed. This default value is consistent with the behavior of the `setInterfaceImplementer` function and simplifies interactions via multisigs where the data of the transaction to sign is constant regardless of the address of the multisig instance. > **identifier:** `aabbb8ca` > **parameters** > `_addr`: Address being queried for the implementer of an interface. (If `_addr` is the zero address then `msg.sender` is assumed.) > `_interfaceHash`: keccak256 hash of the name of the interface as a string. E.g. `web3.utils.keccak256('ERC777Token')` > **returns:** The address of the contract which implements the interface `_interfaceHash` for `_addr` or `0` if `_addr` did not register an implementer for this interface. ### Interface Implementation (`ERC1820ImplementerInterface`) ``` solidity interface ERC1820ImplementerInterface { /// @notice Indicates whether the contract implements the interface `interfaceHash` for the address `addr` or not. /// @param interfaceHash keccak256 hash of the name of the interface /// @param addr Address for which the contract will implement the interface /// @return ERC1820_ACCEPT_MAGIC only if the contract implements `interfaceHash` for the address `addr`. function canImplementInterfaceForAddress(bytes32 interfaceHash, address addr) external view returns(bytes32); } ``` Any contract being registered as the implementation of an interface for a given address MUST implement said interface. In addition if it implements an interface on behalf of a different address, the contract MUST implement the `ERC1820ImplementerInterface` shown above. ``` solidity function canImplementInterfaceForAddress(bytes32 interfaceHash, address addr) external view returns(bytes32) ``` Indicates whether a contract implements an interface (`interfaceHash`) for a given address (`addr`). If a contract implements the interface (`interfaceHash`) for a given address (`addr`), it MUST return `ERC1820_ACCEPT_MAGIC` when called with the `addr` and the `interfaceHash`. If it does not implement the `interfaceHash` for a given address (`addr`), it MUST NOT return `ERC1820_ACCEPT_MAGIC`. > **identifier:** `f0083250` > **parameters** > `interfaceHash`: Hash of the interface which is implemented > `addr`: Address for which the interface is implemented > **returns:** `ERC1820_ACCEPT_MAGIC` only if the contract implements `ìnterfaceHash` for the address `addr`. The special value `ERC1820_ACCEPT_MAGIC` is defined as the `keccka256` hash of the string `"ERC1820_ACCEPT_MAGIC"`. ``` solidity bytes32 constant internal ERC1820_ACCEPT_MAGIC = keccak256(abi.encodePacked("ERC1820_ACCEPT_MAGIC")); ``` > The reason to return `ERC1820_ACCEPT_MAGIC` instead of a boolean is to prevent cases where a contract fails to implement the `canImplementInterfaceForAddress` but implements a fallback function which does not throw. In this case, since `canImplementInterfaceForAddress` does not exist, the fallback function is called instead, executed without throwing and returns `1`. Thus making it appear as if `canImplementInterfaceForAddress` returned `true`. ### Manager The manager of an address (regular account or a contract) is the only entity allowed to register implementations of interfaces for the address. By default, any address is its own manager. The manager can transfer its role to another address by calling `setManager` on the registry contract with the address for which to transfer the manager and the address of the new manager. **`setManager` Function** ``` solidity function setManager(address _addr, address _newManager) external ``` Sets `_newManager` as manager for `_addr`. The new manager will be able to call `setInterfaceImplementer` for `_addr`. If `_newManager` is `0x0`, the manager is reset to `_addr` itself as the manager. > **identifier:** `5df8122f` > **parameters** > `_addr`: Address for which to set the new manager. > `_newManager`: The address of the new manager for `_addr`. (Pass `0x0` to reset the manager to `_addr`.) **`getManager` Function** ``` solidity function getManager(address _addr) public view returns(address) ``` Get the manager of an address. > **identifier:** `3d584063` > **parameters** > `_addr`: Address for which to return the manager. > **returns:** Address of the manager for a given address. ## Rationale This standards offers a way for any type of address (externally owned and contracts) to implement an interface and potentially delegate the implementation of the interface to a proxy contract. This delegation to a proxy contract is necessary for externally owned accounts and useful to avoid redeploying existing contracts such as multisigs and DAOs. The registry can also act as a [ERC-165] cache in order to save gas when looking up if a contract implements a specific [ERC-165] interface. This cache is intentionally kept simple, without automatic cache update or invalidation. Anyone can easily and safely update the cache for any interface and any contract by calling the `updateERC165Cache` function. The registry is deployed using a keyless deployment method relying on a single-use deployment address to ensure no one controls the registry, thereby ensuring trust. ## Backward Compatibility This standard is backward compatible with [ERC-165], as both methods MAY be implemented without conflicting with each other. ## Test Cases Please check the [0xjac/ERC1820] repository for the full test suite. ## Implementation The implementation is available in the repo: [0xjac/ERC1820]. ## Copyright Copyright and related rights waived via [CC0](/LICENSE). [EIP-155]: ./eip-155.md [ERC-165]: ./eip-165.md [ERC-672]: https://github.com/ethereum/EIPs/issues/672 [ERC-820]: ./eip-820.md [ERC-1820]: ./eip-1820.md [ERC1820 registry smart contract]: https://github.com/0xjac/ERC1820/blob/master/contracts/ERC1820Registry.sol [erc1820-annoucement]: https://github.com/ethereum/EIPs/issues/820#issuecomment-464109166 [erc820-bug]: https://github.com/ethereum/EIPs/issues/820#issuecomment-452465748 [erc820-fix]: https://github.com/ethereum/EIPs/issues/820#issuecomment-454021564 [manager]: #manager [lookup]: #get-an-implementation-of-an-interface-for-an-address [ERC165 Cache]: #erc165-cache [Nick's article]: https://medium.com/@weka/how-to-send-ether-to-11-440-people-187e332566b7 [0xjac/ERC1820]: https://github.com/0xjac/ERC1820 [Nick]: https://github.com/Arachnid/ [William Entriken]: https://github.com/fulldecent [ENS]: https://ens.domains/

Universal Upgradeable Proxy Standard (UUPS)

Mon, 04 Mar 2019 00:00:00 +0000

## Simple Summary Standard upgradeable proxy contract. ## Abstract The following describes a standard for proxy contracts which is universally compatible with all contracts, and does not create incompatibility between the proxy and business-logic contracts. This is achieved by utilizing a unique storage position in the proxy contract to store the Logic Contract's address. A compatibility check ensures successful upgrades. Upgrading can be performed unlimited times, or as determined by custom logic. In addition, a method for selecting from multiple constructors is provided, which does not inhibit the ability to verify bytecode. ## Motivation - Improve upon existing proxy implementations to improve developer experience for deploying and maintaining Proxy and Logic Contracts. - Standardize and improve the methods for verifying the bytecode used by the Proxy Contract. ## Terminology - `delegatecall()` - Function in contract **A** which allows an external contract **B** (delegating) to modify **A**'s storage (see diagram below, [Solidity docs](https://solidity.readthedocs.io/en/v0.5.3/introduction-to-smart-contracts.html#delegatecall-callcode-and-libraries)) - **Proxy Contract** - The contract **A** which stores data, but uses the logic of external contract **B** by way of `delegatecall()`. - **Logic Contract** - The contract **B** which contains the logic used by Proxy Contract **A** - **Proxiable Contract** - Inherited in Logic Contract **B** to provide the upgrade functionality ![](../assets/eip-1822/proxy-diagram.png) ## Specification The Proxy Contract proposed here should be deployed _as is_, and used as a drop-in replacement for any existing methods of lifecycle management of contracts. In addition to the Proxy Contract, we propose the Proxiable Contract interface/base which establishes a pattern for the upgrade which does not interfere with existing business rules. The logic for allowing upgrades can be implemented as needed. ### Proxy Contract #### Functions ##### `fallback` The proposed fallback function follows the common pattern seen in other Proxy Contract implementations such as [Zeppelin][1] or [Gnosis][2]. However, rather than forcing use of a variable, the address of the Logic Contract is stored at the defined storage position `keccak256("PROXIABLE")`. This eliminates the possibility of collision between variables in the Proxy and Logic Contracts, thus providing "universal" compatibility with any Logic Contract. ```javascript function() external payable { assembly { // solium-disable-line let contractLogic := sload(0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7) calldatacopy(0x0, 0x0, calldatasize) let success := delegatecall(sub(gas, 10000), contractLogic, 0x0, calldatasize, 0, 0) let retSz := returndatasize returndatacopy(0, 0, retSz) switch success case 0 { revert(0, retSz) } default { return(0, retSz) } } } ``` #### `constructor` The proposed constructor accepts any number of arguments of any type, and thus is compatible with any Logic Contract constructor function. In addition, the arbitrary nature of the Proxy Contract's constructor provides the ability to select from one or more constructor functions available in the Logic Contract source code (e.g., `constructor1`, `constructor2`, ... etc. ). Note that if multiple constructors are included in the Logic Contract, a check should be included to prohibit calling a constructor again post-initialization. It's worth noting that the added functionality of supporting multiple constructors does not inhibit verification of the Proxy Contract's bytecode, since the initialization tx call data (input) can be decoded by first using the Proxy Contract ABI, and then using the Logic Contract ABI. The contract below shows the proposed implementation of the Proxy Contract. ```javascript contract Proxy { // Code position in storage is keccak256("PROXIABLE") = "0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7" constructor(bytes memory constructData, address contractLogic) public { // save the code address assembly { // solium-disable-line sstore(0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7, contractLogic) } (bool success, bytes memory _ ) = contractLogic.delegatecall(constructData); // solium-disable-line require(success, "Construction failed"); } function() external payable { assembly { // solium-disable-line let contractLogic := sload(0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7) calldatacopy(0x0, 0x0, calldatasize) let success := delegatecall(sub(gas, 10000), contractLogic, 0x0, calldatasize, 0, 0) let retSz := returndatasize returndatacopy(0, 0, retSz) switch success case 0 { revert(0, retSz) } default { return(0, retSz) } } } } ``` ### Proxiable Contract The Proxiable Contract is included in the Logic Contract, and provides the functions needed to perform an upgrade. The compatibility check `proxiable` prevents irreparable updates during an upgrade. > :warning: Warning: `updateCodeAddress` and `proxiable` must be present in the Logic Contract. Failure to include these may prevent upgrades, and could allow the Proxy Contract to become entirely unusable. See below [Restricting dangerous functions](#restricting-dangerous-functions) #### Functions ##### `proxiable` Compatibility check to ensure the new Logic Contract implements the Universal Upgradeable Proxy Standard. Note that in order to support future implementations, the `bytes32` comparison could be changed e.g., `keccak256("PROXIABLE-ERC1822-v1")`. ##### `updateCodeAddress` Stores the Logic Contract's address at storage `keccak256("PROXIABLE")` in the Proxy Contract. The contract below shows the proposed implementation of the Proxiable Contract. ```javascript contract Proxiable { // Code position in storage is keccak256("PROXIABLE") = "0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7" function updateCodeAddress(address newAddress) internal { require( bytes32(0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7) == Proxiable(newAddress).proxiableUUID(), "Not compatible" ); assembly { // solium-disable-line sstore(0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7, newAddress) } } function proxiableUUID() public pure returns (bytes32) { return 0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7; } } ``` ## Pitfalls when using a proxy The following common best practices should be employed for all Logic Contracts when using a proxy contract. ### Separating Variables from Logic Careful consideration should be made when designing a new Logic Contract to prevent incompatibility with the existing storage of the Proxy Contract after an upgrade. Specifically, the order in which variables are instantiated in the new contract should not be modified, and any new variables should be added after all existing variables from the previous Logic Contract To facilitate this practice, we recommend utilizing a single "base" contract which holds all variables, and which is inherited in subsequent logic contract(s). This practice greatly reduces the chances of accidentally reordering variables or overwriting them in storage. ### Restricting dangerous functions The compatibility check in the Proxiable Contract is a safety mechanism to prevent upgrading to a Logic Contract which does not implement the Universal Upgradeable Proxy Standard. However, as occurred in the parity wallet hack, it is still possible to perform irreparable damage to the Logic Contract itself. In order to prevent damage to the Logic Contract, we recommend restricting permissions for any potentially damaging functions to `onlyOwner`, and giving away ownership of the Logic Contract immediately upon deployment to a null address (e.g., address(1)). Potentially damaging functions include native functions such as `SELFDESTRUCT`, as well functions whose code may originate externally such as `CALLCODE`, and `delegatecall()`. In the [ERC-20 Token](#erc-20-token) example below, a `LibraryLock` contract is used to prevent destruction of the logic contract. ## Examples ### Owned In this example, we show the standard ownership example, and restrict the `updateCodeAddress` to only the owner. ```javascript contract Owned is Proxiable { // ensures no one can manipulate this contract once it is deployed address public owner = address(1); function constructor1() public{ // ensures this can be called only once per *proxy* contract deployed require(owner == address(0)); owner = msg.sender; } function updateCode(address newCode) onlyOwner public { updateCodeAddress(newCode); } modifier onlyOwner() { require(msg.sender == owner, "Only owner is allowed to perform this action"); _; } } ``` ### ERC-20 Token #### Proxy Contract ```javascript pragma solidity ^0.5.1; contract Proxy { // Code position in storage is keccak256("PROXIABLE") = "0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7" constructor(bytes memory constructData, address contractLogic) public { // save the code address assembly { // solium-disable-line sstore(0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7, contractLogic) } (bool success, bytes memory _ ) = contractLogic.delegatecall(constructData); // solium-disable-line require(success, "Construction failed"); } function() external payable { assembly { // solium-disable-line let contractLogic := sload(0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7) calldatacopy(0x0, 0x0, calldatasize) let success := delegatecall(sub(gas, 10000), contractLogic, 0x0, calldatasize, 0, 0) let retSz := returndatasize returndatacopy(0, 0, retSz) switch success case 0 { revert(0, retSz) } default { return(0, retSz) } } } } ``` #### Token Logic Contract ``` javascript contract Proxiable { // Code position in storage is keccak256("PROXIABLE") = "0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7" function updateCodeAddress(address newAddress) internal { require( bytes32(0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7) == Proxiable(newAddress).proxiableUUID(), "Not compatible" ); assembly { // solium-disable-line sstore(0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7, newAddress) } } function proxiableUUID() public pure returns (bytes32) { return 0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7; } } contract Owned { address owner; function setOwner(address _owner) internal { owner = _owner; } modifier onlyOwner() { require(msg.sender == owner, "Only owner is allowed to perform this action"); _; } } contract LibraryLockDataLayout { bool public initialized = false; } contract LibraryLock is LibraryLockDataLayout { // Ensures no one can manipulate the Logic Contract once it is deployed. // PARITY WALLET HACK PREVENTION modifier delegatedOnly() { require(initialized == true, "The library is locked. No direct 'call' is allowed"); _; } function initialize() internal { initialized = true; } } contract ERC20DataLayout is LibraryLockDataLayout { uint256 public totalSupply; mapping(address=>uint256) public tokens; } contract ERC20 { // ... function transfer(address to, uint256 amount) public { require(tokens[msg.sender] >= amount, "Not enough funds for transfer"); tokens[to] += amount; tokens[msg.sender] -= amount; } } contract MyToken is ERC20DataLayout, ERC20, Owned, Proxiable, LibraryLock { function constructor1(uint256 _initialSupply) public { totalSupply = _initialSupply; tokens[msg.sender] = _initialSupply; initialize(); setOwner(msg.sender); } function updateCode(address newCode) public onlyOwner delegatedOnly { updateCodeAddress(newCode); } function transfer(address to, uint256 amount) public delegatedOnly { ERC20.transfer(to, amount); } } ``` ## References - ["Escape-hatch" proxy Medium Post](https://medium.com/terminaldotco/escape-hatch-proxy-efb681de108d) ## Copyright Copyright and related rights waived via [CC0](/LICENSE). [1]: https://github.com/maraoz/solidity-proxy/blob/master/contracts/Dispatcher.sol [2]: https://blog.gnosis.pm/solidity-delegateproxy-contracts-e09957d0f201

ENS Interface Discovery

Fri, 15 Mar 2019 00:00:00 +0000

## Simple Summary Defines a method of associating contract interfaces with ENS names and addresses, and of discovering those interfaces. ## Abstract This EIP specifies a method for exposing interfaces associated with an ENS name or an address (typically a contract address) and allowing applications to discover those interfaces and interact with them. Interfaces can be implemented either by the target contract (if any) or by any other contract. ## Motivation EIP 165 supports interface discovery - determining if the contract at a given address supports a requested interface. However, in many cases it's useful to be able to discover functionality associated with a name or an address that is implemented by other contracts. For example, a token contract may not itself provide any kind of 'atomic swap' functionality, but there may be associated contracts that do. With ENS interface discovery, the token contract can expose this metadata, informing applications where they can find that functionality. ## Specification A new profile for ENS resolvers is defined, consisting of the following method: ```solidity function interfaceImplementer(bytes32 node, bytes4 interfaceID) external view returns (address); ``` The EIP-165 interface ID of this interface is `0xb8f2bbb4`. Given an ENS name hash `node` and an EIP-165 `interfaceID`, this function returns the address of an appropriate implementer of that interface. If there is no interface matching that interface ID for that node, 0 is returned. The address returned by `interfaceImplementer` MUST refer to a smart contract. The smart contract at the returned address SHOULD implement EIP-165. Resolvers implementing this interface MAY utilise a fallback strategy: If no matching interface was explicitly provided by the user, query the contract returned by `addr()`, returning its address if the requested interface is supported by that contract, and 0 otherwise. If they do this, they MUST ensure they return 0, rather than reverting, if the target contract reverts. This field may be used with both forward resolution and reverse resolution. ## Rationale A naive approach to this problem would involve adding this method directly to the target contract. However, doing this has several shortcomings: 1. Each contract must maintain its own list of interface implementations. 2. Modifying this list requires access controls, which the contract may not have previously required. 3. Support for this must be designed in when the contract is written, and cannot be retrofitted afterwards. 4. Only one canonical list of interfaces can be supported. Using ENS resolvers instead mitigates these shortcomings, making it possible for anyone to associate interfaces with a name, even for contracts not previously built with this in mind. ## Backwards Compatibility There are no backwards compatibility issues. ## Test Cases TBD ## Implementation The PublicResolver in the [ensdomains/resolvers](https://github.com/ensdomains/resolvers/) repository implements this interface. ## Copyright Copyright and related rights waived via [CC0](/LICENSE).