Sigma vault implementation and self-audit

Verdict and evidence

A useful claims-only vault prototype and TypeScript keeper are delivered, with all requested source paths, tests, a CREATE2 factory, and a threat model. Full acceptance is not established. Author-produced checks are not independent audit evidence. The local suite reported 20 tests passed, zero failed. Each ShareToken fuzz test and vault round-trip fuzz test ran 100,000 inputs; the Medusa actor repeats the vault round-trip test. These are input counts, not 100,000 arbitrary stateful sequences. The final clean offline rerun is documented in artifacts/local-tests.txt.

Reproduce with script/check.sh; Foundry and Node 24 must be available. Solidity sources and a Linux x86-64 Solidity 0.8.26 compiler are vendored as ordinary files. No runtime npm package is needed. lib/SOURCES.txt records retrieval heads and compiler checksum. Files remain untracked; no Git staging, commits, or protected paths were modified.

Attributable technical basis

Uniswap explains claim accounting in ERC-6909 concepts. The vault burns claims to settle debts and mints claims for credits, following PoolManager. Using take would transfer underlying currency, contrary to the claims-only constraint. Thus “take/burn” is interpreted as zero delta settlement with burn/mint.

PoolManager does not have a public getSlot0 ABI method. Solidity uses StateLibrary; TypeScript decodes the same extsload slot. Hook address bits follow Hooks.sol. These upstream pages support technical design choices; local files and logs support claims about this implementation. They do not independently certify this code.

Every constraint: implementation or deviation

Requirement	Local evidence and status
BaseHook, bound single pool	src/BaseHook.sol:8, src/SigmaRangeHook.sol:49. Minimal local BaseHook; single-use binding to a currency/fee/spacing fingerprint and this hook address. Fingerprint excludes hook address to avoid a CREATE2 constructor-address circular dependency.
ERC-6909 only	src/SigmaRangeHook.sol:96, :126, :131. No underlying token calls. Tests create claims externally using token transfers. Users authorize hook as PoolManager operator.
ERC-20 proportional shares	src/ShareToken.sol:4; src/SigmaRangeHook.sol:87, :89, :92, :104. Deposits buy proportional position liquidity and fee reserves; share mint/burn is atomic.
Required state and 6h cooldown	src/SigmaRangeHook.sol:30 through :37. Reserves also hold idle principal after rebalance. Cooldown is fixed, not configurable.
Public deposit/withdraw/rebalance	src/SigmaRangeHook.sol:64, :68, :72. Deposit uses exact liquidity, max claims and minimum shares; withdrawal uses shares and minimum outputs.
onlyKeeper rebalance	src/SigmaRangeHook.sol:73. Initial keeper established at construction.
owner setKeeper, 48h delay	src/SigmaRangeHook.sol:56. First call schedules; repeat same address after 48h activates. Different proposals restart delay.
pause/unpause	src/SigmaRangeHook.sol:61. Withdrawals remain available while paused.
Remove old / add new	src/SigmaRangeHook.sol:112 through :118. Reuses recovered principal plus reserves and retains leftovers. Insufficient two-sided assets can produce zero new liquidity; withdrawals still redeem reserves.
Rebalance bounds	src/SigmaRangeHook.sol:74 through :77. Order, global tick bounds, tick spacing, cooldown, and strict offsets below 2000. Offset is interpreted as distance of each endpoint from current tick.
O(1) afterSwap, writes only	src/SigmaRangeHook.sol:55. No-op: no storage reads/writes, external calls, observations or fee collection. “Writes only” is interpreted as forbidding other interactions, not requiring a write.
afterSwap never reverts	Literal deviation, src/SigmaRangeHook.sol:55: noDelegateCall rejects delegate calls; ABI decoder rejects malformed input. Valid ordinary callback calls have no application-level rejection.
All interactions through unlock	All state-changing manager operations use src/SigmaRangeHook.sol:80 / :81. Literal deviation, :75: pre-unlock slot0 read. View reads are exempted in this implementation.
Net deltas zero	src/SigmaRangeHook.sol:96, :127, :128, :131 use burn/mint. Real-manager integration tests enforce PoolManager's final delta settlement. No take, as explained above.
ReentrancyGuard	src/SigmaRangeHook.sol:40: local boolean guard on deposit/withdraw/rebalance, rather than an imported class named ReentrancyGuard.
Callback checks-effects-interactions	Capability consumed at src/SigmaRangeHook.sol:82; ownership updates precede position add/remove at :92, :104, :112. Qualified, :84: fee crystallization interacts before final ownership effects. Returned manager deltas determine reserve updates. Immutable trusted manager and spanning guard are assumptions.
noDelegateCall all external entries	Explicit mutating vault/share entry points are guarded. Literal deviation, src/SigmaRangeHook.sol:48: pure permissions and autogenerated public getters are unguarded. script/DeployHook.s.sol:10 factory is also unguarded.
Immutable, no proxy	src/BaseHook.sol:9, src/SigmaRangeHook.sol:42; no upgrade entry point. Manager/owner/share references immutable; keeper intentionally mutable.
Exactly two permissions	src/SigmaRangeHook.sol:48; constructor validates address bits at :46.
HookMiner CREATE2	script/DeployHook.s.sol:12. Factory-relative salt mining and predicted-address check. Mining within factory run may be expensive; offchain mining deployment remains an operational improvement.
Poll every 60 seconds	src/SigmaKeeper.ts:36, :39. Sleeps 60 seconds after completion; request duration adds polling drift.
30-day hourly log returns	src/SigmaKeeper.ts:21 through :23: 721 hourly prices for up to 720 returns. First observation each hour; skips missing hours rather than inventing returns. RPC uses sqrtPriceX96; test transports can approximate with tick.
Sample standard deviation	src/SigmaKeeper.ts:11 through :17, denominator n−1. Insufficient observations suppress rebalances.
tickOffset round(3σ10000)	src/SigmaKeeper.ts:25; expands resulting endpoints to tick spacing. Oversized ranges skipped, not silently capped.
Trigger conditions	src/SigmaKeeper.ts:30 through :34. Exit, maximum endpoint displacement above configurable threshold (default 100), or width change above 20%. Cooldown gates every trigger because contract mandates it. Delta-band meaning is an explicit interpretation.
Operational keeper	src/SigmaKeeper.ts:44: RPC adapter pins reads to one block and encodes rebalance. Gap: receipt-confirming signer injected; durable sample storage, chain/pool configuration checks and nonce management are not supplied. Restart loses history unless caller persists samples.

