Route Hints

What Are Route Hints?

Route hints are pieces of routing information embedded directly in Lightning invoices. They solve a fundamental problem: how do you receive a payment when your channels aren't visible to the network?

In the Lightning Network, nodes discover payment paths by querying a shared graph of public channels. This graph is built through gossip: nodes announce their channels, and this information propagates across the network. But not all channels are public. Private channels (also called unannounced channels) deliberately stay off this graph for privacy or operational reasons.

Route hints bridge this gap. When you create an invoice, you can include hints that tell the sender: "Here's how to reach me through my private channel." The hint contains everything the sender needs: which node to route through, what fees to pay, and what timelocks to use.

Think of route hints as directions to a private address. The main roads (public channels) are on every map, but your private driveway isn't. Route hints are the directions you give to visitors so they can find you.

Why Route Hints Exist

Lightning routing relies on a shared understanding of network topology. Every node maintains a "channel graph": a map of all public channels and their properties. When you want to send a payment, your node uses this graph to find a path to the recipient.

Public channels announce themselves to the network through gossip messages. They broadcast their existence, capacity, fee policies, and other metadata. This makes them discoverable and usable for routing anyone's payments.

Private channels skip this announcement. They exist only between the two parties who opened them. The rest of the network doesn't know they exist. This is useful for:

• Privacy: not revealing your channel partners or capacity
• Reducing gossip load: fewer announcements mean less bandwidth
• Dedicated channels: channels meant only for direct payments, not routing
• Zero-conf channels: channels that can't be announced until confirmed on-chain

But private channels create a problem: if no one knows about your channel, how can they route payments to you? Route hints solve this by letting you selectively reveal just enough information to receive a specific payment, without permanently announcing your channel to the world.

Technical Structure in BOLT 11

Route hints are defined in BOLT 11, the specification for Lightning payment requests. They're encoded in the invoice using the r field (for "routes").

Each route hint describes one or more hops. A single hop contains five pieces of data:

• pubkey (33 bytes): the public key of the node at the start of this hop. This is the node the sender should route through.
• short_channel_id (8 bytes): the unique identifier of the channel to use. Encoded as block height, transaction index, and output index.
• fee_base_msat (4 bytes): the base fee in millisatoshis that this node charges for forwarding payments.
• fee_proportional_millionths (4 bytes): the proportional fee rate in parts per million (ppm). A value of 1000 means 0.1% of the payment amount.
• cltv_expiry_delta (2 bytes): the number of blocks this node requires for the timelock delta. Used to ensure safe HTLC resolution.

Here's what decoded route hints look like in JSON format:

{
  "route_hints": [
    {
      "hop_hints": [
        {
          "node_id": "03864ef025fde8fb587d989186ce6a4a186895ee44a926bfc370e2c366597a3f8f",
          "chan_id": "824347x2456x1",
          "fee_base_msat": 1000,
          "fee_rate_millionths": 100,
          "cltv_expiry_delta": 144
        }
      ]
    }
  ]
}

An invoice can contain multiple route hints, each representing an alternative path. If the sender can't use the first hint (perhaps the channel lacks capacity), they can try the next one. This redundancy improves payment success rates.

How Route Hints Work in Practice

When a sender receives an invoice with route hints, their node follows this process:

1. Parse the invoice: extract the payment hash, amount, and route hints from the BOLT 11 encoded string.
2. Augment the channel graph: temporarily add the route hint information as "phantom edges" to the local routing graph. These edges only exist for this payment attempt.
3. Find a path: run pathfinding from the sender to the recipient. The algorithm can now use the phantom edges from route hints as part of valid paths.
4. Construct the onion: build the encrypted onion packet that will carry the payment through each hop, including the private channel revealed in the hint.
5. Send the payment: forward the HTLC through the discovered route. The intermediate node (from the hint) receives and forwards the payment without knowing it came from a route hint.

From the intermediate node's perspective, this looks like any other forwarded payment. They don't know their channel was revealed in a route hint. They just see an incoming HTLC that needs forwarding.

Generating Invoices with Route Hints

Most Lightning implementations handle route hints automatically when you have private channels. Here's how to work with them in common implementations:

LND (Lightning Network Daemon)

LND automatically includes route hints for private channels when you create an invoice with the --private flag:

# Create invoice with automatic route hints for private channels
lncli addinvoice --amt 100000 --private

# Manually specify which channels to hint
lncli addinvoice --amt 100000 --private --hints "chanid1,chanid2"

# Decode an invoice to inspect its route hints
lncli decodepayreq lnbc1000n1pj...

