13. Protocol-owned programs and sysvars

13.1 Identity and deployment model

Protocol-owned behavior is selected by public key plus bank state, not by a human-readable program name. A program can be a native builtin, a Core-BPF deployment under an SBF loader, a stateless precompile, or feature-disabled. Migration can retain a public program identifier while changing its execution owner and code source.

[SOL-PRG-0001] Protocol-owned dispatch MUST use the exact program address and form listed in Section 13.2 for epoch E.

[SOL-PRG-0002] For every Core-BPF protocol program, replay MUST resolve and authenticate from the bank the loader, the ProgramData account when applicable, the executable bytes, the deployment slot, and the upgrade-authority state, then execute those bytes under Chapter 12.

[SOL-PRG-0003] A validator MUST select dispatch from the program account and active feature state visible in the bank and MUST NOT substitute a builtin just because the public key is historically associated with one.

[SOL-PRG-0004] A builtin-to-Core-BPF migration MUST update the program and ProgramData accounts, capitalization, program resolution, and execution-cost classification exactly at the activating bank. The migrated bytes MUST have deployment slot d and effective slot d+1, where d is the activating bank’s slot.

13.2 Known protocol identifiers

Normative table.

[SOL-PRG-0005] A program identifier absent from the epoch-E catalog MUST NOT acquire protocol-owned dispatch.

[SOL-PRG-0006] A native builtin MUST follow its normative native transition, while a Core-BPF program MUST follow the authenticated deployed bytes selected by ResolveProgram. A public identifier, historical native behavior, or prose summary MUST NOT override the bank-selected form.

13.3 Protocol program state

System, vote, stake, config, address-lookup-table, loader, feature, and proof-program accounts contain consensus state. Their state tags, byte layouts, authorities, signer/writable requirements, arithmetic, and error codes form part of consensus even when the program is implemented natively.

[SOL-PRG-0007] An active protocol program MUST decode instruction and account-state bytes with the exact bank-selected format and MUST deterministically reject unknown discriminants, truncation, invalid lengths, invalid authorities, missing signatures, and prohibited writable or owner combinations.

[SOL-PRG-0008] A protocol program MUST apply checked or saturating arithmetic exactly where its specified transition requires it and MUST return the specified error without committing partial program changes when a precondition fails.

[SOL-PRG-0009] Address-lookup-table resolution MUST use only lookup-table state produced by the active address-lookup-table program and visible under the bank-slot and SlotHashes rules in Chapter 7.

[SOL-PRG-0010] System durable-nonce initialization, authorization, advancement, withdrawal, and deallocation MUST preserve the nonce state and replay conditions used by Chapters 7 and 11.

13.3.1 System program

System-program instruction data is a Section 5.3 fixed-integer enum. It begins with the u32 little-endian discriminant below. A string is length:u64 || length UTF-8 bytes, has no terminator, and is limited to 32 bytes for a derivation seed. Public keys are 32 raw bytes. The decoder permits trailing instruction-data bytes after a complete variant.

Normative table.

For a seed-derived address, compute SHA256(base[32] || seed_bytes || owner[32]); the result must equal the address being allocated, assigned, created, or debited. Allocation requires a system-owned account with empty data and space <= 10,485,760; assignment requires empty data; a lamport transfer may debit only a system-owned account with empty data. CreateAccount additionally requires the destination balance to be zero. CreateAccountAllowPrefund omits only that zero-balance condition; all allocation, signer, derivation, funding, and assignment checks remain.

Normative table. System Program custom-error domain.

Instruction decode precedes account-list lookup. Thereafter the System Program checks account count and signer privilege in listed-account order, address/seed derivation, ownership and state, data length/allocation, then balances. A named custom error takes precedence at its predicate; otherwise the exact standard InstructionError in Section 12.7 applies.

