Busca en todas las páginas de la documentación
Anchor es el framework dominante para escribir programas de Solana en Rust. Se asienta sobre el mismo runtime de Agave que los programas nativos (bytecode SBF, metadatos de cuenta explícitos, unidades de cómputo, CPI), pero genera el pegamento que de otro modo escribirías a mano: discriminadores de instrucciones, dispatch del punto de entrada, comprobaciones declarativas de cuentas, errores tipados, eventos y un IDL que los clientes consumen.
Esta página es el paraguas para anchor-basics: qué es Anchor, cómo el módulo #[program] y las estructuras #[derive(Accounts)] forman la superficie de instrucciones, cómo se organiza un espacio de trabajo, cómo encajan la compilación/despliegue y las pruebas locales, y cómo se compara Anchor con los programas nativos.
#[program], declare las cuentas y restricciones en las estructuras Accounts, luego anchor build / anchor test / anchor deploy envían el binario más el esquema del cliente.declare_id!, #[program], Context<T>, #[derive(Accounts)], restricciones, estado #[account], IDL, Anchor.toml, SBF / .so, nativo vs Anchor.Qué es Anchor
A nivel de runtime, un programa de Solana todavía implementa aproximadamente process_instruction(program_id, accounts, instruction_data). Anchor no cambia ese contrato. Genera el punto de entrada y desempaqueta los datos de la instrucción en manejadores con nombre y argumentos tipados.
Lo que escribes es un espacio de trabajo: crates de Rust bajo programs/, pruebas de TypeScript (u otro) bajo tests/, y Anchor.toml para el clúster, IDs de programas y scripts. El crate del framework es anchor-lang 0.32.1 (más anchor-spl cuando tocas Token/Associated Token).
La promesa del producto de Anchor es triple:
Signer, Account<T>, Program<T>).anchor build emite el IDL JSON para que el código fuera de la cadena y los módulos CPI se mantengan alineados con las instrucciones en cadena.El módulo del programa
use anchor_lang::prelude::*;
declare_id!("Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS");
#[program]
pub mod counter {
use super::*;
pub fn initialize(ctx: Context<Initialize>) -> Result<()> {
ctx.accounts.counter.count = 0;
ctx.accounts.counter.authority = ctx.accounts.authority.key();
Ok(())
}
pub fn increment(ctx: Context<Increment>) -> Result<()> {
ctx.accounts.counter.count = ctx.accounts.counter.count.checked_add(1).unwrap();
Ok(())
}
}declare_id! codifica la clave pública del programa que espera el binario; debe coincidir con el despliegue (usa anchor keys sync después de que cambien las claves del despliegue).#[program] marca el módulo cuyas funciones públicas se convierten en instrucciones.Context<SomeAccounts> (y argumentos de instrucción opcionales), devuelve Result<()>, y muta solo a través de campos de cuenta validados.Los datos de la instrucción no son bytes de formato libre que analizas ad hoc: Anchor deriva discriminadores de 8 bytes y serializa argumentos con Borsh. Los clientes que omiten el IDL (o lo regeneran tarde) fallan de maneras confusas.
La estructura de Cuentas
Cada instrucción nombra una estructura de cuentas con #[derive(Accounts)]. Los tipos de campo y los atributos son el programa de validación.
#[derive(Accounts)]
pub struct Initialize<'info> {
#[account(
init,
payer = authority,
space = 8 + 8 + 32,
seeds = [b"counter", authority.key().as_ref()],
bump
)]
pub counter: Account<'info, Counter>,
#[account(mut)]
pub authority: Signer<'info>,
pub system_program: Program<'info, System>,
}
#[account]
pub struct Counter {
pub count: u64,
pub authority: Pubkey,
}Antes de que se ejecute initialize, Anchor comprueba los firmantes, la mutabilidad, las semillas de PDA, el ID del programa del sistema y que init asigna y otorga la propiedad correctamente. Account<'info, Counter> se deserializa con el discriminador de cuenta de 8 bytes. Los fallos devuelven errores de Anchor en lugar de escrituras parciales.
Estructura del proyecto (mapa mínimo)
workspace/
Anchor.toml # toolchain, programs.<cluster>, scripts
Cargo.toml # workspace members = ["programs/*"]
programs/my_program/
Cargo.toml # anchor-lang = "0.32.1"
src/lib.rs
tests/*.ts
target/deploy/*.so # después de compilar
target/idl/*.json # después de compilarAnchor.toml fija qué ID de programa se mapea a qué nombre de clúster. El Cargo.toml raíz es un espacio de trabajo de Rust; cada programa es su propio crate. Las pruebas suelen llamar al programa a través de un proveedor (validador local / Surfpool) utilizando el IDL generado.
Compilación, despliegue y flujo de trabajo en una frase
anchor build compila SBF y regenera el IDL; anchor test despliega localmente y ejecuta pruebas; anchor deploy empuja el .so a un clúster; los clientes y consumidores de CPI deben seguir el nuevo IDL y el ID del programa.
Anchor vs nativo (orientación)
Los programas nativos usan entrypoint!, recorrido manual de cuentas y codecs de cliente mantenidos a mano. Anchor genera esa superficie. Pagas algo de tamaño/CU y ganas restricciones más IDL. Los núcleos de liquidación críticos a veces abandonan Anchor; la mayoría de los programas de productos no deberían empezar de forma nativa "por pureza".
Cómo interactúan las piezas de extremo a extremo:
Editar lib.rs (#[program] + Cuentas + estado #[account])
|
v
anchor build --> target/deploy/*.so + target/idl/*.json
|
v
anchor test --> validador local/Surfpool + pruebas TS
|
v
anchor deploy --> programa actualizable en el clúster
|
v
keys sync / IDL publish --> clientes y consumidores de declare_program!Ruta de dispatch en cadena
.so e invoca el punto de entrada generado.Context<T> validando la estructura Accounts.Ok(()) o un error.Contexto es el traspaso
Context<T> contiene accounts: T, program_id, bumps (para las semillas de PDA descubiertas durante la validación) y las cuentas restantes cuando las usas. Los manejadores no deben volver a analizar las listas de AccountInfo desde cero; deben confiar (y solo extender con require!) lo que las restricciones ya han aplicado.
Las restricciones son el límite de seguridad
Atributos comunes:
| Restricción / tipo | Rol |
|---|---|
Signer | Firma de transacción presente |
mut | Meta de cuenta escribible requerida |
init / init_if_needed | Crear (cuidado con esta última) |
seeds + bump | Derivación de PDA y comprobación de dirección |
has_one | Igualdad de campo (p. ej., autoridad almacenada) |
Program<T> | ID de programa conocido (System, Token, …) |
constraint = expr | Invariante booleano personalizado |
El orden importa para la seguridad de init y CPI; trate el orden de validación como parte del diseño, no como un accidente de la lista de atributos. Las reglas de negocio personalizadas pertenecen a las restricciones o a un require! temprano, no a "comprobaremos más tarde si lo recordamos".
Interacciones de configuración del espacio de trabajo
declare_id!, Anchor.toml [programs.*] y la clave del par de despliegue en cadena deben coincidir. Después del despliegue, anchor keys sync reescribe las fuentes/configuración cuando el par de claves es la fuente de verdad..so nuevo sin IDL es cómo las dapps llaman a discriminadores incorrectos.Lado del cliente
Las pruebas y las aplicaciones construyen instrucciones a partir del IDL. @solana/kit 7.0.0 no requiere Anchor específicamente, pero necesita formatos de cableado correctos. La fortaleza de Anchor es producir ese contrato a partir de las mismas macros que generan el programa. Prefiera regenerar clientes tipados en CI cuando el IDL cambie.
Piense en cada función #[program] como un método público versionado. Los discriminadores estables y los órdenes de cuenta estables importan más que los módulos ingeniosos de Rust. Prefiera instrucciones aditivas y layouts de cuenta versionados sobre la reordenación silenciosa de campos.
Cuando cambie el space de la cuenta, planifique instrucciones de realloc o migración; los clientes que tengan layouts antiguos fallarán las comprobaciones de discriminador o deserialización por una buena razón.
Anchor elimina clases enteras de errores (autoridad no firmada, propietario de programa incorrecto en Account<T>, dirección incorrecta del programa del sistema). No inventa tu modelo de amenazas:
UncheckedAccount y por qué?init_if_needed creando una superficie de ataque de reinicialización?La revisión de seguridad todavía se centra en las restricciones, las semillas y los gráficos de CPI, no solo en las matemáticas del manejador.
Un espacio de trabajo puede contener varios crates bajo programs/. Las llamadas entre programas necesitan metadatos de cuenta correctos y, en Anchor 0.32, a menudo declare_program! o tipos compartidos para el llamado. Los límites del framework todavía se componen a través de CPI: un programa de Anchor puede llamar a nativo/Pinocchio si los bytes y las semillas coinciden.
anchor build y confirme o publique los artefactos IDL intencionalmente (la política varía; no los deje accidentales).anchor test en verde en la pila local antes de devnet.| Situación | Preferir |
|---|---|
| MVP, admin, marketplace, lógica estándar de aplicaciones DeFi | Anchor 0.32.1 |
| Fuerte necesidad de clientes impulsados por IDL e iteración rápida | Anchor |
| Techo de CU medido en una instrucción crítica | Optimizar Anchor primero; extraer el núcleo de Pinocchio/nativo si todavía está ajustado |
| Tamaño binario extremo / auditoría desea comprobaciones totalmente explícitas | Nativo o Pinocchio (ver Anchor vs nativo) |
| Sistema mixto | Periferia de Anchor + CPI al núcleo magro |
Mida con transacciones fijas y unitsConsumed; no reescriba frameworks por intuición.
declare_id! es decorativo." El desajuste con el programa desplegado causa fallos en tiempo de ejecución (DeclaredProgramIdMismatch). Sincronice después de cambios de clave.Accounts se ejecuta primero; el manejador asume un Context válido.anchor deploy por sí solo actualiza todos los clientes." El despliegue actualiza el bytecode en cadena; las aplicaciones, los indexadores y los módulos CPI necesitan el IDL y el ID del programa coincidentes.AccountInfo en las cuentas restantes es seguro si la estructura principal es estricta." Las cuentas restantes son una superficie de desvío común; delimítelas y valídalas explícitamente.Un framework de Rust para programas de Solana que genera dispatch de instrucciones, validación declarativa de cuentas, errores/eventos y un IDL a partir de macros sobre el runtime estándar de Agave.
Anchor 0.32.1, Rust 1.91.1, Solana CLI 3.0.10, Agave 4.1.1, y @solana/kit 7.0.0 como la pila de cliente de referencia.
El punto de entrada del programa, la coincidencia del discriminador de instrucción, la deserialización de argumentos y el cableado de cada función pública a su ruta de validación Context<T>.
El argumento del manejador que contiene las cuentas validadas (T), el ID del programa, las semillas de PDA descubiertas durante la validación y las cuentas restantes opcionales.
Construye una lista de cuentas tipada y ejecuta restricciones de nivel de tipo más atributos (signer, mut, owner, seeds, init, expresiones personalizadas) antes de que se ejecute el cuerpo del manejador.
Las referencias a cuentas están vinculadas al ámbito de préstamo de AccountInfo de la instrucción para esa invocación; la vida útil rastrea correctamente ese préstamo de corta duración en Rust.
Account<T> aplica la propiedad del programa y deserializa T con el discriminador de cuenta de Anchor. UncheckedAccount omite estas comprobaciones; debes validar manualmente o estarás expuesto a ataques.
programs/*/src es el crate en cadena; target/deploy contiene el .so; Anchor.toml mapea los nombres de los programas a las claves públicas por clúster; las pruebas y los clientes consumen target/idl.
Un objeto compartido SBF bajo target/deploy/ y JSON IDL bajo target/idl/, además de artefactos de clave relacionados para programas desplegables.
Cambie el código del programa y las cuentas, ejecute anchor build, ejecute anchor test localmente, corrija los fallos, y luego promocione al despliegue en devnet y actualizaciones de cliente antes de mainnet.
Cuando los requisitos medidos de CU o tamaño binario, o las preferencias de auditoría/proceso para una validación totalmente manual, superen la productividad del IDL y las macros; a menudo como una extracción de ruta crítica, no una reescritura completa de la aplicación.
Sí, a través de CPI, cuando los metadatos de cuenta, la propiedad, los layouts de datos y las semillas de firmante de PDA coinciden con lo que espera el llamado.
Sí. Solana CLI 3.0.10 maneja pares de claves, saldos, airdrops, configuración de clúster e inspección de solana program junto con los comandos anchor.
Comience con Conceptos Básicos de Anchor para obtener ejemplos concretos, luego Estructura del Proyecto, La Estructura de Cuentas, El Flujo de Trabajo de Anchor, Compilación y Despliegue, y Anchor vs Nativo.
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.
Revisado por Chris St. John·Última actualización: 15 jul 2026