Module token_2022_ext

Expand description

Zero-copy Token-2022 extension TLV readers.

Token-2022 stores extension data in a TLV region after a fixed per-account prefix. Each TLV entry is [type: u16 LE][length: u16 LE][data: length bytes].

Anchor routes every extension constraint through InterfaceAccount<Mint>, which Borsh-deserializes the whole account. Quasar has a zero-copy base-layout reader but no TLV helpers. Pinocchio has nothing. This module fills the gap.

Every reader here validates only the bytes it reads. No heap allocation, no full-account decode, no version coupling to spl-token-2022. A program that needs to enforce transfer_hook::authority = X on a mint calls require_transfer_hook_authority and pays the cost of a TLV scan plus a 32-byte compare. That is the cost floor for a correct check.

§On-chain layout (authoritative)

An extended mint is padded to the same length as an extended token account so that the Token-2022 program cannot confuse the two by data length alone; the one-byte AccountType discriminator at offset ACCOUNT_TYPE_OFFSET (= 165) disambiguates them.

Extended mint         : [0..82] Mint base | [82..165] padding | [165] AccountType=1 | [166..] TLV
Extended token account: [0..165] Account base                 | [165] AccountType=2 | [166..] TLV

Both shapes place the AccountType byte at offset 165 and begin TLV data at offset 166. BASE_MINT_LEN (82) is the length of a plain, non-extended mint and is used by length checks; it is not the offset at which mint extensions live. This layout matches spl-token-2022 and the pinocchio reference implementation (validate_account_type keys on bytes[BASE_ACCOUNT_LENGTH] where BASE_ACCOUNT_LENGTH = 165).

§Extension type constants

Values are the on-chain u16 encoding from spl-token-2022::extension::ExtensionType. They are stable wire values and safe to hard-code. The full set is listed below so tooling can surface the name for any TLV it encounters.

Constants§

ACCOUNT_TYPE_MINT: Account-type byte: Mint.
ACCOUNT_TYPE_OFFSET: Offset of the AccountType discriminator on any extended Token-2022 account (mint or token account).
ACCOUNT_TYPE_TOKEN: Account-type byte: Token Account.
BASE_MINT_LEN: Length of a plain (non-extended) mint’s data region.
BASE_TOKEN_LEN: Length of a plain (non-extended) token-account’s data region.
EXT_CONFIDENTIAL_TRANSFER_ACCOUNT
EXT_CONFIDENTIAL_TRANSFER_FEE_AMOUNT
EXT_CONFIDENTIAL_TRANSFER_FEE_CONFIG
EXT_CONFIDENTIAL_TRANSFER_MINT
EXT_CPI_GUARD
EXT_DEFAULT_ACCOUNT_STATE
EXT_GROUP_MEMBER_POINTER
EXT_GROUP_POINTER
EXT_IMMUTABLE_OWNER
EXT_INTEREST_BEARING_CONFIG
EXT_MEMO_TRANSFER
EXT_METADATA_POINTER
EXT_MINT_CLOSE_AUTHORITY
EXT_NON_TRANSFERABLE
EXT_NON_TRANSFERABLE_ACCOUNT
EXT_PAUSABLE_ACCOUNT
EXT_PAUSABLE_CONFIG
EXT_PERMANENT_DELEGATE
EXT_SCALED_UI_AMOUNT_CONFIG
EXT_TOKEN_GROUP
EXT_TOKEN_GROUP_MEMBER
EXT_TOKEN_METADATA
EXT_TRANSFER_FEE_AMOUNT
EXT_TRANSFER_FEE_CONFIG
EXT_TRANSFER_HOOK
EXT_TRANSFER_HOOK_ACCOUNT
EXT_UNINITIALIZED
MINT_EXTENSION_PADDING_END: End of the mint extension padding region (exclusive).
MINT_EXTENSION_PADDING_START: Start of the mint’s extension padding region (82..165). Bytes in this range are zero-filled and exist purely to equalize the length of extended mints and extended token accounts.
TLV_OFFSET: Offset at which the TLV extension region begins on any extended Token-2022 account (mint or token account).

Functions§

find_extension: Locate an extension in a Token-2022 account’s TLV region.
mint_tlv_region: Slice the TLV region out of a mint account’s data.
require_default_account_state: Require a mint’s DefaultAccountState byte to equal expected.
require_immutable_owner: Require a token account to carry the ImmutableOwner extension.
require_interest_bearing_authority: Require a mint’s InterestBearingConfig rate-authority to equal expected.
require_metadata_pointer_address: Require a mint’s MetadataPointer metadata-address to equal expected.
require_metadata_pointer_authority: Require a mint’s MetadataPointer authority to equal expected.
require_mint_close_authority: Require a mint’s MintCloseAuthority extension to equal expected.
require_non_transferable: Require a mint to carry the NonTransferable extension.
require_permanent_delegate: Require a mint’s PermanentDelegate extension to equal expected.
require_transfer_fee_config_authority: Require a mint’s TransferFeeConfig transfer-fee-config authority to equal expected.
require_transfer_fee_withdraw_authority: Require a mint’s TransferFeeConfig withdraw-withheld-authority to equal expected.
require_transfer_hook_authority: Require a mint’s TransferHook authority to equal expected.
require_transfer_hook_program: Require a mint’s TransferHook program id to equal expected.
token_account_tlv_region: Slice the TLV region out of a token-account’s data.