feat: add toncoin processing #7

Kaladin13 · 2025-11-06T10:34:13Z

Linked to ton-org/docs#1101
Closes ton-org/docs#1258

Copilot

Pull Request Overview

This PR introduces a comprehensive payment processing guidebook for the TON blockchain, providing educational TypeScript examples that demonstrate various payment integration patterns using the @ton/ton, @ton/core, and @ton/crypto libraries.

Key Changes:

Implements two deposit tracking approaches: invoice-based (single wallet with UUID comments) and unique address-based (individual wallets per user)
Provides subscription classes for monitoring blockchain transactions via account polling and block streaming
Includes utility functions for payment link generation, configuration management, and environment setup

Reviewed Changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
`package.json`	Defines project dependencies and scripts for running examples
`tsconfig.json`	TypeScript configuration with strict mode and ES2020 target
`src/utils/payment-link.ts`	Utility for generating TON payment deeplinks with UUID tracking
`src/utils/config.ts`	Configuration loader with environment variable support
`src/subscription/BlockSubscription.ts`	Block-level transaction monitoring for the entire blockchain
`src/subscription/AccountSubscription.ts`	Account-specific transaction polling with cursor-based pagination
`src/deposits/invoices.ts`	Invoice-based deposit processing using comment-based UUID tracking
`src/deposits/unique-addresses.ts`	Multi-wallet deposit system with automatic forwarding to hot wallet
`README.md`, `.prettierrc`, `.prettierignore`, `.gitignore`, `.env.example`	Project documentation and configuration files

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

guidebook/toncoin-processing/src/utils/payment-link.ts

guidebook/payment-processing/src/deposits/unique-addresses.ts

guidebook/payment-processing/src/deposits/invoices.ts

guidebook/payment-processing/src/subscription/BlockSubscription.ts

guidebook/payment-processing/src/subscription/AccountSubscription.ts

guidebook/payment-processing/src/deposits/invoices.ts

guidebook/payment-processing/src/deposits/unique-addresses.ts

guidebook/payment-processing/src/deposits/invoices.ts

…n.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull Request Overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 6 comments.

Comments suppressed due to low confidence (1)

guidebook/payment-processing/src/deposits/unique-addresses.ts:28

Unused import toNano.

import { Address, internal, fromNano, toNano, SendMode } from '@ton/core';

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

guidebook/toncoin-processing/.prettierignore

guidebook/payment-processing/src/deposits/unique-addresses.ts

guidebook/payment-processing/src/subscription/AccountSubscription.ts

guidebook/payment-processing/src/deposits/unique-addresses.ts

guidebook/payment-processing/src/deposits/invoices.ts

Copilot

Pull Request Overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

guidebook/payment-processing/src/deposits/jetton-unique-addresses.ts

Copilot

Pull Request Overview

Copilot reviewed 15 out of 16 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-11-12T15:32:23Z

guidebook/payment-processing/src/deposits/jetton-unique-addresses.ts

