How to Verify a Program

This guide is meant to be a reference for developers who want to implement verified builds for their programs on Solana. We will cover what verified builds are, how to use them, special considerations, and best practices to ensure the authenticity of your program onchain.

What are verified builds? #

Verified builds ensure that the executable program you deploy to Solana’s network matches the source code in your repository. By doing this, developers and users can have confidence that the program running onchain corresponds exactly to the public codebase, promoting transparency and security.

The verification process involves comparing the hash of the onchain program with the hash of the locally built program from the source code. This ensures no discrepancies between the two versions.

The verified builds pipeline was thought out and is maintained by Ellipsis Labs and OtterSec. For more details, follow the guide in the original verified builds repository as well and the verify build process directly into the Anza tool suite, once supported there.

How does it work? #

The verification process is done by comparing the hash of the onchain program with the hash of the locally built program from the source code. You build your program in a controlled environment using the Solana Verify CLI and Docker. This ensures that the build process is deterministic and consistent across different systems. Once you have the executable, you can deploy it to the Solana network. During the build process a PDA of the verify program will be created. This PDA contains all the data necessary to verify the program. The PDA contains the program address, git url, commit hash and the arguments used to build the program.

Using the data in the PDA everyone can run the verify program command locally and check if the program was built from the provided source code. Then everyone can verify for themselves completely trustlessly or can run their own verify API maintained by OtterSec to provide an easy access point for users to check the verification. You can already see these API calls being used in the Solana Explorer and SolanaFM, among other places.

Why should I use verified builds? #

Using verified builds provides the following benefits:

• Security: Guarantee that the program running onchain matches the source code, preventing malicious alterations.

• Transparency: Allows other users and developers to validate that the onchain program is trustworthy by comparing it with the public codebase.

• Trust: Increase user confidence, as verified builds demonstrate that your program's onchain behavior is aligned with your public code. When building verifiable programs, you minimize risks associated with running unauthorized or malicious code. It also ensures you comply with best practices and give security researchers an easy way to contact you.

How do I create verified builds? #

To create verified builds, you'll need to follow these steps:

Summary:

• Commit your code to a public repository
• Build a verified build in docker
• Deploy the verified build
• Verify the deployed program against public API

If you verify your program which is not build in a docker container it will most likely fail because Solana program builds are not deterministic across different systems.

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

cargo install solana-verify

cargo install solana-verify --version $VERSION

cargo install solana-verify --git https://github.com/Ellipsis-Labs/solana-verifiable-build --rev 13a1db2

[workspace]
members = ["program/programs/*"]
resolver = "2"
[profile.release]
overflow-checks = true
lto = "fat"
codegen-units = 1
 
[profile.release.build-override]
opt-level = 3
incremental = false
codegen-units = 1

solana-verify build

solana-verify build --library-name $PROGRAM_LIB_NAME

solana-verify get-executable-hash target/deploy/$PROGRAM_LIB_NAME.so

solana program deploy -u $NETWORK_URL target/deploy/$PROGRAM_LIB_NAME.so --program-id $PROGRAM_ID --upgrade-authority $UPGRADE_AUTHORITY

solana-verify get-program-hash -u $NETWORK_URL $PROGRAM_ID

solana-verify verify-from-repo -u $NETWORK_URL --program-id $PROGRAM_ID https://github.com/$REPO_PATH --commit-hash $COMMIT_HASH --library-name $PROGRAM_LIB_NAME --mount-path $MOUNT_PATH

solana-verify verify-from-repo --remote -um --program-id PhoeNiXZ8ByJGLkxNfZRnkUfjvmuYqLR89jjFHGqdXY https://github.com/Ellipsis-Labs/phoenix-v1

Example verified build #

Here’s an example of verifying the solana-games-preset with the ID MkabCfyUD6rBTaYHpgKBBpBo5qzWA2pK2hrGGKMurJt using the source code from the repository:

solana-verify verify-from-repo -url https://api.mainnet-beta.solana.com --program-id MkabCfyUD6rBTaYHpgKBBpBo5qzWA2pK2hrGGKMurJt https://github.com/solana-developers/solana-game-preset --library-name lumberjack --mount-path program --commit-hash eaf772fd1f21fe03a9974587f5680635e970be38

By default the verify-from-repo command takes the last commit on the main branch. You can also define a certain commit in case you want to continue working on the repository by using the commit-hash parameter: --commit-hash eaf772fd1f21fe03a9974587f5680635e970be38

You can also verify using Docker images for faster verification:

solana-verify verify-from-image -e examples/hello_world/target/deploy/hello_world.so -i ellipsislabs/hello_world_verifiable_build:latest -p 2ZrriTQSVekoj414Ynysd48jyn4AX6ZF4TTJRqHfbJfn

