referrerpolicy=no-referrer-when-downgrade

sc_rpc_spec_v2/bitswap/
bitswap.rs

1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: GPL-3.0-or-later WITH Classpath-exception-2.0
5
6// This program is free software: you can redistribute it and/or modify
7// it under the terms of the GNU General Public License as published by
8// the Free Software Foundation, either version 3 of the License, or
9// (at your option) any later version.
10
11// This program is distributed in the hope that it will be useful,
12// but WITHOUT ANY WARRANTY; without even the implied warranty of
13// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14// GNU General Public License for more details.
15
16// You should have received a copy of the GNU General Public License
17// along with this program. If not, see <https://www.gnu.org/licenses/>.
18
19//! Implementation of the bitswap RPC methods.
20//!
21//! See the JSON-RPC interface spec:
22//! - <https://github.com/paritytech/json-rpc-interface-spec/blob/main/src/api/bitswap_unstable_get.md>
23//! - <https://github.com/paritytech/json-rpc-interface-spec/blob/main/src/api/bitswap_unstable_stream.md>
24//! - <https://github.com/paritytech/json-rpc-interface-spec/blob/main/src/api/bitswap_unstable_unstream.md>
25
26use crate::{
27	bitswap::{
28		api::{BitswapApiServer, StreamEvent},
29		error::Error,
30	},
31	SubscriptionTaskExecutor,
32};
33use cid::Cid;
34use jsonrpsee::{core::RpcResult, types::ErrorObject, PendingSubscriptionSink};
35use multihash_codetable::Code;
36use sc_client_api::BlockBackend;
37use sc_rpc::utils::Subscription;
38use sp_core::H256;
39use sp_runtime::traits::Block as BlockT;
40use std::{collections::HashSet, sync::Arc};
41
42/// Log target for this file. Filterable independently of the rest of `rpc-spec-v2`, matching
43/// the `rpc-spec-v2::<module>` convention from `archive/archive.rs:58`.
44const LOG_TARGET: &str = "rpc-spec-v2::bitswap";
45
46/// Maximum number of CIDs accepted by `bitswap_unstable_stream` in a single subscription. Bounds
47/// worst-case response at ≤128 MiB (64 × 2 MiB/chunk). Spec only requires ≥16.
48pub const MAX_CIDS_PER_REQUEST: usize = 64;
49
50/// Bitswap RPC implementation.
51pub struct Bitswap<Block, Client> {
52	client: Arc<Client>,
53	sync_oracle: Arc<dyn sp_consensus::SyncOracle + Send + Sync>,
54	executor: SubscriptionTaskExecutor,
55	_phantom: std::marker::PhantomData<Block>,
56}
57
58impl<Block, Client> Bitswap<Block, Client> {
59	/// Creates a new [`Bitswap`] instance.
60	pub fn new(
61		client: Arc<Client>,
62		sync_oracle: Arc<dyn sp_consensus::SyncOracle + Send + Sync>,
63		executor: SubscriptionTaskExecutor,
64	) -> Self {
65		Self { client, sync_oracle, executor, _phantom: std::marker::PhantomData }
66	}
67}
68
69/// Parse a CID string and validate it (CIDv1, sha2-256 / blake2b-256 / keccak-256, 32-byte digest).
70fn parse_and_validate_cid(cid_str: &str) -> Result<H256, Error> {
71	let cid = Cid::try_from(cid_str).map_err(|e| Error::InvalidCid(format!("{e}")))?;
72
73	// Only CIDv1 version is supported according to the spec.
74	if cid.version() != cid::Version::V1 {
75		return Err(Error::InvalidCid("Only CIDv1 is supported".into()));
76	}
77
78	let hash = cid.hash();
79
80	// Only sha2-256, blake2b-256 & keccak-256 hash functions are supported according to the spec.
81	if hash.code() != u64::from(Code::Sha2_256) &&
82		hash.code() != u64::from(Code::Blake2b256) &&
83		hash.code() != u64::from(Code::Keccak256)
84	{
85		return Err(Error::InvalidCid(
86			"Only sha2-256, blake2b-256 & keccak-256 hash functions are supported".into(),
87		));
88	}
89
90	// `H256::from_slice` panics below if the size is incorrect, so double-check the size is
91	// correct, even though we checked the hash function type above.
92	if hash.size() != 32 {
93		return Err(Error::InvalidCid("Only 256-bit hash digests are supported".into()));
94	}
95
96	Ok(H256::from_slice(hash.digest()))
97}
98
99impl<Block, Client> BitswapApiServer for Bitswap<Block, Client>
100where
101	Block: BlockT,
102	Client: BlockBackend<Block> + Send + Sync + 'static,
103{
104	fn bitswap_unstable_get(&self, cid_str: String) -> RpcResult<String> {
105		log::trace!(target: LOG_TARGET, "bitswap_unstable_get cid={cid_str}");
106		let digest = match parse_and_validate_cid(&cid_str) {
107			Ok(d) => d,
108			Err(e) => {
109				log::trace!(target: LOG_TARGET, "bitswap_unstable_get reject cid={cid_str} reason=invalid_cid: {e}");
110				return Err(e.into());
111			},
112		};
113
114		match lookup_by_digest(&self.client, self.sync_oracle.is_major_syncing(), digest) {
115			Ok(value) => {
116				log::trace!(
117					target: LOG_TARGET,
118					"bitswap_unstable_get hit cid={cid_str} bytes={}",
119					// `value` is hex-encoded with `0x` prefix; payload bytes = (len-2)/2.
120					value.len().saturating_sub(2) / 2,
121				);
122				Ok(value)
123			},
124			Err(e) => {
125				log::trace!(target: LOG_TARGET, "bitswap_unstable_get miss cid={cid_str} reason={e}");
126				Err(e.into())
127			},
128		}
129	}
130
131	fn bitswap_unstable_stream(&self, pending: PendingSubscriptionSink, cids: Vec<String>) {
132		let client = self.client.clone();
133		let sync_oracle = self.sync_oracle.clone();
134
135		let fut = async move {
136			let cids_len = cids.len();
137			log::trace!(target: LOG_TARGET, "bitswap_unstable_stream open cids={cids_len}");
138
139			// Top-level validation. Per the spec, all three structural rejections happen
140			// before the subscription is accepted, so no events are ever emitted on these
141			// paths.
142			if cids.is_empty() {
143				log::trace!(target: LOG_TARGET, "bitswap_unstable_stream reject reason=empty_cids");
144				pending.reject(Error::EmptyCids).await;
145				return;
146			}
147			if cids_len > MAX_CIDS_PER_REQUEST {
148				log::trace!(
149					target: LOG_TARGET,
150					"bitswap_unstable_stream reject reason=too_many_cids got={cids_len} max={MAX_CIDS_PER_REQUEST}",
151				);
152				pending
153					.reject(Error::TooManyCids { max: MAX_CIDS_PER_REQUEST, got: cids_len })
154					.await;
155				return;
156			}
157			let parsed = match parse_and_dedup(cids) {
158				Ok(p) => p,
159				Err(e) => {
160					log::trace!(target: LOG_TARGET, "bitswap_unstable_stream reject reason=duplicate_cids");
161					pending.reject(e).await;
162					return;
163				},
164			};
165			let is_major_syncing = sync_oracle.is_major_syncing();
166
167			let Ok(sink) = pending.accept().await.map(Subscription::from) else { return };
168
169			for (cid_str, parse_result) in parsed {
170				let event = match parse_result {
171					Ok(digest) => match lookup_by_digest(&client, is_major_syncing, digest) {
172						Ok(value) => {
173							log::trace!(
174								target: LOG_TARGET,
175								"bitswap_unstable_stream item cid={cid_str} bytes={}",
176								// `value` is hex-encoded with `0x` prefix; payload bytes = (len-2)/2.
177								value.len().saturating_sub(2) / 2,
178							);
179							StreamEvent::StreamItem { cid: cid_str, value }
180						},
181						Err(e) => {
182							log::trace!(
183								target: LOG_TARGET,
184								"bitswap_unstable_stream item-error cid={cid_str} reason={e}",
185							);
186							stream_item_error(cid_str, e)
187						},
188					},
189					Err(e) => {
190						log::trace!(
191							target: LOG_TARGET,
192							"bitswap_unstable_stream item-error cid={cid_str} reason=invalid_cid: {e}",
193						);
194						stream_item_error(cid_str, e)
195					},
196				};
197				// A send error means the client unsubscribed or disconnected. The spec says
198				// `streamDone` must NOT be emitted on cancellation, so we just exit.
199				if sink.send(&event).await.is_err() {
200					log::trace!(target: LOG_TARGET, "bitswap_unstable_stream cancelled (sink closed)");
201					return;
202				}
203			}
204
205			// All per-CID events emitted successfully — send the end-of-stream marker.
206			// Ignore a send error here: the client may have unsubscribed in the window
207			// between the final per-CID event and this `streamDone`, and that's fine.
208			let _ = sink.send(&StreamEvent::StreamDone).await;
209			log::trace!(target: LOG_TARGET, "bitswap_unstable_stream done cids={cids_len}");
210		};
211
212		sc_rpc::utils::spawn_subscription_task(&self.executor, fut);
213	}
214}
215
216/// Render an [`Error`] as a [`StreamEvent::StreamItemError`] for the given CID, using the
217/// standard JSON-RPC error mapping defined in [`super::error`].
218fn stream_item_error(cid: String, e: Error) -> StreamEvent {
219	let obj = ErrorObject::from(e);
220	StreamEvent::StreamItemError { cid, code: obj.code(), message: obj.message().to_string() }
221}
222
223/// Parse all input CIDs and reject duplicates. Two-stage detection:
224/// 1. Literal-string dedup catches identical inputs before any parsing.
225/// 2. Digest dedup catches different strings that decode to the same data.
226///
227/// **Invariant**: when this returns `Ok(out)`, no two `Ok(_)` entries in `out` carry
228/// the same `H256` digest. Detection short-circuits on the first collision via
229/// `Err(Error::DuplicateCids)` *before* the duplicate is appended to `out`.
230fn parse_and_dedup(cids: Vec<String>) -> Result<Vec<(String, Result<H256, Error>)>, Error> {
231	let mut seen_strings: HashSet<String> = HashSet::with_capacity(cids.len());
232	let mut seen_digests: HashSet<H256> = HashSet::with_capacity(cids.len());
233	let mut out = Vec::with_capacity(cids.len());
234
235	for cid_str in cids {
236		// Stage A: literal-string dedup. Catches `[A, A]` and `["bad", "bad"]` —
237		// no parsing required.
238		if !seen_strings.insert(cid_str.clone()) {
239			return Err(Error::DuplicateCids);
240		}
241		let parsed = parse_and_validate_cid(&cid_str);
242		// Stage B: digest dedup. Catches `[A, B]` where A and B are distinct strings
243		// encoding the same data.
244		if let Ok(digest) = &parsed {
245			if !seen_digests.insert(*digest) {
246				return Err(Error::DuplicateCids);
247			}
248		}
249		out.push((cid_str, parsed));
250	}
251
252	Ok(out)
253}
254
255/// DB lookup for a parsed digest.
256///
257/// On a miss, distinguishes "not yet synced" (`MajorSyncing` → `-32812 FailRetryBackoff`,
258/// transient: caller should retry with backoff) from "permanently absent"
259/// (`NotFound` → `-32810 Fail`).
260fn lookup_by_digest<Block, Client>(
261	client: &Arc<Client>,
262	is_major_syncing: bool,
263	digest: H256,
264) -> Result<String, Error>
265where
266	Block: BlockT,
267	Client: BlockBackend<Block> + Send + Sync + 'static,
268{
269	match client.indexed_transaction(digest) {
270		Ok(Some(data)) => Ok(crate::hex_string(&data)),
271		Ok(None) => {
272			if is_major_syncing {
273				Err(Error::MajorSyncing)
274			} else {
275				Err(Error::NotFound)
276			}
277		},
278		Err(err) => {
279			log::warn!(target: LOG_TARGET, "Indexed transaction fetch failed: {err:?}");
280			Err(Error::Internal(err))
281		},
282	}
283}