feat: total-allocation parameter for the WETH/cbBTC LP balancer + backend handbook

[anajuliabit]

Makes the total allocation a configurable, onchain-validated parameter of the WETH/cbBTC setup proposal, and adds the backend handbook for operating the position.

Based on audit-remediations, not main: src/LPAutoBalancerV2.sol does not exist on main at all, and this calls LPValuationLib.principalValue alongside setMaxOracleDelays / setSequencerUptimeFeed, all of which arrived with the audit work.

Supersedes #82, which GitHub auto-closed when this branch was renamed off feat/lp-v2-cbeth-bootstrap. Same commits, same diff.

History note. This branch first built the parameter as a separate proposal 014 against a cbETH/WETH pool. The bootstrap pool is WETH/cbBTC — which 011 already sets up and which has not executed — so 014 would have duplicated 011 in everything except the parameter. 014 and the cbETH venue are removed in 030c351; review the branch as a whole, not commit by commit.

What's here

File	What
multisig/mamo-multisig/011_LPAutoBalancerV2Setup.sol	The allocation parameter + validateAllocation()
test/LPAutoBalancerV2Setup.integration.t.sol	Geometry-sized mint + the non-vacuity control — make lp-v2-setup
docs/LP_AUTO_BALANCER_V2_BACKEND_HANDBOOK.md	New: backend handbook for WETH/cbBTC
docs/LP_AUTO_BALANCER_V2.md	Doc-map entry

The parameter

totalAllocationUsd (8-dec USD, default $50k), set per run via setTotalAllocation(target, toleranceBps). validate() asserts the registered principal lands inside the band, priced with the balancer's own feeds, staleness bounds and sequencer guard at the pool's live sqrtPriceX96 — not an independent estimate that could agree by luck. Leg decimals are asymmetric on this pair (WETH 18dp, cbBTC 8dp) and the valuation carries both.

It validates the size rather than minting it because FPS records build()'s actions as calldata and replays them at Safe-execution time. A mint inside build() returns a tokenId observed during simulation, but the Slipstream NFPM tokenId is a global counter that anyone's mint advances in between — the encoded registerPosition(tokenId) would name someone else's NFT.

Reviewer attention

The mint must be sized from the range geometry, not 50/50 by value. A 50/50 split is only correct when spot sits at the range's centre; at tickSpacing 100 the aligned centre can be up to 99 ticks away, at which point the legs bind ~25/75 and the NFPM refunds about a third of the intended size. The first version of this test failed for exactly that reason, ~33% under target. The helper now prices one reference unit of liquidity across the actual [tl, tu] at live sqrtPriceX96 and scales to the target, so both legs bind together. Recipe is in handbook §2.1 — worth checking, since anyone doing the production mint follows it.

test_validate_rejectsWrongAllocation is the non-vacuity control. Same position, same tolerance, 2x and 0.5x targets, both must revert. Without it a band that accepts everything reads identically to a working one.

R7 is live at minWidth on this venue, and the mitigation is the backend's. minWidth is exactly 2 * tickSpacing, where the balanced and token1-single-sided tick pairs collide — so a spot push inside the calm gate can turn a committed two-sided mint into a single-sided one with a zeroed mint minimum, and the tick commitment cannot detect it (it pins the pair, not the branch). 011 deliberately did not close this at config level. The handbook therefore mandates width >= 4 * tickSpacing = 400 per cycle, asserted in preflight and watched in monitoring. Flagging it because it is a config-level residual discharged by an offchain rule, which is exactly the kind of thing that gets lost.

Handbook

Operating-side companion to the existing setup runbook (which stays the Safe-side deployment doc). Venue facts, allocation sizing, venue mechanics, process shape lifted from mamo-rebalancer, preflight cast commands, failure playbook, env, go-live.

Deliberately no yield or APR projections — those are the backend's, computed from live state per cycle. An earlier draft carried them and the stake-vs-unstake conclusion inverted within a day of being written, which is the argument for keeping mechanics and dropping numbers.

Feed heartbeats measured, not assumed — a slow feed under the armed 3600s bound would brick every priced path. ETH/USD max consecutive gap 1234s over 30.6h; BTC/USD 1232s over 52.0h; each tolerates >= 2 missed rounds. The documented recipe warns about the two traps that produce false over-limit readings: latestRound() on the proxy is phase-encoded and overflows shell arithmetic, and at high xargs -P some calls return empty so gaps get computed across non-adjacent rounds. A first pass at -P 20 reported a 3662s ETH/USD gap that did not exist.

