# Global Session Policy Module (GSPM)

**What this is:** An ERC-6900–style validation & execution hook designed for **Modular4337Account**.\
It follows the ERC-6900 hook pattern (install/uninstall + pre/post hooks) **using project-local interfaces** (`IValidationHookModule`, `IExecutionHookModule`) and enforces:

* Per-account **session agent** binding (authorised UserOp signer)
* Policy firewall for **vault PositionManager** flows, **ERC-20 approvals**, and **0x** routes
* **Recipient pinning** (vault/0x proceeds → account or owner)
* Global allow-lists for **agents** and **tokens**
* Rolling-window **slippage budgets** (liquidity, swaps) and **pool↔oracle deviation** budget
* **Tick-ratio** sanity checks with **single-sided** liquidity allowances

> **Compatibility note:** This module is **not a drop-in ERC-6900 reference interface**.\
> It is designed for accounts that call these hooks exactly as Modular4337Account does.\
> If a different ERC-6900 account expects the canonical interfaces/selectors or invokes hooks outside EntryPoint execution, you’ll need a thin adapter (or to align interfaces) and possibly relax the `sender == entryPoint` guard.

### Hook behaviour (summary)

* `preUserOpValidationHook` — verifies UserOp signature against the account’s **agent**.
* `preRuntimeValidationHook` — **EntryPoint-only**, forbids ETH value, blocks self-target, checks agent allow-list.
* `preExecutionHook` — enforces:
  * **Vault PM** (`collect/decrease/burn/mint/increase`): recipient checks; per-tx slippage bound (`maxSlippageCheck`); user **tick-ratio** deviation ≤ `allowedTicRatioDeviationBps`; pool↔oracle **skew** charged to deviation budget.
  * **ERC20 `approve`**: token must be `isTokenValid` Spender is a registered **vault** or **0x allowance holder**.
  * **0x AllowanceHolder → Aggregator Settler**: inner target/selector **pinned**; src/dst tokens valid; recipient pinned; **oracle-based min-out** enforced; loss charged to **swap budget**.
* `postExecutionHook` — measures realised slippage for vault mint/increase and charges the per-(account, vault) budget; can revert with `HighValueLoss()` on window cap breach.

### Budgets & tuning

* Globals (owner-settable):\
  `slippageBudgetBps`, `swapSlippageBudgetBps`, `deviationSlippageBudgetBps`,\
  `allowedTicRatioDeviationBps`, `maxSlippageCheck`, `slipWindow` (1h default).
* Per-account overrides: `updateSlippageThrottle(...)` (+ `keepSlipState`).

### Security considerations

* Hooks are **no-ops outside EntryPoint** by design (`sender == entryPoint` guard); portability may require adjusting this.
* Oracle freshness/liveness directly impacts slippage/deviation checks.
* Expanding token/agent allow-lists or relaxing budgets increases the attack surface.

### Admin / Owner API

All functions below are **`onlyOwner`**:

* `bulkUpdateAgents(address[] agents, bool allowed)`\
  Add/remove **agents** from the global allow-list (reverts on zero address). Controls who may be bound as a session agent.
* `bulkUpdateValidTokens(address[] tokens, bool valid)`\
  Add/remove **ERC-20 tokens** from the global valid-token list used by approvals and 0x flows.
* `setMaxSlippageCheck(uint256 _maxSlippageCheck)`\
  Sets per-transaction min-out threshold in **basis points** (0 < value ≤ `PERCENTAGE_FACTOR`).\
  Used in vault `mint/increase` and 0x min-out comparisons.
* `setSlippageBudgetBps(uint32 _slippageBudgetBps)`\
  Sets the **liquidity** cumulative slippage budget per window (must be > 0).
* `setSwapSlippageBudgetBps(uint32 _swapSlippageBudgetBps)`\
  Sets the **swap** cumulative slippage budget per window for 0x flows (must be > 0).
* `setDeviationSlippageBudgetBps(uint32 _deviationSlippageBudgetBps)`\
  Sets the cumulative **pool↔oracle deviation** budget per window (must be > 0).
* `setAllowedTicRatioDeviationBps(uint32 _allowedTicRatioDeviationBps)`\
  Max tolerated **user tick-ratio** deviation from expected (0 < value ≤ `PERCENTAGE_FACTOR`).
* `setPriceOracle(address _priceOracle)`\
  Updates the **oracle** used for USD valuations and skew checks (non-zero address).

> ⚠️ Note: GSPM is explicitly designed for permissioned agent flows. If a session key is invalid or missing, the operation fails (no fallback to the owner signature path).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.alloc8.xyz/architechure/readme/global-session-policy-module-gspm.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.