Capped Minters 101

What are Capped Minters?

Capped minters are unique smart contracts of the ZKsync ecosystem that allow for “just-in-time minting.” Each capped minter is assigned a maximum number of tokens, known as the “cap,” which is allowed to be minted. Those with the minter role of a capped minter can mint tokens from that supply whenever they choose to, up to the maximum specified. Learn more about how Capped Minters are used in ZKsync token governance.

ZK Capped Minter V2

The current version of the capped minter contract is the ZKCappedMinterV2. The ZK Capped Minter V2 expands the limited functionality of V1, where the creator could assign a token, admin, and cap.

ZK Capped Minter V2 Features Overview:

  • Minting Cap: Like V1, the ZK Capped Minter V2 enforces a strict upper limit on the total number of tokens that can be minted, ensuring controlled token allocations.

  • Multiple Minters: Uses role-based permissions to manage minting rights, enabling the immutable admin to assign multiple minters for the capped minter.

  • Nested Minters: As a result of the minter role, token programs can have hierarchies of nested capped minters. This is particularly useful for the creation of sub-programs, or agent-specific minting rights.

  • Start and Expiration Dates: Adds the ability to arbitrarily set a start and expiration time for a capped minter.

  • Pause and Cancel Operations: Allows the admin to pause or fully cancel minting activities, providing a safeguard against unforeseen issues. The admin can also assign other addresses to have the power to pause.

  • Metadata: Allows admin to set a custom metadata URI, allowing each minter to contained additional information related to connected token flows.

  • Events: Emits onchain events for granting the minter role, minting, cancelling, setting metadata. New analytics and monitoring are possible.

Deploying a Capped Minter

You can deploy a capped minter through a the ZKCappedMinterV2 Factory. You can find the source code for the V2 Factory here. The V2 Factory was created to make capped minter deployment more accessible.

ℹ️ Testnet capped minter deployment can be done through the Testnet_ZkCappedMinterV2Factory

  1. Go to the CappedMinter V2 Factory

  2. Select “Contract” and “Write”

Screenshot 2025-03-19 at 10.30.21

  1. Connect your wallet

  2. Specificy the parameters for the capped minter V2 being deployed:

    • Mintable Token Address (_mintable): The address of the token contract that will be minted from.

    • Administrator Address (_admin): The address granted administrative privileges, including the ability to assign the MINTER role.

    • Minting Cap (_cap): The maximum number of tokens that can be minted by this contract.

    • Start Time (_startTime): The seconds timestamp from which minting is permitted.

    • Expiration Time (_expirationTime): The seconds timestamp after which minting is no longer allowed. Please note that any child capped minters will expire on the specified end date of a parent capped minter.

    • saltNonce: arbitrary value that helps define the deployed contract’s address.

Screenshot 2025-03-19 at 10.58.50

Verifying a Capped Minter

Verifying in Command Line

  1. Set your working directory: Please note the input below is an EXAMPLE - customize as needed. This is where you will copy the contracts and build the folder system for the code.

cd Documents/Dev/

  1. Clone the repo where governance contracts are managed

git clone <https://github.com/zksync-association/zk-governance.git>

  1. (Optional) Install Hardhat (see npm docs)

npm install --save-dev hardhat
npm install --save-dev typescript

  1. Change directory to L2 governance contract working directory

cd l2-contracts/

  1. Set default network

    1. // Change default network to zkSyncEra

    2. // (IF TESTNET) Change default network to zkSyncTestnet

nano hardhat.config.ts

  1. Compile contracts

npx hardhat compile

  1. Verify Contract

    1. npx hardhat verify [contract address] [token] [admin] [cap] [starttime] [expirationtime]

    2. Change your parameters as needed

EXAMPLE:

npx hardhat verify 0x721b6d77a58FaaF540bE49F28D668a46214Ba44c 0x5A7d6b2F92C77FAD6CCaBd7EE0624E64907Eaf3E 0x77CC0A0582475bfD74CD838610e817d05c181E11 8301475000000000000000000 1736899200 1752537600

Reading a Capped Minter Contract

