> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/solana-foundation/anchor/llms.txt
> Use this file to discover all available pages before exploring further.

# Verifiable Builds

> Learn how to create and verify deterministic builds of Anchor programs using Docker for reproducible deployments.

Verifiable builds ensure that the binary deployed on-chain can be independently reproduced from source code. This is critical for security audits and establishing trust in deployed programs.

## Why Verifiable Builds?

Building Solana programs with the standard toolchain can embed machine-specific information into the resulting binary. This means:

* Building the same source code on different machines produces different binaries
* It's impossible to verify that deployed code matches the published source
* Auditors cannot confirm the on-chain program matches reviewed code

Verifiable builds solve this by building inside a Docker container with pinned dependencies, ensuring identical outputs regardless of the build environment.

## Prerequisites

Before creating verifiable builds, install Docker:

* **macOS/Windows**: [Docker Desktop](https://docs.docker.com/get-docker/)
* **Linux**: [Docker Engine](https://docs.docker.com/engine/install/)

Verify Docker is running:

```shell theme={null}
docker --version
```

## Building with --verifiable

Anchor handles all Docker operations automatically. To create a verifiable build:

```shell theme={null}
anchor build --verifiable
```

This command:

1. Pulls the official Anchor Docker image for your version
2. Mounts your project directory into the container
3. Builds your program(s) in the isolated environment
4. Outputs the compiled `.so` files to `target/verifiable/`

<Callout type="info">
  The first verifiable build downloads the Docker image (\~1-2 GB) which may take several minutes. Subsequent builds are much faster.
</Callout>

### Build Output

Verifiable builds create additional output:

```
project/
├── target/
│   ├── deploy/              # Standard builds
│   │   └── program.so
│   └── verifiable/          # Verifiable builds
│       └── program.so
│   └── idl/
│       └── program.json
```

## Verifying Deployed Programs

To verify that a deployed program matches your local build:

```shell theme={null}
anchor verify -p <lib-name> <program-id>
```

Where:

* `<lib-name>`: The library name from your program's `Cargo.toml`
* `<program-id>`: The on-chain program address

### Example

```shell theme={null}
# Verify a program on mainnet
anchor verify -p my_program Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS
```

The verification process:

1. Builds your program verifiably
2. Fetches the deployed program binary from the blockchain
3. Compares the two binaries byte-by-byte
4. If an IDL exists, verifies the on-chain IDL matches your local version

### Verification Output

**Success:**

```shell theme={null}
✔ Successfully verified program my_program
  On-chain program hash: abc123...
  Built program hash:    abc123...
  IDL hash:             def456...
```

**Failure:**

```shell theme={null}
✖ Verification failed for program my_program
  On-chain hash: abc123...
  Built hash:    xyz789...
  
  The deployed program does not match your local build.
```

## Docker Images

Anchor publishes official Docker images on [Docker Hub](https://hub.docker.com/r/solanafoundation/anchor) for each release.

### Image Tags

Images follow the format: `solanafoundation/anchor:v<version>`

```shell theme={null}
# Pull a specific version
docker pull solanafoundation/anchor:v0.32.1

# List locally available images
docker images | grep anchor
```

### Image Contents

Each image includes:

* Anchor CLI (matching version)
* Solana CLI tools
* Rust toolchain (specific version)
* Build dependencies

## Specifying Versions

Control which versions are used for verifiable builds through `Anchor.toml`:

```toml title="Anchor.toml" theme={null}
[toolchain]
anchor_version = "0.32.1"    # Anchor CLI version
solana_version = "2.3.0"     # Solana tools version
```

When you run `anchor build --verifiable`, Anchor uses the Docker image matching your specified `anchor_version`.

<Callout type="warning">
  If `anchor_version` is not specified in `Anchor.toml`, Anchor uses the version of your currently installed CLI, which may not match the deployed program.
</Callout>

## Advanced Usage

### Build Specific Programs

Build only certain programs from a multi-program workspace:

```shell theme={null}
anchor build --verifiable -p program_name
```

### Custom Docker Image

Use a custom Docker image for builds:

```shell theme={null}
anchor build --verifiable --docker-image custom/anchor:latest
```

### Source Code Verification

For building from a specific commit:

```shell theme={null}
# Checkout specific commit
git checkout <commit-hash>

# Build verifiably
anchor build --verifiable

# Verify against deployed program
anchor verify -p program_name <program-id>
```

## Troubleshooting

### Docker Container Issues

If a verifiable build is interrupted, the container may still be running:

```shell theme={null}
# List running containers
docker ps

# Remove the Anchor build container
docker rm -f anchor-program
```

### Disk Space

Docker images consume significant disk space. Clean up old images:

```shell theme={null}
# Remove unused images
docker image prune

# Remove specific Anchor image
docker rmi solanafoundation/anchor:v0.32.1
```

### Build Failures

**Dependency Resolution Issues:**

If builds fail due to dependency resolution, ensure your `Cargo.lock` is committed:

```shell theme={null}
git add Cargo.lock
git commit -m "Lock dependencies for verifiable builds"
```

**Version Mismatches:**

Verify your local Anchor version matches `Anchor.toml`:

```shell theme={null}
anchor --version
```

Use AVM to switch versions:

```shell theme={null}
avm use 0.32.1
```

### Permission Errors

On Linux, Docker may create files owned by root. Fix ownership:

```shell theme={null}
sudo chown -R $USER:$USER target/verifiable/
```

## CI/CD Integration

Integrate verifiable builds into your deployment pipeline:

### GitHub Actions Example

```yaml title=".github/workflows/verifiable-build.yml" theme={null}
name: Verifiable Build

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Anchor
        run: |
          cargo install --git https://github.com/coral-xyz/anchor anchor-cli --locked --force
      
      - name: Run verifiable build
        run: anchor build --verifiable
      
      - name: Upload artifacts
        uses: actions/upload-artifact@v3
        with:
          name: verifiable-builds
          path: target/verifiable/
```

## Best Practices

<AccordionGroup>
  <Accordion title="Always Use Verifiable Builds for Production">
    Never deploy programs built without the `--verifiable` flag to mainnet:

    ```shell theme={null}
    # Production deployment
    anchor build --verifiable
    anchor deploy --provider.cluster mainnet
    ```
  </Accordion>

  <Accordion title="Pin All Versions">
    Specify exact versions in `Anchor.toml` to ensure reproducibility:

    ```toml theme={null}
    [toolchain]
    anchor_version = "0.32.1"  # Not "0.32" or "latest"
    solana_version = "2.3.0"   # Not "2.3" or "latest"
    ```
  </Accordion>

  <Accordion title="Commit Cargo.lock">
    Always commit your `Cargo.lock` file:

    ```gitignore theme={null}
    # .gitignore
    # Cargo.lock  # <- DO NOT IGNORE for programs
    ```

    This ensures dependency versions are locked across all builds.
  </Accordion>

  <Accordion title="Document Build Instructions">
    Include verification steps in your README:

    ```markdown theme={null}
    ## Verification

    To verify the deployed program matches this repository:

    1. Checkout the deployment commit: `git checkout abc123`
    2. Build: `anchor build --verifiable`
    3. Verify: `anchor verify -p program_name PROGRAM_ID`
    ```
  </Accordion>

  <Accordion title="Test Verification Before Deployment">
    Verify the build process works before deploying:

    ```shell theme={null}
    # Build verifiably
    anchor build --verifiable

    # Deploy to devnet first
    anchor deploy --provider.cluster devnet

    # Verify the devnet deployment
    anchor verify -p program_name <devnet-program-id>
    ```
  </Accordion>
</AccordionGroup>

## Security Considerations

* **Source Code Availability**: Publish your source code in a public repository
* **Commit Hash**: Document which commit corresponds to deployed versions
* **Build Reproducibility**: Test that multiple people can reproduce your build
* **Upgrade Authority**: Consider program upgradeability when planning verifiable deployments

## Resources

* [Anchor Docker Images](https://hub.docker.com/r/solanafoundation/anchor)
* [Solana Program Verification](https://docs.solana.com/cli/deploy-a-program#verify-a-program)
* [Docker Documentation](https://docs.docker.com/)