Lock Files

The --lock-file flag allows you to include your project’s Scarb.lock file in the verification submission, ensuring reproducible builds by locking dependency versions to exactly match your deployment.

Overview

What is Scarb.lock?

Scarb.lock is a lock file generated by Scarb (the Cairo/Starknet package manager) that records the exact versions of all dependencies used in your project. Similar to Cargo.lock in Rust or package-lock.json in Node.js, it ensures that everyone building your project uses identical dependency versions.

Example Scarb.lock:

# This file is automatically generated by Scarb.
# It is not intended for manual editing.
version = 1

[[package]]
name = "my_contract"
version = "0.1.0"
dependencies = [
 "starknet",
]

[[package]]
name = "starknet"
version = "2.11.4"
source = "registry+https://scarb-registry.org/"
checksum = "abc123..."

Why Include Lock Files?

By default, the verifier excludes Scarb.lock from verification submissions. However, including it can be beneficial when:

1. Reproducible Builds - Ensure the remote compiler uses the exact same dependency versions you used locally
2. Version Pinning - Lock specific versions that are known to work with your contract
3. Debugging - Eliminate dependency version differences as a source of verification failures
4. Production Deployments - Guarantee that verified code matches deployed bytecode exactly

Usage

Command-Line Flag

Include Scarb.lock using the --lock-file flag:

voyager verify --network mainnet \
  --class-hash 0x044dc2b3239382230d8b1e943df23b96f52eebcac93efe6e8bde92f9a2f1da18 \
  --contract-name MyContract \
  --lock-file

Configuration File

Set it as default in .voyager.toml:

[voyager]
network = "mainnet"
license = "MIT"
lock-file = true  # Always include Scarb.lock

Then verify without the flag:

voyager verify --class-hash 0x044dc2b3... --contract-name MyContract

Priority System

The --lock-file flag follows the standard priority order:

1. CLI flag (--lock-file) - Highest priority
2. Config file (lock-file = true in .voyager.toml)
3. Default value (false - lock file not included)

When to Use Lock Files

Recommended Use Cases

1. Production Deployments

Always include lock files for production contracts:

voyager verify --network mainnet \
  --class-hash $PROD_CLASS_HASH \
  --contract-name ProductionContract \
  --lock-file \
  --watch

Why: Ensures verification uses the exact same dependencies as your deployment, preventing subtle differences that could cause verification to fail.

2. Reproducible Verification

When you need byte-for-byte reproducibility:

# .voyager.prod.toml
[voyager]
network = "mainnet"
license = "Apache-2.0"
lock-file = true  # Guarantee reproducibility
watch = false

Why: Lock files eliminate any ambiguity about which versions of dependencies should be used.

3. Debugging Verification Failures

If verification fails with dependency-related errors:

# First attempt (failed without lock file)
voyager verify --network mainnet --class-hash $HASH --contract-name MyContract
# Error: Compilation failed

# Retry with lock file
voyager verify --network mainnet --class-hash $HASH --contract-name MyContract --lock-file

Why: Including the lock file can resolve version mismatch issues between local and remote compilation.

4. Specific Dependency Versions

When using specific versions to work around bugs:

# Scarb.toml
[dependencies]
starknet = "2.11.2"  # Specific version due to known issue in 2.11.3

# Ensure remote uses same version
voyager verify --network mainnet \
  --class-hash $HASH \
  --contract-name MyContract \
  --lock-file

Why: Forces the remote compiler to use the same workaround versions.

When Lock Files Are Optional

1. Development/Testing

During active development, lock files may not be necessary:

# Quick verification during development
voyager verify --network sepolia \
  --class-hash $DEV_HASH \
  --contract-name DevContract
# No --lock-file flag

Why: Development often uses latest compatible versions, and exact reproducibility is less critical.

2. Simple Contracts

For contracts with minimal dependencies:

# Scarb.toml - simple contract
[dependencies]
starknet = ">=2.11.0"

# Verification without lock file usually works fine
voyager verify --network mainnet \
  --class-hash $HASH \
  --contract-name SimpleContract

Why: Fewer dependencies mean less chance of version conflicts.

3. Latest Dependency Versions

When you want to test against the latest versions:

# Explicitly exclude lock file (default behavior)
voyager verify --network sepolia \
  --class-hash $HASH \
  --contract-name TestContract

Why: Lets the remote compiler resolve to the latest compatible versions.

How It Works

Without Lock File (Default)

When --lock-file is not specified:

1. Verifier reads Scarb.toml to identify dependencies
2. Sends Scarb.toml to remote API
3. Remote compiler runs scarb build, which:
   • Resolves dependencies to latest compatible versions
   • Downloads dependencies from registry
   • Compiles your contract

Result: May use different dependency versions than your local build.

With Lock File

When --lock-file is specified:

