Put a speed limit on token transfers.

When you finish this: your own copy of the assignment on GitHub and on your machine.

1. Open github.com/decentra1ized/solana-fall-transfer-hook and click Fork, top right.
2. Clone your fork, not the original. Put your GitHub username in the link.

git clone https://github.com/YOUR-USERNAME/solana-fall-transfer-hook.git
cd solana-fall-transfer-hook
yarn install

printf "target/\nnode_modules/\n.anchor/\ntest-ledger/\n" > .gitignore

Versions this repo expects

Push after each challenge, so your progress is saved:

git add -A && git commit -m "challenge 1" && git push

When you finish this: all four tests pass on the untouched code. Prove this before changing anything.

anchor build
cargo test

You should see four passing tests:

test test_initialize ... ok
test test_initialize_extra_account_meta_list ... ok
test test_transfer_hook ... ok
test test_transfer_hook_rate_limit_exceeded ... ok

When you finish this: you can explain what each instruction does and in what order they run.

The program has four instructions. They run in this order:

What happens on each transfer

1. Confirm the hook was called by a real transfer, not directly.
2. If more than one hour has passed since window_start, reset the total to zero.
3. If the total plus this amount is over the cap, fail with RateLimitExceeded.
4. Otherwise add the amount to the total and let the transfer through.

Goal: initialize refuses to run unless it is given a real Token-2022 mint.

Why it matters: right now initialize never looks at a mint. Someone could create a rate limit for a normal SPL Token mint. Those cannot have transfer hooks, so the limit would never be enforced.

1 · Add the mint to the context

In initialize.rs, add this field to Initialize, above rate_limit:

pub mint: InterfaceAccount<'info, Mint>,

2 · Check who owns it

At the top of the handler, before set_inner, check that the mint's owner is the Token-2022 program. If not, return ErrorCode::InvalidMint.

InterfaceAccount accepts mints from both token programs. Your check is what narrows it to Token-2022 only. The imports you need are already at the top of the file.

3 · Update the tests

Two places build Initialize: initialize_rate_limit in tests/helpers/mod.rs, and tests/test_initialize.rs. Add mint: mint.pubkey(), to both, then build and test.

Goal: each RateLimit account records which mint it belongs to.

Why it matters: anyone reading the account later, a wallet, an explorer, or your own code, can see what it is for without working it out from addresses.

1 · Add the field

In state/rate_limit.rs:

pub struct RateLimit {
    pub authority: Pubkey,
    pub mint: Pubkey,          // new
    pub max_amount: u64,
    // ...
}

2 · Set it

In initialize.rs, inside set_inner(RateLimit { ... }):

mint: ctx.accounts.mint.key(),

Goal: every owner gets their own rate limit for each mint, instead of one shared bucket.

Why it matters: with one shared bucket, a single user can send 1,000,000 and block everyone for an hour. That is a free way to freeze a token.

The idea

A PDA's address comes from its seeds. Add the mint and the owner to the seeds, and every mint + owner pair gets a different address, so a different account.

// before: one account for everyone
[b"rate_limit"]

// after: one account per mint, per owner
[b"rate_limit", mint, owner]

The code change is small. The hard part is that these seeds are written in five places, and all five must use the same seeds in the same order. One mismatch and the addresses stop lining up.

1 · transfer_hook.rs

Where the account is loaded. mint and owner are already in the struct:

seeds = [b"rate_limit", mint.key().as_ref(), owner.key().as_ref()],

2 · initialize.rs

Where the account is created. There is no owner field here, so use payer: in the tests, the payer owns the tokens being sent.

seeds = [b"rate_limit", mint.key().as_ref(), payer.key().as_ref()],

Anchor reads fields top to bottom. If mint is declared below rate_limit, the seeds cannot see it and the build fails.

3 · init_extra_account_meta.rs

This is what Token-2022 reads to find the account at transfer time. It cannot use names, only positions in the hook's account list. You fill in the two indexes:

&[
    Seed::Literal { bytes: b"rate_limit".to_vec() },
    Seed::AccountKey { index: ? },   // the mint
    Seed::AccountKey { index: ? },   // the owner
],

4 · tests/helpers/mod.rs

Two functions derive the address. Match the program's seeds exactly:

