Token Authority

The token authority system implements a comprehensive permissions model that enables fine-grained control over token operations. This hierarchical permission structure allows token creators to delegate specific authorities to different addresses while maintaining overall control of their token.

Authority Hierarchy

The Authority system follows a hierarchical structure with the master_authority at the top:

                          
                                 ┌─────────────────────┐
                                 │  master_authority   │
                                 └──────────┬──────────┘
                                            │
                                            ▼
          ┌─────────────────────────┬───────┴────────────┬───────────────────────┐
          │                         │                    │                       │
          ▼                         ▼                    ▼                       ▼
┌──────────────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌───────────────────────────┐ 
│master_mint_burn_authority│ │pause_authorities│ │list_authorities │ │metadata_update_authorities│  
└─────────┬────────────────┘ └─────────────────┘ └─────────────────┘ └───────────────────────────┘ 
          │ 
          ▼ 
 ┌─────────────────────┐ 
 │mint_burn_authorities│ 
 └─────────────────────┘

Permission Types

Master Authority (master_authority)

The master_authority is the root of the permission hierarchy and has complete control over the token.

Capabilities:

• Grant and revoke all other authority types

• Mint tokens without allowance restrictions

• Cannot be changed after token creation

Master Mint Burn Authority (master_mint_burn_authority)

The master_mint_burn_authority can grant and revoke minting and burning privileges to other addresses.

Capabilities:

• Grant minting privileges to other addresses with specific allowances

• Grant burning privileges to other addresses

• Revoke minting and burning privileges from addresses

• Cannot mint tokens directly

Mint Burn Authorities (mint_burn_authorities)

Addresses with minting privileges can create new tokens up to their allowance limit. They can also destroy tokens from any account.

Capabilities:

• Mint new tokens up to their allowance

• Burn tokens from any account

• Cannot grant minting or burning privileges to others

Constraints:

• Maximum of 20 mint burn authorities per token

• Each mint burn authority has a specific allowance that decreases as they mint tokens

Pause Authorities (pause_authorities)

The pause_authorities can temporarily freeze all token transfers.

Capabilities:

• Pause all token transfers, mints, and burns

• Unpause token operations

Constraints:

• Maximum of 5 pause authorities per token

List Authorities (list_authorities)

List authorities can blacklist or white list an address so that it can make the address able or unable to participating in token operations

if it is black listed, the address will be put into black_list.

Capabilities:

• Add addresses to the blacklist

• Remove addresses from the blacklist

Constraints:

• Maximum of 5 blacklist authorities per token

• Blacklisted addresses cannot send or receive tokens

if it is white listed, the address will be put into black_list.

Capabilities:

• Add addresses to the whitelist

• Whitelisting is effective immediately

Constraints:

• Maximum of 5 list authorities per token

Metadata Update Authorities (metadata_update_authorities)

The metadata update authorities can modify the token's metadata.Capabilities:

• Update token name

• Update token URI

• Update additional metadata key-value pairs

Constraints:

• Maximum of 5 metadata update authorities per token

Revoking Authorities

Any authority can be revoked by the master_authority.

---

Best Practices

Separation of Concerns

• Assign different authorities to different addresses based on their responsibilities

• Avoid giving multiple critical authorities to the same address

Secure the Master Authority

• Use a highly secure wallet for the master authority

• Consider using a multisig wallet for the master authority in production environments

Limited Minting Allowances

• Grant minting authorities with appropriate allowances

• Regularly review and adjust allowances as needed

Emergency Planning

• Always have a pause authority assigned for emergency situations

• Test pause/unpause functionality before deploying to production

Authority Rotation

• Periodically rotate authorities as part of security best practices

• Revoke authorities from addresses that no longer need them