From 74c54a7856982b9f4f4b2c65b79a504eb307aad3 Mon Sep 17 00:00:00 2001 From: norwnd <112318969+norwnd@users.noreply.github.com> Date: Thu, 7 Dec 2023 21:26:49 +0300 Subject: [PATCH] docs: (cli) minor updates to deploy-a-program.md (#34307) * docs: (cli) minor updates to deploy-a-program.md * address review comments * remove unnecessary impl details from the docs about deploy command upgrade flow * clarify program redeploy section --------- Co-authored-by: norwnd --- docs/src/cli/deploy-a-program.md | 33 +++++++++++++++++--------------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/docs/src/cli/deploy-a-program.md b/docs/src/cli/deploy-a-program.md index 1f39dfe139..3b2c89bf45 100644 --- a/docs/src/cli/deploy-a-program.md +++ b/docs/src/cli/deploy-a-program.md @@ -13,8 +13,8 @@ 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 +- Upload the program's shared object (the program binary `.so`) to the program account's data buffer +- (optional) Verify the uploaded program - Finalize the program by marking the program account executable. Once deployed, anyone can execute the program by sending transactions that @@ -25,7 +25,7 @@ reference it to the cluster. ### Deploy a program To deploy a program, you will need the location of the program's shared object -(the program binary .so) +(the program binary `.so`): ```bash solana program deploy @@ -89,8 +89,9 @@ Data Length: 5216 (0x1460) bytes ### 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. +bug fixes, or upgrades. If a program id is not provided, the program will be +deployed to the default address at `-keypair.json`. This default +keypair is generated during the first program compilation. The command looks the same as the deployment command: @@ -109,11 +110,6 @@ to become (plus some wiggle room). solana program deploy --max-len 200000 ``` -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 @@ -157,7 +153,7 @@ solana program deploy --buffer 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 +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. @@ -209,7 +205,7 @@ 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 +The program's upgrade authority must 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. @@ -232,6 +228,11 @@ Or after deployment and specifying the current authority: solana program set-upgrade-authority --upgrade-authority --new-upgrade-authority ``` +By default, `set-upgrade-authority` requires a signature from the new authority. This behavior prevents a +developer from giving upgrade authority to a key that they do not have access to. The +`--skip-new-upgrade-authority-signer-check` option relaxes the signer check. This can be useful for situations +where the new upgrade authority is an offline signer or a multisig. + ### Immutable programs A program can be marked immutable, which prevents all further redeployments, by @@ -256,12 +257,12 @@ 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 +shared object (the program binary `.so`), 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. +known program binary. The dumped file can be zero-truncated, hashed, +and compared to the hash of the original program file. ```bash $ solana dump dump.so @@ -298,5 +299,7 @@ solana program deploy --program-id --buffer ``` Note, the buffer's authority must match the program's upgrade authority. +During deployment, the buffer account's contents are copied into the program-data account and +the buffer account is set to zero. The lamports from the buffer account are refunded to a spill account. Buffers also support `show` and `dump` just like programs do.