Finish the escrow, without a framework.

When you finish this: your own copy of the assignment on GitHub and on your machine, with the Solana build tools installed.

1. Open github.com/decentra1ized/solana-fall-pescrow 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-pescrow.git
cd solana-fall-pescrow

Tools this repo expects

Crates this repo pins

Push after each challenge, so your progress is saved:

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

When you finish this: the shipped Make test passes on the untouched code. Prove this before changing anything.

# 1. Compile the on-chain program to target/deploy/escrow.so
cargo build-sbf

# 2. Run the LiteSVM tests (they load the .so from step 1)
cargo test -- --nocapture

You should see one passing test and its compute usage:

Make transaction successful
CUs Consumed: ~30000
test tests::tests::test_make_instruction ... ok

When you finish this: you can explain how an instruction reaches its handler, and how the escrow account stores its data without any serialization library.

1 · lib.rs, the entrypoint

entrypoint!(process_instruction);
declare_id!("4ibrEMW5F6hKnkW4jVedswYv6H6VtwPN6ar6dvXDN1nT");

pub fn process_instruction(
    program_id: &Address,
    accounts: &mut [AccountView],
    instruction_data: &[u8],
) -> ProgramResult {
    if program_id != &ID {
        return Err(ProgramError::IncorrectProgramId);
    }

    // First byte = which instruction. The rest = that instruction's payload.
    let (discriminator, data) = instruction_data
        .split_first()
        .ok_or(ProgramError::InvalidInstructionData)?;

    match EscrowInstructions::try_from(discriminator)? {
        EscrowInstructions::Make => instructions::process_make_instruction(accounts, data)?,
        // TODO (challenge): EscrowInstructions::Take and EscrowInstructions::Cancel
        _ => return Err(ProgramError::InvalidInstructionData),   // ← Take / Cancel land here today
    }
    Ok(())
}

• entrypoint! is Pinocchio's macro. It parses the runtime input into &mut [AccountView] without the allocations and copies of the standard SDK path. Combined with explicit validation and compact instruction data, that can significantly reduce compute.
• The slice is mutable because in 0.11 everything that changes an account in place — set_lamports, close, try_borrow_mut — takes &mut self. Your take.rs and cancel.rs handlers must take &mut [AccountView] too.
• There is no Anchor-style 8-byte discriminator. We use one byte, so the instruction data stays smaller.
• The _ => arm is where your Take and Cancel calls will go.

2 · instructions/mod.rs, the enum

pub enum EscrowInstructions {
    Make = 0,
    Take = 1,
    Cancel = 2,
    MakeV2 = 3,
}

impl TryFrom<&u8> for EscrowInstructions { /* 0 → Make, 1 → Take, 2 → Cancel, 3 → MakeV2, _ → error */ }

Take and Cancel already have their discriminators reserved, 1 and 2. Your test code will put that byte first in instruction_data.

3 · state/escrow.rs, zero-copy state

This is the most "Pinocchio" part of the codebase. There is no Borsh, no serialize() or deserialize(). The struct is the bytes.

#[repr(C)]
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct Escrow {
    maker: [u8; 32],
    mint_a: [u8; 32],
    mint_b: [u8; 32],
    amount_to_receive: [u8; 8],   // stored as raw LE bytes, not u64
    amount_to_give: [u8; 8],      // ↑ keeps align_of::<Escrow>() == 1
    pub bump: u8,
}

impl Escrow {
    pub const LEN: usize = core::mem::size_of::<Self>();   // 113. Let the compiler count

    /// Borrow the account data as a typed, mutable `Escrow` view.
    pub fn load_mut(account: &mut AccountView) -> Result<RefMut<'_, Self>, ProgramError> {
        let data = account.try_borrow_mut()?;
        if data.len() != Escrow::LEN { return Err(ProgramError::InvalidAccountData); }
        if (data.as_ptr() as usize) % core::mem::align_of::<Self>() != 0 {
            return Err(ProgramError::InvalidAccountData);
        }
        // SAFETY: #[repr(C)], alignment 1, and the length check above make the cast sound.
        Ok(RefMut::map(data, |bytes| unsafe { &mut *(bytes.as_mut_ptr() as *mut Self) }))
    }

    pub fn amount_to_give(&self) -> u64 { u64::from_le_bytes(self.amount_to_give) }
    pub fn set_amount_to_give(&mut self, amount: u64) { self.amount_to_give = amount.to_le_bytes(); }
    // ... same pattern for every field
}

