Merge pull request #447 from YusukeShimizu/codex/update-elements-mainnet-requirement

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-nix.md

@@ -5,7 +5,7 @@ This document explains how to set up and maintain the Nix development environmen
 ## Overview
 
 PeerSwap uses Nix flakes for reproducible development environments and Cachix for fast binary caching. This setup provides:
-- Deterministic build environments across all platforms
+- Deterministic build environments on supported package platforms
 - Fast CI/CD builds through binary caching
 - Consistent developer experience
 
@@ -45,6 +45,44 @@ direnv allow
 # Without direnv (manual)
 nix develop
 ```
+
+> **Note**
+> The full daemon integration environment is Linux-oriented because it includes
+> Bitcoin Core, Elements, Core Lightning, LND, and related daemon dependencies.
+> On macOS, the full shell may fail to evaluate unsupported Linux-only packages.
+> Run end-to-end tests on Linux, matching CI.
+
+### Integration and E2E Tests
+
+The CI integration jobs run inside `nix-shell` on Linux. Use the same entry
+point locally on a Linux machine or CI-equivalent runner:
+
+```bash
+nix-shell --run "elementsd --version"
+nix-shell --run "make test-bins"
+```
+
+Run individual matrix targets with the same environment used in CI:
+
+```bash
+nix-shell --run "RUN_INTEGRATION_TESTS=1 PAYMENT_RETRY_TIME=10 PEERSWAP_TEST_FILTER=peerswap INTEGRATION_TEST_PARALLEL=6 make test-matrix-liquid_clncln"
+```
+
+Available matrix targets are:
+
+```text
+bitcoin_clncln
+bitcoin_mixed
+bitcoin_lndlnd
+liquid_clncln
+liquid_mixed
+liquid_lndlnd
+misc_1
+misc_2
+misc_3
+lnd
+```
+
 ### Binary Cache (Cachix)
 
 The project automatically uses the `peerswap` Cachix cache for faster builds. If you don't have Cachix installed:

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)
+				}
+			}
+		})
+	}
+}

flake.nix

@@ -62,15 +62,15 @@
 
             # Bitcoin/Elements daemons (used by integration tests / local networks).
             # Version checks:
-            # - `bitcoind --version` (bitcoind 30.0)
-            # - `elementsd --version` (elementsd 23.2.4)
+            # - `bitcoind --version` (bitcoind 31.0)
+            # - `elementsd --version` (elementsd 23.3.3)
             bitcoind
             elementsd
 
             # Lightning implementations (used by integration tests / local setups).
             # Version checks:
-            # - `lightningd --version` (Core Lightning / clightning 25.09.2)
-            # - `lnd --version` (lnd 0.19.3-beta)
+            # - `lightningd --version` (Core Lightning / clightning 26.04.1)
+            # - `lnd --version` (lnd 0.20.1-beta)
             clightning
             lnd