Skip to content

feat: include HIP-3 DEX clearinghouses in the account snapshot (standard abstraction) - #189

Merged
keitaj merged 2 commits into
mainfrom
feat/hip3-dex-equity
Nov 19, 2026
Merged

keitaj merged 2 commits into
mainfrom
feat/hip3-dex-equity

Conversation

@keitaj

@keitaj keitaj commented Nov 19, 2026

Copy link
Copy Markdown
Owner

Summary

  • Under standard abstraction (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 perp accountValue and 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.
  • Under unified account / portfolio margin the DEX margin is a hold on the spot balance that the snapshot already counts, so unconditionally adding it would double count. The behaviour is therefore opt-in via a new env flag, default off = unchanged legacy behaviour.
  • The bot now logs the account's abstraction mode at startup and warns when it contradicts the flag, in either direction.

Changes

  • config.py: INCLUDE_HIP3_DEX_EQUITY (bool, default false).
  • account_utils.py: set_hip3_dexes() / get_hip3_dexes() (startup setter, mirrors set_snapshot_cache_ttl; invalidates the snapshot cache). When set, get_account_snapshot also calls info.user_state(address, dex) per DEX and adds marginSummary.accountValue to account_value and totalMarginUsed to margin_used. A DEX API failure uses last_known_balance when 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(), calls set_hip3_dexes(TRADING_DEXES) when the flag is on, then _check_abstraction_mode() (queries userAbstraction through api_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; missing marginSummary counts zero; all warning combinations.

No risk-guard thresholds change. Callers (risk_manager, base_strategy, margin_validator) are untouched.

Test plan

  • Unit tests added (16)
  • flake8 passes
  • pytest passes (full suite)
  • No regressions in existing tests

🤖 Generated with Claude Code

…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 keitaj left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 keitaj left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-review (after 7911cdf)

Both findings from the previous review are addressed:

  1. Fallback double count (blocker) — fixed. used_last_known is set when the spot fallback substitutes last_known_balance, and the DEX addition is skipped in that case. New test test_spot_fallback_does_not_double_count_dex_equity asserts account_value == last_known_balance exactly and that no DEX call is even issued.
  2. Uncached DEX calls (should-fix) — fixed. DEX totals are fetched by _fetch_dex_totals behind a per-address cache with the snapshot TTL, read in both the cached and the pre-fetched user_state paths; invalidate_snapshot_cache / set_hip3_dexes clear 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.

@keitaj
keitaj merged commit 12aa04d into main Nov 19, 2026
@keitaj
keitaj deleted the feat/hip3-dex-equity branch November 19, 2026 21:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant