Skip to content

Latest commit

 

History

History
67 lines (44 loc) · 3.92 KB

eip-0025.md

File metadata and controls

67 lines (44 loc) · 3.92 KB
Raw

EIP-0025: URI scheme for payment requests

  • Author: MrStahlfelge, Aberg
  • Created: 14-Dec-2021
  • License: CC0
  • Forking: not needed

Motivation

Like BIP-0021 for Bitcoin, this EIP proposes a URI scheme for initiating payments.

The purpose of this URI scheme is to enable users to easily make payments by simply clicking links on webpages or in e-mails.

In difference to Ergo Pay (EIP-0020), this URI scheme does not contain a prepared transaction that the wallet should sign or discard. Instead, it contains the data that the wallet application should use to fill its payment form. The user can change the details when needed. The wallet will build the transaction, so this scheme is easier to handle on static websites or in e-mails.

Format

ergourn            = "ergo:" ergoaddress [ "?" ergoparams ]
ergoaddress        = *base58
ergoparams         = ergoparam [ "&" ergoparams ]
ergoparam          = [ amountparam / labelparam / descriptionparam / tokenparam ]
amountparam        = "amount=" *digit [ "." *digit ]
labelparam         = "label=" *qchar
descriptionparam   = "description=" *qchar
tokenparam         = "token-" qchar *qchar "=" *digit [ "." *digit ]
  • label: Label for that address (e.g. name of recipient). This can be used for when saving to an address book, for example
  • address: Ergo P2PK or P2S address
  • description: Message that describes the transaction to the user

Amount

If an amount is provided, it MUST be specified in decimal ERG. All amounts MUST contain no commas and use a period (.) as the separating character to separate whole numbers and decimal fractions. I.e. amount=50.00 or amount=50 is treated as 50 ERG, and amount=50,000.00 is invalid.

Tokens

If a token parameter is provided, it specifies the token id and the desired amount separated by an equals sign. The amount must be specified in decimal token value, for example "3.45" for 3.45 SigUSD. The amount MUST contain no commas and use a period (.) as the separating character to separate whole numbers and decimal fractions.

In the case of sending only tokens, a minimum amount of ERGs MUST also be sent to a new box (it is not possible to create boxes containing tokens only with zero ERGs).

The wallet should process the URI as long as it can parse and interpret the content unambiguously. Any ambiguity should be detected and if it cannot be resolved, the wallet should give a descriptive message to the user (not just "Invalid URI", but what exactly has been detected as invalid).

At the same time the wallet should not do anything implicitly, even if it is smart enough to so some implicit actions, it should display what is going on to the user on the transaction sending screen. The user should be aware that some implicit actions were taken by wallet and that those actions will take effect when the transaction is sent.

Applying the above principles to the missing ERGs amount parameter problem we can see that it can be automatically resolved by the wallet, so the wallet shouldn't reject the URI as invalid when the amount of ERGs is missing. At the same time, the screen should have an explanation that non-zero amount of ERGs in the field is required and that it was suggested by the wallet.

For the case of duplicate tokens, the wallet CAN consider such URI as invalid, and clearly communicate the problem to the user so that the user can take a screenshot and send it back to the URI author. The duplication problem should be clear from the screenshot.

Examples

 ergo:9ewA9T53dy5qvAkcR5jVCtbaDW2XgWzbLPs5H4uCJJavmA4fzDx

 ergo:9ewA9T53dy5qvAkcR5jVCtbaDW2XgWzbLPs5H4uCJJavmA4fzDx?amount=1.0&description=Hard%20work

requests 1 ERG for hard work

 ergo:9ewA9T53dy5qvAkcR5jVCtbaDW2XgWzbLPs5H4uCJJavmA4fzDx?token-03faf2cb329f2e90d6d23b58d91bbb6c046aa143261cc21f52fbe2824bfcbf04=5

requests 5 SigUSD