Concentrated Liquidity

HivemindOS can watch a real Uniswap v3 position on Base and model when moving its price range may be worthwhile. The manager is deliberately shadow-only: it reads public chain state and updates a virtual range, but it has no signer and cannot approve tokens, remove liquidity, mint a position, or submit a transaction.

This makes it useful for testing the idea behind an automated market-making agent before giving any separate system authority over funds.

What the manager checks

Each evaluation reads the position NFT from Uniswap’s official Base position-manager contract, resolves its pool, and records the current tick, configured range, fee tier, owner, token amounts, and observed Base block. For stablecoin-quoted pools it also estimates the position’s USD value.

The policy then classifies the position as:

• Hold — the price remains comfortably inside the range.
• Watch — the price is near or outside an edge, but a safety or economics gate has not cleared.
• Propose rebalance — a new virtual range is centered on the current tick because every configured gate cleared.

The explanation shown beside each decision includes the nearest-edge distance, estimated fees recovered during the evaluation window, gas and inventory-cost assumptions, expected net benefit, and any remaining cooldown.

Read the paper ledger

Each saved monitor also keeps a local paper portfolio. It marks the virtual LP range against the observed pool price, accrues fees from the configured fee-APR assumption only while that range is active, and deducts the configured gas plus inventory cost whenever the policy proposes a virtual rebalance. The ledger reports virtual principal, modeled fees, total value, normalized return, a same-start HODL baseline, excess return, cumulative costs, and the number of paper rebalances.

Paper returns are deliberately separate from the real NFT snapshot. Real principal and uncollected fees remain on-chain evidence; paper fees are scenario output. The ledger starts when the upgraded observer first evaluates a USD-priced position, so do not compare it with a control measured over a different starting window.

Learn from history faster

The research runner can replay many synchronized paper policies over cached Base history instead of waiting one day for each new observation. It derives gross fee opportunities from the pool’s real Uniswap v3 Swap events, tests a capital ladder, and compares fixed-width, recentering, and volatility-adaptive ranges against the same-start passive and HODL baselines.

For a quick first pass, the runner samples 1,000 blocks from each 10,000-block window and discloses the fee scaling in its report. Use full resolution to confirm a finalist:

pnpm liquidity-range:research -- \
  --experiment-root /path/to/read-only-canary \
  --days 30

pnpm liquidity-range:research -- \
  --experiment-root /path/to/read-only-canary \
  --days 30 \
  --full-resolution

Each run uses a chronological train/purge/holdout split and executes a paper decision one bar after it is made. It also repeats the baseline/treatment comparison across three non-overlapping walk-forward periods. The default capital ladder is $5, $50, $500, and $5,000, so fixed transaction costs can suppress a policy at tiny size without hiding whether the same policy has merit at a realistic notional. Results include HODL excess, passive spread, drawdown, time in range, turnover, regime returns, and a deterministic bootstrap adjusted for the number of policies tested.

The report separates two decisions: whether adaptive management beats passive LP, and whether the LP allocation itself beats holding the starting inventory. A policy can have a useful LP-management edge during a trend while LP still trails HODL; only a challenger that clears both gates can become a promotion proposal.

Historical winners are challengers, not production settings. The runner writes a versioned, review-only proposal with dataset and policy hashes. It never edits the saved monitor, reads a wallet credential, or applies a policy automatically. A sampled winner must survive full-resolution replay and human review before any paper-policy change, and live execution remains a separate authority decision.

Set up a shadow monitor

1. Open Trade, then choose Liquidity.
2. Copy the numeric NFT ID for a Base Uniswap v3 position into Position NFT ID.
3. Choose a target range, edge trigger, cooldown, evaluation window, fee APR assumption, gas estimate, inventory/impermanent-loss cost, and minimum net benefit.
4. Select Inspect position. Check the owner warning, live range, block evidence, and decision explanation.
5. Select Save shadow monitor, then start it or run one evaluation immediately.

Importing an NFT ID grants no permissions. You can inspect an NFT owned by another address, but HivemindOS labels the mismatch and makes no ownership claim.

Understand the assumptions

The live shadow manager does not predict fees or impermanent loss. Its fee APR, gas, and inventory-cost inputs are your explicit scenario assumptions. The historical research runner is different: it reconstructs a gross fee opportunity from real swap events, but sampled runs remain estimates and neither mode predicts future order flow. A proposed rebalance means its scenario cleared the configured threshold; it does not mean a real trade would be profitable.

If a USD position value cannot be estimated, the economics gate fails closed. The manager also enforces its cooldown and minimum-net-benefit threshold before changing the virtual range. An out-of-range Uniswap v3 position does not earn fees until price returns to its range, which is why range distance is shown prominently.

Run it in the background

The Trade desk can run one evaluation while it is open. For an always-on observer, install the optional user service from the repository:

./scripts/install-liquidity-range-manager.sh

The service heartbeat explicitly reports that it has no signing authority. To stop and remove only this managed service and its installed daemon bundle:

./scripts/install-liquidity-range-manager.sh uninstall

Saved policies and shadow history stay local after uninstall, so they can be reviewed or removed separately.

Safety boundary

• Base and Uniswap v3 only.
• Public, read-only contract calls only.
• No private-key lookup, wallet approval, transaction construction, signature, or submission path.
• A “rebalance” event changes only the locally stored virtual range.
• Paper fee accrual uses the configured APR assumption; it is not a claim about fees earned by the real NFT.
• Historical research is isolated from the observer, enforces a one-bar execution lag, and can emit only review-required policy proposals.
• Estimates are scenario outputs, not financial, accounting, legal, or tax advice.

For protocol details, see Uniswap’s documentation on concentrated liquidity and its current Base deployments.