tessl/pypi-solders
Python bindings for Solana Rust tools providing high-performance blockchain development primitives, RPC functionality, and testing infrastructure.
—
Pending
system-programs.mddocs/
System Programs
Built-in Solana programs including the System program for account creation and transfers, the Compute Budget program for transaction optimization, and Address Lookup Table operations. These programs provide essential blockchain functionality and performance management.
Capabilities
System Program Operations
Core blockchain operations for account management, transfers, and state changes provided by the System program.
# System Program ID
ID: Final[Pubkey] = Pubkey.from_string("11111111111111111111111111111112")Account Creation and Management
def create_account(params: CreateAccountParams) -> Instruction:
"""
Create a new account with specified size and owner.
Parameters:
- params: CreateAccountParams, account creation parameters
Returns:
Instruction for creating account
"""
class CreateAccountParams:
"""Parameters for create_account instruction."""
from_pubkey: Pubkey # Funding account (must sign)
to_pubkey: Pubkey # New account address
lamports: int # Initial balance in lamports
space: int # Data size in bytes
owner: Pubkey # Program that will own the account
def decode_create_account(instruction: Instruction) -> CreateAccountParams:
"""
Decode create account instruction.
Parameters:
- instruction: Instruction, create account instruction
Returns:
CreateAccountParams with decoded parameters
"""
def create_account_with_seed(params: CreateAccountWithSeedParams) -> Instruction:
"""
Create account with deterministic address based on seed.
Parameters:
- params: CreateAccountWithSeedParams, creation parameters
Returns:
Instruction for creating account with seed
"""
class CreateAccountWithSeedParams:
"""Parameters for create_account_with_seed instruction."""
from_pubkey: Pubkey # Funding account
to_pubkey: Pubkey # Derived account address
base: Pubkey # Base pubkey for derivation
seed: str # Seed string for derivation
lamports: int # Initial balance
space: int # Data size
owner: Pubkey # Program ownerAccount Assignment and Allocation
def assign(params: AssignParams) -> Instruction:
"""
Assign account to a new owner program.
Parameters:
- params: AssignParams, assignment parameters
Returns:
Instruction for assigning account
"""
class AssignParams:
"""Parameters for assign instruction."""
account_pubkey: Pubkey # Account to assign
owner: Pubkey # New owner program
def assign_with_seed(params: AssignWithSeedParams) -> Instruction:
"""
Assign account created with seed to new owner.
Parameters:
- params: AssignWithSeedParams, assignment parameters
Returns:
Instruction for assigning account with seed
"""
class AssignWithSeedParams:
"""Parameters for assign_with_seed instruction."""
account_pubkey: Pubkey # Account to assign
base: Pubkey # Base pubkey used in derivation
seed: str # Seed string used in derivation
owner: Pubkey # New owner program
def allocate(params: AllocateParams) -> Instruction:
"""
Allocate space in an account for data storage.
Parameters:
- params: AllocateParams, allocation parameters
Returns:
Instruction for allocating space
"""
class AllocateParams:
"""Parameters for allocate instruction."""
account_pubkey: Pubkey # Account to allocate space in
space: int # Number of bytes to allocate
def allocate_with_seed(params: AllocateWithSeedParams) -> Instruction:
"""
Allocate space in account created with seed.
Parameters:
- params: AllocateWithSeedParams, allocation parameters
Returns:
Instruction for allocating space with seed
"""
class AllocateWithSeedParams:
"""Parameters for allocate_with_seed instruction."""
account_pubkey: Pubkey # Account to allocate
base: Pubkey # Base pubkey for derivation
seed: str # Seed string for derivation
space: int # Space to allocateLamport Transfers
def transfer(params: TransferParams) -> Instruction:
"""
Transfer lamports between accounts.
Parameters:
- params: TransferParams, transfer parameters
Returns:
Instruction for transferring lamports
"""
class TransferParams:
"""Parameters for transfer instruction."""
from_pubkey: Pubkey # Source account (must sign)
to_pubkey: Pubkey # Destination account
lamports: int # Amount to transfer
def transfer_with_seed(params: TransferWithSeedParams) -> Instruction:
"""
Transfer lamports from account created with seed.
Parameters:
- params: TransferWithSeedParams, transfer parameters
Returns:
Instruction for transferring with seed
"""
class TransferWithSeedParams:
"""Parameters for transfer_with_seed instruction."""
from_pubkey: Pubkey # Source account
from_base: Pubkey # Base pubkey for source derivation
from_seed: str # Seed string for source
from_owner: Pubkey # Owner of source account
to_pubkey: Pubkey # Destination account
lamports: int # Amount to transfer
def transfer_many(transfers: List[TransferParams]) -> List[Instruction]:
"""
Create multiple transfer instructions efficiently.
Parameters:
- transfers: List[TransferParams], list of transfers to create
Returns:
List[Instruction], transfer instructions
"""Nonce Account Operations
def initialize_nonce_account(params: InitializeNonceAccountParams) -> Instruction:
"""
Initialize account as nonce account for durable transactions.
Parameters:
- params: InitializeNonceAccountParams, initialization parameters
Returns:
Instruction for initializing nonce account
"""
class InitializeNonceAccountParams:
"""Parameters for initialize_nonce_account instruction."""
nonce_pubkey: Pubkey # Nonce account address
authorized_pubkey: Pubkey # Authority for nonce operations
def advance_nonce_account(params: AdvanceNonceAccountParams) -> Instruction:
"""
Advance nonce value to invalidate previous transactions.
Parameters:
- params: AdvanceNonceAccountParams, advance parameters
Returns:
Instruction for advancing nonce
"""
class AdvanceNonceAccountParams:
"""Parameters for advance_nonce_account instruction."""
nonce_pubkey: Pubkey # Nonce account
authorized_pubkey: Pubkey # Authority (must sign)
def withdraw_nonce_account(params: WithdrawNonceAccountParams) -> Instruction:
"""
Withdraw lamports from nonce account.
Parameters:
- params: WithdrawNonceAccountParams, withdrawal parameters
Returns:
Instruction for withdrawing from nonce account
"""
class WithdrawNonceAccountParams:
"""Parameters for withdraw_nonce_account instruction."""
nonce_pubkey: Pubkey # Nonce account
authorized_pubkey: Pubkey # Authority (must sign)
to_pubkey: Pubkey # Recipient account
lamports: int # Amount to withdraw
def authorize_nonce_account(params: AuthorizeNonceAccountParams) -> Instruction:
"""
Change nonce account authority.
Parameters:
- params: AuthorizeNonceAccountParams, authorization parameters
Returns:
Instruction for changing nonce authority
"""
class AuthorizeNonceAccountParams:
"""Parameters for authorize_nonce_account instruction."""
nonce_pubkey: Pubkey # Nonce account
authorized_pubkey: Pubkey # Current authority (must sign)
new_authorized_pubkey: Pubkey # New authority
def create_nonce_account(
from_pubkey: Pubkey,
nonce_pubkey: Pubkey,
authorized_pubkey: Pubkey,
lamports: int
) -> List[Instruction]:
"""
Create and initialize nonce account in single call.
Parameters:
- from_pubkey: Pubkey, funding account
- nonce_pubkey: Pubkey, new nonce account
- authorized_pubkey: Pubkey, nonce authority
- lamports: int, initial balance
Returns:
List[Instruction], create and initialize instructions
"""
def create_nonce_account_with_seed(
from_pubkey: Pubkey,
nonce_pubkey: Pubkey,
base: Pubkey,
seed: str,
authorized_pubkey: Pubkey,
lamports: int
) -> List[Instruction]:
"""
Create and initialize nonce account with seed derivation.
Returns:
List[Instruction], create and initialize instructions
"""Address Lookup Table Operations
Efficient address compression through lookup table management.
def create_lookup_table(params: CreateLookupTableParams) -> Instruction:
"""
Create new address lookup table.
Parameters:
- params: CreateLookupTableParams, creation parameters
Returns:
Instruction for creating lookup table
"""
class CreateLookupTableParams:
"""Parameters for create_lookup_table instruction."""
lookup_table: Pubkey # Lookup table account address
authority: Pubkey # Table authority
payer: Pubkey # Fee payer (must sign)
recent_slot: int # Recent slot for derivation
def create_lookup_table_signed(params: CreateLookupTableSignedParams) -> Instruction:
"""
Create lookup table with explicit signing.
Parameters:
- params: CreateLookupTableSignedParams, creation parameters
Returns:
Instruction for creating signed lookup table
"""
def extend_lookup_table(params: ExtendLookupTableParams) -> Instruction:
"""
Add addresses to existing lookup table.
Parameters:
- params: ExtendLookupTableParams, extension parameters
Returns:
Instruction for extending lookup table
"""
class ExtendLookupTableParams:
"""Parameters for extend_lookup_table instruction."""
lookup_table: Pubkey # Lookup table account
authority: Pubkey # Table authority (must sign)
payer: Optional[Pubkey] # Fee payer for expansion
new_addresses: List[Pubkey] # Addresses to add
def deactivate_lookup_table(params: DeactivateLookupTableParams) -> Instruction:
"""
Deactivate lookup table (prepare for closure).
Parameters:
- params: DeactivateLookupTableParams, deactivation parameters
Returns:
Instruction for deactivating lookup table
"""
class DeactivateLookupTableParams:
"""Parameters for deactivate_lookup_table instruction."""
lookup_table: Pubkey # Lookup table account
authority: Pubkey # Table authority (must sign)
def freeze_lookup_table(params: FreezeLookupTableParams) -> Instruction:
"""
Freeze lookup table (prevent further modifications).
Parameters:
- params: FreezeLookupTableParams, freeze parameters
Returns:
Instruction for freezing lookup table
"""
class FreezeLookupTableParams:
"""Parameters for freeze_lookup_table instruction."""
lookup_table: Pubkey # Lookup table account
authority: Pubkey # Table authority (must sign)
def close_lookup_table(params: CloseLookupTableParams) -> Instruction:
"""
Close deactivated lookup table and reclaim rent.
Parameters:
- params: CloseLookupTableParams, closure parameters
Returns:
Instruction for closing lookup table
"""
class CloseLookupTableParams:
"""Parameters for close_lookup_table instruction."""
lookup_table: Pubkey # Lookup table account
authority: Pubkey # Table authority (must sign)
recipient: Pubkey # Recipient of reclaimed rentCompute Budget Program
Transaction performance optimization through compute unit management.
# Compute Budget Program ID
ID: Final[Pubkey] = Pubkey.from_string("ComputeBudget111111111111111111111111111111")def set_compute_unit_limit(units: int) -> Instruction:
"""
Set maximum compute units for transaction.
Parameters:
- units: int, compute unit limit (max 1,400,000)
Returns:
Instruction for setting compute limit
"""
def set_compute_unit_price(micro_lamports: int) -> Instruction:
"""
Set compute unit price for transaction prioritization.
Parameters:
- micro_lamports: int, price per compute unit in micro-lamports
Returns:
Instruction for setting compute price
"""
def request_heap_frame(bytes: int) -> Instruction:
"""
Request additional heap memory for transaction.
Parameters:
- bytes: int, additional heap bytes requested
Returns:
Instruction for requesting heap frame
"""
class ComputeBudget:
"""
Compute budget configuration for transaction optimization.
"""
def __init__(self, max_units: int, heap_size: int, additional_fee: int):
"""
Create compute budget configuration.
Parameters:
- max_units: int, maximum compute units allowed
- heap_size: int, heap memory allocation
- additional_fee: int, prioritization fee in micro-lamports
"""
@property
def max_units(self) -> int:
"""Maximum compute units."""
@property
def heap_size(self) -> int:
"""Heap memory size."""
@property
def additional_fee(self) -> int:
"""Additional fee for prioritization."""Usage Examples
Basic Account Operations
from solders.system_program import (
create_account, transfer, CreateAccountParams, TransferParams, ID
)
from solders.keypair import Keypair
from solders.transaction import Transaction
# Generate keypairs
payer = Keypair()
new_account = Keypair()
recipient = Keypair()
# Create account instruction
create_params = CreateAccountParams(
from_pubkey=payer.pubkey(),
to_pubkey=new_account.pubkey(),
lamports=2039280, # Rent-exempt minimum for token account
space=165, # Token account size
owner=ID # System program owns initially
)
create_ix = create_account(create_params)
# Transfer instruction
transfer_params = TransferParams(
from_pubkey=payer.pubkey(),
to_pubkey=recipient.pubkey(),
lamports=1000000 # 0.001 SOL
)
transfer_ix = transfer(transfer_params)
# Combine in transaction
transaction = Transaction.new_with_payer([create_ix, transfer_ix], payer.pubkey())Nonce Account Management
from solders.system_program import (
create_nonce_account, advance_nonce_account, AdvanceNonceAccountParams
)
# Create nonce account for durable transactions
nonce_keypair = Keypair()
authority = Keypair()
# Create and initialize nonce account
nonce_instructions = create_nonce_account(
from_pubkey=payer.pubkey(),
nonce_pubkey=nonce_keypair.pubkey(),
authorized_pubkey=authority.pubkey(),
lamports=2000000 # Rent-exempt amount
)
nonce_tx = Transaction.new_with_payer(nonce_instructions, payer.pubkey())
nonce_tx.sign([payer, nonce_keypair], recent_blockhash)
# Later: advance nonce for new transaction
advance_params = AdvanceNonceAccountParams(
nonce_pubkey=nonce_keypair.pubkey(),
authorized_pubkey=authority.pubkey()
)
advance_ix = advance_nonce_account(advance_params)Address Lookup Table Operations
from solders.system_program import (
create_lookup_table, extend_lookup_table,
CreateLookupTableParams, ExtendLookupTableParams
)
from solders.address_lookup_table_account import derive_lookup_table_address
# Create lookup table
recent_slot = 100000000 # Current slot number
authority = Keypair()
# Derive lookup table address
lookup_table_address, bump = derive_lookup_table_address(
authority.pubkey(), recent_slot
)
# Create lookup table
create_table_params = CreateLookupTableParams(
lookup_table=lookup_table_address,
authority=authority.pubkey(),
payer=payer.pubkey(),
recent_slot=recent_slot
)
create_table_ix = create_lookup_table(create_table_params)
# Add addresses to table
frequently_used_addresses = [
Pubkey.from_string("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"), # Token program
Pubkey.from_string("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL"), # Associated token
# ... more frequently used addresses
]
extend_params = ExtendLookupTableParams(
lookup_table=lookup_table_address,
authority=authority.pubkey(),
payer=payer.pubkey(),
new_addresses=frequently_used_addresses
)
extend_ix = extend_lookup_table(extend_params)Compute Budget Optimization
from solders.compute_budget import set_compute_unit_limit, set_compute_unit_price
# Set compute budget for transaction optimization
compute_limit_ix = set_compute_unit_limit(200000) # Reduce from default 1.4M
compute_price_ix = set_compute_unit_price(1000) # 1000 micro-lamports per CU
# Add to transaction (compute budget instructions go first)
optimized_tx = Transaction.new_with_payer([
compute_limit_ix,
compute_price_ix,
transfer_ix # Your main instruction
], payer.pubkey())Account Creation with Seed
from solders.system_program import create_account_with_seed, CreateAccountWithSeedParams
from solders.pubkey import Pubkey
# Create account with deterministic address
base_pubkey = payer.pubkey()
seed = "my_deterministic_seed"
# Calculate derived address
derived_address = Pubkey.create_with_seed(base_pubkey, seed, ID)
# Create account with seed
create_seed_params = CreateAccountWithSeedParams(
from_pubkey=payer.pubkey(),
to_pubkey=derived_address,
base=base_pubkey,
seed=seed,
lamports=1000000,
space=100,
owner=ID
)
create_seed_ix = create_account_with_seed(create_seed_params)Multi-Transfer Operations
# Transfer to multiple recipients efficiently
recipients = [recipient1.pubkey(), recipient2.pubkey(), recipient3.pubkey()]
amounts = [500000, 750000, 1000000] # Different amounts
transfer_params_list = [
TransferParams(
from_pubkey=payer.pubkey(),
to_pubkey=recipient,
lamports=amount
)
for recipient, amount in zip(recipients, amounts)
]
# Create all transfer instructions
transfer_instructions = transfer_many(transfer_params_list)
# Add to transaction
multi_transfer_tx = Transaction.new_with_payer(transfer_instructions, payer.pubkey())Instruction Decoding
Decoding System Instructions
from solders.system_program import (
decode_create_account, decode_transfer, decode_assign
)
# Decode instructions from transaction
for instruction in transaction.message.instructions:
if instruction.program_id == system_program.ID:
try:
# Try different decoders based on instruction data
create_params = decode_create_account(instruction)
print(f"Create account: {create_params.space} bytes for {create_params.to_pubkey}")
except:
try:
transfer_params = decode_transfer(instruction)
print(f"Transfer: {transfer_params.lamports} lamports to {transfer_params.to_pubkey}")
except:
print("Unknown system instruction")Constants and Limits
System Program Limits
# Maximum account data size
MAX_PERMITTED_DATA_LENGTH: Final[int] = 10 * 1024 * 1024 # 10 MB
# Minimum lamports for account creation
LAMPORTS_PER_SIGNATURE: Final[int] = 5000
# Maximum seed length for derived addresses
MAX_SEED_LENGTH: Final[int] = 32Compute Budget Limits
# Default compute unit limit
DEFAULT_COMPUTE_UNITS: Final[int] = 200000
# Maximum compute unit limit
MAX_COMPUTE_UNITS: Final[int] = 1400000
# Maximum compute unit price (micro-lamports)
MAX_COMPUTE_UNIT_PRICE: Final[int] = 1000000Error Handling
System program operations can fail for various reasons:
from solders.errors import InstructionError
try:
# Account creation with insufficient funds
create_ix = create_account(CreateAccountParams(
from_pubkey=payer.pubkey(),
to_pubkey=new_account.pubkey(),
lamports=10000000000, # More than payer has
space=165,
owner=ID
))
except InstructionError as e:
print(f"Account creation failed: {e}")
try:
# Transfer more than available
transfer_ix = transfer(TransferParams(
from_pubkey=payer.pubkey(),
to_pubkey=recipient.pubkey(),
lamports=999999999999 # Excessive amount
))
except InstructionError as e:
print(f"Transfer failed: {e}")