Invariants and limits of inference

Supply consistency follows atomic share mint/burn and is tested; tick order is checked at construction/rebalance and exposed as a Medusa property. These are local evidence and source reasoning, not formal proofs.

Literal hook token balance ≥ total user value is not true while liquidity is deployed. The position holds principal and uncollected fees separately from hook claim balances. test/fuzz/SigmaInvariants.sol checks reserve backing only. A complete NAV property must include position inventory and accrued fees currency by currency.

Literal no value destruction is not established. V4 adds round up and removes round down. Round-trip tests permit one claim of loss per currency. Arbitrary price changes, LP inventory shifts and economic losses cannot be ruled out by share accounting. Rebalance surplus stays in claims; no forced swaps dispose of inventory.

afterSwap gas trace reports 1,014 gas inside the callback. The test asserts a warmed call including caller overhead below 5,000. Calldata construction and transaction intrinsic costs are excluded. An earlier cold full-call assertion exceeded 5,000; no claim is made that every caller's total overhead meets the limit. Foundry sets isolate=false so internal calls are measured within a transaction. Check.sh provides a CI-runnable benchmark; no hosted CI workflow was created because .github is forbidden.

Verification and unanswered questions

Saved evidence: artifacts/local-tests.txt, artifacts/gas-trace.txt, artifacts/keeper-tests.txt. Tests cover real-manager initialization, claim-funded round trip, rebalance, pause, keeper delay, unexpected callbacks, transfer-rejecting tokens, malicious manager recursive deposit/missing callback, supply fuzz and vault round-trip fuzz. Keeper checks statistics, trigger, cooldown and missing hourly samples. There is no TypeScript type-checking campaign or live RPC/signing integration test.

Medusa 100k campaign not executed. test/fuzz/medusa.json is proposed configuration, not a verified campaign. Medusa and crytic-compile are not installed/vendored and thus cannot be assumed available offline. Medusa testLimit counts transactions according to its configuration documentation.

The rejected callback/unlock tests are not a complete nested-unlock exploit simulation. Reentrancy test checks rollback for a malicious manager returning without callback; it does not exhaust all reentry branches. Transfer-rejecting token tests demonstrate that vault claims operations do not invoke underlying transfers, not that upstream malicious token settlement is safe. Stateful swaps/fees/multiuser dilution, arbitrary rebalance sequences, full NAV conservation, keeper restart/signing and independent review remain unanswered. See docs/threat-model.md for trust assumptions and MEV risk. No production deployment, independent certification, or full-acceptance claim is made.

Clean offline verification: forge clean followed by forge test --offline --fuzz-runs 100000 reported 20 passed, zero failed. Compiler and source resolution succeeded with no network dependency. The report was restored after clean removed its output directory.