pallet_registrar_relay/

lib.rs

// This file is part of Substrate.

// Copyright (C) Parity Technologies (UK) Ltd.
// SPDX-License-Identifier: Apache-2.0

// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// 	http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

//! # Relay-chain registrar pallet
//!
//! Relay half of the parachain registrar. Runs on the relay chain, applying registrations
//! authorized on a parachain (`pallet-registrar-para`) and driving the relay's legacy `paras`
//! state.
//!
//! ## Two-phase registration
//!
//! Pushing a multi-megabyte validation code through XCM would be wasteful when the parachain can
//! commit to the exact bytes and let anybody upload them here directly, so registration arrives in
//! two pieces:
//!
//! 1. [`Pallet::receive`] takes the parachain's request, which carries the head data plus the hash
//!    and length of the code that is coming, and parks it in [`PendingRegistrations`]. Only
//!    callable by a trusted XCM origin (e.g. the Coretime chain).
//! 2. [`Pallet::apply_authorized_code`] takes the blob itself. It needs no signature: anybody may
//!    push the code, because a pending entry already pins down exactly which bytes are acceptable,
//!    and the parachain has already made the manager pay for them. If the blob matches, the para is
//!    onboarded and the outcome is reported back to the parachain.
//!
//! A registration authorization never times out here. The parachain sends
//! [`MessageToRelayV1::CancelRegistration`] when the manager gives up, this pallet drops the entry
//! and confirms, and the parachain releases the deposit. So the relay chain runs no per-block
//! sweep, and whoever wants the deposit back pays for the round trip. No deposit is taken here.
//!
//! Code upgrade authorizations do lapse instead: no deposit is at stake, and their validity
//! depends on relay-chain state the parachain does not track.
//!
//! ## Locking
//!
//! The relay chain also tells the parachain when a para produces a head, so the chain holding the
//! manager relationship can lock the para. Add this pallet to `paras::Config::OnNewHead`.
//!
//! ## Runtime requirement
//!
//! `apply_authorized_code` authorizes itself through [`frame_support::pallet_macros::authorize`],
//! so the runtime must carry `frame_system::AuthorizeCall` in its transaction extension pipeline.

#![cfg_attr(not(feature = "std"), no_std)]

extern crate alloc;

use alloc::vec::Vec;
use codec::{Decode, DecodeWithMemTracking, Encode, MaxEncodedLen};
use frame_support::{traits::Get, weights::Weight};
pub use pallet::*;
use polkadot_primitives::{HeadData, Id};
use polkadot_runtime_parachains::paras::OnNewHead;
use registrar_primitives::{
	FailureReason, MessageToPara, MessageToParaV1, MessageToRelay, MessageToRelayV1, Outcome,
	ParaId, ParachainRegistrar,
};
use scale_info::TypeInfo;
use sp_core::H256;
pub use weights::WeightInfo;

pub mod weights;

#[cfg(feature = "runtime-benchmarks")]
mod benchmarking;
#[cfg(test)]
mod mock;
#[cfg(test)]
mod tests;

pub trait SendToPara {
	/// Send `message` to the parachain.
	///
	/// `Err(())` means the transport refused the message; callers log and carry on rather than
	/// unwind committed state.
	#[allow(clippy::result_unit_err)]
	fn send(message: MessageToPara) -> Result<(), ()>;
}

#[cfg(feature = "std")]
impl SendToPara for () {
	fn send(_message: MessageToPara) -> Result<(), ()> {
		Ok(())
	}
}

/// A registration the parachain has asked for, waiting on its validation code.
#[derive(
	Encode, Decode, DecodeWithMemTracking, Clone, Eq, PartialEq, TypeInfo, MaxEncodedLen, Debug,
)]
#[scale_info(skip_type_params(MaxHeadDataSize))]
pub struct PendingRegistration<AccountId, MaxHeadDataSize: Get<u32>> {
	/// The id of the [`MessageToRelayV1::Register`] that created this entry, echoed back in the
	/// response once the code arrives.
	pub message_id: u64,
	/// The account managing this registration on the parachain.
	pub manager: AccountId,
	/// The genesis head data, held here until the code arrives.
	pub genesis_head: frame_support::BoundedVec<u8, MaxHeadDataSize>,
	/// Blake2-256 hash the validation code must have.
	pub code_hash: H256,
	/// Exact length the validation code must have; the parachain sized the deposit from it.
	pub code_len: u32,
}

