Cheatcode

I cheatcode sono mutazioni di stato che bypassano il normale flusso delle transazioni. Vengono eseguiti istantaneamente senza consumare un blockhash né pagare commissioni, che è esattamente ciò di cui hai bisogno per la configurazione dei test.

In Rust, i cheatcode si trovano sotto Surfnet::cheatcodes(). In JS, sono metodi direttamente sull'istanza Surfnet.

Finanzia SOL

fundSol / fund_sol imposta il saldo in lamport su qualsiasi account, creando l' account se non esiste.

use surfpool_sdk::{Pubkey, Surfnet};

let surfnet = Surfnet::start().await?;
let cheats = surfnet.cheatcodes();
let wallet = Pubkey::new_unique();

cheats.fund_sol(&wallet, 1_000_000_000)?;

// Fund several accounts in one call.
let bob = Pubkey::new_unique();
let carol = Pubkey::new_unique();
cheats.fund_sol_many(&[(&bob, 2_000_000_000), (&carol, 3_000_000_000)])?;

Finanzia Token

fundToken / fund_token conia token su un wallet calcolando il token account associato, creandolo se necessario e impostando l'importo.

Mint Token-2022

Per impostazione predefinita, fundToken utilizza il classico Token Program SPL. Per i mint Token-2022, passa l'ID del programma Token-2022 (TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb) come argomento finale.

use surfpool_sdk::{Pubkey, Surfnet};

let surfnet = Surfnet::start().await?;
let cheats = surfnet.cheatcodes();

let wallet = Pubkey::new_unique();
let mint: Pubkey = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    .parse()
    .unwrap();

// Classic SPL Token mint.
cheats.fund_token(&wallet, &mint, 5_000_000, None)?;

// Token-2022 mint — pass the program id explicitly.
let token_2022: Pubkey = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb"
    .parse()
    .unwrap();
cheats.fund_token(&wallet, &mint, 5_000_000, Some(&token_2022))?;

// Fund many wallets with the same mint.
let mob = vec![Pubkey::new_unique(), Pubkey::new_unique()];
cheats.fund_token_many(&mob.iter().collect::<Vec<_>>(), &mint, 1_000_000, None)?;

Per derivare l'ATA senza finanziarlo, usa getAta / get_ata:

let ata = cheats.get_ata(&wallet, &mint, None);

Imposta uno Stato Arbitrario per gli Account

Il metodo setAccount scrive lamport, proprietario e byte di dati grezzi per qualsiasi account in una singola chiamata. L'SDK Rust espone inoltre un builder SetAccount per campi più avanzati come rent_epoch e executable.

use surfpool_sdk::cheatcodes::builders::SetAccount;
use surfpool_sdk::{Pubkey, Surfnet};

let surfnet = Surfnet::start().await?;
let cheats = surfnet.cheatcodes();

let address = Pubkey::new_unique();
let owner = Pubkey::new_unique();

// Direct method.
cheats.set_account(&address, 500_000, &[1, 2, 3], &owner)?;

// Builder when you need finer control.
cheats.execute(
    SetAccount::new(address)
        .lamports(500_000)
        .owner(owner)
        .data(vec![1, 2, 3])
        .rent_epoch(0)
        .executable(false),
)?;

Modifica i Campi del Token Account

setTokenAccount aggiorna i campi avanzati di un token account esistente — delegato, stato, autorità di chiusura, importo delegato. Utilizzalo quando fundToken da solo non è sufficiente.

use surfpool_sdk::cheatcodes::builders::SetTokenAccount;
use surfpool_sdk::{Pubkey, Surfnet};

let cheats = Surfnet::start().await?.cheatcodes();

let owner = Pubkey::new_unique();
let mint: Pubkey = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v".parse()?;
let delegate = Pubkey::new_unique();

cheats.execute(
    SetTokenAccount::new(owner, mint)
        .amount(2_000_000)
        .delegate(delegate)
        .delegated_amount(500_000)
        .state("initialized"),
)?;

// Later: clear the delegation.
cheats.execute(SetTokenAccount::new(owner, mint).clear_delegate())?;

Ripristina gli Account allo Stato Upstream

resetAccount elimina qualsiasi modifica locale e recupera nuovamente l'account dall' RPC upstream. Passa includeOwnedAccounts: true per reimpostare anche ogni account posseduto dal target — utile quando si ripristina un programma e tutti i suoi PDA.

Richiede `remoteRpcUrl` per il recupero

Su una Surfnet offline, resetAccount cancella la copia locale ma non ha un upstream da cui recuperare. Configura remoteRpcUrl all'avvio per fare in modo che i ripristini restaurino lo stato upstream.

use surfpool_sdk::cheatcodes::builders::ResetAccount;
use surfpool_sdk::{Pubkey, Surfnet};

let cheats = Surfnet::start().await?.cheatcodes();
let token_program: Pubkey = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA".parse()?;

cheats.execute(
    ResetAccount::new(token_program).include_owned_accounts(true),
)?;

Trasmetti Account in Tempo Reale

streamAccount registra un account per il polling in background dall'RPC upstream. La copia locale su Surfnet rimane sincronizzata con la mainnet senza che il test debba eseguire il polling esplicitamente. Combinalo con includeOwnedAccounts per trasmettere ogni PDA posseduto da un programma.

Richiede `remoteRpcUrl`

streamAccount funziona solo su una Surfnet avviata con remoteRpcUrl (o remote_rpc_url in Rust). Senza un RPC upstream non c'è nulla da trasmettere e la chiamata restituirà un errore.

use surfpool_sdk::cheatcodes::builders::StreamAccount;
use surfpool_sdk::{Pubkey, Surfnet};

let cheats = Surfnet::builder()
    .remote_rpc_url("https://api.mainnet-beta.solana.com")
    .start()
    .await?
    .cheatcodes();

let oracle: Pubkey = "H6ARHf6YXhGYeQfUzQNGk6rDNnLBQKrenN712K4AQJEG".parse()?;

cheats.execute(StreamAccount::new(oracle).include_owned_accounts(false))?;

Builder per Cheatcode (Rust)

L'SDK Rust espone builder tipizzati sotto surfpool_sdk::cheatcodes::builders per i casi in cui i metodi di convenienza non sono sufficienti. Ogni builder implementa il trait CheatcodeBuilder e viene eseguito tramite cheats.execute(builder).

Builder	Costruttore	Setter comuni
`SetAccount`	`new(address: Pubkey)`	`lamports`, `data`, `owner`, `rent_epoch`, `executable`
`SetTokenAccount`	`new(owner: Pubkey, mint: Pubkey)`	`amount`, `delegate`, `clear_delegate`, `state`, `delegated_amount`, `close_authority`, `clear_close_authority`, `token_program`
`ResetAccount`	`new(address: Pubkey)`	`include_owned_accounts(bool)`
`StreamAccount`	`new(address: Pubkey)`	`include_owned_accounts(bool)`
`DeployProgram`	`new(program_id: Pubkey)`, `from_keypair_path(path)`	`so_path`, `so_bytes`, `idl_path`

Per la superficie JS completa, consulta Riferimento JS. Per la superficie Rust completa, consulta Riferimento Rust.

Indice dei contenuti