From 1ab61c13f8793fec7ece146088e70e0a80bc4ad4 Mon Sep 17 00:00:00 2001 From: Adin Schmahmann Date: Fri, 4 Mar 2022 16:06:43 +0000 Subject: [PATCH 1/4] feat: bitswap 1.3.0 initial spec proposal --- BITSWAP.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 90 insertions(+), 1 deletion(-) diff --git a/BITSWAP.md b/BITSWAP.md index 6463325c7..9d7e6be1f 100644 --- a/BITSWAP.md +++ b/BITSWAP.md @@ -40,6 +40,7 @@ There are multiple Bitswap versions and more may evolve over time. We give brief - `/ipfs/bitswap/1.0.0` - Initial version - `/ipfs/bitswap/1.1.0` - Support CIDv1 - `/ipfs/bitswap/1.2.0` - Support Wantlist Have's and Have/DontHave responses +- `/ipfs/bitswap/1.3.0` - Support adding tokens in Bitswap requests/responses and BlockTooBig error message ## Block Sizes @@ -192,7 +193,95 @@ message Message { } ``` -## Implementations +## Bitswap 1.3.0 + +Bitswap 1.3.0 extends the Bitswap 1.2.0 protocol with the following changes: +1. Having a list of tokens that may be sent with the message and referenced within the message +2. Allowing each entry in the wantlist to contain a set of tokens +3. Allowing responses (both BlockPresences and Blocks) to contain a set of tokens +4. Adding an `AuthRequired` BlockPresence +5. Adding a `BlockTooBig` BlockPresence + +### 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 + 4. For each of the items in the wantlist C may append any `tokens` they want. Recommended tokens include those that would convince S to give C the blocks they want. +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) + 1. For each of the items that S sends back Blocks or BlockPresences for they may append any `tokens` they want + 2. If C sends S a Have request for data S has but is not currently willing to give to C, S may respond with an `AuthRequired` BlockPresence + 1. For each of the items that S sends back Blocks or BlockPresences for they may append any `tokens` they want. Recommended tokens include those that would inform C how they could convince S to give them access to the blocks they want. + 2. If C sends S a Have request for data S does not have (or has but is not willing to tell C it has) 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. If C asked for a block that S has but it is bigger than the maximum block size it should return `BlockTooBig` +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. + +### Tokens + +The major change in this protocol version is the introduction of the ability to pass tokens along with requests and responses. A token is defined as `` where the multicode is an identifier in the multicodec table, and the data is token-specific data associated with that code. + +Users who require additional codes for their new token formats should do one of: +- Register their code in the table +- For non-deployed testing purposes only - use a code in the application reserved range of the code table + - Note: if codes in the application reserved range will not be reservable in the code table which means that the code may conflict with another one used in the ecosystem which could cause application problems on collision. It is high recommended to not use these codes outside of testing or early development. + +To save space within the message the list of tokens used within the message are declared within the top level message and all other references to tokens are instead to the indices within the token list in the top level message. + +### 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 tokens int32 = 6; // the indices of the tokens in the token list + } + + 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; + repeated tokens int32 = 3; // the indices of the tokens in the token list + } + + enum BlockPresenceType { + Have = 0; + DontHave = 1; + AuthRequired = 2; + BlockTooBig = 3; + } + message BlockPresence { + bytes cid = 1; + BlockPresenceType type = 2; + repeated tokens int32 = 3; // the indices of the tokens in the token list + } + + Wantlist wantlist = 1; + repeated Block payload = 3; + repeated BlockPresence blockPresences = 4; + int32 pendingBytes = 5; + repeated bytes tokens = 6; // Each token is of the form where the multicode identifies what the data is for +} +``` + +# Implementations - - From acc0fe0f10016b5b397704293d15f72db25bae17 Mon Sep 17 00:00:00 2001 From: Adin Schmahmann Date: Fri, 26 Aug 2022 13:49:35 -0400 Subject: [PATCH 2/4] bitswap: bump field numbers used for tokens in bitswap 1.3.0 to avoid collision with Peergos numbers --- BITSWAP.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/BITSWAP.md b/BITSWAP.md index 9d7e6be1f..7364b8fce 100644 --- a/BITSWAP.md +++ b/BITSWAP.md @@ -249,7 +249,7 @@ message Message { 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 tokens int32 = 6; // the indices of the tokens in the token list + repeated tokens int32 = 7; // the indices of the tokens in the token list } repeated Entry entries = 1; // a list of wantlist entries @@ -258,7 +258,7 @@ message Message { message Block { bytes prefix = 1; // CID prefix (all of the CID components except for the digest of the multihash) bytes data = 2; - repeated tokens int32 = 3; // the indices of the tokens in the token list + repeated tokens int32 = 4; // the indices of the tokens in the token list } enum BlockPresenceType { @@ -270,7 +270,7 @@ message Message { message BlockPresence { bytes cid = 1; BlockPresenceType type = 2; - repeated tokens int32 = 3; // the indices of the tokens in the token list + repeated tokens int32 = 4; // the indices of the tokens in the token list } Wantlist wantlist = 1; From 661ab5bf195a6d7094851dbec85545cc8052e9bb Mon Sep 17 00:00:00 2001 From: Adin Schmahmann Date: Fri, 26 Aug 2022 13:50:08 -0400 Subject: [PATCH 3/4] bitswap: rename bitswap 1.3.0 AuthRequired to TokenErr --- BITSWAP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/BITSWAP.md b/BITSWAP.md index 7364b8fce..6c74a7bb5 100644 --- a/BITSWAP.md +++ b/BITSWAP.md @@ -199,7 +199,7 @@ Bitswap 1.3.0 extends the Bitswap 1.2.0 protocol with the following changes: 1. Having a list of tokens that may be sent with the message and referenced within the message 2. Allowing each entry in the wantlist to contain a set of tokens 3. Allowing responses (both BlockPresences and Blocks) to contain a set of tokens -4. Adding an `AuthRequired` BlockPresence +4. Adding an `TokenErr` BlockPresence 5. Adding a `BlockTooBig` BlockPresence ### Interaction Pattern From add1c6a646416063bf2593d8b8ca384a8e68bb93 Mon Sep 17 00:00:00 2001 From: Adin Schmahmann Date: Fri, 26 Aug 2022 13:53:55 -0400 Subject: [PATCH 4/4] make linter happy --- BITSWAP.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/BITSWAP.md b/BITSWAP.md index 6c74a7bb5..549ad62c2 100644 --- a/BITSWAP.md +++ b/BITSWAP.md @@ -215,10 +215,10 @@ Given that a client C wants to fetch data from some server S: 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) 1. For each of the items that S sends back Blocks or BlockPresences for they may append any `tokens` they want 2. If C sends S a Have request for data S has but is not currently willing to give to C, S may respond with an `AuthRequired` BlockPresence - 1. For each of the items that S sends back Blocks or BlockPresences for they may append any `tokens` they want. Recommended tokens include those that would inform C how they could convince S to give them access to the blocks they want. - 2. If C sends S a Have request for data S does not have (or has but is not willing to tell C it has) 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. If C asked for a block that S has but it is bigger than the maximum block size it should return `BlockTooBig` + 1. For each of the items that S sends back Blocks or BlockPresences for they may append any `tokens` they want. Recommended tokens include those that would inform C how they could convince S to give them access to the blocks they want. + 2. If C sends S a Have request for data S does not have (or has but is not willing to tell C it has) 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. If C asked for a block that S has but it is bigger than the maximum block size it should return `BlockTooBig` 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. ### Tokens @@ -228,13 +228,13 @@ The major change in this protocol version is the introduction of the ability to Users who require additional codes for their new token formats should do one of: - Register their code in the table - For non-deployed testing purposes only - use a code in the application reserved range of the code table - - Note: if codes in the application reserved range will not be reservable in the code table which means that the code may conflict with another one used in the ecosystem which could cause application problems on collision. It is high recommended to not use these codes outside of testing or early development. + - Note: if codes in the application reserved range will not be reservable in the code table which means that the code may conflict with another one used in the ecosystem which could cause application problems on collision. It is high recommended to not use these codes outside of testing or early development. To save space within the message the list of tokens used within the message are declared within the top level message and all other references to tokens are instead to the indices within the token list in the top level message. ### Wire Format -``` +```protobuf message Message { message Wantlist { @@ -245,14 +245,14 @@ message Message { message Entry { bytes block = 1; // CID of the block - int32 priority = 2; // the priority (normalized). default to 1 + 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 tokens int32 = 7; // the indices of the tokens in the token list - } + } - repeated Entry entries = 1; // a list of wantlist entries + repeated Entry entries = 1; // a list of wantlist entries bool full = 2; // whether this is the full wantlist. default to false } message Block { @@ -281,7 +281,7 @@ message Message { } ``` -# Implementations +## Implementations - -