Skip to content

Roles And Custody

Production security depends on both smart-contract rules and key custody. The current source makes role assignments explicit, but it cannot force good off-chain signer operations.

Custody group Holds Purpose
RoleAdmin Safe roleAdmin only Root authority for role lifecycle and admin transfer.
Upgrade Operations Safe PROPOSER_ROLE, QUEUER_ROLE, EXECUTOR_ROLE Routine upgrade execution after release review.
Guardian/Canceller Safe CANCELLER_ROLE, optionally FREEZER_ROLE Independent emergency veto and beacon freeze authority.
Release/Registrar Safe REGISTRAR_ROLE Target registration and genesis implementation approval.
Operational/Risk Safe Controller owner, factory owner, deposit allowlistAdmin if approved by governance Day-to-day risk, receipt, reserve, vault, and admission operations.

Do not collapse review paths

If the same signer set holds role admin, registrar, upgrade operation, and guardian powers, the governance model has only one real control point.

RoleAdmin Responsibilities

The roleAdmin can:

  • propose role grants that become executable after minDelay;
  • execute matured grants;
  • cancel pending grants;
  • revoke roles immediately;
  • stage and cancel role-admin transfer;
  • accept transfer only from the pending admin address after its delay.

Because revocation is instant, roleAdmin is also an emergency-response tool. Because grants and admin transfer can reshape all other authorities, it is the highest-custody address.

Upgrade Operations Responsibilities

Upgrade roles must never sign from a UI summary alone. They must verify:

  • target type and target address;
  • expected target kind;
  • implementation address and code hash;
  • implementation metadata;
  • calldata and expected initialized version;
  • storage-layout compatibility;
  • evidence package location;
  • cancel path availability.

Guardian Responsibilities

The guardian path must be independent enough to cancel a malicious or mistaken operation even if upgrade operations is compromised. Guardian signers need real-time alerting for UpgradeProposed, UpgradeQueued, role changes, registrar events, and unexpected final-freeze attempts.

Registrar Responsibilities

The registrar controls which targets and genesis implementations become trusted by the governor. A bad registration can make later policy assertions misleading or impossible. Registrar changes require artifact review, runtime codehash checks, and target-kind verification.

Operational/Risk Responsibilities

Controller owner and related operational authorities affect claims, reserve coverage, receipt accounting, risk observations, exits, and settlement. These powers can impact funds even though they are not upgrade roles. They should be treated as production governance powers, not ordinary backend credentials.

Rotation And Compromise Response

On signer departure, suspected key compromise, device loss, or role reassignment:

  1. inventory current hasRole assignments and pending grants;
  2. cancel unnecessary pending grants;
  3. propose replacement grants;
  4. wait through minDelay;
  5. execute replacement grants;
  6. revoke old roles immediately after replacement is live;
  7. archive event logs and signer approvals.

Anti-Patterns

  • EOAs holding production roles;
  • one Safe holding every role;
  • hot-wallet signing for upgrade execution;
  • unclear ownership of allowlistAdmin, controller owner, or factory owner;
  • role grants without a ticket, reviewer, and expiration rationale;
  • signing calldata that has not been independently decoded.