sp_hop/
lib.rs

1// This file is part of Substrate.
2
3// Copyright (C) Parity Technologies (UK) Ltd.
4// SPDX-License-Identifier: Apache-2.0
5
6// Licensed under the Apache License, Version 2.0 (the "License");
7// you may not use this file except in compliance with the License.
8// You may obtain a copy of the License at
9//
10// 	http://www.apache.org/licenses/LICENSE-2.0
11//
12// Unless required by applicable law or agreed to in writing, software
13// distributed under the License is distributed on an "AS IS" BASIS,
14// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15// See the License for the specific language governing permissions and
16// limitations under the License.
17
18//! HOP (Hand-Off Protocol) primitives.
19//!
20//! Contains the runtime API trait for HOP — authorization checks and promotion
21//! of ephemeral pool data to on-chain storage.
22
23#![cfg_attr(not(feature = "std"), no_std)]
24
25extern crate alloc;
26
27sp_api::decl_runtime_apis! {
28	/// Runtime API for HOP.
29	///
30	/// Runtimes that support HOP implement this API so the node can check
31	/// authorization and promote near-expiry pool entries to on-chain storage.
32	#[api_version(1)]
33	pub trait HopRuntimeApi<AccountId> where AccountId: codec::Codec {
34		/// Maximum blob size (in bytes) the runtime will accept for promotion.
35		///
36		/// Authoritative — the node rejects oversized submissions at the RPC
37		/// boundary using this value, before any per-account authorization lookup
38		/// or signature verification.
39		fn max_promotion_size() -> u32;
40		/// Whether `who` may submit a HOP blob of `data_len` bytes for promotion.
41		///
42		/// Returns `false` for any per-account "not allowed" reason — unknown
43		/// account, exhausted quota, size outside a per-account tier, etc. The
44		/// absolute per-submission size cap is the responsibility of
45		/// [`Self::max_promotion_size`]; this hook is for per-account policy.
46		fn can_account_promote(who: AccountId, data_len: u32) -> bool;
47		/// Construct an unsigned promotion extrinsic carrying the user's submit-time
48		/// (in milliseconds from the Unix epoch), signer, signature, and timestamp
49		/// so the runtime pallet can verify consent on-chain.
50		///
51		/// `submit_timestamp` is bound into the signed payload. Implementing
52		/// runtimes **must** reject promotions whose timestamp is outside a
53		/// tolerance window around the current on-chain clock — otherwise the
54		/// same `(data, signer, signature)` tuple can be replayed indefinitely
55		/// from the collator's persisted metadata. The width of the window is a
56		/// runtime policy decision (clock skew + max acceptable promotion
57		/// latency); a few hours is a reasonable upper bound.
58		fn create_promotion_extrinsic(
59			data: alloc::vec::Vec<u8>,
60			signer: sp_runtime::MultiSigner,
61			signature: sp_runtime::MultiSignature,
62			submit_timestamp: u64,
63		) -> Block::Extrinsic;
64		/// Whether the content with `hash` is already stored on-chain.
65		///
66		/// Used by HOP's maintenance task to confirm that a previously submitted
67		/// promotion extrinsic actually made it into a block.
68		fn is_promoted_on_chain(hash: [u8; 32]) -> bool;
69	}
70}
sp_hop/lib.rs

sp_hop/
lib.rs
