EIP: Payment request URL specification

[nagydani]

Payment request URL specification for QR codes, hyperlinks and Android Intents.

[chriseth]

Kindly inviting @ligi @tayvano to this discussion (please also add other wallet developers).

[ligi]

Great to see work on a proper specification! Just have 2 concerns currently after reading it initially:

• the token-transfer method is different from ERC-67 (ERC: Standard URI scheme with metadata, value and byte code  #67) and as ERC-67 is now already reality out there we would need to do some ugly code to distinguish between ERC-67 and this new approach - I also do not yet see any advantage of this new way of doing things
• the use of decimals - this way we need to read from contracts to build a transaction. This will be a problem e.g. in offline use-cases (e.g. when building transactions with hardware like wallets - http://walleth.org/2017/06/12/offline-transactions )

This just as some initial thoughts - will think deeper about this later today.

cc @kumavis , @manuelsc , @alexvandesande , @jbenet , @prusnak

[tayvano]

About a year ago I was all for including data in the URI / QR codes / and so forth.

I'm not as for it, but I think it's a necessary thing to include. I think that it should come with a very, very large red warning to wallets that if you accept data via URI, you need warn the user about the potential downsides to this (e.g. a malicious data string could send all your tokens).

For example, we parse the signed transaction and show users, so sending a standard ERC-20 token would show "sending 1 GNT" over "sending 0 ETH". Some others do not, and show "sending 0 ETH to 0x2342342, sometimes without mention of data. I'm sure there are other potential malicious use-cases that I haven't thought of. The overall userbase today is much different than 6 months ago, 1 year ago. Do not overestimate them. 😉

---

This is what MEW currently does

This is not saying it's the correct way, simply what we currently use. The data and possible gas limit do not currently work due to ENS revisions, its never been a widely used or promoted feature, so I urge you to take this with a grain of salt as your progress. However, these keys match the raw / unsigned tx (found at bottom of this wall of text), which is a obvious benefit.

• to = address, preferably prefixed with 0x

• value = amount of ETH to send in ETH or tokens to send or ETC to send or whatever. (not WEI, IMO. It will lead to more confusion than it's worth and is the input that most UIs take as it is. Keep in mind—as a wallet provider we don't just send this TX off. We parse it, check it, and fill it in for the user, and let them review and look at fields before they take the action to send.) This warrants more thought. I'm pretty up in the air at this point.

• gas & gasLimit = amount of gas

• gasPrice = gas price in wei

• data = hex data

• chainId = we don't yet include this, but would be smart to do so.

No fields are mandatory. Obviously, not really that useful if you don't include some things, but whatever. You never know what the use case would be. Maybe someone wants to show someone how to send a message to whatever address with data string. Maybe they just want to ensure the user sets a gasPrice of 60 GWEI bc there is a token sale going on. Leave it up to the people providing these QR codes to provide what is necessary.

That said, exchanges / wallets / shops that are building these URIs / QR codes should be discouraged from including any unnecessary data. e.g. in 99% of cases, including gasLimit is overkill and they should opt for the wallet to handle it. 99% of use cases will likely be to and value. For those 1% of cases, having the ability to set the gasLimit will be nice.

Example of a URI that used to work on MEW:

https://www.myetherwallet.com/?to=0x7cB57B5A97eAbe94205C07890BE4c1aD31E486A8&value=1&gaslimit=23000&data=0x5468616e6b20796f752c204d455720322e30

---

Tokens

There are a few ways to handle this:

• Provide the token address, token decimals, and token symbol (although the latter may give user a false sense of security, as I could likely send malicious URI with GNT tokens labeled as SHIT tokens)

• Provide symbol and if the wallet provider has a match, use that. If not, UI throws error.

• ???

Regardless, should have a key that aligns to value ERC20 that people are strongly encouraged to use when construction token transactions. This will be a pain to handle if we have a different ERC later and we don't do this now.

---

Contracts

We have been speaking with Matt @ Etherscan about contracts. It would be super freaking cool if there was a was for a user to click a link from Etherscan that had the specific (e.g. one function) loaded up in the user's wallet, where the user could then interact with the write functions in a given contract. In that case:

• contractAddr — address of contract that you would want to interact with.

• contractAbi — not the full abi, just the one function, base64'd or something URL-proof in order to eliminate any weirdness.

• value, gaslimit, and so forth would be as described above.

This is slightly unrelated but figured I would include this anyways. Totally probably best to ignore this :P

---

Raw / Signed Transactions

And now we are really off topic but if we are going to discuss QR codes, someone speak up if there is a better way than just throwing the full signed / unsigned TX data in a QR code. Potential issues:

• QR code can be too dense / large if TX has a super long data string (kumavis had recommendation to have QR gif spec. Don't think it's necessary but if anyone is bored, would love to see a POC of this for curiosity's sake.)

• Malicious third party intercepts unsigned transaction and mutates it in some way. Should be solvable with strong confirmation dialog but worth considering. Checksum?

• Should we have a label / key in it at least to ID it?

Above 2 maybe as separate EIP to keep this one super focused

---

Reference: a raw (unsigned) TX:

{ 
"nonce":"0x0174",
"gasPrice":"0x3b9aca00",
"gasLimit":"0x5208", 
"to":"0x7cB57B5A97eAbe94205C07890BE4c1aD31E486A8", 
"value":"0x0de0b6b3a7640000", 
"data":"", 
"chainId":1
}

---

Final Thoughts

• I would opt for keeping the same keys across transactions & URIs / QR codes. Consistency = good. From a wallet's perspective, those fields are already very familiar. It would surprise me if an exchange wasn't familiar with this as well.

• I see no reason for splitting Ethereum, token contract address, and beneficiary addresses in that manner. There is one address you are sending to: the receiver. The token address would only be used in the case you are providing a reference to the token you want sent, in which case you must at least include decimals too.

• While I understand the rationale for matching whatever is going on in Bitcoin-land, if people are constructing QR codes for ETH, it should be assumed that they have a basic understanding of ETH, namely the core underlying transactions. I would prioritize making this easy and foolproof for wallets and UIs that will be preventing users from sending their life savings away accidentally. I would like to hear others' thoughts on this (Jaxx? Exodus? Coinbase? Shapeshift?). I don't really do Bitcoin at that level).

• I have no opinion on camelCase vs underscore_all_the_things vs dash-the-fuckers

• Users do like to touch URI strings and QR codes and construct them themselves in certain cases (e.g. "send me some eth, bro!"). Demanding / expecting these URIs to be in hex / WEI has potential downsides for that reason.

[prusnak]

Agree that decimals should be killed with fire :-)

[axic]

I think it would be nice to require the checksummed address format.

[MicahZoltu]

Style: Recommend not including hard-line breaks in prose text. As is, it is a bit of a pain to read on a 1900px wide window (split diff), and similarly hard to read on a phone.

[MicahZoltu]

I agree with @tayvano that we shouldn't be striving for bitcoin similarity. I see minimal value in such similarities and it constrains design decisions.

I think if we are going to use ethereum: it should be generic, not specific to token/ETH transfers. Of course, it would support token and ETH transfers but it would also support any arbitrary contract calls just the same. Also, I think long term ERC20 isn't going to stand the test of time (at least I sincerely hope it doesn't) so we shouldn't be designing the ethereum: URL against it.

