RoadmapsProjects
Sign in./start

Learn

RoadmapsProjects

Contribute

DiscoverIssuesOpen Source Guide

Account

Sign in./start-building

Become an Open Source Builder. Learn. Build. Contribute.

Learn

RoadmapsProjectsStart Building

Contribute

DiscoverIssues

Account

Sign inDashboardSettings

Legal

PrivacyTermsCredits

© 2026 Pull // code MIT · curriculum CC BY-SA 4.0

PrivacyTermsCredits

lesson // lightning

Channel Liquidity

Understand inbound vs outbound balance and why funded channels can still fail to pay or receive.

intermediate4 days

Public lesson — sign in to track progress on this roadmap.

./sign-in

On this page

Learning objectives

  • Explain inbound vs outbound capacity without ops jargon
  • Predict when a payment will fail due to balance direction
  • Relate channel balance to forwarding constraints

study // plan

Lessons are primers. Depth comes from required reading, interactive labs, reflection, and a hands-on check with evidence — the BOSS study pattern.

Research on Bitcoin Search

Required reading

  • bookMastering the Lightning Network

    Ch. 7: Payment Channels

Reflection prompts

  1. Explain inbound vs outbound to a teammate who only knows on-chain Bitcoin — what is different?
  2. Your node shows 1 BTC total channel capacity but cannot receive a 50k sat invoice. What is the most likely cause?
  3. Which side of a single-funded channel holds inbound capacity for the funder?

Lab // Balance direction check

In Polar or regtest, open a channel and inspect balances. Attempt a small payment in each direction and note which direction fails first when imbalanced.

evidence required

  • ·Screenshot or CLI output showing local/remote balance split
  • ·One sentence on send vs receive failure when outbound-heavy
  • ·Link to the Ch. 7 section you used
  1. 01

    Worked mental model

    Re-read the diagrams in this lesson once out loud in plain language. If you cannot explain the flow to a friend without jargon, pause and revisit the Mastering Bitcoin / Mastering Lightning chapters linked in Resources. Chapter references are intentional, not decorative.

  2. 02

    Hands-on habit

    Every protocol idea should be paired with one local experiment. That habit turns reading into builder instinct.

    1. Reproduce the happy path on regtest (or Polar for Lightning)
    2. Break it on purpose (wrong fee, expired invoice, offline peer)
    3. Write down what error you saw and which layer produced it (wallet, node, mempool, peer)
  3. 03

    Glossary check

    Pick three terms from this lesson and define them in one sentence each without opening notes. Weak definitions mean the lesson is not finished yet.

  4. 04

    Resource order

    Use Resources in order: narrative book chapter first, then BIP/BOLT for precision, then implementation docs for commands. Jumping straight to RPC flags without the mental model creates brittle knowledge.

Channel liquidity is not how much bitcoin you locked — it is which side of each channel holds that balance. Lightning is directional: the same channel can send easily in one direction and fail in the other.

Why this matters

This is the Lightning-specific idea that confuses people the first time. On-chain, a UTXO is yours to spend. In a channel, only your outbound balance is spendable by you; inbound is the counterparty's share that lets you receive. Routing later is just finding a path where every hop has enough outbound on the forward edge.

Fixed capacity

Total channel capacity is fixed until you splice, dual-fund, or close. Payments move balance between the two sides — they do not create new capacity.

Channel outbound versus inbound capacity
Outbound is your spendable side; inbound is what lets you receive.

Inbound vs outbound

TermMeaning
OutboundYour side's balance — what you can send or forward
InboundCounterparty's balance on your channel — what you can receive

After a typical single-funded open, the funder starts outbound-heavy (can send, cannot receive much). The peer starts inbound-heavy relative to the funder.

Payment failure from wrong-side balance

Loading diagram…

A route fails when any hop lacks outbound on the forward edge.

Funded does not mean receive-ready

A merchant with 10 BTC locked across channels but zero inbound on the invoice route still cannot get paid. Capacity and direction are different questions.

Forwarding locks liquidity

When your node forwards an HTLC, that slice of outbound is reserved until the payment settles or fails. Heavy routing without balanced channels drains outbound on busy edges — another reason direction matters before you study pathfinding.

Try it in Polar or regtest

  1. Open a channel between two nodes.
  2. Check local_balance vs remote_balance (or equivalent).
  3. Pay from the funder toward the peer — should succeed.
  4. Pay back the full amount — may fail if inbound is insufficient.
  5. Write one sentence explaining the failure in inbound/outbound terms.

Next steps

Commitment transactions — the signed states that make channel updates safe.

further reading

  • bookMastering the Lightning Network

    Ch. 8: Routing (balance context)

  • toolAmboss

review // club

Review club

Practice on real Lightning OSS changes tied to this chapter. Read the diff, use the checklist, and optionally paste your review comment URL in your lab notes.

  • Polar local dev GFI

    Polar powers most labs — review a small issue that improves local Lightning learning.

    gfi
    developer UXregtest
    25 min·beginneropen on GitHub
  • CLN plugin docs good first issue

    Pick a documentation GFI related to channels or plugins and draft a review comment on clarity.

    gfi
    readabilityexamples
    30 min·beginneropen on GitHub
review checklist
  1. Does the change solve the stated problem?
  2. Are edge cases and rollout behavior covered?
  3. Are tests or test vectors included?
  4. Is the diff minimal and clearly explained?

More repos and GFIs on /discover and /issues.

progress // sign in

Reading is public. Sign in to mark lessons complete, sync across devices, and unlock your roadmap.

./sign-in-to-track
prevOpening ChannelsnextCommitment Transactions

On this page

Press Shift + ? for keyboard shortcuts.

Press R to research on Bitcoin Search.