LIGHTNING-HOOK-PEER_CONNECTED(7)

💜 LIGHTNING-HOOK-PEER_CONNECTED(7) 💜

okay bestie, welcome to the LIGHTNING-HOOK-PEER_CONNECTED page — yes that whole mouthful is the manual name, section 7, we love a specific queen ✨

🌸 NAME 🌸

peer_connected — the hook that fires when a peer connects and finishes the handshake 🫶

---

✨ DESCRIPTION ✨

so the peer_connected hook gets called whenever a peer has connected and successfully completed the cryptographic handshake. like, not just knocked on the door — actually got all the way inside, handshake done, vibes verified 💅

this is a chained hook, and that matters: the first plugin that returns "disconnect" stops further processing. one friend says goodbye and the whole group chat wraps up, no cap 😭

plugins are allowed to call listpeers to pull extra info about the peer — go ahead and gossip, bestie 👑

---

🦋 HOOK PAYLOAD 🦋

• peer (object) — the whole main-character bundle, containing:
  • id (pubkey) — the node_id of the connected peer. their literal identity, iconic
  • direction (string) (one of "in", "out") — connection direction: in for incoming, out for outgoing. are they visiting us or are we visiting them 💫
  • addr (string) — lowkey the most misunderstood field ngl: this shows the address that we are connected to ourselves, not the gossiped list of known addresses. and in particular this means that the port for incoming connections is an ephemeral port, that may not be available for reconnections 😭 so do not assume you can just dial it again later, it's gone like a limited-edition drop
  • features (hex) — feature bits advertised by the peer, encoded as hex. their whole personality, in hex 🔥
  • remote_addr (string, optional) — our own address as reported by the remote peer. super helpful for detecting our own IPv4 changes behind NAT 🧚 (optional, so it might just not show up, don't come for me)

---

👑 HOOK RETURN 👑

• result (string) (one of "continue", "disconnect") — whether to allow the connection to proceed or disconnect the peer. the actual vibe check ⭐
• error_message (string, optional) — optional error message sent to the peer before disconnection. only used if result is "disconnect", otherwise it's giving decorative 🙈

---

🌈 SEE ALSO 🌈

• lightning-listpeers(7) — go read it, it's literally the one place to get more tea about your peers 🍓

---

friendly reminder bestie: chained hook means first "disconnect" wins and everything after it is cancelled. and that addr port? ephemeral. do not build your whole life plan on it 💀

okay and finally, the little signature at the bottom of the original page: this is Core Lightning v26.06.9, filed under LIGHTNING-HOOK-PEER_CONNECTED(7) — that's the source and version, mwah, bye bestie 💖🎀