• #[repr(C)] pins the field order and layout so we can reinterpret the account's byte buffer as &mut Escrow with a pointer cast. Writing to the struct writes straight into the account.
• The u64s are stored as [u8; 8] on purpose. A real u64 field would force 8-byte alignment, and account data buffers are not guaranteed to be aligned. Byte arrays have alignment 1, so the cast is always sound.
• The getters and setters do the little-endian conversion on the way in and out. You will use escrow.maker(), escrow.mint_b(), escrow.amount_to_receive() and escrow.bump heavily in Take and Cancel.
• load_mut returns a RefMut<Escrow>, not a bare &mut Escrow. RefMut::map re-types the guard from [u8] to Escrow without releasing it, so the account's borrow flag stays set for as long as the view lives. Use it through DerefMut exactly like a &mut Escrow.

When you finish this: you know the seven moves in make.rs. Take and Cancel reuse five of them.

1 · Unpack accounts by position

No names, no #[account] attributes. The client must pass them in exactly this order.

let [
    maker,                          // 0  signer, pays for everything
    mint_a,                         // 1  the token being deposited
    mint_b,                         // 2  the token the maker wants back
    escrow_account,                 // 3  PDA ["escrow", maker], to be created
    maker_ata,                      // 4  maker's token account for mint A (source)
    escrow_ata,                     // 5  vault: ATA(owner = escrow PDA, mint A), to be created
    system_program,                 // 6
    token_program,                  // 7
    _associated_token_program @ ..  // 8
] = accounts else {
    return Err(ProgramError::NotEnoughAccountKeys);
};

Because accounts is &mut [AccountView], each binding here is a &mut AccountView. CPI structs want &AccountView, and Rust reborrows automatically, so you pass them as-is.

2 · Validate the maker's token account

Anchor's token::authority = maker, token::mint = mint_a constraints, done by hand:

{
    let maker_ata_state = pinocchio_token::state::Account::from_account_view(maker_ata)?;
    if maker_ata_state.owner() != maker.address() { return Err(ProgramError::IllegalOwner); }
    if maker_ata_state.mint()  != mint_a.address() { return Err(ProgramError::InvalidAccountData); }
}

3 · Parse instruction data

Layout after the discriminator byte: [amount_to_receive: u64 LE][amount_to_give: u64 LE]. No bump — the program derives it itself in step 4.

const MAKE_DATA_LEN: usize = 16;   // 8 + 8

if data.len() < MAKE_DATA_LEN {
    return Err(ProgramError::InvalidInstructionData);
}
let amount_to_receive = u64::from_le_bytes(data[0..8].try_into().unwrap());
let amount_to_give    = u64::from_le_bytes(data[8..16].try_into().unwrap());

if !maker.is_signer() {
    return Err(ProgramError::MissingRequiredSignature);
}

from_le_bytes on a slice is the idiomatic way to read an integer out of instruction data: no alignment concerns, no unsafe, and the length check up front means a short payload fails cleanly instead of reading out of bounds.

4 · Derive the canonical bump, and verify the PDA

Anchor's seeds = [b"escrow", maker.key().as_ref()], bump constraint. Make derives the canonical bump on-chain and stores it in the escrow in step 5. It never accepts a bump from the client.

let (escrow_account_pda, bump) =
    Address::find_program_address(&[b"escrow", maker.address().as_ref()], &crate::ID);
if escrow_account_pda != *escrow_account.address() {
    return Err(ProgramError::InvalidSeeds);
}

Return an error rather than assert_eq!. A panic surfaces to the client as a generic "program failed to complete", while InvalidSeeds says exactly what went wrong.

5 · Create the escrow account, signed by the PDA

init in Anchor terms.

let bump_bytes = [bump];
let seed  = [Seed::from(b"escrow"), Seed::from(maker.address().as_array()), Seed::from(&bump_bytes)];
let seeds = Signer::from(&seed);

// Refuse to overwrite an escrow that already exists for this maker.
if escrow_account.owned_by(&crate::ID) {
    return Err(ProgramError::AccountAlreadyInitialized);
}

