Crate solana_program

Source
Expand description

The base library for all Safecoin on-chain Rust programs.

All Safecoin Rust programs that run on-chain will link to this crate, which acts as a standard library for Safecoin programs. Safecoin programs also link to the Rust standard library, though it is modified for the Safecoin runtime environment. While off-chain programs that interact with the Safecoin network can link to this crate, they typically instead use the safecoin-sdk crate, which reexports all modules from safecoin-program.

This library defines

Idiomatic examples of safecoin-program usage can be found in the Safecoin Program Library.

§Defining a safecoin program

Safecoin program crates have some unique properties compared to typical Rust programs:

  • They are often compiled for both on-chain use and off-chain use. This is primarily because off-chain clients may need access to data types defined by the on-chain program.
  • They do not define a main function, but instead define their entrypoint with the entrypoint! macro.
  • They are compiled as the “cdylib” crate type for dynamic loading by the Safecoin runtime.
  • They run in a constrained VM environment, and while they do have access to the Rust standard library, many features of the standard library, particularly related to OS services, will fail at runtime, will silently do nothing, or are not defined. See the restrictions to the Rust standard library in the Safecoin documentation for more.

Because multiple crates that are linked together cannot all define program entrypoints (see the entrypoint! documentation) a common convention is to use a Cargo feature called no-entrypoint to allow the program entrypoint to be disabled.

The skeleton of a Safecoin program typically looks like:

#[cfg(not(feature = "no-entrypoint"))]
pub mod entrypoint {
    use solana_program::{
        account_info::AccountInfo,
        entrypoint,
        entrypoint::ProgramResult,
        pubkey::Pubkey,
    };

    entrypoint!(process_instruction);

    pub fn process_instruction(
        program_id: &Pubkey,
        accounts: &[AccountInfo],
        instruction_data: &[u8],
    ) -> ProgramResult {
        // Decode and dispatch instructions here.
        todo!()
    }
}

// Additional code goes here.

With a Cargo.toml file that contains

[lib]
crate-type = ["cdylib", "rlib"]

[features]
no-entrypoint = []

Note that a Safecoin program must specify its crate-type as “cdylib”, and “cdylib” crates will automatically be discovered and built by the cargo build-bpf command. Safecoin programs also often have crate-type “rlib” so they can be linked to other Rust crates.

§On-chain vs. off-chain compilation targets

Safecoin programs run on the rbpf VM, which implements a variant of the eBPF instruction set. Because this crate can be compiled for both on-chain and off-chain execution, the environments of which are significantly different, it extensively uses conditional compilation to tailor its implementation to the environment. The cfg predicate used for identifying compilation for on-chain programs is target_os = "solana", as in this example from the safecoin-program codebase that logs a message via a syscall when run on-chain, and via a library call when offchain:

pub fn sol_log(message: &str) {
    #[cfg(target_os = "solana")]
    unsafe {
        sol_log_(message.as_ptr(), message.len() as u64);
    }

    #[cfg(not(target_os = "solana"))]
    program_stubs::sol_log(message);
}

This cfg pattern is suitable as well for user code that needs to work both on-chain and off-chain.

safecoin-program and safecoin-sdk were previously a single crate. Because of this history, and because of the dual-usage of safecoin-program for two different environments, it contains some features that are not available to on-chain programs at compile-time. It also contains some on-chain features that will fail in off-chain scenarios at runtime. This distinction is not well-reflected in the documentation.

For a more complete description of Safecoin’s implementation of eBPF and its limitations, see the main Safecoin documentation for on-chain programs.

§Core data types

  • Pubkey — The address of a Safecoin account. Some account addresses are ed25519 public keys, with corresponding secret keys that are managed off-chain. Often, though, account addresses do not have corresponding secret keys — as with program derived addresses — or the secret key is not relevant to the operation of a program, and may have even been disposed of. As running Safecoin programs can not safely create or manage secret keys, the full Keypair is not defined in safecoin-program but in safecoin-sdk.
  • Hash — A cryptographic hash. Used to uniquely identify blocks, and also for general purpose hashing.
  • AccountInfo — A description of a single Safecoin account. All accounts that might be accessed by a program invocation are provided to the program entrypoint as AccountInfo.
  • Instruction — A directive telling the runtime to execute a program, passing it a set of accounts and program-specific data.
  • ProgramError and ProgramResult — The error type that all programs must return, reported to the runtime as a u64.
  • Safe — The Safecoin native token type, with conversions to and from lamports, the smallest fractional unit of SAFE, in the native_token module.

