Imported from GuardianAudits/AlongsideUniveralEVMDefender (AGENTS.md). Install upstream with npx skills add GuardianAudits/AlongsideUniveralEVMDefender. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

• src/ holds primary Solidity contracts, including the V4 hook (src/v4-hook) and supporting libraries.
• test/ mirrors the source layout with Foundry-based tests (e.g., test/V4-hook/UniversalJITHook.t.sol).
• External dependencies live under lib/, notably Uniswap v4 core/periphery, Hookmate artifacts, and helper tooling.

Build, Test, and Development Commands

• forge build: compiles all contracts using the Foundry toolchain.
• forge test: runs the full Solidity test suite; combine with flags such as --match-test test_PoC or --via-ir for targeted or IR-based runs.
• forge test --gas-report: produces a gas usage report, useful before submitting optimizations.
• sync.sh: fetches or updates tracked submodules/libraries to the expected revisions.

Coding Style & Naming Conventions

• Solidity files target pragma ^0.8.26 (or explicit 0.8.26 in Uniswap-derived modules).
• Use 4-space indentation and camelCase for functions/variables, PascalCase for contracts/libraries.
• Keep inline comments minimal and descriptive; prefer NatSpec for public/external functions.
• Respect remappings.txt when importing external packages (@uniswap/v4-core/…, hookmate/…).

Testing Guidelines

• Tests rely on Foundry’s forge framework; naming follows test_<ScenarioDescription>() conventions.
• Mirror contract hierarchy in test/ to keep fixtures and helper utilities close to their targets.
• When reproducing exploits or edge cases, log intermediate state with console2 and assert invariant protection.
• Always run focused tests (forge test --match-test <name>) and the affected suites before opening a PR.

Commit & Pull Request Guidelines

• Craft concise commit messages in the “verb + object” style (e.g., “Fix clamp logic for zero-for-one”).
• Each PR should describe the problem, the approach, and testing evidence (command output or gas report snippets).
• Link to relevant issues or specs when applicable, and mention any configuration changes that require operator action.
• Avoid bundling unrelated changes; keep rewrites to a minimum to simplify audits.

About the project

We are trying to build a JIT Uniswap hook that can provide two different bands of single sided liquidity depending on trade direction, if buying a uAsset, it will provide the amount of uAssets provided by the oracle, if buying USDC (Pair token) it will use whatever is available in merchant balance.

The problem comes in that, because there is an spread in between, the pool pricing can jump around freely as only one band of liquidity is provided at a time. However, if a user does a zeroForOne swap and moves the tick inside the range reported, and then follows a one for zero swap, he can do another zero for one swap and begin at the beginning of the range provided by the oracle.

This is why we introduced virtual pricing,