diff --git a/programs/stake/src/stake_instruction.rs b/programs/stake/src/stake_instruction.rs index d937976658..9073117b81 100644 --- a/programs/stake/src/stake_instruction.rs +++ b/programs/stake/src/stake_instruction.rs @@ -43,86 +43,75 @@ impl DecodeError for StakeError { #[derive(Serialize, Deserialize, Debug, PartialEq, Clone)] pub enum StakeInstruction { - /// `Initialize` a stake with Lockup and Authorized information + /// Initialize a stake with lockup and authorization information /// - /// Expects 2 Accounts: - /// 0 - Uninitialized StakeAccount - /// 1 - Rent sysvar + /// # Account references + /// 0. [WRITE] Uninitialized stake account + /// 1. [] Rent sysvar /// /// Authorized carries pubkeys that must sign staker transactions /// and withdrawer transactions. /// Lockup carries information about withdrawal restrictions - /// Initialize(Authorized, Lockup), /// Authorize a key to manage stake or withdrawal - /// requires Authorized::staker or Authorized::withdrawer - /// signature, depending on which key's being updated /// - /// Expects 2 Accounts: - /// 0 - StakeAccount to be updated with the Pubkey for - /// authorization - /// 1 - (reserved for future use) Clock sysvar Account that carries - /// clock bank epoch + /// # Account references + /// 0. [WRITE] Stake account to be updated + /// 1. [] (reserved for future use) Clock sysvar + /// 2. [SIGNER] The stake or withdraw authority Authorize(Pubkey, StakeAuthorize), - /// `Delegate` a stake to a particular vote account - /// requires Authorized::staker signature + /// Delegate a stake to a particular vote account /// - /// Expects 4 Accounts: - /// 0 - Initialized StakeAccount to be delegated - /// 1 - VoteAccount to which this Stake will be delegated - /// 2 - Clock sysvar Account that carries clock bank epoch - /// 3 - Config Account that carries stake config + /// # Account references + /// 0. [WRITE] Initialized stake account to be delegated + /// 1. [] Vote account to which this stake will be delegated + /// 2. [] Clock sysvar + /// 3. [] Stake history sysvar that carries stake warmup/cooldown history + /// 4. [] Address of config account that carries stake config + /// 5. [SIGNER] Stake authority /// /// The entire balance of the staking account is staked. DelegateStake /// can be called multiple times, but re-delegation is delayed /// by one epoch - /// DelegateStake, - /// Split u64 tokens and stake off a stake account into another stake - /// account. Requires Authorized::staker signature and the - /// signature of the split-off stake address. - /// - /// The source stake must be either Initialized or a Stake. - /// - /// Expects 2 Accounts: - /// 0 - StakeAccount to be split - /// 1 - Uninitialized StakeAcount that will take the split-off amount + /// Split u64 tokens and stake off a stake account into another stake account. /// + /// # Account references + /// 0. [WRITE] Stake account to be split; must be in the Initialized or Stake state + /// 1. [WRITE] Uninitialized stake account that will take the split-off amount + /// 2. [SIGNER] Stake authority Split(u64), /// Withdraw unstaked lamports from the stake account - /// requires Authorized::withdrawer signature. If withdrawal - /// is before lockup has expired, also requires signature - /// of the lockup custodian. /// - /// Expects 4 Accounts: - /// 0 - StakeAccount from which to withdraw - /// 1 - Account to which the lamports will be transferred - /// 2 - Syscall Account that carries epoch - /// 3 - StakeHistory sysvar that carries stake warmup/cooldown history + /// # Account references + /// 0. [WRITE] Stake account from which to withdraw + /// 1. [WRITE] Recipient account + /// 2. [] Clock sysvar + /// 3. [] Stake history sysvar that carries stake warmup/cooldown history + /// 4. [SIGNER] Withdraw authority + /// 5. Optional: [SIGNER] Lockup authority, if before lockup expiration /// - /// The u64 is the portion of the Stake account balance to be withdrawn, - /// must be <= StakeAccount.lamports - staked lamports. + /// The u64 is the portion of the stake account balance to be withdrawn, + /// must be `<= StakeAccount.lamports - staked_lamports`. Withdraw(u64), /// Deactivates the stake in the account - /// requires Authorized::staker signature - /// - /// Expects 2 Accounts: - /// 0 - Delegate StakeAccount - /// 1 - Syscall Account that carries epoch /// + /// # Account references + /// 0. [WRITE] Delegated stake account + /// 1. [] Clock sysvar + /// 2. [SIGNER] Stake authority Deactivate, /// Set stake lockup - /// requires Lockup::custodian signature - /// - /// Expects 1 Account: - /// 0 - initialized StakeAccount /// + /// # Account references + /// 0. [WRITE] Initialized stake account + /// 1. [SIGNER] Lockup authority SetLockup(LockupArgs), } diff --git a/programs/vote/src/vote_instruction.rs b/programs/vote/src/vote_instruction.rs index e2012a87d4..18db807484 100644 --- a/programs/vote/src/vote_instruction.rs +++ b/programs/vote/src/vote_instruction.rs @@ -51,59 +51,55 @@ impl DecodeError for VoteError { #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)] pub enum VoteInstruction { - /// Initialize the VoteState for this `vote account` - /// requires VoteInit::node_pubkey signature - /// - /// Expects 3 Accounts: - /// 0 - Uninitialized Vote account - /// 1 - Rent sysvar - /// 2 - Clock sysvar + /// Initialize a vote account /// + /// # Account references + /// 0. [WRITE] Uninitialized vote account + /// 1. [] Rent sysvar + /// 2. [] Clock sysvar + /// 3. [SIGNER] New validator identity (node_pubkey) InitializeAccount(VoteInit), /// Authorize a key to send votes or issue a withdrawal - /// requires authorized voter or authorized withdrawer signature, - /// depending on which key's being updated - /// - /// Expects 2 Accounts: - /// 0 - Vote account to be updated with the Pubkey for authorization - /// 1 - Clock sysvar /// + /// # Account references + /// 0. [WRITE] Vote account to be updated with the Pubkey for authorization + /// 1. [] Clock sysvar + /// 2. [SIGNER] Vote or withdraw authority Authorize(Pubkey, VoteAuthorize), /// A Vote instruction with recent votes - /// requires authorized voter signature /// - /// Expects 3 Accounts: - /// 0 - Vote account to vote with - /// 1 - Slot hashes sysvar - /// 2 - Clock sysvar + /// # Account references + /// 0. [WRITE] Vote account to vote with + /// 1. [] Slot hashes sysvar + /// 2. [] Clock sysvar + /// 3. [SIGNER] Vote authority Vote(Vote), /// Withdraw some amount of funds - /// requires authorized withdrawer signature /// - /// Expects 2 Accounts: - /// 0 - Vote account to withdraw from - /// 1 - Destination account for the withdrawal + /// # Account references + /// 0. [WRITE] Vote account to withdraw from + /// 1. [WRITE] Recipient account + /// 2. [SIGNER] Withdraw authority Withdraw(u64), /// Update the vote account's validator identity (node_pubkey) - /// requires authorized withdrawer and new validator identity signature - /// - /// Expects 2 Accounts: - /// 0 - Vote account to be updated with the Pubkey for authorization - /// 1 - New validator identity (node_pubkey) /// + /// # Account references + /// 0. [WRITE] Vote account to be updated with the given authority public key + /// 1. [SIGNER] New validator identity (node_pubkey) + /// 2. [SIGNER] Withdraw authority UpdateValidatorIdentity, /// A Vote instruction with recent votes - /// requires authorized voter signature /// - /// Expects 3 Accounts: - /// 0 - Vote account to vote with - /// 1 - Slot hashes sysvar - /// 2 - Clock sysvar + /// # Account references + /// 0. [WRITE] Vote account to vote with + /// 1. [] Slot hashes sysvar + /// 2. [] Clock sysvar + /// 3. [SIGNER] Vote authority VoteSwitch(Vote, Hash), } diff --git a/sdk/src/loader_instruction.rs b/sdk/src/loader_instruction.rs index 72bcbaf38f..17a0c207a2 100644 --- a/sdk/src/loader_instruction.rs +++ b/sdk/src/loader_instruction.rs @@ -8,23 +8,25 @@ use crate::{ pub enum LoaderInstruction { /// Write program data into an account /// - /// * key[0] - the account to write into. - /// - /// The transaction must be signed by key[0] + /// # Account references + /// 0. [WRITE, SIGNER] Account to write to Write { + /// Offset at which to write the given bytes offset: u32, + + /// Serialized program data #[serde(with = "serde_bytes")] bytes: Vec, }, - /// Finalize an account loaded with program data for execution. + /// Finalize an account loaded with program data for execution + /// /// The exact preparation steps is loader specific but on success the loader must set the executable - /// bit of the Account + /// bit of the account. /// - /// * key[0] - the account to prepare for execution - /// * key[1] - rent sysvar account - /// - /// The transaction must be signed by key[0] + /// # Account references + /// 0. [WRITE, SIGNER] The account to prepare for execution + /// 1. [] Rent sysvar Finalize, } diff --git a/sdk/src/system_instruction.rs b/sdk/src/system_instruction.rs index 6b5542e6e2..ea5cfa0193 100644 --- a/sdk/src/system_instruction.rs +++ b/sdk/src/system_instruction.rs @@ -55,66 +55,87 @@ pub const MAX_PERMITTED_DATA_LENGTH: u64 = 10 * 1024 * 1024; #[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] pub enum SystemInstruction { /// Create a new account - /// * Transaction::keys[0] - source - /// * Transaction::keys[1] - new account key - /// * lamports - number of lamports to transfer to the new account - /// * space - number of bytes of memory to allocate - /// * owner - the program that will own the new account + /// + /// # Account references + /// 0. [WRITE, SIGNER] Funding account + /// 1. [WRITE, SIGNER] New account CreateAccount { + /// Number of lamports to transfer to the new account lamports: u64, + + /// Number of bytes of memory to allocate space: u64, + + /// Address of program that will own the new account owner: Pubkey, }, + /// Assign account to a program - /// * Transaction::keys[0] - account to assign - Assign { owner: Pubkey }, - /// Transfer lamports - /// * Transaction::keys[0] - source - /// * Transaction::keys[1] - destination - Transfer { lamports: u64 }, - /// Create a new account at an address derived from - /// a base pubkey and a seed - /// * Transaction::keys[0] - source - /// * Transaction::keys[1] - new account key - /// * seed - string of ascii chars, no longer than pubkey::MAX_SEED_LEN - /// * lamports - number of lamports to transfer to the new account - /// * space - number of bytes of memory to allocate - /// * owner - the program that will own the new account - CreateAccountWithSeed { - base: Pubkey, - seed: String, - lamports: u64, - space: u64, + /// + /// # Account references + /// 0. [WRITE, SIGNER] Assigned account public key + Assign { + /// Owner program account owner: Pubkey, }, - /// `AdvanceNonceAccount` consumes a stored nonce, replacing it with a successor + + /// Transfer lamports /// - /// Expects 2 Accounts: - /// 0 - A NonceAccount - /// 1 - RecentBlockhashes sysvar + /// # Account references + /// 0. [WRITE, SIGNER] Funding account + /// 1. [WRITE] Recipient account + Transfer { lamports: u64 }, + + /// Create a new account at an address derived from a base pubkey and a seed /// - /// The current authority must sign a transaction executing this instrucion + /// # Account references + /// 0. [WRITE, SIGNER] Funding account + /// 1. [WRITE] Created account + /// 2. [SIGNER] Base account + CreateAccountWithSeed { + /// Base public key + base: Pubkey, + + /// String of ASCII chars, no longer than `Pubkey::MAX_SEED_LEN` + seed: String, + + /// Number of lamports to transfer to the new account + lamports: u64, + + /// Number of bytes of memory to allocate + space: u64, + + /// Owner program account address + owner: Pubkey, + }, + + /// Consumes a stored nonce, replacing it with a successor + /// + /// # Account references + /// 0. [WRITE, SIGNER] Nonce account + /// 1. [] RecentBlockhashes sysvar + /// 2. [SIGNER] Nonce authority AdvanceNonceAccount, - /// `WithdrawNonceAccount` transfers funds out of the nonce account + + /// Withdraw funds from a nonce account /// - /// Expects 4 Accounts: - /// 0 - A NonceAccount - /// 1 - A system account to which the lamports will be transferred - /// 2 - RecentBlockhashes sysvar - /// 3 - Rent sysvar + /// # Account references + /// 0. [WRITE] Nonce account + /// 1. [WRITE] Recipient account + /// 2. [] RecentBlockhashes sysvar + /// 3. [] Rent sysvar + /// 4. [SIGNER] Nonce authority /// /// The `u64` parameter is the lamports to withdraw, which must leave the /// account balance above the rent exempt reserve or at zero. - /// - /// The current authority must sign a transaction executing this instruction WithdrawNonceAccount(u64), - /// `InitializeNonceAccount` drives state of Uninitalized NonceAccount to Initialized, - /// setting the nonce value. + + /// Drive state of Uninitalized nonce account to Initialized, setting the nonce value /// - /// Expects 3 Accounts: - /// 0 - A NonceAccount in the Uninitialized state - /// 1 - RecentBlockHashes sysvar - /// 2 - Rent sysvar + /// # Account references + /// 0. [WRITE] Nonce account + /// 1. [] RecentBlockhashes sysvar + /// 2. [] Rent sysvar /// /// The `Pubkey` parameter specifies the entity authorized to execute nonce /// instruction on the account @@ -122,39 +143,57 @@ pub enum SystemInstruction { /// No signatures are required to execute this instruction, enabling derived /// nonce account addresses InitializeNonceAccount(Pubkey), - /// `AuthorizeNonceAccount` changes the entity authorized to execute nonce instructions - /// on the account + + /// Change the entity authorized to execute nonce instructions on the account /// - /// Expects 1 Account: - /// 0 - A NonceAccount + /// # Account references + /// 0. [WRITE, SIGNER] Nonce account /// /// The `Pubkey` parameter identifies the entity to authorize - /// - /// The current authority must sign a transaction executing this instruction AuthorizeNonceAccount(Pubkey), + /// Allocate space in a (possibly new) account without funding - /// * Transaction::keys[0] - new account key - /// * space - number of bytes of memory to allocate - Allocate { space: u64 }, - /// Allocate space for and assign an account at an address - /// derived from a base pubkey and a seed - /// * Transaction::keys[0] - new account key - /// * seed - string of ascii chars, no longer than pubkey::MAX_SEED_LEN - /// * space - number of bytes of memory to allocate - /// * owner - the program that will own the new account - AllocateWithSeed { - base: Pubkey, - seed: String, + /// + /// # Account references + /// 0. [WRITE, SIGNER] New account + Allocate { + /// Number of bytes of memory to allocate space: u64, + }, + + /// Allocate space for and assign an account at an address + /// derived from a base public key and a seed + /// + /// # Account references + /// 0. [WRITE] Allocated account + /// 1. [SIGNER] Base account + AllocateWithSeed { + /// Base public key + base: Pubkey, + + /// String of ASCII chars, no longer than `pubkey::MAX_SEED_LEN` + seed: String, + + /// Number of bytes of memory to allocate + space: u64, + + /// Owner program account owner: Pubkey, }, + /// Assign account to a program based on a seed - /// * Transaction::keys[0] - account to assign - /// * seed - string of ascii chars, no longer than pubkey::MAX_SEED_LEN - /// * owner - the program that will own the new account + /// + /// # Account references + /// 0. [WRITE] Assigned account + /// 1. [SIGNER] Base account AssignWithSeed { + /// Base public key base: Pubkey, + + /// String of ASCII chars, no longer than `pubkey::MAX_SEED_LEN` seed: String, + + /// Owner program account owner: Pubkey, }, }