vls-core 0.10.0

A library for implementing a Lightning signer, which externalizes and secures cryptographic operations.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

# Validating Lightning Signer

Please see the
[VLS Project Overview](https://gitlab.com/lightning-signer/docs/-/blob/master/README.md)
for more information.  Our [web site](https://vls.tech/).

## 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](./vls-protocol)
- a `no_std` protocol handler for VLS - in [./vls-protocol-signer](vls-protocol-signer/README.md)
- a replacement for the UNIX CLN `hsmd` binary, implemented in Rust in [./vls-proxy](./vls-proxy).

## Development Information

[Additional HOWTO Documentation](./contrib/howto/README.md)

### 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](https://github.com/SimonKagstrom/kcov) for Code Coverage

Dependencies:

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

or
    
    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.