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}