jam_std_common/

extrinsic.rs

use crate::{
	AvailabilityAssurance, EpochIndex, ErasureRoot, TicketEnvelope, hash_encoded, hash_raw,
	header::OffendersMark,
};
use bounded_collections::ConstU32;
use bytes::Bytes;
use codec::{Compact, CompactLen, ConstEncodedLen, Decode, Encode, MaxEncodedLen};
use jam_types::{
	AuthTrace, AuthorizerHash, BoundedVec, CoreCount, CoreIndex, ExtrinsicHash, MaxDependencies,
	MaxTicketsPerBlock, MaxValSuperMajority, MaxWorkItems, RefineContext, SegmentTreeRoot,
	ServiceId, Slot, UnsignedGas, VALS_PER_CORE, ValIndex, VecMap, WorkDigest, WorkPackageHash,
	WorkReportHash, max_report_elective_data, max_work_items,
};

pub const MAX_VERDICTS_COUNT: usize = 16;
pub const MAX_OFFENSES_COUNT: usize = 16;

/// A bunch of preimages.
pub type PreimagesXt = Vec<Preimage>;
/// A collection of preimage info (hash + requestor).
pub type LightPreimagesXt = Vec<LightPreimage>;
/// A collection of ticket envelopes.
pub type TicketsXt = BoundedVec<TicketEnvelope, MaxTicketsPerBlock>;
/// A bunch of assurances.
pub type AssurancesXt = BoundedVec<AvailabilityAssurance, jam_types::MaxValCount>;
/// A bunch of guarantees.
pub type GuaranteesXt = BoundedVec<ReportGuarantee, CoreCount>;
/// A collection of lightweight report info (hash + slot + signatures).
pub type LightGuaranteesXt = BoundedVec<LightReportGuarantee, CoreCount>;

/// The disputes extrinsic.
#[derive(Clone, Encode, Decode, Debug, Default, MaxEncodedLen)]
pub struct DisputesXt {
	/// Disputed work reports together with their judgements.
	pub verdicts: BoundedVec<Verdict, ConstU32<{ MAX_VERDICTS_COUNT as u32 }>>,
	/// Validators who guaranteed a work report subsequently determined to be invalid.
	pub culprits: BoundedVec<CulpritProof, ConstU32<{ MAX_OFFENSES_COUNT as u32 }>>,
	/// Validators who audited a work report in conflict with the final dispute resolution.
	pub faults: BoundedVec<FaultProof, ConstU32<{ MAX_OFFENSES_COUNT as u32 }>>,
}

impl DisputesXt {
	pub fn offenders_mark(&self) -> OffendersMark {
		let offenders: Vec<_> = self
			.culprits
			.iter()
			.map(|v| v.key)
			.chain(self.faults.iter().map(|v| v.key))
			.collect();
		offenders.try_into().expect("OffendersMark bounds equal culprits + faults")
	}
	pub fn implies_offenders_mark(&self, offenders_mark: &OffendersMark) -> bool {
		self.culprits
			.iter()
			.map(|v| &v.key)
			.chain(self.faults.iter().map(|v| &v.key))
			.eq(offenders_mark.iter())
	}
}

/// Judgements coming from a supermajority of either the active validators
/// set (κ) or the previous epoch's validator set (λ).
pub type VerdictVotes = BoundedVec<Judgement, MaxValSuperMajority>;

