Puntos Clave de los PDA en Anchor

Una Dirección Derivada por Programa (PDA) es una clave pública derivada de bytes de semilla y un ID de programa que se encuentra fuera de la curva ed25519, por lo que no tiene clave privada. Tu programa Anchor es el único actor que puede autorizar acciones para esa dirección, demostrando las semillas y el bump al runtime durante una CPI.

Esta página es el mapa conceptual para PDA, Semillas de Firma y Anchor: derivación impulsada por restricciones, almacenamiento de bumps, firma de PDA, patrones de autoridad, derivación del lado del cliente y los modos de fallo que aparecen en producción en Agave 4.1.1.

Resumen

• Anchor convierte los PDA en cuentas validadas y deterministas: las restricciones seeds y bump prueban la identidad de la dirección en cada instrucción, y la misma tupla de semillas es lo que el programa usa más tarde para firmar CPIs.
• Por qué Importa: Las cuentas de depósito en garantía (escrow), bóvedas, acuñaciones (mints), cuentas de configuración y estados por usuario casi siempre residen en PDA. Semillas incorrectas, restricciones faltantes o semillas de firma rotas significan tokens atascados, estados falsificados o deriva silenciosa de direcciones entre el cliente y el programa.
• Conceptos Clave: seeds (semillas), canonical bump (bump canónico), find_program_address / create_program_address, #[account(seeds, bump)], ctx.bumps, stored bump (bump almacenado), CpiContext::new_with_signer, PDA authority (autoridad PDA), client seed parity (paridad de semillas del cliente).
• Cuándo Usar Este Modelo: Diseñar grafos de cuentas de Anchor que necesiten direcciones deterministas, custodia del programa o fragmentación por entidad; conectar clientes TypeScript con @solana/kit 7.0.0; auditar instrucciones que tocan bóvedas o autoridades de acuñación.
• Limitaciones / Compensaciones: Los PDA no pueden ser cuentas Signer normales; las fórmulas de semillas son permanentes una vez que existen las cuentas; las matrices de semillas y la búsqueda de bump consumen CU; los clientes y el código en cadena deben ser byte a byte idénticos en semillas y ID de programa.
• Temas Relacionados: PDAs en Anchor, Firmar con PDA, Almacenar Bumps, Autoridades PDA, Derivación de PDA del Lado del Cliente, Errores Comunes de PDA.

Fundamentos

Los programas de Solana no contienen el estado de la aplicación dentro de su ejecutable. Los registros duraderos residen en cuentas que el programa posee. Un PDA es un tipo especial de dirección para esas cuentas (y para roles de firma puros que nunca contienen datos): se calcula, no se genera a partir de un par de claves.

(address, bump) = find_program_address(seeds, program_id)

find_program_address prueba valores de bump desde 255 hacia abajo hasta que el punto está fuera de la curva. Ese primer valor válido es el bump canónico. create_program_address verifica un candidato con un bump conocido; no busca.

Debido a que no existe una clave privada para una dirección fuera de la curva, una firma de transacción normal no puede autorizar esa clave. Solo un programa que proporcione las semillas y el bump correctos (bajo el ID de programa utilizado en la derivación) puede marcar el PDA como firmante en una instrucción anidada a través de invoke_signed / Anchor with_signer.

En Anchor 0.32.1 declaras esa verificación en lugar de implementarla manualmente:

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

Anchor re-deriva el PDA a partir de esas semillas y declare_id!, luego requiere que la clave de cuenta pasada coincida. bump = account.bump opcional utiliza un byte almacenado para que la validación no vuelva a buscar. Las rutas de inicialización usan init, payer, space, y las mismas semillas para que la cuenta se cree en la dirección derivada en un solo paso.

Un PDA no es un Signer<'info> en la estructura de cuentas. Los firmantes de par de claves prueban su presencia con una firma de transacción; los PDA prueban su presencia con semillas. Usa Account, SystemAccount u otros envoltorios tipados con seeds / bump, y firma solo al emitir una CPI.

Mecánicas e Interacciones

Restricciones como la verdad en cadena

Cada instrucción que toca un PDA debe reafirmar las semillas. Los clientes eligen qué clave pública pasar; sin restricciones, un atacante puede sustituir una cuenta parecida que tu manejador trata como la bóveda canónica o el registro de usuario.

