From 1101f0c524d73e6a5f113ceba5035d4211885f3e Mon Sep 17 00:00:00 2001 From: saubyk <39208279+saubyk@users.noreply.github.com> Date: Fri, 2 Oct 2026 11:46:38 -0700 Subject: [PATCH 1/2] lndclient: warn if connected lnd version is unsupported The lnd project only supports its current and previous major release. The version check only enforces the minimum version requested by the caller, which can be lowered through the CheckVersion config option. Log a warning if the connected node passes that check but is older than the oldest version still supported by lnd, without refusing the connection. Co-Authored-By: Claude Fable 5.1 --- lnd_services.go | 24 ++++++++++++++ lnd_services_test.go | 76 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+) diff --git a/lnd_services.go b/lnd_services.go index 51090378..7503f389 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 4a239759..06e3d8c1 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) { From 29fe8771f7a9c25bfdb2c3c5782a0f3be720c39e Mon Sep 17 00:00:00 2001 From: saubyk <39208279+saubyk@users.noreply.github.com> Date: Fri, 2 Oct 2026 11:46:44 -0700 Subject: [PATCH 2/2] README: document supported lnd versions Mark which entries of the compatibility matrix still require a supported version of lnd and describe the warning that is logged when connecting to an unsupported node. Co-Authored-By: Claude Fable 5.1 --- README.md | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 83697306..8cf0f9e4 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