Deployed to Base mainnet

Two deployments of the same bytecode, differing only in who holds the roles. Both verified on Etherscan v2 (chainid 8453).

Test pair — EOA admin (7412b72)

What we actually wanted. Use this one for the test position.

Contract	Address
MAMO_LP_AUTO_BALANCER_V2_TEST	0x9f548228A41d18e2DC736ceF048cfBeC8fFC55E6
MAMO_LP_COMPOUND_MODULE_TEST	0x7B3690d05eDB4305a7F66d52b4BBe9f89F503eF3

admin = guardian = 0xd4669fCee3BE73b51438ad1f1debEB3505Eab308, manager = rebalancer = address(0) — the admin grants REBALANCER_ROLE when it's needed. Verified on chain: the Safe holds no role here, and REBALANCER_ROLE is unset.

Deployed by script/DeployLPAutoBalancerV2Test.s.sol, which is deliberately not a parameterisation of DeployLPAutoBalancerV2. That script hardcodes F-MAMO and registers under MAMO_LP_AUTO_BALANCER_V2 — the exact key 011.deploy() tests for idempotency — so a test address landing there would make the Safe proposal skip deployment and wire itself to an EOA-admin contract. Roles come from LP_TEST_ADMIN / _GUARDIAN / _MANAGER / _REBALANCER.

An EOA admin holds exit(), setPool, setOracles and recoverERC20. Fine for a test position, not for real funds.

Production pair — F-MAMO admin (dbdb5bd)

This one is correctly configured for production and is what 011 resolves through; it simply landed earlier than intended.

Contract	Address	Runtime
MAMO_LP_AUTO_BALANCER_V2	0x9CDBe7DB9F967E793E7261e0ffd546E5D29b476f	24,486 B
MAMO_LP_COMPOUND_MODULE	0x699318E0641518eF39418a8D86F93BF8b0715c88	7,588 B
LPGeometryLib	0x54823d912575bAF4831a0E7a3173321429209a49	3,642 B
LPPositionLib	0xC8fB25B6769ea283e6aeF5896A0CD70e9BAd5cE6	6,713 B
LPValuationLib	0x8A30d89B720F61c0fF8F1f3558CBFd4e5cCc6368	4,911 B

Deployer 0xDca82E03057329f53Ed4173429D46B0511E46Fb8. Runtime sizes match the local build — the balancer is 90 bytes under EIP-170.

State read back from chain rather than assumed:

• admin and guardian are both F-MAMO
• REBALANCER_ROLE is not granted (0xd4669fCe… → false)
• sequencerUptimeFeed is address(0) — the L2 guard is off
• maxOracleDelay0/1 carry the constructor default (3600), not a proposal-armed value
• the module is bound to the balancer, module admin is F-MAMO

The balancer is inert. 011 arms the guards, transfers and registers the position, and grants the rebalancer. Until the Safe executes it there is no position and nothing to protect — registerPosition is admin-only, so nothing can be registered outside the proposal.

MAMO_LP_REBALANCER (0xd4669fCee3BE73b51438ad1f1debEB3505Eab308) is registered in the address book so 011's _resolveRebalancer() fallback grants the role to it. /broadcast is gitignored, so only the address book is committed.

Running 011 from the CLI

forge script cannot call setTokenId / setTotalAllocation — those setters exist for the fork test, which builds the proposal in-process. A mainnet --broadcast therefore reached build() with tokenId == 0 and reverted "tokenId not set", making the proposal un-runnable as written. run() now reads INIT_TOKEN_ID (required), TOTAL_ALLOCATION_USD and ALLOCATION_TOLERANCE_BPS from the environment; setters still win, so the fork test is untouched. Pinned by test_runLoadsInputsFromEnv, mutation-verified.

Tenderly vnet run (pre-deployment)

Deployed and driven end to end on a Base-fork vnet, both scenarios green (script/tenderly/lpv2-vnet.json):

Measurement	Value
liquidity across reset()	179715587681210 → 179715587681209 (1 wei)
WETH dust to feeCollector	11127 wei
cbBTC dust to feeCollector	0
cooldown blocks 2nd reset()	yes
role gating blocks reset/exit/stake	yes
exit() returned to Safe	1999999999999982368 WETH, slot inactive