// in initialize_rate_limit (mint is a Keypair here)
&[b"rate_limit", mint.pubkey().as_ref(), payer.pubkey().as_ref()],

// in build_transfer_with_hook_ix (mint and owner are Pubkeys)
&[b"rate_limit", mint.as_ref(), owner.as_ref()],

5 · tests/test_initialize.rs

This test derives the address on its own. Use the same seeds as initialize_rate_limit. The README lists four places and misses this one.

Goal: an on-chain instruction that moves tokens by calling Token-2022's transfer_checked, with the rate limit still enforced.

Why it matters: so far only wallets send tokens. Real apps like vaults, escrows and games move tokens from inside a program. If your hook breaks for them, nobody can build on your token.

The call chain

A program calling another program is a CPI (cross-program invocation). Here there are two, one inside the other:

wallet
 └─ your program   transfer instruction
     └─ Token-2022   transfer_checked
         └─ hook      transfer_hook, checks the rate limit

Your program must hand Token-2022 the hook's extra accounts too, or Token-2022 cannot run the hook and the transfer fails.

1 · The re-entrancy problem

The repo gives you transfer.rs inside the hook program. But then "your program" and "hook" in the chain above are the same program:

hook program → Token-2022 → hook program   // blocked

The fix: put the transfer instruction in a second program. The hook stays where it is. Now the chain is mover → Token-2022 → hook, and no program appears twice.

2 · Create the second program

anchor new token-mover

This adds programs/token-mover and registers it in Anchor.toml. In its Cargo.toml, copy these from the hook's Cargo.toml:

[features]
idl-build = ["anchor-lang/idl-build", "anchor-spl/idl-build"]

[dependencies]
anchor-spl = "1.2.0"
spl-transfer-hook-interface = "2.1.0"

3 · The accounts

Only the accounts a normal transfer needs:

#[derive(Accounts)]
pub struct TransferWithHook<'info> {
    pub owner: Signer<'info>,
    #[account(mut, token::mint = mint, token::authority = owner)]
    pub source_token: InterfaceAccount<'info, TokenAccount>,
    pub mint: InterfaceAccount<'info, Mint>,
    #[account(mut, token::mint = mint)]
    pub destination_token: InterfaceAccount<'info, TokenAccount>,
    pub token_program: Interface<'info, TokenInterface>,
}

4 · The handler, in four moves

1. Build a plain transfer_checked instruction.
2. List the account infos that go with it.
3. Append the hook's accounts with add_extra_accounts_for_execute_cpi. It reads the extra account meta list and adds exactly what the hook asked for.
4. Invoke Token-2022.

use anchor_lang::solana_program::program::invoke;
use anchor_spl::token_2022::spl_token_2022;
use spl_transfer_hook_interface::onchain::add_extra_accounts_for_execute_cpi;

// Get these from ctx.accounts with .to_account_info()
let (source, mint, destination, owner) = /* ... */;
let hook_program_id = ctx.remaining_accounts[0].key();

// 1. Build
let mut ix = spl_token_2022::instruction::transfer_checked(
    /* token program, source, mint, destination, owner, &[], amount, decimals */
)?;

// 2. List (same order as the instruction's accounts)
let mut infos = vec![source.clone(), mint.clone(), destination.clone(), owner.clone()];

// 3. Append the hook's accounts
add_extra_accounts_for_execute_cpi(
    &mut ix, &mut infos, &hook_program_id,
    source, mint, destination, owner,
    amount, ctx.remaining_accounts,
)?;

// 4. Invoke
invoke(&ix, &infos)?;

pub fn handler<'info>(ctx: Context<'info, TransferWithHook<'info>>, amount: u64) -> Result<()>

5 · Test it

1. Run anchor build. It builds both programs.
2. In setup(), load the new program next to the hook with another svm.add_program(...), pointing at target/deploy/token_mover.so.
3. So the tests can use its types, add it to the hook's [dev-dependencies]: token-mover = { path = "../token-mover", features = ["no-entrypoint"] }.
4. Build the instruction with token_mover::accounts::TransferWithHook and token_mover::instruction::TransferWithHook, the same way the tests build Initialize.
5. Push the remaining accounts, hook program first. Copy the three ix.accounts.push lines from build_transfer_with_hook_ix.

Then write two tests: