2-hop peerswap

[YusukeShimizu]

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 (Optional Proposal)

Purpose

Let the intermediary m periodically broadcast its own connected_peers list.
Doing so makes it easier for u and v to discover potential 2-hop routes.

Method

Add an optional neighbors_ad 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.

Example of the extended poll message:

{
  "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,
  "neighbors_ad": {
    "v": 1,
    "public_only": true,
    "limit": 20,
    "entries": [
      {
        "node_id": "<pubkey-of-neighbor>",
        "channels": [
          {
            "channel_id": 1234567890,
            "short_channel_id": "x:y:z",
            "active": true
            // Optional (not sent by default):
            // "local_balance": 0,
            // "remote_balance": 0
          }
        ]
      }
    ]
  }
}

Sending policy

When transmitting, the LN node extracts public and active neighbours from its channel list.
By default no balance information is sent (privacy). The operator may opt-in to send approx values.
If the number of neighbours exceeds limit, prune by random / score order.
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.

Conceptual example of a 2-hop candidate list:

[
  {
    "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