bittorrent-codex-docs/10 Notes/Codex Peer Context Records.md

tags	related
codex/peer-presence	Codex WantList

#codex/peer-presence

related	Codex WantList, When Peer Presence Records are added and removed?, When Peer Want List is updated?

For each remote peer we are interacting with, we create an object of type BlockExcPeerCtx (codex/blockexchange/peers/peercontext.nim). This object is created in one place only: in BlockExcEngine.setupPeer, which is called in response to PeerEventKind.Joined peer event (registered in BlockExcEngine.new).

BlockExcPeerCtx objects keeps two important things about the peer:

1. the blocks the remote peer has - in the form of Presence records stored in blocks: Table[BlockAddress, Presence]
2. the blocks the remote peer has explicitly asked for - as peerWants: seq[WantListEntry]

Note

It is easy to get confused, so this note: peerCtx.peerWants is a list of blocks for which the remote peer explicitly asked, and not the blocks that remote peer would like to have. The blocks that the remote peer would like to have (but did not request them explicitly yet) are not recorded and handled on-the-fly by sending the presence list in response to WantHave request (see BlockExcEngine.wantListHandler).

Note

This is important to emphasize that the presence list - the block that the remote peer has, is constrained to the list of blocks that the current peer is interested in (wants). Thus, at any given time, the blocks in the BlockExcPeerCtx records is conjunction of two sets: the blocks that the remote peer has AND the blocks that we want.

[!info] In BitTorrent peers use have (equivalent of our presence but for single piece only, which may comprise of many blocks) to say they have a block. But then a peer seems to never say which blocks it wants without wanting to download them immediately (so, our WantBlock). On the very first message the downloaders send bitfield message to indicate which blocks they already have. Downloaders which don't have anything yet may skip the 'bitfield' message. And then they have interested not interested to indicate if they have interest in receiving blocks (any blocks, those messages do not have payload, so they do not tell which blocks you are or are no longer interested in). Interest state must be kept up to date at all times - whenever a downloader doesn't have something they currently would ask a peer for in unchoked, they must express lack of interest, despite being choked.

For peer's have list, we have a couple of helpers:

• peerHave - these are the blocks (given as seq[BlockAddress]) the peer has
• peerHaveCids - the corresponding cids (HashSet[Cid])
• contains - to check if the remote peer has given block (as BlockAddress)
• setPresence and cleanPresence to add/remove the blocks from peer's have list

For peer's want list, there is one helper peerWantsCids, giving back the cids of the corresponding blocks (as HashSet[Cid]).

See also When Peer Presence Records are added and removed? and When Peer Want List is updated?