[SOL-PRG-0011] The System program MUST decode the table above, enforce the listed signer and writable privileges, use checked lamport arithmetic, and perform allocation, assignment, transfer, and durable-nonce transitions atomically. An invalid derivation, owner, data length, balance, signature, or account list MUST fail the instruction without a partial System-program transition.

13.3.2 Upgradeable BPF loader

Upgradeable-loader state begins with a u32 little-endian discriminant. The fixed metadata offsets, rather than the serialized length of an absent option, locate following program bytes.

Normative table.

Management instruction data is another Section 5.3 fixed-integer enum:

Normative table.

Normative table. Upgradeable-loader ordered accounts and transitions.

ProgramData is derived from the Program address by the Section 5.5 PDA algorithm with the Program address as the sole seed and the Upgradeable BPF Loader as program ID. Write ranges must remain within the Buffer data after byte 37. Deploy and upgrade validate the resulting ELF under Section 12.8.5, copy program bytes into ProgramData after byte 45, set the deployment slot, and make the Program account executable. An upgrade or authority change requires the current authority; SetAuthorityChecked also requires the new authority. ExtendProgram adds at least 10,240 bytes unless fewer than 10,240 bytes remain before the 10-MiB account limit, and cannot exceed that limit.

[SOL-PRG-0012] The Upgradeable BPF Loader MUST preserve the state tags, metadata offsets, PDA relationship, authority checks, minimum extension, deployment slot, executable transition, and bank-visible program bytes above. A successful deploy or upgrade at slot d MUST set effective slot d+1; the new bytes are unavailable for invocation in d and become resolvable in the child slot.

13.3.3 Vote program

Vote-account data is a Section 5.3 fixed-integer enum followed by unused account capacity. Its first four bytes are a little-endian state discriminant: 0 Uninitialized, 1 V1_14_11, 2 V3, or 3 V4. The decoder permits unused trailing bytes. Serialization overwrites the encoded prefix but preserves any remaining account bytes, which therefore remain part of the account hash.

The component encodings used below are:

Normative table.

Legacy states remain decodable because an untouched account can retain them. Their exact field sequences after the four-byte state discriminant are:

Normative table.

Every successful epoch-E Vote-program mutation stores V4 and grows a shorter legacy account to 3,762 bytes only if its balance is rent-exempt at that length. The V4 prefix after discriminant 3 is:

Normative table.

Vote instruction data also begins with a u32 little-endian discriminant and permits trailing bytes. Only the following forms execute in epoch E; any other Vote-instruction discriminant is invalid instruction data.

Normative table.

Authority-kind is LE(0,4) for a voter, LE(1,4) for a withdrawer, or LE(2,4) || bls_key[48] || proof_of_possession[96] for a BLS voter. A seed string uses length:u64 || UTF-8 bytes and is at most 32 bytes.

Normative table.

Offsets are accumulated with checked u64 addition and must produce strictly increasing vote slots. The voted-bank hash must equal SlotHashes for the last vote, and the block identifier field is the Chapter 14 terminal FEC root for the same slot. Vote lockouts, roots, authorization, timestamp monotonicity, credit accrual, withdrawals, collector fields, and commission updates are applied to the V4 fields as specified by Chapters 15 and 16.

[SOL-PRG-0013] The Vote program MUST accept only the epoch-E instruction forms above, decode legacy account states exactly, store every successful mutation as V4, and enforce the named authority, tower, SlotHashes, timestamp, rent, credit, withdrawal, and commission rules without partially updating the vote account on failure.

Normative table. Vote Program custom-error domain.

Vote instruction decode and account-count/signature checks precede these semantic errors. For a vote/tower update, test empty/ordered/bounded tower shape, old-slot filtering, SlotHashes membership and bank hash, proposed-root ancestry, lockout consistency, then timestamp monotonicity; the first failing predicate supplies the value above. Authority/owner/account-data failures use the exact standard InstructionError from Section 12.7.

13.3.4 Stake Program v5

A Stake account is exactly 200 bytes, owned by the Stake Program, and decoded with FIXINT-LE. Bytes not occupied by the selected state are retained as zero/unused capacity and remain committed by the account hash.

