Max Balance Hook
TransferHook program for per-wallet maximum token balance enforcement
Overview
The Max Balance Hook enforces a maximum token balance per wallet. When a transfer would cause the destination wallet to exceed the configured limit, the transaction is rejected. This prevents concentration violations and supports regulatory caps like Reg D/S investor limits.
Program ID: Ctx9ZtNzPFYyjqxdZSMYLgHdqNNpAS61G6ok1dYVBHWi
How It Works
During execute_transfer_hook, the program reads the destination token account's current balance at byte offset 64 (the amount field in a Token-2022 account). It then checks:
If the check fails, the transaction reverts with MaxBalanceExceeded.
Accounts
MaxBalanceConfig PDA
Seeds: ["max-balance-config", mint]
| Field | Type | Description |
|---|---|---|
authority | Pubkey | Admin who can manage the config |
mint | Pubkey | The token mint |
max_balance | u64 | Maximum allowed balance per wallet |
is_active | bool | Kill switch |
ExtraAccountMetas PDA
Seeds: ["extra-account-metas", mint]
Instructions
| Instruction | Description |
|---|---|
initialize_extra_account_metas | Create the ExtraAccountMetas PDA |
initialize_max_balance_config | Create the MaxBalanceConfig PDA |
update_max_balance | Change the maximum balance limit |
toggle_active | Emergency kill switch |
update_authority | Transfer admin rights |
execute_transfer_hook | TransferHook entry point — checks balance + amount does not exceed max_balance |
Error Codes
| Code | Name | Description |
|---|---|---|
| 6000 | Unauthorized | Signer is not the config authority |
| 6001 | MaxBalanceExceeded | Transfer would push destination above max_balance |
| 6002 | InvalidMaxBalance | max_balance must be greater than zero |
PDA Seeds
| PDA | Seeds |
|---|---|
| MaxBalanceConfig | ["max-balance-config", mint] |
| ExtraAccountMetas | ["extra-account-metas", mint] |