DEXBot2

A sophisticated market making bot for the BitShares Decentralized Exchange (DEX), implementing optimized staggered order strategies for automated trading.

🚀 Features

Staggered Order Grid: Creates geometric order grids around market price for efficient market making.
Dynamic Rebalancing: Automatically adjusts orders after fills to maintain optimal spread.
Multi-Bot Support: Run multiple bots simultaneously on different trading pairs.
PM2 Process Management: Automatic restart and monitoring for production use.
Master Password Security: Encrypted key storage with RAM-only password handling.

🔥 Quick Start

Get DEXBot2 running in 5 minutes:

# 1. Clone and install
git clone https://github.com/froooze/DEXBot2.git && cd DEXBot2 && npm install

# 2. Set up your master password and add bots
node dexbot keys
node dexbot bots

# 3. Start with PM2 (production) or directly
node pm2.js              # Production with auto-restart
node dexbot.js start     # Start all active bots

For detailed setup, see Installation or Updating sections below.

⚠️ Disclaimer — Use At Your Own Risk

This software is in beta stage and provided "as‑is" without warranty.
Secure your keys and secrets. Do not commit private keys or passwords to anyone — use profiles/ for live configuration and keep it out of source control.
The authors and maintainers are not responsible for losses.

📥 Installation

Prerequisites

You'll need Git and Node.js installed on your system.

Windows Users

Install Node.js LTS from nodejs.org (accept defaults, restart after)
Install Git from git-scm.com (accept defaults, restart after)
Verify installation in Command Prompt:
```
node --version && npm --version && git --version
```
All three should display version numbers.

macOS Users

Use Homebrew to install Node.js and Git:

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js and Git
brew install node git

Linux Users

Use your package manager:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install nodejs npm git

# Fedora/RHEL
sudo dnf install nodejs npm git

Clone and Setup DEXBot2

# Clone the repository and switch to folder
git clone https://github.com/froooze/DEXBot2.git
cd DEXBot2

# Install dependencies
npm install

# Set up your master password and keyring
node dexbot keys

# Create and configure your bots
node dexbot bots

Updating DEXBot2

To update DEXBot2 to the latest version from the main branch:

# Run the update script from project root
bash scripts/update.sh

The update script automatically:

Fetches and pulls the latest code from GitHub
Installs any new dependencies
Reloads PM2 processes if running
Ensures your profiles/ directory is protected and unchanged
Keeps your changes to modules/constants.js
Logs all operations to update.log

🔧 Configuration

Define each bot in profiles/bots.json. A minimal structure looks like this:

{
  "bots": [
    {
      "name": "your-name",
      "active": true,
      "dryRun": true,
      "preferredAccount": "example-account",
      "assetA": "IOB.XRP",
      "assetB": "BTS",
      "marketPrice": "pool",
      "minPrice": "3x",
      "maxPrice": "3x",
      "incrementPercent": 0.5,
      "targetSpreadPercent": 2,
      "weightDistribution": { "sell": 0.5, "buy": 0.5 },
      "botFunds": { "sell": "100%", "buy": "100%" },
      "activeOrders": { "sell": 20, "buy": 20 }
    }
  ]
}

⚙️ Configuration Options

Below is a concise description of each configuration option you may set per-bot (use these keys inside each bots entry in examples/bots.json / profiles/bots.json):

