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 // bitcoin

P2P Adversarial Thinking

Eclipse attacks, topology leaks, compact block relay, and why Bitcoin’s gossip layer is a security surface.

advanced6 days

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

./sign-in

On this page

Learning objectives

  • Explain eclipse and partitioning risks for Bitcoin peers
  • Describe what compact blocks optimize and what they do not secure
  • List practical defenses for node operators and wallet backends

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.

  • articleEclipse Attacks on Bitcoin’s Peer-to-Peer Network
  • bipBIP-152 Compact Block Relay
  • docsCompact Blocks FAQ

Reflection prompts

  1. How can an adversary isolate a node from honest peers, and what symptoms would you look for in logs?
  2. What problem do compact blocks solve, and which attack classes remain even with BIP-152?
  3. If you run infrastructure for wallets, which P2P settings and monitoring would you harden first?

Lab // Node exposure worksheet

Complete Steps 2–3. Document your bitcoind (or Polar) peer settings — maxconnections, addnode/connect, onion vs clearnet — and write a short adversarial threat note for that setup.

evidence required

  • ·Export or screenshot of peer/connection config
  • ·Half-page threat note covering eclipse and DoS
  • ·One concrete hardening change you would make
  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.

Bitcoin’s P2P network is not just plumbing. Peer selection, relay, and topology affect censorship resistance, privacy, and whether your node sees the same chain tip as the honest majority.

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

Step 2 — Core idea: eclipse, partitions, compact relay

Wallets and services that trust a small set of peers inherit those peers’ view of the mempool and chain. Protocol builders who ignore gossip security ship fragile products.

An eclipse attack aims to surround a victim with attacker-controlled peers so the victim’s view of the network is filtered. Related risks include BGP-level routing interference and intentional network partitions.

BIP-152 compact blocks reduce bandwidth when relaying new blocks by sending short transaction IDs peers likely already have. This improves propagation — it is not a substitute for validating consensus rules.

Loading diagram…

Honest nodes need diverse peers; compacted relay speeds block gossip.

Operator habits

  • Prefer diversity (ASNs, networks, onion where appropriate)
  • Monitor peer churn and unexpected tip disagreements
  • Separate listening services from keys when possible

Done when: You can name one eclipse symptom and one thing BIP-152 does not fix.

Step 3 — Threat note for your setup (lab)

Document your node’s peer settings (maxconnections, addnode/connect, onion vs clearnet). Write a short threat note covering eclipse and DoS for that setup, plus one concrete hardening change you would make.

bitcoin-cli -regtest getnetworkinfo
# Also note bitcoin.conf / Polar peer settings you actually use

Common mistakes

  • Running a “full node” with one trusted outbound peer forever
  • Assuming private RPC + public P2P needs no hardening
  • Confusing relay policy DoS mitigations with consensus safety

Done when: Lab evidence (config export + threat note + one hardening change) is complete.

Next lesson

Security Models & Light Clients — full validation vs SPV, filters, and AssumeUTXO tradeoffs.

further reading

  • bookMastering Bitcoin

    Ch. 10: The Bitcoin Network

review // club

Review club

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

  • BIP-152 compact block relay

    Read BIP-152 and explain how compact blocks reduce relay bandwidth during block propagation.

    spec review
    bandwidthmempool reconstruction
    45 min·advancedopen 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

discussion

Discussion

prevP2P NetworknextSecurity Models & Light Clients

On this page

Press Shift + ? for keyboard shortcuts.

Press R to research on Bitcoin Search.

No questions yet — be the first to ask.