Finally you can also directly verify the program against the OtterSec API:

solana-verify verify-from-repo --remote -um --program-id PhoeNiXZ8ByJGLkxNfZRnkUfjvmuYqLR89jjFHGqdXY https://github.com/Ellipsis-Labs/phoenix-v1

The --remote command sends a build request to the OtterSec API, which triggers a remote build of your program. Once the build is complete, the system verifies that the onchain hash of your program matches the hash of the generated build artifact from your repository.

Conclusion #

Using verified builds on Solana ensures the integrity and trustworthiness of your programs on the network. By leveraging tools like the Solana Verify CLI and Docker, you can maintain verifiable and secure builds that align with your source code. Always take the necessary precautions to use consistent environments, and consider governance solutions for safe upgrades and deployments.

Security + Disclaimer #

While verified builds are a powerful tool for ensuring the integrity of your Solana programs it is not completely trustless in the default setup. The docker images are build and hosted by the Ellipsis Labs team and the Solana Foundation.

Be aware that you are building your project in a downloaded docker image and that your whole setup gets copied into that docker image for building including potentially sensitive information.

If you want to have a completely trustless setup you can build the docker images yourself and host them on your own infrastructure. This way you can be sure that the docker images are not tampered with. You can find the scripts to create your own docker images in the Verified builds repository.

Furthermore for the remote verification you are trusting the OtterSec API and the Solana Explorer to a certain degree.

The API and the Solana Explorer could potentially be compromised and show you false information.

If you want to have a completely trustless setup you can run the Verify API yourself or run the program verification locally yourself using the verify-from-repo command using the on chain verify data that is saved in a PDA that is derived from the programs deploy authority and the verify program.

The verify program is deployed by the OtterSec team and is not yet frozen so it can be upgraded at any time.

The Solana Foundation, OtterSec and the Ellipsis Labs team are not responsible for any losses or damages that may occur from using the verified builds pipeline.

Security.txt for Solana programs #

In addition to verified builds you can also add a security.txt file to your program. In the future, once implemented, the security.txt will hold the verifier public key for easy access to the verification data stored in the verification PDA. The PDA containing all the information needed to build and verify a program is derived from the programs address and the verifier pubkey. By default this is the same pubkey that built and deployed the program. But it can also be another pubkey that can be specified in the security.txt.

The security.txt feature allows developers to embed contact and security information directly within their Solana smart contracts. Inspired by securitytxt.org, this approach provides a standardized way for security researchers to reach out to project maintainers, even if they only know the contract's address.

Why use security.txt? #

For many projects, especially smaller or private ones, identifying the developers from just the contract address can be difficult and time-consuming. Embedding a security.txt file within the program ensures that security researchers can easily contact the correct people, potentially preventing exploits and ensuring timely bug reports.

How to implement security.txt #

To add a security.txt to your Solana program, include the following steps:

Add the solana-security-txt dependency to your Cargo.toml:

[dependencies]
solana-security-txt = "1.1.1"

Use the security_txt! macro in your contract to define your security information. You can include contact details, project URLs, and even a security policy. Here's an example:

#[cfg(not(feature = "no-entrypoint"))]
use {default_env::default_env, solana_security_txt::security_txt};
 
#[cfg(not(feature = "no-entrypoint"))]
security_txt! {
    name: "MyProject",
    project_url: "https://myproject.com",
    contacts: "email:security@myproject.com,discord:security#1234",
    policy: "https://myproject.com/security-policy",
 
    // Optional Fields
    preferred_languages: "en,de",
    source_code: "https://github.com/solana-developers/solana-game-preset",
    source_revision: "5vJwnLeyjV8uNJSp1zn7VLW8GwiQbcsQbGaVSwRmkE4r",
    source_release: "",
    encryption: "",
    auditors: "Verifier pubkey: 5vJwnLeyjV8uNJSp1zn7VLW8GwiQbcsQbGaVSwRmkE4r",
    acknowledgements: "Thank you to our bug bounty hunters!"
}

Once the security.txt information is embedded in your program, it can be easily queried via tools like the Solana Explorer, ensuring that your contact and security details are available to anyone looking to report potential issues.

Best practices #

• Use Links: For information likely to change (e.g., contact details), it's recommended to link to a web page rather than hard-coding them into the contract. This avoids the need for frequent program upgrades.

• Verification: Before deploying, verify the format and content using the query-security-txt tool, which can validate both onchain programs and local binaries:

query-security-txt target/bpfel-unknown-unknown/release/my_contract.so

By embedding security contact information directly into your contract, you make it easier for researchers to reach you, fostering better security and communication within the Solana ecosystem.

This is an example of how security.txt looks in the Solana Explorer

The security.txt project is maintained by Neodyme Labs