Skip to content

Commit a60b85b

Browse files
vp-mazekinevp-mazekine
authored
Add TIP 5.1 - EVER payment links (#369)
1 parent 1f74278 commit a60b85b

2 files changed

Lines changed: 185 additions & 0 deletions

File tree

‎src/standard/TIP-5/1.md‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
---
2+
title: 1. EVER payment link
3+
sidebar_position: 1
4+
slug: /standard/TIP-5.1
5+
---
6+
7+
# EVER payment link (TIP-5.1)
8+
9+
## Abstract
10+
11+
This TIP proposes a URI scheme for making EVER payments.
12+
13+
## Motivation
14+
15+
Payment URIs has become widely adopted since the introduction of Bitcoin’s improvement proposals [BIP-20](https://github.com/bitcoin/bips/blob/master/bip-0020.mediawiki), [21](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki), [70](https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki), [71](https://github.com/bitcoin/bips/blob/master/bip-0071.mediawiki), and [72](https://github.com/bitcoin/bips/blob/master/bip-0072.mediawiki). For instance, most modern mobile wallets support the scanning of QR codes containing encoded bitcoin payment links.
16+
17+
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.
18+
19+
## Specification
20+
21+
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.
22+
23+
All symbols in the payment link MUST be encoded following the guidelines set out in RFC 3986.
24+
25+
### General rules for handling
26+
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.
27+
28+
### Operating system integration
29+
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.
30+
31+
### EBNF grammar
32+
```ebnf
33+
everurn = protocol, ":", ["//"], everaddress, ["?", everparams];
34+
35+
protocol = "everscale" | "ever" | "tvm:42";
36+
37+
everaddress = rawaddress | base64 | base64url;
38+
39+
rawaddress = chainnumber, ":", {letter | digit};
40+
chainnumber = ["-"], digit, digit*;
41+
42+
base64 = base64character, {base64character};
43+
base64character = letter | digit | base64symbol;
44+
base64symbol = "/" | "+";
45+
46+
base64url = base64urlcharacter, {base64urlcharacter};
47+
base64urlcharacter = letter | digit | base64urlsymbol;
48+
base64urlsymbol = "-" | "_";
49+
50+
everparams = everparam, ["&", everparams*];
51+
everparam = amountparam | labelparam | commentparam | versionparam | otherparam | reqparam | netparam;
52+
amountparam = amountnotation, "=", digit, digit*, [".", digit*];
53+
amountnotation = "amount" | "a";
54+
labelparam = labelnotation, "=", labelcharacter*;
55+
labelnotation = "label" | "l";
56+
commentparam = commentnotation, "=", labelcharacter*;
57+
commentnotation = "comment" | "c";
58+
versionparam = versionnotation, "=", digit, digit*, [".", digit, digit*];
59+
versionnotation = "version" | "v";
60+
otherparam = labelcharacter, labelcharacter*, "=", labelcharacter*;
61+
reqparam = "req-", otherparam;
62+
netparam = netnotation, "=", labelcharacter*;
63+
netnotation = "net" | "n";
64+
65+
labelcharacter = letter | digit | urisymbol;
66+
67+
letter = "A" | "B" | "C" | "D" | "E" | "F" | "G"
68+
| "H" | "I" | "J" | "K" | "L" | "M" | "N"
69+
| "O" | "P" | "Q" | "R" | "S" | "T" | "U"
70+
| "V" | "W" | "X" | "Y" | "Z" | "a" | "b"
71+
| "c" | "d" | "e" | "f" | "g" | "h" | "i"
72+
| "j" | "k" | "l" | "m" | "n" | "o" | "p"
73+
| "q" | "r" | "s" | "t" | "u" | "v" | "w"
74+
| "x" | "y" | "z" ;
75+
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6"
76+
| "7" | "8" | "9";
77+
urisymbol = ":" | "/" | "?" | "#" | "[" | "]" | "@"
78+
| "!" | "$" | "'" | "(" | ")" | "*" | "+"
79+
| "," | ";" | "%" | "." ;
80+
```
81+
82+
You can validate your payment link for validity at the [EBNF evaluator](https://mdkrajnak.github.io/ebnftest/).
83+
84+
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.
85+
86+
### Query Keys
87+
88+
* **`label` or `l`:** Label for that address (e.g. name of receiver or order number);
89+
* **`address`:** Everscale address in raw or packed (base64 / base64url) representation;
90+
* **`comment` or `c`:** message to attach to the transaction while sending it to the network;
91+
* **`amount` or `a`:** amount of base currency units (see below);
92+
* **`version` or `v`:** applicable standard version. If omitted, version 1 will apply;
93+
* **`net` or `n`:** network to perform operation, e.g. “main” or “dev”;
94+
* **(other):** optional, for future extensions.
95+
96+
#### Transfer amount/size
97+
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.
98+
99+
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.
100+
101+
#### Forward compatibility
102+
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.
103+
104+
## Appendix
105+
106+
### Simpler syntax
107+
This section is non-normative and does not cover all possible syntax. Please see the EBNF grammar above for the normative syntax.
108+
`[foo]` means optional, `<bar>` are placeholders.
109+
110+
```
111+
ever://<address>[?amount=<amount>][&label=<label>][&comment=<comment>]
112+
```
113+
114+
### Examples
115+
Characters must be URI encoded properly.
116+
117+
#### Just address (in different formats)
118+
119+
##### `ever:` protocol
120+
```
121+
ever:0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3
122+
```
123+
124+
##### `everscale:` protocol
125+
```
126+
everscale:0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3
127+
```
128+
129+
##### `tvm:42:` protocol
130+
```
131+
tvm:42:0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3
132+
```
133+
134+
##### URL-like link
135+
```
136+
ever://0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3
137+
```
138+
139+
##### Address with name
140+
```
141+
ever:0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3?label=Mr.Skywalker
142+
```
143+
144+
##### Request 100.2 EVER
145+
```
146+
ever:0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3?label=Mr.Skywalker&amount=100.2
147+
```
148+
149+
##### Payment with comment
150+
```
151+
ever:0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3?label=Mr.Skywalker&amount=100.2&comment=hello%21
152+
```
153+
154+
##### Some future version that has variables that are (currently) not understood and required and thus invalid
155+
```
156+
ever:0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3?req-special1=abc&req-special2=123
157+
```
158+
159+
##### Some future version that has variables that are (currently) not understood but not required and thus valid
160+
```
161+
ever:0:e2b874ee05cd7e5d1475d90bab04d26974e67fe7aef97d730c2adcba5ea895c3?special1=abc&special2=123
162+
```
163+
164+
## Reserved standard extensions
165+
The future standard extensions are reserved:
166+
* `TIP-5.2` &mdash; URI scheme (TIP-3 fungible token payment link)
167+
* `TIP-5.3` &mdash; URI scheme (TIP-4 non-fungible token payment link)

‎src/standard/TIP-5/core-description.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Core description
3+
sidebar_position: 0
4+
slug: /standard/TIP-5
5+
[//]: # (draft: true)
6+
---
7+
8+
# URI scheme
9+
10+
## Abstract
11+
12+
This TIP proposes a URI scheme for making payments and transfers in EVER, fungible and non-fungible tokens.
13+
14+
## Motivation
15+
16+
Payment URIs has become widely adopted since the introduction of Bitcoin’s improvement proposals [BIP-20](https://github.com/bitcoin/bips/blob/master/bip-0020.mediawiki), [21](https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki), [70](https://github.com/bitcoin/bips/blob/master/bip-0070.mediawiki), [71](https://github.com/bitcoin/bips/blob/master/bip-0071.mediawiki), and [72](https://github.com/bitcoin/bips/blob/master/bip-0072.mediawiki). For instance, most modern mobile wallets support the scanning of QR codes containing encoded bitcoin payment links.
17+
18+
The purpose of this URI scheme is to enable users to easily make payments and transfers in EVER, fungible and non-fungible tokens by simply clicking links on web pages or scanning QR Codes.

0 commit comments

Comments
 (0)