diff --git a/cli-output/src/cli_output.rs b/cli-output/src/cli_output.rs index db448fd7f4..a39ee0799e 100644 --- a/cli-output/src/cli_output.rs +++ b/cli-output/src/cli_output.rs @@ -1524,8 +1524,8 @@ pub struct CliUpgradeableProgram { pub program_id: String, pub programdata_address: String, pub authority: String, - pub last_upgrade_slot: u64, - pub program_len: usize, + pub last_deploy_slot: u64, + pub data_len: usize, } impl QuietDisplay for CliUpgradeableProgram {} impl VerboseDisplay for CliUpgradeableProgram {} @@ -1537,13 +1537,13 @@ impl fmt::Display for CliUpgradeableProgram { writeln_name_value(f, "Authority:", &self.authority)?; writeln_name_value( f, - "Last Upgraded In Slot:", - &self.last_upgrade_slot.to_string(), + "Last Deployed In Slot:", + &self.last_deploy_slot.to_string(), )?; writeln_name_value( f, - "Program Length:", - &format!("{:?} ({:#x?}) bytes", self.program_len, self.program_len), + "Data Length:", + &format!("{:?} ({:#x?}) bytes", self.data_len, self.data_len), )?; Ok(()) } diff --git a/cli/src/program.rs b/cli/src/program.rs index dad5a03f20..9b070ecc50 100644 --- a/cli/src/program.rs +++ b/cli/src/program.rs @@ -951,8 +951,8 @@ fn process_show( authority: upgrade_authority_address .map(|pubkey| pubkey.to_string()) .unwrap_or_else(|| "none".to_string()), - last_upgrade_slot: slot, - program_len: programdata_account.data.len() + last_deploy_slot: slot, + data_len: programdata_account.data.len() - UpgradeableLoaderState::programdata_data_offset()?, })) } else { diff --git a/docs/sidebars.js b/docs/sidebars.js index 53056976e8..93aa0873d9 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -53,7 +53,8 @@ module.exports = { "cli/choose-a-cluster", "cli/transfer-tokens", "cli/delegate-stake", - "cli/manage-stake-accounts", + "cli/manage-stake-accounts", + "cli/deploy-a-program", "offline-signing", "offline-signing/durable-nonce", "cli/usage", diff --git a/docs/src/cli/.usage.md.header b/docs/src/cli/.usage.md.header index b81231c573..dbd384b1a3 100644 --- a/docs/src/cli/.usage.md.header +++ b/docs/src/cli/.usage.md.header @@ -50,7 +50,7 @@ $ solana confirm ```bash // Command -$ solana deploy +$ solana program deploy // Return diff --git a/docs/src/cli/delegate-stake.md b/docs/src/cli/delegate-stake.md index bb2d5f602f..ffbcf2d998 100644 --- a/docs/src/cli/delegate-stake.md +++ b/docs/src/cli/delegate-stake.md @@ -11,6 +11,7 @@ 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). @@ -61,6 +62,7 @@ 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 diff --git a/docs/src/cli/deploy-a-program.md b/docs/src/cli/deploy-a-program.md new file mode 100644 index 0000000000..720c501fc0 --- /dev/null +++ b/docs/src/cli/deploy-a-program.md @@ -0,0 +1,217 @@ +--- +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 [deployed programs](developing/deployed-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 +``` + +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 +``` + +If the program id is not specified on the command line the tools will first look +for a keypair file matching the ``, or internally generate a +new keypair. + +A matching program/keypair file is generated automatically by the program build +tools and looks like: + +```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 show +``` + +An example output looks like: + +```bash +Program Id: 3KS2k14CmtnuVv2fvYcvdrNgC94Y11WETBpMUGgXyWZL +ProgramData Address: EHsACWBhgmw8iq5dmUZzTA1esRqcTognhKNHUkPi4q4g +Authority: FwoGJNUaJN2zfVEex9BB11Dqb3NJKy3e9oY3KTh9XzCU +Last Upgraded In Slot: 63890568 +Program Length: 5216 (0x1460) bytes +``` + +- `Program Id` is the address that can be referenced in an instruction's + `program_id` field when invoking a program. +- `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 +``` + +By default, programs are deployed to accounts that are twice the size of the +original deployment. Doing so leaves room for further 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 +``` + +Note that program accounts are required to be +[rent-excempt](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. + +### 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 +``` + +Or after deployment and using the default keypair as the current authority: + +```bash +solana program set-upgrade-authority --new-upgrade-authority +``` + +Or after deployment and specifying the current authority: + +```bash +solana program set-upgrade-authority --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 --final +``` + +Or anytime after: + +```bash +solana program set-upgrade-authority --final +``` + +### Dumping a program to a file + +The deployed program may be dumped back to a local file: + +```bash +solana program dump +``` + +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 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. Doing so can be useful for things like +multi-entity governed programs. + +```bash +solana progrma write-buffer +``` + +Buffer accounts support authorities like program accounts: + +```bash +solana program set-buffer-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 --buffer +``` + +Note, the buffer's authority must match the program's upgrade authority. + +Buffers also support `show` and `dump` just like programs do. + +### Non-redeployable programs + +Using `solana program ...` utilizes Solana's upgradeable loader, but there is +another way to deploy programs using the original on-chain loader. + +```bash +solana deploy +``` + +Programs deployed with `solana deploy ...` are not upgradeable and are not +compatible with the `solana program ...` commands. diff --git a/docs/src/developing/programming-model/overview.md b/docs/src/developing/programming-model/overview.md index eabb9033e0..4a3c3ee8cc 100644 --- a/docs/src/developing/programming-model/overview.md +++ b/docs/src/developing/programming-model/overview.md @@ -5,13 +5,13 @@ title: "Overview" An [app](terminology.md#app) interacts with a Solana cluster by sending it [transactions](transactions.md) with one or more [instructions](transactions.md#instructions). The Solana [runtime](runtime.md) -passes those instructions to [programs](terminology.md#program) deployed by app developers -beforehand. An instruction might, for example, tell a program to transfer -[lamports](terminology.md#lamports) from one [account](accounts.md) to another -or create an interactive contract that governs how lamports are transferred. -Instructions are executed sequentially and atomically for each transaction. If -any instruction is invalid, all account changes in the transaction are -discarded. +passes those instructions to [programs](terminology.md#program) deployed by app +developers beforehand. An instruction might, for example, tell a program to +transfer [lamports](terminology.md#lamports) from one [account](accounts.md) to +another or create an interactive contract that governs how lamports are +transferred. Instructions are executed sequentially and atomically for each +transaction. If any instruction is invalid, all account changes in the +transaction are discarded. To start developing immediately you can build, deploy, and run one of the [examples](developing/deployed-programs/examples.md). \ No newline at end of file