Overview

The Allowlist token utility contract can be used to control who explicitly can interact with your Fireblocks token contracts. This contract works seamlessly with Fireblocks ERC-20F, ERC-721F, and ERC-1155F token contracts and uses a registry of authorized addresses to enforce access control.

• The Allowlist must be used with a deployed Fireblocks token contract, not third-party contracts like those created by BitBond, OpenZeppelin, etc.
• Multiple Fireblocks token contracts can work with the same Allowlist.
• A token contract can only be connected to a single Allowlist or Denylist at a given time. You can change which Allowlist or Denylist is connected as required.

The Allowlist is upgradeable using the UUPS proxy pattern. This consists of a Fireblocks-deployed Logic contract and a customer-deployed Proxy contract that points to the Logic contract. Learn more.

Deploying

When deploying an Allowlist contract, make sure to enter the addresses, such as a Fireblocks vault account, you want for the Default Admin, Pauser, and Upgrader roles.

Learn more about smart contract roles.

Roles for managing the Allowlist

The following smart contract roles can be assigned to help manage the Allowlist.

• Upgrader: Can make changes and improvements to the Allowlist
• Pauser: Can temporarily pause the Allowlist
• Contract admin: Can manage the contract’s settings, such as adding a link in the contractUri field
• Access list admin: Can add, remove, or change permissions by adding and removing addresses in the Allowlist

Updating the Allowlist

After deploying the Allowlist, you can add and remove addresses to and from the Allowlist as needed.

First, you need to grant someone the Access List Admin role.

1. On the Tokenization page, select More Actions (...) > Manage contract corresponding to the relevant smart contract.
2. Copy the Access List Admin role hash from the Read functions.
3. Select Write and use the grantRole function.
4. Enter the hash for the Access List Admin role you copied in step 2, and then enter the address that should be granted the role.
5. Select Submit.

At this point, the user granted the Access List Admin role can add and remove addresses to and from the Allowlist.

Adding addresses

1. On the Tokenization page, select Manage contract for the Allowlist contract.
2. Then select Write and use the accessListAdd function.
3. Enter the addresses to add to the Allowlist. You must select the Enter key after each address you add.
4. Select Submit.

Removing addresses

1. On the Tokenization page, select Manage contract for the Allowlist contract.
2. Then select Write and use the accessListRemove function.
3. Enter the address you want to remove from the Allowlist.
4. Select Submit.

Connecting the Allowlist to your Fireblocks token contracts

You can connect the Allowlist to one or more of your deployed Fireblocks token contracts, such as ERC-20F, ERC-721F, and ERC-1155F.

First, you need to grant the Contract Admin role for your Fireblocks token contract to a user’s address.

1. In the Fireblocks Console, go to the Tokenization page and select More Actions (...) > Manage contract for the token contract you want the Allowlist connected to.
2. Copy the Contract Admin role hash from the Read functions.
3. Then select Write and use the grantRole function.
4. Enter the hash for the Contract Admin role you copied in step 2, and then enter the address that should be granted the role.
5. Select Submit.

At this point, the user granted the Contract Admin role can access the token contract and connect the Allowlist.

1. On the Tokenization page, copy the address to the Allowlist.
2. Select More Actions (...) > Manage contract corresponding to the relevant token contract.
3. Then select Write and use the accessRegistryUpdate() function.
4. Enter the Allowlist’s address in the Access registry field.
5. Select Submit.