Validating Lightning Signer

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

Limitations

The following remain to be implemented:

vlsd2 --recover-to can only handle a simple force-close by us. It cannot sweep a force-close or a breach by the peer. It also cannot sweep HTLC outputs.
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

Additional HOWTO Documentation

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

Running Unit Tests

cargo test

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

RUST_LOG=trace cargo test

Using kcov for Code Coverage

Dependencies:

sudo dnf install -y elfutils-devel curl-devel binutils-devel

sudo apt-get install -y libcurl4-openssl-dev libelf-dev libdw-dev binutils-dev libiberty-dev

Build v38 of kcov from git@github.com:SimonKagstrom/kcov.git .

Ensure kcov --verify /tmp/x a.out does not complain about libbfd.

More dependencies:

cargo install cargo-kcov
cargo install cargo-coverage-annotations

Run coverage:

./scripts/run-kcov
./scripts/run-kcov --lib
./scripts/run-kcov --test functional_test

View Coverage Report:

[target/kcov/cov/index.html](target/kcov/cov/index.html)

Benchmarks

Running Benchmarks

cargo bench -p vls-core --bench secp_bench

Note that you might need to add --features=test_utils if you want to run all benches in vls-core.

Without optimizations:

cargo bench -p vls-core --bench secp_bench --profile=dev

Expect something like:

test fib1_bench ... bench: 1 ns/iter (+/- 0) test fib_bench ... bench: 17,247 ns/iter (+/- 198) test hash_bench ... bench: 258 ns/iter (+/- 2) test secp_create_bench ... bench: 49,981 ns/iter (+/- 642) test sign_bench ... bench: 25,692 ns/iter (+/- 391) test verify_bench ... bench: 31,705 ns/iter (+/- 1,445)

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