/// Collection of judgements for a given target work report.
#[derive(Clone, Encode, Decode, Debug, MaxEncodedLen)]
pub struct Verdict {
	/// Target work report.
	pub target: WorkReportHash,
	/// Epoch index of the prior state or one less depending on the key set
	/// used to sign the votes.
	pub age: EpochIndex,
	/// Verdict votes collection.
	pub votes: VerdictVotes,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum VerdictKind {
	Good,
	Bad,
	Wonky,
}

impl Verdict {
	/// Returns the kind of verdict (good/bad/wonky) based on the vote split, or `Err` if the vote
	/// split is invalid.
	///
	/// Assumes `votes` holds a validator supermajority (`⌊2V/3⌋ + 1` votes, checked by the
	/// caller), so the wonky threshold `⌊V/3⌋` is derived from the votes count itself.
	pub fn kind(&self) -> Result<VerdictKind, ()> {
		let valid_count = self.votes.iter().filter(|v| v.vote).count();
		if valid_count == self.votes.len() {
			Ok(VerdictKind::Good)
		} else if valid_count == 0 {
			Ok(VerdictKind::Bad)
		} else if valid_count == (self.votes.len() - 1) / 2 {
			Ok(VerdictKind::Wonky)
		} else {
			Err(())
		}
	}
}

#[derive(Clone, Encode, Decode, Debug, PartialEq, MaxEncodedLen)]
pub struct Judgement {
	pub vote: bool,
	pub index: ValIndex,
	pub signature: super::ed25519::Signature,
}

// This represents a culprit where we have received a signature for a guarantee
// of a report `report_hash` that was found in a dispute to be Bad.
#[derive(Clone, Encode, Decode, Debug, MaxEncodedLen)]
pub struct CulpritProof {
	pub report_hash: WorkReportHash,
	pub key: super::ed25519::Public,
	pub signature: super::ed25519::Signature,
}

// This represents a fault where we have received a signature for report `report_hash`
// claiming it was valid if `vote == True` and invalid if `vote == False`,
// while we determined in a dispute that actually the report's validity is otherwise.
#[derive(Clone, Encode, Decode, Debug, MaxEncodedLen)]
pub struct FaultProof {
	pub report_hash: WorkReportHash,
	pub vote: bool,
	pub key: super::ed25519::Public,
	pub signature: super::ed25519::Signature,
}

#[derive(Clone, Encode, Decode, Debug, Default)]
pub struct Extrinsic {
	pub tickets: TicketsXt,
	pub preimages: PreimagesXt,
	pub guarantees: GuaranteesXt,
	pub assurances: AssurancesXt,
	pub disputes: DisputesXt,
}

#[derive(Clone, Encode, Decode, Debug, Default)]
pub struct LightExtrinsic {
	pub tickets: TicketsXt,
	pub preimages: LightPreimagesXt,
	pub guarantees: LightGuaranteesXt,
	pub assurances: AssurancesXt,
	pub disputes: DisputesXt,
}

impl Extrinsic {
	pub fn guarantees_prehashed(&self) -> Vec<(WorkReportHash, Slot, &GuaranteeSignatures)> {
		self.guarantees
			.iter()
			.map(|r| (r.report.hash(), r.slot, &r.signatures))
			.collect()
	}

	pub fn preimages_prehashed(&self) -> Vec<(ServiceId, jam_types::Hash)> {
		self.preimages.iter().map(|r| (r.requester, r.hash)).collect()
	}

	pub fn hash(&self) -> ExtrinsicHash {
		let tickets_hash = hash_encoded(&self.tickets);
		let disputes_hash = hash_encoded(&self.disputes);
		let preimages_hash = hash_encoded(&self.preimages_prehashed());
		let assurances_hash = hash_encoded(&self.assurances);
		let guarantees_hash = hash_encoded(&self.guarantees_prehashed());
		let top = (tickets_hash, preimages_hash, guarantees_hash, assurances_hash, disputes_hash);
		hash_encoded(&top).into()
	}

	pub fn encode_as_light<T: codec::Output + ?Sized>(&self, dest: &mut T) {
		self.tickets.encode_to(dest);
		let size = codec::Compact::<u32>(self.preimages.len() as u32);
		size.encode_to(dest);
		for preimage in &self.preimages {
			preimage.as_light().encode_to(dest);
		}
		let size = codec::Compact::<u32>(self.guarantees.len() as u32);
		size.encode_to(dest);
		for guarantee in &self.guarantees {
			guarantee.as_light().encode_to(dest);
		}
		self.assurances.encode_to(dest);
		self.disputes.encode_to(dest);
	}
}

#[derive(Clone, Debug, Eq, PartialOrd, Ord, Encode)]
pub struct Preimage {
	pub requester: ServiceId,
	blob: Bytes,
	#[codec(skip)]
	hash: jam_types::Hash,
}

impl PartialEq<Preimage> for Preimage {
	fn eq(&self, other: &Preimage) -> bool {
		self.requester == other.requester && self.hash == other.hash
	}
}

impl Preimage {
	pub fn as_light(&self) -> LightPreimage {
		LightPreimage { requester: self.requester, hash: self.hash() }
	}
}

impl Decode for Preimage {
	fn decode<I: codec::Input>(input: &mut I) -> Result<Self, codec::Error> {
		let requester: ServiceId = Decode::decode(input)?;
		let blob: Bytes = Decode::decode(input)?;
		let hash = hash_raw(&blob);
		Ok(Preimage { requester, blob, hash })
	}
}

impl Preimage {
	/// Utility to create preimage for testing: calculate hash of blob internally.
	/// Jam code do not need it as it is either known (persistence) or calculated in `decode`
	/// method.
	pub fn new_testing(requester: ServiceId, blob: impl Into<Bytes>) -> Self {
		let blob: Bytes = blob.into();
		let hash = hash_raw(&blob);
		Self { requester, blob, hash }
	}

