Policy schema

Representative document

Addresses and limits are illustrative, not deployments or recommended production values. Integers that can exceed 2⁵³ are decimal strings. Floats are rejected.

{
  "schema_version": "1.0",
  "policy_id": "policy_trading_001",
  "version": 7,
  "account": {
    "chain_id": 4663,
    "address": "0x1111111111111111111111111111111111111111"
  },
  "status": "active",
  "limits": {
    "max_transaction_value_wei": "100000000000000000",
    "max_gas_cost_wei": "5000000000000000",
    "hourly_budget_usd_micros": "500000000",
    "max_pending_operations": 3,
    "max_price_age_seconds": 60
  },
  "cooldowns": {
    "identical_calldata_seconds": 60,
    "identical_intent_seconds": 15
  },
  "contracts": {
    "default": "deny",
    "allowlist": [
      {
        "address": "0x2222222222222222222222222222222222222222",
        "selectors": [
          "0xa9059cbb"
        ],
        "require_verified_code": true
      },
      {
        "address": "0x3333333333333333333333333333333333333333",
        "selectors": [
          "0x38ed1739"
        ],
        "require_verified_code": true
      }
    ],
    "denylist": [
      "0x5555555555555555555555555555555555555555"
    ]
  },
  "human_approval": {
    "usd_threshold_micros": "150000000",
    "require_for_unknown_methods": true
  },
  "failure_mode": "closed"
}

The full JSON Schema is in packages/policy-schema/policy.schema.json. Unknown fields are rejected so that a typo can never silently disable a rule.

Field reference

Units

• Native value and fees are integer wei.
• USD amounts are integer micros (1 USD = 1,000,000). Conversion rounds up, so limits are never under-counted.
• USD enforcement needs a fresh price. A missing price, or one older than max_price_age_seconds, fails closed with RW_STATE_001.
• Exposure is native value plus estimated fee. Token-denominated allocations are specified but not yet in schema 1.0.

Precedence

1. An active global emergency stop denies all new protected executions.
2. An explicit deny overrides any allow.
3. A required human approval cannot be overridden by an ordinary allow rule.
4. A missing or invalid policy is never treated as an empty, allow-all policy.
5. An unknown method is denied or routed to review, according to require_for_unknown_methods.
6. An unavailable or unbounded fee estimate is never treated as zero.
7. Activating a new policy version invalidates pending approvals bound to the previous one.

Evaluation order

Checks run in this fixed order and stop at the first failure. The SDK never decides which checks are authoritative. Read-only checks may be reordered for performance; budget reservation and replay protection stay atomic.

After a local ALLOW, the production path also simulates execution, binds the authorization to the operation hash, chain, policy version and expiry, signs inside the enclave, and submits to the bundler. None of these run in the simulator.

Budgets and reservations

Every allowed or pending operation creates a reservation with a unique ID, amount, policy version, expiry and lifecycle state: reserved, pending_approval, released or finalized. The hourly budget counts every non-released reservation created in the trailing 3,600 seconds.

Version migration

schema_version names the document format; version numbers each activated policy. They move independently.

• Policy versions. Every activation creates a new integer version. The previous version is kept and can be loaded back into a draft; nothing is edited in place. Pending approvals evaluated under an older version are invalidated on activation.
• Schema versions. A schema change ships with a new schema_version. Unknown fields are rejected, so a document written for a newer schema fails validation on an older evaluator instead of being half-applied.
• Migrating a document. Convert the old document, validate it against the new schema, run your test transactions against it as a draft, compare the decisions with the active version, then activate it explicitly.

Schema 1.0 is the first version, so no migrations exist yet. Each future schema version will list its changes and a conversion table in the changelog.

Validation errors

Validation returns a list of { path, message } pairs using JSONPath-style paths, for example $.limits.max_transaction_value_wei: must be a non-negative integer string. A policy with any validation error cannot be activated. Try it: edit a limit in the workbench to an invalid value.