Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 18 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
24 changes: 24 additions & 0 deletions lnd_services.go
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
}
Expand Down
76 changes: 76 additions & 0 deletions lnd_services_test.go
Original file line number Diff line number Diff line change
@@ -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"
Expand Down Expand Up @@ -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) {
Expand Down
Loading