referrerpolicy=no-referrer-when-downgrade

sc_rpc_spec_v2/bitswap/
api.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//! API trait for the bitswap RPC methods.
20
21use jsonrpsee::{core::RpcResult, proc_macros::rpc};
22use serde::{Deserialize, Serialize};
23
24/// Per-event payload emitted by [`BitswapApiServer::bitswap_unstable_stream`].
25///
26/// Wire shape is a tagged object distinguished by the `event` field, per the spec:
27/// `{ "event": "streamItem", "cid": "...", "value": "0x..." }`,
28/// `{ "event": "streamItemError", "cid": "...", "code": ..., "message": "..." }`,
29/// `{ "event": "streamDone" }`.
30#[derive(Clone, Debug, Serialize, Deserialize)]
31#[serde(tag = "event", rename_all = "camelCase")]
32pub enum StreamEvent {
33	/// Successful retrieval of a single CID.
34	StreamItem {
35		/// The input CID string, returned verbatim.
36		cid: String,
37		/// Hex-encoded chunk data, always starting with `0x...`.
38		value: String,
39	},
40	/// Failed retrieval of a single CID. The stream continues with the remaining CIDs.
41	StreamItemError {
42		/// The input CID string, returned verbatim.
43		cid: String,
44		/// JSON-RPC error code identifying the retry category.
45		code: i32,
46		/// Human-readable diagnostic message. Implementation-specific; do not rely on in business
47		/// logic.
48		message: String,
49	},
50	/// End-of-stream marker. Emitted exactly once after a per-CID event has been emitted for every
51	/// input CID. Not emitted on client cancellation or disconnect.
52	StreamDone,
53}
54
55#[rpc(client, server)]
56pub trait BitswapApi {
57	/// Retrieve indexed transaction data by CID.
58	///
59	/// Accepts a CIDv1 (base32 multibase-encoded string), extracts the 32-byte hash
60	/// digest, looks up the indexed transaction, and returns hex-encoded data.
61	///
62	/// `bitswap_v1_get` is kept as an alias during the transition to the `unstable_` naming and
63	/// will be removed once clients migrate.
64	#[method(name = "bitswap_unstable_get", aliases = ["bitswap_v1_get"])]
65	fn bitswap_unstable_get(&self, cid: String) -> RpcResult<String>;
66
67	/// Stream chunks as they become available.
68	///
69	/// Emits one [`StreamEvent::StreamItem`] / [`StreamEvent::StreamItemError`] event per input
70	/// CID, in arrival order (the order in which each CID resolves) — **not** input order.
71	/// Clients correlate each event with its request via the embedded `cid`. After the last
72	/// per-CID event, a single [`StreamEvent::StreamDone`] marks end-of-stream. No
73	/// `streamDone` is emitted if the client cancels via the unsubscribe method or disconnects.
74	///
75	/// Top-level rejections (no events emitted, no subscription opened):
76	/// `-32801 TooManyCids`, `-32802 EmptyCids`, `-32803 DuplicateCids`.
77	#[subscription(
78		name = "bitswap_unstable_stream" => "bitswap_unstable_streamEvent",
79		unsubscribe = "bitswap_unstable_unstream",
80		item = StreamEvent,
81	)]
82	fn bitswap_unstable_stream(&self, cids: Vec<String>);
83}