§Serialization

Within the Safecoin runtime, programs, and network, at least three different serialization formats are used, and safecoin-program provides access to those needed by programs.

In user-written Safecoin program code, serialization is primarily used for accessing AccountInfo data and Instruction data, both of which are program-specific binary data. Every program is free to decide their own serialization format, but data received from other sources — sysvars for example — must be deserialized using the methods indicated by the documentation for that data or data type.

The three serialization formats in use in Safecoin are:

  • Borsh, a compact and well-specified format developed by the NEAR project, suitable for use in protocol definitions and for archival storage. It has a Rust implementation and a JavaScript implementation and is recommended for all purposes.

    Users need to import the borsh crate themselves — it is not re-exported by safecoin-program, though this crate provides several useful utilities in its borsh module that are not available in the borsh library.

    The Instruction::new_with_borsh function creates an Instruction by serializing a value with borsh.

  • Bincode, a compact serialization format that implements the Serde Rust APIs. As it does not have a specification nor a JavaScript implementation, and uses more CPU than borsh, it is not recommend for new code.

    Many system program and native program instructions are serialized with bincode, and it is used for other purposes in the runtime. In these cases Rust programmers are generally not directly exposed to the encoding format as it is hidden behind APIs.

    The Instruction::new_with_bincode function creates an Instruction by serializing a value with bincode.

  • Pack, a Safecoin-specific serialization API that is used by many older programs in the Safecoin Program Library to define their account format. It is difficult to implement and does not define a language-independent serialization format. It is not generally recommended for new code.

Developers should carefully consider the CPU cost of serialization, balanced against the need for correctness and ease of use: off-the-shelf serialization formats tend to be more expensive than carefully hand-written application-specific formats; but application-specific formats are more difficult to ensure the correctness of, and to provide multi-language implementations for. It is not uncommon for programs to pack and unpack their data with hand-written code.

§Cross-program instruction execution

Safecoin programs may call other programs, termed cross-program invocation (CPI), with the invoke and invoke_signed functions. When calling another program the caller must provide the Instruction to be invoked, as well as the AccountInfo for every account required by the instruction. Because the only way for a program to acquire AccountInfo values is by receiving them from the runtime at the program entrypoint, any account required by the callee program must transitively be required by the caller program, and provided by its caller.

A simple example of transferring lamports via CPI:

use solana_program::{
    account_info::{next_account_info, AccountInfo},
    entrypoint,
    entrypoint::ProgramResult,
    program::invoke,
    pubkey::Pubkey,
    system_instruction,
    system_program,
};

entrypoint!(process_instruction);

fn process_instruction(
    program_id: &Pubkey,
    accounts: &[AccountInfo],
    instruction_data: &[u8],
) -> ProgramResult {
    let account_info_iter = &mut accounts.iter();

    let payer = next_account_info(account_info_iter)?;
    let recipient = next_account_info(account_info_iter)?;
    // The system program is a required account to invoke a system
    // instruction, even though we don't use it directly.
    let system_account = next_account_info(account_info_iter)?;

    assert!(payer.is_writable);
    assert!(payer.is_signer);
    assert!(recipient.is_writable);
    assert!(system_program::check_id(system_account.key));

    let lamports = 1000000;

    invoke(
        &system_instruction::transfer(payer.key, recipient.key, lamports),
        &[payer.clone(), recipient.clone(), system_account.clone()],
    )
}

Safecoin also includes a mechanism to let programs control and sign for accounts without needing to protect a corresponding secret key, called program derived addresses. PDAs are derived with the Pubkey::find_program_address function. With a PDA, a program can call invoke_signed to call another program while virtually “signing” for the PDA.

A simple example of creating an account for a PDA:

use solana_program::{
    account_info::{next_account_info, AccountInfo},
    entrypoint,
    entrypoint::ProgramResult,
    program::invoke_signed,
    pubkey::Pubkey,
    system_instruction,
    system_program,
};

