Technical Onboarding (Stack & Services)
For engineers who need the technical map: service boundaries, data flow, packages, and where to extend for wallet/sweep/withdrawal and cost efficiency.
Companion: Onboarding Portal (quick links) · DEVELOPER_ONBOARDING.md (full narrative)
1. Stack at a Glance
| Layer | What | Where |
|---|---|---|
| Entry | Gateway (REST, JWT, proxy), Telegram Bot (webhook) | services/gateway, services/telegrambot |
| Core business | Wallet, Account, Market, Payment, Swap, Withdrawal, Voucher, Ledger, Storage | services/{wallet,account,market,payment,swap,withdrawal,voucher,ledger,storage} |
| Blockchain | Watchers (TON, TRON, ETH, BNB, BTC) | services/watcher + per-chain under internal/watcher/chains/ |
| Shared libs | Blockchain (signers, tx builders, TWC, fee, broadcaster), RPC, Vault, Logger, Metrics | packages/blockchain, packages/rpc, packages/vault, etc. |
| Schema | Protos + generated Go | shared-schema/proto, shared-schema/proto-gen/go |
| Deploy | Docker Swarm, Traefik | docker-compose.swarm.yml |
2. Request Flow (Technical)
- User → Gateway (REST) → Gateway calls Wallet (gRPC/HTTP), Account, Market, Payment, Withdrawal, etc.
- Deposits: Watcher (per chain) → Postgres (deposits, cursor) → Ledger (credit) + RabbitMQ (notify bot).
- Withdrawals: Gateway/Admin → Withdrawal service → Wallet (sign via gRPC) → Broadcaster (RPC) → chain. Fiat path: Withdrawal → Payment (PayStar).
- Sweeps: Wallet service (balance scanner + sweeper) → deposit-address keys from HD → TxBuilder + Signer → Broadcaster.
Key technical details:
- Wallet owns HD derivation (BIP39/44), deposit addresses per user/chain, hot wallet (index 0), and sweep (planner → executor).
- Withdrawal owns state machine (pending → in_progress → confirmed → completed), batch processor (EVM multisend when supported), and hot-wallet signing via Wallet gRPC.
- Signing: Pure-Go signers by default; optional Trust Wallet Core (TWC) behind build tag
twc(packages/blockchain/twc, wallet + withdrawal use it when enabled).
3. Packages You’ll Touch
| Package | Purpose | Use when |
|---|---|---|
packages/blockchain/txbuilder |
Build unsigned tx (EVM, TRON, TON, multisend) | Sweep, withdrawal, any new chain tx |
packages/blockchain/twc |
TWC protobuf SigningInput (EVM, TRON, TON) | When building/signing with TWC |
packages/blockchain/tronresource |
TRON energy/bandwidth (Phase 1: pay-per-tx; Phase 2: freeze/rent) | TRON cost optimization |
packages/blockchain/broadcaster |
Submit signed tx (ETH, TON, TRON) | After signing |
packages/blockchain/fee |
Gas/fee estimation | Withdrawal, sweep |
packages/blockchain/hotwallet |
Hot wallet manager | Withdrawal hot wallet |
packages/rpc |
Chain RPC clients, provider health, circuit breaker | Watchers, wallet balance, broadcast |
4. Where to Extend (Cost & Efficiency)
- User wallet generation / deposit addresses:
services/wallet(CreateHDWallet, deposit address by chain). No change needed for “one address per user per chain”; for gas/energy efficiency, see Gas and Energy Efficiency. - TRON energy/dust:
packages/blockchain/tronresource/manager.go(Phase 2: freeze/rent, estimate cost). TRON tx build:packages/blockchain/txbuilder/tron.go; TWC TRON:packages/blockchain/twc/tron_builder.go. - EVM gas / batch:
packages/blockchain/txbuilder/evm.go(multisend, gas params);packages/blockchain/twc/evm_builder.go(BuildMultisendSigningInput). Withdrawal already batches EVM via multisend when supported. - Sweeps:
services/wallet/internal/wallet/service/sweeper/(planner, executor, balance scanner). Executor uses txbuilder + signer; adjust gas/energy here for cost. - Withdrawals:
services/withdrawal/internal/withdrawal/service/withdrawal_service_v2.go(batch processor, multisend path). Gas safety:gas_safety.go; risk:risk_engine.go. - TWC / L2:
packages/blockchain/twc(EVM, TRON, TON protobufs). New chains or L2 = new SigningInput builder + signer route; contracts we can leverage are documented in the gas/energy guide.
5. Docs That Match This Map
- Architecture Portal — high-level architecture.
- Operations Portal — deploy, rollback, runbooks.
- Gas and Energy Efficiency — TRON energy, EVM batch/permit, and implementation map.
- TWC Audit & Zero-Fee Strategy — Trust Wallet (app) patterns, TWC batch/UserOp/Paymaster (use them, don’t overwrite), zero-fee and infrastructure goals.
- Signer Implementation — signers and TWC.
- Wallet Service — wallet and sweep flows.
- Remaining Tasks — Tier A hardening and backlog.
6. Quick Commands (Technical)
# Build wallet with TWC
CGO_ENABLED=1 go build -tags twc -o wallet-service ./services/wallet/cmd/server
# Run one watcher locally (e.g. TRON)
go run ./services/watcher/cmd/main.go --chain=tron
# Migrations (wallet DB)
cd services/wallet && go run cmd/migrator/main.go
Last updated: 2026-02-04