LND selects route hints based on inbound capacity and channel health. It typically includes hints for channels with sufficient inbound liquidity to receive the invoice amount.

Core Lightning (CLN)

CLN automatically includes route hints for unannounced channels. You can control this behavior with the exposeprivatechannels parameter:

# Standard invoice (auto-includes private channel hints)
lightning-cli invoice 100000sat "label" "description"

# Specify which private channels to expose
lightning-cli invoice 100000sat "label" "description" \
  exposeprivatechannels='["chanid1", "chanid2"]'

# Decode to see route hints
lightning-cli decode lnbc1000n1pj...

LDK (Lightning Development Kit)

When building with LDK, you control route hint generation through the PhantomRouteHints and RouteHint structures:

// Create route hints manually
let route_hint = RouteHint(vec![RouteHintHop {
    src_node_id: channel_counterparty_pubkey,
    short_channel_id: channel_id,
    fees: RoutingFees {
        base_msat: 1000,
        proportional_millionths: 100,
    },
    cltv_expiry_delta: 144,
    htlc_minimum_msat: None,
    htlc_maximum_msat: None,
}]);

Use Cases and Applications

Route hints enable several important Lightning Network use cases:

Mobile Lightning Wallets

Mobile wallets typically connect to Lightning Service Providers (LSPs) through private channels. When you install a Lightning wallet on your phone, the LSP opens a channel to you. This channel often starts as zero-conf (usable before on-chain confirmation) and unannounced. Every invoice your wallet generates includes route hints pointing through the LSP.

Zero-Confirmation Channels

Zero-conf channels can't be announced to the network until the funding transaction confirms (typically 3-6 blocks). But users want to receive payments immediately. Route hints make this possible: the invoice includes hints for the unconfirmed channel, allowing payments to flow while waiting for confirmation.

Privacy-Preserving Setups

Some node operators deliberately keep all channels private to avoid revealing their network position, channel partners, or capacity. Route hints let them receive payments without sacrificing this privacy. The hints are only shared with specific payers, not broadcast to the entire network.

Enterprise and Custodial Services

Exchanges and custodial wallets often maintain private channels with market makers or liquidity providers. These high-capacity channels handle significant volume but aren't announced publicly. Route hints enable withdrawals and payments through these private pathways.

Limitations and Considerations

Route hints come with trade-offs that developers and users should understand:

Invoice Size and QR Codes

Each route hint adds approximately 50-55 bytes to an invoice. Since Lightning invoices are often displayed as QR codes, this matters. Standard QR codes become difficult to scan beyond ~2,900 characters. With multiple route hints, invoices can exceed this limit, forcing users to copy-paste instead of scan. Best practice is to limit invoices to 5-6 route hints maximum.

Hints Are Suggestions, Not Requirements

A sender's node may ignore your route hints entirely if it finds a better path. If the sender discovers a lower-fee route through public channels that reaches the same destination, most implementations will prefer that route. Hints guarantee reachability, not that the specific path will be used.

Stale Information

Route hints capture channel state at invoice creation time. If fees change, the channel closes, or capacity shifts before payment, the hint becomes stale. Stale hints can cause payment failures. Regenerate invoices rather than reusing old ones for extended periods.

Privacy Trade-offs

Including route hints reveals information about your private channels to anyone who sees the invoice. They learn your channel partner's pubkey, the channel ID, and fee policies. For sensitive setups, consider the privacy implications of each hint you include.

Debugging Route Hint Issues

Route hint problems are a common source of payment failures. Here's how to diagnose and fix them:

NO_ROUTE Errors

If senders report "no route found" errors, check these common causes:

• Missing hints: decode the invoice and verify the route_hints field exists and contains valid entries.
• Insufficient inbound capacity: the hinted channel needs enough inbound liquidity to receive the payment amount plus fees.
• Wrong channel ID: verify the short_channel_id matches your actual channel. Channel IDs change if the funding transaction gets reorged.
• Peer offline: the intermediate node (your channel partner) must be online to forward payments.

Inspecting Invoices

Always decode invoices to verify route hints are present and correct:

# LND
lncli decodepayreq lnbc100n1pj...

# CLN
lightning-cli decode lnbc100n1pj...

# Look for "route_hints" in the output
# Verify pubkeys and channel IDs match your channels

Fee Mismatches

If the fee information in your hints doesn't match what the intermediate node actually charges, payments fail with fee-related errors. This often happens when channel policies change after invoice creation. Generate fresh invoices or ensure hints use current fee policies.