Bitswap Protocol

4.1 Bitswap 1.0.0: Interaction Pattern

Given that a client C wants to fetch data from some server S:

1. C sends a message to S for the blocks it wants, via a stream s_want
   1. C MAY either send a complete wantlist, or an update to an outstanding wantlist
   2. C MAY reuse this stream to send new wants
2. S sends back blocks on a stream s_receive. S MAY reuse this stream to send back subsequent responses.
   1. S SHOULD respect the relative priority of wantlist requests from C, with wants that have higher priority values being responded to first.
3. When C no longer needs a block it previously asked for, it SHOULD send a Cancel message for that block to all peers from which it has not received a response about that block

4.2 Bitswap 1.0.0: Message

A single Bitswap message MAY contain any of the following content:

1. The sender’s wantlist. This wantlist MAY either be the sender’s complete wantlist or just the changes to the sender’s wantlist that the receiver needs to know.
2. Data blocks. These are meant to be blocks that the receiver has requested (i.e., blocks that are on the receiver’s wantlist as far as the sender is aware at the time of sending).

message Message {
  message Wantlist {
    message Entry {
      bytes block = 1; // the block key, i.e. a CIDv0
      int32 priority = 2; // the priority (normalized). default to 1
      bool cancel = 3;  // whether this revokes an entry
    }

    repeated Entry entries = 1; // a list of wantlist entries
    bool full = 2; // whether this is the full wantlist. default to false
  }

  Wantlist wantlist = 1;
  repeated bytes blocks = 2;
}

4.3 Bitswap 1.0.0: Protocol Format

All protocol messages sent over a stream are prefixed with the message length in bytes, encoded as an unsigned variable length integer as defined by the multiformats unsigned-varint spec.

All protocol messages MUST be less than or equal to 4MiB in size.

5.1 Bitswap 1.1.0: Wire Format

message Message {
    message Entry {
      bytes block = 1; // CID of the block
      int32 priority = 2; // the priority (normalized). default to 1
      bool cancel = 3; // whether this revokes an entry
    }

    repeated Entry entries = 1; // a list of wantlist entries
    bool full = 2; // whether this is the full wantlist. default to false
  }

  message Block {
    bytes prefix = 1; // CID prefix (all of the CID components except for the digest of the multihash)
    bytes data = 2;
  }

  Wantlist wantlist = 1;
  repeated Block payload = 3; 
}

6.1 Bitswap 1.2.0: Interaction Pattern

Given that a client C wants to fetch data from some server S:

1. C opens a stream s_want to S and sends a message for the blocks it wants:
   1. C MAY either send a complete wantlist, or an update to an outstanding wantlist.
   2. C MAY reuse this stream to send new wants.
   3. For each of the items in the wantlist C MAY ask if S has the block (i.e. a Have request) or for S to send the block (i.e. a Block request). C MAY also ask S to send back a DontHave message in the event it doesn't have the block.
2. S responds back on a stream s_receive. S MAY reuse this stream to send back subsequent responses:
   1. If C sends S a Have request for data S has (and is willing to give to C) it SHOULD respond with a Have, although it MAY instead respond with the block itself (e.g. if the block is very small).
   2. If C sends S a Have request for data S does not have (or has but is not willing to give to C) and C has requested for DontHave responses then S SHOULD respond with DontHave.
   3. S MAY choose to include the number of bytes that are pending to be sent to C in the response message.
   4. S SHOULD respect the relative priority of wantlist requests from C, with wants that have higher priority values being responded to first.
3. When C no longer needs a block it previously asked for it SHOULD send a Cancel message for that request to any peers that have not already responded about that particular block. It SHOULD particularly send Cancel messages for Block requests (as opposed to Have requests) that have not yet been answered.

6.2 Bitswap 1.2.0: Wire Format

message Message {
  message Wantlist {
    enum WantType {
      Block = 0;
      Have = 1;
    }

    message Entry {
      bytes block = 1; // CID of the block
      int32 priority = 2; // the priority (normalized). default to 1
      bool cancel = 3; // whether this revokes an entry
      WantType wantType = 4; // Note: defaults to enum 0, ie Block
      bool sendDontHave = 5; // Note: defaults to false
    }

    repeated Entry entries = 1; // a list of wantlist entries
    bool full = 2; // whether this is the full wantlist. default to false
  }
  message Block {
    bytes prefix = 1; // CID prefix (all of the CID components except for the digest of the multihash)
    bytes data = 2;
  }

  enum BlockPresenceType {
    Have = 0;
    DontHave = 1;
  }
  message BlockPresence {
    bytes cid = 1;
    BlockPresenceType type = 2;
  }

  Wantlist wantlist = 1;
  repeated Block payload = 3;
  repeated BlockPresence blockPresences = 4;
  int32 pendingBytes = 5;
}