Skip to main content

EVER payment link (TIP-5.1)

Abstract​

This TIP proposes a URI scheme for making EVER payments.

Motivation​

Payment URIs has become widely adopted since the introduction of Bitcoin’s improvement proposals BIP-20, 21, 70, 71, and 72. For instance, most modern mobile wallets support the scanning of QR codes containing encoded bitcoin payment links.

The purpose of this URI scheme is to enable users to easily make payments in EVER by simply clicking links on web pages or scanning QR Codes.

Specification​

The keywords "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.

All symbols in the payment link MUST be encoded following the guidelines set out in RFC 3986.

General rules for handling​

Everscale clients MUST NOT act on URIs without getting the user’s authorization. They SHOULD require the user to manually approve each payment individually, though in some cases, they MAY allow the user to make this decision automatically.

Operating system integration​

Graphical Everscale clients SHOULD register themselves as the handler for the URI scheme by default if no other handler is already registered. If a registered handler is already present, they MAY prompt the user to change it once they first run the client.

EBNF grammar​

everurn = protocol, ":", ["//"], everaddress, ["?", everparams];

protocol = "everscale" | "ever" | "tvm:42";

everaddress = rawaddress | base64 | base64url;

rawaddress = chainnumber, ":", {letter | digit};
chainnumber = ["-"], digit, digit*;

base64 = base64character, {base64character};
base64character = letter | digit | base64symbol;
base64symbol = "/" | "+";

base64url = base64urlcharacter, {base64urlcharacter};
base64urlcharacter = letter | digit | base64urlsymbol;
base64urlsymbol = "-" | "_";

everparams = everparam, ["&", everparams*];
everparam = amountparam | labelparam | commentparam | versionparam | otherparam | reqparam | netparam;
amountparam = amountnotation, "=", digit, digit*, [".", digit*];
amountnotation = "amount" | "a";
labelparam = labelnotation, "=", labelcharacter*;
labelnotation = "label" | "l";
commentparam = commentnotation, "=", labelcharacter*;
commentnotation = "comment" | "c";
versionparam = versionnotation, "=", digit, digit*, [".", digit, digit*];
versionnotation = "version" | "v";
otherparam = labelcharacter, labelcharacter*, "=", labelcharacter*;
reqparam = "req-", otherparam;
netparam = netnotation, "=", labelcharacter*;
netnotation = "net" | "n";

labelcharacter = letter | digit | urisymbol;

letter = "A" | "B" | "C" | "D" | "E" | "F" | "G"
| "H" | "I" | "J" | "K" | "L" | "M" | "N"
| "O" | "P" | "Q" | "R" | "S" | "T" | "U"
| "V" | "W" | "X" | "Y" | "Z" | "a" | "b"
| "c" | "d" | "e" | "f" | "g" | "h" | "i"
| "j" | "k" | "l" | "m" | "n" | "o" | "p"
| "q" | "r" | "s" | "t" | "u" | "v" | "w"
| "x" | "y" | "z" ;
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6"
| "7" | "8" | "9";
urisymbol = ":" | "/" | "?" | "#" | "[" | "]" | "@"
| "!" | "$" | "'" | "(" | ")" | "*" | "+"
| "," | ";" | "%" | "." ;

You can validate your payment link for validity at the EBNF evaluator.

The scheme component (ever:, everscale:, or tvm:42:) is case-insensitive, and implementations must accept any combination of uppercase and lowercase letters. The rest of the URI is case-sensitive, including the query parameter keys.

Query Keys​

  • label or l: Label for that address (e.g. name of receiver or order number);
  • address: Everscale address in raw or packed (base64 / base64url) representation;
  • comment or c: message to attach to the transaction while sending it to the network;
  • amount or a: amount of base currency units (see below);
  • version or v: applicable standard version. If omitted, version 1 will apply;
  • net or n: network to perform operation, e.g. “main” or “dev”;
  • (other): optional, for future extensions.

Transfer amount/size​

If an amount is provided, it MUST be specified in decimal EVER. 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 EVER, and amount=50,000.00 is invalid.

Everscale clients MAY display the amount in any format that is not intended to deceive the user. However, they SHOULD choose a foremost least confusing format, and only after that most reasonable given the amount requested. Thus, for example, so long as most users work in EVER units, values should always be displayed in EVER by default, even if mEVER or kEVER would otherwise be a more logical interpretation of the amount.

Forward compatibility​

Variables that are prefixed with a req- are considered required. If a client does not implement any variables prefixed with req-, it MUST consider the entire URI invalid. Any other variables that are not implemented but are not prefixed with a req- can be safely ignored.

Appendix​

Simpler syntax​

This section is non-normative and does not cover all possible syntax. Please see the EBNF grammar above for the normative syntax. [foo] means optional, <bar> are placeholders.

ever://<address>[?amount=<amount>][&label=<label>][&comment=<comment>]

Examples​

Characters must be URI encoded properly.

Just address (in different formats)​

ever: protocol​
ever:0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3
everscale: protocol​
everscale:0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3
tvm:42: protocol​
tvm:42:0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3
ever://0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3
Address with name​
ever:0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3?label=Mr.Skywalker
Request 100.2 EVER​
ever:0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3?label=Mr.Skywalker&amount=100.2
Payment with comment​
ever:0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3?label=Mr.Skywalker&amount=100.2&comment=hello%21
Some future version that has variables that are (currently) not understood and required and thus invalid​
ever:0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3?req-special1=abc&req-special2=123
Some future version that has variables that are (currently) not understood but not required and thus valid​
ever:0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3?special1=abc&special2=123

Reserved standard extensions​

The future standard extensions are reserved:

  • TIP-5.2 — URI scheme (TIP-3 fungible token payment link)
  • TIP-5.3 — URI scheme (TIP-4 non-fungible token payment link)