tp_runtime/generic/
era.rs

1// This file is part of Tetcore.
2
3// Copyright (C) 2017-2021 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//! Generic implementation of an unchecked (pre-verification) extrinsic.
19
20#[cfg(feature = "std")]
21use serde::{Serialize, Deserialize};
22
23use crate::codec::{Decode, Encode, Input, Output, Error};
24
25/// Era period
26pub type Period = u64;
27
28/// Era phase
29pub type Phase = u64;
30
31/// An era to describe the longevity of a transaction.
32#[derive(PartialEq, Eq, Clone, Copy, tet_core::RuntimeDebug)]
33#[cfg_attr(feature = "std", derive(Serialize, Deserialize))]
34pub enum Era {
35	/// The transaction is valid forever. The genesis hash must be present in the signed content.
36	Immortal,
37
38	/// Period and phase are encoded:
39	/// - The period of validity from the block hash found in the signing material.
40	/// - The phase in the period that this transaction's lifetime begins (and, importantly,
41	/// implies which block hash is included in the signature material). If the `period` is
42	/// greater than 1 << 12, then it will be a factor of the times greater than 1<<12 that
43	/// `period` is.
44	///
45	/// When used on `FABRIC`-based runtimes, `period` cannot exceed `BlockHashCount` parameter
46	/// of `system` module.
47	Mortal(Period, Phase),
48}
49
50/*
51 * E.g. with period == 4:
52 * 0         10        20        30        40
53 * 0123456789012345678901234567890123456789012
54 *              |...|
55 *    authored -/   \- expiry
56 * phase = 1
57 * n = Q(current - phase, period) + phase
58 */
59impl Era {
60	/// Create a new era based on a period (which should be a power of two between 4 and 65536 inclusive)
61	/// and a block number on which it should start (or, for long periods, be shortly after the start).
62	///
63	/// If using `Era` in the context of `FABRIC` runtime, make sure that `period`
64	/// does not exceed `BlockHashCount` parameter passed to `system` module, since that
65	/// prunes old blocks and renders transactions immediately invalid.
66	pub fn mortal(period: u64, current: u64) -> Self {
67		let period = period.checked_next_power_of_two()
68			.unwrap_or(1 << 16)
69			.max(4)
70			.min(1 << 16);
71		let phase = current % period;
72		let quantize_factor = (period >> 12).max(1);
73		let quantized_phase = phase / quantize_factor * quantize_factor;
74
75		Era::Mortal(period, quantized_phase)
76	}
77
78	/// Create an "immortal" transaction.
79	pub fn immortal() -> Self {
80		Era::Immortal
81	}
82
83	/// `true` if this is an immortal transaction.
84	pub fn is_immortal(&self) -> bool {
85		match self {
86			Era::Immortal => true,
87			_ => false,
88		}
89	}
90
91	/// Get the block number of the start of the era whose properties this object
92	/// describes that `current` belongs to.
93	pub fn birth(self, current: u64) -> u64 {
94		match self {
95			Era::Immortal => 0,
96			Era::Mortal(period, phase) => (current.max(phase) - phase) / period * period + phase,
97		}
98	}
99
100	/// Get the block number of the first block at which the era has ended.
101	pub fn death(self, current: u64) -> u64 {
102		match self {
103			Era::Immortal => u64::max_value(),
104			Era::Mortal(period, _) => self.birth(current) + period,
105		}
106	}
107}
108
109impl Encode for Era {
110	fn encode_to<T: Output + ?Sized>(&self, output: &mut T) {
111		match self {
112			Era::Immortal => output.push_byte(0),
113			Era::Mortal(period, phase) => {
114				let quantize_factor = (*period as u64 >> 12).max(1);
115				let encoded = (period.trailing_zeros() - 1).max(1).min(15) as u16 | ((phase / quantize_factor) << 4) as u16;
116				encoded.encode_to(output);
117			}
118		}
119	}
120}
121
122impl codec::EncodeLike for Era {}
123
124impl Decode for Era {
125	fn decode<I: Input>(input: &mut I) -> Result<Self, Error> {
126		let first = input.read_byte()?;
127		if first == 0 {
128			Ok(Era::Immortal)
129		} else {
130			let encoded = first as u64 + ((input.read_byte()? as u64) << 8);
131			let period = 2 << (encoded % (1 << 4));
132			let quantize_factor = (period >> 12).max(1);
133			let phase = (encoded >> 4) * quantize_factor;
134			if period >= 4 && phase < period {
135				Ok(Era::Mortal(period, phase))
136			} else {
137				Err("Invalid period and phase".into())
138			}
139		}
140	}
141}
142
143#[cfg(test)]
144mod tests {
145	use super::*;
146
147	#[test]
148	fn immortal_works() {
149		let e = Era::immortal();
150		assert_eq!(e.birth(0), 0);
151		assert_eq!(e.death(0), u64::max_value());
152		assert_eq!(e.birth(1), 0);
153		assert_eq!(e.death(1), u64::max_value());
154		assert_eq!(e.birth(u64::max_value()), 0);
155		assert_eq!(e.death(u64::max_value()), u64::max_value());
156		assert!(e.is_immortal());
157
158		assert_eq!(e.encode(), vec![0u8]);
159		assert_eq!(e, Era::decode(&mut&[0u8][..]).unwrap());
160	}
161
162	#[test]
163	fn mortal_codec_works() {
164		let e = Era::mortal(64, 42);
165		assert!(!e.is_immortal());
166
167		let expected = vec![5 + 42 % 16 * 16, 42 / 16];
168		assert_eq!(e.encode(), expected);
169		assert_eq!(e, Era::decode(&mut&expected[..]).unwrap());
170	}
171
172	#[test]
173	fn long_period_mortal_codec_works() {
174		let e = Era::mortal(32768, 20000);
175
176		let expected = vec![(14 + 2500 % 16 * 16) as u8, (2500 / 16) as u8];
177		assert_eq!(e.encode(), expected);
178		assert_eq!(e, Era::decode(&mut&expected[..]).unwrap());
179	}
180
181	#[test]
182	fn era_initialization_works() {
183		assert_eq!(Era::mortal(64, 42), Era::Mortal(64, 42));
184		assert_eq!(Era::mortal(32768, 20000), Era::Mortal(32768, 20000));
185		assert_eq!(Era::mortal(200, 513), Era::Mortal(256, 1));
186		assert_eq!(Era::mortal(2, 1), Era::Mortal(4, 1));
187		assert_eq!(Era::mortal(4, 5), Era::Mortal(4, 1));
188	}
189
190	#[test]
191	fn quantized_clamped_era_initialization_works() {
192		// clamp 1000000 to 65536, quantize 1000001 % 65536 to the nearest 4
193		assert_eq!(Era::mortal(1000000, 1000001), Era::Mortal(65536, 1000001 % 65536 / 4 * 4));
194	}
195
196	#[test]
197	fn mortal_birth_death_works() {
198		let e = Era::mortal(4, 6);
199		for i in 6..10 {
200			assert_eq!(e.birth(i), 6);
201			assert_eq!(e.death(i), 10);
202		}
203
204		// wrong because it's outside of the (current...current + period) range
205		assert_ne!(e.birth(10), 6);
206		assert_ne!(e.birth(5), 6);
207	}
208
209	#[test]
210	fn current_less_than_phase() {
211		// should not panic
212		Era::mortal(4, 3).birth(1);
213	}
214}
tp_runtime/generic/era.rs

tp_runtime/generic/
era.rs