Normative table. Stake v5 state byte layout.

Stake instructions use FIXINT-LE: a u32 discriminant followed by the payload below. Option<T> is tag byte 0, or 1||T; StakeAuthorize is u32 0 staker or 1 withdrawer. LockupArgs is optional i64, optional u64, optional key; the checked form omits the key and takes a signed new custodian account. A seed string is u64 length || UTF-8 and at most 32 bytes.

Normative table. Stake v5 instructions and ordered accounts.

Effective, activating, and deactivating amounts are computed from the Delegation fields and StakeHistory by Section 16.4 before any withdraw, split, merge, delinquent deactivation, move, or reward operation. A lockup is in force when lockup.unix_timestamp > Clock.unix_timestamp or lockup.epoch > Clock.epoch, unless its custodian signed. Stake mutations other than reward redemption fail with Custom(16) while EpochRewards is active.

Normative table. Stake custom-error domain.

All other failures use the exact standard InstructionError named by the failed predicate: owner, state bytes, account count, signature, authority, funds, rent, or checked arithmetic are tested in that order after instruction decode. Stake reward redemption uses the vote-credit and commission algorithm in Section 16.6. An ordinary zero-lamport reward does not advance credits_observed; only the activation-epoch and credits-rewind forced updates named there do so without a payout.

13.3.5 Config Program

A Config account is owned by the Config Program. Its data begins with a canonical ShortU16 key count N, then N records of public key [32] and Boolean signer byte, followed by opaque configuration bytes. The entire instruction data uses the same layout and replaces the account prefix; there is no instruction discriminant.

Normative table. Config transition and exact precedence.

The fixed Core-BPF behavior consumes SBF compute under Chapter 12; the former native 450-CU dispatch constant is not applied. This transition is the only Config instruction and provides no interpretation of the opaque suffix.

13.3.6 Feature Program

The single authoritative Feature-account layout and decoder are in Section 17.1. A Feature-Program-created account has the nine-byte canonical length; the bank feature scan applies Section 17.1’s explicitly broader accepted domain for already-present account state.

Feature activation is not a Feature-Program instruction. It is an atomic transaction sequence that System-transfers the rent-exempt balance, allocates nine bytes, and assigns the signed feature address to the Feature Program. At the next new-bank feature scan, a pending account selected for activation is written as 1||LE(current_slot,8); the behavioral side effects in Appendix C and Section 17.4 are applied in that same bank before transactions.

The sole Feature instruction is byte 00, RevokePendingActivation, with feature account 0 W,S, incinerator account 1 W, and System Program account 2 readonly. Require Feature ownership and a decodable pending state; an active state returns Custom(0) (FeatureAlreadyActivated). On success transfer all lamports to the incinerator, resize the feature account to zero, and assign it to the System Program. Revocation after activation cannot undo a rule. A Core-BPF migration changes only execution form; it neither activates nor revokes any Feature account.

13.3.7 Address Lookup Table Program

Lookup-table instruction data is FIXINT-LE: u32 discriminants 0 Create (recent_slot:u64,bump:u8), 1 Freeze, 2 Extend (count:u64 then that many 32-byte addresses), 3 Deactivate, and 4 Close. State is u32 tag 0 Uninitialized or tag 1 LookupTable followed by the metadata below.

Normative table. Lookup-table account bytes.

Normative table. Lookup-table lifecycle.

An active/deactivating table remains usable while its deactivation slot is the current slot or occurs in SlotHashes. It becomes deactivated when that slot is absent. For lookup in current slot s, if s == last_extended_slot, only indices below last_extended_slot_start_index are visible; otherwise all N are visible. Invalid state/owner/index map to the four exact transaction errors in Section 7.8 during message loading. Program-instruction failures use InvalidAccountOwner, MissingRequiredSignature, Immutable, IncorrectAuthority, AccountAlreadyInitialized, InvalidArgument, or InvalidInstructionData in the predicate order shown above.

