diff --git a/README.md b/README.md index c0b2297f..19192f91 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ Proposal management is done using GitHub pull requests, the process is described | TEP | Title | Type | Created | |----------------------------------------------|------------------------------------|--------------------|------------| | [1](./text/0001-tep-lifecycle.md) | TEP Lifecycle | Meta | 11.06.2022 | +| [2](./text/0002-address.md) | TON Addresses | Core | 07.09.2019 | | [62](./text/0062-nft-standard.md) | NFT Standard | Contract Interface | 01.02.2022 | | [64](./text/0064-token-data-standard.md) | Token Data Standard | Contract Interface | 03.02.2022 | | [66](./text/0066-nft-royalty-standard.md) | NFTRoyalty Standard Extension | Contract Interface | 12.02.2022 | diff --git a/text/0002-address.md b/text/0002-address.md new file mode 100644 index 00000000..57d696e6 --- /dev/null +++ b/text/0002-address.md @@ -0,0 +1,132 @@ +- **TEP**: [2](https://github.com/ton-blockchain/TEPs/pull/2) +- **title**: TON Addresses +- **status**: Active +- **type**: Core +- **authors**: - +- **created**: 07.09.2019 +- **replaces**: - +- **replaced by**: - + +# Summary + +This document describes TON addresses and their representation. + +# Specification + +## Smart-contract addresses + +Smart-contract addresses in the TON Network consist of two parts: + +(a) the workchain ID (a signed 32-bit integer) and + +(b) the address inside the workchain (64-512 bits depending on the workchain). + +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. + +Under the conditions stated above, the smart-contract address can be represented in the following forms: + +A) "Raw": :<64 hexadecimal digits with address> + +B) "User-friendly", which is obtained by first generating: +- 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) +- one byte containing a signed 8-bit integer with the workchain_id (0x00 for the basic workchain, 0xff for the masterchain) +- 32 bytes containing 256 bits of the smart-contract address inside the workchain (big-endian) +- 2 bytes containing CRC16-CCITT of the previous 34 bytes + +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. + +Example: + +The "root dns" (a special smart contract residing in the masterchain) has the address + +`-1:e56754f83426f69b09267bd876ac97c44821345b7e266bd956a7bfbfb98df35c` + +in the "raw" form (notice that uppercase Latin letters 'A'..'F' may be used instead of 'a'..'f') + +and + +`Ef_lZ1T4NCb2mwkme9h2rJfESCE0W34ma9lWp7-_uY3zXDvq` (bounceable) + +`Uf_lZ1T4NCb2mwkme9h2rJfESCE0W34ma9lWp7-_uY3zXGYv` (non-bounceable) + +in the "user-friendly" form (to be displayed by user-friendly clients). + +Notice that both forms (base64 and base64url) are valid and must be accepted. + +## Wallets applications + +At the moment, TON wallets work with addresses as follows: + +For receiving: + +- 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). + +When sending: + +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. + +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. + +3) The wallet app retrieve from address bounceable flag. + +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. + +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. + +## Public keys + +The ubiquitous 256-bit Ed25519 public keys can be represented in the following forms: + +A) "Raw": <64 hexadecimal digits with address> + +B) "User-friendly" or "armored", which is obtained by first generating: + +- one tag byte 0x3E, meaning that this is a public key +- one tag byte 0xE6, meaning that this is a Ed25519 public key +- 32 bytes containing the standard binary representation of the Ed25519 public key +- 2 bytes containing the big-endian representation of CRC16-CCITT of the previous 34 bytes. + +The resulting 36-byte sequence is converted into a 48-character base64 or base64url string in the standard fashion. + +For example, the Ed25519 public key `E39ECDA0A7B0C60A7107EC43967829DBE8BC356A49B9DFC6186B3EAC74B5477D` (usually represented by a sequence of 32 bytes `0xE3, 0x9E, ..., 0x7D`) has the following "armored" representation: + +`Pubjns2gp7DGCnEH7EOWeCnb6Lw1akm538YYaz6sdLVHfRB2` + +## ADNL address + +The ADNL protocol based on 256-bit abstract addresses. + +The ADNL address can be represented in the following forms: + +A) "Raw": <64 hexadecimal digits with address> + +B) "User-friendly" or "armored", which is obtained by first generating: + +- one tag byte 0x2d, meaning that this is a ADNL address +- 32 bytes containing 256 bits of the ADNL address (big-endian) +- 2 bytes containing the big-endian representation of CRC16-CCITT of the previous 34 bytes. + +The resulting 35-byte sequence is converted into a 55-character base32 string in the standard fashion. + +Example: + +For example ADNL address `45061C1D4EC44A937D0318589E13C73D151D1CEF5D3C0E53AFBCF56A6C2FE2BD` has the following "armored" representation: + +`vcqmha5j3ceve35ammfrhqty46rkhi455otydstv66pk2tmf7rl25f3` + +# Drawbacks + +- 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). + Thus, until the smart contract is deployed for this address, there is no way to get the public key on-chain. + +- (UI) Most OS do not allow you to select an address with double click because of '_', '-', '/', '+' base64 symbols. + +# Rationale and alternatives + +- The prefix (the first byte(s)) allows you to understand exactly what type this address or key is. + +- The checksum built into the address prevents the loss of funds due to a user typo. + +- Built-in testnet flag prevents loss of funds by a user who mistakenly tries to send real coins to a testnet address. + +- A different form of address than most other blockchains allows the user to more easily identify the TON address. \ No newline at end of file