CreateAccount {
    from: maker,
    to: escrow_account,
    lamports: Rent::get()?.try_minimum_balance(Escrow::LEN)?,
    space: Escrow::LEN as u64,
    owner: &crate::ID,
}.invoke_signed(&[seeds.clone()])?;

// Scoped so the RefMut guard on the escrow data is released before the CPIs below.
{
    let mut escrow_state = Escrow::load_mut(escrow_account)?;
    escrow_state.set_maker(maker.address());
    escrow_state.set_mint_a(mint_a.address());
    escrow_state.set_mint_b(mint_b.address());
    escrow_state.set_amount_to_receive(amount_to_receive);
    escrow_state.set_amount_to_give(amount_to_give);
    escrow_state.bump = bump;
}

Note the shape: an early return on the "already exists" case, then the happy path straight down the function. Guard clauses read better than nesting the whole instruction inside an if, and AccountAlreadyInitialized tells the client more than IllegalOwner would.

6 · Create the vault

An ATA whose wallet is the escrow PDA. Because the PDA is the owner, only this program, via invoke_signed, can ever move tokens out of it.

pinocchio_associated_token_account::instructions::Create {
    funding_account: maker,
    account: escrow_ata,
    wallet: escrow_account,
    mint: mint_a,
    token_program,
    system_program,
}.invoke()?;

7 · Deposit

A plain SPL Token transfer, signed by the maker who signed the transaction. So invoke(), not invoke_signed().

pinocchio_token::instructions::Transfer {
    from: maker_ata,
    to: escrow_ata,
    authority: maker,
    multisig_signers: &[] as &[&AccountView],   // no multisig here; the type still has to be spelled out
    amount: amount_to_give,
}.invoke()?;

multisig_signers is new in pinocchio-token 0.6 and there is no Default to lean on, so every Transfer and CloseAccount you write needs it. The as &[&AccountView] cast is there so the generic parameter can be inferred from an empty slice.

Done. Three CPIs, about 30k CU total.

How the test drives it

setup() creates a LiteSVM, overrides the Rent sysvar, airdrops a payer, and loads target/deploy/escrow.so. Then test_make_instruction:

1. Creates two mints, A and B, with 6 decimals.
2. Creates the maker's ATA for A and mints 1,000 A into it.
3. Derives the escrow PDA with Pubkey::find_program_address(&[b"escrow", maker], &PROGRAM_ID) and the vault with get_associated_token_address(&escrow, &mint_a).
4. Builds the instruction data [0u8, amount_to_receive LE, amount_to_give LE] and the 9 AccountMetas in the order from step 1. The test still calls find_program_address to know the escrow address, and to check the stored bump afterwards, but it does not send the bump.
5. Sends the transaction and prints CU usage.
6. Reads the accounts back and asserts the vault holds 500 A, the maker's ATA dropped to 500 A, and the escrow's 113 bytes contain the maker, both mints, both amounts and the bump.

The one line in setup() you must not delete

let mut svm = LiteSVM::new();

// LiteSVM 0.9 still ships the pre-SIMD-0194 Rent sysvar. Match the live cluster.
#[allow(deprecated)]
svm.set_sysvar(&solana_rent::Rent {
    lamports_per_byte_year: 6960,
    exemption_threshold: 1.0,
    burn_percent: 50,
});

Goal: Bob sees Alice's escrow, 500 A for 100 B, and calls Take. In one atomic transaction, 100 B moves from Bob to Alice, 500 A moves from the vault to Bob, and the vault and escrow accounts are closed with their rent refunded to Alice.

Why it matters: without Take, the escrow is a one-way deposit box. This is the instruction that makes it a trade.

Instruction data

Just the discriminator, 1. Everything else is already in the escrow account.

Accounts, suggested order

1 · Destructure and check the signer

Your handler takes accounts: &mut [AccountView], same as process_make_instruction. Destructure with the same let [ ... ] = accounts else { ... } pattern, with the twelve accounts above, so every binding is already a &mut AccountView. Then check taker.is_signer().

2 · Load the escrow state, and trust it only after checking the owner

Escrow::load_mut(escrow_account)? gives you a RefMut<Escrow>. Before trusting anything in it, verify escrow_account.owned_by(&crate::ID). Otherwise anyone could pass a fake account with a fake maker.