This means that the pieces of information that should be included are:

• source address
• target address
• attached value
• method signature being called
• list of parameters to pass to the method
• gas
• gas price

As @tayvano indicated, most of these things will be left out in most calls but I think there is value in allowing the caller to specify any subset of them.

Another thing that I strongly recommend is some form of protocol versioning. While the above list makes sense now, Ethereum is still very young and the set above may not make sense in a year or two. For example, there has been discussion about changing ETH to no longer be special and instead be a traditional token. If this were to go through, then attached value would no longer make sense as a parameter. Similarly, changes may be made to the protocol that allow for new transaction parameters.

A simple means of versioning would be to have the version be the first segment like ethereum:v5/....

Re @tayvano's suggestion to denominate in ETH, not WEI. I quite strongly disagree with this. While it is nice when a URI is semi-readable, the intent is not to make them user friendly, especially when it introduces risk into the system. If values are denominated in ETH then that means many transactions will contain fractional ETH. It is incredibly easy to get the parsing wrong and parse the URI into a double/float and accidentally truncate it! On top of that, the receiving system will need to send that number as WEI anyway so you are just making their life hard. The sending system also probably is using WEI under the hood (at least I hope they are), so both systems are having to convert to/from ETH/WEI and deal with the fact that you need a 300-bit (or something) floating point number to accurately store ETH (and any token with "decimals").

[tayvano]

After sleeping on it.......

• WEI not ETH works better for a variety of reasons. I don't necessarily like this, but it removes a lot of unnecessary complexity and bad things

