From eddb464f8d32ccc3821786316f52dbe8ac29ec8e Mon Sep 17 00:00:00 2001 From: aigerimu <89766357+aigerimu@users.noreply.github.com> Date: Fri, 3 Oct 2025 02:19:08 +0700 Subject: [PATCH 1/4] wallets-overview-draft --- ecosystem/wallet-apps/overview.mdx | 89 +++++++++++++++++++++++++++++- 1 file changed, 88 insertions(+), 1 deletion(-) diff --git a/ecosystem/wallet-apps/overview.mdx b/ecosystem/wallet-apps/overview.mdx index 3988599e..4d863e12 100644 --- a/ecosystem/wallet-apps/overview.mdx +++ b/ecosystem/wallet-apps/overview.mdx @@ -2,4 +2,91 @@ title: "Overview" --- -Stub +**TODO: clarify account moments** + +**TODO: add links** + +This article provides an overview of wallet applications built on the standard [wallet contract](/standard/wallets/how-it-works), describing their _operation, creation, transaction handling, and classification_. + +## How wallet apps work + +This section explains how wallet applications manage keys, initialize accounts, and process transactions on TON. + +### Mnemonic decoding + +A **mnemonic (seed phrase)** is a human-readable sequence of typically 24 words. It encodes the information needed to generate a **key pair**, consisting of a private key and a public key. +- The **private key** is used to sign messages and authorize transactions. +- The **public key** is stored in the wallet’s smart contract and is used to verify signatures of incoming messages. + +A mnemonic allows a user to **recover** their wallet and key pair on the same wallet app or compatible implementations. +Users are fully responsible for securely storing their mnemonic, as loss results in permanent loss of access. + +### Account initialization + +A wallet account begins in the [nonexist state](/ton/statuses#status-variety), which is the default for accounts with no transaction history, code, data, or balance. At this stage, the account does not exist on-chain. However, its **wallet address** can already be computed from the wallet’s **TODO**. This address can be used to receive funds even before the wallet is initialized. + +After receiving coins, the account transitions to the [uninit state](/ton/statuses#status-variety). In this state, it holds a balance and metadata but cannot execute transactions or process messages. + +The initialization process then proceeds as follows: +- Deploying the wallet contract — the wallet’s smart contract is deployed, initializing its code and persistent data. + +### First transaction + +A wallet becomes **active** upon executing its first transaction. +This initial transaction completes the wallet’s activation, enabling it to interact with the blockchain. +In the [active state](/ton/statuses#status-variety), the wallet: +- Contains deployed contract code and persistent data. +- Holds a balance and can process incoming and outgoing messages. +- It is capable of signing and sending further transactions using its private key. + +### Transaction process + +A wallet transaction is initiated by creating an **external message** signed with the wallet’s private key. The wallet contract uses the corresponding public key to verify the signature. + +Key steps: +- Message creation — specify recipient, amount, and optional payload (e.g., smart contract call). +- Signing — the wallet signs the message with its private key. +- Sequence number (seqno) — ensures uniqueness and prevents replay attacks. +- Submission — the signed message is sent to the blockchain network. +- Processing — validators verify the signature, apply fees, and update the account's balance and state. + +Each processed transaction increments the wallet's seqno and updates its state. Transactions can carry Toncoin or other supported assets and interact with other smart contracts. + +## Wallet types + +Wallets are classified by how they manage private keys, store them, and their intended usage. + +### Custodial and non-custodial + +Wallets are defined by _how private keys are managed_. + +- **Custodial wallets** store private keys with a third party, such as an exchange or service provider. The custodian manages security and may provide account recovery. However, users must trust the custodian with full access to their assets. +- **Non-custodial or self-custody wallets** store private keys only with the user. Keys are protected with a **seed phrase** — a sequence of 24 words generated at wallet creation. This gives the user _complete ownership_ and _control over their data_. However, full responsibility also applies: losing the seed phrase means permanent loss of access. + +### Hardware and software + +The storage of private keys defines wallet types — _online (hot) or offline (cold)_. + +- **Hardware (cold) wallets** are physical devices that keep private keys offline, isolated from internet exposure. When authorizing a transaction, the device signs it internally, ensuring that private keys remain on the device. +- **Software (hot) wallets** run on devices such as smartphones or computers. Private keys are stored in the device’s secure storage, making them readily available for transactions but also exposed to online risks. Software wallets include **mobile**, **web**, and **desktop** applications. + + +### Developer and user + +Wallets differ by their intended use. + +- **User wallets** are designed for everyday operations, including storing, sending, and receiving Toncoin or tokens, as well as interacting with applications. Their design emphasizes usability and accessibility. +- **Developer wallets** are designed for testing and development purposes. They are typically used with Testnet, SDKs, or command-line tools to deploy contracts, generate keys, and send transactions in controlled environments. + +## Wallet examples + +The table below summarizes each wallet’s usage, type, and custody model. + +| Wallet | Custody | Type | Usage | +|-------------------------------------------------------------------|------------------|--------|:-----------:| +| [Tonkeeper](https://tonkeeper.com) | non-custodial | hot | user & dev | +| [TonDevWallet](https://github.com/TonDevWallet/TonDevWallet) | non-custodial | hot | dev | +| [wallet.ton.org](https://wallet.ton.org/) | non-custodial | hot | user & dev | + + +_Explore the full range of wallets at [ton.org](https://ton.org/en/wallets?locale=en&pagination[limit]=-1)._ From e1722817e2534dfd95ffc0db760b749cfaa9f1f7 Mon Sep 17 00:00:00 2001 From: aigerimu <89766357+aigerimu@users.noreply.github.com> Date: Sat, 4 Oct 2025 04:57:12 +0700 Subject: [PATCH 2/4] wallets-overview --- ecosystem/wallet-apps/overview.mdx | 77 +++++++++++++++--------------- standard/wallets/mnemonics.mdx | 16 +++---- 2 files changed, 47 insertions(+), 46 deletions(-) diff --git a/ecosystem/wallet-apps/overview.mdx b/ecosystem/wallet-apps/overview.mdx index 4d863e12..bf0149d9 100644 --- a/ecosystem/wallet-apps/overview.mdx +++ b/ecosystem/wallet-apps/overview.mdx @@ -2,55 +2,60 @@ title: "Overview" --- -**TODO: clarify account moments** +import { Aside } from '/snippets/aside.jsx'; -**TODO: add links** - -This article provides an overview of wallet applications built on the standard [wallet contract](/standard/wallets/how-it-works), describing their _operation, creation, transaction handling, and classification_. +This article provides an overview of wallet applications built on the standard [wallet contract](/standard/wallets/how-it-works), describing their _creation, operation, transaction handling, and classification_. ## How wallet apps work -This section explains how wallet applications manage keys, initialize accounts, and process transactions on TON. +Wallets manage accounts, control keys, sign messages, and initiate transactions. This process starts with mnemonic decoding and continues through transaction execution. ### Mnemonic decoding -A **mnemonic (seed phrase)** is a human-readable sequence of typically 24 words. It encodes the information needed to generate a **key pair**, consisting of a private key and a public key. -- The **private key** is used to sign messages and authorize transactions. -- The **public key** is stored in the wallet’s smart contract and is used to verify signatures of incoming messages. +A **mnemonic (seed phrase)** is a human-readable sequence of 24 words that generates a **key pair**, which a wallet uses to manage the account. + +The key pair consists of: +- **Private key** signs messages and authorizes transactions. +- **Public key** is stored in the wallet's smart contract to verify signatures of incoming messages. + +A mnemonic allows the user **to recover** the wallet and key pair on the same wallet app or any compatible implementation. Losing it results in permanent loss of access. + + -A mnemonic allows a user to **recover** their wallet and key pair on the same wallet app or compatible implementations. -Users are fully responsible for securely storing their mnemonic, as loss results in permanent loss of access. +With the derived keys, the wallet can establish an on-chain account. -### Account initialization +### Account creation -A wallet account begins in the [nonexist state](/ton/statuses#status-variety), which is the default for accounts with no transaction history, code, data, or balance. At this stage, the account does not exist on-chain. However, its **wallet address** can already be computed from the wallet’s **TODO**. This address can be used to receive funds even before the wallet is initialized. +A wallet account starts in the [nonexist state](/ton/statuses#status-variety), which is the default for accounts with no transaction history, code, data, or balance. At this stage, the account does not exist on-chain. -After receiving coins, the account transitions to the [uninit state](/ton/statuses#status-variety). In this state, it holds a balance and metadata but cannot execute transactions or process messages. +However, its **wallet address** can be computed from the [workchain_id](/ton/addresses/addresses-general-info#workchain-id) and [account_id](/ton/addresses/addresses-general-info#account-id). This address can be used to receive funds even before the wallet is initialized. -The initialization process then proceeds as follows: -- Deploying the wallet contract — the wallet’s smart contract is deployed, initializing its code and persistent data. +After receiving coins, the account enters the [uninit state](/ton/statuses#status-variety). In this state, it holds a balance and metadata but cannot execute transactions or process messages. ### First transaction -A wallet becomes **active** upon executing its first transaction. -This initial transaction completes the wallet’s activation, enabling it to interact with the blockchain. -In the [active state](/ton/statuses#status-variety), the wallet: -- Contains deployed contract code and persistent data. -- Holds a balance and can process incoming and outgoing messages. -- It is capable of signing and sending further transactions using its private key. +The wallet account becomes **active** when its code and data are deployed. +It happens when the wallet sends its first transaction, which finalizes activation and enables interaction with the blockchain. -### Transaction process +In the [active state](/ton/statuses#status-variety), the account: +- Contains deployed contract code, persistent data, and a balance. +- Can process incoming and outgoing messages. +- Can sign and send transactions using its private key. -A wallet transaction is initiated by creating an **external message** signed with the wallet’s private key. The wallet contract uses the corresponding public key to verify the signature. +### Transaction process -Key steps: -- Message creation — specify recipient, amount, and optional payload (e.g., smart contract call). -- Signing — the wallet signs the message with its private key. -- Sequence number (seqno) — ensures uniqueness and prevents replay attacks. -- Submission — the signed message is sent to the blockchain network. -- Processing — validators verify the signature, apply fees, and update the account's balance and state. +When making a transaction, the wallet goes through these steps: +- **Message creation** — builds an external message with the recipient, amount, and optional payload. +- **Sequence number check** — reads the account's current on-chain `seqno` and includes it to prevent [replay attacks](/standard/wallets/how-it-works#how-replay-protection-works). +- **Signing** — signs the message with the private key. +- **Submission** — sends the signed message to the blockchain. -Each processed transaction increments the wallet's seqno and updates its state. Transactions can carry Toncoin or other supported assets and interact with other smart contracts. +**On-chain execution:** +- Validators verify the signature using the **public key** stored in the wallet contract. +- Fees are applied and the `seqno` is incremented. +- The account balance and state reflect the transaction outcome. ## Wallet types @@ -78,15 +83,11 @@ Wallets differ by their intended use. - **User wallets** are designed for everyday operations, including storing, sending, and receiving Toncoin or tokens, as well as interacting with applications. Their design emphasizes usability and accessibility. - **Developer wallets** are designed for testing and development purposes. They are typically used with Testnet, SDKs, or command-line tools to deploy contracts, generate keys, and send transactions in controlled environments. -## Wallet examples - -The table below summarizes each wallet’s usage, type, and custody model. -| Wallet | Custody | Type | Usage | -|-------------------------------------------------------------------|------------------|--------|:-----------:| -| [Tonkeeper](https://tonkeeper.com) | non-custodial | hot | user & dev | -| [TonDevWallet](https://github.com/TonDevWallet/TonDevWallet) | non-custodial | hot | dev | -| [wallet.ton.org](https://wallet.ton.org/) | non-custodial | hot | user & dev | + +## Wallet apps _Explore the full range of wallets at [ton.org](https://ton.org/en/wallets?locale=en&pagination[limit]=-1)._ diff --git a/standard/wallets/mnemonics.mdx b/standard/wallets/mnemonics.mdx index 5f2e29b4..6e98ea0a 100644 --- a/standard/wallets/mnemonics.mdx +++ b/standard/wallets/mnemonics.mdx @@ -6,7 +6,7 @@ sidebarTitle: "Mnemonics" import { Aside } from '/snippets/aside.jsx'; -## Key pair +## Key pair TON Blockchain uses asymmetric cryptography, such as the [Ed25519](https://en.wikipedia.org/wiki/EdDSA#Ed25519) signature scheme. @@ -32,7 +32,7 @@ The most commonly used values are: | `c` | Number of iterations desired | 100000 | `dkLen` | Desired bit-length of the derived key | 64 -### Generate a key pair +### Generate a key pair ```ts title="TypeScript" import { mnemonicToPrivateKey, mnemonicNew } from "@ton/crypto"; @@ -41,7 +41,7 @@ import { mnemonicToPrivateKey, mnemonicNew } from "@ton/crypto"; const mnemonicArray = await mnemonicNew(); // derive private and public keys from the mnemonic -const keyPair = await mnemonicToPrivateKey(mnemonicArray); +const keyPair = await mnemonicToPrivateKey(mnemonicArray); console.log("Public Key: " + keyPair.publicKey.toString('hex')); console.log("Private Key: " + keyPair.secretKey.toString('hex')); @@ -53,9 +53,9 @@ The private key is needed to sign messages, and the public key is stored in the Save the generated mnemonic seed phrase. If you need deterministic behavior during development, print and reuse the exact phrase so the wallet derives the same key pair on every run. -## Mnemonic validation +## Mnemonic validation -1. Check that all the words are from the list of [BIP-39](https://github.com/ton-org/ton-crypto/blob/c3435833a0da52a96f674c352c4c6f91fcc07f6d/src/mnemonic/wordlist.ts#L9). +1. Check that all the words are from the list of [BIP-39](https://github.com/ton-org/ton-crypto/blob/c3435833a0da52a96f674c352c4c6f91fcc07f6d/src/mnemonic/wordlist.ts#L9). 2. If a password is used: the first byte of the derived `seed` computed with `c = 1` and `salt = 'TON fast seed version'` must equal `0`. 3. If no password is used: the first byte of the derived `seed` computed with `c = floor(100000/256) = 390` and `salt = 'TON seed version'` must equal `1`. @@ -66,6 +66,6 @@ Random mnemonic phrases are generated until PBKDF2 yields a seed whose first byt ```ts title="TypeScript" import { mnemonicNew } from "@ton/crypto"; -const mnemonicArray = await mnemonicNew(); -console.log(mnemonicArray); -``` \ No newline at end of file +const mnemonicArray = await mnemonicNew(); +console.log(mnemonicArray); +``` From 7cb89dc87a7b5b5b6c15de64748d27b3d473296f Mon Sep 17 00:00:00 2001 From: aigerimu <89766357+aigerimu@users.noreply.github.com> Date: Tue, 14 Oct 2025 01:42:42 +0700 Subject: [PATCH 3/4] upd-comments --- ecosystem/wallet-apps/overview.mdx | 60 +++++------------------------- 1 file changed, 10 insertions(+), 50 deletions(-) diff --git a/ecosystem/wallet-apps/overview.mdx b/ecosystem/wallet-apps/overview.mdx index bf0149d9..c25dbbb4 100644 --- a/ecosystem/wallet-apps/overview.mdx +++ b/ecosystem/wallet-apps/overview.mdx @@ -4,58 +4,13 @@ title: "Overview" import { Aside } from '/snippets/aside.jsx'; -This article provides an overview of wallet applications built on the standard [wallet contract](/standard/wallets/how-it-works), describing their _creation, operation, transaction handling, and classification_. - -## How wallet apps work - -Wallets manage accounts, control keys, sign messages, and initiate transactions. This process starts with mnemonic decoding and continues through transaction execution. - -### Mnemonic decoding - -A **mnemonic (seed phrase)** is a human-readable sequence of 24 words that generates a **key pair**, which a wallet uses to manage the account. - -The key pair consists of: -- **Private key** signs messages and authorizes transactions. -- **Public key** is stored in the wallet's smart contract to verify signatures of incoming messages. - -A mnemonic allows the user **to recover** the wallet and key pair on the same wallet app or any compatible implementation. Losing it results in permanent loss of access. +This article provides an overview of wallet apps built on the standard [wallet contract](/standard/wallets/how-it-works), explaining how they are classified based on _key management, storage method, and intended use_. - -With the derived keys, the wallet can establish an on-chain account. - -### Account creation - -A wallet account starts in the [nonexist state](/ton/statuses#status-variety), which is the default for accounts with no transaction history, code, data, or balance. At this stage, the account does not exist on-chain. + **Wallet apps** are user-facing applications for managing assets and interacting with contracts. -However, its **wallet address** can be computed from the [workchain_id](/ton/addresses/addresses-general-info#workchain-id) and [account_id](/ton/addresses/addresses-general-info#account-id). This address can be used to receive funds even before the wallet is initialized. - -After receiving coins, the account enters the [uninit state](/ton/statuses#status-variety). In this state, it holds a balance and metadata but cannot execute transactions or process messages. - -### First transaction - -The wallet account becomes **active** when its code and data are deployed. -It happens when the wallet sends its first transaction, which finalizes activation and enables interaction with the blockchain. - -In the [active state](/ton/statuses#status-variety), the account: -- Contains deployed contract code, persistent data, and a balance. -- Can process incoming and outgoing messages. -- Can sign and send transactions using its private key. - -### Transaction process - -When making a transaction, the wallet goes through these steps: -- **Message creation** — builds an external message with the recipient, amount, and optional payload. -- **Sequence number check** — reads the account's current on-chain `seqno` and includes it to prevent [replay attacks](/standard/wallets/how-it-works#how-replay-protection-works). -- **Signing** — signs the message with the private key. -- **Submission** — sends the signed message to the blockchain. - -**On-chain execution:** -- Validators verify the signature using the **public key** stored in the wallet contract. -- Fees are applied and the `seqno` is incremented. -- The account balance and state reflect the transaction outcome. + **Wallet contracts** are separate on-chain smart contracts. + ## Wallet types @@ -90,4 +45,9 @@ Wallets differ by their intended use. ## Wallet apps -_Explore the full range of wallets at [ton.org](https://ton.org/en/wallets?locale=en&pagination[limit]=-1)._ +| Wallet app | Description | Creator | +|--------------------------------------------------------------|:------------:|---------| +| [Tonkeeper](/ecosystem/wallet-apps/tonkeeper) | Self‑custodial wallet supports jettons, NFTs, and TON Connect. | Open-source | +| [TonDevWallet](/ecosystem/wallet-apps/dev) | Self‑custodial desktop wallet designed for development and testing. | Open-source | +| [wallet.ton.org](/ecosystem/wallet-apps/web) | Self-custodial wallet supports jettons, NFTs, TON DNS, TON Sites, TON Proxy. | TON Core | + From 6f6f3c27a5dc3d9da52c03b2b3001d10510dee90 Mon Sep 17 00:00:00 2001 From: aigerimu <89766357+aigerimu@users.noreply.github.com> Date: Tue, 14 Oct 2025 01:45:28 +0700 Subject: [PATCH 4/4] ci --- ecosystem/wallet-apps/overview.mdx | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/ecosystem/wallet-apps/overview.mdx b/ecosystem/wallet-apps/overview.mdx index c25dbbb4..30ea6130 100644 --- a/ecosystem/wallet-apps/overview.mdx +++ b/ecosystem/wallet-apps/overview.mdx @@ -6,7 +6,9 @@ import { Aside } from '/snippets/aside.jsx'; This article provides an overview of wallet apps built on the standard [wallet contract](/standard/wallets/how-it-works), explaining how they are classified based on _key management, storage method, and intended use_. -