diff --git a/README.md b/README.md index 8369730..8cf0f9e 100644 --- a/README.md +++ b/README.md @@ -24,11 +24,24 @@ different versions. There are two "levels" of depending on a version of The current compatibility matrix reads as follows: -| tag | `lnd` version in `go.mod` | minimum required `lnd` version | -|--------------|---------------------------|--------------------------------| -| `v0.18.5-13` | `v0.18.5-beta` | `v0.18.5-beta` | -| `v0.20.0-4` | `v0.20.0-beta` | `v0.19.0-beta` | -| `v0.21.0-1` | `v0.21.0-beta` | `v0.21.0-beta` | +| tag | `lnd` version in `go.mod` | minimum required `lnd` version | minimum is a supported `lnd` version | +|--------------|---------------------------|--------------------------------|--------------------------------------| +| `v0.20.0-4` | `v0.20.0-beta` | `v0.19.0-beta` | no | +| `v0.21.0-1` | `v0.21.0-beta` | `v0.21.0-beta` | yes | + +### Supported `lnd` versions + +The `lnd` project only supports its current and its previous major release, +which at the moment are `v0.21.x-beta` and `v0.20.x-beta`. Older versions of +`lnd` no longer receive fixes and should not be used, even if a tag of this +library still accepts them (see the last column of the matrix above). + +The version check only enforces the minimum required version, which users of +`lndclient` can lower when creating a new client. To make sure an unsupported +node doesn't go unnoticed in that case, `lndclient` logs a warning when the +connected `lnd` is older than the oldest supported version, as defined in +`oldestSupportedVersion` in [`lnd_services.go`](lnd_services.go). The +connection itself is not refused. By default, `lndclient` requires (and enforces) the following RPC subservers to diff --git a/lnd_services.go b/lnd_services.go index 5109037..7503f38 100644 --- a/lnd_services.go +++ b/lnd_services.go @@ -46,6 +46,19 @@ var ( BuildTags: DefaultBuildTags, } + // oldestSupportedVersion is the oldest version of lnd that is still + // supported by the lnd project, which only maintains the current and + // the previous major release. Callers can still connect to an older + // node by lowering the required version through the CheckVersion + // config option, but a warning is logged in that case. This needs to + // be bumped whenever lndclient is updated to a new major release of + // lnd. + oldestSupportedVersion = &verrpc.Version{ + AppMajor: 0, + AppMinor: 20, + AppPatch: 0, + } + // ErrVersionCheckNotImplemented is the error that is returned if the // version RPC is not implemented in lnd. This means the version of lnd // is lower than v0.10.0-beta. @@ -891,6 +904,17 @@ func checkVersionCompatibility(client VersionerClient, return nil, err } + // The version requested by the caller might be lower than what is + // still supported by the lnd project. We don't refuse the connection + // in that case but make sure it doesn't go unnoticed. + err = AssertVersionCompatible(version, oldestSupportedVersion) + if err != nil { + log.Warnf("Connected lnd version %v is no longer supported "+ + "by the lnd project, please upgrade to at least %v", + VersionStringShort(version), + VersionStringShort(oldestSupportedVersion)) + } + // All check positive, version is fully compatible. return version, nil } diff --git a/lnd_services_test.go b/lnd_services_test.go index 4a23975..06e3d8c 100644 --- a/lnd_services_test.go +++ b/lnd_services_test.go @@ -1,11 +1,13 @@ package lndclient import ( + "bytes" "context" "errors" "testing" "time" + "github.com/btcsuite/btclog/v2" "github.com/lightningnetwork/lnd/lnrpc" "github.com/lightningnetwork/lnd/lnrpc/verrpc" "github.com/stretchr/testify/require" @@ -91,6 +93,80 @@ func TestCheckVersionCompatibility(t *testing.T) { } } +// TestUnsupportedVersionWarning makes sure a warning is logged if the connected +// lnd passes the version check requested by the caller but is older than the +// oldest version still supported by the lnd project. +func TestUnsupportedVersionWarning(t *testing.T) { + testCases := []struct { + name string + actual *verrpc.Version + expectWarn bool + }{ + { + name: "older than oldest supported version", + actual: &verrpc.Version{ + AppMajor: oldestSupportedVersion.AppMajor, + AppMinor: oldestSupportedVersion.AppMinor - 1, + AppPatch: 3, + }, + expectWarn: true, + }, + { + name: "oldest supported version", + actual: oldestSupportedVersion, + expectWarn: false, + }, + { + name: "newer than oldest supported version", + actual: &verrpc.Version{ + AppMajor: oldestSupportedVersion.AppMajor, + AppMinor: oldestSupportedVersion.AppMinor + 1, + AppPatch: 0, + }, + expectWarn: false, + }, + } + + for _, tc := range testCases { + t.Run(tc.name, func(t *testing.T) { + // Capture everything that is logged on warning level or + // above for the duration of the test. + var logOutput bytes.Buffer + testLogger := btclog.NewSLogger( + btclog.NewDefaultHandler(&logOutput), + ) + testLogger.SetLevel(btclog.LevelWarn) + + oldLogger := log + UseLogger(testLogger) + t.Cleanup(func() { + UseLogger(oldLogger) + }) + + // The caller explicitly accepts any version, so the + // check itself must always succeed. + client := &mockVersioner{version: tc.actual} + version, err := checkVersionCompatibility( + client, &verrpc.Version{}, + ) + require.NoError(t, err) + require.Equal(t, tc.actual, version) + + if !tc.expectWarn { + require.Empty(t, logOutput.String()) + + return + } + + require.Contains(t, logOutput.String(), "[WRN]") + require.Contains( + t, logOutput.String(), + VersionStringShort(tc.actual), + ) + }) + } +} + // TestLndVersionCheckComparison makes sure the version check comparison works // correctly and considers all three version levels. func TestLndVersionCheckComparison(t *testing.T) {