Feedback
Sign in./start

Site navigation

Theme

Learn

  • Roadmaps

Build

  • Projects
  • Developer Tools

Contribute

  • Open Source Projects
  • Issues
  • Reviews
  • First Contribution
  • BountiesSoon
  • Feedback

Prove

  • Builders

Ecosystem

  • Partners
  • Get Funded↗
  • HackathonsSoon
Sign in./start-building

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

Feedback welcome — open a GitHub issue.

Learn

RoadmapsStart Building

Build

ProjectsDeveloper Tools

Contribute

Open Source ProjectsIssuesReviewsFirst ContributionSupportFeedback

Prove

Builders Directory

Account

Sign in

Legal

PrivacyTermsCredits

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

PrivacyTermsCredits

lesson // lightning

Custom Router

Implement a pathfinding service with custom fee and reliability heuristics.

advanced2 weeksproject // custom-router

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

./sign-in

On this page

Learning objectives

  • Ingest a channel graph snapshot
  • Score edges with custom weights
  • Benchmark success vs baseline routing

study // plan

Lessons are primers. Start with Step 1 (required reading) when present, then follow the numbered steps in the article. Depth comes from primary sources, labs, reflection, and evidence.

Research on Bitcoin Search

Step 1 // Required reading

Complete these before the numbered steps in the lesson body. Links are listed here once — not repeated below.

  • docsProject Spec: Custom Router

    Pull project page — acceptance criteria and submit flow.

  • bookMastering the Lightning Network

    Ch. 12: Pathfinding

Reflection prompts

  1. Explain Custom Router to a teammate without jargon - what problem does it solve?
  2. What would break in production if you misunderstood Custom Router?
  3. Which BOLT (or implementation doc) is the source of truth for this topic, and what did you verify there?

Lab // Project milestone evidence

Complete Steps 2–4. Ship a service that returns ranked routes for (source, dest, amount) and capture a small benchmark note vs a baseline.

evidence required

  • ·Link to public repo or branch
  • ·Example route response or CLI output for a sample query
  • ·Short benchmark note (success rate, fee, or latency vs baseline)
  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.

A custom router lets you experiment with weights: fee, uptime, historical fail rates, and liquidity hints.

Complete Step 1 // Required reading in the study plan above, then continue here. This closes Lightning Projects.

Step 2 — Goal

Service that:

  1. Loads graph data
  2. Returns routes for (source, destination, amount)
  3. Logs hypothetical success metrics against a dataset

Loading diagram…

Score edges, search paths, measure outcomes.

Done when: You can write the edge-weight formula you will ship first.

Step 3 — Milestones

PhaseShip
Milestone AIngest graph snapshot (file, Amboss, or node gossip export)
Milestone BRanked routes API for amount-constrained search
Milestone CBenchmark harness vs baseline weights

Done when: Milestone B returns at least one path or a clear “no route” with reasons.

Step 4 — Build & evidence (lab)

Implement against /projects/custom-router. Capture repo link, sample route output, and benchmark note.

Common mistakes

  • Optimizing only fees and ignoring historical fail rates
  • Treating gossip capacity as guaranteed liquidity
  • Benchmarking only on a single lucky path

Done when: Lab evidence is filed.

Next lesson

Contribution Discovery — find beginner-friendly issues across LND, CLN, and LDK.

further reading

  • toolAmboss API / graph data
  • boltBOLT7 Gossip

review // club

Chapter review picks

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.

  • Ride The Lightning UI GFI

    Compare RTL's channel views with what you'd build in the node ops dashboard project.

    gfi
    UXnode ops
    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.

build // next

Apply this chapter in a project

You have the concepts — ship something small to prove it. These Pull projects connect directly to what you just studied.

  • project // lightning-pos

    Lightning POS
    ./spec./submit

  • project // ln-node-dashboard

    Node Ops Dashboard
    ./spec./submit

  • project // custom-router

    Custom Router
    ./spec./submit

discussion

Discussion

prevNode Ops DashboardnextContribution Discovery

On this page

Press Shift + ? for keyboard shortcuts.

Press R to research on Bitcoin Search.

No questions yet — be the first to ask.