	/// Warning hash parameter for this method MUST be the hash of the blob (we only add it as
	/// parameter to avoid hash computation when already checked, for instance when read from db).
	pub fn new_with_hash(
		requester: ServiceId,
		blob: impl Into<Bytes>,
		hash: jam_types::Hash,
	) -> Self {
		let blob: Bytes = blob.into();
		debug_assert_eq!(hash_raw(&blob), hash);
		Self { requester, blob, hash }
	}

	pub fn hash(&self) -> jam_types::Hash {
		self.hash
	}

	pub fn blob(&self) -> &Bytes {
		&self.blob
	}

	pub fn encoded_len(blob_len: usize) -> usize {
		core::mem::size_of::<ServiceId>() +
			Compact::<u64>::compact_len(&(blob_len as u64)) +
			blob_len
	}
}

/// Preimage data stored in db, actual blob is part of state.
#[derive(Clone, Encode, Decode, Debug, MaxEncodedLen)]
#[cfg_attr(test, derive(PartialEq, Eq))]
pub struct LightPreimage {
	pub requester: ServiceId,
	pub hash: jam_types::Hash,
}

/// A Work Report along with a guarantee of its correctness from staked sources.
#[derive(Clone, Encode, Decode, Debug, Eq, PartialEq, MaxEncodedLen)]
pub struct ReportGuarantee {
	/// The Work Report which is being attested.
	pub report: WorkReport,
	/// Timeslot of the guarantee: the slot at which the guarantors attested to the report. It
	/// determines the guarantor rotation, and hence the validator set the indices in `signatures`
	/// refer to; the indices must be a subset of those assigned to `report.core_index` at this
	/// slot. Must fall within the including block's rotation or the one before.
	pub slot: Slot,
	/// The signatures from the guarantors whose message is the hash of the `report`.
	/// The order of the signatures is the same order as the validators appear in
	/// the epochal validator set.
	pub signatures: GuaranteeSignatures,
}

impl ReportGuarantee {
	pub fn as_light(&self) -> LightReportGuaranteeEncode<'_> {
		LightReportGuaranteeEncode {
			report_hash: self.report.hash(),
			slot: self.slot,
			signatures: &self.signatures,
		}
	}
}

/// Report guarantee but only with a hash pointing to work report.
#[derive(Clone, Encode, Decode, Debug, MaxEncodedLen)]
#[cfg_attr(test, derive(PartialEq, Eq))]
pub struct LightReportGuarantee {
	pub report_hash: WorkReportHash,
	pub slot: Slot,
	pub signatures: GuaranteeSignatures,
}

#[derive(Encode, Debug)]
#[cfg_attr(test, derive(PartialEq, Eq))]
pub struct LightReportGuaranteeEncode<'a> {
	pub report_hash: WorkReportHash,
	pub slot: Slot,
	pub signatures: &'a GuaranteeSignatures,
}

pub type GuaranteeSignatures = BoundedVec<ValSignature, ConstU32<{ VALS_PER_CORE as u32 }>>;

#[derive(Clone, Encode, Decode, Debug, Eq, PartialEq, MaxEncodedLen)]
pub struct ValSignature {
	pub val_index: ValIndex,
	pub signature: super::ed25519::Signature,
}

impl ConstEncodedLen for ValSignature {}

/// Secure reference to a Work Package.
#[derive(Clone, Encode, Decode, Debug, Eq, PartialEq, MaxEncodedLen)]
pub struct WorkPackageSpec {
	/// The hash of the Work Package.
	pub hash: WorkPackageHash,
	/// The length in bytes of Work Bundle.
	pub len: u32,
	/// The erasure root of the Work Bundle and export-segment pieces.
	pub erasure_root: ErasureRoot,
	/// The total number of erasure-coded chunks, one per assuring validator.
	///
	/// Determines the erasure-coding rate used for the Work Bundle and export segments; a
	/// report may only be included on-chain if this matches the active validator-set size.
	pub erasure_shards: ValIndex,
	/// The segment root of the Work Package.
	pub exports_root: SegmentTreeRoot,
	/// The number of segments exported by the Work Package.
	pub exports_count: u16,
}

