Deploying Programs

This guide assumes knowledge of the following topics:

Loader-v3 and Loader-v4

There is currently an ongoing transition from loader-v3 (program subcommand) to loader-v4 (program -v4 subcommand) as loader-v3 is being deprecated.

For new deployments please use solana program-v4 deploy instead of solana program deploy.

To migrate an existing program (which is essentially redeploying it):

solana program migrate ./target/deploy/your_program-keypair.json

Preparation

First, the program needs to be build (compiled, linked, stripped).

cargo +solana build --target sbpf-solana-solana --release

This step must be performed before every re-/deployment.

Check that sufficient funds are available to the default payer account proportional to the size of the executable:

du -h ./target/deploy/your_program.so 
solana balance

Additionally, each program has a program account and a program ID, which is the address of that program account. The following generates a keypair for the program account:

solana-keygen new -o ./target/deploy/your_program-keypair.json

This must only be performed once per program and will be reused for redeployments of the same program later on.

The toolchain contained a short cut, it is however being phased out / deprecated:

cargo-build-sbf

Initial Deployment

Now the executable can be uploaded to the program account:

Loader-v3

The parameter is called program-id even though it expects the file-path of a keypair:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

Loader-v4

solana program-v4 deploy ./target/deploy/your_program.so --program-keypair ./target/deploy/your_program-keypair.json

Uploading a different executable to the same program account again will overwrite / replace it. However, for redeployments, only the program ID (pubkey of the program keypair) is needed, not the entire keypair, because the signer is the upgrade authority keypair instead.

Loader-v3

This is exactly the same as the initial deployment:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

If the old executable was shorter than the new one it might be necessary to grow the programdata account first:

solana program extend ./target/deploy/your_program.so <ADDITIONAL_BYTES>

Loader-v4

Notice the initial deployment used program-keypair, while the redeployment uses program-id instead:

solana program-v4 deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

Prioritizing an Upload

During times of congestion, there are a few additional flags you can use to help with program deployment:

--with-compute-unit-price: Set compute unit price for transaction, in increments of 0.000001 lamports (micro-lamports) per compute unit. Use the Priority Fee API by Helius to get an estimate of the priority fee to set.
--use-rpc: Send write transactions to the configured RPC instead of validator TPUs. This flag requires a stake-weighted RPC connection such as Helius or Triton. This flag can also be configured to be default using: solana config set --url <RPC_URL>.
--max-sign-attempts: Maximum number of attempts to sign or resign transactions after blockhash expiration. If any transactions sent during the program deploy are still unconfirmed after the initially chosen recent blockhash expires, those transactions will be resigned with a new recent blockhash and resent. Use this setting to adjust the maximum number of transaction signing iterations. Each blockhash is valid for about 60 seconds, which means using the default value of 5 will lead to sending transactions for at least 5 minutes or until all transactions are confirmed, whichever comes first.

Resuming an Upload

It is possible that an upload gets stuck or is aborted.

Loader-v3

If program deployment fails, there will be a hanging intermediate buffer account that contains a non-zero balance. In order to recoup that balance you may resume a failed deployment by providing the same intermediate buffer to a new call to deploy.

Deployment failures will print an error message specifying the seed phrase needed to recover the generated intermediate buffer's keypair:

