IPFS Bitswap Ledgers: How Peers Decide Who to Trust

Bitswap, the block-exchange protocol covered in this series' DHT-and-retrieval article, has no payment layer and no central authority deciding who gets served first. What it has instead is a ledger: a simple per-peer record of how much data has flowed in each direction, used to decide, moment to moment, whether a given peer is worth sending a block to. This closes a gap the earlier article left open, want-have and want-block explain how a single exchange happens, but not what stops a peer from taking blocks from everyone while giving nothing back.

TL;DR:

• Bitswap keeps a ledger per peer relationship, tracking bytes sent and bytes received, rather than relying on any payment or central coordination
• IPFS's original design describes a debt ratio, sent divided by received, used to decide how likely a peer is to get served on a given request, closer to 1 meaning a fair exchange
• Peers aren't cut off outright for a bad ratio; sending becomes probabilistic instead, falling as the debt ratio climbs, so a strategy can still serve a debtor sometimes rather than blacklisting them entirely
• This is a lighter-weight cousin of BitTorrent's tit-for-tat, not identical to it, actual go-bitswap implementations have room to differ in the specifics from the ledger model the original design paper describes
• AIOZ Pin's dedicated gateways sidestep this entire negotiation: a gateway response doesn't depend on any peer-to-peer debt ratio, since the request never enters Bitswap's peer-exchange logic at all

Why Bitswap Needs Fairness at All

Bitswap, as this series' DHT-and-Bitswap article covers, works off want-lists: ask connected peers what they have, then request the blocks that come back with a have response. Nothing about that exchange loop on its own stops one peer from constantly asking for blocks while never holding, serving, or sending anything useful back. Without some notion of fairness, a purely-taking peer costs its neighbors bandwidth for nothing in return, and at network scale that's exactly the kind of freeloading dynamic a p2p protocol either accounts for or gets exploited by.

The Ledger: A Simple Per-Peer Record

Rather than a payment system, Bitswap keeps a ledger with each peer it exchanges with, tallying how much data has moved in each direction over the life of that relationship. This ledger is entirely local and relationship-specific, node A's record of its dealings with node B has nothing to do with how node A treats node C, there's no shared or global reputation score being computed anywhere.

Debt Ratio: Deciding Who's Worth Serving

From that ledger, IPFS's original design describes a debt ratio, calculated as bytes sent to a peer divided by bytes received from them (plus one, to avoid dividing by zero on a brand-new relationship). A ratio near 1 means the exchange has been roughly balanced, each side has given about as much as it's gotten. A high ratio means one side has been sending far more than it's received back, the exact signature of a peer that keeps asking without reciprocating.

Probabilistic Sending, Not a Hard Cutoff

Rather than an outright ban once a peer's debt ratio crosses some threshold, the described strategy sends to debtor peers probabilistically, with the odds of serving them falling as their debt ratio rises. This matters for two reasons. First, it avoids permanently punishing a peer for a temporarily lopsided exchange, since ratios shift as more data moves in either direction, a peer that starts contributing again can work its ratio back down. Second, a rejected request triggers a cooldown before that peer gets reconsidered, which keeps a debtor from gaming the odds by simply retrying the same request over and over in rapid succession.

Leniency for Known Peers, Skepticism for Strangers

The same design leans toward leniency with peers that have a track record of successful exchange, and toward skepticism with peers a node has no history with. A peer that's reciprocated fairly in the past gets more benefit of the doubt on a temporarily unfavorable ratio than one a node has never dealt with before, which is a reasonable hedge, an unknown peer's bad ratio could just as easily be the start of a freeloading pattern as an unlucky snapshot.

Not Quite BitTorrent's Tit-for-Tat

It's worth being precise about the comparison this design invites: it's inspired by the same fairness problem BitTorrent's tit-for-tat solves, but it isn't a straight port of that algorithm. BitTorrent's classic tit-for-tat is a more rigid, round-based reciprocity scheme; Bitswap's described debt-ratio approach is probabilistic and continuous rather than round-based. It's also worth flagging honestly that this describes the strategy from IPFS's original design paper, actual go-bitswap implementations have evolved over time and have room to differ from that original description in their specifics, so treat this as the conceptual model Bitswap fairness is built around rather than a guarantee of the exact live algorithm in any given release.

Where AIOZ Pin's Gateways Sidestep This Entirely

Everything above describes fairness between peers exchanging blocks directly over Bitswap, an ongoing, relationship-based negotiation that only exists because peer-to-peer retrieval has no other way to discourage freeloading. A request to an AIOZ Pin gateway never enters that negotiation at all: it's a plain HTTP request to infrastructure that already holds the content, with no ledger, no debt ratio, and no probabilistic serving decision involved, the same category of shortcut this series already covered for DHT discovery and libp2p connection setup, applied here to Bitswap's own fairness layer specifically.

Frequently Asked Questions

Does Bitswap use payment to prevent freeloading? No. It uses a per-peer ledger tracking bytes sent and received, and a debt ratio derived from that, rather than any form of payment.

What is a Bitswap debt ratio? Bytes sent to a peer divided by bytes received from them. A ratio near 1 means a roughly balanced exchange; a high ratio flags a peer that's taken much more than it's given back.

Does a bad debt ratio get a peer blocked outright? Not according to the original design, sending becomes probabilistic and less likely as the ratio worsens, rather than an immediate hard cutoff, giving a peer room to recover by contributing again.

Is Bitswap's fairness the same as BitTorrent's tit-for-tat? It's inspired by the same problem but implemented differently, probabilistic and continuous rather than BitTorrent's more rigid round-based reciprocity scheme.

Is this exactly how current go-bitswap works today? This describes the debt-ratio model from IPFS's original design paper. Real implementations have evolved since, so treat this as the conceptual fairness model rather than a guarantee of the exact current algorithm.

Does AIOZ Pin's gateway traffic involve a Bitswap ledger? No. A gateway request is a direct HTTP call to infrastructure that already has the content, it never enters Bitswap's peer-to-peer exchange logic or its fairness negotiation at all.

Related Reading

• How IPFS Finds and Retrieves Your Files: DHT Provider Records and Bitswap Explained - the want-have/want-block exchange this article's fairness layer sits on top of
• libp2p: The Networking Layer Underneath IPFS - the connection layer Bitswap's peer exchanges actually run over
• How IPFS Verifies Content Without Trusting the Gateway - how a received block gets checked regardless of which peer's ledger it came through
• AIOZ Pin Dedicated Gateways: Simple, High-Performance IPFS Access - the product feature that bypasses this negotiation entirely
• Types of IPFS Nodes: The Different Roles, Explained - the peer roles a Bitswap ledger is actually tracking reputation between

References

• IPFS - Content Addressed, Versioned, P2P File System (original design paper)
• ipfs/go-bitswap Issue #224: Bitswap Strategy Implementation