13.3.8 Native Loader and BPF loader execution

The Native Loader address is a reserved dispatch owner, not a general-purpose instruction program. Directly invoking it returns UnsupportedProgramId. A Native-Loader-owned program account dispatches only when its key is in the bank’s builtin registry; an unregistered key produces TransactionError::InvalidProgramForExecution during loading. The program’s own instruction accounts exclude the loader-owner account.

The deprecated and current BPF loaders may execute already-deployed program accounts using ABI v0 and v1 respectively, but direct management instructions return UnsupportedProgramId after the fixed loader charge in Section 12.8.8. The Upgradeable Loader alone accepts the management state machine in Section 13.3.2. CPI directly to any loader, and CPI to an Upgradeable-Loader Upgrade, SetAuthority, SetAuthorityChecked, or Close instruction, returns UnsupportedProgramId before the nested invocation begins.

13.3.9 ZK ElGamal Proof Program

Instruction byte zero is the u8 discriminant below. For a verify instruction, the remaining bytes are either the exact proof-data POD value or exactly four bytes proof_offset:u32; the latter reads that POD at the offset in readonly account 0. A verification with no context needs no more accounts. To store the verified statement, supply a writable context account followed by the context authority; when proof bytes came from account 0 those are accounts 1 and 2.

Normative table. ZK ElGamal proof instructions and complete POD envelopes.

Every inline proof envelope is exactly discriminant:u8 || context_POD || proof_POD, with no padding or trailing bytes. The five-byte account form is exactly discriminant:u8 || proof_offset:u32_le; its readonly proof account must contain context_POD || proof_POD at [proof_offset, proof_offset + context_bytes + proof_bytes). A stored context state is exactly authority[32] || proof_type:u8 || context_POD, which yields the lengths in the table.

All keys, ciphertext components, commitments, and proof points are canonical compressed Ristretto encodings; each proof scalar is canonical modulo the Ristretto scalar order. An ElGamal ciphertext is commitment[32] || decryption_handle[32]; a two- or three-handle grouped ciphertext is one commitment followed by two or three 32-byte handles. The proof relations are, respectively: encryption of zero; equality of the two ciphertext plaintexts; equality of a ciphertext plaintext and a Pedersen commitment opening; knowledge of the secret key corresponding to the supplied public key; either percentage == max_value or delta == claimed; membership of every committed value in its declared unsigned bit range; and validity of every grouped decryption handle for one shared commitment. Batched grouped proofs check both the low and high grouped ciphertext under the same supplied keys.

For a batched range context, selected commitments are the prefix before the first all-zero 32-byte commitment, so there are at most eight. The equally long prefix of bit_lengths supplies the selected unsigned u8 widths; its sum must be exactly 64, 128, or 256 for discriminants 6, 7, or 8. The remaining commitment and length slots are not selected, but their raw bytes remain bound into the transcript and are not required to be zero. Verification uses the named proof’s fixed Fiat–Shamir transcript and rejects a noncanonical scalar, invalid compressed point, identity commitment where prohibited, malformed range vector, or false relation. Any POD decode or verification failure is InvalidInstructionData after the row’s full CU is charged.

A context account is Proof-Program-owned and exactly authority[32] || proof_type:u8 || context_POD. It must contain proof type 0 Uninitialized and have exactly the resulting length; otherwise return AccountAlreadyInitialized or InvalidAccountData. Success replaces the entire bytes. Close takes context W, distinct destination W, authority S; it validates owner, initialized type, and exact authority in that order, transfers all lamports, truncates data, and assigns System ownership. Failures are respectively MissingRequiredSignature, InvalidInstructionData, InvalidAccountOwner, UninitializedAccount, or InvalidAccountOwner for an authority mismatch.

13.3.10 Core-BPF migration and upgrade side effects