3 · Cross-check the passed accounts against the state

maker.address() must equal escrow.maker(), and the two mints must match escrow.mint_a() and escrow.mint_b(). Copy amount_to_receive and bump into locals now, then end the block so the borrow drops. You are about to CPI with escrow_account as a signer, and a live borrow will fail.

let (amount_to_receive, bump) = {
    let escrow = Escrow::load_mut(escrow_account)?;
    if escrow.maker()  != *maker.address()  { return Err(ProgramError::InvalidAccountData); }
    if escrow.mint_a() != *mint_a.address() { return Err(ProgramError::InvalidAccountData); }
    if escrow.mint_b() != *mint_b.address() { return Err(ProgramError::InvalidAccountData); }
    (escrow.amount_to_receive(), escrow.bump)
};   // ← RefMut guard dropped here

4 · Re-derive the PDA

derive_address(&[b"escrow", maker.address().as_ref(), &[bump]], None, &crate::ID.to_bytes()), from pinocchio_pubkey, must equal escrow_account.address(). The bump is the canonical one Make stored, so this is a single hash with no loop. It is what proves the escrow belongs to this maker with this bump.

Do not call find_program_address here. Make already paid for the search and wrote the answer into state; repeating it burns CU on every Take.

5 · Validate the vault

Load it with pinocchio_token::state::Account::from_account_view, check owner() == escrow_account.address() and mint() == mint_a.address(), read amount() into a local. That is how much A the taker will receive. Drop the borrow.

6 · Make sure the destination ATAs exist

taker_ata_a and maker_ata_b may not have been created yet. Use pinocchio_associated_token_account::instructions::CreateIdempotent, which is safe to call if they already exist, with taker as the funding account. Then validate taker_ata_b the same way Make validated maker_ata: owner = taker, mint = mint_b.

pinocchio_associated_token_account::instructions::CreateIdempotent {
    funding_account: taker,
    account: taker_ata_a,
    wallet: taker,
    mint: mint_a,
    token_program,
    system_program,
}.invoke()?;
// and again for maker_ata_b with wallet: maker, mint: mint_b

7 · CPI #1, taker pays maker

Transfer amount_to_receive of mint B from taker_ata_b to maker_ata_b. The authority is the taker, who signed the transaction, so this is a plain invoke().

pinocchio_token::instructions::Transfer {
    from: taker_ata_b,
    to: maker_ata_b,
    authority: taker,
    multisig_signers: &[] as &[&AccountView],
    amount: amount_to_receive,
}.invoke()?;   // plain invoke: the taker signed the transaction

8 · Build the PDA signer, then CPI #2, vault pays taker

The vault's authority is the escrow PDA, not any wallet, so this transfer must be invoke_signed with a Signer built from the same three seeds Make used: b"escrow", the maker's address, and the bump. The bump comes from state; you never recompute it with find_program_address here.

Move vault_amount — the balance you read in step 5, not amount_to_give from state — out of the vault and into taker_ata_a.

let bump_bytes = [bump];
let seed   = [Seed::from(b"escrow"), Seed::from(maker.address().as_array()), Seed::from(&bump_bytes)];
let signer = Signer::from(&seed);

pinocchio_token::instructions::Transfer {
    from: vault,
    to: taker_ata_a,
    authority: escrow_account,
    multisig_signers: &[] as &[&AccountView],
    amount: vault_amount,
}.invoke_signed(&[signer.clone()])?;

9 · CPI #3, close the vault

An empty token account still holds rent. Close it with the token program's CloseAccount, again signed by the PDA, and send the lamports to the maker, who paid for it.

10 · Close the escrow account, by hand

The escrow is owned by this program, so there is no CPI for it. Two moves, in this order: add its lamports to the maker's balance and zero its own, then call close(). Skip the lamport move and the runtime rejects the instruction as unbalanced.

AccountView::close zeroes the account's data length, lamports and owner in one go. Both set_lamports and close take &mut self — that is why the accounts slice is mutable. close fails with AccountBorrowFailed if you still hold a borrow on the escrow data, which is another reason to copy the fields out in step 3.