Mantén los componentes de las semillas pequeños y estables: un prefijo estático (b"vault"), una clave pública distintiva y quizás un ID en little-endian. Las pilas de semillas largas o variables queman CU e invitan a errores del cliente. Documenta la tupla de semillas junto al tipo de cuenta para que Rust, las pruebas y TypeScript se mantengan alineados.

Almacenar bumps

En la inicialización inicial, Anchor expone el mapa de bump resuelto como ctx.bumps.<nombre_campo>. Escribe eso en los datos de la cuenta:

ctx.accounts.vault.bump = ctx.bumps.vault;

Las instrucciones posteriores usan bump = vault.bump en la restricción y el mismo byte en las semillas de firma CPI. Beneficios:

1. CU: no hay búsqueda repetida de bump en rutas críticas.
2. Determinismo: la CPI siempre usa el bump que hizo que la dirección fuera válida en el momento de la creación.
3. Claridad: un campo es la fuente de verdad para la firma.

No aceptes un bump proporcionado por el cliente como argumento de instrucción para comprobaciones críticas de seguridad. Prefiere el almacenamiento en cadena y las restricciones. Si las cuentas heredadas no tienen un campo de bump, agrega una instrucción de migración que recalcule con find_program_address una vez y escriba el resultado; no inventes un bump.

Consulta Almacenar Bumps para ver patrones y notas de migración.

Firmar con PDA

Cuando el PDA debe autorizar una CPI (transferencia de tokens desde un ATA de bóveda, mint_to, transferencia del sistema de lamports en posesión de un PDA, etc.), construye semillas de firma que coincidan con las semillas de la restricción, con el bump como la semilla final de un byte:

let bump = ctx.accounts.vault.bump;
let seeds: &[&[u8]] = &[b"vault", authority.key().as_ref(), &[bump]];
let signer_seeds = &[seeds];
 
token::transfer(
    CpiContext::new_with_signer(
        ctx.accounts.token_program.to_account_info(),
        token::Transfer {
            from: ctx.accounts.vault_ata.to_account_info(),
            to: ctx.accounts.user_ata.to_account_info(),
            authority: ctx.accounts.vault.to_account_info(),
        },
        signer_seeds,
    ),
    amount,
)?;

El orden y los bytes de las semillas deben coincidir con la inicialización y las restricciones. El metadato de autoridad en la CPI debe ser la información de la cuenta PDA, no una billetera de usuario. Un PDA puede firmar múltiples CPIs en la misma instrucción con las mismas semillas. Un bump incorrecto o una semilla faltante fallan la CPI como una firma faltante (toda la transacción se revierte). Equivalente nativo: invoke_signed. Detalles en Firmar con PDA.

Autoridades PDA

Los programas usan PDA como autoridades cuando el protocolo, no un par de claves humano, debe controlar activos o suministro:

• Bóveda / PDA de depósito en garantía posee un ATA que contiene depósitos; las CPIs de retiro usan las semillas de la bóveda.
• PDA de Tesorería recibe tarifas; las rutas de gasto requieren reglas impuestas por el programa más semillas de firma.
• PDA de autoridad de acuñación acuña recompensas o elementos de juego; opcionalmente, renuncia más tarde estableciendo la autoridad de acuñación en None a través de CPI cuando el diseño congela el suministro.

Siempre restringe las relaciones de acuñación y ATA (token::authority, associated_token::authority, igualdad de claves de acuñación) para que una firma PDA válida no pueda operar sobre la acuñación o cuenta de token incorrecta. Prefiere PDA divididos por mercado, pool o característica en lugar de un PDA de autoridad global: menor radio de explosión si aparece un error en una ruta, y mejor paralelismo de Sealevel cuando diferentes mercados escriben claves diferentes.

Consulta Autoridades PDA.

Derivación del lado del cliente

Los clientes deben pasar las mismas claves públicas que el programa re-derivará. Con @solana/kit 7.0.0, usa getProgramDerivedAddress (o ayudantes generados) con:

1. La dirección del programa de la IDL / declare_id! (no una clave de despliegue aleatoria de un archivo de entorno antiguo).
2. Bytes de semilla idénticos a los de la cadena: prefijos de cadena como bytes ASCII que coincidan con b"...", claves públicas como 32 bytes crudos, enteros como little-endian (paridad to_le_bytes).
3. El mismo orden de semillas.

const [escrowPda] = await getProgramDerivedAddress({
  programAddress: programId,
  seeds: [
    new TextEncoder().encode("escrow"),
    getBytesEncoder().encode(makerAddress),
    // u64 little-endian que coincide con Rust to_le_bytes
    u64ToLeBytes(escrowId),
  ],
});