/// [`PendingRegistration`] as this pallet stores it.
pub type PendingRegistrationOf<T> =
	PendingRegistration<<T as frame_system::Config>::AccountId, <T as Config>::MaxHeadDataSize>;

#[frame_support::pallet]
pub mod pallet {
	use super::*;
	use frame_support::pallet_prelude::*;
	use frame_system::pallet_prelude::*;
	use sp_runtime::traits::{BlakeTwo256, Hash};

	#[pallet::config]
	pub trait Config: frame_system::Config {
		/// The overarching event type.
		#[allow(deprecated)]
		type RuntimeEvent: From<Event<Self>> + IsType<<Self as frame_system::Config>::RuntimeEvent>;

		/// A trusted parachain parachain authorized to drive registrations.
		type ParaOrigin: EnsureOrigin<Self::RuntimeOrigin>;

		/// Sends messages to the parachain.
		type SendToPara: SendToPara;

		/// The relay chain's parachain registry.
		type Registrar: ParachainRegistrar<AccountId = Self::AccountId>;

		/// The largest head data this pallet will hold onto while waiting for code.
		///
		/// Should be at least the relay chain's `max_head_data_size`.
		#[pallet::constant]
		type MaxHeadDataSize: Get<u32>;

		/// The largest validation code [`Pallet::apply_authorized_code`] will accept.
		///
		/// Should be at least the relay chain's `max_code_size`.
		#[pallet::constant]
		type MaxCodeSize: Get<u32>;

		/// How many registrations may be waiting on their code at once.
		///
		/// Bounds the head data stored here, where no deposit is held.
		#[pallet::constant]
		type MaxPendingRegistrations: Get<u32>;

		/// Priority given to a valid [`Pallet::apply_authorized_code`] in the transaction pool.
		#[pallet::constant]
		type UnsignedPriority: Get<TransactionPriority>;

		/// Weight information for the extrinsics in this pallet.
		type WeightInfo: WeightInfo;
	}

	#[pallet::pallet]
	pub struct Pallet<T>(_);

	/// Registrations waiting on their validation code, by para id.
	///
	/// Counted so [`Config::MaxPendingRegistrations`] can be enforced with a single read.
	#[pallet::storage]
	pub type PendingRegistrations<T: Config> =
		CountedStorageMap<_, Blake2_128Concat, ParaId, PendingRegistrationOf<T>>;

	/// Paras registered here that have not produced their first head yet, by para id.
	#[pallet::storage]
	pub type AwaitingFirstHead<T: Config> = StorageMap<_, Blake2_128Concat, ParaId, ()>;

	#[pallet::event]
	#[pallet::generate_deposit(pub(super) fn deposit_event)]
	pub enum Event<T: Config> {
		/// A registration request was accepted and is waiting on its validation code.
		RegistrationPending { para_id: ParaId, message_id: u64, code_hash: H256 },
		/// A registration request was rejected out of hand.
		RegistrationRejected { para_id: ParaId, message_id: u64, reason: FailureReason },
		/// A para was onboarded.
		Registered { para_id: ParaId, message_id: u64, manager: T::AccountId },
		/// An authorization was dropped at the parachain's request.
		AuthorizationCancelled { para_id: ParaId, message_id: u64 },
		/// A cancellation arrived after the para had already been onboarded, and was refused.
		CancellationRefused { para_id: ParaId, message_id: u64 },
		/// A report could not be sent back to the parachain.
		ReportFailed { para_id: ParaId, message_id: u64 },
		/// The parachain was told that a para produced its first head.
		HeadNoted { para_id: ParaId },
		/// A para's first head could not be reported to the parachain.
		HeadNoteFailed { para_id: ParaId },
	}

	#[pallet::error]
	pub enum Error<T> {
		/// No registration is waiting on code for this para id.
		NothingPending,
		/// The validation code does not match the hash the parachain committed to.
		CodeHashMismatch,
		/// The validation code is not the length the parachain committed to.
		CodeLenMismatch,
		/// The validation code is larger than this pallet will accept.
		CodeTooLarge,
	}