1. Verifier reads both Scarb.toml and Scarb.lock
2. Sends both files to remote API
3. Remote compiler runs scarb build, which:
   • Uses exact versions from Scarb.lock
   • Downloads those specific versions
   • Compiles your contract

Result: Uses identical dependency versions to your local build.

File Location

The verifier looks for Scarb.lock in the same directory as Scarb.toml:

my_project/
├── Scarb.toml          # Always included
├── Scarb.lock          # Included only with --lock-file
└── src/
    └── lib.cairo

Workspace Projects

For workspace projects, the lock file is at the workspace root:

my_workspace/
├── Scarb.toml          # Workspace manifest
├── Scarb.lock          # Workspace lock file (included with --lock-file)
├── package1/
│   ├── Scarb.toml
│   └── src/
└── package2/
    ├── Scarb.toml
    └── src/

Lock File Validation

Missing Lock File

If --lock-file is specified but Scarb.lock doesn’t exist:

voyager verify --network mainnet \
  --class-hash $HASH \
  --contract-name MyContract \
  --lock-file

Warning: --lock-file specified but Scarb.lock not found
Continuing without lock file...

The verification proceeds without the lock file rather than failing.

Generating Lock Files

If you don’t have a Scarb.lock file, generate one:

# Generate lock file
scarb build

# Verify the lock file was created
ls Scarb.lock

# Now verify with lock file
voyager verify --network mainnet \
  --class-hash $HASH \
  --contract-name MyContract \
  --lock-file

Best Practices

1. Commit Lock Files to Version Control

Always commit Scarb.lock to your repository:

git add Scarb.lock
git commit -m "Add Scarb.lock for reproducible builds"

Why: Ensures all team members and CI/CD systems use identical dependencies.

2. Update Lock Files Intentionally

Don’t update Scarb.lock accidentally:

# Update dependencies intentionally
scarb update

# Review changes to lock file
git diff Scarb.lock

# Commit if changes are acceptable
git add Scarb.lock
git commit -m "Update dependencies"

Why: Prevents unexpected version changes that could break your build.

3. Use Lock Files in Production

Always use --lock-file for production deployments:

# .voyager.prod.toml
[voyager]
network = "mainnet"
lock-file = true  # Required for production
license = "Apache-2.0"

Why: Guarantees verification matches deployment.

4. Keep Lock Files Fresh

Periodically update dependencies to get security fixes:

# Update to latest compatible versions
scarb update

# Test locally
scarb test

# Deploy and verify with updated lock file
voyager verify --network mainnet \
  --class-hash $NEW_HASH \
  --contract-name MyContract \
  --lock-file

Why: Keeps your dependencies secure while maintaining reproducibility.

5. Document Lock File Usage

Document in your README when lock files should be used:

## Verification

### Production
Always verify production deployments with the lock file:
```bash
voyager verify --network mainnet \
  --class-hash $CLASS_HASH \
  --contract-name MyContract \
  --lock-file

Development

Lock file is optional during development.

## Configuration Examples

### Production Deployment

```toml
# .voyager.prod.toml
[voyager]
network = "mainnet"
license = "Apache-2.0"
lock-file = true      # Reproducible builds
watch = false
verbose = false

Staging/Testing

# .voyager.staging.toml
[voyager]
network = "sepolia"
license = "MIT"
lock-file = true      # Test with exact production dependencies
watch = true
verbose = true

Development

# .voyager.dev.toml
[voyager]
network = "sepolia"
license = "MIT"
lock-file = false     # Optional during development
watch = true
verbose = true
test-files = true

Troubleshooting

Verification Fails Without Lock File

Problem: Verification succeeds locally but fails remotely without --lock-file

Error: Compilation failed

Solution: Include the lock file to use exact dependency versions:

voyager verify --network mainnet \
  --class-hash $HASH \
  --contract-name MyContract \
  --lock-file \
  --verbose

Lock File Out of Date

Problem: Lock file doesn’t match Scarb.toml dependencies

Warning: Scarb.lock is out of date

Solution: Regenerate the lock file:

# Remove old lock file
rm Scarb.lock

# Regenerate from Scarb.toml
scarb build

# Verify
voyager verify --network mainnet \
  --class-hash $HASH \
  --contract-name MyContract \
  --lock-file

Dependency Version Conflicts

Problem: Lock file specifies versions incompatible with remote compiler

Error: Failed to resolve dependency: starknet = "2.8.0" (unsupported version)

Solution: Update dependencies to supported versions:

# Update dependencies
scarb update

# Verify compatible versions in Scarb.lock
cat Scarb.lock | grep -A 3 starknet

# Retry verification
voyager verify --network mainnet \
  --class-hash $HASH \
  --contract-name MyContract \
  --lock-file

Comparison with Test Files

See Also

• Test Files - Including test files in verification
• Configuration File Guide - Complete configuration system
• CLI Options Reference - All command-line flags
• Dry-Run Mode - Preview what files will be included
• Configuration Examples - Production configuration patterns