Add system program client crate (#13)

* Add system helper crate

* Add missing feature

* Add more instructions

* Rename to programs

* Add remaining instructions

* Add readme

* Update banner image

* Tweak formatting

* Bump version

Author: febo

Cargo.lock

@@ -1,6 +1,7 @@
 [workspace]
 resolver = "2"
 members = [
+    "programs/system",
     "sdk/pinocchio",
     "sdk/pubkey",
 ]

Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "pinocchio-system"
+description = "Pinocchio helpers to invoke System program instructions"
+version = "0.1.0"
+edition = "2021"
+license = "Apache-2.0"
+readme = "./README.md"
+repository = "https://github.com/febo/pinocchio"
+
+[dependencies]
+pinocchio = { version="^0", path="../../sdk/pinocchio" }
+pinocchio-pubkey = { version="^0", path="../../sdk/pubkey" }

programs/system/Cargo.toml

@@ -0,0 +1,37 @@
+# <img width="250" alt="pinocchio-system" src="https://github.com/user-attachments/assets/6a775333-c3a1-4623-aa7a-afdc8c492594"/>
+
+This crate contains [`pinocchio`](https://crates.io/crates/pinocchio) helpers to perform cross-program invocations (CPIs) for System program instructions.
+
+Each instruction defines an `struct` with the accounts and parameters required. Once all values are set, you can call directly `invoke` or `invoke_signed` to perform the CPI.
+
+> **Note:** The API defined in this crate is subject to change.
+
+## Examples
+
+Creating a new account:
+```rust
+// This example assumes that the instruction receives a writable signer `payer_info`
+// and `new_account` accounts.
+CreateAccount {
+    from: payer_info,
+    to: new_account,
+    lamports: 1_000_000_000, // 1 SOL
+    space: 200,              // 200 bytes
+    owner: &spl_token::ID,
+}.invoke()?;
+```
+
+Performing a transfer of lamports:
+```rust
+// This example assumes that the instruction receives a writable signer `payer_info`
+// account and a writable `recipient` account.
+Transfer {
+    from: payer_info,
+    to: recipient,
+    lamports: 500_000_000, // 0.5 SOL
+}.invoke()?;
+```
+
+## License
+
+The code is licensed under the [Apache License Version 2.0](../LICENSE)

programs/system/README.md

@@ -0,0 +1,52 @@
+use pinocchio::{
+    account_info::AccountInfo,
+    entrypoint::ProgramResult,
+    instruction::{AccountMeta, Instruction, Signer},
+    program::invoke_signed,
+};
+
+/// Consumes a stored nonce, replacing it with a successor.
+///
+/// ### Accounts:
+///   0. `[WRITE]` Nonce account
+///   1. `[]` RecentBlockhashes sysvar
+///   2. `[SIGNER]` Nonce authority
+pub struct AdvanceNonceAccount<'a> {
+    /// Nonce account.
+    pub account: &'a AccountInfo,
+
+    /// RecentBlockhashes sysvar.
+    pub recent_blockhashes_sysvar: &'a AccountInfo,
+
+    /// Nonce authority.
+    pub authority: &'a AccountInfo,
+}
+
+impl<'a> AdvanceNonceAccount<'a> {
+    #[inline(always)]
+    pub fn invoke(&self) -> ProgramResult {
+        self.invoke_signed(&[])
+    }
+
+    pub fn invoke_signed(&self, signers: &[Signer]) -> ProgramResult {
+        // account metadata
+        let account_metas: [AccountMeta; 3] = [
+            AccountMeta::writable(self.account.key()),
+            AccountMeta::readonly(self.recent_blockhashes_sysvar.key()),
+            AccountMeta::readonly_signer(self.authority.key()),
+        ];
+
+        // instruction
+        let instruction = Instruction {
+            program_id: &crate::ID,
+            accounts: &account_metas,
+            data: &[4],
+        };
+
+        invoke_signed(
+            &instruction,
+            &[self.account, self.recent_blockhashes_sysvar, self.authority],
+            signers,
+        )
+    }
+}

programs/system/src/instructions/advance_nonce_account.rs

@@ -0,0 +1,45 @@
+use pinocchio::{
+    account_info::AccountInfo,
+    entrypoint::ProgramResult,
+    instruction::{AccountMeta, Instruction, Signer},
+    program::invoke_signed,
+};
+
+/// Allocate space in a (possibly new) account without funding.
+///
+/// ### Accounts:
+///   0. `[WRITE, SIGNER]` New account
+pub struct Allocate<'a> {
+    /// Account to be assigned.
+    pub account: &'a AccountInfo,
+
+    /// Number of bytes of memory to allocate.
+    pub space: u64,
+}
+
+impl<'a> Allocate<'a> {
+    #[inline(always)]
+    pub fn invoke(&self) -> ProgramResult {
+        self.invoke_signed(&[])
+    }
+
+    pub fn invoke_signed(&self, signers: &[Signer]) -> ProgramResult {
+        // account metadata
+        let account_metas: [AccountMeta; 1] = [AccountMeta::writable_signer(self.account.key())];
+
+        // instruction data
+        // -  [0..4 ]: instruction discriminator
+        // -  [4..12]: space
+        let mut instruction_data = [0; 12];
+        instruction_data[0] = 8;
+        instruction_data[4..12].copy_from_slice(&self.space.to_le_bytes());
+
+        let instruction = Instruction {
+            program_id: &crate::ID,
+            accounts: &account_metas,
+            data: &instruction_data,
+        };
+
+        invoke_signed(&instruction, &[self.account], signers)
+    }
+}