==================================================================================
Recover the intermediate account's ephemeral keypair file with
`solana-keygen recover` and the following 12-word seed phrase:
==================================================================================
valley flat great hockey share token excess clever benefit traffic avocado athlete
==================================================================================
To resume a deploy, pass the recovered keypair as
the [BUFFER_SIGNER] to `solana program deploy` or `solana program write-buffer'.
Or to recover the account's lamports, pass it as the
[BUFFER_ACCOUNT_ADDRESS] argument to `solana program drain`.
==================================================================================

To recover the keypair:

solana-keygen recover -o ./target/deploy/buffer-keypair.json

When asked, enter the 12-word seed phrase.

Then issue a new deploy command and specify the buffer:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json --buffer ./target/deploy/buffer-keypair.json

Loader-v4

It is possible to resume an upload at a specified byte offset:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json --start-offset <BYTES_UPLOADED_SO_FAR>

Finalization

This is an irreversible action.

A program can be made immutable by removing its upgrade authority.

Loader-v3

solana program set-upgrade-authority ./target/deploy/your_program-keypair.json --final

Loader-v4

solana program finalize --program-id ./target/deploy/your_program-keypair.json

Instead of overwriting programs it is also possible to provide users the choice of which version of a program they want to use by constructing a linked list of finalized programs:

solana program finalize --program-id ./target/deploy/your_program-keypair.json --next-version ../your_newer_program/target/deploy/your_newer_program-keypair.json

Closing

For programs deployed under loader-v3 only their programdata account, the buffer accounts and the funds locked in those can be reclaimed. The program account together with the program ID and funds locked in the program account specifically are stuck.

Programs deployed under loader-v4 can be closed with their program account, their program ID and their locked funds all becoming available for other uses again.

Loader-v3

This is an irreversible action for programs deployed using loader-v3.

Note that once a program is closed, its program ID cannot be reused. Attempting to deploy a program with a previously closed program ID will result in an error. If you need to redeploy a program after closing it, you must generate a new program keypair file.

To close a single programdata account:

solana program close ./target/deploy/your_program-keypair.json

To close all the buffer accounts associated with the current authority:

solana program close --buffers

Loader-v4

solana program-v4 close --program-id ./target/deploy/your_program-keypair.json

Inspecting Metadata

The show subcommand lists the metadata of a program.

An example output looks like:

Program Id: 3KS2k14CmtnuVv2fvYcvdrNgC94Y11WETBpMUGgXyWZL
Owner: BPFLoaderUpgradeab1e11111111111111111111111
ProgramData Address: EHsACWBhgmw8iq5dmUZzTA1esRqcTognhKNHUkPi4q4g
Authority: FwoGJNUaJN2zfVEex9BB11Dqb3NJKy3e9oY3KTh9XzCU
Last Deployed In Slot: 63890568
Data Length: 5216 (0x1460) bytes

Program Id is the address that can be referenced in an instruction's program_id field when invoking a program.
Owner: The loader this program was deployed with.
ProgramData Address is the programdata account associated with the program account that holds the program's executable (loader-v3 only).
Status: retracted, deployed or finalized (loader-v4 only).
Authority is the program's upgrade authority.
Last Deployed In Slot is the slot in which the program was last deployed.
Data Length is the size of the space reserved for deployments. The actual space used by the currently deployed program may be less.

Loader-v3

To view a specific program:

solana program show ./target/deploy/your_program-keypair.json

To view the list of programs deployed with the default authority:

solana program show --programs

To show all buffer accounts regardless of the authority:

solana program show --buffers --all

To specify a different authority:

solana program show --programs --buffer-authority ~/.config/solana/authority-keypair.json
solana program show --buffers --buffer-authority ~/.config/solana/authority-keypair.json

Loader-v4

To view a specific program:

solana program-v4 show --program-id ./target/deploy/your_program-keypair.json

To view the list of programs deployed with the default authority:

solana program-v4 show --all

To view the list of programs deployed with a specific authority:

solana program-v4 show --authority ~/.config/solana/authority-keypair.json

Downloading the Executable

Sometimes it is useful to download and compare a program to ensure it contains a known executable. The downloaded file can be truncated, hashed, and compared to the hash of the original program file.

Loader-v3

solana program dump ./target/deploy/your_program-keypair.json ./target/deploy/your_program.so

Loader-v4

solana program download ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

Advanced: Authority Transfer

The right to change a given program lies with its authority. This authority can be transferred to another keypair without changing the program keypair, so that the program ID stays the same. Furthermore, a single authority can control multiple program accounts.

If not explicitly specified during the initial deployment, then the default keypair is used as authority. This is why redeploying a program in the steps above didn't require an authority to be explicitly specified.

An explicit authority is useful for offline signing and multi-entity governed programs.

First, a keypair for the authority must be generated:

solana-keygen new -o ~/.config/solana/authority-keypair.json

Loader-v3

The authority can be specified during deployment:

solana program deploy ./target/deploy/your_program.so --upgrade-authority ~/.config/solana/authority-keypair.json

Or after deployment and using the default keypair as the current authority:

solana program set-upgrade-authority ./target/deploy/your_program-keypair.json --new-upgrade-authority ~/.config/solana/authority-keypair.json

Or after deployment and specifying the current authority:

solana program set-upgrade-authority ./target/deploy/your_program-keypair.json --upgrade-authority ~/.config/solana/authority-keypair.json --new-upgrade-authority ~/.config/solana/new_authority-keypair.json

Loader-v4

The authority can be specified during deployment:

solana program-v4 deploy ./target/deploy/your_program.so --program-keypair ./target/deploy/your_program-keypair.json --authority ~/.config/solana/authority-keypair.json

Or after deployment and using the default keypair as the current authority:

solana program-v4 transfer-authority --program-id ./target/deploy/your_program-keypair.json --new-authority ~/.config/solana/authority-keypair.json

Or after deployment and specifying the current authority:

solana program-v4 transfer-authority --program-id ./target/deploy/your_program-keypair.json --authority ~/.config/solana/authority-keypair.json --new-authority ~/.config/solana/new_authority-keypair.json

Advanced: Two-Step Redeployment using a Buffer

Instead of uploading directly to the program account, the executable can be uploaded to a staging buffer account first and then be transferred to the program account in a second step (the actual re-/deployment). This is useful for offline signing and multi-entity governed programs such as a DAO voting to choose or reject an uploaded executable before the actual redeployment.

Keep in mind that using buffer accounts roughly doubles the funds required during the upload process because two accounts are holding one executable each, simultaneously.

First, a keypair for the buffer account must be created:

solana-keygen new -o ~/.config/solana/buffer-keypair.json

The buffer account can be reused for different uploads and is not bound to any specific program account.

Loader-v3

solana program write-buffer ./target/deploy/your_program.so --buffer ~/.config/solana/buffer-keypair.json
solana program deploy --program-id ./target/deploy/your_program-keypair.json --buffer ~/.config/solana/buffer-keypair.json

Loader-v4

solana program-v4 deploy ./target/deploy/your_program.so --buffer ~/.config/solana/buffer-keypair.json
solana program-v4 deploy --program-id ./target/deploy/your_program-keypair.json --buffer ~/.config/solana/buffer-keypair.json

Advanced: Offline Signing

Some security models require separating the signing process from the transaction broadcast, such that the signing keys can be completely disconnected from any network, also known as offline signing.

Note that only the redeployments can be performed in offline mode. The initial program deployment must be performed from an online machine, and only subsequent program redeployments can leverage offline signing.

A typical setup would consist of two different signers:

online signer (fee payer and authority of the buffer account)
offline signer (authority of the program account)

The general process is a two-step redeployment with some extras:

(online) create a new program
(online) transfer the authority to the offline signer
(online) create buffer and upload an executable to it
(optional) verify the buffer's on-chain contents
(offline) sign a transaction to redeploy the program using the buffer --blockhash <VALUE> --sign-only
(online) use this signature to broadcast the redeployment transaction --blockhash <VALUE> --signer <OFFLINE_SIGNER_PUBKEY>:<OFFLINE_SIGNER_SIGNATURE>

Look up a recent blockhash and paste it in to generate the offline transaction signature. The blockhash expires after ~60 seconds. If you didn't make it in time - just get another fresh hash and repeat until you succeed, or consider using durable transaction nonces.

Table of Contents