ADAMANT Exchange Bot v3.0.0: runtime modernization, consensus-grade funds safety, and deposit claims tracking

[al-onyxprotocol]

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 (ethers 6, bitcoinjs-lib 7 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.

Security Note: Security audited and maintained by cryptofoundry in collaboration with the ADAMANT developer community.

---

1. Stack & Architecture Modernization

The codebase was brought up to modern Node.js ecosystem standards, removing legacy dependencies and unifying asynchronous execution:

• Node.js 22.13+ LTS: Upgraded runtime requirements (package.json engines and .nvmrc)
• Ethers 6 Migration: Fully replaced legacy web3-eth and web3-utils with ethers v6 for Ethereum and ERC-20 token interactions, providing deterministic contract calls, accurate gas estimations, and reliable nonce management
• BitcoinJS-lib 7 & PSBT Workflow: Migrated Bitcoin, Dash, and Dogecoin transaction construction to Partially Signed Bitcoin Transactions (PSBT), completely removing the deprecated TransactionBuilder
• MongoDB 7 Native Async Driver: All queries across payments, incomingtxs, and systems collections now use native Promise-based async/await syntax, eliminating legacy callback patterns
• Adamant-API 3.x: Upgraded node client integration using AdamantApi and WebSocketClient with modern key-derivation helpers
• Complete Lisk (LSK) Removal: Purged legacy @liskhq/* dependencies, lsk_utils.js, lskBaseCoin.js, and associated configuration options (node_LSK, service_LSK)
• Development Tooling: Adopted ESLint 9 flat configuration (eslint.config.js), Prettier 3, and Jest 30

---

2. 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:

• An asynchronous memory mutex locks selected UTXOs during PSBT creation and signing
• UTXOs remain locked until broadcast confirmation is verified on the network
• If a transaction assembly or broadcast fails, the locked UTXOs are safely released back to the available pool, preventing stalled balances without risking double-spends

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:

• Mempool Monitoring (modules/depositWatcher.js): Monitors unconfirmed and incoming transactions using each adapter's getPendingIncomingTransactions implementation without reliance on centralized webhooks
• Deposit Claims Management (modules/depositClaims.js): Tracks deposit claims across their lifecycle to prevent duplicate claiming of the same on-chain transaction hash
• 5-Minute Dispute Window: External deposits undergo a mandatory 5-minute dispute window to guard against blockchain reorgs, race attacks, and double-claim exploits before payout execution
• KVS Verification (modules/deepExchangeValidator.js): Cryptographically verifies the deposit against the sender's ADAMANT Key-Value Storage (KVS) address records with caching and automatic retry logic

---

4. Exchange UX & Chat Command Enhancements

• /cancel Command: Users who send a deposit without specifying an exchange pair (inUpdateState: 'outCurrency') can now issue /cancel (or cancel) in chat to cancel the pending exchange and automatically receive their deposit back (minus the network transaction fee)
• Abandoned Deposit Auto-Refund: If a user with a deposit in inUpdateState sends 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 state
• Exponential Number Representation: Refactored utils.formatNumber to 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 tokens
• Onyxcoin (XCN) Token: Added native configuration and registry support for XCN ERC-20 token

---

5. Configuration Schema & Multi-Node Failover

• Pure Schema Validation (modules/configSchema.js): Configuration files (config.jsonc, config.default.jsonc) are strictly validated against declarative schemas at startup. Missing keys, unknown cryptocurrencies in accepted_crypto, or coins configured without nodes trigger immediate fail-fast errors
• Resilient Multi-Node Client (helpers/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 nodes
• Granular Per-Ticker Overrides: Operators can specify ticker-specific overrides for network fees (exchange_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

• Comprehensive Test Suite: 31 Jest test suites containing 690 unit tests covering core exchange modules, cryptocurrency adapters, configuration schemas, and utilities without requiring live nodes, MongoDB, or real private keys
• AI Agent Operating Manual (AGENTS.md): Formalized repository conventions, technical architecture map, invariant guidelines, and change discipline rules

---

Links & Resources

• GitHub Release: v3.0.0 Release Notes & Assets
• Source Repository: Adamant-im/adamant-exchangebot
• Ecosystem Article: Multiple anonymous crypto exchanges on the ADAMANT platform
• Security & Development: cryptofoundry
• ADAMANT Messenger: adamant.im