Skip to content

Blockchain bridges ​

Crypto deposits and withdrawals need two things working together: the platform's scheduled tasks, which watch for deposits and track withdrawals, and a small bridge service for each network, which creates addresses and signs transactions.

20 minutesServer administrationDevOpsVerified against the platform code

Who does what ​

StepDone by
Create a user's deposit addressThe network's bridge (/wallet/create)
Notice a new depositdeposits:scan (or the network's monitor), which asks a block explorer API or the network's node every minute
Move the deposit into the hot walletdeposits:sweep, which asks the bridge to send it (and to top up the fee coin first, for tokens)
Send a withdrawalThe bridge (/wallet/withdraw/...), signed with the hot wallet's key
Confirm a withdrawal arrivedThe bridge writes the transaction into the withdrawal; withdrawals:sync then pays it out (or refunds it once if the bridge marked it failed)
Hot wallet balances in reportsScheduled wallets:*-balance tasks, through the bridge

The full task list is in Scheduler → Deposits and withdrawals.

The bridges ​

BridgeFolderPortNode / RPC variableDefault if empty
Ethereumbridges/ethereum8000APP_ETHEREUM_NODEnone, required
BNB Smart Chainbridges/bnb8001APP_BNB_NODEhttps://bsc-dataseed.binance.org
Tronbridges/tron8002APP_TRON_NODE, APP_TRONGRID_API (TronGrid API key, optional but recommended)https://api.trongrid.io (mainnet)
Polygonbridges/polygon8003APP_POLYGON_NODEhttps://polygon-rpc.com
Solanabridges/solana8006SOLANA_RPC_ENDPOINThttps://api.mainnet-beta.solana.com
TONbridges/ton8007 (APP_TON_PORT)TON_RPC_ENDPOINT, TON_API_KEYhttps://toncenter.com/api/v2/jsonRPC

The bridges read the platform's main .env (they look for it one folder up from where you start them), including the database settings. The platform finds them at http://localhost:<port>. If you run a bridge elsewhere, point the platform to it with APP_ETHEREUM_URL, APP_BSC_URL, APP_TRON_URL, APP_POLYGON_URL, APP_SOLANA_URL or APP_TON_URL.

Use your own node provider

The free public endpoints are rate-limited and can drop requests during busy periods. For a live exchange, use a paid provider (Infura, Alchemy, QuickNode, Ankr and others) for every network you offer. Ethereum has no default at all: without APP_ETHEREUM_NODE the Ethereum bridge can't work.

Block explorer API keys ​

Deposit detection on Ethereum, BNB Smart Chain and Polygon uses the Etherscan API (V2). Add the keys to .env. None of them are in .env.example:

ini
APP_ETHERSCAN_KEY=your-etherscan-key    # Ethereum (ETH and ERC-20)
APP_BSCSCAN_KEY=your-etherscan-key      # BNB Smart Chain (BNB and BEP-20)
APP_POLYGONSCAN_KEY=your-etherscan-key  # Polygon

One Etherscan V2 key works for all three chains. Get it at etherscan.io/apis.

One key or five

Each variable takes one key, or exactly five keys separated by commas. With five, the platform uses a different key for each part of the hour to stay under the free rate limit. Two, three or four keys cause errors in some minutes of every hour.

Tron deposits are read from the public Tronscan API, which needs no key. Solana, TON and XRP deposits are read from the network's node.

Install ​

bash
cd /var/www/exchange/bridges && npm install
for network in ethereum bnb tron polygon solana ton; do
  (cd $network && npm install)
done

Don't use npm run install:all

That script also tries to install a custom-evm-token-node folder that isn't included, so it stops with an error at the end.

Start ​

Run them from the bridges folder, as the web server user, and only for the networks you offer:

bash
cd /var/www/exchange/bridges
pm2w start ethereum/app.js --name bridge-ethereum
pm2w start bnb/app.js      --name bridge-bnb
pm2w start tron/app.js     --name bridge-tron
pm2w start polygon/app.js  --name bridge-polygon
pm2w start solana/app.js   --name bridge-solana
pm2w start ton/app.js      --name bridge-ton
pm2w save

pm2w is the alias from Installation → Prepare PM2. Bridges aren't managed by pm:watcher. PM2 restarts them if they crash, and pm2 startup brings them back after a reboot.

Logs and health checks ​

bash
pm2w status                    # every bridge-* should be online
pm2w logs bridge-ethereum      # live log of one bridge

On start, each bridge logs which .env file it loaded ([env-loader] Auto-detected .env from: …). If it says No .env file found, start it from the bridges folder.

Quick checks from the server:

bash
curl -s http://localhost:8000/wallet/create   # Ethereum: returns a new address (not saved anywhere)
curl -s http://localhost:8007/                # TON: answers when running

Admin → System Monitor checks the API of every network and marks it online or offline.

Keep bridge ports private

The bridges listen on all network interfaces and have no password. Anyone who can reach ports 8000–8007 could ask them to send funds. Block them from outside and allow only the server itself:

bash
sudo ufw deny 8000:8007/tcp

Tron used to run on the test network

Older copies of the Tron bridge were hard-coded to the Shasta testnet. The bridge now uses mainnet (https://api.trongrid.io) unless APP_TRON_NODE says otherwise. To test with test coins, set APP_TRON_NODE=https://api.shasta.trongrid.io (or the Nile testnet).

What a bridge reports back ​

Every withdrawal ends in one of three results:

ResultWhenWhat the platform does
SentThe network accepted the transaction (and, where the bridge waits, confirmed it)Saves the transaction hash; the withdrawal is done
Not sentIt was refused before or by the network, so nothing left the hot wallet (bad address or amount, not enough balance, refused broadcast, failed on chain, expired)Marks it failed and returns the coins to the user
UnknownThe connection dropped while sending, or no confirmation came backNothing is changed. The withdrawal is held under Needs review, so it's never refunded while the coins may already be gone

Other things the bridges now check:

  • Amounts are converted exactly. Floating-point rounding used to send, for example, 1.004999 instead of 1.005 USDT on Tron.
  • The Solana bridge answers the platform straight away and finishes deposit collection in the background. It used to wait for confirmation and time out.
  • The TON bridge refuses to send when the hot wallet key doesn't belong to the hot wallet address in settings. It reports a transfer as sent only when the wallet's own transaction contains the payment, so a deposit landing at the same moment can't be taken for it. Deposits are found whichever address form (EQ… or UQ…) is saved in settings.
  • One bad request no longer stops a bridge: errors are logged and the bridge keeps serving.
  • Merchant payouts, refunds and fund collection use the same withdraw and sweep routes as users; the request says which table gets the result (bridges/result-target.js, next to env-loader.js; deploy it with the bridges). The old merchant-only routes (/wallet/transfer/<coin>, /wallet/transfer/spl, /wallet/merchant/sweep/...) are gone.

Hot wallets and gas ​

Each network has a hot wallet, set in Admin → Settings → Hot wallets. It pays withdrawals and receives collected deposits. Keep in it:

  • enough of every coin and token to cover a day of withdrawals, and
  • enough of the network's own coin (ETH, BNB, TRX, POL, SOL, TON) for fees. Collecting a token deposit first sends a little of that coin to the user's address to pay for the transfer.

If the fee coin runs out, token deposits stay at the users' addresses and withdrawals fail. Watch balances in Reports → System wallets, and move the excess to cold storage with Cold storage rules.

XRP and TON: one address, many memos ​

On XRP Ledger and TON, every user deposits to the same hot wallet address, with their own memo / destination tag. The deposit screen shows both, and users must include the memo.

CommandWhat it does
ripple:system-wallet-generate, ton:system-wallet-generateCreate a new hot wallet and save it in settings
ripple:refresh-system-wallet, ton:refresh-system-walletCreate a new hot wallet and delete every user's memo, so users get new ones

These commands replace your hot wallet

Both commands generate a new wallet and overwrite the saved key. Funds left in the old wallet stay there, and you can reach them only if you kept its key. Before running either: move the funds out, and write down the old address and key.

The XRP and TON deposit monitors (ripple:monitor-xrp-deposits, ton:monitor-ton-deposits) aren't in the scheduler (TON withdrawals are finished by withdrawals:sync automatically). If you offer XRP or TON, add the monitors to app/Console/Kernel.php, next to the other networks:

php
$schedule->command('ripple:monitor-xrp-deposits')->everyMinute()->withoutOverlapping();
$schedule->command('ton:monitor-ton-deposits')->everyMinute()->withoutOverlapping();

Bitcoin ​

Bitcoin doesn't use a bridge. The platform talks to your own Bitcoin Core node over RPC:

ini
BITCOIND_HOST=127.0.0.1
BITCOIND_PORT=8332
BITCOIND_USER=rpc-user
BITCOIND_PASSWORD=rpc-password

The node tells the platform about deposits. Add this to its bitcoin.conf:

ini
walletnotify=curl -s "https://yourdomain.com/api/v1/gateways/bitcoin/BTC?txn=%s"

The platform then reads the transaction from your node and credits it after the currency's minimum deposit confirmations (set on the currency in Admin → Currencies).

Adding tokens on supported networks ​

You don't need a new bridge for a new token on Ethereum, BNB Smart Chain, Tron, Polygon or Solana:

  1. Create the currency in Admin → Currencies. The symbol must match the token contract's symbol, and decimals must match the token's decimals.
  2. Add the network to it, and enter the token's contract address exactly as shown on the network's block explorer.
  3. Set minimum deposit, withdrawal limits and fees.
  4. Test with a small deposit and a small withdrawal before announcing it.

Check the contract address twice

A wrong contract address means deposits of the real token are never detected, and withdrawals send a different token. Copy it from the token's official site or the block explorer, never from a chat message.

Owner documentation for the CryptoTech exchange platform.