From a0c471c1c7658312ff34f17a6edb0b3e9c7241bf Mon Sep 17 00:00:00 2001 From: norwnd Date: Sat, 2 Dec 2023 20:34:01 +0300 Subject: [PATCH 1/4] docs: (cli) minor updates to deploy-a-program.md --- docs/src/cli/deploy-a-program.md | 52 ++++++++++++++++++++------------ 1 file changed, 32 insertions(+), 20 deletions(-) diff --git a/docs/src/cli/deploy-a-program.md b/docs/src/cli/deploy-a-program.md index 1f39dfe1399e70..da33fd93803030 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 @@ -48,9 +48,9 @@ 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 in the same directory as the program's shared -object, and named -keypair.json. Matching program keypairs are -generated automatically by the program build tools: +You can typically find a matching program keypair file is in the same directory +as the program's shared object, and named -keypair.json. Matching +program keypairs are generated automatically by the program build tools: ```bash ./path-to-program/program.so @@ -89,10 +89,10 @@ 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. -The command looks the same as the deployment command: +The command looks the same as the deployment command (same keypair file that resides from file directory corresponding +to , this keypair file will be generated once and then reused): ```bash solana program deploy @@ -111,8 +111,8 @@ 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. +`max-len` **cannot be changed** after initial deployment, yet any SOL in the program accounts +is locked up permanently and cannot be reclaimed. ### Resuming a failed deploy @@ -157,7 +157,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 +209,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 +232,16 @@ Or after deployment and specifying the current authority: solana program set-upgrade-authority --upgrade-authority --new-upgrade-authority ``` +In case you want to set "new upgrade authority" to a signer that you only have a pubkey of (meaning, you don't have access +to its private key) - which is useful for things like [upgrading program using offline signer as authority](deploy-a-program.md#upgrading-program-using-offline-signer-as-authority) - +you need to use `--skip-new-upgrade-authority-signer-check` option to inform `solana program set-upgrade-authority` +command of your intentions (because otherwise it assumes you have access to that singer's private key and checks for +that, to ensure you don't accidentally supply "new upgrade authority" you don't have control over): + +```bash +solana program set-upgrade-authority --new-upgrade-authority --skip-new-upgrade-authority-signer-check +``` + ### Immutable programs A program can be marked immutable, which prevents all further redeployments, by @@ -256,12 +266,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`. +might 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 @@ -275,13 +285,14 @@ $ sha256sum extended.so dump.so 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. +intermediary buffer contents and then vote to allow an upgrade using it, or for +[deploying programs with offline signer authority](#deploying-program-with-offline-signer-authority). ```bash solana program write-buffer ``` -Buffer accounts support authorities like program accounts: +Buffer accounts support different authorities (including offline signer and program account signer): ```bash solana program set-buffer-authority --new-buffer-authority @@ -297,6 +308,7 @@ the program: solana program deploy --program-id --buffer ``` -Note, the buffer's authority must match the program's upgrade authority. +Note, the buffer's authority must match the program's upgrade authority. Also, upon successful deploy +buffer accounts contents are copied into program accounts and are erased from blockchain. Buffers also support `show` and `dump` just like programs do. From a22965706fd4d569b07409b161d2cdc5874d1ea1 Mon Sep 17 00:00:00 2001 From: norwnd Date: Thu, 7 Dec 2023 13:06:20 +0300 Subject: [PATCH 2/4] address review comments --- docs/src/cli/deploy-a-program.md | 36 ++++++++++++-------------------- 1 file changed, 13 insertions(+), 23 deletions(-) diff --git a/docs/src/cli/deploy-a-program.md b/docs/src/cli/deploy-a-program.md index da33fd93803030..d763d234a0c7f1 100644 --- a/docs/src/cli/deploy-a-program.md +++ b/docs/src/cli/deploy-a-program.md @@ -48,9 +48,9 @@ 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. -You can typically find a matching program keypair file is in the same directory -as the program's shared object, and named -keypair.json. Matching -program keypairs are generated automatically by the program build tools: +A matching program keypair file is in the same directory as the program's shared +object, and named -keypair.json. Matching program keypairs are +generated automatically by the program build tools: ```bash ./path-to-program/program.so @@ -109,11 +109,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` **cannot be changed** after initial deployment, yet any SOL in the program accounts -is locked up permanently and cannot be reclaimed. - ### Resuming a failed deploy If program deployment fails, there will be a hanging intermediate buffer account @@ -232,15 +227,10 @@ Or after deployment and specifying the current authority: solana program set-upgrade-authority --upgrade-authority --new-upgrade-authority ``` -In case you want to set "new upgrade authority" to a signer that you only have a pubkey of (meaning, you don't have access -to its private key) - which is useful for things like [upgrading program using offline signer as authority](deploy-a-program.md#upgrading-program-using-offline-signer-as-authority) - -you need to use `--skip-new-upgrade-authority-signer-check` option to inform `solana program set-upgrade-authority` -command of your intentions (because otherwise it assumes you have access to that singer's private key and checks for -that, to ensure you don't accidentally supply "new upgrade authority" you don't have control over): - -```bash -solana program set-upgrade-authority --new-upgrade-authority --skip-new-upgrade-authority-signer-check -``` +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 @@ -268,7 +258,7 @@ solana program dump The dumped file will be in the same as what was deployed, so in the case of a 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 -might have trailing zeros after the shared object's data up to `max_len`. +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 dumped file can be zero-truncated, hashed, and compared to the hash of the original program file. @@ -285,14 +275,13 @@ $ sha256sum extended.so dump.so 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, or for -[deploying programs with offline signer authority](#deploying-program-with-offline-signer-authority). +intermediary buffer contents and then vote to allow an upgrade using it. ```bash solana program write-buffer ``` -Buffer accounts support different authorities (including offline signer and program account signer): +Buffer accounts support authorities like program accounts: ```bash solana program set-buffer-authority --new-buffer-authority @@ -308,7 +297,8 @@ the program: solana program deploy --program-id --buffer ``` -Note, the buffer's authority must match the program's upgrade authority. Also, upon successful deploy -buffer accounts contents are copied into program accounts and are erased from blockchain. +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. From 6867112079bcd772720177d8ec1995d9372594db Mon Sep 17 00:00:00 2001 From: norwnd Date: Thu, 7 Dec 2023 19:01:49 +0300 Subject: [PATCH 3/4] remove unnecessary impl details from the docs about deploy command upgrade flow --- docs/src/cli/deploy-a-program.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/src/cli/deploy-a-program.md b/docs/src/cli/deploy-a-program.md index d763d234a0c7f1..043e4d3d1b4fa5 100644 --- a/docs/src/cli/deploy-a-program.md +++ b/docs/src/cli/deploy-a-program.md @@ -91,8 +91,7 @@ Data Length: 5216 (0x1460) bytes A program can be redeployed to the same address to facilitate rapid development, bug fixes, or upgrades. -The command looks the same as the deployment command (same keypair file that resides from file directory corresponding -to , this keypair file will be generated once and then reused): +The command looks the same as the deployment command: ```bash solana program deploy From c6e733537441efafb4aac68752a3f49e948dc87c Mon Sep 17 00:00:00 2001 From: norwnd Date: Thu, 7 Dec 2023 21:19:29 +0300 Subject: [PATCH 4/4] clarify program redeploy section --- docs/src/cli/deploy-a-program.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/src/cli/deploy-a-program.md b/docs/src/cli/deploy-a-program.md index 043e4d3d1b4fa5..3b2c89bf454ea2 100644 --- a/docs/src/cli/deploy-a-program.md +++ b/docs/src/cli/deploy-a-program.md @@ -89,7 +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. +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: