Access and Policy

A token's controls are part of the contract, not an off-chain layer. Who may hold it, who may act on it, how much may be minted, and whether it is paused are all enforced on chain. Every change runs through the token's admin Safe, so high-impact actions require its signer quorum.

Access registry: allow and deny lists

An access registry gates who may send or receive a token. A token runs in one of two modes:

Allow list: only listed addresses may transact. Adding an address permits it. This is the closed model for a permissioned asset.
Deny list: everyone may transact except listed addresses. Adding an address blocks it.

A token may be deployed with a registry, or deployed open and have a registry attached later. Membership is changed through the admin Safe (add or remove addresses), and the on-chain registry reflects the change once the operation confirms. A token without a registry is open: any address may hold it.

Roles

Named roles govern who may perform privileged contract actions. The admin Safe holds the top admin role and is the administrator of every named role, so it grants and revokes the rest. The named roles come from a fixed set, for example a minter role, a burner role, a pauser role, and a recovery role.

The deploy grants the admin Safe its core roles (admin, minter, pauser).
Some actions need a role the deploy does not grant. Burning needs a burner role; the compliance recovery action needs a recovery role. Grant it through the Safe before using that action.
On chain is the source of truth. The off-chain role record is updated only after a grant or revoke confirms.

Recovery: clawing back a blocked balance

The compliance recovery action moves a blocked account's balance to the admin Safe. It is the strictest privileged action and the contract enforces three prerequisites, all of which must hold or the action reverts on chain:

The admin Safe must hold the recovery role. The deploy does not grant it, so grant it through the Safe first, as noted above.
The token must have an access registry attached. Recovery is defined only against a registry, so a token with no registry cannot recover.
The target account must currently be denied by that registry. Recovery works on a blocked account, not an active one, so recovering an account that still has access reverts.

Because recovery reverts unless all three hold, block the account first in whichever mode the registry runs: on a deny-list token, add the account to the deny list; on an allow-list token, remove the account from the allow list. Then recover.

Policies: capped, unattended minting

A mint-cap policy lets a server-controlled key mint gaslessly within a per-call amount cap, without a Safe signature each time. This is the unattended capped-minting path for automation that issues supply on a schedule or on demand.

The Safe sets the policy once: it scopes a verified server key to mint up to a fixed cap.
After that, the server key submits capped mints gaslessly. The relayer submits them; a mint above the cap reverts on chain.
The Safe can revoke the policy at any time, which removes the server key's scoped permission.

A policy never widens what a key may do beyond its cap. The cap is enforced on chain, so a compromised server key still cannot mint above the policy limit.

How a policy mint is signed

POST /v1/tokenization/tokens/{id}/policy-mint builds the operation and returns module_typed_data and module_tx_hash. The scoped server key signs module_typed_data with eth_signTypedData (EIP-712). Do not sign module_tx_hash with personal_sign (EIP-191): personal_sign prefixes the digest, recovery produces a different address, and the submission is rejected with a signer mismatch.

This is a deliberately different shape from a Safe-path mint. A Safe mint signs a Safe transaction (typed_data, keyed by safe_tx_hash) against the admin Safe's signer quorum. A policy mint signs a module transaction against the token's on-chain policy contract (a Zodiac Roles module, the Safe-ecosystem permissions component), whose EIP-712 domain is the policy contract itself; the module enforces the amount cap during execution, so no Safe quorum is needed per mint. module_tx_hash is the EIP-712 digest and the operation's replay guard.

Submit the signature to POST /v1/tokenization/tokens/{id}/operations/{operation_id}/module-signature; the relayer then executes the mint gaslessly. The generic .../signatures endpoint is the Safe-path (SafeTx) signature route and rejects a policy-mint operation, because a policy mint's ModuleTx signature carries only the raw signature (no Safe-owner signer field) and is verified against the scoped authority's key, not the Safe owner set. For the exact typed-data fields, see the interactive reference.

Pause: the circuit breaker

Pausing flips a global circuit breaker on the token. While paused, every transfer, mint, and burn reverts on chain. Pause and unpause run through the admin Safe and require the pauser role (granted at deploy). Use it to freeze a token during an incident, then unpause to restore normal operation.

Everything routes through the Safe

Attaching a registry, changing membership, granting or revoking a role, setting or revoking a policy, and pausing all build a Safe transaction. The Safe's N of M owners sign the typed data, the platform relayer submits it, and a confirmation poller records success only after the transaction confirms on chain. A reverted-but-mined transaction is never treated as success.

For the exact request shapes, the role names, and the policy parameters, see the interactive reference or the operations list under the tokenization tag. For the quorum and governance model, see Policies and Quorum Governance.

Was this helpful?