feat: add Quasar variants for repository-layout, rent, and cross-program-invocation

Author: mikemaccana-edwardbot

basics/cross-program-invocation/quasar/README.md

@@ -0,0 +1,36 @@
+# Cross-Program Invocation — Quasar
+
+This example contains **two separate Quasar programs** that work together:
+
+- **`lever/`** — A program with on-chain `PowerStatus` state and a `switch_power` instruction that toggles a boolean.
+- **`hand/`** — A program that calls the lever program's `switch_power` via CPI.
+
+## Building
+
+Each program is a separate Quasar workspace. Build them independently:
+
+```bash
+cd lever && quasar build
+cd hand && quasar build
+```
+
+The hand program must be built **after** the lever, since its tests load the lever's compiled `.so` file.
+
+## Testing
+
+```bash
+cd lever && cargo test
+cd hand && cargo test
+```
+
+The hand tests load **both** programs into `QuasarSvm` and verify that the CPI correctly toggles the lever's power state.
+
+## CPI Pattern
+
+Quasar doesn't have a `declare_program!` equivalent for importing arbitrary program instruction types (unlike Anchor). Instead, the hand program:
+
+1. Defines a **marker type** (`LeverProgram`) that implements the `Id` trait with the lever's program address
+2. Uses `Program<LeverProgram>` in the accounts struct for compile-time address + executable validation
+3. Builds the CPI instruction data **manually** using `BufCpiCall`, constructing the lever's wire format directly
+
+This is lower-level than Anchor's CPI pattern but gives full control and works with any program.

basics/cross-program-invocation/quasar/hand/.gitignore

@@ -0,0 +1,12 @@
+# Build artifacts
+/target
+
+# Dependencies
+node_modules
+
+# Environment
+.env
+.env.*
+
+# OS
+.DS_Store

basics/cross-program-invocation/quasar/hand/Cargo.toml

@@ -0,0 +1,32 @@
+[package]
+name = "quasar-hand"
+version = "0.1.0"
+edition = "2021"
+
+# Standalone workspace — not part of the root program-examples workspace.
+[workspace]
+
+[lints.rust.unexpected_cfgs]
+level = "warn"
+check-cfg = [
+    'cfg(target_os, values("solana"))',
+]
+
+[lib]
+crate-type = ["cdylib"]
+
+[features]
+alloc = []
+client = []
+debug = []
+
+[dependencies]
+quasar-lang = "0.0"
+solana-instruction = { version = "3.2.0" }
+
+[dev-dependencies]
+quasar-svm = { version = "0.1" }
+solana-account = { version = "3.4.0" }
+solana-address = { version = "2.2.0", features = ["decode"] }
+solana-instruction = { version = "3.2.0", features = ["bincode"] }
+solana-pubkey = { version = "4.1.0" }

basics/cross-program-invocation/quasar/hand/Quasar.toml

@@ -0,0 +1,21 @@
+[project]
+name = "quasar_hand"
+
+[toolchain]
+type = "solana"
+
+[testing]
+language = "rust"
+
+[testing.rust]
+framework = "quasar-svm"
+
+[testing.rust.test]
+program = "cargo"
+args = [
+    "test",
+    "tests::",
+]
+
+[clients]
+languages = ["rust"]

basics/cross-program-invocation/quasar/hand/src/instructions/mod.rs

@@ -0,0 +1,2 @@
+pub mod pull_lever;
+pub use pull_lever::*;

basics/cross-program-invocation/quasar/hand/src/instructions/pull_lever.rs

