Validating Lightning Signer

Please see the VLS Project Overview for more information. Our web site.

Limitations

The following remain to be implemented:

• vlsd --recover-to can recover a holder force-close, including holder second-level HTLC transactions for supported commitment types. It does not yet handle recovery from counterparty force-closes or breach transactions.
• there is no facility to recover from loss of signer state.
• on-chain tracking is not fully implemented, so a malicious node can steal funds by failing to remedy a breach (for example)

Additional Crates

• a no_std VLS wire protocol encoder/decoder - in ./vls-protocol
• a no_std protocol handler for VLS - in ./vls-protocol-signer
• a replacement for the UNIX CLN hsmd binary, implemented in Rust in ./vls-proxy.

Development Information

Check out our Docs

For any large feature work make sure to consider whether it would require a VIP (VLS Improvement Proposal) or not.

Recommended Rust Version

We recommend using the nightly version of Rust only in specific cases, such as for cargo fmt and no-std. Otherwise, we explicitly recommend using the stable version.

Formatting Code

Enable formatting precommit hooks:

./scripts/enable-githooks

For some reason, the ignore configuration for rustfmt is only available on the nightly channel, even though it's documented as stable.

rustup install nightly

cargo +nightly fmt

Building Validating Lightning Signer

Build VLS and related crates:

cargo build

Workspace Structure

This is a Cargo workspace with multiple crates:

Workspace members (built with cargo build):

• Core: vls-core, vls-protocol, vls-protocol-signer, vls-persist, vls-frontend
• Integration: vls-proxy, vlsd, vls-cli
• Support: bolt-derive, vls-policy-derive, vls-util

Excluded crates (require special build steps):

• vls-signer-stm32 - STM32 microcontroller port (requires cargo +nightly-2026-02-26)
• embedded - Bare-metal implementation
• wasm - WebAssembly build
• lnrod - LDK-based Lightning node reference
• lightning-storage-server - Cloud storage service
• vls-core-test - Benchmarking utilities

Use ./scripts/build-all to build all crates including excluded ones.

Running Unit Tests

cargo test

To enable logging for a failing test (adjust log level to preference):

RUST_LOG=trace cargo test

Running System Tests

Some crates have system tests that require additional features:

cargo test --features system-test

For vls-proxy specifically:

cargo test --package vls-proxy --test frontend_system_test --features system-test

Important Feature Flags

When testing or developing, be aware of these feature flags:

vls-core:

• test_utils - Required for comprehensive testing (enables testing utilities)
• no-std - For embedded/bare-metal environments
• grpc - Auto-conversion to tonic::Status
• debug - Enable state tracing
• txoo-source - UTXO oracle integration

vls-protocol:

• developer - Test-only helpers and additional tests
• log-secrets - ⚠️ DANGEROUS: Prints secrets in debug output (never use in production)

Example:

cargo build --features system-test,redb-kvv
cargo test --package vls-core --features test_utils

Using llvm-cov for Code Coverage

Dependencies:

cargo +stable install cargo-llvm-cov --locked

Run coverage:

./scripts/run-llvm-cov

Changing linker to mold instead of ld:

cp .cargo/config.sample.toml .cargo/config.toml

Updating Dependencies

There are a few crates with lock files. You can update them all and view the results of cargo audit in one command:

scripts/update-all

Additional Development Scripts

The scripts/ directory contains helpful development tools:

• ./scripts/build-all - Build all crates including excluded ones (embedded, wasm, lnrod, etc.)
• ./scripts/build-nostd - Build no_std targets
• ./scripts/clean-all - Clean all build artifacts across workspace
• ./scripts/fmt-all - Format all crates with nightly rustfmt
• ./scripts/do-all - Run a command across all workspace members

Benchmarks

Running Benchmarks

cargo bench --manifest-path vls-core-test/Cargo.toml --bench secp_bench

Without optimizations:

cargo bench --manifest-path vls-core-test/Cargo.toml --bench secp_bench --profile=dev

Expect something like:

hash bench              time:   [116.14 ns 116.65 ns 117.29 ns]
                        change: [-3.5998% -2.8971% -2.0825%] (p = 0.00 < 0.05)
                        Performance has improved.
Found 14 outliers among 100 measurements (14.00%)
  3 (3.00%) high mild
  11 (11.00%) high severe

secp create bench       time:   [10.684 µs 10.721 µs 10.769 µs]
                        change: [-2.2977% -1.7787% -1.2637%] (p = 0.00 < 0.05)
                        Performance has improved.
Found 13 outliers among 100 measurements (13.00%)
  8 (8.00%) high mild
  5 (5.00%) high severe

i.e. around 30 microseconds per secp256k1 crypto operation. We also see that creating a secp context is expensive, but not prohibitively so.