Token Metadata v1.12 -- Initial Fees

[samuelvanderwaal]

Token Metadata v1.12 Summary

Adds the system_program and sysvar_instruction accounts to all instructions that don't already have them to facilitate future fee-taking.

Levies fees on the following instructions:

• create_metadata_accounts_v3
• create

"Print" commands, which create edition NFTs, will have the same fee applied but will be shipped after the pNFT unified Print command is implemented for consistency.

Makes edition account mutable for the following instructions:

• freeze_delegated_account
• thaw_delegated_account

Makes metadata account mutable for the following instructions:

• approve_collection_authority
• revoke_collection_authority
• approve_use_authority
• revoke_use_authority

Writes a Fee Flag to the last byte of the Metadata account or the second to last byte of the Master Edition account to indicate the account has fees to be collected.

Fees

Strategy

For most instructions, we need the system_program account passed in so we can CPI into it and call the transfer function to move funds from a user wallet to one of our PDA accounts. We also include the sysvars_instruction account so we can determine ordering of instructions in a transaction to try to avoid double charging users who use certain combinations of instructions in the same transaction. An example of this would be candy machine mint transactions which call both create_metadata and update_metadata.

Instead of using a fee treasury account, and passing it in, we are opting to store fees in metadata and edition accounts and harvesting them later with an automated service. The advantage of this is we already have these accounts passed into most instructions, and storing funds in them does not incur any additional write lock penalties, unlike using a single treasury account across multiple instructions. Even using multiple fee treasury accounts may not be sufficient, as a single instruction such as set_and_verify could be run thousands of times in a collection migration scenario. Multiple thousand item collections being migrated concurrently could result in an unacceptably severe write lock on the fee treasury account.

Adding additional accounts is a breaking change, so the strategy here is to only collect fees on instructions that already have system_program, which is only the create instructions. We also can collect fees on burn instructions as they are a unique case, but have opted to do this later.

For all the other instructions we wish to collect fees on, we add in the extra accounts now into the instructions, but do not use them in the actual processor handlers for the instructions. This keeps this on-chain version backwards compatible with other instructions but also gives users new instructions they can migrate to now, and which will be required for the next version when we start processing the instructions in the handlers on-chain.

Accounts that already have the edition or metadata accounts passed in, but as readonly have these accounts changed to mutable in these new instructions but won't be used mutably on chain until the next version.

Implementation

There's a new source file called fees.rs where most of the fee logic is contained. levy() calculates the correct fee amount based on the instruction type (IxType). Currently only the create instructions are implemented here. All future fee instructions that require a system transfer from a user's wallet should be added here.

Charging fees then, is a simple matter of calling this function within the instruction handler and passing in the correct IxType and a few other parameters:

levy(LevyArgs {
    ix_type: IxType::CreateMetadata,
    payer_account_info,
    receiver_account_info: metadata_account_info,
})?;

The burn_nft and burn_print_edition instructions have also had the additional accounts added for maximum future flexibility, though they shouldn't ever need them.

[github-actions]

Workflow Verify package library found differences when running yarn api:gen in the JS lib for token-metadata. Please see the job for more details: https://github.com/metaplex-foundation/metaplex-program-library/actions/runs/5049919025.

[github-actions]

Workflow Verify package library found differences when running yarn api:gen in the JS lib for token-metadata. Please see the job for more details: https://github.com/metaplex-foundation/metaplex-program-library/actions/runs/5050632653.

[github-actions]

Workflow Verify package library found differences when running yarn api:gen in the JS lib for token-metadata. Please see the job for more details: https://github.com/metaplex-foundation/metaplex-program-library/actions/runs/5061767444.

[github-actions]

Workflow Verify package library found differences when running yarn api:gen in the JS lib for token-metadata. Please see the job for more details: https://github.com/metaplex-foundation/metaplex-program-library/actions/runs/5083555352.

[danenbm]

imo this should just use md_account.unwrap() since you know it will still be open, but if you want to leave it as is to be flexible that's fine with me too, I just don't really like if let without else when we are talking verifying a test result.

[samuelvanderwaal]

There are two situations here: one where the Metadata account is still open either because it has not been garbage collected yet, or because it still has fees on it. In that case we use the if let to see if it has an account data length of 0. In the case where it's been garbage collected it's the None case and the else is implicit. The only time to fail is if it exists and the account length isn't 0.

[danenbm]

Ok that is fine. I thought all the nonfungible accounts used in tests would now have uncollected fees on them from create and remain open since the tests don't remove fees.

[danenbm]

Ok that is fine. I thought all the nonfungible accounts used in tests would now have uncollected fees on them from create and remain open since the tests don't remove fees.