ADAMANT Exchange Bot v3.0.0: runtime modernization, consensus-grade funds safety, and deposit claims tracking #79
al-onyxprotocol
started this conversation in
Ecosystem & Integrations
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
ADAMANT Exchange Bot is self-hosted software that allows operators to run an instant, anonymous cryptocurrency exchange directly inside end-to-end encrypted ADAMANT Messenger chats. The bot operates hot wallets across multiple blockchains (Bitcoin, Ethereum, Dash, Dogecoin, and ADAMANT) without third-party custodians, accounts, or exposed web interfaces.
Version 3.0.0 is a major architectural milestone. It modernizes the underlying runtime stack to Node.js 22 LTS, transitions cryptography and blockchain integration to modern libraries (
ethers6,bitcoinjs-lib7 PSBT), enforces consensus-grade funds-safety invariants through UTXO and request-level mutex locking, and introduces an external deposit claims watcher with a 5-minute dispute window.1. Stack & Architecture Modernization
The codebase was brought up to modern Node.js ecosystem standards, removing legacy dependencies and unifying asynchronous execution:
package.jsonengines and.nvmrc)web3-ethandweb3-utilswithethersv6 for Ethereum and ERC-20 token interactions, providing deterministic contract calls, accurate gas estimations, and reliable nonce managementTransactionBuilderpayments,incomingtxs, andsystemscollections now use native Promise-based async/await syntax, eliminating legacy callback patternsAdamantApiandWebSocketClientwith modern key-derivation helpers@liskhq/*dependencies,lsk_utils.js,lskBaseCoin.js, and associated configuration options (node_LSK,service_LSK)eslint.config.js), Prettier 3, and Jest 302. Concurrency Guarantees & Funds Safety Invariants
Operating an unattended exchange bot requires consensus-grade financial safety: rates, fees, decimals, and balances must be exact, and payouts or refunds must remain strictly idempotent.
UTXO Mutex Locking (
helpers/mutex.js/btcBaseCoin.js)On UTXO-based chains (BTC, DASH, DOGE), concurrent payouts or refunds risked race conditions where multiple transactions attempted to spend the same unspent outputs. In v3.0.0:
Sender-Level Request Serialization
Incoming chat commands, new transfer events, and cancellation requests from the same user are synchronized via a per-sender mutex lock in
incomingTxsParser.js. This eliminates race conditions when users send simultaneous transfers or attempt to trigger refunds during state transitions.Idempotency and Restart Recovery
Every payment record transitions through deterministic states (
inProcessing,needToSendBack,sent,refunded) persisted to MongoDB before network transmission. If the bot restarts or encounters an interrupted connection mid-transfer, pending payments are safely reconciled and resumed without double-spending funds.3. Deposit Watcher & Claims Lifecycle
External blockchain deposits (BTC, ETH, ERC-20, DASH, DOGE) require correlation between on-chain transactions and ADAMANT chat identities:
modules/depositWatcher.js): Monitors unconfirmed and incoming transactions using each adapter'sgetPendingIncomingTransactionsimplementation without reliance on centralized webhooksmodules/depositClaims.js): Tracks deposit claims across their lifecycle to prevent duplicate claiming of the same on-chain transaction hashmodules/deepExchangeValidator.js): Cryptographically verifies the deposit against the sender's ADAMANT Key-Value Storage (KVS) address records with caching and automatic retry logic4. Exchange UX & Chat Command Enhancements
/cancelCommand: Users who send a deposit without specifying an exchange pair (inUpdateState: 'outCurrency') can now issue/cancel(orcancel) in chat to cancel the pending exchange and automatically receive their deposit back (minus the network transaction fee)inUpdateStatesends a subsequent transfer rather than clarifying the target currency, the bot queues the previous deposit for automatic refund instead of abandoning it in an ignored stateutils.formatNumberto expand scientific notation (e+/e-) into human-readable, full decimal strings before digit grouping and bolding, eliminating malformed spaces or exponent artifacts on high-magnitude numbers or high-decimal tokens5. Configuration Schema & Multi-Node Failover
modules/configSchema.js): Configuration files (config.jsonc,config.default.jsonc) are strictly validated against declarative schemas at startup. Missing keys, unknown cryptocurrencies inaccepted_crypto, or coins configured without nodes trigger immediate fail-fast errorshelpers/cryptos/nodeClient.js): HTTP and JSON-RPC node calls automatically round-robin and fail over across configured endpoints, ensuring resilience against offline or desynchronized blockchain nodesexchange_fee_<COIN>), required confirmations (min_confirmations_<COIN>), daily USD volume limits (daily_limit_usd_<COIN>), and pricing limits (fixed_buy_price_usd_<COIN>,min_sell_price_usd_<COIN>)6. Testing & AI Operating Manual
AGENTS.md): Formalized repository conventions, technical architecture map, invariant guidelines, and change discipline rulesLinks & Resources
All reactions