Getting there needed three harness fixes, all in this branch:

• Chain id was pinned to 8453 in four places. A Tenderly vnet may carry any chain id and the dashboard defaults a Base fork to 9998453. chain_sanity asserted equality; forge's broadcast directory is named after the live id so three orchestrator paths were wrong; and FPS's single-arg getAddress(name) resolves against block.chainid (Addresses.sol:110), so the harness went looking for addresses/9998453.json. Now: the id is read into $VNET_CHAIN_ID, artifact paths derive from it, and ensure_address_book materializes a copy of the book for the run and deletes it on exit. EXPECTED_CHAIN opts back into a hard assertion.
• Three entrypoints never called _resolve() — each forge --sig run is a fresh process, so POOL was address(0) and the phase died on slot0().
• A pending vm.prank was being eaten by an argument-position call at four sites: abi.encodeCall(lab.rebalanceUsingAlt, (_resetParams())) evaluates _resetParams() first, and its slot0() staticcall consumed the prank, so the call under test ran as the script. Verified with a throwaway probe rather than assumed. checkRoleGating had been passing for the wrong reason; doReset's cooldown check and the calm-gate/stale-oracle checks would have failed outright.

Both latent bugs were dormant until the audit remediation appended expectedTickLower/Upper to RebalanceParams — that made _resetParams() read the pool for the first time.

No vnet address goes into addresses/8453.json. They have no code on Base mainnet (verified) and a fresh vnet reassigns them; more importantly 011 gates its deploy on !addresses.isAddressSet("MAMO_LP_AUTO_BALANCER_V2"), so registering one would make the production Safe run skip deployment and wire itself to a nonexistent contract. The manifest also omits the vnet RPC URL, which is effectively a bearer credential for the cheat RPCs.

Verification

• make lp-v2-setup 5/5, lp-auto-balancer-v2 9/9, make test-unit 486/486.
• make test aborts with Missing operator fee scalar for isthmus L1 Block. Pre-existing — it comes from the self-forking suites that predate this branch (LPAutoBalancerV2SetupTest, LPAutoBalancerV2Integration, DeployLPAutoBalancerV2Test, ERC20StrategyV2Test) colliding with --fork-url; excluding those four makes it pass. Unchanged by this PR.
• forge fmt was not run. Local forge is 1.7.1; CI pins nightly e520767, and they wrap tuple destructuring and long-string returns oppositely. Run foundryup -i nightly-e52076714ace23c7a68e14f0048a40be3c6c8f0b && forge fmt before merge if you want it canonical.

🤖 Generated with Claude Code

[anajuliabit]

Comment, not blocking. The allocation parameter does what it claims: validate size, don't mint in build(). Geometry sizing + the 2×/0.5× non-vacuity test are the real meat. CI is still empty on this head (unstable / no statuses), so I wouldn't merge on that yet.

What holds up

validateAllocation() prices principal with LPValuationLib.principalValue at live sqrtPriceX96, 18/8 decimals, and the proposal's own delay + sequencer config. Zero target is rejected. test_validate_rejectsWrongAllocation actually moves the target, not the position.

_mintAllocationTo sizes off amountsForLiquidityAtTicks then scales (plus 50 bps headroom). Range is center ± 200 (width 400), which matches the handbook's R7 operating width. Rebalance params in the lifecycle test also use 400.

Nits

• setTotalAllocation allows 10_000 bps. Then lo is 0, so the under-allocation assert is ≥ 0 and always passes. Cap below 10000 (or reject 10000) the same way you reject a zero target.
• setUp still says the mint uses the "50/50-by-value recipe". The helper does geometry now. That comment will bite the next person.
• validateAllocation reads feeds/pool/NFPM from the address book, not lab.position(). Fine if validatePosition already pins those to the balancer; if it doesn't, this can agree with a book that isn't what got registered.
• R7 is still a backend rule (minWidth stays 200). Honest in the handbook; it is not closed onchain. Treat the width PAGE as load-bearing, not documentation flavor.
• Test mint still uses amount0Min/amount1Min = 0. Fine for the fork; don't copy that for the Safe mint.

Did not re-run make lp-v2-setup.