jam_std_common/

rpc.rs

use jam_types::{CoreIndex, Hash, ServiceId, Slot};
use jsonrpsee::{
	core::{RpcResult, SubscriptionResult},
	proc_macros::rpc,
};

/// 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: Hash,
	pub slot: u32,
	pub value: T,
}

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

#[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<([u8; 32], u32)>;

	/// Subscribe to updates of the head of the "best" chain, as returned by `bestBlock`.
	#[subscription(name = "subscribeBestBlock", item = ([u8; 32], u32))]
	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<([u8; 32], u32)>;

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

	/// Returns the header hash and slot of the parent of the block with the given header hash, or
	/// `None` if this is not known.
	#[method(name = "parent")]
	fn parent(&self, header_hash: Hash) -> RpcResult<Option<([u8; 32], u32)>>;

	/// Returns the posterior state root of the block with the given header hash, or `None` if this
	/// is not known.
	#[method(name = "stateRoot")]
	fn state_root(&self, header_hash: Hash) -> RpcResult<Option<[u8; 32]>>;

	/// 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. `None` is returned if the block's posterior state
	/// is not known.
	#[method(name = "statistics")]
	fn statistics(&self, header_hash: Hash) -> 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: Hash, id: u32) -> 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 info may never be included in the finalized chain.
	///
	/// The data are encoded as per the GP.
	#[subscription(name = "subscribeServiceData", item = StateUpdate<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: Hash,
		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: Hash,
		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 `preimage` 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: Hash,
		id: ServiceId,
		hash: Hash,
		len: u32,
	) -> RpcResult<Option<Vec<Slot>>>;

	/// 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 `request` 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, or `None` if this is not
	/// known.
	#[method(name = "beefyRoot")]
	fn beefy_root(&self, header_hash: Hash) -> RpcResult<Option<[u8; 32]>>;

	/// 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.
	#[method(name = "submitPreimage")]
	async fn submit_preimage(
		&self,
		service: ServiceId,
		preimage: Vec<u8>,
		require_block: Hash,
	) -> 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: Hash) -> RpcResult<Vec<ServiceId>>;
}