// 9 · the vault is an SPL token account, so the token program closes it
pinocchio_token::instructions::CloseAccount {
    account: vault,
    destination: maker,
    authority: escrow_account,
    multisig_signers: &[] as &[&AccountView],
}.invoke_signed(&[signer.clone()])?;

// 10 · the escrow is ours, so we close it ourselves
maker.set_lamports(maker.lamports() + escrow_account.lamports());
escrow_account.set_lamports(0);
escrow_account.close()?;

11 · Wire it up

1. In instructions/mod.rs: pub mod take; pub use take::*;
2. In lib.rs, replace the _ => arm with a real one for EscrowInstructions::Take.
3. cargo build-sbf. It must compile before you touch the tests.

Goal: Alice changes her mind before anyone takes the deal. She calls Cancel. The 500 A go back to her, the vault and escrow are closed, and rent is refunded to her.

Why it matters: without Cancel, a deposit nobody takes is locked forever. With a wrong Cancel, anyone can drain any escrow. This is the shortest instruction and the easiest to get dangerously wrong.

Instruction data

Just the discriminator, 2.

Accounts, suggested order

The steps

1. Destructure. Check maker.is_signer().
2. Load escrow state with Escrow::load_mut, verify program ownership, verify escrow.maker() == maker.address() and escrow.mint_a() == mint_a.address(). Copy out bump, drop the guard.
3. Re-derive and check the PDA.
4. Validate the vault: owner = escrow PDA, mint = mint A. Read its balance, drop the borrow. Validate maker_ata_a: owner = maker, mint = mint A.
5. Build the PDA signer.
6. Transfer { from: vault, to: maker_ata_a, authority: escrow_account, multisig_signers: &[] as &[&AccountView], amount: vault_amount }.invoke_signed(...)
7. CloseAccount { account: vault, destination: maker, authority: escrow_account, multisig_signers: &[] as &[&AccountView] }.invoke_signed(...)
8. Close the escrow account by hand, same as Take step 10.
9. Wire up cancel.rs in mod.rs and lib.rs. Build.

Goal: four new LiteSVM tests. Two happy paths that read state back, and two negative tests that must fail for the right reason.

Why it matters: a Take that "works" but leaves the escrow open, or a Cancel that a stranger can call, both pass a test that only checks the transaction succeeded.

1 · Factor the Make setup into a helper

Every test starts the same way: two mints, a funded maker ATA, a Make transaction. Pull that out of test_make_instruction into a function that returns what the next steps need: the svm, the maker, both mints, the escrow PDA and bump, and the vault address.

2 · test_take_instruction

1. Run the Make helper.
2. Create a second keypair, taker. Airdrop it SOL. Create taker_ata_b and mint 100 B into it.
3. Derive taker_ata_a and maker_ata_b with get_associated_token_address. Do not create them. Your program does that with CreateIdempotent.
4. Build the instruction: data vec![1u8], the twelve AccountMetas in the order from challenge 1, signed by the taker.
5. Send it, print compute_units_consumed.

Then assert:

3 · test_cancel_instruction

After Make, send Cancel signed by the maker: data vec![2u8], the six accounts from challenge 2. Assert the maker's ATA is back to 1,000 A and both PDA accounts are gone.

4 · Two negative tests

let result = svm.send_transaction(transaction);
assert!(result.is_err(), "a stranger must not be able to cancel");

// then prove nothing moved
let vault_acc = svm.get_account(&vault).unwrap();
let vault_state = spl_token_2022::state::Account::unpack(&vault_acc.data).unwrap();
assert_eq!(vault_state.amount, amount_to_give);

5 · Definition of done

• src/instructions/take.rs implemented and wired into mod.rs and lib.rs.
• src/instructions/cancel.rs implemented and wired.
• cargo build-sbf succeeds with no new unsafe. The only one in the codebase is the pointer cast in Escrow::load_mut; you should not need another.
• cargo test runs Make → Take, Make → Cancel, and at least the two negative tests above, all green.
• Every test prints compute_units_consumed, like the Make test does, and you have compared Take and Cancel against Make's ~30k. There is no fixed budget to hit, but a number far above Make's is worth a look at how many CPIs you are making.

Pinocchio cheat sheet

Quick reference for the APIs used in this repo: pinocchio = 0.11.2, pinocchio-token = 0.6.0.