• ENS support is question as well (especially .eth vs .company.eth etc.

[ligi]

Really not sure about adding ENS here - and if we really add it here IMHO it should be at least prefixed because:

• otherwise it is not 100% clear if it is an address or an ENS name in all cases - you could assume that if the length is 40 chars it is an address - but it could also be an ENS name - a prefix would make this clear and remove the need for assumptions like this
• It is too tightly coupled to ENS and we might end up with other name-services in the future as ENS suffers a serious squatting problem
• same problem as with decimals: to build a transaction we need to be online to resolve the name to an address - this is a problem for offline/hardware wallet solutions

[nagydani]

I think that this is a higher-level protocol than the one in ERC #67 and it is really unfortunate that they use the same protocol name. I am willing to change it to something else. @fjl proposed ethpay: to which the two objections are that it suggests that payments are in ETH (though it is actually a reference to the blockchain, not its native token) and that not all token transfers are strictly speaking payments. I am still willing to go with ethpay: despite these two objections.

[ligi]

why does it require ERC-67?

[nagydani]

You are right, it should not be required. It is merely referenced.

[nagydani]

To highlight that the purpose of this URL format is different from that in ERC #67 and to remain compatible with it, I have changed the ethereum protocol name to ethpay as suggested by @fjl . This also implies, that this standard

I am very hesitant to switch to WEI (and atomic units in general) as suggested, because human readability and writability are very important. More important than the offline use case, which should be handled though ERC #67 links, as those also help with gasprice and other low-level stuff, which cannot be decided safely offline anyway.

[ligi]

because human readability and writability are very important.

can you elaborate on why you think these are important in this case. Would also appreciate some use-cases

[nagydani]

@ligi basically, this ERC is to provide the same functionality as BIP21. People write BIP21 links and QR-codes by hand all the time. The standard, most anticipated and most important use case is that the user clicks (scans, etc.) such a link, it brings up their wallet app asking for confirming the payment. In this case, the wallet needs to know about decimals anyway in order to display a meaningful message to the user. Thus, no matter if the value in the URL is in decimal representation or in atomic units, the wallet app needs to have access to the contract to convert between the two.

[ligi]

People write BIP21 links and QR-codes by hand all the time.

Can you support this claim with data? Would also love the input of @schildbach in this regard.

[Arachnid]

I disagree about wei vs ETH - URIs are supposed to be human readable, and decimal ETH is far more readable for practical purposes. This is not a machine interchange standard, but rather a human one.

otherwise it is not 100% clear if it is an address or an ENS name in all cases - you could assume that if the length is 40 chars it is an address - but it could also be an ENS name - a prefix would make this clear and remove the need for assumptions like this

I promise we'll never issue 42 character TLDs starting with 0x.

It is too tightly coupled to ENS and we might end up with other name-services in the future as ENS suffers a serious squatting problem

You are welcome to invent your own squatting-free name service and then submit a proposal to add support for it to a standard like this.

same problem as with decimals: to build a transaction we need to be online to resolve the name to an address - this is a problem for offline/hardware wallet solutions

I would not expect offline or hardware wallets to parse these URIs themselves, though - they would get a transaction in ready-to-sign form from something online.

[nagydani]

@tayvano , I disagree with you that using WEI would save complexity and bad things. Please read our discussion with @ligi above; in both cases, the user-facing app will need to do a conversion for which it will need to access the contract in case of token payments. It would, however, make it near-impossible and highly error-prone for human beings to construct payment request URLs, should they require amounts in WEI.

@ligi , I obviously have no data, but I have seen it done many times and regularly do it myself. Whenever I invoice in BTC, I include a bitcoin:... link and a QR code in the email as a courtesy in addition to simply stating my address and the invoiced amount.

[prusnak]

If you really NEED to include decimal point in the URI, please include decimals as well (so the offline signer, does not need to interact with blockchain to get the correct value for a token).

Something like the following could work:

?amount=1.2345&decimals=18

[ligi]

You are welcome to invent your own squatting-free name service and then submit a proposal to add support for it to a standard like this.

OK - so we need the prefix - I don't think it will be me as I am busy with other projects currently - but we need an upgrade path here - and this is what I was stating in the original comment

I promise we'll never issue 42 character TLDs starting with 0x.

Is there anything in code that prevents it?

EDIT: with registrar.ens.domains I am at least able to spend money on a domain that is a valid address (https://etherscan.io/tx/0x5262ed605bb4c924ae627b38b26db4066c097d346f1d262d2e97011858bf5b65) - but then it is just buggy - I don't see the bids anymore and the 0.01ETH are just wasted - the ens-bids-backup does not contain the bid ..
Let's just leave ENS out - or at least prefix it

[tayvano]

FWIW, MEW doesn't allow any ENSs names to be registered that start with 0x and there are issues with having strings that start with 0x that aren't hex.

Adjusting ENS to address 42 char / 0x is relatively easy thing to do. This is not to say that more consideration & discussion isn't warranted, but let's eliminate the technical feasibility from the discussion.

ENS meetup / panels / discussions are on Aug 11-14.

I am for moving discussion of ENS to new EIP in order to keep it focused & moving.

[MicahZoltu]

URIs are supposed to be human readable, and decimal ETH is far more readable for practical purposes. This is not a machine interchange standard, but rather a human one.

@Arachnid I don't agree with this assessment (and this is probably the source of disagreement in general on this topic). The purpose of a URI is to make it easy for application A to talk to application B. If they are human readable that is a nice advantage, but if you look at most URIs on the internet, that isn't a primary concern. Even Google's URIs which include the URI encoded query string in them also include a bunch of crap that I still don't fully understand even though I am often fiddling with them manually. IMO, the purpose of this spec (and #67) is to facilitate data transfer between applications. I do not think we should be targeting manually constructed URIs or human read URIs. It is the job of the tool on either end to present the data to the user in a user friendly way.

In the case of eth vs attoeth, I have personally seen too many errors around parsing values into JavaScript doubles to be comfortable with anything other than hex encoded values. Just the other day some ICO lost millions of dollars due to this bug (don't remember the name). If the values are hex encoded they aren't human readable, and its much easier to encode/parse a 256-bit hex integer than a 300-bit (depending on decided mantisa size) floating point value.

[nagydani]

@MicahZoltu , I disagree. What you write is true about ERC #67 , but not this ERC. It is important that payment requests be readable and writeable by humans; we know that much from Bitcoin (BIP21).

[ligi]

we know that much from Bitcoin

no - you assume this and I have not yet seen any data that supports this.
Also in your introductional post you state it is for also for Android Intents - and they are never really hand-crafted or parsed - same goes for QR codes you mention there ..

[nagydani]

@ligi if I see something left and right, I do not need "data" to prove that it occurs sufficiently frequently. Android intents get fired automagically upon opening URLs, and those URLs are often hand-crafted in case of BTC payment requests (in emails and chats, for example). Generating a QR-code from a hand-crafted URL is also something for which there are many on- and offline tools. I really doubt that everybody except me uses specialized bitcoin QR code generators instead of simply hand-crafting a URL and using whatever QR code generator is at hand.

[ligi]

I strongly disagree - and I think it all boils down to who you see as the target audience. Everyday humans (who I see as the future target audience for Ethereum and maybe this EIP) will not hand-craft a URL - they will use tools for this. Hand-crafting URLs will only be done by done by tech-savvy people - and I hope we overcome the time where cryptocurrencies are only used by us ..
This is also why I asked for use-cases in the beginning which you just ignored - so here are some that come to my mind:

• Displaying QR-Codes on POS terminals - if you pay via this QR-Code the cashier hands you out the item you just paid for (no hand-crafted URL)
• Printing QR-Codes on bills - if you pay via this QR-Code you can just leave e.g. the restaurant (no hand-crafted URL)
• Requesting money from an Android-App (no hand-crafted URL)
• Displaying QR-Codes on Vending machines - if you pay via this QR-Code the item is released (no hand-crafted URL)
• Requesting money from a wallet app (like you see in the last screenshot here: http://walleth.org/2017/05/23/walleth-0.11/) - (no hand-crafted URL)
• Attaching a QR-Code to an object/venue/.. to collect donations
• Showing a QR-Code at a door/turnstile - if you pay you get access (no hand-crafted URL)
• Showing a QR-Code on the info-screen of a ransom-ware - if you pay via this URL your data might get decrypted (no hand-crafted URL)
• Showing a QR-Code at a Music-Box - so you can choose the music (no hand-crafted URL)
• Showing a QR-Code with a transaction to be signed by a offline device (like this: http://walleth.org/2017/06/12/offline-transactions) (no hand-crafted URL)
• Showing a QR-Code in front of a pay-wall - if you pay via this URL you can read the article or view the video (no hand-crafted URL)
• Showing a QR-Code next to a power-outlet or charging station - if you pay via this URL power is switched on for a certain amount of time (no hand-crafted URL)
• Showing a QR-Code to convert tokens (e.g. like shapeshift is doing) - (no hand-crafted URL)
• ..

QR-Code could also be replaced with NFC/Bluetooth solutions - same applies

[ligi]

yea - but they have other problems than missing 681 ..

Anyway this goes way out of topic. They could easily implement it - not sure why they don't. Guess they are busy fighting x-code and trying to get their apps in the store. Really sad people waste their time this way.

[masterial]

5 major wallets (trust, imtoken, toshi, cypher, blockchain). none have support. seriously, WTF am I missing here?

[ligi]

yes I also think we need more support in general: https://ethereum-magicians.org/t/we-need-more-support-for-erc-681/897
@vikmeup told me trust should support it soon - but this is also already a while ago ..
Write to your favorite wallets and demand it! Android wallets can also use this lib: https://github.com/walleth/kethereum/tree/master/erc681 - could even be used on iOS - but not that easily out of the box - but again - why would you waste your time with iOS anyway.

[masterial]

dude, i can't just tell my customers to use android. they tell me what they use. i also did write to them today. this is kind the most important feature of ethereum. they will probably implement it eventually. but once again, wtf? also seems like QR does not even work on Trust anymore for regular send input. unbelievable.

[skywinder]

@ligi Challenge accepted! We will do that in ETHBerlin! 🔥
Keep in touch!

[brunobar79]

Hey guys, just wanted to share two tools here that might be useful for people trying to implement this on their end:

• eth-url-parser - JS module that handles parsing and building ethereum standard urls

• link generator - Web app that allows you to generate valid ethereum links (and it's corresponding QR code)

Note: I wrote both in a rush so please lmk if you find any issues with it (or even better submit a PR and fix it!)

[ligi]

I am really puzzled upon this commit:
ab76063

It breaks compatibility and I really do not see any advantage of it being there except for improved human readability. I signal removing this.

[dwjorgeb]

Hello guys. I'm sorry for digging this up, but I have a serious doubt with this.

For ERC-20 tokens, such as USDT, which has 6 decimals, to request 1.5 USDT, the payment URI whould look something like this, right?

ethereum:0xdAC17F958D2ee523a2206206994597C13D831ec7/transfer?address=0x8e23ee67d1332ad560396262c48ffbb01f93d052&uint256=1.5e6

However, when I parse that with MetaMask, it shows 1.5 million USDT to send, which makes no sense.

In order to make it parse 1.5 USDT I'd have to put the URI as

ethereum:0xdAC17F958D2ee523a2206206994597C13D831ec7/transfer?address=0x8e23ee67d1332ad560396262c48ffbb01f93d052&uint256=1.5

which makes even less sense, since it's an uint, shouldn't even accept decimal numbers.

I went through this entire thread, but I couldn't come to a conclusion how are we supposed to handle decimals?

Is MetaMask's implementation wrong, or am I doing something wrong?

Thanks

@ligi @nagydani @Arachnid

[ligi]

sounds like the MM implementation is wrong there - seems to assume 18 decimals where it is only 6

[dwjorgeb]

sounds like the MM implementation is wrong there - seems to assume 18 decimals where it is only 6

no, even worse, it assumes the value as the main denomination, not atomic units.

uint256=1.5 is parsed as 1.5 USDT
uint256=1000000 (which should be parsed as 1 USDT) is parsed as 1.000.000 USDT

[ligi]

yea this is wrong. Please report upstream. Is this in the mobile wallet or the browser plugin?

[dwjorgeb]

yea this is wrong. Please report upstream. Is this in the mobile wallet or the browser plugin?

Android app

[php4fan]

I see here: #67
that EIP 67 was superseded by this one. However, that one talked about providing the bytecode data, as opposed to the readable format (method name plus type-value pairs for parameters) specified by this one. Both are useful and necessary, and I don't see the first one implemented here. Am I missing something??

[MicahZoltu]

There is no EIP-67. #67 is just an idea for an EIP that never actually made it to a standard.

[matteosistisette]

I know, but I've seen it informally called "eip 67" all over the place.
That doesn't change the substance of my question.

[MicahZoltu]

You probably want to continue this over at the discussions-to for this EIP. It can be found at the top of the EIP at https://eips.ethereum.org/EIPS/eip-681

[Abubakar672]

Hi Guys, Sorry for digging up the conversation again, I need to build a QR code that can have the account address and only the data in it the amount can be entered by the user itself or i can add it in the QR code too. Can someone tell me is there any standard to do this. Or is that even possible to have this type of QR code that can be readable by the different mobile crypto wallet like metamask and trust wallet. Like they read all data address, data and the amount

[melonges]

Hi Guys, Sorry for digging up the conversation again, I need to build a QR code that can have the account address and only the data in it the amount can be entered by the user itself or i can add it in the QR code too. Can someone tell me is there any standard to do this. Or is that even possible to have this type of QR code that can be readable by the different mobile crypto wallet like metamask and trust wallet. Like they read all data address, data and the amount

few wallets support this at the moment