name: string — optional friendly name for the bot. Used for logging and selection when calling CLI commands (e.g. dexbot start my-bot).
active: boolean — if false, the bot is kept in the config but not started. Use this to keep templates in your file without running them.
dryRun: boolean — when true the bot simulates orders and does not broadcast transactions on-chain. Use false only after you have verified your settings and secured keys.
preferredAccount: string — the account name to use for on-chain operations; dexbot will prompt once for the master password and reuse it for all bots needing this value.
assetA: string — human-friendly name or symbol of the base asset (the asset you are selling on a sell order). Example: "BTC", "BTS".
assetB: string — human-friendly name or symbol of the quote asset (the asset you receive on a sell order). Example: "USD", "IOB.XRP".
marketPrice: number | string — preferred market price. You may provide a numeric value (e.g. 42000) or let the bot derive it by setting "pool" (use liquidity pool) or "market" (use order book/ticker). If omitted the runtime will attempt to derive it from assetA/assetB.
minPrice: number | string — lower bound for allowed order prices. You may provide a concrete numeric value (e.g. 525) or a multiplier string like "5x". When given as a multiplier the runtime resolves it relative to marketPrice (e.g. "5x" -> marketPrice / 5). Choose values that meaningfully bracket your expected market range to avoid accidental order placement far from the current price.
maxPrice: number | string — upper bound for allowed order prices. You may provide a concrete numeric value (e.g. 8400) or a multiplier string like "5x". When given as a multiplier the runtime resolves it relative to marketPrice (e.g. "5x" -> marketPrice * 5). Choose values that meaningfully bracket your expected market range to avoid accidental order placement far from the current price.
incrementPercent: number — percent step between adjacent order price levels (e.g. 0.5 means 0.5% steps). Smaller values produce denser grids.
targetSpreadPercent: number — target spread (in percent) around the market price that the grid should cover. The manager uses this to place buy/sell layers around the market.
weightDistribution: object — { "sell": <number>, "buy": <number> }. Controls order sizing shape. Values are the distribution coefficient (examples below):
- Typical values: -1 = Super Valley (more weight far from market), 0 = Valley, 0.5 = Neutral, 1 = Mountain (more weight near market), 2 = Super Mountain.
botFunds: object — { "sell": <number|string>, "buy": <number|string> }.
- sell: amount of base asset allocated for selling (absolute like 0.1 or percentage string like "100%").
- buy: amount of quote asset allocated for buying (can be an absolute number like 10000 or a percentage string like "50%").
- buy refers to the quote-side (what you spend to buy base); sell refers to the base-side (what you sell). Provide human-readable units (not blockchain integer units).
- If you supply percentages (e.g. "50%") the manager needs accountTotals to resolve them to absolute amounts before placing orders; otherwise provide absolute numbers.
activeOrders: object — { "sell": <integer>, "buy": <integer> } number of sell/buy orders to keep active in the grid for each side.

💻 CLI & Running

Choosing Your Setup

For Testing & Development (Direct CLI)

Run bots directly with dexbot or node dexbot.js
Quick testing with drystart (simulates orders without broadcasting)
Manual start/stop control
Use this while configuring and testing your bots

For Production (PM2 Process Manager) — Recommended

Runs bots 24/7 with automatic restart on crashes
Professional monitoring and logging
Recommended once you've tested and secured your setup
See PM2 Process Management section below

Direct CLI Commands

You can run bots directly via node dexbot.js or the dexbot CLI wrapper (installed via npm link or run with npx dexbot):

node dexbot.js or dexbot — starts all active bots defined in profiles/bots.json (use examples/bots.json as a template).
dexbot start [bot_name] — start a specific bot (or all active bots if omitted). Respects each bot's dryRun setting.
dexbot drystart [bot_name] — same as start but forces dryRun=true for safe simulation.
dexbot stop [bot_name] — mark a bot (or all bots) inactive; the config file is used the next time the process launches.
dexbot reset [bot_name] — trigger a grid reset (auto-reloads if running, or applies on next start).
dexbot keys — manage master password and keyring via modules/chain_keys.js.
dexbot bots — open the interactive editor in modules/account_bots.js to create or edit bot entries.
dexbot --cli-examples — print curated CLI snippets for common tasks.

dexbot is a thin wrapper around ./dexbot.js. You can link it for system-wide use via npm link or run it with npx dexbot.

If any active bot requires preferredAccount, dexbot will prompt once for the master password and reuse it for subsequent bots.

🎯 PM2 Process Management (Recommended for Production)

For production use with automatic restart and process monitoring, use PM2:

Quick Start (All Bots)

# Start all active bots with PM2
node pm2.js

# Or via CLI
node dexbot.js pm2

This unified launcher handles everything automatically:

BitShares Connection: Waits for network connection
PM2 Check: Detects local and global PM2; prompts to install if missing
Config Generation: Creates profiles/ecosystem.config.js from profiles/bots.json
Authentication: Prompts for master password (kept in RAM only, never saved to disk)
Startup: Starts all active bots as PM2-managed processes with auto-restart

Single Bot via PM2

# Start a specific bot via PM2
node pm2.js <bot-name>

Same as node pm2.js but only starts the specified bot.

Individual Bot (Direct, without PM2)

# Run a single bot directly (prompts for password if not in environment)
node bot.js <bot-name>

PM2 Management Commands

After startup via node pm2.js:

# View bot status and resource usage
pm2 status

