Skip to content

fix(transfer): never report a failed balance lookup as a successful Result - #12

Merged
ngurmen merged 2 commits into
mainfrom
mng/balance-result-semantics
Sep 20, 2026
Merged

ngurmen merged 2 commits into
mainfrom
mng/balance-result-semantics

Conversation

@ngurmen

@ngurmen ngurmen commented Sep 20, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Return Result.fail from get_chain_wallet_balance when the RPC read fails; previously an RPC 500 produced Result.ok({"balance": "Error: ..."}), which TradeBots turned into decimal.ConversionSyntax on 2026-09-19. Failed entries now carry balance=None plus an error key, never a string sentinel in balance.
  • Report partial failures in get_chain_wallet_balances / get_all_chain_wallet_balances through an additive errors list instead of pushing error-string entries into chain_balances; the Result fails only when every lookup failed. _fetch_erc20_balances_list reports failed tokens instead of silently dropping them.
  • Stop caching failed Results in ttl_cached / async_ttl_cached across all four tiers; stampede waiters still receive the failure, the next caller retries. Rewrote test_get_deployment_uses_cache, which was only "instant" because it cached a failure.
  • Add a level kwarg to _sanitize_error (default ERROR, unchanged elsewhere); balance helpers log at WARNING without a traceback.
  • Bump version to 0.6.2 and sync docs/index.md (was stale at 0.4.0). Docs: README, user guide, error-handling, sdk-caching, remediation plan (new H-6), CLAUDE.md.

Quality Gates

  • ruff check . / ruff format --check . clean
  • mypy --config-file mypy.ini --follow-imports=silent clean (61 files)
  • pytest --cov=src --cov-fail-under=100 tests/unit (1201 passed, 100% coverage)
  • bandit -r src --severity-level high + pip-audit --skip-editable clean
  • scripts/version_manager.py validate in sync at 0.6.2

Behavioural changes

  • get_chain_wallet_balance now fails instead of succeeding with a non-numeric balance on RPC errors, unknown tokens, or Dexalot L1 not connected.
  • Plural balance results gain an errors: list[str] field; failed entries are no longer present in chain_balances.
  • get_chain_token_balances now fails when a requested token's RPC read fails (it already failed for unknown tokens).
  • Any cached method returning Result.fail is no longer served from cache for the TTL; the next call retries.
  • Per-token balance RPC failures log one WARNING line instead of an ERROR with a stack trace.

…esult

An RPC failure in _get_native_balance / _get_erc20_balance /
_get_l1_native_balance used to write "Error: ..." (or "Not connected")
into the entry's `balance` field, and get_chain_wallet_balance wrapped
that entry in Result.ok. Consumers doing Decimal(balance) then raised
decimal.ConversionSyntax, and the poisoned Result sat in the 10 s
balance cache. Seen in TradeBots on 2026-09-19 after an Avalanche RPC
HTTP 500 on eth_getBalance.

- Failed entries now carry balance=None plus an `error` key
  (_balance_error_entry); no string sentinel ever lands in `balance`.
- get_chain_wallet_balance returns Result.fail for any error entry
  (L1, native and ERC20 paths alike).
- get_chain_wallet_balances / get_all_chain_wallet_balances drop failed
  entries from chain_balances, report them in an additive `errors`
  list, and fail only when every lookup failed.
  _fetch_erc20_balances_list emits error entries instead of silently
  skipping failed tokens.
- ttl_cached / async_ttl_cached no longer store a Result with
  success=False, in any tier; stampede waiters still receive it.
- _sanitize_error gains a `level` kwarg (default ERROR, unchanged);
  balance helpers log at WARNING without a traceback.

Docs: README, user guide, error-handling, sdk-caching, remediation
plan (new H-6), CLAUDE.md non-obvious decisions.
@ngurmen
ngurmen requested review from ilkerulutas and removed request for ilkerulutas September 20, 2026 09:12
@ngurmen
ngurmen merged commit e93498f into main Sep 20, 2026
3 checks passed
@ngurmen
ngurmen deleted the mng/balance-result-semantics branch September 20, 2026 09:24
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.

2 participants