In order to read the parameters of an already deployed capped minter contract, simply paste the address in the ZKsync Era Block Explorer, go to “Contract”, and the “Read”. There, you will find the following parameters.

  1. CAP: Query this parameter to see the immutable cap on a given capped minter

  2. DEFAULT_ADMIN_ROLE: Query this parameter to get the default admin role address

  3. EXPIRATION_TIME: Query this parameter to see the end (expiration) date of a capped minter

  4. MINTABLE: Query this parameter to get the address of the token being minter (ZK)

  5. MINTER_ROLE: Query this parameter to get the minter role address for this capped minter

  6. PAUSER_ROLE: Query this parameter to get the pauser role address for this capped minter

  7. START_TIME: Query this parameter to see the start (activation) date of a capped minter

  8. closed: Query this parameter to check if the minter is closed

  9. getRoleAdmin: Query this parameter to see if a role is an admin of another role on the capped minter

  10. hasRole: Query this parameter to verify if a specific address has a certain role

  11. metadataURI: Query this parameter to get a URI for capped minter metadata

  12. minted: Query this parameter to see how much ZK has been minted from the CAP

  13. paused: Query this parameter to see if the capped minter contract has been pause (true = paused, false = not paused)

  14. supportsinterface: Query this parameter by adding an interface ID to check if an interface is supported with the contract

Confirming the Minter Role on a Capped Minter

Minting rights are represented by the minter role. The minter role is granted and revoked by passing a Token Program Proposal (TPP). To verify if a capped minter has the minter role or not, following the steps below.

Verify Parent Capped Minter has minter role on ZK token contract

  1. Open the ZK token contract on the Era Block Explorer

  2. Go to Contract > Read

  3. Toggle down the hasRole parameter

  4. Enter the MINTER_ROLE address (query from above)

  5. Enter address of the capped minter

  6. Select “Query”

If the query returns true, the capped minter has the minter role on the ZK token contract and is able to mint up to it’s specified cap. If it returns false, it means the capped minter does not have the minter role, and no tokens can be minted from that capped minter.

Example from the TPP-6 capped minter.

Nested Capped Minters (Parent / Child)

It is possible to nest “child” capped minters under a “parent” capped minter. While a parent capped minter’s target to mint from will always be the ZK token contract, a child’s target to mint from will be the parent (or a mod linked to the parent).

Verify Child Capped Minter has minter role on parent capped minter

  1. Open the Parent Capped Minter contract on the Era Block Explorer

  2. Go to Contract > Read as Proxy

  3. Toggle down the hasRole parameter

  4. Enter the MINTER_ROLE address (query from above)

  5. Enter address of the child capped minter

  6. Select “Query”

If the query returns true, the child capped minter has the minter role on the parent capped minter and is able to mint up to it’s specified cap. If it returns false, it means the child capped minter does not have the minter role, and no tokens can be minted from that capped minter.

Minting from a Capped Minter

ℹ️ Please note that only users assigned the minter role are able to mint from a capped minter. The Admin of a capped minter can assign the minter role on a give capped minter.

Minting ZK from Era Block Explorer

  1. Enter the capped minter address you want to mint from in the Era Block Explorer

  2. Go to “Contract”, then “Write”

  3. Connect the wallet that has the minter role

  4. Toggle down the “mint” parameter

  5. Enter address of where you want the ZK minted to in “_to (address)”:

  6. Enter the amount ZK in “amount (unit256)

ℹ️ We recommend doing a test mint for a small portion of the full cap to the target address before minting the full cap.

  1. Select “write”

  2. Verify that the minted ZK was received by target address

Mint Tokens through Safe UI

  1. Login to the SC Ops multisig Safe wallet and select "New transaction" in the top left corner

  2. Select “Transaction Builder”

  3. Enter the capped minter contract address: (the ABI should automatically load)

  4. Scroll down to “Contract Method Selector” and select “mint”

  5. Enter address of where you want the ZK minted to in “_to (address)”:

  6. Enter the amount ZK in “amount (unit256)

ℹ️ We recommend doing a test mint for a small portion of the full cap to the target address before minting the full cap.

  1. Select “Add new transaction”

  2. Select “Create branch” in top right and follow the instructions in the Safe UI to review and execute the transaction

  3. Verify that the minted ZK was received by target address

PreviousTPP FAQNextGovernance Advisory Proposals (GAPs)

Last updated