# View real-time logs from all bots (or specific bot)
pm2 logs [<bot-name>]

# Reset Grid (Regenerate orders)
dexbot reset [<bot-name>]

# Stop all bots (or specific bot)
pm2 stop {all|<bot-name>}

# Restart process (without reset)
pm2 restart {all|<bot-name>}

# Delete all bots from PM2 (or specific bot)
pm2 delete {all|<bot-name>}

Configuration & Logs

Bot configurations are defined in profiles/bots.json. The PM2 launcher automatically:

Filters only bots with active !== false
Generates ecosystem config with proper paths and logging
Logs bot output to profiles/logs/<bot-name>.log
Logs bot errors to profiles/logs/<bot-name>-error.log
Applies restart policies (max 13 restarts, 1 day min uptime, 3 second restart delay)

Security

Master password is prompted interactively in your terminal
Password passed via environment variable to bot processes (RAM only)
Never written to disk or config files
Cleared when process exits

🔍 Advanced Features

⚛️ Atomic Updates & Partial Order State Management

DEXBot handles filled orders and partial fills with atomic transactions across all operations:

Partial Fills: Remaining portion tracked in PARTIAL state instead of cancellation
Atomic Moves: Partial orders moved to new price levels in single transaction
Fill Detection: Automatically detects filled orders via blockchain history or open orders snapshot
State Synchronization: Grid state immediately reflects filled orders, proceeds credited to available funds
Batch Execution: All updates submitted as single atomic operation (creates + updates + cancellations)
Consistency Guarantee: Either all operations succeed or all fail - no partial blockchain states
No Manual Intervention: Fully automatic fill processing, state updates, and rebalancing

This comprehensive fill handling ensures capital efficiency, eliminates orphaned orders or stuck funds, and guarantees consistency across all order state changes.

🔢 Price Tolerance & Integer Rounding

The bot calculates price tolerances to account for blockchain integer rounding discrepancies. This ensures reliable matching of on-chain orders with grid orders despite minor precision differences.

⏱️ Fill Deduplication

Fills are tracked with a 5-second deduplication window to prevent duplicate order processing. This ensures reliable fill detection even if the same fill event arrives multiple times.

💾 Persistent Grid & Price Caching

DEXBot intelligently caches grid calculations and order prices to avoid unnecessary recalculation:

Grid state persists in profiles/orders/<bot-name>.json across bot restarts
Order prices preserved from the last successful synchronization
No recalculation on startup if grid matches on-chain state
Automatic resync only when on-chain state differs (fills, cancellations)

This optimization significantly reduces startup time and blockchain queries, especially for bots running 20+ orders.

✈️ Offline Filled Order Detection

The bot automatically detects orders that were filled while offline:

Compares persisted grid with current on-chain open orders on startup
Identifies missing orders (orders from grid that are no longer on-chain)
Marks them as FILLED and credits proceeds to available funds
Immediate rebalancing - replaces filled orders on next cycle
No manual intervention needed - fully automatic synchronization

This ensures seamless resumption after being offline without missing fill proceeds.

📡 Periodic Blockchain Fetch

DEXBot can automatically refresh your blockchain account balances at regular intervals to keep order values up-to-date:

Default interval: 240 minutes (4 hours)
Configurable: Set BLOCKCHAIN_FETCH_INTERVAL_MIN in modules/constants.js
Automatic: Runs in background without interrupting trading
Disable: Set interval to 0 or an invalid value to disable periodic fetches

This ensures your bot's internal account balance tracking stays synchronized with the blockchain, especially useful for accounts that receive external transfers or participate in other trading activities.

Configure via environment variable or modules/constants.js:

TIMING: {
    BLOCKCHAIN_FETCH_INTERVAL_MIN: 240  // fetch every 4 hours (0 = disabled)
}

⚡ Automatic Grid Recalculation via Threshold Detection

DEXBot automatically regenerates grid order sizes when market conditions or cached proceeds exceed configurable thresholds. This ensures orders remain optimally sized without manual intervention:

Two Independent Triggering Mechanisms:

Cache & Available Funds Threshold (3% by default)
- Monitors cached funds (proceeds from fills) + newly available funds (deposits)
- Triggers when (cacheFunds + availableFunds) ≥ 3% of allocated grid capital on either side
- Example: Grid 1000 BTS + new deposit 200 BTS available → ratio 20% → triggers update
- Enables automatic fund cycling: new deposits are immediately resized into grid
- Updates buy and sell sides independently based on their respective ratios

