arch_program 0.12.0

A Rust library for building programs that run inside the Arch Virtual Machine. Provides core functionality for creating instructions, managing accounts, handling program errors, and interacting with the Arch runtime environment. Includes utilities for logging, transaction handling, and Bitcoin UTXO management.
Documentation
use crate::{
    account::AccountMeta,
    decode_error::DecodeError,
    instruction::{Instruction, InstructionError},
    pubkey::Pubkey,
    system_instruction,
    vote::state::VoteState,
};
use num_derive::{FromPrimitive, ToPrimitive};
use thiserror::Error;

use super::{
    program::{VOTE_ACCOUNT_SEED, VOTE_PROGRAM_ID},
    state::VoteInit,
};

#[derive(Error, Debug, Clone, PartialEq, Eq, FromPrimitive, ToPrimitive)]
pub enum VoteError {
    #[error("not enough credits to redeem")]
    NoCreditsToRedeem,
    #[error("too soon to reauthorize")]
    TooSoonToReauthorize,
}

impl From<VoteError> for InstructionError {
    fn from(error: VoteError) -> Self {
        InstructionError::VoteError(error)
    }
}

impl<E> DecodeError<E> for VoteError {
    fn type_of() -> &'static str {
        "VoteError"
    }
}

#[derive(
    Serialize, Deserialize, Debug, PartialEq, Eq, Clone, wincode::SchemaWrite, wincode::SchemaRead,
)]
pub enum VoteInstruction {
    /// Initialize a stake with lockup and authorization information
    ///
    /// # Account references
    ///   0. `[WRITE]` Uninitialized validator account
    ///   1. `[]` Rent sysvar
    ///
    /// Authorized carries pubkeys that must sign staker transactions
    ///   and withdrawer transactions.
    /// Lockup carries information about withdrawal restrictions
    Initialize(VoteInit),
    Authorize(Pubkey),
    UpdateCommission(u8),
    InitializeSharedValidatorAccountChunk {
        first_chunk: bool,
        last_chunk: bool,
        start_offset: u64,
        chunk: Vec<u8>,
    },
    AddPeerToWhitelist(Vec<u8>),
    RemovePeerFromWhitelist(Vec<u8>),
}

/// Initializes a vote account. The validator identity `vote_init.node_pubkey`
/// must sign: it agrees to be represented by this vote account.
pub fn initialize(vote_pubkey: &Pubkey, vote_init: &VoteInit) -> Instruction {
    Instruction::new_with_wincode(
        VOTE_PROGRAM_ID,
        VoteInstruction::Initialize(*vote_init),
        vec![
            AccountMeta::new(*vote_pubkey, false),
            AccountMeta::new_readonly(*vote_init.node_pubkey(), true),
        ],
    )
}

pub fn create_account(
    from_pubkey: &Pubkey,
    vote_pubkey: &Pubkey,
    vote_init: &VoteInit,
    lamports: u64,
) -> Vec<Instruction> {
    vec![
        system_instruction::create_account(
            from_pubkey,
            vote_pubkey,
            lamports,
            VoteState::size_of_new() as u64,
            &VOTE_PROGRAM_ID,
        ),
        initialize(vote_pubkey, vote_init),
    ]
}

/// Creates and initializes the vote account of the validator whose identity
/// is `node_pubkey`, at
/// [`vote_account_address`](super::program::vote_account_address). The
/// identity signs as the base of the derived address.
pub fn create_account_with_seed(
    from_pubkey: &Pubkey,
    node_pubkey: &Pubkey,
    vote_init: &VoteInit,
    lamports: u64,
) -> Vec<Instruction> {
    let vote_pubkey = super::program::vote_account_address(node_pubkey);
    vec![
        system_instruction::create_account_with_seed(
            from_pubkey,
            &vote_pubkey,
            node_pubkey,
            VOTE_ACCOUNT_SEED,
            lamports,
            VoteState::size_of_new() as u64,
            &VOTE_PROGRAM_ID,
        ),
        initialize(&vote_pubkey, vote_init),
    ]
}

pub fn authorize(vote_pubkey: &Pubkey, authority: &Pubkey, new_authority: &Pubkey) -> Instruction {
    Instruction::new_with_wincode(
        VOTE_PROGRAM_ID,
        VoteInstruction::Authorize(*new_authority),
        vec![
            AccountMeta::new(*vote_pubkey, false),
            AccountMeta::new(*authority, true),
        ],
    )
}

pub fn update_commission(vote_pubkey: &Pubkey, authority: &Pubkey, commission: u8) -> Instruction {
    Instruction::new_with_wincode(
        VOTE_PROGRAM_ID,
        VoteInstruction::UpdateCommission(commission),
        vec![
            AccountMeta::new(*vote_pubkey, false),
            AccountMeta::new(*authority, true),
        ],
    )
}

pub fn initialize_shared_validator_account_chunk(
    shared_validator_staging_pubkey: &Pubkey,
    shared_validator_pubkey: &Pubkey,
    first_chunk: bool,
    last_chunk: bool,
    start_offset: u64,
    chunk: Vec<u8>,
) -> Instruction {
    Instruction::new_with_wincode(
        VOTE_PROGRAM_ID,
        VoteInstruction::InitializeSharedValidatorAccountChunk {
            first_chunk,
            last_chunk,
            start_offset,
            chunk,
        },
        vec![
            AccountMeta::new(*shared_validator_staging_pubkey, false),
            AccountMeta::new(*shared_validator_pubkey, false),
        ],
    )
}

pub fn add_peer_to_whitelist(
    shared_validator_pubkey: &Pubkey,
    bootnode_pubkey: &[u8; 33],
    peer_pubkey: &[u8; 33],
) -> Instruction {
    Instruction::new_with_wincode(
        VOTE_PROGRAM_ID,
        VoteInstruction::AddPeerToWhitelist(peer_pubkey.to_vec()),
        vec![
            AccountMeta::new(*shared_validator_pubkey, false),
            AccountMeta::new(Pubkey::from_slice(&bootnode_pubkey[1..33]), true),
        ],
    )
}

pub fn remove_peer_from_whitelist(
    shared_validator_pubkey: &Pubkey,
    bootnode_pubkey: &[u8; 33],
    peer_pubkey: &[u8; 33],
) -> Instruction {
    Instruction::new_with_wincode(
        VOTE_PROGRAM_ID,
        VoteInstruction::RemovePeerFromWhitelist(peer_pubkey.to_vec()),
        vec![
            AccountMeta::new(*shared_validator_pubkey, false),
            AccountMeta::new(Pubkey::from_slice(&bootnode_pubkey[1..33]), true),
        ],
    )
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Wincode encodes the variant index; independently built clients
    /// (bootnode, arch-cli) depend on these values.
    #[test]
    fn vote_instruction_discriminants_are_stable() {
        let discriminant = |ix: &VoteInstruction| -> u32 {
            let bytes = wincode::serialize(ix).unwrap();
            u32::from_le_bytes(bytes[..4].try_into().unwrap())
        };

        assert_eq!(
            discriminant(&VoteInstruction::AddPeerToWhitelist(vec![])),
            4
        );
        assert_eq!(
            discriminant(&VoteInstruction::RemovePeerFromWhitelist(vec![])),
            5
        );
    }
}