Guida Rapida

Visualizza litesvm-loader su crates.io

Installazione

Assicurati di avere tutte le dipendenze necessarie:

cargo add --dev litesvm litesvm-loader solana-keypair solana-signer

Se il tuo test richiama direttamente il programma distribuito, aggiungi anche i crate Solana per istruzioni e transazioni utilizzati dal tuo test:

cargo add --dev solana-instruction solana-message solana-transaction

Il crate litesvm-loader fornisce degli helper per il deployment di programmi tramite il loader BPF aggiornabile all'interno di LiteSVM. Utilizzalo quando il tuo test necessita di program account di proprietà del loader, program data account o del comportamento dell'autorità di aggiornamento, invece di inserire direttamente un programma con svm.add_program(...).

Deployment Aggiornabile

Crea l'account buffer del loader
Scrive i byte del programma in blocchi
Distribuisce il program account finale con il loader BPF aggiornabile
Utilizza il keypair del programma fornito come ID del programma

Gestione dell'Autorità di Aggiornamento - Modifica l'autorità di aggiornamento per un programma già distribuito - Supporta l'assegnazione di una nuova autorità - Supporta il passaggio di None per rendere il programma immutabile

Stato Reale del Loader - Esercita lo stesso modello di account del loader che il tuo programma vede on-chain - Consente ai test di ispezionare il program account e il program data account - Aiuta a individuare errori nascosti dall'inserimento diretto del programma

Per la maggior parte dei test, svm.add_program(program_id, program_bytes) rimane il modo più rapido e semplice per caricare un programma. Usa litesvm-loader quando il layout dell'account loader o l'autorità di aggiornamento fanno parte di ciò che devi testare.

Esempio Rapido

Ecco un esempio completo che distribuisce un programma tramite l'upgradeable loader e poi ruota la sua autorità:

use litesvm::LiteSVM;
use litesvm_loader::{deploy_upgradeable_program, set_upgrade_authority};
use solana_keypair::Keypair;
use solana_signer::Signer;

#[test]
fn test_upgradeable_deployment() {
    let mut svm = LiteSVM::new();

    let payer = Keypair::new();
    svm.airdrop(&payer.pubkey(), 10_000_000_000).unwrap();

    // Use the keypair that should own the program ID.
    // For Anchor programs, this is usually target/deploy/<program>-keypair.json.
    let program = Keypair::new();
    let program_bytes = include_bytes!("../target/deploy/my_program.so");

    deploy_upgradeable_program(&mut svm, &payer, &program, program_bytes).unwrap();

    let program_account = svm.get_account(&program.pubkey()).unwrap();
    assert!(program_account.executable);

    let new_authority = Keypair::new();
    set_upgrade_authority(
        &mut svm,
        &payer,
        &program.pubkey(),
        &payer,
        Some(&new_authority.pubkey()),
    )
    .unwrap();
}

Scelta del keypair del Programma

deploy_upgradeable_program usa l'argomento program_kp come indirizzo del programma. Se il tuo programma dichiara un ID fisso, carica il keypair di deploy generato invece di crearne uno casuale:

use solana_keypair::read_keypair_file;

let program = read_keypair_file("target/deploy/my_program-keypair.json").unwrap();
deploy_upgradeable_program(&mut svm, &payer, &program, program_bytes).unwrap();

Invocazione del Programma Distribuito

Dopo la distribuzione, chiama il programma nello stesso modo in cui chiameresti qualsiasi programma caricato con LiteSVM. Costruisci un'istruzione per il tuo programma, firma la transazione e inviala tramite la stessa istanza LiteSVM:

use solana_instruction::Instruction;
use solana_message::Message;
use solana_transaction::Transaction;

let instruction = Instruction::new_with_bytes(
    program.pubkey(),
    &[],  // instruction data for your program
    vec![], // account metas for your program
);

let message = Message::new(&[instruction], Some(&payer.pubkey()));
let tx = Transaction::new(&[&payer], message, svm.latest_blockhash());

svm.send_transaction(tx).unwrap();

Componenti Principali

deploy_upgradeable_program

Argomento	Descrizione
`svm`	Istanza `LiteSVM` mutabile che riceve il programma distribuito
`payer_kp`	Pagatore delle commissioni e autorità di aggiornamento iniziale
`program_kp`	keypair la cui chiave pubblica diventa l'ID del programma
`program_bytes`	Byte del programma SBF compilato, solitamente da `target/deploy/*.so`

deploy_upgradeable_program crea un buffer per il loader, scrive i byte del programma in blocchi da 512 byte e distribuisce il programma con spazio per futuri aggiornamenti.

set_upgrade_authority

Argomento	Descrizione
`svm`	Istanza `LiteSVM` mutabile contenente il programma distribuito
`from_keypair`	Pagatore delle commissioni e autorità firmataria per la transazione
`program_address`	ID del programma la cui autorità deve cambiare
`current_authority_keypair`	keypair dell'autorità di aggiornamento corrente
`new_authority_address`	Nuovo indirizzo dell'autorità, o `None` per rendere il programma immutabile

Nell'implementazione corrente dell'helper, la transazione generata viene firmata da from_keypair. Passa l'autorità corrente come from_keypair, oppure mantieni il pagante e l'autorità corrente uguali, quando si cambia l'autorità di aggiornamento.

Flussi di lavoro comuni

Distribuire con l'ID programma dichiarato

use solana_keypair::read_keypair_file;

let program = read_keypair_file("target/deploy/my_program-keypair.json").unwrap();
let program_bytes = include_bytes!("../target/deploy/my_program.so");

deploy_upgradeable_program(&mut svm, &payer, &program, program_bytes).unwrap();

Rendere un programma immutabile

set_upgrade_authority(
    &mut svm,
    &payer,
    &program.pubkey(),
    &payer,
    None,
)
.unwrap();

Risoluzione dei problemi

Errori comuni

Errore	Causa	Soluzione
`ProgramAccountNotFound` o errori di istruzione con l'ID errato	Il deployment ha utilizzato un `Keypair` casuale mentre il programma si aspetta un ID dichiarato	Leggi `target/deploy/<program>-keypair.json` e passa quel keypair a `deploy_upgradeable_program`
`InsufficientFunds`	Il pagante non ha abbastanza lamport per il buffer del loader e i program account	Esegui un airdrop di altri lamport prima del deployment
`MissingRequiredSignature` durante il cambio di autorità	L'autorità corrente non ha firmato la transazione	Passa l'autorità corrente come `from_keypair`, oppure mantieni il pagante e l'autorità corrente come lo stesso keypair
Il deployment del programma è più lento del previsto	Il deployment del loader scrive i byte tramite istruzioni reali del loader	Usa `svm.add_program(...)` quando non hai bisogno del comportamento dello stato del loader o dell'autorità di aggiornamento