At an activating bank, a protocol-owned migration first authenticates the source Upgradeable-Loader Buffer state, its configured address and authority, and any configured verified-build hash; authenticates the target’s expected builtin/stateless/Core-BPF form; derives the target ProgramData PDA; constructs the Program and ProgramData states from Section 13.3.2; and validates/deploys the source ELF under the bank’s Chapter 12 environment. No bank account is changed if any check fails.

On success it replaces the target Program/ProgramData accounts, logically deletes the source buffer by setting its lamports to zero, removes any native builtin registration, and adjusts capitalization by the following checked expression:

Normative algorithm.

new_program_lamports + new_programdata_lamports
    - old_target_lamports - old_programdata_lamports - buffer_lamports

A Core-BPF upgrade retains the Program account and authority, replaces only ProgramData, clears the buffer, updates the deployment slot, and adjusts the same capitalization components. For migration or upgrade slot d, the new bytes have effective slot d+1; ResolveProgram does not dispatch the old or new form during d. These are bank-creation transitions, not transaction instructions, so a configured authentication/ELF/hash failure is bank-fatal rather than a transaction error.

For a Core-BPF row, execution follows Chapter 12 using deployed account bytes in the bank. The public program identifier and migration feature do not substitute for the Program/ProgramData relationship or executable bytes.

13.4 Sysvar account identities

Sysvar accounts use owner Sysvar1111111111111111111111111111111111111 unless a specific protocol exception is specified. Known addresses are:

Normative table.

Sysvar account data uses the Chapter 5 fixed-width and sequence rules. There is no host-structure padding. The exact data grammars are:

Normative table.

SlotHistory bit i is the least-significant-bit-first bit (i mod 64) in block floor(i/64). A slot s in [next_slot.saturating_sub(1048576), next_slot) is present exactly when bit s mod 1048576 is set; a slot at or above next_slot is future and an older slot is too old. Mainnet EpochSchedule bytes are (432000, 432000, false, 0, 0). Mainnet Rent bytes are LE(5080,8) || 00 00 00 00 00 00 f0 3f || 32; the final byte is decimal 50 (0x32) and the middle bytes are the little-endian IEEE-754 representation of 1.0 retained for compatibility.

[SOL-PRG-0014] A persistent sysvar account MUST have its canonical address, Sysvar owner, a false executable flag, a rent-exempt balance, and the exact serialized data for the child bank.

[SOL-PRG-0015] A sysvar update MUST replace the account data using the canonical serializer and MUST adjust capitalization for any protocol-funded rent-exempt balance change.

[SOL-PRG-0016] The sysvar cache supplied to builtins, SBF syscalls, and loaders MUST reflect the same values as the child bank’s canonical sysvar state at the invocation point.

13.5 Sysvar update phases

[SOL-PRG-0017] Before transaction execution, SlotHashes MUST incorporate the parent slot and parent bank hash according to its bounded history rule, and Clock MUST identify the child slot and epoch with the stake-weighted timestamp result below.

[SOL-PRG-0018] StakeHistory MUST be updated exactly when the child crosses an epoch boundary, and LastRestartSlot MUST reflect the greatest qualifying hard-fork or restart slot visible to the child.

[SOL-PRG-0019] EpochRewards MUST be initialized and updated in lockstep with the partitioned epoch-reward state transition, including its active/inactive status and distributed amount.

[SOL-PRG-0020] At the slot boundary, RecentBlockhashes MUST reflect the active recent-blockhash queue after terminal hash registration; during freeze, SlotHistory MUST record the child slot before bank hashing.

The bounded histories, timestamp estimator, reward fields, and deprecated-sysvar availability are selected by the bank feature state and the relevant protocol-program transition.