Grid Divergence Threshold (10% RMS by default)

Compares currently calculated grid with persisted grid state
What is the RMS Threshold? RMS (Root Mean Square) measures grid divergence as the quadratic mean of relative order size errors—this penalizes uneven distributions. For the same 3.2% average error, uneven distributions require higher RMS thresholds.
```
Mean Squared Diff = Σ((calculated - persisted) / persisted)² / count
RMS = √(Mean Squared Diff)  [Root Mean Square - quadratic mean of relative errors]
Triggers update when: RMS > (RMS_PERCENTAGE / 100)
```

RMS Threshold Reference Table: RMS increases as grid distribution worsens (more uneven/concentrated errors). Uneven distributions need higher thresholds to allow the same average error.

Avg Error	100% Distribution	50% Distribution	25% Distribution	5% Distribution
1.0%	1.0%	1.4%	2.0%	4.5%
2.2%	2.2%	3.1%	4.4%	9.8%
3.2%	3.2%	4.5%	6.4%	14.3%
4.5%	4.5%	6.4%	9.0%	20.1%
7.1%	7.1%	10.0%	14.2%	31.7%
10%	10%	14.1%	20%	44.7%

Default: 14.3% RMS - Allows ~3.2% average error when concentrated in just 5% of orders (most realistic scenario).

When Grid Recalculation Occurs:

After order fills and proceeds are collected
On startup if cached state diverges from current market conditions
Automatically without user action when either threshold is breached
Buy and sell sides can update independently

Benefits:

Keeps order sizing optimal as market volatility or proceeds accumulate
Avoids manual recalculation requests for most scenarios
Reduces grid staleness while minimizing unnecessary regenerations
Maintains capital efficiency by redistributing proceeds back into orders

Customization: You can adjust thresholds in modules/constants.js:

GRID_REGENERATION_PERCENTAGE: 3,  // Cache funds threshold (%)
GRID_COMPARISON: {
    RMS_PERCENTAGE: 14.3  // Grid divergence RMS threshold (%)
}

📌 Trigger-File Grid Regeneration

Create a trigger file profiles/recalculate.<bot-key>.trigger to request immediate grid regeneration on the next polling cycle. This allows external scripts to request recalculation without restarting the bot.

Example:

touch profiles/recalculate.my-bot.trigger

🧮 Standalone Grid Calculator

Use the standalone calculator to dry-run grid calculations without blockchain interaction:

# Calculate grid 5 times with 1-second delays
CALC_CYCLES=5 CALC_DELAY_MS=1000 BOT_NAME=my-bot node -e "require('./modules/order/runner').runOrderManagerCalculation()"

Environment variables:

BOT_NAME or LIVE_BOT_NAME - Select bot from profiles/bots.json
CALC_CYCLES - Number of calculation passes (default: 1)
CALC_DELAY_MS - Delay between cycles in milliseconds (default: 0)

📚 Technical Details

For users interested in understanding the math and mechanics behind DEXBot's order generation and grid algorithms:

🔄 How It Works

Grid Creation: Generates buy/sell orders in geometric progression.
Order Sizing: Applies weight distribution for optimal capital allocation.
Activation: Converts virtual orders to active state.
Rebalancing: Creates new orders from filled positions.
Spread Control: Adds extra orders if the spread becomes too wide.

📐 Order Calculation

The order sizing follows a compact formula:

y = (1-c)^(x*n) = order size

Definitions:

c = increment (price step)
x = order number (layer index; 0 is closest to market)
n = weight distribution (controls how sizes scale across grid)

Weight distribution examples (set n via weightDistribution):

-1 = Super Valley (aggressive concentration towards the edge)
0 = Valley (orders increase linearly towards edge)
0.5 = Neutral (balanced distribution)
1 = Mountain (order increase linearly towards center)
2 = Super Mountain (aggressive concentration towards center)

Output Example

===== ORDER GRID (SAMPLE) =====
Market: IOB.XRP/BTS @ 1831.0833206976029
Price            Type            State           Size
-----------------------------------------------
3660.2208        sell            virtual         0.11175292
3645.6382        sell            virtual         0.11220173
3631.1137        sell            virtual         0.11265234

