Role keys

A Roles Modifier stores each role under a bytes32 key. The key is the only identity that a role has: members are assigned to the key, permissions are scoped to it, and members name it when they execute.

Keys and policies

A policy enables roles on the Roles Modifiers of its vaults. All of these roles use the policy’s key. A policy that applies to three vaults has three roles, one on each Roles Modifier, under one key.

Format

A key is a label packed into bytes32. The label’s bytes fill the value from the left, and the remaining bytes stay zero:

Keys are case-sensitive: swapper and Swapper are different bytes, so they identify different roles. A policy key has 1 to 31 characters: letters, digits, underscores, and hyphens.

A role can also live under a bytes32 value that is not a packed label, for example a hash. Such a key has no readable form, so a policy cannot use it.

One policy per key

A Roles Modifier holds one role per key, and two policies meet on a Roles Modifier when they share a vault. Within a workspace, a key therefore belongs to one policy per chain.

A key also stays taken while a policy that no longer carries it still has a role under it onchain: the key of a deleted policy, until its roles are removed, and the key a policy was imported with, until the first deployment has moved the role. A role that somebody else put under the key does not count.

Keys do not change

A Roles Modifier cannot rename a role, and a policy keeps its key from the moment it is created. To use another key, create a new policy under it and delete the old one. Deploying the new policy sets up its roles; applying the old policy’s deletion removes the roles under the old key.

Roles that already exist under a key

A Roles Modifier does not record who created a role. If a role already exists under the policy’s key on one of its Roles Modifiers — created by a constellation, a script, or another app — deploying the policy replaces that role’s members and permissions.

Imported roles

An imported role keeps its key, so the policy manages the same role onchain. When the label cannot be a policy key — it contains other characters, or another policy in the workspace already uses it — the policy gets a new key at import. The first deployment then moves the role: it sets up the role under the new key and clears the original one. This is the only way a role ends up under a different key than the one it was created with.

A role whose key has no readable form cannot be imported.

Next steps

• Assign members and scope targets: Permission model
• Execute under a role: Execution & debugging