StarkLP Lab

Starknet concentrated-liquidity economics, reproduced rather than advertised.

StarkLP Lab is an analytics-only research PoC for Ekubo pools on Starknet. It compares a hypothetical, no-rebalance LP range with a fixed-entry 50/50 HODL portfolio and records AVNU quote conditions. It never holds keys, trades, opens positions, or manages live capital.

Live demo

Public dashboard: https://starklp-lab-domain.streamlit.app/

The dashboard presents the pinned Starknet mainnet / Ekubo P0 evidence, including the 30-day ETH/USDC.e LP-vs-50/50-HODL replay.

Analytics only. No keys, trades, positions, or live capital.

P0 technical status

TECHNICAL_P0_GATE: PASS
MAINNET: Starknet
PRIMARY DEX: Ekubo
EXECUTION BENCHMARK: AVNU
LIVE CAPITAL: NO

Verified P0

• Official Ekubo mainnet dump provenance and immutable snapshot hashes.
• Three real concentrated-liquidity pools with exact historical Core RPC parity.
• Official SDK parity on those same pool states.
• A 30-day no-rebalance LP versus fixed 50/50 HODL replay.
• Immutable mainnet reproduction and 82 Python 3.12 tests.

See evidence/P0_FINAL_TECHNICAL_REPORT.md.

What this repository does

• Uses an immutable official Ekubo indexer GitHub Actions PostgreSQL dump as the primary mainnet source; pairs are never embedded in the ranking policy.
• Validates an immutable event snapshot before replaying it in block/event order.
• Models a fixed range position and a fixed 50/50 HODL benchmark from the same entry price and capital.
• Writes hashes, row counts, timestamps and warnings to a manifest.
• Requests AVNU quotes only; a no-route is a recorded result, never a fake quote.

Important limits

data/sample/ is a deterministic synthetic fixture, used solely to exercise the offline pipeline. It is not Starknet mainnet evidence and cannot make a mainnet or grant gate pass. Fee attribution in P0 is a transparent proportional active-liquidity model, not an exact Ekubo fee-growth reconstruction; it is labelled MODELED_PROXY everywhere. Exact pool price/tick conversion is delegated to the optional official SDK bridge and fails closed when that bridge is absent.

Run

Python 3.12 is the supported runtime (CI should use 3.12).

cp .env.example .env
python -m pip install -e '.[dev]'
cd sdk_bridge && npm ci && cd ..
make test
make reproduce-p0-mainnet
streamlit run app/streamlit_app.py
uvicorn starklp.api.main:app --reload

make reproduce-p0-mainnet is the reviewer-facing reproduction path and never fetches latest data. make reproduce-p0 is intentionally offline and emits a manifest whose source is synthetic_fixture_not_mainnet; it is test-only. To produce new reviewer-grade evidence, provide an immutable real indexer export and RPC configuration, then run python -m starklp.cli run-live --input <events.csv> --pools <pools.csv> --attestation <attestation.json>. Without a hash-matching mainnet indexer attestation, the command labels input as unverified and blocks headline performance. The command refuses FAIL data and preserves input ordering by (block_number, event_index).

Official indexer snapshot path

The public pool-discovery API is informational only during the observed Starknet-address incompatibility/degradation; it cannot satisfy a mainnet gate. The primary source is the official Ekubo indexer Dump Database workflow. Its full PostgreSQL dump is deliberately not committed. Place the official artifact's extracted custom dump at external/ekubo-indexer/db-backup.dump, then run:

.\.venv\Scripts\python.exe -m starklp.cli attest-ekubo-dump --indexer-git-sha <40-character-run-SHA> --run-id <run-id> --artifact-id <artifact-id>
.\.venv\Scripts\python.exe -m starklp.cli ekubo-restore-command --database-url $env:EKUBO_INDEXER_DSN
.\.venv\Scripts\python.exe -m starklp.cli ekubo-schema-inventory-sql

The first command hashes and attests the exact dump. The second prints (rather than hides) the official pg_restore --clean --if-exists --no-owner invocation. Schema inventory and extraction are performed only after restoring that dump; the replay reproduction path must consume the small hash-verified normalized snapshot derived from it and never fetches “latest” data.

Why this stack

Starknet is the target chain. Ekubo is the primary concentrated-liquidity integration; its protocol-specific pool semantics must come from the official SDK, not Uniswap assumptions. AVNU provides an independent, quote-only execution reality check. PostgreSQL and the official Ekubo indexer are supported through the supplied Docker composition; immutable Parquet/CSV snapshots feed DuckDB or the deterministic Python replay.

Data sources and methodology

Live runs record the indexer source URL/export identity, direct Starknet RPC responses, AVNU response timestamps, software versions, hashes and warnings. At entry, LP and HODL are valued at the same capital; HODL receives half of the capital in each token by entry value and is never rebalanced. LP NAV is marked from range inventory plus modeled fees. Alpha is LP NAV - HODL NAV.

This is research software, not investment advice, a yield promise, execution software, custody software, or a recommendation to provide liquidity.

Gate discipline

See docs/gates.md. A gate only passes when its corresponding evidence exists and validates. A repository local to this machine is not a public repository; synthetic fixtures are not real pools; an unavailable SDK/RPC does not become parity.

License

Apache-2.0. See LICENSE.