Skip to content

Commit

Permalink
Cleanup program docs (#10283) (#10360)
Browse files Browse the repository at this point in the history
automerge
  • Loading branch information
mergify[bot] authored Jun 2, 2020
1 parent ae1a0f5 commit 800b65b
Show file tree
Hide file tree
Showing 4 changed files with 169 additions and 143 deletions.
85 changes: 37 additions & 48 deletions programs/stake/src/stake_instruction.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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),
}

Expand Down
60 changes: 28 additions & 32 deletions programs/vote/src/vote_instruction.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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),
}

Expand Down
20 changes: 11 additions & 9 deletions sdk/src/loader_instruction.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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.
/// The exact preparation steps is loader specific but on success the loader must set the executable
/// bit of the Account
/// Finalize an account loaded with program data for execution
///
/// * key[0] - the account to prepare for execution
/// * key[1] - rent sysvar account
/// The exact preparation steps is loader specific but on success the loader must set the executable
/// bit of the account.
///
/// The transaction must be signed by key[0]
/// # Account references
/// 0. [WRITE, SIGNER] The account to prepare for execution
/// 1. [] Rent sysvar
Finalize,
}

Expand Down
Loading

0 comments on commit 800b65b

Please sign in to comment.