Start with sensitive actions, not role names
Defining permissions for a Web3 product is not a matter of deciding that there will be an administrator and beginning to code. First, list the actions that can change the system's state or rules: creating or removing items, updating parameters, pausing a function, managing lists, moving operational funds or authorising a new version. Each action needs a business reason and an understandable boundary.
Ethereum explains that public or external functions can receive calls from accounts outside the project. Access control must prevent a sensitive action being available to every participant. Before choosing a library, prepare a table with one row per action. This work exposes decisions that an attractive interface can hide and lets the team discuss them while the scope can still change.
Build a matrix with six questions for each action
For every action, record who may initiate it, who may approve it, which conditions constrain it, how long execution takes, which event records it and what happens when the responsible account is unavailable. Not every column needs a complex mechanism. A low-impact operation may be immediate, while a change affecting the whole system may need proposal and execution to be separated.
The matrix should use product responsibilities rather than final wallet addresses. For example, operations lead is more stable than a particular address during design. Accounts, multisignature contracts or governance modules can be assigned later. This approach allows non-technical participants to validate the logic and preserves a clear link between each need and its eventual implementation.
- Action and observable effect.
- Initiator and approver.
- Limits, conditions or delay.
- Evidence emitted by the contract.
- Procedure for loss or compromise.
- Owner of the permission review.
Choose single ownership or separate roles for an explicit reason
OpenZeppelin documents Ownable as a simple model in which one account performs administrative tasks. It can fit when there genuinely is one responsibility and the scope is limited. When different people or systems need different capabilities, role-based control can separate, for example, an emergency pause from changing parameters or managing members.
Separating roles does not provide security by itself when every role is assigned to the same account or an administrator can recover them without control. Apply least privilege: each account receives only the actions it needs. Also document who grants and revokes every role. In AccessControl, each role has an administrator role; that relationship is part of the product and should not remain an invisible code detail.
Design transfer and loss of access before deployment
A misdirected transfer can leave control with the wrong account or one that cannot interact with the contract. OpenZeppelin provides Ownable2Step so the new owner must accept the transfer. The two-step concept illustrates a wider question: how is the destination checked before a critical capability is handed over, and who can stop the process when an error is noticed?
Recovery should not mean adding an unexplained, permanent master key. Define scenarios: a lost device, a team member leaving, an unavailable signer or a compromised account. Then decide whether the response is to replace a multisignature member, revoke a role, use a delay or execute a previously limited emergency procedure. If recovery does not exist, that irreversibility should be a conscious and visible decision.
Add delays only when something useful can happen during the wait
A delay can separate approval of an action from its execution. OpenZeppelin describes TimelockController as a mechanism that subjects selected maintenance operations to a waiting period before execution. That period may allow an operation to be reviewed or a response to be taken, but it achieves little if nobody monitors proposals or the product does not define what an affected person can do during the wait.
Decide which actions need a delay, who proposes them, who executes them and who can cancel them. Avoid applying one period to the whole system merely for convenience: changing auxiliary text and replacing a principal authority do not have the same impact. The matrix should explain the purpose of every wait and the consequences if proposers or executors become unavailable, because excessive rigidity can also block legitimate operations.
Make permissions visible in the interface and operations
A contract may enforce a rule correctly while still creating a confusing experience. Before requesting an administrative signature or transaction, the interface should explain the action, affected contract, authorising role and any delay. Do not present a signature as merely signing in when it actually grants a capability or confirms an operation with persistent effects.
Ethereum recommends emitting events for relevant actions and monitoring them off-chain. Define which events the team needs for grants, revocations, pauses and authority changes. Monitoring does not replace contract controls, but it helps identify unexpected use and reconstruct what happened. Assign who receives an alert and which decision they can make as well; collecting signals without a planned response provides little continuity.
Validate the matrix with scenarios before turning it into code
Test the table with a clearly labelled hypothetical example. Imagine a digital membership: operations can issue an approved membership and support can suspend its use temporarily, but neither function can replace the principal authority. A structural change needs a separate approval and a delay. Then simulate a lost account, a member leaving the project and an incorrect destination address being proposed.
The review should cover permitted actions and rejected ones. Ethereum notes that unit tests in isolation do not cover every risk; the design needs edge cases and properties that must remain true. The outcome of this stage is not a promise of absolute security or an audit. It is a clearer specification for estimating, implementing, testing and reviewing a Web3 service without postponing control decisions until the end.
- Does every sensitive action have an owner and a boundary?
- Is the party that grants each role identified and controlled?
- Is there a defined response to the loss of an account?
- Do delays allow a useful action during the waiting period?
- Does the interface explain an authorisation before requesting it?
Sources and documentation
- OpenZeppelin Contracts: Access Control ↗
- OpenZeppelin Contracts API: Access ↗
- Ethereum.org: Introduction to smart contracts ↗
- Ethereum.org: Smart contract security ↗
Content created with AI assistance. Check the sources, date and scope of each guide.