dexbot 1.4.16 → 1.4.18

package/docs/MPA_CREDIT_USAGE.md

@@ -0,0 +1,353 @@
+# MPA and Credit Usage
+
+DEXBot2 supports native BitShares debt workflows through the bot-level `debtPolicy` config block. Each lending item declares its own collateral asset, and the runtime groups items by collateral to compute independent distributions. For the related AMA/grid side, see [Market Adapter](../market_adapter/README.md).
+
+## Contents
+
+- [Configuration Format](#configuration-format)
+- [Credit-Only Mode](#credit-only-mode)
+- [Collateral Distribution](#collateral-distribution)
+- [Runtime Timing](#runtime-timing)
+- [MPA Maintenance](#mpa-maintenance)
+- [Credit Offer Maintenance](#credit-offer-maintenance)
+- [LP-Backed Credit Collateral](#lp-backed-credit-collateral)
+- [State Files](#state-files)
+- [Operational Notes](#operational-notes)
+- [Related Files](#related-files)
+
+## Which section do I need?
+
+| If you want to… | Read this | Key file / field |
+|-----------------|-----------|-------------------|
+| Configure a bot to borrow MPAs or credit offers | [Configuration Format](#configuration-format) | `debtPolicy.lending` in `bots.json` |
+| Understand how collateral is split across lending items | [Collateral Distribution](#collateral-distribution) | `outputWeight` |
+| Change how often the credit watchdog runs | [Runtime Timing](#runtime-timing) | `TIMING` in `constants.ts` |
+| Know what happens when MPA CR drops below minimum | [MPA Maintenance](#mpa-maintenance) | `minCollateralRatio` |
+| Know how credit deals are renewed and repaid | [Credit Offer Maintenance](#credit-offer-maintenance) | `autoReborrow` / `autoRepay` |
+| Cap the size of a single borrow, or split oversized deals | [Credit Offer Maintenance](#credit-offer-maintenance) | `maxBorrowAmountPerOperation` |
+| Use LP shares as credit-offer collateral | [LP-Backed Credit Collateral](#lp-backed-credit-collateral) | automatic valuation |
+| Diagnose pending reborrow or renewal issues | [State Files](#state-files) | `profiles/credit_runtime/<botKey>.json` |
+| Safe operating practices | [Operational Notes](#operational-notes) | — |
+
+## Configuration Format
+
+Add `debtPolicy` to a bot entry in `profiles/bots.json`:
+
+```json
+{
+  "name": "credit-bot-1",
+  "preferredAccount": "my-account",
+  "active": true,
+
+  "creditOnly": true,
+
+  "debtPolicy": {
+    "maxCollateralAmount": "80%",
+    "lending": [
+      {
+        "asset": "HONEST.USD",
+        "collateralAsset": "BTS",
+        "type": "mpa",
+        "outputWeight": 1,
+        "maxBorrowAmount": 1000,
+        "maxCollateralAmount": 5000,
+        "minCollateralRatio": 2.0,
+        "maxCollateralRatio": 2.5,
+        "targetCollateralRatio": 2.2
+      },
+      {
+        "asset": "HONEST.CNY",
+        "collateralAsset": "BTS",
+        "type": "creditOffer",
+        "outputWeight": 1,
+        "maxBorrowAmount": 1000,
+        "maxCollateralRatio": 2.5,
+        "maxFeeRatePerDay": 0.05,
+        "autoReborrow": true,
+        "autoRepay": 2
+      }
+    ]
+  }
+}
+```
+
+### Field Reference
+
+<details><summary>All config fields (click to expand)</summary>
+
+**Required Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `lending` | `array` | Non-empty array of lending items. Each item maps a debt asset to a debt type and collateral asset. |
+
+**Lending Item Fields** (every item must have):
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `asset` | `string` | Yes | Debt asset symbol or ID (e.g. `"HONEST.USD"`). |
+| `collateralAsset` | `string` | Yes | Collateral asset (e.g. `"BTS"`). Multiple items may share the same collateral asset. |
+| `type` | `string` | Yes | `"mpa"` (BitShares MPA call order) or `"creditOffer"` (credit offer deal). |
+
+**Shared Optional Fields** (both `"mpa"` and `"creditOffer"`):
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `outputWeight` | `number` | No | Output weight for this asset. Controls the proportion of debt value across lending items (not collateral). Defaults to `1`. See **Collateral Distribution** below. |
+| `maxBorrowAmount` | `number` | No | **Fixed** total debt ceiling. Must be a positive number (not a percentage). |
+| `maxBorrowAmountPerOperation` | `number` | No | **Per-operation borrow cap**. Any single credit-offer accept operation whose borrow amount exceeds this is rejected. For MPA, the planner clamps each `debtDelta` by this cap on top of `maxBorrowAmount`. When set, oversized credit deals are split into equal pieces via repay+reborrow cycles during maintenance (see [Credit Offer Maintenance](#credit-offer-maintenance)). Must be a positive number. |
+| `maxCollateralAmount` | `number \| percentage string` | No | Total collateral ceiling. Use a number for an absolute collateral amount, e.g. `5000`, or a percentage string of total available collateral, e.g. `"80%"`. |
+| `minCollateralIncreaseThreshold` | `number \| percentage string` | No | Minimum unused collateral allocation before increasing debt. Use a number for an absolute collateral amount, e.g. `25`, or a percentage string of assigned collateral budget, e.g. `"5%"`. `0` means no minimum. |
+| `maxCollateralRatio` | `number` | No\* | Behavior differs by type: MPA — hard CR ceiling above which debt is increased first; creditOffer — maximum effective ratio when accepting offers. **Required** for `creditOffer`. |
+
+**MPA-Specific Fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `targetCollateralRatio` | `number` | No | Preferred operating CR. If omitted, midpoint of min/max is used. |
+| `minCollateralRatio` | `number` | No | Hard minimum CR floor. Below this, debt is reduced first. |
+| `debtOnly` | `boolean` | No | If `true`, the bot only adjusts debt to manage the collateral ratio — collateral is never added or withdrawn. Combined with `minCollateralRatio`/`maxCollateralRatio`, this keeps the position size constant while maintaining CR bounds. |
+
+**Credit-Offer-Specific Fields:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `maxFeeRatePerDay` | `number` | No | Maximum acceptable daily fee rate. Defaults to `1/2900` (~0.034%/day). |
+| `autoReborrow` | `boolean` | No | If `true`, the bot reborrows from the same offer after repayment. |
+| `autoRepay` | `number` | No | On-chain auto-repay mode: `0` (off), `1` (full only), `2` (partial allowed). |
+| `allowedOfferIds` | `string[]` | No | Whitelist of credit offer object IDs (1.21.x) the bot may accept. |
+| `disallowedDealIds` | `string[]` | No | Denylist of credit deal object IDs (1.22.x) the bot must not reborrow from. Repay is unaffected — the bot can still repay deals in this list. |
+| `renewOnly` | `boolean` | No | If `true`, the bot only reborrows existing deals — standalone credit borrows are refused. Default `false`. |
+| `minDurationSeconds` | `number` | No | Minimum acceptable offer duration in seconds. Offers with `duration_seconds` below this value are skipped. |
+
+**Global Fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `maxCollateralAmount` | `number \| percentage string` | **Global** collateral cap across all lending items. Use a number for an absolute collateral amount, e.g. `10000`, or a percentage string of total available collateral, e.g. `"80%"`. |
+
+</details>
+
+There is no separate enable switch. If `debtPolicy.lending` is present, non-empty, and every item has a valid `collateralAsset`, the credit runtime loads for that bot.
+
+## Credit-Only Mode
+
+Set `creditOnly: true` on a bot entry to run only the credit runtime — no grid trading, order management, or fill processing.
+
+```json
+{ "name": "Credit", "active": true, "creditOnly": true,
+  "preferredAccount": "my-account", "debtPolicy": { "lending": [...] } }
+```
+
+No trading fields (`assetA`, `assetB`, `startPrice`, `incrementPercent`, `activeOrders`, `botFunds`) are needed.
+
+```bash
+dexbot start credit          # Background daemon — runs only the credit worker
+dexbot start <bot-name>      # Start a named bot directly
+```
+
+### Collateral Increase Thresholds
+
+`minCollateralIncreaseThreshold` is evaluated in collateral-asset units against the unused assigned collateral for that lending item:
+
+- `25` means at least 25 units of the collateral asset, such as `25 BTS`.
+- `"5%"` means at least 5% of that item’s assigned collateral budget.
+- `0` means no minimum; any positive unused assigned collateral may trigger an increase.
+- Omitted on credit-offer items leaves proactive credit increases disabled for backward compatibility.
+
+## Collateral Distribution
+
+The runtime calculates required collateral for each lending item **backwards from the desired debt output ratio**. The `outputWeight` field controls the proportion of debt value (not collateral) each item receives.
+
+### Formulas
+
+```
+MPA weight_i    = outputWeight_i * feedPrice_i * targetCR_i
+Credit weight_i = (outputWeight_i * maxCR_i) / conversionRate_i
+C_total         = min(availableCollateral, globalMaxCollateral)
+C_i             = C_total * weight_i / sum(all weights)
+```
+
+- **MPA**: `feedPrice_i` is the current settlement feed price (collateral per debt asset), discovered from the chain and cached per position.
+- **Credit**: `conversionRate_i` is the offer's `acceptable_collateral` price (debt asset per collateral unit), discovered from existing deals or `allowedOfferIds`.
+- **Fallback**: If the price cannot be discovered, `weight = outputWeight * targetCR` and a warning is logged.
+- `outputWeight` is the user's output proportion. Equal weights produce **equal economic debt value** across all lending items, regardless of price or CR differences.
+
+### Examples
+
+**Two assets, equal weight** — collateral split 50:50.
+
+**Two assets, 80% output on USD** — USD receives a proportionally smaller share of the configured collateral pool, CNY receives the remaining larger share.
+
+**Three assets, equal weight** — collateral split 1/3 : 1/3 : 1/3.
+
+## Runtime Timing
+
+Credit and MPA maintenance are separated from periodic grid checks. DEXBot2 starts a dedicated credit watchdog interval during bot startup.
+
+Timing defaults live in `modules/constants.ts`:
+
+```json
+{
+  "TIMING": {
+    "CREDIT_DEAL_CHECK_INTERVAL_MIN": 60,
+    "CREDIT_DEAL_EXPIRY_THRESHOLD_HOURS": 12,
+    "CREDIT_DEAL_SPLIT_MAX_PIECES": 48,
+    "BLOCKCHAIN_SETTLE_DELAY_MS": 6000
+  }
+}
+```
+
+- `CREDIT_DEAL_CHECK_INTERVAL_MIN`: how often the credit watchdog runs. Set to `0` or negative to disable.
+- `CREDIT_DEAL_EXPIRY_THRESHOLD_HOURS`: how far before `latest_repay_time` the bot proactively repays and reborrows.
+- `CREDIT_DEAL_SPLIT_MAX_PIECES`: hard cap on pieces per `_splitOversizedCreditDeals` cycle (default 48; ~4.8min at 6s/piece). Prevents one maintenance run from exceeding the watchdog interval.
+- `BLOCKCHAIN_SETTLE_DELAY_MS`: pause between split pieces (default 6000ms). Resolved from the `TIMING` constant — per-bot `bots.json` overrides for this field are **not** honoured for split pacing.
+
+## MPA Maintenance
+
+For each `type: "mpa"` lending item:
+
+- If CR is below `minCollateralRatio`, **reduce debt first**, then add collateral if needed.
+- If CR is above `maxCollateralRatio`, **increase debt first**, then withdraw collateral if allowed.
+- Debt increases are calculated from the current feed price and current call-order collateral, capped by the total outstanding debt ceiling in `maxBorrowAmount`.
+- `minCollateralIncreaseThreshold` suppresses dust-sized increases when unused assigned collateral is below the configured absolute or percentage threshold.
+- If the debt-first leg fails (e.g. insufficient free MPA to repay), the runtime attempts a collateral-only fallback.
+- If `targetCollateralRatio` is not set, the midpoint of the min/max band is used.
+- After any successful CR adjustment, the bot requests a grid reset so order sizing reflects the new capital base.
+- `maxBorrowAmount` only prevents additional debt above the configured total; it does not block debt reduction. Must be a **fixed positive number** (no percentages).
+
+## Credit Offer Maintenance
+
+For each `type: "creditOffer"` lending item, the runtime:
+
+- **Phase 0 — Split oversized deals**: if `maxBorrowAmountPerOperation` is set, scans existing credit deals and splits any whose debt exceeds the per-op cap into equal pieces via repay+reborrow cycles (see [Oversized Credit Deal Splitter](#oversized-credit-deal-splitter)). This keeps each individual deal below the per-op cap and makes future renewals easier with less liquidity per operation.
+- Discovers active credit deals on-chain.
+- Validates deals against the per-item policy (`maxCollateralRatio`, `maxFeeRatePerDay`, `allowedOfferIds`, `disallowedDealIds`, etc.).
+- Gates increases on unused assigned collateral. If the collateral shortfall is at least `minCollateralIncreaseThreshold`, it accepts an additional credit deal from the cheapest acceptable offer; the selected offer's price derives the borrow amount, capped by `maxBorrowAmount` and, when set, `maxBorrowAmountPerOperation`. A borrow-cap-capped increase is skipped if the actual collateral used would fall below `minCollateralIncreaseThreshold`.
+- Proactively repays deals nearing expiration (within `CREDIT_DEAL_EXPIRY_THRESHOLD_HOURS`) and reborrows when `autoReborrow` is enabled.
+- Ensures `auto_repay` on-chain matches the policy's `autoRepay` setting, updating local state after each successful broadcast.
+
+### Oversized Credit Deal Splitter
+
+When `maxBorrowAmountPerOperation` is set, each credit-maintenance cycle runs `_splitOversizedCreditDeals` as Phase 0. The splitter:
+
+- Discovers deals whose `debtAmount` exceeds `maxBorrowAmountPerOperation`.
+- Splits each oversized deal into `ceil(debt / maxPerOp)` equal pieces via atomic repay+reborrow transactions. Total debt across the new deals is preserved; only deal granularity changes.
+- Skips a deal if any piece would fall below the offer's `min_deal_amount` (the offer is cached for the runtime lifetime, so on-chain `min_deal_amount` changes mid-split are not re-read).
+- Pauses `BLOCKCHAIN_SETTLE_DELAY_MS` between pieces; aborts on shutdown.
+- Stops once `CREDIT_DEAL_SPLIT_MAX_PIECES` pieces have been emitted in the current cycle. Remaining oversized deals are deferred to the next maintenance cycle.
+- Uses an in-process `_splitInFlight` guard so `runMaintenance` and `runCreditWatchdog` cannot start overlapping splits.
+
+The split pieces are normal credit deals — they appear in `profiles/credit_runtime/<botKey>.json` alongside other deals and are subject to the usual renewal, `auto_repay`, and collateral-switching flows.
+
+### Amount Cap Semantics
+
+| Policy | Field | Scope |
+|--------|-------|-------|
+| MPA | `maxBorrowAmount` | **Total debt ceiling** — call order debt cannot exceed this. |
+| MPA | `maxBorrowAmountPerOperation` | **Per-op borrow cap** — clamps each `debtDelta` increment during CR-band adjustments. Ignored on debt-reduction moves. |
+| MPA | `maxCollateralAmount` | **Total collateral ceiling** — call order collateral cannot exceed this. Withdrawals still allowed. |
+| Credit | `maxBorrowAmount` | **Total debt ceiling** — total credit debt for the asset cannot exceed this. |
+| Credit | `maxBorrowAmountPerOperation` | **Per-op borrow cap** — rejects any single `credit_offer_accept` whose borrow amount exceeds this. Oversized existing deals are split during maintenance (see [Oversized Credit Deal Splitter](#oversized-credit-deal-splitter)). |
+| Credit | `maxCollateralAmount` | **Total collateral ceiling** — total credit collateral for the asset cannot exceed this. |
+
+`maxBorrowAmount` is always a **fixed number** (no percentages). `maxCollateralAmount` may be a fixed number or a percentage.
+
+### Credit Deal Renewal
+
+When `renewOnly` is `true`, the bot refuses standalone credit borrows and only renews existing deals via repay+reborrow. This is useful when you want the bot to maintain existing positions but not open new ones.
+
+When a deal's `latest_repay_time` is within `CREDIT_DEAL_EXPIRY_THRESHOLD_HOURS`:
+
+1. Repay the deal.
+2. Reborrow from the same offer when `autoReborrow` is enabled, using the full `assignedCollateralBudget`.
+3. Preserve configured `autoRepay` on the new credit-offer accept operation.
+
+If inline reborrow cannot be built safely, the runtime stores a deferred reborrow request in `profiles/credit_runtime/<botKey>.json` and retries later.
+
+### Collateral Switching on Renewal
+
+You can switch a credit deal's collateral to a different asset on its next renewal by changing `lendingItem.collateralAsset` to the new asset in `bots.json`. The runtime detects existing deals whose collateral no longer matches the policy and migrates them during proactive expiry repay+reborrow. Requirements:
+
+- The new asset must be listed in the credit offer's `acceptable_collateral`. The runtime rejects mismatched collateral with a specific error message.
+- The bot must hold enough of the new collateral asset before the deal is repaid. The offer's minimum required collateral is computed from the borrow amount and the new collateral price — the old deal's collateral amount is not carried forward.
+- Only applies to `type: "creditOffer"` items — MPA collateral is fixed by the call order asset.
+- Deferred reborrow requests from before the switch may fail; drop stale pending reborrows by clearing `profiles/credit_runtime/<botKey>.json` or letting them expire naturally.
+- If the switch produces no active reborrow (e.g., insufficient balance for the new collateral), the deal is repaid and the reborrow is deferred to the pending queue for later retry.
+
+### auto_repay Enforcement
+
+On each maintenance cycle, the runtime compares each deal's on-chain `auto_repay` against the policy's `autoRepay` value. If they differ, a `credit_deal_update` operation is broadcast. After a successful update, the local deal state is updated to prevent redundant broadcasts on the next cycle.
+
+<details><summary>BitShares auto-repay modes (click to expand)</summary>
+
+BitShares core 7.0.2 defines three auto-repay modes:
+
+| Value | Mode | Behavior at `latest_repay_time` |
+|-------|------|--------------------------------|
+| `0` | `no_auto_repayment` | No auto-repay. Deal expires; collateral is liquidated to the offer owner. |
+| `1` | `only_full_repayment` | Full repay if borrower balance >= debt + fee; otherwise deal expires. |
+| `2` | `allow_partial_repayment` | Repay as much as possible with available balance; any remaining debt triggers expiry with proportional collateral liquidation. |
+
+</details>
+
+### Important Distinction
+
+- `autoReborrow` is **DEXBot2 behavior** — the bot re-accepts the same offer after a repay.
+- `autoRepay` is **BitShares chain behavior** — the chain attempts automatic repayment at deal expiry.
+
+## LP-Backed Credit Collateral
+
+Credit offers may accept liquidity-pool share assets as collateral. Before accepting an offer, DEXBot2:
+
+1. Resolves the LP pool for the share asset.
+2. Reads pool balances and share supply.
+3. Computes the collateral value from the underlying reserves.
+4. Converts that value into the debt asset denomination.
+5. Rejects the borrow if the effective ratio exceeds the lending item's `maxCollateralRatio`.
+
+If pool lookup, supply lookup, or valuation cannot be resolved, the runtime fails closed and does not sign the borrow.
+
+## State Files
+
+The runtime persists one state file per bot:
+
+```text
+profiles/credit_runtime/<botKey>.json
+```
+
+The file tracks discovered chain state and pending work, including:
+
+- `positions` — per-position state map keyed as `debtAssetId:collateralAssetId`
+- Active MPA call-order state and credit deal IDs per position
+- `assignedCollateralBudget` per position
+- Pending reborrow requests (including deferred split pieces when an oversized-deal cycle hits `CREDIT_DEAL_SPLIT_MAX_PIECES`)
+- Last repay timestamp and grid reset request
+- Debt snapshot across all assets
+
+Treat this file as runtime state, not primary configuration. The source of truth for enabled policy is `profiles/bots.json`.
+
+## Operational Notes
+
+- Keep `debtPolicy` narrow. Only list assets and offers the bot is allowed to use.
+- Use conservative CR bands. `minCollateralRatio` is a hard safety floor, not a target.
+- Keep `maxFeeRatePerDay` explicit for credit offers.
+- Credit-offer collateral ratio and MPA call-order CR are validated in separate paths.
+- After editing `profiles/bots.json`, restart the bot so the runtime picks up the new policy.
+- Review `profiles/credit_runtime/<botKey>.json` when diagnosing pending reborrow or renewal behavior.
+
+## Related Files
+
+<details><summary>Source files and tests (click to expand)</summary>
+
+- `modules/credit_runtime.ts`: debt workflow executor (Phase 0 oversized-deal splitter lives here)
+- `modules/cr_planner.ts`: MPA debt-first planner; clamps `debtDelta` by `maxBorrowAmountPerOperation`
+- `modules/types.ts`: `LendingEntryBase` — shared `mpa` / `creditOffer` type including `maxBorrowAmountPerOperation`
+- `modules/dexbot_class.ts`: runtime startup and watchdog lifecycle
+- `modules/bot_settings.ts`: `debtPolicy` validation
+- `market_adapter/README.md`: AMA pricing, grid triggers, and dynamic-weight runtime
+- `modules/credential_policy.ts`: signing constraints for credit and call-order operations
+- `tests/test_credit_runtime.ts`: credit runtime behavior coverage (including 6 oversized-deal splitter tests)
+- `tests/test_multi_asset_distribution.ts`: collateral distribution and multi-asset state coverage
+
+</details>

package/docs/README.md

@@ -0,0 +1,199 @@
+# DEXBot2 Documentation
+
+This directory contains the comprehensive technical documentation for the DEXBot2 trading bot. It is designed to guide developers from high-level architecture down to the nuances of fund accounting and state management.
+
+**Version context:** v1.4.17 (released).
+
+---
+
+## User-Facing Workflows
+
+### 🎓 [BitShares Onboarding](BITSHARES_ONBOARDING.md)
+*Beginner tutorial for new BitShares users getting started with DEXBot2.*
+- **Account Setup**: Register and fund a BitShares account
+- **Keys Explained**: Owner vs active vs memo vs login key — and which one the bot needs
+- **First Bot**: Import keys, create a bot config, and run a dry run
+- **Troubleshooting**: The most common first-run mistakes and how to fix them
+
+### 📡 [Market Adapter](../market_adapter/README.md)
+*Live AMA pricing, dynamic weights, and recalc trigger orchestration.*
+- **Quick Start**: Enable AMA, generate the whitelist, and start DEXBot2
+- **Settings**: Global, pair, and bot-specific adapter overrides
+- **Dynamic Weights**: How adapter signals write live weight snapshots
+- **Troubleshooting**: Common adapter startup and trigger issues
+
+### 💳 [MPA and Credit Usage](MPA_CREDIT_USAGE.md)
+*User-facing MPA and credit offer workflow guide.*
+- **Debt Policy**: Per-bot `debtPolicy.lending` configuration where each item declares its own `collateralAsset`
+- **Credit-Only Mode**: Run credit runtime without grid trading (`creditOnly: true`, `dexbot start credit` runs just that worker as a background daemon)
+- **MPA Borrowing**: Call-order updates with debt-first CR planning
+- **Credit Offers**: Accept/repay with auto-reborrow and LP-backed collateral valuation
+- **Watchdog Timing**: Dedicated credit deal renewal interval and expiry threshold settings
+
+### 📈 [Analysis](../analysis/README.md)
+*Research runners, chart generators, and tuning helpers.*
+- **Trend Detection**: SMA, MACD, RSI, Hurst, Kalman, and regime analysis tools
+- **AMA Fitting**: Parameter fitting, comparison charts, and LP data workflows
+- **Bot Fitting**: Grid parameter sweep backtests for AMA winners
+- **TradingView Exports**: Chart export utilities for visual analysis
+- **Trade Profitability**: FIFO-based PnL analysis from Kibana fill data (`trade_profitability.ts`)
+- **Bot Usage Discovery**: On-chain bot account finder and Kibana query helpers (`bot_usage/`)
+
+### 🦀 [Claw](../claw/README.md)
+*Bridge between DEXBot2 and external runtimes.*
+- **Purpose**: Exposes BitShares capabilities and DEXBot2 infrastructure through JSON/CLI bridges, MCP, and runtime-native skill packaging for OpenClaw and compatible runtimes (see [claw/README.md](../claw/README.md) for the full list).
+- **API Boundary**: Responsibility split between the AI decision layer and the DEXBot2 execution substrate ([AI_BOT_LIBRARY_API.md](../claw/docs/AI_BOT_LIBRARY_API.md))
+- **Tuning Reference**: Practical grid-tuning baselines ([DEXBOT2_TUNING_CHEAT_SHEET.md](../claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md))
+- **Position Management**: Health monitoring, margin planner, and dynamic weight policy
+- **Skills**: Presentation-only, concept-reference, and launcher-orchestration skill packs for bitshares-guide, margin-trading, launcher-ops, and shared references
+
+## Operational & Security
+
+### 🔐 [Credential Security](CREDENTIAL_SECURITY.md)
+*How private keys are protected at rest, in transit, and in RAM.*
+- **Vault v2**: scrypt (N=2¹⁷) key derivation, per-record HKDF isolation, AES-256-GCM encryption
+- **Daemon-backed signing**: primary bot flow uses signing tokens; all signing happens inside the daemon, raw keys never exported
+- **Session cache**: encrypted HKDF re-encryption with a random salt that is never persisted
+- **Runtime hardening**: lstat + owner/mode/type checks on all sockets and ready files; bootstrap socket destroyed after first use
+
+### 📊 [Grid Recalculation](GRID_RECALCULATION.md)
+*When and why the grid resets.*
+- **Reset Sources**: Market-adapter bootstrap, AMA delta, AMA-slope range reset, RMS divergence correction, and fund regeneration
+- **Configuration**: Per-source thresholds, whitelist requirements, and defaults
+- **Trigger Execution**: How `profiles/recalculate.<botKey>.trigger` is consumed under the fill-processing lock
+
+### 🔁 [Grid Reconciliation](GRID_RECONCILE.md)
+*How the bot re-aligns its intended grid with on-chain reality at startup.*
+- **3-Phase Plan-then-Execute**: Phase 1 pure in-memory planning under `_gridLock`, Phase 2 blockchain execution outside the lock, Phase 3 fresh re-read and stale surplus cleanup
+- **Safety Guardrails**: Fresh-grid `matchedOnGrid > 0` guard, 5× duplicate tolerance, freshly-assigned deferral, and truncated-read ambiguity handling
+- **Partial Failure State**: No rollback on partial Phase 2 success; remaining mismatches caught by the next maintenance or startup cycle
+- **Lock Hierarchy**: Canonical `_syncLock`/`_gridLock` level reference and the 1.4.6 ABBA deadlock correction
+
+### 📝 [Logging System](LOGGING.md)
+*Configuration reference for log levels, rotation, JSON output, and categories.*
+- **5 Severity Levels**: `debug`, `info`, `warn`, `error`, `critical`.
+- **Rotation**: Size-based (1GB default), auto-prune (5 files).
+- **JSON Output**: Structured lines for log aggregators (opt-in).
+- **Categories**: 6 independently enablable category groups.
+- **Change Detection**: Skips redundant logs (40-50% reduction).
+- **Batch Processing Logs**: Fill batching, recovery retry, and orphan-fill deduplication messages.
+- **Fill History Scans**: The `Subscriptions` logger emits `fetchFillHistoryEntries: maxPages (X) reached` at `info` level when the history scan hits its page cap — normal on busy accounts; see LOGGING.md for the `--partial-operations` diagnostic.
+
+### 🐳 [Docker](docker.md)
+*Container build, release images, and secure startup.*
+- **Build Flow**: Docker-based packaging for the bot runtime
+- **Release Images**: Container release and startup guidance
+- **Security**: Notes on secure container launch behavior
+
+### 🛠️ [Scripts](../scripts/README.md)
+*CLI maintenance and diagnostic utilities.*
+- **Update**: Safe production update via `dexbot update`
+- **Reset & Cleanup**: Log wiping, setting resets, PM2 ecosystem regeneration
+- **Analysis Helpers**: Diagnostic connection tests and health probes
+
+## Reference Docs
+
+### 🏛️ [Architecture](architecture.md)
+*The blueprint of the system.*
+- **Design Philosophy**: Simplicity, constant spread, minimal blockchain interaction, and closed-loop market dynamics.
+- **System Design**: High-level overview of how the bot components interact.
+- **Module Responsibilities**: Detailed breakdown of the **Manager**, **Accountant**, **Strategy**, **Grid**, **FillRuntime**, and **MaintenanceRuntime** modules.
+- **Copy-on-Write Pattern**: Safe concurrent rebalancing with isolated working grids (see [COPY_ON_WRITE_MASTER_PLAN.md](COPY_ON_WRITE_MASTER_PLAN.md))
+- **Fill Processing Pipeline**: Fixed-cap batch fill processing (1-4 fills per broadcast; documented Feb 7 29-fill scenario: ~24s)
+- **Fund-Driven Boundary Sync**: Automatic grid alignment with inventory distribution
+- **Spread Correction**: Conservative, fund-aware maintenance of constant spread width
+- **Periodic Market Price Refresh**: Background 4-hour price updates
+- **Pipeline Safety & Diagnostics**: 5-minute timeout safeguard and health monitoring
+- **Data Flow**: Visualization of how market data becomes trading operations and then blockchain transactions.
+- **Zero-Dependency Policy**: Formal policy rationale, trading-bot special-case justification, and practical implications (native blockchain client, crypto, testing, persistence)
+- **Market Adapter Signal Pipeline**: AMA center, dynamic weights, regime detection, and collateral advisories
+- **Credit/Debt Runtime**: Native MPA and credit offer workflows with CR planning and grid reset coupling; `creditOnly` mode for runtime-only operation without grid trading
+
+### 📖 [Developer Guide](developer_guide.md)
+*Your daily companion for coding.*
+- **Quick Start**: How to get the development environment running.
+- **Module Deep-Dive**: In-depth analysis of the internal logic of each primary module.
+- **Copy-on-Write Pattern**: How to work safely within the COW rebalance pipeline; `WorkingGrid` usage and master-grid commit rules (see [COPY_ON_WRITE_MASTER_PLAN.md](COPY_ON_WRITE_MASTER_PLAN.md))
+- **Startup Sequence & Lock Ordering**: Consolidated startup with deadlock prevention
+- **Zero-Amount Order Prevention**: Validation gates for healthy order sizes
+- **Configurable startPrice & gridPrice**: Fixed numeric, pool, book-derived, or AMA keyword pricing modes
+- **Pool ID Caching**: Optimization for price derivation
+- **Order State Helper Functions**: Centralized predicate functions for state checking
+- **Signal Concepts**: Dynamic weights, regime detection, derivative signals, and market adapter integration
+- **Debt Policy**: Native MPA and credit offer configuration and runtime rules
+- **Common Tasks**: Practical "how-to" guides for adding features or fixing bugs.
+- **Glossary**: Definitions of project-specific terminology (e.g., "Virtual Orders", "Rotation", "Pipeline Safety", "Fund-Driven Boundary", "WorkingGrid", "COW Commit", "Dynamic Weight", "Regime Detection").
+
+### 🔄 [Workflow](WORKFLOW.md)
+*How we build and release.*
+- **Branching Strategy**: Explanation of the `test` → `dev` → `main` lifecycle.
+- **CI/CD Patterns**: Standards for merging and ensuring code quality across branches.
+
+### 🧮 [DEXBot vs DEXBot2 Comparison](DEXBOT_COMPARISON.md)
+*Architectural, functional, and operational comparison with the original Python DEXBot.*
+- **Scope**: Full side-by-side of technology stack, architecture, trading strategies, order management, configuration, blockchain integration, fund accounting, and concurrency safety
+- **Audience**: Developers and operators evaluating or migrating between the two projects
+
+### 🧭 [Evolution Report](EVOLUTION.md)
+*Project timeline and major architecture phases.*
+- **Coverage**: Historical milestones from the initial December 2025 bootstrap through the v1.4.18 stable release (grid persistence safety, dust pipeline fix, net inventory lots); credit/debt runtime and maintenance hardening are covered under Phase 5 (Mar–Jun 2026)
+- **Focus**: Architecture evolution, release history, test growth, and documentation changes
+
+### 🗒️ [Changelog](../CHANGELOG.md)
+*Release notes and documentation history.*
+- **Scope**: Versioned notes for patch releases and the current unreleased documentation refresh
+
+### 🧩 [Copy-on-Write Master Plan](COPY_ON_WRITE_MASTER_PLAN.md)
+*COW design, phases, and state machine details.*
+- **Architecture**: Master-grid projection model and rebalance flow
+- **Lifecycle**: Implementation phases, commit boundaries, and test coverage
+- **Safety**: Invariants and guardrails for concurrent updates
+
+### 🔒 [COW Invariants](COW_INVARIANTS.md)
+*Stable theory contract for COW pipeline.*
+- **Non-negotiable invariants**: Master immutability, commit atomicity, projection rules, accounting separation
+- **Test mapping**: Links each invariant to regression tests
+- **Review checklist**: Quick-use verification for COW/accounting changes
+
+### 🧪 [Test Suite](../tests/README.md)
+*Test organization, categories, and key architectural patterns tested.*
+- **Test Layout**: Directory structure, helpers, and quick-start commands
+- **Categories**: Core infrastructure, order management, COW rebalancing, fees/accounting, integration, edge cases, and more
+- **Architectural Patterns**: COW rebalancing, RMS divergence, and fund invariants with doc cross-references
+
+### 💰 [Fund Movement & Accounting](FUND_MOVEMENT_AND_ACCOUNTING.md)
+*The most critical part of the bot: safe capital management.*
+- **Single Source of Truth**: How the bot avoids double-spending and out-of-sync balances.
+- **Optimistic ChainFree**: The mechanism that allows the bot to trade with fill proceeds before they are finalized on-chain.
+- **Fill Batch Processing**: Fixed-cap batching for efficient fill processing (`<=4` unified, `>4` chunked)
+- **Partial Order Consolidation**: Simplified, direct consolidation through grid rebuilding (no merge/split mechanics)
+- **Dust Detection & Management**: Partials below the dust threshold are cancelled on-chain immediately on detection (no delay, no timer)
+- **BTS Fee Object Structure**: `netProceeds` field for accounting precision
+- **BUY Side Sizing & Fee Accounting**: Correct fee application by order side
+- **Mixed Order Fund Validation**: Separate validation for BUY vs SELL order fund checks
+- **Fee Management**: Detailed logic for BTS fee reservations and market fee deductions.
+
+---
+
+## Source Code Map
+
+While these docs explain the *why*, the *how* lives in the code. See the full [module index](../modules/README.md) for a complete directory walkthrough. Key source modules:
+
+- **`modules/dexbot_class.ts`**: Bot initialization, account setup, lifecycle orchestration, credit runtime startup, and shared runtime wiring
+- **`modules/dexbot_fill_runtime.ts`**: Fill processing, replay-safe accounting, and fill queue handling
+- **`modules/dexbot_maintenance_runtime.ts`**: Open-orders sync loop, blockchain fetch loop, grid maintenance, trigger handling, and market adapter watchdog
+- **`modules/order/manager.ts`**: Central controller with Copy-on-Write rebalancing pattern (see [COPY_ON_WRITE_MASTER_PLAN.md](COPY_ON_WRITE_MASTER_PLAN.md))
+- **`modules/order/working_grid.ts`**: COW grid wrapper enabling safe concurrent rebalancing with isolated modifications
+- **`modules/order/grid.ts`**: Grid generation, sizing, divergence detection, and spread management
+- **`modules/order/accounting.ts`**: Fund tracking, available balance calculation, fee deduction, and committed fund management
+- **`modules/order/processed_fill_store.ts`**: Processed fill dedupe tracker and persistence batching
+- **`modules/order/strategy.ts`**: Grid rebalancing, order activation, consolidation, rotation, and spread management
+- **`modules/order/sync_engine.ts`**: Blockchain synchronization, fill detection, order reconciliation
+- **`modules/credit_runtime.ts`**: Bot-scoped debt workflow executor (MPA and credit offer accept/repay/reborrow)
+- **`modules/cr_planner.ts`**: Shared collateral-ratio math layer for debt-first planning
+- **`modules/order/utils/math.ts`**: Precision conversions, RMS divergence calculation, fund allocation math
+- **`modules/order/utils/order.ts`**: Order state predicates, grid indexing, reconciliation helpers, delta building, index utilities
+- **`modules/order/utils/validate.ts`**: Order validation, grid reconciliation, COW action building
+- **`modules/order/utils/system.ts`**: System utilities, price derivation, fill deduplication
+- **`modules/order/grid_reconcile.ts`**: Startup grid reconciliation and offline fill detection ([GRID_RECONCILE.md](GRID_RECONCILE.md))
+- **`modules/credential_policy.ts`**: Signing policy validation and operation allowlists