blockworks-foundation
/
solana
mirror of https://github.com/blockworks-foundation/solana.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Cleanup program docs (#10283)

This commit is contained in:
Greg Fitzgerald 2020-05-29 20:29:24 -06:00 committed by GitHub
parent de5b21e444
commit 55a64712b9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 179 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
programs/stake/src/stake_instruction.rs
View File

@ -43,86 +43,75 @@ impl<E> DecodeError<E> for StakeError {
#[derive(Serialize, Deserialize, Debug, PartialEq, Clone)] #[derive(Serialize, Deserialize, Debug, PartialEq, Clone)]
pub enum StakeInstruction { pub enum StakeInstruction {
/// `Initialize` a stake with Lockup and Authorized information /// Initialize a stake with lockup and authorization information
/// ///
/// Expects 2 Accounts: /// # Account references
/// 0 - Uninitialized StakeAccount /// 0. [WRITE] Uninitialized stake account
/// 1 - Rent sysvar /// 1. [] Rent sysvar
/// ///
/// Authorized carries pubkeys that must sign staker transactions /// Authorized carries pubkeys that must sign staker transactions
/// and withdrawer transactions. /// and withdrawer transactions.
/// Lockup carries information about withdrawal restrictions /// Lockup carries information about withdrawal restrictions
///
Initialize(Authorized, Lockup), Initialize(Authorized, Lockup),
/// Authorize a key to manage stake or withdrawal /// 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: /// # Account references
/// 0 - StakeAccount to be updated with the Pubkey for /// 0. [WRITE] Stake account to be updated
/// authorization /// 1. [] (reserved for future use) Clock sysvar
/// 1 - (reserved for future use) Clock sysvar Account that carries /// 2. [SIGNER] The stake or withdraw authority
/// clock bank epoch
Authorize(Pubkey, StakeAuthorize), Authorize(Pubkey, StakeAuthorize),
/// `Delegate` a stake to a particular vote account /// Delegate a stake to a particular vote account
/// requires Authorized::staker signature
/// ///
/// Expects 4 Accounts: /// # Account references
/// 0 - Initialized StakeAccount to be delegated /// 0. [WRITE] Initialized stake account to be delegated
/// 1 - VoteAccount to which this Stake will be delegated /// 1. [] Vote account to which this stake will be delegated
/// 2 - Clock sysvar Account that carries clock bank epoch /// 2. [] Clock sysvar
/// 3 - Config Account that carries stake config /// 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 /// The entire balance of the staking account is staked. DelegateStake
/// can be called multiple times, but re-delegation is delayed /// can be called multiple times, but re-delegation is delayed
/// by one epoch /// by one epoch
///
DelegateStake, DelegateStake,
/// Split u64 tokens and stake off a stake account into another stake /// Split u64 tokens and stake off a stake account into another stake account.
/// 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
/// ///
/// # 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), Split(u64),
/// Withdraw unstaked lamports from the stake account /// 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: /// # Account references
/// 0 - StakeAccount from which to withdraw /// 0. [WRITE] Stake account from which to withdraw
/// 1 - Account to which the lamports will be transferred /// 1. [WRITE] Recipient account
/// 2 - Syscall Account that carries epoch /// 2. [] Clock sysvar
/// 3 - StakeHistory sysvar that carries stake warmup/cooldown history /// 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, /// The u64 is the portion of the stake account balance to be withdrawn,
/// must be <= StakeAccount.lamports - staked lamports. /// must be `<= StakeAccount.lamports - staked_lamports`.
Withdraw(u64), Withdraw(u64),
/// Deactivates the stake in the account /// 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, Deactivate,
/// Set stake lockup /// 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), SetLockup(LockupArgs),
} }

60
programs/vote/src/vote_instruction.rs
View File

@ -51,59 +51,55 @@ impl<E> DecodeError<E> for VoteError {
#[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)] #[derive(Serialize, Deserialize, Debug, PartialEq, Eq, Clone)]
pub enum VoteInstruction { pub enum VoteInstruction {
/// Initialize the VoteState for this `vote account` /// Initialize a vote account
/// requires VoteInit::node_pubkey signature
///
/// Expects 3 Accounts:
/// 0 - Uninitialized Vote account
/// 1 - Rent sysvar
/// 2 - Clock sysvar
/// ///
/// # Account references
/// 0. [WRITE] Uninitialized vote account
/// 1. [] Rent sysvar
/// 2. [] Clock sysvar
/// 3. [SIGNER] New validator identity (node_pubkey)
InitializeAccount(VoteInit), InitializeAccount(VoteInit),
/// Authorize a key to send votes or issue a withdrawal /// 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), Authorize(Pubkey, VoteAuthorize),
/// A Vote instruction with recent votes /// A Vote instruction with recent votes
/// requires authorized voter signature
/// ///
/// Expects 3 Accounts: /// # Account references
/// 0 - Vote account to vote with /// 0. [WRITE] Vote account to vote with
/// 1 - Slot hashes sysvar /// 1. [] Slot hashes sysvar
/// 2 - Clock sysvar /// 2. [] Clock sysvar
/// 3. [SIGNER] Vote authority
Vote(Vote), Vote(Vote),
/// Withdraw some amount of funds /// Withdraw some amount of funds
/// requires authorized withdrawer signature
/// ///
/// Expects 2 Accounts: /// # Account references
/// 0 - Vote account to withdraw from /// 0. [WRITE] Vote account to withdraw from
/// 1 - Destination account for the withdrawal /// 1. [WRITE] Recipient account
/// 2. [SIGNER] Withdraw authority
Withdraw(u64), Withdraw(u64),
/// Update the vote account's validator identity (node_pubkey) /// 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, UpdateValidatorIdentity,
/// A Vote instruction with recent votes /// A Vote instruction with recent votes
/// requires authorized voter signature
/// ///
/// Expects 3 Accounts: /// # Account references
/// 0 - Vote account to vote with /// 0. [WRITE] Vote account to vote with
/// 1 - Slot hashes sysvar /// 1. [] Slot hashes sysvar
/// 2 - Clock sysvar /// 2. [] Clock sysvar
/// 3. [SIGNER] Vote authority
VoteSwitch(Vote, Hash), VoteSwitch(Vote, Hash),
} }

20
sdk/src/loader_instruction.rs
View File

@ -8,23 +8,25 @@ use crate::{
pub enum LoaderInstruction { pub enum LoaderInstruction {
/// Write program data into an account /// Write program data into an account
/// ///
/// * key[0] - the account to write into. /// # Account references
/// /// 0. [WRITE, SIGNER] Account to write to
/// The transaction must be signed by key[0]
Write { Write {
/// Offset at which to write the given bytes
offset: u32, offset: u32,
/// Serialized program data
#[serde(with = "serde_bytes")] #[serde(with = "serde_bytes")]
bytes: Vec<u8>, bytes: Vec<u8>,
}, },
/// 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 /// 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 /// # Account references
/// * key[1] - rent sysvar account /// 0. [WRITE, SIGNER] The account to prepare for execution
/// /// 1. [] Rent sysvar
/// The transaction must be signed by key[0]
Finalize, Finalize,
} }

167
sdk/src/system_instruction.rs
View File

@ -55,66 +55,87 @@ pub const MAX_PERMITTED_DATA_LENGTH: u64 = 10 * 1024 * 1024;
#[derive(Serialize, Deserialize, Debug, Clone, PartialEq)] #[derive(Serialize, Deserialize, Debug, Clone, PartialEq)]
pub enum SystemInstruction { pub enum SystemInstruction {
/// Create a new account /// Create a new account
/// * Transaction::keys[0] - source ///
/// * Transaction::keys[1] - new account key /// # Account references
/// * lamports - number of lamports to transfer to the new account /// 0. [WRITE, SIGNER] Funding account
/// * space - number of bytes of memory to allocate /// 1. [WRITE, SIGNER] New account
/// * owner - the program that will own the new account
CreateAccount { CreateAccount {
/// Number of lamports to transfer to the new account
lamports: u64, lamports: u64,
/// Number of bytes of memory to allocate
space: u64, space: u64,
/// Address of program that will own the new account
owner: Pubkey, owner: Pubkey,
}, },
/// Assign account to a program /// Assign account to a program
/// * Transaction::keys[0] - account to assign ///
Assign { owner: Pubkey }, /// # Account references
/// Transfer lamports /// 0. [WRITE, SIGNER] Assigned account public key
/// * Transaction::keys[0] - source Assign {
/// * Transaction::keys[1] - destination /// Owner program account
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,
owner: Pubkey, owner: Pubkey,
}, },
/// `AdvanceNonceAccount` consumes a stored nonce, replacing it with a successor
/// Transfer lamports
/// ///
/// Expects 2 Accounts: /// # Account references
/// 0 - A NonceAccount /// 0. [WRITE, SIGNER] Funding account
/// 1 - RecentBlockhashes sysvar /// 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, AdvanceNonceAccount,
/// `WithdrawNonceAccount` transfers funds out of the nonce account
/// Withdraw funds from a nonce account
/// ///
/// Expects 4 Accounts: /// # Account references
/// 0 - A NonceAccount /// 0. [WRITE] Nonce account
/// 1 - A system account to which the lamports will be transferred /// 1. [WRITE] Recipient account
/// 2 - RecentBlockhashes sysvar /// 2. [] RecentBlockhashes sysvar
/// 3 - Rent sysvar /// 3. [] Rent sysvar
/// 4. [SIGNER] Nonce authority
/// ///
/// The `u64` parameter is the lamports to withdraw, which must leave the /// The `u64` parameter is the lamports to withdraw, which must leave the
/// account balance above the rent exempt reserve or at zero. /// account balance above the rent exempt reserve or at zero.
///
/// The current authority must sign a transaction executing this instruction
WithdrawNonceAccount(u64), 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: /// # Account references
/// 0 - A NonceAccount in the Uninitialized state /// 0. [WRITE] Nonce account
/// 1 - RecentBlockHashes sysvar /// 1. [] RecentBlockhashes sysvar
/// 2 - Rent sysvar /// 2. [] Rent sysvar
/// ///
/// The `Pubkey` parameter specifies the entity authorized to execute nonce /// The `Pubkey` parameter specifies the entity authorized to execute nonce
/// instruction on the account /// instruction on the account
@ -122,39 +143,57 @@ pub enum SystemInstruction {
/// No signatures are required to execute this instruction, enabling derived /// No signatures are required to execute this instruction, enabling derived
/// nonce account addresses /// nonce account addresses
InitializeNonceAccount(Pubkey), 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: /// # Account references
/// 0 - A NonceAccount /// 0. [WRITE, SIGNER] Nonce account
/// ///
/// The `Pubkey` parameter identifies the entity to authorize /// The `Pubkey` parameter identifies the entity to authorize
///
/// The current authority must sign a transaction executing this instruction
AuthorizeNonceAccount(Pubkey), AuthorizeNonceAccount(Pubkey),
/// Allocate space in a (possibly new) account without funding /// Allocate space in a (possibly new) account without funding
/// * Transaction::keys[0] - new account key ///
/// * space - number of bytes of memory to allocate /// # Account references
Allocate { space: u64 }, /// 0. [WRITE, SIGNER] New account
/// Allocate space for and assign an account at an address Allocate {
/// derived from a base pubkey and a seed /// Number of bytes of memory to allocate
/// * 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,
space: u64, 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, owner: Pubkey,
}, },
/// Assign account to a program based on a seed /// 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 /// # Account references
/// * owner - the program that will own the new account /// 0. [WRITE] Assigned account
/// 1. [SIGNER] Base account
AssignWithSeed { AssignWithSeed {
/// Base public key
base: Pubkey, base: Pubkey,
/// String of ASCII chars, no longer than `pubkey::MAX_SEED_LEN`
seed: String, seed: String,
/// Owner program account
owner: Pubkey, owner: Pubkey,
}, },
} }