@@ -0,0 +1,60 @@
+use quasar_lang::{
+    cpi::{BufCpiCall, InstructionAccount},
+    prelude::*,
+};
+
+/// Accounts for the hand program's pull_lever instruction.
+/// The lever_program uses `Program<LeverProgram>` with a custom marker type
+/// that implements `Id` — this lets Quasar verify the program address and
+/// the executable flag during account parsing.
+#[derive(Accounts)]
+pub struct PullLever<'info> {
+    #[account(mut)]
+    pub power: &'info UncheckedAccount,
+    pub lever_program: &'info Program<crate::LeverProgram>,
+}
+
+impl<'info> PullLever<'info> {
+    #[inline(always)]
+    pub fn pull_lever(&self, name: &str) -> Result<(), ProgramError> {
+        log("Hand is pulling the lever!");
+
+        // Build the switch_power instruction data for the lever program:
+        //   [disc=1] [name: u32 len + bytes]
+        // 128 bytes is enough for any reasonable name.
+        let mut data = [0u8; 128];
+        let name_bytes = name.as_bytes();
+        let data_len = 1 + 4 + name_bytes.len();
+
+        // Discriminator = 1 (switch_power)
+        data[0] = 1;
+
+        // Name string: u32 little-endian length prefix + bytes
+        let len_bytes = (name_bytes.len() as u32).to_le_bytes();
+        data[1] = len_bytes[0];
+        data[2] = len_bytes[1];
+        data[3] = len_bytes[2];
+        data[4] = len_bytes[3];
+
+        // Copy name bytes
+        let mut i = 0;
+        while i < name_bytes.len() {
+            data[5 + i] = name_bytes[i];
+            i += 1;
+        }
+
+        let power_view = self.power.to_account_view();
+        let lever_view = self.lever_program.to_account_view();
+
+        // Build CPI call with 1 account (power, writable, not a signer).
+        let cpi = BufCpiCall::<1, 128>::new(
+            lever_view.address(),
+            [InstructionAccount::writable(power_view.address())],
+            [power_view],
+            data,
+            data_len,
+        );
+
+        cpi.invoke()
+    }
+}

basics/cross-program-invocation/quasar/hand/src/lib.rs

@@ -0,0 +1,32 @@
+#![cfg_attr(not(test), no_std)]
+
+use quasar_lang::prelude::*;
+
+mod instructions;
+use instructions::*;
+#[cfg(test)]
+mod tests;
+
+declare_id!("Bi5N7SUQhpGknVcqPTzdFFVueQoxoUu8YTLz75J6fT8A");
+
+/// The lever program's ID — used to verify the correct program is passed.
+pub const LEVER_PROGRAM_ID: Address = address!("E64FVeubGC4NPNF2UBJYX4AkrVowf74fRJD9q6YhwstN");
+
+/// Marker type for the lever program, implementing `Id` so it can be used
+/// with `Program<LeverProgram>` in the accounts struct.
+pub struct LeverProgram;
+
+impl Id for LeverProgram {
+    const ID: Address = LEVER_PROGRAM_ID;
+}
+
+#[program]
+mod quasar_hand {
+    use super::*;
+
+    /// Pull the lever by invoking the lever program's switch_power via CPI.
+    #[instruction(discriminator = 0)]
+    pub fn pull_lever(ctx: Ctx<PullLever>, name: String) -> Result<(), ProgramError> {
+        ctx.accounts.pull_lever(name)
+    }
+}

basics/cross-program-invocation/quasar/hand/src/tests.rs

