Developers can deploy on-chain programs (often called smart contracts elsewhere) with the Solana tools.
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
- Finalize the program by marking the program account executable.
Once deployed, anyone can execute the program by sending transactions that 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)
Successful deployment will return the program id of the deployed program, for example:
Specify the keypair in the deploy command to deploy to a specific program id:
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
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:
Showing a program account
To get information about a deployed program:
An example output looks like:
Program Idis the address that can be referenced in an instruction's
program_idfield when invoking a program.
ProgramData Addressis the account associated with the program account that holds the program's data (shared object).
Authorityis the program's upgrade authority.
Last Deployed In Slotis the slot in which the program was last deployed.
Data Lengthis the size of the space reserved for deployments. The actual space used by the currently deployed program may be less.
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.
The command looks the same as the deployment command:
By default, programs are deployed to accounts that are twice the size of the
original deployment. Doing so leaves room for program growth in future
redeployments. But, if the initially deployed program is very small (like a
simple helloworld program) and then later grows substantially, the redeployment
may fail. To avoid this, specify a
max_len that is at least the size (in
bytes) that the program is expected to become (plus some wiggle room).
Note that program accounts are required to be
rent-exempt, 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
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
Deployment failures will print an error message specifying the seed phrase needed to recover the generated intermediate buffer's keypair:
To recover the keypair:
When asked, enter the 12-word seed phrase.
Then issue a new
deploy command and specify the buffer:
Set a program's upgrade authority
The program's upgrade authority must to 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.
The authority can be specified during deployment:
Or after deployment and using the default keypair as the current authority:
Or after deployment and specifying the current authority:
A program can be marked immutable, which prevents all further redeployments, by
--final flag during deployment:
Or anytime after:
solana program deploy ... utilizes Solana's upgradeable loader, but there is
another way to deploy immutable programs using the original on-chain loader:
Programs deployed with
solana deploy ... are not redeployable and are not
compatible with the
solana program ... commands.
Dumping a program to a file
The deployed program may be dumped back to a local file:
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
dump command dumps the entire data space, which means the output file
will have trailing zeros after the shared object's data up to
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.
Using an intermediary Buffer account
Instead of deploying directly to the program account, the program can be written to an intermediary buffer account. Intermediary accounts can 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.
Buffer accounts support authorities like program accounts:
One exception is that buffer accounts cannot be marked immutable like program
accounts can, so they don't support
The buffer account, once entirely written, can be passed to
deploy to deploy
Note, the buffer's authority must match the program's upgrade authority.
Buffers also support
dump just like programs do.