dexbot 1.6.13 → 1.6.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +32 -0
- package/README.md +2 -2
- package/claw/docs/AI_BOT_LIBRARY_API.md +1 -1
- package/claw/docs/DEXBOT2_TUNING_CHEAT_SHEET.md +4 -4
- package/claw/modules/claw_catalog.ts +8 -4
- package/claw/modules/dexbot_profiles.ts +59 -15
- package/claw/modules/types.ts +2 -1
- package/claw/package.json +1 -1
- package/claw/runtimes/openclaw-plugin/openclaw.plugin.json +1 -1
- package/claw/runtimes/openclaw-plugin/package.json +1 -1
- package/claw/skills/margin-trading/SKILL.md +1 -1
- package/claw/skills/margin-trading/references/position-management.md +1 -1
- package/dist/analysis/tradingview/tradingview_uplot_chart_generator.js +25 -25
- package/dist/modules/account_bots.d.ts +7 -6
- package/dist/modules/account_bots.js +10 -10
- package/dist/modules/account_orders.d.ts +36 -4
- package/dist/modules/account_orders.js +76 -5
- package/dist/modules/bitshares-native/crypto/ecc_core.d.ts +1 -2
- package/dist/modules/bitshares-native/crypto/ecc_core.js +1 -1
- package/dist/modules/bitshares-native/serial/chain_constants.d.ts +1 -2
- package/dist/modules/bitshares-native/serial/chain_constants.js +1 -2
- package/dist/modules/bot_defaults.d.ts +16 -2
- package/dist/modules/bot_defaults.js +34 -8
- package/dist/modules/bot_settings.d.ts +4 -0
- package/dist/modules/bot_settings.js +55 -21
- package/dist/modules/config.js +6 -1
- package/dist/modules/constants.d.ts +7 -5
- package/dist/modules/constants.js +12 -5
- package/dist/modules/dexbot_class.d.ts +5 -0
- package/dist/modules/dexbot_class.js +8 -3
- package/dist/modules/dexbot_cow_runtime.d.ts +62 -174
- package/dist/modules/dexbot_cow_runtime.js +331 -46
- package/dist/modules/dexbot_credential_client.d.ts +1 -16
- package/dist/modules/dexbot_credential_client.js +1 -1
- package/dist/modules/dexbot_fill_runtime.d.ts +1 -1
- package/dist/modules/dexbot_fill_runtime.js +12 -1
- package/dist/modules/dexbot_maintenance_runtime.d.ts +18 -80
- package/dist/modules/dexbot_maintenance_runtime.js +57 -68
- package/dist/modules/dexbot_startup_runtime.js +12 -0
- package/dist/modules/dexbot_state_recovery.js +16 -0
- package/dist/modules/key_store.d.ts +0 -5
- package/dist/modules/key_store.js +1 -1
- package/dist/modules/order/accounting.js +11 -11
- package/dist/modules/order/export.js +2 -2
- package/dist/modules/order/format.d.ts +15 -1
- package/dist/modules/order/format.js +19 -1
- package/dist/modules/order/genesis_policy.d.ts +1 -1
- package/dist/modules/order/genesis_policy.js +1 -1
- package/dist/modules/order/grid.d.ts +23 -11
- package/dist/modules/order/grid.js +383 -51
- package/dist/modules/order/grid_reconcile.d.ts +1 -1
- package/dist/modules/order/grid_reconcile.js +5 -5
- package/dist/modules/order/grid_reconcile_internal.js +48 -40
- package/dist/modules/order/index.d.ts +34 -8
- package/dist/modules/order/logger.js +2 -2
- package/dist/modules/order/manager.d.ts +9 -2
- package/dist/modules/order/manager.js +58 -24
- package/dist/modules/order/strategy.d.ts +2 -2
- package/dist/modules/order/strategy.js +51 -21
- package/dist/modules/order/sync_engine.js +4 -0
- package/dist/modules/order/utils/math.d.ts +3 -3
- package/dist/modules/order/utils/math.js +38 -27
- package/dist/modules/order/utils/order.d.ts +58 -58
- package/dist/modules/order/utils/order.js +119 -102
- package/dist/modules/order/utils/system.d.ts +193 -6
- package/dist/modules/order/utils/system.js +392 -29
- package/dist/modules/order/utils/validate.js +26 -4
- package/dist/modules/runtime_settings.d.ts +1 -1
- package/dist/modules/runtime_settings.js +3 -3
- package/dist/modules/types.d.ts +48 -4
- package/dist/scripts/analyze-orders.d.ts +1 -1
- package/dist/scripts/analyze-orders.js +4 -4
- package/dist/scripts/divergence-calc.js +6 -6
- package/dist/scripts/validate_bots.d.ts +1 -1
- package/dist/scripts/validate_bots.js +3 -3
- package/dist/unlock.js +7 -2
- package/docs/COPY_ON_WRITE_MASTER_PLAN.md +1 -2
- package/docs/COW_INVARIANTS.md +6 -6
- package/docs/DEXBOT_COMPARISON.md +5 -5
- package/docs/EVOLUTION.md +8 -7
- package/docs/FUND_MOVEMENT_AND_ACCOUNTING.md +8 -6
- package/docs/GRID_PRICE_INVARIANT.md +3 -3
- package/docs/GRID_RECALCULATION.md +4 -1
- package/docs/GRID_RECONCILE.md +4 -4
- package/docs/LIFECYCLE.md +11 -11
- package/docs/LOGGING.md +14 -0
- package/docs/MPA_CREDIT_USAGE.md +1 -1
- package/docs/ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md +12 -4
- package/docs/README.md +3 -3
- package/docs/architecture.md +6 -6
- package/docs/developer_guide.md +7 -2
- package/package.json +1 -1
- package/tests/README.md +1 -1
package/dist/modules/types.d.ts
CHANGED
|
@@ -23,10 +23,22 @@ export type OrderState = 'virtual' | 'active' | 'partial';
|
|
|
23
23
|
* behind it). Only a chain sync can tell the two apart,
|
|
24
24
|
* so it arms the refresh too; the out-of-spread staleness
|
|
25
25
|
* watchdog remains the backstop if the sync heals nothing.
|
|
26
|
+
* cold-book — no live order on either side (readiness P-A): there is
|
|
27
|
+
* no realized spread to repair. The reconcile path owns
|
|
28
|
+
* the first window; a targeted sync is armed.
|
|
29
|
+
* unmatched-orders — readiness P-C: the only tightening candidates collided
|
|
30
|
+
* with known-unmatched chain orders, so planning skipped
|
|
31
|
+
* them and let the sync adopt them first.
|
|
32
|
+
* readiness-gate — the readiness gate itself failed (threw), so the cycle
|
|
33
|
+
* was refused correct-by-refusal. A fault to triage, not
|
|
34
|
+
* a structural candidate condition.
|
|
26
35
|
* batch-not-executed— a plan was prepared but the COW batch did not run.
|
|
27
36
|
* apply-error — the broadcast threw.
|
|
37
|
+
*
|
|
38
|
+
* ('stale-snapshot' is degraded-ok, not a stall: the planner still acts, it
|
|
39
|
+
* only withholds the LAST-FILL-GUARD bypass.)
|
|
28
40
|
*/
|
|
29
|
-
export type SpreadCorrectionStall = 'no-free-funds' | 'unfunded' | 'no-candidates' | 'batch-not-executed' | 'apply-error';
|
|
41
|
+
export type SpreadCorrectionStall = 'no-free-funds' | 'unfunded' | 'no-candidates' | 'cold-book' | 'unmatched-orders' | 'readiness-gate' | 'batch-not-executed' | 'apply-error';
|
|
30
42
|
/**
|
|
31
43
|
* Dict with unknown values. The canonical replacement for
|
|
32
44
|
* `Record<string, any>`; callers must narrow a value before using it.
|
|
@@ -484,6 +496,16 @@ export interface BotMetrics extends UnknownRecord {
|
|
|
484
496
|
maxQueueDepth: number;
|
|
485
497
|
gridLockContention: number;
|
|
486
498
|
fundRecalcCount: number;
|
|
499
|
+
/** Genuine post-broadcast commit refusals (working grid rejected). Excludes a poll-confirmed success that merely reuses the recovery funnel for adoption. */
|
|
500
|
+
refusedCommitCount: number;
|
|
501
|
+
/** Orphan fills whose proceeds were credited outside slot accounting. */
|
|
502
|
+
orphanFillCreditedCount: number;
|
|
503
|
+
/** BUY emissions at/above the last filled BUY pivot (guard bypass / leak). */
|
|
504
|
+
restampBuyAboveAnchorCount: number;
|
|
505
|
+
/** Derived boundary moved more than the active window in one plan. */
|
|
506
|
+
boundaryDriftExceedsWindowCount: number;
|
|
507
|
+
/** Non-spread-correction CREATE/UPDATE destinations inside the gap band (shadow). */
|
|
508
|
+
gapBandPlacementShadowCount: number;
|
|
487
509
|
}
|
|
488
510
|
/** An unmatched chain order surfaced by a sync pass. */
|
|
489
511
|
export interface UnmatchedChainOrder extends UnknownRecord {
|
|
@@ -562,8 +584,8 @@ export interface ManagedOrder {
|
|
|
562
584
|
sideHint?: string;
|
|
563
585
|
[key: string]: unknown;
|
|
564
586
|
}
|
|
565
|
-
/**
|
|
566
|
-
export interface
|
|
587
|
+
/** Market-order target counts (core-order window). */
|
|
588
|
+
export interface CoreOrdersConfig extends UnknownRecord {
|
|
567
589
|
buy?: number;
|
|
568
590
|
sell?: number;
|
|
569
591
|
}
|
|
@@ -598,7 +620,7 @@ export interface GridConfig extends UnknownRecord {
|
|
|
598
620
|
[key: string]: unknown;
|
|
599
621
|
};
|
|
600
622
|
targetSpreadPercent?: number;
|
|
601
|
-
|
|
623
|
+
coreOrders?: CoreOrdersConfig;
|
|
602
624
|
assetA?: string;
|
|
603
625
|
assetB?: string;
|
|
604
626
|
botKey?: string;
|
|
@@ -649,6 +671,16 @@ interface TimingConfig extends UnknownRecord {
|
|
|
649
671
|
BLOCKCHAIN_FETCH_INTERVAL_MIN?: number;
|
|
650
672
|
BOTS_CONFIG_POLL_INTERVAL_MS?: number;
|
|
651
673
|
BTS_ACQUIRE_COOLDOWN_MIN?: number;
|
|
674
|
+
/**
|
|
675
|
+
* Spread-correction trust window (ms). How old the last completed
|
|
676
|
+
* open-orders sync may be before the local snapshot is treated as stale
|
|
677
|
+
* (the planner still acts but loses the LAST-FILL-GUARD bypass), and how
|
|
678
|
+
* often the live market price is re-read for the crossing floor. Defaults to
|
|
679
|
+
* `TIMING.SPREAD_CORRECTION_SYNC_FRESH_MS` (10 min); a non-positive value
|
|
680
|
+
* disables the time bound entirely (snapshot is never stale and the live
|
|
681
|
+
* price is never force-refreshed, so the floor stays on the fill anchor).
|
|
682
|
+
*/
|
|
683
|
+
SPREAD_CORRECTION_SYNC_FRESH_MS?: number;
|
|
652
684
|
}
|
|
653
685
|
/** `config.fillProcessing` knobs read by the fill consumer. */
|
|
654
686
|
interface FillProcessingConfig extends UnknownRecord {
|
|
@@ -821,6 +853,7 @@ export interface AccountOrdersLike {
|
|
|
821
853
|
loadGenesis(forceReload?: boolean): unknown;
|
|
822
854
|
loadGapEvacStreaks(forceReload?: boolean): unknown;
|
|
823
855
|
loadLastFillPivot?(forceReload?: boolean): unknown;
|
|
856
|
+
loadLastMarketFill?(forceReload?: boolean): unknown;
|
|
824
857
|
loadPendingFillCrawls(forceReload?: boolean): unknown[];
|
|
825
858
|
loadRecentFillKeys(forceReload?: boolean): unknown;
|
|
826
859
|
loadPersistedAssets(forceReload?: boolean): {
|
|
@@ -832,6 +865,8 @@ export interface AccountOrdersLike {
|
|
|
832
865
|
clearGrid(): Promise<unknown>;
|
|
833
866
|
clearPersistedBoundary(...args: unknown[]): Promise<unknown>;
|
|
834
867
|
clearPersistedLastFillPivot(...args: unknown[]): Promise<unknown>;
|
|
868
|
+
clearPersistedLastMarketFill?(...args: unknown[]): Promise<unknown>;
|
|
869
|
+
backupSnapshot?(reason?: string): Promise<string | null>;
|
|
835
870
|
loadProcessedFills(options?: boolean | {
|
|
836
871
|
forceReload?: boolean;
|
|
837
872
|
minTimestamp?: number | null;
|
|
@@ -999,6 +1034,8 @@ export interface OrderManagerLike {
|
|
|
999
1034
|
createdAt?: number;
|
|
1000
1035
|
} | null;
|
|
1001
1036
|
_missingGenesis?: unknown;
|
|
1037
|
+
_metrics?: BotMetrics;
|
|
1038
|
+
_lastBoundaryDriftWarnAt?: number;
|
|
1002
1039
|
_genesisInvariantViolations?: number;
|
|
1003
1040
|
_genesisInvariantLoggedAt?: number;
|
|
1004
1041
|
_fundDriftLedger?: {
|
|
@@ -1014,6 +1051,13 @@ export interface OrderManagerLike {
|
|
|
1014
1051
|
_lastFilledType: string | null;
|
|
1015
1052
|
_lastFilledAt: number | null;
|
|
1016
1053
|
lastFillPivotSource: 'fill' | 'book' | null;
|
|
1054
|
+
_lastMarketFillPrice?: number | null;
|
|
1055
|
+
_lastMarketFillType?: string | null;
|
|
1056
|
+
_lastMarketFillAt?: number | null;
|
|
1057
|
+
_liveMarketPrice?: number | null;
|
|
1058
|
+
_liveMarketPriceAt?: number | null;
|
|
1059
|
+
_liveMarketPriceAttemptedAt?: number | null;
|
|
1060
|
+
_lastSyncAt?: number;
|
|
1017
1061
|
_lastUnmatchedChainOrders?: UnmatchedChainOrder[];
|
|
1018
1062
|
_lastUnmatchedChainOrdersAt?: number;
|
|
1019
1063
|
_lastAccountingFailure?: unknown;
|
|
@@ -539,7 +539,7 @@ function analyzeOrder(botData, config, botKey) {
|
|
|
539
539
|
sell: sellSlots
|
|
540
540
|
},
|
|
541
541
|
// Target active orders from config
|
|
542
|
-
|
|
542
|
+
coreOrdersTarget: config ? config.coreOrders : null,
|
|
543
543
|
// Bot fund allocation settings from config (normalized to strings for
|
|
544
544
|
// the display paths; bots.json allows percentage strings or numbers)
|
|
545
545
|
botFunds: config && config.botFunds
|
|
@@ -1137,9 +1137,9 @@ function formatAnalysis(analysisInput) {
|
|
|
1137
1137
|
lines.push(` Spread:${formatPercent(analysis.spread.real).padStart(6)} | Incr.:${formatPercent(analysis.increment.avg).padStart(6)}`);
|
|
1138
1138
|
}
|
|
1139
1139
|
// Active orders comparison
|
|
1140
|
-
if (analysis.hasConfig && analysis.
|
|
1141
|
-
const buyTarget = analysis.
|
|
1142
|
-
const sellTarget = analysis.
|
|
1140
|
+
if (analysis.hasConfig && analysis.coreOrdersTarget) {
|
|
1141
|
+
const buyTarget = analysis.coreOrdersTarget.buy;
|
|
1142
|
+
const sellTarget = analysis.coreOrdersTarget.sell;
|
|
1143
1143
|
const buyActual = analysis.slots.activeBuy;
|
|
1144
1144
|
const sellActual = analysis.slots.activeSell;
|
|
1145
1145
|
// Collect raw buy/sell values across Active, Weight, Funds for column alignment
|
|
@@ -73,21 +73,21 @@ lines.forEach((line) => {
|
|
|
73
73
|
// Filter out partial orders from divergence calculation
|
|
74
74
|
// Include: 'active' and 'virtual' orders - these represent the intended grid structure
|
|
75
75
|
// Exclude: 'partial' orders - these are temporarily filled and in transition
|
|
76
|
-
const
|
|
77
|
-
const partialOrdersCount = orders.length -
|
|
76
|
+
const nonPartialOrders = orders.filter((o) => o.state !== 'partial');
|
|
77
|
+
const partialOrdersCount = orders.length - nonPartialOrders.length;
|
|
78
78
|
// Calculate divergence metric: sum of ((calculated - persisted) / persisted)^2 / count
|
|
79
79
|
let sumSquaredDiff = 0;
|
|
80
|
-
|
|
80
|
+
nonPartialOrders.forEach((order) => {
|
|
81
81
|
const relativeError = (order.calculated - order.persisted) / order.persisted;
|
|
82
82
|
sumSquaredDiff += relativeError * relativeError;
|
|
83
83
|
});
|
|
84
|
-
const normalizedMetric =
|
|
84
|
+
const normalizedMetric = nonPartialOrders.length > 0 ? sumSquaredDiff / nonPartialOrders.length : 0;
|
|
85
85
|
const promille = normalizedMetric * 1000;
|
|
86
86
|
// Calculate real error as √(promille / 1000)
|
|
87
87
|
const realErrorPercent = Math.sqrt(promille / 1000) * 100;
|
|
88
88
|
console.log('=== QUADRATIC DIVERGENCE ANALYSIS ===\n');
|
|
89
89
|
console.log(`Total orders in input: ${orders.length}`);
|
|
90
|
-
console.log(`Orders analyzed: ${
|
|
90
|
+
console.log(`Orders analyzed: ${nonPartialOrders.length}`);
|
|
91
91
|
if (partialOrdersCount > 0) {
|
|
92
92
|
console.log(`Partial orders excluded: ${partialOrdersCount}`);
|
|
93
93
|
}
|
|
@@ -102,7 +102,7 @@ console.log(` Status: ${promille <= 1 ? '✓ WITHIN THRESHOLD' : '✗ EXCEEDS T
|
|
|
102
102
|
// Show min/max errors
|
|
103
103
|
let minError = Infinity, maxError = -Infinity;
|
|
104
104
|
let minErrorOrder = null, maxErrorOrder = null;
|
|
105
|
-
|
|
105
|
+
nonPartialOrders.forEach((order, idx) => {
|
|
106
106
|
const absError = Math.abs((order.calculated - order.persisted) / order.persisted);
|
|
107
107
|
if (absError < minError) {
|
|
108
108
|
minError = absError;
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
* for each bot entry. This is a health check to ensure configurations are
|
|
7
7
|
* valid before being used by the system.
|
|
8
8
|
*
|
|
9
|
-
* Required fields for each bot: assetA, assetB,
|
|
9
|
+
* Required fields for each bot: assetA, assetB, coreOrders, botFunds
|
|
10
10
|
* Optional field: gridPrice (number | null | "ama"/"ama1".."ama4")
|
|
11
11
|
*
|
|
12
12
|
* Usage: node dist/scripts/validate_bots.js
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
* for each bot entry. This is a health check to ensure configurations are
|
|
7
7
|
* valid before being used by the system.
|
|
8
8
|
*
|
|
9
|
-
* Required fields for each bot: assetA, assetB,
|
|
9
|
+
* Required fields for each bot: assetA, assetB, coreOrders, botFunds
|
|
10
10
|
* Optional field: gridPrice (number | null | "ama"/"ama1".."ama4")
|
|
11
11
|
*
|
|
12
12
|
* Usage: node dist/scripts/validate_bots.js
|
|
@@ -27,7 +27,7 @@ const livePath = PATHS.PROFILES.BOTS_JSON;
|
|
|
27
27
|
* Required fields:
|
|
28
28
|
* - assetA: Base currency symbol (e.g., 'XRP')
|
|
29
29
|
* - assetB: Quote currency symbol (e.g., 'BTS')
|
|
30
|
-
* -
|
|
30
|
+
* - coreOrders: Number of orders in the grid
|
|
31
31
|
* - botFunds: Amount of funds allocated to the bot
|
|
32
32
|
*
|
|
33
33
|
* Output:
|
|
@@ -44,7 +44,7 @@ function checkConfig(obj, src) {
|
|
|
44
44
|
const bots = Array.isArray(o.bots) && o.bots.length ? o.bots : [o];
|
|
45
45
|
console.log(`\n== Checking ${src}: found ${bots.length} bot entries`);
|
|
46
46
|
// List of required fields that every bot must have
|
|
47
|
-
const required = ['assetA', 'assetB', '
|
|
47
|
+
const required = ['assetA', 'assetB', 'coreOrders', 'botFunds'];
|
|
48
48
|
let anyMissing = false;
|
|
49
49
|
let anyGridPriceWarnings = false;
|
|
50
50
|
// Validate each bot entry
|
package/dist/unlock.js
CHANGED
|
@@ -56,8 +56,6 @@ import { buildRuntimeScriptArgs } from './modules/launcher/runtime_entry.js';
|
|
|
56
56
|
import { sendControlCommand } from './modules/launcher/supervisor_control.js';
|
|
57
57
|
import { registerCleanup, setupGracefulShutdown } from './modules/graceful_shutdown.js';
|
|
58
58
|
import { normalizeBotEntry, resolveRawBotEntries, loadSettingsFile } from './modules/bot_settings.js';
|
|
59
|
-
import { main as runBotEditor } from './modules/account_bots.js';
|
|
60
|
-
import { setSuppressConnectionLog, disconnectClient } from './modules/bitshares_client.js';
|
|
61
59
|
import { selectStartOnboardingCommand } from './modules/cli_start_onboarding.js';
|
|
62
60
|
import * as chainKeys from './modules/chain_keys.js';
|
|
63
61
|
import * as credentialPolicy from './modules/credential_policy.js';
|
|
@@ -421,6 +419,13 @@ async function runStartOnboardingIfNeeded({ allowInteractive = true, nonInteract
|
|
|
421
419
|
await chainKeys.main();
|
|
422
420
|
return true;
|
|
423
421
|
}
|
|
422
|
+
// The interactive bot editor drags in the heavyweight native chain client
|
|
423
|
+
// (~80 ms of module graph). It is only needed on this onboarding path, so
|
|
424
|
+
// load it lazily instead of eagerly on every `unlock`/`start` invocation.
|
|
425
|
+
const [{ main: runBotEditor }, { setSuppressConnectionLog, disconnectClient }] = await Promise.all([
|
|
426
|
+
import('./modules/account_bots.js'),
|
|
427
|
+
import('./modules/bitshares_client.js'),
|
|
428
|
+
]);
|
|
424
429
|
setSuppressConnectionLog(true);
|
|
425
430
|
try {
|
|
426
431
|
await runBotEditor();
|
|
@@ -95,7 +95,6 @@ boundary position and slot BUY/SELL roles during blockchain execution.
|
|
|
95
95
|
├─> Create WorkingGrid (clone master)
|
|
96
96
|
├─> Calculate target grid (from strategy)
|
|
97
97
|
├─> Reconcile against working copy
|
|
98
|
-
├─> Validate working grid funds
|
|
99
98
|
└─> Return { workingGrid, actions, ... }
|
|
100
99
|
|
|
101
100
|
2. updateOrdersOnChainBatch(result)
|
|
@@ -265,7 +264,7 @@ During Rebalance**.
|
|
|
265
264
|
|
|
266
265
|
## Safety Guardrails
|
|
267
266
|
|
|
268
|
-
1. **
|
|
267
|
+
1. **Planning-time budget feasibility:** order sizes are derived from `funds.allocated` via `getSideBudget` / `_getSizingContext`, so a proposed grid cannot exceed the side budget by construction. (The historical `Accountant.validateTargetGrid` dry-run was removed — it had no production caller.)
|
|
269
268
|
2. **Atomic Transaction Semantics:** Large boundary shifts (>5 slots) are inherently safe because the COW pattern only commits after successful blockchain confirmation. If market volatility causes rapid shifts during planning, the plan is caught by the **pre-broadcast staleness guard** (`evaluateCommit` against `_gridVersion`): it re-plans ONCE from the fresh master with the same fills (`replanStaleBatch`, bounded by `STALE_PLAN_REPLAN_LIMIT`), then proceeds + structural resync if still stale — never a silent discard that drops the fill set. If the master changes *during* broadcast, the commit-time guard refuses the commit and the placed orders are adopted from chain so on-chain state never runs ahead of the grid.
|
|
270
269
|
3. **Resync on Error:** If any blockchain action fails (e.g., "Insufficient funds"), the bot discards the working grid and triggers `grid_reconcile.ts` for a fresh blockchain sync ([GRID_RECONCILE.md](GRID_RECONCILE.md)).
|
|
271
270
|
|
package/docs/COW_INVARIANTS.md
CHANGED
|
@@ -61,15 +61,15 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
|
|
|
61
61
|
- Funds drive order sizing/budget allocation only; `syncBoundaryToFunds`/`calculateFundDrivenBoundary` are deleted (1.5.3).
|
|
62
62
|
|
|
63
63
|
- `INV-COW-007` Boundary hold on guard-skipped refills
|
|
64
|
-
- When a slot on the plan's refill wire (`collectRefillSlotIds`: the plan's CREATE ids minus
|
|
65
|
-
-
|
|
64
|
+
- When a slot on the plan's refill wire (`collectRefillSlotIds`: the plan's CREATE ids minus edge-ladder edge ids) was guard-skipped at broadcast (`skippedUpdateSlotIds` ∪ `clampedUpdateSlotIds` ∪ `skippedCreateSlotIds`), `resolveRefillBoundaryHold` keeps the COMMITTED boundary instead of committing the plan's shifted one over the stranded rail hole; the grid still commits.
|
|
65
|
+
- Edge-ladder CREATEs are excluded because reserves are static edge insurance whose fills never crawl — a skipped reserve must not pin geometry.
|
|
66
66
|
- The hold rides to the commit as `options.boundaryHeld`, which suppresses the pending-crawl clear.
|
|
67
67
|
- `trackBoundaryHold` counts consecutive hold batches (`manager._consecutiveBoundaryHolds`, cleared on the first clean batch) with a last-hold snapshot (`manager._lastBoundaryHoldInfo`); runs of 3+ escalate visibly. It also records a hold signature (`manager._lastHeldPlanSignature`: committed boundary + guard pivot + `_lastFilledAt` + held wire) so a fill-less re-plan of an unchanged state defers instead of re-broadcasting the identical vetoed plan.
|
|
68
68
|
- Fill-driven rebalances never sleep on `_broadcastingFlag` inside `_fillProcessingLock`: `performSafeRebalance({deferIfBroadcasting:true})` returns a `deferred` result and the region-end hook schedules one no-fill rebalance (`schedulePostRecoveryRebalance`). This prevents the 20s lock-acquisition-timeout cascade when a broadcast region outlives the 30s `_awaitBroadcastIdle` wait. The stale-flag watchdog (`_clearStaleBroadcastFlag`, 120s) fires the same region-end hook when it hard-clears a leaked flag, so deferred fills are woken even when the region never ends through `stopBroadcasting()`.
|
|
69
69
|
- A hold run carrying fresh fills (>= `TIMING.BOUNDARY_HOLD_RESYNC_THRESHOLD`) requests a guard-aware structural re-center (`requestStructuralGridResync`, cooldown `TIMING.BOUNDARY_HOLD_RESYNC_COOLDOWN_MS`) instead of holding forever — the heal path when the grid is trailing the market.
|
|
70
70
|
|
|
71
71
|
- `INV-COW-008` Owed fill crawls survive unapplied commits
|
|
72
|
-
- `order/strategy.ts` records a crawl per shift-eligible fill at intake (slot-level dedupe, capped at 500); `deriveTargetBoundary` folds still-owed `_pendingFillCrawls` into the next derivation, excluding the current batch's slots,
|
|
72
|
+
- `order/strategy.ts` records a crawl per shift-eligible fill at intake (slot-level dedupe, capped at 500); `deriveTargetBoundary` folds still-owed `_pendingFillCrawls` into the next derivation, excluding the current batch's slots, edge slots, and window members — a window that reaches the grid edge is not an edge order, using the same window exclusion every placement picker and `countLiveEdgeOrders` apply.
|
|
73
73
|
- `_commitWorkingGrid` clears them only when the plan's boundary was actually applied — a held boundary (`boundaryHeld`), a gate-rejected boundary, and a null boundary all leave them owed.
|
|
74
74
|
- `consumePendingFillCrawls` applies them onto a restored finite boundary; `applyPersistedPendingCrawls` is the shared startup/recovery wrapper used before sync/reconcile; `_clearPendingFillCrawls` drops them when the boundary is re-anchored (grid rebuild via `initializeGrid`, rejected snapshot via `rejectCorruptedGridSnapshot`, persisted snapshot wipe via `AccountOrders.clearGrid`).
|
|
75
75
|
|
|
@@ -87,11 +87,11 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
|
|
|
87
87
|
- `INV-PROJ-002` Preserve on-chain PARTIAL size in projection
|
|
88
88
|
- If identity is retained (`keepOrderId=true`) and current state is `PARTIAL`, projected size must preserve current on-chain remaining size.
|
|
89
89
|
- It must not be overwritten by ideal geometric `targetSize`.
|
|
90
|
-
- Exception: a `PARTIAL` with a rotation/size-update action targeting its `orderId` does use `targetSize` (the explicit-UPDATE path at `modules/order/utils/validate.ts:
|
|
90
|
+
- Exception: a `PARTIAL` with a rotation/size-update action targeting its `orderId` does use `targetSize` (the explicit-UPDATE path at `modules/order/utils/validate.ts:1187`).
|
|
91
91
|
- Preserve-path size must be normalized to finite, non-negative value.
|
|
92
92
|
|
|
93
93
|
- `INV-PROJ-003` ACTIVE on-chain projection preserves current size (same as PARTIAL)
|
|
94
|
-
- If identity is retained and state is `ACTIVE`, projection preserves current on-chain size via the same `shouldPreserveSize` path as `PARTIAL` (`validate.ts:
|
|
94
|
+
- If identity is retained and state is `ACTIVE`, projection preserves current on-chain size via the same `shouldPreserveSize` path as `PARTIAL` (`validate.ts:1187`).
|
|
95
95
|
- An explicit UPDATE action targeting the `orderId` is required to apply `targetSize`.
|
|
96
96
|
|
|
97
97
|
- `INV-ID-001` Order identity retention rule
|
|
@@ -191,7 +191,7 @@ This document defines the non-negotiable behavioral invariants for the DEXBot2 s
|
|
|
191
191
|
- `INV-GRID-001` One-to-one order mapping
|
|
192
192
|
- One grid slot = at most one on-chain order. No two chain orders may map to the same grid slot.
|
|
193
193
|
- Sync engine tracks `matchedGridOrderIds` through both sync passes and skips already-matched slots.
|
|
194
|
-
- Surplus orders (matched count above the per-side `
|
|
194
|
+
- Surplus orders (matched count above the per-side `coreOrders` + `edgeOrders` targets) are flagged for cancellation.
|
|
195
195
|
|
|
196
196
|
- `INV-GRID-002` One order per price level
|
|
197
197
|
- The active grid must have at most one on-chain order per (type, price) pair.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# DEXBot vs DEXBot2 — Detailed Comparison Report
|
|
2
2
|
|
|
3
3
|
> **Date:** 2026-09-02 *(metrics refreshed against local source trees)*
|
|
4
|
-
> **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.6.
|
|
4
|
+
> **Scope:** Full architectural, functional, and operational comparison between the original [DEXBot](https://github.com/Codaone/DEXBot) (Python, v1.0.0) and DEXBot2 (TypeScript, v1.6.14).
|
|
5
5
|
> **Audience:** Developers, contributors, and operators evaluating or migrating between the two projects.
|
|
6
6
|
|
|
7
7
|
---
|
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
|
|
37
37
|
| Attribute | DEXBot (original) | DEXBot2 |
|
|
38
38
|
|---|---|---|
|
|
39
|
-
| **Release Track** | 1.0.0 | v1.6.
|
|
39
|
+
| **Release Track** | 1.0.0 | v1.6.14 |
|
|
40
40
|
| **Language** | Python 3.6+ | TypeScript 5.x |
|
|
41
41
|
| **Status** | Released 1.0.0, unmaintained | Active development |
|
|
42
42
|
| **Last Repo Activity** | May 23, 2020 | 2026-09-02 |
|
|
@@ -347,7 +347,7 @@ workers:
|
|
|
347
347
|
"targetSpreadPercent": 4,
|
|
348
348
|
"weightDistribution": { "sell": 1, "buy": 1 },
|
|
349
349
|
"botFunds": { "sell": "100%", "buy": "100%" },
|
|
350
|
-
"
|
|
350
|
+
"coreOrders": { "sell": 5, "buy": 5 },
|
|
351
351
|
"poolRef": "1.19.133" // optional: pin a specific pool for price derivation
|
|
352
352
|
}
|
|
353
353
|
```
|
|
@@ -776,10 +776,10 @@ Where:
|
|
|
776
776
|
|
|
777
777
|
| Metric | DEXBot | DEXBot2 |
|
|
778
778
|
|---|---|---|
|
|
779
|
-
| **Release Track** | 1.0.0 | v1.6.
|
|
779
|
+
| **Release Track** | 1.0.0 | v1.6.14 |
|
|
780
780
|
| **Active Since** | ~2018 | December 2025 |
|
|
781
781
|
| **Last Commit** | May 23, 2020 | 2026-10-10 |
|
|
782
|
-
| **Total Commits** | 2281 | 2,
|
|
782
|
+
| **Total Commits** | 2281 | 2,390 (current HEAD, v1.6.14 line) |
|
|
783
783
|
| **Lines of Code** | ~10,846 Python LOC in `dexbot/` | Large TypeScript runtime + adapter + Claw + analysis + tests |
|
|
784
784
|
| **Source Files** | 72 Python files in `dexbot/` | ~656 TS files across the repo |
|
|
785
785
|
| **Test Files** | 16 Python test files | 324 `test_*.ts` files (307 `tests/` + 17 `claw/tests/`, auto-discovered via `globSync`) |
|
package/docs/EVOLUTION.md
CHANGED
|
@@ -2,14 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
## Executive Summary
|
|
4
4
|
|
|
5
|
-
DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.6.
|
|
5
|
+
DEXBot2 is a sophisticated decentralized exchange trading bot for the BitShares blockchain. This report documents the complete evolution of the project from its inception in December 2025 through the current 1.6.14 release.
|
|
6
6
|
|
|
7
7
|
### Key Milestones
|
|
8
8
|
- **Project Inception**: December 2, 2025
|
|
9
|
-
- **Growth Phase**: 2,
|
|
9
|
+
- **Growth Phase**: 2,390 commits over ~9 active months
|
|
10
10
|
- **Code Maturity**: Evolution from basic utilities to a ~100,000+ LoC intelligent TypeScript system
|
|
11
11
|
- **Stability**: Progression from manual testing to a suite of 307 automated test files
|
|
12
|
-
- **Releases**:
|
|
12
|
+
- **Releases**: 146 version entries in the changelog (v0.1.0 to v1.6.14)
|
|
13
13
|
|
|
14
14
|
> **Post-1.0.0 "why":** the thematic story behind the hardening releases — root cause, recurring
|
|
15
15
|
> bug families, and lessons — lives in
|
|
@@ -149,7 +149,7 @@ Evolved from a basic README to a comprehensive framework (50+ docs entries, 80%+
|
|
|
149
149
|
|
|
150
150
|
## Version History
|
|
151
151
|
|
|
152
|
-
Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` over the current history (2026-10-
|
|
152
|
+
Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` over the current history (2026-10-12). The 107 commits up to and including the `v0.1.0` tag are not attributed to an era, so the current totals are 2,283 (`v0.1.0..HEAD`) and 2,390 (`HEAD`); the `v1.4.x` era rows overlap slightly because `v1.4.13` is not an ancestor of `v1.4.25` in the current history. Per-release detail lives in [CHANGELOG.md](../CHANGELOG.md); the thematic post-1.0.0 story in [ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md](ORDER_ENGINE_POST_1.0_RETROSPECTIVE.md).
|
|
153
153
|
|
|
154
154
|
| Era | Commits | Theme |
|
|
155
155
|
|-----|--------:|-------|
|
|
@@ -171,11 +171,12 @@ Compact, era-level view; commit counts are `git rev-list --count <tag>..<tag>` o
|
|
|
171
171
|
| v1.6.10 → v1.6.11 | 6 | AMA-slope 3-bar persistence gate + 16h Huber lookback, EMA-smoothing removal, PnL HTML report + month-shard fill cache, five order-engine/lifecycle safety fixes |
|
|
172
172
|
| v1.6.11 → v1.6.12 | 27 | Explicit-`any` elimination + ratchet, shared ECC core & Firefox-safe pure-JS scrypt, worker-drain and fresh-placement cancel-grace safety fixes, funded spread correction, partial credit renewal, update install-layout classifier, AMA persistence-override fixes, test-suite speedup, dynamic-weight knob retune |
|
|
173
173
|
| v1.6.12 → v1.6.13 | 21 | Spread-stall cause reporting + chain sync on every stall, resync-cascade guards (uncertain broadcast / suspended persistence), month-shard candle cache, dedup & dead-code purge, npm 12 install & PM2 fixes |
|
|
174
|
+
| v1.6.13 → v1.6.14 | 17 | Last-fill guard + live market floor for spread correction, committed-size drift resize, COW pre-broadcast guards & P2 counters, fail-closed unknown geometry, order-key rename, worker-thread test runner |
|
|
174
175
|
|
|
175
176
|
---
|
|
176
177
|
|
|
177
178
|
**Report Originally Generated**: February 19, 2026
|
|
178
|
-
**Last Updated**: October
|
|
179
|
-
**Total Commits**: 2,
|
|
180
|
-
**Date Range**: December 2, 2025 – October
|
|
179
|
+
**Last Updated**: October 12, 2026
|
|
180
|
+
**Total Commits**: 2,390
|
|
181
|
+
**Date Range**: December 2, 2025 – October 12, 2026
|
|
181
182
|
**Repository**: DEXBot2 (BitShares DEX Trading Bot)
|
|
@@ -52,7 +52,7 @@ funds.allocated → _getSizingContext() (budget for spread correction)
|
|
|
52
52
|
**Key points:**
|
|
53
53
|
- `botFunds` percentage applies to **total** capital (free + locked in orders), not just free. A bot at `"50%"` gets half of everything, not half of what's currently idle.
|
|
54
54
|
- `funds.allocated` is the ceiling for each side. Existing orders already consume part of it; the remaining free portion is available for new placements.
|
|
55
|
-
- The downstream `applyBotFundsAllocation()` (`manager.ts:
|
|
55
|
+
- The downstream `applyBotFundsAllocation()` (`manager.ts:1296`) also caps `funds.available` to `<= allocated` as a safety net, but the primary budget chokepoint is `getSideBudget` / `_getSizingContext` reading `allocated` directly (v1.2.6).
|
|
56
56
|
|
|
57
57
|
---
|
|
58
58
|
|
|
@@ -112,7 +112,7 @@ See [developer_guide.md#order-state-helper-functions](developer_guide.md#order-s
|
|
|
112
112
|
|
|
113
113
|
#### Gap-Slot Batch Fill Processing
|
|
114
114
|
|
|
115
|
-
**Mechanism**: Fill events arrive via `modules/dexbot_fill_runtime.ts` (the fill-runtime module), which pushes them into `bot._incomingFillQueue` (declared in `modules/dexbot_class.ts`). The drain loop in `dexbot_fill_runtime.ts` then chunks the queue into capped batches and calls `modules/order/manager.ts::processFilledOrders` (line
|
|
115
|
+
**Mechanism**: Fill events arrive via `modules/dexbot_fill_runtime.ts` (the fill-runtime module), which pushes them into `bot._incomingFillQueue` (declared in `modules/dexbot_class.ts`). The drain loop in `dexbot_fill_runtime.ts` then chunks the queue into capped batches and calls `modules/order/manager.ts::processFilledOrders` (line 1811) once per chunk to run the full rebalance pipeline.
|
|
116
116
|
|
|
117
117
|
**Batch Sizing Algorithm**: Batch size is derived from the grid gap-slot count + 1 (`DEXBot._getGapSlotBatchSize`): a queue depth at or below gapSlots+1 is processed as one unified batch; deeper queues are chunked into repeated batches of gapSlots+1 (the last chunk may be smaller). The same gapSlots+1 size caps order operations per broadcast transaction (oversized op batches are split into sequential broadcasts).
|
|
118
118
|
|
|
@@ -123,7 +123,7 @@ See [developer_guide.md#order-state-helper-functions](developer_guide.md#order-s
|
|
|
123
123
|
**Per-Batch Execution**:
|
|
124
124
|
|
|
125
125
|
1. **Peek & Pop**: Check `_incomingFillQueue`, pop up to N fills (batch size)
|
|
126
|
-
2. **Replay-safe Accounting Pass**: Each fill is accounted individually via `processFillAccounting(fillOp, fillKey)` with replay-safe dedup (`applyReplaySafeFillAccounting`, `dexbot_fill_runtime.ts:
|
|
126
|
+
2. **Replay-safe Accounting Pass**: Each fill is accounted individually via `processFillAccounting(fillOp, fillKey)` with replay-safe dedup (`applyReplaySafeFillAccounting`, `dexbot_fill_runtime.ts:303`)
|
|
127
127
|
- Proceeds credited directly to `chainFree` (via `adjustTotalBalance`)
|
|
128
128
|
- Same-order fill batching (sync_engine Phase 6 cumulative transition) aggregates multiple fill transitions on one order before a single rebalance
|
|
129
129
|
- All proceeds immediately available to next rebalance cycle (not split across cycles)
|
|
@@ -137,7 +137,7 @@ See [developer_guide.md#order-state-helper-functions](developer_guide.md#order-s
|
|
|
137
137
|
|
|
138
138
|
**Result**: 29 fills now processed in ~8 broadcasts (~24s) instead of 29 broadcasts (~90s).
|
|
139
139
|
|
|
140
|
-
**Residual Dust Cancellation** (post-1.4.12): After a sub-dust fill leaves a residual order on chain (e.g. the quote-side value truncates to 0 on `bitshares-core` `maybe_cull_small_order`), the fill runtime explicitly cancels those residuals via `cancelResidualOrders()` (`dexbot_fill_runtime.ts:
|
|
140
|
+
**Residual Dust Cancellation** (post-1.4.12): After a sub-dust fill leaves a residual order on chain (e.g. the quote-side value truncates to 0 on `bitshares-core` `maybe_cull_small_order`), the fill runtime explicitly cancels those residuals via `cancelResidualOrders()` (`dexbot_fill_runtime.ts:191`, `[RESIDUAL]` tag) so a leftover of ≥1 base unit cannot be re-adopted into a grid slot by maintenance.
|
|
141
141
|
|
|
142
142
|
#### Grid Regeneration Trigger (Available Funds Ratio — bidirectional)
|
|
143
143
|
|
|
@@ -156,6 +156,8 @@ SHRINK: overAlloc = (gridTracked - allocatedCapital) / allocatedCapital * 100
|
|
|
156
156
|
|
|
157
157
|
Deliberately no per-side chain-total-drop leg: a normal fill moves value across sides (pays one asset, receives the other — see `processFillAccounting`), so one side's total routinely drops ≥3% on ordinary fills, and the fill pipeline already re-sizes from the post-fill budget.
|
|
158
158
|
|
|
159
|
+
**Committed-Size Drift leg**: the available-funds ratio above is measured as `chainFree − virtual`. The fill/rotation sizing pipeline re-derives VIRTUAL slot sizes from the live budget, so an external deposit (or withdrawal) is folded into the virtual reservation on the first rotation after it lands — `chainFree` and `virtual` move together, the ratio stays pinned at the unallocated remainder, and the on-chain (ACTIVE/PARTIAL) orders can stay at their pre-deposit sizes with no trigger. The committed-drift leg (folded into `checkAndUpdateGridIfNeeded`, exposed drift-only as `checkCommittedSizeDrift`) closes that gap: it computes the geometric ideal for each side from the current budget and compares it against the sizes actually committed on-chain (replaying the resize path's free-balance growth cap). A side whose committed orders would change by ≥ `GRID_REGENERATION_PERCENTAGE` of its **committed size** is flagged on the same ratio leg, so the full side is resized rather than only the fill-generated replacement orders. The denominator is the committed total, not the whole allocation: the on-chain window is a small slice of the plan (the far rail holds most of it), so an allocation-relative fraction would understate a genuine full-side undersize.
|
|
160
|
+
|
|
159
161
|
**How It Works (grow)**:
|
|
160
162
|
1. Fill occurs → proceeds added to `chainFree`
|
|
161
163
|
2. `calculateAvailableFundsValue()` computes true spending power (chainFree minus reservations)
|
|
@@ -525,7 +527,7 @@ BitShares charges fees for `limit_order_create` and `limit_order_cancel`.
|
|
|
525
527
|
|
|
526
528
|
- **Reservation** (`BTS_RESERVATION_MULTIPLIER` in `constants.ts::FEE_PARAMETERS`):
|
|
527
529
|
$$Reserve = N_{active} \times BTS\_RESERVATION\_MULTIPLIER$$
|
|
528
|
-
*(Default: 5× per order — covers create, rotate (cancel+place), update, and cancel over the order's lifetime. $N_{active}$ counts window orders plus the `
|
|
530
|
+
*(Default: 5× per order — covers create, rotate (cancel+place), update, and cancel over the order's lifetime. $N_{active}$ counts window orders plus the `edgeOrders` edge ladder — reserves rest live on-chain and pay fees like window orders)*
|
|
529
531
|
|
|
530
532
|
- **Settlement (`deductBtsFees`):**
|
|
531
533
|
1. Check `Funds.btsFeesOwed`.
|
|
@@ -801,4 +803,4 @@ To prevent "Time-of-Check to Time-of-Use" errors:
|
|
|
801
803
|
**TOCTOU protection in `processFillAccounting`.** `_buildBtsDeferredRefundAdjustment` reads `btsFeeState` from `mgr.orders` while the order lock is held — the lock is acquired before accounting runs, and the POST-RESET and BOOTSTRAP tracked-fill accounting paths follow the same locking pattern.
|
|
802
804
|
|
|
803
805
|
---
|
|
804
|
-
*Technical Reference for DEXBot2 v1.6.
|
|
806
|
+
*Technical Reference for DEXBot2 v1.6.14 release*
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# The Grid-Price Invariant
|
|
2
2
|
|
|
3
3
|
Status: **implemented; the emission check is BLOCKING**
|
|
4
|
-
Last code-reviewed against the v1.6.
|
|
4
|
+
Last code-reviewed against the v1.6.13 release baseline `1a1ae60c` (2026-10-11).
|
|
5
5
|
|
|
6
6
|
## The invariant
|
|
7
7
|
|
|
@@ -413,7 +413,7 @@ is divergence telemetry built on `calculateGridSideDivergenceMetric`.
|
|
|
413
413
|
**A grid with no price ladder is not a degraded grid — it is an undefined one.**
|
|
414
414
|
Every consumer of the invariant reads `priceForSlot(idx, genesis)`, and each one
|
|
415
415
|
silently degrades without it: nearest-slot adoption, `computeOutOfToleranceDriftTag`,
|
|
416
|
-
the materialize descriptor-price fallback, `
|
|
416
|
+
the materialize descriptor-price fallback, `resolveLiveEdgeAnchorPrice`
|
|
417
417
|
tiers 3/4, and the `isSlotInRail` fail-open. That degradation is the tolerance
|
|
418
418
|
matcher, which is exactly the path on which an off-grid price becomes grid
|
|
419
419
|
evidence. So the ladder is treated as a **required** part of a snapshot, not a
|
|
@@ -489,7 +489,7 @@ degrade *into*:
|
|
|
489
489
|
| correction-queue staleness matched by tolerance | `priceSlotEqual` against the slot's own level, and a ladder-less entry is dropped |
|
|
490
490
|
| `computeOutOfToleranceDriftTag` + `price-drift-orphan` auto-cancel (`PRICE_DRIFT_TOLERANCE_MULTIPLIER`) | removed — an off-grid order is HELD (`out-of-grid-deferred`) and resolved structurally, never cancelled off a fuzzy price diff |
|
|
491
491
|
| `findMatchingGridOrderByOpenOrder` | removed (its last production caller was the pass-2 legacy block; the cancelOrder linkage matches by `orderId`) |
|
|
492
|
-
| `
|
|
492
|
+
| `resolveLiveEdgeAnchorPrice` tiers 2/3 (live slot extreme, config bound) | ladder extreme only; a ladder-less manager returns `null` (the live resolver no longer computes a config bound — consumers that want one, e.g. `edgeOrderIdSet`, resolve it themselves) |
|
|
493
493
|
| materialize descriptor-price fallback for a `slot-N` id | kept only for an unparseable id; a `slot-N` id with no ladder logs `error` and requests a structural resync |
|
|
494
494
|
|
|
495
495
|
**E2 is fail-closed.** `syncFromOpenOrders` calls `_assertGenesisInvariant`
|
|
@@ -457,16 +457,19 @@ GRID_LIMITS: {
|
|
|
457
457
|
**Parameters:**
|
|
458
458
|
- `GRID_REGENERATION_PERCENTAGE`: Bidirectional threshold for size recalculation (default: `3%`)
|
|
459
459
|
- Grow: free funds accumulate to ≥3% of allocated capital (e.g. availableFunds ≥ 60 BTS on a 2000 BTS grid)
|
|
460
|
+
- Grow (committed drift): the on-chain (ACTIVE/PARTIAL) orders lag their geometric ideal by ≥3% of the committed size — catches an external deposit that the fill/rotation pipeline already folded into `virtual`, which blinds the `availableFunds = chainFree − virtual` ratio
|
|
460
461
|
- Shrink: grid-tracked size (ACTIVE + PARTIAL + VIRTUAL) exceeds allocation by ≥3% (external fund removal resizes affected orders down; per-side chain totals are not used — fills move value across sides)
|
|
462
|
+
- Shrink (committed drift): the on-chain orders exceed their geometric ideal by ≥3% of the committed size (external withdrawal)
|
|
461
463
|
|
|
462
464
|
### How It Works
|
|
463
465
|
|
|
464
466
|
1. **OrderManager** tracks available funds per side (BUY and SELL separately)
|
|
465
467
|
2. Allocated capital = number of active orders × size per order
|
|
466
|
-
3. When `availableFunds / allocatedCapital × 100 >= GRID_REGENERATION_PERCENTAGE
|
|
468
|
+
3. When `availableFunds / allocatedCapital × 100 >= GRID_REGENERATION_PERCENTAGE`, OR the committed-drift leg flags the side (on-chain orders ≥threshold off their geometric ideal):
|
|
467
469
|
- Triggers `Grid.recalculateGrid()` on that side only
|
|
468
470
|
- Recalculates order sizes to incorporate freed capital
|
|
469
471
|
- Maintains asymmetric fills (BUY fills don't trigger SELL resize)
|
|
472
|
+
- The committed-drift leg is what keeps a deposit that was absorbed into the VIRTUAL reservation from silently leaving the on-chain side un-resized
|
|
470
473
|
4. After the resize, available funds are re-allocated into active orders
|
|
471
474
|
5. Mirror (shrink): when `(gridTracked - allocated) / allocated × 100 >= threshold` (external fund removal), the same path resizes affected orders down
|
|
472
475
|
|
package/docs/GRID_RECONCILE.md
CHANGED
|
@@ -26,7 +26,7 @@ Phase 1 does all reasoning in memory under `_gridLock` (fast); Phases 2 and 3 ex
|
|
|
26
26
|
|
|
27
27
|
Phase 2 and 3 both respect the `dryRun` flag: when true, no on-chain mutations are attempted — plans are logged but not executed.
|
|
28
28
|
|
|
29
|
-
`targetCount` (per side, `targetSell`/`targetBuy`) is sourced from bot config (`
|
|
29
|
+
`targetCount` (per side, `targetSell`/`targetBuy`) is sourced from bot config (`coreOrders` window plus `edgeOrders` edge ladder) and determines how many live orders each side should maintain. The internal `planOnly` flag controls whether `_reconcileStartupSide` records plans for Phase 2 or executes inline — Phase 1 always calls with `planOnly=true`.
|
|
30
30
|
|
|
31
31
|
```
|
|
32
32
|
Grid generated
|
|
@@ -93,7 +93,7 @@ Phase 2 and 3 both respect the `dryRun` flag: when true, no on-chain mutations a
|
|
|
93
93
|
- Match sorted unmatched chain orders to virtual slots → `plannedUpdates`
|
|
94
94
|
- Detect grid-edge lock and plan a largest-order cancel
|
|
95
95
|
- Plan creates for remaining slots
|
|
96
|
-
- Plan excess cancellations (guarded by `matchedOnGrid > 0`): orphans first, then **matched surplus** (`chainCount - targetCount`,
|
|
96
|
+
- Plan excess cancellations (guarded by `matchedOnGrid > 0`): orphans first, then **matched surplus** (`chainCount - targetCount`, edge slots last) — the matched-excess selection is shared by the planOnly and execute branches so planning can never drift from execution; planOnly omits `releaseUntrackedFunds` for matched slots (their funds are tracked on the grid slot)
|
|
97
97
|
- Fork-kept **shelf orders** (live non-slot-N ids below the rail, e.g. `deep-*`) are never cancel candidates or reserve members — see [Shelf Orders](#shelf-orders-fork-kept-manual-orders)
|
|
98
98
|
- **Vacated-rail refill**: each PROCEEDING update whose vacated price exactly matches (`priceSlotEqual`) an empty, sized, in-rail slot of the same side queues a refill CREATE in the same plan (`source startupVacatedRailRefill`) — skipped updates, ghost prices (lattice moved), in-band slots, and already-desired slots never refill; refill targets require VIRTUAL state with no `orderId`
|
|
99
99
|
|
|
@@ -213,7 +213,7 @@ Reconcile's role in the defense-in-depth: during Phase 1, any ACTIVE/PARTIAL ord
|
|
|
213
213
|
|
|
214
214
|
Live on-chain orders with non-slot-N ids below the rail (e.g. `deep-*` manuals kept across a fork) are **shelf orders**: they sit outside the grid contract and must survive every startup path untouched. Three gates enforce this (all no-ops on grids that only mint slot-N ids):
|
|
215
215
|
|
|
216
|
-
- **Reserve classification/placement** (`order.ts`, `grid_reconcile_internal.ts`, `manager.ts`): `
|
|
216
|
+
- **Reserve classification/placement** (`order.ts`, `grid_reconcile_internal.ts`, `manager.ts`): `edgeOrderIdSet`, the Tier-2 live-anchor scan, `_pickEdgeSlots`, and `pickEdgeSlots` all gate to `parseSlotIndex(id) !== null`, so a shelf can never count as the edge (which would mask a real edge deficit) nor be activated as an edge order it would never be counted as. The live-edge count additionally excludes window members via `liveWindowIdSet`, so an edge-reaching window cannot masquerade as dedicated edge orders.
|
|
217
217
|
- **Startup excess cancels** (`grid_reconcile_internal.ts`): the matched-excess selection filters to slot-N ids in both planOnly and execute branches — the cheapest-first sort would otherwise wipe the shelf on the next boot.
|
|
218
218
|
- **Geometric size recalc** (`grid.ts`): `_recalculateGridOrderSizesFromBlockchain` skips non-slot-N slots in the per-slot loop, so divergence-triggered resizing never overwrites manual shelf sizes on-chain (the shelf stays in the budget denominator, so allocation math is unchanged).
|
|
219
219
|
|
|
@@ -286,7 +286,7 @@ Commit `e64db685` replaced 6 single-value boolean state fields with refcounts/st
|
|
|
286
286
|
| `tests/test_race_condition_fixes_batch1.ts` | ABBA deadlock (RC-1B) |
|
|
287
287
|
| `tests/test_async_lock_force_release.ts` | Nested multi-lock re-entrancy |
|
|
288
288
|
| `tests/test_targeted_drift_reconcile.ts` | Active-order shortfall triggers sync |
|
|
289
|
-
| `tests/
|
|
289
|
+
| `tests/test_edge_orders.ts` | Reserve startup coverage: fully-placed matched-surplus cancels, orphan+matched ordering, at-target silence, plan/execute parity, shelf-order survival, reserve-deficit trigger (`buy reserves 0/2`) with filled/disabled/empty-budget silence, window-exclusion counting |
|
|
290
290
|
| `tests/repro_phantom_orders.ts` | Phantom order prevention |
|
|
291
291
|
|
|
292
292
|
---
|
package/docs/LIFECYCLE.md
CHANGED
|
@@ -90,7 +90,7 @@ sequenceDiagram
|
|
|
90
90
|
participant CO as chain_orders (broadcast)
|
|
91
91
|
participant STORE as Storage
|
|
92
92
|
|
|
93
|
-
CH->>Q: enqueue fill(s) (dexbot_fill_runtime.ts:
|
|
93
|
+
CH->>Q: enqueue fill(s) (dexbot_fill_runtime.ts:466)
|
|
94
94
|
FR->>FR: drain queue -> _processFillsWithBatching
|
|
95
95
|
FR->>OM: processFilledOrders() (manager.ts)
|
|
96
96
|
OM->>AC: processFillAccounting() (single call, batch)
|
|
@@ -134,10 +134,10 @@ sequenceDiagram
|
|
|
134
134
|
participant STORE as Storage
|
|
135
135
|
|
|
136
136
|
MA->>CL: AMA center snapshot updated
|
|
137
|
-
CL->>CL: _performPeriodicGridChecks() (dexbot_class.ts:
|
|
138
|
-
CL->>RT: performPeriodicGridChecks() (dexbot_maintenance_runtime.ts:
|
|
139
|
-
RT->>RT: runGridMaintenance(bot,'periodic') (dexbot_maintenance_runtime.ts:
|
|
140
|
-
RT->>RT: executeMaintenanceLogic() (dexbot_maintenance_runtime.ts:
|
|
137
|
+
CL->>CL: _performPeriodicGridChecks() (dexbot_class.ts:1720)
|
|
138
|
+
CL->>RT: performPeriodicGridChecks() (dexbot_maintenance_runtime.ts:1677)
|
|
139
|
+
RT->>RT: runGridMaintenance(bot,'periodic') (dexbot_maintenance_runtime.ts:2953)
|
|
140
|
+
RT->>RT: executeMaintenanceLogic() (dexbot_maintenance_runtime.ts:2462)
|
|
141
141
|
RT->>AC: recalculate funds from balances
|
|
142
142
|
RT->>GD: promote AMA center -> grid center
|
|
143
143
|
RT->>GD: recalculateGrid() (grid.ts)
|
|
@@ -157,13 +157,13 @@ The AMA signal stack (AMA/Kalman/Hurst/PE) is *research-tuned* in `analysis/` an
|
|
|
157
157
|
the parameters.
|
|
158
158
|
|
|
159
159
|
> Note: `runMaintenance()` is a **different** subsystem — the credit/MPA debt
|
|
160
|
-
> runtime (`modules/credit_runtime.ts:
|
|
161
|
-
> `_runCreditRuntimeMaintenance` at `dexbot_class.ts:
|
|
160
|
+
> runtime (`modules/credit_runtime.ts:3441`, reached via
|
|
161
|
+
> `_runCreditRuntimeMaintenance` at `dexbot_class.ts:1837`). The grid maintenance
|
|
162
162
|
> chain above is the one that matters for order/price upkeep.
|
|
163
163
|
|
|
164
|
-
References: `modules/dexbot_class.ts:
|
|
165
|
-
`modules/dexbot_maintenance_runtime.ts:
|
|
166
|
-
`:
|
|
164
|
+
References: `modules/dexbot_class.ts:1720` (`_performPeriodicGridChecks`) →
|
|
165
|
+
`modules/dexbot_maintenance_runtime.ts:1677` (`performPeriodicGridChecks`) →
|
|
166
|
+
`:2953` (`runGridMaintenance`) → `:2462` (`executeMaintenanceLogic`),
|
|
167
167
|
`docs/GRID_RECALCULATION.md`, `docs/GRID_RECONCILE.md`.
|
|
168
168
|
|
|
169
169
|
---
|
|
@@ -192,7 +192,7 @@ enforced*, not compiler-enforced — learn them or you will introduce fund bugs.
|
|
|
192
192
|
| How a fill becomes orders | `modules/dexbot_fill_runtime.ts` → `modules/order/manager.ts` |
|
|
193
193
|
| Grid math / recalculation | `modules/order/grid.ts`, `docs/GRID_RECALCULATION.md` |
|
|
194
194
|
| Funds & accounting | `modules/order/accounting.ts`, `docs/FUND_MOVEMENT_AND_ACCOUNTING.md` |
|
|
195
|
-
| Periodic loop & AMA hook | `modules/dexbot_maintenance_runtime.ts`, `modules/dexbot_class.ts:
|
|
195
|
+
| Periodic loop & AMA hook | `modules/dexbot_maintenance_runtime.ts`, `modules/dexbot_class.ts:1720` |
|
|
196
196
|
| Market signal source | `market_adapter/market_adapter.ts`, `analysis/README.md` |
|
|
197
197
|
| Startup & orchestration | `modules/dexbot_class.ts`, `docs/developer_guide.md` §"Startup Sequence" |
|
|
198
198
|
| Why COW exists | `docs/architecture.md` §"Copy-on-Write (COW) Grid Pattern", `docs/COW_INVARIANTS.md` |
|