+        // not internal message check
+        if (!inMessage || inMessage.info.type !== 'internal') {
+            return;
+        }
+
+        // bounced check
+        if (tx.outMessages.size > 0) {


[nitpick] The bounced transaction check appears after the internal message check, but the comment on line 239 says 'bounced check'. This ordering is inconsistent with unique-addresses.ts where the outMessages check comes first (line 260). For consistency and clarity, consider reordering these checks to match the pattern in unique-addresses.ts, or update the comment to accurately reflect what is being checked.

Suggested change

// not internal message check

if (!inMessage || inMessage.info.type !== 'internal') {

return;

}

// bounced check

if (tx.outMessages.size > 0) {

// outMessages check (internal message filter)

if (tx.outMessages.size > 0) {

return;

}

// not internal message check

if (!inMessage || inMessage.info.type !== 'internal') {

Copilot · 2025-11-12T15:32:24Z

guidebook/payment-processing/src/deposits/invoices.ts

+async function main(): Promise<void> {
+    console.log('Starting deposit monitoring...');
+    console.log(`Network: ${IS_MAINNET ? 'MAINNET' : 'TESTNET'}`);
+    console.log(`Wallet: ${MY_WALLET_ADDRESS}`);


This expression always evaluates to false.

Suggested change

console.log(`Wallet: ${MY_WALLET_ADDRESS}`);

console.log(`Wallet: ${MY_WALLET_ADDRESS}`);

// In a real application, LAST_PROCESSED_LT and LAST_PROCESSED_HASH should be loaded from persistent storage (e.g., a database).

verytactical

Obviously a lot of work went into this PR. Thanks a lot!

To progress further on this PR, we'll have to

Separate different demos into separate projects
Put separate projects into separate PRs
Fix styleguide issues, and feedback above

If there is any way we can help, let's hop into OO.

verytactical · 2025-11-17T08:05:18Z

guidebook/payment-processing/README.md

@@ -0,0 +1,5 @@
+# TON Payment Processing Examples
+
+Educational TypeScript examples demonstrating payment processing on the TON blockchain using `@ton/ton`, `@ton/core`, and `@ton/crypto` libraries.


Add links to libraries

verytactical · 2025-11-17T08:08:17Z

guidebook/payment-processing/README.md

+# TON Payment Processing Examples
+
+Educational TypeScript examples demonstrating payment processing on the TON blockchain using `@ton/ton`, `@ton/core`, and `@ton/crypto` libraries.
+


Should include description of entrypoints.

Also should include description of dev processes: which scripts in package.json are for what purpose, especially

start:invoices - this should be npm start

start:unique - is this npm start script, but for a separate project? probably, projects should be actually separated then

payment-link - unclear

build - should it be executed prior to npm start or not? is it merely for checking types?

verytactical · 2025-11-17T08:08:56Z

guidebook/payment-processing/src/deposits/invoices.ts

+ * This example demonstrates how to accept TON coin deposits to a single wallet.
+ *
+ * Flow:
+ * 1. Generate a wallet address once (see wallet setup in separate example)


Once in what period of time? For what purpose?

verytactical · 2025-11-17T08:11:15Z

guidebook/payment-processing/src/deposits/invoices.ts

+ *
+ * Flow:
+ * 1. Generate a wallet address once (see wallet setup in separate example)
+ * 2. For each payment, generate a unique UUID and save it in your database


The script describes "how to accept Toncoin", but this description matches with "how to process a batch of payments".

If this code is supposed to show how to process payment batches, change file description.

If file description is correct, this should be "on each payment", and "generate a unique UUID and save it" should be a subitem.

verytactical · 2025-11-17T08:11:41Z

guidebook/payment-processing/src/deposits/invoices.ts

+ * 1. Generate a wallet address once (see wallet setup in separate example)
+ * 2. For each payment, generate a unique UUID and save it in your database
+ * 3. Provide the user with:
+ *    - Your wallet address


"Your" - whose?

verytactical · 2025-11-17T08:54:45Z

guidebook/payment-processing/src/subscription/BlockSubscription.ts

+
+        let nextSeqno = this.lastProcessedBlock + 1;
+
+        while (nextSeqno <= targetSeqno) {


while loops must never be used in production.

This looks like a

for ( let nextSeqno = this.lastProcessedBlock + 1; nextSeqno <= targetSeqno; nextSeqno += 1 ) { ... }

verytactical · 2025-11-17T08:56:53Z

guidebook/payment-processing/src/utils/config.ts

+export function loadConfig(): Config {
+    const isMainnet = process.env.IS_MAINNET === 'true';
+    const apiKey = process.env.API_KEY || 'YOUR_API_KEY_HERE';
+    const walletAddress = process.env.WALLET_ADDRESS || 'UQB7...5I';


Do not assume values in case config is missing. This must throw.

verytactical · 2025-11-17T08:58:25Z

guidebook/payment-processing/src/utils/payment-link.ts

+    const encodedComment = encodeURIComponent(comment);
+
+    // Build the deeplink
+    return `ton://transfer/${walletAddress}?amount=${amount}&text=${encodedComment}`;


https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams

verytactical · 2025-11-17T09:00:05Z

guidebook/payment-processing/src/utils/payment-link.ts

+
+/**
+ * Generates a UUID for payment tracking
+ * Simple implementation - in production, use a proper UUID library


Proper UUID library is built into Node.

https://nodejs.org/api/crypto.html#cryptorandomuuidoptions

https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID

verytactical · 2025-11-17T09:01:36Z

guidebook/payment-processing/src/utils/payment-link.ts

+ * Example usage
+ */
+export function createPaymentExample(): void {
+    const walletAddress = 'UQB7...5I';


This is not a valid address, and not a running example.

This repo contains code for running examples.

Copilot

Pull Request Overview

Copilot reviewed 13 out of 14 changed files in this pull request and generated 3 comments.

Files not reviewed (1)

guidebook/toncoin-processing/package-lock.json: Language not supported

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-11-17T13:40:47Z

guidebook/toncoin-processing/.gitignore

+# Other private editor folders
+.nvim/
+.emacs/
+.helix/


The .gitignore file is missing the .env entry. While .env.example is provided for configuration, the actual .env file containing sensitive API keys and wallet addresses should be excluded from version control to prevent credential exposure.

Suggested change

.helix/

.helix/

# Environment variable files

.env

Copilot · 2025-11-17T13:40:48Z

guidebook/toncoin-processing/src/deposits/unique-addresses.ts

+    hotWalletAddress: string,
+    networkGlobalId: number,
+): Promise<void> {
+    // Skip outgoing transactions (bounced messages)


The check tx.outMessages.size > 0 filters out transactions with outgoing messages, but the inline comment on line 195 says 'Skip outgoing transactions (bounced messages)'. This is misleading because transactions with outgoing messages aren't necessarily 'outgoing transactions' - they could be incoming transactions that triggered contract execution. The comment should clarify that this filters out transactions that resulted in bounced messages or contract interactions, not just 'outgoing transactions'.

Suggested change

// Skip outgoing transactions (bounced messages)

// Skip transactions that resulted in outgoing messages (e.g., bounced messages or contract interactions)

Copilot · 2025-11-17T13:40:48Z

guidebook/toncoin-processing/src/deposits/invoices.ts

+    console.log('Starting deposit monitoring...');
+    console.log(`Network: ${config.isTestnet ? 'TESTNET' : 'MAINNET'}`);
+    console.log(`Wallet: ${config.walletAddress}`);
+    if (LAST_PROCESSED_LT && LAST_PROCESSED_HASH) {


This expression always evaluates to false.

Kaladin13 added 6 commits November 5, 2025 11:57

init deposit with invoices

70d9f56

readme

28cfb0d

lint

0afa976

persist lt+hash

adcaaa1

add folders and readme

4c46c2c

scripts

6e0b4d1

Kaladin13 mentioned this pull request Nov 10, 2025

feat: add toncoin processing ton-org/docs#1101

Merged

implement unique

fcc3616

Copilot AI review requested due to automatic review settings November 10, 2025 11:11

Copilot AI reviewed Nov 10, 2025

View reviewed changes

Update guidebook/payment-processing/src/subscription/BlockSubscriptio…

2c2a472

…n.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings November 10, 2025 13:28

Copilot AI reviewed Nov 10, 2025

View reviewed changes

novusnota changed the title ~~deat: add processing deposits~~ feat: add processing deposits Nov 11, 2025

Kaladin13 added 2 commits November 12, 2025 17:40

add jettons multi-address

c1e2cf6

add jetton deposits

bb42f62

Kaladin13 mentioned this pull request Nov 12, 2025

feat: add jetton processing ton-org/docs#1202

Merged

fixes

c76b996

Copilot AI review requested due to automatic review settings November 12, 2025 15:10

Copilot started reviewing on behalf of Kaladin13 November 12, 2025 15:10 View session

Copilot finished reviewing on behalf of Kaladin13 November 12, 2025 15:11

Copilot AI reviewed Nov 12, 2025

View reviewed changes

guidebook/payment-processing/src/deposits/jetton-unique-addresses.ts Outdated Show resolved Hide resolved

Kaladin13 and others added 2 commits November 12, 2025 18:22

fix opcode

8a11691

Merge branch 'main' into processing

72516f5

Copilot AI review requested due to automatic review settings November 12, 2025 15:30

Copilot started reviewing on behalf of Kaladin13 November 12, 2025 15:30 View session

Copilot finished reviewing on behalf of Kaladin13 November 12, 2025 15:31

Copilot AI reviewed Nov 12, 2025

View reviewed changes

verytactical changed the title ~~feat: add processing deposits~~ feat: add toncoin processing Nov 17, 2025

verytactical requested changes Nov 17, 2025

View reviewed changes

Kaladin13 added 2 commits November 17, 2025 15:45

chore: scope processing branch to toncoin-processing only

80ffb4b

fix

269386b

Copilot AI review requested due to automatic review settings November 17, 2025 13:38

Copilot started reviewing on behalf of Kaladin13 November 17, 2025 13:39 View session

Copilot finished reviewing on behalf of Kaladin13 November 17, 2025 13:39

Copilot AI reviewed Nov 17, 2025

View reviewed changes

	console.log(`Wallet: ${MY_WALLET_ADDRESS}`);
	console.log(`Wallet: ${MY_WALLET_ADDRESS}`);
	// In a real application, LAST_PROCESSED_LT and LAST_PROCESSED_HASH should be loaded from persistent storage (e.g., a database).

		@@ -0,0 +1,5 @@
		# TON Payment Processing Examples

		Educational TypeScript examples demonstrating payment processing on the TON blockchain using `@ton/ton`, `@ton/core`, and `@ton/crypto` libraries.


		let nextSeqno = this.lastProcessedBlock + 1;

		while (nextSeqno <= targetSeqno) {

-.helix/
+.helix/
+# Environment variable files
+.env

	// Skip outgoing transactions (bounced messages)
	// Skip transactions that resulted in outgoing messages (e.g., bounced messages or contract interactions)

feat: add toncoin processing #7

Are you sure you want to change the base?

feat: add toncoin processing #7

Uh oh!

Conversation

Kaladin13 commented Nov 6, 2025 • edited by verytactical Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

verytactical left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 17, 2025

Choose a reason for hiding this comment

Kaladin13 commented Nov 6, 2025 •

edited by verytactical

Loading