impl WorkPackageSpec {
	pub fn wp_srl(&self) -> (WorkPackageHash, SegmentTreeRoot) {
		(self.hash, self.exports_root)
	}
}

/// Execution report of a Work Package, mainly comprising the Results from the Refinement
/// of its Work Items.
#[derive(Clone, Encode, Decode, Debug, Eq, PartialEq)]
pub struct WorkReport {
	/// The specification of the underlying Work Package.
	pub package_spec: WorkPackageSpec,
	/// The context of the underlying Work Package.
	pub context: RefineContext,
	/// The Core index under which the Work Package was Refined to generate the Report.
	#[codec(compact)]
	pub core_index: CoreIndex,
	/// The authorizer under which this Work Package got executed. For the Work Package to be
	/// validly reported, this must appear in the Core's authorizer queue at the time of reporting.
	pub authorizer_hash: AuthorizerHash,
	/// The amount of gas actually used by the IsAuthorized call.
	#[codec(compact)]
	pub auth_gas_used: UnsignedGas,
	/// The output of the authorizer under which this Work Package got executed.
	pub auth_output: AuthTrace,
	/// The segment-root lookup dictionary.
	pub sr_lookup: VecMap<WorkPackageHash, SegmentTreeRoot>,
	/// The results of the evaluation of the Items in the underlying Work Package.
	pub results: BoundedVec<WorkDigest, MaxWorkItems>,
}

impl WorkReport {
	/// Report hash.
	pub fn hash(&self) -> WorkReportHash {
		hash_encoded(self).into()
	}

	/// Saturating sum of the `accumulate_gas` of all digests.
	pub fn gas(&self) -> UnsignedGas {
		self.results
			.iter()
			.fold(0, |gas: UnsignedGas, r| gas.saturating_add(r.accumulate_gas))
	}

	/// Report dependencies derived from both context prerequisites and the segments root
	/// lookup dictionary.
	pub fn deps(&self) -> impl Iterator<Item = &WorkPackageHash> {
		self.sr_lookup.keys().chain(self.context.prerequisites.iter())
	}

	/// Count report dependencies derived from both context prerequisites and the segments root
	/// lookup dictionary.
	pub fn dep_count(&self) -> usize {
		self.sr_lookup.len() + self.context.prerequisites.len()
	}

	/// Determine if the report size is within the limit.
	pub fn check_size(&self) -> bool {
		let total: usize =
			self.results.iter().filter_map(|r| Some(r.result.as_ref().ok()?.len())).sum();
		total + self.auth_output.len() <= max_report_elective_data() as usize
	}

	/// Work package hash for this report.
	pub fn package_hash(&self) -> WorkPackageHash {
		self.package_spec.hash
	}
}

impl MaxEncodedLen for WorkReport {
	fn max_encoded_len() -> usize {
		let mut max = WorkPackageSpec::max_encoded_len() +
			RefineContext::max_encoded_len() +
			codec::Compact::<CoreIndex>::max_encoded_len() +
			AuthorizerHash::max_encoded_len() +
			AuthTrace::max_encoded_len() +
			BoundedVec::<(WorkPackageHash, SegmentTreeRoot), MaxDependencies>::max_encoded_len() + // sr_lookup
			BoundedVec::<WorkDigest, MaxWorkItems>::max_encoded_len() +
			codec::Compact::<UnsignedGas>::max_encoded_len(); // auth_gas_used

		// In the max expression above, the max_report_elective_data() bound is effectively applied
		// separately to auth_output and item results. It actually applies to the combined size of
		// these -- they cannot _all_ have maximum length. Account for this.
		max -= max_work_items() * (max_report_elective_data() as usize);

		max
	}
}

pub mod tests_utils {
	use super::*;
	use bounded_collections::TryCollect;
	use jam_types::{RefineLoad, max_dependencies};

