Policy engine

Documentation Index

Fetch the complete documentation index at: https://docs.usecompassai.com/llms.txt

Use this file to discover all available pages before exploring further.

The policy engine is the gate every plan passes through. Rules are stored on-chain on the user’s smart account; checks run twice — once in the off-chain loop as an optimization, and once on-chain at the contract level as the actual guarantee.

​

What “policy” means in Compass

​

Two layers of enforcement

1. Off-chain, in the deterministic loop. As step 4 of an EvaluatorThought. This is an optimization — it stops out-of-policy plans before they consume gas and lets the dashboard show users why something was rejected.
2. On-chain, in the smart account. The session key facet validates every call against the policy stored on the same account. Any call that violates a rule reverts before USDC moves.

​

The check sequence

1. Chain whitelist. Is every chain in the plan (source and target) in chain_whitelist?
2. Protocol whitelist. Is the (protocol, target_chain) pair in protocol_whitelist?
3. Risk band. Is the target protocol’s assigned risk score ≤ risk_band?
4. Per-route cap. Is the route amount ≤ per_route_cap_usdc?
5. Daily cap. Would executing this route push today’s total above daily_cap_usdc?

​

What a rejection looks like

{
  "rule": "protocol_whitelist",
  "reason": "(protocol, chain) pair not in whitelist",
  "candidate": {
    "source_chain": "arc_testnet",
    "target_chain": "<l2_chain>",
    "target_protocol": "<lending_protocol>",
    "amount_usdc": "5000000"
  },
  "policy_snapshot_hash": "0x7f3a..."
}

• rule is the failed rule name, not a free-text reason. This lets the UI and audit tooling categorize failures without parsing strings.
• policy_snapshot_hash lets a reader verify which version of the policy was in force when the check ran. Policy changes are on-chain transactions; rejections can be tied back to the exact policy state.
• The full candidate is preserved, so the rejection can be replayed against a different policy (e.g. “would this plan have passed if my risk band were 7?”).

​

What happens when a plan is rejected

• No transaction is broadcast. USDC does not move. No gas is spent.
• The EvaluatorThought is still written. This includes the PolicyRejection plus the full state snapshot from steps 1–3. See Audit trail.
• The scheduler does not immediately retry the same plan. Re-running the evaluator on the same inputs produces the same rejection. The scheduler waits for a relevant state change before re-evaluating.
• The user can see the rejection. Both the chat panel (if the plan came from chat) and the dashboard surface the failed rule name.

​

Policy updates and in-flight plans

• A policy update is a normal on-chain transaction. It commits a new policy state with a new snapshot hash.
• In-flight plans are re-checked against the current policy before signing. A plan generated under the old policy can be rejected by the new one. This is intentional — if a user tightens their rules, the next tick respects the new rules immediately.
• In-flight Gateway intents are not rolled back. If USDC is mid-flight between chains and the user tightens their chain whitelist mid-route, the intent still settles (it has already been signed). The new policy applies to the next tick.

​

Why a separate engine

• Reasoning over candidates without signing them. The off-chain engine can evaluate hundreds of candidate plans per tick (different venues, different amounts) and pick the best one before signing anything. Pushing every candidate to the chain for a revert-or-pass check would be gas-prohibitive.
• Structured failure information. A reverted transaction tells you that something failed, not why. The off-chain engine produces typed rejections that the audit trail and UI can act on.

​

Next steps