Evaluation Flow
This page explains the end-to-end flow when a transaction is evaluated against a PolicyKit policy.Overview
When a smart account attempts to execute a transaction, PolicyKit intercepts it through a guard or module and evaluates it against the registered policy. The evaluation follows a strict order and fails fast — if any rule rejects the transaction, evaluation stops immediately.Step-by-Step Flow
1. Transaction Interception
The transaction is intercepted by one of:PolicyGuard— A guard contract attached to the smart accountPolicyKit7579Module— An ERC-7579 validation module
2. Policy Lookup
ThePolicyEngine looks up the active policy set for the sender account:
3. Tier 1 Evaluation (Stateless On-Chain)
Stateless rules are evaluated first because they are the cheapest:PolicyEngine. If any rule returns false, the transaction is rejected.
4. Tier 2 Evaluation (Stateful On-Chain)
Stateful rules are evaluated next. These read and write on-chain state:Tier 2 rules update state even during evaluation. If a later rule fails, the state changes are reverted along with the transaction.
5. Attestation Check
If the policy has off-chain rules (Tier 3), thePolicyEngine checks for a valid attestation:
- The transaction submitter must provide an EIP-712 signed attestation from the policy’s PKP
- The
AttestationVerifiercontract verifies:- The signature is valid
- The signer matches the registered PKP address
- The signed data matches the current transaction parameters
- The attestation hasn’t expired
closed, the transaction is rejected. If the fail mode is open, Tier 3 rules are skipped.
6. Tier 3 Evaluation (Off-Chain via Lit Protocol)
Tier 3 evaluation happens before the transaction is submitted to the smart account. The flow is:6a. Request Lit Action Execution
The SDK calls the Lit Protocol network to execute thepolicyEvaluator action:
6b. Lit Action Fetches Policy
The Lit Action runs on the Lit network nodes and:- Fetches the full policy JSON from IPFS using the policy CID
- Parses and validates the policy structure
6c. Evaluate Off-Chain Rules
Each Tier 3 rule is evaluated:6d. Sign Attestation
If all Tier 3 rules pass, the Lit network threshold-signs an EIP-712PolicyApproval:
6e. Return Attestation
The signed attestation is returned to the SDK, which includes it with the transaction submission.7. Final Decision
Error Handling
Lit Protocol Unavailable
If the Lit Protocol network is unreachable:- Closed fail mode: Transaction is blocked. This is the safe default for high-value operations.
- Open fail mode: Transaction proceeds with only on-chain rule evaluation.
IPFS Unavailable
If IPFS is unreachable during Lit Action execution:- The Lit Action fails to fetch the policy
- No attestation is produced
- Behavior follows the fail mode setting
Attestation Expired
Attestations have a deadline (typically 5 minutes). If the attestation expires before the transaction is submitted, it is rejected. The SDK must request a new attestation.Performance Characteristics
| Phase | Latency | Cost |
|---|---|---|
| Tier 1 evaluation | ~0ms (same tx) | ~5,000-20,000 gas |
| Tier 2 evaluation | ~0ms (same tx) | ~20,000-50,000 gas |
| Lit Action execution | ~1-3 seconds | Off-chain (no gas) |
| Attestation verification | ~0ms (same tx) | ~30,000-50,000 gas |