For child slot s, retain each vote account’s most recent timestamp only when its reported slot r <= s and s-r <= 432000. Advance that timestamp by the PoH duration from r+1 through s, group equal advanced estimates, and sum the epoch stake delegated to each group with saturating u128 arithmetic. The estimate is the smallest timestamp whose cumulative stake in ascending timestamp order is strictly greater than half the total included stake. If no stake is included, retain the parent’s timestamp. Relative to the epoch-start PoH estimate, clamp an estimate that is too far behind to 25% behind and one that is too far ahead to 150% ahead; finally, do not permit the child Unix timestamp to precede its parent’s. On an epoch boundary, the resulting value also becomes epoch_start_timestamp.

13.6 Instructions sysvar

The instructions sysvar is transaction-scoped. It contains a serialization of the top-level message instructions and a mutable current top-level instruction index used during execution; it is not loaded from the parent account database.

Normative table.

Every offset points at the corresponding record’s account count. Records are stored in top-level message order and account metas retain instruction order. All counts, offsets, and total size must fit u16.

[SOL-PRG-0021] When the instructions-sysvar key is present in a transaction, account loading MUST synthesize its data from that transaction’s complete top-level instruction list and MUST NOT use any persistent account value at the same address.

[SOL-PRG-0022] Immediately before each top-level instruction is invoked, the runtime MUST set the synthesized instructions sysvar’s current index to that instruction’s zero-based message index.

[SOL-PRG-0023] CPI MUST NOT append callee instructions to the synthesized top-level instruction list or change the current index away from the enclosing top-level instruction.

13.7 Reserved protocol accounts and incineration

The epoch-E set has no pending or conditionally writable entries. Every row is an always-readonly base entry; no feature adds or removes it in E.

Normative table. Complete reserved-account set.

[SOL-PRG-0024] Immediately after address resolution, sanitation MUST demote every row above to readonly. Demotion changes only the effective writable bitmap: the signed message bytes and its three header counts remain unchanged. A reserved address requested writable still contributes one requested-writable-account cost in Section 10.4.1, but it is not included in effective-writable account cost attribution and does not change fee calculation.

[SOL-PRG-0025] At freeze, a present incinerator account MUST be replaced with the default account and its lamports MUST be removed from capitalization before the accounts commitment and bank hash are finalized.

[SOL-PRG-0026] Lamports sent to the incinerator after its processing point MUST NOT be retroactively burned in an earlier bank.

[SOL-PRG-0027] A transaction that attempts a state change through a demoted reserved account MUST fail at instruction validation with the applicable ReadonlyLamportChange or ReadonlyDataModified; the message is not rejected merely for having requested that reserved key writable.

[SOL-PRG-0028] A Core-BPF program MUST execute the authenticated deployed bytes selected by ResolveProgram; prose in this chapter is not authority to substitute a native implementation. The Stake, Config, Feature, and Address Lookup Table state decoders and cross-program rules in Sections 13.3.4 through 13.3.10 remain normative where the rest of the protocol consumes those accounts. Any mismatch between the prose and authenticated execution is a defect in this specification, not an alternative state transition.

13.8 Core-BPF programs

The following subsections are an index, not duplicate definitions. Each program’s single authoritative state machine is the referenced Section 13.3 subsection; Chapter 12 supplies its SBF execution semantics and the bank’s authenticated Program/ProgramData bytes supply its code.

13.8.1 Stake Program v5

The complete active instruction set, 200-byte state, transitions, and custom error domain are defined once in Section 13.3.4.

13.8.2 Config Program

The key-prefix and opaque-suffix state, sole update transition, and exact error precedence are defined once in Section 13.3.5.

13.8.3 Feature Program

Pending/active state, activation, revocation, and migration behavior are defined once in Sections 13.3.6 and 17.1–17.4.

13.8.4 Address Lookup Table Program

Instruction bytes, 56-byte metadata, address visibility, and the complete lifecycle are defined once in Sections 13.3.7 and 7.4.

13.9 Deployment dependence

Core-BPF executable bytes and upgrade-authority state are ordinary bank state. An implementation restoring or replaying a bank authenticates those accounts through the state commitment and executes the version visible at that bank, as required by SOL-PRG-0002; this document does not embed mutable deployed bytes.