Defining Instruction Accounts with the `Accounts` Struct

Hello! Welcome back to our exploration of the Anchor framework.

In our last lesson, you learned how to define the schema for your program's on-chain data using the #[account] macro. We covered how this defines the structure of accounts your program owns, how Anchor uses an 8-byte discriminator for type safety, and how to calculate the required space for these accounts.

This lesson addresses the next logical step: how do we tell a specific instruction which accounts it needs and what rules those accounts must follow? This is the heart of Anchor's security model and the focus of today's learning outcome: to specify and validate instruction accounts using an Accounts struct.

Think of the #[account] struct from last lesson as defining a "table schema" in a database. Today, you'll learn to write the "function signature" that specifies which tables (accounts) a particular operation can access and what permissions (e.g., read-only, write) it has.

From Manual Iteration to Declarative Validation

In native Solana development, you had to manually iterate through a flat list of AccountInfo objects passed to your program. You were responsible for checking that you received the correct number of accounts, that they were in the right order, that they were writable if needed, and that the transaction was signed by the right parties. This is tedious and a major source of security vulnerabilities.

Anchor replaces this imperative, error-prone process with a clean, declarative model. You simply declare what you expect, and Anchor generates the validation code for you.

This declarative approach is the purpose of the #[derive(Accounts)] macro. You apply it to a struct where each field represents an account required by your instruction. This struct then becomes the T in the Context<T> parameter of your instruction handler.

// This struct defines all the accounts our `initialize` instruction needs.
#[derive(Accounts)]
pub struct Initialize<'info> {
    // ... fields representing accounts go here ...
}

// Our instruction handler receives the validated accounts in the context.
pub fn initialize(ctx: Context<Initialize>) -> Result<()> {
    // We can now safely access the accounts via ctx.accounts
    // e.g., ctx.accounts.some_account
    Ok(())
}

Let's consult the official Anchor documentation for a formal introduction to this concept.

Defining the Players: Anchor's Account Types

As the documentation explains, the fields in your Accounts struct are not just any Rust types. They are specific Anchor types that encapsulate validation logic. Here are the three most fundamental ones you'll use constantly:

1. Account<'info, T>: Represents a data account owned by your program. The T is a struct you've defined with #[account] (like we did in the last lesson). When Anchor processes this type, it automatically performs several critical checks:

   • Ownership Check: Verifies the account is owned by the currently executing program.
   • Discriminator Check: Verifies the first 8 bytes of the account's data match the discriminator for the struct T.
   • Deserialization: If both checks pass, it deserializes the account data into the T struct for you to use.

2. Signer<'info>: Represents an account that must have signed the transaction. This is the primary way you authorize actions. Anchor simply checks the is_signer flag on the underlying AccountInfo. The data of this account is not read or trusted.

3. Program<'info, T>: Represents another program on the blockchain (e.g., the SystemProgram or the TokenProgram). Anchor verifies that the public key of the account passed in matches the expected program ID for T and that the account is marked as executable.

Setting the Rules: The #[account] Constraint Attribute

You've now seen the main types of accounts. The real power comes from applying constraints to them using the #[account(...)] attribute on each field. This is how you enforce the specific rules for your instruction.

Let's explore some of the most common constraints.

Putting it all Together: An Example

Let's analyze a canonical example that uses the types and constraints we've just learned about. This is the Accounts struct for a typical "initialize" instruction that creates a new data account.

use anchor_lang::prelude::*;

// This is our program-owned data account structure (from the previous lesson)
#[account]
pub struct MyAccount {
    pub data: u64,
}

// This is the Accounts struct for our 'initialize' instruction
#[derive(Accounts)]
pub struct Initialize<'info> {
    // 1. The 'init' constraint
    #[account(
        init, // Tells Anchor to create this account
        payer = user, // The 'user' account below will pay for rent
        space = 8 + 8 // The space to allocate (8 for discriminator + 8 for u64)
    )]
    pub my_account: Account<'info, MyAccount>,

    // 2. The 'mut' constraint on the Signer
    #[account(mut)]
    pub user: Signer<'info>,

    // 3. The System Program
    pub system_program: Program<'info, System>,
}

Let's break down what's happening here when this instruction is called:

1. my_account:

   • init: This is the key constraint. Anchor will make a Cross-Program Invocation (CPI) to the System Program to create a new account.
   • payer = user: It specifies that the user account (defined below) must pay the lamports required for rent. Anchor ensures user has sufficient funds.
   • space = 8 + 8: It tells the System Program to allocate 16 bytes for the new account. This connects directly to what you learned about space calculation in the last lesson.
   • The type Account<'info, MyAccount> ensures that after creation, the account will be owned by our program and its data structure will be prepared for a MyAccount struct.

2. user:

   • Signer<'info>: Anchor validates that this account signed the transaction. This is our authority check.
   • #[account(mut)]: The mut constraint is crucial here. Since this account is the payer, its lamport balance will be debited. Therefore, it must be mutable. If a client submits a transaction where the user account isn't marked as writable, Anchor will reject it.

3. system_program:

   • Program<'info, System>: The init constraint requires the System Program to create the account. We must pass it in so Anchor can use it for the CPI. The Program type validates that the account provided at this position is indeed the official Solana System Program.

This small, declarative struct packs an incredible amount of validation that you would otherwise have to write manually.

#[derive(Accounts)]
pub struct Increment<'info> {
    // The counter account must be mutable to be changed.
    // The `Account` type will check ownership and the discriminator.
    #[account(mut)]
    pub counter: Account<'info, Counter>,

    // The authority must sign the transaction.
    pub authority: Signer<'info>,
}

What Happens When Validation Fails?

The beauty of this system is the automatic error handling. If a client tries to call an instruction with the wrong accounts or without meeting the constraints, the transaction doesn't just fail cryptically. Anchor returns a specific error code that tells you exactly what went wrong.

Conclusion

In this lesson, you've learned to use one of Anchor's most powerful features: the Accounts struct. By moving from manual, imperative checks to a declarative validation model, you eliminate huge amounts of boilerplate code and dramatically improve the security and readability of your programs.

Here are the key takeaways:

• The #[derive(Accounts)] macro is used on a struct to define the set of accounts an instruction requires.
• Each field in the struct uses a specific Anchor Type (Account, Signer, Program) to perform baseline validation.
• The #[account(...)] attribute is used to apply constraints (mut, init, payer, space, etc.) that enforce the rules and logic for your instruction.
• This declarative system provides robust, automatic security checks before your instruction logic even runs.

You now have the tools to define both the data structures (#[account]) and the instruction access patterns (#[derive(Accounts)]).

In the next lesson, we will deepen our understanding of security by exploring more advanced constraints. You'll learn how to implement security checks by applying constraints like signer, mut, and has_one to accounts. We will focus particularly on has_one, which is essential for creating relationships between accounts and ensuring that the signer of a transaction is the authorized user for a specific piece of data.