feat: add 2-hop swaps and channel_adjacency hint

Implements 2-hop swap negotiation and pinned 2-hop payments (u→m→v).
Adds poll capability extension for 2-hop candidate discovery via channel_adjacency (legacy neighbors_ad supported).
Updates RPC/proto/docs and adds unit + integration tests.

Author: YusukeShimizu

2hop.execplan.md

@@ -0,0 +1,228 @@
+Define the minimal extension that enables atomic swaps even over a 2-hop path `u → m → v`.
+
+## Motivation
+
+PeerSwap can perform atomic swap between direct nodes. However, in real networks many two-hop paths exist where exactly one intermediary node forms the route, `u → m → v`. We therefore want to enable swaps over these paths as well.
+
+* Release liquidity without opening additional channels  
+* No cooperation or trust required from the relay node m  
+* Keep using the existing one-hop protocol on the endpoint nodes u and v as is
+
+## Network Model
+
+```
+u──ch₁──m──ch₂──v
+↕  p2p (tcp) ↕
+```
+
+* `ch₁` and `ch₂` are public LN channels
+* `u` and `v` are already connected via p2p (TCP) and can exchange BOLT#1 custom messages
+* It is irrelevant whether the relay node `m` supports PeerSwap or not
+
+**Notation**
+
+* `u`: initiator  
+* `m`: intermediary  
+* `v`: responder
+
+## Messages
+
+Policy
+
+* No new message types are introduced.  
+* The existing JSON messages are extended with additional optional fields.  
+* The semantics of existing fields are unchanged.  
+* All added fields are OPTIONAL; nodes that do not understand them simply ignore them.  
+* The JSON container twohop indicates “2-hop discovery mode”; the message is interpreted as 2-hop only when this container is present.
+
+Affected messages (type numbers stay the same)
+
+* swap_in_request  (JSON, type = 42069)  
+* swap_in_agreement (JSON, type = 42073)  
+* swap_out_request (JSON, type = 42071)  
+* swap_out_agreement (JSON, type = 42075)  
+* opening_tx_broadcasted and the rest remain unchanged
+
+### `swap_out_request`
+
+Additional Fields
+
+* `twohop`: object — A container that signals 2-hop discovery mode.  
+  The receiver treats the message as 2-hop only when this object is present.  
+  * `twohop.intermediary_pubkey`: string (33-byte compressed pubkey, hex) —  
+    the pubkey of the intermediary node **m**
+
+Behaviour
+
+* When `twohop` is present, the receiver **v** derives its local channel  
+  **`ch₂` (m–v)** from `intermediary_pubkey`, computes its own  
+  `receivable_msat`, and decides whether the requested amount is within the
+  executable range.
+
+Compatibility
+
+* A legacy node that does not understand `twohop` ignores the unknown field and
+  will safely reject the request for ordinary reasons (e.g. the `scid`
+  is not a direct channel or `amount = 0`).
+
+### `swap_out_agreement`
+
+Additional Fields (all OPTIONAL)
+
+* `twohop`: object — The result of 2-hop discovery.  
+  * `twohop.incoming_scid`: string (e.g. `"x:y:z"`) —  
+    the short_channel_id of **`ch₂` (m–v)**
+
+Behaviour
+
+* If `twohop` is present, the receiver **u** pays the `payreq` via a 2-hop route
+  that includes `incoming_scid`.
+
+Notes
+
+* Route hints are **not** used; the sender pins the route itself (doable with
+  standard LN APIs).  
+* Route hints cannot reliably force a fixed route.
+
+### `swap_in_request`
+
+Additional Fields
+
+* `twohop`: object — Container that signals 2-hop discovery mode.  
+  * `twohop.intermediary_pubkey`: string (33-byte compressed pubkey, hex) —  
+    the pubkey of the intermediary node **m**
+
+Behaviour
+
+* When `twohop` is present, the receiver **v** identifies its local  
+  **`ch₂` (m–v)** from `intermediary_pubkey` and checks whether the requested
+  **`amount`** can be sent.
+
+Compatibility
+
+* A legacy node that does not understand `twohop` ignores the field and rejects
+  the request using the current rules (`scid`, `amount`, etc.).
+
+### `swap_in_agreement`
+
+Additional Fields (all OPTIONAL)
+
+* `twohop`: object — The result of 2-hop discovery.  
+  * `twohop.incoming_scid`: string (e.g. `"x:y:z"`) —  
+    the short_channel_id of **`ch₂` (m–v)**, viewed from **v** (m → v)
+
+Behaviour
+
+* If `twohop` is present, the responder **v**, when making the payment, verifies
+  that the receivable amount on `incoming_scid`** is sufficient for
+  **`amount`.
+
+## Doing the Swap
+
+* When `twohop` is present, the swap maker locates its local  
+  **`ch₁` (u–m)** using `intermediary_pubkey`, then pays the `payreq` over the
+  2-hop route that includes `scid`.
+  
+## Extension of the `poll` Message (Implemented; optional to rely on)
+
+### Purpose  
+Let the intermediary **m** periodically advertise its own channel adjacency list
+(public + active channels from **m** to immediate neighbors).  
+Doing so makes it easier for **u** and **v** to discover potential 2-hop routes.
+
+### Method
+Add an optional `channel_adjacency` object to the existing `poll` JSON.  
+Nodes that do not understand the field simply ignore it, so backward compatibility is preserved.  
+In most cases it is sufficient to send it on the same schedule as the ordinary `poll`.
+
+* The broadcast interval is fixed; freshness is **not** guaranteed.  
+* Because there is no defence against false reports, using this extension is **optional**.  
+* When the swap is actually executed, the amount is finalised with the 2-hop discovery step.
+* Legacy note: older drafts used the name `neighbors_ad` with keys
+  `v/public_only/limit/entries`. This repository accepts both representations on
+  receive, but emits `channel_adjacency` going forward.
+
+Example of the extended `poll` message:
+
+```json
+{
+  "version": 5,
+  "assets": ["BTC", "LBTC"],
+  "peer_allowed": true,
+  "btc_swap_in_premium_rate_ppm": 100,
+  "btc_swap_out_premium_rate_ppm": 200,
+  "lbtc_swap_in_premium_rate_ppm": 50,
+  "lbtc_swap_out_premium_rate_ppm": 150,
+  "channel_adjacency": {
+    "schema_version": 1,
+    "public_channels_only": true,
+    "max_neighbors": 20,
+    "truncated": false,
+    "neighbors": [
+      {
+        "node_id": "<pubkey-of-neighbor>",
+        "channels": [
+          {
+            "channel_id": 1234567890,
+            "short_channel_id": "1x2x3",
+            "active": true
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Sending policy  
+When transmitting, the LN node extracts public and active neighbours from its channel list.  
+By default no balance information is sent (privacy).  
+If the number of neighbours exceeds `max_neighbors`, prune deterministically and set `truncated=true`.  
+Send triggers: the regular `poll` interval and the reply to an initial `request_poll`.
+
+### Receiver behaviour  
+A listener can build a list of 2-hop candidates — even to nodes with which it does **not** share a direct channel.
+
+In this repository, the last received `channel_adjacency` is stored in the peersync database and is surfaced via `listpeers` as `channel_adjacency`.
+
+Conceptual example of a 2-hop candidate list:
+
+```json
+[
+  {
+    "nodeid": "<v_pubkey>",
+    "intermediary_nodeid": "<m_pubkey>",
+    "outgoing_scid": "<ch1 u–m>",
+    "incoming_scid": "<ch2 m–v>",
+    "spendable_msat": 0,
+    "receivable_msat": 0,
+    "sent": {
+      "total_swaps_out": 2,
+      "total_swaps_in": 1,
+      "total_sats_swapped_out": 5300000,
+      "total_sats_swapped_in": 302938
+    },
+    "received": {
+      "total_swaps_out": 1,
+      "total_swaps_in": 0,
+      "total_sats_swapped_out": 2400000,
+      "total_sats_swapped_in": 0
+    },
+    "total_fee_paid": 6082,
+    "swap_in_premium_rate_ppm": 100,
+    "swap_out_premium_rate_ppm": 100
+  }
+]
+```
+
+When actually executing a swap, the implementation can pick transparently from this list, but — given equal conditions — a direct 1-hop path should always be preferred.
+
+## Peer-Discovery Strategy
+
+The `poll` extension makes it easier to estimate whether a 2-hop swap is possible and what the rough capacity might be.  
+Even without it, discovery can still be done by probing directly, but this is less efficient.
+
+| Strategy                                                     | support required on m? | Pros             | Cons                                   |
+| ------------------------------------------------------------ | ---------------------- | ---------------- | -------------------------------------- |
+| A – Poll extension (periodic broadcast of `connected_peers`) | yes                    | Low latency      | Useless if m does not support PeerSwap |
+| B – Direct probe                                             | no                     | Works everywhere | Less efficient                         |

2hop.md

@@ -8,6 +8,7 @@ import (
 	"fmt"
 	log2 "log"
 	"os"
+	"sort"
 	"time"
 
 	"github.com/btcsuite/btcd/chaincfg"
@@ -198,6 +199,7 @@ type PeerChannel struct {
 	PeerConnected    bool              `json:"peer_connected"`
 	State            string            `json:"state"`
 	ShortChannelId   string            `json:"short_channel_id,omitempty"`
+	Private          bool              `json:"private,omitempty"`
 	TotalMsat        glightning.Amount `json:"total_msat,omitempty"`
 	ToUsMsat         glightning.Amount `json:"to_us_msat,omitempty"`
 	ReceivableMsat   glightning.Amount `json:"receivable_msat,omitempty"`
@@ -294,6 +296,55 @@ func (cl *ClightningClient) ReceivableMsat(scid string) (uint64, error) {
 	return 0, fmt.Errorf("could not find a channel with scid: %s", scid)
 }
 
+func (cl *ClightningClient) ChannelsToPeer(peerPubkey string) ([]string, error) {
+	var res ListPeerChannelsResponse
+	err := cl.glightning.Request(ListPeerChannelsRequest{Id: peerPubkey}, &res)
+	if err != nil {
+		return nil, err
+	}
+
+	var scids []string
+	for _, ch := range res.Channels {
+		if ch.PeerId != peerPubkey || ch.ShortChannelId == "" {
+			continue
+		}
+		if err := cl.checkChannel(ch); err != nil {
+			continue
+		}
+		scids = append(scids, lightning.Scid(ch.ShortChannelId).ClnStyle())
+	}
+	sort.Strings(scids)
+	return scids, nil
+}
+
+func (cl *ClightningClient) ListChannels(ctx context.Context) ([]peersync.Channel, error) {
+	var res ListPeerChannelsResponse
+	if err := cl.glightning.Request(ListPeerChannelsRequest{}, &res); err != nil {
+		return nil, err
+	}
+
+	channels := make([]peersync.Channel, 0, len(res.Channels))
+	for _, ch := range res.Channels {
+		if ch.PeerId == "" || ch.ShortChannelId == "" {
+			continue
+		}
+		peerID, err := peersync.NewPeerID(ch.PeerId)
+		if err != nil {
+			continue
+		}
+
+		channels = append(channels, peersync.Channel{
+			Peer:           peerID,
+			ChannelID:      0,
+			ShortChannelID: lightning.Scid(ch.ShortChannelId).ClnStyle(),
+			Active:         ch.PeerConnected && ch.State == "CHANNELD_NORMAL",
+			Public:         !ch.Private,
+		})
+	}
+
+	return channels, nil
+}
+
 // checkChannel performs a set of sanity checks id the channel is eligible for
 // a swap of amtSat
 func (cl *ClightningClient) checkChannel(ch PeerChannel) error {
@@ -503,6 +554,66 @@ func (cl *ClightningClient) PayInvoiceViaChannel(payreq string, scid string) (pr
 	return preimage, nil
 }
 
+func (cl *ClightningClient) PayInvoiceVia2HopRoute(payreq string, outgoingScid string, incomingScid string, intermediaryPubkey string) (preimage string, err error) {
+	bolt11, err := cl.glightning.DecodeBolt11(payreq)
+	if err != nil {
+		return "", err
+	}
+
+	if bolt11.AmountMsat.MSat() == 0 {
+		return "", fmt.Errorf("invoice has no amount")
+	}
+
+	outgoingScid = lightning.Scid(outgoingScid).ClnStyle()
+	incomingScid = lightning.Scid(incomingScid).ClnStyle()
+
+	route, err := cl.glightning.GetRoute(
+		bolt11.Payee,
+		bolt11.AmountMsat.MSat(),
+		10.0,
+		uint(bolt11.MinFinalCltvExpiry+1),
+		"",
+		0.0001,
+		nil,
+		2,
+	)
+	if err != nil {
+		return "", err
+	}
+
+	if len(route) != 2 {
+		return "", fmt.Errorf("could not find 2-hop route")
+	}
+	if route[0].Id != intermediaryPubkey {
+		return "", fmt.Errorf("route does not use expected intermediary")
+	}
+	if route[0].ShortChannelId != outgoingScid || route[1].ShortChannelId != incomingScid {
+		return "", fmt.Errorf("route does not use expected channels")
+	}
+
+	label := randomString()
+	_, err = cl.glightning.SendPay(
+		route,
+		bolt11.PaymentHash,
+		label,
+		bolt11.AmountMsat.MSat(),
+		payreq,
+		bolt11.PaymentSecret,
+		0,
+	)
+	if err != nil {
+		return "", err
+	}
+
+	res, err := cl.glightning.WaitSendPay(bolt11.PaymentHash, 0)
+	if err != nil {
+		return "", err
+	}
+
+	preimage = res.PaymentPreimage
+	return preimage, nil
+}
+
 // RebalancePayment handles the lightning payment that should re-balance the
 // channel.
 func (cl *ClightningClient) RebalancePayment(payreq string, channel string) (preimage string, err error) {