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)]
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),
}

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)]
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),
}

20
sdk/src/loader_instruction.rs
View File

@ -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<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
/// 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,
}

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)]
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,
},
}