Cross-Chain Token Standard - Registration & Administration (EVM)

The process of registering your token for Cross-Chain Token (CCT) involves a two-step process to ensure that the correct administrator is assigned. The token's administrator will initially be placed in a proposed state. The administrator must then explicitly accept the role to complete the registration.

Self-Service Registration Flow

If the token contract includes any of the necessary functions (getCCIPAdmin(), or owner()), the registration can be done autonomously by the token administrator:

1. Admin Initiates Registration: The token administrator begins the process by calling one of these functions on the RegistryModuleOwnerCustom contract:
   • registerAdminViaGetCCIPAdmin()
   • registerAdminViaOwner()
2. Determine Administrator: The RegistryModuleOwnerCustom contract retrieves the administrator from the token contract using the appropriate method:
   • Via getCCIPAdmin()
   • Via owner()
3. Propose Administrator: The retrieved administrator is then proposed to the TokenAdminRegistry using the proposeAdministrator() function, placing the administrator in a pending state.
4. Pending Administrator: At this point, the administrator is marked as "pending" in the TokenAdminRegistry and must complete the second step—accepting the role—before being officially assigned.

Non-Self-Service Registration Flow

If the token contract does not have the necessary functions (getCCIPAdmin() or owner()), the token developer must manually initiate the registration by submitting a request here.

Interacting with the Registry

Proposing the Administrator

The following sequence diagram illustrates the process of proposing the administrator for both self-service registration flow:

Accepting the Administrator Role

Once the administrator has been proposed and is in a pending state, they must accept the role to complete the registration process. This step finalizes the assignment of the administrator.

1. Administrator Accepts Role: The pending administrator must explicitly call the acceptAdminRole() function on the TokenAdminRegistry to complete the registration.
2. Finalize Registration: Once the administrator accepts the role, they are assigned as the token administrator, and the registration process is complete. At this point, the token administrator can set a token pool for the token in the TokenAdminRegistry.

Once the administrator has been proposed and is in a pending state, the final step in the registration process is for the pending administrator to accept the role. This sequence diagram illustrates how the pending administrator interacts with the TokenAdminRegistry to complete the registration. It also covers the scenario where an incorrect entity attempts to accept the role, leading to an error.

Transfer Administrator Role

The transferAdminRole function allows the current token administrator to initiate the transfer of their role to a new administrator. The transfer process is a secure two-step procedure, requiring the new administrator to explicitly accept the role before the transfer is finalized.

1. Initiate Role Transfer: The current administrator calls the transferAdminRole() function on the TokenAdminRegistry, specifying the token address and the new administrator's address.
2. Set Pending Administrator: The TokenAdminRegistry contract verifies that the caller is the current administrator of the token and sets the new administrator as pending. The role will remain in this pending state until it is accepted.
3. Accept the Role: The new administrator must call the acceptAdminRole() function to finalize the transfer and assume the administrator role.

The following sequence diagram illustrates the process of transferring the administrator role and how the new administrator must accept the role to complete the transfer.

Setting the Token Pool

The setPool function allows the token administrator to assign or update the token pool for a specific token in the TokenAdminRegistry.

1. Set Token Pool: The current administrator calls the setPool() function on the TokenAdminRegistry, providing the token address and the new pool address.
2. Validate Pool: If the new pool address is not address(0), the contract validates that the provided pool supports the token by calling isSupportedToken() on the pool contract.
3. Update or Remove Pool: If validation succeeds, the token's pool is updated in the registry. Setting the pool to address(0) effectively delists the token from cross-chain operations.

The sequence diagram below shows how the token administrator sets or updates the pool for a token. If the pool is set to address(0), the token is delisted from cross-chain operations.

Configuring the Token Pool

The configuration of token pools includes adding new blockchains, setting remote pool addresses, and applying rate limits for cross-chain transfers. The following functions from the TokenPool contract are used for configuring token pools:

applyChainUpdates

• Purpose: This function is the primary method for configuring which blockchains the token pool supports and defining rate limits for cross-chain transfers.
• Details:
  • It allows the token pool owner to add new chains or remove existing ones.
  • Configures the pool and token addresses for remote blockchains.
  • Sets rate limits for both outbound and inbound transfers.
• Usage:
  • To add a new blockchain, the pool owner provides the remote chain selector, pool address, token address, and rate limiter configurations.
  • To remove a blockchain, the allowed flag is set to false, and the chain is removed from the list of supported chains.

addRemotePool

• Purpose: Adds a new remote pool address for a specific blockchain, enabling support for multiple pools per chain.
• Details:
  • Allows adding multiple pools for a single chain selector, which is crucial during pool upgrades
  • Maintains support for in-flight messages from existing pools while adding new ones
  • Validates chain selector support and prevents duplicate pool additions
  • Each pool address is hashed and stored for efficient lookup
• Usage: This function is particularly useful during pool upgrades, allowing seamless transitions between pool versions while maintaining transaction support.

setChainRateLimiterConfig

• Purpose: Configures the rate limits for outbound and inbound token transfers between blockchains.
• Details:
  • The outbound rate limiter config controls how many tokens can be transferred out of the token pool per unit of time.
  • The inbound rate limiter config limits how many tokens can be transferred into the token pool per unit of time.
  • Only the pool owner or rate limit admin can call this function.
• Notes on Rate Limit Admin: The rate limit admin is a designated address that is authorized to configure the rate limits for a token pool. This admin can be set by the pool owner using the setRateLimitAdmin function. If no rate limit admin is set, only the pool owner can modify the rate limits. You can retrieve the current rate limit admin address using the getRateLimitAdmin function.
• Usage: This function adjusts rate limits to prevent excessive token transfers or overload of the token pool. Note: This function also supports disabling rate limits.

applyAllowListUpdates

• Purpose: Manages an allowlist of addresses permitted to interact with the token pool.
• Details:
  • This function is only relevant if the token pool is access-controlled (i.e., an allowlist is enabled).
  • The allowlist ensures that only specific addresses, such as trusted addresses, can transfer tokens.
• Usage: The pool owner uses this function to add or remove addresses from the allowlist, controlling who can transfer the tokens through CCIP.