# 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](https://developers.uniswap.org/docs/protocols/v4/concepts/erc-6909). The vault burns claims to settle debts and mints claims for credits, following [PoolManager](https://github.com/Uniswap/v4-core/blob/main/src/PoolManager.sol). 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](https://github.com/Uniswap/v4-core/blob/main/src/libraries/StateLibrary.sol); TypeScript decodes the same `extsload` slot. Hook address bits follow [Hooks.sol](https://github.com/Uniswap/v4-core/blob/main/src/libraries/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](https://secure-contracts.com/program-analysis/medusa/docs/src/project_configuration/overview.html). 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.