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 all 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
33 changes: 18 additions & 15 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,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 `<PROGRAM_NAME>-keypair.json`. This default
keypair is generated during the first program compilation.

The command looks the same as the deployment command:

Expand All @@ -109,11 +110,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 +153,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 +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.
Expand All @@ -232,6 +228,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 +257,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 +299,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.