solanabr/ai-kit / .claude/skills/token-extensions
token-extensions
VerifiedToken-2022 (Token Extensions) on Solana. Pick, combine and create mint and account extensions with the spl-token CLI, @solana/kit or Anchor, and integrate extension mints. Use for transfer fees, hooks, metadata, groups, pausable, permanent delegate, soulbound, interest-bearing, scaled UI or confidential tokens.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 13.7 KB |
| references/account-extensions.md | markdown | 5.9 KB |
| references/confidential.md | markdown | 7.1 KB |
| references/display-amounts.md | markdown | 4.8 KB |
| references/fees.md | markdown | 6.0 KB |
| references/issuer-controls.md | markdown | 8.1 KB |
| references/metadata-groups.md | markdown | 9.1 KB |
| references/programs.md | markdown | 8.7 KB |
| references/transfer-hooks.md | markdown | 10.9 KB |
references/fees.md
View on GitHub# Transfer fees: TransferFeeConfig, TransferFeeAmount
A fee withheld from every `TransferChecked`. The sender is debited `amount`, the recipient is credited `amount - fee`, and the fee stays withheld in the recipient's token account until anyone harvests it to the mint or the withdraw authority withdraws it.
- **Lives on:** the mint (TransferFeeConfig). Every token account of the mint gets TransferFeeAmount, which holds its withheld fees.
- **Authorities:** the transfer fee config authority changes the fee; the withdraw withheld authority collects fees. Rotate them with SetAuthority types `TransferFeeConfig` and `WithheldWithdraw` (CLI `spl-token authorize <MINT> transfer-fee-config|withheld-withdraw <NEW>`, or `--disable`). Either can be None, and setting one to None can't be undone.
## Fee math
- `fee = ceil(amount * basis_points / 10_000)`, capped at `maximum_fee`, and 0 when either is 0. Basis points above 10_000 fail with `TransferFeeExceedsMaximum`.
- The mint stores an older and a newer fee; the newer one applies from its epoch on. `SetTransferFee` in epoch N makes the new fee apply from epoch N+2, and calling it again before then restarts that delay. Read the fee that applies now with `get_epoch_fee(current_epoch)` (Rust) or `getEpochFee(config, epoch)` (web3.js 1.x), not `newer_transfer_fee`.
- Kit has no fee calculator. web3.js 1.x has `calculateEpochFee(config, epoch, amount)`; Rust has `TransferFeeConfig::calculate_epoch_fee(epoch, amount)`. For a transfer that must deliver exactly `net`, `calculate_inverse_epoch_fee(epoch, net)` returns the fee, so send `net + fee`; `get_epoch_fee(epoch).calculate_pre_fee_amount(net)` returns that gross amount directly.
## Create the mint
CLI (the maximum fee is in UI units; the mint authority becomes both fee authorities):
```sh
spl-token --program-2022 create-token --decimals 6 \
--transfer-fee-basis-points 50 --transfer-fee-maximum-fee 5000
```
Kit, as one entry in the `extensions` array of `createMint` or `getCreateMintInstructionPlan` (see the SKILL.md creation steps):
```ts
extension('TransferFeeConfig', {
transferFeeConfigAuthority: authority,
withdrawWithheldAuthority: authority,
withheldAmount: 0n,
olderTransferFee: { epoch: 0n, maximumFee: 5_000_000_000n, transferFeeBasisPoints: 50 },
newerTransferFee: { epoch: 0n, maximumFee: 5_000_000_000n, transferFeeBasisPoints: 50 },
});
```
Only `newerTransferFee`'s basis points and maximum reach the initialize instruction; the program sets both fees to the current epoch. For a None authority, call `getInitializeTransferFeeConfigInstruction({ mint, transferFeeConfigAuthority, withdrawWithheldAuthority, transferFeeBasisPoints, maximumFee })` yourself, since `extension()` requires both addresses.
Anchor 1.2.0 has no `extensions::` constraint for fees. Create the account, then `transfer_fee_initialize(ctx, Some(&config_authority), Some(&withdraw_authority), basis_points, maximum_fee)`, then `initialize_mint2`: see the example in [programs.md](programs.md).
To keep the option of a fee later, create the mint with 0 basis points and keep the fee config authority. The extension can't be added to an existing mint.
## Transfer
- `TransferChecked` charges the fee. `TransferCheckedWithFee` also asserts the fee you computed and fails with `FeeMismatch` if it differs; use it when a UI has shown the user a fee (Kit `getTransferCheckedWithFeeInstruction({ source, mint, destination, authority, amount, decimals, fee })`, Anchor `transfer_checked_with_fee(ctx, amount, decimals, fee)`, CLI `spl-token transfer <MINT> <AMOUNT> <RECIPIENT> --expected-fee <UI_AMOUNT>`).
- Plain `Transfer` fails with `MintRequiredForTransfer`.
- A program that receives these tokens should reload the destination after the CPI and credit the balance change, not `amount`.
- A transfer to the same account charges no fee.
## Collect withheld fees
1. `HarvestWithheldTokensToMint` moves withheld fees from token accounts into the mint. Anyone can call it; it skips accounts it can't harvest and works on frozen accounts.
2. `WithdrawWithheldTokensFromMint` (withdraw authority signs) sends the mint's withheld total to a token account of the same mint that isn't frozen. `WithdrawWithheldTokensFromAccounts` does the same straight from listed token accounts.
| | Harvest to mint | Withdraw from mint | Withdraw from accounts |
|---|---|---|---|
| Kit | `getHarvestWithheldTokensToMintInstruction({ mint, sources })` | `getWithdrawWithheldTokensFromMintInstruction({ mint, feeReceiver, withdrawWithheldAuthority })` | `getWithdrawWithheldTokensFromAccountsInstruction({ mint, feeReceiver, withdrawWithheldAuthority, numTokenAccounts, sources })`; set `numTokenAccounts` to `sources.length`, since the program treats the surplus leading accounts as multisig signers and skips them |
| Anchor 1.2.0 | `harvest_withheld_tokens_to_mint(ctx, sources)` | `withdraw_withheld_tokens_from_mint(ctx)` | `withdraw_withheld_tokens_from_accounts(ctx, sources)` |
| CLI | `spl-token close` harvests first | `spl-token withdraw-withheld-tokens <RECIPIENT_ACCOUNT> --include-mint` | `spl-token withdraw-withheld-tokens <RECIPIENT_ACCOUNT> <SOURCE_ACCOUNT>...` |
The Anchor wrappers take their program id from the `token_program_id` account and pass no multisig signers, so a multisig authority needs a hand-built instruction.
## Gotchas
- A token account holding withheld fees can't be closed (`AccountHasWithheldTransferFees`). Harvest it to the mint first.
- Withheld fees still count in the supply. Closing a mint (MintCloseAuthority) needs a supply of 0, so withdraw and burn them first.
- TransferFeeConfig together with ConfidentialTransferMint also needs ConfidentialTransferFeeConfig ([confidential.md](confidential.md)); the CLI adds it when you enable both.
- Test the two-epoch delay by warping epochs: Surfpool's `surfnet_timeTravel` takes `{"absoluteEpoch": n}` ([cheatcodes.md](../../ext/solana-dev/skills/solana-dev/references/surfpool/cheatcodes.md)).
- Orca's pools accept fee mints without a TokenBadge; other venues set their own rules ([programs.md](programs.md)).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |