jam_std_common/

rpc.rs

use jam_types::{
	CoreIndex, Hash, HeaderHash, MmrPeakHash, Segment, SegmentTreeRoot, ServiceId, Slot,
	StateRootHash, WorkPackageHash,
};
use jsonrpsee::{
	core::{RpcResult, SubscriptionResult},
	proc_macros::rpc,
};

#[derive(Clone, Copy, serde::Serialize, serde::Deserialize, Debug)]
pub struct BlockDesc {
	pub header_hash: HeaderHash,
	pub slot: Slot,
}

/// An update from a state subscription. `header_hash` and `slot` are of the block whose posterior
/// state contains `value`.
#[derive(serde::Serialize, serde::Deserialize, Debug)]
pub struct StateUpdate<T> {
	pub header_hash: HeaderHash,
	pub slot: Slot,
	pub value: T,
}

#[derive(serde::Serialize, serde::Deserialize, Clone, Debug)]
pub enum VersionedParameters {
	/// Parameters of the chain, version 1.
	V1(crate::Parameters),
}

#[derive(Clone, Copy, serde::Serialize, serde::Deserialize, Debug)]
pub struct SyncState {
	pub num_peers: u32,
	pub status: SyncStatus,
}

#[derive(Clone, Copy, serde::Serialize, serde::Deserialize, Debug, Eq, PartialEq)]
pub enum SyncStatus {
	InProgress,
	Completed,
}

#[rpc(client, server)]
pub trait Rpc {
	/// Parameters of the chain, version 1.
	#[method(name = "parameters")]
	fn parameters(&self) -> RpcResult<VersionedParameters>;

	/// Returns the header hash and slot of the head of the "best" chain.
	#[method(name = "bestBlock")]
	fn best_block(&self) -> RpcResult<BlockDesc>;

	/// Subscribe to updates of the head of the "best" chain, as returned by `bestBlock`.
	#[subscription(name = "subscribeBestBlock", item = BlockDesc)]
	async fn subscribe_best_block(&self) -> SubscriptionResult;

	/// Returns the header hash and slot of the latest finalized block.
	#[method(name = "finalizedBlock")]
	fn finalized_block(&self) -> RpcResult<BlockDesc>;

	/// Subscribe to updates of the latest finalized block, as returned by `finalizedBlock`.
	#[subscription(name = "subscribeFinalizedBlock", item = BlockDesc)]
	async fn subscribe_finalized_block(&self) -> SubscriptionResult;

	/// Returns the header hash and slot of the parent of the block with the given header hash.
	#[method(name = "parent")]
	fn parent(&self, header_hash: HeaderHash) -> RpcResult<BlockDesc>;

	/// Returns the posterior state root of the block with the given header hash.
	#[method(name = "stateRoot")]
	fn state_root(&self, header_hash: HeaderHash) -> RpcResult<StateRootHash>;

	/// Returns the activity statistics stored in the posterior state of the block with the given
	/// header hash.
	///
	/// The statistics are encoded as per the GP.
	#[method(name = "statistics")]
	fn statistics(&self, header_hash: HeaderHash) -> RpcResult<Vec<u8>>;

	/// Subscribe to updates of the activity statistics stored in chain state.
	///
	/// If `finalized` is true, the subscription will track the latest finalized block. If
	/// `finalized` is false, the subscription will track the head of the "best" chain. Note that
	/// in the latter case the reported statistics may never be included in the finalized chain.
	///
	/// The statistics are encoded as per the GP.
	#[subscription(name = "subscribeStatistics", item = StateUpdate<Vec<u8>>)]
	async fn subscribe_statistics(&self, finalized: bool) -> SubscriptionResult;

	/// Returns the storage data for the service of the given service ID.
	///
	/// The data are encoded as per the GP. `None` is returned if there is no value associated with
	/// the given service ID.
	#[method(name = "serviceData")]
	fn service_data(&self, header_hash: HeaderHash, id: ServiceId) -> RpcResult<Option<Vec<u8>>>;

	/// Subscribe to updates of the storage data for the service of the given service ID.
	///
	/// If `finalized` is true, the subscription will track the latest finalized block. If
	/// `finalized` is false, the subscription will track the head of the "best" chain. Note that
	/// in the latter case the reported service data may never be included in the finalized chain.
	///
	/// The `value` field of subscription messages will contain service data encoded as per the GP.
	/// It will be `None` when there is no data associated with the given ID.
	#[subscription(name = "subscribeServiceData", item = StateUpdate<Option<Vec<u8>>>)]
	async fn subscribe_service_data(&self, id: ServiceId, finalized: bool) -> SubscriptionResult;

	/// Returns the value associated with the given service ID and key in the posterior state of
	/// the block with the given header hash.
	///
	/// `None` is returned if there is no value associated with the given service ID and key.
	#[method(name = "serviceValue")]
	fn service_value(
		&self,
		header_hash: HeaderHash,
		id: ServiceId,
		key: Vec<u8>,
	) -> RpcResult<Option<Vec<u8>>>;

	/// Subscribe to updates of the value associated with the given service ID and key.
	///
	/// If `finalized` is true, the subscription will track the latest finalized block. If
	/// `finalized` is false, the subscription will track the head of the "best" chain. Note that
	/// in the latter case reported value changes may never be included in the finalized chain.
	///
	/// The `value` field of subscription messages will be `None` when there is no value associated
	/// with the given service ID and key.
	#[subscription(name = "subscribeServiceValue", item = StateUpdate<Option<Vec<u8>>>)]
	async fn subscribe_service_value(
		&self,
		id: ServiceId,
		key: Vec<u8>,
		finalized: bool,
	) -> SubscriptionResult;

	/// Returns the preimage associated with the given service ID and hash in the posterior state
	/// of the block with the given header hash.
	///
	/// `None` is returned if there is no preimage associated with the given service ID and
	/// hash.
	#[method(name = "servicePreimage")]
	fn service_preimage(
		&self,
		header_hash: HeaderHash,
		id: ServiceId,
		hash: Hash,
	) -> RpcResult<Option<Vec<u8>>>;

	/// Subscribe to updates of the preimage associated with the given service ID and hash.
	///
	/// If `finalized` is true, the subscription will track the latest finalized block. If
	/// `finalized` is false, the subscription will track the head of the "best" chain. Note that
	/// in the latter case reported preimage changes may never be included in the finalized chain.
	///
	/// The `value` field of subscription messages will be `None` when there is no preimage
	/// associated with the given service ID and hash.
	#[subscription(name = "subscribeServicePreimage", item = StateUpdate<Option<Vec<u8>>>)]
	async fn subscribe_service_preimage(
		&self,
		id: ServiceId,
		hash: Hash,
		finalized: bool,
	) -> SubscriptionResult;

	/// Returns the preimage request associated with the given service ID and hash/len in the
	/// posterior state of the block with the given header hash.
	///
	/// `None` is returned if there is no preimage request associated with the given service ID,
	/// hash and length.
	#[method(name = "serviceRequest")]
	fn service_request(
		&self,
		header_hash: HeaderHash,
		id: ServiceId,
		hash: Hash,
		len: u32,
	) -> RpcResult<Option<Vec<Slot>>>;

	/// Subscribe to updates of the preimage request associated with the given service ID and
	/// hash/len.
	///
	/// If `finalized` is true, the subscription will track the latest finalized block. If
	/// `finalized` is false, the subscription will track the head of the "best" chain. Note that
	/// in the latter case reported preimage request changes may never be included in the finalized
	/// chain.
	///
	/// The `value` field of subscription messages will be `None` when there is no preimage request
	/// associated with the given service ID, hash and length.
	#[subscription(name = "subscribeServiceRequest", item = StateUpdate<Option<Vec<Slot>>>)]
	async fn subscribe_service_request(
		&self,
		id: ServiceId,
		hash: Hash,
		len: u32,
		finalized: bool,
	) -> SubscriptionResult;

	/// Returns the BEEFY root of the block with the given header hash.
	#[method(name = "beefyRoot")]
	fn beefy_root(&self, header_hash: HeaderHash) -> RpcResult<MmrPeakHash>;

	/// Submit a work-package to the guarantors currently assigned to the given core.
	#[method(name = "submitWorkPackage")]
	async fn submit_work_package(
		&self,
		core: CoreIndex,
		package: Vec<u8>,
		extrinsics: Vec<Vec<u8>>,
	) -> RpcResult<()>;

	/// Submit a preimage which is being requested by a given service.
	///
	/// Note that this method does not wait for the preimage to be distributed or integrated
	/// on-chain; it returns immediately.
	#[method(name = "submitPreimage")]
	fn submit_preimage(&self, requester: ServiceId, preimage: Vec<u8>) -> RpcResult<()>;

	/// Returns a list of all services currently known to be on JAM. This is a best-effort list and
	/// may not reflect the true state. Nodes could e.g. reasonably hide services which are not
	/// recently active from this list.
	#[method(name = "listServices")]
	fn list_services(&self, header_hash: HeaderHash) -> RpcResult<Vec<ServiceId>>;

	/// Fetches a list of exported segments from the DA layer for the given work package hash.
	#[method(name = "fetchWorkPackageSegments")]
	async fn fetch_work_package_segments(
		&self,
		wp_hash: WorkPackageHash,
		indices: Vec<u16>,
	) -> RpcResult<Vec<Segment>>;

	/// Fetches a list of exported segments from the DA layer for the given segment root hash.
	#[method(name = "fetchSegments")]
	async fn fetch_segments(
		&self,
		segment_root: SegmentTreeRoot,
		indices: Vec<u16>,
	) -> RpcResult<Vec<Segment>>;

	/// Returns the sync status of the node.
	#[method(name = "syncState")]
	fn sync_state(&self) -> RpcResult<SyncState>;

	/// Subscribe to changes in sync status.
	#[subscription(name = "subscribeSyncStatus", item = SyncStatus)]
	async fn subscribe_sync_status(&self) -> SubscriptionResult;
}