entrypoint!(process_instruction);

fn process_instruction(
    program_id: &Pubkey,
    accounts: &[AccountInfo],
    instruction_data: &[u8],
) -> ProgramResult {
    let account_info_iter = &mut accounts.iter();
    let payer = next_account_info(account_info_iter)?;
    let vault_pda = next_account_info(account_info_iter)?;
    let system_program = next_account_info(account_info_iter)?;

    assert!(payer.is_writable);
    assert!(payer.is_signer);
    assert!(vault_pda.is_writable);
    assert_eq!(vault_pda.owner, &system_program::ID);
    assert!(system_program::check_id(system_program.key));

    let vault_bump_seed = instruction_data[0];
    let vault_seeds = &[b"vault", payer.key.as_ref(), &[vault_bump_seed]];
    let expected_vault_pda = Pubkey::create_program_address(vault_seeds, program_id)?;

    assert_eq!(vault_pda.key, &expected_vault_pda);

    let lamports = 10000000;
    let vault_size = 16;

    invoke_signed(
        &system_instruction::create_account(
            &payer.key,
            &vault_pda.key,
            lamports,
            vault_size,
            &program_id,
        ),
        &[
            payer.clone(),
            vault_pda.clone(),
        ],
        &[
            &[
                b"vault",
                payer.key.as_ref(),
                &[vault_bump_seed],
            ],
        ]
    )?;
    Ok(())
}

§Native programs

Some safecoin programs are native programs, running native machine code that is distributed with the runtime, with well-known program IDs.

Some native programs can be invoked by other programs, but some can only be executed as “top-level” instructions included by off-chain clients in a Transaction.

This crate defines the program IDs for most native programs. Even though some native programs cannot be invoked by other programs, a Safecoin program may need access to their program IDs. For example, a program may need to verify that an ed25519 signature verification instruction was included in the same transaction as its own instruction. For many native programs, this crate also defines enums that represent the instructions they process, and constructors for building the instructions.

Locations of program IDs and instruction constructors are noted in the list below, as well as whether they are invokable by other programs.

While some native programs have been active since the genesis block, others are activated dynamically after a specific slot, and some are not yet active. This documentation does not distinguish which native programs are active on any particular network. The safecoin feature status CLI command can help in determining active features.

Native programs important to Safecoin program authors include:

§Sysvars

Sysvars are special accounts that contain dynamically-updated data about the network cluster, the blockchain history, and the executing transaction.

The program IDs for sysvars are defined in the sysvar module, and simple sysvars implement the Sysvar::get method, which loads a sysvar directly from the runtime, as in this example that logs the clock sysvar:

use solana_program::{
    account_info::AccountInfo,
    clock,
    entrypoint::ProgramResult,
    msg,
    pubkey::Pubkey,
    sysvar::Sysvar,
};

fn process_instruction(
    program_id: &Pubkey,
    accounts: &[AccountInfo],
    instruction_data: &[u8],
) -> ProgramResult {
    let clock = clock::Clock::get()?;
    msg!("clock: {:#?}", clock);
    Ok(())
}

Since Safecoin sysvars are accounts, if the AccountInfo is provided to the program, then the program can deserialize the sysvar with Sysvar::from_account_info to access its data, as in this example that again logs the clock sysvar.

use solana_program::{
    account_info::{next_account_info, AccountInfo},
    clock,
    entrypoint::ProgramResult,
    msg,
    pubkey::Pubkey,
    sysvar::Sysvar,
};

fn process_instruction(
    program_id: &Pubkey,
    accounts: &[AccountInfo],
    instruction_data: &[u8],
) -> ProgramResult {
    let account_info_iter = &mut accounts.iter();
    let clock_account = next_account_info(account_info_iter)?;
    let clock = clock::Clock::from_account_info(&clock_account)?;
    msg!("clock: {:#?}", clock);
    Ok(())
}

When possible, programs should prefer to call Sysvar::get instead of deserializing with Sysvar::from_account_info, as the latter imposes extra overhead of deserialization while also requiring the sysvar account address be passed to the program, wasting the limited space available to transactions. Deserializing sysvars that can instead be retrieved with Sysvar::get should be only be considered for compatibility with older programs that pass around sysvar accounts.

