elements: Require 23.3.1 on Liquid

Author: YusukeShimizu

README.md

@@ -70,6 +70,9 @@ To run Elements for L-BTC swaps, see the [Elements setup guide](./docs/setup_ele
 
 To run LWK for L-BTC swaps, see the [LWK setup guide](./docs/setup_lwk.md).
 
+> **Important**
+> Liquid mainnet L-BTC swaps require a backend that follows the post-[ELIP 203](https://raw.githubusercontent.com/ElementsProject/ELIPs/main/elip-0203.mediawiki) chain tip. When using Elements RPC, run Elements 23.3.1 or newer; Elements 23.3.3 is recommended.
+
 > **Note**
 > Most of the benefits of PeerSwap come from using L-BTC. Swaps using L-BTC are more private, faster, and avoid the mainchain blockchain during high fee environments that can make swaps uneconomical.
 

docs/setup_elementsd.md

@@ -17,7 +17,7 @@ If you would rather just download the binary instead, skip to the next section.
 
 Download the `elementsd` binary release [here](https://github.com/ElementsProject/elements/releases). 
 > [!IMPORTANT]
-> The minimum required version for peerswap is now updated to Elements 23.2.5. Please ensure you are using this version or later to maintain compatibility and functionality. You can find the release details here: [Elements 23.2.5](https://github.com/ElementsProject/elements/releases/tag/elements-23.2.5).
+> Liquid mainnet L-BTC swaps require Elements 23.3.1 or newer. Elements 23.3.3 is the recommended stable release. The [ELIP 203](https://raw.githubusercontent.com/ElementsProject/ELIPs/main/elip-0203.mediawiki) Liquid mainnet hard fork is active, and older `elementsd` versions cannot follow the post-fork chain. You can find current binaries on the [Elements releases](https://github.com/ElementsProject/elements/releases) page.
 
 Extract the archive
 
@@ -27,6 +27,19 @@ Copy the binaries to your PATH
 
 `cp elements*/elementsd elements*/elements-cli /usr/local/bin`
 
+Confirm the installed version:
+
+`elements-cli --version`
+
+For Liquid mainnet, confirm that your node follows the post-fork chain tip:
+
+`elements-cli -chain=liquidv1 getblockchaininfo`
+
+Check that `blocks` is close to `headers` and that `verificationprogress` shows the node is synced. If `blocks` stops advancing on Liquid mainnet, upgrade `elementsd` before using L-BTC swaps.
+
+> **Note**
+> [ELIP 201](https://raw.githubusercontent.com/ElementsProject/ELIPs/main/elip-0201.mediawiki) is not the Liquid hard fork that requires the `elementsd` upgrade. The consensus-affecting hard fork is ELIP 203.
+
 
 ## Configuring
 
@@ -83,4 +96,3 @@ To create a new Liquid receiving address:
 To send L-BTC to a Liquid address:
 
 `elements-cli -rpcwallet=peerswap sendtoaddress [address] [amount in decimal form, e.g. 0.1 for 0.10000000 L-BTC]`
-

docs/setup_lwk.md

@@ -5,6 +5,9 @@ To set up `lwk` for PeerSwap, follow the steps here.
 lwk is currently under development and changes are being made.  
 **peerswap has been tested only with [cli_0.5.1](https://github.com/Blockstream/lwk/releases/tag/cli_0.5.1)**.
 
+> [!IMPORTANT]
+> Liquid mainnet L-BTC swaps require the LWK/Electrum backend to follow the post-[ELIP 203](https://raw.githubusercontent.com/ElementsProject/ELIPs/main/elip-0203.mediawiki) chain tip. If you run your own backend, make sure it is backed by an Elements node that supports the active Liquid mainnet hard fork.
+
 ## wallet
 peerswap assumes a wallet with blinding-key set in singlesig to lwk.
 
@@ -31,7 +34,7 @@ lwk_cli server start
 ```
 
 ## electrum
-peerswap uses [esplora-electrs](https://github.com/Blockstream/electrs) to communicate with the luqiud chain.  
+peerswap uses [esplora-electrs](https://github.com/Blockstream/electrs) to communicate with the Liquid chain.
 By default, peerswap connects to `blockstream.info:995` used by lwk, so no configuration is needed.
 
 If you want to use your own chain, follow the instructions in [esplora-electrs](https://github.com/Blockstream/electrs) to start Electrum JSON-RPC server.
@@ -63,4 +66,4 @@ signername="signername"
 walletname="walletname"
 network="liquid"
 liquidswaps=true
-```
+```

elements/client.go

@@ -1,13 +1,23 @@
 package elements
 
 import (
+	"fmt"
 	"strings"
 	"time"
 
 	"github.com/elementsproject/glightning/gelements"
 	"github.com/elementsproject/peerswap/log"
 )
 
+const (
+	liquidMainnetChain = "liquidv1"
+
+	minLiquidMainnetElementsVersion           = 230301
+	minLiquidMainnetElementsVersionString     = "23.3.1"
+	recommendedLiquidMainnetElementsVersion   = "23.3.3"
+	unsupportedLiquidMainnetElementsErrorText = "unsupported elementsd version for Liquid mainnet"
+)
+
 type ElementsClientBuilder struct {
 }
 
@@ -34,11 +44,18 @@ func NewClient(rpcUser, rpcPassword, rpcHost, RpcPasswordFile string, rpcPort ui
 	}
 
 	backoff = 1
+	versionChecked := false
 	for {
 		info, err := c.GetChainInfo()
 		if err != nil {
 			return nil, err
 		}
+		if !versionChecked {
+			if err := checkLiquidMainnetElementsVersion(c, info.Chain); err != nil {
+				return nil, err
+			}
+			versionChecked = true
+		}
 		if info.VerificationProgress < 1. {
 			// Waiting for block verification to catch up.
 			log.Infof("Elementsd still syncing, progress: %f", info.VerificationProgress)
@@ -49,3 +66,35 @@ func NewClient(rpcUser, rpcPassword, rpcHost, RpcPasswordFile string, rpcPort ui
 		return c, nil
 	}
 }
+
+func checkLiquidMainnetElementsVersion(c *gelements.Elements, chain string) error {
+	if chain != liquidMainnetChain {
+		return nil
+	}
+	info, err := c.GetNetworkInfo()
+	if err != nil {
+		return err
+	}
+	return validateLiquidMainnetElementsVersion(chain, info.Version, info.Subversion)
+}
+
+func validateLiquidMainnetElementsVersion(chain string, version int, subversion string) error {
+	if chain != liquidMainnetChain || version >= minLiquidMainnetElementsVersion {
+		return nil
+	}
+
+	return fmt.Errorf(
+		"%s: Liquid mainnet requires elementsd %s or newer after ELIP 203; "+
+			"detected version %s (%s). Upgrade to Elements %s or newer, preferably %s",
+		unsupportedLiquidMainnetElementsErrorText,
+		minLiquidMainnetElementsVersionString,
+		formatElementsVersion(version),
+		subversion,
+		minLiquidMainnetElementsVersionString,
+		recommendedLiquidMainnetElementsVersion,
+	)
+}
+
+func formatElementsVersion(version int) string {
+	return fmt.Sprintf("%d.%d.%d", version/10000, version/100%100, version%100)
+}

elements/client_test.go

@@ -0,0 +1,76 @@
+package elements
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestValidateLiquidMainnetElementsVersion(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name       string
+		chain      string
+		version    int
+		subversion string
+		wantErr    bool
+	}{
+		{
+			name:       "liquid mainnet rejects 23.2.5",
+			chain:      liquidMainnetChain,
+			version:    230205,
+			subversion: "/Elements Core:23.2.5/",
+			wantErr:    true,
+		},
+		{
+			name:       "liquid mainnet accepts 23.3.1",
+			chain:      liquidMainnetChain,
+			version:    230301,
+			subversion: "/Elements Core:23.3.1/",
+		},
+		{
+			name:       "liquid mainnet accepts 23.3.3",
+			chain:      liquidMainnetChain,
+			version:    230303,
+			subversion: "/Elements Core:23.3.3/",
+		},
+		{
+			name:       "liquid testnet does not enforce mainnet minimum",
+			chain:      "liquidtestnet",
+			version:    230205,
+			subversion: "/Elements Core:23.2.5/",
+		},
+		{
+			name:       "liquid regtest does not enforce mainnet minimum",
+			chain:      "liquidregtest",
+			version:    230205,
+			subversion: "/Elements Core:23.2.5/",
+		},
+	}
+
+	for _, tt := range tests {
+		tt := tt
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := validateLiquidMainnetElementsVersion(tt.chain, tt.version, tt.subversion)
+			if (err != nil) != tt.wantErr {
+				t.Fatalf("validateLiquidMainnetElementsVersion() error = %v, wantErr %v", err, tt.wantErr)
+			}
+			if !tt.wantErr {
+				return
+			}
+
+			for _, want := range []string{
+				unsupportedLiquidMainnetElementsErrorText,
+				minLiquidMainnetElementsVersionString,
+				recommendedLiquidMainnetElementsVersion,
+				tt.subversion,
+			} {
+				if !strings.Contains(err.Error(), want) {
+					t.Fatalf("validateLiquidMainnetElementsVersion() error = %q, want substring %q", err, want)
+				}
+			}
+		})
+	}
+}