Portfolio Rebalancer

LIVE ON STARKNET MAINNET

This is the MVP product. The portfolio rebalancer is running on Starknet mainnet at zkde.fi/portfolio — real capital, real transactions, real receipts. Currently tracking ~$75M across Starknet DeFi.

The rebalancer keeps your portfolio aligned with your target allocation across Starknet protocols. Markets move, positions drift, yields change — the system catches the drift, generates an AI-recommended rebalance plan, runs risk checks, and executes. It can run manually (you trigger each step) or autonomously (the agent handles it within session key bounds).

What /portfolio does

When you open /portfolio, you see:

• Current balances across ETH, STRK, USDC, and WBTC
• Target allocation — what your portfolio should look like
• Drift indicator — how far your current state has deviated (aligned / watch / rebalance)
• AI recommendation — the system's suggested rebalance plan, factoring in yields from Ekubo, Vesu, and staking
• Risk assessment — policy-aware checks before execution

The rebalancer routes through mainnet protocols directly via your wallet:

Protocol	How it's used	Network
Ekubo	Swap execution, LP positions, fee collection	Mainnet (via Ekubo Router)
Vesu	Position scanning, lending routes	Mainnet
Staking	Staking position reads	Mainnet

MAINNET EXECUTION MODEL

On mainnet, the backend builds calldata targeting mainnet Ekubo Router, and your wallet signs+submits directly. This is different from the Sepolia proof-gated pipeline, where transactions route through VaultController → AllocationRouter → Adapter contracts. The Sepolia adapter contracts (EkuboLpAdapter, LendingAdapter, StakingAdapter) are not yet on mainnet.

The pipeline

Every rebalance — manual or autonomous — follows the same six-stage pipeline:

flowchart LR
  A["<b>Analyze</b><br/>How far has the<br/>portfolio drifted?"] --> B["<b>Propose</b><br/>What changes<br/>would fix it?"]
  B --> C["<b>Check</b><br/>Do the changes<br/>pass risk screening?"]
  C --> D["<b>Prepare</b><br/>Build execution<br/>context + calldata"]
  D --> E["<b>Execute</b><br/>Submit to chain"]
  E --> F["<b>Receipt</b><br/>Record result +<br/>update trust state"]

1. Analyze — the system looks at your current portfolio composition and compares it against your target allocation. It computes drift metrics: how much each position has deviated from its target weight, and whether the aggregate drift exceeds your tolerance threshold.

2. Propose — based on the analysis, the system generates a rebalance proposal. This includes specific trades: "sell X of token A, buy Y of token B, adjust LP range on pool C." The proposal is a plan, not an execution. On mainnet, the AI recommendation factors in current yields across Ekubo, Vesu, and staking.

3. Check — the proposal runs through risk screening. Risk score, anomaly detection, impermanent loss prediction, correlation risk — whatever applies to the proposed trades. If the screening flags the proposal, it gets caught here. There's also an advisory mode that returns risk signals without blocking.

4. Prepare — the approved proposal is converted into execution context: calldata for each trade, simulation results, adapter routing, gas estimates. At this point you have everything needed to execute, but nothing has been submitted yet.

5. Execute — calldata goes to chain. For manual mode, the user signs each tx in their wallet. For autonomous mode, the agent submits within session key bounds.

6. Receipt — results are recorded in ReceiptRegistry on mainnet. Trust state updates. The cycle closes.

Endpoints

All endpoints are under /api/v1/zkdefi/rebalancer/:

Stage	Method	Path	What it does
Analyze	POST	/analyze	Assess portfolio drift against target allocation
Propose	POST	/propose	Generate a rebalance proposal with specific trades
Check	POST	/check	Run risk/anomaly screening against the proposal (blocking)
Advisory check	POST	/advisory-check	Same screening, but returns signals without blocking
Prepare	POST	/prepare	Build execution context — calldata, simulation, routing
Execute	POST	/execute	Submit the prepared rebalance to chain

Autonomous mode

If you've granted a session key with rebalancing permissions, the agent can run the pipeline automatically. It watches for drift, proposes adjustments, screens them, and executes — all within the bounds you set.

Method	Path	Auth	What it does
POST	/autonomous/start	X-Wallet-Address	Start autonomous rebalancing
POST	/autonomous/stop	X-Wallet-Address	Stop it
GET	/autonomous/status/{address}	Public	Check if autonomous mode is active
POST	/autonomous/pause/{address}	X-Wallet-Address	Pause without fully stopping
POST	/autonomous/resume/{address}	X-Wallet-Address	Resume after pause
GET	/autonomous/all	X-Admin-Key	Fleet status — all users (admin only)

Autonomous mode respects your session key constraints. If the agent proposes a trade that exceeds your max position size or touches a protocol not in your allowed list, the session key validation rejects it before it goes to chain.

Check modes

The check stage supports two modes:

• Strict mode — risk screening is a hard gate. If the circuits flag the proposal, execution can't proceed. Used for autonomous operations where the agent needs guardrails.
• Advisory mode — risk screening returns signals, but the user decides. Used for manual rebalancing where the human is in the loop.

Mainnet contracts

The rebalancer on mainnet uses:

Contract	Role	Network
ReceiptRegistry	Immutable receipt per rebalance operation	Mainnet
ReceiptOS Archive	Permanent receipt archive	Mainnet
Ekubo Router	Swap execution target	Mainnet (third-party)
Ekubo Core	Pool state + pricing	Mainnet (third-party)

The backend reads your positions via mainnet RPC (position_scanner.py, ekubo_config.py), builds calldata for the Ekubo mainnet router, and returns it to the frontend. Your wallet signs and submits directly.

What about VaultController, AllocationRouter, adapters?

Those are on Starknet Sepolia — part of the proof-gated execution pipeline that's coming to mainnet. On Sepolia, the flow goes: proof → VaultController → AllocationRouter → Adapter → protocol. On mainnet today, the flow is simpler: recommendation → calldata → your wallet → Ekubo directly.

Server-side execution gates

Server-side mainnet execution is double-gated off by default. Both EXECUTOR_LIVE_SUBMIT_MAINNET and EXECUTION_GATE_ALLOW_MAINNET_LIVE must be true for the backend to submit transactions on your behalf. In practice, your wallet signs everything.

Full addresses: Contracts

Trying it out

Go to zkde.fi/portfolio. Connect your wallet (ArgentX or Braavos on Starknet mainnet). If you have ETH, STRK, or USDC, the system will show your current allocation and suggest a target. From there, the AI recommendation engine takes over.

For the deeper proof pipeline that the Sepolia version exercises (zkML circuits, five proof lanes, privacy rails), see Proof Pipeline.