Red Alarm tells BNB Chain users if a vault is a scam. vault-xray tells them how a real vault actually makes money — and what can take it away.
An open-source, contract-level analyzer for BSC DeFi vaults/strategies. Point it at a vault and it produces a structured, evidence-cited breakdown of:
- Where the yield comes from — lending interest, trading/LP fees, token emissions, leverage, staking — attributed by resolving the vault's actual on-chain dependencies, not guessed.
- What can take it away (risk surface) — admin/upgrade/oracle/fee powers, leverage/liquidation exposure, exit constraints, timelock gaps.
- Confidence — degrades and flags clearly when a proxy's implementation is unverified.
This is a proof-of-concept supporting a BNB Chain Builder Grant proposal. It is the evidence that the approach works, not the finished product.
The deterministic core is the source of truth. Every finding carries the on-chain evidence (function name, dependency address, event, timelock value) that produced it. The LLM is only a phrasing layer on top of cited, structured facts — it cannot introduce a claim that isn't backed by evidence. A test (test_no_hallucination_every_claim_has_evidence) enforces this: the narrative must cite evidence for every finding.
The shipped narrate() is a deterministic template, not a live model call — wiring an actual LLM into that constrained slot is future work (see Scope & honesty).
| Path | Role |
|---|---|
src/vault_xray/registry.py |
Curated registry of known BSC yield-source protocols (Venus, PancakeSwap, Lista, oracles…) → maps a called address to a yield category. |
src/vault_xray/analyzer.py |
Deterministic core: proxy/verification handling, admin-power extraction from ABI, yield-source attribution, risk-surface detection, confidence scoring. |
src/vault_xray/report.py |
Assembles the structured analysis into a human-readable, evidence-cited report (the LLM-narration slot). CLI + --json. |
examples/ |
Three worked BSC artifacts: a leveraged Venus vault, an emissions-only farm, an unverified proxy. |
tests/test_vault_xray.py |
6 tests: yield attribution, risk surface, emissions-sustainability flag, unverified-proxy degradation, no-hallucination invariant, registry sanity. |
Requires Python ≥ 3.10. No runtime dependencies for the core.
# from the repo root
python -m pip install -e ".[dev]" # installs the package + pytest
pytest -q # 6/6 passing
# human-readable report
python -m vault_xray.report examples/sample_vault.json
# machine-readable
python -m vault_xray.report examples/sample_vault.json --jsonAfter pip install, a vault-xray console script is also available:
vault-xray examples/sample_vault.jsonvault-xray attributes the yield to Venus lending + PancakeSwap fees + leverage + emissions, then flags the risk surface: owner can change the oracle, swap the strategy, upgrade the logic, and pause — behind only a 1-hour timelock — plus liquidation exposure from borrowing. That's the gap above "is it a scam": a non-scam vault whose operator powers and thin timelock are the real risk.
- Attribution is highest-confidence on verified, ERC-4626-style, known-protocol vaults; it degrades gracefully and labels low confidence on unverified proxies (heimdall-style bytecode analysis is future work).
- The registry is a seed set; the funded work expands and community-maintains it.
- Yield-source attribution (vs. just listing dependencies) is the hard, defensible core and the focus of the grant.
- The narration layer is a deterministic template today; a constrained LLM phrasing layer (that may only restate cited facts) is future work.
- DappBay Red Alarm (the "is it a scam?" layer vault-xray sits above): https://dappbay.bnbchain.org/red-alarm
- BNB Chain developer docs: https://docs.bnbchain.org/
- Venus Protocol (lending): https://docs.venus.io/
- PancakeSwap (trading/LP fees): https://docs.pancakeswap.finance/
- Lista DAO (liquid staking): https://lista.org/
MIT © 2026 Ruiyang Zhang. See LICENSE.