Comparte constantes o genera constructores de semillas a partir de la IDL para que TypeScript no se desvíe de Rust. Las pruebas de integración deben afirmar que los PDA derivados por el cliente son iguales a las direcciones creadas en las pruebas de Anchor. Consulta Derivación de PDA del Lado del Cliente.

Consideraciones Avanzadas y Aplicaciones

PDA de programas externos. Cuando haces CPI a otro programa que posee un PDA, pasa esa dirección pero no firmes por ella a menos que seas ese programa. seeds::program de Anchor valida los PDA extranjeros contra otro ID de programa. Tu programa solo firma PDA derivados bajo tu ID de programa.

Inicialización vs. Re-inicialización. Las semillas fijan una ranura en el espacio de direcciones. Después de cerrar, las mismas semillas pueden reabrir la misma dirección; diseña las rutas de cierre cuidadosamente si la lógica asume "una vez inicializado, siempre confiable".

Fragmentación y CU. Los PDA por usuario mantienen los bloqueos de escritura disjuntos bajo Sealevel. Mantén la configuración global de solo lectura en rutas críticas. Almacena los bumps, mantén las semillas cortas y simula antes de mainnet: la búsqueda de bump y las pilas de CPI profundas cuestan CU.

Ciclo de vida de la autoridad. Mueve la autoridad de acuñación o congelación a un PDA solo en una inicialización controlada. Dejar una autoridad de acuñación de par de claves después de un despliegue de "bóveda PDA" es un error de seguridad.

Matriz de pruebas. Para cada tipo de PDA: inicialización en el camino feliz, semillas de cliente incorrectas, ID de programa incorrecto, CPI con semillas de firma buenas y malas, y desajuste de autoridad de token. Los casos de fallo se catalogan en Errores Comunes de PDA.

Conceptos Erróneos Comunes

• "Un PDA es solo una cuenta normal con un nombre elegante." Es una dirección fuera de la curva; la identidad y la firma dependen de las semillas y el ID del programa, no de una clave privada.
• "Si paso la clave pública correcta desde el cliente, las restricciones de semillas son opcionales." Sin re-derivación en cadena, el cliente elige la confianza. Los atacantes pasan cuentas parecidas.
• "Los PDA pertenecen a Signer<'info> porque firman CPIs." Los firmantes a nivel de transacción son pares de claves. Los PDA se convierten en firmantes solo para invocaciones anidadas a través de prueba de semillas.
• "Puedo cambiar las fórmulas de semillas en una actualización y mantener las mismas cuentas." Las direcciones están fijadas por las semillas y el ID del programa. Las nuevas fórmulas son nuevas direcciones; planifica la migración.
• "El bump es un secreto." El bump es público y recuperable; la seguridad proviene de la lógica del programa y las restricciones, no de la confidencialidad del bump. Aun así, almacena y reutiliza el bump canónico para CU y consistencia.
• "La endianidad del cliente no importa para las semillas numéricas." to_le_bytes de Rust y los buffers big-endian de JS producen diferentes PDA. Coincide explícitamente con LE.
• "Un PDA de autoridad compartido es más simple y igual de seguro." Más simple hasta que un error agota todos los mercados. Prefiere PDA con ámbito cuando la escala o el aislamiento importan.
• "with_signer es solo para Token." Cualquier CPI que requiera el PDA como firmante (Programa del Sistema, Token, Token-2022, llamados personalizados) necesita semillas de firma.
• "UncheckedAccount está bien para los PDA durante el desarrollo." Es la ruta predeterminada a la falta de comprobaciones de propiedad y semillas. Usa cuentas tipadas con semillas desde el primer borrador.
• "find_program_address en cada CPI es gratis." Es correcto pero cuesta CU; almacena el bump después de la inicialización para rutas críticas.

Preguntas Frecuentes

Relacionados

• PDAs en Anchor - semillas, bump y restricciones de inicialización
• Firmar con PDA - with_signer y porciones de semillas CPI
• Almacenar Bumps - persistencia y reutilización del bump canónico
• Autoridades PDA - bóvedas, tesorerías y autoridades de acuñación
• Derivación de PDA del Lado del Cliente - coincidencia de semillas en TypeScript con kit
• Errores Comunes de PDA - desajustes de semillas, restricciones faltantes, errores de firma

Versiones de la pila: Esta página fue escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1, y @solana/kit 7.0.0.