	// The largest possible work-report, or at least very close -- it might be possible to get
	// a few bytes more by eg rebalancing the output Vec lengths, as Vec lengths use compact
	// encoding.
	//
	// This is actually a bit larger than the largest valid report as both the prerequisites
	// set and the sr_lookup map have max_dependencies() entries; the max_dependencies() limit
	// is supposed to apply to the combined count. WorkReport::max_encoded_len() doesn't
	// account for this though, so we don't bother accounting for it here either.
	pub fn largest_report() -> WorkReport {
		let largest_spec = WorkPackageSpec {
			hash: Default::default(),
			len: u32::MAX,
			erasure_root: Default::default(),
			erasure_shards: ValIndex::MAX,
			exports_root: Default::default(),
			exports_count: u16::MAX,
		};

		let max_outputs = 1 + max_work_items(); // AuthTrace + WorkOutputs
		let output = |i| {
			let mut size = (max_report_elective_data() as usize) / max_outputs;
			if i == 0 {
				size += (max_report_elective_data() as usize) % max_outputs;
			}
			vec![0; size]
		};

		WorkReport {
			package_spec: largest_spec,
			context: RefineContext::largest(),
			core_index: CoreIndex::MAX,
			authorizer_hash: Default::default(),
			auth_output: output(0).into(),
			sr_lookup: (0..max_dependencies())
				.map(|i| ([i as u8; 32].into(), Default::default()))
				.collect(),
			results: (0..max_work_items())
				.map(|i| WorkDigest {
					service: ServiceId::MAX,
					code_hash: Default::default(),
					payload_hash: Default::default(),
					accumulate_gas: UnsignedGas::MAX,
					result: Ok(output(1 + i).into()),
					refine_load: RefineLoad {
						gas_used: UnsignedGas::MAX,
						imports: u16::MAX,
						extrinsic_count: u16::MAX,
						extrinsic_size: u32::MAX,
						exports: u16::MAX,
					},
				})
				.try_collect()
				.expect("max workitem should be this vec bound"),
			auth_gas_used: UnsignedGas::MAX,
		}
	}
}

#[cfg(test)]
mod tests {
	use super::*;
	use jam_types::{MAX_PREIMAGE_BLOB_LEN, MAX_PREIMAGE_LEN, max_work_items};

	#[test]
	fn report_gas_saturates() {
		let mut report = tests_utils::largest_report();
		report.results.truncate(2);
		report.results[0].accumulate_gas = UnsignedGas::MAX - 2;
		// Just below the max, the sum is exact.
		report.results[1].accumulate_gas = 1;
		assert_eq!(report.gas(), UnsignedGas::MAX - 1);
		// Saturate it.
		report.results[1].accumulate_gas = 10000;
		assert_eq!(report.gas(), UnsignedGas::MAX);
	}

	#[test]
	fn max_preimage_blob_len_is_correct() {
		let preimage = Preimage::new_testing(ServiceId::MAX, vec![123_u8; MAX_PREIMAGE_BLOB_LEN]);
		let encoded_len = preimage.encode().len();
		assert_eq!(MAX_PREIMAGE_LEN, encoded_len);
	}

	#[test]
	fn preimage_encoded_len_works() {
		for blob_len in (0..MAX_PREIMAGE_BLOB_LEN).step_by(997 * 64) {
			let preimage = Preimage::new_testing(ServiceId::MAX, vec![123_u8; blob_len]);
			let expected_len = Preimage::encoded_len(blob_len);
			let actual_len = preimage.encode().len();
			assert_eq!(expected_len, actual_len);
		}
	}

	#[test]
	fn report_max_encoded_len() {
		let largest_report = super::tests_utils::largest_report();
		assert_eq!(largest_report.package_spec.encoded_size(), WorkPackageSpec::max_encoded_len());

		let largest_report_size = largest_report.encoded_size();

		// WorkReport::max_encoded_len() assumes each "output" Vec can be the maximum length when
		// calculating how many bytes are needed for encoding Vec lengths in the worst case. The
		// Vecs cannot all be the maximum length though due to the shared nature of
		// max_report_elective_data(). To account for this discrepancy, we allow
		// WorkReport::max_encoded_len() to overshoot largest_report_size by 1 for each such Vec.
		let max = WorkReport::max_encoded_len();
		assert!(largest_report_size <= max);
		let max_outputs = 1 + max_work_items(); // AuthTrace + WorkOutputs
		assert!((largest_report_size + max_outputs) >= max);
	}
}