Crate waffles_solana_program
source ·Expand description
The base library for all Solana on-chain Rust programs.
All Solana Rust programs that run on-chain will link to this crate, which
acts as a standard library for Solana programs. Solana programs also link to
the Rust standard library, though it is modified for the
Solana runtime environment. While off-chain programs that interact with the
Solana network can link to this crate, they typically instead use the
solana-sdk
crate, which reexports all modules from solana-program
.
This library defines
- macros for declaring the program entrypoint,
- core data types,
- logging macros,
- serialization methods,
- methods for cross-program instruction execution,
- program IDs and instruction constructors for the system program and other native programs,
- sysvar accessors.
Idiomatic examples of solana-program
usage can be found in
the Solana Program Library.
Defining a solana program
Solana 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 theentrypoint!
macro. - They are compiled as the “cdylib” crate type for dynamic loading by the Solana 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 Solana 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 Solana 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 Solana program must specify its crate-type as “cdylib”, and
“cdylib” crates will automatically be discovered and built by the cargo build-bpf
command. Solana programs also often have crate-type “rlib” so
they can be linked to other Rust crates.
On-chain vs. off-chain compilation targets
Solana 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 solana-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.
solana-program
and solana-sdk
were previously a single crate. Because of
this history, and because of the dual-usage of solana-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 Solana’s implementation of eBPF and its limitations, see the main Solana documentation for on-chain programs.
Core data types
Pubkey
— The address of a Solana 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 Solana programs can not safely create or manage secret keys, the fullKeypair
is not defined insolana-program
but insolana-sdk
.Hash
— A cryptographic hash. Used to uniquely identify blocks, and also for general purpose hashing.AccountInfo
— A description of a single Solana account. All accounts that might be accessed by a program invocation are provided to the program entrypoint asAccountInfo
.Instruction
— A directive telling the runtime to execute a program, passing it a set of accounts and program-specific data.ProgramError
andProgramResult
— The error type that all programs must return, reported to the runtime as au64
.Sol
— The Solana native token type, with conversions to and from lamports, the smallest fractional unit of SOL, in thenative_token
module.
Serialization
Within the Solana runtime, programs, and network, at least three different
serialization formats are used, and solana-program
provides access to
those needed by programs.
In user-written Solana 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 Solana 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 bysolana-program
, though this crate provides several useful utilities in itsborsh
module that are not available in theborsh
library.The
Instruction::new_with_borsh
function creates anInstruction
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 anInstruction
by serializing a value with bincode. -
Pack
, a Solana-specific serialization API that is used by many older programs in the Solana 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
Solana 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()],
)
}
Solana 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 solana 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 Solana 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 solana feature status
CLI command
can help in determining active features.
Native programs important to Solana program authors include:
-
System Program: Creates new accounts, allocates account data, assigns accounts to owning programs, transfers lamports from System Program owned accounts and pays transaction fees.
- ID:
solana_program::system_program
- Instruction:
solana_program::system_instruction
- Invokable by programs? yes
- ID:
-
Compute Budget Program: Requests additional CPU or memory resources for a transaction. This program does nothing when called from another program.
- ID:
solana_sdk::compute_budget
- Instruction:
solana_sdk::compute_budget
- Invokable by programs? no
- ID:
-
ed25519 Program: Verifies an ed25519 signature.
- ID:
solana_program::ed25519_program
- Instruction:
solana_sdk::ed25519_instruction
- Invokable by programs? no
- ID:
-
secp256k1 Program: Verifies secp256k1 public key recovery operations.
- ID:
solana_program::secp256k1_program
- Instruction:
solana_sdk::secp256k1_instruction
- Invokable by programs? no
- ID:
-
BPF Loader: Deploys, and executes immutable programs on the chain.
- ID:
solana_program::bpf_loader
- Instruction:
solana_program::loader_instruction
- Invokable by programs? yes
- ID:
-
Upgradable BPF Loader: Deploys, upgrades, and executes upgradable programs on the chain.
- ID:
solana_program::bpf_loader_upgradeable
- Instruction:
solana_program::loader_upgradeable_instruction
- Invokable by programs? yes
- ID:
-
Deprecated BPF Loader: Deploys, and executes immutable programs on the chain.
- ID:
solana_program::bpf_loader_deprecated
- Instruction:
solana_program::loader_instruction
- Invokable by programs? yes
- ID:
Modules
- Account information.
- The definition of address lookup table accounts.
- Hashing with the blake3 hash function.
- Utilities for the borsh serialization format.
- The latest BPF loader native program.
- The original and now deprecated Solana BPF loader.
- An upgradeable BPF loader native program.
- Information about the network’s clock, ticks, slots, etc.
- Debug-formatting of account data.
- Converting custom error codes to enums.
- The Rust-based BPF program entrypoint supported by the latest BPF loader.
- The Rust-based BPF program entrypoint supported by the original BPF loader.
- Configuration for epochs and slots.
- Runtime features.
- Calculation of transaction fees.
- A designated address for burning lamports.
- Types for directing the execution of Solana programs.
- Hashing with the keccak (SHA-3) hash function.
- Defines the
LamportsError
type. - Instructions for the non-upgradable BPF loader.
- Instructions for the upgradable BPF loader.
- Logging utilities for Rust-based Solana programs.
- Sequences of
Instruction
s executed within a single transaction. - Definitions for the native SOL token and its fractional lamports.
- Durable transaction nonces.
- Cross-program invocation.
- The
ProgramError
type and related definitions. - Basic low-level memory operations.
- A C representation of Rust’s
Option
, used across the FFI boundary for Solana program interfaces. - The
Pack
serialization trait. - Implementations of syscalls used when
solana-program
is built for non-SBF targets. - Contains a single utility function for deserializing from bincode.
- Solana account addresses.
- Configuration for network rent.
- A trait for sanitizing values and members of over the wire messages.
- A vector of Solana SDK IDs.
- Public key recovery from secp256k1 ECDSA signatures.
- Integers that serialize to variable size.
- Helpers for reading and writing bytes.
- Compact serde-encoding of vectors with small length.
- A type to hold data for the
SlotHashes
sysvar. - A type to hold data for the
SlotHistory
sysvar. - The stake native program.
- A type to hold data for the
StakeHistory
sysvar. - Declarations of Solana program syscalls.
- Instructions and constructors for the system program.
- Access to special accounts with dynamically-updated data.
- The vote native program.
Macros
- Define the default global allocator.
- Define the default global panic handler.
- Same as
declare_id
except that it reports that this ID has been deprecated. - Same as
declare_sysvar_id
except that it reports that this ID has been deprecated. - Convenience macro to declare a static public key and functions to interact with it.
- Declares an ID that implements
SysvarId
. - Declare the program entrypoint and set up global handlers.
- Declare the program entrypoint.
- Implements the
Sysvar::get
method for both SBF and host targets. - infoDeprecatedPrint a message to the log.
- Print a message to the log.
- Convenience macro to define a static public key.
- Convenience macro for doing integer division where the operation’s safety can be checked at compile-time.
Attribute Macros
- Re-export of wasm-bindgen.