TON payment processor

[![Based on TON][ton-svg]][ton] [![Telegram][telegram-svg]][telegram-url]

Microservice for accepting payments and making withdrawals to wallets in TON blockchain.
Supports TON coins and Jettons (conforming certain criteria)
Provides REST API for integration. Service is ADNL based and interacts directly with node and do not use any third party API.

Warning Manual withdrawals from hot wallet is prohibited do not withdraw funds from a hot wallet bypassing the service, this will lead to a service error

How it works
- Features
Glossary
Prerequisites
- Criteria for valid Jettons
Deployment
- Configurable parameters
- Service deploy
Payment notifications
Binary comment support
REST API
Technical notes
Threat model
Manual migrations
TODO list

test_dashboard db_dashboard

How it works

The service provides the following functionality:

generate new deposit address of wallet (TON or Jetton) for TON blockchain. This address you provide to customer for payment. Payments are accumulated in the hot-wallet.
make withdrawal of TONs or Jettons from hot-wallet to customer wallet at TON blockchain.

Features

Deposit addresses can be reused for multiple payments
Sends withdrawals with comment
Sends withdrawals in batches using highload wallet
Aggregates part of TONs or Jettons at cold-wallet
Supports authorization by Bearer token
Service withdrawals (cancellation of incorrect payments)

Glossary

deposit-address - address generated by the service to which users send payments.
deposit - blockchain account with deposit-address
hot-wallet - wallet for aggregation all incoming TONs and Jettons from deposit-addresses.
cold-wallet - wallet to which part of the funds from the hot wallet is sent for security. Cold-wallet seed phrase is not used by the service.
user_id - unique text value to identify deposit-addresses or withdrawal request for a specific user.
query_id - unique text value to identify withdrawal request for a specific user to prevent double spending.
basic unit - minimum indivisible unit for TON (e.g. for TON basic unit = nanoTONs) or Jetton.
hot_wallet_minimum_balance - minimum TON balance in nanoTONs at hot wallet to start service.
hot_wallet_maximum_balance - maximum balance (of TONs or Jettons) in basic units at hot wallet. Anything more than this amount will be withdrawn to a cold wallet.
minimum_withdrawal_amount - minimum balance (of TONs or Jettons) in basic units at deposit account to make withdrawal to hot wallet. It is necessary to prevent the case when the withdrawal fee will be close to the balance on the deposit.

Prerequisites

Need minimum (configured) amount of TONs at HighloadV2 wallet address correlated with seed phrase or already deployed HighloadV2 wallet.
To ensure the reliability and security of the service, you need to provide your own TON node (with lite server) on the same machine as the service. If you want to use an untrusted node (such as a rented node), you need to set PROOF_CHECK_ENABLED=true and specify NETWORK_CONFIG_URL.
Jettons used must meet certain criteria

Criteria for valid Jettons

conforming to the standard TEP-74
the Jetton wallet should not spontaneously change its balance, only with transfer.
fee for the withdrawal of Jettons from the wallet should not be too high and meet the internal setting of the service

For more information on Jettons compatibility, see Jettons compatibility

Deployment

Configurable parameters

| ENV variable | Description | |------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | LITESERVER | IP and port of lite server, example: 185.86.76.183:5815 | | LITESERVER_KEY | public key of lite server 5v2dHtSclsGsZVbNVwTj4hQDso5xvQjzL/yPEHJevHk=. Be careful with base64 encoding and ENV var. Use '' | | LITESERVER_RATE_LIMIT | If you have a rented node with an RPS limit, set the RPS value here equal to (or preferably slightly less than) the limit. Default: 100. | | SEED | seed phrase for main hot wallet. 24 words compatible with standard TON wallets | | DB_URI | URI for DB connection, example: postgresql://db_user:db_password@localhost:5432/payment_processor | | POSTGRES_DB | name of database for storing payments data | | POSTGRES_READONLY_PASSWORD | password for grafana readonly db user | | API_PORT | port for REST API, example 8081 | | API_TOKEN | Bearer token for REST API, example 123 | | IS_TESTNET | true if service works in TESTNET, false - for MAINNET. Default: true. | | JETTONS | list of Jettons, processed by service in format: JETTON_SYMBOL_1:MASTER_CONTRACT_ADDR_1:hot_wallet_max_balance:min_withdrawal_amount:hot_wallet_residual_balance, JETTON_SYMBOL_2:MASTER_CONTRACT_ADDR_2:hot_wallet_max_balance:min_withdrawal_amount:hot_wallet_residual_balance, example: TGR:kQCKt2WPGX-fh0cIAz38Ljd_OKQjoZE_cqk7QrYGsNP6wfP0:1000000:100000 | | TON_CUTOFFS | cutoffs in nanoTONs in format: hot_wallet_min_balance:hot_wallet_max_balance:min_withdrawal_amount:hot_wallet_residual_balance, example 1000000000:100000000000:1000000000:95000000000 | | `COLD_WALL

Bicycle

Install / Use

README