Skip to content

Commit 3d4648e

Browse files
rise1507rise1507
committed
TEP-2 - TON Addresses
1 parent bad4320 commit 3d4648e

File tree

2 files changed

+133
-0
lines changed

2 files changed

+133
-0
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ Proposal management is done using GitHub pull requests, the process is described
1919
| TEP | Title | Type | Created |
2020
|----------------------------------------------|------------------------------------|--------------------|------------|
2121
| [1](./text/0001-tep-lifecycle.md) | TEP Lifecycle | Meta | 11.06.2022 |
22+
| [2](./text/0002-address.md) | TON Addresses | Core | 07.09.2019 |
2223
| [62](./text/0062-nft-standard.md) | NFT Standard | Contract Interface | 01.02.2022 |
2324
| [64](./text/0064-token-data-standard.md) | Token Data Standard | Contract Interface | 03.02.2022 |
2425
| [66](./text/0066-nft-royalty-standard.md) | NFTRoyalty Standard Extension | Contract Interface | 12.02.2022 |

‎text/0002-address.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
- **TEP**: [2](https://github.com/ton-blockchain/TEPs/pull/2)
2+
- **title**: TON Addresses
3+
- **status**: Active
4+
- **type**: Core
5+
- **authors**: -
6+
- **created**: 07.09.2019
7+
- **replaces**: -
8+
- **replaced by**: -
9+
10+
# Summary
11+
12+
This document describes TON addresses and their representation.
13+
14+
# Specification
15+
16+
## Smart-contract addresses
17+
18+
Smart-contract addresses in the TON Network consist of two parts:
19+
20+
(a) the workchain ID (a signed 32-bit integer) and
21+
22+
(b) the address inside the workchain (64-512 bits depending on the workchain).
23+
24+
Currently, only the masterchain (workchain_id=-1) and the basic workchain (workchain_id=0) are running in the TON Blockchain Network. Both of them have 256-bit addresses, so until a new different workchains appears we assume that workchain_id is either 0 or -1 and that the address inside the workchain is exactly 256-bit.
25+
26+
Under the conditions stated above, the smart-contract address can be represented in the following forms:
27+
28+
A) "Raw": <decimal workchain_id>:<64 hexadecimal digits with address>
29+
30+
B) "User-friendly", which is obtained by first generating:
31+
- one tag byte (0x11 for "bounceable" addresses, 0x51 for "non-bounceable"; add +0x80 if the address should not be accepted by software running in the mainnet network)
32+
- one byte containing a signed 8-bit integer with the workchain_id (0x00 for the basic workchain, 0xff for the masterchain)
33+
- 32 bytes containing 256 bits of the smart-contract address inside the workchain (big-endian)
34+
- 2 bytes containing CRC16-CCITT of the previous 34 bytes
35+
36+
In case B), the 36 bytes thus obtained are then encoded using base64 (i.e., with digits, upper- and lowercase Latin letters, '/' and '+') or base64url (with '_' and '-' instead of '/' and '+'), yielding 48 printable non-space characters.
37+
38+
Example:
39+
40+
The "root dns" (a special smart contract residing in the masterchain) has the address
41+
42+
`-1:e56754f83426f69b09267bd876ac97c44821345b7e266bd956a7bfbfb98df35c`
43+
44+
in the "raw" form (notice that uppercase Latin letters 'A'..'F' may be used instead of 'a'..'f')
45+
46+
and
47+
48+
`Ef_lZ1T4NCb2mwkme9h2rJfESCE0W34ma9lWp7-_uY3zXDvq` (bounceable)
49+
50+
`Uf_lZ1T4NCb2mwkme9h2rJfESCE0W34ma9lWp7-_uY3zXGYv` (non-bounceable)
51+
52+
in the "user-friendly" form (to be displayed by user-friendly clients).
53+
54+
Notice that both forms (base64 and base64url) are valid and must be accepted.
55+
56+
## Wallets applications
57+
58+
At the moment, TON wallets work with addresses as follows:
59+
60+
For receiving:
61+
62+
- Wallets display the user's address in a user-friendly bounceable or non-bounceable form (at the moment, the majority of wallet apps display bounceable form).
63+
64+
When sending:
65+
66+
1) The wallet app checks the validity of the destination address representation - its length, valid characters, prefix and checksum. If the address is not valid, then an alert is shown and the sending operation is not performed.
67+
68+
2) If the address has a testnet flag, and the wallet app works with the mainnet network, then an alert is shown and the sending operation is not performed.
69+
70+
3) The wallet app retrieve from address bounceable flag.
71+
72+
4) The wallet app check the destination address - if it has `unitialized` state wallet force set `bounce` field of sending message to `false` and ignore bounceable/non-bounceable flag from address representation.
73+
74+
5) If destination is not `unitialized` then wallet app uses the bounceable/non-bounceable flag from the address representation for the `bounce` field of sending message.
75+
76+
## Public keys
77+
78+
The ubiquitous 256-bit Ed25519 public keys can be represented in the following forms:
79+
80+
A) "Raw": <64 hexadecimal digits with address>
81+
82+
B) "User-friendly" or "armored", which is obtained by first generating:
83+
84+
- one tag byte 0x3E, meaning that this is a public key
85+
- one tag byte 0xE6, meaning that this is a Ed25519 public key
86+
- 32 bytes containing the standard binary representation of the Ed25519 public key
87+
- 2 bytes containing the big-endian representation of CRC16-CCITT of the previous 34 bytes.
88+
89+
The resulting 36-byte sequence is converted into a 48-character base64 or base64url string in the standard fashion.
90+
91+
For example, the Ed25519 public key `E39ECDA0A7B0C60A7107EC43967829DBE8BC356A49B9DFC6186B3EAC74B5477D` (usually represented by a sequence of 32 bytes `0xE3, 0x9E, ..., 0x7D`) has the following "armored" representation:
92+
93+
`Pubjns2gp7DGCnEH7EOWeCnb6Lw1akm538YYaz6sdLVHfRB2`
94+
95+
## ADNL address
96+
97+
The ADNL protocol based on 256-bit abstract addresses.
98+
99+
The ADNL address can be represented in the following forms:
100+
101+
A) "Raw": <64 hexadecimal digits with address>
102+
103+
B) "User-friendly" or "armored", which is obtained by first generating:
104+
105+
- one tag byte 0x2d, meaning that this is a ADNL address
106+
- 32 bytes containing 256 bits of the ADNL address (big-endian)
107+
- 2 bytes containing the big-endian representation of CRC16-CCITT of the previous 34 bytes.
108+
109+
The resulting 35-byte sequence is converted into a 55-character base32 string in the standard fashion.
110+
111+
Example:
112+
113+
For example ADNL address `45061C1D4EC44A937D0318589E13C73D151D1CEF5D3C0E53AFBCF56A6C2FE2BD` has the following "armored" representation:
114+
115+
`vcqmha5j3ceve35ammfrhqty46rkhi455otydstv66pk2tmf7rl25f3`
116+
117+
# Drawbacks
118+
119+
- It is impossible to extract the public key from the address, which is needed for some tasks (for example, to send an encrypted message to this address).
120+
Thus, until the smart contract is deployed for this address, there is no way to get the public key on-chain.
121+
122+
- (UI) Most OS do not allow you to select an address with double click because of '_', '-', '/', '+' base64 symbols.
123+
124+
# Rationale and alternatives
125+
126+
- The prefix (the first byte(s)) allows you to understand exactly what type this address or key is.
127+
128+
- The checksum built into the address prevents the loss of funds due to a user typo.
129+
130+
- Built-in testnet flag prevents loss of funds by a user who mistakenly tries to send real coins to a testnet address.
131+
132+
- A different form of address than most other blockchains allows the user to more easily identify the TON address.

0 commit comments

Comments
 (0)