HomeForumWebsiteImpact
GitHub Icon
API Reference

AccessControl API

AnthropicOpen in Claude

This page provides the full AccessControl module API.

Roles are referred to by their Bytes<32> identifier. These should be exposed in the top-level contract and be unique. The best way to achieve this is by using export sealed ledger hash digests that are initialized in the top-level contract:

import CompactStandardLibrary;
import "./node_modules/@openzeppelin/compact-contracts/access/AccessControl"
  prefix AccessControl_;

export sealed ledger MY_ROLE: Bytes<32>;

constructor() {
  MY_ROLE = persistentHash<Bytes<32>>(pad(32, "MY_ROLE"));
}

To restrict access to a circuit, use assertOnlyRole:

circuit foo(): [] {
  AccessControl_assertOnlyRole(MY_ROLE);
}

Roles can be granted and revoked dynamically via the grantRole and revokeRole circuits. Each role has an associated admin role, and only accounts that have a role's admin role can call grantRole and revokeRole.

By default, the admin role for all roles is DEFAULT_ADMIN_ROLE (zero bytes), which means that only accounts with this role will be able to grant or revoke other roles. More complex role relationships can be created by using _setRoleAdmin.

The DEFAULT_ADMIN_ROLE is also its own admin: it has permission to grant and revoke this role. Extra precautions should be taken to secure accounts that have been granted it.

For an overview of the module, read the AccessControl guide.

AccessControl

GitHub icon
import "./node_modules/@openzeppelin/compact-contracts/access/AccessControl";

Ledger

_operatorRoles: Map<Bytes<32>, Map<Either<Bytes<32>, ContractAddress>, Boolean>>

ledger

#

Mapping from a role identifier -> account -> its permissions.

_adminRoles: Map<Bytes<32>, Bytes<32>>

ledger

#

Mapping from a role identifier to an admin role identifier.

Witnesses

wit_AccessControlSK() → Bytes<32>

witness

#

Returns the caller's secret key used in deriving the account identifier.

The same key produces the same account identifier across all contracts. Users who desire cross-contract unlinkability should use different keys per contract.

Circuits

DEFAULT_ADMIN_ROLE() → Bytes<32>

circuit

#

The default admin role for all roles. Returns zero bytes (default<Bytes<32>>). Only accounts with this role will be able to grant or revoke other roles unless custom admin roles are created via _setRoleAdmin.

hasRole(roleId: Bytes<32>, account: Either<Bytes<32>, ContractAddress>) → Boolean

circuit

#

Returns true if account has been granted roleId.

k=10, rows=1019

_hasRole(
  roleId: Bytes<32>,
  account: Either<Bytes<32>, ContractAddress>
) → Boolean

internal

#

Returns true if account has been granted roleId. Internal variant that assumes account has already been canonicalized by the caller. External consumers should use hasRole which canonicalizes the input automatically.

assertOnlyRole(roleId: Bytes<32>) → []

circuit

#

Reverts if the caller cannot prove ownership of roleId. The caller's identity is derived from the wit_AccessControlSK witness as persistentHash(secretKey).

Requirements:

  • The caller must have roleId.
k=13, rows=2669

_checkRole(roleId: Bytes<32>, account: Either<Bytes<32>, ContractAddress>) → []

circuit

#

Reverts if account is missing roleId.

Requirements:

  • account must have roleId.
k=10, rows=999

getRoleAdmin(roleId: Bytes<32>) → Bytes<32>

circuit

#

Returns the admin role that controls roleId or a byte array with all zero bytes if roleId doesn't exist. See grantRole and revokeRole.

To change a role's admin use _setRoleAdmin.

k=9, rows=373

grantRole(roleId: Bytes<32>, account: Either<Bytes<32>, ContractAddress>) → []

circuit

#

Grants roleId to account.

Granting roles to contract addresses is currently disallowed until contract-to-contract interactions are supported in Compact. This restriction prevents permanently disabling access to a circuit.

Requirements:

  • account must not be a ContractAddress.
  • The caller must have roleId's admin role.
k=13, rows=3536

revokeRole(roleId: Bytes<32>, account: Either<Bytes<32>, ContractAddress>) → []

circuit

#

Revokes roleId from account.

Requirements:

  • The caller must have roleId's admin role.
k=13, rows=3466

renounceRole(
  roleId: Bytes<32>,
  callerConfirmation: Either<Bytes<32>, ContractAddress>
) → []

circuit

#

Revokes roleId from the calling account.

Roles are often managed via grantRole and revokeRole: this circuit's purpose is to provide a mechanism for accounts to lose their privileges if they are compromised (such as when a trusted device is misplaced).

The caller's identity is derived from the wit_AccessControlSK witness as persistentHash(secretKey). The callerConfirmation parameter must match the caller's computed account identifier to prevent accidental renunciation.

We do not provide functionality for smart contracts to renounce roles because self-executing transactions are not supported on Midnight at this time. We may revisit this in future if this feature is made available in Compact.

Requirements:

  • The caller's computed account identifier must match callerConfirmation.
  • The caller must not be a ContractAddress.
k=13, rows=3322

_setRoleAdmin(roleId: Bytes<32>, adminRole: Bytes<32>) → []

circuit

#

Sets adminRole as roleId's admin role.

k=10, rows=581

_grantRole(roleId: Bytes<32>, account: Either<Bytes<32>, ContractAddress>) → Boolean

circuit

#

Attempts to grant roleId to account and returns a boolean indicating if roleId was granted.

Internal circuit without access restriction.

Granting roles to contract addresses is currently disallowed in this circuit until contract-to-contract interactions are supported in Compact. This restriction prevents permanently disabling access to a circuit.

Requirements:

  • account must not be a ContractAddress.
k=11, rows=1143

_unsafeGrantRole(roleId: Bytes<32>, account: Either<Bytes<32>, ContractAddress>) → Boolean

circuit

#

Unsafe variant of _grantRole.

Granting roles to contract addresses is considered unsafe because contract-to-contract calls are not currently supported. Granting a role to a smart contract may render a circuit permanently inaccessible. Once contract-to-contract calls are supported, this circuit may be deprecated.

k=11, rows=1142

_revokeRole(roleId: Bytes<32>, account: Either<Bytes<32>, ContractAddress>) → Boolean

circuit

#

Attempts to revoke roleId from account and returns a boolean indicating if roleId was revoked.

Internal circuit without access restriction.

k=11, rows=1073

_computeAccountId() → Bytes<32>

internal

#

Computes the caller's account identifier from the wit_AccessControlSK witness.

ID Derivation: accountId = persistentHash(secretKey)

The result is a 32-byte commitment that uniquely identifies the caller.

computeAccountId(secretKey: Bytes<32>) → Bytes<32>

pure

#

Computes an account identifier without on-chain state, allowing a user to derive their identity commitment before submitting it in a grant or revoke operation. This is the off-chain counterpart to the internal _computeAccountId and produces an identical result given the same inputs.

ID Derivation: accountId = persistentHash(secretKey)

The secretKey parameter is a sensitive secret. Mishandling it can permanently compromise the privacy guarantees of this system. Never log or persist the key in plaintext. Use cryptographically secure randomness to generate keys. Treat key loss as identity loss. A lost key cannot be recovered.

On this page

AccessControlLedger_operatorRoles_adminRolesWitnesseswit_AccessControlSKCircuitsDEFAULT_ADMIN_ROLEhasRole_hasRoleassertOnlyRole_checkRolegetRoleAdmingrantRolerevokeRolerenounceRole_setRoleAdmin_grantRole_unsafeGrantRole_revokeRole_computeAccountIdcomputeAccountId