Some sysvars are too large to deserialize within a program, and Sysvar::from_account_info returns an error. Some sysvars are too large to deserialize within a program, and attempting to will exhaust the program’s compute budget. Some sysvars do not implement Sysvar::get and return an error. Some sysvars have custom deserializers that do not implement the Sysvar trait. These cases are documented in the modules for individual sysvars.

For more details see the Safecoin documentation on sysvars.

Modules§

account_info
Account information.
address_lookup_table_account
The definition of address lookup table accounts.
blake3
Hashing with the blake3 hash function.
borsh
Utilities for the borsh serialization format.
bpf_loader
The latest BPF loader native program.
bpf_loader_deprecated
The original and now deprecated Safecoin BPF loader.
bpf_loader_upgradeable
An upgradeable BPF loader native program.
clock
Information about the network’s clock, ticks, slots, etc.
config
The config native program.
debug_account_data
Debug-formatting of account data.
decode_error
Converting custom error codes to enums.
ed25519_program
The ed25519 native program.
entrypoint
The Rust-based BPF program entry point supported by the latest BPF loader.
entrypoint_deprecated
The Rust-based BPF program entry point supported by the original BPF loader.
epoch_schedule
Configuration for epochs and slots.
feature
Runtime features.
fee_calculator
Calculation of transaction fees.
hash
Hashing with the SHA-256 hash function, and a general Hash type.
incinerator
A designated address for burning lamports.
instruction
Types for directing the execution of Safecoin programs.
keccak
Hashing with the keccak (SHA-3) hash function.
lamports
Defines the LamportsError type.
loader_instruction
Instructions for the non-upgradable BPF loader.
loader_upgradeable_instruction
Instructions for the upgradable BPF loader.
log
Logging utilities for Rust-based Safecoin programs.
message
Sequences of Instructions executed within a single transaction.
native_token
Definitions for the native SAFE token and its fractional lamports.
nonce
Durable transaction nonces.
program
Cross-program invocation.
program_error
The ProgramError type and related definitions.
program_memory
Basic low-level memory operations.
program_option
A C representation of Rust’s Option, used across the FFI boundary for Safecoin program interfaces.
program_pack
The Pack serialization trait.
program_stubs
Implementations of syscalls used when safecoin-program is built for non-BPF targets.
program_utils
Contains a single utility function for deserializing from bincode.
pubkey
Safecoin account addresses.
rent
Configuration for network rent.
sanitize
A trait for sanitizing values and members of over the wire messages.
sdk_ids
A vector of Safecoin SDK IDs
secp256k1_program
The secp256k1 native program.
secp256k1_recover
Public key recovery from secp256k1 ECDSA signatures.
serde_varint
serialize_utils
Helpers for reading and writing bytes.
short_vec
Compact serde-encoding of vectors with small length.
slot_hashes
A type to hold data for the SlotHashes sysvar.
slot_history
A type to hold data for the SlotHistory sysvar.
stake
The stake native program.
stake_history
A type to hold data for the StakeHistory sysvar.
syscalls
system_instruction
Instructions and constructors for the system program.
system_program
The system native program.
sysvar
Access to special accounts with dynamically-updated data.
vote
The vote native program.

Macros§

copy_field
custom_heap_default
Define the default global allocator.
custom_panic_default
Define the default global panic handler.
declare_deprecated_id
Same as declare_id except that it reports that this ID has been deprecated.
declare_deprecated_sysvar_id
Same as declare_sysvar_id except that it reports that this ID has been deprecated.
declare_id
Convenience macro to declare a static public key and functions to interact with it.
declare_sysvar_id
Declares an ID that implements SysvarId.
entrypoint
Declare the program entry point and set up global handlers.
entrypoint_deprecated
Declare the program entry point.
impl_sysvar_get
Implements the Sysvar::get method for both BPF and host targets.
infoDeprecated
Print a message to the log.
msg
Print a message to the log.
pubkey
Convenience macro to define a static public key.
unchecked_div_by_const
Convenience macro for doing integer division where the operation’s safety can be checked at compile-time.

Functions§

clone_zeroed

Attribute Macros§

wasm_bindgen
Re-export of wasm-bindgen.