use hopper_schema::accounts::{AccountLifecycle, ContextAccountDescriptor, ContextDescriptor};
use hopper_schema::c_client::CClientGen;
use hopper_schema::clientgen::{KtClientGen, TsClientGen};
use hopper_schema::go_client::GoClientGen;
use hopper_schema::python_client::PyClientGen;
use hopper_schema::{
compare_fields,
decode_account_fields,
decode_header,
decode_segments,
AccountEntry,
ArgDescriptor,
CompatImpact,
CompatibilityPair,
CompatibilityVerdict,
DecodedHeader,
DecodedReceipt,
EventDescriptor,
FieldCompat,
FieldDescriptor,
FieldIntent,
InstructionDescriptor,
LayoutFingerprint,
LayoutManifest,
LayoutMetadata,
MigrationAction,
MigrationPlan,
MigrationPolicy,
Phase,
PolicyDescriptor,
ProgramManifest,
SegmentMigrationReport,
SegmentRoleHint,
WriteRange,
};
use std::env;
use std::path::PathBuf;
use std::process;
mod bench;
mod cmd;
mod config;
mod interactive;
mod rpc;
mod style;
mod workspace;
fn require_header(data: &[u8]) -> DecodedHeader {
match decode_header(data) {
Some(h) => h,
None => {
eprintln!(
"Failed to decode Hopper header (data too short: {} bytes).",
data.len()
);
process::exit(1);
}
}
}
fn main() {
let args: Vec<String> = env::args().collect();
if args.len() < 2 {
print_usage();
process::exit(1);
}
if !config::GlobalConfig::load().ui.color {
style::init(false);
}
match args[1].as_str() {
"schema" => cmd_schema_family(&args[2..]),
"compile" => cmd_compile(&args[2..]),
"inspect" => cmd_inspect_family(&args[2..]),
"explain" => cmd_explain_family(&args[2..]),
"client" => cmd_client_family(&args[2..]),
"profile" => cmd::profile::cmd_profile(&args[2..]),
"fetch" => cmd_fetch(&args[2..]),
"init" => cmd::lifecycle::cmd_init(&args[2..]),
"add" => cmd::add::cmd_add(&args[2..]),
"build" => cmd::lifecycle::cmd_build(&args[2..]),
"test" => cmd::lifecycle::cmd_test(&args[2..]),
"deploy" => cmd::lifecycle::cmd_deploy(&args[2..]),
"upgrade" => cmd::lifecycle::cmd_upgrade(&args[2..]),
"close" => cmd::lifecycle::cmd_close(&args[2..]),
"buffers" => cmd::buffers::cmd_buffers(&args[2..]),
"migrate" => cmd::lifecycle::cmd_migrate(&args[2..]),
"dump" => cmd::lifecycle::cmd_dump(&args[2..]),
"clean" => cmd::clean::cmd_clean(&args[2..]),
"verify" => cmd::verify::cmd_verify(&args[2..]),
"publish-check" => cmd::publish_check::cmd_publish_check(&args[2..]),
"audit-check" => cmd::audit_check::cmd_audit_check(&args[2..]),
"publish-idl" => cmd::publish_idl::cmd_publish_idl(&args[2..]),
"publish-security" => cmd::publish_security::cmd_publish_security(&args[2..]),
"publish-manifest" => cmd::publish_manifest::cmd_publish_manifest(&args[2..]),
"solana-check" => cmd::solana_check::cmd_solana_check(&args[2..]),
"keys" => cmd::keys::cmd_keys(&args[2..]),
"config" => cmd::config::cmd_config(&args[2..]),
"lint" => cmd::lint::cmd_lint(&args[2..]),
"fuzz" => cmd::fuzz::cmd_fuzz(&args[2..], load_program_manifest),
"contention" => cmd::contention::cmd_contention(&args[2..], load_program_manifest),
"expand" => cmd::expand::cmd_expand(&args[2..]),
"tx" => cmd_tx_family(&args[2..]),
"doctor" => cmd::doctor::cmd_doctor(&args[2..]),
"feature-gate" | "feature-gates" => cmd::feature_gate::cmd_feature_gate(&args[2..]),
"completions" => cmd::meta::cmd_completions(&args[2..]),
"version" | "--version" | "-V" => cmd::meta::cmd_version(&args[2..]),
"actions" => cmd::actions::cmd_actions(&args[2..]),
"mobile" => cmd::mobile::cmd_mobile(&args[2..]),
"test-gen" => cmd::test_gen::cmd_test_gen(&args[2..]),
"decode" => cmd_inspect(&args[2..]),
"segments" => cmd_segments(&args[2..]),
"receipt" => cmd_receipt(&args[2..]),
"compat" => cmd_compat(&args[2..]),
"diff" => cmd_diff(&args[2..]),
"plan" => cmd_plan(&args[2..]),
"schema-export" => cmd_schema_export(),
"manager" => cmd_manager(&args[2..]),
"interactive" | "ui" => cmd_interactive(&args[2..]),
"help" | "--help" | "-h" => print_usage(),
other => {
eprintln!("Unknown command: {}", other);
print_usage();
process::exit(1);
}
}
}
fn cmd_schema_family(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper schema <subcommand>");
eprintln!();
eprintln!("Subcommands:");
eprintln!(
" export [--manifest|--idl|--codama] Export schema; --anchor-idl also requires --program-id"
);
eprintln!(" validate <manifest-json> Validate a program manifest");
eprintln!(" diff <old-json> <new-json> Field-level diff between versions");
process::exit(1);
}
match args[0].as_str() {
"export" => cmd_schema_export_family(&args[1..]),
"validate" => cmd_schema_validate(&args[1..]),
"diff" => cmd_diff(&args[1..]),
other => {
eprintln!("Unknown schema subcommand: {}", other);
process::exit(1);
}
}
}
fn cmd_inspect_family(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper inspect <hex-data|subcommand>");
eprintln!();
eprintln!(" hopper inspect <hex-data> Decode account header");
eprintln!(" hopper inspect layout <manifest> <hex-data> Decode fields using a manifest");
eprintln!(" hopper inspect segments <hex-data> Decode segment map");
eprintln!(" hopper inspect receipt <hex-data> Decode a state receipt");
process::exit(1);
}
match args[0].as_str() {
"layout" => cmd_inspect_layout(&args[1..]),
"segments" => cmd_segments(&args[1..]),
"receipt" => cmd_receipt(&args[1..]),
_ => cmd_inspect(args), }
}
fn cmd_explain_family(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper explain <hex-data|subcommand>");
eprintln!();
eprintln!(
" hopper explain <hex-data> Human-readable headered-account explanation"
);
eprintln!(" hopper explain account <hex-data> Explicit headered-account explanation");
eprintln!(" hopper explain receipt <hex-data> Explain a receipt in plain English");
eprintln!(" hopper explain compat <old> <new> Explain compatibility report");
eprintln!(" hopper explain policy <pack-name> Explain a named policy pack");
eprintln!(" hopper explain layout <manifest> Explain layout fields, intents, and fingerprint");
eprintln!(
" hopper explain program <manifest> Explain an entire program from its manifest"
);
eprintln!(" hopper explain context <manifest> Explain instruction contexts (accounts, roles, policies)");
eprintln!(" hopper explain instruction <manifest> <tag|name> Explain one instruction's accounts and policy");
process::exit(1);
}
match args[0].as_str() {
"account" => cmd_explain(&args[1..]),
"receipt" => cmd_explain_receipt(&args[1..]),
"compat" => cmd_explain_compat(&args[1..]),
"policy" => cmd_explain_policy(&args[1..]),
"layout" => cmd_explain_layout(&args[1..]),
"program" => cmd_explain_program(&args[1..]),
"context" => cmd_explain_context(&args[1..]),
"instruction" => cmd_explain_instruction(&args[1..]),
first if looks_like_tx_signature(first) => {
cmd::tx_explain::cmd_tx_explain(args);
}
first if looks_like_program_id(first) => {
cmd_explain_program_onchain(args);
}
_ => cmd_explain(args), }
}
fn looks_like_tx_signature(s: &str) -> bool {
if s.len() < 84 || s.len() > 90 {
return false;
}
is_base58(s)
&& bs58::decode(s)
.into_vec()
.map(|b| b.len() == 64)
.unwrap_or(false)
}
fn looks_like_program_id(s: &str) -> bool {
if s.len() < 32 || s.len() > 44 {
return false;
}
if !is_base58(s) {
return false;
}
let all_hex = s.chars().all(|c| c.is_ascii_hexdigit());
if all_hex {
return false;
}
bs58::decode(s)
.into_vec()
.map(|b| b.len() == 32)
.unwrap_or(false)
}
fn is_base58(s: &str) -> bool {
const ALPHABET: &[u8] = b"123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
!s.is_empty() && s.bytes().all(|b| ALPHABET.contains(&b))
}
fn cmd_explain_program_onchain(args: &[String]) {
let program_id = &args[0];
let mut rpc_override: Option<String> = None;
let mut i = 1;
while i < args.len() {
if args[i] == "--rpc" {
rpc_override = args.get(i + 1).cloned();
i += 2;
} else {
i += 1;
}
}
let rpc_url = crate::rpc::resolve_rpc_url(rpc_override.as_deref());
match cmd::manager_invoke::try_fetch_manifest(&rpc_url, program_id) {
Ok(json) => cmd_explain_program(&[json]),
Err(e) => {
eprintln!("hopper explain {program_id}: no on-chain Hopper manifest found ({e})");
eprintln!();
eprintln!("Hint: Hopper has no generic publisher for the legacy manifest PDA.");
eprintln!("Pass a local manifest: `hopper explain program <manifest.json>`.");
process::exit(1);
}
}
}
fn cmd_explain_instruction(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper explain instruction <manifest> <tag|name>");
process::exit(1);
}
cmd_manager_instruction(args);
}
fn cmd_client_family(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper client gen [--ts|--kt|--py|--go|--c] <manifest-json>");
eprintln!();
eprintln!("Subcommands:");
eprintln!(" gen --ts <manifest> Generate TypeScript client SDK");
eprintln!(" gen --kt <manifest> Generate Kotlin client SDK");
eprintln!(" gen --py <manifest> Generate Python client SDK");
eprintln!(" gen --go <manifest> Generate Go client SDK");
eprintln!(" gen --c <manifest> Generate C client header");
process::exit(1);
}
match args[0].as_str() {
"gen" => cmd_client_gen(&args[1..]),
other => {
eprintln!("Unknown client subcommand: {}", other);
process::exit(1);
}
}
}
#[derive(Default)]
struct RustEmitFilters {
layout: Option<String>,
instruction: Option<String>,
context: Option<String>,
}
enum CompileManifestSource {
Explicit(String),
CurrentPackage,
Package(String),
ProgramId {
program_id: String,
rpc_override: Option<String>,
},
}
struct CompileOptions {
source: CompileManifestSource,
filters: RustEmitFilters,
out: Option<PathBuf>,
force: bool,
lint: bool,
lint_fail_on_warn: bool,
}
fn cmd_compile(args: &[String]) {
if args.iter().any(|arg| arg == "--help" || arg == "-h") {
print_compile_usage();
return;
}
if args.len() < 2 || args[0] != "--emit" {
eprintln!("Usage: hopper compile --emit <target> [options]");
eprintln!();
eprintln!("Supported targets:");
eprintln!(" rust Lowered Rust preview (what the macros expand to)");
eprintln!(" ts TypeScript client SDK");
eprintln!(" kt Kotlin client SDK");
eprintln!(" py Python client SDK");
eprintln!(" go Go client SDK");
eprintln!(" c C client header");
eprintln!(" rust-client Off-chain Rust client (solana-sdk types)");
eprintln!(" idl Hopper public IDL JSON");
eprintln!(" codama Codama-flavored JSON");
eprintln!(" schema Hopper program manifest JSON (from an existing manifest)");
eprintln!(" manifest GENERATE hopper.manifest.json from the package source");
eprintln!();
eprintln!("See `hopper compile --help` for the full option set.");
process::exit(1);
}
let target = args[1].as_str();
let cwd = workspace::current_dir().unwrap_or_else(|err| {
eprintln!("{err}");
process::exit(1);
});
let options = parse_compile_options(&args[2..]).unwrap_or_else(|err| {
eprintln!("hopper compile failed: {err}");
process::exit(1);
});
if target == "manifest" {
let package = match &options.source {
CompileManifestSource::Package(name) => name.clone(),
_ => {
eprintln!(
"hopper compile --emit manifest requires --package <name> (the manifest is generated from that package's source)"
);
process::exit(1);
}
};
let out = options.out.as_deref().map(std::path::Path::new);
match cmd::emit_manifest::emit_manifest_from_source(&package, out, &cwd) {
Ok(path) => {
println!("wrote {}", path.display());
println!(
"every emit target can now consume it, e.g. `hopper compile --emit ts --package {package}` or `hopper tx explain <sig> --manifest {}`",
path.display()
);
return;
}
Err(err) => {
eprintln!("hopper compile failed: {err}");
process::exit(1);
}
}
}
let prog = load_compile_manifest(&options.source, &cwd).unwrap_or_else(|err| {
eprintln!("hopper compile failed: {err}");
process::exit(1);
});
let (artifact, label): (String, &'static str) = match target {
"rust" => match render_program_rust_preview(&prog, &options.filters) {
Ok(text) => (text, "lowered Rust preview"),
Err(err) => {
eprintln!("hopper compile failed: {err}");
process::exit(1);
}
},
"ts" => (format!("{}", TsClientGen(&prog)), "TypeScript client SDK"),
"kt" => (format!("{}", KtClientGen(&prog)), "Kotlin client SDK"),
"py" => (format!("{}", PyClientGen(&prog)), "Python client SDK"),
"go" => (format!("{}", GoClientGen(&prog)), "Go client SDK"),
"c" => (format!("{}", CClientGen(&prog)), "C client header"),
"rust-client" => (
format!("{}", hopper_schema::rust_client::RsClientGen(&prog)),
"Rust off-chain client",
),
"idl" => (
format!("{}", hopper_schema::codama::IdlJsonFromManifest(&prog)),
"Hopper public IDL JSON",
),
"codama" => (
format!("{}", hopper_schema::codama::CodamaJsonFromManifest(&prog)),
"Codama JSON",
),
"schema" => (
format!("{}", hopper_schema::codama::ManifestJson(&prog)),
"Hopper manifest JSON",
),
other => {
eprintln!("Unsupported emit target: {}", other);
eprintln!(
"Supported: rust | ts | kt | py | go | c | rust-client | idl | codama | schema | manifest"
);
process::exit(1);
}
};
if let Some(path) = options.out {
let output_path = if path.is_absolute() {
path
} else {
cwd.join(path)
};
workspace::write_text_file(&output_path, &artifact, options.force).unwrap_or_else(|err| {
eprintln!("hopper compile failed: {err}");
process::exit(1);
});
println!("Wrote {} to {}", label, output_path.display());
} else {
print!("{artifact}");
}
if options.lint {
let project_root = workspace::find_project_root(&cwd).unwrap_or_else(|err| {
eprintln!("hopper compile --lint failed: {err}");
process::exit(1);
});
match cmd::lint::run_lint_diagnostics(&project_root) {
Ok(summary) => {
for line in &summary.lines {
println!("{line}");
}
eprintln!(
"[hopper compile --lint] {} error(s), {} warning(s)",
summary.errors, summary.warnings,
);
let fail =
summary.errors > 0 || (options.lint_fail_on_warn && summary.warnings > 0);
if fail {
process::exit(1);
}
}
Err(err) => {
eprintln!("hopper compile --lint failed: {err}");
process::exit(1);
}
}
}
}
fn parse_compile_options(args: &[String]) -> Result<CompileOptions, String> {
let mut explicit_manifest = None;
let mut package = None;
let mut program_id = None;
let mut rpc_override = None;
let mut filters = RustEmitFilters::default();
let mut out = None;
let mut force = false;
let mut lint = false;
let mut lint_fail_on_warn = false;
let mut i = 0;
while i < args.len() {
match args[i].as_str() {
"--program-id" => {
if i + 1 >= args.len() {
return Err("--program-id requires a base58 program address".to_string());
}
program_id = Some(args[i + 1].clone());
i += 2;
}
"--rpc" => {
if i + 1 >= args.len() {
return Err("--rpc requires a URL argument".to_string());
}
rpc_override = Some(args[i + 1].clone());
i += 2;
}
"--package" => {
if i + 1 >= args.len() {
return Err("--package requires a workspace member name".to_string());
}
package = Some(args[i + 1].clone());
i += 2;
}
"--layout" => {
if i + 1 >= args.len() {
return Err("--layout requires a layout name".to_string());
}
filters.layout = Some(args[i + 1].clone());
i += 2;
}
"--instruction" => {
if i + 1 >= args.len() {
return Err("--instruction requires an instruction name".to_string());
}
filters.instruction = Some(args[i + 1].clone());
i += 2;
}
"--context" => {
if i + 1 >= args.len() {
return Err("--context requires a context name".to_string());
}
filters.context = Some(args[i + 1].clone());
i += 2;
}
"--out" => {
if i + 1 >= args.len() {
return Err("--out requires a file path".to_string());
}
out = Some(PathBuf::from(&args[i + 1]));
i += 2;
}
"--force" => {
force = true;
i += 1;
}
"--lint" => {
lint = true;
i += 1;
}
"--lint-fail-on-warn" => {
lint = true;
lint_fail_on_warn = true;
i += 1;
}
other if other.starts_with('-') => {
return Err(format!("Unknown compile argument: {other}"));
}
other => {
if explicit_manifest.is_some() {
return Err(format!("Unexpected extra manifest argument: {other}"));
}
explicit_manifest = Some(other.to_string());
i += 1;
}
}
}
if rpc_override.is_some() && program_id.is_none() {
return Err("--rpc is only valid together with --program-id".to_string());
}
let source_count =
explicit_manifest.is_some() as u8 + package.is_some() as u8 + program_id.is_some() as u8;
if source_count > 1 {
return Err(
"Choose only one manifest source: an explicit manifest, --package, or --program-id"
.to_string(),
);
}
let source = if let Some(program_id) = program_id {
CompileManifestSource::ProgramId {
program_id,
rpc_override,
}
} else if let Some(package) = package {
CompileManifestSource::Package(package)
} else if let Some(arg) = explicit_manifest {
CompileManifestSource::Explicit(arg)
} else {
CompileManifestSource::CurrentPackage
};
Ok(CompileOptions {
source,
filters,
out,
force,
lint,
lint_fail_on_warn,
})
}
fn load_compile_manifest(
source: &CompileManifestSource,
cwd: &std::path::Path,
) -> Result<ProgramManifest, String> {
match source {
CompileManifestSource::Explicit(arg) => Ok(load_program_manifest(arg)),
CompileManifestSource::CurrentPackage => {
let manifest_path = workspace::infer_program_manifest_for_project(cwd)?;
load_program_manifest_from_path(&manifest_path)
}
CompileManifestSource::Package(package) => {
let workspace_root = workspace::find_workspace_root(cwd)?;
let manifest_path =
workspace::infer_program_manifest_for_package(&workspace_root, package)?;
load_program_manifest_from_path(&manifest_path)
}
CompileManifestSource::ProgramId {
program_id,
rpc_override,
} => {
let json = fetch_manifest_json(program_id, rpc_override.as_deref());
Ok(load_program_manifest_from_json(&json))
}
}
}
fn load_program_manifest_from_path(path: &std::path::Path) -> Result<ProgramManifest, String> {
let json = std::fs::read_to_string(path)
.map_err(|err| format!("Failed to read {}: {err}", path.display()))?;
Ok(load_program_manifest_from_json(&json))
}
fn cmd_client_gen(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper client gen [--ts|--kt|--py|--go|--c] <manifest-json>");
process::exit(1);
}
let (lang, manifest_arg) = if args[0].starts_with("--") {
if args.len() < 2 {
eprintln!("Usage: hopper client gen [--ts|--kt|--py|--go|--c] <manifest-json>");
process::exit(1);
}
(args[0].as_str(), &args[1])
} else {
("--ts", &args[0])
};
let manifest = load_program_manifest(manifest_arg);
match lang {
"--ts" => {
println!("{}", TsClientGen(&manifest));
}
"--kt" => {
println!("{}", KtClientGen(&manifest));
}
"--py" => {
println!("{}", PyClientGen(&manifest));
}
"--go" => {
println!("{}", GoClientGen(&manifest));
}
"--c" => {
println!("{}", CClientGen(&manifest));
}
other => {
eprintln!(
"Unknown language flag: {}. Use --ts, --kt, --py, --go, or --c.",
other
);
process::exit(1);
}
}
}
fn cmd_schema_validate(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper schema validate <manifest-json>");
process::exit(1);
}
let manifest = load_program_manifest(&args[0]);
println!("=== Manifest Validation ===");
println!();
println!(" Program: {} v{}", manifest.name, manifest.version);
println!(" Layouts: {}", manifest.layouts.len());
println!(" Instructions: {}", manifest.instructions.len());
println!(" Events: {}", manifest.events.len());
println!(" Policies: {}", manifest.policies.len());
println!();
let mut errors = 0u32;
for (i, l1) in manifest.layouts.iter().enumerate() {
for l2 in manifest.layouts[i + 1..].iter() {
if l1.disc == l2.disc {
println!(
" ERROR: Duplicate discriminator {} for {} and {}",
l1.disc, l1.name, l2.name
);
errors += 1;
}
}
}
for (i, ix1) in manifest.instructions.iter().enumerate() {
for ix2 in manifest.instructions[i + 1..].iter() {
if ix1.tag == ix2.tag {
println!(
" ERROR: Duplicate instruction tag {} for {} and {}",
ix1.tag, ix1.name, ix2.name
);
errors += 1;
}
}
}
for (i, e1) in manifest.events.iter().enumerate() {
for e2 in manifest.events[i + 1..].iter() {
if e1.tag == e2.tag {
println!(
" ERROR: Duplicate event tag {} for {} and {}",
e1.tag, e1.name, e2.name
);
errors += 1;
}
}
}
if errors == 0 {
println!(" VALID: No errors found.");
} else {
println!();
println!(" {} error(s) found.", errors);
process::exit(1);
}
}
fn cmd_explain_receipt(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper explain receipt <hex-data>");
process::exit(1);
}
let data = match hex_decode(&args[0]) {
Ok(d) => d,
Err(e) => {
eprintln!("Hex decode error: {}", e);
process::exit(1);
}
};
if data.len() < RECEIPT_WIRE_SIZE {
eprintln!("Receipt data too short.");
process::exit(1);
}
let changed_bytes = u32::from_le_bytes(data[16..20].try_into().expect("slice length mismatch"));
let flags = data[32];
let was_resized = flags & (1 << 0) != 0;
let invariants_passed = flags & (1 << 1) != 0;
let cpi_invoked = flags & (1 << 2) != 0;
let committed = flags & (1 << 3) != 0;
let before_fp = &data[33..41];
let after_fp = &data[41..49];
let phase = data[58];
let compat_impact = data[61];
let migration_flags = data[62];
let phase_name = match phase {
1 => "initialization",
2 => "close",
3 => "migration",
4 => "read-only inspection",
_ => "update",
};
println!("=== Receipt Explanation ===");
println!();
if !committed {
println!(" This receipt was NOT committed. The mutation was started but not finalized.");
return;
}
println!(" This receipt records a state {} operation.", phase_name);
if before_fp == after_fp {
println!(" The account data was NOT changed (fingerprints match).");
} else {
println!(
" The account data WAS changed ({} bytes modified).",
changed_bytes
);
}
if was_resized {
let old_size = u32::from_le_bytes(data[22..26].try_into().expect("slice length mismatch"));
let new_size = u32::from_le_bytes(data[26..30].try_into().expect("slice length mismatch"));
println!(
" The account was RESIZED from {} to {} bytes.",
old_size, new_size
);
}
if invariants_passed {
println!(" All invariants PASSED.");
} else {
let inv_checked =
u16::from_le_bytes(data[30..32].try_into().expect("slice length mismatch"));
if inv_checked > 0 {
println!(" WARNING: Invariants were checked but DID NOT PASS.");
}
}
if cpi_invoked {
let cpi_count = data[57];
println!(" CPI was invoked ({} call(s)).", cpi_count);
}
if compat_impact != 0 {
let impact_name = match compat_impact {
1 => "append-only (backward readable)",
2 => "requires migration",
3 => "BREAKING",
_ => "unknown",
};
println!(" Compatibility impact: {}.", impact_name);
}
if migration_flags != 0 {
let mut mig = Vec::new();
if migration_flags & 1 != 0 {
mig.push("triggered");
}
if migration_flags & 2 != 0 {
mig.push("realloc");
}
if migration_flags & 4 != 0 {
mig.push("schema bump");
}
println!(" Migration: {}.", mig.join(", "));
}
}
fn cmd_explain_compat(args: &[String]) {
if args.len() < 2 {
eprintln!("Usage: hopper explain compat <v1-json> <v2-json>");
process::exit(1);
}
let v1 = parse_or_exit(&args[0]);
let v2 = parse_or_exit(&args[1]);
let (m1, _f1) = to_manifest(&v1);
let (m2, _f2) = to_manifest(&v2);
let verdict = CompatibilityVerdict::between(&m1, &m2);
println!("=== Compatibility Explanation ===");
println!();
println!(
" Comparing '{}' v{} → v{}",
m1.name, m1.version, m2.version
);
println!(" Verdict: {}", verdict.name());
println!();
match verdict {
CompatibilityVerdict::Identical => {
println!(" No structural changes detected.");
}
CompatibilityVerdict::WireCompatible => {
println!(" WIRE-COMPATIBLE: Byte layout is identical but semantic metadata differs.");
println!(" Readers can parse both versions with the same wire code.");
println!(" Review field intents and update tooling if semantics changed.");
}
CompatibilityVerdict::AppendSafe => {
println!(" SAFE upgrade: New version preserves the old field prefix.");
println!(" Old readers can still parse new accounts (they ignore new fields).");
}
CompatibilityVerdict::MigrationRequired => {
println!(" MIGRATION required: Field layout has changed.");
println!(" Old data is NOT directly backward-readable.");
println!(" You need a migration instruction to move accounts to the new layout.");
println!(" Use `hopper plan` to generate a step-by-step migration plan.");
}
CompatibilityVerdict::Incompatible => {
println!(" BREAKING change: Field layout has changed and is NOT backward-readable.");
println!(" You MUST migrate all accounts before deploying the new version.");
println!(" Use `hopper plan` to generate a step-by-step migration plan.");
}
}
let report = compare_fields::<64>(&m1, &m2);
let mut changes = Vec::new();
for i in 0..report.len() {
if let Some(entry) = report.get(i) {
match entry.status {
FieldCompat::Identical => {}
FieldCompat::Added => changes.push(format!(" + Added field '{}'", entry.name)),
FieldCompat::Removed => changes.push(format!(" - Removed field '{}'", entry.name)),
FieldCompat::Changed => changes.push(format!(" ~ Changed field '{}'", entry.name)),
}
}
}
if !changes.is_empty() {
println!();
println!(" Field changes:");
for c in &changes {
println!("{}", c);
}
}
}
fn cmd_explain_policy(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper explain policy <pack-name>");
eprintln!();
eprintln!("Available packs:");
eprintln!(" TreasuryWrite Vault/treasury balance mutations");
eprintln!(" JournalTouch Journal segment writes");
eprintln!(" ExternalCall CPI-invoking instructions");
eprintln!(" ShardMutation Shard data modifications");
eprintln!(" MigrationSensitive Account reallocation/migration");
eprintln!(" AuthorityChange Authority/permission modifications");
eprintln!(" ReadOnlyAudit Read-only inspection/audit");
eprintln!(" AccountInit Account creation");
eprintln!(" AccountClose Account closure");
process::exit(1);
}
let policy_info: (&str, &[(&str, &str)], bool, &[&str]) = match args[0].as_str() {
"TreasuryWrite" => (
"Vault/treasury balance mutations",
&[
("MutatesState", "Authority, StateSnapshot"),
("MutatesTreasury", "LamportConservation, InvariantCheck"),
],
true,
&["lamport_balance_conserved", "no_phantom_credit"],
),
"JournalTouch" => (
"Journal segment writes",
&[
("MutatesState", "Authority"),
("TouchesJournal", "JournalCapacity, StateSnapshot"),
],
true,
&["journal_append_only", "segment_bounds_checked"],
),
"ExternalCall" => (
"CPI-invoking instructions",
&[("ExternalCall", "CpiGuard, PostMutationCheck, StateSnapshot")],
true,
&["cpi_target_allowlisted", "no_reentrant_mutation"],
),
"ShardMutation" => (
"Shard data modifications",
&[("MutatesState", "Authority, StateSnapshot, InvariantCheck")],
true,
&["shard_index_bounds_checked", "discriminator_preserved"],
),
"MigrationSensitive" => (
"Account reallocation/migration",
&[(
"ReallocatesAccount",
"Authority, RentExemption, StateSnapshot, InvariantCheck",
)],
true,
&["layout_id_updated", "old_data_preserved_or_migrated"],
),
"AuthorityChange" => (
"Authority/permission modifications",
&[(
"ModifiesAuthority",
"Authority, CpiGuard, PostMutationCheck, InvariantCheck",
)],
true,
&["old_authority_signed", "no_authority_escalation"],
),
"ReadOnlyAudit" => (
"Read-only inspection",
&[("ReadsState", "StateSnapshot")],
false,
&["no_state_mutation"],
),
"AccountInit" => (
"Account creation",
&[("CreatesAccount", "Authority, RentExemption, InvariantCheck")],
true,
&["header_initialized_correctly", "discriminator_set"],
),
"AccountClose" => (
"Account closure",
&[(
"ClosesAccount",
"Authority, StateSnapshot, LamportConservation",
)],
true,
&["lamports_drained", "data_zeroed"],
),
other => {
eprintln!("Unknown policy pack: {}", other);
process::exit(1);
}
};
println!("=== Policy Pack: {} ===", args[0]);
println!();
println!(" Purpose: {}", policy_info.0);
println!();
println!(" Rules:");
for &(cap, reqs) in policy_info.1 {
println!(" When {} → require {}", cap, reqs);
}
println!();
println!(
" Receipt expected: {}",
if policy_info.2 { "YES" } else { "NO" }
);
println!();
if !policy_info.3.is_empty() {
println!(" Invariant hints:");
for hint in policy_info.3 {
println!(" • {}", hint);
}
println!();
}
println!(" When this policy pack is active, the listed requirements");
println!(" are automatically enforced for any instruction declaring");
println!(" the corresponding capability.");
}
fn cmd_explain_layout(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper explain layout <manifest-json>");
process::exit(1);
}
let pm = load_program_manifest(&args[0]);
println!("=== Layout Explanation: {} v{} ===", pm.name, pm.version);
println!();
if pm.layouts.is_empty() {
println!(" No layouts defined.");
return;
}
for layout in pm.layouts {
println!(
" Layout: {} (disc={}, version={})",
layout.name, layout.disc, layout.version
);
println!(" Wire layout_id: {}", hex_encode(&layout.layout_id));
let fp = LayoutFingerprint::from_manifest(layout);
println!(
" Semantic fingerprint: {}",
hex_encode(&fp.semantic_hash)
);
println!(
" Total size: {} bytes ({} fields)",
layout.total_size, layout.field_count
);
println!();
if layout.fields.is_empty() {
println!(" (no field descriptors)");
} else {
println!(" Fields:");
let mut monetary_count = 0u32;
let mut identity_count = 0u32;
for field in layout.fields {
let intent_tag = if field.intent as u8 != 255 {
field.intent.name()
} else {
"custom"
};
println!(
" {:16} {:12} {:>3}B @{:<4} intent={}",
field.name, field.canonical_type, field.size, field.offset, intent_tag
);
if field.intent.is_monetary() {
monetary_count += 1;
}
if field.intent.is_identity() {
identity_count += 1;
}
}
println!();
if monetary_count > 0 {
println!(
" {} monetary field(s): lamport conservation checks recommended.",
monetary_count
);
}
if identity_count > 0 {
println!(
" {} identity field(s): authority validation required.",
identity_count
);
}
}
println!();
}
}
fn cmd_explain_program(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper explain program <manifest>");
eprintln!(" Human-readable explanation of the entire program: layouts, instructions,");
eprintln!(" policies, events, compatibility, and the Hopper pipeline steps it uses.");
process::exit(1);
}
let prog = load_program_manifest(&args[0]);
println!("=== Program: {} v{} ===", prog.name, prog.version);
println!();
println!(" {}", prog.description);
println!();
println!(" Pipeline Coverage:");
println!(" 1. Define {} layout(s) defined", prog.layouts.len());
println!(
" 2. Resolve {} instruction(s) with account resolution",
prog.instructions.len()
);
let policy_count = prog.policies.len();
if policy_count > 0 {
println!(" 3. Validate {} policy pack(s) enforced", policy_count);
} else {
println!(" 3. Validate (no named policies; consider adding policy packs)");
}
println!(" 4. Execute Mutations guarded by capabilities");
let receipt_count = prog
.instructions
.iter()
.filter(|ix| ix.receipt_expected)
.count();
if receipt_count > 0 {
println!(
" 5. Record {} instruction(s) emit receipts",
receipt_count
);
} else {
println!(" 5. Record (no receipt expectations; consider adding receipt tracking)");
}
let compat_count = prog.compatibility_pairs.len();
if compat_count > 0 {
println!(" 6. Verify {} compatibility rule(s)", compat_count);
} else {
println!(" 6. Verify (no compat rules; safe for single-version programs)");
}
let event_count = prog.events.len();
println!(
" 7. Inspect {} event(s) for off-chain observability",
event_count
);
println!();
println!(" Layouts:");
for l in prog.layouts.iter() {
let fp = LayoutFingerprint::from_manifest(l);
println!(
" {} v{} | disc {} | {} bytes | {} fields",
l.name, l.version, l.disc, l.total_size, l.field_count
);
println!(
" wire={} semantic={}",
hex_encode(&fp.wire_hash),
hex_encode(&fp.semantic_hash)
);
let monetary: Vec<&str> = l
.fields
.iter()
.filter(|f| f.intent.is_monetary())
.map(|f| f.name)
.collect();
let identity: Vec<&str> = l
.fields
.iter()
.filter(|f| f.intent.is_identity())
.map(|f| f.name)
.collect();
if !monetary.is_empty() {
println!(" monetary fields: {}", monetary.join(", "));
}
if !identity.is_empty() {
println!(" identity fields: {}", identity.join(", "));
}
}
println!();
println!(" Instructions:");
for ix in prog.instructions.iter() {
let read_accounts: Vec<&str> = ix
.accounts
.iter()
.filter(|account| !account.writable)
.map(|account| account.name)
.collect();
let write_accounts: Vec<&str> = ix
.accounts
.iter()
.filter(|account| account.writable)
.map(|account| account.name)
.collect();
let signer_accounts: Vec<&str> = ix
.accounts
.iter()
.filter(|account| account.signer)
.map(|account| account.name)
.collect();
print!(
" [{}] {} | {} args | {} accounts",
ix.tag,
ix.name,
ix.args.len(),
ix.accounts.len()
);
if ix.receipt_expected {
print!(" | receipt");
}
if !ix.policy_pack.is_empty() {
print!(" | policy={}", ix.policy_pack);
}
println!();
println!(" reads : {}", format_name_list(&read_accounts));
println!(" writes: {}", format_name_list(&write_accounts));
println!(" signers: {}", format_name_list(&signer_accounts));
}
println!();
if !prog.policies.is_empty() {
println!(" Policies:");
for p in prog.policies.iter() {
println!(
" {} | {} capabilities, {} requirements, {} invariants | receipt={}",
p.name,
p.capabilities.len(),
p.requirements.len(),
p.invariants.len(),
p.receipt_profile
);
}
println!();
}
if !prog.events.is_empty() {
println!(" Events:");
for ev in prog.events.iter() {
println!(" [{}] {} | {} fields", ev.tag, ev.name, ev.fields.len());
}
println!();
}
if !prog.contexts.is_empty() {
println!(" Contexts:");
for ctx in prog.contexts.iter() {
let signers = ctx.accounts.iter().filter(|a| a.signer).count();
let writables = ctx.accounts.iter().filter(|a| a.writable).count();
print!(
" {} | {} accounts ({} signer, {} writable)",
ctx.name,
ctx.accounts.len(),
signers,
writables
);
if !ctx.policies.is_empty() {
print!(" | policies: {}", ctx.policies.join(", "));
}
if ctx.receipts_expected {
print!(" | receipt");
}
println!();
}
println!();
} else {
println!(" Contexts:");
println!(" No typed contexts embedded in this manifest.");
println!(" Use `hopper compile --emit rust [<manifest>|--package <name>]` to inspect");
println!(" runtime accessors Hopper derives from the instruction account lists.");
println!();
}
println!(" Assessment:");
if policy_count > 0 && receipt_count > 0 && compat_count > 0 {
println!(" This manifest declares layouts, policies, receipts, and");
println!(" compatibility rules for schema-aware tooling.");
} else {
let mut missing = Vec::new();
if policy_count == 0 {
missing.push("named policies");
}
if receipt_count == 0 {
missing.push("receipt tracking");
}
if compat_count == 0 {
missing.push("compatibility rules");
}
println!(
" This manifest does not declare: {}.",
missing.join(", ")
);
println!(" These are optional for simple programs but recommended for");
println!(" protocols planning version evolution or operator dashboards.");
}
}
fn cmd_explain_context(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper explain context <manifest> [--type <ContextName>]");
eprintln!(" Show instruction contexts with account roles, mutability, signer status,");
eprintln!(
" layout bindings, policy bindings, seeds, optionality, and generated accessors."
);
eprintln!();
eprintln!(" Without --type, shows all contexts in the manifest.");
eprintln!(" With --type, filters to a single named context.");
process::exit(1);
}
let mut manifest_path: Option<&str> = None;
let mut filter_type: Option<&str> = None;
let mut i = 0;
while i < args.len() {
if args[i] == "--type" {
if i + 1 < args.len() {
filter_type = Some(&args[i + 1]);
i += 2;
continue;
} else {
eprintln!("--type requires a context name argument");
process::exit(1);
}
}
if manifest_path.is_none() {
manifest_path = Some(&args[i]);
}
i += 1;
}
let manifest_path = match manifest_path {
Some(p) => p,
None => {
eprintln!("Missing manifest path");
process::exit(1);
}
};
let manifest = load_program_manifest(manifest_path);
if manifest.contexts.is_empty() {
println!("=== Contexts: {} v{} ===", manifest.name, manifest.version);
println!();
println!(" No contexts defined in this manifest.");
println!(" Use hopper_accounts! or #[derive(HopperAccounts)] to add typed contexts.");
println!(" For instruction-level lowered accessors, run:");
println!(" hopper compile --emit rust {}", manifest_path);
return;
}
let contexts: Vec<_> = if let Some(name) = filter_type {
manifest
.contexts
.iter()
.filter(|c| c.name == name)
.collect()
} else {
manifest.contexts.iter().collect()
};
if contexts.is_empty() {
if let Some(name) = filter_type {
eprintln!("No context named '{}' found in manifest.", name);
eprintln!("Available contexts:");
for c in manifest.contexts.iter() {
eprintln!(" {}", c.name);
}
process::exit(1);
}
}
println!("=== Contexts: {} v{} ===", manifest.name, manifest.version);
println!();
for ctx in &contexts {
let read_accounts: Vec<&str> = ctx
.accounts
.iter()
.filter(|account| !account.writable)
.map(|account| account.name)
.collect();
let write_accounts: Vec<&str> = ctx
.accounts
.iter()
.filter(|account| account.writable)
.map(|account| account.name)
.collect();
let signer_accounts: Vec<&str> = ctx
.accounts
.iter()
.filter(|account| account.signer)
.map(|account| account.name)
.collect();
println!(" Context: {}", ctx.name);
println!(
" Accounts: {} total, {} signer(s), {} writable",
ctx.accounts.len(),
ctx.accounts.iter().filter(|a| a.signer).count(),
ctx.accounts.iter().filter(|a| a.writable).count(),
);
println!(" Reads: {}", format_name_list(&read_accounts));
println!(" Writes: {}", format_name_list(&write_accounts));
println!(" Signers: {}", format_name_list(&signer_accounts));
println!();
for acct in ctx.accounts.iter() {
print!(" {:16} {:16}", acct.name, acct.kind);
let mut flags = Vec::new();
if acct.writable {
flags.push("mut");
}
if acct.signer {
flags.push("signer");
}
if acct.optional {
flags.push("optional");
}
if !flags.is_empty() {
print!(" [{}]", flags.join(", "));
}
println!();
if !acct.layout_ref.is_empty() {
println!(" layout = {}", acct.layout_ref);
}
if !acct.policy_ref.is_empty() {
println!(" policy = {}", acct.policy_ref);
}
if !acct.seeds.is_empty() {
println!(" seeds = [{}]", acct.seeds.join(", "));
}
println!(
" access = {}",
render_context_accessor_summary(ctx.name, acct)
);
}
println!();
println!(" Borrow path:");
println!(
" Shared reads lower to Context::account(index) -> AccountView::load()/raw_ref()."
);
println!(" Writable access lowers to Context::account_mut(index) -> AccountView::load_mut()/raw_mut().");
println!(
" Segment-safe mutations stay explicit in handlers via Context::segment_mut(...)."
);
println!(" Conflict model:");
println!(" Static duplicate-name conflicts are not visible in the manifest.");
println!(" Runtime duplicate-account and segment conflicts are enforced by Hopper's audit and borrow registry.");
println!();
if !ctx.policies.is_empty() {
println!(" Policies: {}", ctx.policies.join(", "));
}
if ctx.receipts_expected {
println!(" Receipts: expected");
}
if !ctx.mutation_classes.is_empty() {
println!(" Mutations: {}", ctx.mutation_classes.join(", "));
}
if !ctx.policies.is_empty() || ctx.receipts_expected || !ctx.mutation_classes.is_empty() {
println!();
}
}
}
fn cmd_inspect_layout(args: &[String]) {
decode_layout_from_source(
args,
"hopper inspect layout <manifest> <hex-data> | --program-id <program-id> [--rpc <url>] <hex-data>",
"Layout Inspect",
);
}
fn render_program_rust_preview(
prog: &ProgramManifest,
filters: &RustEmitFilters,
) -> Result<String, String> {
if let Some(layout_name) = filters.layout.as_deref() {
if !prog.layouts.iter().any(|layout| layout.name == layout_name) {
return Err(format!(
"unknown layout '{}' (available: {})",
layout_name,
prog.layouts
.iter()
.map(|layout| layout.name)
.collect::<Vec<_>>()
.join(", ")
));
}
}
if let Some(instruction_name) = filters.instruction.as_deref() {
if !prog
.instructions
.iter()
.any(|instruction| instruction.name == instruction_name)
{
return Err(format!(
"unknown instruction '{}' (available: {})",
instruction_name,
prog.instructions
.iter()
.map(|instruction| instruction.name)
.collect::<Vec<_>>()
.join(", ")
));
}
}
if let Some(context_name) = filters.context.as_deref() {
if !prog
.contexts
.iter()
.any(|context| context.name == context_name)
{
return Err(format!(
"unknown context '{}' (available: {})",
context_name,
prog.contexts
.iter()
.map(|context| context.name)
.collect::<Vec<_>>()
.join(", ")
));
}
}
let selected_instructions: Vec<&InstructionDescriptor> = prog
.instructions
.iter()
.filter(|instruction| match filters.instruction.as_deref() {
Some(name) => instruction.name == name,
None => true,
})
.collect();
let selected_contexts: Vec<&ContextDescriptor> = prog
.contexts
.iter()
.filter(|context| match filters.context.as_deref() {
Some(name) => context.name == name,
None => true,
})
.collect();
let referenced_layouts: Vec<&str> = if filters.layout.is_none()
&& (filters.instruction.is_some() || filters.context.is_some())
{
let mut names = Vec::new();
for instruction in selected_instructions.iter() {
for account in instruction.accounts.iter() {
if !account.layout_ref.is_empty() && !names.contains(&account.layout_ref) {
names.push(account.layout_ref);
}
}
}
for context in selected_contexts.iter() {
for account in context.accounts.iter() {
if !account.layout_ref.is_empty() && !names.contains(&account.layout_ref) {
names.push(account.layout_ref);
}
}
}
names
} else {
Vec::new()
};
let selected_layouts: Vec<&LayoutManifest> = prog
.layouts
.iter()
.filter(|layout| {
if let Some(name) = filters.layout.as_deref() {
return layout.name == name;
}
if referenced_layouts.is_empty() {
return true;
}
referenced_layouts.contains(&layout.name)
})
.collect();
let mut out = String::new();
out.push_str("// ───────────────────────────────────────────────────────────────\n");
out.push_str("// Hopper lowered Rust preview\n");
out.push_str("// ───────────────────────────────────────────────────────────────\n");
out.push_str("// Generated from ProgramManifest metadata. NOT your source file.\n");
out.push_str("// This is what Hopper's one access model lowers to: indexed accounts,\n");
out.push_str("// const segment offsets, and typed projections. No hidden runtime,\n");
out.push_str("// no reflection, no string lookups in the hot path.\n");
out.push_str("//\n");
out.push_str("// Access model (all three paths share the same pointer arithmetic):\n");
out.push_str("// Tier A ctx.load::<T>(idx)? // validate header + project\n");
out.push_str("// Tier B ctx.segment_mut::<T>(idx, off) // fine-grained segment borrow\n");
out.push_str("// Tier C unsafe ctx.raw_mut::<T>(idx)? // caller owns all validation\n");
out.push_str("// ───────────────────────────────────────────────────────────────\n\n");
out.push_str("use hopper::prelude::*;\n");
out.push_str("use hopper::__runtime::{Ref, RefMut};\n\n");
let module_name = sanitize_ident(&format!("{}_generated", &snake_case(prog.name)));
push_line(&mut out, 0, &format!("pub mod {} {{", module_name));
push_line(
&mut out,
4,
&format!(
"pub const PROGRAM_NAME: &str = \"{}\";",
escape_rust_string(prog.name)
),
);
push_line(
&mut out,
4,
&format!(
"pub const PROGRAM_VERSION: &str = \"{}\";",
escape_rust_string(prog.version)
),
);
push_line(
&mut out,
4,
&format!(
"pub const PROGRAM_DESCRIPTION: &str = \"{}\";",
escape_rust_string(prog.description)
),
);
push_line(&mut out, 4, "pub const HEADER_LEN: usize = 16;");
out.push('\n');
if !selected_layouts.is_empty() {
push_line(&mut out, 4, "pub mod layouts {");
for layout in selected_layouts.iter() {
render_layout_rust_preview(&mut out, layout);
}
push_line(&mut out, 4, "}");
out.push('\n');
}
if !selected_instructions.is_empty() {
push_line(&mut out, 4, "pub mod instructions {");
for instruction in selected_instructions.iter() {
render_instruction_rust_preview(&mut out, instruction);
}
push_line(&mut out, 4, "}");
out.push('\n');
}
if !selected_contexts.is_empty() {
push_line(&mut out, 4, "pub mod contexts {");
for context in selected_contexts.iter() {
render_context_rust_preview(&mut out, context);
}
push_line(&mut out, 4, "}");
out.push('\n');
}
if selected_instructions.is_empty() && selected_contexts.is_empty() {
push_line(
&mut out,
4,
"// No instruction or context metadata was selected.",
);
push_line(&mut out, 4, "// Add --instruction/--context filters only when those descriptors exist in the manifest.");
out.push('\n');
}
push_line(&mut out, 0, "}");
Ok(out)
}
fn render_layout_rust_preview(out: &mut String, layout: &LayoutManifest) {
let module_name = sanitize_ident(&snake_case(layout.name));
push_line(out, 8, &format!("pub mod {} {{", module_name));
push_line(
out,
12,
&format!(
"pub const NAME: &str = \"{}\";",
escape_rust_string(layout.name)
),
);
push_line(out, 12, &format!("pub const DISC: u8 = {};", layout.disc));
push_line(
out,
12,
&format!("pub const VERSION: u8 = {};", layout.version),
);
push_line(
out,
12,
&format!("pub const TOTAL_SIZE: usize = {};", layout.total_size),
);
push_line(
out,
12,
&format!(
"pub const LAYOUT_ID: [u8; 8] = {};",
render_u8_array(&layout.layout_id)
),
);
push_line(out, 12, "pub const TYPE_OFFSET: usize = HEADER_LEN;");
push_line(out, 12, "");
for field in layout.fields.iter() {
let field_name = upper_snake_case(field.name);
let field_end = field.offset as usize + field.size as usize;
push_line(
out,
12,
&format!(
"// {}: {} @ bytes {}..{}",
field.name, field.canonical_type, field.offset, field_end
),
);
push_line(
out,
12,
&format!(
"// pointer path: account.try_borrow()? -> base_ptr.add({}) as *const {}",
field.offset, field.canonical_type
),
);
push_line(
out,
12,
&format!("pub const {}_OFFSET: usize = {};", field_name, field.offset),
);
push_line(
out,
12,
&format!("pub const {}_SIZE: usize = {};", field_name, field.size),
);
push_line(out, 12, "");
}
push_line(out, 8, "}");
out.push('\n');
}
fn render_instruction_rust_preview(out: &mut String, instruction: &InstructionDescriptor) {
let module_name = sanitize_ident(&snake_case(instruction.name));
let reads: Vec<&str> = instruction
.accounts
.iter()
.filter(|account| !account.writable)
.map(|account| account.name)
.collect();
let writes: Vec<&str> = instruction
.accounts
.iter()
.filter(|account| account.writable)
.map(|account| account.name)
.collect();
let signers: Vec<&str> = instruction
.accounts
.iter()
.filter(|account| account.signer)
.map(|account| account.name)
.collect();
push_line(out, 8, &format!("pub mod {} {{", module_name));
push_line(
out,
12,
&format!(
"pub const NAME: &str = \"{}\";",
escape_rust_string(instruction.name)
),
);
push_line(
out,
12,
&format!("pub const TAG: u8 = {};", instruction.tag),
);
push_line(
out,
12,
&format!("pub const READS: &[&str] = &{};", render_str_slice(&reads)),
);
push_line(
out,
12,
&format!(
"pub const WRITES: &[&str] = &{};",
render_str_slice(&writes)
),
);
push_line(
out,
12,
&format!(
"pub const SIGNERS: &[&str] = &{};",
render_str_slice(&signers)
),
);
if !instruction.policy_pack.is_empty() {
push_line(
out,
12,
&format!(
"pub const POLICY_PACK: &str = \"{}\";",
escape_rust_string(instruction.policy_pack)
),
);
}
push_line(
out,
12,
&format!(
"pub const RECEIPT_EXPECTED: bool = {};",
instruction.receipt_expected
),
);
push_line(out, 12, "");
if !instruction.args.is_empty() {
push_line(out, 12, "// Instruction arguments:");
for argument in instruction.args.iter() {
push_line(
out,
12,
&format!(
"// {}: {} ({} bytes)",
argument.name, argument.canonical_type, argument.size
),
);
}
push_line(out, 12, "");
}
render_account_accessor_block(
out,
12,
&format!("{}Accounts", pascal_case(instruction.name)),
instruction
.accounts
.iter()
.map(|account| DerivedAccountDescriptor {
name: account.name,
kind: "AccountView",
writable: account.writable,
signer: account.signer,
layout_ref: account.layout_ref,
policy_ref: "",
seeds: &[],
optional: false,
})
.collect::<Vec<_>>()
.as_slice(),
Some("Generated from InstructionDescriptor account order."),
);
push_line(out, 8, "}");
out.push('\n');
}
fn render_context_rust_preview(out: &mut String, context: &ContextDescriptor) {
let module_name = sanitize_ident(&snake_case(context.name));
push_line(out, 8, &format!("pub mod {} {{", module_name));
push_line(
out,
12,
&format!(
"pub const NAME: &str = \"{}\";",
escape_rust_string(context.name)
),
);
push_line(
out,
12,
&format!(
"pub const POLICIES: &[&str] = &{};",
render_str_slice(context.policies)
),
);
push_line(
out,
12,
&format!(
"pub const MUTATION_CLASSES: &[&str] = &{};",
render_str_slice(context.mutation_classes)
),
);
push_line(
out,
12,
&format!(
"pub const RECEIPTS_EXPECTED: bool = {};",
context.receipts_expected
),
);
push_line(out, 12, "");
let accounts: Vec<DerivedAccountDescriptor<'_>> = context
.accounts
.iter()
.map(|account| DerivedAccountDescriptor {
name: account.name,
kind: account.kind,
writable: account.writable,
signer: account.signer,
layout_ref: account.layout_ref,
policy_ref: account.policy_ref,
seeds: account.seeds,
optional: account.optional,
})
.collect();
render_account_accessor_block(
out,
12,
&format!("{}Context", pascal_case(context.name)),
accounts.as_slice(),
Some("Generated from ContextDescriptor account order."),
);
push_line(out, 8, "}");
out.push('\n');
}
#[derive(Clone, Copy)]
struct DerivedAccountDescriptor<'a> {
name: &'a str,
kind: &'a str,
writable: bool,
signer: bool,
layout_ref: &'a str,
policy_ref: &'a str,
seeds: &'a [&'a str],
optional: bool,
}
fn render_account_accessor_block(
out: &mut String,
indent: usize,
struct_name: &str,
accounts: &[DerivedAccountDescriptor<'_>],
header_note: Option<&str>,
) {
if let Some(note) = header_note {
push_line(out, indent, &format!("// {}", note));
}
push_line(
out,
indent,
&format!("pub struct {};", sanitize_ident(struct_name)),
);
push_line(
out,
indent,
&format!("impl {} {{", sanitize_ident(struct_name)),
);
push_line(
out,
indent + 4,
&format!("pub const ACCOUNT_LEN: usize = {};", accounts.len()),
);
push_line(out, indent + 4, "");
for (index, account) in accounts.iter().enumerate() {
let const_name = format!("{}_INDEX", upper_snake_case(account.name));
push_line(
out,
indent + 4,
&format!("pub const {}: usize = {};", const_name, index),
);
}
push_line(out, indent + 4, "");
for account in accounts.iter() {
let account_fn = sanitize_ident(&format!("{}_account", snake_case(account.name)));
let index_const = format!("{}_INDEX", upper_snake_case(account.name));
let account_getter = if account.writable {
"account_mut"
} else {
"account"
};
push_line(
out,
indent + 4,
&format!(
"// {}: {}{}{}{}",
account.name,
account.kind,
if account.writable { " [mut]" } else { "" },
if account.signer { " [signer]" } else { "" },
if account.optional { " [optional]" } else { "" },
),
);
if !account.layout_ref.is_empty() {
push_line(
out,
indent + 4,
&format!("// layout = {}", account.layout_ref),
);
}
if !account.policy_ref.is_empty() {
push_line(
out,
indent + 4,
&format!("// policy = {}", account.policy_ref),
);
}
if !account.seeds.is_empty() {
push_line(
out,
indent + 4,
&format!("// seeds = [{}]", account.seeds.join(", ")),
);
}
push_line(
out,
indent + 4,
&format!(
"pub fn {}(ctx: &Context<'_>) -> Result<&AccountView, ProgramError> {{",
account_fn
),
);
push_line(
out,
indent + 8,
&format!("ctx.{}(Self::{})", account_getter, index_const),
);
push_line(out, indent + 4, "}");
if !account.layout_ref.is_empty() {
let load_fn = sanitize_ident(&format!("{}_load", snake_case(account.name)));
let raw_ref_fn = sanitize_ident(&format!("{}_raw_ref", snake_case(account.name)));
push_line(
out,
indent + 4,
&format!(
"pub fn {}(ctx: &Context<'_>) -> Result<Ref<'_, {}>, ProgramError> {{",
load_fn, account.layout_ref,
),
);
push_line(
out,
indent + 8,
&format!(
"Self::{}(ctx)?.load::<{}>()",
account_fn, account.layout_ref
),
);
push_line(out, indent + 4, "}");
push_line(
out,
indent + 4,
&format!(
"pub unsafe fn {}(ctx: &Context<'_>) -> Result<Ref<'_, {}>, ProgramError> {{",
raw_ref_fn, account.layout_ref,
),
);
push_line(
out,
indent + 8,
&format!(
"unsafe {{ Self::{}(ctx)?.raw_ref::<{}>() }}",
account_fn, account.layout_ref
),
);
push_line(out, indent + 4, "}");
if account.writable {
let load_mut_fn = sanitize_ident(&format!("{}_load_mut", snake_case(account.name)));
let raw_mut_fn = sanitize_ident(&format!("{}_raw_mut", snake_case(account.name)));
push_line(
out,
indent + 4,
"// Whole-account mutable path. Use Context::segment_mut(...) when you only need a narrower region.",
);
push_line(
out,
indent + 4,
&format!(
"pub fn {}(ctx: &Context<'_>) -> Result<RefMut<'_, {}>, ProgramError> {{",
load_mut_fn, account.layout_ref,
),
);
push_line(
out,
indent + 8,
&format!(
"Self::{}(ctx)?.load_mut::<{}>()",
account_fn, account.layout_ref
),
);
push_line(out, indent + 4, "}");
push_line(
out,
indent + 4,
&format!(
"pub unsafe fn {}(ctx: &Context<'_>) -> Result<RefMut<'_, {}>, ProgramError> {{",
raw_mut_fn,
account.layout_ref,
),
);
push_line(
out,
indent + 8,
&format!(
"unsafe {{ Self::{}(ctx)?.raw_mut::<{}>() }}",
account_fn, account.layout_ref
),
);
push_line(out, indent + 4, "}");
}
}
push_line(out, indent + 4, "");
}
push_line(out, indent, "}");
}
fn render_context_accessor_summary(
context_name: &str,
account: &ContextAccountDescriptor,
) -> String {
let mut accessors = vec![format!("{}_account()", snake_case(account.name))];
if !account.layout_ref.is_empty() {
accessors.push(format!("{}_load()", snake_case(account.name)));
accessors.push(format!("{}_raw_ref()", snake_case(account.name)));
if account.writable {
accessors.push(format!("{}_load_mut()", snake_case(account.name)));
accessors.push(format!("{}_raw_mut()", snake_case(account.name)));
}
}
format!("{} on {}", accessors.join(", "), context_name,)
}
fn format_name_list(names: &[&str]) -> String {
if names.is_empty() {
"(none)".to_string()
} else {
names.join(", ")
}
}
fn push_line(out: &mut String, indent: usize, line: &str) {
for _ in 0..indent {
out.push(' ');
}
out.push_str(line);
out.push('\n');
}
fn render_u8_array(bytes: &[u8]) -> String {
let rendered = bytes
.iter()
.map(|byte| byte.to_string())
.collect::<Vec<_>>()
.join(", ");
format!("[{rendered}]")
}
fn render_str_slice(values: &[&str]) -> String {
if values.is_empty() {
return "[]".to_string();
}
let rendered = values
.iter()
.map(|value| format!("\"{}\"", escape_rust_string(value)))
.collect::<Vec<_>>()
.join(", ");
format!("[{rendered}]")
}
fn escape_rust_string(value: &str) -> String {
value
.replace('\\', "\\\\")
.replace('"', "\\\"")
.replace('\n', "\\n")
}
fn sanitize_ident(value: &str) -> String {
let mut ident = String::new();
for ch in value.chars() {
if ch.is_ascii_alphanumeric() || ch == '_' {
ident.push(ch);
} else {
ident.push('_');
}
}
if ident.is_empty() {
ident.push('_');
}
if ident
.chars()
.next()
.map(|ch| ch.is_ascii_digit())
.unwrap_or(false)
{
ident.insert(0, '_');
}
ident
}
fn snake_case(value: &str) -> String {
let mut out = String::new();
let mut prev_was_lower_or_digit = false;
for ch in value.chars() {
if ch.is_ascii_alphanumeric() {
if ch.is_ascii_uppercase() {
if prev_was_lower_or_digit && !out.ends_with('_') {
out.push('_');
}
out.push(ch.to_ascii_lowercase());
prev_was_lower_or_digit = false;
} else {
out.push(ch.to_ascii_lowercase());
prev_was_lower_or_digit = ch.is_ascii_lowercase() || ch.is_ascii_digit();
}
} else if !out.ends_with('_') {
out.push('_');
prev_was_lower_or_digit = false;
}
}
sanitize_ident(out.trim_matches('_'))
}
fn upper_snake_case(value: &str) -> String {
snake_case(value).to_ascii_uppercase()
}
fn pascal_case(value: &str) -> String {
let mut out = String::new();
let mut capitalize = true;
for ch in value.chars() {
if ch.is_ascii_alphanumeric() {
if capitalize {
out.push(ch.to_ascii_uppercase());
capitalize = false;
} else {
out.push(ch);
}
} else {
capitalize = true;
}
}
sanitize_ident(&out)
}
fn print_compile_usage() {
eprintln!("Usage: hopper compile --emit <target> [<manifest> | --package <name> | --program-id <id>] [--rpc <url>] [--layout <L>] [--instruction <I>] [--context <C>] [--out <path>] [--force] [--lint] [--lint-fail-on-warn]");
eprintln!();
eprintln!("Supported targets:");
eprintln!(" rust Lowered Rust preview (accessors, offsets, pointer path)");
eprintln!(" ts TypeScript client SDK");
eprintln!(" kt Kotlin client SDK");
eprintln!(" py Python client SDK");
eprintln!(" go Go client SDK");
eprintln!(" c C client header");
eprintln!(" rust-client Off-chain Rust client SDK");
eprintln!(" idl Hopper public IDL JSON");
eprintln!(" codama Codama-flavored JSON");
eprintln!(" schema Normalize a supplied or fetched Hopper manifest as JSON");
eprintln!(" manifest Generate hopper.manifest.json from package source (--package required)");
eprintln!();
eprintln!("Inline lint:");
eprintln!(" --lint Run `hopper lint` against the project after emitting");
eprintln!(" the artifact. Errors fail the command; warnings pass.");
eprintln!(" --lint-fail-on-warn Treat lint warnings as errors (implies --lint)");
eprintln!();
eprintln!("For targets other than manifest, omitting a source infers an existing");
eprintln!(
"hopper.manifest.json from the current package. The manifest target requires --package."
);
eprintln!();
eprintln!("Examples:");
eprintln!(" hopper compile --emit rust");
eprintln!(
" hopper compile --emit ts --package hopper-token-2022-vault --out vault.ts --force"
);
eprintln!(" hopper compile --emit idl @hopper.manifest.json --out idl.json");
eprintln!(" hopper compile --emit codama --program-id <program-id> --rpc <url>");
eprintln!(" hopper compile --emit kt --package vault");
eprintln!(" hopper compile --emit py --package vault --out vault_client.py --force");
eprintln!(" hopper compile --emit go --package vault --out vault_client.go --force");
eprintln!(" hopper compile --emit c --package vault --out vault_client.h --force");
eprintln!(" hopper compile --emit schema @hopper.manifest.json --out normalized.json --force");
eprintln!(" hopper compile --emit manifest --package vault");
eprintln!(" hopper compile --emit rust --package vault --lint # one-shot build + lint");
}
fn print_usage() {
println!("hopper-cli: Hopper account inspection, schema tooling, and program management");
println!();
println!("COMMAND FAMILIES:");
println!();
println!(" Compile:");
println!(" hopper compile --emit <rust|ts|kt|py|go|c|rust-client|idl|codama|schema|manifest> [<manifest>|--package <name>|--program-id ...]");
println!(" Emit lowered Rust, client SDKs, IDL JSON, Codama, or manifest");
println!();
println!(" Verify (manifest and release-interface integrity):");
println!(" hopper verify [<manifest>] [<.so>] Check manifest integrity and report layout-anchor diagnostics");
println!(" hopper verify --release <manifest> <.so> Require the exact versioned interface commitment in the ELF");
println!(
" hopper verify --package <name> Infer manifest + .so from a workspace package"
);
println!(" hopper publish-check --package <name> Run interface binding, docs, feature, client, and fuzz gates");
println!(
" hopper audit-check [--strict] [--json] Verify audit evidence, freshness, and blockers"
);
println!(" hopper publish-idl --manifest <path> --program-id <pubkey> [--dry-run]");
println!(" Publish Solana IDL v0.1.0 through Program Metadata (zero Node deps)");
println!(" hopper publish-security --file security.json --program-id <pubkey> [--init] [--read] [--dry-run]");
println!(" Publish, scaffold, or read back the security.txt record (seed \"security\")");
println!(
" hopper publish-manifest --manifest <path> --program-id <pubkey> [--read] [--dry-run]"
);
println!(" Publish or read back the full Hopper manifest (seed \"hopper-manifest\")");
println!(" hopper solana-check [--all] Check SBF crate shape and Hopper entrypoint invariants");
println!(" hopper contention <manifest> Declared write-lock/signature footprint per instruction");
println!(" (--max-block-cost <CU> gates it in CI)");
println!(" hopper fuzz generate --program <manifest> [--out <plan.json>] [--corpus <dir>]");
println!(" Derive seeded cases from every declared contract");
println!(" hopper fuzz check --program <manifest> [--plan <plan.json>]");
println!(
" Fail CI when the committed fuzz plan drifts"
);
println!(
" hopper fuzz run --program <manifest> --adapter <executable> [--plan <plan.json>]"
);
println!(
" Execute cases and required invariant hooks"
);
println!();
println!(" Schema:");
println!(" hopper schema export Schema format reference");
println!(" hopper schema validate <manifest> Validate a program manifest");
println!(" hopper schema diff <old> <new> Field-level diff");
println!();
println!(" Inspect:");
println!(" hopper inspect <hex-data> Decode account header");
println!(" hopper inspect layout <manifest|--program-id ...> <hex> Decode fields using a manifest");
println!(" hopper inspect segments <hex-data> Decode segment map");
println!(" hopper inspect receipt <hex-data> Decode a state receipt");
println!();
println!(" Explain:");
println!(" hopper explain <hex-data> Human-readable headered-account explanation");
println!(" hopper explain account <hex-data> Explicit headered-account explanation");
println!(" hopper explain receipt <hex-data> Explain a receipt in plain English");
println!(" hopper explain compat <old> <new> Explain compatibility report");
println!(" hopper explain policy <pack-name> Explain a named policy pack");
println!(" hopper explain layout <manifest> Explain layout fields, intents, fingerprint");
println!(" hopper explain program <manifest> Explain entire program pipeline");
println!(" hopper explain <tx-signature> Decode a confirmed tx against local or application-provisioned legacy manifests");
println!(" hopper explain <program-id> Fetch an application-provisioned legacy manifest PDA");
println!(" hopper explain instruction <manifest> <tag|name> Explain instruction accounts and policy");
println!(
" hopper explain context <manifest> Explain instruction contexts and account roles"
);
println!();
println!(" Compatibility:");
println!(" hopper compat <v1-json> <v2-json> Compatibility report");
println!(" hopper plan <v1-json> <v2-json> Migration plan with steps");
println!();
println!(" Receipts:");
println!(" hopper receipt <hex-data> Decode and display receipt");
println!();
println!(" Manager:");
println!(" hopper manager summary <manifest|--program-id ...> Program overview");
println!(
" hopper manager identify <manifest|--program-id ...> <hex> Identify account type"
);
println!(" hopper manager decode <manifest|--program-id ...> <hex> Decode all fields");
println!(" hopper manager instruction <manifest|--program-id ...> <tag|name> Instruction details");
println!(" hopper manager layouts <manifest|--program-id ...> List all layouts");
println!(" hopper manager policies <manifest|--program-id ...> List policy packs");
println!(" hopper manager events <manifest|--program-id ...> List events with fields");
println!(" hopper manager fingerprints <manifest|--program-id ...> Show all fingerprints");
println!(" hopper manager compat <manifest|--program-id ...> <hex-old> <hex-new> Compare two accounts");
println!(" hopper manager receipt <hex-64-or-72-bytes> Decode a state receipt");
println!(" hopper manager explain <manifest|--program-id ...> Aggregated summary");
println!(" hopper manager diff <manifest|--program-id ...> <hex-old> <hex-new> Semantic field diff");
println!(" hopper manager simulate <manifest|--program-id ...> <instruction> Preview requirements");
println!();
println!(" Fetch (application-provisioned legacy PDA; no generic Hopper publisher):");
println!(" hopper fetch <program-id> [--rpc <url>] Fetch legacy manifest PDA");
println!(" hopper fetch <program-id> --json [--rpc <url>] Fetch legacy manifest JSON");
println!(
" hopper manager fetch <program-id> [--rpc <url>] Fetch legacy PDA + show summary"
);
println!();
println!(" Lifecycle:");
println!(" hopper init [path] Create a Hopper project (wizard if no path)");
println!(" hopper add [-i|-s|-e <name>] Scaffold an instruction, state, or error into the current project");
println!(" hopper build [--host|--sbf] Build the current project (default: SBF)");
println!(" hopper test Run the current project's host-side tests");
println!(" hopper deploy [--dry-run] [--cluster <c>] [--keypair <p>] [--no-build] Quote or deploy the current SBF program");
println!(
" hopper upgrade --program-id <id> [--cluster <c>] Upgrade a deployed program in place"
);
println!(" hopper close --program-id <id> [--cluster <c>] Close a program/buffer and reclaim rent");
println!(" hopper migrate --program-id <id> [--cluster <c>] Upgrade a program carrying a layout migration");
println!(" hopper dump [--no-build] Disassemble the current SBF artifact");
println!(" hopper clean [-a|--all] Remove target/{{deploy,idl,client,profile,hopper}} (preserves keypairs)");
println!();
println!(" Profiling:");
println!(" hopper profile bench Run the primitive benchmark lab");
println!();
println!(" Interactive:");
println!(" hopper interactive <manifest|--program-id ...> Launch interactive explorer");
println!(" hopper ui <manifest|--program-id ...> Alias for interactive");
println!(" hopper manager interactive <manifest|--program-id ...> Interactive from manager context");
println!();
println!(" Client:");
println!(" hopper client gen --ts <manifest> Generate TypeScript client SDK");
println!(" hopper client gen --kt <manifest> Generate Kotlin client SDK");
println!(" hopper client gen --py <manifest> Generate Python client SDK");
println!(" hopper client gen --go <manifest> Generate Go client SDK");
println!(" hopper client gen --c <manifest> Generate C client header");
println!(" hopper actions gen --program <manifest> --out api/actions Generate Solana Actions route scaffolds");
println!(" hopper mobile gen --program <manifest> --target kotlin|react-native Generate mobile binding stubs");
println!(
" hopper test-gen security --program <manifest> Generate security test matrix scaffold"
);
println!();
println!("Hex data: hex-encoded account bytes (no 0x prefix).");
println!("Manifest arguments accept inline JSON or @path/to/file.json.");
println!("Program IDs: base58-encoded Solana public keys.");
println!("RPC URL: set via --rpc flag, SOLANA_RPC_URL env, or defaults to mainnet.");
}
fn hex_decode(s: &str) -> Result<Vec<u8>, String> {
let s = s.trim();
if !s.len().is_multiple_of(2) {
return Err("Hex string must have even length".to_string());
}
let mut bytes = Vec::with_capacity(s.len() / 2);
let chars: Vec<u8> = s.bytes().collect();
for pair in chars.chunks(2) {
let hi =
hex_nibble(pair[0]).ok_or_else(|| format!("Invalid hex char: {}", pair[0] as char))?;
let lo =
hex_nibble(pair[1]).ok_or_else(|| format!("Invalid hex char: {}", pair[1] as char))?;
bytes.push((hi << 4) | lo);
}
Ok(bytes)
}
fn hex_nibble(c: u8) -> Option<u8> {
match c {
b'0'..=b'9' => Some(c - b'0'),
b'a'..=b'f' => Some(c - b'a' + 10),
b'A'..=b'F' => Some(c - b'A' + 10),
_ => None,
}
}
fn hex_encode(bytes: &[u8]) -> String {
const HEX: &[u8; 16] = b"0123456789abcdef";
let mut s = String::with_capacity(bytes.len() * 2);
for &b in bytes {
s.push(HEX[(b >> 4) as usize] as char);
s.push(HEX[(b & 0xf) as usize] as char);
}
s
}
struct ParsedManifest {
name: String,
disc: u8,
version: u8,
layout_id: [u8; 8],
total_size: usize,
has_dynamic_tail: bool,
fields: Vec<ParsedField>,
}
struct ParsedField {
name: String,
canonical_type: String,
size: u16,
offset: u16,
}
fn parse_manifest_json(json: &str) -> Result<ParsedManifest, String> {
let json = json.trim();
if !json.starts_with('{') || !json.ends_with('}') {
return Err("Expected JSON object".to_string());
}
let name = extract_string(json, "name")?;
let disc = extract_number(json, "disc")? as u8;
let version = extract_number(json, "version")? as u8;
let total_size =
extract_number(json, "total_size").or_else(|_| extract_number(json, "totalSize"))? as usize;
let has_dynamic_tail = if find_after_key(json, "has_dynamic_tail").is_some() {
extract_bool(json, "has_dynamic_tail")?
} else if find_after_key(json, "hasDynamicTail").is_some() {
extract_bool(json, "hasDynamicTail")?
} else {
false
};
let mut lid = [0u8; 8];
match extract_array_u8(json, "layout_id") {
Ok(layout_id) => {
if layout_id.len() != 8 {
return Err("layout_id must be exactly 8 bytes".to_string());
}
lid.copy_from_slice(&layout_id);
}
Err(_) => {
let hex = extract_string(json, "layoutId")
.map_err(|_| "Missing key: layout_id (or layoutId)".to_string())?;
if hex.len() != 16 {
return Err("layoutId hex string must be 16 chars (8 bytes)".to_string());
}
for (i, chunk) in hex.as_bytes().chunks(2).enumerate() {
let s = std::str::from_utf8(chunk).map_err(|_| "layoutId not UTF-8")?;
lid[i] =
u8::from_str_radix(s, 16).map_err(|e| format!("layoutId hex parse: {e}"))?;
}
}
}
let fields = extract_fields(json)?;
Ok(ParsedManifest {
name,
disc,
version,
layout_id: lid,
total_size,
has_dynamic_tail,
fields,
})
}
fn find_after_key<'a>(json: &'a str, key: &str) -> Option<&'a str> {
let pattern = format!("\"{}\"", key);
let mut from = 0;
while let Some(rel) = json[from..].find(&pattern) {
let after_pat = from + rel + pattern.len();
let rest = json[after_pat..].trim_start();
if let Some(value) = rest.strip_prefix(':') {
return Some(value.trim_start());
}
from = after_pat;
}
None
}
fn extract_string(json: &str, key: &str) -> Result<String, String> {
let after = find_after_key(json, key).ok_or_else(|| format!("Missing key: {}", key))?;
if !after.starts_with('"') {
return Err(format!("Expected string value for {}", key));
}
let after = &after[1..]; let end = after.find('"').ok_or("Unterminated string")?;
Ok(after[..end].to_string())
}
fn extract_number(json: &str, key: &str) -> Result<u64, String> {
let after = find_after_key(json, key).ok_or_else(|| format!("Missing key: {}", key))?;
let end = after
.find(|c: char| !c.is_ascii_digit())
.unwrap_or(after.len());
after[..end]
.parse()
.map_err(|e| format!("Invalid number for {}: {}", key, e))
}
fn extract_bool(json: &str, key: &str) -> Result<bool, String> {
let after = find_after_key(json, key).ok_or_else(|| format!("Missing key: {}", key))?;
if after.starts_with("true") {
Ok(true)
} else if after.starts_with("false") {
Ok(false)
} else {
Err(format!("Invalid boolean for {}", key))
}
}
fn extract_array_u8(json: &str, key: &str) -> Result<Vec<u8>, String> {
let after = find_after_key(json, key).ok_or_else(|| format!("Missing key: {}", key))?;
let start = after.find('[').ok_or("Expected [")?;
let end = after.find(']').ok_or("Expected ]")?;
let inner = &after[start + 1..end];
inner
.split(',')
.map(|s| {
s.trim()
.parse::<u8>()
.map_err(|e| format!("Invalid byte: {}", e))
})
.collect()
}
fn extract_fields(json: &str) -> Result<Vec<ParsedField>, String> {
let key = "\"fields\"";
let pos = json.find(key).ok_or("Missing fields array")?;
let after = &json[pos + key.len()..];
let after = after.trim_start().strip_prefix(':').ok_or("Expected :")?;
let after = after.trim_start();
let start = after.find('[').ok_or("Expected [")?;
let after = &after[start + 1..];
let mut fields = Vec::new();
let mut remaining = after;
loop {
remaining = remaining.trim_start();
if remaining.starts_with(']') {
break;
}
if remaining.starts_with(',') {
remaining = &remaining[1..];
continue;
}
if !remaining.starts_with('{') {
break;
}
let end = remaining.find('}').ok_or("Unterminated field object")?;
let obj = &remaining[..=end];
let name = extract_string(obj, "name")?;
let canonical_type = extract_string(obj, "type")?;
let size = extract_number(obj, "size")? as u16;
let offset = extract_number(obj, "offset")? as u16;
fields.push(ParsedField {
name,
canonical_type,
size,
offset,
});
remaining = &remaining[end + 1..];
}
Ok(fields)
}
struct OwnedManifest {
name: String,
disc: u8,
version: u8,
layout_id: [u8; 8],
total_size: usize,
has_dynamic_tail: bool,
field_count: usize,
fields: Vec<OwnedField>,
}
struct OwnedField {
name: String,
canonical_type: String,
size: u16,
offset: u16,
intent: FieldIntent,
}
impl From<ParsedManifest> for OwnedManifest {
fn from(p: ParsedManifest) -> Self {
Self {
name: p.name,
disc: p.disc,
version: p.version,
layout_id: p.layout_id,
total_size: p.total_size,
has_dynamic_tail: p.has_dynamic_tail,
field_count: p.fields.len(),
fields: p
.fields
.into_iter()
.map(|f| OwnedField {
name: f.name,
canonical_type: f.canonical_type,
size: f.size,
offset: f.offset,
intent: FieldIntent::Custom,
})
.collect(),
}
}
}
fn cmd_explain(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper explain <hex-data>");
process::exit(1);
}
let data = match hex_decode(&args[0]) {
Ok(d) => d,
Err(e) => {
eprintln!("Hex decode error: {}", e);
process::exit(1);
}
};
if data.len() < 16 {
println!(
"This data is {} bytes, which is too short for Hopper's headered-account decoder.",
data.len()
);
println!("Compact accounts are not decoded by this command.");
process::exit(1);
}
let header = require_header(&data);
println!(
"Interpreting this as a headered Hopper account ({} bytes total).",
data.len()
);
println!();
println!("Header:");
println!(
" Discriminator {} identifies the account type.",
header.disc
);
println!(
" Layout version {}, fingerprint {}.",
header.version,
hex_encode(&header.layout_id)
);
let flag_str = format_flags(header.flags);
if header.flags == 0 {
println!(" No flags set.");
} else {
println!(" Flags: {} (0x{:04x}).", flag_str, header.flags);
}
println!();
let is_segmented = header.flags & 0x0004 != 0;
let has_registry = data.len() >= 20;
let seg_result = if is_segmented || has_registry {
decode_segments::<16>(&data)
} else {
None
};
match seg_result {
Some((count, segments)) if count > 0 => {
println!("Account structure: segmented ({} segments).", count);
println!();
let reg_end = 16 + 4 + count * 16;
println!(
" Bytes 0..16 are the header, 16..{} is the segment registry.",
reg_end
);
for (i, seg) in segments[..count].iter().enumerate() {
let end = seg.offset as usize + seg.size as usize;
let role_name = decode_segment_role(seg.flags);
println!(
" Segment {} (id {}): bytes {}..{} ({} bytes, role: {}).",
i,
hex_encode(&seg.id),
seg.offset,
end,
seg.size,
role_name,
);
println!(" {}", describe_segment_role(role_name));
}
let advice = SegmentMigrationReport::<16>::analyze(&segments, count);
println!();
println!("Migration readiness:");
println!(
" {} must-preserve, {} clearable, {} rebuildable.",
advice.must_preserve_count(),
advice.clearable_count(),
advice.rebuildable_bytes,
);
println!(
" preserve={} bytes, clearable={} bytes.",
advice.preserve_bytes, advice.clearable_bytes,
);
}
_ => {
let body_size = data.len() - 16;
println!(
"Account structure: fixed layout ({} byte body after header).",
body_size
);
}
}
println!();
if data[0] == 0xFF {
println!("Warning: discriminator is 0xFF. This account may have been closed");
println!("with a sentinel byte to prevent revival.");
println!();
}
let zero_body = data[16..].iter().all(|&b| b == 0);
if zero_body && data.len() > 16 {
println!("Note: the body is entirely zeroed. This account may be freshly");
println!("initialized and still zeroed.");
println!();
}
if is_segmented || seg_result.is_some() {
println!("Policy context:");
println!(" Segmented accounts typically use named policy packs:");
println!(" TREASURY_WRITE -- balance mutations (authority + snapshot + conservation)");
println!(" JOURNAL_TOUCH -- journal appends (authority + capacity + snapshot)");
println!(" AUTHORITY_CHANGE -- permission changes (authority + CPI guard + invariants)");
println!(" Use 'hopper receipt <hex>' to decode which capabilities were declared");
println!(" in a specific transaction.");
println!();
}
println!("Next steps:");
println!(" hopper inspect <hex> -- raw header fields");
println!(" hopper segments <hex> -- segment map with roles");
println!(" hopper receipt <hex> -- decode a state receipt from transaction logs");
println!(" hopper compat <v1> <v2> -- compare against another version");
println!(" hopper plan <v1> <v2> -- generate migration plan");
}
fn decode_segment_role(flags: u16) -> &'static str {
SegmentRoleHint::from_flags(flags).name()
}
fn describe_segment_role(role: &str) -> &'static str {
match role {
"Core" | "core" => "Primary state, must be preserved across migrations.",
"Extension" | "extension" => "Optional extension data, safe to append new fields.",
"Journal" | "journal" => "Append-only log, may wrap if circular. Clearable on migration.",
"Index" | "index" => "Derived lookup data. Can be rebuilt from core state.",
"Cache" | "cache" => "Computed cache. Can be cleared and recomputed on migration.",
"Audit" | "audit" => "Immutable audit trail. Must be preserved.",
"Shard" | "shard" => "Partitioned data. May be split or merged across accounts.",
_ => "No defined migration or runtime semantics.",
}
}
fn cmd_inspect(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper inspect <hex-data>");
process::exit(1);
}
let data = match hex_decode(&args[0]) {
Ok(d) => d,
Err(e) => {
eprintln!("Hex decode error: {}", e);
process::exit(1);
}
};
match decode_header(&data) {
Some(h) => print_header(&h),
None => {
eprintln!(
"Account data too short for header (need 16 bytes, got {})",
data.len()
);
process::exit(1);
}
}
}
fn print_header(h: &DecodedHeader) {
println!("=== Account Header (16 bytes) ===");
println!(" Discriminator : {}", h.disc);
println!(" Version : {}", h.version);
println!(
" Flags : 0x{:04x} ({})",
h.flags,
format_flags(h.flags)
);
println!(" Layout ID : {}", hex_encode(&h.layout_id));
println!(" Schema epoch : {}", h.schema_epoch);
}
fn format_flags(flags: u16) -> String {
if flags == 0 {
return "none".to_string();
}
let mut parts = Vec::new();
if flags & 0x0001 != 0 {
parts.push("INITIALIZED");
}
if flags & 0x0002 != 0 {
parts.push("FROZEN");
}
if flags & 0x0004 != 0 {
parts.push("SEGMENTED");
}
if flags & 0x0008 != 0 {
parts.push("CLOSING");
}
if parts.is_empty() {
format!("0x{:04x}", flags)
} else {
parts.join(" | ")
}
}
fn cmd_segments(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper segments <hex-data>");
process::exit(1);
}
let data = match hex_decode(&args[0]) {
Ok(d) => d,
Err(e) => {
eprintln!("Hex decode error: {}", e);
process::exit(1);
}
};
if let Some(h) = decode_header(&data) {
print_header(&h);
println!();
}
match decode_segments::<16>(&data) {
Some((count, segments)) => {
println!("=== Segment Registry ({} segments) ===", count);
println!(
" {:>4} {:>10} {:>10} {:>8} {:>6} Ver",
"#", "ID", "Offset", "Size", "Flags"
);
println!(" {}", "-".repeat(56));
for (i, seg) in segments[..count].iter().enumerate() {
println!(
" {:>4} {:>10} {:>10} {:>8} 0x{:04x} {:>4}",
i,
hex_encode(&seg.id),
seg.offset,
seg.size,
seg.flags,
seg.version,
);
}
println!();
println!("=== Segment Map ===");
println!(" [Header: 0..16]");
let reg_end = 16 + 4 + count * 16;
println!(" [Registry: 16..{}]", reg_end);
for (i, seg) in segments[..count].iter().enumerate() {
let end = seg.offset as usize + seg.size as usize;
println!(
" [Segment {}: {}..{} ({} bytes, id={})]",
i,
seg.offset,
end,
seg.size,
hex_encode(&seg.id),
);
}
}
None => {
eprintln!("Could not decode segment registry (data too short or invalid)");
process::exit(1);
}
}
}
const RECEIPT_WIRE_SIZE: usize = 72;
const RECEIPT_WIRE_SIZE_LEGACY: usize = 64;
fn valid_receipt_len(len: usize) -> bool {
len == RECEIPT_WIRE_SIZE_LEGACY || len >= RECEIPT_WIRE_SIZE
}
fn receipt_failure_stage_name(stage: u8) -> &'static str {
match stage {
1 => "validation",
2 => "handler",
3 => "invariant",
4 => "post",
5 => "teardown",
_ => "none",
}
}
fn cmd_receipt(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper receipt <hex-data>");
process::exit(1);
}
let data = match hex_decode(&args[0]) {
Ok(d) => d,
Err(e) => {
eprintln!("Hex decode error: {}", e);
process::exit(1);
}
};
if !valid_receipt_len(data.len()) {
eprintln!(
"Receipt data must be exactly {} legacy bytes or at least {} current bytes (got {}).",
RECEIPT_WIRE_SIZE_LEGACY,
RECEIPT_WIRE_SIZE,
data.len(),
);
process::exit(1);
}
let layout_id = &data[0..8];
let changed_fields = u64::from_le_bytes(data[8..16].try_into().expect("slice length mismatch"));
let changed_bytes = u32::from_le_bytes(data[16..20].try_into().expect("slice length mismatch"));
let changed_regions =
u16::from_le_bytes(data[20..22].try_into().expect("slice length mismatch"));
let old_size = u32::from_le_bytes(data[22..26].try_into().expect("slice length mismatch"));
let new_size = u32::from_le_bytes(data[26..30].try_into().expect("slice length mismatch"));
let invariants_checked =
u16::from_le_bytes(data[30..32].try_into().expect("slice length mismatch"));
let flags = data[32];
let was_resized = flags & (1 << 0) != 0;
let invariants_passed = flags & (1 << 1) != 0;
let cpi_invoked = flags & (1 << 2) != 0;
let committed = flags & (1 << 3) != 0;
let had_failure = flags & (1 << 4) != 0;
let before_fp = &data[33..41];
let after_fp = &data[41..49];
let segment_mask = u16::from_le_bytes(data[49..51].try_into().expect("slice length mismatch"));
let policy_flags = u32::from_le_bytes(data[51..55].try_into().expect("slice length mismatch"));
let journal_appends =
u16::from_le_bytes(data[55..57].try_into().expect("slice length mismatch"));
let cpi_count = data[57];
let phase = data[58];
let validation_bundle_id =
u16::from_le_bytes(data[59..61].try_into().expect("slice length mismatch"));
let compat_impact = data[61];
let migration_flags = data[62];
let (failed_invariant_idx, failed_error_code, failure_stage) =
if data.len() >= RECEIPT_WIRE_SIZE {
(
data[63],
u32::from_le_bytes(data[64..68].try_into().expect("slice length mismatch")),
data[68],
)
} else {
(0xFF, 0, 0)
};
let phase_name = match phase {
1 => "init",
2 => "close",
3 => "migrate",
4 => "read-only",
_ => "update",
};
let compat_name = match compat_impact {
1 => "append",
2 => "migration",
3 => "breaking",
_ => "none",
};
println!("=== State Receipt ({} bytes) ===", data.len());
println!(
" Wire format : {}",
if data.len() == RECEIPT_WIRE_SIZE_LEGACY {
"legacy 64-byte"
} else {
"current 72-byte"
}
);
println!();
println!(" Layout ID : {}", hex_encode(layout_id));
println!(
" Committed : {}",
if committed { "YES" } else { "NO" }
);
println!(" Phase : {}", phase_name);
println!();
println!(" Changed bytes : {}", changed_bytes);
println!(" Changed regions : {}", changed_regions);
println!(" Changed field mask : 0x{:016x}", changed_fields);
if changed_fields != 0 {
let mut fields_list = Vec::new();
for bit in 0..64u32 {
if changed_fields & (1u64 << bit) != 0 {
fields_list.push(format!("{}", bit));
}
}
println!(" Fields touched : [{}]", fields_list.join(", "));
}
println!();
println!(" Old size : {} bytes", old_size);
println!(" New size : {} bytes", new_size);
println!(
" Resized : {}",
if was_resized { "YES" } else { "NO" }
);
println!();
println!(" Before fingerprint : {}", hex_encode(before_fp));
println!(" After fingerprint : {}", hex_encode(after_fp));
let fp_changed = before_fp != after_fp;
println!(
" Data changed : {}",
if fp_changed { "YES" } else { "NO" }
);
println!();
println!(" Invariants checked : {}", invariants_checked);
println!(
" Invariants passed : {}",
if invariants_passed { "YES" } else { "NO" }
);
println!();
if policy_flags != 0 {
println!(" Policy flags : 0x{:08x}", policy_flags);
let cap_names = [
"ReadsState",
"MutatesState",
"TouchesJournal",
"ExternalCall",
"MutatesTreasury",
"ReallocatesAccount",
"CreatesAccount",
"ClosesAccount",
"ModifiesAuthority",
"TransitionsState",
];
let mut active = Vec::new();
for (i, name) in cap_names.iter().enumerate() {
if policy_flags & (1 << i) != 0 {
active.push(*name);
}
}
if !active.is_empty() {
println!(" Capabilities : {}", active.join(", "));
}
println!();
}
if segment_mask != 0 {
println!(" Segment change mask : 0x{:04x}", segment_mask);
let mut segs = Vec::new();
for bit in 0..16u32 {
if segment_mask & (1 << bit) != 0 {
segs.push(format!("{}", bit));
}
}
println!(" Segments touched : [{}]", segs.join(", "));
println!();
}
if journal_appends > 0 {
println!(" Journal appends : {}", journal_appends);
}
if cpi_invoked {
println!(" CPI invoked : YES ({} calls)", cpi_count);
}
if validation_bundle_id != 0 {
println!(" Validation bundle : {}", validation_bundle_id);
}
if compat_impact != 0 {
println!(" Compat impact : {}", compat_name);
}
if migration_flags != 0 {
let mut mig = Vec::new();
if migration_flags & 1 != 0 {
mig.push("triggered");
}
if migration_flags & 2 != 0 {
mig.push("realloc");
}
if migration_flags & 4 != 0 {
mig.push("schema-bump");
}
println!(" Migration : {}", mig.join(", "));
}
if had_failure || data.len() >= RECEIPT_WIRE_SIZE {
println!(
" Failure recorded : {}",
if had_failure { "YES" } else { "NO" }
);
println!(
" Failure stage : {}",
receipt_failure_stage_name(failure_stage)
);
println!(" Failed invariant : 0x{:02x}", failed_invariant_idx);
println!(" Failed error code : {}", failed_error_code);
}
}
fn cmd_compat(args: &[String]) {
let (why, operands) = match args.first().map(String::as_str) {
Some("--why") => (true, &args[1..]),
_ => (false, args),
};
if operands.len() != 2 {
eprintln!("Usage: hopper compat [--why] <v1-json> <v2-json>");
process::exit(1);
}
if why {
cmd_explain_compat(operands);
return;
}
let v1 = parse_or_exit(&operands[0]);
let v2 = parse_or_exit(&operands[1]);
let (m1, _f1) = to_manifest(&v1);
let (m2, _f2) = to_manifest(&v2);
let verdict = CompatibilityVerdict::between(&m1, &m2);
println!("=== Compatibility Report ===");
println!(
" {} v{} -> {} v{}",
v1.name, v1.version, v2.name, v2.version
);
println!(" Layout ID (old) : {}", hex_encode(&v1.layout_id));
println!(" Layout ID (new) : {}", hex_encode(&v2.layout_id));
println!(" Size (old) : {} bytes", v1.total_size);
println!(" Size (new) : {} bytes", v2.total_size);
println!(" Verdict : {}", verdict.name());
println!(
" Safe : {}",
if verdict.is_safe() { "YES" } else { "NO" }
);
println!(
" Backward-read : {}",
if verdict.is_backward_readable() {
"YES"
} else {
"NO"
}
);
println!(
" Requires migration: {}",
if verdict.requires_migration() {
"YES"
} else {
"NO"
}
);
println!();
match verdict {
CompatibilityVerdict::Identical => {
println!(" Result: No changes detected.");
}
CompatibilityVerdict::WireCompatible => {
println!(
" Result: Wire-compatible. Byte layout identical, semantic metadata differs."
);
}
CompatibilityVerdict::AppendSafe => {
println!(" Result: Safe upgrade. Old field prefix preserved, no migration needed.");
}
CompatibilityVerdict::MigrationRequired => {
println!(" Result: Migration required. Use `hopper plan` for details.");
}
CompatibilityVerdict::Incompatible => {
println!(" Result: Breaking change. Full migration required before upgrade.");
}
}
}
fn cmd_diff(args: &[String]) {
if args.len() < 2 {
eprintln!("Usage: hopper diff <v1-json> <v2-json>");
process::exit(1);
}
let v1 = parse_or_exit(&args[0]);
let v2 = parse_or_exit(&args[1]);
let (m1, _f1) = to_manifest(&v1);
let (m2, _f2) = to_manifest(&v2);
let report = compare_fields::<32>(&m1, &m2);
println!(
"=== Field Diff: {} v{} -> {} v{} ===",
v1.name, v1.version, v2.name, v2.version
);
println!(" {:>20} {:>12} {:>8}", "Field", "Status", "Detail");
println!(" {}", "-".repeat(46));
for i in 0..report.len() {
if let Some(entry) = report.get(i) {
let status_str = match entry.status {
FieldCompat::Identical => "IDENTICAL",
FieldCompat::Changed => "CHANGED",
FieldCompat::Added => "ADDED",
FieldCompat::Removed => "REMOVED",
};
let detail = match entry.status {
FieldCompat::Added => {
let mut d = String::new();
for f in &v2.fields {
if f.name == entry.name {
d = format!("{} ({} bytes @ {})", f.canonical_type, f.size, f.offset);
break;
}
}
d
}
FieldCompat::Removed => "(deleted)".to_string(),
FieldCompat::Changed => "(type or size changed)".to_string(),
FieldCompat::Identical => "".to_string(),
};
println!(" {:>20} {:>12} {}", entry.name, status_str, detail);
}
}
println!();
let identical = report.count_status(FieldCompat::Identical);
let added = report.count_status(FieldCompat::Added);
let removed = report.count_status(FieldCompat::Removed);
let changed = report.count_status(FieldCompat::Changed);
println!(
" Summary: {} identical, {} added, {} removed, {} changed",
identical, added, removed, changed
);
println!(
" Append-safe: {}",
if report.is_append_safe { "YES" } else { "NO" }
);
}
fn cmd_plan(args: &[String]) {
if args.len() < 2 {
eprintln!("Usage: hopper plan <v1-json> <v2-json>");
process::exit(1);
}
let v1 = parse_or_exit(&args[0]);
let v2 = parse_or_exit(&args[1]);
let (m1, _f1) = to_manifest(&v1);
let (m2, _f2) = to_manifest(&v2);
let plan = MigrationPlan::<16>::generate(&m1, &m2);
println!(
"=== Migration Plan: {} v{} -> {} v{} ===",
v1.name, v1.version, v2.name, v2.version
);
println!();
let policy_str = match plan.policy {
MigrationPolicy::NoOp => "NO-OP (layouts identical)",
MigrationPolicy::AppendOnly => "APPEND-ONLY (safe in-place upgrade)",
MigrationPolicy::RequiresMigration => "FULL MIGRATION (data copy required)",
MigrationPolicy::Incompatible => "INCOMPATIBLE (different discriminators)",
};
println!(" Policy : {}", policy_str);
println!(" Old size : {} bytes", plan.old_size);
println!(" New size : {} bytes", plan.new_size);
println!(" Copy bytes : {}", plan.copy_bytes);
println!(" Zero bytes : {}", plan.zero_bytes);
println!(
" Backward : {}",
if plan.backward_readable {
"YES (v1 code can read v2 accounts)"
} else {
"NO"
}
);
println!(" Steps : {}", plan.len());
if !plan.is_empty() {
println!();
println!(
" {:>4} {:>14} {:>8} {:>8} Field",
"#", "Action", "Offset", "Size"
);
println!(" {}", "-".repeat(52));
plan.for_each_step(|i, step| {
let action_str = match step.action {
MigrationAction::CopyPrefix => "CopyPrefix",
MigrationAction::ZeroInit => "ZeroInit",
MigrationAction::UpdateHeader => "UpdateHeader",
MigrationAction::Realloc => "Realloc",
};
let field = if step.field.is_empty() {
"-"
} else {
step.field
};
println!(
" {:>4} {:>14} {:>8} {:>8} {}",
i, action_str, step.offset, step.size, field
);
});
}
}
fn cmd_schema_export_family(args: &[String]) {
if args.is_empty() {
cmd_schema_export();
return;
}
match args[0].as_str() {
"--manifest" => {
if args.len() < 2 {
eprintln!("Usage: hopper schema export --manifest <manifest-json>");
process::exit(1);
}
let prog = load_program_manifest(&args[1]);
println!("{}", hopper_schema::codama::ManifestJson(&prog));
}
"--idl" => {
if args.len() < 2 {
eprintln!("Usage: hopper schema export --idl <manifest-json>");
process::exit(1);
}
let prog = load_program_manifest(&args[1]);
println!("{}", hopper_schema::codama::IdlJsonFromManifest(&prog));
}
"--codama" => {
if args.len() < 2 {
eprintln!("Usage: hopper schema export --codama <manifest-json>");
process::exit(1);
}
let prog = load_program_manifest(&args[1]);
println!("{}", hopper_schema::codama::CodamaJsonFromManifest(&prog));
}
"--anchor-idl" => {
if args.len() != 4 || args[2] != "--program-id" {
eprintln!(
"Usage: hopper schema export --anchor-idl <manifest-json> --program-id <pubkey>"
);
process::exit(1);
}
let program_id = &args[3];
let decoded = bs58::decode(program_id).into_vec().unwrap_or_else(|error| {
eprintln!("invalid base58 program id: {error}");
process::exit(1);
});
if decoded.len() != 32 {
eprintln!("program id must be 32 bytes, got {}", decoded.len());
process::exit(1);
}
let prog = load_program_manifest(&args[1]);
let projection = hopper_schema::anchor_idl::AnchorIdlFromManifest {
manifest: &prog,
address: program_id,
};
if let Err(error) = projection.validate() {
eprintln!("cannot export a complete Solana IDL v0.1.0: {error}");
process::exit(1);
}
println!("{projection}");
}
_ => cmd_schema_export(),
}
}
fn cmd_schema_export() {
println!("=== Hopper Account Schema Format ===");
println!();
println!("Header (16 bytes, offset 0):");
println!(" [0] disc u8 Account discriminator");
println!(" [1] version u8 Layout version");
println!(" [2..4] flags u16 LE Status flags");
println!(" [4..12] layout_id [u8;8] SHA-256 fingerprint (first 8 bytes)");
println!(" [12..16] schema_epoch u32 LE Schema evolution epoch");
println!();
println!("Flags (bits):");
println!(" 0x0001 INITIALIZED");
println!(" 0x0002 FROZEN");
println!(" 0x0004 SEGMENTED");
println!(" 0x0008 CLOSING");
println!();
println!("Layout ID computation:");
println!(" sha256(\"hopper:v1:{{Name}}:{{version}}:{{field}}:{{type}}:{{size}},...\")[..8]");
println!();
println!("Segment Registry (for segmented accounts):");
println!(" [+0..2] count u16 LE Number of segments");
println!(" [+2..4] reserved u16 LE Reserved");
println!(" For each segment (16 bytes):");
println!(" [+0..4] id [u8;4] FNV-1a hash of segment name");
println!(" [+4..8] offset u32 LE Byte offset in account data");
println!(" [+8..12] size u32 LE Segment size in bytes");
println!(" [+12..14] flags u16 LE Segment flags (includes role in bits 12-15)");
println!(" [+14] version u8 Segment version");
println!(" [+15] reserved u8 Reserved");
println!();
println!("Segment Roles (upper 4 bits of segment flags):");
println!(" 0x0000 Unclassified");
println!(" 0x1000 Core -- primary state, must preserve");
println!(" 0x2000 Extension -- optional fields, must preserve");
println!(" 0x3000 Journal -- append-only log, clearable on migration");
println!(" 0x4000 Index -- derived lookup, rebuildable");
println!(" 0x5000 Cache -- computed cache, rebuildable");
println!(" 0x6000 Audit -- immutable trail, must preserve");
println!(" 0x7000 Shard -- partitioned data, must preserve");
println!();
println!("State Receipt (72 bytes current, 64-byte legacy prefix supported):");
println!(" [0..8] layout_id [u8;8] Source layout fingerprint");
println!(" [8..16] changed_fields u64 LE Changed field bitmask");
println!(" [16..20] changed_bytes u32 LE Byte count of changes");
println!(" [20..22] changed_regions u16 LE Number of changed regions");
println!(" [22..26] old_size u32 LE Size before mutation");
println!(" [26..30] new_size u32 LE Size after mutation");
println!(" [30..32] inv_checked u16 LE Invariants checked count");
println!(" [32] flags u8 resized/passed/CPI/committed/failure bits");
println!(" [33..41] before_fp [u8;8] Fingerprint before mutation");
println!(" [41..49] after_fp [u8;8] Fingerprint after mutation");
println!(" [49..51] segment_mask u16 LE Bitmask of changed segments");
println!(" [51..55] policy_flags u32 LE Capability bitmask");
println!(" [55..57] journal_appends u16 LE Journal append count");
println!(" [57] cpi_count u8 CPI invocation count");
println!(" [58] phase u8 Instruction phase tag");
println!(" [59..61] validation_bundle_id u16 LE Program-defined validation bundle");
println!(" [61] compat_impact u8 Compatibility impact tag");
println!(" [62] migration_flags u8 Migration flags");
println!(" [63] failed_invariant_idx u8 0xFF = none");
println!(" [64..68] failed_error_code u32 LE 0 = none");
println!(" [68] failure_stage u8 FailureStage tag");
println!(" [69..72] reserved [u8;3] Reserved");
println!();
println!("Policy Capability Bits (in receipt policy_flags):");
println!(" bit 0 ReadsState");
println!(" bit 1 MutatesState");
println!(" bit 2 TouchesJournal");
println!(" bit 3 ExternalCall");
println!(" bit 4 MutatesTreasury");
println!(" bit 5 ReallocatesAccount");
println!(" bit 6 CreatesAccount");
println!(" bit 7 ClosesAccount");
println!(" bit 8 ModifiesAuthority");
println!(" bit 9 TransitionsState");
println!();
println!("Named Policy Packs:");
println!(" TREASURY_WRITE MutatesState + MutatesTreasury");
println!(" JOURNAL_TOUCH MutatesState + TouchesJournal");
println!(" EXTERNAL_CALL ExternalCall");
println!(" SHARD_MUTATION MutatesState");
println!(" MIGRATION_SENSITIVE MutatesState + ReallocatesAccount");
println!(" AUTHORITY_CHANGE MutatesState + ModifiesAuthority");
println!();
println!("--- Layout Manifest JSON ---");
println!(" {{");
println!(" \"name\": \"Vault\",");
println!(" \"disc\": 1,");
println!(" \"version\": 1,");
println!(" \"layout_id\": [1,2,3,4,5,6,7,8],");
println!(" \"total_size\": 57,");
println!(" \"fields\": [");
println!(" {{\"name\":\"authority\",\"type\":\"[u8;32]\",\"size\":32,\"offset\":16}},");
println!(" {{\"name\":\"balance\",\"type\":\"WireU64\",\"size\":8,\"offset\":48}},");
println!(" {{\"name\":\"bump\",\"type\":\"u8\",\"size\":1,\"offset\":56}}");
println!(" ]");
println!(" }}");
println!();
println!("--- Program Manifest JSON (for Hopper Manager) ---");
println!(" {{");
println!(" \"name\": \"my_program\",");
println!(" \"version\": \"0.3.0\",");
println!(" \"description\": \"Program description\",");
println!(" \"layouts\": [");
println!(" {{ <layout manifest as above> }}");
println!(" ],");
println!(" \"instructions\": [");
println!(" {{");
println!(" \"name\": \"deposit\",");
println!(" \"tag\": 1,");
println!(" \"args\": [{{\"name\":\"amount\",\"type\":\"WireU64\",\"size\":8}}],");
println!(" \"accounts\": [");
println!(" {{\"name\":\"vault\",\"writable\":true,\"signer\":false,\"layout_ref\":\"VaultState\"}}");
println!(" ],");
println!(" \"capabilities\": [\"MutatesState\",\"MutatesTreasury\"],");
println!(" \"policy_pack\": \"TREASURY_WRITE\",");
println!(" \"receipt_expected\": true");
println!(" }}");
println!(" ],");
println!(" \"events\": [");
println!(" {{");
println!(" \"name\": \"DepositEvent\",");
println!(" \"tag\": 1,");
println!(" \"fields\": [{{\"name\":\"amount\",\"type\":\"WireU64\",\"size\":8,\"offset\":0}}]");
println!(" }}");
println!(" ],");
println!(" \"policies\": [");
println!(" {{");
println!(" \"name\": \"TREASURY_WRITE\",");
println!(" \"capabilities\": [\"MutatesState\",\"MutatesTreasury\"],");
println!(" \"requirements\": [\"SignerAuthority\",\"SnapshotCommit\"]");
println!(" }}");
println!(" ]");
println!(" }}");
println!();
println!("Use 'hopper manager summary @manifest.json' to inspect a program manifest.");
println!("Use 'hopper manager decode @manifest.json <hex>' to decode account fields.");
}
fn resolve_manifest_arg(arg: &str) -> String {
if let Some(path) = arg.strip_prefix('@') {
match std::fs::read_to_string(path) {
Ok(contents) => contents,
Err(e) => {
eprintln!("Could not read manifest file '{}': {}", path, e);
process::exit(1);
}
}
} else {
arg.to_string()
}
}
struct OwnedProgramManifest {
name: String,
version: String,
description: String,
layouts: Vec<OwnedManifest>,
instructions: Vec<OwnedInstruction>,
events: Vec<OwnedEvent>,
policies: Vec<OwnedPolicy>,
layout_metadata: Vec<OwnedLayoutMetadata>,
compatibility_pairs: Vec<OwnedCompatibilityPair>,
tooling_hints: Vec<String>,
contexts: Vec<OwnedContext>,
}
struct OwnedInstruction {
name: String,
tag: u8,
discriminator: Vec<u8>,
args: Vec<OwnedArg>,
accounts: Vec<OwnedAccount>,
remaining_accounts_max: Option<u16>,
capabilities: Vec<String>,
policy_pack: String,
receipt_expected: bool,
strict_writes: bool,
write_ranges: Vec<OwnedWriteRange>,
parametric_write_ranges: Vec<OwnedParametricWriteRange>,
mutation_complete: bool,
lamport_accounts: Vec<u8>,
cu_estimate: u32,
}
struct OwnedWriteRange {
account_index: u8,
offset: u32,
size: u32,
}
struct OwnedParametricWriteRange {
account_index: u8,
base_offset: u32,
stride: u32,
cell_size: u32,
count: u32,
argument_index: u8,
argument: String,
segment: String,
}
struct OwnedArg {
name: String,
canonical_type: String,
size: u16,
encoding: OwnedArgEncoding,
max_len: u16,
element_size: u16,
}
#[derive(Clone, Copy)]
enum OwnedArgEncoding {
Fixed,
BoundedVec,
BoundedString,
}
struct OwnedAccount {
name: String,
writable: bool,
signer: bool,
layout_ref: String,
seeds: Vec<String>,
}
struct OwnedEvent {
name: String,
tag: u8,
fields: Vec<OwnedField>,
}
struct OwnedPolicy {
name: String,
capabilities: Vec<String>,
requirements: Vec<String>,
invariants: Vec<String>,
receipt_profile: String,
}
struct OwnedLayoutMetadata {
name: String,
segment_roles: Vec<String>,
append_safe: bool,
migration_required: bool,
rebuildable: bool,
policy_pack: String,
invariant_pack: Vec<String>,
receipt_profile: String,
phase_requirements: Vec<String>,
trust_profile: String,
manager_hints: Vec<String>,
}
struct OwnedCompatibilityPair {
from_layout: String,
from_version: u8,
to_layout: String,
to_version: u8,
policy: MigrationPolicy,
backward_readable: bool,
}
struct OwnedContext {
name: String,
instructions: Vec<String>,
accounts: Vec<OwnedContextAccount>,
policies: Vec<String>,
receipts_expected: bool,
mutation_classes: Vec<String>,
strict_writes: bool,
write_ranges: Vec<OwnedWriteRange>,
parametric_write_ranges: Vec<OwnedParametricWriteRange>,
mutation_complete: bool,
lamport_accounts: Vec<u8>,
}
struct OwnedContextAccount {
name: String,
kind: String,
writable: bool,
signer: bool,
layout_ref: String,
policy_ref: String,
seeds: Vec<String>,
optional: bool,
lifecycle: AccountLifecycle,
payer: String,
init_space: u32,
has_one: Vec<String>,
expected_address: String,
expected_owner: String,
}
fn parse_program_manifest_json(json: &str) -> Result<OwnedProgramManifest, String> {
use serde_json::{Map, Value};
fn object<'a>(value: &'a Value, label: &str) -> Result<&'a Map<String, Value>, String> {
value
.as_object()
.ok_or_else(|| format!("{label} must be a JSON object"))
}
fn value_for<'a>(obj: &'a Map<String, Value>, keys: &[&str]) -> Option<&'a Value> {
keys.iter().find_map(|key| obj.get(*key))
}
fn string(obj: &Map<String, Value>, keys: &[&str], default: &str) -> Result<String, String> {
match value_for(obj, keys) {
Some(value) => value
.as_str()
.map(str::to_string)
.ok_or_else(|| format!("{} must be a string", keys[0])),
None => Ok(default.to_string()),
}
}
fn required_string(obj: &Map<String, Value>, keys: &[&str]) -> Result<String, String> {
let value = string(obj, keys, "")?;
if value.is_empty() {
Err(format!("missing required string {}", keys[0]))
} else {
Ok(value)
}
}
fn number(obj: &Map<String, Value>, keys: &[&str], default: u64) -> Result<u64, String> {
match value_for(obj, keys) {
Some(value) => value
.as_u64()
.ok_or_else(|| format!("{} must be an unsigned integer", keys[0])),
None => Ok(default),
}
}
fn boolean(obj: &Map<String, Value>, keys: &[&str], default: bool) -> Result<bool, String> {
match value_for(obj, keys) {
Some(value) => value
.as_bool()
.ok_or_else(|| format!("{} must be a boolean", keys[0])),
None => Ok(default),
}
}
fn array<'a>(obj: &'a Map<String, Value>, keys: &[&str]) -> Result<&'a [Value], String> {
match value_for(obj, keys) {
Some(value) => value
.as_array()
.map(Vec::as_slice)
.ok_or_else(|| format!("{} must be an array", keys[0])),
None => Ok(&[]),
}
}
fn strings(obj: &Map<String, Value>, keys: &[&str]) -> Result<Vec<String>, String> {
array(obj, keys)?
.iter()
.map(|value| {
value
.as_str()
.map(str::to_string)
.ok_or_else(|| format!("{} entries must be strings", keys[0]))
})
.collect()
}
fn as_u8(value: u64, label: &str) -> Result<u8, String> {
u8::try_from(value).map_err(|_| format!("{label} exceeds u8"))
}
fn as_u16(value: u64, label: &str) -> Result<u16, String> {
u16::try_from(value).map_err(|_| format!("{label} exceeds u16"))
}
fn as_u32(value: u64, label: &str) -> Result<u32, String> {
u32::try_from(value).map_err(|_| format!("{label} exceeds u32"))
}
fn byte_array(obj: &Map<String, Value>, keys: &[&str]) -> Result<Vec<u8>, String> {
array(obj, keys)?
.iter()
.map(|value| {
value
.as_u64()
.ok_or_else(|| format!("{} entries must be bytes", keys[0]))
.and_then(|value| as_u8(value, keys[0]))
})
.collect()
}
fn layout_id(obj: &Map<String, Value>) -> Result<[u8; 8], String> {
if let Some(value) = value_for(obj, &["layoutId"]) {
let hex = value
.as_str()
.ok_or_else(|| "layoutId must be a hex string".to_string())?;
if hex.len() != 16 {
return Err("layoutId must contain exactly 8 bytes".to_string());
}
let mut out = [0u8; 8];
for (index, chunk) in hex.as_bytes().chunks_exact(2).enumerate() {
let pair = std::str::from_utf8(chunk).map_err(|_| "layoutId is not UTF-8")?;
out[index] = u8::from_str_radix(pair, 16)
.map_err(|error| format!("invalid layoutId: {error}"))?;
}
return Ok(out);
}
let bytes = byte_array(obj, &["layout_id"])?;
bytes
.try_into()
.map_err(|_| "layout_id must contain exactly 8 bytes".to_string())
}
fn field_intent(value: &str) -> Result<FieldIntent, String> {
let intent = match value {
"balance" => FieldIntent::Balance,
"authority" => FieldIntent::Authority,
"timestamp" => FieldIntent::Timestamp,
"counter" => FieldIntent::Counter,
"index" => FieldIntent::Index,
"basis_points" => FieldIntent::BasisPoints,
"flag" => FieldIntent::Flag,
"address" => FieldIntent::Address,
"hash" => FieldIntent::Hash,
"pda_seed" => FieldIntent::PDASeed,
"version" => FieldIntent::Version,
"bump" => FieldIntent::Bump,
"nonce" => FieldIntent::Nonce,
"supply" => FieldIntent::Supply,
"limit" => FieldIntent::Limit,
"threshold" => FieldIntent::Threshold,
"owner" => FieldIntent::Owner,
"delegate" => FieldIntent::Delegate,
"status" => FieldIntent::Status,
"custom" => FieldIntent::Custom,
_ => return Err(format!("unknown field intent `{value}`")),
};
Ok(intent)
}
fn arg_encoding(value: &str) -> Result<OwnedArgEncoding, String> {
match value {
"fixed" => Ok(OwnedArgEncoding::Fixed),
"boundedVec" => Ok(OwnedArgEncoding::BoundedVec),
"boundedString" => Ok(OwnedArgEncoding::BoundedString),
_ => Err(format!("unknown argument encoding `{value}`")),
}
}
fn account_lifecycle(value: &str) -> Result<AccountLifecycle, String> {
let normalized: String = value
.trim()
.chars()
.filter(|character| !matches!(character, '_' | '-'))
.map(|character| character.to_ascii_lowercase())
.collect();
match normalized.as_str() {
"existing" => Ok(AccountLifecycle::Existing),
"init" | "create" => Ok(AccountLifecycle::Init),
"initifneeded" | "createifneeded" => Ok(AccountLifecycle::InitIfNeeded),
"realloc" | "reallocate" => Ok(AccountLifecycle::Realloc),
"close" => Ok(AccountLifecycle::Close),
_ => Err(format!("unknown account lifecycle `{value}`")),
}
}
fn write_ranges(
obj: &Map<String, Value>,
keys: &[&str],
) -> Result<Vec<OwnedWriteRange>, String> {
array(obj, keys)?
.iter()
.map(|value| {
let range = object(value, "write range")?;
Ok(OwnedWriteRange {
account_index: as_u8(
number(range, &["accountIndex", "account_index"], 0)?,
"accountIndex",
)?,
offset: as_u32(number(range, &["offset"], 0)?, "offset")?,
size: as_u32(number(range, &["size"], 0)?, "size")?,
})
})
.collect()
}
fn parametric_ranges(
obj: &Map<String, Value>,
keys: &[&str],
) -> Result<Vec<OwnedParametricWriteRange>, String> {
array(obj, keys)?
.iter()
.map(|value| {
let range = object(value, "parametric write range")?;
Ok(OwnedParametricWriteRange {
account_index: as_u8(
number(range, &["accountIndex", "account_index"], 0)?,
"accountIndex",
)?,
base_offset: as_u32(
number(range, &["baseOffset", "base_offset"], 0)?,
"baseOffset",
)?,
stride: as_u32(number(range, &["stride"], 0)?, "stride")?,
cell_size: as_u32(number(range, &["cellSize", "cell_size"], 0)?, "cellSize")?,
count: as_u32(number(range, &["count"], 0)?, "count")?,
argument_index: as_u8(
number(range, &["argumentIndex", "argument_index"], 0)?,
"argumentIndex",
)?,
argument: required_string(
range,
&["argument", "argumentName", "argument_name"],
)?,
segment: required_string(range, &["segment", "segmentName", "segment_name"])?,
})
})
.collect()
}
let root: Value = serde_json::from_str(json)
.map_err(|error| format!("invalid program manifest JSON: {error}"))?;
let root = object(&root, "program manifest")?;
let name = required_string(root, &["name"])?;
let version = string(root, &["version"], "0.1.0")?;
let description = string(root, &["description"], "")?;
let mut layouts = Vec::new();
for value in array(root, &["layouts"])? {
let layout = object(value, "layout")?;
let mut fields = Vec::new();
for value in array(layout, &["fields"])? {
let field = object(value, "layout field")?;
fields.push(OwnedField {
name: required_string(field, &["name"])?,
canonical_type: required_string(
field,
&["type", "canonicalType", "canonical_type"],
)?,
size: as_u16(number(field, &["size"], 0)?, "field size")?,
offset: as_u16(number(field, &["offset"], 0)?, "field offset")?,
intent: field_intent(&string(field, &["intent"], "custom")?)?,
});
}
let field_count = usize::try_from(number(
layout,
&["fieldCount", "field_count"],
fields.len() as u64,
)?)
.map_err(|_| "fieldCount exceeds usize".to_string())?;
layouts.push(OwnedManifest {
name: required_string(layout, &["name"])?,
disc: as_u8(number(layout, &["disc"], 0)?, "layout disc")?,
version: as_u8(number(layout, &["version"], 0)?, "layout version")?,
layout_id: layout_id(layout)?,
total_size: usize::try_from(number(layout, &["totalSize", "total_size"], 0)?)
.map_err(|_| "totalSize exceeds usize".to_string())?,
has_dynamic_tail: boolean(layout, &["hasDynamicTail", "has_dynamic_tail"], false)?,
field_count,
fields,
});
}
let mut instructions = Vec::new();
for value in array(root, &["instructions"])? {
let instruction = object(value, "instruction")?;
let ix_name = required_string(instruction, &["name"])?;
let tag = as_u8(number(instruction, &["tag"], 0)?, "instruction tag")?;
let mut args = Vec::new();
for value in array(instruction, &["args"])? {
let arg = object(value, "instruction argument")?;
args.push(OwnedArg {
name: required_string(arg, &["name"])?,
canonical_type: required_string(arg, &["type", "canonicalType", "canonical_type"])?,
size: as_u16(number(arg, &["size"], 0)?, "argument size")?,
encoding: arg_encoding(&string(arg, &["encoding"], "fixed")?)?,
max_len: as_u16(number(arg, &["maxLen", "max_len"], 0)?, "maxLen")?,
element_size: as_u16(
number(arg, &["elementSize", "element_size"], 0)?,
"elementSize",
)?,
});
}
let mut accounts = Vec::new();
for value in array(instruction, &["accounts"])? {
let account = object(value, "instruction account")?;
accounts.push(OwnedAccount {
name: required_string(account, &["name"])?,
writable: boolean(account, &["writable"], false)?,
signer: boolean(account, &["signer"], false)?,
layout_ref: string(account, &["layoutRef", "layout_ref"], "")?,
seeds: strings(account, &["seeds"])?,
});
}
let mut discriminator =
byte_array(instruction, &["discriminatorBytes", "discriminator_bytes"])?;
if discriminator.is_empty() {
discriminator.push(tag);
}
if discriminator.len() > 8 || discriminator[0] != tag {
return Err(format!(
"instruction `{ix_name}` has invalid discriminatorBytes: expected 1..=8 bytes beginning with tag {tag}"
));
}
let remaining_accounts_max = value_for(
instruction,
&["remainingAccountsMax", "remaining_accounts_max"],
)
.map(|_| {
number(
instruction,
&["remainingAccountsMax", "remaining_accounts_max"],
0,
)
})
.transpose()?
.map(|value| as_u16(value, "remainingAccountsMax"))
.transpose()?;
instructions.push(OwnedInstruction {
name: ix_name,
tag,
discriminator,
args,
accounts,
remaining_accounts_max,
capabilities: strings(instruction, &["capabilities"])?,
policy_pack: string(instruction, &["policyPack", "policy_pack"], "")?,
receipt_expected: boolean(
instruction,
&["receiptExpected", "receipt_expected"],
false,
)?,
strict_writes: boolean(instruction, &["strictWrites", "strict_writes"], false)?,
write_ranges: write_ranges(instruction, &["writeRanges", "write_ranges"])?,
parametric_write_ranges: parametric_ranges(
instruction,
&["parametricWriteRanges", "parametric_write_ranges"],
)?,
mutation_complete: boolean(
instruction,
&["mutationComplete", "mutation_complete"],
false,
)?,
lamport_accounts: byte_array(instruction, &["lamportAccounts", "lamport_accounts"])?,
cu_estimate: as_u32(
number(instruction, &["cuEstimate", "cu_estimate"], 0)?,
"cuEstimate",
)?,
});
}
let mut events = Vec::new();
for value in array(root, &["events"])? {
let event = object(value, "event")?;
let mut fields = Vec::new();
for value in array(event, &["fields"])? {
let field = object(value, "event field")?;
fields.push(OwnedField {
name: required_string(field, &["name"])?,
canonical_type: required_string(field, &["type"])?,
size: as_u16(number(field, &["size"], 0)?, "event field size")?,
offset: as_u16(number(field, &["offset"], 0)?, "event field offset")?,
intent: field_intent(&string(field, &["intent"], "custom")?)?,
});
}
events.push(OwnedEvent {
name: required_string(event, &["name"])?,
tag: as_u8(number(event, &["tag"], 0)?, "event tag")?,
fields,
});
}
let mut policies = Vec::new();
for value in array(root, &["policies"])? {
let policy = object(value, "policy")?;
policies.push(OwnedPolicy {
name: required_string(policy, &["name"])?,
capabilities: strings(policy, &["capabilities"])?,
requirements: strings(policy, &["requirements"])?,
invariants: strings(policy, &["invariants"])?,
receipt_profile: string(policy, &["receiptProfile", "receipt_profile"], "")?,
});
}
let mut layout_metadata = Vec::new();
for value in array(root, &["layoutMetadata", "layout_metadata"])? {
let metadata = object(value, "layout metadata")?;
layout_metadata.push(OwnedLayoutMetadata {
name: required_string(metadata, &["name"])?,
segment_roles: strings(metadata, &["segmentRoles", "segment_roles"])?,
append_safe: boolean(metadata, &["appendSafe", "append_safe"], false)?,
migration_required: boolean(
metadata,
&["migrationRequired", "migration_required"],
false,
)?,
rebuildable: boolean(metadata, &["rebuildable"], false)?,
policy_pack: string(metadata, &["policyPack", "policy_pack"], "")?,
invariant_pack: strings(metadata, &["invariantPack", "invariant_pack"])?,
receipt_profile: string(metadata, &["receiptProfile", "receipt_profile"], "")?,
phase_requirements: strings(metadata, &["phaseRequirements", "phase_requirements"])?,
trust_profile: string(metadata, &["trustProfile", "trust_profile"], "")?,
manager_hints: strings(metadata, &["managerHints", "manager_hints"])?,
});
}
let mut compatibility_pairs = Vec::new();
for value in array(
root,
&["compatRules", "compatibilityPairs", "compatibility_pairs"],
)? {
let pair = object(value, "compatibility rule")?;
let policy_name = required_string(pair, &["policy"])?;
let policy = match policy_name.as_str() {
"noop" | "no-op" => MigrationPolicy::NoOp,
"append-only" | "append_only" => MigrationPolicy::AppendOnly,
"requires-migration" | "requires_migration" => MigrationPolicy::RequiresMigration,
"incompatible" => MigrationPolicy::Incompatible,
_ => return Err(format!("unknown migration policy `{policy_name}`")),
};
compatibility_pairs.push(OwnedCompatibilityPair {
from_layout: required_string(pair, &["from", "fromLayout", "from_layout"])?,
from_version: as_u8(
number(pair, &["fromVersion", "from_version"], 0)?,
"fromVersion",
)?,
to_layout: required_string(pair, &["to", "toLayout", "to_layout"])?,
to_version: as_u8(number(pair, &["toVersion", "to_version"], 0)?, "toVersion")?,
policy,
backward_readable: boolean(pair, &["backwardReadable", "backward_readable"], false)?,
});
}
let mut contexts = Vec::new();
for value in array(root, &["contexts"])? {
let context = object(value, "context")?;
let mut accounts = Vec::new();
for value in array(context, &["accounts"])? {
let account = object(value, "context account")?;
accounts.push(OwnedContextAccount {
name: required_string(account, &["name"])?,
kind: string(account, &["kind"], "AccountView")?,
writable: boolean(account, &["writable"], false)?,
signer: boolean(account, &["signer"], false)?,
layout_ref: string(account, &["layoutRef", "layout_ref"], "")?,
policy_ref: string(account, &["policyRef", "policy_ref"], "")?,
seeds: strings(account, &["seeds"])?,
optional: boolean(account, &["optional"], false)?,
lifecycle: account_lifecycle(&string(account, &["lifecycle"], "existing")?)?,
payer: string(account, &["payer"], "")?,
init_space: as_u32(
number(account, &["initSpace", "init_space"], 0)?,
"initSpace",
)?,
has_one: strings(account, &["hasOne", "has_one"])?,
expected_address: string(account, &["expectedAddress", "expected_address"], "")?,
expected_owner: string(account, &["expectedOwner", "expected_owner"], "")?,
});
}
contexts.push(OwnedContext {
name: required_string(context, &["name"])?,
instructions: strings(context, &["instructions"])?,
accounts,
policies: strings(context, &["policies"])?,
receipts_expected: boolean(context, &["receiptsExpected", "receipts_expected"], false)?,
mutation_classes: strings(context, &["mutationClasses", "mutation_classes"])?,
strict_writes: boolean(context, &["strictWrites", "strict_writes"], false)?,
write_ranges: write_ranges(context, &["writeRanges", "write_ranges"])?,
parametric_write_ranges: parametric_ranges(
context,
&["parametricWriteRanges", "parametric_write_ranges"],
)?,
mutation_complete: boolean(context, &["mutationComplete", "mutation_complete"], false)?,
lamport_accounts: byte_array(context, &["lamportAccounts", "lamport_accounts"])?,
});
}
Ok(OwnedProgramManifest {
name,
version,
description,
layouts,
instructions,
events,
policies,
layout_metadata,
compatibility_pairs,
tooling_hints: strings(root, &["toolingHints", "tooling_hints"])?,
contexts,
})
}
fn to_program_manifest(m: &OwnedProgramManifest) -> ProgramManifest {
let layouts: Vec<LayoutManifest> = m.layouts.iter().map(|l| to_manifest(l).0).collect();
let instructions: Vec<InstructionDescriptor> = m
.instructions
.iter()
.map(|ix| {
let context = matching_owned_context(ix, &m.contexts);
let args: Vec<ArgDescriptor> = ix
.args
.iter()
.map(|a| ArgDescriptor {
name: leak_str(&a.name),
canonical_type: leak_str(&a.canonical_type),
size: a.size,
encoding: match a.encoding {
OwnedArgEncoding::Fixed => hopper_schema::ArgEncoding::Fixed,
OwnedArgEncoding::BoundedVec => hopper_schema::ArgEncoding::BoundedVec {
max_len: a.max_len,
element_size: a.element_size,
},
OwnedArgEncoding::BoundedString => {
hopper_schema::ArgEncoding::BoundedString { max_len: a.max_len }
}
},
})
.collect();
let accounts: Vec<AccountEntry> = ix
.accounts
.iter()
.enumerate()
.map(|(account_index, account)| {
let context_account =
context.and_then(|context| context.accounts.get(account_index));
let layout_ref = if account.layout_ref.is_empty() {
context_account.map_or("", |context| context.layout_ref.as_str())
} else {
account.layout_ref.as_str()
};
let source_seeds = if account.seeds.is_empty() {
context_account.map(|context| context.seeds.as_slice())
} else {
Some(account.seeds.as_slice())
};
let seeds: Vec<&'static str> = source_seeds
.unwrap_or_default()
.iter()
.map(|seed| leak_str(seed))
.collect();
AccountEntry {
name: leak_str(&account.name),
writable: account.writable,
signer: account.signer,
layout_ref: leak_str(layout_ref),
seeds: Box::leak(seeds.into_boxed_slice()),
}
})
.collect();
let capabilities: Vec<&'static str> =
ix.capabilities.iter().map(|c| leak_str(c)).collect();
let write_ranges: Vec<WriteRange> = ix
.write_ranges
.iter()
.map(|r| WriteRange::new(r.account_index, r.offset, r.size))
.collect();
let lamport_accounts: Vec<u8> = ix.lamport_accounts.clone();
let parametric_write_ranges: Vec<hopper_schema::ParametricWriteRange> = ix
.parametric_write_ranges
.iter()
.map(|range| {
hopper_schema::ParametricWriteRange::new(
range.account_index,
range.base_offset,
range.stride,
range.cell_size,
range.count,
range.argument_index,
leak_str(&range.argument),
leak_str(&range.segment),
)
})
.collect();
InstructionDescriptor {
name: leak_str(&ix.name),
tag: ix.tag,
discriminator: Box::leak(ix.discriminator.clone().into_boxed_slice()),
args: Box::leak(args.into_boxed_slice()),
accounts: Box::leak(accounts.into_boxed_slice()),
remaining_accounts: ix
.remaining_accounts_max
.map(|max| hopper_schema::RemainingAccountsDescriptor { max }),
capabilities: Box::leak(capabilities.into_boxed_slice()),
policy_pack: leak_str(&ix.policy_pack),
receipt_expected: ix.receipt_expected,
strict_writes: ix.strict_writes,
write_ranges: Box::leak(write_ranges.into_boxed_slice()),
parametric_write_ranges: Box::leak(parametric_write_ranges.into_boxed_slice()),
mutation_complete: ix.mutation_complete,
lamport_accounts: Box::leak(lamport_accounts.into_boxed_slice()),
cu_estimate: ix.cu_estimate,
}
})
.collect();
let events: Vec<EventDescriptor> = m
.events
.iter()
.map(|e| {
let fields: Vec<FieldDescriptor> = e
.fields
.iter()
.map(|f| FieldDescriptor {
name: leak_str(&f.name),
canonical_type: leak_str(&f.canonical_type),
size: f.size,
offset: f.offset,
intent: f.intent,
})
.collect();
EventDescriptor {
name: leak_str(&e.name),
tag: e.tag,
fields: Box::leak(fields.into_boxed_slice()),
}
})
.collect();
let policies: Vec<PolicyDescriptor> = m
.policies
.iter()
.map(|p| {
let caps: Vec<&'static str> = p.capabilities.iter().map(|c| leak_str(c)).collect();
let reqs: Vec<&'static str> = p.requirements.iter().map(|r| leak_str(r)).collect();
let invs: Vec<&'static str> = p.invariants.iter().map(|i| leak_str(i)).collect();
PolicyDescriptor {
name: leak_str(&p.name),
capabilities: Box::leak(caps.into_boxed_slice()),
requirements: Box::leak(reqs.into_boxed_slice()),
invariants: Box::leak(invs.into_boxed_slice()),
receipt_profile: leak_str(&p.receipt_profile),
}
})
.collect();
let contexts: Vec<ContextDescriptor> = m
.contexts
.iter()
.map(|ctx| {
let accounts: Vec<ContextAccountDescriptor> = ctx
.accounts
.iter()
.map(|account| {
let seeds: Vec<&'static str> =
account.seeds.iter().map(|seed| leak_str(seed)).collect();
let has_one: Vec<&'static str> =
account.has_one.iter().map(|h| leak_str(h)).collect();
ContextAccountDescriptor {
name: leak_str(&account.name),
kind: leak_str(&account.kind),
writable: account.writable,
signer: account.signer,
layout_ref: leak_str(&account.layout_ref),
policy_ref: leak_str(&account.policy_ref),
seeds: Box::leak(seeds.into_boxed_slice()),
optional: account.optional,
lifecycle: account.lifecycle,
payer: leak_str(&account.payer),
init_space: account.init_space,
has_one: Box::leak(has_one.into_boxed_slice()),
expected_address: leak_str(&account.expected_address),
expected_owner: leak_str(&account.expected_owner),
}
})
.collect();
let policies: Vec<&'static str> =
ctx.policies.iter().map(|policy| leak_str(policy)).collect();
let mutation_classes: Vec<&'static str> = ctx
.mutation_classes
.iter()
.map(|class_name| leak_str(class_name))
.collect();
let ctx_write_ranges: Vec<WriteRange> = ctx
.write_ranges
.iter()
.map(|r| WriteRange::new(r.account_index, r.offset, r.size))
.collect();
let ctx_parametric_write_ranges: Vec<hopper_schema::ParametricWriteRange> = ctx
.parametric_write_ranges
.iter()
.map(|range| {
hopper_schema::ParametricWriteRange::new(
range.account_index,
range.base_offset,
range.stride,
range.cell_size,
range.count,
range.argument_index,
leak_str(&range.argument),
leak_str(&range.segment),
)
})
.collect();
let lamport_accounts = ctx.lamport_accounts.clone();
let instructions: Vec<&'static str> =
ctx.instructions.iter().map(|name| leak_str(name)).collect();
ContextDescriptor {
name: leak_str(&ctx.name),
instructions: Box::leak(instructions.into_boxed_slice()),
accounts: Box::leak(accounts.into_boxed_slice()),
policies: Box::leak(policies.into_boxed_slice()),
receipts_expected: ctx.receipts_expected,
mutation_classes: Box::leak(mutation_classes.into_boxed_slice()),
strict_writes: ctx.strict_writes,
write_ranges: Box::leak(ctx_write_ranges.into_boxed_slice()),
parametric_write_ranges: Box::leak(ctx_parametric_write_ranges.into_boxed_slice()),
mutation_complete: ctx.mutation_complete,
lamport_accounts: Box::leak(lamport_accounts.into_boxed_slice()),
}
})
.collect();
let layout_metadata: Vec<LayoutMetadata> = m
.layout_metadata
.iter()
.map(|metadata| {
let segment_roles: Vec<&'static str> = metadata
.segment_roles
.iter()
.map(|value| leak_str(value))
.collect();
let invariant_pack: Vec<&'static str> = metadata
.invariant_pack
.iter()
.map(|value| leak_str(value))
.collect();
let phase_requirements: Vec<&'static str> = metadata
.phase_requirements
.iter()
.map(|value| leak_str(value))
.collect();
let manager_hints: Vec<&'static str> = metadata
.manager_hints
.iter()
.map(|value| leak_str(value))
.collect();
LayoutMetadata {
name: leak_str(&metadata.name),
segment_roles: Box::leak(segment_roles.into_boxed_slice()),
append_safe: metadata.append_safe,
migration_required: metadata.migration_required,
rebuildable: metadata.rebuildable,
policy_pack: leak_str(&metadata.policy_pack),
invariant_pack: Box::leak(invariant_pack.into_boxed_slice()),
receipt_profile: leak_str(&metadata.receipt_profile),
phase_requirements: Box::leak(phase_requirements.into_boxed_slice()),
trust_profile: leak_str(&metadata.trust_profile),
manager_hints: Box::leak(manager_hints.into_boxed_slice()),
}
})
.collect();
let compatibility_pairs: Vec<CompatibilityPair> = m
.compatibility_pairs
.iter()
.map(|pair| CompatibilityPair {
from_layout: leak_str(&pair.from_layout),
from_version: pair.from_version,
to_layout: leak_str(&pair.to_layout),
to_version: pair.to_version,
policy: pair.policy,
backward_readable: pair.backward_readable,
})
.collect();
let tooling_hints: Vec<&'static str> =
m.tooling_hints.iter().map(|hint| leak_str(hint)).collect();
ProgramManifest {
name: leak_str(&m.name),
version: leak_str(&m.version),
description: leak_str(&m.description),
layouts: Box::leak(layouts.into_boxed_slice()),
instructions: Box::leak(instructions.into_boxed_slice()),
events: Box::leak(events.into_boxed_slice()),
policies: Box::leak(policies.into_boxed_slice()),
layout_metadata: Box::leak(layout_metadata.into_boxed_slice()),
compatibility_pairs: Box::leak(compatibility_pairs.into_boxed_slice()),
tooling_hints: Box::leak(tooling_hints.into_boxed_slice()),
contexts: Box::leak(contexts.into_boxed_slice()),
}
}
fn matching_owned_context<'a>(
instruction: &OwnedInstruction,
contexts: &'a [OwnedContext],
) -> Option<&'a OwnedContext> {
let instruction_name = canonical_manifest_name(&instruction.name);
if let Some(named) = contexts
.iter()
.filter(|context| owned_context_matches_instruction(instruction, context))
.find(|context| canonical_manifest_name(&context.name) == instruction_name)
{
return Some(named);
}
let mut candidates = contexts
.iter()
.filter(|context| owned_context_matches_instruction(instruction, context));
let only = candidates.next()?;
candidates.next().is_none().then_some(only)
}
fn owned_context_matches_instruction(
instruction: &OwnedInstruction,
context: &OwnedContext,
) -> bool {
context.accounts.len() == instruction.accounts.len()
&& instruction.accounts.iter().zip(&context.accounts).all(
|(instruction_account, context_account)| {
instruction_account.name == context_account.name
&& instruction_account.writable == context_account.writable
&& instruction_account.signer == context_account.signer
&& (instruction_account.layout_ref.is_empty()
|| context_account.layout_ref.is_empty()
|| instruction_account.layout_ref == context_account.layout_ref)
},
)
}
fn canonical_manifest_name(value: &str) -> String {
value
.bytes()
.filter(u8::is_ascii_alphanumeric)
.map(|byte| byte.to_ascii_lowercase() as char)
.collect()
}
fn cmd_tx_family(args: &[String]) {
if args.is_empty() || matches!(args[0].as_str(), "--help" | "-h" | "help") {
eprintln!("Usage: hopper tx <subcommand>");
eprintln!();
eprintln!("Subcommands:");
eprintln!(" explain <signature> Decode a confirmed transaction against");
eprintln!(" every touched Hopper program's manifest");
eprintln!(" send --program <id> ... Send one instruction with explicit metas");
eprintln!(" and hex data, signed locally (no Node)");
eprintln!(" simulate <tx-base64> Simulate a pre-built transaction");
eprintln!(" submit <tx-base64> Submit a pre-built transaction");
return;
}
match args[0].as_str() {
"explain" => cmd::tx_explain::cmd_tx_explain(&args[1..]),
"send" => cmd::tx_send::cmd_tx_send(&args[1..]),
"simulate" => cmd::meta::cmd_tx_simulate(&args[1..]),
"submit" => cmd::meta::cmd_tx_submit(&args[1..]),
other => {
eprintln!("Unknown tx subcommand: {other}");
process::exit(1);
}
}
}
fn cmd_manager(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper manager <subcommand> [args]");
eprintln!();
eprintln!("Subcommands:");
eprintln!(" summary <manifest|--program-id ...> Program overview");
eprintln!(" identify <manifest|--program-id ...> <hex> Identify account type");
eprintln!(" decode <manifest|--program-id ...> <hex> Decode all fields with values");
eprintln!(" instruction <manifest|--program-id ...> <tag|name> Instruction details and policies");
eprintln!(" layouts <manifest|--program-id ...> List all layouts with fields");
eprintln!(" policies <manifest|--program-id ...> List policy packs with mappings");
eprintln!(" events <manifest|--program-id ...> List events with fields");
eprintln!(" fingerprints <manifest|--program-id ...> Show all layout fingerprints");
eprintln!(" compat <manifest|--program-id ...> <hex-old> <hex-new> Compare two account versions");
eprintln!(" receipt <hex-64-or-72-bytes> Decode a receipt from wire bytes");
eprintln!(" explain <manifest|--program-id ...> Aggregated human-readable summary");
eprintln!(" diff <manifest|--program-id ...> <hex-before> <hex-after> Semantic field-level diff");
eprintln!(" simulate <manifest|--program-id ...> <instruction> Preview instruction requirements");
eprintln!(" fetch <program-id> [--rpc <url>] Fetch manifest from on-chain");
eprintln!(" interactive <manifest|--program-id ...> Interactive terminal explorer");
process::exit(1);
}
match args[0].as_str() {
"summary" => cmd_manager_summary(&args[1..]),
"identify" => cmd_manager_identify(&args[1..]),
"decode" => cmd_manager_decode(&args[1..]),
"instruction" => cmd_manager_instruction(&args[1..]),
"layouts" => cmd_manager_layouts(&args[1..]),
"policies" => cmd_manager_policies(&args[1..]),
"events" => cmd_manager_events(&args[1..]),
"fingerprints" => cmd_manager_fingerprints(&args[1..]),
"compat" => cmd_manager_compat(&args[1..]),
"receipt" => cmd_manager_receipt(&args[1..]),
"explain" => cmd_manager_explain(&args[1..]),
"diff" => cmd_manager_diff(&args[1..]),
"fetch" => cmd_manager_fetch(&args[1..]),
"simulate" => cmd_manager_simulate(&args[1..]),
"invoke" => cmd::manager_invoke::cmd_manager_invoke(&args[1..]),
"crank" => cmd::manager_invoke::cmd_manager_crank(&args[1..]),
"accounts" => {
if matches!(args.get(1).map(String::as_str), Some("read")) {
cmd::meta::cmd_manager_accounts_read(&args[2..]);
} else {
cmd::manager_accounts::cmd_manager_accounts(&args[1..]);
}
}
"interactive" | "ui" => cmd_interactive(&args[1..]),
other => {
eprintln!("Unknown manager subcommand: {}", other);
process::exit(1);
}
}
}
fn parse_fetch_args(args: &[String]) -> (String, Option<String>, bool) {
let mut program_id = None;
let mut rpc_override = None;
let mut json_mode = false;
let mut i = 0;
while i < args.len() {
match args[i].as_str() {
"--rpc" => {
if i + 1 >= args.len() {
eprintln!("--rpc requires a URL argument");
process::exit(1);
}
rpc_override = Some(args[i + 1].clone());
i += 2;
}
"--json" => {
json_mode = true;
i += 1;
}
other => {
if program_id.is_none() {
program_id = Some(other.to_string());
} else {
eprintln!("Unexpected argument: {}", other);
process::exit(1);
}
i += 1;
}
}
}
let pid = match program_id {
Some(p) => p,
None => {
eprintln!("Missing required <program-id> argument");
process::exit(1);
}
};
(pid, rpc_override, json_mode)
}
fn fetch_manifest_json(program_id_str: &str, rpc_override: Option<&str>) -> String {
let rpc_url = rpc::resolve_rpc_url(rpc_override);
let program_id = match rpc::decode_pubkey(program_id_str) {
Ok(pk) => pk,
Err(e) => {
eprintln!("Invalid program ID: {}", e);
process::exit(1);
}
};
let (pda, bump) = match rpc::find_program_address(&[hopper_schema::MANIFEST_SEED], &program_id)
{
Some(result) => result,
None => {
eprintln!("Failed to derive manifest PDA (no valid bump found)");
process::exit(1);
}
};
let pda_b58 = rpc::encode_pubkey(&pda);
eprintln!("Legacy manifest PDA: {} (bump {})", pda_b58, bump);
eprintln!("RPC endpoint: {}", rpc_url);
eprintln!();
let account = match rpc::get_account_info(&rpc_url, &pda_b58) {
Ok(Some(info)) => info,
Ok(None) => {
eprintln!(
"No application-provisioned legacy manifest found at PDA {}",
pda_b58
);
eprintln!();
eprintln!(
"The program {} does not have a legacy Hopper manifest at MANIFEST_SEED.",
program_id_str
);
eprintln!("Hopper has no generic publisher for this legacy manifest PDA.");
eprintln!("Use an application-specific publisher, or pass a local manifest file.");
process::exit(1);
}
Err(e) => {
eprintln!("RPC error: {}", e);
process::exit(1);
}
};
let manifest = match rpc::decode_manifest_account(&account.data) {
Ok(m) => m,
Err(e) => {
eprintln!("Failed to decode manifest account: {}", e);
eprintln!("Account owner: {}", account.owner);
eprintln!("Account size: {} bytes", account.data.len());
process::exit(1);
}
};
eprintln!("Manifest version: {}", manifest.version);
eprintln!("JSON size: {} bytes", manifest.json.len());
eprintln!();
manifest.json
}
fn cmd_fetch(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper fetch <program-id> [--rpc <url>] [--json]");
eprintln!();
eprintln!("Fetch an application-provisioned legacy Hopper manifest PDA and display it.");
eprintln!(
"This does not discover Solana Program Metadata; Hopper ships no generic publisher."
);
eprintln!();
eprintln!("Options:");
eprintln!(" --rpc <url> Solana RPC endpoint (default: SOLANA_RPC_URL env or mainnet)");
eprintln!(" --json Output raw manifest JSON instead of summary");
process::exit(1);
}
let (program_id, rpc_override, json_mode) = parse_fetch_args(args);
let json = fetch_manifest_json(&program_id, rpc_override.as_deref());
if json_mode {
println!("{}", json);
} else {
let prog = load_program_manifest_from_json(&json);
println!("{}", prog);
}
}
fn cmd_manager_fetch(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper manager fetch <program-id> [--rpc <url>]");
eprintln!();
eprintln!("Fetch a program's Hopper manifest from on-chain and show manager summary.");
process::exit(1);
}
let (program_id, rpc_override, _) = parse_fetch_args(args);
let json = fetch_manifest_json(&program_id, rpc_override.as_deref());
let prog = load_program_manifest_from_json(&json);
println!("{}", prog);
}
fn cmd_interactive(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper interactive <manifest>");
eprintln!(" hopper interactive --program-id <program-id> [--rpc <url>]");
eprintln!(" hopper manager interactive <manifest>");
eprintln!(" hopper manager interactive --program-id <program-id> [--rpc <url>]");
eprintln!(" hopper ui <manifest>");
eprintln!();
eprintln!("Launch an interactive terminal UI for exploring a program manifest.");
eprintln!("Manifest can be inline JSON, @path/to/file.json, or fetched from a program ID.");
process::exit(1);
}
let (prog, _) = load_program_manifest_source(
args,
"hopper interactive <manifest> | --program-id <program-id> [--rpc <url>]",
);
let mut session = interactive::Session::new(&prog);
if let Err(e) = session.run() {
eprintln!("Interactive session error: {}", e);
process::exit(1);
}
}
fn load_program_manifest(arg: &str) -> ProgramManifest {
let resolved = if std::path::Path::new(arg).is_file() {
std::fs::read_to_string(arg).unwrap_or_else(|error| {
eprintln!("Could not read manifest file '{arg}': {error}");
process::exit(1);
})
} else {
resolve_manifest_arg(arg)
};
load_program_manifest_from_json(&resolved)
}
fn load_program_manifest_from_json(json: &str) -> ProgramManifest {
match parse_program_manifest_json(json) {
Ok(m) => to_program_manifest(&m),
Err(e) => {
eprintln!("Program manifest parse error: {}", e);
process::exit(1);
}
}
}
fn load_program_manifest_source(args: &[String], usage: &str) -> (ProgramManifest, usize) {
if args.is_empty() {
eprintln!("Usage: {usage}");
process::exit(1);
}
if args[0] != "--program-id" {
return (load_program_manifest(&args[0]), 1);
}
if args.len() < 2 {
eprintln!("Usage: {usage}");
eprintln!();
eprintln!("--program-id requires a base58 program address.");
process::exit(1);
}
let mut rpc_override = None;
let mut consumed = 2;
while consumed < args.len() {
match args[consumed].as_str() {
"--rpc" => {
if consumed + 1 >= args.len() {
eprintln!("Usage: {usage}");
eprintln!();
eprintln!("--rpc requires a URL argument.");
process::exit(1);
}
rpc_override = Some(args[consumed + 1].clone());
consumed += 2;
}
_ => break,
}
}
let json = fetch_manifest_json(&args[1], rpc_override.as_deref());
(load_program_manifest_from_json(&json), consumed)
}
fn cmd_manager_summary(args: &[String]) {
let (prog, _) = load_program_manifest_source(
args,
"hopper manager summary <manifest> | --program-id <program-id> [--rpc <url>]",
);
println!("{}", prog);
}
fn cmd_manager_identify(args: &[String]) {
let usage = "hopper manager identify <manifest> <hex-data> | --program-id <program-id> [--rpc <url>] <hex-data>";
let (prog, consumed) = load_program_manifest_source(args, usage);
if args.len() <= consumed {
eprintln!("Usage: {usage}");
process::exit(1);
}
let data = match hex_decode(&args[consumed]) {
Ok(d) => d,
Err(e) => {
eprintln!("Hex decode error: {}", e);
process::exit(1);
}
};
if data.len() < 16 {
eprintln!(
"Data too short for Hopper header (need 16 bytes, got {})",
data.len()
);
process::exit(1);
}
let header = require_header(&data);
println!("=== Account Identification ===");
println!(" Data size : {} bytes", data.len());
println!(" Header disc : {}", header.disc);
println!(" Header ver : {}", header.version);
println!(" Layout ID : {}", hex_encode(&header.layout_id));
println!();
match prog.identify_from_data(&data) {
Some(layout) => {
println!(" MATCH: {} v{}", layout.name, layout.version);
println!(" Expected size: {} bytes", layout.total_size);
println!(" Fields : {}", layout.field_count);
if data.len() != layout.total_size {
println!(
" WARNING: data size ({}) != expected size ({})",
data.len(),
layout.total_size
);
}
println!();
println!("Use 'hopper manager decode' to see field values.");
}
None => {
println!(" NO MATCH: This account does not match any layout in the manifest.");
println!();
println!("Known layouts:");
for l in prog.layouts.iter() {
println!(
" {} v{} (disc={}, id={})",
l.name,
l.version,
l.disc,
hex_encode(&l.layout_id)
);
}
}
}
}
fn cmd_manager_decode(args: &[String]) {
decode_layout_from_source(
args,
"hopper manager decode <manifest> <hex-data> | --program-id <program-id> [--rpc <url>] <hex-data>",
"Account Decode",
);
}
fn decode_layout_from_source(args: &[String], usage: &str, heading: &str) {
let (prog, consumed) = load_program_manifest_source(args, usage);
if args.len() <= consumed {
eprintln!("Usage: {usage}");
process::exit(1);
}
let data = match hex_decode(&args[consumed]) {
Ok(d) => d,
Err(e) => {
eprintln!("Hex decode error: {}", e);
process::exit(1);
}
};
if data.len() < 16 {
eprintln!("Data too short for Hopper header");
process::exit(1);
}
let header = require_header(&data);
let layout = match prog.identify_from_data(&data) {
Some(layout) => layout,
None => {
eprintln!(
"Cannot identify account type (disc={}, layout_id={})",
header.disc,
hex_encode(&header.layout_id)
);
eprintln!("Use 'hopper manager identify' for diagnostics.");
process::exit(1);
}
};
println!("=== {}: {} v{} ===", heading, layout.name, layout.version);
println!(
" Size: {} bytes (expected {})",
data.len(),
layout.total_size
);
println!(
" Flags: {} (0x{:04x})",
format_flags(header.flags),
header.flags
);
println!(" Disc : {}", header.disc);
println!(" Wire : {}", hex_encode(&layout.layout_id));
println!();
if layout.field_count == 0 {
println!(" (no field descriptors in manifest)");
return;
}
let (count, fields) = decode_account_fields::<64>(&data, layout);
let mut buf = [0u8; 128];
println!(
" {:>4} {:>20} {:>12} {:>6} {:>6} Value",
"#", "Field", "Type", "Offset", "Size"
);
println!(" {}", "-".repeat(76));
for (i, slot) in fields.iter().enumerate().take(count) {
if let Some(ref field) = slot {
let val_len = field.format_value(&mut buf);
let val_str = std::str::from_utf8(&buf[..val_len]).unwrap_or("???");
println!(
" {:>4} {:>20} {:>12} {:>6} {:>6} {}",
i, field.name, field.canonical_type, field.offset, field.size, val_str,
);
}
}
println!();
println!(" Decoded {}/{} fields.", count, layout.field_count);
}
fn cmd_manager_instruction(args: &[String]) {
let usage = "hopper manager instruction <manifest> <tag|name> | --program-id <program-id> [--rpc <url>] <tag|name>";
let (prog, consumed) = load_program_manifest_source(args, usage);
if args.len() <= consumed {
eprintln!("Usage: {usage}");
process::exit(1);
}
let tag: u8 = match args[consumed].parse() {
Ok(t) => t,
Err(_) => {
let name = &args[consumed];
let mut found = None;
for ix in prog.instructions.iter() {
if ix.name == name.as_str() {
found = Some(ix.tag);
break;
}
}
match found {
Some(t) => t,
None => {
eprintln!("Unknown instruction: '{}'. Known:", name);
for ix in prog.instructions.iter() {
eprintln!(" {} {}", ix.tag, ix.name);
}
process::exit(1);
}
}
}
};
let ix = match prog.find_instruction(tag) {
Some(ix) => ix,
None => {
eprintln!("No instruction with tag {}", tag);
process::exit(1);
}
};
println!("=== Instruction: {} (tag {}) ===", ix.name, ix.tag);
println!();
if !ix.accounts.is_empty() {
println!(" Accounts ({}):", ix.accounts.len());
for (i, acct) in ix.accounts.iter().enumerate() {
let mut flags = Vec::new();
if acct.writable {
flags.push("writable");
}
if acct.signer {
flags.push("signer");
}
let flag_str = if flags.is_empty() {
"read-only".to_string()
} else {
flags.join(", ")
};
let layout_str = if acct.layout_ref.is_empty() {
""
} else {
acct.layout_ref
};
if layout_str.is_empty() {
println!(" [{}] {:20} ({})", i, acct.name, flag_str);
} else {
println!(
" [{}] {:20} ({}) -> {}",
i, acct.name, flag_str, layout_str
);
}
}
println!();
}
if !ix.args.is_empty() {
println!(" Arguments ({}):", ix.args.len());
for arg in ix.args.iter() {
println!(
" {:20} : {} ({} bytes)",
arg.name, arg.canonical_type, arg.size
);
}
println!();
}
if !ix.capabilities.is_empty() {
println!(" Capabilities:");
for cap in ix.capabilities.iter() {
println!(" - {}", cap);
}
println!();
}
if !ix.policy_pack.is_empty() {
println!(" Policy pack: {}", ix.policy_pack);
if let Some(policy) = prog.find_policy(ix.policy_pack) {
println!(" Requirements:");
for req in policy.requirements.iter() {
println!(" - {}", req);
}
}
println!();
}
println!(
" Receipt expected: {}",
if ix.receipt_expected { "YES" } else { "NO" }
);
}
fn cmd_manager_layouts(args: &[String]) {
let (prog, _) = load_program_manifest_source(
args,
"hopper manager layouts <manifest> | --program-id <program-id> [--rpc <url>]",
);
print!("{}", hopper_manager::summary::layouts_report(&prog));
}
fn cmd_manager_policies(args: &[String]) {
let (prog, _) = load_program_manifest_source(
args,
"hopper manager policies <manifest> | --program-id <program-id> [--rpc <url>]",
);
if prog.policies.is_empty() {
println!("No policies defined in manifest.");
return;
}
println!("=== Policy Packs ({}) ===", prog.policies.len());
println!();
for policy in prog.policies.iter() {
println!(" {}", policy.name);
if !policy.capabilities.is_empty() {
println!(" Capabilities:");
for cap in policy.capabilities.iter() {
println!(" - {}", cap);
}
}
if !policy.requirements.is_empty() {
println!(" Requirements:");
for req in policy.requirements.iter() {
println!(" - {}", req);
}
}
println!();
}
println!(" Instruction -> Policy mapping:");
for ix in prog.instructions.iter() {
if !ix.policy_pack.is_empty() {
println!(" {:20} -> {}", ix.name, ix.policy_pack);
}
}
}
fn cmd_manager_events(args: &[String]) {
let (prog, _) = load_program_manifest_source(
args,
"hopper manager events <manifest> | --program-id <program-id> [--rpc <url>]",
);
if prog.events.is_empty() {
println!("No events defined in manifest.");
return;
}
println!("=== Events ({}) ===", prog.events.len());
println!();
for event in prog.events.iter() {
println!(" {} (tag {})", event.name, event.tag);
if event.fields.is_empty() {
println!(" (no fields)");
} else {
println!(" Fields ({}):", event.fields.len());
for f in event.fields.iter() {
println!(
" [{:>3}..{:>3}] {:20} : {} ({} bytes)",
f.offset,
f.offset + f.size,
f.name,
f.canonical_type,
f.size,
);
}
}
println!();
}
let has_receipt_ix: Vec<_> = prog
.instructions
.iter()
.filter(|ix| ix.receipt_expected)
.collect();
if !has_receipt_ix.is_empty() {
println!(" Instructions with receipt emissions:");
for ix in &has_receipt_ix {
println!(" {:20} (tag {})", ix.name, ix.tag);
}
}
}
fn cmd_manager_fingerprints(args: &[String]) {
let (prog, _) = load_program_manifest_source(
args,
"hopper manager fingerprints <manifest> | --program-id <program-id> [--rpc <url>]",
);
println!("=== Layout Fingerprints ===");
println!();
println!(
" {:>20} {:>3} {:>3} {:>6} Layout ID",
"Name", "D", "V", "Size"
);
println!(" {}", "-".repeat(60));
for layout in prog.layouts.iter() {
println!(
" {:>20} {:>3} {:>3} {:>6} {}",
layout.name,
layout.disc,
layout.version,
layout.total_size,
hex_encode(&layout.layout_id),
);
}
println!();
let mut seen_discs = std::collections::HashMap::new();
for layout in prog.layouts.iter() {
if let Some(prev) = seen_discs.insert(layout.disc, layout.name) {
println!(
" WARNING: Disc {} shared by '{}' and '{}'",
layout.disc, prev, layout.name
);
}
}
let mut seen_ids = std::collections::HashMap::new();
for layout in prog.layouts.iter() {
let id_hex = hex_encode(&layout.layout_id);
if let Some(prev) = seen_ids.insert(id_hex.clone(), layout.name) {
println!(
" WARNING: Layout ID {} shared by '{}' and '{}'",
id_hex, prev, layout.name
);
}
}
if seen_discs.len() == prog.layouts.len() && seen_ids.len() == prog.layouts.len() {
println!(" All discriminators and layout IDs are unique.");
}
}
fn cmd_manager_compat(args: &[String]) {
let usage = "hopper manager compat <manifest> <hex-old> <hex-new> | --program-id <program-id> [--rpc <url>] <hex-old> <hex-new>";
let (prog, consumed) = load_program_manifest_source(args, usage);
if args.len() < consumed + 2 {
eprintln!("Usage: {usage}");
eprintln!(" Compares two account data blobs and reports compatibility.");
process::exit(1);
}
let old_data = match hex_decode(&args[consumed]) {
Ok(d) => d,
Err(e) => {
eprintln!("Hex decode error (old): {}", e);
process::exit(1);
}
};
let new_data = match hex_decode(&args[consumed + 1]) {
Ok(d) => d,
Err(e) => {
eprintln!("Hex decode error (new): {}", e);
process::exit(1);
}
};
if old_data.len() < 16 || new_data.len() < 16 {
eprintln!("Both data blobs must be at least 16 bytes (header).");
process::exit(1);
}
let old_header = require_header(&old_data);
let new_header = require_header(&new_data);
println!("=== Compatibility Analysis ===");
println!();
println!(
" Old: disc={}, ver={}, layout_id={}, size={}",
old_header.disc,
old_header.version,
hex_encode(&old_header.layout_id),
old_data.len()
);
println!(
" New: disc={}, ver={}, layout_id={}, size={}",
new_header.disc,
new_header.version,
hex_encode(&new_header.layout_id),
new_data.len()
);
println!();
if old_header.disc != new_header.disc {
println!(" RESULT: Different discriminators. These are different account types.");
return;
}
if old_header.layout_id == new_header.layout_id {
println!(" RESULT: Same layout ID. Same schema version, no compat issue.");
return;
}
let old_layout = prog.identify_from_data(&old_data);
let new_layout = prog.identify_from_data(&new_data);
match (old_layout, new_layout) {
(Some(ol), Some(nl)) => {
println!(" Old layout: {} v{}", ol.name, ol.version);
println!(" New layout: {} v{}", nl.name, nl.version);
let report = compare_fields::<64>(ol, nl);
println!();
println!(" Field-level changes:");
for i in 0..report.len() {
if let Some(entry) = report.get(i) {
let status = match entry.status {
FieldCompat::Identical => "identical",
FieldCompat::Changed => "CHANGED",
FieldCompat::Added => "added",
FieldCompat::Removed => "REMOVED",
};
println!(" {:20} : {}", entry.name, status);
}
}
let verdict = CompatibilityVerdict::between(ol, nl);
println!();
println!(" Verdict: {}", verdict.name());
match verdict {
CompatibilityVerdict::Identical => {
println!(" RESULT: Identical layout. No changes.");
}
CompatibilityVerdict::WireCompatible => {
println!(" RESULT: Wire-compatible. Byte layout identical, semantic metadata differs.");
}
CompatibilityVerdict::AppendSafe => {
println!(
" RESULT: Append-safe. Old field prefix preserved, no migration needed."
);
}
CompatibilityVerdict::MigrationRequired => {
println!(
" RESULT: Migration required. Data is not directly backward-readable."
);
}
CompatibilityVerdict::Incompatible => {
println!(" RESULT: Incompatible. Breaking change detected.");
}
}
}
(Some(ol), None) => {
println!(" Old layout identified: {} v{}", ol.name, ol.version);
println!(" New layout: NOT IN MANIFEST");
println!(" RESULT: Cannot determine compatibility (new layout unknown).");
}
(None, Some(nl)) => {
println!(" Old layout: NOT IN MANIFEST");
println!(" New layout identified: {} v{}", nl.name, nl.version);
println!(" RESULT: Cannot determine compatibility (old layout unknown).");
}
(None, None) => {
println!(" Neither layout found in manifest.");
println!(" RESULT: Cannot determine compatibility.");
}
}
}
fn cmd_manager_receipt(args: &[String]) {
if args.is_empty() {
eprintln!("Usage: hopper manager receipt <hex-64-or-72-bytes>");
process::exit(1);
}
let data = match hex_decode(&args[0]) {
Ok(d) => d,
Err(e) => {
eprintln!("Hex decode error: {}", e);
process::exit(1);
}
};
if !valid_receipt_len(data.len()) {
eprintln!(
"Receipt data must be exactly {} legacy bytes or at least {} current bytes (got {})",
RECEIPT_WIRE_SIZE_LEGACY,
RECEIPT_WIRE_SIZE,
data.len()
);
process::exit(1);
}
let r = match DecodedReceipt::from_bytes(&data) {
Some(r) => r,
None => {
eprintln!("Failed to decode receipt");
process::exit(1);
}
};
let phase = Phase::from_tag(r.phase);
let impact = CompatImpact::from_tag(r.compat_impact);
println!("=== State Receipt ===");
println!(
" Wire format : {}",
if data.len() == RECEIPT_WIRE_SIZE_LEGACY {
"legacy 64-byte"
} else {
"current 72-byte"
}
);
println!();
println!(" Layout ID : {}", hex_encode(&r.layout_id));
println!(" Phase : {} ({})", phase.name(), r.phase);
println!(" Committed : {}", r.committed);
println!();
println!(" Changed fields mask : 0x{:016x}", r.changed_fields);
println!(" Changed bytes : {}", r.changed_bytes);
println!(" Changed regions : {}", r.changed_regions);
println!(
" Was resized : {} ({} -> {} bytes)",
r.was_resized, r.old_size, r.new_size
);
println!();
println!(
" Before fingerprint : {}",
hex_encode(&r.before_fingerprint)
);
println!(
" After fingerprint : {}",
hex_encode(&r.after_fingerprint)
);
let fp_changed = r.before_fingerprint != r.after_fingerprint;
println!(" Fingerprint changed : {}", fp_changed);
println!();
println!(" Invariants passed : {}", r.invariants_passed);
println!(" Invariants checked : {}", r.invariants_checked);
println!(
" CPI invoked : {} ({} calls)",
r.cpi_invoked, r.cpi_count
);
println!(" Journal appends : {}", r.journal_appends);
println!(" Segment mask : 0x{:04x}", r.segment_changed_mask);
println!(" Policy flags : 0x{:08x}", r.policy_flags);
println!();
println!(
" Compat impact : {} ({})",
impact.name(),
r.compat_impact
);
println!(" Validation bundle : {}", r.validation_bundle_id);
println!(" Migration flags : 0b{:08b}", r.migration_flags);
if r.migration_flags & 0x01 != 0 {
println!(" - Migration triggered");
}
if r.migration_flags & 0x02 != 0 {
println!(" - Realloc performed");
}
if r.migration_flags & 0x04 != 0 {
println!(" - Schema version bumped");
}
println!();
println!(" Failure recorded : {}", r.had_failure);
println!(
" Failure stage : {}",
receipt_failure_stage_name(r.failure_stage)
);
println!(" Failed invariant : 0x{:02x}", r.failed_invariant_idx);
println!(" Failed error code : {}", r.failed_error_code);
}
fn cmd_manager_explain(args: &[String]) {
if args.is_empty() {
eprintln!(
"Usage: hopper manager explain <manifest> | --program-id <program-id> [--rpc <url>]"
);
eprintln!(" Aggregated human-readable summary of the program manifest.");
process::exit(1);
}
let (prog, _) = load_program_manifest_source(
args,
"hopper manager explain <manifest> | --program-id <program-id> [--rpc <url>]",
);
println!("=== Program Explanation ===");
println!();
println!(" Name : {}", prog.name);
println!(" Version : {}", prog.version);
println!(" Description : {}", prog.description);
println!();
println!(" Layouts ({})", prog.layouts.len());
for l in prog.layouts.iter() {
let fp = LayoutFingerprint::from_manifest(l);
println!(
" {} v{} | disc={} | {} fields | {} bytes | wire={} sem={}",
l.name,
l.version,
l.disc,
l.field_count,
l.total_size,
hex_encode(&fp.wire_hash),
hex_encode(&fp.semantic_hash)
);
}
println!();
println!(" Instructions ({})", prog.instructions.len());
for ix in prog.instructions.iter() {
println!(
" [{}] {} | {} args | {} accounts",
ix.tag,
ix.name,
ix.args.len(),
ix.accounts.len()
);
}
println!();
println!(" Policies ({})", prog.policies.len());
for p in prog.policies.iter() {
println!(
" {} | {}cap {}req {}inv | receipt={}",
p.name,
p.capabilities.len(),
p.requirements.len(),
p.invariants.len(),
p.receipt_profile
);
}
println!();
println!(" Events ({})", prog.events.len());
for ev in prog.events.iter() {
println!(" [{}] {} | {} fields", ev.tag, ev.name, ev.fields.len());
}
println!();
if !prog.compatibility_pairs.is_empty() {
println!(" Compatibility Rules ({})", prog.compatibility_pairs.len());
for cp in prog.compatibility_pairs.iter() {
let policy = match cp.policy {
MigrationPolicy::NoOp => "noop",
MigrationPolicy::AppendOnly => "append-only",
MigrationPolicy::RequiresMigration => "migration",
MigrationPolicy::Incompatible => "incompatible",
};
println!(
" {} v{} → {} v{} | {} | backward={}",
cp.from_layout,
cp.from_version,
cp.to_layout,
cp.to_version,
policy,
cp.backward_readable
);
}
println!();
}
if !prog.tooling_hints.is_empty() {
println!(" Tooling Hints");
for h in prog.tooling_hints.iter() {
println!(" - {}", h);
}
}
}
fn cmd_manager_diff(args: &[String]) {
let usage = "hopper manager diff <manifest> <hex-before> <hex-after> | --program-id <program-id> [--rpc <url>] <hex-before> <hex-after>";
let (prog, consumed) = load_program_manifest_source(args, usage);
if args.len() < consumed + 2 {
eprintln!("Usage: {usage}");
eprintln!(" Semantic field-level diff between two account states.");
process::exit(1);
}
let before = match hex_decode(&args[consumed]) {
Ok(d) => d,
Err(e) => {
eprintln!("Hex decode error (before): {}", e);
process::exit(1);
}
};
let after = match hex_decode(&args[consumed + 1]) {
Ok(d) => d,
Err(e) => {
eprintln!("Hex decode error (after): {}", e);
process::exit(1);
}
};
if before.len() < 16 || after.len() < 16 {
eprintln!("Both data blobs must be at least 16 bytes (header).");
process::exit(1);
}
let before_header = require_header(&before);
let after_header = require_header(&after);
println!("=== Semantic Diff ===");
println!();
let before_layout = prog.identify_from_data(&before);
let after_layout = prog.identify_from_data(&after);
match (before_layout, after_layout) {
(Some(bl), Some(al)) => {
println!(" Before : {} v{} (disc={})", bl.name, bl.version, bl.disc);
println!(" After : {} v{} (disc={})", al.name, al.version, al.disc);
println!();
let verdict = CompatibilityVerdict::between(bl, al);
println!(" Verdict: {}", verdict.name());
println!();
let (_bc, before_fields) = decode_account_fields::<64>(&before, bl);
let (_ac, after_fields) = decode_account_fields::<64>(&after, al);
println!(" Field-level changes:");
let max_fields = std::cmp::max(bl.field_count, al.field_count);
let mut diffs_found = 0usize;
for i in 0..max_fields {
if i < bl.field_count && i < al.field_count {
let bf = &bl.fields[i];
let af = &al.fields[i];
let bv = before_fields[i].as_ref().map(|f| f.raw).unwrap_or(&[]);
let av = after_fields[i].as_ref().map(|f| f.raw).unwrap_or(&[]);
if bv != av || bf.name != af.name || bf.canonical_type != af.canonical_type {
println!(
" {:20} : {} → {}",
bf.name,
hex_encode(bv),
hex_encode(av)
);
diffs_found += 1;
}
} else if i < al.field_count {
let af = &al.fields[i];
let av = after_fields[i].as_ref().map(|f| f.raw).unwrap_or(&[]);
println!(" {:20} : (added) = {}", af.name, hex_encode(av));
diffs_found += 1;
} else if i < bl.field_count {
let bf = &bl.fields[i];
println!(" {:20} : (removed)", bf.name);
diffs_found += 1;
}
}
if diffs_found == 0 {
println!(" (no field-level differences)");
}
if before.len() != after.len() {
println!();
println!(
" Size: {} → {} bytes ({}{})",
before.len(),
after.len(),
if after.len() > before.len() { "+" } else { "" },
after.len() as isize - before.len() as isize
);
}
}
(Some(bl), None) => {
println!(" Before : {} v{}", bl.name, bl.version);
println!(
" After : UNKNOWN LAYOUT (id={})",
hex_encode(&after_header.layout_id)
);
println!(" Cannot compute semantic diff: after layout not in manifest.");
}
(None, Some(al)) => {
println!(
" Before : UNKNOWN LAYOUT (id={})",
hex_encode(&before_header.layout_id)
);
println!(" After : {} v{}", al.name, al.version);
println!(" Cannot compute semantic diff: before layout not in manifest.");
}
(None, None) => {
println!(
" Before : UNKNOWN LAYOUT (id={})",
hex_encode(&before_header.layout_id)
);
println!(
" After : UNKNOWN LAYOUT (id={})",
hex_encode(&after_header.layout_id)
);
println!(" Cannot compute semantic diff: neither layout is in the manifest.");
}
}
}
fn cmd_manager_simulate(args: &[String]) {
let usage = "hopper manager simulate <manifest> <instruction-name|tag> | --program-id <program-id> [--rpc <url>] <instruction-name|tag>";
let (prog, consumed) = load_program_manifest_source(args, usage);
if args.len() <= consumed {
eprintln!("Usage: {usage}");
eprintln!(" Preview what an instruction requires: accounts, args, policies, receipt.");
process::exit(1);
}
let query = &args[consumed];
let ix = prog
.instructions
.iter()
.find(|ix| ix.name == query.as_str() || format!("{}", ix.tag) == query.as_str());
let ix = match ix {
Some(ix) => ix,
None => {
eprintln!("Instruction '{}' not found.", query);
eprintln!();
eprintln!("Available instructions:");
for ix in prog.instructions.iter() {
eprintln!(" [{}] {}", ix.tag, ix.name);
}
process::exit(1);
}
};
println!("=== Simulate: {} (tag {}) ===", ix.name, ix.tag);
println!();
println!(" Accounts required ({}):", ix.accounts.len());
for (i, acc) in ix.accounts.iter().enumerate() {
let mut flags = Vec::new();
if acc.signer {
flags.push("SIGNER");
}
if acc.writable {
flags.push("WRITABLE");
}
let flag_str = if flags.is_empty() {
"read-only".to_string()
} else {
flags.join(" + ")
};
let layout_note = if acc.layout_ref.is_empty() {
String::new()
} else {
format!(" → layout:{}", acc.layout_ref)
};
println!(" #{}: {} [{}]{}", i, acc.name, flag_str, layout_note);
}
println!();
if ix.args.is_empty() {
println!(" Arguments: none (tag byte only)");
} else {
let total_size: u16 = ix.args.iter().map(|a| a.size).sum();
println!(
" Arguments ({}, {} bytes after tag):",
ix.args.len(),
total_size
);
let mut offset = 1usize; for arg in ix.args.iter() {
println!(
" @{}: {} ({}, {} bytes)",
offset, arg.name, arg.canonical_type, arg.size
);
offset += arg.size as usize;
}
println!(" Total instruction data: {} bytes", offset);
}
println!();
if !ix.policy_pack.is_empty() {
println!(" Policy: {}", ix.policy_pack);
if let Some(pol) = prog.policies.iter().find(|p| p.name == ix.policy_pack) {
if !pol.capabilities.is_empty() {
println!(" Capabilities:");
for cap in pol.capabilities.iter() {
println!(" - {}", cap);
}
}
if !pol.requirements.is_empty() {
println!(" Requirements:");
for req in pol.requirements.iter() {
println!(" - {}", req);
}
}
if !pol.invariants.is_empty() {
println!(" Invariants checked:");
for inv in pol.invariants.iter() {
println!(" - {}", inv);
}
}
}
} else {
println!(" Policy: (none / custom)");
}
println!();
if ix.receipt_expected {
println!(" Receipt: YES. This instruction emits a state receipt.");
println!(" The receipt captures:");
println!(" - Phase (Init/Update/Close/Migrate)");
println!(" - Changed field bitmask");
println!(" - Segment change mask");
println!(" - Fingerprint before/after");
println!(" - Compatibility impact");
println!(" - CPI invocation flag");
} else {
println!(" Receipt: NO. This instruction does not emit a receipt.");
}
if !ix.capabilities.is_empty() {
println!();
println!(" Capabilities:");
for cap in ix.capabilities.iter() {
println!(" - {}", cap);
}
}
}
fn parse_or_exit(json: &str) -> OwnedManifest {
let resolved = resolve_manifest_arg(json);
match parse_manifest_json(&resolved) {
Ok(p) => p.into(),
Err(e) => {
eprintln!("JSON parse error: {}", e);
process::exit(1);
}
}
}
fn to_manifest(m: &OwnedManifest) -> (LayoutManifest, Vec<FieldDescriptor>) {
let fields: Vec<FieldDescriptor> = m
.fields
.iter()
.map(|f| FieldDescriptor {
name: leak_str(&f.name),
canonical_type: leak_str(&f.canonical_type),
size: f.size,
offset: f.offset,
intent: f.intent,
})
.collect();
let manifest = LayoutManifest {
name: leak_str(&m.name),
disc: m.disc,
version: m.version,
layout_id: m.layout_id,
total_size: m.total_size,
has_dynamic_tail: m.has_dynamic_tail,
field_count: m.field_count,
fields: leak_slice(&fields),
};
(manifest, fields)
}
fn leak_str(s: &str) -> &'static str {
Box::leak(s.to_string().into_boxed_str())
}
fn leak_slice(v: &[FieldDescriptor]) -> &'static [FieldDescriptor] {
Box::leak(v.to_vec().into_boxed_slice())
}
#[cfg(test)]
mod loader_write_set_tests {
use super::*;
const MANIFEST_WITH_WRITE_SET: &str = r#"{
"name": "TestProgram",
"version": "1.2.3",
"instructions": [
{
"name": "deposit",
"tag": 3,
"args": [],
"accounts": [
{ "name": "vault", "writable": true, "signer": false, "layout_ref": "Vault" },
{ "name": "authority", "writable": false, "signer": true, "layout_ref": "" }
],
"capabilities": ["MutatesState"],
"policy_pack": "VAULT_WRITE",
"receipt_expected": true,
"cuEstimate": 4200,
"strictWrites": true,
"mutationComplete": true,
"lamportAccounts": [0, 1],
"writeRanges": [
{ "account": "vault", "accountIndex": 0, "offset": 16, "size": 8 },
{ "account": "vault", "accountIndex": 0, "offset": 40, "size": 32 }
]
}
],
"contexts": [
{
"name": "Deposit",
"accounts": [
{ "name": "vault", "kind": "HopperAccount", "writable": true, "signer": false, "layout_ref": "Vault", "policy_ref": "VAULT_WRITE", "seeds": [], "optional": false }
],
"policies": ["VAULT_WRITE"],
"receipts_expected": true,
"mutation_classes": ["StateTransition"],
"strictWrites": true,
"writeRanges": [
{ "account": "vault", "accountIndex": 0, "offset": 16, "size": 8 }
]
}
]
}"#;
const MANIFEST_WITHOUT_WRITE_SET: &str = r#"{
"name": "TestProgram",
"version": "1.2.3",
"instructions": [
{
"name": "deposit",
"tag": 3,
"args": [],
"accounts": [
{ "name": "vault", "writable": true, "signer": false, "layout_ref": "Vault" }
],
"capabilities": ["MutatesState"],
"policy_pack": "VAULT_WRITE",
"receipt_expected": true
}
],
"contexts": [
{
"name": "Deposit",
"accounts": [
{ "name": "vault", "kind": "HopperAccount", "writable": true, "signer": false, "layout_ref": "Vault", "policy_ref": "", "seeds": [], "optional": false }
],
"policies": [],
"receipts_expected": false,
"mutation_classes": []
}
]
}"#;
#[test]
fn emitted_manifest_round_trips_rich_context_and_upgrade_contract() {
use hopper_schema::accounts::AccountLifecycle;
use hopper_schema::codama::ManifestJson;
static INSTRUCTION_ACCOUNTS: &[AccountEntry] = &[
AccountEntry {
name: "payer",
writable: true,
signer: true,
layout_ref: "",
seeds: &[],
},
AccountEntry {
name: "state",
writable: true,
signer: false,
layout_ref: "StateV2",
seeds: &[],
},
];
static INSTRUCTIONS: &[InstructionDescriptor] = &[InstructionDescriptor {
name: "initialize",
tag: 1,
discriminator: &[1],
args: &[],
accounts: INSTRUCTION_ACCOUNTS,
remaining_accounts: None,
capabilities: &["MutatesState"],
policy_pack: "StatePolicy",
receipt_expected: true,
strict_writes: false,
write_ranges: &[],
parametric_write_ranges: &[],
mutation_complete: false,
lamport_accounts: &[],
cu_estimate: 3_000,
}];
static EVENT_FIELDS: &[FieldDescriptor] = &[
FieldDescriptor {
name: "authority",
canonical_type: "Pubkey",
size: 32,
offset: 0,
intent: FieldIntent::Authority,
},
FieldDescriptor {
name: "opaque",
canonical_type: "u8",
size: 1,
offset: 32,
intent: FieldIntent::Custom,
},
];
static EVENTS: &[EventDescriptor] = &[EventDescriptor {
name: "Initialized",
tag: 9,
fields: EVENT_FIELDS,
}];
static CONTEXT_ACCOUNTS: &[ContextAccountDescriptor] = &[
ContextAccountDescriptor {
name: "payer",
kind: "Signer",
writable: true,
signer: true,
layout_ref: "",
policy_ref: "",
seeds: &[],
optional: false,
lifecycle: AccountLifecycle::Existing,
payer: "",
init_space: 0,
has_one: &[],
expected_address: "",
expected_owner: "",
},
ContextAccountDescriptor {
name: "state",
kind: "InitAccount",
writable: true,
signer: false,
layout_ref: "StateV2",
policy_ref: "StatePolicy",
seeds: &["b\"state\"", "payer.address()"],
optional: true,
lifecycle: AccountLifecycle::Init,
payer: "payer",
init_space: 64,
has_one: &["payer"],
expected_address: "state-address",
expected_owner: "state-owner",
},
];
static CONTEXT_RANGES: &[WriteRange] = &[WriteRange::new(1, 16, 8)];
static CONTEXT_PARAMETRIC: &[hopper_schema::ParametricWriteRange] =
&[hopper_schema::ParametricWriteRange::new(
1, 24, 8, 8, 4, 0, "slot", "cells",
)];
static CONTEXTS: &[ContextDescriptor] = &[ContextDescriptor {
name: "Initialize",
instructions: &[],
accounts: CONTEXT_ACCOUNTS,
policies: &["StatePolicy"],
receipts_expected: true,
mutation_classes: &["Initialization"],
strict_writes: true,
write_ranges: CONTEXT_RANGES,
parametric_write_ranges: CONTEXT_PARAMETRIC,
mutation_complete: true,
lamport_accounts: &[0, 1],
}];
static METADATA: &[LayoutMetadata] = &[LayoutMetadata {
name: "StateV2",
segment_roles: &["core", "cells"],
append_safe: true,
migration_required: false,
rebuildable: true,
policy_pack: "StatePolicy",
invariant_pack: &["StateValid"],
receipt_profile: "StateReceipt",
phase_requirements: &["Update"],
trust_profile: "verified",
manager_hints: &["show-cells"],
}];
static COMPATIBILITY: &[CompatibilityPair] = &[CompatibilityPair {
from_layout: "StateV1",
from_version: 1,
to_layout: "StateV2",
to_version: 2,
policy: MigrationPolicy::AppendOnly,
backward_readable: true,
}];
static POLICIES: &[PolicyDescriptor] = &[PolicyDescriptor {
name: "StatePolicy",
capabilities: &["MutatesState"],
requirements: &["SignerAuthority"],
invariants: &["StateValid"],
receipt_profile: "StateReceipt",
}];
static LAYOUTS: &[LayoutManifest] = &[LayoutManifest {
name: "StateV2",
disc: 7,
version: 2,
layout_id: [7; 8],
total_size: 1,
has_dynamic_tail: true,
field_count: 0,
fields: &[],
}];
let source = ProgramManifest {
name: "roundtrip",
version: "1.0.0",
description: "rich manifest",
layouts: LAYOUTS,
layout_metadata: METADATA,
instructions: INSTRUCTIONS,
events: EVENTS,
policies: POLICIES,
compatibility_pairs: COMPATIBILITY,
tooling_hints: &["lossless"],
contexts: CONTEXTS,
};
let json = format!("{}", ManifestJson(&source));
let owned = parse_program_manifest_json(&json).expect("emitted manifest parses");
let loaded = to_program_manifest(&owned);
assert!(json.contains("\"hasDynamicTail\": true"));
assert!(loaded.layouts[0].has_dynamic_tail);
assert_eq!(loaded.instructions[0].policy_pack, "StatePolicy");
assert!(loaded.instructions[0].receipt_expected);
assert_eq!(
loaded.instructions[0].accounts[1].seeds,
&["b\"state\"", "payer.address()"]
);
assert_eq!(loaded.layout_metadata.len(), 1);
assert_eq!(loaded.layout_metadata[0].segment_roles, &["core", "cells"]);
assert_eq!(loaded.layout_metadata[0].invariant_pack, &["StateValid"]);
assert_eq!(loaded.compatibility_pairs.len(), 1);
assert_eq!(
loaded.compatibility_pairs[0].policy,
MigrationPolicy::AppendOnly
);
assert!(loaded.compatibility_pairs[0].backward_readable);
assert_eq!(loaded.contexts.len(), 1);
assert_eq!(
loaded.contexts[0].accounts[1].lifecycle,
AccountLifecycle::Init
);
assert_eq!(loaded.contexts[0].accounts[1].has_one, &["payer"]);
assert_eq!(loaded.contexts[0].parametric_write_ranges.len(), 1);
assert!(loaded.contexts[0].mutation_complete);
assert_eq!(loaded.contexts[0].lamport_accounts, &[0, 1]);
assert_eq!(loaded.tooling_hints, &["lossless"]);
assert_eq!(loaded.events[0].fields[0].intent, FieldIntent::Authority);
assert_eq!(loaded.events[0].fields[1].intent, FieldIntent::Custom);
}
#[test]
fn legacy_layout_without_dynamic_tail_flag_defaults_to_fixed() {
let json = r#"{
"name": "legacy",
"version": "0.1.0",
"layouts": [{
"name": "FixedCompact",
"disc": 3,
"version": 1,
"layoutId": "0102030405060708",
"totalSize": 1,
"fieldCount": 0,
"fields": []
}]
}"#;
let owned = parse_program_manifest_json(json).expect("legacy layout should parse");
let loaded = to_program_manifest(&owned);
assert!(!loaded.layouts[0].has_dynamic_tail);
}
#[test]
fn single_layout_parser_carries_dynamic_tail_aliases() {
let parsed = parse_manifest_json(
r#"{
"name": "DynamicCompact",
"disc": 3,
"version": 1,
"layoutId": "0102030405060708",
"totalSize": 1,
"hasDynamicTail": true,
"fields": []
}"#,
)
.expect("dynamic compact layout should parse");
assert!(parsed.has_dynamic_tail);
let legacy = parse_manifest_json(
r#"{
"name": "FixedCompact",
"disc": 4,
"version": 1,
"layout_id": [1, 2, 3, 4, 5, 6, 7, 8],
"total_size": 1,
"fields": []
}"#,
)
.expect("legacy fixed compact layout should parse");
assert!(!legacy.has_dynamic_tail);
}
#[test]
fn loader_carries_instruction_write_set_verbatim() {
let owned = parse_program_manifest_json(MANIFEST_WITH_WRITE_SET)
.expect("manifest with write set should parse");
let prog = to_program_manifest(&owned);
let ix = &prog.instructions[0];
assert_eq!(ix.name, "deposit");
assert!(ix.strict_writes, "strict_writes should round-trip as true");
assert!(
ix.mutation_complete,
"mutation_complete should round-trip as true"
);
assert_eq!(ix.cu_estimate, 4200, "cu_estimate should round-trip");
assert_eq!(
ix.lamport_accounts,
&[0u8, 1u8],
"lamport_accounts should round-trip"
);
assert_eq!(ix.write_ranges.len(), 2, "both write ranges carried");
assert_eq!(ix.write_ranges[0].account_index, 0);
assert_eq!(ix.write_ranges[0].offset, 16);
assert_eq!(ix.write_ranges[0].size, 8);
assert_eq!(ix.write_ranges[1].account_index, 0);
assert_eq!(ix.write_ranges[1].offset, 40);
assert_eq!(ix.write_ranges[1].size, 32);
}
#[test]
fn parser_key_matcher_skips_string_values_that_equal_a_key() {
let range = r#"{ "account": "offset", "accountIndex": 3, "offset": 16, "size": 8 }"#;
assert_eq!(extract_number(range, "offset").unwrap(), 16);
assert_eq!(extract_number(range, "accountIndex").unwrap(), 3);
assert_eq!(extract_number(range, "size").unwrap(), 8);
assert_eq!(extract_string(range, "account").unwrap(), "offset");
let ix = r#"{ "policy_pack": "strictWrites", "strictWrites": true }"#;
assert!(find_after_key(ix, "strictWrites")
.expect("strictWrites key")
.starts_with("true"));
assert_eq!(extract_string(ix, "policy_pack").unwrap(), "strictWrites");
}
#[test]
fn loader_carries_context_write_set_verbatim() {
let owned = parse_program_manifest_json(MANIFEST_WITH_WRITE_SET)
.expect("manifest with write set should parse");
let prog = to_program_manifest(&owned);
let ctx = &prog.contexts[0];
assert_eq!(ctx.name, "Deposit");
assert!(ctx.strict_writes, "context strict_writes should round-trip");
assert_eq!(ctx.write_ranges.len(), 1);
assert_eq!(ctx.write_ranges[0].account_index, 0);
assert_eq!(ctx.write_ranges[0].offset, 16);
assert_eq!(ctx.write_ranges[0].size, 8);
}
#[test]
fn release_manifest_rejects_unknown_argument_encoding() {
let json = r#"{
"name": "fail-closed",
"instructions": [{
"name": "write",
"args": [{ "name": "value", "type": "u8", "encoding": "futureEncoding" }]
}]
}"#;
let error = parse_program_manifest_json(json)
.err()
.expect("unknown argument encoding must fail");
assert_eq!(error, "unknown argument encoding `futureEncoding`");
}
#[test]
fn release_manifest_rejects_unknown_account_lifecycle() {
let json = r#"{
"name": "fail-closed",
"contexts": [{
"name": "Write",
"accounts": [{ "name": "state", "lifecycle": "teleport" }]
}]
}"#;
let error = parse_program_manifest_json(json)
.err()
.expect("unknown account lifecycle must fail");
assert_eq!(error, "unknown account lifecycle `teleport`");
}
#[test]
fn release_manifest_rejects_unknown_layout_and_event_field_intents() {
let manifests = [
r#"{
"name": "fail-closed-layout",
"layouts": [{
"name": "State",
"layoutId": "0000000000000000",
"fields": [{ "name": "value", "type": "u8", "intent": "mystery" }]
}]
}"#,
r#"{
"name": "fail-closed-event",
"events": [{
"name": "Changed",
"fields": [{ "name": "value", "type": "u8", "intent": "mystery" }]
}]
}"#,
];
for json in manifests {
let error = parse_program_manifest_json(json)
.err()
.expect("unknown field intent must fail");
assert_eq!(error, "unknown field intent `mystery`");
}
}
#[test]
fn release_manifest_typed_values_and_event_intents_round_trip() {
let json = r#"{
"name": "typed-round-trip",
"layouts": [{
"name": "State",
"layoutId": "0000000000000000",
"fields": [{ "name": "opaque", "type": "u8", "intent": "custom" }]
}],
"instructions": [{
"name": "write",
"args": [
{ "name": "fixed", "type": "u8", "size": 1, "encoding": "fixed" },
{ "name": "items", "type": "Vec<u16>", "encoding": "boundedVec", "maxLen": 7, "elementSize": 2 },
{ "name": "label", "type": "String", "encoding": "boundedString", "maxLen": 19 }
]
}],
"events": [{
"name": "Changed",
"fields": [
{ "name": "authority", "type": "Pubkey", "intent": "authority" },
{ "name": "opaque", "type": "u8", "intent": "custom" },
{ "name": "defaulted", "type": "u8" }
]
}],
"contexts": [{
"name": "Write",
"accounts": [
{ "name": "current", "lifecycle": "existing" },
{ "name": "created", "lifecycle": "init" },
{ "name": "maybe_created", "lifecycle": "init_if_needed" },
{ "name": "grown", "lifecycle": "realloc" },
{ "name": "recipient", "lifecycle": "close" }
]
}]
}"#;
let owned = parse_program_manifest_json(json).expect("known typed values should parse");
let manifest = to_program_manifest(&owned);
assert_eq!(manifest.layouts[0].fields[0].intent, FieldIntent::Custom);
assert_eq!(
manifest.instructions[0].args[0].encoding,
hopper_schema::ArgEncoding::Fixed
);
assert_eq!(
manifest.instructions[0].args[1].encoding,
hopper_schema::ArgEncoding::BoundedVec {
max_len: 7,
element_size: 2,
}
);
assert_eq!(
manifest.instructions[0].args[2].encoding,
hopper_schema::ArgEncoding::BoundedString { max_len: 19 }
);
assert_eq!(manifest.events[0].fields[0].intent, FieldIntent::Authority);
assert_eq!(manifest.events[0].fields[1].intent, FieldIntent::Custom);
assert_eq!(manifest.events[0].fields[2].intent, FieldIntent::Custom);
assert_eq!(
manifest.contexts[0]
.accounts
.iter()
.map(|account| account.lifecycle)
.collect::<Vec<_>>(),
vec![
AccountLifecycle::Existing,
AccountLifecycle::Init,
AccountLifecycle::InitIfNeeded,
AccountLifecycle::Realloc,
AccountLifecycle::Close,
]
);
}
#[test]
fn old_manifest_loads_with_documented_defaults() {
let owned = parse_program_manifest_json(MANIFEST_WITHOUT_WRITE_SET)
.expect("legacy manifest should still parse");
let prog = to_program_manifest(&owned);
let ix = &prog.instructions[0];
assert!(!ix.strict_writes);
assert!(ix.write_ranges.is_empty());
assert!(!ix.mutation_complete);
assert!(ix.lamport_accounts.is_empty());
assert_eq!(ix.cu_estimate, 0);
let ctx = &prog.contexts[0];
assert!(!ctx.strict_writes);
assert!(ctx.write_ranges.is_empty());
}
#[test]
fn golden_counter_manifest_loads_without_write_set() {
const COUNTER: &str = include_str!("../tests/fixtures/hopper-counter.manifest.json");
let owned =
parse_program_manifest_json(COUNTER).expect("golden counter manifest should parse");
let prog = to_program_manifest(&owned);
assert!(!prog.instructions.is_empty());
for ix in prog.instructions.iter() {
assert!(!ix.strict_writes);
assert!(ix.write_ranges.is_empty());
assert!(!ix.mutation_complete);
assert!(ix.lamport_accounts.is_empty());
assert_eq!(ix.cu_estimate, 0);
}
}
}