Smart Contract Access Control

AI-assisted manuscript. Roles and actions below are educational; no production keys are used.

Learning objectives

• Map privileged actions to the actors authorized to perform them.
• Distinguish operating a role from administering membership.
• Design revocation and emergency actions without a hidden bypass.

Privilege is a financial dependency

A smart contract can restrict functions, but the administrator of those restrictions may control who can mint, pause, recover or upgrade. The relevant question is not simply whether a function has a role check. It is who can acquire that role, alter its administrator or replace the implementation.

OpenZeppelin Contracts 5.x documents role-based access control in which a role's administrator controls granting and revoking it. Holding an operational role does not automatically grant membership-management power. The default administrator is highly privileged because it administers roles and itself by default. The documentation also describes additional default-admin rules and timelock patterns with their own assumptions. OpenZeppelin: Access Control

A timelock creates delay and an opportunity to observe a proposed action. It does not make a malicious action benign. Loss of necessary proposer or executor capabilities can also lock a system. Treat authority, delay and recovery as distinct design dimensions.

Worked example: the minter who can appoint another minter

Imagine a teaching token with operations role MINT and administrator role ADMIN. An authorized operator may mint up to an approved subscription's units. Under the intended rule, only ADMIN may grant MINT. A mistaken implementation lets MINT grant MINT to any address.

The ordinary mint test passes: an authorized minter creates 100 units. The missing forbidden test is a minter attempting to appoint an accomplice. If that succeeds, the business authorization boundary has widened. Fixing the visible mint button cannot repair the membership writer; the membership owner must enforce its own rule.

Now consider a compromised operator. Revoking MINT should remove future authority, but previously submitted or scheduled operations need explicit treatment. For a proposed 48-hour upgrade delay in this fictional model, identify who schedules, who executes, who cancels and what happens if one role is lost. The 48 hours is a teaching assumption, not a recommended universal delay.

Subscription reviewer → approves business amount
Minter → executes only authorized issuance
Role administrator → grants/revokes minter
Upgrade administrator → changes implementation under separate controls
Emergency authority → bounded pause + documented recovery

A diagram with separate boxes does not prove separate keys or independent people. Verify actual role memberships and shared control.

Specify both authority and limits

Create an action matrix covering mint, burn, freeze, recovery, policy change, role grant, role revoke and upgrade. For each action, record the intended actor, prerequisite evidence, allowed effect, audit record and recovery procedure. An event naming an actor is evidence of an operation; it is not proof that the actor had proper business approval.

Tests need normal, unauthorized, revoked and boundary cases. A pause should block the paths it promises to block without accidentally granting new powers. A recovery function should not silently bypass eligibility, accounting or legal authorization. Shared rules belong at the relevant owner, with every writer identified.

Operational key management matters too. A correct role model can still fail if keys are copied, a signer is unavailable or administrators share one compromised dependency. This chapter does not prescribe a custody product; it identifies evidence needed to assess the chosen arrangement.

Common misconceptions

“Only authorized users can mint, so governance is safe.” Role assignment and upgrades can change who is authorized.

“Timelock means approved.” Delay is not consent or legal authority.

“An emergency function should bypass everything.” Unbounded recovery can become the largest attack surface.

Risks and limits

The cited library documentation is version-specific technical guidance, directly read on 2026-10-18. This lesson does not audit a deployed contract or establish real signer independence. Governance mistakes, compromised keys and unavailable recovery actors require their own evidence and rehearsal.

Exercise and answer

Exercise: A MINT operator cannot call an upgrade function, but can grant ADMIN to itself through a membership bug. Is the upgrade boundary intact?

Answer: No. Reachable authority matters. The role-management path enables escalation to the upgrade administrator and must enforce its own intended boundary.

Related learning

Continue in engineering with external data and security review. Use Build to inspect educational models before considering any deployment.

Source map

openzeppelin-access-control: OpenZeppelin Contracts 5.x official technical documentation, retrieved 2026-10-18. Role names, 100-unit example and 48-hour delay are original teaching assumptions. No real contract, key custody setup or governance action was tested.