Repository navigation
feat: include HIP-3 DEX clearinghouses in the account snapshot (standard abstraction) - #189
Conversation
…ard abstraction) Under standard abstraction every HIP-3 DEX keeps its own margin balance, so the shared account snapshot (perp accountValue + spot stablecoins) misses the margin parked on each DEX and every position cap and margin guard runs on an understated value. Under unified account / portfolio margin the same DEX margin is a hold on the spot balance that is already counted, so adding it would double count. - INCLUDE_HIP3_DEX_EQUITY (default false = legacy) opts in; when on, the snapshot sums each TRADING_DEXES clearinghouse's accountValue and totalMarginUsed, with the same last-known-balance fallback as spot. - The bot logs the account's userAbstraction at startup and warns when it contradicts the flag (double count / understated). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
keitaj
left a comment
There was a problem hiding this comment.
Review: include HIP-3 DEX clearinghouses in the account snapshot
The opt-in design is right (default off keeps legacy behaviour; the mode/flag consistency check is a pure, tested function; callers and risk-guard thresholds are untouched). The userAbstraction mode strings match the docs ("disabled" = standard). But the interaction with the existing fallback paths in get_account_snapshot has one real defect and one performance gap, both visible from how risk_manager calls it.
1. Spot fallback + DEX loop double counts DEX equity (blocker)
account_utils.py — spot except API_ERRORS branch followed by the new for dex in _hip3_dexes loop:
risk_manager passes last_known_balance=self._last_known_balance, which is the previous snapshot.account_value. With INCLUDE_HIP3_DEX_EQUITY on, that value already contains the DEX equity. When the spot call fails, the code sets account_value = last_known_balance (full value, DEX included) and then the DEX loop adds the DEX accountValue on top. Result: an overstated account value for that cycle, i.e. larger position caps and a looser margin ratio — the opposite of the conservative fallback the spot path intends.
Suggestion: Track whether the spot fallback was used and skip the DEX addition in that case — last_known_balance is a complete snapshot value and must not be augmented. Add a test: spot raises, last_known_balance given, DEXes configured → account_value == last_known_balance exactly.
2. DEX calls are uncached on the pre-fetched user_state path (should-fix)
account_utils.py — DEX loop placement vs. the cache check at the top of the function:
The snapshot cache is only consulted when user_state is None. risk_manager always passes a pre-fetched user_state, so every risk check would issue one user_state(address, dex) call per DEX with no caching, while the spot call in the same path has the same issue only because it was already there. The point of the cache ("multiple callers in the same bot cycle share one set of API calls") does not extend to the new calls.
Suggestion: Cache the summed DEX totals per address with the same TTL (_snapshot_cache_ttl) and read through that cache in both paths; clear it in invalidate_snapshot_cache / set_hip3_dexes. Fetching all configured DEXes as one unit (all-or-nothing) also simplifies the failure semantics: on any DEX error, either fall back to last_known_balance or add nothing, rather than a partial sum. Add tests for cache reuse on the pre-fetched path and for invalidation.
Verdict: Changes requested
One blocker (fallback double count) and one should-fix (uncached DEX calls). Re-review after the fix per the PR process.
…oss both snapshot paths Review fixes on #189: - last_known_balance is a complete prior snapshot (DEX equity included when enabled), so when the spot fallback substitutes it the DEX loop is skipped instead of adding the DEX accountValue a second time. - DEX totals are fetched all-or-nothing behind their own per-address TTL cache (cleared with the snapshot cache), so callers passing a pre-fetched user_state no longer re-query every DEX on each call. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
keitaj
left a comment
There was a problem hiding this comment.
Re-review (after 7911cdf)
Both findings from the previous review are addressed:
- Fallback double count (blocker) — fixed.
used_last_knownis set when the spot fallback substituteslast_known_balance, and the DEX addition is skipped in that case. New testtest_spot_fallback_does_not_double_count_dex_equityassertsaccount_value == last_known_balanceexactly and that no DEX call is even issued. - Uncached DEX calls (should-fix) — fixed. DEX totals are fetched by
_fetch_dex_totalsbehind a per-address cache with the snapshot TTL, read in both the cached and the pre-fetcheduser_statepaths;invalidate_snapshot_cache/set_hip3_dexesclear it. All-or-nothing: a failing DEX propagates and nothing partial is cached or added. New tests cover cache reuse on the pre-fetched path, invalidation, and the all-or-nothing failure case.
Re-checked: callers unchanged, risk-guard thresholds unchanged, default behaviour (flag off) byte-identical to before — the DEX block is gated on _hip3_dexes being set.
Verdict: LGTM
CI: flake8 clean, full suite passing. Merging.
Summary
userAbstraction == "disabled") each HIP-3 DEX keeps its own margin balance in its own clearinghouse. The shared account snapshot (account_utils.get_account_snapshot) only summed the standard perpaccountValueand spot stablecoins, so the margin parked on each DEX was invisible: position caps (ACCOUNT_CAP_PCT-style sizing) and margin guards ran on an understated account value.Changes
config.py:INCLUDE_HIP3_DEX_EQUITY(bool, defaultfalse).account_utils.py:set_hip3_dexes()/get_hip3_dexes()(startup setter, mirrorsset_snapshot_cache_ttl; invalidates the snapshot cache). When set,get_account_snapshotalso callsinfo.user_state(address, dex)per DEX and addsmarginSummary.accountValuetoaccount_valueandtotalMarginUsedtomargin_used. A DEX API failure useslast_known_balancewhen provided (same contract as the spot fallback) so a transient error does not shrink every cap for a cycle; without a fallback the failing DEX is skipped and logged.abstraction_mismatch_warning()is a pure function encoding the consistency rule;"default"/"dexAbstraction"/ unknown modes never warn.bot.py: after_init_connections(), callsset_hip3_dexes(TRADING_DEXES)when the flag is on, then_check_abstraction_mode()(queriesuserAbstractionthroughapi_wrapper; never raises).README.md: env example + AI parameter reference.tests/test_account_utils.py: 16 new tests — legacy default makes no DEX calls; equity and margin summed across DEXes with spot; setter drops empty names and invalidates the cache; DEX failure with/without fallback; missingmarginSummarycounts zero; all warning combinations.No risk-guard thresholds change. Callers (
risk_manager,base_strategy,margin_validator) are untouched.Test plan
flake8passespytestpasses (full suite)🤖 Generated with Claude Code