programs/system/src/instructions/allocate.rs

@@ -0,0 +1,74 @@
+use pinocchio::{
+    account_info::AccountInfo,
+    entrypoint::ProgramResult,
+    instruction::{AccountMeta, Instruction, Signer},
+    program::invoke_signed,
+    pubkey::Pubkey,
+};
+
+/// Allocate space for and assign an account at an address derived
+/// from a base public key and a seed.
+///
+/// ### Accounts:
+///   0. `[WRITE]` Allocated account
+///   1. `[SIGNER]` Base account
+pub struct AllocateWithSeed<'a, 'b, 'c> {
+    /// Allocated account.
+    pub account: &'a AccountInfo,
+
+    /// Base account.
+    ///
+    /// The account matching the base Pubkey below must be provided as
+    /// a signer, but may be the same as the funding account and provided
+    /// as account 0.
+    pub base: &'a AccountInfo,
+
+    /// String of ASCII chars, no longer than `Pubkey::MAX_SEED_LEN`.
+    pub seed: &'b str,
+
+    /// Number of bytes of memory to allocate.
+    pub space: u64,
+
+    /// Address of program that will own the new account.
+    pub owner: &'c Pubkey,
+}
+
+impl<'a, 'b, 'c> AllocateWithSeed<'a, 'b, 'c> {
+    #[inline(always)]
+    pub fn invoke(&self) -> ProgramResult {
+        self.invoke_signed(&[])
+    }
+
+    pub fn invoke_signed(&self, signers: &[Signer]) -> ProgramResult {
+        // account metadata
+        let account_metas: [AccountMeta; 2] = [
+            AccountMeta::writable_signer(self.account.key()),
+            AccountMeta::readonly_signer(self.base.key()),
+        ];
+
+        // instruction data
+        // - [0..4  ]: instruction discriminator
+        // - [4..36 ]: base pubkey
+        // - [36..40]: seed length
+        // - [40..  ]: seed (max 32)
+        // - [..  +8]: account space
+        // - [.. +32]: owner pubkey
+        let mut instruction_data = [0; 112];
+        instruction_data[0] = 9;
+        instruction_data[4..36].copy_from_slice(self.base.key());
+        instruction_data[36..40].copy_from_slice(&u32::to_le_bytes(self.seed.len() as u32));
+
+        let offset = 40 + self.seed.len();
+        instruction_data[40..offset].copy_from_slice(self.seed.as_bytes());
+        instruction_data[offset..offset + 8].copy_from_slice(&self.space.to_le_bytes());
+        instruction_data[offset + 8..offset + 40].copy_from_slice(self.owner.as_ref());
+
+        let instruction = Instruction {
+            program_id: &crate::ID,
+            accounts: &account_metas,
+            data: &instruction_data[..offset + 40],
+        };
+
+        invoke_signed(&instruction, &[self.account, self.base], signers)
+    }
+}

