Production Readiness
A checklist and guide for deploying Matador policies to mainnet.
Deploying permission policies to production is a critical operation. A mistake could lock funds or leave a vulnerability open. This guide outlines the rigorous processes required for a safe deployment.
Deployment Lifecycle
1. Final Compilation
Perform a clean build of your policies. Do not use cached artifacts.
# Clean output
rm -rf ./out
# Compile
npx matador-policy-cli compile ./policies/mainnet/*.matador -d ./out2. Verification
Verify that the hexData in your output JSON matches the expectations.
- Instruction Audit: Review the
instructionsfield in the JSON artifact. Does the logic flow match your source code? - Checksum: Commit the
checksumandspecVersionto your deployment log.
3. Provisioning
Submit the transaction to grant the permission.
- Manual (Safe): Use a transaction builder app to call
grantPermissionwith the bytecode. - Automated (Script): Use a hardened script with a hardware wallet.
4. Live Test
Immediately after provisioning, execute a low-value "canary" transaction to verify the policy behaves as expected.
Policy Management
Updating Policies
Policies are immutable by design. To "update" a policy, you must:
- Grant the new policy (new
permissionId). - Revoke the old policy.
Atomic Updates
If your smart account supports batched transactions (like Safe or Kernel), bundle the revoke and grant calls into a single transaction to ensure zero downtime or security gaps.
Emergency Procedures
Define clear rollback procedures before deployment.
- Revoke Access: The owner key must be able to call
revokePermissioninstantly if a bug is found. - Bypass Mode: Consider having a "Break Glass" policy (e.g., a high-threshold MultiSig) that can bypass specific restrictions in an emergency.
Monitoring & Observability
You cannot debug what you cannot see. Ensure your infrastructure captures interpreter events.
Key Events
| Event | Logic | Action |
|---|---|---|
PermissionEnforced | Policy Passed | Log for audit trail. |
PermissionViolation | Policy Failed | Alert immediately. Investigate the opcode and subject. |
PermissionGranted | New Policy | Verify against changelog. |
PermissionRevoked | Policy Removed | Verify authorization. |
Health Checks
Protocols upgrade. Your policies might not.
- Periodic ABI Check: Automated scripts should verify that the
targetaddresses in your policies still point to the correct implementation contracts. - Selector Verification: Ensure function selectors haven't changed (rare, but possible with proxy upgrades).
Production Checklist
- Source Control: All deployed policies are committed to git with a version tag.
- Clean Build: Artifacts were generated from a clean CI pipeline, not a local dev machine.
- Audit: Logic has been reviewed by at least two engineers.
- Test Coverage: Foundry tests cover >95% of policy logic, including edge cases.
- Gas Analysis: The policy overhead is acceptable for the intended transaction frequency.
- Monitoring: Alerts are configured for
PermissionViolationevents. - Recovery: The account owner has access to keys capable of revoking permissions.