	#[pallet::call]
	impl<T: Config> Pallet<T> {
		/// Accept a control-plane message from the parachain's registrar pallet.
		///
		/// The origin is a trusted XCM origin, not a user. A rejected request still returns `Ok`:
		/// failing would roll back the rejection report and leave the parachain holding a deposit
		/// for news that never comes.
		#[pallet::call_index(0)]
		#[pallet::weight(match message {
			MessageToRelay::V1(MessageToRelayV1::Register { genesis_head, .. }) =>
				T::WeightInfo::receive_register(genesis_head.len() as u32),
			MessageToRelay::V1(MessageToRelayV1::CancelRegistration { .. }) =>
				T::WeightInfo::receive_cancel_registration(),
			MessageToRelay::V1(MessageToRelayV1::Deregister { .. }) |
			MessageToRelay::V1(MessageToRelayV1::AuthorizeCodeUpgrade { .. }) |
			MessageToRelay::V1(MessageToRelayV1::SetCurrentHead { .. }) => Weight::MAX,
		})]
		pub fn receive(
			origin: OriginFor<T>,
			message: MessageToRelay<T::AccountId>,
		) -> DispatchResult {
			T::ParaOrigin::ensure_origin_or_root(origin)?;

			match message {
				MessageToRelay::V1(MessageToRelayV1::Register {
					para_id,
					message_id,
					manager,
					genesis_head,
					code_hash,
					code_len,
				}) => Self::on_register_request(
					para_id,
					message_id,
					manager,
					genesis_head,
					code_hash,
					code_len,
				),
				MessageToRelay::V1(MessageToRelayV1::CancelRegistration {
					para_id,
					message_id,
				}) => Self::on_cancel_request(para_id, message_id),
				MessageToRelay::V1(MessageToRelayV1::Deregister { para_id, message_id }) => {
					Self::on_deregister_request(para_id, message_id)
				},
				MessageToRelay::V1(MessageToRelayV1::AuthorizeCodeUpgrade {
					para_id,
					message_id,
					code_hash,
					code_len,
				}) => Self::on_authorize_code_upgrade_request(
					para_id, message_id, code_hash, code_len,
				),
				MessageToRelay::V1(MessageToRelayV1::SetCurrentHead {
					para_id,
					message_id,
					head,
				}) => Self::on_set_current_head_request(para_id, message_id, head),
			}

			Ok(())
		}

		/// Upload the validation code for a pending authorization, onboarding the para.
		///
		/// Unsigned and free: the pending entry already pins the exact bytes accepted, and the
		/// manager has paid for them on the parachain.
		#[pallet::call_index(1)]
		#[pallet::authorize(Self::authorize_apply_authorized_code)]
		#[pallet::weight_of_authorize(T::WeightInfo::authorize_apply_authorized_code(validation_code.len() as u32))]
		#[pallet::weight(T::WeightInfo::apply_authorized_code(validation_code.len() as u32))]
		pub fn apply_authorized_code(
			origin: OriginFor<T>,
			para_id: ParaId,
			validation_code: Vec<u8>,
		) -> DispatchResultWithPostInfo {
			ensure_authorized(origin)?;

			let pending = Self::validate_pending_code(para_id, &validation_code)?;

			T::Registrar::register(
				pending.manager.clone(),
				para_id,
				pending.genesis_head.into_inner(),
				validation_code,
			)?;
			PendingRegistrations::<T>::remove(para_id);

			let message_id = pending.message_id;
			Self::report_registration(para_id, message_id, Ok(()));
			Self::deposit_event(Event::Registered {
				para_id,
				message_id,
				manager: pending.manager,
			});
			Ok(Pays::No.into())
		}
	}

	impl<T: Config> Pallet<T> {
		/// Validate an unsigned [`Pallet::apply_authorized_code`], with the same checks as the
		/// dispatch so the pool and the block cannot disagree.
		// `#[pallet::authorize]` passes the call arguments by reference, so the types must mirror
		// the call's exactly; `&[u8]` would not compile.
		#[allow(clippy::ptr_arg)]
		pub fn authorize_apply_authorized_code(
			_source: TransactionSource,
			para_id: &ParaId,
			validation_code: &Vec<u8>,
		) -> TransactionValidityWithRefund {
			let pending = Self::validate_pending_code(*para_id, validation_code)
				.map_err(|e| InvalidTransaction::Custom(Self::err_to_code(e)))?;

			// No longevity bound: an authorization does not expire, so the transaction stays valid
			// until the code is applied or the parachain cancels, and revalidation drops it then.
			let validity = ValidTransaction::with_tag_prefix("RegistrarApplyAuthorizedCode")
				.priority(T::UnsignedPriority::get())
				.and_provides((*para_id, pending.code_hash))
				.propagate(true)
				.build()?;

			Ok((validity, Weight::zero()))
		}

		/// Apply a registration request from the parachain, accepting or rejecting it.
		fn on_register_request(
			para_id: ParaId,
			message_id: u64,
			manager: T::AccountId,
			genesis_head: Vec<u8>,
			code_hash: H256,
			code_len: u32,
		) {
			let Ok(head_len) = u32::try_from(genesis_head.len()) else {
				return Self::reject(para_id, message_id, FailureReason::InvalidOnboardingData);
			};

			if T::Registrar::is_registered(para_id) ||
				PendingRegistrations::<T>::contains_key(para_id)
			{
				return Self::reject(para_id, message_id, FailureReason::AlreadyRegistered);
			}
			if PendingRegistrations::<T>::count() >= T::MaxPendingRegistrations::get() {
				return Self::reject(para_id, message_id, FailureReason::TooManyPending);
			}
			if code_len > T::MaxCodeSize::get() ||
				T::Registrar::check_onboarding(head_len, code_len).is_err()
			{
				return Self::reject(para_id, message_id, FailureReason::InvalidOnboardingData);
			}
			let Ok(genesis_head) = BoundedVec::try_from(genesis_head) else {
				return Self::reject(para_id, message_id, FailureReason::InvalidOnboardingData);
			};

			PendingRegistrations::<T>::insert(
				para_id,
				PendingRegistration { message_id, manager, genesis_head, code_hash, code_len },
			);

			AwaitingFirstHead::<T>::insert(para_id, ());

			Self::deposit_event(Event::RegistrationPending { para_id, message_id, code_hash });
		}

		/// Turn a request away and tell the parachain to release the deposit.
		fn reject(para_id: ParaId, message_id: u64, reason: FailureReason) {
			Self::report_registration(para_id, message_id, Err(reason.clone()));
			Self::deposit_event(Event::RegistrationRejected { para_id, message_id, reason });
		}

		/// Drop the authorization for `para_id` and tell the parachain to release the deposit.
		///
		/// If the code already landed the cancellation is refused and the deposit is kept. Nothing
		/// pending still gets an `Ok`: the request may have been rejected here and the report lost.
		fn on_cancel_request(para_id: ParaId, message_id: u64) {
			PendingRegistrations::<T>::remove(para_id);

			if T::Registrar::is_registered(para_id) {
				Self::report_cancellation(
					para_id,
					message_id,
					Err(FailureReason::AlreadyRegistered),
				);
				return Self::deposit_event(Event::CancellationRefused { para_id, message_id });
			}

			AwaitingFirstHead::<T>::remove(para_id);

			Self::report_cancellation(para_id, message_id, Ok(()));
			Self::deposit_event(Event::AuthorizationCancelled { para_id, message_id });
		}

		/// Check `validation_code` against the pending entry for `para_id`.
		fn validate_pending_code(
			para_id: ParaId,
			validation_code: &[u8],
		) -> Result<PendingRegistrationOf<T>, Error<T>> {
			// Bound the work before hashing, so an oversized blob is rejected cheaply.
			let code_len =
				u32::try_from(validation_code.len()).map_err(|_| Error::<T>::CodeTooLarge)?;
			ensure!(code_len <= T::MaxCodeSize::get(), Error::<T>::CodeTooLarge);

			let pending =
				PendingRegistrations::<T>::get(para_id).ok_or(Error::<T>::NothingPending)?;
			ensure!(code_len == pending.code_len, Error::<T>::CodeLenMismatch);
			ensure!(
				BlakeTwo256::hash(validation_code) == pending.code_hash,
				Error::<T>::CodeHashMismatch
			);

			Ok(pending)
		}

		/// Map a validation failure onto the `InvalidTransaction::Custom` code it reports.
		pub fn err_to_code(error: Error<T>) -> u8 {
			match error {
				Error::<T>::NothingPending => 0,
				Error::<T>::CodeHashMismatch => 1,
				Error::<T>::CodeLenMismatch => 2,
				Error::<T>::CodeTooLarge => 3,
			}
		}

		/// Tell the parachain how a registration ended.
		fn report_registration(para_id: ParaId, message_id: u64, outcome: Outcome) {
			Self::report(
				para_id,
				message_id,
				MessageToParaV1::RegisterResponse { para_id, message_id, outcome },
			);
		}

		/// Tell the parachain what became of its cancellation.
		fn report_cancellation(para_id: ParaId, message_id: u64, outcome: Outcome) {
			Self::report(
				para_id,
				message_id,
				MessageToParaV1::CancelResponse { para_id, message_id, outcome },
			);
		}

		fn on_deregister_request(para_id: ParaId, message_id: u64) {
			let _ = (para_id, message_id);
			// TODO(ahm-v2): deregister the para and report the outcome back.
		}

		fn on_authorize_code_upgrade_request(
			para_id: ParaId,
			message_id: u64,
			code_hash: H256,
			code_len: u32,
		) {
			let _ = (para_id, message_id, code_hash, code_len);
			// TODO(ahm-v2): authorize the code upgrade and report the outcome back.
		}

		fn on_set_current_head_request(para_id: ParaId, message_id: u64, head: Vec<u8>) {
			let _ = (para_id, message_id, head);
			// TODO(ahm-v2): set the para's head and report the outcome back.
		}

		#[allow(dead_code)]
		fn report_deregistration(para_id: ParaId, message_id: u64, outcome: Outcome) {
			Self::report(
				para_id,
				message_id,
				MessageToParaV1::DeregisterResponse { para_id, message_id, outcome },
			);
		}

		#[allow(dead_code)]
		fn report_code_upgrade(
			para_id: ParaId,
			message_id: u64,
			outcome: Result<u32, FailureReason>,
		) {
			Self::report(
				para_id,
				message_id,
				MessageToParaV1::CodeUpgradeResponse { para_id, message_id, outcome },
			);
		}

		#[allow(dead_code)]
		fn report_code_upgrade_scheduled(para_id: ParaId, message_id: u64) {
			Self::report(
				para_id,
				message_id,
				MessageToParaV1::CodeUpgradeScheduled { para_id, message_id },
			);
		}

		#[allow(dead_code)]
		fn report_set_head(para_id: ParaId, message_id: u64, outcome: Outcome) {
			Self::report(
				para_id,
				message_id,
				MessageToParaV1::SetHeadResponse { para_id, message_id, outcome },
			);
		}

		/// Hand a report to the transport.
		///
		/// A failure is only logged and evented: callers have committed relay-chain state that must
		/// not unwind because a report bounced.
		fn report(para_id: ParaId, message_id: u64, message: MessageToParaV1) {
			if T::SendToPara::send(MessageToPara::V1(message)).is_err() {
				log::error!(
					target: "runtime::registrar-relay",
					"failed to report the outcome for para {para_id} back to the parachain",
				);
				Self::deposit_event(Event::ReportFailed { para_id, message_id });
			}
		}
	}
}

/// Tells the parachain the first time a para produces a head, so it can lock the para.
///
/// The caller is a hook that cannot fail, so a send failure is only logged and evented. Nothing is
/// recorded in that case, so the next head retries.
impl<T: Config> OnNewHead for Pallet<T> {
	fn on_new_head(id: Id, _head: &HeadData) -> Weight {
		let para_id: ParaId = id.into();
		if !AwaitingFirstHead::<T>::contains_key(para_id) {
			return T::WeightInfo::on_new_head_already_noted();
		}

		if T::SendToPara::send(MessageToPara::V1(MessageToParaV1::HeadNoted { para_id })).is_err() {
			log::error!(
				target: "runtime::registrar-relay",
				"failed to tell the parachain about a new head for para {para_id}",
			);
			Self::deposit_event(Event::HeadNoteFailed { para_id });
		} else {
			AwaitingFirstHead::<T>::remove(para_id);
			Self::deposit_event(Event::HeadNoted { para_id });
		}

		T::WeightInfo::on_new_head()
	}
}