feat: add toncoin processing #1101
Draft
+140
−2
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
To fix the formatting issues:
npx remark -o --silent --silently-ignore payments/toncoin.mdx |
|
To fix the formatting issues:
npx remark -o --silent --silently-ignore payments/toncoin.mdx |
|
/review |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
|
To fix the formatting issues:
npx remark -o --silent --silently-ignore payments/toncoin.mdx |
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
|
To fix the formatting issues:
npx remark -o --silent --silently-ignore payments/toncoin.mdx |
|
/review |
anton-trunov
requested changes
Nov 6, 2025
| | Security exposure | One shared hot wallet; a key leak drains the full pool | Each wallet isolates funds; compromise affects only the impacted user | | ||
| | User input requirements | User must include an invoice ID comment; missing or malformed comments need manual recovery workflows | User only needs the destination address | | ||
| | Parsing and validation | Backend parses comments on every deposit and matches to invoices | No parsing; deposit attribution is address-based | | ||
| | Deployment and storage costs | Deploy and maintain a single wallet; storage rent limited to that contract | Deploy many wallets; storage rent and deployment gas scale with user count | |
There was a problem hiding this comment.
Need a link to the storage rent explanation. This is more or less unique to TON blockchain
| | User input requirements | User must include an invoice ID comment; missing or malformed comments need manual recovery workflows | User only needs the destination address | | ||
| | Parsing and validation | Backend parses comments on every deposit and matches to invoices | No parsing; deposit attribution is address-based | | ||
| | Deployment and storage costs | Deploy and maintain a single wallet; storage rent limited to that contract | Deploy many wallets; storage rent and deployment gas scale with user count | | ||
| | Monitoring workload | Poll one address; comment parsing adds CPU but RPC calls stay low | Track many addresses; RPC queries and state tracking grow with the active user base | |
| | Parsing and validation | Backend parses comments on every deposit and matches to invoices | No parsing; deposit attribution is address-based | | ||
| | Deployment and storage costs | Deploy and maintain a single wallet; storage rent limited to that contract | Deploy many wallets; storage rent and deployment gas scale with user count | | ||
| | Monitoring workload | Poll one address; comment parsing adds CPU but RPC calls stay low | Track many addresses; RPC queries and state tracking grow with the active user base | | ||
| | Withdrawal handling | Highload wallet can batch withdrawals from one balance | Need sweeps or coordinated withdrawals from many wallets; extra gas and sequencing logic | |
There was a problem hiding this comment.
highload wallet is mentioned here for the first time -- needs a link
| | Deployment and storage costs | Deploy and maintain a single wallet; storage rent limited to that contract | Deploy many wallets; storage rent and deployment gas scale with user count | | ||
| | Monitoring workload | Poll one address; comment parsing adds CPU but RPC calls stay low | Track many addresses; RPC queries and state tracking grow with the active user base | | ||
| | Withdrawal handling | Highload wallet can batch withdrawals from one balance | Need sweeps or coordinated withdrawals from many wallets; extra gas and sequencing logic | | ||
| | Sharding behavior | All activity hits one shard; throughput limited by that shard | Wallets are distributed across shards; helps spread load | |
There was a problem hiding this comment.
link to the page explaining sharding
| import { Aside } from "/snippets/aside.jsx"; | ||
|
|
||
| <Stub issue="204" /> | ||
| Processing Toncoin payments requires choosing between two architectural approaches: invoice-based deposits to a single address, common to all users or unique deposit addresses per user. Each approach has different security characteristics, implementation complexity, and operational requirements. |
There was a problem hiding this comment.
To make the exposition more self-contained and given this most likely will be read by seasoned Web3 engineers, let's add a brief note that TON blockchain does not have Ethereum-like externally owned accounts and probably link to the "Coming from Ethereum" page as well.
| Environment: validate the full flow on testnet before using mainnet. | ||
| </Aside> | ||
|
|
||
| Wallet deployment happens lazily when users first request their deposit address. Generate the address deterministically without deploying the contract. When the user sends their first deposit to the un-deployed address, send the transaction in non-bounceable mode. The contract doesn't exist yet, so bounceable messages would return the funds. After the first deposit arrives, deploy the contract using funds from that deposit or from an external source. |
There was a problem hiding this comment.
link to the place the distinction between bounceable and unbounceable messages is explained
| - Withdrawal processing requires coordination across wallets | ||
| - Storage fees apply to each deployed contract (currently \~0.001 TON per year per contract) | ||
|
|
||
| Reference education-only implementation: [Unique address Toncoin deposits](https://github.com/ton-org/docs-examples/blob/processing/guidebook/payment-processing/src/deposits/unique-addresses.ts). |
There was a problem hiding this comment.
Suggested change
| Reference education-only implementation: [Unique address Toncoin deposits](https://github.com/ton-org/docs-examples/blob/processing/guidebook/payment-processing/src/deposits/unique-addresses.ts). | |
| To understand this approach in greater detail, see the following TypeScript implementation: [Unique address Toncoin deposits](https://github.com/ton-org/docs-examples/blob/processing/guidebook/payment-processing/src/deposits/unique-addresses.ts). |
There was a problem hiding this comment.
Again, let's add an "Aside" to mark this as "not production-ready code, use only for educational purposes"
|
|
||
| ## Common abuse patterns | ||
|
|
||
| - Reusing a previously settled invoice identifier to trigger duplicate credits when the backend does not invalidate the invoice after first use. |
There was a problem hiding this comment.
Suggested change
| - Reusing a previously settled invoice identifier to trigger duplicate credits when the backend does not invalidate the invoice after first use. | |
| - Reusing a previously settled invoice identifier to trigger duplicate credits when the backend does not invalidate the invoice after the first use. |
|
|
||
| ## Monitoring best practices | ||
|
|
||
| Implement exponential backoff for RPC failures. Network issues or node maintenance can interrupt transaction polling. When `getTransactions` fails, wait before retrying with increasing delays to avoid overwhelming the endpoint. |
There was a problem hiding this comment.
need to link to the definition of getTransactions
|
|
||
| Implement exponential backoff for RPC failures. Network issues or node maintenance can interrupt transaction polling. When `getTransactions` fails, wait before retrying with increasing delays to avoid overwhelming the endpoint. | ||
|
|
||
| Store transaction state persistently. Record the last processed `lt` value and transaction hash to resume monitoring after restarts without reprocessing transactions. This prevents duplicate deposit credits. |
There was a problem hiding this comment.
explain lt means "logic time" and link to the corresponding page
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Closes #204