# AGENTS.md

## OVERVIEW
System contract integration layer with canonical addresses, deployment transactions, and frame-init interception logic.

## STRUCTURE
- `oracle.rs`: oracle contract address, code constants, deployment helper.
- `keyless_deploy.rs`: keyless deploy address, code constants, deployment helper.
- `control.rs`: MegaAccessControl address, selectors, deployment helper, revert payload builders.
- `limit_control.rs`: MegaLimitControl address and deployment helper.
- `intercept.rs`: interceptor dispatch and synthetic frame-result handling.
- `tx.rs`: helpers for system/deposit-like transaction construction.

## KEY PATTERNS
- Deployment helpers are idempotent and keyed by code hash equality.
- Hardfork gating happens in each deployment helper.
- Interceptors return `None` to fall through to on-chain bytecode on unknown selectors.
- View/control interceptors reject non-zero transfer values with `NonZeroTransfer()`.
- Synthetic interceptor results bypass normal child-frame init and require empty tracking frame push by caller.
- Keep selector constants and ABI encode/decode paths aligned with `mega-system-contracts` interfaces.

## ANTI-PATTERNS
- Do not intercept unknown selectors with a synthetic revert unless spec requires it.
- Preserve on-chain-bytecode fallback for unknown calls.
- Do not accept value transfers for view/control interceptors unless explicitly specified and tested.
- Do not deploy system bytecode by raw literals in this crate.
- Reuse constants generated by `mega-system-contracts`.

## WHERE TO LOOK
- Add a new system contract deployment: new `<name>.rs` + hook call in `block/executor.rs::pre_execution_changes`.
- Add interceptor method behavior: `intercept.rs` for decode/dispatch and revert policy.
- Change access-control volatile disable semantics: `control.rs` + `intercept.rs` + `access/tracker.rs`.
- Change keyless deploy interception entrypoint: `intercept.rs` and `keyless_deploy.rs`.
- Update system contract address or code hash references: corresponding module constant definitions.
