PDAs no Anchor

Program Derived Addresses (PDAs) não possuem chave privada; seu programa assina por elas com seeds e bump via invoke_signed ou CPI with_signer.

Receita

#[account(
    seeds = [b"escrow", maker.key().as_ref()],
    bump,
)]
pub escrow: Account<'info, Escrow>,

Quando usar: O programa precisa custodiar ativos ou armazenar estado canônico em um endereço determinístico.

Exemplo prático

use anchor_lang::prelude::*;
 
#[account]
#[derive(InitSpace)]
pub struct Escrow {
    pub maker: Pubkey,
    pub escrow_id: u64,
    pub bump: u8,
}
 
// `escrow_id` é um argumento da instrução, então a struct de contas deve
// declará-lo com #[instruction(..)] antes que as seeds possam referenciá-lo.
#[derive(Accounts)]
#[instruction(escrow_id: u64)]
pub struct InitEscrow<'info> {
    #[account(
        init,
        payer = maker,
        space = 8 + Escrow::INIT_SPACE,
        seeds = [b"escrow", maker.key().as_ref(), escrow_id.to_le_bytes().as_ref()],
        bump,
    )]
    pub escrow: Account<'info, Escrow>,
    #[account(mut)]
    pub maker: Signer<'info>,
    pub system_program: Program<'info, System>,
}
 
pub fn init_escrow(ctx: Context<InitEscrow>, escrow_id: u64) -> Result<()> {
    let escrow = &mut ctx.accounts.escrow;
    escrow.maker = ctx.accounts.maker.key();
    escrow.escrow_id = escrow_id;
    // O Anchor NÃO persiste o bump para você - escreva-o você mesmo.
    escrow.bump = ctx.bumps.escrow;
    Ok(())
}

O que isso demonstra:

• Seeds + ID do programa determinam o endereço da PDA
• bump encontra o bump canônico fora da curva; ctx.bumps.escrow o expõe
• Escrow::INIT_SPACE só existe por causa de #[derive(InitSpace)]
• Seeds que referenciam um argumento de instrução precisam de #[instruction(..)]
• Armazene o bump na conta para verificações posteriores mais baratas
• PDAs não podem ser do tipo Signer

Aprofundamento

Derivação

Pubkey::find_program_address(seeds, program_id) retorna (endereço, bump). O Anchor encapsula isso em restrições.

Assinatura pelo Programa

Apenas o programa que possui as seeds da PDA pode assinar, a menos que você use um ID de programa externo nas seeds (avançado).

Erros comuns

• Bump fora da curva não armazenado - Custo extra de CU a cada CPI. Correção: Persista o bump no estado.
• Limites de comprimento das seeds - Restrições de dados máximos de seeds. Correção: Mantenha as seeds compactas.
• Padrão de PDA de propriedade do sistema usado incorretamente - Atribua ao programa após a criação. Correção: Use a inicialização do Anchor na PDA.
• Mismatch de seeds entre cliente/servidor - A transação falha. Correção: Compartilhe o construtor de seeds no SDK.
• PDA como Signer<'info> - Compila, mas sempre falha em tempo de execução: uma PDA não tem chave para assinar a transação. Correção: Use Account com uma restrição de seeds e assine apenas dentro de CPIs.

Alternativas

FAQs

Relacionados

• Assinatura com PDAs - Assinatura em CPI
• Seeds & Bump Constraints - Validação
• Noções básicas de PDA - Modelo nativo

Versões da stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x.