El Punto de Entrada y Despacho

El punto de entrada es la única superficie RPC de tu programa. Dispatch analiza instruction_data, valida el contexto y enruta a los manejadores con semántica de error consistente.

Receta

entrypoint!(process_instruction);
 
let ix = MyInstruction::try_from_slice(data)?;
match ix { /* ... */ }

Cuándo usar esto:

• Al construir programas nativos sin el despacho de Anchor.
• Al añadir una nueva variante de instrucción a un programa existente.
• Al auditar el análisis de instrucciones en busca de ambigüedad.

Ejemplo Funcional

use borsh::BorshDeserialize;
use solana_program::{account_info::AccountInfo, entrypoint, entrypoint::ProgramResult, pubkey::Pubkey};
 
entrypoint!(process_instruction);
 
#[derive(BorshDeserialize)]
pub enum MyInstruction { Init, Increment }
 
pub fn process_instruction(program_id: &Pubkey, accounts: &[AccountInfo], data: &[u8]) -> ProgramResult {
    if data.is_empty() { return Err(ProgramError::InvalidInstructionData); }
    let ix = MyInstruction::deserialize(&mut &data[..]).map_err(|_| ProgramError::InvalidInstructionData)?;
    match ix {
        MyInstruction::Init => init(program_id, accounts),
        MyInstruction::Increment => increment(program_id, accounts),
    }
}

Lo que esto demuestra:

• Guardia de datos vacíos antes de la deserialización.
• Mapeo de errores de análisis a InvalidInstructionData.
• Los manejadores reciben program_id para la derivación de PDA.

Análisis Profundo

Cómo Funciona

• El runtime pasa los bytes crudos de la instrucción de la transacción.
• El discriminante de la enumeración es el primer byte serializado, a menos que se utilicen etiquetas manuales.
• Cada manejador es responsable de la iteración de cuentas para su subconjunto.

Estilos de Despacho

Notas de Rust

// Mantén los manejadores ligeros; delega las comprobaciones compartidas a los validadores.

Trampas Comunes

• Datos vacíos ambiguos - Tratados como una enumeración vacía válida en algunos diseños. Solución: Rechazar data.is_empty() cuando no existe una instrucción predeterminada.
• Reordenamiento de variantes - Rompe los clientes silenciosamente. Solución: Añadir variantes solo al final; versionar los cambios que rompen la compatibilidad.
• Brazos de match extensos - Los manejadores grandes oscurecen el rastro de auditoría. Solución: Una función por instrucción.
• Falta program_id - Los manejadores no pueden verificar PDAs. Solución: Pasar program_id a través de todas las rutas.
• unwrap sin verificar en slice - Pánicos por longitud incorrecta. Solución: Usar el mapeo de Result de deserialize.

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de Programas Nativos - Estructura
• Serialización/Deserialización de Datos de Instrucción - Diseños
• Conceptos Básicos de CPI - Llamar a otros

Versiones de la Pila: Esta página fue 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, y LiteSVM 0.6.x.