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 2 commits
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
34 changes: 18 additions & 16 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 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 @@ -109,11 +109,6 @@ to become (plus some wiggle room).
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
Expand Down Expand Up @@ -157,7 +152,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 +204,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 +227,11 @@ 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>
```

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
Expand All @@ -256,12 +256,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`.
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 Down Expand Up @@ -298,5 +298,7 @@ solana program deploy --program-id <PROGRAM_ADDRESS> --buffer <BUFFER_ADDRESS>
```

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.