Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
//! Shared harness for the Solana program invariant tests in `tests/`.
//!
//! Every test in this crate runs the REAL compiled SBF bytecode of the program
//! under test inside [LiteSVM](https://github.com/LiteSVM/litesvm). Nothing here
//! re-implements program logic: the helpers below only build instructions, derive
//! addresses, and read account bytes back, so a test failure always means the
//! program (or the invariant) is wrong, never the harness.
//!
//! Build the bytecode before running the tests:
//!
//! ```text
//! cd contracts/skill-license && cargo-build-sbf
//! cd contracts/agent-invocation && cargo-build-sbf
//! cd contracts/program-tests && cargo test
//! ```
use litesvm::LiteSVM;
use solana_clock::Clock;
use sha2::{Digest, Sha256};
use solana_pubkey::Pubkey;
use std::path::PathBuf;
use std::str::FromStr;
/// `skill_license`'s `declare_id!`.
pub const SKILL_LICENSE_ID: &str = "EdngSwxmDktyrr4phwGEZnCXEoQ27vgnBtowjhKa7Wr8";
/// `agent_invocation`'s `declare_id!`.
pub const AGENT_INVOCATION_ID: &str = "AgEntJDMi1A7UadCoYcx6Fm3gusNk8SHLCi7vSUa4Zfo";
/// SPL Associated Token Account program, the canonical mainnet address.
pub const ASSOCIATED_TOKEN_PROGRAM_ID: &str = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
/// SPL Token program, the canonical mainnet address.
pub const TOKEN_PROGRAM_ID: &str = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
/// Parse a base58 program address that is a compile-time constant of this crate.
pub fn pk(s: &str) -> Pubkey {
Pubkey::from_str(s).expect("constant program address must parse")
}
/// SHA-256, the same digest the programs use for `skill_seed` and the same one
/// Anchor uses to derive discriminators.
pub fn sha256(bytes: &[u8]) -> [u8; 32] {
let mut hasher = Sha256::new();
hasher.update(bytes);
hasher.finalize().into()
}
/// Anchor's 8-byte discriminator: the first eight bytes of
/// `sha256("<namespace>:<name>")`. `namespace` is `global` for an instruction
/// and `account` for an account type.
pub fn discriminator(namespace: &str, name: &str) -> [u8; 8] {
let digest = sha256(format!("{namespace}:{name}").as_bytes());
let mut out = [0u8; 8];
out.copy_from_slice(&digest[..8]);
out
}
/// Instruction data for an Anchor instruction: discriminator followed by the
/// borsh-encoded arguments.
pub fn ix_data(name: &str, args: &[u8]) -> Vec<u8> {
let mut data = discriminator("global", name).to_vec();
data.extend_from_slice(args);
data
}
/// Load a program's compiled bytecode into the VM, failing with an actionable
/// message when the SBF build has not been run yet.
pub fn load_program(svm: &mut LiteSVM, program_id: Pubkey, crate_dir: &str, so_name: &str) {
let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
.join("..")
.join(crate_dir)
.join("target/deploy")
.join(so_name);
let bytes = std::fs::read(&path).unwrap_or_else(|e| {
panic!(
"cannot read {}: {e}. Build it first: cd contracts/{crate_dir} && cargo-build-sbf",
path.display()
)
});
svm.add_program(program_id, &bytes)
.unwrap_or_else(|e| panic!("loading {so_name} into the VM failed: {e:?}"));
}
/// Derive the associated token account for `(owner, mint)`, the same derivation
/// the ATA program itself performs.
pub fn associated_token_address(owner: &Pubkey, mint: &Pubkey) -> Pubkey {
Pubkey::find_program_address(
&[
owner.as_ref(),
pk(TOKEN_PROGRAM_ID).as_ref(),
mint.as_ref(),
],
&pk(ASSOCIATED_TOKEN_PROGRAM_ID),
)
.0
}
/// Fields of an SPL token `Mint` this suite asserts on. Offsets are the SPL
/// Token program's fixed 82-byte layout, which is part of its wire format.
pub struct MintState {
pub mint_authority: Option<Pubkey>,
pub supply: u64,
pub decimals: u8,
pub freeze_authority: Option<Pubkey>,
}
/// Decode an SPL `Mint` account.
pub fn decode_mint(data: &[u8]) -> MintState {
assert!(data.len() >= 82, "mint account is {} bytes", data.len());
let coption = |offset: usize| -> Option<Pubkey> {
let tag = u32::from_le_bytes(data[offset..offset + 4].try_into().unwrap());
if tag == 0 {
None
} else {
Some(Pubkey::new_from_array(
data[offset + 4..offset + 36].try_into().unwrap(),
))
}
};
MintState {
mint_authority: coption(0),
supply: u64::from_le_bytes(data[36..44].try_into().unwrap()),
decimals: data[44],
freeze_authority: coption(46),
}
}
/// Fields of an SPL token account this suite asserts on. Offsets are the SPL
/// Token program's fixed 165-byte layout.
pub struct TokenAccountState {
pub mint: Pubkey,
pub owner: Pubkey,
pub amount: u64,
/// SPL `AccountState`: 0 uninitialized, 1 initialized, 2 frozen.
pub state: u8,
}
impl TokenAccountState {
pub fn is_frozen(&self) -> bool {
self.state == 2
}
}
/// Decode an SPL token account.
pub fn decode_token_account(data: &[u8]) -> TokenAccountState {
assert!(data.len() >= 165, "token account is {} bytes", data.len());
TokenAccountState {
mint: Pubkey::new_from_array(data[0..32].try_into().unwrap()),
owner: Pubkey::new_from_array(data[32..64].try_into().unwrap()),
amount: u64::from_le_bytes(data[64..72].try_into().unwrap()),
state: data[108],
}
}
/// A fixed, realistic wall-clock time for the VM: 2026-01-01T00:00:00Z.
///
/// LiteSVM boots with `unix_timestamp == 0`, which no real cluster ever reports.
/// The programs under test stamp `Clock::get()?.unix_timestamp` into account
/// state and treat `0` as "not set", so tests must run against a clock that
/// looks like a real one. Fixed rather than "now" so runs stay reproducible.
pub const TEST_UNIX_TIMESTAMP: i64 = 1_767_225_600;
/// Point the VM's clock at [`TEST_UNIX_TIMESTAMP`].
pub fn set_realistic_clock(svm: &mut LiteSVM) {
let mut clock = svm.get_sysvar::<Clock>();
clock.unix_timestamp = TEST_UNIX_TIMESTAMP;
clock.epoch_start_timestamp = TEST_UNIX_TIMESTAMP;
svm.set_sysvar(&clock);
}
/// Borsh-encode a string argument (4-byte little-endian length, then bytes).
pub fn borsh_string(s: &str) -> Vec<u8> {
let mut out = (s.len() as u32).to_le_bytes().to_vec();
out.extend_from_slice(s.as_bytes());
out
}
/// True when a failed transaction's logs mention the given Anchor error name.
/// Anchor logs `Error Code: <Name>. Error Number: <n>` on a constraint or
/// `require!` failure, so matching the name is exact, not a substring guess.
pub fn logs_have_anchor_error(logs: &[String], error_name: &str) -> bool {
let needle = format!("Error Code: {error_name}.");
logs.iter().any(|l| l.contains(&needle))
}
// ── SPL token helpers ───────────────────────────────────────────────────────
//
// LiteSVM boots with the real SPL Token and Associated Token Account programs,
// so these build genuine instructions against them rather than writing account
// bytes by hand. A test that fabricated a token account would prove nothing
// about a program that CPIs into the token program.
use litesvm::types::FailedTransactionMetadata;
use solana_instruction::{AccountMeta, Instruction};
use solana_keypair::Keypair;
use solana_signer::Signer;
use solana_system_interface::instruction as system_instruction;
use solana_system_interface::program as system_program;
use solana_transaction::Transaction;
/// Rent-exempt size of an SPL `Mint`.
const MINT_LEN: u64 = 82;
/// Send one instruction and return its logs, or the failure's logs.
pub fn send_ix(
svm: &mut LiteSVM,
ix: Instruction,
payer: &Keypair,
signers: &[&Keypair],
) -> Result<Vec<String>, Vec<String>> {
svm.expire_blockhash();
let tx = Transaction::new_signed_with_payer(
&[ix],
Some(&payer.pubkey()),
signers,
svm.latest_blockhash(),
);
match svm.send_transaction(tx) {
Ok(meta) => Ok(meta.logs),
Err(FailedTransactionMetadata { meta, .. }) => Err(meta.logs),
}
}
/// Create and initialize a real SPL mint whose authority is `authority`.
pub fn create_mint(svm: &mut LiteSVM, payer: &Keypair, authority: &Pubkey, decimals: u8) -> Pubkey {
let mint = Keypair::new();
let lamports = svm.minimum_balance_for_rent_exemption(MINT_LEN as usize);
let create = system_instruction::create_account(
&payer.pubkey(),
&mint.pubkey(),
lamports,
MINT_LEN,
&pk(TOKEN_PROGRAM_ID),
);
// InitializeMint2 (tag 20): decimals, mint authority, then a COption
// freeze authority which we leave as None.
let mut data = vec![20u8, decimals];
data.extend_from_slice(authority.as_ref());
data.push(0);
let init = Instruction {
program_id: pk(TOKEN_PROGRAM_ID),
accounts: vec![AccountMeta::new(mint.pubkey(), false)],
data,
};
svm.expire_blockhash();
let tx = Transaction::new_signed_with_payer(
&[create, init],
Some(&payer.pubkey()),
&[payer, &mint],
svm.latest_blockhash(),
);
svm.send_transaction(tx).expect("mint creation must succeed");
mint.pubkey()
}
/// Create the associated token account for `(owner, mint)` and return it.
pub fn create_ata(svm: &mut LiteSVM, payer: &Keypair, owner: &Pubkey, mint: &Pubkey) -> Pubkey {
let ata = associated_token_address(owner, mint);
let ix = Instruction {
program_id: pk(ASSOCIATED_TOKEN_PROGRAM_ID),
accounts: vec![
AccountMeta::new(payer.pubkey(), true),
AccountMeta::new(ata, false),
AccountMeta::new_readonly(*owner, false),
AccountMeta::new_readonly(*mint, false),
AccountMeta::new_readonly(system_program::id(), false),
AccountMeta::new_readonly(pk(TOKEN_PROGRAM_ID), false),
],
data: vec![0], // Create
};
send_ix(svm, ix, payer, &[payer]).expect("ATA creation must succeed");
ata
}
/// Mint `amount` to `dest`, signed by the mint authority.
pub fn mint_to(
svm: &mut LiteSVM,
payer: &Keypair,
authority: &Keypair,
mint: &Pubkey,
dest: &Pubkey,
amount: u64,
) {
let mut data = vec![7u8]; // MintTo
data.extend_from_slice(&amount.to_le_bytes());
let ix = Instruction {
program_id: pk(TOKEN_PROGRAM_ID),
accounts: vec![
AccountMeta::new(*mint, false),
AccountMeta::new(*dest, false),
AccountMeta::new_readonly(authority.pubkey(), true),
],
data,
};
send_ix(svm, ix, payer, &[payer, authority]).expect("mint_to must succeed");
}
/// Token balance of an account, or 0 when the account no longer exists (which
/// is what a closed vault looks like).
pub fn token_balance(svm: &LiteSVM, account: &Pubkey) -> u64 {
match svm.get_account(account) {
Some(a) if a.data.len() >= 165 => decode_token_account(&a.data).amount,
_ => 0,
}
}
/// Push the VM's clock forward by `seconds`, so a test can cross an expiry
/// boundary without sleeping.
pub fn advance_clock(svm: &mut LiteSVM, seconds: i64) {
let mut clock = svm.get_sysvar::<Clock>();
clock.unix_timestamp += seconds;
svm.set_sysvar(&clock);
}