Dev Environment Setup

A complete guide to configuring your development environment for building vProgs and Silverscript contracts on Kaspa.

Recommended Hardware

These specs cover running a local dev node, compiling the workspace, and generating ZK proofs during development.

ZK proving note: Generating ZK proofs locally is CPU-intensive. If you plan to run proving workloads frequently, 16+ cores and 64 GB RAM will significantly reduce proof generation times. For lighter development work (writing contracts, running unit tests), the minimum spec is sufficient.

macOS / Windows: Development is supported on macOS (Apple Silicon or Intel) and Windows via WSL2. Native Windows builds are not currently supported.

Rust Toolchain

vProgs and Silverscript are written in Rust and require the nightly toolchain.

Install Rust via rustup

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

Configure Nightly

source ~/.cargo/env   # Load rustup into the current shell
rustup default nightly
rustup component add rust-src rustfmt clippy
rustup target add wasm32-unknown-unknown  # For future WASM support

Verify Installation

rustc --version   # rustc 1.96.0-nightly (...)
cargo --version   # cargo 1.96.0-nightly (...)

Additional Build Dependencies

Repository Structure

The vProgs ecosystem is a layered Rust monorepo where each crate has a single responsibility. Dependencies flow strictly downward.

vprogs/
  core/                     # Fundamental types, hashing, serialization
    src/
      types.rs              # Core data types (AccountId, StateRoot, Proof)
      hash.rs               # Blake3 hashing primitives
      serialization.rs      # Borsh serialization
  storage/                  # Database abstraction layer
    src/
      db.rs                 # Storage traits
      rocksdb_backend.rs    # RocksDB implementation
  state/                    # State management and Merkle trees
    src/
      merkle.rs             # Hierarchical Merkle commitments
      account.rs            # Account state model
      commitment.rs         # State commitment generation
  scheduling/               # Transaction ordering and scheduling
    src/
      scheduler.rs          # DAG-aware transaction scheduler
      lane.rs               # KIP-21 lane management
  transaction-runtime/      # Execution environment
    src/
      runtime.rs            # Transaction execution
      vm.rs                 # State transition validation
  node/                     # Full node binary
    src/
      main.rs               # Entry point
      rpc/                  # RPC server
      network/              # P2P networking

Key Architecture Principles

• Layered dependencies: core -> storage -> state -> scheduling -> transaction-runtime -> node
• No upward imports: Lower layers never depend on higher layers
• Single responsibility: Each crate owns exactly one concern
• Trait-based abstraction: Storage, networking, and proving are abstracted behind traits

IDE Setup

VS Code (Recommended)

Install these extensions:

Workspace Settings

Create .vscode/settings.json in the vProgs repo root:

{
    "rust-analyzer.cargo.features": "all",
    "rust-analyzer.check.command": "clippy",
    "rust-analyzer.procMacro.enable": true,
    "rust-analyzer.imports.granularity.group": "module",
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "rust-lang.rust-analyzer"
}

Launch Configuration

Create .vscode/launch.json for debugging:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "lldb",
            "request": "launch",
            "name": "Run vProgs Node (simnet)",
            "cargo": {
                "args": ["build", "--bin=vprogs-node", "--package=vprogs-node"],
                "filter": { "name": "vprogs-node", "kind": "bin" }
            },
            "args": ["--simnet"],
            "cwd": "${workspaceFolder}"
        },
        {
            "type": "lldb",
            "request": "launch",
            "name": "Run Tests",
            "cargo": {
                "args": ["test", "--no-run", "--lib"],
                "filter": { "kind": "lib" }
            },
            "cwd": "${workspaceFolder}"
        }
    ]
}

Silverscript Extension

[Coming Soon] A VS Code extension for Silverscript syntax highlighting and diagnostics is under development. Track progress in the Silverscript repo.

A DAP (Debug Adapter Protocol) debugger for Silverscript is in active development (see Silverscript repo).

SilverScript tooling has recently seen major leaps in developer experience, now supporting source-level debugging and complex state-transition test scenarios natively, making it drastically easier to build and test sophisticated contracts.

Development is set to resume on the SilverScript VS Code debugger extension, reinforcing the ecosystem’s focus on providing a premium developer experience (DevEx) for smart contract builders.

Local Testnet Configuration

Connecting to TN12

TN12 is the public Covenants++ testnet. See the Testnet Guide for full details.

# Run a vProgs node connected to TN12
cargo run --release --bin vprogs-node -- --testnet

Local Simnet

[Coming Soon] For isolated development, a local simnet mode is available:

# Start a local simnet node
cargo run --release --bin vprogs-node -- --simnet --listen 127.0.0.1:16111

# In another terminal, connect a second node
cargo run --release --bin vprogs-node -- --simnet --connect 127.0.0.1:16111

Useful CLI Commands

Cargo Commands

# Build the entire workspace
cargo build --release

# Build a specific crate
cargo build -p vprogs-core

# Run all tests
cargo test

# Run tests for a specific crate
cargo test -p vprogs-state

# Check for compilation errors without building
cargo check

# Format code
cargo fmt

# Run clippy lints
cargo clippy -- -D warnings

# Generate documentation
cargo doc --open

Silverscript CLI

# Compile a Silverscript contract
silverscript compile contract.ss --output contract.script

# Compile with debug info
silverscript compile contract.ss --debug

# Check syntax without compiling
silverscript check contract.ss

# [Coming Soon] Deploy to testnet
silverscript deploy contract.script --network testnet

Git Workflow

The vProgs repo uses a standard PR-based workflow:

# Create a feature branch
git checkout -b feature/my-covenant

# After making changes
cargo fmt && cargo clippy -- -D warnings && cargo test

# Push and create PR
git push -u origin feature/my-covenant

Project Configuration Files

rust-toolchain.toml

If not already present, create this in the repo root:

[toolchain]
channel = "nightly"
components = ["rustfmt", "clippy", "rust-src"]

.cargo/config.toml

Useful build optimizations:

[build]
# Use all available CPU cores
jobs = 0

[target.x86_64-unknown-linux-gnu]
rustflags = ["-C", "target-cpu=native"]

Next Steps

• Quickstart – Build and run your first project
• Your First vProg – Write a complete vProg
• Testnet Guide – Connect to TN12
• Developer Tools – CLI tools and debugging utilities

Build from Source

Build Pipeline Optimizations

Rusty-Kaspa’s build pipeline has been upgraded (PR #934) to use pre-built artifacts, drastically reducing build times for developers. This optimization was recently merged into the covpp-reset2 testnet, accelerating the development and testing cycle.

Furthermore, overall CI/CD pipeline stability has been bolstered. Developers have addressed recurring timeout errors in integration tests (e.g., via PR #937 by increasing notification timeouts), ensuring a more reliable development and testing process for ongoing protocol updates.