Add `bitswap_v1_get` method by dmitry-markin · Pull Request #183 · paritytech/json-rpc-interface-spec

dmitry-markin · 2026-03-24T15:46:00Z

This PR standardizes bitswap_v1_get RPC used to download data from Polkadot Bulletin Chain. Calling this method is equivalent to downloading the data from a full node via Bitswap protocol. Both light & full nodes must provide this endpoint.

Follow-ups

bitswap_v1_stream method for requesting streaming of multiple Bitswap chunks (multiple CIDs) will be introduced in a separate PR.

CC @ERussel

lexnv · 2026-03-24T16:19:34Z

+
+
+**Return value**: String containing the requested data chunk, hexadecimal-encoded. Always starts with
+`0x...`.


When the CID maps to an empty block we return 0x?

Yes, but in practice it is not possible to store empty indexed transaction.

lexnv · 2026-03-24T16:20:14Z

+**Parameters**:
+
+- `cid`: CID of the data chunk requested serialized in a [string format](https://github.com/multiformats/cid/blob/edb1c5294ad2d8257812d7ded4941c3e0fafccf3/README.md#variant---stringified-form).  
+  Only CIDv1 version in `base32` multibase encoding (string starting from `b...`) is supported.  


Do we plan to extend these in the near future?

This is the default string representation of a CID and CIDv1 is the latest default as well, so we are free to define this as a requirement here and support nothing else.

lexnv · 2026-03-24T16:28:16Z

@@ -0,0 +1,8 @@
+# Introduction
+
+The functions with `bitswap` prefix allow fetching data chunks from the storage given their CID,


Nit: I would add a tiny mention, "For the implementation details of the bitswap implementation see... url-link"

Not sure what implementation to include (litep2p / substrate / smoldot?), plus the implementation may change / get moved to another place and get outdated.

bkontur · 2026-03-25T12:19:19Z

    - [archive_v1_storage](api/archive_v1_storage.md)
    - [archive_v1_storageDiff](api/archive_v1_storageDiff.md)
+  - [bitswap](api/bitswap.md)
+    - [bitswap_v1_get](api/bitswap_v1_get.md)


@dmitry-markin what about the stream version we discussed before?

It will go as a separate PR. Going to open it when the streaming version is added to smoldot to be sure we don't miss anything important.

Meanwhile, the RPC endpoint in the full node gained the priority, so I will implement it first before going back to streaming in smoldot.

lexnv · 2026-03-25T13:37:31Z

+```
+
+Please note again that only the `code` and corresponding error retry categories in the table above
+are stable. Everything else is provided for debugging purposes only, subject to change, and must not


In this case we could simplify the retur error code and incldue all details into the serialized message? I think chainHead follows a similar impl

I would go a JSON-RPC standard way of returning the data on success and using standard JSON-RPC error codes like -3602 for "invalid params" already familiar to web app developers.

Edit: I see what you mean, yep it makes sense

dmitry-markin · 2026-03-25T16:24:42Z

+| -32602 | `InvalidParams`     | Invalid/unsupported CID was passed. Must not retry      |
+| -32810 | `Fail`              | Permanent failure for this request, e.g. data not found |
+| -32811 | `FailRetry`         | Transient failure, can retry immediately                |
+| -32812 | `FailRetryBackoff`  | Transient failure, can retry with a delay               |


Only -32602 code here is standard JSON-RPC error code, and for application-defined error codes we can use something simple like -1, -2, -3. Unless we reserve "easy" codes for some common json-rpc-interface-spec errors — then we need to use unique codes per method to be consistent.

Also, according to JSON-RPC 2.0 spec, the messages for standard codes (like InvalidParams in our case) seem to be standard ("Invalid params"). smoldot hardcodes a message for invalid params to "Invalid method parameter(s)." Theoretically, we can replace the hardcoded message with a human-readable description of a specific error — then we won't need to introduce a separate field data.details for a human-readable message in this particular case.

E.g., we can use a custom message Invalid params: {error} and remove data.details field completely.

"E.g., we can use a custom message Invalid params: {error} and remove data.details field completely."

Yep, lets only keep the code + message, then we can extend the message with all the other datails from data

The design intiiatly showed the data variant:

{"code": -32812, "message": "No Bitswap peers connected", "data": {"variant": "NoPeers"}}

It could be simplified such that we place all details into the serialized message:

{"code": -32812, "message": "No Bitswap peers connected: No peers"}

The data.variant actually makes sense, because it is suitable for structured logging in grafana etc. It is synonymous to message, not supplementing it.

But let's get rid of data.details completely and put the human-readable info into message for consistency of InvalidParams case with other cases.

dmitry-markin · 2026-03-26T15:26:11Z

Added a minor clarification regarding limiting the number of retry attempts, and it rendered the approvals obsolete. @lexnv @x3c41a can you approve again, please?

lexnv

LGTM! Thanks @dmitry-markin for spec here 🙏

Add bitswap_v1_get method

691ec1f

dmitry-markin requested review from bkontur and lexnv March 24, 2026 15:46

dmitry-markin added 2 commits March 24, 2026 17:49

Add newlines

af690e7

Warning about detailed error information

aaf1e46

lexnv reviewed Mar 24, 2026

View reviewed changes

Comment thread src/api/bitswap.md

lexnv reviewed Mar 24, 2026

View reviewed changes

Comment thread src/api/bitswap_v1_get.md Outdated

lexnv reviewed Mar 24, 2026

View reviewed changes

Comment thread src/api/bitswap.md

lexnv reviewed Mar 24, 2026

View reviewed changes

dmitry-markin added 2 commits March 25, 2026 13:49

Apply review suggestions

15013be

minor: make sure data.variant examples are incomplete

7be3526

bkontur reviewed Mar 25, 2026

View reviewed changes

lexnv reviewed Mar 25, 2026

View reviewed changes

dmitry-markin commented Mar 25, 2026

View reviewed changes

dmitry-markin added 2 commits March 26, 2026 11:19

Get rid of data.details

c13a8f4

minor: newline

9d6b7d1

dmitry-markin mentioned this pull request Mar 26, 2026

Implement bitswap_v1_get RPC method paritytech/polkadot-sdk#11521

Merged

lexnv previously approved these changes Mar 26, 2026

View reviewed changes

x3c41a previously approved these changes Mar 26, 2026

View reviewed changes

Limit the total number of retries

5fd4b58

dmitry-markin dismissed stale reviews from x3c41a and lexnv via 5fd4b58 March 26, 2026 15:18

x3c41a approved these changes Mar 26, 2026

View reviewed changes

lexnv approved these changes Mar 26, 2026

View reviewed changes

dmitry-markin merged commit 06e3bae into main Mar 27, 2026
3 checks passed

dmitry-markin deleted the dm-bitswap-v1-get branch March 27, 2026 11:18



		Return value: String containing the requested data chunk, hexadecimal-encoded. Always starts with
		`0x...`.

		@@ -0,0 +1,8 @@
		# Introduction

		The functions with `bitswap` prefix allow fetching data chunks from the storage given their CID,

Conversation

dmitry-markin commented Mar 24, 2026

Follow-ups

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lexnv Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmitry-markin Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmitry-markin Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lexnv Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmitry-markin Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmitry-markin commented Mar 26, 2026

Uh oh!

lexnv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lexnv Mar 25, 2026 •

edited

Loading

dmitry-markin Mar 25, 2026 •

edited

Loading

dmitry-markin Mar 25, 2026 •

edited

Loading

lexnv Mar 26, 2026 •

edited

Loading

dmitry-markin Mar 26, 2026 •

edited

Loading