Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: (cli) minor updates to deploy-a-program.md #34307

Merged
merged 4 commits into from
Dec 7, 2023
Merged

docs: (cli) minor updates to deploy-a-program.md #34307

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a0c471c
docs: (cli) minor updates to deploy-a-program.md
Dec 2, 2023
a229657
address review comments
Dec 7, 2023
6867112
remove unnecessary impl details from the docs about deploy command up…
Dec 7, 2023
c6e7335
clarify program redeploy section
Dec 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 32 additions & 20 deletions docs/src/cli/deploy-a-program.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 <PROGRAM_FILEPATH>
Expand All @@ -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 `<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:
You can typically find 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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is this change for? With the change in wording, it makes it seem like the keypair isn't always generated. Is that the case?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess I was trying to point out that program keypairs aren't there until you compile your program's source code. Re-reading it now - can't say I succeeded : )

Perhaps we'd want to put Matching program keypairs are generated ... sentence first to make it abundantly clear, but for now I've reverted this change in a229657


```bash
./path-to-program/program.so
Expand Down Expand Up @@ -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 <PROGRAM_FILEPATH>, this keypair file will be generated once and then reused):
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I don't understand what this is trying to say anymore, and think the previous sentence was clearer. What was the exact problem with the previous language?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Whoops, bad phrasing on my part, I was trying to elaborate that deploy command in "upgrade" mode will also be using that same keypair file that was used during "initial deploy" mode (and that's how it knows what program to upgrade on-chain),

perhaps that's an implementation detail that's not really needed in the docs, removing for now: 6867112 (let me know if you want it added to the docs in some other form)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about we go back to the previous sentence that was there? With this change, there's no more reference to the generated keypair at all

Copy link
Contributor Author

@norwnd norwnd Dec 7, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pretty much, the Matching keypair files are generated is a bit unspecific/lacking for my taste (which is why I tried changing it),

perhaps repharase:

Matching keypair files are generated once so that
redeployments will be to the same program address.

into something like ?

Program signer stored in keypair file at <PROGRAM_FILEPATH> is 
generated once (when program is compiled for the very first time) and 
will be used to identify which on-chain program (what Solana address) 
redeployment targets.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about we simplify and explain how the CLI behaves:

If a program id is not provided, the program will be deployed to the default address
at `<PROGRAM_NAME>-keypair.json`. This default keypair is generated during the first
program compilation.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

c6e7335


```bash
solana program deploy <PROGRAM_FILEPATH>
Expand All @@ -111,8 +111,8 @@ 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.
`max-len` **cannot be changed** after initial deployment, yet any SOL in the program accounts
is locked up permanently and cannot be reclaimed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Neither of these are currently true, since you can close a program to reclaim the lamports and you can extend a program to use more data. Do you mind removing this whole paragraph?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see, removed in a229657


### Resuming a failed deploy

Expand Down Expand Up @@ -157,7 +157,7 @@ solana program deploy --buffer <KEYPAIR_PATH> <PROGRAM_FILEPATH>
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.

Expand Down Expand Up @@ -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.
Expand All @@ -232,6 +232,16 @@ Or after deployment and specifying the current authority:
solana program set-upgrade-authority <PROGRAM_ADDRESS> --upgrade-authority <UPGRADE_AUTHORITY_SIGNER> --new-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):
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[upgrading program using offline signer as authority](deploy-a-program.md#upgrading-program-using-offline-signer-as-authority) section will be available once #33860 is merged.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove the reference to the new section. This PR will go in first, which means that the docs would point to nothing for some time. For consistency, let's add the reference when it goes in

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Okay, can add it later, removed in a229657

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: How about we give the precise motivation

Suggested change
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):
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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied in a229657


```bash
solana program set-upgrade-authority <PROGRAM_ADDRESS> --new-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
Expand All @@ -256,12 +266,12 @@ 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
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`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: I think this should stay will, since it will always have trailing zeros after the shared object's data up to max_len

Copy link
Contributor Author

@norwnd norwnd Dec 7, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was trying to be precise (I think there shouldn't be trailing zeros if shared object's data == max_len ?), anyway reverted in a229657

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 <ACCOUNT_ADDRESS> dump.so
Expand All @@ -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).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's revert this change and have it in the original PR. It's strange to reference a section that doesn't exist!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, removed in a229657


```bash
solana program write-buffer <PROGRAM_FILEPATH>
```

Buffer accounts support authorities like program accounts:
Buffer accounts support different authorities (including offline signer and program account signer):
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The original sentence means that buffers have an authority, similar to program accounts. With the change, it makes it sound like a buffer has multiple authorities, which is not the case. So let's revert the change

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gotcha, reverted in a229657


```bash
solana program set-buffer-authority <BUFFER_ADDRESS> --new-buffer-authority <NEW_BUFFER_AUTHORITY>
Expand All @@ -297,6 +308,7 @@ the program:
solana program deploy --program-id <PROGRAM_ADDRESS> --buffer <BUFFER_ADDRESS>
```

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit:

Suggested change
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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied in a229657


Buffers also support `show` and `dump` just like programs do.