solana-docs 0.0.0

package/src/cli/conventions.md

@@ -0,0 +1,80 @@
+---
+title: Using Solana CLI
+---
+
+Before running any Solana CLI commands, let's go over some conventions that
+you will see across all commands. First, the Solana CLI is actually a collection
+of different commands for each action you might want to take. You can view the list
+of all possible commands by running:
+
+```bash
+solana --help
+```
+
+To zoom in on how to use a particular command, run:
+
+```bash
+solana <COMMAND> --help
+```
+
+where you replace the text `<COMMAND>` with the name of the command you want
+to learn more about.
+
+The command's usage message will typically contain words such as `<AMOUNT>`,
+`<ACCOUNT_ADDRESS>` or `<KEYPAIR>`. Each word is a placeholder for the _type_ of
+text you can execute the command with. For example, you can replace `<AMOUNT>`
+with a number such as `42` or `100.42`. You can replace `<ACCOUNT_ADDRESS>` with
+the base58 encoding of your public key, such as
+`9grmKMwTiZwUHSExjtbFzHLPTdWoXgcg1bZkhvwTrTww`.
+
+## Keypair conventions
+
+Many commands using the CLI tools require a value for a `<KEYPAIR>`. The value
+you should use for the keypair depends on what type of
+[command line wallet you created](../wallet-guide/cli.md).
+
+For example, the CLI help shows that the way to display any wallet's address
+(also known as the keypair's pubkey), is:
+
+```bash
+solana-keygen pubkey <KEYPAIR>
+```
+
+Below, we show how to resolve what you should put in `<KEYPAIR>` depending
+on your wallet type.
+
+#### Paper Wallet
+
+In a paper wallet, the keypair is securely derived from the seed words and
+optional passphrase you entered when the wallet was created. To use a paper
+wallet keypair anywhere the `<KEYPAIR>` text is shown in examples or help
+documents, enter the uri scheme `prompt://` and the program will prompt you to
+enter your seed words when you run the command.
+
+To display the wallet address of a Paper Wallet:
+
+```bash
+solana-keygen pubkey prompt://
+```
+
+#### File System Wallet
+
+With a file system wallet, the keypair is stored in a file on your computer.
+Replace `<KEYPAIR>` with the complete file path to the keypair file.
+
+For example, if the file system keypair file location is
+`/home/solana/my_wallet.json`, to display the address, do:
+
+```bash
+solana-keygen pubkey /home/solana/my_wallet.json
+```
+
+#### Hardware Wallet
+
+If you chose a hardware wallet, use your
+[keypair URL](../wallet-guide/hardware-wallets.md#specify-a-hardware-wallet-key),
+such as `usb://ledger?key=0`.
+
+```bash
+solana-keygen pubkey usb://ledger?key=0
+```

package/src/cli/delegate-stake.md

@@ -0,0 +1,206 @@
+---
+title: Staking
+---
+For an overview of staking, read first the
+[Staking and Inflation FAQ](https://solana.com/staking).
+
+------
+
+After you have [received SOL](transfer-tokens.md), you might consider putting
+it to use by delegating _stake_ to a validator. Stake is what we call tokens
+in a _stake account_. Solana weights validator votes by the amount of stake
+delegated to them, which gives those validators more influence in determining
+then next valid block of transactions in the blockchain. Solana then generates
+new SOL periodically to reward stakers and validators. You earn more rewards
+the more stake you delegate.
+
+## Create a Stake Account
+
+To delegate stake, you will need to transfer some tokens into a stake account.
+To create an account, you will need a keypair. Its public key will be used as
+the [stake account address](../staking/stake-accounts.md#account-address).
+No need for a password or encryption here; this keypair will be discarded right
+after creating the stake account.
+
+```bash
+solana-keygen new --no-passphrase -o stake-account.json
+```
+
+The output will contain the public key after the text `pubkey:`.
+
+```text
+pubkey: GKvqsuNcnwWqPzzuhLmGi4rzzh55FhJtGizkhHaEJqiV
+```
+
+Copy the public key and store it for safekeeping. You will need it any time you
+want to perform an action on the stake account you create next.
+
+Now, create a stake account:
+
+```bash
+solana create-stake-account --from <KEYPAIR> stake-account.json <AMOUNT> \
+    --stake-authority <KEYPAIR> --withdraw-authority <KEYPAIR> \
+    --fee-payer <KEYPAIR>
+```
+
+`<AMOUNT>` tokens are transferred from the account at the "from" `<KEYPAIR>` to
+a new stake account at the public key of stake-account.json.
+
+The stake-account.json file can now be discarded. To authorize additional
+actions, you will use the `--stake-authority` or `--withdraw-authority` keypair,
+not stake-account.json.
+
+View the new stake account with the `solana stake-account` command:
+
+```bash
+solana stake-account <STAKE_ACCOUNT_ADDRESS>
+```
+
+The output will look similar to this:
+
+```text
+Total Stake: 5000 SOL
+Stake account is undelegated
+Stake Authority: EXU95vqs93yPeCeAU7mPPu6HbRUmTFPEiGug9oCdvQ5F
+Withdraw Authority: EXU95vqs93yPeCeAU7mPPu6HbRUmTFPEiGug9oCdvQ5F
+```
+
+### Set Stake and Withdraw Authorities
+
+[Stake and withdraw authorities](../staking/stake-accounts.md#understanding-account-authorities)
+can be set when creating an account via the
+`--stake-authority` and `--withdraw-authority` options, or afterward with the
+`solana stake-authorize` command. For example, to set a new stake authority,
+run:
+
+```bash
+solana stake-authorize <STAKE_ACCOUNT_ADDRESS> \
+    --stake-authority <KEYPAIR> --new-stake-authority <PUBKEY> \
+    --fee-payer <KEYPAIR>
+```
+
+This will use the existing stake authority `<KEYPAIR>` to authorize a new stake
+authority `<PUBKEY>` on the stake account `<STAKE_ACCOUNT_ADDRESS>`.
+
+### Advanced: Derive Stake Account Addresses
+
+When you delegate stake, you delegate all tokens in the stake account to a
+single validator. To delegate to multiple validators, you will need multiple
+stake accounts. Creating a new keypair for each account and managing those
+addresses can be cumbersome. Fortunately, you can derive stake addresses using
+the `--seed` option:
+
+```bash
+solana create-stake-account --from <KEYPAIR> <STAKE_ACCOUNT_KEYPAIR> --seed <STRING> <AMOUNT> \
+    --stake-authority <PUBKEY> --withdraw-authority <PUBKEY> --fee-payer <KEYPAIR>
+```
+
+`<STRING>` is an arbitrary string up to 32 bytes, but will typically be a
+number corresponding to which derived account this is. The first account might
+be "0", then "1", and so on. The public key of `<STAKE_ACCOUNT_KEYPAIR>` acts
+as the base address. The command derives a new address from the base address
+and seed string. To see what stake address the command will derive, use `solana create-address-with-seed`:
+
+```bash
+solana create-address-with-seed --from <PUBKEY> <SEED_STRING> STAKE
+```
+
+`<PUBKEY>` is the public key of the `<STAKE_ACCOUNT_KEYPAIR>` passed to
+`solana create-stake-account`.
+
+The command will output a derived address, which can be used for the
+`<STAKE_ACCOUNT_ADDRESS>` argument in staking operations.
+
+## Delegate Stake
+
+To delegate your stake to a validator, you will need its vote account address.
+Find it by querying the cluster for the list of all validators and their vote
+accounts with the `solana validators` command:
+
+```bash
+solana validators
+```
+
+The first column of each row contains the validator's identity and the second
+is the vote account address. Choose a validator and use its vote account
+address in `solana delegate-stake`:
+
+```bash
+solana delegate-stake --stake-authority <KEYPAIR> <STAKE_ACCOUNT_ADDRESS> <VOTE_ACCOUNT_ADDRESS> \
+    --fee-payer <KEYPAIR>
+```
+
+The stake authority `<KEYPAIR>` authorizes the operation on the account with
+address `<STAKE_ACCOUNT_ADDRESS>`. The stake is delegated to the vote account
+with address `<VOTE_ACCOUNT_ADDRESS>`.
+
+After delegating stake, use `solana stake-account` to observe the changes
+to the stake account:
+
+```bash
+solana stake-account <STAKE_ACCOUNT_ADDRESS>
+```
+
+You will see new fields "Delegated Stake" and "Delegated Vote Account Address"
+in the output. The output will look similar to this:
+
+```text
+Total Stake: 5000 SOL
+Credits Observed: 147462
+Delegated Stake: 4999.99771712 SOL
+Delegated Vote Account Address: CcaHc2L43ZWjwCHART3oZoJvHLAe9hzT2DJNUpBzoTN1
+Stake activates starting from epoch: 42
+Stake Authority: EXU95vqs93yPeCeAU7mPPu6HbRUmTFPEiGug9oCdvQ5F
+Withdraw Authority: EXU95vqs93yPeCeAU7mPPu6HbRUmTFPEiGug9oCdvQ5F
+```
+
+## Deactivate Stake
+
+Once delegated, you can undelegate stake with the `solana deactivate-stake`
+command:
+
+```bash
+solana deactivate-stake --stake-authority <KEYPAIR> <STAKE_ACCOUNT_ADDRESS> \
+    --fee-payer <KEYPAIR>
+```
+
+The stake authority `<KEYPAIR>` authorizes the operation on the account
+with address `<STAKE_ACCOUNT_ADDRESS>`.
+
+Note that stake takes several epochs to "cool down". Attempts to delegate stake
+in the cool down period will fail.
+
+## Withdraw Stake
+
+Transfer tokens out of a stake account with the `solana withdraw-stake` command:
+
+```bash
+solana withdraw-stake --withdraw-authority <KEYPAIR> <STAKE_ACCOUNT_ADDRESS> <RECIPIENT_ADDRESS> <AMOUNT> \
+    --fee-payer <KEYPAIR>
+```
+
+`<STAKE_ACCOUNT_ADDRESS>` is the existing stake account, the stake authority
+`<KEYPAIR>` is the withdraw authority, and `<AMOUNT>` is the number of tokens
+to transfer to `<RECIPIENT_ADDRESS>`.
+
+## Split Stake
+
+You may want to delegate stake to additional validators while your existing
+stake is not eligible for withdrawal. It might not be eligible because it is
+currently staked, cooling down, or locked up. To transfer tokens from an
+existing stake account to a new one, use the `solana split-stake` command:
+
+```bash
+solana split-stake --stake-authority <KEYPAIR> <STAKE_ACCOUNT_ADDRESS> <NEW_STAKE_ACCOUNT_KEYPAIR> <AMOUNT> \
+    --fee-payer <KEYPAIR>
+```
+
+`<STAKE_ACCOUNT_ADDRESS>` is the existing stake account, the stake authority
+`<KEYPAIR>` is the stake authority, `<NEW_STAKE_ACCOUNT_KEYPAIR>` is the
+keypair for the new account, and `<AMOUNT>` is the number of tokens to transfer
+to the new account.
+
+To split a stake account into a derived account address, use the `--seed`
+option. See
+[Derive Stake Account Addresses](#advanced-derive-stake-account-addresses)
+for details.

package/src/cli/deploy-a-program.md

@@ -0,0 +1,302 @@
+---
+title: Deploy a Program
+---
+
+Developers can deploy on-chain [programs](terminology.md#program) (often called
+smart contracts elsewhere) with the Solana tools.
+
+To learn about developing and executing programs on Solana, start with the
+[overview](developing/programming-model/overview.md) and then dig into the
+details of [on-chain programs](developing/on-chain-programs/overview.md).
+
+To deploy a program, use the Solana tools to interact with the on-chain loader
+to:
+
+- Initialize a program account
+- Upload the program's shared object to the program account's data buffer
+- Verify the uploaded program
+- Finalize the program by marking the program account executable.
+
+Once deployed, anyone can execute the program by sending transactions that
+reference it to the cluster.
+
+## Usage
+
+### Deploy a program
+
+To deploy a program, you will need the location of the program's shared object
+(the program binary .so)
+
+```bash
+solana program deploy <PROGRAM_FILEPATH>
+```
+
+Successful deployment will return the program id of the deployed program, for
+example:
+
+```bash
+Program Id: 3KS2k14CmtnuVv2fvYcvdrNgC94Y11WETBpMUGgXyWZL
+```
+
+Specify the keypair in the deploy command to deploy to a specific program id:
+
+```bash
+solana program deploy --program-id <KEYPAIR_FILEPATH> <PROGRAM_FILEPATH>
+```
+
+If the program id is not specified on the command line the tools will first look
+for a keypair file matching the `<PROGRAM_FILEPATH>`, or internally generate a
+new keypair.
+
+A matching program keypair file is in the same directory as the program's shared
+object, and named <PROGRAM_NAME>-keypair.json. Matching program keypairs are
+generated automatically by the program build tools:
+
+```bash
+./path-to-program/program.so
+./path-to-program/program-keypair.json
+```
+
+### Showing a program account
+
+To get information about a deployed program:
+
+```bash
+solana program show <ACCOUNT_ADDRESS>
+```
+
+An example output looks like:
+
+```bash
+Program Id: 3KS2k14CmtnuVv2fvYcvdrNgC94Y11WETBpMUGgXyWZL
+Owner: BPFLoaderUpgradeab1e11111111111111111111111
+ProgramData Address: EHsACWBhgmw8iq5dmUZzTA1esRqcTognhKNHUkPi4q4g
+Authority: FwoGJNUaJN2zfVEex9BB11Dqb3NJKy3e9oY3KTh9XzCU
+Last Deployed In Slot: 63890568
+Data Length: 5216 (0x1460) bytes
+```
+
+- `Program Id` is the address that can be referenced in an instruction's
+  `program_id` field when invoking a program.
+- `Owner`: The loader this program was deployed with.
+- `ProgramData Address` is the account associated with the program account that
+  holds the program's data (shared object).
+- `Authority` is the program's upgrade authority.
+- `Last Deployed In Slot` is the slot in which the program was last deployed.
+- `Data Length` is the size of the space reserved for deployments. The actual
+  space used by the currently deployed program may be less.
+
+### Redeploy a program
+
+A program can be redeployed to the same address to facilitate rapid development,
+bug fixes, or upgrades. Matching keypair files are generated once so that
+redeployments will be to the same program address.
+
+The command looks the same as the deployment command:
+
+```bash
+solana program deploy <PROGRAM_FILEPATH>
+```
+
+By default, programs are deployed to accounts that are twice the size of the
+original deployment. Doing so leaves room for program growth in future
+redeployments. But, if the initially deployed program is very small (like a
+simple helloworld program) and then later grows substantially, the redeployment
+may fail. To avoid this, specify a `max_len` that is at least the size (in
+bytes) that the program is expected to become (plus some wiggle room).
+
+```bash
+solana program deploy --max-len 200000 <PROGRAM_FILEPATH>
+```
+
+Note that program accounts are required to be
+[rent-exempt](developing/programming-model/accounts.md#rent-exemption), and the
+`max-len` is fixed after initial deployment, so any SOL in the program accounts
+is locked up permanently.
+
+### Resuming a failed deploy
+
+If program deployment fails, there will be a hanging intermediate buffer account
+that contains a non-zero balance. In order to recoup that balance you may
+resume a failed deployment by providing the same intermediate buffer to a new
+call to `deploy`.
+
+Deployment failures will print an error message specifying the seed phrase
+needed to recover the generated intermediate buffer's keypair:
+
+```
+==================================================================================
+Recover the intermediate account's ephemeral keypair file with
+`solana-keygen recover` and the following 12-word seed phrase:
+==================================================================================
+valley flat great hockey share token excess clever benefit traffic avocado athlete
+==================================================================================
+To resume a deploy, pass the recovered keypair as
+the [BUFFER_SIGNER] to `solana program deploy` or `solana write-buffer'.
+Or to recover the account's lamports, pass it as the
+[BUFFER_ACCOUNT_ADDRESS] argument to `solana program drain`.
+==================================================================================
+```
+
+To recover the keypair:
+
+```bash
+solana-keygen recover -o <KEYPAIR_PATH>
+```
+
+When asked, enter the 12-word seed phrase.
+
+Then issue a new `deploy` command and specify the buffer:
+
+```bash
+solana program deploy --buffer <KEYPAIR_PATH> <PROGRAM_FILEPATH>
+```
+
+### Closing program and buffer accounts, and reclaiming their lamports
+
+Both program and buffer accounts can be closed and their lamport balances
+transferred to a recipient's account.
+
+If deployment fails there will be a left over buffer account that holds
+lamports. The buffer account can either be used to [resume a
+deploy](#resuming-a-failed-deploy) or closed.
+
+The program or buffer account's authority must be present to close an account,
+to list all the open program or buffer accounts that match the default
+authority:
+
+```bash
+solana program show --programs
+solana program show --buffers
+```
+
+To specify a different authority:
+
+```bash
+solana program show --programs --buffer-authority <AURTHORITY_ADRESS>
+solana program show --buffers --buffer-authority <AURTHORITY_ADRESS>
+```
+
+To close a single account:
+
+```bash
+solana program close <BADDRESS>
+```
+
+To close a single account and specify a different authority than the default:
+
+```bash
+solana program close <ADDRESS> --buffer-authority <KEYPAIR_FILEPATH>
+```
+
+To close a single account and specify a different recipient than the default:
+
+```bash
+solana program close <ADDRESS> --recipient <RECIPIENT_ADDRESS>
+```
+
+To close all the buffer accounts associated with the current authority:
+
+```bash
+solana program close --buffers
+```
+
+To show all buffer accounts regardless of the authority
+
+```bash
+solana program show --buffers --all
+```
+
+### Set a program's upgrade authority
+
+The program's upgrade authority must to be present to deploy a program. If no
+authority is specified during program deployment, the default keypair is used as
+the authority. This is why redeploying a program in the steps above didn't
+require an authority to be explicitly specified.
+
+The authority can be specified during deployment:
+
+```bash
+solana program deploy --upgrade-authority <UPGRADE_AUTHORITY_SIGNER> <PROGRAM_FILEPATH>
+```
+
+Or after deployment and using the default keypair as the current authority:
+
+```bash
+solana program set-upgrade-authority <PROGRAM_ADDRESS> --new-upgrade-authority <NEW_UPGRADE_AUTHORITY>
+```
+
+Or after deployment and specifying the current authority:
+
+```bash
+solana program set-upgrade-authority <PROGRAM_ADDRESS> --upgrade-authority <UPGRADE_AUTHORITY_SIGNER> --new-upgrade-authority <NEW_UPGRADE_AUTHORITY>
+```
+
+### Immutable programs
+
+A program can be marked immutable, which prevents all further redeployments, by
+specifying the `--final` flag during deployment:
+
+```bash
+solana program deploy <PROGRAM_FILEPATH> --final
+```
+
+Or anytime after:
+
+```bash
+solana program set-upgrade-authority <PROGRAM_ADDRESS> --final
+```
+
+### Dumping a program to a file
+
+The deployed program may be dumped back to a local file:
+
+```bash
+solana program dump <ACCOUNT_ADDRESS> <OUTPUT_FILEPATH>
+```
+
+The dumped file will be in the same as what was deployed, so in the case of a
+shared object, the dumped file will be a fully functional shared object. Note
+that the `dump` command dumps the entire data space, which means the output file
+will have trailing zeros after the shared object's data up to `max_len`.
+Sometimes it is useful to dump and compare a program to ensure it matches a
+known program binary. The original program file can be zero-extended, hashed,
+and compared to the hash of the dumped file.
+
+```bash
+$ solana dump <ACCOUNT_ADDRESS> dump.so
+$ cp original.so extended.so
+$ truncate -r dump.so extended.so
+$ sha256sum extended.so dump.so
+```
+
+### Using an intermediary Buffer account
+
+Instead of deploying directly to the program account, the program can be written
+to an intermediary buffer account. Intermediary accounts can be useful for things
+like multi-entity governed programs where the governing members fist verify the
+intermediary buffer contents and then vote to allow an upgrade using it.
+
+```bash
+solana program write-buffer <PROGRAM_FILEPATH>
+```
+
+Buffer accounts support authorities like program accounts:
+
+```bash
+solana program set-buffer-authority <BUFFER_ADDRESS> --new-upgrade-authority <NEW_UPGRADE_AUTHORITY>
+```
+
+One exception is that buffer accounts cannot be marked immutable like program
+accounts can, so they don't support `--final`.
+
+The buffer account, once entirely written, can be passed to `deploy` to deploy
+the program:
+
+```bash
+solana program deploy --program-id <PROGRAM_ADDRESS> --buffer <BUFFER_ADDRESS>
+```
+
+Note, the buffer's authority must match the program's upgrade authority.
+
+Buffers also support `show` and `dump` just like programs do.