programs/system/src/instructions/allocate_with_seed.rs

@@ -0,0 +1,46 @@
+use pinocchio::{
+    account_info::AccountInfo,
+    entrypoint::ProgramResult,
+    instruction::{AccountMeta, Instruction, Signer},
+    program::invoke_signed,
+    pubkey::Pubkey,
+};
+
+/// Assign account to a program
+///
+/// ### Accounts:
+///   0. `[WRITE, SIGNER]` Assigned account public key
+pub struct Assign<'a, 'b> {
+    /// Account to be assigned.
+    pub account: &'a AccountInfo,
+
+    /// Program account to assign as owner.
+    pub owner: &'b Pubkey,
+}
+
+impl<'a, 'b> Assign<'a, 'b> {
+    #[inline(always)]
+    pub fn invoke(&self) -> ProgramResult {
+        self.invoke_signed(&[])
+    }
+
+    pub fn invoke_signed(&self, signers: &[Signer]) -> ProgramResult {
+        // account metadata
+        let account_metas: [AccountMeta; 1] = [AccountMeta::writable_signer(self.account.key())];
+
+        // instruction data
+        // -  [0..4 ]: instruction discriminator
+        // -  [4..36]: owner pubkey
+        let mut instruction_data = [0; 36];
+        instruction_data[0] = 1;
+        instruction_data[4..36].copy_from_slice(self.owner.as_ref());
+
+        let instruction = Instruction {
+            program_id: &crate::ID,
+            accounts: &account_metas,
+            data: &instruction_data,
+        };
+
+        invoke_signed(&instruction, &[self.account], signers)
+    }
+}

programs/system/src/instructions/assign.rs

@@ -0,0 +1,68 @@
+use pinocchio::{
+    account_info::AccountInfo,
+    entrypoint::ProgramResult,
+    instruction::{AccountMeta, Instruction, Signer},
+    program::invoke_signed,
+    pubkey::Pubkey,
+};
+
+/// Assign account to a program based on a seed.
+///
+/// ### Accounts:
+///   0. `[WRITE]` Assigned account
+///   1. `[SIGNER]` Base account
+pub struct AssignWithSeed<'a, 'b, 'c> {
+    /// Allocated account.
+    pub account: &'a AccountInfo,
+
+    /// Base account.
+    ///
+    /// The account matching the base Pubkey below must be provided as
+    /// a signer, but may be the same as the funding account and provided
+    /// as account 0.
+    pub base: &'a AccountInfo,
+
+    /// String of ASCII chars, no longer than `Pubkey::MAX_SEED_LEN`.
+    pub seed: &'b str,
+
+    /// Address of program that will own the new account.
+    pub owner: &'c Pubkey,
+}
+
+impl<'a, 'b, 'c> AssignWithSeed<'a, 'b, 'c> {
+    #[inline(always)]
+    pub fn invoke(&self) -> ProgramResult {
+        self.invoke_signed(&[])
+    }
+
+    pub fn invoke_signed(&self, signers: &[Signer]) -> ProgramResult {
+        // account metadata
+        let account_metas: [AccountMeta; 2] = [
+            AccountMeta::writable_signer(self.account.key()),
+            AccountMeta::readonly_signer(self.base.key()),
+        ];
+
+        // instruction data
+        // - [0..4  ]: instruction discriminator
+        // - [4..36 ]: base pubkey
+        // - [36..40]: seed length
+        // - [40..  ]: seed (max 32)
+        // - [.. +32]: owner pubkey
+        let mut instruction_data = [0; 104];
+        instruction_data[0] = 10;
+        instruction_data[4..36].copy_from_slice(self.base.key());
+        instruction_data[36..40].copy_from_slice(&u32::to_le_bytes(self.seed.len() as u32));
+
+        let offset = 40 + self.seed.len();
+        instruction_data[40..offset].copy_from_slice(self.seed.as_bytes());
+        instruction_data[offset..offset + 32].copy_from_slice(self.owner.as_ref());
+
+        let instruction = Instruction {
+            program_id: &crate::ID,
+            accounts: &account_metas,
+            data: &instruction_data[..offset + 32],
+        };
+
+        invoke_signed(&instruction, &[self.account, self.base], signers)
+    }
+}