1864.2743        sell            virtual         0.22000406
1856.8469        sell            virtual         0.22088761
1849.4491        sell            virtual         0.22177471
1842.0808        spread          virtual         0.00000000
1834.7418        spread          virtual         0.00000000
1827.4175        spread          virtual         0.00000000
1812.8274        buy             virtual         422.06696353
1805.5761        buy             virtual         420.37869568
1798.3538        buy             virtual         418.69718090

924.5392         buy             virtual         215.25349670
920.8410         buy             virtual         214.39248272
917.1576         buy             virtual         213.53491279
===============================================

📦 Modules

Below is a short summary of the modules in this repository and what they provide. You can paste these lines elsewhere if you need a quick reference.

🔌 Entry Points

dexbot.js: Main CLI entry point. Handles single-bot mode (start, stop, reset, drystart) and management commands (keys, bots, --cli-examples). Includes full DEXBot class with grid management, fill processing, and account operations.
pm2.js: Unified PM2 launcher. Orchestrates BitShares connection, PM2 check/install, ecosystem config generation from profiles/bots.json, master password authentication, and bot startup with automatic restart policies.
bot.js: PM2-friendly per-bot entry point. Loads bot config by name from profiles/bots.json, authenticates via master password (from environment or interactive prompt), initializes DEXBot instance, and runs the trading loop.

🧩 Core Modules

modules/account_bots.js: Interactive editor for bot configurations (profiles/bots.json). Prompts accept numbers, percentages and multiplier strings (e.g. 5x).
modules/chain_keys.js: Encrypted master-password storage for private keys (profiles/keys.json), plus key authentication and management utilities.
modules/chain_orders.js: Account-level order operations: select account, create/update/cancel orders, listen for fills with deduplication, read open orders. Uses 'history' mode for fill processing which matches orders from blockchain events.
modules/bitshares_client.js: Shared BitShares client wrapper and connection utilities (BitShares, createAccountClient, waitForConnected).
modules/btsdex_event_patch.js: Runtime patch for btsdex library to improve history and account event handling.
modules/account_orders.js: Local persistence for per-bot order-grid snapshots, metadata, and cacheFunds (profiles/orders/<bot-name>.json). Manages bot-specific files with atomic updates and race-condition protection. Note: Legacy pendingProceeds data (pre-0.4.0) is migrated to cacheFunds via scripts/migrate_pending_proceeds.js.

📊 Order Subsystem (`modules/order/`)

Core order generation, management, and grid algorithms:

modules/constants.js: Centralized order constants (types: SELL, BUY, SPREAD; states: VIRTUAL, ACTIVE, PARTIAL), timing constants, and DEFAULT_CONFIG.
modules/order/index.js: Public entry point: exports OrderManager and runOrderManagerCalculation() (dry-run helper).
modules/order/logger.js: Colored console logger and logOrderGrid() helper for formatted output.
modules/order/manager.js: OrderManager class — derives market price, resolves bounds, builds and manages the grid, handles fills and rebalancing.
modules/order/grid.js: Grid generation algorithms, order sizing, weight distribution, and minimum size validation.
modules/order/runner.js: Runner for calculation passes and dry-runs without blockchain interaction.
modules/order/utils.js: Utility functions (percent parsing, multiplier parsing, blockchain float/int conversion, market price helpers).

🔐 Environment Variables

Control bot behavior via environment variables (useful for advanced setups):

MASTER_PASSWORD - Master password for key decryption (set by pm2.js, used by bot.js and dexbot.js)
BOT_NAME or LIVE_BOT_NAME - Select a specific bot from profiles/bots.json by name (for single-bot runs)
PREFERRED_ACCOUNT - Override the preferred account for the selected bot
RUN_LOOP_MS - Polling interval in milliseconds (default: 5000). Controls how often the bot checks for fills and market conditions
CALC_CYCLES - Number of calculation passes for standalone grid calculator (default: 1)
CALC_DELAY_MS - Delay between calculator cycles in milliseconds (default: 0)

Example - Run a specific bot with custom polling interval:

BOT_NAME=my-bot RUN_LOOP_MS=3000 node dexbot.js

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

📄 License

MIT License - see LICENSE file for details

Name		Name	Last commit message	Last commit date
Latest commit History 341 Commits
examples		examples
modules		modules
scripts		scripts
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
bot.js		bot.js
dexbot.js		dexbot.js
package-lock.json		package-lock.json
package.json		package.json
pm2.js		pm2.js

License

froooze/DEXBot2

Folders and files

Latest commit

History

Repository files navigation