@@ -0,0 +1,113 @@
+use quasar_svm::{Account, Instruction, Pubkey, QuasarSvm};
+use solana_address::Address;
+
+/// Lever program's program ID — must match the lever's declare_id!().
+fn lever_program_id() -> Pubkey {
+    Pubkey::from(crate::LEVER_PROGRAM_ID)
+}
+
+/// PowerStatus discriminator from the lever program.
+const POWER_STATUS_DISCRIMINATOR: u8 = 1;
+
+fn setup() -> QuasarSvm {
+    let hand_elf = include_bytes!("../target/deploy/quasar_hand.so");
+    let lever_elf = include_bytes!("../../lever/target/deploy/quasar_lever.so");
+    QuasarSvm::new()
+        .with_program(&Pubkey::from(crate::ID), hand_elf)
+        .with_program(&lever_program_id(), lever_elf)
+}
+
+fn power_account(address: Pubkey, is_on: bool) -> Account {
+    // Account data: [discriminator: u8] [is_on: u8]
+    let data = vec![POWER_STATUS_DISCRIMINATOR, if is_on { 1 } else { 0 }];
+    Account {
+        address,
+        lamports: 1_000_000_000,
+        data,
+        owner: lever_program_id(),
+        executable: false,
+    }
+}
+
+/// Build pull_lever instruction data (discriminator = 0).
+/// Wire format: [disc=0] [name: String]
+fn build_pull_lever(name: &str) -> Vec<u8> {
+    let mut data = vec![0u8]; // discriminator = 0
+    data.extend_from_slice(&(name.len() as u32).to_le_bytes());
+    data.extend_from_slice(name.as_bytes());
+    data
+}
+
+#[test]
+fn test_pull_lever_turns_on() {
+    let mut svm = setup();
+
+    let (power_addr, _bump) = Pubkey::find_program_address(&[b"power"], &lever_program_id());
+
+    let ix = Instruction {
+        program_id: Pubkey::from(crate::ID),
+        accounts: vec![
+            solana_instruction::AccountMeta::new(
+                Address::from(power_addr.to_bytes()),
+                false,
+            ),
+            solana_instruction::AccountMeta::new_readonly(
+                Address::from(lever_program_id().to_bytes()),
+                false,
+            ),
+        ],
+        data: build_pull_lever("Alice"),
+    };
+
+    // The lever program account is provided by the SVM (loaded via with_program).
+    // Only the power data account needs to be passed explicitly.
+    let result = svm.process_instruction(
+        &ix,
+        &[power_account(power_addr, false)],
+    );
+
+    result.assert_success();
+
+    let logs = result.logs.join("\n");
+    assert!(logs.contains("Hand is pulling"), "hand should log");
+    assert!(logs.contains("pulling the power switch"), "lever should log");
+    assert!(logs.contains("now on"), "power should turn on");
+
+    let account = result.account(&power_addr).unwrap();
+    assert_eq!(account.data[1], 1, "power should be on");
+}
+
+#[test]
+fn test_pull_lever_turns_off() {
+    let mut svm = setup();
+
+    let (power_addr, _bump) = Pubkey::find_program_address(&[b"power"], &lever_program_id());
+
+    let ix = Instruction {
+        program_id: Pubkey::from(crate::ID),
+        accounts: vec![
+            solana_instruction::AccountMeta::new(
+                Address::from(power_addr.to_bytes()),
+                false,
+            ),
+            solana_instruction::AccountMeta::new_readonly(
+                Address::from(lever_program_id().to_bytes()),
+                false,
+            ),
+        ],
+        data: build_pull_lever("Bob"),
+    };
+
+    let result = svm.process_instruction(
+        &ix,
+        &[power_account(power_addr, true)],
+    );
+
+    result.assert_success();
+
+    let logs = result.logs.join("\n");
+    assert!(logs.contains("now off"), "power should turn off");
+
+    let account = result.account(&power_addr).unwrap();
+    assert_eq!(account.data[1], 0, "power should be off");
+}

basics/cross-program-invocation/quasar/lever/.gitignore

@@ -0,0 +1,12 @@
+# Build artifacts
+/target
+
+# Dependencies
+node_modules
+
+# Environment
+.env
+.env.*
+
+# OS
+.DS_Store

basics/cross-program-invocation/quasar/lever/Cargo.toml

@@ -0,0 +1,32 @@
+[package]
+name = "quasar-lever"
+version = "0.1.0"
+edition = "2021"
+
+# Standalone workspace — not part of the root program-examples workspace.
+[workspace]
+
+[lints.rust.unexpected_cfgs]
+level = "warn"
+check-cfg = [
+    'cfg(target_os, values("solana"))',
+]
+
+[lib]
+crate-type = ["cdylib"]
+
+[features]
+alloc = []
+client = []
+debug = []
+
+[dependencies]
+quasar-lang = "0.0"
+solana-instruction = { version = "3.2.0" }
+
+[dev-dependencies]
+quasar-svm = { version = "0.1" }
+solana-account = { version = "3.4.0" }
+solana-address = { version = "2.2.0", features = ["decode"] }
+solana-instruction = { version = "3.2.0", features = ["bincode"] }
+solana-pubkey = { version = "4.1.0" }