pub(crate) fn main()pub(crate) fn main()pub(crate) fn main()Contract execution context.
+pub trait Context {
+ type PublicStore: PublicStore;
+ type ConfidentialStore: ConfidentialStore;
+ type Env: Env + Crypto;
+
+ // Required methods
+ fn instance_id(&self) -> InstanceId;
+ fn instance_address(&self) -> &Address;
+ fn caller_address(&self) -> &Address;
+ fn deposited_tokens(&self) -> &[BaseUnits];
+ fn is_read_only(&self) -> bool;
+ fn call_format(&self) -> CallFormat;
+ fn emit_message(&mut self, msg: Message);
+ fn emit_event<E: Event>(&mut self, event: E);
+ fn public_store(&mut self) -> &mut Self::PublicStore;
+ fn confidential_store(&mut self) -> &mut Self::ConfidentialStore;
+ fn env(&self) -> &Self::Env;
+}Execution context.
+The public store.
+The confidential store.
+Contract instance identifier.
+Contract instance address.
+Caller address.
+Tokens deposited by the caller.
+Whether the call is read-only and must not make any storage modifications.
+Call format.
+Emits a message.
+Emits an event.
+Public contract store.
+Confidential contract store.
+The contract trait.
+pub trait Contract {
+ type Request: Decode;
+ type Response: Encode;
+ type Error: Error;
+
+ // Required methods
+ fn call<C: Context>(
+ ctx: &mut C,
+ request: Self::Request,
+ ) -> Result<Self::Response, Self::Error>;
+ fn query<C: Context>(
+ _ctx: &mut C,
+ _request: Self::Request,
+ ) -> Result<Self::Response, Self::Error>;
+
+ // Provided methods
+ fn instantiate<C: Context>(
+ _ctx: &mut C,
+ _request: Self::Request,
+ ) -> Result<(), Self::Error> { ... }
+ fn handle_reply<C: Context>(
+ _ctx: &mut C,
+ _reply: Reply,
+ ) -> Result<Option<Self::Response>, Self::Error> { ... }
+ fn pre_upgrade<C: Context>(
+ _ctx: &mut C,
+ _request: Self::Request,
+ ) -> Result<(), Self::Error> { ... }
+ fn post_upgrade<C: Context>(
+ _ctx: &mut C,
+ _request: Self::Request,
+ ) -> Result<(), Self::Error> { ... }
+}Trait that needs to be implemented by contract implementations.
+Instantiate the contract.
+Handle replies from sent messages.
+#[derive(Error)]
+{
+ // Attributes available to this derive:
+ #[sdk_error]
+ #[source]
+ #[from]
+}
+Derives the Error trait on an enum.
#[derive(Event)]
+{
+ // Attributes available to this derive:
+ #[sdk_event]
+}
+Derives the Event trait on an enum.
pub enum CryptoError {
+ DecryptionFailed,
+}Errors that can be returned from crypto functions.
+Smart contract environment query interface.
+pub trait Crypto {
+ // Required methods
+ fn ecdsa_recover(&self, input: &[u8]) -> [u8; 65];
+ fn signature_verify_ed25519(
+ &self,
+ key: &[u8],
+ message: &[u8],
+ signature: &[u8],
+ ) -> bool;
+ fn signature_verify_secp256k1(
+ &self,
+ key: &[u8],
+ message: &[u8],
+ signature: &[u8],
+ ) -> bool;
+ fn signature_verify_sr25519(
+ &self,
+ key: &[u8],
+ context: &[u8],
+ message: &[u8],
+ signature: &[u8],
+ ) -> bool;
+ fn x25519_derive_symmetric(
+ &self,
+ public_key: &[u8],
+ private_key: &[u8],
+ ) -> [u8; 32];
+ fn deoxysii_seal(
+ &self,
+ key: &[u8],
+ nonce: &[u8],
+ message: &[u8],
+ additional_data: &[u8],
+ ) -> Result<Vec<u8>, CryptoError>;
+ fn deoxysii_open(
+ &self,
+ key: &[u8],
+ nonce: &[u8],
+ message: &[u8],
+ additional_data: &[u8],
+ ) -> Result<Vec<u8>, CryptoError>;
+ fn random_bytes(&self, pers: &[u8], dst: &mut [u8]) -> usize;
+}Crypto helpers trait.
+ECDSA public key recovery function.
+Verify an ed25519 message signature.
+Verify a secp256k1 message signature.
+Verify an sr25519 message signature.
+Derive a symmetric key from a public/private key pair.
+Encrypt and authenticate a message and authenticate additional data using DeoxysII.
+Decrypt and authenticate a message and authenticate additional data using DeoxysII.
+Fills dst with cryptographically secure random bytes.
+Returns the number of bytes written.
+If the optional personalization string (pers) is provided, it will be mixed into the RNG to provide additional domain separation.
pub trait Env {
+ // Required methods
+ fn query<Q: Into<QueryRequest>>(&self, query: Q) -> QueryResponse;
+ fn address_for_instance(&self, instance_id: InstanceId) -> Address;
+ fn debug_print(&self, msg: &str);
+}Environment query trait.
+Perform an environment query.
+Returns an address for the contract instance id.
+Prints a message to the console. Useful when debugging.
+Contract error trait.
+pub trait Error: Error {
+ // Required methods
+ fn module_name(&self) -> &str;
+ fn code(&self) -> u32;
+
+ // Provided method
+ fn to_execution_result(&self) -> ExecutionResult { ... }
+}A contract error that gets propagated to the caller.
+It extends std::error::Error with module name and error code so that errors can be easily
+serialized and transferred between different processes.
This trait can be derived:
+ +#[derive(Clone, Debug, Error, thiserror::Error)]
+#[sdk_error(autonumber)]
+enum Error {
+ #[error("invalid argument")]
+ InvalidArgument, // autonumbered to 0
+
+ #[error("forbidden")]
+ #[sdk_error(code = 401)] // manually numbered to 403 (`code` or autonumbering is required)
+ Forbidden,
+}Name of the module that emitted the error.
+Converts the error into an execution result.
+Contract event trait.
+pub trait Event: Sized + Encode {
+ // Required methods
+ fn module_name(&self) -> &str;
+ fn code(&self) -> u32;
+
+ // Provided method
+ fn into_raw(self) -> Event { ... }
+}An event emitted by the contract.
+This trait can be derived:
+ +#[derive(Clone, Debug, cbor::Encode, Event)]
+#[cbor(untagged)]
+#[sdk_event(autonumber)]
+enum MyEvent {
+ Greeting(String), // autonumbered to 0
+ #[sdk_event(code = 2)] // manually numbered to 2 (`code` is required if not autonumbering)
+ DontPanic,
+ Salutation { // autonumbered to 1
+ plural: bool,
+ }
+}Name of the module that emitted the event.
+Oasis Contract SDK.
+pub use self::context::Context;pub use self::contract::Contract;pub use self::error::Error;pub use self::event::Event;pub use oasis_contract_sdk_types as types;pub use cbor;Error trait on an enum.Event trait on an enum.Redirecting to macro.create_contract.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_contract_sdk/macro.create_contract.html b/rust/oasis_contract_sdk/macro.create_contract.html new file mode 100644 index 0000000000..900206a445 --- /dev/null +++ b/rust/oasis_contract_sdk/macro.create_contract.html @@ -0,0 +1 @@ +create_contract!() { /* proc-macro */ }pub fn allocate_host(length: u32) -> u32Allocate memory on host’s behalf.
+pub fn deallocate_host(offset: u32, length: u32)Deallocate memory on host’s behalf.
+Memory management.
+#[repr(C)]pub struct HostRegion {
+ pub offset: u32,
+ pub length: u32,
+}A region of memory managed on behalf of the host.
+The host is responsible for deallocating the region by calling deallocate.
offset: u32§length: u32Creates a new host region from arguments.
+This does not yet transfer memory ownership from the host.
+Creates a new host region from arguments.
+This does not yet transfer memory ownership from the host.
+Transfers ownership of memory to the host by constructing a host region.
+Transfers ownership of memory from the host and returns the vector.
+This is safe as long as the region was constructed from valid arguments.
+Returns a new region by dereferencing a pointer to the region.
+This does not yet transfer memory ownership from the host.
+This is safe as long as the pointer is a valid pointer to the region struct.
+pub struct HostRegionRef<'a> {
+ pub offset: u32,
+ pub length: u32,
+ /* private fields */
+}Reference to a host region.
+offset: u32§length: u32Creates a new host region from the given byte slice.
+Smart contract storage interface.
+pub trait ConfidentialStore: Store { }Marker trait for stores backed by confidential storage.
+pub trait PublicStore: Store { }Marker trait for stores backed by public storage.
+pub trait Store {
+ // Required methods
+ fn get(&self, key: &[u8]) -> Option<Vec<u8>>;
+ fn insert(&mut self, key: &[u8], value: &[u8]);
+ fn remove(&mut self, key: &[u8]);
+}Key/value store trait.
+Utilities for testing smart contracts.
+pub struct MockContext {
+ pub ec: ExecutionContext,
+ pub public_store: MockStore,
+ pub confidential_store: MockStore,
+ pub env: MockEnv,
+ pub messages: Vec<Message>,
+ pub events: Vec<Event>,
+}A mock contract context suitable for testing.
+ec: ExecutionContextExecution context.
+public_store: MockStorePublic store.
+confidential_store: MockStore“Confidential” store.
+env: MockEnvEnvironment.
+messages: Vec<Message>Emitted messages.
+events: Vec<Event>Emitted events.
+pub struct MockEnv { /* private fields */ }Mock environment.
+clone_to_uninit)pub struct MockStore { /* private fields */ }Mock store.
+clone_to_uninit)Low-level storage primitive that holds one value.
+pub struct ConfidentialCell<'key, T> { /* private fields */ }A storage cell identifies a storage key of a specific type.
+Return the current value of the storage cell.
+The method will panic in case the raw cell value cannot be deserialized.
+Set the value of the storage cell.
+pub struct PublicCell<'key, T> { /* private fields */ }A storage cell identifies a storage key of a specific type.
+Return the current value of the storage cell.
+The method will panic in case the raw cell value cannot be deserialized.
+Set the value of the storage cell.
+High-level storage helpers for the Oasis Contract SDK.
+A map backed by contract storage.
+pub struct ConfidentialMap<'key, K, V> { /* private fields */ }A map backed by contract storage.
+Lookup a given key.
+Insert a given key/value pair.
+Remove a given key.
+pub struct Int<I: Integer> { /* private fields */ }An integer in big-endian representation.
+pub struct PublicMap<'key, K, V> { /* private fields */ }A map backed by contract storage.
+Lookup a given key.
+Insert a given key/value pair.
+Remove a given key.
+pub trait Integer {
+ type Encoded: AsRef<[u8]>;
+
+ // Required method
+ fn to_be_bytes(self) -> Self::Encoded;
+}A trait representing an integer that can be encoded into big-endian bytes.
+Return the memory representation of this integer as a byte array in big-endian byte order.
+pub trait MapKey {
+ // Required method
+ fn key(&self) -> Vec<&[u8]>;
+}A trait for types which can be used as map keys.
+pub enum Error {
+ MalformedAddress,
+}Error.
+pub struct Address(/* private fields */);An account address.
+try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)clone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)#[repr(u32)]pub enum SignatureKind {
+ Ed25519 = 0,
+ Secp256k1 = 1,
+ Sr25519 = 2,
+}Signature kind.
+source. Read moreclone_to_uninit)clone_to_uninit)Cryptography-related types.
+#[repr(u8)]pub enum CallFormat {
+ Plain = 0,
+ EncryptedX25519DeoxysII = 1,
+}Format used for encoding the call (and output) information.
+Plain text call data.
+Encrypted call data using X25519 for key exchange and Deoxys-II for symmetric encryption.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)clone_to_uninit)key and return true if they are equal.pub enum ExecutionResult {
+ Ok(ExecutionOk),
+ Failed {
+ module: String,
+ code: u32,
+ message: String,
+ },
+}Contract execution result.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)#[non_exhaustive]pub enum AccountsQuery {
+ Balance {
+ address: Address,
+ denomination: Denomination,
+ },
+}Accounts API queries.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)#[non_exhaustive]pub enum AccountsResponse {
+ Balance {
+ balance: u128,
+ },
+}Accounts API responses.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)#[non_exhaustive]pub enum QueryRequest {
+ BlockInfo,
+ Accounts(AccountsQuery),
+}A query request.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)#[non_exhaustive]pub enum QueryResponse {
+ Error {
+ module: String,
+ code: u32,
+ message: String,
+ },
+ BlockInfo {
+ round: u64,
+ epoch: u64,
+ timestamp: u64,
+ },
+ Accounts(AccountsResponse),
+}A query response.
+Indication of a failing request.
+Information about the current runtime block.
+Accounts queries.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)Environment query-related types.
+Events.
+pub struct Event {
+ pub module: String,
+ pub code: u32,
+ pub data: Vec<u8>,
+}An event emitted from the contract.
+module: StringOptional module name.
+code: u32Unique code representing the event for the given module.
+data: Vec<u8>Arbitrary data associated with the event.
+try_default in case the value is null or
+undefined.clone_to_uninit)A collection of common types used by the Oasis Contract SDK.
+pub enum CallResult {
+ Ok(Value),
+ Failed {
+ module: String,
+ code: u32,
+ },
+}Call result.
+Check whether the call result indicates a successful operation or not.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)#[non_exhaustive]pub enum Message {
+ Call {
+ id: u64,
+ reply: NotifyReply,
+ method: String,
+ body: Value,
+ max_gas: Option<u64>,
+ data: Option<Value>,
+ },
+}Messages can be emitted by contracts and are processed after the contract execution completes.
+Calls an arbitrary runtime method handler in a child context with an optional gas limit.
+The call is executed in the context of the smart contract as the caller within the same +transaction.
+This can be used to call other smart contracts.
+try_default in case the value is null or
+undefined.clone_to_uninit)#[repr(u8)]pub enum NotifyReply {
+ Never = 0,
+ OnError = 1,
+ OnSuccess = 2,
+ Always = 3,
+}Specifies when the caller (smart contract) wants to be notified of a reply.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)clone_to_uninit)key and return true if they are equal.#[non_exhaustive]pub enum Reply {
+ Call {
+ id: u64,
+ result: CallResult,
+ data: Option<Value>,
+ },
+}Replies to delivered messages.
+try_default in case the value is null or
+undefined.clone_to_uninit)Messages that can be emitted by contracts.
+pub struct InstantiateResult {
+ pub id: InstanceId,
+}Instantiate call result.
+id: InstanceIdAssigned instance identifier.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)A collection of types for easier calling into existing SDK modules.
+#[repr(u32)]pub enum StoreKind {
+ Public = 0,
+ Confidential = 1,
+}Kind of the store to use.
+clone_to_uninit)clone_to_uninit)Storage-related types.
+pub struct CodeId(/* private fields */);Unique stored code identifier.
+try_default in case the value is null or
+undefined.clone_to_uninit)clone_to_uninit)key and return true if they are equal.pub struct ExecutionContext {
+ pub instance_id: InstanceId,
+ pub instance_address: Address,
+ pub caller_address: Address,
+ pub deposited_tokens: Vec<BaseUnits>,
+ pub read_only: bool,
+ pub call_format: CallFormat,
+}Execution context.
+Contains information that is useful on most invocations as it is always +included without requiring any explicit queries.
+instance_id: InstanceIdContract instance identifier.
+instance_address: AddressContract instance address.
+caller_address: AddressCaller address.
+deposited_tokens: Vec<BaseUnits>Tokens deposited by the caller.
+read_only: boolRead-only flag.
+A read-only call cannot make any changes to runtime state. Any attempt at modifying state +will result in the call failing.
+call_format: CallFormatTransaction’s call format.
+try_default in case the value is null or
+undefined.pub struct ExecutionOk {
+ pub data: Vec<u8>,
+ pub messages: Vec<Message>,
+ pub events: Vec<Event>,
+}Result of a successful contract execution.
+data: Vec<u8>Raw data returned from the contract.
+messages: Vec<Message>Messages emitted from the contract.
+events: Vec<Event>Events emitted from the contract.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct InstanceId(/* private fields */);Unique deployed code instance identifier.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)clone_to_uninit)key and return true if they are equal.Testing helpers.
+pub enum Error {
+ NameTooLong {
+ length: usize,
+ },
+}Token types.
+pub struct BaseUnits(pub u128, pub Denomination);Token amount of given denomination in base units.
+0: u128§1: DenominationCreates a new token amount of the given denomination.
+Denomination of the token amount.
+try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.pub struct Denomination(/* private fields */);Name/type of the token.
+Maximum length of a denomination.
+Denomination in native token.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub fn new(app: Box<dyn App>) -> Box<dyn Initializer>Create a new runtime initializer for an application.
+pub struct NoopApp;An application which doesn’t do anything.
+pub trait App: Send + Sync {
+ // Provided methods
+ fn is_rofl(&self) -> bool { ... }
+ fn on_init(&mut self, host: Arc<dyn Host>) -> Result<()> { ... }
+ fn quote_policy<'life0, 'async_trait>(
+ &'life0 self,
+ ) -> Pin<Box<dyn Future<Output = Result<QuotePolicy>> + Send + 'async_trait>>
+ where Self: 'async_trait,
+ 'life0: 'async_trait { ... }
+ fn on_runtime_block<'life0, 'life1, 'async_trait>(
+ &'life0 self,
+ blk: &'life1 AnnotatedBlock,
+ ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
+ where Self: 'async_trait,
+ 'life0: 'async_trait,
+ 'life1: 'async_trait { ... }
+ fn on_runtime_event<'life0, 'life1, 'life2, 'async_trait>(
+ &'life0 self,
+ blk: &'life1 AnnotatedBlock,
+ tags: &'life2 [Vec<u8>],
+ ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
+ where Self: 'async_trait,
+ 'life0: 'async_trait,
+ 'life1: 'async_trait,
+ 'life2: 'async_trait { ... }
+ fn query<'life0, 'life1, 'async_trait>(
+ &'life0 self,
+ method: &'life1 str,
+ args: Vec<u8>,
+ ) -> Pin<Box<dyn Future<Output = Result<Vec<u8>>> + Send + 'async_trait>>
+ where Self: 'async_trait,
+ 'life0: 'async_trait,
+ 'life1: 'async_trait { ... }
+}An Oasis runtime app.
+Called on application initialization.
+Quote policy to use for verifying our own enclave identity.
+Called on new runtime block being received.
+Called on new runtime event being detected.
+pub struct Cache { /* private fields */ }Cached storage tree with an associated root.
+pub struct CacheSet { /* private fields */ }A set of storage tree caches, one for each storage operation:
+Execution and checking of transactions each have their own cache guarded by a mutex +since the usual use case is that only one execution/check batch is running at any given time.
+Queries have a thread-local cache as there can be multiple queries running at any given +time and having a global lock would kill concurrency.
+clone_to_uninit)Byte array type helpers.
+pub struct Hash(pub [u8; 32]);A 32-byte SHA-512/256 hash.
+0: [u8; 32]Compute a digest of the passed slice of bytes.
+Compute a digest of the passed slices of bytes.
+Hash of an empty string.
+try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)clone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub const NONCE_SIZE: usize = 15; // 15usizeSize of the nonce in bytes.
+pub fn box_open(
+ nonce: &[u8; 15],
+ ciphertext: Vec<u8>,
+ additional_data: Vec<u8>,
+ peers_public_key: &PublicKey,
+ private_key: &StaticSecret,
+) -> Result<Vec<u8>>Unboxes (“opens”) the provided additional data and ciphertext via
+Deoxys-II-256-128 using a symmetric key derived from the provided
+X25519 public and private keys.
+The nonce should be NONCE_SIZE bytes long and both it and the additional
+data must match the value passed to box_seal.
pub fn box_seal(
+ nonce: &[u8; 15],
+ plaintext: Vec<u8>,
+ additional_data: Vec<u8>,
+ peers_public_key: &PublicKey,
+ private_key: &StaticSecret,
+) -> Result<Vec<u8>>Boxes (“seals”) the provided additional data and plaintext via
+Deoxys-II-256-128 using a symmetric key derived from the provided
+X25519 public and private keys.
+The nonce should be NONCE_SIZE bytes long and unique for all time
+for a given public and private key tuple.
pub fn generate_key_pair() -> (PublicKey, StaticSecret)Generates a public/private key pair suitable for use with
+derive_symmetric_key, box_seal, and box_open.
Deoxys-II-256-128 MRAE primitives implementation.
+NONCE_SIZE bytes long and both it and the additional
+data must match the value passed to box_seal.NONCE_SIZE bytes long and unique for all time
+for a given public and private key tuple.derive_symmetric_key, box_seal, and box_open.#[repr(align(16))]pub struct DeoxysII { /* private fields */ }Deoxys-II-256-128 state.
+We don’t store the key itself, but only components derived from the key. +These components are automatically erased after the structure is dropped.
+Encrypts and authenticates plaintext, authenticates the additional +data and returns the result.
+Like DeoxysII::seal but seals into ciphertext_with_tag,
+returning the number of bytes written.
Decrypts and authenticates ciphertext, authenticates the additional +data and, if successful, returns the resulting plaintext. +If the tag verification fails, an error is returned and the +intermediary plaintext is securely erased from memory.
+pub const NONCE_SIZE: usize = 15; // 15usizeSize of the nonce in bytes. +Size of the nonce in bytes.
+Nonce utility used to ensure nonces are safely incremented.
+pub struct Nonce { /* private fields */ }120 bit nonce with a 88 bit tag and 32 bit counter. If the counter exceeds +32 bits, then the nonce is no longer valid and must be refreshed with a new +random nonce. It is expected that all 128 bits are given randomly. However, +the last 32 counting bits may wrap around to ensure 2^32 counts may be used +per nonce.
+Adds one to the nonce, affecting only the last 32 counting bits. +Returns an error iff we’ve exceeded our nonce’s counter capacity, i.e., +we’ve incremented 2^32 times. In this case, the Nonce remains unchanged, +and all subsequent calls to this method will return an Error.
+Returns a slice containing the entire array. Equivalent to &s[..].
Borrows each element and returns an array of references with the same
+size as self.
let floats = [3.1, 2.7, -1.0];
+let float_refs: [&f64; 3] = floats.each_ref();
+assert_eq!(float_refs, [&3.1, &2.7, &-1.0]);This method is particularly useful if combined with other methods, like
+map. This way, you can avoid moving the original
+array if its elements are not Copy.
let strings = ["Ferris".to_string(), "♥".to_string(), "Rust".to_string()];
+let is_ascii = strings.each_ref().map(|s| s.is_ascii());
+assert_eq!(is_ascii, [true, false, true]);
+
+// We can still access the original array: it has not been moved.
+assert_eq!(strings.len(), 3);split_array)Divides one array reference into two at an index.
+The first will contain all indices from [0, M) (excluding
+the index M itself) and the second will contain all
+indices from [M, N) (excluding the index N itself).
Panics if M > N.
#![feature(split_array)]
+
+let v = [1, 2, 3, 4, 5, 6];
+
+{
+ let (left, right) = v.split_array_ref::<0>();
+ assert_eq!(left, &[]);
+ assert_eq!(right, &[1, 2, 3, 4, 5, 6]);
+}
+
+{
+ let (left, right) = v.split_array_ref::<2>();
+ assert_eq!(left, &[1, 2]);
+ assert_eq!(right, &[3, 4, 5, 6]);
+}
+
+{
+ let (left, right) = v.split_array_ref::<6>();
+ assert_eq!(left, &[1, 2, 3, 4, 5, 6]);
+ assert_eq!(right, &[]);
+}split_array)Divides one array reference into two at an index from the end.
+The first will contain all indices from [0, N - M) (excluding
+the index N - M itself) and the second will contain all
+indices from [N - M, N) (excluding the index N itself).
Panics if M > N.
#![feature(split_array)]
+
+let v = [1, 2, 3, 4, 5, 6];
+
+{
+ let (left, right) = v.rsplit_array_ref::<0>();
+ assert_eq!(left, &[1, 2, 3, 4, 5, 6]);
+ assert_eq!(right, &[]);
+}
+
+{
+ let (left, right) = v.rsplit_array_ref::<2>();
+ assert_eq!(left, &[1, 2, 3, 4]);
+ assert_eq!(right, &[5, 6]);
+}
+
+{
+ let (left, right) = v.rsplit_array_ref::<6>();
+ assert_eq!(left, &[]);
+ assert_eq!(right, &[1, 2, 3, 4, 5, 6]);
+}ascii_char)Converts this array of bytes into a array of ASCII characters,
+or returns None if any of the characters is non-ASCII.
#![feature(ascii_char)]
+#![feature(const_option)]
+
+const HEX_DIGITS: [std::ascii::Char; 16] =
+ *b"0123456789abcdef".as_ascii().unwrap();
+
+assert_eq!(HEX_DIGITS[1].as_str(), "1");
+assert_eq!(HEX_DIGITS[10].as_str(), "a");ascii_char)Converts this array of bytes into a array of ASCII characters, +without checking whether they’re valid.
+Every byte in the array must be in 0..=127, or else this is UB.
clone_to_uninit)pub fn signature_context_with_chain_separation(
+ context: Vec<u8>,
+ chain_context: &String,
+) -> Vec<u8> ⓘExtends signature context with additional domain separation based on the chain context.
+pub fn signature_context_with_runtime_separation(
+ context: Vec<u8>,
+ runtime_id: &Namespace,
+) -> Vec<u8> ⓘExtends signature context with additional domain separation based on the runtime ID.
+Signature types.
+pub struct MultiSigned {
+ pub blob: Vec<u8>,
+ pub signatures: Vec<SignatureBundle>,
+}Blob signed by multiple public keys.
+blob: Vec<u8>Signed blob.
+signatures: Vec<SignatureBundle>Signatures over the blob.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct PrivateKey(pub SigningKey);An Ed25519 private key.
+0: SigningKeyConstruct a private key from bytes returned by to_bytes.
This method will panic in case the passed bytes do not have the correct length.
+Generate a new private key from a test key seed.
+Returns the public key.
+pub struct PublicKey(pub [u8; 32]);An Ed25519 public key.
+0: [u8; 32]try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)clone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub struct Signature(pub [u8; 64]);An Ed25519 signature.
+0: [u8; 64]try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)clone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub struct SignatureBundle {
+ pub public_key: PublicKey,
+ pub signature: Signature,
+}A signature bundled with a public key.
+public_key: PublicKeyPublic key that produced the signature.
+signature: SignatureActual signature.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct Signed {
+ pub blob: Vec<u8>,
+ pub signature: SignatureBundle,
+}Blob signed with one public key.
+blob: Vec<u8>Signed blob.
+signature: SignatureBundleSignature over the blob.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub const PRIVATE_KEY_LENGTH: usize = 32;The length of an X25519 private key, in bytes.
+pub const PUBLIC_KEY_LENGTH: usize = 32;The length of an X25519 public key, in bytes.
+CBOR serializable X25519 types.
+pub struct PrivateKey(pub StaticSecret);A CBOR serializable Diffie-Hellman X25519 private key.
+0: StaticSecretCompute corresponding public key.
+Generate a new private key from a test key seed.
+source. Read moretry_default in case the value is null or
+undefined.Given an X25519 private key, compute its corresponding public key.
+clone_to_uninit)self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub struct PublicKey(pub PublicKey);A CBOR serializable Diffie-Hellman X25519 public key.
+0: PublicKeytry_default in case the value is null or
+undefined.Given an X25519 private key, compute its corresponding public key.
+clone_to_uninit)clone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)Common types.
+pub trait KeyFormat {
+ // Required methods
+ fn prefix() -> u8;
+ fn size() -> usize;
+ fn encode_atoms(self, atoms: &mut Vec<Vec<u8>>);
+ fn decode_atoms(data: &[u8]) -> Self
+ where Self: Sized;
+
+ // Provided methods
+ fn encode_partial(self, count: usize) -> Vec<u8> ⓘ
+ where Self: Sized { ... }
+ fn encode(self) -> Vec<u8> ⓘ
+ where Self: Sized { ... }
+ fn decode(data: &[u8]) -> Option<Self>
+ where Self: Sized { ... }
+}A key formatting helper trait to be used together with key-value +backends for constructing keys.
+Encode the given key format into a set of atoms.
+Decode the given key format from data (without prefix).
+The caller must ensure that the size of the passed data is at
+least the minimum size returned by size.
pub trait KeyFormatAtom {
+ // Required methods
+ fn size() -> usize;
+ fn encode_atom(self) -> Vec<u8> ⓘ;
+ fn decode_atom(data: &[u8]) -> Self
+ where Self: Sized;
+}Part of the KeyFormat to be used with key-value backends for constructing keys.
+pub fn get_logger(module: &'static str) -> LoggerGet the logger.
+pub fn init_logger(level: Level)Initialize the global slog_stdlog adapter to allow logging with the log crate (instead of slog).
+Logging subsystem for runtimes.
+pub const NAMESPACE_SIZE: usize = 32;Size of the namespace in bytes.
+pub struct Namespace(pub [u8; 32]);Chain namespace.
+0: [u8; 32]try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)clone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)Panic-related functions.
+pub struct AbortOnPanic;A guard that will abort the process if dropped while panicking.
+This is to ensure that the runtime will terminate in case there is +a panic encountered during dispatch and the runtime is built with +a non-abort panic handler.
+pub struct Quantity(/* private fields */);An arbitrary precision unsigned integer.
+Subtracts two numbers, checking for underflow. If underflow happens, None is returned.
Divides two numbers, checking for underflow, overflow and division by zero. If any of that
+happens, None is returned.
+= operation. Read more+= operation. Read more+= operation. Read moretry_default in case the value is null or
+undefined.*= operation. Read more*= operation. Read more*= operation. Read moreself and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.pub const MAX_QUOTE_AGE: i64 = _; // 86_400i64Maximum age of a quote from the viewpoint of the enclave.
+pub fn egetkey(key_policy: Keypolicy, context: &[u8]) -> [u8; 32]egetkey returns a 256 bit key suitable for sealing secrets to the
+enclave in cold storage, derived from the results of the EGETKEY
+instruction. The context field is a domain separation tag.
Note: The key can also be used for other things (eg: as an X25519 +private key).
+SGX per-CPU package sealing key accessor.
+EGETKEY
+instruction. The context field is a domain separation tag.pub enum Quote {
+ Ias(AVR),
+ Pcs(QuoteBundle),
+}An unverified SGX remote attestation quote, depending on the attestation scheme.
+Verify the remote attestation quote.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub fn report_for(_target_info: &Targetinfo, report_data: &[u8; 64]) -> ReportGenerate a report for the given target enclave.
+pub const QUOTE_CONTEXT_LEN: usize = 8;pub fn verify(avr: &AVR, policy: &QuotePolicy) -> Result<VerifiedQuote>Verify attestation report.
+Intel Attestation Service (IAS) attestation verification report handling.
+QuoteContext is to prevent quotes from being used in
+different contexts. The value is included as a prefix in report data.pub struct AVR {
+ pub body: Vec<u8>,
+ pub signature: Vec<u8>,
+ pub certificate_chain: Vec<u8>,
+}Attestation verification report.
+body: Vec<u8>§signature: Vec<u8>§certificate_chain: Vec<u8>try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct QuotePolicy {
+ pub disabled: bool,
+ pub allowed_quote_statuses: Vec<i64>,
+ pub gid_blacklist: Vec<u32>,
+ pub min_tcb_evaluation_data_number: u32,
+}Quote validity policy.
+disabled: boolWhether IAS quotes are disabled and will always be rejected.
+allowed_quote_statuses: Vec<i64>Allowed quote statuses.
+Note: QuoteOK and QuoteSwHardeningNeeded are ALWAYS allowed, and do not need to be +specified.
+gid_blacklist: Vec<u32>List of blocked platform EPID group IDs.
+min_tcb_evaluation_data_number: u32The minimum TCB evaluation data number that should be accepted.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub type QuoteContext = [u8; 8];The purpose of QuoteContext is to prevent quotes from being used in
+different contexts. The value is included as a prefix in report data.
SGX-specific functionality.
+pub enum Error {
+Show 24 variants
UnsupportedQEVendor,
+ UnsupportedAttestationKeyType,
+ UnsupportedTeeType,
+ QuoteParseError(String),
+ VerificationFailed(String),
+ UnexpectedCertificateChain,
+ UnexpectedCertificationData,
+ MalformedCertificationData,
+ MalformedPCK,
+ TCBParseError(Error),
+ TCBVerificationFailed,
+ TCBExpired,
+ TCBOutOfDate,
+ TCBMismatch,
+ TCBEvaluationDataNumberInvalid,
+ BlacklistedFMSPC,
+ MalformedQEReport,
+ MalformedReport,
+ DebugEnclave,
+ ProductionEnclave,
+ TeeTypeNotAllowed,
+ TdxModuleNotAllowed,
+ Disabled,
+ Other(Error),
+}Possible errors returned by this module.
+Intel Provisioning Certification Services (PCS) quote handling.
+Redirecting to ../../../../../oasis_core_runtime/common/sgx/pcs/struct.QuotePolicy.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/common/sgx/pcs/policy/struct.TdxModulePolicy.html b/rust/oasis_core_runtime/common/sgx/pcs/policy/struct.TdxModulePolicy.html new file mode 100644 index 0000000000..2dc7c76d80 --- /dev/null +++ b/rust/oasis_core_runtime/common/sgx/pcs/policy/struct.TdxModulePolicy.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/common/sgx/pcs/struct.TdxModulePolicy.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/common/sgx/pcs/policy/struct.TdxQuotePolicy.html b/rust/oasis_core_runtime/common/sgx/pcs/policy/struct.TdxQuotePolicy.html new file mode 100644 index 0000000000..6d68590e6a --- /dev/null +++ b/rust/oasis_core_runtime/common/sgx/pcs/policy/struct.TdxQuotePolicy.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/common/sgx/pcs/struct.TdxQuotePolicy.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/common/sgx/pcs/quote/struct.Quote.html b/rust/oasis_core_runtime/common/sgx/pcs/quote/struct.Quote.html new file mode 100644 index 0000000000..29cf618aa7 --- /dev/null +++ b/rust/oasis_core_runtime/common/sgx/pcs/quote/struct.Quote.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/common/sgx/pcs/struct.Quote.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/common/sgx/pcs/quote/struct.QuoteBundle.html b/rust/oasis_core_runtime/common/sgx/pcs/quote/struct.QuoteBundle.html new file mode 100644 index 0000000000..3e47f81a57 --- /dev/null +++ b/rust/oasis_core_runtime/common/sgx/pcs/quote/struct.QuoteBundle.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/common/sgx/pcs/struct.QuoteBundle.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/common/sgx/pcs/report/fn.td_enclave_identity.html b/rust/oasis_core_runtime/common/sgx/pcs/report/fn.td_enclave_identity.html new file mode 100644 index 0000000000..7b347380fb --- /dev/null +++ b/rust/oasis_core_runtime/common/sgx/pcs/report/fn.td_enclave_identity.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/common/sgx/pcs/fn.td_enclave_identity.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/common/sgx/pcs/report/struct.TdAttributes.html b/rust/oasis_core_runtime/common/sgx/pcs/report/struct.TdAttributes.html new file mode 100644 index 0000000000..3d7363dcda --- /dev/null +++ b/rust/oasis_core_runtime/common/sgx/pcs/report/struct.TdAttributes.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/common/sgx/pcs/struct.TdAttributes.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/common/sgx/pcs/report/struct.TdReport.html b/rust/oasis_core_runtime/common/sgx/pcs/report/struct.TdReport.html new file mode 100644 index 0000000000..a1b44a55de --- /dev/null +++ b/rust/oasis_core_runtime/common/sgx/pcs/report/struct.TdReport.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/common/sgx/pcs/struct.TdReport.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/common/sgx/pcs/sidebar-items.js b/rust/oasis_core_runtime/common/sgx/pcs/sidebar-items.js new file mode 100644 index 0000000000..c1804c65c7 --- /dev/null +++ b/rust/oasis_core_runtime/common/sgx/pcs/sidebar-items.js @@ -0,0 +1 @@ +window.SIDEBAR_ITEMS = {"enum":["Error"],"fn":["td_enclave_identity"],"struct":["Quote","QuoteBundle","QuotePolicy","TCBBundle","TdAttributes","TdReport","TdxModulePolicy","TdxQuotePolicy"]}; \ No newline at end of file diff --git a/rust/oasis_core_runtime/common/sgx/pcs/struct.Quote.html b/rust/oasis_core_runtime/common/sgx/pcs/struct.Quote.html new file mode 100644 index 0000000000..8e564ccc86 --- /dev/null +++ b/rust/oasis_core_runtime/common/sgx/pcs/struct.Quote.html @@ -0,0 +1,28 @@ +pub struct Quote<'a> { /* private fields */ }An enclave quote.
+pub struct QuoteBundle {
+ pub quote: Vec<u8>,
+ pub tcb: TCBBundle,
+}An attestation quote together with the TCB bundle required for its verification.
+quote: Vec<u8>§tcb: TCBBundleVerify the quote bundle.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct QuotePolicy {
+ pub disabled: bool,
+ pub tcb_validity_period: u16,
+ pub min_tcb_evaluation_data_number: u32,
+ pub fmspc_blacklist: Vec<String>,
+ pub tdx: Option<TdxQuotePolicy>,
+}Quote validity policy.
+disabled: boolWhether PCS quotes are disabled and will always be rejected.
+tcb_validity_period: u16Validity (in days) of the TCB collateral.
+min_tcb_evaluation_data_number: u32Minimum TCB evaluation data number that is considered to be valid. TCB bundles containing +smaller values will be invalid.
+fmspc_blacklist: Vec<String>A list of hexadecimal encoded FMSPCs specifying which processor packages and platform +instances are blocked.
+tdx: Option<TdxQuotePolicy>Optional TDX-specific policy. In case this is None, TDX quotes are disallowed.
Whether the quote with timestamp ts is expired.
source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct TCBBundle {
+ pub tcb_info: SignedTCBInfo,
+ pub qe_identity: SignedQEIdentity,
+ pub certificates: Vec<u8>,
+}The TCB bundle contains all the required components to verify a quote’s TCB.
+tcb_info: SignedTCBInfo§qe_identity: SignedQEIdentity§certificates: Vec<u8>try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct TdAttributes(/* private fields */);TDX TD attributes.
+SEC.SEPT_VE_DISABLE (Disable EPT violation conversion to #VE on TD access of PENDING pages).
+Get the underlying bits value.
+The returned value is exactly the bits set in this flags value.
+Convert from a bits value.
+This method will return None if any unknown bits are set.
Convert from a bits value, unsetting any unknown bits.
+Convert from a bits value exactly.
+Get a flags value with the bits of a flag with the given name set.
+This method will return None if name is empty or doesn’t
+correspond to any named flag.
Whether any set bits in a source flags value are also set in a target flags value.
+Whether all set bits in a source flags value are also set in a target flags value.
+The intersection of a source flags value with the complement of a target flags value (&!).
This method is not equivalent to self & !other when other has unknown bits set.
+remove won’t truncate other, but the ! operator will.
The bitwise exclusive-or (^) of the bits in two flags values.
Call insert when value is true or remove when value is false.
The bitwise and (&) of the bits in two flags values.
The bitwise or (|) of the bits in two flags values.
The intersection of a source flags value with the complement of a target flags value (&!).
This method is not equivalent to self & !other when other has unknown bits set.
+difference won’t truncate other, but the ! operator will.
The bitwise exclusive-or (^) of the bits in two flags values.
The bitwise negation (!) of the bits in a flags value, truncating the result.
Yield a set of contained flags values.
+Each yielded flags value will correspond to a defined named flag. Any unknown bits +will be yielded together as a final flags value.
+Yield a set of contained named flags values.
+This method is like iter, except only yields bits in contained named flags.
+Any unknown bits, or bits not corresponding to a contained flag will not be yielded.
The bitwise and (&) of the bits in two flags values.
The bitwise or (|) of the bits in two flags values.
| operator.The bitwise or (|) of the bits in two flags values.
The bitwise exclusive-or (^) of the bits in two flags values.
source. Read moreThe bitwise or (|) of the bits in each flags value.
extend_one)extend_one)|) of the bits in two flags values.&!). Read more^) of the bits in two flags values.Flags::insert] when value is true or [Flags::remove] when value is false.&) of the bits in two flags values.&!). Read more^) of the bits in two flags values.!) of the bits in a flags value, truncating the result.The bitwise or (|) of the bits in each flags value.
self and other values to be equal, and is used
+by ==.The intersection of a source flags value with the complement of a target flags value (&!).
This method is not equivalent to self & !other when other has unknown bits set.
+difference won’t truncate other, but the ! operator will.
- operator.The intersection of a source flags value with the complement of a target flags value (&!).
This method is not equivalent to self & !other when other has unknown bits set.
+difference won’t truncate other, but the ! operator will.
clone_to_uninit)clone_to_uninit)key and return true if they are equal.pub struct TdReport {Show 15 fields
+ pub tee_tcb_svn: [u8; 16],
+ pub mr_seam: [u8; 48],
+ pub mr_signer_seam: [u8; 48],
+ pub seam_attributes: [u8; 8],
+ pub td_attributes: TdAttributes,
+ pub xfam: [u8; 8],
+ pub mr_td: [u8; 48],
+ pub mr_config_id: [u8; 48],
+ pub mr_owner: [u8; 48],
+ pub mr_owner_config: [u8; 48],
+ pub rtmr0: [u8; 48],
+ pub rtmr1: [u8; 48],
+ pub rtmr2: [u8; 48],
+ pub rtmr3: [u8; 48],
+ pub report_data: [u8; 64],
+}TDX TD report.
+tee_tcb_svn: [u8; 16]Describes the TCB of TDX.
+mr_seam: [u8; 48]Measurement of the TDX Module.
+mr_signer_seam: [u8; 48]Signer of the TDX Module (zero for Intel).
+seam_attributes: [u8; 8]TDX Module attributes (must be zero for TDX 1.0).
+td_attributes: TdAttributesTD attributes.
+xfam: [u8; 8]XFAM (eXtended Features Available Mask).
+mr_td: [u8; 48]Measurement of the initial contents of the TD.
+mr_config_id: [u8; 48]Software-defined ID for non-owner-defined configuration of the TD, e.g., runtime or OS +configuration.
+mr_owner: [u8; 48]Software-defined ID for the TD’s owner.
+mr_owner_config: [u8; 48]Software-defined ID for owner-defined configuration of the TD, e.g., specific to the +workload rather than the runtime or OS.
+rtmr0: [u8; 48]Runtime extendable measurement register 0.
+rtmr1: [u8; 48]Runtime extendable measurement register 1.
+rtmr2: [u8; 48]Runtime extendable measurement register 2.
+rtmr3: [u8; 48]Runtime extendable measurement register 3.
+report_data: [u8; 64]Custom report data.
+clone_to_uninit)key and return true if they are equal.pub struct TdxModulePolicy {
+ pub mr_seam: Option<[u8; 48]>,
+ pub mr_signer_seam: [u8; 48],
+}TDX module policy.
+mr_seam: Option<[u8; 48]>Optional allowed measurement of the TDX Module. In case it is None, ANY measurement is
+allowed and only the signer is checked.
mr_signer_seam: [u8; 48]Allowed signer of the TDX Module (zero for Intel).
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct TdxQuotePolicy {
+ pub allowed_tdx_modules: Vec<TdxModulePolicy>,
+}TDX-specific quote policy.
+allowed_tdx_modules: Vec<TdxModulePolicy>Allowed TDX modules. Empty to allow ANY Intel-signed module.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.Redirecting to ../../../../../oasis_core_runtime/common/sgx/pcs/struct.TCBBundle.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/common/sgx/seal/fn.new_deoxysii.html b/rust/oasis_core_runtime/common/sgx/seal/fn.new_deoxysii.html new file mode 100644 index 0000000000..12c2be25c6 --- /dev/null +++ b/rust/oasis_core_runtime/common/sgx/seal/fn.new_deoxysii.html @@ -0,0 +1,4 @@ +pub fn new_deoxysii(key_policy: Keypolicy, context: &[u8]) -> DeoxysIICreates a new Deoxys-II instance initialized with an SGX sealing key derived
+from the results of the EGETKEYinstruction.
The context field is a domain separation tag.
Wrappers for sealing secrets to the enclave in cold storage.
+EGETKEYinstruction.pub struct EnclaveIdentity {
+ pub mr_enclave: MrEnclave,
+ pub mr_signer: MrSigner,
+}Enclave identity.
+mr_enclave: MrEnclave§mr_signer: MrSignersource. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct MrEnclave(pub [u8; 32]);Enclave hash (MRENCLAVE).
+0: [u8; 32]try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)clone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub struct MrSigner(pub [u8; 32]);Enclave signer hash (MRSIGNER).
+0: [u8; 32]try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)clone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub struct QuotePolicy {
+ pub ias: Option<QuotePolicy>,
+ pub pcs: Option<QuotePolicy>,
+}Quote validity policy.
+ias: Option<QuotePolicy>§pcs: Option<QuotePolicy>source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct VerifiedQuote {
+ pub report_data: Vec<u8>,
+ pub identity: EnclaveIdentity,
+ pub timestamp: i64,
+}A remote attestation quote that has undergone verification.
+report_data: Vec<u8>§identity: EnclaveIdentity§timestamp: i64source. Read moreclone_to_uninit)pub fn insecure_posix_system_time() -> SystemTimepub fn insecure_posix_time() -> i64Returns the number of seconds since the UNIX epoch. The time returned +is guaranteed to never decrease within each enclave instance (though it +may decrease iff the enclave is re-launched).
+The returned timestamp MUST NOT be trusted on in any way, as the underlying +time source is reliant on the host operating system.
+Runtime time source.
+pub const PROTOCOL_VERSION: Version;pub struct ProtocolVersions {
+ pub consensus_protocol: Version,
+ pub runtime_host_protocol: Version,
+ pub runtime_committee_protocol: Version,
+}Protocol versions.
+consensus_protocol: Version§runtime_host_protocol: Version§runtime_committee_protocol: Versionsource. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct Version {
+ pub major: u16,
+ pub minor: u16,
+ pub patch: u16,
+}A protocol or runtime version.
+major: u16§minor: u16§patch: u16try_default in case the value is null or
+undefined.clone_to_uninit)clone_to_uninit)key and return true if they are equal.pub const VERSION_KEY: &str = "v";Version key used in serialized form.
+pub struct Versioned<T> {
+ pub version: u16,
+ pub inner: T,
+}A generic versioned serializable data structure.
+version: u16§inner: Ttry_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct Config {
+ pub version: Version,
+ pub trust_root: Option<TrustRoot>,
+ pub storage: Storage,
+ pub features: Features,
+ pub persist_check_tx_state: bool,
+}Global runtime configuration.
+version: VersionSemantic runtime version.
+trust_root: Option<TrustRoot>Optional trust root for consensus layer integrity verification.
+storage: StorageStorage configuration.
+features: FeaturesAdvertised runtime features.
+persist_check_tx_state: boolWhether storage state should be persisted between transaction check invocations. The state +is invalidated on the next round.
+clone_to_uninit)pub struct Storage {
+ pub cache_node_capacity: usize,
+ pub cache_value_capacity: usize,
+}Storage-related configuration.
+cache_node_capacity: usizeThe maximum number of tree nodes held by the cache before eviction. +A zero value denotes unlimited capacity.
+cache_value_capacity: usizeThe total size, in bytes, of values held by the cache before eviction. +A zero value denotes unlimited capacity.
+clone_to_uninit)Consensus account address structures.
+pub struct Address(/* private fields */);A staking account address.
+Creates a new address from a context, version and data.
+Creates a new runtime address.
+Tries to create a new address from Bech32-encoded string.
+try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub struct COMMON_POOL_ADDRESS { /* private fields */ }Common pool reserved address.
+pub struct FEE_ACC_ADDRESS { /* private fields */ }Per-block fee accumulator reserved address.
+pub struct GOVERNANCE_DEPOSITS_ADDRESS { /* private fields */ }Governance deposits reserved address.
+pub const EPOCH_INVALID: EpochTime = 0xffffffffffffffff;An invalid epoch time.
+pub struct EpochTimeState {
+ pub epoch: EpochTime,
+ pub height: i64,
+}The epoch state.
+epoch: EpochTime§height: i64source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub const HEIGHT_LATEST: u64 = 0;The height that represents the most recent block height.
+pub const METHOD_META: &str = "consensus.Meta";pub const MODULE_NAME: &str = "consensus";A unique module name for the consensus module.
+pub enum Event {
+ Staking(Event),
+}An event emitted by the consensus layer.
+try_default in case the value is null or
+undefined.clone_to_uninit)#[repr(u8)]pub enum Vote {
+ Invalid = 0,
+ Yes = 1,
+ No = 2,
+ Abstain = 3,
+}A governance vote.
+Invalid vote that should never be explicitly set.
+Yes Vote.
+No vote.
+Abstained.
+try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.pub struct CancelUpgradeProposal {
+ pub proposal_id: u64,
+}Cancel proposal content.
+proposal_id: u64source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct ChangeParametersProposal {
+ pub module: String,
+ pub changes: Option<Value>,
+}Change parameters proposal content.
+module: String§changes: Option<Value>source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct ConsensusParameterChanges {
+ pub gas_costs: BTreeMap<String, u64>,
+ pub min_proposal_deposit: Option<Quantity>,
+ pub voting_period: Option<EpochTime>,
+ pub stake_threshold: Option<u8>,
+ pub upgrade_min_epoch_diff: Option<EpochTime>,
+ pub upgrade_cancel_min_epoch_diff: Option<EpochTime>,
+ pub enable_change_parameters_proposal: Option<bool>,
+}gas_costs: BTreeMap<String, u64>§min_proposal_deposit: Option<Quantity>§voting_period: Option<EpochTime>§stake_threshold: Option<u8>§upgrade_min_epoch_diff: Option<EpochTime>§upgrade_cancel_min_epoch_diff: Option<EpochTime>§enable_change_parameters_proposal: Option<bool>source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct ProposalContent {
+ pub upgrade: Option<UpgradeProposal>,
+ pub cancel_upgrade: Option<CancelUpgradeProposal>,
+ pub change_parameters: Option<ChangeParametersProposal>,
+}Consensus layer governance proposal content.
+upgrade: Option<UpgradeProposal>§cancel_upgrade: Option<CancelUpgradeProposal>§change_parameters: Option<ChangeParametersProposal>source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct ProposalVote {
+ pub id: u64,
+ pub vote: Vote,
+}Vote for a proposal.
+id: u64Unique identifier of a proposal.
+vote: VoteProposal vote.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct UpgradeProposal {
+ pub v: u16,
+ pub handler: String,
+ pub target: ProtocolVersions,
+ pub epoch: EpochTime,
+}Upgrade proposal content.
+v: u16§handler: String§target: ProtocolVersions§epoch: EpochTimesource. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.Consensus service interfaces.
+pub enum Error {
+ InvalidSignature,
+}Errors emitted by the CHURP module.
+#[repr(u8)]pub enum SuiteId {
+ NistP384Sha3_384 = 0,
+}Cipher suite identifier.
+The NIST P-384 elliptic curve group with the SHA3-384 hash function +used to encode arbitrary-length byte strings to elements of the +underlying prime field or elliptic curve points.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.Key manager state in the consensus layer.
+pub struct Application {
+ pub checksum: Hash,
+ pub reconstructed: bool,
+}Application represents a node’s application to form a new committee.
+checksum: HashThe hash of the random verification matrix.
+In all handoffs, except in the dealer phase, the verification matrix +needs to be zero-hole.
+reconstructed: boolReconstructed is true if and only if the node verified all matrices +and successfully reconstructed its share during the handoff.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct PolicySGX {
+ pub id: u8,
+ pub runtime_id: Namespace,
+ pub serial: u32,
+ pub may_share: Vec<EnclaveIdentity>,
+ pub may_join: Vec<EnclaveIdentity>,
+ pub may_query: HashMap<Namespace, Vec<EnclaveIdentity>>,
+}Key manager access control policy.
+id: u8A unique identifier within the key manager runtime.
+runtime_id: NamespaceThe identifier of the key manager runtime.
+serial: u32A monotonically increasing policy serial number.
+A vector of enclave identities from which a share can be obtained +during handoffs.
+may_join: Vec<EnclaveIdentity>A vector of enclave identities that may form the new committee +in the next handoffs.
+may_query: HashMap<Namespace, Vec<EnclaveIdentity>>A map of runtime identities to the vector of enclave identities +that may query key shares.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct SignedPolicySGX {
+ pub policy: PolicySGX,
+ pub signatures: Vec<SignatureBundle>,
+}Signed key manager access control policy.
+policy: PolicySGXAn SGX access control policy.
+signatures: Vec<SignatureBundle>A vector of signatures.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct Status {Show 13 fields
+ pub id: u8,
+ pub runtime_id: Namespace,
+ pub suite_id: SuiteId,
+ pub threshold: u8,
+ pub extra_shares: u8,
+ pub handoff_interval: EpochTime,
+ pub policy: SignedPolicySGX,
+ pub handoff: EpochTime,
+ pub checksum: Option<Hash>,
+ pub committee: Vec<PublicKey>,
+ pub next_handoff: EpochTime,
+ pub next_checksum: Option<Hash>,
+ pub applications: HashMap<PublicKey, Application>,
+}Status represents the current state of a CHURP instance.
+id: u8A unique identifier within the key manager runtime.
+runtime_id: NamespaceThe identifier of the key manager runtime.
+suite_id: SuiteIdThe identifier of a cipher suite used for verifiable secret sharing +and key derivation.
+threshold: u8The degree of the secret-sharing polynomial.
+In a (t,n) secret-sharing scheme, where t represents the threshold, +any combination of t+1 or more shares can reconstruct the secret, +while losing n-t or fewer shares still allows the secret to be +recovered.
+The minimum number of shares that can be lost to render the secret +unrecoverable.
+If t and e represent the threshold and extra shares, respectively, +then the minimum size of the committee is t+e+1.
+handoff_interval: EpochTimeThe time interval in epochs between handoffs.
+A zero value disables handoffs.
+policy: SignedPolicySGXA signed SGX access control policy.
+handoff: EpochTimeThe epoch of the last successfully completed handoff.
+The zero value indicates that no handoffs have been completed so far. +Note that the first handoff is special and is called the dealer phase, +in which nodes do not reshare or randomize shares but instead construct +the secret and shares.
+checksum: Option<Hash>The hash of the verification matrix from the last successfully completed +handoff.
+committee: Vec<PublicKey>A vector of nodes holding a share of the secret in the active handoff.
+A client needs to obtain more than a threshold number of key shares +from the nodes in this vector to construct the key.
+next_handoff: EpochTimeThe epoch in which the next handoff will occur.
+If an insufficient number of applications is received, the next handoff +will be delayed by one epoch.
+next_checksum: Option<Hash>The hash of the verification matrix from the current handoff.
+The first candidate to confirm share reconstruction is the source +of truth for the checksum. All other candidates need to confirm +with the same checksum; otherwise, the applications will be annulled, +and the nodes will need to apply for the new committee again.
+applications: HashMap<PublicKey, Application>A map of nodes that wish to form the new committee.
+Candidates are expected to generate a random bivariate polynomial, +construct a verification matrix, compute its checksum, and submit +an application one epoch in advance of the next scheduled handoff. +Subsequently, upon the arrival of the handoff epoch, nodes must execute +the handoff protocol and confirm the reconstruction of its share.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub enum Error {
+ InvalidSignature,
+}Errors emitted by the key manager module.
+pub struct EnclavePolicySGX {
+ pub may_query: HashMap<Namespace, Vec<EnclaveIdentity>>,
+ pub may_replicate: Vec<EnclaveIdentity>,
+}Per enclave key manager access control policy.
+may_query: HashMap<Namespace, Vec<EnclaveIdentity>>A map of runtime IDs to the vector of enclave IDs that may query +private key material.
+may_replicate: Vec<EnclaveIdentity>A vector of enclave IDs that may retrieve the master secret.
+NOTE: Each enclave ID may always implicitly replicate from other +instances of itself.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct EncryptedEphemeralSecret {
+ pub runtime_id: Namespace,
+ pub epoch: EpochTime,
+ pub secret: EncryptedSecret,
+}Encrypted ephemeral secret.
+runtime_id: NamespaceRuntime ID of the key manager.
+epoch: EpochTimeEpoch time to which the ephemeral secret belongs.
+secret: EncryptedSecretEncrypted secret.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct EncryptedMasterSecret {
+ pub runtime_id: Namespace,
+ pub generation: u64,
+ pub epoch: EpochTime,
+ pub secret: EncryptedSecret,
+}Encrypted master secret.
+runtime_id: NamespaceRuntime ID of the key manager.
+generation: u64Generation of the secret.
+epoch: EpochTimeEpoch time in which the secret was created.
+secret: EncryptedSecretEncrypted secret.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct EncryptedSecret {
+ pub checksum: Vec<u8>,
+ pub pub_key: PublicKey,
+ pub ciphertexts: HashMap<PublicKey, Vec<u8>>,
+}A secret encrypted with Deoxys-II MRAE algorithm.
+checksum: Vec<u8>Checksum for validating decrypted secret.
+pub_key: PublicKeyPublic key to derive the symmetric key for decryption.
+ciphertexts: HashMap<PublicKey, Vec<u8>>A map of REK encrypted secrets.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct PolicySGX {
+ pub serial: u32,
+ pub id: Namespace,
+ pub enclaves: HashMap<EnclaveIdentity, EnclavePolicySGX>,
+ pub master_secret_rotation_interval: EpochTime,
+ pub max_ephemeral_secret_age: EpochTime,
+}Key manager access control policy.
+serial: u32§id: Namespace§enclaves: HashMap<EnclaveIdentity, EnclavePolicySGX>§master_secret_rotation_interval: EpochTime§max_ephemeral_secret_age: EpochTimetry_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct SignedEncryptedEphemeralSecret {
+ pub secret: EncryptedEphemeralSecret,
+ pub signature: Signature,
+}Signed encrypted ephemeral secret (RAK).
+secret: EncryptedEphemeralSecretEncrypted ephemeral secret.
+signature: SignatureSignature of the encrypted ephemeral secret.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct SignedEncryptedMasterSecret {
+ pub secret: EncryptedMasterSecret,
+ pub signature: Signature,
+}Signed encrypted master secret (RAK).
+secret: EncryptedMasterSecretEncrypted master secret.
+signature: SignatureSignature of the encrypted master secret.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct SignedPolicySGX {
+ pub policy: PolicySGX,
+ pub signatures: Vec<SignatureBundle>,
+}Signed key manager access control policy.
+policy: PolicySGX§signatures: Vec<SignatureBundle>source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub const ATTESTATION_SIGNATURE_CONTEXT: &[u8] = b"oasis-core/node: TEE attestation signature";Attestation signature context.
+pub const ENDORSE_CAPABILITY_TEE_SIGNATURE_CONTEXT: &[u8] = b"oasis-core/node: endorse TEE capability";TEE capability endorsement signature context.
+pub const LATEST_RUNTIME_DESCRIPTOR_VERSION: u16 = 3;The latest entity descriptor version that should be used for all new descriptors. Using earlier +versions may be rejected.
+pub const METHOD_PROVE_FRESHNESS: &str = "registry.ProveFreshness";The method name for freshness proofs.
+pub const MODULE_NAME: &str = "registry";A unique module name for the registry module.
+#[repr(u8)]pub enum RuntimeGovernanceModel {
+ GovernanceInvalid = 0,
+ GovernanceEntity = 1,
+ GovernanceRuntime = 2,
+ GovernanceConsensus = 3,
+}Runtime governance model.
+Invalid model that should never be explicitly set.
+Entity governance model.
+Runtime governance model.
+Consensus governance model.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.#[repr(u32)]pub enum RuntimeKind {
+ KindInvalid = 0,
+ KindCompute = 1,
+ KindKeyManager = 2,
+}Runtime kind.
+Invalid runtime that should never be explicitly set.
+Generic compute runtime.
+Key manager runtime.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub enum SGXAttestation {
+ V0(AVR),
+ V1 {
+ quote: Quote,
+ height: u64,
+ signature: Signature,
+ },
+}Intel SGX remote attestation.
+Old V0 format that only supported IAS quotes.
+New V1 format that supports both IAS and PCS policies.
+Hashes the required data that needs to be signed by RAK producing the attestation signature.
+Verifies the SGX attestation.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub enum SGXConstraints {
+ V0 {
+ enclaves: Vec<EnclaveIdentity>,
+ allowed_quote_statuses: Vec<i64>,
+ },
+ V1 {
+ enclaves: Vec<EnclaveIdentity>,
+ policy: QuotePolicy,
+ max_attestation_age: u64,
+ },
+}Intel SGX TEE constraints.
+Old V0 format that only supported IAS policies.
+enclaves: Vec<EnclaveIdentity>The allowed MRENCLAVE/MRSIGNER pairs.
+New V1 format that supports both IAS and PCS policies.
+enclaves: Vec<EnclaveIdentity>The allowed MRENCLAVE/MRSIGNER pairs.
+policy: QuotePolicyThe quote policy.
+Identities of allowed enclaves.
+Checks whether the given enclave identity is whitelisted.
+SGX quote policy.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)#[repr(u8)]pub enum TEEHardware {
+ TEEHardwareInvalid = 0,
+ TEEHardwareIntelSGX = 1,
+}TEE hardware implementation.
+Non-TEE implementation.
+Intel SGX TEE implementation.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct AnyNodeRuntimeAdmissionPolicy {}Admission policy that allows any node to register.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct Capabilities {
+ pub tee: Option<CapabilityTEE>,
+}Represents a node’s capabilities.
+tee: Option<CapabilityTEE>Is the capability of a node executing batches in a TEE.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct CapabilityTEE {
+ pub hardware: TEEHardware,
+ pub rak: PublicKey,
+ pub rek: Option<PublicKey>,
+ pub attestation: Vec<u8>,
+}Represents the node’s TEE capability.
+hardware: TEEHardwareHardware type.
+rak: PublicKeyRuntime attestation key.
+rek: Option<PublicKey>Runtime encryption key.
+attestation: Vec<u8>Attestation.
+Tries to decode the TEE-specific attestation.
+Checks whether the TEE capability matches the given TEE identity.
+Verifies the TEE capability.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct ConsensusAddress {
+ pub id: PublicKey,
+ pub address: TCPAddress,
+}Represents a consensus address that includes an ID and a TCP address.
+NOTE: The consensus address ID could be different from the consensus ID +to allow using a sentry node’s ID and address instead of the validator’s.
+id: PublicKeyPublic key identifying the node.
+address: TCPAddressAddress at which the node can be reached.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct ConsensusInfo {
+ pub id: PublicKey,
+ pub addresses: Option<Vec<ConsensusAddress>>,
+}Node’s consensus member information.
+id: PublicKeyUnique identifier of the node as a consensus member.
+addresses: Option<Vec<ConsensusAddress>>List of addresses at which the node can be reached.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct EndorsedCapabilityTEE {
+ pub capability_tee: CapabilityTEE,
+ pub node_endorsement: SignatureBundle,
+}An endorsed CapabilityTEE structure.
+Endorsement is needed for off-chain runtime components where their RAK is not published in the +consensus layer and verification is part of the runtime itself. Via endorsement one can enforce +policies like “only components executed by the current compute committee are authorized”.
+capability_tee: CapabilityTEETEE capability structure to be endorsed.
+node_endorsement: SignatureBundleNode endorsement signature.
+Verify the endorsement signature is valid.
+This does not verify the TEE capability itself, use verify for that.
Verify endorsed TEE capability is valid.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct EntityWhitelistConfig {
+ pub max_nodes: BTreeMap<RolesMask, u16>,
+}Entity whitelist configuration.
+max_nodes: BTreeMap<RolesMask, u16>Maximum number of nodes that an entity can register under the given +runtime for a specific role. If the map is empty or absent, the number +of nodes is unlimited. If the map is present and non-empty, the number +of nodes is restricted to the specified maximum (where zero +means no nodes allowed), any missing roles imply zero nodes.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct EntityWhitelistRoleAdmissionPolicy {
+ pub entities: BTreeMap<PublicKey, EntityWhitelistRoleConfig>,
+}A per-role entity whitelist policy.
+entities: BTreeMap<PublicKey, EntityWhitelistRoleConfig>source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct EntityWhitelistRoleConfig {
+ pub max_nodes: u16,
+}A per-entity whitelist configuration for a given role.
+max_nodes: u16source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct EntityWhitelistRuntimeAdmissionPolicy {
+ pub entities: BTreeMap<PublicKey, EntityWhitelistConfig>,
+}Policy that allows only whitelisted entities’ nodes to register.
+entities: BTreeMap<PublicKey, EntityWhitelistConfig>Entity whitelist configuration for each whitelisted entity.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct ExecutorParameters {
+ pub group_size: u16,
+ pub group_backup_size: u16,
+ pub allowed_stragglers: u16,
+ pub round_timeout: i64,
+ pub max_messages: u32,
+ pub min_live_rounds_percent: u8,
+ pub max_missed_proposals_percent: u8,
+ pub min_live_rounds_eval: u64,
+ pub max_liveness_fails: u8,
+}Parameters for the executor committee.
+group_size: u16Size of the committee.
+group_backup_size: u16Size of the discrepancy resolution group.
+allowed_stragglers: u16Number of allowed stragglers.
+round_timeout: i64Round timeout in consensus blocks.
+max_messages: u32Maximum number of messages that can be emitted by the runtime +in a single round.
+min_live_rounds_percent: u8Minimum percentage of rounds in an epoch that a node must participate in positively in order +to be considered live. Nodes not satisfying this may be penalized.
+max_missed_proposals_percent: u8Maximum percentage of proposed rounds in an epoch that can fail for a node +to be considered live. Nodes not satisfying this may be penalized. Zero means +that all proposed rounds can fail.
+min_live_rounds_eval: u64Minimum number of live rounds in an epoch for the liveness calculations to be considered for +evaluation.
+max_liveness_fails: u8Maximum number of liveness failures that are tolerated before suspending and/or slashing the +node. Zero means unlimited.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct MaxNodesConstraint {
+ pub limit: u16,
+}A constraint which specifies that only the given number of nodes may be eligible per entity.
+limit: u16source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct MinPoolSizeConstraint {
+ pub limit: u16,
+}A constraint which specifies the minimum required candidate pool size.
+limit: u16source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct Node {
+ pub v: u16,
+ pub id: PublicKey,
+ pub entity_id: PublicKey,
+ pub expiration: u64,
+ pub tls: TLSInfo,
+ pub p2p: P2PInfo,
+ pub consensus: ConsensusInfo,
+ pub vrf: VRFInfo,
+ pub runtimes: Option<Vec<NodeRuntime>>,
+ pub roles: RolesMask,
+ pub software_version: Option<String>,
+}Node registry descriptor.
+v: u16Structure version.
+id: PublicKeyPublic key identifying the node.
+entity_id: PublicKeyPublic key identifying the Entity controlling the node.
+expiration: u64Epoch in which the node’s commitment expires.
+tls: TLSInfoInformation for connecting to this node via TLS.
+p2p: P2PInfoInformation for connecting to this node via P2P.
+consensus: ConsensusInfoInformation for connecting to this node as a consensus member.
+vrf: VRFInfoInformation for this node’s participation in VRF based elections.
+runtimes: Option<Vec<NodeRuntime>>Node’s runtimes.
+roles: RolesMaskBitmask representing the node roles.
+software_version: Option<String>Node’s oasis-node software version.
+Checks whether the node has any of the specified roles.
+Checks whether the node has the provided TEE identity configured.
+Searches for an existing supported runtime descriptor +in runtimes with the specified version and returns it.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct NodeRuntime {
+ pub id: Namespace,
+ pub version: Version,
+ pub capabilities: Capabilities,
+ pub extra_info: Option<Vec<u8>>,
+}Represents the runtimes supported by a given Oasis node.
+id: NamespacePublic key identifying the runtime.
+version: VersionVersion of the runtime.
+capabilities: CapabilitiesNode’s capabilities for a given runtime.
+extra_info: Option<Vec<u8>>Extra per node + per runtime opaque data associated with the current instance.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct P2PInfo {
+ pub id: PublicKey,
+ pub addresses: Option<Vec<TCPAddress>>,
+}Node’s P2P information.
+id: PublicKeyUnique identifier of the node on the P2P transport.
+addresses: Option<Vec<TCPAddress>>List of addresses at which the node can be reached.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct PerRoleAdmissionPolicy {
+ pub entity_whitelist: Option<EntityWhitelistRoleAdmissionPolicy>,
+}A per-role admission policy.
+entity_whitelist: Option<EntityWhitelistRoleAdmissionPolicy>source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct RolesMask(pub u32);Oasis node roles bitmask.
+0: u32Empty roles mask.
+Compute worker role.
+Observer role.
+Key manager role.
+Validator role.
+Public consensus RPC services worker role.
+Public storage RPC services worker role.
+Whether the roles mask contains any of the specified roles.
+Whether the roles mask encodes a single valid role.
+try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)clone_to_uninit)key and return true if they are equal.pub struct Runtime {Show 15 fields
+ pub v: u16,
+ pub id: Namespace,
+ pub entity_id: PublicKey,
+ pub genesis: RuntimeGenesis,
+ pub kind: RuntimeKind,
+ pub tee_hardware: TEEHardware,
+ pub deployments: Vec<VersionInfo>,
+ pub key_manager: Option<Namespace>,
+ pub executor: ExecutorParameters,
+ pub txn_scheduler: TxnSchedulerParameters,
+ pub storage: StorageParameters,
+ pub admission_policy: RuntimeAdmissionPolicy,
+ pub constraints: BTreeMap<CommitteeKind, BTreeMap<Role, SchedulingConstraints>>,
+ pub staking: RuntimeStakingParameters,
+ pub governance_model: RuntimeGovernanceModel,
+}Runtime.
+v: u16Structure version.
+id: NamespaceGlobally unique long term identifier of the runtime.
+entity_id: PublicKeyPublic key identifying the Entity controlling the runtime.
+genesis: RuntimeGenesisRuntime genesis information.
+kind: RuntimeKindType of runtime.
+tee_hardware: TEEHardwareRuntime’s TEE hardware requirements.
+deployments: Vec<VersionInfo>Runtime deployment information.
+key_manager: Option<Namespace>Key manager runtime ID for this runtime.
+executor: ExecutorParametersParameters of the executor committee.
+txn_scheduler: TxnSchedulerParametersTransaction scheduling parameters of the executor committee.
+storage: StorageParametersParameters of the storage committee.
+admission_policy: RuntimeAdmissionPolicyWhich nodes are allowed to register for this runtime.
+constraints: BTreeMap<CommitteeKind, BTreeMap<Role, SchedulingConstraints>>Node scheduling constraints.
+staking: RuntimeStakingParametersRuntime’s staking-related parameters.
+governance_model: RuntimeGovernanceModelRuntime governance model.
+The currently active deployment for the specified epoch if it exists.
+Deployment corresponding to the specified version if it exists.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct RuntimeAdmissionPolicy {
+ pub any_node: Option<AnyNodeRuntimeAdmissionPolicy>,
+ pub entity_whitelist: Option<EntityWhitelistRuntimeAdmissionPolicy>,
+ pub per_role: BTreeMap<RolesMask, PerRoleAdmissionPolicy>,
+}Specification of which nodes are allowed to register for a runtime.
+any_node: Option<AnyNodeRuntimeAdmissionPolicy>Allow any node to register.
+entity_whitelist: Option<EntityWhitelistRuntimeAdmissionPolicy>Allow only the whitelisted entities’ nodes to register.
+per_role: BTreeMap<RolesMask, PerRoleAdmissionPolicy>A per-role admission policy that must be satisfied in addition to the global admission +policy for a specific role.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct RuntimeGenesis {
+ pub state_root: Hash,
+ pub round: u64,
+}Runtime genesis information that is used to initialize runtime state in the first block.
+state_root: HashState root that should be used at genesis time. If the runtime should start with empty state, +this must be set to the empty hash.
+round: u64Runtime round in the genesis.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct RuntimeStakingParameters {
+ pub thresholds: BTreeMap<ThresholdKind, Quantity>,
+ pub slashing: BTreeMap<SlashReason, Slash>,
+ pub reward_equivocation: u8,
+ pub reward_bad_results: u8,
+ pub min_in_message_fee: Quantity,
+}Stake-related parameters for a runtime.
+thresholds: BTreeMap<ThresholdKind, Quantity>Minimum stake thresholds for a runtime. These per-runtime thresholds are +in addition to the global thresholds. May be left unspecified.
+In case a node is registered for multiple runtimes, it will need to +satisfy the maximum threshold of all the runtimes.
+slashing: BTreeMap<SlashReason, Slash>Per-runtime misbehavior slashing parameters.
+reward_equivocation: u8The percentage of the reward obtained when slashing for equivocation that is transferred to +the runtime’s account.
+reward_bad_results: u8The percentage of the reward obtained when slashing for incorrect results that is +transferred to the runtime’s account.
+min_in_message_fee: QuantitySpecifies the minimum fee that the incoming message must include for the +message to be queued.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct SchedulingConstraints {
+ pub validator_set: Option<ValidatorSetConstraint>,
+ pub max_nodes: Option<MaxNodesConstraint>,
+ pub min_pool_size: Option<MinPoolSizeConstraint>,
+}The node scheduling constraints.
+Multiple fields may be set in which case the ALL the constraints must be satisfied.
+validator_set: Option<ValidatorSetConstraint>§max_nodes: Option<MaxNodesConstraint>§min_pool_size: Option<MinPoolSizeConstraint>source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct StorageParameters {
+ pub checkpoint_interval: u64,
+ pub checkpoint_num_kept: u64,
+ pub checkpoint_chunk_size: u64,
+}Storage parameters.
+checkpoint_interval: u64Expected runtime state checkpoint interval (in rounds).
+checkpoint_num_kept: u64Expected minimum number of checkpoints to keep.
+checkpoint_chunk_size: u64Chunk size parameter for checkpoint creation.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct TCPAddress {
+ pub ip: Vec<u8>,
+ pub port: i64,
+ pub zone: String,
+}Represents the address of a TCP endpoint.
+ip: Vec<u8>§port: i64§zone: Stringsource. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct TLSAddress {
+ pub pub_key: PublicKey,
+ pub address: TCPAddress,
+}Represents an Oasis committee address that includes a TLS public key and a TCP address.
+NOTE: The address TLS public key can be different from the actual node TLS public key to allow +using a sentry node’s addresses.
+pub_key: PublicKeyPublic key used for establishing TLS connections.
+address: TCPAddressAddress at which the node can be reached.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct TLSInfo {
+ pub pub_key: PublicKey,
+ pub _deprecated_next_pub_key: Option<PublicKey>,
+ pub _deprecated_addresses: Option<Vec<TLSAddress>>,
+}Node’s TLS information.
+pub_key: PublicKeyPublic key used for establishing TLS connections.
+_deprecated_next_pub_key: Option<PublicKey>§_deprecated_addresses: Option<Vec<TLSAddress>>try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct TxnSchedulerParameters {
+ pub batch_flush_timeout: i64,
+ pub max_batch_size: u64,
+ pub max_batch_size_bytes: u64,
+ pub max_in_messages: u32,
+ pub propose_batch_timeout: i64,
+}Parameters for the runtime transaction scheduler.
+batch_flush_timeout: i64How long to wait for a scheduled batch in nanoseconds (when using the +“simple” scheduling algorithm).
+max_batch_size: u64Maximum size of a scheduled batch.
+max_batch_size_bytes: u64Maximum size of a scheduled batch in bytes.
+max_in_messages: u32Maximum size of the incoming message queue.
+propose_batch_timeout: i64How long to wait before accepting proposal from the next backup scheduler in nanoseconds.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct VRFInfo {
+ pub id: PublicKey,
+}Contains information for this node’s participation in VRF based elections.
+id: PublicKeyUnique identifier of the node used to generate VRF proofs.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct ValidatorSetConstraint {}A constraint which specifies that the entity must have a node that is part of the validator set. +No other options can currently be specified.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct VerifiedAttestation {
+ pub quote: VerifiedQuote,
+ pub height: Option<u64>,
+}Verified remote attestation.
+quote: VerifiedQuoteVerified enclave quote.
+height: Option<u64>Enclave’s view of the consensus layer height at the time of attestation.
+source. Read moreclone_to_uninit)pub struct VerifiedEndorsedCapabilityTEE {
+ pub verified_attestation: VerifiedAttestation,
+ pub node_id: Option<PublicKey>,
+}A verified endorsed CapabilityTEE structure.
+verified_attestation: VerifiedAttestationVerified TEE remote attestation.
+node_id: Option<PublicKey>Optional identifier of the node that endorsed the TEE capability.
+source. Read moreclone_to_uninit)pub struct VersionInfo {
+ pub version: Version,
+ pub valid_from: EpochTime,
+ pub tee: Vec<u8>,
+ pub bundle_checksum: Vec<u8>,
+}Per-runtime version information.
+version: VersionVersion of the runtime.
+valid_from: EpochTimeThe epoch at which this version is valid.
+tee: Vec<u8>Enclave version information, in an enclave provided specific format (if any).
+bundle_checksum: Vec<u8>The SHA256 hash of the runtime bundle (optional).
+Tries to decode the TEE-specific version information.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.Redirecting to ../../../../oasis_core_runtime/consensus/roothash/enum.HeaderType.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/block/struct.Block.html b/rust/oasis_core_runtime/consensus/roothash/block/struct.Block.html new file mode 100644 index 0000000000..cfc70f0b2d --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/block/struct.Block.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../oasis_core_runtime/consensus/roothash/struct.Block.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/block/struct.Header.html b/rust/oasis_core_runtime/consensus/roothash/block/struct.Header.html new file mode 100644 index 0000000000..8ede2ed4a9 --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/block/struct.Header.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../oasis_core_runtime/consensus/roothash/struct.Header.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/commitment/executor/constant.COMPUTE_RESULTS_HEADER_SIGNATURE_CONTEXT.html b/rust/oasis_core_runtime/consensus/roothash/commitment/executor/constant.COMPUTE_RESULTS_HEADER_SIGNATURE_CONTEXT.html new file mode 100644 index 0000000000..c88d2a34bb --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/commitment/executor/constant.COMPUTE_RESULTS_HEADER_SIGNATURE_CONTEXT.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/consensus/roothash/constant.COMPUTE_RESULTS_HEADER_SIGNATURE_CONTEXT.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/commitment/executor/constant.EXECUTOR_COMMITMENT_SIGNATURE_CONTEXT.html b/rust/oasis_core_runtime/consensus/roothash/commitment/executor/constant.EXECUTOR_COMMITMENT_SIGNATURE_CONTEXT.html new file mode 100644 index 0000000000..878d9314c5 --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/commitment/executor/constant.EXECUTOR_COMMITMENT_SIGNATURE_CONTEXT.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/consensus/roothash/constant.EXECUTOR_COMMITMENT_SIGNATURE_CONTEXT.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/commitment/executor/enum.ExecutorCommitmentFailure.html b/rust/oasis_core_runtime/consensus/roothash/commitment/executor/enum.ExecutorCommitmentFailure.html new file mode 100644 index 0000000000..19de9d8a00 --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/commitment/executor/enum.ExecutorCommitmentFailure.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/consensus/roothash/enum.ExecutorCommitmentFailure.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/commitment/executor/struct.ComputeResultsHeader.html b/rust/oasis_core_runtime/consensus/roothash/commitment/executor/struct.ComputeResultsHeader.html new file mode 100644 index 0000000000..e606b821f3 --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/commitment/executor/struct.ComputeResultsHeader.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/consensus/roothash/struct.ComputeResultsHeader.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/commitment/executor/struct.ExecutorCommitment.html b/rust/oasis_core_runtime/consensus/roothash/commitment/executor/struct.ExecutorCommitment.html new file mode 100644 index 0000000000..3527316416 --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/commitment/executor/struct.ExecutorCommitment.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/consensus/roothash/struct.ExecutorCommitment.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/commitment/executor/struct.ExecutorCommitmentHeader.html b/rust/oasis_core_runtime/consensus/roothash/commitment/executor/struct.ExecutorCommitmentHeader.html new file mode 100644 index 0000000000..47eb1cf63a --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/commitment/executor/struct.ExecutorCommitmentHeader.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/consensus/roothash/struct.ExecutorCommitmentHeader.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/commitment/pool/struct.Pool.html b/rust/oasis_core_runtime/consensus/roothash/commitment/pool/struct.Pool.html new file mode 100644 index 0000000000..2449fd259d --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/commitment/pool/struct.Pool.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/consensus/roothash/struct.Pool.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/commitment/pool/trait.MessageValidator.html b/rust/oasis_core_runtime/consensus/roothash/commitment/pool/trait.MessageValidator.html new file mode 100644 index 0000000000..824330f537 --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/commitment/pool/trait.MessageValidator.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/consensus/roothash/trait.MessageValidator.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/commitment/pool/trait.NodeLookup.html b/rust/oasis_core_runtime/consensus/roothash/commitment/pool/trait.NodeLookup.html new file mode 100644 index 0000000000..c09efc22e1 --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/commitment/pool/trait.NodeLookup.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/consensus/roothash/trait.NodeLookup.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/commitment/trait.OpenCommitment.html b/rust/oasis_core_runtime/consensus/roothash/commitment/trait.OpenCommitment.html new file mode 100644 index 0000000000..bf4d238cb2 --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/commitment/trait.OpenCommitment.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../oasis_core_runtime/consensus/roothash/trait.OpenCommitment.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/constant.COMPUTE_RESULTS_HEADER_SIGNATURE_CONTEXT.html b/rust/oasis_core_runtime/consensus/roothash/constant.COMPUTE_RESULTS_HEADER_SIGNATURE_CONTEXT.html new file mode 100644 index 0000000000..ed3c66d601 --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/constant.COMPUTE_RESULTS_HEADER_SIGNATURE_CONTEXT.html @@ -0,0 +1,2 @@ +pub const COMPUTE_RESULTS_HEADER_SIGNATURE_CONTEXT: &[u8] = b"oasis-core/roothash: compute results header";The signature context used to sign compute results headers with RAK.
+pub const EXECUTOR_COMMITMENT_SIGNATURE_CONTEXT: &[u8] = b"oasis-core/roothash: executor commitment";The signature context used to sign executor worker commitments.
+pub enum Error {
+Show 17 variants
InvalidRuntime(Namespace),
+ State(StateError),
+ NoRuntime,
+ NoCommittee,
+ InvalidCommitteeKind,
+ RakSigInvalid,
+ NotInCommittee,
+ AlreadyCommitted,
+ NotBasedOnCorrectBlock,
+ DiscrepancyDetected,
+ StillWaiting,
+ InsufficientVotes,
+ BadExecutorCommitment,
+ InvalidMessages,
+ InvalidRound,
+ NoProposerCommitment,
+ BadProposerCommitment,
+}Errors emitted by the roothash module.
+#[repr(u8)]pub enum ExecutorCommitmentFailure {
+ FailureNone = 0,
+ FailureUnknown = 1,
+ FailureStateUnavailable = 2,
+}The executor commitment failure reason.
+Indicates that no failure has occurred.
+Indicates a generic failure.
+Indicates that batch processing failed due to the state being +unavailable.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub enum GovernanceMessage {
+ CastVote(ProposalVote),
+ SubmitProposal(ProposalContent),
+}Performs basic validation of the governance message.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.#[repr(u8)]pub enum HeaderType {
+ Invalid = 0,
+ Normal = 1,
+ RoundFailed = 2,
+ EpochTransition = 3,
+ Suspended = 4,
+}source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub enum Message {
+ Staking(Versioned<StakingMessage>),
+ Registry(Versioned<RegistryMessage>),
+ Governance(Versioned<GovernanceMessage>),
+}A message that can be emitted by the runtime to be processed by the consensus layer.
+Returns a hash of provided runtime messages.
+Returns a hash of provided incoming runtime messages.
+Performs basic validation of the runtime message.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub enum RegistryMessage {
+ UpdateRuntime(Runtime),
+}Performs basic validation of the registry message.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub enum StakingMessage {
+ Transfer(Transfer),
+ Withdraw(Withdraw),
+ AddEscrow(Escrow),
+ ReclaimEscrow(ReclaimEscrow),
+}Performs basic validation of the staking message.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.Redirecting to ../../../../oasis_core_runtime/consensus/roothash/enum.GovernanceMessage.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/message/enum.Message.html b/rust/oasis_core_runtime/consensus/roothash/message/enum.Message.html new file mode 100644 index 0000000000..5c639c4192 --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/message/enum.Message.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../oasis_core_runtime/consensus/roothash/enum.Message.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/message/enum.RegistryMessage.html b/rust/oasis_core_runtime/consensus/roothash/message/enum.RegistryMessage.html new file mode 100644 index 0000000000..a8a5f06b6a --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/message/enum.RegistryMessage.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../oasis_core_runtime/consensus/roothash/enum.RegistryMessage.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/message/enum.StakingMessage.html b/rust/oasis_core_runtime/consensus/roothash/message/enum.StakingMessage.html new file mode 100644 index 0000000000..7ac803a89d --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/message/enum.StakingMessage.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../oasis_core_runtime/consensus/roothash/enum.StakingMessage.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/message/struct.IncomingMessage.html b/rust/oasis_core_runtime/consensus/roothash/message/struct.IncomingMessage.html new file mode 100644 index 0000000000..b6fb77003a --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/message/struct.IncomingMessage.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../oasis_core_runtime/consensus/roothash/struct.IncomingMessage.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/sidebar-items.js b/rust/oasis_core_runtime/consensus/roothash/sidebar-items.js new file mode 100644 index 0000000000..f728757bdf --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/sidebar-items.js @@ -0,0 +1 @@ +window.SIDEBAR_ITEMS = {"constant":["COMPUTE_RESULTS_HEADER_SIGNATURE_CONTEXT","EXECUTOR_COMMITMENT_SIGNATURE_CONTEXT"],"enum":["Error","ExecutorCommitmentFailure","GovernanceMessage","HeaderType","Message","RegistryMessage","StakingMessage"],"struct":["AnnotatedBlock","Block","ComputeResultsHeader","ExecutorCommitment","ExecutorCommitmentHeader","Header","IncomingMessage","MessageEvent","Pool","RoundResults","RoundRoots"],"trait":["MessageValidator","NodeLookup","OpenCommitment"]}; \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/roothash/struct.AnnotatedBlock.html b/rust/oasis_core_runtime/consensus/roothash/struct.AnnotatedBlock.html new file mode 100644 index 0000000000..a8da8f87c9 --- /dev/null +++ b/rust/oasis_core_runtime/consensus/roothash/struct.AnnotatedBlock.html @@ -0,0 +1,38 @@ +pub struct AnnotatedBlock {
+ pub consensus_height: i64,
+ pub block: Block,
+}Runtime block annotated with consensus information.
+consensus_height: i64Consensus height at which this runtime block was produced.
+block: BlockRuntime block.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct Block {
+ pub header: Header,
+}header: HeaderHeader.
+Creates a new empty genesis block given a runtime id and POSIX timestamp.
+Creates a new empty block with a specific type.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct ComputeResultsHeader {
+ pub round: u64,
+ pub previous_hash: Hash,
+ pub io_root: Option<Hash>,
+ pub state_root: Option<Hash>,
+ pub messages_hash: Option<Hash>,
+ pub in_msgs_hash: Option<Hash>,
+ pub in_msgs_count: u32,
+}The header of a computed batch output by a runtime. This header is a +compressed representation (e.g., hashes instead of full content) of +the actual results.
+This should be kept in sync with go/roothash/api/commitment/executor.go.
+round: u64Round number.
+previous_hash: HashHash of the previous block header this batch was computed against.
+io_root: Option<Hash>The I/O merkle root.
+state_root: Option<Hash>The root hash of the state after computing this batch.
+messages_hash: Option<Hash>Hash of messages sent from this batch.
+in_msgs_hash: Option<Hash>The hash of processed incoming messages.
+in_msgs_count: u32The number of processed incoming messages.
+Returns a hash of an encoded header.
+Returns true iff the header is the parent of a child header.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct ExecutorCommitment {
+ pub node_id: PublicKey,
+ pub header: ExecutorCommitmentHeader,
+ pub signature: Signature,
+ pub messages: Vec<Message>,
+}A commitment to results of processing a proposed runtime block.
+node_id: PublicKey§header: ExecutorCommitmentHeader§signature: Signature§messages: Vec<Message>Signs the executor commitment header and sets the signature on the commitment.
+Verifies that the header signature is valid.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct ExecutorCommitmentHeader {
+ pub header: ComputeResultsHeader,
+ pub failure: ExecutorCommitmentFailure,
+ pub rak_signature: Option<Signature>,
+}The header of an executor commitment.
+header: ComputeResultsHeaderThe compute results header.
+failure: ExecutorCommitmentFailureThe executor commitment failure reason.
+rak_signature: Option<Signature>source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct Header {
+ pub version: u16,
+ pub namespace: Namespace,
+ pub round: u64,
+ pub timestamp: u64,
+ pub header_type: HeaderType,
+ pub previous_hash: Hash,
+ pub io_root: Hash,
+ pub state_root: Hash,
+ pub messages_hash: Hash,
+ pub in_msgs_hash: Hash,
+}version: u16Protocol version number.
+namespace: NamespaceChain namespace.
+round: u64Round number.
+timestamp: u64Timestamp (POSIX time).
+header_type: HeaderTypeHeader type.
+previous_hash: HashPrevious block hash.
+io_root: HashI/O merkle root.
+state_root: HashState merkle root.
+messages_hash: HashMessages hash.
+in_msgs_hash: HashHash of processed incoming messages.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct IncomingMessage {
+ pub id: u64,
+ pub caller: Address,
+ pub tag: u64,
+ pub fee: Quantity,
+ pub tokens: Quantity,
+ pub data: Vec<u8>,
+}An incoming message emitted by the consensus layer to be processed by the runtime.
+id: u64Unique identifier of the message.
+caller: AddressAddress of the caller authenticated by the consensus layer.
+tag: u64An optional tag provided by the caller which is ignored and can be used to match processed +incoming message events later.
+fee: QuantityFee sent into the runtime as part of the message being sent. The fee is transferred before +the message is processed by the runtime.
+tokens: QuantityTokens sent into the runtime as part of the message being sent. The tokens are transferred +before the message is processed by the runtime.
+data: Vec<u8>Arbitrary runtime-dependent data.
+Returns a hash of provided runtime messages.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct MessageEvent {
+ pub module: String,
+ pub code: u32,
+ pub index: u32,
+ pub result: Option<Value>,
+}Result of a message being processed by the consensus layer.
+module: String§code: u32§index: u32§result: Option<Value>Returns true if the event indicates that the message was successfully processed.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct Pool { /* private fields */ }A pool of commitments that can be used to perform +discrepancy detection.
+The pool is not safe for concurrent use.
+Verifies and adds a new executor commitment to the pool.
+Performs a single round of commitment checks. If there are enough commitments +in the pool, it performs discrepancy detection or resolution.
+pub struct RoundResults {
+ pub messages: Vec<MessageEvent>,
+ pub good_compute_entities: Vec<PublicKey>,
+ pub bad_compute_entities: Vec<PublicKey>,
+}Information about how a particular round was executed by the consensus layer.
+messages: Vec<MessageEvent>Results of executing emitted runtime messages.
+good_compute_entities: Vec<PublicKey>Public keys of compute nodes’ controlling entities that positively contributed to the round +by replicating the computation correctly.
+bad_compute_entities: Vec<PublicKey>Public keys of compute nodes’ controlling entities that negatively contributed to the round +by causing discrepancies.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct RoundRoots {
+ pub state_root: Hash,
+ pub io_root: Hash,
+}Per-round state and I/O roots that are stored in consensus state.
+state_root: Hash§io_root: Hashsource. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub trait OpenCommitment {
+ // Required methods
+ fn mostly_equal(&self, other: &Self) -> bool
+ where Self: Sized;
+ fn is_indicating_failure(&self) -> bool;
+ fn to_vote(&self) -> Hash;
+ fn to_dd_result(&self) -> &dyn Any;
+}Verified roothash commitment.
+Returns true if the commitment is mostly equal to another +specified commitment as per discrepancy detection criteria.
+The caller MUST guarantee that the passed commitment is of the same +type.
+Returns true if this commitment indicates a failure.
+Returns a hash that represents a vote for this commitment as +per discrepancy resolution criteria.
+Returns a commitment-specific result after discrepancy +detection.
+#[repr(u8)]pub enum CommitteeKind {
+ Invalid = 0,
+ ComputeExecutor = 1,
+}The functionality a committee exists to provide.
+An invalid committee (should never appear on the wire).
+A compute executor committee.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.#[repr(u8)]pub enum Role {
+ Invalid = 0,
+ Worker = 1,
+ BackupWorker = 2,
+}The role a given node plays in a committee.
+An invalid role (should never appear on the wire).
+Indicates the node is a worker.
+Indicates the node is a backup worker.
+try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.pub struct Committee {
+ pub kind: CommitteeKind,
+ pub members: Vec<CommitteeNode>,
+ pub runtime_id: Namespace,
+ pub valid_for: EpochTime,
+}A per-runtime (instance) committee.
+kind: CommitteeKindThe functionality a committee exists to provide.
+members: Vec<CommitteeNode>The committee members.
+runtime_id: NamespaceThe runtime ID that this committee is for.
+valid_for: EpochTimeThe epoch for which the committee is valid.
+Returns committee nodes with Worker role.
+Returns the transaction scheduler of the provided committee based on the provided round.
+pub struct CommitteeNode {
+ pub role: Role,
+ pub public_key: PublicKey,
+}A node participating in a committee.
+role: RoleThe node’s role in a committee.
+public_key: PublicKeyThe node’s public key.
+pub enum EscrowEvent {
+ Add {
+ owner: Address,
+ escrow: Address,
+ amount: Quantity,
+ new_shares: Quantity,
+ },
+ Take {
+ owner: Address,
+ amount: Quantity,
+ debonding_amount: Quantity,
+ },
+ DebondingStart {
+ owner: Address,
+ escrow: Address,
+ amount: Quantity,
+ active_shares: Quantity,
+ debonding_shares: Quantity,
+ debond_end_time: EpochTime,
+ },
+ Reclaim {
+ owner: Address,
+ escrow: Address,
+ amount: Quantity,
+ shares: Quantity,
+ },
+}Escrow-related events.
+Event emitted when stake is transferred into an escrow account.
+Event emitted when stake is taken from an escrow account (i.e. stake is slashed).
+Event emitted when the debonding process has started and the given number of active shares +have been moved into the debonding pool and started debonding.
+Note that the given amount is valid at the time of debonding start and may not correspond to +the final debonded amount in case any escrowed stake is subject to slashing.
+Event emitted when stake is reclaimed from an escrow account back into owner’s general +account.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.#[repr(u8)]pub enum SlashReason {
+ RuntimeIncorrectResults = 128,
+ RuntimeEquivocation = 129,
+ RuntimeLiveness = 130,
+}Reason for slashing an entity.
+Slashing due to submission of incorrect results in runtime executor commitments.
+Slashing due to signing two different executor commits or proposed batches for the same +round.
+Slashing due to not doing the required work.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.#[repr(i32)]pub enum ThresholdKind {
+ KindEntity = 0,
+ KindNodeValidator = 1,
+ KindNodeCompute = 2,
+ KindNodeKeyManager = 4,
+ KindRuntimeCompute = 5,
+ KindRuntimeKeyManager = 6,
+}Kind of staking threshold.
+Entity staking threshold.
+Validator node staking threshold.
+Compute node staking threshold.
+Keymanager node staking threshold.
+Compute runtime staking threshold.
+Keymanager runtime staking threshold.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.pub struct Account {
+ pub general: GeneralAccount,
+ pub escrow: EscrowAccount,
+}Entry in the staking ledger.
+general: GeneralAccount§escrow: EscrowAccounttry_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct AddEscrowResult {
+ pub owner: Address,
+ pub escrow: Address,
+ pub amount: Quantity,
+ pub new_shares: Quantity,
+}Add escrow result.
+owner: Address§escrow: Address§amount: Quantitysource. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct AllowanceChangeEvent {
+ pub owner: Address,
+ pub beneficiary: Address,
+ pub allowance: Quantity,
+ pub negative: bool,
+ pub amount_change: Quantity,
+}Event emitted when allowance is changed for a beneficiary.
+owner: Address§beneficiary: Address§allowance: Quantity§negative: bool§amount_change: Quantitysource. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct BurnEvent {
+ pub owner: Address,
+ pub amount: Quantity,
+}Event emitted when stake is destroyed via a call to Burn.
+owner: Address§amount: Quantitytry_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct CommissionRateBoundStep {
+ pub start: EpochTime,
+ pub rate_min: Quantity,
+ pub rate_max: Quantity,
+}Commission rate bound and its starting time.
+start: EpochTime§rate_min: Quantity§rate_max: Quantitysource. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct CommissionRateStep {
+ pub start: EpochTime,
+ pub rate: Quantity,
+}Commission rate and its starting time.
+start: EpochTime§rate: Quantitysource. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct CommissionSchedule {
+ pub rates: Vec<CommissionRateStep>,
+ pub bounds: Vec<CommissionRateBoundStep>,
+}Defines a list of commission rates and commission rate bounds with their starting times.
+rates: Vec<CommissionRateStep>§bounds: Vec<CommissionRateBoundStep>source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct DebondingDelegation {
+ pub shares: Quantity,
+ pub debond_end_time: EpochTime,
+}Debonding delegation descriptor.
+debond_end_time: EpochTimesource. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct Delegation {
+ pub shares: Quantity,
+}Delegation descriptor.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct Escrow {
+ pub account: Address,
+ pub amount: Quantity,
+}A stake escrow.
+account: Address§amount: Quantitytry_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct EscrowAccount {
+ pub active: SharePool,
+ pub debonding: SharePool,
+ pub commission_schedule: CommissionSchedule,
+ pub stake_accumulator: StakeAccumulator,
+}Escrow account.
+active: SharePool§debonding: SharePool§commission_schedule: CommissionSchedule§stake_accumulator: StakeAccumulatorsource. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct Event {
+ pub height: i64,
+ pub tx_hash: Hash,
+ pub transfer: Option<TransferEvent>,
+ pub burn: Option<BurnEvent>,
+ pub escrow: Option<EscrowEvent>,
+ pub allowance_change: Option<AllowanceChangeEvent>,
+}A staking-related event.
+height: i64§tx_hash: Hash§transfer: Option<TransferEvent>§burn: Option<BurnEvent>§escrow: Option<EscrowEvent>§allowance_change: Option<AllowanceChangeEvent>try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct GeneralAccount {
+ pub balance: Quantity,
+ pub nonce: u64,
+ pub allowances: BTreeMap<Address, Quantity>,
+}General purpose account.
+balance: Quantity§nonce: u64§allowances: BTreeMap<Address, Quantity>source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct ReclaimEscrow {
+ pub account: Address,
+ pub shares: Quantity,
+}A reclaim escrow.
+account: Addresssource. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct ReclaimEscrowResult {
+ pub owner: Address,
+ pub escrow: Address,
+ pub amount: Quantity,
+ pub remaining_shares: Quantity,
+ pub debonding_shares: Quantity,
+ pub debond_end_time: EpochTime,
+}Reclaim escrow result.
+owner: Address§escrow: Address§amount: Quantity§debond_end_time: EpochTimesource. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct SharePool {
+ pub balance: Quantity,
+ pub total_shares: Quantity,
+}Combined balance of serval entries, the relative sizes of which are tracked through shares.
+balance: Quantitytry_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct Slash {
+ pub amount: Quantity,
+ pub freeze_interval: EpochTime,
+}Per-reason slashing configuration.
+amount: Quantity§freeze_interval: EpochTimetry_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct StakeAccumulator {
+ pub claims: BTreeMap<StakeClaim, Vec<StakeThreshold>>,
+}Per escrow account stake accumulator.
+claims: BTreeMap<StakeClaim, Vec<StakeThreshold>>source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct StakeThreshold {
+ pub global: Option<ThresholdKind>,
+ pub constant: Option<Quantity>,
+}Stake threshold used in the stake accumulator.
+global: Option<ThresholdKind>§constant: Option<Quantity>source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct Transfer {
+ pub to: Address,
+ pub amount: Quantity,
+}A stake transfer.
+to: Address§amount: Quantitytry_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct TransferEvent {
+ pub from: Address,
+ pub to: Address,
+ pub amount: Quantity,
+}Event emitted when stake is transferred, either by a call to Transfer or Withdraw.
+from: Address§to: Address§amount: Quantitysource. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct TransferResult {
+ pub from: Address,
+ pub to: Address,
+ pub amount: Quantity,
+}Transfer result.
+from: Address§to: Address§amount: Quantitysource. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct Withdraw {
+ pub from: Address,
+ pub amount: Quantity,
+}A withdrawal from an account.
+from: Address§amount: Quantitytry_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct WithdrawResult {
+ pub owner: Address,
+ pub beneficiary: Address,
+ pub allowance: Quantity,
+ pub amount_change: Quantity,
+}Withdraw result.
+owner: Address§beneficiary: Address§allowance: Quantity§amount_change: Quantitysource. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub type StakeClaim = String;Unique stake claim identifier.
+struct StakeClaim { /* private fields */ }pub struct ImmutableState<'a, T: ImmutableMKVS> { /* private fields */ }Consensus beacon state wrapper.
+Constructs a new ImmutableMKVS.
+Returns the current epoch number.
+Returns the current epoch state.
+Returns the future epoch number.
+Returns the future epoch state.
+pub struct MutableState;Mutable consensus beacon state wrapper.
+Set current epoch state.
+Set future epoch state.
+pub enum StateError {
+ Unavailable(Error),
+}Consensus state wrappers.
+Key manager state in the consensus layer.
+pub struct ImmutableState<'a, T: ImmutableMKVS> { /* private fields */ }Consensus CHURP state wrapper.
+Constructs a new ImmutableMKVS.
+Key manager state in the consensus layer.
+pub struct ImmutableState<'a, T: ImmutableMKVS> { /* private fields */ }Consensus key manager state wrapper.
+Constructs a new ImmutableMKVS.
+Looks up a specific key manager status by its namespace identifier.
+Returns the list of all key manager statuses.
+Looks up a specific key manager master secret by its namespace identifier.
+Looks up a specific key manager ephemeral secret by its namespace identifier and epoch.
+pub struct Status {
+ pub id: Namespace,
+ pub is_initialized: bool,
+ pub is_secure: bool,
+ pub generation: u64,
+ pub rotation_epoch: EpochTime,
+ pub checksum: Vec<u8>,
+ pub nodes: Vec<PublicKey>,
+ pub policy: Option<SignedPolicySGX>,
+ pub rsk: Option<PublicKey>,
+}Current key manager status.
+id: NamespaceRuntime ID of the key manager.
+is_initialized: boolTrue iff the key manager is done initializing.
+is_secure: boolTrue iff the key manager is secure.
+generation: u64Generation of the latest master secret.
+rotation_epoch: EpochTimeEpoch of the last master secret rotation.
+checksum: Vec<u8>Key manager master secret verification checksum.
+nodes: Vec<PublicKey>List of currently active key manager node IDs.
+policy: Option<SignedPolicySGX>Key manager policy.
+rsk: Option<PublicKey>Runtime signing key of the key manager.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct ImmutableState<'a, T: ImmutableMKVS> { /* private fields */ }Consensus registry state wrapper.
+Constructs a new ImmutableMKVS.
+pub struct ImmutableState<'a, T: ImmutableMKVS> { /* private fields */ }Consensus roothash state wrapper.
+Constructs a new ImmutableMKVS.
+Returns the state root for a specific runtime.
+Returns the last round results for a specific runtime.
+pub struct ImmutableState<'a, T: ImmutableMKVS> { /* private fields */ }Consensus staking state wrapper.
+Constructs a new ImmutableMKVS.
+Returns the staking account for the given account address.
+Returns the total supply.
+Returns the balance of the global common pool.
+Returns the last block fees balance.
+Returns the governance deposits balance.
+Returns the non-empty addresses from the staking ledger.
+Returns the delegation.
+Returns all active delegations.
+Returns the debonding delegation.
+Returns all debonding delegations.
+pub struct ConsensusState { /* private fields */ }Provides consensus state tree from the host.
+pub struct BlockMetadata {
+ pub state_root: Hash,
+ pub events_root: Vec<u8>,
+}BlockMetadata contains additional metadata related to the executing block.
+The metadata is included in the form of a special transaction where this structure is the +transaction body.
+state_root: HashState root after executing all logic in the block.
+events_root: Vec<u8>source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct LightBlock {
+ pub height: u64,
+ pub meta: Vec<u8>,
+}Light consensus block.
+height: u64§meta: Vec<u8>source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub const BACKEND_NAME: &str = "tendermint";Tendermint consensus backend name. +Keep synced with go/consensus/cometbft/api/api.go.
+pub const TENDERMINT_CONTEXT: &[u8] = b"oasis-core/tendermint";The domain separation context used by Oasis Core for Tendermint cryptography. +Keep synced with go/consensus/cometbft/crypto/signature.go.
+pub fn chain_id(chain_context: &str) -> IdConvert an Oasis Core chain context into a Tendermint chain ID.
+pub fn decode_light_block(light_block: LightBlock) -> Result<LightBlockMeta>Decode the light block metadata as a Tendermint light block.
+pub fn encode_light_block(
+ light_block_meta: LightBlockMeta,
+) -> Result<LightBlock>Encode the light block metadata to a Tendermint light block.
+pub fn state_root_from_header(signed_header: &SignedHeader) -> RootExtract state root from the given signed block header.
+The signed header must be present and the application hash must be a valid Oasis Core +application hash (state root hash).
+Tendermint consensus layer backend.
+pub const MAX_AUNTS: usize = 100;Maximum number of aunts that can be included in a Proof. +This corresponds to a tree of size 2^100, which should be sufficient for all conceivable purposes. +This maximum helps prevent Denial-of-Service attacks by limiting the size of the proofs.
+Merkle proofs used in Tendermint networks
+Rewritten to Rust from: +https://github.com/tendermint/tendermint/blob/main/crypto/merkle/proof.go
+Helper functions copied from: +https://github.com/informalsystems/tendermint-rs/blob/main/tendermint/src/merkle.rs
+pub struct Proof {
+ pub total: i64,
+ pub index: i64,
+ pub leaf_hash: Hash,
+ pub aunts: Vec<Hash>,
+}Proof represents a Merkle proof.
+NOTE: The convention for proofs is to include leaf hashes but to +exclude the root hash. +This convention is implemented across IAVL range proofs as well. +Keep this consistent unless there’s a very good reason to change +everything. This also affects the generalized proof system as +well.
+total: i64§index: i64§leaf_hash: Hash§aunts: Vec<Hash>try_default in case the value is null or
+undefined.pub struct LightBlockMeta {
+ pub signed_header: Option<SignedHeader>,
+ pub validators: Set,
+}Tendermint light consensus block metadata.
+signed_header: Option<SignedHeader>§validators: SetState root specified by this light block.
+The signed header must be present and the application hash must be a valid Oasis Core +application hash (state root hash).
+source. Read moreVec<u8>.Vec<u8> (or equivalent).Vec<u8> Protobuf-encoded message.Vec<u8> or equivalent.clone_to_uninit)Tendermint consensus layer verification logic.
+Redirecting to ../../../../../oasis_core_runtime/consensus/tendermint/verifier/struct.NopVerifier.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/tendermint/verifier/sidebar-items.js b/rust/oasis_core_runtime/consensus/tendermint/verifier/sidebar-items.js new file mode 100644 index 0000000000..9bd8b333fd --- /dev/null +++ b/rust/oasis_core_runtime/consensus/tendermint/verifier/sidebar-items.js @@ -0,0 +1 @@ +window.SIDEBAR_ITEMS = {"struct":["NopVerifier","Verifier"]}; \ No newline at end of file diff --git a/rust/oasis_core_runtime/consensus/tendermint/verifier/struct.NopVerifier.html b/rust/oasis_core_runtime/consensus/tendermint/verifier/struct.NopVerifier.html new file mode 100644 index 0000000000..c757d75fa1 --- /dev/null +++ b/rust/oasis_core_runtime/consensus/tendermint/verifier/struct.NopVerifier.html @@ -0,0 +1,69 @@ +pub struct NopVerifier { /* private fields */ }A verifier which performs no verification.
+pub struct Verifier { /* private fields */ }Tendermint consensus layer verifier.
+pub const SIGNATURE_CONTEXT: &[u8] = b"oasis-core/consensus: tx";pub struct Fee {
+ pub amount: Quantity,
+ pub gas: Gas,
+}Consensus transaction fee the sender wishes to pay for operations which +require a fee to be paid to validators.
+amount: QuantityFee amount to be paid.
+gas: GasMaximum gas that a transaction can use.
+try_default in case the value is null or
+undefined.pub struct Proof {
+ pub height: u64,
+ pub raw_proof: Vec<u8>,
+}Proof of transaction inclusion in a block.
+height: u64Block height at which the transaction was published.
+raw_proof: Vec<u8>Actual raw proof.
+try_default in case the value is null or
+undefined.pub struct SignedTransactionWithProof {
+ pub signed_tx: SignedTransaction,
+ pub proof: Proof,
+}Signed consensus transaction with a proof of its inclusion in a block.
+signed_tx: SignedTransactionSigned transaction.
+proof: ProofProof of transaction inclusion in a block.
+try_default in case the value is null or
+undefined.pub struct Transaction {
+ pub nonce: u64,
+ pub fee: Option<Fee>,
+ pub method: MethodName,
+ pub body: Value,
+}Unsigned consensus transaction.
+nonce: u64Nonce to prevent replay.
+fee: Option<Fee>Optional fee that the sender commits to pay to execute this transaction.
+method: MethodNameMethod that should be called.
+body: ValueMethod call body.
+try_default in case the value is null or
+undefined.pub type Gas = u64;Consensus gas representation.
+pub type MethodName = String;Method name.
+struct MethodName { /* private fields */ }pub type SignedTransaction = Signed;Signed consensus transaction.
+struct SignedTransaction {
+ pub blob: Vec<u8>,
+ pub signature: SignatureBundle,
+}blob: Vec<u8>Signed blob.
+signature: SignatureBundleSignature over the blob.
+pub enum Error {
+ Builder(Error),
+ VerificationFailed(Error),
+ TrustedStateLoadingFailed,
+ ChainContextTransitionFailed(Error),
+ FreshnessVerificationFailed(Error),
+ TransactionVerificationFailed(Error),
+ StateRoot(Error),
+ Internal,
+}pub fn verify_state_freshness(
+ state: &ConsensusState,
+ identity: &Identity,
+ runtime_id: &Namespace,
+ version: &Version,
+ host_node_id: &PublicKey,
+) -> Result<(), Error>Verify consensus layer state freshness based on our internal state.
+pub struct TrustRoot {
+ pub height: u64,
+ pub hash: String,
+ pub runtime_id: Namespace,
+ pub chain_context: String,
+}Consensus layer trust root.
+height: u64Known trusted height.
+hash: StringKnown hex-encoded trusted consensus layer header hash.
+runtime_id: NamespaceKnown runtime identifier.
+chain_context: StringKnown consensus chain context.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub trait Verifier: Send + Sync {
+ // Required methods
+ fn sync<'life0, 'async_trait>(
+ &'life0 self,
+ height: u64,
+ ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
+ where Self: 'async_trait,
+ 'life0: 'async_trait;
+ fn verify<'life0, 'async_trait>(
+ &'life0 self,
+ consensus_block: LightBlock,
+ runtime_header: Header,
+ epoch: EpochTime,
+ ) -> Pin<Box<dyn Future<Output = Result<ConsensusState, Error>> + Send + 'async_trait>>
+ where Self: 'async_trait,
+ 'life0: 'async_trait;
+ fn verify_for_query<'life0, 'async_trait>(
+ &'life0 self,
+ consensus_block: LightBlock,
+ runtime_header: Header,
+ epoch: EpochTime,
+ ) -> Pin<Box<dyn Future<Output = Result<ConsensusState, Error>> + Send + 'async_trait>>
+ where Self: 'async_trait,
+ 'life0: 'async_trait;
+ fn unverified_state<'life0, 'async_trait>(
+ &'life0 self,
+ consensus_block: LightBlock,
+ ) -> Pin<Box<dyn Future<Output = Result<ConsensusState, Error>> + Send + 'async_trait>>
+ where Self: 'async_trait,
+ 'life0: 'async_trait;
+ fn latest_state<'life0, 'async_trait>(
+ &'life0 self,
+ ) -> Pin<Box<dyn Future<Output = Result<ConsensusState, Error>> + Send + 'async_trait>>
+ where Self: 'async_trait,
+ 'life0: 'async_trait;
+ fn state_at<'life0, 'async_trait>(
+ &'life0 self,
+ height: u64,
+ ) -> Pin<Box<dyn Future<Output = Result<ConsensusState, Error>> + Send + 'async_trait>>
+ where Self: 'async_trait,
+ 'life0: 'async_trait;
+ fn events_at<'life0, 'async_trait>(
+ &'life0 self,
+ height: u64,
+ kind: EventKind,
+ ) -> Pin<Box<dyn Future<Output = Result<Vec<Event>, Error>> + Send + 'async_trait>>
+ where Self: 'async_trait,
+ 'life0: 'async_trait;
+ fn latest_height<'life0, 'async_trait>(
+ &'life0 self,
+ ) -> Pin<Box<dyn Future<Output = Result<u64, Error>> + Send + 'async_trait>>
+ where Self: 'async_trait,
+ 'life0: 'async_trait;
+}Verifier is the consensus layer state verifier trait.
+Synchronize the verifier state up to including the passed consensus height.
+Verify that the given runtime header is valid at the given consensus layer block and return +the consensus layer state accessor for that block.
+This also verifies that the state is fresh.
+Verify that the given runtime header is valid at the given consensus layer block and return +the consensus layer state accessor for that block.
+This is a relaxed version of the verify function that should be used for verifying state
+in queries.
Return the consensus layer state accessor for the given consensus layer block WITHOUT +performing any verification. This method should only be used for operations that do not +require integrity guarantees.
+Return the latest verified consensus layer state.
+The state is not verified to be fresh. Use verify_state_freshness to perform this
+verification manually if needed.
Return the verified consensus layer state for a given height.
+The state is not verified to be fresh. Use verify_state_freshness to perform this
+verification manually if needed.
Return the consensus layer events at the given height.
+Event integrity is currently not verified and it thus relies on replicated computation even +when using a TEE-enabled runtime.
+Runtime call dispatcher.
+pub struct Dispatcher { /* private fields */ }Runtime call dispatcher.
+pub struct PostInitState {
+ pub txn_dispatcher: Option<Box<dyn TxnDispatcher>>,
+ pub app: Option<Box<dyn App>>,
+}State returned by the initializer.
+txn_dispatcher: Option<Box<dyn TxnDispatcher>>Optional transaction dispatcher that should be used.
+app: Option<Box<dyn App>>Optional ROFL application.
+pub struct PreInitState<'a> {
+ pub protocol: &'a Arc<Protocol>,
+ pub identity: &'a Arc<Identity>,
+ pub rpc_demux: &'a mut Demux,
+ pub rpc_dispatcher: &'a mut Dispatcher,
+ pub consensus_verifier: &'a Arc<dyn Verifier>,
+}State available before initialization.
+protocol: &'a Arc<Protocol>Protocol instance.
+identity: &'a Arc<Identity>Runtime Attestation Key instance.
+rpc_demux: &'a mut DemuxRPC demultiplexer instance.
+rpc_dispatcher: &'a mut DispatcherRPC dispatcher instance.
+consensus_verifier: &'a Arc<dyn Verifier>Consensus verifier instance.
+pub trait Initializer: Send + Sync {
+ // Required method
+ fn init(self: Box<Self>, state: PreInitState<'_>) -> PostInitState;
+}Interface for dispatcher initializers.
+Initializes the dispatcher(s).
+pub enum RpcClientError {
+ CallFailed(String),
+ ExpectedResponseMessage(Message),
+ ExpectedCloseMessage(Message),
+ Transport,
+ UnsupportedRpcKind,
+ Dropped,
+ DecodeError(DecodeError),
+ SessionsError(Error),
+ Unknown(Error),
+}RPC client error.
+Enclave RPC client.
+pub struct Response<'a, T> { /* private fields */ }An EnclaveRPC response that can be used to provide peer feedback.
+Report success if result was Ok(_) and failure if result was Err(_), then return the
+inner result consuming the response instance.
Reference to inner result.
+Consume the response instance returning the inner result.
+pub struct RpcClient { /* private fields */ }RPC client.
+Construct an unconnected RPC client with runtime-internal transport.
+Update allowed remote enclave identities.
+Update remote end’s quote policy.
+Update remote runtime id.
+RPC call context.
+pub struct Context {
+ pub session_info: Option<Arc<SessionInfo>>,
+}RPC call context.
+session_info: Option<Arc<SessionInfo>>Information about the session the RPC call was delivered over.
+pub enum Error {
+ MalformedPayload(DecodeError),
+ MalformedRequestMethod,
+ SessionsError(Error),
+ Other(Error),
+}Demultiplexer error.
+Session demultiplexer.
+pub struct Demux { /* private fields */ }Session demultiplexer.
+Create new session demultiplexer.
+Set the session builder to use.
+Process a frame, returning the locked session guard and decoded message.
+Any data that needs to be transmitted back to the peer is written to the passed writer.
+RPC dispatcher.
+pub struct Dispatcher { /* private fields */ }RPC call dispatcher.
+Register a new method in the dispatcher.
+Register new methods in the dispatcher.
+Dispatch request.
+Handle key manager status update.
+Handle key manager quote policy update.
+Update key manager status update handler.
+Update key manager quote policy update handler.
+pub struct Method { /* private fields */ }RPC method dispatcher implementation.
+Create a new enclave method descriptor.
+pub struct MethodDescriptor {
+ pub name: String,
+ pub kind: Kind,
+}Descriptor of a RPC API method.
+name: StringMethod name.
+kind: KindSpecifies which kind of RPC is allowed to call the method.
+source. Read moreclone_to_uninit)pub trait Handler {
+ // Required method
+ fn methods(&'static self) -> Vec<Method>;
+}RPC handler.
+pub trait MethodHandlerDispatch {
+ // Required methods
+ fn get_descriptor(&self) -> &MethodDescriptor;
+ fn dispatch(&self, ctx: &Context, request: Request) -> Result<Response>;
+}Dispatcher for a RPC method.
+Get method descriptor.
+pub type KeyManagerQuotePolicyHandler = dyn Fn(QuotePolicy) + Send + Sync;Key manager quote policy update handler callback.
+pub type KeyManagerStatusHandler = dyn Fn(Status) + Send + Sync;Key manager status update handler callback.
+Secure inter-enclave RPC.
+pub use self::context::Context;pub enum RAKBinding {
+ V0 {
+ rak_pub: PublicKey,
+ binding: Signature,
+ avr: AVR,
+ },
+ V1 {
+ rak_pub: PublicKey,
+ binding: Signature,
+ quote: Quote,
+ },
+ V2 {
+ ect: EndorsedCapabilityTEE,
+ binding: Signature,
+ },
+}Binding of the session’s static public key to a remote attestation +verification report through the use of the remote attestation key.
+The signature chain is as follows:
+avr contains the remote attestation verification report which
+binds RAK to the remote attestation.rak_pub contains the public part of RAK.binding is signed by rak_pub and binds the session’s static
+public key to RAK.Old V0 format that only supported IAS quotes.
+New V1 format that supports both IAS and PCS quotes.
+V2 format which supports endorsed CapabilityTEE structures.
+Verify the RAK binding.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)Secure channel session.
+pub struct Builder { /* private fields */ }Session builder.
+Return remote enclave identities if configured in the builder.
+Enable remote enclave identity verification.
+Return remote runtime ID if configured in the builder.
+Set remote runtime ID for node identity verification.
+Enable remote node identity verification.
+Return quote policy if configured in the builder.
+Configure quote policy used for remote quote verification.
+Use endorsement from host node when establishing sessions.
+Return the local identity if configured in the builder.
+Enable RAK binding.
+Build initiator session.
+Build responder session.
+clone_to_uninit)pub struct Session { /* private fields */ }An encrypted and authenticated RPC session.
+Process incoming data.
+In case the session is in transport mode the returned result will
+contained a parsed message. The writer will be used in case any
+protocol replies need to be generated.
Write message to session.
+The writer will be used for protocol message output which should
+be transmitted to the remote session counterpart.
Mark the session as closed.
+After the session is closed it can no longer be used to transmit +or receive messages and any such use will result in an error.
+Session information.
+Whether the session handshake has completed and the session +is in transport mode.
+Whether the session is connected to one of the given nodes.
+Whether the session is in unauthenticated transport state. In this state the session can +only be used to transmit a close notification.
+Return remote node identifier.
+Set the remote node identifier.
+pub struct SessionInfo {
+ pub rak_binding: RAKBinding,
+ pub verified_attestation: VerifiedAttestation,
+ pub endorsed_by: Option<PublicKey>,
+}Information about a session.
+rak_binding: RAKBindingRAK binding.
+verified_attestation: VerifiedAttestationVerified TEE remote attestation.
+endorsed_by: Option<PublicKey>Identifier of the node that endorsed the TEE.
+pub enum Error {
+ MaxConcurrentSessions,
+}Sessions error.
+Session demultiplexer.
+pub struct MultiplexedSession<PeerID> { /* private fields */ }A multiplexed session.
+Return the session’s peer ID.
+Set the session’s peer ID.
+Return the session ID.
+Session information.
+Process incoming session data.
+Write message to session and generate a response.
+Return remote node identifier.
+Set the remote node identifier.
+Whether the session handshake has completed and the session +is in transport mode.
+Whether the session is in unauthenticated transport state. In this state the session can +only be used to transmit a close notification.
+pub struct SessionMeta<PeerID: Clone + Ord + Hash> { /* private fields */ }Structure used for session accounting.
+pub struct Sessions<PeerID: Clone + Ord + Hash> { /* private fields */ }Session indices and management operations.
+Create a new session management instance.
+Set the session builder to use.
+Update remote enclave identity verification in the session builder +and clear all sessions if the identity has changed.
+Update quote policy used for remote quote verification in the session builder +and clear all sessions if the policy has changed.
+Update remote runtime ID for node identity verification in the session builder +and clear all sessions if the runtime ID has changed.
+Create a new multiplexed responder session.
+Create a new multiplexed initiator session.
+Fetch an existing session given its identifier.
+Fetch an existing session from one of the given peers. If no peers +are provided, a session from any peer will be returned.
+Fetch an existing session from any peer.
+Fetch an existing session from one of the given peers.
+Remove one session to free up a slot for the given peer.
+Remove one existing session from the given peer if the peer has reached +the maximum number of sessions or if the total number of sessions exceeds +the global session limit.
+Remove one stale session if the total number of sessions exceeds +the global session limit.
+Add a session if there is an available spot.
+Remove a session that must be currently owned by the caller.
+Removes and returns all sessions.
+pub type SessionByTimeKey<PeerID> = (i64, PeerID, SessionID);Key for use in the by-idle-time index.
+pub type SharedSession<PeerID> = Arc<Mutex<MultiplexedSession<PeerID>>>;Shared pointer to a multiplexed session.
+struct SharedSession<PeerID> { /* private fields */ }pub enum Body {
+ Success(Value),
+ Error(String),
+}try_default in case the value is null or
+undefined.clone_to_uninit)#[repr(u8)]pub enum Kind {
+ NoiseSession = 0,
+ InsecureQuery = 1,
+ LocalQuery = 2,
+}RPC call kind.
+A secure RPC call using an encrypted and authenticated Noise session.
+An insecure RPC call where messages are sent in plain text.
+A local RPC call.
+try_default in case the value is null or
+undefined.clone_to_uninit)clone_to_uninit)key and return true if they are equal.pub enum Message {
+ Request(Request),
+ Response(Response),
+ Close,
+}Protocol message.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub enum PeerFeedback {
+ Success = 0,
+ Failure = 1,
+ BadPeer = 2,
+}Feedback on the peer that handled the last EnclaveRPC call.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)clone_to_uninit)key and return true if they are equal.RPC protocol types.
+pub struct Error {
+ pub message: String,
+}message: Stringtry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Frame {
+ pub session: SessionID,
+ pub untrusted_plaintext: String,
+ pub payload: Vec<u8>,
+}Frame.
+session: SessionID§untrusted_plaintext: String§payload: Vec<u8>try_default in case the value is null or
+undefined.clone_to_uninit)pub struct Request {
+ pub method: String,
+ pub args: Value,
+}method: String§args: Valuetry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Response {
+ pub body: Body,
+}body: Bodytry_default in case the value is null or
+undefined.clone_to_uninit)pub struct SessionID(pub [u8; 32]);Session identifier for multiplexing multiple sessions over the same transport
+0: [u8; 32]try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)clone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub enum TeeType {
+ None,
+ Sgx,
+ Tdx,
+}TEE type this build is for.
+key and return true if they are equal.pub fn new_tokio_runtime() -> RuntimeCreate a new asynchronous Tokio runtime.
+Helper functions to use with the asynchronous Tokio runtime.
+pub enum Error {
+ BadResponse,
+ Other(Error),
+}Errors.
+pub struct RegisterNotifyOpts {
+ pub runtime_block: bool,
+ pub runtime_event: Vec<Vec<u8>>,
+}Notification registration options.
+runtime_block: boolSubscribe to runtime block notifications.
+runtime_event: Vec<Vec<u8>>Subscribe to runtime event notifications.
+source. Read moreclone_to_uninit)pub struct SubmitTxOpts {
+ pub runtime_id: Option<Namespace>,
+ pub wait: bool,
+ pub prove: bool,
+}Transaction submission options.
+runtime_id: Option<Namespace>Target runtime identifier. If not specified, own runtime identifier is used.
+wait: boolWhether the call should wait until the transaction is included in a block.
+prove: boolWhether the response should include a proof of transaction being included in a block.
+source. Read moreclone_to_uninit)pub struct TxResult {
+ pub output: Vec<u8>,
+ pub round: u64,
+ pub batch_order: u32,
+ pub proof: Option<Proof>,
+}Transaction submission result.
+output: Vec<u8>Transaction output.
+round: u64Round in which the transaction was executed.
+batch_order: u32Order of the transaction in the execution batch.
+proof: Option<Proof>Optional inclusion proof.
+clone_to_uninit)pub trait Host: Send + Sync {
+ // Required methods
+ fn identity<'life0, 'async_trait>(
+ &'life0 self,
+ ) -> Pin<Box<dyn Future<Output = Result<PublicKey, Error>> + Send + 'async_trait>>
+ where Self: 'async_trait,
+ 'life0: 'async_trait;
+ fn submit_tx<'life0, 'async_trait>(
+ &'life0 self,
+ data: Vec<u8>,
+ opts: SubmitTxOpts,
+ ) -> Pin<Box<dyn Future<Output = Result<Option<TxResult>, Error>> + Send + 'async_trait>>
+ where Self: 'async_trait,
+ 'life0: 'async_trait;
+ fn register_notify<'life0, 'async_trait>(
+ &'life0 self,
+ opts: RegisterNotifyOpts,
+ ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait>>
+ where Self: 'async_trait,
+ 'life0: 'async_trait;
+}Interface to the (untrusted) host node.
+Returns the identity of the host node.
+Submit a transaction.
+Register for receiving notifications.
+Runtime attestation key handling.
+pub struct Identity { /* private fields */ }Runtime identity.
+The identity can be used to sign remote attestations with runtime +attestation key (RAK) or to decrypt ciphertexts sent to the enclave +with runtime encryption key (REK). RAK avoids round trips to IAS/PCS +for each verification as the verifier can instead verify the RAK signature +and the signature on the provided quote which binds RAK to the enclave. +REK allows enclaves to publish encrypted data on-chain to an enclave +instance.
+Endorsed TEE capability.
+Host node identity public key.
+Public part of RAK.
+This method will return an insecure test key in the case where +the enclave is not running on SGX hardware.
+Public part of REK.
+This method will return an insecure test key in the case where +the enclave is not running on SGX hardware.
+Quote for RAK.
+This method may return None in case quote has not yet been set from
+the outside, or if the quote has expired.
Runtime quote policy.
+This method may return None in the case where the enclave is not
+running on SGX hardware or if the quote policy has not yet been
+fetched from the consensus layer.
Verify a provided RAK binding.
+Checks whether the RAK matches another specified (RAK_pub, quote) pair.
+Oasis Core runtime SDK.
+To create a minimal runtime that doesn’t expose any APIs to the
+outside world, you need to call the start_runtime function:
oasis_core_runtime::start_runtime(Some(Box::new(reg)), config);This will start the required services needed to communicate with +the worker host.
+pub use self::enclave_rpc::demux::Demux as RpcDemux;pub use self::enclave_rpc::dispatcher::Dispatcher as RpcDispatcher;pub use self::init::start_runtime;pub use self::protocol::Protocol;pub use self::transaction::dispatcher::Dispatcher as TxnDispatcher;pub use cbor;pub fn start_runtime(initializer: Box<dyn Initializer>, config: Config)Starts the runtime.
+Runtime initialization.
+Redirecting to macro.classify_noderef.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/macro.classify_noderef.html b/rust/oasis_core_runtime/macro.classify_noderef.html new file mode 100644 index 0000000000..f6b6e92e35 --- /dev/null +++ b/rust/oasis_core_runtime/macro.classify_noderef.html @@ -0,0 +1,4 @@ +macro_rules! classify_noderef { + (? $e:expr) => { ... }; + ($e:expr) => { ... }; +}
Redirecting to macro.impl_bytes.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/macro.impl_bytes.html b/rust/oasis_core_runtime/macro.impl_bytes.html new file mode 100644 index 0000000000..415f1b487b --- /dev/null +++ b/rust/oasis_core_runtime/macro.impl_bytes.html @@ -0,0 +1,6 @@ +macro_rules! impl_bytes { + ($name:ident, $size:expr, $doc:expr) => { ... }; +}
Redirecting to macro.key_format.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/macro.key_format.html b/rust/oasis_core_runtime/macro.key_format.html new file mode 100644 index 0000000000..055ec492fa --- /dev/null +++ b/rust/oasis_core_runtime/macro.key_format.html @@ -0,0 +1,6 @@ +macro_rules! key_format { + ($name:ident, $prefix:expr, $inner:ty) => { ... }; +}
Redirecting to macro.noderef_as.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/macro.noderef_as.html b/rust/oasis_core_runtime/macro.noderef_as.html new file mode 100644 index 0000000000..2354f86f2d --- /dev/null +++ b/rust/oasis_core_runtime/macro.noderef_as.html @@ -0,0 +1,3 @@ +macro_rules! noderef_as { + ($ref:expr, $type:ident) => { ... }; +}
Redirecting to macro.noderef_as_mut.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/macro.noderef_as_mut.html b/rust/oasis_core_runtime/macro.noderef_as_mut.html new file mode 100644 index 0000000000..faf9eaa277 --- /dev/null +++ b/rust/oasis_core_runtime/macro.noderef_as_mut.html @@ -0,0 +1,3 @@ +macro_rules! noderef_as_mut { + ($ref:expr, $type:ident) => { ... }; +}
Redirecting to macro.version_from_cargo.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/macro.version_from_cargo.html b/rust/oasis_core_runtime/macro.version_from_cargo.html new file mode 100644 index 0000000000..5cab8e3a1d --- /dev/null +++ b/rust/oasis_core_runtime/macro.version_from_cargo.html @@ -0,0 +1,3 @@ +macro_rules! version_from_cargo {
+ () => { ... };
+}pub enum PolicyVerifierError {
+ MissingRuntimeDescriptor,
+ NoDeployment,
+ BadTEEConstraints,
+ PolicyMismatch,
+ PolicyNotPublished,
+ StatusMismatch,
+ StatusNotPublished,
+ HardwareMismatch,
+ NoKeyManager,
+}Policy verifier error.
+Consensus SGX and quote policy handling.
+pub struct PolicyVerifier { /* private fields */ }Consensus policy verifier.
+Create a new consensus policy verifier.
+Fetch runtime’s quote policy from the latest verified consensus layer state.
+If the runtime version is not provided, the policy for the active deployment is returned.
+Verify that runtime’s quote policy has been published in the consensus layer.
+Fetch key manager’s status from the latest verified consensus layer state.
+Verify that key manager’s status has been published in the consensus layer.
+Fetch key manager’s policy from the latest verified consensus layer state.
+Verify that key manager’s policy has been published in the consensus layer.
+Fetch runtime’s key manager.
+pub enum ProtocolError {
+ MessageTooLarge,
+ MethodNotSupported,
+ InvalidResponse,
+ AttestationRequired,
+ HostInfoNotConfigured,
+ IncompatibleConsensusBackend,
+ InvalidRuntimeId(Namespace, Namespace),
+ AlreadyInitialized,
+ ChannelClosed,
+}pub enum Stream {
+ Unix(UnixStream),
+ Tcp(TcpStream),
+}Stream used to communicate with the host.
+read, except that it reads into a slice of buffers. Read morecan_vector)buf. Read morebuf. Read morebuf. Read moreread_buf)read_buf)cursor. Read moreRead. Read morecan_vector)write_all_vectored)Runtime side of the worker-host protocol.
+pub struct HostInfo {
+ pub runtime_id: Namespace,
+ pub consensus_backend: String,
+ pub consensus_protocol_version: Version,
+ pub consensus_chain_context: String,
+ pub local_config: BTreeMap<String, Value>,
+}Information about the host environment.
+runtime_id: NamespaceAssigned runtime identifier of the loaded runtime.
+consensus_backend: StringName of the consensus backend that is in use for the consensus layer.
+consensus_protocol_version: VersionConsensus protocol version that is in use for the consensus layer.
+consensus_chain_context: StringConsensus layer chain domain separation context.
+local_config: BTreeMap<String, Value>Node-local runtime configuration.
+This configuration must not be used in any context which requires determinism across +replicated runtime instances.
+clone_to_uninit)pub struct Protocol { /* private fields */ }Runtime part of the runtime host protocol.
+The supplied runtime configuration.
+The runtime identity.
+The runtime identifier for this instance.
+Panics, if the host environment information is not set.
+The host environment information for this instance.
+Panics, if the host environment information is not set.
+Make a new request to the runtime host and wait for the response.
+This is a blocking variant of call_host_async.
This function panics if called within an asynchronous execution context.
+Make a new request to the runtime host and wait for the response.
+Send an async response to a previous request back to the host.
+Ensure that the runtime is ready to process requests and fail otherwise.
+pub struct ProtocolUntrustedLocalStorage { /* private fields */ }Untrusted key/value store which stores arbitrary binary key/value pairs +on the worker host.
+Care MUST be taken to not trust this interface at all. The worker host +is capable of doing whatever it wants including but not limited to, +hiding data, tampering with keys/values, ignoring writes, replaying +past values, etc.
+Runtime storage interfaces and implementations.
+pub use self::mkvs::MKVS;pub enum LogEntryKind {
+ Insert,
+ Delete,
+}The type of entry in the log.
+source. Read moreself and other values to be equal, and is used
+by ==.clone_to_uninit)clone_to_uninit)key and return true if they are equal.pub enum NodeBox {
+ Internal(InternalNode),
+ Leaf(LeafNode),
+}A box type that can contain either internal or leaf nodes.
+key and return true if they are equal.#[repr(u8)]pub enum RootType {
+ Invalid = 0,
+ State = 1,
+ IO = 2,
+}Storage root type.
+Invalid or uninitialized storage root type.
+Storage root for runtime state.
+Storage root for transaction IO.
+try_default in case the value is null or
+undefined.clone_to_uninit)clone_to_uninit)key and return true if they are equal.Merklized key-value store.
+pub trait Marshal {
+ // Required methods
+ fn marshal_binary(&self) -> Result<Vec<u8>>;
+ fn unmarshal_binary(&mut self, data: &[u8]) -> Result<usize>;
+}The Marshal trait is used for marshaling and unmarshaling MKVS trees.
Marshal the object into a binary form and return it as a new vector.
+Unmarshal from the given byte slice reference and modify self.
pub struct LogEntry {
+ pub key: Vec<u8>,
+ pub value: Option<Vec<u8>>,
+}An entry in the write log, describing a single update.
+key: Vec<u8>The key that was inserted or deleted.
+value: Option<Vec<u8>>The inserted value (empty if the key was deleted).
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct NodePointer {
+ pub clean: bool,
+ pub hash: Hash,
+ pub node: Option<Rc<RefCell<NodeBox>>>,
+ pub cache_extra: Option<NonNull<CacheItemBox<NodePointer>>>,
+}A pointer to a node in the tree.
+clean: bool§hash: Hash§node: Option<Rc<RefCell<NodeBox>>>§cache_extra: Option<NonNull<CacheItemBox<NodePointer>>>Construct a null pointer.
+Construct a hash-only pointer.
+Construct a node pointer from a full node.
+Check if the pointer has a resolved reference to a concrete node.
+Get a reference to the node the pointer is pointing to.
+Return a copy of this pointer containing only hash references.
+self and other values to be equal, and is used
+by ==.key and return true if they are equal.pub struct OverlayTree<T: FallibleMKVS> { /* private fields */ }A key-value tree overlay that holds all updates in memory and only commits them if requested. +This can be used to create snapshots that can be discarded.
+While updates (inserts, removes) are stored in the overlay, reads are not cached in the overlay +as the inner tree has its own cache and double caching makes less sense.
+Insert a key/value pair into the tree.
+Remove entry with given key, returning the value at the key if the key was previously +in the database.
+pub struct Prefix(/* private fields */);A key prefix.
+Returns the total number of elements the vector can hold without +reallocating.
+let mut vec: Vec<i32> = Vec::with_capacity(10);
+vec.push(42);
+assert!(vec.capacity() >= 10);Reserves capacity for at least additional more elements to be inserted
+in the given Vec<T>. The collection may reserve more space to
+speculatively avoid frequent reallocations. After calling reserve,
+capacity will be greater than or equal to self.len() + additional.
+Does nothing if capacity is already sufficient.
Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1];
+vec.reserve(10);
+assert!(vec.capacity() >= 11);Reserves the minimum capacity for at least additional more elements to
+be inserted in the given Vec<T>. Unlike reserve, this will not
+deliberately over-allocate to speculatively avoid frequent allocations.
+After calling reserve_exact, capacity will be greater than or equal to
+self.len() + additional. Does nothing if the capacity is already
+sufficient.
Note that the allocator may give the collection more space than it
+requests. Therefore, capacity can not be relied upon to be precisely
+minimal. Prefer reserve if future insertions are expected.
Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1];
+vec.reserve_exact(10);
+assert!(vec.capacity() >= 11);Tries to reserve capacity for at least additional more elements to be inserted
+in the given Vec<T>. The collection may reserve more space to speculatively avoid
+frequent reallocations. After calling try_reserve, capacity will be
+greater than or equal to self.len() + additional if it returns
+Ok(()). Does nothing if capacity is already sufficient. This method
+preserves the contents even if an error occurs.
If the capacity overflows, or the allocator reports a failure, then an error +is returned.
+use std::collections::TryReserveError;
+
+fn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {
+ let mut output = Vec::new();
+
+ // Pre-reserve the memory, exiting if we can't
+ output.try_reserve(data.len())?;
+
+ // Now we know this can't OOM in the middle of our complex work
+ output.extend(data.iter().map(|&val| {
+ val * 2 + 5 // very complicated
+ }));
+
+ Ok(output)
+}Tries to reserve the minimum capacity for at least additional
+elements to be inserted in the given Vec<T>. Unlike try_reserve,
+this will not deliberately over-allocate to speculatively avoid frequent
+allocations. After calling try_reserve_exact, capacity will be greater
+than or equal to self.len() + additional if it returns Ok(()).
+Does nothing if the capacity is already sufficient.
Note that the allocator may give the collection more space than it
+requests. Therefore, capacity can not be relied upon to be precisely
+minimal. Prefer try_reserve if future insertions are expected.
If the capacity overflows, or the allocator reports a failure, then an error +is returned.
+use std::collections::TryReserveError;
+
+fn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {
+ let mut output = Vec::new();
+
+ // Pre-reserve the memory, exiting if we can't
+ output.try_reserve_exact(data.len())?;
+
+ // Now we know this can't OOM in the middle of our complex work
+ output.extend(data.iter().map(|&val| {
+ val * 2 + 5 // very complicated
+ }));
+
+ Ok(output)
+}Shrinks the capacity of the vector as much as possible.
+The behavior of this method depends on the allocator, which may either shrink the vector
+in-place or reallocate. The resulting vector might still have some excess capacity, just as
+is the case for with_capacity. See Allocator::shrink for more details.
let mut vec = Vec::with_capacity(10);
+vec.extend([1, 2, 3]);
+assert!(vec.capacity() >= 10);
+vec.shrink_to_fit();
+assert!(vec.capacity() >= 3);Shrinks the capacity of the vector with a lower bound.
+The capacity will remain at least as large as both the length +and the supplied value.
+If the current capacity is less than the lower limit, this is a no-op.
+let mut vec = Vec::with_capacity(10);
+vec.extend([1, 2, 3]);
+assert!(vec.capacity() >= 10);
+vec.shrink_to(4);
+assert!(vec.capacity() >= 4);
+vec.shrink_to(0);
+assert!(vec.capacity() >= 3);Shortens the vector, keeping the first len elements and dropping
+the rest.
If len is greater or equal to the vector’s current length, this has
+no effect.
The drain method can emulate truncate, but causes the excess
+elements to be returned instead of dropped.
Note that this method has no effect on the allocated capacity +of the vector.
+Truncating a five element vector to two elements:
+ +let mut vec = vec![1, 2, 3, 4, 5];
+vec.truncate(2);
+assert_eq!(vec, [1, 2]);No truncation occurs when len is greater than the vector’s current
+length:
let mut vec = vec![1, 2, 3];
+vec.truncate(8);
+assert_eq!(vec, [1, 2, 3]);Truncating when len == 0 is equivalent to calling the clear
+method.
let mut vec = vec![1, 2, 3];
+vec.truncate(0);
+assert_eq!(vec, []);Extracts a slice containing the entire vector.
+Equivalent to &s[..].
use std::io::{self, Write};
+let buffer = vec![1, 2, 3, 5, 8];
+io::sink().write(buffer.as_slice()).unwrap();Extracts a mutable slice of the entire vector.
+Equivalent to &mut s[..].
use std::io::{self, Read};
+let mut buffer = vec![0; 3];
+io::repeat(0b101).read_exact(buffer.as_mut_slice()).unwrap();Returns a raw pointer to the vector’s buffer, or a dangling raw pointer +valid for zero sized reads if the vector didn’t allocate.
+The caller must ensure that the vector outlives the pointer this +function returns, or else it will end up pointing to garbage. +Modifying the vector may cause its buffer to be reallocated, +which would also make any pointers to it invalid.
+The caller must also ensure that the memory the pointer (non-transitively) points to
+is never written to (except inside an UnsafeCell) using this pointer or any pointer
+derived from it. If you need to mutate the contents of the slice, use as_mut_ptr.
This method guarantees that for the purpose of the aliasing model, this method
+does not materialize a reference to the underlying slice, and thus the returned pointer
+will remain valid when mixed with other calls to as_ptr and as_mut_ptr.
+Note that calling other methods that materialize mutable references to the slice,
+or mutable references to specific elements you are planning on accessing through this pointer,
+as well as writing to those elements, may still invalidate this pointer.
+See the second example below for how this guarantee can be used.
let x = vec![1, 2, 4];
+let x_ptr = x.as_ptr();
+
+unsafe {
+ for i in 0..x.len() {
+ assert_eq!(*x_ptr.add(i), 1 << i);
+ }
+}Due to the aliasing guarantee, the following code is legal:
+ +unsafe {
+ let mut v = vec![0, 1, 2];
+ let ptr1 = v.as_ptr();
+ let _ = ptr1.read();
+ let ptr2 = v.as_mut_ptr().offset(2);
+ ptr2.write(2);
+ // Notably, the write to `ptr2` did *not* invalidate `ptr1`
+ // because it mutated a different element:
+ let _ = ptr1.read();
+}Returns an unsafe mutable pointer to the vector’s buffer, or a dangling +raw pointer valid for zero sized reads if the vector didn’t allocate.
+The caller must ensure that the vector outlives the pointer this +function returns, or else it will end up pointing to garbage. +Modifying the vector may cause its buffer to be reallocated, +which would also make any pointers to it invalid.
+This method guarantees that for the purpose of the aliasing model, this method
+does not materialize a reference to the underlying slice, and thus the returned pointer
+will remain valid when mixed with other calls to as_ptr and as_mut_ptr.
+Note that calling other methods that materialize references to the slice,
+or references to specific elements you are planning on accessing through this pointer,
+may still invalidate this pointer.
+See the second example below for how this guarantee can be used.
// Allocate vector big enough for 4 elements.
+let size = 4;
+let mut x: Vec<i32> = Vec::with_capacity(size);
+let x_ptr = x.as_mut_ptr();
+
+// Initialize elements via raw pointer writes, then set length.
+unsafe {
+ for i in 0..size {
+ *x_ptr.add(i) = i as i32;
+ }
+ x.set_len(size);
+}
+assert_eq!(&*x, &[0, 1, 2, 3]);Due to the aliasing guarantee, the following code is legal:
+ +unsafe {
+ let mut v = vec![0];
+ let ptr1 = v.as_mut_ptr();
+ ptr1.write(1);
+ let ptr2 = v.as_mut_ptr();
+ ptr2.write(2);
+ // Notably, the write to `ptr2` did *not* invalidate `ptr1`:
+ ptr1.write(3);
+}allocator_api)Returns a reference to the underlying allocator.
+Forces the length of the vector to new_len.
This is a low-level operation that maintains none of the normal
+invariants of the type. Normally changing the length of a vector
+is done using one of the safe operations instead, such as
+truncate, resize, extend, or clear.
new_len must be less than or equal to capacity().old_len..new_len must be initialized.This method can be useful for situations in which the vector +is serving as a buffer for other code, particularly over FFI:
+ +pub fn get_dictionary(&self) -> Option<Vec<u8>> {
+ // Per the FFI method's docs, "32768 bytes is always enough".
+ let mut dict = Vec::with_capacity(32_768);
+ let mut dict_length = 0;
+ // SAFETY: When `deflateGetDictionary` returns `Z_OK`, it holds that:
+ // 1. `dict_length` elements were initialized.
+ // 2. `dict_length` <= the capacity (32_768)
+ // which makes `set_len` safe to call.
+ unsafe {
+ // Make the FFI call...
+ let r = deflateGetDictionary(self.strm, dict.as_mut_ptr(), &mut dict_length);
+ if r == Z_OK {
+ // ...and update the length to what was initialized.
+ dict.set_len(dict_length);
+ Some(dict)
+ } else {
+ None
+ }
+ }
+}While the following example is sound, there is a memory leak since
+the inner vectors were not freed prior to the set_len call:
let mut vec = vec![vec![1, 0, 0],
+ vec![0, 1, 0],
+ vec![0, 0, 1]];
+// SAFETY:
+// 1. `old_len..0` is empty so no elements need to be initialized.
+// 2. `0 <= capacity` always holds whatever `capacity` is.
+unsafe {
+ vec.set_len(0);
+}Normally, here, one would use clear instead to correctly drop
+the contents and thus not leak memory.
Removes an element from the vector and returns it.
+The removed element is replaced by the last element of the vector.
+This does not preserve ordering of the remaining elements, but is O(1).
+If you need to preserve the element order, use remove instead.
Panics if index is out of bounds.
let mut v = vec!["foo", "bar", "baz", "qux"];
+
+assert_eq!(v.swap_remove(1), "bar");
+assert_eq!(v, ["foo", "qux", "baz"]);
+
+assert_eq!(v.swap_remove(0), "foo");
+assert_eq!(v, ["baz", "qux"]);Inserts an element at position index within the vector, shifting all
+elements after it to the right.
Panics if index > len.
let mut vec = vec![1, 2, 3];
+vec.insert(1, 4);
+assert_eq!(vec, [1, 4, 2, 3]);
+vec.insert(4, 5);
+assert_eq!(vec, [1, 4, 2, 3, 5]);Takes O(Vec::len) time. All items after the insertion index must be
+shifted to the right. In the worst case, all elements are shifted when
+the insertion index is 0.
Removes and returns the element at position index within the vector,
+shifting all elements after it to the left.
Note: Because this shifts over the remaining elements, it has a
+worst-case performance of O(n). If you don’t need the order of elements
+to be preserved, use swap_remove instead. If you’d like to remove
+elements from the beginning of the Vec, consider using
+VecDeque::pop_front instead.
Panics if index is out of bounds.
let mut v = vec![1, 2, 3];
+assert_eq!(v.remove(1), 2);
+assert_eq!(v, [1, 3]);Retains only the elements specified by the predicate.
+In other words, remove all elements e for which f(&e) returns false.
+This method operates in place, visiting each element exactly once in the
+original order, and preserves the order of the retained elements.
let mut vec = vec![1, 2, 3, 4];
+vec.retain(|&x| x % 2 == 0);
+assert_eq!(vec, [2, 4]);Because the elements are visited exactly once in the original order, +external state may be used to decide which elements to keep.
+ +let mut vec = vec![1, 2, 3, 4, 5];
+let keep = [false, true, true, false, true];
+let mut iter = keep.iter();
+vec.retain(|_| *iter.next().unwrap());
+assert_eq!(vec, [2, 3, 5]);Retains only the elements specified by the predicate, passing a mutable reference to it.
+In other words, remove all elements e such that f(&mut e) returns false.
+This method operates in place, visiting each element exactly once in the
+original order, and preserves the order of the retained elements.
let mut vec = vec![1, 2, 3, 4];
+vec.retain_mut(|x| if *x <= 3 {
+ *x += 1;
+ true
+} else {
+ false
+});
+assert_eq!(vec, [2, 3, 4]);Removes all but the first of consecutive elements in the vector that resolve to the same +key.
+If the vector is sorted, this removes all duplicates.
+let mut vec = vec![10, 20, 21, 30, 20];
+
+vec.dedup_by_key(|i| *i / 10);
+
+assert_eq!(vec, [10, 20, 30, 20]);Removes all but the first of consecutive elements in the vector satisfying a given equality +relation.
+The same_bucket function is passed references to two elements from the vector and
+must determine if the elements compare equal. The elements are passed in opposite order
+from their order in the slice, so if same_bucket(a, b) returns true, a is removed.
If the vector is sorted, this removes all duplicates.
+let mut vec = vec!["foo", "bar", "Bar", "baz", "bar"];
+
+vec.dedup_by(|a, b| a.eq_ignore_ascii_case(b));
+
+assert_eq!(vec, ["foo", "bar", "baz", "bar"]);Appends an element to the back of a collection.
+Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1, 2];
+vec.push(3);
+assert_eq!(vec, [1, 2, 3]);Takes amortized O(1) time. If the vector’s length would exceed its +capacity after the push, O(capacity) time is taken to copy the +vector’s elements to a larger allocation. This expensive operation is +offset by the capacity O(1) insertions it allows.
+vec_push_within_capacity)Appends an element if there is sufficient spare capacity, otherwise an error is returned +with the element.
+Unlike push this method will not reallocate when there’s insufficient capacity.
+The caller should use reserve or try_reserve to ensure that there is enough capacity.
A manual, panic-free alternative to FromIterator:
#![feature(vec_push_within_capacity)]
+
+use std::collections::TryReserveError;
+fn from_iter_fallible<T>(iter: impl Iterator<Item=T>) -> Result<Vec<T>, TryReserveError> {
+ let mut vec = Vec::new();
+ for value in iter {
+ if let Err(value) = vec.push_within_capacity(value) {
+ vec.try_reserve(1)?;
+ // this cannot fail, the previous line either returned or added at least 1 free slot
+ let _ = vec.push_within_capacity(value);
+ }
+ }
+ Ok(vec)
+}
+assert_eq!(from_iter_fallible(0..100), Ok(Vec::from_iter(0..100)));Takes O(1) time.
+Removes the last element from a vector and returns it, or None if it
+is empty.
If you’d like to pop the first element, consider using
+VecDeque::pop_front instead.
let mut vec = vec![1, 2, 3];
+assert_eq!(vec.pop(), Some(3));
+assert_eq!(vec, [1, 2]);Takes O(1) time.
+vec_pop_if)Removes and returns the last element in a vector if the predicate
+returns true, or None if the predicate returns false or the vector
+is empty.
#![feature(vec_pop_if)]
+
+let mut vec = vec![1, 2, 3, 4];
+let pred = |x: &mut i32| *x % 2 == 0;
+
+assert_eq!(vec.pop_if(pred), Some(4));
+assert_eq!(vec, [1, 2, 3]);
+assert_eq!(vec.pop_if(pred), None);Removes the specified range from the vector in bulk, returning all +removed elements as an iterator. If the iterator is dropped before +being fully consumed, it drops the remaining removed elements.
+The returned iterator keeps a mutable borrow on the vector to optimize +its implementation.
+Panics if the starting point is greater than the end point or if +the end point is greater than the length of the vector.
+If the returned iterator goes out of scope without being dropped (due to
+mem::forget, for example), the vector may have lost and leaked
+elements arbitrarily, including elements outside the range.
let mut v = vec![1, 2, 3];
+let u: Vec<_> = v.drain(1..).collect();
+assert_eq!(v, &[1]);
+assert_eq!(u, &[2, 3]);
+
+// A full range clears the vector, like `clear()` does
+v.drain(..);
+assert_eq!(v, &[]);Clears the vector, removing all values.
+Note that this method has no effect on the allocated capacity +of the vector.
+let mut v = vec![1, 2, 3];
+
+v.clear();
+
+assert!(v.is_empty());Returns the number of elements in the vector, also referred to +as its ‘length’.
+let a = vec![1, 2, 3];
+assert_eq!(a.len(), 3);Returns true if the vector contains no elements.
let mut v = Vec::new();
+assert!(v.is_empty());
+
+v.push(1);
+assert!(!v.is_empty());Splits the collection into two at the given index.
+Returns a newly allocated vector containing the elements in the range
+[at, len). After the call, the original vector will be left containing
+the elements [0, at) with its previous capacity unchanged.
mem::take or mem::replace.Vec::truncate.Vec::drain.Panics if at > len.
let mut vec = vec![1, 2, 3];
+let vec2 = vec.split_off(1);
+assert_eq!(vec, [1]);
+assert_eq!(vec2, [2, 3]);Resizes the Vec in-place so that len is equal to new_len.
If new_len is greater than len, the Vec is extended by the
+difference, with each additional slot filled with the result of
+calling the closure f. The return values from f will end up
+in the Vec in the order they have been generated.
If new_len is less than len, the Vec is simply truncated.
This method uses a closure to create new values on every push. If
+you’d rather Clone a given value, use Vec::resize. If you
+want to use the Default trait to generate values, you can
+pass Default::default as the second argument.
let mut vec = vec![1, 2, 3];
+vec.resize_with(5, Default::default);
+assert_eq!(vec, [1, 2, 3, 0, 0]);
+
+let mut vec = vec![];
+let mut p = 1;
+vec.resize_with(4, || { p *= 2; p });
+assert_eq!(vec, [2, 4, 8, 16]);Returns the remaining spare capacity of the vector as a slice of
+MaybeUninit<T>.
The returned slice can be used to fill the vector with data (e.g. by
+reading from a file) before marking the data as initialized using the
+set_len method.
// Allocate vector big enough for 10 elements.
+let mut v = Vec::with_capacity(10);
+
+// Fill in the first 3 elements.
+let uninit = v.spare_capacity_mut();
+uninit[0].write(0);
+uninit[1].write(1);
+uninit[2].write(2);
+
+// Mark the first 3 elements of the vector as being initialized.
+unsafe {
+ v.set_len(3);
+}
+
+assert_eq!(&v, &[0, 1, 2]);vec_split_at_spare)Returns vector content as a slice of T, along with the remaining spare
+capacity of the vector as a slice of MaybeUninit<T>.
The returned spare capacity slice can be used to fill the vector with data
+(e.g. by reading from a file) before marking the data as initialized using
+the set_len method.
Note that this is a low-level API, which should be used with care for
+optimization purposes. If you need to append data to a Vec
+you can use push, extend, extend_from_slice,
+extend_from_within, insert, append, resize or
+resize_with, depending on your exact needs.
#![feature(vec_split_at_spare)]
+
+let mut v = vec![1, 1, 2];
+
+// Reserve additional space big enough for 10 elements.
+v.reserve(10);
+
+let (init, uninit) = v.split_at_spare_mut();
+let sum = init.iter().copied().sum::<u32>();
+
+// Fill in the next 4 elements.
+uninit[0].write(sum);
+uninit[1].write(sum * 2);
+uninit[2].write(sum * 3);
+uninit[3].write(sum * 4);
+
+// Mark the 4 elements of the vector as being initialized.
+unsafe {
+ let len = v.len();
+ v.set_len(len + 4);
+}
+
+assert_eq!(&v, &[1, 1, 2, 4, 8, 12, 16]);Resizes the Vec in-place so that len is equal to new_len.
If new_len is greater than len, the Vec is extended by the
+difference, with each additional slot filled with value.
+If new_len is less than len, the Vec is simply truncated.
This method requires T to implement Clone,
+in order to be able to clone the passed value.
+If you need more flexibility (or want to rely on Default instead of
+Clone), use Vec::resize_with.
+If you only need to resize to a smaller size, use Vec::truncate.
let mut vec = vec!["hello"];
+vec.resize(3, "world");
+assert_eq!(vec, ["hello", "world", "world"]);
+
+let mut vec = vec![1, 2, 3, 4];
+vec.resize(2, 0);
+assert_eq!(vec, [1, 2]);Clones and appends all elements in a slice to the Vec.
Iterates over the slice other, clones each element, and then appends
+it to this Vec. The other slice is traversed in-order.
Note that this function is same as extend except that it is
+specialized to work with slices instead. If and when Rust gets
+specialization this function will likely be deprecated (but still
+available).
let mut vec = vec![1];
+vec.extend_from_slice(&[2, 3, 4]);
+assert_eq!(vec, [1, 2, 3, 4]);Copies elements from src range to the end of the vector.
Panics if the starting point is greater than the end point or if +the end point is greater than the length of the vector.
+let mut vec = vec![0, 1, 2, 3, 4];
+
+vec.extend_from_within(2..);
+assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4]);
+
+vec.extend_from_within(..2);
+assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1]);
+
+vec.extend_from_within(4..8);
+assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);Creates a splicing iterator that replaces the specified range in the vector
+with the given replace_with iterator and yields the removed items.
+replace_with does not need to be the same length as range.
range is removed even if the iterator is not consumed until the end.
It is unspecified how many elements are removed from the vector
+if the Splice value is leaked.
The input iterator replace_with is only consumed when the Splice value is dropped.
This is optimal if:
+range) is empty,replace_with yields fewer or equal elements than range’s lengthsize_hint() is exact.Otherwise, a temporary vector is allocated and the tail is moved twice.
+Panics if the starting point is greater than the end point or if +the end point is greater than the length of the vector.
+let mut v = vec![1, 2, 3, 4];
+let new = [7, 8, 9];
+let u: Vec<_> = v.splice(1..3, new).collect();
+assert_eq!(v, &[1, 7, 8, 9, 4]);
+assert_eq!(u, &[2, 3]);extract_if)Creates an iterator which uses a closure to determine if an element should be removed.
+If the closure returns true, then the element is removed and yielded. +If the closure returns false, the element will remain in the vector and will not be yielded +by the iterator.
+If the returned ExtractIf is not exhausted, e.g. because it is dropped without iterating
+or the iteration short-circuits, then the remaining elements will be retained.
+Use retain with a negated predicate if you do not need the returned iterator.
Using this method is equivalent to the following code:
+ +let mut i = 0;
+while i < vec.len() {
+ if some_predicate(&mut vec[i]) {
+ let val = vec.remove(i);
+ // your code here
+ } else {
+ i += 1;
+ }
+}
+But extract_if is easier to use. extract_if is also more efficient,
+because it can backshift the elements of the array in bulk.
Note that extract_if also lets you mutate every element in the filter closure,
+regardless of whether you choose to keep or remove it.
Splitting an array into evens and odds, reusing the original allocation:
+ +#![feature(extract_if)]
+let mut numbers = vec![1, 2, 3, 4, 5, 6, 8, 9, 11, 13, 14, 15];
+
+let evens = numbers.extract_if(|x| *x % 2 == 0).collect::<Vec<_>>();
+let odds = numbers;
+
+assert_eq!(evens, vec![2, 4, 6, 8, 14]);
+assert_eq!(odds, vec![1, 3, 5, 9, 11, 13, 15]);ascii_char)Views this slice of ASCII characters as a UTF-8 str.
ascii_char)Views this slice of ASCII characters as a slice of u8 bytes.
sort_floats)Sorts the slice of floats.
+This sort is in-place (i.e. does not allocate), O(n * log(n)) worst-case, and uses
+the ordering defined by f32::total_cmp.
This uses the same sorting algorithm as sort_unstable_by.
#![feature(sort_floats)]
+let mut v = [2.6, -5e-8, f32::NAN, 8.29, f32::INFINITY, -1.0, 0.0, -f32::INFINITY, -0.0];
+
+v.sort_floats();
+let sorted = [-f32::INFINITY, -1.0, -5e-8, -0.0, 0.0, 2.6, 8.29, f32::INFINITY, f32::NAN];
+assert_eq!(&v[..8], &sorted[..8]);
+assert!(v[8].is_nan());Checks if all bytes in this slice are within the ASCII range.
+ascii_char)If this slice is_ascii, returns it as a slice of
+ASCII characters, otherwise returns None.
ascii_char)Converts this slice of bytes into a slice of ASCII characters, +without checking whether they’re valid.
+Every byte in the slice must be in 0..=127, or else this is UB.
Checks that two slices are an ASCII case-insensitive match.
+Same as to_ascii_lowercase(a) == to_ascii_lowercase(b),
+but without allocating and copying temporaries.
Converts this slice to its ASCII upper case equivalent in-place.
+ASCII letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’, +but non-ASCII letters are unchanged.
+To return a new uppercased value without modifying the existing one, use
+to_ascii_uppercase.
Converts this slice to its ASCII lower case equivalent in-place.
+ASCII letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’, +but non-ASCII letters are unchanged.
+To return a new lowercased value without modifying the existing one, use
+to_ascii_lowercase.
Returns an iterator that produces an escaped version of this slice, +treating it as an ASCII string.
+
+let s = b"0\t\r\n'\"\\\x9d";
+let escaped = s.escape_ascii().to_string();
+assert_eq!(escaped, "0\\t\\r\\n\\'\\\"\\\\\\x9d");Returns a byte slice with leading ASCII whitespace bytes removed.
+‘Whitespace’ refers to the definition used by
+u8::is_ascii_whitespace.
assert_eq!(b" \t hello world\n".trim_ascii_start(), b"hello world\n");
+assert_eq!(b" ".trim_ascii_start(), b"");
+assert_eq!(b"".trim_ascii_start(), b"");Returns a byte slice with trailing ASCII whitespace bytes removed.
+‘Whitespace’ refers to the definition used by
+u8::is_ascii_whitespace.
assert_eq!(b"\r hello world\n ".trim_ascii_end(), b"\r hello world");
+assert_eq!(b" ".trim_ascii_end(), b"");
+assert_eq!(b"".trim_ascii_end(), b"");Returns a byte slice with leading and trailing ASCII whitespace bytes +removed.
+‘Whitespace’ refers to the definition used by
+u8::is_ascii_whitespace.
assert_eq!(b"\r hello world\n ".trim_ascii(), b"hello world");
+assert_eq!(b" ".trim_ascii(), b"");
+assert_eq!(b"".trim_ascii(), b"");Creates an iterator over the contiguous valid UTF-8 ranges of this +slice, and the non-UTF-8 fragments in between.
+This function formats arbitrary but mostly-UTF-8 bytes into Rust source
+code in the form of a C-string literal (c"...").
use std::fmt::Write as _;
+
+pub fn cstr_literal(bytes: &[u8]) -> String {
+ let mut repr = String::new();
+ repr.push_str("c\"");
+ for chunk in bytes.utf8_chunks() {
+ for ch in chunk.valid().chars() {
+ // Escapes \0, \t, \r, \n, \\, \', \", and uses \u{...} for non-printable characters.
+ write!(repr, "{}", ch.escape_debug()).unwrap();
+ }
+ for byte in chunk.invalid() {
+ write!(repr, "\\x{:02X}", byte).unwrap();
+ }
+ }
+ repr.push('"');
+ repr
+}
+
+fn main() {
+ let lit = cstr_literal(b"\xferris the \xf0\x9f\xa6\x80\x07");
+ let expected = stringify!(c"\xFErris the 🦀\u{7}");
+ assert_eq!(lit, expected);
+}Takes a &[[T; N]], and flattens it to a &[T].
This panics if the length of the resulting slice would overflow a usize.
This is only possible when flattening a slice of arrays of zero-sized
+types, and thus tends to be irrelevant in practice. If
+size_of::<T>() > 0, this will never panic.
assert_eq!([[1, 2, 3], [4, 5, 6]].as_flattened(), &[1, 2, 3, 4, 5, 6]);
+
+assert_eq!(
+ [[1, 2, 3], [4, 5, 6]].as_flattened(),
+ [[1, 2], [3, 4], [5, 6]].as_flattened(),
+);
+
+let slice_of_empty_arrays: &[[i32; 0]] = &[[], [], [], [], []];
+assert!(slice_of_empty_arrays.as_flattened().is_empty());
+
+let empty_slice_of_arrays: &[[u32; 10]] = &[];
+assert!(empty_slice_of_arrays.as_flattened().is_empty());Takes a &mut [[T; N]], and flattens it to a &mut [T].
This panics if the length of the resulting slice would overflow a usize.
This is only possible when flattening a slice of arrays of zero-sized
+types, and thus tends to be irrelevant in practice. If
+size_of::<T>() > 0, this will never panic.
fn add_5_to_all(slice: &mut [i32]) {
+ for i in slice {
+ *i += 5;
+ }
+}
+
+let mut array = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
+add_5_to_all(array.as_flattened_mut());
+assert_eq!(array, [[6, 7, 8], [9, 10, 11], [12, 13, 14]]);sort_floats)Sorts the slice of floats.
+This sort is in-place (i.e. does not allocate), O(n * log(n)) worst-case, and uses
+the ordering defined by f64::total_cmp.
This uses the same sorting algorithm as sort_unstable_by.
#![feature(sort_floats)]
+let mut v = [2.6, -5e-8, f64::NAN, 8.29, f64::INFINITY, -1.0, 0.0, -f64::INFINITY, -0.0];
+
+v.sort_floats();
+let sorted = [-f64::INFINITY, -1.0, -5e-8, -0.0, 0.0, 2.6, 8.29, f64::INFINITY, f64::NAN];
+assert_eq!(&v[..8], &sorted[..8]);
+assert!(v[8].is_nan());Returns the number of elements in the slice.
+let a = [1, 2, 3];
+assert_eq!(a.len(), 3);Returns true if the slice has a length of 0.
let a = [1, 2, 3];
+assert!(!a.is_empty());
+
+let b: &[i32] = &[];
+assert!(b.is_empty());Returns the first element of the slice, or None if it is empty.
let v = [10, 40, 30];
+assert_eq!(Some(&10), v.first());
+
+let w: &[i32] = &[];
+assert_eq!(None, w.first());Returns a mutable pointer to the first element of the slice, or None if it is empty.
let x = &mut [0, 1, 2];
+
+if let Some(first) = x.first_mut() {
+ *first = 5;
+}
+assert_eq!(x, &[5, 1, 2]);
+
+let y: &mut [i32] = &mut [];
+assert_eq!(None, y.first_mut());Returns the first and all the rest of the elements of the slice, or None if it is empty.
let x = &[0, 1, 2];
+
+if let Some((first, elements)) = x.split_first() {
+ assert_eq!(first, &0);
+ assert_eq!(elements, &[1, 2]);
+}Returns the first and all the rest of the elements of the slice, or None if it is empty.
let x = &mut [0, 1, 2];
+
+if let Some((first, elements)) = x.split_first_mut() {
+ *first = 3;
+ elements[0] = 4;
+ elements[1] = 5;
+}
+assert_eq!(x, &[3, 4, 5]);Returns the last and all the rest of the elements of the slice, or None if it is empty.
let x = &[0, 1, 2];
+
+if let Some((last, elements)) = x.split_last() {
+ assert_eq!(last, &2);
+ assert_eq!(elements, &[0, 1]);
+}Returns the last and all the rest of the elements of the slice, or None if it is empty.
let x = &mut [0, 1, 2];
+
+if let Some((last, elements)) = x.split_last_mut() {
+ *last = 3;
+ elements[0] = 4;
+ elements[1] = 5;
+}
+assert_eq!(x, &[4, 5, 3]);Returns the last element of the slice, or None if it is empty.
let v = [10, 40, 30];
+assert_eq!(Some(&30), v.last());
+
+let w: &[i32] = &[];
+assert_eq!(None, w.last());Returns a mutable reference to the last item in the slice, or None if it is empty.
let x = &mut [0, 1, 2];
+
+if let Some(last) = x.last_mut() {
+ *last = 10;
+}
+assert_eq!(x, &[0, 1, 10]);
+
+let y: &mut [i32] = &mut [];
+assert_eq!(None, y.last_mut());Return an array reference to the first N items in the slice.
If the slice is not at least N in length, this will return None.
let u = [10, 40, 30];
+assert_eq!(Some(&[10, 40]), u.first_chunk::<2>());
+
+let v: &[i32] = &[10];
+assert_eq!(None, v.first_chunk::<2>());
+
+let w: &[i32] = &[];
+assert_eq!(Some(&[]), w.first_chunk::<0>());Return a mutable array reference to the first N items in the slice.
If the slice is not at least N in length, this will return None.
let x = &mut [0, 1, 2];
+
+if let Some(first) = x.first_chunk_mut::<2>() {
+ first[0] = 5;
+ first[1] = 4;
+}
+assert_eq!(x, &[5, 4, 2]);
+
+assert_eq!(None, x.first_chunk_mut::<4>());Return an array reference to the first N items in the slice and the remaining slice.
If the slice is not at least N in length, this will return None.
let x = &[0, 1, 2];
+
+if let Some((first, elements)) = x.split_first_chunk::<2>() {
+ assert_eq!(first, &[0, 1]);
+ assert_eq!(elements, &[2]);
+}
+
+assert_eq!(None, x.split_first_chunk::<4>());Return a mutable array reference to the first N items in the slice and the remaining
+slice.
If the slice is not at least N in length, this will return None.
let x = &mut [0, 1, 2];
+
+if let Some((first, elements)) = x.split_first_chunk_mut::<2>() {
+ first[0] = 3;
+ first[1] = 4;
+ elements[0] = 5;
+}
+assert_eq!(x, &[3, 4, 5]);
+
+assert_eq!(None, x.split_first_chunk_mut::<4>());Return an array reference to the last N items in the slice and the remaining slice.
If the slice is not at least N in length, this will return None.
let x = &[0, 1, 2];
+
+if let Some((elements, last)) = x.split_last_chunk::<2>() {
+ assert_eq!(elements, &[0]);
+ assert_eq!(last, &[1, 2]);
+}
+
+assert_eq!(None, x.split_last_chunk::<4>());Return a mutable array reference to the last N items in the slice and the remaining
+slice.
If the slice is not at least N in length, this will return None.
let x = &mut [0, 1, 2];
+
+if let Some((elements, last)) = x.split_last_chunk_mut::<2>() {
+ last[0] = 3;
+ last[1] = 4;
+ elements[0] = 5;
+}
+assert_eq!(x, &[5, 3, 4]);
+
+assert_eq!(None, x.split_last_chunk_mut::<4>());Return an array reference to the last N items in the slice.
If the slice is not at least N in length, this will return None.
let u = [10, 40, 30];
+assert_eq!(Some(&[40, 30]), u.last_chunk::<2>());
+
+let v: &[i32] = &[10];
+assert_eq!(None, v.last_chunk::<2>());
+
+let w: &[i32] = &[];
+assert_eq!(Some(&[]), w.last_chunk::<0>());Return a mutable array reference to the last N items in the slice.
If the slice is not at least N in length, this will return None.
let x = &mut [0, 1, 2];
+
+if let Some(last) = x.last_chunk_mut::<2>() {
+ last[0] = 10;
+ last[1] = 20;
+}
+assert_eq!(x, &[0, 10, 20]);
+
+assert_eq!(None, x.last_chunk_mut::<4>());Returns a reference to an element or subslice depending on the type of +index.
+None if out of bounds.None if out of bounds.let v = [10, 40, 30];
+assert_eq!(Some(&40), v.get(1));
+assert_eq!(Some(&[10, 40][..]), v.get(0..2));
+assert_eq!(None, v.get(3));
+assert_eq!(None, v.get(0..4));Returns a reference to an element or subslice, without doing bounds +checking.
+For a safe alternative see get.
Calling this method with an out-of-bounds index is undefined behavior +even if the resulting reference is not used.
+You can think of this like .get(index).unwrap_unchecked(). It’s UB
+to call .get_unchecked(len), even if you immediately convert to a
+pointer. And it’s UB to call .get_unchecked(..len + 1),
+.get_unchecked(..=len), or similar.
let x = &[1, 2, 4];
+
+unsafe {
+ assert_eq!(x.get_unchecked(1), &2);
+}Returns a mutable reference to an element or subslice, without doing +bounds checking.
+For a safe alternative see get_mut.
Calling this method with an out-of-bounds index is undefined behavior +even if the resulting reference is not used.
+You can think of this like .get_mut(index).unwrap_unchecked(). It’s
+UB to call .get_unchecked_mut(len), even if you immediately convert
+to a pointer. And it’s UB to call .get_unchecked_mut(..len + 1),
+.get_unchecked_mut(..=len), or similar.
let x = &mut [1, 2, 4];
+
+unsafe {
+ let elem = x.get_unchecked_mut(1);
+ *elem = 13;
+}
+assert_eq!(x, &[1, 13, 4]);Returns a raw pointer to the slice’s buffer.
+The caller must ensure that the slice outlives the pointer this +function returns, or else it will end up pointing to garbage.
+The caller must also ensure that the memory the pointer (non-transitively) points to
+is never written to (except inside an UnsafeCell) using this pointer or any pointer
+derived from it. If you need to mutate the contents of the slice, use as_mut_ptr.
Modifying the container referenced by this slice may cause its buffer +to be reallocated, which would also make any pointers to it invalid.
+let x = &[1, 2, 4];
+let x_ptr = x.as_ptr();
+
+unsafe {
+ for i in 0..x.len() {
+ assert_eq!(x.get_unchecked(i), &*x_ptr.add(i));
+ }
+}Returns an unsafe mutable pointer to the slice’s buffer.
+The caller must ensure that the slice outlives the pointer this +function returns, or else it will end up pointing to garbage.
+Modifying the container referenced by this slice may cause its buffer +to be reallocated, which would also make any pointers to it invalid.
+let x = &mut [1, 2, 4];
+let x_ptr = x.as_mut_ptr();
+
+unsafe {
+ for i in 0..x.len() {
+ *x_ptr.add(i) += 2;
+ }
+}
+assert_eq!(x, &[3, 4, 6]);Returns the two raw pointers spanning the slice.
+The returned range is half-open, which means that the end pointer +points one past the last element of the slice. This way, an empty +slice is represented by two equal pointers, and the difference between +the two pointers represents the size of the slice.
+See as_ptr for warnings on using these pointers. The end pointer
+requires extra caution, as it does not point to a valid element in the
+slice.
This function is useful for interacting with foreign interfaces which +use two pointers to refer to a range of elements in memory, as is +common in C++.
+It can also be useful to check if a pointer to an element refers to an +element of this slice:
+ +let a = [1, 2, 3];
+let x = &a[1] as *const _;
+let y = &5 as *const _;
+
+assert!(a.as_ptr_range().contains(&x));
+assert!(!a.as_ptr_range().contains(&y));Returns the two unsafe mutable pointers spanning the slice.
+The returned range is half-open, which means that the end pointer +points one past the last element of the slice. This way, an empty +slice is represented by two equal pointers, and the difference between +the two pointers represents the size of the slice.
+See as_mut_ptr for warnings on using these pointers. The end
+pointer requires extra caution, as it does not point to a valid element
+in the slice.
This function is useful for interacting with foreign interfaces which +use two pointers to refer to a range of elements in memory, as is +common in C++.
+Swaps two elements in the slice.
+If a equals to b, it’s guaranteed that elements won’t change value.
Panics if a or b are out of bounds.
let mut v = ["a", "b", "c", "d", "e"];
+v.swap(2, 4);
+assert!(v == ["a", "b", "e", "d", "c"]);slice_swap_unchecked)Swaps two elements in the slice, without doing bounds checking.
+For a safe alternative see swap.
Calling this method with an out-of-bounds index is undefined behavior.
+The caller has to ensure that a < self.len() and b < self.len().
#![feature(slice_swap_unchecked)]
+
+let mut v = ["a", "b", "c", "d"];
+// SAFETY: we know that 1 and 3 are both indices of the slice
+unsafe { v.swap_unchecked(1, 3) };
+assert!(v == ["a", "d", "c", "b"]);Reverses the order of elements in the slice, in place.
+let mut v = [1, 2, 3];
+v.reverse();
+assert!(v == [3, 2, 1]);Returns an iterator over the slice.
+The iterator yields all items from start to end.
+let x = &[1, 2, 4];
+let mut iterator = x.iter();
+
+assert_eq!(iterator.next(), Some(&1));
+assert_eq!(iterator.next(), Some(&2));
+assert_eq!(iterator.next(), Some(&4));
+assert_eq!(iterator.next(), None);Returns an iterator that allows modifying each value.
+The iterator yields all items from start to end.
+let x = &mut [1, 2, 4];
+for elem in x.iter_mut() {
+ *elem += 2;
+}
+assert_eq!(x, &[3, 4, 6]);Returns an iterator over all contiguous windows of length
+size. The windows overlap. If the slice is shorter than
+size, the iterator returns no values.
Panics if size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.windows(3);
+assert_eq!(iter.next().unwrap(), &['l', 'o', 'r']);
+assert_eq!(iter.next().unwrap(), &['o', 'r', 'e']);
+assert_eq!(iter.next().unwrap(), &['r', 'e', 'm']);
+assert!(iter.next().is_none());If the slice is shorter than size:
let slice = ['f', 'o', 'o'];
+let mut iter = slice.windows(4);
+assert!(iter.next().is_none());There’s no windows_mut, as that existing would let safe code violate the
+“only one &mut at a time to the same thing” rule. However, you can sometimes
+use Cell::as_slice_of_cells in
+conjunction with windows to accomplish something similar:
use std::cell::Cell;
+
+let mut array = ['R', 'u', 's', 't', ' ', '2', '0', '1', '5'];
+let slice = &mut array[..];
+let slice_of_cells: &[Cell<char>] = Cell::from_mut(slice).as_slice_of_cells();
+for w in slice_of_cells.windows(3) {
+ Cell::swap(&w[0], &w[2]);
+}
+assert_eq!(array, ['s', 't', ' ', '2', '0', '1', '5', 'u', 'R']);Returns an iterator over chunk_size elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are slices and do not overlap. If chunk_size does not divide the length of the
+slice, then the last chunk will not have length chunk_size.
See chunks_exact for a variant of this iterator that returns chunks of always exactly
+chunk_size elements, and rchunks for the same iterator but starting at the end of the
+slice.
Panics if chunk_size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.chunks(2);
+assert_eq!(iter.next().unwrap(), &['l', 'o']);
+assert_eq!(iter.next().unwrap(), &['r', 'e']);
+assert_eq!(iter.next().unwrap(), &['m']);
+assert!(iter.next().is_none());Returns an iterator over chunk_size elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are mutable slices, and do not overlap. If chunk_size does not divide the
+length of the slice, then the last chunk will not have length chunk_size.
See chunks_exact_mut for a variant of this iterator that returns chunks of always
+exactly chunk_size elements, and rchunks_mut for the same iterator but starting at
+the end of the slice.
Panics if chunk_size is 0.
let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.chunks_mut(2) {
+ for elem in chunk.iter_mut() {
+ *elem += count;
+ }
+ count += 1;
+}
+assert_eq!(v, &[1, 1, 2, 2, 3]);Returns an iterator over chunk_size elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are slices and do not overlap. If chunk_size does not divide the length of the
+slice, then the last up to chunk_size-1 elements will be omitted and can be retrieved
+from the remainder function of the iterator.
Due to each chunk having exactly chunk_size elements, the compiler can often optimize the
+resulting code better than in the case of chunks.
See chunks for a variant of this iterator that also returns the remainder as a smaller
+chunk, and rchunks_exact for the same iterator but starting at the end of the slice.
Panics if chunk_size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.chunks_exact(2);
+assert_eq!(iter.next().unwrap(), &['l', 'o']);
+assert_eq!(iter.next().unwrap(), &['r', 'e']);
+assert!(iter.next().is_none());
+assert_eq!(iter.remainder(), &['m']);Returns an iterator over chunk_size elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are mutable slices, and do not overlap. If chunk_size does not divide the
+length of the slice, then the last up to chunk_size-1 elements will be omitted and can be
+retrieved from the into_remainder function of the iterator.
Due to each chunk having exactly chunk_size elements, the compiler can often optimize the
+resulting code better than in the case of chunks_mut.
See chunks_mut for a variant of this iterator that also returns the remainder as a
+smaller chunk, and rchunks_exact_mut for the same iterator but starting at the end of
+the slice.
Panics if chunk_size is 0.
let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.chunks_exact_mut(2) {
+ for elem in chunk.iter_mut() {
+ *elem += count;
+ }
+ count += 1;
+}
+assert_eq!(v, &[1, 1, 2, 2, 0]);slice_as_chunks)Splits the slice into a slice of N-element arrays,
+assuming that there’s no remainder.
This may only be called when
+N-element chunks (aka self.len() % N == 0).N != 0.#![feature(slice_as_chunks)]
+let slice: &[char] = &['l', 'o', 'r', 'e', 'm', '!'];
+let chunks: &[[char; 1]] =
+ // SAFETY: 1-element chunks never have remainder
+ unsafe { slice.as_chunks_unchecked() };
+assert_eq!(chunks, &[['l'], ['o'], ['r'], ['e'], ['m'], ['!']]);
+let chunks: &[[char; 3]] =
+ // SAFETY: The slice length (6) is a multiple of 3
+ unsafe { slice.as_chunks_unchecked() };
+assert_eq!(chunks, &[['l', 'o', 'r'], ['e', 'm', '!']]);
+
+// These would be unsound:
+// let chunks: &[[_; 5]] = slice.as_chunks_unchecked() // The slice length is not a multiple of 5
+// let chunks: &[[_; 0]] = slice.as_chunks_unchecked() // Zero-length chunks are never allowedslice_as_chunks)Splits the slice into a slice of N-element arrays,
+starting at the beginning of the slice,
+and a remainder slice with length strictly less than N.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(slice_as_chunks)]
+let slice = ['l', 'o', 'r', 'e', 'm'];
+let (chunks, remainder) = slice.as_chunks();
+assert_eq!(chunks, &[['l', 'o'], ['r', 'e']]);
+assert_eq!(remainder, &['m']);If you expect the slice to be an exact multiple, you can combine
+let-else with an empty slice pattern:
#![feature(slice_as_chunks)]
+let slice = ['R', 'u', 's', 't'];
+let (chunks, []) = slice.as_chunks::<2>() else {
+ panic!("slice didn't have even length")
+};
+assert_eq!(chunks, &[['R', 'u'], ['s', 't']]);slice_as_chunks)Splits the slice into a slice of N-element arrays,
+starting at the end of the slice,
+and a remainder slice with length strictly less than N.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(slice_as_chunks)]
+let slice = ['l', 'o', 'r', 'e', 'm'];
+let (remainder, chunks) = slice.as_rchunks();
+assert_eq!(remainder, &['l']);
+assert_eq!(chunks, &[['o', 'r'], ['e', 'm']]);array_chunks)Returns an iterator over N elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are array references and do not overlap. If N does not divide the
+length of the slice, then the last up to N-1 elements will be omitted and can be
+retrieved from the remainder function of the iterator.
This method is the const generic equivalent of chunks_exact.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(array_chunks)]
+let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.array_chunks();
+assert_eq!(iter.next().unwrap(), &['l', 'o']);
+assert_eq!(iter.next().unwrap(), &['r', 'e']);
+assert!(iter.next().is_none());
+assert_eq!(iter.remainder(), &['m']);slice_as_chunks)Splits the slice into a slice of N-element arrays,
+assuming that there’s no remainder.
This may only be called when
+N-element chunks (aka self.len() % N == 0).N != 0.#![feature(slice_as_chunks)]
+let slice: &mut [char] = &mut ['l', 'o', 'r', 'e', 'm', '!'];
+let chunks: &mut [[char; 1]] =
+ // SAFETY: 1-element chunks never have remainder
+ unsafe { slice.as_chunks_unchecked_mut() };
+chunks[0] = ['L'];
+assert_eq!(chunks, &[['L'], ['o'], ['r'], ['e'], ['m'], ['!']]);
+let chunks: &mut [[char; 3]] =
+ // SAFETY: The slice length (6) is a multiple of 3
+ unsafe { slice.as_chunks_unchecked_mut() };
+chunks[1] = ['a', 'x', '?'];
+assert_eq!(slice, &['L', 'o', 'r', 'a', 'x', '?']);
+
+// These would be unsound:
+// let chunks: &[[_; 5]] = slice.as_chunks_unchecked_mut() // The slice length is not a multiple of 5
+// let chunks: &[[_; 0]] = slice.as_chunks_unchecked_mut() // Zero-length chunks are never allowedslice_as_chunks)Splits the slice into a slice of N-element arrays,
+starting at the beginning of the slice,
+and a remainder slice with length strictly less than N.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(slice_as_chunks)]
+let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+let (chunks, remainder) = v.as_chunks_mut();
+remainder[0] = 9;
+for chunk in chunks {
+ *chunk = [count; 2];
+ count += 1;
+}
+assert_eq!(v, &[1, 1, 2, 2, 9]);slice_as_chunks)Splits the slice into a slice of N-element arrays,
+starting at the end of the slice,
+and a remainder slice with length strictly less than N.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(slice_as_chunks)]
+let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+let (remainder, chunks) = v.as_rchunks_mut();
+remainder[0] = 9;
+for chunk in chunks {
+ *chunk = [count; 2];
+ count += 1;
+}
+assert_eq!(v, &[9, 1, 1, 2, 2]);array_chunks)Returns an iterator over N elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are mutable array references and do not overlap. If N does not divide
+the length of the slice, then the last up to N-1 elements will be omitted and
+can be retrieved from the into_remainder function of the iterator.
This method is the const generic equivalent of chunks_exact_mut.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(array_chunks)]
+let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.array_chunks_mut() {
+ *chunk = [count; 2];
+ count += 1;
+}
+assert_eq!(v, &[1, 1, 2, 2, 0]);array_windows)Returns an iterator over overlapping windows of N elements of a slice,
+starting at the beginning of the slice.
This is the const generic equivalent of windows.
If N is greater than the size of the slice, it will return no windows.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(array_windows)]
+let slice = [0, 1, 2, 3];
+let mut iter = slice.array_windows();
+assert_eq!(iter.next().unwrap(), &[0, 1]);
+assert_eq!(iter.next().unwrap(), &[1, 2]);
+assert_eq!(iter.next().unwrap(), &[2, 3]);
+assert!(iter.next().is_none());Returns an iterator over chunk_size elements of the slice at a time, starting at the end
+of the slice.
The chunks are slices and do not overlap. If chunk_size does not divide the length of the
+slice, then the last chunk will not have length chunk_size.
See rchunks_exact for a variant of this iterator that returns chunks of always exactly
+chunk_size elements, and chunks for the same iterator but starting at the beginning
+of the slice.
Panics if chunk_size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.rchunks(2);
+assert_eq!(iter.next().unwrap(), &['e', 'm']);
+assert_eq!(iter.next().unwrap(), &['o', 'r']);
+assert_eq!(iter.next().unwrap(), &['l']);
+assert!(iter.next().is_none());Returns an iterator over chunk_size elements of the slice at a time, starting at the end
+of the slice.
The chunks are mutable slices, and do not overlap. If chunk_size does not divide the
+length of the slice, then the last chunk will not have length chunk_size.
See rchunks_exact_mut for a variant of this iterator that returns chunks of always
+exactly chunk_size elements, and chunks_mut for the same iterator but starting at the
+beginning of the slice.
Panics if chunk_size is 0.
let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.rchunks_mut(2) {
+ for elem in chunk.iter_mut() {
+ *elem += count;
+ }
+ count += 1;
+}
+assert_eq!(v, &[3, 2, 2, 1, 1]);Returns an iterator over chunk_size elements of the slice at a time, starting at the
+end of the slice.
The chunks are slices and do not overlap. If chunk_size does not divide the length of the
+slice, then the last up to chunk_size-1 elements will be omitted and can be retrieved
+from the remainder function of the iterator.
Due to each chunk having exactly chunk_size elements, the compiler can often optimize the
+resulting code better than in the case of rchunks.
See rchunks for a variant of this iterator that also returns the remainder as a smaller
+chunk, and chunks_exact for the same iterator but starting at the beginning of the
+slice.
Panics if chunk_size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.rchunks_exact(2);
+assert_eq!(iter.next().unwrap(), &['e', 'm']);
+assert_eq!(iter.next().unwrap(), &['o', 'r']);
+assert!(iter.next().is_none());
+assert_eq!(iter.remainder(), &['l']);Returns an iterator over chunk_size elements of the slice at a time, starting at the end
+of the slice.
The chunks are mutable slices, and do not overlap. If chunk_size does not divide the
+length of the slice, then the last up to chunk_size-1 elements will be omitted and can be
+retrieved from the into_remainder function of the iterator.
Due to each chunk having exactly chunk_size elements, the compiler can often optimize the
+resulting code better than in the case of chunks_mut.
See rchunks_mut for a variant of this iterator that also returns the remainder as a
+smaller chunk, and chunks_exact_mut for the same iterator but starting at the beginning
+of the slice.
Panics if chunk_size is 0.
let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.rchunks_exact_mut(2) {
+ for elem in chunk.iter_mut() {
+ *elem += count;
+ }
+ count += 1;
+}
+assert_eq!(v, &[0, 2, 2, 1, 1]);Returns an iterator over the slice producing non-overlapping runs +of elements using the predicate to separate them.
+The predicate is called for every pair of consecutive elements,
+meaning that it is called on slice[0] and slice[1],
+followed by slice[1] and slice[2], and so on.
let slice = &[1, 1, 1, 3, 3, 2, 2, 2];
+
+let mut iter = slice.chunk_by(|a, b| a == b);
+
+assert_eq!(iter.next(), Some(&[1, 1, 1][..]));
+assert_eq!(iter.next(), Some(&[3, 3][..]));
+assert_eq!(iter.next(), Some(&[2, 2, 2][..]));
+assert_eq!(iter.next(), None);This method can be used to extract the sorted subslices:
+ +let slice = &[1, 1, 2, 3, 2, 3, 2, 3, 4];
+
+let mut iter = slice.chunk_by(|a, b| a <= b);
+
+assert_eq!(iter.next(), Some(&[1, 1, 2, 3][..]));
+assert_eq!(iter.next(), Some(&[2, 3][..]));
+assert_eq!(iter.next(), Some(&[2, 3, 4][..]));
+assert_eq!(iter.next(), None);Returns an iterator over the slice producing non-overlapping mutable +runs of elements using the predicate to separate them.
+The predicate is called for every pair of consecutive elements,
+meaning that it is called on slice[0] and slice[1],
+followed by slice[1] and slice[2], and so on.
let slice = &mut [1, 1, 1, 3, 3, 2, 2, 2];
+
+let mut iter = slice.chunk_by_mut(|a, b| a == b);
+
+assert_eq!(iter.next(), Some(&mut [1, 1, 1][..]));
+assert_eq!(iter.next(), Some(&mut [3, 3][..]));
+assert_eq!(iter.next(), Some(&mut [2, 2, 2][..]));
+assert_eq!(iter.next(), None);This method can be used to extract the sorted subslices:
+ +let slice = &mut [1, 1, 2, 3, 2, 3, 2, 3, 4];
+
+let mut iter = slice.chunk_by_mut(|a, b| a <= b);
+
+assert_eq!(iter.next(), Some(&mut [1, 1, 2, 3][..]));
+assert_eq!(iter.next(), Some(&mut [2, 3][..]));
+assert_eq!(iter.next(), Some(&mut [2, 3, 4][..]));
+assert_eq!(iter.next(), None);Divides one slice into two at an index.
+The first will contain all indices from [0, mid) (excluding
+the index mid itself) and the second will contain all
+indices from [mid, len) (excluding the index len itself).
Panics if mid > len. For a non-panicking alternative see
+split_at_checked.
let v = [1, 2, 3, 4, 5, 6];
+
+{
+ let (left, right) = v.split_at(0);
+ assert_eq!(left, []);
+ assert_eq!(right, [1, 2, 3, 4, 5, 6]);
+}
+
+{
+ let (left, right) = v.split_at(2);
+ assert_eq!(left, [1, 2]);
+ assert_eq!(right, [3, 4, 5, 6]);
+}
+
+{
+ let (left, right) = v.split_at(6);
+ assert_eq!(left, [1, 2, 3, 4, 5, 6]);
+ assert_eq!(right, []);
+}Divides one mutable slice into two at an index.
+The first will contain all indices from [0, mid) (excluding
+the index mid itself) and the second will contain all
+indices from [mid, len) (excluding the index len itself).
Panics if mid > len. For a non-panicking alternative see
+split_at_mut_checked.
let mut v = [1, 0, 3, 0, 5, 6];
+let (left, right) = v.split_at_mut(2);
+assert_eq!(left, [1, 0]);
+assert_eq!(right, [3, 0, 5, 6]);
+left[1] = 2;
+right[1] = 4;
+assert_eq!(v, [1, 2, 3, 4, 5, 6]);Divides one slice into two at an index, without doing bounds checking.
+The first will contain all indices from [0, mid) (excluding
+the index mid itself) and the second will contain all
+indices from [mid, len) (excluding the index len itself).
For a safe alternative see split_at.
Calling this method with an out-of-bounds index is undefined behavior
+even if the resulting reference is not used. The caller has to ensure that
+0 <= mid <= self.len().
let v = [1, 2, 3, 4, 5, 6];
+
+unsafe {
+ let (left, right) = v.split_at_unchecked(0);
+ assert_eq!(left, []);
+ assert_eq!(right, [1, 2, 3, 4, 5, 6]);
+}
+
+unsafe {
+ let (left, right) = v.split_at_unchecked(2);
+ assert_eq!(left, [1, 2]);
+ assert_eq!(right, [3, 4, 5, 6]);
+}
+
+unsafe {
+ let (left, right) = v.split_at_unchecked(6);
+ assert_eq!(left, [1, 2, 3, 4, 5, 6]);
+ assert_eq!(right, []);
+}Divides one mutable slice into two at an index, without doing bounds checking.
+The first will contain all indices from [0, mid) (excluding
+the index mid itself) and the second will contain all
+indices from [mid, len) (excluding the index len itself).
For a safe alternative see split_at_mut.
Calling this method with an out-of-bounds index is undefined behavior
+even if the resulting reference is not used. The caller has to ensure that
+0 <= mid <= self.len().
let mut v = [1, 0, 3, 0, 5, 6];
+// scoped to restrict the lifetime of the borrows
+unsafe {
+ let (left, right) = v.split_at_mut_unchecked(2);
+ assert_eq!(left, [1, 0]);
+ assert_eq!(right, [3, 0, 5, 6]);
+ left[1] = 2;
+ right[1] = 4;
+}
+assert_eq!(v, [1, 2, 3, 4, 5, 6]);Divides one slice into two at an index, returning None if the slice is
+too short.
If mid ≤ len returns a pair of slices where the first will contain all
+indices from [0, mid) (excluding the index mid itself) and the
+second will contain all indices from [mid, len) (excluding the index
+len itself).
Otherwise, if mid > len, returns None.
let v = [1, -2, 3, -4, 5, -6];
+
+{
+ let (left, right) = v.split_at_checked(0).unwrap();
+ assert_eq!(left, []);
+ assert_eq!(right, [1, -2, 3, -4, 5, -6]);
+}
+
+{
+ let (left, right) = v.split_at_checked(2).unwrap();
+ assert_eq!(left, [1, -2]);
+ assert_eq!(right, [3, -4, 5, -6]);
+}
+
+{
+ let (left, right) = v.split_at_checked(6).unwrap();
+ assert_eq!(left, [1, -2, 3, -4, 5, -6]);
+ assert_eq!(right, []);
+}
+
+assert_eq!(None, v.split_at_checked(7));Divides one mutable slice into two at an index, returning None if the
+slice is too short.
If mid ≤ len returns a pair of slices where the first will contain all
+indices from [0, mid) (excluding the index mid itself) and the
+second will contain all indices from [mid, len) (excluding the index
+len itself).
Otherwise, if mid > len, returns None.
let mut v = [1, 0, 3, 0, 5, 6];
+
+if let Some((left, right)) = v.split_at_mut_checked(2) {
+ assert_eq!(left, [1, 0]);
+ assert_eq!(right, [3, 0, 5, 6]);
+ left[1] = 2;
+ right[1] = 4;
+}
+assert_eq!(v, [1, 2, 3, 4, 5, 6]);
+
+assert_eq!(None, v.split_at_mut_checked(7));Returns an iterator over subslices separated by elements that match
+pred. The matched element is not contained in the subslices.
let slice = [10, 40, 33, 20];
+let mut iter = slice.split(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[10, 40]);
+assert_eq!(iter.next().unwrap(), &[20]);
+assert!(iter.next().is_none());If the first element is matched, an empty slice will be the first item +returned by the iterator. Similarly, if the last element in the slice +is matched, an empty slice will be the last item returned by the +iterator:
+ +let slice = [10, 40, 33];
+let mut iter = slice.split(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[10, 40]);
+assert_eq!(iter.next().unwrap(), &[]);
+assert!(iter.next().is_none());If two matched elements are directly adjacent, an empty slice will be +present between them:
+ +let slice = [10, 6, 33, 20];
+let mut iter = slice.split(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[10]);
+assert_eq!(iter.next().unwrap(), &[]);
+assert_eq!(iter.next().unwrap(), &[20]);
+assert!(iter.next().is_none());Returns an iterator over mutable subslices separated by elements that
+match pred. The matched element is not contained in the subslices.
let mut v = [10, 40, 30, 20, 60, 50];
+
+for group in v.split_mut(|num| *num % 3 == 0) {
+ group[0] = 1;
+}
+assert_eq!(v, [1, 40, 30, 1, 60, 1]);Returns an iterator over subslices separated by elements that match
+pred. The matched element is contained in the end of the previous
+subslice as a terminator.
let slice = [10, 40, 33, 20];
+let mut iter = slice.split_inclusive(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[10, 40, 33]);
+assert_eq!(iter.next().unwrap(), &[20]);
+assert!(iter.next().is_none());If the last element of the slice is matched, +that element will be considered the terminator of the preceding slice. +That slice will be the last item returned by the iterator.
+ +let slice = [3, 10, 40, 33];
+let mut iter = slice.split_inclusive(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[3]);
+assert_eq!(iter.next().unwrap(), &[10, 40, 33]);
+assert!(iter.next().is_none());Returns an iterator over mutable subslices separated by elements that
+match pred. The matched element is contained in the previous
+subslice as a terminator.
let mut v = [10, 40, 30, 20, 60, 50];
+
+for group in v.split_inclusive_mut(|num| *num % 3 == 0) {
+ let terminator_idx = group.len()-1;
+ group[terminator_idx] = 1;
+}
+assert_eq!(v, [10, 40, 1, 20, 1, 1]);Returns an iterator over subslices separated by elements that match
+pred, starting at the end of the slice and working backwards.
+The matched element is not contained in the subslices.
let slice = [11, 22, 33, 0, 44, 55];
+let mut iter = slice.rsplit(|num| *num == 0);
+
+assert_eq!(iter.next().unwrap(), &[44, 55]);
+assert_eq!(iter.next().unwrap(), &[11, 22, 33]);
+assert_eq!(iter.next(), None);As with split(), if the first or last element is matched, an empty
+slice will be the first (or last) item returned by the iterator.
let v = &[0, 1, 1, 2, 3, 5, 8];
+let mut it = v.rsplit(|n| *n % 2 == 0);
+assert_eq!(it.next().unwrap(), &[]);
+assert_eq!(it.next().unwrap(), &[3, 5]);
+assert_eq!(it.next().unwrap(), &[1, 1]);
+assert_eq!(it.next().unwrap(), &[]);
+assert_eq!(it.next(), None);Returns an iterator over mutable subslices separated by elements that
+match pred, starting at the end of the slice and working
+backwards. The matched element is not contained in the subslices.
let mut v = [100, 400, 300, 200, 600, 500];
+
+let mut count = 0;
+for group in v.rsplit_mut(|num| *num % 3 == 0) {
+ count += 1;
+ group[0] = count;
+}
+assert_eq!(v, [3, 400, 300, 2, 600, 1]);Returns an iterator over subslices separated by elements that match
+pred, limited to returning at most n items. The matched element is
+not contained in the subslices.
The last element returned, if any, will contain the remainder of the +slice.
+Print the slice split once by numbers divisible by 3 (i.e., [10, 40],
+[20, 60, 50]):
let v = [10, 40, 30, 20, 60, 50];
+
+for group in v.splitn(2, |num| *num % 3 == 0) {
+ println!("{group:?}");
+}Returns an iterator over mutable subslices separated by elements that match
+pred, limited to returning at most n items. The matched element is
+not contained in the subslices.
The last element returned, if any, will contain the remainder of the +slice.
+let mut v = [10, 40, 30, 20, 60, 50];
+
+for group in v.splitn_mut(2, |num| *num % 3 == 0) {
+ group[0] = 1;
+}
+assert_eq!(v, [1, 40, 30, 1, 60, 50]);Returns an iterator over subslices separated by elements that match
+pred limited to returning at most n items. This starts at the end of
+the slice and works backwards. The matched element is not contained in
+the subslices.
The last element returned, if any, will contain the remainder of the +slice.
+Print the slice split once, starting from the end, by numbers divisible
+by 3 (i.e., [50], [10, 40, 30, 20]):
let v = [10, 40, 30, 20, 60, 50];
+
+for group in v.rsplitn(2, |num| *num % 3 == 0) {
+ println!("{group:?}");
+}Returns an iterator over subslices separated by elements that match
+pred limited to returning at most n items. This starts at the end of
+the slice and works backwards. The matched element is not contained in
+the subslices.
The last element returned, if any, will contain the remainder of the +slice.
+let mut s = [10, 40, 30, 20, 60, 50];
+
+for group in s.rsplitn_mut(2, |num| *num % 3 == 0) {
+ group[0] = 1;
+}
+assert_eq!(s, [1, 40, 30, 20, 60, 1]);slice_split_once)Splits the slice on the first element that matches the specified +predicate.
+If any matching elements are present in the slice, returns the prefix
+before the match and suffix after. The matching element itself is not
+included. If no elements match, returns None.
#![feature(slice_split_once)]
+let s = [1, 2, 3, 2, 4];
+assert_eq!(s.split_once(|&x| x == 2), Some((
+ &[1][..],
+ &[3, 2, 4][..]
+)));
+assert_eq!(s.split_once(|&x| x == 0), None);slice_split_once)Splits the slice on the last element that matches the specified +predicate.
+If any matching elements are present in the slice, returns the prefix
+before the match and suffix after. The matching element itself is not
+included. If no elements match, returns None.
#![feature(slice_split_once)]
+let s = [1, 2, 3, 2, 4];
+assert_eq!(s.rsplit_once(|&x| x == 2), Some((
+ &[1, 2, 3][..],
+ &[4][..]
+)));
+assert_eq!(s.rsplit_once(|&x| x == 0), None);Returns true if the slice contains an element with the given value.
This operation is O(n).
+Note that if you have a sorted slice, binary_search may be faster.
let v = [10, 40, 30];
+assert!(v.contains(&30));
+assert!(!v.contains(&50));If you do not have a &T, but some other value that you can compare
+with one (for example, String implements PartialEq<str>), you can
+use iter().any:
let v = [String::from("hello"), String::from("world")]; // slice of `String`
+assert!(v.iter().any(|e| e == "hello")); // search with `&str`
+assert!(!v.iter().any(|e| e == "hi"));Returns true if needle is a prefix of the slice or equal to the slice.
let v = [10, 40, 30];
+assert!(v.starts_with(&[10]));
+assert!(v.starts_with(&[10, 40]));
+assert!(v.starts_with(&v));
+assert!(!v.starts_with(&[50]));
+assert!(!v.starts_with(&[10, 50]));Always returns true if needle is an empty slice:
let v = &[10, 40, 30];
+assert!(v.starts_with(&[]));
+let v: &[u8] = &[];
+assert!(v.starts_with(&[]));Returns true if needle is a suffix of the slice or equal to the slice.
let v = [10, 40, 30];
+assert!(v.ends_with(&[30]));
+assert!(v.ends_with(&[40, 30]));
+assert!(v.ends_with(&v));
+assert!(!v.ends_with(&[50]));
+assert!(!v.ends_with(&[50, 30]));Always returns true if needle is an empty slice:
let v = &[10, 40, 30];
+assert!(v.ends_with(&[]));
+let v: &[u8] = &[];
+assert!(v.ends_with(&[]));Returns a subslice with the prefix removed.
+If the slice starts with prefix, returns the subslice after the prefix, wrapped in Some.
+If prefix is empty, simply returns the original slice. If prefix is equal to the
+original slice, returns an empty slice.
If the slice does not start with prefix, returns None.
let v = &[10, 40, 30];
+assert_eq!(v.strip_prefix(&[10]), Some(&[40, 30][..]));
+assert_eq!(v.strip_prefix(&[10, 40]), Some(&[30][..]));
+assert_eq!(v.strip_prefix(&[10, 40, 30]), Some(&[][..]));
+assert_eq!(v.strip_prefix(&[50]), None);
+assert_eq!(v.strip_prefix(&[10, 50]), None);
+
+let prefix : &str = "he";
+assert_eq!(b"hello".strip_prefix(prefix.as_bytes()),
+ Some(b"llo".as_ref()));Returns a subslice with the suffix removed.
+If the slice ends with suffix, returns the subslice before the suffix, wrapped in Some.
+If suffix is empty, simply returns the original slice. If suffix is equal to the
+original slice, returns an empty slice.
If the slice does not end with suffix, returns None.
let v = &[10, 40, 30];
+assert_eq!(v.strip_suffix(&[30]), Some(&[10, 40][..]));
+assert_eq!(v.strip_suffix(&[40, 30]), Some(&[10][..]));
+assert_eq!(v.strip_suffix(&[10, 40, 30]), Some(&[][..]));
+assert_eq!(v.strip_suffix(&[50]), None);
+assert_eq!(v.strip_suffix(&[50, 30]), None);Binary searches this slice for a given element. +If the slice is not sorted, the returned result is unspecified and +meaningless.
+If the value is found then Result::Ok is returned, containing the
+index of the matching element. If there are multiple matches, then any
+one of the matches could be returned. The index is chosen
+deterministically, but is subject to change in future versions of Rust.
+If the value is not found then Result::Err is returned, containing
+the index where a matching element could be inserted while maintaining
+sorted order.
See also binary_search_by, binary_search_by_key, and partition_point.
Looks up a series of four elements. The first is found, with a
+uniquely determined position; the second and third are not
+found; the fourth could match any position in [1, 4].
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+
+assert_eq!(s.binary_search(&13), Ok(9));
+assert_eq!(s.binary_search(&4), Err(7));
+assert_eq!(s.binary_search(&100), Err(13));
+let r = s.binary_search(&1);
+assert!(match r { Ok(1..=4) => true, _ => false, });If you want to find that whole range of matching items, rather than
+an arbitrary matching one, that can be done using partition_point:
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+
+let low = s.partition_point(|x| x < &1);
+assert_eq!(low, 1);
+let high = s.partition_point(|x| x <= &1);
+assert_eq!(high, 5);
+let r = s.binary_search(&1);
+assert!((low..high).contains(&r.unwrap()));
+
+assert!(s[..low].iter().all(|&x| x < 1));
+assert!(s[low..high].iter().all(|&x| x == 1));
+assert!(s[high..].iter().all(|&x| x > 1));
+
+// For something not found, the "range" of equal items is empty
+assert_eq!(s.partition_point(|x| x < &11), 9);
+assert_eq!(s.partition_point(|x| x <= &11), 9);
+assert_eq!(s.binary_search(&11), Err(9));If you want to insert an item to a sorted vector, while maintaining
+sort order, consider using partition_point:
let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+let num = 42;
+let idx = s.partition_point(|&x| x <= num);
+// If `num` is unique, `s.partition_point(|&x| x < num)` (with `<`) is equivalent to
+// `s.binary_search(&num).unwrap_or_else(|x| x)`, but using `<=` will allow `insert`
+// to shift less elements.
+s.insert(idx, num);
+assert_eq!(s, [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]);Binary searches this slice with a comparator function.
+The comparator function should return an order code that indicates
+whether its argument is Less, Equal or Greater the desired
+target.
+If the slice is not sorted or if the comparator function does not
+implement an order consistent with the sort order of the underlying
+slice, the returned result is unspecified and meaningless.
If the value is found then Result::Ok is returned, containing the
+index of the matching element. If there are multiple matches, then any
+one of the matches could be returned. The index is chosen
+deterministically, but is subject to change in future versions of Rust.
+If the value is not found then Result::Err is returned, containing
+the index where a matching element could be inserted while maintaining
+sorted order.
See also binary_search, binary_search_by_key, and partition_point.
Looks up a series of four elements. The first is found, with a
+uniquely determined position; the second and third are not
+found; the fourth could match any position in [1, 4].
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+
+let seek = 13;
+assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Ok(9));
+let seek = 4;
+assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(7));
+let seek = 100;
+assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(13));
+let seek = 1;
+let r = s.binary_search_by(|probe| probe.cmp(&seek));
+assert!(match r { Ok(1..=4) => true, _ => false, });Binary searches this slice with a key extraction function.
+Assumes that the slice is sorted by the key, for instance with
+sort_by_key using the same key extraction function.
+If the slice is not sorted by the key, the returned result is
+unspecified and meaningless.
If the value is found then Result::Ok is returned, containing the
+index of the matching element. If there are multiple matches, then any
+one of the matches could be returned. The index is chosen
+deterministically, but is subject to change in future versions of Rust.
+If the value is not found then Result::Err is returned, containing
+the index where a matching element could be inserted while maintaining
+sorted order.
See also binary_search, binary_search_by, and partition_point.
Looks up a series of four elements in a slice of pairs sorted by
+their second elements. The first is found, with a uniquely
+determined position; the second and third are not found; the
+fourth could match any position in [1, 4].
let s = [(0, 0), (2, 1), (4, 1), (5, 1), (3, 1),
+ (1, 2), (2, 3), (4, 5), (5, 8), (3, 13),
+ (1, 21), (2, 34), (4, 55)];
+
+assert_eq!(s.binary_search_by_key(&13, |&(a, b)| b), Ok(9));
+assert_eq!(s.binary_search_by_key(&4, |&(a, b)| b), Err(7));
+assert_eq!(s.binary_search_by_key(&100, |&(a, b)| b), Err(13));
+let r = s.binary_search_by_key(&1, |&(a, b)| b);
+assert!(match r { Ok(1..=4) => true, _ => false, });Sorts the slice without preserving the initial order of equal elements.
+This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not +allocate), and O(n * log(n)) worst-case.
+If T: Ord does not implement a total order the resulting order is unspecified. All
+original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if T: Ord panics.
The current implementation is based on ipnsort by Lukas Bergdoll and Orson Peters, which +combines the fast average case of quicksort with the fast worst case of heapsort, achieving +linear time on fully sorted and reversed inputs. On inputs with k distinct elements, the +expected time to sort the data is O(n * log(k)).
+It is typically faster than stable sorting, except in a few special cases, e.g., when the +slice is partially sorted.
+If T: Ord does not implement a total order, the implementation may panic.
let mut v = [-5, 4, 1, -3, 2];
+
+v.sort_unstable();
+assert!(v == [-5, -3, 1, 2, 4]);Sorts the slice with a comparator function, without preserving the initial order of +equal elements.
+This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not +allocate), and O(n * log(n)) worst-case.
+The comparator function should define a total ordering for the elements in the slice. If the +ordering is not total, the order of the elements is unspecified.
+If the comparator function does not implement a total order the resulting order is
+unspecified. All original elements will remain in the slice and any possible modifications
+via interior mutability are observed in the input. Same is true if the comparator function
+panics. A total order (for all a, b and c):
a < b, a == b or a > b is true, anda < b and b < c implies a < c. The same must hold for both == and >.For example, while f64 doesn’t implement Ord because NaN != NaN, we can use
+partial_cmp as our sort function when we know the slice doesn’t contain a NaN.
let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
+floats.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap());
+assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);The current implementation is based on ipnsort by Lukas Bergdoll and Orson Peters, which +combines the fast average case of quicksort with the fast worst case of heapsort, achieving +linear time on fully sorted and reversed inputs. On inputs with k distinct elements, the +expected time to sort the data is O(n * log(k)).
+It is typically faster than stable sorting, except in a few special cases, e.g., when the +slice is partially sorted.
+If T: Ord does not implement a total order, the implementation may panic.
let mut v = [5, 4, 1, 3, 2];
+v.sort_unstable_by(|a, b| a.cmp(b));
+assert!(v == [1, 2, 3, 4, 5]);
+
+// reverse sorting
+v.sort_unstable_by(|a, b| b.cmp(a));
+assert!(v == [5, 4, 3, 2, 1]);Sorts the slice with a key extraction function, without preserving the initial order of +equal elements.
+This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not +allocate), and O(n * log(n)) worst-case.
+If K: Ord does not implement a total order the resulting order is unspecified.
+All original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if K: Ord panics.
The current implementation is based on ipnsort by Lukas Bergdoll and Orson Peters, which +combines the fast average case of quicksort with the fast worst case of heapsort, achieving +linear time on fully sorted and reversed inputs. On inputs with k distinct elements, the +expected time to sort the data is O(n * log(k)).
+It is typically faster than stable sorting, except in a few special cases, e.g., when the +slice is partially sorted.
+If K: Ord does not implement a total order, the implementation may panic.
let mut v = [-5i32, 4, 1, -3, 2];
+
+v.sort_unstable_by_key(|k| k.abs());
+assert!(v == [1, 2, -3, 4, -5]);Reorder the slice such that the element at index after the reordering is at its final
+sorted position.
This reordering has the additional property that any value at position i < index will be
+less than or equal to any value at a position j > index. Additionally, this reordering is
+unstable (i.e. any number of equal elements may end up at position index), in-place (i.e.
+does not allocate), and runs in O(n) time. This function is also known as “kth element”
+in other libraries.
It returns a triplet of the following from the reordered slice: the subslice prior to
+index, the element at index, and the subslice after index; accordingly, the values in
+those two subslices will respectively all be less-than-or-equal-to and
+greater-than-or-equal-to the value of the element at index.
The current algorithm is an introselect implementation based on ipnsort by Lukas Bergdoll
+and Orson Peters, which is also the basis for sort_unstable. The fallback algorithm is
+Median of Medians using Tukey’s Ninther for pivot selection, which guarantees linear runtime
+for all inputs.
It is typically faster than stable sorting, except in a few special cases, e.g., when the
+slice is nearly fully sorted, where slice::sort may be faster.
Panics when index >= len(), meaning it always panics on empty slices.
let mut v = [-5i32, 4, 2, -3, 1];
+
+// Find the items less than or equal to the median, the median, and greater than or equal to
+// the median.
+let (lesser, median, greater) = v.select_nth_unstable(2);
+
+assert!(lesser == [-3, -5] || lesser == [-5, -3]);
+assert_eq!(median, &mut 1);
+assert!(greater == [4, 2] || greater == [2, 4]);
+
+// We are only guaranteed the slice will be one of the following, based on the way we sort
+// about the specified index.
+assert!(v == [-3, -5, 1, 2, 4] ||
+ v == [-5, -3, 1, 2, 4] ||
+ v == [-3, -5, 1, 4, 2] ||
+ v == [-5, -3, 1, 4, 2]);Reorder the slice with a comparator function such that the element at index after the
+reordering is at its final sorted position.
This reordering has the additional property that any value at position i < index will be
+less than or equal to any value at a position j > index using the comparator function.
+Additionally, this reordering is unstable (i.e. any number of equal elements may end up at
+position index), in-place (i.e. does not allocate), and runs in O(n) time. This
+function is also known as “kth element” in other libraries.
It returns a triplet of the following from the slice reordered according to the provided
+comparator function: the subslice prior to index, the element at index, and the subslice
+after index; accordingly, the values in those two subslices will respectively all be
+less-than-or-equal-to and greater-than-or-equal-to the value of the element at index.
The current algorithm is an introselect implementation based on ipnsort by Lukas Bergdoll
+and Orson Peters, which is also the basis for sort_unstable. The fallback algorithm is
+Median of Medians using Tukey’s Ninther for pivot selection, which guarantees linear runtime
+for all inputs.
It is typically faster than stable sorting, except in a few special cases, e.g., when the
+slice is nearly fully sorted, where slice::sort may be faster.
Panics when index >= len(), meaning it always panics on empty slices.
let mut v = [-5i32, 4, 2, -3, 1];
+
+// Find the items less than or equal to the median, the median, and greater than or equal to
+// the median as if the slice were sorted in descending order.
+let (lesser, median, greater) = v.select_nth_unstable_by(2, |a, b| b.cmp(a));
+
+assert!(lesser == [4, 2] || lesser == [2, 4]);
+assert_eq!(median, &mut 1);
+assert!(greater == [-3, -5] || greater == [-5, -3]);
+
+// We are only guaranteed the slice will be one of the following, based on the way we sort
+// about the specified index.
+assert!(v == [2, 4, 1, -5, -3] ||
+ v == [2, 4, 1, -3, -5] ||
+ v == [4, 2, 1, -5, -3] ||
+ v == [4, 2, 1, -3, -5]);Reorder the slice with a key extraction function such that the element at index after the
+reordering is at its final sorted position.
This reordering has the additional property that any value at position i < index will be
+less than or equal to any value at a position j > index using the key extraction function.
+Additionally, this reordering is unstable (i.e. any number of equal elements may end up at
+position index), in-place (i.e. does not allocate), and runs in O(n) time. This
+function is also known as “kth element” in other libraries.
It returns a triplet of the following from the slice reordered according to the provided key
+extraction function: the subslice prior to index, the element at index, and the subslice
+after index; accordingly, the values in those two subslices will respectively all be
+less-than-or-equal-to and greater-than-or-equal-to the value of the element at index.
The current algorithm is an introselect implementation based on ipnsort by Lukas Bergdoll
+and Orson Peters, which is also the basis for sort_unstable. The fallback algorithm is
+Median of Medians using Tukey’s Ninther for pivot selection, which guarantees linear runtime
+for all inputs.
It is typically faster than stable sorting, except in a few special cases, e.g., when the
+slice is nearly fully sorted, where slice::sort may be faster.
Panics when index >= len(), meaning it always panics on empty slices.
let mut v = [-5i32, 4, 1, -3, 2];
+
+// Find the items less than or equal to the median, the median, and greater than or equal to
+// the median as if the slice were sorted according to absolute value.
+let (lesser, median, greater) = v.select_nth_unstable_by_key(2, |a| a.abs());
+
+assert!(lesser == [1, 2] || lesser == [2, 1]);
+assert_eq!(median, &mut -3);
+assert!(greater == [4, -5] || greater == [-5, 4]);
+
+// We are only guaranteed the slice will be one of the following, based on the way we sort
+// about the specified index.
+assert!(v == [1, 2, -3, 4, -5] ||
+ v == [1, 2, -3, -5, 4] ||
+ v == [2, 1, -3, 4, -5] ||
+ v == [2, 1, -3, -5, 4]);slice_partition_dedup)Moves all consecutive repeated elements to the end of the slice according to the
+PartialEq trait implementation.
Returns two slices. The first contains no consecutive repeated elements. +The second contains all the duplicates in no specified order.
+If the slice is sorted, the first returned slice contains no duplicates.
+#![feature(slice_partition_dedup)]
+
+let mut slice = [1, 2, 2, 3, 3, 2, 1, 1];
+
+let (dedup, duplicates) = slice.partition_dedup();
+
+assert_eq!(dedup, [1, 2, 3, 2, 1]);
+assert_eq!(duplicates, [2, 3, 1]);slice_partition_dedup)Moves all but the first of consecutive elements to the end of the slice satisfying +a given equality relation.
+Returns two slices. The first contains no consecutive repeated elements. +The second contains all the duplicates in no specified order.
+The same_bucket function is passed references to two elements from the slice and
+must determine if the elements compare equal. The elements are passed in opposite order
+from their order in the slice, so if same_bucket(a, b) returns true, a is moved
+at the end of the slice.
If the slice is sorted, the first returned slice contains no duplicates.
+#![feature(slice_partition_dedup)]
+
+let mut slice = ["foo", "Foo", "BAZ", "Bar", "bar", "baz", "BAZ"];
+
+let (dedup, duplicates) = slice.partition_dedup_by(|a, b| a.eq_ignore_ascii_case(b));
+
+assert_eq!(dedup, ["foo", "BAZ", "Bar", "baz"]);
+assert_eq!(duplicates, ["bar", "Foo", "BAZ"]);slice_partition_dedup)Moves all but the first of consecutive elements to the end of the slice that resolve +to the same key.
+Returns two slices. The first contains no consecutive repeated elements. +The second contains all the duplicates in no specified order.
+If the slice is sorted, the first returned slice contains no duplicates.
+#![feature(slice_partition_dedup)]
+
+let mut slice = [10, 20, 21, 30, 30, 20, 11, 13];
+
+let (dedup, duplicates) = slice.partition_dedup_by_key(|i| *i / 10);
+
+assert_eq!(dedup, [10, 20, 30, 20, 11]);
+assert_eq!(duplicates, [21, 30, 13]);Rotates the slice in-place such that the first mid elements of the
+slice move to the end while the last self.len() - mid elements move to
+the front. After calling rotate_left, the element previously at index
+mid will become the first element in the slice.
This function will panic if mid is greater than the length of the
+slice. Note that mid == self.len() does not panic and is a no-op
+rotation.
Takes linear (in self.len()) time.
let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
+a.rotate_left(2);
+assert_eq!(a, ['c', 'd', 'e', 'f', 'a', 'b']);Rotating a subslice:
+ +let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
+a[1..5].rotate_left(1);
+assert_eq!(a, ['a', 'c', 'd', 'e', 'b', 'f']);Rotates the slice in-place such that the first self.len() - k
+elements of the slice move to the end while the last k elements move
+to the front. After calling rotate_right, the element previously at
+index self.len() - k will become the first element in the slice.
This function will panic if k is greater than the length of the
+slice. Note that k == self.len() does not panic and is a no-op
+rotation.
Takes linear (in self.len()) time.
let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
+a.rotate_right(2);
+assert_eq!(a, ['e', 'f', 'a', 'b', 'c', 'd']);Rotating a subslice:
+ +let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
+a[1..5].rotate_right(1);
+assert_eq!(a, ['a', 'e', 'b', 'c', 'd', 'f']);Fills self with elements by cloning value.
let mut buf = vec![0; 10];
+buf.fill(1);
+assert_eq!(buf, vec![1; 10]);Fills self with elements returned by calling a closure repeatedly.
This method uses a closure to create new values. If you’d rather
+Clone a given value, use fill. If you want to use the Default
+trait to generate values, you can pass Default::default as the
+argument.
let mut buf = vec![1; 10];
+buf.fill_with(Default::default);
+assert_eq!(buf, vec![0; 10]);Copies the elements from src into self.
The length of src must be the same as self.
This function will panic if the two slices have different lengths.
+Cloning two elements from a slice into another:
+ +let src = [1, 2, 3, 4];
+let mut dst = [0, 0];
+
+// Because the slices have to be the same length,
+// we slice the source slice from four elements
+// to two. It will panic if we don't do this.
+dst.clone_from_slice(&src[2..]);
+
+assert_eq!(src, [1, 2, 3, 4]);
+assert_eq!(dst, [3, 4]);Rust enforces that there can only be one mutable reference with no
+immutable references to a particular piece of data in a particular
+scope. Because of this, attempting to use clone_from_slice on a
+single slice will result in a compile failure:
let mut slice = [1, 2, 3, 4, 5];
+
+slice[..2].clone_from_slice(&slice[3..]); // compile fail!To work around this, we can use split_at_mut to create two distinct
+sub-slices from a slice:
let mut slice = [1, 2, 3, 4, 5];
+
+{
+ let (left, right) = slice.split_at_mut(2);
+ left.clone_from_slice(&right[1..]);
+}
+
+assert_eq!(slice, [4, 5, 3, 4, 5]);Copies all elements from src into self, using a memcpy.
The length of src must be the same as self.
If T does not implement Copy, use clone_from_slice.
This function will panic if the two slices have different lengths.
+Copying two elements from a slice into another:
+ +let src = [1, 2, 3, 4];
+let mut dst = [0, 0];
+
+// Because the slices have to be the same length,
+// we slice the source slice from four elements
+// to two. It will panic if we don't do this.
+dst.copy_from_slice(&src[2..]);
+
+assert_eq!(src, [1, 2, 3, 4]);
+assert_eq!(dst, [3, 4]);Rust enforces that there can only be one mutable reference with no
+immutable references to a particular piece of data in a particular
+scope. Because of this, attempting to use copy_from_slice on a
+single slice will result in a compile failure:
let mut slice = [1, 2, 3, 4, 5];
+
+slice[..2].copy_from_slice(&slice[3..]); // compile fail!To work around this, we can use split_at_mut to create two distinct
+sub-slices from a slice:
let mut slice = [1, 2, 3, 4, 5];
+
+{
+ let (left, right) = slice.split_at_mut(2);
+ left.copy_from_slice(&right[1..]);
+}
+
+assert_eq!(slice, [4, 5, 3, 4, 5]);Copies elements from one part of the slice to another part of itself, +using a memmove.
+src is the range within self to copy from. dest is the starting
+index of the range within self to copy to, which will have the same
+length as src. The two ranges may overlap. The ends of the two ranges
+must be less than or equal to self.len().
This function will panic if either range exceeds the end of the slice,
+or if the end of src is before the start.
Copying four bytes within a slice:
+ +let mut bytes = *b"Hello, World!";
+
+bytes.copy_within(1..5, 8);
+
+assert_eq!(&bytes, b"Hello, Wello!");Swaps all elements in self with those in other.
The length of other must be the same as self.
This function will panic if the two slices have different lengths.
+Swapping two elements across slices:
+ +let mut slice1 = [0, 0];
+let mut slice2 = [1, 2, 3, 4];
+
+slice1.swap_with_slice(&mut slice2[2..]);
+
+assert_eq!(slice1, [3, 4]);
+assert_eq!(slice2, [1, 2, 0, 0]);Rust enforces that there can only be one mutable reference to a
+particular piece of data in a particular scope. Because of this,
+attempting to use swap_with_slice on a single slice will result in
+a compile failure:
let mut slice = [1, 2, 3, 4, 5];
+slice[..2].swap_with_slice(&mut slice[3..]); // compile fail!To work around this, we can use split_at_mut to create two distinct
+mutable sub-slices from a slice:
let mut slice = [1, 2, 3, 4, 5];
+
+{
+ let (left, right) = slice.split_at_mut(2);
+ left.swap_with_slice(&mut right[1..]);
+}
+
+assert_eq!(slice, [4, 5, 3, 1, 2]);Transmute the slice to a slice of another type, ensuring alignment of the types is +maintained.
+This method splits the slice into three distinct slices: prefix, correctly aligned middle +slice of a new type, and the suffix slice. The middle part will be as big as possible under +the given alignment constraint and element size.
+This method has no purpose when either input element T or output element U are
+zero-sized and will return the original slice without splitting anything.
This method is essentially a transmute with respect to the elements in the returned
+middle slice, so all the usual caveats pertaining to transmute::<T, U> also apply here.
Basic usage:
+ +unsafe {
+ let bytes: [u8; 7] = [1, 2, 3, 4, 5, 6, 7];
+ let (prefix, shorts, suffix) = bytes.align_to::<u16>();
+ // less_efficient_algorithm_for_bytes(prefix);
+ // more_efficient_algorithm_for_aligned_shorts(shorts);
+ // less_efficient_algorithm_for_bytes(suffix);
+}Transmute the mutable slice to a mutable slice of another type, ensuring alignment of the +types is maintained.
+This method splits the slice into three distinct slices: prefix, correctly aligned middle +slice of a new type, and the suffix slice. The middle part will be as big as possible under +the given alignment constraint and element size.
+This method has no purpose when either input element T or output element U are
+zero-sized and will return the original slice without splitting anything.
This method is essentially a transmute with respect to the elements in the returned
+middle slice, so all the usual caveats pertaining to transmute::<T, U> also apply here.
Basic usage:
+ +unsafe {
+ let mut bytes: [u8; 7] = [1, 2, 3, 4, 5, 6, 7];
+ let (prefix, shorts, suffix) = bytes.align_to_mut::<u16>();
+ // less_efficient_algorithm_for_bytes(prefix);
+ // more_efficient_algorithm_for_aligned_shorts(shorts);
+ // less_efficient_algorithm_for_bytes(suffix);
+}portable_simd)Split a slice into a prefix, a middle of aligned SIMD types, and a suffix.
+This is a safe wrapper around slice::align_to, so has the same weak
+postconditions as that method. You’re only assured that
+self.len() == prefix.len() + middle.len() * LANES + suffix.len().
Notably, all of the following are possible:
+prefix.len() >= LANES.middle.is_empty() despite self.len() >= 3 * LANES.suffix.len() >= LANES.That said, this is a safe method, so if you’re only writing safe code, +then this can at most cause incorrect logic, not unsoundness.
+This will panic if the size of the SIMD type is different from
+LANES times that of the scalar.
At the time of writing, the trait restrictions on Simd<T, LANES> keeps
+that from ever happening, as only power-of-two numbers of lanes are
+supported. It’s possible that, in the future, those restrictions might
+be lifted in a way that would make it possible to see panics from this
+method for something like LANES == 3.
#![feature(portable_simd)]
+use core::simd::prelude::*;
+
+let short = &[1, 2, 3];
+let (prefix, middle, suffix) = short.as_simd::<4>();
+assert_eq!(middle, []); // Not enough elements for anything in the middle
+
+// They might be split in any possible way between prefix and suffix
+let it = prefix.iter().chain(suffix).copied();
+assert_eq!(it.collect::<Vec<_>>(), vec![1, 2, 3]);
+
+fn basic_simd_sum(x: &[f32]) -> f32 {
+ use std::ops::Add;
+ let (prefix, middle, suffix) = x.as_simd();
+ let sums = f32x4::from_array([
+ prefix.iter().copied().sum(),
+ 0.0,
+ 0.0,
+ suffix.iter().copied().sum(),
+ ]);
+ let sums = middle.iter().copied().fold(sums, f32x4::add);
+ sums.reduce_sum()
+}
+
+let numbers: Vec<f32> = (1..101).map(|x| x as _).collect();
+assert_eq!(basic_simd_sum(&numbers[1..99]), 4949.0);portable_simd)Split a mutable slice into a mutable prefix, a middle of aligned SIMD types, +and a mutable suffix.
+This is a safe wrapper around slice::align_to_mut, so has the same weak
+postconditions as that method. You’re only assured that
+self.len() == prefix.len() + middle.len() * LANES + suffix.len().
Notably, all of the following are possible:
+prefix.len() >= LANES.middle.is_empty() despite self.len() >= 3 * LANES.suffix.len() >= LANES.That said, this is a safe method, so if you’re only writing safe code, +then this can at most cause incorrect logic, not unsoundness.
+This is the mutable version of slice::as_simd; see that for examples.
This will panic if the size of the SIMD type is different from
+LANES times that of the scalar.
At the time of writing, the trait restrictions on Simd<T, LANES> keeps
+that from ever happening, as only power-of-two numbers of lanes are
+supported. It’s possible that, in the future, those restrictions might
+be lifted in a way that would make it possible to see panics from this
+method for something like LANES == 3.
is_sorted)Checks if the elements of this slice are sorted.
+That is, for each element a and its following element b, a <= b must hold. If the
+slice yields exactly zero or one element, true is returned.
Note that if Self::Item is only PartialOrd, but not Ord, the above definition
+implies that this function returns false if any two consecutive items are not
+comparable.
#![feature(is_sorted)]
+let empty: [i32; 0] = [];
+
+assert!([1, 2, 2, 9].is_sorted());
+assert!(![1, 3, 2, 4].is_sorted());
+assert!([0].is_sorted());
+assert!(empty.is_sorted());
+assert!(![0.0, 1.0, f32::NAN].is_sorted());is_sorted)Checks if the elements of this slice are sorted using the given comparator function.
+Instead of using PartialOrd::partial_cmp, this function uses the given compare
+function to determine whether two elements are to be considered in sorted order.
#![feature(is_sorted)]
+
+assert!([1, 2, 2, 9].is_sorted_by(|a, b| a <= b));
+assert!(![1, 2, 2, 9].is_sorted_by(|a, b| a < b));
+
+assert!([0].is_sorted_by(|a, b| true));
+assert!([0].is_sorted_by(|a, b| false));
+
+let empty: [i32; 0] = [];
+assert!(empty.is_sorted_by(|a, b| false));
+assert!(empty.is_sorted_by(|a, b| true));is_sorted)Checks if the elements of this slice are sorted using the given key extraction function.
+Instead of comparing the slice’s elements directly, this function compares the keys of the
+elements, as determined by f. Apart from that, it’s equivalent to is_sorted; see its
+documentation for more information.
#![feature(is_sorted)]
+
+assert!(["c", "bb", "aaa"].is_sorted_by_key(|s| s.len()));
+assert!(![-2i32, -1, 0, 3].is_sorted_by_key(|n| n.abs()));Returns the index of the partition point according to the given predicate +(the index of the first element of the second partition).
+The slice is assumed to be partitioned according to the given predicate.
+This means that all elements for which the predicate returns true are at the start of the slice
+and all elements for which the predicate returns false are at the end.
+For example, [7, 15, 3, 5, 4, 12, 6] is partitioned under the predicate x % 2 != 0
+(all odd numbers are at the start, all even at the end).
If this slice is not partitioned, the returned result is unspecified and meaningless, +as this method performs a kind of binary search.
+See also binary_search, binary_search_by, and binary_search_by_key.
let v = [1, 2, 3, 3, 5, 6, 7];
+let i = v.partition_point(|&x| x < 5);
+
+assert_eq!(i, 4);
+assert!(v[..i].iter().all(|&x| x < 5));
+assert!(v[i..].iter().all(|&x| !(x < 5)));If all elements of the slice match the predicate, including if the slice +is empty, then the length of the slice will be returned:
+ +let a = [2, 4, 8];
+assert_eq!(a.partition_point(|x| x < &100), a.len());
+let a: [i32; 0] = [];
+assert_eq!(a.partition_point(|x| x < &100), 0);If you want to insert an item to a sorted vector, while maintaining +sort order:
+ +let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+let num = 42;
+let idx = s.partition_point(|&x| x <= num);
+s.insert(idx, num);
+assert_eq!(s, [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]);slice_take)Removes the subslice corresponding to the given range +and returns a reference to it.
+Returns None and does not modify the slice if the given
+range is out of bounds.
Note that this method only accepts one-sided ranges such as
+2.. or ..6, but not 2..6.
Taking the first three elements of a slice:
+ +#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c', 'd'];
+let mut first_three = slice.take(..3).unwrap();
+
+assert_eq!(slice, &['d']);
+assert_eq!(first_three, &['a', 'b', 'c']);Taking the last two elements of a slice:
+ +#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c', 'd'];
+let mut tail = slice.take(2..).unwrap();
+
+assert_eq!(slice, &['a', 'b']);
+assert_eq!(tail, &['c', 'd']);Getting None when range is out of bounds:
#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c', 'd'];
+
+assert_eq!(None, slice.take(5..));
+assert_eq!(None, slice.take(..5));
+assert_eq!(None, slice.take(..=4));
+let expected: &[char] = &['a', 'b', 'c', 'd'];
+assert_eq!(Some(expected), slice.take(..4));slice_take)Removes the subslice corresponding to the given range +and returns a mutable reference to it.
+Returns None and does not modify the slice if the given
+range is out of bounds.
Note that this method only accepts one-sided ranges such as
+2.. or ..6, but not 2..6.
Taking the first three elements of a slice:
+ +#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd'];
+let mut first_three = slice.take_mut(..3).unwrap();
+
+assert_eq!(slice, &mut ['d']);
+assert_eq!(first_three, &mut ['a', 'b', 'c']);Taking the last two elements of a slice:
+ +#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd'];
+let mut tail = slice.take_mut(2..).unwrap();
+
+assert_eq!(slice, &mut ['a', 'b']);
+assert_eq!(tail, &mut ['c', 'd']);Getting None when range is out of bounds:
#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd'];
+
+assert_eq!(None, slice.take_mut(5..));
+assert_eq!(None, slice.take_mut(..5));
+assert_eq!(None, slice.take_mut(..=4));
+let expected: &mut [_] = &mut ['a', 'b', 'c', 'd'];
+assert_eq!(Some(expected), slice.take_mut(..4));slice_take)Removes the first element of the slice and returns a reference +to it.
+Returns None if the slice is empty.
#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c'];
+let first = slice.take_first().unwrap();
+
+assert_eq!(slice, &['b', 'c']);
+assert_eq!(first, &'a');slice_take)Removes the first element of the slice and returns a mutable +reference to it.
+Returns None if the slice is empty.
#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c'];
+let first = slice.take_first_mut().unwrap();
+*first = 'd';
+
+assert_eq!(slice, &['b', 'c']);
+assert_eq!(first, &'d');slice_take)Removes the last element of the slice and returns a reference +to it.
+Returns None if the slice is empty.
#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c'];
+let last = slice.take_last().unwrap();
+
+assert_eq!(slice, &['a', 'b']);
+assert_eq!(last, &'c');slice_take)Removes the last element of the slice and returns a mutable +reference to it.
+Returns None if the slice is empty.
#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c'];
+let last = slice.take_last_mut().unwrap();
+*last = 'd';
+
+assert_eq!(slice, &['a', 'b']);
+assert_eq!(last, &'d');get_many_mut)Returns mutable references to many indices at once, without doing any checks.
+For a safe alternative see get_many_mut.
Calling this method with overlapping or out-of-bounds indices is undefined behavior +even if the resulting references are not used.
+#![feature(get_many_mut)]
+
+let x = &mut [1, 2, 4];
+
+unsafe {
+ let [a, b] = x.get_many_unchecked_mut([0, 2]);
+ *a *= 10;
+ *b *= 100;
+}
+assert_eq!(x, &[10, 2, 400]);get_many_mut)Returns mutable references to many indices at once.
+Returns an error if any index is out-of-bounds, or if the same index was +passed more than once.
+#![feature(get_many_mut)]
+
+let v = &mut [1, 2, 3];
+if let Ok([a, b]) = v.get_many_mut([0, 2]) {
+ *a = 413;
+ *b = 612;
+}
+assert_eq!(v, &[413, 2, 612]);Sorts the slice, preserving initial order of equal elements.
+This sort is stable (i.e., does not reorder equal elements) and O(n * log(n)) +worst-case.
+If T: Ord does not implement a total order the resulting order is unspecified. All
+original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if T: Ord panics.
When applicable, unstable sorting is preferred because it is generally faster than stable
+sorting and it doesn’t allocate auxiliary memory. See
+sort_unstable. The exception are partially sorted slices, which
+may be better served with slice::sort.
The current implementation is based on driftsort by Orson Peters and Lukas Bergdoll, which +combines the fast average case of quicksort with the fast worst case and partial run +detection of mergesort, achieving linear time on fully sorted and reversed inputs. On inputs +with k distinct elements, the expected time to sort the data is O(n * log(k)).
+The auxiliary memory allocation behavior depends on the input length. Short slices are
+handled without allocation, medium sized slices allocate self.len() and beyond that it
+clamps at self.len() / 2.
If T: Ord does not implement a total order, the implementation may panic.
let mut v = [-5, 4, 1, -3, 2];
+
+v.sort();
+assert!(v == [-5, -3, 1, 2, 4]);Sorts the slice with a comparator function, preserving initial order of equal elements.
+This sort is stable (i.e., does not reorder equal elements) and O(n * log(n)) +worst-case.
+The comparator function should define a total ordering for the elements in the slice. If the +ordering is not total, the order of the elements is unspecified.
+If the comparator function does not implement a total order the resulting order is
+unspecified. All original elements will remain in the slice and any possible modifications
+via interior mutability are observed in the input. Same is true if the comparator function
+panics. A total order (for all a, b and c):
a < b, a == b or a > b is true, anda < b and b < c implies a < c. The same must hold for both == and >.For example, while f64 doesn’t implement Ord because NaN != NaN, we can use
+partial_cmp as our sort function when we know the slice doesn’t contain a NaN.
let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
+floats.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap());
+assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);The current implementation is based on driftsort by Orson Peters and Lukas Bergdoll, which +combines the fast average case of quicksort with the fast worst case and partial run +detection of mergesort, achieving linear time on fully sorted and reversed inputs. On inputs +with k distinct elements, the expected time to sort the data is O(n * log(k)).
+The auxiliary memory allocation behavior depends on the input length. Short slices are
+handled without allocation, medium sized slices allocate self.len() and beyond that it
+clamps at self.len() / 2.
If T: Ord does not implement a total order, the implementation may panic.
let mut v = [5, 4, 1, 3, 2];
+v.sort_by(|a, b| a.cmp(b));
+assert!(v == [1, 2, 3, 4, 5]);
+
+// reverse sorting
+v.sort_by(|a, b| b.cmp(a));
+assert!(v == [5, 4, 3, 2, 1]);Sorts the slice with a key extraction function, preserving initial order of equal elements.
+This sort is stable (i.e., does not reorder equal elements) and O(m * n * log(n)) +worst-case, where the key function is O(m).
+If K: Ord does not implement a total order the resulting order is unspecified.
+All original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if K: Ord panics.
The current implementation is based on driftsort by Orson Peters and Lukas Bergdoll, which +combines the fast average case of quicksort with the fast worst case and partial run +detection of mergesort, achieving linear time on fully sorted and reversed inputs. On inputs +with k distinct elements, the expected time to sort the data is O(n * log(k)).
+The auxiliary memory allocation behavior depends on the input length. Short slices are
+handled without allocation, medium sized slices allocate self.len() and beyond that it
+clamps at self.len() / 2.
If K: Ord does not implement a total order, the implementation may panic.
let mut v = [-5i32, 4, 1, -3, 2];
+
+v.sort_by_key(|k| k.abs());
+assert!(v == [1, 2, -3, 4, -5]);Sorts the slice with a key extraction function, preserving initial order of equal elements.
+This sort is stable (i.e., does not reorder equal elements) and O(m * n + n * +log(n)) worst-case, where the key function is O(m).
+During sorting, the key function is called at most once per element, by using temporary +storage to remember the results of key evaluation. The order of calls to the key function is +unspecified and may change in future versions of the standard library.
+If K: Ord does not implement a total order the resulting order is unspecified.
+All original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if K: Ord panics.
For simple key functions (e.g., functions that are property accesses or basic operations),
+sort_by_key is likely to be faster.
The current implementation is based on instruction-parallel-network sort by Lukas +Bergdoll, which combines the fast average case of randomized quicksort with the fast worst +case of heapsort, while achieving linear time on fully sorted and reversed inputs. And +O(k * log(n)) where k is the number of distinct elements in the input. It leverages +superscalar out-of-order execution capabilities commonly found in CPUs, to efficiently +perform the operation.
+In the worst case, the algorithm allocates temporary storage in a Vec<(K, usize)> the
+length of the slice.
let mut v = [-5i32, 4, 32, -3, 2];
+
+v.sort_by_cached_key(|k| k.to_string());
+assert!(v == [-3, -5, 2, 32, 4]);Copies self into a new Vec.
let s = [10, 40, 30];
+let x = s.to_vec();
+// Here, `s` and `x` can be modified independently.allocator_api)Copies self into a new Vec with an allocator.
#![feature(allocator_api)]
+
+use std::alloc::System;
+
+let s = [10, 40, 30];
+let x = s.to_vec_in(System);
+// Here, `s` and `x` can be modified independently.Flattens a slice of T into a single value Self::Output.
assert_eq!(["hello", "world"].concat(), "helloworld");
+assert_eq!([[1, 2], [3, 4]].concat(), [1, 2, 3, 4]);Flattens a slice of T into a single value Self::Output, placing a
+given separator between each.
assert_eq!(["hello", "world"].join(" "), "hello world");
+assert_eq!([[1, 2], [3, 4]].join(&0), [1, 2, 0, 3, 4]);
+assert_eq!([[1, 2], [3, 4]].join(&[0, 0][..]), [1, 2, 0, 0, 3, 4]);Flattens a slice of T into a single value Self::Output, placing a
+given separator between each.
assert_eq!(["hello", "world"].connect(" "), "hello world");
+assert_eq!([[1, 2], [3, 4]].connect(&0), [1, 2, 0, 3, 4]);Returns a vector containing a copy of this slice where each byte +is mapped to its ASCII upper case equivalent.
+ASCII letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’, +but non-ASCII letters are unchanged.
+To uppercase the value in-place, use make_ascii_uppercase.
Returns a vector containing a copy of this slice where each byte +is mapped to its ASCII lower case equivalent.
+ASCII letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’, +but non-ASCII letters are unchanged.
+To lowercase the value in-place, use make_ascii_lowercase.
try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub struct Root {
+ pub namespace: Namespace,
+ pub version: u64,
+ pub root_type: RootType,
+ pub hash: Hash,
+}Storage root.
+namespace: NamespaceNamespace under which the root is stored.
+version: u64Monotonically increasing version number in which the root is stored.
+root_type: RootTypeThe storage type that this root has data for.
+hash: HashMerkle root hash.
+try_default in case the value is null or
+undefined.clone_to_uninit)clone_to_uninit)key and return true if they are equal.pub struct Tree { /* private fields */ }A patricia tree-based MKVS implementation.
+pub enum SyncerError {
+ Unsupported,
+}Redirecting to ../../../../../oasis_core_runtime/storage/mkvs/sync/enum.SyncerError.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/sync/fn.merge_verified_subtree.html b/rust/oasis_core_runtime/storage/mkvs/sync/fn.merge_verified_subtree.html new file mode 100644 index 0000000000..f9ca300947 --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/sync/fn.merge_verified_subtree.html @@ -0,0 +1,6 @@ +pub fn merge_verified_subtree(
+ dst: NodePtrRef,
+ subtree: NodePtrRef,
+ updater: &mut Vec<NodePtrRef>,
+) -> Result<()>Merges a previously verified subtree with an existing tree.
+Redirecting to ../../../../../oasis_core_runtime/storage/mkvs/sync/struct.HostReadSyncer.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/sync/index.html b/rust/oasis_core_runtime/storage/mkvs/sync/index.html new file mode 100644 index 0000000000..0a202c015d --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/sync/index.html @@ -0,0 +1,3 @@ +The read-only tree sync interface.
+Redirecting to ../../../../../oasis_core_runtime/storage/mkvs/sync/fn.merge_verified_subtree.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/sync/noop/struct.NoopReadSyncer.html b/rust/oasis_core_runtime/storage/mkvs/sync/noop/struct.NoopReadSyncer.html new file mode 100644 index 0000000000..aabaa85277 --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/sync/noop/struct.NoopReadSyncer.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/storage/mkvs/sync/struct.NoopReadSyncer.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/sync/proof/struct.Proof.html b/rust/oasis_core_runtime/storage/mkvs/sync/proof/struct.Proof.html new file mode 100644 index 0000000000..93e90f31e0 --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/sync/proof/struct.Proof.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/storage/mkvs/sync/struct.Proof.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/sync/proof/struct.ProofBuilder.html b/rust/oasis_core_runtime/storage/mkvs/sync/proof/struct.ProofBuilder.html new file mode 100644 index 0000000000..7bfd857a82 --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/sync/proof/struct.ProofBuilder.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/storage/mkvs/sync/struct.ProofBuilder.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/sync/proof/struct.ProofVerifier.html b/rust/oasis_core_runtime/storage/mkvs/sync/proof/struct.ProofVerifier.html new file mode 100644 index 0000000000..14e5185a03 --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/sync/proof/struct.ProofVerifier.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/storage/mkvs/sync/struct.ProofVerifier.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/sync/proof/struct.RawProofEntry.html b/rust/oasis_core_runtime/storage/mkvs/sync/proof/struct.RawProofEntry.html new file mode 100644 index 0000000000..1645aec26c --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/sync/proof/struct.RawProofEntry.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/storage/mkvs/sync/struct.RawProofEntry.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/sync/sidebar-items.js b/rust/oasis_core_runtime/storage/mkvs/sync/sidebar-items.js new file mode 100644 index 0000000000..a4e6f85f74 --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/sync/sidebar-items.js @@ -0,0 +1 @@ +window.SIDEBAR_ITEMS = {"enum":["SyncerError"],"fn":["merge_verified_subtree"],"struct":["GetPrefixesRequest","GetRequest","HostReadSyncer","IterateRequest","NoopReadSyncer","Proof","ProofBuilder","ProofResponse","ProofVerifier","RawProofEntry","StatsCollector","TreeID"],"trait":["ReadSync"]}; \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/sync/stats/struct.StatsCollector.html b/rust/oasis_core_runtime/storage/mkvs/sync/stats/struct.StatsCollector.html new file mode 100644 index 0000000000..e9ea97b182 --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/sync/stats/struct.StatsCollector.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/storage/mkvs/sync/struct.StatsCollector.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/sync/struct.GetPrefixesRequest.html b/rust/oasis_core_runtime/storage/mkvs/sync/struct.GetPrefixesRequest.html new file mode 100644 index 0000000000..5c1c3a5b9d --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/sync/struct.GetPrefixesRequest.html @@ -0,0 +1,31 @@ +pub struct GetPrefixesRequest {
+ pub tree: TreeID,
+ pub prefixes: Vec<Prefix>,
+ pub limit: u16,
+}Request for the SyncGetPrefixes operation.
+tree: TreeID§prefixes: Vec<Prefix>§limit: u16source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct GetRequest {
+ pub tree: TreeID,
+ pub key: Vec<u8>,
+ pub include_siblings: bool,
+}Request for the SyncGet operation.
+tree: TreeID§key: Vec<u8>§include_siblings: boolsource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct HostReadSyncer { /* private fields */ }A proxy read syncer which forwards calls to the runtime host.
+Construct a new host proxy instance.
+pub struct IterateRequest {
+ pub tree: TreeID,
+ pub key: Vec<u8>,
+ pub prefetch: u16,
+}Request for the SyncIterate operation.
+tree: TreeID§key: Vec<u8>§prefetch: u16source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct NoopReadSyncer;A no-op read syncer which doesn’t support any of the required operations.
+pub struct Proof {
+ pub v: u16,
+ pub untrusted_root: Hash,
+ pub entries: Vec<Option<RawProofEntry>>,
+}A Merkle proof for a subtree.
+v: u16§untrusted_root: HashThe root hash this proof is for. This should only be used as a quick +sanity check and proof verification MUST use an independently obtained +root hash as the prover can provide any root.
+entries: Vec<Option<RawProofEntry>>Proof entries in pre-order traversal.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct ProofBuilder { /* private fields */ }A Merkle proof builder.
+pub struct ProofResponse {
+ pub proof: Proof,
+}Response for requests that produce proofs.
+proof: Proofsource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct ProofVerifier;A proof verifier enables verifying proofs returned by the ReadSyncer API.
+Verify a proof and generate an in-memory subtree representing the +nodes which are included in the proof.
+pub struct RawProofEntry(pub Vec<u8>);A raw proof entry.
+0: Vec<u8>Returns the total number of elements the vector can hold without +reallocating.
+let mut vec: Vec<i32> = Vec::with_capacity(10);
+vec.push(42);
+assert!(vec.capacity() >= 10);Reserves capacity for at least additional more elements to be inserted
+in the given Vec<T>. The collection may reserve more space to
+speculatively avoid frequent reallocations. After calling reserve,
+capacity will be greater than or equal to self.len() + additional.
+Does nothing if capacity is already sufficient.
Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1];
+vec.reserve(10);
+assert!(vec.capacity() >= 11);Reserves the minimum capacity for at least additional more elements to
+be inserted in the given Vec<T>. Unlike reserve, this will not
+deliberately over-allocate to speculatively avoid frequent allocations.
+After calling reserve_exact, capacity will be greater than or equal to
+self.len() + additional. Does nothing if the capacity is already
+sufficient.
Note that the allocator may give the collection more space than it
+requests. Therefore, capacity can not be relied upon to be precisely
+minimal. Prefer reserve if future insertions are expected.
Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1];
+vec.reserve_exact(10);
+assert!(vec.capacity() >= 11);Tries to reserve capacity for at least additional more elements to be inserted
+in the given Vec<T>. The collection may reserve more space to speculatively avoid
+frequent reallocations. After calling try_reserve, capacity will be
+greater than or equal to self.len() + additional if it returns
+Ok(()). Does nothing if capacity is already sufficient. This method
+preserves the contents even if an error occurs.
If the capacity overflows, or the allocator reports a failure, then an error +is returned.
+use std::collections::TryReserveError;
+
+fn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {
+ let mut output = Vec::new();
+
+ // Pre-reserve the memory, exiting if we can't
+ output.try_reserve(data.len())?;
+
+ // Now we know this can't OOM in the middle of our complex work
+ output.extend(data.iter().map(|&val| {
+ val * 2 + 5 // very complicated
+ }));
+
+ Ok(output)
+}Tries to reserve the minimum capacity for at least additional
+elements to be inserted in the given Vec<T>. Unlike try_reserve,
+this will not deliberately over-allocate to speculatively avoid frequent
+allocations. After calling try_reserve_exact, capacity will be greater
+than or equal to self.len() + additional if it returns Ok(()).
+Does nothing if the capacity is already sufficient.
Note that the allocator may give the collection more space than it
+requests. Therefore, capacity can not be relied upon to be precisely
+minimal. Prefer try_reserve if future insertions are expected.
If the capacity overflows, or the allocator reports a failure, then an error +is returned.
+use std::collections::TryReserveError;
+
+fn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {
+ let mut output = Vec::new();
+
+ // Pre-reserve the memory, exiting if we can't
+ output.try_reserve_exact(data.len())?;
+
+ // Now we know this can't OOM in the middle of our complex work
+ output.extend(data.iter().map(|&val| {
+ val * 2 + 5 // very complicated
+ }));
+
+ Ok(output)
+}Shrinks the capacity of the vector as much as possible.
+The behavior of this method depends on the allocator, which may either shrink the vector
+in-place or reallocate. The resulting vector might still have some excess capacity, just as
+is the case for with_capacity. See Allocator::shrink for more details.
let mut vec = Vec::with_capacity(10);
+vec.extend([1, 2, 3]);
+assert!(vec.capacity() >= 10);
+vec.shrink_to_fit();
+assert!(vec.capacity() >= 3);Shrinks the capacity of the vector with a lower bound.
+The capacity will remain at least as large as both the length +and the supplied value.
+If the current capacity is less than the lower limit, this is a no-op.
+let mut vec = Vec::with_capacity(10);
+vec.extend([1, 2, 3]);
+assert!(vec.capacity() >= 10);
+vec.shrink_to(4);
+assert!(vec.capacity() >= 4);
+vec.shrink_to(0);
+assert!(vec.capacity() >= 3);Shortens the vector, keeping the first len elements and dropping
+the rest.
If len is greater or equal to the vector’s current length, this has
+no effect.
The drain method can emulate truncate, but causes the excess
+elements to be returned instead of dropped.
Note that this method has no effect on the allocated capacity +of the vector.
+Truncating a five element vector to two elements:
+ +let mut vec = vec![1, 2, 3, 4, 5];
+vec.truncate(2);
+assert_eq!(vec, [1, 2]);No truncation occurs when len is greater than the vector’s current
+length:
let mut vec = vec![1, 2, 3];
+vec.truncate(8);
+assert_eq!(vec, [1, 2, 3]);Truncating when len == 0 is equivalent to calling the clear
+method.
let mut vec = vec![1, 2, 3];
+vec.truncate(0);
+assert_eq!(vec, []);Extracts a slice containing the entire vector.
+Equivalent to &s[..].
use std::io::{self, Write};
+let buffer = vec![1, 2, 3, 5, 8];
+io::sink().write(buffer.as_slice()).unwrap();Extracts a mutable slice of the entire vector.
+Equivalent to &mut s[..].
use std::io::{self, Read};
+let mut buffer = vec![0; 3];
+io::repeat(0b101).read_exact(buffer.as_mut_slice()).unwrap();Returns a raw pointer to the vector’s buffer, or a dangling raw pointer +valid for zero sized reads if the vector didn’t allocate.
+The caller must ensure that the vector outlives the pointer this +function returns, or else it will end up pointing to garbage. +Modifying the vector may cause its buffer to be reallocated, +which would also make any pointers to it invalid.
+The caller must also ensure that the memory the pointer (non-transitively) points to
+is never written to (except inside an UnsafeCell) using this pointer or any pointer
+derived from it. If you need to mutate the contents of the slice, use as_mut_ptr.
This method guarantees that for the purpose of the aliasing model, this method
+does not materialize a reference to the underlying slice, and thus the returned pointer
+will remain valid when mixed with other calls to as_ptr and as_mut_ptr.
+Note that calling other methods that materialize mutable references to the slice,
+or mutable references to specific elements you are planning on accessing through this pointer,
+as well as writing to those elements, may still invalidate this pointer.
+See the second example below for how this guarantee can be used.
let x = vec![1, 2, 4];
+let x_ptr = x.as_ptr();
+
+unsafe {
+ for i in 0..x.len() {
+ assert_eq!(*x_ptr.add(i), 1 << i);
+ }
+}Due to the aliasing guarantee, the following code is legal:
+ +unsafe {
+ let mut v = vec![0, 1, 2];
+ let ptr1 = v.as_ptr();
+ let _ = ptr1.read();
+ let ptr2 = v.as_mut_ptr().offset(2);
+ ptr2.write(2);
+ // Notably, the write to `ptr2` did *not* invalidate `ptr1`
+ // because it mutated a different element:
+ let _ = ptr1.read();
+}Returns an unsafe mutable pointer to the vector’s buffer, or a dangling +raw pointer valid for zero sized reads if the vector didn’t allocate.
+The caller must ensure that the vector outlives the pointer this +function returns, or else it will end up pointing to garbage. +Modifying the vector may cause its buffer to be reallocated, +which would also make any pointers to it invalid.
+This method guarantees that for the purpose of the aliasing model, this method
+does not materialize a reference to the underlying slice, and thus the returned pointer
+will remain valid when mixed with other calls to as_ptr and as_mut_ptr.
+Note that calling other methods that materialize references to the slice,
+or references to specific elements you are planning on accessing through this pointer,
+may still invalidate this pointer.
+See the second example below for how this guarantee can be used.
// Allocate vector big enough for 4 elements.
+let size = 4;
+let mut x: Vec<i32> = Vec::with_capacity(size);
+let x_ptr = x.as_mut_ptr();
+
+// Initialize elements via raw pointer writes, then set length.
+unsafe {
+ for i in 0..size {
+ *x_ptr.add(i) = i as i32;
+ }
+ x.set_len(size);
+}
+assert_eq!(&*x, &[0, 1, 2, 3]);Due to the aliasing guarantee, the following code is legal:
+ +unsafe {
+ let mut v = vec![0];
+ let ptr1 = v.as_mut_ptr();
+ ptr1.write(1);
+ let ptr2 = v.as_mut_ptr();
+ ptr2.write(2);
+ // Notably, the write to `ptr2` did *not* invalidate `ptr1`:
+ ptr1.write(3);
+}allocator_api)Returns a reference to the underlying allocator.
+Forces the length of the vector to new_len.
This is a low-level operation that maintains none of the normal
+invariants of the type. Normally changing the length of a vector
+is done using one of the safe operations instead, such as
+truncate, resize, extend, or clear.
new_len must be less than or equal to capacity().old_len..new_len must be initialized.This method can be useful for situations in which the vector +is serving as a buffer for other code, particularly over FFI:
+ +pub fn get_dictionary(&self) -> Option<Vec<u8>> {
+ // Per the FFI method's docs, "32768 bytes is always enough".
+ let mut dict = Vec::with_capacity(32_768);
+ let mut dict_length = 0;
+ // SAFETY: When `deflateGetDictionary` returns `Z_OK`, it holds that:
+ // 1. `dict_length` elements were initialized.
+ // 2. `dict_length` <= the capacity (32_768)
+ // which makes `set_len` safe to call.
+ unsafe {
+ // Make the FFI call...
+ let r = deflateGetDictionary(self.strm, dict.as_mut_ptr(), &mut dict_length);
+ if r == Z_OK {
+ // ...and update the length to what was initialized.
+ dict.set_len(dict_length);
+ Some(dict)
+ } else {
+ None
+ }
+ }
+}While the following example is sound, there is a memory leak since
+the inner vectors were not freed prior to the set_len call:
let mut vec = vec![vec![1, 0, 0],
+ vec![0, 1, 0],
+ vec![0, 0, 1]];
+// SAFETY:
+// 1. `old_len..0` is empty so no elements need to be initialized.
+// 2. `0 <= capacity` always holds whatever `capacity` is.
+unsafe {
+ vec.set_len(0);
+}Normally, here, one would use clear instead to correctly drop
+the contents and thus not leak memory.
Removes an element from the vector and returns it.
+The removed element is replaced by the last element of the vector.
+This does not preserve ordering of the remaining elements, but is O(1).
+If you need to preserve the element order, use remove instead.
Panics if index is out of bounds.
let mut v = vec!["foo", "bar", "baz", "qux"];
+
+assert_eq!(v.swap_remove(1), "bar");
+assert_eq!(v, ["foo", "qux", "baz"]);
+
+assert_eq!(v.swap_remove(0), "foo");
+assert_eq!(v, ["baz", "qux"]);Inserts an element at position index within the vector, shifting all
+elements after it to the right.
Panics if index > len.
let mut vec = vec![1, 2, 3];
+vec.insert(1, 4);
+assert_eq!(vec, [1, 4, 2, 3]);
+vec.insert(4, 5);
+assert_eq!(vec, [1, 4, 2, 3, 5]);Takes O(Vec::len) time. All items after the insertion index must be
+shifted to the right. In the worst case, all elements are shifted when
+the insertion index is 0.
Removes and returns the element at position index within the vector,
+shifting all elements after it to the left.
Note: Because this shifts over the remaining elements, it has a
+worst-case performance of O(n). If you don’t need the order of elements
+to be preserved, use swap_remove instead. If you’d like to remove
+elements from the beginning of the Vec, consider using
+VecDeque::pop_front instead.
Panics if index is out of bounds.
let mut v = vec![1, 2, 3];
+assert_eq!(v.remove(1), 2);
+assert_eq!(v, [1, 3]);Retains only the elements specified by the predicate.
+In other words, remove all elements e for which f(&e) returns false.
+This method operates in place, visiting each element exactly once in the
+original order, and preserves the order of the retained elements.
let mut vec = vec![1, 2, 3, 4];
+vec.retain(|&x| x % 2 == 0);
+assert_eq!(vec, [2, 4]);Because the elements are visited exactly once in the original order, +external state may be used to decide which elements to keep.
+ +let mut vec = vec![1, 2, 3, 4, 5];
+let keep = [false, true, true, false, true];
+let mut iter = keep.iter();
+vec.retain(|_| *iter.next().unwrap());
+assert_eq!(vec, [2, 3, 5]);Retains only the elements specified by the predicate, passing a mutable reference to it.
+In other words, remove all elements e such that f(&mut e) returns false.
+This method operates in place, visiting each element exactly once in the
+original order, and preserves the order of the retained elements.
let mut vec = vec![1, 2, 3, 4];
+vec.retain_mut(|x| if *x <= 3 {
+ *x += 1;
+ true
+} else {
+ false
+});
+assert_eq!(vec, [2, 3, 4]);Removes all but the first of consecutive elements in the vector that resolve to the same +key.
+If the vector is sorted, this removes all duplicates.
+let mut vec = vec![10, 20, 21, 30, 20];
+
+vec.dedup_by_key(|i| *i / 10);
+
+assert_eq!(vec, [10, 20, 30, 20]);Removes all but the first of consecutive elements in the vector satisfying a given equality +relation.
+The same_bucket function is passed references to two elements from the vector and
+must determine if the elements compare equal. The elements are passed in opposite order
+from their order in the slice, so if same_bucket(a, b) returns true, a is removed.
If the vector is sorted, this removes all duplicates.
+let mut vec = vec!["foo", "bar", "Bar", "baz", "bar"];
+
+vec.dedup_by(|a, b| a.eq_ignore_ascii_case(b));
+
+assert_eq!(vec, ["foo", "bar", "baz", "bar"]);Appends an element to the back of a collection.
+Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1, 2];
+vec.push(3);
+assert_eq!(vec, [1, 2, 3]);Takes amortized O(1) time. If the vector’s length would exceed its +capacity after the push, O(capacity) time is taken to copy the +vector’s elements to a larger allocation. This expensive operation is +offset by the capacity O(1) insertions it allows.
+vec_push_within_capacity)Appends an element if there is sufficient spare capacity, otherwise an error is returned +with the element.
+Unlike push this method will not reallocate when there’s insufficient capacity.
+The caller should use reserve or try_reserve to ensure that there is enough capacity.
A manual, panic-free alternative to FromIterator:
#![feature(vec_push_within_capacity)]
+
+use std::collections::TryReserveError;
+fn from_iter_fallible<T>(iter: impl Iterator<Item=T>) -> Result<Vec<T>, TryReserveError> {
+ let mut vec = Vec::new();
+ for value in iter {
+ if let Err(value) = vec.push_within_capacity(value) {
+ vec.try_reserve(1)?;
+ // this cannot fail, the previous line either returned or added at least 1 free slot
+ let _ = vec.push_within_capacity(value);
+ }
+ }
+ Ok(vec)
+}
+assert_eq!(from_iter_fallible(0..100), Ok(Vec::from_iter(0..100)));Takes O(1) time.
+Removes the last element from a vector and returns it, or None if it
+is empty.
If you’d like to pop the first element, consider using
+VecDeque::pop_front instead.
let mut vec = vec![1, 2, 3];
+assert_eq!(vec.pop(), Some(3));
+assert_eq!(vec, [1, 2]);Takes O(1) time.
+vec_pop_if)Removes and returns the last element in a vector if the predicate
+returns true, or None if the predicate returns false or the vector
+is empty.
#![feature(vec_pop_if)]
+
+let mut vec = vec![1, 2, 3, 4];
+let pred = |x: &mut i32| *x % 2 == 0;
+
+assert_eq!(vec.pop_if(pred), Some(4));
+assert_eq!(vec, [1, 2, 3]);
+assert_eq!(vec.pop_if(pred), None);Removes the specified range from the vector in bulk, returning all +removed elements as an iterator. If the iterator is dropped before +being fully consumed, it drops the remaining removed elements.
+The returned iterator keeps a mutable borrow on the vector to optimize +its implementation.
+Panics if the starting point is greater than the end point or if +the end point is greater than the length of the vector.
+If the returned iterator goes out of scope without being dropped (due to
+mem::forget, for example), the vector may have lost and leaked
+elements arbitrarily, including elements outside the range.
let mut v = vec![1, 2, 3];
+let u: Vec<_> = v.drain(1..).collect();
+assert_eq!(v, &[1]);
+assert_eq!(u, &[2, 3]);
+
+// A full range clears the vector, like `clear()` does
+v.drain(..);
+assert_eq!(v, &[]);Clears the vector, removing all values.
+Note that this method has no effect on the allocated capacity +of the vector.
+let mut v = vec![1, 2, 3];
+
+v.clear();
+
+assert!(v.is_empty());Returns the number of elements in the vector, also referred to +as its ‘length’.
+let a = vec![1, 2, 3];
+assert_eq!(a.len(), 3);Returns true if the vector contains no elements.
let mut v = Vec::new();
+assert!(v.is_empty());
+
+v.push(1);
+assert!(!v.is_empty());Splits the collection into two at the given index.
+Returns a newly allocated vector containing the elements in the range
+[at, len). After the call, the original vector will be left containing
+the elements [0, at) with its previous capacity unchanged.
mem::take or mem::replace.Vec::truncate.Vec::drain.Panics if at > len.
let mut vec = vec![1, 2, 3];
+let vec2 = vec.split_off(1);
+assert_eq!(vec, [1]);
+assert_eq!(vec2, [2, 3]);Resizes the Vec in-place so that len is equal to new_len.
If new_len is greater than len, the Vec is extended by the
+difference, with each additional slot filled with the result of
+calling the closure f. The return values from f will end up
+in the Vec in the order they have been generated.
If new_len is less than len, the Vec is simply truncated.
This method uses a closure to create new values on every push. If
+you’d rather Clone a given value, use Vec::resize. If you
+want to use the Default trait to generate values, you can
+pass Default::default as the second argument.
let mut vec = vec![1, 2, 3];
+vec.resize_with(5, Default::default);
+assert_eq!(vec, [1, 2, 3, 0, 0]);
+
+let mut vec = vec![];
+let mut p = 1;
+vec.resize_with(4, || { p *= 2; p });
+assert_eq!(vec, [2, 4, 8, 16]);Returns the remaining spare capacity of the vector as a slice of
+MaybeUninit<T>.
The returned slice can be used to fill the vector with data (e.g. by
+reading from a file) before marking the data as initialized using the
+set_len method.
// Allocate vector big enough for 10 elements.
+let mut v = Vec::with_capacity(10);
+
+// Fill in the first 3 elements.
+let uninit = v.spare_capacity_mut();
+uninit[0].write(0);
+uninit[1].write(1);
+uninit[2].write(2);
+
+// Mark the first 3 elements of the vector as being initialized.
+unsafe {
+ v.set_len(3);
+}
+
+assert_eq!(&v, &[0, 1, 2]);vec_split_at_spare)Returns vector content as a slice of T, along with the remaining spare
+capacity of the vector as a slice of MaybeUninit<T>.
The returned spare capacity slice can be used to fill the vector with data
+(e.g. by reading from a file) before marking the data as initialized using
+the set_len method.
Note that this is a low-level API, which should be used with care for
+optimization purposes. If you need to append data to a Vec
+you can use push, extend, extend_from_slice,
+extend_from_within, insert, append, resize or
+resize_with, depending on your exact needs.
#![feature(vec_split_at_spare)]
+
+let mut v = vec![1, 1, 2];
+
+// Reserve additional space big enough for 10 elements.
+v.reserve(10);
+
+let (init, uninit) = v.split_at_spare_mut();
+let sum = init.iter().copied().sum::<u32>();
+
+// Fill in the next 4 elements.
+uninit[0].write(sum);
+uninit[1].write(sum * 2);
+uninit[2].write(sum * 3);
+uninit[3].write(sum * 4);
+
+// Mark the 4 elements of the vector as being initialized.
+unsafe {
+ let len = v.len();
+ v.set_len(len + 4);
+}
+
+assert_eq!(&v, &[1, 1, 2, 4, 8, 12, 16]);Resizes the Vec in-place so that len is equal to new_len.
If new_len is greater than len, the Vec is extended by the
+difference, with each additional slot filled with value.
+If new_len is less than len, the Vec is simply truncated.
This method requires T to implement Clone,
+in order to be able to clone the passed value.
+If you need more flexibility (or want to rely on Default instead of
+Clone), use Vec::resize_with.
+If you only need to resize to a smaller size, use Vec::truncate.
let mut vec = vec!["hello"];
+vec.resize(3, "world");
+assert_eq!(vec, ["hello", "world", "world"]);
+
+let mut vec = vec![1, 2, 3, 4];
+vec.resize(2, 0);
+assert_eq!(vec, [1, 2]);Clones and appends all elements in a slice to the Vec.
Iterates over the slice other, clones each element, and then appends
+it to this Vec. The other slice is traversed in-order.
Note that this function is same as extend except that it is
+specialized to work with slices instead. If and when Rust gets
+specialization this function will likely be deprecated (but still
+available).
let mut vec = vec![1];
+vec.extend_from_slice(&[2, 3, 4]);
+assert_eq!(vec, [1, 2, 3, 4]);Copies elements from src range to the end of the vector.
Panics if the starting point is greater than the end point or if +the end point is greater than the length of the vector.
+let mut vec = vec![0, 1, 2, 3, 4];
+
+vec.extend_from_within(2..);
+assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4]);
+
+vec.extend_from_within(..2);
+assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1]);
+
+vec.extend_from_within(4..8);
+assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);Creates a splicing iterator that replaces the specified range in the vector
+with the given replace_with iterator and yields the removed items.
+replace_with does not need to be the same length as range.
range is removed even if the iterator is not consumed until the end.
It is unspecified how many elements are removed from the vector
+if the Splice value is leaked.
The input iterator replace_with is only consumed when the Splice value is dropped.
This is optimal if:
+range) is empty,replace_with yields fewer or equal elements than range’s lengthsize_hint() is exact.Otherwise, a temporary vector is allocated and the tail is moved twice.
+Panics if the starting point is greater than the end point or if +the end point is greater than the length of the vector.
+let mut v = vec![1, 2, 3, 4];
+let new = [7, 8, 9];
+let u: Vec<_> = v.splice(1..3, new).collect();
+assert_eq!(v, &[1, 7, 8, 9, 4]);
+assert_eq!(u, &[2, 3]);extract_if)Creates an iterator which uses a closure to determine if an element should be removed.
+If the closure returns true, then the element is removed and yielded. +If the closure returns false, the element will remain in the vector and will not be yielded +by the iterator.
+If the returned ExtractIf is not exhausted, e.g. because it is dropped without iterating
+or the iteration short-circuits, then the remaining elements will be retained.
+Use retain with a negated predicate if you do not need the returned iterator.
Using this method is equivalent to the following code:
+ +let mut i = 0;
+while i < vec.len() {
+ if some_predicate(&mut vec[i]) {
+ let val = vec.remove(i);
+ // your code here
+ } else {
+ i += 1;
+ }
+}
+But extract_if is easier to use. extract_if is also more efficient,
+because it can backshift the elements of the array in bulk.
Note that extract_if also lets you mutate every element in the filter closure,
+regardless of whether you choose to keep or remove it.
Splitting an array into evens and odds, reusing the original allocation:
+ +#![feature(extract_if)]
+let mut numbers = vec![1, 2, 3, 4, 5, 6, 8, 9, 11, 13, 14, 15];
+
+let evens = numbers.extract_if(|x| *x % 2 == 0).collect::<Vec<_>>();
+let odds = numbers;
+
+assert_eq!(evens, vec![2, 4, 6, 8, 14]);
+assert_eq!(odds, vec![1, 3, 5, 9, 11, 13, 15]);ascii_char)Views this slice of ASCII characters as a UTF-8 str.
ascii_char)Views this slice of ASCII characters as a slice of u8 bytes.
sort_floats)Sorts the slice of floats.
+This sort is in-place (i.e. does not allocate), O(n * log(n)) worst-case, and uses
+the ordering defined by f32::total_cmp.
This uses the same sorting algorithm as sort_unstable_by.
#![feature(sort_floats)]
+let mut v = [2.6, -5e-8, f32::NAN, 8.29, f32::INFINITY, -1.0, 0.0, -f32::INFINITY, -0.0];
+
+v.sort_floats();
+let sorted = [-f32::INFINITY, -1.0, -5e-8, -0.0, 0.0, 2.6, 8.29, f32::INFINITY, f32::NAN];
+assert_eq!(&v[..8], &sorted[..8]);
+assert!(v[8].is_nan());Checks if all bytes in this slice are within the ASCII range.
+ascii_char)If this slice is_ascii, returns it as a slice of
+ASCII characters, otherwise returns None.
ascii_char)Converts this slice of bytes into a slice of ASCII characters, +without checking whether they’re valid.
+Every byte in the slice must be in 0..=127, or else this is UB.
Checks that two slices are an ASCII case-insensitive match.
+Same as to_ascii_lowercase(a) == to_ascii_lowercase(b),
+but without allocating and copying temporaries.
Converts this slice to its ASCII upper case equivalent in-place.
+ASCII letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’, +but non-ASCII letters are unchanged.
+To return a new uppercased value without modifying the existing one, use
+to_ascii_uppercase.
Converts this slice to its ASCII lower case equivalent in-place.
+ASCII letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’, +but non-ASCII letters are unchanged.
+To return a new lowercased value without modifying the existing one, use
+to_ascii_lowercase.
Returns an iterator that produces an escaped version of this slice, +treating it as an ASCII string.
+
+let s = b"0\t\r\n'\"\\\x9d";
+let escaped = s.escape_ascii().to_string();
+assert_eq!(escaped, "0\\t\\r\\n\\'\\\"\\\\\\x9d");Returns a byte slice with leading ASCII whitespace bytes removed.
+‘Whitespace’ refers to the definition used by
+u8::is_ascii_whitespace.
assert_eq!(b" \t hello world\n".trim_ascii_start(), b"hello world\n");
+assert_eq!(b" ".trim_ascii_start(), b"");
+assert_eq!(b"".trim_ascii_start(), b"");Returns a byte slice with trailing ASCII whitespace bytes removed.
+‘Whitespace’ refers to the definition used by
+u8::is_ascii_whitespace.
assert_eq!(b"\r hello world\n ".trim_ascii_end(), b"\r hello world");
+assert_eq!(b" ".trim_ascii_end(), b"");
+assert_eq!(b"".trim_ascii_end(), b"");Returns a byte slice with leading and trailing ASCII whitespace bytes +removed.
+‘Whitespace’ refers to the definition used by
+u8::is_ascii_whitespace.
assert_eq!(b"\r hello world\n ".trim_ascii(), b"hello world");
+assert_eq!(b" ".trim_ascii(), b"");
+assert_eq!(b"".trim_ascii(), b"");Creates an iterator over the contiguous valid UTF-8 ranges of this +slice, and the non-UTF-8 fragments in between.
+This function formats arbitrary but mostly-UTF-8 bytes into Rust source
+code in the form of a C-string literal (c"...").
use std::fmt::Write as _;
+
+pub fn cstr_literal(bytes: &[u8]) -> String {
+ let mut repr = String::new();
+ repr.push_str("c\"");
+ for chunk in bytes.utf8_chunks() {
+ for ch in chunk.valid().chars() {
+ // Escapes \0, \t, \r, \n, \\, \', \", and uses \u{...} for non-printable characters.
+ write!(repr, "{}", ch.escape_debug()).unwrap();
+ }
+ for byte in chunk.invalid() {
+ write!(repr, "\\x{:02X}", byte).unwrap();
+ }
+ }
+ repr.push('"');
+ repr
+}
+
+fn main() {
+ let lit = cstr_literal(b"\xferris the \xf0\x9f\xa6\x80\x07");
+ let expected = stringify!(c"\xFErris the 🦀\u{7}");
+ assert_eq!(lit, expected);
+}Takes a &[[T; N]], and flattens it to a &[T].
This panics if the length of the resulting slice would overflow a usize.
This is only possible when flattening a slice of arrays of zero-sized
+types, and thus tends to be irrelevant in practice. If
+size_of::<T>() > 0, this will never panic.
assert_eq!([[1, 2, 3], [4, 5, 6]].as_flattened(), &[1, 2, 3, 4, 5, 6]);
+
+assert_eq!(
+ [[1, 2, 3], [4, 5, 6]].as_flattened(),
+ [[1, 2], [3, 4], [5, 6]].as_flattened(),
+);
+
+let slice_of_empty_arrays: &[[i32; 0]] = &[[], [], [], [], []];
+assert!(slice_of_empty_arrays.as_flattened().is_empty());
+
+let empty_slice_of_arrays: &[[u32; 10]] = &[];
+assert!(empty_slice_of_arrays.as_flattened().is_empty());Takes a &mut [[T; N]], and flattens it to a &mut [T].
This panics if the length of the resulting slice would overflow a usize.
This is only possible when flattening a slice of arrays of zero-sized
+types, and thus tends to be irrelevant in practice. If
+size_of::<T>() > 0, this will never panic.
fn add_5_to_all(slice: &mut [i32]) {
+ for i in slice {
+ *i += 5;
+ }
+}
+
+let mut array = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
+add_5_to_all(array.as_flattened_mut());
+assert_eq!(array, [[6, 7, 8], [9, 10, 11], [12, 13, 14]]);sort_floats)Sorts the slice of floats.
+This sort is in-place (i.e. does not allocate), O(n * log(n)) worst-case, and uses
+the ordering defined by f64::total_cmp.
This uses the same sorting algorithm as sort_unstable_by.
#![feature(sort_floats)]
+let mut v = [2.6, -5e-8, f64::NAN, 8.29, f64::INFINITY, -1.0, 0.0, -f64::INFINITY, -0.0];
+
+v.sort_floats();
+let sorted = [-f64::INFINITY, -1.0, -5e-8, -0.0, 0.0, 2.6, 8.29, f64::INFINITY, f64::NAN];
+assert_eq!(&v[..8], &sorted[..8]);
+assert!(v[8].is_nan());Returns the number of elements in the slice.
+let a = [1, 2, 3];
+assert_eq!(a.len(), 3);Returns true if the slice has a length of 0.
let a = [1, 2, 3];
+assert!(!a.is_empty());
+
+let b: &[i32] = &[];
+assert!(b.is_empty());Returns the first element of the slice, or None if it is empty.
let v = [10, 40, 30];
+assert_eq!(Some(&10), v.first());
+
+let w: &[i32] = &[];
+assert_eq!(None, w.first());Returns a mutable pointer to the first element of the slice, or None if it is empty.
let x = &mut [0, 1, 2];
+
+if let Some(first) = x.first_mut() {
+ *first = 5;
+}
+assert_eq!(x, &[5, 1, 2]);
+
+let y: &mut [i32] = &mut [];
+assert_eq!(None, y.first_mut());Returns the first and all the rest of the elements of the slice, or None if it is empty.
let x = &[0, 1, 2];
+
+if let Some((first, elements)) = x.split_first() {
+ assert_eq!(first, &0);
+ assert_eq!(elements, &[1, 2]);
+}Returns the first and all the rest of the elements of the slice, or None if it is empty.
let x = &mut [0, 1, 2];
+
+if let Some((first, elements)) = x.split_first_mut() {
+ *first = 3;
+ elements[0] = 4;
+ elements[1] = 5;
+}
+assert_eq!(x, &[3, 4, 5]);Returns the last and all the rest of the elements of the slice, or None if it is empty.
let x = &[0, 1, 2];
+
+if let Some((last, elements)) = x.split_last() {
+ assert_eq!(last, &2);
+ assert_eq!(elements, &[0, 1]);
+}Returns the last and all the rest of the elements of the slice, or None if it is empty.
let x = &mut [0, 1, 2];
+
+if let Some((last, elements)) = x.split_last_mut() {
+ *last = 3;
+ elements[0] = 4;
+ elements[1] = 5;
+}
+assert_eq!(x, &[4, 5, 3]);Returns the last element of the slice, or None if it is empty.
let v = [10, 40, 30];
+assert_eq!(Some(&30), v.last());
+
+let w: &[i32] = &[];
+assert_eq!(None, w.last());Returns a mutable reference to the last item in the slice, or None if it is empty.
let x = &mut [0, 1, 2];
+
+if let Some(last) = x.last_mut() {
+ *last = 10;
+}
+assert_eq!(x, &[0, 1, 10]);
+
+let y: &mut [i32] = &mut [];
+assert_eq!(None, y.last_mut());Return an array reference to the first N items in the slice.
If the slice is not at least N in length, this will return None.
let u = [10, 40, 30];
+assert_eq!(Some(&[10, 40]), u.first_chunk::<2>());
+
+let v: &[i32] = &[10];
+assert_eq!(None, v.first_chunk::<2>());
+
+let w: &[i32] = &[];
+assert_eq!(Some(&[]), w.first_chunk::<0>());Return a mutable array reference to the first N items in the slice.
If the slice is not at least N in length, this will return None.
let x = &mut [0, 1, 2];
+
+if let Some(first) = x.first_chunk_mut::<2>() {
+ first[0] = 5;
+ first[1] = 4;
+}
+assert_eq!(x, &[5, 4, 2]);
+
+assert_eq!(None, x.first_chunk_mut::<4>());Return an array reference to the first N items in the slice and the remaining slice.
If the slice is not at least N in length, this will return None.
let x = &[0, 1, 2];
+
+if let Some((first, elements)) = x.split_first_chunk::<2>() {
+ assert_eq!(first, &[0, 1]);
+ assert_eq!(elements, &[2]);
+}
+
+assert_eq!(None, x.split_first_chunk::<4>());Return a mutable array reference to the first N items in the slice and the remaining
+slice.
If the slice is not at least N in length, this will return None.
let x = &mut [0, 1, 2];
+
+if let Some((first, elements)) = x.split_first_chunk_mut::<2>() {
+ first[0] = 3;
+ first[1] = 4;
+ elements[0] = 5;
+}
+assert_eq!(x, &[3, 4, 5]);
+
+assert_eq!(None, x.split_first_chunk_mut::<4>());Return an array reference to the last N items in the slice and the remaining slice.
If the slice is not at least N in length, this will return None.
let x = &[0, 1, 2];
+
+if let Some((elements, last)) = x.split_last_chunk::<2>() {
+ assert_eq!(elements, &[0]);
+ assert_eq!(last, &[1, 2]);
+}
+
+assert_eq!(None, x.split_last_chunk::<4>());Return a mutable array reference to the last N items in the slice and the remaining
+slice.
If the slice is not at least N in length, this will return None.
let x = &mut [0, 1, 2];
+
+if let Some((elements, last)) = x.split_last_chunk_mut::<2>() {
+ last[0] = 3;
+ last[1] = 4;
+ elements[0] = 5;
+}
+assert_eq!(x, &[5, 3, 4]);
+
+assert_eq!(None, x.split_last_chunk_mut::<4>());Return an array reference to the last N items in the slice.
If the slice is not at least N in length, this will return None.
let u = [10, 40, 30];
+assert_eq!(Some(&[40, 30]), u.last_chunk::<2>());
+
+let v: &[i32] = &[10];
+assert_eq!(None, v.last_chunk::<2>());
+
+let w: &[i32] = &[];
+assert_eq!(Some(&[]), w.last_chunk::<0>());Return a mutable array reference to the last N items in the slice.
If the slice is not at least N in length, this will return None.
let x = &mut [0, 1, 2];
+
+if let Some(last) = x.last_chunk_mut::<2>() {
+ last[0] = 10;
+ last[1] = 20;
+}
+assert_eq!(x, &[0, 10, 20]);
+
+assert_eq!(None, x.last_chunk_mut::<4>());Returns a reference to an element or subslice depending on the type of +index.
+None if out of bounds.None if out of bounds.let v = [10, 40, 30];
+assert_eq!(Some(&40), v.get(1));
+assert_eq!(Some(&[10, 40][..]), v.get(0..2));
+assert_eq!(None, v.get(3));
+assert_eq!(None, v.get(0..4));Returns a reference to an element or subslice, without doing bounds +checking.
+For a safe alternative see get.
Calling this method with an out-of-bounds index is undefined behavior +even if the resulting reference is not used.
+You can think of this like .get(index).unwrap_unchecked(). It’s UB
+to call .get_unchecked(len), even if you immediately convert to a
+pointer. And it’s UB to call .get_unchecked(..len + 1),
+.get_unchecked(..=len), or similar.
let x = &[1, 2, 4];
+
+unsafe {
+ assert_eq!(x.get_unchecked(1), &2);
+}Returns a mutable reference to an element or subslice, without doing +bounds checking.
+For a safe alternative see get_mut.
Calling this method with an out-of-bounds index is undefined behavior +even if the resulting reference is not used.
+You can think of this like .get_mut(index).unwrap_unchecked(). It’s
+UB to call .get_unchecked_mut(len), even if you immediately convert
+to a pointer. And it’s UB to call .get_unchecked_mut(..len + 1),
+.get_unchecked_mut(..=len), or similar.
let x = &mut [1, 2, 4];
+
+unsafe {
+ let elem = x.get_unchecked_mut(1);
+ *elem = 13;
+}
+assert_eq!(x, &[1, 13, 4]);Returns a raw pointer to the slice’s buffer.
+The caller must ensure that the slice outlives the pointer this +function returns, or else it will end up pointing to garbage.
+The caller must also ensure that the memory the pointer (non-transitively) points to
+is never written to (except inside an UnsafeCell) using this pointer or any pointer
+derived from it. If you need to mutate the contents of the slice, use as_mut_ptr.
Modifying the container referenced by this slice may cause its buffer +to be reallocated, which would also make any pointers to it invalid.
+let x = &[1, 2, 4];
+let x_ptr = x.as_ptr();
+
+unsafe {
+ for i in 0..x.len() {
+ assert_eq!(x.get_unchecked(i), &*x_ptr.add(i));
+ }
+}Returns an unsafe mutable pointer to the slice’s buffer.
+The caller must ensure that the slice outlives the pointer this +function returns, or else it will end up pointing to garbage.
+Modifying the container referenced by this slice may cause its buffer +to be reallocated, which would also make any pointers to it invalid.
+let x = &mut [1, 2, 4];
+let x_ptr = x.as_mut_ptr();
+
+unsafe {
+ for i in 0..x.len() {
+ *x_ptr.add(i) += 2;
+ }
+}
+assert_eq!(x, &[3, 4, 6]);Returns the two raw pointers spanning the slice.
+The returned range is half-open, which means that the end pointer +points one past the last element of the slice. This way, an empty +slice is represented by two equal pointers, and the difference between +the two pointers represents the size of the slice.
+See as_ptr for warnings on using these pointers. The end pointer
+requires extra caution, as it does not point to a valid element in the
+slice.
This function is useful for interacting with foreign interfaces which +use two pointers to refer to a range of elements in memory, as is +common in C++.
+It can also be useful to check if a pointer to an element refers to an +element of this slice:
+ +let a = [1, 2, 3];
+let x = &a[1] as *const _;
+let y = &5 as *const _;
+
+assert!(a.as_ptr_range().contains(&x));
+assert!(!a.as_ptr_range().contains(&y));Returns the two unsafe mutable pointers spanning the slice.
+The returned range is half-open, which means that the end pointer +points one past the last element of the slice. This way, an empty +slice is represented by two equal pointers, and the difference between +the two pointers represents the size of the slice.
+See as_mut_ptr for warnings on using these pointers. The end
+pointer requires extra caution, as it does not point to a valid element
+in the slice.
This function is useful for interacting with foreign interfaces which +use two pointers to refer to a range of elements in memory, as is +common in C++.
+Swaps two elements in the slice.
+If a equals to b, it’s guaranteed that elements won’t change value.
Panics if a or b are out of bounds.
let mut v = ["a", "b", "c", "d", "e"];
+v.swap(2, 4);
+assert!(v == ["a", "b", "e", "d", "c"]);slice_swap_unchecked)Swaps two elements in the slice, without doing bounds checking.
+For a safe alternative see swap.
Calling this method with an out-of-bounds index is undefined behavior.
+The caller has to ensure that a < self.len() and b < self.len().
#![feature(slice_swap_unchecked)]
+
+let mut v = ["a", "b", "c", "d"];
+// SAFETY: we know that 1 and 3 are both indices of the slice
+unsafe { v.swap_unchecked(1, 3) };
+assert!(v == ["a", "d", "c", "b"]);Reverses the order of elements in the slice, in place.
+let mut v = [1, 2, 3];
+v.reverse();
+assert!(v == [3, 2, 1]);Returns an iterator over the slice.
+The iterator yields all items from start to end.
+let x = &[1, 2, 4];
+let mut iterator = x.iter();
+
+assert_eq!(iterator.next(), Some(&1));
+assert_eq!(iterator.next(), Some(&2));
+assert_eq!(iterator.next(), Some(&4));
+assert_eq!(iterator.next(), None);Returns an iterator that allows modifying each value.
+The iterator yields all items from start to end.
+let x = &mut [1, 2, 4];
+for elem in x.iter_mut() {
+ *elem += 2;
+}
+assert_eq!(x, &[3, 4, 6]);Returns an iterator over all contiguous windows of length
+size. The windows overlap. If the slice is shorter than
+size, the iterator returns no values.
Panics if size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.windows(3);
+assert_eq!(iter.next().unwrap(), &['l', 'o', 'r']);
+assert_eq!(iter.next().unwrap(), &['o', 'r', 'e']);
+assert_eq!(iter.next().unwrap(), &['r', 'e', 'm']);
+assert!(iter.next().is_none());If the slice is shorter than size:
let slice = ['f', 'o', 'o'];
+let mut iter = slice.windows(4);
+assert!(iter.next().is_none());There’s no windows_mut, as that existing would let safe code violate the
+“only one &mut at a time to the same thing” rule. However, you can sometimes
+use Cell::as_slice_of_cells in
+conjunction with windows to accomplish something similar:
use std::cell::Cell;
+
+let mut array = ['R', 'u', 's', 't', ' ', '2', '0', '1', '5'];
+let slice = &mut array[..];
+let slice_of_cells: &[Cell<char>] = Cell::from_mut(slice).as_slice_of_cells();
+for w in slice_of_cells.windows(3) {
+ Cell::swap(&w[0], &w[2]);
+}
+assert_eq!(array, ['s', 't', ' ', '2', '0', '1', '5', 'u', 'R']);Returns an iterator over chunk_size elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are slices and do not overlap. If chunk_size does not divide the length of the
+slice, then the last chunk will not have length chunk_size.
See chunks_exact for a variant of this iterator that returns chunks of always exactly
+chunk_size elements, and rchunks for the same iterator but starting at the end of the
+slice.
Panics if chunk_size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.chunks(2);
+assert_eq!(iter.next().unwrap(), &['l', 'o']);
+assert_eq!(iter.next().unwrap(), &['r', 'e']);
+assert_eq!(iter.next().unwrap(), &['m']);
+assert!(iter.next().is_none());Returns an iterator over chunk_size elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are mutable slices, and do not overlap. If chunk_size does not divide the
+length of the slice, then the last chunk will not have length chunk_size.
See chunks_exact_mut for a variant of this iterator that returns chunks of always
+exactly chunk_size elements, and rchunks_mut for the same iterator but starting at
+the end of the slice.
Panics if chunk_size is 0.
let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.chunks_mut(2) {
+ for elem in chunk.iter_mut() {
+ *elem += count;
+ }
+ count += 1;
+}
+assert_eq!(v, &[1, 1, 2, 2, 3]);Returns an iterator over chunk_size elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are slices and do not overlap. If chunk_size does not divide the length of the
+slice, then the last up to chunk_size-1 elements will be omitted and can be retrieved
+from the remainder function of the iterator.
Due to each chunk having exactly chunk_size elements, the compiler can often optimize the
+resulting code better than in the case of chunks.
See chunks for a variant of this iterator that also returns the remainder as a smaller
+chunk, and rchunks_exact for the same iterator but starting at the end of the slice.
Panics if chunk_size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.chunks_exact(2);
+assert_eq!(iter.next().unwrap(), &['l', 'o']);
+assert_eq!(iter.next().unwrap(), &['r', 'e']);
+assert!(iter.next().is_none());
+assert_eq!(iter.remainder(), &['m']);Returns an iterator over chunk_size elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are mutable slices, and do not overlap. If chunk_size does not divide the
+length of the slice, then the last up to chunk_size-1 elements will be omitted and can be
+retrieved from the into_remainder function of the iterator.
Due to each chunk having exactly chunk_size elements, the compiler can often optimize the
+resulting code better than in the case of chunks_mut.
See chunks_mut for a variant of this iterator that also returns the remainder as a
+smaller chunk, and rchunks_exact_mut for the same iterator but starting at the end of
+the slice.
Panics if chunk_size is 0.
let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.chunks_exact_mut(2) {
+ for elem in chunk.iter_mut() {
+ *elem += count;
+ }
+ count += 1;
+}
+assert_eq!(v, &[1, 1, 2, 2, 0]);slice_as_chunks)Splits the slice into a slice of N-element arrays,
+assuming that there’s no remainder.
This may only be called when
+N-element chunks (aka self.len() % N == 0).N != 0.#![feature(slice_as_chunks)]
+let slice: &[char] = &['l', 'o', 'r', 'e', 'm', '!'];
+let chunks: &[[char; 1]] =
+ // SAFETY: 1-element chunks never have remainder
+ unsafe { slice.as_chunks_unchecked() };
+assert_eq!(chunks, &[['l'], ['o'], ['r'], ['e'], ['m'], ['!']]);
+let chunks: &[[char; 3]] =
+ // SAFETY: The slice length (6) is a multiple of 3
+ unsafe { slice.as_chunks_unchecked() };
+assert_eq!(chunks, &[['l', 'o', 'r'], ['e', 'm', '!']]);
+
+// These would be unsound:
+// let chunks: &[[_; 5]] = slice.as_chunks_unchecked() // The slice length is not a multiple of 5
+// let chunks: &[[_; 0]] = slice.as_chunks_unchecked() // Zero-length chunks are never allowedslice_as_chunks)Splits the slice into a slice of N-element arrays,
+starting at the beginning of the slice,
+and a remainder slice with length strictly less than N.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(slice_as_chunks)]
+let slice = ['l', 'o', 'r', 'e', 'm'];
+let (chunks, remainder) = slice.as_chunks();
+assert_eq!(chunks, &[['l', 'o'], ['r', 'e']]);
+assert_eq!(remainder, &['m']);If you expect the slice to be an exact multiple, you can combine
+let-else with an empty slice pattern:
#![feature(slice_as_chunks)]
+let slice = ['R', 'u', 's', 't'];
+let (chunks, []) = slice.as_chunks::<2>() else {
+ panic!("slice didn't have even length")
+};
+assert_eq!(chunks, &[['R', 'u'], ['s', 't']]);slice_as_chunks)Splits the slice into a slice of N-element arrays,
+starting at the end of the slice,
+and a remainder slice with length strictly less than N.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(slice_as_chunks)]
+let slice = ['l', 'o', 'r', 'e', 'm'];
+let (remainder, chunks) = slice.as_rchunks();
+assert_eq!(remainder, &['l']);
+assert_eq!(chunks, &[['o', 'r'], ['e', 'm']]);array_chunks)Returns an iterator over N elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are array references and do not overlap. If N does not divide the
+length of the slice, then the last up to N-1 elements will be omitted and can be
+retrieved from the remainder function of the iterator.
This method is the const generic equivalent of chunks_exact.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(array_chunks)]
+let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.array_chunks();
+assert_eq!(iter.next().unwrap(), &['l', 'o']);
+assert_eq!(iter.next().unwrap(), &['r', 'e']);
+assert!(iter.next().is_none());
+assert_eq!(iter.remainder(), &['m']);slice_as_chunks)Splits the slice into a slice of N-element arrays,
+assuming that there’s no remainder.
This may only be called when
+N-element chunks (aka self.len() % N == 0).N != 0.#![feature(slice_as_chunks)]
+let slice: &mut [char] = &mut ['l', 'o', 'r', 'e', 'm', '!'];
+let chunks: &mut [[char; 1]] =
+ // SAFETY: 1-element chunks never have remainder
+ unsafe { slice.as_chunks_unchecked_mut() };
+chunks[0] = ['L'];
+assert_eq!(chunks, &[['L'], ['o'], ['r'], ['e'], ['m'], ['!']]);
+let chunks: &mut [[char; 3]] =
+ // SAFETY: The slice length (6) is a multiple of 3
+ unsafe { slice.as_chunks_unchecked_mut() };
+chunks[1] = ['a', 'x', '?'];
+assert_eq!(slice, &['L', 'o', 'r', 'a', 'x', '?']);
+
+// These would be unsound:
+// let chunks: &[[_; 5]] = slice.as_chunks_unchecked_mut() // The slice length is not a multiple of 5
+// let chunks: &[[_; 0]] = slice.as_chunks_unchecked_mut() // Zero-length chunks are never allowedslice_as_chunks)Splits the slice into a slice of N-element arrays,
+starting at the beginning of the slice,
+and a remainder slice with length strictly less than N.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(slice_as_chunks)]
+let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+let (chunks, remainder) = v.as_chunks_mut();
+remainder[0] = 9;
+for chunk in chunks {
+ *chunk = [count; 2];
+ count += 1;
+}
+assert_eq!(v, &[1, 1, 2, 2, 9]);slice_as_chunks)Splits the slice into a slice of N-element arrays,
+starting at the end of the slice,
+and a remainder slice with length strictly less than N.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(slice_as_chunks)]
+let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+let (remainder, chunks) = v.as_rchunks_mut();
+remainder[0] = 9;
+for chunk in chunks {
+ *chunk = [count; 2];
+ count += 1;
+}
+assert_eq!(v, &[9, 1, 1, 2, 2]);array_chunks)Returns an iterator over N elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are mutable array references and do not overlap. If N does not divide
+the length of the slice, then the last up to N-1 elements will be omitted and
+can be retrieved from the into_remainder function of the iterator.
This method is the const generic equivalent of chunks_exact_mut.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(array_chunks)]
+let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.array_chunks_mut() {
+ *chunk = [count; 2];
+ count += 1;
+}
+assert_eq!(v, &[1, 1, 2, 2, 0]);array_windows)Returns an iterator over overlapping windows of N elements of a slice,
+starting at the beginning of the slice.
This is the const generic equivalent of windows.
If N is greater than the size of the slice, it will return no windows.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(array_windows)]
+let slice = [0, 1, 2, 3];
+let mut iter = slice.array_windows();
+assert_eq!(iter.next().unwrap(), &[0, 1]);
+assert_eq!(iter.next().unwrap(), &[1, 2]);
+assert_eq!(iter.next().unwrap(), &[2, 3]);
+assert!(iter.next().is_none());Returns an iterator over chunk_size elements of the slice at a time, starting at the end
+of the slice.
The chunks are slices and do not overlap. If chunk_size does not divide the length of the
+slice, then the last chunk will not have length chunk_size.
See rchunks_exact for a variant of this iterator that returns chunks of always exactly
+chunk_size elements, and chunks for the same iterator but starting at the beginning
+of the slice.
Panics if chunk_size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.rchunks(2);
+assert_eq!(iter.next().unwrap(), &['e', 'm']);
+assert_eq!(iter.next().unwrap(), &['o', 'r']);
+assert_eq!(iter.next().unwrap(), &['l']);
+assert!(iter.next().is_none());Returns an iterator over chunk_size elements of the slice at a time, starting at the end
+of the slice.
The chunks are mutable slices, and do not overlap. If chunk_size does not divide the
+length of the slice, then the last chunk will not have length chunk_size.
See rchunks_exact_mut for a variant of this iterator that returns chunks of always
+exactly chunk_size elements, and chunks_mut for the same iterator but starting at the
+beginning of the slice.
Panics if chunk_size is 0.
let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.rchunks_mut(2) {
+ for elem in chunk.iter_mut() {
+ *elem += count;
+ }
+ count += 1;
+}
+assert_eq!(v, &[3, 2, 2, 1, 1]);Returns an iterator over chunk_size elements of the slice at a time, starting at the
+end of the slice.
The chunks are slices and do not overlap. If chunk_size does not divide the length of the
+slice, then the last up to chunk_size-1 elements will be omitted and can be retrieved
+from the remainder function of the iterator.
Due to each chunk having exactly chunk_size elements, the compiler can often optimize the
+resulting code better than in the case of rchunks.
See rchunks for a variant of this iterator that also returns the remainder as a smaller
+chunk, and chunks_exact for the same iterator but starting at the beginning of the
+slice.
Panics if chunk_size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.rchunks_exact(2);
+assert_eq!(iter.next().unwrap(), &['e', 'm']);
+assert_eq!(iter.next().unwrap(), &['o', 'r']);
+assert!(iter.next().is_none());
+assert_eq!(iter.remainder(), &['l']);Returns an iterator over chunk_size elements of the slice at a time, starting at the end
+of the slice.
The chunks are mutable slices, and do not overlap. If chunk_size does not divide the
+length of the slice, then the last up to chunk_size-1 elements will be omitted and can be
+retrieved from the into_remainder function of the iterator.
Due to each chunk having exactly chunk_size elements, the compiler can often optimize the
+resulting code better than in the case of chunks_mut.
See rchunks_mut for a variant of this iterator that also returns the remainder as a
+smaller chunk, and chunks_exact_mut for the same iterator but starting at the beginning
+of the slice.
Panics if chunk_size is 0.
let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.rchunks_exact_mut(2) {
+ for elem in chunk.iter_mut() {
+ *elem += count;
+ }
+ count += 1;
+}
+assert_eq!(v, &[0, 2, 2, 1, 1]);Returns an iterator over the slice producing non-overlapping runs +of elements using the predicate to separate them.
+The predicate is called for every pair of consecutive elements,
+meaning that it is called on slice[0] and slice[1],
+followed by slice[1] and slice[2], and so on.
let slice = &[1, 1, 1, 3, 3, 2, 2, 2];
+
+let mut iter = slice.chunk_by(|a, b| a == b);
+
+assert_eq!(iter.next(), Some(&[1, 1, 1][..]));
+assert_eq!(iter.next(), Some(&[3, 3][..]));
+assert_eq!(iter.next(), Some(&[2, 2, 2][..]));
+assert_eq!(iter.next(), None);This method can be used to extract the sorted subslices:
+ +let slice = &[1, 1, 2, 3, 2, 3, 2, 3, 4];
+
+let mut iter = slice.chunk_by(|a, b| a <= b);
+
+assert_eq!(iter.next(), Some(&[1, 1, 2, 3][..]));
+assert_eq!(iter.next(), Some(&[2, 3][..]));
+assert_eq!(iter.next(), Some(&[2, 3, 4][..]));
+assert_eq!(iter.next(), None);Returns an iterator over the slice producing non-overlapping mutable +runs of elements using the predicate to separate them.
+The predicate is called for every pair of consecutive elements,
+meaning that it is called on slice[0] and slice[1],
+followed by slice[1] and slice[2], and so on.
let slice = &mut [1, 1, 1, 3, 3, 2, 2, 2];
+
+let mut iter = slice.chunk_by_mut(|a, b| a == b);
+
+assert_eq!(iter.next(), Some(&mut [1, 1, 1][..]));
+assert_eq!(iter.next(), Some(&mut [3, 3][..]));
+assert_eq!(iter.next(), Some(&mut [2, 2, 2][..]));
+assert_eq!(iter.next(), None);This method can be used to extract the sorted subslices:
+ +let slice = &mut [1, 1, 2, 3, 2, 3, 2, 3, 4];
+
+let mut iter = slice.chunk_by_mut(|a, b| a <= b);
+
+assert_eq!(iter.next(), Some(&mut [1, 1, 2, 3][..]));
+assert_eq!(iter.next(), Some(&mut [2, 3][..]));
+assert_eq!(iter.next(), Some(&mut [2, 3, 4][..]));
+assert_eq!(iter.next(), None);Divides one slice into two at an index.
+The first will contain all indices from [0, mid) (excluding
+the index mid itself) and the second will contain all
+indices from [mid, len) (excluding the index len itself).
Panics if mid > len. For a non-panicking alternative see
+split_at_checked.
let v = [1, 2, 3, 4, 5, 6];
+
+{
+ let (left, right) = v.split_at(0);
+ assert_eq!(left, []);
+ assert_eq!(right, [1, 2, 3, 4, 5, 6]);
+}
+
+{
+ let (left, right) = v.split_at(2);
+ assert_eq!(left, [1, 2]);
+ assert_eq!(right, [3, 4, 5, 6]);
+}
+
+{
+ let (left, right) = v.split_at(6);
+ assert_eq!(left, [1, 2, 3, 4, 5, 6]);
+ assert_eq!(right, []);
+}Divides one mutable slice into two at an index.
+The first will contain all indices from [0, mid) (excluding
+the index mid itself) and the second will contain all
+indices from [mid, len) (excluding the index len itself).
Panics if mid > len. For a non-panicking alternative see
+split_at_mut_checked.
let mut v = [1, 0, 3, 0, 5, 6];
+let (left, right) = v.split_at_mut(2);
+assert_eq!(left, [1, 0]);
+assert_eq!(right, [3, 0, 5, 6]);
+left[1] = 2;
+right[1] = 4;
+assert_eq!(v, [1, 2, 3, 4, 5, 6]);Divides one slice into two at an index, without doing bounds checking.
+The first will contain all indices from [0, mid) (excluding
+the index mid itself) and the second will contain all
+indices from [mid, len) (excluding the index len itself).
For a safe alternative see split_at.
Calling this method with an out-of-bounds index is undefined behavior
+even if the resulting reference is not used. The caller has to ensure that
+0 <= mid <= self.len().
let v = [1, 2, 3, 4, 5, 6];
+
+unsafe {
+ let (left, right) = v.split_at_unchecked(0);
+ assert_eq!(left, []);
+ assert_eq!(right, [1, 2, 3, 4, 5, 6]);
+}
+
+unsafe {
+ let (left, right) = v.split_at_unchecked(2);
+ assert_eq!(left, [1, 2]);
+ assert_eq!(right, [3, 4, 5, 6]);
+}
+
+unsafe {
+ let (left, right) = v.split_at_unchecked(6);
+ assert_eq!(left, [1, 2, 3, 4, 5, 6]);
+ assert_eq!(right, []);
+}Divides one mutable slice into two at an index, without doing bounds checking.
+The first will contain all indices from [0, mid) (excluding
+the index mid itself) and the second will contain all
+indices from [mid, len) (excluding the index len itself).
For a safe alternative see split_at_mut.
Calling this method with an out-of-bounds index is undefined behavior
+even if the resulting reference is not used. The caller has to ensure that
+0 <= mid <= self.len().
let mut v = [1, 0, 3, 0, 5, 6];
+// scoped to restrict the lifetime of the borrows
+unsafe {
+ let (left, right) = v.split_at_mut_unchecked(2);
+ assert_eq!(left, [1, 0]);
+ assert_eq!(right, [3, 0, 5, 6]);
+ left[1] = 2;
+ right[1] = 4;
+}
+assert_eq!(v, [1, 2, 3, 4, 5, 6]);Divides one slice into two at an index, returning None if the slice is
+too short.
If mid ≤ len returns a pair of slices where the first will contain all
+indices from [0, mid) (excluding the index mid itself) and the
+second will contain all indices from [mid, len) (excluding the index
+len itself).
Otherwise, if mid > len, returns None.
let v = [1, -2, 3, -4, 5, -6];
+
+{
+ let (left, right) = v.split_at_checked(0).unwrap();
+ assert_eq!(left, []);
+ assert_eq!(right, [1, -2, 3, -4, 5, -6]);
+}
+
+{
+ let (left, right) = v.split_at_checked(2).unwrap();
+ assert_eq!(left, [1, -2]);
+ assert_eq!(right, [3, -4, 5, -6]);
+}
+
+{
+ let (left, right) = v.split_at_checked(6).unwrap();
+ assert_eq!(left, [1, -2, 3, -4, 5, -6]);
+ assert_eq!(right, []);
+}
+
+assert_eq!(None, v.split_at_checked(7));Divides one mutable slice into two at an index, returning None if the
+slice is too short.
If mid ≤ len returns a pair of slices where the first will contain all
+indices from [0, mid) (excluding the index mid itself) and the
+second will contain all indices from [mid, len) (excluding the index
+len itself).
Otherwise, if mid > len, returns None.
let mut v = [1, 0, 3, 0, 5, 6];
+
+if let Some((left, right)) = v.split_at_mut_checked(2) {
+ assert_eq!(left, [1, 0]);
+ assert_eq!(right, [3, 0, 5, 6]);
+ left[1] = 2;
+ right[1] = 4;
+}
+assert_eq!(v, [1, 2, 3, 4, 5, 6]);
+
+assert_eq!(None, v.split_at_mut_checked(7));Returns an iterator over subslices separated by elements that match
+pred. The matched element is not contained in the subslices.
let slice = [10, 40, 33, 20];
+let mut iter = slice.split(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[10, 40]);
+assert_eq!(iter.next().unwrap(), &[20]);
+assert!(iter.next().is_none());If the first element is matched, an empty slice will be the first item +returned by the iterator. Similarly, if the last element in the slice +is matched, an empty slice will be the last item returned by the +iterator:
+ +let slice = [10, 40, 33];
+let mut iter = slice.split(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[10, 40]);
+assert_eq!(iter.next().unwrap(), &[]);
+assert!(iter.next().is_none());If two matched elements are directly adjacent, an empty slice will be +present between them:
+ +let slice = [10, 6, 33, 20];
+let mut iter = slice.split(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[10]);
+assert_eq!(iter.next().unwrap(), &[]);
+assert_eq!(iter.next().unwrap(), &[20]);
+assert!(iter.next().is_none());Returns an iterator over mutable subslices separated by elements that
+match pred. The matched element is not contained in the subslices.
let mut v = [10, 40, 30, 20, 60, 50];
+
+for group in v.split_mut(|num| *num % 3 == 0) {
+ group[0] = 1;
+}
+assert_eq!(v, [1, 40, 30, 1, 60, 1]);Returns an iterator over subslices separated by elements that match
+pred. The matched element is contained in the end of the previous
+subslice as a terminator.
let slice = [10, 40, 33, 20];
+let mut iter = slice.split_inclusive(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[10, 40, 33]);
+assert_eq!(iter.next().unwrap(), &[20]);
+assert!(iter.next().is_none());If the last element of the slice is matched, +that element will be considered the terminator of the preceding slice. +That slice will be the last item returned by the iterator.
+ +let slice = [3, 10, 40, 33];
+let mut iter = slice.split_inclusive(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[3]);
+assert_eq!(iter.next().unwrap(), &[10, 40, 33]);
+assert!(iter.next().is_none());Returns an iterator over mutable subslices separated by elements that
+match pred. The matched element is contained in the previous
+subslice as a terminator.
let mut v = [10, 40, 30, 20, 60, 50];
+
+for group in v.split_inclusive_mut(|num| *num % 3 == 0) {
+ let terminator_idx = group.len()-1;
+ group[terminator_idx] = 1;
+}
+assert_eq!(v, [10, 40, 1, 20, 1, 1]);Returns an iterator over subslices separated by elements that match
+pred, starting at the end of the slice and working backwards.
+The matched element is not contained in the subslices.
let slice = [11, 22, 33, 0, 44, 55];
+let mut iter = slice.rsplit(|num| *num == 0);
+
+assert_eq!(iter.next().unwrap(), &[44, 55]);
+assert_eq!(iter.next().unwrap(), &[11, 22, 33]);
+assert_eq!(iter.next(), None);As with split(), if the first or last element is matched, an empty
+slice will be the first (or last) item returned by the iterator.
let v = &[0, 1, 1, 2, 3, 5, 8];
+let mut it = v.rsplit(|n| *n % 2 == 0);
+assert_eq!(it.next().unwrap(), &[]);
+assert_eq!(it.next().unwrap(), &[3, 5]);
+assert_eq!(it.next().unwrap(), &[1, 1]);
+assert_eq!(it.next().unwrap(), &[]);
+assert_eq!(it.next(), None);Returns an iterator over mutable subslices separated by elements that
+match pred, starting at the end of the slice and working
+backwards. The matched element is not contained in the subslices.
let mut v = [100, 400, 300, 200, 600, 500];
+
+let mut count = 0;
+for group in v.rsplit_mut(|num| *num % 3 == 0) {
+ count += 1;
+ group[0] = count;
+}
+assert_eq!(v, [3, 400, 300, 2, 600, 1]);Returns an iterator over subslices separated by elements that match
+pred, limited to returning at most n items. The matched element is
+not contained in the subslices.
The last element returned, if any, will contain the remainder of the +slice.
+Print the slice split once by numbers divisible by 3 (i.e., [10, 40],
+[20, 60, 50]):
let v = [10, 40, 30, 20, 60, 50];
+
+for group in v.splitn(2, |num| *num % 3 == 0) {
+ println!("{group:?}");
+}Returns an iterator over mutable subslices separated by elements that match
+pred, limited to returning at most n items. The matched element is
+not contained in the subslices.
The last element returned, if any, will contain the remainder of the +slice.
+let mut v = [10, 40, 30, 20, 60, 50];
+
+for group in v.splitn_mut(2, |num| *num % 3 == 0) {
+ group[0] = 1;
+}
+assert_eq!(v, [1, 40, 30, 1, 60, 50]);Returns an iterator over subslices separated by elements that match
+pred limited to returning at most n items. This starts at the end of
+the slice and works backwards. The matched element is not contained in
+the subslices.
The last element returned, if any, will contain the remainder of the +slice.
+Print the slice split once, starting from the end, by numbers divisible
+by 3 (i.e., [50], [10, 40, 30, 20]):
let v = [10, 40, 30, 20, 60, 50];
+
+for group in v.rsplitn(2, |num| *num % 3 == 0) {
+ println!("{group:?}");
+}Returns an iterator over subslices separated by elements that match
+pred limited to returning at most n items. This starts at the end of
+the slice and works backwards. The matched element is not contained in
+the subslices.
The last element returned, if any, will contain the remainder of the +slice.
+let mut s = [10, 40, 30, 20, 60, 50];
+
+for group in s.rsplitn_mut(2, |num| *num % 3 == 0) {
+ group[0] = 1;
+}
+assert_eq!(s, [1, 40, 30, 20, 60, 1]);slice_split_once)Splits the slice on the first element that matches the specified +predicate.
+If any matching elements are present in the slice, returns the prefix
+before the match and suffix after. The matching element itself is not
+included. If no elements match, returns None.
#![feature(slice_split_once)]
+let s = [1, 2, 3, 2, 4];
+assert_eq!(s.split_once(|&x| x == 2), Some((
+ &[1][..],
+ &[3, 2, 4][..]
+)));
+assert_eq!(s.split_once(|&x| x == 0), None);slice_split_once)Splits the slice on the last element that matches the specified +predicate.
+If any matching elements are present in the slice, returns the prefix
+before the match and suffix after. The matching element itself is not
+included. If no elements match, returns None.
#![feature(slice_split_once)]
+let s = [1, 2, 3, 2, 4];
+assert_eq!(s.rsplit_once(|&x| x == 2), Some((
+ &[1, 2, 3][..],
+ &[4][..]
+)));
+assert_eq!(s.rsplit_once(|&x| x == 0), None);Returns true if the slice contains an element with the given value.
This operation is O(n).
+Note that if you have a sorted slice, binary_search may be faster.
let v = [10, 40, 30];
+assert!(v.contains(&30));
+assert!(!v.contains(&50));If you do not have a &T, but some other value that you can compare
+with one (for example, String implements PartialEq<str>), you can
+use iter().any:
let v = [String::from("hello"), String::from("world")]; // slice of `String`
+assert!(v.iter().any(|e| e == "hello")); // search with `&str`
+assert!(!v.iter().any(|e| e == "hi"));Returns true if needle is a prefix of the slice or equal to the slice.
let v = [10, 40, 30];
+assert!(v.starts_with(&[10]));
+assert!(v.starts_with(&[10, 40]));
+assert!(v.starts_with(&v));
+assert!(!v.starts_with(&[50]));
+assert!(!v.starts_with(&[10, 50]));Always returns true if needle is an empty slice:
let v = &[10, 40, 30];
+assert!(v.starts_with(&[]));
+let v: &[u8] = &[];
+assert!(v.starts_with(&[]));Returns true if needle is a suffix of the slice or equal to the slice.
let v = [10, 40, 30];
+assert!(v.ends_with(&[30]));
+assert!(v.ends_with(&[40, 30]));
+assert!(v.ends_with(&v));
+assert!(!v.ends_with(&[50]));
+assert!(!v.ends_with(&[50, 30]));Always returns true if needle is an empty slice:
let v = &[10, 40, 30];
+assert!(v.ends_with(&[]));
+let v: &[u8] = &[];
+assert!(v.ends_with(&[]));Returns a subslice with the prefix removed.
+If the slice starts with prefix, returns the subslice after the prefix, wrapped in Some.
+If prefix is empty, simply returns the original slice. If prefix is equal to the
+original slice, returns an empty slice.
If the slice does not start with prefix, returns None.
let v = &[10, 40, 30];
+assert_eq!(v.strip_prefix(&[10]), Some(&[40, 30][..]));
+assert_eq!(v.strip_prefix(&[10, 40]), Some(&[30][..]));
+assert_eq!(v.strip_prefix(&[10, 40, 30]), Some(&[][..]));
+assert_eq!(v.strip_prefix(&[50]), None);
+assert_eq!(v.strip_prefix(&[10, 50]), None);
+
+let prefix : &str = "he";
+assert_eq!(b"hello".strip_prefix(prefix.as_bytes()),
+ Some(b"llo".as_ref()));Returns a subslice with the suffix removed.
+If the slice ends with suffix, returns the subslice before the suffix, wrapped in Some.
+If suffix is empty, simply returns the original slice. If suffix is equal to the
+original slice, returns an empty slice.
If the slice does not end with suffix, returns None.
let v = &[10, 40, 30];
+assert_eq!(v.strip_suffix(&[30]), Some(&[10, 40][..]));
+assert_eq!(v.strip_suffix(&[40, 30]), Some(&[10][..]));
+assert_eq!(v.strip_suffix(&[10, 40, 30]), Some(&[][..]));
+assert_eq!(v.strip_suffix(&[50]), None);
+assert_eq!(v.strip_suffix(&[50, 30]), None);Binary searches this slice for a given element. +If the slice is not sorted, the returned result is unspecified and +meaningless.
+If the value is found then Result::Ok is returned, containing the
+index of the matching element. If there are multiple matches, then any
+one of the matches could be returned. The index is chosen
+deterministically, but is subject to change in future versions of Rust.
+If the value is not found then Result::Err is returned, containing
+the index where a matching element could be inserted while maintaining
+sorted order.
See also binary_search_by, binary_search_by_key, and partition_point.
Looks up a series of four elements. The first is found, with a
+uniquely determined position; the second and third are not
+found; the fourth could match any position in [1, 4].
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+
+assert_eq!(s.binary_search(&13), Ok(9));
+assert_eq!(s.binary_search(&4), Err(7));
+assert_eq!(s.binary_search(&100), Err(13));
+let r = s.binary_search(&1);
+assert!(match r { Ok(1..=4) => true, _ => false, });If you want to find that whole range of matching items, rather than
+an arbitrary matching one, that can be done using partition_point:
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+
+let low = s.partition_point(|x| x < &1);
+assert_eq!(low, 1);
+let high = s.partition_point(|x| x <= &1);
+assert_eq!(high, 5);
+let r = s.binary_search(&1);
+assert!((low..high).contains(&r.unwrap()));
+
+assert!(s[..low].iter().all(|&x| x < 1));
+assert!(s[low..high].iter().all(|&x| x == 1));
+assert!(s[high..].iter().all(|&x| x > 1));
+
+// For something not found, the "range" of equal items is empty
+assert_eq!(s.partition_point(|x| x < &11), 9);
+assert_eq!(s.partition_point(|x| x <= &11), 9);
+assert_eq!(s.binary_search(&11), Err(9));If you want to insert an item to a sorted vector, while maintaining
+sort order, consider using partition_point:
let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+let num = 42;
+let idx = s.partition_point(|&x| x <= num);
+// If `num` is unique, `s.partition_point(|&x| x < num)` (with `<`) is equivalent to
+// `s.binary_search(&num).unwrap_or_else(|x| x)`, but using `<=` will allow `insert`
+// to shift less elements.
+s.insert(idx, num);
+assert_eq!(s, [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]);Binary searches this slice with a comparator function.
+The comparator function should return an order code that indicates
+whether its argument is Less, Equal or Greater the desired
+target.
+If the slice is not sorted or if the comparator function does not
+implement an order consistent with the sort order of the underlying
+slice, the returned result is unspecified and meaningless.
If the value is found then Result::Ok is returned, containing the
+index of the matching element. If there are multiple matches, then any
+one of the matches could be returned. The index is chosen
+deterministically, but is subject to change in future versions of Rust.
+If the value is not found then Result::Err is returned, containing
+the index where a matching element could be inserted while maintaining
+sorted order.
See also binary_search, binary_search_by_key, and partition_point.
Looks up a series of four elements. The first is found, with a
+uniquely determined position; the second and third are not
+found; the fourth could match any position in [1, 4].
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+
+let seek = 13;
+assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Ok(9));
+let seek = 4;
+assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(7));
+let seek = 100;
+assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(13));
+let seek = 1;
+let r = s.binary_search_by(|probe| probe.cmp(&seek));
+assert!(match r { Ok(1..=4) => true, _ => false, });Binary searches this slice with a key extraction function.
+Assumes that the slice is sorted by the key, for instance with
+sort_by_key using the same key extraction function.
+If the slice is not sorted by the key, the returned result is
+unspecified and meaningless.
If the value is found then Result::Ok is returned, containing the
+index of the matching element. If there are multiple matches, then any
+one of the matches could be returned. The index is chosen
+deterministically, but is subject to change in future versions of Rust.
+If the value is not found then Result::Err is returned, containing
+the index where a matching element could be inserted while maintaining
+sorted order.
See also binary_search, binary_search_by, and partition_point.
Looks up a series of four elements in a slice of pairs sorted by
+their second elements. The first is found, with a uniquely
+determined position; the second and third are not found; the
+fourth could match any position in [1, 4].
let s = [(0, 0), (2, 1), (4, 1), (5, 1), (3, 1),
+ (1, 2), (2, 3), (4, 5), (5, 8), (3, 13),
+ (1, 21), (2, 34), (4, 55)];
+
+assert_eq!(s.binary_search_by_key(&13, |&(a, b)| b), Ok(9));
+assert_eq!(s.binary_search_by_key(&4, |&(a, b)| b), Err(7));
+assert_eq!(s.binary_search_by_key(&100, |&(a, b)| b), Err(13));
+let r = s.binary_search_by_key(&1, |&(a, b)| b);
+assert!(match r { Ok(1..=4) => true, _ => false, });Sorts the slice without preserving the initial order of equal elements.
+This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not +allocate), and O(n * log(n)) worst-case.
+If T: Ord does not implement a total order the resulting order is unspecified. All
+original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if T: Ord panics.
The current implementation is based on ipnsort by Lukas Bergdoll and Orson Peters, which +combines the fast average case of quicksort with the fast worst case of heapsort, achieving +linear time on fully sorted and reversed inputs. On inputs with k distinct elements, the +expected time to sort the data is O(n * log(k)).
+It is typically faster than stable sorting, except in a few special cases, e.g., when the +slice is partially sorted.
+If T: Ord does not implement a total order, the implementation may panic.
let mut v = [-5, 4, 1, -3, 2];
+
+v.sort_unstable();
+assert!(v == [-5, -3, 1, 2, 4]);Sorts the slice with a comparator function, without preserving the initial order of +equal elements.
+This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not +allocate), and O(n * log(n)) worst-case.
+The comparator function should define a total ordering for the elements in the slice. If the +ordering is not total, the order of the elements is unspecified.
+If the comparator function does not implement a total order the resulting order is
+unspecified. All original elements will remain in the slice and any possible modifications
+via interior mutability are observed in the input. Same is true if the comparator function
+panics. A total order (for all a, b and c):
a < b, a == b or a > b is true, anda < b and b < c implies a < c. The same must hold for both == and >.For example, while f64 doesn’t implement Ord because NaN != NaN, we can use
+partial_cmp as our sort function when we know the slice doesn’t contain a NaN.
let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
+floats.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap());
+assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);The current implementation is based on ipnsort by Lukas Bergdoll and Orson Peters, which +combines the fast average case of quicksort with the fast worst case of heapsort, achieving +linear time on fully sorted and reversed inputs. On inputs with k distinct elements, the +expected time to sort the data is O(n * log(k)).
+It is typically faster than stable sorting, except in a few special cases, e.g., when the +slice is partially sorted.
+If T: Ord does not implement a total order, the implementation may panic.
let mut v = [5, 4, 1, 3, 2];
+v.sort_unstable_by(|a, b| a.cmp(b));
+assert!(v == [1, 2, 3, 4, 5]);
+
+// reverse sorting
+v.sort_unstable_by(|a, b| b.cmp(a));
+assert!(v == [5, 4, 3, 2, 1]);Sorts the slice with a key extraction function, without preserving the initial order of +equal elements.
+This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not +allocate), and O(n * log(n)) worst-case.
+If K: Ord does not implement a total order the resulting order is unspecified.
+All original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if K: Ord panics.
The current implementation is based on ipnsort by Lukas Bergdoll and Orson Peters, which +combines the fast average case of quicksort with the fast worst case of heapsort, achieving +linear time on fully sorted and reversed inputs. On inputs with k distinct elements, the +expected time to sort the data is O(n * log(k)).
+It is typically faster than stable sorting, except in a few special cases, e.g., when the +slice is partially sorted.
+If K: Ord does not implement a total order, the implementation may panic.
let mut v = [-5i32, 4, 1, -3, 2];
+
+v.sort_unstable_by_key(|k| k.abs());
+assert!(v == [1, 2, -3, 4, -5]);Reorder the slice such that the element at index after the reordering is at its final
+sorted position.
This reordering has the additional property that any value at position i < index will be
+less than or equal to any value at a position j > index. Additionally, this reordering is
+unstable (i.e. any number of equal elements may end up at position index), in-place (i.e.
+does not allocate), and runs in O(n) time. This function is also known as “kth element”
+in other libraries.
It returns a triplet of the following from the reordered slice: the subslice prior to
+index, the element at index, and the subslice after index; accordingly, the values in
+those two subslices will respectively all be less-than-or-equal-to and
+greater-than-or-equal-to the value of the element at index.
The current algorithm is an introselect implementation based on ipnsort by Lukas Bergdoll
+and Orson Peters, which is also the basis for sort_unstable. The fallback algorithm is
+Median of Medians using Tukey’s Ninther for pivot selection, which guarantees linear runtime
+for all inputs.
It is typically faster than stable sorting, except in a few special cases, e.g., when the
+slice is nearly fully sorted, where slice::sort may be faster.
Panics when index >= len(), meaning it always panics on empty slices.
let mut v = [-5i32, 4, 2, -3, 1];
+
+// Find the items less than or equal to the median, the median, and greater than or equal to
+// the median.
+let (lesser, median, greater) = v.select_nth_unstable(2);
+
+assert!(lesser == [-3, -5] || lesser == [-5, -3]);
+assert_eq!(median, &mut 1);
+assert!(greater == [4, 2] || greater == [2, 4]);
+
+// We are only guaranteed the slice will be one of the following, based on the way we sort
+// about the specified index.
+assert!(v == [-3, -5, 1, 2, 4] ||
+ v == [-5, -3, 1, 2, 4] ||
+ v == [-3, -5, 1, 4, 2] ||
+ v == [-5, -3, 1, 4, 2]);Reorder the slice with a comparator function such that the element at index after the
+reordering is at its final sorted position.
This reordering has the additional property that any value at position i < index will be
+less than or equal to any value at a position j > index using the comparator function.
+Additionally, this reordering is unstable (i.e. any number of equal elements may end up at
+position index), in-place (i.e. does not allocate), and runs in O(n) time. This
+function is also known as “kth element” in other libraries.
It returns a triplet of the following from the slice reordered according to the provided
+comparator function: the subslice prior to index, the element at index, and the subslice
+after index; accordingly, the values in those two subslices will respectively all be
+less-than-or-equal-to and greater-than-or-equal-to the value of the element at index.
The current algorithm is an introselect implementation based on ipnsort by Lukas Bergdoll
+and Orson Peters, which is also the basis for sort_unstable. The fallback algorithm is
+Median of Medians using Tukey’s Ninther for pivot selection, which guarantees linear runtime
+for all inputs.
It is typically faster than stable sorting, except in a few special cases, e.g., when the
+slice is nearly fully sorted, where slice::sort may be faster.
Panics when index >= len(), meaning it always panics on empty slices.
let mut v = [-5i32, 4, 2, -3, 1];
+
+// Find the items less than or equal to the median, the median, and greater than or equal to
+// the median as if the slice were sorted in descending order.
+let (lesser, median, greater) = v.select_nth_unstable_by(2, |a, b| b.cmp(a));
+
+assert!(lesser == [4, 2] || lesser == [2, 4]);
+assert_eq!(median, &mut 1);
+assert!(greater == [-3, -5] || greater == [-5, -3]);
+
+// We are only guaranteed the slice will be one of the following, based on the way we sort
+// about the specified index.
+assert!(v == [2, 4, 1, -5, -3] ||
+ v == [2, 4, 1, -3, -5] ||
+ v == [4, 2, 1, -5, -3] ||
+ v == [4, 2, 1, -3, -5]);Reorder the slice with a key extraction function such that the element at index after the
+reordering is at its final sorted position.
This reordering has the additional property that any value at position i < index will be
+less than or equal to any value at a position j > index using the key extraction function.
+Additionally, this reordering is unstable (i.e. any number of equal elements may end up at
+position index), in-place (i.e. does not allocate), and runs in O(n) time. This
+function is also known as “kth element” in other libraries.
It returns a triplet of the following from the slice reordered according to the provided key
+extraction function: the subslice prior to index, the element at index, and the subslice
+after index; accordingly, the values in those two subslices will respectively all be
+less-than-or-equal-to and greater-than-or-equal-to the value of the element at index.
The current algorithm is an introselect implementation based on ipnsort by Lukas Bergdoll
+and Orson Peters, which is also the basis for sort_unstable. The fallback algorithm is
+Median of Medians using Tukey’s Ninther for pivot selection, which guarantees linear runtime
+for all inputs.
It is typically faster than stable sorting, except in a few special cases, e.g., when the
+slice is nearly fully sorted, where slice::sort may be faster.
Panics when index >= len(), meaning it always panics on empty slices.
let mut v = [-5i32, 4, 1, -3, 2];
+
+// Find the items less than or equal to the median, the median, and greater than or equal to
+// the median as if the slice were sorted according to absolute value.
+let (lesser, median, greater) = v.select_nth_unstable_by_key(2, |a| a.abs());
+
+assert!(lesser == [1, 2] || lesser == [2, 1]);
+assert_eq!(median, &mut -3);
+assert!(greater == [4, -5] || greater == [-5, 4]);
+
+// We are only guaranteed the slice will be one of the following, based on the way we sort
+// about the specified index.
+assert!(v == [1, 2, -3, 4, -5] ||
+ v == [1, 2, -3, -5, 4] ||
+ v == [2, 1, -3, 4, -5] ||
+ v == [2, 1, -3, -5, 4]);slice_partition_dedup)Moves all consecutive repeated elements to the end of the slice according to the
+PartialEq trait implementation.
Returns two slices. The first contains no consecutive repeated elements. +The second contains all the duplicates in no specified order.
+If the slice is sorted, the first returned slice contains no duplicates.
+#![feature(slice_partition_dedup)]
+
+let mut slice = [1, 2, 2, 3, 3, 2, 1, 1];
+
+let (dedup, duplicates) = slice.partition_dedup();
+
+assert_eq!(dedup, [1, 2, 3, 2, 1]);
+assert_eq!(duplicates, [2, 3, 1]);slice_partition_dedup)Moves all but the first of consecutive elements to the end of the slice satisfying +a given equality relation.
+Returns two slices. The first contains no consecutive repeated elements. +The second contains all the duplicates in no specified order.
+The same_bucket function is passed references to two elements from the slice and
+must determine if the elements compare equal. The elements are passed in opposite order
+from their order in the slice, so if same_bucket(a, b) returns true, a is moved
+at the end of the slice.
If the slice is sorted, the first returned slice contains no duplicates.
+#![feature(slice_partition_dedup)]
+
+let mut slice = ["foo", "Foo", "BAZ", "Bar", "bar", "baz", "BAZ"];
+
+let (dedup, duplicates) = slice.partition_dedup_by(|a, b| a.eq_ignore_ascii_case(b));
+
+assert_eq!(dedup, ["foo", "BAZ", "Bar", "baz"]);
+assert_eq!(duplicates, ["bar", "Foo", "BAZ"]);slice_partition_dedup)Moves all but the first of consecutive elements to the end of the slice that resolve +to the same key.
+Returns two slices. The first contains no consecutive repeated elements. +The second contains all the duplicates in no specified order.
+If the slice is sorted, the first returned slice contains no duplicates.
+#![feature(slice_partition_dedup)]
+
+let mut slice = [10, 20, 21, 30, 30, 20, 11, 13];
+
+let (dedup, duplicates) = slice.partition_dedup_by_key(|i| *i / 10);
+
+assert_eq!(dedup, [10, 20, 30, 20, 11]);
+assert_eq!(duplicates, [21, 30, 13]);Rotates the slice in-place such that the first mid elements of the
+slice move to the end while the last self.len() - mid elements move to
+the front. After calling rotate_left, the element previously at index
+mid will become the first element in the slice.
This function will panic if mid is greater than the length of the
+slice. Note that mid == self.len() does not panic and is a no-op
+rotation.
Takes linear (in self.len()) time.
let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
+a.rotate_left(2);
+assert_eq!(a, ['c', 'd', 'e', 'f', 'a', 'b']);Rotating a subslice:
+ +let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
+a[1..5].rotate_left(1);
+assert_eq!(a, ['a', 'c', 'd', 'e', 'b', 'f']);Rotates the slice in-place such that the first self.len() - k
+elements of the slice move to the end while the last k elements move
+to the front. After calling rotate_right, the element previously at
+index self.len() - k will become the first element in the slice.
This function will panic if k is greater than the length of the
+slice. Note that k == self.len() does not panic and is a no-op
+rotation.
Takes linear (in self.len()) time.
let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
+a.rotate_right(2);
+assert_eq!(a, ['e', 'f', 'a', 'b', 'c', 'd']);Rotating a subslice:
+ +let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
+a[1..5].rotate_right(1);
+assert_eq!(a, ['a', 'e', 'b', 'c', 'd', 'f']);Fills self with elements by cloning value.
let mut buf = vec![0; 10];
+buf.fill(1);
+assert_eq!(buf, vec![1; 10]);Fills self with elements returned by calling a closure repeatedly.
This method uses a closure to create new values. If you’d rather
+Clone a given value, use fill. If you want to use the Default
+trait to generate values, you can pass Default::default as the
+argument.
let mut buf = vec![1; 10];
+buf.fill_with(Default::default);
+assert_eq!(buf, vec![0; 10]);Copies the elements from src into self.
The length of src must be the same as self.
This function will panic if the two slices have different lengths.
+Cloning two elements from a slice into another:
+ +let src = [1, 2, 3, 4];
+let mut dst = [0, 0];
+
+// Because the slices have to be the same length,
+// we slice the source slice from four elements
+// to two. It will panic if we don't do this.
+dst.clone_from_slice(&src[2..]);
+
+assert_eq!(src, [1, 2, 3, 4]);
+assert_eq!(dst, [3, 4]);Rust enforces that there can only be one mutable reference with no
+immutable references to a particular piece of data in a particular
+scope. Because of this, attempting to use clone_from_slice on a
+single slice will result in a compile failure:
let mut slice = [1, 2, 3, 4, 5];
+
+slice[..2].clone_from_slice(&slice[3..]); // compile fail!To work around this, we can use split_at_mut to create two distinct
+sub-slices from a slice:
let mut slice = [1, 2, 3, 4, 5];
+
+{
+ let (left, right) = slice.split_at_mut(2);
+ left.clone_from_slice(&right[1..]);
+}
+
+assert_eq!(slice, [4, 5, 3, 4, 5]);Copies all elements from src into self, using a memcpy.
The length of src must be the same as self.
If T does not implement Copy, use clone_from_slice.
This function will panic if the two slices have different lengths.
+Copying two elements from a slice into another:
+ +let src = [1, 2, 3, 4];
+let mut dst = [0, 0];
+
+// Because the slices have to be the same length,
+// we slice the source slice from four elements
+// to two. It will panic if we don't do this.
+dst.copy_from_slice(&src[2..]);
+
+assert_eq!(src, [1, 2, 3, 4]);
+assert_eq!(dst, [3, 4]);Rust enforces that there can only be one mutable reference with no
+immutable references to a particular piece of data in a particular
+scope. Because of this, attempting to use copy_from_slice on a
+single slice will result in a compile failure:
let mut slice = [1, 2, 3, 4, 5];
+
+slice[..2].copy_from_slice(&slice[3..]); // compile fail!To work around this, we can use split_at_mut to create two distinct
+sub-slices from a slice:
let mut slice = [1, 2, 3, 4, 5];
+
+{
+ let (left, right) = slice.split_at_mut(2);
+ left.copy_from_slice(&right[1..]);
+}
+
+assert_eq!(slice, [4, 5, 3, 4, 5]);Copies elements from one part of the slice to another part of itself, +using a memmove.
+src is the range within self to copy from. dest is the starting
+index of the range within self to copy to, which will have the same
+length as src. The two ranges may overlap. The ends of the two ranges
+must be less than or equal to self.len().
This function will panic if either range exceeds the end of the slice,
+or if the end of src is before the start.
Copying four bytes within a slice:
+ +let mut bytes = *b"Hello, World!";
+
+bytes.copy_within(1..5, 8);
+
+assert_eq!(&bytes, b"Hello, Wello!");Swaps all elements in self with those in other.
The length of other must be the same as self.
This function will panic if the two slices have different lengths.
+Swapping two elements across slices:
+ +let mut slice1 = [0, 0];
+let mut slice2 = [1, 2, 3, 4];
+
+slice1.swap_with_slice(&mut slice2[2..]);
+
+assert_eq!(slice1, [3, 4]);
+assert_eq!(slice2, [1, 2, 0, 0]);Rust enforces that there can only be one mutable reference to a
+particular piece of data in a particular scope. Because of this,
+attempting to use swap_with_slice on a single slice will result in
+a compile failure:
let mut slice = [1, 2, 3, 4, 5];
+slice[..2].swap_with_slice(&mut slice[3..]); // compile fail!To work around this, we can use split_at_mut to create two distinct
+mutable sub-slices from a slice:
let mut slice = [1, 2, 3, 4, 5];
+
+{
+ let (left, right) = slice.split_at_mut(2);
+ left.swap_with_slice(&mut right[1..]);
+}
+
+assert_eq!(slice, [4, 5, 3, 1, 2]);Transmute the slice to a slice of another type, ensuring alignment of the types is +maintained.
+This method splits the slice into three distinct slices: prefix, correctly aligned middle +slice of a new type, and the suffix slice. The middle part will be as big as possible under +the given alignment constraint and element size.
+This method has no purpose when either input element T or output element U are
+zero-sized and will return the original slice without splitting anything.
This method is essentially a transmute with respect to the elements in the returned
+middle slice, so all the usual caveats pertaining to transmute::<T, U> also apply here.
Basic usage:
+ +unsafe {
+ let bytes: [u8; 7] = [1, 2, 3, 4, 5, 6, 7];
+ let (prefix, shorts, suffix) = bytes.align_to::<u16>();
+ // less_efficient_algorithm_for_bytes(prefix);
+ // more_efficient_algorithm_for_aligned_shorts(shorts);
+ // less_efficient_algorithm_for_bytes(suffix);
+}Transmute the mutable slice to a mutable slice of another type, ensuring alignment of the +types is maintained.
+This method splits the slice into three distinct slices: prefix, correctly aligned middle +slice of a new type, and the suffix slice. The middle part will be as big as possible under +the given alignment constraint and element size.
+This method has no purpose when either input element T or output element U are
+zero-sized and will return the original slice without splitting anything.
This method is essentially a transmute with respect to the elements in the returned
+middle slice, so all the usual caveats pertaining to transmute::<T, U> also apply here.
Basic usage:
+ +unsafe {
+ let mut bytes: [u8; 7] = [1, 2, 3, 4, 5, 6, 7];
+ let (prefix, shorts, suffix) = bytes.align_to_mut::<u16>();
+ // less_efficient_algorithm_for_bytes(prefix);
+ // more_efficient_algorithm_for_aligned_shorts(shorts);
+ // less_efficient_algorithm_for_bytes(suffix);
+}portable_simd)Split a slice into a prefix, a middle of aligned SIMD types, and a suffix.
+This is a safe wrapper around slice::align_to, so has the same weak
+postconditions as that method. You’re only assured that
+self.len() == prefix.len() + middle.len() * LANES + suffix.len().
Notably, all of the following are possible:
+prefix.len() >= LANES.middle.is_empty() despite self.len() >= 3 * LANES.suffix.len() >= LANES.That said, this is a safe method, so if you’re only writing safe code, +then this can at most cause incorrect logic, not unsoundness.
+This will panic if the size of the SIMD type is different from
+LANES times that of the scalar.
At the time of writing, the trait restrictions on Simd<T, LANES> keeps
+that from ever happening, as only power-of-two numbers of lanes are
+supported. It’s possible that, in the future, those restrictions might
+be lifted in a way that would make it possible to see panics from this
+method for something like LANES == 3.
#![feature(portable_simd)]
+use core::simd::prelude::*;
+
+let short = &[1, 2, 3];
+let (prefix, middle, suffix) = short.as_simd::<4>();
+assert_eq!(middle, []); // Not enough elements for anything in the middle
+
+// They might be split in any possible way between prefix and suffix
+let it = prefix.iter().chain(suffix).copied();
+assert_eq!(it.collect::<Vec<_>>(), vec![1, 2, 3]);
+
+fn basic_simd_sum(x: &[f32]) -> f32 {
+ use std::ops::Add;
+ let (prefix, middle, suffix) = x.as_simd();
+ let sums = f32x4::from_array([
+ prefix.iter().copied().sum(),
+ 0.0,
+ 0.0,
+ suffix.iter().copied().sum(),
+ ]);
+ let sums = middle.iter().copied().fold(sums, f32x4::add);
+ sums.reduce_sum()
+}
+
+let numbers: Vec<f32> = (1..101).map(|x| x as _).collect();
+assert_eq!(basic_simd_sum(&numbers[1..99]), 4949.0);portable_simd)Split a mutable slice into a mutable prefix, a middle of aligned SIMD types, +and a mutable suffix.
+This is a safe wrapper around slice::align_to_mut, so has the same weak
+postconditions as that method. You’re only assured that
+self.len() == prefix.len() + middle.len() * LANES + suffix.len().
Notably, all of the following are possible:
+prefix.len() >= LANES.middle.is_empty() despite self.len() >= 3 * LANES.suffix.len() >= LANES.That said, this is a safe method, so if you’re only writing safe code, +then this can at most cause incorrect logic, not unsoundness.
+This is the mutable version of slice::as_simd; see that for examples.
This will panic if the size of the SIMD type is different from
+LANES times that of the scalar.
At the time of writing, the trait restrictions on Simd<T, LANES> keeps
+that from ever happening, as only power-of-two numbers of lanes are
+supported. It’s possible that, in the future, those restrictions might
+be lifted in a way that would make it possible to see panics from this
+method for something like LANES == 3.
is_sorted)Checks if the elements of this slice are sorted.
+That is, for each element a and its following element b, a <= b must hold. If the
+slice yields exactly zero or one element, true is returned.
Note that if Self::Item is only PartialOrd, but not Ord, the above definition
+implies that this function returns false if any two consecutive items are not
+comparable.
#![feature(is_sorted)]
+let empty: [i32; 0] = [];
+
+assert!([1, 2, 2, 9].is_sorted());
+assert!(![1, 3, 2, 4].is_sorted());
+assert!([0].is_sorted());
+assert!(empty.is_sorted());
+assert!(![0.0, 1.0, f32::NAN].is_sorted());is_sorted)Checks if the elements of this slice are sorted using the given comparator function.
+Instead of using PartialOrd::partial_cmp, this function uses the given compare
+function to determine whether two elements are to be considered in sorted order.
#![feature(is_sorted)]
+
+assert!([1, 2, 2, 9].is_sorted_by(|a, b| a <= b));
+assert!(![1, 2, 2, 9].is_sorted_by(|a, b| a < b));
+
+assert!([0].is_sorted_by(|a, b| true));
+assert!([0].is_sorted_by(|a, b| false));
+
+let empty: [i32; 0] = [];
+assert!(empty.is_sorted_by(|a, b| false));
+assert!(empty.is_sorted_by(|a, b| true));is_sorted)Checks if the elements of this slice are sorted using the given key extraction function.
+Instead of comparing the slice’s elements directly, this function compares the keys of the
+elements, as determined by f. Apart from that, it’s equivalent to is_sorted; see its
+documentation for more information.
#![feature(is_sorted)]
+
+assert!(["c", "bb", "aaa"].is_sorted_by_key(|s| s.len()));
+assert!(![-2i32, -1, 0, 3].is_sorted_by_key(|n| n.abs()));Returns the index of the partition point according to the given predicate +(the index of the first element of the second partition).
+The slice is assumed to be partitioned according to the given predicate.
+This means that all elements for which the predicate returns true are at the start of the slice
+and all elements for which the predicate returns false are at the end.
+For example, [7, 15, 3, 5, 4, 12, 6] is partitioned under the predicate x % 2 != 0
+(all odd numbers are at the start, all even at the end).
If this slice is not partitioned, the returned result is unspecified and meaningless, +as this method performs a kind of binary search.
+See also binary_search, binary_search_by, and binary_search_by_key.
let v = [1, 2, 3, 3, 5, 6, 7];
+let i = v.partition_point(|&x| x < 5);
+
+assert_eq!(i, 4);
+assert!(v[..i].iter().all(|&x| x < 5));
+assert!(v[i..].iter().all(|&x| !(x < 5)));If all elements of the slice match the predicate, including if the slice +is empty, then the length of the slice will be returned:
+ +let a = [2, 4, 8];
+assert_eq!(a.partition_point(|x| x < &100), a.len());
+let a: [i32; 0] = [];
+assert_eq!(a.partition_point(|x| x < &100), 0);If you want to insert an item to a sorted vector, while maintaining +sort order:
+ +let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+let num = 42;
+let idx = s.partition_point(|&x| x <= num);
+s.insert(idx, num);
+assert_eq!(s, [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]);slice_take)Removes the subslice corresponding to the given range +and returns a reference to it.
+Returns None and does not modify the slice if the given
+range is out of bounds.
Note that this method only accepts one-sided ranges such as
+2.. or ..6, but not 2..6.
Taking the first three elements of a slice:
+ +#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c', 'd'];
+let mut first_three = slice.take(..3).unwrap();
+
+assert_eq!(slice, &['d']);
+assert_eq!(first_three, &['a', 'b', 'c']);Taking the last two elements of a slice:
+ +#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c', 'd'];
+let mut tail = slice.take(2..).unwrap();
+
+assert_eq!(slice, &['a', 'b']);
+assert_eq!(tail, &['c', 'd']);Getting None when range is out of bounds:
#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c', 'd'];
+
+assert_eq!(None, slice.take(5..));
+assert_eq!(None, slice.take(..5));
+assert_eq!(None, slice.take(..=4));
+let expected: &[char] = &['a', 'b', 'c', 'd'];
+assert_eq!(Some(expected), slice.take(..4));slice_take)Removes the subslice corresponding to the given range +and returns a mutable reference to it.
+Returns None and does not modify the slice if the given
+range is out of bounds.
Note that this method only accepts one-sided ranges such as
+2.. or ..6, but not 2..6.
Taking the first three elements of a slice:
+ +#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd'];
+let mut first_three = slice.take_mut(..3).unwrap();
+
+assert_eq!(slice, &mut ['d']);
+assert_eq!(first_three, &mut ['a', 'b', 'c']);Taking the last two elements of a slice:
+ +#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd'];
+let mut tail = slice.take_mut(2..).unwrap();
+
+assert_eq!(slice, &mut ['a', 'b']);
+assert_eq!(tail, &mut ['c', 'd']);Getting None when range is out of bounds:
#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd'];
+
+assert_eq!(None, slice.take_mut(5..));
+assert_eq!(None, slice.take_mut(..5));
+assert_eq!(None, slice.take_mut(..=4));
+let expected: &mut [_] = &mut ['a', 'b', 'c', 'd'];
+assert_eq!(Some(expected), slice.take_mut(..4));slice_take)Removes the first element of the slice and returns a reference +to it.
+Returns None if the slice is empty.
#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c'];
+let first = slice.take_first().unwrap();
+
+assert_eq!(slice, &['b', 'c']);
+assert_eq!(first, &'a');slice_take)Removes the first element of the slice and returns a mutable +reference to it.
+Returns None if the slice is empty.
#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c'];
+let first = slice.take_first_mut().unwrap();
+*first = 'd';
+
+assert_eq!(slice, &['b', 'c']);
+assert_eq!(first, &'d');slice_take)Removes the last element of the slice and returns a reference +to it.
+Returns None if the slice is empty.
#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c'];
+let last = slice.take_last().unwrap();
+
+assert_eq!(slice, &['a', 'b']);
+assert_eq!(last, &'c');slice_take)Removes the last element of the slice and returns a mutable +reference to it.
+Returns None if the slice is empty.
#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c'];
+let last = slice.take_last_mut().unwrap();
+*last = 'd';
+
+assert_eq!(slice, &['a', 'b']);
+assert_eq!(last, &'d');get_many_mut)Returns mutable references to many indices at once, without doing any checks.
+For a safe alternative see get_many_mut.
Calling this method with overlapping or out-of-bounds indices is undefined behavior +even if the resulting references are not used.
+#![feature(get_many_mut)]
+
+let x = &mut [1, 2, 4];
+
+unsafe {
+ let [a, b] = x.get_many_unchecked_mut([0, 2]);
+ *a *= 10;
+ *b *= 100;
+}
+assert_eq!(x, &[10, 2, 400]);get_many_mut)Returns mutable references to many indices at once.
+Returns an error if any index is out-of-bounds, or if the same index was +passed more than once.
+#![feature(get_many_mut)]
+
+let v = &mut [1, 2, 3];
+if let Ok([a, b]) = v.get_many_mut([0, 2]) {
+ *a = 413;
+ *b = 612;
+}
+assert_eq!(v, &[413, 2, 612]);Sorts the slice, preserving initial order of equal elements.
+This sort is stable (i.e., does not reorder equal elements) and O(n * log(n)) +worst-case.
+If T: Ord does not implement a total order the resulting order is unspecified. All
+original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if T: Ord panics.
When applicable, unstable sorting is preferred because it is generally faster than stable
+sorting and it doesn’t allocate auxiliary memory. See
+sort_unstable. The exception are partially sorted slices, which
+may be better served with slice::sort.
The current implementation is based on driftsort by Orson Peters and Lukas Bergdoll, which +combines the fast average case of quicksort with the fast worst case and partial run +detection of mergesort, achieving linear time on fully sorted and reversed inputs. On inputs +with k distinct elements, the expected time to sort the data is O(n * log(k)).
+The auxiliary memory allocation behavior depends on the input length. Short slices are
+handled without allocation, medium sized slices allocate self.len() and beyond that it
+clamps at self.len() / 2.
If T: Ord does not implement a total order, the implementation may panic.
let mut v = [-5, 4, 1, -3, 2];
+
+v.sort();
+assert!(v == [-5, -3, 1, 2, 4]);Sorts the slice with a comparator function, preserving initial order of equal elements.
+This sort is stable (i.e., does not reorder equal elements) and O(n * log(n)) +worst-case.
+The comparator function should define a total ordering for the elements in the slice. If the +ordering is not total, the order of the elements is unspecified.
+If the comparator function does not implement a total order the resulting order is
+unspecified. All original elements will remain in the slice and any possible modifications
+via interior mutability are observed in the input. Same is true if the comparator function
+panics. A total order (for all a, b and c):
a < b, a == b or a > b is true, anda < b and b < c implies a < c. The same must hold for both == and >.For example, while f64 doesn’t implement Ord because NaN != NaN, we can use
+partial_cmp as our sort function when we know the slice doesn’t contain a NaN.
let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
+floats.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap());
+assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);The current implementation is based on driftsort by Orson Peters and Lukas Bergdoll, which +combines the fast average case of quicksort with the fast worst case and partial run +detection of mergesort, achieving linear time on fully sorted and reversed inputs. On inputs +with k distinct elements, the expected time to sort the data is O(n * log(k)).
+The auxiliary memory allocation behavior depends on the input length. Short slices are
+handled without allocation, medium sized slices allocate self.len() and beyond that it
+clamps at self.len() / 2.
If T: Ord does not implement a total order, the implementation may panic.
let mut v = [5, 4, 1, 3, 2];
+v.sort_by(|a, b| a.cmp(b));
+assert!(v == [1, 2, 3, 4, 5]);
+
+// reverse sorting
+v.sort_by(|a, b| b.cmp(a));
+assert!(v == [5, 4, 3, 2, 1]);Sorts the slice with a key extraction function, preserving initial order of equal elements.
+This sort is stable (i.e., does not reorder equal elements) and O(m * n * log(n)) +worst-case, where the key function is O(m).
+If K: Ord does not implement a total order the resulting order is unspecified.
+All original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if K: Ord panics.
The current implementation is based on driftsort by Orson Peters and Lukas Bergdoll, which +combines the fast average case of quicksort with the fast worst case and partial run +detection of mergesort, achieving linear time on fully sorted and reversed inputs. On inputs +with k distinct elements, the expected time to sort the data is O(n * log(k)).
+The auxiliary memory allocation behavior depends on the input length. Short slices are
+handled without allocation, medium sized slices allocate self.len() and beyond that it
+clamps at self.len() / 2.
If K: Ord does not implement a total order, the implementation may panic.
let mut v = [-5i32, 4, 1, -3, 2];
+
+v.sort_by_key(|k| k.abs());
+assert!(v == [1, 2, -3, 4, -5]);Sorts the slice with a key extraction function, preserving initial order of equal elements.
+This sort is stable (i.e., does not reorder equal elements) and O(m * n + n * +log(n)) worst-case, where the key function is O(m).
+During sorting, the key function is called at most once per element, by using temporary +storage to remember the results of key evaluation. The order of calls to the key function is +unspecified and may change in future versions of the standard library.
+If K: Ord does not implement a total order the resulting order is unspecified.
+All original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if K: Ord panics.
For simple key functions (e.g., functions that are property accesses or basic operations),
+sort_by_key is likely to be faster.
The current implementation is based on instruction-parallel-network sort by Lukas +Bergdoll, which combines the fast average case of randomized quicksort with the fast worst +case of heapsort, while achieving linear time on fully sorted and reversed inputs. And +O(k * log(n)) where k is the number of distinct elements in the input. It leverages +superscalar out-of-order execution capabilities commonly found in CPUs, to efficiently +perform the operation.
+In the worst case, the algorithm allocates temporary storage in a Vec<(K, usize)> the
+length of the slice.
let mut v = [-5i32, 4, 32, -3, 2];
+
+v.sort_by_cached_key(|k| k.to_string());
+assert!(v == [-3, -5, 2, 32, 4]);Copies self into a new Vec.
let s = [10, 40, 30];
+let x = s.to_vec();
+// Here, `s` and `x` can be modified independently.allocator_api)Copies self into a new Vec with an allocator.
#![feature(allocator_api)]
+
+use std::alloc::System;
+
+let s = [10, 40, 30];
+let x = s.to_vec_in(System);
+// Here, `s` and `x` can be modified independently.Flattens a slice of T into a single value Self::Output.
assert_eq!(["hello", "world"].concat(), "helloworld");
+assert_eq!([[1, 2], [3, 4]].concat(), [1, 2, 3, 4]);Flattens a slice of T into a single value Self::Output, placing a
+given separator between each.
assert_eq!(["hello", "world"].join(" "), "hello world");
+assert_eq!([[1, 2], [3, 4]].join(&0), [1, 2, 0, 3, 4]);
+assert_eq!([[1, 2], [3, 4]].join(&[0, 0][..]), [1, 2, 0, 0, 3, 4]);Flattens a slice of T into a single value Self::Output, placing a
+given separator between each.
assert_eq!(["hello", "world"].connect(" "), "hello world");
+assert_eq!([[1, 2], [3, 4]].connect(&0), [1, 2, 0, 3, 4]);Returns a vector containing a copy of this slice where each byte +is mapped to its ASCII upper case equivalent.
+ASCII letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’, +but non-ASCII letters are unchanged.
+To uppercase the value in-place, use make_ascii_uppercase.
Returns a vector containing a copy of this slice where each byte +is mapped to its ASCII lower case equivalent.
+ASCII letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’, +but non-ASCII letters are unchanged.
+To lowercase the value in-place, use make_ascii_lowercase.
Self from the given unstructured data. Read moreSelf from the entirety of the given
+unstructured data. Read moresource. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub struct StatsCollector {
+ pub sync_get_count: usize,
+ pub sync_get_prefixes_count: usize,
+ pub sync_iterate_count: usize,
+ /* private fields */
+}A proxy read syncer which keeps track of call statistics.
+sync_get_count: usizeCount of sync_get calls made to the underlying read syncer.
sync_get_prefixes_count: usizeCount of sync_get_prefixes calls made to the underlying read syncer.
sync_iterate_count: usizeCount of sync_iterate calls made to the underlying read syncer.
Construct a new instance, proxying to the given backing read syncer.
+pub struct TreeID {
+ pub root: Root,
+ pub position: Hash,
+}Identifies a specific tree and a position within that tree.
+root: RootThe Merkle tree root.
+position: HashThe caller’s position in the tree structure to allow +returning partial proofs if possible.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub trait ReadSync {
+ // Required methods
+ fn as_any(&self) -> &dyn Any;
+ fn sync_get(&mut self, request: GetRequest) -> Result<ProofResponse>;
+ fn sync_get_prefixes(
+ &mut self,
+ request: GetPrefixesRequest,
+ ) -> Result<ProofResponse>;
+ fn sync_iterate(&mut self, request: IterateRequest) -> Result<ProofResponse>;
+}ReadSync is the interface for synchronizing the in-memory cache +with another (potentially untrusted) MKVS.
+Fetch a single key and returns the corresponding proof.
+Fetch all keys under the given prefixes and returns the corresponding proofs.
+Seek to a given key and then fetch the specified number of following items +based on key iteration order.
+pub trait FallibleMKVS {
+ // Required methods
+ fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>>;
+ fn get_proof(&self, key: &[u8]) -> Result<Option<Proof>>;
+ fn cache_contains_key(&self, key: &[u8]) -> bool;
+ fn insert(&mut self, key: &[u8], value: &[u8]) -> Result<Option<Vec<u8>>>;
+ fn remove(&mut self, key: &[u8]) -> Result<Option<Vec<u8>>>;
+ fn prefetch_prefixes(&self, prefixes: &[Prefix], limit: u16) -> Result<()>;
+ fn iter(&self) -> Box<dyn Iterator + '_>;
+ fn commit(&mut self, namespace: Namespace, version: u64) -> Result<Hash>;
+}Merklized key-value store where methods return errors instead of panicking.
+Fetch proof for entry with given key.
+Check if the local MKVS cache contains the given key.
+While get can be used to check if the MKVS as a whole contains +a given key, this function specifically guarantees that no remote +syncing will be invoked, only checking the local cache.
+Update entry with given key.
+If the database did not have this key present, None is returned.
If the database did have this key present, the value is updated, and the old value is +returned.
+Remove entry with given key, returning the value at the key if the key was previously +in the database.
+pub trait ImmutableMKVS {
+ // Required methods
+ fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>>;
+ fn get_proof(&self, key: &[u8]) -> Result<Option<Proof>>;
+ fn prefetch_prefixes(&self, prefixes: &[Prefix], limit: u16) -> Result<()>;
+ fn iter(&self) -> Box<dyn Iterator + '_>;
+}Immutable merkalized key value store.
+Fetch proof for entry with given key.
+pub trait Iterator: Iterator<Item = (Vec<u8>, Vec<u8>)> {
+ // Required methods
+ fn set_prefetch(&mut self, prefetch: usize);
+ fn is_valid(&self) -> bool;
+ fn error(&self) -> &Option<Error>;
+ fn rewind(&mut self);
+ fn seek(&mut self, key: &[u8]);
+ fn get_key(&self) -> &Option<Key>;
+ fn get_value(&self) -> &Option<Vec<u8>>;
+ fn next(&mut self);
+}An MKVS iterator.
+Sets the number of next elements to prefetch.
+pub trait MKVS {
+ // Required methods
+ fn get(&self, key: &[u8]) -> Option<Vec<u8>>;
+ fn get_proof(&self, key: &[u8]) -> Option<Proof>;
+ fn cache_contains_key(&self, key: &[u8]) -> bool;
+ fn insert(&mut self, key: &[u8], value: &[u8]) -> Option<Vec<u8>>;
+ fn remove(&mut self, key: &[u8]) -> Option<Vec<u8>>;
+ fn prefetch_prefixes(&self, prefixes: &[Prefix], limit: u16);
+ fn iter(&self) -> Box<dyn Iterator + '_>;
+ fn commit(
+ &mut self,
+ namespace: Namespace,
+ version: u64,
+ ) -> Result<(WriteLog, Hash)>;
+}Merklized key-value store.
+Check if the local MKVS cache contains the given key.
+While get can be used to check if the MKVS as a whole contains +a given key, this function specifically guarantees that no remote +syncing will be invoked, only checking the local cache.
+Update entry with given key.
+If the database did not have this key present, None is returned.
If the database did have this key present, the value is updated, and the old value is +returned.
+Remove entry with given key, returning the value at the key if the key was previously +in the database.
+Populate the in-memory tree with nodes for keys starting with given prefixes.
+Redirecting to ../../../../../oasis_core_runtime/storage/mkvs/enum.NodeBox.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/tree/node/enum.RootType.html b/rust/oasis_core_runtime/storage/mkvs/tree/node/enum.RootType.html new file mode 100644 index 0000000000..35115b13e9 --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/tree/node/enum.RootType.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/storage/mkvs/enum.RootType.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/tree/node/struct.NodePointer.html b/rust/oasis_core_runtime/storage/mkvs/tree/node/struct.NodePointer.html new file mode 100644 index 0000000000..f61d26d524 --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/tree/node/struct.NodePointer.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/storage/mkvs/struct.NodePointer.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/tree/node/struct.Root.html b/rust/oasis_core_runtime/storage/mkvs/tree/node/struct.Root.html new file mode 100644 index 0000000000..200016b118 --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/tree/node/struct.Root.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/storage/mkvs/struct.Root.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/tree/node/type.Depth.html b/rust/oasis_core_runtime/storage/mkvs/tree/node/type.Depth.html new file mode 100644 index 0000000000..69ff461108 --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/tree/node/type.Depth.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/storage/mkvs/type.Depth.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/tree/node/type.Key.html b/rust/oasis_core_runtime/storage/mkvs/tree/node/type.Key.html new file mode 100644 index 0000000000..aad7a2c6c1 --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/tree/node/type.Key.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/storage/mkvs/type.Key.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/tree/node/type.NodePtrRef.html b/rust/oasis_core_runtime/storage/mkvs/tree/node/type.NodePtrRef.html new file mode 100644 index 0000000000..75f222ad35 --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/tree/node/type.NodePtrRef.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/storage/mkvs/type.NodePtrRef.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/tree/overlay/struct.OverlayTree.html b/rust/oasis_core_runtime/storage/mkvs/tree/overlay/struct.OverlayTree.html new file mode 100644 index 0000000000..2afe9447db --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/tree/overlay/struct.OverlayTree.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_core_runtime/storage/mkvs/struct.OverlayTree.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/tree/struct.Tree.html b/rust/oasis_core_runtime/storage/mkvs/tree/struct.Tree.html new file mode 100644 index 0000000000..44c0a4ea0d --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/tree/struct.Tree.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../oasis_core_runtime/storage/mkvs/struct.Tree.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_core_runtime/storage/mkvs/type.Depth.html b/rust/oasis_core_runtime/storage/mkvs/type.Depth.html new file mode 100644 index 0000000000..0a9b06ab92 --- /dev/null +++ b/rust/oasis_core_runtime/storage/mkvs/type.Depth.html @@ -0,0 +1 @@ +pub type NodePtrRef = Rc<RefCell<NodePointer>>;A reference-counted pointer to a pointer.
+struct NodePtrRef { /* private fields */ }pub struct UntrustedInMemoryStorage { /* private fields */ }Untrusted key/value storage which stores arbitrary binary key/value pairs +in memory.
+pub trait KeyValue: Send + Sync {
+ // Required methods
+ fn get(&self, key: Vec<u8>) -> Result<Vec<u8>, Error>;
+ fn insert(&self, key: Vec<u8>, value: Vec<u8>) -> Result<(), Error>;
+}Trivial key/value storage.
+pub struct BUILD_INFO { /* private fields */ }pub struct BuildInfo {
+ pub tee_type: TeeType,
+ pub protocol_version: Version,
+ pub is_secure: bool,
+}Runtime build information.
+tee_type: TeeTypeTEE type this build is for.
+protocol_version: VersionSupported runtime protocol version.
+is_secure: boolTrue iff the build can provide integrity and confidentiality.
+Runtime call context.
+pub struct Context<'a> {
+ pub protocol: Arc<Protocol>,
+ pub consensus_block: &'a LightBlock,
+ pub consensus_state: ConsensusState,
+ pub runtime_state: &'a mut dyn MKVS,
+ pub header: &'a Header,
+ pub epoch: EpochTime,
+ pub round_results: &'a RoundResults,
+ pub max_messages: u32,
+ pub check_only: bool,
+}Transaction context.
+protocol: Arc<Protocol>Low-level access to the underlying Runtime Host Protocol.
+consensus_block: &'a LightBlockConsensus light block.
+consensus_state: ConsensusStateConsensus state tree.
+runtime_state: &'a mut dyn MKVSRuntime state.
+header: &'a HeaderThe block header accompanying this transaction.
+epoch: EpochTimeEpoch corresponding to the currently processed block.
+round_results: &'a RoundResultsResults of processing the previous successful round.
+max_messages: u32The maximum number of messages that can be emitted in this round.
+check_only: boolFlag indicating whether to only perform transaction check rather than +running the transaction.
+Construct new transaction context.
+Runtime transaction batch dispatcher.
+pub struct ExecuteBatchResult {
+ pub results: Vec<ExecuteTxResult>,
+ pub messages: Vec<Message>,
+ pub in_msgs_count: usize,
+ pub block_tags: Tags,
+ pub tx_reject_hashes: Vec<Hash>,
+}Result of processing a batch of ExecuteTx.
+results: Vec<ExecuteTxResult>Per-transaction execution results.
+messages: Vec<Message>Emitted runtime messages.
+in_msgs_count: usizeNumber of processed incoming messages.
+Block emitted tags (not emitted by a specific transaction).
+tx_reject_hashes: Vec<Hash>Hashes of transactions to reject.
+Note that these are only taken into account in schedule execution mode.
+pub struct ExecuteTxResult {
+ pub output: Vec<u8>,
+ pub tags: Tags,
+}Result of processing an ExecuteTx.
+output: Vec<u8>Transaction output.
+Emitted tags.
+pub struct NoopDispatcher;No-op dispatcher.
+This is mainly used by the runtime dispatcher as a fallback in case +the runtime’s initializer doesn’t produce its own dispatcher object.
+pub trait Dispatcher: Send + Sync {
+ // Required methods
+ fn execute_batch(
+ &self,
+ ctx: Context<'_>,
+ batch: &TxnBatch,
+ in_msgs: &[IncomingMessage],
+ ) -> Result<ExecuteBatchResult, RuntimeError>;
+ fn check_batch(
+ &self,
+ ctx: Context<'_>,
+ batch: &TxnBatch,
+ ) -> Result<Vec<CheckTxResult>, RuntimeError>;
+
+ // Provided methods
+ fn is_supported(&self) -> bool { ... }
+ fn schedule_and_execute_batch(
+ &self,
+ _ctx: Context<'_>,
+ _initial_batch: &mut TxnBatch,
+ _in_msgs: &[IncomingMessage],
+ ) -> Result<ExecuteBatchResult, RuntimeError> { ... }
+ fn finalize(&self, _new_storage_root: Hash) { ... }
+ fn set_abort_batch_flag(&mut self, _abort_batch: Arc<AtomicBool>) { ... }
+ fn query(
+ &self,
+ _ctx: Context<'_>,
+ _method: &str,
+ _args: Vec<u8>,
+ ) -> Result<Vec<u8>, RuntimeError> { ... }
+}Runtime transaction dispatcher trait.
+It defines the interface used by the runtime call dispatcher +to process transactions.
+Execute the transactions in the given batch.
+Before this method is invoked, consensus layer state integrity verification is performed.
+Check the transactions in the given batch for validity.
+No consensus layer state integrity verification is performed for queries by default. The +runtime dispatcher implementation should perform integrity verification if needed on a +query-by-query basis.
+Whether dispatch is supported by this dispatcher.
+Schedule and execute transactions in the given batch.
+The passed batch is an initial batch. In case the runtime needs additional items it should +request them from the host.
+Before this method is invoked, consensus layer state integrity verification is performed.
+Configure abort batch flag.
+Process a query.
+No consensus layer state integrity verification is performed for queries by default. The +runtime dispatcher implementation should perform integrity verification if needed on a +query-by-query basis.
+Runtime transaction processing.
+pub use self::context::Context;Read/write set.
+pub struct CoarsenedKey(pub Vec<u8>);A coarsened key prefix that represents any key that starts with +this prefix.
+0: Vec<u8>source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub struct ReadWriteSet {
+ pub granularity: u16,
+ pub read_set: CoarsenedSet,
+ pub write_set: CoarsenedSet,
+}A read/write set.
+granularity: u16Size of the key prefixes (in bytes) used for coarsening the keys.
+read_set: CoarsenedSetThe read set.
+write_set: CoarsenedSetThe write set.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub type CoarsenedSet = Vec<CoarsenedKey>;A set of coarsened keys.
+struct CoarsenedSet { /* private fields */ }Transaction tags.
+pub struct Tag {
+ pub key: Vec<u8>,
+ pub value: Vec<u8>,
+ pub tx_hash: Hash,
+}Tag is a key/value pair of arbitrary byte blobs with runtime-dependent +semantics which can be indexed to allow easier lookup of blocks and +transactions on runtime clients.
+key: Vec<u8>The tag key.
+value: Vec<u8>The tag value.
+tx_hash: HashThe hash of the transaction that emitted the tag.
+clone_to_uninit)pub type Tags = Vec<Tag>;A set of tags.
+struct Tags { /* private fields */ }pub const TAG_BLOCK_TX_HASH: Hash;Hash used for block emitted tags not tied to a specific transaction.
+Transaction I/O tree.
+pub struct Tree { /* private fields */ }A Merkle tree containing transaction artifacts.
+Create a new transaction artifacts tree.
+Add an input transaction artifact.
+Add an output transaction artifact.
+Add block tags.
+Transaction protocol types.
+pub struct TxnBatch(pub Vec<Vec<u8>>);Batch of transaction inputs/outputs.
+0: Vec<Vec<u8>>Returns the total number of elements the vector can hold without +reallocating.
+let mut vec: Vec<i32> = Vec::with_capacity(10);
+vec.push(42);
+assert!(vec.capacity() >= 10);Reserves capacity for at least additional more elements to be inserted
+in the given Vec<T>. The collection may reserve more space to
+speculatively avoid frequent reallocations. After calling reserve,
+capacity will be greater than or equal to self.len() + additional.
+Does nothing if capacity is already sufficient.
Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1];
+vec.reserve(10);
+assert!(vec.capacity() >= 11);Reserves the minimum capacity for at least additional more elements to
+be inserted in the given Vec<T>. Unlike reserve, this will not
+deliberately over-allocate to speculatively avoid frequent allocations.
+After calling reserve_exact, capacity will be greater than or equal to
+self.len() + additional. Does nothing if the capacity is already
+sufficient.
Note that the allocator may give the collection more space than it
+requests. Therefore, capacity can not be relied upon to be precisely
+minimal. Prefer reserve if future insertions are expected.
Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1];
+vec.reserve_exact(10);
+assert!(vec.capacity() >= 11);Tries to reserve capacity for at least additional more elements to be inserted
+in the given Vec<T>. The collection may reserve more space to speculatively avoid
+frequent reallocations. After calling try_reserve, capacity will be
+greater than or equal to self.len() + additional if it returns
+Ok(()). Does nothing if capacity is already sufficient. This method
+preserves the contents even if an error occurs.
If the capacity overflows, or the allocator reports a failure, then an error +is returned.
+use std::collections::TryReserveError;
+
+fn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {
+ let mut output = Vec::new();
+
+ // Pre-reserve the memory, exiting if we can't
+ output.try_reserve(data.len())?;
+
+ // Now we know this can't OOM in the middle of our complex work
+ output.extend(data.iter().map(|&val| {
+ val * 2 + 5 // very complicated
+ }));
+
+ Ok(output)
+}Tries to reserve the minimum capacity for at least additional
+elements to be inserted in the given Vec<T>. Unlike try_reserve,
+this will not deliberately over-allocate to speculatively avoid frequent
+allocations. After calling try_reserve_exact, capacity will be greater
+than or equal to self.len() + additional if it returns Ok(()).
+Does nothing if the capacity is already sufficient.
Note that the allocator may give the collection more space than it
+requests. Therefore, capacity can not be relied upon to be precisely
+minimal. Prefer try_reserve if future insertions are expected.
If the capacity overflows, or the allocator reports a failure, then an error +is returned.
+use std::collections::TryReserveError;
+
+fn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {
+ let mut output = Vec::new();
+
+ // Pre-reserve the memory, exiting if we can't
+ output.try_reserve_exact(data.len())?;
+
+ // Now we know this can't OOM in the middle of our complex work
+ output.extend(data.iter().map(|&val| {
+ val * 2 + 5 // very complicated
+ }));
+
+ Ok(output)
+}Shrinks the capacity of the vector as much as possible.
+The behavior of this method depends on the allocator, which may either shrink the vector
+in-place or reallocate. The resulting vector might still have some excess capacity, just as
+is the case for with_capacity. See Allocator::shrink for more details.
let mut vec = Vec::with_capacity(10);
+vec.extend([1, 2, 3]);
+assert!(vec.capacity() >= 10);
+vec.shrink_to_fit();
+assert!(vec.capacity() >= 3);Shrinks the capacity of the vector with a lower bound.
+The capacity will remain at least as large as both the length +and the supplied value.
+If the current capacity is less than the lower limit, this is a no-op.
+let mut vec = Vec::with_capacity(10);
+vec.extend([1, 2, 3]);
+assert!(vec.capacity() >= 10);
+vec.shrink_to(4);
+assert!(vec.capacity() >= 4);
+vec.shrink_to(0);
+assert!(vec.capacity() >= 3);Shortens the vector, keeping the first len elements and dropping
+the rest.
If len is greater or equal to the vector’s current length, this has
+no effect.
The drain method can emulate truncate, but causes the excess
+elements to be returned instead of dropped.
Note that this method has no effect on the allocated capacity +of the vector.
+Truncating a five element vector to two elements:
+ +let mut vec = vec![1, 2, 3, 4, 5];
+vec.truncate(2);
+assert_eq!(vec, [1, 2]);No truncation occurs when len is greater than the vector’s current
+length:
let mut vec = vec![1, 2, 3];
+vec.truncate(8);
+assert_eq!(vec, [1, 2, 3]);Truncating when len == 0 is equivalent to calling the clear
+method.
let mut vec = vec![1, 2, 3];
+vec.truncate(0);
+assert_eq!(vec, []);Extracts a slice containing the entire vector.
+Equivalent to &s[..].
use std::io::{self, Write};
+let buffer = vec![1, 2, 3, 5, 8];
+io::sink().write(buffer.as_slice()).unwrap();Extracts a mutable slice of the entire vector.
+Equivalent to &mut s[..].
use std::io::{self, Read};
+let mut buffer = vec![0; 3];
+io::repeat(0b101).read_exact(buffer.as_mut_slice()).unwrap();Returns a raw pointer to the vector’s buffer, or a dangling raw pointer +valid for zero sized reads if the vector didn’t allocate.
+The caller must ensure that the vector outlives the pointer this +function returns, or else it will end up pointing to garbage. +Modifying the vector may cause its buffer to be reallocated, +which would also make any pointers to it invalid.
+The caller must also ensure that the memory the pointer (non-transitively) points to
+is never written to (except inside an UnsafeCell) using this pointer or any pointer
+derived from it. If you need to mutate the contents of the slice, use as_mut_ptr.
This method guarantees that for the purpose of the aliasing model, this method
+does not materialize a reference to the underlying slice, and thus the returned pointer
+will remain valid when mixed with other calls to as_ptr and as_mut_ptr.
+Note that calling other methods that materialize mutable references to the slice,
+or mutable references to specific elements you are planning on accessing through this pointer,
+as well as writing to those elements, may still invalidate this pointer.
+See the second example below for how this guarantee can be used.
let x = vec![1, 2, 4];
+let x_ptr = x.as_ptr();
+
+unsafe {
+ for i in 0..x.len() {
+ assert_eq!(*x_ptr.add(i), 1 << i);
+ }
+}Due to the aliasing guarantee, the following code is legal:
+ +unsafe {
+ let mut v = vec![0, 1, 2];
+ let ptr1 = v.as_ptr();
+ let _ = ptr1.read();
+ let ptr2 = v.as_mut_ptr().offset(2);
+ ptr2.write(2);
+ // Notably, the write to `ptr2` did *not* invalidate `ptr1`
+ // because it mutated a different element:
+ let _ = ptr1.read();
+}Returns an unsafe mutable pointer to the vector’s buffer, or a dangling +raw pointer valid for zero sized reads if the vector didn’t allocate.
+The caller must ensure that the vector outlives the pointer this +function returns, or else it will end up pointing to garbage. +Modifying the vector may cause its buffer to be reallocated, +which would also make any pointers to it invalid.
+This method guarantees that for the purpose of the aliasing model, this method
+does not materialize a reference to the underlying slice, and thus the returned pointer
+will remain valid when mixed with other calls to as_ptr and as_mut_ptr.
+Note that calling other methods that materialize references to the slice,
+or references to specific elements you are planning on accessing through this pointer,
+may still invalidate this pointer.
+See the second example below for how this guarantee can be used.
// Allocate vector big enough for 4 elements.
+let size = 4;
+let mut x: Vec<i32> = Vec::with_capacity(size);
+let x_ptr = x.as_mut_ptr();
+
+// Initialize elements via raw pointer writes, then set length.
+unsafe {
+ for i in 0..size {
+ *x_ptr.add(i) = i as i32;
+ }
+ x.set_len(size);
+}
+assert_eq!(&*x, &[0, 1, 2, 3]);Due to the aliasing guarantee, the following code is legal:
+ +unsafe {
+ let mut v = vec![0];
+ let ptr1 = v.as_mut_ptr();
+ ptr1.write(1);
+ let ptr2 = v.as_mut_ptr();
+ ptr2.write(2);
+ // Notably, the write to `ptr2` did *not* invalidate `ptr1`:
+ ptr1.write(3);
+}allocator_api)Returns a reference to the underlying allocator.
+Forces the length of the vector to new_len.
This is a low-level operation that maintains none of the normal
+invariants of the type. Normally changing the length of a vector
+is done using one of the safe operations instead, such as
+truncate, resize, extend, or clear.
new_len must be less than or equal to capacity().old_len..new_len must be initialized.This method can be useful for situations in which the vector +is serving as a buffer for other code, particularly over FFI:
+ +pub fn get_dictionary(&self) -> Option<Vec<u8>> {
+ // Per the FFI method's docs, "32768 bytes is always enough".
+ let mut dict = Vec::with_capacity(32_768);
+ let mut dict_length = 0;
+ // SAFETY: When `deflateGetDictionary` returns `Z_OK`, it holds that:
+ // 1. `dict_length` elements were initialized.
+ // 2. `dict_length` <= the capacity (32_768)
+ // which makes `set_len` safe to call.
+ unsafe {
+ // Make the FFI call...
+ let r = deflateGetDictionary(self.strm, dict.as_mut_ptr(), &mut dict_length);
+ if r == Z_OK {
+ // ...and update the length to what was initialized.
+ dict.set_len(dict_length);
+ Some(dict)
+ } else {
+ None
+ }
+ }
+}While the following example is sound, there is a memory leak since
+the inner vectors were not freed prior to the set_len call:
let mut vec = vec![vec![1, 0, 0],
+ vec![0, 1, 0],
+ vec![0, 0, 1]];
+// SAFETY:
+// 1. `old_len..0` is empty so no elements need to be initialized.
+// 2. `0 <= capacity` always holds whatever `capacity` is.
+unsafe {
+ vec.set_len(0);
+}Normally, here, one would use clear instead to correctly drop
+the contents and thus not leak memory.
Removes an element from the vector and returns it.
+The removed element is replaced by the last element of the vector.
+This does not preserve ordering of the remaining elements, but is O(1).
+If you need to preserve the element order, use remove instead.
Panics if index is out of bounds.
let mut v = vec!["foo", "bar", "baz", "qux"];
+
+assert_eq!(v.swap_remove(1), "bar");
+assert_eq!(v, ["foo", "qux", "baz"]);
+
+assert_eq!(v.swap_remove(0), "foo");
+assert_eq!(v, ["baz", "qux"]);Inserts an element at position index within the vector, shifting all
+elements after it to the right.
Panics if index > len.
let mut vec = vec![1, 2, 3];
+vec.insert(1, 4);
+assert_eq!(vec, [1, 4, 2, 3]);
+vec.insert(4, 5);
+assert_eq!(vec, [1, 4, 2, 3, 5]);Takes O(Vec::len) time. All items after the insertion index must be
+shifted to the right. In the worst case, all elements are shifted when
+the insertion index is 0.
Removes and returns the element at position index within the vector,
+shifting all elements after it to the left.
Note: Because this shifts over the remaining elements, it has a
+worst-case performance of O(n). If you don’t need the order of elements
+to be preserved, use swap_remove instead. If you’d like to remove
+elements from the beginning of the Vec, consider using
+VecDeque::pop_front instead.
Panics if index is out of bounds.
let mut v = vec![1, 2, 3];
+assert_eq!(v.remove(1), 2);
+assert_eq!(v, [1, 3]);Retains only the elements specified by the predicate.
+In other words, remove all elements e for which f(&e) returns false.
+This method operates in place, visiting each element exactly once in the
+original order, and preserves the order of the retained elements.
let mut vec = vec![1, 2, 3, 4];
+vec.retain(|&x| x % 2 == 0);
+assert_eq!(vec, [2, 4]);Because the elements are visited exactly once in the original order, +external state may be used to decide which elements to keep.
+ +let mut vec = vec![1, 2, 3, 4, 5];
+let keep = [false, true, true, false, true];
+let mut iter = keep.iter();
+vec.retain(|_| *iter.next().unwrap());
+assert_eq!(vec, [2, 3, 5]);Retains only the elements specified by the predicate, passing a mutable reference to it.
+In other words, remove all elements e such that f(&mut e) returns false.
+This method operates in place, visiting each element exactly once in the
+original order, and preserves the order of the retained elements.
let mut vec = vec![1, 2, 3, 4];
+vec.retain_mut(|x| if *x <= 3 {
+ *x += 1;
+ true
+} else {
+ false
+});
+assert_eq!(vec, [2, 3, 4]);Removes all but the first of consecutive elements in the vector that resolve to the same +key.
+If the vector is sorted, this removes all duplicates.
+let mut vec = vec![10, 20, 21, 30, 20];
+
+vec.dedup_by_key(|i| *i / 10);
+
+assert_eq!(vec, [10, 20, 30, 20]);Removes all but the first of consecutive elements in the vector satisfying a given equality +relation.
+The same_bucket function is passed references to two elements from the vector and
+must determine if the elements compare equal. The elements are passed in opposite order
+from their order in the slice, so if same_bucket(a, b) returns true, a is removed.
If the vector is sorted, this removes all duplicates.
+let mut vec = vec!["foo", "bar", "Bar", "baz", "bar"];
+
+vec.dedup_by(|a, b| a.eq_ignore_ascii_case(b));
+
+assert_eq!(vec, ["foo", "bar", "baz", "bar"]);Appends an element to the back of a collection.
+Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1, 2];
+vec.push(3);
+assert_eq!(vec, [1, 2, 3]);Takes amortized O(1) time. If the vector’s length would exceed its +capacity after the push, O(capacity) time is taken to copy the +vector’s elements to a larger allocation. This expensive operation is +offset by the capacity O(1) insertions it allows.
+vec_push_within_capacity)Appends an element if there is sufficient spare capacity, otherwise an error is returned +with the element.
+Unlike push this method will not reallocate when there’s insufficient capacity.
+The caller should use reserve or try_reserve to ensure that there is enough capacity.
A manual, panic-free alternative to FromIterator:
#![feature(vec_push_within_capacity)]
+
+use std::collections::TryReserveError;
+fn from_iter_fallible<T>(iter: impl Iterator<Item=T>) -> Result<Vec<T>, TryReserveError> {
+ let mut vec = Vec::new();
+ for value in iter {
+ if let Err(value) = vec.push_within_capacity(value) {
+ vec.try_reserve(1)?;
+ // this cannot fail, the previous line either returned or added at least 1 free slot
+ let _ = vec.push_within_capacity(value);
+ }
+ }
+ Ok(vec)
+}
+assert_eq!(from_iter_fallible(0..100), Ok(Vec::from_iter(0..100)));Takes O(1) time.
+Removes the last element from a vector and returns it, or None if it
+is empty.
If you’d like to pop the first element, consider using
+VecDeque::pop_front instead.
let mut vec = vec![1, 2, 3];
+assert_eq!(vec.pop(), Some(3));
+assert_eq!(vec, [1, 2]);Takes O(1) time.
+vec_pop_if)Removes and returns the last element in a vector if the predicate
+returns true, or None if the predicate returns false or the vector
+is empty.
#![feature(vec_pop_if)]
+
+let mut vec = vec![1, 2, 3, 4];
+let pred = |x: &mut i32| *x % 2 == 0;
+
+assert_eq!(vec.pop_if(pred), Some(4));
+assert_eq!(vec, [1, 2, 3]);
+assert_eq!(vec.pop_if(pred), None);Removes the specified range from the vector in bulk, returning all +removed elements as an iterator. If the iterator is dropped before +being fully consumed, it drops the remaining removed elements.
+The returned iterator keeps a mutable borrow on the vector to optimize +its implementation.
+Panics if the starting point is greater than the end point or if +the end point is greater than the length of the vector.
+If the returned iterator goes out of scope without being dropped (due to
+mem::forget, for example), the vector may have lost and leaked
+elements arbitrarily, including elements outside the range.
let mut v = vec![1, 2, 3];
+let u: Vec<_> = v.drain(1..).collect();
+assert_eq!(v, &[1]);
+assert_eq!(u, &[2, 3]);
+
+// A full range clears the vector, like `clear()` does
+v.drain(..);
+assert_eq!(v, &[]);Clears the vector, removing all values.
+Note that this method has no effect on the allocated capacity +of the vector.
+let mut v = vec![1, 2, 3];
+
+v.clear();
+
+assert!(v.is_empty());Returns the number of elements in the vector, also referred to +as its ‘length’.
+let a = vec![1, 2, 3];
+assert_eq!(a.len(), 3);Returns true if the vector contains no elements.
let mut v = Vec::new();
+assert!(v.is_empty());
+
+v.push(1);
+assert!(!v.is_empty());Splits the collection into two at the given index.
+Returns a newly allocated vector containing the elements in the range
+[at, len). After the call, the original vector will be left containing
+the elements [0, at) with its previous capacity unchanged.
mem::take or mem::replace.Vec::truncate.Vec::drain.Panics if at > len.
let mut vec = vec![1, 2, 3];
+let vec2 = vec.split_off(1);
+assert_eq!(vec, [1]);
+assert_eq!(vec2, [2, 3]);Resizes the Vec in-place so that len is equal to new_len.
If new_len is greater than len, the Vec is extended by the
+difference, with each additional slot filled with the result of
+calling the closure f. The return values from f will end up
+in the Vec in the order they have been generated.
If new_len is less than len, the Vec is simply truncated.
This method uses a closure to create new values on every push. If
+you’d rather Clone a given value, use Vec::resize. If you
+want to use the Default trait to generate values, you can
+pass Default::default as the second argument.
let mut vec = vec![1, 2, 3];
+vec.resize_with(5, Default::default);
+assert_eq!(vec, [1, 2, 3, 0, 0]);
+
+let mut vec = vec![];
+let mut p = 1;
+vec.resize_with(4, || { p *= 2; p });
+assert_eq!(vec, [2, 4, 8, 16]);Returns the remaining spare capacity of the vector as a slice of
+MaybeUninit<T>.
The returned slice can be used to fill the vector with data (e.g. by
+reading from a file) before marking the data as initialized using the
+set_len method.
// Allocate vector big enough for 10 elements.
+let mut v = Vec::with_capacity(10);
+
+// Fill in the first 3 elements.
+let uninit = v.spare_capacity_mut();
+uninit[0].write(0);
+uninit[1].write(1);
+uninit[2].write(2);
+
+// Mark the first 3 elements of the vector as being initialized.
+unsafe {
+ v.set_len(3);
+}
+
+assert_eq!(&v, &[0, 1, 2]);vec_split_at_spare)Returns vector content as a slice of T, along with the remaining spare
+capacity of the vector as a slice of MaybeUninit<T>.
The returned spare capacity slice can be used to fill the vector with data
+(e.g. by reading from a file) before marking the data as initialized using
+the set_len method.
Note that this is a low-level API, which should be used with care for
+optimization purposes. If you need to append data to a Vec
+you can use push, extend, extend_from_slice,
+extend_from_within, insert, append, resize or
+resize_with, depending on your exact needs.
#![feature(vec_split_at_spare)]
+
+let mut v = vec![1, 1, 2];
+
+// Reserve additional space big enough for 10 elements.
+v.reserve(10);
+
+let (init, uninit) = v.split_at_spare_mut();
+let sum = init.iter().copied().sum::<u32>();
+
+// Fill in the next 4 elements.
+uninit[0].write(sum);
+uninit[1].write(sum * 2);
+uninit[2].write(sum * 3);
+uninit[3].write(sum * 4);
+
+// Mark the 4 elements of the vector as being initialized.
+unsafe {
+ let len = v.len();
+ v.set_len(len + 4);
+}
+
+assert_eq!(&v, &[1, 1, 2, 4, 8, 12, 16]);Resizes the Vec in-place so that len is equal to new_len.
If new_len is greater than len, the Vec is extended by the
+difference, with each additional slot filled with value.
+If new_len is less than len, the Vec is simply truncated.
This method requires T to implement Clone,
+in order to be able to clone the passed value.
+If you need more flexibility (or want to rely on Default instead of
+Clone), use Vec::resize_with.
+If you only need to resize to a smaller size, use Vec::truncate.
let mut vec = vec!["hello"];
+vec.resize(3, "world");
+assert_eq!(vec, ["hello", "world", "world"]);
+
+let mut vec = vec![1, 2, 3, 4];
+vec.resize(2, 0);
+assert_eq!(vec, [1, 2]);Clones and appends all elements in a slice to the Vec.
Iterates over the slice other, clones each element, and then appends
+it to this Vec. The other slice is traversed in-order.
Note that this function is same as extend except that it is
+specialized to work with slices instead. If and when Rust gets
+specialization this function will likely be deprecated (but still
+available).
let mut vec = vec![1];
+vec.extend_from_slice(&[2, 3, 4]);
+assert_eq!(vec, [1, 2, 3, 4]);Copies elements from src range to the end of the vector.
Panics if the starting point is greater than the end point or if +the end point is greater than the length of the vector.
+let mut vec = vec![0, 1, 2, 3, 4];
+
+vec.extend_from_within(2..);
+assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4]);
+
+vec.extend_from_within(..2);
+assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1]);
+
+vec.extend_from_within(4..8);
+assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);Creates a splicing iterator that replaces the specified range in the vector
+with the given replace_with iterator and yields the removed items.
+replace_with does not need to be the same length as range.
range is removed even if the iterator is not consumed until the end.
It is unspecified how many elements are removed from the vector
+if the Splice value is leaked.
The input iterator replace_with is only consumed when the Splice value is dropped.
This is optimal if:
+range) is empty,replace_with yields fewer or equal elements than range’s lengthsize_hint() is exact.Otherwise, a temporary vector is allocated and the tail is moved twice.
+Panics if the starting point is greater than the end point or if +the end point is greater than the length of the vector.
+let mut v = vec![1, 2, 3, 4];
+let new = [7, 8, 9];
+let u: Vec<_> = v.splice(1..3, new).collect();
+assert_eq!(v, &[1, 7, 8, 9, 4]);
+assert_eq!(u, &[2, 3]);extract_if)Creates an iterator which uses a closure to determine if an element should be removed.
+If the closure returns true, then the element is removed and yielded. +If the closure returns false, the element will remain in the vector and will not be yielded +by the iterator.
+If the returned ExtractIf is not exhausted, e.g. because it is dropped without iterating
+or the iteration short-circuits, then the remaining elements will be retained.
+Use retain with a negated predicate if you do not need the returned iterator.
Using this method is equivalent to the following code:
+ +let mut i = 0;
+while i < vec.len() {
+ if some_predicate(&mut vec[i]) {
+ let val = vec.remove(i);
+ // your code here
+ } else {
+ i += 1;
+ }
+}
+But extract_if is easier to use. extract_if is also more efficient,
+because it can backshift the elements of the array in bulk.
Note that extract_if also lets you mutate every element in the filter closure,
+regardless of whether you choose to keep or remove it.
Splitting an array into evens and odds, reusing the original allocation:
+ +#![feature(extract_if)]
+let mut numbers = vec![1, 2, 3, 4, 5, 6, 8, 9, 11, 13, 14, 15];
+
+let evens = numbers.extract_if(|x| *x % 2 == 0).collect::<Vec<_>>();
+let odds = numbers;
+
+assert_eq!(evens, vec![2, 4, 6, 8, 14]);
+assert_eq!(odds, vec![1, 3, 5, 9, 11, 13, 15]);ascii_char)Views this slice of ASCII characters as a UTF-8 str.
ascii_char)Views this slice of ASCII characters as a slice of u8 bytes.
sort_floats)Sorts the slice of floats.
+This sort is in-place (i.e. does not allocate), O(n * log(n)) worst-case, and uses
+the ordering defined by f32::total_cmp.
This uses the same sorting algorithm as sort_unstable_by.
#![feature(sort_floats)]
+let mut v = [2.6, -5e-8, f32::NAN, 8.29, f32::INFINITY, -1.0, 0.0, -f32::INFINITY, -0.0];
+
+v.sort_floats();
+let sorted = [-f32::INFINITY, -1.0, -5e-8, -0.0, 0.0, 2.6, 8.29, f32::INFINITY, f32::NAN];
+assert_eq!(&v[..8], &sorted[..8]);
+assert!(v[8].is_nan());Checks if all bytes in this slice are within the ASCII range.
+ascii_char)If this slice is_ascii, returns it as a slice of
+ASCII characters, otherwise returns None.
ascii_char)Converts this slice of bytes into a slice of ASCII characters, +without checking whether they’re valid.
+Every byte in the slice must be in 0..=127, or else this is UB.
Checks that two slices are an ASCII case-insensitive match.
+Same as to_ascii_lowercase(a) == to_ascii_lowercase(b),
+but without allocating and copying temporaries.
Converts this slice to its ASCII upper case equivalent in-place.
+ASCII letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’, +but non-ASCII letters are unchanged.
+To return a new uppercased value without modifying the existing one, use
+to_ascii_uppercase.
Converts this slice to its ASCII lower case equivalent in-place.
+ASCII letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’, +but non-ASCII letters are unchanged.
+To return a new lowercased value without modifying the existing one, use
+to_ascii_lowercase.
Returns an iterator that produces an escaped version of this slice, +treating it as an ASCII string.
+
+let s = b"0\t\r\n'\"\\\x9d";
+let escaped = s.escape_ascii().to_string();
+assert_eq!(escaped, "0\\t\\r\\n\\'\\\"\\\\\\x9d");Returns a byte slice with leading ASCII whitespace bytes removed.
+‘Whitespace’ refers to the definition used by
+u8::is_ascii_whitespace.
assert_eq!(b" \t hello world\n".trim_ascii_start(), b"hello world\n");
+assert_eq!(b" ".trim_ascii_start(), b"");
+assert_eq!(b"".trim_ascii_start(), b"");Returns a byte slice with trailing ASCII whitespace bytes removed.
+‘Whitespace’ refers to the definition used by
+u8::is_ascii_whitespace.
assert_eq!(b"\r hello world\n ".trim_ascii_end(), b"\r hello world");
+assert_eq!(b" ".trim_ascii_end(), b"");
+assert_eq!(b"".trim_ascii_end(), b"");Returns a byte slice with leading and trailing ASCII whitespace bytes +removed.
+‘Whitespace’ refers to the definition used by
+u8::is_ascii_whitespace.
assert_eq!(b"\r hello world\n ".trim_ascii(), b"hello world");
+assert_eq!(b" ".trim_ascii(), b"");
+assert_eq!(b"".trim_ascii(), b"");Creates an iterator over the contiguous valid UTF-8 ranges of this +slice, and the non-UTF-8 fragments in between.
+This function formats arbitrary but mostly-UTF-8 bytes into Rust source
+code in the form of a C-string literal (c"...").
use std::fmt::Write as _;
+
+pub fn cstr_literal(bytes: &[u8]) -> String {
+ let mut repr = String::new();
+ repr.push_str("c\"");
+ for chunk in bytes.utf8_chunks() {
+ for ch in chunk.valid().chars() {
+ // Escapes \0, \t, \r, \n, \\, \', \", and uses \u{...} for non-printable characters.
+ write!(repr, "{}", ch.escape_debug()).unwrap();
+ }
+ for byte in chunk.invalid() {
+ write!(repr, "\\x{:02X}", byte).unwrap();
+ }
+ }
+ repr.push('"');
+ repr
+}
+
+fn main() {
+ let lit = cstr_literal(b"\xferris the \xf0\x9f\xa6\x80\x07");
+ let expected = stringify!(c"\xFErris the 🦀\u{7}");
+ assert_eq!(lit, expected);
+}Takes a &[[T; N]], and flattens it to a &[T].
This panics if the length of the resulting slice would overflow a usize.
This is only possible when flattening a slice of arrays of zero-sized
+types, and thus tends to be irrelevant in practice. If
+size_of::<T>() > 0, this will never panic.
assert_eq!([[1, 2, 3], [4, 5, 6]].as_flattened(), &[1, 2, 3, 4, 5, 6]);
+
+assert_eq!(
+ [[1, 2, 3], [4, 5, 6]].as_flattened(),
+ [[1, 2], [3, 4], [5, 6]].as_flattened(),
+);
+
+let slice_of_empty_arrays: &[[i32; 0]] = &[[], [], [], [], []];
+assert!(slice_of_empty_arrays.as_flattened().is_empty());
+
+let empty_slice_of_arrays: &[[u32; 10]] = &[];
+assert!(empty_slice_of_arrays.as_flattened().is_empty());Takes a &mut [[T; N]], and flattens it to a &mut [T].
This panics if the length of the resulting slice would overflow a usize.
This is only possible when flattening a slice of arrays of zero-sized
+types, and thus tends to be irrelevant in practice. If
+size_of::<T>() > 0, this will never panic.
fn add_5_to_all(slice: &mut [i32]) {
+ for i in slice {
+ *i += 5;
+ }
+}
+
+let mut array = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
+add_5_to_all(array.as_flattened_mut());
+assert_eq!(array, [[6, 7, 8], [9, 10, 11], [12, 13, 14]]);sort_floats)Sorts the slice of floats.
+This sort is in-place (i.e. does not allocate), O(n * log(n)) worst-case, and uses
+the ordering defined by f64::total_cmp.
This uses the same sorting algorithm as sort_unstable_by.
#![feature(sort_floats)]
+let mut v = [2.6, -5e-8, f64::NAN, 8.29, f64::INFINITY, -1.0, 0.0, -f64::INFINITY, -0.0];
+
+v.sort_floats();
+let sorted = [-f64::INFINITY, -1.0, -5e-8, -0.0, 0.0, 2.6, 8.29, f64::INFINITY, f64::NAN];
+assert_eq!(&v[..8], &sorted[..8]);
+assert!(v[8].is_nan());Returns the number of elements in the slice.
+let a = [1, 2, 3];
+assert_eq!(a.len(), 3);Returns true if the slice has a length of 0.
let a = [1, 2, 3];
+assert!(!a.is_empty());
+
+let b: &[i32] = &[];
+assert!(b.is_empty());Returns the first element of the slice, or None if it is empty.
let v = [10, 40, 30];
+assert_eq!(Some(&10), v.first());
+
+let w: &[i32] = &[];
+assert_eq!(None, w.first());Returns a mutable pointer to the first element of the slice, or None if it is empty.
let x = &mut [0, 1, 2];
+
+if let Some(first) = x.first_mut() {
+ *first = 5;
+}
+assert_eq!(x, &[5, 1, 2]);
+
+let y: &mut [i32] = &mut [];
+assert_eq!(None, y.first_mut());Returns the first and all the rest of the elements of the slice, or None if it is empty.
let x = &[0, 1, 2];
+
+if let Some((first, elements)) = x.split_first() {
+ assert_eq!(first, &0);
+ assert_eq!(elements, &[1, 2]);
+}Returns the first and all the rest of the elements of the slice, or None if it is empty.
let x = &mut [0, 1, 2];
+
+if let Some((first, elements)) = x.split_first_mut() {
+ *first = 3;
+ elements[0] = 4;
+ elements[1] = 5;
+}
+assert_eq!(x, &[3, 4, 5]);Returns the last and all the rest of the elements of the slice, or None if it is empty.
let x = &[0, 1, 2];
+
+if let Some((last, elements)) = x.split_last() {
+ assert_eq!(last, &2);
+ assert_eq!(elements, &[0, 1]);
+}Returns the last and all the rest of the elements of the slice, or None if it is empty.
let x = &mut [0, 1, 2];
+
+if let Some((last, elements)) = x.split_last_mut() {
+ *last = 3;
+ elements[0] = 4;
+ elements[1] = 5;
+}
+assert_eq!(x, &[4, 5, 3]);Returns the last element of the slice, or None if it is empty.
let v = [10, 40, 30];
+assert_eq!(Some(&30), v.last());
+
+let w: &[i32] = &[];
+assert_eq!(None, w.last());Returns a mutable reference to the last item in the slice, or None if it is empty.
let x = &mut [0, 1, 2];
+
+if let Some(last) = x.last_mut() {
+ *last = 10;
+}
+assert_eq!(x, &[0, 1, 10]);
+
+let y: &mut [i32] = &mut [];
+assert_eq!(None, y.last_mut());Return an array reference to the first N items in the slice.
If the slice is not at least N in length, this will return None.
let u = [10, 40, 30];
+assert_eq!(Some(&[10, 40]), u.first_chunk::<2>());
+
+let v: &[i32] = &[10];
+assert_eq!(None, v.first_chunk::<2>());
+
+let w: &[i32] = &[];
+assert_eq!(Some(&[]), w.first_chunk::<0>());Return a mutable array reference to the first N items in the slice.
If the slice is not at least N in length, this will return None.
let x = &mut [0, 1, 2];
+
+if let Some(first) = x.first_chunk_mut::<2>() {
+ first[0] = 5;
+ first[1] = 4;
+}
+assert_eq!(x, &[5, 4, 2]);
+
+assert_eq!(None, x.first_chunk_mut::<4>());Return an array reference to the first N items in the slice and the remaining slice.
If the slice is not at least N in length, this will return None.
let x = &[0, 1, 2];
+
+if let Some((first, elements)) = x.split_first_chunk::<2>() {
+ assert_eq!(first, &[0, 1]);
+ assert_eq!(elements, &[2]);
+}
+
+assert_eq!(None, x.split_first_chunk::<4>());Return a mutable array reference to the first N items in the slice and the remaining
+slice.
If the slice is not at least N in length, this will return None.
let x = &mut [0, 1, 2];
+
+if let Some((first, elements)) = x.split_first_chunk_mut::<2>() {
+ first[0] = 3;
+ first[1] = 4;
+ elements[0] = 5;
+}
+assert_eq!(x, &[3, 4, 5]);
+
+assert_eq!(None, x.split_first_chunk_mut::<4>());Return an array reference to the last N items in the slice and the remaining slice.
If the slice is not at least N in length, this will return None.
let x = &[0, 1, 2];
+
+if let Some((elements, last)) = x.split_last_chunk::<2>() {
+ assert_eq!(elements, &[0]);
+ assert_eq!(last, &[1, 2]);
+}
+
+assert_eq!(None, x.split_last_chunk::<4>());Return a mutable array reference to the last N items in the slice and the remaining
+slice.
If the slice is not at least N in length, this will return None.
let x = &mut [0, 1, 2];
+
+if let Some((elements, last)) = x.split_last_chunk_mut::<2>() {
+ last[0] = 3;
+ last[1] = 4;
+ elements[0] = 5;
+}
+assert_eq!(x, &[5, 3, 4]);
+
+assert_eq!(None, x.split_last_chunk_mut::<4>());Return an array reference to the last N items in the slice.
If the slice is not at least N in length, this will return None.
let u = [10, 40, 30];
+assert_eq!(Some(&[40, 30]), u.last_chunk::<2>());
+
+let v: &[i32] = &[10];
+assert_eq!(None, v.last_chunk::<2>());
+
+let w: &[i32] = &[];
+assert_eq!(Some(&[]), w.last_chunk::<0>());Return a mutable array reference to the last N items in the slice.
If the slice is not at least N in length, this will return None.
let x = &mut [0, 1, 2];
+
+if let Some(last) = x.last_chunk_mut::<2>() {
+ last[0] = 10;
+ last[1] = 20;
+}
+assert_eq!(x, &[0, 10, 20]);
+
+assert_eq!(None, x.last_chunk_mut::<4>());Returns a reference to an element or subslice depending on the type of +index.
+None if out of bounds.None if out of bounds.let v = [10, 40, 30];
+assert_eq!(Some(&40), v.get(1));
+assert_eq!(Some(&[10, 40][..]), v.get(0..2));
+assert_eq!(None, v.get(3));
+assert_eq!(None, v.get(0..4));Returns a reference to an element or subslice, without doing bounds +checking.
+For a safe alternative see get.
Calling this method with an out-of-bounds index is undefined behavior +even if the resulting reference is not used.
+You can think of this like .get(index).unwrap_unchecked(). It’s UB
+to call .get_unchecked(len), even if you immediately convert to a
+pointer. And it’s UB to call .get_unchecked(..len + 1),
+.get_unchecked(..=len), or similar.
let x = &[1, 2, 4];
+
+unsafe {
+ assert_eq!(x.get_unchecked(1), &2);
+}Returns a mutable reference to an element or subslice, without doing +bounds checking.
+For a safe alternative see get_mut.
Calling this method with an out-of-bounds index is undefined behavior +even if the resulting reference is not used.
+You can think of this like .get_mut(index).unwrap_unchecked(). It’s
+UB to call .get_unchecked_mut(len), even if you immediately convert
+to a pointer. And it’s UB to call .get_unchecked_mut(..len + 1),
+.get_unchecked_mut(..=len), or similar.
let x = &mut [1, 2, 4];
+
+unsafe {
+ let elem = x.get_unchecked_mut(1);
+ *elem = 13;
+}
+assert_eq!(x, &[1, 13, 4]);Returns a raw pointer to the slice’s buffer.
+The caller must ensure that the slice outlives the pointer this +function returns, or else it will end up pointing to garbage.
+The caller must also ensure that the memory the pointer (non-transitively) points to
+is never written to (except inside an UnsafeCell) using this pointer or any pointer
+derived from it. If you need to mutate the contents of the slice, use as_mut_ptr.
Modifying the container referenced by this slice may cause its buffer +to be reallocated, which would also make any pointers to it invalid.
+let x = &[1, 2, 4];
+let x_ptr = x.as_ptr();
+
+unsafe {
+ for i in 0..x.len() {
+ assert_eq!(x.get_unchecked(i), &*x_ptr.add(i));
+ }
+}Returns an unsafe mutable pointer to the slice’s buffer.
+The caller must ensure that the slice outlives the pointer this +function returns, or else it will end up pointing to garbage.
+Modifying the container referenced by this slice may cause its buffer +to be reallocated, which would also make any pointers to it invalid.
+let x = &mut [1, 2, 4];
+let x_ptr = x.as_mut_ptr();
+
+unsafe {
+ for i in 0..x.len() {
+ *x_ptr.add(i) += 2;
+ }
+}
+assert_eq!(x, &[3, 4, 6]);Returns the two raw pointers spanning the slice.
+The returned range is half-open, which means that the end pointer +points one past the last element of the slice. This way, an empty +slice is represented by two equal pointers, and the difference between +the two pointers represents the size of the slice.
+See as_ptr for warnings on using these pointers. The end pointer
+requires extra caution, as it does not point to a valid element in the
+slice.
This function is useful for interacting with foreign interfaces which +use two pointers to refer to a range of elements in memory, as is +common in C++.
+It can also be useful to check if a pointer to an element refers to an +element of this slice:
+ +let a = [1, 2, 3];
+let x = &a[1] as *const _;
+let y = &5 as *const _;
+
+assert!(a.as_ptr_range().contains(&x));
+assert!(!a.as_ptr_range().contains(&y));Returns the two unsafe mutable pointers spanning the slice.
+The returned range is half-open, which means that the end pointer +points one past the last element of the slice. This way, an empty +slice is represented by two equal pointers, and the difference between +the two pointers represents the size of the slice.
+See as_mut_ptr for warnings on using these pointers. The end
+pointer requires extra caution, as it does not point to a valid element
+in the slice.
This function is useful for interacting with foreign interfaces which +use two pointers to refer to a range of elements in memory, as is +common in C++.
+Swaps two elements in the slice.
+If a equals to b, it’s guaranteed that elements won’t change value.
Panics if a or b are out of bounds.
let mut v = ["a", "b", "c", "d", "e"];
+v.swap(2, 4);
+assert!(v == ["a", "b", "e", "d", "c"]);slice_swap_unchecked)Swaps two elements in the slice, without doing bounds checking.
+For a safe alternative see swap.
Calling this method with an out-of-bounds index is undefined behavior.
+The caller has to ensure that a < self.len() and b < self.len().
#![feature(slice_swap_unchecked)]
+
+let mut v = ["a", "b", "c", "d"];
+// SAFETY: we know that 1 and 3 are both indices of the slice
+unsafe { v.swap_unchecked(1, 3) };
+assert!(v == ["a", "d", "c", "b"]);Reverses the order of elements in the slice, in place.
+let mut v = [1, 2, 3];
+v.reverse();
+assert!(v == [3, 2, 1]);Returns an iterator over the slice.
+The iterator yields all items from start to end.
+let x = &[1, 2, 4];
+let mut iterator = x.iter();
+
+assert_eq!(iterator.next(), Some(&1));
+assert_eq!(iterator.next(), Some(&2));
+assert_eq!(iterator.next(), Some(&4));
+assert_eq!(iterator.next(), None);Returns an iterator that allows modifying each value.
+The iterator yields all items from start to end.
+let x = &mut [1, 2, 4];
+for elem in x.iter_mut() {
+ *elem += 2;
+}
+assert_eq!(x, &[3, 4, 6]);Returns an iterator over all contiguous windows of length
+size. The windows overlap. If the slice is shorter than
+size, the iterator returns no values.
Panics if size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.windows(3);
+assert_eq!(iter.next().unwrap(), &['l', 'o', 'r']);
+assert_eq!(iter.next().unwrap(), &['o', 'r', 'e']);
+assert_eq!(iter.next().unwrap(), &['r', 'e', 'm']);
+assert!(iter.next().is_none());If the slice is shorter than size:
let slice = ['f', 'o', 'o'];
+let mut iter = slice.windows(4);
+assert!(iter.next().is_none());There’s no windows_mut, as that existing would let safe code violate the
+“only one &mut at a time to the same thing” rule. However, you can sometimes
+use Cell::as_slice_of_cells in
+conjunction with windows to accomplish something similar:
use std::cell::Cell;
+
+let mut array = ['R', 'u', 's', 't', ' ', '2', '0', '1', '5'];
+let slice = &mut array[..];
+let slice_of_cells: &[Cell<char>] = Cell::from_mut(slice).as_slice_of_cells();
+for w in slice_of_cells.windows(3) {
+ Cell::swap(&w[0], &w[2]);
+}
+assert_eq!(array, ['s', 't', ' ', '2', '0', '1', '5', 'u', 'R']);Returns an iterator over chunk_size elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are slices and do not overlap. If chunk_size does not divide the length of the
+slice, then the last chunk will not have length chunk_size.
See chunks_exact for a variant of this iterator that returns chunks of always exactly
+chunk_size elements, and rchunks for the same iterator but starting at the end of the
+slice.
Panics if chunk_size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.chunks(2);
+assert_eq!(iter.next().unwrap(), &['l', 'o']);
+assert_eq!(iter.next().unwrap(), &['r', 'e']);
+assert_eq!(iter.next().unwrap(), &['m']);
+assert!(iter.next().is_none());Returns an iterator over chunk_size elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are mutable slices, and do not overlap. If chunk_size does not divide the
+length of the slice, then the last chunk will not have length chunk_size.
See chunks_exact_mut for a variant of this iterator that returns chunks of always
+exactly chunk_size elements, and rchunks_mut for the same iterator but starting at
+the end of the slice.
Panics if chunk_size is 0.
let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.chunks_mut(2) {
+ for elem in chunk.iter_mut() {
+ *elem += count;
+ }
+ count += 1;
+}
+assert_eq!(v, &[1, 1, 2, 2, 3]);Returns an iterator over chunk_size elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are slices and do not overlap. If chunk_size does not divide the length of the
+slice, then the last up to chunk_size-1 elements will be omitted and can be retrieved
+from the remainder function of the iterator.
Due to each chunk having exactly chunk_size elements, the compiler can often optimize the
+resulting code better than in the case of chunks.
See chunks for a variant of this iterator that also returns the remainder as a smaller
+chunk, and rchunks_exact for the same iterator but starting at the end of the slice.
Panics if chunk_size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.chunks_exact(2);
+assert_eq!(iter.next().unwrap(), &['l', 'o']);
+assert_eq!(iter.next().unwrap(), &['r', 'e']);
+assert!(iter.next().is_none());
+assert_eq!(iter.remainder(), &['m']);Returns an iterator over chunk_size elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are mutable slices, and do not overlap. If chunk_size does not divide the
+length of the slice, then the last up to chunk_size-1 elements will be omitted and can be
+retrieved from the into_remainder function of the iterator.
Due to each chunk having exactly chunk_size elements, the compiler can often optimize the
+resulting code better than in the case of chunks_mut.
See chunks_mut for a variant of this iterator that also returns the remainder as a
+smaller chunk, and rchunks_exact_mut for the same iterator but starting at the end of
+the slice.
Panics if chunk_size is 0.
let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.chunks_exact_mut(2) {
+ for elem in chunk.iter_mut() {
+ *elem += count;
+ }
+ count += 1;
+}
+assert_eq!(v, &[1, 1, 2, 2, 0]);slice_as_chunks)Splits the slice into a slice of N-element arrays,
+assuming that there’s no remainder.
This may only be called when
+N-element chunks (aka self.len() % N == 0).N != 0.#![feature(slice_as_chunks)]
+let slice: &[char] = &['l', 'o', 'r', 'e', 'm', '!'];
+let chunks: &[[char; 1]] =
+ // SAFETY: 1-element chunks never have remainder
+ unsafe { slice.as_chunks_unchecked() };
+assert_eq!(chunks, &[['l'], ['o'], ['r'], ['e'], ['m'], ['!']]);
+let chunks: &[[char; 3]] =
+ // SAFETY: The slice length (6) is a multiple of 3
+ unsafe { slice.as_chunks_unchecked() };
+assert_eq!(chunks, &[['l', 'o', 'r'], ['e', 'm', '!']]);
+
+// These would be unsound:
+// let chunks: &[[_; 5]] = slice.as_chunks_unchecked() // The slice length is not a multiple of 5
+// let chunks: &[[_; 0]] = slice.as_chunks_unchecked() // Zero-length chunks are never allowedslice_as_chunks)Splits the slice into a slice of N-element arrays,
+starting at the beginning of the slice,
+and a remainder slice with length strictly less than N.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(slice_as_chunks)]
+let slice = ['l', 'o', 'r', 'e', 'm'];
+let (chunks, remainder) = slice.as_chunks();
+assert_eq!(chunks, &[['l', 'o'], ['r', 'e']]);
+assert_eq!(remainder, &['m']);If you expect the slice to be an exact multiple, you can combine
+let-else with an empty slice pattern:
#![feature(slice_as_chunks)]
+let slice = ['R', 'u', 's', 't'];
+let (chunks, []) = slice.as_chunks::<2>() else {
+ panic!("slice didn't have even length")
+};
+assert_eq!(chunks, &[['R', 'u'], ['s', 't']]);slice_as_chunks)Splits the slice into a slice of N-element arrays,
+starting at the end of the slice,
+and a remainder slice with length strictly less than N.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(slice_as_chunks)]
+let slice = ['l', 'o', 'r', 'e', 'm'];
+let (remainder, chunks) = slice.as_rchunks();
+assert_eq!(remainder, &['l']);
+assert_eq!(chunks, &[['o', 'r'], ['e', 'm']]);array_chunks)Returns an iterator over N elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are array references and do not overlap. If N does not divide the
+length of the slice, then the last up to N-1 elements will be omitted and can be
+retrieved from the remainder function of the iterator.
This method is the const generic equivalent of chunks_exact.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(array_chunks)]
+let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.array_chunks();
+assert_eq!(iter.next().unwrap(), &['l', 'o']);
+assert_eq!(iter.next().unwrap(), &['r', 'e']);
+assert!(iter.next().is_none());
+assert_eq!(iter.remainder(), &['m']);slice_as_chunks)Splits the slice into a slice of N-element arrays,
+assuming that there’s no remainder.
This may only be called when
+N-element chunks (aka self.len() % N == 0).N != 0.#![feature(slice_as_chunks)]
+let slice: &mut [char] = &mut ['l', 'o', 'r', 'e', 'm', '!'];
+let chunks: &mut [[char; 1]] =
+ // SAFETY: 1-element chunks never have remainder
+ unsafe { slice.as_chunks_unchecked_mut() };
+chunks[0] = ['L'];
+assert_eq!(chunks, &[['L'], ['o'], ['r'], ['e'], ['m'], ['!']]);
+let chunks: &mut [[char; 3]] =
+ // SAFETY: The slice length (6) is a multiple of 3
+ unsafe { slice.as_chunks_unchecked_mut() };
+chunks[1] = ['a', 'x', '?'];
+assert_eq!(slice, &['L', 'o', 'r', 'a', 'x', '?']);
+
+// These would be unsound:
+// let chunks: &[[_; 5]] = slice.as_chunks_unchecked_mut() // The slice length is not a multiple of 5
+// let chunks: &[[_; 0]] = slice.as_chunks_unchecked_mut() // Zero-length chunks are never allowedslice_as_chunks)Splits the slice into a slice of N-element arrays,
+starting at the beginning of the slice,
+and a remainder slice with length strictly less than N.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(slice_as_chunks)]
+let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+let (chunks, remainder) = v.as_chunks_mut();
+remainder[0] = 9;
+for chunk in chunks {
+ *chunk = [count; 2];
+ count += 1;
+}
+assert_eq!(v, &[1, 1, 2, 2, 9]);slice_as_chunks)Splits the slice into a slice of N-element arrays,
+starting at the end of the slice,
+and a remainder slice with length strictly less than N.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(slice_as_chunks)]
+let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+let (remainder, chunks) = v.as_rchunks_mut();
+remainder[0] = 9;
+for chunk in chunks {
+ *chunk = [count; 2];
+ count += 1;
+}
+assert_eq!(v, &[9, 1, 1, 2, 2]);array_chunks)Returns an iterator over N elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are mutable array references and do not overlap. If N does not divide
+the length of the slice, then the last up to N-1 elements will be omitted and
+can be retrieved from the into_remainder function of the iterator.
This method is the const generic equivalent of chunks_exact_mut.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(array_chunks)]
+let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.array_chunks_mut() {
+ *chunk = [count; 2];
+ count += 1;
+}
+assert_eq!(v, &[1, 1, 2, 2, 0]);array_windows)Returns an iterator over overlapping windows of N elements of a slice,
+starting at the beginning of the slice.
This is the const generic equivalent of windows.
If N is greater than the size of the slice, it will return no windows.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(array_windows)]
+let slice = [0, 1, 2, 3];
+let mut iter = slice.array_windows();
+assert_eq!(iter.next().unwrap(), &[0, 1]);
+assert_eq!(iter.next().unwrap(), &[1, 2]);
+assert_eq!(iter.next().unwrap(), &[2, 3]);
+assert!(iter.next().is_none());Returns an iterator over chunk_size elements of the slice at a time, starting at the end
+of the slice.
The chunks are slices and do not overlap. If chunk_size does not divide the length of the
+slice, then the last chunk will not have length chunk_size.
See rchunks_exact for a variant of this iterator that returns chunks of always exactly
+chunk_size elements, and chunks for the same iterator but starting at the beginning
+of the slice.
Panics if chunk_size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.rchunks(2);
+assert_eq!(iter.next().unwrap(), &['e', 'm']);
+assert_eq!(iter.next().unwrap(), &['o', 'r']);
+assert_eq!(iter.next().unwrap(), &['l']);
+assert!(iter.next().is_none());Returns an iterator over chunk_size elements of the slice at a time, starting at the end
+of the slice.
The chunks are mutable slices, and do not overlap. If chunk_size does not divide the
+length of the slice, then the last chunk will not have length chunk_size.
See rchunks_exact_mut for a variant of this iterator that returns chunks of always
+exactly chunk_size elements, and chunks_mut for the same iterator but starting at the
+beginning of the slice.
Panics if chunk_size is 0.
let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.rchunks_mut(2) {
+ for elem in chunk.iter_mut() {
+ *elem += count;
+ }
+ count += 1;
+}
+assert_eq!(v, &[3, 2, 2, 1, 1]);Returns an iterator over chunk_size elements of the slice at a time, starting at the
+end of the slice.
The chunks are slices and do not overlap. If chunk_size does not divide the length of the
+slice, then the last up to chunk_size-1 elements will be omitted and can be retrieved
+from the remainder function of the iterator.
Due to each chunk having exactly chunk_size elements, the compiler can often optimize the
+resulting code better than in the case of rchunks.
See rchunks for a variant of this iterator that also returns the remainder as a smaller
+chunk, and chunks_exact for the same iterator but starting at the beginning of the
+slice.
Panics if chunk_size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.rchunks_exact(2);
+assert_eq!(iter.next().unwrap(), &['e', 'm']);
+assert_eq!(iter.next().unwrap(), &['o', 'r']);
+assert!(iter.next().is_none());
+assert_eq!(iter.remainder(), &['l']);Returns an iterator over chunk_size elements of the slice at a time, starting at the end
+of the slice.
The chunks are mutable slices, and do not overlap. If chunk_size does not divide the
+length of the slice, then the last up to chunk_size-1 elements will be omitted and can be
+retrieved from the into_remainder function of the iterator.
Due to each chunk having exactly chunk_size elements, the compiler can often optimize the
+resulting code better than in the case of chunks_mut.
See rchunks_mut for a variant of this iterator that also returns the remainder as a
+smaller chunk, and chunks_exact_mut for the same iterator but starting at the beginning
+of the slice.
Panics if chunk_size is 0.
let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.rchunks_exact_mut(2) {
+ for elem in chunk.iter_mut() {
+ *elem += count;
+ }
+ count += 1;
+}
+assert_eq!(v, &[0, 2, 2, 1, 1]);Returns an iterator over the slice producing non-overlapping runs +of elements using the predicate to separate them.
+The predicate is called for every pair of consecutive elements,
+meaning that it is called on slice[0] and slice[1],
+followed by slice[1] and slice[2], and so on.
let slice = &[1, 1, 1, 3, 3, 2, 2, 2];
+
+let mut iter = slice.chunk_by(|a, b| a == b);
+
+assert_eq!(iter.next(), Some(&[1, 1, 1][..]));
+assert_eq!(iter.next(), Some(&[3, 3][..]));
+assert_eq!(iter.next(), Some(&[2, 2, 2][..]));
+assert_eq!(iter.next(), None);This method can be used to extract the sorted subslices:
+ +let slice = &[1, 1, 2, 3, 2, 3, 2, 3, 4];
+
+let mut iter = slice.chunk_by(|a, b| a <= b);
+
+assert_eq!(iter.next(), Some(&[1, 1, 2, 3][..]));
+assert_eq!(iter.next(), Some(&[2, 3][..]));
+assert_eq!(iter.next(), Some(&[2, 3, 4][..]));
+assert_eq!(iter.next(), None);Returns an iterator over the slice producing non-overlapping mutable +runs of elements using the predicate to separate them.
+The predicate is called for every pair of consecutive elements,
+meaning that it is called on slice[0] and slice[1],
+followed by slice[1] and slice[2], and so on.
let slice = &mut [1, 1, 1, 3, 3, 2, 2, 2];
+
+let mut iter = slice.chunk_by_mut(|a, b| a == b);
+
+assert_eq!(iter.next(), Some(&mut [1, 1, 1][..]));
+assert_eq!(iter.next(), Some(&mut [3, 3][..]));
+assert_eq!(iter.next(), Some(&mut [2, 2, 2][..]));
+assert_eq!(iter.next(), None);This method can be used to extract the sorted subslices:
+ +let slice = &mut [1, 1, 2, 3, 2, 3, 2, 3, 4];
+
+let mut iter = slice.chunk_by_mut(|a, b| a <= b);
+
+assert_eq!(iter.next(), Some(&mut [1, 1, 2, 3][..]));
+assert_eq!(iter.next(), Some(&mut [2, 3][..]));
+assert_eq!(iter.next(), Some(&mut [2, 3, 4][..]));
+assert_eq!(iter.next(), None);Divides one slice into two at an index.
+The first will contain all indices from [0, mid) (excluding
+the index mid itself) and the second will contain all
+indices from [mid, len) (excluding the index len itself).
Panics if mid > len. For a non-panicking alternative see
+split_at_checked.
let v = [1, 2, 3, 4, 5, 6];
+
+{
+ let (left, right) = v.split_at(0);
+ assert_eq!(left, []);
+ assert_eq!(right, [1, 2, 3, 4, 5, 6]);
+}
+
+{
+ let (left, right) = v.split_at(2);
+ assert_eq!(left, [1, 2]);
+ assert_eq!(right, [3, 4, 5, 6]);
+}
+
+{
+ let (left, right) = v.split_at(6);
+ assert_eq!(left, [1, 2, 3, 4, 5, 6]);
+ assert_eq!(right, []);
+}Divides one mutable slice into two at an index.
+The first will contain all indices from [0, mid) (excluding
+the index mid itself) and the second will contain all
+indices from [mid, len) (excluding the index len itself).
Panics if mid > len. For a non-panicking alternative see
+split_at_mut_checked.
let mut v = [1, 0, 3, 0, 5, 6];
+let (left, right) = v.split_at_mut(2);
+assert_eq!(left, [1, 0]);
+assert_eq!(right, [3, 0, 5, 6]);
+left[1] = 2;
+right[1] = 4;
+assert_eq!(v, [1, 2, 3, 4, 5, 6]);Divides one slice into two at an index, without doing bounds checking.
+The first will contain all indices from [0, mid) (excluding
+the index mid itself) and the second will contain all
+indices from [mid, len) (excluding the index len itself).
For a safe alternative see split_at.
Calling this method with an out-of-bounds index is undefined behavior
+even if the resulting reference is not used. The caller has to ensure that
+0 <= mid <= self.len().
let v = [1, 2, 3, 4, 5, 6];
+
+unsafe {
+ let (left, right) = v.split_at_unchecked(0);
+ assert_eq!(left, []);
+ assert_eq!(right, [1, 2, 3, 4, 5, 6]);
+}
+
+unsafe {
+ let (left, right) = v.split_at_unchecked(2);
+ assert_eq!(left, [1, 2]);
+ assert_eq!(right, [3, 4, 5, 6]);
+}
+
+unsafe {
+ let (left, right) = v.split_at_unchecked(6);
+ assert_eq!(left, [1, 2, 3, 4, 5, 6]);
+ assert_eq!(right, []);
+}Divides one mutable slice into two at an index, without doing bounds checking.
+The first will contain all indices from [0, mid) (excluding
+the index mid itself) and the second will contain all
+indices from [mid, len) (excluding the index len itself).
For a safe alternative see split_at_mut.
Calling this method with an out-of-bounds index is undefined behavior
+even if the resulting reference is not used. The caller has to ensure that
+0 <= mid <= self.len().
let mut v = [1, 0, 3, 0, 5, 6];
+// scoped to restrict the lifetime of the borrows
+unsafe {
+ let (left, right) = v.split_at_mut_unchecked(2);
+ assert_eq!(left, [1, 0]);
+ assert_eq!(right, [3, 0, 5, 6]);
+ left[1] = 2;
+ right[1] = 4;
+}
+assert_eq!(v, [1, 2, 3, 4, 5, 6]);Divides one slice into two at an index, returning None if the slice is
+too short.
If mid ≤ len returns a pair of slices where the first will contain all
+indices from [0, mid) (excluding the index mid itself) and the
+second will contain all indices from [mid, len) (excluding the index
+len itself).
Otherwise, if mid > len, returns None.
let v = [1, -2, 3, -4, 5, -6];
+
+{
+ let (left, right) = v.split_at_checked(0).unwrap();
+ assert_eq!(left, []);
+ assert_eq!(right, [1, -2, 3, -4, 5, -6]);
+}
+
+{
+ let (left, right) = v.split_at_checked(2).unwrap();
+ assert_eq!(left, [1, -2]);
+ assert_eq!(right, [3, -4, 5, -6]);
+}
+
+{
+ let (left, right) = v.split_at_checked(6).unwrap();
+ assert_eq!(left, [1, -2, 3, -4, 5, -6]);
+ assert_eq!(right, []);
+}
+
+assert_eq!(None, v.split_at_checked(7));Divides one mutable slice into two at an index, returning None if the
+slice is too short.
If mid ≤ len returns a pair of slices where the first will contain all
+indices from [0, mid) (excluding the index mid itself) and the
+second will contain all indices from [mid, len) (excluding the index
+len itself).
Otherwise, if mid > len, returns None.
let mut v = [1, 0, 3, 0, 5, 6];
+
+if let Some((left, right)) = v.split_at_mut_checked(2) {
+ assert_eq!(left, [1, 0]);
+ assert_eq!(right, [3, 0, 5, 6]);
+ left[1] = 2;
+ right[1] = 4;
+}
+assert_eq!(v, [1, 2, 3, 4, 5, 6]);
+
+assert_eq!(None, v.split_at_mut_checked(7));Returns an iterator over subslices separated by elements that match
+pred. The matched element is not contained in the subslices.
let slice = [10, 40, 33, 20];
+let mut iter = slice.split(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[10, 40]);
+assert_eq!(iter.next().unwrap(), &[20]);
+assert!(iter.next().is_none());If the first element is matched, an empty slice will be the first item +returned by the iterator. Similarly, if the last element in the slice +is matched, an empty slice will be the last item returned by the +iterator:
+ +let slice = [10, 40, 33];
+let mut iter = slice.split(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[10, 40]);
+assert_eq!(iter.next().unwrap(), &[]);
+assert!(iter.next().is_none());If two matched elements are directly adjacent, an empty slice will be +present between them:
+ +let slice = [10, 6, 33, 20];
+let mut iter = slice.split(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[10]);
+assert_eq!(iter.next().unwrap(), &[]);
+assert_eq!(iter.next().unwrap(), &[20]);
+assert!(iter.next().is_none());Returns an iterator over mutable subslices separated by elements that
+match pred. The matched element is not contained in the subslices.
let mut v = [10, 40, 30, 20, 60, 50];
+
+for group in v.split_mut(|num| *num % 3 == 0) {
+ group[0] = 1;
+}
+assert_eq!(v, [1, 40, 30, 1, 60, 1]);Returns an iterator over subslices separated by elements that match
+pred. The matched element is contained in the end of the previous
+subslice as a terminator.
let slice = [10, 40, 33, 20];
+let mut iter = slice.split_inclusive(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[10, 40, 33]);
+assert_eq!(iter.next().unwrap(), &[20]);
+assert!(iter.next().is_none());If the last element of the slice is matched, +that element will be considered the terminator of the preceding slice. +That slice will be the last item returned by the iterator.
+ +let slice = [3, 10, 40, 33];
+let mut iter = slice.split_inclusive(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[3]);
+assert_eq!(iter.next().unwrap(), &[10, 40, 33]);
+assert!(iter.next().is_none());Returns an iterator over mutable subslices separated by elements that
+match pred. The matched element is contained in the previous
+subslice as a terminator.
let mut v = [10, 40, 30, 20, 60, 50];
+
+for group in v.split_inclusive_mut(|num| *num % 3 == 0) {
+ let terminator_idx = group.len()-1;
+ group[terminator_idx] = 1;
+}
+assert_eq!(v, [10, 40, 1, 20, 1, 1]);Returns an iterator over subslices separated by elements that match
+pred, starting at the end of the slice and working backwards.
+The matched element is not contained in the subslices.
let slice = [11, 22, 33, 0, 44, 55];
+let mut iter = slice.rsplit(|num| *num == 0);
+
+assert_eq!(iter.next().unwrap(), &[44, 55]);
+assert_eq!(iter.next().unwrap(), &[11, 22, 33]);
+assert_eq!(iter.next(), None);As with split(), if the first or last element is matched, an empty
+slice will be the first (or last) item returned by the iterator.
let v = &[0, 1, 1, 2, 3, 5, 8];
+let mut it = v.rsplit(|n| *n % 2 == 0);
+assert_eq!(it.next().unwrap(), &[]);
+assert_eq!(it.next().unwrap(), &[3, 5]);
+assert_eq!(it.next().unwrap(), &[1, 1]);
+assert_eq!(it.next().unwrap(), &[]);
+assert_eq!(it.next(), None);Returns an iterator over mutable subslices separated by elements that
+match pred, starting at the end of the slice and working
+backwards. The matched element is not contained in the subslices.
let mut v = [100, 400, 300, 200, 600, 500];
+
+let mut count = 0;
+for group in v.rsplit_mut(|num| *num % 3 == 0) {
+ count += 1;
+ group[0] = count;
+}
+assert_eq!(v, [3, 400, 300, 2, 600, 1]);Returns an iterator over subslices separated by elements that match
+pred, limited to returning at most n items. The matched element is
+not contained in the subslices.
The last element returned, if any, will contain the remainder of the +slice.
+Print the slice split once by numbers divisible by 3 (i.e., [10, 40],
+[20, 60, 50]):
let v = [10, 40, 30, 20, 60, 50];
+
+for group in v.splitn(2, |num| *num % 3 == 0) {
+ println!("{group:?}");
+}Returns an iterator over mutable subslices separated by elements that match
+pred, limited to returning at most n items. The matched element is
+not contained in the subslices.
The last element returned, if any, will contain the remainder of the +slice.
+let mut v = [10, 40, 30, 20, 60, 50];
+
+for group in v.splitn_mut(2, |num| *num % 3 == 0) {
+ group[0] = 1;
+}
+assert_eq!(v, [1, 40, 30, 1, 60, 50]);Returns an iterator over subslices separated by elements that match
+pred limited to returning at most n items. This starts at the end of
+the slice and works backwards. The matched element is not contained in
+the subslices.
The last element returned, if any, will contain the remainder of the +slice.
+Print the slice split once, starting from the end, by numbers divisible
+by 3 (i.e., [50], [10, 40, 30, 20]):
let v = [10, 40, 30, 20, 60, 50];
+
+for group in v.rsplitn(2, |num| *num % 3 == 0) {
+ println!("{group:?}");
+}Returns an iterator over subslices separated by elements that match
+pred limited to returning at most n items. This starts at the end of
+the slice and works backwards. The matched element is not contained in
+the subslices.
The last element returned, if any, will contain the remainder of the +slice.
+let mut s = [10, 40, 30, 20, 60, 50];
+
+for group in s.rsplitn_mut(2, |num| *num % 3 == 0) {
+ group[0] = 1;
+}
+assert_eq!(s, [1, 40, 30, 20, 60, 1]);slice_split_once)Splits the slice on the first element that matches the specified +predicate.
+If any matching elements are present in the slice, returns the prefix
+before the match and suffix after. The matching element itself is not
+included. If no elements match, returns None.
#![feature(slice_split_once)]
+let s = [1, 2, 3, 2, 4];
+assert_eq!(s.split_once(|&x| x == 2), Some((
+ &[1][..],
+ &[3, 2, 4][..]
+)));
+assert_eq!(s.split_once(|&x| x == 0), None);slice_split_once)Splits the slice on the last element that matches the specified +predicate.
+If any matching elements are present in the slice, returns the prefix
+before the match and suffix after. The matching element itself is not
+included. If no elements match, returns None.
#![feature(slice_split_once)]
+let s = [1, 2, 3, 2, 4];
+assert_eq!(s.rsplit_once(|&x| x == 2), Some((
+ &[1, 2, 3][..],
+ &[4][..]
+)));
+assert_eq!(s.rsplit_once(|&x| x == 0), None);Returns true if the slice contains an element with the given value.
This operation is O(n).
+Note that if you have a sorted slice, binary_search may be faster.
let v = [10, 40, 30];
+assert!(v.contains(&30));
+assert!(!v.contains(&50));If you do not have a &T, but some other value that you can compare
+with one (for example, String implements PartialEq<str>), you can
+use iter().any:
let v = [String::from("hello"), String::from("world")]; // slice of `String`
+assert!(v.iter().any(|e| e == "hello")); // search with `&str`
+assert!(!v.iter().any(|e| e == "hi"));Returns true if needle is a prefix of the slice or equal to the slice.
let v = [10, 40, 30];
+assert!(v.starts_with(&[10]));
+assert!(v.starts_with(&[10, 40]));
+assert!(v.starts_with(&v));
+assert!(!v.starts_with(&[50]));
+assert!(!v.starts_with(&[10, 50]));Always returns true if needle is an empty slice:
let v = &[10, 40, 30];
+assert!(v.starts_with(&[]));
+let v: &[u8] = &[];
+assert!(v.starts_with(&[]));Returns true if needle is a suffix of the slice or equal to the slice.
let v = [10, 40, 30];
+assert!(v.ends_with(&[30]));
+assert!(v.ends_with(&[40, 30]));
+assert!(v.ends_with(&v));
+assert!(!v.ends_with(&[50]));
+assert!(!v.ends_with(&[50, 30]));Always returns true if needle is an empty slice:
let v = &[10, 40, 30];
+assert!(v.ends_with(&[]));
+let v: &[u8] = &[];
+assert!(v.ends_with(&[]));Returns a subslice with the prefix removed.
+If the slice starts with prefix, returns the subslice after the prefix, wrapped in Some.
+If prefix is empty, simply returns the original slice. If prefix is equal to the
+original slice, returns an empty slice.
If the slice does not start with prefix, returns None.
let v = &[10, 40, 30];
+assert_eq!(v.strip_prefix(&[10]), Some(&[40, 30][..]));
+assert_eq!(v.strip_prefix(&[10, 40]), Some(&[30][..]));
+assert_eq!(v.strip_prefix(&[10, 40, 30]), Some(&[][..]));
+assert_eq!(v.strip_prefix(&[50]), None);
+assert_eq!(v.strip_prefix(&[10, 50]), None);
+
+let prefix : &str = "he";
+assert_eq!(b"hello".strip_prefix(prefix.as_bytes()),
+ Some(b"llo".as_ref()));Returns a subslice with the suffix removed.
+If the slice ends with suffix, returns the subslice before the suffix, wrapped in Some.
+If suffix is empty, simply returns the original slice. If suffix is equal to the
+original slice, returns an empty slice.
If the slice does not end with suffix, returns None.
let v = &[10, 40, 30];
+assert_eq!(v.strip_suffix(&[30]), Some(&[10, 40][..]));
+assert_eq!(v.strip_suffix(&[40, 30]), Some(&[10][..]));
+assert_eq!(v.strip_suffix(&[10, 40, 30]), Some(&[][..]));
+assert_eq!(v.strip_suffix(&[50]), None);
+assert_eq!(v.strip_suffix(&[50, 30]), None);Binary searches this slice for a given element. +If the slice is not sorted, the returned result is unspecified and +meaningless.
+If the value is found then Result::Ok is returned, containing the
+index of the matching element. If there are multiple matches, then any
+one of the matches could be returned. The index is chosen
+deterministically, but is subject to change in future versions of Rust.
+If the value is not found then Result::Err is returned, containing
+the index where a matching element could be inserted while maintaining
+sorted order.
See also binary_search_by, binary_search_by_key, and partition_point.
Looks up a series of four elements. The first is found, with a
+uniquely determined position; the second and third are not
+found; the fourth could match any position in [1, 4].
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+
+assert_eq!(s.binary_search(&13), Ok(9));
+assert_eq!(s.binary_search(&4), Err(7));
+assert_eq!(s.binary_search(&100), Err(13));
+let r = s.binary_search(&1);
+assert!(match r { Ok(1..=4) => true, _ => false, });If you want to find that whole range of matching items, rather than
+an arbitrary matching one, that can be done using partition_point:
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+
+let low = s.partition_point(|x| x < &1);
+assert_eq!(low, 1);
+let high = s.partition_point(|x| x <= &1);
+assert_eq!(high, 5);
+let r = s.binary_search(&1);
+assert!((low..high).contains(&r.unwrap()));
+
+assert!(s[..low].iter().all(|&x| x < 1));
+assert!(s[low..high].iter().all(|&x| x == 1));
+assert!(s[high..].iter().all(|&x| x > 1));
+
+// For something not found, the "range" of equal items is empty
+assert_eq!(s.partition_point(|x| x < &11), 9);
+assert_eq!(s.partition_point(|x| x <= &11), 9);
+assert_eq!(s.binary_search(&11), Err(9));If you want to insert an item to a sorted vector, while maintaining
+sort order, consider using partition_point:
let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+let num = 42;
+let idx = s.partition_point(|&x| x <= num);
+// If `num` is unique, `s.partition_point(|&x| x < num)` (with `<`) is equivalent to
+// `s.binary_search(&num).unwrap_or_else(|x| x)`, but using `<=` will allow `insert`
+// to shift less elements.
+s.insert(idx, num);
+assert_eq!(s, [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]);Binary searches this slice with a comparator function.
+The comparator function should return an order code that indicates
+whether its argument is Less, Equal or Greater the desired
+target.
+If the slice is not sorted or if the comparator function does not
+implement an order consistent with the sort order of the underlying
+slice, the returned result is unspecified and meaningless.
If the value is found then Result::Ok is returned, containing the
+index of the matching element. If there are multiple matches, then any
+one of the matches could be returned. The index is chosen
+deterministically, but is subject to change in future versions of Rust.
+If the value is not found then Result::Err is returned, containing
+the index where a matching element could be inserted while maintaining
+sorted order.
See also binary_search, binary_search_by_key, and partition_point.
Looks up a series of four elements. The first is found, with a
+uniquely determined position; the second and third are not
+found; the fourth could match any position in [1, 4].
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+
+let seek = 13;
+assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Ok(9));
+let seek = 4;
+assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(7));
+let seek = 100;
+assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(13));
+let seek = 1;
+let r = s.binary_search_by(|probe| probe.cmp(&seek));
+assert!(match r { Ok(1..=4) => true, _ => false, });Binary searches this slice with a key extraction function.
+Assumes that the slice is sorted by the key, for instance with
+sort_by_key using the same key extraction function.
+If the slice is not sorted by the key, the returned result is
+unspecified and meaningless.
If the value is found then Result::Ok is returned, containing the
+index of the matching element. If there are multiple matches, then any
+one of the matches could be returned. The index is chosen
+deterministically, but is subject to change in future versions of Rust.
+If the value is not found then Result::Err is returned, containing
+the index where a matching element could be inserted while maintaining
+sorted order.
See also binary_search, binary_search_by, and partition_point.
Looks up a series of four elements in a slice of pairs sorted by
+their second elements. The first is found, with a uniquely
+determined position; the second and third are not found; the
+fourth could match any position in [1, 4].
let s = [(0, 0), (2, 1), (4, 1), (5, 1), (3, 1),
+ (1, 2), (2, 3), (4, 5), (5, 8), (3, 13),
+ (1, 21), (2, 34), (4, 55)];
+
+assert_eq!(s.binary_search_by_key(&13, |&(a, b)| b), Ok(9));
+assert_eq!(s.binary_search_by_key(&4, |&(a, b)| b), Err(7));
+assert_eq!(s.binary_search_by_key(&100, |&(a, b)| b), Err(13));
+let r = s.binary_search_by_key(&1, |&(a, b)| b);
+assert!(match r { Ok(1..=4) => true, _ => false, });Sorts the slice without preserving the initial order of equal elements.
+This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not +allocate), and O(n * log(n)) worst-case.
+If T: Ord does not implement a total order the resulting order is unspecified. All
+original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if T: Ord panics.
The current implementation is based on ipnsort by Lukas Bergdoll and Orson Peters, which +combines the fast average case of quicksort with the fast worst case of heapsort, achieving +linear time on fully sorted and reversed inputs. On inputs with k distinct elements, the +expected time to sort the data is O(n * log(k)).
+It is typically faster than stable sorting, except in a few special cases, e.g., when the +slice is partially sorted.
+If T: Ord does not implement a total order, the implementation may panic.
let mut v = [-5, 4, 1, -3, 2];
+
+v.sort_unstable();
+assert!(v == [-5, -3, 1, 2, 4]);Sorts the slice with a comparator function, without preserving the initial order of +equal elements.
+This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not +allocate), and O(n * log(n)) worst-case.
+The comparator function should define a total ordering for the elements in the slice. If the +ordering is not total, the order of the elements is unspecified.
+If the comparator function does not implement a total order the resulting order is
+unspecified. All original elements will remain in the slice and any possible modifications
+via interior mutability are observed in the input. Same is true if the comparator function
+panics. A total order (for all a, b and c):
a < b, a == b or a > b is true, anda < b and b < c implies a < c. The same must hold for both == and >.For example, while f64 doesn’t implement Ord because NaN != NaN, we can use
+partial_cmp as our sort function when we know the slice doesn’t contain a NaN.
let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
+floats.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap());
+assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);The current implementation is based on ipnsort by Lukas Bergdoll and Orson Peters, which +combines the fast average case of quicksort with the fast worst case of heapsort, achieving +linear time on fully sorted and reversed inputs. On inputs with k distinct elements, the +expected time to sort the data is O(n * log(k)).
+It is typically faster than stable sorting, except in a few special cases, e.g., when the +slice is partially sorted.
+If T: Ord does not implement a total order, the implementation may panic.
let mut v = [5, 4, 1, 3, 2];
+v.sort_unstable_by(|a, b| a.cmp(b));
+assert!(v == [1, 2, 3, 4, 5]);
+
+// reverse sorting
+v.sort_unstable_by(|a, b| b.cmp(a));
+assert!(v == [5, 4, 3, 2, 1]);Sorts the slice with a key extraction function, without preserving the initial order of +equal elements.
+This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not +allocate), and O(n * log(n)) worst-case.
+If K: Ord does not implement a total order the resulting order is unspecified.
+All original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if K: Ord panics.
The current implementation is based on ipnsort by Lukas Bergdoll and Orson Peters, which +combines the fast average case of quicksort with the fast worst case of heapsort, achieving +linear time on fully sorted and reversed inputs. On inputs with k distinct elements, the +expected time to sort the data is O(n * log(k)).
+It is typically faster than stable sorting, except in a few special cases, e.g., when the +slice is partially sorted.
+If K: Ord does not implement a total order, the implementation may panic.
let mut v = [-5i32, 4, 1, -3, 2];
+
+v.sort_unstable_by_key(|k| k.abs());
+assert!(v == [1, 2, -3, 4, -5]);Reorder the slice such that the element at index after the reordering is at its final
+sorted position.
This reordering has the additional property that any value at position i < index will be
+less than or equal to any value at a position j > index. Additionally, this reordering is
+unstable (i.e. any number of equal elements may end up at position index), in-place (i.e.
+does not allocate), and runs in O(n) time. This function is also known as “kth element”
+in other libraries.
It returns a triplet of the following from the reordered slice: the subslice prior to
+index, the element at index, and the subslice after index; accordingly, the values in
+those two subslices will respectively all be less-than-or-equal-to and
+greater-than-or-equal-to the value of the element at index.
The current algorithm is an introselect implementation based on ipnsort by Lukas Bergdoll
+and Orson Peters, which is also the basis for sort_unstable. The fallback algorithm is
+Median of Medians using Tukey’s Ninther for pivot selection, which guarantees linear runtime
+for all inputs.
It is typically faster than stable sorting, except in a few special cases, e.g., when the
+slice is nearly fully sorted, where slice::sort may be faster.
Panics when index >= len(), meaning it always panics on empty slices.
let mut v = [-5i32, 4, 2, -3, 1];
+
+// Find the items less than or equal to the median, the median, and greater than or equal to
+// the median.
+let (lesser, median, greater) = v.select_nth_unstable(2);
+
+assert!(lesser == [-3, -5] || lesser == [-5, -3]);
+assert_eq!(median, &mut 1);
+assert!(greater == [4, 2] || greater == [2, 4]);
+
+// We are only guaranteed the slice will be one of the following, based on the way we sort
+// about the specified index.
+assert!(v == [-3, -5, 1, 2, 4] ||
+ v == [-5, -3, 1, 2, 4] ||
+ v == [-3, -5, 1, 4, 2] ||
+ v == [-5, -3, 1, 4, 2]);Reorder the slice with a comparator function such that the element at index after the
+reordering is at its final sorted position.
This reordering has the additional property that any value at position i < index will be
+less than or equal to any value at a position j > index using the comparator function.
+Additionally, this reordering is unstable (i.e. any number of equal elements may end up at
+position index), in-place (i.e. does not allocate), and runs in O(n) time. This
+function is also known as “kth element” in other libraries.
It returns a triplet of the following from the slice reordered according to the provided
+comparator function: the subslice prior to index, the element at index, and the subslice
+after index; accordingly, the values in those two subslices will respectively all be
+less-than-or-equal-to and greater-than-or-equal-to the value of the element at index.
The current algorithm is an introselect implementation based on ipnsort by Lukas Bergdoll
+and Orson Peters, which is also the basis for sort_unstable. The fallback algorithm is
+Median of Medians using Tukey’s Ninther for pivot selection, which guarantees linear runtime
+for all inputs.
It is typically faster than stable sorting, except in a few special cases, e.g., when the
+slice is nearly fully sorted, where slice::sort may be faster.
Panics when index >= len(), meaning it always panics on empty slices.
let mut v = [-5i32, 4, 2, -3, 1];
+
+// Find the items less than or equal to the median, the median, and greater than or equal to
+// the median as if the slice were sorted in descending order.
+let (lesser, median, greater) = v.select_nth_unstable_by(2, |a, b| b.cmp(a));
+
+assert!(lesser == [4, 2] || lesser == [2, 4]);
+assert_eq!(median, &mut 1);
+assert!(greater == [-3, -5] || greater == [-5, -3]);
+
+// We are only guaranteed the slice will be one of the following, based on the way we sort
+// about the specified index.
+assert!(v == [2, 4, 1, -5, -3] ||
+ v == [2, 4, 1, -3, -5] ||
+ v == [4, 2, 1, -5, -3] ||
+ v == [4, 2, 1, -3, -5]);Reorder the slice with a key extraction function such that the element at index after the
+reordering is at its final sorted position.
This reordering has the additional property that any value at position i < index will be
+less than or equal to any value at a position j > index using the key extraction function.
+Additionally, this reordering is unstable (i.e. any number of equal elements may end up at
+position index), in-place (i.e. does not allocate), and runs in O(n) time. This
+function is also known as “kth element” in other libraries.
It returns a triplet of the following from the slice reordered according to the provided key
+extraction function: the subslice prior to index, the element at index, and the subslice
+after index; accordingly, the values in those two subslices will respectively all be
+less-than-or-equal-to and greater-than-or-equal-to the value of the element at index.
The current algorithm is an introselect implementation based on ipnsort by Lukas Bergdoll
+and Orson Peters, which is also the basis for sort_unstable. The fallback algorithm is
+Median of Medians using Tukey’s Ninther for pivot selection, which guarantees linear runtime
+for all inputs.
It is typically faster than stable sorting, except in a few special cases, e.g., when the
+slice is nearly fully sorted, where slice::sort may be faster.
Panics when index >= len(), meaning it always panics on empty slices.
let mut v = [-5i32, 4, 1, -3, 2];
+
+// Find the items less than or equal to the median, the median, and greater than or equal to
+// the median as if the slice were sorted according to absolute value.
+let (lesser, median, greater) = v.select_nth_unstable_by_key(2, |a| a.abs());
+
+assert!(lesser == [1, 2] || lesser == [2, 1]);
+assert_eq!(median, &mut -3);
+assert!(greater == [4, -5] || greater == [-5, 4]);
+
+// We are only guaranteed the slice will be one of the following, based on the way we sort
+// about the specified index.
+assert!(v == [1, 2, -3, 4, -5] ||
+ v == [1, 2, -3, -5, 4] ||
+ v == [2, 1, -3, 4, -5] ||
+ v == [2, 1, -3, -5, 4]);slice_partition_dedup)Moves all consecutive repeated elements to the end of the slice according to the
+PartialEq trait implementation.
Returns two slices. The first contains no consecutive repeated elements. +The second contains all the duplicates in no specified order.
+If the slice is sorted, the first returned slice contains no duplicates.
+#![feature(slice_partition_dedup)]
+
+let mut slice = [1, 2, 2, 3, 3, 2, 1, 1];
+
+let (dedup, duplicates) = slice.partition_dedup();
+
+assert_eq!(dedup, [1, 2, 3, 2, 1]);
+assert_eq!(duplicates, [2, 3, 1]);slice_partition_dedup)Moves all but the first of consecutive elements to the end of the slice satisfying +a given equality relation.
+Returns two slices. The first contains no consecutive repeated elements. +The second contains all the duplicates in no specified order.
+The same_bucket function is passed references to two elements from the slice and
+must determine if the elements compare equal. The elements are passed in opposite order
+from their order in the slice, so if same_bucket(a, b) returns true, a is moved
+at the end of the slice.
If the slice is sorted, the first returned slice contains no duplicates.
+#![feature(slice_partition_dedup)]
+
+let mut slice = ["foo", "Foo", "BAZ", "Bar", "bar", "baz", "BAZ"];
+
+let (dedup, duplicates) = slice.partition_dedup_by(|a, b| a.eq_ignore_ascii_case(b));
+
+assert_eq!(dedup, ["foo", "BAZ", "Bar", "baz"]);
+assert_eq!(duplicates, ["bar", "Foo", "BAZ"]);slice_partition_dedup)Moves all but the first of consecutive elements to the end of the slice that resolve +to the same key.
+Returns two slices. The first contains no consecutive repeated elements. +The second contains all the duplicates in no specified order.
+If the slice is sorted, the first returned slice contains no duplicates.
+#![feature(slice_partition_dedup)]
+
+let mut slice = [10, 20, 21, 30, 30, 20, 11, 13];
+
+let (dedup, duplicates) = slice.partition_dedup_by_key(|i| *i / 10);
+
+assert_eq!(dedup, [10, 20, 30, 20, 11]);
+assert_eq!(duplicates, [21, 30, 13]);Rotates the slice in-place such that the first mid elements of the
+slice move to the end while the last self.len() - mid elements move to
+the front. After calling rotate_left, the element previously at index
+mid will become the first element in the slice.
This function will panic if mid is greater than the length of the
+slice. Note that mid == self.len() does not panic and is a no-op
+rotation.
Takes linear (in self.len()) time.
let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
+a.rotate_left(2);
+assert_eq!(a, ['c', 'd', 'e', 'f', 'a', 'b']);Rotating a subslice:
+ +let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
+a[1..5].rotate_left(1);
+assert_eq!(a, ['a', 'c', 'd', 'e', 'b', 'f']);Rotates the slice in-place such that the first self.len() - k
+elements of the slice move to the end while the last k elements move
+to the front. After calling rotate_right, the element previously at
+index self.len() - k will become the first element in the slice.
This function will panic if k is greater than the length of the
+slice. Note that k == self.len() does not panic and is a no-op
+rotation.
Takes linear (in self.len()) time.
let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
+a.rotate_right(2);
+assert_eq!(a, ['e', 'f', 'a', 'b', 'c', 'd']);Rotating a subslice:
+ +let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
+a[1..5].rotate_right(1);
+assert_eq!(a, ['a', 'e', 'b', 'c', 'd', 'f']);Fills self with elements by cloning value.
let mut buf = vec![0; 10];
+buf.fill(1);
+assert_eq!(buf, vec![1; 10]);Fills self with elements returned by calling a closure repeatedly.
This method uses a closure to create new values. If you’d rather
+Clone a given value, use fill. If you want to use the Default
+trait to generate values, you can pass Default::default as the
+argument.
let mut buf = vec![1; 10];
+buf.fill_with(Default::default);
+assert_eq!(buf, vec![0; 10]);Copies the elements from src into self.
The length of src must be the same as self.
This function will panic if the two slices have different lengths.
+Cloning two elements from a slice into another:
+ +let src = [1, 2, 3, 4];
+let mut dst = [0, 0];
+
+// Because the slices have to be the same length,
+// we slice the source slice from four elements
+// to two. It will panic if we don't do this.
+dst.clone_from_slice(&src[2..]);
+
+assert_eq!(src, [1, 2, 3, 4]);
+assert_eq!(dst, [3, 4]);Rust enforces that there can only be one mutable reference with no
+immutable references to a particular piece of data in a particular
+scope. Because of this, attempting to use clone_from_slice on a
+single slice will result in a compile failure:
let mut slice = [1, 2, 3, 4, 5];
+
+slice[..2].clone_from_slice(&slice[3..]); // compile fail!To work around this, we can use split_at_mut to create two distinct
+sub-slices from a slice:
let mut slice = [1, 2, 3, 4, 5];
+
+{
+ let (left, right) = slice.split_at_mut(2);
+ left.clone_from_slice(&right[1..]);
+}
+
+assert_eq!(slice, [4, 5, 3, 4, 5]);Copies all elements from src into self, using a memcpy.
The length of src must be the same as self.
If T does not implement Copy, use clone_from_slice.
This function will panic if the two slices have different lengths.
+Copying two elements from a slice into another:
+ +let src = [1, 2, 3, 4];
+let mut dst = [0, 0];
+
+// Because the slices have to be the same length,
+// we slice the source slice from four elements
+// to two. It will panic if we don't do this.
+dst.copy_from_slice(&src[2..]);
+
+assert_eq!(src, [1, 2, 3, 4]);
+assert_eq!(dst, [3, 4]);Rust enforces that there can only be one mutable reference with no
+immutable references to a particular piece of data in a particular
+scope. Because of this, attempting to use copy_from_slice on a
+single slice will result in a compile failure:
let mut slice = [1, 2, 3, 4, 5];
+
+slice[..2].copy_from_slice(&slice[3..]); // compile fail!To work around this, we can use split_at_mut to create two distinct
+sub-slices from a slice:
let mut slice = [1, 2, 3, 4, 5];
+
+{
+ let (left, right) = slice.split_at_mut(2);
+ left.copy_from_slice(&right[1..]);
+}
+
+assert_eq!(slice, [4, 5, 3, 4, 5]);Copies elements from one part of the slice to another part of itself, +using a memmove.
+src is the range within self to copy from. dest is the starting
+index of the range within self to copy to, which will have the same
+length as src. The two ranges may overlap. The ends of the two ranges
+must be less than or equal to self.len().
This function will panic if either range exceeds the end of the slice,
+or if the end of src is before the start.
Copying four bytes within a slice:
+ +let mut bytes = *b"Hello, World!";
+
+bytes.copy_within(1..5, 8);
+
+assert_eq!(&bytes, b"Hello, Wello!");Swaps all elements in self with those in other.
The length of other must be the same as self.
This function will panic if the two slices have different lengths.
+Swapping two elements across slices:
+ +let mut slice1 = [0, 0];
+let mut slice2 = [1, 2, 3, 4];
+
+slice1.swap_with_slice(&mut slice2[2..]);
+
+assert_eq!(slice1, [3, 4]);
+assert_eq!(slice2, [1, 2, 0, 0]);Rust enforces that there can only be one mutable reference to a
+particular piece of data in a particular scope. Because of this,
+attempting to use swap_with_slice on a single slice will result in
+a compile failure:
let mut slice = [1, 2, 3, 4, 5];
+slice[..2].swap_with_slice(&mut slice[3..]); // compile fail!To work around this, we can use split_at_mut to create two distinct
+mutable sub-slices from a slice:
let mut slice = [1, 2, 3, 4, 5];
+
+{
+ let (left, right) = slice.split_at_mut(2);
+ left.swap_with_slice(&mut right[1..]);
+}
+
+assert_eq!(slice, [4, 5, 3, 1, 2]);Transmute the slice to a slice of another type, ensuring alignment of the types is +maintained.
+This method splits the slice into three distinct slices: prefix, correctly aligned middle +slice of a new type, and the suffix slice. The middle part will be as big as possible under +the given alignment constraint and element size.
+This method has no purpose when either input element T or output element U are
+zero-sized and will return the original slice without splitting anything.
This method is essentially a transmute with respect to the elements in the returned
+middle slice, so all the usual caveats pertaining to transmute::<T, U> also apply here.
Basic usage:
+ +unsafe {
+ let bytes: [u8; 7] = [1, 2, 3, 4, 5, 6, 7];
+ let (prefix, shorts, suffix) = bytes.align_to::<u16>();
+ // less_efficient_algorithm_for_bytes(prefix);
+ // more_efficient_algorithm_for_aligned_shorts(shorts);
+ // less_efficient_algorithm_for_bytes(suffix);
+}Transmute the mutable slice to a mutable slice of another type, ensuring alignment of the +types is maintained.
+This method splits the slice into three distinct slices: prefix, correctly aligned middle +slice of a new type, and the suffix slice. The middle part will be as big as possible under +the given alignment constraint and element size.
+This method has no purpose when either input element T or output element U are
+zero-sized and will return the original slice without splitting anything.
This method is essentially a transmute with respect to the elements in the returned
+middle slice, so all the usual caveats pertaining to transmute::<T, U> also apply here.
Basic usage:
+ +unsafe {
+ let mut bytes: [u8; 7] = [1, 2, 3, 4, 5, 6, 7];
+ let (prefix, shorts, suffix) = bytes.align_to_mut::<u16>();
+ // less_efficient_algorithm_for_bytes(prefix);
+ // more_efficient_algorithm_for_aligned_shorts(shorts);
+ // less_efficient_algorithm_for_bytes(suffix);
+}portable_simd)Split a slice into a prefix, a middle of aligned SIMD types, and a suffix.
+This is a safe wrapper around slice::align_to, so has the same weak
+postconditions as that method. You’re only assured that
+self.len() == prefix.len() + middle.len() * LANES + suffix.len().
Notably, all of the following are possible:
+prefix.len() >= LANES.middle.is_empty() despite self.len() >= 3 * LANES.suffix.len() >= LANES.That said, this is a safe method, so if you’re only writing safe code, +then this can at most cause incorrect logic, not unsoundness.
+This will panic if the size of the SIMD type is different from
+LANES times that of the scalar.
At the time of writing, the trait restrictions on Simd<T, LANES> keeps
+that from ever happening, as only power-of-two numbers of lanes are
+supported. It’s possible that, in the future, those restrictions might
+be lifted in a way that would make it possible to see panics from this
+method for something like LANES == 3.
#![feature(portable_simd)]
+use core::simd::prelude::*;
+
+let short = &[1, 2, 3];
+let (prefix, middle, suffix) = short.as_simd::<4>();
+assert_eq!(middle, []); // Not enough elements for anything in the middle
+
+// They might be split in any possible way between prefix and suffix
+let it = prefix.iter().chain(suffix).copied();
+assert_eq!(it.collect::<Vec<_>>(), vec![1, 2, 3]);
+
+fn basic_simd_sum(x: &[f32]) -> f32 {
+ use std::ops::Add;
+ let (prefix, middle, suffix) = x.as_simd();
+ let sums = f32x4::from_array([
+ prefix.iter().copied().sum(),
+ 0.0,
+ 0.0,
+ suffix.iter().copied().sum(),
+ ]);
+ let sums = middle.iter().copied().fold(sums, f32x4::add);
+ sums.reduce_sum()
+}
+
+let numbers: Vec<f32> = (1..101).map(|x| x as _).collect();
+assert_eq!(basic_simd_sum(&numbers[1..99]), 4949.0);portable_simd)Split a mutable slice into a mutable prefix, a middle of aligned SIMD types, +and a mutable suffix.
+This is a safe wrapper around slice::align_to_mut, so has the same weak
+postconditions as that method. You’re only assured that
+self.len() == prefix.len() + middle.len() * LANES + suffix.len().
Notably, all of the following are possible:
+prefix.len() >= LANES.middle.is_empty() despite self.len() >= 3 * LANES.suffix.len() >= LANES.That said, this is a safe method, so if you’re only writing safe code, +then this can at most cause incorrect logic, not unsoundness.
+This is the mutable version of slice::as_simd; see that for examples.
This will panic if the size of the SIMD type is different from
+LANES times that of the scalar.
At the time of writing, the trait restrictions on Simd<T, LANES> keeps
+that from ever happening, as only power-of-two numbers of lanes are
+supported. It’s possible that, in the future, those restrictions might
+be lifted in a way that would make it possible to see panics from this
+method for something like LANES == 3.
is_sorted)Checks if the elements of this slice are sorted.
+That is, for each element a and its following element b, a <= b must hold. If the
+slice yields exactly zero or one element, true is returned.
Note that if Self::Item is only PartialOrd, but not Ord, the above definition
+implies that this function returns false if any two consecutive items are not
+comparable.
#![feature(is_sorted)]
+let empty: [i32; 0] = [];
+
+assert!([1, 2, 2, 9].is_sorted());
+assert!(![1, 3, 2, 4].is_sorted());
+assert!([0].is_sorted());
+assert!(empty.is_sorted());
+assert!(![0.0, 1.0, f32::NAN].is_sorted());is_sorted)Checks if the elements of this slice are sorted using the given comparator function.
+Instead of using PartialOrd::partial_cmp, this function uses the given compare
+function to determine whether two elements are to be considered in sorted order.
#![feature(is_sorted)]
+
+assert!([1, 2, 2, 9].is_sorted_by(|a, b| a <= b));
+assert!(![1, 2, 2, 9].is_sorted_by(|a, b| a < b));
+
+assert!([0].is_sorted_by(|a, b| true));
+assert!([0].is_sorted_by(|a, b| false));
+
+let empty: [i32; 0] = [];
+assert!(empty.is_sorted_by(|a, b| false));
+assert!(empty.is_sorted_by(|a, b| true));is_sorted)Checks if the elements of this slice are sorted using the given key extraction function.
+Instead of comparing the slice’s elements directly, this function compares the keys of the
+elements, as determined by f. Apart from that, it’s equivalent to is_sorted; see its
+documentation for more information.
#![feature(is_sorted)]
+
+assert!(["c", "bb", "aaa"].is_sorted_by_key(|s| s.len()));
+assert!(![-2i32, -1, 0, 3].is_sorted_by_key(|n| n.abs()));Returns the index of the partition point according to the given predicate +(the index of the first element of the second partition).
+The slice is assumed to be partitioned according to the given predicate.
+This means that all elements for which the predicate returns true are at the start of the slice
+and all elements for which the predicate returns false are at the end.
+For example, [7, 15, 3, 5, 4, 12, 6] is partitioned under the predicate x % 2 != 0
+(all odd numbers are at the start, all even at the end).
If this slice is not partitioned, the returned result is unspecified and meaningless, +as this method performs a kind of binary search.
+See also binary_search, binary_search_by, and binary_search_by_key.
let v = [1, 2, 3, 3, 5, 6, 7];
+let i = v.partition_point(|&x| x < 5);
+
+assert_eq!(i, 4);
+assert!(v[..i].iter().all(|&x| x < 5));
+assert!(v[i..].iter().all(|&x| !(x < 5)));If all elements of the slice match the predicate, including if the slice +is empty, then the length of the slice will be returned:
+ +let a = [2, 4, 8];
+assert_eq!(a.partition_point(|x| x < &100), a.len());
+let a: [i32; 0] = [];
+assert_eq!(a.partition_point(|x| x < &100), 0);If you want to insert an item to a sorted vector, while maintaining +sort order:
+ +let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+let num = 42;
+let idx = s.partition_point(|&x| x <= num);
+s.insert(idx, num);
+assert_eq!(s, [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]);slice_take)Removes the subslice corresponding to the given range +and returns a reference to it.
+Returns None and does not modify the slice if the given
+range is out of bounds.
Note that this method only accepts one-sided ranges such as
+2.. or ..6, but not 2..6.
Taking the first three elements of a slice:
+ +#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c', 'd'];
+let mut first_three = slice.take(..3).unwrap();
+
+assert_eq!(slice, &['d']);
+assert_eq!(first_three, &['a', 'b', 'c']);Taking the last two elements of a slice:
+ +#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c', 'd'];
+let mut tail = slice.take(2..).unwrap();
+
+assert_eq!(slice, &['a', 'b']);
+assert_eq!(tail, &['c', 'd']);Getting None when range is out of bounds:
#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c', 'd'];
+
+assert_eq!(None, slice.take(5..));
+assert_eq!(None, slice.take(..5));
+assert_eq!(None, slice.take(..=4));
+let expected: &[char] = &['a', 'b', 'c', 'd'];
+assert_eq!(Some(expected), slice.take(..4));slice_take)Removes the subslice corresponding to the given range +and returns a mutable reference to it.
+Returns None and does not modify the slice if the given
+range is out of bounds.
Note that this method only accepts one-sided ranges such as
+2.. or ..6, but not 2..6.
Taking the first three elements of a slice:
+ +#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd'];
+let mut first_three = slice.take_mut(..3).unwrap();
+
+assert_eq!(slice, &mut ['d']);
+assert_eq!(first_three, &mut ['a', 'b', 'c']);Taking the last two elements of a slice:
+ +#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd'];
+let mut tail = slice.take_mut(2..).unwrap();
+
+assert_eq!(slice, &mut ['a', 'b']);
+assert_eq!(tail, &mut ['c', 'd']);Getting None when range is out of bounds:
#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd'];
+
+assert_eq!(None, slice.take_mut(5..));
+assert_eq!(None, slice.take_mut(..5));
+assert_eq!(None, slice.take_mut(..=4));
+let expected: &mut [_] = &mut ['a', 'b', 'c', 'd'];
+assert_eq!(Some(expected), slice.take_mut(..4));slice_take)Removes the first element of the slice and returns a reference +to it.
+Returns None if the slice is empty.
#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c'];
+let first = slice.take_first().unwrap();
+
+assert_eq!(slice, &['b', 'c']);
+assert_eq!(first, &'a');slice_take)Removes the first element of the slice and returns a mutable +reference to it.
+Returns None if the slice is empty.
#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c'];
+let first = slice.take_first_mut().unwrap();
+*first = 'd';
+
+assert_eq!(slice, &['b', 'c']);
+assert_eq!(first, &'d');slice_take)Removes the last element of the slice and returns a reference +to it.
+Returns None if the slice is empty.
#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c'];
+let last = slice.take_last().unwrap();
+
+assert_eq!(slice, &['a', 'b']);
+assert_eq!(last, &'c');slice_take)Removes the last element of the slice and returns a mutable +reference to it.
+Returns None if the slice is empty.
#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c'];
+let last = slice.take_last_mut().unwrap();
+*last = 'd';
+
+assert_eq!(slice, &['a', 'b']);
+assert_eq!(last, &'d');get_many_mut)Returns mutable references to many indices at once, without doing any checks.
+For a safe alternative see get_many_mut.
Calling this method with overlapping or out-of-bounds indices is undefined behavior +even if the resulting references are not used.
+#![feature(get_many_mut)]
+
+let x = &mut [1, 2, 4];
+
+unsafe {
+ let [a, b] = x.get_many_unchecked_mut([0, 2]);
+ *a *= 10;
+ *b *= 100;
+}
+assert_eq!(x, &[10, 2, 400]);get_many_mut)Returns mutable references to many indices at once.
+Returns an error if any index is out-of-bounds, or if the same index was +passed more than once.
+#![feature(get_many_mut)]
+
+let v = &mut [1, 2, 3];
+if let Ok([a, b]) = v.get_many_mut([0, 2]) {
+ *a = 413;
+ *b = 612;
+}
+assert_eq!(v, &[413, 2, 612]);Sorts the slice, preserving initial order of equal elements.
+This sort is stable (i.e., does not reorder equal elements) and O(n * log(n)) +worst-case.
+If T: Ord does not implement a total order the resulting order is unspecified. All
+original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if T: Ord panics.
When applicable, unstable sorting is preferred because it is generally faster than stable
+sorting and it doesn’t allocate auxiliary memory. See
+sort_unstable. The exception are partially sorted slices, which
+may be better served with slice::sort.
The current implementation is based on driftsort by Orson Peters and Lukas Bergdoll, which +combines the fast average case of quicksort with the fast worst case and partial run +detection of mergesort, achieving linear time on fully sorted and reversed inputs. On inputs +with k distinct elements, the expected time to sort the data is O(n * log(k)).
+The auxiliary memory allocation behavior depends on the input length. Short slices are
+handled without allocation, medium sized slices allocate self.len() and beyond that it
+clamps at self.len() / 2.
If T: Ord does not implement a total order, the implementation may panic.
let mut v = [-5, 4, 1, -3, 2];
+
+v.sort();
+assert!(v == [-5, -3, 1, 2, 4]);Sorts the slice with a comparator function, preserving initial order of equal elements.
+This sort is stable (i.e., does not reorder equal elements) and O(n * log(n)) +worst-case.
+The comparator function should define a total ordering for the elements in the slice. If the +ordering is not total, the order of the elements is unspecified.
+If the comparator function does not implement a total order the resulting order is
+unspecified. All original elements will remain in the slice and any possible modifications
+via interior mutability are observed in the input. Same is true if the comparator function
+panics. A total order (for all a, b and c):
a < b, a == b or a > b is true, anda < b and b < c implies a < c. The same must hold for both == and >.For example, while f64 doesn’t implement Ord because NaN != NaN, we can use
+partial_cmp as our sort function when we know the slice doesn’t contain a NaN.
let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
+floats.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap());
+assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);The current implementation is based on driftsort by Orson Peters and Lukas Bergdoll, which +combines the fast average case of quicksort with the fast worst case and partial run +detection of mergesort, achieving linear time on fully sorted and reversed inputs. On inputs +with k distinct elements, the expected time to sort the data is O(n * log(k)).
+The auxiliary memory allocation behavior depends on the input length. Short slices are
+handled without allocation, medium sized slices allocate self.len() and beyond that it
+clamps at self.len() / 2.
If T: Ord does not implement a total order, the implementation may panic.
let mut v = [5, 4, 1, 3, 2];
+v.sort_by(|a, b| a.cmp(b));
+assert!(v == [1, 2, 3, 4, 5]);
+
+// reverse sorting
+v.sort_by(|a, b| b.cmp(a));
+assert!(v == [5, 4, 3, 2, 1]);Sorts the slice with a key extraction function, preserving initial order of equal elements.
+This sort is stable (i.e., does not reorder equal elements) and O(m * n * log(n)) +worst-case, where the key function is O(m).
+If K: Ord does not implement a total order the resulting order is unspecified.
+All original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if K: Ord panics.
The current implementation is based on driftsort by Orson Peters and Lukas Bergdoll, which +combines the fast average case of quicksort with the fast worst case and partial run +detection of mergesort, achieving linear time on fully sorted and reversed inputs. On inputs +with k distinct elements, the expected time to sort the data is O(n * log(k)).
+The auxiliary memory allocation behavior depends on the input length. Short slices are
+handled without allocation, medium sized slices allocate self.len() and beyond that it
+clamps at self.len() / 2.
If K: Ord does not implement a total order, the implementation may panic.
let mut v = [-5i32, 4, 1, -3, 2];
+
+v.sort_by_key(|k| k.abs());
+assert!(v == [1, 2, -3, 4, -5]);Sorts the slice with a key extraction function, preserving initial order of equal elements.
+This sort is stable (i.e., does not reorder equal elements) and O(m * n + n * +log(n)) worst-case, where the key function is O(m).
+During sorting, the key function is called at most once per element, by using temporary +storage to remember the results of key evaluation. The order of calls to the key function is +unspecified and may change in future versions of the standard library.
+If K: Ord does not implement a total order the resulting order is unspecified.
+All original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if K: Ord panics.
For simple key functions (e.g., functions that are property accesses or basic operations),
+sort_by_key is likely to be faster.
The current implementation is based on instruction-parallel-network sort by Lukas +Bergdoll, which combines the fast average case of randomized quicksort with the fast worst +case of heapsort, while achieving linear time on fully sorted and reversed inputs. And +O(k * log(n)) where k is the number of distinct elements in the input. It leverages +superscalar out-of-order execution capabilities commonly found in CPUs, to efficiently +perform the operation.
+In the worst case, the algorithm allocates temporary storage in a Vec<(K, usize)> the
+length of the slice.
let mut v = [-5i32, 4, 32, -3, 2];
+
+v.sort_by_cached_key(|k| k.to_string());
+assert!(v == [-3, -5, 2, 32, 4]);Copies self into a new Vec.
let s = [10, 40, 30];
+let x = s.to_vec();
+// Here, `s` and `x` can be modified independently.allocator_api)Copies self into a new Vec with an allocator.
#![feature(allocator_api)]
+
+use std::alloc::System;
+
+let s = [10, 40, 30];
+let x = s.to_vec_in(System);
+// Here, `s` and `x` can be modified independently.Flattens a slice of T into a single value Self::Output.
assert_eq!(["hello", "world"].concat(), "helloworld");
+assert_eq!([[1, 2], [3, 4]].concat(), [1, 2, 3, 4]);Flattens a slice of T into a single value Self::Output, placing a
+given separator between each.
assert_eq!(["hello", "world"].join(" "), "hello world");
+assert_eq!([[1, 2], [3, 4]].join(&0), [1, 2, 0, 3, 4]);
+assert_eq!([[1, 2], [3, 4]].join(&[0, 0][..]), [1, 2, 0, 0, 3, 4]);Flattens a slice of T into a single value Self::Output, placing a
+given separator between each.
assert_eq!(["hello", "world"].connect(" "), "hello world");
+assert_eq!([[1, 2], [3, 4]].connect(&0), [1, 2, 0, 3, 4]);Returns a vector containing a copy of this slice where each byte +is mapped to its ASCII upper case equivalent.
+ASCII letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’, +but non-ASCII letters are unchanged.
+To uppercase the value in-place, use make_ascii_uppercase.
Returns a vector containing a copy of this slice where each byte +is mapped to its ASCII lower case equivalent.
+ASCII letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’, +but non-ASCII letters are unchanged.
+To lowercase the value in-place, use make_ascii_lowercase.
try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub enum Body {
+Show 64 variants
Empty {},
+ Error(Error),
+ RuntimeInfoRequest(RuntimeInfoRequest),
+ RuntimeInfoResponse(RuntimeInfoResponse),
+ RuntimePingRequest {},
+ RuntimeShutdownRequest {},
+ RuntimeAbortRequest {},
+ RuntimeAbortResponse {},
+ RuntimeCapabilityTEERakInitRequest {
+ target_info: Vec<u8>,
+ },
+ RuntimeCapabilityTEERakInitResponse {},
+ RuntimeCapabilityTEERakReportRequest {},
+ RuntimeCapabilityTEERakReportResponse {
+ rak_pub: PublicKey,
+ rek_pub: PublicKey,
+ report: Vec<u8>,
+ nonce: String,
+ },
+ RuntimeCapabilityTEERakAvrRequest {
+ avr: AVR,
+ },
+ RuntimeCapabilityTEERakAvrResponse {},
+ RuntimeCapabilityTEERakQuoteRequest {
+ quote: Quote,
+ },
+ RuntimeCapabilityTEERakQuoteResponse {
+ height: u64,
+ signature: Signature,
+ },
+ RuntimeCapabilityTEEUpdateEndorsementRequest {
+ ect: EndorsedCapabilityTEE,
+ },
+ RuntimeCapabilityTEEUpdateEndorsementResponse {},
+ RuntimeRPCCallRequest {
+ request: Vec<u8>,
+ kind: Kind,
+ peer_id: Vec<u8>,
+ },
+ RuntimeRPCCallResponse {
+ response: Vec<u8>,
+ },
+ RuntimeLocalRPCCallRequest {
+ request: Vec<u8>,
+ },
+ RuntimeLocalRPCCallResponse {
+ response: Vec<u8>,
+ },
+ RuntimeCheckTxBatchRequest {
+ consensus_block: LightBlock,
+ inputs: TxnBatch,
+ block: Block,
+ epoch: EpochTime,
+ max_messages: u32,
+ },
+ RuntimeCheckTxBatchResponse {
+ results: Vec<CheckTxResult>,
+ },
+ RuntimeExecuteTxBatchRequest {
+ mode: ExecutionMode,
+ consensus_block: LightBlock,
+ round_results: RoundResults,
+ io_root: Hash,
+ inputs: Option<TxnBatch>,
+ in_msgs: Vec<IncomingMessage>,
+ block: Block,
+ epoch: EpochTime,
+ max_messages: u32,
+ },
+ RuntimeExecuteTxBatchResponse {
+ batch: ComputedBatch,
+ tx_hashes: Vec<Hash>,
+ tx_reject_hashes: Vec<Hash>,
+ tx_input_root: Hash,
+ tx_input_write_log: WriteLog,
+ },
+ RuntimeKeyManagerStatusUpdateRequest {
+ status: Status,
+ },
+ RuntimeKeyManagerStatusUpdateResponse {},
+ RuntimeKeyManagerQuotePolicyUpdateRequest {
+ policy: QuotePolicy,
+ },
+ RuntimeKeyManagerQuotePolicyUpdateResponse {},
+ RuntimeQueryRequest {
+ consensus_block: LightBlock,
+ header: Header,
+ epoch: EpochTime,
+ max_messages: u32,
+ method: String,
+ args: Vec<u8>,
+ },
+ RuntimeQueryResponse {
+ data: Vec<u8>,
+ },
+ RuntimeConsensusSyncRequest {
+ height: u64,
+ },
+ RuntimeConsensusSyncResponse {},
+ RuntimeNotifyRequest {
+ runtime_block: Option<AnnotatedBlock>,
+ runtime_event: Option<RuntimeNotifyEvent>,
+ },
+ RuntimeNotifyResponse {},
+ HostRPCCallRequest {
+ endpoint: String,
+ request_id: u64,
+ request: Vec<u8>,
+ kind: Kind,
+ nodes: Vec<PublicKey>,
+ },
+ HostRPCCallResponse {
+ response: Vec<u8>,
+ node: PublicKey,
+ },
+ HostSubmitPeerFeedbackRequest {
+ endpoint: String,
+ request_id: u64,
+ peer_feedback: PeerFeedback,
+ },
+ HostSubmitPeerFeedbackResponse {},
+ HostStorageSyncRequest(StorageSyncRequestWithEndpoint),
+ HostStorageSyncResponse(StorageSyncResponse),
+ HostLocalStorageGetRequest {
+ key: Vec<u8>,
+ },
+ HostLocalStorageGetResponse {
+ value: Vec<u8>,
+ },
+ HostLocalStorageSetRequest {
+ key: Vec<u8>,
+ value: Vec<u8>,
+ },
+ HostLocalStorageSetResponse {},
+ HostFetchConsensusBlockRequest {
+ height: u64,
+ },
+ HostFetchConsensusBlockResponse {
+ block: LightBlock,
+ },
+ HostFetchConsensusEventsRequest(HostFetchConsensusEventsRequest),
+ HostFetchConsensusEventsResponse(HostFetchConsensusEventsResponse),
+ HostFetchTxBatchRequest {
+ offset: Option<Hash>,
+ limit: u32,
+ },
+ HostFetchTxBatchResponse {
+ batch: Option<TxnBatch>,
+ },
+ HostFetchBlockMetadataTxRequest {
+ height: u64,
+ },
+ HostFetchBlockMetadataTxResponse {
+ signed_tx: SignedTransaction,
+ proof: Proof,
+ },
+ HostFetchGenesisHeightRequest {},
+ HostFetchGenesisHeightResponse {
+ height: u64,
+ },
+ HostProveFreshnessRequest {
+ blob: Vec<u8>,
+ },
+ HostProveFreshnessResponse {
+ signed_tx: SignedTransaction,
+ proof: Proof,
+ },
+ HostIdentityRequest {},
+ HostIdentityResponse {
+ node_id: PublicKey,
+ },
+ HostSubmitTxRequest {
+ runtime_id: Namespace,
+ data: Vec<u8>,
+ wait: bool,
+ prove: bool,
+ },
+ HostSubmitTxResponse {
+ output: Vec<u8>,
+ round: u64,
+ batch_order: u32,
+ proof: Option<Proof>,
+ },
+ HostRegisterNotifyRequest {
+ runtime_block: bool,
+ runtime_event: Option<RegisterNotifyRuntimeEvent>,
+ },
+ HostRegisterNotifyResponse {},
+}Runtime host protocol message body.
+results: Vec<CheckTxResult>mode: ExecutionModeconsensus_block: LightBlockround_results: RoundResultsin_msgs: Vec<IncomingMessage>batch: ComputedBatchpolicy: QuotePolicyconsensus_block: LightBlockblock: LightBlocktry_default in case the value is null or
+undefined.#[repr(u8)]pub enum EventKind {
+ Staking = 1,
+ Registry = 2,
+ RootHash = 3,
+ Governance = 4,
+}Consensus event kind.
+try_default in case the value is null or
+undefined.clone_to_uninit)clone_to_uninit)pub enum ExecutionMode {
+ Execute = 0,
+ Schedule = 1,
+}Batch execution mode.
+Execution mode where the batch of transactions is executed as-is without the ability to +perform and modifications to the batch.
+Execution mode where the runtime is in control of scheduling and may arbitrarily modify the +batch during execution.
+This execution mode will only be used in case the runtime advertises to support the schedule +control feature. In this case the call will only contain up to InitialBatchSize transactions +and the runtime will need to request more if it needs more.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.#[repr(u8)]pub enum HostStorageEndpoint {
+ Runtime = 0,
+ Consensus = 1,
+}Host storage endpoint.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)clone_to_uninit)key and return true if they are equal.#[repr(u8)]pub enum MessageType {
+ Invalid = 0,
+ Request = 1,
+ Response = 2,
+}Invalid message (should never be seen on the wire).
+Request.
+Response.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)clone_to_uninit)pub enum StorageSyncRequest {
+ SyncGet(GetRequest),
+ SyncGetPrefixes(GetPrefixesRequest),
+ SyncIterate(IterateRequest),
+}Storage sync request.
+try_default in case the value is null or
+undefined.pub enum StorageSyncResponse {
+ ProofResponse(ProofResponse),
+}Storage sync response.
+try_default in case the value is null or
+undefined.Types used by the worker-host protocol.
+pub struct CheckTxMetadata {
+ pub priority: u64,
+ pub sender: Vec<u8>,
+ pub sender_seq: u64,
+ pub sender_state_seq: u64,
+}CheckTx transaction metadata.
+priority: u64§sender: Vec<u8>§sender_seq: u64§sender_state_seq: u64source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct CheckTxResult {
+ pub error: Error,
+ pub meta: Option<CheckTxMetadata>,
+}Result of a CheckTx operation.
+error: Error§meta: Option<CheckTxMetadata>source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct ComputedBatch {
+ pub header: ComputeResultsHeader,
+ pub io_write_log: WriteLog,
+ pub state_write_log: WriteLog,
+ pub rak_sig: Signature,
+ pub messages: Vec<Message>,
+}Computed batch.
+header: ComputeResultsHeaderCompute results header.
+io_write_log: WriteLogLog that generates the I/O tree.
+state_write_log: WriteLogLog of changes to the state tree.
+rak_sig: SignatureIf this runtime uses a TEE, then this is the signature of the batch’s +BatchSigMessage with the node’s RAK for this runtime.
+messages: Vec<Message>Messages emitted by the runtime.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Error {
+ pub module: String,
+ pub code: u32,
+ pub message: String,
+}A serializable error.
+module: String§code: u32§message: Stringtry_default in case the value is null or
+undefined.clone_to_uninit)pub struct FeatureScheduleControl {
+ pub initial_batch_size: u32,
+}A feature specifying that the runtime supports controlling the scheduling of batches. This means +that the scheduler should only take priority into account and ignore weights, leaving it up to +the runtime to decide which transactions to include.
+initial_batch_size: u32Size of the initial batch of transactions.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Features {
+ pub schedule_control: Option<FeatureScheduleControl>,
+ pub key_manager_quote_policy_updates: bool,
+ pub key_manager_status_updates: bool,
+ pub endorsed_capability_tee: bool,
+}Set of supported runtime features.
+schedule_control: Option<FeatureScheduleControl>Schedule control feature.
+key_manager_quote_policy_updates: boolA feature specifying that the runtime supports updating key manager’s quote policy.
+key_manager_status_updates: boolA feature specifying that the runtime supports updating key manager’s status.
+endorsed_capability_tee: boolA feature specifying that the runtime supports endorsed TEE capabilities.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct HostFetchConsensusEventsRequest {
+ pub height: u64,
+ pub kind: EventKind,
+}Request to host to fetch the consensus events for the given height.
+height: u64§kind: EventKindsource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct HostFetchConsensusEventsResponse {
+ pub events: Vec<Event>,
+}Response from host fetching the consensus events for the given height.
+events: Vec<Event>source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Message {
+ pub id: u64,
+ pub message_type: MessageType,
+ pub body: Body,
+}Runtime protocol message.
+id: u64Unique request identifier.
+message_type: MessageTypeMessage type.
+body: BodyMessage body.
+try_default in case the value is null or
+undefined.pub struct RegisterNotifyRuntimeEvent {
+ pub tags: Vec<Vec<u8>>,
+}Registration for runtime event notifications.
+Event tags to subscribe to.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct RuntimeInfoRequest {
+ pub runtime_id: Namespace,
+ pub consensus_backend: String,
+ pub consensus_protocol_version: Version,
+ pub consensus_chain_context: String,
+ pub local_config: BTreeMap<String, Value>,
+}Runtime information request.
+runtime_id: Namespace§consensus_backend: String§consensus_protocol_version: Version§consensus_chain_context: String§local_config: BTreeMap<String, Value>source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct RuntimeInfoResponse {
+ pub protocol_version: Version,
+ pub runtime_version: Version,
+ pub features: Features,
+}Runtime information response.
+protocol_version: VersionThe runtime protocol version supported by the runtime.
+runtime_version: VersionThe version of the runtime.
+features: FeaturesDescribes the features supported by the runtime.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct RuntimeNotifyEvent {
+ pub block: AnnotatedBlock,
+ pub tags: Vec<Vec<u8>>,
+}An event notification.
+block: AnnotatedBlockHeader of the block that emitted the event.
+Matching tags.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct StorageSyncRequestWithEndpoint {
+ pub endpoint: HostStorageEndpoint,
+ pub request: StorageSyncRequest,
+}endpoint: HostStorageEndpoint§request: StorageSyncRequesttry_default in case the value is null or
+undefined.#[handler]A helper attribute for #[sdk_derive(...)]. It doesn’t do anyting on its own;
+it only marks functions that represent a paratime method handler.
+The permitted forms are:
#[handler(call = "my_module.MyCall")]: Marks a function that handles
+the “my_module.MyCall” call and can be passed to
+oasis_runtime_sdk::module::dispatch_call.#[handler(prefetch = "my_module.MyCall")]: Marks a function that handles
+the request to prefetch any data ahead of the “my_module.MyCall” call.
+Its signature should be Fn( add_prefix: &mut dyn FnMut(Prefix) -> (), body: cbor::Value, auth_info: &AuthInfo, ) -> Result<(), oasis_runtime_sdk::error::RuntimeError>#[handler(query = "my_module.MyQuery")]: Marks a function that handles
+the “my_module.MyQuery” query and can be passed to
+oasis_runtime_sdk::module::dispatch_query.#[handler(message_result = "my_module.MyMR")]: Marks a function that handles
+the “my_module.MyMR” message result and can be passed to
+oasis_runtime_sdk::module::dispatch_message_result.Query handler can also contain the expensive tag. Example:
+#[handler(query = "my_module.MyQuery", expensive)].
+Queries tagged expensive can be enabled/disabled are disabled by default to avoid
+excessive costs to the node operator. This can be overridden in the node config.
NOTE: This attribute is parsed by the #[sdk_derive(...)] macro, which cannot
+interpret the attribute name semantically. Use #[handler], not
+#[oasis_runtime_sdk_macros::handler] or other paths/aliases.
#[migration]A helper attribute for #[sdk_derive(...)]. It doesn’t do anything on its own;
+it only marks functions that represent a module state migration.
The permitted forms are:
+#[migration(init)]: Marks the initial (genesis) migration.#[migration(from = v)]: Marks a migration from version v to v+1, where v is
+a non-negative integer.#[sdk_derive]Derives traits from a non-trait impl block (rather than from a struct).
Only the Module trait is supported. In other words, given an impl MyModule block, the macro
+derives implementations needed for implementing a module.
+See also the #[handler] and #[migration] attributes.
pub enum Metadata {
+ Empty,
+ EncryptedX25519DeoxysII {
+ pk: PublicKey,
+ sk: PrivateKey,
+ index: usize,
+ },
+}Additional metadata required by the result encoding function.
+pub fn decode_call<C: Context>(
+ ctx: &C,
+ call: Call,
+ index: usize,
+) -> Result<Option<(Call, Metadata)>, Error>Decode call arguments.
+Returns Some((Call, Metadata)) when processing should proceed and None in case further
+execution needs to be deferred (e.g., because key manager access is required).
pub fn decode_call_ex<C: Context>(
+ ctx: &C,
+ call: Call,
+ index: usize,
+ assume_km_reachable: bool,
+) -> Result<Option<(Call, Metadata)>, Error>Decode call arguments.
+Returns Some((Call, Metadata)) when processing should proceed and None in case further
+execution needs to be deferred (e.g., because key manager access is required).
+If assume_km_reachable is set, then this method will return errors instead of None.
pub fn encode_result<C: Context>(
+ ctx: &C,
+ result: CallResult,
+ metadata: Metadata,
+) -> CallResultEncode call results.
+pub fn encode_result_ex<C: Context>(
+ ctx: &C,
+ result: CallResult,
+ metadata: Metadata,
+ expose_failure: bool,
+) -> CallResultEncode call results.
+If expose_failure is set, then this method will not encrypt errors.
pub fn encrypt_result_x25519_deoxysii<C: Context>(
+ ctx: &C,
+ result: CallResult,
+ pk: PublicKey,
+ sk: PrivateKey,
+ index: usize,
+) -> ValueEncrypt a call result using the X25519-Deoxys-II encryption scheme.
+pub fn get_key_pair_id(epoch: EpochTime) -> KeyPairIdDerive the key pair ID for the call data encryption key pair.
+Handling of different call formats.
+Configuration types.
+pub struct ScheduleControl {
+ pub initial_batch_size: u32,
+ pub batch_size: u32,
+ pub min_remaining_gas: u64,
+ pub max_tx_count: usize,
+}Runtime schedule control configuration.
+initial_batch_size: u32Size of the initial batch that the node should provide to the runtime.
+batch_size: u32Size of each extra batch that the runtime should fetch.
+min_remaining_gas: u64Minimum amount of gas that needs to be remaining in a batch in order to still consider +including new transactions.
+max_tx_count: usizeMaximum number of transactions that can go in a batch.
+This is only used as a last resort to avoid the batch going over the runtime’s limit.
+Execution context.
+pub struct RuntimeBatchContext<'a, R: Runtime> { /* private fields */ }Dispatch context for the whole batch.
+Create a new dispatch context.
+method is an allowed query per policy in the local config.pub trait Context {
+ type Runtime: Runtime;
+
+Show 15 methods
// Required methods
+ fn clone(&self) -> Self;
+ fn get_logger(&self, module: &'static str) -> Logger;
+ fn host_info(&self) -> &HostInfo;
+ fn key_manager(&self) -> Option<&dyn KeyManager>;
+ fn runtime_header(&self) -> &Header;
+ fn runtime_round_results(&self) -> &RoundResults;
+ fn consensus_state(&self) -> &ConsensusState;
+ fn history(&self) -> &dyn HistoryHost;
+ fn epoch(&self) -> EpochTime;
+ fn max_messages(&self) -> u32;
+
+ // Provided methods
+ fn should_execute_contracts(&self) -> bool { ... }
+ fn is_allowed_query<R: Runtime>(&self, method: &str) -> bool { ... }
+ fn local_config<T>(&self, key: &str) -> Option<T>
+ where T: Decode { ... }
+ fn runtime_id(&self) -> &Namespace { ... }
+ fn is_confidential(&self) -> bool { ... }
+}Runtime SDK context.
+Returns a logger.
+The key manager, if the runtime is confidential.
+Last runtime block header.
+Results of executing the last successful runtime round.
+Consensus state.
+Historical state.
+Maximum number of consensus messages that the runtime can emit in this block.
+Whether smart contracts should be executed in this context.
+Whether method is an allowed query per policy in the local config.
Returns node operator-provided local configuration.
+This method will always return None in Mode::ExecuteTx contexts.
Runtime ID.
+Whether the context has a key manager available (e.g. the runtime is confidential).
+pub enum Error {
+ InvalidConfig,
+ InvalidSignatureSet,
+ InsufficientWeight,
+}Error.
+signers vec.SignatureSet owned in a Vec.pub struct Config {
+ pub signers: Vec<Signer>,
+ pub threshold: u64,
+}A multisig configuration. +A set of signers with total “weight” greater than or equal to a “threshold” can authenticate +for the configuration.
+signers: Vec<Signer>The signers.
+threshold: u64The threshold.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct Signer {
+ pub public_key: PublicKey,
+ pub weight: u64,
+}One of the signers in a multisig configuration.
+public_key: PublicKeyThe public key of the signer.
+weight: u64The weight of the signer.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub type SignatureSet = [Option<Signature>];A set of signatures corresponding to a multisig configuration.
+The indices match the configuration’s signers vec.
pub type SignatureSetOwned = Vec<Option<Signature>>;A SignatureSet owned in a Vec.
struct SignatureSetOwned { /* private fields */ }pub struct LeafRng(/* private fields */);A leaf RNG.
+dest with random data. Read moreRngCore trait object.BigUint of the given bit size.BigUint less than the given bound. Fails
+when the bound is zero.p of being true. Read morenumerator/denominator of being
+true. I.e. gen_ratio(2, 3) has chance of 2 in 3, or about 67%, of
+returning true. If numerator == denominator, then the returned value
+is guaranteed to be true. If numerator == 0, then the returned
+value is guaranteed to be false. Read morepub struct RootRng { /* private fields */ }A root RNG that can be used to derive domain-separated leaf RNGs.
+Create an invalid root RNG which will fail when any leaf RNGs are requested.
+Append local entropy to the root RNG.
+Using this method will result in the RNG being non-deterministic.
+Append an observed transaction hash to RNG transcript.
+Append an observed subcontext to RNG transcript.
+pub fn get_chain_context_for(base: &[u8]) -> Vec<u8> ⓘReturn the globally configured chain domain separation context.
+The returned domain separation context is computed as:
+<base> || " for chain " || <chain-context>
+This function will panic in case the global chain domain separation context was not previously
+set using set_chain_context.
pub fn set_chain_context(runtime_id: Namespace, consensus_chain_context: &str)Configure the global chain domain separation context.
+The domain separation context is computed as:
+Base-16(H(<runtime-id> || <consensus-chain-context>))
+This function will panic in case the global chain domain separation context was already set.
+pub struct MemorySigner { /* private fields */ }A memory-backed signer for Ed25519.
+pub struct PublicKey(/* private fields */);An Ed25519 public key.
+Construct a public key from a slice of bytes.
+Verify a signature.
+try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.pub enum Error {
+ MalformedPublicKey,
+ MalformedPrivateKey,
+ MalformedSignature,
+ VerificationFailed,
+ InvalidArgument,
+ InvalidDigestLength,
+ SigningError,
+}Error.
+pub enum MemorySigner {
+ Ed25519(MemorySigner),
+ Secp256k1(MemorySigner),
+ Secp256r1(MemorySigner),
+ Secp384r1(MemorySigner),
+}A memory-backed signer.
+Create a new memory signer from a seed.
+Create a new signer for testing purposes.
+Reconstruct the signer from its byte representation.
+Public key corresponding to the signer.
+Generate a signature with the private key over the context and message.
+Generate a signature with the private key over the message.
+Generate a signature for the specified message and optional context.
+pub enum PublicKey {
+ Ed25519(PublicKey),
+ Secp256k1(PublicKey),
+ Secp256r1(PublicKey),
+ Secp384r1(PublicKey),
+ Sr25519(PublicKey),
+}A public key used for signing.
+Construct a public key from a slice of bytes.
+Verify a signature.
+Verify signature raw using the underlying method, without the domain +separation schema.
+Verify the signature of a message.
+try_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub enum SignatureType {
+ Ed25519_Oasis,
+ Ed25519_Pure,
+ Ed25519_PrehashedSha512,
+ Secp256k1_Oasis,
+ Secp256k1_PrehashedKeccak256,
+ Secp256k1_PrehashedSha256,
+ Sr25519,
+ Secp256r1_PrehashedSha256,
+ Secp384r1_PrehashedSha384,
+}A specific combination of signature and hash.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)clone_to_uninit)key and return true if they are equal.Cryptographic signatures.
+pub struct MemorySigner { /* private fields */ }A memory-backed signer for Secp256k1.
+pub struct PublicKey(/* private fields */);A Secp256k1 public key (in compressed form).
+Return an alternative byte representation used in deriving Ethereum-compatible addresses.
+Derive an Ethereum-compatible address.
+Construct a public key from a slice of bytes.
+Verify a signature.
+try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.pub struct MemorySigner { /* private fields */ }A memory-backed signer for Secp256r1.
+pub struct PublicKey(/* private fields */);A Secp256r1 public key (in compressed form).
+Construct a public key from a slice of bytes.
+Verify a signature.
+try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.pub struct MemorySigner { /* private fields */ }A memory-backed signer for Secp384r1.
+pub struct PublicKey(/* private fields */);A Secp384r1 public key (in compressed form).
+Construct a public key from a slice of bytes.
+Verify a signature.
+try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.pub struct PublicKey(/* private fields */);A Sr25519 public key.
+try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.pub struct Signature(/* private fields */);Variable-length opaque signature.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub trait Signer: Send + Sync {
+ // Required methods
+ fn random(rng: &mut impl RngCore) -> Result<Self, Error>
+ where Self: Sized;
+ fn new_from_seed(seed: &[u8]) -> Result<Self, Error>
+ where Self: Sized;
+ fn from_bytes(bytes: &[u8]) -> Result<Self, Error>
+ where Self: Sized;
+ fn to_bytes(&self) -> Vec<u8> ⓘ;
+ fn public_key(&self) -> PublicKey;
+ fn sign(&self, context: &[u8], message: &[u8]) -> Result<Signature, Error>;
+ fn sign_raw(&self, message: &[u8]) -> Result<Signature, Error>;
+}Common trait for memory signers.
+Create a new random signer.
+Create a new signer from the given seed.
+Recreate signer from a byte serialization.
+Return the public key counterpart to the signer’s secret key.
+#[derive(Error)]
+{
+ // Attributes available to this derive:
+ #[sdk_error]
+ #[source]
+ #[from]
+}
+Derives the Error trait on an enum.
#[derive(Event)]
+{
+ // Attributes available to this derive:
+ #[sdk_event]
+}
+Derives the Event trait on an enum.
pub enum Error {
+ Aborted,
+ MalformedTransactionInBatch(Error),
+ QueryAborted(String),
+ KeyManagerFailure(KeyManagerError),
+ BatchOutOfGas,
+}Error emitted by the dispatch process. Note that this indicates an error in the dispatch +process itself and should not be used for any transaction-related errors.
+Ok(err) (where err is a dispatcher error) when batch
+should abort or Err(self) when this is just a regular error.Transaction dispatcher.
+pub struct DispatchOptions<'a> {
+ pub tx_size: u32,
+ pub tx_index: usize,
+ pub tx_hash: Hash,
+ pub method_authorizer: Option<&'a dyn Fn(&str) -> bool>,
+ pub skip_authentication: bool,
+}Additional options for dispatch operations.
+tx_size: u32Transaction size.
+tx_index: usizeTransaction index within the batch.
+tx_hash: HashTransaction hash.
+Optionally only allow methods for which the provided authorizer closure returns true.
+skip_authentication: boolOptionally skip authentication.
+pub struct DispatchResult {
+ pub result: CallResult,
+ pub tags: Tags,
+ pub priority: u64,
+ pub sender_metadata: SenderMeta,
+ pub call_format_metadata: Metadata,
+}Result of dispatching a transaction.
+result: CallResultTransaction call result.
+Transaction tags.
+priority: u64Transaction priority.
+sender_metadata: SenderMetaTransaction sender metadata.
+call_format_metadata: MetadataCall format metadata.
+pub struct Dispatcher<R: Runtime> { /* private fields */ }The runtime dispatcher.
+Decode a runtime transaction.
+Run the dispatch steps inside a transaction context. This includes the before call hooks, +the call itself and after call hooks. The after call hooks are called regardless if the call +succeeds or not.
+Dispatch a runtime transaction in the given context with the provided options.
+Dispatch a runtime transaction in the given context.
+Check whether the given transaction is valid.
+Execute the given transaction, returning unserialized results.
+Execute the given transaction.
+Prefetch prefixes for the given transaction.
+Process the given runtime query.
+Register EnclaveRPC methods.
+pub const METHOD_QUERY: &str = "runtime-sdk/query";Name of the query method.
Exposed EnclaveRPC methods.
+query method.query method.pub struct QueryRequest {
+ pub round: u64,
+ pub method: String,
+ pub args: Vec<u8>,
+}Arguments for the query method.
round: u64§method: String§args: Vec<u8>source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)Error types for runtimes.
+pub struct RuntimeError {
+ pub module: String,
+ pub code: u32,
+ pub message: String,
+}A serializable error.
+module: String§code: u32§message: Stringtry_default in case the value is null or
+undefined.clone_to_uninit)pub trait Error: Error {
+ // Required methods
+ fn module_name(&self) -> &str;
+ fn code(&self) -> u32;
+
+ // Provided methods
+ fn into_call_result(self) -> CallResult
+ where Self: Sized { ... }
+ fn into_abort(self) -> Result<Error, Self>
+ where Self: Sized { ... }
+}A runtime error that gets propagated to the caller.
+It extends std::error::Error with module name and error code so that errors can be easily
+serialized and transferred between different processes.
This trait can be derived:
+ +const MODULE_NAME: &str = "my-module";
+#[derive(Clone, Debug, Error, thiserror::Error)]
+#[sdk_error(autonumber)] // `module_name` meta is required if `MODULE_NAME` isn't in scope
+enum Error {
+ #[error("invalid argument")]
+ InvalidArgument, // autonumbered to 0
+
+ #[error("forbidden")]
+ #[sdk_error(code = 401)] // manually numbered to 403 (`code` or autonumbering is required)
+ Forbidden,
+}Name of the module that emitted the error.
+Converts the error into a call result.
+Consumes self and returns either Ok(err) (where err is a dispatcher error) when batch
+should abort or Err(self) when this is just a regular error.
pub fn etag_for_event(module_name: &str, code: u32, value: Value) -> EventTagGenerate an EventTag corresponding to the passed event triple.
+Event types for runtimes.
+pub struct EventTag {
+ pub key: Vec<u8>,
+ pub value: Value,
+}A key-value pair representing an emitted event that will be emitted as a tag.
+key: Vec<u8>§value: Valueclone_to_uninit)pub trait Event: Sized + Encode {
+ // Required methods
+ fn module_name() -> &'static str;
+ fn code(&self) -> u32;
+
+ // Provided method
+ fn into_event_tag(self) -> EventTag { ... }
+}An event emitted by the runtime.
+This trait can be derived:
+ +const MODULE_NAME: &str = "my-module";
+#[derive(Clone, Debug, cbor::Encode, Event)]
+#[cbor(untagged)]
+#[sdk_event(autonumber)] // `module_name` meta is required if `MODULE_NAME` isn't in scope
+enum MyEvent {
+ Greeting(String), // autonumbered to 0
+ #[sdk_event(code = 2)] // manually numbered to 2 (`code` is required if not autonumbering)
+ DontPanic,
+ Salutation { // autonumbered to 1
+ plural: bool,
+ }
+}Name of the module that emitted the event.
+pub enum Error {
+ FailedToFetchBlock,
+ FailedToFetchEvents,
+}History host errors.
+Ok(err) (where err is a dispatcher error) when batch
+should abort or Err(self) when this is just a regular error.Historic state access.
+pub trait HistoryHost {
+ // Required methods
+ fn consensus_state_at(&self, height: u64) -> Result<ConsensusState, Error>;
+ fn consensus_events_at(
+ &self,
+ height: u64,
+ kind: EventKind,
+ ) -> Result<Vec<Event>, Error>;
+}Interface to the runtime host to fetch historic information.
+Fetch historic consensus state after executing the block at given height.
+Oasis runtime SDK.
+pub use crate::context::Context;pub use crate::module::Module;pub use crate::runtime::Runtime;pub use crate::state::CurrentState;pub use oasis_core_runtime as core;pub use cbor;oasis_sdk::core::common::version::Version from the Cargo.toml version.#[sdk_derive(...)]. It doesn’t do anyting on its own;
+it only marks functions that represent a paratime method handler.
+The permitted forms are:#[sdk_derive(...)]. It doesn’t do anything on its own;
+it only marks functions that represent a module state migration.impl block (rather than from a struct).Error trait on an enum.Event trait on an enum.pub const KEY_PAIR_ID_CONTEXT: &[u8] = b"oasis-runtime-sdk/keymanager: key pair id";Key pair ID domain separation context.
+pub enum KeyManagerError {
+Show 33 variants
NotAuthenticated,
+ NotAuthorized,
+ InvalidEpoch(u64, u64),
+ InvalidGeneration(u64, u64),
+ GenerationFromFuture(u64, u64),
+ HeightNotFresh,
+ NotInitialized,
+ StateCorrupted,
+ StorageCorrupted,
+ PolicyRequired,
+ PolicyRollback,
+ PolicyChanged,
+ PolicyInvalidRuntime,
+ InsufficientKeyShares,
+ InsufficientSignatures,
+ RSKMissing,
+ REKNotPublished,
+ InvalidSignature(Error),
+ MasterSecretChecksumMismatch,
+ MasterSecretNotFound(u64),
+ MasterSecretNotReplicated(u64),
+ MasterSecretNotPublished,
+ EphemeralSecretNotFound(u64),
+ EphemeralSecretNotReplicated(u64),
+ EphemeralSecretNotPublished,
+ EphemeralSecretChecksumMismatch,
+ InvalidCiphertext,
+ StatusNotFound,
+ RuntimeMismatch,
+ ActiveDeploymentNotFound,
+ StateError(StateError),
+ VerificationError(Error),
+ Other(Error),
+}Key manager error.
+pub fn get_key_pair_id<'a, C>(context: C) -> KeyPairIdwhere
+ C: IntoIterator<Item = &'a [u8]> + 'a,Derive a KeyPairId for use with the key manager functions.
Keymanager interface.
+KeyPairId for use with the key manager functions.pub struct KeyManagerClientWithContext { /* private fields */ }Convenience wrapper around an existing KeyManagerClient instance which uses +a default io context for all calls.
+source. Read moreNone in case the
+identifier is not known yet (e.g. the client has not yet been initialized). Read moreclone_to_uninit)pub struct KeyPair {
+ pub input_keypair: InputKeyPair,
+ pub state_key: StateKey,
+ pub checksum: Vec<u8>,
+}A key pair managed by the key manager.
+input_keypair: InputKeyPairInput key pair (pk, sk)
+state_key: StateKeyState encryption key
+checksum: Vec<u8>Checksum of the key manager state.
+Generate a new random key (for testing).
+Create a KeyPair.
Create a KeyPair with only the public key.
try_default in case the value is null or
+undefined.clone_to_uninit)pub struct KeyPairId(pub [u8; 32]);A 256-bit key pair identifier.
+0: [u8; 32]try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)clone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub struct SignedPublicKey {
+ pub key: PublicKey,
+ pub checksum: Vec<u8>,
+ pub signature: Signature,
+ pub expiration: Option<u64>,
+}Signed public key.
+key: PublicKeyPublic key.
+checksum: Vec<u8>Checksum of the key manager state.
+signature: SignatureSign(sk, (key || checksum || runtime id || key pair id || epoch || expiration epoch)) from +the key manager.
+expiration: Option<u64>Expiration epoch.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct StateKey(pub [u8; 32]);A state encryption key.
+0: [u8; 32]try_default in case the value is null or
+undefined.clone_to_uninit)self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub struct TrustedSigners {
+ pub signers: HashSet<PublicKey>,
+ pub threshold: u64,
+}Set of trusted key manager signing keys.
+signers: HashSet<PublicKey>Set of trusted signers.
+threshold: u64Threshold for determining if enough valid signatures are present.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub trait KeyManager {
+ // Required methods
+ fn runtime_id(&self) -> Option<Namespace>;
+ fn runtime_signing_key(&self) -> Option<PublicKey>;
+ fn clear_cache(&self);
+ fn get_or_create_keys(
+ &self,
+ key_pair_id: KeyPairId,
+ ) -> Result<KeyPair, KeyManagerError>;
+ fn get_public_key(
+ &self,
+ key_pair_id: KeyPairId,
+ ) -> Result<SignedPublicKey, KeyManagerError>;
+ fn get_or_create_ephemeral_keys(
+ &self,
+ key_pair_id: KeyPairId,
+ epoch: EpochTime,
+ ) -> Result<KeyPair, KeyManagerError>;
+ fn get_public_ephemeral_key(
+ &self,
+ key_pair_id: KeyPairId,
+ epoch: EpochTime,
+ ) -> Result<SignedPublicKey, KeyManagerError>;
+ fn box_clone(&self) -> Box<dyn KeyManager>;
+}Key manager interface.
+Key manager runtime identifier this client is connected to. It may be None in case the
+identifier is not known yet (e.g. the client has not yet been initialized).
See the oasis-core documentation for details.
+Key manager runtime signing key used to sign messages from the key manager.
+See the oasis-core documentation for details.
+Clear local key cache.
+See the oasis-core documentation for details.
+Get or create named key pair.
+See the oasis-core documentation for details. This variant of the method +synchronously blocks for the result.
+Get public key for a key pair id.
+See the oasis-core documentation for details. This variant of the method +synchronously blocks for the result.
+Get or create named ephemeral key pair for given epoch.
+See the oasis-core documentation for details. This variant of the method +synchronously blocks for the result.
+Get ephemeral public key for an epoch and a key pair id.
+See the oasis-core documentation for details. This variant of the method +synchronously blocks for the result.
+Redirecting to macro.version_from_cargo.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_runtime_sdk/macro.version_from_cargo.html b/rust/oasis_runtime_sdk/macro.version_from_cargo.html new file mode 100644 index 0000000000..40d6dff71f --- /dev/null +++ b/rust/oasis_runtime_sdk/macro.version_from_cargo.html @@ -0,0 +1,2 @@ +version_from_cargo!() { /* proc-macro */ }Constructs an oasis_sdk::core::common::version::Version from the Cargo.toml version.
pub enum AuthDecision {
+ Continue,
+ Stop,
+}An authentication decision for cases where multiple handlers are available.
+Authentication passed, continue with the next authentication handler.
+Authentication passed, no further authentication handlers should be called.
+source. Read moreclone_to_uninit)pub enum CallResult {
+ Ok(Value),
+ Failed {
+ module: String,
+ code: u32,
+ message: String,
+ },
+ Aborted(Error),
+}A variant of types::transaction::CallResult but used for dispatch purposes so the dispatch
+process can use a different representation.
Specifically, this type is not serializable.
+Call has completed successfully.
+Call has completed with failure.
+A fatal error has occurred and the batch must be aborted.
+Check whether the call result indicates a successful operation or not.
+pub enum DispatchResult<B, R> {
+ Handled(R),
+ Unhandled(B),
+}Result of invoking the method handler.
+Transforms DispatchResult<B, R> into Result<R, E>, mapping Handled(r) to Ok(r) and
+Unhandled(_) to Err(err).
Transforms DispatchResult<B, R> into Result<R, E>, mapping Handled(r) to Ok(r) and
+Unhandled(_) to Err(err) using the provided function.
pub fn dispatch_call<C, B, R, E, F>(
+ ctx: &C,
+ body: Value,
+ f: F,
+) -> DispatchResult<Value, CallResult>A convenience function for dispatching method calls.
+pub fn dispatch_query<C, B, R, E, F>(
+ ctx: &C,
+ body: Value,
+ f: F,
+) -> DispatchResult<Value, Result<Value, RuntimeError>>A convenience function for dispatching queries.
+Runtime modules.
+types::transaction::CallResult but used for dispatch purposes so the dispatch
+process can use a different representation.pub trait BlockHandler {
+ // Provided methods
+ fn begin_block<C: Context>(_ctx: &C) { ... }
+ fn end_block<C: Context>(_ctx: &C) { ... }
+}Block handler.
+Perform any common actions at the start of the block (before any transactions have been +executed).
+pub trait FeeProxyHandler {
+ // Required method
+ fn resolve_payer<C: Context>(
+ ctx: &C,
+ tx: &Transaction,
+ ) -> Result<Option<Address>, Error>;
+}Fee proxy handler.
+Resolve the proxy payer for the given transaction. If no payer could be resolved, None
+should be returned.
pub trait InvariantHandler {
+ // Provided method
+ fn check_invariants<C: Context>(_ctx: &C) -> Result<(), Error> { ... }
+}Invariant handler.
+pub trait MethodHandler {
+ // Provided methods
+ fn prefetch(
+ _prefixes: &mut BTreeSet<Prefix>,
+ _method: &str,
+ body: Value,
+ _auth_info: &AuthInfo,
+ ) -> DispatchResult<Value, Result<(), RuntimeError>> { ... }
+ fn dispatch_call<C: Context>(
+ _ctx: &C,
+ _method: &str,
+ body: Value,
+ ) -> DispatchResult<Value, CallResult> { ... }
+ fn dispatch_query<C: Context>(
+ _ctx: &C,
+ _method: &str,
+ args: Value,
+ ) -> DispatchResult<Value, Result<Value, RuntimeError>> { ... }
+ fn dispatch_message_result<C: Context>(
+ _ctx: &C,
+ _handler_name: &str,
+ result: MessageResult,
+ ) -> DispatchResult<MessageResult, ()> { ... }
+ fn supported_methods() -> Vec<MethodHandlerInfo> { ... }
+ fn is_expensive_query(_method: &str) -> bool { ... }
+ fn is_allowed_private_km_query(_method: &str) -> bool { ... }
+ fn is_allowed_interactive_call(_method: &str) -> bool { ... }
+}Method handler.
+Add storage prefixes to prefetch.
+Dispatch a call.
+Dispatch a query.
+Dispatch a message result.
+Lists the names of all RPC methods exposed by this module. The result is informational +only. An empty return vector means that the implementor does not care to list the methods, +or the implementor is a tuple of modules.
+Checks whether the given query method is tagged as expensive.
+Checks whether the given query is allowed to access private key manager state.
+Checks whether the given call is allowed to be called interactively via read-only +transactions.
+pub trait MigrationHandler {
+ type Genesis;
+
+ // Provided method
+ fn init_or_migrate<C: Context>(
+ _ctx: &C,
+ _meta: &mut Metadata,
+ _genesis: Self::Genesis,
+ ) -> bool { ... }
+}Migration handler.
+pub trait Module {
+ type Error: Error + 'static;
+ type Event: Event + 'static;
+ type Parameters: Parameters + 'static;
+
+ const NAME: &'static str;
+ const VERSION: u32 = 1u32;
+
+ // Provided methods
+ fn params() -> Self::Parameters { ... }
+ fn set_params(params: Self::Parameters) { ... }
+}A runtime module.
+Module parameters.
+Return the module’s parameters.
+Set the module’s parameters.
+pub trait ModuleInfoHandler {
+ // Required method
+ fn module_info<C: Context>(_ctx: &C) -> BTreeMap<String, ModuleInfo>;
+}Info handler.
+Reports info about the module (or modules, if Self is a tuple).
pub trait Parameters: Debug + Default + Encode + Decode {
+ type Error;
+
+ const STORE_KEY: &'static [u8] = _;
+
+ // Provided method
+ fn validate_basic(&self) -> Result<(), Self::Error> { ... }
+}Parameters for a runtime module.
+Perform basic parameter validation.
+pub trait TransactionHandler {
+ // Provided methods
+ fn approve_raw_tx<C: Context>(_ctx: &C, _tx: &[u8]) -> Result<(), Error> { ... }
+ fn approve_unverified_tx<C: Context>(
+ _ctx: &C,
+ _utx: &UnverifiedTransaction,
+ ) -> Result<(), Error> { ... }
+ fn decode_tx<C: Context>(
+ _ctx: &C,
+ _scheme: &str,
+ _body: &[u8],
+ ) -> Result<Option<Transaction>, Error> { ... }
+ fn authenticate_tx<C: Context>(
+ _ctx: &C,
+ _tx: &Transaction,
+ ) -> Result<AuthDecision, Error> { ... }
+ fn before_handle_call<C: Context>(
+ _ctx: &C,
+ _call: &Call,
+ ) -> Result<(), Error> { ... }
+ fn before_authorized_call_dispatch<C: Context>(
+ _ctx: &C,
+ _call: &Call,
+ ) -> Result<(), Error> { ... }
+ fn after_handle_call<C: Context>(
+ _ctx: &C,
+ result: CallResult,
+ ) -> Result<CallResult, Error> { ... }
+ fn after_dispatch_tx<C: Context>(
+ _ctx: &C,
+ _tx_auth_info: &AuthInfo,
+ _result: &CallResult,
+ ) { ... }
+}Transaction handler.
+Judge if a raw transaction is good enough to undergo decoding. +This takes place before even decoding the transaction.
+Judge if an unverified transaction is good enough to undergo verification. +This takes place before even verifying signatures.
+Decode a transaction that was sent with module-controlled decoding and verify any +signatures.
+Postcondition: if returning a Transaction, that transaction must pass validate_basic.
Returns Ok(Some(_)) if the module is in charge of the encoding scheme identified by _scheme +or Ok(None) otherwise.
+Authenticate a transaction.
+Note that any signatures have already been verified.
+Perform any action after authentication, within the transaction context.
+At this point call format has not yet been decoded so peeking into the call may not be +possible in case the call is encrypted.
+Perform any action after authentication and decoding, within the transaction context.
+At this point, the call has been decoded according to the call format, +and method authorizers have run.
+Perform any action after call, within the transaction context.
+If an error is returned the transaction call fails and updates are rolled back.
+Perform any action after dispatching the transaction, in batch context.
+pub enum Error {
+ NotAuthorized,
+}Errors emitted by the access module.
+Ok(err) (where err is a dispatcher error) when batch
+should abort or Err(self) when this is just a regular error.pub struct Module<Cfg: Config> { /* private fields */ }The method access control module.
+Self is a tuple).pub trait Config: 'static {
+ const METHOD_AUTHORIZATIONS: Lazy<Authorization> = _;
+}Module configuration.
+To filter methods by caller address, add them to this mapping.
+If the mapping is empty, no method is filtered.
+pub enum Authorization {
+ FilterOnly(Methods),
+}A specific kind of access control.
+Control a statically configured set of methods, each with a +statically configured set of addresses that are allowed to call it.
+Helper for creating a static access control configuration.
+pub enum MethodAuthorization {
+ AllowFrom(Addresses),
+}A specific kind of method authorization.
+Only allow method calls from these addresses; +for other callers, the method call will fail.
+Helper for creating a method authorization type that +only allows callers with the given addresses.
+Method access control module types.
+pub type Methods = BTreeMap<String, MethodAuthorization>;A set of methods that are subject to access control.
+struct Methods { /* private fields */ }pub enum Error {
+ InvalidArgument,
+ InsufficientBalance,
+ Forbidden,
+ NotFound,
+ Core(Error),
+}Errors emitted by the accounts module.
+Ok(err) (where err is a dispatcher error) when batch
+should abort or Err(self) when this is just a regular error.pub enum Event {
+ Transfer {
+ from: Address,
+ to: Address,
+ amount: BaseUnits,
+ },
+ Burn {
+ owner: Address,
+ amount: BaseUnits,
+ },
+ Mint {
+ owner: Address,
+ amount: BaseUnits,
+ },
+}Events emitted by the accounts module.
+pub enum ParameterValidationError {
+ DebugOptionUsed(String),
+}Errors emitted during rewards parameter validation.
+Fee manager.
+commit_tx.pub struct FeeManager { /* private fields */ }The per-block fee manager that records what fees have been charged by the current transaction, +how much should be refunded and what were all of the fee payments in the current block.
+Note that the fee manager does not perform any state modifications by itself.
+Fees charged for the current transaction.
+Record that a transaction fee has been charged.
+This method should only be called after the charged fee has been subtracted from the payer’s +account (e.g. reflected in state).
+Record that a portion of the previously charged transaction fee should be refunded.
+Commit the currently open transaction fee by moving the final recorded amount into the fees +charged for the current block.
+Note that this does not perform any state modifications and the caller is assumed to apply +any updates after calling this method.
+Commit the fees accumulated for the current block, returning the resulting map.
+Note that this does not perform any state modifications and the caller is assumed to apply +any updates after calling this method.
+source. Read moreclone_to_uninit)pub struct FeeUpdates {
+ pub payer: Address,
+ pub refund: BaseUnits,
+}Fee updates to apply to state after commit_tx.
This assumes that the initial fee charge has already happened, see the description of
+FeeManager::record_fee for details.
payer: AddressFee payer.
+refund: BaseUnitsAmount that should be refunded to fee payer.
+pub struct TransactionFee { /* private fields */ }Information about fees charged for the current transaction.
+Denomination of the transaction fee.
+source. Read moreclone_to_uninit)Accounts module.
+pub const TOTAL_SUPPLY: &[u8];Map of total supplies (per denomination).
+pub static ADDRESS_COMMON_POOL: Lazy<Address>Module’s address that has the common pool.
+oasis1qz78phkdan64g040cvqvqpwkplfqf6tj6uwcsh30
+pub static ADDRESS_FEE_ACCUMULATOR: Lazy<Address>Module’s address that has the fee accumulator.
+oasis1qp3r8hgsnphajmfzfuaa8fhjag7e0yt35cjxq0u4
+pub struct GasCosts {
+ pub tx_transfer: u64,
+}Gas costs.
+tx_transfer: u64try_default in case the value is null or
+undefined.clone_to_uninit)pub struct Genesis {
+ pub parameters: Parameters,
+ pub accounts: BTreeMap<Address, Account>,
+ pub balances: BTreeMap<Address, BTreeMap<Denomination, u128>>,
+ pub total_supplies: BTreeMap<Denomination, u128>,
+}Genesis state for the accounts module.
+parameters: Parameters§accounts: BTreeMap<Address, Account>§balances: BTreeMap<Address, BTreeMap<Denomination, u128>>§total_supplies: BTreeMap<Denomination, u128>try_default in case the value is null or
+undefined.clone_to_uninit)pub struct Module;Self is a tuple).pub struct Parameters {
+ pub transfers_disabled: bool,
+ pub gas_costs: GasCosts,
+ pub debug_disable_nonce_check: bool,
+ pub denomination_infos: BTreeMap<Denomination, DenominationInfo>,
+}Parameters for the accounts module.
+transfers_disabled: bool§gas_costs: GasCosts§debug_disable_nonce_check: bool§denomination_infos: BTreeMap<Denomination, DenominationInfo>source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub trait API {
+Show 20 methods
// Required methods
+ fn transfer(
+ from: Address,
+ to: Address,
+ amount: &BaseUnits,
+ ) -> Result<(), Error>;
+ fn transfer_silent(
+ from: Address,
+ to: Address,
+ amount: &BaseUnits,
+ ) -> Result<(), Error>;
+ fn mint(to: Address, amount: &BaseUnits) -> Result<(), Error>;
+ fn burn(from: Address, amount: &BaseUnits) -> Result<(), Error>;
+ fn set_nonce(address: Address, nonce: u64);
+ fn get_nonce(address: Address) -> Result<u64, Error>;
+ fn inc_nonce(address: Address);
+ fn set_balance(address: Address, amount: &BaseUnits);
+ fn get_balance(
+ address: Address,
+ denomination: Denomination,
+ ) -> Result<u128, Error>;
+ fn get_balances(address: Address) -> Result<AccountBalances, Error>;
+ fn get_addresses(denomination: Denomination) -> Result<Vec<Address>, Error>;
+ fn get_total_supplies() -> Result<BTreeMap<Denomination, u128>, Error>;
+ fn set_total_supply(amount: &BaseUnits);
+ fn get_denomination_info(
+ denomination: &Denomination,
+ ) -> Result<DenominationInfo, Error>;
+ fn charge_tx_fee(from: Address, amount: &BaseUnits) -> Result<(), Error>;
+ fn set_refund_unused_tx_fee(refund: bool);
+ fn take_refund_unused_tx_fee() -> bool;
+ fn check_signer_nonces<C: Context>(
+ ctx: &C,
+ tx_auth_info: &AuthInfo,
+ ) -> Result<Address, Error>;
+ fn update_signer_nonces<C: Context>(
+ ctx: &C,
+ tx_auth_info: &AuthInfo,
+ ) -> Result<(), Error>;
+
+ // Provided method
+ fn ensure_balance(address: Address, amount: &BaseUnits) -> Result<(), Error> { ... }
+}Interface that can be called from other modules.
+Transfer an amount from one account to the other.
+Transfer an amount from one account to the other without emitting an event.
+Mint new tokens, increasing the total supply.
+Burn existing tokens, decreasing the total supply.
+Sets an account’s balance of the given denomination.
+This method is dangerous as it can result in invariant violations.
+Fetch an account’s balance of the given denomination.
+Fetch an account’s current balances.
+Fetch addresses.
+Fetch total supplies.
+Sets the total supply for the given denomination.
+This method is dangerous as it can result in invariant violations.
+Fetch information about a denomination.
+Moves the amount into the per-transaction fee accumulator.
+Indicates that the unused portion of the transaction fee should be refunded after the +transaction completes (even in case it fails).
+Take the flag indicating that the unused portion of the transaction fee should be refunded +after the transaction completes is set.
+After calling this method the flag is reset to false.
Account module types.
+pub struct Account {
+ pub nonce: u64,
+}Account metadata.
+nonce: u64try_default in case the value is null or
+undefined.clone_to_uninit)pub struct AccountBalances {
+ pub balances: BTreeMap<Denomination, u128>,
+}Balances in an account.
+balances: BTreeMap<Denomination, u128>source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct AddressesQuery {
+ pub denomination: Denomination,
+}Arguments for the Addresses query.
+denomination: Denominationsource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct BalancesQuery {
+ pub address: Address,
+}Arguments for the Balances query.
+address: Addresssource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct DenominationInfo {
+ pub decimals: u8,
+}Information about a denomination.
+decimals: u8Number of decimals that the denomination is using.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct DenominationInfoQuery {
+ pub denomination: Denomination,
+}Arguments for the DenominationInfo query.
+denomination: Denominationsource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct NonceQuery {
+ pub address: Address,
+}Arguments for the Nonce query.
+address: Addresssource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Transfer {
+ pub to: Address,
+ pub amount: BaseUnits,
+}Transfer call.
+to: Address§amount: BaseUnitstry_default in case the value is null or
+undefined.clone_to_uninit)pub enum Error {
+ InvalidArgument,
+ InvalidDenomination,
+ InternalStateError(StateError),
+ Core(Error),
+ ConsensusIncompatibleSigner,
+ AmountNotRepresentable,
+ UnderMinDelegationAmount,
+ History(Error),
+}Ok(err) (where err is a dispatcher error) when batch
+should abort or Err(self) when this is just a regular error.pub enum Event {}Events emitted by the consensus module (none so far).
+pub enum ParameterValidationError {
+ ZeroScalingFactor,
+ ScalingFactorNotPowerOf10,
+}Errors emitted during rewards parameter validation.
+Consensus module.
+Low level consensus module for communicating with the consensus layer.
+pub struct GasCosts {
+ pub round_root: u64,
+}Gas costs.
+round_root: u64Cost of the internal round_root call.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct Genesis {
+ pub parameters: Parameters,
+}Genesis state for the consensus module.
+parameters: Parameterstry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Module;Self is a tuple).pub struct Parameters {
+ pub gas_costs: GasCosts,
+ pub consensus_denomination: Denomination,
+ pub consensus_scaling_factor: u64,
+ pub min_delegate_amount: u128,
+}Parameters for the consensus module.
+gas_costs: GasCosts§consensus_denomination: Denomination§consensus_scaling_factor: u64§min_delegate_amount: u128Minimum amount that is allowed to be delegated. This should be greater than or equal to what +is configured in the consensus layer as the consensus layer will do its own checks.
+The amount is in consensus units.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub trait API {
+ // Required methods
+ fn transfer<C: Context>(
+ ctx: &C,
+ to: Address,
+ amount: &BaseUnits,
+ hook: MessageEventHookInvocation,
+ ) -> Result<(), Error>;
+ fn withdraw<C: Context>(
+ ctx: &C,
+ from: Address,
+ amount: &BaseUnits,
+ hook: MessageEventHookInvocation,
+ ) -> Result<(), Error>;
+ fn escrow<C: Context>(
+ ctx: &C,
+ to: Address,
+ amount: &BaseUnits,
+ hook: MessageEventHookInvocation,
+ ) -> Result<(), Error>;
+ fn reclaim_escrow<C: Context>(
+ ctx: &C,
+ from: Address,
+ amount: u128,
+ hook: MessageEventHookInvocation,
+ ) -> Result<(), Error>;
+ fn consensus_denomination() -> Result<Denomination, Error>;
+ fn ensure_compatible_tx_signer() -> Result<(), Error>;
+ fn account<C: Context>(
+ ctx: &C,
+ addr: Address,
+ ) -> Result<ConsensusAccount, Error>;
+ fn delegation<C: Context>(
+ ctx: &C,
+ delegator_addr: Address,
+ escrow_addr: Address,
+ ) -> Result<ConsensusDelegation, Error>;
+ fn amount_from_consensus<C: Context>(
+ ctx: &C,
+ amount: u128,
+ ) -> Result<u128, Error>;
+ fn amount_to_consensus<C: Context>(
+ ctx: &C,
+ amount: u128,
+ ) -> Result<u128, Error>;
+ fn height_for_epoch<C: Context>(
+ ctx: &C,
+ epoch: EpochTime,
+ ) -> Result<u64, Error>;
+ fn round_roots<C: Context>(
+ ctx: &C,
+ runtime_id: Namespace,
+ round: u64,
+ ) -> Result<Option<RoundRoots>, Error>;
+}Interface that can be called from other modules.
+Transfer an amount from the runtime account.
+Withdraw an amount into the runtime account.
+Escrow an amount of the runtime account funds.
+Reclaim an amount of runtime staked shares.
+Returns consensus token denomination.
+Ensures transaction signer is consensus compatible.
+Query consensus account info.
+Query consensus delegation info.
+Convert runtime amount to consensus amount, scaling as needed.
+Convert consensus amount to runtime amount, scaling as needed.
+Determine consensus height corresponding to the given epoch transition. This query may be +expensive in case the epoch is far back.
+Round roots return the round roots for the given runtime ID and round.
+#[repr(u8)]pub enum RootKind {
+ State = 1,
+ IO = 2,
+}Kind of root.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct RoundRootBody {
+ pub runtime_id: Namespace,
+ pub round: u64,
+ pub kind: RootKind,
+}Internal round root call body.
+runtime_id: Namespace§round: u64§kind: RootKindsource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub enum Error {
+ InvalidArgument,
+ InvalidDenomination,
+ InsufficientBalance,
+ Forbidden,
+ Consensus(Error),
+ Core(Error),
+}Ok(err) (where err is a dispatcher error) when batch
+should abort or Err(self) when this is just a regular error.pub enum Event {
+ Deposit {
+ from: Address,
+ nonce: u64,
+ to: Address,
+ amount: BaseUnits,
+ error: Option<ConsensusError>,
+ },
+ Withdraw {
+ from: Address,
+ nonce: u64,
+ to: Address,
+ amount: BaseUnits,
+ error: Option<ConsensusError>,
+ },
+ Delegate {
+ from: Address,
+ nonce: u64,
+ to: Address,
+ amount: BaseUnits,
+ error: Option<ConsensusError>,
+ },
+ UndelegateStart {
+ from: Address,
+ nonce: u64,
+ to: Address,
+ shares: u128,
+ debond_end_time: EpochTime,
+ error: Option<ConsensusError>,
+ },
+ UndelegateDone {
+ from: Address,
+ to: Address,
+ shares: u128,
+ amount: BaseUnits,
+ },
+}Events emitted by the consensus accounts module.
+Consensus accounts module.
+This module allows consensus transfers in and out of the runtime account, +while keeping track of amount deposited per account.
+pub const DELEGATIONS: &[u8];Map of active delegations.
+pub const RECEIPTS: &[u8];Receipts.
+pub const UNDELEGATIONS: &[u8];Map of undelegations.
+pub const UNDELEGATION_QUEUE: &[u8];An undelegation queue.
+pub fn add_delegation(
+ from: Address,
+ to: Address,
+ shares: u128,
+) -> Result<(), Error>Add delegation for a given (from, to) pair.
+The given shares are added to any existing delegation that may exist for the same (from, to) +address pair. If no delegation exists a new one is created.
+pub fn add_undelegation(
+ from: Address,
+ to: Address,
+ epoch: EpochTime,
+ shares: u128,
+ receipt: u64,
+) -> Result<u64, Error>Record new undelegation and add to undelegation queue.
+In case an undelegation for the given (from, to, epoch) tuple already exists, the undelegation +entry is merged by adding shares. When a non-zero receipt identifier is passed, the identifier +is set in case the existing entry has no such identifier yet.
+It returns the receipt identifier of the undelegation done receipt.
+pub fn get_delegation(
+ from: Address,
+ to: Address,
+) -> Result<DelegationInfo, Error>Retrieve delegation metadata for a given (from, to) pair.
+In case no delegation exists for the given (from, to) address pair, an all-zero delegation +metadata are returned.
+pub fn get_delegations(
+ from: Address,
+) -> Result<Vec<ExtendedDelegationInfo>, Error>Retrieve all delegation metadata originating from a given address.
+pub fn get_delegations_by_destination() -> Result<BTreeMap<Address, u128>, Error>Return the number of delegated shares for each destination escrow account.
+pub fn get_queued_undelegations(
+ epoch: EpochTime,
+) -> Result<Vec<Undelegation>, Error>Retrieve all queued undelegations for epochs earlier than or equal to the passed epoch.
+pub fn get_undelegations(to: Address) -> Result<Vec<UndelegationInfo>, Error>Retrieve all undelegation metadata to a given address.
+pub fn set_receipt(owner: Address, kind: ReceiptKind, id: u64, receipt: Receipt)Store the given receipt.
+pub fn sub_delegation(
+ from: Address,
+ to: Address,
+ shares: u128,
+) -> Result<(), Error>Subtract delegation from a given (from, to) pair.
+pub fn take_receipt(
+ owner: Address,
+ kind: ReceiptKind,
+ id: u64,
+) -> Option<Receipt>Remove the given receipt from storage if it exists and return it, otherwise return None.
pub fn take_undelegation(ud: &Undelegation) -> Result<DelegationInfo, Error>Remove an existing undelegation and return it.
+In case the undelegation doesn’t exist, returns a default-constructed DelegationInfo.
+State schema.
+None.pub struct Undelegation {
+ pub from: Address,
+ pub to: Address,
+ pub epoch: EpochTime,
+}Undelegation metadata.
+from: Address§to: Address§epoch: EpochTimepub static ADDRESS_PENDING_DELEGATION: Lazy<Address>Module’s address that has the tokens pending delegation.
+oasis1qzcdegtf7aunxr5n5pw7n5xs3u7cmzlz9gwmq49r
+pub static ADDRESS_PENDING_WITHDRAWAL: Lazy<Address>Module’s address that has the tokens pending withdrawal.
+oasis1qr677rv0dcnh7ys4yanlynysvnjtk9gnsyhvm6ln
+pub struct GasCosts {
+ pub tx_deposit: u64,
+ pub tx_withdraw: u64,
+ pub tx_delegate: u64,
+ pub tx_undelegate: u64,
+ pub store_receipt: u64,
+ pub take_receipt: u64,
+}Gas costs.
+tx_deposit: u64§tx_withdraw: u64§tx_delegate: u64§tx_undelegate: u64§store_receipt: u64Cost of storing a delegation/undelegation receipt.
+take_receipt: u64Cost of taking a delegation/undelegation receipt.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct Genesis {
+ pub parameters: Parameters,
+}Genesis state for the consensus module.
+parameters: Parameterstry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Module<Consensus: API> { /* private fields */ }Self is a tuple).pub struct Parameters {
+ pub gas_costs: GasCosts,
+ pub disable_delegate: bool,
+ pub disable_undelegate: bool,
+ pub disable_deposit: bool,
+ pub disable_withdraw: bool,
+}Parameters for the consensus module.
+gas_costs: GasCosts§disable_delegate: boolWhether delegate functionality should be disabled.
+disable_undelegate: boolWhether undelegate functionality should be disabled.
+disable_deposit: boolWhether deposit functionality should be disabled.
+disable_withdraw: boolWhether withdraw functionality should be disabled.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub trait API {
+ // Required methods
+ fn deposit<C: Context>(
+ ctx: &C,
+ from: Address,
+ nonce: u64,
+ to: Address,
+ amount: BaseUnits,
+ ) -> Result<(), Error>;
+ fn withdraw<C: Context>(
+ ctx: &C,
+ from: Address,
+ nonce: u64,
+ to: Address,
+ amount: BaseUnits,
+ ) -> Result<(), Error>;
+ fn delegate<C: Context>(
+ ctx: &C,
+ from: Address,
+ nonce: u64,
+ to: Address,
+ amount: BaseUnits,
+ receipt: bool,
+ ) -> Result<(), Error>;
+ fn undelegate<C: Context>(
+ ctx: &C,
+ from: Address,
+ nonce: u64,
+ to: Address,
+ shares: u128,
+ receipt: bool,
+ ) -> Result<(), Error>;
+}Interface that can be called from other modules.
+Transfer from consensus staking account to runtime account.
+nonce: A caller-provided sequence number that will help identify the success/fail events.
+When called from a deposit transaction, we use the signer nonce.Transfer from runtime account to consensus staking account.
+nonce: A caller-provided sequence number that will help identify the success/fail events.
+When called from a withdraw transaction, we use the signer nonce.Delegate from runtime account to consensus staking account.
+nonce: A caller-provided sequence number that will help identify the success/fail events.
+When called from a delegate transaction, we use the signer nonce.Start the undelegation process of the given number of shares from consensus staking account +to runtime account.
+nonce: A caller-provided sequence number that will help identify the success/fail events.
+When called from an undelegate transaction, we use the signer nonce.#[repr(u8)]pub enum ReceiptKind {
+ Invalid = 0,
+ Delegate = 1,
+ UndelegateStart = 2,
+ UndelegateDone = 3,
+}Kind of receipt.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)Consensus module types.
+to address runtime account gets the tokens.to address consensus staking account gets the tokens.pub struct AccountBalance {
+ pub balance: u128,
+}balance: u128source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct BalanceQuery {
+ pub address: Address,
+}Balance query.
+address: Addresssource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct ConsensusAccountQuery {
+ pub address: Address,
+}Consensus account query.
+address: Addresssource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct ConsensusDelegateContext {
+ pub from: Address,
+ pub nonce: u64,
+ pub to: Address,
+ pub amount: BaseUnits,
+ pub receipt: bool,
+}Context for consensus delegate message handler.
+from: Address§nonce: u64§to: Address§amount: BaseUnits§receipt: boolsource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct ConsensusError {
+ pub module: String,
+ pub code: u32,
+}Error details from the consensus layer.
+module: String§code: u32source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct ConsensusTransferContext {
+ pub address: Address,
+ pub nonce: u64,
+ pub to: Address,
+ pub amount: BaseUnits,
+}Context for consensus transfer message handler.
+address: Address§nonce: u64§to: Address§amount: BaseUnitssource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct ConsensusUndelegateContext {
+ pub from: Address,
+ pub nonce: u64,
+ pub to: Address,
+ pub shares: u128,
+ pub receipt: bool,
+}Context for consensus undelegate message handler.
+from: Address§nonce: u64§to: Address§receipt: boolsource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct ConsensusWithdrawContext {
+ pub from: Address,
+ pub nonce: u64,
+ pub address: Address,
+ pub amount: BaseUnits,
+}Context for consensus withdraw message handler.
+from: Address§nonce: u64§address: Address§amount: BaseUnitssource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Delegate {
+ pub to: Address,
+ pub amount: BaseUnits,
+ pub receipt: u64,
+}Delegate from runtime call.
+to: Address§amount: BaseUnits§receipt: u64try_default in case the value is null or
+undefined.clone_to_uninit)pub struct DelegationInfo {
+ pub shares: u128,
+ pub receipt: u64,
+}Information about a delegation.
+The amount of owned shares.
+receipt: u64Receipt identifier for this undelegation.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct DelegationQuery {
+ pub from: Address,
+ pub to: Address,
+}Delegation query.
+from: Address§to: Addresssource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct DelegationsQuery {
+ pub from: Address,
+}Delegations query.
+from: Addresssource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Deposit {
+ pub to: Option<Address>,
+ pub amount: BaseUnits,
+}Deposit into runtime call.
+Transfer from consensus staking to an account in this runtime.
+The transaction signer has a consensus layer allowance benefiting this runtime’s staking
+address. The to address runtime account gets the tokens.
to: Option<Address>§amount: BaseUnitstry_default in case the value is null or
+undefined.clone_to_uninit)pub struct ExtendedDelegationInfo {
+ pub to: Address,
+ pub shares: u128,
+}Extended information about a delegation.
+to: AddressAddress delegated to.
+The amount of owned shares.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Receipt {
+ pub shares: u128,
+ pub epoch: EpochTime,
+ pub receipt: u64,
+ pub amount: u128,
+ pub error: Option<ConsensusError>,
+}A receipt.
+Shares received (for delegations).
+epoch: EpochTimeUndelegate end epoch.
+receipt: u64Undelegate end receipt.
+amount: u128Amount of tokens received.
+error: Option<ConsensusError>Consensus layer error.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct TakeReceipt {
+ pub kind: ReceiptKind,
+ pub id: u64,
+}Take receipt internal runtime call.
+kind: ReceiptKind§id: u64source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Undelegate {
+ pub from: Address,
+ pub shares: u128,
+ pub receipt: u64,
+}Undelegate into runtime call.
+from: Address§receipt: u64source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct UndelegationInfo {
+ pub from: Address,
+ pub epoch: EpochTime,
+ pub shares: u128,
+}Information about an undelegation.
+from: AddressAddress being undelegated from.
+epoch: EpochTimeEpoch when the undelegation will be complete.
+The amount of undelegated shares.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct UndelegationsQuery {
+ pub to: Address,
+}Undelegations query.
+to: Addresssource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Withdraw {
+ pub to: Option<Address>,
+ pub amount: BaseUnits,
+}Withdraw from runtime call.
+Transfer from an account in this runtime to consensus staking.
+The to address consensus staking account gets the tokens.
to: Option<Address>§amount: BaseUnitstry_default in case the value is null or
+undefined.clone_to_uninit)pub const MODULE_NAME: &str = "core";Unique module name.
+pub enum Error {
+Show 26 variants
MalformedTransaction(Error),
+ InvalidTransaction(Error),
+ InvalidMethod(String),
+ InvalidNonce,
+ InsufficientFeeBalance,
+ OutOfMessageSlots,
+ MessageHandlerNotInvoked,
+ MessageHandlerMissing(u32),
+ InvalidArgument(Error),
+ GasOverflow,
+ OutOfGas(u64, u64),
+ TooManyAuth,
+ MultisigTooManySigners,
+ InvariantViolation(String),
+ InvalidCallFormat(Error),
+ Abort(Error),
+ NotAuthenticated,
+ GasPriceTooLow,
+ ForbiddenInSecureBuild,
+ Forbidden,
+ OversizedTransaction,
+ ExpiredTransaction,
+ ReadOnlyTransaction,
+ FutureNonce,
+ CallDepthExceeded(u16, u16),
+ TxSimulationFailed(TxSimulationFailure),
+}Errors emitted by the core module.
+Ok(err) (where err is a dispatcher error) when batch
+should abort or Err(self) when this is just a regular error.pub enum Event {
+ GasUsed {
+ amount: u64,
+ },
+}Events emitted by the core module.
+key and return true if they are equal.pub enum ParameterValidationError {
+ InvalidTargetBlockGasUsagePercentage,
+ InvalidMinPriceMaxChangeDenominator,
+}Errors emitted during core parameter validation.
+Core definitions module.
+pub const DYNAMIC_MIN_GAS_PRICE: &[u8];Dynamic min gas price.
+pub const LAST_EPOCH: &[u8];Last processed epoch for detecting epoch changes.
+pub const MESSAGE_HANDLERS: &[u8];Map of message idx to message handlers for messages emitted in previous round.
+pub struct DynamicMinGasPrice {
+ pub enabled: bool,
+ pub target_block_gas_usage_percentage: u8,
+ pub min_price_max_change_denominator: u8,
+}Dynamic min gas price parameters.
+enabled: boolEnables the dynamic min gas price feature which dynamically adjusts the minimum gas price +based on block fullness, inspired by EIP-1559.
+Only takes effect if min_gas_price(s) are set.
target_block_gas_usage_percentage: u8Target block gas usage indicates the desired block gas usage as a percentage of the total +block gas limit.
+The min gas price will adjust up or down depending on whether the actual gas usage is above +or below this target.
+min_price_max_change_denominator: u8Represents a constant value used to limit the rate at which the min price can change +between blocks.
+For example, if min_price_max_change_denominator is set to 8, the maximum change in
+min price is 12.5% between blocks.
source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct GasCosts {
+ pub tx_byte: u64,
+ pub storage_byte: u64,
+ pub auth_signature: u64,
+ pub auth_multisig_signer: u64,
+ pub callformat_x25519_deoxysii: u64,
+}Gas costs.
+tx_byte: u64§storage_byte: u64§auth_signature: u64§auth_multisig_signer: u64§callformat_x25519_deoxysii: u64try_default in case the value is null or
+undefined.clone_to_uninit)pub struct Genesis {
+ pub parameters: Parameters,
+}Genesis state for the accounts module.
+parameters: Parameterstry_default in case the value is null or
+undefined.clone_to_uninit)pub struct LocalConfig {
+ pub min_gas_price: BTreeMap<Denomination, u128>,
+ pub max_estimated_gas: u64,
+ pub estimate_gas_search_max_iters: u64,
+}Local configuration that can be provided by the node operator.
+min_gas_price: BTreeMap<Denomination, u128>Minimum gas price to accept.
+max_estimated_gas: u64When estimating gas in core.EstimateGas, simulate the tx (and report) only up to this much
+used gas. This limit is more likely to be relevant if estimate_gas_by_simulating_contracts is
+enabled in the local config. The special value of 0 means that the maximum amount of gas in a
+batch will be used.
estimate_gas_search_max_iters: u64The maximum number of iterations of the binary search to be done when simulating contracts for
+gas estimation in core.EstimateGas.
+The special value of 0 means that binary search won’t be performed, and the transaction will be
+simulated using maximum possible gas, which might return an overestimation in some special cases.
+This setting should likely be kept at 0, unless the runtime is using the EVM module.
source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Module<Cfg: Config> { /* private fields */ }Run a transaction in simulation and return how much gas it uses. This looks up the method +in the context’s method registry. Transactions that fail still use gas, and this query will +estimate that and return successfully, so do not use this query to see if a transaction will +succeed.
+Self is a tuple).pub struct Parameters {
+ pub max_batch_gas: u64,
+ pub max_tx_size: u32,
+ pub max_tx_signers: u32,
+ pub max_multisig_signers: u32,
+ pub gas_costs: GasCosts,
+ pub min_gas_price: BTreeMap<Denomination, u128>,
+ pub dynamic_min_gas_price: DynamicMinGasPrice,
+}Parameters for the core module.
+max_batch_gas: u64§max_tx_size: u32§max_tx_signers: u32§max_multisig_signers: u32§gas_costs: GasCosts§min_gas_price: BTreeMap<Denomination, u128>§dynamic_min_gas_price: DynamicMinGasPricesource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct TxSimulationFailure { /* private fields */ }Simulation failure error.
+Returns true if the failure is “core::Error::OutOfGas”.
+pub trait API {
+ type Config: Config;
+
+Show 14 methods
// Required methods
+ fn use_batch_gas(gas: u64) -> Result<(), Error>;
+ fn use_tx_gas(gas: u64) -> Result<(), Error>;
+ fn remaining_batch_gas() -> u64;
+ fn used_batch_gas() -> u64;
+ fn remaining_tx_gas() -> u64;
+ fn used_tx_gas() -> u64;
+ fn max_batch_gas() -> u64;
+ fn min_gas_price(denom: &Denomination) -> Option<u128>;
+ fn set_priority(priority: u64);
+ fn take_priority() -> u64;
+ fn set_sender_meta(meta: SenderMeta);
+ fn take_sender_meta() -> SenderMeta;
+ fn estimate_gas_search_max_iters<C: Context>(ctx: &C) -> u64;
+ fn has_epoch_changed() -> bool;
+}Interface that can be called from other modules.
+Attempt to use gas. If the gas specified would cause either total used to exceed +its limit, fails with Error::OutOfGas or Error::BatchOutOfGas, and neither gas usage is +increased.
+Attempt to use gas. If the gas specified would cause either total used to exceed +its limit, fails with Error::OutOfGas or Error::BatchOutOfGas, and neither gas usage is +increased.
+Returns the remaining batch-wide gas.
+Returns the total batch-wide gas used.
+Return the remaining tx-wide gas.
+Return the used tx-wide gas.
+Configured maximum amount of gas that can be used in a batch.
+Configured minimum gas price.
+Sets the transaction priority to the provided amount.
+Takes and returns the stored transaction priority.
+Set transaction sender metadata.
+Takes and returns the stored transaction sender metadata.
+Returns the configured max iterations in the binary search for the estimate +gas.
+Check whether the epoch has changed since last processed block.
+pub trait Config: 'static {
+ const DEFAULT_LOCAL_MIN_GAS_PRICE: Lazy<BTreeMap<Denomination, u128>> = _;
+ const DEFAULT_LOCAL_ESTIMATE_GAS_SEARCH_MAX_ITERS: u64 = 0u64;
+ const ESTIMATE_GAS_EXTRA_FAIL: Lazy<BTreeMap<&'static str, u64>> = _;
+ const MIN_GAS_PRICE_EXEMPT_METHODS: Lazy<BTreeSet<&'static str>> = _;
+ const EMIT_GAS_USED_EVENTS: bool = true;
+ const ALLOW_INTERACTIVE_READ_ONLY_TRANSACTIONS: bool = false;
+ const GAS_COST_CALL_CALLDATA_PUBLIC_KEY: u64 = 20u64;
+ const GAS_COST_CALL_CURRENT_EPOCH: u64 = 10u64;
+}Module configuration.
+Default local minimum gas price configuration that is used in case no overrides are set in +local per-node configuration.
+Default local estimate gas max search iterations configuration that is used in case no overrides +are set in the local per-node configuration.
+Estimated gas amount to be added to failed transaction simulations for selected methods.
+Methods which are exempt from minimum gas price requirements.
+Whether gas used events should be emitted for every transaction.
+Confidential runtimes may want to disable this as it is a possible side channel.
+Whether to allow submission of read-only transactions in an interactive way.
+Note that execution of such transactions is allowed to access confidential state.
+The gas cost of the internal call to retrieve the current calldata public key.
+The gas cost of the internal call to retrieve the current epoch.
+pub const VERSION_GLOBAL_KEY: &str = "";Key in the versions map used for the global state version.
+pub enum MethodHandlerKind {
+ Call,
+ Query,
+ MessageResult,
+}source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)clone_to_uninit)pub struct CallDataPublicKeyQueryResponse {
+ pub public_key: SignedPublicKey,
+ pub epoch: u64,
+}Response to the call data public key query.
+public_key: SignedPublicKeyPublic key used for deriving the shared secret for encrypting call data.
+epoch: u64Epoch of the ephemeral runtime key.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct EstimateGasQuery {
+ pub caller: Option<CallerAddress>,
+ pub tx: Transaction,
+ pub propagate_failures: bool,
+}Arguments for the EstimateGas query.
+caller: Option<CallerAddress>The address of the caller for which to do estimation. If not specified the authentication +information from the passed transaction is used.
+tx: TransactionThe unsigned transaction to estimate.
+propagate_failures: boolIf the estimate gas query should fail in case of transaction failures. +If true, the query will return the transaction error and not the gas estimation. +Defaults to false.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct ExecuteReadOnlyTxQuery {
+ pub tx: Vec<u8>,
+}Arguments for the ExecuteReadOnlyTx query.
+tx: Vec<u8>source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct ExecuteReadOnlyTxResponse {
+ pub result: CallResult,
+}Response to the ExecuteReadOnlyTx query.
+result: CallResultsource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Metadata {
+ pub versions: BTreeMap<String, u32>,
+}Basic per-module metadata; tracked in core module’s state.
+versions: BTreeMap<String, u32>A set of state versions for all supported modules.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct MethodHandlerInfo {
+ pub kind: MethodHandlerKind,
+ pub name: String,
+}kind: MethodHandlerKind§name: Stringsource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct ModuleInfo {
+ pub version: u32,
+ pub params: Value,
+ pub methods: Vec<MethodHandlerInfo>,
+}Metadata for an individual module.
+version: u32§params: Value§methods: Vec<MethodHandlerInfo>source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct RuntimeInfoResponse {
+ pub runtime_version: Version,
+ pub state_version: u32,
+ pub modules: BTreeMap<String, ModuleInfo>,
+}Response to the RuntimeInfo query.
+runtime_version: Version§state_version: u32§modules: BTreeMap<String, ModuleInfo>source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)Runtime modules included with the SDK.
+pub enum Error {
+ InvalidArgument,
+}Errors emitted by the rewards module.
+Ok(err) (where err is a dispatcher error) when batch
+should abort or Err(self) when this is just a regular error.pub enum ParameterValidationError {
+ InvalidParticipationThreshold,
+ InvalidSchedule(RewardScheduleError),
+}Errors emitted during rewards parameter validation.
+Rewards module.
+pub static ADDRESS_REWARD_POOL: Lazy<Address>Module’s address that has the reward pool.
+oasis1qp7x0q9qahahhjas0xde8w0v04ctp4pqzu5mhjav
+pub struct Genesis {
+ pub parameters: Parameters,
+}Genesis state for the rewards module.
+parameters: Parameterstry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Module;Rewards module.
+Self is a tuple).pub struct Parameters {
+ pub schedule: RewardSchedule,
+ pub participation_threshold_numerator: u64,
+ pub participation_threshold_denominator: u64,
+}Parameters for the rewards module.
+schedule: RewardSchedule§participation_threshold_numerator: u64§participation_threshold_denominator: u64source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub enum RewardAction {
+ Reward(u64),
+ NoReward,
+}Action that should be taken for a given address when disbursing rewards.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub enum RewardScheduleError {
+ StepsNotSorted,
+}Errors emitted during reward schedule validation.
+Rewards module types.
+pub struct EpochRewards {
+ pub pending: BTreeMap<Address, RewardAction>,
+}Rewards for the epoch.
+pending: BTreeMap<Address, RewardAction>source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct RewardSchedule {
+ pub steps: Vec<RewardStep>,
+}A reward schedule.
+steps: Vec<RewardStep>Perform basic reward schedule validation.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct RewardStep {
+ pub until: EpochTime,
+ pub amount: BaseUnits,
+}One of the time periods in the reward schedule.
+until: EpochTime§amount: BaseUnitssource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)Redirecting to ../../../../../oasis_runtime_sdk/modules/rofl/app/struct.Client.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_runtime_sdk/modules/rofl/app/env/struct.Environment.html b/rust/oasis_runtime_sdk/modules/rofl/app/env/struct.Environment.html new file mode 100644 index 0000000000..7f86ec5ce1 --- /dev/null +++ b/rust/oasis_runtime_sdk/modules/rofl/app/env/struct.Environment.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../../oasis_runtime_sdk/modules/rofl/app/struct.Environment.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_runtime_sdk/modules/rofl/app/index.html b/rust/oasis_runtime_sdk/modules/rofl/app/index.html new file mode 100644 index 0000000000..762c00f16a --- /dev/null +++ b/rust/oasis_runtime_sdk/modules/rofl/app/index.html @@ -0,0 +1,2 @@ +Wrapper to make development of ROFL components easier.
+pub use crate::modules::rofl::app_id::AppId;#[async_trait]Prelude for ROFL applications.
+pub use crate as sdk;pub use super::App;pub use super::AppId;pub use super::Environment;Result<T, Error>pub struct Arc<T, A = Global>{ /* private fields */ }A thread-safe reference-counting pointer. ‘Arc’ stands for ‘Atomically +Reference Counted’.
+The type Arc<T> provides shared ownership of a value of type T,
+allocated in the heap. Invoking clone on Arc produces
+a new Arc instance, which points to the same allocation on the heap as the
+source Arc, while increasing a reference count. When the last Arc
+pointer to a given allocation is destroyed, the value stored in that allocation (often
+referred to as “inner value”) is also dropped.
Shared references in Rust disallow mutation by default, and Arc is no
+exception: you cannot generally obtain a mutable reference to something
+inside an Arc. If you need to mutate through an Arc, use
+Mutex, RwLock, or one of the Atomic
+types.
Note: This type is only available on platforms that support atomic
+loads and stores of pointers, which includes all platforms that support
+the std crate but not all those which only support alloc.
+This may be detected at compile time using #[cfg(target_has_atomic = "ptr")].
Unlike Rc<T>, Arc<T> uses atomic operations for its reference
+counting. This means that it is thread-safe. The disadvantage is that
+atomic operations are more expensive than ordinary memory accesses. If you
+are not sharing reference-counted allocations between threads, consider using
+Rc<T> for lower overhead. Rc<T> is a safe default, because the
+compiler will catch any attempt to send an Rc<T> between threads.
+However, a library might choose Arc<T> in order to give library consumers
+more flexibility.
Arc<T> will implement Send and Sync as long as the T implements
+Send and Sync. Why can’t you put a non-thread-safe type T in an
+Arc<T> to make it thread-safe? This may be a bit counter-intuitive at
+first: after all, isn’t the point of Arc<T> thread safety? The key is
+this: Arc<T> makes it thread safe to have multiple ownership of the same
+data, but it doesn’t add thread safety to its data. Consider
+Arc<RefCell<T>>. RefCell<T> isn’t Sync, and if Arc<T> was always
+Send, Arc<RefCell<T>> would be as well. But then we’d have a problem:
+RefCell<T> is not thread safe; it keeps track of the borrowing count using
+non-atomic operations.
In the end, this means that you may need to pair Arc<T> with some sort of
+std::sync type, usually Mutex<T>.
WeakThe downgrade method can be used to create a non-owning
+Weak pointer. A Weak pointer can be upgraded
+to an Arc, but this will return None if the value stored in the allocation has
+already been dropped. In other words, Weak pointers do not keep the value
+inside the allocation alive; however, they do keep the allocation
+(the backing store for the value) alive.
A cycle between Arc pointers will never be deallocated. For this reason,
+Weak is used to break cycles. For example, a tree could have
+strong Arc pointers from parent nodes to children, and Weak
+pointers from children back to their parents.
Creating a new reference from an existing reference-counted pointer is done using the
+Clone trait implemented for Arc<T> and Weak<T>.
use std::sync::Arc;
+let foo = Arc::new(vec![1.0, 2.0, 3.0]);
+// The two syntaxes below are equivalent.
+let a = foo.clone();
+let b = Arc::clone(&foo);
+// a, b, and foo are all Arcs that point to the same memory locationDeref behaviorArc<T> automatically dereferences to T (via the Deref trait),
+so you can call T’s methods on a value of type Arc<T>. To avoid name
+clashes with T’s methods, the methods of Arc<T> itself are associated
+functions, called using fully qualified syntax:
use std::sync::Arc;
+
+let my_arc = Arc::new(());
+let my_weak = Arc::downgrade(&my_arc);Arc<T>’s implementations of traits like Clone may also be called using
+fully qualified syntax. Some people prefer to use fully qualified syntax,
+while others prefer using method-call syntax.
use std::sync::Arc;
+
+let arc = Arc::new(());
+// Method-call syntax
+let arc2 = arc.clone();
+// Fully qualified syntax
+let arc3 = Arc::clone(&arc);Weak<T> does not auto-dereference to T, because the inner value may have
+already been dropped.
Sharing some immutable data between threads:
+ +use std::sync::Arc;
+use std::thread;
+
+let five = Arc::new(5);
+
+for _ in 0..10 {
+ let five = Arc::clone(&five);
+
+ thread::spawn(move || {
+ println!("{five:?}");
+ });
+}Sharing a mutable AtomicUsize:
use std::sync::Arc;
+use std::sync::atomic::{AtomicUsize, Ordering};
+use std::thread;
+
+let val = Arc::new(AtomicUsize::new(5));
+
+for _ in 0..10 {
+ let val = Arc::clone(&val);
+
+ thread::spawn(move || {
+ let v = val.fetch_add(1, Ordering::Relaxed);
+ println!("{v:?}");
+ });
+}See the rc documentation for more examples of reference
+counting in general.
Constructs a new Arc<T> while giving you a Weak<T> to the allocation,
+to allow you to construct a T which holds a weak pointer to itself.
Generally, a structure circularly referencing itself, either directly or
+indirectly, should not hold a strong reference to itself to prevent a memory leak.
+Using this function, you get access to the weak pointer during the
+initialization of T, before the Arc<T> is created, such that you can
+clone and store it inside the T.
new_cyclic first allocates the managed allocation for the Arc<T>,
+then calls your closure, giving it a Weak<T> to this allocation,
+and only afterwards completes the construction of the Arc<T> by placing
+the T returned from your closure into the allocation.
Since the new Arc<T> is not fully-constructed until Arc<T>::new_cyclic
+returns, calling upgrade on the weak reference inside your closure will
+fail and result in a None value.
If data_fn panics, the panic is propagated to the caller, and the
+temporary Weak<T> is dropped normally.
use std::sync::{Arc, Weak};
+
+struct Gadget {
+ me: Weak<Gadget>,
+}
+
+impl Gadget {
+ /// Construct a reference counted Gadget.
+ fn new() -> Arc<Self> {
+ // `me` is a `Weak<Gadget>` pointing at the new allocation of the
+ // `Arc` we're constructing.
+ Arc::new_cyclic(|me| {
+ // Create the actual struct here.
+ Gadget { me: me.clone() }
+ })
+ }
+
+ /// Return a reference counted pointer to Self.
+ fn me(&self) -> Arc<Self> {
+ self.me.upgrade().unwrap()
+ }
+}new_uninit)Constructs a new Arc with uninitialized contents.
#![feature(new_uninit)]
+#![feature(get_mut_unchecked)]
+
+use std::sync::Arc;
+
+let mut five = Arc::<u32>::new_uninit();
+
+// Deferred initialization:
+Arc::get_mut(&mut five).unwrap().write(5);
+
+let five = unsafe { five.assume_init() };
+
+assert_eq!(*five, 5)new_uninit)Constructs a new Arc with uninitialized contents, with the memory
+being filled with 0 bytes.
See MaybeUninit::zeroed for examples of correct and incorrect usage
+of this method.
#![feature(new_uninit)]
+
+use std::sync::Arc;
+
+let zero = Arc::<u32>::new_zeroed();
+let zero = unsafe { zero.assume_init() };
+
+assert_eq!(*zero, 0)Constructs a new Pin<Arc<T>>. If T does not implement Unpin, then
+data will be pinned in memory and unable to be moved.
allocator_api)Constructs a new Pin<Arc<T>>, return an error if allocation fails.
allocator_api)Constructs a new Arc<T>, returning an error if allocation fails.
#![feature(allocator_api)]
+use std::sync::Arc;
+
+let five = Arc::try_new(5)?;allocator_api)Constructs a new Arc with uninitialized contents, returning an error
+if allocation fails.
#![feature(new_uninit, allocator_api)]
+#![feature(get_mut_unchecked)]
+
+use std::sync::Arc;
+
+let mut five = Arc::<u32>::try_new_uninit()?;
+
+// Deferred initialization:
+Arc::get_mut(&mut five).unwrap().write(5);
+
+let five = unsafe { five.assume_init() };
+
+assert_eq!(*five, 5);allocator_api)Constructs a new Arc with uninitialized contents, with the memory
+being filled with 0 bytes, returning an error if allocation fails.
See MaybeUninit::zeroed for examples of correct and incorrect usage
+of this method.
#![feature(new_uninit, allocator_api)]
+
+use std::sync::Arc;
+
+let zero = Arc::<u32>::try_new_zeroed()?;
+let zero = unsafe { zero.assume_init() };
+
+assert_eq!(*zero, 0);allocator_api)Returns a reference to the underlying allocator.
+Note: this is an associated function, which means that you have
+to call it as Arc::allocator(&a) instead of a.allocator(). This
+is so that there is no conflict with a method on the inner type.
allocator_api)Constructs a new Arc<T> in the provided allocator.
#![feature(allocator_api)]
+
+use std::sync::Arc;
+use std::alloc::System;
+
+let five = Arc::new_in(5, System);allocator_api)Constructs a new Arc with uninitialized contents in the provided allocator.
#![feature(new_uninit)]
+#![feature(get_mut_unchecked)]
+#![feature(allocator_api)]
+
+use std::sync::Arc;
+use std::alloc::System;
+
+let mut five = Arc::<u32, _>::new_uninit_in(System);
+
+let five = unsafe {
+ // Deferred initialization:
+ Arc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);
+
+ five.assume_init()
+};
+
+assert_eq!(*five, 5)allocator_api)Constructs a new Arc with uninitialized contents, with the memory
+being filled with 0 bytes, in the provided allocator.
See MaybeUninit::zeroed for examples of correct and incorrect usage
+of this method.
#![feature(new_uninit)]
+#![feature(allocator_api)]
+
+use std::sync::Arc;
+use std::alloc::System;
+
+let zero = Arc::<u32, _>::new_zeroed_in(System);
+let zero = unsafe { zero.assume_init() };
+
+assert_eq!(*zero, 0)allocator_api)Constructs a new Pin<Arc<T, A>> in the provided allocator. If T does not implement Unpin,
+then data will be pinned in memory and unable to be moved.
allocator_api)Constructs a new Pin<Arc<T, A>> in the provided allocator, return an error if allocation
+fails.
allocator_api)Constructs a new Arc<T, A> in the provided allocator, returning an error if allocation fails.
#![feature(allocator_api)]
+
+use std::sync::Arc;
+use std::alloc::System;
+
+let five = Arc::try_new_in(5, System)?;allocator_api)Constructs a new Arc with uninitialized contents, in the provided allocator, returning an
+error if allocation fails.
#![feature(new_uninit, allocator_api)]
+#![feature(get_mut_unchecked)]
+
+use std::sync::Arc;
+use std::alloc::System;
+
+let mut five = Arc::<u32, _>::try_new_uninit_in(System)?;
+
+let five = unsafe {
+ // Deferred initialization:
+ Arc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);
+
+ five.assume_init()
+};
+
+assert_eq!(*five, 5);allocator_api)Constructs a new Arc with uninitialized contents, with the memory
+being filled with 0 bytes, in the provided allocator, returning an error if allocation
+fails.
See MaybeUninit::zeroed for examples of correct and incorrect usage
+of this method.
#![feature(new_uninit, allocator_api)]
+
+use std::sync::Arc;
+use std::alloc::System;
+
+let zero = Arc::<u32, _>::try_new_zeroed_in(System)?;
+let zero = unsafe { zero.assume_init() };
+
+assert_eq!(*zero, 0);Returns the inner value, if the Arc has exactly one strong reference.
Otherwise, an Err is returned with the same Arc that was
+passed in.
This will succeed even if there are outstanding weak references.
+It is strongly recommended to use Arc::into_inner instead if you don’t
+keep the Arc in the Err case.
+Immediately dropping the Err-value, as the expression
+Arc::try_unwrap(this).ok() does, can cause the strong count to
+drop to zero and the inner value of the Arc to be dropped.
+For instance, if two threads execute such an expression in parallel,
+there is a race condition without the possibility of unsafety:
+The threads could first both check whether they own the last instance
+in Arc::try_unwrap, determine that they both do not, and then both
+discard and drop their instance in the call to ok.
+In this scenario, the value inside the Arc is safely destroyed
+by exactly one of the threads, but neither thread will ever be able
+to use the value.
use std::sync::Arc;
+
+let x = Arc::new(3);
+assert_eq!(Arc::try_unwrap(x), Ok(3));
+
+let x = Arc::new(4);
+let _y = Arc::clone(&x);
+assert_eq!(*Arc::try_unwrap(x).unwrap_err(), 4);Returns the inner value, if the Arc has exactly one strong reference.
Otherwise, None is returned and the Arc is dropped.
This will succeed even if there are outstanding weak references.
+If Arc::into_inner is called on every clone of this Arc,
+it is guaranteed that exactly one of the calls returns the inner value.
+This means in particular that the inner value is not dropped.
Arc::try_unwrap is conceptually similar to Arc::into_inner, but it
+is meant for different use-cases. If used as a direct replacement
+for Arc::into_inner anyway, such as with the expression
+Arc::try_unwrap(this).ok(), then it does
+not give the same guarantee as described in the previous paragraph.
+For more information, see the examples below and read the documentation
+of Arc::try_unwrap.
Minimal example demonstrating the guarantee that Arc::into_inner gives.
use std::sync::Arc;
+
+let x = Arc::new(3);
+let y = Arc::clone(&x);
+
+// Two threads calling `Arc::into_inner` on both clones of an `Arc`:
+let x_thread = std::thread::spawn(|| Arc::into_inner(x));
+let y_thread = std::thread::spawn(|| Arc::into_inner(y));
+
+let x_inner_value = x_thread.join().unwrap();
+let y_inner_value = y_thread.join().unwrap();
+
+// One of the threads is guaranteed to receive the inner value:
+assert!(matches!(
+ (x_inner_value, y_inner_value),
+ (None, Some(3)) | (Some(3), None)
+));
+// The result could also be `(None, None)` if the threads called
+// `Arc::try_unwrap(x).ok()` and `Arc::try_unwrap(y).ok()` instead.A more practical example demonstrating the need for Arc::into_inner:
use std::sync::Arc;
+
+// Definition of a simple singly linked list using `Arc`:
+#[derive(Clone)]
+struct LinkedList<T>(Option<Arc<Node<T>>>);
+struct Node<T>(T, Option<Arc<Node<T>>>);
+
+// Dropping a long `LinkedList<T>` relying on the destructor of `Arc`
+// can cause a stack overflow. To prevent this, we can provide a
+// manual `Drop` implementation that does the destruction in a loop:
+impl<T> Drop for LinkedList<T> {
+ fn drop(&mut self) {
+ let mut link = self.0.take();
+ while let Some(arc_node) = link.take() {
+ if let Some(Node(_value, next)) = Arc::into_inner(arc_node) {
+ link = next;
+ }
+ }
+ }
+}
+
+// Implementation of `new` and `push` omitted
+impl<T> LinkedList<T> {
+ /* ... */
+}
+
+// The following code could have still caused a stack overflow
+// despite the manual `Drop` impl if that `Drop` impl had used
+// `Arc::try_unwrap(arc).ok()` instead of `Arc::into_inner(arc)`.
+
+// Create a long list and clone it
+let mut x = LinkedList::new();
+let size = 100000;
+for i in 0..size {
+ x.push(i); // Adds i to the front of x
+}
+let y = x.clone();
+
+// Drop the clones in parallel
+let x_thread = std::thread::spawn(|| drop(x));
+let y_thread = std::thread::spawn(|| drop(y));
+x_thread.join().unwrap();
+y_thread.join().unwrap();new_uninit)Constructs a new atomically reference-counted slice with uninitialized contents.
+#![feature(new_uninit)]
+#![feature(get_mut_unchecked)]
+
+use std::sync::Arc;
+
+let mut values = Arc::<[u32]>::new_uninit_slice(3);
+
+// Deferred initialization:
+let data = Arc::get_mut(&mut values).unwrap();
+data[0].write(1);
+data[1].write(2);
+data[2].write(3);
+
+let values = unsafe { values.assume_init() };
+
+assert_eq!(*values, [1, 2, 3])new_uninit)Constructs a new atomically reference-counted slice with uninitialized contents, with the memory being
+filled with 0 bytes.
See MaybeUninit::zeroed for examples of correct and
+incorrect usage of this method.
#![feature(new_uninit)]
+
+use std::sync::Arc;
+
+let values = Arc::<[u32]>::new_zeroed_slice(3);
+let values = unsafe { values.assume_init() };
+
+assert_eq!(*values, [0, 0, 0])new_uninit)Constructs a new atomically reference-counted slice with uninitialized contents in the +provided allocator.
+#![feature(new_uninit)]
+#![feature(get_mut_unchecked)]
+#![feature(allocator_api)]
+
+use std::sync::Arc;
+use std::alloc::System;
+
+let mut values = Arc::<[u32], _>::new_uninit_slice_in(3, System);
+
+let values = unsafe {
+ // Deferred initialization:
+ Arc::get_mut_unchecked(&mut values)[0].as_mut_ptr().write(1);
+ Arc::get_mut_unchecked(&mut values)[1].as_mut_ptr().write(2);
+ Arc::get_mut_unchecked(&mut values)[2].as_mut_ptr().write(3);
+
+ values.assume_init()
+};
+
+assert_eq!(*values, [1, 2, 3])new_uninit)Constructs a new atomically reference-counted slice with uninitialized contents, with the memory being
+filled with 0 bytes, in the provided allocator.
See MaybeUninit::zeroed for examples of correct and
+incorrect usage of this method.
#![feature(new_uninit)]
+#![feature(allocator_api)]
+
+use std::sync::Arc;
+use std::alloc::System;
+
+let values = Arc::<[u32], _>::new_zeroed_slice_in(3, System);
+let values = unsafe { values.assume_init() };
+
+assert_eq!(*values, [0, 0, 0])new_uninit)Converts to Arc<T>.
As with MaybeUninit::assume_init,
+it is up to the caller to guarantee that the inner value
+really is in an initialized state.
+Calling this when the content is not yet fully initialized
+causes immediate undefined behavior.
#![feature(new_uninit)]
+#![feature(get_mut_unchecked)]
+
+use std::sync::Arc;
+
+let mut five = Arc::<u32>::new_uninit();
+
+// Deferred initialization:
+Arc::get_mut(&mut five).unwrap().write(5);
+
+let five = unsafe { five.assume_init() };
+
+assert_eq!(*five, 5)new_uninit)Converts to Arc<[T]>.
As with MaybeUninit::assume_init,
+it is up to the caller to guarantee that the inner value
+really is in an initialized state.
+Calling this when the content is not yet fully initialized
+causes immediate undefined behavior.
#![feature(new_uninit)]
+#![feature(get_mut_unchecked)]
+
+use std::sync::Arc;
+
+let mut values = Arc::<[u32]>::new_uninit_slice(3);
+
+// Deferred initialization:
+let data = Arc::get_mut(&mut values).unwrap();
+data[0].write(1);
+data[1].write(2);
+data[2].write(3);
+
+let values = unsafe { values.assume_init() };
+
+assert_eq!(*values, [1, 2, 3])Constructs an Arc<T> from a raw pointer.
The raw pointer must have been previously returned by a call to
+Arc<U>::into_raw with the following requirements:
U is sized, it must have the same size and alignment as T. This
+is trivially true if U is T.U is unsized, its data pointer must have the same size and
+alignment as T. This is trivially true if Arc<U> was constructed
+through Arc<T> and then converted to Arc<U> through an unsized
+coercion.Note that if U or U’s data pointer is not T but has the same size
+and alignment, this is basically like transmuting references of
+different types. See mem::transmute for more information
+on what restrictions apply in this case.
The user of from_raw has to make sure a specific value of T is only
+dropped once.
This function is unsafe because improper use may lead to memory unsafety,
+even if the returned Arc<T> is never accessed.
use std::sync::Arc;
+
+let x = Arc::new("hello".to_owned());
+let x_ptr = Arc::into_raw(x);
+
+unsafe {
+ // Convert back to an `Arc` to prevent leak.
+ let x = Arc::from_raw(x_ptr);
+ assert_eq!(&*x, "hello");
+
+ // Further calls to `Arc::from_raw(x_ptr)` would be memory-unsafe.
+}
+
+// The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling!Convert a slice back into its original array:
+ +use std::sync::Arc;
+
+let x: Arc<[u32]> = Arc::new([1, 2, 3]);
+let x_ptr: *const [u32] = Arc::into_raw(x);
+
+unsafe {
+ let x: Arc<[u32; 3]> = Arc::from_raw(x_ptr.cast::<[u32; 3]>());
+ assert_eq!(&*x, &[1, 2, 3]);
+}Increments the strong reference count on the Arc<T> associated with the
+provided pointer by one.
The pointer must have been obtained through Arc::into_raw, and the
+associated Arc instance must be valid (i.e. the strong count must be at
+least 1) for the duration of this method.
use std::sync::Arc;
+
+let five = Arc::new(5);
+
+unsafe {
+ let ptr = Arc::into_raw(five);
+ Arc::increment_strong_count(ptr);
+
+ // This assertion is deterministic because we haven't shared
+ // the `Arc` between threads.
+ let five = Arc::from_raw(ptr);
+ assert_eq!(2, Arc::strong_count(&five));
+}Decrements the strong reference count on the Arc<T> associated with the
+provided pointer by one.
The pointer must have been obtained through Arc::into_raw, and the
+associated Arc instance must be valid (i.e. the strong count must be at
+least 1) when invoking this method. This method can be used to release the final
+Arc and backing storage, but should not be called after the final Arc has been
+released.
use std::sync::Arc;
+
+let five = Arc::new(5);
+
+unsafe {
+ let ptr = Arc::into_raw(five);
+ Arc::increment_strong_count(ptr);
+
+ // Those assertions are deterministic because we haven't shared
+ // the `Arc` between threads.
+ let five = Arc::from_raw(ptr);
+ assert_eq!(2, Arc::strong_count(&five));
+ Arc::decrement_strong_count(ptr);
+ assert_eq!(1, Arc::strong_count(&five));
+}Consumes the Arc, returning the wrapped pointer.
To avoid a memory leak the pointer must be converted back to an Arc using
+Arc::from_raw.
use std::sync::Arc;
+
+let x = Arc::new("hello".to_owned());
+let x_ptr = Arc::into_raw(x);
+assert_eq!(unsafe { &*x_ptr }, "hello");allocator_api)Consumes the Arc, returning the wrapped pointer and allocator.
To avoid a memory leak the pointer must be converted back to an Arc using
+Arc::from_raw_in.
#![feature(allocator_api)]
+use std::sync::Arc;
+use std::alloc::System;
+
+let x = Arc::new_in("hello".to_owned(), System);
+let (ptr, alloc) = Arc::into_raw_with_allocator(x);
+assert_eq!(unsafe { &*ptr }, "hello");
+let x = unsafe { Arc::from_raw_in(ptr, alloc) };
+assert_eq!(&*x, "hello");Provides a raw pointer to the data.
+The counts are not affected in any way and the Arc is not consumed. The pointer is valid for
+as long as there are strong counts in the Arc.
use std::sync::Arc;
+
+let x = Arc::new("hello".to_owned());
+let y = Arc::clone(&x);
+let x_ptr = Arc::as_ptr(&x);
+assert_eq!(x_ptr, Arc::as_ptr(&y));
+assert_eq!(unsafe { &*x_ptr }, "hello");allocator_api)Constructs an Arc<T, A> from a raw pointer.
The raw pointer must have been previously returned by a call to Arc<U, A>::into_raw with the following requirements:
U is sized, it must have the same size and alignment as T. This
+is trivially true if U is T.U is unsized, its data pointer must have the same size and
+alignment as T. This is trivially true if Arc<U> was constructed
+through Arc<T> and then converted to Arc<U> through an unsized
+coercion.Note that if U or U’s data pointer is not T but has the same size
+and alignment, this is basically like transmuting references of
+different types. See mem::transmute for more information
+on what restrictions apply in this case.
The raw pointer must point to a block of memory allocated by alloc
The user of from_raw has to make sure a specific value of T is only
+dropped once.
This function is unsafe because improper use may lead to memory unsafety,
+even if the returned Arc<T> is never accessed.
#![feature(allocator_api)]
+
+use std::sync::Arc;
+use std::alloc::System;
+
+let x = Arc::new_in("hello".to_owned(), System);
+let x_ptr = Arc::into_raw(x);
+
+unsafe {
+ // Convert back to an `Arc` to prevent leak.
+ let x = Arc::from_raw_in(x_ptr, System);
+ assert_eq!(&*x, "hello");
+
+ // Further calls to `Arc::from_raw(x_ptr)` would be memory-unsafe.
+}
+
+// The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling!Convert a slice back into its original array:
+ +#![feature(allocator_api)]
+
+use std::sync::Arc;
+use std::alloc::System;
+
+let x: Arc<[u32], _> = Arc::new_in([1, 2, 3], System);
+let x_ptr: *const [u32] = Arc::into_raw(x);
+
+unsafe {
+ let x: Arc<[u32; 3], _> = Arc::from_raw_in(x_ptr.cast::<[u32; 3]>(), System);
+ assert_eq!(&*x, &[1, 2, 3]);
+}Gets the number of Weak pointers to this allocation.
This method by itself is safe, but using it correctly requires extra care. +Another thread can change the weak count at any time, +including potentially between calling this method and acting on the result.
+use std::sync::Arc;
+
+let five = Arc::new(5);
+let _weak_five = Arc::downgrade(&five);
+
+// This assertion is deterministic because we haven't shared
+// the `Arc` or `Weak` between threads.
+assert_eq!(1, Arc::weak_count(&five));Gets the number of strong (Arc) pointers to this allocation.
This method by itself is safe, but using it correctly requires extra care. +Another thread can change the strong count at any time, +including potentially between calling this method and acting on the result.
+use std::sync::Arc;
+
+let five = Arc::new(5);
+let _also_five = Arc::clone(&five);
+
+// This assertion is deterministic because we haven't shared
+// the `Arc` between threads.
+assert_eq!(2, Arc::strong_count(&five));allocator_api)Increments the strong reference count on the Arc<T> associated with the
+provided pointer by one.
The pointer must have been obtained through Arc::into_raw, and the
+associated Arc instance must be valid (i.e. the strong count must be at
+least 1) for the duration of this method,, and ptr must point to a block of memory
+allocated by alloc.
#![feature(allocator_api)]
+
+use std::sync::Arc;
+use std::alloc::System;
+
+let five = Arc::new_in(5, System);
+
+unsafe {
+ let ptr = Arc::into_raw(five);
+ Arc::increment_strong_count_in(ptr, System);
+
+ // This assertion is deterministic because we haven't shared
+ // the `Arc` between threads.
+ let five = Arc::from_raw_in(ptr, System);
+ assert_eq!(2, Arc::strong_count(&five));
+}allocator_api)Decrements the strong reference count on the Arc<T> associated with the
+provided pointer by one.
The pointer must have been obtained through Arc::into_raw, the
+associated Arc instance must be valid (i.e. the strong count must be at
+least 1) when invoking this method, and ptr must point to a block of memory
+allocated by alloc. This method can be used to release the final
+Arc and backing storage, but should not be called after the final Arc has been
+released.
#![feature(allocator_api)]
+
+use std::sync::Arc;
+use std::alloc::System;
+
+let five = Arc::new_in(5, System);
+
+unsafe {
+ let ptr = Arc::into_raw(five);
+ Arc::increment_strong_count_in(ptr, System);
+
+ // Those assertions are deterministic because we haven't shared
+ // the `Arc` between threads.
+ let five = Arc::from_raw_in(ptr, System);
+ assert_eq!(2, Arc::strong_count(&five));
+ Arc::decrement_strong_count_in(ptr, System);
+ assert_eq!(1, Arc::strong_count(&five));
+}Returns true if the two Arcs point to the same allocation in a vein similar to
+ptr::eq. This function ignores the metadata of dyn Trait pointers.
use std::sync::Arc;
+
+let five = Arc::new(5);
+let same_five = Arc::clone(&five);
+let other_five = Arc::new(5);
+
+assert!(Arc::ptr_eq(&five, &same_five));
+assert!(!Arc::ptr_eq(&five, &other_five));Makes a mutable reference into the given Arc.
If there are other Arc pointers to the same allocation, then make_mut will
+clone the inner value to a new allocation to ensure unique ownership. This is also
+referred to as clone-on-write.
However, if there are no other Arc pointers to this allocation, but some Weak
+pointers, then the Weak pointers will be dissociated and the inner value will not
+be cloned.
See also get_mut, which will fail rather than cloning the inner value
+or dissociating Weak pointers.
use std::sync::Arc;
+
+let mut data = Arc::new(5);
+
+*Arc::make_mut(&mut data) += 1; // Won't clone anything
+let mut other_data = Arc::clone(&data); // Won't clone inner data
+*Arc::make_mut(&mut data) += 1; // Clones inner data
+*Arc::make_mut(&mut data) += 1; // Won't clone anything
+*Arc::make_mut(&mut other_data) *= 2; // Won't clone anything
+
+// Now `data` and `other_data` point to different allocations.
+assert_eq!(*data, 8);
+assert_eq!(*other_data, 12);Weak pointers will be dissociated:
use std::sync::Arc;
+
+let mut data = Arc::new(75);
+let weak = Arc::downgrade(&data);
+
+assert!(75 == *data);
+assert!(75 == *weak.upgrade().unwrap());
+
+*Arc::make_mut(&mut data) += 1;
+
+assert!(76 == *data);
+assert!(weak.upgrade().is_none());If we have the only reference to T then unwrap it. Otherwise, clone T and return the
+clone.
Assuming arc_t is of type Arc<T>, this function is functionally equivalent to
+(*arc_t).clone(), but will avoid cloning the inner value where possible.
let inner = String::from("test");
+let ptr = inner.as_ptr();
+
+let arc = Arc::new(inner);
+let inner = Arc::unwrap_or_clone(arc);
+// The inner value was not cloned
+assert!(ptr::eq(ptr, inner.as_ptr()));
+
+let arc = Arc::new(inner);
+let arc2 = arc.clone();
+let inner = Arc::unwrap_or_clone(arc);
+// Because there were 2 references, we had to clone the inner value.
+assert!(!ptr::eq(ptr, inner.as_ptr()));
+// `arc2` is the last reference, so when we unwrap it we get back
+// the original `String`.
+let inner = Arc::unwrap_or_clone(arc2);
+assert!(ptr::eq(ptr, inner.as_ptr()));Returns a mutable reference into the given Arc, if there are
+no other Arc or Weak pointers to the same allocation.
Returns None otherwise, because it is not safe to
+mutate a shared value.
See also make_mut, which will clone
+the inner value when there are other Arc pointers.
use std::sync::Arc;
+
+let mut x = Arc::new(3);
+*Arc::get_mut(&mut x).unwrap() = 4;
+assert_eq!(*x, 4);
+
+let _y = Arc::clone(&x);
+assert!(Arc::get_mut(&mut x).is_none());get_mut_unchecked)Returns a mutable reference into the given Arc,
+without any check.
See also get_mut, which is safe and does appropriate checks.
If any other Arc or Weak pointers to the same allocation exist, then
+they must not be dereferenced or have active borrows for the duration
+of the returned borrow, and their inner type must be exactly the same as the
+inner type of this Rc (including lifetimes). This is trivially the case if no
+such pointers exist, for example immediately after Arc::new.
#![feature(get_mut_unchecked)]
+
+use std::sync::Arc;
+
+let mut x = Arc::new(String::new());
+unsafe {
+ Arc::get_mut_unchecked(&mut x).push_str("foo")
+}
+assert_eq!(*x, "foo");Other Arc pointers to the same allocation must be to the same type.
#![feature(get_mut_unchecked)]
+
+use std::sync::Arc;
+
+let x: Arc<str> = Arc::from("Hello, world!");
+let mut y: Arc<[u8]> = x.clone().into();
+unsafe {
+ // this is Undefined Behavior, because x's inner type is str, not [u8]
+ Arc::get_mut_unchecked(&mut y).fill(0xff); // 0xff is invalid in UTF-8
+}
+println!("{}", &*x); // Invalid UTF-8 in a strOther Arc pointers to the same allocation must be to the exact same type, including lifetimes.
#![feature(get_mut_unchecked)]
+
+use std::sync::Arc;
+
+let x: Arc<&str> = Arc::new("Hello, world!");
+{
+ let s = String::from("Oh, no!");
+ let mut y: Arc<&str> = x.clone().into();
+ unsafe {
+ // this is Undefined Behavior, because x's inner type
+ // is &'long str, not &'short str
+ *Arc::get_mut_unchecked(&mut y) = &s;
+ }
+}
+println!("{}", &*x); // Use-after-freeAttempt to downcast the Arc<dyn Any + Send + Sync> to a concrete type.
use std::any::Any;
+use std::sync::Arc;
+
+fn print_if_string(value: Arc<dyn Any + Send + Sync>) {
+ if let Ok(string) = value.downcast::<String>() {
+ println!("String ({}): {}", string.len(), string);
+ }
+}
+
+let my_string = "Hello World".to_string();
+print_if_string(Arc::new(my_string));
+print_if_string(Arc::new(0i8));downcast_unchecked)Downcasts the Arc<dyn Any + Send + Sync> to a concrete type.
For a safe alternative see downcast.
#![feature(downcast_unchecked)]
+
+use std::any::Any;
+use std::sync::Arc;
+
+let x: Arc<dyn Any + Send + Sync> = Arc::new(1_usize);
+
+unsafe {
+ assert_eq!(*x.downcast_unchecked::<usize>(), 1);
+}The contained value must be of type T. Calling this method
+with the incorrect type is undefined behavior.
Self from the given unstructured data. Read moreSelf from the given unstructured data. Read moreUnstructured this type
+needs to construct itself. Read moreSelf from the entirety of the given
+unstructured data. Read moreSelf from the given unstructured data. Read moreUnstructured this type
+needs to construct itself. Read moreSelf from the entirety of the given
+unstructured data. Read moreThis impl allows implementing traits that require AsFd on Arc.
use std::net::UdpSocket;
+use std::sync::Arc;
+
+trait MyTrait: AsFd {}
+impl MyTrait for Arc<UdpSocket> {}
+impl MyTrait for Box<UdpSocket> {}This impl allows implementing traits that require AsRawFd on Arc.
use std::net::UdpSocket;
+use std::sync::Arc;
+trait MyTrait: AsRawFd {
+}
+impl MyTrait for Arc<UdpSocket> {}
+impl MyTrait for Box<UdpSocket> {}Makes a clone of the Arc pointer.
This creates another pointer to the same allocation, increasing the +strong reference count.
+use std::sync::Arc;
+
+let five = Arc::new(5);
+
+let _ = Arc::clone(&five);source. Read moreRecord) Read moreis_enabledis_enabledis_enabledis_enabledis_enabledis_enabledDrain Read moreDrain (by level) Read moreDrops the Arc.
This will decrement the strong reference count. If the strong reference
+count reaches zero then the only other references (if any) are
+Weak, so we drop the inner value.
use std::sync::Arc;
+
+struct Foo;
+
+impl Drop for Foo {
+ fn drop(&mut self) {
+ println!("dropped!");
+ }
+}
+
+let foo = Arc::new(Foo);
+let foo2 = Arc::clone(&foo);
+
+drop(foo); // Doesn't print anything
+drop(foo2); // Prints "dropped!"Takes each element in the Iterator and collects it into an Arc<[T]>.
In the general case, collecting into Arc<[T]> is done by first
+collecting into a Vec<T>. That is, when writing the following:
let evens: Arc<[u8]> = (0..10).filter(|&x| x % 2 == 0).collect();this behaves as if we wrote:
+ +let evens: Arc<[u8]> = (0..10).filter(|&x| x % 2 == 0)
+ .collect::<Vec<_>>() // The first set of allocations happens here.
+ .into(); // A second allocation for `Arc<[T]>` happens here.This will allocate as many times as needed for constructing the Vec<T>
+and then it will allocate once for turning the Vec<T> into the Arc<[T]>.
When your Iterator implements TrustedLen and is of an exact size,
+a single allocation will be made for the Arc<[T]>. For example:
let evens: Arc<[u8]> = (0..10).collect(); // Just a single allocation happens here.None in case the
+identifier is not known yet (e.g. the client has not yet been initialized).Comparison for two Arcs.
The two are compared by calling cmp() on their inner values.
use std::sync::Arc;
+use std::cmp::Ordering;
+
+let five = Arc::new(5);
+
+assert_eq!(Ordering::Less, five.cmp(&Arc::new(6)));Equality for two Arcs.
Two Arcs are equal if their inner values are equal, even if they are
+stored in different allocation.
If T also implements Eq (implying reflexivity of equality),
+two Arcs that point to the same allocation are always equal.
use std::sync::Arc;
+
+let five = Arc::new(5);
+
+assert!(five == Arc::new(5));Inequality for two Arcs.
Two Arcs are not equal if their inner values are not equal.
If T also implements Eq (implying reflexivity of equality),
+two Arcs that point to the same value are always equal.
use std::sync::Arc;
+
+let five = Arc::new(5);
+
+assert!(five != Arc::new(6));Partial comparison for two Arcs.
The two are compared by calling partial_cmp() on their inner values.
use std::sync::Arc;
+use std::cmp::Ordering;
+
+let five = Arc::new(5);
+
+assert_eq!(Some(Ordering::Less), five.partial_cmp(&Arc::new(6)));Less-than comparison for two Arcs.
The two are compared by calling < on their inner values.
use std::sync::Arc;
+
+let five = Arc::new(5);
+
+assert!(five < Arc::new(6));‘Less than or equal to’ comparison for two Arcs.
The two are compared by calling <= on their inner values.
use std::sync::Arc;
+
+let five = Arc::new(5);
+
+assert!(five <= Arc::new(5));read, except that it reads into a slice of buffers. Read moreread_buf)can_vector)buf. Read morebuf. Read morebuf. Read moreread_buf)cursor. Read moreRead. Read moreseek_stream_len)can_vector)write_all_vectored)clone_to_uninit)key and return true if they are equal.() to
+completion. Read moreread_f32_into instead() to
+completion. Read moreself into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub struct TrustRoot {
+ pub height: u64,
+ pub hash: String,
+ pub runtime_id: Namespace,
+ pub chain_context: String,
+}Consensus layer trust root.
+height: u64Known trusted height.
+hash: StringKnown hex-encoded trusted consensus layer header hash.
+runtime_id: NamespaceKnown runtime identifier.
+chain_context: StringKnown consensus chain context.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct Version {
+ pub major: u16,
+ pub minor: u16,
+ pub patch: u16,
+}A protocol or runtime version.
+major: u16§minor: u16§patch: u16try_default in case the value is null or
+undefined.clone_to_uninit)clone_to_uninit)key and return true if they are equal.pub type Result<T, E = Error> = Result<T, E>;Result<T, Error>
This is a reasonable return type to use throughout your application but also
+for fn main; if you do, failures will be printed along with any
+context and a backtrace if one was captured.
anyhow::Result may be used with one or two type parameters.
use anyhow::Result;
+
+fn demo1() -> Result<T> {...}
+ // ^ equivalent to std::result::Result<T, anyhow::Error>
+
+fn demo2() -> Result<T, OtherError> {...}
+ // ^ equivalent to std::result::Result<T, OtherError>use anyhow::Result;
+
+fn main() -> Result<()> {
+ let config = std::fs::read_to_string("cluster.json")?;
+ let map: ClusterMap = serde_json::from_str(&config)?;
+ println!("cluster info: {:#?}", map);
+ Ok(())
+}enum Result<T, E = Error> {
+ Ok(T),
+ Err(E),
+}pub struct Client<A: App> { /* private fields */ }A runtime client meant for use within runtimes.
+Retrieve the latest known runtime round.
+Retrieve the nonce for the given account.
+Retrieve the gas price in the given denomination.
+Securely query the on-chain runtime component.
+Securely perform gas estimation.
+Sign a given transaction, submit it and wait for block inclusion.
+This method supports multiple transaction signers.
+Sign a given transaction, submit it and wait for block inclusion.
+This method supports multiple transaction signers.
+Sign a given transaction, submit it and wait for block inclusion.
+Run a closure inside a CurrentState context with store for the given round.
Return a store corresponding to the given round.
+clone_to_uninit)pub struct Environment<A: App> { /* private fields */ }Application environment.
+clone_to_uninit)pub trait App: Send + Sync + 'static {
+ const VERSION: Version;
+
+ // Required methods
+ fn id() -> AppId;
+ fn consensus_trust_root() -> Option<TrustRoot>;
+
+ // Provided methods
+ fn new_transaction<B>(&self, method: &str, body: B) -> Transaction
+ where B: Encode { ... }
+ fn run<'async_trait>(
+ self: Arc<Self>,
+ env: Environment<Self>,
+ ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
+ where Self: Sized + 'async_trait { ... }
+ fn on_runtime_block<'async_trait>(
+ self: Arc<Self>,
+ env: Environment<Self>,
+ round: u64,
+ ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
+ where Self: Sized + 'async_trait { ... }
+ fn start(self)
+ where Self: Sized { ... }
+}ROFL component application.
+Return the consensus layer trust root for this runtime; if None, consensus layer integrity
+verification will not be performed.
Create a new unsigned transaction.
+Main application processing loop.
+pub const APP_ID_BECH32_HRP: Hrp;Human readable part for Bech32-encoded application identifier.
+pub enum Error {
+ MalformedIdentifier,
+}Error.
+pub struct AppId(/* private fields */);ROFL application identifier.
+The application identifier is similar to an address, but using its own separate namespace and +derivation scheme as it is not meant to be used as an address.
+Creates a new v0 application identifier from a global name.
+Creates a new v0 application identifier from creator/round/index tuple.
+Creates a new v0 application identifier from creator/nonce tuple.
+Tries to create a new identifier from raw bytes.
+Convert the identifier into raw bytes.
+Tries to create a new identifier from Bech32-encoded string.
+try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)clone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)Redirecting to ../../../../oasis_runtime_sdk/modules/rofl/trait.Config.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_runtime_sdk/modules/rofl/enum.Error.html b/rust/oasis_runtime_sdk/modules/rofl/enum.Error.html new file mode 100644 index 0000000000..9f5545b88f --- /dev/null +++ b/rust/oasis_runtime_sdk/modules/rofl/enum.Error.html @@ -0,0 +1,39 @@ +pub enum Error {
+}Errors emitted by the module.
+Ok(err) (where err is a dispatcher error) when batch
+should abort or Err(self) when this is just a regular error.pub enum Event {
+ AppCreated {
+ id: AppId,
+ },
+ AppUpdated {
+ id: AppId,
+ },
+ AppRemoved {
+ id: AppId,
+ },
+}Events emitted by the ROFL module.
+pub enum ParameterValidationError {}Errors emitted during parameter validation.
+Redirecting to ../../../../oasis_runtime_sdk/modules/rofl/enum.Error.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_runtime_sdk/modules/rofl/event/enum.Event.html b/rust/oasis_runtime_sdk/modules/rofl/event/enum.Event.html new file mode 100644 index 0000000000..6ba4e5cbcc --- /dev/null +++ b/rust/oasis_runtime_sdk/modules/rofl/event/enum.Event.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../../oasis_runtime_sdk/modules/rofl/enum.Event.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_runtime_sdk/modules/rofl/index.html b/rust/oasis_runtime_sdk/modules/rofl/index.html new file mode 100644 index 0000000000..5532fa0c8b --- /dev/null +++ b/rust/oasis_runtime_sdk/modules/rofl/index.html @@ -0,0 +1,2 @@ +On-chain coordination for ROFL components.
+pub enum AllowedEndorsement {
+ Any,
+ ComputeRole,
+ ObserverRole,
+ Entity(PublicKey),
+ Node(PublicKey),
+}An allowed endorsement policy.
+Any node can endorse the enclave.
+Compute node for the current runtime can endorse the enclave.
+Observer node for the current runtime can endorse the enclave.
+Registered node from a specific entity can endorse the enclave.
+Specific node can endorse the enclave.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.#[repr(u8)]pub enum FeePolicy {
+ InstancePays = 1,
+ EndorsingNodePays = 2,
+}Gas fee payment policy.
+Application enclave pays the gas fees.
+Endorsing node pays the gas fees.
+try_default in case the value is null or
+undefined.clone_to_uninit)key and return true if they are equal.pub struct AppAuthPolicy {
+ pub quotes: QuotePolicy,
+ pub enclaves: Vec<EnclaveIdentity>,
+ pub endorsements: Vec<AllowedEndorsement>,
+ pub fees: FeePolicy,
+ pub max_expiration: EpochTime,
+}Per-application ROFL policy.
+quotes: QuotePolicyQuote policy.
+enclaves: Vec<EnclaveIdentity>The set of allowed enclave identities.
+endorsements: Vec<AllowedEndorsement>The set of allowed endorsements.
+fees: FeePolicyGas fee payment policy.
+max_expiration: EpochTimeMaximum number of future epochs for which one can register.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub fn expire_registrations(epoch: EpochTime, limit: usize)Removes all expired registrations, e.g. those that expire in epochs earlier than or equal to the +passed epoch.
+pub fn get_endorser(pk: &PublicKey) -> Option<KeyEndorsementInfo>Retrieves endorser of the given ROFL enclave. In case enclave is not registered, returns None.
pub fn get_registration(app_id: AppId, rak: &PublicKey) -> Option<Registration>Retrieves registration of the given ROFL enclave. In case enclave is not registered, returns
+None.
pub fn get_registrations_for_app(app_id: AppId) -> Vec<Registration>Retrieves all registrations for the given ROFL application.
+pub fn remove_app(app_id: AppId)Removes an application configuration.
+pub fn remove_registration(app_id: AppId, rak: &PublicKey)Removes an existing registration of the given ROFL enclave.
+pub fn update_registration(registration: Registration) -> Result<(), Error>Updates registration of the given ROFL enclave.
+None.None.pub struct KeyEndorsementInfo {
+ pub node_id: PublicKey,
+ pub rak: Option<PublicKey>,
+}Information about an endorsed key.
+node_id: PublicKeyIdentifier of node that endorsed the enclave.
+rak: Option<PublicKey>RAK of the enclave that endorsed the key. This is only set for endorsements of extra keys.
+Create a new key endorsement information for RAK endorsed by given node directly.
+Create a new key endorsement information for extra key endorsed by RAK.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub static ADDRESS_APP_STAKE_POOL: Lazy<Address>Module’s address that has the application stake pool.
+oasis1qza6sddnalgzexk3ct30gqfvntgth5m4hsyywmff
+pub struct Genesis {
+ pub parameters: Parameters,
+ pub apps: Vec<AppConfig>,
+}Genesis state for the module.
+parameters: Parameters§apps: Vec<AppConfig>Application configurations.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct Module<Cfg: Config> { /* private fields */ }None is returned. Read moreNone is returned. Read moreNone
+should be returned.Self is a tuple).pub struct Parameters {}Parameters for the module.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub trait API {
+ // Required methods
+ fn get_origin_rak() -> Option<PublicKey>;
+ fn get_origin_registration(app: AppId) -> Option<Registration>;
+ fn is_authorized_origin(app: AppId) -> bool;
+ fn get_registration(
+ app: AppId,
+ rak: PublicKey,
+ ) -> Result<Registration, Error>;
+ fn get_app(id: AppId) -> Result<AppConfig, Error>;
+ fn get_instances(id: AppId) -> Result<Vec<Registration>, Error>;
+}Interface that can be called from other modules.
+Get the Runtime Attestation Key of the ROFL app instance in case the origin transaction is
+signed by a ROFL instance. Otherwise None is returned.
This method will panic if called outside a transaction environment.
+Get the registration descriptor of the ROFL app instance in case the origin transaction is
+signed by a ROFL instance of the specified app. Otherwise None is returned.
This method will panic if called outside a transaction environment.
+Verify whether the origin transaction is signed by an authorized ROFL instance for the given +application.
+This method will panic if called outside a transaction environment.
+Get a specific registered instance for an application.
+Get all registered instances for an application.
+pub trait Config: 'static {
+ const GAS_COST_CALL_CREATE: u64 = 100_000u64;
+ const GAS_COST_CALL_UPDATE: u64 = 100_000u64;
+ const GAS_COST_CALL_REMOVE: u64 = 10_000u64;
+ const GAS_COST_CALL_REGISTER: u64 = 100_000u64;
+ const GAS_COST_CALL_IS_AUTHORIZED_ORIGIN: u64 = 1_000u64;
+ const GAS_COST_CALL_AUTHORIZED_ORIGIN_NODE: u64 = 2_000u64;
+ const GAS_COST_CALL_AUTHORIZED_ORIGIN_ENTITY: u64 = 2_000u64;
+ const GAS_COST_CALL_STAKE_THRESHOLDS: u64 = 10u64;
+ const STAKE_APP_CREATE: BaseUnits = _;
+}Module configuration.
+Gas cost of rofl.Create call.
+Gas cost of rofl.Update call.
+Gas cost of rofl.Remove call.
+Gas cost of rofl.Register call.
+Gas cost of rofl.IsAuthorizedOrigin call.
+Gas cost of rofl.AuthorizedOriginNode call.
+Gas cost of rofl.AuthorizedOriginEntity call.
+Gas cost of rofl.StakeThresholds call.
+Amount of stake required for maintaining an application.
+The stake is held in escrow and is returned to the administrator when the application is +removed.
+#[repr(u8)]pub enum IdentifierScheme {
+ CreatorRoundIndex = 0,
+ CreatorNonce = 1,
+}ROFL application identifier generation scheme.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)clone_to_uninit)pub struct AppConfig {
+ pub id: AppId,
+ pub policy: AppAuthPolicy,
+ pub admin: Option<Address>,
+ pub stake: BaseUnits,
+}ROFL application configuration.
+id: AppIdROFL application identifier.
+policy: AppAuthPolicyAuthentication policy.
+admin: Option<Address>Application administrator address.
+stake: BaseUnitsStaked amount.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct AppInstanceQuery {
+ pub app: AppId,
+ pub rak: PublicKey,
+}Application instance query.
+app: AppIdROFL application identifier.
+rak: PublicKeyRuntime Attestation Key.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct AppQuery {
+ pub id: AppId,
+}Application-related query.
+id: AppIdROFL application identifier.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct Create {
+ pub policy: AppAuthPolicy,
+ pub scheme: IdentifierScheme,
+}Create new ROFL application call.
+policy: AppAuthPolicyApplication authentication policy.
+scheme: IdentifierSchemeIdentifier generation scheme.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct Register {
+ pub app: AppId,
+ pub ect: EndorsedCapabilityTEE,
+ pub expiration: EpochTime,
+ pub extra_keys: Vec<PublicKey>,
+}Register ROFL call.
+app: AppIdROFL application identifier.
+ect: EndorsedCapabilityTEEEndorsed TEE capability.
+expiration: EpochTimeEpoch when the ROFL registration expires if not renewed.
+extra_keys: Vec<PublicKey>Extra public keys to endorse (e.g. secp256k1 keys).
+All of these keys need to co-sign the registration transaction to prove ownership.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct Registration {
+ pub app: AppId,
+ pub node_id: PublicKey,
+ pub entity_id: Option<PublicKey>,
+ pub rak: PublicKey,
+ pub rek: PublicKey,
+ pub expiration: EpochTime,
+ pub extra_keys: Vec<PublicKey>,
+}ROFL registration descriptor.
+app: AppIdApplication this enclave is registered for.
+node_id: PublicKeyIdentifier of the endorsing node.
+entity_id: Option<PublicKey>Optional identifier of the endorsing entity.
+rak: PublicKeyRuntime Attestation Key.
+rek: PublicKeyRuntime Encryption Key.
+expiration: EpochTimeEpoch when the ROFL registration expires if not renewed.
+extra_keys: Vec<PublicKey>Extra public keys to endorse (e.g. secp256k1 keys).
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct Remove {
+ pub id: AppId,
+}Remove an existing ROFL application call.
+id: AppIdROFL application identifier.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct StakeThresholds {
+ pub app_create: BaseUnits,
+}Stake thresholds for managing ROFL.
+app_create: BaseUnitsRequired stake for creating new ROFL application.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Update {
+ pub id: AppId,
+ pub policy: AppAuthPolicy,
+ pub admin: Option<Address>,
+}Update an existing ROFL application call.
+id: AppIdROFL application identifier.
+policy: AppAuthPolicyAuthentication policy.
+admin: Option<Address>Application administrator address.
+try_default in case the value is null or
+undefined.clone_to_uninit)Runtime.
+pub trait Runtime {
+ type Core: API;
+ type Accounts: API;
+ type Modules: TransactionHandler + MigrationHandler + MethodHandler + BlockHandler + InvariantHandler + ModuleInfoHandler;
+ type FeeProxy: FeeProxyHandler = ();
+
+ const VERSION: Version;
+ const STATE_VERSION: u32 = 0u32;
+ const PREFETCH_LIMIT: u16 = 0u16;
+ const SCHEDULE_CONTROL: ScheduleControl = _;
+
+ // Required method
+ fn genesis_state() -> <Self::Modules as MigrationHandler>::Genesis;
+
+ // Provided methods
+ fn trusted_signers() -> Option<TrustedSigners> { ... }
+ fn consensus_trust_root() -> Option<TrustRoot> { ... }
+ fn migrate_state<C: Context>(_ctx: &C) { ... }
+ fn is_allowed_query(_method: &str) -> bool { ... }
+ fn is_allowed_private_km_query(_method: &str) -> bool { ... }
+ fn is_allowed_interactive_call(_method: &str) -> bool { ... }
+ fn migrate<C: Context>(ctx: &C) { ... }
+ fn start()
+ where Self: Sized + Send + Sync + 'static { ... }
+}A runtime.
+Supported modules.
+Handler for proxy fee payments.
+State version.
+Prefetch limit. To enable prefetch set it to a non-zero value.
+Runtime schedule control configuration.
+Genesis state for the runtime.
+Return the trusted signers for this runtime; if None, a key manager connection will not be
+established on startup.
Return the consensus layer trust root for this runtime; if None, consensus layer integrity
+verification will not be performed.
Perform runtime-specific state migration. This method is only called when the recorded
+state version does not match STATE_VERSION.
Whether a given query method is allowed to be invoked.
+Whether a given query method is allowed to access private key manager state.
+Note that even if this returns true for a method, the method also needs to be tagged as
+being allowed to access private key manager state (e.g. with allow_private_km).
Whether a given call is allowed to be invoked interactively.
+Note that even if this returns true for a method, the method also needs to be tagged as
+being allowed to be executed interactively (e.g. with allow_interactive)
pub enum Error {
+ FailedToFetchBatch,
+}Schedule control errors.
+Ok(err) (where err is a dispatcher error) when batch
+should abort or Err(self) when this is just a regular error.Types related to schedule control.
+pub trait ScheduleControlHost: Send + Sync {
+ // Required method
+ fn fetch_tx_batch(
+ &self,
+ offset: Option<Hash>,
+ limit: u32,
+ ) -> Result<Option<TxnBatch>, Error>;
+}Interface to the runtime host that supports schedule control features.
+Fetch the specified set of transactions from the host’s transaction queue.
+Offset specifies the transaction hash that should serve as an offset when returning +transactions from the pool. Transactions will be skipped until the given hash is encountered +and only following transactions will be returned.
+Transaction sender metadata.
+pub struct SenderMeta {
+ pub address: Address,
+ pub tx_nonce: u64,
+ pub state_nonce: u64,
+}Transaction sender metadata.
+address: AddressSender address.
+tx_nonce: u64Sender nonce contained in the transaction.
+state_nonce: u64Sender nonce contained in runtime state.
+source. Read moreself and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.#[repr(u8)]pub enum Mode {
+ Execute = 0,
+ Check = 1,
+ Simulate = 2,
+ PreSchedule = 3,
+}Execution mode.
+Actually execute transactions during block production.
+Check that transactions are valid for local acceptance into the transaction pool.
+Simulate transaction outcomes (e.g. for gas estimation).
+Check that transactions are still valid before scheduling.
+clone_to_uninit)clone_to_uninit)key and return true if they are equal.pub enum TransactionResult<T> {
+ Commit(T),
+ Rollback(T),
+}Result of a transaction helper closure.
+pub struct CurrentState;State attached to the current thread.
+Attach a new state to the current thread and enter the state’s context.
+The passed store is used as the root store.
+This method will panic if called from within a CurrentState::with block.
Attach a new state to the current thread and enter the state’s context.
+The passed store is used as the root store.
+This method will panic if called from within a CurrentState::with block or if the mode
+has not been explicitly set in opts.
Run a closure with the currently active state.
+This method will panic if called outside CurrentState::enter or if any transaction methods
+are called from the closure.
Run a closure with the store of the currently active state.
+This method will panic if called outside CurrentState::enter or if any transaction methods
+are called from the closure.
Run a closure with the environment of the currently active state.
+This method will panic if called outside CurrentState::enter or if any transaction methods
+are called from the closure.
Run a closure with the origin environment of the currently active state.
+This method will panic if called outside CurrentState::enter or if any transaction methods
+are called from the closure.
Start a new transaction by opening a new child state.
+This method will panic if called outside CurrentState::enter or if called within a
+CurrentState::with block.
Commit a previously started transaction.
+This method will panic if called outside CurrentState::enter, if there is no currently
+open transaction (started via CurrentState::start_transaction) or if called within a
+CurrentState::with block.
Rollback a previously started transaction.
+This method will panic if called outside CurrentState::enter, if there is no currently
+open transaction (started via CurrentState::start_transaction) or if called within a
+CurrentState::with block.
Run a closure within a state transaction.
+If the closure returns TransactionResult::Commit(R) then the child state is committed,
+otherwise the child state is rolled back.
Run a closure within a state transaction, allowing the caller to customize state.
+If the closure returns TransactionResult::Commit(R) then the child state is committed,
+otherwise the child state is rolled back.
pub struct Environment { /* private fields */ }Information about the execution environment.
+Whether the execution mode is such that only checks should be performed.
+Whether the execution mode is Mode::PreSchedule.
Whether the execution mode is Mode::Simulate.
Whether the execution mode is Mode::Execute.
Whether there is an active transaction in the current environment.
+An active transaction’s index (order) within the block.
+This method will panic if called outside a transaction environment.
+An active transaction’s size in bytes.
+This method will panic if called outside a transaction environment.
+An active transaction’s authentication information.
+This method will panic if called outside a transaction environment.
+An active transaction’s call format.
+This method will panic if called outside a transaction environment.
+An active transaction’s read only flag.
+This method will panic if called outside a transaction environment.
+Whether the current execution environment is part of an internal subcall.
+Authenticated address of the caller.
+In case there are multiple signers of a transaction, this will return the address +corresponding to the first signer. If there are no signers, it returns the default address.
+This method will panic if called outside a transaction environment.
+Authenticated caller public key if available.
+In case there are multiple signers of a transaction, this will return the public key
+corresponding to the first signer. If there are no signers or if the address specification
+does not represent a single public key, it returns None.
This method will panic if called outside a transaction environment.
+source. Read moreclone_to_uninit)pub struct Options {
+ pub mode: Option<Mode>,
+ pub tx: Option<TransactionWithMeta>,
+ pub internal: Option<bool>,
+ pub rng_local_entropy: bool,
+}Environment modification options.
+mode: Option<Mode>§tx: Option<TransactionWithMeta>§internal: Option<bool>§rng_local_entropy: boolChange the active transaction of the environment.
+Change the internal flag of the environment.
+Request for local entropy to be mixed into the current RNG.
+Using this method will result in non-deterministic behavior as the node’s local entropy is +mixed into the RNG. As such, this method should only be used in cases where non-determinism +is not problematic (e.g. local queries).
+clone_to_uninit)pub struct State { /* private fields */ }Mutable block state of a runtime.
+The state includes storage, emitted events, messages to consensus layer, etc. States can be
+nested via open, commit and rollback methods which behave like transactions.
Commit the current state and return to its parent state.
+This method will panic when attempting to commit the root state.
+Rollback the current state and return to its parent state.
+This method will panic when attempting to rollback the root state.
+Fetches a block state value entry.
+Block values live as long as the root State and are propagated to child states. They are
+not affected by state rollbacks. If you need state-scoped values, use local values.
Fetches a local state value entry.
+Local values only live as long as the current State, are dropped upon exiting to parent
+state and child states start with an empty set. If you need longer-lived values, use block
+values.
Hides block values from the current state which will have an empty set of values after this +method returns. Hidden values will be restored upon exit to parent state.
+Emitted messages count returns the number of messages emitted so far across this and all +parent states.
+Emitted messages count returns the number of messages emitted so far in this state, not +counting any parent states.
+Maximum number of messages that can be emitted.
+Queue a message to be emitted by the runtime for consensus layer to process.
+Take all messages accumulated in the current state.
+Emit an event.
+Emit a raw event.
+Emit an unconditional event.
+The only difference to regular events is that these are handled as a separate set.
+Take all regular events accumulated in the current state.
+Take all unconditional events accumulated in the current state.
+Take all events accumulated in the current state and return the merged set.
+Whether the store associated with the state has any pending updates.
+Size (in bytes) of any pending updates in the associated store.
+Environment information.
+Origin environment information.
+The origin environment is the first non-internal environment in the hierarchy.
+pub struct StateValue<'a, V> { /* private fields */ }A per-state arbitrary value.
+Gets a reference to the specified per-state value.
+Panics if the retrieved type is not the type that was stored.
+Gets a mutable reference to the specified per-state value.
+Panics if the retrieved type is not the type that was stored.
+Retrieves the existing value or inserts and returns the default.
+Panics if the retrieved type is not the type that was stored.
+pub struct TransactionWithMeta {
+ pub data: Transaction,
+ pub size: u32,
+ pub index: usize,
+ pub hash: Hash,
+}Decoded transaction with additional metadata.
+data: TransactionDecoded transaction.
+size: u32Transaction size.
+index: usizeTransaction index within the batch.
+hash: HashTransaction hash.
+Create transaction with metadata for an internally generated transaction.
+Internally generated transactions have zero size, index and hash.
+source. Read moreclone_to_uninit)pub const KEY_SIZE: usize = 32; // 32usizeSize of the Deoxys-II-256-128 key in bytes.
+pub enum Error {
+ CorruptKey,
+ CorruptValue,
+ DecryptionFailure(Error),
+}Errors emitted by the confidential store.
+pub struct ConfidentialStore<S: Store> { /* private fields */ }A key-value store that encrypts all content with DeoxysII.
+Create a new confidential store with the given keypair.
+Redirecting to ../../../oasis_runtime_sdk/storage/struct.HashedStore.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_runtime_sdk/storage/host/struct.HostStore.html b/rust/oasis_runtime_sdk/storage/host/struct.HostStore.html new file mode 100644 index 0000000000..4a06d42fd9 --- /dev/null +++ b/rust/oasis_runtime_sdk/storage/host/struct.HostStore.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../oasis_runtime_sdk/storage/struct.HostStore.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_runtime_sdk/storage/index.html b/rust/oasis_runtime_sdk/storage/index.html new file mode 100644 index 0000000000..5b2c9d44c9 --- /dev/null +++ b/rust/oasis_runtime_sdk/storage/index.html @@ -0,0 +1,2 @@ +Storage.
+pub use confidential::ConfidentialStore;pub use confidential::Error as ConfidentialStoreError;H(k) || k.Redirecting to ../../../oasis_runtime_sdk/storage/struct.MKVSStore.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_runtime_sdk/storage/overlay/struct.OverlayStore.html b/rust/oasis_runtime_sdk/storage/overlay/struct.OverlayStore.html new file mode 100644 index 0000000000..f8010d5973 --- /dev/null +++ b/rust/oasis_runtime_sdk/storage/overlay/struct.OverlayStore.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../oasis_runtime_sdk/storage/struct.OverlayStore.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_runtime_sdk/storage/prefix/struct.PrefixStore.html b/rust/oasis_runtime_sdk/storage/prefix/struct.PrefixStore.html new file mode 100644 index 0000000000..71bf6cfae8 --- /dev/null +++ b/rust/oasis_runtime_sdk/storage/prefix/struct.PrefixStore.html @@ -0,0 +1,11 @@ + + + + +Redirecting to ../../../oasis_runtime_sdk/storage/struct.PrefixStore.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_runtime_sdk/storage/sidebar-items.js b/rust/oasis_runtime_sdk/storage/sidebar-items.js new file mode 100644 index 0000000000..53b9c6ba90 --- /dev/null +++ b/rust/oasis_runtime_sdk/storage/sidebar-items.js @@ -0,0 +1 @@ +window.SIDEBAR_ITEMS = {"mod":["confidential"],"struct":["HashedStore","HostStore","MKVSStore","OverlayStore","Prefix","PrefixStore","TypedStore"],"trait":["NestedStore","Store"]}; \ No newline at end of file diff --git a/rust/oasis_runtime_sdk/storage/struct.HashedStore.html b/rust/oasis_runtime_sdk/storage/struct.HashedStore.html new file mode 100644 index 0000000000..e227891164 --- /dev/null +++ b/rust/oasis_runtime_sdk/storage/struct.HashedStore.html @@ -0,0 +1,33 @@ +pub struct HashedStore<S: Store, D: Digest> { /* private fields */ }A key-value store that hashes all keys and stores them as H(k) || k.
pub struct HostStore { /* private fields */ }A store for a specific state root that talks to the runtime host.
+Create a new host store for the given host and root.
+Create a new host store for the given host and root at the given round.
+The corresponding root hash is fetched by looking it up in consensus layer state, verified +by the passed verifier to be correct.
+pub struct MKVSStore<M: MKVS> { /* private fields */ }A key-value store backed by MKVS.
+pub struct OverlayStore<S: Store> { /* private fields */ }An overlay store which keeps values locally until explicitly committed.
+pub struct Prefix(/* private fields */);A key prefix.
+Returns the total number of elements the vector can hold without +reallocating.
+let mut vec: Vec<i32> = Vec::with_capacity(10);
+vec.push(42);
+assert!(vec.capacity() >= 10);Reserves capacity for at least additional more elements to be inserted
+in the given Vec<T>. The collection may reserve more space to
+speculatively avoid frequent reallocations. After calling reserve,
+capacity will be greater than or equal to self.len() + additional.
+Does nothing if capacity is already sufficient.
Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1];
+vec.reserve(10);
+assert!(vec.capacity() >= 11);Reserves the minimum capacity for at least additional more elements to
+be inserted in the given Vec<T>. Unlike reserve, this will not
+deliberately over-allocate to speculatively avoid frequent allocations.
+After calling reserve_exact, capacity will be greater than or equal to
+self.len() + additional. Does nothing if the capacity is already
+sufficient.
Note that the allocator may give the collection more space than it
+requests. Therefore, capacity can not be relied upon to be precisely
+minimal. Prefer reserve if future insertions are expected.
Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1];
+vec.reserve_exact(10);
+assert!(vec.capacity() >= 11);Tries to reserve capacity for at least additional more elements to be inserted
+in the given Vec<T>. The collection may reserve more space to speculatively avoid
+frequent reallocations. After calling try_reserve, capacity will be
+greater than or equal to self.len() + additional if it returns
+Ok(()). Does nothing if capacity is already sufficient. This method
+preserves the contents even if an error occurs.
If the capacity overflows, or the allocator reports a failure, then an error +is returned.
+use std::collections::TryReserveError;
+
+fn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {
+ let mut output = Vec::new();
+
+ // Pre-reserve the memory, exiting if we can't
+ output.try_reserve(data.len())?;
+
+ // Now we know this can't OOM in the middle of our complex work
+ output.extend(data.iter().map(|&val| {
+ val * 2 + 5 // very complicated
+ }));
+
+ Ok(output)
+}Tries to reserve the minimum capacity for at least additional
+elements to be inserted in the given Vec<T>. Unlike try_reserve,
+this will not deliberately over-allocate to speculatively avoid frequent
+allocations. After calling try_reserve_exact, capacity will be greater
+than or equal to self.len() + additional if it returns Ok(()).
+Does nothing if the capacity is already sufficient.
Note that the allocator may give the collection more space than it
+requests. Therefore, capacity can not be relied upon to be precisely
+minimal. Prefer try_reserve if future insertions are expected.
If the capacity overflows, or the allocator reports a failure, then an error +is returned.
+use std::collections::TryReserveError;
+
+fn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {
+ let mut output = Vec::new();
+
+ // Pre-reserve the memory, exiting if we can't
+ output.try_reserve_exact(data.len())?;
+
+ // Now we know this can't OOM in the middle of our complex work
+ output.extend(data.iter().map(|&val| {
+ val * 2 + 5 // very complicated
+ }));
+
+ Ok(output)
+}Shrinks the capacity of the vector as much as possible.
+The behavior of this method depends on the allocator, which may either shrink the vector
+in-place or reallocate. The resulting vector might still have some excess capacity, just as
+is the case for with_capacity. See Allocator::shrink for more details.
let mut vec = Vec::with_capacity(10);
+vec.extend([1, 2, 3]);
+assert!(vec.capacity() >= 10);
+vec.shrink_to_fit();
+assert!(vec.capacity() >= 3);Shrinks the capacity of the vector with a lower bound.
+The capacity will remain at least as large as both the length +and the supplied value.
+If the current capacity is less than the lower limit, this is a no-op.
+let mut vec = Vec::with_capacity(10);
+vec.extend([1, 2, 3]);
+assert!(vec.capacity() >= 10);
+vec.shrink_to(4);
+assert!(vec.capacity() >= 4);
+vec.shrink_to(0);
+assert!(vec.capacity() >= 3);Shortens the vector, keeping the first len elements and dropping
+the rest.
If len is greater or equal to the vector’s current length, this has
+no effect.
The drain method can emulate truncate, but causes the excess
+elements to be returned instead of dropped.
Note that this method has no effect on the allocated capacity +of the vector.
+Truncating a five element vector to two elements:
+ +let mut vec = vec![1, 2, 3, 4, 5];
+vec.truncate(2);
+assert_eq!(vec, [1, 2]);No truncation occurs when len is greater than the vector’s current
+length:
let mut vec = vec![1, 2, 3];
+vec.truncate(8);
+assert_eq!(vec, [1, 2, 3]);Truncating when len == 0 is equivalent to calling the clear
+method.
let mut vec = vec![1, 2, 3];
+vec.truncate(0);
+assert_eq!(vec, []);Extracts a slice containing the entire vector.
+Equivalent to &s[..].
use std::io::{self, Write};
+let buffer = vec![1, 2, 3, 5, 8];
+io::sink().write(buffer.as_slice()).unwrap();Extracts a mutable slice of the entire vector.
+Equivalent to &mut s[..].
use std::io::{self, Read};
+let mut buffer = vec![0; 3];
+io::repeat(0b101).read_exact(buffer.as_mut_slice()).unwrap();Returns a raw pointer to the vector’s buffer, or a dangling raw pointer +valid for zero sized reads if the vector didn’t allocate.
+The caller must ensure that the vector outlives the pointer this +function returns, or else it will end up pointing to garbage. +Modifying the vector may cause its buffer to be reallocated, +which would also make any pointers to it invalid.
+The caller must also ensure that the memory the pointer (non-transitively) points to
+is never written to (except inside an UnsafeCell) using this pointer or any pointer
+derived from it. If you need to mutate the contents of the slice, use as_mut_ptr.
This method guarantees that for the purpose of the aliasing model, this method
+does not materialize a reference to the underlying slice, and thus the returned pointer
+will remain valid when mixed with other calls to as_ptr and as_mut_ptr.
+Note that calling other methods that materialize mutable references to the slice,
+or mutable references to specific elements you are planning on accessing through this pointer,
+as well as writing to those elements, may still invalidate this pointer.
+See the second example below for how this guarantee can be used.
let x = vec![1, 2, 4];
+let x_ptr = x.as_ptr();
+
+unsafe {
+ for i in 0..x.len() {
+ assert_eq!(*x_ptr.add(i), 1 << i);
+ }
+}Due to the aliasing guarantee, the following code is legal:
+ +unsafe {
+ let mut v = vec![0, 1, 2];
+ let ptr1 = v.as_ptr();
+ let _ = ptr1.read();
+ let ptr2 = v.as_mut_ptr().offset(2);
+ ptr2.write(2);
+ // Notably, the write to `ptr2` did *not* invalidate `ptr1`
+ // because it mutated a different element:
+ let _ = ptr1.read();
+}Returns an unsafe mutable pointer to the vector’s buffer, or a dangling +raw pointer valid for zero sized reads if the vector didn’t allocate.
+The caller must ensure that the vector outlives the pointer this +function returns, or else it will end up pointing to garbage. +Modifying the vector may cause its buffer to be reallocated, +which would also make any pointers to it invalid.
+This method guarantees that for the purpose of the aliasing model, this method
+does not materialize a reference to the underlying slice, and thus the returned pointer
+will remain valid when mixed with other calls to as_ptr and as_mut_ptr.
+Note that calling other methods that materialize references to the slice,
+or references to specific elements you are planning on accessing through this pointer,
+may still invalidate this pointer.
+See the second example below for how this guarantee can be used.
// Allocate vector big enough for 4 elements.
+let size = 4;
+let mut x: Vec<i32> = Vec::with_capacity(size);
+let x_ptr = x.as_mut_ptr();
+
+// Initialize elements via raw pointer writes, then set length.
+unsafe {
+ for i in 0..size {
+ *x_ptr.add(i) = i as i32;
+ }
+ x.set_len(size);
+}
+assert_eq!(&*x, &[0, 1, 2, 3]);Due to the aliasing guarantee, the following code is legal:
+ +unsafe {
+ let mut v = vec![0];
+ let ptr1 = v.as_mut_ptr();
+ ptr1.write(1);
+ let ptr2 = v.as_mut_ptr();
+ ptr2.write(2);
+ // Notably, the write to `ptr2` did *not* invalidate `ptr1`:
+ ptr1.write(3);
+}allocator_api)Returns a reference to the underlying allocator.
+Forces the length of the vector to new_len.
This is a low-level operation that maintains none of the normal
+invariants of the type. Normally changing the length of a vector
+is done using one of the safe operations instead, such as
+truncate, resize, extend, or clear.
new_len must be less than or equal to capacity().old_len..new_len must be initialized.This method can be useful for situations in which the vector +is serving as a buffer for other code, particularly over FFI:
+ +pub fn get_dictionary(&self) -> Option<Vec<u8>> {
+ // Per the FFI method's docs, "32768 bytes is always enough".
+ let mut dict = Vec::with_capacity(32_768);
+ let mut dict_length = 0;
+ // SAFETY: When `deflateGetDictionary` returns `Z_OK`, it holds that:
+ // 1. `dict_length` elements were initialized.
+ // 2. `dict_length` <= the capacity (32_768)
+ // which makes `set_len` safe to call.
+ unsafe {
+ // Make the FFI call...
+ let r = deflateGetDictionary(self.strm, dict.as_mut_ptr(), &mut dict_length);
+ if r == Z_OK {
+ // ...and update the length to what was initialized.
+ dict.set_len(dict_length);
+ Some(dict)
+ } else {
+ None
+ }
+ }
+}While the following example is sound, there is a memory leak since
+the inner vectors were not freed prior to the set_len call:
let mut vec = vec![vec![1, 0, 0],
+ vec![0, 1, 0],
+ vec![0, 0, 1]];
+// SAFETY:
+// 1. `old_len..0` is empty so no elements need to be initialized.
+// 2. `0 <= capacity` always holds whatever `capacity` is.
+unsafe {
+ vec.set_len(0);
+}Normally, here, one would use clear instead to correctly drop
+the contents and thus not leak memory.
Removes an element from the vector and returns it.
+The removed element is replaced by the last element of the vector.
+This does not preserve ordering of the remaining elements, but is O(1).
+If you need to preserve the element order, use remove instead.
Panics if index is out of bounds.
let mut v = vec!["foo", "bar", "baz", "qux"];
+
+assert_eq!(v.swap_remove(1), "bar");
+assert_eq!(v, ["foo", "qux", "baz"]);
+
+assert_eq!(v.swap_remove(0), "foo");
+assert_eq!(v, ["baz", "qux"]);Inserts an element at position index within the vector, shifting all
+elements after it to the right.
Panics if index > len.
let mut vec = vec![1, 2, 3];
+vec.insert(1, 4);
+assert_eq!(vec, [1, 4, 2, 3]);
+vec.insert(4, 5);
+assert_eq!(vec, [1, 4, 2, 3, 5]);Takes O(Vec::len) time. All items after the insertion index must be
+shifted to the right. In the worst case, all elements are shifted when
+the insertion index is 0.
Removes and returns the element at position index within the vector,
+shifting all elements after it to the left.
Note: Because this shifts over the remaining elements, it has a
+worst-case performance of O(n). If you don’t need the order of elements
+to be preserved, use swap_remove instead. If you’d like to remove
+elements from the beginning of the Vec, consider using
+VecDeque::pop_front instead.
Panics if index is out of bounds.
let mut v = vec![1, 2, 3];
+assert_eq!(v.remove(1), 2);
+assert_eq!(v, [1, 3]);Retains only the elements specified by the predicate.
+In other words, remove all elements e for which f(&e) returns false.
+This method operates in place, visiting each element exactly once in the
+original order, and preserves the order of the retained elements.
let mut vec = vec![1, 2, 3, 4];
+vec.retain(|&x| x % 2 == 0);
+assert_eq!(vec, [2, 4]);Because the elements are visited exactly once in the original order, +external state may be used to decide which elements to keep.
+ +let mut vec = vec![1, 2, 3, 4, 5];
+let keep = [false, true, true, false, true];
+let mut iter = keep.iter();
+vec.retain(|_| *iter.next().unwrap());
+assert_eq!(vec, [2, 3, 5]);Retains only the elements specified by the predicate, passing a mutable reference to it.
+In other words, remove all elements e such that f(&mut e) returns false.
+This method operates in place, visiting each element exactly once in the
+original order, and preserves the order of the retained elements.
let mut vec = vec![1, 2, 3, 4];
+vec.retain_mut(|x| if *x <= 3 {
+ *x += 1;
+ true
+} else {
+ false
+});
+assert_eq!(vec, [2, 3, 4]);Removes all but the first of consecutive elements in the vector that resolve to the same +key.
+If the vector is sorted, this removes all duplicates.
+let mut vec = vec![10, 20, 21, 30, 20];
+
+vec.dedup_by_key(|i| *i / 10);
+
+assert_eq!(vec, [10, 20, 30, 20]);Removes all but the first of consecutive elements in the vector satisfying a given equality +relation.
+The same_bucket function is passed references to two elements from the vector and
+must determine if the elements compare equal. The elements are passed in opposite order
+from their order in the slice, so if same_bucket(a, b) returns true, a is removed.
If the vector is sorted, this removes all duplicates.
+let mut vec = vec!["foo", "bar", "Bar", "baz", "bar"];
+
+vec.dedup_by(|a, b| a.eq_ignore_ascii_case(b));
+
+assert_eq!(vec, ["foo", "bar", "baz", "bar"]);Appends an element to the back of a collection.
+Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1, 2];
+vec.push(3);
+assert_eq!(vec, [1, 2, 3]);Takes amortized O(1) time. If the vector’s length would exceed its +capacity after the push, O(capacity) time is taken to copy the +vector’s elements to a larger allocation. This expensive operation is +offset by the capacity O(1) insertions it allows.
+vec_push_within_capacity)Appends an element if there is sufficient spare capacity, otherwise an error is returned +with the element.
+Unlike push this method will not reallocate when there’s insufficient capacity.
+The caller should use reserve or try_reserve to ensure that there is enough capacity.
A manual, panic-free alternative to FromIterator:
#![feature(vec_push_within_capacity)]
+
+use std::collections::TryReserveError;
+fn from_iter_fallible<T>(iter: impl Iterator<Item=T>) -> Result<Vec<T>, TryReserveError> {
+ let mut vec = Vec::new();
+ for value in iter {
+ if let Err(value) = vec.push_within_capacity(value) {
+ vec.try_reserve(1)?;
+ // this cannot fail, the previous line either returned or added at least 1 free slot
+ let _ = vec.push_within_capacity(value);
+ }
+ }
+ Ok(vec)
+}
+assert_eq!(from_iter_fallible(0..100), Ok(Vec::from_iter(0..100)));Takes O(1) time.
+Removes the last element from a vector and returns it, or None if it
+is empty.
If you’d like to pop the first element, consider using
+VecDeque::pop_front instead.
let mut vec = vec![1, 2, 3];
+assert_eq!(vec.pop(), Some(3));
+assert_eq!(vec, [1, 2]);Takes O(1) time.
+vec_pop_if)Removes and returns the last element in a vector if the predicate
+returns true, or None if the predicate returns false or the vector
+is empty.
#![feature(vec_pop_if)]
+
+let mut vec = vec![1, 2, 3, 4];
+let pred = |x: &mut i32| *x % 2 == 0;
+
+assert_eq!(vec.pop_if(pred), Some(4));
+assert_eq!(vec, [1, 2, 3]);
+assert_eq!(vec.pop_if(pred), None);Removes the specified range from the vector in bulk, returning all +removed elements as an iterator. If the iterator is dropped before +being fully consumed, it drops the remaining removed elements.
+The returned iterator keeps a mutable borrow on the vector to optimize +its implementation.
+Panics if the starting point is greater than the end point or if +the end point is greater than the length of the vector.
+If the returned iterator goes out of scope without being dropped (due to
+mem::forget, for example), the vector may have lost and leaked
+elements arbitrarily, including elements outside the range.
let mut v = vec![1, 2, 3];
+let u: Vec<_> = v.drain(1..).collect();
+assert_eq!(v, &[1]);
+assert_eq!(u, &[2, 3]);
+
+// A full range clears the vector, like `clear()` does
+v.drain(..);
+assert_eq!(v, &[]);Clears the vector, removing all values.
+Note that this method has no effect on the allocated capacity +of the vector.
+let mut v = vec![1, 2, 3];
+
+v.clear();
+
+assert!(v.is_empty());Returns the number of elements in the vector, also referred to +as its ‘length’.
+let a = vec![1, 2, 3];
+assert_eq!(a.len(), 3);Returns true if the vector contains no elements.
let mut v = Vec::new();
+assert!(v.is_empty());
+
+v.push(1);
+assert!(!v.is_empty());Splits the collection into two at the given index.
+Returns a newly allocated vector containing the elements in the range
+[at, len). After the call, the original vector will be left containing
+the elements [0, at) with its previous capacity unchanged.
mem::take or mem::replace.Vec::truncate.Vec::drain.Panics if at > len.
let mut vec = vec![1, 2, 3];
+let vec2 = vec.split_off(1);
+assert_eq!(vec, [1]);
+assert_eq!(vec2, [2, 3]);Resizes the Vec in-place so that len is equal to new_len.
If new_len is greater than len, the Vec is extended by the
+difference, with each additional slot filled with the result of
+calling the closure f. The return values from f will end up
+in the Vec in the order they have been generated.
If new_len is less than len, the Vec is simply truncated.
This method uses a closure to create new values on every push. If
+you’d rather Clone a given value, use Vec::resize. If you
+want to use the Default trait to generate values, you can
+pass Default::default as the second argument.
let mut vec = vec![1, 2, 3];
+vec.resize_with(5, Default::default);
+assert_eq!(vec, [1, 2, 3, 0, 0]);
+
+let mut vec = vec![];
+let mut p = 1;
+vec.resize_with(4, || { p *= 2; p });
+assert_eq!(vec, [2, 4, 8, 16]);Returns the remaining spare capacity of the vector as a slice of
+MaybeUninit<T>.
The returned slice can be used to fill the vector with data (e.g. by
+reading from a file) before marking the data as initialized using the
+set_len method.
// Allocate vector big enough for 10 elements.
+let mut v = Vec::with_capacity(10);
+
+// Fill in the first 3 elements.
+let uninit = v.spare_capacity_mut();
+uninit[0].write(0);
+uninit[1].write(1);
+uninit[2].write(2);
+
+// Mark the first 3 elements of the vector as being initialized.
+unsafe {
+ v.set_len(3);
+}
+
+assert_eq!(&v, &[0, 1, 2]);vec_split_at_spare)Returns vector content as a slice of T, along with the remaining spare
+capacity of the vector as a slice of MaybeUninit<T>.
The returned spare capacity slice can be used to fill the vector with data
+(e.g. by reading from a file) before marking the data as initialized using
+the set_len method.
Note that this is a low-level API, which should be used with care for
+optimization purposes. If you need to append data to a Vec
+you can use push, extend, extend_from_slice,
+extend_from_within, insert, append, resize or
+resize_with, depending on your exact needs.
#![feature(vec_split_at_spare)]
+
+let mut v = vec![1, 1, 2];
+
+// Reserve additional space big enough for 10 elements.
+v.reserve(10);
+
+let (init, uninit) = v.split_at_spare_mut();
+let sum = init.iter().copied().sum::<u32>();
+
+// Fill in the next 4 elements.
+uninit[0].write(sum);
+uninit[1].write(sum * 2);
+uninit[2].write(sum * 3);
+uninit[3].write(sum * 4);
+
+// Mark the 4 elements of the vector as being initialized.
+unsafe {
+ let len = v.len();
+ v.set_len(len + 4);
+}
+
+assert_eq!(&v, &[1, 1, 2, 4, 8, 12, 16]);Resizes the Vec in-place so that len is equal to new_len.
If new_len is greater than len, the Vec is extended by the
+difference, with each additional slot filled with value.
+If new_len is less than len, the Vec is simply truncated.
This method requires T to implement Clone,
+in order to be able to clone the passed value.
+If you need more flexibility (or want to rely on Default instead of
+Clone), use Vec::resize_with.
+If you only need to resize to a smaller size, use Vec::truncate.
let mut vec = vec!["hello"];
+vec.resize(3, "world");
+assert_eq!(vec, ["hello", "world", "world"]);
+
+let mut vec = vec![1, 2, 3, 4];
+vec.resize(2, 0);
+assert_eq!(vec, [1, 2]);Clones and appends all elements in a slice to the Vec.
Iterates over the slice other, clones each element, and then appends
+it to this Vec. The other slice is traversed in-order.
Note that this function is same as extend except that it is
+specialized to work with slices instead. If and when Rust gets
+specialization this function will likely be deprecated (but still
+available).
let mut vec = vec![1];
+vec.extend_from_slice(&[2, 3, 4]);
+assert_eq!(vec, [1, 2, 3, 4]);Copies elements from src range to the end of the vector.
Panics if the starting point is greater than the end point or if +the end point is greater than the length of the vector.
+let mut vec = vec![0, 1, 2, 3, 4];
+
+vec.extend_from_within(2..);
+assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4]);
+
+vec.extend_from_within(..2);
+assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1]);
+
+vec.extend_from_within(4..8);
+assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);Creates a splicing iterator that replaces the specified range in the vector
+with the given replace_with iterator and yields the removed items.
+replace_with does not need to be the same length as range.
range is removed even if the iterator is not consumed until the end.
It is unspecified how many elements are removed from the vector
+if the Splice value is leaked.
The input iterator replace_with is only consumed when the Splice value is dropped.
This is optimal if:
+range) is empty,replace_with yields fewer or equal elements than range’s lengthsize_hint() is exact.Otherwise, a temporary vector is allocated and the tail is moved twice.
+Panics if the starting point is greater than the end point or if +the end point is greater than the length of the vector.
+let mut v = vec![1, 2, 3, 4];
+let new = [7, 8, 9];
+let u: Vec<_> = v.splice(1..3, new).collect();
+assert_eq!(v, &[1, 7, 8, 9, 4]);
+assert_eq!(u, &[2, 3]);extract_if)Creates an iterator which uses a closure to determine if an element should be removed.
+If the closure returns true, then the element is removed and yielded. +If the closure returns false, the element will remain in the vector and will not be yielded +by the iterator.
+If the returned ExtractIf is not exhausted, e.g. because it is dropped without iterating
+or the iteration short-circuits, then the remaining elements will be retained.
+Use retain with a negated predicate if you do not need the returned iterator.
Using this method is equivalent to the following code:
+ +let mut i = 0;
+while i < vec.len() {
+ if some_predicate(&mut vec[i]) {
+ let val = vec.remove(i);
+ // your code here
+ } else {
+ i += 1;
+ }
+}
+But extract_if is easier to use. extract_if is also more efficient,
+because it can backshift the elements of the array in bulk.
Note that extract_if also lets you mutate every element in the filter closure,
+regardless of whether you choose to keep or remove it.
Splitting an array into evens and odds, reusing the original allocation:
+ +#![feature(extract_if)]
+let mut numbers = vec![1, 2, 3, 4, 5, 6, 8, 9, 11, 13, 14, 15];
+
+let evens = numbers.extract_if(|x| *x % 2 == 0).collect::<Vec<_>>();
+let odds = numbers;
+
+assert_eq!(evens, vec![2, 4, 6, 8, 14]);
+assert_eq!(odds, vec![1, 3, 5, 9, 11, 13, 15]);ascii_char)Views this slice of ASCII characters as a UTF-8 str.
ascii_char)Views this slice of ASCII characters as a slice of u8 bytes.
sort_floats)Sorts the slice of floats.
+This sort is in-place (i.e. does not allocate), O(n * log(n)) worst-case, and uses
+the ordering defined by f32::total_cmp.
This uses the same sorting algorithm as sort_unstable_by.
#![feature(sort_floats)]
+let mut v = [2.6, -5e-8, f32::NAN, 8.29, f32::INFINITY, -1.0, 0.0, -f32::INFINITY, -0.0];
+
+v.sort_floats();
+let sorted = [-f32::INFINITY, -1.0, -5e-8, -0.0, 0.0, 2.6, 8.29, f32::INFINITY, f32::NAN];
+assert_eq!(&v[..8], &sorted[..8]);
+assert!(v[8].is_nan());Checks if all bytes in this slice are within the ASCII range.
+ascii_char)If this slice is_ascii, returns it as a slice of
+ASCII characters, otherwise returns None.
ascii_char)Converts this slice of bytes into a slice of ASCII characters, +without checking whether they’re valid.
+Every byte in the slice must be in 0..=127, or else this is UB.
Checks that two slices are an ASCII case-insensitive match.
+Same as to_ascii_lowercase(a) == to_ascii_lowercase(b),
+but without allocating and copying temporaries.
Converts this slice to its ASCII upper case equivalent in-place.
+ASCII letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’, +but non-ASCII letters are unchanged.
+To return a new uppercased value without modifying the existing one, use
+to_ascii_uppercase.
Converts this slice to its ASCII lower case equivalent in-place.
+ASCII letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’, +but non-ASCII letters are unchanged.
+To return a new lowercased value without modifying the existing one, use
+to_ascii_lowercase.
Returns an iterator that produces an escaped version of this slice, +treating it as an ASCII string.
+
+let s = b"0\t\r\n'\"\\\x9d";
+let escaped = s.escape_ascii().to_string();
+assert_eq!(escaped, "0\\t\\r\\n\\'\\\"\\\\\\x9d");Returns a byte slice with leading ASCII whitespace bytes removed.
+‘Whitespace’ refers to the definition used by
+u8::is_ascii_whitespace.
assert_eq!(b" \t hello world\n".trim_ascii_start(), b"hello world\n");
+assert_eq!(b" ".trim_ascii_start(), b"");
+assert_eq!(b"".trim_ascii_start(), b"");Returns a byte slice with trailing ASCII whitespace bytes removed.
+‘Whitespace’ refers to the definition used by
+u8::is_ascii_whitespace.
assert_eq!(b"\r hello world\n ".trim_ascii_end(), b"\r hello world");
+assert_eq!(b" ".trim_ascii_end(), b"");
+assert_eq!(b"".trim_ascii_end(), b"");Returns a byte slice with leading and trailing ASCII whitespace bytes +removed.
+‘Whitespace’ refers to the definition used by
+u8::is_ascii_whitespace.
assert_eq!(b"\r hello world\n ".trim_ascii(), b"hello world");
+assert_eq!(b" ".trim_ascii(), b"");
+assert_eq!(b"".trim_ascii(), b"");Creates an iterator over the contiguous valid UTF-8 ranges of this +slice, and the non-UTF-8 fragments in between.
+This function formats arbitrary but mostly-UTF-8 bytes into Rust source
+code in the form of a C-string literal (c"...").
use std::fmt::Write as _;
+
+pub fn cstr_literal(bytes: &[u8]) -> String {
+ let mut repr = String::new();
+ repr.push_str("c\"");
+ for chunk in bytes.utf8_chunks() {
+ for ch in chunk.valid().chars() {
+ // Escapes \0, \t, \r, \n, \\, \', \", and uses \u{...} for non-printable characters.
+ write!(repr, "{}", ch.escape_debug()).unwrap();
+ }
+ for byte in chunk.invalid() {
+ write!(repr, "\\x{:02X}", byte).unwrap();
+ }
+ }
+ repr.push('"');
+ repr
+}
+
+fn main() {
+ let lit = cstr_literal(b"\xferris the \xf0\x9f\xa6\x80\x07");
+ let expected = stringify!(c"\xFErris the 🦀\u{7}");
+ assert_eq!(lit, expected);
+}Takes a &[[T; N]], and flattens it to a &[T].
This panics if the length of the resulting slice would overflow a usize.
This is only possible when flattening a slice of arrays of zero-sized
+types, and thus tends to be irrelevant in practice. If
+size_of::<T>() > 0, this will never panic.
assert_eq!([[1, 2, 3], [4, 5, 6]].as_flattened(), &[1, 2, 3, 4, 5, 6]);
+
+assert_eq!(
+ [[1, 2, 3], [4, 5, 6]].as_flattened(),
+ [[1, 2], [3, 4], [5, 6]].as_flattened(),
+);
+
+let slice_of_empty_arrays: &[[i32; 0]] = &[[], [], [], [], []];
+assert!(slice_of_empty_arrays.as_flattened().is_empty());
+
+let empty_slice_of_arrays: &[[u32; 10]] = &[];
+assert!(empty_slice_of_arrays.as_flattened().is_empty());Takes a &mut [[T; N]], and flattens it to a &mut [T].
This panics if the length of the resulting slice would overflow a usize.
This is only possible when flattening a slice of arrays of zero-sized
+types, and thus tends to be irrelevant in practice. If
+size_of::<T>() > 0, this will never panic.
fn add_5_to_all(slice: &mut [i32]) {
+ for i in slice {
+ *i += 5;
+ }
+}
+
+let mut array = [[1, 2, 3], [4, 5, 6], [7, 8, 9]];
+add_5_to_all(array.as_flattened_mut());
+assert_eq!(array, [[6, 7, 8], [9, 10, 11], [12, 13, 14]]);sort_floats)Sorts the slice of floats.
+This sort is in-place (i.e. does not allocate), O(n * log(n)) worst-case, and uses
+the ordering defined by f64::total_cmp.
This uses the same sorting algorithm as sort_unstable_by.
#![feature(sort_floats)]
+let mut v = [2.6, -5e-8, f64::NAN, 8.29, f64::INFINITY, -1.0, 0.0, -f64::INFINITY, -0.0];
+
+v.sort_floats();
+let sorted = [-f64::INFINITY, -1.0, -5e-8, -0.0, 0.0, 2.6, 8.29, f64::INFINITY, f64::NAN];
+assert_eq!(&v[..8], &sorted[..8]);
+assert!(v[8].is_nan());Returns the number of elements in the slice.
+let a = [1, 2, 3];
+assert_eq!(a.len(), 3);Returns true if the slice has a length of 0.
let a = [1, 2, 3];
+assert!(!a.is_empty());
+
+let b: &[i32] = &[];
+assert!(b.is_empty());Returns the first element of the slice, or None if it is empty.
let v = [10, 40, 30];
+assert_eq!(Some(&10), v.first());
+
+let w: &[i32] = &[];
+assert_eq!(None, w.first());Returns a mutable pointer to the first element of the slice, or None if it is empty.
let x = &mut [0, 1, 2];
+
+if let Some(first) = x.first_mut() {
+ *first = 5;
+}
+assert_eq!(x, &[5, 1, 2]);
+
+let y: &mut [i32] = &mut [];
+assert_eq!(None, y.first_mut());Returns the first and all the rest of the elements of the slice, or None if it is empty.
let x = &[0, 1, 2];
+
+if let Some((first, elements)) = x.split_first() {
+ assert_eq!(first, &0);
+ assert_eq!(elements, &[1, 2]);
+}Returns the first and all the rest of the elements of the slice, or None if it is empty.
let x = &mut [0, 1, 2];
+
+if let Some((first, elements)) = x.split_first_mut() {
+ *first = 3;
+ elements[0] = 4;
+ elements[1] = 5;
+}
+assert_eq!(x, &[3, 4, 5]);Returns the last and all the rest of the elements of the slice, or None if it is empty.
let x = &[0, 1, 2];
+
+if let Some((last, elements)) = x.split_last() {
+ assert_eq!(last, &2);
+ assert_eq!(elements, &[0, 1]);
+}Returns the last and all the rest of the elements of the slice, or None if it is empty.
let x = &mut [0, 1, 2];
+
+if let Some((last, elements)) = x.split_last_mut() {
+ *last = 3;
+ elements[0] = 4;
+ elements[1] = 5;
+}
+assert_eq!(x, &[4, 5, 3]);Returns the last element of the slice, or None if it is empty.
let v = [10, 40, 30];
+assert_eq!(Some(&30), v.last());
+
+let w: &[i32] = &[];
+assert_eq!(None, w.last());Returns a mutable reference to the last item in the slice, or None if it is empty.
let x = &mut [0, 1, 2];
+
+if let Some(last) = x.last_mut() {
+ *last = 10;
+}
+assert_eq!(x, &[0, 1, 10]);
+
+let y: &mut [i32] = &mut [];
+assert_eq!(None, y.last_mut());Return an array reference to the first N items in the slice.
If the slice is not at least N in length, this will return None.
let u = [10, 40, 30];
+assert_eq!(Some(&[10, 40]), u.first_chunk::<2>());
+
+let v: &[i32] = &[10];
+assert_eq!(None, v.first_chunk::<2>());
+
+let w: &[i32] = &[];
+assert_eq!(Some(&[]), w.first_chunk::<0>());Return a mutable array reference to the first N items in the slice.
If the slice is not at least N in length, this will return None.
let x = &mut [0, 1, 2];
+
+if let Some(first) = x.first_chunk_mut::<2>() {
+ first[0] = 5;
+ first[1] = 4;
+}
+assert_eq!(x, &[5, 4, 2]);
+
+assert_eq!(None, x.first_chunk_mut::<4>());Return an array reference to the first N items in the slice and the remaining slice.
If the slice is not at least N in length, this will return None.
let x = &[0, 1, 2];
+
+if let Some((first, elements)) = x.split_first_chunk::<2>() {
+ assert_eq!(first, &[0, 1]);
+ assert_eq!(elements, &[2]);
+}
+
+assert_eq!(None, x.split_first_chunk::<4>());Return a mutable array reference to the first N items in the slice and the remaining
+slice.
If the slice is not at least N in length, this will return None.
let x = &mut [0, 1, 2];
+
+if let Some((first, elements)) = x.split_first_chunk_mut::<2>() {
+ first[0] = 3;
+ first[1] = 4;
+ elements[0] = 5;
+}
+assert_eq!(x, &[3, 4, 5]);
+
+assert_eq!(None, x.split_first_chunk_mut::<4>());Return an array reference to the last N items in the slice and the remaining slice.
If the slice is not at least N in length, this will return None.
let x = &[0, 1, 2];
+
+if let Some((elements, last)) = x.split_last_chunk::<2>() {
+ assert_eq!(elements, &[0]);
+ assert_eq!(last, &[1, 2]);
+}
+
+assert_eq!(None, x.split_last_chunk::<4>());Return a mutable array reference to the last N items in the slice and the remaining
+slice.
If the slice is not at least N in length, this will return None.
let x = &mut [0, 1, 2];
+
+if let Some((elements, last)) = x.split_last_chunk_mut::<2>() {
+ last[0] = 3;
+ last[1] = 4;
+ elements[0] = 5;
+}
+assert_eq!(x, &[5, 3, 4]);
+
+assert_eq!(None, x.split_last_chunk_mut::<4>());Return an array reference to the last N items in the slice.
If the slice is not at least N in length, this will return None.
let u = [10, 40, 30];
+assert_eq!(Some(&[40, 30]), u.last_chunk::<2>());
+
+let v: &[i32] = &[10];
+assert_eq!(None, v.last_chunk::<2>());
+
+let w: &[i32] = &[];
+assert_eq!(Some(&[]), w.last_chunk::<0>());Return a mutable array reference to the last N items in the slice.
If the slice is not at least N in length, this will return None.
let x = &mut [0, 1, 2];
+
+if let Some(last) = x.last_chunk_mut::<2>() {
+ last[0] = 10;
+ last[1] = 20;
+}
+assert_eq!(x, &[0, 10, 20]);
+
+assert_eq!(None, x.last_chunk_mut::<4>());Returns a reference to an element or subslice depending on the type of +index.
+None if out of bounds.None if out of bounds.let v = [10, 40, 30];
+assert_eq!(Some(&40), v.get(1));
+assert_eq!(Some(&[10, 40][..]), v.get(0..2));
+assert_eq!(None, v.get(3));
+assert_eq!(None, v.get(0..4));Returns a reference to an element or subslice, without doing bounds +checking.
+For a safe alternative see get.
Calling this method with an out-of-bounds index is undefined behavior +even if the resulting reference is not used.
+You can think of this like .get(index).unwrap_unchecked(). It’s UB
+to call .get_unchecked(len), even if you immediately convert to a
+pointer. And it’s UB to call .get_unchecked(..len + 1),
+.get_unchecked(..=len), or similar.
let x = &[1, 2, 4];
+
+unsafe {
+ assert_eq!(x.get_unchecked(1), &2);
+}Returns a mutable reference to an element or subslice, without doing +bounds checking.
+For a safe alternative see get_mut.
Calling this method with an out-of-bounds index is undefined behavior +even if the resulting reference is not used.
+You can think of this like .get_mut(index).unwrap_unchecked(). It’s
+UB to call .get_unchecked_mut(len), even if you immediately convert
+to a pointer. And it’s UB to call .get_unchecked_mut(..len + 1),
+.get_unchecked_mut(..=len), or similar.
let x = &mut [1, 2, 4];
+
+unsafe {
+ let elem = x.get_unchecked_mut(1);
+ *elem = 13;
+}
+assert_eq!(x, &[1, 13, 4]);Returns a raw pointer to the slice’s buffer.
+The caller must ensure that the slice outlives the pointer this +function returns, or else it will end up pointing to garbage.
+The caller must also ensure that the memory the pointer (non-transitively) points to
+is never written to (except inside an UnsafeCell) using this pointer or any pointer
+derived from it. If you need to mutate the contents of the slice, use as_mut_ptr.
Modifying the container referenced by this slice may cause its buffer +to be reallocated, which would also make any pointers to it invalid.
+let x = &[1, 2, 4];
+let x_ptr = x.as_ptr();
+
+unsafe {
+ for i in 0..x.len() {
+ assert_eq!(x.get_unchecked(i), &*x_ptr.add(i));
+ }
+}Returns an unsafe mutable pointer to the slice’s buffer.
+The caller must ensure that the slice outlives the pointer this +function returns, or else it will end up pointing to garbage.
+Modifying the container referenced by this slice may cause its buffer +to be reallocated, which would also make any pointers to it invalid.
+let x = &mut [1, 2, 4];
+let x_ptr = x.as_mut_ptr();
+
+unsafe {
+ for i in 0..x.len() {
+ *x_ptr.add(i) += 2;
+ }
+}
+assert_eq!(x, &[3, 4, 6]);Returns the two raw pointers spanning the slice.
+The returned range is half-open, which means that the end pointer +points one past the last element of the slice. This way, an empty +slice is represented by two equal pointers, and the difference between +the two pointers represents the size of the slice.
+See as_ptr for warnings on using these pointers. The end pointer
+requires extra caution, as it does not point to a valid element in the
+slice.
This function is useful for interacting with foreign interfaces which +use two pointers to refer to a range of elements in memory, as is +common in C++.
+It can also be useful to check if a pointer to an element refers to an +element of this slice:
+ +let a = [1, 2, 3];
+let x = &a[1] as *const _;
+let y = &5 as *const _;
+
+assert!(a.as_ptr_range().contains(&x));
+assert!(!a.as_ptr_range().contains(&y));Returns the two unsafe mutable pointers spanning the slice.
+The returned range is half-open, which means that the end pointer +points one past the last element of the slice. This way, an empty +slice is represented by two equal pointers, and the difference between +the two pointers represents the size of the slice.
+See as_mut_ptr for warnings on using these pointers. The end
+pointer requires extra caution, as it does not point to a valid element
+in the slice.
This function is useful for interacting with foreign interfaces which +use two pointers to refer to a range of elements in memory, as is +common in C++.
+Swaps two elements in the slice.
+If a equals to b, it’s guaranteed that elements won’t change value.
Panics if a or b are out of bounds.
let mut v = ["a", "b", "c", "d", "e"];
+v.swap(2, 4);
+assert!(v == ["a", "b", "e", "d", "c"]);slice_swap_unchecked)Swaps two elements in the slice, without doing bounds checking.
+For a safe alternative see swap.
Calling this method with an out-of-bounds index is undefined behavior.
+The caller has to ensure that a < self.len() and b < self.len().
#![feature(slice_swap_unchecked)]
+
+let mut v = ["a", "b", "c", "d"];
+// SAFETY: we know that 1 and 3 are both indices of the slice
+unsafe { v.swap_unchecked(1, 3) };
+assert!(v == ["a", "d", "c", "b"]);Reverses the order of elements in the slice, in place.
+let mut v = [1, 2, 3];
+v.reverse();
+assert!(v == [3, 2, 1]);Returns an iterator over the slice.
+The iterator yields all items from start to end.
+let x = &[1, 2, 4];
+let mut iterator = x.iter();
+
+assert_eq!(iterator.next(), Some(&1));
+assert_eq!(iterator.next(), Some(&2));
+assert_eq!(iterator.next(), Some(&4));
+assert_eq!(iterator.next(), None);Returns an iterator that allows modifying each value.
+The iterator yields all items from start to end.
+let x = &mut [1, 2, 4];
+for elem in x.iter_mut() {
+ *elem += 2;
+}
+assert_eq!(x, &[3, 4, 6]);Returns an iterator over all contiguous windows of length
+size. The windows overlap. If the slice is shorter than
+size, the iterator returns no values.
Panics if size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.windows(3);
+assert_eq!(iter.next().unwrap(), &['l', 'o', 'r']);
+assert_eq!(iter.next().unwrap(), &['o', 'r', 'e']);
+assert_eq!(iter.next().unwrap(), &['r', 'e', 'm']);
+assert!(iter.next().is_none());If the slice is shorter than size:
let slice = ['f', 'o', 'o'];
+let mut iter = slice.windows(4);
+assert!(iter.next().is_none());There’s no windows_mut, as that existing would let safe code violate the
+“only one &mut at a time to the same thing” rule. However, you can sometimes
+use Cell::as_slice_of_cells in
+conjunction with windows to accomplish something similar:
use std::cell::Cell;
+
+let mut array = ['R', 'u', 's', 't', ' ', '2', '0', '1', '5'];
+let slice = &mut array[..];
+let slice_of_cells: &[Cell<char>] = Cell::from_mut(slice).as_slice_of_cells();
+for w in slice_of_cells.windows(3) {
+ Cell::swap(&w[0], &w[2]);
+}
+assert_eq!(array, ['s', 't', ' ', '2', '0', '1', '5', 'u', 'R']);Returns an iterator over chunk_size elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are slices and do not overlap. If chunk_size does not divide the length of the
+slice, then the last chunk will not have length chunk_size.
See chunks_exact for a variant of this iterator that returns chunks of always exactly
+chunk_size elements, and rchunks for the same iterator but starting at the end of the
+slice.
Panics if chunk_size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.chunks(2);
+assert_eq!(iter.next().unwrap(), &['l', 'o']);
+assert_eq!(iter.next().unwrap(), &['r', 'e']);
+assert_eq!(iter.next().unwrap(), &['m']);
+assert!(iter.next().is_none());Returns an iterator over chunk_size elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are mutable slices, and do not overlap. If chunk_size does not divide the
+length of the slice, then the last chunk will not have length chunk_size.
See chunks_exact_mut for a variant of this iterator that returns chunks of always
+exactly chunk_size elements, and rchunks_mut for the same iterator but starting at
+the end of the slice.
Panics if chunk_size is 0.
let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.chunks_mut(2) {
+ for elem in chunk.iter_mut() {
+ *elem += count;
+ }
+ count += 1;
+}
+assert_eq!(v, &[1, 1, 2, 2, 3]);Returns an iterator over chunk_size elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are slices and do not overlap. If chunk_size does not divide the length of the
+slice, then the last up to chunk_size-1 elements will be omitted and can be retrieved
+from the remainder function of the iterator.
Due to each chunk having exactly chunk_size elements, the compiler can often optimize the
+resulting code better than in the case of chunks.
See chunks for a variant of this iterator that also returns the remainder as a smaller
+chunk, and rchunks_exact for the same iterator but starting at the end of the slice.
Panics if chunk_size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.chunks_exact(2);
+assert_eq!(iter.next().unwrap(), &['l', 'o']);
+assert_eq!(iter.next().unwrap(), &['r', 'e']);
+assert!(iter.next().is_none());
+assert_eq!(iter.remainder(), &['m']);Returns an iterator over chunk_size elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are mutable slices, and do not overlap. If chunk_size does not divide the
+length of the slice, then the last up to chunk_size-1 elements will be omitted and can be
+retrieved from the into_remainder function of the iterator.
Due to each chunk having exactly chunk_size elements, the compiler can often optimize the
+resulting code better than in the case of chunks_mut.
See chunks_mut for a variant of this iterator that also returns the remainder as a
+smaller chunk, and rchunks_exact_mut for the same iterator but starting at the end of
+the slice.
Panics if chunk_size is 0.
let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.chunks_exact_mut(2) {
+ for elem in chunk.iter_mut() {
+ *elem += count;
+ }
+ count += 1;
+}
+assert_eq!(v, &[1, 1, 2, 2, 0]);slice_as_chunks)Splits the slice into a slice of N-element arrays,
+assuming that there’s no remainder.
This may only be called when
+N-element chunks (aka self.len() % N == 0).N != 0.#![feature(slice_as_chunks)]
+let slice: &[char] = &['l', 'o', 'r', 'e', 'm', '!'];
+let chunks: &[[char; 1]] =
+ // SAFETY: 1-element chunks never have remainder
+ unsafe { slice.as_chunks_unchecked() };
+assert_eq!(chunks, &[['l'], ['o'], ['r'], ['e'], ['m'], ['!']]);
+let chunks: &[[char; 3]] =
+ // SAFETY: The slice length (6) is a multiple of 3
+ unsafe { slice.as_chunks_unchecked() };
+assert_eq!(chunks, &[['l', 'o', 'r'], ['e', 'm', '!']]);
+
+// These would be unsound:
+// let chunks: &[[_; 5]] = slice.as_chunks_unchecked() // The slice length is not a multiple of 5
+// let chunks: &[[_; 0]] = slice.as_chunks_unchecked() // Zero-length chunks are never allowedslice_as_chunks)Splits the slice into a slice of N-element arrays,
+starting at the beginning of the slice,
+and a remainder slice with length strictly less than N.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(slice_as_chunks)]
+let slice = ['l', 'o', 'r', 'e', 'm'];
+let (chunks, remainder) = slice.as_chunks();
+assert_eq!(chunks, &[['l', 'o'], ['r', 'e']]);
+assert_eq!(remainder, &['m']);If you expect the slice to be an exact multiple, you can combine
+let-else with an empty slice pattern:
#![feature(slice_as_chunks)]
+let slice = ['R', 'u', 's', 't'];
+let (chunks, []) = slice.as_chunks::<2>() else {
+ panic!("slice didn't have even length")
+};
+assert_eq!(chunks, &[['R', 'u'], ['s', 't']]);slice_as_chunks)Splits the slice into a slice of N-element arrays,
+starting at the end of the slice,
+and a remainder slice with length strictly less than N.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(slice_as_chunks)]
+let slice = ['l', 'o', 'r', 'e', 'm'];
+let (remainder, chunks) = slice.as_rchunks();
+assert_eq!(remainder, &['l']);
+assert_eq!(chunks, &[['o', 'r'], ['e', 'm']]);array_chunks)Returns an iterator over N elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are array references and do not overlap. If N does not divide the
+length of the slice, then the last up to N-1 elements will be omitted and can be
+retrieved from the remainder function of the iterator.
This method is the const generic equivalent of chunks_exact.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(array_chunks)]
+let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.array_chunks();
+assert_eq!(iter.next().unwrap(), &['l', 'o']);
+assert_eq!(iter.next().unwrap(), &['r', 'e']);
+assert!(iter.next().is_none());
+assert_eq!(iter.remainder(), &['m']);slice_as_chunks)Splits the slice into a slice of N-element arrays,
+assuming that there’s no remainder.
This may only be called when
+N-element chunks (aka self.len() % N == 0).N != 0.#![feature(slice_as_chunks)]
+let slice: &mut [char] = &mut ['l', 'o', 'r', 'e', 'm', '!'];
+let chunks: &mut [[char; 1]] =
+ // SAFETY: 1-element chunks never have remainder
+ unsafe { slice.as_chunks_unchecked_mut() };
+chunks[0] = ['L'];
+assert_eq!(chunks, &[['L'], ['o'], ['r'], ['e'], ['m'], ['!']]);
+let chunks: &mut [[char; 3]] =
+ // SAFETY: The slice length (6) is a multiple of 3
+ unsafe { slice.as_chunks_unchecked_mut() };
+chunks[1] = ['a', 'x', '?'];
+assert_eq!(slice, &['L', 'o', 'r', 'a', 'x', '?']);
+
+// These would be unsound:
+// let chunks: &[[_; 5]] = slice.as_chunks_unchecked_mut() // The slice length is not a multiple of 5
+// let chunks: &[[_; 0]] = slice.as_chunks_unchecked_mut() // Zero-length chunks are never allowedslice_as_chunks)Splits the slice into a slice of N-element arrays,
+starting at the beginning of the slice,
+and a remainder slice with length strictly less than N.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(slice_as_chunks)]
+let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+let (chunks, remainder) = v.as_chunks_mut();
+remainder[0] = 9;
+for chunk in chunks {
+ *chunk = [count; 2];
+ count += 1;
+}
+assert_eq!(v, &[1, 1, 2, 2, 9]);slice_as_chunks)Splits the slice into a slice of N-element arrays,
+starting at the end of the slice,
+and a remainder slice with length strictly less than N.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(slice_as_chunks)]
+let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+let (remainder, chunks) = v.as_rchunks_mut();
+remainder[0] = 9;
+for chunk in chunks {
+ *chunk = [count; 2];
+ count += 1;
+}
+assert_eq!(v, &[9, 1, 1, 2, 2]);array_chunks)Returns an iterator over N elements of the slice at a time, starting at the
+beginning of the slice.
The chunks are mutable array references and do not overlap. If N does not divide
+the length of the slice, then the last up to N-1 elements will be omitted and
+can be retrieved from the into_remainder function of the iterator.
This method is the const generic equivalent of chunks_exact_mut.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(array_chunks)]
+let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.array_chunks_mut() {
+ *chunk = [count; 2];
+ count += 1;
+}
+assert_eq!(v, &[1, 1, 2, 2, 0]);array_windows)Returns an iterator over overlapping windows of N elements of a slice,
+starting at the beginning of the slice.
This is the const generic equivalent of windows.
If N is greater than the size of the slice, it will return no windows.
Panics if N is 0. This check will most probably get changed to a compile time
+error before this method gets stabilized.
#![feature(array_windows)]
+let slice = [0, 1, 2, 3];
+let mut iter = slice.array_windows();
+assert_eq!(iter.next().unwrap(), &[0, 1]);
+assert_eq!(iter.next().unwrap(), &[1, 2]);
+assert_eq!(iter.next().unwrap(), &[2, 3]);
+assert!(iter.next().is_none());Returns an iterator over chunk_size elements of the slice at a time, starting at the end
+of the slice.
The chunks are slices and do not overlap. If chunk_size does not divide the length of the
+slice, then the last chunk will not have length chunk_size.
See rchunks_exact for a variant of this iterator that returns chunks of always exactly
+chunk_size elements, and chunks for the same iterator but starting at the beginning
+of the slice.
Panics if chunk_size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.rchunks(2);
+assert_eq!(iter.next().unwrap(), &['e', 'm']);
+assert_eq!(iter.next().unwrap(), &['o', 'r']);
+assert_eq!(iter.next().unwrap(), &['l']);
+assert!(iter.next().is_none());Returns an iterator over chunk_size elements of the slice at a time, starting at the end
+of the slice.
The chunks are mutable slices, and do not overlap. If chunk_size does not divide the
+length of the slice, then the last chunk will not have length chunk_size.
See rchunks_exact_mut for a variant of this iterator that returns chunks of always
+exactly chunk_size elements, and chunks_mut for the same iterator but starting at the
+beginning of the slice.
Panics if chunk_size is 0.
let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.rchunks_mut(2) {
+ for elem in chunk.iter_mut() {
+ *elem += count;
+ }
+ count += 1;
+}
+assert_eq!(v, &[3, 2, 2, 1, 1]);Returns an iterator over chunk_size elements of the slice at a time, starting at the
+end of the slice.
The chunks are slices and do not overlap. If chunk_size does not divide the length of the
+slice, then the last up to chunk_size-1 elements will be omitted and can be retrieved
+from the remainder function of the iterator.
Due to each chunk having exactly chunk_size elements, the compiler can often optimize the
+resulting code better than in the case of rchunks.
See rchunks for a variant of this iterator that also returns the remainder as a smaller
+chunk, and chunks_exact for the same iterator but starting at the beginning of the
+slice.
Panics if chunk_size is 0.
let slice = ['l', 'o', 'r', 'e', 'm'];
+let mut iter = slice.rchunks_exact(2);
+assert_eq!(iter.next().unwrap(), &['e', 'm']);
+assert_eq!(iter.next().unwrap(), &['o', 'r']);
+assert!(iter.next().is_none());
+assert_eq!(iter.remainder(), &['l']);Returns an iterator over chunk_size elements of the slice at a time, starting at the end
+of the slice.
The chunks are mutable slices, and do not overlap. If chunk_size does not divide the
+length of the slice, then the last up to chunk_size-1 elements will be omitted and can be
+retrieved from the into_remainder function of the iterator.
Due to each chunk having exactly chunk_size elements, the compiler can often optimize the
+resulting code better than in the case of chunks_mut.
See rchunks_mut for a variant of this iterator that also returns the remainder as a
+smaller chunk, and chunks_exact_mut for the same iterator but starting at the beginning
+of the slice.
Panics if chunk_size is 0.
let v = &mut [0, 0, 0, 0, 0];
+let mut count = 1;
+
+for chunk in v.rchunks_exact_mut(2) {
+ for elem in chunk.iter_mut() {
+ *elem += count;
+ }
+ count += 1;
+}
+assert_eq!(v, &[0, 2, 2, 1, 1]);Returns an iterator over the slice producing non-overlapping runs +of elements using the predicate to separate them.
+The predicate is called for every pair of consecutive elements,
+meaning that it is called on slice[0] and slice[1],
+followed by slice[1] and slice[2], and so on.
let slice = &[1, 1, 1, 3, 3, 2, 2, 2];
+
+let mut iter = slice.chunk_by(|a, b| a == b);
+
+assert_eq!(iter.next(), Some(&[1, 1, 1][..]));
+assert_eq!(iter.next(), Some(&[3, 3][..]));
+assert_eq!(iter.next(), Some(&[2, 2, 2][..]));
+assert_eq!(iter.next(), None);This method can be used to extract the sorted subslices:
+ +let slice = &[1, 1, 2, 3, 2, 3, 2, 3, 4];
+
+let mut iter = slice.chunk_by(|a, b| a <= b);
+
+assert_eq!(iter.next(), Some(&[1, 1, 2, 3][..]));
+assert_eq!(iter.next(), Some(&[2, 3][..]));
+assert_eq!(iter.next(), Some(&[2, 3, 4][..]));
+assert_eq!(iter.next(), None);Returns an iterator over the slice producing non-overlapping mutable +runs of elements using the predicate to separate them.
+The predicate is called for every pair of consecutive elements,
+meaning that it is called on slice[0] and slice[1],
+followed by slice[1] and slice[2], and so on.
let slice = &mut [1, 1, 1, 3, 3, 2, 2, 2];
+
+let mut iter = slice.chunk_by_mut(|a, b| a == b);
+
+assert_eq!(iter.next(), Some(&mut [1, 1, 1][..]));
+assert_eq!(iter.next(), Some(&mut [3, 3][..]));
+assert_eq!(iter.next(), Some(&mut [2, 2, 2][..]));
+assert_eq!(iter.next(), None);This method can be used to extract the sorted subslices:
+ +let slice = &mut [1, 1, 2, 3, 2, 3, 2, 3, 4];
+
+let mut iter = slice.chunk_by_mut(|a, b| a <= b);
+
+assert_eq!(iter.next(), Some(&mut [1, 1, 2, 3][..]));
+assert_eq!(iter.next(), Some(&mut [2, 3][..]));
+assert_eq!(iter.next(), Some(&mut [2, 3, 4][..]));
+assert_eq!(iter.next(), None);Divides one slice into two at an index.
+The first will contain all indices from [0, mid) (excluding
+the index mid itself) and the second will contain all
+indices from [mid, len) (excluding the index len itself).
Panics if mid > len. For a non-panicking alternative see
+split_at_checked.
let v = [1, 2, 3, 4, 5, 6];
+
+{
+ let (left, right) = v.split_at(0);
+ assert_eq!(left, []);
+ assert_eq!(right, [1, 2, 3, 4, 5, 6]);
+}
+
+{
+ let (left, right) = v.split_at(2);
+ assert_eq!(left, [1, 2]);
+ assert_eq!(right, [3, 4, 5, 6]);
+}
+
+{
+ let (left, right) = v.split_at(6);
+ assert_eq!(left, [1, 2, 3, 4, 5, 6]);
+ assert_eq!(right, []);
+}Divides one mutable slice into two at an index.
+The first will contain all indices from [0, mid) (excluding
+the index mid itself) and the second will contain all
+indices from [mid, len) (excluding the index len itself).
Panics if mid > len. For a non-panicking alternative see
+split_at_mut_checked.
let mut v = [1, 0, 3, 0, 5, 6];
+let (left, right) = v.split_at_mut(2);
+assert_eq!(left, [1, 0]);
+assert_eq!(right, [3, 0, 5, 6]);
+left[1] = 2;
+right[1] = 4;
+assert_eq!(v, [1, 2, 3, 4, 5, 6]);Divides one slice into two at an index, without doing bounds checking.
+The first will contain all indices from [0, mid) (excluding
+the index mid itself) and the second will contain all
+indices from [mid, len) (excluding the index len itself).
For a safe alternative see split_at.
Calling this method with an out-of-bounds index is undefined behavior
+even if the resulting reference is not used. The caller has to ensure that
+0 <= mid <= self.len().
let v = [1, 2, 3, 4, 5, 6];
+
+unsafe {
+ let (left, right) = v.split_at_unchecked(0);
+ assert_eq!(left, []);
+ assert_eq!(right, [1, 2, 3, 4, 5, 6]);
+}
+
+unsafe {
+ let (left, right) = v.split_at_unchecked(2);
+ assert_eq!(left, [1, 2]);
+ assert_eq!(right, [3, 4, 5, 6]);
+}
+
+unsafe {
+ let (left, right) = v.split_at_unchecked(6);
+ assert_eq!(left, [1, 2, 3, 4, 5, 6]);
+ assert_eq!(right, []);
+}Divides one mutable slice into two at an index, without doing bounds checking.
+The first will contain all indices from [0, mid) (excluding
+the index mid itself) and the second will contain all
+indices from [mid, len) (excluding the index len itself).
For a safe alternative see split_at_mut.
Calling this method with an out-of-bounds index is undefined behavior
+even if the resulting reference is not used. The caller has to ensure that
+0 <= mid <= self.len().
let mut v = [1, 0, 3, 0, 5, 6];
+// scoped to restrict the lifetime of the borrows
+unsafe {
+ let (left, right) = v.split_at_mut_unchecked(2);
+ assert_eq!(left, [1, 0]);
+ assert_eq!(right, [3, 0, 5, 6]);
+ left[1] = 2;
+ right[1] = 4;
+}
+assert_eq!(v, [1, 2, 3, 4, 5, 6]);Divides one slice into two at an index, returning None if the slice is
+too short.
If mid ≤ len returns a pair of slices where the first will contain all
+indices from [0, mid) (excluding the index mid itself) and the
+second will contain all indices from [mid, len) (excluding the index
+len itself).
Otherwise, if mid > len, returns None.
let v = [1, -2, 3, -4, 5, -6];
+
+{
+ let (left, right) = v.split_at_checked(0).unwrap();
+ assert_eq!(left, []);
+ assert_eq!(right, [1, -2, 3, -4, 5, -6]);
+}
+
+{
+ let (left, right) = v.split_at_checked(2).unwrap();
+ assert_eq!(left, [1, -2]);
+ assert_eq!(right, [3, -4, 5, -6]);
+}
+
+{
+ let (left, right) = v.split_at_checked(6).unwrap();
+ assert_eq!(left, [1, -2, 3, -4, 5, -6]);
+ assert_eq!(right, []);
+}
+
+assert_eq!(None, v.split_at_checked(7));Divides one mutable slice into two at an index, returning None if the
+slice is too short.
If mid ≤ len returns a pair of slices where the first will contain all
+indices from [0, mid) (excluding the index mid itself) and the
+second will contain all indices from [mid, len) (excluding the index
+len itself).
Otherwise, if mid > len, returns None.
let mut v = [1, 0, 3, 0, 5, 6];
+
+if let Some((left, right)) = v.split_at_mut_checked(2) {
+ assert_eq!(left, [1, 0]);
+ assert_eq!(right, [3, 0, 5, 6]);
+ left[1] = 2;
+ right[1] = 4;
+}
+assert_eq!(v, [1, 2, 3, 4, 5, 6]);
+
+assert_eq!(None, v.split_at_mut_checked(7));Returns an iterator over subslices separated by elements that match
+pred. The matched element is not contained in the subslices.
let slice = [10, 40, 33, 20];
+let mut iter = slice.split(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[10, 40]);
+assert_eq!(iter.next().unwrap(), &[20]);
+assert!(iter.next().is_none());If the first element is matched, an empty slice will be the first item +returned by the iterator. Similarly, if the last element in the slice +is matched, an empty slice will be the last item returned by the +iterator:
+ +let slice = [10, 40, 33];
+let mut iter = slice.split(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[10, 40]);
+assert_eq!(iter.next().unwrap(), &[]);
+assert!(iter.next().is_none());If two matched elements are directly adjacent, an empty slice will be +present between them:
+ +let slice = [10, 6, 33, 20];
+let mut iter = slice.split(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[10]);
+assert_eq!(iter.next().unwrap(), &[]);
+assert_eq!(iter.next().unwrap(), &[20]);
+assert!(iter.next().is_none());Returns an iterator over mutable subslices separated by elements that
+match pred. The matched element is not contained in the subslices.
let mut v = [10, 40, 30, 20, 60, 50];
+
+for group in v.split_mut(|num| *num % 3 == 0) {
+ group[0] = 1;
+}
+assert_eq!(v, [1, 40, 30, 1, 60, 1]);Returns an iterator over subslices separated by elements that match
+pred. The matched element is contained in the end of the previous
+subslice as a terminator.
let slice = [10, 40, 33, 20];
+let mut iter = slice.split_inclusive(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[10, 40, 33]);
+assert_eq!(iter.next().unwrap(), &[20]);
+assert!(iter.next().is_none());If the last element of the slice is matched, +that element will be considered the terminator of the preceding slice. +That slice will be the last item returned by the iterator.
+ +let slice = [3, 10, 40, 33];
+let mut iter = slice.split_inclusive(|num| num % 3 == 0);
+
+assert_eq!(iter.next().unwrap(), &[3]);
+assert_eq!(iter.next().unwrap(), &[10, 40, 33]);
+assert!(iter.next().is_none());Returns an iterator over mutable subslices separated by elements that
+match pred. The matched element is contained in the previous
+subslice as a terminator.
let mut v = [10, 40, 30, 20, 60, 50];
+
+for group in v.split_inclusive_mut(|num| *num % 3 == 0) {
+ let terminator_idx = group.len()-1;
+ group[terminator_idx] = 1;
+}
+assert_eq!(v, [10, 40, 1, 20, 1, 1]);Returns an iterator over subslices separated by elements that match
+pred, starting at the end of the slice and working backwards.
+The matched element is not contained in the subslices.
let slice = [11, 22, 33, 0, 44, 55];
+let mut iter = slice.rsplit(|num| *num == 0);
+
+assert_eq!(iter.next().unwrap(), &[44, 55]);
+assert_eq!(iter.next().unwrap(), &[11, 22, 33]);
+assert_eq!(iter.next(), None);As with split(), if the first or last element is matched, an empty
+slice will be the first (or last) item returned by the iterator.
let v = &[0, 1, 1, 2, 3, 5, 8];
+let mut it = v.rsplit(|n| *n % 2 == 0);
+assert_eq!(it.next().unwrap(), &[]);
+assert_eq!(it.next().unwrap(), &[3, 5]);
+assert_eq!(it.next().unwrap(), &[1, 1]);
+assert_eq!(it.next().unwrap(), &[]);
+assert_eq!(it.next(), None);Returns an iterator over mutable subslices separated by elements that
+match pred, starting at the end of the slice and working
+backwards. The matched element is not contained in the subslices.
let mut v = [100, 400, 300, 200, 600, 500];
+
+let mut count = 0;
+for group in v.rsplit_mut(|num| *num % 3 == 0) {
+ count += 1;
+ group[0] = count;
+}
+assert_eq!(v, [3, 400, 300, 2, 600, 1]);Returns an iterator over subslices separated by elements that match
+pred, limited to returning at most n items. The matched element is
+not contained in the subslices.
The last element returned, if any, will contain the remainder of the +slice.
+Print the slice split once by numbers divisible by 3 (i.e., [10, 40],
+[20, 60, 50]):
let v = [10, 40, 30, 20, 60, 50];
+
+for group in v.splitn(2, |num| *num % 3 == 0) {
+ println!("{group:?}");
+}Returns an iterator over mutable subslices separated by elements that match
+pred, limited to returning at most n items. The matched element is
+not contained in the subslices.
The last element returned, if any, will contain the remainder of the +slice.
+let mut v = [10, 40, 30, 20, 60, 50];
+
+for group in v.splitn_mut(2, |num| *num % 3 == 0) {
+ group[0] = 1;
+}
+assert_eq!(v, [1, 40, 30, 1, 60, 50]);Returns an iterator over subslices separated by elements that match
+pred limited to returning at most n items. This starts at the end of
+the slice and works backwards. The matched element is not contained in
+the subslices.
The last element returned, if any, will contain the remainder of the +slice.
+Print the slice split once, starting from the end, by numbers divisible
+by 3 (i.e., [50], [10, 40, 30, 20]):
let v = [10, 40, 30, 20, 60, 50];
+
+for group in v.rsplitn(2, |num| *num % 3 == 0) {
+ println!("{group:?}");
+}Returns an iterator over subslices separated by elements that match
+pred limited to returning at most n items. This starts at the end of
+the slice and works backwards. The matched element is not contained in
+the subslices.
The last element returned, if any, will contain the remainder of the +slice.
+let mut s = [10, 40, 30, 20, 60, 50];
+
+for group in s.rsplitn_mut(2, |num| *num % 3 == 0) {
+ group[0] = 1;
+}
+assert_eq!(s, [1, 40, 30, 20, 60, 1]);slice_split_once)Splits the slice on the first element that matches the specified +predicate.
+If any matching elements are present in the slice, returns the prefix
+before the match and suffix after. The matching element itself is not
+included. If no elements match, returns None.
#![feature(slice_split_once)]
+let s = [1, 2, 3, 2, 4];
+assert_eq!(s.split_once(|&x| x == 2), Some((
+ &[1][..],
+ &[3, 2, 4][..]
+)));
+assert_eq!(s.split_once(|&x| x == 0), None);slice_split_once)Splits the slice on the last element that matches the specified +predicate.
+If any matching elements are present in the slice, returns the prefix
+before the match and suffix after. The matching element itself is not
+included. If no elements match, returns None.
#![feature(slice_split_once)]
+let s = [1, 2, 3, 2, 4];
+assert_eq!(s.rsplit_once(|&x| x == 2), Some((
+ &[1, 2, 3][..],
+ &[4][..]
+)));
+assert_eq!(s.rsplit_once(|&x| x == 0), None);Returns true if the slice contains an element with the given value.
This operation is O(n).
+Note that if you have a sorted slice, binary_search may be faster.
let v = [10, 40, 30];
+assert!(v.contains(&30));
+assert!(!v.contains(&50));If you do not have a &T, but some other value that you can compare
+with one (for example, String implements PartialEq<str>), you can
+use iter().any:
let v = [String::from("hello"), String::from("world")]; // slice of `String`
+assert!(v.iter().any(|e| e == "hello")); // search with `&str`
+assert!(!v.iter().any(|e| e == "hi"));Returns true if needle is a prefix of the slice or equal to the slice.
let v = [10, 40, 30];
+assert!(v.starts_with(&[10]));
+assert!(v.starts_with(&[10, 40]));
+assert!(v.starts_with(&v));
+assert!(!v.starts_with(&[50]));
+assert!(!v.starts_with(&[10, 50]));Always returns true if needle is an empty slice:
let v = &[10, 40, 30];
+assert!(v.starts_with(&[]));
+let v: &[u8] = &[];
+assert!(v.starts_with(&[]));Returns true if needle is a suffix of the slice or equal to the slice.
let v = [10, 40, 30];
+assert!(v.ends_with(&[30]));
+assert!(v.ends_with(&[40, 30]));
+assert!(v.ends_with(&v));
+assert!(!v.ends_with(&[50]));
+assert!(!v.ends_with(&[50, 30]));Always returns true if needle is an empty slice:
let v = &[10, 40, 30];
+assert!(v.ends_with(&[]));
+let v: &[u8] = &[];
+assert!(v.ends_with(&[]));Returns a subslice with the prefix removed.
+If the slice starts with prefix, returns the subslice after the prefix, wrapped in Some.
+If prefix is empty, simply returns the original slice. If prefix is equal to the
+original slice, returns an empty slice.
If the slice does not start with prefix, returns None.
let v = &[10, 40, 30];
+assert_eq!(v.strip_prefix(&[10]), Some(&[40, 30][..]));
+assert_eq!(v.strip_prefix(&[10, 40]), Some(&[30][..]));
+assert_eq!(v.strip_prefix(&[10, 40, 30]), Some(&[][..]));
+assert_eq!(v.strip_prefix(&[50]), None);
+assert_eq!(v.strip_prefix(&[10, 50]), None);
+
+let prefix : &str = "he";
+assert_eq!(b"hello".strip_prefix(prefix.as_bytes()),
+ Some(b"llo".as_ref()));Returns a subslice with the suffix removed.
+If the slice ends with suffix, returns the subslice before the suffix, wrapped in Some.
+If suffix is empty, simply returns the original slice. If suffix is equal to the
+original slice, returns an empty slice.
If the slice does not end with suffix, returns None.
let v = &[10, 40, 30];
+assert_eq!(v.strip_suffix(&[30]), Some(&[10, 40][..]));
+assert_eq!(v.strip_suffix(&[40, 30]), Some(&[10][..]));
+assert_eq!(v.strip_suffix(&[10, 40, 30]), Some(&[][..]));
+assert_eq!(v.strip_suffix(&[50]), None);
+assert_eq!(v.strip_suffix(&[50, 30]), None);Binary searches this slice for a given element. +If the slice is not sorted, the returned result is unspecified and +meaningless.
+If the value is found then Result::Ok is returned, containing the
+index of the matching element. If there are multiple matches, then any
+one of the matches could be returned. The index is chosen
+deterministically, but is subject to change in future versions of Rust.
+If the value is not found then Result::Err is returned, containing
+the index where a matching element could be inserted while maintaining
+sorted order.
See also binary_search_by, binary_search_by_key, and partition_point.
Looks up a series of four elements. The first is found, with a
+uniquely determined position; the second and third are not
+found; the fourth could match any position in [1, 4].
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+
+assert_eq!(s.binary_search(&13), Ok(9));
+assert_eq!(s.binary_search(&4), Err(7));
+assert_eq!(s.binary_search(&100), Err(13));
+let r = s.binary_search(&1);
+assert!(match r { Ok(1..=4) => true, _ => false, });If you want to find that whole range of matching items, rather than
+an arbitrary matching one, that can be done using partition_point:
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+
+let low = s.partition_point(|x| x < &1);
+assert_eq!(low, 1);
+let high = s.partition_point(|x| x <= &1);
+assert_eq!(high, 5);
+let r = s.binary_search(&1);
+assert!((low..high).contains(&r.unwrap()));
+
+assert!(s[..low].iter().all(|&x| x < 1));
+assert!(s[low..high].iter().all(|&x| x == 1));
+assert!(s[high..].iter().all(|&x| x > 1));
+
+// For something not found, the "range" of equal items is empty
+assert_eq!(s.partition_point(|x| x < &11), 9);
+assert_eq!(s.partition_point(|x| x <= &11), 9);
+assert_eq!(s.binary_search(&11), Err(9));If you want to insert an item to a sorted vector, while maintaining
+sort order, consider using partition_point:
let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+let num = 42;
+let idx = s.partition_point(|&x| x <= num);
+// If `num` is unique, `s.partition_point(|&x| x < num)` (with `<`) is equivalent to
+// `s.binary_search(&num).unwrap_or_else(|x| x)`, but using `<=` will allow `insert`
+// to shift less elements.
+s.insert(idx, num);
+assert_eq!(s, [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]);Binary searches this slice with a comparator function.
+The comparator function should return an order code that indicates
+whether its argument is Less, Equal or Greater the desired
+target.
+If the slice is not sorted or if the comparator function does not
+implement an order consistent with the sort order of the underlying
+slice, the returned result is unspecified and meaningless.
If the value is found then Result::Ok is returned, containing the
+index of the matching element. If there are multiple matches, then any
+one of the matches could be returned. The index is chosen
+deterministically, but is subject to change in future versions of Rust.
+If the value is not found then Result::Err is returned, containing
+the index where a matching element could be inserted while maintaining
+sorted order.
See also binary_search, binary_search_by_key, and partition_point.
Looks up a series of four elements. The first is found, with a
+uniquely determined position; the second and third are not
+found; the fourth could match any position in [1, 4].
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+
+let seek = 13;
+assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Ok(9));
+let seek = 4;
+assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(7));
+let seek = 100;
+assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(13));
+let seek = 1;
+let r = s.binary_search_by(|probe| probe.cmp(&seek));
+assert!(match r { Ok(1..=4) => true, _ => false, });Binary searches this slice with a key extraction function.
+Assumes that the slice is sorted by the key, for instance with
+sort_by_key using the same key extraction function.
+If the slice is not sorted by the key, the returned result is
+unspecified and meaningless.
If the value is found then Result::Ok is returned, containing the
+index of the matching element. If there are multiple matches, then any
+one of the matches could be returned. The index is chosen
+deterministically, but is subject to change in future versions of Rust.
+If the value is not found then Result::Err is returned, containing
+the index where a matching element could be inserted while maintaining
+sorted order.
See also binary_search, binary_search_by, and partition_point.
Looks up a series of four elements in a slice of pairs sorted by
+their second elements. The first is found, with a uniquely
+determined position; the second and third are not found; the
+fourth could match any position in [1, 4].
let s = [(0, 0), (2, 1), (4, 1), (5, 1), (3, 1),
+ (1, 2), (2, 3), (4, 5), (5, 8), (3, 13),
+ (1, 21), (2, 34), (4, 55)];
+
+assert_eq!(s.binary_search_by_key(&13, |&(a, b)| b), Ok(9));
+assert_eq!(s.binary_search_by_key(&4, |&(a, b)| b), Err(7));
+assert_eq!(s.binary_search_by_key(&100, |&(a, b)| b), Err(13));
+let r = s.binary_search_by_key(&1, |&(a, b)| b);
+assert!(match r { Ok(1..=4) => true, _ => false, });Sorts the slice without preserving the initial order of equal elements.
+This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not +allocate), and O(n * log(n)) worst-case.
+If T: Ord does not implement a total order the resulting order is unspecified. All
+original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if T: Ord panics.
The current implementation is based on ipnsort by Lukas Bergdoll and Orson Peters, which +combines the fast average case of quicksort with the fast worst case of heapsort, achieving +linear time on fully sorted and reversed inputs. On inputs with k distinct elements, the +expected time to sort the data is O(n * log(k)).
+It is typically faster than stable sorting, except in a few special cases, e.g., when the +slice is partially sorted.
+If T: Ord does not implement a total order, the implementation may panic.
let mut v = [-5, 4, 1, -3, 2];
+
+v.sort_unstable();
+assert!(v == [-5, -3, 1, 2, 4]);Sorts the slice with a comparator function, without preserving the initial order of +equal elements.
+This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not +allocate), and O(n * log(n)) worst-case.
+The comparator function should define a total ordering for the elements in the slice. If the +ordering is not total, the order of the elements is unspecified.
+If the comparator function does not implement a total order the resulting order is
+unspecified. All original elements will remain in the slice and any possible modifications
+via interior mutability are observed in the input. Same is true if the comparator function
+panics. A total order (for all a, b and c):
a < b, a == b or a > b is true, anda < b and b < c implies a < c. The same must hold for both == and >.For example, while f64 doesn’t implement Ord because NaN != NaN, we can use
+partial_cmp as our sort function when we know the slice doesn’t contain a NaN.
let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
+floats.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap());
+assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);The current implementation is based on ipnsort by Lukas Bergdoll and Orson Peters, which +combines the fast average case of quicksort with the fast worst case of heapsort, achieving +linear time on fully sorted and reversed inputs. On inputs with k distinct elements, the +expected time to sort the data is O(n * log(k)).
+It is typically faster than stable sorting, except in a few special cases, e.g., when the +slice is partially sorted.
+If T: Ord does not implement a total order, the implementation may panic.
let mut v = [5, 4, 1, 3, 2];
+v.sort_unstable_by(|a, b| a.cmp(b));
+assert!(v == [1, 2, 3, 4, 5]);
+
+// reverse sorting
+v.sort_unstable_by(|a, b| b.cmp(a));
+assert!(v == [5, 4, 3, 2, 1]);Sorts the slice with a key extraction function, without preserving the initial order of +equal elements.
+This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not +allocate), and O(n * log(n)) worst-case.
+If K: Ord does not implement a total order the resulting order is unspecified.
+All original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if K: Ord panics.
The current implementation is based on ipnsort by Lukas Bergdoll and Orson Peters, which +combines the fast average case of quicksort with the fast worst case of heapsort, achieving +linear time on fully sorted and reversed inputs. On inputs with k distinct elements, the +expected time to sort the data is O(n * log(k)).
+It is typically faster than stable sorting, except in a few special cases, e.g., when the +slice is partially sorted.
+If K: Ord does not implement a total order, the implementation may panic.
let mut v = [-5i32, 4, 1, -3, 2];
+
+v.sort_unstable_by_key(|k| k.abs());
+assert!(v == [1, 2, -3, 4, -5]);Reorder the slice such that the element at index after the reordering is at its final
+sorted position.
This reordering has the additional property that any value at position i < index will be
+less than or equal to any value at a position j > index. Additionally, this reordering is
+unstable (i.e. any number of equal elements may end up at position index), in-place (i.e.
+does not allocate), and runs in O(n) time. This function is also known as “kth element”
+in other libraries.
It returns a triplet of the following from the reordered slice: the subslice prior to
+index, the element at index, and the subslice after index; accordingly, the values in
+those two subslices will respectively all be less-than-or-equal-to and
+greater-than-or-equal-to the value of the element at index.
The current algorithm is an introselect implementation based on ipnsort by Lukas Bergdoll
+and Orson Peters, which is also the basis for sort_unstable. The fallback algorithm is
+Median of Medians using Tukey’s Ninther for pivot selection, which guarantees linear runtime
+for all inputs.
It is typically faster than stable sorting, except in a few special cases, e.g., when the
+slice is nearly fully sorted, where slice::sort may be faster.
Panics when index >= len(), meaning it always panics on empty slices.
let mut v = [-5i32, 4, 2, -3, 1];
+
+// Find the items less than or equal to the median, the median, and greater than or equal to
+// the median.
+let (lesser, median, greater) = v.select_nth_unstable(2);
+
+assert!(lesser == [-3, -5] || lesser == [-5, -3]);
+assert_eq!(median, &mut 1);
+assert!(greater == [4, 2] || greater == [2, 4]);
+
+// We are only guaranteed the slice will be one of the following, based on the way we sort
+// about the specified index.
+assert!(v == [-3, -5, 1, 2, 4] ||
+ v == [-5, -3, 1, 2, 4] ||
+ v == [-3, -5, 1, 4, 2] ||
+ v == [-5, -3, 1, 4, 2]);Reorder the slice with a comparator function such that the element at index after the
+reordering is at its final sorted position.
This reordering has the additional property that any value at position i < index will be
+less than or equal to any value at a position j > index using the comparator function.
+Additionally, this reordering is unstable (i.e. any number of equal elements may end up at
+position index), in-place (i.e. does not allocate), and runs in O(n) time. This
+function is also known as “kth element” in other libraries.
It returns a triplet of the following from the slice reordered according to the provided
+comparator function: the subslice prior to index, the element at index, and the subslice
+after index; accordingly, the values in those two subslices will respectively all be
+less-than-or-equal-to and greater-than-or-equal-to the value of the element at index.
The current algorithm is an introselect implementation based on ipnsort by Lukas Bergdoll
+and Orson Peters, which is also the basis for sort_unstable. The fallback algorithm is
+Median of Medians using Tukey’s Ninther for pivot selection, which guarantees linear runtime
+for all inputs.
It is typically faster than stable sorting, except in a few special cases, e.g., when the
+slice is nearly fully sorted, where slice::sort may be faster.
Panics when index >= len(), meaning it always panics on empty slices.
let mut v = [-5i32, 4, 2, -3, 1];
+
+// Find the items less than or equal to the median, the median, and greater than or equal to
+// the median as if the slice were sorted in descending order.
+let (lesser, median, greater) = v.select_nth_unstable_by(2, |a, b| b.cmp(a));
+
+assert!(lesser == [4, 2] || lesser == [2, 4]);
+assert_eq!(median, &mut 1);
+assert!(greater == [-3, -5] || greater == [-5, -3]);
+
+// We are only guaranteed the slice will be one of the following, based on the way we sort
+// about the specified index.
+assert!(v == [2, 4, 1, -5, -3] ||
+ v == [2, 4, 1, -3, -5] ||
+ v == [4, 2, 1, -5, -3] ||
+ v == [4, 2, 1, -3, -5]);Reorder the slice with a key extraction function such that the element at index after the
+reordering is at its final sorted position.
This reordering has the additional property that any value at position i < index will be
+less than or equal to any value at a position j > index using the key extraction function.
+Additionally, this reordering is unstable (i.e. any number of equal elements may end up at
+position index), in-place (i.e. does not allocate), and runs in O(n) time. This
+function is also known as “kth element” in other libraries.
It returns a triplet of the following from the slice reordered according to the provided key
+extraction function: the subslice prior to index, the element at index, and the subslice
+after index; accordingly, the values in those two subslices will respectively all be
+less-than-or-equal-to and greater-than-or-equal-to the value of the element at index.
The current algorithm is an introselect implementation based on ipnsort by Lukas Bergdoll
+and Orson Peters, which is also the basis for sort_unstable. The fallback algorithm is
+Median of Medians using Tukey’s Ninther for pivot selection, which guarantees linear runtime
+for all inputs.
It is typically faster than stable sorting, except in a few special cases, e.g., when the
+slice is nearly fully sorted, where slice::sort may be faster.
Panics when index >= len(), meaning it always panics on empty slices.
let mut v = [-5i32, 4, 1, -3, 2];
+
+// Find the items less than or equal to the median, the median, and greater than or equal to
+// the median as if the slice were sorted according to absolute value.
+let (lesser, median, greater) = v.select_nth_unstable_by_key(2, |a| a.abs());
+
+assert!(lesser == [1, 2] || lesser == [2, 1]);
+assert_eq!(median, &mut -3);
+assert!(greater == [4, -5] || greater == [-5, 4]);
+
+// We are only guaranteed the slice will be one of the following, based on the way we sort
+// about the specified index.
+assert!(v == [1, 2, -3, 4, -5] ||
+ v == [1, 2, -3, -5, 4] ||
+ v == [2, 1, -3, 4, -5] ||
+ v == [2, 1, -3, -5, 4]);slice_partition_dedup)Moves all consecutive repeated elements to the end of the slice according to the
+PartialEq trait implementation.
Returns two slices. The first contains no consecutive repeated elements. +The second contains all the duplicates in no specified order.
+If the slice is sorted, the first returned slice contains no duplicates.
+#![feature(slice_partition_dedup)]
+
+let mut slice = [1, 2, 2, 3, 3, 2, 1, 1];
+
+let (dedup, duplicates) = slice.partition_dedup();
+
+assert_eq!(dedup, [1, 2, 3, 2, 1]);
+assert_eq!(duplicates, [2, 3, 1]);slice_partition_dedup)Moves all but the first of consecutive elements to the end of the slice satisfying +a given equality relation.
+Returns two slices. The first contains no consecutive repeated elements. +The second contains all the duplicates in no specified order.
+The same_bucket function is passed references to two elements from the slice and
+must determine if the elements compare equal. The elements are passed in opposite order
+from their order in the slice, so if same_bucket(a, b) returns true, a is moved
+at the end of the slice.
If the slice is sorted, the first returned slice contains no duplicates.
+#![feature(slice_partition_dedup)]
+
+let mut slice = ["foo", "Foo", "BAZ", "Bar", "bar", "baz", "BAZ"];
+
+let (dedup, duplicates) = slice.partition_dedup_by(|a, b| a.eq_ignore_ascii_case(b));
+
+assert_eq!(dedup, ["foo", "BAZ", "Bar", "baz"]);
+assert_eq!(duplicates, ["bar", "Foo", "BAZ"]);slice_partition_dedup)Moves all but the first of consecutive elements to the end of the slice that resolve +to the same key.
+Returns two slices. The first contains no consecutive repeated elements. +The second contains all the duplicates in no specified order.
+If the slice is sorted, the first returned slice contains no duplicates.
+#![feature(slice_partition_dedup)]
+
+let mut slice = [10, 20, 21, 30, 30, 20, 11, 13];
+
+let (dedup, duplicates) = slice.partition_dedup_by_key(|i| *i / 10);
+
+assert_eq!(dedup, [10, 20, 30, 20, 11]);
+assert_eq!(duplicates, [21, 30, 13]);Rotates the slice in-place such that the first mid elements of the
+slice move to the end while the last self.len() - mid elements move to
+the front. After calling rotate_left, the element previously at index
+mid will become the first element in the slice.
This function will panic if mid is greater than the length of the
+slice. Note that mid == self.len() does not panic and is a no-op
+rotation.
Takes linear (in self.len()) time.
let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
+a.rotate_left(2);
+assert_eq!(a, ['c', 'd', 'e', 'f', 'a', 'b']);Rotating a subslice:
+ +let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
+a[1..5].rotate_left(1);
+assert_eq!(a, ['a', 'c', 'd', 'e', 'b', 'f']);Rotates the slice in-place such that the first self.len() - k
+elements of the slice move to the end while the last k elements move
+to the front. After calling rotate_right, the element previously at
+index self.len() - k will become the first element in the slice.
This function will panic if k is greater than the length of the
+slice. Note that k == self.len() does not panic and is a no-op
+rotation.
Takes linear (in self.len()) time.
let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
+a.rotate_right(2);
+assert_eq!(a, ['e', 'f', 'a', 'b', 'c', 'd']);Rotating a subslice:
+ +let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
+a[1..5].rotate_right(1);
+assert_eq!(a, ['a', 'e', 'b', 'c', 'd', 'f']);Fills self with elements by cloning value.
let mut buf = vec![0; 10];
+buf.fill(1);
+assert_eq!(buf, vec![1; 10]);Fills self with elements returned by calling a closure repeatedly.
This method uses a closure to create new values. If you’d rather
+Clone a given value, use fill. If you want to use the Default
+trait to generate values, you can pass Default::default as the
+argument.
let mut buf = vec![1; 10];
+buf.fill_with(Default::default);
+assert_eq!(buf, vec![0; 10]);Copies the elements from src into self.
The length of src must be the same as self.
This function will panic if the two slices have different lengths.
+Cloning two elements from a slice into another:
+ +let src = [1, 2, 3, 4];
+let mut dst = [0, 0];
+
+// Because the slices have to be the same length,
+// we slice the source slice from four elements
+// to two. It will panic if we don't do this.
+dst.clone_from_slice(&src[2..]);
+
+assert_eq!(src, [1, 2, 3, 4]);
+assert_eq!(dst, [3, 4]);Rust enforces that there can only be one mutable reference with no
+immutable references to a particular piece of data in a particular
+scope. Because of this, attempting to use clone_from_slice on a
+single slice will result in a compile failure:
let mut slice = [1, 2, 3, 4, 5];
+
+slice[..2].clone_from_slice(&slice[3..]); // compile fail!To work around this, we can use split_at_mut to create two distinct
+sub-slices from a slice:
let mut slice = [1, 2, 3, 4, 5];
+
+{
+ let (left, right) = slice.split_at_mut(2);
+ left.clone_from_slice(&right[1..]);
+}
+
+assert_eq!(slice, [4, 5, 3, 4, 5]);Copies all elements from src into self, using a memcpy.
The length of src must be the same as self.
If T does not implement Copy, use clone_from_slice.
This function will panic if the two slices have different lengths.
+Copying two elements from a slice into another:
+ +let src = [1, 2, 3, 4];
+let mut dst = [0, 0];
+
+// Because the slices have to be the same length,
+// we slice the source slice from four elements
+// to two. It will panic if we don't do this.
+dst.copy_from_slice(&src[2..]);
+
+assert_eq!(src, [1, 2, 3, 4]);
+assert_eq!(dst, [3, 4]);Rust enforces that there can only be one mutable reference with no
+immutable references to a particular piece of data in a particular
+scope. Because of this, attempting to use copy_from_slice on a
+single slice will result in a compile failure:
let mut slice = [1, 2, 3, 4, 5];
+
+slice[..2].copy_from_slice(&slice[3..]); // compile fail!To work around this, we can use split_at_mut to create two distinct
+sub-slices from a slice:
let mut slice = [1, 2, 3, 4, 5];
+
+{
+ let (left, right) = slice.split_at_mut(2);
+ left.copy_from_slice(&right[1..]);
+}
+
+assert_eq!(slice, [4, 5, 3, 4, 5]);Copies elements from one part of the slice to another part of itself, +using a memmove.
+src is the range within self to copy from. dest is the starting
+index of the range within self to copy to, which will have the same
+length as src. The two ranges may overlap. The ends of the two ranges
+must be less than or equal to self.len().
This function will panic if either range exceeds the end of the slice,
+or if the end of src is before the start.
Copying four bytes within a slice:
+ +let mut bytes = *b"Hello, World!";
+
+bytes.copy_within(1..5, 8);
+
+assert_eq!(&bytes, b"Hello, Wello!");Swaps all elements in self with those in other.
The length of other must be the same as self.
This function will panic if the two slices have different lengths.
+Swapping two elements across slices:
+ +let mut slice1 = [0, 0];
+let mut slice2 = [1, 2, 3, 4];
+
+slice1.swap_with_slice(&mut slice2[2..]);
+
+assert_eq!(slice1, [3, 4]);
+assert_eq!(slice2, [1, 2, 0, 0]);Rust enforces that there can only be one mutable reference to a
+particular piece of data in a particular scope. Because of this,
+attempting to use swap_with_slice on a single slice will result in
+a compile failure:
let mut slice = [1, 2, 3, 4, 5];
+slice[..2].swap_with_slice(&mut slice[3..]); // compile fail!To work around this, we can use split_at_mut to create two distinct
+mutable sub-slices from a slice:
let mut slice = [1, 2, 3, 4, 5];
+
+{
+ let (left, right) = slice.split_at_mut(2);
+ left.swap_with_slice(&mut right[1..]);
+}
+
+assert_eq!(slice, [4, 5, 3, 1, 2]);Transmute the slice to a slice of another type, ensuring alignment of the types is +maintained.
+This method splits the slice into three distinct slices: prefix, correctly aligned middle +slice of a new type, and the suffix slice. The middle part will be as big as possible under +the given alignment constraint and element size.
+This method has no purpose when either input element T or output element U are
+zero-sized and will return the original slice without splitting anything.
This method is essentially a transmute with respect to the elements in the returned
+middle slice, so all the usual caveats pertaining to transmute::<T, U> also apply here.
Basic usage:
+ +unsafe {
+ let bytes: [u8; 7] = [1, 2, 3, 4, 5, 6, 7];
+ let (prefix, shorts, suffix) = bytes.align_to::<u16>();
+ // less_efficient_algorithm_for_bytes(prefix);
+ // more_efficient_algorithm_for_aligned_shorts(shorts);
+ // less_efficient_algorithm_for_bytes(suffix);
+}Transmute the mutable slice to a mutable slice of another type, ensuring alignment of the +types is maintained.
+This method splits the slice into three distinct slices: prefix, correctly aligned middle +slice of a new type, and the suffix slice. The middle part will be as big as possible under +the given alignment constraint and element size.
+This method has no purpose when either input element T or output element U are
+zero-sized and will return the original slice without splitting anything.
This method is essentially a transmute with respect to the elements in the returned
+middle slice, so all the usual caveats pertaining to transmute::<T, U> also apply here.
Basic usage:
+ +unsafe {
+ let mut bytes: [u8; 7] = [1, 2, 3, 4, 5, 6, 7];
+ let (prefix, shorts, suffix) = bytes.align_to_mut::<u16>();
+ // less_efficient_algorithm_for_bytes(prefix);
+ // more_efficient_algorithm_for_aligned_shorts(shorts);
+ // less_efficient_algorithm_for_bytes(suffix);
+}portable_simd)Split a slice into a prefix, a middle of aligned SIMD types, and a suffix.
+This is a safe wrapper around slice::align_to, so has the same weak
+postconditions as that method. You’re only assured that
+self.len() == prefix.len() + middle.len() * LANES + suffix.len().
Notably, all of the following are possible:
+prefix.len() >= LANES.middle.is_empty() despite self.len() >= 3 * LANES.suffix.len() >= LANES.That said, this is a safe method, so if you’re only writing safe code, +then this can at most cause incorrect logic, not unsoundness.
+This will panic if the size of the SIMD type is different from
+LANES times that of the scalar.
At the time of writing, the trait restrictions on Simd<T, LANES> keeps
+that from ever happening, as only power-of-two numbers of lanes are
+supported. It’s possible that, in the future, those restrictions might
+be lifted in a way that would make it possible to see panics from this
+method for something like LANES == 3.
#![feature(portable_simd)]
+use core::simd::prelude::*;
+
+let short = &[1, 2, 3];
+let (prefix, middle, suffix) = short.as_simd::<4>();
+assert_eq!(middle, []); // Not enough elements for anything in the middle
+
+// They might be split in any possible way between prefix and suffix
+let it = prefix.iter().chain(suffix).copied();
+assert_eq!(it.collect::<Vec<_>>(), vec![1, 2, 3]);
+
+fn basic_simd_sum(x: &[f32]) -> f32 {
+ use std::ops::Add;
+ let (prefix, middle, suffix) = x.as_simd();
+ let sums = f32x4::from_array([
+ prefix.iter().copied().sum(),
+ 0.0,
+ 0.0,
+ suffix.iter().copied().sum(),
+ ]);
+ let sums = middle.iter().copied().fold(sums, f32x4::add);
+ sums.reduce_sum()
+}
+
+let numbers: Vec<f32> = (1..101).map(|x| x as _).collect();
+assert_eq!(basic_simd_sum(&numbers[1..99]), 4949.0);portable_simd)Split a mutable slice into a mutable prefix, a middle of aligned SIMD types, +and a mutable suffix.
+This is a safe wrapper around slice::align_to_mut, so has the same weak
+postconditions as that method. You’re only assured that
+self.len() == prefix.len() + middle.len() * LANES + suffix.len().
Notably, all of the following are possible:
+prefix.len() >= LANES.middle.is_empty() despite self.len() >= 3 * LANES.suffix.len() >= LANES.That said, this is a safe method, so if you’re only writing safe code, +then this can at most cause incorrect logic, not unsoundness.
+This is the mutable version of slice::as_simd; see that for examples.
This will panic if the size of the SIMD type is different from
+LANES times that of the scalar.
At the time of writing, the trait restrictions on Simd<T, LANES> keeps
+that from ever happening, as only power-of-two numbers of lanes are
+supported. It’s possible that, in the future, those restrictions might
+be lifted in a way that would make it possible to see panics from this
+method for something like LANES == 3.
is_sorted)Checks if the elements of this slice are sorted.
+That is, for each element a and its following element b, a <= b must hold. If the
+slice yields exactly zero or one element, true is returned.
Note that if Self::Item is only PartialOrd, but not Ord, the above definition
+implies that this function returns false if any two consecutive items are not
+comparable.
#![feature(is_sorted)]
+let empty: [i32; 0] = [];
+
+assert!([1, 2, 2, 9].is_sorted());
+assert!(![1, 3, 2, 4].is_sorted());
+assert!([0].is_sorted());
+assert!(empty.is_sorted());
+assert!(![0.0, 1.0, f32::NAN].is_sorted());is_sorted)Checks if the elements of this slice are sorted using the given comparator function.
+Instead of using PartialOrd::partial_cmp, this function uses the given compare
+function to determine whether two elements are to be considered in sorted order.
#![feature(is_sorted)]
+
+assert!([1, 2, 2, 9].is_sorted_by(|a, b| a <= b));
+assert!(![1, 2, 2, 9].is_sorted_by(|a, b| a < b));
+
+assert!([0].is_sorted_by(|a, b| true));
+assert!([0].is_sorted_by(|a, b| false));
+
+let empty: [i32; 0] = [];
+assert!(empty.is_sorted_by(|a, b| false));
+assert!(empty.is_sorted_by(|a, b| true));is_sorted)Checks if the elements of this slice are sorted using the given key extraction function.
+Instead of comparing the slice’s elements directly, this function compares the keys of the
+elements, as determined by f. Apart from that, it’s equivalent to is_sorted; see its
+documentation for more information.
#![feature(is_sorted)]
+
+assert!(["c", "bb", "aaa"].is_sorted_by_key(|s| s.len()));
+assert!(![-2i32, -1, 0, 3].is_sorted_by_key(|n| n.abs()));Returns the index of the partition point according to the given predicate +(the index of the first element of the second partition).
+The slice is assumed to be partitioned according to the given predicate.
+This means that all elements for which the predicate returns true are at the start of the slice
+and all elements for which the predicate returns false are at the end.
+For example, [7, 15, 3, 5, 4, 12, 6] is partitioned under the predicate x % 2 != 0
+(all odd numbers are at the start, all even at the end).
If this slice is not partitioned, the returned result is unspecified and meaningless, +as this method performs a kind of binary search.
+See also binary_search, binary_search_by, and binary_search_by_key.
let v = [1, 2, 3, 3, 5, 6, 7];
+let i = v.partition_point(|&x| x < 5);
+
+assert_eq!(i, 4);
+assert!(v[..i].iter().all(|&x| x < 5));
+assert!(v[i..].iter().all(|&x| !(x < 5)));If all elements of the slice match the predicate, including if the slice +is empty, then the length of the slice will be returned:
+ +let a = [2, 4, 8];
+assert_eq!(a.partition_point(|x| x < &100), a.len());
+let a: [i32; 0] = [];
+assert_eq!(a.partition_point(|x| x < &100), 0);If you want to insert an item to a sorted vector, while maintaining +sort order:
+ +let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
+let num = 42;
+let idx = s.partition_point(|&x| x <= num);
+s.insert(idx, num);
+assert_eq!(s, [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]);slice_take)Removes the subslice corresponding to the given range +and returns a reference to it.
+Returns None and does not modify the slice if the given
+range is out of bounds.
Note that this method only accepts one-sided ranges such as
+2.. or ..6, but not 2..6.
Taking the first three elements of a slice:
+ +#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c', 'd'];
+let mut first_three = slice.take(..3).unwrap();
+
+assert_eq!(slice, &['d']);
+assert_eq!(first_three, &['a', 'b', 'c']);Taking the last two elements of a slice:
+ +#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c', 'd'];
+let mut tail = slice.take(2..).unwrap();
+
+assert_eq!(slice, &['a', 'b']);
+assert_eq!(tail, &['c', 'd']);Getting None when range is out of bounds:
#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c', 'd'];
+
+assert_eq!(None, slice.take(5..));
+assert_eq!(None, slice.take(..5));
+assert_eq!(None, slice.take(..=4));
+let expected: &[char] = &['a', 'b', 'c', 'd'];
+assert_eq!(Some(expected), slice.take(..4));slice_take)Removes the subslice corresponding to the given range +and returns a mutable reference to it.
+Returns None and does not modify the slice if the given
+range is out of bounds.
Note that this method only accepts one-sided ranges such as
+2.. or ..6, but not 2..6.
Taking the first three elements of a slice:
+ +#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd'];
+let mut first_three = slice.take_mut(..3).unwrap();
+
+assert_eq!(slice, &mut ['d']);
+assert_eq!(first_three, &mut ['a', 'b', 'c']);Taking the last two elements of a slice:
+ +#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd'];
+let mut tail = slice.take_mut(2..).unwrap();
+
+assert_eq!(slice, &mut ['a', 'b']);
+assert_eq!(tail, &mut ['c', 'd']);Getting None when range is out of bounds:
#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd'];
+
+assert_eq!(None, slice.take_mut(5..));
+assert_eq!(None, slice.take_mut(..5));
+assert_eq!(None, slice.take_mut(..=4));
+let expected: &mut [_] = &mut ['a', 'b', 'c', 'd'];
+assert_eq!(Some(expected), slice.take_mut(..4));slice_take)Removes the first element of the slice and returns a reference +to it.
+Returns None if the slice is empty.
#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c'];
+let first = slice.take_first().unwrap();
+
+assert_eq!(slice, &['b', 'c']);
+assert_eq!(first, &'a');slice_take)Removes the first element of the slice and returns a mutable +reference to it.
+Returns None if the slice is empty.
#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c'];
+let first = slice.take_first_mut().unwrap();
+*first = 'd';
+
+assert_eq!(slice, &['b', 'c']);
+assert_eq!(first, &'d');slice_take)Removes the last element of the slice and returns a reference +to it.
+Returns None if the slice is empty.
#![feature(slice_take)]
+
+let mut slice: &[_] = &['a', 'b', 'c'];
+let last = slice.take_last().unwrap();
+
+assert_eq!(slice, &['a', 'b']);
+assert_eq!(last, &'c');slice_take)Removes the last element of the slice and returns a mutable +reference to it.
+Returns None if the slice is empty.
#![feature(slice_take)]
+
+let mut slice: &mut [_] = &mut ['a', 'b', 'c'];
+let last = slice.take_last_mut().unwrap();
+*last = 'd';
+
+assert_eq!(slice, &['a', 'b']);
+assert_eq!(last, &'d');get_many_mut)Returns mutable references to many indices at once, without doing any checks.
+For a safe alternative see get_many_mut.
Calling this method with overlapping or out-of-bounds indices is undefined behavior +even if the resulting references are not used.
+#![feature(get_many_mut)]
+
+let x = &mut [1, 2, 4];
+
+unsafe {
+ let [a, b] = x.get_many_unchecked_mut([0, 2]);
+ *a *= 10;
+ *b *= 100;
+}
+assert_eq!(x, &[10, 2, 400]);get_many_mut)Returns mutable references to many indices at once.
+Returns an error if any index is out-of-bounds, or if the same index was +passed more than once.
+#![feature(get_many_mut)]
+
+let v = &mut [1, 2, 3];
+if let Ok([a, b]) = v.get_many_mut([0, 2]) {
+ *a = 413;
+ *b = 612;
+}
+assert_eq!(v, &[413, 2, 612]);Sorts the slice, preserving initial order of equal elements.
+This sort is stable (i.e., does not reorder equal elements) and O(n * log(n)) +worst-case.
+If T: Ord does not implement a total order the resulting order is unspecified. All
+original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if T: Ord panics.
When applicable, unstable sorting is preferred because it is generally faster than stable
+sorting and it doesn’t allocate auxiliary memory. See
+sort_unstable. The exception are partially sorted slices, which
+may be better served with slice::sort.
The current implementation is based on driftsort by Orson Peters and Lukas Bergdoll, which +combines the fast average case of quicksort with the fast worst case and partial run +detection of mergesort, achieving linear time on fully sorted and reversed inputs. On inputs +with k distinct elements, the expected time to sort the data is O(n * log(k)).
+The auxiliary memory allocation behavior depends on the input length. Short slices are
+handled without allocation, medium sized slices allocate self.len() and beyond that it
+clamps at self.len() / 2.
If T: Ord does not implement a total order, the implementation may panic.
let mut v = [-5, 4, 1, -3, 2];
+
+v.sort();
+assert!(v == [-5, -3, 1, 2, 4]);Sorts the slice with a comparator function, preserving initial order of equal elements.
+This sort is stable (i.e., does not reorder equal elements) and O(n * log(n)) +worst-case.
+The comparator function should define a total ordering for the elements in the slice. If the +ordering is not total, the order of the elements is unspecified.
+If the comparator function does not implement a total order the resulting order is
+unspecified. All original elements will remain in the slice and any possible modifications
+via interior mutability are observed in the input. Same is true if the comparator function
+panics. A total order (for all a, b and c):
a < b, a == b or a > b is true, anda < b and b < c implies a < c. The same must hold for both == and >.For example, while f64 doesn’t implement Ord because NaN != NaN, we can use
+partial_cmp as our sort function when we know the slice doesn’t contain a NaN.
let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
+floats.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap());
+assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);The current implementation is based on driftsort by Orson Peters and Lukas Bergdoll, which +combines the fast average case of quicksort with the fast worst case and partial run +detection of mergesort, achieving linear time on fully sorted and reversed inputs. On inputs +with k distinct elements, the expected time to sort the data is O(n * log(k)).
+The auxiliary memory allocation behavior depends on the input length. Short slices are
+handled without allocation, medium sized slices allocate self.len() and beyond that it
+clamps at self.len() / 2.
If T: Ord does not implement a total order, the implementation may panic.
let mut v = [5, 4, 1, 3, 2];
+v.sort_by(|a, b| a.cmp(b));
+assert!(v == [1, 2, 3, 4, 5]);
+
+// reverse sorting
+v.sort_by(|a, b| b.cmp(a));
+assert!(v == [5, 4, 3, 2, 1]);Sorts the slice with a key extraction function, preserving initial order of equal elements.
+This sort is stable (i.e., does not reorder equal elements) and O(m * n * log(n)) +worst-case, where the key function is O(m).
+If K: Ord does not implement a total order the resulting order is unspecified.
+All original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if K: Ord panics.
The current implementation is based on driftsort by Orson Peters and Lukas Bergdoll, which +combines the fast average case of quicksort with the fast worst case and partial run +detection of mergesort, achieving linear time on fully sorted and reversed inputs. On inputs +with k distinct elements, the expected time to sort the data is O(n * log(k)).
+The auxiliary memory allocation behavior depends on the input length. Short slices are
+handled without allocation, medium sized slices allocate self.len() and beyond that it
+clamps at self.len() / 2.
If K: Ord does not implement a total order, the implementation may panic.
let mut v = [-5i32, 4, 1, -3, 2];
+
+v.sort_by_key(|k| k.abs());
+assert!(v == [1, 2, -3, 4, -5]);Sorts the slice with a key extraction function, preserving initial order of equal elements.
+This sort is stable (i.e., does not reorder equal elements) and O(m * n + n * +log(n)) worst-case, where the key function is O(m).
+During sorting, the key function is called at most once per element, by using temporary +storage to remember the results of key evaluation. The order of calls to the key function is +unspecified and may change in future versions of the standard library.
+If K: Ord does not implement a total order the resulting order is unspecified.
+All original elements will remain in the slice and any possible modifications via interior
+mutability are observed in the input. Same is true if K: Ord panics.
For simple key functions (e.g., functions that are property accesses or basic operations),
+sort_by_key is likely to be faster.
The current implementation is based on instruction-parallel-network sort by Lukas +Bergdoll, which combines the fast average case of randomized quicksort with the fast worst +case of heapsort, while achieving linear time on fully sorted and reversed inputs. And +O(k * log(n)) where k is the number of distinct elements in the input. It leverages +superscalar out-of-order execution capabilities commonly found in CPUs, to efficiently +perform the operation.
+In the worst case, the algorithm allocates temporary storage in a Vec<(K, usize)> the
+length of the slice.
let mut v = [-5i32, 4, 32, -3, 2];
+
+v.sort_by_cached_key(|k| k.to_string());
+assert!(v == [-3, -5, 2, 32, 4]);Copies self into a new Vec.
let s = [10, 40, 30];
+let x = s.to_vec();
+// Here, `s` and `x` can be modified independently.allocator_api)Copies self into a new Vec with an allocator.
#![feature(allocator_api)]
+
+use std::alloc::System;
+
+let s = [10, 40, 30];
+let x = s.to_vec_in(System);
+// Here, `s` and `x` can be modified independently.Flattens a slice of T into a single value Self::Output.
assert_eq!(["hello", "world"].concat(), "helloworld");
+assert_eq!([[1, 2], [3, 4]].concat(), [1, 2, 3, 4]);Flattens a slice of T into a single value Self::Output, placing a
+given separator between each.
assert_eq!(["hello", "world"].join(" "), "hello world");
+assert_eq!([[1, 2], [3, 4]].join(&0), [1, 2, 0, 3, 4]);
+assert_eq!([[1, 2], [3, 4]].join(&[0, 0][..]), [1, 2, 0, 0, 3, 4]);Flattens a slice of T into a single value Self::Output, placing a
+given separator between each.
assert_eq!(["hello", "world"].connect(" "), "hello world");
+assert_eq!([[1, 2], [3, 4]].connect(&0), [1, 2, 0, 3, 4]);Returns a vector containing a copy of this slice where each byte +is mapped to its ASCII upper case equivalent.
+ASCII letters ‘a’ to ‘z’ are mapped to ‘A’ to ‘Z’, +but non-ASCII letters are unchanged.
+To uppercase the value in-place, use make_ascii_uppercase.
Returns a vector containing a copy of this slice where each byte +is mapped to its ASCII lower case equivalent.
+ASCII letters ‘A’ to ‘Z’ are mapped to ‘a’ to ‘z’, +but non-ASCII letters are unchanged.
+To lowercase the value in-place, use make_ascii_lowercase.
try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub struct PrefixStore<S: Store, P: AsRef<[u8]>> { /* private fields */ }A key-value store that prefixes all keys with the given prefix.
+pub struct TypedStore<S: Store> { /* private fields */ }A key-value store that transparently handles serialization/deserialization.
+Fetch entry with given key.
+Update entry with given key to the given value.
+pub trait NestedStore: Store {
+ type Inner;
+
+ // Required methods
+ fn commit(self) -> Self::Inner;
+ fn rollback(self) -> Self::Inner;
+ fn has_pending_updates(&self) -> bool;
+ fn pending_update_byte_size(&self) -> usize;
+}A key-value store that supports the commit operation.
+Commit any changes to the underlying store.
+If this method is not called the changes may be discarded by the store.
+Whether there are any store updates pending to be committed.
+Size (in bytes) of any pending updates.
+pub trait Store {
+ // Required methods
+ fn get(&self, key: &[u8]) -> Option<Vec<u8>>;
+ fn insert(&mut self, key: &[u8], value: &[u8]);
+ fn remove(&mut self, key: &[u8]);
+ fn iter(&self) -> Box<dyn Iterator + '_>;
+ fn prefetch_prefixes(&mut self, prefixes: Vec<Prefix>, limit: u16);
+}A key-value store.
+Update entry with given key to the given value.
+Populate the in-memory tree with nodes for keys starting with given prefixes.
+Redirecting to ../../../oasis_runtime_sdk/storage/struct.TypedStore.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_runtime_sdk/struct.Version.html b/rust/oasis_runtime_sdk/struct.Version.html new file mode 100644 index 0000000000..111ebae4bf --- /dev/null +++ b/rust/oasis_runtime_sdk/struct.Version.html @@ -0,0 +1,41 @@ +pub struct Version {
+ pub major: u16,
+ pub minor: u16,
+ pub patch: u16,
+}A protocol or runtime version.
+major: u16§minor: u16§patch: u16try_default in case the value is null or
+undefined.clone_to_uninit)clone_to_uninit)key and return true if they are equal.pub fn call<C: Context, V: Validator + 'static>(
+ ctx: &C,
+ info: SubcallInfo,
+ validator: V,
+) -> Result<SubcallResult, Error>Perform a subcall.
+pub fn get_current_subcall_depth<C: Context>(_ctx: &C) -> u16The current subcall depth.
+pub struct AllowAllValidator;A validator which allows everything.
+pub struct SubcallInfo {
+ pub caller: CallerAddress,
+ pub method: String,
+ pub body: Value,
+ pub max_depth: u16,
+ pub max_gas: u64,
+}Information about a subcall to be dispatched.
+caller: CallerAddressAddress of the caller.
+method: StringMethod to call.
+body: ValueSubcall body.
+max_depth: u16Maximum subcall depth.
+max_gas: u64Maximum gas amount that can be consumed.
+source. Read moreclone_to_uninit)pub struct SubcallResult {
+ pub call_result: CallResult,
+ pub gas_used: u64,
+}Result of dispatching a subcall.
+call_result: CallResultResult of the subcall.
+gas_used: u64Gas used by the subcall.
+pub trait Validator {
+ // Required method
+ fn validate(&self, info: &SubcallInfo) -> Result<(), Error>;
+}Subcall validator.
+Module which contains utilities useful for testing and development.
+pub enum KeyManagerError {
+Show 33 variants
NotAuthenticated,
+ NotAuthorized,
+ InvalidEpoch(u64, u64),
+ InvalidGeneration(u64, u64),
+ GenerationFromFuture(u64, u64),
+ HeightNotFresh,
+ NotInitialized,
+ StateCorrupted,
+ StorageCorrupted,
+ PolicyRequired,
+ PolicyRollback,
+ PolicyChanged,
+ PolicyInvalidRuntime,
+ InsufficientKeyShares,
+ InsufficientSignatures,
+ RSKMissing,
+ REKNotPublished,
+ InvalidSignature(Error),
+ MasterSecretChecksumMismatch,
+ MasterSecretNotFound(u64),
+ MasterSecretNotReplicated(u64),
+ MasterSecretNotPublished,
+ EphemeralSecretNotFound(u64),
+ EphemeralSecretNotReplicated(u64),
+ EphemeralSecretNotPublished,
+ EphemeralSecretChecksumMismatch,
+ InvalidCiphertext,
+ StatusNotFound,
+ RuntimeMismatch,
+ ActiveDeploymentNotFound,
+ StateError(StateError),
+ VerificationError(Error),
+ Other(Error),
+}Key manager error.
+Mock key manager implementation.
+pub struct KeyPair {
+ pub input_keypair: InputKeyPair,
+ pub state_key: StateKey,
+ pub checksum: Vec<u8>,
+}A key pair managed by the key manager.
+input_keypair: InputKeyPairInput key pair (pk, sk)
+state_key: StateKeyState encryption key
+checksum: Vec<u8>Checksum of the key manager state.
+Generate a new random key (for testing).
+Create a KeyPair.
Create a KeyPair with only the public key.
try_default in case the value is null or
+undefined.clone_to_uninit)pub struct KeyPairId(pub [u8; 32]);A 256-bit key pair identifier.
+0: [u8; 32]try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)clone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub struct MockKeyManagerClient { /* private fields */ }None in case the
+identifier is not known yet (e.g. the client has not yet been initialized). Read moreclone_to_uninit)pub struct SignedPublicKey {
+ pub key: PublicKey,
+ pub checksum: Vec<u8>,
+ pub signature: Signature,
+ pub expiration: Option<u64>,
+}Signed public key.
+key: PublicKeyPublic key.
+checksum: Vec<u8>Checksum of the key manager state.
+signature: SignatureSign(sk, (key || checksum || runtime id || key pair id || epoch || expiration epoch)) from +the key manager.
+expiration: Option<u64>Expiration epoch.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.pub struct StateKey(pub [u8; 32]);A state encryption key.
+0: [u8; 32]try_default in case the value is null or
+undefined.clone_to_uninit)self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub struct TrustedSigners {
+ pub signers: HashSet<PublicKey>,
+ pub threshold: u64,
+}Set of trusted key manager signing keys.
+signers: HashSet<PublicKey>Set of trusted signers.
+threshold: u64Threshold for determining if enough valid signatures are present.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub fn pk_ed25519() -> PublicKeyTest Ed25519 public key +A +.
+pub fn sigspec() -> SignatureAddressSpecTest address derivation information +A +.
+pub fn pk_ed25519() -> PublicKeyTest Ed25519 public key +B +.
+pub fn sigspec() -> SignatureAddressSpecTest address derivation information +B +.
+pub fn pk_ed25519() -> PublicKeyTest Ed25519 public key +C +.
+pub fn sigspec() -> SignatureAddressSpecTest address derivation information +C +.
+pub fn pk_secp256k1() -> PublicKeyTest Secp256k1 public key +D +.
+pub fn sigspec() -> SignatureAddressSpecTest address derivation information +D +.
+pub fn pk_secp256k1() -> PublicKeyTest Secp256k1 public key +E +.
+pub fn sigspec() -> SignatureAddressSpecTest address derivation information +E +.
+pub fn pk_sr25519() -> PublicKeyTest Sr25519 public key +F +.
+pub fn sigspec() -> SignatureAddressSpecTest address derivation information +F +.
+pub fn pk_sr25519() -> PublicKeyTest Sr25519 public key +G +.
+pub fn sigspec() -> SignatureAddressSpecTest address derivation information +G +.
+pub fn empty_store() -> MKVSStore<OverlayTree<Tree>>Create an empty MKVS store.
+pub fn transaction() -> TransactionCreate a new mock transaction.
+Mock dispatch context for use in tests.
+pub struct CallOptions {
+ pub fee: Fee,
+ pub encrypted: bool,
+}Options that can be used during mock signer calls.
+fee: FeeTransaction fee.
+encrypted: boolShould the call be encrypted.
+source. Read moreclone_to_uninit)pub struct Config;pub struct EmptyRuntime;A mock runtime that only has the core module.
+None, a key manager connection will not be
+established on startup.None, consensus layer integrity
+verification will not be performed.STATE_VERSION.pub struct Mock {
+ pub host_info: HostInfo,
+ pub runtime_header: Header,
+ pub runtime_round_results: RoundResults,
+ pub consensus_state: ConsensusState,
+ pub history: Box<dyn HistoryHost>,
+ pub epoch: EpochTime,
+ pub max_messages: u32,
+}Mock dispatch context factory.
+host_info: HostInfo§runtime_header: Header§runtime_round_results: RoundResults§consensus_state: ConsensusState§history: Box<dyn HistoryHost>§epoch: EpochTime§max_messages: u32Create a new mock dispatch context.
+Create a new mock dispatch context.
+Create an instance with the given local configuration.
+pub struct Signer { /* private fields */ }A mock signer for use during tests.
+Create a new mock signer using the given nonce and signature spec.
+Address specification for this signer.
+Dispatch a call to the given method.
+Dispatch a call to the given method with the given options.
+pub const ADDRESS_BECH32_HRP: Hrp;Human readable part for Bech32-encoded addresses.
+pub const ADDRESS_RUNTIME_V0_CONTEXT: &[u8] = b"oasis-core/address: runtime";V0 runtime address context.
+pub const ADDRESS_RUNTIME_V0_VERSION: u8 = 0;V0 runtime address version.
+pub const ADDRESS_V0_ED25519_CONTEXT: &[u8] = b"oasis-core/address: staking";V0 Ed25519 addres context (shared with consensus layer).
+pub const ADDRESS_V0_MODULE_CONTEXT: &[u8] = b"oasis-runtime-sdk/address: module";V0 module address context.
+pub const ADDRESS_V0_MULTISIG_CONTEXT: &[u8] = b"oasis-runtime-sdk/address: multisig";V0 multisig address context.
+pub const ADDRESS_V0_SECP256K1ETH_CONTEXT: &[u8] = b"oasis-runtime-sdk/address: secp256k1eth";V0 Secp256k1 address context.
+pub const ADDRESS_V0_SR25519_CONTEXT: &[u8] = b"oasis-runtime-sdk/address: sr25519";V0 Sr25519 address context.
+pub const ADDRESS_V0_VERSION: u8 = 0;V0 address version.
+pub enum Error {
+ MalformedAddress,
+}Error.
+pub enum SignatureAddressSpec {
+ Ed25519(PublicKey),
+ Secp256k1Eth(PublicKey),
+ Sr25519(PublicKey),
+}Information for signature-based authentication and public key-based address derivation.
+Ed25519 address derivation compatible with the consensus layer.
+Ethereum-compatible address derivation from Secp256k1 public keys.
+Sr25519 address derivation.
+Try to construct an authentication/address derivation specification from the given public
+key. In case the given scheme is not supported, it returns None.
Public key of the authentication/address derivation specification.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)key and return true if they are equal.Account address type.
+pub struct Address(/* private fields */);An account address.
+Creates a new address from a context, version and data.
+Tries to create a new address from raw bytes.
+Convert the address into raw bytes.
+Creates a new address for a specific module and kind.
+Creates a new address for a specific module and raw kind.
+Creates a new runtime address.
+Creates a new address from a public key.
+Creates a new address from a multisig configuration.
+Creates a new address from an Ethereum-compatible address.
+Creates a new address from a consensus-layer Ed25519 public key.
+This is a convenience wrapper and the same result can be obtained by going via the
+from_sigspec method using the same Ed25519 public key.
Tries to create a new address from Bech32-encoded string.
+try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)clone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub const CALL_DATA_KEY_PAIR_ID_CONTEXT_BASE: &[u8] = b"oasis-runtime-sdk/private: tx";Call data key pair ID domain separation context base.
+Types related to call formats.
+pub struct CallEnvelopeX25519DeoxysII {
+ pub pk: PublicKey,
+ pub nonce: [u8; 15],
+ pub epoch: u64,
+ pub data: Vec<u8>,
+}A call envelope when using the EncryptedX25519DeoxysII format.
+pk: PublicKeyCaller’s ephemeral public key used for X25519.
+nonce: [u8; 15]Nonce.
+epoch: u64Epoch of the ephemeral runtime key.
+data: Vec<u8>Encrypted call data.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct ResultEnvelopeX25519DeoxysII {
+ pub nonce: [u8; 15],
+ pub data: Vec<u8>,
+}A result envelope when using the EncryptedX25519DeoxysII format.
+nonce: [u8; 15]Nonce.
+data: Vec<u8>Encrypted call data.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)Types defined by the SDK.
+pub struct MessageEventHookInvocation {
+ pub hook_name: String,
+ pub payload: Value,
+}Handler name and context to be called after message is executed.
+hook_name: String§payload: Valuesource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct MessageResult {
+ pub event: MessageEvent,
+ pub context: Value,
+}Result of a message being processed by the consensus layer combined with the context for the +result handler.
+event: MessageEvent§context: Valuesource. Read moreclone_to_uninit)pub type MessageEvent = MessageEvent;Result of a message being processed by the consensus layer.
+struct MessageEvent {
+ pub module: String,
+ pub code: u32,
+ pub index: u32,
+ pub result: Option<Value>,
+}module: String§code: u32§index: u32§result: Option<Value>pub enum Error {
+ NameTooLong {
+ length: usize,
+ },
+}pub struct BaseUnits(pub u128, pub Denomination);Token amount of given denomination in base units.
+0: u128§1: DenominationCreates a new token amount of the given denomination.
+Denomination of the token amount.
+try_default in case the value is null or
+undefined.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.pub struct Denomination(/* private fields */);Name/type of the token.
+Maximum length of a denomination.
+Denomination in native token.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.self and other) and is used by the <=
+operator. Read moreclone_to_uninit)key and return true if they are equal.self into the result. Lower case
+letters are used (e.g. f9b4ca)self into the result. Upper case
+letters are used (e.g. F9B4CA)pub const LATEST_TRANSACTION_VERSION: u16 = 1;The latest transaction format version.
+pub const SIGNATURE_CONTEXT_BASE: &[u8] = b"oasis-runtime-sdk/tx: v0";Transaction signature domain separation context base.
+pub enum AddressSpec {
+ Signature(SignatureAddressSpec),
+ Multisig(Config),
+ Internal(CallerAddress),
+}Common information that specifies an address as well as how to authenticate.
+For signature authentication.
+For multisig authentication.
+For internal child calls (cannot be serialized/deserialized).
+Returns the public key when the address spec represents a single public key.
+Derives the caller address.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub enum AuthProof {
+ Signature(Signature),
+ Multisig(SignatureSetOwned),
+ Module(String),
+ Invalid,
+}A container for data that authenticates a transaction.
+For signature authentication.
+For multisig authentication.
+A flag to use module-controlled decoding. The string is an encoding scheme name that a +module must handle. The scheme name must not be empty.
+A non-serializable placeholder value.
+try_default in case the value is null or
+undefined.clone_to_uninit)#[repr(u8)]pub enum CallFormat {
+ Plain = 0,
+ EncryptedX25519DeoxysII = 1,
+}Format used for encoding the call (and output) information.
+Plain text call data.
+Encrypted call data using X25519 for key exchange and Deoxys-II for symmetric encryption.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)clone_to_uninit)key and return true if they are equal.pub enum CallResult {
+ Ok(Value),
+ Failed {
+ module: String,
+ code: u32,
+ message: String,
+ },
+ Unknown(Value),
+}Call result.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub enum CallerAddress {
+ Address(Address),
+ EthAddress([u8; 20]),
+}A caller address.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub enum Error {
+ UnsupportedVersion,
+ MalformedTransaction(Error),
+ SignerNotFound,
+ FailedToSign(Error),
+}Error.
+Transaction types.
+pub struct AuthInfo {
+ pub signer_info: Vec<SignerInfo>,
+ pub fee: Fee,
+ pub not_before: Option<u64>,
+ pub not_after: Option<u64>,
+}Transaction authentication information.
+signer_info: Vec<SignerInfo>Transaction signer information.
+fee: FeeFee payment information.
+not_before: Option<u64>Earliest round when the transaction is valid.
+not_after: Option<u64>Latest round when the transaction is valid.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct Call {
+ pub format: CallFormat,
+ pub method: String,
+ pub body: Value,
+ pub read_only: bool,
+}Method call.
+format: CallFormatCall format.
+method: StringMethod name.
+body: ValueMethod body.
+read_only: boolRead-only flag.
+A read-only call cannot make any changes to runtime state. Any attempt at modifying state +will result in the call failing.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct Fee {
+ pub amount: BaseUnits,
+ pub gas: u64,
+ pub consensus_messages: u32,
+ pub proxy: Option<FeeProxy>,
+}Transaction fee.
+amount: BaseUnitsAmount of base units paid as fee for transaction processing.
+gas: u64Maximum amount of gas paid for.
+consensus_messages: u32Maximum amount of emitted consensus messages paid for. Zero means that up to the maximum +number of per-batch messages can be emitted.
+proxy: Option<FeeProxy>Proxy which has authorized the fees to be paid.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct FeeProxy {
+ pub module: String,
+ pub id: Vec<u8>,
+}Information about a fee proxy.
+module: StringModule that will handle the proxy payment.
+id: Vec<u8>Module-specific identifier that will handle fee payments for the transaction signer.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct SignerInfo {
+ pub address_spec: AddressSpec,
+ pub nonce: u64,
+}Transaction signer information.
+address_spec: AddressSpec§nonce: u64Create a new signer info from a signature address specification and nonce.
+Create a new signer info from a multisig configuration and a nonce.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Transaction {
+ pub version: u16,
+ pub call: Call,
+ pub auth_info: AuthInfo,
+}Transaction.
+version: u16§call: Call§auth_info: AuthInfoCreate a new (unsigned) transaction.
+Prepare this transaction for signing.
+Set maximum amount of gas that the transaction can use.
+Amount of fee to pay for transaction execution.
+Set amount of fee to pay for transaction execution.
+Set a proxy for paying the transaction fee.
+Append a new transaction signer information to the transaction.
+Append a new transaction signer information with a signature address specification to the +transaction.
+Append a new transaction signer information with a multisig address specification to the +transaction.
+Perform basic validation on the transaction.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct TransactionSigner { /* private fields */ }Transaction signer.
+Construct a new transaction signer for the given transaction.
+Sign the transaction and append the signature.
+The signer must be specified in the auth_info field.
Finalize the signing process and return the (signed) unverified transaction.
+pub struct UnverifiedTransaction(pub Vec<u8>, pub Vec<AuthProof>);An unverified signed transaction.
+0: Vec<u8>§1: Vec<AuthProof>Verify and deserialize the unverified transaction.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub enum Error {
+Show 33 variants
InvalidArgument,
+ CodeTooLarge(u32, u32),
+ CodeMalformed,
+ UnsupportedABI,
+ CodeMissingRequiredExport(String),
+ CodeDeclaresReservedExport(String),
+ CodeDeclaresStartFunction,
+ CodeDeclaresTooManyMemories,
+ CodeNotFound(u64),
+ InstanceNotFound(u64),
+ ModuleLoadingFailed,
+ ExecutionFailed(Error),
+ Forbidden,
+ Unsupported,
+ InsufficientCallerBalance,
+ ResultTooLarge(u32, u32),
+ TooManySubcalls(u16, u16),
+ CodeAlreadyUpgraded(u64),
+ Abort(Error),
+ StorageKeyTooLarge(u32, u32),
+ StorageValueTooLarge(u32, u32),
+ CryptoMsgTooLarge(u32, u32),
+ CryptoMalformedPublicKey,
+ CodeDeclaresMultipleSubVersions,
+ CryptoMalformedPrivateKey,
+ CryptoMalformedKey,
+ CryptoMalformedNonce,
+ CryptoKeyDerivationFunctionFailure,
+ ModuleUsesFloatingPoint,
+ CodeDeclaresTooManyFunctions,
+ CodeDeclaresTooManyLocals,
+ Core(Error),
+ Contract(ContractError),
+}Errors emitted by the contracts module.
+Ok(err) (where err is a dispatcher error) when batch
+should abort or Err(self) when this is just a regular error.pub enum Event {}Events emitted by the contracts module.
+Smart contracts module.
+pub const CODE: &[u8];Uploaded code.
+pub const CODE_INFO: &[u8];Information about uploaded code.
+pub const INSTANCE_INFO: &[u8];Information about the deployed contract instance.
+pub const INSTANCE_STATE: &[u8];Per-instance key/value store.
+pub const NEXT_CODE_IDENTIFIER: &[u8];Next code identifier (u64).
+pub const NEXT_INSTANCE_IDENTIFIER: &[u8];Next instance identifier (u64).
+State schema constants.
+pub struct GasCosts {Show 27 fields
+ pub tx_upload: u64,
+ pub tx_upload_per_byte: u64,
+ pub tx_instantiate: u64,
+ pub tx_call: u64,
+ pub tx_upgrade: u64,
+ pub tx_change_upgrade_policy: u64,
+ pub subcall_dispatch: u64,
+ pub wasm_public_storage_get_base: u64,
+ pub wasm_public_storage_insert_base: u64,
+ pub wasm_public_storage_remove_base: u64,
+ pub wasm_public_storage_key_byte: u64,
+ pub wasm_public_storage_value_byte: u64,
+ pub wasm_confidential_storage_get_base: u64,
+ pub wasm_confidential_storage_insert_base: u64,
+ pub wasm_confidential_storage_remove_base: u64,
+ pub wasm_confidential_storage_key_byte: u64,
+ pub wasm_confidential_storage_value_byte: u64,
+ pub wasm_env_query_base: u64,
+ pub wasm_crypto_ecdsa_recover: u64,
+ pub wasm_crypto_signature_verify_ed25519: u64,
+ pub wasm_crypto_signature_verify_secp256k1: u64,
+ pub wasm_crypto_signature_verify_sr25519: u64,
+ pub wasm_crypto_x25519_derive_symmetric: u64,
+ pub wasm_crypto_deoxysii_base: u64,
+ pub wasm_crypto_deoxysii_byte: u64,
+ pub wasm_crypto_random_bytes_base: u64,
+ pub wasm_crypto_random_bytes_byte: u64,
+}Gas costs.
+tx_upload: u64§tx_upload_per_byte: u64§tx_instantiate: u64§tx_call: u64§tx_upgrade: u64§tx_change_upgrade_policy: u64§subcall_dispatch: u64§wasm_public_storage_get_base: u64§wasm_public_storage_insert_base: u64§wasm_public_storage_remove_base: u64§wasm_public_storage_key_byte: u64§wasm_public_storage_value_byte: u64§wasm_confidential_storage_get_base: u64§wasm_confidential_storage_insert_base: u64§wasm_confidential_storage_remove_base: u64§wasm_confidential_storage_key_byte: u64§wasm_confidential_storage_value_byte: u64§wasm_env_query_base: u64§wasm_crypto_ecdsa_recover: u64§wasm_crypto_signature_verify_ed25519: u64§wasm_crypto_signature_verify_secp256k1: u64§wasm_crypto_signature_verify_sr25519: u64§wasm_crypto_x25519_derive_symmetric: u64§wasm_crypto_deoxysii_base: u64§wasm_crypto_deoxysii_byte: u64§wasm_crypto_random_bytes_base: u64§wasm_crypto_random_bytes_byte: u64try_default in case the value is null or
+undefined.clone_to_uninit)pub struct Genesis {
+ pub parameters: Parameters,
+}Genesis state for the contracts module.
+parameters: Parameterstry_default in case the value is null or
+undefined.clone_to_uninit)pub struct LocalConfig {
+ pub query_custom_max_gas: u64,
+ pub max_instance_raw_storage_query_items: u64,
+}Local configuration that can be provided by the node operator.
+query_custom_max_gas: u64Gas limit for custom queries that invoke smart contracts.
+max_instance_raw_storage_query_items: u64Maximum number of items per page in InstanceRawStorage query result.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Module<Cfg: Config> { /* private fields */ }Self is a tuple).pub struct Parameters {Show 13 fields
+ pub max_code_size: u32,
+ pub max_stack_size: u32,
+ pub max_memory_pages: u32,
+ pub max_wasm_functions: u32,
+ pub max_wasm_locals: u32,
+ pub max_subcall_depth: u16,
+ pub max_subcall_count: u16,
+ pub max_result_size_bytes: u32,
+ pub max_query_size_bytes: u32,
+ pub max_storage_key_size_bytes: u32,
+ pub max_storage_value_size_bytes: u32,
+ pub max_crypto_signature_verify_message_size_bytes: u32,
+ pub gas_costs: GasCosts,
+}Parameters for the contracts module.
+max_code_size: u32§max_stack_size: u32§max_memory_pages: u32§max_wasm_functions: u32§max_wasm_locals: u32§max_subcall_depth: u16§max_subcall_count: u16§max_result_size_bytes: u32§max_query_size_bytes: u32§max_storage_key_size_bytes: u32§max_storage_value_size_bytes: u32§max_crypto_signature_verify_message_size_bytes: u32§gas_costs: GasCostssource. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub trait Config: 'static { }Module configuration.
+#[repr(u8)]pub enum ABI {
+ OasisV1 = 1,
+}ABI that the given contract should conform to.
+Custom Oasis SDK-specific ABI (v1).
+try_default in case the value is null or
+undefined.clone_to_uninit)clone_to_uninit)key and return true if they are equal.key and return true if they are equal.pub enum Policy {
+ Nobody,
+ Address(Address),
+ Everyone,
+}A generic policy that specifies who is allowed to perform an action.
+try_default in case the value is null or
+undefined.clone_to_uninit)clone_to_uninit)#[repr(u8)]pub enum PublicKeyKind {
+ Transaction = 1,
+}Public key kind.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)#[repr(u32)]pub enum StoreKind {
+ Public = 0,
+ Confidential = 1,
+}Exposed wrapper for oasis-contract-sdk-types::StoreKind.
+try_default in case the value is null or
+undefined.clone_to_uninit)Contracts module types.
+pub struct Call {
+ pub id: InstanceId,
+ pub data: Vec<u8>,
+ pub tokens: Vec<BaseUnits>,
+}Contract call.
+id: InstanceIdInstance identifier.
+data: Vec<u8>Call arguments.
+tokens: Vec<BaseUnits>Tokens that should be sent to the contract as part of the call.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct CallResult(pub Vec<u8>);Contract call result.
+0: Vec<u8>source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct ChangeUpgradePolicy {
+ pub id: InstanceId,
+ pub upgrades_policy: Policy,
+}Change upgrade policy call.
+id: InstanceIdInstance identifier.
+upgrades_policy: PolicyUpdated upgrade policy.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Code {
+ pub id: CodeId,
+ pub hash: Hash,
+ pub abi: ABI,
+ pub abi_sv: u32,
+ pub uploader: Address,
+ pub instantiate_policy: Policy,
+}Stored code information.
+id: CodeIdUnique code identifier.
+hash: HashCode hash.
+abi: ABIABI.
+abi_sv: u32ABI sub-version.
+uploader: AddressCode uploader address.
+instantiate_policy: PolicyWho is allowed to instantiate this code.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct CodeId(/* private fields */);Unique stored code identifier.
+try_default in case the value is null or
+undefined.clone_to_uninit)clone_to_uninit)key and return true if they are equal.key and return true if they are equal.pub struct CodeQuery {
+ pub id: CodeId,
+}Code information query.
+id: CodeIdCode identifier.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct CodeStorageQuery {
+ pub id: CodeId,
+}Code storage information query.
+id: CodeIdCode identifier.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct CodeStorageQueryResult {
+ pub code: Vec<u8>,
+}Code storage query result.
+code: Vec<u8>Stored contract code.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct ContractEvent {
+ pub id: InstanceId,
+ pub data: Vec<u8>,
+}An event emitted from a contract, wrapped to include additional metadata.
+id: InstanceIdIdentifier of the instance that emitted the event.
+data: Vec<u8>Raw event data emitted by the instance.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct CustomQuery {
+ pub id: InstanceId,
+ pub data: Vec<u8>,
+}Custom contract query.
+id: InstanceIdInstance identifier.
+data: Vec<u8>Query arguments.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct CustomQueryResult(pub Vec<u8>);Custom query result.
+0: Vec<u8>source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Instance {
+ pub id: InstanceId,
+ pub code_id: CodeId,
+ pub creator: Address,
+ pub upgrades_policy: Policy,
+}Deployed code instance information.
+id: InstanceIdUnique instance identifier.
+code_id: CodeIdIdentifier of code used by the instance.
+creator: AddressInstance creator address.
+upgrades_policy: PolicyWho is allowed to upgrade this instance.
+Address associated with a specific contract instance.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct InstanceId(/* private fields */);Unique deployed code instance identifier.
+Return the next identifier in sequence.
+Convert identifier to storage key representation.
+source. Read moretry_default in case the value is null or
+undefined.self and other values to be equal, and is used
+by ==.clone_to_uninit)clone_to_uninit)key and return true if they are equal.key and return true if they are equal.pub struct InstanceQuery {
+ pub id: InstanceId,
+}Instance information query.
+id: InstanceIdInstance identifier.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct InstanceRawStorageQuery {
+ pub id: InstanceId,
+ pub store_kind: StoreKind,
+ pub limit: Option<u64>,
+ pub offset: Option<u64>,
+}Instance raw storage query.
+id: InstanceIdInstance identifier.
+store_kind: StoreKindKind of the store to query.
+limit: Option<u64>Maximum number of items per page.
+offset: Option<u64>Number of skipped items.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct InstanceRawStorageQueryResult {
+ pub items: Vec<(Vec<u8>, Vec<u8>)>,
+}Instance raw storage query result.
+items: Vec<(Vec<u8>, Vec<u8>)>List of key-value pairs in contract’s public store.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct InstanceStorageQuery {
+ pub id: InstanceId,
+ pub key: Vec<u8>,
+}Instance storage query.
+id: InstanceIdInstance identifier.
+key: Vec<u8>Storage key.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct InstanceStorageQueryResult {
+ pub value: Option<Vec<u8>>,
+}value: Option<Vec<u8>>Storage value or None if key doesn’t exist.
source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Instantiate {
+ pub code_id: CodeId,
+ pub upgrades_policy: Policy,
+ pub data: Vec<u8>,
+ pub tokens: Vec<BaseUnits>,
+}Instantiate call.
+code_id: CodeIdIdentifier of code used by the instance.
+upgrades_policy: PolicyWho is allowed to upgrade this instance.
+data: Vec<u8>Arguments to contract’s instantiation function.
+tokens: Vec<BaseUnits>Tokens that should be sent to the contract as part of the instantiate call.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct InstantiateResult {
+ pub id: InstanceId,
+}Instantiate call result.
+id: InstanceIdAssigned instance identifier.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct PublicKeyQuery {
+ pub id: InstanceId,
+ pub kind: PublicKeyKind,
+}Public key query.
+id: InstanceIdInstance identifier.
+kind: PublicKeyKindKind of public key.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct PublicKeyQueryResult {
+ pub key: Vec<u8>,
+ pub checksum: Vec<u8>,
+ pub signature: Vec<u8>,
+}Public key query result.
+key: Vec<u8>Public key.
+checksum: Vec<u8>Checksum of the key manager state.
+signature: Vec<u8>Sign(sk, (key || checksum)) from the key manager.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)pub struct Upgrade {
+ pub id: InstanceId,
+ pub code_id: CodeId,
+ pub data: Vec<u8>,
+ pub tokens: Vec<BaseUnits>,
+}Upgrade call.
+id: InstanceIdInstance identifier.
+code_id: CodeIdUpdated code identifier.
+data: Vec<u8>Arguments to contract’s upgrade function.
+tokens: Vec<BaseUnits>Tokens that should be sent to the contract as part of the call.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct Upload {
+ pub abi: ABI,
+ pub instantiate_policy: Policy,
+ pub code: Vec<u8>,
+}Upload call.
+abi: ABIABI.
+instantiate_policy: PolicyWho is allowed to instantiate this code.
+code: Vec<u8>Compiled contract code.
+try_default in case the value is null or
+undefined.clone_to_uninit)pub struct UploadResult {
+ pub id: CodeId,
+}Upload call result.
+id: CodeIdAssigned code identifier.
+source. Read moretry_default in case the value is null or
+undefined.clone_to_uninit)#[handler]A helper attribute for #[sdk_derive(...)]. It doesn’t do anyting on its own;
+it only marks functions that represent a paratime method handler.
+The permitted forms are:
#[handler(call = "my_module.MyCall")]: Marks a function that handles
+the “my_module.MyCall” call and can be passed to
+oasis_runtime_sdk::module::dispatch_call.#[handler(prefetch = "my_module.MyCall")]: Marks a function that handles
+the request to prefetch any data ahead of the “my_module.MyCall” call.
+Its signature should be Fn( add_prefix: &mut dyn FnMut(Prefix) -> (), body: cbor::Value, auth_info: &AuthInfo, ) -> Result<(), oasis_runtime_sdk::error::RuntimeError>#[handler(query = "my_module.MyQuery")]: Marks a function that handles
+the “my_module.MyQuery” query and can be passed to
+oasis_runtime_sdk::module::dispatch_query.#[handler(message_result = "my_module.MyMR")]: Marks a function that handles
+the “my_module.MyMR” message result and can be passed to
+oasis_runtime_sdk::module::dispatch_message_result.Query handler can also contain the expensive tag. Example:
+#[handler(query = "my_module.MyQuery", expensive)].
+Queries tagged expensive can be enabled/disabled are disabled by default to avoid
+excessive costs to the node operator. This can be overridden in the node config.
NOTE: This attribute is parsed by the #[sdk_derive(...)] macro, which cannot
+interpret the attribute name semantically. Use #[handler], not
+#[oasis_runtime_sdk_macros::handler] or other paths/aliases.
#[migration]A helper attribute for #[sdk_derive(...)]. It doesn’t do anything on its own;
+it only marks functions that represent a module state migration.
The permitted forms are:
+#[migration(init)]: Marks the initial (genesis) migration.#[migration(from = v)]: Marks a migration from version v to v+1, where v is
+a non-negative integer.#[sdk_derive]Derives traits from a non-trait impl block (rather than from a struct).
Only the Module trait is supported. In other words, given an impl MyModule block, the macro
+derives implementations needed for implementing a module.
+See also the #[handler] and #[migration] attributes.
#[derive(Error)]
+{
+ // Attributes available to this derive:
+ #[sdk_error]
+ #[source]
+ #[from]
+}
+Derives the Error trait on an enum.
#[derive(Event)]
+{
+ // Attributes available to this derive:
+ #[sdk_event]
+}
+Derives the Event trait on an enum.
oasis_sdk::core::common::version::Version from the Cargo.toml version.#[sdk_derive(...)]. It doesn’t do anyting on its own;
+it only marks functions that represent a paratime method handler.
+The permitted forms are:#[sdk_derive(...)]. It doesn’t do anything on its own;
+it only marks functions that represent a module state migration.impl block (rather than from a struct).Error trait on an enum.Event trait on an enum.Redirecting to macro.version_from_cargo.html...
+ + + \ No newline at end of file diff --git a/rust/oasis_runtime_sdk_macros/macro.version_from_cargo.html b/rust/oasis_runtime_sdk_macros/macro.version_from_cargo.html new file mode 100644 index 0000000000..820ca6c92b --- /dev/null +++ b/rust/oasis_runtime_sdk_macros/macro.version_from_cargo.html @@ -0,0 +1,2 @@ +version_from_cargo!() { /* proc-macro */ }Constructs an oasis_sdk::core::common::version::Version from the Cargo.toml version.
pub fn agent() -> AgentAn ureq::Agent that can be used to perform blocking HTTPS requests.
Note that this forbids non-HTTPS requests. If you need to perform plain HTTP requests consider
+using agent_with_config and pass a suitable config.
pub fn agent_with_config(cfg: AgentConfig) -> AgentAn ureq::Agent with given configuration that can be used to perform blocking HTTPS requests.
A very simple HTTPS client that can be used inside ROFL apps.
+This simple client is needed because Fortanix EDP does not yet have support for mio/Tokio
+networking and so the usual hyper and reqwest cannot be used without patches.
ureq::Agent that can be used to perform blocking HTTPS requests.ureq::Agent with given configuration that can be used to perform blocking HTTPS requests.ROFL utilities.
+Error trait on an enum.\nDerives the Event trait on an enum.\nContract execution context.\nThe contract trait.\nSmart contract environment query interface.\nContract error trait.\nContract event trait.\nMemory management.\nSmart contract storage interface.\nUtilities for testing smart contracts.\nThe confidential store.\nExecution context.\nThe environment.\nThe public store.\nCall format.\nCaller address.\nConfidential contract store.\nTokens deposited by the caller.\nEmits an event.\nEmits a message.\nEnvironment.\nContract instance address.\nContract instance identifier.\nWhether the call is read-only and must not make any …\nPublic contract store.\nTrait that needs to be implemented by contract …\nType of all errors.\nType of all requests.\nType of all responses.\nCall the contract.\nHandle replies from sent messages.\nInstantiate the contract.\nPerform any post-upgrade tasks. This method is called on …\nPerform any pre-upgrade tasks. This method is called on …\nQuery the contract.\nCrypto helpers trait.\nErrors that can be returned from crypto functions.\nEnvironment query trait.\nReturns an address for the contract instance id.\nPrints a message to the console. Useful when debugging.\nDecrypt and authenticate a message and authenticate …\nEncrypt and authenticate a message and authenticate …\nECDSA public key recovery function.\nReturns the argument unchanged.\nCalls U::from(self).\nPerform an environment query.\nFills dst with cryptographically secure random bytes. …\nVerify an ed25519 message signature.\nVerify a secp256k1 message signature.\nVerify an sr25519 message signature.\nDerive a symmetric key from a public/private key pair.\nA contract error that gets propagated to the caller.\nError code uniquely identifying the error.\nName of the module that emitted the error.\nConverts the error into an execution result.\nAn event emitted by the contract.\nCode uniquely identifying the event.\nConverts an event into the raw event type that can be …\nName of the module that emitted the event.\nA region of memory managed on behalf of the host.\nReference to a host region.\nAllocate memory on host’s behalf.\nDeallocate memory on host’s behalf.\nReturns a new region by dereferencing a pointer to the …\nReturns the argument unchanged.\nReturns the argument unchanged.\nCreates a new host region from arguments.\nCreates a new host region from arguments.\nCreates a new host region from the given byte slice.\nTransfers ownership of memory to the host by constructing …\nCalls U::from(self).\nCalls U::from(self).\nTransfers ownership of memory from the host and returns …\nMarker trait for stores backed by confidential storage.\nMarker trait for stores backed by public storage.\nKey/value store trait.\nFetch a given key from contract storage.\nInsert a given key/value pair into contract storage.\nRemove a given key from contract storage.\nA mock contract context suitable for testing.\nMock environment.\nMock store.\n“Confidential” store.\nExecution context.\nEnvironment.\nEmitted events.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nEmitted messages.\nCreate a new empty mock store.\nCreate a new mock environment.\nPublic store.")
\ No newline at end of file
diff --git a/rust/search.desc/oasis_contract_sdk_storage/oasis_contract_sdk_storage-desc-0-.js b/rust/search.desc/oasis_contract_sdk_storage/oasis_contract_sdk_storage-desc-0-.js
new file mode 100644
index 0000000000..9eed8e0383
--- /dev/null
+++ b/rust/search.desc/oasis_contract_sdk_storage/oasis_contract_sdk_storage-desc-0-.js
@@ -0,0 +1 @@
+searchState.loadedDescShard("oasis_contract_sdk_storage", 0, "High-level storage helpers for the Oasis Contract SDK.\nLow-level storage primitive that holds one value.\nA map backed by contract storage.\nA storage cell identifies a storage key of a specific type.\nA storage cell identifies a storage key of a specific type.\nClear the value in the storage cell.\nClear the value in the storage cell.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturn the current value of the storage cell.\nReturn the current value of the storage cell.\nCalls U::from(self).\nCalls U::from(self).\nCreate a new storage cell with the specified key and type.\nCreate a new storage cell with the specified key and type.\nSet the value of the storage cell.\nSet the value of the storage cell.\nA map backed by contract storage.\nType of the encoded representation.\nAn integer in big-endian representation.\nA trait representing an integer that can be encoded into …\nA trait for types which can be used as map keys.\nA map backed by contract storage.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nLookup a given key.\nLookup a given key.\nInsert a given key/value pair.\nInsert a given key/value pair.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nReturn the composite key.\nCreate a new integer in big-endian representation.\nCreate a new map instance.\nCreate a new map instance.\nRemove a given key.\nRemove a given key.\nReturn the memory representation of this integer as a byte …")
\ No newline at end of file
diff --git a/rust/search.desc/oasis_contract_sdk_types/oasis_contract_sdk_types-desc-0-.js b/rust/search.desc/oasis_contract_sdk_types/oasis_contract_sdk_types-desc-0-.js
new file mode 100644
index 0000000000..9efbfbf37f
--- /dev/null
+++ b/rust/search.desc/oasis_contract_sdk_types/oasis_contract_sdk_types-desc-0-.js
@@ -0,0 +1 @@
+searchState.loadedDescShard("oasis_contract_sdk_types", 0, "A collection of common types used by the Oasis Contract …\nFormat used for encoding the call (and output) information.\nUnique stored code identifier.\nEncrypted call data using X25519 for key exchange and …\nExecution context.\nResult of a successful contract execution.\nContract execution result.\nUnique deployed code instance identifier.\nPlain text call data.\nA minimal representation of an Oasis Runtime SDK address.\nConvert identifier to u64.\nConvert identifier to u64.\nTransaction’s call format.\nCaller address.\nCryptography-related types.\nRaw data returned from the contract.\nTokens deposited by the caller.\nEnvironment query-related types.\nEvents.\nEvents emitted from the contract.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturn the next identifier in sequence.\nReturn the next identifier in sequence.\nContract instance address.\nContract instance identifier.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nMessages that can be emitted by contracts.\nMessages emitted from the contract.\nA collection of types for easier calling into existing SDK …\nRead-only flag.\nStorage-related types.\nTesting helpers.\nConvert identifier to storage key representation.\nConvert identifier to storage key representation.\nToken types.\nAn account address.\nError.\nSize of an address in bytes.\nReturns the argument unchanged.\nReturns the argument unchanged.\nTries to create a new address from Bech32-encoded string.\nTries to create a new address from raw bytes.\nCalls U::from(self).\nCalls U::from(self).\nConverts an address to Bech32 representation.\nSignature kind.\nReturns the argument unchanged.\nCalls U::from(self).\nAccounts queries.\nAccounts queries.\nAccounts API queries.\nAccounts API responses.\nQuery an account’s balance.\nAn account’s balance of the given denomination.\nInformation about the current runtime block.\nInformation about the current runtime block.\nIndication of a failing request.\nA query request.\nA query response.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nAn event emitted from the contract.\nUnique code representing the event for the given module.\nArbitrary data associated with the event.\nReturns the argument unchanged.\nCalls U::from(self).\nOptional module name.\nCalls an arbitrary runtime method handler in a child …\nReply from a call message.\nCall result.\nMessages can be emitted by contracts and are processed …\nSpecifies when the caller (smart contract) wants to be …\nReplies to delivered messages.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCheck whether the call result indicates a successful …\nInstantiate call result.\nReturns the argument unchanged.\nAssigned instance identifier.\nCalls U::from(self).\nKind of the store to use.\nReturns the argument unchanged.\nCalls U::from(self).\nPrefix that should be used for the underlying store.\nToken amount of given denomination in base units.\nName/type of the token.\nMaximum length of a denomination.\nDenomination in native token.\nToken amount in base units.\nDenomination of the token amount.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nRaw representation of a denomination.\nWhether the denomination represents the native token.\nCreates a new token amount of the given denomination.")
\ No newline at end of file
diff --git a/rust/search.desc/oasis_core_runtime/oasis_core_runtime-desc-0-.js b/rust/search.desc/oasis_core_runtime/oasis_core_runtime-desc-0-.js
new file mode 100644
index 0000000000..a0043f50e5
--- /dev/null
+++ b/rust/search.desc/oasis_core_runtime/oasis_core_runtime-desc-0-.js
@@ -0,0 +1 @@
+searchState.loadedDescShard("oasis_core_runtime", 0, "Oasis Core runtime SDK.\nRuntime build information.\nTEE type this build is for.\nRuntime apps.\nIn-memory cache of trees.\nCommon types.\nRuntime configuration.\nConsensus service interfaces.\nRuntime call dispatcher.\nSecure inter-enclave RPC.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nHelper functions to use with the asynchronous Tokio …\nHost interface.\nRuntime attestation key handling.\nDefine a byte array-like type.\nRuntime initialization.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nTrue iff the build can provide integrity and …\nDefine a KeyFormat from KeyFormatAtom and a prefix.\nConsensus SGX and quote policy handling.\nRuntime side of the worker-host protocol.\nSupported runtime protocol version.\nRuntime storage interfaces and implementations.\nTEE type this build is for.\nRuntime transaction processing.\nTypes used by the worker-host protocol.\nAn Oasis runtime app.\nAn application which doesn’t do anything.\nReturns the argument unchanged.\nCalls U::from(self).\nWhether this is a ROFL app.\nCreate a new runtime initializer for an application.\nCalled on application initialization.\nCalled on new runtime block being received.\nCalled on new runtime event being detected.\nCalled for runtime queries.\nQuote policy to use for verifying our own enclave identity.\nCached storage tree with an associated root.\nA set of storage tree caches, one for each storage …\nCache used for checking transactions.\nCommits a specific version and root as being stored by the …\nCache used for executing transactions.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCreate a new empty cache set.\nCache used for queries.\nReference to the cached tree.\nMutable reference to the cached tree.\nByte array type helpers.\nCryptographic primitives.\nLogging subsystem for runtimes.\nChain namespace.\nPanic-related functions.\nProcess-related helpers.\nAn arbitrary precision unsigned integer.\nSGX-specific functionality.\nRuntime time source.\nProtocol and runtime versioning.\nHash type.\nMRAE primitives.\nSignature types.\nCBOR serializable X25519 types.\nA 32-byte SHA-512/256 hash.\nCompute a digest of the passed slice of bytes.\nCompute a digest of the passed slices of bytes.\nHash of an empty string.\nReturns the argument unchanged.\nCalls U::from(self).\nReturns true if the hash is of an empty string.\nSize of this object in bytes.\nHash truncated to the given number of bytes.\nDeoxys-II-256-128 MRAE primitives implementation.\nNonce utility used to ensure nonces are safely incremented.\nDeoxys-II-256-128 state.\nSize of the Deoxys-II-256-128 key in bytes.\nSize of the nonce in bytes.\nAn abstract Deoxys-II-256-128 box opener.\nSize of the authentication tag in bytes.\nUnboxes (“opens”) the provided additional data and …\nUnboxes (“opens”) the provided additional data and …\nBoxes (“seals”) the provided additional data and …\nReturns the argument unchanged.\nGenerates a public/private key pair suitable for use with …\nCalls U::from(self).\nCreates a new instance using the provided key.\nDecrypts and authenticates ciphertext, authenticates the …\nLike DeoxysII::open but writes the plaintext into plaintext…\nEncrypts and authenticates plaintext, authenticates the …\nLike DeoxysII::seal but seals into ciphertext_with_tag, …\nSize of the nonce in bytes. Size of the nonce in bytes.\n120 bit nonce with a 88 bit tag and 32 bit counter. If the …\nSize of tag portion of the nonce in bytes. These bytes …\nReturns the argument unchanged.\nGenerate a random nonce.\nAdds one to the nonce, affecting only the last 32 counting …\nCalls U::from(self).\nCreate a new nonce.\nBlob signed by multiple public keys.\nAn Ed25519 private key.\nAn Ed25519 public key.\nAn Ed25519 signature.\nA signature bundled with a public key.\nBlob signed with one public key.\nA abstract signer.\nSigned blob.\nSigned blob.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nConstruct a private key from bytes returned by to_bytes.\nGenerate a new private key from a test key seed.\nGenerates a new private key pair.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nSize of this object in bytes.\nSize of this object in bytes.\nReturns the public key corresponding to the signer.\nReturns the public key.\nPublic key that produced the signature.\nGenerates a signature over the context and message.\nSignature over the blob.\nActual signature.\nExtends signature context with additional domain …\nExtends signature context with additional domain …\nSignatures over the blob.\nConvert this private key into bytes.\nVerify signature.\nReturns true iff the signature is valid.\nVerify returns true iff the signature is valid over the …\nVerify signature without applying domain separation.\nThe length of an X25519 private key, in bytes.\nThe length of an X25519 public key, in bytes.\nA CBOR serializable Diffie-Hellman X25519 private key.\nA CBOR serializable Diffie-Hellman X25519 public key.\nLoad private key from a byte array.\nReturns the argument unchanged.\nGiven an X25519 private key, compute its corresponding …\nLoad public key from a byte array.\nReturns the argument unchanged.\nGenerate a new private key from a test key seed.\nGenerate a new private key.\nCalls U::from(self).\nCalls U::from(self).\nCompute corresponding public key.\nA key formatting helper trait to be used together with …\nPart of the KeyFormat to be used with key-value backends …\nDecode the given key format from data.\nDecode the given key format from data (without prefix).\nEncode the given key format.\nEncode the given key format into a set of atoms.\nEncode the first few atoms in the key format.\nThe prefix that identifies the key format.\nThe minimum size of the encoded key.\nGet the logger.\nInitialize the global slog_stdlog adapter to allow logging …\nSize of the namespace in bytes.\nChain namespace.\nReturns the argument unchanged.\nCalls U::from(self).\nSize of this object in bytes.\nA guard that will abort the process if dropped while …\nReturns the argument unchanged.\nCalls U::from(self).\nAborts the process via std::process::abort, but also …\nAn arbitrary precision unsigned integer.\nDivides two numbers, checking for underflow, overflow and …\nSubtracts two numbers, checking for underflow. If …\nReturns the argument unchanged.\nCalls U::from(self).\nEnclave identity.\nMaximum age of a quote from the viewpoint of the enclave.\nEnclave hash (MRENCLAVE).\nEnclave signer hash (MRSIGNER).\nAn unverified SGX remote attestation quote, depending on …\nQuote validity policy.\nA remote attestation quote that has undergone verification.\nEnclave identity for the current enclave (when available).\nSGX per-CPU package sealing key accessor.\nEnclave identity using a test MRSIGNER from Fortanix with …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nIntel Attestation Service (IAS) attestation verification …\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nWhether the quote should be considered fresh.\nSize of this object in bytes.\nSize of this object in bytes.\nIntel Provisioning Certification Services (PCS) quote …\nGenerate a report for the given target enclave.\nWrappers for sealing secrets to the enclave in cold …\nVerify the remote attestation quote.\negetkey returns a 256 bit key suitable for sealing secrets …\nAttestation verification report.\nThe purpose of QuoteContext is to prevent quotes from …\nQuote validity policy.\nAllowed quote statuses.\nWhether IAS quotes are disabled and will always be …\nReturns the argument unchanged.\nReturns the argument unchanged.\nList of blocked platform EPID group IDs.\nCalls U::from(self).\nCalls U::from(self).\nThe minimum TCB evaluation data number that should be …\nVerify attestation report.\nTUD.DEBUG (TD runs in debug mode).\nPossible errors returned by this module.\nSEC.KL (TD is allowed to use Key Locker).\nOTHER.PERFMON (TD is allowed to use Perfmon and …\nSEC.PKS (TD is allowed to use Supervisor Protection Keys).\nAn enclave quote.\nAn attestation quote together with the TCB bundle required …\nQuote validity policy.\nSEC.SEPT_VE_DISABLE (Disable EPT violation conversion to …\nThe TCB bundle contains all the required components to …\nTDX TD attributes.\nTDX TD report.\nTDX module policy.\nTDX-specific quote policy.\nGet a flags value with all known bits set.\nAllowed TDX modules. Empty to allow ANY Intel-signed …\nConverts this report into an enclave identity.\nThe bitwise and (&) of the bits in two flags values.\nThe bitwise and (&) of the bits in two flags values.\nThe bitwise or (|) of the bits in two flags values.\nThe bitwise or (|) of the bits in two flags values.\nGet the underlying bits value.\nThe bitwise exclusive-or (^) of the bits in two flags …\nThe bitwise exclusive-or (^) of the bits in two flags …\nThe bitwise negation (!) of the bits in a flags value, …\nWhether all set bits in a source flags value are also set …\nThe intersection of a source flags value with the …\nWhether PCS quotes are disabled and will always be …\nGet a flags value with all bits unset.\nThe bitwise or (|) of the bits in each flags value.\nA list of hexadecimal encoded FMSPCs specifying which …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nConvert from a bits value.\nConvert from a bits value exactly.\nConvert from a bits value, unsetting any unknown bits.\nThe bitwise or (|) of the bits in each flags value.\nGet a flags value with the bits of a flag with the given …\nQuote header.\nThe bitwise or (|) of the bits in two flags values.\nThe bitwise and (&) of the bits in two flags values.\nWhether any set bits in a source flags value are also set …\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nWhether all known bits in this flags value are set.\nWhether all bits in this flags value are unset.\nWhether the quote with timestamp ts is expired.\nYield a set of contained flags values.\nYield a set of contained named flags values.\nReturns true iff the TDX module in the given report …\nMinimum TCB evaluation data number that is considered to …\nSoftware-defined ID for non-owner-defined configuration of …\nSoftware-defined ID for the TD’s owner.\nSoftware-defined ID for owner-defined configuration of the …\nOptional allowed measurement of the TDX Module. In case it …\nMeasurement of the TDX Module.\nAllowed signer of the TDX Module (zero for Intel).\nSigner of the TDX Module (zero for Intel).\nMeasurement of the initial contents of the TD.\nThe bitwise negation (!) of the bits in a flags value, …\nParse a TDX report.\nParse raw TDX attributes.\nThe intersection of a source flags value with the …\nReport body.\nCustom report data.\nRuntime extendable measurement register 0.\nRuntime extendable measurement register 1.\nRuntime extendable measurement register 2.\nRuntime extendable measurement register 3.\nTDX Module attributes (must be zero for TDX 1.0).\nCall insert when value is true or remove when value is …\nThe intersection of a source flags value with the …\nThe intersection of a source flags value with the …\nThe bitwise exclusive-or (^) of the bits in two flags …\nValidity (in days) of the TCB collateral.\nTD attributes.\nCompute enclave identity from the given measurements.\nOptional TDX-specific policy. In case this is None, TDX …\nDescribes the TCB of TDX.\nThe bitwise exclusive-or (^) of the bits in two flags …\nThe bitwise or (|) of the bits in two flags values.\nVerify whether the TDX policy is satisfied for the given …\nVerify the quote bundle.\nVerify quote.\nXFAM (eXtended Features Available Mask).\nCreates a new Deoxys-II instance initialized with an SGX …\nSeal a secret to the enclave.\nUnseal a previously sealed secret to the enclave.\nReturns the number of seconds since the UNIX epoch. The …\nProtocol versions.\nA protocol or runtime version.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nChecks if two versions are compatible.\nCreates a new version with given major, minor, and patch …\nVersion key used in serialized form.\nA generic versioned serializable data structure.\nReturns the argument unchanged.\nCalls U::from(self).\nCreate a new versioned structure.\nGlobal runtime configuration.\nStorage-related configuration.\nThe maximum number of tree nodes held by the cache before …\nThe total size, in bytes, of values held by the cache …\nAdvertised runtime features.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nWhether storage state should be persisted between …\nStorage configuration.\nOptional trust root for consensus layer integrity …\nSemantic runtime version.\nBlockMetadata contains additional metadata related to the …\nAn event emitted by the consensus layer.\nThe height that represents the most recent block height.\nLight consensus block.\nA unique module name for the consensus module.\nConsensus account address structures.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nGovernance structures.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nRegistry structures.\nConsensus roothash structures.\nScheduler structures.\nConsensus staking structures.\nConsensus state wrappers.\nState root after executing all logic in the block.\nTendermint consensus layer backend.\nTrait for consensus layer verification.\nA staking account address.\nCommon pool reserved address.\nPer-block fee accumulator reserved address.\nGovernance deposits reserved address.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nTries to create a new address from Bech32-encoded string.\nCreates a new address from a public key.\nCreates a new runtime address.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCreates a new address from a context, version and data.\nConverts an address to Bech32 representation.\nAn invalid epoch time.\nThe number of intervals (epochs) since a fixed instant in …\nThe epoch state.\nReturns the argument unchanged.\nCalls U::from(self).\nAbstained.\nCancel proposal content.\nChange parameters proposal content.\nInvalid vote that should never be explicitly set.\nNo vote.\nConsensus layer governance proposal content.\nVote for a proposal.\nUpgrade proposal content.\nA governance vote.\nYes Vote.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nUnique identifier of a proposal.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nProposal vote.\nPer enclave key manager access control policy.\nEncrypted ephemeral secret.\nEncrypted master secret.\nA secret encrypted with Deoxys-II MRAE algorithm.\nErrors emitted by the key manager module.\nKey manager access control policy.\nSigned encrypted ephemeral secret (RAK).\nSigned encrypted master secret (RAK).\nSigned key manager access control policy.\nChecksum for validating decrypted secret.\nKey manager state in the consensus layer.\nA map of REK encrypted secrets.\nEpoch time in which the secret was created.\nEpoch time to which the ephemeral secret belongs.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nGeneration of the secret.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nA map of runtime IDs to the vector of enclave IDs that may …\nA vector of enclave IDs that may retrieve the master …\nPublic key to derive the symmetric key for decryption.\nRuntime ID of the key manager.\nRuntime ID of the key manager.\nEncrypted secret.\nEncrypted secret.\nEncrypted master secret.\nEncrypted ephemeral secret.\nSignature of the encrypted master secret.\nSignature of the encrypted ephemeral secret.\nVerify the signatures.\nApplication represents a node’s application to form a …\nErrors emitted by the CHURP module.\nThe NIST P-384 elliptic curve group with the SHA3-384 hash …\nKey manager access control policy.\nSigned key manager access control policy.\nStatus represents the current state of a CHURP instance.\nCipher suite identifier.\nA map of nodes that wish to form the new committee.\nThe hash of the verification matrix from the last …\nThe hash of the random verification matrix.\nA vector of nodes holding a share of the secret in the …\nThe minimum number of shares that can be lost to render …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nThe epoch of the last successfully completed handoff.\nThe time interval in epochs between handoffs.\nA unique identifier within the key manager runtime.\nA unique identifier within the key manager runtime.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nA vector of enclave identities that may form the new …\nA map of runtime identities to the vector of enclave …\nA vector of enclave identities from which a share can be …\nThe hash of the verification matrix from the current …\nThe epoch in which the next handoff will occur.\nA signed SGX access control policy.\nAn SGX access control policy.\nReconstructed is true if and only if the node verified all …\nThe identifier of the key manager runtime.\nThe identifier of the key manager runtime.\nA monotonically increasing policy serial number.\nA vector of signatures.\nThe identifier of a cipher suite used for verifiable …\nThe degree of the secret-sharing polynomial.\nVerify the signatures.\nAttestation signature context.\nAdmission policy that allows any node to register.\nRepresents a node’s capabilities.\nRepresents the node’s TEE capability.\nRepresents a consensus address that includes an ID and a …\nNode’s consensus member information.\nTEE capability endorsement signature context.\nAn endorsed CapabilityTEE structure.\nEntity whitelist configuration.\nA per-role entity whitelist policy.\nA per-entity whitelist configuration for a given role.\nPolicy that allows only whitelisted entities’ nodes to …\nParameters for the executor committee.\nConsensus governance model.\nEntity governance model.\nInvalid model that should never be explicitly set.\nRuntime governance model.\nGeneric compute runtime.\nInvalid runtime that should never be explicitly set.\nKey manager runtime.\nThe latest entity descriptor version that should be used …\nThe method name for freshness proofs.\nA unique module name for the registry module.\nA constraint which specifies that only the given number of …\nA constraint which specifies the minimum required …\nNode registry descriptor.\nRepresents the runtimes supported by a given Oasis node.\nNode’s P2P information.\nA per-role admission policy.\nCompute worker role.\nEmpty roles mask.\nKey manager role.\nObserver role.\nPublic consensus RPC services worker role.\nPublic storage RPC services worker role.\nValidator role.\nOasis node roles bitmask.\nRuntime.\nSpecification of which nodes are allowed to register for a …\nRuntime genesis information that is used to initialize …\nRuntime governance model.\nRuntime kind.\nStake-related parameters for a runtime.\nIntel SGX remote attestation.\nIntel SGX TEE constraints.\nThe node scheduling constraints.\nStorage parameters.\nRepresents the address of a TCP endpoint.\nTEE hardware implementation.\nIntel SGX TEE implementation.\nNon-TEE implementation.\nRepresents an Oasis committee address that includes a TLS …\nNode’s TLS information.\nParameters for the runtime transaction scheduler.\nOld V0 format that only supported IAS policies.\nOld V0 format that only supported IAS quotes.\nNew V1 format that supports both IAS and PCS policies.\nNew V1 format that supports both IAS and PCS policies.\nContains information for this node’s participation in …\nA constraint which specifies that the entity must have a …\nVerified remote attestation.\nA verified endorsed CapabilityTEE structure.\nPer-runtime version information.\nThe currently active deployment for the specified epoch if …\nAddress at which the node can be reached.\nAddress at which the node can be reached.\nList of addresses at which the node can be reached.\nList of addresses at which the node can be reached.\nWhich nodes are allowed to register for this runtime.\nNumber of allowed stragglers.\nAllow any node to register.\nAttestation.\nHow long to wait for a scheduled batch in nanoseconds …\nThe SHA256 hash of the runtime bundle (optional).\nNode’s capabilities for a given runtime.\nTEE capability structure to be endorsed.\nChunk size parameter for checkpoint creation.\nExpected runtime state checkpoint interval (in rounds).\nExpected minimum number of checkpoints to keep.\nInformation for connecting to this node as a consensus …\nNode scheduling constraints.\nWhether the roles mask contains any of the specified roles.\nChecks whether the given enclave identity is whitelisted.\nDeployment corresponding to the specified version if it …\nRuntime deployment information.\nIdentities of allowed enclaves.\nEntity whitelist configuration for each whitelisted entity.\nPublic key identifying the Entity controlling the node.\nPublic key identifying the Entity controlling the runtime.\nAllow only the whitelisted entities’ nodes to register.\nParameters of the executor committee.\nEpoch in which the node’s commitment expires.\nExtra per node + per runtime opaque data associated with …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nRuntime genesis information.\nSearches for an existing supported runtime descriptor in …\nRuntime governance model.\nSize of the discrepancy resolution group.\nSize of the committee.\nHardware type.\nChecks whether the node has any of the specified roles.\nChecks whether the node has the provided TEE identity …\nHashes the required data that needs to be signed by RAK …\nEnclave’s view of the consensus layer height at the time …\nUnique identifier of the node on the P2P transport.\nPublic key identifying the node.\nUnique identifier of the node as a consensus member.\nUnique identifier of the node used to generate VRF proofs.\nPublic key identifying the runtime.\nPublic key identifying the node.\nGlobally unique long term identifier of the runtime.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nWhether the roles mask encodes a single valid role.\nKey manager runtime ID for this runtime.\nType of runtime.\nChecks whether the TEE capability matches the given TEE …\nMaximum size of a scheduled batch.\nMaximum size of a scheduled batch in bytes.\nMaximum size of the incoming message queue.\nMaximum number of liveness failures that are tolerated …\nMaximum number of messages that can be emitted by the …\nMaximum percentage of proposed rounds in an epoch that can …\nMaximum number of nodes that an entity can register under …\nSpecifies the minimum fee that the incoming message must …\nMinimum number of live rounds in an epoch for the liveness …\nMinimum percentage of rounds in an epoch that a node must …\nNode endorsement signature.\nOptional identifier of the node that endorsed the TEE …\nInformation for connecting to this node via P2P.\nA per-role admission policy that must be satisfied in …\nSGX quote policy.\nHow long to wait before accepting proposal from the next …\nPublic key used for establishing TLS connections.\nPublic key used for establishing TLS connections.\nSGX attestation quote.\nVerified enclave quote.\nRuntime attestation key.\nRuntime encryption key.\nThe percentage of the reward obtained when slashing for …\nThe percentage of the reward obtained when slashing for …\nBitmask representing the node roles.\nRuntime round in the genesis.\nRound timeout in consensus blocks.\nNode’s runtimes.\nPer-runtime misbehavior slashing parameters.\nNode’s oasis-node software version.\nRuntime’s staking-related parameters.\nState root that should be used at genesis time. If the …\nParameters of the storage committee.\nIs the capability of a node executing batches in a TEE.\nEnclave version information, in an enclave provided …\nRuntime’s TEE hardware requirements.\nMinimum stake thresholds for a runtime. These per-runtime …\nInformation for connecting to this node via TLS.\nTries to decode the TEE-specific attestation.\nTries to decode the TEE-specific version information.\nTransaction scheduling parameters of the executor …\nStructure version.\nStructure version.\nThe epoch at which this version is valid.\nVerified TEE remote attestation.\nVerifies the TEE capability.\nVerify endorsed TEE capability is valid.\nVerifies the SGX attestation.\nVerify the endorsement signature is valid.\nVersion of the runtime.\nVersion of the runtime.\nInformation for this node’s participation in VRF based …\nThe runtime’s view of the consensus layer height at the …\nAn Intel SGX quote.\nThe signature of the attestation by the enclave (RAK).\nA set of allowed quote statuses.\nThe allowed MRENCLAVE/MRSIGNER pairs.\nThe allowed MRENCLAVE/MRSIGNER pairs.\nThe maximum attestation age (in blocks).\nThe quote policy.\nRuntime block annotated with consensus information.\nRuntime block.\nThe signature context used to sign compute results headers …\nThe header of a computed batch output by a runtime. This …\nThe signature context used to sign executor worker …\nErrors emitted by the roothash module.\nA commitment to results of processing a proposed runtime …\nThe executor commitment failure reason.\nThe header of an executor commitment.\nIndicates that no failure has occurred.\nIndicates that batch processing failed due to the state …\nIndicates a generic failure.\nBlock header.\nHeader type.\nAn incoming message emitted by the consensus layer to be …\nA message that can be emitted by the runtime to be …\nResult of a message being processed by the consensus layer.\nA trait that validates messages for validity. It can be …\nA trait for looking up registry node descriptors.\nVerified roothash commitment.\nA pool of commitments that can be used to perform …\nInformation about how a particular round was executed by …\nPer-round state and I/O roots that are stored in consensus …\nVerifies and adds a new executor commitment to the pool.\nPublic keys of compute nodes’ controlling entities that …\nRuntime block.\nAddress of the caller authenticated by the consensus layer.\nConsensus height at which this runtime block was produced.\nArbitrary runtime-dependent data.\nReturns a hash of an encoded header.\nReturns a hash of an encoded header.\nThe executor commitment failure reason.\nFee sent into the runtime as part of the message being …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nPublic keys of compute nodes’ controlling entities that …\nHeader.\nThe compute results header.\nHeader type.\nUnique identifier of the message.\nReturns a hash of provided incoming runtime messages.\nReturns a hash of provided runtime messages.\nThe number of processed incoming messages.\nHash of processed incoming messages.\nThe hash of processed incoming messages.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nI/O merkle root.\nThe I/O merkle root.\nReturns true if this commitment indicates a failure.\nReturns true iff the header is the parent of a child …\nReturns true if the event indicates that the message was …\nResults of executing emitted runtime messages.\nReturns a hash of provided runtime messages.\nMessages hash.\nHash of messages sent from this batch.\nReturns true if the commitment is mostly equal to another …\nChain namespace.\nCreates a new pool.\nCreates a new empty block with a specific type.\nCreates a new empty genesis block given a runtime id and …\nPrevious block hash.\nHash of the previous block header this batch was computed …\nPerforms a single round of commitment checks. If there are …\nRound number.\nRound number.\nSigns the executor commitment header.\nSigns the executor commitment header and sets the …\nState merkle root.\nThe root hash of the state after computing this batch.\nAn optional tag provided by the caller which is ignored …\nTimestamp (POSIX time).\nReturns a commitment-specific result after discrepancy …\nReturns a hash that represents a vote for this commitment …\nTokens sent into the runtime as part of the message being …\nPerforms basic validation of the runtime message.\nPerforms basic validation of the staking message.\nPerforms basic validation of the registry message.\nPerforms basic validation of the governance message.\nVerifies that the header signature is valid.\nVerifies the RAK signature.\nProtocol version number.\nIndicates the node is a backup worker.\nA per-runtime (instance) committee.\nThe functionality a committee exists to provide.\nA node participating in a committee.\nA compute executor committee.\nAn invalid role (should never appear on the wire).\nAn invalid committee (should never appear on the wire).\nThe role a given node plays in a committee.\nIndicates the node is a worker.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nThe functionality a committee exists to provide.\nThe committee members.\nThe node’s public key.\nThe node’s role in a committee.\nThe runtime ID that this committee is for.\nReturns the transaction scheduler of the provided …\nThe epoch for which the committee is valid.\nReturns committee nodes with Worker role.\nEntry in the staking ledger.\nEvent emitted when stake is transferred into an escrow …\nAdd escrow result.\nEvent emitted when allowance is changed for a beneficiary.\nEvent emitted when stake is destroyed via a call to Burn.\nCommission rate bound and its starting time.\nCommission rate and its starting time.\nDefines a list of commission rates and commission rate …\nDebonding delegation descriptor.\nEvent emitted when the debonding process has started and …\nDelegation descriptor.\nA stake escrow.\nEscrow account.\nEscrow-related events.\nA staking-related event.\nGeneral purpose account.\nEntity staking threshold.\nCompute node staking threshold.\nKeymanager node staking threshold.\nValidator node staking threshold.\nCompute runtime staking threshold.\nKeymanager runtime staking threshold.\nEvent emitted when stake is reclaimed from an escrow …\nA reclaim escrow.\nReclaim escrow result.\nSlashing due to signing two different executor commits or …\nSlashing due to submission of incorrect results in runtime …\nSlashing due to not doing the required work.\nCombined balance of serval entries, the relative sizes of …\nPer-reason slashing configuration.\nReason for slashing an entity.\nPer escrow account stake accumulator.\nUnique stake claim identifier.\nStake threshold used in the stake accumulator.\nEvent emitted when stake is taken from an escrow account …\nKind of staking threshold.\nA stake transfer.\nEvent emitted when stake is transferred, either by a call …\nTransfer result.\nA withdrawal from an account.\nWithdraw result.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nProvides consensus state tree from the host.\nBeacon state in the consensus layer.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCreates consensus state using host protocol.\nConsensus layer height that this data is for.\nCalls U::from(self).\nCalls U::from(self).\nKey manager state in the consensus layer.\nCreates a consensus state wrapping the provided tree.\nRegistry state in the consensus layer.\nRoothash state in the consensus layer.\nStaking state in the consensus layer.\nConsensus beacon state wrapper.\nMutable consensus beacon state wrapper.\nReturns the current epoch number.\nReturns the current epoch state.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the future epoch number.\nReturns the future epoch state.\nCalls U::from(self).\nCalls U::from(self).\nConstructs a new ImmutableMKVS.\nSet current epoch state.\nSet future epoch state.\nConsensus key manager state wrapper.\nCurrent key manager status.\nKey manager master secret verification checksum.\nKey manager state in the consensus layer.\nLooks up a specific key manager ephemeral secret by its …\nReturns the argument unchanged.\nReturns the argument unchanged.\nGeneration of the latest master secret.\nRuntime ID of the key manager.\nCalls U::from(self).\nCalls U::from(self).\nTrue iff the key manager is done initializing.\nTrue iff the key manager is secure.\nLooks up a specific key manager master secret by its …\nConstructs a new ImmutableMKVS.\nList of currently active key manager node IDs.\nKey manager policy.\nEpoch of the last master secret rotation.\nRuntime signing key of the key manager.\nLooks up a specific key manager status by its namespace …\nReturns the list of all key manager statuses.\nConsensus CHURP state wrapper.\nReturns the argument unchanged.\nCalls U::from(self).\nConstructs a new ImmutableMKVS.\nLooks up a specific key manager status by its namespace …\nConsensus registry state wrapper.\nReturns the argument unchanged.\nCalls U::from(self).\nConstructs a new ImmutableMKVS.\nLooks up a specific node by its identifier.\nReturns the list of all registered nodes.\nLooks up a specific runtime by its identifier.\nConsensus roothash state wrapper.\nReturns the argument unchanged.\nCalls U::from(self).\nReturns the last round results for a specific runtime.\nConstructs a new ImmutableMKVS.\nReturns the state root for a specific runtime.\nConsensus staking state wrapper.\nReturns the staking account for the given account address.\nReturns the non-empty addresses from the staking ledger.\nReturns the balance of the global common pool.\nReturns the debonding delegation.\nReturns all debonding delegations.\nReturns the delegation.\nReturns all active delegations.\nReturns the argument unchanged.\nReturns the governance deposits balance.\nCalls U::from(self).\nReturns the last block fees balance.\nConstructs a new ImmutableMKVS.\nReturns the total supply.\nTendermint consensus backend name. Keep synced with …\nTendermint light consensus block metadata.\nThe domain separation context used by Oasis Core for …\nConvert an Oasis Core chain context into a Tendermint …\nDecode the light block metadata as a Tendermint light …\nEncode the light block metadata to a Tendermint light …\nReturns the argument unchanged.\nState root specified by this light block.\nCalls U::from(self).\nMerkle proofs used in Tendermint networks\nExtract state root from the given signed block header.\nTendermint consensus layer verification logic.\nMaximum number of aunts that can be included in a Proof. …\nProof represents a Merkle proof.\nCompute the root hash given a leaf hash. Does not verify …\nReturns the argument unchanged.\nCalls U::from(self).\nVerify that the Proof proves the root hash. Check …\nA verifier which performs no verification.\nTendermint consensus layer verifier.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturn a handle to interact with the verifier.\nCalls U::from(self).\nCalls U::from(self).\nCreate a new non-verifying verifier.\nCreate a new Tendermint consensus layer verifier.\nStart the non-verifying verifier.\nStart the verifier in a separate thread.\nConsensus transaction fee the sender wishes to pay for …\nConsensus gas representation.\nMethod name.\nProof of transaction inclusion in a block.\nSigned consensus transaction.\nSigned consensus transaction with a proof of its inclusion …\nUnsigned consensus transaction.\nFee amount to be paid.\nSigned blob.\nMethod call body.\nOptional fee that the sender commits to pay to execute …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nMaximum gas that a transaction can use.\nBlock height at which the transaction was published.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nMethod that should be called.\nNonce to prevent replay.\nProof of transaction inclusion in a block.\nActual raw proof.\nSignature over the blob.\nSigned transaction.\nReturns true iff the signature is valid.\nConsensus layer trust root.\nVerifier is the consensus layer state verifier trait.\nKnown consensus chain context.\nReturn the consensus layer events at the given height.\nReturns the argument unchanged.\nReturns the argument unchanged.\nKnown hex-encoded trusted consensus layer header hash.\nKnown trusted height.\nCalls U::from(self).\nCalls U::from(self).\nReturn the latest known consensus layer height.\nReturn the latest verified consensus layer state.\nKnown runtime identifier.\nReturn the verified consensus layer state for a given …\nSynchronize the verifier state up to including the passed …\nReturn the consensus layer state accessor for the given …\nVerify that the given runtime header is valid at the given …\nVerify that the given runtime header is valid at the given …\nVerify consensus layer state freshness based on our …\nRuntime call dispatcher.\nInterface for dispatcher initializers.\nState returned by the initializer.\nState available before initialization.\nOptional ROFL application.\nConsensus verifier instance.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nRuntime Attestation Key instance.\nInitializes the dispatcher(s).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCreate a new runtime call dispatcher.\nProtocol instance.\nQueue a new request to be dispatched.\nRPC demultiplexer instance.\nRPC dispatcher instance.\nStart the dispatcher.\nOptional transaction dispatcher that should be used.\nEnclave RPC client.\nRPC call context.\nSession demultiplexer.\nRPC dispatcher.\nSecure channel session.\nSession demultiplexer.\nRPC protocol types.\nAn EnclaveRPC response that can be used to provide peer …\nRPC client.\nRPC client error.\nReport bad peer as peer feedback.\nReport failure as peer feedback.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCall a remote method over an insecure channel where …\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nConsume the response instance returning the inner result.\nReport success if result was Ok(_) and failure if result …\nConstruct an unconnected RPC client with runtime-internal …\nReference to inner result.\nCall a remote method using an encrypted and authenticated …\nReport success as peer feedback.\nUpdate allowed remote enclave identities.\nUpdate remote end’s quote policy.\nUpdate remote runtime id.\nRPC call context.\nReturns the argument unchanged.\nCalls U::from(self).\nConstruct new transaction context.\nInformation about the session the RPC call was delivered …\nSession demultiplexer.\nDemultiplexer error.\nCloses the given session.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCreate new session demultiplexer.\nProcess a frame, returning the locked session guard and …\nResets all open sessions.\nSet the session builder to use.\nRPC call dispatcher.\nRPC handler.\nKey manager quote policy update handler callback.\nKey manager status update handler callback.\nRPC method dispatcher implementation.\nDescriptor of a RPC API method.\nHandler for a RPC method.\nDispatcher for a RPC method.\nRegister a new method in the dispatcher.\nRegister new methods in the dispatcher.\nDispatch request.\nDispatch request.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nGet method descriptor.\nInvoke the method implementation and return a response.\nHandle key manager quote policy update.\nHandle key manager status update.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nSpecifies which kind of RPC is allowed to call the method.\nReturns the list of RPC methods supported by this handler.\nMethod name.\nCreate a new enclave method descriptor.\nUpdate key manager quote policy update handler.\nUpdate key manager status update handler.\nSession builder.\nBinding of the session’s static public key to a remote …\nAn encrypted and authenticated RPC session.\nInformation about a session.\nOld V0 format that only supported IAS quotes.\nNew V1 format that supports both IAS and PCS quotes.\nV2 format which supports endorsed CapabilityTEE structures.\nBuild initiator session.\nBuild responder session.\nMark the session as closed.\nEnable remote node identity verification.\nIdentifier of the node that endorsed the TEE.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturn the local identity if configured in the builder.\nReturn quote policy if configured in the builder.\nReturn remote enclave identities if configured in the …\nReturn remote node identifier.\nReturn remote runtime ID if configured in the builder.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nWhether the session is in closed state.\nWhether the session handshake has completed and the session\nWhether the session is connected to one of the given nodes.\nWhether the session is in unauthenticated transport state. …\nEnable RAK binding.\nProcess incoming data.\nConfigure quote policy used for remote quote verification.\nRAK binding.\nPublic part of the RAK.\nEnable remote enclave identity verification.\nSet remote runtime ID for node identity verification.\nSession information.\nSet the remote node identifier.\nUse endorsement from host node when establishing sessions.\nVerified TEE remote attestation.\nVerify the RAK binding.\nWrite message to session.\nSessions error.\nA multiplexed session.\nKey for use in the by-idle-time index.\nStructure used for session accounting.\nSession indices and management operations.\nShared pointer to a multiplexed session.\nAdd a session if there is an available spot.\nMark the session as closed.\nCreate a new multiplexed initiator session.\nCreate a new multiplexed responder session.\nRemoves and returns all sessions.\nFetch an existing session from one of the given peers. If …\nFetch an existing session from any peer.\nFetch an existing session from one of the given peers.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nFetch an existing session given its identifier.\nReturn the session’s peer ID.\nReturn remote node identifier.\nReturn the session ID.\nSession information.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nWhether the session is in closed state.\nWhether the session handshake has completed and the session\nWhether the session is in unauthenticated transport state. …\nCreate a new session management instance.\nProcess incoming session data.\nRemove a session that must be currently owned by the …\nRemove one session to free up a slot for the given peer.\nRemove one existing session from the given peer if the …\nRemove one stale session if the total number of sessions …\nSet the session builder to use.\nSet the session’s peer ID.\nSet the remote node identifier.\nUpdate remote enclave identity verification in the session …\nUpdate quote policy used for remote quote verification in …\nUpdate remote runtime ID for node identity verification in …\nWrite message to session and generate a response.\nFrame.\nAn insecure RPC call where messages are sent in plain text.\nRPC call kind.\nA local RPC call.\nProtocol message.\nA secure RPC call using an encrypted and authenticated …\nFeedback on the peer that handled the last EnclaveRPC call.\nSession identifier for multiplexing multiple sessions over …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nSize of this object in bytes.\nGenerate a random session identifier.\nRuns a future to completion on the current Tokio handle’…\nCreate a new asynchronous Tokio runtime.\nErrors.\nInterface to the (untrusted) host node.\nNotification registration options.\nTransaction submission options.\nTransaction submission result.\nOrder of the transaction in the execution batch.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the identity of the host node.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nTransaction output.\nOptional inclusion proof.\nWhether the response should include a proof of transaction …\nRegister for receiving notifications.\nRound in which the transaction was executed.\nSubscribe to runtime block notifications.\nSubscribe to runtime event notifications.\nTarget runtime identifier. If not specified, own runtime …\nSubmit a transaction.\nWhether the call should wait until the transaction is …\nRuntime identity.\nEndorsed TEE capability.\nReturns the argument unchanged.\nCalls U::from(self).\nCreate an uninitialized runtime identity.\nHost node identity public key.\nPublic part of RAK.\nPublic part of REK.\nQuote for RAK.\nRuntime quote policy.\nChecks whether the RAK matches another specified (RAK_pub, …\nVerify a provided RAK binding.\nStarts the runtime.\nConsensus policy verifier.\nPolicy verifier error.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nFetch runtime’s key manager.\nFetch key manager’s policy from the latest verified …\nFetch key manager’s status from the latest verified …\nCreate a new consensus policy verifier.\nFetch runtime’s quote policy from the latest verified …\nVerify that key manager’s policy has been published in …\nVerify that key manager’s status has been published in …\nVerify that runtime’s quote policy has been published in …\nInformation about the host environment.\nRuntime part of the runtime host protocol.\nUntrusted key/value store which stores arbitrary binary …\nStream used to communicate with the host.\nMake a new request to the runtime host and wait for the …\nMake a new request to the runtime host and wait for the …\nName of the consensus backend that is in use for the …\nConsensus layer chain domain separation context.\nConsensus protocol version that is in use for the …\nEnsure that the runtime is ready to process requests and …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nThe supplied runtime configuration.\nThe host environment information for this instance.\nThe runtime identity.\nThe runtime identifier for this instance.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nNode-local runtime configuration.\nAssigned runtime identifier of the loaded runtime.\nSend an async response to a previous request back to the …\nTrivial key/value storage.\nUntrusted key/value storage which stores arbitrary binary …\nReturns the argument unchanged.\nFetch the value for a specific key.\nStore a specific key/value into storage.\nCalls U::from(self).\nMerklized key-value store.\nMerklized key-value store where methods return errors …\nStorage root for transaction IO.\nImmutable merkalized key value store.\nInvalid or uninitialized storage root type.\nAn MKVS iterator.\nAn entry in the write log, describing a single update.\nThe type of entry in the log.\nMerklized key-value store.\nA box type that can contain either internal or leaf nodes.\nA pointer to a node in the tree.\nA reference-counted pointer to a pointer.\nA key-value tree overlay that holds all updates in memory …\nA key prefix.\nStorage root.\nStorage root type.\nStorage root for runtime state.\nA patricia tree-based MKVS implementation.\nThe write log.\nReturn an builder struct to chain configuration calls on.\nCheck if the local MKVS cache contains the given key.\nCheck if the local MKVS cache contains the given key.\nCheck if the key exists in the local cache.\nCommit all database changes to the underlying store.\nCommit all database changes to the underlying store.\nCommit any modifications to the underlying tree.\nCommit tree updates to the underlying database and return …\nCommit any modifications to the underlying tree and then …\nReturn the error that occurred during iteration if any.\nReturn a copy of this pointer containing only hash …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nConstruct a node pointer from a full node.\nFetch entry with given key.\nFetch entry with given key.\nFetch entry with given key.\nGet an existing key.\nGet an existing key.\nThe key under the iterator.\nGet a reference to the node the pointer is pointing to.\nFetch proof for entry with given key.\nFetch proof for entry with given key.\nFetch proof for entry with given key.\nThe value under the iterator.\nCheck if the pointer has a resolved reference to a …\nMerkle root hash.\nConstruct a hash-only pointer.\nUpdate entry with given key.\nUpdate entry with given key.\nInsert a key/value pair into the tree.\nInsert a key/value pair into the tree.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCheck if the pointer is a null pointer.\nReturn whether the iterator is valid.\nReturns an iterator over the tree.\nReturns an iterator over the tree.\nReturns an iterator over the tree.\nReturn an iterator over the tree.\nReturn an iterator over the tree.\nThe key that was inserted or deleted.\nNamespace under which the root is stored.\nCreate a new overlay tree.\nConstruct a new tree instance using the given read syncer …\nAdvance the iterator to the next key.\nConstruct a null pointer.\nPopulate the in-memory tree with nodes for keys starting …\nPopulate the in-memory tree with nodes for keys starting …\nPopulate the in-memory tree with nodes for keys starting …\nPopulate the in-memory tree with nodes for keys starting …\nRemove entry with given key, returning the value at the …\nRemove entry with given key, returning the value at the …\nRemove entry with given key, returning the value at the …\nRemove entry with given key, returning the value at the …\nMoves the iterator to the first key in the tree.\nThe storage type that this root has data for.\nMoves the iterator either at the given key or at the next …\nSets the number of next elements to prefetch.\nThe read-only tree sync interface.\nThe inserted value (empty if the key was deleted).\nMonotonically increasing version number in which the root …\nThe Marshal trait is used for marshaling and unmarshaling …\nMarshal the object into a binary form and return it as a …\nUnmarshal from the given byte slice reference and modify …\nRequest for the SyncGetPrefixes operation.\nRequest for the SyncGet operation.\nA proxy read syncer which forwards calls to the runtime …\nRequest for the SyncIterate operation.\nA no-op read syncer which doesn’t support any of the …\nA Merkle proof for a subtree.\nA Merkle proof builder.\nResponse for requests that produce proofs.\nA proof verifier enables verifying proofs returned by the …\nA raw proof entry.\nReadSync is the interface for synchronizing the in-memory …\nA proxy read syncer which keeps track of call statistics.\nIdentifies a specific tree and a position within that tree.\nReturn self as an Any object, useful for downcasting.\nBuild the (unverified) proof.\nProof entries in pre-order traversal.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nAdd a node to the set of included nodes.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nMerges a previously verified subtree with an existing tree.\nConstruct a new host proxy instance.\nCreate a new proof builder for the given root hash.\nConstruct a new instance, proxying to the given backing …\nCreate a new proof builder for the given root hash and …\nThe caller’s position in the tree structure to allow …\nThe Merkle tree root.\nFetch a single key and returns the corresponding proof.\nCount of sync_get calls made to the underlying read syncer.\nFetch all keys under the given prefixes and returns the …\nCount of sync_get_prefixes calls made to the underlying …\nSeek to a given key and then fetch the specified number of …\nCount of sync_iterate calls made to the underlying read …\nThe root hash this proof is for. This should only be used …\nVerify a proof and generate an in-memory subtree …\nRuntime call context.\nRuntime transaction batch dispatcher.\nRead/write set.\nTransaction tags.\nTransaction I/O tree.\nTransaction protocol types.\nTransaction context.\nFlag indicating whether to only perform transaction check …\nConsensus light block.\nConsensus state tree.\nEpoch corresponding to the currently processed block.\nReturns the argument unchanged.\nThe block header accompanying this transaction.\nCalls U::from(self).\nThe maximum number of messages that can be emitted in this …\nConstruct new transaction context.\nLow-level access to the underlying Runtime Host Protocol.\nResults of processing the previous successful round.\nRuntime state.\nRuntime transaction dispatcher trait.\nResult of processing a batch of ExecuteTx.\nResult of processing an ExecuteTx.\nNo-op dispatcher.\nBlock emitted tags (not emitted by a specific transaction).\nCheck the transactions in the given batch for validity.\nExecute the transactions in the given batch.\nInvoke the finalizer (if any).\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nNumber of processed incoming messages.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nWhether dispatch is supported by this dispatcher.\nEmitted runtime messages.\nTransaction output.\nProcess a query.\nPer-transaction execution results.\nSchedule and execute transactions in the given batch.\nConfigure abort batch flag.\nEmitted tags.\nHashes of transactions to reject.\nA coarsened key prefix that represents any key that starts …\nA set of coarsened keys.\nA read/write set.\nReturns the argument unchanged.\nReturns the argument unchanged.\nSize of the key prefixes (in bytes) used for coarsening …\nCalls U::from(self).\nCalls U::from(self).\nThe read set.\nThe write set.\nTag is a key/value pair of arbitrary byte blobs with …\nA set of tags.\nReturns the argument unchanged.\nCalls U::from(self).\nThe tag key.\nCreate a new tag.\nThe hash of the transaction that emitted the tag.\nThe tag value.\nHash used for block emitted tags not tied to a specific …\nA Merkle tree containing transaction artifacts.\nAdd block tags.\nAdd an input transaction artifact.\nAdd an output transaction artifact.\nCommit updates to the underlying Merkle tree and return …\nReturns the argument unchanged.\nCalls U::from(self).\nCreate a new transaction artifacts tree.\nBatch of transaction inputs/outputs.\nReturns the argument unchanged.\nCalls U::from(self).\nRuntime host protocol message body.\nCheckTx transaction metadata.\nResult of a CheckTx operation.\nComputed batch.\nA serializable error.\nConsensus event kind.\nExecution mode where the batch of transactions is executed …\nBatch execution mode.\nA feature specifying that the runtime supports controlling …\nSet of supported runtime features.\nRequest to host to fetch the consensus events for the …\nResponse from host fetching the consensus events for the …\nHost storage endpoint.\nInvalid message (should never be seen on the wire).\nRuntime protocol message.\nRegistration for runtime event notifications.\nRequest.\nResponse.\nRuntime information request.\nRuntime information response.\nAn event notification.\nExecution mode where the runtime is in control of …\nStorage sync request.\nStorage sync response.\nHeader of the block that emitted the event.\nMessage body.\nA feature specifying that the runtime supports endorsed …\nDescribes the features supported by the runtime.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCompute results header.\nUnique request identifier.\nSize of the initial batch of transactions.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nLog that generates the I/O tree.\nA feature specifying that the runtime supports updating …\nA feature specifying that the runtime supports updating …\nMessage type.\nMessages emitted by the runtime.\nCreate a new error.\nThe runtime protocol version supported by the runtime.\nIf this runtime uses a TEE, then this is the signature of …\nThe version of the runtime.\nSchedule control feature.\nLog of changes to the state tree.\nEvent tags to subscribe to.\nMatching tags.")
\ No newline at end of file
diff --git a/rust/search.desc/oasis_runtime_sdk/oasis_runtime_sdk-desc-0-.js b/rust/search.desc/oasis_runtime_sdk/oasis_runtime_sdk-desc-0-.js
new file mode 100644
index 0000000000..c26c4e0eca
--- /dev/null
+++ b/rust/search.desc/oasis_runtime_sdk/oasis_runtime_sdk-desc-0-.js
@@ -0,0 +1 @@
+searchState.loadedDescShard("oasis_runtime_sdk", 0, "Oasis runtime SDK.\nDerives the Error trait on an enum.\nDerives the Event trait on an enum.\nA protocol or runtime version.\nHandling of different call formats.\nConfiguration types.\nExecution context.\nCryptography.\nTransaction dispatcher.\nExposed EnclaveRPC methods.\nError types for runtimes.\nEvent types for runtimes.\nReturns the argument unchanged.\nA helper attribute for #[sdk_derive(...)]. It doesn’t do …\nHistoric state access.\nCalls U::from(self).\nChecks if two versions are compatible.\nKeymanager interface.\nA helper attribute for #[sdk_derive(...)]. It doesn’t do …\nRuntime modules.\nRuntime modules included with the SDK.\nCreates a new version with given major, minor, and patch …\nRuntime.\nTypes related to schedule control.\nDerives traits from a non-trait impl block (rather than …\nTransaction sender metadata.\nStorage.\nSubcall dispatch.\nModule which contains utilities useful for testing and …\nTypes defined by the SDK.\nConstructs an oasis_sdk::core::common::version::Version …\nAdditional metadata required by the result encoding …\nDecode call arguments.\nDecode call arguments.\nEncode call results.\nEncode call results.\nEncrypt a call result using the X25519-Deoxys-II …\nReturns the argument unchanged.\nDerive the key pair ID for the call data encryption key …\nCalls U::from(self).\nTransaction index within the batch.\nCaller’s ephemeral public key used for X25519.\nSecret key.\nRuntime schedule control configuration.\nSize of each extra batch that the runtime should fetch.\nConstruct a default schedule control configuration.\nReturns the argument unchanged.\nSize of the initial batch that the node should provide to …\nCalls U::from(self).\nMaximum number of transactions that can go in a batch.\nMinimum amount of gas that needs to be remaining in a …\nRuntime SDK context.\nRuntime that the context is being invoked in.\nDispatch context for the whole batch.\nClone this context.\nConsensus state.\nCurrent epoch.\nReturns the argument unchanged.\nReturns a logger.\nHistorical state.\nInformation about the host environment.\nCalls U::from(self).\nWhether method is an allowed query per policy in the local …\nWhether the context has a key manager available (e.g. the …\nThe key manager, if the runtime is confidential.\nReturns node operator-provided local configuration.\nMaximum number of consensus messages that the runtime can …\nCreate a new dispatch context.\nLast runtime block header.\nRuntime ID.\nResults of executing the last successful runtime round.\nWhether smart contracts should be executed in this context.\nRandom number generator based on root VRF key and Merlin …\nCryptographic signatures.\nA multisig configuration. A set of signers with total “…\nError.\nA set of signatures corresponding to a multisig …\nA SignatureSet owned in a Vec.\nOne of the signers in a multisig configuration.\nChecks that the configuration and signature set are …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nThe public key of the signer.\nThe signers.\nThe threshold.\nPerforms some sanity checks. This looks at the …\nThe weight of the signer.\nA leaf RNG.\nA root RNG that can be used to derive domain-separated …\nAppend local entropy to the root RNG.\nAppend an observed subcontext to RNG transcript.\nAppend an observed transaction hash to RNG transcript.\nCreate an independent leaf RNG using this RNG as its …\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCreate an invalid root RNG which will fail when any leaf …\nCreate a new root RNG.\nError.\nA memory-backed signer.\nA public key used for signing.\nVariable-length opaque signature.\nA specific combination of signature and hash.\nCommon trait for memory signers.\nReturn a byte representation of this public key.\nDomain separation context helpers.\nEd25519 signatures.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nRecreate signer from a byte serialization.\nReconstruct the signer from its byte representation.\nConstruct a public key from a slice of bytes.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nReturn the key type as string.\nCreate a new signer from the given seed.\nCreate a new memory signer from a seed.\nCreate a new signer for testing purposes.\nReturn the public key counterpart to the signer’s secret …\nPublic key corresponding to the signer.\nCreate a new random signer.\nSecp256k1 signatures.\nSecp256r1 signatures.\nSecp384r1 signatures.\nGenerate a signature over the context and message.\nGenerate a signature with the private key over the context …\nGenerate a signature for the specified message and …\nGenerate a signature over the message.\nGenerate a signature with the private key over the message.\nSr25519 signatures.\nSerialize the signer into bytes.\nReturn a byte representation of the signer.\nVerify a signature.\nVerify a batch of signatures of the same message.\nVerify the signature of a message.\nVerify signature raw using the underlying method, without …\nReturn the globally configured chain domain separation …\nConfigure the global chain domain separation context.\nA memory-backed signer for Ed25519.\nAn Ed25519 public key.\nReturn a byte representation of this public key.\nReturns the argument unchanged.\nReturns the argument unchanged.\nConstruct a public key from a slice of bytes.\nCalls U::from(self).\nCalls U::from(self).\nVerify a signature.\nVerify signature of a pre-hashed message.\nVerify signature without applying domain separation.\nA memory-backed signer for Secp256k1.\nA Secp256k1 public key (in compressed form).\nReturn a byte representation of this public key.\nReturns the argument unchanged.\nReturns the argument unchanged.\nConstruct a public key from a slice of bytes.\nCalls U::from(self).\nCalls U::from(self).\nDerive an Ethereum-compatible address.\nReturn an alternative byte representation used in deriving …\nVerify a signature.\nVerify signature of a pre-hashed message.\nVerify signature without using any domain separation …\nA memory-backed signer for Secp256r1.\nA Secp256r1 public key (in compressed form).\nReturn a byte representation of this public key.\nReturns the argument unchanged.\nReturns the argument unchanged.\nConstruct a public key from a slice of bytes.\nCalls U::from(self).\nCalls U::from(self).\nVerify a signature.\nVerify signature of a pre-hashed message.\nVerify signature without using any domain separation …\nA memory-backed signer for Secp384r1.\nA Secp384r1 public key (in compressed form).\nReturn a byte representation of this public key.\nReturns the argument unchanged.\nReturns the argument unchanged.\nConstruct a public key from a slice of bytes.\nCalls U::from(self).\nCalls U::from(self).\nVerify a signature.\nVerify signature of a pre-hashed message.\nVerify signature without using any domain separation …\nA Sr25519 public key.\nReturn a byte representation of this public key.\nReturns the argument unchanged.\nConstruct a public key from a slice of bytes.\nCalls U::from(self).\nVerify a signature.\nAdditional options for dispatch operations.\nResult of dispatching a transaction.\nThe runtime dispatcher.\nError emitted by the dispatch process. Note that this …\nCall format metadata.\nCheck whether the given transaction is valid.\nDecode a runtime transaction.\nProcess the given runtime query.\nDispatch a runtime transaction in the given context.\nRun the dispatch steps inside a transaction context. This …\nDispatch a runtime transaction in the given context with …\nExecute the given transaction.\nExecute the given transaction, returning unserialized …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nOptionally only allow methods for which the provided …\nPrefetch prefixes for the given transaction.\nTransaction priority.\nRegister EnclaveRPC methods.\nTransaction call result.\nTransaction sender metadata.\nOptionally skip authentication.\nTransaction tags.\nTransaction hash.\nTransaction index within the batch.\nTransaction size.\nName of the query method.\nArguments for the query method.\nReturns the argument unchanged.\nCalls U::from(self).\nA runtime error that gets propagated to the caller.\nA serializable error.\nError code uniquely identifying the error.\nReturns the argument unchanged.\nCalls U::from(self).\nConsumes self and returns either Ok(err) (where err is a …\nConverts the error into a call result.\nName of the module that emitted the error.\nCreate a new error.\nAn event emitted by the runtime.\nA key-value pair representing an emitted event that will …\nEvent tags with values accumulated by key.\nProvides method for converting event tags into events.\nCode uniquely identifying the event.\nGenerate an EventTag corresponding to the passed event …\nReturns the argument unchanged.\nCalls U::from(self).\nConverts an event into an event tag.\nName of the module that emitted the event.\nHistory host errors.\nInterface to the runtime host to fetch historic …\nFetch events emitted during execution of the block at …\nFetch historic consensus state after executing the block …\nReturns the argument unchanged.\nCalls U::from(self).\nKey pair ID domain separation context.\nKey manager interface.\nConvenience wrapper around an existing KeyManagerClient …\nKey manager error.\nA key pair managed by the key manager.\nA 256-bit key pair identifier.\nSigned public key.\nA state encryption key.\nSet of trusted key manager signing keys.\nChecksum of the key manager state.\nChecksum of the key manager state.\nClear local key cache.\nExpiration epoch.\nReturns the argument unchanged.\nDerive a KeyPairId for use with the key manager functions.\nGet or create named ephemeral key pair for given epoch.\nGet or create named key pair.\nGet ephemeral public key for an epoch and a key pair id.\nGet public key for a key pair id.\nInput key pair (pk, sk)\nCalls U::from(self).\nPublic key.\nKey manager runtime identifier this client is connected …\nKey manager runtime signing key used to sign messages from …\nSign(sk, (key || checksum || runtime id || key pair id || …\nSet of trusted signers.\nState encryption key\nThreshold for determining if enough valid signatures are …\nA fatal error has occurred and the batch must be aborted.\nAn authentication decision for cases where multiple …\nBlock handler.\nA variant of types::transaction::CallResult but used for …\nAuthentication passed, continue with the next …\nResult of invoking the method handler.\nModule error type.\nModule event type.\nCall has completed with failure.\nFee proxy handler.\nGenesis state type.\nInvariant handler.\nMethod handler.\nMigration handler.\nA runtime module.\nInfo handler.\nModule name.\nCall has completed successfully.\nParameters for a runtime module.\nModule parameters.\nStore key used for storing parameters.\nAuthentication passed, no further authentication handlers …\nTransaction handler.\nModule version.\nPerform any action after dispatching the transaction, in …\nPerform any action after call, within the transaction …\nJudge if a raw transaction is good enough to undergo …\nJudge if an unverified transaction is good enough to …\nAuthenticate a transaction.\nPerform any action after authentication and decoding, …\nPerform any action after authentication, within the …\nPerform any common actions at the start of the block …\nCheck invariants.\nDecode a transaction that was sent with module-controlled …\nA convenience function for dispatching method calls.\nDispatch a call.\nDispatch a message result.\nA convenience function for dispatching queries.\nDispatch a query.\nPerform any common actions at the end of the block (after …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nInitialize state from genesis or perform a migration.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nChecks whether the given call is allowed to be called …\nChecks whether the given query is allowed to access …\nChecks whether the given query method is tagged as …\nCheck whether the call result indicates a successful …\nReports info about the module (or modules, if Self is a …\nTransforms DispatchResult<B, R> into Result<R, E>, mapping …\nTransforms DispatchResult<B, R> into Result<R, E>, mapping …\nReturn the module’s parameters.\nAdd storage prefixes to prefetch.\nResolve the proxy payer for the given transaction. If no …\nSet the module’s parameters.\nLists the names of all RPC methods exposed by this module. …\nPerform basic parameter validation.\nMethod access control module.\nAccounts module.\nConsensus module.\nConsensus accounts module.\nCore definitions module.\nRewards module.\nOn-chain coordination for ROFL components.\nModule configuration.\nErrors emitted by the access module.\nTo filter methods by caller address, add them to this …\nThe method access control module.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nMethod access control module types.\nA set of addresses that can be used to define access …\nOnly allow method calls from these addresses; for other …\nA specific kind of access control.\nControl a statically configured set of methods, each with a\nA specific kind of method authorization.\nA set of methods that are subject to access control.\nHelper for creating a method authorization type that only …\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nReturn a new access control configuration.\nHelper for creating a static access control configuration.\nModule’s address that has the common pool.\nModule’s address that has the fee accumulator.\nInterface that can be called from other modules.\nErrors emitted by the accounts module.\nEvents emitted by the accounts module.\nGas costs.\nGenesis state for the accounts module.\nErrors emitted during rewards parameter validation.\nParameters for the accounts module.\nBurn existing tokens, decreasing the total supply.\nMoves the amount into the per-transaction fee accumulator.\nCheck invariants.\nCheck transaction signer account nonces. Return payer …\nEnsures that the given account has at least the specified …\nFee manager.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nFetch addresses.\nFetch an account’s balance of the given denomination.\nFetch an account’s current balances.\nFetch information about a denomination.\nFetch an account’s current nonce.\nFetch total supplies.\nIncrements an account’s nonce.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nMint new tokens, increasing the total supply.\nSets an account’s balance of the given denomination.\nSets an account’s nonce.\nIndicates that the unused portion of the transaction fee …\nSets the total supply for the given denomination.\nState schema constants.\nTake the flag indicating that the unused portion of the …\nTransfer an amount from one account to the other.\nTransfer an amount from one account to the other without …\nAccount module types.\nUpdate transaction signer account nonces.\nThe per-block fee manager that records what fees have been …\nFee updates to apply to state after commit_tx.\nInformation about fees charged for the current transaction.\nTransaction fee amount.\nCommit the fees accumulated for the current block, …\nCommit the currently open transaction fee by moving the …\nDenomination of the transaction fee.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCreate a new per-block fee manager.\nTransaction fee payer address.\nFee payer.\nRecord that a transaction fee has been charged.\nRecord that a portion of the previously charged …\nAmount that should be refunded to fee payer.\nFees charged for the current transaction.\nMap of account addresses to account metadata.\nMap of account addresses to map of denominations to …\nMap of total supplies (per denomination).\nAccount metadata.\nBalances in an account.\nArguments for the Addresses query.\nArguments for the Balances query.\nInformation about a denomination.\nArguments for the DenominationInfo query.\nArguments for the Nonce query.\nTransfer call.\nNumber of decimals that the denomination is using.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nInterface that can be called from other modules.\nEvents emitted by the consensus module (none so far).\nGas costs.\nGenesis state for the consensus module.\nErrors emitted during rewards parameter validation.\nParameters for the consensus module.\nQuery consensus account info.\nConvert runtime amount to consensus amount, scaling as …\nConvert consensus amount to runtime amount, scaling as …\nReturns consensus token denomination.\nQuery consensus delegation info.\nEnsures transaction signer is consensus compatible.\nEscrow an amount of the runtime account funds.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nDetermine consensus height corresponding to the given …\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nMinimum amount that is allowed to be delegated. This …\nReclaim an amount of runtime staked shares.\nCost of the internal round_root call.\nRound roots return the round roots for the given runtime …\nTransfer an amount from the runtime account.\nWithdraw an amount into the runtime account.\nKind of root.\nInternal round root call body.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nModule’s address that has the tokens pending delegation.\nModule’s address that has the tokens pending withdrawal.\nInterface that can be called from other modules.\nEvents emitted by the consensus accounts module.\nGas costs.\nGenesis state for the consensus module.\nParameters for the consensus module.\nCheck invariants.\nDelegate from runtime account to consensus staking account.\nTransfer from consensus staking account to runtime account.\nWhether delegate functionality should be disabled.\nWhether deposit functionality should be disabled.\nWhether undelegate functionality should be disabled.\nWhether withdraw functionality should be disabled.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nState schema.\nCost of storing a delegation/undelegation receipt.\nCost of taking a delegation/undelegation receipt.\nConsensus module types.\nStart the undelegation process of the given number of …\nTransfer from runtime account to consensus staking account.\nMap of active delegations.\nReceipts.\nMap of undelegations.\nAn undelegation queue.\nUndelegation metadata.\nAdd delegation for a given (from, to) pair.\nRecord new undelegation and add to undelegation queue.\nReturns the argument unchanged.\nRetrieve delegation metadata for a given (from, to) pair.\nRetrieve all delegation metadata originating from a given …\nReturn the number of delegated shares for each destination …\nRetrieve all queued undelegations for epochs earlier than …\nRetrieve all undelegation metadata to a given address.\nCalls U::from(self).\nStore the given receipt.\nSubtract delegation from a given (from, to) pair.\nRemove the given receipt from storage if it exists and …\nRemove an existing undelegation and return it.\nBalance query.\nConsensus account query.\nContext for consensus delegate message handler.\nError details from the consensus layer.\nContext for consensus transfer message handler.\nContext for consensus undelegate message handler.\nContext for consensus withdraw message handler.\nDelegate from runtime call.\nInformation about a delegation.\nDelegation query.\nDelegations query.\nDeposit into runtime call. Transfer from consensus staking …\nExtended information about a delegation.\nA receipt.\nKind of receipt.\nTake receipt internal runtime call.\nUndelegate into runtime call.\nInformation about an undelegation.\nUndelegations query.\nWithdraw from runtime call. Transfer from an account in …\nAmount of tokens received.\nUndelegate end epoch.\nEpoch when the undelegation will be complete.\nConsensus layer error.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nAddress being undelegated from.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nWhether the receipt kind is valid.\nUndelegate end receipt.\nReceipt identifier for this undelegation.\nShares received (for delegations).\nThe amount of owned shares.\nThe amount of owned shares.\nThe amount of undelegated shares.\nAddress delegated to.\nWhether to allow submission of read-only transactions in …\nInterface that can be called from other modules.\nModule configuration.\nModule configuration.\nDefault local estimate gas max search iterations …\nDefault local minimum gas price configuration that is used …\nDynamic min gas price parameters.\nWhether gas used events should be emitted for every …\nEstimated gas amount to be added to failed transaction …\nErrors emitted by the core module.\nEvents emitted by the core module.\nThe gas cost of the internal call to retrieve the current …\nThe gas cost of the internal call to retrieve the current …\nGas costs.\nGenesis state for the accounts module.\nLocal configuration that can be provided by the node …\nMethods which are exempt from minimum gas price …\nUnique module name.\nErrors emitted during core parameter validation.\nParameters for the core module.\nSimulation failure error.\nEnables the dynamic min gas price feature which …\nReturns the configured max iterations in the binary search …\nThe maximum number of iterations of the binary search to …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCheck whether the epoch has changed since last processed …\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nReturns true if the failure is “core::Error::OutOfGas”.\nConfigured maximum amount of gas that can be used in a …\nWhen estimating gas in core.EstimateGas, simulate the tx …\nConfigured minimum gas price.\nMinimum gas price to accept.\nRepresents a constant value used to limit the rate at …\nGenerate a proper OutOfGas error, depending on whether the …\nRun a transaction in simulation and return how much gas it …\nReturns the remaining batch-wide gas.\nReturn the remaining tx-wide gas.\nSets the transaction priority to the provided amount.\nSet transaction sender metadata.\nState schema constants.\nTakes and returns the stored transaction priority.\nTakes and returns the stored transaction sender metadata.\nTarget block gas usage indicates the desired block gas …\nAttempt to use gas. If the gas specified would cause …\nAttempt to use gas. If the gas specified would cause …\nReturns the total batch-wide gas used.\nReturn the used tx-wide gas.\nDynamic min gas price.\nLast processed epoch for detecting epoch changes.\nMap of message idx to message handlers for messages …\nRuntime metadata.\nResponse to the call data public key query.\nArguments for the EstimateGas query.\nArguments for the ExecuteReadOnlyTx query.\nResponse to the ExecuteReadOnlyTx query.\nBasic per-module metadata; tracked in core module’s …\nMetadata for an individual module.\nResponse to the RuntimeInfo query.\nKey in the versions map used for the global state version.\nThe address of the caller for which to do estimation. If …\nEpoch of the ephemeral runtime key.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nIf the estimate gas query should fail in case of …\nPublic key used for deriving the shared secret for …\nThe unsigned transaction to estimate.\nA set of state versions for all supported modules.\nModule’s address that has the reward pool.\nErrors emitted by the rewards module.\nGenesis state for the rewards module.\nRewards module.\nErrors emitted during rewards parameter validation.\nParameters for the rewards module.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nState schema constants.\nRewards module types.\nMap of epochs to rewards pending distribution.\nRewards for the epoch.\nAction that should be taken for a given address when …\nA reward schedule.\nErrors emitted during reward schedule validation.\nOne of the time periods in the reward schedule.\nReturns an iterator over addresses that should be rewarded.\nCompute the per-entity reward amount for the given epoch …\nForbids any rewards from accumulating.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nIncrement the reward counter associated with the reward.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nPerform basic reward schedule validation.\nValue of the reward counter.\nModule’s address that has the application stake pool.\nInterface that can be called from other modules.\nModule configuration.\nErrors emitted by the module.\nEvents emitted by the ROFL module.\nGas cost of rofl.AuthorizedOriginEntity call.\nGas cost of rofl.AuthorizedOriginEntity call.\nGas cost of rofl.AuthorizedOriginNode call.\nGas cost of rofl.AuthorizedOriginNode call.\nGas cost of rofl.Create call.\nGas cost of rofl.Create call.\nGas cost of rofl.IsAuthorizedOrigin call.\nGas cost of rofl.IsAuthorizedOrigin call.\nGas cost of rofl.Register call.\nGas cost of rofl.Register call.\nGas cost of rofl.Remove call.\nGas cost of rofl.Remove call.\nGas cost of rofl.StakeThresholds call.\nGas cost of rofl.StakeThresholds call.\nGas cost of rofl.Update call.\nGas cost of rofl.Update call.\nGenesis state for the module.\nErrors emitted during parameter validation.\nParameters for the module.\nAmount of stake required for maintaining an application.\nAmount of stake required for maintaining an application.\nWrapper to make development of ROFL components easier.\nROFL application identifier.\nApplication configurations.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nGet an application’s configuration.\nGet all registered instances for an application.\nGet the Runtime Attestation Key of the ROFL app instance …\nGet the registration descriptor of the ROFL app instance …\nGet a specific registered instance for an application.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nVerify whether the origin transaction is signed by an …\nROFL component application.\nA runtime client meant for use within runtimes.\nApplication environment.\nROFL application version.\nRetrieve the nonce for the given account.\nRuntime client.\nReturn the consensus layer trust root for this runtime; if …\nSecurely perform gas estimation.\nReturns the argument unchanged.\nReturns the argument unchanged.\nRetrieve the gas price in the given denomination.\nIdentifier of the application (used for registrations).\nCalls U::from(self).\nCalls U::from(self).\nRetrieve the latest known runtime round.\nSign a given transaction, submit it and wait for block …\nSign a given transaction, submit it and wait for block …\nCreate a new unsigned transaction.\nLogic that runs on each runtime block. Only one of these …\nPrelude for ROFL applications.\nSecurely query the on-chain runtime component.\nMain application processing loop.\nSign a given transaction, submit it and wait for block …\nTransaction signer.\nStart the application.\nReturn a store corresponding to the given round.\nRun a closure inside a CurrentState context with store for …\nA thread-safe reference-counting pointer. ‘Arc’ stands …\nContains the error value\nContains the success value\nResult<T, Error>\nConsensus layer trust root.\nA protocol or runtime version.\nReturns a reference to the underlying allocator.\nProvides a raw pointer to the data.\nConverts to Arc<T>.\nConverts to Arc<[T]>.\nKnown consensus chain context.\nMakes a clone of the Arc pointer.\nComparison for two Arcs.\nDecrements the strong reference count on the Arc<T> …\nDecrements the strong reference count on the Arc<T> …\nCreates an empty CStr inside an Arc\nCreates an empty [T] inside an Arc\nCreates an empty str inside an Arc\nCreates a new Arc<T>, with the Default value for T.\nAttempt to downcast the Arc<dyn Any + Send + Sync> to a …\nDowncasts the Arc<dyn Any + Send + Sync> to a concrete …\nCreates a new Weak pointer to this allocation.\nDrops the Arc.\nEquality for two Arcs.\nConverts a &CStr into a Arc<CStr>, by copying the contents …\nConverts a [T; N] into an Arc<[T]>.\nConverts a T into an Arc<T>\nReturns the argument unchanged.\nConverts an OsString into an Arc<OsStr> by moving the …\nCreate an atomically reference-counted pointer from a …\nConverts an atomically reference-counted string slice into …\nAllocate a reference-counted slice and move v’s items …\nConverts a PathBuf into an Arc<Path> by moving the PathBuf …\nCopies the string into a newly allocated Arc<OsStr>.\nConverts a CString into an Arc<CStr> by moving the CString …\nAllocate a reference-counted str and copy v into it.\nMove a boxed object to a new, reference-counted allocation.\nConverts a Path into an Arc by copying the Path data into …\nAllocate a reference-counted slice and fill it by cloning v…\nAllocate a reference-counted str and copy v into it.\nReturns the argument unchanged.\nTakes each element in the Iterator and collects it into an …\nConstructs an Arc<T> from a raw pointer.\nConstructs an Arc<T, A> from a raw pointer.\n‘Greater than or equal to’ comparison for two Arcs.\nReturns a mutable reference into the given Arc, if there …\nReturns a mutable reference into the given Arc, without …\nGreater-than comparison for two Arcs.\nKnown hex-encoded trusted consensus layer header hash.\nKnown trusted height.\nIncrements the strong reference count on the Arc<T> …\nIncrements the strong reference count on the Arc<T> …\nCalls U::from(self).\nCalls U::from(self).\nReturns the inner value, if the Arc has exactly one strong …\nConsumes the Arc, returning the wrapped pointer.\nConsumes the Arc, returning the wrapped pointer and …\n‘Less than or equal to’ comparison for two Arcs.\nLess-than comparison for two Arcs.\nMakes a mutable reference into the given Arc.\nInequality for two Arcs.\nConstructs a new Arc<T>.\nConstructs a new Arc<T> while giving you a Weak<T> to the …\nConstructs a new Arc<T> in the provided allocator.\nConstructs a new Arc with uninitialized contents.\nConstructs a new Arc with uninitialized contents in the …\nConstructs a new atomically reference-counted slice with …\nConstructs a new atomically reference-counted slice with …\nConstructs a new Arc with uninitialized contents, with the …\nConstructs a new Arc with uninitialized contents, with the …\nConstructs a new atomically reference-counted slice with …\nConstructs a new atomically reference-counted slice with …\nPartial comparison for two Arcs.\nConstructs a new Pin<Arc<T>>. If T does not implement Unpin…\nConstructs a new Pin<Arc<T, A>> in the provided allocator. …\nReturns true if the two Arcs point to the same allocation …\nKnown runtime identifier.\nGets the number of strong (Arc) pointers to this …\nConstructs a new Arc<T>, returning an error if allocation …\nConstructs a new Arc<T, A> in the provided allocator, …\nConstructs a new Arc with uninitialized contents, …\nConstructs a new Arc with uninitialized contents, in the …\nConstructs a new Arc with uninitialized contents, with the …\nConstructs a new Arc with uninitialized contents, with the …\nConstructs a new Pin<Arc<T>>, return an error if …\nConstructs a new Pin<Arc<T, A>> in the provided allocator, …\nReturns the inner value, if the Arc has exactly one strong …\nIf we have the only reference to T then unwrap it. …\nGets the number of Weak pointers to this allocation.\nHuman readable part for Bech32-encoded application …\nROFL application identifier.\nError.\nSize of an application identifier in bytes.\nReturns the argument unchanged.\nReturns the argument unchanged.\nTries to create a new identifier from Bech32-encoded …\nTries to create a new identifier from raw bytes.\nCreates a new v0 application identifier from creator/nonce …\nCreates a new v0 application identifier from …\nCreates a new v0 application identifier from a global name.\nCalls U::from(self).\nCalls U::from(self).\nConvert the identifier into raw bytes.\nConverts an identifier to Bech32 representation.\nAn allowed endorsement policy.\nAny node can endorse the enclave.\nPer-application ROFL policy.\nCompute node for the current runtime can endorse the …\nEndorsing node pays the gas fees.\nRegistered node from a specific entity can endorse the …\nGas fee payment policy.\nApplication enclave pays the gas fees.\nSpecific node can endorse the enclave.\nObserver node for the current runtime can endorse the …\nThe set of allowed enclave identities.\nThe set of allowed endorsements.\nGas fee payment policy.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nMaximum number of future epochs for which one can register.\nQuote policy.\nInformation about an endorsed key.\nRemoves all expired registrations, e.g. those that expire …\nCreate a new key endorsement information for extra key …\nCreate a new key endorsement information for RAK endorsed …\nReturns the argument unchanged.\nRetrieves an application configuration.\nRetrieves endorser of the given ROFL enclave. In case …\nRetrieves registration of the given ROFL enclave. In case …\nRetrieves all registrations for the given ROFL application.\nCalls U::from(self).\nIdentifier of node that endorsed the enclave.\nRAK of the enclave that endorsed the key. This is only set …\nRemoves an application configuration.\nRemoves an existing registration of the given ROFL enclave.\nUpdates an application configuration.\nUpdates registration of the given ROFL enclave.\nROFL application configuration.\nApplication instance query.\nApplication-related query.\nCreate new ROFL application call.\nROFL application identifier generation scheme.\nRegister ROFL call.\nROFL registration descriptor.\nRemove an existing ROFL application call.\nStake thresholds for managing ROFL.\nUpdate an existing ROFL application call.\nApplication administrator address.\nApplication administrator address.\nROFL application identifier.\nApplication this enclave is registered for.\nROFL application identifier.\nRequired stake for creating new ROFL application.\nEndorsed TEE capability.\nOptional identifier of the endorsing entity.\nEpoch when the ROFL registration expires if not renewed.\nEpoch when the ROFL registration expires if not renewed.\nExtra public keys to endorse (e.g. secp256k1 keys).\nExtra public keys to endorse (e.g. secp256k1 keys).\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nROFL application identifier.\nROFL application identifier.\nROFL application identifier.\nROFL application identifier.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nIdentifier of the endorsing node.\nApplication authentication policy.\nAuthentication policy.\nAuthentication policy.\nRuntime Attestation Key.\nRuntime Attestation Key.\nRuntime Encryption Key.\nIdentifier generation scheme.\nStaked amount.\nModule that provides the accounts API.\nModule that provides the core API.\nHandler for proxy fee payments.\nSupported modules.\nPrefetch limit. To enable prefetch set it to a non-zero …\nA runtime.\nRuntime schedule control configuration.\nState version.\nRuntime version.\nReturn the consensus layer trust root for this runtime; if …\nGenesis state for the runtime.\nWhether a given call is allowed to be invoked …\nWhether a given query method is allowed to access private …\nWhether a given query method is allowed to be invoked.\nPerform state migrations if required.\nPerform runtime-specific state migration. This method is …\nStart the runtime.\nReturn the trusted signers for this runtime; if None, a …\nSchedule control errors.\nInterface to the runtime host that supports schedule …\nFetch the specified set of transactions from the host’s …\nReturns the argument unchanged.\nCalls U::from(self).\nTransaction sender metadata.\nSender address.\nReturns the argument unchanged.\nUnique identifier of the sender, currently derived from …\nCalls U::from(self).\nSender nonce contained in runtime state.\nSender nonce contained in the transaction.\nCheck that transactions are valid for local acceptance …\nState attached to the current thread.\nInformation about the execution environment.\nActually execute transactions during block production.\nExecution mode.\nEnvironment modification options.\nCheck that transactions are still valid before scheduling.\nSimulate transaction outcomes (e.g. for gas estimation).\nMutable block state of a runtime.\nA per-state arbitrary value.\nResult of a transaction helper closure.\nDecoded transaction with additional metadata.\nFetches a block state value entry.\nCommit the current state and return to its parent state.\nCommit a previously started transaction.\nDecoded transaction.\nEmit an event.\nEmit a raw event.\nQueue a message to be emitted by the runtime for consensus …\nEmit an unconditional event.\nEmitted messages count returns the number of messages …\nEmitted messages count returns the number of messages …\nMaximum number of messages that can be emitted.\nAttach a new state to the current thread and enter the …\nAttach a new state to the current thread and enter the …\nEnvironment information.\nOrigin environment information.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nGets a reference to the specified per-state value.\nGets a mutable reference to the specified per-state value.\nWhether the store associated with the state has any …\nTransaction hash.\nHides block values from the current state which will have …\nTransaction index within the batch.\nCreate transaction with metadata for an internally …\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nWhether the execution mode is such that only checks should …\nWhether the execution mode is Mode::Execute.\nWhether the current execution environment is part of an …\nWhether the execution mode is Mode::PreSchedule.\nAn active transaction’s read only flag.\nWhether the execution mode is Mode::Simulate.\nWhether there is an active transaction in the current …\nReturns the nesting level of the current state.\nFetches a local state value entry.\nExecution mode.\nCreate options with default values.\nOpen a child state after which self will point to the …\nRetrieves the existing value or inserts and returns the …\nSize (in bytes) of any pending updates in the associated …\nRandom number generator.\nRollback the current state and return to its parent state.\nRollback a previously started transaction.\nSets the context value, returning a mutable reference to …\nTransaction size.\nStart a new transaction by opening a new child state.\nStore associated with the state.\nTakes the context value, if it exists.\nTake all events accumulated in the current state and …\nTake all regular events accumulated in the current state.\nTake all messages accumulated in the current state.\nTake all unconditional events accumulated in the current …\nAn active transaction’s authentication information.\nAn active transaction’s call format.\nAuthenticated address of the caller.\nAuthenticated caller public key if available.\nAn active transaction’s index (order) within the block.\nAn active transaction’s size in bytes.\nRun a closure with the currently active state.\nRun a closure with the environment of the currently active …\nRun a closure with the origin environment of the currently …\nChange the internal flag of the environment.\nChange the execution mode of the environment.\nRequest for local entropy to be mixed into the current RNG.\nRun a closure with the store of the currently active state.\nRun a closure within a state transaction.\nRun a closure within a state transaction, allowing the …\nChange the active transaction of the environment.\nA key-value store that hashes all keys and stores them as …\nA store for a specific state root that talks to the …\nType of the inner store.\nA key-value store backed by MKVS.\nA key-value store that supports the commit operation.\nAn overlay store which keeps values locally until …\nA key prefix.\nA key-value store that prefixes all keys with the given …\nA key-value store.\nA key-value store that transparently handles …\nCommit any changes to the underlying store.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nFetch entry with given key.\nFetch entry with given key.\nWhether there are any store updates pending to be …\nUpdate entry with given key to the given value.\nUpdate entry with given key to the given value.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nReturns an iterator over the tree.\nCreate a new hashed store.\nCreate a new host store for the given host and root.\nCreate a new overlay store.\nCreate a new prefix store with the given prefix.\nCreate a new typed store.\nCreate a new host store for the given host and root at the …\nSize (in bytes) of any pending updates.\nPopulate the in-memory tree with nodes for keys starting …\nRemove entry with given key.\nRemove entry with given key.\nRollback any changes.\nA key-value store that encrypts all content with DeoxysII.\nErrors emitted by the confidential store.\nSize of the Deoxys-II-256-128 key in bytes.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCreate a new confidential store with the given keypair.\nA validator which allows everything.\nInformation about a subcall to be dispatched.\nResult of dispatching a subcall.\nSubcall validator.\nSubcall body.\nPerform a subcall.\nResult of the subcall.\nAddress of the caller.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nGas used by the subcall.\nThe current subcall depth.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nMaximum subcall depth.\nMaximum gas amount that can be consumed.\nMethod to call.\nValidate a subcall before it is performed.\nMock key manager implementation.\nModule that contains known test keys.\nMock dispatch context for use in tests.\nKey manager error.\nA key pair managed by the key manager.\nA 256-bit key pair identifier.\nSigned public key.\nA state encryption key.\nSet of trusted key manager signing keys.\nChecksum of the key manager state.\nChecksum of the key manager state.\nExpiration epoch.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCreate a KeyPair with only the public key.\nGenerate a new random key (for testing).\nInput key pair (pk, sk)\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nPublic key.\nSize of this object in bytes.\nCreate a KeyPair.\nCreate a new signed public key.\nSign(sk, (key || checksum || runtime id || key pair id || …\nSet of trusted signers.\nState encryption key\nThreshold for determining if enough valid signatures are …\nVerify the signature.\nVerifies that signed data has valid signatures and that …\nTest key A .\nTest key B .\nTest key C .\nTest key D .\nTest key E .\nTest key F .\nTest key G .\nTest address A .\nTest public key A .\nTest Ed25519 public key A .\nTest address derivation information A .\nTest address B .\nTest public key B .\nTest Ed25519 public key B .\nTest address derivation information B .\nTest address C .\nTest public key C .\nTest Ed25519 public key C .\nTest address derivation information C .\nTest address D .\nTest public key D .\nTest Secp256k1 public key D .\nTest address derivation information D .\nTest address E .\nTest public key E .\nTest Secp256k1 public key E .\nTest address derivation information E .\nTest address F .\nTest public key F .\nTest Sr25519 public key F .\nTest address derivation information F .\nTest address G .\nTest public key G .\nTest Sr25519 public key G .\nTest address derivation information G .\nOptions that can be used during mock signer calls.\nA mock runtime that only has the core module.\nMock dispatch context factory.\nA mock signer for use during tests.\nDispatch a call to the given method.\nDispatch a call to the given method with the given options.\nCreate a new mock dispatch context.\nCreate a new mock dispatch context.\nCreate an empty MKVS store.\nShould the call be encrypted.\nTransaction fee.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCreate a new mock signer using the given nonce and …\nDispatch a query to the given method.\nAddress specification for this signer.\nCreate a new mock transaction.\nCreate an instance with the given local configuration.\nAccount address type.\nTypes related to call formats.\nToken types.\nTransaction types.\nHuman readable part for Bech32-encoded addresses.\nV0 runtime address context.\nV0 runtime address version.\nV0 Ed25519 addres context (shared with consensus layer).\nV0 module address context.\nV0 multisig address context.\nV0 Secp256k1 address context.\nV0 Sr25519 address context.\nV0 address version.\nAn account address.\nEd25519 address derivation compatible with the consensus …\nError.\nSize of an address in bytes.\nEthereum-compatible address derivation from Secp256k1 …\nInformation for signature-based authentication and public …\nSr25519 address derivation.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nTries to create a new address from Bech32-encoded string.\nTries to create a new address from raw bytes.\nCreates a new address from a consensus-layer Ed25519 …\nCreates a new address from an Ethereum-compatible address.\nCreates a new address for a specific module and kind.\nCreates a new address for a specific module and raw kind.\nCreates a new address from a multisig configuration.\nCreates a new runtime address.\nCreates a new address from a public key.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nConvert the address into raw bytes.\nCreates a new address from a context, version and data.\nPublic key of the authentication/address derivation …\nConverts an address to Bech32 representation.\nTry to construct an authentication/address derivation …\nCall data key pair ID domain separation context base.\nA call envelope when using the EncryptedX25519DeoxysII …\nA result envelope when using the EncryptedX25519DeoxysII …\nEncrypted call data.\nEncrypted call data.\nEpoch of the ephemeral runtime key.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nNonce.\nNonce.\nCaller’s ephemeral public key used for X25519.\nResult of a message being processed by the consensus layer.\nHandler name and context to be called after message is …\nResult of a message being processed by the consensus layer …\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nConstructs a new message hook invocation.\nToken amount of given denomination in base units.\nName/type of the token.\nMaximum length of a denomination.\nDenomination in native token.\nToken amount in base units.\nDenomination of the token amount.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nRaw representation of a denomination.\nWhether the denomination represents the native token.\nCreates a new token amount of the given denomination.\nCommon information that specifies an address as well as …\nTransaction authentication information.\nA container for data that authenticates a transaction.\nMethod call.\nFormat used for encoding the call (and output) information.\nCall result.\nA caller address.\nEncrypted call data using X25519 for key exchange and …\nError.\nTransaction fee.\nInformation about a fee proxy.\nFor internal child calls (cannot be …\nA non-serializable placeholder value.\nThe latest transaction format version.\nA flag to use module-controlled decoding. The string is an …\nFor multisig authentication.\nFor multisig authentication.\nPlain text call data.\nTransaction signature domain separation context base.\nFor signature authentication.\nFor signature authentication.\nTransaction signer information.\nTransaction.\nTransaction signer.\nAn unverified signed transaction.\nDerives the address.\nDerives the address.\nAmount of base units paid as fee for transaction …\nAppend a new transaction signer information with a …\nAppend a new transaction signer information with a …\nSign the transaction and append the signature.\nAppend a new transaction signer information to the …\nChecks that the address specification and the …\nMethod body.\nDerives the caller address.\nMaximum amount of emitted consensus messages paid for. …\nFee payment information.\nAmount of fee to pay for transaction execution.\nMaximum amount of gas that the transaction can use.\nFinalize the signing process and return the (signed) …\nCall format.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nMaximum amount of gas paid for.\nCalculates gas price from fee amount and gas.\nModule-specific identifier that will handle fee payments …\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCheck whether the call result indicates a successful …\nMethod name.\nModule that will handle the proxy payment.\nConstruct a new transaction signer for the given …\nCreate a new (unsigned) transaction.\nCreate a new signer info from a multisig configuration and …\nCreate a new signer info from a signature address …\nLatest round when the transaction is valid.\nEarliest round when the transaction is valid.\nTransforms CallResult into anyhow::Result<cbor::Value>, …\nPrepare this transaction for signing.\nProxy which has authorized the fees to be paid.\nReturns the public key when the address spec represents a …\nRead-only flag.\nSet amount of fee to pay for transaction execution.\nSet maximum amount of gas that the transaction can use.\nSet a proxy for paying the transaction fee.\nTransaction signer information.\nPerform basic validation on the transaction.\nVerify and deserialize the unverified transaction.\nMaps the caller address to one of the same type but with …")
\ No newline at end of file
diff --git a/rust/search.desc/oasis_runtime_sdk_contracts/oasis_runtime_sdk_contracts-desc-0-.js b/rust/search.desc/oasis_runtime_sdk_contracts/oasis_runtime_sdk_contracts-desc-0-.js
new file mode 100644
index 0000000000..7e32b28290
--- /dev/null
+++ b/rust/search.desc/oasis_runtime_sdk_contracts/oasis_runtime_sdk_contracts-desc-0-.js
@@ -0,0 +1 @@
+searchState.loadedDescShard("oasis_runtime_sdk_contracts", 0, "Smart contracts module.\nModule configuration.\nErrors emitted by the contracts module.\nEvents emitted by the contracts module.\nGas costs.\nGenesis state for the contracts module.\nLocal configuration that can be provided by the node …\nParameters for the contracts module.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nLoads code with the specified code identifier.\nMaximum number of items per page in InstanceRawStorage …\nGas limit for custom queries that invoke smart contracts.\nState schema constants.\nStores code with the specified code identifier.\nContracts module types.\nUploaded code.\nInformation about uploaded code.\nInformation about the deployed contract instance.\nPer-instance key/value store.\nNext code identifier (u64).\nNext instance identifier (u64).\nABI that the given contract should conform to.\nContract call.\nContract call result.\nChange upgrade policy call.\nStored code information.\nUnique stored code identifier.\nCode information query.\nCode storage information query.\nCode storage query result.\nAn event emitted from a contract, wrapped to include …\nCustom contract query.\nCustom query result.\nDeployed code instance information.\nUnique deployed code instance identifier.\nInstance information query.\nInstance raw storage query.\nInstance raw storage query result.\nInstance storage query.\nInstantiate call.\nInstantiate call result.\nCustom Oasis SDK-specific ABI (v1).\nA generic policy that specifies who is allowed to perform …\nPublic key kind.\nPublic key query.\nPublic key query result.\nExposed wrapper for oasis-contract-sdk-types::StoreKind.\nUpgrade call.\nUpload call.\nUpload call result.\nABI.\nABI.\nABI sub-version.\nAddress associated with the contract.\nAddress associated with a specific contract instance.\nConvert identifier to u64.\nConvert identifier to u64.\nChecksum of the key manager state.\nCompiled contract code.\nStored contract code.\nIdentifier of code used by the instance.\nIdentifier of code used by the instance.\nUpdated code identifier.\nInstance creator address.\nArguments to contract’s instantiation function.\nCall arguments.\nArguments to contract’s upgrade function.\nQuery arguments.\nRaw event data emitted by the instance.\nEnforce the given policy by returning an error if the …\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nReturns the argument unchanged.\nCode hash.\nUnique code identifier.\nUnique instance identifier.\nAssigned code identifier.\nAssigned instance identifier.\nInstance identifier.\nInstance identifier.\nInstance identifier.\nCode identifier.\nCode identifier.\nInstance identifier.\nInstance identifier.\nInstance identifier.\nInstance identifier.\nInstance identifier.\nIdentifier of the instance that emitted the event.\nReturn the next identifier in sequence.\nReturn the next identifier in sequence.\nWho is allowed to instantiate this code.\nWho is allowed to instantiate this code.\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nCalls U::from(self).\nList of key-value pairs in contract’s public store.\nStorage key.\nPublic key.\nKind of public key.\nMaximum number of items per page.\nNumber of skipped items.\nSign(sk, (key || checksum)) from the key manager.\nKind of the store to query.\nConvert identifier to storage key representation.\nConvert identifier to storage key representation.\nTokens that should be sent to the contract as part of the …\nTokens that should be sent to the contract as part of the …\nTokens that should be sent to the contract as part of the …\nWho is allowed to upgrade this instance.\nWho is allowed to upgrade this instance.\nUpdated upgrade policy.\nCode uploader address.\nStorage value or None if key doesn’t exist.")
\ No newline at end of file
diff --git a/rust/search.desc/oasis_runtime_sdk_macros/oasis_runtime_sdk_macros-desc-0-.js b/rust/search.desc/oasis_runtime_sdk_macros/oasis_runtime_sdk_macros-desc-0-.js
new file mode 100644
index 0000000000..aea0d77555
--- /dev/null
+++ b/rust/search.desc/oasis_runtime_sdk_macros/oasis_runtime_sdk_macros-desc-0-.js
@@ -0,0 +1 @@
+searchState.loadedDescShard("oasis_runtime_sdk_macros", 0, "Derives the Error trait on an enum.\nDerives the Event trait on an enum.\nA helper attribute for #[sdk_derive(...)]. It doesn’t do …\nA helper attribute for #[sdk_derive(...)]. It doesn’t do …\nDerives traits from a non-trait impl block (rather than …\nConstructs an oasis_sdk::core::common::version::Version …")
\ No newline at end of file
diff --git a/rust/search.desc/rofl_utils/rofl_utils-desc-0-.js b/rust/search.desc/rofl_utils/rofl_utils-desc-0-.js
new file mode 100644
index 0000000000..196fa1a463
--- /dev/null
+++ b/rust/search.desc/rofl_utils/rofl_utils-desc-0-.js
@@ -0,0 +1 @@
+searchState.loadedDescShard("rofl_utils", 0, "ROFL utilities.\nA very simple HTTPS client that can be used inside ROFL …\nAn ureq::Agent that can be used to perform blocking HTTPS …\nAn ureq::Agent with given configuration that can be used …")
\ No newline at end of file
diff --git a/rust/settings.html b/rust/settings.html
new file mode 100644
index 0000000000..f6344a59a1
--- /dev/null
+++ b/rust/settings.html
@@ -0,0 +1 @@
+use honggfuzz::fuzz;
+
+use oasis_core_runtime::storage::mkvs::{marshal::Marshal, NodeBox};
+
+fn main() {
+ loop {
+ fuzz!(|data: &[u8]| {
+ let mut node = NodeBox::default();
+ if node.unmarshal_binary(data).is_err() {
+ return;
+ }
+
+ let _ = node.marshal_binary().unwrap();
+ });
+ }
+}
+use honggfuzz::fuzz;
+
+use oasis_core_runtime::storage::mkvs::sync::{Proof, ProofVerifier, RawProofEntry};
+
+fn main() {
+ loop {
+ fuzz!(|entries: Vec<Option<RawProofEntry>>| {
+ let proof = Proof {
+ entries,
+ ..Default::default()
+ };
+
+ let pv = ProofVerifier;
+ let _ = pv.verify_proof(proof.untrusted_root, &proof);
+ });
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +
//! Contract execution context.
+use crate::{
+ env::{Crypto, Env},
+ event::Event,
+ storage::{ConfidentialStore, PublicStore},
+ types::{address::Address, message::Message, token, CallFormat, InstanceId},
+};
+
+/// Execution context.
+pub trait Context {
+ /// The public store.
+ type PublicStore: PublicStore;
+ /// The confidential store.
+ type ConfidentialStore: ConfidentialStore;
+ /// The environment.
+ type Env: Env + Crypto;
+
+ /// Contract instance identifier.
+ fn instance_id(&self) -> InstanceId;
+
+ /// Contract instance address.
+ fn instance_address(&self) -> &Address;
+
+ /// Caller address.
+ fn caller_address(&self) -> &Address;
+
+ /// Tokens deposited by the caller.
+ fn deposited_tokens(&self) -> &[token::BaseUnits];
+
+ /// Whether the call is read-only and must not make any storage modifications.
+ fn is_read_only(&self) -> bool;
+
+ /// Call format.
+ fn call_format(&self) -> CallFormat;
+
+ /// Emits a message.
+ fn emit_message(&mut self, msg: Message);
+
+ /// Emits an event.
+ fn emit_event<E: Event>(&mut self, event: E);
+
+ /// Public contract store.
+ fn public_store(&mut self) -> &mut Self::PublicStore;
+
+ /// Confidential contract store.
+ fn confidential_store(&mut self) -> &mut Self::ConfidentialStore;
+
+ /// Environment.
+ fn env(&self) -> &Self::Env;
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +
//! The contract trait.
+use crate::{context::Context, error, types};
+
+/// Trait that needs to be implemented by contract implementations.
+pub trait Contract {
+ /// Type of all requests.
+ type Request: cbor::Decode;
+ /// Type of all responses.
+ type Response: cbor::Encode;
+ /// Type of all errors.
+ type Error: error::Error;
+
+ /// Instantiate the contract.
+ fn instantiate<C: Context>(_ctx: &mut C, _request: Self::Request) -> Result<(), Self::Error> {
+ // Default implementation doesn't do anything.
+ Ok(())
+ }
+
+ /// Call the contract.
+ fn call<C: Context>(ctx: &mut C, request: Self::Request)
+ -> Result<Self::Response, Self::Error>;
+
+ /// Query the contract.
+ fn query<C: Context>(
+ _ctx: &mut C,
+ _request: Self::Request,
+ ) -> Result<Self::Response, Self::Error>;
+
+ /// Handle replies from sent messages.
+ fn handle_reply<C: Context>(
+ _ctx: &mut C,
+ _reply: types::message::Reply,
+ ) -> Result<Option<Self::Response>, Self::Error> {
+ // Default implementation does not perform any processing.
+ Ok(None)
+ }
+
+ /// Perform any pre-upgrade tasks. This method is called on the old contract code.
+ ///
+ /// If this method reports an error the upgrade will be aborted.
+ fn pre_upgrade<C: Context>(_ctx: &mut C, _request: Self::Request) -> Result<(), Self::Error> {
+ // Default implementation accepts all upgrades.
+ Ok(())
+ }
+
+ /// Perform any post-upgrade tasks. This method is called on the new contract code.
+ ///
+ /// If this method reports an error the upgrade will be aborted.
+ fn post_upgrade<C: Context>(_ctx: &mut C, _request: Self::Request) -> Result<(), Self::Error> {
+ // Default implementation accepts all upgrades.
+ Ok(())
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +
//! Smart contract environment query interface.
+use oasis_contract_sdk_types::address::Address;
+
+use crate::types::{
+ env::{QueryRequest, QueryResponse},
+ InstanceId,
+};
+
+/// Environment query trait.
+pub trait Env {
+ /// Perform an environment query.
+ fn query<Q: Into<QueryRequest>>(&self, query: Q) -> QueryResponse;
+
+ /// Returns an address for the contract instance id.
+ fn address_for_instance(&self, instance_id: InstanceId) -> Address;
+
+ /// Prints a message to the console. Useful when debugging.
+ #[cfg(feature = "debug-utils")]
+ fn debug_print(&self, msg: &str);
+}
+
+/// Errors that can be returned from crypto functions.
+#[derive(Debug, thiserror::Error)]
+pub enum CryptoError {
+ #[error("decryption or additional data authentication failed")]
+ DecryptionFailed,
+}
+
+/// Crypto helpers trait.
+pub trait Crypto {
+ /// ECDSA public key recovery function.
+ fn ecdsa_recover(&self, input: &[u8]) -> [u8; 65];
+
+ /// Verify an ed25519 message signature.
+ fn signature_verify_ed25519(&self, key: &[u8], message: &[u8], signature: &[u8]) -> bool;
+
+ /// Verify a secp256k1 message signature.
+ fn signature_verify_secp256k1(&self, key: &[u8], message: &[u8], signature: &[u8]) -> bool;
+
+ /// Verify an sr25519 message signature.
+ fn signature_verify_sr25519(
+ &self,
+ key: &[u8],
+ context: &[u8],
+ message: &[u8],
+ signature: &[u8],
+ ) -> bool;
+
+ /// Derive a symmetric key from a public/private key pair.
+ fn x25519_derive_symmetric(&self, public_key: &[u8], private_key: &[u8]) -> [u8; 32];
+
+ /// Encrypt and authenticate a message and authenticate additional data using DeoxysII.
+ fn deoxysii_seal(
+ &self,
+ key: &[u8],
+ nonce: &[u8],
+ message: &[u8],
+ additional_data: &[u8],
+ ) -> Result<Vec<u8>, CryptoError>;
+
+ /// Decrypt and authenticate a message and authenticate additional data using DeoxysII.
+ fn deoxysii_open(
+ &self,
+ key: &[u8],
+ nonce: &[u8],
+ message: &[u8],
+ additional_data: &[u8],
+ ) -> Result<Vec<u8>, CryptoError>;
+
+ /// Fills `dst` with cryptographically secure random bytes.
+ /// Returns the number of bytes written.
+ /// If the optional personalization string (`pers`) is provided, it will be mixed into the RNG to provide additional domain separation.
+ fn random_bytes(&self, pers: &[u8], dst: &mut [u8]) -> usize;
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +
//! Contract error trait.
+use crate::types::ExecutionResult;
+
+/// A contract error that gets propagated to the caller.
+///
+/// It extends `std::error::Error` with module name and error code so that errors can be easily
+/// serialized and transferred between different processes.
+///
+/// This trait can be derived:
+/// ```
+/// # #[cfg(feature = "oasis-contract-sdk-macros")]
+/// # mod example {
+/// # use oasis_contract_sdk_macros::Error;
+/// #[derive(Clone, Debug, Error, thiserror::Error)]
+/// #[sdk_error(autonumber)]
+/// enum Error {
+/// #[error("invalid argument")]
+/// InvalidArgument, // autonumbered to 0
+///
+/// #[error("forbidden")]
+/// #[sdk_error(code = 401)] // manually numbered to 403 (`code` or autonumbering is required)
+/// Forbidden,
+/// }
+/// # }
+/// ```
+pub trait Error: std::error::Error {
+ /// Name of the module that emitted the error.
+ fn module_name(&self) -> &str;
+
+ /// Error code uniquely identifying the error.
+ fn code(&self) -> u32;
+
+ /// Converts the error into an execution result.
+ fn to_execution_result(&self) -> ExecutionResult {
+ ExecutionResult::Failed {
+ module: self.module_name().to_owned(),
+ code: self.code(),
+ message: self.to_string(),
+ }
+ }
+}
+
+impl Error for std::convert::Infallible {
+ fn module_name(&self) -> &str {
+ "(none)"
+ }
+
+ fn code(&self) -> u32 {
+ Default::default()
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +
//! Contract event trait.
+use crate::types;
+
+/// An event emitted by the contract.
+///
+/// This trait can be derived:
+/// ```
+/// # #[cfg(feature = "oasis-contract-sdk-macros")]
+/// # mod example {
+/// # use oasis_contract_sdk_macros::Event;
+/// #[derive(Clone, Debug, cbor::Encode, Event)]
+/// #[cbor(untagged)]
+/// #[sdk_event(autonumber)]
+/// enum MyEvent {
+/// Greeting(String), // autonumbered to 0
+/// #[sdk_event(code = 2)] // manually numbered to 2 (`code` is required if not autonumbering)
+/// DontPanic,
+/// Salutation { // autonumbered to 1
+/// plural: bool,
+/// }
+/// }
+/// # }
+/// ```
+pub trait Event: Sized + cbor::Encode {
+ /// Name of the module that emitted the event.
+ fn module_name(&self) -> &str;
+
+ /// Code uniquely identifying the event.
+ fn code(&self) -> u32;
+
+ /// Converts an event into the raw event type that can be emitted from the contract.
+ fn into_raw(self) -> types::event::Event {
+ types::event::Event {
+ module: self.module_name().to_string(),
+ code: self.code(),
+ data: cbor::to_vec(self),
+ }
+ }
+}
+
+impl Event for types::event::Event {
+ fn module_name(&self) -> &str {
+ &self.module
+ }
+
+ fn code(&self) -> u32 {
+ self.code
+ }
+
+ fn into_raw(self) -> types::event::Event {
+ self
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +
//! Oasis Contract SDK.
+#![cfg_attr(target_arch = "wasm32", feature(wasm_abi))]
+
+#[cfg(target_arch = "wasm32")]
+pub mod abi;
+pub mod context;
+pub mod contract;
+pub mod env;
+pub mod error;
+pub mod event;
+pub mod memory;
+pub mod storage;
+#[cfg(not(target_arch = "wasm32"))]
+pub mod testing;
+
+// Re-export types.
+pub use oasis_contract_sdk_types as types;
+
+// Re-export the CBOR crate for use in macros.
+pub use cbor;
+
+// Re-exports.
+pub use self::{context::Context, contract::Contract, error::Error, event::Event};
+
+// Re-export the SDK support proc-macros.
+#[cfg(feature = "oasis-contract-sdk-macros")]
+pub use oasis_contract_sdk_macros::*;
+
+// Use `wee_alloc` as the global allocator.
+#[cfg(target_arch = "wasm32")]
+#[global_allocator]
+static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT;
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +
//! Memory management.
+use std::marker::PhantomData;
+
+/// A region of memory managed on behalf of the host.
+///
+/// The host is responsible for deallocating the region by calling `deallocate`.
+#[repr(C)]
+pub struct HostRegion {
+ pub offset: u32,
+ pub length: u32,
+}
+
+impl HostRegion {
+ /// Creates a new host region from arguments.
+ ///
+ /// This does not yet transfer memory ownership from the host.
+ pub fn from_arg((offset, length): (u32, u32)) -> Self {
+ Self::from_args(offset, length)
+ }
+
+ /// Creates a new host region from arguments.
+ ///
+ /// This does not yet transfer memory ownership from the host.
+ pub fn from_args(offset: u32, length: u32) -> Self {
+ Self { offset, length }
+ }
+
+ /// Transfers ownership of memory to the host by constructing a host region.
+ pub fn from_vec(data: Vec<u8>) -> Self {
+ let data_ptr = data.as_ptr() as usize;
+ let data_len = data.len();
+ std::mem::forget(data);
+
+ HostRegion {
+ offset: data_ptr as u32,
+ length: data_len as u32,
+ }
+ }
+
+ /// Transfers ownership of memory from the host and returns the vector.
+ ///
+ /// # Safety
+ ///
+ /// This is safe as long as the region was constructed from valid arguments.
+ pub fn into_vec(self) -> Vec<u8> {
+ let ptr = self.offset as *mut u8;
+ assert!(!ptr.is_null());
+
+ unsafe { Vec::from_raw_parts(ptr, self.length as usize, self.length as usize) }
+ }
+
+ /// Returns a new region by dereferencing a pointer to the region.
+ ///
+ /// This does not yet transfer memory ownership from the host.
+ ///
+ /// # Safety
+ ///
+ /// This is safe as long as the pointer is a valid pointer to the region struct.
+ pub unsafe fn deref(arg: *const HostRegion) -> Self {
+ let hr = &*arg;
+ HostRegion {
+ offset: hr.offset,
+ length: hr.length,
+ }
+ }
+}
+
+/// Reference to a host region.
+pub struct HostRegionRef<'a> {
+ pub offset: u32,
+ pub length: u32,
+
+ _lifetime: PhantomData<&'a [u8]>,
+}
+
+impl<'a> HostRegionRef<'a> {
+ /// Creates a new host region from the given byte slice.
+ pub fn from_slice(data: &'a [u8]) -> Self {
+ Self {
+ offset: data.as_ptr() as u32,
+ length: data.len() as u32,
+ _lifetime: PhantomData,
+ }
+ }
+}
+
+/// Allocate memory on host's behalf.
+pub fn allocate_host(length: u32) -> u32 {
+ let data: Vec<u8> = Vec::with_capacity(length as usize);
+ let data_ptr = data.as_ptr() as usize;
+ std::mem::forget(data);
+ data_ptr as u32
+}
+
+/// Deallocate memory on host's behalf.
+pub fn deallocate_host(offset: u32, length: u32) {
+ HostRegion::from_args(offset, length).into_vec();
+}
+//! Smart contract storage interface.
+
+/// Key/value store trait.
+pub trait Store {
+ /// Fetch a given key from contract storage.
+ fn get(&self, key: &[u8]) -> Option<Vec<u8>>;
+
+ /// Insert a given key/value pair into contract storage.
+ fn insert(&mut self, key: &[u8], value: &[u8]);
+
+ /// Remove a given key from contract storage.
+ fn remove(&mut self, key: &[u8]);
+}
+
+/// Marker trait for stores backed by public storage.
+pub trait PublicStore: Store {}
+
+/// Marker trait for stores backed by confidential storage.
+pub trait ConfidentialStore: Store {}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +
//! Utilities for testing smart contracts.
+use std::{
+ collections::BTreeMap,
+ sync::{Arc, Mutex},
+};
+
+use rand_core::{RngCore as _, SeedableRng as _};
+use rand_xorshift::XorShiftRng;
+
+use oasis_contract_sdk_crypto as crypto;
+use oasis_runtime_sdk::crypto::signature;
+
+use crate::{
+ context::Context,
+ env::{Crypto, CryptoError, Env},
+ event::Event,
+ storage::{ConfidentialStore, PublicStore, Store},
+ types::{
+ address::Address,
+ env::{QueryRequest, QueryResponse},
+ event::Event as RawEvent,
+ message::Message,
+ token, CallFormat, ExecutionContext, InstanceId,
+ },
+};
+
+/// Mock store.
+#[derive(Clone, Default)]
+pub struct MockStore {
+ inner: BTreeMap<Vec<u8>, Vec<u8>>,
+}
+
+impl MockStore {
+ /// Create a new empty mock store.
+ pub fn new() -> Self {
+ Self {
+ inner: BTreeMap::new(),
+ }
+ }
+}
+
+impl Store for MockStore {
+ fn get(&self, key: &[u8]) -> Option<Vec<u8>> {
+ self.inner.get(key).cloned()
+ }
+
+ fn insert(&mut self, key: &[u8], value: &[u8]) {
+ self.inner.insert(key.to_owned(), value.to_owned());
+ }
+
+ fn remove(&mut self, key: &[u8]) {
+ self.inner.remove(key);
+ }
+}
+
+impl PublicStore for MockStore {}
+impl ConfidentialStore for MockStore {}
+
+/// Mock environment.
+#[derive(Clone)]
+pub struct MockEnv {
+ rng: Arc<Mutex<XorShiftRng>>,
+}
+
+impl MockEnv {
+ /// Create a new mock environment.
+ pub fn new() -> Self {
+ Default::default()
+ }
+}
+
+impl Default for MockEnv {
+ fn default() -> Self {
+ Self {
+ rng: Arc::new(Mutex::new(XorShiftRng::seed_from_u64(0))),
+ }
+ }
+}
+
+impl Env for MockEnv {
+ fn query<Q: Into<QueryRequest>>(&self, query: Q) -> QueryResponse {
+ match query.into() {
+ QueryRequest::BlockInfo => QueryResponse::BlockInfo {
+ round: 42,
+ epoch: 2,
+ timestamp: 100_000,
+ },
+ _ => unimplemented!(),
+ }
+ }
+
+ fn address_for_instance(&self, instance_id: InstanceId) -> Address {
+ let b = [
+ "test_12345678".as_bytes(),
+ &instance_id.as_u64().to_be_bytes(),
+ ]
+ .concat();
+ Address::from_bytes(&b).unwrap()
+ }
+
+ #[cfg(feature = "debug-utils")]
+ fn debug_print(&self, msg: &str) {
+ eprintln!("{msg}");
+ }
+}
+
+impl Crypto for MockEnv {
+ fn ecdsa_recover(&self, input: &[u8]) -> [u8; 65] {
+ crypto::ecdsa::recover(input).unwrap()
+ }
+
+ fn signature_verify_ed25519(&self, key: &[u8], message: &[u8], signature: &[u8]) -> bool {
+ let key = if let Ok(key) = signature::ed25519::PublicKey::from_bytes(key) {
+ key
+ } else {
+ return false;
+ };
+ let sig: signature::Signature = signature.to_vec().into();
+ key.verify_raw(message, &sig).is_ok()
+ }
+
+ fn signature_verify_secp256k1(&self, key: &[u8], message: &[u8], signature: &[u8]) -> bool {
+ let key = if let Ok(key) = signature::secp256k1::PublicKey::from_bytes(key) {
+ key
+ } else {
+ return false;
+ };
+ let sig: signature::Signature = signature.to_vec().into();
+ key.verify_raw(message, &sig).is_ok()
+ }
+
+ fn signature_verify_sr25519(
+ &self,
+ key: &[u8],
+ context: &[u8],
+ message: &[u8],
+ signature: &[u8],
+ ) -> bool {
+ let key = if let Ok(key) = signature::sr25519::PublicKey::from_bytes(key) {
+ key
+ } else {
+ return false;
+ };
+ let sig: signature::Signature = signature.to_vec().into();
+ key.verify(context, message, &sig).is_ok()
+ }
+
+ fn x25519_derive_symmetric(&self, public_key: &[u8], private_key: &[u8]) -> [u8; 32] {
+ crypto::x25519::derive_symmetric(public_key, private_key).unwrap()
+ }
+
+ fn deoxysii_seal(
+ &self,
+ key: &[u8],
+ nonce: &[u8],
+ message: &[u8],
+ additional_data: &[u8],
+ ) -> Result<Vec<u8>, CryptoError> {
+ Ok(crypto::deoxysii::seal(key, nonce, message, additional_data).unwrap())
+ }
+
+ fn deoxysii_open(
+ &self,
+ key: &[u8],
+ nonce: &[u8],
+ message: &[u8],
+ additional_data: &[u8],
+ ) -> Result<Vec<u8>, CryptoError> {
+ crypto::deoxysii::open(key, nonce, message, additional_data).map_err(|e| match e {
+ crypto::deoxysii::Error::DecryptionFailed => CryptoError::DecryptionFailed,
+ _ => panic!("unexpected crypto error"),
+ })
+ }
+
+ fn random_bytes(&self, _pers: &[u8], dst: &mut [u8]) -> usize {
+ self.rng.lock().unwrap().fill_bytes(dst);
+ dst.len()
+ }
+}
+
+/// A mock contract context suitable for testing.
+pub struct MockContext {
+ /// Execution context.
+ pub ec: ExecutionContext,
+
+ /// Public store.
+ pub public_store: MockStore,
+ /// "Confidential" store.
+ pub confidential_store: MockStore,
+ /// Environment.
+ pub env: MockEnv,
+
+ /// Emitted messages.
+ pub messages: Vec<Message>,
+ /// Emitted events.
+ pub events: Vec<RawEvent>,
+}
+
+impl From<ExecutionContext> for MockContext {
+ fn from(ec: ExecutionContext) -> Self {
+ Self {
+ ec,
+ public_store: MockStore::new(),
+ confidential_store: MockStore::new(),
+ env: MockEnv::new(),
+ messages: Vec::new(),
+ events: Vec::new(),
+ }
+ }
+}
+
+impl Context for MockContext {
+ type PublicStore = MockStore;
+ type ConfidentialStore = MockStore;
+ type Env = MockEnv;
+
+ fn instance_id(&self) -> InstanceId {
+ self.ec.instance_id
+ }
+
+ fn instance_address(&self) -> &Address {
+ &self.ec.instance_address
+ }
+
+ fn caller_address(&self) -> &Address {
+ &self.ec.caller_address
+ }
+
+ fn deposited_tokens(&self) -> &[token::BaseUnits] {
+ &self.ec.deposited_tokens
+ }
+
+ fn is_read_only(&self) -> bool {
+ self.ec.read_only
+ }
+
+ fn call_format(&self) -> CallFormat {
+ self.ec.call_format
+ }
+
+ fn emit_message(&mut self, msg: Message) {
+ self.messages.push(msg);
+ }
+
+ fn emit_event<E: Event>(&mut self, event: E) {
+ self.events.push(event.into_raw());
+ }
+
+ fn public_store(&mut self) -> &mut Self::PublicStore {
+ &mut self.public_store
+ }
+
+ fn confidential_store(&mut self) -> &mut Self::ConfidentialStore {
+ &mut self.confidential_store
+ }
+
+ fn env(&self) -> &Self::Env {
+ &self.env
+ }
+}
+
+/// A macro that creates Oasis ABI entry points.
+#[macro_export]
+#[doc(hidden)]
+macro_rules! __create_contract {
+ ($name:ty) => {};
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +
//! Low-level storage primitive that holds one value.
+use std::marker::PhantomData;
+
+use oasis_contract_sdk::storage::{ConfidentialStore, PublicStore};
+
+macro_rules! declare_cell {
+ ($name:ident, $store:ident) => {
+ /// A storage cell identifies a storage key of a specific type.
+ pub struct $name<'key, T> {
+ key: &'key [u8],
+ _type: PhantomData<T>,
+ }
+
+ impl<'key, T> $name<'key, T> {
+ /// Create a new storage cell with the specified key and type.
+ pub const fn new(key: &'key [u8]) -> Self {
+ Self {
+ key,
+ _type: PhantomData,
+ }
+ }
+
+ /// Clear the value in the storage cell.
+ pub fn clear(&self, store: &mut dyn $store) {
+ store.remove(self.key);
+ }
+ }
+
+ impl<'key, T> $name<'key, T>
+ where
+ T: cbor::Decode,
+ {
+ /// Return the current value of the storage cell.
+ ///
+ /// # Panics
+ ///
+ /// The method will panic in case the raw cell value cannot be deserialized.
+ ///
+ pub fn get(&self, store: &dyn $store) -> Option<T> {
+ store
+ .get(self.key)
+ .map(|raw| cbor::from_slice(&raw).unwrap())
+ }
+ }
+
+ impl<'key, T> $name<'key, T>
+ where
+ T: cbor::Encode,
+ {
+ /// Set the value of the storage cell.
+ pub fn set(&self, store: &mut dyn $store, value: T) {
+ store.insert(self.key, &cbor::to_vec(value));
+ }
+ }
+ };
+}
+
+declare_cell!(PublicCell, PublicStore);
+declare_cell!(ConfidentialCell, ConfidentialStore);
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +
//! A map backed by contract storage.
+use std::{convert::TryInto, marker::PhantomData};
+
+use oasis_contract_sdk::{
+ storage::{ConfidentialStore, PublicStore},
+ types::address::Address,
+};
+
+use crate::cell::{ConfidentialCell, PublicCell};
+
+macro_rules! declare_map {
+ ($name:ident, $cell:ident, $store:ident) => {
+ /// A map backed by contract storage.
+ pub struct $name<'key, K, V> {
+ /// Unique map identifier.
+ key: &'key [u8],
+
+ _key: PhantomData<K>,
+ _value: PhantomData<V>,
+ }
+
+ impl<'key, K, V> $name<'key, K, V> {
+ /// Create a new map instance.
+ pub const fn new(key: &'key [u8]) -> Self {
+ Self {
+ key,
+ _key: PhantomData,
+ _value: PhantomData,
+ }
+ }
+ }
+
+ impl<'key, K, V> $name<'key, K, V>
+ where
+ K: MapKey,
+ V: cbor::Encode + cbor::Decode,
+ {
+ fn key(&self, key: K) -> Vec<u8> {
+ let raw_key = key.key();
+ encode_length_prefixed_path(
+ self.key,
+ &raw_key[..raw_key.len() - 1],
+ raw_key[raw_key.len() - 1],
+ )
+ }
+
+ /// Lookup a given key.
+ pub fn get(&self, store: &dyn $store, key: K) -> Option<V> {
+ $cell::new(&self.key(key)).get(store)
+ }
+
+ /// Insert a given key/value pair.
+ pub fn insert(&self, store: &mut dyn $store, key: K, value: V) {
+ $cell::new(&self.key(key)).set(store, value);
+ }
+
+ /// Remove a given key.
+ pub fn remove(&self, store: &mut dyn $store, key: K) {
+ $cell::<V>::new(&self.key(key)).clear(store);
+ }
+ }
+ };
+}
+
+declare_map!(PublicMap, PublicCell, PublicStore);
+declare_map!(ConfidentialMap, ConfidentialCell, ConfidentialStore);
+
+/// A trait for types which can be used as map keys.
+pub trait MapKey {
+ /// Return the composite key.
+ fn key(&self) -> Vec<&[u8]>;
+}
+
+impl<const N: usize> MapKey for [u8; N] {
+ fn key(&self) -> Vec<&[u8]> {
+ vec![self]
+ }
+}
+
+impl MapKey for &[u8] {
+ fn key(&self) -> Vec<&[u8]> {
+ vec![self]
+ }
+}
+
+impl MapKey for &str {
+ fn key(&self) -> Vec<&[u8]> {
+ vec![self.as_bytes()]
+ }
+}
+
+impl MapKey for Vec<u8> {
+ fn key(&self) -> Vec<&[u8]> {
+ vec![self]
+ }
+}
+
+impl MapKey for String {
+ fn key(&self) -> Vec<&[u8]> {
+ vec![self.as_bytes()]
+ }
+}
+
+impl<T, U> MapKey for (T, U)
+where
+ T: MapKey,
+ U: MapKey,
+{
+ fn key(&self) -> Vec<&[u8]> {
+ let mut key = self.0.key();
+ key.extend(self.1.key());
+ key
+ }
+}
+
+impl<T, U, V> MapKey for (T, U, V)
+where
+ T: MapKey,
+ U: MapKey,
+ V: MapKey,
+{
+ fn key(&self) -> Vec<&[u8]> {
+ let mut key = self.0.key();
+ key.extend(self.1.key());
+ key.extend(self.2.key());
+ key
+ }
+}
+
+impl MapKey for Address {
+ fn key(&self) -> Vec<&[u8]> {
+ vec![self.as_ref()]
+ }
+}
+
+/// A trait representing an integer that can be encoded into big-endian bytes.
+pub trait Integer {
+ /// Type of the encoded representation.
+ type Encoded: AsRef<[u8]>;
+
+ /// Return the memory representation of this integer as a byte array in big-endian byte order.
+ fn to_be_bytes(self) -> Self::Encoded;
+}
+
+macro_rules! impl_integer_for_primitive {
+ ($ty:ty) => {
+ impl Integer for $ty {
+ type Encoded = [u8; std::mem::size_of::<$ty>()];
+
+ fn to_be_bytes(self) -> Self::Encoded {
+ <$ty>::to_be_bytes(self)
+ }
+ }
+ };
+}
+
+impl_integer_for_primitive!(u8);
+impl_integer_for_primitive!(u16);
+impl_integer_for_primitive!(u32);
+impl_integer_for_primitive!(u64);
+impl_integer_for_primitive!(u128);
+
+impl_integer_for_primitive!(i8);
+impl_integer_for_primitive!(i16);
+impl_integer_for_primitive!(i32);
+impl_integer_for_primitive!(i64);
+impl_integer_for_primitive!(i128);
+
+/// An integer in big-endian representation.
+pub struct Int<I: Integer> {
+ encoded: I::Encoded,
+ _type: PhantomData<I>,
+}
+
+impl<I: Integer> Int<I> {
+ /// Create a new integer in big-endian representation.
+ pub fn new(v: I) -> Self {
+ Self {
+ encoded: v.to_be_bytes(),
+ _type: PhantomData,
+ }
+ }
+}
+
+impl<I: Integer> From<I> for Int<I> {
+ fn from(v: I) -> Self {
+ Self::new(v)
+ }
+}
+
+impl<I: Integer> MapKey for Int<I> {
+ fn key(&self) -> Vec<&[u8]> {
+ vec![self.encoded.as_ref()]
+ }
+}
+
+/// Encodes the given components as a length-prefixed path.
+fn encode_length_prefixed_path(front: &[u8], middle: &[&[u8]], back: &[u8]) -> Vec<u8> {
+ let size = middle.iter().fold(0, |acc, k| acc + k.len() + 1);
+ let mut output = Vec::with_capacity(front.len() + size + back.len());
+
+ // Front is not length-prefixed.
+ output.extend_from_slice(front);
+ // Middle keys are length-prefixed.
+ for key in middle {
+ output.extend_from_slice(&encode_length(key));
+ output.extend_from_slice(key);
+ }
+ // Back is not length-prefixed.
+ output.extend_from_slice(back);
+
+ output
+}
+
+/// Encode the length of a storage key.
+///
+/// # Panics
+///
+/// This function will panic if the key length is greater than 255 bytes.
+fn encode_length(key: &[u8]) -> [u8; 1] {
+ [key.len().try_into().expect("key length greater than 255")]
+}
+
+#[cfg(test)]
+mod test {
+ use oasis_contract_sdk::testing::MockStore;
+
+ use super::*;
+
+ #[test]
+ fn test_map_basic() {
+ let mut store = MockStore::new();
+ let map: PublicMap<&str, u64> = PublicMap::new(b"test");
+
+ assert_eq!(map.get(&store, "foo"), None);
+ map.insert(&mut store, "foo", 42);
+ assert_eq!(map.get(&store, "foo"), Some(42));
+
+ let map: PublicMap<Int<u64>, String> = PublicMap::new(b"test2");
+
+ assert_eq!(map.get(&store, 42.into()), None);
+ map.insert(&mut store, 42.into(), "hello".to_string());
+ assert_eq!(map.get(&store, 42.into()), Some("hello".to_string()));
+
+ map.remove(&mut store, 42.into());
+ assert_eq!(map.get(&store, 42.into()), None);
+ }
+
+ #[test]
+ fn test_map_composite() {
+ let mut store = MockStore::new();
+ let map: PublicMap<(&str, &str), u64> = PublicMap::new(b"test");
+
+ assert_eq!(map.get(&store, ("foo", "bar")), None);
+ map.insert(&mut store, ("foo", "bar"), 42);
+ assert_eq!(map.get(&store, ("foo", "bar")), Some(42));
+ // Make sure we have proper key separation due to length-prefixing.
+ assert_eq!(map.get(&store, ("foob", "ar")), None);
+
+ map.remove(&mut store, ("foo", "bar"));
+ assert_eq!(map.get(&store, ("foo", "bar")), None);
+ }
+
+ #[test]
+ fn test_encode_length() {
+ assert_eq!(encode_length(b"foo"), [0x03]);
+ }
+
+ #[test]
+ #[should_panic]
+ fn test_encode_length_too_long() {
+ let v = vec![0x00; 260];
+ encode_length(&v);
+ }
+
+ #[test]
+ fn test_encode_length_prefixed_path() {
+ let four_five_six = vec![4, 5, 6];
+ let tcs = vec![
+ (vec![], vec![], vec![], vec![]),
+ (vec![1, 2, 3], vec![], vec![], vec![1, 2, 3]),
+ (vec![1, 2, 3], vec![], vec![4, 5, 6], vec![1, 2, 3, 4, 5, 6]),
+ (
+ vec![1, 2, 3],
+ vec![&four_five_six[..]],
+ vec![7, 8, 9],
+ vec![1, 2, 3, 3, 4, 5, 6, 7, 8, 9],
+ ),
+ (
+ vec![1, 2, 3],
+ vec![&four_five_six[..], &four_five_six[..]],
+ vec![7, 8, 9],
+ vec![1, 2, 3, 3, 4, 5, 6, 3, 4, 5, 6, 7, 8, 9],
+ ),
+ ];
+
+ for (front, middle, back, expected) in tcs {
+ assert_eq!(
+ encode_length_prefixed_path(&front, &middle, &back),
+ expected
+ );
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +
//! A minimal representation of an Oasis Runtime SDK address.
+use std::convert::TryFrom;
+
+use bech32::{Bech32, Hrp};
+use thiserror::Error;
+
+const ADDRESS_VERSION_SIZE: usize = 1;
+const ADDRESS_DATA_SIZE: usize = 20;
+const ADDRESS_SIZE: usize = ADDRESS_VERSION_SIZE + ADDRESS_DATA_SIZE;
+
+const ADDRESS_BECH32_HRP: Hrp = Hrp::parse_unchecked("oasis");
+
+/// Error.
+#[derive(Error, Debug)]
+pub enum Error {
+ #[error("malformed address")]
+ MalformedAddress,
+}
+
+/// An account address.
+#[derive(
+ Copy, Clone, Default, Debug, PartialEq, Eq, PartialOrd, Ord, cbor::Encode, cbor::Decode,
+)]
+#[cbor(transparent)]
+pub struct Address([u8; ADDRESS_SIZE]);
+
+impl Address {
+ /// Size of an address in bytes.
+ pub const SIZE: usize = ADDRESS_SIZE;
+
+ /// Tries to create a new address from raw bytes.
+ pub fn from_bytes(data: &[u8]) -> Result<Self, Error> {
+ if data.len() != ADDRESS_SIZE {
+ return Err(Error::MalformedAddress);
+ }
+
+ let mut a = [0; ADDRESS_SIZE];
+ a.copy_from_slice(data);
+
+ Ok(Self(a))
+ }
+
+ /// Tries to create a new address from Bech32-encoded string.
+ pub fn from_bech32(data: &str) -> Result<Self, Error> {
+ let (hrp, data) = bech32::decode(data).map_err(|_| Error::MalformedAddress)?;
+ if hrp != ADDRESS_BECH32_HRP {
+ return Err(Error::MalformedAddress);
+ }
+
+ Address::from_bytes(&data)
+ }
+
+ /// Converts an address to Bech32 representation.
+ pub fn to_bech32(self) -> String {
+ bech32::encode::<Bech32>(ADDRESS_BECH32_HRP, &self.0).unwrap()
+ }
+}
+
+impl AsRef<[u8]> for Address {
+ fn as_ref(&self) -> &[u8] {
+ &self.0
+ }
+}
+
+impl TryFrom<&[u8]> for Address {
+ type Error = Error;
+
+ fn try_from(bytes: &[u8]) -> Result<Self, Self::Error> {
+ Self::from_bytes(bytes)
+ }
+}
+
+#[cfg(feature = "oasis-runtime-sdk")]
+impl From<oasis_runtime_sdk::types::address::Address> for Address {
+ fn from(a: oasis_runtime_sdk::types::address::Address) -> Self {
+ Self(a.into_bytes())
+ }
+}
+
+#[cfg(feature = "oasis-runtime-sdk")]
+impl From<Address> for oasis_runtime_sdk::types::address::Address {
+ fn from(a: Address) -> Self {
+ oasis_runtime_sdk::types::address::Address::from_bytes(&a.0).unwrap()
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use bech32::Bech32m;
+
+ use super::*;
+
+ #[test]
+ fn test_address_try_from_bytes() {
+ let bytes_fixture = vec![42u8; ADDRESS_SIZE + 1];
+ assert_eq!(
+ Address::try_from(&bytes_fixture[0..ADDRESS_SIZE]).unwrap(),
+ Address::from_bytes(&bytes_fixture[0..ADDRESS_SIZE]).unwrap()
+ );
+ assert!(matches!(
+ Address::try_from(bytes_fixture.as_slice()).unwrap_err(),
+ Error::MalformedAddress
+ ));
+ }
+
+ #[test]
+ fn test_address_from_bech32_invalid_hrp() {
+ assert!(matches!(
+ Address::from_bech32("sisoa1qpcprk8jxpsjxw9fadxvzrv9ln7td69yus8rmtux").unwrap_err(),
+ Error::MalformedAddress,
+ ));
+ }
+
+ #[test]
+ fn test_address_from_bech32_invalid_variant() {
+ let b = vec![42u8; ADDRESS_SIZE];
+ let bech32_addr = bech32::encode::<Bech32>(ADDRESS_BECH32_HRP, &b).unwrap();
+ let bech32m_addr = bech32::encode::<Bech32m>(ADDRESS_BECH32_HRP, &b).unwrap();
+
+ assert!(
+ Address::from_bech32(&bech32_addr).is_ok(),
+ "bech32 address should be ok"
+ );
+ assert!(
+ Address::from_bech32(&bech32m_addr).is_ok(),
+ "bech32m address should be ok",
+ );
+ }
+}
+//! Cryptography-related types.
+use std::convert::TryFrom;
+
+/// Signature kind.
+#[derive(Clone, Copy)]
+#[repr(u32)]
+pub enum SignatureKind {
+ Ed25519 = 0,
+ Secp256k1 = 1,
+ Sr25519 = 2,
+}
+
+impl TryFrom<u32> for SignatureKind {
+ type Error = u32;
+
+ fn try_from(value: u32) -> Result<Self, Self::Error> {
+ match value {
+ 0 => Ok(Self::Ed25519),
+ 1 => Ok(Self::Secp256k1),
+ 2 => Ok(Self::Sr25519),
+ _ => Err(value),
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +
//! Environment query-related types.
+use crate::{address::Address, token::Denomination};
+
+/// A query request.
+#[non_exhaustive]
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub enum QueryRequest {
+ /// Information about the current runtime block.
+ #[cbor(rename = "block_info")]
+ BlockInfo,
+
+ /// Accounts queries.
+ #[cbor(rename = "accounts")]
+ Accounts(AccountsQuery),
+}
+
+/// A query response.
+#[non_exhaustive]
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub enum QueryResponse {
+ /// Indication of a failing request.
+ #[cbor(rename = "error")]
+ Error {
+ module: String,
+ code: u32,
+ message: String,
+ },
+
+ /// Information about the current runtime block.
+ #[cbor(rename = "block_info")]
+ BlockInfo {
+ round: u64,
+ epoch: u64,
+ timestamp: u64,
+ },
+
+ /// Accounts queries.
+ #[cbor(rename = "accounts")]
+ Accounts(AccountsResponse),
+}
+
+/// Accounts API queries.
+#[non_exhaustive]
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub enum AccountsQuery {
+ /// Query an account's balance.
+ #[cbor(rename = "balance")]
+ Balance {
+ address: Address,
+ denomination: Denomination,
+ },
+}
+
+impl From<AccountsQuery> for QueryRequest {
+ fn from(q: AccountsQuery) -> Self {
+ Self::Accounts(q)
+ }
+}
+
+/// Accounts API responses.
+#[non_exhaustive]
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub enum AccountsResponse {
+ /// An account's balance of the given denomination.
+ Balance { balance: u128 },
+}
+
+impl From<AccountsResponse> for QueryResponse {
+ fn from(q: AccountsResponse) -> Self {
+ Self::Accounts(q)
+ }
+}
+//! Events.
+
+/// An event emitted from the contract.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct Event {
+ /// Optional module name.
+ #[cbor(optional)]
+ pub module: String,
+
+ /// Unique code representing the event for the given module.
+ pub code: u32,
+
+ /// Arbitrary data associated with the event.
+ #[cbor(optional)]
+ pub data: Vec<u8>,
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +
//! A collection of common types used by the Oasis Contract SDK.
+
+pub mod address;
+pub mod crypto;
+pub mod env;
+pub mod event;
+pub mod message;
+pub mod modules;
+pub mod storage;
+pub mod token;
+
+pub mod testing;
+
+/// Unique stored code identifier.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, cbor::Decode, cbor::Encode)]
+#[cbor(transparent)]
+pub struct CodeId(u64);
+
+impl CodeId {
+ /// Convert identifier to u64.
+ pub fn as_u64(&self) -> u64 {
+ self.0
+ }
+
+ /// Return the next identifier in sequence.
+ pub fn increment(&self) -> Self {
+ CodeId(self.0 + 1)
+ }
+
+ /// Convert identifier to storage key representation.
+ pub fn to_storage_key(self) -> [u8; 8] {
+ self.0.to_be_bytes()
+ }
+}
+
+impl From<u64> for CodeId {
+ fn from(v: u64) -> Self {
+ CodeId(v)
+ }
+}
+
+/// Unique deployed code instance identifier.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, cbor::Decode, cbor::Encode)]
+#[cbor(transparent)]
+pub struct InstanceId(u64);
+
+impl InstanceId {
+ /// Convert identifier to u64.
+ pub fn as_u64(&self) -> u64 {
+ self.0
+ }
+
+ /// Return the next identifier in sequence.
+ pub fn increment(&self) -> Self {
+ InstanceId(self.0 + 1)
+ }
+
+ /// Convert identifier to storage key representation.
+ pub fn to_storage_key(self) -> [u8; 8] {
+ self.0.to_be_bytes()
+ }
+}
+
+impl From<u64> for InstanceId {
+ fn from(v: u64) -> Self {
+ InstanceId(v)
+ }
+}
+
+/// Format used for encoding the call (and output) information.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+#[repr(u8)]
+#[cbor(with_default)]
+pub enum CallFormat {
+ /// Plain text call data.
+ Plain = 0,
+ /// Encrypted call data using X25519 for key exchange and Deoxys-II for symmetric encryption.
+ EncryptedX25519DeoxysII = 1,
+}
+
+impl CallFormat {
+ fn is_plain(&self) -> bool {
+ matches!(self, CallFormat::Plain)
+ }
+}
+
+impl Default for CallFormat {
+ fn default() -> Self {
+ Self::Plain
+ }
+}
+
+#[cfg(feature = "oasis-runtime-sdk")]
+impl From<oasis_runtime_sdk::types::transaction::CallFormat> for CallFormat {
+ fn from(a: oasis_runtime_sdk::types::transaction::CallFormat) -> Self {
+ use oasis_runtime_sdk::types::transaction::CallFormat as RuntimeCallFormat;
+
+ match a {
+ RuntimeCallFormat::Plain => Self::Plain,
+ RuntimeCallFormat::EncryptedX25519DeoxysII => Self::EncryptedX25519DeoxysII,
+ }
+ }
+}
+
+/// Execution context.
+///
+/// Contains information that is useful on most invocations as it is always
+/// included without requiring any explicit queries.
+#[derive(Debug, Default, cbor::Decode, cbor::Encode)]
+pub struct ExecutionContext {
+ /// Contract instance identifier.
+ pub instance_id: InstanceId,
+ /// Contract instance address.
+ pub instance_address: address::Address,
+ /// Caller address.
+ pub caller_address: address::Address,
+ /// Tokens deposited by the caller.
+ #[cbor(optional)]
+ pub deposited_tokens: Vec<token::BaseUnits>,
+ /// Read-only flag.
+ ///
+ /// A read-only call cannot make any changes to runtime state. Any attempt at modifying state
+ /// will result in the call failing.
+ #[cbor(optional)]
+ pub read_only: bool,
+ /// Transaction's call format.
+ #[cbor(optional, skip_serializing_if = "CallFormat::is_plain")]
+ pub call_format: CallFormat,
+}
+
+/// Contract execution result.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub enum ExecutionResult {
+ #[cbor(rename = "ok")]
+ Ok(ExecutionOk),
+
+ #[cbor(rename = "fail")]
+ Failed {
+ #[cbor(optional)]
+ module: String,
+
+ code: u32,
+
+ #[cbor(optional)]
+ message: String,
+ },
+}
+
+/// Result of a successful contract execution.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct ExecutionOk {
+ /// Raw data returned from the contract.
+ pub data: Vec<u8>,
+ /// Messages emitted from the contract.
+ #[cbor(optional)]
+ pub messages: Vec<message::Message>,
+ /// Events emitted from the contract.
+ #[cbor(optional)]
+ pub events: Vec<event::Event>,
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +
//! Messages that can be emitted by contracts.
+
+/// Messages can be emitted by contracts and are processed after the contract execution completes.
+#[non_exhaustive]
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub enum Message {
+ /// Calls an arbitrary runtime method handler in a child context with an optional gas limit.
+ ///
+ /// The call is executed in the context of the smart contract as the caller within the same
+ /// transaction.
+ ///
+ /// This can be used to call other smart contracts.
+ #[cbor(rename = "call")]
+ Call {
+ #[cbor(optional)]
+ id: u64,
+ reply: NotifyReply,
+ method: String,
+ body: cbor::Value,
+ #[cbor(optional)]
+ max_gas: Option<u64>,
+ #[cbor(optional)]
+ data: Option<cbor::Value>,
+ },
+}
+
+/// Specifies when the caller (smart contract) wants to be notified of a reply.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+#[repr(u8)]
+pub enum NotifyReply {
+ Never = 0,
+ OnError = 1,
+ OnSuccess = 2,
+ Always = 3,
+}
+
+/// Replies to delivered messages.
+#[non_exhaustive]
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub enum Reply {
+ /// Reply from a call message.
+ #[cbor(rename = "call")]
+ Call {
+ #[cbor(optional)]
+ id: u64,
+ result: CallResult,
+ #[cbor(optional)]
+ data: Option<cbor::Value>,
+ },
+}
+
+/// Call result.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub enum CallResult {
+ #[cbor(rename = "ok")]
+ Ok(cbor::Value),
+
+ #[cbor(rename = "fail")]
+ Failed { module: String, code: u32 },
+}
+
+impl CallResult {
+ /// Check whether the call result indicates a successful operation or not.
+ pub fn is_success(&self) -> bool {
+ match self {
+ CallResult::Ok(_) => true,
+ CallResult::Failed { .. } => false,
+ }
+ }
+}
+
+#[cfg(feature = "oasis-runtime-sdk")]
+impl From<oasis_runtime_sdk::module::CallResult> for CallResult {
+ fn from(r: oasis_runtime_sdk::module::CallResult) -> Self {
+ match r {
+ oasis_runtime_sdk::module::CallResult::Ok(value) => Self::Ok(value),
+ oasis_runtime_sdk::module::CallResult::Failed { module, code, .. } => {
+ Self::Failed { module, code }
+ }
+ oasis_runtime_sdk::module::CallResult::Aborted(err) => {
+ use oasis_runtime_sdk::error::Error;
+
+ Self::Failed {
+ module: err.module_name().to_string(),
+ code: err.code(),
+ }
+ }
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +
//! Storage-related types.
+use std::convert::TryFrom;
+
+/// Kind of the store to use.
+#[derive(Clone, Copy)]
+#[repr(u32)]
+pub enum StoreKind {
+ Public = 0,
+ Confidential = 1,
+}
+
+impl StoreKind {
+ /// Prefix that should be used for the underlying store.
+ pub fn prefix(&self) -> &'static [u8] {
+ match self {
+ StoreKind::Public => &[0x00],
+ StoreKind::Confidential => &[0x01],
+ }
+ }
+}
+
+impl TryFrom<u32> for StoreKind {
+ type Error = u32;
+
+ fn try_from(value: u32) -> Result<Self, Self::Error> {
+ match value {
+ 0 => Ok(StoreKind::Public),
+ 1 => Ok(StoreKind::Confidential),
+ _ => Err(value),
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +
//! Testing helpers.
+
+pub mod addresses {
+ pub mod alice {
+ use crate::address::Address;
+
+ pub fn address() -> Address {
+ Address::from_bech32("oasis1qrec770vrek0a9a5lcrv0zvt22504k68svq7kzve").unwrap()
+ }
+ }
+
+ pub mod bob {
+ use crate::address::Address;
+
+ pub fn address() -> Address {
+ Address::from_bech32("oasis1qrydpazemvuwtnp3efm7vmfvg3tde044qg6cxwzx").unwrap()
+ }
+ }
+
+ pub mod charlie {
+ use crate::address::Address;
+
+ pub fn address() -> Address {
+ Address::from_bech32("oasis1qr5kfjm8lx6mctjmwcx9225q5k3nxacqwqnjahkw").unwrap()
+ }
+ }
+
+ pub mod dave {
+ use crate::address::Address;
+
+ pub fn address() -> Address {
+ Address::from_bech32("oasis1qpufkctqruam5umugwn5jvxtrvvwl075rqrmxqmm").unwrap()
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +
//! Token types.
+use std::{convert::TryFrom, fmt};
+
+/// Name/type of the token.
+#[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, cbor::Encode)]
+#[cbor(transparent)]
+pub struct Denomination(Vec<u8>);
+
+impl Denomination {
+ /// Maximum length of a denomination.
+ pub const MAX_LENGTH: usize = 32;
+ /// Denomination in native token.
+ pub const NATIVE: Denomination = Denomination(Vec::new());
+
+ /// Whether the denomination represents the native token.
+ pub fn is_native(&self) -> bool {
+ self.0.is_empty()
+ }
+
+ /// Raw representation of a denomination.
+ pub fn into_vec(self) -> Vec<u8> {
+ self.0
+ }
+}
+
+impl AsRef<[u8]> for Denomination {
+ fn as_ref(&self) -> &[u8] {
+ &self.0
+ }
+}
+
+impl fmt::Display for Denomination {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ if self.is_native() {
+ write!(f, "<native>")?;
+ } else {
+ write!(f, "{}", String::from_utf8_lossy(&self.0))?;
+ }
+ Ok(())
+ }
+}
+
+impl std::str::FromStr for Denomination {
+ type Err = Error;
+
+ fn from_str(v: &str) -> Result<Self, Self::Err> {
+ Self::try_from(v.as_bytes())
+ }
+}
+
+impl TryFrom<&[u8]> for Denomination {
+ type Error = Error;
+
+ fn try_from(bytes: &[u8]) -> Result<Self, Self::Error> {
+ if bytes.len() > Self::MAX_LENGTH {
+ return Err(Error::NameTooLong {
+ length: bytes.len(),
+ });
+ }
+ Ok(Self(bytes.to_vec()))
+ }
+}
+
+impl cbor::Decode for Denomination {
+ fn try_default() -> Result<Self, cbor::DecodeError> {
+ Ok(Default::default())
+ }
+
+ fn try_from_cbor_value(value: cbor::Value) -> Result<Self, cbor::DecodeError> {
+ match value {
+ cbor::Value::ByteString(data) => {
+ Self::try_from(data.as_ref()).map_err(|_| cbor::DecodeError::UnexpectedType)
+ }
+ _ => Err(cbor::DecodeError::UnexpectedType),
+ }
+ }
+}
+
+#[cfg(feature = "oasis-runtime-sdk")]
+impl From<oasis_runtime_sdk::types::token::Denomination> for Denomination {
+ fn from(d: oasis_runtime_sdk::types::token::Denomination) -> Self {
+ Self(d.into_vec())
+ }
+}
+
+#[cfg(feature = "oasis-runtime-sdk")]
+impl From<Denomination> for oasis_runtime_sdk::types::token::Denomination {
+ fn from(d: Denomination) -> Self {
+ oasis_runtime_sdk::types::token::Denomination::try_from(d.0.as_ref()).unwrap()
+ }
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+ #[error(
+ "denomination name too long. received length {length} exceeded maximum of {}",
+ Denomination::MAX_LENGTH
+ )]
+ NameTooLong { length: usize },
+}
+
+/// Token amount of given denomination in base units.
+#[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, cbor::Encode, cbor::Decode)]
+pub struct BaseUnits(pub u128, pub Denomination);
+
+impl BaseUnits {
+ /// Creates a new token amount of the given denomination.
+ pub fn new(amount: u128, denomination: Denomination) -> Self {
+ BaseUnits(amount, denomination)
+ }
+
+ /// Token amount in base units.
+ pub fn amount(&self) -> u128 {
+ self.0
+ }
+
+ /// Denomination of the token amount.
+ pub fn denomination(&self) -> &Denomination {
+ &self.1
+ }
+}
+
+impl fmt::Display for BaseUnits {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ write!(f, "{} {}", self.0, self.1)?;
+ Ok(())
+ }
+}
+
+#[cfg(feature = "oasis-runtime-sdk")]
+impl From<oasis_runtime_sdk::types::token::BaseUnits> for BaseUnits {
+ fn from(a: oasis_runtime_sdk::types::token::BaseUnits) -> Self {
+ Self(a.0, a.1.into())
+ }
+}
+
+#[cfg(feature = "oasis-runtime-sdk")]
+impl From<&oasis_runtime_sdk::types::token::BaseUnits> for BaseUnits {
+ fn from(a: &oasis_runtime_sdk::types::token::BaseUnits) -> Self {
+ Self(a.0, a.1.clone().into())
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ #[test]
+ fn test_basic() {
+ let cases = vec![
+ // Native denomination.
+ (0, Denomination::NATIVE, "824040"),
+ (1, Denomination::NATIVE, "82410140"),
+ (1000, Denomination::NATIVE, "824203e840"),
+ // Custom denomination.
+ (0, "test".parse().unwrap(), "82404474657374"),
+ (1, "test".parse().unwrap(), "8241014474657374"),
+ (1000, "test".parse().unwrap(), "824203e84474657374"),
+ ];
+
+ for tc in cases {
+ let token = BaseUnits::new(tc.0, tc.1);
+ let enc = cbor::to_vec(token.clone());
+ assert_eq!(hex::encode(&enc), tc.2, "serialization should match");
+
+ let dec: BaseUnits = cbor::from_slice(&enc).expect("deserialization should succeed");
+ assert_eq!(dec, token, "serialization should round-trip");
+ }
+ }
+
+ #[test]
+ fn test_decoding_denomination() {
+ macro_rules! assert_rountrip_ok {
+ ($bytes:expr) => {
+ let enc = cbor::to_vec($bytes.to_vec());
+ let dec: Denomination = cbor::from_slice(&enc).unwrap();
+ assert_eq!(dec, Denomination::try_from($bytes).unwrap());
+ assert_eq!(dec.0, $bytes);
+ };
+ }
+
+ let bytes_fixture = vec![42u8; Denomination::MAX_LENGTH + 1];
+
+ assert_rountrip_ok!(&bytes_fixture[0..0]);
+ assert_rountrip_ok!(&bytes_fixture[0..1]);
+ assert_rountrip_ok!(&bytes_fixture[0..Denomination::MAX_LENGTH]);
+
+ // Too long denomination:
+ let dec_result: Result<Denomination, _> = cbor::from_slice(&cbor::to_vec(bytes_fixture));
+ assert!(dec_result.is_err());
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +
//! Runtime apps.
+use std::sync::Arc;
+
+use anyhow::{bail, Result};
+use async_trait::async_trait;
+
+use crate::{
+ common::sgx,
+ consensus::roothash,
+ dispatcher::{Initializer, PostInitState, PreInitState},
+ host::Host,
+};
+
+/// An Oasis runtime app.
+#[allow(unused_variables)]
+#[async_trait]
+pub trait App: Send + Sync {
+ /// Whether this is a ROFL app.
+ fn is_rofl(&self) -> bool {
+ true
+ }
+
+ /// Called on application initialization.
+ fn on_init(&mut self, host: Arc<dyn Host>) -> Result<()> {
+ // Default implementation does nothing.
+ Ok(())
+ }
+
+ /// Quote policy to use for verifying our own enclave identity.
+ async fn quote_policy(&self) -> Result<sgx::QuotePolicy> {
+ // Default implementation uses a sane policy.
+ Ok(sgx::QuotePolicy {
+ ias: Some(sgx::ias::QuotePolicy {
+ disabled: true, // Disable legacy EPID attestation.
+ ..Default::default()
+ }),
+ pcs: Some(sgx::pcs::QuotePolicy {
+ // Allow TDX since that is not part of the default policy.
+ tdx: Some(sgx::pcs::TdxQuotePolicy {
+ allowed_tdx_modules: vec![],
+ }),
+ ..Default::default()
+ }),
+ })
+ }
+
+ /// Called on new runtime block being received.
+ async fn on_runtime_block(&self, blk: &roothash::AnnotatedBlock) -> Result<()> {
+ // Default implementation does nothing.
+ Ok(())
+ }
+
+ /// Called on new runtime event being detected.
+ async fn on_runtime_event(
+ &self,
+ blk: &roothash::AnnotatedBlock,
+ tags: &[Vec<u8>],
+ ) -> Result<()> {
+ // Default implementation does nothing.
+ Ok(())
+ }
+
+ /// Called for runtime queries.
+ async fn query(&self, method: &str, args: Vec<u8>) -> Result<Vec<u8>> {
+ // Default implementation rejects all requests.
+ bail!("method not supported");
+ }
+}
+
+/// An application which doesn't do anything.
+pub struct NoopApp;
+
+#[async_trait]
+impl App for NoopApp {
+ fn is_rofl(&self) -> bool {
+ false
+ }
+}
+
+/// Create a new runtime initializer for an application.
+pub fn new(app: Box<dyn App>) -> Box<dyn Initializer> {
+ Box::new(|_state: PreInitState<'_>| -> PostInitState {
+ PostInitState {
+ app: Some(app),
+ ..Default::default()
+ }
+ })
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +
//! Functionality related to the enclave attestation flow.
+use std::sync::Arc;
+
+use anyhow::{bail, Result};
+use slog::{info, Logger};
+
+use crate::{
+ app::App,
+ common::{
+ crypto::signature::Signer, logger::get_logger, namespace::Namespace, panic::AbortOnPanic,
+ sgx::Quote, version::Version,
+ },
+ consensus::{
+ registry::{EndorsedCapabilityTEE, SGXAttestation, ATTESTATION_SIGNATURE_CONTEXT},
+ verifier::Verifier,
+ },
+ host::Host,
+ identity::Identity,
+ policy::PolicyVerifier,
+ types::Body,
+};
+
+/// Attestation flow handler.
+#[derive(Clone)]
+pub struct Handler {
+ identity: Arc<Identity>,
+ host: Arc<dyn Host>,
+ consensus_verifier: Arc<dyn Verifier>,
+ runtime_id: Namespace,
+ version: Version,
+ app: Arc<dyn App>,
+ logger: Logger,
+}
+
+impl Handler {
+ /// Create a new instance of the attestation flow handler.
+ pub fn new(
+ identity: Arc<Identity>,
+ host: Arc<dyn Host>,
+ consensus_verifier: Arc<dyn Verifier>,
+ runtime_id: Namespace,
+ version: Version,
+ app: Arc<dyn App>,
+ ) -> Self {
+ Self {
+ identity,
+ host,
+ consensus_verifier,
+ runtime_id,
+ version,
+ app,
+ logger: get_logger("runtime/attestation"),
+ }
+ }
+}
+
+impl Handler {
+ /// Handle an attestation flow request.
+ pub async fn handle(&self, request: Body) -> Result<Body> {
+ match request {
+ Body::RuntimeCapabilityTEERakInitRequest { target_info } => {
+ self.target_info_init(target_info)
+ }
+ Body::RuntimeCapabilityTEERakReportRequest {} => self.report_init(),
+ Body::RuntimeCapabilityTEERakAvrRequest { avr } => {
+ // TODO: Remove this once we want to break the runtime host protocol.
+ self.set_quote(Quote::Ias(avr)).await
+ }
+ Body::RuntimeCapabilityTEERakQuoteRequest { quote } => self.set_quote(quote).await,
+ Body::RuntimeCapabilityTEEUpdateEndorsementRequest { ect } => {
+ self.update_endorsement(ect).await
+ }
+
+ _ => bail!("unsupported attestation request"),
+ }
+ }
+
+ fn target_info_init(&self, target_info: Vec<u8>) -> Result<Body> {
+ // Make sure to abort the process on panics during attestation process.
+ let _guard = AbortOnPanic;
+
+ info!(self.logger, "Initializing the runtime target info");
+ self.identity.init_target_info(target_info)?;
+ Ok(Body::RuntimeCapabilityTEERakInitResponse {})
+ }
+
+ fn report_init(&self) -> Result<Body> {
+ // Make sure to abort the process on panics during attestation process.
+ let _guard = AbortOnPanic;
+
+ info!(self.logger, "Initializing the runtime key report");
+ let (rak_pub, rek_pub, report, nonce) = self.identity.init_report()?;
+
+ Ok(Body::RuntimeCapabilityTEERakReportResponse {
+ rak_pub,
+ rek_pub,
+ report,
+ nonce,
+ })
+ }
+
+ async fn set_quote_policy(&self) -> Result<()> {
+ info!(self.logger, "Configuring quote policy");
+
+ // Use the correct quote policy for verifying our own identity based on what kind of
+ // application this is. For ROFL, ask the application, for RONL, query consensus.
+ let policy = if self.app.is_rofl() {
+ // ROFL, ask the app for policy.
+ self.app.quote_policy().await?
+ } else {
+ // RONL.
+ // TODO: Make async.
+ let consensus_verifier = self.consensus_verifier.clone();
+ let version = self.version;
+ let runtime_id = self.runtime_id;
+ tokio::task::block_in_place(move || {
+ // Obtain current quote policy from (verified) consensus state.
+ PolicyVerifier::new(consensus_verifier).quote_policy(&runtime_id, Some(version))
+ })?
+ };
+
+ self.identity.set_quote_policy(policy)?;
+
+ Ok(())
+ }
+
+ async fn set_quote(&self, quote: Quote) -> Result<Body> {
+ // Make sure to abort the process on panics during attestation process.
+ let _guard = AbortOnPanic;
+
+ // Ensure a quote policy is configured.
+ self.set_quote_policy().await?;
+
+ info!(
+ self.logger,
+ "Configuring quote for the runtime attestation key binding"
+ );
+
+ // Configure the quote and policy on the identity.
+ let node_id = self.host.identity().await?;
+ let verified_quote = self.identity.set_quote(node_id, quote)?;
+
+ // Sign the report data, latest verified consensus height, REK and host node ID.
+ let consensus_state = self.consensus_verifier.latest_state().await?;
+ let height = consensus_state.height();
+ let rek = self.identity.public_rek();
+ let h = SGXAttestation::hash(&verified_quote.report_data, &node_id, height, &rek);
+ let signature = self.identity.sign(ATTESTATION_SIGNATURE_CONTEXT, &h)?;
+
+ Ok(Body::RuntimeCapabilityTEERakQuoteResponse { height, signature })
+ }
+
+ async fn update_endorsement(&self, ect: EndorsedCapabilityTEE) -> Result<Body> {
+ info!(self.logger, "Updating endorsed TEE capability");
+
+ // Update the endorsed TEE capability. This also performs the necessary verification.
+ self.identity.set_endorsed_capability_tee(ect)?;
+
+ Ok(Body::RuntimeCapabilityTEEUpdateEndorsementResponse {})
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +
//! In-memory cache of trees.
+use std::{
+ cell::RefCell,
+ num::NonZeroUsize,
+ rc::Rc,
+ sync::{Arc, Mutex, MutexGuard},
+};
+
+use crate::{
+ common::crypto::hash::Hash,
+ protocol::Protocol,
+ storage::mkvs::{sync::HostReadSyncer, Root, Tree},
+ types::HostStorageEndpoint,
+};
+
+thread_local! {
+ static QUERY_CACHE: RefCell<lru::LruCache<u64, Rc<RefCell<Cache>>>> = RefCell::new(lru::LruCache::new(NonZeroUsize::new(10).unwrap()));
+}
+
+/// A set of storage tree caches, one for each storage operation:
+///
+/// * **Execution** and **checking** of transactions each have their own cache guarded by a mutex
+/// since the usual use case is that only one execution/check batch is running at any given time.
+///
+/// * **Queries** have a thread-local cache as there can be multiple queries running at any given
+/// time and having a global lock would kill concurrency.
+#[derive(Clone)]
+pub struct CacheSet {
+ protocol: Arc<Protocol>,
+ execute: Arc<Mutex<Cache>>,
+ check: Arc<Mutex<Cache>>,
+}
+
+impl CacheSet {
+ /// Create a new empty cache set.
+ pub fn new(protocol: Arc<Protocol>) -> Self {
+ Self {
+ execute: Arc::new(Mutex::new(Cache::new(&protocol))),
+ check: Arc::new(Mutex::new(Cache::new(&protocol))),
+ protocol,
+ }
+ }
+
+ /// Cache used for executing transactions.
+ pub fn execute(&self, root: Root) -> MutexGuard<'_, Cache> {
+ let mut cache = self.execute.lock().unwrap();
+ cache.maybe_replace(&self.protocol, root);
+ cache
+ }
+
+ /// Cache used for checking transactions.
+ pub fn check(&self, root: Root) -> MutexGuard<'_, Cache> {
+ let mut cache = self.check.lock().unwrap();
+ cache.maybe_replace(&self.protocol, root);
+ cache
+ }
+
+ /// Cache used for queries.
+ pub fn query(&self, root: Root) -> Rc<RefCell<Cache>> {
+ let cache = QUERY_CACHE.with(|caches| {
+ let mut caches = caches.borrow_mut();
+ if let Some(cache) = caches.get(&root.version) {
+ return cache.clone();
+ }
+
+ let cache = Rc::new(RefCell::new(Cache::new(&self.protocol)));
+ caches.put(root.version, cache.clone());
+ cache
+ });
+ cache.borrow_mut().maybe_replace(&self.protocol, root);
+ cache
+ }
+}
+
+/// Cached storage tree with an associated root.
+pub struct Cache {
+ root: Root,
+ tree: Tree,
+}
+
+impl Cache {
+ fn new(protocol: &Arc<Protocol>) -> Self {
+ Self {
+ root: Default::default(),
+ tree: Self::build(protocol, Default::default()),
+ }
+ }
+
+ fn build(protocol: &Arc<Protocol>, root: Root) -> Tree {
+ let config = protocol.get_config();
+ let read_syncer = HostReadSyncer::new(protocol.clone(), HostStorageEndpoint::Runtime);
+ Tree::builder()
+ .with_capacity(
+ config.storage.cache_node_capacity,
+ config.storage.cache_value_capacity,
+ )
+ .with_root(root)
+ .build(Box::new(read_syncer))
+ }
+
+ fn maybe_replace(&mut self, protocol: &Arc<Protocol>, root: Root) {
+ if self.root == root {
+ return;
+ }
+
+ self.tree = Self::build(protocol, root);
+ self.root = root;
+ }
+
+ /// Reference to the cached tree.
+ pub fn tree(&self) -> &Tree {
+ &self.tree
+ }
+
+ /// Mutable reference to the cached tree.
+ pub fn tree_mut(&mut self) -> &mut Tree {
+ &mut self.tree
+ }
+
+ /// Commits a specific version and root as being stored by the tree.
+ pub fn commit(&mut self, version: u64, hash: Hash) {
+ self.root.version = version;
+ self.root.hash = hash;
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +
//! Byte array type helpers.
+
+/// Define a byte array-like type.
+///
+/// # Examples
+///
+/// ```rust,ignore
+/// impl_bytes!(MyType, 32, "A 32-byte type.");
+/// ```
+#[macro_export]
+macro_rules! impl_bytes {
+ ($name:ident, $size:expr, $doc:expr) => {
+ #[doc=$doc]
+ #[derive(Clone, Copy, zeroize::Zeroize)]
+ pub struct $name(pub [u8; $size]);
+
+ impl $name {
+ /// Size of this object in bytes.
+ pub const fn len() -> usize {
+ $size
+ }
+ }
+
+ impl AsRef<[u8]> for $name {
+ fn as_ref(&self) -> &[u8] {
+ &self.0
+ }
+ }
+
+ impl Eq for $name {}
+
+ impl PartialOrd for $name {
+ fn partial_cmp(&self, other: &Self) -> Option<::core::cmp::Ordering> {
+ Some(self.cmp(other))
+ }
+ }
+
+ impl PartialEq for $name {
+ fn eq(&self, other: &Self) -> bool {
+ &self.0[..] == &other.0[..]
+ }
+ }
+
+ impl Ord for $name {
+ fn cmp(&self, other: &Self) -> ::core::cmp::Ordering {
+ self.0[..].cmp(&other.0[..])
+ }
+ }
+
+ impl ::core::hash::Hash for $name {
+ fn hash<H>(&self, state: &mut H)
+ where
+ H: ::core::hash::Hasher,
+ {
+ state.write(&self.0);
+ }
+ }
+
+ impl Default for $name {
+ fn default() -> Self {
+ $name([0; $size])
+ }
+ }
+
+ impl From<$name> for [u8; $size] {
+ fn from(b: $name) -> Self {
+ b.0
+ }
+ }
+
+ impl From<&[u8]> for $name {
+ fn from(b: &[u8]) -> $name {
+ let mut data = [0; $size];
+ data.copy_from_slice(b);
+ $name(data)
+ }
+ }
+
+ impl From<&'static str> for $name {
+ fn from(s: &'static str) -> $name {
+ let s = s.strip_prefix("0x").unwrap_or(s);
+
+ if s.len() % 2 == 1 {
+ ("0".to_owned() + s).parse().unwrap()
+ } else {
+ s.parse().unwrap()
+ }
+ }
+ }
+
+ impl From<Vec<u8>> for $name {
+ fn from(v: Vec<u8>) -> $name {
+ Self::from(&v[..])
+ }
+ }
+
+ impl ::std::str::FromStr for $name {
+ type Err = ::rustc_hex::FromHexError;
+
+ fn from_str(s: &str) -> Result<$name, ::rustc_hex::FromHexError> {
+ use ::rustc_hex::FromHex;
+
+ let a: Vec<u8> = s.from_hex()?;
+ if a.len() != $size {
+ return Err(::rustc_hex::FromHexError::InvalidHexLength);
+ }
+
+ let mut ret = [0; $size];
+ ret.copy_from_slice(&a);
+ Ok($name(ret))
+ }
+ }
+
+ // Formatting.
+
+ impl ::core::fmt::LowerHex for $name {
+ fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
+ for i in &self.0[..] {
+ write!(f, "{:02x}", i)?;
+ }
+ Ok(())
+ }
+ }
+
+ impl ::core::fmt::Debug for $name {
+ fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
+ ::core::fmt::LowerHex::fmt(self, f)
+ }
+ }
+
+ impl ::core::fmt::Display for $name {
+ fn fmt(&self, f: &mut ::core::fmt::Formatter) -> ::core::fmt::Result {
+ for i in &self.0[0..2] {
+ write!(f, "{:02x}", i)?;
+ }
+ write!(f, "…")?;
+ for i in &self.0[$size - 2..$size] {
+ write!(f, "{:02x}", i)?;
+ }
+ Ok(())
+ }
+ }
+
+ // Serialization.
+
+ impl $crate::cbor::Encode for $name {
+ fn into_cbor_value(self) -> $crate::cbor::Value {
+ $crate::cbor::Value::ByteString(self.0.into())
+ }
+ }
+
+ // Deserialization.
+
+ impl $crate::cbor::Decode for $name {
+ fn try_default() -> Result<Self, $crate::cbor::DecodeError> {
+ Ok(Default::default())
+ }
+
+ fn try_from_cbor_value(
+ value: $crate::cbor::Value,
+ ) -> Result<Self, $crate::cbor::DecodeError> {
+ use ::std::convert::TryInto;
+
+ match value {
+ $crate::cbor::Value::ByteString(data) => Ok(Self(
+ data.try_into()
+ .map_err(|_| $crate::cbor::DecodeError::UnexpectedType)?,
+ )),
+ _ => Err($crate::cbor::DecodeError::UnexpectedType),
+ }
+ }
+ }
+ };
+}
+
+#[cfg(test)]
+mod tests {
+ // Use hash of an empty string as a test key.
+ const TEST_KEY_BYTES: [u8; 32] = [
+ 0xc6, 0x72, 0xb8, 0xd1, 0xef, 0x56, 0xed, 0x28, 0xab, 0x87, 0xc3, 0x62, 0x2c, 0x51, 0x14,
+ 0x06, 0x9b, 0xdd, 0x3a, 0xd7, 0xb8, 0xf9, 0x73, 0x74, 0x98, 0xd0, 0xc0, 0x1e, 0xce, 0xf0,
+ 0x96, 0x7a,
+ ];
+
+ impl_bytes!(TestKey, 32, "test key");
+
+ #[test]
+ fn test_length() {
+ assert_eq!(TestKey::len(), 32);
+ }
+
+ #[test]
+ fn test_cbor() {
+ // Serialize.
+ let test_key = TestKey(TEST_KEY_BYTES);
+ let test_key_vec = cbor::to_vec(test_key);
+
+ // CBOR prepends "X " to the binary value.
+ let mut expected_test_key_vec = vec![88, 32];
+ expected_test_key_vec.extend_from_slice(&TEST_KEY_BYTES);
+ assert_eq!(test_key_vec, expected_test_key_vec);
+
+ // Deserialize.
+ let new_test_key: TestKey = cbor::from_slice(&test_key_vec).unwrap();
+ assert_eq!(new_test_key, test_key);
+ }
+
+ #[test]
+ fn test_cbor_null() {
+ let test_key: TestKey = cbor::from_slice(&[0xF6]).unwrap();
+ assert_eq!(
+ test_key,
+ "0000000000000000000000000000000000000000000000000000000000000000".into()
+ );
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +
//! Hash type.
+use std::convert::TryInto;
+
+use sha2::{Digest, Sha512_256};
+
+use crate::common::key_format::KeyFormatAtom;
+
+impl_bytes!(Hash, 32, "A 32-byte SHA-512/256 hash.");
+
+impl Hash {
+ /// Compute a digest of the passed slice of bytes.
+ pub fn digest_bytes(data: &[u8]) -> Hash {
+ let mut result = [0u8; 32];
+ result[..].copy_from_slice(Sha512_256::digest(data).as_ref());
+
+ Hash(result)
+ }
+
+ /// Compute a digest of the passed slices of bytes.
+ pub fn digest_bytes_list(data: &[&[u8]]) -> Hash {
+ let mut ctx = Sha512_256::new();
+ for datum in data {
+ ctx.update(datum);
+ }
+
+ let mut result = [0u8; 32];
+ result[..].copy_from_slice(ctx.finalize().as_ref());
+
+ Hash(result)
+ }
+
+ /// Returns true if the hash is of an empty string.
+ pub fn is_empty(&self) -> bool {
+ self == &Hash::empty_hash()
+ }
+
+ /// Hash of an empty string.
+ pub fn empty_hash() -> Hash {
+ // This is SHA-512/256 of an empty string.
+ Hash([
+ 0xc6, 0x72, 0xb8, 0xd1, 0xef, 0x56, 0xed, 0x28, 0xab, 0x87, 0xc3, 0x62, 0x2c, 0x51,
+ 0x14, 0x06, 0x9b, 0xdd, 0x3a, 0xd7, 0xb8, 0xf9, 0x73, 0x74, 0x98, 0xd0, 0xc0, 0x1e,
+ 0xce, 0xf0, 0x96, 0x7a,
+ ])
+ }
+
+ /// Hash truncated to the given number of bytes.
+ pub fn truncated(&self, n: usize) -> &[u8] {
+ &self.0[..n]
+ }
+}
+
+impl KeyFormatAtom for Hash {
+ fn size() -> usize {
+ Hash::len()
+ }
+
+ fn encode_atom(self) -> Vec<u8> {
+ self.as_ref().to_vec()
+ }
+
+ fn decode_atom(data: &[u8]) -> Self
+ where
+ Self: Sized,
+ {
+ Hash(data.try_into().expect("hash: invalid decode atom data"))
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +
//! Deoxys-II-256-128 MRAE primitives implementation.
+use anyhow::Result;
+use hmac::{Hmac, Mac};
+use rand::rngs::OsRng;
+use sha2::Sha512_256;
+use x25519_dalek::{PublicKey, StaticSecret};
+
+pub use deoxysii::{DeoxysII, KEY_SIZE, NONCE_SIZE, TAG_SIZE};
+
+type Kdf = Hmac<Sha512_256>;
+
+/// An abstract Deoxys-II-256-128 box opener.
+pub trait Opener: Send + Sync {
+ /// Unboxes ("opens") the provided additional data and ciphertext.
+ fn box_open(
+ &self,
+ nonce: &[u8; NONCE_SIZE],
+ ciphertext: Vec<u8>,
+ additional_data: Vec<u8>,
+ peers_public_key: &PublicKey,
+ ) -> Result<Vec<u8>>;
+}
+
+/// Derives a MRAE AEAD symmetric key suitable for use with the asymmetric
+/// box primitives from the provided X25519 public and private keys.
+fn derive_symmetric_key(public: &PublicKey, private: &StaticSecret) -> [u8; KEY_SIZE] {
+ let pmk = private.diffie_hellman(public);
+
+ let mut kdf = Kdf::new_from_slice(b"MRAE_Box_Deoxys-II-256-128").expect("Hmac::new_from_slice");
+ kdf.update(pmk.as_bytes());
+ drop(pmk);
+
+ let mut derived_key = [0u8; KEY_SIZE];
+ let digest = kdf.finalize();
+ derived_key.copy_from_slice(&digest.into_bytes()[..KEY_SIZE]);
+
+ derived_key
+}
+
+/// Generates a public/private key pair suitable for use with
+/// `derive_symmetric_key`, `box_seal`, and `box_open`.
+pub fn generate_key_pair() -> (PublicKey, StaticSecret) {
+ let sk = StaticSecret::random_from_rng(OsRng);
+ let pk = PublicKey::from(&sk);
+
+ (pk, sk)
+}
+
+/// Boxes ("seals") the provided additional data and plaintext via
+/// Deoxys-II-256-128 using a symmetric key derived from the provided
+/// X25519 public and private keys.
+/// The nonce should be `NONCE_SIZE` bytes long and unique for all time
+/// for a given public and private key tuple.
+pub fn box_seal(
+ nonce: &[u8; NONCE_SIZE],
+ plaintext: Vec<u8>,
+ additional_data: Vec<u8>,
+ peers_public_key: &PublicKey,
+ private_key: &StaticSecret,
+) -> Result<Vec<u8>> {
+ let key = derive_symmetric_key(peers_public_key, private_key);
+
+ let d2 = DeoxysII::new(&key);
+
+ Ok(d2.seal(nonce, plaintext, additional_data))
+}
+
+/// Unboxes ("opens") the provided additional data and ciphertext via
+/// Deoxys-II-256-128 using a symmetric key derived from the provided
+/// X25519 public and private keys.
+/// The nonce should be `NONCE_SIZE` bytes long and both it and the additional
+/// data must match the value passed to `box_seal`.
+pub fn box_open(
+ nonce: &[u8; NONCE_SIZE],
+ ciphertext: Vec<u8>,
+ additional_data: Vec<u8>,
+ peers_public_key: &PublicKey,
+ private_key: &StaticSecret,
+) -> Result<Vec<u8>> {
+ let key = derive_symmetric_key(peers_public_key, private_key);
+
+ let d2 = DeoxysII::new(&key);
+
+ d2.open(nonce, ciphertext, additional_data)
+ .map_err(|err| err.into())
+}
+
+#[cfg(test)]
+mod tests {
+ extern crate test;
+
+ use self::test::{black_box, Bencher};
+ use super::*;
+ use rand::RngCore;
+
+ #[test]
+ fn test_mrae_asymmetric() {
+ let (a_pub, a_priv) = generate_key_pair(); // Alice
+ let (b_pub, b_priv) = generate_key_pair(); // Bob
+
+ // None of the generated keys should be the same.
+ assert_ne!(a_pub.to_bytes(), b_pub.to_bytes());
+ assert_ne!(a_priv.to_bytes(), b_priv.to_bytes());
+ assert_ne!(a_pub.to_bytes(), a_priv.to_bytes());
+ assert_ne!(b_pub.to_bytes(), b_priv.to_bytes());
+
+ // Should successfully seal the text in a box.
+ let nonce = [1u8; NONCE_SIZE];
+ let text = String::from("This is a test!").as_bytes().to_vec();
+ let aad = vec![42u8; 10];
+
+ let sealed = box_seal(&nonce, text.clone(), aad.clone(), &b_pub, &a_priv);
+ assert!(sealed.is_ok());
+
+ // Should successfully open the sealed box.
+ let opened = box_open(&nonce, sealed.unwrap(), aad, &a_pub, &b_priv);
+ assert!(opened.is_ok());
+
+ // The deciphered text should match the original.
+ let deciphered = opened.unwrap();
+ assert_eq!(deciphered, text);
+ }
+
+ #[bench]
+ fn bench_mrae_box_seal_4096(b: &mut Bencher) {
+ let mut rng = OsRng {};
+
+ // Set up the keys.
+ let (_a_pub, a_priv) = generate_key_pair(); // Alice
+ let (b_pub, _b_priv) = generate_key_pair(); // Bob
+
+ // Set up the payload.
+ let mut nonce = [0u8; NONCE_SIZE];
+ rng.fill_bytes(&mut nonce);
+ let mut text = [0u8; 4096];
+ rng.fill_bytes(&mut text);
+ let mut aad = [0u8; 64];
+ rng.fill_bytes(&mut aad);
+
+ // Benchmark box sealing.
+ b.iter(|| {
+ let _sealed = black_box(box_seal(
+ &nonce,
+ text.to_vec(),
+ aad.to_vec(),
+ &b_pub,
+ &a_priv,
+ ));
+ });
+ }
+
+ #[bench]
+ fn bench_mrae_box_open_4096(b: &mut Bencher) {
+ let mut rng = OsRng {};
+
+ // Set up the keys.
+ let (a_pub, a_priv) = generate_key_pair(); // Alice
+ let (b_pub, b_priv) = generate_key_pair(); // Bob
+
+ // Set up the payload.
+ let mut nonce = [0u8; NONCE_SIZE];
+ rng.fill_bytes(&mut nonce);
+ let mut text = [0u8; 4096];
+ rng.fill_bytes(&mut text);
+ let mut aad = [0u8; 64];
+ rng.fill_bytes(&mut aad);
+
+ // Seal the payload.
+ let sealed = box_seal(&nonce, text.to_vec(), aad.to_vec(), &b_pub, &a_priv);
+ let ciphertext = sealed.unwrap();
+
+ // Benchmark box opening.
+ b.iter(|| {
+ let _opened = black_box(box_open(
+ &nonce,
+ ciphertext.clone(),
+ aad.to_vec(),
+ &a_pub,
+ &b_priv,
+ ));
+ });
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +
//! Nonce utility used to ensure nonces are safely incremented.
+use std::ops::Deref;
+
+use anyhow::{anyhow, Result};
+use byteorder::{BigEndian, ReadBytesExt, WriteBytesExt};
+use rand::{rngs::OsRng, Rng};
+
+/// Size of the nonce in bytes.
+pub use super::deoxysii::NONCE_SIZE;
+/// Size of tag portion of the nonce in bytes. These bytes will never update.
+pub const TAG_SIZE: usize = 11;
+
+/// 120 bit nonce with a 88 bit tag and 32 bit counter. If the counter exceeds
+/// 32 bits, then the nonce is no longer valid and must be refreshed with a new
+/// random nonce. It is expected that all 128 bits are given randomly. However,
+/// the last 32 counting bits may wrap around to ensure 2^32 counts may be used
+/// per nonce.
+#[derive(Debug, Clone)]
+pub struct Nonce {
+ /// The current value of the nonce, from which we may increment.
+ current_value: [u8; NONCE_SIZE],
+ /// The initial value of the nonce, used to ensure we never allow the nonce
+ /// to be the same again (after incrementing 2^32 times).
+ start_value: [u8; NONCE_SIZE],
+}
+
+impl Nonce {
+ /// Create a new nonce.
+ pub fn new(start_value: [u8; NONCE_SIZE]) -> Self {
+ Nonce {
+ current_value: start_value,
+ start_value,
+ }
+ }
+
+ /// Generate a random nonce.
+ pub fn generate() -> Self {
+ let mut rng = OsRng {};
+ let mut start_value = [0u8; NONCE_SIZE];
+ rng.fill(&mut start_value);
+
+ Self::new(start_value)
+ }
+
+ /// Adds one to the nonce, affecting only the last 32 counting bits.
+ /// Returns an error iff we've exceeded our nonce's counter capacity, i.e.,
+ /// we've incremented 2^32 times. In this case, the Nonce remains unchanged,
+ /// and all subsequent calls to this method will return an Error.
+ pub fn increment(&mut self) -> Result<()> {
+ // Extract the current counter out of the nonce.
+ let mut counter_array = &self.current_value[TAG_SIZE..];
+ // Increment the count and wrap to 0 if necessary.
+ let new_counter: u32 = {
+ let mut counter = counter_array.read_u32::<BigEndian>().unwrap();
+ // If about to overflow wrap around to 0.
+ #[allow(clippy::nonminimal_bool)]
+ if counter == !0u32 {
+ counter = 0;
+ } else {
+ counter += 1;
+ }
+ counter
+ };
+ // Merge this new counter back into the nonce.
+ let new_value: [u8; NONCE_SIZE] = {
+ let mut new_value_vec = self.current_value[..TAG_SIZE].to_vec();
+ new_value_vec.write_u32::<BigEndian>(new_counter).unwrap();
+
+ assert!(new_value_vec.len() == NONCE_SIZE);
+
+ let mut new_value = [0; NONCE_SIZE];
+ new_value.copy_from_slice(&new_value_vec);
+ new_value
+ };
+ // If we've exhausted all 2^32 counters, then error.
+ if new_value == self.start_value {
+ return Err(anyhow!(
+ "This nonce has been exhausted, and a new one must be created",
+ ));
+ }
+ // Update is valid, so mutate.
+ self.current_value = new_value;
+ // Success.
+ Ok(())
+ }
+}
+
+impl Deref for Nonce {
+ type Target = [u8; NONCE_SIZE];
+
+ fn deref(&self) -> &Self::Target {
+ &self.current_value
+ }
+}
+
+#[cfg(test)]
+mod tests {
+
+ use super::*;
+
+ #[test]
+ fn test_increment_zero() {
+ let inner = [0; 15];
+ let mut nonce = Nonce::new(inner);
+ nonce.increment().unwrap();
+ let mut expected = [0; 15];
+ expected[14] = 1;
+ assert_eq!(nonce.to_vec(), expected.to_vec());
+ }
+
+ #[test]
+ fn test_increment_one() {
+ let mut start_value = [0; 15];
+ start_value[14] = 1;
+ let mut nonce = Nonce::new(start_value);
+ nonce.increment().unwrap();
+ let mut expected = [0; 15];
+ expected[14] = 2;
+
+ assert_eq!(nonce.to_vec(), expected.to_vec());
+ }
+
+ #[test]
+ fn test_increment_carry() {
+ let start_value = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 255];
+ let mut nonce = Nonce::new(start_value);
+ nonce.increment().unwrap();
+ let expected = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0];
+ assert_eq!(nonce.to_vec(), expected.to_vec());
+ }
+
+ #[test]
+ fn test_increment_overflow() {
+ let start_value = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 255, 255];
+ let mut nonce = Nonce::new(start_value);
+ nonce.increment().unwrap();
+ let expected = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0];
+ assert_eq!(nonce.to_vec(), expected.to_vec());
+ }
+
+ #[test]
+ fn test_increment_exhaustion() {
+ let start_value = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 255, 255];
+ let current_value = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 255, 254];
+ let mut nonce = Nonce {
+ start_value,
+ current_value,
+ };
+ assert_eq!(nonce.increment().is_err(), true);
+ // Try again.
+ assert_eq!(nonce.increment().is_err(), true);
+ }
+
+ #[test]
+ fn test_double_increment_exhaustion() {
+ let start_value = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 255, 255];
+ let current_value = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 255, 253];
+ let mut nonce = Nonce {
+ start_value,
+ current_value,
+ };
+ let first_expected = [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 255, 254];
+ nonce.increment().unwrap();
+ assert_eq!(nonce.to_vec(), first_expected.to_vec());
+ assert_eq!(nonce.increment().is_err(), true);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +
//! Signature types.
+use std::{cmp::Ordering, convert::TryInto, io::Cursor};
+
+use anyhow::Result;
+use byteorder::{LittleEndian, ReadBytesExt};
+use curve25519_dalek::{
+ edwards::{CompressedEdwardsY, EdwardsPoint},
+ scalar::Scalar,
+};
+use ed25519_dalek::{Digest as _, Sha512, Signer as _};
+use rand::rngs::OsRng;
+use thiserror::Error;
+use zeroize::Zeroize;
+
+use crate::common::namespace::Namespace;
+
+use super::hash::Hash;
+
+/// The chain separator used to add additional domain separation based on the chain context.
+const CHAIN_SIGNATURE_CONTEXT_SEPARATOR: &[u8] = b" for chain ";
+/// The runtime separator used to add additional domain separation based on the runtime ID.
+const RUNTIME_SIGNATURE_CONTEXT_SEPARATOR: &[u8] = b" for runtime ";
+
+impl_bytes!(
+ PublicKey,
+ ed25519_dalek::PUBLIC_KEY_LENGTH,
+ "An Ed25519 public key."
+);
+
+/// Signature error.
+#[derive(Error, Debug)]
+enum SignatureError {
+ #[error("point decompression failed")]
+ PointDecompression,
+ #[error("small order A")]
+ SmallOrderA,
+ #[error("small order R")]
+ SmallOrderR,
+ #[error("signature malleability check failed")]
+ Malleability,
+ #[error("invalid signature")]
+ InvalidSignature,
+}
+
+static CURVE_ORDER: &[u64] = &[
+ 0x1000000000000000,
+ 0,
+ 0x14def9dea2f79cd6,
+ 0x5812631a5cf5d3ed,
+];
+
+/// An Ed25519 private key.
+pub struct PrivateKey(pub ed25519_dalek::SigningKey);
+
+impl PrivateKey {
+ /// Generates a new private key pair.
+ pub fn generate() -> Self {
+ PrivateKey(ed25519_dalek::SigningKey::generate(&mut OsRng))
+ }
+
+ /// Convert this private key into bytes.
+ pub fn to_bytes(&self) -> Vec<u8> {
+ let mut bytes = self.0.to_bytes();
+ let bvec = bytes.to_vec();
+ bytes.zeroize();
+ bvec
+ }
+
+ /// Construct a private key from bytes returned by `to_bytes`.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic in case the passed bytes do not have the correct length.
+ pub fn from_bytes(bytes: Vec<u8>) -> PrivateKey {
+ let mut sk = bytes.try_into().unwrap();
+ let secret = ed25519_dalek::SigningKey::from_bytes(&sk);
+ sk.zeroize();
+
+ PrivateKey(secret)
+ }
+
+ /// Generate a new private key from a test key seed.
+ pub fn from_test_seed(seed: String) -> Self {
+ let mut seed = Hash::digest_bytes(seed.as_bytes());
+ let sk = Self::from_bytes(seed.as_ref().to_vec());
+ seed.zeroize();
+
+ sk
+ }
+
+ /// Returns the public key.
+ pub fn public_key(&self) -> PublicKey {
+ PublicKey(self.0.verifying_key().to_bytes())
+ }
+}
+
+impl Signer for PrivateKey {
+ fn public(&self) -> PublicKey {
+ self.public_key()
+ }
+
+ fn sign(&self, context: &[u8], message: &[u8]) -> Result<Signature> {
+ // TODO/#2103: Replace this with Ed25519ctx.
+ let digest = Hash::digest_bytes_list(&[context, message]);
+
+ Ok(Signature(self.0.sign(digest.as_ref()).to_bytes()))
+ }
+}
+
+impl_bytes!(Signature, 64, "An Ed25519 signature.");
+
+impl Signature {
+ /// Verify signature.
+ pub fn verify(&self, pk: &PublicKey, context: &[u8], message: &[u8]) -> Result<()> {
+ // Apply the Oasis core specific domain separation.
+ //
+ // Note: This should be Ed25519ctx based but "muh Ledger".
+ let digest = Hash::digest_bytes_list(&[context, message]);
+
+ self.verify_raw(pk, digest.as_ref())
+ }
+
+ /// Verify signature without applying domain separation.
+ #[allow(non_snake_case)] // Variable names matching RFC 8032 is more readable.
+ pub fn verify_raw(&self, pk: &PublicKey, msg: &[u8]) -> Result<()> {
+ // We have a very specific idea of what a valid Ed25519 signature
+ // is, that is different from what ed25519-dalek defines, so this
+ // needs to be done by hand.
+
+ // Decompress A (PublicKey)
+ //
+ // TODO/perf:
+ // * PublicKey could just be an EdwardsPoint.
+ // * Could cache the results of is_small_order() in PublicKey.
+ let A = CompressedEdwardsY::from_slice(pk.as_ref())
+ .map_err(|_| SignatureError::PointDecompression)?;
+ let A = A.decompress().ok_or(SignatureError::PointDecompression)?;
+ if A.is_small_order() {
+ return Err(SignatureError::SmallOrderA.into());
+ }
+
+ // Decompress R (signature point), S (signature scalar).
+ //
+ // Note:
+ // * Reject S > L, small order A/R
+ // * Accept non-canonical A/R
+ let sig_slice = self.as_ref();
+ let R_bits = &sig_slice[..32];
+ let S_bits = &sig_slice[32..];
+
+ let R = CompressedEdwardsY::from_slice(R_bits)
+ .map_err(|_| SignatureError::PointDecompression)?;
+ let R = R.decompress().ok_or(SignatureError::PointDecompression)?;
+ if R.is_small_order() {
+ return Err(SignatureError::SmallOrderR.into());
+ }
+
+ if !sc_minimal(S_bits) {
+ return Err(SignatureError::Malleability.into());
+ }
+ let mut S: [u8; 32] = [0u8; 32];
+ S.copy_from_slice(S_bits);
+ #[allow(deprecated)] // S is only used for vartime_double_scalar_mul_basepoint.
+ let S = Scalar::from_bits(S);
+
+ // k = H(R,A,m)
+ let mut k: Sha512 = Sha512::new();
+ k.update(R_bits);
+ k.update(pk.as_ref());
+ k.update(msg);
+ let k = Scalar::from_hash(k);
+
+ // Check the cofactored group equation ([8][S]B = [8]R + [8][k]A').
+ let neg_A = -A;
+ let should_be_small_order =
+ EdwardsPoint::vartime_double_scalar_mul_basepoint(&k, &neg_A, &S) - R;
+ match should_be_small_order.is_small_order() {
+ true => Ok(()),
+ false => Err(SignatureError::InvalidSignature.into()),
+ }
+ }
+}
+
+/// Blob signed with one public key.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct Signed {
+ /// Signed blob.
+ #[cbor(rename = "untrusted_raw_value")]
+ pub blob: Vec<u8>,
+ /// Signature over the blob.
+ pub signature: SignatureBundle,
+}
+
+/// Blob signed by multiple public keys.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct MultiSigned {
+ /// Signed blob.
+ #[cbor(rename = "untrusted_raw_value")]
+ pub blob: Vec<u8>,
+ /// Signatures over the blob.
+ pub signatures: Vec<SignatureBundle>,
+}
+
+/// A signature bundled with a public key.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct SignatureBundle {
+ /// Public key that produced the signature.
+ pub public_key: PublicKey,
+ /// Actual signature.
+ pub signature: Signature,
+}
+
+impl SignatureBundle {
+ /// Verify returns true iff the signature is valid over the given context
+ /// and message.
+ pub fn verify(&self, context: &[u8], message: &[u8]) -> bool {
+ self.signature
+ .verify(&self.public_key, context, message)
+ .is_ok()
+ }
+}
+
+/// A abstract signer.
+pub trait Signer: Send + Sync {
+ /// Returns the public key corresponding to the signer.
+ fn public(&self) -> PublicKey;
+
+ /// Generates a signature over the context and message.
+ fn sign(&self, context: &[u8], message: &[u8]) -> Result<Signature>;
+}
+
+// Check if s < L, per RFC 8032, inspired by the Go runtime library's version
+// of this check.
+fn sc_minimal(raw_s: &[u8]) -> bool {
+ let mut rd = Cursor::new(raw_s);
+ let mut s = [0u64; 4];
+
+ // Read the raw scalar into limbs, and reverse it, because the raw
+ // representation is little-endian.
+ rd.read_u64_into::<LittleEndian>(&mut s[..]).unwrap();
+ s.reverse();
+
+ // Compare each limb, from most significant to least.
+ for i in 0..4 {
+ match s[i].cmp(&CURVE_ORDER[i]) {
+ Ordering::Greater => return false,
+ Ordering::Less => return true,
+ Ordering::Equal => {}
+ }
+ }
+
+ // The scalar is equal to the order of the curve.
+ false
+}
+
+/// Extends signature context with additional domain separation based on the runtime ID.
+pub fn signature_context_with_runtime_separation(
+ mut context: Vec<u8>,
+ runtime_id: &Namespace,
+) -> Vec<u8> {
+ context.extend(RUNTIME_SIGNATURE_CONTEXT_SEPARATOR);
+ context.extend(runtime_id.0);
+ context
+}
+
+/// Extends signature context with additional domain separation based on the chain context.
+pub fn signature_context_with_chain_separation(
+ mut context: Vec<u8>,
+ chain_context: &String,
+) -> Vec<u8> {
+ context.extend(CHAIN_SIGNATURE_CONTEXT_SEPARATOR);
+ context.extend(chain_context.as_bytes());
+ context
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use rustc_hex::FromHex;
+
+ #[test]
+ fn test_sc_minimal() {
+ // L - 2^0
+ assert!(sc_minimal(&[
+ 0xec, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58, 0xd6, 0x9c, 0xf7, 0xa2, 0xde, 0xf9,
+ 0xde, 0x14, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x10
+ ]));
+
+ // L - 2^64
+ assert!(sc_minimal(&[
+ 0xed, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58, 0xd5, 0x9c, 0xf7, 0xa2, 0xde, 0xf9,
+ 0xde, 0x14, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x10
+ ]));
+
+ // L - 2^192
+ assert!(sc_minimal(&[
+ 0xed, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58, 0xd5, 0x9c, 0xf7, 0xa2, 0xde, 0xf9,
+ 0xde, 0x14, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff,
+ 0xff, 0xff, 0xff, 0x0f,
+ ]));
+
+ // L
+ assert!(!sc_minimal(&[
+ 0xed, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58, 0xd6, 0x9c, 0xf7, 0xa2, 0xde, 0xf9,
+ 0xde, 0x14, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x10
+ ]));
+
+ // L + 2^0
+ assert!(!sc_minimal(&[
+ 0xef, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58, 0xd6, 0x9c, 0xf7, 0xa2, 0xde, 0xf9,
+ 0xde, 0x14, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x10
+ ]));
+
+ // L + 2^64
+ assert!(!sc_minimal(&[
+ 0xed, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58, 0xd7, 0x9c, 0xf7, 0xa2, 0xde, 0xf9,
+ 0xde, 0x14, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x10
+ ]));
+
+ // L + 2^128
+ assert!(!sc_minimal(&[
+ 0xed, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58, 0xd6, 0x9c, 0xf7, 0xa2, 0xde, 0xf9,
+ 0xde, 0x14, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x10
+ ]));
+
+ // L + 2^192
+ assert!(!sc_minimal(&[
+ 0xed, 0xd3, 0xf5, 0x5c, 0x1a, 0x63, 0x12, 0x58, 0xd6, 0x9c, 0xf7, 0xa2, 0xde, 0xf9,
+ 0xde, 0x14, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00,
+ 0x00, 0x00, 0x00, 0x10
+ ]));
+
+ // Scalar from the go runtime's test case.
+ assert!(!sc_minimal(&[
+ 0x67, 0x65, 0x4b, 0xce, 0x38, 0x32, 0xc2, 0xd7, 0x6f, 0x8f, 0x6f, 0x5d, 0xaf, 0xc0,
+ 0x8d, 0x93, 0x39, 0xd4, 0xee, 0xf6, 0x76, 0x57, 0x33, 0x36, 0xa5, 0xc5, 0x1e, 0xb6,
+ 0xf9, 0x46, 0xb3, 0x1d,
+ ]))
+ }
+
+ #[test]
+ fn test_private_key_to_bytes() {
+ let secret = PrivateKey::generate();
+ let bytes = secret.to_bytes();
+ let from_bytes = PrivateKey::from_bytes(bytes);
+ assert_eq!(secret.public_key(), from_bytes.public_key());
+ }
+
+ #[test]
+ #[should_panic]
+ fn test_private_key_to_bytes_malformed_a() {
+ PrivateKey::from_bytes(vec![]);
+ }
+
+ #[test]
+ #[should_panic]
+ fn test_private_key_to_bytes_malformed_b() {
+ PrivateKey::from_bytes(vec![1, 2, 3]);
+ }
+
+ #[test]
+ fn verification_small_order_a() {
+ // Case 1 from ed25519-speccheck
+ let pbk = "c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac03fa";
+ let msg = "9bd9f44f4dcc75bd531b56b2cd280b0bb38fc1cd6d1230e14861d861de092e79";
+ let sig = "f7badec5b8abeaf699583992219b7b223f1df3fbbea919844e3f7c554a43dd43a5bb704786be79fc476f91d3f3f89b03984d8068dcf1bb7dfc6637b45450ac04";
+
+ let pbk: Vec<u8> = pbk.from_hex().unwrap();
+ let msg: Vec<u8> = msg.from_hex().unwrap();
+ let sig: Vec<u8> = sig.from_hex().unwrap();
+
+ let pbk = PublicKey::from(pbk);
+ let sig = Signature::from(sig);
+
+ assert!(
+ sig.verify_raw(&pbk, &msg).is_err(),
+ "small order A not rejected"
+ )
+ }
+
+ #[test]
+ fn verification_small_order_r() {
+ // Case 2 from ed25519-speccheck
+ let pbk = "f7badec5b8abeaf699583992219b7b223f1df3fbbea919844e3f7c554a43dd43";
+ let msg = "aebf3f2601a0c8c5d39cc7d8911642f740b78168218da8471772b35f9d35b9ab";
+ let sig = "c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac03fa8c4bd45aecaca5b24fb97bc10ac27ac8751a7dfe1baff8b953ec9f5833ca260e";
+
+ let pbk: Vec<u8> = pbk.from_hex().unwrap();
+ let msg: Vec<u8> = msg.from_hex().unwrap();
+ let sig: Vec<u8> = sig.from_hex().unwrap();
+
+ let pbk = PublicKey::from(pbk);
+ let sig = Signature::from(sig);
+
+ assert!(
+ sig.verify_raw(&pbk, &msg).is_err(),
+ "small order R not rejected"
+ )
+ }
+
+ #[test]
+ fn verification_is_cofactored() {
+ // Case 4 from ed25519-speccheck
+ let pbk = "cdb267ce40c5cd45306fa5d2f29731459387dbf9eb933b7bd5aed9a765b88d4d";
+ let msg = "e47d62c63f830dc7a6851a0b1f33ae4bb2f507fb6cffec4011eaccd55b53f56c";
+ let sig = "160a1cb0dc9c0258cd0a7d23e94d8fa878bcb1925f2c64246b2dee1796bed5125ec6bc982a269b723e0668e540911a9a6a58921d6925e434ab10aa7940551a09";
+
+ let pbk: Vec<u8> = pbk.from_hex().unwrap();
+ let msg: Vec<u8> = msg.from_hex().unwrap();
+ let sig: Vec<u8> = sig.from_hex().unwrap();
+
+ let pbk = PublicKey::from(pbk);
+ let sig = Signature::from(sig);
+
+ assert!(
+ sig.verify_raw(&pbk, &msg).is_ok(),
+ "verification is not cofactored(?)"
+ )
+ }
+
+ // Note: It is hard to test rejects small order A/R combined with
+ // accepts non-canonical A/R as there are no known non-small order
+ // points with a non-canonical encoding, that are not also small
+ // order.
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +
//! CBOR serializable X25519 types.
+use anyhow::Result;
+use rand::rngs::OsRng;
+use zeroize::{Zeroize, ZeroizeOnDrop};
+
+use super::hash::Hash;
+
+/// The length of an X25519 private key, in bytes.
+pub const PRIVATE_KEY_LENGTH: usize = 32;
+
+/// The length of an X25519 public key, in bytes.
+pub const PUBLIC_KEY_LENGTH: usize = 32;
+
+/// A CBOR serializable Diffie-Hellman X25519 private key.
+#[derive(Clone, Zeroize, ZeroizeOnDrop)]
+pub struct PrivateKey(pub x25519_dalek::StaticSecret);
+
+impl PrivateKey {
+ /// Generate a new private key.
+ pub fn generate() -> Self {
+ PrivateKey(x25519_dalek::StaticSecret::random_from_rng(OsRng))
+ }
+
+ /// Compute corresponding public key.
+ pub fn public_key(&self) -> PublicKey {
+ PublicKey(x25519_dalek::PublicKey::from(&self.0))
+ }
+
+ /// Generate a new private key from a test key seed.
+ pub fn from_test_seed(seed: String) -> Self {
+ let seed = Hash::digest_bytes(seed.as_bytes());
+ Self::from(seed.0)
+ }
+}
+
+impl From<[u8; PRIVATE_KEY_LENGTH]> for PrivateKey {
+ /// Load private key from a byte array.
+ fn from(bytes: [u8; PRIVATE_KEY_LENGTH]) -> PrivateKey {
+ PrivateKey(x25519_dalek::StaticSecret::from(bytes))
+ }
+}
+
+impl Default for PrivateKey {
+ fn default() -> Self {
+ Self::from([0; PRIVATE_KEY_LENGTH])
+ }
+}
+
+impl AsRef<[u8]> for PrivateKey {
+ fn as_ref(&self) -> &[u8] {
+ self.0.as_ref()
+ }
+}
+
+impl From<PrivateKey> for x25519_dalek::StaticSecret {
+ fn from(sk: PrivateKey) -> Self {
+ sk.0.clone() // `sk` will be zeroized on drop, so clone is ok.
+ }
+}
+
+impl From<x25519_dalek::StaticSecret> for PrivateKey {
+ fn from(sk: x25519_dalek::StaticSecret) -> Self {
+ Self(sk)
+ }
+}
+
+impl cbor::Encode for PrivateKey {
+ fn into_cbor_value(self) -> cbor::Value {
+ cbor::to_value(self.0.to_bytes())
+ }
+}
+
+impl cbor::Decode for PrivateKey {
+ fn try_default() -> Result<Self, cbor::DecodeError> {
+ Ok(Default::default())
+ }
+
+ fn try_from_cbor_value(value: cbor::Value) -> Result<Self, cbor::DecodeError> {
+ let mut bytes: [u8; PRIVATE_KEY_LENGTH] = cbor::Decode::try_from_cbor_value(value)?;
+ let sk = PrivateKey(x25519_dalek::StaticSecret::from(bytes));
+ bytes.zeroize();
+ Ok(sk)
+ }
+}
+
+/// A CBOR serializable Diffie-Hellman X25519 public key.
+#[derive(PartialEq, Eq, Hash, Copy, Clone, Debug)]
+pub struct PublicKey(pub x25519_dalek::PublicKey);
+
+impl From<[u8; PUBLIC_KEY_LENGTH]> for PublicKey {
+ /// Load public key from a byte array.
+ fn from(bytes: [u8; PUBLIC_KEY_LENGTH]) -> PublicKey {
+ PublicKey(x25519_dalek::PublicKey::from(bytes))
+ }
+}
+
+impl From<&PrivateKey> for PublicKey {
+ /// Given an X25519 private key, compute its corresponding public key.
+ fn from(sk: &PrivateKey) -> PublicKey {
+ PublicKey(x25519_dalek::PublicKey::from(&sk.0))
+ }
+}
+
+impl Default for PublicKey {
+ fn default() -> Self {
+ Self::from([0; PUBLIC_KEY_LENGTH])
+ }
+}
+
+impl AsRef<[u8]> for PublicKey {
+ fn as_ref(&self) -> &[u8] {
+ self.0.as_ref()
+ }
+}
+
+impl From<PublicKey> for x25519_dalek::PublicKey {
+ fn from(pk: PublicKey) -> Self {
+ pk.0
+ }
+}
+
+impl From<x25519_dalek::PublicKey> for PublicKey {
+ fn from(pk: x25519_dalek::PublicKey) -> Self {
+ Self(pk)
+ }
+}
+
+impl cbor::Encode for PublicKey {
+ fn into_cbor_value(self) -> cbor::Value {
+ cbor::to_value(*self.0.as_bytes())
+ }
+}
+
+impl cbor::Decode for PublicKey {
+ fn try_default() -> Result<Self, cbor::DecodeError> {
+ Ok(Default::default())
+ }
+
+ fn try_from_cbor_value(value: cbor::Value) -> Result<Self, cbor::DecodeError> {
+ let bytes: [u8; PUBLIC_KEY_LENGTH] = cbor::Decode::try_from_cbor_value(value)?;
+ let pk = PublicKey(x25519_dalek::PublicKey::from(bytes));
+ Ok(pk)
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use crate::common::crypto::x25519::{PrivateKey, PublicKey, PRIVATE_KEY_LENGTH};
+
+ #[test]
+ fn test_cbor_serialization() {
+ let sk = PrivateKey::from([1; PRIVATE_KEY_LENGTH]);
+ let pk = PublicKey::from(&sk);
+
+ // Encode/decode private key.
+ let enc = cbor::to_vec(sk.clone());
+ let dec: PrivateKey = cbor::from_slice(&enc).expect("deserialization should succeed");
+ assert_eq!(
+ sk.0.to_bytes(),
+ dec.0.to_bytes(),
+ "serialization should round-trip"
+ );
+
+ // Encode/decode public key.
+ let enc = cbor::to_vec(pk.clone());
+ let dec: PublicKey = cbor::from_slice(&enc).expect("deserialization should succeed");
+ assert_eq!(
+ pk.0.to_bytes(),
+ dec.0.to_bytes(),
+ "serialization should round-trip"
+ );
+ }
+
+ #[test]
+ fn test_zeroize_on_drop() {
+ // Prepare private key.
+ let private_key_ptr;
+ {
+ let private_key = PrivateKey([10; 32].into());
+ private_key_ptr = private_key.0.as_bytes().as_ptr();
+ }
+
+ // Access the elements of the private key using pointer
+ // arithmetic and verify that they are all zero.
+ unsafe {
+ for i in 0..32 {
+ assert_eq!(*private_key_ptr.add(i), 0);
+ }
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +
use std::{convert::TryInto, mem::size_of};
+
+use impl_trait_for_tuples::impl_for_tuples;
+
+/// Size of the KeyFormat prefix.
+const KEY_FORMAT_PREFIX_SIZE: usize = size_of::<u8>();
+
+/// A key formatting helper trait to be used together with key-value
+/// backends for constructing keys.
+pub trait KeyFormat {
+ /// The prefix that identifies the key format.
+ fn prefix() -> u8;
+
+ /// The minimum size of the encoded key.
+ fn size() -> usize;
+
+ /// Encode the given key format into a set of atoms.
+ fn encode_atoms(self, atoms: &mut Vec<Vec<u8>>);
+
+ /// Decode the given key format from data (without prefix).
+ ///
+ /// The caller must ensure that the size of the passed data is at
+ /// least the minimum size returned by `size`.
+ fn decode_atoms(data: &[u8]) -> Self
+ where
+ Self: Sized;
+
+ /// Encode the first few atoms in the key format.
+ ///
+ /// This method can be used to construct key prefixes for iteration.
+ /// Specifying a zero count will only generate the prefix.
+ fn encode_partial(self, count: usize) -> Vec<u8>
+ where
+ Self: Sized,
+ {
+ let mut v = Vec::with_capacity(KEY_FORMAT_PREFIX_SIZE + Self::size());
+ v.push(Self::prefix());
+
+ if count == 0 {
+ return v;
+ }
+
+ let mut atoms = Vec::new();
+ self.encode_atoms(&mut atoms);
+ for (included, mut atom) in atoms.into_iter().enumerate() {
+ if included >= count {
+ break;
+ }
+ v.append(&mut atom);
+ }
+
+ v
+ }
+
+ /// Encode the given key format.
+ fn encode(self) -> Vec<u8>
+ where
+ Self: Sized,
+ {
+ self.encode_partial(usize::MAX)
+ }
+
+ /// Decode the given key format from data.
+ ///
+ /// The method may return `None` in case the key is of a different
+ /// type as indicated by the prefix byte.
+ fn decode(data: &[u8]) -> Option<Self>
+ where
+ Self: Sized,
+ {
+ assert!(!data.is_empty(), "key format: malformed input (empty data)");
+ if data[0] != Self::prefix() {
+ return None;
+ }
+ assert!(
+ data.len() >= Self::size() + KEY_FORMAT_PREFIX_SIZE,
+ "key format: malformed input"
+ );
+
+ Some(Self::decode_atoms(&data[1..]))
+ }
+}
+
+/// Part of the KeyFormat to be used with key-value backends for constructing keys.
+pub trait KeyFormatAtom {
+ fn size() -> usize;
+
+ fn encode_atom(self) -> Vec<u8>;
+
+ fn decode_atom(data: &[u8]) -> Self
+ where
+ Self: Sized;
+}
+
+impl KeyFormatAtom for u64 {
+ fn size() -> usize {
+ 8
+ }
+
+ fn encode_atom(self) -> Vec<u8> {
+ self.to_be_bytes().to_vec()
+ }
+
+ fn decode_atom(data: &[u8]) -> Self
+ where
+ Self: Sized,
+ {
+ u64::from_be_bytes(data.try_into().expect("key_format: malformed u64 input"))
+ }
+}
+
+impl KeyFormatAtom for u8 {
+ fn size() -> usize {
+ 1
+ }
+
+ fn encode_atom(self) -> Vec<u8> {
+ vec![self]
+ }
+
+ fn decode_atom(data: &[u8]) -> Self
+ where
+ Self: Sized,
+ {
+ assert!(!data.is_empty(), "key_format: malformed: u8 input");
+ data[0]
+ }
+}
+
+impl KeyFormatAtom for () {
+ fn size() -> usize {
+ 0
+ }
+
+ fn encode_atom(self) -> Vec<u8> {
+ Vec::new()
+ }
+
+ fn decode_atom(_: &[u8]) {}
+}
+
+#[impl_for_tuples(2, 10)]
+impl KeyFormatAtom for Tuple {
+ fn size() -> usize {
+ for_tuples!( #( Tuple::size() )+* );
+ }
+
+ fn encode_atom(self) -> Vec<u8> {
+ let mut atoms: Vec<Vec<u8>> = [for_tuples!( #( self.Tuple.encode_atom() ),* )].to_vec();
+
+ atoms.into_iter().flatten().collect()
+ }
+
+ fn decode_atom(data: &[u8]) -> for_tuples!( ( #( Tuple ),* ) ) {
+ assert!(
+ data.len() >= Self::size(),
+ "key format atom: malformed input"
+ );
+
+ let mut sizes: Vec<usize> = [for_tuples!( #( Tuple::size() ),* )].to_vec();
+ sizes.reverse();
+ let mut data = data.to_vec();
+
+ /*
+ (
+ {
+ let x = T1::decode_atom(data.drain(0..T1::size()));
+ x
+ },
+ {
+ let x = T2::decode_atom(data.drain(0..T2::size()));
+ x
+ }
+ ...
+ )
+ */
+ for_tuples!(
+ (
+ #(
+ {
+ let x = Tuple::decode_atom(data.drain(0..sizes.pop().unwrap()).as_slice());
+ x
+ }
+ ),*
+ )
+ )
+ }
+}
+
+/// Define a KeyFormat from KeyFormatAtom and a prefix.
+///
+/// # Examples
+///
+/// ```rust,ignore
+/// key_format!(NewKeyFormatName, 0x01, InnerType);
+/// ```
+#[macro_export]
+macro_rules! key_format {
+ ($name:ident, $prefix:expr, $inner:ty) => {
+ #[derive(Debug, Default, PartialEq, Eq, Clone)]
+ struct $name($inner);
+
+ impl KeyFormat for $name {
+ fn prefix() -> u8 {
+ $prefix
+ }
+
+ fn size() -> usize {
+ <$inner>::size()
+ }
+
+ fn encode_atoms(self, atoms: &mut Vec<Vec<u8>>) {
+ atoms.push(self.0.encode_atom());
+ }
+
+ fn decode_atoms(data: &[u8]) -> Self {
+ Self(<$inner>::decode_atom(data))
+ }
+ }
+ };
+}
+
+#[cfg(test)]
+mod test {
+ use rustc_hex::ToHex;
+
+ use crate::common::crypto::hash::Hash;
+
+ use super::*;
+
+ #[derive(Debug, PartialEq)]
+ struct Test1KeyFormat {
+ h: Hash,
+ }
+
+ impl KeyFormat for Test1KeyFormat {
+ fn prefix() -> u8 {
+ b'T'
+ }
+
+ fn size() -> usize {
+ 32
+ }
+
+ fn encode_atoms(self, atoms: &mut Vec<Vec<u8>>) {
+ atoms.push(self.h.as_ref().to_vec());
+ }
+
+ fn decode_atoms(data: &[u8]) -> Self {
+ Self { h: data.into() }
+ }
+ }
+
+ #[test]
+ fn test_key_format() {
+ let mut enc = Test1KeyFormat {
+ h: Hash::empty_hash(),
+ }
+ .encode();
+ assert_eq!(
+ enc.to_hex::<String>(),
+ "54c672b8d1ef56ed28ab87c3622c5114069bdd3ad7b8f9737498d0c01ecef0967a"
+ );
+
+ let dec = Test1KeyFormat::decode(&enc);
+ assert_eq!(
+ dec,
+ Some(Test1KeyFormat {
+ h: Hash::empty_hash()
+ })
+ );
+
+ // Clear type.
+ enc[0] = 0x00;
+ let dec = Test1KeyFormat::decode(&enc);
+ assert_eq!(dec, None);
+
+ // Partial encoding.
+ let enc = Test1KeyFormat {
+ h: Hash::empty_hash(),
+ }
+ .encode_partial(0);
+ assert_eq!(enc.to_hex::<String>(), "54");
+ }
+
+ #[test]
+ fn test_key_format_atom() {
+ key_format!(TestKeyFormat, 0x01, (u8, u64, u8, u64, u64));
+
+ let key = TestKeyFormat((1, 2, 3, 4, 5));
+ let enc = key.clone().encode();
+ let dec = TestKeyFormat::decode(&enc);
+
+ assert_eq!(dec, Some(key),)
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +
//! Logging subsystem for runtimes.
+use std::sync::{Mutex, Once};
+
+use lazy_static::lazy_static;
+use log::Level;
+use slog::{o, Drain};
+
+lazy_static! {
+ static ref LOGGER: slog::Logger = slog::Logger::root(
+ Mutex::new(slog_json::Json::default(std::io::stderr())).map(slog::Fuse),
+ o!()
+ );
+
+ /// Initializes the global logger once.
+ static ref INIT_GLOBAL_LOGGER: Once = Once::new();
+
+ /// Prevents the global logger from being dropped.
+ static ref GLOBAL_LOGGER_SCOPE_GUARD: Mutex<Option<slog_scope::GlobalLoggerGuard>> = Mutex::new(None);
+}
+
+/// Get the logger.
+pub fn get_logger(module: &'static str) -> slog::Logger {
+ LOGGER.new(o!("module" => module))
+}
+
+/// Initialize the global slog_stdlog adapter to allow logging with the log crate (instead of slog).
+pub fn init_logger(level: Level) {
+ INIT_GLOBAL_LOGGER.call_once(|| {
+ let global_logger = LOGGER.new(o!("module" => "global"));
+ GLOBAL_LOGGER_SCOPE_GUARD
+ .lock()
+ .unwrap()
+ .get_or_insert(slog_scope::set_global_logger(global_logger));
+ slog_stdlog::init_with_level(level).unwrap();
+ });
+}
+//! Common types.
+
+#[macro_use]
+pub mod bytes;
+pub mod crypto;
+pub mod key_format;
+pub mod logger;
+pub mod namespace;
+pub mod panic;
+pub mod process;
+pub mod quantity;
+pub mod sgx;
+#[cfg(feature = "tdx")]
+pub mod tdx;
+pub mod time;
+pub mod version;
+pub mod versioned;
+//! Panic-related functions.
+
+/// A guard that will abort the process if dropped while panicking.
+///
+/// This is to ensure that the runtime will terminate in case there is
+/// a panic encountered during dispatch and the runtime is built with
+/// a non-abort panic handler.
+pub struct AbortOnPanic;
+
+impl Drop for AbortOnPanic {
+ fn drop(&mut self) {
+ if std::thread::panicking() {
+ crate::common::process::abort();
+ }
+ }
+}
+//! Process-related helpers.
+use std::io::Write;
+
+/// Aborts the process via `std::process::abort`, but also making sure that log buffers are flushed.
+pub fn abort() -> ! {
+ // Attempt to flush buffers to ensure any log output makes it.
+ let _ = std::io::stderr().flush();
+ let _ = std::io::stdout().flush();
+
+ // Abort the process.
+ std::process::abort()
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +
//! An arbitrary precision unsigned integer.
+use std::{
+ convert::TryFrom,
+ fmt,
+ num::IntErrorKind,
+ ops::{Add, AddAssign, Mul, MulAssign},
+};
+
+use num_bigint::BigUint;
+use num_traits::{CheckedDiv, CheckedSub, ToPrimitive, Zero};
+
+/// An arbitrary precision unsigned integer.
+#[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct Quantity(BigUint);
+
+impl Quantity {
+ /// Subtracts two numbers, checking for underflow. If underflow happens, `None` is returned.
+ #[inline]
+ pub fn checked_sub(&self, other: &Quantity) -> Option<Quantity> {
+ // NOTE: This does not implemented the num_traits::CheckedSub trait because this forces
+ // one to also implement Sub which we explicitly don't want to do.
+ self.0.checked_sub(&other.0).map(Quantity)
+ }
+
+ /// Divides two numbers, checking for underflow, overflow and division by zero. If any of that
+ /// happens, `None` is returned.
+ #[inline]
+ pub fn checked_div(&self, other: &Quantity) -> Option<Quantity> {
+ // NOTE: This does not implemented the num_traits::CheckedDiv trait because this forces
+ // one to also implement Div which we explicitly don't want to do.
+ self.0.checked_div(&other.0).map(Quantity)
+ }
+}
+
+impl Zero for Quantity {
+ fn zero() -> Self {
+ Quantity(BigUint::zero())
+ }
+
+ fn is_zero(&self) -> bool {
+ self.0.is_zero()
+ }
+}
+
+impl From<u8> for Quantity {
+ fn from(v: u8) -> Quantity {
+ Quantity(BigUint::from(v))
+ }
+}
+
+impl From<u16> for Quantity {
+ fn from(v: u16) -> Quantity {
+ Quantity(BigUint::from(v))
+ }
+}
+
+impl From<u32> for Quantity {
+ fn from(v: u32) -> Quantity {
+ Quantity(BigUint::from(v))
+ }
+}
+
+impl From<u64> for Quantity {
+ fn from(v: u64) -> Quantity {
+ Quantity(BigUint::from(v))
+ }
+}
+
+impl From<u128> for Quantity {
+ fn from(v: u128) -> Quantity {
+ Quantity(BigUint::from(v))
+ }
+}
+
+impl TryFrom<Quantity> for u64 {
+ type Error = IntErrorKind;
+
+ fn try_from(value: Quantity) -> Result<u64, Self::Error> {
+ value.0.to_u64().ok_or(IntErrorKind::PosOverflow)
+ }
+}
+
+impl TryFrom<&Quantity> for u64 {
+ type Error = IntErrorKind;
+
+ fn try_from(value: &Quantity) -> Result<u64, Self::Error> {
+ value.0.to_u64().ok_or(IntErrorKind::PosOverflow)
+ }
+}
+
+impl TryFrom<Quantity> for u128 {
+ type Error = IntErrorKind;
+
+ fn try_from(value: Quantity) -> Result<u128, Self::Error> {
+ value.0.to_u128().ok_or(IntErrorKind::PosOverflow)
+ }
+}
+
+impl TryFrom<&Quantity> for u128 {
+ type Error = IntErrorKind;
+
+ fn try_from(value: &Quantity) -> Result<u128, Self::Error> {
+ value.0.to_u128().ok_or(IntErrorKind::PosOverflow)
+ }
+}
+
+impl Add for Quantity {
+ type Output = Quantity;
+
+ fn add(mut self, other: Quantity) -> Quantity {
+ self += &other;
+ self
+ }
+}
+
+impl<'a> Add<&'a Quantity> for Quantity {
+ type Output = Quantity;
+
+ fn add(mut self, other: &Quantity) -> Quantity {
+ self += other;
+ self
+ }
+}
+
+impl<'a> AddAssign<&'a Quantity> for Quantity {
+ fn add_assign(&mut self, other: &Quantity) {
+ self.0 += &other.0;
+ }
+}
+
+impl AddAssign<Quantity> for Quantity {
+ fn add_assign(&mut self, other: Quantity) {
+ self.0 += other.0;
+ }
+}
+
+impl Add<u64> for Quantity {
+ type Output = Quantity;
+
+ fn add(mut self, other: u64) -> Quantity {
+ self += other;
+ self
+ }
+}
+
+impl AddAssign<u64> for Quantity {
+ fn add_assign(&mut self, other: u64) {
+ self.0 += other;
+ }
+}
+
+impl Mul for Quantity {
+ type Output = Quantity;
+
+ fn mul(mut self, rhs: Quantity) -> Quantity {
+ self *= &rhs;
+ self
+ }
+}
+
+impl<'a> Mul<&'a Quantity> for Quantity {
+ type Output = Quantity;
+
+ fn mul(mut self, rhs: &Quantity) -> Quantity {
+ self *= rhs;
+ self
+ }
+}
+
+impl<'a> MulAssign<&'a Quantity> for Quantity {
+ fn mul_assign(&mut self, rhs: &Quantity) {
+ self.0 *= &rhs.0;
+ }
+}
+
+impl MulAssign<Quantity> for Quantity {
+ fn mul_assign(&mut self, rhs: Quantity) {
+ self.0 *= rhs.0;
+ }
+}
+
+impl Mul<u64> for Quantity {
+ type Output = Quantity;
+
+ fn mul(mut self, other: u64) -> Quantity {
+ self *= other;
+ self
+ }
+}
+
+impl MulAssign<u64> for Quantity {
+ fn mul_assign(&mut self, other: u64) {
+ self.0 *= other;
+ }
+}
+
+impl fmt::Display for Quantity {
+ fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+ self.0.fmt(f)
+ }
+}
+
+impl cbor::Encode for Quantity {
+ fn is_empty(&self) -> bool {
+ self.0.is_zero()
+ }
+
+ fn into_cbor_value(self) -> cbor::Value {
+ if self.0.is_zero() {
+ cbor::Value::ByteString(vec![])
+ } else {
+ cbor::Value::ByteString(self.0.to_bytes_be())
+ }
+ }
+}
+
+impl cbor::Decode for Quantity {
+ fn try_default() -> Result<Self, cbor::DecodeError> {
+ Ok(Default::default())
+ }
+
+ fn try_from_cbor_value(value: cbor::Value) -> Result<Self, cbor::DecodeError> {
+ match value {
+ cbor::Value::ByteString(data) => Ok(Quantity(BigUint::from_bytes_be(&data))),
+ _ => Err(cbor::DecodeError::UnexpectedType),
+ }
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use rustc_hex::ToHex;
+
+ use crate::common::quantity::Quantity;
+
+ #[test]
+ fn test_serialization() {
+ // NOTE: These should be synced with go/common/quantity/quantity_test.go.
+ let cases = vec![
+ (0u128, "40"),
+ (1, "4101"),
+ (10, "410a"),
+ (100, "4164"),
+ (1000, "4203e8"),
+ (1000000, "430f4240"),
+ (18446744073709551615, "48ffffffffffffffff"),
+ ];
+
+ for tc in cases {
+ let q = Quantity::from(tc.0);
+ let enc = cbor::to_vec(q.clone());
+ assert_eq!(enc.to_hex::<String>(), tc.1, "serialization should match");
+
+ let dec: Quantity = cbor::from_slice(&enc).expect("deserialization should succeed");
+ assert_eq!(dec, q, "serialization should round-trip");
+ }
+ }
+
+ #[test]
+ fn test_ops() {
+ // Add.
+ assert_eq!(
+ Quantity::from(1000u32) + Quantity::from(2000u32),
+ Quantity::from(3000u32)
+ );
+
+ let mut a = Quantity::from(1000u32);
+ a += Quantity::from(42u32);
+ assert_eq!(a, Quantity::from(1042u32));
+ a += &Quantity::from(42u32);
+ assert_eq!(a, Quantity::from(1084u32));
+
+ let mut a = Quantity::from(1000u32);
+ a += 42;
+ assert_eq!(a, Quantity::from(1042u32));
+
+ // Sub.
+ let a = Quantity::from(1000u32);
+ assert_eq!(
+ a.checked_sub(&Quantity::from(42u32)),
+ Some(Quantity::from(958u32))
+ );
+ assert_eq!(a.checked_sub(&Quantity::from(1100u32)), None);
+
+ // Mul.
+ assert_eq!(
+ Quantity::from(1000u32) * Quantity::from(1000u32),
+ Quantity::from(1_000_000u32)
+ );
+
+ let mut a = Quantity::from(1000u32);
+ a *= Quantity::from(1000u32);
+ assert_eq!(a, Quantity::from(1_000_000u32));
+ a *= &Quantity::from(1000u32);
+ assert_eq!(a, Quantity::from(1_000_000_000u32));
+
+ let mut a = Quantity::from(1000u32);
+ a *= 1000;
+ assert_eq!(a, Quantity::from(1_000_000u32));
+
+ // Div.
+ let a = Quantity::from(1000u32);
+ assert_eq!(
+ a.checked_div(&Quantity::from(3u32)),
+ Some(Quantity::from(333u32))
+ );
+ assert_eq!(
+ a.checked_div(&Quantity::from(1001u32)),
+ Some(Quantity::from(0u32))
+ );
+ assert_eq!(a.checked_div(&Quantity::from(0u32)), None);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +
//! SGX per-CPU package sealing key accessor.
+
+use sgx_isa::Keypolicy;
+use sp800_185::KMac;
+
+#[cfg(target_env = "sgx")]
+use sgx_isa::{Keyname, Keyrequest};
+#[cfg(target_env = "sgx")]
+use tiny_keccak::{Hasher, Sha3};
+
+const SEAL_KDF_CUSTOM: &[u8] = b"Ekiden Expand SGX Seal Key";
+
+cfg_if::cfg_if! {
+ if #[cfg(target_env = "sgx")] {
+ fn egetkey_impl(key_policy: Keypolicy, context: &[u8]) -> [u8; 16] {
+ let mut req = Keyrequest::default();
+
+ req.keyname = Keyname::Seal as u16;
+ req.keypolicy = key_policy;
+
+ let mut sha3 = Sha3::v256();
+ sha3.update(context);
+ let mut k = [0; 32];
+ sha3.finalize(&mut k);
+ req.keyid = k;
+
+ // Fucking sgx_isa::Attributes doesn't have a -> [u64;2].
+ req.attributemask[0] = 1 | 2 | 4; // SGX_FLAGS_INITTED | SGX_FLAGS_DEBUG | SGX_FLAGS_MODE64BIT
+ req.attributemask[1] = 3; // SGX_XFRM_LEGACY
+
+ match req.egetkey() {
+ Err(e) => panic!("EGETKEY failed: {:?}", e),
+ Ok(k) => k,
+ }
+ }
+ } else if #[cfg(feature = "tdx")] {
+ fn egetkey_impl(_key_policy: Keypolicy, _context: &[u8]) -> [u8; 16] {
+ unimplemented!("EGETKEY not implemented for TDX");
+ }
+ } else {
+ const MOCK_MRENCLAVE_KEY: &[u8] = b"Ekiden Test MRENCLAVE KEY";
+ const MOCK_MRSIGNER_KEY: &[u8] = b"Ekiden Test MRSIGNER KEY";
+ const MOCK_KDF_CUSTOM: &[u8] = b"Ekiden Extract Test SGX Seal Key";
+
+ fn egetkey_impl(key_policy: Keypolicy, context: &[u8]) -> [u8; 16] {
+ let mut k = [0u8; 16];
+
+ // Deterministically generate a test master key from the context.
+ let mut kdf = match key_policy {
+ Keypolicy::MRENCLAVE => KMac::new_kmac256(MOCK_MRENCLAVE_KEY, MOCK_KDF_CUSTOM),
+ Keypolicy::MRSIGNER => KMac::new_kmac256(MOCK_MRSIGNER_KEY, MOCK_KDF_CUSTOM),
+ _ => panic!("Invalid key_policy"),
+ };
+ kdf.update(context);
+ kdf.finalize(&mut k);
+
+ k
+ }
+ }
+}
+
+/// egetkey returns a 256 bit key suitable for sealing secrets to the
+/// enclave in cold storage, derived from the results of the `EGETKEY`
+/// instruction. The `context` field is a domain separation tag.
+///
+/// Note: The key can also be used for other things (eg: as an X25519
+/// private key).
+pub fn egetkey(key_policy: Keypolicy, context: &[u8]) -> [u8; 32] {
+ let mut k = [0u8; 32];
+
+ // Obtain the per-CPU package SGX sealing key, with the requested
+ // policy.
+ let master_secret = egetkey_impl(key_policy, context);
+
+ // Expand the 128 bit EGETKEY result into a 256 bit key, suitable
+ // for use with our MRAE primitives.
+ let mut kdf = KMac::new_kmac256(&master_secret, SEAL_KDF_CUSTOM);
+ kdf.update(context);
+ kdf.finalize(&mut k);
+
+ k
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn test_egetkey() {
+ // Ensure key policies works.
+ let mr_signer_key = egetkey(Keypolicy::MRSIGNER, b"MRSIGNER");
+ assert!(mr_signer_key != [0u8; 32]);
+ let mr_enclave_key = egetkey(Keypolicy::MRENCLAVE, b"MRENCLAVE");
+ assert!(mr_enclave_key != [0u8; 32]);
+ assert!(mr_signer_key != mr_enclave_key);
+
+ // Ensure the context does something.
+ let a_key = egetkey(Keypolicy::MRENCLAVE, b"Context A");
+ let b_key = egetkey(Keypolicy::MRENCLAVE, b"Context B");
+ assert!(a_key != b_key);
+
+ // Ensure determinism.
+ let aa_key = egetkey(Keypolicy::MRENCLAVE, b"Context A");
+ assert!(a_key == aa_key);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +
//! Intel Attestation Service (IAS) attestation verification report handling.
+use std::io::{Cursor, Read, Seek, SeekFrom};
+
+use anyhow::{anyhow, Result};
+use base64::prelude::*;
+use byteorder::{LittleEndian, ReadBytesExt};
+use chrono::prelude::*;
+use lazy_static::lazy_static;
+use oid_registry::{OID_PKCS1_RSAENCRYPTION, OID_PKCS1_SHA256WITHRSA};
+use rsa::{pkcs1::DecodeRsaPublicKey, pkcs1v15::Pkcs1v15Sign, RsaPublicKey};
+use sgx_isa::{AttributesFlags, Report};
+use sha2::{digest::Update as _, Digest, Sha256};
+use thiserror::Error;
+use x509_parser::prelude::*;
+
+use crate::common::{
+ sgx::{EnclaveIdentity, MrEnclave, MrSigner, VerifiedQuote},
+ time::{insecure_posix_time, update_insecure_posix_time},
+};
+
+/// AVR verification error.
+#[derive(Error, Debug)]
+enum AVRError {
+ #[error("failed to parse report body")]
+ MalformedReportBody,
+ #[error("report body did not contain timestamp")]
+ MissingTimestamp,
+ #[error("failed to parse timestamp")]
+ MalformedTimestamp,
+ #[error("timestamp differs by more than 1 day")]
+ TimestampOutOfRange,
+ #[error("rejecting quote status ({status:?})")]
+ QuoteStatusInvalid { status: String },
+ #[error("debug enclaves not allowed")]
+ DebugEnclave,
+ #[error("production enclaves not allowed")]
+ ProductionEnclave,
+ #[error("AVR did not contain quote status")]
+ MissingQuoteStatus,
+ #[error("AVR did not contain quote body")]
+ MissingQuoteBody,
+ #[error("failed to parse quote")]
+ MalformedQuote,
+ #[error("unable to find exactly 2 certificates")]
+ ChainNotTwoCertificates,
+ #[error("malformed certificate PEM")]
+ MalformedCertificatePEM,
+ #[error("malformed certificate DER")]
+ MalformedCertificateDER,
+ #[error("expired certificate")]
+ ExpiredCertificate,
+ #[error("invalid signature")]
+ InvalidSignature,
+ #[error("IAS quotes are disabled by policy")]
+ Disabled,
+ #[error("blacklisted IAS quote GID")]
+ BlacklistedGID,
+ #[error("TCB evaluation data number is invalid")]
+ TCBEvaluationDataNumberInvalid,
+}
+
+pub const QUOTE_CONTEXT_LEN: usize = 8;
+/// The purpose of `QuoteContext` is to prevent quotes from being used in
+/// different contexts. The value is included as a prefix in report data.
+pub type QuoteContext = [u8; QUOTE_CONTEXT_LEN];
+
+// AVR signature validation constants.
+const IAS_TRUST_ANCHOR_PEM: &str = r#"-----BEGIN CERTIFICATE-----
+MIIFSzCCA7OgAwIBAgIJANEHdl0yo7CUMA0GCSqGSIb3DQEBCwUAMH4xCzAJBgNV
+BAYTAlVTMQswCQYDVQQIDAJDQTEUMBIGA1UEBwwLU2FudGEgQ2xhcmExGjAYBgNV
+BAoMEUludGVsIENvcnBvcmF0aW9uMTAwLgYDVQQDDCdJbnRlbCBTR1ggQXR0ZXN0
+YXRpb24gUmVwb3J0IFNpZ25pbmcgQ0EwIBcNMTYxMTE0MTUzNzMxWhgPMjA0OTEy
+MzEyMzU5NTlaMH4xCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJDQTEUMBIGA1UEBwwL
+U2FudGEgQ2xhcmExGjAYBgNVBAoMEUludGVsIENvcnBvcmF0aW9uMTAwLgYDVQQD
+DCdJbnRlbCBTR1ggQXR0ZXN0YXRpb24gUmVwb3J0IFNpZ25pbmcgQ0EwggGiMA0G
+CSqGSIb3DQEBAQUAA4IBjwAwggGKAoIBgQCfPGR+tXc8u1EtJzLA10Feu1Wg+p7e
+LmSRmeaCHbkQ1TF3Nwl3RmpqXkeGzNLd69QUnWovYyVSndEMyYc3sHecGgfinEeh
+rgBJSEdsSJ9FpaFdesjsxqzGRa20PYdnnfWcCTvFoulpbFR4VBuXnnVLVzkUvlXT
+L/TAnd8nIZk0zZkFJ7P5LtePvykkar7LcSQO85wtcQe0R1Raf/sQ6wYKaKmFgCGe
+NpEJUmg4ktal4qgIAxk+QHUxQE42sxViN5mqglB0QJdUot/o9a/V/mMeH8KvOAiQ
+byinkNndn+Bgk5sSV5DFgF0DffVqmVMblt5p3jPtImzBIH0QQrXJq39AT8cRwP5H
+afuVeLHcDsRp6hol4P+ZFIhu8mmbI1u0hH3W/0C2BuYXB5PC+5izFFh/nP0lc2Lf
+6rELO9LZdnOhpL1ExFOq9H/B8tPQ84T3Sgb4nAifDabNt/zu6MmCGo5U8lwEFtGM
+RoOaX4AS+909x00lYnmtwsDVWv9vBiJCXRsCAwEAAaOByTCBxjBgBgNVHR8EWTBX
+MFWgU6BRhk9odHRwOi8vdHJ1c3RlZHNlcnZpY2VzLmludGVsLmNvbS9jb250ZW50
+L0NSTC9TR1gvQXR0ZXN0YXRpb25SZXBvcnRTaWduaW5nQ0EuY3JsMB0GA1UdDgQW
+BBR4Q3t2pn680K9+QjfrNXw7hwFRPDAfBgNVHSMEGDAWgBR4Q3t2pn680K9+Qjfr
+NXw7hwFRPDAOBgNVHQ8BAf8EBAMCAQYwEgYDVR0TAQH/BAgwBgEB/wIBADANBgkq
+hkiG9w0BAQsFAAOCAYEAeF8tYMXICvQqeXYQITkV2oLJsp6J4JAqJabHWxYJHGir
+IEqucRiJSSx+HjIJEUVaj8E0QjEud6Y5lNmXlcjqRXaCPOqK0eGRz6hi+ripMtPZ
+sFNaBwLQVV905SDjAzDzNIDnrcnXyB4gcDFCvwDFKKgLRjOB/WAqgscDUoGq5ZVi
+zLUzTqiQPmULAQaB9c6Oti6snEFJiCQ67JLyW/E83/frzCmO5Ru6WjU4tmsmy8Ra
+Ud4APK0wZTGtfPXU7w+IBdG5Ez0kE1qzxGQaL4gINJ1zMyleDnbuS8UicjJijvqA
+152Sq049ESDz+1rRGc2NVEqh1KaGXmtXvqxXcTB+Ljy5Bw2ke0v8iGngFBPqCTVB
+3op5KBG3RjbF6RRSzwzuWfL7QErNC8WEy5yDVARzTA5+xmBc388v9Dm21HGfcC8O
+DD+gT9sSpssq0ascmvH49MOgjt1yoysLtdCtJW/9FZpoOypaHx0R+mJTLwPXVMrv
+DaVzWh5aiEx+idkSGMnX
+-----END CERTIFICATE-----"#;
+const PEM_CERTIFICATE_LABEL: &str = "CERTIFICATE";
+const IAS_TS_FMT: &str = "%FT%T%.6f";
+lazy_static! {
+ static ref IAS_TRUST_ANCHOR: Vec<u8> = {
+ let pem = match parse_x509_pem(IAS_TRUST_ANCHOR_PEM.as_bytes()) {
+ Ok((rem, pem)) => {
+ assert!(rem.is_empty(), "anchor PEM has trailing garbage");
+ assert!(
+ pem.label == PEM_CERTIFICATE_LABEL,
+ "PEM does not contain a certificate: '{:?}'",
+ pem.label
+ );
+ pem
+ }
+ err => panic!("failed to decode anchor PEM: {:?}", err),
+ };
+
+ pem.contents.to_vec()
+ };
+}
+
+/// Quote validity policy.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct QuotePolicy {
+ /// Whether IAS quotes are disabled and will always be rejected.
+ #[cbor(optional)]
+ pub disabled: bool,
+
+ /// Allowed quote statuses.
+ ///
+ /// Note: QuoteOK and QuoteSwHardeningNeeded are ALWAYS allowed, and do not need to be
+ /// specified.
+ #[cbor(optional)]
+ pub allowed_quote_statuses: Vec<i64>, // TODO: Define ISVEnclaveQuoteStatus type.
+
+ /// List of blocked platform EPID group IDs.
+ #[cbor(optional)]
+ pub gid_blacklist: Vec<u32>,
+
+ /// The minimum TCB evaluation data number that should be accepted.
+ #[cbor(optional)]
+ pub min_tcb_evaluation_data_number: u32,
+}
+
+/// Decoded quote body.
+#[derive(Default, Debug)]
+struct QuoteBody {
+ version: u16,
+ signature_type: u16,
+ gid: u32,
+ isv_svn_qe: u16,
+ isv_svn_pce: u16,
+ basename: [u8; 32],
+ report_body: Report,
+}
+
+#[allow(clippy::unused_io_amount)]
+impl QuoteBody {
+ /// Decode quote body.
+ fn decode(quote_body: &[u8]) -> Result<QuoteBody> {
+ let mut reader = Cursor::new(quote_body);
+ let mut quote_body: QuoteBody = QuoteBody::default();
+
+ // TODO: Should we ensure that reserved bytes are all zero?
+
+ // Quote body.
+ quote_body.version = reader.read_u16::<LittleEndian>()?;
+ quote_body.signature_type = reader.read_u16::<LittleEndian>()?;
+ quote_body.gid = reader.read_u32::<LittleEndian>()?;
+ quote_body.isv_svn_qe = reader.read_u16::<LittleEndian>()?;
+ quote_body.isv_svn_pce = reader.read_u16::<LittleEndian>()?;
+ reader.seek(SeekFrom::Current(4))?; // 4 reserved bytes.
+ reader.read_exact(&mut quote_body.basename)?;
+
+ // Report body.
+ let mut report_buf = vec![0; Report::UNPADDED_SIZE];
+ reader.read(&mut report_buf)?;
+ quote_body.report_body = match Report::try_copy_from(&report_buf) {
+ Some(r) => r,
+ None => return Err(AVRError::MalformedReportBody.into()),
+ };
+
+ Ok(quote_body)
+ }
+}
+
+/// Attestation verification report.
+#[derive(Debug, Default, Clone, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct AVR {
+ pub body: Vec<u8>,
+ pub signature: Vec<u8>,
+ pub certificate_chain: Vec<u8>,
+}
+
+/// Parsed AVR body.
+#[derive(Debug, Clone)]
+pub(crate) struct ParsedAVR {
+ body: serde_json::Value,
+}
+
+impl ParsedAVR {
+ pub(crate) fn new(avr: &AVR) -> Result<Self> {
+ let body = match serde_json::from_slice(&avr.body) {
+ Ok(avr_body) => avr_body,
+ _ => return Err(AVRError::MalformedReportBody.into()),
+ };
+ Ok(Self { body })
+ }
+
+ fn isv_enclave_quote_status(&self) -> Result<String> {
+ match self.body["isvEnclaveQuoteStatus"].as_str() {
+ Some(status) => Ok(status.to_string()),
+ None => Err(AVRError::MissingQuoteStatus.into()),
+ }
+ }
+
+ fn isv_enclave_quote_body(&self) -> Result<String> {
+ match self.body["isvEnclaveQuoteBody"].as_str() {
+ Some(quote_body) => Ok(quote_body.to_string()),
+ None => Err(AVRError::MissingQuoteBody.into()),
+ }
+ }
+
+ fn tcb_evaluation_data_number(&self) -> Result<u32> {
+ match self.body["tcbEvaluationDataNumber"].as_u64() {
+ None => Ok(0),
+ Some(eval_num) if eval_num > u32::MAX.into() => {
+ Err(AVRError::TCBEvaluationDataNumberInvalid.into())
+ }
+ Some(eval_num) => Ok(eval_num as u32),
+ }
+ }
+
+ fn timestamp(&self) -> Result<i64> {
+ let timestamp = match self.body["timestamp"].as_str() {
+ Some(timestamp) => timestamp,
+ None => {
+ return Err(AVRError::MissingTimestamp.into());
+ }
+ };
+ parse_avr_timestamp(timestamp)
+ }
+}
+
+/// Verify attestation report.
+pub fn verify(avr: &AVR, policy: &QuotePolicy) -> Result<VerifiedQuote> {
+ if policy.disabled {
+ return Err(AVRError::Disabled.into());
+ }
+
+ let unsafe_skip_avr_verification = option_env!("OASIS_UNSAFE_SKIP_AVR_VERIFY").is_some();
+ let unsafe_lax_avr_verification = option_env!("OASIS_UNSAFE_LAX_AVR_VERIFY").is_some();
+
+ // Get the time.
+ let timestamp_now = insecure_posix_time();
+
+ // Verify IAS signature.
+ if !unsafe_skip_avr_verification {
+ validate_avr_signature(
+ &avr.certificate_chain,
+ &avr.body,
+ &avr.signature,
+ timestamp_now as u64,
+ )?;
+ }
+
+ // Parse AV report body.
+ let avr_body = ParsedAVR::new(avr)?;
+
+ // Check timestamp, reject if report is too old.
+ let timestamp = avr_body.timestamp()?;
+ if !timestamp_is_fresh(timestamp_now, timestamp) {
+ return Err(AVRError::TimestampOutOfRange.into());
+ }
+
+ let quote_status = avr_body.isv_enclave_quote_status()?;
+ match quote_status.as_str() {
+ "OK" | "SW_HARDENING_NEEDED" => {}
+ "GROUP_OUT_OF_DATE" | "CONFIGURATION_NEEDED" | "CONFIGURATION_AND_SW_HARDENING_NEEDED" => {
+ if !unsafe_lax_avr_verification {
+ return Err(AVRError::QuoteStatusInvalid {
+ status: quote_status.to_owned(),
+ }
+ .into());
+ }
+ }
+ _ => {
+ return Err(AVRError::QuoteStatusInvalid {
+ status: quote_status.to_owned(),
+ }
+ .into());
+ }
+ };
+
+ let quote_body = avr_body.isv_enclave_quote_body()?;
+ let quote_body = match BASE64_STANDARD.decode(quote_body) {
+ Ok(quote_body) => quote_body,
+ _ => return Err(AVRError::MalformedQuote.into()),
+ };
+ let quote_body = match QuoteBody::decode("e_body) {
+ Ok(quote_body) => quote_body,
+ _ => return Err(AVRError::MalformedQuote.into()),
+ };
+
+ // Verify EPID GID not blacklisted.
+ if policy
+ .gid_blacklist
+ .iter()
+ .any(|gid| gid == "e_body.gid)
+ {
+ return Err(AVRError::BlacklistedGID.into());
+ }
+
+ // Disallow debug enclaves, if we are in production environment and disallow production enclaves,
+ // if we are in debug environment.
+ let is_debug = quote_body
+ .report_body
+ .attributes
+ .flags
+ .contains(AttributesFlags::DEBUG);
+ let allow_debug = option_env!("OASIS_UNSAFE_ALLOW_DEBUG_ENCLAVES").is_some();
+ if is_debug && !allow_debug {
+ return Err(AVRError::DebugEnclave.into());
+ } else if !is_debug && allow_debug {
+ return Err(AVRError::ProductionEnclave.into());
+ }
+
+ // If the minimum TCB evaluation data number is present in the policy,
+ // then the report's shouldn't be too low.
+ if avr_body.tcb_evaluation_data_number()? < policy.min_tcb_evaluation_data_number {
+ return Err(AVRError::TCBEvaluationDataNumberInvalid.into());
+ }
+
+ // Force-ratchet the clock forward, to at least the time in the AVR.
+ update_insecure_posix_time(timestamp);
+
+ Ok(VerifiedQuote {
+ report_data: quote_body.report_body.reportdata.to_vec(),
+ identity: EnclaveIdentity {
+ mr_enclave: MrEnclave::from(quote_body.report_body.mrenclave.to_vec()),
+ mr_signer: MrSigner::from(quote_body.report_body.mrsigner.to_vec()),
+ },
+ timestamp,
+ })
+}
+
+fn parse_avr_timestamp(timestamp: &str) -> Result<i64> {
+ let timestamp_unix = match NaiveDateTime::parse_from_str(timestamp, IAS_TS_FMT) {
+ Ok(timestamp) => timestamp.and_utc().timestamp(),
+ _ => return Err(AVRError::MalformedTimestamp.into()),
+ };
+ Ok(timestamp_unix)
+}
+
+fn validate_avr_signature(
+ cert_chain: &[u8],
+ message: &[u8],
+ signature: &[u8],
+ unix_time: u64,
+) -> Result<()> {
+ // WARNING: This is the entirely wrong way to validate a certificate
+ // chain as it does not come close to implementing anything resembling
+ // what is specified in RFC 5280 6.1. There probably should be a CRL
+ // check here as well, now that I think about it.
+ //
+ // The main assumptions made about how exactly the signing key is
+ // certified/distributed, and the AVR is signed are based on the
+ // following documentation:
+ //
+ // * 4.2.2 Report Signature:
+ // * "The Attestation Verification Report is cryptographically
+ // signed by Report Signing Key (owned by the Attestation
+ // Service) using the RSA-SHA256 algorithm."
+ // * 4.2.3 Report Signing Certificate Chain:
+ // * "The public part of Report Key is distributed in the form
+ // of an x.509 digital certificate called Attestation Report
+ // Signing Certificate. It is a leaf certificate issued by
+ // the Attestation Report Signing CA Certificate"
+ // * "A PEM-encoded certificate chain consisting of Attestation
+ // Report Signing Certificate and Attestation Report Signing
+ // CA Certificate is returned..."
+ //
+ // See: "Attestation Service for Intel(R) Software Guard Extensions
+ // (Intel(R) SGX): API Documentation" (Revision: 6.0)
+
+ // Decode the certificate chain from percent encoded PEM to DER.
+ let raw_pem = percent_encoding::percent_decode(cert_chain).decode_utf8()?;
+ let mut cert_ders = Vec::new();
+ for pem in pem::Pem::iter_from_buffer(raw_pem.as_bytes()) {
+ let pem = match pem {
+ Ok(p) => p,
+ Err(_) => return Err(AVRError::MalformedCertificatePEM.into()),
+ };
+ if pem.label != PEM_CERTIFICATE_LABEL {
+ return Err(AVRError::MalformedCertificatePEM.into());
+ }
+ cert_ders.push(pem.contents);
+ }
+
+ // IAS per the API will only ever send two certificates.
+ if cert_ders.len() != 2 {
+ return Err(AVRError::ChainNotTwoCertificates.into());
+ }
+
+ // Convert our timestamp to something that can be used to check
+ // certificate expiration.
+ let time = ASN1Time::from_timestamp(unix_time as i64)?;
+
+ // Attestation Report Signing CA Certificate:
+ //
+ // Ensure that it matches the hard-coded copy, and decode it, so
+ // that the expiration can be validated and the public key can
+ // be used to verify the leaf certificate's signature.
+ //
+ // This could be more paranoid and check that the cert doesn't
+ // have trailing garbage, the usage is correct, etc, but we can
+ // take it as a matter of faith that it is well-formed since
+ // it is the same as the hard-coded one.
+ //
+ // TODO/perf: In theory this can be done once and only once, but
+ // the borrow checker thwarted my attempts to initialize a tuple
+ // containing a X509Certificate and Pem via lazy_static.
+ if cert_ders[1] != *IAS_TRUST_ANCHOR {
+ return Err(anyhow!("AVR certificate chain trust anchor mismatch"));
+ }
+ let anchor = match parse_x509_certificate(&cert_ders[1]) {
+ Ok((_, cert)) => cert,
+ Err(_) => return Err(AVRError::MalformedCertificateDER.into()),
+ };
+ if !anchor.validity().is_valid_at(time) {
+ return Err(AVRError::ExpiredCertificate.into());
+ }
+ let anchor_pk = extract_certificate_rsa_public_key(&anchor)?;
+ if !check_certificate_rsa_signature(&anchor, &anchor_pk) {
+ // The hard-coded cert is self-signed. This will need to be
+ // changed if it ever isn't.
+ return Err(anyhow!(
+ "AVR certificate chain trust anchor has invalid signature"
+ ));
+ }
+ if !anchor.tbs_certificate.is_ca() {
+ return Err(anyhow!("AVR certificate trust anchor is not a CA"));
+ }
+
+ // Attestation Report Signing Certificate (leaf):
+ //
+ // Decode the certificate, ensure that it appears to be sensible,
+ // and then pull out the public key that presumably signs the AVR.
+ let leaf = match parse_x509_certificate(&cert_ders[0]) {
+ Ok((rem, cert)) => {
+ if !rem.is_empty() {
+ return Err(AVRError::MalformedCertificateDER.into());
+ }
+ cert
+ }
+ Err(_) => return Err(AVRError::MalformedCertificateDER.into()),
+ };
+ if !check_certificate_rsa_signature(&leaf, &anchor_pk) {
+ return Err(anyhow!("invalid leaf certificate signature"));
+ }
+
+ if !leaf.validity().is_valid_at(time) {
+ return Err(AVRError::ExpiredCertificate.into());
+ }
+ match leaf.tbs_certificate.key_usage()? {
+ Some(ku) => {
+ if !ku.value.digital_signature() {
+ return Err(anyhow!("leaf certificate can't sign"));
+ }
+ }
+ None => {
+ return Err(anyhow!("leaf cert missing key usage"));
+ }
+ }
+
+ // Validate the actual signature.
+ let leaf_pk = extract_certificate_rsa_public_key(&leaf)?;
+ let scheme = Pkcs1v15Sign::new::<sha2::Sha256>();
+ let digest = Sha256::new().chain(message).finalize();
+ let signature = BASE64_STANDARD.decode(signature)?;
+ leaf_pk
+ .verify(scheme, &digest, &signature)
+ .map_err(|_| AVRError::InvalidSignature)?;
+ Ok(())
+}
+
+fn extract_certificate_rsa_public_key(cert: &X509Certificate) -> Result<RsaPublicKey> {
+ let cert_spki = &cert.tbs_certificate.subject_pki;
+ if cert_spki.algorithm.algorithm != OID_PKCS1_RSAENCRYPTION {
+ return Err(anyhow!("invalid certificate public key algorithm"));
+ }
+
+ match RsaPublicKey::from_pkcs1_der(&cert_spki.subject_public_key.data) {
+ Ok(pk) => Ok(pk),
+ Err(err) => Err(anyhow!("invalid certificate public key: {:?}", err)),
+ }
+}
+
+fn check_certificate_rsa_signature(cert: &X509Certificate, public_key: &RsaPublicKey) -> bool {
+ if cert.signature_algorithm.algorithm != OID_PKCS1_SHA256WITHRSA {
+ return false;
+ }
+ let scheme = Pkcs1v15Sign::new::<sha2::Sha256>();
+ let digest = Sha256::new()
+ .chain(cert.tbs_certificate.as_ref())
+ .finalize();
+
+ public_key
+ .verify(scheme, &digest, &cert.signature_value.data)
+ .is_ok()
+}
+
+/// Return true iff the (POXIX) timestamp is considered "fresh" for the purposes
+/// of a cached AVR, given the current time.
+pub(crate) fn timestamp_is_fresh(now: i64, timestamp: i64) -> bool {
+ (now - timestamp).abs() < 60 * 60 * 24
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ const IAS_CERT_CHAIN: &[u8] =
+ include_bytes!("../../../testdata/avr_certificates_urlencoded.pem");
+
+ #[test]
+ fn test_validate_avr_signature() {
+ const MSG: &[u8] = include_bytes!("../../../testdata/avr_body_group_out_of_date.json");
+ const SIG: &[u8] = include_bytes!("../../../testdata/avr_signature_group_out_of_date.sig");
+ const SIG_AT: u64 = 1522447346; // 2018-03-30T22:02:26
+
+ // Positive test.
+ let result = validate_avr_signature(IAS_CERT_CHAIN, MSG, SIG, SIG_AT);
+ assert!(result.is_ok());
+
+ // Invalid timestamp.
+ let result = validate_avr_signature(IAS_CERT_CHAIN, MSG, SIG, 0);
+ assert!(result.is_err());
+
+ // Bad message.
+ let bad_msg: &mut [u8] = &mut MSG.to_owned();
+ bad_msg[0] ^= 0x23;
+ let result = validate_avr_signature(IAS_CERT_CHAIN, bad_msg, SIG, SIG_AT);
+ assert!(result.is_err());
+
+ // Bad signature.
+ let bad_sig = BASE64_STANDARD.decode(SIG).unwrap();
+ let bad_sig = &mut bad_sig.to_owned();
+ bad_sig[0] ^= 0x42;
+ let bad_sig = BASE64_STANDARD.encode(bad_sig);
+ let result = validate_avr_signature(IAS_CERT_CHAIN, MSG, bad_sig.as_bytes(), SIG_AT);
+ assert!(result.is_err());
+
+ // Test timestamp validation while we're at it.
+ let timestamp = parse_avr_timestamp("2018-03-30T22:02:26.123456").unwrap();
+ assert_eq!(timestamp, SIG_AT as i64);
+ }
+
+ #[test]
+ fn test_decode_avr_v4() {
+ const AVR: &[u8] = include_bytes!(
+ "../../../../go/common/sgx/ias/testdata/avr_v4_body_sw_hardening_needed.json"
+ );
+ const SIG: &[u8] = include_bytes!(
+ "../../../../go/common/sgx/ias/testdata/avr_v4_body_sw_hardening_needed.sig"
+ );
+ const SIG_AT: u64 = 1589188875; // 2020-05-11T09:21:15
+ const ID: &str = "323119119247496566074708526703373820736";
+ const NONCE: &str = "biNMqBAuTPF2hp/0fXa4P3splRkLHJf0";
+ const EPID_PSEUDONYM: &str = "uAFRLXADu90LsPq9Btgx8MWUPOzmDHE51pwLlUlU3hzFUk2EmvWpF6fZsyokOVkQUJ0UwZk0nCF8XPaCcSmLwqXAzLa+n/K7TdwlxKofEyTgG8da8mmrShNoFw3BSD74wSA4aAc753IfrbnnmuYk00lkmSUOTzqsqHlAORcweqg=";
+
+ let result = validate_avr_signature(IAS_CERT_CHAIN, AVR, SIG, SIG_AT);
+ assert!(result.is_ok());
+
+ let raw_avr = AVR {
+ body: AVR.to_vec(),
+ signature: SIG.to_vec(),
+ certificate_chain: IAS_CERT_CHAIN.to_vec(),
+ };
+ let avr = ParsedAVR::new(&raw_avr).expect("parsing raw AVR should succeed");
+ assert_eq!(avr.body["id"].as_str().expect("id should be present"), ID);
+ assert_eq!(
+ avr.timestamp().expect("timestamp should exist"),
+ SIG_AT as i64
+ );
+ assert_eq!(
+ avr.body["version"].as_u64().expect("version should exist"),
+ 4
+ );
+ assert_eq!(
+ avr.isv_enclave_quote_status()
+ .expect("isv enclave quote status should exist"),
+ "SW_HARDENING_NEEDED"
+ );
+
+ let isv_enclave_quote_body = BASE64_STANDARD
+ .decode(
+ avr.isv_enclave_quote_body()
+ .expect("isv enclave quote body should exist"),
+ )
+ .expect("decoding isv enclave quote body should succeed");
+ assert_eq!(isv_enclave_quote_body.len(), 432);
+ assert!(avr.body.get("revocationReason").is_none());
+ assert!(avr.body.get("pseManifestStatus").is_none());
+ assert!(avr.body.get("pseManifestHash").is_none());
+ assert!(avr.body.get("platformInfoBlob").is_none());
+ assert_eq!(
+ avr.body["nonce"].as_str().expect("nonce should exist"),
+ NONCE
+ );
+ assert_eq!(
+ avr.body["epidPseudonym"]
+ .as_str()
+ .expect("epid pseudonym should exist"),
+ EPID_PSEUDONYM
+ );
+ assert_eq!(
+ avr.body["advisoryURL"]
+ .as_str()
+ .expect("advisory URL should exist"),
+ "https://security-center.intel.com"
+ );
+ for (avr_id, known_id) in avr.body["advisoryIDs"]
+ .as_array()
+ .expect("advisory ID array should exist")
+ .iter()
+ .zip(["INTEL-SA-00334"])
+ {
+ assert_eq!(
+ avr_id.as_str().expect("advisory ID should be a string"),
+ known_id
+ );
+ }
+ }
+
+ #[test]
+ fn test_decode_avr_v5() {
+ const AVR: &[u8] = include_bytes!(
+ "../../../../go/common/sgx/ias/testdata/avr_v5_body_sw_hardening_needed.json"
+ );
+ const SIG: &[u8] = include_bytes!(
+ "../../../../go/common/sgx/ias/testdata/avr_v5_body_sw_hardening_needed.sig"
+ );
+ const SIG_AT: u64 = 1695829918; // 2023-09-27T15:51:58
+ const ID: &str = "325753020347524304899139732345489823748";
+ const EPID_PSEUDONYM: &str = "twLvZuBD1sOHsNPsHGbZOVlGh9rXw9XzVQTVKUuvsqypw0iWcFKwR7aNoHmDSoeFc/+pH6LLCI2bQBKx/ygwXphePD4GTTRwBi9EIBFRlURTk4p4NosbA7xcCG4hRuCDaEKPtAX6XHjNKEvWA+4f1aAfD7jwOtGAzHeaqBldaD8=";
+
+ let result = validate_avr_signature(IAS_CERT_CHAIN, AVR, SIG, SIG_AT);
+ assert!(result.is_ok());
+
+ let raw_avr = AVR {
+ body: AVR.to_vec(),
+ signature: SIG.to_vec(),
+ certificate_chain: IAS_CERT_CHAIN.to_vec(),
+ };
+ let avr = ParsedAVR::new(&raw_avr).expect("parsing raw AVR should succeed");
+ assert_eq!(avr.body["id"].as_str().expect("id should be present"), ID);
+ assert_eq!(
+ avr.timestamp().expect("timestamp should exist"),
+ SIG_AT as i64
+ );
+ assert_eq!(
+ avr.body["version"].as_u64().expect("version should exist"),
+ 5
+ );
+ assert_eq!(
+ avr.isv_enclave_quote_status()
+ .expect("isv enclave quote status should exist"),
+ "SW_HARDENING_NEEDED"
+ );
+
+ let isv_enclave_quote_body = BASE64_STANDARD
+ .decode(
+ avr.isv_enclave_quote_body()
+ .expect("isv enclave quote body should exist"),
+ )
+ .expect("decoding isv enclave quote body should succeed");
+ assert_eq!(isv_enclave_quote_body.len(), 432);
+ assert!(avr.body.get("revocationReason").is_none());
+ assert!(avr.body.get("pseManifestStatus").is_none());
+ assert!(avr.body.get("pseManifestHash").is_none());
+ assert!(avr.body.get("platformInfoBlob").is_none());
+ assert!(avr.body.get("nonce").is_none());
+ assert_eq!(
+ avr.body["epidPseudonym"]
+ .as_str()
+ .expect("epid pseudonym should exist"),
+ EPID_PSEUDONYM
+ );
+ assert_eq!(
+ avr.body["advisoryURL"]
+ .as_str()
+ .expect("advisory URL should exist"),
+ "https://security-center.intel.com"
+ );
+ for (avr_id, known_id) in avr.body["advisoryIDs"]
+ .as_array()
+ .expect("advisory ID array should exist")
+ .iter()
+ .zip(["INTEL-SA-00334", "INTEL-SA-00615"])
+ {
+ assert_eq!(
+ avr_id.as_str().expect("advisory ID should be a string"),
+ known_id
+ );
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +
//! SGX-specific functionality.
+
+pub mod egetkey;
+pub mod ias;
+pub mod pcs;
+pub mod seal;
+
+use anyhow::Result;
+use chrono::prelude::*;
+
+use crate::common::time::{insecure_posix_time, update_insecure_posix_time};
+
+/// Maximum age of a quote from the viewpoint of the enclave.
+pub const MAX_QUOTE_AGE: i64 = 24 * 60 * 60; // 24 hours
+
+impl_bytes!(MrEnclave, 32, "Enclave hash (MRENCLAVE).");
+impl_bytes!(MrSigner, 32, "Enclave signer hash (MRSIGNER).");
+
+/// Enclave identity.
+#[derive(Debug, Default, Clone, Hash, Eq, PartialEq, cbor::Encode, cbor::Decode)]
+pub struct EnclaveIdentity {
+ pub mr_enclave: MrEnclave,
+ pub mr_signer: MrSigner,
+}
+
+impl EnclaveIdentity {
+ /// Enclave identity for the current enclave (when available).
+ pub fn current() -> Option<Self> {
+ cfg_if::cfg_if! {
+ if #[cfg(target_env = "sgx")] {
+ // SGX builds, generate actual report.
+ let report = sgx_isa::Report::for_self();
+ Some(EnclaveIdentity {
+ mr_enclave: MrEnclave(report.mrenclave),
+ mr_signer: MrSigner(report.mrsigner),
+ })
+ } else if #[cfg(feature = "tdx")] {
+ // TDX builds, generate TD report.
+ let report = crate::common::tdx::report::get_report(&[0; 64]).expect("failed to get report");
+ Some(report.as_enclave_identity())
+ } else if #[cfg(feature = "debug-mock-sgx")] {
+ // Non-SGX builds, mock SGX enabled, generate mock report. The mock MRENCLAVE is
+ // expected to be passed in by the mock SGX runner.
+ Some(Self::fortanix_test(std::env::var("OASIS_MOCK_MRENCLAVE").unwrap().parse().unwrap()))
+ } else {
+ // Non-SGX builds, mock SGX disabled, no enclave identity.
+ None
+ }
+ }
+ }
+
+ /// Enclave identity using a test MRSIGNER from Fortanix with a well-known private key.
+ pub fn fortanix_test(mr_enclave: MrEnclave) -> Self {
+ Self {
+ mr_enclave,
+ mr_signer: MrSigner::from(
+ "9affcfae47b848ec2caf1c49b4b283531e1cc425f93582b36806e52a43d78d1a",
+ ),
+ }
+ }
+}
+
+/// An unverified SGX remote attestation quote, depending on the attestation scheme.
+#[derive(Clone, Debug, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub enum Quote {
+ #[cbor(rename = "ias")]
+ Ias(ias::AVR),
+
+ #[cbor(rename = "pcs")]
+ Pcs(pcs::QuoteBundle),
+}
+
+impl Quote {
+ /// Verify the remote attestation quote.
+ pub fn verify(&self, policy: &QuotePolicy) -> Result<VerifiedQuote> {
+ let mut verified_quote = match self {
+ Quote::Ias(avr) => ias::verify(avr, &policy.ias.clone().unwrap_or_default()),
+ Quote::Pcs(qb) => {
+ let now = Utc.timestamp_opt(insecure_posix_time(), 0).unwrap();
+ Ok(qb.verify(&policy.pcs.clone().unwrap_or_default(), now)?)
+ }
+ }?;
+
+ // Force-ratchet the clock forward, to at least the time in the verified quote.
+ update_insecure_posix_time(verified_quote.timestamp);
+ verified_quote.timestamp = insecure_posix_time();
+
+ Ok(verified_quote)
+ }
+
+ /// Whether the quote should be considered fresh.
+ pub fn is_fresh(&self, now: i64, ts: i64, policy: &QuotePolicy) -> bool {
+ // Check general freshness requirement.
+ if (now - ts).abs() > MAX_QUOTE_AGE {
+ return false;
+ }
+
+ // Check quote-specific expiration policy.
+ match self {
+ Quote::Ias(_) => true, // No additional checks for IAS quotes.
+ Quote::Pcs(_) => !policy.pcs.clone().unwrap_or_default().is_expired(now, ts),
+ }
+ }
+}
+
+/// Quote validity policy.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct QuotePolicy {
+ #[cbor(rename = "ias")]
+ pub ias: Option<ias::QuotePolicy>,
+
+ #[cbor(rename = "pcs")]
+ pub pcs: Option<pcs::QuotePolicy>,
+}
+
+/// A remote attestation quote that has undergone verification.
+#[derive(Debug, Default, Clone)]
+pub struct VerifiedQuote {
+ pub report_data: Vec<u8>,
+ pub identity: EnclaveIdentity,
+ pub timestamp: i64,
+}
+
+/// Generate a report for the given target enclave.
+#[cfg(target_env = "sgx")]
+pub fn report_for(target_info: &sgx_isa::Targetinfo, report_data: &[u8; 64]) -> sgx_isa::Report {
+ sgx_isa::Report::for_target(target_info, report_data)
+}
+
+/// Generate a report for the given target enclave.
+#[cfg(not(target_env = "sgx"))]
+pub fn report_for(_target_info: &sgx_isa::Targetinfo, report_data: &[u8; 64]) -> sgx_isa::Report {
+ let ei = EnclaveIdentity::current().expect("mock enclave identity not available");
+
+ // In non-SGX mode, reports are mocked.
+ sgx_isa::Report {
+ mrenclave: ei.mr_enclave.into(),
+ mrsigner: ei.mr_signer.into(),
+ cpusvn: [8, 9, 14, 13, 255, 255, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+ attributes: sgx_isa::Attributes {
+ flags: sgx_isa::AttributesFlags::INIT
+ | sgx_isa::AttributesFlags::DEBUG
+ | sgx_isa::AttributesFlags::MODE64BIT,
+ xfrm: 3,
+ },
+ reportdata: *report_data,
+ ..Default::default()
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +
use std::ffi::CString;
+
+use mbedtls::{alloc::List as MbedtlsList, x509::certificate::Certificate};
+
+/// Intel's PCS signing root certificate (PEM-encoded).
+pub const PCS_TRUST_ROOT_CERT: &str = r#"-----BEGIN CERTIFICATE-----
+MIICjzCCAjSgAwIBAgIUImUM1lqdNInzg7SVUr9QGzknBqwwCgYIKoZIzj0EAwIw
+aDEaMBgGA1UEAwwRSW50ZWwgU0dYIFJvb3QgQ0ExGjAYBgNVBAoMEUludGVsIENv
+cnBvcmF0aW9uMRQwEgYDVQQHDAtTYW50YSBDbGFyYTELMAkGA1UECAwCQ0ExCzAJ
+BgNVBAYTAlVTMB4XDTE4MDUyMTEwNDUxMFoXDTQ5MTIzMTIzNTk1OVowaDEaMBgG
+A1UEAwwRSW50ZWwgU0dYIFJvb3QgQ0ExGjAYBgNVBAoMEUludGVsIENvcnBvcmF0
+aW9uMRQwEgYDVQQHDAtTYW50YSBDbGFyYTELMAkGA1UECAwCQ0ExCzAJBgNVBAYT
+AlVTMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEC6nEwMDIYZOj/iPWsCzaEKi7
+1OiOSLRFhWGjbnBVJfVnkY4u3IjkDYYL0MxO4mqsyYjlBalTVYxFP2sJBK5zlKOB
+uzCBuDAfBgNVHSMEGDAWgBQiZQzWWp00ifODtJVSv1AbOScGrDBSBgNVHR8ESzBJ
+MEegRaBDhkFodHRwczovL2NlcnRpZmljYXRlcy50cnVzdGVkc2VydmljZXMuaW50
+ZWwuY29tL0ludGVsU0dYUm9vdENBLmRlcjAdBgNVHQ4EFgQUImUM1lqdNInzg7SV
+Ur9QGzknBqwwDgYDVR0PAQH/BAQDAgEGMBIGA1UdEwEB/wQIMAYBAf8CAQEwCgYI
+KoZIzj0EAwIDSQAwRgIhAOW/5QkR+S9CiSDcNoowLuPRLsWGf/Yi7GSX94BgwTwg
+AiEA4J0lrHoMs+Xo5o/sX6O9QWxHRAvZUGOdRQ7cvqRXaqI=
+-----END CERTIFICATE-----"#;
+
+lazy_static::lazy_static! {
+ /// Intel's PCS signing root certificate.
+ pub static ref PCS_TRUST_ROOT: MbedtlsList<Certificate> = {
+ let mut cert_chain = MbedtlsList::new();
+ let raw_cert = CString::new(PCS_TRUST_ROOT_CERT.as_bytes()).unwrap();
+ let cert = Certificate::from_pem(raw_cert.as_bytes_with_nul()).unwrap();
+ cert_chain.push(cert);
+
+ cert_chain
+ };
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +
use chrono::Duration;
+
+// Required values of various TCB fields.
+pub const REQUIRED_TCB_INFO_VERSION: u32 = 3;
+pub const REQUIRED_QE_IDENTITY_VERSION: u32 = 2;
+
+pub const DEFAULT_MIN_TCB_EVALUATION_DATA_NUMBER: u32 = 12; // As of 2022-08-01.
+pub const DEFAULT_TCB_VALIDITY_PERIOD: Duration = Duration::try_days(30).unwrap();
+
+// PCS timestamp format.
+pub const PCS_TS_FMT: &str = "%FT%T%.9fZ";
+
+// OIDs for PCK X509 certificate extensions.
+pub const PCK_SGX_EXTENSIONS_OID: &[u64] = &[1, 2, 840, 113741, 1, 13, 1];
+pub const PCK_SGX_EXTENSIONS_FMSPC_OID: &[u64] = &[1, 2, 840, 113741, 1, 13, 1, 4];
+pub const PCK_SGX_EXTENSIONS_TCB_OID: &[u64] = &[1, 2, 840, 113741, 1, 13, 1, 2];
+
+pub const QE_VENDOR_ID_INTEL: [u8; 16] = [
+ 0x93, 0x9a, 0x72, 0x33, 0xf7, 0x9c, 0x4c, 0xa9, 0x94, 0x0a, 0x0d, 0xb3, 0x95, 0x7f, 0x06, 0x07,
+];
+
+pub const TDX_MRSIGNER_INTEL: [u8; 48] = [0; 48];
+
+pub const QUOTE_HEADER_LEN: usize = 48;
+pub const ECDSA_P256_SIGNATURE_LEN: usize = 64;
+pub const ECDSA_P256_PUBLIC_KEY_LEN: usize = 64;
+pub const QE_VENDOR_ID_LEN: usize = 16;
+pub const QE_USER_DATA_LEN: usize = 20;
+pub const SGX_REPORT_BODY_LEN: usize = 384;
+pub const TDX_REPORT_BODY_LEN: usize = 584;
+pub const CPUSVN_LEN: usize = 16;
+
+pub const QUOTE_VERSION_3: u16 = 3;
+pub const QUOTE_VERSION_4: u16 = 4;
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +
//! Intel Provisioning Certification Services (PCS) quote handling.
+
+mod certificates;
+mod constants;
+mod policy;
+mod quote;
+mod report;
+mod tcb;
+mod utils;
+
+/// Possible errors returned by this module.
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+ #[error("unsupported QE vendor")]
+ UnsupportedQEVendor,
+ #[error("unsupported attestation key type")]
+ UnsupportedAttestationKeyType,
+ #[error("unsupported TEE type")]
+ UnsupportedTeeType,
+ #[error("failed to parse quote: {0}")]
+ QuoteParseError(String),
+ #[error("failed to verify quote: {0}")]
+ VerificationFailed(String),
+ #[error("unexpected certificate chain")]
+ UnexpectedCertificateChain,
+ #[error("unexpected certification data")]
+ UnexpectedCertificationData,
+ #[error("malformed certification data")]
+ MalformedCertificationData,
+ #[error("PCK is malformed")]
+ MalformedPCK,
+ #[error("failed to parse TCB bundle: {0}")]
+ TCBParseError(anyhow::Error),
+ #[error("TCB verification failed")]
+ TCBVerificationFailed,
+ #[error("TCB is expired or not yet valid")]
+ TCBExpired,
+ #[error("TCB is out of date")]
+ TCBOutOfDate,
+ #[error("TCB does not match the quote")]
+ TCBMismatch,
+ #[error("TCB evaluation data number is invalid")]
+ TCBEvaluationDataNumberInvalid,
+ #[error("FMSPC is blacklisted")]
+ BlacklistedFMSPC,
+ #[error("QE report is malformed")]
+ MalformedQEReport,
+ #[error("report is malformed")]
+ MalformedReport,
+ #[error("debug enclaves not allowed")]
+ DebugEnclave,
+ #[error("production enclaves not allowed")]
+ ProductionEnclave,
+ #[error("TEE type not allowed by policy")]
+ TeeTypeNotAllowed,
+ #[error("TDX module not allowed by policy")]
+ TdxModuleNotAllowed,
+ #[error("PCS quotes are disabled by policy")]
+ Disabled,
+ #[error(transparent)]
+ Other(#[from] anyhow::Error),
+}
+
+pub use policy::{QuotePolicy, TdxModulePolicy, TdxQuotePolicy};
+pub use quote::{Quote, QuoteBundle};
+pub use report::{td_enclave_identity, TdAttributes, TdReport};
+pub use tcb::TCBBundle;
+
+#[cfg(test)]
+mod tests {
+ use chrono::prelude::*;
+
+ use super::*;
+
+ #[test]
+ fn test_quote_v3_ecdsa_p256_pck_certificatechain() {
+ const RAW_QUOTE: &[u8] =
+ include_bytes!("../../../../testdata/quote_v3_ecdsa_p256_pck_chain.bin");
+ const RAW_TCB_INFO: &[u8] =
+ include_bytes!("../../../../testdata/tcb_info_v3_fmspc_00606A000000.json"); // From PCS V4 response.
+ const RAW_CERTS: &[u8] =
+ include_bytes!("../../../../testdata/tcb_info_v3_fmspc_00606A000000_certs.pem"); // From PCS V4 response (TCB-Info-Issuer-Chain header).
+ const RAW_QE_IDENTITY: &[u8] = include_bytes!("../../../../testdata/qe_identity_v2.json"); // From PCS V4 response.
+
+ let qb = QuoteBundle {
+ quote: RAW_QUOTE.to_owned(),
+ tcb: TCBBundle {
+ tcb_info: serde_json::from_slice(RAW_TCB_INFO).unwrap(),
+ qe_identity: serde_json::from_slice(RAW_QE_IDENTITY).unwrap(),
+ certificates: RAW_CERTS.to_owned(),
+ },
+ };
+
+ let now = Utc.timestamp_opt(1671497404, 0).unwrap();
+
+ let verified_quote = qb.verify(&QuotePolicy::default(), now).unwrap();
+ assert_eq!(
+ verified_quote.identity.mr_signer,
+ "9affcfae47b848ec2caf1c49b4b283531e1cc425f93582b36806e52a43d78d1a".into()
+ );
+ assert_eq!(
+ verified_quote.identity.mr_enclave,
+ "68823bc62f409ee33a32ea270cfe45d4b19a6fb3c8570d7bc186cbe062398e8f".into()
+ );
+ }
+
+ #[test]
+ fn test_quote_v4_tdx_ecdsa_p256() {
+ const RAW_QUOTE: &[u8] = include_bytes!("../../../../testdata/quote_v4_tdx_ecdsa_p256.bin");
+ const RAW_TCB_INFO: &[u8] =
+ include_bytes!("../../../../testdata/tcb_info_v3_tdx_fmspc_C0806F000000.json"); // From PCS V4 response.
+ const RAW_CERTS: &[u8] =
+ include_bytes!("../../../../testdata/tcb_info_v3_fmspc_00606A000000_certs.pem"); // From PCS V4 response (TCB-Info-Issuer-Chain header).
+ const RAW_QE_IDENTITY: &[u8] =
+ include_bytes!("../../../../testdata/qe_identity_v2_tdx2.json"); // From PCS V4 response.
+
+ let qb = QuoteBundle {
+ quote: RAW_QUOTE.to_owned(),
+ tcb: TCBBundle {
+ tcb_info: serde_json::from_slice(RAW_TCB_INFO).unwrap(),
+ qe_identity: serde_json::from_slice(RAW_QE_IDENTITY).unwrap(),
+ certificates: RAW_CERTS.to_owned(),
+ },
+ };
+
+ let now = Utc.timestamp_opt(1725263032, 0).unwrap();
+ let policy = QuotePolicy {
+ tdx: Some(TdxQuotePolicy::default()), // Allow TDX.
+ ..Default::default()
+ };
+
+ let verified_quote = qb.verify(&policy, now).unwrap();
+ assert_eq!(
+ verified_quote.identity.mr_signer,
+ "0000000000000000000000000000000000000000000000000000000000000000".into()
+ );
+ assert_eq!(
+ verified_quote.identity.mr_enclave,
+ "63d522d975f7de879a8f3368b4f32dd1e8db635f5a24b651ce8ff81705028813".into()
+ );
+
+ // Ensure TDX quote verification fails in case it is not allowed.
+ let policy = QuotePolicy {
+ tdx: None,
+ ..Default::default()
+ };
+
+ let result = qb.verify(&policy, now);
+ assert!(matches!(result, Err(Error::TeeTypeNotAllowed)));
+
+ // Ensure TDX quote verification fails in case the given TDX Module is not allowed.
+ let policy = QuotePolicy {
+ tdx: Some(TdxQuotePolicy {
+ allowed_tdx_modules: vec![TdxModulePolicy {
+ mr_seam: None,
+ mr_signer_seam: [1; 48],
+ }],
+ }),
+ ..Default::default()
+ };
+
+ let result = qb.verify(&policy, now);
+ assert!(matches!(result, Err(Error::TdxModuleNotAllowed)));
+ }
+
+ #[test]
+ fn test_quote_v4_tdx_ecdsa_p256_out_of_date() {
+ const RAW_QUOTE: &[u8] =
+ include_bytes!("../../../../testdata/quote_v4_tdx_ecdsa_p256_out_of_date.bin");
+ const RAW_TCB_INFO: &[u8] =
+ include_bytes!("../../../../testdata/tcb_info_v3_tdx_fmspc_50806F000000.json"); // From PCS V4 response.
+ const RAW_CERTS: &[u8] =
+ include_bytes!("../../../../testdata/tcb_info_v3_fmspc_00606A000000_certs.pem"); // From PCS V4 response (TCB-Info-Issuer-Chain header).
+ const RAW_QE_IDENTITY: &[u8] =
+ include_bytes!("../../../../testdata/qe_identity_v2_tdx.json"); // From PCS V4 response.
+
+ let qb = QuoteBundle {
+ quote: RAW_QUOTE.to_owned(),
+ tcb: TCBBundle {
+ tcb_info: serde_json::from_slice(RAW_TCB_INFO).unwrap(),
+ qe_identity: serde_json::from_slice(RAW_QE_IDENTITY).unwrap(),
+ certificates: RAW_CERTS.to_owned(),
+ },
+ };
+
+ let now = Utc.timestamp_opt(1687091776, 0).unwrap();
+ let policy = QuotePolicy {
+ tdx: Some(TdxQuotePolicy::default()), // Allow TDX.
+ ..Default::default()
+ };
+
+ let result = qb.verify(&policy, now);
+
+ // NOTE: The quote is out of date.
+ assert!(matches!(result, Err(Error::TCBOutOfDate)));
+ }
+
+ #[test]
+ fn test_quote_bundle_decoding() {
+ // From Go implementation.
+ const RAW_QUOTE_BUNDLE: &[u8] =
+ include_bytes!("../../../../testdata/pcs_quote_bundle.cbor");
+
+ let qb: QuoteBundle = cbor::from_slice(RAW_QUOTE_BUNDLE).unwrap();
+
+ let now = Utc.timestamp_opt(1671497404, 0).unwrap();
+
+ let verified_quote = qb.verify(&QuotePolicy::default(), now).unwrap();
+ assert_eq!(
+ verified_quote.identity.mr_signer,
+ "9affcfae47b848ec2caf1c49b4b283531e1cc425f93582b36806e52a43d78d1a".into()
+ );
+ assert_eq!(
+ verified_quote.identity.mr_enclave,
+ "68823bc62f409ee33a32ea270cfe45d4b19a6fb3c8570d7bc186cbe062398e8f".into()
+ );
+ }
+
+ #[test]
+ fn test_quote_blacklisted_fmscp() {
+ // From Go implementation.
+ const RAW_QUOTE_BUNDLE: &[u8] =
+ include_bytes!("../../../../testdata/pcs_quote_bundle.cbor");
+
+ let qb: QuoteBundle = cbor::from_slice(RAW_QUOTE_BUNDLE).unwrap();
+
+ let now = Utc.timestamp_opt(1671497404, 0).unwrap();
+ let policy = &QuotePolicy {
+ fmspc_blacklist: vec!["00606A000000".to_string()],
+ ..Default::default()
+ };
+
+ qb.verify(policy, now)
+ .expect_err("quote verification should fail for blacklisted FMSPCs");
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +
//! Quote policy.
+use super::{constants::*, report::TdReport, Error};
+
+/// Quote validity policy.
+#[derive(Clone, Debug, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct QuotePolicy {
+ /// Whether PCS quotes are disabled and will always be rejected.
+ #[cbor(optional)]
+ pub disabled: bool,
+
+ /// Validity (in days) of the TCB collateral.
+ pub tcb_validity_period: u16,
+
+ /// Minimum TCB evaluation data number that is considered to be valid. TCB bundles containing
+ /// smaller values will be invalid.
+ pub min_tcb_evaluation_data_number: u32,
+
+ /// A list of hexadecimal encoded FMSPCs specifying which processor packages and platform
+ /// instances are blocked.
+ #[cbor(optional)]
+ pub fmspc_blacklist: Vec<String>,
+
+ /// Optional TDX-specific policy. In case this is `None`, TDX quotes are disallowed.
+ #[cbor(optional)]
+ pub tdx: Option<TdxQuotePolicy>,
+}
+
+impl Default for QuotePolicy {
+ fn default() -> Self {
+ Self {
+ disabled: false,
+ tcb_validity_period: 30,
+ min_tcb_evaluation_data_number: DEFAULT_MIN_TCB_EVALUATION_DATA_NUMBER,
+ fmspc_blacklist: Vec::new(),
+ tdx: None,
+ }
+ }
+}
+
+impl QuotePolicy {
+ /// Whether the quote with timestamp `ts` is expired.
+ pub fn is_expired(&self, now: i64, ts: i64) -> bool {
+ if self.disabled {
+ return true;
+ }
+
+ now.checked_sub(ts)
+ .map(|d| d > 60 * 60 * 24 * (self.tcb_validity_period as i64))
+ .expect("quote timestamp is in the future") // This should never happen.
+ }
+}
+
+/// TDX-specific quote policy.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct TdxQuotePolicy {
+ /// Allowed TDX modules. Empty to allow ANY Intel-signed module.
+ pub allowed_tdx_modules: Vec<TdxModulePolicy>,
+}
+
+impl TdxQuotePolicy {
+ /// Verify whether the TDX policy is satisfied for the given report.
+ pub fn verify(&self, report: &TdReport) -> Result<(), Error> {
+ self.verify_tdx_module(report)?;
+ Ok(())
+ }
+
+ fn verify_tdx_module(&self, report: &TdReport) -> Result<(), Error> {
+ // If at least one TDX Module matches, then we are good.
+ for allowed_module in &self.allowed_tdx_modules {
+ if allowed_module.matches(report) {
+ return Ok(());
+ }
+ }
+
+ // No module matched. Iff the list of modules is empty, allow ANY Intel-signed module.
+ // As per the TDX specifications, MRSIGNER is all-zero for Intel.
+ if self.allowed_tdx_modules.is_empty() && report.mr_signer_seam == TDX_MRSIGNER_INTEL {
+ return Ok(());
+ }
+
+ Err(Error::TdxModuleNotAllowed)
+ }
+}
+
+/// TDX module policy.
+#[derive(Clone, Debug, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct TdxModulePolicy {
+ /// Optional allowed measurement of the TDX Module. In case it is `None`, ANY measurement is
+ /// allowed and only the signer is checked.
+ pub mr_seam: Option<[u8; 48]>,
+
+ /// Allowed signer of the TDX Module (zero for Intel).
+ pub mr_signer_seam: [u8; 48],
+}
+
+impl TdxModulePolicy {
+ /// Returns true iff the TDX module in the given report matches this module policy.
+ pub fn matches(&self, report: &TdReport) -> bool {
+ // Check MRSEAM if set.
+ if let Some(mr_seam) = self.mr_seam {
+ if mr_seam != report.mr_seam {
+ return false;
+ }
+ }
+
+ // Check MRSIGNER.
+ if self.mr_signer_seam != report.mr_signer_seam {
+ return false;
+ }
+
+ true
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +765 +766 +767 +768 +769 +770 +771 +772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805 +806 +807 +808 +809 +810 +811 +812 +813 +814 +815 +816 +817 +818 +819 +820 +821 +822 +823 +824 +825 +826 +827 +828 +829 +830 +831 +832 +833 +834 +835 +836 +837 +838 +839 +840 +841 +842 +843 +844 +845 +846 +847 +848 +849 +850 +851 +852 +853 +854 +855 +856 +857 +858 +859 +860 +861 +862 +863 +864 +865 +866 +867 +868 +869 +870 +871 +872 +873 +874 +875 +876 +877 +878 +879 +880 +881 +882 +883 +884 +885 +886 +887 +888 +889 +890 +891 +892 +893 +894 +895 +896 +897 +898 +899 +900 +901 +902 +903 +904 +905 +906 +907 +908 +909 +910 +911 +912 +913 +914 +915 +916 +917 +918 +919 +920 +921 +922 +923 +924 +925 +926 +927 +928 +929 +930 +931 +932 +933 +934 +935 +936 +937 +938 +939 +940 +
use std::{borrow::Cow, convert::TryInto, ffi::CString, mem};
+
+use byteorder::{ByteOrder, LittleEndian};
+use chrono::prelude::*;
+use mbedtls::{
+ alloc::List as MbedtlsList,
+ ecp::{EcGroup, EcPoint},
+ hash::{self, Md},
+ pk::{EcGroupId, Pk},
+ x509::certificate::Certificate,
+};
+use num_derive::{FromPrimitive, ToPrimitive};
+use num_traits::FromPrimitive;
+use sgx_isa::AttributesFlags;
+
+use super::{
+ certificates::PCS_TRUST_ROOT,
+ constants::*,
+ policy::QuotePolicy,
+ report::{SgxReport, TdAttributes, TdReport},
+ tcb::{QEIdentity, TCBBundle, TCBInfo, TCBLevel, TCBStatus},
+ utils::TakePrefix,
+ Error,
+};
+use crate::common::sgx::{EnclaveIdentity, MrEnclave, MrSigner, VerifiedQuote};
+
+/// An attestation quote together with the TCB bundle required for its verification.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct QuoteBundle {
+ #[cbor(rename = "quote")]
+ pub quote: Vec<u8>,
+
+ #[cbor(rename = "tcb")]
+ pub tcb: TCBBundle,
+}
+
+impl QuoteBundle {
+ /// Verify the quote bundle.
+ pub fn verify(&self, policy: &QuotePolicy, ts: DateTime<Utc>) -> Result<VerifiedQuote, Error> {
+ if policy.disabled {
+ return Err(Error::Disabled);
+ }
+
+ // XXX: We reuse the IAS specific variables to avoid having additional environment
+ // variables. Rename these variables when IAS support is removed.
+ let unsafe_skip_quote_verification = option_env!("OASIS_UNSAFE_SKIP_AVR_VERIFY").is_some();
+ let unsafe_lax_quote_verification = option_env!("OASIS_UNSAFE_LAX_AVR_VERIFY").is_some();
+
+ // Parse the quote.
+ let quote = Quote::parse(&self.quote)?;
+ let tee_type = quote.header().tee_type();
+
+ // Ensure given TEE type is allowed by the policy.
+ match (tee_type, &policy.tdx) {
+ (TeeType::SGX, _) => { /* Ok. */ }
+ (TeeType::TDX, &None) => return Err(Error::TeeTypeNotAllowed),
+ (TeeType::TDX, &Some(_)) => { /* Ok. */ }
+ }
+
+ // Ensure correct QE vendor.
+ if quote.header().qe_vendor_id() != QE_VENDOR_ID_INTEL {
+ return Err(Error::UnsupportedQEVendor);
+ }
+
+ // Verify TCB bundle and get TCB info and QE identity.
+ let mut tcb_cert = self.tcb.verify_certificates(ts)?;
+ let qe_identity =
+ self.tcb
+ .qe_identity
+ .open(tee_type, ts, policy, tcb_cert.public_key_mut())?;
+ let tcb_info = self
+ .tcb
+ .tcb_info
+ .open(tee_type, ts, policy, tcb_cert.public_key_mut())?;
+
+ // We use the TCB info issue date as the timestamp.
+ let timestamp = NaiveDateTime::parse_from_str(&tcb_info.issue_date, PCS_TS_FMT)
+ .map_err(|err| Error::TCBParseError(err.into()))?
+ .and_utc()
+ .timestamp();
+
+ // Perform quote verification.
+ if !unsafe_skip_quote_verification {
+ let tcb_level = quote.verify(tcb_info, qe_identity)?;
+
+ // Validate TCB level.
+ match tcb_level.status {
+ TCBStatus::UpToDate | TCBStatus::SWHardeningNeeded => {}
+ TCBStatus::OutOfDate
+ | TCBStatus::ConfigurationNeeded
+ | TCBStatus::OutOfDateConfigurationNeeded
+ if unsafe_lax_quote_verification => {}
+ _ => {
+ return Err(Error::TCBOutOfDate);
+ }
+ }
+ }
+
+ // Disallow debug enclaves, if we are in production environment and disallow production
+ // enclaves, if we are in debug environment.
+ let is_debug = quote.report_body().is_debug();
+ let allow_debug = option_env!("OASIS_UNSAFE_ALLOW_DEBUG_ENCLAVES").is_some();
+ if is_debug && !allow_debug {
+ return Err(Error::DebugEnclave);
+ } else if !is_debug && allow_debug {
+ return Err(Error::ProductionEnclave);
+ }
+
+ // Verify report against TDX policy.
+ if let ReportBody::Tdx(report) = quote.report_body() {
+ let tdx_policy = policy.tdx.as_ref().ok_or(Error::TeeTypeNotAllowed)?;
+ tdx_policy.verify(report)?;
+ }
+
+ Ok(VerifiedQuote {
+ report_data: quote.report_body().report_data(),
+ identity: quote.report_body().as_enclave_identity(),
+ timestamp,
+ })
+ }
+}
+
+/// An enclave quote.
+#[derive(Debug)]
+pub struct Quote<'a> {
+ header: Header<'a>,
+ report_body: ReportBody,
+ signature: QuoteSignatureEcdsaP256<'a>,
+ signed_data: Cow<'a, [u8]>,
+}
+
+impl<'a> Quote<'a> {
+ pub fn parse<T: Into<Cow<'a, [u8]>>>(quote: T) -> Result<Quote<'a>, Error> {
+ let mut quote = quote.into();
+ let mut raw = quote.clone();
+
+ // Parse header, depending on version.
+ let version = quote
+ .take_prefix(mem::size_of::<u16>())
+ .map(|v| LittleEndian::read_u16(&v))?;
+ match version {
+ QUOTE_VERSION_3 => {
+ // Version 3 (SGX-ECDSA).
+ let att_key_type = quote
+ .take_prefix(mem::size_of::<u16>())
+ .map(|v| LittleEndian::read_u16(&v))?;
+ let attestation_key_type = AttestationKeyType::from_u16(att_key_type)
+ .ok_or(Error::UnsupportedAttestationKeyType)?;
+ let reserved = quote
+ .take_prefix(mem::size_of::<u32>())
+ .map(|v| LittleEndian::read_u32(&v))?;
+ if reserved != 0 {
+ return Err(Error::QuoteParseError("data in reserved field".to_string()));
+ }
+
+ let qe_svn = quote
+ .take_prefix(mem::size_of::<u16>())
+ .map(|v| LittleEndian::read_u16(&v))?;
+ let pce_svn = quote
+ .take_prefix(mem::size_of::<u16>())
+ .map(|v| LittleEndian::read_u16(&v))?;
+ let qe_vendor_id = quote.take_prefix(QE_VENDOR_ID_LEN)?;
+ let user_data = quote.take_prefix(QE_USER_DATA_LEN)?;
+ let report_body = quote.take_prefix(SGX_REPORT_BODY_LEN)?;
+ let report_body = ReportBody::parse(TeeType::SGX, &report_body)?;
+
+ if attestation_key_type != AttestationKeyType::EcdsaP256 {
+ return Err(Error::UnsupportedAttestationKeyType);
+ }
+ let signature = QuoteSignatureEcdsaP256::parse(version, quote)?;
+ let signed_data = raw.take_prefix(QUOTE_HEADER_LEN + SGX_REPORT_BODY_LEN)?;
+
+ Ok(Quote {
+ header: Header::V3 {
+ attestation_key_type,
+ qe_svn,
+ pce_svn,
+ qe_vendor_id,
+ user_data,
+ },
+ report_body,
+ signature,
+ signed_data,
+ })
+ }
+ QUOTE_VERSION_4 => {
+ // Version 4 (TDX-ECDSA, SGX-ECDSA).
+ let att_key_type = quote
+ .take_prefix(mem::size_of::<u16>())
+ .map(|v| LittleEndian::read_u16(&v))?;
+ let attestation_key_type = AttestationKeyType::from_u16(att_key_type)
+ .ok_or(Error::UnsupportedAttestationKeyType)?;
+
+ let tee_type_raw = quote
+ .take_prefix(mem::size_of::<u32>())
+ .map(|v| LittleEndian::read_u32(&v))?;
+ let tee_type = TeeType::from_u32(tee_type_raw).ok_or(Error::UnsupportedTeeType)?;
+
+ let reserved1 = quote
+ .take_prefix(mem::size_of::<u16>())
+ .map(|v| LittleEndian::read_u16(&v))?;
+ let reserved2 = quote
+ .take_prefix(mem::size_of::<u16>())
+ .map(|v| LittleEndian::read_u16(&v))?;
+
+ if reserved1 != 0 || reserved2 != 0 {
+ return Err(Error::QuoteParseError("data in reserved field".to_string()));
+ }
+
+ let qe_vendor_id = quote.take_prefix(QE_VENDOR_ID_LEN)?;
+ let user_data = quote.take_prefix(QE_USER_DATA_LEN)?;
+
+ let header = Header::V4 {
+ attestation_key_type,
+ tee_type,
+ qe_vendor_id,
+ user_data,
+ };
+ let report_body = quote.take_prefix(header.report_body_len())?;
+ let report_body = ReportBody::parse(tee_type, &report_body)?;
+
+ if attestation_key_type != AttestationKeyType::EcdsaP256 {
+ return Err(Error::UnsupportedAttestationKeyType);
+ }
+ let signature = QuoteSignatureEcdsaP256::parse(version, quote)?;
+ let signed_data = raw.take_prefix(QUOTE_HEADER_LEN + header.report_body_len())?;
+
+ Ok(Quote {
+ header,
+ report_body,
+ signature,
+ signed_data,
+ })
+ }
+ _ => Err(Error::QuoteParseError(format!(
+ "unsupported quote version: {}",
+ version
+ ))),
+ }
+ }
+
+ /// Quote header.
+ pub fn header(&self) -> &Header<'a> {
+ &self.header
+ }
+
+ /// Report body.
+ pub fn report_body(&self) -> &ReportBody {
+ &self.report_body
+ }
+
+ /// Verify quote.
+ pub fn verify(&self, tcb_info: TCBInfo, qe_identity: QEIdentity) -> Result<TCBLevel, Error> {
+ let tdx_comp_svn = self.report_body.tdx_comp_svn();
+
+ let mut verifier: QeEcdsaP256Verifier =
+ QeEcdsaP256Verifier::new(tcb_info, qe_identity, tdx_comp_svn);
+ self.signature.verify(&self.signed_data, &mut verifier)?;
+
+ Ok(verifier.tcb_level().unwrap())
+ }
+}
+
+/// An enclave quote header.
+#[derive(Debug)]
+pub enum Header<'a> {
+ V3 {
+ attestation_key_type: AttestationKeyType,
+ qe_svn: u16,
+ pce_svn: u16,
+ qe_vendor_id: Cow<'a, [u8]>,
+ user_data: Cow<'a, [u8]>,
+ },
+
+ V4 {
+ attestation_key_type: AttestationKeyType,
+ tee_type: TeeType,
+ qe_vendor_id: Cow<'a, [u8]>,
+ user_data: Cow<'a, [u8]>,
+ },
+}
+
+impl<'a> Header<'a> {
+ /// Quote header version.
+ pub fn version(&self) -> u16 {
+ match self {
+ Self::V3 { .. } => QUOTE_VERSION_3,
+ Self::V4 { .. } => QUOTE_VERSION_4,
+ }
+ }
+
+ /// Attestation key type.
+ pub fn attestation_key_type(&self) -> AttestationKeyType {
+ match self {
+ Self::V3 {
+ attestation_key_type,
+ ..
+ } => *attestation_key_type,
+ Self::V4 {
+ attestation_key_type,
+ ..
+ } => *attestation_key_type,
+ }
+ }
+
+ /// TEE type the quote is for.
+ pub fn tee_type(&self) -> TeeType {
+ match self {
+ Self::V3 { .. } => TeeType::SGX,
+ Self::V4 { tee_type, .. } => *tee_type,
+ }
+ }
+
+ /// Quoting Enclave (QE) vendor identifier.
+ pub fn qe_vendor_id(&self) -> &[u8] {
+ match self {
+ Self::V3 { qe_vendor_id, .. } => qe_vendor_id,
+ Self::V4 { qe_vendor_id, .. } => qe_vendor_id,
+ }
+ }
+
+ /// Length of the report body field.
+ pub fn report_body_len(&self) -> usize {
+ match self.tee_type() {
+ TeeType::SGX => SGX_REPORT_BODY_LEN,
+ TeeType::TDX => TDX_REPORT_BODY_LEN,
+ }
+ }
+}
+
+/// TEE type.
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, FromPrimitive, ToPrimitive)]
+#[repr(u32)]
+pub enum TeeType {
+ SGX = 0x00000000,
+ TDX = 0x00000081,
+}
+
+/// Attestation key type.
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, FromPrimitive, ToPrimitive)]
+#[repr(u16)]
+pub enum AttestationKeyType {
+ EcdsaP256 = 2,
+}
+
+/// Report body.
+#[derive(Debug)]
+pub enum ReportBody {
+ Sgx(SgxReport),
+ Tdx(TdReport),
+}
+
+impl ReportBody {
+ /// Parse the report body.
+ pub fn parse(tee_type: TeeType, raw: &[u8]) -> Result<Self, Error> {
+ match tee_type {
+ TeeType::SGX => {
+ // Parse SGX report body.
+ let mut report_body = Vec::with_capacity(SgxReport::UNPADDED_SIZE);
+ report_body.extend(raw);
+ report_body.resize_with(SgxReport::UNPADDED_SIZE, Default::default);
+ let report =
+ SgxReport::try_copy_from(&report_body).ok_or(Error::MalformedReport)?;
+
+ Ok(Self::Sgx(report))
+ }
+ TeeType::TDX => {
+ // Parse TDX TD report body.
+ let report = TdReport::parse(raw)?;
+
+ Ok(Self::Tdx(report))
+ }
+ }
+ }
+
+ /// TDX TEE Component SVNs.
+ ///
+ /// Returns `None` in case of a non-TDX report body.
+ pub fn tdx_comp_svn(&self) -> Option<[u32; 16]> {
+ match self {
+ Self::Sgx(_) => None,
+ Self::Tdx(report) => Some(
+ report
+ .tee_tcb_svn
+ .iter()
+ .map(|x| *x as u32)
+ .collect::<Vec<u32>>()
+ .try_into()
+ .unwrap(),
+ ),
+ }
+ }
+
+ /// Whether the report indicates a debug TEE.
+ pub fn is_debug(&self) -> bool {
+ match self {
+ Self::Sgx(report) => report.attributes.flags.contains(AttributesFlags::DEBUG),
+ Self::Tdx(report) => report.td_attributes.contains(TdAttributes::DEBUG),
+ }
+ }
+
+ /// Converts this report into an enclave identity.
+ pub fn as_enclave_identity(&self) -> EnclaveIdentity {
+ match self {
+ Self::Sgx(report) => EnclaveIdentity {
+ mr_enclave: MrEnclave::from(report.mrenclave.to_vec()),
+ mr_signer: MrSigner::from(report.mrsigner.to_vec()),
+ },
+ Self::Tdx(report) => report.as_enclave_identity(),
+ }
+ }
+
+ /// Data contained in the report.
+ pub fn report_data(&self) -> Vec<u8> {
+ match self {
+ Self::Sgx(report) => report.reportdata.to_vec(),
+ Self::Tdx(report) => report.report_data.to_vec(),
+ }
+ }
+}
+
+/// Quote signature trait.
+pub trait QuoteSignature<'a>: Sized {
+ /// Parse the quote signature from the passed data.
+ fn parse(version: u16, data: Cow<'a, [u8]>) -> Result<Self, Error>;
+}
+
+/// ECDSA-P256 quote signature.
+#[derive(Debug)]
+pub struct QuoteSignatureEcdsaP256<'a> {
+ signature: Cow<'a, [u8]>,
+ attestation_public_key: Cow<'a, [u8]>,
+
+ qe: CertificationDataQeReport<'a>,
+}
+
+impl<'a> QuoteSignature<'a> for QuoteSignatureEcdsaP256<'a> {
+ fn parse(version: u16, mut data: Cow<'a, [u8]>) -> Result<Self, Error> {
+ let sig_len = data
+ .take_prefix(mem::size_of::<u32>())
+ .map(|v| LittleEndian::read_u32(&v))?;
+ if sig_len as usize != data.len() {
+ return Err(Error::QuoteParseError(
+ "unexpected trailing data after signature".to_string(),
+ ));
+ }
+ let signature = data.take_prefix(ECDSA_P256_SIGNATURE_LEN)?;
+ let attestation_public_key = data.take_prefix(ECDSA_P256_PUBLIC_KEY_LEN)?;
+
+ // In version 4 quotes, there is an intermediate certification data tuple.
+ if version == QUOTE_VERSION_4 {
+ let cd_type = data
+ .take_prefix(mem::size_of::<u16>())
+ .map(|v| LittleEndian::read_u16(&v))?;
+ let certification_data_type =
+ CertificationDataType::from_u16(cd_type).ok_or_else(|| {
+ Error::QuoteParseError(format!("unknown certification data type: {}", cd_type))
+ })?;
+ let certdata_len = data
+ .take_prefix(mem::size_of::<u32>())
+ .map(|v| LittleEndian::read_u32(&v))?;
+ if certdata_len as usize != data.len() {
+ return Err(Error::QuoteParseError(
+ "invalid certification data length".to_string(),
+ ));
+ }
+
+ if certification_data_type != CertificationDataType::QeReport {
+ return Err(Error::UnexpectedCertificationData);
+ }
+ }
+
+ let qe = CertificationDataQeReport::parse(data)?;
+
+ Ok(QuoteSignatureEcdsaP256 {
+ signature,
+ attestation_public_key,
+ qe,
+ })
+ }
+}
+
+impl<'a> QuoteSignatureEcdsaP256<'a> {
+ /// Raw signature.
+ pub fn signature(&self) -> &[u8] {
+ &self.signature
+ }
+
+ /// Raw attestation public key.
+ pub fn attestation_public_key(&self) -> &[u8] {
+ &self.attestation_public_key
+ }
+
+ /// Verify signature against quote using the attestation public key.
+ ///
+ /// The passed `data` must cover the Quote Header and the Report Data.
+ pub fn verify_quote_signature(&'a self, data: &[u8]) -> Result<&'a Self, Error> {
+ let sig = raw_ecdsa_sig_to_der(self.signature())?;
+ let mut pk = parse_ecdsa_pk(self.attestation_public_key())?;
+
+ let mut hash = [0u8; 32];
+ Md::hash(hash::Type::Sha256, data, &mut hash).map_err(|err| Error::Other(err.into()))?;
+ pk.verify(hash::Type::Sha256, &hash, &sig)
+ .map_err(|_| Error::VerificationFailed("quote signature is invalid".to_string()))?;
+
+ Ok(self)
+ }
+
+ /// Verify QE Report signature using the PCK public key.
+ pub fn verify_qe_report_signature(&self, pck_pk: &[u8]) -> Result<(), Error> {
+ self.qe
+ .verify_qe_report_signature(self.attestation_public_key(), pck_pk)
+ }
+}
+
+/// Convert IEEE P1363 ECDSA signature to RFC5480 ASN.1 representation.
+fn raw_ecdsa_sig_to_der(sig: &[u8]) -> Result<Vec<u8>, Error> {
+ if sig.len() % 2 != 0 {
+ return Err(Error::QuoteParseError(
+ "malformed ECDSA signature".to_string(),
+ ));
+ }
+
+ let (r_bytes, s_bytes) = sig.split_at(sig.len() / 2);
+ let r = num_bigint::BigUint::from_bytes_be(r_bytes);
+ let s = num_bigint::BigUint::from_bytes_be(s_bytes);
+
+ let der = yasna::construct_der(|writer| {
+ writer.write_sequence(|writer| {
+ writer.next().write_biguint(&r);
+ writer.next().write_biguint(&s);
+ })
+ });
+
+ Ok(der)
+}
+
+/// Parse Secp256r1 public key.
+fn parse_ecdsa_pk(pk: &[u8]) -> Result<Pk, Error> {
+ let mut pt = vec![0x4]; // Add SEC 1 tag (uncompressed).
+ pt.extend_from_slice(pk);
+
+ let group = EcGroup::new(EcGroupId::SecP256R1).map_err(|err| Error::Other(err.into()))?;
+ let pt = EcPoint::from_binary(&group, &pt).map_err(|err| Error::Other(err.into()))?;
+ Pk::public_from_ec_components(group, pt).map_err(|err| Error::Other(err.into()))
+}
+
+/// Quote signature verifier for ECDSA-P256 signatures.
+pub trait QuoteSignatureEcdsaP256Verifier {
+ /// Verify the platform certification data.
+ ///
+ /// The certification data is in `signature.certification_data()`.
+ ///
+ /// On success, should return the platform certification public key (PCK) in DER format.
+ fn verify_certification_data(
+ &mut self,
+ signature: &QuoteSignatureEcdsaP256,
+ ) -> Result<Vec<u8>, Error>;
+
+ /// Verify the quoting enclave.
+ fn verify_qe(&mut self, qe_report: &[u8], authentication_data: &[u8]) -> Result<(), Error>;
+}
+
+pub trait QuoteSignatureVerify<'a>: QuoteSignature<'a> {
+ type TrustRoot;
+
+ fn verify(&self, quote: &[u8], root_of_trust: Self::TrustRoot) -> Result<(), Error>;
+}
+
+impl<'a> QuoteSignatureVerify<'a> for QuoteSignatureEcdsaP256<'a> {
+ type TrustRoot = &'a mut dyn QuoteSignatureEcdsaP256Verifier;
+
+ fn verify(&self, quote: &[u8], verifier: Self::TrustRoot) -> Result<(), Error> {
+ let pck_pk = verifier.verify_certification_data(self)?;
+ self.verify_qe_report_signature(&pck_pk)?;
+ verifier.verify_qe(self.qe.qe_report(), self.qe.authentication_data())?;
+ self.verify_quote_signature(quote)?;
+ Ok(())
+ }
+}
+
+/// Certification data type.
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, FromPrimitive, ToPrimitive)]
+#[repr(u16)]
+pub enum CertificationDataType {
+ PpidCleartext = 1,
+ PpidEncryptedRsa2048 = 2,
+ PpidEncryptedRsa3072 = 3,
+ PckCertificate = 4,
+ PckCertificateChain = 5,
+ QeReport = 6,
+ PlatformManifest = 7,
+}
+
+/// Certification data trait.
+pub trait CertificationData<'a>: Sized {
+ /// Parse certification data of the given type from the given raw data.
+ fn parse(r#type: CertificationDataType, data: Cow<'a, [u8]>) -> Result<Self, Error>;
+}
+
+/// PPID certification data.
+#[derive(Clone, Debug, Hash, PartialEq, Eq)]
+pub struct CertificationDataPpid<'a> {
+ pub ppid: Cow<'a, [u8]>,
+ pub cpusvn: Cow<'a, [u8]>,
+ pub pcesvn: u16,
+ pub pceid: u16,
+}
+
+impl<'a> CertificationData<'a> for CertificationDataPpid<'a> {
+ fn parse(r#type: CertificationDataType, mut data: Cow<'a, [u8]>) -> Result<Self, Error> {
+ let ppid_len = match r#type {
+ CertificationDataType::PpidEncryptedRsa2048 => 256,
+ CertificationDataType::PpidEncryptedRsa3072 => 384,
+ _ => return Err(Error::UnexpectedCertificationData),
+ };
+
+ let ppid = data.take_prefix(ppid_len)?;
+ let cpusvn = data.take_prefix(CPUSVN_LEN)?;
+ let pcesvn = data
+ .take_prefix(mem::size_of::<u16>())
+ .map(|v| LittleEndian::read_u16(&v))?;
+ let pceid = data
+ .take_prefix(mem::size_of::<u16>())
+ .map(|v| LittleEndian::read_u16(&v))?;
+ if !data.is_empty() {
+ return Err(Error::MalformedCertificationData);
+ }
+
+ Ok(CertificationDataPpid {
+ ppid,
+ cpusvn,
+ pcesvn,
+ pceid,
+ })
+ }
+}
+
+/// PCK certificate chain certification data.
+#[derive(Clone, Debug, Hash, PartialEq, Eq)]
+pub struct CertificationDataPckCertificateChain<'a> {
+ pub certs: Vec<Cow<'a, str>>,
+}
+
+impl<'a> CertificationData<'a> for CertificationDataPckCertificateChain<'a> {
+ fn parse(r#type: CertificationDataType, data: Cow<'a, [u8]>) -> Result<Self, Error> {
+ if r#type != CertificationDataType::PckCertificateChain {
+ return Err(Error::UnexpectedCertificationData);
+ }
+
+ let mut data = match data {
+ Cow::Borrowed(s) => std::str::from_utf8(s)
+ .map(Cow::Borrowed)
+ .map_err(|_| Error::MalformedPCK)?,
+ Cow::Owned(s) => String::from_utf8(s)
+ .map(Cow::Owned)
+ .map_err(|_| Error::MalformedPCK)?,
+ };
+
+ let mut certs = vec![];
+ let mark = "-----END CERTIFICATE-----";
+ while let Some(pos) = data.find(mark) {
+ certs.push(data.take_prefix(pos + mark.len()).unwrap()); // Pos is always valid.
+ if let Some(start) = data.find("-") {
+ data.take_prefix(start).unwrap(); // Start is always valid.
+ }
+ }
+
+ Ok(CertificationDataPckCertificateChain { certs })
+ }
+}
+
+/// QE report certification data.
+#[derive(Debug)]
+pub struct CertificationDataQeReport<'a> {
+ qe_report: Cow<'a, [u8]>,
+ qe_report_signature: Cow<'a, [u8]>,
+ authentication_data: Cow<'a, [u8]>,
+ certification_data_type: CertificationDataType,
+ certification_data: Cow<'a, [u8]>,
+}
+
+impl<'a> CertificationDataQeReport<'a> {
+ fn parse(mut data: Cow<'a, [u8]>) -> Result<Self, Error> {
+ let qe_report = data.take_prefix(SGX_REPORT_BODY_LEN)?;
+ let qe_report_signature = data.take_prefix(ECDSA_P256_SIGNATURE_LEN)?;
+ let authdata_len = data
+ .take_prefix(mem::size_of::<u16>())
+ .map(|v| LittleEndian::read_u16(&v))?;
+ let authentication_data = data.take_prefix(authdata_len as _)?;
+
+ let cd_type = data
+ .take_prefix(mem::size_of::<u16>())
+ .map(|v| LittleEndian::read_u16(&v))?;
+ let certification_data_type =
+ CertificationDataType::from_u16(cd_type).ok_or_else(|| {
+ Error::QuoteParseError(format!("unknown certification data type: {}", cd_type))
+ })?;
+ let certdata_len = data
+ .take_prefix(mem::size_of::<u32>())
+ .map(|v| LittleEndian::read_u32(&v))?;
+ if certdata_len as usize != data.len() {
+ return Err(Error::QuoteParseError(
+ "invalid certification data length".to_string(),
+ ));
+ }
+
+ Ok(CertificationDataQeReport {
+ qe_report,
+ qe_report_signature,
+ authentication_data,
+ certification_data_type,
+ certification_data: data,
+ })
+ }
+
+ /// Raw QE report.
+ pub fn qe_report(&self) -> &[u8] {
+ &self.qe_report
+ }
+
+ /// Raw QE report signature.
+ pub fn qe_report_signature(&self) -> &[u8] {
+ &self.qe_report_signature
+ }
+
+ /// Raw authentication data.
+ pub fn authentication_data(&self) -> &[u8] {
+ &self.authentication_data
+ }
+
+ /// Inner certification data type.
+ pub fn certification_data_type(&self) -> CertificationDataType {
+ self.certification_data_type
+ }
+
+ /// Parse inner certification data.
+ pub fn certification_data<T: CertificationData<'a>>(&self) -> Result<T, Error> {
+ T::parse(
+ self.certification_data_type,
+ self.certification_data.clone(),
+ )
+ }
+
+ /// Verify QE Report signature using the PCK public key.
+ pub fn verify_qe_report_signature(
+ &self,
+ attestation_pk: &[u8],
+ pck_pk: &[u8],
+ ) -> Result<(), Error> {
+ // Verify QE report signature using PCK public key.
+ let sig = raw_ecdsa_sig_to_der(self.qe_report_signature())?;
+ let mut hash = [0u8; 32];
+ Md::hash(hash::Type::Sha256, self.qe_report(), &mut hash)
+ .map_err(|err| Error::Other(err.into()))?;
+ let mut pck_pk = Pk::from_public_key(pck_pk).map_err(|err| Error::Other(err.into()))?;
+ pck_pk
+ .verify(mbedtls::hash::Type::Sha256, &hash, &sig)
+ .map_err(|_| Error::VerificationFailed("QE report signature is invalid".to_string()))?;
+
+ // Verify QE report data. First 32 bytes MUST be:
+ // SHA-256(AttestationPublicKey || AuthenticationData)
+ // and the remaining 32 bytes MUST be zero.
+ let mut hash = [0u8; 32];
+ let mut sha256 = Md::new(hash::Type::Sha256).map_err(|err| Error::Other(err.into()))?;
+ sha256
+ .update(attestation_pk)
+ .map_err(|err| Error::Other(err.into()))?;
+ sha256
+ .update(self.authentication_data())
+ .map_err(|err| Error::Other(err.into()))?;
+ sha256
+ .finish(&mut hash)
+ .map_err(|err| Error::Other(err.into()))?;
+
+ let mut qe_report = Vec::with_capacity(SgxReport::UNPADDED_SIZE);
+ qe_report.extend(self.qe_report());
+ qe_report.resize_with(SgxReport::UNPADDED_SIZE, Default::default);
+ let qe_report = SgxReport::try_copy_from(&qe_report).ok_or(Error::MalformedQEReport)?;
+
+ if qe_report.reportdata[0..32] != hash {
+ return Err(Error::VerificationFailed(
+ "QE report data does not match expected value".to_string(),
+ ));
+ }
+ if qe_report.reportdata[32..64] != [0; 32] {
+ return Err(Error::VerificationFailed(
+ "QE report data does not match expected value".to_string(),
+ ));
+ }
+
+ Ok(())
+ }
+}
+
+/// Quoting Enclave ECDSA P-256 verifier.
+pub struct QeEcdsaP256Verifier {
+ tcb_info: TCBInfo,
+ qe_identity: QEIdentity,
+ tdx_comp_svn: Option<[u32; 16]>,
+ tcb_level: Option<TCBLevel>,
+}
+
+impl QeEcdsaP256Verifier {
+ /// Create a new verifier.
+ pub fn new(
+ tcb_info: TCBInfo,
+ qe_identity: QEIdentity,
+ tdx_comp_svn: Option<[u32; 16]>,
+ ) -> Self {
+ Self {
+ tcb_info,
+ qe_identity,
+ tdx_comp_svn,
+ tcb_level: None,
+ }
+ }
+
+ /// Get the TCB level.
+ /// This will return `None` if the quote has not been verified yet.
+ pub fn tcb_level(&self) -> Option<TCBLevel> {
+ self.tcb_level.clone()
+ }
+}
+
+impl QuoteSignatureEcdsaP256Verifier for QeEcdsaP256Verifier {
+ fn verify_certification_data(
+ &mut self,
+ signature: &QuoteSignatureEcdsaP256,
+ ) -> Result<Vec<u8>, Error> {
+ // Only PCK certificate chain is supported as certification data.
+ let certs = signature
+ .qe
+ .certification_data::<CertificationDataPckCertificateChain>()?
+ .certs;
+ if certs.len() != 3 {
+ return Err(Error::UnexpectedCertificateChain);
+ }
+
+ // Verify certificate chain.
+ let mut cert_chain = MbedtlsList::new();
+ for raw_cert in &certs {
+ let raw_cert = CString::new(raw_cert.as_ref()).map_err(|_| Error::MalformedPCK)?;
+ let cert = Certificate::from_pem(raw_cert.as_bytes_with_nul())
+ .map_err(|_| Error::MalformedPCK)?;
+ cert_chain.push(cert);
+ }
+ // TODO: Specify current timestamp.
+ Certificate::verify(&cert_chain, &PCS_TRUST_ROOT, None, None).map_err(|_| {
+ Error::VerificationFailed("PCK certificate chain is invalid".to_string())
+ })?;
+
+ // Extract TCB parameters from the PCK certificate.
+ let mut pck_cert = cert_chain.pop_front().unwrap();
+
+ let sgx_extensions = pck_cert
+ .extensions()
+ .map_err(|_| Error::MalformedPCK)?
+ .into_iter()
+ .find(|ext| ext.oid.as_ref() == PCK_SGX_EXTENSIONS_OID)
+ .ok_or(Error::TCBVerificationFailed)?;
+ let mut fmspc: Option<Vec<u8>> = None;
+ let mut tcb_comp_svn: Option<[u32; 16]> = None;
+ let mut pcesvn: Option<u32> = None;
+ yasna::parse_der(&sgx_extensions.value, |reader| {
+ reader.read_sequence_of(|reader| {
+ reader.read_sequence(|reader| {
+ match reader.next().read_oid()?.as_ref() {
+ PCK_SGX_EXTENSIONS_FMSPC_OID => {
+ // FMSPC
+ let raw_fmspc = reader.next().read_bytes()?;
+ if raw_fmspc.len() != 6 {
+ return Err(yasna::ASN1Error::new(yasna::ASN1ErrorKind::Invalid));
+ }
+ fmspc = Some(raw_fmspc);
+ }
+ PCK_SGX_EXTENSIONS_TCB_OID => {
+ // TCB
+ reader.next().read_sequence_of(|reader| {
+ reader.read_sequence(|reader| {
+ let comp_id =
+ *reader.next().read_oid()?.as_ref().last().unwrap();
+ if (1..=16).contains(&comp_id) {
+ // TCB Component SVNs
+ tcb_comp_svn.get_or_insert([0; 16])
+ [(comp_id - 1) as usize] = reader.next().read_u32()?;
+ } else if comp_id == 17 {
+ // PCESVN
+ pcesvn = Some(reader.next().read_u32()?);
+ } else if comp_id == 18 {
+ // CPUSVN
+ reader.next().read_bytes()?;
+ }
+ Ok(())
+ })
+ })?;
+ }
+ _ => {
+ reader.next().read_der()?;
+ }
+ }
+
+ Ok(())
+ })
+ })
+ })
+ .map_err(|_| Error::MalformedPCK)?;
+ if fmspc.is_none() || tcb_comp_svn.is_none() || pcesvn.is_none() {
+ return Err(Error::MalformedPCK);
+ }
+
+ // Verify TCB level.
+ let tcb_level = self.tcb_info.verify(
+ &fmspc.unwrap(),
+ &tcb_comp_svn.unwrap(),
+ self.tdx_comp_svn.as_ref(),
+ pcesvn.unwrap(),
+ )?;
+ self.tcb_level = Some(tcb_level);
+
+ // Extract PCK public key.
+ let pck_pk = pck_cert
+ .public_key_mut()
+ .write_public_der_vec()
+ .map_err(|_| Error::MalformedPCK)?;
+
+ Ok(pck_pk)
+ }
+
+ fn verify_qe(&mut self, qe_report: &[u8], _authentication_data: &[u8]) -> Result<(), Error> {
+ let mut report = Vec::with_capacity(SgxReport::UNPADDED_SIZE);
+ report.extend(qe_report);
+ report.resize_with(SgxReport::UNPADDED_SIZE, Default::default);
+
+ let report = SgxReport::try_copy_from(&report).ok_or(Error::MalformedQEReport)?;
+ self.qe_identity.verify(&report)?;
+
+ Ok(())
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +
//! TDX structures.
+use std::convert::TryInto;
+
+use byteorder::{ByteOrder, LittleEndian};
+pub use sgx_isa::Report as SgxReport;
+use tiny_keccak::{Hasher, TupleHash};
+
+use super::{constants::*, utils::*, Error};
+use crate::common::sgx::{EnclaveIdentity, MrEnclave};
+
+/// TDX TD report.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct TdReport {
+ /// Describes the TCB of TDX.
+ pub tee_tcb_svn: [u8; 16],
+ /// Measurement of the TDX Module.
+ pub mr_seam: [u8; 48],
+ /// Signer of the TDX Module (zero for Intel).
+ pub mr_signer_seam: [u8; 48],
+ /// TDX Module attributes (must be zero for TDX 1.0).
+ pub seam_attributes: [u8; 8],
+ /// TD attributes.
+ pub td_attributes: TdAttributes,
+ /// XFAM (eXtended Features Available Mask).
+ pub xfam: [u8; 8],
+ /// Measurement of the initial contents of the TD.
+ pub mr_td: [u8; 48],
+ /// Software-defined ID for non-owner-defined configuration of the TD, e.g., runtime or OS
+ /// configuration.
+ pub mr_config_id: [u8; 48],
+ /// Software-defined ID for the TD’s owner.
+ pub mr_owner: [u8; 48],
+ /// Software-defined ID for owner-defined configuration of the TD, e.g., specific to the
+ /// workload rather than the runtime or OS.
+ pub mr_owner_config: [u8; 48],
+ /// Runtime extendable measurement register 0.
+ pub rtmr0: [u8; 48],
+ /// Runtime extendable measurement register 1.
+ pub rtmr1: [u8; 48],
+ /// Runtime extendable measurement register 2.
+ pub rtmr2: [u8; 48],
+ /// Runtime extendable measurement register 3.
+ pub rtmr3: [u8; 48],
+ /// Custom report data.
+ pub report_data: [u8; 64],
+}
+
+impl TdReport {
+ /// Parse a TDX report.
+ pub fn parse(mut data: &[u8]) -> Result<Self, Error> {
+ if data.len() != TDX_REPORT_BODY_LEN {
+ return Err(Error::MalformedReport);
+ }
+
+ let report = Self {
+ tee_tcb_svn: data
+ .take_prefix(16)
+ .map_err(|_| Error::MalformedReport)?
+ .try_into()
+ .unwrap(),
+ mr_seam: data
+ .take_prefix(48)
+ .map_err(|_| Error::MalformedReport)?
+ .try_into()
+ .unwrap(),
+ mr_signer_seam: data
+ .take_prefix(48)
+ .map_err(|_| Error::MalformedReport)?
+ .try_into()
+ .unwrap(),
+ seam_attributes: data
+ .take_prefix(8)
+ .map_err(|_| Error::MalformedReport)?
+ .try_into()
+ .unwrap(),
+ td_attributes: TdAttributes::parse(
+ data.take_prefix(8).map_err(|_| Error::MalformedReport)?,
+ )?,
+ xfam: data
+ .take_prefix(8)
+ .map_err(|_| Error::MalformedReport)?
+ .try_into()
+ .unwrap(),
+ mr_td: data
+ .take_prefix(48)
+ .map_err(|_| Error::MalformedReport)?
+ .try_into()
+ .unwrap(),
+ mr_config_id: data
+ .take_prefix(48)
+ .map_err(|_| Error::MalformedReport)?
+ .try_into()
+ .unwrap(),
+ mr_owner: data
+ .take_prefix(48)
+ .map_err(|_| Error::MalformedReport)?
+ .try_into()
+ .unwrap(),
+ mr_owner_config: data
+ .take_prefix(48)
+ .map_err(|_| Error::MalformedReport)?
+ .try_into()
+ .unwrap(),
+ rtmr0: data
+ .take_prefix(48)
+ .map_err(|_| Error::MalformedReport)?
+ .try_into()
+ .unwrap(),
+ rtmr1: data
+ .take_prefix(48)
+ .map_err(|_| Error::MalformedReport)?
+ .try_into()
+ .unwrap(),
+ rtmr2: data
+ .take_prefix(48)
+ .map_err(|_| Error::MalformedReport)?
+ .try_into()
+ .unwrap(),
+ rtmr3: data
+ .take_prefix(48)
+ .map_err(|_| Error::MalformedReport)?
+ .try_into()
+ .unwrap(),
+ report_data: data
+ .take_prefix(64)
+ .map_err(|_| Error::MalformedReport)?
+ .try_into()
+ .unwrap(),
+ };
+
+ // SEAM attributes must be zero for TDX 1.0.
+ if report.seam_attributes != [0; 8] {
+ return Err(Error::MalformedReport);
+ }
+
+ Ok(report)
+ }
+
+ /// Converts this report into an enclave identity.
+ pub fn as_enclave_identity(&self) -> EnclaveIdentity {
+ td_enclave_identity(
+ &self.mr_td,
+ &self.rtmr0,
+ &self.rtmr1,
+ &self.rtmr2,
+ &self.rtmr3,
+ )
+ }
+}
+
+/// Compute enclave identity from the given measurements.
+pub fn td_enclave_identity(
+ mr_td: &[u8; 48],
+ rtmr0: &[u8; 48],
+ rtmr1: &[u8; 48],
+ rtmr2: &[u8; 48],
+ rtmr3: &[u8; 48],
+) -> EnclaveIdentity {
+ // TODO: Change the EnclaveIdentity structure to allow specifying all the different things.
+
+ // Compute MRENCLAVE as TupleHash[TD_ENCLAVE_IDENTITY_CONTEXT](MRTD, RTMR0, RTMR1, RTMR2, RTMR3).
+ //
+ // MRTD -- Measurement of virtual firmware.
+ // RTMR0 -- Measurement of virtual firmware data and configuration.
+ // RTMR1 -- Measurement of OS loader, option ROM, boot parameters.
+ // RTMR2 -- Measurement of OS kernel, initrd, boot parameters.
+ // RTMR3 -- Reserved.
+ //
+ let mut mr_enclave = MrEnclave::default();
+ let mut h = TupleHash::v256(TD_ENCLAVE_IDENTITY_CONTEXT);
+ h.update(mr_td);
+ h.update(rtmr0);
+ h.update(rtmr1);
+ h.update(rtmr2);
+ h.update(rtmr3);
+ h.finalize(&mut mr_enclave.0);
+
+ EnclaveIdentity {
+ mr_signer: Default::default(), // All-zero MRSIGNER (invalid in SGX).
+ mr_enclave,
+ }
+}
+
+/// TD enclave identity conversion context.
+pub const TD_ENCLAVE_IDENTITY_CONTEXT: &[u8] = b"oasis-core/tdx: TD enclave identity";
+
+bitflags::bitflags! {
+ /// TDX TD attributes.
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
+ pub struct TdAttributes: u64 {
+ /// TUD.DEBUG (TD runs in debug mode).
+ const DEBUG = 0b00000000_00000000_00000000_00000000_00000000_00000000_00000000_00000001;
+ // TUD bits 7:1 reserved for future use and must be zero.
+
+ // SEC bits 27:8 reserved for future use and must be zero.
+ /// SEC.SEPT_VE_DISABLE (Disable EPT violation conversion to #VE on TD access of PENDING pages).
+ const SEPT_VE_DISABLE = 0b00000000_00000000_00000000_00000000_00010000_00000000_00000000_00000000;
+ // SEC bit 28 reserved for future use and must be zero.
+ /// SEC.PKS (TD is allowed to use Supervisor Protection Keys).
+ const PKS = 0b00000000_00000000_00000000_00000000_01000000_00000000_00000000_00000000;
+ /// SEC.KL (TD is allowed to use Key Locker).
+ const KL = 0b00000000_00000000_00000000_00000000_10000000_00000000_00000000_00000000;
+
+ // OTHER bits 62:32 reserved for future use and must be zero.
+ /// OTHER.PERFMON (TD is allowed to use Perfmon and PERF_METRICS capabilities).
+ const PERFMON = 0b10000000_00000000_00000000_00000000_00000000_00000000_00000000_00000000;
+ }
+}
+
+impl TdAttributes {
+ /// Parse raw TDX attributes.
+ pub fn parse(data: &[u8]) -> Result<Self, Error> {
+ if data.len() != 8 {
+ return Err(Error::MalformedReport);
+ }
+
+ let attrs = LittleEndian::read_u64(data);
+
+ Self::from_bits(attrs).ok_or(Error::MalformedReport)
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ #[test]
+ fn test_td_attributes() {
+ let attrs = TdAttributes::DEBUG | TdAttributes::SEPT_VE_DISABLE | TdAttributes::PKS;
+ assert!(attrs.contains(TdAttributes::DEBUG));
+ assert!(attrs.contains(TdAttributes::SEPT_VE_DISABLE));
+ assert!(attrs.contains(TdAttributes::PKS));
+ assert!(attrs.contains(TdAttributes::DEBUG | TdAttributes::SEPT_VE_DISABLE));
+ assert!(!attrs.contains(TdAttributes::KL));
+ assert!(!attrs.contains(TdAttributes::DEBUG | TdAttributes::KL));
+
+ let reserved = vec![0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff];
+ let result = TdAttributes::parse(&reserved);
+ assert!(matches!(result, Err(Error::MalformedReport)));
+
+ let reserved = vec![0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01];
+ let result = TdAttributes::parse(&reserved);
+ assert!(matches!(result, Err(Error::MalformedReport)));
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +
use std::ffi::CString;
+
+use byteorder::{ByteOrder, LittleEndian};
+use chrono::{prelude::*, Duration};
+use mbedtls::{alloc::Box as MbedtlsBox, x509::certificate::Certificate};
+use rustc_hex::FromHex;
+use serde_json::value::RawValue;
+use sgx_isa::Report;
+
+use super::{
+ certificates::PCS_TRUST_ROOT, constants::*, policy::QuotePolicy, quote::TeeType, Error,
+};
+
+/// The TCB bundle contains all the required components to verify a quote's TCB.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct TCBBundle {
+ #[cbor(rename = "tcb_info")]
+ pub tcb_info: SignedTCBInfo,
+
+ #[cbor(rename = "qe_id")]
+ pub qe_identity: SignedQEIdentity,
+
+ #[cbor(rename = "certs")]
+ pub certificates: Vec<u8>,
+}
+
+impl TCBBundle {
+ pub(super) fn verify_certificates(
+ &self,
+ _ts: DateTime<Utc>,
+ ) -> Result<MbedtlsBox<Certificate>, Error> {
+ let raw_certs =
+ CString::new(&*self.certificates).map_err(|err| Error::TCBParseError(err.into()))?;
+ let mut cert_chain = Certificate::from_pem_multiple(raw_certs.as_bytes_with_nul())
+ .map_err(|err| Error::TCBParseError(err.into()))?;
+ if cert_chain.iter().count() != 2 {
+ return Err(Error::UnexpectedCertificateChain);
+ }
+
+ // TODO: Specify current timestamp.
+ Certificate::verify(&cert_chain, &PCS_TRUST_ROOT, None, None)
+ .map_err(|_| Error::TCBVerificationFailed)?;
+
+ Ok(cert_chain.pop_front().unwrap())
+ }
+}
+
+#[inline]
+fn encode_raw_value(value: &Box<RawValue>) -> Vec<u8> {
+ value.get().as_bytes().to_owned()
+}
+
+#[inline]
+fn decode_raw_value(value: Vec<u8>) -> Result<Box<RawValue>, cbor::DecodeError> {
+ RawValue::from_string(String::from_utf8(value).map_err(|_| cbor::DecodeError::UnexpectedType)?)
+ .map_err(|_| cbor::DecodeError::UnexpectedType)
+}
+
+/// A signed TCB info structure.
+#[derive(Clone, Debug, Default, serde::Deserialize, cbor::Encode, cbor::Decode)]
+pub struct SignedTCBInfo {
+ #[cbor(
+ rename = "tcb_info",
+ serialize_with = "encode_raw_value",
+ deserialize_with = "decode_raw_value"
+ )]
+ #[serde(rename = "tcbInfo")]
+ pub tcb_info: Box<RawValue>,
+
+ #[cbor(rename = "signature")]
+ #[serde(rename = "signature")]
+ pub signature: String,
+}
+
+impl PartialEq for SignedTCBInfo {
+ fn eq(&self, other: &SignedTCBInfo) -> bool {
+ self.tcb_info.get() == other.tcb_info.get() && self.signature == other.signature
+ }
+}
+
+impl Eq for SignedTCBInfo {}
+
+fn open_signed_tcb<'a, T: serde::Deserialize<'a>>(
+ data: &'a str,
+ signature: &str,
+ pk: &mut mbedtls::pk::Pk,
+) -> Result<T, Error> {
+ let mut hash = [0u8; 32];
+ mbedtls::hash::Md::hash(mbedtls::hash::Type::Sha256, data.as_bytes(), &mut hash)
+ .map_err(|_| Error::TCBVerificationFailed)?;
+ let sig: Vec<u8> = signature
+ .from_hex()
+ .map_err(|_| Error::TCBVerificationFailed)?;
+
+ // Convert IEEE P1363 ECDSA signature to RFC5480 ASN.1 representation.
+ if sig.len() % 2 != 0 {
+ return Err(Error::TCBVerificationFailed);
+ }
+
+ let (r_bytes, s_bytes) = sig.split_at(sig.len() / 2);
+ let r = num_bigint::BigUint::from_bytes_be(r_bytes);
+ let s = num_bigint::BigUint::from_bytes_be(s_bytes);
+
+ let sig = yasna::construct_der(|writer| {
+ writer.write_sequence(|writer| {
+ writer.next().write_biguint(&r);
+ writer.next().write_biguint(&s);
+ })
+ });
+
+ pk.verify(mbedtls::hash::Type::Sha256, &hash, &sig)
+ .map_err(|_| Error::TCBVerificationFailed)?;
+
+ serde_json::from_str(data).map_err(|err| Error::TCBParseError(err.into()))
+}
+
+impl SignedTCBInfo {
+ pub fn open(
+ &self,
+ tee_type: TeeType,
+ ts: DateTime<Utc>,
+ policy: &QuotePolicy,
+ pk: &mut mbedtls::pk::Pk,
+ ) -> Result<TCBInfo, Error> {
+ let ti: TCBInfo = open_signed_tcb(self.tcb_info.get(), &self.signature, pk)?;
+ ti.validate(tee_type, ts, policy)?;
+
+ Ok(ti)
+ }
+}
+
+/// TCB info identifier.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, serde::Deserialize)]
+pub enum TCBInfoID {
+ SGX,
+ TDX,
+ #[serde(other)]
+ #[default]
+ Invalid,
+}
+
+/// TCB info body.
+#[derive(Clone, Debug, Default, serde::Deserialize)]
+pub struct TCBInfo {
+ #[serde(rename = "id")]
+ pub id: TCBInfoID,
+
+ #[serde(rename = "version")]
+ pub version: u32,
+
+ #[serde(rename = "issueDate")]
+ pub issue_date: String,
+
+ #[serde(rename = "nextUpdate")]
+ pub next_update: String,
+
+ #[serde(rename = "fmspc")]
+ pub fmspc: String,
+
+ #[serde(rename = "pceId")]
+ pub pceid: String,
+
+ #[serde(rename = "tcbType")]
+ pub tcb_type: u32,
+
+ #[serde(rename = "tcbEvaluationDataNumber")]
+ pub tcb_evaluation_data_number: u32,
+
+ #[serde(default, rename = "tdxModule")]
+ pub tdx_module: TDXModule,
+
+ #[serde(default, rename = "tdxModuleIdentities")]
+ pub tdx_module_identities: Vec<TDXModuleIdentity>,
+
+ #[serde(rename = "tcbLevels")]
+ pub tcb_levels: Vec<TCBLevel>,
+}
+
+impl TCBInfo {
+ /// Validate the TCB info against the quote policy.
+ pub fn validate(
+ &self,
+ tee_type: TeeType,
+ ts: DateTime<Utc>,
+ policy: &QuotePolicy,
+ ) -> Result<(), Error> {
+ match (self.id, tee_type) {
+ (TCBInfoID::SGX, TeeType::SGX) => {}
+ (TCBInfoID::TDX, TeeType::TDX) => {}
+ _ => {
+ return Err(Error::TCBParseError(anyhow::anyhow!(
+ "unexpected TCB info identifier"
+ )))
+ }
+ }
+
+ if self.version != REQUIRED_TCB_INFO_VERSION {
+ return Err(Error::TCBParseError(anyhow::anyhow!(
+ "unexpected TCB info version"
+ )));
+ }
+
+ // Validate TCB info is not expired/not yet valid based on current time.
+ let issue_date = NaiveDateTime::parse_from_str(&self.issue_date, PCS_TS_FMT)
+ .map_err(|err| Error::TCBParseError(err.into()))?
+ .and_utc();
+ let _next_update = NaiveDateTime::parse_from_str(&self.next_update, PCS_TS_FMT)
+ .map_err(|err| Error::TCBParseError(err.into()))?
+ .and_utc();
+ if issue_date > ts {
+ return Err(Error::TCBExpired);
+ }
+ if ts - issue_date
+ > Duration::try_days(policy.tcb_validity_period.into())
+ .unwrap_or(DEFAULT_TCB_VALIDITY_PERIOD)
+ {
+ return Err(Error::TCBExpired);
+ }
+
+ if self.tcb_evaluation_data_number < policy.min_tcb_evaluation_data_number {
+ return Err(Error::TCBEvaluationDataNumberInvalid);
+ }
+
+ // Validate FMSPC not blacklisted.
+ let blocked = policy
+ .fmspc_blacklist
+ .iter()
+ .any(|blocked| blocked == &self.fmspc);
+ if blocked {
+ return Err(Error::BlacklistedFMSPC);
+ }
+
+ Ok(())
+ }
+
+ /// Verify and return the TCB level matching the given TCB components and PCESVN.
+ pub fn verify(
+ &self,
+ fmspc: &[u8],
+ sgx_comp_svn: &[u32; 16],
+ tdx_comp_svn: Option<&[u32; 16]>,
+ pcesvn: u32,
+ ) -> Result<TCBLevel, Error> {
+ // Validate FMSPC matches.
+ let expected_fmspc: Vec<u8> = self
+ .fmspc
+ .from_hex()
+ .map_err(|err| Error::TCBParseError(err.into()))?;
+ if fmspc != expected_fmspc {
+ return Err(Error::TCBMismatch);
+ }
+
+ // Find first matching TCB level.
+ let level = self
+ .tcb_levels
+ .iter()
+ .find(|level| level.matches(sgx_comp_svn, tdx_comp_svn, pcesvn))
+ .ok_or(Error::TCBOutOfDate)?
+ .clone();
+
+ if self.id == TCBInfoID::TDX {
+ // Perform additional TCB status evaluation for TDX module in case TEE TCB SVN at index
+ // 1 is greater or equal to 1, otherwise finish the comparison logic.
+ let tdx_comp_svn = tdx_comp_svn.ok_or(Error::TCBMismatch)?;
+ let tdx_module_version = tdx_comp_svn[1];
+ if tdx_module_version >= 1 {
+ // In order to determine TCB status of TDX module, find a matching TDX Module
+ // Identity (in tdxModuleIdentities array of TCB Info) with its id set to
+ // "TDX_<version>" where <version> matches the value of TEE TCB SVN at index 1. If a
+ // matching TDX Module Identity cannot be found, fail.
+ let tdx_module_id = format!("TDX_{:02}", tdx_module_version);
+ let tdx_module = self
+ .tdx_module_identities
+ .iter()
+ .find(|tm| tm.id == tdx_module_id)
+ .ok_or(Error::TCBOutOfDate)?;
+
+ // Otherwise, for the selected TDX Module Identity go over the sorted collection of
+ // TCB Levels starting from the first item on the list and compare its isvsvn value
+ // to the TEE TCB SVN at index 0. If TEE TCB SVN at index 0 is greater or equal to
+ // its value, read tcbStatus assigned to this TCB level, otherwise move to the next
+ // item on TCB levels list.
+ let tdx_module_level = tdx_module
+ .tcb_levels
+ .iter()
+ .find(|level| level.tcb.isv_svn as u32 <= tdx_comp_svn[0])
+ .ok_or(Error::TCBOutOfDate)?;
+ if tdx_module_level.status != TCBStatus::UpToDate {
+ return Err(Error::TCBOutOfDate);
+ }
+ }
+ }
+
+ Ok(level)
+ }
+}
+
+/// A representation of the properties of Intel's TDX SEAM module.
+#[derive(Clone, Debug, Default, serde::Deserialize)]
+pub struct TDXModule {
+ #[serde(rename = "mrsigner")]
+ pub mr_signer: String,
+
+ #[serde(rename = "attributes")]
+ pub attributes: String,
+
+ #[serde(rename = "attributesMask")]
+ pub attributes_mask: String,
+}
+
+/// A representation of the identity of the Intel's TDX SEAM module in case the platform supports
+/// more than one TDX SEAM module.
+#[derive(Clone, Debug, Default, serde::Deserialize)]
+pub struct TDXModuleIdentity {
+ #[serde(rename = "id")]
+ pub id: String,
+
+ #[serde(flatten)]
+ pub module: TDXModule,
+
+ #[serde(rename = "tcbLevels")]
+ pub tcb_levels: Vec<EnclaveTCBLevel>,
+}
+
+/// A platform TCB level.
+#[derive(Clone, Debug, Default, serde::Deserialize)]
+pub struct TCBLevel {
+ #[serde(rename = "tcb")]
+ pub tcb: TCBVersions,
+
+ #[serde(rename = "tcbDate")]
+ pub date: String,
+
+ #[serde(rename = "tcbStatus")]
+ pub status: TCBStatus,
+
+ #[serde(default, rename = "advisoryIDs")]
+ pub advisory_ids: Vec<String>,
+}
+
+impl TCBLevel {
+ /// Whether the TCB level matches the given TCB components and PCESVN.
+ pub fn matches(
+ &self,
+ sgx_comp_svn: &[u32],
+ tdx_comp_svn: Option<&[u32; 16]>,
+ pcesvn: u32,
+ ) -> bool {
+ // a) Compare all of the SGX TCB Comp SVNs retrieved from the SGX PCK Certificate (from 01 to
+ // 16) with the corresponding values in the TCB Level. If all SGX TCB Comp SVNs in the
+ // certificate are greater or equal to the corresponding values in TCB Level, go to b,
+ // otherwise move to the next item on TCB Levels list.
+ for (i, comp) in self.tcb.sgx_components.iter().enumerate() {
+ // At least one SVN is lower, no match.
+ if sgx_comp_svn[i] < comp.svn {
+ return false;
+ }
+ }
+
+ // b) Compare PCESVN value retrieved from the SGX PCK certificate with the corresponding value
+ // in the TCB Level. If it is greater or equal to the value in TCB Level, read status
+ // assigned to this TCB level (in case of SGX) or go to c (in case of TDX). Otherwise,
+ // move to the next item on TCB Levels list.
+ if self.tcb.pcesvn < pcesvn {
+ return false;
+ }
+
+ if let Some(tdx_comp_svn) = tdx_comp_svn {
+ // c) Compare SVNs in TEE TCB SVN array retrieved from TD Report in Quote (from index 0 to
+ // 15 if TEE TCB SVN at index 1 is set to 0, or from index 2 to 15 otherwise) with the
+ // corresponding values of SVNs in tdxtcbcomponents array of TCB Level. If all TEE TCB
+ // SVNs in the TD Report are greater or equal to the corresponding values in TCB Level,
+ // read tcbStatus assigned to this TCB level. Otherwise, move to the next item on TCB
+ // Levels list.
+ let comps = self.tcb.tdx_components.iter().enumerate();
+ let offset = if tdx_comp_svn[1] != 0 { 2 } else { 0 };
+
+ for (i, comp) in comps.skip(offset) {
+ // At least one SVN is lower, no match.
+ if tdx_comp_svn[i] < comp.svn {
+ return false;
+ }
+ }
+ }
+
+ // Match.
+ true
+ }
+}
+
+/// TCB versions.
+#[derive(Clone, Debug, Default, serde::Deserialize)]
+pub struct TCBVersions {
+ #[serde(rename = "pcesvn")]
+ pub pcesvn: u32,
+
+ #[serde(rename = "sgxtcbcomponents")]
+ pub sgx_components: [TCBComponent; 16],
+
+ #[serde(default, rename = "tdxtcbcomponents")]
+ pub tdx_components: [TCBComponent; 16],
+}
+
+/// A TCB component.
+#[derive(Clone, Debug, Default, serde::Deserialize)]
+pub struct TCBComponent {
+ #[serde(rename = "svn")]
+ pub svn: u32,
+
+ #[serde(default, rename = "category")]
+ pub category: String,
+
+ #[serde(default, rename = "type")]
+ pub tcb_comp_type: String,
+}
+
+/// TCB status.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, serde::Deserialize)]
+pub enum TCBStatus {
+ UpToDate,
+ SWHardeningNeeded,
+ ConfigurationNeeded,
+ ConfigurationAndSWHardeningNeeded,
+ OutOfDate,
+ OutOfDateConfigurationNeeded,
+ Revoked,
+ #[serde(other)]
+ #[default]
+ Invalid,
+}
+
+/// A signed QE identity structure.
+#[derive(Clone, Debug, Default, serde::Deserialize, cbor::Encode, cbor::Decode)]
+pub struct SignedQEIdentity {
+ #[cbor(
+ rename = "enclave_identity",
+ serialize_with = "encode_raw_value",
+ deserialize_with = "decode_raw_value"
+ )]
+ #[serde(rename = "enclaveIdentity")]
+ pub enclave_identity: Box<RawValue>,
+
+ #[cbor(rename = "signature")]
+ #[serde(rename = "signature")]
+ pub signature: String,
+}
+
+impl PartialEq for SignedQEIdentity {
+ fn eq(&self, other: &SignedQEIdentity) -> bool {
+ self.enclave_identity.get() == other.enclave_identity.get()
+ && self.signature == other.signature
+ }
+}
+
+impl Eq for SignedQEIdentity {}
+
+impl SignedQEIdentity {
+ pub fn open(
+ &self,
+ tee_type: TeeType,
+ ts: DateTime<Utc>,
+ policy: &QuotePolicy,
+ pk: &mut mbedtls::pk::Pk,
+ ) -> Result<QEIdentity, Error> {
+ let qe: QEIdentity = open_signed_tcb(self.enclave_identity.get(), &self.signature, pk)?;
+ qe.validate(tee_type, ts, policy)?;
+
+ Ok(qe)
+ }
+}
+
+/// QE identity identifier.
+#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, serde::Deserialize)]
+#[allow(non_camel_case_types)]
+pub enum QEIdentityID {
+ QE,
+ TD_QE,
+ #[serde(other)]
+ #[default]
+ Invalid,
+}
+
+/// QE identity body.
+#[derive(Clone, Debug, Default, serde::Deserialize)]
+pub struct QEIdentity {
+ #[serde(rename = "id")]
+ pub id: QEIdentityID,
+
+ #[serde(rename = "version")]
+ pub version: u32,
+
+ #[serde(rename = "issueDate")]
+ pub issue_date: String,
+
+ #[serde(rename = "nextUpdate")]
+ pub next_update: String,
+
+ #[serde(rename = "tcbEvaluationDataNumber")]
+ pub tcb_evaluation_data_number: u32,
+
+ #[serde(rename = "miscselect")]
+ pub miscselect: String,
+
+ #[serde(rename = "miscselectMask")]
+ pub miscselect_mask: String,
+
+ #[serde(rename = "attributes")]
+ pub attributes: String,
+
+ #[serde(rename = "attributesMask")]
+ pub attributes_mask: String,
+
+ #[serde(rename = "mrsigner")]
+ pub mr_signer: String,
+
+ #[serde(rename = "isvprodid")]
+ pub isv_prod_id: u16,
+
+ #[serde(rename = "tcbLevels")]
+ pub tcb_levels: Vec<EnclaveTCBLevel>,
+
+ #[serde(default, rename = "advisoryIDs")]
+ pub advisory_ids: Vec<String>,
+}
+
+impl QEIdentity {
+ /// Validate the QE identity against the quote policy.
+ pub fn validate(
+ &self,
+ tee_type: TeeType,
+ ts: DateTime<Utc>,
+ policy: &QuotePolicy,
+ ) -> Result<(), Error> {
+ match (self.id, tee_type) {
+ (QEIdentityID::QE, TeeType::SGX) => {}
+ (QEIdentityID::TD_QE, TeeType::TDX) => {}
+ _ => return Err(Error::TCBParseError(anyhow::anyhow!("unexpected QE ID"))),
+ }
+
+ if self.version != REQUIRED_QE_IDENTITY_VERSION {
+ return Err(Error::TCBParseError(anyhow::anyhow!(
+ "unexpected QE identity version"
+ )));
+ }
+
+ // Validate QE identity is not expired/not yet valid based on current time.
+ let issue_date = NaiveDateTime::parse_from_str(&self.issue_date, PCS_TS_FMT)
+ .map_err(|err| Error::TCBParseError(err.into()))?
+ .and_utc();
+ let _next_update = NaiveDateTime::parse_from_str(&self.next_update, PCS_TS_FMT)
+ .map_err(|err| Error::TCBParseError(err.into()))?
+ .and_utc();
+ if issue_date > ts {
+ return Err(Error::TCBExpired);
+ }
+ if ts - issue_date
+ > Duration::try_days(policy.tcb_validity_period.into())
+ .unwrap_or(DEFAULT_TCB_VALIDITY_PERIOD)
+ {
+ return Err(Error::TCBExpired);
+ }
+
+ if self.tcb_evaluation_data_number < policy.min_tcb_evaluation_data_number {
+ return Err(Error::TCBEvaluationDataNumberInvalid);
+ }
+
+ Ok(())
+ }
+
+ /// Verify the QE report against the QE identity.
+ pub fn verify(&self, report: &Report) -> Result<(), Error> {
+ // Verify if MRSIGNER field retrieved from SGX Enclave Report is equal to the value of
+ // mrsigner field in QE Identity.
+ let expected_mr_signer: Vec<u8> = self
+ .mr_signer
+ .from_hex()
+ .map_err(|_| Error::TCBParseError(anyhow::anyhow!("malformed QE MRSIGNER")))?;
+ if expected_mr_signer != report.mrsigner {
+ return Err(Error::TCBVerificationFailed);
+ }
+
+ // Verify if ISVPRODID field retrieved from SGX Enclave Report is equal to the value of
+ // isvprodid field in QE Identity.
+ if self.isv_prod_id != report.isvprodid {
+ return Err(Error::TCBVerificationFailed);
+ }
+
+ // Apply miscselectMask (binary mask) from QE Identity to MISCSELECT field retrieved from
+ // SGX Enclave Report. Verify if the outcome (miscselectMask & MISCSELECT) is equal to the
+ // value of miscselect field in QE Identity.
+ let raw_miscselect: Vec<u8> = self
+ .miscselect
+ .from_hex()
+ .map_err(|_| Error::TCBParseError(anyhow::anyhow!("malformed QE miscselect")))?;
+ if raw_miscselect.len() != 4 {
+ return Err(Error::TCBParseError(anyhow::anyhow!(
+ "malformed QE miscselect"
+ )));
+ }
+ let raw_miscselect_mask: Vec<u8> = self
+ .miscselect_mask
+ .from_hex()
+ .map_err(|_| Error::TCBParseError(anyhow::anyhow!("malformed QE miscselect mask")))?;
+ if raw_miscselect_mask.len() != 4 {
+ return Err(Error::TCBParseError(anyhow::anyhow!(
+ "malformed QE miscselect"
+ )));
+ }
+ let expected_miscselect = LittleEndian::read_u32(&raw_miscselect);
+ let miscselect_mask = LittleEndian::read_u32(&raw_miscselect_mask);
+ if report.miscselect.bits() & miscselect_mask != expected_miscselect {
+ return Err(Error::TCBVerificationFailed);
+ }
+
+ // Apply attributesMask (binary mask) from QE Identity to ATTRIBUTES field retrieved from
+ // SGX Enclave Report. Verify if the outcome (attributesMask & ATTRIBUTES) is equal to the
+ // value of attributes field in QE Identity.
+ let raw_attributes: Vec<u8> = self
+ .attributes
+ .from_hex()
+ .map_err(|_| Error::TCBParseError(anyhow::anyhow!("malformed QE attributes")))?;
+ if raw_attributes.len() != 16 {
+ return Err(Error::TCBParseError(anyhow::anyhow!(
+ "malformed QE attributes"
+ )));
+ }
+ let raw_attributes_mask: Vec<u8> = self
+ .attributes_mask
+ .from_hex()
+ .map_err(|_| Error::TCBParseError(anyhow::anyhow!("malformed QE attributes mask")))?;
+ if raw_attributes_mask.len() != 16 {
+ return Err(Error::TCBParseError(anyhow::anyhow!(
+ "malformed QE attributes"
+ )));
+ }
+ let expected_flags = LittleEndian::read_u64(&raw_attributes[..8]);
+ let expected_xfrm = LittleEndian::read_u64(&raw_attributes[8..]);
+ let flags_mask = LittleEndian::read_u64(&raw_attributes_mask[..8]);
+ let xfrm_mask = LittleEndian::read_u64(&raw_attributes_mask[8..]);
+ if report.attributes.flags.bits() & flags_mask != expected_flags {
+ return Err(Error::TCBVerificationFailed);
+ }
+ if report.attributes.xfrm & xfrm_mask != expected_xfrm {
+ return Err(Error::TCBVerificationFailed);
+ }
+
+ // Determine a TCB status of the Quoting Enclave.
+ //
+ // Go over the list of TCB Levels (descending order) and find the one that has ISVSVN that
+ // is lower or equal to the ISVSVN value from SGX Enclave Report.
+ if let Some(level) = self
+ .tcb_levels
+ .iter()
+ .find(|level| level.tcb.isv_svn <= report.isvsvn)
+ {
+ // Ensure that the TCB is up to date.
+ if level.status == TCBStatus::UpToDate {
+ return Ok(());
+ }
+ }
+
+ Err(Error::TCBOutOfDate)
+ }
+}
+
+/// An enclave TCB level.
+#[derive(Clone, Debug, Default, serde::Deserialize)]
+pub struct EnclaveTCBLevel {
+ #[serde(rename = "tcb")]
+ pub tcb: EnclaveTCBVersions,
+
+ #[serde(rename = "tcbDate")]
+ pub date: String,
+
+ #[serde(rename = "tcbStatus")]
+ pub status: TCBStatus,
+
+ #[serde(default, rename = "advisoryIDs")]
+ pub advisory_ids: Vec<String>,
+}
+
+/// Enclave TCB versions.
+#[derive(Clone, Debug, Default, serde::Deserialize)]
+pub struct EnclaveTCBVersions {
+ #[serde(rename = "isvsvn")]
+ pub isv_svn: u16,
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +
//! Various parsing utilities.
+use std::{borrow::Cow, mem};
+
+use super::Error;
+
+pub trait TakePrefix: Sized {
+ fn take_prefix(&mut self, mid: usize) -> Result<Self, Error>;
+}
+
+impl<'a, T: 'a> TakePrefix for &'a [T] {
+ fn take_prefix(&mut self, mid: usize) -> Result<Self, Error> {
+ if let (Some(prefix), Some(rest)) = (self.get(..mid), self.get(mid..)) {
+ *self = rest;
+ Ok(prefix)
+ } else {
+ Err(Error::QuoteParseError(
+ "unexpected end of quote".to_string(),
+ ))
+ }
+ }
+}
+
+impl<'a, T: 'a + Clone> TakePrefix for Cow<'a, [T]> {
+ fn take_prefix(&mut self, mid: usize) -> Result<Self, Error> {
+ if mid <= self.len() {
+ match *self {
+ Cow::Borrowed(ref mut slice) => slice.take_prefix(mid).map(Cow::Borrowed),
+ Cow::Owned(ref mut vec) => {
+ let rest = vec.split_off(mid);
+ Ok(Cow::Owned(mem::replace(vec, rest)))
+ }
+ }
+ } else {
+ Err(Error::QuoteParseError(
+ "unexpected end of quote".to_string(),
+ ))
+ }
+ }
+}
+
+impl<'a> TakePrefix for &'a str {
+ fn take_prefix(&mut self, mid: usize) -> Result<Self, Error> {
+ if let (Some(prefix), Some(rest)) = (self.get(..mid), self.get(mid..)) {
+ *self = rest;
+ Ok(prefix)
+ } else {
+ Err(Error::QuoteParseError(
+ "unexpected end of quote".to_string(),
+ ))
+ }
+ }
+}
+
+impl<'a> TakePrefix for Cow<'a, str> {
+ fn take_prefix(&mut self, mid: usize) -> Result<Self, Error> {
+ if mid <= self.len() {
+ match *self {
+ Cow::Borrowed(ref mut slice) => slice.take_prefix(mid).map(Cow::Borrowed),
+ Cow::Owned(ref mut vec) => {
+ let rest = vec.split_off(mid);
+ Ok(Cow::Owned(mem::replace(vec, rest)))
+ }
+ }
+ } else {
+ Err(Error::QuoteParseError(
+ "unexpected end of quote".to_string(),
+ ))
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +
//! Wrappers for sealing secrets to the enclave in cold storage.
+use anyhow::{format_err, Error};
+use rand::{rngs::OsRng, Rng};
+use sgx_isa::Keypolicy;
+use zeroize::Zeroize;
+
+use crate::common::{
+ crypto::mrae::deoxysii::{DeoxysII, NONCE_SIZE, TAG_SIZE},
+ sgx::egetkey::egetkey,
+};
+
+/// Seal a secret to the enclave.
+///
+/// The `context` field is a domain separation tag.
+pub fn seal(key_policy: Keypolicy, context: &[u8], data: &[u8]) -> Vec<u8> {
+ let mut rng = OsRng {};
+
+ // Encrypt the raw policy.
+ let mut nonce = [0u8; NONCE_SIZE];
+ rng.fill(&mut nonce);
+ let d2 = new_deoxysii(key_policy, context);
+ let mut ciphertext = d2.seal(&nonce, data, vec![]);
+ ciphertext.extend_from_slice(&nonce);
+
+ ciphertext
+}
+
+/// Unseal a previously sealed secret to the enclave.
+///
+/// The `context` field is a domain separation tag.
+pub fn unseal(
+ key_policy: Keypolicy,
+ context: &[u8],
+ ciphertext: &[u8],
+) -> Result<Option<Vec<u8>>, Error> {
+ let ct_len = ciphertext.len();
+ if ct_len == 0 {
+ return Ok(None);
+ }
+ if ct_len < TAG_SIZE + NONCE_SIZE {
+ return Err(format_err!("ciphertext is corrupted: invalid size"));
+ }
+ let ct_len = ct_len - NONCE_SIZE;
+
+ // Split the ciphertext || tag || nonce.
+ let mut nonce = [0u8; NONCE_SIZE];
+ nonce.copy_from_slice(&ciphertext[ct_len..]);
+ let ciphertext = &ciphertext[..ct_len];
+
+ let d2 = new_deoxysii(key_policy, context);
+
+ match d2.open(&nonce, ciphertext.to_vec(), vec![]) {
+ Ok(plaintext) => Ok(Some(plaintext)),
+ Err(_) => Err(format_err!("ciphertext is corrupted")),
+ }
+}
+
+/// Creates a new Deoxys-II instance initialized with an SGX sealing key derived
+/// from the results of the `EGETKEY`instruction.
+///
+/// The `context` field is a domain separation tag.
+pub fn new_deoxysii(key_policy: Keypolicy, context: &[u8]) -> DeoxysII {
+ let mut seal_key = egetkey(key_policy, context);
+ let d2 = DeoxysII::new(&seal_key);
+ seal_key.zeroize();
+
+ d2
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn test_seal_unseal() {
+ // Test different policies.
+ let sealed_a = seal(Keypolicy::MRSIGNER, b"MRSIGNER", b"Mr. Signer");
+ let unsealed_a = unseal(Keypolicy::MRSIGNER, b"MRSIGNER", &sealed_a);
+ assert_eq!(unsealed_a.unwrap(), Some(b"Mr. Signer".to_vec()));
+
+ let sealed_b = seal(Keypolicy::MRENCLAVE, b"MRENCLAVE", b"Mr. Enclave");
+ let unsealed_b = unseal(Keypolicy::MRENCLAVE, b"MRENCLAVE", &sealed_b);
+ assert_eq!(unsealed_b.unwrap(), Some(b"Mr. Enclave".to_vec()));
+
+ // Test zero-length ciphertext.
+ let unsealed_c = unseal(Keypolicy::MRENCLAVE, b"MRENCLAVE", b"");
+ assert_eq!(unsealed_c.unwrap(), None);
+ }
+
+ #[test]
+ fn test_incorrect_context() {
+ // Test incorrect context.
+ let sealed_b = seal(Keypolicy::MRENCLAVE, b"MRENCLAVE1", b"Mr. Enclave");
+ let unsealed_b = unseal(Keypolicy::MRENCLAVE, b"MRENCLAVE2", &sealed_b);
+ assert_eq!(unsealed_b.is_err(), true);
+ }
+
+ #[test]
+ fn test_incorrect_ciphertext_a() {
+ let sealed_b = seal(Keypolicy::MRENCLAVE, b"MRENCLAVE", b"Mr. Enclave");
+ let unsealed_b = unseal(Keypolicy::MRENCLAVE, b"MRENCLAVE", &sealed_b[..2]);
+ assert_eq!(unsealed_b.is_err(), true);
+ }
+
+ #[test]
+ fn test_incorrect_ciphertext_b() {
+ let mut sealed_b = seal(Keypolicy::MRENCLAVE, b"MRENCLAVE", b"Mr. Enclave");
+ sealed_b[0] = sealed_b[0].wrapping_add(1);
+ let unsealed_b = unseal(Keypolicy::MRENCLAVE, b"MRENCLAVE", &sealed_b);
+ assert_eq!(unsealed_b.is_err(), true);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +
//! Runtime time source.
+use std::{
+ sync::Mutex,
+ time::{Duration, SystemTime, UNIX_EPOCH},
+};
+
+use lazy_static::lazy_static;
+use slog::error;
+
+use crate::common::{logger::get_logger, process};
+
+const INITIAL_MINIMUM_TIME: i64 = 1704067200; // Mon, 01 Jan 2024 00:00:00 UTC
+
+struct TimeSource {
+ inner: Mutex<Inner>,
+}
+
+struct Inner {
+ timestamp: i64,
+}
+
+/// Returns the number of seconds since the UNIX epoch. The time returned
+/// is guaranteed to never decrease within each enclave instance (though it
+/// may decrease iff the enclave is re-launched).
+///
+/// The returned timestamp MUST NOT be trusted on in any way, as the underlying
+/// time source is reliant on the host operating system.
+pub fn insecure_posix_time() -> i64 {
+ let mut inner = TIME_SOURCE.inner.lock().unwrap();
+
+ let now = SystemTime::now().duration_since(UNIX_EPOCH).unwrap();
+ let now = now.as_secs() as i64;
+
+ if now < inner.timestamp {
+ error!(
+ get_logger("runtime/time"),
+ "clock appeared to have ran backwards"
+ );
+ process::abort();
+ }
+ inner.timestamp = now;
+
+ inner.timestamp
+}
+
+// Returns `insecure_posix_time` as SystemTime.
+pub fn insecure_posix_system_time() -> SystemTime {
+ UNIX_EPOCH + Duration::from_secs(insecure_posix_time() as u64)
+}
+
+/// Force update the minimum timestamp from a semi-trusted source (eg: the AVR
+/// timestamp), under the assumption that the semi-trusted source is more trust
+/// worthy than the host operating system.
+pub(crate) fn update_insecure_posix_time(timestamp: i64) {
+ let mut inner = TIME_SOURCE.inner.lock().unwrap();
+
+ if timestamp > inner.timestamp {
+ inner.timestamp = timestamp;
+ }
+
+ // The IAS clock and local clock should be closely synced, and minor
+ // differences in NTP implementations (eg: smear vs no smear), should
+ // be masked by the fact that the AVR timestamp will be a minimum of
+ // 1 RTT in the past.
+}
+
+lazy_static! {
+ static ref TIME_SOURCE: TimeSource = TimeSource {
+ inner: Mutex::new(Inner {
+ timestamp: INITIAL_MINIMUM_TIME,
+ })
+ };
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +
//! Protocol and runtime versioning.
+// NOTE: This should be kept in sync with go/common/version/version.go.
+
+/// A protocol or runtime version.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct Version {
+ #[cbor(optional)]
+ pub major: u16,
+
+ #[cbor(optional)]
+ pub minor: u16,
+
+ #[cbor(optional)]
+ pub patch: u16,
+}
+
+#[macro_export]
+macro_rules! version_from_cargo {
+ () => {
+ Version::new(
+ env!("CARGO_PKG_VERSION_MAJOR").parse::<u16>().unwrap(),
+ env!("CARGO_PKG_VERSION_MINOR").parse::<u16>().unwrap(),
+ env!("CARGO_PKG_VERSION_PATCH").parse::<u16>().unwrap(),
+ )
+ };
+}
+
+impl Version {
+ /// Creates a new version with given major, minor, and patch segments.
+ pub const fn new(major: u16, minor: u16, patch: u16) -> Version {
+ Version {
+ major,
+ minor,
+ patch,
+ }
+ }
+
+ /// Checks if two versions are compatible.
+ pub fn is_compatible_with(&self, other: &Version) -> bool {
+ self.major == other.major
+ }
+}
+
+// Returns the version as a platform-dependent u64.
+impl From<Version> for u64 {
+ fn from(val: Version) -> Self {
+ ((val.major as u64) << 32) | ((val.minor as u64) << 16) | (val.patch as u64)
+ }
+}
+
+// Creates the version from a platform-dependent u64.
+impl From<u64> for Version {
+ fn from(v: u64) -> Version {
+ Version {
+ major: ((v >> 32) & 0xffff) as u16,
+ minor: ((v >> 16) & 0xffff) as u16,
+ patch: (v & 0xffff) as u16,
+ }
+ }
+}
+
+// Version of the protocol used for communication between the Oasis node(s)
+// and the runtime. This version MUST be compatible with the one supported by
+// the worker host.
+pub const PROTOCOL_VERSION: Version = Version {
+ major: 5,
+ minor: 1,
+ patch: 0,
+};
+
+/// Protocol versions.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct ProtocolVersions {
+ pub consensus_protocol: Version,
+ pub runtime_host_protocol: Version,
+ pub runtime_committee_protocol: Version,
+}
+
+#[cfg(test)]
+mod test {
+ use super::Version;
+
+ #[test]
+ fn test_version() {
+ assert!(Version {
+ major: 32,
+ minor: 25,
+ patch: 10,
+ }
+ .is_compatible_with(&Version {
+ major: 32,
+ minor: 10,
+ patch: 100,
+ }),);
+
+ let v = Version {
+ major: 17,
+ minor: 11,
+ patch: 1,
+ };
+ let vi: u64 = v.into();
+ assert_eq!(v, Version::from(vi));
+ }
+
+ #[test]
+ fn test_version_u64() {
+ for v in vec![
+ Version::default(),
+ Version {
+ major: 0,
+ minor: 0,
+ patch: 0,
+ },
+ Version {
+ major: 1,
+ minor: 1,
+ patch: 1,
+ },
+ Version {
+ major: 10,
+ minor: 20,
+ patch: 30,
+ },
+ Version {
+ major: 300,
+ minor: 400,
+ patch: 500,
+ },
+ Version {
+ major: 30000,
+ minor: 40000,
+ patch: 50000,
+ },
+ ] {
+ let vi: u64 = v.into();
+ assert_eq!(Version::from(vi), v)
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +
/// Version key used in serialized form.
+pub const VERSION_KEY: &str = "v";
+
+/// A generic versioned serializable data structure.
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub struct Versioned<T> {
+ pub version: u16,
+ pub inner: T,
+}
+
+impl<T> Versioned<T> {
+ /// Create a new versioned structure.
+ pub fn new(version: u16, inner: T) -> Self {
+ Self { version, inner }
+ }
+}
+
+impl<T: cbor::EncodeAsMap> cbor::Encode for Versioned<T> {
+ fn into_cbor_value(self) -> cbor::Value {
+ let mut inner = cbor::EncodeAsMap::into_cbor_map(self.inner);
+ // Add version to the given map.
+ let key = cbor::values::IntoCborValue::into_cbor_value(VERSION_KEY);
+ inner.push((key, self.version.into_cbor_value()));
+ cbor::Value::Map(inner)
+ }
+}
+
+impl<T: cbor::Decode> cbor::Decode for Versioned<T> {
+ fn try_from_cbor_value(value: cbor::Value) -> Result<Self, cbor::DecodeError> {
+ match value {
+ cbor::Value::Map(mut items) => {
+ // Take the version field from the map and decode the rest.
+ let key = cbor::values::IntoCborValue::into_cbor_value(VERSION_KEY);
+ let (index, _) = items
+ .iter()
+ .enumerate()
+ .find(|(_, v)| v.0 == key)
+ .ok_or(cbor::DecodeError::MissingField)?;
+ let version = items.remove(index).1;
+
+ Ok(Self {
+ version: cbor::Decode::try_from_cbor_value(version)?,
+ inner: cbor::Decode::try_from_cbor_value(cbor::Value::Map(items))?,
+ })
+ }
+ _ => Err(cbor::DecodeError::UnexpectedType),
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +
//! Runtime configuration.
+use crate::{common::version::Version, consensus::verifier::TrustRoot, types::Features};
+
+/// Global runtime configuration.
+#[derive(Clone, Debug, Default)]
+pub struct Config {
+ /// Semantic runtime version.
+ pub version: Version,
+ /// Optional trust root for consensus layer integrity verification.
+ pub trust_root: Option<TrustRoot>,
+ /// Storage configuration.
+ pub storage: Storage,
+ /// Advertised runtime features.
+ pub features: Features,
+ /// Whether storage state should be persisted between transaction check invocations. The state
+ /// is invalidated on the next round.
+ pub persist_check_tx_state: bool,
+}
+
+/// Storage-related configuration.
+#[derive(Clone, Debug)]
+pub struct Storage {
+ /// The maximum number of tree nodes held by the cache before eviction.
+ /// A zero value denotes unlimited capacity.
+ pub cache_node_capacity: usize,
+ /// The total size, in bytes, of values held by the cache before eviction.
+ /// A zero value denotes unlimited capacity.
+ pub cache_value_capacity: usize,
+}
+
+impl Default for Storage {
+ fn default() -> Self {
+ Self {
+ cache_node_capacity: 100_000,
+ cache_value_capacity: 32 * 1024 * 1024, // 32 MiB
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +
//! Consensus account address structures.
+use std::{convert::TryInto, fmt};
+
+use anyhow::{anyhow, Result};
+use bech32::{Bech32, Hrp};
+use lazy_static::lazy_static;
+
+use crate::common::{
+ crypto::{hash::Hash, signature::PublicKey},
+ key_format::KeyFormatAtom,
+ namespace::Namespace,
+};
+
+lazy_static! {
+ /// Common pool reserved address.
+ pub static ref COMMON_POOL_ADDRESS: Address = Address::from_pk(&PublicKey::from("1abe11edc001ffffffffffffffffffffffffffffffffffffffffffffffffffff"));
+
+ /// Per-block fee accumulator reserved address.
+ pub static ref FEE_ACC_ADDRESS: Address = Address::from_pk(&PublicKey::from("1abe11edfeeaccffffffffffffffffffffffffffffffffffffffffffffffffff"));
+
+ /// Governance deposits reserved address.
+ pub static ref GOVERNANCE_DEPOSITS_ADDRESS: Address = Address::from_pk(&PublicKey::from("1abe11eddeaccfffffffffffffffffffffffffffffffffffffffffffffffffff"));
+}
+
+const ADDRESS_VERSION_SIZE: usize = 1;
+const ADDRESS_DATA_SIZE: usize = 20;
+const ADDRESS_SIZE: usize = ADDRESS_VERSION_SIZE + ADDRESS_DATA_SIZE;
+
+// V0 staking addres.
+const ADDRESS_V0_CONTEXT: &[u8] = b"oasis-core/address: staking";
+const ADDRESS_V0_VERSION: u8 = 0;
+
+// V0 runtime address.
+const ADDRESS_RUNTIME_V0_CONTEXT: &[u8] = b"oasis-core/address: runtime";
+const ADDRESS_RUNTIME_V0_VERSION: u8 = 0;
+
+const ADDRESS_BECH32_HRP: Hrp = Hrp::parse_unchecked("oasis");
+
+/// A staking account address.
+#[derive(Clone, Default, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub struct Address([u8; ADDRESS_SIZE]);
+
+impl Address {
+ /// Creates a new address from a context, version and data.
+ pub fn new(ctx: &'static [u8], version: u8, data: &[u8]) -> Self {
+ let h = Hash::digest_bytes_list(&[ctx, &[version], data]);
+
+ let mut a = [0; ADDRESS_SIZE];
+ a[..ADDRESS_VERSION_SIZE].copy_from_slice(&[version]);
+ a[ADDRESS_VERSION_SIZE..].copy_from_slice(h.truncated(ADDRESS_DATA_SIZE));
+
+ Address(a)
+ }
+
+ /// Creates a new address from a public key.
+ pub fn from_pk(pk: &PublicKey) -> Self {
+ Address::new(ADDRESS_V0_CONTEXT, ADDRESS_V0_VERSION, pk.as_ref())
+ }
+
+ /// Creates a new runtime address.
+ pub fn from_runtime_id(id: &Namespace) -> Self {
+ Address::new(
+ ADDRESS_RUNTIME_V0_CONTEXT,
+ ADDRESS_RUNTIME_V0_VERSION,
+ id.as_ref(),
+ )
+ }
+
+ /// Tries to create a new address from Bech32-encoded string.
+ pub fn from_bech32(data: &str) -> Result<Self> {
+ let (hrp, data) = bech32::decode(data).map_err(|_| anyhow!("malformed address"))?;
+
+ if hrp != ADDRESS_BECH32_HRP {
+ return Err(anyhow!("malformed address"));
+ }
+
+ let sized: &[u8; ADDRESS_SIZE] = &data.as_slice().try_into()?;
+ Ok(sized.into())
+ }
+
+ /// Converts an address to Bech32 representation.
+ pub fn to_bech32(&self) -> String {
+ bech32::encode::<Bech32>(ADDRESS_BECH32_HRP, &self.0).unwrap()
+ }
+}
+
+impl fmt::LowerHex for Address {
+ fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+ for i in &self.0[..] {
+ write!(f, "{i:02x}")?;
+ }
+ Ok(())
+ }
+}
+
+impl<'a> From<&'a str> for Address {
+ fn from(s: &'a str) -> Address {
+ Address::from_bech32(s).unwrap()
+ }
+}
+
+impl AsRef<[u8]> for Address {
+ fn as_ref(&self) -> &[u8] {
+ &self.0
+ }
+}
+
+impl From<Address> for [u8; ADDRESS_SIZE] {
+ fn from(val: Address) -> Self {
+ val.0
+ }
+}
+
+impl From<&[u8; ADDRESS_SIZE]> for Address {
+ fn from(b: &[u8; ADDRESS_SIZE]) -> Address {
+ let mut data = [0; ADDRESS_SIZE];
+ data.copy_from_slice(b);
+ Address(data)
+ }
+}
+
+impl fmt::Debug for Address {
+ fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+ write!(f, "{}", self.to_bech32())?;
+ Ok(())
+ }
+}
+
+impl cbor::Encode for Address {
+ fn into_cbor_value(self) -> cbor::Value {
+ cbor::Value::ByteString(self.as_ref().to_vec())
+ }
+}
+
+impl cbor::Decode for Address {
+ fn try_default() -> Result<Self, cbor::DecodeError> {
+ Ok(Default::default())
+ }
+
+ fn try_from_cbor_value(value: cbor::Value) -> Result<Self, cbor::DecodeError> {
+ match value {
+ cbor::Value::ByteString(data) => Ok(Address(
+ data.try_into()
+ .map_err(|_| cbor::DecodeError::UnexpectedType)?,
+ )),
+ _ => Err(cbor::DecodeError::UnexpectedType),
+ }
+ }
+}
+
+impl KeyFormatAtom for Address {
+ fn size() -> usize {
+ ADDRESS_SIZE
+ }
+
+ fn encode_atom(self) -> Vec<u8> {
+ self.as_ref().to_vec()
+ }
+
+ fn decode_atom(data: &[u8]) -> Self
+ where
+ Self: Sized,
+ {
+ let sized: &[u8; ADDRESS_SIZE] =
+ &data.try_into().expect("address: invalid decode atom data");
+ sized.into()
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use super::Address;
+ use crate::common::{crypto::signature::PublicKey, namespace::Namespace};
+
+ #[test]
+ fn test_address() {
+ let pk =
+ PublicKey::from("badadd1e55ffffffffffffffffffffffffffffffffffffffffffffffffffffff");
+
+ let addr = Address::from_pk(&pk);
+ assert_eq!(
+ addr.to_bech32(),
+ "oasis1qryqqccycvckcxp453tflalujvlf78xymcdqw4vz"
+ );
+
+ assert_eq!(
+ Address::from("oasis1qryqqccycvckcxp453tflalujvlf78xymcdqw4vz").to_bech32(),
+ "oasis1qryqqccycvckcxp453tflalujvlf78xymcdqw4vz"
+ );
+
+ let runtime_id =
+ Namespace::from("80000000000000002aff7f6dfb62720cfd735f2b037b81572fad1b7937d826b3");
+ let addr = Address::from_runtime_id(&runtime_id);
+ assert_eq!(
+ addr.to_bech32(),
+ "oasis1qpllh99nhwzrd56px4txvl26atzgg4f3a58jzzad"
+ );
+ }
+
+ #[test]
+ fn test_deserialization() {
+ let addr: Address = cbor::from_slice(&[0xF6]).unwrap();
+ assert_eq!(
+ addr.to_bech32(),
+ "oasis1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq0ltrq9"
+ );
+ }
+}
+/// The number of intervals (epochs) since a fixed instant in time/block height (epoch date/height).
+pub type EpochTime = u64;
+
+/// An invalid epoch time.
+pub const EPOCH_INVALID: EpochTime = 0xffffffffffffffff;
+
+/// The epoch state.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct EpochTimeState {
+ pub epoch: EpochTime,
+ pub height: i64,
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +
//! Governance structures.
+//!
+//! # Note
+//!
+//! This **MUST** be kept in sync with go/governance/api.
+//!
+use std::collections::BTreeMap;
+
+use crate::{
+ common::{quantity::Quantity, version::ProtocolVersions},
+ consensus::beacon::EpochTime,
+};
+
+/// A governance vote.
+#[derive(
+ Clone, Debug, Default, PartialEq, Eq, Hash, PartialOrd, Ord, cbor::Encode, cbor::Decode,
+)]
+#[repr(u8)]
+pub enum Vote {
+ /// Invalid vote that should never be explicitly set.
+ #[default]
+ Invalid = 0,
+ /// Yes Vote.
+ Yes = 1,
+ /// No vote.
+ No = 2,
+ /// Abstained.
+ Abstain = 3,
+}
+
+/// Vote for a proposal.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct ProposalVote {
+ /// Unique identifier of a proposal.
+ pub id: u64,
+
+ /// Proposal vote.
+ pub vote: Vote,
+}
+
+/// Upgrade proposal content.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct UpgradeProposal {
+ pub v: u16,
+ pub handler: String,
+ pub target: ProtocolVersions,
+ pub epoch: EpochTime,
+}
+
+/// Cancel proposal content.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct CancelUpgradeProposal {
+ pub proposal_id: u64,
+}
+
+/// Change parameters proposal content.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct ChangeParametersProposal {
+ pub module: String,
+ pub changes: Option<cbor::Value>,
+}
+
+/// Consensus layer governance proposal content.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct ProposalContent {
+ #[cbor(optional)]
+ pub upgrade: Option<UpgradeProposal>,
+ #[cbor(optional)]
+ pub cancel_upgrade: Option<CancelUpgradeProposal>,
+ #[cbor(optional)]
+ pub change_parameters: Option<ChangeParametersProposal>,
+}
+
+// Allowed governance consensus parameter changes.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct ConsensusParameterChanges {
+ #[cbor(optional)]
+ pub gas_costs: BTreeMap<String, u64>,
+ #[cbor(optional)]
+ pub min_proposal_deposit: Option<Quantity>,
+ #[cbor(optional)]
+ pub voting_period: Option<EpochTime>,
+ #[cbor(optional)]
+ pub stake_threshold: Option<u8>,
+ #[cbor(optional)]
+ pub upgrade_min_epoch_diff: Option<EpochTime>,
+ #[cbor(optional)]
+ pub upgrade_cancel_min_epoch_diff: Option<EpochTime>,
+ #[cbor(optional)]
+ pub enable_change_parameters_proposal: Option<bool>,
+}
+
+#[cfg(test)]
+mod tests {
+ use base64::prelude::*;
+
+ use super::*;
+
+ #[test]
+ fn test_consistent_proposal_vote() {
+ // NOTE: These tests MUST be synced with go/governance/api/api_test.go.
+ let tcs = vec![
+ (
+ "omJpZAtkdm90ZQE=",
+ ProposalVote {
+ id: 11,
+ vote: Vote::Yes,
+ },
+ ),
+ (
+ "omJpZAxkdm90ZQI=",
+ ProposalVote {
+ id: 12,
+ vote: Vote::No,
+ },
+ ),
+ (
+ "omJpZA1kdm90ZQM=",
+ ProposalVote {
+ id: 13,
+ vote: Vote::Abstain,
+ },
+ ),
+ ];
+ for (encoded_base64, vote) in tcs {
+ let dec: ProposalVote =
+ cbor::from_slice(&BASE64_STANDARD.decode(encoded_base64).unwrap())
+ .expect("proposal vote should deserialize correctly");
+ assert_eq!(
+ dec, vote,
+ "decoded proposal vote should match the expected value"
+ );
+
+ let ser = BASE64_STANDARD.encode(cbor::to_vec(dec));
+ assert_eq!(
+ ser, encoded_base64,
+ "proposal vote should serialize correctly"
+ );
+ }
+ }
+
+ #[test]
+ fn test_consistent_proposal_content() {
+ // NOTE: These tests MUST be synced with go/governance/api/api_test.go.
+ let tcs = vec![
+ (
+ "oW5jYW5jZWxfdXBncmFkZaFrcHJvcG9zYWxfaWQYKg==",
+ ProposalContent {
+ cancel_upgrade: Some(CancelUpgradeProposal { proposal_id: 42 }),
+ ..Default::default()
+ },
+ ),
+ (
+ "oWd1cGdyYWRlpGF2AmVlcG9jaBgqZnRhcmdldKNyY29uc2Vuc3VzX3Byb3RvY29soWVwYXRjaBh7dXJ1bnRpbWVfaG9zdF9wcm90b2NvbKFlcGF0Y2gZAch4GnJ1bnRpbWVfY29tbWl0dGVlX3Byb3RvY29soWVwYXRjaBkDFWdoYW5kbGVybHRlc3QtaGFuZGxlcg==",
+ ProposalContent {
+ upgrade: Some(UpgradeProposal {
+ v: 2,
+ handler: "test-handler".into(),
+ target: ProtocolVersions { consensus_protocol: 123.into(), runtime_host_protocol: 456.into(), runtime_committee_protocol: 789.into() } ,
+ epoch: 42,
+ }),
+ ..Default::default()
+ },
+ ),
+ (
+ "oXFjaGFuZ2VfcGFyYW1ldGVyc6JmbW9kdWxla3Rlc3QtbW9kdWxlZ2NoYW5nZXOhbXZvdGluZ19wZXJpb2QYew==",
+ ProposalContent {
+ change_parameters: Some(ChangeParametersProposal {
+ module: "test-module".into(),
+ changes: Some(cbor::to_value(ConsensusParameterChanges{
+ voting_period: Some(123),
+ ..Default::default()
+ })),
+ }),
+ ..Default::default()
+ }
+ ),
+ ];
+ for (encoded_base64, content) in tcs {
+ let dec: ProposalContent =
+ cbor::from_slice(&BASE64_STANDARD.decode(encoded_base64).unwrap())
+ .expect("proposal content should deserialize correctly");
+ assert_eq!(
+ dec, content,
+ "decoded proposal content should match the expected value"
+ );
+
+ let ser = BASE64_STANDARD.encode(cbor::to_vec(dec));
+ assert_eq!(
+ ser, encoded_base64,
+ "proposal content should serialize correctly"
+ );
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +
use std::{collections::HashMap, sync::Arc};
+
+use anyhow::Result;
+use thiserror::Error;
+
+use crate::common::{
+ crypto::{
+ signature::{Signature, SignatureBundle, Signer},
+ x25519,
+ },
+ namespace::Namespace,
+ sgx::EnclaveIdentity,
+};
+
+use super::beacon::EpochTime;
+
+pub mod churp;
+
+/// Context used to sign key manager policies.
+const POLICY_SIGNATURE_CONTEXT: &[u8] = b"oasis-core/keymanager: policy";
+
+/// Context used to sign encrypted key manager master secrets.
+const ENCRYPTED_MASTER_SECRET_SIGNATURE_CONTEXT: &[u8] =
+ b"oasis-core/keymanager: encrypted master secret";
+
+/// Context used to sign encrypted key manager ephemeral secrets.
+const ENCRYPTED_EPHEMERAL_SECRET_SIGNATURE_CONTEXT: &[u8] =
+ b"oasis-core/keymanager: encrypted ephemeral secret";
+
+/// Errors emitted by the key manager module.
+#[derive(Error, Debug)]
+pub enum Error {
+ #[error("invalid signature")]
+ InvalidSignature,
+}
+
+/// Key manager access control policy.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct PolicySGX {
+ pub serial: u32,
+ pub id: Namespace,
+ pub enclaves: HashMap<EnclaveIdentity, EnclavePolicySGX>,
+ #[cbor(optional)]
+ pub master_secret_rotation_interval: EpochTime,
+ #[cbor(optional)]
+ pub max_ephemeral_secret_age: EpochTime,
+}
+
+/// Per enclave key manager access control policy.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct EnclavePolicySGX {
+ /// A map of runtime IDs to the vector of enclave IDs that may query
+ /// private key material.
+ pub may_query: HashMap<Namespace, Vec<EnclaveIdentity>>,
+
+ /// A vector of enclave IDs that may retrieve the master secret.
+ ///
+ /// NOTE: Each enclave ID may always implicitly replicate from other
+ /// instances of itself.
+ pub may_replicate: Vec<EnclaveIdentity>,
+}
+
+/// Signed key manager access control policy.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct SignedPolicySGX {
+ pub policy: PolicySGX,
+ pub signatures: Vec<SignatureBundle>,
+}
+
+impl SignedPolicySGX {
+ /// Verify the signatures.
+ pub fn verify(&self) -> Result<&PolicySGX> {
+ let raw_policy = cbor::to_vec(self.policy.clone());
+ for sig in &self.signatures {
+ sig.signature
+ .verify(&sig.public_key, POLICY_SIGNATURE_CONTEXT, &raw_policy)
+ .map_err(|_| Error::InvalidSignature)?;
+ }
+
+ Ok(&self.policy)
+ }
+}
+
+/// A secret encrypted with Deoxys-II MRAE algorithm.
+#[derive(Clone, Default, Debug, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct EncryptedSecret {
+ /// Checksum for validating decrypted secret.
+ pub checksum: Vec<u8>,
+ /// Public key to derive the symmetric key for decryption.
+ pub pub_key: x25519::PublicKey,
+ /// A map of REK encrypted secrets.
+ pub ciphertexts: HashMap<x25519::PublicKey, Vec<u8>>,
+}
+
+/// Encrypted master secret.
+#[derive(Clone, Default, Debug, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct EncryptedMasterSecret {
+ /// Runtime ID of the key manager.
+ pub runtime_id: Namespace,
+ /// Generation of the secret.
+ pub generation: u64,
+ /// Epoch time in which the secret was created.
+ pub epoch: EpochTime,
+ /// Encrypted secret.
+ pub secret: EncryptedSecret,
+}
+
+/// Encrypted ephemeral secret.
+#[derive(Clone, Default, Debug, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct EncryptedEphemeralSecret {
+ /// Runtime ID of the key manager.
+ pub runtime_id: Namespace,
+ /// Epoch time to which the ephemeral secret belongs.
+ pub epoch: EpochTime,
+ /// Encrypted secret.
+ pub secret: EncryptedSecret,
+}
+
+/// Signed encrypted master secret (RAK).
+#[derive(Clone, Default, Debug, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct SignedEncryptedMasterSecret {
+ /// Encrypted master secret.
+ pub secret: EncryptedMasterSecret,
+ /// Signature of the encrypted master secret.
+ pub signature: Signature,
+}
+
+impl SignedEncryptedMasterSecret {
+ pub fn new(secret: EncryptedMasterSecret, signer: &Arc<dyn Signer>) -> Result<Self> {
+ let signature = signer.sign(
+ ENCRYPTED_MASTER_SECRET_SIGNATURE_CONTEXT,
+ &cbor::to_vec(secret.clone()),
+ )?;
+ Ok(Self { secret, signature })
+ }
+}
+
+/// Signed encrypted ephemeral secret (RAK).
+#[derive(Clone, Default, Debug, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct SignedEncryptedEphemeralSecret {
+ /// Encrypted ephemeral secret.
+ pub secret: EncryptedEphemeralSecret,
+ /// Signature of the encrypted ephemeral secret.
+ pub signature: Signature,
+}
+
+impl SignedEncryptedEphemeralSecret {
+ pub fn new(secret: EncryptedEphemeralSecret, signer: &Arc<dyn Signer>) -> Result<Self> {
+ let signature = signer.sign(
+ ENCRYPTED_EPHEMERAL_SECRET_SIGNATURE_CONTEXT,
+ &cbor::to_vec(secret.clone()),
+ )?;
+ Ok(Self { secret, signature })
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +
//! Key manager state in the consensus layer.
+use std::collections::HashMap;
+
+use anyhow::Result;
+use thiserror::Error;
+
+use crate::{
+ common::{
+ crypto::{
+ hash::Hash,
+ signature::{PublicKey, SignatureBundle},
+ },
+ namespace::Namespace,
+ sgx::EnclaveIdentity,
+ },
+ consensus::beacon::EpochTime,
+};
+
+/// Context used to sign key manager CHURP policies.
+const POLICY_SIGNATURE_CONTEXT: &[u8] = b"oasis-core/keymanager/churp: policy";
+
+/// Errors emitted by the CHURP module.
+#[derive(Error, Debug)]
+pub enum Error {
+ #[error("invalid signature")]
+ InvalidSignature,
+}
+
+/// Cipher suite identifier.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Decode, cbor::Encode)]
+#[repr(u8)]
+pub enum SuiteId {
+ /// The NIST P-384 elliptic curve group with the SHA3-384 hash function
+ /// used to encode arbitrary-length byte strings to elements of the
+ /// underlying prime field or elliptic curve points.
+ #[default]
+ NistP384Sha3_384 = 0,
+}
+
+/// Status represents the current state of a CHURP instance.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Decode, cbor::Encode)]
+pub struct Status {
+ /// A unique identifier within the key manager runtime.
+ pub id: u8,
+
+ /// The identifier of the key manager runtime.
+ pub runtime_id: Namespace,
+
+ /// The identifier of a cipher suite used for verifiable secret sharing
+ /// and key derivation.
+ pub suite_id: SuiteId,
+
+ /// The degree of the secret-sharing polynomial.
+ ///
+ /// In a (t,n) secret-sharing scheme, where t represents the threshold,
+ /// any combination of t+1 or more shares can reconstruct the secret,
+ /// while losing n-t or fewer shares still allows the secret to be
+ /// recovered.
+ pub threshold: u8,
+
+ /// The minimum number of shares that can be lost to render the secret
+ /// unrecoverable.
+ ///
+ /// If t and e represent the threshold and extra shares, respectively,
+ /// then the minimum size of the committee is t+e+1.
+ pub extra_shares: u8,
+
+ /// The time interval in epochs between handoffs.
+ ///
+ /// A zero value disables handoffs.
+ pub handoff_interval: EpochTime,
+
+ /// A signed SGX access control policy.
+ pub policy: SignedPolicySGX,
+
+ /// The epoch of the last successfully completed handoff.
+ ///
+ /// The zero value indicates that no handoffs have been completed so far.
+ /// Note that the first handoff is special and is called the dealer phase,
+ /// in which nodes do not reshare or randomize shares but instead construct
+ /// the secret and shares.
+ pub handoff: EpochTime,
+
+ /// The hash of the verification matrix from the last successfully completed
+ /// handoff.
+ #[cbor(optional)]
+ pub checksum: Option<Hash>,
+
+ /// A vector of nodes holding a share of the secret in the active handoff.
+ ///
+ /// A client needs to obtain more than a threshold number of key shares
+ /// from the nodes in this vector to construct the key.
+ #[cbor(optional)]
+ pub committee: Vec<PublicKey>,
+
+ /// The epoch in which the next handoff will occur.
+ ///
+ /// If an insufficient number of applications is received, the next handoff
+ /// will be delayed by one epoch.
+ pub next_handoff: EpochTime,
+
+ /// The hash of the verification matrix from the current handoff.
+ ///
+ /// The first candidate to confirm share reconstruction is the source
+ /// of truth for the checksum. All other candidates need to confirm
+ /// with the same checksum; otherwise, the applications will be annulled,
+ /// and the nodes will need to apply for the new committee again.
+ #[cbor(optional)]
+ pub next_checksum: Option<Hash>,
+
+ /// A map of nodes that wish to form the new committee.
+ ///
+ /// Candidates are expected to generate a random bivariate polynomial,
+ /// construct a verification matrix, compute its checksum, and submit
+ /// an application one epoch in advance of the next scheduled handoff.
+ /// Subsequently, upon the arrival of the handoff epoch, nodes must execute
+ /// the handoff protocol and confirm the reconstruction of its share.
+ #[cbor(optional)]
+ pub applications: HashMap<PublicKey, Application>,
+}
+
+/// Application represents a node's application to form a new committee.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Decode, cbor::Encode)]
+pub struct Application {
+ /// The hash of the random verification matrix.
+ ///
+ /// In all handoffs, except in the dealer phase, the verification matrix
+ /// needs to be zero-hole.
+ pub checksum: Hash,
+
+ /// Reconstructed is true if and only if the node verified all matrices
+ /// and successfully reconstructed its share during the handoff.
+ pub reconstructed: bool,
+}
+
+/// Key manager access control policy.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct PolicySGX {
+ /// A unique identifier within the key manager runtime.
+ pub id: u8,
+
+ /// The identifier of the key manager runtime.
+ pub runtime_id: Namespace,
+
+ /// A monotonically increasing policy serial number.
+ pub serial: u32,
+
+ /// A vector of enclave identities from which a share can be obtained
+ /// during handoffs.
+ pub may_share: Vec<EnclaveIdentity>,
+
+ /// A vector of enclave identities that may form the new committee
+ /// in the next handoffs.
+ pub may_join: Vec<EnclaveIdentity>,
+
+ /// A map of runtime identities to the vector of enclave identities
+ /// that may query key shares.
+ pub may_query: HashMap<Namespace, Vec<EnclaveIdentity>>,
+}
+
+/// Signed key manager access control policy.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct SignedPolicySGX {
+ /// An SGX access control policy.
+ pub policy: PolicySGX,
+
+ /// A vector of signatures.
+ #[cbor(optional)]
+ pub signatures: Vec<SignatureBundle>,
+}
+
+impl SignedPolicySGX {
+ /// Verify the signatures.
+ pub fn verify(&self) -> Result<&PolicySGX> {
+ let raw_policy = cbor::to_vec(self.policy.clone());
+ for sig in &self.signatures {
+ sig.signature
+ .verify(&sig.public_key, POLICY_SIGNATURE_CONTEXT, &raw_policy)
+ .map_err(|_| Error::InvalidSignature)?;
+ }
+
+ Ok(&self.policy)
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +
//! Consensus service interfaces.
+
+use crate::common::crypto::hash::Hash;
+
+pub mod address;
+pub mod beacon;
+pub mod governance;
+pub mod keymanager;
+pub mod registry;
+pub mod roothash;
+pub mod scheduler;
+pub mod staking;
+pub mod state;
+pub mod tendermint;
+pub mod transaction;
+pub mod verifier;
+
+/// A unique module name for the consensus module.
+pub const MODULE_NAME: &str = "consensus";
+
+// Method name for the special block metadata transaction.
+pub const METHOD_META: &str = "consensus.Meta";
+
+/// The height that represents the most recent block height.
+pub const HEIGHT_LATEST: u64 = 0;
+
+/// Light consensus block.
+#[derive(Clone, Default, Debug, cbor::Encode, cbor::Decode)]
+pub struct LightBlock {
+ pub height: u64,
+ pub meta: Vec<u8>,
+}
+
+/// An event emitted by the consensus layer.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub enum Event {
+ #[cbor(rename = "staking")]
+ Staking(staking::Event),
+ // TODO: Add support for other kind of events.
+}
+
+/// BlockMetadata contains additional metadata related to the executing block.
+///
+/// The metadata is included in the form of a special transaction where this structure is the
+/// transaction body.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct BlockMetadata {
+ /// State root after executing all logic in the block.
+ pub state_root: Hash,
+ // EventsRoot is the provable events root.
+ pub events_root: Vec<u8>,
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +765 +766 +767 +768 +769 +770 +771 +772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805 +806 +807 +808 +809 +810 +811 +812 +813 +814 +815 +816 +817 +818 +819 +820 +821 +822 +823 +824 +825 +826 +827 +828 +829 +830 +831 +832 +833 +834 +835 +836 +837 +838 +839 +840 +841 +842 +843 +844 +845 +846 +847 +848 +849 +850 +851 +852 +853 +854 +855 +856 +857 +858 +859 +860 +861 +862 +863 +864 +865 +866 +867 +868 +869 +870 +871 +872 +873 +874 +875 +876 +877 +878 +879 +880 +881 +882 +883 +884 +885 +886 +887 +888 +889 +890 +891 +892 +893 +894 +895 +896 +897 +898 +899 +900 +901 +902 +903 +904 +905 +906 +907 +908 +909 +910 +911 +912 +913 +914 +915 +916 +917 +918 +919 +920 +921 +922 +923 +924 +925 +926 +927 +928 +929 +930 +931 +932 +933 +934 +935 +936 +937 +938 +939 +940 +941 +942 +943 +944 +945 +946 +947 +948 +949 +950 +951 +952 +953 +954 +955 +956 +957 +958 +959 +960 +961 +962 +963 +964 +965 +966 +967 +968 +969 +970 +971 +972 +973 +974 +975 +976 +977 +978 +979 +980 +981 +982 +983 +984 +985 +986 +987 +988 +989 +990 +991 +992 +993 +994 +995 +996 +997 +998 +999 +1000 +1001 +1002 +1003 +1004 +1005 +1006 +1007 +1008 +1009 +1010 +1011 +1012 +1013 +1014 +1015 +1016 +1017 +1018 +1019 +1020 +1021 +1022 +1023 +1024 +1025 +1026 +1027 +1028 +1029 +1030 +1031 +1032 +1033 +1034 +1035 +1036 +1037 +1038 +1039 +1040 +1041 +1042 +1043 +1044 +1045 +1046 +1047 +1048 +1049 +1050 +1051 +1052 +1053 +1054 +1055 +1056 +1057 +1058 +1059 +1060 +1061 +1062 +1063 +1064 +1065 +1066 +1067 +1068 +1069 +1070 +1071 +1072 +1073 +1074 +1075 +1076 +1077 +1078 +1079 +1080 +1081 +1082 +1083 +1084 +1085 +1086 +1087 +1088 +1089 +1090 +1091 +1092 +1093 +1094 +1095 +1096 +1097 +1098 +1099 +1100 +1101 +1102 +1103 +1104 +1105 +1106 +1107 +1108 +1109 +1110 +1111 +1112 +1113 +1114 +1115 +1116 +1117 +1118 +1119 +1120 +1121 +1122 +1123 +1124 +1125 +1126 +1127 +1128 +1129 +1130 +1131 +1132 +1133 +1134 +1135 +1136 +1137 +1138 +1139 +1140 +1141 +1142 +1143 +1144 +1145 +1146 +1147 +1148 +1149 +1150 +1151 +1152 +1153 +1154 +1155 +1156 +1157 +1158 +1159 +1160 +1161 +1162 +1163 +1164 +1165 +1166 +1167 +1168 +1169 +1170 +1171 +1172 +1173 +1174 +1175 +1176 +1177 +1178 +1179 +1180 +1181 +1182 +1183 +1184 +1185 +1186 +1187 +1188 +1189 +1190 +1191 +1192 +1193 +1194 +1195 +1196 +1197 +1198 +1199 +1200 +1201 +1202 +1203 +1204 +1205 +1206 +1207 +1208 +1209 +1210 +1211 +1212 +1213 +1214 +1215 +1216 +1217 +1218 +1219 +1220 +1221 +1222 +1223 +1224 +1225 +1226 +1227 +1228 +1229 +1230 +1231 +1232 +1233 +1234 +1235 +1236 +1237 +1238 +1239 +1240 +1241 +1242 +1243 +1244 +1245 +1246 +1247 +1248 +1249 +1250 +1251 +1252 +1253 +1254 +1255 +1256 +1257 +1258 +1259 +1260 +1261 +1262 +1263 +1264 +1265 +1266 +1267 +1268 +1269 +1270 +1271 +1272 +1273 +1274 +1275 +1276 +1277 +1278 +1279 +1280 +1281 +1282 +1283 +1284 +1285 +1286 +1287 +1288 +1289 +1290 +1291 +1292 +1293 +1294 +1295 +1296 +1297 +1298 +1299 +1300 +1301 +1302 +1303 +1304 +1305 +1306 +1307 +1308 +1309 +1310 +1311 +1312 +1313 +1314 +1315 +1316 +1317 +1318 +1319 +1320 +1321 +1322 +1323 +1324 +1325 +1326 +1327 +1328 +1329 +1330 +1331 +1332 +1333 +1334 +1335 +1336 +1337 +1338 +1339 +1340 +1341 +1342 +1343 +1344 +1345 +1346 +1347 +1348 +1349 +1350 +1351 +1352 +1353 +1354 +1355 +1356 +1357 +1358 +1359 +1360 +1361 +1362 +1363 +1364 +1365 +1366 +1367 +1368 +1369 +1370 +1371 +1372 +1373 +1374 +1375 +1376 +1377 +1378 +1379 +1380 +1381 +1382 +1383 +1384 +1385 +1386 +1387 +1388 +1389 +1390 +1391 +1392 +1393 +1394 +1395 +1396 +1397 +1398 +1399 +1400 +1401 +1402 +1403 +1404 +1405 +1406 +1407 +1408 +1409 +1410 +1411 +1412 +1413 +1414 +1415 +1416 +1417 +1418 +1419 +1420 +1421 +1422 +1423 +1424 +1425 +1426 +1427 +1428 +1429 +1430 +1431 +1432 +1433 +1434 +1435 +1436 +1437 +1438 +1439 +1440 +1441 +1442 +1443 +1444 +1445 +1446 +1447 +1448 +1449 +1450 +1451 +1452 +1453 +1454 +1455 +1456 +1457 +1458 +1459 +1460 +1461 +1462 +1463 +1464 +1465 +1466 +1467 +1468 +1469 +1470 +1471 +1472 +1473 +1474 +1475 +1476 +1477 +1478 +1479 +1480 +1481 +1482 +1483 +1484 +
//! Registry structures.
+//!
+//! # Note
+//!
+//! This **MUST** be kept in sync with go/registry/api.
+//!
+use std::collections::BTreeMap;
+
+use anyhow::{anyhow, bail};
+use num_traits::Zero;
+use tiny_keccak::{Hasher, TupleHash};
+
+use crate::{
+ common::{
+ crypto::{
+ hash::Hash,
+ signature::{self, Signature},
+ x25519,
+ },
+ namespace::Namespace,
+ quantity, sgx,
+ version::Version,
+ },
+ consensus::{beacon::EpochTime, scheduler, staking},
+ identity::Identity,
+};
+
+/// A unique module name for the registry module.
+pub const MODULE_NAME: &str = "registry";
+
+/// The method name for freshness proofs.
+pub const METHOD_PROVE_FRESHNESS: &str = "registry.ProveFreshness";
+
+/// Attestation signature context.
+pub const ATTESTATION_SIGNATURE_CONTEXT: &[u8] = b"oasis-core/node: TEE attestation signature";
+
+/// TEE capability endorsement signature context.
+pub const ENDORSE_CAPABILITY_TEE_SIGNATURE_CONTEXT: &[u8] =
+ b"oasis-core/node: endorse TEE capability";
+
+/// Represents the address of a TCP endpoint.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct TCPAddress {
+ #[cbor(rename = "IP")]
+ pub ip: Vec<u8>,
+ #[cbor(rename = "Port")]
+ pub port: i64,
+ #[cbor(rename = "Zone")]
+ pub zone: String,
+}
+
+/// Represents an Oasis committee address that includes a TLS public key and a TCP address.
+///
+/// NOTE: The address TLS public key can be different from the actual node TLS public key to allow
+/// using a sentry node's addresses.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct TLSAddress {
+ /// Public key used for establishing TLS connections.
+ pub pub_key: signature::PublicKey,
+
+ /// Address at which the node can be reached.
+ pub address: TCPAddress,
+}
+
+/// Node's TLS information.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct TLSInfo {
+ /// Public key used for establishing TLS connections.
+ pub pub_key: signature::PublicKey,
+
+ #[cbor(rename = "next_pub_key", optional)]
+ pub _deprecated_next_pub_key: Option<signature::PublicKey>,
+
+ #[cbor(rename = "addresses", optional)]
+ pub _deprecated_addresses: Option<Vec<TLSAddress>>,
+}
+
+/// Node's P2P information.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct P2PInfo {
+ /// Unique identifier of the node on the P2P transport.
+ pub id: signature::PublicKey,
+
+ /// List of addresses at which the node can be reached.
+ pub addresses: Option<Vec<TCPAddress>>,
+}
+
+/// Represents a consensus address that includes an ID and a TCP address.
+///
+/// NOTE: The consensus address ID could be different from the consensus ID
+/// to allow using a sentry node's ID and address instead of the validator's.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct ConsensusAddress {
+ /// Public key identifying the node.
+ pub id: signature::PublicKey,
+
+ /// Address at which the node can be reached.
+ pub address: TCPAddress,
+}
+
+/// Node's consensus member information.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct ConsensusInfo {
+ /// Unique identifier of the node as a consensus member.
+ pub id: signature::PublicKey,
+
+ /// List of addresses at which the node can be reached.
+ pub addresses: Option<Vec<ConsensusAddress>>,
+}
+
+/// Contains information for this node's participation in VRF based elections.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct VRFInfo {
+ /// Unique identifier of the node used to generate VRF proofs.
+ pub id: signature::PublicKey,
+}
+
+/// Represents the node's TEE capability.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct CapabilityTEE {
+ /// Hardware type.
+ pub hardware: TEEHardware,
+
+ /// Runtime attestation key.
+ pub rak: signature::PublicKey,
+
+ /// Runtime encryption key.
+ #[cbor(optional)]
+ pub rek: Option<x25519::PublicKey>,
+
+ /// Attestation.
+ pub attestation: Vec<u8>,
+}
+
+impl CapabilityTEE {
+ /// Tries to decode the TEE-specific attestation.
+ pub fn try_decode_attestation<T>(&self) -> Result<T, cbor::DecodeError>
+ where
+ T: cbor::Decode,
+ {
+ cbor::from_slice_non_strict(&self.attestation)
+ }
+
+ /// Checks whether the TEE capability matches the given TEE identity.
+ pub fn matches(&self, identity: &Identity) -> bool {
+ match self.hardware {
+ TEEHardware::TEEHardwareInvalid => false,
+ TEEHardware::TEEHardwareIntelSGX => {
+ // Decode SGX attestation and check quote equality.
+ let attestation: SGXAttestation = match self.try_decode_attestation() {
+ Ok(a) => a,
+ _ => return false,
+ };
+ identity.rak_matches(&self.rak, &attestation.quote())
+ }
+ }
+ }
+
+ /// Verifies the TEE capability.
+ pub fn verify(
+ &self,
+ policy: &sgx::QuotePolicy,
+ node_id: &signature::PublicKey,
+ ) -> anyhow::Result<VerifiedAttestation> {
+ match self.hardware {
+ TEEHardware::TEEHardwareInvalid => bail!("invalid TEE hardware"),
+ TEEHardware::TEEHardwareIntelSGX => {
+ // Decode SGX attestation and verify it.
+ let attestation: SGXAttestation = self.try_decode_attestation()?;
+ attestation.verify(
+ policy,
+ node_id,
+ &self.rak,
+ self.rek.as_ref().ok_or(anyhow!("missing REK"))?,
+ )
+ }
+ }
+ }
+}
+
+/// An endorsed CapabilityTEE structure.
+///
+///
+/// Endorsement is needed for off-chain runtime components where their RAK is not published in the
+/// consensus layer and verification is part of the runtime itself. Via endorsement one can enforce
+/// policies like "only components executed by the current compute committee are authorized".
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct EndorsedCapabilityTEE {
+ /// TEE capability structure to be endorsed.
+ pub capability_tee: CapabilityTEE,
+
+ /// Node endorsement signature.
+ pub node_endorsement: signature::SignatureBundle,
+}
+
+impl EndorsedCapabilityTEE {
+ /// Verify the endorsement signature is valid.
+ ///
+ /// **This does not verify the TEE capability itself, use `verify` for that.**
+ pub fn verify_endorsement(&self) -> anyhow::Result<()> {
+ if !self.node_endorsement.verify(
+ ENDORSE_CAPABILITY_TEE_SIGNATURE_CONTEXT,
+ &cbor::to_vec(self.capability_tee.clone()),
+ ) {
+ bail!("invalid node endorsement signature");
+ }
+ Ok(())
+ }
+
+ /// Verify endorsed TEE capability is valid.
+ pub fn verify(
+ &self,
+ policy: &sgx::QuotePolicy,
+ ) -> anyhow::Result<VerifiedEndorsedCapabilityTEE> {
+ // Verify node endorsement.
+ self.verify_endorsement()?;
+
+ // Verify TEE capability.
+ let verified_attestation = self
+ .capability_tee
+ .verify(policy, &self.node_endorsement.public_key)?;
+
+ Ok(VerifiedEndorsedCapabilityTEE {
+ verified_attestation,
+ node_id: Some(self.node_endorsement.public_key),
+ })
+ }
+}
+
+/// A verified endorsed CapabilityTEE structure.
+#[derive(Clone, Debug, Default)]
+pub struct VerifiedEndorsedCapabilityTEE {
+ /// Verified TEE remote attestation.
+ pub verified_attestation: VerifiedAttestation,
+ /// Optional identifier of the node that endorsed the TEE capability.
+ pub node_id: Option<signature::PublicKey>,
+}
+
+impl From<VerifiedAttestation> for VerifiedEndorsedCapabilityTEE {
+ fn from(verified_attestation: VerifiedAttestation) -> Self {
+ Self {
+ verified_attestation,
+ node_id: None,
+ }
+ }
+}
+
+impl From<sgx::VerifiedQuote> for VerifiedEndorsedCapabilityTEE {
+ fn from(verified_quote: sgx::VerifiedQuote) -> Self {
+ Self {
+ verified_attestation: verified_quote.into(),
+ node_id: None,
+ }
+ }
+}
+
+/// Represents a node's capabilities.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct Capabilities {
+ /// Is the capability of a node executing batches in a TEE.
+ #[cbor(optional)]
+ pub tee: Option<CapabilityTEE>,
+}
+
+/// Represents the runtimes supported by a given Oasis node.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct NodeRuntime {
+ /// Public key identifying the runtime.
+ pub id: Namespace,
+
+ /// Version of the runtime.
+ pub version: Version,
+
+ /// Node's capabilities for a given runtime.
+ pub capabilities: Capabilities,
+
+ /// Extra per node + per runtime opaque data associated with the current instance.
+ pub extra_info: Option<Vec<u8>>,
+}
+
+/// Oasis node roles bitmask.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+#[cbor(transparent)]
+pub struct RolesMask(pub u32);
+
+// XXX: Would be nicer to use bitflags crate for this, but there is no way to add
+// custom derives to the enum at the moment.
+// Should be possible in v2.0 (https://github.com/bitflags/bitflags/issues/262).
+impl RolesMask {
+ /// Empty roles mask.
+ pub const ROLE_EMPTY: RolesMask = RolesMask(0);
+ /// Compute worker role.
+ pub const ROLE_COMPUTE_WORKER: RolesMask = RolesMask(1 << 0);
+ /// Observer role.
+ pub const ROLE_OBSERVER: RolesMask = RolesMask(1 << 1);
+ /// Key manager role.
+ pub const ROLE_KEY_MANAGER: RolesMask = RolesMask(1 << 2);
+ /// Validator role.
+ pub const ROLE_VALIDATOR: RolesMask = RolesMask(1 << 3);
+ /// Public consensus RPC services worker role.
+ pub const ROLE_RESERVED_3: RolesMask = RolesMask(1 << 4);
+ /// Public storage RPC services worker role.
+ pub const ROLE_STORAGE_RPC: RolesMask = RolesMask(1 << 5);
+
+ // Bits of the Oasis node roles bitmask that are reserved and must not be used.
+ pub const ROLES_RESERVED: RolesMask =
+ RolesMask(u32::MAX & !((Self::ROLE_STORAGE_RPC.0 << 1) - 1) | Self::ROLE_RESERVED_3.0);
+
+ /// Whether the roles mask contains any of the specified roles.
+ pub fn contains(&self, role: RolesMask) -> bool {
+ (self.0 & role.0) != 0
+ }
+
+ /// Whether the roles mask encodes a single valid role.
+ pub fn is_single_role(&self) -> bool {
+ // Ensures exactly one bit is set, and the set bit is a valid role.
+ self.0 != 0 && self.0 & (self.0 - 1) == 0 && self.0 & Self::ROLES_RESERVED.0 == 0
+ }
+}
+
+impl std::ops::BitAnd for RolesMask {
+ type Output = Self;
+
+ fn bitand(self, rhs: Self) -> Self::Output {
+ Self(self.0.bitand(rhs.0))
+ }
+}
+
+impl std::ops::BitOr for RolesMask {
+ type Output = Self;
+
+ fn bitor(self, rhs: Self) -> Self::Output {
+ Self(self.0.bitor(rhs.0))
+ }
+}
+
+impl PartialOrd for RolesMask {
+ fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
+ Some(self.cmp(other))
+ }
+}
+
+impl Ord for RolesMask {
+ fn cmp(&self, other: &Self) -> std::cmp::Ordering {
+ self.0.cmp(&other.0)
+ }
+}
+
+impl Default for RolesMask {
+ fn default() -> Self {
+ Self::ROLE_EMPTY
+ }
+}
+
+/// Node registry descriptor.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct Node {
+ /// Structure version.
+ pub v: u16,
+
+ /// Public key identifying the node.
+ pub id: signature::PublicKey,
+
+ /// Public key identifying the Entity controlling the node.
+ pub entity_id: signature::PublicKey,
+
+ /// Epoch in which the node's commitment expires.
+ pub expiration: u64,
+
+ /// Information for connecting to this node via TLS.
+ pub tls: TLSInfo,
+
+ /// Information for connecting to this node via P2P.
+ pub p2p: P2PInfo,
+
+ /// Information for connecting to this node as a consensus member.
+ pub consensus: ConsensusInfo,
+
+ /// Information for this node's participation in VRF based elections.
+ pub vrf: VRFInfo,
+
+ /// Node's runtimes.
+ pub runtimes: Option<Vec<NodeRuntime>>,
+
+ /// Bitmask representing the node roles.
+ pub roles: RolesMask,
+
+ /// Node's oasis-node software version.
+ #[cbor(optional)]
+ pub software_version: Option<String>,
+}
+
+impl Node {
+ /// Checks whether the node has any of the specified roles.
+ pub fn has_roles(&self, roles: RolesMask) -> bool {
+ self.roles.contains(roles)
+ }
+
+ /// Checks whether the node has the provided TEE identity configured.
+ pub fn has_tee(&self, identity: &Identity, runtime_id: &Namespace, version: &Version) -> bool {
+ if let Some(rts) = &self.runtimes {
+ for rt in rts {
+ if runtime_id != &rt.id {
+ continue;
+ }
+ if version != &rt.version {
+ continue;
+ }
+ if let Some(tee) = &rt.capabilities.tee {
+ if tee.matches(identity) {
+ return true;
+ }
+ }
+ }
+ }
+ false
+ }
+
+ /// Searches for an existing supported runtime descriptor
+ /// in runtimes with the specified version and returns it.
+ pub fn get_runtime(&self, runtime_id: &Namespace, version: &Version) -> Option<NodeRuntime> {
+ if let Some(rts) = &self.runtimes {
+ for rt in rts {
+ if runtime_id != &rt.id {
+ continue;
+ }
+ if version != &rt.version {
+ continue;
+ }
+ return Some(rt.clone());
+ }
+ }
+ None
+ }
+}
+
+/// Runtime kind.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+#[repr(u32)]
+pub enum RuntimeKind {
+ /// Invalid runtime that should never be explicitly set.
+ #[default]
+ KindInvalid = 0,
+ /// Generic compute runtime.
+ KindCompute = 1,
+ /// Key manager runtime.
+ KindKeyManager = 2,
+}
+
+/// Parameters for the executor committee.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct ExecutorParameters {
+ /// Size of the committee.
+ pub group_size: u16,
+ /// Size of the discrepancy resolution group.
+ pub group_backup_size: u16,
+ /// Number of allowed stragglers.
+ pub allowed_stragglers: u16,
+ /// Round timeout in consensus blocks.
+ pub round_timeout: i64,
+ /// Maximum number of messages that can be emitted by the runtime
+ /// in a single round.
+ pub max_messages: u32,
+ /// Minimum percentage of rounds in an epoch that a node must participate in positively in order
+ /// to be considered live. Nodes not satisfying this may be penalized.
+ #[cbor(optional)]
+ pub min_live_rounds_percent: u8,
+ /// Maximum percentage of proposed rounds in an epoch that can fail for a node
+ /// to be considered live. Nodes not satisfying this may be penalized. Zero means
+ /// that all proposed rounds can fail.
+ #[cbor(optional)]
+ pub max_missed_proposals_percent: u8,
+ /// Minimum number of live rounds in an epoch for the liveness calculations to be considered for
+ /// evaluation.
+ #[cbor(optional)]
+ pub min_live_rounds_eval: u64,
+ /// Maximum number of liveness failures that are tolerated before suspending and/or slashing the
+ /// node. Zero means unlimited.
+ #[cbor(optional)]
+ pub max_liveness_fails: u8,
+}
+
+/// Parameters for the runtime transaction scheduler.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct TxnSchedulerParameters {
+ /// How long to wait for a scheduled batch in nanoseconds (when using the
+ /// "simple" scheduling algorithm).
+ #[cbor(optional)]
+ pub batch_flush_timeout: i64,
+ /// Maximum size of a scheduled batch.
+ #[cbor(optional)]
+ pub max_batch_size: u64,
+ /// Maximum size of a scheduled batch in bytes.
+ #[cbor(optional)]
+ pub max_batch_size_bytes: u64,
+ /// Maximum size of the incoming message queue.
+ #[cbor(optional)]
+ pub max_in_messages: u32,
+ /// How long to wait before accepting proposal from the next backup scheduler in nanoseconds.
+ #[cbor(optional)]
+ pub propose_batch_timeout: i64,
+}
+
+/// Storage parameters.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct StorageParameters {
+ /// Expected runtime state checkpoint interval (in rounds).
+ pub checkpoint_interval: u64,
+ /// Expected minimum number of checkpoints to keep.
+ pub checkpoint_num_kept: u64,
+ /// Chunk size parameter for checkpoint creation.
+ pub checkpoint_chunk_size: u64,
+}
+
+/// The node scheduling constraints.
+///
+/// Multiple fields may be set in which case the ALL the constraints must be satisfied.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct SchedulingConstraints {
+ #[cbor(optional)]
+ pub validator_set: Option<ValidatorSetConstraint>,
+
+ #[cbor(optional)]
+ pub max_nodes: Option<MaxNodesConstraint>,
+
+ #[cbor(optional)]
+ pub min_pool_size: Option<MinPoolSizeConstraint>,
+}
+
+/// A constraint which specifies that the entity must have a node that is part of the validator set.
+/// No other options can currently be specified.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct ValidatorSetConstraint {}
+
+/// A constraint which specifies that only the given number of nodes may be eligible per entity.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct MaxNodesConstraint {
+ pub limit: u16,
+}
+
+/// A constraint which specifies the minimum required candidate pool size.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct MinPoolSizeConstraint {
+ pub limit: u16,
+}
+
+/// Stake-related parameters for a runtime.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct RuntimeStakingParameters {
+ /// Minimum stake thresholds for a runtime. These per-runtime thresholds are
+ /// in addition to the global thresholds. May be left unspecified.
+ ///
+ /// In case a node is registered for multiple runtimes, it will need to
+ /// satisfy the maximum threshold of all the runtimes.
+ #[cbor(optional)]
+ pub thresholds: BTreeMap<staking::ThresholdKind, quantity::Quantity>,
+
+ /// Per-runtime misbehavior slashing parameters.
+ #[cbor(optional)]
+ pub slashing: BTreeMap<staking::SlashReason, staking::Slash>,
+
+ /// The percentage of the reward obtained when slashing for equivocation that is transferred to
+ /// the runtime's account.
+ #[cbor(optional)]
+ pub reward_equivocation: u8,
+
+ /// The percentage of the reward obtained when slashing for incorrect results that is
+ /// transferred to the runtime's account.
+ #[cbor(optional)]
+ pub reward_bad_results: u8,
+
+ /// Specifies the minimum fee that the incoming message must include for the
+ /// message to be queued.
+ #[cbor(optional)]
+ pub min_in_message_fee: quantity::Quantity,
+}
+
+/// Policy that allows only whitelisted entities' nodes to register.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct EntityWhitelistRuntimeAdmissionPolicy {
+ /// Entity whitelist configuration for each whitelisted entity.
+ #[cbor(optional)]
+ pub entities: BTreeMap<signature::PublicKey, EntityWhitelistConfig>,
+}
+
+/// Entity whitelist configuration.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct EntityWhitelistConfig {
+ /// Maximum number of nodes that an entity can register under the given
+ /// runtime for a specific role. If the map is empty or absent, the number
+ /// of nodes is unlimited. If the map is present and non-empty, the number
+ /// of nodes is restricted to the specified maximum (where zero
+ /// means no nodes allowed), any missing roles imply zero nodes.
+ #[cbor(optional)]
+ pub max_nodes: BTreeMap<RolesMask, u16>,
+}
+
+/// A per-entity whitelist configuration for a given role.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct EntityWhitelistRoleConfig {
+ #[cbor(optional)]
+ pub max_nodes: u16,
+}
+
+/// A per-role entity whitelist policy.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct EntityWhitelistRoleAdmissionPolicy {
+ pub entities: BTreeMap<signature::PublicKey, EntityWhitelistRoleConfig>,
+}
+
+/// A per-role admission policy.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct PerRoleAdmissionPolicy {
+ #[cbor(optional)]
+ pub entity_whitelist: Option<EntityWhitelistRoleAdmissionPolicy>,
+}
+
+/// Admission policy that allows any node to register.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct AnyNodeRuntimeAdmissionPolicy {}
+
+/// Specification of which nodes are allowed to register for a runtime.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct RuntimeAdmissionPolicy {
+ /// Allow any node to register.
+ #[cbor(optional)]
+ pub any_node: Option<AnyNodeRuntimeAdmissionPolicy>,
+
+ /// Allow only the whitelisted entities' nodes to register.
+ #[cbor(optional)]
+ pub entity_whitelist: Option<EntityWhitelistRuntimeAdmissionPolicy>,
+
+ /// A per-role admission policy that must be satisfied in addition to the global admission
+ /// policy for a specific role.
+ #[cbor(optional)]
+ pub per_role: BTreeMap<RolesMask, PerRoleAdmissionPolicy>,
+}
+
+/// Runtime governance model.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+#[repr(u8)]
+pub enum RuntimeGovernanceModel {
+ /// Invalid model that should never be explicitly set.
+ #[default]
+ GovernanceInvalid = 0,
+ /// Entity governance model.
+ GovernanceEntity = 1,
+ /// Runtime governance model.
+ GovernanceRuntime = 2,
+ /// Consensus governance model.
+ GovernanceConsensus = 3,
+}
+
+/// Per-runtime version information.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct VersionInfo {
+ /// Version of the runtime.
+ pub version: Version,
+ /// The epoch at which this version is valid.
+ pub valid_from: EpochTime,
+ /// Enclave version information, in an enclave provided specific format (if any).
+ #[cbor(optional)]
+ pub tee: Vec<u8>,
+ /// The SHA256 hash of the runtime bundle (optional).
+ #[cbor(optional)]
+ pub bundle_checksum: Vec<u8>,
+}
+
+impl VersionInfo {
+ /// Tries to decode the TEE-specific version information.
+ pub fn try_decode_tee<T>(&self) -> Result<T, cbor::DecodeError>
+ where
+ T: cbor::Decode,
+ {
+ cbor::from_slice_non_strict(&self.tee)
+ }
+}
+
+/// Intel SGX TEE constraints.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(tag = "v")]
+pub enum SGXConstraints {
+ /// Old V0 format that only supported IAS policies.
+ #[cbor(rename = 0, missing)]
+ V0 {
+ /// The allowed MRENCLAVE/MRSIGNER pairs.
+ #[cbor(optional)]
+ enclaves: Vec<sgx::EnclaveIdentity>,
+
+ /// A set of allowed quote statuses.
+ #[cbor(optional)]
+ allowed_quote_statuses: Vec<i64>,
+ },
+
+ /// New V1 format that supports both IAS and PCS policies.
+ #[cbor(rename = 1)]
+ V1 {
+ /// The allowed MRENCLAVE/MRSIGNER pairs.
+ #[cbor(optional)]
+ enclaves: Vec<sgx::EnclaveIdentity>,
+
+ /// The quote policy.
+ #[cbor(optional)]
+ policy: sgx::QuotePolicy,
+
+ /// The maximum attestation age (in blocks).
+ #[cbor(optional)]
+ max_attestation_age: u64,
+ },
+}
+
+impl SGXConstraints {
+ /// Identities of allowed enclaves.
+ pub fn enclaves(&self) -> &Vec<sgx::EnclaveIdentity> {
+ match self {
+ Self::V0 { ref enclaves, .. } => enclaves,
+ Self::V1 { ref enclaves, .. } => enclaves,
+ }
+ }
+
+ /// Checks whether the given enclave identity is whitelisted.
+ pub fn contains_enclave(&self, eid: &sgx::EnclaveIdentity) -> bool {
+ self.enclaves().contains(eid)
+ }
+
+ /// SGX quote policy.
+ pub fn policy(&self) -> sgx::QuotePolicy {
+ match self {
+ Self::V0 {
+ ref allowed_quote_statuses,
+ ..
+ } => sgx::QuotePolicy {
+ ias: Some(sgx::ias::QuotePolicy {
+ disabled: false,
+ allowed_quote_statuses: allowed_quote_statuses.clone(),
+ gid_blacklist: Vec::new(),
+ min_tcb_evaluation_data_number: 0,
+ }),
+ ..Default::default()
+ },
+ Self::V1 { ref policy, .. } => policy.clone(),
+ }
+ }
+}
+
+/// Verified remote attestation.
+#[derive(Clone, Debug, Default)]
+pub struct VerifiedAttestation {
+ /// Verified enclave quote.
+ pub quote: sgx::VerifiedQuote,
+ /// Enclave's view of the consensus layer height at the time of attestation.
+ pub height: Option<u64>,
+}
+
+impl From<sgx::VerifiedQuote> for VerifiedAttestation {
+ fn from(quote: sgx::VerifiedQuote) -> Self {
+ Self {
+ quote,
+ height: None,
+ }
+ }
+}
+
+/// Intel SGX remote attestation.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(tag = "v")]
+pub enum SGXAttestation {
+ /// Old V0 format that only supported IAS quotes.
+ #[cbor(rename = 0, missing)]
+ V0(sgx::ias::AVR),
+
+ /// New V1 format that supports both IAS and PCS policies.
+ #[cbor(rename = 1)]
+ V1 {
+ /// An Intel SGX quote.
+ quote: sgx::Quote,
+ /// The runtime's view of the consensus layer height at the time of attestation.
+ height: u64,
+ /// The signature of the attestation by the enclave (RAK).
+ signature: Signature,
+ },
+}
+
+impl SGXAttestation {
+ /// SGX attestation quote.
+ pub fn quote(&self) -> sgx::Quote {
+ match self {
+ Self::V0(avr) => sgx::Quote::Ias(avr.clone()),
+ Self::V1 { quote, .. } => quote.clone(),
+ }
+ }
+
+ /// Hashes the required data that needs to be signed by RAK producing the attestation signature.
+ pub fn hash(
+ report_data: &[u8],
+ node_id: &signature::PublicKey,
+ height: u64,
+ rek: &x25519::PublicKey,
+ ) -> [u8; 32] {
+ let mut h = TupleHash::v256(ATTESTATION_SIGNATURE_CONTEXT);
+ h.update(report_data);
+ h.update(node_id.as_ref());
+ h.update(&height.to_le_bytes());
+ h.update(rek.0.as_bytes());
+ let mut result = [0u8; 32];
+ h.finalize(&mut result);
+ result
+ }
+
+ /// Verifies the SGX attestation.
+ pub fn verify(
+ &self,
+ policy: &sgx::QuotePolicy,
+ node_id: &signature::PublicKey,
+ rak: &signature::PublicKey,
+ rek: &x25519::PublicKey,
+ ) -> anyhow::Result<VerifiedAttestation> {
+ // Verify the quote.
+ let verified_quote = self.quote().verify(policy)?;
+
+ // Ensure that the report data includes the hash of the node's RAK.
+ Identity::verify_binding(&verified_quote, rak)?;
+
+ // Verify the attestation signature.
+ match self {
+ Self::V1 {
+ height, signature, ..
+ } => {
+ let h = Self::hash(&verified_quote.report_data, node_id, *height, rek);
+ signature.verify(rak, ATTESTATION_SIGNATURE_CONTEXT, &h)?;
+
+ Ok(VerifiedAttestation {
+ quote: verified_quote,
+ height: Some(*height),
+ })
+ }
+ _ => bail!("V0 attestation not supported"),
+ }
+ }
+}
+
+/// TEE hardware implementation.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+#[repr(u8)]
+pub enum TEEHardware {
+ /// Non-TEE implementation.
+ #[default]
+ TEEHardwareInvalid = 0,
+ /// Intel SGX TEE implementation.
+ TEEHardwareIntelSGX = 1,
+}
+
+/// The latest entity descriptor version that should be used for all new descriptors. Using earlier
+/// versions may be rejected.
+pub const LATEST_RUNTIME_DESCRIPTOR_VERSION: u16 = 3;
+
+/// Runtime.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct Runtime {
+ /// Structure version.
+ pub v: u16,
+ /// Globally unique long term identifier of the runtime.
+ pub id: Namespace,
+ /// Public key identifying the Entity controlling the runtime.
+ pub entity_id: signature::PublicKey,
+ /// Runtime genesis information.
+ pub genesis: RuntimeGenesis,
+ /// Type of runtime.
+ pub kind: RuntimeKind,
+ /// Runtime's TEE hardware requirements.
+ pub tee_hardware: TEEHardware,
+ /// Runtime deployment information.
+ #[cbor(optional)]
+ pub deployments: Vec<VersionInfo>,
+ /// Key manager runtime ID for this runtime.
+ #[cbor(optional)]
+ pub key_manager: Option<Namespace>,
+ /// Parameters of the executor committee.
+ #[cbor(optional)]
+ pub executor: ExecutorParameters,
+ /// Transaction scheduling parameters of the executor committee.
+ #[cbor(optional)]
+ pub txn_scheduler: TxnSchedulerParameters,
+ /// Parameters of the storage committee.
+ #[cbor(optional)]
+ pub storage: StorageParameters,
+ /// Which nodes are allowed to register for this runtime.
+ pub admission_policy: RuntimeAdmissionPolicy,
+ /// Node scheduling constraints.
+ #[cbor(optional)]
+ pub constraints:
+ BTreeMap<scheduler::CommitteeKind, BTreeMap<scheduler::Role, SchedulingConstraints>>,
+ /// Runtime's staking-related parameters.
+ #[cbor(optional, skip_serializing_if = "staking_params_are_empty")]
+ pub staking: RuntimeStakingParameters,
+ /// Runtime governance model.
+ pub governance_model: RuntimeGovernanceModel,
+}
+
+fn staking_params_are_empty(p: &RuntimeStakingParameters) -> bool {
+ p.thresholds.is_empty()
+ && p.slashing.is_empty()
+ && p.reward_equivocation == 0
+ && p.reward_bad_results == 0
+ && p.min_in_message_fee.is_zero()
+}
+
+impl Runtime {
+ /// The currently active deployment for the specified epoch if it exists.
+ pub fn active_deployment(&self, now: EpochTime) -> Option<VersionInfo> {
+ self.deployments
+ .iter()
+ .filter(|vi| vi.valid_from <= now) // Ignore versions that are not valid yet.
+ .fold(None, |acc, vi| match acc {
+ None => Some(vi.clone()),
+ Some(ad) if ad.valid_from < vi.valid_from => Some(vi.clone()),
+ _ => acc,
+ })
+ }
+
+ /// Deployment corresponding to the specified version if it exists.
+ pub fn deployment_for_version(&self, version: Version) -> Option<VersionInfo> {
+ self.deployments
+ .iter()
+ .find(|vi| vi.version == version)
+ .cloned()
+ }
+}
+
+/// Runtime genesis information that is used to initialize runtime state in the first block.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct RuntimeGenesis {
+ /// State root that should be used at genesis time. If the runtime should start with empty state,
+ /// this must be set to the empty hash.
+ pub state_root: Hash,
+
+ /// Runtime round in the genesis.
+ pub round: u64,
+}
+
+#[cfg(test)]
+mod tests {
+ use std::{convert::TryInto, net::Ipv4Addr};
+
+ use base64::prelude::*;
+ use rustc_hex::{FromHex, ToHex};
+
+ use crate::common::quantity::Quantity;
+
+ use super::*;
+
+ /// Constructs a BTreeMap using a `btreemap! { key => value, ... }` syntax.
+ macro_rules! btreemap {
+ // allow trailing comma
+ ( $($key:expr => $value:expr,)+ ) => (btreemap!($($key => $value),+));
+ ( $($key:expr => $value:expr),* ) => {
+ {
+ let mut m = BTreeMap::new();
+ $( m.insert($key.into(), $value); )*
+ m
+ }
+ };
+}
+
+ #[test]
+ fn test_consistent_runtime() {
+ // NOTE: These tests MUST be synced with go/registry/api/runtime.go.
+ let tcs = vec![
+ // FIXME: Change to "qmF2AGJpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABka2luZABnZ2VuZXNpc6Jlcm91bmQAanN0YXRlX3Jvb3RYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAZ3N0b3JhZ2Wjc2NoZWNrcG9pbnRfaW50ZXJ2YWwAc2NoZWNrcG9pbnRfbnVtX2tlcHQAdWNoZWNrcG9pbnRfY2h1bmtfc2l6ZQBoZXhlY3V0b3Klamdyb3VwX3NpemUAbG1heF9tZXNzYWdlcwBtcm91bmRfdGltZW91dABxZ3JvdXBfYmFja3VwX3NpemUAcmFsbG93ZWRfc3RyYWdnbGVycwBpZW50aXR5X2lkWCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGx0ZWVfaGFyZHdhcmUAcGFkbWlzc2lvbl9wb2xpY3mhaGFueV9ub2RloHBnb3Zlcm5hbmNlX21vZGVsAA==" once cbor is fixed.
+ ("q2F2AGJpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABka2luZABnZ2VuZXNpc6Jlcm91bmQAanN0YXRlX3Jvb3RYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAZ3N0b3JhZ2Wjc2NoZWNrcG9pbnRfaW50ZXJ2YWwAc2NoZWNrcG9pbnRfbnVtX2tlcHQAdWNoZWNrcG9pbnRfY2h1bmtfc2l6ZQBoZXhlY3V0b3Klamdyb3VwX3NpemUAbG1heF9tZXNzYWdlcwBtcm91bmRfdGltZW91dABxZ3JvdXBfYmFja3VwX3NpemUAcmFsbG93ZWRfc3RyYWdnbGVycwBpZW50aXR5X2lkWCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGx0ZWVfaGFyZHdhcmUAbXR4bl9zY2hlZHVsZXKgcGFkbWlzc2lvbl9wb2xpY3mhaGFueV9ub2RloHBnb3Zlcm5hbmNlX21vZGVsAA==", Runtime {
+ admission_policy: RuntimeAdmissionPolicy {
+ any_node: Some(AnyNodeRuntimeAdmissionPolicy {}),
+ ..Default::default()
+ },
+ ..Default::default()
+ }),
+ // FIXME: Change to "qmF2AGJpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABka2luZABnZ2VuZXNpc6Jlcm91bmQAanN0YXRlX3Jvb3RYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAZ3N0b3JhZ2Wjc2NoZWNrcG9pbnRfaW50ZXJ2YWwAc2NoZWNrcG9pbnRfbnVtX2tlcHQAdWNoZWNrcG9pbnRfY2h1bmtfc2l6ZQBoZXhlY3V0b3Klamdyb3VwX3NpemUAbG1heF9tZXNzYWdlcwBtcm91bmRfdGltZW91dABxZ3JvdXBfYmFja3VwX3NpemUAcmFsbG93ZWRfc3RyYWdnbGVycwBpZW50aXR5X2lkWCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGx0ZWVfaGFyZHdhcmUAcGFkbWlzc2lvbl9wb2xpY3mhaGFueV9ub2RloHBnb3Zlcm5hbmNlX21vZGVsAA==" once cbor is fixed.
+ (
+ "q2F2AGJpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABka2luZABnZ2VuZXNpc6Jlcm91bmQAanN0YXRlX3Jvb3RYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAZ3N0b3JhZ2Wjc2NoZWNrcG9pbnRfaW50ZXJ2YWwAc2NoZWNrcG9pbnRfbnVtX2tlcHQAdWNoZWNrcG9pbnRfY2h1bmtfc2l6ZQBoZXhlY3V0b3Klamdyb3VwX3NpemUAbG1heF9tZXNzYWdlcwBtcm91bmRfdGltZW91dABxZ3JvdXBfYmFja3VwX3NpemUAcmFsbG93ZWRfc3RyYWdnbGVycwBpZW50aXR5X2lkWCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGx0ZWVfaGFyZHdhcmUAbXR4bl9zY2hlZHVsZXKgcGFkbWlzc2lvbl9wb2xpY3mhaGFueV9ub2RloHBnb3Zlcm5hbmNlX21vZGVsAA==",
+ Runtime {
+ admission_policy: RuntimeAdmissionPolicy {
+ any_node: Some(AnyNodeRuntimeAdmissionPolicy {}),
+ ..Default::default()
+ },
+ staking: RuntimeStakingParameters {
+ thresholds: BTreeMap::new(),
+ slashing: BTreeMap::new(),
+ reward_equivocation: 0,
+ reward_bad_results: 0,
+ min_in_message_fee: Quantity::from(0u32),
+ },
+ ..Default::default()
+ },
+ ),
+ // FIXME: Change to "q2F2AGJpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABka2luZABnZ2VuZXNpc6Jlcm91bmQAanN0YXRlX3Jvb3RYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAZ3N0YWtpbmehcnJld2FyZF9iYWRfcmVzdWx0cwpnc3RvcmFnZaNzY2hlY2twb2ludF9pbnRlcnZhbABzY2hlY2twb2ludF9udW1fa2VwdAB1Y2hlY2twb2ludF9jaHVua19zaXplAGhleGVjdXRvcqVqZ3JvdXBfc2l6ZQBsbWF4X21lc3NhZ2VzAG1yb3VuZF90aW1lb3V0AHFncm91cF9iYWNrdXBfc2l6ZQByYWxsb3dlZF9zdHJhZ2dsZXJzAGllbnRpdHlfaWRYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAbHRlZV9oYXJkd2FyZQBwYWRtaXNzaW9uX3BvbGljeaFoYW55X25vZGWgcGdvdmVybmFuY2VfbW9kZWwA" once cbor is fixed.
+ (
+ "rGF2AGJpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABka2luZABnZ2VuZXNpc6Jlcm91bmQAanN0YXRlX3Jvb3RYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAZ3N0YWtpbmehcnJld2FyZF9iYWRfcmVzdWx0cwpnc3RvcmFnZaNzY2hlY2twb2ludF9pbnRlcnZhbABzY2hlY2twb2ludF9udW1fa2VwdAB1Y2hlY2twb2ludF9jaHVua19zaXplAGhleGVjdXRvcqVqZ3JvdXBfc2l6ZQBsbWF4X21lc3NhZ2VzAG1yb3VuZF90aW1lb3V0AHFncm91cF9iYWNrdXBfc2l6ZQByYWxsb3dlZF9zdHJhZ2dsZXJzAGllbnRpdHlfaWRYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAbHRlZV9oYXJkd2FyZQBtdHhuX3NjaGVkdWxlcqBwYWRtaXNzaW9uX3BvbGljeaFoYW55X25vZGWgcGdvdmVybmFuY2VfbW9kZWwA",
+ Runtime {
+ admission_policy: RuntimeAdmissionPolicy {
+ any_node: Some(AnyNodeRuntimeAdmissionPolicy {}),
+ ..Default::default()
+ },
+ staking: RuntimeStakingParameters {
+ thresholds: BTreeMap::new(),
+ slashing: BTreeMap::new(),
+ reward_equivocation: 0,
+ reward_bad_results: 10,
+ min_in_message_fee: Quantity::from(0u32),
+ },
+ ..Default::default()
+ },
+ ),
+ (
+ "r2F2GCpiaWRYIIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAZGtpbmQCZ2dlbmVzaXOiZXJvdW5kGCtqc3RhdGVfcm9vdFggseUhAZ+3vd413IH+55BlYQy937jvXCXihJg2aBkqbQ1nc3Rha2luZ6FycmV3YXJkX2JhZF9yZXN1bHRzCmdzdG9yYWdlo3NjaGVja3BvaW50X2ludGVydmFsGCFzY2hlY2twb2ludF9udW1fa2VwdAZ1Y2hlY2twb2ludF9jaHVua19zaXplGGVoZXhlY3V0b3Kpamdyb3VwX3NpemUJbG1heF9tZXNzYWdlcwVtcm91bmRfdGltZW91dAZxZ3JvdXBfYmFja3VwX3NpemUIcmFsbG93ZWRfc3RyYWdnbGVycwdybWF4X2xpdmVuZXNzX2ZhaWxzAXRtaW5fbGl2ZV9yb3VuZHNfZXZhbAJ3bWluX2xpdmVfcm91bmRzX3BlcmNlbnQEeBxtYXhfbWlzc2VkX3Byb3Bvc2Fsc19wZXJjZW50A2llbnRpdHlfaWRYIBI0VniQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAa2NvbnN0cmFpbnRzoQGhAaNpbWF4X25vZGVzoWVsaW1pdAptbWluX3Bvb2xfc2l6ZaFlbGltaXQFbXZhbGlkYXRvcl9zZXSga2RlcGxveW1lbnRzgaRjdGVlS3ZlcnNpb24gdGVlZ3ZlcnNpb26iZW1ham9yGCxlcGF0Y2gBanZhbGlkX2Zyb20Ab2J1bmRsZV9jaGVja3N1bVggAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQFra2V5X21hbmFnZXJYIIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABbHRlZV9oYXJkd2FyZQFtdHhuX3NjaGVkdWxlcqVubWF4X2JhdGNoX3NpemUZJxBvbWF4X2luX21lc3NhZ2VzGCBzYmF0Y2hfZmx1c2hfdGltZW91dBo7msoAdG1heF9iYXRjaF9zaXplX2J5dGVzGgCYloB1cHJvcG9zZV9iYXRjaF90aW1lb3V0Gnc1lABwYWRtaXNzaW9uX3BvbGljeaFwZW50aXR5X3doaXRlbGlzdKFoZW50aXRpZXOhWCASNFZ4kAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKFpbWF4X25vZGVzogEDBAFwZ292ZXJuYW5jZV9tb2RlbAM=",
+ Runtime {
+ v: 42,
+ id: Namespace::from(
+ "8000000000000000000000000000000000000000000000000000000000000000",
+ ),
+ entity_id: signature::PublicKey::from(
+ "1234567890000000000000000000000000000000000000000000000000000000",
+ ),
+ genesis: RuntimeGenesis {
+ round: 43,
+ state_root: Hash::digest_bytes(b"stateroot hash"),
+ },
+ kind: RuntimeKind::KindKeyManager,
+ tee_hardware: TEEHardware::TEEHardwareIntelSGX,
+ deployments: vec![VersionInfo {
+ version: Version {
+ major: 44,
+ minor: 0,
+ patch: 1,
+ },
+ valid_from: 0,
+ tee: b"version tee".to_vec(),
+ bundle_checksum: vec![0x1; 32],
+ }],
+ key_manager: Some(Namespace::from(
+ "8000000000000000000000000000000000000000000000000000000000000001",
+ )),
+ executor: ExecutorParameters {
+ group_size: 9,
+ group_backup_size: 8,
+ allowed_stragglers: 7,
+ round_timeout: 6,
+ max_messages: 5,
+ min_live_rounds_percent: 4,
+ max_missed_proposals_percent: 3,
+ min_live_rounds_eval: 2,
+ max_liveness_fails: 1,
+ },
+ txn_scheduler: TxnSchedulerParameters {
+ batch_flush_timeout: 1_000_000_000, // 1 second.
+ max_batch_size: 10_000,
+ max_batch_size_bytes: 10_000_000,
+ max_in_messages: 32,
+ propose_batch_timeout: 2_000_000_000, // 2 seconds.
+ },
+ storage: StorageParameters {
+ checkpoint_interval: 33,
+ checkpoint_num_kept: 6,
+ checkpoint_chunk_size: 101,
+ },
+ admission_policy: RuntimeAdmissionPolicy {
+ entity_whitelist: Some(EntityWhitelistRuntimeAdmissionPolicy {
+ entities: btreemap! {
+ signature::PublicKey::from("1234567890000000000000000000000000000000000000000000000000000000") => EntityWhitelistConfig {
+ max_nodes: btreemap! {
+ RolesMask::ROLE_COMPUTE_WORKER => 3,
+ RolesMask::ROLE_KEY_MANAGER => 1,
+ }
+ }
+ },
+ }),
+ ..Default::default()
+ },
+ constraints: btreemap! {
+ scheduler::CommitteeKind::ComputeExecutor => btreemap! {
+ scheduler::Role::Worker => SchedulingConstraints{
+ max_nodes: Some(
+ MaxNodesConstraint{
+ limit: 10,
+ }
+ ),
+ min_pool_size: Some(
+ MinPoolSizeConstraint {
+ limit: 5,
+ }
+ ),
+ validator_set: Some(ValidatorSetConstraint{}),
+ },
+ }
+ },
+ staking: RuntimeStakingParameters {
+ thresholds: BTreeMap::new(),
+ slashing: BTreeMap::new(),
+ reward_equivocation: 0,
+ reward_bad_results: 10,
+ min_in_message_fee: Quantity::from(0u32),
+ },
+ governance_model: RuntimeGovernanceModel::GovernanceConsensus,
+ },
+ ),
+ ];
+ for (encoded_base64, rr) in tcs {
+ let dec: Runtime = cbor::from_slice(&BASE64_STANDARD.decode(encoded_base64).unwrap())
+ .expect("runtime should deserialize correctly");
+ assert_eq!(dec, rr, "decoded runtime should match the expected value");
+ let ser = BASE64_STANDARD.encode(cbor::to_vec(dec));
+ assert_eq!(ser, encoded_base64, "runtime should serialize correctly");
+ }
+ }
+
+ #[test]
+ fn test_consistent_node() {
+ // NOTE: These tests MUST be synced with go/common/node/node_test.go.
+ let tcs = vec![
+ (
+ "qmF2A2JpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABjcDJwomJpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABpYWRkcmVzc2Vz9mN0bHOhZ3B1Yl9rZXlYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY3ZyZqFiaWRYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAZXJvbGVzAGhydW50aW1lc/ZpY29uc2Vuc3VzomJpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABpYWRkcmVzc2Vz9mllbnRpdHlfaWRYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAamV4cGlyYXRpb24A",
+ Node{v: 3, ..Default::default()},
+ true,
+ ),
+ (
+ "qmF2A2JpZFgg//////////////////////////////////////////BjcDJwomJpZFgg//////////////////////////////////////////VpYWRkcmVzc2Vz9mN0bHOhZ3B1Yl9rZXlYIP/////////////////////////////////////////yY3ZyZqFiaWRYIP/////////////////////////////////////////3ZXJvbGVzAGhydW50aW1lc4KkYmlkWCCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEGd2ZXJzaW9uoWVwYXRjaBkBQWpleHRyYV9pbmZv9mxjYXBhYmlsaXRpZXOgpGJpZFgggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABFndmVyc2lvbqFlcGF0Y2gYe2pleHRyYV9pbmZvRAUDAgFsY2FwYWJpbGl0aWVzoWN0ZWWjY3Jha1gg//////////////////////////////////////////hoaGFyZHdhcmUBa2F0dGVzdGF0aW9uRgABAgMEBWljb25zZW5zdXOiYmlkWCD/////////////////////////////////////////9mlhZGRyZXNzZXOAaWVudGl0eV9pZFgg//////////////////////////////////////////FqZXhwaXJhdGlvbhgg",
+ Node{
+ v: 3,
+ id: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0"),
+ entity_id: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff1"),
+ expiration: 32,
+ tls: TLSInfo{
+ pub_key: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff2"),
+ ..Default::default()
+ },
+ p2p: P2PInfo{
+ id: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff5"),
+ ..Default::default()
+ },
+ consensus: ConsensusInfo{
+ id: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff6"),
+ addresses: Some(Vec::new()),
+ },
+ vrf: VRFInfo{
+ id: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7"),
+ },
+ runtimes: Some(vec![
+ NodeRuntime{
+ id: Namespace::from("8000000000000000000000000000000000000000000000000000000000000010"),
+ version: Version::from(321u64),
+ ..Default::default()
+ },
+ NodeRuntime{
+ id: Namespace::from("8000000000000000000000000000000000000000000000000000000000000011"),
+ version: Version::from(123),
+ capabilities: Capabilities{
+ tee: Some(CapabilityTEE{
+ hardware: TEEHardware::TEEHardwareIntelSGX,
+ rak: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff8"),
+ attestation: vec![0, 1,2,3,4,5],
+ ..Default::default()
+ }),
+ },
+ extra_info: Some(vec![5,3,2,1]),
+ },
+ ]),
+ ..Default::default()
+ },
+ true,
+ ),
+ (
+ "qWF2A2JpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABjcDJwomJpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABpYWRkcmVzc2Vz9mN0bHOhZ3B1Yl9rZXlYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAZXJvbGVzAGhydW50aW1lc4GkYmlkWCCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEGd2ZXJzaW9uoGpleHRyYV9pbmZv9mxjYXBhYmlsaXRpZXOgaWNvbnNlbnN1c6JiaWRYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAaWFkZHJlc3Nlc/ZpZW50aXR5X2lkWCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGpleHBpcmF0aW9uAA==",
+ Node{
+ v: 3,
+ runtimes: Some(vec![
+ NodeRuntime{
+ id: Namespace::from("8000000000000000000000000000000000000000000000000000000000000010"),
+ version: Version::from(0u64),
+ ..Default::default()
+ },
+ ]),
+ ..Default::default()
+ },
+ false,
+ ),
+ ];
+ for (encoded_base64, node, round_trip) in tcs {
+ println!("{:?}", node);
+ let dec: Node = cbor::from_slice(&BASE64_STANDARD.decode(encoded_base64).unwrap())
+ .expect("node should deserialize correctly");
+ assert_eq!(dec, node, "decoded node should match the expected value");
+
+ if round_trip {
+ let ser = BASE64_STANDARD.encode(cbor::to_vec(dec));
+ assert_eq!(ser, encoded_base64, "node should serialize correctly");
+ }
+ }
+ }
+
+ #[test]
+ fn test_deserialize_node_v2() {
+ // NOTE: These tests MUST be synced with go/common/node/node_test.go.
+ let tcs = vec![
+ (
+ "qWF2AmJpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABjcDJwomJpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABpYWRkcmVzc2Vz9mN0bHOiZ3B1Yl9rZXlYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAaWFkZHJlc3Nlc/Zlcm9sZXMAaHJ1bnRpbWVz9mljb25zZW5zdXOiYmlkWCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGlhZGRyZXNzZXP2aWVudGl0eV9pZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABqZXhwaXJhdGlvbgA=",
+ Node{v: 2, ..Default::default()},
+ ),
+ (
+ "qmF2AmJpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABjcDJwomJpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABpYWRkcmVzc2Vz9mN0bHOjZ3B1Yl9rZXlYIP/////////////////////////////////////////yaWFkZHJlc3Nlc4BsbmV4dF9wdWJfa2V5WCD/////////////////////////////////////////82N2cmahYmlkWCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGVyb2xlcwBocnVudGltZXP2aWNvbnNlbnN1c6JiaWRYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAaWFkZHJlc3Nlc/ZpZW50aXR5X2lkWCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAGpleHBpcmF0aW9uAA==",
+ Node{
+ v: 2,
+ tls: TLSInfo{
+ pub_key: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff2"),
+ _deprecated_next_pub_key: Some(signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff3")),
+ _deprecated_addresses: Some(vec![]),
+ },
+ ..Default::default()
+ },
+ ),
+ (
+ "qmF2AmJpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABjcDJwomJpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABpYWRkcmVzc2Vz9mN0bHOjZ3B1Yl9rZXlYIP/////////////////////////////////////////yaWFkZHJlc3Nlc4OiZ2FkZHJlc3OjYklQUAAAAAAAAAAAAAD//38AAAFkUG9ydBh7ZFpvbmVgZ3B1Yl9rZXlYIP/////////////////////////////////////////0omdhZGRyZXNzo2JJUFAAAAAAAAAAAAAA///AqAEBZFBvcnQZD6BkWm9uZWBncHViX2tleVgg/////////////////////////////////////////8SiZ2FkZHJlc3OjYklQUAAAAAAAAAAAAAD//+pkY1hkUG9ydBkfQGRab25lYGdwdWJfa2V5WCD/////////////////////////////////////////1GxuZXh0X3B1Yl9rZXlYIP/////////////////////////////////////////zY3ZyZqFiaWRYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAZXJvbGVzAGhydW50aW1lc/ZpY29uc2Vuc3VzomJpZFggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABpYWRkcmVzc2Vz9mllbnRpdHlfaWRYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAamV4cGlyYXRpb24A",
+ Node{
+ v: 2,
+ tls: TLSInfo{
+ pub_key: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff2"),
+ _deprecated_next_pub_key: Some(signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff3")),
+ _deprecated_addresses: Some(vec![
+ TLSAddress{
+ pub_key: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff4"),
+ address: TCPAddress { ip: Ipv4Addr::new(127, 0, 0, 1).to_ipv6_mapped().octets().to_vec(), port: 123, ..Default::default() }
+ },
+ TLSAddress{
+ pub_key: signature::PublicKey::from("ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffc4"),
+ address: TCPAddress { ip: Ipv4Addr::new(192, 168, 1, 1).to_ipv6_mapped().octets().to_vec(), port: 4000, ..Default::default() }
+ },
+ TLSAddress{
+ pub_key: signature::PublicKey::from("ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffd4"),
+ address: TCPAddress { ip: Ipv4Addr::new(234, 100, 99, 88).to_ipv6_mapped().octets().to_vec(), port: 8000, ..Default::default() }
+ },
+
+ ])
+ },
+ ..Default::default()
+ },
+ ),
+ (
+ "qmF2AmJpZFgg//////////////////////////////////////////BjcDJwomJpZFgg//////////////////////////////////////////VpYWRkcmVzc2Vz9mN0bHOjZ3B1Yl9rZXlYIP/////////////////////////////////////////yaWFkZHJlc3Nlc4GiZ2FkZHJlc3OjYklQUAAAAAAAAAAAAAD//38AAAFkUG9ydBh7ZFpvbmVgZ3B1Yl9rZXlYIP/////////////////////////////////////////0bG5leHRfcHViX2tleVgg//////////////////////////////////////////NjdnJmoWJpZFgg//////////////////////////////////////////dlcm9sZXMAaHJ1bnRpbWVzgqRiaWRYIIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQZ3ZlcnNpb26hZXBhdGNoGQFBamV4dHJhX2luZm/2bGNhcGFiaWxpdGllc6CkYmlkWCCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEWd2ZXJzaW9uoWVwYXRjaBh7amV4dHJhX2luZm9EBQMCAWxjYXBhYmlsaXRpZXOhY3RlZaNjcmFrWCD/////////////////////////////////////////+GhoYXJkd2FyZQFrYXR0ZXN0YXRpb25GAAECAwQFaWNvbnNlbnN1c6JiaWRYIP/////////////////////////////////////////2aWFkZHJlc3Nlc4BpZW50aXR5X2lkWCD/////////////////////////////////////////8WpleHBpcmF0aW9uGCA=",
+ Node{
+ v: 2,
+ id: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0"),
+ entity_id: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff1"),
+ expiration: 32,
+ tls: TLSInfo{
+ pub_key: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff2"),
+ _deprecated_next_pub_key: Some(signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff3")),
+ _deprecated_addresses: Some(vec![TLSAddress{
+ pub_key: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff4"),
+ address: TCPAddress { ip: Ipv4Addr::new(127, 0, 0, 1).to_ipv6_mapped().octets().to_vec(), port: 123, ..Default::default() }
+ }])
+ },
+ p2p: P2PInfo{
+ id: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff5"),
+ ..Default::default()
+ },
+ consensus: ConsensusInfo{
+ id: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff6"),
+ addresses: Some(Vec::new()),
+ },
+ vrf: VRFInfo{
+ id: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7"),
+ },
+ runtimes: Some(vec![
+ NodeRuntime{
+ id: Namespace::from("8000000000000000000000000000000000000000000000000000000000000010"),
+ version: Version::from(321u64),
+ ..Default::default()
+ },
+ NodeRuntime{
+ id: Namespace::from("8000000000000000000000000000000000000000000000000000000000000011"),
+ version: Version::from(123),
+ capabilities: Capabilities{
+ tee: Some(CapabilityTEE{
+ hardware: TEEHardware::TEEHardwareIntelSGX,
+ rak: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff8"),
+ attestation: vec![0, 1,2,3,4,5],
+ ..Default::default()
+ }),
+ },
+ extra_info: Some(vec![5,3,2,1]),
+ },
+ ]),
+ ..Default::default()
+ },
+ ),
+ (
+ "qmF2AmJpZFgg//////////////////////////////////////////BjcDJwomJpZFgg//////////////////////////////////////////VpYWRkcmVzc2Vz9mN0bHOjZ3B1Yl9rZXlYIP/////////////////////////////////////////yaWFkZHJlc3Nlc4GiZ2FkZHJlc3OjYklQUAAAAAAAAAAAAAD//38AAAFkUG9ydBh7ZFpvbmVgZ3B1Yl9rZXlYIP/////////////////////////////////////////0bG5leHRfcHViX2tleVgg//////////////////////////////////////////NjdnJmoWJpZFgg//////////////////////////////////////////dlcm9sZXMAaHJ1bnRpbWVzgqRiaWRYIIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQZ3ZlcnNpb26hZXBhdGNoGQFBamV4dHJhX2luZm/2bGNhcGFiaWxpdGllc6CkYmlkWCCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEWd2ZXJzaW9uoWVwYXRjaBh7amV4dHJhX2luZm9EBQMCAWxjYXBhYmlsaXRpZXOhY3RlZaRjcmFrWCD/////////////////////////////////////////+GNyZWtYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAaGhhcmR3YXJlAWthdHRlc3RhdGlvbkYAAQIDBAVpY29uc2Vuc3VzomJpZFgg//////////////////////////////////////////ZpYWRkcmVzc2VzgGllbnRpdHlfaWRYIP/////////////////////////////////////////xamV4cGlyYXRpb24YIA==",
+ Node{
+ v: 2,
+ id: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0"),
+ entity_id: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff1"),
+ expiration: 32,
+ tls: TLSInfo{
+ pub_key: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff2"),
+ _deprecated_next_pub_key: Some(signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff3")),
+ _deprecated_addresses: Some(vec![TLSAddress{
+ pub_key: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff4"),
+ address: TCPAddress { ip: Ipv4Addr::new(127, 0, 0, 1).to_ipv6_mapped().octets().to_vec(), port: 123, ..Default::default() }
+ }])
+ },
+ p2p: P2PInfo{
+ id: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff5"),
+ ..Default::default()
+ },
+ consensus: ConsensusInfo{
+ id: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff6"),
+ addresses: Some(Vec::new()),
+ },
+ vrf: VRFInfo{
+ id: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff7"),
+ },
+ runtimes: Some(vec![
+ NodeRuntime{
+ id: Namespace::from("8000000000000000000000000000000000000000000000000000000000000010"),
+ version: Version::from(321u64),
+ ..Default::default()
+ },
+ NodeRuntime{
+ id: Namespace::from("8000000000000000000000000000000000000000000000000000000000000011"),
+ version: Version::from(123),
+ capabilities: Capabilities{
+ tee: Some(CapabilityTEE{
+ hardware: TEEHardware::TEEHardwareIntelSGX,
+ rak: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff8"),
+ rek: Some(x25519::PublicKey::from([0;32])),
+ attestation: vec![0, 1,2,3,4,5],
+ }),
+ },
+ extra_info: Some(vec![5,3,2,1]),
+ },
+ ]),
+ ..Default::default()
+ },
+ ),
+ ];
+ for (encoded_base64, node) in tcs {
+ println!("{:?}", node);
+ let dec: Node = cbor::from_slice(&BASE64_STANDARD.decode(encoded_base64).unwrap())
+ .expect("node should deserialize correctly");
+ assert_eq!(dec, node, "decoded node should match the expected value");
+ }
+ }
+
+ #[test]
+ fn test_runtime_deployments() {
+ let rt = Runtime::default();
+ assert_eq!(rt.active_deployment(0), None);
+
+ let rt = Runtime {
+ deployments: vec![
+ VersionInfo {
+ version: Version {
+ major: 0,
+ minor: 1,
+ patch: 0,
+ },
+ valid_from: 0,
+ ..Default::default()
+ },
+ VersionInfo {
+ version: Version {
+ major: 0,
+ minor: 2,
+ patch: 0,
+ },
+ valid_from: 10,
+ ..Default::default()
+ },
+ VersionInfo {
+ version: Version {
+ major: 0,
+ minor: 3,
+ patch: 0,
+ },
+ valid_from: 20,
+ ..Default::default()
+ },
+ ],
+ ..Default::default()
+ };
+
+ let ad = rt.active_deployment(0).unwrap();
+ assert_eq!(ad.version.minor, 1);
+ let ad = rt.active_deployment(1).unwrap();
+ assert_eq!(ad.version.minor, 1);
+ let ad = rt.active_deployment(9).unwrap();
+ assert_eq!(ad.version.minor, 1);
+ let ad = rt.active_deployment(10).unwrap();
+ assert_eq!(ad.version.minor, 2);
+ let ad = rt.active_deployment(20).unwrap();
+ assert_eq!(ad.version.minor, 3);
+ let ad = rt.active_deployment(50).unwrap();
+ assert_eq!(ad.version.minor, 3);
+ let ad = rt.active_deployment(100).unwrap();
+ assert_eq!(ad.version.minor, 3);
+ let ad = rt.active_deployment(1000).unwrap();
+ assert_eq!(ad.version.minor, 3);
+
+ let ad = rt
+ .deployment_for_version(Version {
+ major: 0,
+ minor: 1,
+ patch: 0,
+ })
+ .unwrap();
+ assert_eq!(ad.valid_from, 0);
+ let ad = rt
+ .deployment_for_version(Version {
+ major: 0,
+ minor: 2,
+ patch: 0,
+ })
+ .unwrap();
+ assert_eq!(ad.valid_from, 10);
+ let ad = rt
+ .deployment_for_version(Version {
+ major: 0,
+ minor: 3,
+ patch: 0,
+ })
+ .unwrap();
+ assert_eq!(ad.valid_from, 20);
+ let ad = rt.deployment_for_version(Version {
+ major: 0,
+ minor: 99,
+ patch: 0,
+ });
+ assert_eq!(ad, None);
+ }
+
+ #[test]
+ fn test_hash_attestation() {
+ let report_data = b"foo bar";
+ let node_id = signature::PublicKey::from(
+ "47aadd91516ac548decdb436fde957992610facc09ba2f850da0fe1b2be96119",
+ );
+ let height = 42;
+ let rek: [u8; x25519::PUBLIC_KEY_LENGTH] =
+ "7992610facc09ba2f850da0fe1b2be9611947aadd91516ac548decdb436fde95"
+ .from_hex::<Vec<u8>>()
+ .unwrap()
+ .try_into()
+ .unwrap();
+ let rek = x25519::PublicKey::from(rek);
+
+ let h = SGXAttestation::hash(report_data, &node_id, height, &rek);
+ assert_eq!(
+ h.to_hex::<String>(),
+ "9a288bd33ba7a4c2eefdee68e4c08c1a34c369302ef8176a3bfdb4fedcec333e"
+ );
+ }
+
+ #[test]
+ fn test_roles_mask() {
+ let mask = RolesMask::ROLE_OBSERVER | RolesMask::ROLE_COMPUTE_WORKER;
+ assert!(mask.contains(RolesMask::ROLE_OBSERVER));
+ assert!(mask.contains(RolesMask::ROLE_COMPUTE_WORKER));
+ assert!(!mask.contains(RolesMask::ROLE_KEY_MANAGER));
+ assert!(!mask.contains(RolesMask::ROLE_VALIDATOR));
+ assert!(!mask.contains(RolesMask::ROLE_STORAGE_RPC));
+ assert!(!mask.is_single_role());
+
+ let mask = RolesMask::ROLE_OBSERVER;
+ assert!(mask.is_single_role());
+
+ let node = Node {
+ roles: RolesMask::ROLE_COMPUTE_WORKER | RolesMask::ROLE_VALIDATOR,
+ ..Default::default()
+ };
+ assert!(node.has_roles(RolesMask::ROLE_COMPUTE_WORKER));
+ assert!(node.has_roles(RolesMask::ROLE_VALIDATOR));
+ assert!(node.has_roles(RolesMask::ROLE_COMPUTE_WORKER | RolesMask::ROLE_VALIDATOR));
+ assert!(!node.has_roles(RolesMask::ROLE_KEY_MANAGER));
+ assert!(!node.has_roles(RolesMask::ROLE_STORAGE_RPC));
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +
//! Roothash block and header.
+//!
+//! # Note
+//!
+//! This **MUST** be kept in sync with go/roothash/api/block.
+//!
+use crate::common::{crypto::hash::Hash, namespace::Namespace};
+
+/// Runtime block.
+///
+/// # Note
+///
+/// This should be kept in sync with go/roothash/api/block/block.go.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct Block {
+ /// Header.
+ pub header: Header,
+}
+
+impl Block {
+ /// Creates a new empty genesis block given a runtime id and POSIX timestamp.
+ pub fn new_genesis_block(id: Namespace, timestamp: u64) -> Block {
+ Block {
+ header: Header {
+ version: 0,
+ round: 0,
+ timestamp,
+ header_type: HeaderType::Normal,
+ namespace: id,
+ previous_hash: Hash::empty_hash(),
+ io_root: Hash::empty_hash(),
+ state_root: Hash::empty_hash(),
+ messages_hash: Hash::empty_hash(),
+ in_msgs_hash: Hash::empty_hash(),
+ },
+ }
+ }
+
+ /// Creates a new empty block with a specific type.
+ pub fn new_empty_block(child: &Block, timestamp: u64, header_type: HeaderType) -> Block {
+ Block {
+ header: Header {
+ version: child.header.version,
+ namespace: child.header.namespace,
+ round: child.header.round + 1,
+ timestamp,
+ header_type,
+ previous_hash: child.header.encoded_hash(),
+ io_root: Hash::empty_hash(),
+ // State root is unchanged.
+ state_root: child.header.state_root,
+ messages_hash: Hash::empty_hash(),
+ in_msgs_hash: Hash::empty_hash(),
+ },
+ }
+ }
+}
+
+/// Header type.
+///
+/// # Note
+///
+/// This should be kept in sync with go/roothash/api/block/header.go.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+#[repr(u8)]
+pub enum HeaderType {
+ #[default]
+ Invalid = 0,
+ Normal = 1,
+ RoundFailed = 2,
+ EpochTransition = 3,
+ Suspended = 4,
+}
+
+/// Block header.
+///
+/// # Note
+///
+/// This should be kept in sync with go/roothash/api/block/header.go.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct Header {
+ /// Protocol version number.
+ pub version: u16,
+ /// Chain namespace.
+ pub namespace: Namespace,
+ /// Round number.
+ pub round: u64,
+ /// Timestamp (POSIX time).
+ pub timestamp: u64,
+ /// Header type.
+ pub header_type: HeaderType,
+ /// Previous block hash.
+ pub previous_hash: Hash,
+ /// I/O merkle root.
+ pub io_root: Hash,
+ /// State merkle root.
+ pub state_root: Hash,
+ /// Messages hash.
+ pub messages_hash: Hash,
+ /// Hash of processed incoming messages.
+ pub in_msgs_hash: Hash,
+}
+
+impl Header {
+ /// Returns a hash of an encoded header.
+ pub fn encoded_hash(&self) -> Hash {
+ Hash::digest_bytes(&cbor::to_vec(self.clone()))
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn test_consistent_hash_header() {
+ // NOTE: These hashes MUST be synced with go/roothash/api/block/header_test.go.
+ let empty = Header::default();
+ assert_eq!(
+ empty.encoded_hash(),
+ Hash::from("677ad1a6b9f5e99ed94e5d598b6f92a4641a5f952f2d753b2a6122b6dceeb792")
+ );
+
+ let populated = Header {
+ version: 42,
+ namespace: Namespace::from(Hash::empty_hash().as_ref()),
+ round: 1000,
+ timestamp: 1560257841,
+ header_type: HeaderType::RoundFailed,
+ previous_hash: empty.encoded_hash(),
+ io_root: Hash::empty_hash(),
+ state_root: Hash::empty_hash(),
+ messages_hash: Hash::empty_hash(),
+ in_msgs_hash: Hash::empty_hash(),
+ };
+ assert_eq!(
+ populated.encoded_hash(),
+ Hash::from("b17374d9b36796752a787d0726ef44826bfdb3ece52545e126c8e7592663544d")
+ );
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +
use std::any::Any;
+
+use anyhow::{anyhow, Result};
+
+use crate::{
+ common::{
+ crypto::{
+ hash::Hash,
+ signature::{
+ signature_context_with_chain_separation, signature_context_with_runtime_separation,
+ PublicKey, Signature, Signer,
+ },
+ },
+ namespace::Namespace,
+ },
+ consensus::roothash::{Header, Message},
+};
+
+use super::OpenCommitment;
+
+/// The signature context used to sign compute results headers with RAK.
+pub const COMPUTE_RESULTS_HEADER_SIGNATURE_CONTEXT: &[u8] =
+ b"oasis-core/roothash: compute results header";
+
+/// The signature context used to sign executor worker commitments.
+pub const EXECUTOR_COMMITMENT_SIGNATURE_CONTEXT: &[u8] =
+ b"oasis-core/roothash: executor commitment";
+
+fn executor_commitment_signature_context(
+ runtime_id: &Namespace,
+ chain_context: &String,
+) -> Vec<u8> {
+ let context = EXECUTOR_COMMITMENT_SIGNATURE_CONTEXT.to_vec();
+ let context = signature_context_with_runtime_separation(context, runtime_id);
+ signature_context_with_chain_separation(context, chain_context)
+}
+
+/// The header of a computed batch output by a runtime. This header is a
+/// compressed representation (e.g., hashes instead of full content) of
+/// the actual results.
+///
+/// # Note
+///
+/// This should be kept in sync with go/roothash/api/commitment/executor.go.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct ComputeResultsHeader {
+ /// Round number.
+ pub round: u64,
+ /// Hash of the previous block header this batch was computed against.
+ pub previous_hash: Hash,
+
+ /// The I/O merkle root.
+ #[cbor(optional)]
+ pub io_root: Option<Hash>,
+ /// The root hash of the state after computing this batch.
+ #[cbor(optional)]
+ pub state_root: Option<Hash>,
+ /// Hash of messages sent from this batch.
+ #[cbor(optional)]
+ pub messages_hash: Option<Hash>,
+
+ /// The hash of processed incoming messages.
+ #[cbor(optional)]
+ pub in_msgs_hash: Option<Hash>,
+ /// The number of processed incoming messages.
+ #[cbor(optional)]
+ pub in_msgs_count: u32,
+}
+
+impl ComputeResultsHeader {
+ /// Returns a hash of an encoded header.
+ pub fn encoded_hash(&self) -> Hash {
+ Hash::digest_bytes(&cbor::to_vec(self.clone()))
+ }
+
+ /// Returns true iff the header is the parent of a child header.
+ pub fn is_parent_of(&self, child: &Header) -> bool {
+ if self.round != child.round + 1 {
+ return false;
+ }
+ self.previous_hash == child.encoded_hash()
+ }
+}
+
+/// The executor commitment failure reason.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+#[repr(u8)]
+pub enum ExecutorCommitmentFailure {
+ /// Indicates that no failure has occurred.
+ #[default]
+ FailureNone = 0,
+
+ /// Indicates a generic failure.
+ FailureUnknown = 1,
+
+ /// Indicates that batch processing failed due to the state being
+ /// unavailable.
+ FailureStateUnavailable = 2,
+}
+
+/// The header of an executor commitment.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct ExecutorCommitmentHeader {
+ /// The compute results header.
+ pub header: ComputeResultsHeader,
+
+ /// The executor commitment failure reason.
+ #[cbor(optional)]
+ pub failure: ExecutorCommitmentFailure,
+
+ // Optional fields (may be absent for failure indication).
+ #[cbor(optional, rename = "rak_sig")]
+ pub rak_signature: Option<Signature>,
+}
+
+impl ExecutorCommitmentHeader {
+ /// Signs the executor commitment header.
+ pub fn sign(
+ &self,
+ signer: &impl Signer,
+ runtime_id: &Namespace,
+ chain_context: &String,
+ ) -> Result<Signature> {
+ let context = executor_commitment_signature_context(runtime_id, chain_context);
+ let message = cbor::to_vec(self.clone());
+
+ signer.sign(&context, &message)
+ }
+
+ /// Verifies the RAK signature.
+ pub fn verify_rak(&self, rak: PublicKey) -> Result<()> {
+ let sig = self.rak_signature.ok_or(anyhow!("missing RAK signature"))?;
+ let message = cbor::to_vec(self.header.clone());
+
+ sig.verify(&rak, COMPUTE_RESULTS_HEADER_SIGNATURE_CONTEXT, &message)
+ .map_err(|_| anyhow!("RAK signature verification failed"))
+ }
+}
+
+/// A commitment to results of processing a proposed runtime block.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct ExecutorCommitment {
+ // The public key of the node that generated this commitment.
+ pub node_id: PublicKey,
+
+ // The commitment header.
+ pub header: ExecutorCommitmentHeader,
+
+ // The commitment header signature.
+ #[cbor(rename = "sig")]
+ pub signature: Signature,
+
+ // The messages emitted by the runtime.
+ //
+ // This field is only present in case this commitment belongs to the proposer. In case of
+ // the commitment being submitted as equivocation evidence, this field should be omitted.
+ #[cbor(optional)]
+ pub messages: Vec<Message>,
+}
+
+impl ExecutorCommitment {
+ /// Signs the executor commitment header and sets the signature on the commitment.
+ pub fn sign(
+ &mut self,
+ signer: &impl Signer,
+ runtime_id: &Namespace,
+ chain_context: &String,
+ ) -> Result<()> {
+ let pk = signer.public();
+ if self.node_id != pk {
+ return Err(anyhow!(
+ "node ID does not match signer (ID: {} signer: {})",
+ self.node_id,
+ pk,
+ ));
+ }
+
+ self.signature = self.header.sign(signer, runtime_id, chain_context)?;
+
+ Ok(())
+ }
+
+ /// Verifies that the header signature is valid.
+ pub fn verify(&self, runtime_id: &Namespace, chain_context: &String) -> Result<()> {
+ let context = executor_commitment_signature_context(runtime_id, chain_context);
+ let message = cbor::to_vec(self.header.clone());
+
+ self.signature
+ .verify(&self.node_id, &context, &message)
+ .map_err(|_| anyhow!("roothash/commitment: signature verification failed"))
+ }
+
+ pub fn validate_basic(&self) -> Result<()> {
+ match self.header.failure {
+ ExecutorCommitmentFailure::FailureNone => {
+ // Ensure header fields are present.
+ if self.header.header.io_root.is_none() {
+ return Err(anyhow!("missing IORoot"));
+ }
+ if self.header.header.state_root.is_none() {
+ return Err(anyhow!("missing StateRoot"));
+ }
+ if self.header.header.messages_hash.is_none() {
+ return Err(anyhow!("missing messages hash"));
+ }
+ if self.header.header.in_msgs_hash.is_none() {
+ return Err(anyhow!("missing incoming messages hash"));
+ }
+
+ // Validate any included runtime messages.
+ for msg in self.messages.iter() {
+ msg.validate_basic()
+ .map_err(|err| anyhow!("bad runtime message: {:?}", err))?;
+ }
+ }
+ ExecutorCommitmentFailure::FailureUnknown
+ | ExecutorCommitmentFailure::FailureStateUnavailable => {
+ // Ensure header fields are empty.
+ if self.header.header.io_root.is_some() {
+ return Err(anyhow!("failure indicating body includes IORoot"));
+ }
+ if self.header.header.state_root.is_some() {
+ return Err(anyhow!("failure indicating commitment includes StateRoot"));
+ }
+ if self.header.header.messages_hash.is_some() {
+ return Err(anyhow!(
+ "failure indicating commitment includes MessagesHash"
+ ));
+ }
+ if self.header.header.in_msgs_hash.is_some()
+ || self.header.header.in_msgs_count != 0
+ {
+ return Err(anyhow!(
+ "failure indicating commitment includes InMessagesHash/Count"
+ ));
+ }
+ // In case of failure indicating commitment make sure RAK signature is empty.
+ if self.header.rak_signature.is_some() {
+ return Err(anyhow!("failure indicating body includes RAK signature"));
+ }
+ // In case of failure indicating commitment make sure messages are empty.
+ if !self.messages.is_empty() {
+ return Err(anyhow!("failure indicating body includes messages"));
+ }
+ }
+ }
+
+ Ok(())
+ }
+}
+
+impl OpenCommitment for ExecutorCommitment {
+ fn mostly_equal(&self, other: &Self) -> bool {
+ self.to_vote() == other.to_vote()
+ }
+
+ fn is_indicating_failure(&self) -> bool {
+ self.header.failure != ExecutorCommitmentFailure::FailureNone
+ }
+
+ fn to_vote(&self) -> Hash {
+ self.header.header.encoded_hash()
+ }
+
+ fn to_dd_result(&self) -> &dyn Any {
+ self
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn test_consistent_hash() {
+ // NOTE: These hashes MUST be synced with go/roothash/api/commitment/executor_test.go.
+ let empty = ComputeResultsHeader::default();
+ assert_eq!(
+ empty.encoded_hash(),
+ Hash::from("57d73e02609a00fcf4ca43cbf8c9f12867c46942d246fb2b0bce42cbdb8db844")
+ );
+
+ let populated = ComputeResultsHeader {
+ round: 42,
+ previous_hash: empty.encoded_hash(),
+ io_root: Some(Hash::empty_hash()),
+ state_root: Some(Hash::empty_hash()),
+ messages_hash: Some(Hash::empty_hash()),
+ in_msgs_hash: Some(Hash::empty_hash()),
+ in_msgs_count: 0,
+ };
+ assert_eq!(
+ populated.encoded_hash(),
+ Hash::from("8459a9e6e3341cd2df5ada5737469a505baf92397aaa88b7100915324506d843")
+ );
+ }
+
+ #[test]
+ fn test_validate_basic() {
+ // NOTE: These hashes MUST be synced with go/roothash/api/commitment/executor_test.go.
+ let empty = ComputeResultsHeader::default();
+ assert_eq!(
+ empty.encoded_hash(),
+ Hash::from("57d73e02609a00fcf4ca43cbf8c9f12867c46942d246fb2b0bce42cbdb8db844")
+ );
+
+ let body = ExecutorCommitment {
+ header: ExecutorCommitmentHeader {
+ header: ComputeResultsHeader {
+ round: 42,
+ previous_hash: empty.encoded_hash(),
+ io_root: Some(Hash::empty_hash()),
+ state_root: Some(Hash::empty_hash()),
+ messages_hash: Some(Hash::empty_hash()),
+ in_msgs_hash: Some(Hash::empty_hash()),
+ in_msgs_count: 0,
+ },
+ failure: ExecutorCommitmentFailure::FailureNone,
+ rak_signature: None,
+ },
+ messages: vec![],
+ node_id: PublicKey::default(),
+ signature: Signature::default(),
+ };
+
+ let tcs: Vec<(&str, fn(&mut ExecutorCommitment), bool)> = vec![
+ (
+ "Ok",
+ |ec: &mut ExecutorCommitment| {
+ ec.header.header.round -= 1;
+ },
+ false,
+ ),
+ (
+ "Bad io_root",
+ |ec: &mut ExecutorCommitment| ec.header.header.io_root = None,
+ true,
+ ),
+ (
+ "Bad state_root",
+ |ec: &mut ExecutorCommitment| ec.header.header.state_root = None,
+ true,
+ ),
+ (
+ "Bad messages_hash",
+ |ec: &mut ExecutorCommitment| ec.header.header.messages_hash = None,
+ true,
+ ),
+ (
+ "Bad Failure (existing io_root)",
+ |ec: &mut ExecutorCommitment| {
+ ec.header.failure = ExecutorCommitmentFailure::FailureUnknown;
+ // ec.header.compute_results_header.io_root is set.
+ ec.header.header.state_root = None;
+ ec.header.header.messages_hash = None;
+ ec.header.header.in_msgs_hash = None;
+ },
+ true,
+ ),
+ (
+ "Bad Failure (existing state_root)",
+ |ec: &mut ExecutorCommitment| {
+ ec.header.failure = ExecutorCommitmentFailure::FailureUnknown;
+ ec.header.header.io_root = None;
+ // ec.header.compute_results_header.state_root is set.
+ ec.header.header.messages_hash = None;
+ ec.header.header.in_msgs_hash = None;
+ },
+ true,
+ ),
+ (
+ "Bad Failure (existing messages_hash)",
+ |ec: &mut ExecutorCommitment| {
+ ec.header.failure = ExecutorCommitmentFailure::FailureUnknown;
+ ec.header.header.io_root = None;
+ ec.header.header.state_root = None;
+ // ec.header.compute_results_header.messages_hash is set.
+ ec.header.header.in_msgs_hash = None;
+ },
+ true,
+ ),
+ (
+ "Bad Failure (existing in_msgs_hash)",
+ |ec: &mut ExecutorCommitment| {
+ ec.header.failure = ExecutorCommitmentFailure::FailureUnknown;
+ ec.header.header.io_root = None;
+ ec.header.header.state_root = None;
+ ec.header.header.messages_hash = None;
+ // ec.header.compute_results_header.in_msgs_hash is set.
+ },
+ true,
+ ),
+ (
+ "Ok Failure",
+ |ec: &mut ExecutorCommitment| {
+ ec.header.failure = ExecutorCommitmentFailure::FailureUnknown;
+ },
+ true,
+ ),
+ ];
+
+ for (name, f, should_err) in tcs {
+ let mut b = body.clone();
+ f(&mut b);
+ let res = b.validate_basic();
+ assert_eq!(res.is_err(), should_err, "validate_basic({})", name)
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +
//! Roothash commitments.
+//!
+//! # Note
+//!
+//! This **MUST** be kept in sync with go/roothash/api/commitment.
+//!
+use std::any::Any;
+
+use crate::common::crypto::hash::Hash;
+
+// Modules.
+mod executor;
+mod pool;
+
+// Re-exports.
+pub use executor::*;
+pub use pool::*;
+
+/// Verified roothash commitment.
+pub trait OpenCommitment {
+ /// Returns true if the commitment is mostly equal to another
+ /// specified commitment as per discrepancy detection criteria.
+ ///
+ /// The caller MUST guarantee that the passed commitment is of the same
+ /// type.
+ fn mostly_equal(&self, other: &Self) -> bool
+ where
+ Self: Sized;
+
+ /// Returns true if this commitment indicates a failure.
+ fn is_indicating_failure(&self) -> bool;
+
+ /// Returns a hash that represents a vote for this commitment as
+ /// per discrepancy resolution criteria.
+ fn to_vote(&self) -> Hash;
+
+ /// Returns a commitment-specific result after discrepancy
+ /// detection.
+ fn to_dd_result(&self) -> &dyn Any;
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +
use std::collections::{HashMap, HashSet};
+
+use anyhow::Result;
+
+use crate::{
+ common::crypto::{hash::Hash, signature::PublicKey},
+ consensus::{
+ registry::{Node, Runtime, TEEHardware},
+ roothash::{Block, Error, Message, OpenCommitment},
+ scheduler::{Committee, CommitteeKind, Role},
+ },
+};
+
+use super::ExecutorCommitment;
+
+/// A trait for looking up registry node descriptors.
+pub trait NodeLookup {
+ fn node(&self, id: PublicKey) -> Result<Node, Error>;
+}
+
+/// A trait that validates messages for validity. It can be used for gas accounting.
+pub trait MessageValidator {
+ fn validate(&self, msgs: &[Message]) -> Result<()>;
+}
+
+impl<F> MessageValidator for F
+where
+ F: Fn(&[Message]) -> Result<()>,
+{
+ fn validate(&self, msgs: &[Message]) -> Result<()> {
+ (*self)(msgs)
+ }
+}
+
+/// A pool of commitments that can be used to perform
+/// discrepancy detection.
+///
+/// The pool is not safe for concurrent use.
+pub struct Pool {
+ /// The runtime descriptor this pool is collecting
+ /// the commitments for.
+ runtime: Runtime,
+ /// The committee this pool is collecting the commitments for.
+ committee: Committee,
+ /// The current protocol round.
+ round: u64,
+ // The commitments in the pool iff Committee.Kind
+ // is scheduler.KindComputeExecutor.
+ execute_commitments: HashMap<PublicKey, ExecutorCommitment>,
+ // A flag signalling that a discrepancy has been detected.
+ discrepancy: bool,
+ // The time when the next call to TryFinalize(true) should
+ // be scheduled to be executed. Zero means that no timeout is to be scheduled.
+ _next_timeout: i64,
+
+ // A cached committee member set. It will be automatically
+ // constructed based on the passed Committee.
+ member_set: HashSet<PublicKey>,
+ // A cached committee worker set. It will be automatically
+ // constructed based on the passed Committee.
+ _worker_set: HashSet<PublicKey>,
+}
+
+impl Pool {
+ /// Creates a new pool.
+ pub fn new(runtime: Runtime, committee: Committee, round: u64) -> Self {
+ let mut member_set = HashSet::new();
+ let mut _worker_set = HashSet::new();
+
+ for m in &committee.members {
+ member_set.insert(m.public_key);
+ if m.role == Role::Worker {
+ _worker_set.insert(m.public_key);
+ }
+ }
+
+ Pool {
+ runtime,
+ committee,
+ round,
+ execute_commitments: HashMap::new(),
+ discrepancy: false,
+ _next_timeout: 0,
+ member_set,
+ _worker_set,
+ }
+ }
+
+ fn is_member(&self, id: &PublicKey) -> bool {
+ self.member_set.contains(id)
+ }
+
+ fn _is_worker(&self, id: &PublicKey) -> bool {
+ self._worker_set.contains(id)
+ }
+
+ fn is_scheduler(&self, id: &PublicKey) -> bool {
+ if let Ok(scheduler) = self.committee.transaction_scheduler(self.round) {
+ return &scheduler.public_key == id;
+ }
+ false
+ }
+
+ /// Verifies and adds a new executor commitment to the pool.
+ fn add_verified_executor_commitment(
+ &mut self,
+ blk: &Block,
+ nl: &impl NodeLookup,
+ msg_validator: &impl MessageValidator,
+ commit: ExecutorCommitment,
+ ) -> Result<()> {
+ if self.committee.kind != CommitteeKind::ComputeExecutor {
+ return Err(Error::InvalidCommitteeKind.into());
+ }
+
+ // Ensure that the node is actually a committee member. We do not enforce specific
+ // roles based on current discrepancy state to allow commitments arriving in any
+ // order (e.g., a backup worker can submit a commitment even before there is a
+ // discrepancy).
+ if !self.is_member(&commit.node_id) {
+ return Err(Error::NotInCommittee.into());
+ }
+
+ // Ensure the node did not already submit a commitment.
+ if self.execute_commitments.contains_key(&commit.node_id) {
+ return Err(Error::AlreadyCommitted.into());
+ }
+
+ if self.round != blk.header.round {
+ return Err(Error::InvalidRound.into());
+ }
+
+ // Check if the block is based on the previous block.
+ if !commit.header.header.is_parent_of(&blk.header) {
+ return Err(Error::NotBasedOnCorrectBlock.into());
+ }
+
+ if commit.validate_basic().is_err() {
+ return Err(Error::BadExecutorCommitment.into());
+ }
+
+ // TODO: Check for evidence of equivocation (oasis-core#3685).
+
+ if !commit.is_indicating_failure() {
+ // Verify RAK-attestation.
+ if self.runtime.tee_hardware != TEEHardware::TEEHardwareInvalid {
+ let n = nl.node(commit.node_id).map_err(|_|
+ // This should never happen as nodes cannot disappear mid-epoch.
+ Error::NotInCommittee)?;
+
+ let ad = self
+ .runtime
+ .active_deployment(self.committee.valid_for)
+ .ok_or(
+ // This should never happen as we prevent this elsewhere.
+ Error::NoRuntime,
+ )?;
+
+ let rt = n.get_runtime(&self.runtime.id, &ad.version).ok_or(
+ // We currently prevent this case throughout the rest of the system.
+ // Still, it's prudent to check.
+ Error::NotInCommittee,
+ )?;
+
+ let tee = rt.capabilities.tee.ok_or(
+ // This should never happen as we prevent this elsewhere.
+ Error::RakSigInvalid,
+ )?;
+
+ commit
+ .header
+ .verify_rak(tee.rak)
+ .map_err(|_| Error::RakSigInvalid)?;
+ }
+
+ // Check emitted runtime messages.
+ match self.is_scheduler(&commit.node_id) {
+ true => {
+ // The transaction scheduler can include messages.
+ if commit.messages.len() as u32 > self.runtime.executor.max_messages {
+ return Err(Error::InvalidMessages.into());
+ }
+
+ let messages_hash = commit
+ .header
+ .header
+ .messages_hash
+ .ok_or(Error::InvalidMessages)?;
+ let h = Message::messages_hash(&commit.messages);
+ if h != messages_hash {
+ return Err(Error::InvalidMessages.into());
+ }
+
+ // Perform custom message validation and propagate the error unchanged.
+ if !commit.messages.is_empty() {
+ msg_validator.validate(&commit.messages)?;
+ }
+ }
+ false => {
+ // Other workers cannot include any messages.
+ if !commit.messages.is_empty() {
+ return Err(Error::InvalidMessages.into());
+ }
+ }
+ }
+ }
+
+ self.execute_commitments.insert(commit.node_id, commit);
+
+ Ok(())
+ }
+
+ /// Verifies and adds a new executor commitment to the pool.
+ pub fn add_executor_commitment(
+ &mut self,
+ blk: &Block,
+ nl: &impl NodeLookup,
+ commit: ExecutorCommitment,
+ msg_validator: &impl MessageValidator,
+ chain_context: &String,
+ ) -> Result<()> {
+ // Check executor commitment signature.
+ commit.verify(&self.runtime.id, chain_context)?;
+
+ self.add_verified_executor_commitment(blk, nl, msg_validator, commit)
+ }
+
+ /// Performs a single round of commitment checks. If there are enough commitments
+ /// in the pool, it performs discrepancy detection or resolution.
+ pub fn process_commitments(&mut self, did_timeout: bool) -> Result<&dyn OpenCommitment> {
+ if self.committee.kind != CommitteeKind::ComputeExecutor {
+ panic!(
+ "roothash/commitment: unknown committee kind: {:?}",
+ self.committee.kind
+ );
+ }
+
+ #[derive(Default)]
+ struct Vote<'a> {
+ commit: Option<&'a ExecutorCommitment>,
+ tally: u16,
+ }
+
+ let mut total = 0;
+ let mut commits = 0;
+ let mut failures = 0;
+
+ // Gather votes.
+ let mut votes: HashMap<Hash, Vote> = HashMap::new();
+ for n in &self.committee.members {
+ if !self.discrepancy && n.role != Role::Worker {
+ continue;
+ }
+ if self.discrepancy && n.role != Role::BackupWorker {
+ continue;
+ }
+
+ total += 1;
+ let commit = match self.execute_commitments.get(&n.public_key) {
+ Some(commit) => commit,
+ None => continue,
+ };
+ commits += 1;
+
+ if commit.is_indicating_failure() {
+ failures += 1;
+ continue;
+ }
+
+ let k = commit.to_vote();
+ match votes.get_mut(&k) {
+ Some(v) => v.tally += 1,
+ None => {
+ votes.insert(
+ k,
+ Vote {
+ tally: 1,
+ commit: Some(commit),
+ },
+ );
+ }
+ }
+
+ if !self.discrepancy && votes.len() > 1 {
+ self.discrepancy = true;
+ return Err(Error::DiscrepancyDetected.into());
+ }
+ }
+
+ // Determine whether the proposer has submitted a commitment.
+ let proposer = self
+ .committee
+ .transaction_scheduler(self.round)
+ .map_err(|_| Error::NoCommittee)?;
+ let proposer_commit = self.execute_commitments.get(&proposer.public_key);
+ if proposer_commit.is_none() && did_timeout {
+ return Err(Error::NoProposerCommitment.into());
+ }
+
+ match self.discrepancy {
+ false => {
+ // Discrepancy detection.
+ let allowed_stragglers = self.runtime.executor.allowed_stragglers;
+
+ // If it is already known that the number of valid commitments will not exceed the required
+ // threshold, there is no need to wait for the timer to expire. Instead, proceed directly to
+ // the discrepancy resolution mode, regardless of any additional commits.
+ if failures > allowed_stragglers {
+ self.discrepancy = true;
+ return Err(Error::DiscrepancyDetected.into());
+ }
+
+ // While a timer is running, all nodes are required to answer.
+ let mut required = total;
+
+ // After the timeout has elapsed, a limited number of stragglers are allowed.
+ if did_timeout {
+ required -= allowed_stragglers;
+ commits -= failures // Since failures count as stragglers.
+ }
+
+ // Check if the majority has been reached.
+ if commits < required || proposer_commit.is_none() {
+ return Err(Error::StillWaiting.into());
+ }
+ }
+ true => {
+ // Discrepancy resolution.
+ let required = total / 2 + 1;
+
+ // Find the commit with the highest number of votes.
+ let mut top_vote = &Vote::default();
+ for v in votes.values() {
+ if v.tally > top_vote.tally {
+ top_vote = v;
+ }
+ }
+
+ // Fail the round if the majority cannot be reached due to insufficient votes remaining
+ // (e.g. too many nodes have failed),
+ let remaining = total - commits;
+ if top_vote.tally + remaining < required {
+ return Err(Error::InsufficientVotes.into());
+ }
+
+ // Check if the majority has been reached.
+ if top_vote.tally < required || proposer_commit.is_none() {
+ if did_timeout {
+ return Err(Error::InsufficientVotes.into());
+ }
+ return Err(Error::StillWaiting.into());
+ }
+
+ let proposer_commit = proposer_commit.expect("proposer commit should be set");
+ let top_vote_commit = top_vote.commit.expect("top vote commit should be set");
+
+ // Make sure that the majority commitment is the same as the proposer commitment.
+ if !proposer_commit.mostly_equal(top_vote_commit) {
+ return Err(Error::BadProposerCommitment.into());
+ }
+ }
+ }
+
+ // We must return the proposer commitment as that one contains additional data.
+ let proposer_commit = proposer_commit.expect("proposer commit should be set");
+ Ok(proposer_commit)
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use anyhow::{anyhow, Result};
+
+ use crate::{
+ common::{
+ crypto::{
+ hash::Hash,
+ signature::{self, PublicKey, Signature},
+ },
+ namespace::Namespace,
+ versioned::Versioned,
+ },
+ consensus::{
+ registry::{
+ ExecutorParameters, Node, NodeRuntime, Runtime, RuntimeGovernanceModel,
+ RuntimeKind, TEEHardware,
+ },
+ roothash::{
+ Block, ComputeResultsHeader, Error, ExecutorCommitment, ExecutorCommitmentFailure,
+ ExecutorCommitmentHeader, HeaderType, Message, Pool, RegistryMessage,
+ StakingMessage,
+ },
+ scheduler::{Committee, CommitteeKind, CommitteeNode, Role},
+ staking::Transfer,
+ },
+ };
+
+ use super::NodeLookup;
+
+ struct StaticNodeLookup {
+ runtime: NodeRuntime,
+ }
+
+ impl NodeLookup for StaticNodeLookup {
+ fn node(&self, id: PublicKey) -> Result<Node, Error> {
+ Ok(Node {
+ id,
+ runtimes: Some(vec![self.runtime.clone()]),
+ ..Default::default()
+ })
+ }
+ }
+
+ #[test]
+ fn test_pool_single_commitment() {
+ let chain_context = "test: oasis-core tests".to_owned();
+
+ // Generate a non-TEE runtime.
+ let id =
+ Namespace::from("0000000000000000000000000000000000000000000000000000000000000000");
+
+ let rt = Runtime {
+ id,
+ kind: RuntimeKind::KindCompute,
+ tee_hardware: TEEHardware::TEEHardwareInvalid,
+ executor: ExecutorParameters {
+ max_messages: 32,
+ ..Default::default()
+ },
+ governance_model: RuntimeGovernanceModel::GovernanceEntity,
+ ..Default::default()
+ };
+
+ // Generate a commitment signing key.
+ let sk = signature::PrivateKey::generate();
+
+ // Generate a committee.
+ let committee = Committee {
+ kind: CommitteeKind::ComputeExecutor,
+ members: vec![CommitteeNode {
+ role: Role::Worker,
+ public_key: sk.public_key(),
+ }],
+ runtime_id: id,
+ valid_for: 0,
+ };
+
+ // Create a pool.
+ let mut pool = Pool::new(rt, committee, 0);
+
+ // Generate a commitment.
+ let (child_blk, _, mut ec) = generate_executor_commitment(id, pool.round);
+
+ let nl = StaticNodeLookup {
+ runtime: NodeRuntime {
+ id,
+ ..Default::default()
+ },
+ };
+
+ // Test invalid commitments.
+ let tcs: Vec<(&str, fn(&mut ExecutorCommitment), Error)> = vec![
+ (
+ "BlockBadRound",
+ |ec: &mut ExecutorCommitment| ec.header.header.round -= 1,
+ Error::NotBasedOnCorrectBlock,
+ ),
+ (
+ "BlockBadPreviousHash",
+ |ec: &mut ExecutorCommitment| {
+ ec.header.header.previous_hash = Hash::digest_bytes(b"invalid")
+ },
+ Error::NotBasedOnCorrectBlock,
+ ),
+ (
+ "MissingIORootHash",
+ |ec: &mut ExecutorCommitment| ec.header.header.io_root = None,
+ Error::BadExecutorCommitment,
+ ),
+ (
+ "MissingStateRootHash",
+ |ec: &mut ExecutorCommitment| ec.header.header.state_root = None,
+ Error::BadExecutorCommitment,
+ ),
+ (
+ "MissingMessagesHash",
+ |ec: &mut ExecutorCommitment| ec.header.header.messages_hash = None,
+ Error::BadExecutorCommitment,
+ ),
+ (
+ "MissingInMessagesHash",
+ |ec: &mut ExecutorCommitment| ec.header.header.in_msgs_hash = None,
+ Error::BadExecutorCommitment,
+ ),
+ (
+ "BadFailureIndicating",
+ |ec: &mut ExecutorCommitment| {
+ ec.header.failure = ExecutorCommitmentFailure::FailureUnknown
+ },
+ Error::BadExecutorCommitment,
+ ),
+ ];
+
+ let msg_validator = |_: &_| Ok(());
+ for (name, f, expected_err) in tcs {
+ let (_, _, mut invalid_ec) = generate_executor_commitment(id, pool.round);
+ f(&mut invalid_ec);
+
+ invalid_ec.node_id = sk.public_key();
+ let res = invalid_ec.sign(&sk, &id, &chain_context);
+ assert!(res.is_ok(), "invalid_ec.sign({})", name);
+
+ let res = pool.add_executor_commitment(
+ &child_blk,
+ &nl,
+ invalid_ec,
+ &msg_validator,
+ &chain_context,
+ );
+ assert!(res.is_err(), "add_executor_commitment({})", name);
+ assert_eq!(
+ res.err().unwrap().to_string(),
+ expected_err.to_string(),
+ "add_executor_commitment({})",
+ name
+ );
+ }
+
+ // Generate a valid commitment.
+ ec.node_id = sk.public_key();
+ let res = ec.sign(&sk, &id, &chain_context);
+ assert!(res.is_ok(), "ec.sign");
+
+ // There should not be enough executor commitments.
+ let res = pool.process_commitments(false);
+ assert_eq!(
+ res.err().unwrap().to_string(),
+ Error::StillWaiting.to_string(),
+ "process_commitments",
+ );
+
+ let res = pool.process_commitments(true);
+ assert_eq!(
+ res.err().unwrap().to_string(),
+ Error::NoProposerCommitment.to_string(),
+ "process_commitments",
+ );
+
+ // Test message validator function.
+ let mut ec_with_msgs = ec.clone();
+ ec_with_msgs.messages = vec![
+ Message::Staking(Versioned {
+ version: 0,
+ inner: StakingMessage::Transfer(Transfer::default()),
+ }),
+ Message::Registry(Versioned {
+ version: 0,
+ inner: RegistryMessage::UpdateRuntime(Runtime::default()),
+ }),
+ ];
+ let msg_hash = Message::messages_hash(&ec_with_msgs.messages);
+ ec_with_msgs.header.header.messages_hash = Some(msg_hash);
+
+ let res = ec_with_msgs.sign(&sk, &id, &chain_context);
+ assert!(res.is_ok(), "ec_with_msgs.sign");
+
+ let error_msg = "message validation error";
+ let always_fail_msg_validator = |_: &_| -> Result<()> { Err(anyhow!(error_msg)) };
+ let res = pool.add_executor_commitment(
+ &child_blk,
+ &nl,
+ ec_with_msgs,
+ &always_fail_msg_validator,
+ &chain_context,
+ );
+ assert!(res.is_err(), "add_executor_commitment");
+ assert_eq!(
+ res.err().unwrap().to_string(),
+ error_msg,
+ "add_executor_commitment",
+ );
+
+ // Adding a commitment should succeed.
+ let res = pool.add_executor_commitment(
+ &child_blk,
+ &nl,
+ ec.clone(),
+ &msg_validator,
+ &chain_context,
+ );
+ assert!(res.is_ok(), "add_executor_commitment");
+
+ // Adding a commitment twice for the same node should fail.
+ let res = pool.add_executor_commitment(
+ &child_blk,
+ &nl,
+ ec.clone(),
+ &msg_validator,
+ &chain_context,
+ );
+ assert!(res.is_err(), "add_executor_commitment, duplicate");
+
+ // There should be enough executor commitments and no discrepancy.
+ let res = pool.process_commitments(false);
+ assert!(res.is_ok(), "process_commitments");
+ let dd_ec = res
+ .unwrap()
+ .to_dd_result()
+ .downcast_ref::<ExecutorCommitment>();
+ assert_eq!(dd_ec, Some(&ec), "DD should return the correct commitment");
+ assert_eq!(false, pool.discrepancy);
+ }
+
+ fn generate_executor_commitment(
+ id: Namespace,
+ round: u64,
+ ) -> (Block, Block, ExecutorCommitment) {
+ let child_blk = Block::new_genesis_block(id, round);
+ let parent_blk = Block::new_empty_block(&child_blk, 1, HeaderType::Normal);
+
+ // TODO: Add tests with some emitted messages.
+ let msgs_hash = Message::messages_hash(&vec![]);
+ // TODO: Add tests with some incoming messages.
+ let in_msgs_hash = Message::in_messages_hash(&vec![]);
+
+ let ec = ExecutorCommitment {
+ header: ExecutorCommitmentHeader {
+ header: ComputeResultsHeader {
+ round: parent_blk.header.round,
+ previous_hash: parent_blk.header.previous_hash,
+ io_root: Some(parent_blk.header.io_root),
+ state_root: Some(parent_blk.header.state_root),
+ messages_hash: Some(msgs_hash),
+ in_msgs_hash: Some(in_msgs_hash),
+ in_msgs_count: 0,
+ },
+ failure: ExecutorCommitmentFailure::FailureNone,
+ rak_signature: None,
+ },
+ node_id: PublicKey::default(),
+ signature: Signature::default(),
+ messages: vec![],
+ };
+
+ (child_blk, parent_blk, ec)
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +
use anyhow::Result;
+
+use crate::{
+ common::{crypto::hash::Hash, quantity::Quantity, versioned::Versioned},
+ consensus::{address::Address, governance, registry, staking},
+};
+
+/// A message that can be emitted by the runtime to be processed by the consensus layer.
+#[derive(Clone, Debug, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub enum Message {
+ #[cbor(rename = "staking")]
+ Staking(Versioned<StakingMessage>),
+
+ #[cbor(rename = "registry")]
+ Registry(Versioned<RegistryMessage>),
+
+ #[cbor(rename = "governance")]
+ Governance(Versioned<GovernanceMessage>),
+}
+
+impl Message {
+ /// Returns a hash of provided runtime messages.
+ pub fn messages_hash(msgs: &[Message]) -> Hash {
+ if msgs.is_empty() {
+ // Special case if there are no messages.
+ return Hash::empty_hash();
+ }
+ Hash::digest_bytes(&cbor::to_vec(msgs.to_vec()))
+ }
+
+ /// Returns a hash of provided incoming runtime messages.
+ pub fn in_messages_hash(msgs: &[IncomingMessage]) -> Hash {
+ if msgs.is_empty() {
+ // Special case if there are no messages.
+ return Hash::empty_hash();
+ }
+ Hash::digest_bytes(&cbor::to_vec(msgs.to_vec()))
+ }
+
+ /// Performs basic validation of the runtime message.
+ pub fn validate_basic(&self) -> Result<()> {
+ match self {
+ Message::Staking(msg) => msg.inner.validate_basic(),
+ Message::Registry(msg) => msg.inner.validate_basic(),
+ Message::Governance(msg) => msg.inner.validate_basic(),
+ }
+ }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub enum StakingMessage {
+ #[cbor(rename = "transfer")]
+ Transfer(staking::Transfer),
+
+ #[cbor(rename = "withdraw")]
+ Withdraw(staking::Withdraw),
+
+ #[cbor(rename = "add_escrow")]
+ AddEscrow(staking::Escrow),
+
+ #[cbor(rename = "reclaim_escrow")]
+ ReclaimEscrow(staking::ReclaimEscrow),
+}
+
+impl StakingMessage {
+ /// Performs basic validation of the staking message.
+ pub fn validate_basic(&self) -> Result<()> {
+ match self {
+ StakingMessage::Transfer(_) => {
+ // No validation at this time.
+ Ok(())
+ }
+ StakingMessage::Withdraw(_) => {
+ // No validation at this time.
+ Ok(())
+ }
+ StakingMessage::AddEscrow(_) => {
+ // No validation at this time.
+ Ok(())
+ }
+ StakingMessage::ReclaimEscrow(_) => {
+ // No validation at this time.
+ Ok(())
+ }
+ }
+ }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub enum RegistryMessage {
+ #[cbor(rename = "update_runtime")]
+ UpdateRuntime(registry::Runtime),
+}
+
+impl RegistryMessage {
+ /// Performs basic validation of the registry message.
+ pub fn validate_basic(&self) -> Result<()> {
+ match self {
+ RegistryMessage::UpdateRuntime(_) => {
+ // The runtime descriptor will already be validated in registerRuntime
+ // in the registry app when it processes the message, so we don't have
+ // to do any validation here.
+ Ok(())
+ }
+ }
+ }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub enum GovernanceMessage {
+ #[cbor(rename = "cast_vote")]
+ CastVote(governance::ProposalVote),
+ #[cbor(rename = "submit_proposal")]
+ SubmitProposal(governance::ProposalContent),
+}
+
+impl GovernanceMessage {
+ /// Performs basic validation of the governance message.
+ pub fn validate_basic(&self) -> Result<()> {
+ match self {
+ GovernanceMessage::CastVote(_) => {
+ // No validation at this time.
+ Ok(())
+ }
+ GovernanceMessage::SubmitProposal(_) => {
+ // No validation at this time.
+ Ok(())
+ }
+ }
+ }
+}
+
+/// An incoming message emitted by the consensus layer to be processed by the runtime.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct IncomingMessage {
+ /// Unique identifier of the message.
+ pub id: u64,
+ /// Address of the caller authenticated by the consensus layer.
+ pub caller: Address,
+ /// An optional tag provided by the caller which is ignored and can be used to match processed
+ /// incoming message events later.
+ #[cbor(optional)]
+ pub tag: u64,
+ /// Fee sent into the runtime as part of the message being sent. The fee is transferred before
+ /// the message is processed by the runtime.
+ #[cbor(optional)]
+ pub fee: Quantity,
+ /// Tokens sent into the runtime as part of the message being sent. The tokens are transferred
+ /// before the message is processed by the runtime.
+ #[cbor(optional)]
+ pub tokens: Quantity,
+ /// Arbitrary runtime-dependent data.
+ #[cbor(optional)]
+ pub data: Vec<u8>,
+}
+
+impl IncomingMessage {
+ /// Returns a hash of provided runtime messages.
+ pub fn in_messages_hash(msgs: &[IncomingMessage]) -> Hash {
+ if msgs.is_empty() {
+ // Special case if there are no messages.
+ return Hash::empty_hash();
+ }
+ Hash::digest_bytes(&cbor::to_vec(msgs.to_vec()))
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use std::collections::BTreeMap;
+
+ use crate::{
+ common::{crypto::signature::PublicKey, namespace::Namespace, quantity},
+ consensus::scheduler,
+ };
+
+ use super::*;
+
+ #[test]
+ fn test_consistent_messages_hash() {
+ // NOTE: This runtime structure must be synced with go/roothash/api/messages_test.go.
+ let test_ent_id =
+ PublicKey::from("4ea5328f943ef6f66daaed74cb0e99c3b1c45f76307b425003dbc7cb3638ed35");
+
+ let q = quantity::Quantity::from(1000u32);
+
+ let mut st = BTreeMap::new();
+ st.insert(staking::ThresholdKind::KindNodeCompute, q.clone());
+
+ let mut wlc = BTreeMap::new();
+ wlc.insert(registry::RolesMask::ROLE_COMPUTE_WORKER, 2);
+
+ let mut wl = BTreeMap::new();
+ wl.insert(
+ test_ent_id,
+ registry::EntityWhitelistConfig { max_nodes: wlc },
+ );
+
+ let rt = registry::Runtime {
+ v: registry::LATEST_RUNTIME_DESCRIPTOR_VERSION,
+ id: Namespace::default(),
+ entity_id: test_ent_id,
+ genesis: registry::RuntimeGenesis {
+ state_root: Hash::empty_hash(),
+ round: 0,
+ },
+ kind: registry::RuntimeKind::KindCompute,
+ tee_hardware: registry::TEEHardware::TEEHardwareInvalid,
+ deployments: vec![registry::VersionInfo::default()],
+ key_manager: None,
+ executor: registry::ExecutorParameters {
+ group_size: 3,
+ group_backup_size: 5,
+ allowed_stragglers: 1,
+ round_timeout: 10,
+ max_messages: 32,
+ ..Default::default()
+ },
+ txn_scheduler: registry::TxnSchedulerParameters {
+ batch_flush_timeout: 1_000_000_000, // 1 second.
+ max_batch_size: 1,
+ max_batch_size_bytes: 1024,
+ max_in_messages: 0,
+ propose_batch_timeout: 2_000_000_000, // 2 seconds.
+ },
+ storage: registry::StorageParameters {
+ checkpoint_interval: 0,
+ checkpoint_num_kept: 0,
+ checkpoint_chunk_size: 0,
+ },
+ admission_policy: registry::RuntimeAdmissionPolicy {
+ entity_whitelist: Some(registry::EntityWhitelistRuntimeAdmissionPolicy {
+ entities: wl,
+ }),
+ ..Default::default()
+ },
+ constraints: {
+ let mut cs = BTreeMap::new();
+ cs.insert(scheduler::CommitteeKind::ComputeExecutor, {
+ let mut ce = BTreeMap::new();
+ ce.insert(
+ scheduler::Role::Worker,
+ registry::SchedulingConstraints {
+ min_pool_size: Some(registry::MinPoolSizeConstraint { limit: 1 }),
+ validator_set: Some(registry::ValidatorSetConstraint {}),
+ ..Default::default()
+ },
+ );
+ ce.insert(
+ scheduler::Role::BackupWorker,
+ registry::SchedulingConstraints {
+ min_pool_size: Some(registry::MinPoolSizeConstraint { limit: 2 }),
+ ..Default::default()
+ },
+ );
+ ce
+ });
+
+ cs
+ },
+ staking: registry::RuntimeStakingParameters {
+ thresholds: st,
+ ..Default::default()
+ },
+ governance_model: registry::RuntimeGovernanceModel::GovernanceEntity,
+ };
+
+ // NOTE: These hashes MUST be synced with go/roothash/api/message/message_test.go.
+ let tcs = vec![
+ (
+ vec![],
+ "c672b8d1ef56ed28ab87c3622c5114069bdd3ad7b8f9737498d0c01ecef0967a",
+ ),
+ (
+ vec![Message::Staking(Versioned::new(
+ 0,
+ StakingMessage::Transfer(staking::Transfer::default()),
+ ))],
+ "a6b91f974b34a9192efd12025659a768520d2f04e1dae9839677456412cdb2be",
+ ),
+ (
+ vec![Message::Staking(Versioned::new(
+ 0,
+ StakingMessage::Withdraw(staking::Withdraw::default()),
+ ))],
+ "069b0fda76d804e3fd65d4bbd875c646f15798fb573ac613100df67f5ba4c3fd",
+ ),
+ (
+ vec![Message::Staking(Versioned::new(
+ 0,
+ StakingMessage::AddEscrow(staking::Escrow::default()),
+ ))],
+ "65049870b9dae657390e44065df0c78176816876e67b96dac7791ee6a1aa42e2",
+ ),
+ (
+ vec![Message::Staking(Versioned::new(
+ 0,
+ StakingMessage::ReclaimEscrow(staking::ReclaimEscrow::default()),
+ ))],
+ "c78547eae2f104268e49827cbe624cf2b350ee59e8d693dec0673a70a4664a2e",
+ ),
+ (
+ vec![Message::Registry(Versioned::new(
+ 0,
+ RegistryMessage::UpdateRuntime(registry::Runtime {
+ admission_policy: registry::RuntimeAdmissionPolicy {
+ any_node: Some(registry::AnyNodeRuntimeAdmissionPolicy {}),
+ ..Default::default()
+ },
+ ..Default::default()
+ }),
+ ))],
+ // FIXME: Change to e6e170fb771583147255e0c96dc88615d4fd2fd28488ae489df01da201affe72 once cbor is fixed.
+ "baf9eeaa4860e363a9c27d99555839afc535f0cd32d23dc640f0f020677460e0",
+ ),
+ (
+ vec![Message::Registry(Versioned::new(
+ 0,
+ RegistryMessage::UpdateRuntime(rt),
+ ))],
+ "03e77fbeda1a2291c87c06c59335a49fe18852266d58608c1ddec8ef64209458",
+ ),
+ (
+ vec![Message::Governance(Versioned::new(
+ 0,
+ GovernanceMessage::CastVote(governance::ProposalVote {
+ id: 32,
+ vote: governance::Vote::Yes,
+ }),
+ ))],
+ "f45e26eb8ace807ad5bd02966cde1f012d1d978d4cbddd59e9bfd742dcf39b90",
+ ),
+ (
+ vec![Message::Governance(Versioned::new(
+ 0,
+ GovernanceMessage::SubmitProposal(governance::ProposalContent {
+ cancel_upgrade: Some(governance::CancelUpgradeProposal { proposal_id: 32 }),
+ ..Default::default()
+ }),
+ ))],
+ "03312ddb5c41a30fbd29fb91cf6bf26d58073996f89657ca4f3b3a43a98bfd0b",
+ ),
+ ];
+ for (msgs, expected_hash) in tcs {
+ println!("{:?}", cbor::to_vec(msgs.clone()));
+ assert_eq!(Message::messages_hash(&msgs), Hash::from(expected_hash));
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +
//! Consensus roothash structures.
+//!
+//! # Note
+//!
+//! This **MUST** be kept in sync with go/roothash/api.
+//!
+use thiserror::Error;
+
+use crate::{
+ common::{
+ crypto::{hash::Hash, signature::PublicKey},
+ namespace::Namespace,
+ },
+ consensus::state::StateError,
+};
+
+// Modules.
+mod block;
+mod commitment;
+mod message;
+
+// Re-exports.
+pub use block::*;
+pub use commitment::*;
+pub use message::*;
+
+/// Errors emitted by the roothash module.
+#[derive(Debug, Error)]
+pub enum Error {
+ #[error("roothash: invalid runtime {0}")]
+ InvalidRuntime(Namespace),
+
+ #[error(transparent)]
+ State(#[from] StateError),
+
+ #[error("roothash/commitment: no runtime configured")]
+ NoRuntime,
+
+ #[error("roothash/commitment: no committee configured")]
+ NoCommittee,
+
+ #[error("roothash/commitment: invalid committee kind")]
+ InvalidCommitteeKind,
+
+ #[error("roothash/commitment: batch RAK signature invalid")]
+ RakSigInvalid,
+
+ #[error("roothash/commitment: node not part of committee")]
+ NotInCommittee,
+
+ #[error("roothash/commitment: node already sent commitment")]
+ AlreadyCommitted,
+
+ #[error("roothash/commitment: submitted commitment is not based on correct block")]
+ NotBasedOnCorrectBlock,
+
+ #[error("roothash/commitment: discrepancy detected")]
+ DiscrepancyDetected,
+
+ #[error("roothash/commitment: still waiting for commits")]
+ StillWaiting,
+
+ #[error("roothash/commitment: insufficient votes to finalize discrepancy resolution round")]
+ InsufficientVotes,
+
+ #[error("roothash/commitment: bad executor commitment")]
+ BadExecutorCommitment,
+
+ #[error("roothash/commitment: invalid messages")]
+ InvalidMessages,
+
+ #[error("roothash/commitment: invalid round")]
+ InvalidRound,
+
+ #[error("roothash/commitment: no proposer commitment")]
+ NoProposerCommitment,
+
+ #[error("roothash/commitment: bad proposer commitment")]
+ BadProposerCommitment,
+}
+
+/// Runtime block annotated with consensus information.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct AnnotatedBlock {
+ /// Consensus height at which this runtime block was produced.
+ pub consensus_height: i64,
+ /// Runtime block.
+ pub block: Block,
+}
+
+/// Result of a message being processed by the consensus layer.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct MessageEvent {
+ #[cbor(optional)]
+ pub module: String,
+
+ #[cbor(optional)]
+ pub code: u32,
+
+ #[cbor(optional)]
+ pub index: u32,
+
+ #[cbor(optional)]
+ pub result: Option<cbor::Value>,
+}
+
+impl MessageEvent {
+ /// Returns true if the event indicates that the message was successfully processed.
+ pub fn is_success(&self) -> bool {
+ self.code == 0
+ }
+}
+
+/// Information about how a particular round was executed by the consensus layer.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct RoundResults {
+ /// Results of executing emitted runtime messages.
+ #[cbor(optional)]
+ pub messages: Vec<MessageEvent>,
+
+ /// Public keys of compute nodes' controlling entities that positively contributed to the round
+ /// by replicating the computation correctly.
+ #[cbor(optional)]
+ pub good_compute_entities: Vec<PublicKey>,
+ /// Public keys of compute nodes' controlling entities that negatively contributed to the round
+ /// by causing discrepancies.
+ #[cbor(optional)]
+ pub bad_compute_entities: Vec<PublicKey>,
+}
+
+/// Per-round state and I/O roots that are stored in consensus state.
+#[derive(Clone, Debug, Default, Eq, PartialEq, Hash, cbor::Encode, cbor::Decode)]
+#[cbor(as_array)]
+pub struct RoundRoots {
+ pub state_root: Hash,
+ pub io_root: Hash,
+}
+
+#[cfg(test)]
+mod tests {
+ use base64::prelude::*;
+
+ use super::*;
+
+ #[test]
+ fn test_consistent_round_results() {
+ let tcs = vec![
+ ("oA==", RoundResults::default()),
+ ("oWhtZXNzYWdlc4GiZGNvZGUBZm1vZHVsZWR0ZXN0", RoundResults {
+ messages: vec![MessageEvent{module: "test".to_owned(), code: 1, index: 0, result: None}],
+ ..Default::default()
+ }),
+ ("omhtZXNzYWdlc4GkZGNvZGUYKmVpbmRleAFmbW9kdWxlZHRlc3RmcmVzdWx0a3Rlc3QtcmVzdWx0dWdvb2RfY29tcHV0ZV9lbnRpdGllc4NYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAVggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAI=",
+ RoundResults {
+ messages: vec![MessageEvent{module: "test".to_owned(), code: 42, index: 1, result: Some(cbor::Value::TextString("test-result".to_string()))}],
+ good_compute_entities: vec![
+ "0000000000000000000000000000000000000000000000000000000000000000".into(),
+ "0000000000000000000000000000000000000000000000000000000000000001".into(),
+ "0000000000000000000000000000000000000000000000000000000000000002".into(),
+ ],
+ ..Default::default()
+ }),
+ ("o2htZXNzYWdlc4GkZGNvZGUYKmVpbmRleAFmbW9kdWxlZHRlc3RmcmVzdWx0a3Rlc3QtcmVzdWx0dGJhZF9jb21wdXRlX2VudGl0aWVzgVggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAF1Z29vZF9jb21wdXRlX2VudGl0aWVzglggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAC",
+ RoundResults {
+ messages: vec![MessageEvent{module: "test".to_owned(), code: 42, index: 1, result: Some(cbor::Value::TextString("test-result".to_string()))}],
+ good_compute_entities: vec![
+ "0000000000000000000000000000000000000000000000000000000000000000".into(),
+ "0000000000000000000000000000000000000000000000000000000000000002".into(),
+ ],
+ bad_compute_entities: vec![
+ "0000000000000000000000000000000000000000000000000000000000000001".into(),
+ ],
+ }),
+ ];
+ for (encoded_base64, rr) in tcs {
+ let dec: RoundResults =
+ cbor::from_slice(&BASE64_STANDARD.decode(encoded_base64).unwrap())
+ .expect("round results should deserialize correctly");
+ assert_eq!(dec, rr, "decoded results should match the expected value");
+ }
+ }
+
+ #[test]
+ fn test_consistent_round_roots() {
+ let tcs = vec![
+ ("glggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABYIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", RoundRoots::default()),
+ ("glggPTf+WENeDYcyPe5KLBsznvlU3mNxbuefV0f5TZdPkT9YIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", RoundRoots {
+ state_root: Hash::digest_bytes(b"test"),
+ ..Default::default()
+ }),
+ ("glggAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABYID03/lhDXg2HMj3uSiwbM575VN5jcW7nn1dH+U2XT5E/", RoundRoots {
+ io_root: Hash::digest_bytes(b"test"),
+ ..Default::default()
+ }),
+ ("glggPTf+WENeDYcyPe5KLBsznvlU3mNxbuefV0f5TZdPkT9YID03/lhDXg2HMj3uSiwbM575VN5jcW7nn1dH+U2XT5E/",
+ RoundRoots {
+ state_root: Hash::digest_bytes(b"test"),
+ io_root: Hash::digest_bytes(b"test"),
+ }),
+ ("glggC4+lzfqNgLxCHLxwDp+Bf5PLLb0DILrUZWwF+lp6Z/NYIJ3seczGUDFDvmAEdVCeep6Xsn8XRosTKWpu9wZ3mQRq",
+ RoundRoots {
+ state_root: Hash::digest_bytes(b"test1"),
+ io_root: Hash::digest_bytes(b"test2"),
+ }),
+ ("glggnex5zMZQMUO+YAR1UJ56npeyfxdGixMpam73BneZBGpYIAuPpc36jYC8Qhy8cA6fgX+Tyy29AyC61GVsBfpaemfz",
+ RoundRoots {
+ state_root: Hash::digest_bytes(b"test2"),
+ io_root: Hash::digest_bytes(b"test1"),
+ }),
+ ];
+
+ for (encoded_base64, rr) in tcs {
+ let dec: RoundRoots =
+ cbor::from_slice(&BASE64_STANDARD.decode(encoded_base64).unwrap())
+ .expect("round roots should deserialize correctly");
+ assert_eq!(
+ dec, rr,
+ "decoded round roots should match the expected value"
+ );
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +
//! Scheduler structures.
+use anyhow::{anyhow, Result};
+
+use crate::{
+ common::{crypto::signature::PublicKey, namespace::Namespace},
+ consensus::beacon::EpochTime,
+};
+
+/// The role a given node plays in a committee.
+#[derive(
+ Clone, Debug, Default, PartialEq, Eq, Hash, PartialOrd, Ord, cbor::Encode, cbor::Decode,
+)]
+#[repr(u8)]
+pub enum Role {
+ /// An invalid role (should never appear on the wire).
+ #[default]
+ Invalid = 0,
+ /// Indicates the node is a worker.
+ Worker = 1,
+ /// Indicates the node is a backup worker.
+ BackupWorker = 2,
+}
+
+/// A node participating in a committee.
+pub struct CommitteeNode {
+ /// The node's role in a committee.
+ pub role: Role,
+
+ /// The node's public key.
+ pub public_key: PublicKey,
+}
+
+/// The functionality a committee exists to provide.
+#[derive(
+ Clone, Debug, Default, PartialEq, Eq, Hash, PartialOrd, Ord, cbor::Encode, cbor::Decode,
+)]
+#[repr(u8)]
+pub enum CommitteeKind {
+ /// An invalid committee (should never appear on the wire).
+ #[default]
+ Invalid = 0,
+ /// A compute executor committee.
+ ComputeExecutor = 1,
+}
+
+/// A per-runtime (instance) committee.
+pub struct Committee {
+ /// The functionality a committee exists to provide.
+ pub kind: CommitteeKind,
+
+ /// The committee members.
+ pub members: Vec<CommitteeNode>,
+
+ /// The runtime ID that this committee is for.
+ pub runtime_id: Namespace,
+
+ /// The epoch for which the committee is valid.
+ pub valid_for: EpochTime,
+}
+
+impl Committee {
+ /// Returns committee nodes with Worker role.
+ pub fn workers(&self) -> Vec<&CommitteeNode> {
+ self.members
+ .iter()
+ .filter(|&member| member.role == Role::Worker)
+ .collect()
+ }
+
+ /// Returns the transaction scheduler of the provided committee based on the provided round.
+ pub fn transaction_scheduler(&self, round: u64) -> Result<&CommitteeNode> {
+ let workers = self.workers();
+ if workers.is_empty() {
+ return Err(anyhow!("GetTransactionScheduler: no workers in committee"));
+ }
+ let scheduler_idx = round as usize % workers.len();
+ let scheduler = workers[scheduler_idx];
+
+ Ok(scheduler)
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +
//! Consensus staking structures.
+//!
+//! # Note
+//!
+//! This **MUST** be kept in sync with go/staking/api.
+//!
+use std::collections::BTreeMap;
+
+use crate::{
+ common::{crypto::hash::Hash, quantity::Quantity},
+ consensus::{address::Address, beacon::EpochTime},
+};
+
+/// A stake transfer.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct Transfer {
+ pub to: Address,
+ pub amount: Quantity,
+}
+
+/// A withdrawal from an account.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct Withdraw {
+ pub from: Address,
+ pub amount: Quantity,
+}
+
+/// A stake escrow.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct Escrow {
+ pub account: Address,
+ pub amount: Quantity,
+}
+
+/// A reclaim escrow.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct ReclaimEscrow {
+ pub account: Address,
+ pub shares: Quantity,
+}
+
+/// Kind of staking threshold.
+#[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, cbor::Encode, cbor::Decode)]
+#[repr(i32)]
+pub enum ThresholdKind {
+ /// Entity staking threshold.
+ KindEntity = 0,
+ /// Validator node staking threshold.
+ KindNodeValidator = 1,
+ /// Compute node staking threshold.
+ KindNodeCompute = 2,
+ /// Keymanager node staking threshold.
+ KindNodeKeyManager = 4,
+ /// Compute runtime staking threshold.
+ KindRuntimeCompute = 5,
+ /// Keymanager runtime staking threshold.
+ KindRuntimeKeyManager = 6,
+}
+
+/// Entry in the staking ledger.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct Account {
+ #[cbor(optional)]
+ pub general: GeneralAccount,
+
+ #[cbor(optional)]
+ pub escrow: EscrowAccount,
+}
+
+/// General purpose account.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct GeneralAccount {
+ #[cbor(optional)]
+ pub balance: Quantity,
+
+ #[cbor(optional)]
+ pub nonce: u64,
+
+ #[cbor(optional)]
+ pub allowances: BTreeMap<Address, Quantity>,
+}
+
+/// Escrow account.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct EscrowAccount {
+ #[cbor(optional)]
+ pub active: SharePool,
+
+ #[cbor(optional)]
+ pub debonding: SharePool,
+
+ #[cbor(optional)]
+ pub commission_schedule: CommissionSchedule,
+
+ #[cbor(optional)]
+ pub stake_accumulator: StakeAccumulator,
+}
+
+/// Combined balance of serval entries, the relative sizes of which are tracked through shares.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct SharePool {
+ #[cbor(optional)]
+ pub balance: Quantity,
+
+ #[cbor(optional)]
+ pub total_shares: Quantity,
+}
+
+/// Defines a list of commission rates and commission rate bounds with their starting times.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct CommissionSchedule {
+ #[cbor(optional)]
+ pub rates: Vec<CommissionRateStep>,
+
+ #[cbor(optional)]
+ pub bounds: Vec<CommissionRateBoundStep>,
+}
+
+/// Commission rate and its starting time.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct CommissionRateStep {
+ pub start: EpochTime,
+ pub rate: Quantity,
+}
+
+/// Commission rate bound and its starting time.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct CommissionRateBoundStep {
+ #[cbor(optional)]
+ pub start: EpochTime,
+
+ #[cbor(optional)]
+ pub rate_min: Quantity,
+
+ #[cbor(optional)]
+ pub rate_max: Quantity,
+}
+
+/// Per escrow account stake accumulator.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct StakeAccumulator {
+ #[cbor(optional)]
+ pub claims: BTreeMap<StakeClaim, Vec<StakeThreshold>>,
+}
+
+/// Unique stake claim identifier.
+pub type StakeClaim = String;
+
+/// Stake threshold used in the stake accumulator.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct StakeThreshold {
+ #[cbor(optional)]
+ pub global: Option<ThresholdKind>,
+
+ #[cbor(optional, rename = "const")]
+ pub constant: Option<Quantity>,
+}
+
+/// Delegation descriptor.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct Delegation {
+ pub shares: Quantity,
+}
+
+/// Debonding delegation descriptor.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct DebondingDelegation {
+ pub shares: Quantity,
+
+ #[cbor(rename = "debond_end")]
+ pub debond_end_time: EpochTime,
+}
+
+/// Reason for slashing an entity.
+#[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, cbor::Encode, cbor::Decode)]
+#[repr(u8)]
+pub enum SlashReason {
+ /// Slashing due to submission of incorrect results in runtime executor commitments.
+ RuntimeIncorrectResults = 0x80,
+ /// Slashing due to signing two different executor commits or proposed batches for the same
+ /// round.
+ RuntimeEquivocation = 0x81,
+ /// Slashing due to not doing the required work.
+ RuntimeLiveness = 0x82,
+}
+
+/// Per-reason slashing configuration.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct Slash {
+ pub amount: Quantity,
+ pub freeze_interval: EpochTime,
+}
+
+/// Transfer result.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct TransferResult {
+ pub from: Address,
+ pub to: Address,
+ pub amount: Quantity,
+}
+
+/// Add escrow result.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct AddEscrowResult {
+ pub owner: Address,
+ pub escrow: Address,
+ pub amount: Quantity,
+ pub new_shares: Quantity,
+}
+
+/// Reclaim escrow result.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct ReclaimEscrowResult {
+ pub owner: Address,
+ pub escrow: Address,
+ pub amount: Quantity,
+ pub remaining_shares: Quantity,
+ pub debonding_shares: Quantity,
+ pub debond_end_time: EpochTime,
+}
+
+/// Withdraw result.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct WithdrawResult {
+ pub owner: Address,
+ pub beneficiary: Address,
+ pub allowance: Quantity,
+ pub amount_change: Quantity,
+}
+
+/// A staking-related event.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct Event {
+ #[cbor(optional)]
+ pub height: i64,
+ #[cbor(optional)]
+ pub tx_hash: Hash,
+
+ // TODO: Consider refactoring this to be an enum.
+ #[cbor(optional)]
+ pub transfer: Option<TransferEvent>,
+ #[cbor(optional)]
+ pub burn: Option<BurnEvent>,
+ #[cbor(optional)]
+ pub escrow: Option<EscrowEvent>,
+ #[cbor(optional)]
+ pub allowance_change: Option<AllowanceChangeEvent>,
+}
+
+/// Event emitted when stake is transferred, either by a call to Transfer or Withdraw.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct TransferEvent {
+ pub from: Address,
+ pub to: Address,
+ pub amount: Quantity,
+}
+
+/// Event emitted when stake is destroyed via a call to Burn.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct BurnEvent {
+ pub owner: Address,
+ pub amount: Quantity,
+}
+
+/// Escrow-related events.
+#[derive(Clone, Debug, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub enum EscrowEvent {
+ /// Event emitted when stake is transferred into an escrow account.
+ #[cbor(rename = "add")]
+ Add {
+ owner: Address,
+ escrow: Address,
+ amount: Quantity,
+ new_shares: Quantity,
+ },
+
+ /// Event emitted when stake is taken from an escrow account (i.e. stake is slashed).
+ #[cbor(rename = "take")]
+ Take {
+ owner: Address,
+ // The sum of amounts slashed from active and debonding escrow balances.
+ amount: Quantity,
+ // The amount slashed from the debonding escrow balance.
+ debonding_amount: Quantity,
+ },
+
+ /// Event emitted when the debonding process has started and the given number of active shares
+ /// have been moved into the debonding pool and started debonding.
+ ///
+ /// Note that the given amount is valid at the time of debonding start and may not correspond to
+ /// the final debonded amount in case any escrowed stake is subject to slashing.
+ #[cbor(rename = "debonding_start")]
+ DebondingStart {
+ owner: Address,
+ escrow: Address,
+ amount: Quantity,
+ active_shares: Quantity,
+ debonding_shares: Quantity,
+ debond_end_time: EpochTime,
+ },
+
+ /// Event emitted when stake is reclaimed from an escrow account back into owner's general
+ /// account.
+ #[cbor(rename = "reclaim")]
+ Reclaim {
+ owner: Address,
+ escrow: Address,
+ amount: Quantity,
+ shares: Quantity,
+ },
+}
+
+/// Event emitted when allowance is changed for a beneficiary.
+#[derive(Clone, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+pub struct AllowanceChangeEvent {
+ pub owner: Address,
+ pub beneficiary: Address,
+ pub allowance: Quantity,
+ #[cbor(optional)]
+ pub negative: bool,
+ pub amount_change: Quantity,
+}
+
+#[cfg(test)]
+mod tests {
+ use base64::prelude::*;
+
+ use super::*;
+ use crate::{
+ common::crypto::signature::PublicKey,
+ consensus::address::{COMMON_POOL_ADDRESS, GOVERNANCE_DEPOSITS_ADDRESS},
+ };
+
+ #[test]
+ fn test_consistent_accounts() {
+ let tcs = vec![
+ ("oA==", Account::default()),
+ (
+ "oWdnZW5lcmFsomVub25jZRghZ2JhbGFuY2VBCg==",
+ Account {
+ general: GeneralAccount {
+ balance: Quantity::from(10u32),
+ nonce: 33,
+ ..Default::default()
+ },
+ ..Default::default()
+ },
+ ),
+ (
+ "oWdnZW5lcmFsoWphbGxvd2FuY2VzolUAdU/0RxQ6XsX0cbMPhna5TVaxV1BBIVUA98Te1iET4sKC6oZyI6VE7VXWum5BZA==",
+ {
+ Account {
+ general: GeneralAccount {
+ allowances: [
+ (COMMON_POOL_ADDRESS.clone(), Quantity::from(100u32)),
+ (GOVERNANCE_DEPOSITS_ADDRESS.clone(), Quantity::from(33u32))
+ ].iter().cloned().collect(),
+ ..Default::default()
+ },
+ ..Default::default()
+ }
+ },
+ ),
+ (
+ "oWZlc2Nyb3ejZmFjdGl2ZaJnYmFsYW5jZUIETGx0b3RhbF9zaGFyZXNBC3FzdGFrZV9hY2N1bXVsYXRvcqFmY2xhaW1zoWZlbnRpdHmCoWVjb25zdEFNoWZnbG9iYWwCc2NvbW1pc3Npb25fc2NoZWR1bGWhZmJvdW5kc4GjZXN0YXJ0GCFocmF0ZV9tYXhCA+hocmF0ZV9taW5BCg==",
+ Account {
+ escrow: EscrowAccount {
+ active: SharePool{
+ balance: Quantity::from(1100u32),
+ total_shares: Quantity::from(11u32),
+ },
+ debonding: SharePool::default(),
+ commission_schedule: CommissionSchedule {
+ bounds: vec![CommissionRateBoundStep{
+ start: 33,
+ rate_min: Quantity::from(10u32),
+ rate_max: Quantity::from(1000u32),
+ }],
+ ..Default::default()
+ },
+ stake_accumulator: StakeAccumulator {
+ claims: [
+ (
+ "entity".to_string(),
+ vec![
+ StakeThreshold{
+ constant: Some(Quantity::from(77u32)),
+ ..Default::default()
+ },
+ StakeThreshold{
+ global: Some(ThresholdKind::KindNodeCompute),
+ ..Default::default()
+ },
+ ]
+ )
+ ].iter().cloned().collect()
+ }
+ },
+ ..Default::default()
+ },
+ )
+ ];
+ for (encoded_base64, rr) in tcs {
+ let dec: Account = cbor::from_slice(&BASE64_STANDARD.decode(encoded_base64).unwrap())
+ .expect("account should deserialize correctly");
+ assert_eq!(dec, rr, "decoded account should match the expected value");
+ }
+ }
+
+ #[test]
+ fn test_consistent_delegations() {
+ let tcs = vec![
+ ("oWZzaGFyZXNA", Delegation::default()),
+ (
+ "oWZzaGFyZXNBZA==",
+ Delegation {
+ shares: Quantity::from(100u32),
+ },
+ ),
+ ];
+ for (encoded_base64, rr) in tcs {
+ let dec: Delegation =
+ cbor::from_slice(&BASE64_STANDARD.decode(encoded_base64).unwrap())
+ .expect("delegation should deserialize correctly");
+ assert_eq!(dec, rr, "decoded account should match the expected value");
+ }
+ }
+
+ #[test]
+ fn test_consistent_debonding_delegations() {
+ let tcs = vec![
+ (
+ "omZzaGFyZXNAamRlYm9uZF9lbmQA",
+ DebondingDelegation::default(),
+ ),
+ (
+ "omZzaGFyZXNBZGpkZWJvbmRfZW5kFw==",
+ DebondingDelegation {
+ shares: Quantity::from(100u32),
+ debond_end_time: 23,
+ },
+ ),
+ ];
+ for (encoded_base64, rr) in tcs {
+ let dec: DebondingDelegation =
+ cbor::from_slice(&BASE64_STANDARD.decode(encoded_base64).unwrap())
+ .expect("debonding delegation should deserialize correctly");
+ assert_eq!(dec, rr, "decoded account should match the expected value");
+ }
+ }
+
+ #[test]
+ fn test_consistent_transfer_results() {
+ let addr1 = Address::from_pk(&PublicKey::from(
+ "aaafffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+ ));
+ let addr2 = Address::from_pk(&PublicKey::from(
+ "bbbfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+ ));
+
+ let tcs = vec![
+ ("o2J0b1UAAAAAAAAAAAAAAAAAAAAAAAAAAABkZnJvbVUAAAAAAAAAAAAAAAAAAAAAAAAAAABmYW1vdW50QA==", TransferResult::default()),
+ (
+ "o2J0b1UAuRI5eJXmRwxR+r7MndyD9wrthqFkZnJvbVUAIHIUNIk/YWwJgUjiz5+Z4+KCbhNmYW1vdW50QWQ=",
+ TransferResult {
+ amount: Quantity::from(100u32),
+ from: addr1,
+ to: addr2,
+ },
+ ),
+ ];
+ for (encoded_base64, rr) in tcs {
+ let dec: TransferResult =
+ cbor::from_slice(&BASE64_STANDARD.decode(encoded_base64).unwrap())
+ .expect("transfer result should deserialize correctly");
+ assert_eq!(dec, rr, "decoded result should match the expected value");
+ }
+ }
+
+ #[test]
+ fn test_consistent_withdraw_results() {
+ let addr1 = Address::from_pk(&PublicKey::from(
+ "aaafffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+ ));
+ let addr2 = Address::from_pk(&PublicKey::from(
+ "bbbfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+ ));
+
+ let tcs = vec![
+ ("pGVvd25lclUAAAAAAAAAAAAAAAAAAAAAAAAAAABpYWxsb3dhbmNlQGtiZW5lZmljaWFyeVUAAAAAAAAAAAAAAAAAAAAAAAAAAABtYW1vdW50X2NoYW5nZUA=", WithdrawResult::default()),
+ (
+ "pGVvd25lclUAIHIUNIk/YWwJgUjiz5+Z4+KCbhNpYWxsb3dhbmNlQQprYmVuZWZpY2lhcnlVALkSOXiV5kcMUfq+zJ3cg/cK7YahbWFtb3VudF9jaGFuZ2VBBQ==",
+ WithdrawResult {
+ owner: addr1,
+ beneficiary: addr2,
+ allowance: Quantity::from(10u32),
+ amount_change: Quantity::from(5u32),
+ },
+ ),
+ ];
+ for (encoded_base64, rr) in tcs {
+ let dec: WithdrawResult =
+ cbor::from_slice(&BASE64_STANDARD.decode(encoded_base64).unwrap())
+ .expect("withdraw result should deserialize correctly");
+ assert_eq!(dec, rr, "decoded result should match the expected value");
+ }
+ }
+
+ #[test]
+ fn test_consistent_add_escrow_results() {
+ let addr1 = Address::from_pk(&PublicKey::from(
+ "aaafffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+ ));
+ let addr2 = Address::from_pk(&PublicKey::from(
+ "bbbfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+ ));
+
+ let tcs = vec![
+ ("pGVvd25lclUAAAAAAAAAAAAAAAAAAAAAAAAAAABmYW1vdW50QGZlc2Nyb3dVAAAAAAAAAAAAAAAAAAAAAAAAAAAAam5ld19zaGFyZXNA", AddEscrowResult::default()),
+ (
+ "pGVvd25lclUAIHIUNIk/YWwJgUjiz5+Z4+KCbhNmYW1vdW50QWRmZXNjcm93VQC5Ejl4leZHDFH6vsyd3IP3Cu2GoWpuZXdfc2hhcmVzQQU=",
+ AddEscrowResult {
+ owner: addr1,
+ escrow: addr2,
+ amount: Quantity::from(100u32),
+ new_shares: Quantity::from(5u32),
+ },
+ ),
+ ];
+ for (encoded_base64, rr) in tcs {
+ let dec: AddEscrowResult =
+ cbor::from_slice(&BASE64_STANDARD.decode(encoded_base64).unwrap())
+ .expect("add escrow result should deserialize correctly");
+ assert_eq!(dec, rr, "decoded result should match the expected value");
+ }
+ }
+
+ #[test]
+ fn test_consistent_reclaim_escrow_results() {
+ let addr1 = Address::from_pk(&PublicKey::from(
+ "aaafffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+ ));
+ let addr2 = Address::from_pk(&PublicKey::from(
+ "bbbfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+ ));
+
+ let tcs = vec![
+ ("pmVvd25lclUAAAAAAAAAAAAAAAAAAAAAAAAAAABmYW1vdW50QGZlc2Nyb3dVAAAAAAAAAAAAAAAAAAAAAAAAAAAAb2RlYm9uZF9lbmRfdGltZQBwZGVib25kaW5nX3NoYXJlc0BwcmVtYWluaW5nX3NoYXJlc0A=", ReclaimEscrowResult::default()),
+ (
+ "pmVvd25lclUAIHIUNIk/YWwJgUjiz5+Z4+KCbhNmYW1vdW50QWRmZXNjcm93VQC5Ejl4leZHDFH6vsyd3IP3Cu2GoW9kZWJvbmRfZW5kX3RpbWUYKnBkZWJvbmRpbmdfc2hhcmVzQRlwcmVtYWluaW5nX3NoYXJlc0Ey",
+ ReclaimEscrowResult {
+ owner: addr1,
+ escrow: addr2,
+ amount: Quantity::from(100u32),
+ remaining_shares: Quantity::from(50u32),
+ debonding_shares: Quantity::from(25u32),
+ debond_end_time: 42,
+ },
+ ),
+ ];
+ for (encoded_base64, rr) in tcs {
+ let dec: ReclaimEscrowResult =
+ cbor::from_slice(&BASE64_STANDARD.decode(encoded_base64).unwrap())
+ .expect("reclaim escrow result should deserialize correctly");
+ assert_eq!(dec, rr, "decoded result should match the expected value");
+ }
+ }
+
+ #[test]
+ fn test_consistent_events() {
+ let addr1 = Address::from_pk(&PublicKey::from(
+ "aaafffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+ ));
+ let addr2 = Address::from_pk(&PublicKey::from(
+ "bbbfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+ ));
+ let tx_hash = Hash::empty_hash();
+
+ let tcs = vec![
+ (
+ "oWd0eF9oYXNoWCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+ Event::default(),
+ ),
+ (
+ "omZoZWlnaHQYKmd0eF9oYXNoWCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+ Event {
+ height: 42,
+ ..Default::default()
+ },
+ ),
+ (
+ "omZoZWlnaHQYKmd0eF9oYXNoWCDGcrjR71btKKuHw2IsURQGm90617j5c3SY0MAezvCWeg==",
+ Event {
+ height: 42,
+ tx_hash,
+ ..Default::default()
+ },
+ ),
+
+ // Transfer.
+ (
+ "o2ZoZWlnaHQYKmd0eF9oYXNoWCDGcrjR71btKKuHw2IsURQGm90617j5c3SY0MAezvCWemh0cmFuc2ZlcqNidG9VALkSOXiV5kcMUfq+zJ3cg/cK7YahZGZyb21VACByFDSJP2FsCYFI4s+fmePigm4TZmFtb3VudEFk",
+ Event {
+ height: 42,
+ tx_hash,
+ transfer: Some(TransferEvent {
+ from: addr1.clone(),
+ to: addr2.clone(),
+ amount: 100u32.into(),
+ }),
+ ..Default::default()
+ },
+ ),
+
+ // Burn.
+ (
+ "o2RidXJuomVvd25lclUAIHIUNIk/YWwJgUjiz5+Z4+KCbhNmYW1vdW50QWRmaGVpZ2h0GCpndHhfaGFzaFggxnK40e9W7Sirh8NiLFEUBpvdOte4+XN0mNDAHs7wlno=",
+ Event {
+ height: 42,
+ tx_hash,
+ burn: Some(BurnEvent {
+ owner: addr1.clone(),
+ amount: 100u32.into(),
+ }),
+ ..Default::default()
+ },
+ ),
+
+ // Escrow.
+ (
+ "o2Zlc2Nyb3ehY2FkZKRlb3duZXJVACByFDSJP2FsCYFI4s+fmePigm4TZmFtb3VudEFkZmVzY3Jvd1UAuRI5eJXmRwxR+r7MndyD9wrthqFqbmV3X3NoYXJlc0EyZmhlaWdodBgqZ3R4X2hhc2hYIMZyuNHvVu0oq4fDYixRFAab3TrXuPlzdJjQwB7O8JZ6",
+ Event {
+ height: 42,
+ tx_hash,
+ escrow: Some(EscrowEvent::Add {
+ owner: addr1.clone(),
+ escrow: addr2.clone(),
+ amount: 100u32.into(),
+ new_shares: 50u32.into(),
+ }),
+ ..Default::default()
+ },
+ ),
+ (
+ "o2Zlc2Nyb3ehZHRha2WjZW93bmVyVQAgchQ0iT9hbAmBSOLPn5nj4oJuE2ZhbW91bnRBZHBkZWJvbmRpbmdfYW1vdW50QRRmaGVpZ2h0GCpndHhfaGFzaFggxnK40e9W7Sirh8NiLFEUBpvdOte4+XN0mNDAHs7wlno=",
+ Event {
+ height: 42,
+ tx_hash,
+ escrow: Some(EscrowEvent::Take {
+ owner: addr1.clone(),
+ amount: 100u32.into(),
+ debonding_amount: 20u32.into()
+ }),
+ ..Default::default()
+ },
+ ),
+ (
+ "o2Zlc2Nyb3ehb2RlYm9uZGluZ19zdGFydKZlb3duZXJVACByFDSJP2FsCYFI4s+fmePigm4TZmFtb3VudEFkZmVzY3Jvd1UAuRI5eJXmRwxR+r7MndyD9wrthqFtYWN0aXZlX3NoYXJlc0Eyb2RlYm9uZF9lbmRfdGltZRgqcGRlYm9uZGluZ19zaGFyZXNBGWZoZWlnaHQYKmd0eF9oYXNoWCDGcrjR71btKKuHw2IsURQGm90617j5c3SY0MAezvCWeg==",
+ Event {
+ height: 42,
+ tx_hash,
+ escrow: Some(EscrowEvent::DebondingStart {
+ owner: addr1.clone(),
+ escrow: addr2.clone(),
+ amount: 100u32.into(),
+ active_shares: 50u32.into(),
+ debonding_shares: 25u32.into(),
+ debond_end_time: 42,
+ }),
+ ..Default::default()
+ },
+ ),
+ (
+ "o2Zlc2Nyb3ehZ3JlY2xhaW2kZW93bmVyVQAgchQ0iT9hbAmBSOLPn5nj4oJuE2ZhbW91bnRBZGZlc2Nyb3dVALkSOXiV5kcMUfq+zJ3cg/cK7YahZnNoYXJlc0EZZmhlaWdodBgqZ3R4X2hhc2hYIMZyuNHvVu0oq4fDYixRFAab3TrXuPlzdJjQwB7O8JZ6",
+ Event {
+ height: 42,
+ tx_hash,
+ escrow: Some(EscrowEvent::Reclaim {
+ owner: addr1.clone(),
+ escrow: addr2.clone(),
+ amount: 100u32.into(),
+ shares: 25u32.into(),
+ }),
+ ..Default::default()
+ },
+ ),
+
+ // Allowance change.
+ (
+ "o2ZoZWlnaHQYKmd0eF9oYXNoWCDGcrjR71btKKuHw2IsURQGm90617j5c3SY0MAezvCWenBhbGxvd2FuY2VfY2hhbmdlpGVvd25lclUAIHIUNIk/YWwJgUjiz5+Z4+KCbhNpYWxsb3dhbmNlQWRrYmVuZWZpY2lhcnlVALkSOXiV5kcMUfq+zJ3cg/cK7YahbWFtb3VudF9jaGFuZ2VBMg==",
+ Event {
+ height: 42,
+ tx_hash,
+ allowance_change: Some(AllowanceChangeEvent {
+ owner: addr1.clone(),
+ beneficiary: addr2.clone(),
+ allowance: 100u32.into(),
+ negative: false,
+ amount_change: 50u32.into(),
+ }),
+ ..Default::default()
+ },
+ ),
+ (
+ "o2ZoZWlnaHQYKmd0eF9oYXNoWCDGcrjR71btKKuHw2IsURQGm90617j5c3SY0MAezvCWenBhbGxvd2FuY2VfY2hhbmdlpWVvd25lclUAIHIUNIk/YWwJgUjiz5+Z4+KCbhNobmVnYXRpdmX1aWFsbG93YW5jZUFka2JlbmVmaWNpYXJ5VQC5Ejl4leZHDFH6vsyd3IP3Cu2GoW1hbW91bnRfY2hhbmdlQTI=",
+ Event {
+ height: 42,
+ tx_hash,
+ allowance_change: Some(AllowanceChangeEvent {
+ owner: addr1.clone(),
+ beneficiary: addr2.clone(),
+ allowance: 100u32.into(),
+ negative: true,
+ amount_change: 50u32.into(),
+ }),
+ ..Default::default()
+ },
+ ),
+ ];
+ for (encoded_base64, ev) in tcs {
+ let dec: Event = cbor::from_slice(&BASE64_STANDARD.decode(encoded_base64).unwrap())
+ .expect("event should deserialize correctly");
+ assert_eq!(dec, ev, "decoded event should match the expected value");
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +
//! Beacon state in the consensus layer.
+use anyhow::anyhow;
+
+use crate::{
+ common::key_format::{KeyFormat, KeyFormatAtom},
+ consensus::{
+ beacon::{EpochTime, EpochTimeState},
+ state::StateError,
+ },
+ key_format,
+ storage::mkvs::{FallibleMKVS, ImmutableMKVS},
+};
+
+/// Consensus beacon state wrapper.
+pub struct ImmutableState<'a, T: ImmutableMKVS> {
+ mkvs: &'a T,
+}
+
+impl<'a, T: ImmutableMKVS> ImmutableState<'a, T> {
+ /// Constructs a new ImmutableMKVS.
+ pub fn new(mkvs: &'a T) -> ImmutableState<'a, T> {
+ ImmutableState { mkvs }
+ }
+}
+
+key_format!(CurrentEpochKeyFmt, 0x40, ());
+key_format!(FutureEpochKeyFmt, 0x41, ());
+
+impl<'a, T: ImmutableMKVS> ImmutableState<'a, T> {
+ /// Returns the current epoch number.
+ pub fn epoch(&self) -> Result<EpochTime, StateError> {
+ self.epoch_state().map(|es| es.epoch)
+ }
+
+ /// Returns the current epoch state.
+ pub fn epoch_state(&self) -> Result<EpochTimeState, StateError> {
+ match self.mkvs.get(&CurrentEpochKeyFmt(()).encode()) {
+ Ok(Some(b)) => {
+ let state: EpochTimeState =
+ cbor::from_slice(&b).map_err(|err| StateError::Unavailable(anyhow!(err)))?;
+ Ok(state)
+ }
+ Ok(None) => Ok(EpochTimeState::default()),
+ Err(err) => Err(StateError::Unavailable(anyhow!(err))),
+ }
+ }
+
+ /// Returns the future epoch number.
+ pub fn future_epoch(&self) -> Result<EpochTime, StateError> {
+ self.future_epoch_state().map(|es| es.epoch)
+ }
+
+ /// Returns the future epoch state.
+ pub fn future_epoch_state(&self) -> Result<EpochTimeState, StateError> {
+ match self.mkvs.get(&FutureEpochKeyFmt(()).encode()) {
+ Ok(Some(b)) => {
+ let state: EpochTimeState =
+ cbor::from_slice(&b).map_err(|err| StateError::Unavailable(anyhow!(err)))?;
+ Ok(state)
+ }
+ Ok(None) => Ok(EpochTimeState::default()),
+ Err(err) => Err(StateError::Unavailable(anyhow!(err))),
+ }
+ }
+}
+
+/// Mutable consensus beacon state wrapper.
+pub struct MutableState;
+
+impl MutableState {
+ /// Set current epoch state.
+ pub fn set_epoch_state<S: FallibleMKVS>(
+ mkvs: &mut S,
+ epoch_state: EpochTimeState,
+ ) -> Result<(), StateError> {
+ mkvs.insert(&CurrentEpochKeyFmt(()).encode(), &cbor::to_vec(epoch_state))?;
+ Ok(())
+ }
+
+ /// Set future epoch state.
+ pub fn set_future_epoch_state<S: FallibleMKVS>(
+ mkvs: &mut S,
+ epoch_state: EpochTimeState,
+ ) -> Result<(), StateError> {
+ mkvs.insert(&FutureEpochKeyFmt(()).encode(), &cbor::to_vec(epoch_state))?;
+ Ok(())
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use crate::{
+ common::crypto::hash::Hash,
+ storage::mkvs::{
+ interop::{Fixture, ProtocolServer},
+ sync::NoopReadSyncer,
+ Root, RootType, Tree,
+ },
+ };
+
+ use super::*;
+
+ #[test]
+ fn test_mutable_state() {
+ let mut mkvs = Tree::builder()
+ .with_root_type(RootType::State)
+ .build(Box::new(NoopReadSyncer));
+
+ MutableState::set_epoch_state(
+ &mut mkvs,
+ EpochTimeState {
+ epoch: 10,
+ height: 100,
+ },
+ )
+ .unwrap();
+
+ MutableState::set_future_epoch_state(
+ &mut mkvs,
+ EpochTimeState {
+ epoch: 11,
+ height: 110,
+ },
+ )
+ .unwrap();
+
+ let beacon_state = ImmutableState::new(&mkvs);
+
+ // Test current epoch state.
+ let epoch_state = beacon_state
+ .epoch_state()
+ .expect("epoch state query should work");
+ assert_eq!(10u64, epoch_state.epoch, "expected epoch should match");
+ assert_eq!(100i64, epoch_state.height, "expected height should match");
+
+ // Test future epoch state.
+ let epoch_state = beacon_state
+ .future_epoch_state()
+ .expect("future epoch state query should work");
+ assert_eq!(11u64, epoch_state.epoch, "expected epoch should match");
+ assert_eq!(110i64, epoch_state.height, "expected height should match");
+ }
+
+ #[test]
+ fn test_beacon_state_interop() {
+ // Keep in sync with go/consensus/cometbft/apps/beacon/state/interop/interop.go.
+ // If mock consensus state changes, update the root hash bellow.
+ // See protocol server stdout for hash.
+ // To make the hash show up during tests, run "cargo test" as
+ // "cargo test -- --nocapture".
+
+ // Setup protocol server with initialized mock consensus state.
+ let server = ProtocolServer::new(Fixture::ConsensusMock.into());
+ let mock_consensus_root = Root {
+ version: 1,
+ root_type: RootType::State,
+ hash: Hash::from("8e39bf193f8a954ab8f8d7cb6388c591fd0785ea060bbd8e3752e266b54499d3"),
+ ..Default::default()
+ };
+ let mkvs = Tree::builder()
+ .with_capacity(100_000, 10_000_000)
+ .with_root(mock_consensus_root)
+ .build(server.read_sync());
+ let beacon_state = ImmutableState::new(&mkvs);
+
+ // Test current epoch number.
+ let epoch = beacon_state.epoch().expect("epoch query should work");
+ assert_eq!(42u64, epoch, "expected epoch should match");
+
+ // Test current epoch state.
+ let epoch_state = beacon_state
+ .epoch_state()
+ .expect("epoch state query should work");
+ assert_eq!(42u64, epoch_state.epoch, "expected epoch should match");
+ assert_eq!(13i64, epoch_state.height, "expected height should match");
+
+ // Test future epoch number.
+ let epoch = beacon_state
+ .future_epoch()
+ .expect("future epoch query should work");
+ assert_eq!(43u64, epoch, "expected future epoch should match");
+
+ // Test future epoch state.
+ let epoch_state = beacon_state
+ .future_epoch_state()
+ .expect("future epoch state query should work");
+ assert_eq!(43u64, epoch_state.epoch, "expected epoch should match");
+ assert_eq!(15i64, epoch_state.height, "expected height should match");
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +
//! Key manager state in the consensus layer.
+use anyhow::anyhow;
+
+use crate::{
+ common::{
+ crypto::{hash::Hash, signature::PublicKey},
+ key_format::{KeyFormat, KeyFormatAtom},
+ namespace::Namespace,
+ },
+ consensus::{
+ beacon::EpochTime,
+ keymanager::{
+ SignedEncryptedEphemeralSecret, SignedEncryptedMasterSecret, SignedPolicySGX,
+ },
+ state::StateError,
+ },
+ key_format,
+ storage::mkvs::ImmutableMKVS,
+};
+
+pub mod churp;
+
+/// Consensus key manager state wrapper.
+pub struct ImmutableState<'a, T: ImmutableMKVS> {
+ mkvs: &'a T,
+}
+
+impl<'a, T: ImmutableMKVS> ImmutableState<'a, T> {
+ /// Constructs a new ImmutableMKVS.
+ pub fn new(mkvs: &'a T) -> ImmutableState<'a, T> {
+ ImmutableState { mkvs }
+ }
+}
+
+key_format!(StatusKeyFmt, 0x70, Hash);
+key_format!(MasterSecretKeyFmt, 0x72, Hash);
+key_format!(EphemeralSecretKeyFmt, 0x73, Hash);
+
+/// Current key manager status.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Decode, cbor::Encode)]
+pub struct Status {
+ /// Runtime ID of the key manager.
+ pub id: Namespace,
+ /// True iff the key manager is done initializing.
+ pub is_initialized: bool,
+ /// True iff the key manager is secure.
+ pub is_secure: bool,
+ /// Generation of the latest master secret.
+ pub generation: u64,
+ /// Epoch of the last master secret rotation.
+ pub rotation_epoch: EpochTime,
+ /// Key manager master secret verification checksum.
+ pub checksum: Vec<u8>,
+ /// List of currently active key manager node IDs.
+ pub nodes: Vec<PublicKey>,
+ /// Key manager policy.
+ pub policy: Option<SignedPolicySGX>,
+ /// Runtime signing key of the key manager.
+ pub rsk: Option<PublicKey>,
+}
+
+impl<'a, T: ImmutableMKVS> ImmutableState<'a, T> {
+ /// Looks up a specific key manager status by its namespace identifier.
+ pub fn status(&self, id: Namespace) -> Result<Option<Status>, StateError> {
+ let h = Hash::digest_bytes(id.as_ref());
+ match self.mkvs.get(&StatusKeyFmt(h).encode()) {
+ Ok(Some(b)) => Ok(Some(self.decode_status(&b)?)),
+ Ok(None) => Ok(None),
+ Err(err) => Err(StateError::Unavailable(anyhow!(err))),
+ }
+ }
+
+ /// Returns the list of all key manager statuses.
+ pub fn statuses(&self) -> Result<Vec<Status>, StateError> {
+ let mut it = self.mkvs.iter();
+ it.seek(&StatusKeyFmt::default().encode_partial(0));
+
+ let mut result: Vec<Status> = Vec::new();
+
+ while let Some(value) = it
+ .next()
+ .and_then(|(key, value)| StatusKeyFmt::decode(&key).map(|_| value))
+ {
+ result.push(self.decode_status(&value)?)
+ }
+
+ Ok(result)
+ }
+
+ /// Looks up a specific key manager master secret by its namespace identifier.
+ pub fn master_secret(
+ &self,
+ id: Namespace,
+ ) -> Result<Option<SignedEncryptedMasterSecret>, StateError> {
+ let h = Hash::digest_bytes(id.as_ref());
+ match self.mkvs.get(&MasterSecretKeyFmt(h).encode()) {
+ Ok(Some(b)) => Ok(Some(self.decode_master_secret(&b)?)),
+ Ok(None) => Ok(None),
+ Err(err) => Err(StateError::Unavailable(anyhow!(err))),
+ }
+ }
+
+ /// Looks up a specific key manager ephemeral secret by its namespace identifier and epoch.
+ pub fn ephemeral_secret(
+ &self,
+ id: Namespace,
+ ) -> Result<Option<SignedEncryptedEphemeralSecret>, StateError> {
+ let h = Hash::digest_bytes(id.as_ref());
+ match self.mkvs.get(&EphemeralSecretKeyFmt(h).encode()) {
+ Ok(Some(b)) => Ok(Some(self.decode_ephemeral_secret(&b)?)),
+ Ok(None) => Ok(None),
+ Err(err) => Err(StateError::Unavailable(anyhow!(err))),
+ }
+ }
+
+ fn decode_status(&self, data: &[u8]) -> Result<Status, StateError> {
+ cbor::from_slice(data).map_err(|err| StateError::Unavailable(anyhow!(err)))
+ }
+
+ fn decode_master_secret(&self, data: &[u8]) -> Result<SignedEncryptedMasterSecret, StateError> {
+ cbor::from_slice(data).map_err(|err| StateError::Unavailable(anyhow!(err)))
+ }
+
+ fn decode_ephemeral_secret(
+ &self,
+ data: &[u8],
+ ) -> Result<SignedEncryptedEphemeralSecret, StateError> {
+ cbor::from_slice(data).map_err(|err| StateError::Unavailable(anyhow!(err)))
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use std::collections::HashMap;
+
+ use rustc_hex::FromHex;
+
+ use super::*;
+ use crate::{
+ common::{
+ crypto::{
+ signature::{Signature, SignatureBundle},
+ x25519,
+ },
+ sgx::{EnclaveIdentity, MrEnclave, MrSigner},
+ },
+ consensus::keymanager::{
+ EnclavePolicySGX, EncryptedEphemeralSecret, EncryptedSecret, PolicySGX,
+ },
+ storage::mkvs::{
+ interop::{Fixture, ProtocolServer},
+ Root, RootType, Tree,
+ },
+ };
+
+ #[test]
+ fn test_keymanager_secrets_state_interop() {
+ // Keep in sync with go/consensus/cometbft/apps/keymanager/secrets/state/interop/interop.go.
+ // If mock consensus state changes, update the root hash bellow.
+ // See protocol server stdout for hash.
+ // To make the hash show up during tests, run "cargo test" as
+ // "cargo test -- --nocapture".
+
+ // Setup protocol server with initialized mock consensus state.
+ let server = ProtocolServer::new(Fixture::ConsensusMock.into());
+ let mock_consensus_root = Root {
+ version: 1,
+ root_type: RootType::State,
+ hash: Hash::from("8e39bf193f8a954ab8f8d7cb6388c591fd0785ea060bbd8e3752e266b54499d3"),
+ ..Default::default()
+ };
+ let mkvs = Tree::builder()
+ .with_capacity(100_000, 10_000_000)
+ .with_root(mock_consensus_root)
+ .build(server.read_sync());
+ let keymanager_state = ImmutableState::new(&mkvs);
+
+ // Prepare expected results.
+ let runtime =
+ Namespace::from("8000000000000000000000000000000000000000000000000000000000000000");
+ let keymanager1 =
+ Namespace::from("c000000000000000fffffffffffffffffffffffffffffffffffffffffffffffe");
+ let keymanager2 =
+ Namespace::from("c000000000000000ffffffffffffffffffffffffffffffffffffffffffffffff");
+ let runtime_enclave = EnclaveIdentity {
+ mr_enclave: MrEnclave::from(
+ "18256f783c071521be2da041cd9347b5bdb5a8ef58fb34658571a6e14cf1fcb0",
+ ),
+ mr_signer: MrSigner::from(
+ "e48049d1de0eb333523991671a6c93b97dd65bcf09273d5b6bfe8262dc968ec7",
+ ),
+ };
+ let keymanager_enclave1 = EnclaveIdentity {
+ mr_enclave: MrEnclave::from(
+ "c9a589851b1f35627177fd70378ed778170f737611e4dfbf0b6d25bdff55b474",
+ ),
+ mr_signer: MrSigner::from(
+ "7d310664780931ae103ab30a90171c201af385a72757bb4683578fdebde9adf5",
+ ),
+ };
+ let keymanager_enclave2 = EnclaveIdentity {
+ mr_enclave: MrEnclave::from(
+ "756eaf76f5482c5345808b1eaccdd5c60f864bb2aa2d2b870df00ce435af4e23",
+ ),
+ mr_signer: MrSigner::from(
+ "3597a2ff0743016f28e5d7e129304ee1c43dbdae3dba94e19cee3549038a5a32",
+ ),
+ };
+ let signer1 =
+ PublicKey::from("96533c123a6f4d33c68357109c2eb7c6e6a0f947be3ae1e320d153f561523ff2");
+ let signer2 =
+ PublicKey::from("4b97bfd95e829d5838131492b5c133e66ac6ef0db414c0be6207ec78c12d2b17");
+ let sig1 = Signature::from("eda666cff6e4030200737e0c7707ad4a378aab4cc0455306992c13da2155b97c91b0fde0325a7a6818f2cbf92813cc587723c8c205a7cb5389ca7b21a038b60a");
+ let sig2 = Signature::from("db90d354272e025aa9a5856f32ea4f5d6becb0ff6340f3cb7f9104ac04ef29ed4f9b5c21b7ea82924800b30f94724b40c376414f80780ff8b7b60a34edea9f02");
+ let checksum = "1bff211fae98c88ba82388ae954b88a71d3bbe327e162e9fa711fe7a1b759c3e"
+ .from_hex()
+ .unwrap();
+
+ let expected_statuses = vec![
+ Status {
+ id: keymanager1,
+ is_initialized: false,
+ is_secure: false,
+ generation: 0,
+ rotation_epoch: 0,
+ checksum: vec![],
+ nodes: vec![],
+ policy: None,
+ rsk: None,
+ },
+ Status {
+ id: keymanager2,
+ is_initialized: true,
+ is_secure: true,
+ generation: 0,
+ rotation_epoch: 0,
+ checksum: checksum,
+ nodes: vec![signer1, signer2],
+ policy: Some(SignedPolicySGX {
+ policy: PolicySGX {
+ serial: 1,
+ id: keymanager2,
+ enclaves: HashMap::from([(
+ keymanager_enclave1,
+ EnclavePolicySGX {
+ may_query: HashMap::from([(runtime, vec![runtime_enclave])]),
+ may_replicate: vec![keymanager_enclave2],
+ },
+ )]),
+ master_secret_rotation_interval: 0,
+ max_ephemeral_secret_age: 10,
+ },
+ signatures: vec![
+ SignatureBundle {
+ public_key: signer1,
+ signature: sig1,
+ },
+ SignatureBundle {
+ public_key: signer2,
+ signature: sig2,
+ },
+ ],
+ }),
+ rsk: None,
+ },
+ ];
+
+ let rek1 = x25519::PrivateKey::from_test_seed("first rek".to_string());
+ let rek2 = x25519::PrivateKey::from_test_seed("second rek".to_string());
+
+ let expected_secret = SignedEncryptedEphemeralSecret {
+ secret: EncryptedEphemeralSecret {
+ runtime_id: keymanager1,
+ epoch: 1,
+ secret: EncryptedSecret{
+ checksum: vec![1,2,3,4,5],
+ pub_key: rek1.public_key(),
+ ciphertexts: HashMap::from([
+ (rek1.public_key(), vec![1, 2, 3]),
+ (rek2.public_key(), vec![4, 5, 6]),
+ ]),
+ },
+ },
+ signature: Signature::from("4a2d098e02411fdc14d6a36f91bb362fd4f4dbaadb4cbf70e20e038fe1740bc7dde0b20afd25657d6abc916be2b9ed0054d586aedb2b7951c99aab3206b24b02"),
+ };
+
+ // Test statuses.
+ let mut statuses = keymanager_state
+ .statuses()
+ .expect("statuses query should work");
+ statuses.sort_by(|a, b| a.id.partial_cmp(&b.id).unwrap());
+ assert_eq!(statuses, expected_statuses, "invalid statuses");
+
+ // Test status.
+ let status = keymanager_state
+ .status(expected_statuses[1].id)
+ .expect("status query should work")
+ .expect("status query should return a result");
+ assert_eq!(status, expected_statuses[1], "invalid status");
+
+ let id =
+ Namespace::from("ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff");
+ let status = keymanager_state
+ .status(id)
+ .expect("status query should work");
+ assert_eq!(status, None, "invalid status");
+
+ // Test ephemeral secret (happy path, invalid epoch, invalid runtime).
+ let secret = keymanager_state
+ .ephemeral_secret(keymanager1)
+ .expect("ephemeral secret query should work")
+ .expect("ephemeral secret query should return a result");
+ assert_eq!(secret, expected_secret, "invalid ephemeral secret");
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +
//! Key manager state in the consensus layer.
+use anyhow::anyhow;
+
+use crate::{
+ common::{
+ crypto::hash::Hash,
+ key_format::{KeyFormat, KeyFormatAtom},
+ namespace::Namespace,
+ },
+ consensus::{keymanager::churp::Status, state::StateError},
+ key_format,
+ storage::mkvs::ImmutableMKVS,
+};
+
+key_format!(StatusKeyFmt, 0x75, (Hash, u8));
+
+/// Consensus CHURP state wrapper.
+pub struct ImmutableState<'a, T: ImmutableMKVS> {
+ mkvs: &'a T,
+}
+
+impl<'a, T: ImmutableMKVS> ImmutableState<'a, T> {
+ /// Constructs a new ImmutableMKVS.
+ pub fn new(mkvs: &'a T) -> ImmutableState<'a, T> {
+ ImmutableState { mkvs }
+ }
+}
+
+impl<'a, T: ImmutableMKVS> ImmutableState<'a, T> {
+ /// Looks up a specific key manager status by its namespace identifier.
+ pub fn status(
+ &self,
+ runtime_id: Namespace,
+ churp_id: u8,
+ ) -> Result<Option<Status>, StateError> {
+ let h = Hash::digest_bytes(runtime_id.as_ref());
+ match self.mkvs.get(&StatusKeyFmt((h, churp_id)).encode()) {
+ Ok(Some(b)) => Ok(Some(self.decode_status(&b)?)),
+ Ok(None) => Ok(None),
+ Err(err) => Err(StateError::Unavailable(anyhow!(err))),
+ }
+ }
+
+ fn decode_status(&self, data: &[u8]) -> Result<Status, StateError> {
+ cbor::from_slice(data).map_err(|err| StateError::Unavailable(anyhow!(err)))
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use std::collections::HashMap;
+
+ use super::*;
+ use crate::{
+ common::{
+ crypto::signature::{PublicKey, Signature, SignatureBundle},
+ sgx::{EnclaveIdentity, MrEnclave, MrSigner},
+ },
+ consensus::keymanager::churp::{Application, PolicySGX, SignedPolicySGX, SuiteId},
+ storage::mkvs::{
+ interop::{Fixture, ProtocolServer},
+ Root, RootType, Tree,
+ },
+ };
+
+ #[test]
+ fn test_keymanager_secrets_state_interop() {
+ // Keep in sync with go/consensus/cometbft/apps/keymanager/churp/state/interop/interop.go.
+ // If mock consensus state changes, update the root hash bellow.
+ // See protocol server stdout for hash.
+ // To make the hash show up during tests, run "cargo test" as
+ // "cargo test -- --nocapture".
+
+ // Setup protocol server with initialized mock consensus state.
+ let server = ProtocolServer::new(Fixture::ConsensusMock.into());
+ let mock_consensus_root = Root {
+ version: 1,
+ root_type: RootType::State,
+ hash: Hash::from("8e39bf193f8a954ab8f8d7cb6388c591fd0785ea060bbd8e3752e266b54499d3"),
+ ..Default::default()
+ };
+ let mkvs = Tree::builder()
+ .with_capacity(100_000, 10_000_000)
+ .with_root(mock_consensus_root)
+ .build(server.read_sync());
+ let state = ImmutableState::new(&mkvs);
+
+ // Prepare expected results.
+ let runtime_id =
+ Namespace::from("8000000000000000000000000000000000000000000000000000000000000000");
+ let enclave1 = EnclaveIdentity {
+ mr_enclave: MrEnclave::from(
+ "c9a589851b1f35627177fd70378ed778170f737611e4dfbf0b6d25bdff55b474",
+ ),
+ mr_signer: MrSigner::from(
+ "7d310664780931ae103ab30a90171c201af385a72757bb4683578fdebde9adf5",
+ ),
+ };
+ let enclave2 = EnclaveIdentity {
+ mr_enclave: MrEnclave::from(
+ "756eaf76f5482c5345808b1eaccdd5c60f864bb2aa2d2b870df00ce435af4e23",
+ ),
+ mr_signer: MrSigner::from(
+ "3597a2ff0743016f28e5d7e129304ee1c43dbdae3dba94e19cee3549038a5a32",
+ ),
+ };
+ let signer1 =
+ PublicKey::from("96533c123a6f4d33c68357109c2eb7c6e6a0f947be3ae1e320d153f561523ff2");
+ let signer2 =
+ PublicKey::from("4b97bfd95e829d5838131492b5c133e66ac6ef0db414c0be6207ec78c12d2b17");
+ let sig1 = Signature::from("eda666cff6e4030200737e0c7707ad4a378aab4cc0455306992c13da2155b97c91b0fde0325a7a6818f2cbf92813cc587723c8c205a7cb5389ca7b21a038b60a");
+ let sig2 = Signature::from("db90d354272e025aa9a5856f32ea4f5d6becb0ff6340f3cb7f9104ac04ef29ed4f9b5c21b7ea82924800b30f94724b40c376414f80780ff8b7b60a34edea9f02");
+ let checksum =
+ Hash::from("1bff211fae98c88ba82388ae954b88a71d3bbe327e162e9fa711fe7a1b759c3e");
+ let committee = vec![signer1, signer2];
+ let mut applications = HashMap::new();
+ applications.insert(
+ signer1,
+ Application {
+ checksum: checksum.clone(),
+ reconstructed: false,
+ },
+ );
+ applications.insert(
+ signer2,
+ Application {
+ checksum: checksum.clone(),
+ reconstructed: true,
+ },
+ );
+ let checksum = Some(checksum);
+ let next_checksum = checksum;
+
+ // Test empty status.
+ let status = Status {
+ ..Default::default()
+ };
+
+ let status = state
+ .status(status.runtime_id, status.id)
+ .expect("status query should work")
+ .expect("status query should return a result");
+ assert_eq!(status, status, "invalid status");
+
+ // Test non-empty status.
+ let status = Status {
+ id: 1,
+ runtime_id,
+ suite_id: SuiteId::NistP384Sha3_384,
+ threshold: 2,
+ extra_shares: 1,
+ handoff_interval: 3,
+ policy: SignedPolicySGX {
+ policy: PolicySGX {
+ id: 1,
+ runtime_id,
+ serial: 6,
+ may_share: vec![enclave1],
+ may_join: vec![enclave2],
+ may_query: HashMap::new(),
+ },
+ signatures: vec![
+ SignatureBundle {
+ public_key: signer1,
+ signature: sig1,
+ },
+ SignatureBundle {
+ public_key: signer2,
+ signature: sig2,
+ },
+ ],
+ },
+ handoff: 4,
+ checksum,
+ committee,
+ next_handoff: 5,
+ next_checksum,
+ applications,
+ };
+
+ let status = state
+ .status(status.runtime_id, status.id)
+ .expect("status query should work")
+ .expect("status query should return a result");
+ assert_eq!(status, status, "invalid status");
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +
//! Consensus state wrappers.
+use std::sync::Arc;
+
+use anyhow::{Error, Result};
+use thiserror::Error;
+
+use crate::{
+ protocol::Protocol,
+ storage::mkvs::{sync::HostReadSyncer, ImmutableMKVS, Root, Tree},
+ types::{self, HostStorageEndpoint},
+};
+
+pub mod beacon;
+pub mod keymanager;
+pub mod registry;
+pub mod roothash;
+pub mod staking;
+
+#[derive(Error, Debug)]
+pub enum StateError {
+ #[error("consensus state: unavailable/corrupted state: {0}")]
+ Unavailable(#[from] Error),
+}
+
+impl From<StateError> for types::Error {
+ fn from(e: StateError) -> Self {
+ Self {
+ module: "consensus".to_string(),
+ code: 1,
+ message: e.to_string(),
+ }
+ }
+}
+
+/// Provides consensus state tree from the host.
+pub struct ConsensusState {
+ // An explicit height field is needed because the relationship between the underlying consensus
+ // height and the corresponding state root is a consensus backend implementation detail.
+ height: u64,
+ mkvs: Tree,
+}
+
+impl ConsensusState {
+ /// Creates a consensus state wrapping the provided tree.
+ pub fn new(height: u64, tree: Tree) -> Self {
+ Self { height, mkvs: tree }
+ }
+
+ /// Creates consensus state using host protocol.
+ pub fn from_protocol(protocol: Arc<Protocol>, height: u64, root: Root) -> Self {
+ let read_syncer = HostReadSyncer::new(protocol, HostStorageEndpoint::Consensus);
+ Self {
+ height,
+ mkvs: Tree::builder()
+ .with_capacity(100_000, 10_000_000)
+ .with_root(root)
+ .build(Box::new(read_syncer)),
+ }
+ }
+
+ /// Consensus layer height that this data is for.
+ pub fn height(&self) -> u64 {
+ self.height
+ }
+}
+
+impl ImmutableMKVS for ConsensusState {
+ fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>> {
+ self.mkvs.get(key)
+ }
+
+ fn get_proof(&self, key: &[u8]) -> Result<Option<crate::storage::mkvs::sync::Proof>> {
+ self.mkvs.get_proof(key)
+ }
+
+ fn prefetch_prefixes(
+ &self,
+ prefixes: &[crate::storage::mkvs::Prefix],
+ limit: u16,
+ ) -> Result<()> {
+ self.mkvs.prefetch_prefixes(prefixes, limit)
+ }
+
+ fn iter(&self) -> Box<dyn crate::storage::mkvs::Iterator + '_> {
+ Box::new(self.mkvs.iter())
+ }
+}
+
+impl ImmutableMKVS for &ConsensusState {
+ fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>> {
+ self.mkvs.get(key)
+ }
+
+ fn get_proof(&self, key: &[u8]) -> Result<Option<crate::storage::mkvs::sync::Proof>> {
+ self.mkvs.get_proof(key)
+ }
+
+ fn prefetch_prefixes(
+ &self,
+ prefixes: &[crate::storage::mkvs::Prefix],
+ limit: u16,
+ ) -> Result<()> {
+ self.mkvs.prefetch_prefixes(prefixes, limit)
+ }
+
+ fn iter(&self) -> Box<dyn crate::storage::mkvs::Iterator + '_> {
+ Box::new(self.mkvs.iter())
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +
//! Registry state in the consensus layer.
+use anyhow::anyhow;
+
+use crate::{
+ common::{
+ crypto::{
+ hash::Hash,
+ signature::{MultiSigned, PublicKey},
+ },
+ key_format::{KeyFormat, KeyFormatAtom},
+ namespace::Namespace,
+ },
+ consensus::{
+ registry::{Node, Runtime},
+ state::StateError,
+ },
+ key_format,
+ storage::mkvs::ImmutableMKVS,
+};
+
+/// Consensus registry state wrapper.
+pub struct ImmutableState<'a, T: ImmutableMKVS> {
+ mkvs: &'a T,
+}
+
+impl<'a, T: ImmutableMKVS> ImmutableState<'a, T> {
+ /// Constructs a new ImmutableMKVS.
+ pub fn new(mkvs: &'a T) -> ImmutableState<'a, T> {
+ ImmutableState { mkvs }
+ }
+}
+
+key_format!(SignedNodeKeyFmt, 0x11, Hash);
+key_format!(RuntimeKeyFmt, 0x13, Hash);
+key_format!(SuspendedRuntimeKeyFmt, 0x18, Hash);
+
+impl<'a, T: ImmutableMKVS> ImmutableState<'a, T> {
+ fn decode_node(&self, data: &[u8]) -> Result<Node, StateError> {
+ let signed: MultiSigned =
+ cbor::from_slice(data).map_err(|err| StateError::Unavailable(anyhow!(err)))?;
+ // The signed blob is transported as-is so we need to use non-strict decoding.
+ cbor::from_slice_non_strict(&signed.blob)
+ .map_err(|err| StateError::Unavailable(anyhow!(err)))
+ }
+
+ /// Looks up a specific node by its identifier.
+ pub fn node(&self, id: &PublicKey) -> Result<Option<Node>, StateError> {
+ let h = Hash::digest_bytes(id.as_ref());
+ match self.mkvs.get(&SignedNodeKeyFmt(h).encode()) {
+ Ok(Some(b)) => Ok(Some(self.decode_node(&b)?)),
+ Ok(None) => Ok(None),
+ Err(err) => Err(StateError::Unavailable(anyhow!(err))),
+ }
+ }
+
+ /// Returns the list of all registered nodes.
+ pub fn nodes(&self) -> Result<Vec<Node>, StateError> {
+ let mut it = self.mkvs.iter();
+ it.seek(&SignedNodeKeyFmt::default().encode_partial(0));
+
+ let mut result: Vec<Node> = Vec::new();
+
+ while let Some(value) = it
+ .next()
+ .and_then(|(key, value)| SignedNodeKeyFmt::decode(&key).map(|_| value))
+ {
+ result.push(self.decode_node(&value)?)
+ }
+
+ Ok(result)
+ }
+
+ fn decode_runtime(&self, data: &[u8]) -> Result<Runtime, StateError> {
+ cbor::from_slice(data).map_err(|err| StateError::Unavailable(anyhow!(err)))
+ }
+
+ /// Looks up a specific runtime by its identifier.
+ ///
+ /// # Note
+ ///
+ /// This includes both non-suspended and suspended runtimes.
+ pub fn runtime(&self, id: &Namespace) -> Result<Option<Runtime>, StateError> {
+ let h = Hash::digest_bytes(id.as_ref());
+
+ // Try non-suspended first.
+ match self.mkvs.get(&RuntimeKeyFmt(h).encode()) {
+ Ok(Some(b)) => Ok(Some(self.decode_runtime(&b)?)),
+ Ok(None) => {
+ // Also try suspended.
+ match self.mkvs.get(&SuspendedRuntimeKeyFmt(h).encode()) {
+ Ok(Some(b)) => Ok(Some(self.decode_runtime(&b)?)),
+ Ok(None) => Ok(None),
+ Err(err) => Err(StateError::Unavailable(anyhow!(err))),
+ }
+ }
+ Err(err) => Err(StateError::Unavailable(anyhow!(err))),
+ }
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use std::collections::BTreeMap;
+
+ use crate::{
+ common::crypto::signature,
+ consensus::registry::{
+ AnyNodeRuntimeAdmissionPolicy, Capabilities, CapabilityTEE, ConsensusInfo,
+ EntityWhitelistRoleAdmissionPolicy, NodeRuntime, P2PInfo, PerRoleAdmissionPolicy,
+ RolesMask, RuntimeAdmissionPolicy, RuntimeKind, TEEHardware, TLSInfo, VRFInfo,
+ VersionInfo,
+ },
+ storage::mkvs::{
+ interop::{Fixture, ProtocolServer},
+ Root, RootType, Tree,
+ },
+ Version,
+ };
+
+ use super::*;
+
+ #[test]
+ fn test_registry_state_interop() {
+ // Keep in sync with go/consensus/cometbft/apps/registry/state/interop/interop.go.
+ // If mock consensus state changes, update the root hash bellow.
+ // See protocol server stdout for hash.
+ // To make the hash show up during tests, run "cargo test" as
+ // "cargo test -- --nocapture".
+
+ // Setup protocol server with initialized mock consensus state.
+ let server = ProtocolServer::new(Fixture::ConsensusMock.into());
+ let mock_consensus_root = Root {
+ version: 1,
+ root_type: RootType::State,
+ hash: Hash::from("8e39bf193f8a954ab8f8d7cb6388c591fd0785ea060bbd8e3752e266b54499d3"),
+ ..Default::default()
+ };
+ let mkvs = Tree::builder()
+ .with_capacity(100_000, 10_000_000)
+ .with_root(mock_consensus_root)
+ .build(server.read_sync());
+ let registry_state = ImmutableState::new(&mkvs);
+
+ // Test get nodes.
+ let nodes = registry_state.nodes().expect("nodes query should work");
+ assert_eq!(
+ nodes.len(),
+ 2,
+ "expected number of nodes should be returned"
+ );
+
+ let expected_nodes = vec![
+ Node{
+ v: 3,
+ id: signature::PublicKey::from("43e5aaee54c768867718837ef4f6a6161e0615da0fcf8da394e5c8b7a0d54c18"),
+ entity_id: signature::PublicKey::from("761950dfe65936f6e9d06a0124bc930f7d5b1812ceefdfb2cae0ef5841291531"),
+ expiration: 32,
+ ..Default::default()
+ },
+ Node{
+ v: 3,
+ id: signature::PublicKey::from("f43c3559658f76b85d0630f56dc75d603807ac60be0ca3aada66799289066758"),
+ entity_id: signature::PublicKey::from("761950dfe65936f6e9d06a0124bc930f7d5b1812ceefdfb2cae0ef5841291531"),
+ expiration: 32,
+ tls: TLSInfo{
+ pub_key: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0"),
+ ..Default::default()
+ },
+ p2p: P2PInfo{
+ id: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff3"),
+ addresses: Some(Vec::new()),
+ },
+ consensus: ConsensusInfo{
+ id: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff4"),
+ addresses: Some(Vec::new()),
+ },
+ vrf: VRFInfo{
+ id: PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff5"),
+ },
+ runtimes: Some(vec![
+ NodeRuntime{
+ id: Namespace::from("8000000000000000000000000000000000000000000000000000000000000010"),
+ version: Version::from(321),
+ ..Default::default()
+ },
+ NodeRuntime{
+ id: Namespace::from("8000000000000000000000000000000000000000000000000000000000000011"),
+ version: Version::from(123),
+ capabilities: Capabilities{
+ tee: Some(CapabilityTEE{
+ hardware: TEEHardware::TEEHardwareIntelSGX,
+ rak: signature::PublicKey::from("fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff8"),
+ attestation: vec![0, 1,2,3,4,5],
+ ..Default::default()
+ }),
+ },
+ extra_info: Some(vec![5,3,2,1]),
+ },
+ ]),
+ ..Default::default()
+ },
+ ];
+ assert_eq!(nodes, expected_nodes,);
+
+ let node = registry_state
+ .node(&expected_nodes.get(1).unwrap().id)
+ .expect("node query should work");
+ assert_eq!(node, Some(expected_nodes.get(1).unwrap().clone()));
+
+ let node = registry_state
+ .node(&signature::PublicKey::from(
+ "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+ ))
+ .expect("node query should work");
+ assert_eq!(node, None);
+
+ let expected_runtimes = vec![
+ Runtime {
+ v: 3,
+ id: Namespace::from(
+ "8000000000000000000000000000000000000000000000000000000000000010",
+ ),
+ entity_id: signature::PublicKey::from(
+ "761950dfe65936f6e9d06a0124bc930f7d5b1812ceefdfb2cae0ef5841291531",
+ ),
+ kind: RuntimeKind::KindCompute,
+ tee_hardware: TEEHardware::TEEHardwareInvalid,
+ admission_policy: RuntimeAdmissionPolicy {
+ any_node: Some(AnyNodeRuntimeAdmissionPolicy {}),
+ ..Default::default()
+ },
+ deployments: vec![
+ VersionInfo {
+ version: Version::from(321),
+ valid_from: 42,
+ ..Default::default()
+ },
+ VersionInfo {
+ version: Version::from(320),
+ valid_from: 10,
+ ..Default::default()
+ },
+ ],
+ ..Default::default()
+ },
+ Runtime {
+ v: 3,
+ id: Namespace::from(
+ "8000000000000000000000000000000000000000000000000000000000000011",
+ ),
+ entity_id: signature::PublicKey::from(
+ "761950dfe65936f6e9d06a0124bc930f7d5b1812ceefdfb2cae0ef5841291531",
+ ),
+ kind: RuntimeKind::KindCompute,
+ tee_hardware: TEEHardware::TEEHardwareIntelSGX,
+ admission_policy: RuntimeAdmissionPolicy {
+ any_node: Some(AnyNodeRuntimeAdmissionPolicy {}),
+ ..Default::default()
+ },
+ deployments: vec![
+ VersionInfo {
+ version: Version::from(123),
+ valid_from: 42,
+ tee: vec![1, 2, 3, 4, 5],
+ bundle_checksum: vec![0x5; 32],
+ },
+ VersionInfo {
+ version: Version::from(120),
+ valid_from: 10,
+ tee: vec![5, 4, 3, 2, 1],
+ ..Default::default()
+ },
+ ],
+ ..Default::default()
+ },
+ Runtime {
+ v: 3,
+ id: Namespace::from(
+ "8000000000000000000000000000000000000000000000000000000000000012",
+ ),
+ entity_id: signature::PublicKey::from(
+ "761950dfe65936f6e9d06a0124bc930f7d5b1812ceefdfb2cae0ef5841291531",
+ ),
+ kind: RuntimeKind::KindCompute,
+ tee_hardware: TEEHardware::TEEHardwareIntelSGX,
+ admission_policy: RuntimeAdmissionPolicy {
+ per_role: BTreeMap::from([(
+ RolesMask::ROLE_OBSERVER,
+ PerRoleAdmissionPolicy {
+ entity_whitelist: Some(EntityWhitelistRoleAdmissionPolicy {
+ entities: BTreeMap::new(),
+ }),
+ },
+ )]),
+ ..Default::default()
+ },
+ deployments: vec![VersionInfo {
+ version: Version::from(123),
+ valid_from: 42,
+ tee: vec![1, 2, 3, 4, 5],
+ bundle_checksum: vec![0x5; 32],
+ }],
+ ..Default::default()
+ },
+ ];
+
+ for rt in expected_runtimes {
+ let ext_rt = registry_state
+ .runtime(&rt.id)
+ .expect("runtime query should work");
+ assert_eq!(ext_rt, Some(rt));
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +
//! Roothash state in the consensus layer.
+use std::{collections::BTreeMap, convert::TryInto};
+
+use anyhow::anyhow;
+
+use crate::{
+ common::{
+ crypto::hash::Hash,
+ key_format::{KeyFormat, KeyFormatAtom},
+ namespace::Namespace,
+ },
+ consensus::{
+ roothash::{Error, RoundResults, RoundRoots},
+ state::StateError,
+ },
+ key_format,
+ storage::mkvs::ImmutableMKVS,
+};
+
+/// Consensus roothash state wrapper.
+pub struct ImmutableState<'a, T: ImmutableMKVS> {
+ mkvs: &'a T,
+}
+
+impl<'a, T: ImmutableMKVS> ImmutableState<'a, T> {
+ /// Constructs a new ImmutableMKVS.
+ pub fn new(mkvs: &'a T) -> ImmutableState<'a, T> {
+ ImmutableState { mkvs }
+ }
+}
+
+key_format!(StateRootKeyFmt, 0x25, Hash);
+key_format!(LastRoundResultsKeyFmt, 0x27, Hash);
+key_format!(PastRootsKeyFmt, 0x2a, (Hash, u64));
+
+impl<'a, T: ImmutableMKVS> ImmutableState<'a, T> {
+ /// Returns the state root for a specific runtime.
+ pub fn state_root(&self, id: Namespace) -> Result<Hash, Error> {
+ match self
+ .mkvs
+ .get(&StateRootKeyFmt(Hash::digest_bytes(id.as_ref())).encode())
+ {
+ Ok(Some(b)) => Ok(Hash(b.try_into().map_err(|_| -> Error {
+ StateError::Unavailable(anyhow!("corrupted hash value")).into()
+ })?)),
+ Ok(None) => Err(Error::InvalidRuntime(id)),
+ Err(err) => Err(StateError::Unavailable(anyhow!(err)).into()),
+ }
+ }
+
+ /// Returns the last round results for a specific runtime.
+ pub fn last_round_results(&self, id: Namespace) -> Result<RoundResults, Error> {
+ match self
+ .mkvs
+ .get(&LastRoundResultsKeyFmt(Hash::digest_bytes(id.as_ref())).encode())
+ {
+ Ok(Some(b)) => {
+ cbor::from_slice(&b).map_err(|err| StateError::Unavailable(anyhow!(err)).into())
+ }
+ Ok(None) => Err(Error::InvalidRuntime(id)),
+ Err(err) => Err(StateError::Unavailable(anyhow!(err)).into()),
+ }
+ }
+
+ // Returns the state and I/O roots for the given runtime and round.
+ pub fn round_roots(&self, id: Namespace, round: u64) -> Result<Option<RoundRoots>, StateError> {
+ match self
+ .mkvs
+ .get(&PastRootsKeyFmt((Hash::digest_bytes(id.as_ref()), round)).encode())
+ {
+ Ok(Some(b)) => {
+ cbor::from_slice(&b).map_err(|err| StateError::Unavailable(anyhow!(err)))
+ }
+ Ok(None) => Ok(None),
+ Err(err) => Err(StateError::Unavailable(anyhow!(err))),
+ }
+ }
+
+ // Returns all past round roots for the given runtime.
+ pub fn past_round_roots(&self, id: Namespace) -> Result<BTreeMap<u64, RoundRoots>, StateError> {
+ let h = Hash::digest_bytes(id.as_ref());
+ let mut it = self.mkvs.iter();
+ it.seek(&PastRootsKeyFmt((h, Default::default())).encode_partial(1));
+
+ let mut result: BTreeMap<u64, RoundRoots> = BTreeMap::new();
+
+ for (round, value) in it.map_while(|(key, value)| {
+ PastRootsKeyFmt::decode(&key)
+ .filter(|PastRootsKeyFmt((ns, _))| ns == &h)
+ .map(|PastRootsKeyFmt((_, round))| (round, value))
+ }) {
+ result.insert(
+ round,
+ cbor::from_slice(&value).map_err(|err| StateError::Unavailable(anyhow!(err)))?,
+ );
+ }
+
+ Ok(result)
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use crate::storage::mkvs::{
+ interop::{Fixture, ProtocolServer},
+ Root, RootType, Tree,
+ };
+
+ use super::*;
+ #[test]
+ fn test_roothash_state_interop() {
+ // Keep in sync with go/consensus/cometbft/apps/roothash/state/interop/interop.go.
+ // If mock consensus state changes, update the root hash bellow.
+ // See protocol server stdout for hash.
+ // To make the hash show up during tests, run "cargo test" as
+ // "cargo test -- --nocapture".
+
+ // Setup protocol server with initialized mock consensus state.
+ let server = ProtocolServer::new(Fixture::ConsensusMock.into());
+ let mock_consensus_root = Root {
+ version: 1,
+ root_type: RootType::State,
+ hash: Hash::from("8e39bf193f8a954ab8f8d7cb6388c591fd0785ea060bbd8e3752e266b54499d3"),
+ ..Default::default()
+ };
+ let mkvs = Tree::builder()
+ .with_capacity(100_000, 10_000_000)
+ .with_root(mock_consensus_root)
+ .build(server.read_sync());
+ let state = ImmutableState::new(&mkvs);
+
+ let runtime_id =
+ Namespace::from("8000000000000000000000000000000000000000000000000000000000000010");
+
+ // Test fetching past round roots.
+ let past_round_roots = state
+ .past_round_roots(runtime_id)
+ .expect("past round roots query should work");
+ assert_eq!(
+ 10,
+ past_round_roots.len(),
+ "expected number of roots should match"
+ );
+ past_round_roots.iter().for_each(|(round, roots)| {
+ assert_eq!(
+ RoundRoots {
+ state_root: Hash::digest_bytes(format!("state {}", round).as_bytes()),
+ io_root: Hash::digest_bytes(format!("io {}", round).as_bytes())
+ },
+ *roots,
+ "expected roots should match"
+ );
+ });
+
+ // Test fetching latest round roots.
+ let round_roots = state
+ .round_roots(runtime_id, 100)
+ .expect("round roots query should work");
+ assert_eq!(None, round_roots, "round root should be missing");
+
+ let round_roots = state
+ .round_roots(runtime_id, 10)
+ .expect("round roots query should work");
+ assert_eq!(
+ Some(RoundRoots {
+ state_root: Hash::digest_bytes(format!("state {}", 10).as_bytes()),
+ io_root: Hash::digest_bytes(format!("io {}", 10).as_bytes())
+ }),
+ round_roots,
+ "round root should be missing"
+ );
+
+ // Test non-existing runtime.
+ let runtime_id =
+ Namespace::from("8000000000000000000000000000000000000000000000000000000000000000");
+ let past_round_roots = state
+ .past_round_roots(runtime_id)
+ .expect("past round roots query should work");
+ assert_eq!(
+ 0,
+ past_round_roots.len(),
+ "there should be no roots for non-existing runtime"
+ );
+ let round_roots = state
+ .round_roots(runtime_id, 10)
+ .expect("round roots query should work");
+ assert_eq!(
+ None, round_roots,
+ "round root should be missing for non-existing runtime"
+ )
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +
//! Staking state in the consensus layer.
+use std::collections::BTreeMap;
+
+use anyhow::anyhow;
+
+use crate::{
+ common::{
+ key_format::{KeyFormat, KeyFormatAtom},
+ quantity::Quantity,
+ },
+ consensus::{
+ address::Address,
+ beacon::EpochTime,
+ staking::{Account, DebondingDelegation, Delegation},
+ state::StateError,
+ },
+ key_format,
+ storage::mkvs::ImmutableMKVS,
+};
+
+/// Consensus staking state wrapper.
+pub struct ImmutableState<'a, T: ImmutableMKVS> {
+ mkvs: &'a T,
+}
+
+impl<'a, T: ImmutableMKVS> ImmutableState<'a, T> {
+ /// Constructs a new ImmutableMKVS.
+ pub fn new(mkvs: &'a T) -> ImmutableState<'a, T> {
+ ImmutableState { mkvs }
+ }
+}
+
+key_format!(AccountsKeyFmt, 0x50, Address);
+key_format!(TotalSupplyKeyFmt, 0x51, ());
+key_format!(CommonPoolKeyFmt, 0x52, ());
+key_format!(DelegationKeyFmt, 0x53, (Address, Address));
+key_format!(
+ DebondingDelegationKeyFmt,
+ 0x54,
+ (Address, Address, EpochTime)
+);
+key_format!(LastBlockFees, 0x57, ());
+key_format!(GovernanceDepositsKeyFmt, 0x59, ());
+
+impl<'a, T: ImmutableMKVS> ImmutableState<'a, T> {
+ /// Returns the staking account for the given account address.
+ pub fn account(&self, address: Address) -> Result<Account, StateError> {
+ match self.mkvs.get(&AccountsKeyFmt(address).encode()) {
+ Ok(Some(b)) => {
+ cbor::from_slice(&b).map_err(|err| StateError::Unavailable(anyhow!(err)))
+ }
+ Ok(None) => Ok(Account::default()),
+ Err(err) => Err(StateError::Unavailable(anyhow!(err))),
+ }
+ }
+
+ fn load_stored_balance<K: KeyFormat>(&self, key_format: K) -> Result<Quantity, StateError> {
+ match self.mkvs.get(&key_format.encode()) {
+ Ok(Some(b)) => {
+ cbor::from_slice(&b).map_err(|err| StateError::Unavailable(anyhow!(err)))
+ }
+ Ok(None) => Ok(Quantity::default()),
+ Err(err) => Err(StateError::Unavailable(anyhow!(err))),
+ }
+ }
+
+ /// Returns the total supply.
+ pub fn total_supply(&self) -> Result<Quantity, StateError> {
+ self.load_stored_balance(TotalSupplyKeyFmt(()))
+ }
+
+ /// Returns the balance of the global common pool.
+ pub fn common_pool(&self) -> Result<Quantity, StateError> {
+ self.load_stored_balance(CommonPoolKeyFmt(()))
+ }
+
+ /// Returns the last block fees balance.
+ pub fn last_block_fees(&self) -> Result<Quantity, StateError> {
+ self.load_stored_balance(LastBlockFees(()))
+ }
+
+ /// Returns the governance deposits balance.
+ pub fn governance_deposits(&self) -> Result<Quantity, StateError> {
+ self.load_stored_balance(GovernanceDepositsKeyFmt(()))
+ }
+
+ /// Returns the non-empty addresses from the staking ledger.
+ pub fn addresses(&self) -> Result<Vec<Address>, StateError> {
+ let mut it = self.mkvs.iter();
+ it.seek(&AccountsKeyFmt::default().encode_partial(0));
+
+ Ok(it
+ .map_while(|(key, _)| AccountsKeyFmt::decode(&key))
+ .map(|AccountsKeyFmt(addr)| addr)
+ .collect())
+ }
+
+ /// Returns the delegation.
+ pub fn delegation(
+ &self,
+ delegator_addr: Address,
+ escrow_addr: Address,
+ ) -> Result<Delegation, StateError> {
+ match self
+ .mkvs
+ .get(&DelegationKeyFmt((escrow_addr, delegator_addr)).encode())
+ {
+ Ok(Some(b)) => {
+ cbor::from_slice(&b).map_err(|err| StateError::Unavailable(anyhow!(err)))
+ }
+ Ok(None) => Ok(Delegation::default()),
+ Err(err) => Err(StateError::Unavailable(anyhow!(err))),
+ }
+ }
+
+ /// Returns all active delegations.
+ pub fn delegations(
+ &self,
+ ) -> Result<BTreeMap<Address, BTreeMap<Address, Delegation>>, StateError> {
+ let mut it = self.mkvs.iter();
+ it.seek(&DelegationKeyFmt::default().encode_partial(0));
+
+ let mut result: BTreeMap<Address, BTreeMap<Address, Delegation>> = BTreeMap::new();
+
+ while let Some((DelegationKeyFmt((escrow_addr, delegator_addr)), value)) = it
+ .next()
+ .and_then(|(key, value)| DelegationKeyFmt::decode(&key).zip(value.into()))
+ {
+ if !result.contains_key(&escrow_addr) {
+ result.insert(escrow_addr.clone(), BTreeMap::new());
+ }
+ let inner = result.get_mut(&escrow_addr).expect("inner map must exist");
+
+ inner.insert(
+ delegator_addr,
+ cbor::from_slice(&value).map_err(|err| StateError::Unavailable(anyhow!(err)))?,
+ );
+ }
+
+ Ok(result)
+ }
+
+ /// Returns the debonding delegation.
+ pub fn debonding_delegation(
+ &self,
+ delegator_addr: Address,
+ escrow_addr: Address,
+ epoch: EpochTime,
+ ) -> Result<DebondingDelegation, StateError> {
+ match self
+ .mkvs
+ .get(&DebondingDelegationKeyFmt((delegator_addr, escrow_addr, epoch)).encode())
+ {
+ Ok(Some(b)) => {
+ cbor::from_slice(&b).map_err(|err| StateError::Unavailable(anyhow!(err)))
+ }
+ Ok(None) => Ok(DebondingDelegation::default()),
+ Err(err) => Err(StateError::Unavailable(anyhow!(err))),
+ }
+ }
+
+ /// Returns all debonding delegations.
+ pub fn debonding_delegations(
+ &self,
+ ) -> Result<BTreeMap<Address, BTreeMap<Address, Vec<DebondingDelegation>>>, StateError> {
+ let mut it = self.mkvs.iter();
+ it.seek(&DebondingDelegationKeyFmt::default().encode_partial(0));
+
+ let mut result: BTreeMap<Address, BTreeMap<Address, Vec<DebondingDelegation>>> =
+ BTreeMap::new();
+
+ while let Some((DebondingDelegationKeyFmt((delegator_addr, escrow_addr, _)), value)) = it
+ .next()
+ .and_then(|(key, value)| DebondingDelegationKeyFmt::decode(&key).zip(value.into()))
+ {
+ if !result.contains_key(&escrow_addr) {
+ result.insert(escrow_addr.clone(), BTreeMap::new());
+ }
+ let inner = result.get_mut(&escrow_addr).expect("inner map must exist");
+ if !inner.contains_key(&delegator_addr) {
+ inner.insert(delegator_addr.clone(), Vec::new());
+ }
+ let in_inner = inner
+ .get_mut(&delegator_addr)
+ .expect("inner vec in inner map must exist");
+ in_inner.push(
+ cbor::from_slice(&value).map_err(|err| StateError::Unavailable(anyhow!(err)))?,
+ );
+ }
+
+ Ok(result)
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use crate::{
+ common::crypto::{hash::Hash, signature::PublicKey},
+ consensus::staking::{EscrowAccount, GeneralAccount, SharePool},
+ storage::mkvs::{
+ interop::{Fixture, ProtocolServer},
+ Root, RootType, Tree,
+ },
+ };
+
+ use super::*;
+
+ #[test]
+ fn test_staking_state_interop() {
+ // Keep in sync with go/consensus/cometbft/apps/staking/state/interop/interop.go.
+ // If mock consensus state changes, update the root hash bellow.
+ // See protocol server stdout for hash.
+ // To make the hash show up during tests, run "cargo test" as
+ // "cargo test -- --nocapture".
+
+ // Setup protocol server with initialized mock consensus state.
+ let server = ProtocolServer::new(Fixture::ConsensusMock.into());
+ let mock_consensus_root = Root {
+ version: 1,
+ root_type: RootType::State,
+ hash: Hash::from("8e39bf193f8a954ab8f8d7cb6388c591fd0785ea060bbd8e3752e266b54499d3"),
+ ..Default::default()
+ };
+ let mkvs = Tree::builder()
+ .with_capacity(100_000, 10_000_000)
+ .with_root(mock_consensus_root)
+ .build(server.read_sync());
+ let staking_state = ImmutableState::new(&mkvs);
+
+ let pk =
+ PublicKey::from("7e57baaad01fffffffffffffffffffffffffffffffffffffffffffffffffffff");
+ let pk2 =
+ PublicKey::from("7e57baaad02fffffffffffffffffffffffffffffffffffffffffffffffffffff");
+ let pk3 =
+ PublicKey::from("7e57baaad03fffffffffffffffffffffffffffffffffffffffffffffffffffff");
+ let expected_addrs = vec![
+ Address::from_pk(&pk),
+ Address::from_pk(&pk2),
+ Address::from_pk(&pk3),
+ ];
+
+ // Test all addresses and accounts.
+ let addrs = staking_state
+ .addresses()
+ .expect("addresses query should work");
+ assert_eq!(expected_addrs, addrs, "expected addresses should match");
+
+ let mut accounts = Vec::new();
+ for addr in &addrs {
+ let acc = staking_state
+ .account(addr.clone())
+ .expect("accounts query should work");
+ accounts.push(acc);
+ }
+
+ let expected_accounts = vec![
+ Account {
+ general: GeneralAccount {
+ balance: Quantity::from(23u32),
+ nonce: 13,
+ ..Default::default()
+ },
+ escrow: EscrowAccount {
+ active: SharePool {
+ balance: Quantity::from(100u32),
+ total_shares: Quantity::from(10u32),
+ },
+ debonding: SharePool {
+ balance: Quantity::from(5u32),
+ total_shares: Quantity::from(5u32),
+ },
+ ..Default::default()
+ },
+ ..Default::default()
+ },
+ Account {
+ general: GeneralAccount {
+ balance: Quantity::from(23u32),
+ nonce: 1,
+ ..Default::default()
+ },
+ escrow: EscrowAccount {
+ active: SharePool {
+ balance: Quantity::from(500u32),
+ total_shares: Quantity::from(5u32),
+ },
+ ..Default::default()
+ },
+ ..Default::default()
+ },
+ Account {
+ general: GeneralAccount {
+ balance: Quantity::from(113u32),
+ nonce: 17,
+ ..Default::default()
+ },
+ escrow: EscrowAccount {
+ active: SharePool {
+ balance: Quantity::from(400u32),
+ total_shares: Quantity::from(35u32),
+ },
+ ..Default::default()
+ },
+ ..Default::default()
+ },
+ ];
+ assert_eq!(
+ expected_accounts, accounts,
+ "expected addresses should match"
+ );
+
+ // Test all delegations.
+ let delegations = staking_state
+ .delegations()
+ .expect("delegations query should work");
+ for (escrow_addr, dels) in &delegations {
+ for (delegator_addr, del) in dels.clone() {
+ let d = staking_state
+ .delegation(delegator_addr, escrow_addr.clone())
+ .expect("delegation query should work");
+ assert_eq!(del, d, "delegation should match")
+ }
+ }
+
+ let mut expected_delegations: BTreeMap<Address, BTreeMap<Address, Delegation>> =
+ BTreeMap::new();
+ // Delegations to address[0].
+ expected_delegations.insert(
+ addrs[0].clone(),
+ [
+ (
+ addrs[0].clone(),
+ Delegation {
+ shares: Quantity::from(5u32),
+ },
+ ),
+ (
+ addrs[1].clone(),
+ Delegation {
+ shares: Quantity::from(5u32),
+ },
+ ),
+ ]
+ .iter()
+ .cloned()
+ .collect(),
+ );
+ // Delegations to address[1].
+ expected_delegations.insert(
+ addrs[1].clone(),
+ [(
+ addrs[2].clone(),
+ Delegation {
+ shares: Quantity::from(5u32),
+ },
+ )]
+ .iter()
+ .cloned()
+ .collect(),
+ );
+ // Delegations to address[2].
+ expected_delegations.insert(
+ addrs[2].clone(),
+ [
+ (
+ addrs[0].clone(),
+ Delegation {
+ shares: Quantity::from(20u32),
+ },
+ ),
+ (
+ addrs[1].clone(),
+ Delegation {
+ shares: Quantity::from(6u32),
+ },
+ ),
+ (
+ addrs[2].clone(),
+ Delegation {
+ shares: Quantity::from(10u32),
+ },
+ ),
+ ]
+ .iter()
+ .cloned()
+ .collect(),
+ );
+ assert_eq!(
+ expected_delegations, delegations,
+ "expected delegations should match"
+ );
+
+ // Test all debonding delegations.
+ let debonding_delegations = staking_state
+ .debonding_delegations()
+ .expect("debonding delegations query should work");
+ for (escrow_addr, debss) in &debonding_delegations {
+ for (delegator_addr, debs) in debss {
+ for deb in debs {
+ let d = staking_state
+ .debonding_delegation(
+ delegator_addr.clone(),
+ escrow_addr.clone(),
+ deb.debond_end_time,
+ )
+ .expect("debonding delegation query should work");
+ assert_eq!(deb.clone(), d, "debonding delegation should match")
+ }
+ }
+ }
+ let mut expected_debonding: BTreeMap<Address, BTreeMap<Address, Vec<DebondingDelegation>>> =
+ BTreeMap::new();
+ // Debonding delegations in address[0].
+ expected_debonding.insert(
+ addrs[0].clone(),
+ [
+ (
+ addrs[0].clone(),
+ vec![DebondingDelegation {
+ shares: Quantity::from(1u32),
+ debond_end_time: 33,
+ }],
+ ),
+ (
+ addrs[1].clone(),
+ vec![
+ DebondingDelegation {
+ shares: Quantity::from(1u32),
+ debond_end_time: 15,
+ },
+ DebondingDelegation {
+ shares: Quantity::from(1u32),
+ debond_end_time: 21,
+ },
+ ],
+ ),
+ (
+ addrs[2].clone(),
+ vec![DebondingDelegation {
+ shares: Quantity::from(2u32),
+ debond_end_time: 100,
+ }],
+ ),
+ ]
+ .iter()
+ .cloned()
+ .collect(),
+ );
+ assert_eq!(
+ expected_debonding, debonding_delegations,
+ "expected debonding delegations should match"
+ );
+
+ // Test all stored balances.
+ let total_supply = staking_state
+ .total_supply()
+ .expect("total supply query should work");
+ assert_eq!(
+ Quantity::from(10000u32),
+ total_supply,
+ "total supply should match expected"
+ );
+
+ let common_pool = staking_state
+ .common_pool()
+ .expect("common pool query should work");
+ assert_eq!(
+ Quantity::from(1000u32),
+ common_pool,
+ "common pool should match expected"
+ );
+
+ let last_block_fees = staking_state
+ .last_block_fees()
+ .expect("last block fees query should work");
+ assert_eq!(
+ Quantity::from(33u32),
+ last_block_fees,
+ "last block fees should match expected"
+ );
+
+ let governance_deposits = staking_state
+ .governance_deposits()
+ .expect("governance deposits query should work");
+ assert_eq!(
+ Quantity::from(12u32),
+ governance_deposits,
+ "governance deposits should match expected"
+ );
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +
//! Merkle proofs used in Tendermint networks
+//!
+//! Rewritten to Rust from:
+//! https://github.com/tendermint/tendermint/blob/main/crypto/merkle/proof.go
+//!
+//! Helper functions copied from:
+//! https://github.com/informalsystems/tendermint-rs/blob/main/tendermint/src/merkle.rs
+
+use std::cmp::Ordering;
+
+use anyhow::{anyhow, Result};
+use rustc_hex::ToHex;
+use sha2::{Digest, Sha256};
+
+use tendermint::merkle::{Hash, HASH_SIZE};
+
+/// Maximum number of aunts that can be included in a Proof.
+/// This corresponds to a tree of size 2^100, which should be sufficient for all conceivable purposes.
+/// This maximum helps prevent Denial-of-Service attacks by limiting the size of the proofs.
+pub const MAX_AUNTS: usize = 100;
+
+/// Proof represents a Merkle proof.
+///
+/// NOTE: The convention for proofs is to include leaf hashes but to
+/// exclude the root hash.
+/// This convention is implemented across IAVL range proofs as well.
+/// Keep this consistent unless there's a very good reason to change
+/// everything. This also affects the generalized proof system as
+/// well.
+#[derive(Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Proof {
+ pub total: i64, // Total number of items.
+ pub index: i64, // Index of item to prove.
+ pub leaf_hash: Hash, // Hash of item value.
+ pub aunts: Vec<Hash>, // Hashes from leaf's sibling to a root's child.
+}
+
+impl Proof {
+ /// Verify that the Proof proves the root hash.
+ /// Check index/total manually if needed.
+ pub fn verify(&self, root_hash: Hash, leaf: Hash) -> Result<()> {
+ if self.total < 0 {
+ return Err(anyhow!("proof total must be positive"));
+ }
+ if self.index < 0 {
+ return Err(anyhow!("proof index cannot be negative"));
+ }
+ if self.aunts.len() > MAX_AUNTS {
+ return Err(anyhow!(
+ "expected no more than {} aunts, got {}",
+ MAX_AUNTS,
+ self.aunts.len()
+ ));
+ }
+
+ let leaf_hash = leaf_hash(&leaf);
+ match self.leaf_hash.cmp(&leaf_hash) {
+ Ordering::Equal => (),
+ _ => {
+ return Err(anyhow!(
+ "invalid leaf hash: wanted {} got {}",
+ leaf_hash.to_hex::<String>(),
+ self.leaf_hash.to_hex::<String>(),
+ ));
+ }
+ }
+
+ let computed_hash = self.compute_root_hash().ok_or_else(|| {
+ anyhow!(
+ "invalid root hash: wanted {} got None",
+ root_hash.to_hex::<String>()
+ )
+ })?;
+ match computed_hash.cmp(&root_hash) {
+ Ordering::Equal => (),
+ _ => {
+ return Err(anyhow!(
+ "invalid root hash: wanted {} got {}",
+ root_hash.to_hex::<String>(),
+ computed_hash.to_hex::<String>(),
+ ));
+ }
+ }
+
+ Ok(())
+ }
+
+ /// Compute the root hash given a leaf hash. Does not verify the result.
+ pub fn compute_root_hash(&self) -> Option<Hash> {
+ Self::compute_hash_from_aunts(self.index, self.total, self.leaf_hash, &self.aunts)
+ }
+
+ /// Use the leaf_hash and inner_hashes to get the root merkle hash.
+ /// If the length of the inner_hashes slice isn't exactly correct, the result is None.
+ /// Recursive impl.
+ fn compute_hash_from_aunts(
+ index: i64,
+ total: i64,
+ leaf_hash: Hash,
+ inner_hashes: &[Hash],
+ ) -> Option<Hash> {
+ if index >= total || index < 0 || total <= 0 {
+ return None;
+ }
+ match total {
+ 0 => unreachable!("cannot call compute_hash_from_aunts() with 0 total"), // Handled above.
+ 1 => {
+ if !inner_hashes.is_empty() {
+ return None;
+ }
+ Some(leaf_hash)
+ }
+ _ => {
+ if inner_hashes.is_empty() {
+ return None;
+ }
+ let last_idx = inner_hashes.len() - 1;
+ let last_hash = inner_hashes[last_idx];
+ let inner_hashes = &inner_hashes[..last_idx];
+
+ let num_left = get_split_point(total as usize) as i64;
+ if index < num_left {
+ if let Some(left_hash) =
+ Self::compute_hash_from_aunts(index, num_left, leaf_hash, inner_hashes)
+ {
+ return Some(inner_hash(&left_hash, &last_hash));
+ }
+ return None;
+ }
+ if let Some(right_hash) = Self::compute_hash_from_aunts(
+ index - num_left,
+ total - num_left,
+ leaf_hash,
+ inner_hashes,
+ ) {
+ return Some(inner_hash(&last_hash, &right_hash));
+ }
+ None
+ }
+ }
+ }
+}
+
+/// returns the largest power of 2 less than length
+fn get_split_point(length: usize) -> usize {
+ match length {
+ 0 => panic!("tree is empty!"),
+ 1 => panic!("tree has only one element!"),
+ 2 => 1,
+ _ => length.next_power_of_two() / 2,
+ }
+}
+
+/// tmhash(0x00 || leaf)
+fn leaf_hash(bytes: &[u8]) -> Hash {
+ // make a new array starting with 0 and copy in the bytes
+ let mut leaf_bytes = Vec::with_capacity(bytes.len() + 1);
+ leaf_bytes.push(0x00);
+ leaf_bytes.extend_from_slice(bytes);
+
+ // hash it !
+ let digest = Sha256::digest(&leaf_bytes);
+
+ // copy the GenericArray out
+ let mut hash_bytes = [0u8; HASH_SIZE];
+ hash_bytes.copy_from_slice(&digest);
+ hash_bytes
+}
+
+/// tmhash(0x01 || left || right)
+fn inner_hash(left: &[u8], right: &[u8]) -> Hash {
+ // make a new array starting with 0x1 and copy in the bytes
+ let mut inner_bytes = Vec::with_capacity(left.len() + right.len() + 1);
+ inner_bytes.push(0x01);
+ inner_bytes.extend_from_slice(left);
+ inner_bytes.extend_from_slice(right);
+
+ // hash it !
+ let digest = Sha256::digest(&inner_bytes);
+
+ // copy the GenericArray out
+ let mut hash_bytes = [0u8; HASH_SIZE];
+ hash_bytes.copy_from_slice(&digest);
+ hash_bytes
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +
//! Tendermint consensus layer backend.
+
+pub mod merkle;
+pub mod verifier;
+
+use std::convert::{TryFrom, TryInto};
+
+use anyhow::{anyhow, Result};
+use tendermint::{
+ block::signed_header::SignedHeader as TMSignedHeader, chain, validator::Set as TMValidatorSet,
+};
+use tendermint_proto::{types::LightBlock as RawLightBlock, Protobuf};
+
+use crate::{
+ common::{crypto::hash::Hash, namespace::Namespace},
+ consensus::LightBlock,
+ storage::mkvs::{Root, RootType},
+};
+
+/// Tendermint consensus backend name.
+/// Keep synced with go/consensus/cometbft/api/api.go.
+pub const BACKEND_NAME: &str = "tendermint";
+
+/// The domain separation context used by Oasis Core for Tendermint cryptography.
+/// Keep synced with go/consensus/cometbft/crypto/signature.go.
+pub const TENDERMINT_CONTEXT: &[u8] = b"oasis-core/tendermint";
+
+/// Convert an Oasis Core chain context into a Tendermint chain ID.
+pub fn chain_id(chain_context: &str) -> chain::Id {
+ chain_context[..chain::id::MAX_LENGTH].try_into().unwrap()
+}
+
+/// Decode the light block metadata as a Tendermint light block.
+pub fn decode_light_block(light_block: LightBlock) -> Result<LightBlockMeta> {
+ LightBlockMeta::decode_vec(&light_block.meta).map_err(|e| anyhow!("{}", e))
+}
+
+/// Encode the light block metadata to a Tendermint light block.
+pub fn encode_light_block(light_block_meta: LightBlockMeta) -> Result<LightBlock> {
+ let height = u64::from(
+ light_block_meta
+ .signed_header
+ .as_ref()
+ .ok_or_else(|| anyhow!("signed header should be present"))?
+ .header
+ .height,
+ );
+ let meta = LightBlockMeta::encode_vec(light_block_meta);
+
+ Ok(LightBlock { height, meta })
+}
+
+/// Extract state root from the given signed block header.
+///
+/// # Panics
+///
+/// The signed header must be present and the application hash must be a valid Oasis Core
+/// application hash (state root hash).
+pub fn state_root_from_header(signed_header: &TMSignedHeader) -> Root {
+ let header = signed_header.header();
+ let height: u64 = header.height.into();
+ let hash: [u8; 32] = header
+ .app_hash
+ .as_bytes()
+ .try_into()
+ .expect("invalid app hash");
+
+ Root {
+ namespace: Namespace::default(),
+ version: height - 1,
+ root_type: RootType::State,
+ hash: Hash(hash),
+ }
+}
+
+/// Tendermint light consensus block metadata.
+#[derive(Debug, Clone)]
+pub struct LightBlockMeta {
+ pub signed_header: Option<TMSignedHeader>,
+ pub validators: TMValidatorSet,
+}
+
+impl LightBlockMeta {
+ /// State root specified by this light block.
+ ///
+ /// # Panics
+ ///
+ /// The signed header must be present and the application hash must be a valid Oasis Core
+ /// application hash (state root hash).
+ pub fn get_state_root(&self) -> Root {
+ let header = self
+ .signed_header
+ .as_ref()
+ .expect("signed header should be present");
+
+ state_root_from_header(header)
+ }
+}
+
+impl Protobuf<RawLightBlock> for LightBlockMeta {}
+
+impl TryFrom<RawLightBlock> for LightBlockMeta {
+ type Error = anyhow::Error;
+
+ fn try_from(value: RawLightBlock) -> Result<Self> {
+ Ok(LightBlockMeta {
+ signed_header: value
+ .signed_header
+ .map(TryInto::try_into)
+ .transpose()
+ .map_err(|error| anyhow!("{}", error))?,
+ validators: value
+ .validator_set
+ .ok_or_else(|| anyhow!("missing validator set"))?
+ .try_into()
+ .map_err(|error| anyhow!("{}", error))?,
+ })
+ }
+}
+
+impl From<LightBlockMeta> for RawLightBlock {
+ fn from(value: LightBlockMeta) -> Self {
+ RawLightBlock {
+ signed_header: value.signed_header.map(Into::into),
+ validator_set: Some(value.validators.into()),
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +
use std::num::NonZeroUsize;
+
+use tendermint::block::Height;
+use tendermint_light_client::types::LightBlock as TMLightBlock;
+
+use crate::common::crypto::{hash::Hash, signature::PublicKey};
+
+/// Verifier cache.
+pub struct Cache {
+ pub last_verified_height: u64,
+ pub last_verified_round: u64,
+ pub last_verified_epoch: u64,
+ pub last_verified_block: Option<TMLightBlock>,
+ pub verified_state_roots: lru::LruCache<u64, (Hash, u64)>,
+ pub host_node_id: PublicKey,
+}
+
+impl Cache {
+ /// Latest known and verified consensus layer height.
+ pub fn latest_known_height(&self) -> Option<u64> {
+ self.last_verified_block
+ .as_ref()
+ .map(|b| b.signed_header.header.height.value())
+ }
+
+ /// Process a new verified consensus layer block and update the cache if needed.
+ pub fn update_verified_block(&mut self, verified_block: &TMLightBlock) {
+ let h = |b: &TMLightBlock| -> Height { b.signed_header.header.height };
+ if let Some(last_verified_block) = self.last_verified_block.as_ref() {
+ if h(verified_block) <= h(last_verified_block) {
+ return;
+ }
+ }
+ self.last_verified_block = Some(verified_block.clone())
+ }
+}
+
+impl Cache {
+ /// Construct a new verifier cache.
+ pub fn new(host_node_id: PublicKey) -> Self {
+ Self {
+ last_verified_height: 0,
+ last_verified_round: 0,
+ last_verified_epoch: 0,
+ last_verified_block: None,
+ verified_state_roots: lru::LruCache::new(NonZeroUsize::new(128).unwrap()),
+ host_node_id,
+ }
+ }
+}
+use tendermint_light_client::{components, types::Time};
+
+use crate::common::time;
+
+pub struct InsecureClock;
+
+impl components::clock::Clock for InsecureClock {
+ fn now(&self) -> Time {
+ Time::from_unix_timestamp(time::insecure_posix_time(), 0).unwrap()
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +
use std::sync::Arc;
+
+use async_trait::async_trait;
+use crossbeam::channel;
+use tokio::sync::oneshot;
+
+use crate::{
+ consensus::{
+ beacon::EpochTime,
+ roothash::Header,
+ state::ConsensusState,
+ tendermint::decode_light_block,
+ verifier::{self, Error},
+ Event, LightBlock,
+ },
+ protocol::Protocol,
+ types::EventKind,
+};
+
+use super::types::Command;
+
+pub struct Handle {
+ pub protocol: Arc<Protocol>,
+ pub command_sender: channel::Sender<Command>,
+}
+
+#[async_trait]
+impl verifier::Verifier for Handle {
+ async fn sync(&self, height: u64) -> Result<(), Error> {
+ let (sender, receiver) = oneshot::channel();
+ self.command_sender
+ .send(Command::Synchronize(height, sender))
+ .map_err(|_| Error::Internal)?;
+
+ receiver.await.map_err(|_| Error::Internal)?
+ }
+
+ async fn verify(
+ &self,
+ consensus_block: LightBlock,
+ runtime_header: Header,
+ epoch: EpochTime,
+ ) -> Result<ConsensusState, Error> {
+ let (sender, receiver) = oneshot::channel();
+ self.command_sender
+ .send(Command::Verify(
+ consensus_block,
+ runtime_header,
+ epoch,
+ sender,
+ false,
+ ))
+ .map_err(|_| Error::Internal)?;
+
+ receiver.await.map_err(|_| Error::Internal)?
+ }
+
+ async fn verify_for_query(
+ &self,
+ consensus_block: LightBlock,
+ runtime_header: Header,
+ epoch: EpochTime,
+ ) -> Result<ConsensusState, Error> {
+ let (sender, receiver) = oneshot::channel();
+ self.command_sender
+ .send(Command::Verify(
+ consensus_block,
+ runtime_header,
+ epoch,
+ sender,
+ true,
+ ))
+ .map_err(|_| Error::Internal)?;
+
+ receiver.await.map_err(|_| Error::Internal)?
+ }
+
+ async fn unverified_state(&self, consensus_block: LightBlock) -> Result<ConsensusState, Error> {
+ let untrusted_block =
+ decode_light_block(consensus_block).map_err(Error::VerificationFailed)?;
+ // NOTE: No actual verification is performed.
+ let state_root = untrusted_block.get_state_root();
+ Ok(ConsensusState::from_protocol(
+ self.protocol.clone(),
+ state_root.version + 1,
+ state_root,
+ ))
+ }
+
+ async fn latest_state(&self) -> Result<ConsensusState, Error> {
+ let (sender, receiver) = oneshot::channel();
+ self.command_sender
+ .send(Command::LatestState(sender))
+ .map_err(|_| Error::Internal)?;
+
+ receiver.await.map_err(|_| Error::Internal)?
+ }
+
+ async fn state_at(&self, height: u64) -> Result<ConsensusState, Error> {
+ let (sender, receiver) = oneshot::channel();
+ self.command_sender
+ .send(Command::StateAt(height, sender))
+ .map_err(|_| Error::Internal)?;
+
+ receiver.await.map_err(|_| Error::Internal)?
+ }
+
+ async fn events_at(&self, height: u64, kind: EventKind) -> Result<Vec<Event>, Error> {
+ let (sender, receiver) = oneshot::channel();
+ self.command_sender
+ .send(Command::EventsAt(height, kind, sender))
+ .map_err(|_| Error::Internal)?;
+
+ receiver.await.map_err(|_| Error::Internal)?
+ }
+
+ async fn latest_height(&self) -> Result<u64, Error> {
+ let (sender, receiver) = oneshot::channel();
+ self.command_sender
+ .send(Command::LatestHeight(sender))
+ .map_err(|_| Error::Internal)?;
+
+ receiver.await.map_err(|_| Error::Internal)?
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +
use std::sync::Arc;
+
+use tendermint_light_client::{
+ components::{
+ self,
+ io::{AtHeight, IoError},
+ },
+ types::{LightBlock as TMLightBlock, PeerId},
+};
+use tendermint_rpc::error::Error as RpcError;
+
+use crate::{
+ consensus::{
+ tendermint::{decode_light_block, LightBlockMeta},
+ transaction::SignedTransactionWithProof,
+ HEIGHT_LATEST,
+ },
+ protocol::Protocol,
+ types::Body,
+};
+
+use super::types::Nonce;
+
+pub struct Io {
+ protocol: Arc<Protocol>,
+}
+
+impl Io {
+ pub fn new(protocol: &Arc<Protocol>) -> Self {
+ Self {
+ protocol: protocol.clone(),
+ }
+ }
+
+ fn fetch_light_block(&self, height: u64) -> Result<LightBlockMeta, IoError> {
+ let result = self
+ .protocol
+ .call_host(Body::HostFetchConsensusBlockRequest { height })
+ .map_err(|err| IoError::rpc(RpcError::server(err.to_string())))?;
+
+ // Extract generic light block from response.
+ let block = match result {
+ Body::HostFetchConsensusBlockResponse { block } => block,
+ _ => return Err(IoError::rpc(RpcError::server("bad response".to_string()))),
+ };
+
+ // Decode block as a Tendermint light block.
+ let block = decode_light_block(block)
+ .map_err(|err| IoError::rpc(RpcError::server(err.to_string())))?;
+
+ Ok(block)
+ }
+
+ pub fn fetch_genesis_height(&self) -> Result<u64, IoError> {
+ let result = self
+ .protocol
+ .call_host(Body::HostFetchGenesisHeightRequest {})
+ .map_err(|err| IoError::rpc(RpcError::server(err.to_string())))?;
+
+ // Extract genesis height from response.
+ let height = match result {
+ Body::HostFetchGenesisHeightResponse { height } => height,
+ _ => return Err(IoError::rpc(RpcError::server("bad response".to_string()))),
+ };
+
+ Ok(height)
+ }
+
+ pub fn fetch_freshness_proof(
+ &self,
+ nonce: &Nonce,
+ ) -> Result<SignedTransactionWithProof, IoError> {
+ let result = self
+ .protocol
+ .call_host(Body::HostProveFreshnessRequest {
+ blob: nonce.to_vec(),
+ })
+ .map_err(|err| IoError::rpc(RpcError::server(err.to_string())))?;
+
+ // Extract proof from response.
+ let (signed_tx, proof) = match result {
+ Body::HostProveFreshnessResponse { signed_tx, proof } => (signed_tx, proof),
+ _ => return Err(IoError::rpc(RpcError::server("bad response".to_string()))),
+ };
+
+ Ok(SignedTransactionWithProof { signed_tx, proof })
+ }
+
+ pub fn fetch_block_metadata(&self, height: u64) -> Result<SignedTransactionWithProof, IoError> {
+ let result = self
+ .protocol
+ .call_host(Body::HostFetchBlockMetadataTxRequest { height })
+ .map_err(|err| IoError::rpc(RpcError::server(err.to_string())))?;
+
+ // Extract proof from response.
+ let (signed_tx, proof) = match result {
+ Body::HostFetchBlockMetadataTxResponse { signed_tx, proof } => (signed_tx, proof),
+ _ => return Err(IoError::rpc(RpcError::server("bad response".to_string()))),
+ };
+
+ Ok(SignedTransactionWithProof { signed_tx, proof })
+ }
+}
+
+impl components::io::Io for Io {
+ fn fetch_light_block(&self, height: AtHeight) -> Result<TMLightBlock, IoError> {
+ let height = match height {
+ AtHeight::At(height) => height.into(),
+ AtHeight::Highest => HEIGHT_LATEST,
+ };
+
+ // Fetch light block at height and height+1.
+ let block = Io::fetch_light_block(self, height)?;
+ let height: u64 = block
+ .signed_header
+ .as_ref()
+ .ok_or_else(|| IoError::rpc(RpcError::server("missing signed header".to_string())))?
+ .header()
+ .height
+ .into();
+ // NOTE: It seems that the requirement to fetch the next validator set is redundant and it
+ // should be handled at a higher layer of the light client.
+ let next_block = Io::fetch_light_block(self, height + 1)?;
+
+ Ok(TMLightBlock {
+ signed_header: block.signed_header.unwrap(), // Checked above.
+ validators: block.validators,
+ next_validators: next_block.validators,
+ provider: PeerId::new([0; 20]),
+ })
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +765 +766 +767 +768 +769 +770 +771 +772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805 +806 +807 +808 +809 +810 +811 +812 +813 +814 +815 +816 +817 +818 +819 +820 +821 +822 +823 +824 +825 +826 +827 +828 +829 +830 +831 +832 +833 +834 +835 +836 +837 +838 +839 +840 +841 +842 +843 +844 +845 +846 +847 +848 +849 +850 +851 +852 +853 +854 +855 +856 +857 +858 +859 +860 +861 +862 +863 +864 +865 +866 +867 +868 +869 +870 +871 +872 +873 +874 +875 +876 +877 +878 +879 +880 +881 +882 +883 +884 +885 +886 +887 +888 +889 +890 +891 +892 +893 +894 +895 +896 +897 +898 +899 +900 +901 +902 +903 +904 +905 +906 +907 +908 +909 +910 +911 +912 +913 +914 +915 +916 +917 +918 +919 +920 +921 +922 +923 +924 +925 +
//! Tendermint consensus layer verification logic.
+use std::{convert::TryInto, str::FromStr, sync::Arc, time::Duration};
+
+use anyhow::anyhow;
+use crossbeam::channel;
+use rand::{rngs::OsRng, Rng};
+use sha2::{Digest, Sha256};
+use slog::{debug, error, info};
+use tendermint::merkle::HASH_SIZE;
+use tendermint_light_client::{
+ builder::LightClientBuilder,
+ components::{self, io::AtHeight, verifier::PredicateVerifier},
+ instance::Instance,
+ light_client,
+ operations::{ProdCommitValidator, ProvidedVotingPowerCalculator},
+ store::LightStore,
+ types::{
+ Hash as TMHash, LightBlock as TMLightBlock, PeerId, Status, Time, TrustThreshold,
+ TrustedBlockState,
+ },
+ verifier::{predicates::ProdPredicates, Verdict, Verifier as TMVerifier},
+};
+
+use crate::{
+ common::{logger::get_logger, namespace::Namespace, process, time, version::Version},
+ consensus::{
+ beacon::EpochTime,
+ registry::METHOD_PROVE_FRESHNESS,
+ roothash::Header,
+ state::ConsensusState,
+ tendermint::{
+ chain_id, decode_light_block, merkle, state_root_from_header,
+ verifier::{
+ clock::InsecureClock,
+ io::Io,
+ store::LruStore,
+ types::{Command, Nonce, NONCE_SIZE},
+ },
+ LightBlockMeta,
+ },
+ transaction::{Proof, SignedTransaction, Transaction},
+ verifier::{self, verify_state_freshness, Error, TrustRoot},
+ BlockMetadata, Event, LightBlock, HEIGHT_LATEST, METHOD_META,
+ },
+ future::block_on,
+ host::Host,
+ protocol::Protocol,
+ storage::mkvs::{Root, RootType},
+ types::{Body, EventKind, HostFetchConsensusEventsRequest, HostFetchConsensusEventsResponse},
+};
+
+use self::{
+ cache::Cache,
+ handle::Handle,
+ store::{TrustedState, TrustedStateStore},
+};
+
+// Modules.
+mod cache;
+mod clock;
+mod handle;
+mod io;
+mod noop;
+mod predicates;
+mod signature;
+mod store;
+mod types;
+
+// Re-exports.
+pub use noop::NopVerifier;
+
+/// Maximum number of times to retry initialization.
+const MAX_INITIALIZATION_RETRIES: usize = 3;
+
+/// Trusted state save interval (in consensus blocks).
+const TRUSTED_STATE_SAVE_INTERVAL: u64 = 128;
+
+/// Tendermint consensus layer verifier.
+pub struct Verifier {
+ logger: slog::Logger,
+ protocol: Arc<Protocol>,
+ tokio_runtime: tokio::runtime::Handle,
+ runtime_version: Version,
+ runtime_id: Namespace,
+ chain_context: String,
+ trust_root: TrustRoot,
+ command_sender: channel::Sender<Command>,
+ command_receiver: channel::Receiver<Command>,
+ trusted_state_store: TrustedStateStore,
+}
+
+impl Verifier {
+ /// Create a new Tendermint consensus layer verifier.
+ pub fn new(
+ protocol: Arc<Protocol>,
+ tokio_runtime: tokio::runtime::Handle,
+ trust_root: TrustRoot,
+ runtime_id: Namespace,
+ chain_context: String,
+ ) -> Self {
+ let logger = get_logger("consensus/cometbft/verifier");
+ let (command_sender, command_receiver) = channel::unbounded();
+ let runtime_version = protocol.get_config().version;
+ let trusted_state_store =
+ TrustedStateStore::new(runtime_id, chain_context.clone(), protocol.clone());
+
+ assert_eq!(
+ trust_root.runtime_id, runtime_id,
+ "trust root must have the same runtime id"
+ );
+
+ Self {
+ logger,
+ protocol,
+ tokio_runtime,
+ runtime_version,
+ runtime_id,
+ chain_context,
+ trust_root,
+ command_sender,
+ command_receiver,
+ trusted_state_store,
+ }
+ }
+
+ /// Return a handle to interact with the verifier.
+ pub fn handle(&self) -> impl verifier::Verifier {
+ Handle {
+ protocol: self.protocol.clone(),
+ command_sender: self.command_sender.clone(),
+ }
+ }
+
+ fn verify_to_target(
+ &self,
+ height: u64,
+ cache: &mut Cache,
+ instance: &mut Instance,
+ ) -> Result<TMLightBlock, Error> {
+ let verified_block = match height {
+ HEIGHT_LATEST => instance.light_client.verify_to_highest(&mut instance.state),
+ _ => instance
+ .light_client
+ .verify_to_target(height.try_into().unwrap(), &mut instance.state),
+ }
+ .map_err(|err| Error::VerificationFailed(err.into()))?;
+
+ // Clear verification trace as it could otherwise lead to infinite memory growth.
+ instance.state.verification_trace.clear();
+
+ cache.update_verified_block(&verified_block);
+ self.update_insecure_posix_time(&verified_block);
+
+ Ok(verified_block)
+ }
+
+ fn sync(&self, cache: &mut Cache, instance: &mut Instance, height: u64) -> Result<(), Error> {
+ if height < cache.last_verified_height || height < cache.latest_known_height().unwrap_or(0)
+ {
+ // Ignore requests for earlier heights.
+ return Ok(());
+ }
+ self.verify_to_target(height, cache, instance)?;
+ Ok(())
+ }
+
+ fn latest_consensus_state(
+ &self,
+ cache: &mut Cache,
+ instance: &mut Instance,
+ ) -> Result<ConsensusState, Error> {
+ // When latest state is requested we always perform same-block execution verification.
+ let height = self.latest_consensus_height(cache)?;
+ let state_root = self.state_root_from_metadata(cache, instance, height)?;
+
+ Ok(ConsensusState::from_protocol(
+ self.protocol.clone(),
+ state_root.version,
+ state_root,
+ ))
+ }
+
+ fn latest_consensus_height(&self, cache: &Cache) -> Result<u64, Error> {
+ let height = cache.latest_known_height().ok_or(Error::Internal)?;
+ Ok(height)
+ }
+
+ fn consensus_state_at(
+ &self,
+ cache: &mut Cache,
+ instance: &mut Instance,
+ height: u64,
+ ) -> Result<ConsensusState, Error> {
+ // Obtain an authoritative state root, either from the current block if it is already
+ // finalized or from the metadata transaction of the previous block.
+ let state_root = match self.verify_to_target(height, cache, instance) {
+ Ok(verified_block) => state_root_from_header(&verified_block.signed_header),
+ Err(_) => self.state_root_from_metadata(cache, instance, height - 1)?,
+ };
+
+ Ok(ConsensusState::from_protocol(
+ self.protocol.clone(),
+ state_root.version + 1,
+ state_root,
+ ))
+ }
+
+ fn verify_consensus_block(
+ &self,
+ cache: &mut Cache,
+ instance: &mut Instance,
+ consensus_block: LightBlock,
+ ) -> Result<LightBlockMeta, Error> {
+ // Decode passed block as a Tendermint block.
+ let lb_height = consensus_block.height;
+ let untrusted_block =
+ decode_light_block(consensus_block).map_err(Error::VerificationFailed)?;
+ let untrusted_header = untrusted_block
+ .signed_header
+ .as_ref()
+ .ok_or_else(|| Error::VerificationFailed(anyhow!("missing signed header")))?;
+
+ // Verify up to the block at current height.
+ // Only does forward verification and fails if height is lower than the last trust height.
+ let height = untrusted_header.header().height.value();
+ if height != lb_height {
+ return Err(Error::VerificationFailed(anyhow!(
+ "inconsistent light block/header height"
+ )));
+ }
+ let verified_block = self.verify_to_target(height, cache, instance)?;
+
+ // Validate passed consensus block.
+ if untrusted_header.header() != verified_block.signed_header.header() {
+ return Err(Error::VerificationFailed(anyhow!("header mismatch")));
+ }
+
+ Ok(untrusted_block)
+ }
+
+ /// Verify state freshness using RAK and nonces.
+ fn verify_freshness_with_rak(
+ &self,
+ state: &ConsensusState,
+ cache: &Cache,
+ ) -> Result<(), Error> {
+ let identity = if let Some(identity) = self.protocol.get_identity() {
+ identity
+ } else {
+ return Ok(());
+ };
+
+ verify_state_freshness(
+ state,
+ identity,
+ &self.runtime_id,
+ &self.runtime_version,
+ &cache.host_node_id,
+ )
+ }
+
+ /// Verify state freshness using prove freshness transaction.
+ ///
+ /// Verification is done in three steps. In the first one, the verifier selects a unique nonce
+ /// and sends it to the host. The second step is done by the host, who prepares, signs and
+ /// submits a prove freshness transaction using the received nonce. Once transaction is included
+ /// in a block, the host replies with block's height, transaction details and a Merkle proof
+ /// that the transaction was included in the block. In the final step, the verifier verifies
+ /// the proof and accepts state as fresh iff verification succeeds.
+ fn verify_freshness_with_proof(
+ &self,
+ instance: &mut Instance,
+ cache: &mut Cache,
+ ) -> Result<(), Error> {
+ info!(
+ self.logger,
+ "Verifying state freshness using prove freshness transaction"
+ );
+
+ // Generate a random nonce for prove freshness transaction.
+ let mut rng = OsRng {};
+ let mut nonce = [0u8; NONCE_SIZE];
+ rng.fill(&mut nonce);
+
+ // Ask host for freshness proof.
+ let io = Io::new(&self.protocol);
+ let stwp = io.fetch_freshness_proof(&nonce).map_err(|err| {
+ Error::FreshnessVerificationFailed(anyhow!("failed to fetch freshness proof: {}", err))
+ })?;
+
+ // Verify the transaction and the proof.
+ let tx = self.verify_transaction(cache, instance, &stwp.signed_tx, &stwp.proof)?;
+
+ // Verify the method name and the nonce.
+ if tx.method != METHOD_PROVE_FRESHNESS {
+ return Err(Error::FreshnessVerificationFailed(anyhow!(
+ "invalid method name"
+ )));
+ }
+
+ let tx_nonce: Nonce = cbor::from_value(tx.body).map_err(|err| {
+ Error::FreshnessVerificationFailed(anyhow!("failed to decode nonce: {}", err))
+ })?;
+ match nonce.cmp(&tx_nonce) {
+ std::cmp::Ordering::Equal => (),
+ _ => return Err(Error::FreshnessVerificationFailed(anyhow!("invalid nonce"))),
+ }
+
+ info!(self.logger, "State freshness successfully verified");
+
+ Ok(())
+ }
+
+ fn verify_transaction(
+ &self,
+ cache: &mut Cache,
+ instance: &mut Instance,
+ signed_tx: &SignedTransaction,
+ proof: &Proof,
+ ) -> Result<Transaction, Error> {
+ // Verify the signature.
+ if !signed_tx.verify(&self.chain_context) {
+ return Err(Error::TransactionVerificationFailed(anyhow!(
+ "failed to verify the signature"
+ )));
+ }
+
+ // Fetch the root hash of a block in which the transaction was published.
+ let verified_block = self
+ .verify_to_target(proof.height, cache, instance)
+ .map_err(|err| {
+ Error::TransactionVerificationFailed(anyhow!("failed to fetch the block: {}", err))
+ })?;
+
+ let header = verified_block.signed_header.header;
+ if header.height.value() != proof.height {
+ return Err(Error::TransactionVerificationFailed(anyhow!(
+ "invalid block"
+ )));
+ }
+
+ let root_hash = header
+ .data_hash
+ .ok_or_else(|| Error::TransactionVerificationFailed(anyhow!("root hash not found")))?;
+ let root_hash = match root_hash {
+ TMHash::Sha256(hash) => hash,
+ TMHash::None => {
+ return Err(Error::TransactionVerificationFailed(anyhow!(
+ "root hash not found"
+ )));
+ }
+ };
+
+ // Compute hash of the transaction.
+ let digest = Sha256::digest(cbor::to_vec(signed_tx.clone()));
+ let mut tx_hash = [0u8; HASH_SIZE];
+ tx_hash.copy_from_slice(&digest);
+
+ // Decode raw proof as a CometBFT Merkle proof of inclusion.
+ let merkle_proof: merkle::Proof = cbor::from_slice(&proof.raw_proof).map_err(|err| {
+ Error::TransactionVerificationFailed(anyhow!("failed to decode Merkle proof: {}", err))
+ })?;
+
+ merkle_proof.verify(root_hash, tx_hash).map_err(|err| {
+ Error::TransactionVerificationFailed(anyhow!("failed to verify Merkle proof: {}", err))
+ })?;
+
+ // Decode transaction.
+ let tx: Transaction = cbor::from_slice(signed_tx.blob.as_slice()).map_err(|err| {
+ Error::TransactionVerificationFailed(anyhow!("failed to decode transaction: {}", err))
+ })?;
+
+ Ok(tx)
+ }
+
+ /// Fetch state root from block metadata transaction.
+ fn state_root_from_metadata(
+ &self,
+ cache: &mut Cache,
+ instance: &mut Instance,
+ height: u64,
+ ) -> Result<Root, Error> {
+ debug!(
+ self.logger,
+ "Fetching state root from block metadata transaction"
+ );
+
+ // Ask the host for block metadata transaction.
+ let io = Io::new(&self.protocol);
+ let stwp = io.fetch_block_metadata(height).map_err(|err| {
+ Error::StateRoot(anyhow!(
+ "failed to fetch block metadata transaction: {}",
+ err
+ ))
+ })?;
+
+ // Verify the transaction and the proof.
+ let tx = self.verify_transaction(cache, instance, &stwp.signed_tx, &stwp.proof)?;
+
+ if tx.method != METHOD_META {
+ return Err(Error::StateRoot(anyhow!("invalid method name")));
+ }
+
+ let meta: BlockMetadata = cbor::from_value(tx.body).map_err(|err| {
+ Error::StateRoot(anyhow!(
+ "failed to decode block metadata transaction: {}",
+ err
+ ))
+ })?;
+
+ Ok(Root {
+ namespace: Namespace::default(),
+ version: height,
+ root_type: RootType::State,
+ hash: meta.state_root,
+ })
+ }
+
+ fn verify(
+ &self,
+ cache: &mut Cache,
+ instance: &mut Instance,
+ consensus_block: LightBlock,
+ runtime_header: Header,
+ epoch: EpochTime,
+ ) -> Result<ConsensusState, Error> {
+ // Perform basic verifications.
+ predicates::verify_namespace(self.runtime_id, &runtime_header)?;
+ predicates::verify_round_advance(cache, &runtime_header, &consensus_block, epoch)?;
+ predicates::verify_consensus_advance(cache, &consensus_block)?;
+
+ // Verify the consensus layer block.
+ let height = consensus_block.height;
+ let consensus_block = self.verify_consensus_block(cache, instance, consensus_block)?;
+
+ // Perform basic verifications.
+ predicates::verify_time(&runtime_header, &consensus_block)?;
+
+ // Obtain an authoritative state root.
+ let state = self.consensus_state_at(cache, instance, height)?;
+
+ // Check if we have already verified this runtime header to avoid re-verification.
+ if let Some((state_root, state_epoch)) =
+ cache.verified_state_roots.get(&runtime_header.round)
+ {
+ if state_root == &runtime_header.state_root
+ && state_epoch == &epoch
+ && epoch == cache.last_verified_epoch
+ {
+ // Header and epoch matches, no need to perform re-verification.
+
+ // Cache last verified fields.
+ cache.last_verified_height = height;
+ cache.last_verified_round = runtime_header.round;
+
+ return Ok(state);
+ }
+
+ // Force full verification in case of cache mismatch.
+ }
+
+ // Obtain an authoritative state root for full verification.
+ // Note that we cannot return the state at height+1 as the block might not have been
+ // finalized yet, and we won't be able to query block results such as events.
+ let next_state = self.consensus_state_at(cache, instance, height + 1)?;
+
+ // Perform full verification.
+ predicates::verify_state_root(&next_state, &runtime_header)?;
+ predicates::verify_epoch(&next_state, epoch)?;
+
+ // Verify our own RAK is published in registry once per epoch.
+ // This ensures consensus state is recent enough.
+ if cache.last_verified_epoch != epoch {
+ let latest_state = self.latest_consensus_state(cache, instance)?;
+ self.verify_freshness_with_rak(&latest_state, cache)?;
+ }
+
+ // Cache verified state root and epoch.
+ cache
+ .verified_state_roots
+ .put(runtime_header.round, (runtime_header.state_root, epoch));
+
+ // Cache last verified fields.
+ cache.last_verified_height = height;
+ cache.last_verified_round = runtime_header.round;
+ cache.last_verified_epoch = epoch;
+
+ Ok(state)
+ }
+
+ fn verify_for_query(
+ &self,
+ cache: &mut Cache,
+ instance: &mut Instance,
+ consensus_block: LightBlock,
+ runtime_header: Header,
+ epoch: EpochTime,
+ ) -> Result<ConsensusState, Error> {
+ // Perform basic verifications.
+ predicates::verify_namespace(self.runtime_id, &runtime_header)?;
+
+ // Verify the consensus layer block.
+ let height = consensus_block.height;
+ let consensus_block = self.verify_consensus_block(cache, instance, consensus_block)?;
+
+ // Perform basic verifications.
+ predicates::verify_time(&runtime_header, &consensus_block)?;
+
+ // Obtain an authoritative state root.
+ let state = self.consensus_state_at(cache, instance, height)?;
+
+ // Check if we have already verified this runtime header to avoid re-verification.
+ if let Some((state_root, state_epoch)) =
+ cache.verified_state_roots.get(&runtime_header.round)
+ {
+ if state_root == &runtime_header.state_root && state_epoch == &epoch {
+ // Header and epoch matches, no need to perform re-verification.
+ return Ok(state);
+ }
+
+ // Force full verification in case of cache mismatch.
+ }
+
+ // Obtain an authoritative state root for full verification.
+ // Note that we cannot return the state at height+1 as the block might not have been
+ // finalized yet, and we won't be able to query block results such as events.
+ let next_state = self.consensus_state_at(cache, instance, height + 1)?;
+
+ // Perform full verification.
+ predicates::verify_state_root(&next_state, &runtime_header)?;
+ predicates::verify_epoch(&next_state, epoch)?;
+
+ // Cache verified state root and epoch.
+ cache
+ .verified_state_roots
+ .put(runtime_header.round, (runtime_header.state_root, epoch));
+
+ Ok(state)
+ }
+
+ fn events_at(&self, height: u64, kind: EventKind) -> Result<Vec<Event>, Error> {
+ let result = self
+ .protocol
+ .call_host(Body::HostFetchConsensusEventsRequest(
+ HostFetchConsensusEventsRequest { height, kind },
+ ))
+ .map_err(|err| Error::VerificationFailed(err.into()))?;
+ // TODO: Perform event verification once this becomes possible.
+
+ match result {
+ Body::HostFetchConsensusEventsResponse(HostFetchConsensusEventsResponse { events }) => {
+ Ok(events)
+ }
+ _ => Err(Error::VerificationFailed(anyhow!("bad response from host"))),
+ }
+ }
+
+ fn update_insecure_posix_time(&self, verified_block: &TMLightBlock) {
+ // Update untrusted time if ahead. This makes sure that the enclave's sense of time is
+ // synced with consensus sense of time based on the fact that consensus time is harder to
+ // fake than host operating system time.
+ time::update_insecure_posix_time(
+ verified_block
+ .signed_header
+ .header
+ .time
+ .duration_since(Time::unix_epoch())
+ .unwrap()
+ .as_secs()
+ .try_into()
+ .unwrap(),
+ );
+ }
+
+ /// Start the verifier in a separate thread.
+ pub fn start(self) {
+ std::thread::spawn(move || {
+ let _guard = self.tokio_runtime.enter(); // Ensure Tokio runtime is available.
+
+ let logger = get_logger("consensus/cometbft/verifier");
+ info!(logger, "Starting consensus verifier");
+
+ // Try to initialize a couple of times as initially it may be the case that we have
+ // started while the Runtime Host Protocol has not been fully initialized so the host
+ // is still rejecting requests. This is the case because `start()` is called as part
+ // of the RHP initialization itself (when handling a `RuntimeInfoRequest`).
+ for retry in 1..=MAX_INITIALIZATION_RETRIES {
+ // Handle panics by logging and aborting the runtime.
+ let result =
+ match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| self.run())) {
+ Ok(result) => result,
+ Err(_) => {
+ error!(logger, "Consensus verifier aborted");
+ process::abort();
+ }
+ };
+
+ // Handle failures.
+ match result {
+ Ok(_) => {}
+ Err(err @ Error::Builder(_))
+ | Err(err @ Error::TrustedStateLoadingFailed)
+ | Err(err @ Error::ChainContextTransitionFailed(_)) => {
+ error!(logger, "Consensus verifier failed to initialize, retrying";
+ "err" => %err,
+ "retry" => retry,
+ );
+ }
+ Err(err) => {
+ // All other errors are fatal.
+ error!(logger, "Consensus verifier terminated, aborting";
+ "err" => %err,
+ );
+ process::abort();
+ }
+ }
+
+ // Retry to initialize the verifier.
+ std::thread::sleep(Duration::from_secs(1));
+ }
+
+ error!(logger, "Failed to start consensus verifier, aborting");
+ process::abort();
+ });
+ }
+
+ fn run(&self) -> Result<(), Error> {
+ // Create a new light client instance.
+ let options = light_client::Options {
+ trust_threshold: Default::default(),
+ // XXX: Until we have a way to retrieve trusted light client headers from other nodes
+ // (e.g., via EnclaveRPC) there is little sense in specifying a trusting period.
+ trusting_period: Duration::from_secs(3600 * 24 * 365 * 10), // 10 years
+ clock_drift: Duration::from_secs(60),
+ };
+
+ // NOTE: Peer identifier is irrelevant as the enclave is totally eclipsed.
+ let peer_id = PeerId::new([0; 20]);
+ let clock = Box::new(InsecureClock);
+ let verifier = Box::new(PredicateVerifier::new(
+ ProdPredicates,
+ ProvidedVotingPowerCalculator::<signature::DomSepVerifier>::default(),
+ ProdCommitValidator,
+ ));
+ let io = Box::new(Io::new(&self.protocol));
+
+ // Build a light client using the embedded trust root or trust root
+ // stored in the local store.
+ info!(self.logger, "Loading trusted state");
+ let trusted_state = self
+ .trusted_state_store
+ .load(self.runtime_version, &self.trust_root);
+
+ let trusted_state: TrustedState = match trusted_state {
+ Ok(state) => state,
+ Err(err) => {
+ error!(self.logger, "failed to load trusted state (if running in SGX mode, check if the CPU had changed; if yes, wipe 'worker-local-storage.badger.db' and restart the node)");
+ return Err(err);
+ }
+ };
+
+ // Verify if we can trust light blocks from a new chain if the consensus
+ // chain context changes.
+ info!(self.logger, "Checking chain context change");
+ let trusted_state = self.handle_chain_context_change(
+ trusted_state,
+ verifier.as_ref(),
+ clock.as_ref(),
+ io.as_ref(),
+ )?;
+
+ // Insert all of the trusted blocks into the light store as trusted.
+ let mut store = Box::new(LruStore::new(
+ 512,
+ trusted_state.trust_root.height.try_into().unwrap(),
+ ));
+ for lb in trusted_state.trusted_blocks {
+ store.insert(lb.into(), Status::Trusted);
+ }
+ let trust_root = trusted_state.trust_root;
+
+ let builder = LightClientBuilder::custom(
+ peer_id,
+ options,
+ store,
+ io,
+ clock,
+ verifier,
+ Box::new(components::scheduler::basic_bisecting_schedule),
+ Box::new(ProdPredicates),
+ );
+
+ let mut instance = builder
+ .trust_primary_at(
+ trust_root.height.try_into().unwrap(),
+ TMHash::from_str(&trust_root.hash.to_uppercase()).unwrap(),
+ )
+ .map_err(|err| Error::Builder(err.into()))?
+ .build();
+
+ info!(self.logger, "Consensus verifier initialized";
+ "trust_root_height" => trust_root.height,
+ "trust_root_hash" => ?trust_root.hash,
+ "trust_root_runtime_id" => ?trust_root.runtime_id,
+ "trust_root_chain_context" => ?trust_root.chain_context,
+ );
+
+ let host_node_id =
+ block_on(self.protocol.identity()).expect("host should provide a node identity");
+
+ let mut cache = Cache::new(host_node_id);
+
+ // Sync the verifier up to the latest block to make sure we are up to date before
+ // processing any requests.
+ let verified_block = self.verify_to_target(HEIGHT_LATEST, &mut cache, &mut instance)?;
+
+ self.trusted_state_store
+ .save(self.runtime_version, &instance.state.light_store);
+
+ let mut last_saved_verified_block_height =
+ verified_block.signed_header.header.height.value();
+
+ info!(self.logger, "Consensus verifier synced";
+ "latest_height" => cache.latest_known_height(),
+ );
+
+ // Verify state freshness with freshness proof. This step is required only for clients
+ // as executors and key managers verify freshness regularly using node registration
+ // (RAK with random nonces).
+ self.verify_freshness_with_proof(&mut instance, &mut cache)?;
+
+ // Start the command processing loop.
+ loop {
+ let command = self.command_receiver.recv().map_err(|_| Error::Internal)?;
+
+ match command {
+ Command::Synchronize(height, sender) => {
+ sender
+ .send(self.sync(&mut cache, &mut instance, height))
+ .map_err(|_| Error::Internal)?;
+ }
+ Command::Verify(consensus_block, runtime_header, epoch, sender, false) => {
+ sender
+ .send(self.verify(
+ &mut cache,
+ &mut instance,
+ consensus_block,
+ runtime_header,
+ epoch,
+ ))
+ .map_err(|_| Error::Internal)?;
+ }
+ Command::Verify(consensus_block, runtime_header, epoch, sender, true) => {
+ sender
+ .send(self.verify_for_query(
+ &mut cache,
+ &mut instance,
+ consensus_block,
+ runtime_header,
+ epoch,
+ ))
+ .map_err(|_| Error::Internal)?;
+ }
+ Command::LatestState(sender) => {
+ sender
+ .send(self.latest_consensus_state(&mut cache, &mut instance))
+ .map_err(|_| Error::Internal)?;
+ }
+ Command::StateAt(height, sender) => {
+ sender
+ .send(self.consensus_state_at(&mut cache, &mut instance, height))
+ .map_err(|_| Error::Internal)?;
+ }
+ Command::LatestHeight(sender) => {
+ sender
+ .send(self.latest_consensus_height(&cache))
+ .map_err(|_| Error::Internal)?;
+ }
+ Command::EventsAt(height, kind, sender) => {
+ sender
+ .send(self.events_at(height, kind))
+ .map_err(|_| Error::Internal)?;
+ }
+ }
+
+ // Persist last verified block once in a while.
+ if let Some(last_verified_block) = cache.last_verified_block.as_ref() {
+ let last_height = last_verified_block.signed_header.header.height.into();
+ if last_height - last_saved_verified_block_height > TRUSTED_STATE_SAVE_INTERVAL {
+ self.trusted_state_store
+ .save(self.runtime_version, &instance.state.light_store);
+ last_saved_verified_block_height = last_height;
+ }
+ }
+ }
+ }
+
+ fn handle_chain_context_change(
+ &self,
+ mut trusted_state: TrustedState,
+ verifier: &impl TMVerifier,
+ clock: &impl components::clock::Clock,
+ io: &Io,
+ ) -> Result<TrustedState, Error> {
+ let host_info = self.protocol.get_host_info();
+
+ // Nothing to handle.
+ if trusted_state.trust_root.chain_context == host_info.consensus_chain_context {
+ info!(self.logger, "Consensus chain context hasn't changed");
+ return Ok(trusted_state);
+ }
+ info!(self.logger, "Consensus chain context has changed");
+
+ // Chain context transition cannot be done directly from the embedded
+ // trust root as we don't have access to the matching trusted light
+ // block which validator set we need to verify blocks from the new chain.
+ let trusted_block: TMLightBlock = trusted_state
+ .trusted_blocks
+ .pop()
+ .ok_or_else(|| {
+ Error::ChainContextTransitionFailed(anyhow!(
+ "cannot transition from embedded trust root"
+ ))
+ })?
+ .into();
+
+ // Fetch genesis block from the host and prepare untrusted state for
+ // verification. Since host cannot be trusted we need to verify if
+ // fetched height and block belong to the genesis.
+ let height = io
+ .fetch_genesis_height()
+ .map_err(|err| Error::ChainContextTransitionFailed(err.into()))?;
+ let height = AtHeight::At(height.try_into().unwrap());
+ let untrusted_block = components::io::Io::fetch_light_block(io, height)
+ .map_err(|err| Error::ChainContextTransitionFailed(err.into()))?;
+
+ if untrusted_block.signed_header.header.last_block_id.is_some() {
+ return Err(Error::ChainContextTransitionFailed(anyhow!(
+ "invalid genesis block"
+ )));
+ }
+
+ let untrusted = untrusted_block.as_untrusted_state();
+
+ // Prepare trusted state for verification. As we are using the verifier
+ // to verify the untrusted block and state transition, we must make
+ // sure that trusted and untrusted states don't belong to consecutive
+ // blocks as otherwise validator set hash will get verified also.
+ // Keeping heights at minimum distance of 2 will make sure that the
+ // verifier will check if there is enough overlap between the validator
+ // sets.
+ let header = trusted_block.signed_header.header;
+ let height = header.height;
+ let height = if height.increment() != untrusted.height() {
+ height
+ } else {
+ height
+ .value()
+ .checked_sub(1)
+ .ok_or_else(|| Error::ChainContextTransitionFailed(anyhow!("height underflow")))?
+ .try_into()
+ .unwrap()
+ };
+
+ let trusted = TrustedBlockState {
+ header_time: header.time,
+ height,
+ next_validators: &trusted_block.validators,
+ next_validators_hash: header.validators_hash,
+ // We need to use the target chain ID as we know it has changed.
+ chain_id: &chain_id(&host_info.consensus_chain_context),
+ };
+
+ // Verify the new block using +2/3 trust threshold rule.
+ let options = light_client::Options {
+ trust_threshold: TrustThreshold::TWO_THIRDS,
+ trusting_period: Duration::from_secs(3600 * 24 * 365 * 10), // 10 years
+ clock_drift: Duration::from_secs(60),
+ };
+ let now = clock.now();
+
+ let verdict = verifier.verify_update_header(untrusted, trusted, &options, now);
+
+ match verdict {
+ Verdict::Success => (),
+ Verdict::NotEnoughTrust(tally) => {
+ info!(
+ self.logger,
+ "Not enough trust to accept new chain context";
+ "log_event" => "consensus/cometbft/verifier/chain_context/no_trust",
+ "tally" => ?tally,
+ );
+ return Err(Error::ChainContextTransitionFailed(anyhow!(
+ "not enough trust"
+ )));
+ }
+ Verdict::Invalid(e) => {
+ info!(
+ self.logger,
+ "Failed to accept new chain context";
+ "log_event" => "consensus/cometbft/verifier/chain_context/failed",
+ "error" => ?e,
+ );
+ return Err(Error::ChainContextTransitionFailed(anyhow!(
+ "invalid genesis block"
+ )));
+ }
+ }
+
+ info!(self.logger, "Consensus chain context transition done");
+
+ let header = &untrusted_block.signed_header.header;
+ let trust_root = TrustRoot {
+ height: header.height.into(),
+ hash: header.hash().to_string(),
+ runtime_id: self.runtime_id,
+ chain_context: host_info.consensus_chain_context,
+ };
+
+ Ok(TrustedState {
+ trust_root,
+ trusted_blocks: vec![untrusted_block.into()],
+ })
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +
use std::sync::{Arc, Mutex};
+
+use anyhow::anyhow;
+use async_trait::async_trait;
+use slog::info;
+
+use crate::{
+ common::{logger::get_logger, namespace::Namespace},
+ consensus::{
+ beacon::EpochTime,
+ roothash::Header,
+ state::ConsensusState,
+ tendermint::decode_light_block,
+ transaction::Transaction,
+ verifier::{self, Error},
+ BlockMetadata, Event, LightBlock, HEIGHT_LATEST, METHOD_META,
+ },
+ protocol::Protocol,
+ storage::mkvs::{Root, RootType},
+ types::{Body, EventKind, HostFetchConsensusEventsRequest, HostFetchConsensusEventsResponse},
+};
+
+struct Inner {
+ latest_height: Option<u64>,
+}
+
+/// A verifier which performs no verification.
+pub struct NopVerifier {
+ protocol: Arc<Protocol>,
+ inner: Arc<Mutex<Inner>>,
+}
+
+impl NopVerifier {
+ /// Create a new non-verifying verifier.
+ pub fn new(protocol: Arc<Protocol>) -> Self {
+ Self {
+ protocol,
+ inner: Arc::new(Mutex::new(Inner {
+ latest_height: None,
+ })),
+ }
+ }
+
+ /// Start the non-verifying verifier.
+ pub fn start(&self) {
+ let logger = get_logger("consensus/cometbft/verifier");
+ info!(logger, "Starting consensus noop verifier");
+ }
+
+ async fn fetch_light_block(&self, height: u64) -> Result<LightBlock, Error> {
+ let result = self
+ .protocol
+ .call_host_async(Body::HostFetchConsensusBlockRequest { height })
+ .await
+ .map_err(|err| Error::VerificationFailed(err.into()))?;
+
+ match result {
+ Body::HostFetchConsensusBlockResponse { block } => Ok(block),
+ _ => Err(Error::VerificationFailed(anyhow!("bad response from host"))),
+ }
+ }
+}
+
+#[async_trait]
+impl verifier::Verifier for NopVerifier {
+ async fn sync(&self, height: u64) -> Result<(), Error> {
+ let mut inner = self.inner.lock().unwrap();
+ inner.latest_height = Some(height);
+
+ Ok(())
+ }
+
+ async fn verify(
+ &self,
+ consensus_block: LightBlock,
+ _runtime_header: Header,
+ _epoch: EpochTime,
+ ) -> Result<ConsensusState, Error> {
+ self.unverified_state(consensus_block).await
+ }
+
+ async fn verify_for_query(
+ &self,
+ consensus_block: LightBlock,
+ _runtime_header: Header,
+ _epoch: EpochTime,
+ ) -> Result<ConsensusState, Error> {
+ self.unverified_state(consensus_block).await
+ }
+
+ async fn unverified_state(&self, consensus_block: LightBlock) -> Result<ConsensusState, Error> {
+ let untrusted_block =
+ decode_light_block(consensus_block).map_err(Error::VerificationFailed)?;
+ // NOTE: No actual verification is performed.
+ let state_root = untrusted_block.get_state_root();
+
+ let mut inner = self.inner.lock().unwrap();
+ if state_root.version + 1 > inner.latest_height.unwrap_or_default() {
+ inner.latest_height = Some(state_root.version + 1);
+ }
+
+ Ok(ConsensusState::from_protocol(
+ self.protocol.clone(),
+ state_root.version + 1,
+ state_root,
+ ))
+ }
+
+ async fn latest_state(&self) -> Result<ConsensusState, Error> {
+ let height = self.latest_height().await?;
+
+ // When latest state is requested we always perform same-block execution verification.
+ let result = self
+ .protocol
+ .call_host_async(Body::HostFetchBlockMetadataTxRequest { height })
+ .await
+ .map_err(|err| Error::StateRoot(err.into()))?;
+
+ // NOTE: This is a noop verifier so we do not verify the Merkle proof.
+ let signed_tx = match result {
+ Body::HostFetchBlockMetadataTxResponse { signed_tx, .. } => signed_tx,
+ _ => return Err(Error::StateRoot(anyhow!("bad response from host"))),
+ };
+
+ let tx: Transaction = cbor::from_slice(signed_tx.blob.as_slice()).map_err(|err| {
+ Error::TransactionVerificationFailed(anyhow!("failed to decode transaction: {}", err))
+ })?;
+
+ if tx.method != METHOD_META {
+ return Err(Error::StateRoot(anyhow!("invalid method name")));
+ }
+
+ let meta: BlockMetadata = cbor::from_value(tx.body).map_err(|err| {
+ Error::StateRoot(anyhow!(
+ "failed to decode block metadata transaction: {}",
+ err
+ ))
+ })?;
+
+ let state_root = Root {
+ namespace: Namespace::default(),
+ version: height,
+ root_type: RootType::State,
+ hash: meta.state_root,
+ };
+
+ Ok(ConsensusState::from_protocol(
+ self.protocol.clone(),
+ state_root.version,
+ state_root,
+ ))
+ }
+
+ async fn state_at(&self, height: u64) -> Result<ConsensusState, Error> {
+ let block = self.fetch_light_block(height).await?;
+ self.unverified_state(block).await
+ }
+
+ async fn events_at(&self, height: u64, kind: EventKind) -> Result<Vec<Event>, Error> {
+ let result = self
+ .protocol
+ .call_host_async(Body::HostFetchConsensusEventsRequest(
+ HostFetchConsensusEventsRequest { height, kind },
+ ))
+ .await
+ .map_err(|err| Error::VerificationFailed(err.into()))?;
+
+ match result {
+ Body::HostFetchConsensusEventsResponse(HostFetchConsensusEventsResponse { events }) => {
+ Ok(events)
+ }
+ _ => Err(Error::VerificationFailed(anyhow!("bad response from host"))),
+ }
+ }
+
+ async fn latest_height(&self) -> Result<u64, Error> {
+ {
+ let inner = self.inner.lock().unwrap();
+ if let Some(latest_height) = inner.latest_height {
+ return Ok(latest_height);
+ }
+ }
+
+ let latest_height = self.fetch_light_block(HEIGHT_LATEST).await?.height;
+ self.sync(latest_height).await?;
+ Ok(latest_height)
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +
use anyhow::anyhow;
+
+use crate::{
+ common::namespace::Namespace,
+ consensus::{
+ beacon::EpochTime,
+ roothash::Header,
+ state::{
+ beacon::ImmutableState as BeaconState, roothash::ImmutableState as RoothashState,
+ ConsensusState,
+ },
+ tendermint::{verifier::Cache, LightBlockMeta},
+ verifier::Error,
+ LightBlock,
+ },
+};
+
+/// Verifies that the namespace in the runtime header matches the trusted namespace.
+pub fn verify_namespace(trusted: Namespace, runtime_header: &Header) -> Result<(), Error> {
+ if trusted != runtime_header.namespace {
+ return Err(Error::VerificationFailed(anyhow!(
+ "header namespace does not match trusted runtime id"
+ )));
+ }
+
+ Ok(())
+}
+
+/// Verifies that consensus height has correctly advanced since the last update.
+pub fn verify_consensus_advance(cache: &Cache, consensus_block: &LightBlock) -> Result<(), Error> {
+ if consensus_block.height < cache.last_verified_height {
+ // Reject requests for earlier heights.
+ return Err(Error::VerificationFailed(anyhow!(
+ "height seems to have moved backwards"
+ )));
+ }
+
+ Ok(())
+}
+
+/// Verifies that the round has correctly advanced since the last update.
+pub fn verify_round_advance(
+ cache: &Cache,
+ runtime_header: &Header,
+ consensus_block: &LightBlock,
+ epoch: EpochTime,
+) -> Result<(), Error> {
+ if runtime_header.round < cache.last_verified_round {
+ // Reject requests for earlier rounds.
+ return Err(Error::VerificationFailed(anyhow!(
+ "round seems to have moved backwards"
+ )));
+ }
+ if epoch < cache.last_verified_epoch {
+ // Reject requests for earlier epochs.
+ return Err(Error::VerificationFailed(anyhow!(
+ "epoch seems to have moved backwards"
+ )));
+ }
+
+ // If round has advanced make sure that consensus height has also advanced as a round can
+ // only be finalized in a subsequent consensus block. This is to avoid a situation where
+ // one would keep feeding the same consensus block for subsequent rounds.
+ if runtime_header.round > cache.last_verified_round
+ && consensus_block.height <= cache.last_verified_height
+ {
+ return Err(Error::VerificationFailed(anyhow!(
+ "consensus height did not advance but runtime round did"
+ )));
+ }
+
+ Ok(())
+}
+
+/// Verifies that the runtime header has time consistent with the consensus header.
+pub fn verify_time(runtime_header: &Header, consensus_block: &LightBlockMeta) -> Result<(), Error> {
+ let consensus_header = &consensus_block
+ .signed_header
+ .as_ref()
+ .ok_or_else(|| Error::VerificationFailed(anyhow!("missing signed header")))?
+ .header;
+ if runtime_header.timestamp != consensus_header.time.unix_timestamp() as u64 {
+ return Err(Error::VerificationFailed(anyhow!(
+ "runtime block timestamp inconsistent with consensus time"
+ )));
+ }
+
+ Ok(())
+}
+
+/// Verifies that the runtime header has state root consistent with consensus state.
+///
+/// Assumes the namespace in the runtime header has already been verified via `verify_namespace`.
+pub fn verify_state_root(state: &ConsensusState, runtime_header: &Header) -> Result<(), Error> {
+ let roothash_state = RoothashState::new(&state);
+ let state_root = roothash_state
+ .state_root(runtime_header.namespace)
+ .map_err(|err| {
+ Error::VerificationFailed(anyhow!("failed to retrieve trusted state root: {}", err))
+ })?;
+
+ if runtime_header.state_root != state_root {
+ return Err(Error::VerificationFailed(anyhow!(
+ "state root mismatch (expected: {} got: {})",
+ state_root,
+ runtime_header.state_root
+ )));
+ }
+
+ Ok(())
+}
+
+/// Verifies that the epoch is consistent with consensus state.
+pub fn verify_epoch(state: &ConsensusState, epoch: EpochTime) -> Result<(), Error> {
+ let beacon_state = BeaconState::new(&state);
+ let current_epoch = beacon_state
+ .epoch()
+ .map_err(|err| Error::VerificationFailed(anyhow!("failed to retrieve epoch: {}", err)))?;
+
+ if current_epoch != epoch {
+ return Err(Error::VerificationFailed(anyhow!(
+ "epoch number mismatch (expected: {} got: {})",
+ current_epoch,
+ epoch,
+ )));
+ }
+
+ Ok(())
+}
+use tendermint::{crypto::signature, PublicKey, Signature};
+
+use crate::{common::crypto::hash::Hash, consensus::tendermint::TENDERMINT_CONTEXT};
+
+/// A signature verifier that uses the Oasis Core domain separation scheme.
+#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)]
+pub struct DomSepVerifier;
+
+impl signature::Verifier for DomSepVerifier {
+ fn verify(
+ pubkey: PublicKey,
+ msg: &[u8],
+ signature: &Signature,
+ ) -> Result<(), signature::Error> {
+ // Use Oasis Core domain separation scheme.
+ let msg = Hash::digest_bytes_list(&[TENDERMINT_CONTEXT, msg]);
+
+ // Forward the actual verification to the Tendermint's default verifier.
+ tendermint::crypto::default::signature::Verifier::verify(pubkey, msg.as_ref(), signature)
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +
//! An in-memory LRU store for the light client.
+use std::{
+ num::NonZeroUsize,
+ sync::{Mutex, MutexGuard},
+};
+
+use tendermint_light_client::{
+ store::LightStore,
+ types::{Height, LightBlock, Status},
+};
+
+/// In-memory LRU store.
+pub struct LruStore {
+ inner: Mutex<Inner>,
+}
+
+impl std::fmt::Debug for LruStore {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> Result<(), std::fmt::Error> {
+ write!(f, "LruStore")
+ }
+}
+
+#[derive(Clone, Debug, PartialEq)]
+struct StoreEntry {
+ light_block: LightBlock,
+ status: Status,
+}
+
+impl StoreEntry {
+ fn new(light_block: LightBlock, status: Status) -> Self {
+ Self {
+ light_block,
+ status,
+ }
+ }
+}
+
+struct Inner {
+ trust_root_height: Height,
+ blocks: lru::LruCache<Height, StoreEntry>,
+}
+
+impl LruStore {
+ /// Create a new, empty, in-memory LRU store of the given capacity and trust root height.
+ pub fn new(capacity: usize, trust_root_height: Height) -> Self {
+ Self {
+ inner: Mutex::new(Inner {
+ trust_root_height,
+ blocks: lru::LruCache::new(NonZeroUsize::new(capacity).unwrap()),
+ }),
+ }
+ }
+
+ fn inner(&self) -> MutexGuard<'_, Inner> {
+ self.inner.lock().unwrap()
+ }
+
+ fn inner_mut(&mut self) -> &mut Inner {
+ self.inner.get_mut().unwrap()
+ }
+}
+
+impl LightStore for LruStore {
+ fn get(&self, height: Height, status: Status) -> Option<LightBlock> {
+ self.inner()
+ .blocks
+ .get(&height)
+ .filter(|e| e.status == status)
+ .map(|e| e.light_block.clone())
+ }
+
+ fn insert(&mut self, light_block: LightBlock, status: Status) {
+ let store = self.inner_mut();
+
+ // Promote trust root to prevent it from being evicted.
+ store.blocks.promote(&store.trust_root_height);
+
+ store
+ .blocks
+ .put(light_block.height(), StoreEntry::new(light_block, status));
+ }
+
+ fn remove(&mut self, height: Height, status: Status) {
+ let store = self.inner_mut();
+
+ // Prevent removal of trust root.
+ if height == store.trust_root_height {
+ return;
+ }
+
+ if store
+ .blocks
+ .get(&height)
+ .map(|e| e.status != status)
+ .unwrap_or(true)
+ {
+ return;
+ }
+ store.blocks.pop(&height);
+ }
+
+ fn update(&mut self, light_block: &LightBlock, status: Status) {
+ self.insert(light_block.clone(), status)
+ }
+
+ fn highest(&self, status: Status) -> Option<LightBlock> {
+ self.inner()
+ .blocks
+ .iter()
+ .filter(|(_, e)| e.status == status)
+ .max_by_key(|(&height, _)| height)
+ .map(|(_, e)| e.light_block.clone())
+ }
+
+ fn highest_before(&self, height: Height, status: Status) -> Option<LightBlock> {
+ self.inner()
+ .blocks
+ .iter()
+ .filter(|(_, e)| e.status == status)
+ .filter(|(h, _)| h <= &&height)
+ .max_by_key(|(&height, _)| height)
+ .map(|(_, e)| e.light_block.clone())
+ }
+
+ fn lowest(&self, status: Status) -> Option<LightBlock> {
+ self.inner()
+ .blocks
+ .iter()
+ .filter(|(_, e)| e.status == status)
+ .min_by_key(|(&height, _)| height)
+ .map(|(_, e)| e.light_block.clone())
+ }
+
+ #[allow(clippy::needless_collect)]
+ fn all(&self, status: Status) -> Box<dyn Iterator<Item = LightBlock>> {
+ let light_blocks: Vec<_> = self
+ .inner()
+ .blocks
+ .iter()
+ .filter(|(_, e)| e.status == status)
+ .map(|(_, e)| e.light_block.clone())
+ .collect();
+
+ Box::new(light_blocks.into_iter())
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use tendermint_light_client::{
+ store::LightStore,
+ types::{LightBlock, Status},
+ };
+ use tendermint_testgen::{Generator, LightChain};
+
+ use super::LruStore;
+
+ fn generate_blocks(count: u64) -> Vec<LightBlock> {
+ LightChain::default_with_length(count)
+ .light_blocks
+ .into_iter()
+ .map(|lb| lb.generate().unwrap())
+ .map(|lb| LightBlock {
+ signed_header: lb.signed_header,
+ validators: lb.validators,
+ next_validators: lb.next_validators,
+ provider: lb.provider,
+ })
+ .collect()
+ }
+
+ #[test]
+ fn test_trust_root_height_retained() {
+ let blocks = generate_blocks(10);
+ let mut store = LruStore::new(2, blocks[0].height()); // Only storing two blocks.
+ store.insert(blocks[0].clone(), Status::Trusted);
+ store.insert(blocks[1].clone(), Status::Trusted);
+ store.insert(blocks[2].clone(), Status::Trusted);
+ store.insert(blocks[3].clone(), Status::Trusted);
+
+ let lowest = store
+ .lowest(Status::Trusted)
+ .expect("there should be a lowest block");
+ assert_eq!(lowest, blocks[0]);
+ }
+
+ #[test]
+ fn test_basic() {
+ let blocks = generate_blocks(10);
+ let mut store = LruStore::new(10, blocks[0].height());
+ for block in &blocks {
+ store.insert(block.clone(), Status::Trusted);
+
+ // Block should be stored.
+ let stored_block = store.get(block.height(), Status::Trusted);
+ assert_eq!(stored_block.as_ref(), Some(block));
+
+ // Highest and lowest blocks should be correct.
+ let highest = store
+ .highest(Status::Trusted)
+ .expect("there should be a highest block");
+ let lowest = store
+ .lowest(Status::Trusted)
+ .expect("there should be a lowest block");
+ assert_eq!(&highest, block);
+ assert_eq!(lowest, blocks[0]);
+
+ // Highest before should work.
+ let highest_before = store.highest_before(block.height(), Status::Trusted);
+ assert_eq!(highest_before.as_ref(), Some(block));
+
+ let highest_before = store.highest_before(block.height().increment(), Status::Trusted);
+ assert_eq!(highest_before.as_ref(), Some(block));
+ }
+
+ // Test removal of trust root block.
+ store.remove(blocks[0].height(), Status::Trusted);
+
+ let block_zero = store.get(blocks[0].height(), Status::Trusted);
+ assert_eq!(block_zero.as_ref(), Some(&blocks[0]));
+
+ let lowest = store
+ .lowest(Status::Trusted)
+ .expect("there should be a lowest block");
+ assert_eq!(lowest, blocks[0]);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +
use std::sync::Arc;
+
+use sgx_isa::Keypolicy;
+use tendermint_light_client::{
+ store::LightStore,
+ types::{LightBlock as TMLightBlock, Status},
+};
+
+use crate::{
+ common::{
+ namespace::Namespace,
+ sgx::{seal, EnclaveIdentity},
+ version::Version,
+ },
+ consensus::verifier::{Error, TrustRoot},
+ protocol::ProtocolUntrustedLocalStorage,
+ storage::KeyValue,
+ Protocol, TeeType, BUILD_INFO,
+};
+
+/// Storage key prefix under which the sealed trusted state is stored in
+/// the untrusted local storage.
+///
+/// The actual key includes the MRENCLAVE to support upgrades.
+const TRUSTED_STATE_STORAGE_KEY_PREFIX: &str = "tendermint.verifier.trusted_state";
+
+/// Domain separation context for the trusted state.
+const TRUSTED_STATE_CONTEXT: &[u8] = b"oasis-core/verifier: trusted state";
+
+/// An encoded Tendermint light block.
+#[derive(Debug, Clone)]
+pub struct EncodedLightBlock(TMLightBlock);
+
+impl From<TMLightBlock> for EncodedLightBlock {
+ fn from(value: TMLightBlock) -> Self {
+ Self(value)
+ }
+}
+
+impl From<EncodedLightBlock> for TMLightBlock {
+ fn from(value: EncodedLightBlock) -> Self {
+ value.0
+ }
+}
+
+impl cbor::Encode for EncodedLightBlock {
+ fn into_cbor_value(self) -> cbor::Value {
+ cbor::serde::to_value(&self.0).unwrap()
+ }
+}
+
+impl cbor::Decode for EncodedLightBlock {
+ fn try_from_cbor_value(value: cbor::Value) -> Result<Self, cbor::DecodeError> {
+ cbor::serde::from_value(value)
+ .map_err(|_| cbor::DecodeError::ParsingFailed)
+ .map(Self)
+ }
+}
+
+/// Trusted state containing trust root and trusted light block.
+#[derive(Debug, Clone, Default, cbor::Encode, cbor::Decode)]
+pub struct TrustedState {
+ /// Trust root.
+ pub trust_root: TrustRoot,
+ /// Trusted light blocks, ordered by height from lowest to highest.
+ ///
+ /// Optional as we don't want to force trusted state for embedded trust
+ /// root to have a matching trusted light block.
+ pub trusted_blocks: Vec<EncodedLightBlock>,
+}
+
+/// Untrusted local storage for storing the sealed latest trusted root.
+pub struct TrustedStateStore {
+ runtime_id: Namespace,
+ chain_context: String,
+ untrusted_local_store: ProtocolUntrustedLocalStorage,
+}
+
+impl TrustedStateStore {
+ /// Create a new trusted state local store.
+ pub fn new(runtime_id: Namespace, chain_context: String, protocol: Arc<Protocol>) -> Self {
+ let untrusted_local_store = ProtocolUntrustedLocalStorage::new(protocol);
+
+ Self {
+ runtime_id,
+ chain_context,
+ untrusted_local_store,
+ }
+ }
+
+ /// Persist latest trusted state from the in-memory light store.
+ ///
+ /// # Panics
+ ///
+ /// Panics in case the light store does not have any blocks or if insertion to the underlying
+ /// runtime's untrusted local store fails.
+ pub fn save(&self, runtime_version: Version, store: &Box<dyn LightStore>) {
+ if BUILD_INFO.tee_type == TeeType::Tdx {
+ // TODO: Currently TDX does not have sealing capabilities, so we just do not persist
+ // anything as we can't seal secrets until we have CPU-bound key derivation.
+ return;
+ }
+
+ let lowest_block = store.lowest(Status::Trusted).unwrap();
+ let highest_block = store.highest(Status::Trusted).unwrap();
+
+ // Generate a new trust root from the highest trusted block.
+ let trust_root = TrustRoot {
+ height: highest_block.height().into(),
+ hash: highest_block.signed_header.header.hash().to_string(),
+ runtime_id: self.runtime_id,
+ chain_context: self.chain_context.clone(),
+ };
+
+ let trusted_state = TrustedState {
+ trust_root,
+ trusted_blocks: vec![lowest_block.into(), highest_block.into()],
+ };
+
+ // Serialize and seal the trusted state.
+ let raw = cbor::to_vec(trusted_state);
+ let sealed = seal::seal(Keypolicy::MRENCLAVE, TRUSTED_STATE_CONTEXT, &raw);
+
+ // Store the trusted state.
+ self.untrusted_local_store
+ .insert(Self::derive_storage_key(runtime_version), sealed)
+ .unwrap();
+ }
+
+ /// Attempts to load previously sealed trusted state.
+ ///
+ /// If no sealed trusted state is available, it returns state based on the passed trust root.
+ pub fn load(
+ &self,
+ runtime_version: Version,
+ trust_root: &TrustRoot,
+ ) -> Result<TrustedState, Error> {
+ if BUILD_INFO.tee_type == TeeType::Tdx {
+ // TODO: Currently TDX does not have sealing capabilities, so we just do not persist
+ // anything as we can't seal secrets until we have CPU-bound key derivation.
+ return Ok(TrustedState {
+ trust_root: trust_root.clone(),
+ trusted_blocks: vec![],
+ });
+ }
+
+ // Attempt to load the previously sealed trusted state.
+ let untrusted_value = self
+ .untrusted_local_store
+ .get(Self::derive_storage_key(runtime_version))
+ .map_err(|_| Error::TrustedStateLoadingFailed)?;
+ if untrusted_value.is_empty() {
+ return Ok(TrustedState {
+ trust_root: trust_root.clone(),
+ trusted_blocks: vec![],
+ });
+ }
+
+ // Unseal the sealed trusted state.
+ let raw = seal::unseal(
+ Keypolicy::MRENCLAVE,
+ TRUSTED_STATE_CONTEXT,
+ &untrusted_value,
+ )
+ .map_err(|_| Error::TrustedStateLoadingFailed)?
+ .unwrap();
+
+ let trusted_state: TrustedState =
+ cbor::from_slice(&raw).expect("corrupted sealed trusted state");
+
+ Ok(trusted_state)
+ }
+
+ fn derive_storage_key(runtime_version: Version) -> Vec<u8> {
+ // Namespace storage key by MRENCLAVE as we can only unseal our own sealed data and we need
+ // to support upgrades. We assume that an upgrade will include an up-to-date trusted state
+ // anyway.
+ format!(
+ "{}.{}.{:x}",
+ TRUSTED_STATE_STORAGE_KEY_PREFIX,
+ u64::from(runtime_version),
+ EnclaveIdentity::current()
+ .map(|eid| eid.mr_enclave)
+ .unwrap_or_default()
+ )
+ .into_bytes()
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +
use tokio::sync::oneshot;
+
+use crate::{
+ consensus::{
+ beacon::EpochTime, roothash::Header, state::ConsensusState, verifier::Error, Event,
+ LightBlock,
+ },
+ types::EventKind,
+};
+
+/// Size of nonce for prove freshness request.
+pub const NONCE_SIZE: usize = 32;
+
+/// Nonce for prove freshness request.
+pub type Nonce = [u8; NONCE_SIZE];
+
+/// Command sent to the verifier thread.
+pub enum Command {
+ Synchronize(u64, oneshot::Sender<Result<(), Error>>),
+ Verify(
+ LightBlock,
+ Header,
+ EpochTime,
+ oneshot::Sender<Result<ConsensusState, Error>>,
+ bool,
+ ),
+ LatestState(oneshot::Sender<Result<ConsensusState, Error>>),
+ LatestHeight(oneshot::Sender<Result<u64, Error>>),
+ StateAt(u64, oneshot::Sender<Result<ConsensusState, Error>>),
+ EventsAt(u64, EventKind, oneshot::Sender<Result<Vec<Event>, Error>>),
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +
use crate::common::{
+ crypto::signature::{signature_context_with_chain_separation, Signed},
+ quantity::Quantity,
+};
+
+pub const SIGNATURE_CONTEXT: &[u8] = b"oasis-core/consensus: tx";
+
+fn signature_context(chain_context: &String) -> Vec<u8> {
+ let context = SIGNATURE_CONTEXT.to_vec();
+ signature_context_with_chain_separation(context, chain_context)
+}
+
+/// Unsigned consensus transaction.
+#[derive(Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct Transaction {
+ /// Nonce to prevent replay.
+ pub nonce: u64,
+ /// Optional fee that the sender commits to pay to execute this transaction.
+ pub fee: Option<Fee>,
+
+ /// Method that should be called.
+ pub method: MethodName,
+ /// Method call body.
+ pub body: cbor::Value,
+}
+
+/// Signed consensus transaction.
+pub type SignedTransaction = Signed;
+
+impl SignedTransaction {
+ /// Returns true iff the signature is valid.
+ pub fn verify(&self, chain_context: &String) -> bool {
+ let context = signature_context(chain_context);
+ self.signature.verify(&context, &self.blob)
+ }
+}
+
+/// Consensus transaction fee the sender wishes to pay for operations which
+/// require a fee to be paid to validators.
+#[derive(Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Fee {
+ /// Fee amount to be paid.
+ pub amount: Quantity,
+ /// Maximum gas that a transaction can use.
+ pub gas: Gas,
+}
+
+/// Consensus gas representation.
+pub type Gas = u64;
+
+/// Method name.
+pub type MethodName = String;
+
+/// Proof of transaction inclusion in a block.
+#[derive(Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Proof {
+ /// Block height at which the transaction was published.
+ pub height: u64,
+ /// Actual raw proof.
+ pub raw_proof: Vec<u8>,
+}
+
+/// Signed consensus transaction with a proof of its inclusion in a block.
+#[derive(Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct SignedTransactionWithProof {
+ /// Signed transaction.
+ pub signed_tx: SignedTransaction,
+ /// Proof of transaction inclusion in a block.
+ pub proof: Proof,
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +
//! Trait for consensus layer verification.
+use std::sync::Arc;
+
+use anyhow::anyhow;
+use async_trait::async_trait;
+use thiserror::Error;
+
+use super::{
+ beacon::EpochTime,
+ roothash::Header,
+ state::{registry::ImmutableState as RegistryState, ConsensusState},
+ Event, LightBlock,
+};
+use crate::{
+ common::{crypto::signature::PublicKey, namespace::Namespace, version::Version},
+ identity::Identity,
+ types::{self, EventKind},
+};
+
+#[derive(Debug, Error)]
+pub enum Error {
+ #[error("builder: {0}")]
+ Builder(#[source] anyhow::Error),
+
+ #[error("verification: {0}")]
+ VerificationFailed(#[source] anyhow::Error),
+
+ #[error("trusted state loading failed")]
+ TrustedStateLoadingFailed,
+
+ #[error("consensus chain context transition failed: {0}")]
+ ChainContextTransitionFailed(#[source] anyhow::Error),
+
+ #[error("freshness verification: {0}")]
+ FreshnessVerificationFailed(#[source] anyhow::Error),
+
+ #[error("transaction verification: {0}")]
+ TransactionVerificationFailed(#[source] anyhow::Error),
+
+ #[error("state root: {0}")]
+ StateRoot(#[source] anyhow::Error),
+
+ #[error("internal consensus verifier error")]
+ Internal,
+}
+
+impl Error {
+ fn code(&self) -> u32 {
+ match self {
+ Error::Builder(_) => 1,
+ Error::VerificationFailed(_) => 2,
+ Error::TrustedStateLoadingFailed => 3,
+ Error::ChainContextTransitionFailed(_) => 4,
+ Error::FreshnessVerificationFailed(_) => 5,
+ Error::TransactionVerificationFailed(_) => 6,
+ Error::StateRoot(_) => 7,
+ Error::Internal => 8,
+ }
+ }
+}
+
+impl From<Error> for types::Error {
+ fn from(e: Error) -> Self {
+ Self {
+ module: "verifier".to_string(),
+ code: e.code(),
+ message: e.to_string(),
+ }
+ }
+}
+
+/// Verifier is the consensus layer state verifier trait.
+#[async_trait]
+pub trait Verifier: Send + Sync {
+ /// Synchronize the verifier state up to including the passed consensus height.
+ async fn sync(&self, height: u64) -> Result<(), Error>;
+
+ /// Verify that the given runtime header is valid at the given consensus layer block and return
+ /// the consensus layer state accessor for that block.
+ ///
+ /// This also verifies that the state is fresh.
+ async fn verify(
+ &self,
+ consensus_block: LightBlock,
+ runtime_header: Header,
+ epoch: EpochTime,
+ ) -> Result<ConsensusState, Error>;
+
+ /// Verify that the given runtime header is valid at the given consensus layer block and return
+ /// the consensus layer state accessor for that block.
+ ///
+ /// This is a relaxed version of the `verify` function that should be used for verifying state
+ /// in queries.
+ async fn verify_for_query(
+ &self,
+ consensus_block: LightBlock,
+ runtime_header: Header,
+ epoch: EpochTime,
+ ) -> Result<ConsensusState, Error>;
+
+ /// Return the consensus layer state accessor for the given consensus layer block WITHOUT
+ /// performing any verification. This method should only be used for operations that do not
+ /// require integrity guarantees.
+ async fn unverified_state(&self, consensus_block: LightBlock) -> Result<ConsensusState, Error>;
+
+ /// Return the latest verified consensus layer state.
+ ///
+ /// # Warning
+ ///
+ /// The state is not verified to be fresh. Use `verify_state_freshness` to perform this
+ /// verification manually if needed.
+ async fn latest_state(&self) -> Result<ConsensusState, Error>;
+
+ /// Return the verified consensus layer state for a given height.
+ ///
+ /// # Warning
+ ///
+ /// The state is not verified to be fresh. Use `verify_state_freshness` to perform this
+ /// verification manually if needed.
+ async fn state_at(&self, height: u64) -> Result<ConsensusState, Error>;
+
+ /// Return the consensus layer events at the given height.
+ ///
+ /// # Warning
+ ///
+ /// Event integrity is currently not verified and it thus relies on replicated computation even
+ /// when using a TEE-enabled runtime.
+ async fn events_at(&self, height: u64, kind: EventKind) -> Result<Vec<Event>, Error>;
+
+ /// Return the latest known consensus layer height.
+ async fn latest_height(&self) -> Result<u64, Error>;
+}
+
+#[async_trait]
+impl<T: ?Sized + Verifier> Verifier for Arc<T> {
+ async fn sync(&self, height: u64) -> Result<(), Error> {
+ Verifier::sync(&**self, height).await
+ }
+
+ async fn verify(
+ &self,
+ consensus_block: LightBlock,
+ runtime_header: Header,
+ epoch: EpochTime,
+ ) -> Result<ConsensusState, Error> {
+ Verifier::verify(&**self, consensus_block, runtime_header, epoch).await
+ }
+
+ async fn verify_for_query(
+ &self,
+ consensus_block: LightBlock,
+ runtime_header: Header,
+ epoch: EpochTime,
+ ) -> Result<ConsensusState, Error> {
+ Verifier::verify_for_query(&**self, consensus_block, runtime_header, epoch).await
+ }
+
+ async fn unverified_state(&self, consensus_block: LightBlock) -> Result<ConsensusState, Error> {
+ Verifier::unverified_state(&**self, consensus_block).await
+ }
+
+ async fn latest_state(&self) -> Result<ConsensusState, Error> {
+ Verifier::latest_state(&**self).await
+ }
+
+ async fn state_at(&self, height: u64) -> Result<ConsensusState, Error> {
+ Verifier::state_at(&**self, height).await
+ }
+
+ async fn events_at(&self, height: u64, kind: EventKind) -> Result<Vec<Event>, Error> {
+ Verifier::events_at(&**self, height, kind).await
+ }
+
+ async fn latest_height(&self) -> Result<u64, Error> {
+ Verifier::latest_height(&**self).await
+ }
+}
+
+/// Consensus layer trust root.
+#[derive(Debug, Clone, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct TrustRoot {
+ /// Known trusted height.
+ pub height: u64,
+ /// Known hex-encoded trusted consensus layer header hash.
+ pub hash: String,
+ /// Known runtime identifier.
+ pub runtime_id: Namespace,
+ /// Known consensus chain context.
+ pub chain_context: String,
+}
+
+/// Verify consensus layer state freshness based on our internal state.
+pub fn verify_state_freshness(
+ state: &ConsensusState,
+ identity: &Identity,
+ runtime_id: &Namespace,
+ version: &Version,
+ host_node_id: &PublicKey,
+) -> Result<(), Error> {
+ let registry_state = RegistryState::new(&state);
+
+ let node = registry_state.node(host_node_id).map_err(|err| {
+ Error::VerificationFailed(anyhow!(
+ "failed to retrieve node from the registry: {}",
+ err
+ ))
+ })?;
+ let node = node.ok_or_else(|| {
+ Error::VerificationFailed(anyhow!(
+ "own node ID '{}' not found in registry state",
+ host_node_id,
+ ))
+ })?;
+
+ if !node.has_tee(identity, runtime_id, version) {
+ return Err(Error::VerificationFailed(anyhow!(
+ "own identity not found in registry state"
+ )));
+ }
+
+ Ok(())
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +765 +766 +767 +768 +769 +770 +771 +772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805 +806 +807 +808 +809 +810 +811 +812 +813 +814 +815 +816 +817 +818 +819 +820 +821 +822 +823 +824 +825 +826 +827 +828 +829 +830 +831 +832 +833 +834 +835 +836 +837 +838 +839 +840 +841 +842 +843 +844 +845 +846 +847 +848 +849 +850 +851 +852 +853 +854 +855 +856 +857 +858 +859 +860 +861 +862 +863 +864 +865 +866 +867 +868 +869 +870 +871 +872 +873 +874 +875 +876 +877 +878 +879 +880 +881 +882 +883 +884 +885 +886 +887 +888 +889 +890 +891 +892 +893 +894 +895 +896 +897 +898 +899 +900 +901 +902 +903 +904 +905 +906 +907 +908 +909 +910 +911 +912 +913 +914 +915 +916 +917 +918 +919 +920 +921 +922 +923 +924 +925 +926 +927 +928 +929 +930 +931 +932 +933 +934 +935 +936 +937 +938 +939 +940 +941 +942 +943 +944 +945 +946 +947 +948 +949 +950 +951 +952 +953 +954 +955 +956 +957 +958 +959 +960 +961 +962 +963 +964 +965 +966 +967 +968 +969 +970 +971 +972 +973 +974 +975 +976 +977 +978 +979 +980 +981 +982 +983 +984 +985 +986 +987 +988 +989 +990 +991 +992 +993 +994 +995 +996 +997 +998 +999 +1000 +1001 +1002 +1003 +1004 +1005 +1006 +1007 +
//! Runtime call dispatcher.
+use std::{
+ convert::TryInto,
+ sync::{Arc, Condvar, Mutex},
+ thread,
+};
+
+use anyhow::Result as AnyResult;
+use rustc_hex::ToHex;
+use slog::{debug, error, info, warn, Logger};
+use tokio::sync::mpsc;
+
+use crate::{
+ app, attestation, cache,
+ common::{
+ crypto::{hash::Hash, signature::Signer},
+ logger::get_logger,
+ panic::AbortOnPanic,
+ sgx::QuotePolicy,
+ },
+ consensus::{
+ beacon::EpochTime,
+ roothash::{self, ComputeResultsHeader, Header, COMPUTE_RESULTS_HEADER_SIGNATURE_CONTEXT},
+ state::keymanager::Status as KeyManagerStatus,
+ verifier::Verifier,
+ LightBlock,
+ },
+ enclave_rpc::{
+ demux::Demux as RpcDemux,
+ dispatcher::Dispatcher as RpcDispatcher,
+ session::{self, SessionInfo},
+ types::{
+ Kind as RpcKind, Message as RpcMessage, Request as RpcRequest, Response as RpcResponse,
+ },
+ Context as RpcContext,
+ },
+ future::block_on,
+ identity::Identity,
+ policy::PolicyVerifier,
+ protocol::Protocol,
+ storage::mkvs::{sync::NoopReadSyncer, OverlayTree, Root, RootType},
+ transaction::{
+ dispatcher::{Dispatcher as TxnDispatcher, NoopDispatcher as TxnNoopDispatcher},
+ tree::Tree as TxnTree,
+ types::TxnBatch,
+ Context as TxnContext,
+ },
+ types::{Body, ComputedBatch, Error, ExecutionMode},
+};
+
+/// Maximum amount of requests that can be in the dispatcher queue.
+const BACKLOG_SIZE: usize = 1000;
+
+/// Maximum total number of EnclaveRPC sessions.
+const RPC_MAX_SESSIONS: usize = 1024;
+/// Maximum concurrent EnclaveRPC sessions per peer. In case more sessions are open, old sessions
+/// will be closed to make room for new sessions.
+const RPC_MAX_SESSIONS_PER_PEER: usize = 8;
+/// EnclaveRPC sessions without any processed frame for more than RPC_STALE_SESSION_TIMEOUT_SECS
+/// seconds can be closed to make room for new sessions.
+const RPC_STALE_SESSION_TIMEOUT_SECS: i64 = 10;
+
+/// Interface for dispatcher initializers.
+pub trait Initializer: Send + Sync {
+ /// Initializes the dispatcher(s).
+ fn init(self: Box<Self>, state: PreInitState<'_>) -> PostInitState;
+}
+
+impl<F> Initializer for F
+where
+ F: FnOnce(PreInitState<'_>) -> PostInitState + Send + Sync,
+{
+ fn init(self: Box<Self>, state: PreInitState<'_>) -> PostInitState {
+ self(state)
+ }
+}
+
+/// State available before initialization.
+pub struct PreInitState<'a> {
+ /// Protocol instance.
+ pub protocol: &'a Arc<Protocol>,
+ /// Runtime Attestation Key instance.
+ pub identity: &'a Arc<Identity>,
+ /// RPC demultiplexer instance.
+ pub rpc_demux: &'a mut RpcDemux,
+ /// RPC dispatcher instance.
+ pub rpc_dispatcher: &'a mut RpcDispatcher,
+ /// Consensus verifier instance.
+ pub consensus_verifier: &'a Arc<dyn Verifier>,
+}
+
+/// State returned by the initializer.
+#[derive(Default)]
+pub struct PostInitState {
+ /// Optional transaction dispatcher that should be used.
+ pub txn_dispatcher: Option<Box<dyn TxnDispatcher>>,
+ /// Optional ROFL application.
+ pub app: Option<Box<dyn app::App>>,
+}
+
+impl From<tokio::task::JoinError> for Error {
+ fn from(e: tokio::task::JoinError) -> Self {
+ Error::new(
+ "dispatcher",
+ 1,
+ &format!("error while processing request: {e}"),
+ )
+ }
+}
+
+/// State related to dispatching a runtime transaction.
+struct TxDispatchState {
+ mode: ExecutionMode,
+ consensus_block: LightBlock,
+ consensus_verifier: Arc<dyn Verifier>,
+ header: Header,
+ epoch: EpochTime,
+ round_results: roothash::RoundResults,
+ max_messages: u32,
+ check_only: bool,
+}
+
+/// State provided by the protocol upon successful initialization.
+struct ProtocolState {
+ protocol: Arc<Protocol>,
+ consensus_verifier: Arc<dyn Verifier>,
+}
+
+/// State held by the dispatcher, shared between all async tasks.
+#[derive(Clone)]
+struct State {
+ protocol: Arc<Protocol>,
+ consensus_verifier: Arc<dyn Verifier>,
+ dispatcher: Arc<Dispatcher>,
+ app: Arc<dyn app::App>,
+ rpc_demux: Arc<RpcDemux>,
+ rpc_dispatcher: Arc<RpcDispatcher>,
+ txn_dispatcher: Arc<dyn TxnDispatcher>,
+ attestation_handler: attestation::Handler,
+ policy_verifier: Arc<PolicyVerifier>,
+ cache_set: cache::CacheSet,
+}
+
+#[derive(Debug)]
+enum Command {
+ Request(u64, Body),
+}
+
+/// Runtime call dispatcher.
+pub struct Dispatcher {
+ logger: Logger,
+ queue_tx: mpsc::Sender<Command>,
+ identity: Arc<Identity>,
+
+ state: Mutex<Option<ProtocolState>>,
+ state_cond: Condvar,
+
+ tokio_runtime: tokio::runtime::Handle,
+}
+
+impl Dispatcher {
+ /// Create a new runtime call dispatcher.
+ pub fn new(
+ tokio_runtime: tokio::runtime::Handle,
+ initializer: Box<dyn Initializer>,
+ identity: Arc<Identity>,
+ ) -> Arc<Self> {
+ let (tx, rx) = mpsc::channel(BACKLOG_SIZE);
+
+ let dispatcher = Arc::new(Dispatcher {
+ logger: get_logger("runtime/dispatcher"),
+ queue_tx: tx,
+ identity,
+ state: Mutex::new(None),
+ state_cond: Condvar::new(),
+ tokio_runtime,
+ });
+
+ // Spawn the dispatcher processing thread.
+ let d = dispatcher.clone();
+ thread::spawn(move || {
+ let _guard = AbortOnPanic;
+ d.run(initializer, rx);
+ });
+
+ dispatcher
+ }
+
+ /// Start the dispatcher.
+ pub fn start(&self, protocol: Arc<Protocol>, consensus_verifier: Box<dyn Verifier>) {
+ let consensus_verifier = Arc::from(consensus_verifier);
+ let mut s = self.state.lock().unwrap();
+ *s = Some(ProtocolState {
+ protocol,
+ consensus_verifier,
+ });
+ self.state_cond.notify_one();
+ }
+
+ /// Queue a new request to be dispatched.
+ pub fn queue_request(&self, id: u64, body: Body) -> AnyResult<()> {
+ self.queue_tx.blocking_send(Command::Request(id, body))?;
+ Ok(())
+ }
+
+ fn run(self: &Arc<Self>, initializer: Box<dyn Initializer>, mut rx: mpsc::Receiver<Command>) {
+ // Wait for the state to be available.
+ let ProtocolState {
+ protocol,
+ consensus_verifier,
+ } = {
+ let mut guard = self.state.lock().unwrap();
+ while guard.is_none() {
+ guard = self.state_cond.wait(guard).unwrap();
+ }
+
+ guard.take().unwrap()
+ };
+
+ // Ensure Tokio runtime is available during dispatcher initialization.
+ let _guard = self.tokio_runtime.enter();
+
+ // Create actual dispatchers for RPCs and transactions.
+ info!(self.logger, "Starting the runtime dispatcher");
+ let mut rpc_demux = RpcDemux::new(
+ session::Builder::default().local_identity(self.identity.clone()),
+ RPC_MAX_SESSIONS,
+ RPC_MAX_SESSIONS_PER_PEER,
+ RPC_STALE_SESSION_TIMEOUT_SECS,
+ );
+ let mut rpc_dispatcher = RpcDispatcher::default();
+ let pre_init_state = PreInitState {
+ protocol: &protocol,
+ identity: &self.identity,
+ rpc_demux: &mut rpc_demux,
+ rpc_dispatcher: &mut rpc_dispatcher,
+ consensus_verifier: &consensus_verifier,
+ };
+ let post_init_state = initializer.init(pre_init_state);
+ let txn_dispatcher = post_init_state
+ .txn_dispatcher
+ .unwrap_or_else(|| Box::<TxnNoopDispatcher>::default());
+ let mut app = post_init_state
+ .app
+ .unwrap_or_else(|| Box::new(app::NoopApp));
+
+ // Initialize the application.
+ if let Err(err) = app.on_init(protocol.clone()) {
+ error!(self.logger, "ROFL application initialization failed"; "err" => ?err);
+ }
+
+ let app: Arc<dyn app::App> = Arc::from(app);
+ let state = State {
+ protocol: protocol.clone(),
+ consensus_verifier: consensus_verifier.clone(),
+ dispatcher: self.clone(),
+ app: app.clone(),
+ rpc_demux: Arc::new(rpc_demux),
+ rpc_dispatcher: Arc::new(rpc_dispatcher),
+ txn_dispatcher: Arc::from(txn_dispatcher),
+ attestation_handler: attestation::Handler::new(
+ self.identity.clone(),
+ protocol.clone(),
+ consensus_verifier.clone(),
+ protocol.get_runtime_id(),
+ protocol.get_config().version,
+ app,
+ ),
+ policy_verifier: Arc::new(PolicyVerifier::new(consensus_verifier)),
+ cache_set: cache::CacheSet::new(protocol.clone()),
+ };
+
+ // Start the async message processing task.
+ self.tokio_runtime.block_on(async move {
+ while let Some(cmd) = rx.recv().await {
+ // Process received command.
+ match cmd {
+ Command::Request(id, request) => {
+ // Process request in its own task.
+ let state = state.clone();
+
+ tokio::spawn(async move {
+ let protocol = state.protocol.clone();
+ let dispatcher = state.dispatcher.clone();
+ let result = dispatcher.handle_request(state, request).await;
+
+ // Send response.
+ let response = match result {
+ Ok(body) => body,
+ Err(error) => Body::Error(error),
+ };
+ protocol.send_response(id, response).unwrap();
+ });
+ }
+ }
+ }
+ });
+
+ info!(self.logger, "Runtime call dispatcher is terminating");
+ }
+
+ async fn handle_request(self: &Arc<Self>, state: State, request: Body) -> Result<Body, Error> {
+ match request {
+ // Attestation-related requests.
+ Body::RuntimeCapabilityTEERakInitRequest { .. }
+ | Body::RuntimeCapabilityTEERakReportRequest {}
+ | Body::RuntimeCapabilityTEERakAvrRequest { .. }
+ | Body::RuntimeCapabilityTEERakQuoteRequest { .. }
+ | Body::RuntimeCapabilityTEEUpdateEndorsementRequest { .. } => {
+ Ok(state.attestation_handler.handle(request).await?)
+ }
+
+ // RPC requests.
+ Body::RuntimeRPCCallRequest {
+ request,
+ kind,
+ peer_id,
+ } => {
+ debug!(self.logger, "Received RPC call request";
+ "kind" => ?kind,
+ "peer_id" => peer_id.to_hex::<String>(),
+ );
+
+ match kind {
+ RpcKind::NoiseSession => {
+ self.dispatch_secure_rpc(state, request, peer_id).await
+ }
+ RpcKind::InsecureQuery => self.dispatch_insecure_rpc(state, request).await,
+ RpcKind::LocalQuery => self.dispatch_local_rpc(state, request).await,
+ }
+ }
+ Body::RuntimeLocalRPCCallRequest { request } => {
+ debug!(self.logger, "Received RPC call request";
+ "kind" => ?RpcKind::LocalQuery,
+ );
+
+ self.dispatch_local_rpc(state, request).await
+ }
+
+ // RONL.
+ // TODO: Refactor this so it can be part of an "app".
+ Body::RuntimeExecuteTxBatchRequest {
+ mode,
+ consensus_block,
+ round_results,
+ io_root,
+ inputs,
+ in_msgs,
+ block,
+ epoch,
+ max_messages,
+ } => {
+ // Transaction execution.
+ self.dispatch_txn(
+ state.cache_set,
+ &state.txn_dispatcher,
+ &state.protocol,
+ io_root,
+ inputs.unwrap_or_default(),
+ in_msgs,
+ TxDispatchState {
+ mode,
+ consensus_block,
+ consensus_verifier: state.consensus_verifier,
+ header: block.header,
+ epoch,
+ round_results,
+ max_messages,
+ check_only: false,
+ },
+ )
+ .await
+ }
+ Body::RuntimeCheckTxBatchRequest {
+ consensus_block,
+ inputs,
+ block,
+ epoch,
+ max_messages,
+ } => {
+ // Transaction check.
+ self.dispatch_txn(
+ state.cache_set,
+ &state.txn_dispatcher,
+ &state.protocol,
+ Hash::default(),
+ inputs,
+ vec![],
+ TxDispatchState {
+ mode: ExecutionMode::Execute,
+ consensus_block,
+ consensus_verifier: state.consensus_verifier,
+ header: block.header,
+ epoch,
+ round_results: Default::default(),
+ max_messages,
+ check_only: true,
+ },
+ )
+ .await
+ }
+ Body::RuntimeQueryRequest {
+ consensus_block,
+ header,
+ epoch,
+ max_messages,
+ method,
+ args,
+ } if state.txn_dispatcher.is_supported() => {
+ // Query.
+ self.dispatch_query(
+ state.cache_set,
+ &state.txn_dispatcher,
+ &state.protocol,
+ method,
+ args,
+ TxDispatchState {
+ mode: ExecutionMode::Execute,
+ consensus_block,
+ consensus_verifier: state.consensus_verifier,
+ header,
+ epoch,
+ round_results: Default::default(),
+ max_messages,
+ check_only: true,
+ },
+ )
+ .await
+ }
+
+ // ROFL.
+ Body::RuntimeQueryRequest { method, args, .. } if state.app.is_rofl() => state
+ .app
+ .query(&method, args)
+ .await
+ .map(|data| Body::RuntimeQueryResponse { data })
+ .map_err(Into::into),
+ Body::RuntimeNotifyRequest {
+ runtime_block,
+ runtime_event,
+ } => {
+ if let Some(runtime_block) = runtime_block {
+ if let Err(err) = state.app.on_runtime_block(&runtime_block).await {
+ error!(self.logger, "Application block notification failed"; "err" => ?err);
+ }
+ }
+ if let Some(runtime_event) = runtime_event {
+ if let Err(err) = state
+ .app
+ .on_runtime_event(&runtime_event.block, &runtime_event.tags)
+ .await
+ {
+ error!(self.logger, "Application event notification failed"; "err" => ?err);
+ }
+ }
+
+ Ok(Body::Empty {})
+ }
+
+ // Other requests.
+ Body::RuntimeKeyManagerStatusUpdateRequest { status } => {
+ // Key manager status update local RPC call.
+ self.handle_km_status_update(state, status).await
+ }
+ Body::RuntimeKeyManagerQuotePolicyUpdateRequest {
+ policy: quote_policy,
+ } => {
+ // Key manager quote policy update local RPC call.
+ self.handle_km_quote_policy_update(state, quote_policy)
+ .await
+ }
+ Body::RuntimeConsensusSyncRequest { height } => state
+ .consensus_verifier
+ .sync(height)
+ .await
+ .map_err(Into::into)
+ .map(|_| Body::RuntimeConsensusSyncResponse {}),
+
+ _ => {
+ error!(self.logger, "Unsupported request type");
+ Err(Error::new("dispatcher", 1, "Unsupported request type"))
+ }
+ }
+ }
+
+ #[allow(clippy::too_many_arguments)]
+ async fn dispatch_query(
+ &self,
+ cache_set: cache::CacheSet,
+ txn_dispatcher: &Arc<dyn TxnDispatcher>,
+ protocol: &Arc<Protocol>,
+ method: String,
+ args: Vec<u8>,
+ state: TxDispatchState,
+ ) -> Result<Body, Error> {
+ debug!(self.logger, "Received query request";
+ "method" => &method,
+ "state_root" => ?state.header.state_root,
+ "round" => ?state.header.round,
+ );
+
+ // Verify that the runtime ID matches the block's namespace. This is a protocol violation
+ // as the compute node should never change the runtime ID.
+ if state.header.namespace != protocol.get_runtime_id() {
+ return Err(Error::new(
+ "dispatcher",
+ 1,
+ &format!(
+ "block namespace does not match runtime id (namespace: {:?} runtime ID: {:?})",
+ state.header.namespace,
+ protocol.get_runtime_id(),
+ ),
+ ));
+ }
+
+ let protocol = protocol.clone();
+ let txn_dispatcher = txn_dispatcher.clone();
+
+ // For queries we don't do any consensus layer integrity verification by default and it
+ // is up to the runtime to decide whether this is critical on a query-by-query basis.
+ let consensus_state = state
+ .consensus_verifier
+ .unverified_state(state.consensus_block.clone())
+ .await?;
+
+ tokio::task::spawn_blocking(move || {
+ let cache = cache_set.query(Root {
+ namespace: state.header.namespace,
+ version: state.header.round,
+ root_type: RootType::State,
+ hash: state.header.state_root,
+ });
+ let mut cache = cache.borrow_mut();
+ let mut overlay = OverlayTree::new(cache.tree_mut());
+
+ let txn_ctx = TxnContext::new(
+ protocol,
+ &state.consensus_block,
+ consensus_state,
+ &mut overlay,
+ &state.header,
+ state.epoch,
+ &state.round_results,
+ state.max_messages,
+ state.check_only,
+ );
+
+ txn_dispatcher
+ .query(txn_ctx, &method, args)
+ .map(|data| Body::RuntimeQueryResponse { data })
+ })
+ .await?
+ }
+
+ fn txn_check_batch(
+ &self,
+ protocol: Arc<Protocol>,
+ cache_set: cache::CacheSet,
+ txn_dispatcher: &dyn TxnDispatcher,
+ inputs: TxnBatch,
+ state: TxDispatchState,
+ ) -> Result<Body, Error> {
+ // For check-only we don't do any consensus layer integrity verification.
+ // TODO: Make this async.
+ let consensus_state = block_on(
+ state
+ .consensus_verifier
+ .unverified_state(state.consensus_block.clone()),
+ )?;
+
+ let mut cache = cache_set.check(Root {
+ namespace: state.header.namespace,
+ version: state.header.round,
+ root_type: RootType::State,
+ hash: state.header.state_root,
+ });
+ let mut overlay = OverlayTree::new(cache.tree_mut());
+
+ let txn_ctx = TxnContext::new(
+ protocol.clone(),
+ &state.consensus_block,
+ consensus_state,
+ &mut overlay,
+ &state.header,
+ state.epoch,
+ &state.round_results,
+ state.max_messages,
+ state.check_only,
+ );
+ let results = txn_dispatcher.check_batch(txn_ctx, &inputs);
+
+ if protocol.get_config().persist_check_tx_state {
+ // Commit results to in-memory tree so they persist for subsequent batches that are
+ // based on the same block.
+ let _ = overlay.commit().unwrap();
+ }
+
+ debug!(self.logger, "Transaction batch check complete");
+
+ results.map(|results| Body::RuntimeCheckTxBatchResponse { results })
+ }
+
+ #[allow(clippy::too_many_arguments)]
+ fn txn_execute_batch(
+ &self,
+ protocol: Arc<Protocol>,
+ cache_set: cache::CacheSet,
+ txn_dispatcher: &dyn TxnDispatcher,
+ mut inputs: TxnBatch,
+ in_msgs: Vec<roothash::IncomingMessage>,
+ io_root: Hash,
+ state: TxDispatchState,
+ ) -> Result<Body, Error> {
+ // Verify consensus state and runtime state root integrity before execution.
+ // TODO: Make this async.
+ let consensus_state = block_on(state.consensus_verifier.verify(
+ state.consensus_block.clone(),
+ state.header.clone(),
+ state.epoch,
+ ))?;
+ // Ensure the runtime is still ready to process requests.
+ protocol.ensure_initialized()?;
+
+ let header = &state.header;
+
+ let mut cache = cache_set.execute(Root {
+ namespace: state.header.namespace,
+ version: state.header.round,
+ root_type: RootType::State,
+ hash: state.header.state_root,
+ });
+ let mut overlay = OverlayTree::new(cache.tree_mut());
+
+ let txn_ctx = TxnContext::new(
+ protocol,
+ &state.consensus_block,
+ consensus_state,
+ &mut overlay,
+ header,
+ state.epoch,
+ &state.round_results,
+ state.max_messages,
+ state.check_only,
+ );
+
+ // Perform execution based on the passed mode.
+ let mut results = match state.mode {
+ ExecutionMode::Execute => {
+ // Just execute the batch.
+ txn_dispatcher.execute_batch(txn_ctx, &inputs, &in_msgs)?
+ }
+ ExecutionMode::Schedule => {
+ // Allow the runtime to arbitrarily update the batch.
+ txn_dispatcher.schedule_and_execute_batch(txn_ctx, &mut inputs, &in_msgs)?
+ }
+ };
+
+ // Finalize state.
+ let (state_write_log, new_state_root) = overlay
+ .commit_both(header.namespace, header.round + 1)
+ .expect("state commit must succeed");
+
+ txn_dispatcher.finalize(new_state_root);
+ cache.commit(header.round + 1, new_state_root);
+
+ // Generate I/O root. Since we already fetched the inputs we avoid the need
+ // to fetch them again by generating the previous I/O tree (generated by the
+ // transaction scheduler) from the inputs.
+ let mut txn_tree = TxnTree::new(
+ Box::new(NoopReadSyncer),
+ Root {
+ namespace: header.namespace,
+ version: header.round + 1,
+ root_type: RootType::IO,
+ hash: Hash::empty_hash(),
+ },
+ );
+ let mut hashes = Vec::new();
+ for (batch_order, input) in inputs.drain(..).enumerate() {
+ hashes.push(Hash::digest_bytes(&input));
+ txn_tree
+ .add_input(input, batch_order.try_into().unwrap())
+ .expect("add transaction must succeed");
+ }
+
+ let (input_write_log, input_io_root) = txn_tree.commit().expect("io commit must succeed");
+
+ assert!(
+ state.mode != ExecutionMode::Execute || input_io_root == io_root,
+ "dispatcher: I/O root inconsistent with inputs (expected: {:?} got: {:?})",
+ io_root,
+ input_io_root
+ );
+
+ for (tx_hash, result) in hashes.iter().zip(results.results.drain(..)) {
+ txn_tree
+ .add_output(*tx_hash, result.output, result.tags)
+ .expect("add transaction must succeed");
+ }
+
+ txn_tree
+ .add_block_tags(results.block_tags)
+ .expect("adding block tags must succeed");
+
+ let (io_write_log, io_root) = txn_tree.commit().expect("io commit must succeed");
+
+ let header = ComputeResultsHeader {
+ round: header.round + 1,
+ previous_hash: header.encoded_hash(),
+ io_root: Some(io_root),
+ state_root: Some(new_state_root),
+ messages_hash: Some(roothash::Message::messages_hash(&results.messages)),
+ in_msgs_hash: Some(roothash::IncomingMessage::in_messages_hash(
+ &in_msgs[..results.in_msgs_count],
+ )),
+ in_msgs_count: results.in_msgs_count.try_into().unwrap(),
+ };
+
+ debug!(self.logger, "Transaction batch execution complete";
+ "previous_hash" => ?header.previous_hash,
+ "io_root" => ?header.io_root,
+ "state_root" => ?header.state_root,
+ "messages_hash" => ?header.messages_hash,
+ "in_msgs_hash" => ?header.in_msgs_hash,
+ );
+
+ let rak_sig = self
+ .identity
+ .sign(
+ COMPUTE_RESULTS_HEADER_SIGNATURE_CONTEXT,
+ &cbor::to_vec(header.clone()),
+ )
+ .unwrap();
+
+ Ok(Body::RuntimeExecuteTxBatchResponse {
+ batch: ComputedBatch {
+ header,
+ io_write_log,
+ state_write_log,
+ rak_sig,
+ messages: results.messages,
+ },
+ tx_hashes: hashes,
+ tx_reject_hashes: results.tx_reject_hashes,
+ tx_input_root: input_io_root,
+ tx_input_write_log: input_write_log,
+ })
+ }
+
+ #[allow(clippy::too_many_arguments)]
+ async fn dispatch_txn(
+ self: &Arc<Self>,
+ cache_set: cache::CacheSet,
+ txn_dispatcher: &Arc<dyn TxnDispatcher>,
+ protocol: &Arc<Protocol>,
+ io_root: Hash,
+ inputs: TxnBatch,
+ in_msgs: Vec<roothash::IncomingMessage>,
+ state: TxDispatchState,
+ ) -> Result<Body, Error> {
+ // Make sure to abort the process on panic during transaction processing as that indicates
+ // a serious problem and should make sure to clean up the process.
+ let _guard = AbortOnPanic;
+
+ debug!(self.logger, "Received transaction batch request";
+ "state_root" => ?state.header.state_root,
+ "round" => state.header.round + 1,
+ "round_results" => ?state.round_results,
+ "tx_count" => inputs.len(),
+ "in_msg_count" => in_msgs.len(),
+ "check_only" => state.check_only,
+ );
+
+ // Verify that the runtime ID matches the block's namespace. This is a protocol violation
+ // as the compute node should never change the runtime ID.
+ assert!(
+ state.header.namespace == protocol.get_runtime_id(),
+ "block namespace does not match runtime id (namespace: {:?} runtime ID: {:?})",
+ state.header.namespace,
+ protocol.get_runtime_id(),
+ );
+
+ let protocol = protocol.clone();
+ let dispatcher = self.clone();
+ let txn_dispatcher = txn_dispatcher.clone();
+
+ tokio::task::spawn_blocking(move || {
+ if state.check_only {
+ dispatcher.txn_check_batch(protocol, cache_set, &txn_dispatcher, inputs, state)
+ } else {
+ dispatcher.txn_execute_batch(
+ protocol,
+ cache_set,
+ &txn_dispatcher,
+ inputs,
+ in_msgs,
+ io_root,
+ state,
+ )
+ }
+ })
+ .await
+ .unwrap() // Propagate panics during transaction dispatch.
+ }
+
+ async fn dispatch_secure_rpc(
+ &self,
+ state: State,
+ request: Vec<u8>,
+ peer_id: Vec<u8>,
+ ) -> Result<Body, Error> {
+ // Make sure to abort the process on panic during RPC processing as that indicates a
+ // serious problem and should make sure to clean up the process.
+ let _guard = AbortOnPanic;
+
+ // Process frame.
+ let mut buffer = vec![];
+ let (mut session, message) = state
+ .rpc_demux
+ .process_frame(peer_id, request, &mut buffer)
+ .await?;
+
+ if let Some(message) = message {
+ // Dispatch request.
+ assert!(
+ buffer.is_empty(),
+ "must have no handshake data in transport mode"
+ );
+
+ match message {
+ RpcMessage::Request(req) => {
+ // Request, dispatch.
+ let response = self
+ .dispatch_rpc(req, RpcKind::NoiseSession, session.info(), &state)
+ .await?;
+ let response = RpcMessage::Response(response);
+
+ // Note: MKVS commit is omitted, this MUST be global side-effect free.
+
+ debug!(self.logger, "RPC call dispatch complete";
+ "kind" => ?RpcKind::NoiseSession,
+ );
+
+ let mut buffer = vec![];
+ session
+ .write_message(response, &mut buffer)
+ .map_err(|err| {
+ error!(self.logger, "Error while writing response"; "err" => %err);
+ Error::new("rhp/dispatcher", 1, &format!("{err}"))
+ })
+ .map(|_| Body::RuntimeRPCCallResponse { response: buffer })
+ }
+ RpcMessage::Close => {
+ // Session close.
+ let mut buffer = vec![];
+ state
+ .rpc_demux
+ .close(session, &mut buffer)
+ .map_err(|err| {
+ error!(self.logger, "Error while closing session"; "err" => %err);
+ Error::new("rhp/dispatcher", 1, &format!("{err}"))
+ })
+ .map(|_| Body::RuntimeRPCCallResponse { response: buffer })
+ }
+ msg => {
+ warn!(self.logger, "Ignoring invalid RPC message type"; "msg" => ?msg);
+ Err(Error::new("rhp/dispatcher", 1, "invalid RPC message type"))
+ }
+ }
+ } else {
+ // Send back any handshake frames.
+ Ok(Body::RuntimeRPCCallResponse { response: buffer })
+ }
+ }
+
+ async fn dispatch_insecure_rpc(&self, state: State, request: Vec<u8>) -> Result<Body, Error> {
+ // Make sure to abort the process on panic during RPC processing as that indicates a
+ // serious problem and should make sure to clean up the process.
+ let _guard = AbortOnPanic;
+
+ let request: RpcRequest = cbor::from_slice(&request)
+ .map_err(|_| Error::new("rhp/dispatcher", 1, "malformed request"))?;
+
+ // Request, dispatch.
+ let response = self
+ .dispatch_rpc(request, RpcKind::InsecureQuery, None, &state)
+ .await?;
+ let response = cbor::to_vec(response);
+
+ // Note: MKVS commit is omitted, this MUST be global side-effect free.
+
+ debug!(self.logger, "RPC call dispatch complete";
+ "kind" => ?RpcKind::InsecureQuery,
+ );
+
+ Ok(Body::RuntimeRPCCallResponse { response })
+ }
+
+ async fn dispatch_local_rpc(&self, state: State, request: Vec<u8>) -> Result<Body, Error> {
+ // Make sure to abort the process on panic during local RPC processing as that indicates a
+ // serious problem and should make sure to clean up the process.
+ let _guard = AbortOnPanic;
+
+ let request = cbor::from_slice(&request)
+ .map_err(|_| Error::new("rhp/dispatcher", 1, "malformed request"))?;
+
+ // Request, dispatch.
+ let response = self
+ .dispatch_rpc(request, RpcKind::LocalQuery, None, &state)
+ .await?;
+ let response = RpcMessage::Response(response);
+ let response = cbor::to_vec(response);
+
+ debug!(self.logger, "RPC call dispatch complete";
+ "kind" => ?RpcKind::LocalQuery,
+ );
+
+ Ok(Body::RuntimeLocalRPCCallResponse { response })
+ }
+
+ async fn dispatch_rpc(
+ &self,
+ request: RpcRequest,
+ kind: RpcKind,
+ session_info: Option<Arc<SessionInfo>>,
+ state: &State,
+ ) -> Result<RpcResponse, Error> {
+ let rpc_dispatcher = state.rpc_dispatcher.clone();
+
+ let response = tokio::task::spawn_blocking(move || {
+ let rpc_ctx = RpcContext::new(session_info);
+ rpc_dispatcher.dispatch(rpc_ctx, request, kind)
+ })
+ .await?;
+
+ Ok(response)
+ }
+
+ async fn handle_km_status_update(
+ &self,
+ state: State,
+ status: KeyManagerStatus,
+ ) -> Result<Body, Error> {
+ // Make sure to abort the process on panic during policy processing as that indicates a
+ // serious problem and should make sure to clean up the process.
+ let _guard = AbortOnPanic;
+
+ debug!(self.logger, "Received km status update request");
+
+ // Verify and decode the status.
+ let runtime_id = state.protocol.get_host_info().runtime_id;
+
+ tokio::task::spawn_blocking(move || -> Result<(), Error> {
+ let key_manager = state.policy_verifier.key_manager(&runtime_id)?;
+ let published_status = state
+ .policy_verifier
+ .verify_key_manager_status(status, key_manager)?;
+
+ // Dispatch the local RPC call.
+ state
+ .rpc_dispatcher
+ .handle_km_status_update(published_status);
+
+ Ok(())
+ })
+ .await
+ .unwrap()?; // Propagate panics during key manager status update.
+
+ debug!(self.logger, "KM status update request complete");
+
+ Ok(Body::RuntimeKeyManagerStatusUpdateResponse {})
+ }
+
+ async fn handle_km_quote_policy_update(
+ &self,
+ state: State,
+ quote_policy: QuotePolicy,
+ ) -> Result<Body, Error> {
+ // Make sure to abort the process on panic during quote policy processing as that indicates
+ // a serious problem and should make sure to clean up the process.
+ let _guard = AbortOnPanic;
+
+ debug!(self.logger, "Received km quote policy update request");
+
+ // Verify and decode the policy.
+ let runtime_id = state.protocol.get_host_info().runtime_id;
+
+ tokio::task::spawn_blocking(move || -> Result<(), Error> {
+ let key_manager = state.policy_verifier.key_manager(&runtime_id)?;
+ let policy =
+ state
+ .policy_verifier
+ .verify_quote_policy(quote_policy, &key_manager, None)?;
+
+ // Dispatch the local RPC call.
+ state.rpc_dispatcher.handle_km_quote_policy_update(policy);
+
+ Ok(())
+ })
+ .await
+ .unwrap()?; // Propagate panics during key manager quote policy update.
+
+ debug!(self.logger, "KM quote policy update request complete");
+
+ Ok(Body::RuntimeKeyManagerQuotePolicyUpdateResponse {})
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +765 +766 +767 +768 +769 +770 +771 +772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805 +806 +807 +808 +809 +810 +811 +812 +813 +814 +815 +816 +817 +818 +819 +820 +821 +822 +823 +824 +825 +826 +827 +828 +829 +830 +831 +832 +833 +834 +835 +836 +837 +838 +839 +840 +841 +842 +843 +844 +845 +846 +847 +848 +849 +850 +851 +852 +853 +854 +855 +856 +857 +858 +859 +860 +861 +862 +863 +864 +865 +866 +867 +868 +869 +870 +871 +872 +873 +874 +875 +876 +877 +878 +879 +880 +881 +882 +883 +884 +885 +886 +887 +888 +889 +890 +891 +892 +893 +894 +895 +
//! Enclave RPC client.
+use std::{
+ collections::HashSet,
+ sync::{
+ atomic::{AtomicU32, Ordering},
+ Arc,
+ },
+};
+
+use futures::stream::{FuturesUnordered, StreamExt};
+use lazy_static::lazy_static;
+#[cfg(not(test))]
+use rand::{rngs::OsRng, RngCore};
+
+use thiserror::Error;
+use tokio::sync::OwnedMutexGuard;
+
+use crate::{
+ common::{
+ crypto::signature,
+ namespace::Namespace,
+ sgx::{EnclaveIdentity, QuotePolicy},
+ time::insecure_posix_time,
+ },
+ enclave_rpc::{session::Builder, types},
+ future::block_on,
+ protocol::Protocol,
+};
+
+use super::{
+ sessions::{self, MultiplexedSession, Sessions, SharedSession},
+ transport::{RuntimeTransport, Transport},
+};
+
+/// Maximum number of retries on transport errors.
+const MAX_TRANSPORT_ERROR_RETRIES: usize = 3;
+
+lazy_static! {
+ /// The ID of the next RPC client.
+ static ref NEXT_CLIENT_ID: AtomicU32 = AtomicU32::new(RpcClient::random_client_id());
+}
+
+/// RPC client error.
+#[derive(Error, Debug)]
+pub enum RpcClientError {
+ #[error("call failed: {0}")]
+ CallFailed(String),
+ #[error("expected response message, received: {0:?}")]
+ ExpectedResponseMessage(types::Message),
+ #[error("expected close message, received: {0:?}")]
+ ExpectedCloseMessage(types::Message),
+ #[error("transport error")]
+ Transport,
+ #[error("unsupported RPC kind")]
+ UnsupportedRpcKind,
+ #[error("client dropped")]
+ Dropped,
+ #[error("decode error: {0}")]
+ DecodeError(#[from] cbor::DecodeError),
+ #[error("sessions error: {0}")]
+ SessionsError(#[from] sessions::Error),
+ #[error("unknown error: {0}")]
+ Unknown(#[from] anyhow::Error),
+}
+
+/// An EnclaveRPC response that can be used to provide peer feedback.
+pub struct Response<'a, T> {
+ transport: &'a dyn Transport,
+ request_id: Option<u64>,
+ inner: Result<T, RpcClientError>,
+}
+
+impl<'a, T> Response<'a, T> {
+ /// Report success if result was `Ok(_)` and failure if result was `Err(_)`, then return the
+ /// inner result consuming the response instance.
+ pub async fn into_result_with_feedback(mut self) -> Result<T, RpcClientError> {
+ match self.inner {
+ Ok(_) => self.success().await,
+ Err(_) => self.failure().await,
+ }
+
+ self.inner
+ }
+
+ /// Reference to inner result.
+ pub fn result(&self) -> &Result<T, RpcClientError> {
+ &self.inner
+ }
+
+ /// Consume the response instance returning the inner result.
+ pub fn into_result(self) -> Result<T, RpcClientError> {
+ self.inner
+ }
+
+ /// Report success as peer feedback.
+ pub async fn success(&mut self) {
+ self.send_peer_feedback(types::PeerFeedback::Success).await;
+ }
+
+ /// Report failure as peer feedback.
+ pub async fn failure(&mut self) {
+ self.send_peer_feedback(types::PeerFeedback::Failure).await;
+ }
+
+ /// Report bad peer as peer feedback.
+ pub async fn bad_peer(&mut self) {
+ self.send_peer_feedback(types::PeerFeedback::BadPeer).await;
+ }
+
+ /// Send peer feedback.
+ async fn send_peer_feedback(&mut self, feedback: types::PeerFeedback) {
+ if let Some(request_id) = self.request_id.take() {
+ // Only count feedback once.
+ let _ = self
+ .transport
+ .submit_peer_feedback(request_id, feedback)
+ .await; // Ignore error.
+ }
+ }
+}
+
+/// RPC client.
+pub struct RpcClient {
+ /// Used transport.
+ transport: Box<dyn Transport>,
+ /// Multiplexed sessions.
+ sessions: tokio::sync::Mutex<Sessions<signature::PublicKey>>,
+ /// The ID of the client.
+ client_id: u32,
+ /// The ID of the next transport request.
+ next_request_id: AtomicU32,
+}
+
+impl RpcClient {
+ fn new(
+ transport: Box<dyn Transport>,
+ builder: Builder,
+ max_sessions: usize,
+ max_sessions_per_peer: usize,
+ stale_session_timeout: i64,
+ ) -> Self {
+ // Assign a unique ID to each client to avoid overlapping request IDs.
+ let client_id = NEXT_CLIENT_ID.fetch_add(1, Ordering::SeqCst); // Wraps if overflows.
+ let next_request_id = AtomicU32::new(1);
+
+ let sessions = tokio::sync::Mutex::new(Sessions::new(
+ builder,
+ max_sessions,
+ max_sessions_per_peer,
+ stale_session_timeout,
+ ));
+
+ Self {
+ transport,
+ sessions,
+ client_id,
+ next_request_id,
+ }
+ }
+
+ /// Construct an unconnected RPC client with runtime-internal transport.
+ pub fn new_runtime(
+ protocol: Arc<Protocol>,
+ endpoint: &str,
+ builder: Builder,
+ max_sessions: usize,
+ max_sessions_per_peer: usize,
+ stale_session_timeout: i64,
+ ) -> Self {
+ let transport = Box::new(RuntimeTransport::new(protocol, endpoint));
+
+ Self::new(
+ transport,
+ builder,
+ max_sessions,
+ max_sessions_per_peer,
+ stale_session_timeout,
+ )
+ }
+
+ /// Update allowed remote enclave identities.
+ pub async fn update_enclaves(&self, enclaves: Option<HashSet<EnclaveIdentity>>) {
+ let sessions = {
+ let mut sessions = self.sessions.lock().await;
+ sessions.update_enclaves(enclaves)
+ };
+ self.close_all(sessions).await;
+ }
+
+ /// Update remote end's quote policy.
+ pub async fn update_quote_policy(&self, policy: QuotePolicy) {
+ let sessions = {
+ let mut sessions = self.sessions.lock().await;
+ sessions.update_quote_policy(policy)
+ };
+ self.close_all(sessions).await;
+ }
+
+ /// Update remote runtime id.
+ pub async fn update_runtime_id(&self, id: Option<Namespace>) {
+ let sessions = {
+ let mut sessions = self.sessions.lock().await;
+ sessions.update_runtime_id(id)
+ };
+ self.close_all(sessions).await;
+ }
+
+ /// Call a remote method using an encrypted and authenticated Noise session.
+ pub async fn secure_call<C, O>(
+ &self,
+ method: &'static str,
+ args: C,
+ nodes: Vec<signature::PublicKey>,
+ ) -> Response<O>
+ where
+ C: cbor::Encode,
+ O: cbor::Decode + Send + 'static,
+ {
+ self.call(method, args, types::Kind::NoiseSession, nodes)
+ .await
+ }
+
+ /// Call a remote method over an insecure channel where messages are sent in plain text.
+ pub async fn insecure_call<C, O>(
+ &self,
+ method: &'static str,
+ args: C,
+ nodes: Vec<signature::PublicKey>,
+ ) -> Response<O>
+ where
+ C: cbor::Encode,
+ O: cbor::Decode + Send + 'static,
+ {
+ self.call(method, args, types::Kind::InsecureQuery, nodes)
+ .await
+ }
+
+ async fn call<C, O>(
+ &self,
+ method: &'static str,
+ args: C,
+ kind: types::Kind,
+ nodes: Vec<signature::PublicKey>,
+ ) -> Response<O>
+ where
+ C: cbor::Encode,
+ O: cbor::Decode + Send + 'static,
+ {
+ let request = types::Request {
+ method: method.to_owned(),
+ args: cbor::to_value(args),
+ };
+
+ // In case the `execute_call` method returns an outer error, this means that there was a
+ // problem with the transport itself and we can retry.
+ let retry_strategy = tokio_retry::strategy::ExponentialBackoff::from_millis(2)
+ .factor(25)
+ .max_delay(std::time::Duration::from_millis(250))
+ .take(MAX_TRANSPORT_ERROR_RETRIES);
+
+ let result = tokio_retry::Retry::spawn(retry_strategy, || {
+ self.execute_call(request.clone(), kind, nodes.clone())
+ })
+ .await;
+
+ let (request_id, inner) = match result {
+ Ok((request_id, response)) => match response.body {
+ types::Body::Success(value) => (
+ Some(request_id),
+ cbor::from_value(value).map_err(Into::into),
+ ),
+ types::Body::Error(error) => {
+ (Some(request_id), Err(RpcClientError::CallFailed(error)))
+ }
+ },
+ Err(err) => (None, Err(err)),
+ };
+
+ Response {
+ transport: &*self.transport,
+ request_id,
+ inner,
+ }
+ }
+
+ async fn execute_call(
+ &self,
+ request: types::Request,
+ kind: types::Kind,
+ nodes: Vec<signature::PublicKey>,
+ ) -> Result<(u64, types::Response), RpcClientError> {
+ match kind {
+ types::Kind::NoiseSession => {
+ // Attempt to establish a connection. This will not do anything in case the
+ // session has already been established.
+ let session = self.connect(nodes).await?;
+ let mut session = session.lock_owned().await;
+
+ // Perform the call.
+ let result = self.secure_call_raw(request, &mut session).await;
+
+ // In case there was a transport error we need to remove the session immediately
+ // as no progress is possible. The next call should select another peer or
+ // the same peer but another session.
+ if result.is_err() {
+ let mut sessions = self.sessions.lock().await;
+ sessions.remove(&session);
+ }
+
+ result
+ }
+ types::Kind::InsecureQuery => {
+ // Perform the call.
+ self.insecure_call_raw(request, nodes).await
+ }
+ _ => Err(RpcClientError::UnsupportedRpcKind),
+ }
+ }
+
+ async fn connect(
+ &self,
+ nodes: Vec<signature::PublicKey>,
+ ) -> Result<SharedSession<signature::PublicKey>, RpcClientError> {
+ // Create a new session.
+ let mut session = {
+ let mut sessions = self.sessions.lock().await;
+
+ // No need to create a new session if we are connected to one of the nodes.
+ if let Some(session) = sessions.find(&nodes) {
+ return Ok(session);
+ }
+
+ // Since the peer ID is not yet known, use the default value and set it later.
+ let peer_id = Default::default();
+ sessions.create_initiator(peer_id)
+ };
+
+ // Copy session ID to avoid moved value errors.
+ let session_id = *session.get_session_id();
+
+ // Prepare buffers upfront.
+ let mut buffer1 = vec![];
+ let mut buffer2 = vec![];
+
+ // Session Handshake1: prepare initialization request.
+ session
+ .process_data(&[], &mut buffer1)
+ .await
+ .expect("initiation must always succeed");
+
+ let request_id = self.next_request_id();
+ let result: Result<_, RpcClientError> = async {
+ // Transport: send initialization request and receive a response.
+ let rsp = self
+ .transport
+ .write_noise_session(request_id, session_id, buffer1, String::new(), nodes)
+ .await
+ .map_err(|_| RpcClientError::Transport)?;
+
+ // Update the session with unverified identity of the remote node.
+ // The identity will be verified in Handshake2 using the RAK from
+ // the consensus layer.
+ session.set_peer_id(rsp.node);
+ session
+ .set_remote_node(rsp.node)
+ .expect("remote node should not be set");
+
+ // Session Handshake2: process initialization response, verify
+ // remote node, and prepare the next request containing RAK binding.
+ let _ = session
+ .process_data(&rsp.data, &mut buffer2)
+ .await
+ .map_err(|_| RpcClientError::Transport)?;
+
+ Ok(rsp)
+ }
+ .await;
+
+ // Submit peer feedback for the last transport and the received
+ // initialization response.
+ let feedback = match result {
+ Ok(_) => types::PeerFeedback::Success,
+ Err(_) => types::PeerFeedback::Failure,
+ };
+ let _ = self
+ .transport
+ .submit_peer_feedback(request_id, feedback)
+ .await; // Ignore error.
+
+ // Forward error after peer feedback is sent.
+ let rsp = result?;
+
+ let request_id = self.next_request_id();
+ let result = async {
+ // Transport: send RAK binding request.
+ let rsp = self
+ .transport
+ .write_noise_session(
+ request_id,
+ session_id,
+ buffer2,
+ String::new(),
+ vec![rsp.node],
+ )
+ .await
+ .map_err(|_| RpcClientError::Transport)?;
+
+ if session.is_unauthenticated() {
+ return Err(RpcClientError::Transport);
+ }
+
+ Ok(rsp)
+ }
+ .await;
+
+ // Submit peer feedback for the last transport and session
+ // authentication.
+ let feedback = match result {
+ Ok(_) => types::PeerFeedback::Success,
+ Err(_) => types::PeerFeedback::Failure,
+ };
+ let _ = self
+ .transport
+ .submit_peer_feedback(request_id, feedback)
+ .await; // Ignore error.
+
+ // Forward error after peer feedback is sent.
+ if let Err(err) = result {
+ // Failed to complete handshake. Gracefully close the session.
+ let session = Arc::new(tokio::sync::Mutex::new(session))
+ .lock_owned()
+ .await;
+ let _ = self.close(session).await; // Ignore error.
+
+ return Err(err);
+ }
+
+ // The connection has been successfully established. The session can
+ // be added to the set of active sessions if there is space available,
+ // or if we can make space by removing a stale session.
+ let now = insecure_posix_time();
+ let mut sessions = self.sessions.lock().await;
+ let maybe_removed_session = match sessions.remove_for(&rsp.node, now) {
+ Ok(maybe_removed_session) => maybe_removed_session,
+ Err(err) => {
+ // Unable to make space. Gracefully close the session.
+ drop(sessions); // Unlock.
+
+ let session = Arc::new(tokio::sync::Mutex::new(session))
+ .lock_owned()
+ .await;
+ let _ = self.close(session).await; // Ignore error.
+
+ return Err(err.into());
+ }
+ };
+ let session = sessions
+ .add(session, now)
+ .expect("there should be space for the new session");
+
+ if let Some(removed_session) = maybe_removed_session {
+ // A stale session was removed. Gracefully close the removed session.
+ drop(sessions); // Unlock.
+
+ let _ = self.close(removed_session).await; // Ignore error.
+ }
+
+ Ok(session)
+ }
+
+ async fn secure_call_raw(
+ &self,
+ request: types::Request,
+ session: &mut OwnedMutexGuard<MultiplexedSession<signature::PublicKey>>,
+ ) -> Result<(u64, types::Response), RpcClientError> {
+ let method = request.method.clone();
+ let msg = types::Message::Request(request);
+ let session_id = *session.get_session_id();
+
+ // Session Transport: prepare the request message.
+ let mut buffer = vec![];
+ session
+ .write_message(msg, &mut buffer)
+ .map_err(|_| RpcClientError::Transport)?;
+ let node = session.get_remote_node()?;
+
+ let request_id = self.next_request_id();
+ let result = async {
+ // Transport: send the request and receive a response.
+ let rsp = self
+ .transport
+ .write_noise_session(request_id, session_id, buffer, method, vec![node])
+ .await
+ .map_err(|_| RpcClientError::Transport)?;
+
+ // Session Transport: process the response.
+ session.process_data(&rsp.data, vec![]).await
+ }
+ .await;
+
+ // Submit negative peer feedback for the last transport
+ // and the received response immediately.
+ if result.is_err() {
+ let _ = self
+ .transport
+ .submit_peer_feedback(request_id, types::PeerFeedback::Failure)
+ .await; // Ignore error.
+ }
+
+ // Forward error after peer feedback is sent.
+ let maybe_msg = result?;
+
+ // Unwrap response.
+ let msg = maybe_msg.expect("message must be decoded if there is no error");
+ let rsp = match msg {
+ types::Message::Response(rsp) => rsp,
+ msg => return Err(RpcClientError::ExpectedResponseMessage(msg)),
+ };
+
+ Ok((request_id, rsp))
+ }
+
+ async fn insecure_call_raw(
+ &self,
+ request: types::Request,
+ nodes: Vec<signature::PublicKey>,
+ ) -> Result<(u64, types::Response), RpcClientError> {
+ // Transport: send the request.
+ let request_id = self.next_request_id();
+ let result = self
+ .transport
+ .write_insecure_query(request_id, cbor::to_vec(request), nodes)
+ .await
+ .map_err(|_| RpcClientError::Transport);
+
+ // Submit negative peer feedback for the last transport immediately.
+ if result.is_err() {
+ let _ = self
+ .transport
+ .submit_peer_feedback(request_id, types::PeerFeedback::Failure)
+ .await; // Ignore error.
+ }
+
+ // Forward error after peer feedback is sent.
+ let rsp = result?;
+
+ // Unwrap response.
+ let rsp = cbor::from_slice(&rsp.data).map_err(RpcClientError::DecodeError)?;
+
+ Ok((request_id, rsp))
+ }
+
+ /// Close the session.
+ async fn close(
+ &self,
+ mut session: OwnedMutexGuard<MultiplexedSession<signature::PublicKey>>,
+ ) -> Result<(), RpcClientError> {
+ if !session.is_connected() && !session.is_unauthenticated() {
+ return Ok(());
+ }
+
+ let session_id = *session.get_session_id();
+ let node = session.get_remote_node()?;
+
+ // Session Transport: prepare close request.
+ let mut buffer = vec![];
+ session
+ .write_message(types::Message::Close, &mut buffer)
+ .map_err(|_| RpcClientError::Transport)?;
+
+ // Transport: send close request.
+ let request_id = self.next_request_id();
+ let rsp = self
+ .transport
+ .write_noise_session(request_id, session_id, buffer, String::new(), vec![node])
+ .await
+ .map_err(|_| RpcClientError::Transport)?;
+
+ // Skipping peer feedback, as the request was sent only to inform
+ // the other side of a graceful session close.
+
+ // Session Transport: process the response.
+ let msg = session
+ .process_data(&rsp.data, vec![])
+ .await?
+ .expect("message must be decoded if there is no error");
+
+ // Close the session.
+ session.close();
+
+ match msg {
+ types::Message::Close => Ok(()),
+ msg => Err(RpcClientError::ExpectedCloseMessage(msg)),
+ }
+ }
+
+ /// Close all sessions.
+ async fn close_all(&self, sessions: Vec<SharedSession<signature::PublicKey>>) {
+ let futures = FuturesUnordered::new();
+ for session in sessions {
+ let future = async {
+ let locked_session = session.lock_owned().await;
+ let _ = self.close(locked_session).await; // Ignore errors.
+ };
+ futures.push(future);
+ }
+ futures.collect::<()>().await;
+ }
+
+ /// Return the ID of the next transport request.
+ fn next_request_id(&self) -> u64 {
+ let next_request_id = self.next_request_id.fetch_add(1, Ordering::SeqCst); // Wraps if overflows.
+ ((self.client_id as u64) << 32) + (next_request_id as u64)
+ }
+
+ /// Generate a random client ID.
+ fn random_client_id() -> u32 {
+ #[cfg(test)]
+ return 0;
+
+ #[cfg(not(test))]
+ OsRng.next_u32()
+ }
+}
+
+impl Drop for RpcClient {
+ fn drop(&mut self) {
+ // Close all sessions after the client is dropped.
+ block_on(async {
+ let sessions = {
+ let mut sessions = self.sessions.lock().await;
+ sessions.drain()
+ };
+ self.close_all(sessions).await;
+ });
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use std::sync::{
+ atomic::{AtomicBool, Ordering},
+ Arc, Mutex,
+ };
+
+ use anyhow::anyhow;
+ use async_trait::async_trait;
+
+ use crate::{
+ common::crypto::signature,
+ enclave_rpc::{demux::Demux, session, transport::EnclaveResponse, types},
+ };
+
+ use super::{super::transport::Transport, RpcClient};
+
+ #[derive(Clone)]
+ struct MockTransport {
+ demux: Arc<Demux>,
+ next_error: Arc<AtomicBool>,
+ peer_feedback_history: Arc<Mutex<Vec<(u64, types::PeerFeedback)>>>,
+ }
+
+ impl MockTransport {
+ fn new() -> Self {
+ Self {
+ demux: Arc::new(Demux::new(session::Builder::default(), 4, 4, 60)),
+ next_error: Arc::new(AtomicBool::new(false)),
+ peer_feedback_history: Arc::new(Mutex::new(Vec::new())),
+ }
+ }
+
+ fn reset(&self) {
+ self.demux.reset();
+ }
+
+ fn induce_transport_error(&self) {
+ self.next_error.store(true, Ordering::SeqCst);
+ }
+
+ fn take_peer_feedback_history(&self) -> Vec<(u64, types::PeerFeedback)> {
+ let mut pfh = self.peer_feedback_history.lock().unwrap();
+ pfh.drain(..).collect()
+ }
+ }
+
+ #[async_trait]
+ impl Transport for MockTransport {
+ async fn write_message_impl(
+ &self,
+ _request_id: u64,
+ request: Vec<u8>,
+ kind: types::Kind,
+ _nodes: Vec<signature::PublicKey>,
+ ) -> Result<EnclaveResponse, anyhow::Error> {
+ // Induce error when configured to do so.
+ if self
+ .next_error
+ .compare_exchange(true, false, Ordering::SeqCst, Ordering::SeqCst)
+ .is_ok()
+ {
+ return Err(anyhow!("transport error"));
+ }
+
+ match kind {
+ types::Kind::NoiseSession => {
+ // Deliver directly to the multiplexer.
+ let mut buffer = Vec::new();
+ let (mut session, message) = self
+ .demux
+ .process_frame(vec![], request, &mut buffer)
+ .await?;
+
+ match message {
+ Some(message) => {
+ let mut buffer = Vec::new();
+
+ // Message, process and write reply.
+ match message {
+ types::Message::Request(rq) => {
+ // Just echo back what was given.
+ let response = types::Message::Response(types::Response {
+ body: types::Body::Success(rq.args),
+ });
+
+ session.write_message(response, &mut buffer)?;
+ }
+ types::Message::Close => {
+ self.demux.close(session, &mut buffer)?;
+ }
+ _ => panic!("unhandled message type"),
+ };
+
+ let rsp = EnclaveResponse {
+ data: buffer,
+ node: Default::default(),
+ };
+ Ok(rsp)
+ }
+ None => {
+ // Handshake.
+ let rsp = EnclaveResponse {
+ data: buffer,
+ node: Default::default(),
+ };
+ Ok(rsp)
+ }
+ }
+ }
+ types::Kind::InsecureQuery => {
+ // Just echo back what was given.
+ let rq: types::Request = cbor::from_slice(&request).unwrap();
+ let body = types::Body::Success(rq.args);
+ let response = types::Response { body };
+ let rsp = EnclaveResponse {
+ data: cbor::to_vec(response),
+ node: Default::default(),
+ };
+ return Ok(rsp);
+ }
+ types::Kind::LocalQuery => {
+ panic!("unhandled RPC kind")
+ }
+ }
+ }
+
+ async fn submit_peer_feedback(
+ &self,
+ request_id: u64,
+ peer_feedback: types::PeerFeedback,
+ ) -> Result<(), anyhow::Error> {
+ self.peer_feedback_history
+ .lock()
+ .unwrap()
+ .push((request_id, peer_feedback));
+
+ Ok(())
+ }
+ }
+
+ #[test]
+ fn test_rpc_client() {
+ let rt = tokio::runtime::Runtime::new().unwrap();
+ let _guard = rt.enter(); // Ensure Tokio runtime is available.
+ let transport = MockTransport::new();
+ let builder = session::Builder::default();
+ let client = RpcClient::new(Box::new(transport.clone()), builder, 8, 2, 60);
+
+ // Basic secure call.
+ let result: u64 = rt
+ .block_on(async {
+ client
+ .secure_call("test", 42, vec![])
+ .await
+ .into_result_with_feedback()
+ .await
+ })
+ .unwrap();
+ assert_eq!(result, 42, "secure call should work");
+ assert_eq!(
+ transport.take_peer_feedback_history(),
+ vec![
+ (1, types::PeerFeedback::Success), // Handshake.
+ (2, types::PeerFeedback::Success), // Handshake.
+ (3, types::PeerFeedback::Success), // Handled call.
+ ]
+ );
+
+ // Reset all sessions on the server and make sure that we can still get a response.
+ transport.reset();
+
+ let result: u64 = rt
+ .block_on(async {
+ client
+ .secure_call("test", 43, vec![])
+ .await
+ .into_result_with_feedback()
+ .await
+ })
+ .unwrap();
+ assert_eq!(result, 43, "secure call should work");
+ assert_eq!(
+ transport.take_peer_feedback_history(),
+ vec![
+ (4, types::PeerFeedback::Failure), // Failed call due to session reset.
+ (5, types::PeerFeedback::Success), // New handshake.
+ (6, types::PeerFeedback::Success), // New handshake.
+ (7, types::PeerFeedback::Success), // Handled call.
+ ]
+ );
+
+ // Induce a single transport error without resetting the server sessions and make sure we
+ // can still get a response.
+ transport.induce_transport_error();
+
+ let result: u64 = rt
+ .block_on(async {
+ client
+ .secure_call("test", 44, vec![])
+ .await
+ .into_result_with_feedback()
+ .await
+ })
+ .unwrap();
+ assert_eq!(result, 44, "secure call should work");
+ assert_eq!(
+ transport.take_peer_feedback_history(),
+ vec![
+ (8, types::PeerFeedback::Failure), // Handshake failed due to induced error.
+ // (9, types::PeerFeedback::Failure), // Session close failed due to decrypt error (handshake not completed). [skipped]
+ (9, types::PeerFeedback::Success), // New handshake.
+ (10, types::PeerFeedback::Success), // New handshake.
+ (11, types::PeerFeedback::Success), // Handled call.
+ ]
+ );
+
+ // Basic insecure call.
+ let result: u64 = rt
+ .block_on(async {
+ client
+ .insecure_call("test", 45, vec![])
+ .await
+ .into_result_with_feedback()
+ .await
+ })
+ .unwrap();
+ assert_eq!(result, 45, "insecure call should work");
+ assert_eq!(
+ transport.take_peer_feedback_history(),
+ vec![
+ (12, types::PeerFeedback::Success), // Handled call.
+ ]
+ );
+
+ // Induce a single transport error and make sure we can still get a response.
+ transport.induce_transport_error();
+
+ let result: u64 = rt
+ .block_on(async {
+ client
+ .insecure_call("test", 46, vec![])
+ .await
+ .into_result_with_feedback()
+ .await
+ })
+ .unwrap();
+ assert_eq!(result, 46, "insecure call should work");
+ assert_eq!(
+ transport.take_peer_feedback_history(),
+ vec![
+ (13, types::PeerFeedback::Failure), // Failed call due to induced error.
+ (14, types::PeerFeedback::Success), // Handled call.
+ ]
+ );
+ }
+}
+//! RPC call context.
+use std::sync::Arc;
+
+use super::session::SessionInfo;
+
+/// RPC call context.
+pub struct Context {
+ /// Information about the session the RPC call was delivered over.
+ pub session_info: Option<Arc<SessionInfo>>,
+}
+
+impl Context {
+ /// Construct new transaction context.
+ pub fn new(session_info: Option<Arc<SessionInfo>>) -> Self {
+ Self { session_info }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +
//! Session demultiplexer.
+use std::{io::Write, sync::Mutex};
+
+use thiserror::Error;
+use tokio::sync::OwnedMutexGuard;
+
+use super::{
+ session::Builder,
+ sessions::{self, MultiplexedSession, Sessions},
+ types::{Frame, Message, SessionID},
+};
+use crate::common::time::insecure_posix_time;
+
+/// Demultiplexer error.
+#[derive(Error, Debug)]
+pub enum Error {
+ #[error("malformed payload: {0}")]
+ MalformedPayload(#[from] cbor::DecodeError),
+ #[error("malformed request method")]
+ MalformedRequestMethod,
+ #[error("sessions error: {0}")]
+ SessionsError(#[from] sessions::Error),
+ #[error("{0}")]
+ Other(#[from] anyhow::Error),
+}
+
+impl Error {
+ fn code(&self) -> u32 {
+ match self {
+ Error::MalformedPayload(_) => 1,
+ Error::MalformedRequestMethod => 2,
+ Error::SessionsError(_) => 3,
+ Error::Other(_) => 4,
+ }
+ }
+}
+
+impl From<Error> for crate::types::Error {
+ fn from(e: Error) -> Self {
+ Self {
+ module: "demux".to_string(),
+ code: e.code(),
+ message: e.to_string(),
+ }
+ }
+}
+
+/// Session demultiplexer.
+pub struct Demux {
+ sessions: Mutex<Sessions<Vec<u8>>>,
+}
+
+impl Demux {
+ /// Create new session demultiplexer.
+ pub fn new(
+ builder: Builder,
+ max_sessions: usize,
+ max_sessions_per_peer: usize,
+ stale_session_timeout: i64,
+ ) -> Self {
+ Self {
+ sessions: Mutex::new(Sessions::new(
+ builder,
+ max_sessions,
+ max_sessions_per_peer,
+ stale_session_timeout,
+ )),
+ }
+ }
+
+ /// Set the session builder to use.
+ pub fn set_session_builder(&self, builder: Builder) {
+ let mut sessions = self.sessions.lock().unwrap();
+ sessions.set_builder(builder);
+ }
+
+ async fn get_or_create_session(
+ &self,
+ peer_id: Vec<u8>,
+ session_id: SessionID,
+ ) -> Result<OwnedMutexGuard<MultiplexedSession<Vec<u8>>>, Error> {
+ let session = {
+ let mut sessions = self.sessions.lock().unwrap();
+ match sessions.get(&peer_id, &session_id) {
+ Some(session) => session,
+ None => {
+ let now = insecure_posix_time();
+ let _ = sessions.remove_for(&peer_id, now)?;
+ let session = sessions.create_responder(peer_id, session_id);
+ sessions
+ .add(session, now)
+ .expect("there should be space for the new session")
+ }
+ }
+ };
+
+ Ok(session.lock_owned().await)
+ }
+
+ /// Process a frame, returning the locked session guard and decoded message.
+ ///
+ /// Any data that needs to be transmitted back to the peer is written to the passed writer.
+ pub async fn process_frame<W: Write>(
+ &self,
+ peer_id: Vec<u8>,
+ data: Vec<u8>,
+ writer: W,
+ ) -> Result<
+ (
+ OwnedMutexGuard<MultiplexedSession<Vec<u8>>>,
+ Option<Message>,
+ ),
+ Error,
+ > {
+ // Decode frame.
+ let frame: Frame = cbor::from_slice(&data)?;
+ // Get the existing session or create a new one.
+ let mut session = self.get_or_create_session(peer_id, frame.session).await?;
+ // Process session data.
+ match session.process_data(&frame.payload, writer).await {
+ Ok(msg) => {
+ if let Some(Message::Request(ref req)) = msg {
+ // Make sure that the untrusted_plaintext matches the request's method.
+ if frame.untrusted_plaintext != req.method {
+ return Err(Error::MalformedRequestMethod);
+ }
+ }
+
+ Ok((session, msg))
+ }
+ Err(err) => {
+ // In case the session was closed, remove the session.
+ if session.is_closed() {
+ let mut sessions = self.sessions.lock().unwrap();
+ sessions.remove(&session);
+ }
+ Err(Error::Other(err))
+ }
+ }
+ }
+
+ /// Closes the given session.
+ ///
+ /// Any data that needs to be transmitted back to the peer is written to the passed writer.
+ pub fn close<W: Write>(
+ &self,
+ mut session: OwnedMutexGuard<MultiplexedSession<Vec<u8>>>,
+ writer: W,
+ ) -> Result<(), Error> {
+ let mut sessions = self.sessions.lock().unwrap();
+ sessions.remove(&session);
+
+ session.write_message(Message::Close, writer)?;
+ Ok(())
+ }
+
+ /// Resets all open sessions.
+ pub fn reset(&self) {
+ let mut sessions = self.sessions.lock().unwrap();
+ let _ = sessions.drain();
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +
//! RPC dispatcher.
+use std::collections::HashMap;
+
+use anyhow::{bail, Result};
+use thiserror::Error;
+
+use crate::{common::sgx::QuotePolicy, consensus::state::keymanager::Status as KeyManagerStatus};
+
+use super::{
+ context::Context,
+ types::{Body, Kind, Request, Response},
+};
+
+/// Dispatch error.
+#[derive(Error, Debug)]
+enum DispatchError {
+ #[error("method not found: {method:?}")]
+ MethodNotFound { method: String },
+ #[error("invalid RPC kind: {method:?} ({kind:?})")]
+ InvalidRpcKind { method: String, kind: Kind },
+}
+
+/// RPC handler.
+pub trait Handler {
+ /// Returns the list of RPC methods supported by this handler.
+ fn methods(&'static self) -> Vec<Method>;
+}
+
+/// Descriptor of a RPC API method.
+#[derive(Clone, Debug)]
+pub struct MethodDescriptor {
+ /// Method name.
+ pub name: String,
+ /// Specifies which kind of RPC is allowed to call the method.
+ pub kind: Kind,
+}
+
+/// Handler for a RPC method.
+pub trait MethodHandler<Rq, Rsp> {
+ /// Invoke the method implementation and return a response.
+ fn handle(&self, ctx: &Context, request: &Rq) -> Result<Rsp>;
+}
+
+impl<Rq, Rsp, F> MethodHandler<Rq, Rsp> for F
+where
+ Rq: 'static,
+ Rsp: 'static,
+ F: Fn(&Context, &Rq) -> Result<Rsp> + 'static,
+{
+ fn handle(&self, ctx: &Context, request: &Rq) -> Result<Rsp> {
+ (*self)(ctx, request)
+ }
+}
+
+/// Dispatcher for a RPC method.
+pub trait MethodHandlerDispatch {
+ /// Get method descriptor.
+ fn get_descriptor(&self) -> &MethodDescriptor;
+
+ /// Dispatch request.
+ fn dispatch(&self, ctx: &Context, request: Request) -> Result<Response>;
+}
+
+struct MethodHandlerDispatchImpl<Rq, Rsp> {
+ /// Method descriptor.
+ descriptor: MethodDescriptor,
+ /// Method handler.
+ handler: Box<dyn MethodHandler<Rq, Rsp> + Send + Sync>,
+}
+
+impl<Rq, Rsp> MethodHandlerDispatch for MethodHandlerDispatchImpl<Rq, Rsp>
+where
+ Rq: cbor::Decode + 'static,
+ Rsp: cbor::Encode + 'static,
+{
+ fn get_descriptor(&self) -> &MethodDescriptor {
+ &self.descriptor
+ }
+
+ fn dispatch(&self, ctx: &Context, request: Request) -> Result<Response> {
+ let request = cbor::from_value(request.args)?;
+ let response = self.handler.handle(ctx, &request)?;
+
+ Ok(Response {
+ body: Body::Success(cbor::to_value(response)),
+ })
+ }
+}
+
+/// RPC method dispatcher implementation.
+pub struct Method {
+ /// Method dispatcher.
+ dispatcher: Box<dyn MethodHandlerDispatch + Send + Sync>,
+}
+
+impl Method {
+ /// Create a new enclave method descriptor.
+ pub fn new<Rq, Rsp, Handler>(method: MethodDescriptor, handler: Handler) -> Self
+ where
+ Rq: cbor::Decode + 'static,
+ Rsp: cbor::Encode + 'static,
+ Handler: MethodHandler<Rq, Rsp> + Send + Sync + 'static,
+ {
+ Method {
+ dispatcher: Box::new(MethodHandlerDispatchImpl {
+ descriptor: method,
+ handler: Box::new(handler),
+ }),
+ }
+ }
+
+ /// Return method name.
+ fn get_name(&self) -> &String {
+ &self.dispatcher.get_descriptor().name
+ }
+
+ /// Return RPC call kind.
+ fn get_kind(&self) -> Kind {
+ self.dispatcher.get_descriptor().kind
+ }
+
+ /// Dispatch a request.
+ fn dispatch(&self, ctx: &mut Context, request: Request) -> Result<Response> {
+ self.dispatcher.dispatch(ctx, request)
+ }
+}
+
+/// Key manager status update handler callback.
+pub type KeyManagerStatusHandler = dyn Fn(KeyManagerStatus) + Send + Sync;
+/// Key manager quote policy update handler callback.
+pub type KeyManagerQuotePolicyHandler = dyn Fn(QuotePolicy) + Send + Sync;
+
+/// RPC call dispatcher.
+#[derive(Default)]
+pub struct Dispatcher {
+ /// Registered RPC methods.
+ methods: HashMap<String, Method>,
+ /// Registered key manager status handler.
+ km_status_handler: Option<Box<KeyManagerStatusHandler>>,
+ /// Registered key manager quote policy handler.
+ km_quote_policy_handler: Option<Box<KeyManagerQuotePolicyHandler>>,
+}
+
+impl Dispatcher {
+ /// Register a new method in the dispatcher.
+ pub fn add_method(&mut self, method: Method) {
+ self.methods.insert(method.get_name().clone(), method);
+ }
+
+ /// Register new methods in the dispatcher.
+ pub fn add_methods(&mut self, methods: Vec<Method>) {
+ for method in methods {
+ self.add_method(method);
+ }
+ }
+
+ /// Dispatch request.
+ pub fn dispatch(&self, mut ctx: Context, request: Request, kind: Kind) -> Response {
+ match self.dispatch_fallible(&mut ctx, request, kind) {
+ Ok(response) => response,
+ Err(error) => Response {
+ body: Body::Error(format!("{error}")),
+ },
+ }
+ }
+
+ fn dispatch_fallible(
+ &self,
+ ctx: &mut Context,
+ request: Request,
+ kind: Kind,
+ ) -> Result<Response> {
+ let method = match self.methods.get(&request.method) {
+ Some(method) => method,
+ None => bail!(DispatchError::MethodNotFound {
+ method: request.method,
+ }),
+ };
+
+ if method.get_kind() != kind {
+ bail!(DispatchError::InvalidRpcKind {
+ method: request.method,
+ kind,
+ });
+ };
+
+ method.dispatch(ctx, request)
+ }
+
+ /// Handle key manager status update.
+ pub fn handle_km_status_update(&self, status: KeyManagerStatus) {
+ if let Some(handler) = self.km_status_handler.as_ref() {
+ handler(status)
+ }
+ }
+
+ /// Handle key manager quote policy update.
+ pub fn handle_km_quote_policy_update(&self, policy: QuotePolicy) {
+ if let Some(handler) = self.km_quote_policy_handler.as_ref() {
+ handler(policy)
+ }
+ }
+
+ /// Update key manager status update handler.
+ pub fn set_keymanager_status_update_handler(
+ &mut self,
+ f: Option<Box<KeyManagerStatusHandler>>,
+ ) {
+ self.km_status_handler = f;
+ }
+
+ /// Update key manager quote policy update handler.
+ pub fn set_keymanager_quote_policy_update_handler(
+ &mut self,
+ f: Option<Box<KeyManagerQuotePolicyHandler>>,
+ ) {
+ self.km_quote_policy_handler = f;
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +
//! Secure channel session.
+use std::{collections::HashSet, io::Write, mem, sync::Arc};
+
+use anyhow::Result;
+use thiserror::Error;
+
+use super::types::Message;
+use crate::{
+ common::{
+ crypto::signature::{self, PublicKey, Signature, Signer},
+ namespace::Namespace,
+ sgx::{ias, EnclaveIdentity, Quote, QuotePolicy},
+ },
+ consensus::{
+ registry::{EndorsedCapabilityTEE, VerifiedAttestation, VerifiedEndorsedCapabilityTEE},
+ state::registry::ImmutableState as RegistryState,
+ verifier::Verifier,
+ },
+ identity::Identity,
+};
+
+/// Noise protocol pattern.
+const NOISE_PATTERN: &str = "Noise_XX_25519_ChaChaPoly_SHA256";
+/// RAK signature session binding context.
+const RAK_SESSION_BINDING_CONTEXT: [u8; 8] = *b"EkRakRpc";
+
+/// Session-related error.
+#[derive(Error, Debug)]
+enum SessionError {
+ #[error("invalid input")]
+ InvalidInput,
+ #[error("invalid state")]
+ InvalidState,
+ #[error("session closed")]
+ Closed,
+ #[error("mismatched enclave identity")]
+ MismatchedEnclaveIdentity,
+ #[error("missing quote policy")]
+ MissingQuotePolicy,
+ #[error("remote node not set")]
+ NodeNotSet,
+ #[error("remote node already set")]
+ NodeAlreadySet,
+ #[error("remote node not registered")]
+ NodeNotRegistered,
+ #[error("RAK not published in the consensus layer")]
+ RAKNotFound,
+ #[error("runtime id not set")]
+ RuntimeNotSet,
+}
+
+/// Information about a session.
+pub struct SessionInfo {
+ /// RAK binding.
+ pub rak_binding: RAKBinding,
+ /// Verified TEE remote attestation.
+ pub verified_attestation: VerifiedAttestation,
+ /// Identifier of the node that endorsed the TEE.
+ pub endorsed_by: Option<PublicKey>,
+}
+
+enum State {
+ Handshake1(snow::HandshakeState),
+ Handshake2(snow::HandshakeState),
+ Transport(snow::TransportState),
+ UnauthenticatedTransport(snow::TransportState),
+ Closed,
+}
+
+/// An encrypted and authenticated RPC session.
+pub struct Session {
+ cfg: Config,
+ local_static_pub: Vec<u8>,
+ remote_node: Option<signature::PublicKey>,
+ info: Option<Arc<SessionInfo>>,
+ state: State,
+ buf: Vec<u8>,
+}
+
+impl Session {
+ fn new(handshake_state: snow::HandshakeState, local_static_pub: Vec<u8>, cfg: Config) -> Self {
+ Self {
+ cfg,
+ local_static_pub,
+ remote_node: None,
+ info: None,
+ state: State::Handshake1(handshake_state),
+ buf: vec![0u8; 65535],
+ }
+ }
+
+ /// Process incoming data.
+ ///
+ /// In case the session is in transport mode the returned result will
+ /// contained a parsed message. The `writer` will be used in case any
+ /// protocol replies need to be generated.
+ pub async fn process_data<W: Write>(
+ &mut self,
+ data: &[u8],
+ mut writer: W,
+ ) -> Result<Option<Message>> {
+ // Replace the state with a closed state. In case processing fails for whatever
+ // reason, this will cause the session to be torn down.
+ match mem::replace(&mut self.state, State::Closed) {
+ State::Handshake1(mut state) => {
+ if state.is_initiator() {
+ // Initiator only sends in this state.
+ if !data.is_empty() {
+ return Err(SessionError::InvalidInput.into());
+ }
+
+ // -> e
+ let len = state.write_message(&[], &mut self.buf)?;
+ writer.write_all(&self.buf[..len])?;
+ } else {
+ // <- e
+ state.read_message(data, &mut self.buf)?;
+
+ // -> e, ee, s, es
+ let len = state.write_message(&self.get_rak_binding(), &mut self.buf)?;
+ writer.write_all(&self.buf[..len])?;
+ }
+
+ self.state = State::Handshake2(state);
+ }
+ State::Handshake2(mut state) => {
+ // Process data sent during Handshake1 phase.
+ let len = state.read_message(data, &mut self.buf)?;
+ let remote_static = state
+ .get_remote_static()
+ .expect("dh exchange just happened");
+ let auth_info = self
+ .verify_rak_binding(&self.buf[..len], remote_static)
+ .await;
+
+ if state.is_initiator() {
+ // -> s, se
+ let len = state.write_message(&self.get_rak_binding(), &mut self.buf)?;
+ writer.write_all(&self.buf[..len])?;
+ }
+
+ match auth_info {
+ Ok(auth_info) => {
+ self.info = auth_info;
+ self.state = State::Transport(state.into_transport_mode()?);
+ }
+ Err(_) if state.is_initiator() => {
+ // There was an error authenticating the session and we are the initiator.
+ // Transition into unauthenticated transport state so we can notify the
+ // other side of the close.
+ self.state = State::UnauthenticatedTransport(state.into_transport_mode()?);
+ }
+ Err(err) => {
+ // There was an authentication error and we are not the initiator, abort.
+ return Err(err);
+ }
+ }
+ }
+ State::Transport(mut state) => {
+ // TODO: Restore session in case of errors.
+ let len = state.read_message(data, &mut self.buf)?;
+ let msg = cbor::from_slice(&self.buf[..len])?;
+
+ self.state = State::Transport(state);
+ return Ok(Some(msg));
+ }
+ State::Closed | State::UnauthenticatedTransport(_) => {
+ return Err(SessionError::Closed.into());
+ }
+ }
+
+ Ok(None)
+ }
+
+ /// Write message to session.
+ ///
+ /// The `writer` will be used for protocol message output which should
+ /// be transmitted to the remote session counterpart.
+ pub fn write_message<W: Write>(&mut self, msg: Message, mut writer: W) -> Result<()> {
+ let state = match self.state {
+ State::Transport(ref mut state) => state,
+ State::UnauthenticatedTransport(ref mut state) if matches!(msg, Message::Close) => {
+ state
+ }
+ _ => return Err(SessionError::InvalidState.into()),
+ };
+
+ let len = state.write_message(&cbor::to_vec(msg), &mut self.buf)?;
+ writer.write_all(&self.buf[..len])?;
+
+ Ok(())
+ }
+
+ /// Mark the session as closed.
+ ///
+ /// After the session is closed it can no longer be used to transmit
+ /// or receive messages and any such use will result in an error.
+ pub fn close(&mut self) {
+ self.state = State::Closed;
+ }
+
+ fn get_rak_binding(&self) -> Vec<u8> {
+ match self.cfg.identity {
+ Some(ref identity) => {
+ if identity.quote().is_none() {
+ return vec![];
+ }
+
+ let binding = identity
+ .sign(&RAK_SESSION_BINDING_CONTEXT, &self.local_static_pub)
+ .unwrap();
+
+ if self.cfg.use_endorsement {
+ // Use endorsed TEE capability when available.
+ if let Some(ect) = identity.endorsed_capability_tee() {
+ return cbor::to_vec(RAKBinding::V2 { ect, binding });
+ }
+ }
+
+ // Use the local RAK and quote.
+ let rak_pub = identity.public_rak();
+ let quote = identity.quote().expect("quote is configured");
+
+ cbor::to_vec(RAKBinding::V1 {
+ rak_pub,
+ binding,
+ quote: (*quote).clone(),
+ })
+ }
+ None => vec![],
+ }
+ }
+
+ async fn verify_rak_binding(
+ &self,
+ rak_binding: &[u8],
+ remote_static: &[u8],
+ ) -> Result<Option<Arc<SessionInfo>>> {
+ if rak_binding.is_empty() {
+ // If enclave identity verification is required and no RAK binding
+ // has been provided, we must abort the session.
+ if self.cfg.remote_enclaves.is_some() {
+ return Err(SessionError::MismatchedEnclaveIdentity.into());
+ }
+ return Ok(None);
+ }
+
+ let policy = self
+ .cfg
+ .policy
+ .as_ref()
+ .ok_or(SessionError::MissingQuotePolicy)?;
+
+ let rak_binding: RAKBinding = cbor::from_slice(rak_binding)?;
+ let vect = rak_binding.verify(remote_static, &self.cfg.remote_enclaves, policy)?;
+
+ // Verify node identity if verification is enabled.
+ if self.cfg.consensus_verifier.is_some() {
+ let rak = rak_binding.rak_pub();
+ self.verify_node_identity(rak).await?;
+ }
+
+ Ok(Some(Arc::new(SessionInfo {
+ rak_binding,
+ verified_attestation: vect.verified_attestation,
+ endorsed_by: vect.node_id,
+ })))
+ }
+
+ /// Session information.
+ pub fn session_info(&self) -> Option<Arc<SessionInfo>> {
+ self.info.clone()
+ }
+
+ /// Whether the session handshake has completed and the session
+ /// is in transport mode.
+ pub fn is_connected(&self) -> bool {
+ matches!(self.state, State::Transport(_))
+ }
+
+ /// Whether the session is connected to one of the given nodes.
+ pub fn is_connected_to(&self, nodes: &Vec<signature::PublicKey>) -> bool {
+ nodes.iter().any(|&node| Some(node) == self.remote_node)
+ }
+
+ /// Whether the session is in closed state.
+ pub fn is_closed(&self) -> bool {
+ matches!(self.state, State::Closed)
+ }
+
+ /// Whether the session is in unauthenticated transport state. In this state the session can
+ /// only be used to transmit a close notification.
+ pub fn is_unauthenticated(&self) -> bool {
+ matches!(self.state, State::UnauthenticatedTransport(_))
+ }
+
+ /// Return remote node identifier.
+ pub fn get_remote_node(&self) -> Result<signature::PublicKey> {
+ self.remote_node.ok_or(SessionError::NodeNotSet.into())
+ }
+
+ /// Set the remote node identifier.
+ pub fn set_remote_node(&mut self, node: signature::PublicKey) -> Result<()> {
+ if self.remote_node.is_some() {
+ return Err(SessionError::NodeAlreadySet.into());
+ }
+ self.remote_node = Some(node);
+ Ok(())
+ }
+
+ /// Verify the identity of the remote node by comparing the given RAK with the trusted RAK
+ /// obtained from the consensus layer registry service.
+ async fn verify_node_identity(&self, rak: signature::PublicKey) -> Result<()> {
+ let consensus_verifier = self
+ .cfg
+ .consensus_verifier
+ .as_ref()
+ .expect("consensus verifier should be set");
+ let runtime_id = self
+ .cfg
+ .remote_runtime_id
+ .ok_or(SessionError::RuntimeNotSet)?;
+ let node = self.remote_node.ok_or(SessionError::NodeNotSet)?;
+
+ let consensus_state = consensus_verifier.latest_state().await?;
+ // TODO: Make this access async.
+ let node = tokio::task::block_in_place(move || -> Result<_> {
+ let registry_state = RegistryState::new(&consensus_state);
+ Ok(registry_state
+ .node(&node)?
+ .ok_or(SessionError::NodeNotRegistered)?)
+ })?;
+
+ let verified = node
+ .runtimes
+ .unwrap_or_default()
+ .iter()
+ .filter(|rt| rt.id == runtime_id)
+ .flat_map(|rt| &rt.capabilities.tee)
+ .any(|tee| tee.rak == rak);
+
+ if !verified {
+ return Err(SessionError::RAKNotFound.into());
+ }
+ Ok(())
+ }
+}
+
+/// Binding of the session's static public key to a remote attestation
+/// verification report through the use of the remote attestation key.
+///
+/// The signature chain is as follows:
+///
+/// * `avr` contains the remote attestation verification report which
+/// binds RAK to the remote attestation.
+/// * `rak_pub` contains the public part of RAK.
+/// * `binding` is signed by `rak_pub` and binds the session's static
+/// public key to RAK.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(tag = "v")]
+pub enum RAKBinding {
+ /// Old V0 format that only supported IAS quotes.
+ #[cbor(rename = 0, missing)]
+ V0 {
+ rak_pub: PublicKey,
+ binding: Signature,
+ avr: ias::AVR,
+ },
+
+ /// New V1 format that supports both IAS and PCS quotes.
+ #[cbor(rename = 1)]
+ V1 {
+ rak_pub: PublicKey,
+ binding: Signature,
+ quote: Quote,
+ },
+
+ /// V2 format which supports endorsed CapabilityTEE structures.
+ #[cbor(rename = 2)]
+ V2 {
+ ect: EndorsedCapabilityTEE,
+ binding: Signature,
+ },
+}
+
+impl RAKBinding {
+ /// Public part of the RAK.
+ pub fn rak_pub(&self) -> PublicKey {
+ match self {
+ Self::V0 { rak_pub, .. } => *rak_pub,
+ Self::V1 { rak_pub, .. } => *rak_pub,
+ Self::V2 { ect, .. } => ect.capability_tee.rak,
+ }
+ }
+
+ /// Signature from RAK, binding the session's static public key to RAK.
+ fn binding(&self) -> Signature {
+ match self {
+ Self::V0 { binding, .. } => *binding,
+ Self::V1 { binding, .. } => *binding,
+ Self::V2 { binding, .. } => *binding,
+ }
+ }
+
+ /// Verify the RAK binding.
+ pub fn verify(
+ &self,
+ remote_static: &[u8],
+ remote_enclaves: &Option<HashSet<EnclaveIdentity>>,
+ policy: &QuotePolicy,
+ ) -> Result<VerifiedEndorsedCapabilityTEE> {
+ let vect = self.verify_inner(policy)?;
+
+ // Ensure that the report data includes the hash of the node's RAK.
+ // NOTE: For V2 this check is part of verify_inner so it is not really needed.
+ Identity::verify_binding(&vect.verified_attestation.quote, &self.rak_pub())?;
+
+ // Verify MRENCLAVE/MRSIGNER.
+ if let Some(ref remote_enclaves) = remote_enclaves {
+ if !remote_enclaves.contains(&vect.verified_attestation.quote.identity) {
+ return Err(SessionError::MismatchedEnclaveIdentity.into());
+ }
+ }
+
+ // Verify remote static key binding.
+ self.binding()
+ .verify(&self.rak_pub(), &RAK_SESSION_BINDING_CONTEXT, remote_static)?;
+
+ Ok(vect)
+ }
+
+ fn verify_inner(&self, policy: &QuotePolicy) -> Result<VerifiedEndorsedCapabilityTEE> {
+ match self {
+ Self::V0 { ref avr, .. } => {
+ ias::verify(avr, &policy.ias.clone().unwrap_or_default()).map(|vq| vq.into())
+ }
+ Self::V1 { ref quote, .. } => quote.verify(policy).map(|vq| vq.into()),
+ Self::V2 { ref ect, .. } => ect.verify(policy),
+ }
+ }
+}
+
+/// Session configuration.
+#[derive(Clone, Default)]
+struct Config {
+ consensus_verifier: Option<Arc<dyn Verifier>>,
+ identity: Option<Arc<Identity>>,
+ remote_enclaves: Option<HashSet<EnclaveIdentity>>,
+ remote_runtime_id: Option<Namespace>,
+ use_endorsement: bool,
+ policy: Option<Arc<QuotePolicy>>,
+}
+
+/// Session builder.
+#[derive(Clone, Default)]
+pub struct Builder {
+ cfg: Config,
+}
+
+impl Builder {
+ /// Return remote enclave identities if configured in the builder.
+ pub fn get_remote_enclaves(&self) -> &Option<HashSet<EnclaveIdentity>> {
+ &self.cfg.remote_enclaves
+ }
+
+ /// Enable remote enclave identity verification.
+ pub fn remote_enclaves(mut self, enclaves: Option<HashSet<EnclaveIdentity>>) -> Self {
+ self.cfg.remote_enclaves = enclaves;
+ self
+ }
+
+ /// Return remote runtime ID if configured in the builder.
+ pub fn get_remote_runtime_id(&self) -> &Option<Namespace> {
+ &self.cfg.remote_runtime_id
+ }
+
+ /// Set remote runtime ID for node identity verification.
+ pub fn remote_runtime_id(mut self, id: Option<Namespace>) -> Self {
+ self.cfg.remote_runtime_id = id;
+ self
+ }
+
+ /// Enable remote node identity verification.
+ pub fn consensus_verifier(mut self, verifier: Option<Arc<dyn Verifier>>) -> Self {
+ self.cfg.consensus_verifier = verifier;
+ self
+ }
+
+ /// Return quote policy if configured in the builder.
+ pub fn get_quote_policy(&self) -> &Option<Arc<QuotePolicy>> {
+ &self.cfg.policy
+ }
+
+ /// Configure quote policy used for remote quote verification.
+ pub fn quote_policy(mut self, policy: Option<Arc<QuotePolicy>>) -> Self {
+ self.cfg.policy = policy;
+ self
+ }
+
+ /// Use endorsement from host node when establishing sessions.
+ pub fn use_endorsement(mut self, use_endorsement: bool) -> Self {
+ self.cfg.use_endorsement = use_endorsement;
+ self
+ }
+
+ /// Return the local identity if configured in the builder.
+ pub fn get_local_identity(&self) -> &Option<Arc<Identity>> {
+ &self.cfg.identity
+ }
+
+ /// Enable RAK binding.
+ pub fn local_identity(mut self, identity: Arc<Identity>) -> Self {
+ self.cfg.identity = Some(identity);
+ self
+ }
+
+ fn build<'a>(self) -> (snow::Builder<'a>, snow::Keypair, Config) {
+ let noise_builder = snow::Builder::new(NOISE_PATTERN.parse().unwrap());
+ let keypair = noise_builder.generate_keypair().unwrap();
+ let cfg = self.cfg;
+
+ (noise_builder, keypair, cfg)
+ }
+
+ /// Build initiator session.
+ pub fn build_initiator(self) -> Session {
+ let (builder, keypair, cfg) = self.build();
+ let session = builder
+ .local_private_key(&keypair.private)
+ .build_initiator()
+ .unwrap();
+ Session::new(session, keypair.public, cfg)
+ }
+
+ /// Build responder session.
+ pub fn build_responder(self) -> Session {
+ let (builder, keypair, cfg) = self.build();
+ let session = builder
+ .local_private_key(&keypair.private)
+ .build_responder()
+ .unwrap();
+ Session::new(session, keypair.public, cfg)
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +765 +766 +767 +768 +769 +770 +771 +772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805 +806 +807 +808 +809 +810 +811 +812 +813 +814 +815 +816 +817 +818 +819 +820 +821 +822 +823 +824 +825 +826 +827 +828 +829 +830 +831 +832 +833 +834 +835 +836 +837 +838 +839 +840 +841 +842 +843 +844 +845 +846 +847 +848 +849 +850 +851 +852 +853 +854 +855 +856 +857 +858 +859 +860 +861 +862 +863 +864 +865 +866 +867 +868 +869 +870 +871 +872 +873 +874 +875 +876 +877 +878 +879 +880 +881 +882 +883 +884 +885 +886 +887 +888 +889 +890 +891 +892 +893 +894 +895 +896 +897 +898 +899 +900 +901 +902 +903 +904 +905 +906 +907 +908 +909 +910 +911 +912 +913 +914 +915 +916 +917 +918 +919 +920 +921 +922 +923 +924 +925 +926 +927 +928 +929 +930 +931 +932 +933 +934 +935 +936 +937 +938 +939 +940 +941 +942 +943 +944 +945 +946 +947 +948 +949 +950 +
//! Session demultiplexer.
+use std::{
+ collections::{BTreeSet, HashMap, HashSet},
+ hash::Hash,
+ io::Write,
+ mem,
+ sync::Arc,
+};
+
+use anyhow::Result;
+use rand::{rngs::OsRng, Rng};
+use tokio::sync::OwnedMutexGuard;
+
+use super::{
+ session::{Builder, Session, SessionInfo},
+ types::{Message, SessionID},
+};
+use crate::common::{
+ crypto::signature,
+ namespace::Namespace,
+ sgx::{EnclaveIdentity, QuotePolicy},
+ time::insecure_posix_time,
+};
+
+/// Shared pointer to a multiplexed session.
+pub type SharedSession<PeerID> = Arc<tokio::sync::Mutex<MultiplexedSession<PeerID>>>;
+
+/// Key for use in the by-idle-time index.
+pub type SessionByTimeKey<PeerID> = (i64, PeerID, SessionID);
+
+/// Sessions error.
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+ #[error("max concurrent sessions reached")]
+ MaxConcurrentSessions,
+}
+
+/// A multiplexed session.
+pub struct MultiplexedSession<PeerID> {
+ /// Peer identifier (needed for resolution when only given the shared pointer).
+ peer_id: PeerID,
+ /// Session identifier (needed for resolution when only given the shared pointer).
+ session_id: SessionID,
+ /// The actual session.
+ inner: Session,
+}
+
+impl<PeerID> MultiplexedSession<PeerID> {
+ /// Return the session's peer ID.
+ pub fn get_peer_id(&self) -> &PeerID {
+ &self.peer_id
+ }
+
+ /// Set the session's peer ID.
+ pub fn set_peer_id(&mut self, peer_id: PeerID) {
+ self.peer_id = peer_id;
+ }
+
+ /// Return the session ID.
+ pub fn get_session_id(&self) -> &SessionID {
+ &self.session_id
+ }
+
+ /// Session information.
+ pub fn info(&self) -> Option<Arc<SessionInfo>> {
+ self.inner.session_info()
+ }
+
+ /// Whether the session is in closed state.
+ pub fn is_closed(&self) -> bool {
+ self.inner.is_closed()
+ }
+
+ /// Process incoming session data.
+ pub async fn process_data<W: Write>(
+ &mut self,
+ data: &[u8],
+ writer: W,
+ ) -> Result<Option<Message>> {
+ self.inner.process_data(data, writer).await
+ }
+
+ /// Write message to session and generate a response.
+ pub fn write_message<W: Write>(&mut self, msg: Message, mut writer: W) -> Result<()> {
+ self.inner.write_message(msg, &mut writer)
+ }
+
+ /// Return remote node identifier.
+ pub fn get_remote_node(&self) -> Result<signature::PublicKey> {
+ self.inner.get_remote_node()
+ }
+
+ /// Set the remote node identifier.
+ pub fn set_remote_node(&mut self, node: signature::PublicKey) -> Result<()> {
+ self.inner.set_remote_node(node)
+ }
+
+ /// Whether the session handshake has completed and the session
+ /// is in transport mode.
+ pub fn is_connected(&self) -> bool {
+ self.inner.is_connected()
+ }
+
+ /// Whether the session is in unauthenticated transport state. In this state the session can
+ /// only be used to transmit a close notification.
+ pub fn is_unauthenticated(&self) -> bool {
+ self.inner.is_unauthenticated()
+ }
+
+ /// Mark the session as closed.
+ ///
+ /// After the session is closed it can no longer be used to transmit
+ /// or receive messages and any such use will result in an error.
+ pub fn close(&mut self) {
+ self.inner.close()
+ }
+}
+
+/// Structure used for session accounting.
+pub struct SessionMeta<PeerID: Clone + Ord + Hash> {
+ /// Peer identifier.
+ peer_id: PeerID,
+ /// Session identifier.
+ session_id: SessionID,
+ /// Timestamp when the session was last accessed.
+ last_access_time: i64,
+ /// The shared session pointer that needs to be locked for access.
+ inner: SharedSession<PeerID>,
+}
+
+impl<PeerID> SessionMeta<PeerID>
+where
+ PeerID: Clone + Ord + Hash,
+{
+ /// Key for ordering in the by-idle-time index.
+ fn by_time_key(&self) -> SessionByTimeKey<PeerID> {
+ (self.last_access_time, self.peer_id.clone(), self.session_id)
+ }
+}
+
+/// Session indices and management operations.
+pub struct Sessions<PeerID: Clone + Ord + Hash> {
+ /// Session builder.
+ builder: Builder,
+ /// Maximum number of sessions.
+ max_sessions: usize,
+ /// Maximum number of sessions per peer.
+ max_sessions_per_peer: usize,
+ /// Stale session timeout (in seconds).
+ stale_session_timeout: i64,
+
+ /// A map of sessions for each peer.
+ by_peer: HashMap<PeerID, HashMap<SessionID, SessionMeta<PeerID>>>,
+ /// A set of all sessions, ordered by idle time.
+ by_idle_time: BTreeSet<SessionByTimeKey<PeerID>>,
+}
+
+impl<PeerID> Sessions<PeerID>
+where
+ PeerID: Clone + Ord + Hash,
+{
+ /// Create a new session management instance.
+ pub fn new(
+ builder: Builder,
+ max_sessions: usize,
+ max_sessions_per_peer: usize,
+ stale_session_timeout: i64,
+ ) -> Self {
+ Self {
+ builder,
+ max_sessions,
+ max_sessions_per_peer,
+ stale_session_timeout,
+ by_peer: HashMap::new(),
+ by_idle_time: BTreeSet::new(),
+ }
+ }
+
+ /// Set the session builder to use.
+ pub fn set_builder(&mut self, builder: Builder) {
+ self.builder = builder;
+ }
+
+ /// Update remote enclave identity verification in the session builder
+ /// and clear all sessions if the identity has changed.
+ pub fn update_enclaves(
+ &mut self,
+ enclaves: Option<HashSet<EnclaveIdentity>>,
+ ) -> Vec<SharedSession<PeerID>> {
+ if self.builder.get_remote_enclaves() == &enclaves {
+ return vec![];
+ }
+
+ self.builder = mem::take(&mut self.builder).remote_enclaves(enclaves);
+ self.drain()
+ }
+
+ /// Update quote policy used for remote quote verification in the session builder
+ /// and clear all sessions if the policy has changed.
+ pub fn update_quote_policy(&mut self, policy: QuotePolicy) -> Vec<SharedSession<PeerID>> {
+ let policy = Some(Arc::new(policy));
+ if self.builder.get_quote_policy() == &policy {
+ return vec![];
+ }
+
+ self.builder = mem::take(&mut self.builder).quote_policy(policy);
+ self.drain()
+ }
+
+ /// Update remote runtime ID for node identity verification in the session builder
+ /// and clear all sessions if the runtime ID has changed.
+ pub fn update_runtime_id(&mut self, id: Option<Namespace>) -> Vec<SharedSession<PeerID>> {
+ if self.builder.get_remote_runtime_id() == &id {
+ return vec![];
+ }
+
+ self.builder = mem::take(&mut self.builder).remote_runtime_id(id);
+ self.drain()
+ }
+
+ /// Create a new multiplexed responder session.
+ pub fn create_responder(
+ &mut self,
+ peer_id: PeerID,
+ session_id: SessionID,
+ ) -> MultiplexedSession<PeerID> {
+ // If no quote policy is set, use the local one.
+ if self.builder.get_quote_policy().is_none() {
+ let policy = self
+ .builder
+ .get_local_identity()
+ .as_ref()
+ .and_then(|id| id.quote_policy());
+
+ self.builder = mem::take(&mut self.builder).quote_policy(policy);
+ }
+
+ MultiplexedSession {
+ peer_id: peer_id.clone(),
+ session_id,
+ inner: self.builder.clone().build_responder(),
+ }
+ }
+
+ /// Create a new multiplexed initiator session.
+ pub fn create_initiator(&self, peer_id: PeerID) -> MultiplexedSession<PeerID> {
+ let session_id = SessionID::random();
+
+ MultiplexedSession {
+ peer_id: peer_id.clone(),
+ session_id,
+ inner: self.builder.clone().build_initiator(),
+ }
+ }
+
+ /// Fetch an existing session given its identifier.
+ pub fn get(
+ &mut self,
+ peer_id: &PeerID,
+ session_id: &SessionID,
+ ) -> Option<SharedSession<PeerID>> {
+ // Check if peer exists.
+ let sessions = match self.by_peer.get_mut(peer_id) {
+ Some(sessions) => sessions,
+ None => return None,
+ };
+
+ // Check if the session exists. If so, return it.
+ let session = match sessions.get_mut(session_id) {
+ Some(session) => session,
+ None => return None,
+ };
+
+ Self::update_access_time(session, &mut self.by_idle_time);
+
+ Some(session.inner.clone())
+ }
+
+ /// Fetch an existing session from one of the given peers. If no peers
+ /// are provided, a session from any peer will be returned.
+ pub fn find(&mut self, peer_ids: &[PeerID]) -> Option<SharedSession<PeerID>> {
+ match peer_ids.is_empty() {
+ true => self.find_any(),
+ false => self.find_one(peer_ids),
+ }
+ }
+
+ /// Fetch an existing session from any peer.
+ pub fn find_any(&mut self) -> Option<SharedSession<PeerID>> {
+ if self.by_idle_time.is_empty() {
+ return None;
+ }
+
+ // Check if there is a session that is not currently in use.
+ for (_, peer_id, session_id) in self.by_idle_time.iter() {
+ let session = self
+ .by_peer
+ .get_mut(peer_id)
+ .unwrap()
+ .get_mut(session_id)
+ .unwrap();
+
+ if session.inner.clone().try_lock_owned().is_ok() {
+ Self::update_access_time(session, &mut self.by_idle_time);
+ return Some(session.inner.clone());
+ }
+ }
+
+ // If all sessions are in use, return a random one.
+ let n = OsRng.gen_range(0..self.by_idle_time.len());
+ let (_, peer_id, session_id) = self.by_idle_time.iter().nth(n).unwrap();
+ let session = self
+ .by_peer
+ .get_mut(peer_id)
+ .unwrap()
+ .get_mut(session_id)
+ .unwrap();
+
+ Self::update_access_time(session, &mut self.by_idle_time);
+
+ Some(session.inner.clone())
+ }
+
+ /// Fetch an existing session from one of the given peers.
+ pub fn find_one(&mut self, peer_ids: &[PeerID]) -> Option<SharedSession<PeerID>> {
+ let mut all_sessions = vec![];
+
+ for peer_id in peer_ids.iter() {
+ let sessions = match self.by_peer.get_mut(peer_id) {
+ Some(sessions) => sessions,
+ None => return None,
+ };
+
+ // Check if peer has a session that is not currently in use.
+ let session = sessions
+ .values_mut()
+ .filter(|s| s.inner.clone().try_lock_owned().is_ok())
+ .min_by_key(|s| s.last_access_time);
+
+ if let Some(session) = session {
+ Self::update_access_time(session, &mut self.by_idle_time);
+ return Some(session.inner.clone());
+ }
+
+ for session in sessions.values() {
+ all_sessions.push((session.peer_id.clone(), session.session_id));
+ }
+ }
+
+ if all_sessions.is_empty() {
+ return None;
+ }
+
+ // If all sessions are in use, return a random one.
+ let n = OsRng.gen_range(0..all_sessions.len());
+ let (peer_id, session_id) = all_sessions.get(n).unwrap();
+ let session = self
+ .by_peer
+ .get_mut(peer_id)
+ .unwrap()
+ .get_mut(session_id)
+ .unwrap();
+
+ Self::update_access_time(session, &mut self.by_idle_time);
+
+ Some(session.inner.clone())
+ }
+
+ /// Remove one session to free up a slot for the given peer.
+ pub fn remove_for(
+ &mut self,
+ peer_id: &PeerID,
+ now: i64,
+ ) -> Result<Option<OwnedMutexGuard<MultiplexedSession<PeerID>>>, Error> {
+ if let Some(session) = self.remove_from(peer_id)? {
+ return Ok(Some(session));
+ }
+ self.remove_one(now)
+ }
+
+ /// Remove one existing session from the given peer if the peer has reached
+ /// the maximum number of sessions or if the total number of sessions exceeds
+ /// the global session limit.
+ pub fn remove_from(
+ &mut self,
+ peer_id: &PeerID,
+ ) -> Result<Option<OwnedMutexGuard<MultiplexedSession<PeerID>>>, Error> {
+ // Check if peer exists.
+ let sessions = match self.by_peer.get_mut(peer_id) {
+ Some(sessions) => sessions,
+ None => return Ok(None),
+ };
+
+ // Check if the peer has max sessions or if no more sessions are available globally.
+ // If so, remove the oldest or return an error.
+ if sessions.len() < self.max_sessions_per_peer
+ && self.by_idle_time.len() < self.max_sessions
+ {
+ return Ok(None);
+ }
+
+ // Force close the oldest idle session.
+ let remove_session = sessions
+ .iter()
+ .min_by_key(|(_, s)| {
+ if let Ok(_inner) = s.inner.try_lock() {
+ s.last_access_time
+ } else {
+ i64::MAX // Session is currently in use.
+ }
+ })
+ .map(|(_, s)| s.inner.clone())
+ .ok_or(Error::MaxConcurrentSessions)?;
+
+ let session = match remove_session.try_lock_owned() {
+ Ok(inner) => inner,
+ Err(_) => return Err(Error::MaxConcurrentSessions), // All sessions are in use.
+ };
+
+ self.remove(&session);
+
+ Ok(Some(session))
+ }
+
+ /// Remove one stale session if the total number of sessions exceeds
+ /// the global session limit.
+ pub fn remove_one(
+ &mut self,
+ now: i64,
+ ) -> Result<Option<OwnedMutexGuard<MultiplexedSession<PeerID>>>, Error> {
+ // Check if there are too many sessions. If so, remove one or return an error.
+ if self.by_idle_time.len() < self.max_sessions {
+ return Ok(None);
+ }
+
+ // Attempt to prune stale sessions, starting with the oldest ones.
+ let mut remove_session: Option<OwnedMutexGuard<MultiplexedSession<PeerID>>> = None;
+
+ for (last_process_frame_time, peer_id, session_id) in self.by_idle_time.iter() {
+ if now.saturating_sub(*last_process_frame_time) < self.stale_session_timeout {
+ // This is the oldest session, all next ones will be more fresh.
+ return Err(Error::MaxConcurrentSessions);
+ }
+
+ // Fetch session and attempt to lock it.
+ if let Some(sessions) = self.by_peer.get(peer_id) {
+ if let Some(session) = sessions.get(session_id) {
+ if let Ok(session) = session.inner.clone().try_lock_owned() {
+ remove_session = Some(session);
+ break;
+ }
+ }
+ }
+ }
+
+ // Check if we found a session that can be removed.
+ let session = match remove_session {
+ Some(session) => session,
+ None => return Err(Error::MaxConcurrentSessions), // All stale sessions are in use.
+ };
+
+ self.remove(&session);
+
+ Ok(Some(session))
+ }
+
+ /// Add a session if there is an available spot.
+ pub fn add(
+ &mut self,
+ session: MultiplexedSession<PeerID>,
+ now: i64,
+ ) -> Result<SharedSession<PeerID>, Error> {
+ if self.by_idle_time.len() >= self.max_sessions {
+ return Err(Error::MaxConcurrentSessions);
+ }
+
+ let sessions = self.by_peer.entry(session.peer_id.clone()).or_default();
+ if sessions.len() >= self.max_sessions_per_peer {
+ return Err(Error::MaxConcurrentSessions);
+ }
+
+ let peer_id = session.peer_id.clone();
+ let session_id = session.session_id;
+
+ let session = SessionMeta {
+ inner: Arc::new(tokio::sync::Mutex::new(session)),
+ peer_id,
+ session_id,
+ last_access_time: now,
+ };
+ let inner = session.inner.clone();
+
+ self.by_idle_time.insert(session.by_time_key());
+ sessions.insert(session.session_id, session);
+
+ Ok(inner)
+ }
+
+ /// Remove a session that must be currently owned by the caller.
+ pub fn remove(&mut self, session: &OwnedMutexGuard<MultiplexedSession<PeerID>>) {
+ let sessions = self.by_peer.get_mut(&session.peer_id).unwrap();
+ let session_meta = sessions.get(&session.session_id).unwrap();
+ let key = session_meta.by_time_key();
+ sessions.remove(&session.session_id);
+ self.by_idle_time.remove(&key);
+
+ // If peer doesn't have any more sessions, remove the peer.
+ if sessions.is_empty() {
+ self.by_peer.remove(&session.peer_id);
+ }
+ }
+
+ /// Removes and returns all sessions.
+ pub fn drain(&mut self) -> Vec<SharedSession<PeerID>> {
+ self.by_idle_time.clear();
+
+ let mut all_sessions = vec![];
+ for (_, mut sessions) in self.by_peer.drain() {
+ for (_, session) in sessions.drain() {
+ all_sessions.push(session.inner);
+ }
+ }
+
+ all_sessions
+ }
+
+ fn update_access_time(
+ session: &mut SessionMeta<PeerID>,
+ by_idle_time: &mut BTreeSet<SessionByTimeKey<PeerID>>,
+ ) {
+ // Remove old idle time.
+ by_idle_time.remove(&session.by_time_key());
+
+ // Update idle time.
+ session.last_access_time = insecure_posix_time();
+ by_idle_time.insert(session.by_time_key());
+ }
+
+ /// Number of all sessions.
+ #[cfg(test)]
+ fn session_count(&self) -> usize {
+ self.by_idle_time.len()
+ }
+
+ /// Number of all peers.
+ #[cfg(test)]
+ fn peer_count(&self) -> usize {
+ self.by_peer.len()
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use crate::enclave_rpc::{session::Builder, types::SessionID};
+
+ use super::{Error, Sessions};
+
+ fn ids() -> (Vec<Vec<u8>>, Vec<SessionID>) {
+ let peer_ids: Vec<Vec<u8>> = (1..8).map(|x| vec![x]).collect();
+ let session_ids: Vec<SessionID> = (1..8).map(|_| SessionID::random()).collect();
+
+ (peer_ids, session_ids)
+ }
+
+ #[test]
+ fn test_add() {
+ let (peer_ids, session_ids) = ids();
+ let mut sessions = Sessions::new(Builder::default(), 4, 2, 60);
+
+ let test_vector = vec![
+ (&peer_ids[0], &session_ids[0], 1, 1, true),
+ (&peer_ids[0], &session_ids[1], 2, 1, true), // Different session ID.
+ (&peer_ids[0], &session_ids[2], 2, 1, false), // Too many sessions per peer.
+ (&peer_ids[1], &session_ids[0], 3, 2, true), // Different peer ID.
+ (&peer_ids[2], &session_ids[2], 4, 3, true), // Different peer ID and session ID.
+ (&peer_ids[3], &session_ids[3], 4, 3, false), // Too many sessions.
+ ];
+
+ let now = 0;
+ for (peer_id, session_id, num_sessions, num_peers, created) in test_vector {
+ let session = sessions.create_responder(peer_id.clone(), session_id.clone());
+ let res = sessions.add(session, now);
+ match created {
+ true => {
+ assert!(res.is_ok(), "session should be created");
+ let s = res.unwrap();
+ let s_owned = s.try_lock().unwrap();
+ assert_eq!(&s_owned.peer_id, peer_id);
+ assert_eq!(&s_owned.session_id, session_id);
+ }
+ false => {
+ assert!(res.is_err(), "session should not be created");
+ assert!(matches!(res, Err(Error::MaxConcurrentSessions)));
+ }
+ };
+ assert_eq!(sessions.session_count(), num_sessions);
+ assert_eq!(sessions.peer_count(), num_peers);
+ }
+ }
+
+ #[test]
+ fn test_get() {
+ let (peer_ids, session_ids) = ids();
+ let mut sessions = Sessions::new(Builder::default(), 8, 2, 60);
+
+ let test_vector = vec![
+ (&peer_ids[0], &session_ids[0], true),
+ (&peer_ids[0], &session_ids[1], false), // Different peer ID.
+ (&peer_ids[1], &session_ids[0], false), // Different session ID.
+ (&peer_ids[1], &session_ids[1], false), // Different peer ID and session ID.
+ ];
+
+ let now = 0;
+ for (peer_id, session_id, create) in test_vector {
+ if create {
+ let session = sessions.create_responder(peer_id.clone(), session_id.clone());
+ let _ = sessions.add(session, now);
+ }
+
+ let maybe_s = sessions.get(peer_id, session_id);
+ match create {
+ true => {
+ assert!(maybe_s.is_some(), "session should exist");
+ let s = maybe_s.unwrap();
+ let s_owned = s.try_lock_owned().unwrap();
+ assert_eq!(&s_owned.peer_id, peer_id);
+ assert_eq!(&s_owned.session_id, session_id);
+ }
+ false => assert!(maybe_s.is_none(), "session should not exist"),
+ }
+ }
+ }
+
+ #[test]
+ fn test_find_any() {
+ let (peer_ids, session_ids) = ids();
+ let mut sessions = Sessions::new(Builder::default(), 8, 2, 60);
+
+ let test_vector = vec![
+ (&peer_ids[0], &session_ids[0]),
+ (&peer_ids[0], &session_ids[1]),
+ (&peer_ids[1], &session_ids[2]),
+ ];
+
+ // No sessions.
+ let maybe_s = sessions.find_any();
+ assert!(maybe_s.is_none(), "session should not be found");
+
+ let mut now = 0;
+ for (peer_id, session_id) in test_vector {
+ let session = sessions.create_responder(peer_id.clone(), session_id.clone());
+ let _ = sessions.add(session, now);
+ now += 1
+ }
+
+ // No sessions in use.
+ let maybe_s = sessions.find_any();
+ assert!(maybe_s.is_some(), "session should be found");
+ let s = maybe_s.unwrap();
+ let s1_owned = s.try_lock_owned().unwrap(); // Session now in use.
+ assert_eq!(&s1_owned.peer_id, &peer_ids[0]);
+ assert_eq!(&s1_owned.session_id, &session_ids[0]);
+
+ // One session in use.
+ let maybe_s = sessions.find_any();
+ assert!(maybe_s.is_some(), "session should be found");
+ let s = maybe_s.unwrap();
+ let s2_owned = s.try_lock_owned().unwrap(); // Session now in use.
+ assert_eq!(&s2_owned.peer_id, &peer_ids[0]);
+ assert_eq!(&s2_owned.session_id, &session_ids[1]); // Different session found.
+
+ // Two sessions in use.
+ let maybe_s = sessions.find_any();
+ assert!(maybe_s.is_some(), "session should be found");
+ let s = maybe_s.unwrap();
+ let s3_owned = s.try_lock_owned().unwrap(); // Session now in use.
+ assert_eq!(&s3_owned.peer_id, &peer_ids[1]);
+ assert_eq!(&s3_owned.session_id, &session_ids[2]); // Different session found.
+
+ // All sessions in use.
+ let maybe_s = sessions.find_any();
+ assert!(maybe_s.is_some(), "session should be found");
+ let s = maybe_s.unwrap();
+ let res = s.try_lock_owned(); // Session now in use.
+ assert!(res.is_err(), "session should be in use");
+
+ // Free one session.
+ drop(s2_owned);
+
+ // Two sessions in use.
+ let maybe_s = sessions.find_any();
+ assert!(maybe_s.is_some(), "session should be found");
+ let s = maybe_s.unwrap();
+ let s_owned = s.try_lock_owned().unwrap(); // Session now in use.
+ assert_eq!(&s_owned.peer_id, &peer_ids[0]);
+ assert_eq!(&s_owned.session_id, &session_ids[1]);
+ }
+
+ #[test]
+ fn test_find_one() {
+ let (peer_ids, session_ids) = ids();
+ let mut sessions = Sessions::new(Builder::default(), 8, 2, 60);
+
+ let test_vector = vec![
+ (&peer_ids[2], &session_ids[0]), // Incorrect peer.
+ (&peer_ids[0], &session_ids[0]),
+ (&peer_ids[3], &session_ids[1]), // Incorrect peer.
+ (&peer_ids[0], &session_ids[1]),
+ (&peer_ids[3], &session_ids[2]), // Incorrect peer.
+ (&peer_ids[1], &session_ids[2]),
+ (&peer_ids[2], &session_ids[2]), // Incorrect peer.
+ ];
+
+ // No sessions.
+ let maybe_s = sessions.find_one(&peer_ids[0..2]);
+ assert!(maybe_s.is_none(), "session should not be found");
+
+ let mut now = 0;
+ for (peer_id, session_id) in test_vector {
+ let session = sessions.create_responder(peer_id.clone(), session_id.clone());
+ let _ = sessions.add(session, now);
+ now += 1
+ }
+
+ // Peers without sessions.
+ let maybe_s = sessions.find_one(&peer_ids[4..]);
+ assert!(maybe_s.is_none(), "session should not be found");
+
+ // No sessions in use.
+ let maybe_s = sessions.find_one(&peer_ids[0..2]);
+ assert!(maybe_s.is_some(), "session should be found");
+ let s = maybe_s.unwrap();
+ let s1_owned = s.try_lock_owned().unwrap(); // Session now in use.
+ assert_eq!(&s1_owned.peer_id, &peer_ids[0]);
+ assert_eq!(&s1_owned.session_id, &session_ids[0]);
+
+ // One session in use.
+ let maybe_s = sessions.find_one(&peer_ids[0..2]);
+ assert!(maybe_s.is_some(), "session should be found");
+ let s = maybe_s.unwrap();
+ let s2_owned = s.try_lock_owned().unwrap(); // Session now in use.
+ assert_eq!(&s2_owned.peer_id, &peer_ids[0]);
+ assert_eq!(&s2_owned.session_id, &session_ids[1]); // Different session found.
+
+ // Two sessions in use.
+ let maybe_s = sessions.find_one(&peer_ids[0..2]);
+ assert!(maybe_s.is_some(), "session should be found");
+ let s = maybe_s.unwrap();
+ let s3_owned = s.try_lock_owned().unwrap(); // Session now in use.
+ assert_eq!(&s3_owned.peer_id, &peer_ids[1]);
+ assert_eq!(&s3_owned.session_id, &session_ids[2]); // Different session found.
+
+ // All sessions in use.
+ let maybe_s = sessions.find_one(&peer_ids[0..2]);
+ assert!(maybe_s.is_some(), "session should be found");
+ let s = maybe_s.unwrap();
+ let res = s.try_lock_owned(); // Session now in use.
+ assert!(res.is_err(), "session should be in use");
+
+ // Free one session.
+ drop(s2_owned);
+
+ // Two sessions in use.
+ let maybe_s = sessions.find_one(&peer_ids[0..2]);
+ assert!(maybe_s.is_some(), "session should be found");
+ let s = maybe_s.unwrap();
+ let s_owned = s.try_lock_owned().unwrap(); // Session now in use.
+ assert_eq!(&s_owned.peer_id, &peer_ids[0]);
+ assert_eq!(&s_owned.session_id, &session_ids[1]);
+ }
+
+ #[test]
+ fn test_remove_from() {
+ let (peer_ids, session_ids) = ids();
+ let mut sessions = Sessions::new(Builder::default(), 4, 2, 60);
+
+ let test_vector = vec![
+ (&peer_ids[0], &session_ids[0]),
+ (&peer_ids[1], &session_ids[1]),
+ (&peer_ids[2], &session_ids[2]),
+ (&peer_ids[2], &session_ids[3]), // Max sessions per peer reached.
+ // Max sessions reached.
+ ];
+
+ let mut now = 0;
+ for (peer_id, session_id) in test_vector.clone() {
+ let session = sessions.create_responder(peer_id.clone(), session_id.clone());
+ let _ = sessions.add(session, now);
+ now += 1;
+ }
+
+ // Removing one session from an unknown peer should have no effect,
+ // even if all global session slots are occupied.
+ let res = sessions.remove_from(&peer_ids[3]);
+ assert!(res.is_ok(), "remove_from should succeed");
+ let maybe_s_owned = res.unwrap();
+ assert!(maybe_s_owned.is_none(), "no sessions should be removed");
+ assert_eq!(sessions.session_count(), 4);
+ assert_eq!(sessions.peer_count(), 3);
+
+ // Removing one session for one of the existing peers should work
+ // as it should force evict an old session.
+ // Note that each peer has 2 available slots, but globally there are
+ // only 4 slots so if global slots are full this should trigger peer
+ // session eviction.
+ let res = sessions.remove_from(&peer_ids[0]);
+ assert!(res.is_ok(), "remove_from should succeed");
+ let maybe_s_owned = res.unwrap();
+ assert!(maybe_s_owned.is_some(), "one session should be removed");
+ let s_owned = maybe_s_owned.unwrap();
+ assert_eq!(&s_owned.peer_id, &peer_ids[0]);
+ assert_eq!(&s_owned.session_id, &session_ids[0]);
+ assert_eq!(sessions.session_count(), 3);
+ assert_eq!(sessions.peer_count(), 2);
+
+ // Removing another session should fail as one global session slot
+ // is available.
+ for peer_id in vec![&peer_ids[0], &peer_ids[1]] {
+ let res = sessions.remove_from(peer_id);
+ assert!(res.is_ok(), "remove_from should succeed");
+ let maybe_s_owned = res.unwrap();
+ assert!(maybe_s_owned.is_none(), "no sessions should be removed");
+ assert_eq!(sessions.session_count(), 3);
+ assert_eq!(sessions.peer_count(), 2);
+ }
+
+ // Removing one session from a peer with max sessions should succeed
+ // even if one global slot is available.
+ let res = sessions.remove_from(&peer_ids[2]);
+ assert!(res.is_ok(), "remove_from should succeed");
+ let maybe_s_owned = res.unwrap();
+ assert!(maybe_s_owned.is_some(), "one session should be removed");
+ let s_owned = maybe_s_owned.unwrap();
+ assert_eq!(&s_owned.peer_id, &peer_ids[2]);
+ assert_eq!(&s_owned.session_id, &session_ids[2]);
+ assert_eq!(sessions.session_count(), 2);
+ assert_eq!(sessions.peer_count(), 2);
+ }
+
+ #[test]
+ fn test_remove_one() {
+ let (peer_ids, session_ids) = ids();
+ let mut sessions = Sessions::new(Builder::default(), 4, 2, 60);
+
+ let test_vector = vec![
+ (&peer_ids[0], &session_ids[0]),
+ (&peer_ids[1], &session_ids[1]),
+ (&peer_ids[2], &session_ids[2]),
+ (&peer_ids[2], &session_ids[3]), // Max sessions reached.
+ ];
+
+ let mut now = 0;
+ for (peer_id, session_id) in test_vector.clone() {
+ let session = sessions.create_responder(peer_id.clone(), session_id.clone());
+ let _ = sessions.add(session, now);
+ now += 1;
+ }
+
+ // Forward time (stale_session_timeout - test_vector.len() - 1).
+ now += 60 - 4 - 1;
+
+ // Removing one session should fail as there are none stale sessions.
+ let res = sessions.remove_one(now);
+ assert!(res.is_err(), "remove_one should fail");
+ assert!(matches!(res, Err(Error::MaxConcurrentSessions)));
+ assert_eq!(sessions.session_count(), 4);
+ assert_eq!(sessions.peer_count(), 3);
+
+ // Forward time.
+ now += 1;
+
+ // Removing one session should succeed as no session slots
+ // are available and there is one stale session.
+ let res = sessions.remove_one(now);
+ assert!(res.is_ok(), "remove_one should succeed");
+ let maybe_s_owned = res.unwrap();
+ assert!(maybe_s_owned.is_some(), "one session should be removed");
+ let s_owned = maybe_s_owned.unwrap();
+ assert_eq!(&s_owned.peer_id, &peer_ids[0]);
+ assert_eq!(&s_owned.session_id, &session_ids[0]);
+ assert_eq!(sessions.session_count(), 3);
+ assert_eq!(sessions.peer_count(), 2);
+
+ // Forward time.
+ now += 100;
+
+ // Removing one session should fail even though there are stale sessions
+ // because there is one session slot available.
+ let res = sessions.remove_one(now);
+ assert!(res.is_ok(), "remove_one should succeed");
+ let maybe_s_owned = res.unwrap();
+ assert!(maybe_s_owned.is_none(), "no sessions should be removed");
+ assert_eq!(sessions.session_count(), 3);
+ assert_eq!(sessions.peer_count(), 2);
+ }
+
+ #[test]
+ fn test_remove() {
+ let (peer_ids, session_ids) = ids();
+ let mut sessions = Sessions::new(Builder::default(), 8, 2, 60);
+
+ let test_vector = vec![
+ (&peer_ids[0], &session_ids[0], 3, 2),
+ (&peer_ids[1], &session_ids[1], 2, 1),
+ (&peer_ids[2], &session_ids[2], 1, 1),
+ (&peer_ids[2], &session_ids[3], 0, 0),
+ ];
+
+ let now = 0;
+ for (peer_id, session_id, _, _) in test_vector.clone() {
+ let session = sessions.create_responder(peer_id.clone(), session_id.clone());
+ let _ = sessions.add(session, now);
+ }
+
+ for (peer_id, session_id, num_sessions, num_peers) in test_vector {
+ let maybe_s = sessions.get(peer_id, session_id);
+ assert!(maybe_s.is_some(), "session should exist");
+ let s = maybe_s.unwrap();
+ let s_owned = s.try_lock_owned().unwrap();
+
+ sessions.remove(&s_owned);
+ assert_eq!(sessions.session_count(), num_sessions);
+ assert_eq!(sessions.peer_count(), num_peers);
+ }
+ }
+
+ #[test]
+ fn test_clear() {
+ let (peer_ids, session_ids) = ids();
+ let mut sessions = Sessions::new(Builder::default(), 8, 2, 60);
+
+ let test_vector = vec![
+ (&peer_ids[0], &session_ids[0]),
+ (&peer_ids[1], &session_ids[1]),
+ (&peer_ids[2], &session_ids[2]),
+ (&peer_ids[2], &session_ids[3]),
+ ];
+
+ let now = 0;
+ for (peer_id, session_id) in test_vector.clone() {
+ let session = sessions.create_responder(peer_id.clone(), session_id.clone());
+ let _ = sessions.add(session, now);
+ }
+
+ let removed_sessions = sessions.drain();
+ assert_eq!(removed_sessions.len(), 4);
+ assert_eq!(sessions.session_count(), 0);
+ assert_eq!(sessions.peer_count(), 0);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +
use std::sync::Arc;
+
+use anyhow::{anyhow, Error as AnyError};
+use async_trait::async_trait;
+
+use crate::{common::crypto::signature, types::Body, Protocol};
+
+use super::types;
+
+// Enclave's response.
+pub struct EnclaveResponse {
+ // Actual response data.
+ pub data: Vec<u8>,
+ // The public key of the node that generated the response.
+ pub node: signature::PublicKey,
+}
+
+/// An EnclaveRPC transport.
+#[async_trait]
+pub trait Transport: Send + Sync {
+ async fn write_noise_session(
+ &self,
+ request_id: u64,
+ session_id: types::SessionID,
+ data: Vec<u8>,
+ untrusted_plaintext: String,
+ nodes: Vec<signature::PublicKey>,
+ ) -> Result<EnclaveResponse, AnyError> {
+ let frame = types::Frame {
+ session: session_id,
+ untrusted_plaintext,
+ payload: data,
+ };
+
+ self.write_message_impl(
+ request_id,
+ cbor::to_vec(frame),
+ types::Kind::NoiseSession,
+ nodes,
+ )
+ .await
+ }
+
+ async fn write_insecure_query(
+ &self,
+ request_id: u64,
+ data: Vec<u8>,
+ nodes: Vec<signature::PublicKey>,
+ ) -> Result<EnclaveResponse, AnyError> {
+ self.write_message_impl(request_id, data, types::Kind::InsecureQuery, nodes)
+ .await
+ }
+
+ async fn write_message_impl(
+ &self,
+ request_id: u64,
+ data: Vec<u8>,
+ kind: types::Kind,
+ nodes: Vec<signature::PublicKey>,
+ ) -> Result<EnclaveResponse, AnyError>;
+
+ async fn submit_peer_feedback(
+ &self,
+ request_id: u64,
+ feedback: types::PeerFeedback,
+ ) -> Result<(), AnyError>;
+}
+
+/// A transport implementation which can be used from inside the runtime and uses the Runtime Host
+/// Protocol to transport EnclaveRPC frames.
+pub struct RuntimeTransport {
+ pub protocol: Arc<Protocol>,
+ pub endpoint: String,
+}
+
+impl RuntimeTransport {
+ pub fn new(protocol: Arc<Protocol>, endpoint: &str) -> Self {
+ Self {
+ protocol,
+ endpoint: endpoint.to_string(),
+ }
+ }
+}
+
+#[async_trait]
+impl Transport for RuntimeTransport {
+ async fn write_message_impl(
+ &self,
+ request_id: u64,
+ data: Vec<u8>,
+ kind: types::Kind,
+ nodes: Vec<signature::PublicKey>,
+ ) -> Result<EnclaveResponse, AnyError> {
+ let rsp = self
+ .protocol
+ .call_host_async(Body::HostRPCCallRequest {
+ endpoint: self.endpoint.clone(),
+ request_id,
+ request: data,
+ kind,
+ nodes,
+ })
+ .await?;
+
+ match rsp {
+ Body::HostRPCCallResponse { response, node } => Ok(EnclaveResponse {
+ data: response,
+ node,
+ }),
+ _ => Err(anyhow!("bad response type")),
+ }
+ }
+
+ async fn submit_peer_feedback(
+ &self,
+ request_id: u64,
+ peer_feedback: types::PeerFeedback,
+ ) -> Result<(), AnyError> {
+ let rsp = self
+ .protocol
+ .call_host_async(Body::HostSubmitPeerFeedbackRequest {
+ endpoint: self.endpoint.clone(),
+ request_id,
+ peer_feedback,
+ })
+ .await?;
+
+ match rsp {
+ Body::HostSubmitPeerFeedbackResponse {} => Ok(()),
+ _ => Err(anyhow!("bad response type")),
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +
//! RPC protocol types.
+use rand::{rngs::OsRng, Rng};
+
+impl_bytes!(
+ SessionID,
+ 32,
+ "Session identifier for multiplexing multiple sessions over the \
+ same transport"
+);
+
+impl SessionID {
+ /// Generate a random session identifier.
+ pub fn random() -> Self {
+ let mut session_id = [0u8; 32];
+ OsRng.fill(&mut session_id);
+
+ SessionID(session_id)
+ }
+}
+
+/// RPC call kind.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+#[cbor(with_default)]
+#[repr(u8)]
+pub enum Kind {
+ /// A secure RPC call using an encrypted and authenticated Noise session.
+ NoiseSession = 0,
+ /// An insecure RPC call where messages are sent in plain text.
+ InsecureQuery = 1,
+ /// A local RPC call.
+ LocalQuery = 2,
+}
+
+impl Default for Kind {
+ fn default() -> Self {
+ Self::NoiseSession
+ }
+}
+
+/// Frame.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Frame {
+ pub session: SessionID,
+ // The `untrusted_plaintext` field is only a temporary workaround until
+ // the snow library supports encrypting the payload with authenticated
+ // data.
+ // This field contains a plaintext copy of the Request's `method` field
+ // and is verified inside the enclave. It is unused in other cases.
+ pub untrusted_plaintext: String,
+ pub payload: Vec<u8>,
+}
+
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct Request {
+ pub method: String,
+ pub args: cbor::Value,
+}
+
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Error {
+ pub message: String,
+}
+
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub enum Body {
+ Success(cbor::Value),
+ Error(String),
+}
+
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct Response {
+ pub body: Body,
+}
+
+/// Protocol message.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub enum Message {
+ Request(Request),
+ Response(Response),
+ Close,
+}
+
+/// Feedback on the peer that handled the last EnclaveRPC call.
+#[derive(Copy, Clone, Debug, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub enum PeerFeedback {
+ Success = 0,
+ Failure = 1,
+ BadPeer = 2,
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +
//! Helper functions to use with the asynchronous Tokio runtime.
+use std::future::Future;
+
+/// Create a new asynchronous Tokio runtime.
+#[cfg(any(target_env = "sgx", feature = "debug-mock-sgx"))]
+pub fn new_tokio_runtime() -> tokio::runtime::Runtime {
+ // In SGX use a trimmed-down version of the Tokio runtime.
+ //
+ // Make sure to update THREADS.md if you change any of the thread-related settings.
+ tokio::runtime::Builder::new_multi_thread()
+ .worker_threads(6)
+ .max_blocking_threads(16)
+ .thread_keep_alive(std::time::Duration::MAX)
+ .enable_all()
+ .build()
+ .unwrap()
+}
+
+/// Create a new asynchronous Tokio runtime.
+#[cfg(not(any(target_env = "sgx", feature = "debug-mock-sgx")))]
+pub fn new_tokio_runtime() -> tokio::runtime::Runtime {
+ // In non-SGX we use a fully-fledged Tokio runtime.
+ tokio::runtime::Runtime::new().unwrap()
+}
+
+/// Runs a future to completion on the current Tokio handle's associated Runtime.
+pub fn block_on<F: Future>(future: F) -> F::Output {
+ tokio::runtime::Handle::current().block_on(future)
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +
//! Host interface.
+use async_trait::async_trait;
+use thiserror::Error;
+
+use crate::{
+ common::{crypto::signature::PublicKey, namespace::Namespace},
+ protocol::Protocol,
+ storage::mkvs::sync,
+ types::{self, Body},
+};
+
+/// Errors.
+#[derive(Error, Debug)]
+pub enum Error {
+ #[error("bad response from host")]
+ BadResponse,
+ #[error("{0}")]
+ Other(#[from] types::Error),
+}
+
+/// Transaction submission options.
+#[derive(Clone, Default, Debug)]
+pub struct SubmitTxOpts {
+ /// Target runtime identifier. If not specified, own runtime identifier is used.
+ pub runtime_id: Option<Namespace>,
+ /// Whether the call should wait until the transaction is included in a block.
+ pub wait: bool,
+ /// Whether the response should include a proof of transaction being included in a block.
+ pub prove: bool,
+}
+
+/// Transaction submission result.
+#[derive(Clone, Default, Debug)]
+pub struct TxResult {
+ /// Transaction output.
+ pub output: Vec<u8>,
+ /// Round in which the transaction was executed.
+ pub round: u64,
+ /// Order of the transaction in the execution batch.
+ pub batch_order: u32,
+ /// Optional inclusion proof.
+ pub proof: Option<sync::Proof>,
+}
+
+/// Notification registration options.
+#[derive(Clone, Default, Debug)]
+pub struct RegisterNotifyOpts {
+ /// Subscribe to runtime block notifications.
+ pub runtime_block: bool,
+ /// Subscribe to runtime event notifications.
+ pub runtime_event: Vec<Vec<u8>>,
+}
+
+/// Interface to the (untrusted) host node.
+#[async_trait]
+pub trait Host: Send + Sync {
+ /// Returns the identity of the host node.
+ async fn identity(&self) -> Result<PublicKey, Error>;
+
+ /// Submit a transaction.
+ async fn submit_tx(&self, data: Vec<u8>, opts: SubmitTxOpts)
+ -> Result<Option<TxResult>, Error>;
+
+ /// Register for receiving notifications.
+ async fn register_notify(&self, opts: RegisterNotifyOpts) -> Result<(), Error>;
+}
+
+#[async_trait]
+impl Host for Protocol {
+ async fn identity(&self) -> Result<PublicKey, Error> {
+ match self.call_host_async(Body::HostIdentityRequest {}).await? {
+ Body::HostIdentityResponse { node_id } => Ok(node_id),
+ _ => Err(Error::BadResponse),
+ }
+ }
+
+ async fn submit_tx(
+ &self,
+ data: Vec<u8>,
+ opts: SubmitTxOpts,
+ ) -> Result<Option<TxResult>, Error> {
+ match self
+ .call_host_async(Body::HostSubmitTxRequest {
+ runtime_id: opts.runtime_id.unwrap_or_else(|| self.get_runtime_id()),
+ data,
+ wait: opts.wait,
+ prove: opts.prove,
+ })
+ .await?
+ {
+ Body::HostSubmitTxResponse {
+ output,
+ round,
+ batch_order,
+ proof,
+ } => {
+ if opts.wait {
+ Ok(Some(TxResult {
+ output,
+ round,
+ batch_order,
+ proof,
+ }))
+ } else {
+ // If we didn't wait for inclusion then there is no result.
+ Ok(None)
+ }
+ }
+ _ => Err(Error::BadResponse),
+ }
+ }
+
+ async fn register_notify(&self, opts: RegisterNotifyOpts) -> Result<(), Error> {
+ match self
+ .call_host_async(Body::HostRegisterNotifyRequest {
+ runtime_block: opts.runtime_block,
+ runtime_event: match opts.runtime_event {
+ tags if tags.is_empty() => None,
+ tags => Some(types::RegisterNotifyRuntimeEvent { tags }),
+ },
+ })
+ .await?
+ {
+ Body::Empty {} => Ok(()),
+ _ => Err(Error::BadResponse),
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +
//! Runtime attestation key handling.
+use std::{
+ collections::VecDeque,
+ sync::{Arc, RwLock},
+};
+
+use anyhow::Result;
+use base64::prelude::*;
+use rand::{rngs::OsRng, Rng};
+use sgx_isa::Targetinfo;
+use thiserror::Error;
+use tiny_keccak::{Hasher, TupleHash};
+
+use crate::{
+ common::{
+ crypto::{
+ hash::Hash,
+ mrae::deoxysii::{self, Opener},
+ signature::{self, Signature, Signer},
+ x25519,
+ },
+ sgx::{self, EnclaveIdentity, Quote, QuotePolicy, VerifiedQuote},
+ time::insecure_posix_time,
+ },
+ consensus::registry::EndorsedCapabilityTEE,
+ TeeType, BUILD_INFO,
+};
+
+/// Context used for computing the RAK digest.
+const RAK_HASH_CONTEXT: &[u8] = b"oasis-core/node: TEE RAK binding";
+/// Context used for deriving the nonce used in quotes.
+const QUOTE_NONCE_CONTEXT: &[u8] = b"oasis-core/node: TEE quote nonce";
+
+/// A dummy RAK seed for use in non-SGX tests where integrity is not needed.
+const INSECURE_RAK_SEED: &str = "ekiden test key manager RAK seed";
+/// A dummy REK seed for use in non-SGX tests where confidentiality is not needed.
+const INSECURE_REK_SEED: &str = "ekiden test key manager REK seed";
+
+/// Identity-related error.
+#[derive(Error, Debug)]
+enum IdentityError {
+ #[error("RAK binding mismatch")]
+ BindingMismatch,
+ #[error("malformed report data")]
+ MalformedReportData,
+}
+
+/// Quote-related errors.
+#[derive(Error, Debug)]
+enum QuoteError {
+ #[error("target info not set")]
+ TargetInfoNotSet,
+ #[error("malformed target_info")]
+ MalformedTargetInfo,
+ #[error("MRENCLAVE mismatch")]
+ MrEnclaveMismatch,
+ #[error("MRSIGNER mismatch")]
+ MrSignerMismatch,
+ #[error("quote nonce mismatch")]
+ NonceMismatch,
+ #[error("quote policy not set")]
+ QuotePolicyNotSet,
+ #[error("node identity not set")]
+ NodeIdentityNotSet,
+ #[error("endorsed quote mismatch")]
+ EndorsedQuoteMismatch,
+}
+
+struct Inner {
+ rak: signature::PrivateKey,
+ rek: x25519::PrivateKey,
+ quote: Option<Arc<Quote>>,
+ quote_timestamp: Option<i64>,
+ quote_policy: Option<Arc<QuotePolicy>>,
+ known_quotes: VecDeque<Arc<Quote>>,
+ enclave_identity: Option<EnclaveIdentity>,
+ node_identity: Option<signature::PublicKey>,
+ endorsed_capability_tee: Option<EndorsedCapabilityTEE>,
+ target_info: Option<Targetinfo>,
+ nonce: Option<[u8; 32]>,
+}
+
+/// Runtime identity.
+///
+/// The identity can be used to sign remote attestations with runtime
+/// attestation key (RAK) or to decrypt ciphertexts sent to the enclave
+/// with runtime encryption key (REK). RAK avoids round trips to IAS/PCS
+/// for each verification as the verifier can instead verify the RAK signature
+/// and the signature on the provided quote which binds RAK to the enclave.
+/// REK allows enclaves to publish encrypted data on-chain to an enclave
+/// instance.
+pub struct Identity {
+ inner: RwLock<Inner>,
+}
+
+impl Default for Identity {
+ fn default() -> Self {
+ Self::new()
+ }
+}
+
+impl Identity {
+ /// Create an uninitialized runtime identity.
+ pub fn new() -> Self {
+ let (rak, rek) = match BUILD_INFO.tee_type {
+ TeeType::None => {
+ // Use insecure mock keys for insecure non-TEE builds.
+ assert!(!BUILD_INFO.is_secure);
+
+ (
+ signature::PrivateKey::from_test_seed(INSECURE_RAK_SEED.to_string()),
+ x25519::PrivateKey::from_test_seed(INSECURE_REK_SEED.to_string()),
+ )
+ }
+ _ => {
+ // Generate ephemeral RAK and REK.
+ (
+ signature::PrivateKey::generate(),
+ x25519::PrivateKey::generate(),
+ )
+ }
+ };
+
+ Self {
+ inner: RwLock::new(Inner {
+ rak,
+ rek,
+ quote: None,
+ quote_timestamp: None,
+ quote_policy: None,
+ known_quotes: Default::default(),
+ enclave_identity: EnclaveIdentity::current(),
+ node_identity: None,
+ endorsed_capability_tee: None,
+ target_info: None,
+ nonce: None,
+ }),
+ }
+ }
+
+ /// Generate report body = H(RAK_HASH_CONTEXT || RAK_pub).
+ fn report_body_for_rak(rak: &signature::PublicKey) -> Hash {
+ let mut message = [0; 64];
+ message[0..32].copy_from_slice(RAK_HASH_CONTEXT);
+ message[32..64].copy_from_slice(rak.as_ref());
+ Hash::digest_bytes(&message)
+ }
+
+ /// Generate a random 256-bit nonce, for anti-replay.
+ fn generate_nonce() -> [u8; 32] {
+ let mut nonce_bytes = [0u8; 32];
+ OsRng.fill(&mut nonce_bytes);
+
+ let mut h = TupleHash::v256(QUOTE_NONCE_CONTEXT);
+ h.update(&nonce_bytes);
+ h.finalize(&mut nonce_bytes);
+
+ nonce_bytes
+ }
+
+ /// Get the SGX target info.
+ fn get_sgx_target_info(&self) -> Option<Targetinfo> {
+ let inner = self.inner.read().unwrap();
+ inner.target_info.clone()
+ }
+
+ /// Initialize the SGX target info.
+ pub(crate) fn init_target_info(&self, target_info: Vec<u8>) -> Result<()> {
+ match BUILD_INFO.tee_type {
+ TeeType::Sgx => {
+ let mut inner = self.inner.write().unwrap();
+
+ // Set the Quoting Enclave target_info first, as unlike key generation
+ // it can fail.
+ let target_info = match Targetinfo::try_copy_from(&target_info) {
+ Some(target_info) => target_info,
+ None => return Err(QuoteError::MalformedTargetInfo.into()),
+ };
+ inner.target_info = Some(target_info);
+
+ Ok(())
+ }
+ TeeType::Tdx => {
+ // Target info configuration is not needed on TDX and MUST be empty.
+ if !target_info.is_empty() {
+ return Err(QuoteError::MalformedTargetInfo.into());
+ }
+
+ Ok(())
+ }
+ TeeType::None => Ok(()),
+ }
+ }
+
+ /// Initialize the attestation report.
+ pub(crate) fn init_report(
+ &self,
+ ) -> Result<(signature::PublicKey, x25519::PublicKey, Vec<u8>, String)> {
+ let rak_pub = self.public_rak();
+ let rek_pub = self.public_rek();
+
+ // Generate a new anti-replay nonce.
+ let nonce = Self::generate_nonce();
+ // Generate report body.
+ let report_body = Self::report_body_for_rak(&rak_pub);
+ let mut report_data = [0; 64];
+ report_data[0..32].copy_from_slice(report_body.as_ref());
+ report_data[32..64].copy_from_slice(nonce.as_ref());
+
+ let result = match BUILD_INFO.tee_type {
+ TeeType::Sgx => {
+ let target_info = self
+ .get_sgx_target_info()
+ .ok_or(QuoteError::TargetInfoNotSet)?;
+
+ // The derived nonce is only used in case IAS-based attestation is used
+ // as it is included in the outer AVR envelope. But given that the body
+ // also includes the nonce in our specific case, this is not relevant.
+ let quote_nonce = BASE64_STANDARD.encode(&nonce[..24]);
+
+ let report = sgx::report_for(&target_info, &report_data);
+ let report: &[u8] = report.as_ref();
+ let report = report.to_vec();
+
+ // This used to reset the quote, but that is now done in the external
+ // accessor combined with a freshness check.
+
+ (rak_pub, rek_pub, report, quote_nonce)
+ }
+ #[cfg(feature = "tdx")]
+ TeeType::Tdx => {
+ // In TDX we can immediately generate a quote. Do it and return it as a "report".
+ let quote = crate::common::tdx::report::get_quote(&report_data)?;
+
+ (rak_pub, rek_pub, quote, String::new())
+ }
+ _ => panic!("init_report called outside TEE environment"),
+ };
+
+ // Cache the nonce, the report was generated.
+ let mut inner = self.inner.write().unwrap();
+ inner.nonce = Some(nonce);
+
+ Ok(result)
+ }
+
+ /// Configure the remote attestation quote for RAK.
+ pub(crate) fn set_quote(
+ &self,
+ node_id: signature::PublicKey,
+ quote: Quote,
+ ) -> Result<VerifiedQuote> {
+ let rak_pub = self.public_rak();
+
+ let mut inner = self.inner.write().unwrap();
+
+ // If there is no anti-replay nonce set, we aren't in the process of attesting.
+ let expected_nonce = match &inner.nonce {
+ Some(nonce) => *nonce,
+ None => return Err(QuoteError::NonceMismatch.into()),
+ };
+
+ // Verify that the quote's nonce matches one that we generated,
+ // and remove it. If the validation fails for any reason, we
+ // should not accept a new quote with the same nonce as a quote
+ // that failed.
+ inner.nonce = None;
+
+ let policy = inner
+ .quote_policy
+ .as_ref()
+ .ok_or(QuoteError::QuotePolicyNotSet)?;
+ let verified_quote = quote.verify(policy)?;
+ let nonce = &verified_quote.report_data[32..];
+ if expected_nonce.as_ref() != nonce {
+ return Err(QuoteError::NonceMismatch.into());
+ }
+
+ // Verify that the quote's enclave identity matches our own.
+ let enclave_identity = inner
+ .enclave_identity
+ .as_ref()
+ .expect("Enclave identity must be configured");
+ if verified_quote.identity.mr_enclave != enclave_identity.mr_enclave {
+ return Err(QuoteError::MrEnclaveMismatch.into());
+ }
+ if verified_quote.identity.mr_signer != enclave_identity.mr_signer {
+ return Err(QuoteError::MrSignerMismatch.into());
+ }
+
+ // Verify that the quote has H(RAK) in report body.
+ Self::verify_binding(&verified_quote, &rak_pub)?;
+
+ // If there is an existing quote that is dated more recently than
+ // the one being set, silently ignore the update.
+ if inner.quote.is_some() {
+ let existing_timestamp = inner.quote_timestamp.unwrap();
+ if existing_timestamp > verified_quote.timestamp {
+ return Ok(verified_quote);
+ }
+ }
+
+ // Ensure host identity cannot change.
+ match inner.node_identity {
+ Some(existing_node_id) if node_id != existing_node_id => {
+ panic!("host node identity may never change");
+ }
+ Some(_) => {} // Host identity already set and is the same.
+ None => inner.node_identity = Some(node_id),
+ }
+
+ let quote = Arc::new(quote);
+ inner.quote = Some(quote.clone());
+ inner.quote_timestamp = Some(verified_quote.timestamp);
+
+ // Keep around last two valid quotes to allow for transition as node registration does not
+ // happen immediately after a quote has been verified by the runtime.
+ inner.known_quotes.push_back(quote);
+ if inner.known_quotes.len() > 2 {
+ inner.known_quotes.pop_front();
+ }
+
+ Ok(verified_quote)
+ }
+
+ /// Configure the runtime quote policy.
+ pub(crate) fn set_quote_policy(&self, policy: QuotePolicy) -> Result<()> {
+ let mut inner = self.inner.write().unwrap();
+ inner.quote_policy = Some(Arc::new(policy));
+
+ Ok(())
+ }
+
+ /// Configure the endorsed TEE capability.
+ pub(crate) fn set_endorsed_capability_tee(&self, ect: EndorsedCapabilityTEE) -> Result<()> {
+ // Make sure the endorsed quote is actually ours.
+ if !ect.capability_tee.matches(self) {
+ return Err(QuoteError::EndorsedQuoteMismatch.into());
+ }
+
+ let mut inner = self.inner.write().unwrap();
+ let policy = inner
+ .quote_policy
+ .as_ref()
+ .ok_or(QuoteError::QuotePolicyNotSet)?;
+ let node_id = inner.node_identity.ok_or(QuoteError::NodeIdentityNotSet)?;
+
+ // Verify the endorsed capability TEE to make sure it matches our state.
+ if ect.node_endorsement.public_key != node_id {
+ return Err(QuoteError::EndorsedQuoteMismatch.into());
+ }
+ ect.verify(policy)?;
+
+ inner.endorsed_capability_tee = Some(ect);
+
+ Ok(())
+ }
+
+ /// Endorsed TEE capability.
+ pub fn endorsed_capability_tee(&self) -> Option<EndorsedCapabilityTEE> {
+ let inner = self.inner.read().unwrap();
+ inner.endorsed_capability_tee.clone()
+ }
+
+ /// Host node identity public key.
+ pub fn node_identity(&self) -> Option<signature::PublicKey> {
+ let inner = self.inner.read().unwrap();
+ inner.node_identity
+ }
+
+ /// Public part of RAK.
+ ///
+ /// This method will return an insecure test key in the case where
+ /// the enclave is not running on SGX hardware.
+ pub fn public_rak(&self) -> signature::PublicKey {
+ let inner = self.inner.read().unwrap();
+ inner.rak.public_key()
+ }
+
+ /// Public part of REK.
+ ///
+ /// This method will return an insecure test key in the case where
+ /// the enclave is not running on SGX hardware.
+ pub fn public_rek(&self) -> x25519::PublicKey {
+ let inner = self.inner.read().unwrap();
+ inner.rek.public_key()
+ }
+
+ /// Quote for RAK.
+ ///
+ /// This method may return `None` in case quote has not yet been set from
+ /// the outside, or if the quote has expired.
+ pub fn quote(&self) -> Option<Arc<Quote>> {
+ let now = insecure_posix_time();
+
+ // Enforce quote expiration.
+ let mut inner = self.inner.write().unwrap();
+ if inner.quote.is_some() {
+ let quote = inner.quote.as_ref().unwrap();
+ let timestamp = inner.quote_timestamp.unwrap();
+ let quote_policy = inner.quote_policy.as_ref().unwrap();
+
+ if !quote.is_fresh(now, timestamp, quote_policy) {
+ // Reset the quote.
+ inner.quote = None;
+ inner.quote_timestamp = None;
+ inner.quote_policy = None;
+
+ return None;
+ }
+ }
+
+ inner.quote.clone()
+ }
+
+ /// Runtime quote policy.
+ ///
+ /// This method may return `None` in the case where the enclave is not
+ /// running on SGX hardware or if the quote policy has not yet been
+ /// fetched from the consensus layer.
+ pub fn quote_policy(&self) -> Option<Arc<QuotePolicy>> {
+ let inner = self.inner.read().unwrap();
+ inner.quote_policy.clone()
+ }
+
+ /// Verify a provided RAK binding.
+ pub fn verify_binding(quote: &VerifiedQuote, rak: &signature::PublicKey) -> Result<()> {
+ if quote.report_data.len() < 32 {
+ return Err(IdentityError::MalformedReportData.into());
+ }
+ if Self::report_body_for_rak(rak).as_ref() != "e.report_data[..32] {
+ return Err(IdentityError::BindingMismatch.into());
+ }
+
+ Ok(())
+ }
+
+ /// Checks whether the RAK matches another specified (RAK_pub, quote) pair.
+ pub fn rak_matches(&self, rak: &signature::PublicKey, quote: &Quote) -> bool {
+ // Check if public key matches.
+ if &self.public_rak() != rak {
+ return false;
+ }
+
+ let inner = self.inner.read().unwrap();
+ inner.known_quotes.iter().any(|q| &**q == quote)
+ }
+}
+
+impl Signer for Identity {
+ fn public(&self) -> signature::PublicKey {
+ let inner = self.inner.read().unwrap();
+ inner.rak.public_key()
+ }
+
+ fn sign(&self, context: &[u8], message: &[u8]) -> Result<Signature> {
+ let inner = self.inner.read().unwrap();
+ inner.rak.sign(context, message)
+ }
+}
+
+impl Opener for Identity {
+ fn box_open(
+ &self,
+ nonce: &[u8; deoxysii::NONCE_SIZE],
+ ciphertext: Vec<u8>,
+ additional_data: Vec<u8>,
+ peers_public_key: &x25519_dalek::PublicKey,
+ ) -> Result<Vec<u8>> {
+ let inner = self.inner.read().unwrap();
+ let private_key = &inner.rek.0;
+
+ deoxysii::box_open(
+ nonce,
+ ciphertext,
+ additional_data,
+ peers_public_key,
+ private_key,
+ )
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +
//! Runtime initialization.
+use std::sync::Arc;
+
+use anyhow::Result;
+use slog::{error, info};
+
+use crate::{
+ common::logger::{get_logger, init_logger},
+ config::Config,
+ dispatcher::{Dispatcher, Initializer},
+ future::new_tokio_runtime,
+ identity::Identity,
+ protocol::{Protocol, Stream},
+ TeeType, BUILD_INFO,
+};
+
+/// Starts the runtime.
+pub fn start_runtime(initializer: Box<dyn Initializer>, config: Config) {
+ // Initialize logging.
+ init_logger(log::Level::Info);
+ let logger = get_logger("runtime");
+ info!(logger, "Runtime is starting");
+
+ // Perform TDX-specific early initialization.
+ #[cfg(feature = "tdx")]
+ if BUILD_INFO.tee_type == TeeType::Tdx {
+ crate::common::tdx::init::init();
+ }
+
+ // Initialize runtime identity with runtime attestation key and runtime encryption key.
+ let identity = Arc::new(Identity::new());
+
+ // Initialize the async Tokio runtime.
+ let tokio_runtime = new_tokio_runtime();
+ let tokio_handle = tokio_runtime.handle();
+
+ // Initialize the dispatcher.
+ let dispatcher = Dispatcher::new(tokio_handle.clone(), initializer, identity.clone());
+
+ // Connect to the runtime host.
+ info!(logger, "Establishing connection with the worker host");
+
+ let stream = match connect() {
+ Ok(stream) => stream,
+ Err(err) => {
+ error!(logger, "Failed to connect with the worker host"; "err" => %err);
+ return;
+ }
+ };
+
+ // Initialize the protocol handler loop.
+ let protocol = Arc::new(Protocol::new(
+ tokio_handle.clone(),
+ stream,
+ identity,
+ dispatcher,
+ config,
+ ));
+
+ // Start handling protocol messages. This blocks the main thread forever
+ // (or until we get a shutdown request).
+ protocol.start();
+
+ info!(logger, "Protocol handler terminated, shutting down");
+}
+
+/// Establish a connection with the host.
+fn connect() -> Result<Stream> {
+ match BUILD_INFO.tee_type {
+ #[cfg(not(target_env = "sgx"))]
+ TeeType::Sgx | TeeType::None => {
+ let stream = std::os::unix::net::UnixStream::connect(
+ std::env::var("OASIS_WORKER_HOST").unwrap_or_default(),
+ )?;
+ Ok(Stream::Unix(stream))
+ }
+
+ #[cfg(target_env = "sgx")]
+ TeeType::Sgx => {
+ let stream = std::net::TcpStream::connect("worker-host")?;
+ Ok(Stream::Tcp(stream))
+ }
+
+ #[cfg(feature = "tdx")]
+ TeeType::Tdx => {
+ /// VSOCK port used for the Runtime Host Protocol.
+ const VSOCK_PORT_RHP: u32 = 1;
+
+ // Accept first connection.
+ let listener = vsock::VsockListener::bind(&vsock::VsockAddr::new(
+ libc::VMADDR_CID_ANY,
+ VSOCK_PORT_RHP,
+ ))?;
+ let stream = listener
+ .incoming()
+ .next()
+ .ok_or(anyhow::anyhow!("failed to accept connection"))??;
+ Ok(Stream::Vsock(stream))
+ }
+
+ #[allow(unreachable_patterns)]
+ _ => Err(anyhow::anyhow!("unsupported TEE type")),
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +
//! Oasis Core runtime SDK.
+//!
+//! # Examples
+//!
+//! To create a minimal runtime that doesn't expose any APIs to the
+//! outside world, you need to call the `start_runtime` function:
+//! ```rust,ignore
+//! oasis_core_runtime::start_runtime(Some(Box::new(reg)), config);
+//! ```
+//!
+//! This will start the required services needed to communicate with
+//! the worker host.
+#![feature(test)]
+#![feature(arbitrary_self_types)]
+#![feature(const_option)]
+
+use lazy_static::lazy_static;
+#[cfg(target_env = "sgx")]
+use sgx_isa::{AttributesFlags, Report};
+
+#[cfg_attr(test, macro_use)]
+extern crate base64_serde;
+
+#[macro_use]
+pub mod common;
+pub mod app;
+mod attestation;
+pub mod cache;
+pub mod config;
+pub mod consensus;
+pub mod dispatcher;
+pub mod enclave_rpc;
+pub mod future;
+pub mod host;
+pub mod identity;
+pub mod init;
+pub mod policy;
+pub mod protocol;
+pub mod storage;
+pub mod transaction;
+pub mod types;
+
+use common::{
+ sgx::{EnclaveIdentity, MrSigner},
+ version::{Version, PROTOCOL_VERSION},
+};
+
+// Validate features.
+#[cfg(all(target_env = "sgx", feature = "debug-mock-sgx"))]
+compile_error!("the debug-mock-sgx feature can only be enabled on non-sgx targets");
+
+#[cfg(all(target_env = "sgx", feature = "tdx"))]
+compile_error!("the tdx feature can only be enabled on non-sgx targets");
+
+#[cfg(all(feature = "tdx", feature = "debug-mock-sgx"))]
+compile_error!("the tdx feature can't be enabled together with debug-mock-sgx");
+
+lazy_static! {
+ pub static ref BUILD_INFO: BuildInfo = {
+ // Determine TEE type.
+ let tee_type = if cfg!(any(target_env = "sgx", feature = "debug-mock-sgx")) {
+ TeeType::Sgx
+ } else if cfg!(feature = "tdx") {
+ TeeType::Tdx
+ } else {
+ TeeType::None
+ };
+
+ // Determine build security.
+ #[allow(clippy::let_and_return)]
+ let is_secure = match tee_type {
+ TeeType::Sgx => {
+ // SGX build security depends on how it was built.
+ //
+ // Optimistically start out as "it could be secure", and any single insecure build time
+ // option will propagate failure.
+ let maybe_secure = true;
+
+ // Quote signature verification MUST be enabled.
+ let maybe_secure = maybe_secure && option_env!("OASIS_UNSAFE_SKIP_AVR_VERIFY").is_none();
+
+ // Disallow debug enclaves MUST be enabled.
+ let maybe_secure = maybe_secure && option_env!("OASIS_UNSAFE_ALLOW_DEBUG_ENCLAVES").is_none();
+
+ // Attestation `OutOfDate` and `ConfigurationNeeded` responses MUST count as attestation
+ // failure.
+ //
+ // Rationale: This is how remote attestation signifies that the host environment is
+ // insecure (eg: SMT is enabled when it should not be).
+ let maybe_secure = maybe_secure && option_env!("OASIS_UNSAFE_LAX_AVR_VERIFY").is_none();
+
+ // The enclave MUST NOT be a debug one.
+ #[cfg(target_env = "sgx")]
+ let maybe_secure = maybe_secure && !Report::for_self().attributes.flags.contains(AttributesFlags::DEBUG);
+
+ // The enclave MUST NOT be signed by a test key,
+ let enclave_identity = EnclaveIdentity::current().unwrap();
+ let fortanix_mrsigner = MrSigner::from("9affcfae47b848ec2caf1c49b4b283531e1cc425f93582b36806e52a43d78d1a");
+ let maybe_secure = maybe_secure && (enclave_identity.mr_signer != fortanix_mrsigner);
+
+ maybe_secure
+ }
+ TeeType::Tdx => {
+ // TDX build security depends on how it was built.
+ //
+ // Optimistically start out as "it could be secure", and any single insecure build time
+ // option will propagate failure.
+ let maybe_secure = true;
+
+ // Quote signature verification MUST be enabled.
+ let maybe_secure = maybe_secure && option_env!("OASIS_UNSAFE_SKIP_AVR_VERIFY").is_none();
+
+ // Disallow debug enclaves MUST be enabled.
+ let maybe_secure = maybe_secure && option_env!("OASIS_UNSAFE_ALLOW_DEBUG_ENCLAVES").is_none();
+
+ // Attestation `OutOfDate` and `ConfigurationNeeded` responses MUST count as attestation
+ // failure.
+ //
+ // Rationale: This is how remote attestation signifies that the host environment is
+ // insecure (eg: SMT is enabled when it should not be).
+ let maybe_secure = maybe_secure && option_env!("OASIS_UNSAFE_LAX_AVR_VERIFY").is_none();
+
+ // TODO: Debug TD attributes.
+
+ maybe_secure
+ }
+ TeeType::None => {
+ // Non-TEE builds are insecure by definition.
+ false
+ }
+ };
+
+ BuildInfo {
+ tee_type,
+ protocol_version: PROTOCOL_VERSION,
+ is_secure,
+ }
+ };
+}
+
+/// TEE type this build is for.
+#[derive(Debug, Default, PartialEq, Eq)]
+pub enum TeeType {
+ #[default]
+ None,
+ Sgx,
+ Tdx,
+}
+
+/// Runtime build information.
+#[derive(Debug)]
+pub struct BuildInfo {
+ /// TEE type this build is for.
+ pub tee_type: TeeType,
+ /// Supported runtime protocol version.
+ pub protocol_version: Version,
+ /// True iff the build can provide integrity and confidentiality.
+ pub is_secure: bool,
+}
+
+// Re-exports.
+pub use self::{
+ enclave_rpc::{demux::Demux as RpcDemux, dispatcher::Dispatcher as RpcDispatcher},
+ init::start_runtime,
+ protocol::Protocol,
+ transaction::dispatcher::Dispatcher as TxnDispatcher,
+};
+
+// Re-export the cbor crate.
+pub use cbor;
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +
//! Consensus SGX and quote policy handling.
+
+use std::sync::Arc;
+
+use anyhow::{bail, Result};
+use slog::{debug, Logger};
+use thiserror::Error;
+
+use crate::{
+ common::{logger::get_logger, namespace::Namespace, sgx::QuotePolicy, version::Version},
+ consensus::{
+ keymanager::SignedPolicySGX,
+ registry::{SGXConstraints, TEEHardware},
+ state::{
+ beacon::ImmutableState as BeaconState,
+ keymanager::{ImmutableState as KeyManagerState, Status},
+ registry::ImmutableState as RegistryState,
+ },
+ verifier::Verifier,
+ },
+ future::block_on,
+};
+
+/// Policy verifier error.
+#[derive(Error, Debug)]
+pub enum PolicyVerifierError {
+ #[error("missing runtime descriptor")]
+ MissingRuntimeDescriptor,
+ #[error("no corresponding runtime deployment")]
+ NoDeployment,
+ #[error("bad TEE constraints")]
+ BadTEEConstraints,
+ #[error("policy mismatch")]
+ PolicyMismatch,
+ #[error("policy hasn't been published")]
+ PolicyNotPublished,
+ #[error("status mismatch")]
+ StatusMismatch,
+ #[error("status hasn't been published")]
+ StatusNotPublished,
+ #[error("configured runtime hardware mismatch")]
+ HardwareMismatch,
+ #[error("runtime doesn't use key manager")]
+ NoKeyManager,
+}
+
+/// Consensus policy verifier.
+pub struct PolicyVerifier {
+ consensus_verifier: Arc<dyn Verifier>,
+ logger: Logger,
+}
+
+impl PolicyVerifier {
+ /// Create a new consensus policy verifier.
+ pub fn new(consensus_verifier: Arc<dyn Verifier>) -> Self {
+ let logger = get_logger("runtime/policy_verifier");
+ Self {
+ consensus_verifier,
+ logger,
+ }
+ }
+
+ /// Fetch runtime's quote policy from the latest verified consensus layer state.
+ ///
+ /// If the runtime version is not provided, the policy for the active deployment is returned.
+ pub fn quote_policy(
+ &self,
+ runtime_id: &Namespace,
+ version: Option<Version>,
+ ) -> Result<QuotePolicy> {
+ // Fetch quote policy from the consensus layer using the given or the active version.
+ // TODO: Make this async.
+ let consensus_state = block_on(self.consensus_verifier.latest_state())?;
+ let registry_state = RegistryState::new(&consensus_state);
+ let runtime = registry_state
+ .runtime(runtime_id)?
+ .ok_or(PolicyVerifierError::MissingRuntimeDescriptor)?;
+
+ let ad = match version {
+ Some(version) => runtime
+ .deployment_for_version(version)
+ .ok_or(PolicyVerifierError::NoDeployment)?,
+ None => {
+ let beacon_state = BeaconState::new(&consensus_state);
+ let epoch = beacon_state.epoch()?;
+
+ runtime
+ .active_deployment(epoch)
+ .ok_or(PolicyVerifierError::NoDeployment)?
+ }
+ };
+
+ let policy = match runtime.tee_hardware {
+ TEEHardware::TEEHardwareIntelSGX => {
+ let sc: SGXConstraints = ad
+ .try_decode_tee()
+ .map_err(|_| PolicyVerifierError::BadTEEConstraints)?;
+ sc.policy()
+ }
+ _ => bail!(PolicyVerifierError::HardwareMismatch),
+ };
+
+ Ok(policy)
+ }
+
+ /// Verify that runtime's quote policy has been published in the consensus layer.
+ pub fn verify_quote_policy(
+ &self,
+ policy: QuotePolicy,
+ runtime_id: &Namespace,
+ version: Option<Version>,
+ ) -> Result<QuotePolicy> {
+ let published_policy = self.quote_policy(runtime_id, version)?;
+
+ if policy != published_policy {
+ debug!(
+ self.logger,
+ "quote policy mismatch";
+ "untrusted" => ?policy,
+ "published" => ?published_policy,
+ );
+ return Err(PolicyVerifierError::PolicyMismatch.into());
+ }
+
+ Ok(published_policy)
+ }
+
+ /// Fetch key manager's status from the latest verified consensus layer state.
+ pub fn key_manager_status(&self, key_manager: Namespace) -> Result<Status> {
+ // TODO: Make this async.
+ let consensus_state = block_on(self.consensus_verifier.latest_state())?;
+ let km_state = KeyManagerState::new(&consensus_state);
+ km_state
+ .status(key_manager)?
+ .ok_or_else(|| PolicyVerifierError::StatusNotPublished.into())
+ }
+
+ /// Verify that key manager's status has been published in the consensus layer.
+ pub fn verify_key_manager_status(
+ &self,
+ status: Status,
+ key_manager: Namespace,
+ ) -> Result<Status> {
+ let published_status = self.key_manager_status(key_manager)?;
+
+ if status != published_status {
+ debug!(
+ self.logger,
+ "key manager status mismatch";
+ "untrusted" => ?status,
+ "published" => ?published_status,
+ );
+ return Err(PolicyVerifierError::StatusMismatch.into());
+ }
+
+ Ok(published_status)
+ }
+
+ /// Fetch key manager's policy from the latest verified consensus layer state.
+ pub fn key_manager_policy(&self, key_manager: Namespace) -> Result<SignedPolicySGX> {
+ self.key_manager_status(key_manager)?
+ .policy
+ .ok_or_else(|| PolicyVerifierError::PolicyNotPublished.into())
+ }
+
+ /// Verify that key manager's policy has been published in the consensus layer.
+ pub fn verify_key_manager_policy(
+ &self,
+ policy: SignedPolicySGX,
+ key_manager: Namespace,
+ ) -> Result<SignedPolicySGX> {
+ let published_policy = self.key_manager_policy(key_manager)?;
+
+ if policy != published_policy {
+ debug!(
+ self.logger,
+ "key manager policy mismatch";
+ "untrusted" => ?policy,
+ "published" => ?published_policy,
+ );
+ return Err(PolicyVerifierError::PolicyMismatch.into());
+ }
+
+ Ok(published_policy)
+ }
+
+ /// Fetch runtime's key manager.
+ pub fn key_manager(&self, runtime_id: &Namespace) -> Result<Namespace> {
+ // TODO: Make this async.
+ let consensus_state = block_on(self.consensus_verifier.latest_state())?;
+ let registry_state = RegistryState::new(&consensus_state);
+ let runtime = registry_state
+ .runtime(runtime_id)?
+ .ok_or(PolicyVerifierError::MissingRuntimeDescriptor)?;
+ let key_manager = runtime
+ .key_manager
+ .ok_or(PolicyVerifierError::NoKeyManager)?;
+
+ Ok(key_manager)
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +
//! Runtime side of the worker-host protocol.
+use std::{
+ collections::{BTreeMap, HashMap},
+ io::{BufReader, BufWriter, Read, Write},
+ sync::{
+ atomic::{AtomicUsize, Ordering},
+ Arc, Mutex,
+ },
+};
+
+use byteorder::{BigEndian, ReadBytesExt, WriteBytesExt};
+use crossbeam::channel;
+use slog::{debug, error, info, warn, Logger};
+use thiserror::Error;
+use tokio::sync::oneshot;
+
+use crate::{
+ common::{logger::get_logger, namespace::Namespace, version::Version},
+ config::Config,
+ consensus::{tendermint, verifier::Verifier},
+ dispatcher::Dispatcher,
+ future::block_on,
+ identity::Identity,
+ storage::KeyValue,
+ types::{Body, Error, Message, MessageType, RuntimeInfoRequest, RuntimeInfoResponse},
+ TeeType, BUILD_INFO,
+};
+
+/// Stream used to communicate with the host.
+pub enum Stream {
+ #[cfg(not(target_env = "sgx"))]
+ Unix(std::os::unix::net::UnixStream),
+ Tcp(std::net::TcpStream),
+ #[cfg(feature = "tdx")]
+ Vsock(vsock::VsockStream),
+}
+
+impl Read for &Stream {
+ fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
+ #[allow(clippy::borrow_deref_ref)]
+ match self {
+ #[cfg(not(target_env = "sgx"))]
+ Stream::Unix(stream) => (&*stream).read(buf),
+ Stream::Tcp(stream) => (&*stream).read(buf),
+ #[cfg(feature = "tdx")]
+ Stream::Vsock(stream) => (&*stream).read(buf),
+ }
+ }
+}
+
+impl Write for &Stream {
+ fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
+ #[allow(clippy::borrow_deref_ref)]
+ match self {
+ #[cfg(not(target_env = "sgx"))]
+ Stream::Unix(stream) => (&*stream).write(buf),
+ Stream::Tcp(stream) => (&*stream).write(buf),
+ #[cfg(feature = "tdx")]
+ Stream::Vsock(stream) => (&*stream).write(buf),
+ }
+ }
+
+ fn flush(&mut self) -> std::io::Result<()> {
+ #[allow(clippy::borrow_deref_ref)]
+ match self {
+ #[cfg(not(target_env = "sgx"))]
+ Stream::Unix(stream) => (&*stream).flush(),
+ Stream::Tcp(stream) => (&*stream).flush(),
+ #[cfg(feature = "tdx")]
+ Stream::Vsock(stream) => (&*stream).flush(),
+ }
+ }
+}
+
+/// Maximum message size.
+const MAX_MESSAGE_SIZE: usize = 16 * 1024 * 1024; // 16MiB
+
+#[derive(Error, Debug)]
+pub enum ProtocolError {
+ #[error("message too large")]
+ MessageTooLarge,
+ #[error("method not supported")]
+ MethodNotSupported,
+ #[error("invalid response")]
+ InvalidResponse,
+ #[error("attestation required")]
+ #[allow(unused)]
+ AttestationRequired,
+ #[error("host environment information not configured")]
+ HostInfoNotConfigured,
+ #[error("incompatible consensus backend")]
+ IncompatibleConsensusBackend,
+ #[error("invalid runtime id (expected: {0} got: {1})")]
+ InvalidRuntimeId(Namespace, Namespace),
+ #[error("already initialized")]
+ AlreadyInitialized,
+ #[error("channel closed")]
+ ChannelClosed,
+}
+
+impl From<ProtocolError> for Error {
+ fn from(err: ProtocolError) -> Self {
+ Self {
+ module: "protocol".to_string(),
+ code: 1,
+ message: err.to_string(),
+ }
+ }
+}
+
+/// Information about the host environment.
+#[derive(Debug, Clone)]
+pub struct HostInfo {
+ /// Assigned runtime identifier of the loaded runtime.
+ pub runtime_id: Namespace,
+ /// Name of the consensus backend that is in use for the consensus layer.
+ pub consensus_backend: String,
+ /// Consensus protocol version that is in use for the consensus layer.
+ pub consensus_protocol_version: Version,
+ /// Consensus layer chain domain separation context.
+ pub consensus_chain_context: String,
+ /// Node-local runtime configuration.
+ ///
+ /// This configuration must not be used in any context which requires determinism across
+ /// replicated runtime instances.
+ pub local_config: BTreeMap<String, cbor::Value>,
+}
+
+/// Runtime part of the runtime host protocol.
+pub struct Protocol {
+ /// Logger.
+ logger: Logger,
+ /// Runtime identity.
+ #[cfg_attr(
+ not(any(target_env = "sgx", feature = "debug-mock-sgx")),
+ allow(unused)
+ )]
+ identity: Arc<Identity>,
+ /// Incoming request dispatcher.
+ dispatcher: Arc<Dispatcher>,
+ /// Channel for sending outgoing messages.
+ outgoing_tx: channel::Sender<Message>,
+ /// Channel for receiving outgoing messages.
+ outgoing_rx: channel::Receiver<Message>,
+ /// Stream to the runtime host.
+ stream: Stream,
+ /// Outgoing request identifier generator.
+ last_request_id: AtomicUsize,
+ /// Pending outgoing requests.
+ pending_out_requests: Mutex<HashMap<u64, oneshot::Sender<Body>>>,
+ /// Runtime configuration.
+ config: Config,
+ /// Host environment information.
+ host_info: Mutex<Option<HostInfo>>,
+ /// Tokio runtime handle.
+ tokio_runtime: tokio::runtime::Handle,
+}
+
+impl Protocol {
+ /// Create a new protocol handler instance.
+ pub(crate) fn new(
+ tokio_runtime: tokio::runtime::Handle,
+ stream: Stream,
+ identity: Arc<Identity>,
+ dispatcher: Arc<Dispatcher>,
+ config: Config,
+ ) -> Self {
+ let logger = get_logger("runtime/protocol");
+
+ let (outgoing_tx, outgoing_rx) = channel::unbounded();
+
+ Self {
+ logger,
+ identity,
+ dispatcher,
+ outgoing_tx,
+ outgoing_rx,
+ stream,
+ last_request_id: AtomicUsize::new(0),
+ pending_out_requests: Mutex::new(HashMap::new()),
+ config,
+ host_info: Mutex::new(None),
+ tokio_runtime,
+ }
+ }
+
+ /// The supplied runtime configuration.
+ pub fn get_config(&self) -> &Config {
+ &self.config
+ }
+
+ /// The runtime identity.
+ pub fn get_identity(&self) -> Option<&Arc<Identity>> {
+ self.identity.quote()?;
+ Some(&self.identity)
+ }
+
+ /// The runtime identifier for this instance.
+ ///
+ /// # Panics
+ ///
+ /// Panics, if the host environment information is not set.
+ pub fn get_runtime_id(&self) -> Namespace {
+ self.host_info
+ .lock()
+ .unwrap()
+ .as_ref()
+ .expect("host environment information should be set")
+ .runtime_id
+ }
+
+ /// The host environment information for this instance.
+ ///
+ /// # Panics
+ ///
+ /// Panics, if the host environment information is not set.
+ pub fn get_host_info(&self) -> HostInfo {
+ self.host_info
+ .lock()
+ .unwrap()
+ .as_ref()
+ .expect("host environment information should be set")
+ .clone()
+ }
+
+ /// Start the protocol handler loop.
+ pub(crate) fn start(self: &Arc<Protocol>) {
+ // Spawn write end in a separate thread.
+ let protocol = self.clone();
+ std::thread::spawn(move || protocol.io_write());
+
+ // Run read end in the current thread.
+ self.io_read();
+ }
+
+ fn io_read(self: &Arc<Protocol>) {
+ info!(self.logger, "Starting protocol reader thread");
+ let mut reader = BufReader::new(&self.stream);
+
+ loop {
+ if let Err(error) = self.handle_message(&mut reader) {
+ error!(self.logger, "Failed to handle message"; "err" => %error);
+ break;
+ }
+ }
+
+ info!(self.logger, "Protocol reader thread is terminating");
+ }
+
+ fn io_write(self: &Arc<Protocol>) {
+ info!(self.logger, "Starting protocol writer thread");
+
+ while let Ok(message) = self.outgoing_rx.recv() {
+ if let Err(error) = self.write_message(message) {
+ warn!(self.logger, "Failed to write message"; "err" => %error);
+ }
+ }
+
+ info!(self.logger, "Protocol writer thread is terminating");
+ }
+
+ /// Make a new request to the runtime host and wait for the response.
+ ///
+ /// This is a blocking variant of `call_host_async`.
+ ///
+ /// # Panics
+ ///
+ /// This function panics if called within an asynchronous execution context.
+ pub fn call_host(&self, body: Body) -> Result<Body, Error> {
+ block_on(self.call_host_async(body))
+ }
+
+ /// Make a new request to the runtime host and wait for the response.
+ pub async fn call_host_async(&self, body: Body) -> Result<Body, Error> {
+ let id = self.last_request_id.fetch_add(1, Ordering::SeqCst) as u64;
+ let message = Message {
+ id,
+ body,
+ message_type: MessageType::Request,
+ };
+
+ // Create a response channel and register an outstanding pending request.
+ let (tx, rx) = oneshot::channel();
+ {
+ let mut pending_requests = self.pending_out_requests.lock().unwrap();
+ pending_requests.insert(id, tx);
+ }
+
+ // Write message to stream and wait for the response.
+ self.send_message(message).map_err(Error::from)?;
+
+ let result = rx
+ .await
+ .map_err(|_| Error::from(ProtocolError::ChannelClosed))?;
+ match result {
+ Body::Error(err) => Err(err),
+ body => Ok(body),
+ }
+ }
+
+ /// Send an async response to a previous request back to the host.
+ pub fn send_response(&self, id: u64, body: Body) -> anyhow::Result<()> {
+ self.send_message(Message {
+ id,
+ body,
+ message_type: MessageType::Response,
+ })
+ }
+
+ fn send_message(&self, message: Message) -> anyhow::Result<()> {
+ self.outgoing_tx.send(message).map_err(|err| err.into())
+ }
+
+ fn decode_message<R: Read>(&self, mut reader: R) -> anyhow::Result<Message> {
+ let length = reader.read_u32::<BigEndian>()? as usize;
+ if length > MAX_MESSAGE_SIZE {
+ return Err(ProtocolError::MessageTooLarge.into());
+ }
+
+ // TODO: Avoid allocations.
+ let mut buffer = vec![0; length];
+ reader.read_exact(&mut buffer)?;
+
+ let message = cbor::from_slice(&buffer)
+ .map_err(|error| {
+ warn!(self.logger, "Failed to decode message"; "err" => %error);
+ debug!(self.logger, "Malformed message"; "bytes" => ?buffer);
+ error
+ })
+ .unwrap_or_default();
+
+ Ok(message)
+ }
+
+ fn write_message(&self, message: Message) -> anyhow::Result<()> {
+ let buffer = cbor::to_vec(message);
+ if buffer.len() > MAX_MESSAGE_SIZE {
+ return Err(ProtocolError::MessageTooLarge.into());
+ }
+
+ let mut writer = BufWriter::new(&self.stream);
+ writer.write_u32::<BigEndian>(buffer.len() as u32)?;
+ writer.write_all(&buffer)?;
+
+ Ok(())
+ }
+
+ fn handle_message<R: Read>(self: &Arc<Protocol>, reader: R) -> anyhow::Result<()> {
+ let message = self.decode_message(reader)?;
+
+ match message.message_type {
+ MessageType::Request => {
+ // Incoming request.
+ let id = message.id;
+
+ let body = match self.handle_request(id, message.body) {
+ Ok(Some(result)) => result,
+ Ok(None) => {
+ // A message will be sent later by another thread so there
+ // is no need to do anything more.
+ return Ok(());
+ }
+ Err(error) => Body::Error(Error::new("rhp/dispatcher", 1, &format!("{error}"))),
+ };
+
+ // Send response back.
+ self.send_message(Message {
+ id,
+ message_type: MessageType::Response,
+ body,
+ })?;
+ }
+ MessageType::Response => {
+ // Response to our request.
+ let response_sender = {
+ let mut pending_requests = self.pending_out_requests.lock().unwrap();
+ pending_requests.remove(&message.id)
+ };
+
+ match response_sender {
+ Some(response_sender) => {
+ if response_sender.send(message.body).is_err() {
+ warn!(self.logger, "Unable to deliver response to local handler");
+ }
+ }
+ None => {
+ warn!(self.logger, "Received response message for unknown request"; "msg_id" => message.id);
+ }
+ }
+ }
+ _ => warn!(self.logger, "Received a malformed message"),
+ }
+
+ Ok(())
+ }
+
+ fn handle_request(
+ self: &Arc<Protocol>,
+ id: u64,
+ request: Body,
+ ) -> anyhow::Result<Option<Body>> {
+ match request {
+ // Connection setup and various requests.
+ Body::RuntimeInfoRequest(request) => Ok(Some(Body::RuntimeInfoResponse(
+ self.initialize_guest(request)?,
+ ))),
+ Body::RuntimePingRequest {} => Ok(Some(Body::Empty {})),
+ Body::RuntimeShutdownRequest {} => {
+ info!(self.logger, "Received worker shutdown request");
+ Err(ProtocolError::MethodNotSupported.into())
+ }
+ Body::RuntimeAbortRequest {} => {
+ info!(self.logger, "Received worker abort request");
+ Err(ProtocolError::MethodNotSupported.into())
+ }
+
+ // Attestation-related requests.
+ Body::RuntimeCapabilityTEERakInitRequest { .. }
+ | Body::RuntimeCapabilityTEERakReportRequest {}
+ | Body::RuntimeCapabilityTEERakAvrRequest { .. }
+ | Body::RuntimeCapabilityTEERakQuoteRequest { .. }
+ | Body::RuntimeCapabilityTEEUpdateEndorsementRequest { .. } => {
+ self.dispatcher.queue_request(id, request)?;
+ Ok(None)
+ }
+
+ // Other requests.
+ Body::RuntimeRPCCallRequest { .. }
+ | Body::RuntimeLocalRPCCallRequest { .. }
+ | Body::RuntimeCheckTxBatchRequest { .. }
+ | Body::RuntimeExecuteTxBatchRequest { .. }
+ | Body::RuntimeNotifyRequest { .. }
+ | Body::RuntimeKeyManagerStatusUpdateRequest { .. }
+ | Body::RuntimeKeyManagerQuotePolicyUpdateRequest { .. }
+ | Body::RuntimeQueryRequest { .. }
+ | Body::RuntimeConsensusSyncRequest { .. } => {
+ self.ensure_initialized()?;
+ self.dispatcher.queue_request(id, request)?;
+ Ok(None)
+ }
+
+ _ => {
+ warn!(self.logger, "Received unsupported request"; "req" => format!("{request:?}"));
+ Err(ProtocolError::MethodNotSupported.into())
+ }
+ }
+ }
+
+ fn initialize_guest(
+ self: &Arc<Protocol>,
+ host_info: RuntimeInfoRequest,
+ ) -> anyhow::Result<RuntimeInfoResponse> {
+ info!(self.logger, "Received host environment information";
+ "runtime_id" => ?host_info.runtime_id,
+ "consensus_backend" => &host_info.consensus_backend,
+ "consensus_protocol_version" => ?host_info.consensus_protocol_version,
+ "consensus_chain_context" => &host_info.consensus_chain_context,
+ "local_config" => ?host_info.local_config,
+ );
+
+ if tendermint::BACKEND_NAME != host_info.consensus_backend {
+ return Err(ProtocolError::IncompatibleConsensusBackend.into());
+ }
+ let mut local_host_info = self.host_info.lock().unwrap();
+ if local_host_info.is_some() {
+ return Err(ProtocolError::AlreadyInitialized.into());
+ }
+
+ // Create and start the consensus verifier.
+ let consensus_verifier: Box<dyn Verifier> =
+ if let Some(ref trust_root) = self.config.trust_root {
+ // Make sure that the host environment matches the trust root.
+ if host_info.runtime_id != trust_root.runtime_id {
+ return Err(ProtocolError::InvalidRuntimeId(
+ trust_root.runtime_id,
+ host_info.runtime_id,
+ )
+ .into());
+ }
+
+ // Create the Tendermint consensus layer verifier and spawn it in a separate thread.
+ let verifier = tendermint::verifier::Verifier::new(
+ self.clone(),
+ self.tokio_runtime.clone(),
+ trust_root.clone(),
+ host_info.runtime_id,
+ host_info.consensus_chain_context.clone(),
+ );
+ let handle = verifier.handle();
+ verifier.start();
+
+ Box::new(handle)
+ } else {
+ // Create a no-op verifier.
+ let verifier = tendermint::verifier::NopVerifier::new(self.clone());
+ verifier.start();
+
+ Box::new(verifier)
+ };
+
+ // Configure the host environment info.
+ *local_host_info = Some(HostInfo {
+ runtime_id: host_info.runtime_id,
+ consensus_backend: host_info.consensus_backend,
+ consensus_protocol_version: host_info.consensus_protocol_version,
+ consensus_chain_context: host_info.consensus_chain_context,
+ local_config: host_info.local_config,
+ });
+
+ // Start the dispatcher.
+ self.dispatcher.start(self.clone(), consensus_verifier);
+
+ Ok(RuntimeInfoResponse {
+ protocol_version: BUILD_INFO.protocol_version,
+ runtime_version: self.config.version,
+ features: self.config.features.clone(),
+ })
+ }
+
+ /// Ensure that the runtime is ready to process requests and fail otherwise.
+ pub fn ensure_initialized(&self) -> anyhow::Result<()> {
+ self.host_info
+ .lock()
+ .unwrap()
+ .as_ref()
+ .ok_or(ProtocolError::HostInfoNotConfigured)?;
+
+ match BUILD_INFO.tee_type {
+ TeeType::Sgx | TeeType::Tdx => {
+ self.identity
+ .quote()
+ .ok_or(ProtocolError::AttestationRequired)?;
+ }
+ TeeType::None => {}
+ }
+
+ Ok(())
+ }
+}
+
+/// Untrusted key/value store which stores arbitrary binary key/value pairs
+/// on the worker host.
+///
+/// Care MUST be taken to not trust this interface at all. The worker host
+/// is capable of doing whatever it wants including but not limited to,
+/// hiding data, tampering with keys/values, ignoring writes, replaying
+/// past values, etc.
+pub struct ProtocolUntrustedLocalStorage {
+ protocol: Arc<Protocol>,
+}
+
+impl ProtocolUntrustedLocalStorage {
+ pub fn new(protocol: Arc<Protocol>) -> Self {
+ Self { protocol }
+ }
+}
+
+impl KeyValue for ProtocolUntrustedLocalStorage {
+ fn get(&self, key: Vec<u8>) -> Result<Vec<u8>, Error> {
+ match self
+ .protocol
+ .call_host(Body::HostLocalStorageGetRequest { key })?
+ {
+ Body::HostLocalStorageGetResponse { value } => Ok(value),
+ _ => Err(ProtocolError::InvalidResponse.into()),
+ }
+ }
+
+ fn insert(&self, key: Vec<u8>, value: Vec<u8>) -> Result<(), Error> {
+ match self
+ .protocol
+ .call_host(Body::HostLocalStorageSetRequest { key, value })?
+ {
+ Body::HostLocalStorageSetResponse {} => Ok(()),
+ _ => Err(ProtocolError::InvalidResponse.into()),
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +
use std::{cell::RefCell, pin::Pin, ptr::NonNull, rc::Rc};
+
+use anyhow::{anyhow, Result};
+use intrusive_collections::{intrusive_adapter, LinkedList, LinkedListLink};
+use thiserror::Error;
+
+#[cfg(test)]
+use crate::storage::mkvs::cache::CacheStats;
+use crate::storage::mkvs::{
+ cache::{Cache, CacheExtra, CacheItem, ReadSyncFetcher},
+ sync::{merge_verified_subtree, ProofVerifier, ReadSync},
+ tree::{
+ Depth, InternalNode, Key, LeafNode, NodeBox, NodeKind, NodePointer, NodePtrRef, NodeRef,
+ Root, RootType, Value,
+ },
+};
+
+#[derive(Error, Debug)]
+#[error("mkvs: tried to remove locked node")]
+struct RemoveLockedError;
+
+#[derive(Clone, Default)]
+pub struct CacheItemBox<Item: CacheItem + Default> {
+ item: Rc<RefCell<Item>>,
+ link: LinkedListLink,
+}
+
+intrusive_adapter!(
+ CacheItemAdapter<Item> = Pin<Box<CacheItemBox<Item>>>:
+ CacheItemBox<Item> { link: LinkedListLink }
+ where Item: CacheItem + Default
+);
+
+struct LRUList<V>
+where
+ V: CacheItem + Default,
+{
+ pub list: LinkedList<CacheItemAdapter<V>>,
+ pub size: usize,
+ pub capacity: usize,
+ pub mark: CacheExtra<V>,
+}
+
+impl<V> LRUList<V>
+where
+ V: CacheItem + Default,
+{
+ pub fn new(capacity: usize) -> LRUList<V> {
+ LRUList {
+ list: LinkedList::new(CacheItemAdapter::new()),
+ size: 0,
+ capacity,
+ mark: None,
+ }
+ }
+
+ fn mark(&mut self) {
+ self.mark = self.list.front().get().map(|front| {
+ front
+ .item
+ .borrow()
+ .get_cache_extra()
+ .expect("item was just retrieved from list, cache extra must exist")
+ });
+ }
+
+ fn add(&mut self, val: Rc<RefCell<V>>) {
+ let mut val_ref = val.borrow_mut();
+ if val_ref.get_cache_extra().is_none() {
+ self.size += val_ref.get_cached_size();
+ let mut item_box = Box::pin(CacheItemBox {
+ item: val.clone(),
+ link: LinkedListLink::new(),
+ });
+ val_ref.set_cache_extra(NonNull::new(&mut *item_box));
+ if let Some(non_null_pos) = &self.mark {
+ let mut pos_cursor =
+ unsafe { self.list.cursor_mut_from_ptr(non_null_pos.as_ptr()) };
+ pos_cursor.insert_after(item_box);
+ } else {
+ self.list.push_front(item_box);
+ }
+ } else {
+ self.use_val(val.clone());
+ }
+ }
+
+ fn use_val(&mut self, val: Rc<RefCell<V>>) -> bool {
+ let val_ref = val.borrow();
+ match val_ref.get_cache_extra() {
+ None => false,
+ Some(non_null) => {
+ let mut item_cursor = unsafe { self.list.cursor_mut_from_ptr(non_null.as_ptr()) };
+ let removed_box = item_cursor.remove().unwrap();
+ self.list.push_front(removed_box);
+ true
+ }
+ }
+ }
+
+ fn remove(&mut self, val: Rc<RefCell<V>>) -> bool {
+ let extra = val.borrow().get_cache_extra();
+ match extra {
+ None => false,
+ Some(non_null) => {
+ if let Some(non_null_mark) = self.mark {
+ if non_null.as_ptr() == non_null_mark.as_ptr() {
+ self.mark = None;
+ }
+ }
+
+ let mut item_cursor = unsafe { self.list.cursor_mut_from_ptr(non_null.as_ptr()) };
+ match item_cursor.remove() {
+ None => false,
+ Some(item_box) => {
+ let mut val = item_box.item.borrow_mut();
+ val.set_cache_extra(None);
+ self.size -= val.get_cached_size();
+ true
+ }
+ }
+ }
+ }
+ }
+
+ fn evict_for_val(
+ &mut self,
+ val: Rc<RefCell<V>>,
+ locked_val: Option<&Rc<RefCell<V>>>,
+ ) -> Result<Vec<Rc<RefCell<V>>>, RemoveLockedError> {
+ let mut evicted: Vec<Rc<RefCell<V>>> = Vec::new();
+ if self.capacity > 0 {
+ let target_size = val.borrow().get_cached_size();
+ while !self.list.is_empty() && self.size + target_size > self.capacity {
+ let back = self.list.back().get().unwrap().item.clone();
+ if let Some(locked_val) = locked_val {
+ if back.as_ptr() == locked_val.as_ptr() {
+ return Err(RemoveLockedError);
+ }
+ }
+ if self.remove(back.clone()) {
+ evicted.push(back);
+ }
+ }
+ }
+ Ok(evicted)
+ }
+}
+
+/// Cache implementation with a simple LRU eviction strategy.
+pub struct LRUCache {
+ read_syncer: Box<dyn ReadSync>,
+
+ pending_root: NodePtrRef,
+ sync_root: Root,
+
+ lru_leaf: LRUList<NodePointer>,
+ lru_internal: LRUList<NodePointer>,
+}
+
+impl LRUCache {
+ /// Construct a new cache instance.
+ ///
+ /// * `node_capacity` is the maximum number of internal nodes held by the
+ /// cache before eviction.
+ /// * `value_capacity` is the total size, in bytes, of values held
+ /// by the cache before eviction.
+ /// * `read_syncer` is the read syncer used as backing for the cache.
+ pub fn new(
+ node_capacity: usize,
+ value_capacity: usize,
+ read_syncer: Box<dyn ReadSync>,
+ root_type: RootType,
+ ) -> Box<LRUCache> {
+ Box::new(LRUCache {
+ read_syncer,
+
+ pending_root: Rc::new(RefCell::new(NodePointer {
+ node: None,
+ ..Default::default()
+ })),
+ sync_root: Root {
+ root_type,
+ ..Default::default()
+ },
+
+ lru_leaf: LRUList::new(value_capacity),
+ lru_internal: LRUList::new(node_capacity),
+ })
+ }
+
+ fn new_internal_node_ptr(&mut self, node: Option<NodeRef>) -> NodePtrRef {
+ Rc::new(RefCell::new(NodePointer {
+ node,
+ ..Default::default()
+ }))
+ }
+
+ fn new_leaf_node_ptr(&mut self, node: Option<NodeRef>) -> NodePtrRef {
+ Rc::new(RefCell::new(NodePointer {
+ node,
+ ..Default::default()
+ }))
+ }
+
+ fn try_commit_node(
+ &mut self,
+ ptr: NodePtrRef,
+ locked_ptr: Option<&NodePtrRef>,
+ ) -> Result<(), RemoveLockedError> {
+ assert!(ptr.borrow().clean, "mkvs: commit_node called on dirty node");
+ if ptr.borrow().node.is_none() {
+ return Ok(());
+ }
+ if self.use_node(ptr.clone()) {
+ return Ok(());
+ }
+
+ match classify_noderef!(? ptr.borrow().node) {
+ NodeKind::Internal => {
+ let evicted = self.lru_internal.evict_for_val(ptr.clone(), locked_ptr)?;
+ for node in evicted {
+ self.try_remove_node(node.clone(), locked_ptr)?;
+ }
+ self.lru_internal.add(ptr);
+ }
+ NodeKind::Leaf => {
+ let evicted = self.lru_leaf.evict_for_val(ptr.clone(), locked_ptr)?;
+ for node in evicted {
+ self.try_remove_node(node.clone(), locked_ptr)?;
+ }
+ self.lru_leaf.add(ptr);
+ }
+ NodeKind::None => return Ok(()),
+ };
+
+ Ok(())
+ }
+
+ fn try_remove_node(
+ &mut self,
+ ptr: NodePtrRef,
+ locked_ptr: Option<&NodePtrRef>,
+ ) -> Result<(), RemoveLockedError> {
+ #[derive(Clone, Copy)]
+ enum VisitState {
+ Unvisited,
+ VisitedLeaf,
+ VisitedLeft,
+ VisitedRight,
+ }
+ #[derive(Clone)]
+ struct PendingNode(NodePtrRef, VisitState);
+
+ let mut stack: Vec<PendingNode> = vec![PendingNode(ptr, VisitState::Unvisited)];
+ 'stack: while !stack.is_empty() {
+ let top_idx = stack.len() - 1;
+ let top = stack[top_idx].clone();
+
+ if let Some(locked_ptr) = locked_ptr {
+ if locked_ptr.as_ptr() == top.0.as_ptr() {
+ return Err(RemoveLockedError);
+ }
+ }
+
+ // Perform removal in depth-first order. We do not remove the node from
+ // the stack until all of its subtrees have been fully removed.
+ if let Some(ref node_ref) = top.0.borrow().node {
+ if let NodeBox::Internal(ref n) = *node_ref.borrow() {
+ match top.1 {
+ VisitState::Unvisited => {
+ stack[top_idx].1 = VisitState::VisitedLeaf;
+ stack.push(PendingNode(n.leaf_node.clone(), VisitState::Unvisited));
+ continue 'stack;
+ }
+ VisitState::VisitedLeaf => {
+ stack[top_idx].1 = VisitState::VisitedLeft;
+ stack.push(PendingNode(n.left.clone(), VisitState::Unvisited));
+ continue 'stack;
+ }
+ VisitState::VisitedLeft => {
+ stack[top_idx].1 = VisitState::VisitedRight;
+ stack.push(PendingNode(n.right.clone(), VisitState::Unvisited));
+ continue 'stack;
+ }
+ VisitState::VisitedRight => {
+ // Now it can finally be removed.
+ }
+ }
+ }
+ }
+
+ stack.pop();
+
+ match classify_noderef!(? top.0.borrow().node) {
+ NodeKind::Internal => {
+ self.lru_internal.remove(top.0.clone());
+ top.0.borrow_mut().node = None;
+ }
+ NodeKind::Leaf => {
+ self.lru_leaf.remove(top.0.clone());
+ top.0.borrow_mut().node = None;
+ }
+ NodeKind::None => {}
+ }
+ }
+
+ Ok(())
+ }
+
+ fn commit_merged_node(
+ &mut self,
+ ptr: NodePtrRef,
+ locked_ptr: &NodePtrRef,
+ ) -> Result<(), RemoveLockedError> {
+ // Try to commit the node. If we fail this means that there is not enough
+ // space in the cache to keep the node that we are trying to dereference.
+ if let Err(error) = self.try_commit_node(ptr.clone(), Some(locked_ptr)) {
+ // Failed to commit, make sure to not keep the subtree in memory.
+ ptr.borrow_mut().node = None;
+ return Err(error);
+ }
+
+ // Commit all children.
+ match classify_noderef!(? ptr.borrow().node) {
+ NodeKind::Internal => {
+ let node_ref = ptr.borrow().get_node();
+ self.commit_merged_node(noderef_as!(node_ref, Internal).left.clone(), locked_ptr)?;
+ self.commit_merged_node(noderef_as!(node_ref, Internal).right.clone(), locked_ptr)?;
+ }
+ NodeKind::Leaf => {}
+ NodeKind::None => {}
+ }
+
+ Ok(())
+ }
+}
+
+impl Cache for LRUCache {
+ #[cfg(test)]
+ fn stats(&self) -> CacheStats {
+ CacheStats {
+ internal_node_count: self.lru_internal.size,
+ leaf_value_size: self.lru_leaf.size,
+ }
+ }
+
+ fn get_pending_root(&self) -> NodePtrRef {
+ self.pending_root.clone()
+ }
+
+ fn set_pending_root(&mut self, new_root: NodePtrRef) {
+ self.pending_root = new_root;
+ }
+
+ fn set_sync_root(&mut self, root: Root) {
+ self.sync_root = root;
+ }
+
+ #[cfg(test)]
+ fn get_read_syncer(&self) -> &Box<dyn ReadSync> {
+ &self.read_syncer
+ }
+
+ fn new_internal_node(
+ &mut self,
+ label: &Key,
+ label_bit_length: Depth,
+ leaf_node: NodePtrRef,
+ left: NodePtrRef,
+ right: NodePtrRef,
+ ) -> NodePtrRef {
+ let node = Rc::new(RefCell::new(NodeBox::Internal(InternalNode {
+ label: label.clone(),
+ label_bit_length,
+ leaf_node,
+ left,
+ right,
+ ..Default::default()
+ })));
+ self.new_internal_node_ptr(Some(node))
+ }
+
+ fn new_leaf_node(&mut self, key: &Key, value: Value) -> NodePtrRef {
+ let node = Rc::new(RefCell::new(NodeBox::Leaf(LeafNode {
+ key: key.clone(),
+ value,
+ ..Default::default()
+ })));
+ self.new_leaf_node_ptr(Some(node))
+ }
+
+ fn remove_node(&mut self, ptr: NodePtrRef) {
+ self.try_remove_node(ptr, None)
+ .expect("no locked pointer passed, cannot fail");
+ }
+
+ fn deref_node_ptr<F: ReadSyncFetcher>(
+ &mut self,
+ ptr: NodePtrRef,
+ fetcher: Option<F>,
+ ) -> Result<Option<NodeRef>> {
+ let ptr_ref = ptr;
+ let ptr = ptr_ref.borrow();
+
+ self.use_node(ptr_ref.clone());
+
+ if let Some(ref node) = &ptr.node {
+ let refetch = match *node.borrow() {
+ NodeBox::Internal(ref n) => {
+ // If this is an internal node, check if the leaf node has been evicted.
+ // In this case treat it as if we need to re-fetch the node.
+ let leaf_ptr = n.leaf_node.borrow();
+ !leaf_ptr.is_null() && leaf_ptr.node.is_none()
+ }
+ NodeBox::Leaf(..) => false,
+ };
+
+ if refetch {
+ drop(ptr);
+ self.remove_node(ptr_ref.clone());
+ } else {
+ return Ok(Some(node.clone()));
+ }
+ } else {
+ if !ptr.clean || ptr.is_null() {
+ return Ok(None);
+ }
+ drop(ptr);
+ }
+
+ // Node not available locally, fetch from read syncer.
+ if let Some(fetcher) = fetcher {
+ self.remote_sync(ptr_ref.clone(), fetcher)?;
+ } else {
+ return Err(anyhow!(
+ "mkvs: node to dereference not available locally and no fetcher provided"
+ ));
+ }
+
+ let ptr = ptr_ref.borrow();
+ if ptr.node.is_none() {
+ return Err(anyhow!(
+ "mkvs: received result did not contain node (or cache too small)"
+ ));
+ }
+ Ok(ptr.node.clone())
+ }
+
+ fn remote_sync<F: ReadSyncFetcher>(&mut self, ptr: NodePtrRef, fetcher: F) -> Result<()> {
+ let proof = fetcher.fetch(self.sync_root, ptr.clone(), &mut self.read_syncer)?;
+
+ // The proof can be for one of two hashes: i) it is either for ptr.Hash in case
+ // all the nodes are only contained in the subtree below ptr, or ii) it is for
+ // the c.syncRoot.Hash in case it contains nodes outside the subtree.
+ let ptr_hash = ptr.borrow().hash;
+ let (dst_ptr, expected_root) = if proof.untrusted_root == ptr_hash {
+ (ptr.clone(), ptr_hash)
+ } else if proof.untrusted_root == self.sync_root.hash {
+ (self.pending_root.clone(), self.sync_root.hash)
+ } else {
+ return Err(anyhow!(
+ "mkvs: got proof for unexpected root ({:?})",
+ proof.untrusted_root
+ ));
+ };
+
+ // Verify proof.
+ let pv = ProofVerifier;
+ let subtree = pv.verify_proof(expected_root, &proof)?;
+
+ // Merge resulting nodes.
+ let mut merged_nodes: Vec<NodePtrRef> = Vec::new();
+ merge_verified_subtree(dst_ptr, subtree, &mut merged_nodes)?;
+ let mut remove = false;
+ for node_ref in merged_nodes {
+ if remove {
+ // Do not keep subtrees that we failed to commit in memory.
+ node_ref.borrow_mut().node = None;
+ }
+
+ if let Err(RemoveLockedError) = self.commit_merged_node(node_ref, &ptr) {
+ // Cache is too small, ignore.
+ remove = true;
+ }
+ }
+
+ Ok(())
+ }
+
+ fn use_node(&mut self, ptr: NodePtrRef) -> bool {
+ match classify_noderef!(? ptr.borrow().node) {
+ NodeKind::Internal => self.lru_internal.use_val(ptr),
+ NodeKind::Leaf => self.lru_leaf.use_val(ptr),
+ NodeKind::None => false,
+ }
+ }
+
+ fn commit_node(&mut self, ptr: NodePtrRef) {
+ self.try_commit_node(ptr, None)
+ .expect("no locked pointer passed, cannot fail");
+ }
+
+ fn rollback_node(&mut self, ptr: NodePtrRef, kind: NodeKind) {
+ if ptr.borrow().get_cache_extra().is_none() {
+ // Node has not yet been committed to cache.
+ return;
+ }
+
+ let lru = match kind {
+ NodeKind::Internal => &mut self.lru_internal,
+ NodeKind::Leaf => &mut self.lru_leaf,
+ NodeKind::None => panic!("lru_cache: rollback works only for Internal and Leaf nodes!"),
+ };
+ lru.remove(ptr.clone());
+
+ ptr.borrow_mut().set_cache_extra(None);
+ }
+
+ fn mark_position(&mut self) {
+ self.lru_internal.mark();
+ self.lru_leaf.mark();
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +
mod lru_cache;
+
+pub use lru_cache::LRUCache;
+
+use std::ptr::NonNull;
+
+use anyhow::Result;
+
+use crate::storage::mkvs::{
+ cache::lru_cache::CacheItemBox,
+ sync::{Proof, ReadSync},
+ tree::{Depth, Key, NodeKind, NodePtrRef, NodeRef, Root, Value},
+};
+
+/// Statistics about the contents of the cache.
+#[derive(Debug, Default)]
+#[cfg(test)]
+pub struct CacheStats {
+ /// Count of internal nodes held by the cache.
+ pub internal_node_count: usize,
+ /// Total size of values held by the cache.
+ pub leaf_value_size: usize,
+}
+
+/// Used to fetch proofs from a remote tree via the ReadSyncer interface.
+pub trait ReadSyncFetcher {
+ /// Fetch proof.
+ fn fetch(&self, root: Root, ptr: NodePtrRef, rs: &mut Box<dyn ReadSync>) -> Result<Proof>;
+}
+
+impl<F> ReadSyncFetcher for F
+where
+ F: Fn(Root, NodePtrRef, &mut Box<dyn ReadSync>) -> Result<Proof>,
+{
+ fn fetch(&self, root: Root, ptr: NodePtrRef, rs: &mut Box<dyn ReadSync>) -> Result<Proof> {
+ (*self)(root, ptr, rs)
+ }
+}
+
+/// Cache interface for the in-mmory tree cache.
+pub trait Cache {
+ /// Return statistics about the contents of the cache.
+ #[cfg(test)]
+ fn stats(&self) -> CacheStats;
+
+ /// Get a pointer to the current uncommitted root node.
+ fn get_pending_root(&self) -> NodePtrRef;
+ /// Set the root node for the tree to the given pointer.
+ fn set_pending_root(&mut self, new_root: NodePtrRef);
+ /// Set the root of the tree after committing.
+ fn set_sync_root(&mut self, root: Root);
+
+ /// Get the read syncer backing this cache.
+ #[cfg(test)]
+ fn get_read_syncer(&self) -> &Box<dyn ReadSync>;
+
+ /// Create a new internal node and returns a pointer to it.
+ fn new_internal_node(
+ &mut self,
+ label: &Key,
+ label_bit_length: Depth,
+ leaf_node: NodePtrRef,
+ left: NodePtrRef,
+ right: NodePtrRef,
+ ) -> NodePtrRef;
+ /// Create a new leaf node and returns a pointer to it.
+ fn new_leaf_node(&mut self, key: &Key, value: Value) -> NodePtrRef;
+
+ /// Try removing a node from the cache.
+ fn remove_node(&mut self, ptr: NodePtrRef);
+
+ /// Dereference a node pointer into a concrete node object.
+ ///
+ /// Calling this method may invoke the underlying read syncer.
+ /// Giving a None fetcher forces the dereference to be local-only,
+ /// without invoking the read syncer.
+ fn deref_node_ptr<F: ReadSyncFetcher>(
+ &mut self,
+ ptr: NodePtrRef,
+ fetcher: Option<F>,
+ ) -> Result<Option<NodeRef>>;
+ /// Perform a remote sync with the configured remote syncer.
+ fn remote_sync<F: ReadSyncFetcher>(&mut self, ptr: NodePtrRef, fetcher: F) -> Result<()>;
+
+ /// Mark that a tree node was just used.
+ fn use_node(&mut self, ptr: NodePtrRef) -> bool;
+
+ /// Commit a node into the cache.
+ ///
+ /// This method may evict some nodes in order to make space
+ /// for the one being committed.
+ fn commit_node(&mut self, ptr: NodePtrRef);
+
+ // Mark a tree node as no longer being eligible for eviction
+ // due to it becoming dirty.
+ fn rollback_node(&mut self, ptr: NodePtrRef, kind: NodeKind);
+
+ /// Mark the current LRU queue positions as the ones before any nodes are
+ /// visited. Any new nodes committed into the cache after this is called
+ /// will be inserted after the marked position.
+ ///
+ /// This makes it possible to keep the path from the root to the derefed
+ /// node in the cache instead of evicting it.
+ fn mark_position(&mut self);
+}
+
+/// Shorthand for the type that cacheable items must hold to aid caching.
+pub type CacheExtra<T> = Option<NonNull<CacheItemBox<T>>>;
+
+/// Cacheable objects must implement this trait to enable the cache to cache them.
+pub trait CacheItem<Item = Self>
+where
+ Item: CacheItem + Default,
+{
+ /// Get the item's caching hint.
+ ///
+ /// For e.g. the LRU cache, this may be a used timestamp.
+ fn get_cache_extra(&self) -> CacheExtra<Item>;
+ /// Set the item's caching hint.
+ fn set_cache_extra(&mut self, new_val: CacheExtra<Item>);
+ /// Return the size, in bytes, of the item when cached.
+ fn get_cached_size(&self) -> usize;
+}
+
+/// Callback type used for updating cache items after a commit.
+pub type CacheUpdater<C> = Box<dyn Fn(&mut C)>;
+
+/// A list of cache update callbacks.
+pub struct UpdateList<C: Cache> {
+ updates: Vec<CacheUpdater<C>>,
+}
+
+impl<C: Cache> UpdateList<C> {
+ /// Construct a new UpdateList instance.
+ pub fn new() -> UpdateList<C> {
+ UpdateList {
+ updates: Vec::new(),
+ }
+ }
+
+ /// Push a new callback to the end of the list.
+ pub fn push(&mut self, updater: CacheUpdater<C>) {
+ self.updates.push(updater);
+ }
+
+ /// Commit the update list by calling all callbacks in order and destroying the list.
+ pub fn commit(&mut self, cache: &mut C) {
+ for update in &self.updates {
+ (update)(cache);
+ }
+ self.updates.clear();
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +
use std::io::Cursor;
+
+use anyhow::{anyhow, Result};
+use byteorder::{LittleEndian, ReadBytesExt, WriteBytesExt};
+
+/// The `Marshal` trait is used for marshaling and unmarshaling MKVS trees.
+pub trait Marshal {
+ /// Marshal the object into a binary form and return it as a new vector.
+ fn marshal_binary(&self) -> Result<Vec<u8>>;
+ /// Unmarshal from the given byte slice reference and modify `self`.
+ fn unmarshal_binary(&mut self, data: &[u8]) -> Result<usize>;
+}
+
+impl Marshal for u16 {
+ fn marshal_binary(&self) -> Result<Vec<u8>> {
+ let mut result: Vec<u8> = Vec::with_capacity(2);
+ result.write_u16::<LittleEndian>(*self)?;
+ Ok(result)
+ }
+
+ fn unmarshal_binary(&mut self, data: &[u8]) -> Result<usize> {
+ if data.len() < 2 {
+ Err(anyhow!("mkvs: malformed 16-bit integer"))
+ } else {
+ let mut reader = Cursor::new(data);
+ *self = reader.read_u16::<LittleEndian>()?;
+ Ok(2)
+ }
+ }
+}
+
+impl Marshal for u32 {
+ fn marshal_binary(&self) -> Result<Vec<u8>> {
+ let mut result: Vec<u8> = Vec::with_capacity(4);
+ result.write_u32::<LittleEndian>(*self)?;
+ Ok(result)
+ }
+
+ fn unmarshal_binary(&mut self, data: &[u8]) -> Result<usize> {
+ if data.len() < 4 {
+ Err(anyhow!("mkvs: malformed 32-bit integer"))
+ } else {
+ let mut reader = Cursor::new(data);
+ *self = reader.read_u32::<LittleEndian>()?;
+ Ok(4)
+ }
+ }
+}
+
+impl Marshal for u64 {
+ fn marshal_binary(&self) -> Result<Vec<u8>> {
+ let mut result: Vec<u8> = Vec::with_capacity(8);
+ result.write_u64::<LittleEndian>(*self)?;
+ Ok(result)
+ }
+
+ fn unmarshal_binary(&mut self, data: &[u8]) -> Result<usize> {
+ if data.len() < 8 {
+ Err(anyhow!("mkvs: malformed 64-bit integer"))
+ } else {
+ let mut reader = Cursor::new(data);
+ *self = reader.read_u64::<LittleEndian>()?;
+ Ok(8)
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +
//! Merklized key-value store.
+use std::{
+ iter,
+ ops::{Deref, DerefMut},
+};
+
+use anyhow::{Error, Result};
+
+use crate::common::{crypto::hash::Hash, namespace::Namespace};
+
+use self::sync::Proof;
+
+#[macro_use]
+mod tree;
+mod cache;
+#[cfg(test)]
+pub mod interop;
+pub mod marshal;
+pub mod sync;
+#[cfg(test)]
+mod tests;
+
+pub use tree::{Depth, Key, NodeBox, NodePointer, NodePtrRef, OverlayTree, Root, RootType, Tree};
+
+/// The type of entry in the log.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+pub enum LogEntryKind {
+ Insert,
+ Delete,
+}
+
+/// An entry in the write log, describing a single update.
+#[derive(Clone, Debug, Default, Eq, PartialEq, Hash, cbor::Encode, cbor::Decode)]
+#[cbor(as_array)]
+pub struct LogEntry {
+ /// The key that was inserted or deleted.
+ pub key: Vec<u8>,
+ /// The inserted value (empty if the key was deleted).
+ pub value: Option<Vec<u8>>,
+}
+
+impl LogEntry {
+ pub fn new(key: &[u8], value: &[u8]) -> Self {
+ Self {
+ key: key.to_owned(),
+ value: Some(value.to_owned()),
+ }
+ }
+
+ pub fn kind(&self) -> LogEntryKind {
+ match self.value {
+ Some(_) => LogEntryKind::Insert,
+ None => LogEntryKind::Delete,
+ }
+ }
+}
+
+/// The write log.
+///
+/// The keys in the write log must be unique.
+pub type WriteLog = Vec<LogEntry>;
+
+/// A key prefix.
+#[derive(Clone, Debug, Default, Eq, PartialEq, PartialOrd, Ord, cbor::Encode, cbor::Decode)]
+#[cbor(transparent)]
+pub struct Prefix(Vec<u8>);
+
+impl AsRef<[u8]> for Prefix {
+ fn as_ref(&self) -> &[u8] {
+ &self.0
+ }
+}
+
+impl Deref for Prefix {
+ type Target = Vec<u8>;
+
+ fn deref(&self) -> &Self::Target {
+ &self.0
+ }
+}
+
+impl DerefMut for Prefix {
+ fn deref_mut(&mut self) -> &mut Self::Target {
+ &mut self.0
+ }
+}
+
+impl From<Prefix> for Vec<u8> {
+ fn from(val: Prefix) -> Self {
+ val.0
+ }
+}
+
+impl From<Vec<u8>> for Prefix {
+ fn from(v: Vec<u8>) -> Prefix {
+ Prefix(v)
+ }
+}
+
+/// Merklized key-value store.
+pub trait MKVS {
+ /// Fetch entry with given key.
+ fn get(&self, key: &[u8]) -> Option<Vec<u8>>;
+
+ /// Fetch proof for entry with given key.
+ fn get_proof(&self, key: &[u8]) -> Option<Proof>;
+
+ /// Check if the local MKVS cache contains the given key.
+ ///
+ /// While get can be used to check if the MKVS as a whole contains
+ /// a given key, this function specifically guarantees that no remote
+ /// syncing will be invoked, only checking the local cache.
+ fn cache_contains_key(&self, key: &[u8]) -> bool;
+
+ /// Update entry with given key.
+ ///
+ /// If the database did not have this key present, [`None`] is returned.
+ ///
+ /// If the database did have this key present, the value is updated, and the old value is
+ /// returned.
+ ///
+ /// [`None`]: std::option::Option
+ fn insert(&mut self, key: &[u8], value: &[u8]) -> Option<Vec<u8>>;
+
+ /// Remove entry with given key, returning the value at the key if the key was previously
+ /// in the database.
+ fn remove(&mut self, key: &[u8]) -> Option<Vec<u8>>;
+
+ /// Populate the in-memory tree with nodes for keys starting with given prefixes.
+ fn prefetch_prefixes(&self, prefixes: &[Prefix], limit: u16);
+
+ /// Returns an iterator over the tree.
+ fn iter(&self) -> Box<dyn Iterator + '_>;
+
+ /// Commit all database changes to the underlying store.
+ fn commit(&mut self, namespace: Namespace, version: u64) -> Result<(WriteLog, Hash)>;
+}
+
+/// Merklized key-value store where methods return errors instead of panicking.
+pub trait FallibleMKVS {
+ /// Fetch entry with given key.
+ fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>>;
+
+ /// Fetch proof for entry with given key.
+ fn get_proof(&self, key: &[u8]) -> Result<Option<Proof>>;
+
+ /// Check if the local MKVS cache contains the given key.
+ ///
+ /// While get can be used to check if the MKVS as a whole contains
+ /// a given key, this function specifically guarantees that no remote
+ /// syncing will be invoked, only checking the local cache.
+ fn cache_contains_key(&self, key: &[u8]) -> bool;
+
+ /// Update entry with given key.
+ ///
+ /// If the database did not have this key present, [`None`] is returned.
+ ///
+ /// If the database did have this key present, the value is updated, and the old value is
+ /// returned.
+ ///
+ /// [`None`]: std::option::Option
+ fn insert(&mut self, key: &[u8], value: &[u8]) -> Result<Option<Vec<u8>>>;
+
+ /// Remove entry with given key, returning the value at the key if the key was previously
+ /// in the database.
+ fn remove(&mut self, key: &[u8]) -> Result<Option<Vec<u8>>>;
+
+ /// Populate the in-memory tree with nodes for keys starting with given prefixes.
+ fn prefetch_prefixes(&self, prefixes: &[Prefix], limit: u16) -> Result<()>;
+
+ /// Returns an iterator over the tree.
+ fn iter(&self) -> Box<dyn Iterator + '_>;
+
+ /// Commit all database changes to the underlying store.
+ fn commit(&mut self, namespace: Namespace, version: u64) -> Result<Hash>;
+}
+
+/// Immutable merkalized key value store.
+pub trait ImmutableMKVS {
+ /// Fetch entry with given key.
+ fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>>;
+
+ /// Fetch proof for entry with given key.
+ fn get_proof(&self, key: &[u8]) -> Result<Option<Proof>>;
+
+ /// Populate the in-memory tree with nodes for keys starting with given prefixes.
+ fn prefetch_prefixes(&self, prefixes: &[Prefix], limit: u16) -> Result<()>;
+
+ /// Returns an iterator over the tree.
+ fn iter(&self) -> Box<dyn Iterator + '_>;
+}
+
+impl<T> ImmutableMKVS for T
+where
+ T: FallibleMKVS,
+{
+ fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>> {
+ T::get(self, key)
+ }
+
+ fn get_proof(&self, key: &[u8]) -> Result<Option<Proof>> {
+ T::get_proof(self, key)
+ }
+
+ fn prefetch_prefixes(&self, prefixes: &[Prefix], limit: u16) -> Result<()> {
+ T::prefetch_prefixes(self, prefixes, limit)
+ }
+
+ fn iter(&self) -> Box<dyn Iterator + '_> {
+ T::iter(self)
+ }
+}
+
+/// An MKVS iterator.
+pub trait Iterator: iter::Iterator<Item = (Vec<u8>, Vec<u8>)> {
+ /// Sets the number of next elements to prefetch.
+ fn set_prefetch(&mut self, prefetch: usize);
+
+ /// Return whether the iterator is valid.
+ fn is_valid(&self) -> bool;
+
+ /// Return the error that occurred during iteration if any.
+ fn error(&self) -> &Option<Error>;
+
+ /// Moves the iterator to the first key in the tree.
+ fn rewind(&mut self);
+
+ /// Moves the iterator either at the given key or at the next larger key.
+ fn seek(&mut self, key: &[u8]);
+
+ /// The key under the iterator.
+ fn get_key(&self) -> &Option<Key>;
+
+ /// The value under the iterator.
+ fn get_value(&self) -> &Option<Vec<u8>>;
+
+ /// Advance the iterator to the next key.
+ fn next(&mut self);
+}
+
+impl<T: MKVS + ?Sized> MKVS for &mut T {
+ fn get(&self, key: &[u8]) -> Option<Vec<u8>> {
+ T::get(self, key)
+ }
+
+ fn get_proof(&self, key: &[u8]) -> Option<Proof> {
+ T::get_proof(self, key)
+ }
+
+ fn cache_contains_key(&self, key: &[u8]) -> bool {
+ T::cache_contains_key(self, key)
+ }
+
+ fn insert(&mut self, key: &[u8], value: &[u8]) -> Option<Vec<u8>> {
+ T::insert(self, key, value)
+ }
+
+ fn remove(&mut self, key: &[u8]) -> Option<Vec<u8>> {
+ T::remove(self, key)
+ }
+
+ fn prefetch_prefixes(&self, prefixes: &[Prefix], limit: u16) {
+ T::prefetch_prefixes(self, prefixes, limit)
+ }
+
+ fn iter(&self) -> Box<dyn Iterator + '_> {
+ T::iter(self)
+ }
+
+ fn commit(&mut self, namespace: Namespace, version: u64) -> Result<(WriteLog, Hash)> {
+ T::commit(self, namespace, version)
+ }
+}
+
+impl<T: FallibleMKVS + ?Sized> FallibleMKVS for &mut T {
+ fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>> {
+ T::get(self, key)
+ }
+
+ fn get_proof(&self, key: &[u8]) -> Result<Option<Proof>> {
+ T::get_proof(self, key)
+ }
+
+ fn cache_contains_key(&self, key: &[u8]) -> bool {
+ T::cache_contains_key(self, key)
+ }
+
+ fn insert(&mut self, key: &[u8], value: &[u8]) -> Result<Option<Vec<u8>>> {
+ T::insert(self, key, value)
+ }
+
+ fn remove(&mut self, key: &[u8]) -> Result<Option<Vec<u8>>> {
+ T::remove(self, key)
+ }
+
+ fn prefetch_prefixes(&self, prefixes: &[Prefix], limit: u16) -> Result<()> {
+ T::prefetch_prefixes(self, prefixes, limit)
+ }
+
+ fn iter(&self) -> Box<dyn Iterator + '_> {
+ T::iter(self)
+ }
+
+ fn commit(&mut self, namespace: Namespace, version: u64) -> Result<Hash> {
+ T::commit(self, namespace, version)
+ }
+}
+
+#[cfg(test)]
+mod _tests {
+ use super::*;
+
+ #[test]
+ fn test_write_log_serialization() {
+ let write_log = vec![LogEntry {
+ key: b"foo".to_vec(),
+ value: Some(b"bar".to_vec()),
+ }];
+
+ let raw = cbor::to_vec(write_log.clone());
+ let deserialized: WriteLog = cbor::from_slice(&raw).unwrap();
+
+ assert_eq!(write_log, deserialized);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +
use std::{any::Any, sync::Arc};
+
+use anyhow::Result;
+
+use crate::{
+ protocol::{Protocol, ProtocolError},
+ storage::mkvs::sync::{
+ GetPrefixesRequest, GetRequest, IterateRequest, ProofResponse, ReadSync,
+ },
+ types::{
+ Body, HostStorageEndpoint, StorageSyncRequest, StorageSyncRequestWithEndpoint,
+ StorageSyncResponse,
+ },
+};
+
+/// A proxy read syncer which forwards calls to the runtime host.
+pub struct HostReadSyncer {
+ protocol: Arc<Protocol>,
+ endpoint: HostStorageEndpoint,
+}
+
+impl HostReadSyncer {
+ /// Construct a new host proxy instance.
+ pub fn new(protocol: Arc<Protocol>, endpoint: HostStorageEndpoint) -> HostReadSyncer {
+ HostReadSyncer { protocol, endpoint }
+ }
+
+ fn call_host_with_proof(&self, request: StorageSyncRequest) -> Result<ProofResponse> {
+ let request = Body::HostStorageSyncRequest(StorageSyncRequestWithEndpoint {
+ endpoint: self.endpoint,
+ request,
+ });
+ match self.protocol.call_host(request) {
+ Ok(Body::HostStorageSyncResponse(StorageSyncResponse::ProofResponse(response))) => {
+ Ok(response)
+ }
+ Ok(_) => Err(ProtocolError::InvalidResponse.into()),
+ Err(error) => Err(error.into()),
+ }
+ }
+}
+
+impl ReadSync for HostReadSyncer {
+ fn as_any(&self) -> &dyn Any {
+ self
+ }
+
+ fn sync_get(&mut self, request: GetRequest) -> Result<ProofResponse> {
+ self.call_host_with_proof(StorageSyncRequest::SyncGet(request))
+ }
+
+ fn sync_get_prefixes(&mut self, request: GetPrefixesRequest) -> Result<ProofResponse> {
+ self.call_host_with_proof(StorageSyncRequest::SyncGetPrefixes(request))
+ }
+
+ fn sync_iterate(&mut self, request: IterateRequest) -> Result<ProofResponse> {
+ self.call_host_with_proof(StorageSyncRequest::SyncIterate(request))
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +
use anyhow::{anyhow, Result};
+
+use crate::storage::mkvs::tree::*;
+
+/// Merges a previously verified subtree with an existing tree.
+pub fn merge_verified_subtree(
+ dst: NodePtrRef,
+ subtree: NodePtrRef,
+ updater: &mut Vec<NodePtrRef>,
+) -> Result<()> {
+ let dst_ref = dst;
+ let mut dst = dst_ref.borrow_mut();
+ let subtree = subtree.borrow();
+ if dst.is_null() || subtree.is_null() {
+ return Ok(());
+ }
+
+ if !dst.clean {
+ // TODO: Support merging into non-clean subtrees. If a subtree
+ // is not clean, this means that the tree structure may
+ // be changed.
+ return Err(anyhow!(
+ "merger: merging into non-clean subtree not yet supported"
+ ));
+ }
+
+ // If the destination pointer is clean, sanity check that we are
+ // merging correct nodes.
+ if dst.hash != subtree.hash {
+ return Err(anyhow!(
+ "merger: hash mismatch during merge (expected: {:?} got: {:?})",
+ dst.hash,
+ subtree.hash,
+ ));
+ }
+
+ // If the subtree node is nil, there is nothing more to merge.
+ if subtree.node.is_none() {
+ return Ok(());
+ }
+
+ // If destination node is nil, we can simply replace the whole subtree.
+ if dst.node.is_none() {
+ dst.node = subtree.node.clone();
+ drop(dst);
+ updater.push(dst_ref);
+ return Ok(());
+ }
+
+ if let NodeBox::Internal(ref int_dst) = *dst.node.as_ref().unwrap().borrow() {
+ if let NodeBox::Internal(ref int_subtree) = *subtree.node.as_ref().unwrap().borrow() {
+ // Proceed with merging children.
+ merge_verified_subtree(int_dst.left.clone(), int_subtree.left.clone(), updater)?;
+ merge_verified_subtree(int_dst.right.clone(), int_subtree.right.clone(), updater)?;
+ } else {
+ panic!("hash was the same so nodes must be of the same type");
+ }
+ }
+
+ Ok(())
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +
//! The read-only tree sync interface.
+mod errors;
+mod host;
+mod merge;
+mod noop;
+mod proof;
+mod stats;
+
+pub use errors::SyncerError;
+pub use host::HostReadSyncer;
+pub use merge::merge_verified_subtree;
+pub use noop::NoopReadSyncer;
+pub use proof::{Proof, ProofBuilder, ProofVerifier, RawProofEntry};
+pub use stats::StatsCollector;
+
+use std::any::Any;
+
+use anyhow::Result;
+
+use crate::{
+ common::crypto::hash::Hash,
+ storage::mkvs::{tree::Root, Prefix},
+};
+
+/// Identifies a specific tree and a position within that tree.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct TreeID {
+ /// The Merkle tree root.
+ pub root: Root,
+ /// The caller's position in the tree structure to allow
+ /// returning partial proofs if possible.
+ pub position: Hash,
+}
+
+/// Request for the SyncGet operation.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct GetRequest {
+ pub tree: TreeID,
+ pub key: Vec<u8>,
+ #[cbor(optional)]
+ pub include_siblings: bool,
+}
+
+/// Request for the SyncGetPrefixes operation.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct GetPrefixesRequest {
+ pub tree: TreeID,
+ pub prefixes: Vec<Prefix>,
+ pub limit: u16,
+}
+
+/// Request for the SyncIterate operation.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct IterateRequest {
+ pub tree: TreeID,
+ pub key: Vec<u8>,
+ pub prefetch: u16,
+}
+
+/// Response for requests that produce proofs.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct ProofResponse {
+ pub proof: Proof,
+}
+
+/// ReadSync is the interface for synchronizing the in-memory cache
+/// with another (potentially untrusted) MKVS.
+pub trait ReadSync {
+ /// Return `self` as an `Any` object, useful for downcasting.
+ fn as_any(&self) -> &dyn Any;
+
+ /// Fetch a single key and returns the corresponding proof.
+ fn sync_get(&mut self, request: GetRequest) -> Result<ProofResponse>;
+
+ /// Fetch all keys under the given prefixes and returns the corresponding proofs.
+ fn sync_get_prefixes(&mut self, request: GetPrefixesRequest) -> Result<ProofResponse>;
+
+ /// Seek to a given key and then fetch the specified number of following items
+ /// based on key iteration order.
+ fn sync_iterate(&mut self, request: IterateRequest) -> Result<ProofResponse>;
+}
+
+#[cfg(test)]
+mod test;
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +
use std::any::Any;
+
+use anyhow::Result;
+
+use crate::storage::mkvs::sync::{
+ GetPrefixesRequest, GetRequest, IterateRequest, ProofResponse, ReadSync, SyncerError,
+};
+
+/// A no-op read syncer which doesn't support any of the required operations.
+pub struct NoopReadSyncer;
+
+impl ReadSync for NoopReadSyncer {
+ fn as_any(&self) -> &dyn Any {
+ self
+ }
+
+ fn sync_get(&mut self, _request: GetRequest) -> Result<ProofResponse> {
+ Err(SyncerError::Unsupported.into())
+ }
+
+ fn sync_get_prefixes(&mut self, _request: GetPrefixesRequest) -> Result<ProofResponse> {
+ Err(SyncerError::Unsupported.into())
+ }
+
+ fn sync_iterate(&mut self, _request: IterateRequest) -> Result<ProofResponse> {
+ Err(SyncerError::Unsupported.into())
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +
use std::{
+ cell::RefCell,
+ collections::BTreeMap,
+ ops::{Deref, DerefMut},
+ rc::Rc,
+};
+
+use anyhow::{anyhow, Result};
+use arbitrary::Arbitrary;
+
+use crate::{
+ common::crypto::hash::Hash,
+ storage::mkvs::{marshal::Marshal, tree::*},
+};
+
+/// Proof entry type for full nodes.
+const PROOF_ENTRY_FULL: u8 = 0x01;
+/// Proof entry type for subtree hashes.
+const PROOF_ENTRY_HASH: u8 = 0x02;
+
+// Min and max supported proof versions.
+const MIN_PROOF_VERSION: u16 = 0;
+const MAX_PROOF_VERSION: u16 = 1;
+
+/// A raw proof entry.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode, Arbitrary)]
+#[cbor(transparent)]
+pub struct RawProofEntry(pub Vec<u8>);
+
+impl AsRef<[u8]> for RawProofEntry {
+ fn as_ref(&self) -> &[u8] {
+ &self.0
+ }
+}
+
+impl Deref for RawProofEntry {
+ type Target = Vec<u8>;
+
+ fn deref(&self) -> &Self::Target {
+ &self.0
+ }
+}
+
+impl DerefMut for RawProofEntry {
+ fn deref_mut(&mut self) -> &mut Self::Target {
+ &mut self.0
+ }
+}
+
+impl From<RawProofEntry> for Vec<u8> {
+ fn from(val: RawProofEntry) -> Self {
+ val.0
+ }
+}
+
+impl From<Vec<u8>> for RawProofEntry {
+ fn from(v: Vec<u8>) -> RawProofEntry {
+ RawProofEntry(v)
+ }
+}
+
+/// A Merkle proof for a subtree.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct Proof {
+ // The proof version.
+ //
+ // We don't use `Versioned` since we want version 0 proofs to be
+ // backwards compatible with the old structure which was not versioned.
+ //
+ // Version 0:
+ // Initial format.
+ //
+ // Version 1 change:
+ // Leaf nodes are included separately, as children. In version 0 the leaf node was
+ // serialized within the internal node. The rationale behind this change is to eliminate
+ // the need to serialize all leaf nodes on the path when proving the existence of a
+ // specific value.
+ #[cbor(optional)]
+ pub v: u16,
+ /// The root hash this proof is for. This should only be used as a quick
+ /// sanity check and proof verification MUST use an independently obtained
+ /// root hash as the prover can provide any root.
+ pub untrusted_root: Hash,
+ /// Proof entries in pre-order traversal.
+ pub entries: Vec<Option<RawProofEntry>>,
+}
+
+struct ProofNode {
+ serialized: Vec<u8>,
+ children: Vec<Hash>,
+}
+
+/// A Merkle proof builder.
+pub struct ProofBuilder {
+ proof_version: u16,
+ root: Hash,
+ included: BTreeMap<Hash, ProofNode>,
+}
+
+impl ProofBuilder {
+ /// Create a new proof builder for the given root hash.
+ pub fn new(root: Hash) -> Self {
+ Self::new_with_version(root, MAX_PROOF_VERSION).unwrap()
+ }
+
+ /// Create a new proof builder for the given root hash and proof version.
+ pub fn new_with_version(root: Hash, proof_version: u16) -> Result<Self> {
+ if !(MIN_PROOF_VERSION..=MAX_PROOF_VERSION).contains(&proof_version) {
+ return Err(anyhow!(
+ "proof builder: unsupported proof version: {}",
+ proof_version
+ ));
+ }
+
+ Ok(Self {
+ proof_version,
+ root,
+ included: BTreeMap::new(),
+ })
+ }
+
+ /// Add a node to the set of included nodes.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the node is not clean.
+ pub fn include(&mut self, node: &NodeBox) {
+ if !node.is_clean() {
+ panic!("proof builder: node is not clean");
+ }
+
+ // If node is already included, skip.
+ let nh = node.get_hash();
+ if self.included.contains_key(&nh) {
+ return;
+ }
+ let mut pn = ProofNode {
+ serialized: node
+ .compact_marshal_binary(self.proof_version)
+ .expect("marshaling node in proof"),
+ children: vec![],
+ };
+
+ // For internal nodes, also include children.
+ if let NodeBox::Internal(nd) = node {
+ fn get_child_hash(nd: &Rc<RefCell<NodePointer>>) -> Hash {
+ nd.borrow()
+ .node
+ .as_ref()
+ .map(|n| n.borrow().get_hash())
+ .unwrap_or_else(Hash::empty_hash)
+ }
+
+ if self.proof_version == 1 {
+ // In proof version 1, leaf nodes are included separately as children.
+ pn.children.push(get_child_hash(&nd.leaf_node));
+ }
+ pn.children.push(get_child_hash(&nd.left));
+ pn.children.push(get_child_hash(&nd.right));
+ }
+
+ self.included.insert(nh, pn);
+ }
+
+ /// Build the (unverified) proof.
+ pub fn build(&self) -> Proof {
+ let mut proof = Proof {
+ v: self.proof_version,
+ untrusted_root: self.root,
+ entries: vec![],
+ };
+ self._build(&mut proof, &self.root);
+
+ proof
+ }
+
+ fn _build(&self, p: &mut Proof, h: &Hash) {
+ if h.is_empty() {
+ // Append nil for empty nodes.
+ p.entries.push(None);
+ return;
+ }
+
+ match self.included.get(h) {
+ None => {
+ // Node is not included in this proof, just add hash of subtree.
+ let mut data = Vec::with_capacity(h.as_ref().len() + 1);
+ data.push(PROOF_ENTRY_HASH);
+ data.extend_from_slice(h.as_ref());
+
+ p.entries.push(Some(RawProofEntry(data)));
+ }
+ Some(pn) => {
+ // Pre-order traversal, add visited node.
+ let mut data = Vec::with_capacity(pn.serialized.len() + 1);
+ data.push(PROOF_ENTRY_FULL);
+ data.extend_from_slice(&pn.serialized);
+
+ p.entries.push(Some(RawProofEntry(data)));
+
+ // Recurse into children.
+ for ch in pn.children.iter() {
+ self._build(p, ch);
+ }
+ }
+ }
+ }
+}
+
+/// A proof verifier enables verifying proofs returned by the ReadSyncer API.
+pub struct ProofVerifier;
+
+impl ProofVerifier {
+ /// Verify a proof and generate an in-memory subtree representing the
+ /// nodes which are included in the proof.
+ pub fn verify_proof(&self, root: Hash, proof: &Proof) -> Result<NodePtrRef> {
+ // Check proof version.
+ if !(MIN_PROOF_VERSION..=MAX_PROOF_VERSION).contains(&proof.v) {
+ return Err(anyhow!("verifier: unsupported proof version: {}", proof.v));
+ }
+
+ // Sanity check that the proof is for the correct root (as otherwise it
+ // makes no sense to verify the proof).
+ if proof.untrusted_root != root {
+ return Err(anyhow!(
+ "verifier: got proof for unexpected root (expected: {:?} got {:?})",
+ root,
+ proof.untrusted_root,
+ ));
+ }
+ if proof.entries.is_empty() {
+ return Err(anyhow!("verifier: empty proof"));
+ }
+
+ let (idx, root_node) = Self::_verify_proof(proof, 0)?;
+ // Make sure that all of the entries in the proof have been used. The returned index should
+ // point to just beyond the last element.
+ if idx != proof.entries.len() {
+ return Err(anyhow!("verifier: unused entries in proof"));
+ }
+ let root_hash = root_node.borrow().hash;
+ if root_hash != root {
+ return Err(anyhow!(
+ "verifier: bad root (expected: {:?} got {:?})",
+ root,
+ root_hash,
+ ));
+ }
+
+ Ok(root_node)
+ }
+
+ fn _verify_proof(proof: &Proof, idx: usize) -> Result<(usize, NodePtrRef)> {
+ if idx >= proof.entries.len() {
+ return Err(anyhow!("verifier: malformed proof"));
+ }
+ let entry = match &proof.entries[idx] {
+ Some(entry) => entry.as_ref(),
+ None => return Ok((idx + 1, NodePointer::null_ptr())),
+ };
+ if entry.is_empty() {
+ return Err(anyhow!("verifier: malformed proof"));
+ }
+
+ match entry[0] {
+ PROOF_ENTRY_FULL => {
+ // Full node.
+ let mut node = NodeBox::default();
+ node.unmarshal_binary(&entry[1..])?;
+
+ // For internal nodes, also decode children.
+ let mut pos = idx + 1;
+ if let NodeBox::Internal(ref mut nd) = node {
+ match proof.v {
+ 0 => {
+ // In proof version 0, leaf nodes are included within the internal node.
+ }
+ 1 => {
+ // In proof version 1, leaf nodes are included separately as children.
+ (pos, nd.leaf_node) = Self::_verify_proof(proof, pos)?;
+ }
+ _ => {
+ // Should not happen, checked in verify_proof.
+ panic!("unsupported proof version: {:?}", proof.v)
+ }
+ }
+
+ // Left.
+ (pos, nd.left) = Self::_verify_proof(proof, pos)?;
+ // Right.
+ (pos, nd.right) = Self::_verify_proof(proof, pos)?;
+
+ // Recompute hash as hashes were not recomputed for compact encoding.
+ nd.update_hash();
+ }
+
+ Ok((pos, NodePointer::from_node(node)))
+ }
+ PROOF_ENTRY_HASH => {
+ // Hash of a node.
+ let entry = &entry[1..];
+ if entry.len() != Hash::len() {
+ return Err(anyhow!("verifier: malformed hash entry"));
+ }
+
+ Ok((idx + 1, NodePointer::hash_ptr(entry.into())))
+ }
+ entry_type => Err(anyhow!(
+ "verifier: unexpected entry in proof ({:?})",
+ entry_type
+ )),
+ }
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use base64::prelude::*;
+ use rustc_hex::ToHex;
+
+ use crate::storage::mkvs::{cache::Cache, sync::NoopReadSyncer};
+
+ use super::*;
+
+ #[test]
+ fn test_proof() {
+ // Test vectors generated by Go.
+
+ // V0 proof.
+ let test_vector_proof = BASE64_STANDARD.decode(
+ "omdlbnRyaWVzhUoBASQAa2V5IDACRgEBAQAAAlghAsFltYRhD4dAwHOdOmEigY1r02pJH6InhiibKlh9neYlWCECpsJnkjOnIgc4+\
+yfvpsqCcIYHh5eld1hNMWTT7arAfHFYIQLhNTLWRbks1RBf52ulnlOTO+7D5EZNMYFzTx8U46sCnm51bnRydXN0ZWRfcm9vdFggWeZ8L9wIuOEN0Iu2\
+uO/mFPzJZey4liX5fxf4fwcQRhM=",
+ ).unwrap();
+
+ let test_vector_root_hash =
+ "59e67c2fdc08b8e10dd08bb6b8efe614fcc965ecb89625f97f17f87f07104613";
+
+ // Proof should decode.
+ let proof: Proof =
+ cbor::from_slice(&test_vector_proof).expect("V0 proof should deserialize");
+ assert_eq!(proof.v, 0, "proof version should be 0");
+ let root_hash = Hash::from(test_vector_root_hash);
+
+ // Proof should round-trip.
+ assert_eq!(
+ test_vector_proof,
+ cbor::to_vec(proof.clone()),
+ "proof should round-trip"
+ );
+
+ // Proof should verify.
+ let pv = ProofVerifier;
+ pv.verify_proof(root_hash, &proof)
+ .expect("verify proof should not fail with a valid proof");
+
+ // Invalid proofs should not verify.
+
+ // Empty proof.
+ let empty_proof = Proof::default();
+ let result = pv.verify_proof(root_hash, &empty_proof);
+ assert!(
+ result.is_err(),
+ "verify proof should fail with an empty proof"
+ );
+
+ // Different root.
+ let bogus_hash = Hash::digest_bytes(b"i am a bogus hash");
+ let result = pv.verify_proof(bogus_hash, &proof);
+ assert!(
+ result.is_err(),
+ "verify proof should fail with a proof for a different root"
+ );
+
+ // Different hash element.
+ let mut corrupted = proof.clone();
+ corrupted.entries[4].as_mut().unwrap()[10] = 0x00;
+ let result = pv.verify_proof(root_hash, &corrupted);
+ assert!(
+ result.is_err(),
+ "verify proof should fail with invalid proof"
+ );
+
+ // Corrupted full node.
+ let mut corrupted = proof.clone();
+ corrupted.entries[0].as_mut().unwrap().truncate(3);
+ let result = pv.verify_proof(root_hash, &corrupted);
+ assert!(
+ result.is_err(),
+ "verify proof should fail with invalid proof"
+ );
+
+ // Corrupted hash.
+ let mut corrupted = proof.clone();
+ corrupted.entries[2].as_mut().unwrap().truncate(3);
+ let result = pv.verify_proof(root_hash, &corrupted);
+ assert!(
+ result.is_err(),
+ "verify proof should fail with invalid proof"
+ );
+
+ // Corrupted proof element type.
+ let mut corrupted = proof.clone();
+ corrupted.entries[3].as_mut().unwrap()[0] = 0xaa;
+ let result = pv.verify_proof(root_hash, &corrupted);
+ assert!(
+ result.is_err(),
+ "verify proof should fail with invalid proof"
+ );
+
+ // Missing elements.
+ let mut corrupted = proof.clone();
+ corrupted.entries.truncate(3);
+ let result = pv.verify_proof(root_hash, &corrupted);
+ assert!(
+ result.is_err(),
+ "verify proof should fail with invalid proof"
+ );
+
+ // V1 proof.
+ let test_vector_proof = BASE64_STANDARD.decode(
+ "o2F2AWdlbnRyaWVzh0oBASQAa2V5IDAC9kYBAQEAAAL2WCECwWW1hGEPh0DAc506YSKBjWvTakkfoieGKJsqWH2d5iVYIQKmwmeSM6ciBzj7J+\
+ +myoJwhgeHl6V3WE0xZNPtqsB8cVghAuE1MtZFuSzVEF/na6WeU5M77sPkRk0xgXNPHxTjqwKebnVudHJ1c3RlZF9yb290WCBZ5nwv3Ai44Q3Qi7a47+\
+ YU/Mll7LiWJfl/F/h/BxBGEw=="
+ ).unwrap();
+
+ // Proof should decode.
+ let proof: Proof =
+ cbor::from_slice(&test_vector_proof).expect("V1 proof should deserialize");
+ assert_eq!(proof.v, 1, "proof version should be 1");
+ let root_hash = Hash::from(test_vector_root_hash);
+
+ // Proof should round-trip.
+ assert_eq!(
+ test_vector_proof,
+ cbor::to_vec(proof.clone()),
+ "proof should round-trip"
+ );
+
+ // Proof should verify.
+ let pv = ProofVerifier;
+ pv.verify_proof(root_hash, &proof)
+ .expect("verify proof should not fail with a valid proof");
+ }
+
+ #[test]
+ fn test_proof_builder_v1() {
+ // NOTE: Ensure this test matches TestProofV1 in go/storage/mkvs/syncer_test.go.
+
+ // Prepare test tree.
+ let mut tree = Tree::builder()
+ .with_root(Root {
+ hash: Hash::empty_hash(),
+ ..Default::default()
+ })
+ .build(Box::new(NoopReadSyncer));
+ for i in 0..11 {
+ let k = format!("key {}", i).into_bytes();
+ let v = format!("value {}", i).into_bytes();
+ tree.insert(&k, &v).expect("insert");
+ }
+ let roothash = tree.commit(Default::default(), 1).expect("commit");
+
+ let mut pb = ProofBuilder::new(roothash);
+
+ // Ensure proof matches Go side.
+ let proof = pb.build();
+ assert_eq!(
+ BASE64_STANDARD.encode(cbor::to_vec(proof)),
+ "o2F2AWdlbnRyaWVzgVghAqlAud7XYhorEEl8hG9G3Hd4OXl5VR1xvuLAepMZ5qpFbnVudHJ1c3RlZF9yb290WCCpQLne12IaKxBJfIRvRtx3eDl5eVUdcb7iwHqTGeaqRQ=="
+ );
+
+ // Include root node.
+ let root_ptr = tree.cache.borrow().get_pending_root();
+ let root_node = root_ptr.borrow().get_node();
+ pb.include(&*root_node.borrow());
+ // Ensure proof matches Go side.
+ let proof = pb.build();
+ assert_eq!(
+ BASE64_STANDARD.encode(cbor::to_vec(proof)),
+ "o2F2AWdlbnRyaWVzhEoBASQAa2V5IDAC9lghAhQ6RgqFtADx+B6VKE0CVRrfDHmwgZwU3ewsj4gswWv+WCEC4TUy1kW5LNUQX+drpZ5Tkzvuw+RGTTGBc08fFOOrAp5udW50cnVzdGVkX3Jvb3RYIKlAud7XYhorEEl8hG9G3Hd4OXl5VR1xvuLAepMZ5qpF",
+ );
+
+ // Include root.left node.
+ let root_left = noderef_as!(root_node, Internal).left.borrow().get_node();
+ pb.include(&*root_left.borrow());
+ // Ensure proof matches Go side.
+ let proof = pb.build();
+ assert_eq!(
+ BASE64_STANDARD.encode(cbor::to_vec(proof)),
+ "o2F2AWdlbnRyaWVzh0oBASQAa2V5IDAC9kYBAQEAAAL2WCEC+OrSSPCCo9/QXQt7IsunAp+eUqMndKBCu0NcGHx4HrhYIQKmwmeSM6ciBzj7J++myoJwhgeHl6V3WE0xZNPtqsB8cVghAuE1MtZFuSzVEF/na6WeU5M77sPkRk0xgXNPHxTjqwKebnVudHJ1c3RlZF9yb290WCCpQLne12IaKxBJfIRvRtx3eDl5eVUdcb7iwHqTGeaqRQ==",
+ );
+
+ // Include root.left.left node.
+ let root_left2 = noderef_as!(root_left, Internal).left.borrow().get_node();
+ pb.include(&*root_left2.borrow());
+
+ // Include root.left.left.left node.
+ let root_left3: Rc<RefCell<NodeBox>> =
+ noderef_as!(root_left2, Internal).left.borrow().get_node();
+ pb.include(&*root_left3.borrow());
+
+ // Include root.left.left.left.right node.
+ let root_left3_right = noderef_as!(root_left3, Internal).right.borrow().get_node();
+ pb.include(&*root_left3_right.borrow());
+
+ // Include root.left.left.left.right.left leaf node.
+ let bottom = noderef_as!(root_left3_right, Internal)
+ .left
+ .borrow()
+ .get_node();
+ pb.include(&*bottom.borrow());
+ // Ensure proof matches Go side.
+ let proof = pb.build();
+ assert_eq!(
+ BASE64_STANDARD.encode(cbor::to_vec(proof)),
+ "o2F2AWdlbnRyaWVzkEoBASQAa2V5IDAC9kYBAQEAAAL2RgEBAQAAAvZGAQEBAAAC9lghAlF8/rp9QOAd1qSchhUxDtVkpmnze6sjz5IfFhdOuaypRgEBAQCAAlghAldMzQwgHh/Ecm+rF+i31AnOgFYBipBAlcx5Tf5l4yW+VgEABgBrZXkgMTAIAAAAdmFsdWUgMTD2WCECDnYjQhsAp5fD+gf0W5YYFY6CnGURrEETtJvJp+ijH4xYIQKmwmeSM6ciBzj7J++myoJwhgeHl6V3WE0xZNPtqsB8cVghAuE1MtZFuSzVEF/na6WeU5M77sPkRk0xgXNPHxTjqwKebnVudHJ1c3RlZF9yb290WCCpQLne12IaKxBJfIRvRtx3eDl5eVUdcb7iwHqTGeaqRQ==",
+ );
+ }
+
+ #[test]
+ fn test_proof_extra_nodes() {
+ // V0 proof.
+ let test_vector_proof = BASE64_STANDARD.decode(
+ "omdlbnRyaWVzhUoBASQAa2V5IDACRgEBAQAAAlghAsFltYRhD4dAwHOdOmEigY1r02pJH6InhiibKlh9neYlWCECpsJnkjOnIgc4+\
+ yfvpsqCcIYHh5eld1hNMWTT7arAfHFYIQLhNTLWRbks1RBf52ulnlOTO+7D5EZNMYFzTx8U46sCnm51bnRydXN0ZWRfcm9vdFggWeZ8L9wIuOEN0Iu2\
+ uO/mFPzJZey4liX5fxf4fwcQRhM=",
+ ).unwrap();
+ let test_vector_root_hash =
+ "59e67c2fdc08b8e10dd08bb6b8efe614fcc965ecb89625f97f17f87f07104613";
+
+ // Proof should decode.
+ let mut proof: Proof =
+ cbor::from_slice(&test_vector_proof).expect("proof should deserialize");
+ let root_hash = Hash::from(test_vector_root_hash);
+
+ // Proof should verify.
+ let pv = ProofVerifier;
+ pv.verify_proof(root_hash, &proof)
+ .expect("verify proof should not fail with a valid proof");
+
+ // Duplicate some nodes and add them to the end.
+ proof.entries.push(proof.entries[0].clone());
+
+ pv.verify_proof(root_hash, &proof)
+ .expect_err("proof with extra data should fail to validate");
+
+ // V1 proof.
+ let test_vector_proof = BASE64_STANDARD.decode(
+ "o2F2AWdlbnRyaWVzh0oBASQAa2V5IDAC9kYBAQEAAAL2WCECwWW1hGEPh0DAc506YSKBjWvTakkfoieGKJsqWH2d5iVYIQKmwmeSM6ciBzj7J+\
+ +myoJwhgeHl6V3WE0xZNPtqsB8cVghAuE1MtZFuSzVEF/na6WeU5M77sPkRk0xgXNPHxTjqwKebnVudHJ1c3RlZF9yb290WCBZ5nwv3Ai44Q3Qi7a47+\
+ YU/Mll7LiWJfl/F/h/BxBGEw=="
+ ).unwrap();
+
+ // Proof should decode.
+ let mut proof: Proof =
+ cbor::from_slice(&test_vector_proof).expect("V1 proof should deserialize");
+ assert_eq!(proof.v, 1, "proof version should be 1");
+ let root_hash = Hash::from(test_vector_root_hash);
+
+ // Proof should verify.
+ let pv = ProofVerifier;
+ pv.verify_proof(root_hash, &proof)
+ .expect("verify proof should not fail with a valid proof");
+
+ // Duplicate some nodes and add them to the end.
+ proof.entries.push(proof.entries[0].clone());
+ pv.verify_proof(root_hash, &proof)
+ .expect_err("verify proof should fail with an invalid proof");
+ }
+
+ #[test]
+ fn test_proof_builder_v0() {
+ // NOTE: Ensure this test matches TestProofV0 in go/storage/mkvs/syncer_test.go.
+
+ // Prepare test tree.
+ let mut tree = Tree::builder()
+ .with_root(Root {
+ hash: Hash::empty_hash(),
+ ..Default::default()
+ })
+ .build(Box::new(NoopReadSyncer));
+ for i in 0..10 {
+ let k = format!("key {}", i).into_bytes();
+ let v = format!("value {}", i).into_bytes();
+ tree.insert(&k, &v).expect("insert");
+ }
+ let roothash = tree.commit(Default::default(), 1).expect("commit");
+
+ // Ensure tree matches Go side.
+ assert_eq!(
+ roothash.0.to_hex::<String>(),
+ "59e67c2fdc08b8e10dd08bb6b8efe614fcc965ecb89625f97f17f87f07104613",
+ );
+
+ // Ensure proof matches Go side.
+ let mut pb = ProofBuilder::new_with_version(roothash, 0).expect("new proof builder v0");
+ let root_only_proof = pb.build();
+ assert_eq!(
+ BASE64_STANDARD.encode(cbor::to_vec(root_only_proof)),
+ "omdlbnRyaWVzgVghAlnmfC/cCLjhDdCLtrjv5hT8yWXsuJYl+X8X+H8HEEYTbnVudHJ1c3RlZF9yb290WCBZ5nwv3Ai44Q3Qi7a47+YU/Mll7LiWJfl/F/h/BxBGEw==",
+ );
+
+ // Include root node.
+ let root_ptr = tree.cache.borrow().get_pending_root();
+ let root_node = root_ptr.borrow().get_node();
+ pb.include(&*root_node.borrow());
+ // Include root.left node.
+ pb.include(
+ &*noderef_as!(root_node, Internal)
+ .left
+ .borrow()
+ .get_node()
+ .borrow(),
+ );
+ // Ensure proofs matches Go side.
+ let test_proof = pb.build();
+ assert_eq!(
+ BASE64_STANDARD.encode(cbor::to_vec(test_proof)),
+ "omdlbnRyaWVzhUoBASQAa2V5IDACRgEBAQAAAlghAsFltYRhD4dAwHOdOmEigY1r02pJH6InhiibKlh9neYlWCECpsJnkjOnIgc4+yfvpsqCcIYHh5eld1hNMWTT7arAfHFYIQLhNTLWRbks1RBf52ulnlOTO+7D5EZNMYFzTx8U46sCnm51bnRydXN0ZWRfcm9vdFggWeZ8L9wIuOEN0Iu2uO/mFPzJZey4liX5fxf4fwcQRhM=",
+ );
+ }
+
+ #[test]
+ fn test_tree_proofs() {
+ // NOTE: Ensure this test matches TestTreeProofs in go/storage/mkvs/syncer_test.go.
+
+ // Prepare test tree.
+ let mut tree = Tree::builder()
+ .with_root(Root {
+ hash: Hash::empty_hash(),
+ ..Default::default()
+ })
+ .build(Box::new(NoopReadSyncer));
+ let mut keys = vec![];
+ for i in 0..11 {
+ let k = format!("key {}", i).into_bytes();
+ let v = format!("value {}", i).into_bytes();
+ tree.insert(&k, &v).expect("insert");
+ keys.push(k);
+ }
+ let roothash = tree.commit(Default::default(), 1).expect("commit");
+ // Ensure tree matches Go side.
+ assert_eq!(
+ roothash.0.to_hex::<String>(),
+ "a940b9ded7621a2b10497c846f46dc7778397979551d71bee2c07a9319e6aa45",
+ );
+
+ for tc in vec![
+ // Note: Tree::get_proof doesn't support version 0 proofs.
+ // We test only version 1 proofs here.
+ (
+ // Proof v.
+ 1,
+ vec![
+ // 0.
+ "o2F2AWdlbnRyaWVzjUoBASQAa2V5IDAC9kYBAQEAAAL2RgEBAQAAAvZGAQEBAAAC9lQBAAUAa2V5IDAHAAAAdmFsdWUgMFghAlO8PtYkGTEg304b/z/cv4oH6+BRaJ88layf7VgIl3xTWCECDnYjQhsAp5fD+gf0W5YYFY6CnGURrEETtJvJp+ijH4xYIQKmwmeSM6ciBzj7J++myoJwhgeHl6V3WE0xZNPtqsB8cVghAuE1MtZFuSzVEF/na6WeU5M77sPkRk0xgXNPHxTjqwKebnVudHJ1c3RlZF9yb290WCCpQLne12IaKxBJfIRvRtx3eDl5eVUdcb7iwHqTGeaqRQ==",
+ // 1.
+ "o2F2AWdlbnRyaWVzkEoBASQAa2V5IDAC9kYBAQEAAAL2RgEBAQAAAvZGAQEBAAAC9lghAlF8/rp9QOAd1qSchhUxDtVkpmnze6sjz5IfFhdOuaypRgEBAQCAAlQBAAUAa2V5IDEHAAAAdmFsdWUgMVghAm2EG0dH85+yEl5rdT67+D59/gbjHB9qDtnCcv0kkuje9lghAg52I0IbAKeXw/oH9FuWGBWOgpxlEaxBE7Sbyafoox+MWCECpsJnkjOnIgc4+yfvpsqCcIYHh5eld1hNMWTT7arAfHFYIQLhNTLWRbks1RBf52ulnlOTO+7D5EZNMYFzTx8U46sCnm51bnRydXN0ZWRfcm9vdFggqUC53tdiGisQSXyEb0bcd3g5eXlVHXG+4sB6kxnmqkU=",
+ // 2.
+ "o2F2AWdlbnRyaWVzjUoBASQAa2V5IDAC9kYBAQEAAAL2RgEBAQAAAvZYIQLnu/nMm00WQo9ZxRbRFM/hVtoTov4Phs3vIQ/6jS/29kYBAQEAgAL2VAEABQBrZXkgMgcAAAB2YWx1ZSAyWCECJtIdvBvSs2Vh4Z1ghY3zvHvK8JsoBmt3+dBpRCNdA/xYIQKmwmeSM6ciBzj7J++myoJwhgeHl6V3WE0xZNPtqsB8cVghAuE1MtZFuSzVEF/na6WeU5M77sPkRk0xgXNPHxTjqwKebnVudHJ1c3RlZF9yb290WCCpQLne12IaKxBJfIRvRtx3eDl5eVUdcb7iwHqTGeaqRQ==",
+ // 3.
+ "o2F2AWdlbnRyaWVzjUoBASQAa2V5IDAC9kYBAQEAAAL2RgEBAQAAAvZYIQLnu/nMm00WQo9ZxRbRFM/hVtoTov4Phs3vIQ/6jS/29kYBAQEAgAL2WCECoYj1TutUHeB1K0anT1hRts8AKOw8AfEtn963XMVxV1xUAQAFAGtleSAzBwAAAHZhbHVlIDNYIQKmwmeSM6ciBzj7J++myoJwhgeHl6V3WE0xZNPtqsB8cVghAuE1MtZFuSzVEF/na6WeU5M77sPkRk0xgXNPHxTjqwKebnVudHJ1c3RlZF9yb290WCCpQLne12IaKxBJfIRvRtx3eDl5eVUdcb7iwHqTGeaqRQ==",
+ // 4.
+ "o2F2AWdlbnRyaWVzjUoBASQAa2V5IDAC9kYBAQEAAAL2WCEC+OrSSPCCo9/QXQt7IsunAp+eUqMndKBCu0NcGHx4HrhGAQEBAIAC9kYBAQEAAAL2VAEABQBrZXkgNAcAAAB2YWx1ZSA0WCEC7uES0HThvwiREsS6OKGDOodNGn7WGC3BTBJSLBIsJf1YIQK31gqPbwp33M7yKb2VSo7eB8p4jZZmYGnJ7njeFBGHtVghAuE1MtZFuSzVEF/na6WeU5M77sPkRk0xgXNPHxTjqwKebnVudHJ1c3RlZF9yb290WCCpQLne12IaKxBJfIRvRtx3eDl5eVUdcb7iwHqTGeaqRQ==",
+ // 5.
+ "o2F2AWdlbnRyaWVzjUoBASQAa2V5IDAC9kYBAQEAAAL2WCEC+OrSSPCCo9/QXQt7IsunAp+eUqMndKBCu0NcGHx4HrhGAQEBAIAC9kYBAQEAAAL2WCECxgplEp2jBopznMqoBJZ1ezCE7IO2Bb5CqLypC+IiEhpUAQAFAGtleSA1BwAAAHZhbHVlIDVYIQK31gqPbwp33M7yKb2VSo7eB8p4jZZmYGnJ7njeFBGHtVghAuE1MtZFuSzVEF/na6WeU5M77sPkRk0xgXNPHxTjqwKebnVudHJ1c3RlZF9yb290WCCpQLne12IaKxBJfIRvRtx3eDl5eVUdcb7iwHqTGeaqRQ==",
+ // 6.
+ "o2F2AWdlbnRyaWVzjUoBASQAa2V5IDAC9kYBAQEAAAL2WCEC+OrSSPCCo9/QXQt7IsunAp+eUqMndKBCu0NcGHx4HrhGAQEBAIAC9lghAivLwJbWkwZ8nROaPHGxpfthiG8vqyPbvzhkEEX793dIRgEBAQCAAvZUAQAFAGtleSA2BwAAAHZhbHVlIDZYIQK96CvAaM4vOReqLe+AoO6KajYFZiUsAyvSi8rEgClU7FghAuE1MtZFuSzVEF/na6WeU5M77sPkRk0xgXNPHxTjqwKebnVudHJ1c3RlZF9yb290WCCpQLne12IaKxBJfIRvRtx3eDl5eVUdcb7iwHqTGeaqRQ==",
+ // 7.
+ "o2F2AWdlbnRyaWVzjUoBASQAa2V5IDAC9kYBAQEAAAL2WCEC+OrSSPCCo9/QXQt7IsunAp+eUqMndKBCu0NcGHx4HrhGAQEBAIAC9lghAivLwJbWkwZ8nROaPHGxpfthiG8vqyPbvzhkEEX793dIRgEBAQCAAvZYIQICPF9slSfLMzCKpIGUKFWpXWq5dxfVdfe6wfGW6xjer1QBAAUAa2V5IDcHAAAAdmFsdWUgN1ghAuE1MtZFuSzVEF/na6WeU5M77sPkRk0xgXNPHxTjqwKebnVudHJ1c3RlZF9yb290WCCpQLne12IaKxBJfIRvRtx3eDl5eVUdcb7iwHqTGeaqRQ==",
+ // 8.
+ "o2F2AWdlbnRyaWVzh0oBASQAa2V5IDAC9lghAhQ6RgqFtADx+B6VKE0CVRrfDHmwgZwU3ewsj4gswWv+RgEBAwCAAvZUAQAFAGtleSA4BwAAAHZhbHVlIDhYIQINczJ806eMr+T/iGsJmo8/JQFXZtjy1/k+as0V9FdfVG51bnRydXN0ZWRfcm9vdFggqUC53tdiGisQSXyEb0bcd3g5eXlVHXG+4sB6kxnmqkU=",
+ // 9.
+ "o2F2AWdlbnRyaWVzh0oBASQAa2V5IDAC9lghAhQ6RgqFtADx+B6VKE0CVRrfDHmwgZwU3ewsj4gswWv+RgEBAwCAAvZYIQIwwW7eyXCi2yXyFCzFD9U+Ssy1gwSwiskBQfk+9KCUA1QBAAUAa2V5IDkHAAAAdmFsdWUgOW51bnRydXN0ZWRfcm9vdFggqUC53tdiGisQSXyEb0bcd3g5eXlVHXG+4sB6kxnmqkU=",
+ // 10.
+ "o2F2AWdlbnRyaWVzkEoBASQAa2V5IDAC9kYBAQEAAAL2RgEBAQAAAvZGAQEBAAAC9lghAlF8/rp9QOAd1qSchhUxDtVkpmnze6sjz5IfFhdOuaypRgEBAQCAAlghAldMzQwgHh/Ecm+rF+i31AnOgFYBipBAlcx5Tf5l4yW+VgEABgBrZXkgMTAIAAAAdmFsdWUgMTD2WCECDnYjQhsAp5fD+gf0W5YYFY6CnGURrEETtJvJp+ijH4xYIQKmwmeSM6ciBzj7J++myoJwhgeHl6V3WE0xZNPtqsB8cVghAuE1MtZFuSzVEF/na6WeU5M77sPkRk0xgXNPHxTjqwKebnVudHJ1c3RlZF9yb290WCCpQLne12IaKxBJfIRvRtx3eDl5eVUdcb7iwHqTGeaqRQ==",
+ ],
+ ),
+ ]{
+ // Ensure tree proofs match Go side.
+ for (i, k) in tc.1.iter().enumerate() {
+ let proof = tree.get_proof(&keys[i]).expect("get proof works").expect("proof exists");
+ assert_eq!(
+ BASE64_STANDARD.encode(cbor::to_vec(proof.clone())),
+ *k,
+ "expected proof for keys[{}]",
+ i
+ );
+ // Proof should verify.
+ let pv = ProofVerifier;
+ pv.verify_proof(roothash, &proof)
+ .expect("verify proof should not fail with a valid proof");
+ }
+ };
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +
use std::any::Any;
+
+use anyhow::Result;
+
+use super::{GetPrefixesRequest, GetRequest, IterateRequest, ProofResponse, ReadSync};
+
+/// A proxy read syncer which keeps track of call statistics.
+pub struct StatsCollector {
+ /// Count of `sync_get` calls made to the underlying read syncer.
+ pub sync_get_count: usize,
+ /// Count of `sync_get_prefixes` calls made to the underlying read syncer.
+ pub sync_get_prefixes_count: usize,
+ /// Count of `sync_iterate` calls made to the underlying read syncer.
+ pub sync_iterate_count: usize,
+
+ rs: Box<dyn ReadSync>,
+}
+
+impl StatsCollector {
+ /// Construct a new instance, proxying to the given backing read syncer.
+ pub fn new(rs: Box<dyn ReadSync>) -> StatsCollector {
+ StatsCollector {
+ sync_get_count: 0,
+ sync_get_prefixes_count: 0,
+ sync_iterate_count: 0,
+ rs,
+ }
+ }
+}
+
+impl ReadSync for StatsCollector {
+ fn as_any(&self) -> &dyn Any {
+ self
+ }
+
+ fn sync_get(&mut self, request: GetRequest) -> Result<ProofResponse> {
+ self.sync_get_count += 1;
+ self.rs.sync_get(request)
+ }
+
+ fn sync_get_prefixes(&mut self, request: GetPrefixesRequest) -> Result<ProofResponse> {
+ self.sync_get_prefixes_count += 1;
+ self.rs.sync_get_prefixes(request)
+ }
+
+ fn sync_iterate(&mut self, request: IterateRequest) -> Result<ProofResponse> {
+ self.sync_iterate_count += 1;
+ self.rs.sync_iterate(request)
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +
use anyhow::Result;
+
+use crate::{
+ common::{crypto::hash::Hash, namespace::Namespace},
+ storage::mkvs::{
+ cache::{Cache, LRUCache, UpdateList},
+ tree::{Node, NodeBox, NodeKind, NodePtrRef, Root, Tree},
+ },
+};
+
+impl Tree {
+ /// Commit tree updates to the underlying database and return
+ /// the write log and new merkle root.
+ pub fn commit(&mut self, namespace: Namespace, version: u64) -> Result<Hash> {
+ let mut update_list: UpdateList<LRUCache> = UpdateList::new();
+ let pending_root = self.cache.borrow().get_pending_root();
+ let new_hash = _commit(pending_root, &mut update_list)?;
+
+ update_list.commit(&mut self.cache.borrow_mut());
+
+ self.cache.borrow_mut().set_sync_root(Root {
+ namespace,
+ version,
+ root_type: self.root_type,
+ hash: new_hash,
+ });
+
+ Ok(new_hash)
+ }
+}
+
+pub fn _commit<C: Cache>(ptr: NodePtrRef, update_list: &mut UpdateList<C>) -> Result<Hash> {
+ if ptr.borrow().clean {
+ return Ok(ptr.borrow().hash);
+ }
+
+ match classify_noderef!(? ptr.borrow().node) {
+ NodeKind::None => {
+ ptr.borrow_mut().hash = Hash::empty_hash();
+ }
+ NodeKind::Internal => {
+ let some_node_ref = ptr.borrow().get_node();
+ if some_node_ref.borrow().is_clean() {
+ ptr.borrow_mut().hash = some_node_ref.borrow().get_hash();
+ } else {
+ let int_leaf_node = noderef_as!(some_node_ref, Internal).leaf_node.clone();
+ let int_left = noderef_as!(some_node_ref, Internal).left.clone();
+ let int_right = noderef_as!(some_node_ref, Internal).right.clone();
+
+ _commit(int_leaf_node, update_list)?;
+ _commit(int_left, update_list)?;
+ _commit(int_right, update_list)?;
+
+ some_node_ref.borrow_mut().update_hash();
+ ptr.borrow_mut().hash = some_node_ref.borrow().get_hash();
+
+ update_list.push(Box::new(move |_| {
+ noderef_as_mut!(some_node_ref, Internal).clean = true
+ }));
+ }
+ }
+ NodeKind::Leaf => {
+ let node_ref = ptr.borrow().get_node();
+ if node_ref.borrow().is_clean() {
+ ptr.borrow_mut().hash = node_ref.borrow().get_hash();
+ } else {
+ node_ref.borrow_mut().update_hash();
+ ptr.borrow_mut().hash = node_ref.borrow().get_hash();
+
+ update_list.push(Box::new(move |_| {
+ noderef_as_mut!(node_ref, Leaf).clean = true
+ }));
+ }
+ }
+ };
+
+ let closure_ptr = ptr.clone();
+ update_list.push(Box::new(move |cache| {
+ closure_ptr.borrow_mut().clean = true;
+ // Make node eligible for eviction.
+ cache.commit_node(closure_ptr.clone());
+ }));
+
+ Ok(ptr.borrow().hash)
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +
use std::mem;
+
+use anyhow::{anyhow, Result};
+
+use crate::storage::mkvs::{
+ cache::Cache,
+ tree::{Depth, Key, KeyTrait, NodeBox, NodeKind, NodePointer, NodePtrRef, Tree, Value},
+};
+
+use super::lookup::FetcherSyncGet;
+
+impl Tree {
+ /// Insert a key/value pair into the tree.
+ pub fn insert(&mut self, key: &[u8], value: &[u8]) -> Result<Option<Vec<u8>>> {
+ let pending_root = self.cache.borrow().get_pending_root();
+ let boxed_key = key.to_vec();
+ let boxed_val = value.to_vec();
+
+ // Remember where the path from root to target node ends (will end).
+ self.cache.borrow_mut().mark_position();
+
+ let (new_root, old_val) = self._insert(pending_root, 0, &boxed_key, boxed_val)?;
+ self.cache.borrow_mut().set_pending_root(new_root);
+
+ Ok(old_val)
+ }
+
+ fn _insert(
+ &mut self,
+ ptr: NodePtrRef,
+ bit_depth: Depth,
+ key: &Key,
+ val: Value,
+ ) -> Result<(NodePtrRef, Option<Value>)> {
+ let node_ref = self
+ .cache
+ .borrow_mut()
+ .deref_node_ptr(ptr.clone(), Some(FetcherSyncGet::new(key, false)))?;
+
+ let (_, key_remainder) = key.split(bit_depth, key.bit_length());
+
+ match classify_noderef!(?node_ref) {
+ NodeKind::None => {
+ return Ok((self.cache.borrow_mut().new_leaf_node(key, val), None));
+ }
+ NodeKind::Internal => {
+ let node_ref = node_ref.unwrap();
+ let (leaf_node, left, right): (NodePtrRef, NodePtrRef, NodePtrRef);
+ let cp_len: Depth;
+ let label_prefix: Key;
+ if let NodeBox::Internal(ref mut n) = *node_ref.borrow_mut() {
+ cp_len = n.label.common_prefix_len(
+ n.label_bit_length,
+ &key_remainder,
+ key.bit_length() - bit_depth,
+ );
+
+ if cp_len == n.label_bit_length {
+ // The current part of key matched the node's Label. Do recursion.
+ let r: (NodePtrRef, Option<Value>);
+ if key.bit_length() == bit_depth + n.label_bit_length {
+ // Key to insert ends exactly at this node. Add it to the
+ // existing internal node as LeafNode.
+ r = self._insert(
+ n.leaf_node.clone(),
+ bit_depth + n.label_bit_length,
+ key,
+ val,
+ )?;
+ n.leaf_node = r.0;
+ } else if key.get_bit(bit_depth + n.label_bit_length) {
+ // Insert recursively based on the bit value.
+ r = self._insert(
+ n.right.clone(),
+ bit_depth + n.label_bit_length,
+ key,
+ val,
+ )?;
+ n.right = r.0;
+ } else {
+ r = self._insert(
+ n.left.clone(),
+ bit_depth + n.label_bit_length,
+ key,
+ val,
+ )?;
+ n.left = r.0;
+ }
+
+ if !n.leaf_node.borrow().clean
+ || !n.left.borrow().clean
+ || !n.right.borrow().clean
+ {
+ n.clean = false;
+ ptr.borrow_mut().clean = false;
+ // No longer eligible for eviction as it is dirty.
+ self.cache
+ .borrow_mut()
+ .rollback_node(ptr.clone(), NodeKind::Internal);
+ }
+
+ return Ok((ptr, r.1));
+ }
+
+ // Key mismatches the label at position cp_len. Split the edge and
+ // insert new leaf.
+ let label_split = n.label.split(cp_len, n.label_bit_length);
+ label_prefix = label_split.0;
+ n.label = label_split.1;
+ n.label_bit_length -= cp_len;
+ n.clean = false;
+ ptr.borrow_mut().clean = false;
+ // No longer eligible for eviction as it is dirty.
+ self.cache
+ .borrow_mut()
+ .rollback_node(ptr.clone(), NodeKind::Internal);
+
+ let new_leaf = self.cache.borrow_mut().new_leaf_node(key, val);
+ if key.bit_length() - bit_depth == cp_len {
+ // The key is a prefix of existing path.
+ leaf_node = new_leaf;
+ if n.label.get_bit(0) {
+ left = NodePointer::null_ptr();
+ right = ptr;
+ } else {
+ left = ptr;
+ right = NodePointer::null_ptr();
+ }
+ } else {
+ leaf_node = NodePointer::null_ptr();
+ if key_remainder.get_bit(cp_len) {
+ left = ptr;
+ right = new_leaf;
+ } else {
+ left = new_leaf;
+ right = ptr;
+ }
+ }
+ } else {
+ return Err(anyhow!(
+ "insert.rs: unknown internal node_ref {:?}",
+ node_ref
+ ));
+ }
+
+ return Ok((
+ self.cache.borrow_mut().new_internal_node(
+ &label_prefix,
+ cp_len,
+ leaf_node,
+ left,
+ right,
+ ),
+ None,
+ ));
+ }
+ NodeKind::Leaf => {
+ // If the key matches, we can just update the value.
+ let node_ref = node_ref.unwrap();
+ let (leaf_node, left, right): (NodePtrRef, NodePtrRef, NodePtrRef);
+ let cp_len: Depth;
+ let label_prefix: Key;
+ if let NodeBox::Leaf(ref mut n) = *node_ref.borrow_mut() {
+ // Should always succeed.
+ if n.key == *key {
+ // If the key matches, we can just update the value.
+ if n.value == val {
+ return Ok((ptr, Some(val)));
+ }
+ let old_val = mem::replace(&mut n.value, val);
+ n.clean = false;
+ ptr.borrow_mut().clean = false;
+ // No longer eligible for eviction as it is dirty.
+ self.cache
+ .borrow_mut()
+ .rollback_node(ptr.clone(), NodeKind::Leaf);
+ return Ok((ptr, Some(old_val)));
+ }
+
+ let (_, leaf_key_remainder) = n.key.split(bit_depth, n.key.bit_length());
+ cp_len = leaf_key_remainder.common_prefix_len(
+ n.key.bit_length() - bit_depth,
+ &key_remainder,
+ key.bit_length() - bit_depth,
+ );
+
+ // Key mismatches the label at position cp_len. Split the edge.
+ label_prefix = leaf_key_remainder
+ .split(cp_len, leaf_key_remainder.bit_length())
+ .0;
+ let new_leaf = self.cache.borrow_mut().new_leaf_node(key, val);
+
+ if key.bit_length() - bit_depth == cp_len {
+ // Inserted key is a prefix of the label.
+ leaf_node = new_leaf;
+ if leaf_key_remainder.get_bit(cp_len) {
+ left = NodePointer::null_ptr();
+ right = ptr;
+ } else {
+ left = ptr;
+ right = NodePointer::null_ptr();
+ }
+ } else if n.key.bit_length() - bit_depth == cp_len {
+ // Label is a prefix of the inserted key.
+ leaf_node = ptr;
+ if key_remainder.get_bit(cp_len) {
+ left = NodePointer::null_ptr();
+ right = new_leaf;
+ } else {
+ left = new_leaf;
+ right = NodePointer::null_ptr();
+ }
+ } else {
+ leaf_node = NodePointer::null_ptr();
+ if key_remainder.get_bit(cp_len) {
+ left = ptr;
+ right = new_leaf;
+ } else {
+ left = new_leaf;
+ right = ptr;
+ }
+ }
+ } else {
+ return Err(anyhow!("insert.rs: invalid leaf node_ref {:?}", node_ref));
+ }
+
+ let new_internal = self.cache.borrow_mut().new_internal_node(
+ &label_prefix,
+ cp_len,
+ leaf_node,
+ left,
+ right,
+ );
+ Ok((new_internal, None))
+ }
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +
//! Tree iterator.
+use std::{collections::VecDeque, fmt};
+
+use anyhow::{Error, Result};
+
+use crate::storage::mkvs::{
+ self,
+ cache::{Cache, ReadSyncFetcher},
+ sync::{IterateRequest, Proof, ReadSync, TreeID},
+ tree::{Depth, Key, KeyTrait, NodeBox, NodeKind, NodePtrRef, Root, Tree},
+};
+
+pub(super) struct FetcherSyncIterate<'a> {
+ key: &'a Key,
+ prefetch: usize,
+}
+
+impl<'a> FetcherSyncIterate<'a> {
+ pub(super) fn new(key: &'a Key, prefetch: usize) -> Self {
+ Self { key, prefetch }
+ }
+}
+
+impl<'a> ReadSyncFetcher for FetcherSyncIterate<'a> {
+ fn fetch(&self, root: Root, ptr: NodePtrRef, rs: &mut Box<dyn ReadSync>) -> Result<Proof> {
+ let rsp = rs.sync_iterate(IterateRequest {
+ tree: TreeID {
+ root,
+ position: ptr.borrow().hash,
+ },
+ key: self.key.clone(),
+ prefetch: self.prefetch as u16,
+ })?;
+ Ok(rsp.proof)
+ }
+}
+
+/// Visit state of a node.
+#[derive(Debug, PartialEq)]
+enum VisitState {
+ Before,
+ At,
+ AtLeft,
+ After,
+}
+
+/// Atom in the current iterator path. Can be used to resume iteration
+/// from a given position.
+struct PathAtom {
+ ptr: NodePtrRef,
+ bit_depth: Depth,
+ path: Key,
+ state: VisitState,
+}
+
+impl fmt::Debug for PathAtom {
+ fn fmt(&self, f: &mut fmt::Formatter) -> std::result::Result<(), fmt::Error> {
+ f.debug_struct("PathAtom")
+ .field("bit_depth", &self.bit_depth)
+ .field("path", &self.path)
+ .field("state", &self.state)
+ .finish()
+ }
+}
+
+/// Tree iterator.
+pub struct TreeIterator<'tree> {
+ tree: &'tree Tree,
+ prefetch: usize,
+ pos: VecDeque<PathAtom>,
+ key: Option<Key>,
+ value: Option<Vec<u8>>,
+ error: Option<Error>,
+}
+
+impl<'tree> TreeIterator<'tree> {
+ /// Create a new tree iterator.
+ fn new(tree: &'tree Tree) -> Self {
+ Self {
+ tree,
+ prefetch: 0,
+ pos: VecDeque::new(),
+ key: None,
+ value: None,
+ error: None,
+ }
+ }
+
+ fn reset(&mut self) {
+ self.pos.clear();
+ self.key = None;
+ self.value = None;
+ }
+
+ fn next(&mut self) {
+ if self.error.is_some() {
+ return;
+ }
+
+ while !self.pos.is_empty() {
+ // Start where we left off.
+ let atom = self.pos.pop_front().expect("not empty");
+ let mut remainder = std::mem::take(&mut self.pos);
+
+ // Remember where the path from root to target node ends (will end).
+ let mut cache = self.tree.cache.borrow_mut();
+ cache.mark_position();
+ for atom in &remainder {
+ cache.use_node(atom.ptr.clone());
+ }
+ drop(cache);
+
+ // Try to proceed with the current node. If we don't succeed, proceed to the
+ // next node.
+ let key = self.key.take().expect("iterator is valid");
+ self.reset();
+ if let Err(error) =
+ self._next(atom.ptr, atom.bit_depth, atom.path, key.clone(), atom.state)
+ {
+ self.error = Some(error);
+ self.reset();
+ return;
+ }
+ if self.key.is_some() {
+ // Key has been found.
+ self.pos.append(&mut remainder);
+ return;
+ }
+
+ self.key = Some(key);
+ self.pos = remainder;
+ }
+
+ // We have reached the end of the tree, make sure everything is reset.
+ self.key = None;
+ self.value = None;
+ }
+
+ fn _next(
+ &mut self,
+ ptr: NodePtrRef,
+ bit_depth: Depth,
+ path: Key,
+ mut key: Key,
+ mut state: VisitState,
+ ) -> Result<()> {
+ let node_ref = self.tree.cache.borrow_mut().deref_node_ptr(
+ ptr.clone(),
+ Some(FetcherSyncIterate::new(&key, self.prefetch)),
+ )?;
+
+ match classify_noderef!(?node_ref) {
+ NodeKind::None => {
+ // Reached a nil node, there is nothing here.
+ Ok(())
+ }
+ NodeKind::Internal => {
+ let node_ref = node_ref.unwrap();
+ if let NodeBox::Internal(ref n) = *node_ref.borrow() {
+ // Internal node.
+ let bit_length = bit_depth + n.label_bit_length;
+ let new_path = path.merge(bit_depth, &n.label, n.label_bit_length);
+
+ // Check if the key is longer than the current path but lexicographically smaller. In this
+ // case everything in this subtree will be larger so we need to take the first value.
+ let take_first =
+ bit_length > 0 && key.bit_length() >= bit_length && key < new_path;
+
+ // Does lookup key end here? Look into LeafNode.
+ if (state == VisitState::Before
+ && (key.bit_length() <= bit_length || take_first))
+ || state == VisitState::At
+ {
+ if state == VisitState::Before {
+ self._next(
+ n.leaf_node.clone(),
+ bit_length,
+ path.clone(),
+ key.clone(),
+ VisitState::Before,
+ )?;
+ if self.key.is_some() {
+ // Key has been found.
+ self.pos.push_back(PathAtom {
+ ptr,
+ bit_depth,
+ path,
+ state: VisitState::At,
+ });
+ return Ok(());
+ }
+ }
+ // Key has not been found, continue with search for next key.
+ if key.bit_length() <= bit_length {
+ key = key.append_bit(bit_length, false);
+ }
+ }
+
+ if state == VisitState::Before {
+ state = VisitState::At;
+ }
+
+ // Continue recursively based on a bit value.
+ if (state == VisitState::At && (!key.get_bit(bit_length) || take_first))
+ || state == VisitState::AtLeft
+ {
+ if state == VisitState::At {
+ self._next(
+ n.left.clone(),
+ bit_length,
+ new_path.append_bit(bit_length, false),
+ key.clone(),
+ VisitState::Before,
+ )?;
+ if self.key.is_some() {
+ // Key has been found.
+ self.pos.push_back(PathAtom {
+ ptr,
+ bit_depth,
+ path,
+ state: VisitState::AtLeft,
+ });
+ return Ok(());
+ }
+ }
+ // Key has not been found, continue with search for next key.
+ key = key.split(bit_length, key.bit_length()).0;
+ key = key.append_bit(bit_length, true);
+ }
+
+ if state == VisitState::At || state == VisitState::AtLeft {
+ self._next(
+ n.right.clone(),
+ bit_length,
+ new_path.append_bit(bit_length, true),
+ key,
+ VisitState::Before,
+ )?;
+ if self.key.is_some() {
+ // Key has been found.
+ self.pos.push_back(PathAtom {
+ ptr,
+ bit_depth,
+ path,
+ state: VisitState::After,
+ });
+ return Ok(());
+ }
+ }
+
+ return Ok(());
+ }
+
+ unreachable!("node kind is internal node");
+ }
+ NodeKind::Leaf => {
+ // Reached a leaf node.
+ let node_ref = node_ref.unwrap();
+ if let NodeBox::Leaf(ref n) = *node_ref.borrow() {
+ if n.key >= key {
+ self.key = Some(n.key.clone());
+ self.value = Some(n.value.clone());
+ }
+ } else {
+ unreachable!("node kind is leaf node");
+ }
+
+ Ok(())
+ }
+ }
+ }
+}
+
+impl<'tree> Iterator for TreeIterator<'tree> {
+ type Item = (Vec<u8>, Vec<u8>);
+
+ fn next(&mut self) -> Option<Self::Item> {
+ use mkvs::Iterator;
+
+ if !self.is_valid() {
+ return None;
+ }
+
+ let key = self.key.as_ref().expect("iterator is valid").clone();
+ let value = self.value.as_ref().expect("iterator is valid").clone();
+ TreeIterator::next(self);
+
+ Some((key, value))
+ }
+}
+
+impl<'tree> mkvs::Iterator for TreeIterator<'tree> {
+ fn set_prefetch(&mut self, prefetch: usize) {
+ self.prefetch = prefetch;
+ }
+
+ fn is_valid(&self) -> bool {
+ self.key.is_some()
+ }
+
+ fn error(&self) -> &Option<Error> {
+ &self.error
+ }
+
+ fn rewind(&mut self) {
+ self.seek(&[])
+ }
+
+ fn seek(&mut self, key: &[u8]) {
+ if self.error.is_some() {
+ return;
+ }
+
+ self.reset();
+ let pending_root = self.tree.cache.borrow().get_pending_root();
+ if let Err(error) = self._next(
+ pending_root,
+ 0,
+ Key::new(),
+ key.to_vec(),
+ VisitState::Before,
+ ) {
+ self.error = Some(error);
+ self.reset();
+ }
+ }
+
+ fn get_key(&self) -> &Option<Key> {
+ &self.key
+ }
+
+ fn get_value(&self) -> &Option<Vec<u8>> {
+ &self.value
+ }
+
+ fn next(&mut self) {
+ TreeIterator::next(self)
+ }
+}
+
+impl Tree {
+ /// Return an iterator over the tree.
+ pub fn iter(&self) -> TreeIterator {
+ TreeIterator::new(self)
+ }
+}
+
+#[cfg(test)]
+pub(super) mod test {
+ use std::iter;
+
+ use rustc_hex::FromHex;
+
+ use super::{super::tree_test::generate_key_value_pairs_ex, *};
+ use crate::storage::mkvs::{
+ interop::{Driver, ProtocolServer},
+ sync::{NoopReadSyncer, StatsCollector},
+ Iterator, OverlayTree, RootType,
+ };
+
+ #[test]
+ fn test_iterator() {
+ let server = ProtocolServer::new(None);
+
+ let mut tree = Tree::builder()
+ .with_root_type(RootType::State)
+ .build(Box::new(NoopReadSyncer));
+
+ // Test with an empty tree.
+ let mut it = tree.iter();
+ it.rewind();
+ assert!(
+ !it.is_valid(),
+ "iterator should be invalid on an empty tree"
+ );
+
+ // Test with one item.
+ tree.insert(b"key", b"first").unwrap();
+ let mut it = tree.iter();
+ it.rewind();
+ assert!(
+ it.is_valid(),
+ "iterator should be valid on a non-empty tree"
+ );
+
+ // Insert some items.
+ let items = vec![
+ (b"key".to_vec(), b"first".to_vec()),
+ (b"key 1".to_vec(), b"one".to_vec()),
+ (b"key 2".to_vec(), b"two".to_vec()),
+ (b"key 5".to_vec(), b"five".to_vec()),
+ (b"key 8".to_vec(), b"eight".to_vec()),
+ (b"key 9".to_vec(), b"nine".to_vec()),
+ ];
+ for (key, value) in items.iter() {
+ tree.insert(key, value).unwrap();
+ }
+
+ let tests = vec![
+ (b"k".to_vec(), 0),
+ (b"key 1".to_vec(), 1),
+ (b"key 3".to_vec(), 3),
+ (b"key 4".to_vec(), 3),
+ (b"key 5".to_vec(), 3),
+ (b"key 6".to_vec(), 4),
+ (b"key 7".to_vec(), 4),
+ (b"key 8".to_vec(), 4),
+ (b"key 9".to_vec(), 5),
+ (b"key A".to_vec(), -1),
+ ];
+
+ // Direct.
+ let it = tree.iter();
+ test_iterator_with(&items, it, &tests);
+
+ // Remote.
+ let hash = tree.commit(Default::default(), 0).expect("commit");
+ let write_log = items
+ .iter()
+ .cloned()
+ .map(|(key, value)| mkvs::LogEntry {
+ key,
+ value: Some(value),
+ })
+ .collect();
+ server.apply(&write_log, hash, Default::default(), 0);
+
+ let remote_tree = Tree::builder()
+ .with_capacity(0, 0)
+ .with_root(Root {
+ root_type: RootType::State,
+ hash,
+ ..Default::default()
+ })
+ .build(server.read_sync());
+
+ let it = remote_tree.iter();
+ test_iterator_with(&items, it, &tests);
+
+ // Remote with prefetch (10).
+ let stats = StatsCollector::new(server.read_sync());
+ let remote_tree = Tree::builder()
+ .with_capacity(0, 0)
+ .with_root(Root {
+ root_type: RootType::State,
+ hash,
+ ..Default::default()
+ })
+ .build(Box::new(stats));
+
+ let mut it = remote_tree.iter();
+ it.set_prefetch(10);
+ test_iterator_with(&items, it, &tests);
+
+ let cache = remote_tree.cache.borrow();
+ let stats = cache
+ .get_read_syncer()
+ .as_any()
+ .downcast_ref::<StatsCollector>()
+ .expect("stats");
+ assert_eq!(0, stats.sync_get_count, "sync_get_count");
+ assert_eq!(0, stats.sync_get_prefixes_count, "sync_get_prefixes_count");
+ assert_eq!(1, stats.sync_iterate_count, "sync_iterate_count");
+
+ // Remote with prefetch (3).
+ let stats = StatsCollector::new(server.read_sync());
+ let remote_tree = Tree::builder()
+ .with_capacity(0, 0)
+ .with_root(Root {
+ root_type: RootType::State,
+ hash,
+ ..Default::default()
+ })
+ .build(Box::new(stats));
+
+ let mut it = remote_tree.iter();
+ it.set_prefetch(3);
+ test_iterator_with(&items, it, &tests);
+
+ let cache = remote_tree.cache.borrow();
+ let stats = cache
+ .get_read_syncer()
+ .as_any()
+ .downcast_ref::<StatsCollector>()
+ .expect("stats");
+ assert_eq!(0, stats.sync_get_count, "sync_get_count");
+ assert_eq!(0, stats.sync_get_prefixes_count, "sync_get_prefixes_count");
+ assert_eq!(2, stats.sync_iterate_count, "sync_iterate_count");
+ }
+
+ #[test]
+ fn test_iterator_case1() {
+ let mut tree = Tree::builder()
+ .with_root_type(RootType::State)
+ .build(Box::new(NoopReadSyncer));
+
+ let items = vec![
+ (b"key 5".to_vec(), b"fivey".to_vec()),
+ (b"key 7".to_vec(), b"seven".to_vec()),
+ ];
+ for (key, value) in items.iter() {
+ tree.insert(key, value).unwrap();
+ }
+
+ let tests = vec![(b"key 3".to_vec(), 0)];
+
+ let it = tree.iter();
+ test_iterator_with(&items, it, &tests);
+ }
+
+ #[test]
+ fn test_iterator_case2() {
+ let mut tree = Tree::builder()
+ .with_root_type(RootType::State)
+ .build(Box::new(NoopReadSyncer));
+
+ let items: Vec<(Vec<u8>, Vec<u8>)> = vec![
+ (
+ "54dcb497eb46bc7cb1a1a29d143d5d41f1a684c97e12f2ae536eceb828c15fc34c02"
+ .from_hex()
+ .unwrap(),
+ b"value".to_vec(),
+ ),
+ (
+ "54dcb497eb46bc7cb1a1a29d143d5d41f1a684c97e12f2ae536eceb828c15fc34c02"
+ .from_hex()
+ .unwrap(),
+ b"value".to_vec(),
+ ),
+ ];
+ for (key, value) in items.iter() {
+ tree.insert(key, value).unwrap();
+ }
+
+ let mut it = tree.iter();
+ let missing_key: Vec<u8> =
+ "54da85be3251772db943cba67341d402117c87ada2a9e8aad7171d40b6b4dc9fbc"
+ .from_hex()
+ .unwrap();
+ it.seek(&missing_key);
+ assert!(it.is_valid(), "iterator should be valid");
+ let item = iter::Iterator::next(&mut it);
+ assert_eq!(
+ Some((items[0].0.clone(), b"value".to_vec())),
+ item,
+ "value should be correct"
+ );
+ }
+
+ #[test]
+ fn test_iterator_eviction() {
+ let server = ProtocolServer::new(None);
+
+ let mut tree = OverlayTree::new(
+ Tree::builder()
+ .with_capacity(0, 0)
+ .with_root_type(RootType::State)
+ .build(Box::new(NoopReadSyncer)),
+ );
+
+ let (keys, values) = generate_key_value_pairs_ex("T".to_owned(), 100);
+ let items: Vec<(Vec<u8>, Vec<u8>)> = keys.into_iter().zip(values.into_iter()).collect();
+ for (key, value) in &items {
+ tree.insert(&key, &value).unwrap();
+ }
+
+ let (write_log, hash) = tree.commit_both(Default::default(), 0).expect("commit");
+ server.apply(&write_log, hash, Default::default(), 0);
+
+ // Create a remote tree with limited cache capacity so that nodes will
+ // be evicted while iterating.
+ let stats = StatsCollector::new(server.read_sync());
+ let remote_tree = Tree::builder()
+ .with_capacity(50, 16 * 1024 * 1024)
+ .with_root(Root {
+ root_type: RootType::State,
+ hash,
+ ..Default::default()
+ })
+ .build(Box::new(stats));
+
+ let mut it = remote_tree.iter();
+ it.set_prefetch(1000);
+ test_iterator_with(&items, it, &vec![]);
+
+ let cache = remote_tree.cache.borrow();
+ let stats = cache
+ .get_read_syncer()
+ .as_any()
+ .downcast_ref::<StatsCollector>()
+ .expect("stats");
+ assert_eq!(0, stats.sync_get_count, "sync_get_count");
+ assert_eq!(0, stats.sync_get_prefixes_count, "sync_get_prefixes_count");
+ // We require multiple fetches as we can only store a limited amount of
+ // results per fetch due to the cache being too small.
+ assert_eq!(2, stats.sync_iterate_count, "sync_iterate_count");
+ }
+
+ pub(in super::super) fn test_iterator_with<I: mkvs::Iterator>(
+ items: &[(Vec<u8>, Vec<u8>)],
+ mut it: I,
+ tests: &[(Vec<u8>, isize)],
+ ) {
+ // Iterate through the whole tree.
+ let mut iterations = 0;
+ it.rewind();
+ for (idx, (key, value)) in it.by_ref().enumerate() {
+ if !tests.is_empty() {
+ assert_eq!(items[idx].0, key, "iterator should have the correct key");
+ assert_eq!(
+ items[idx].1, value,
+ "iterator should have the correct value"
+ );
+ }
+ iterations += 1;
+ }
+ assert!(it.error().is_none(), "iterator should not error");
+ assert_eq!(iterations, items.len(), "iterator should go over all items");
+
+ for (seek, pos) in tests {
+ it.seek(&seek);
+ if *pos == -1 {
+ assert!(!it.is_valid(), "iterator should not be valid after seek");
+ continue;
+ }
+
+ for expected in &items[*pos as usize..] {
+ let item = iter::Iterator::next(&mut it);
+ assert_eq!(
+ Some(expected.clone()),
+ item,
+ "iterator should have the correct item"
+ );
+ }
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +
use anyhow::Result;
+
+use crate::storage::mkvs::{
+ cache::{Cache, ReadSyncFetcher},
+ sync::{GetRequest, Proof, ProofBuilder, ReadSync, TreeID},
+ tree::{Depth, Key, KeyTrait, NodeBox, NodeKind, NodePtrRef, Root, Tree, Value},
+};
+
+pub(super) struct FetcherSyncGet<'a> {
+ key: &'a Key,
+ include_siblings: bool,
+}
+
+impl<'a> FetcherSyncGet<'a> {
+ pub(super) fn new(key: &'a Key, include_siblings: bool) -> Self {
+ Self {
+ key,
+ include_siblings,
+ }
+ }
+}
+
+impl<'a> ReadSyncFetcher for FetcherSyncGet<'a> {
+ fn fetch(&self, root: Root, ptr: NodePtrRef, rs: &mut Box<dyn ReadSync>) -> Result<Proof> {
+ let rsp = rs.sync_get(GetRequest {
+ tree: TreeID {
+ root,
+ position: ptr.borrow().hash,
+ },
+ key: self.key.clone(),
+ include_siblings: self.include_siblings,
+ })?;
+ Ok(rsp.proof)
+ }
+}
+
+impl Tree {
+ /// Get an existing key.
+ pub fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>> {
+ self._get_top(key, false)
+ }
+
+ pub fn get_proof(&self, key: &[u8]) -> Result<Option<Proof>> {
+ let boxed_key = key.to_vec();
+ let pending_root = self.cache.borrow().get_pending_root();
+
+ // Remember where the path from root to target node ends (will end).
+ self.cache.borrow_mut().mark_position();
+
+ let mut proof_builder = ProofBuilder::new(pending_root.as_ref().borrow().hash);
+
+ let result = self._get(pending_root, 0, &boxed_key, false, Some(&mut proof_builder))?;
+ match result {
+ Some(_) => Ok(Some(proof_builder.build())),
+ None => Ok(None),
+ }
+ }
+
+ /// Check if the key exists in the local cache.
+ pub fn cache_contains_key(&self, key: &[u8]) -> bool {
+ match self._get_top(key, true) {
+ Ok(Some(_)) => true,
+ Ok(None) => false,
+ Err(_) => false,
+ }
+ }
+
+ fn _get_top(&self, key: &[u8], check_only: bool) -> Result<Option<Vec<u8>>> {
+ let boxed_key = key.to_vec();
+ let pending_root = self.cache.borrow().get_pending_root();
+
+ // Remember where the path from root to target node ends (will end).
+ self.cache.borrow_mut().mark_position();
+
+ self._get(pending_root, 0, &boxed_key, check_only, None)
+ }
+
+ fn _get(
+ &self,
+ ptr: NodePtrRef,
+ bit_depth: Depth,
+ key: &Key,
+ check_only: bool,
+ mut proof_builder: Option<&mut ProofBuilder>,
+ ) -> Result<Option<Value>> {
+ let node_ref = self.cache.borrow_mut().deref_node_ptr(
+ ptr,
+ if check_only {
+ None
+ } else {
+ Some(FetcherSyncGet::new(key, false))
+ },
+ )?;
+
+ // Include nodes in proof if we have a proof builder.
+ if let (Some(pb), Some(node_ref)) = (proof_builder.as_mut(), &node_ref) {
+ pb.include(&node_ref.borrow());
+ }
+
+ match classify_noderef!(?node_ref) {
+ NodeKind::None => {
+ // Reached a nil node, there is nothing here.
+ Ok(None)
+ }
+ NodeKind::Internal => {
+ let node_ref = node_ref.unwrap();
+ if let NodeBox::Internal(ref mut n) = *node_ref.borrow_mut() {
+ // Internal node.
+ // Does lookup key end here? Look into LeafNode.
+ if key.bit_length() == bit_depth + n.label_bit_length {
+ return self._get(
+ n.leaf_node.clone(),
+ bit_depth + n.label_bit_length,
+ key,
+ check_only,
+ proof_builder,
+ );
+ }
+
+ // Lookup key is too short for the current n.Label. It's not stored.
+ if key.bit_length() < bit_depth + n.label_bit_length {
+ return Ok(None);
+ }
+
+ // Continue recursively based on a bit value.
+ if key.get_bit(bit_depth + n.label_bit_length) {
+ return self._get(
+ n.right.clone(),
+ bit_depth + n.label_bit_length,
+ key,
+ check_only,
+ proof_builder,
+ );
+ } else {
+ return self._get(
+ n.left.clone(),
+ bit_depth + n.label_bit_length,
+ key,
+ check_only,
+ proof_builder,
+ );
+ }
+ }
+
+ unreachable!("node kind is internal node");
+ }
+ NodeKind::Leaf => {
+ // Reached a leaf node, check if key matches.
+ let node_ref = node_ref.unwrap();
+ if noderef_as!(node_ref, Leaf).key == *key {
+ Ok(Some(noderef_as!(node_ref, Leaf).value.clone()))
+ } else {
+ Ok(None)
+ }
+ }
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +
#[macro_export]
+macro_rules! classify_noderef {
+ (? $e:expr) => {{
+ let kind = match $e {
+ None => NodeKind::None,
+ Some(ref node) => classify_noderef!(node),
+ };
+ kind
+ }};
+ ($e:expr) => {{
+ // Ensure references don't leak outside this macro.
+ let kind = match *$e.borrow() {
+ NodeBox::Internal(_) => NodeKind::Internal,
+ NodeBox::Leaf(_) => NodeKind::Leaf,
+ };
+ kind
+ }};
+}
+
+#[macro_export]
+macro_rules! noderef_as {
+ ($ref:expr, $type:ident) => {
+ match *$ref.borrow() {
+ NodeBox::$type(ref deref) => deref,
+ _ => unreachable!(),
+ }
+ };
+}
+
+#[macro_export]
+macro_rules! noderef_as_mut {
+ ($ref:expr, $type:ident) => {
+ match *$ref.borrow_mut() {
+ NodeBox::$type(ref mut deref) => deref,
+ _ => unreachable!(),
+ }
+ };
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +
use std::{cell::RefCell, mem::size_of, rc::Rc};
+
+use anyhow::Result;
+
+use crate::{
+ common::crypto::hash::Hash,
+ storage::mkvs::{
+ marshal::Marshal,
+ tree::{
+ Depth, DepthTrait, InternalNode, Key, LeafNode, Node, NodeBox, NodeKind, NodePointer,
+ TreeError, Value,
+ },
+ },
+};
+
+/// Size of the encoded value length.
+const VALUE_LENGTH_SIZE: usize = size_of::<u32>();
+
+impl NodeBox {
+ pub fn compact_marshal_binary(&self, v: u16) -> Result<Vec<u8>> {
+ match self {
+ NodeBox::Internal(ref n) => n.compact_marshal_binary(v),
+ NodeBox::Leaf(ref n) => n.compact_marshal_binary(),
+ }
+ }
+}
+
+impl InternalNode {
+ pub fn compact_marshal_binary(&self, v: u16) -> Result<Vec<u8>> {
+ match v {
+ 0 => {
+ // In version 0 of compact serialization, leaf node is included in the internal
+ // nodes serialization.
+ let leaf_node_binary = if self.leaf_node.borrow().is_null() {
+ vec![NodeKind::None as u8]
+ } else {
+ noderef_as!(self.leaf_node.borrow().get_node(), Leaf).marshal_binary()?
+ };
+
+ let mut result: Vec<u8> = Vec::with_capacity(
+ 1 + size_of::<u16>() + self.label.len() + leaf_node_binary.len(),
+ );
+ result.push(NodeKind::Internal as u8);
+ result.append(&mut self.label_bit_length.marshal_binary()?);
+ result.extend_from_slice(&self.label);
+ result.extend_from_slice(leaf_node_binary.as_ref());
+
+ Ok(result)
+ }
+ 1 => {
+ // In version 1 of compact serialization, leaf node is not included.
+ let mut result: Vec<u8> =
+ Vec::with_capacity(1 + size_of::<u16>() + self.label.len() + 1);
+ result.push(NodeKind::Internal as u8);
+ result.append(&mut self.label_bit_length.marshal_binary()?);
+ result.extend_from_slice(&self.label);
+ result.push(NodeKind::None as u8);
+
+ Ok(result)
+ }
+ _ => panic!("unsupported compact serialization version: {:?}", v),
+ }
+ }
+}
+
+impl Marshal for NodeBox {
+ fn marshal_binary(&self) -> Result<Vec<u8>> {
+ match self {
+ NodeBox::Internal(ref n) => n.marshal_binary(),
+ NodeBox::Leaf(ref n) => n.marshal_binary(),
+ }
+ }
+
+ fn unmarshal_binary(&mut self, data: &[u8]) -> Result<usize> {
+ if data.is_empty() {
+ Err(TreeError::MalformedNode.into())
+ } else {
+ let mut kind = NodeKind::None;
+ kind.unmarshal_binary(data)?;
+ match kind {
+ NodeKind::Internal => {
+ *self = NodeBox::Internal(InternalNode {
+ ..Default::default()
+ });
+ }
+ NodeKind::Leaf => {
+ *self = NodeBox::Leaf(LeafNode {
+ ..Default::default()
+ });
+ }
+ _ => {
+ return Err(TreeError::MalformedNode.into());
+ }
+ };
+ match self {
+ NodeBox::Internal(ref mut n) => n.unmarshal_binary(data),
+ NodeBox::Leaf(ref mut n) => n.unmarshal_binary(data),
+ }
+ }
+ }
+}
+
+impl Marshal for NodeKind {
+ fn marshal_binary(&self) -> Result<Vec<u8>> {
+ Ok(vec![*self as u8])
+ }
+
+ fn unmarshal_binary(&mut self, data: &[u8]) -> Result<usize> {
+ if data.is_empty() {
+ Err(TreeError::MalformedNode.into())
+ } else {
+ if data[0] == NodeKind::None as u8 {
+ *self = NodeKind::None;
+ } else if data[0] == NodeKind::Internal as u8 {
+ *self = NodeKind::Internal;
+ } else if data[0] == NodeKind::Leaf as u8 {
+ *self = NodeKind::Leaf;
+ } else {
+ return Err(TreeError::MalformedNode.into());
+ }
+ Ok(1)
+ }
+ }
+}
+
+impl Marshal for InternalNode {
+ fn marshal_binary(&self) -> Result<Vec<u8>> {
+ let leaf_node_binary = if self.leaf_node.borrow().is_null() {
+ vec![NodeKind::None as u8]
+ } else {
+ noderef_as!(self.leaf_node.borrow().get_node(), Leaf).marshal_binary()?
+ };
+
+ let mut result: Vec<u8> = Vec::with_capacity(
+ 1 + size_of::<u16>() + self.label.len() + leaf_node_binary.len() + Hash::len() * 2,
+ );
+ result.push(NodeKind::Internal as u8);
+ result.append(&mut self.label_bit_length.marshal_binary()?);
+ result.extend_from_slice(&self.label);
+ result.extend_from_slice(leaf_node_binary.as_ref());
+ result.extend_from_slice(self.left.borrow().hash.as_ref());
+ result.extend_from_slice(self.right.borrow().hash.as_ref());
+
+ Ok(result)
+ }
+
+ fn unmarshal_binary(&mut self, data: &[u8]) -> Result<usize> {
+ let mut pos = 0;
+ if data.len() < 1 + size_of::<Depth>() + 1 || data[pos] != NodeKind::Internal as u8 {
+ return Err(TreeError::MalformedNode.into());
+ }
+ pos += 1;
+
+ pos += self.label_bit_length.unmarshal_binary(&data[pos..])?;
+ self.label = vec![0; self.label_bit_length.to_bytes()];
+ if pos + self.label_bit_length.to_bytes() > data.len() {
+ return Err(TreeError::MalformedNode.into());
+ }
+ self.label
+ .clone_from_slice(&data[pos..pos + self.label_bit_length.to_bytes()]);
+ pos += self.label_bit_length.to_bytes();
+ if pos >= data.len() {
+ return Err(TreeError::MalformedNode.into());
+ }
+
+ if data[pos] == NodeKind::None as u8 {
+ self.leaf_node = NodePointer::null_ptr();
+ pos += 1;
+ } else {
+ let mut leaf_node = LeafNode {
+ ..Default::default()
+ };
+ pos += leaf_node.unmarshal_binary(&data[pos..])?;
+ self.leaf_node = Rc::new(RefCell::new(NodePointer {
+ clean: true,
+ hash: leaf_node.get_hash(),
+ node: Some(Rc::new(RefCell::new(NodeBox::Leaf(leaf_node)))),
+ ..Default::default()
+ }));
+ };
+
+ // Hashes are only present in non-compact serialization.
+ if data.len() >= pos + Hash::len() * 2 {
+ let left_hash = Hash::from(&data[pos..pos + Hash::len()]);
+ pos += Hash::len();
+ let right_hash = Hash::from(&data[pos..pos + Hash::len()]);
+ pos += Hash::len();
+
+ if left_hash.is_empty() {
+ self.left = NodePointer::null_ptr();
+ } else {
+ self.left = Rc::new(RefCell::new(NodePointer {
+ clean: true,
+ hash: left_hash,
+ node: None,
+ ..Default::default()
+ }));
+ }
+ if right_hash.is_empty() {
+ self.right = NodePointer::null_ptr();
+ } else {
+ self.right = Rc::new(RefCell::new(NodePointer {
+ clean: true,
+ hash: right_hash,
+ node: None,
+ ..Default::default()
+ }));
+ }
+
+ self.update_hash();
+ }
+
+ self.clean = true;
+
+ Ok(pos)
+ }
+}
+
+impl LeafNode {
+ pub fn compact_marshal_binary(&self) -> Result<Vec<u8>> {
+ let mut result: Vec<u8> = Vec::with_capacity(1 + VALUE_LENGTH_SIZE);
+ result.push(NodeKind::Leaf as u8);
+ result.append(&mut self.key.marshal_binary()?);
+ result.append(&mut (self.value.len() as u32).marshal_binary()?);
+ result.extend_from_slice(&self.value);
+
+ Ok(result)
+ }
+}
+
+impl Marshal for LeafNode {
+ fn marshal_binary(&self) -> Result<Vec<u8>> {
+ self.compact_marshal_binary()
+ }
+
+ fn unmarshal_binary(&mut self, data: &[u8]) -> Result<usize> {
+ if data.len() < 1 + size_of::<Depth>() + VALUE_LENGTH_SIZE
+ || data[0] != NodeKind::Leaf as u8
+ {
+ return Err(TreeError::MalformedNode.into());
+ }
+
+ self.clean = true;
+
+ let mut pos = 1;
+ self.key = Key::new();
+ let key_len = self.key.unmarshal_binary(&data[pos..])?;
+ pos += key_len;
+ if pos + VALUE_LENGTH_SIZE > data.len() {
+ return Err(TreeError::MalformedNode.into());
+ }
+
+ self.value = Value::new();
+ let mut value_len = 0u32;
+ value_len.unmarshal_binary(&data[pos..(pos + VALUE_LENGTH_SIZE)])?;
+ pos += VALUE_LENGTH_SIZE;
+ if pos + (value_len as usize) > data.len() {
+ return Err(TreeError::MalformedNode.into());
+ }
+
+ self.value
+ .extend_from_slice(&data[pos..(pos + value_len as usize)]);
+ pos += value_len as usize;
+
+ self.update_hash();
+
+ Ok(pos)
+ }
+}
+
+impl Marshal for Key {
+ fn marshal_binary(&self) -> Result<Vec<u8>> {
+ let mut result: Vec<u8> = Vec::new();
+ result.append(&mut (self.len() as Depth).marshal_binary()?);
+ result.extend_from_slice(self);
+ Ok(result)
+ }
+
+ fn unmarshal_binary(&mut self, data: &[u8]) -> Result<usize> {
+ if data.len() < size_of::<Depth>() {
+ return Err(TreeError::MalformedKey.into());
+ }
+ let mut key_len: Depth = 0;
+ key_len.unmarshal_binary(data)?;
+
+ if data.len() < size_of::<Depth>() + key_len as usize {
+ return Err(TreeError::MalformedKey.into());
+ }
+
+ self.extend_from_slice(&data[size_of::<Depth>()..(size_of::<Depth>() + key_len as usize)]);
+ Ok(size_of::<Depth>() + key_len as usize)
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +
#[macro_use]
+mod macros;
+
+mod commit;
+mod errors;
+mod insert;
+mod iterator;
+mod lookup;
+mod marshal;
+mod node;
+mod overlay;
+mod prefetch;
+mod remove;
+
+pub use errors::*;
+pub use node::*;
+pub use overlay::*;
+
+use std::{cell::RefCell, fmt, rc::Rc};
+
+use anyhow::Result;
+
+use crate::{
+ common::{crypto::hash::Hash, namespace::Namespace},
+ storage::mkvs::{self, cache::*, sync::*},
+};
+
+/// A container for the parameters used to construct a new MKVS tree instance.
+pub struct Options {
+ node_capacity: usize,
+ value_capacity: usize,
+ root: Option<Root>,
+ root_type: Option<RootType>,
+}
+
+impl Default for Options {
+ fn default() -> Self {
+ Self {
+ node_capacity: 50_000,
+ value_capacity: 16 * 1024 * 1024,
+ root: None,
+ root_type: None,
+ }
+ }
+}
+
+/// Tree builder.
+///
+/// This can be used to construct a `Tree` through a builder-like pattern.
+#[derive(Default)]
+pub struct Builder {
+ options: Options,
+}
+
+impl Builder {
+ /// Creates a new builder.
+ pub fn new() -> Self {
+ Builder::default()
+ }
+
+ /// Set the capacity of the underlying in-memory cache.
+ ///
+ /// * `node_capacity` is the maximum number of nodes held by the
+ /// cache before eviction.
+ /// * `value_capacity` is the total size, in bytes, of values held
+ /// by the cache before eviction.
+ ///
+ /// If set to 0, the relevant cache will have an unlimited capacity. If left
+ /// unspecified, the cache will default to 50_000 for nodes and 16MB for values.
+ pub fn with_capacity(mut self, node_capacity: usize, value_capacity: usize) -> Self {
+ self.options.node_capacity = node_capacity;
+ self.options.value_capacity = value_capacity;
+ self
+ }
+
+ /// Set an existing root as the root for the new tree.
+ ///
+ /// Either this or a root type must be specified to construct a new
+ /// tree. If neither is specified, or if both are set but don't agree on
+ /// the root type, the constructor will panic.
+ pub fn with_root(mut self, root: Root) -> Self {
+ self.options.root = Some(root);
+ self
+ }
+
+ /// Set the storage root type for this tree.
+ ///
+ /// Either this or an existing root must be specified to construct a new
+ /// tree. If neither is specified, or if both are set but don't agree on
+ /// the root type, the constructor will panic.
+ pub fn with_root_type(mut self, root_type: RootType) -> Self {
+ self.options.root_type = Some(root_type);
+ self
+ }
+
+ /// Commit the options set so far into a newly constructed tree instance.
+ pub fn build(self, read_syncer: Box<dyn ReadSync>) -> Tree {
+ assert!(
+ self.options.root_type.is_some() || self.options.root.is_some(),
+ "mkvs/tree: neither root type nor storage root specified"
+ );
+ if let Some(root) = self.options.root {
+ if let Some(root_type) = self.options.root_type {
+ assert!(
+ root.root_type == root_type,
+ "mkvs/tree: specified storage root and incompatible root type"
+ );
+ }
+ }
+ Tree::new(read_syncer, &self.options)
+ }
+}
+
+/// A patricia tree-based MKVS implementation.
+pub struct Tree {
+ pub(crate) cache: RefCell<Box<LRUCache>>,
+ pub(crate) root_type: RootType,
+}
+
+// Tree is Send as long as ownership of internal Rcs cannot leak out via any of its methods.
+unsafe impl Send for Tree {}
+
+impl Tree {
+ /// Construct a new tree instance using the given read syncer and options struct.
+ pub fn new(read_syncer: Box<dyn ReadSync>, opts: &Options) -> Tree {
+ let root_type = if opts.root.is_none() {
+ opts.root_type.unwrap()
+ } else {
+ opts.root.unwrap().root_type
+ };
+ let tree = Tree {
+ cache: RefCell::new(LRUCache::new(
+ opts.node_capacity,
+ opts.value_capacity,
+ read_syncer,
+ root_type,
+ )),
+ root_type,
+ };
+
+ if let Some(root) = opts.root {
+ tree.cache
+ .borrow_mut()
+ .set_pending_root(Rc::new(RefCell::new(NodePointer {
+ clean: true,
+ hash: root.hash,
+ ..Default::default()
+ })));
+ tree.cache.borrow_mut().set_sync_root(root);
+ }
+
+ tree
+ }
+
+ /// Return an builder struct to chain configuration calls on.
+ pub fn builder() -> Builder {
+ Builder::new()
+ }
+}
+
+impl fmt::Debug for Tree {
+ fn fmt(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> {
+ self.cache.borrow().get_pending_root().fmt(f)
+ }
+}
+
+impl mkvs::FallibleMKVS for Tree {
+ fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>> {
+ Tree::get(self, key)
+ }
+
+ fn get_proof(&self, key: &[u8]) -> Result<Option<Proof>> {
+ Tree::get_proof(self, key)
+ }
+
+ fn cache_contains_key(&self, key: &[u8]) -> bool {
+ Tree::cache_contains_key(self, key)
+ }
+
+ fn insert(&mut self, key: &[u8], value: &[u8]) -> Result<Option<Vec<u8>>> {
+ Tree::insert(self, key, value)
+ }
+
+ fn remove(&mut self, key: &[u8]) -> Result<Option<Vec<u8>>> {
+ Tree::remove(self, key)
+ }
+
+ fn prefetch_prefixes(&self, prefixes: &[mkvs::Prefix], limit: u16) -> Result<()> {
+ Tree::prefetch_prefixes(self, prefixes, limit)
+ }
+
+ fn iter(&self) -> Box<dyn mkvs::Iterator + '_> {
+ Box::new(Tree::iter(self))
+ }
+
+ fn commit(&mut self, namespace: Namespace, version: u64) -> Result<Hash> {
+ Tree::commit(self, namespace, version)
+ }
+}
+
+#[cfg(test)]
+mod node_test;
+#[cfg(test)]
+mod tree_bench;
+#[cfg(test)]
+mod tree_test;
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +
use std::{cell::RefCell, rc::Rc};
+
+use crate::{
+ common::{crypto::hash::Hash, namespace::Namespace},
+ storage::mkvs::{
+ cache::{CacheExtra, CacheItem},
+ marshal::Marshal,
+ },
+};
+
+/// Common interface for node-like objects in the tree.
+pub trait Node {
+ /// Check whether the node is clean or not.
+ fn is_clean(&self) -> bool;
+ /// Get the node's hash.
+ fn get_hash(&self) -> Hash;
+ /// Recompute the node's hash.
+ fn update_hash(&mut self);
+ /// Duplicate the node but include only hash references.
+ fn extract(&self) -> NodeRef;
+}
+
+/// Storage root type.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+#[repr(u8)]
+pub enum RootType {
+ /// Invalid or uninitialized storage root type.
+ #[default]
+ Invalid = 0,
+ /// Storage root for runtime state.
+ State = 1,
+ /// Storage root for transaction IO.
+ IO = 2,
+}
+
+/// Storage root.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct Root {
+ /// Namespace under which the root is stored.
+ #[cbor(rename = "ns")]
+ pub namespace: Namespace,
+ /// Monotonically increasing version number in which the root is stored.
+ pub version: u64,
+ /// The storage type that this root has data for.
+ pub root_type: RootType,
+ /// Merkle root hash.
+ pub hash: Hash,
+}
+
+/// A box type that can contain either internal or leaf nodes.
+#[derive(Debug, Eq, PartialEq)]
+pub enum NodeBox {
+ Internal(InternalNode),
+ Leaf(LeafNode),
+}
+
+impl Default for NodeBox {
+ fn default() -> Self {
+ NodeBox::Internal(Default::default())
+ }
+}
+
+impl Node for NodeBox {
+ fn is_clean(&self) -> bool {
+ match self {
+ NodeBox::Internal(ref n) => n.is_clean(),
+ NodeBox::Leaf(ref n) => n.is_clean(),
+ }
+ }
+
+ fn get_hash(&self) -> Hash {
+ match self {
+ NodeBox::Internal(ref n) => n.get_hash(),
+ NodeBox::Leaf(ref n) => n.get_hash(),
+ }
+ }
+
+ fn update_hash(&mut self) {
+ match self {
+ NodeBox::Internal(ref mut n) => n.update_hash(),
+ NodeBox::Leaf(ref mut n) => n.update_hash(),
+ }
+ }
+
+ fn extract(&self) -> NodeRef {
+ match self {
+ NodeBox::Internal(ref n) => n.extract(),
+ NodeBox::Leaf(ref n) => n.extract(),
+ }
+ }
+}
+
+/// Node types in the tree.
+///
+/// Integer values of the variants here are also used in subtree
+/// serialization and as prefixes in node hash computations.
+#[derive(Copy, Clone, Debug)]
+#[repr(u8)]
+pub enum NodeKind {
+ None = 0x02,
+ Internal = 0x01,
+ Leaf = 0x00,
+}
+
+/// `NodeRef` is a reference-counted pointer to a node box.
+pub type NodeRef = Rc<RefCell<NodeBox>>;
+
+/// A pointer to a node in the tree.
+#[derive(Debug, Default)]
+pub struct NodePointer {
+ pub clean: bool,
+ pub hash: Hash,
+ pub node: Option<NodeRef>,
+
+ pub cache_extra: CacheExtra<NodePointer>,
+}
+
+/// A reference-counted pointer to a pointer.
+pub type NodePtrRef = Rc<RefCell<NodePointer>>;
+
+impl NodePointer {
+ /// Construct a null pointer.
+ pub fn null_ptr() -> NodePtrRef {
+ Rc::new(RefCell::new(NodePointer {
+ node: None,
+ clean: true,
+ hash: Hash::empty_hash(),
+ ..Default::default()
+ }))
+ }
+
+ /// Construct a hash-only pointer.
+ pub fn hash_ptr(hash: Hash) -> NodePtrRef {
+ Rc::new(RefCell::new(NodePointer {
+ node: None,
+ clean: true,
+ hash,
+ ..Default::default()
+ }))
+ }
+
+ /// Construct a node pointer from a full node.
+ pub fn from_node(node: NodeBox) -> NodePtrRef {
+ Rc::new(RefCell::new(NodePointer {
+ hash: node.get_hash(),
+ node: Some(Rc::new(RefCell::new(node))),
+ clean: true,
+ ..Default::default()
+ }))
+ }
+
+ /// Check if the pointer is a null pointer.
+ pub fn is_null(&self) -> bool {
+ self.hash.is_empty()
+ }
+
+ /// Check if the pointer has a resolved reference to a concrete node.
+ pub fn has_node(&self) -> bool {
+ !self.is_null() && self.node.is_some()
+ }
+
+ /// Get a reference to the node the pointer is pointing to.
+ pub fn get_node(&self) -> NodeRef {
+ match &self.node {
+ None => panic!("mkvs: get_node called on pointer without a node"),
+ Some(node) => node.clone(),
+ }
+ }
+
+ /// Return a copy of this pointer containing only hash references.
+ pub fn extract(&self) -> NodePtrRef {
+ assert!(self.clean, "mkvs: extract called on dirty pointer");
+
+ Rc::new(RefCell::new(NodePointer {
+ clean: true,
+ hash: self.hash,
+ ..Default::default()
+ }))
+ }
+
+ // Make deep copy of the Pointer to LeafNode excluding LRU and DBInternal.
+ //
+ // Panics, if it's called on non-leaf node pointer.
+ fn copy_leaf_ptr(&self) -> NodePtrRef {
+ if !self.has_node() {
+ return NodePointer::null_ptr();
+ }
+
+ assert!(self.clean, "mkvs: copy_leaf_ptr called on dirty pointer");
+
+ if let Some(ref some_node) = self.node {
+ let nyoo = noderef_as!(some_node, Leaf).copy();
+ Rc::new(RefCell::new(NodePointer {
+ clean: true,
+ hash: self.hash,
+ node: Some(Rc::new(RefCell::new(NodeBox::Leaf(nyoo)))),
+ ..Default::default()
+ }))
+ } else {
+ panic!("mkvs: copy_leaf_ptr called on a non-leaf pointer");
+ }
+ }
+}
+
+impl CacheItem for NodePointer {
+ fn get_cache_extra(&self) -> CacheExtra<NodePointer> {
+ self.cache_extra
+ }
+
+ fn set_cache_extra(&mut self, new_val: CacheExtra<NodePointer>) {
+ self.cache_extra = new_val;
+ }
+
+ fn get_cached_size(&self) -> usize {
+ 1
+ }
+}
+
+impl PartialEq for NodePointer {
+ fn eq(&self, other: &NodePointer) -> bool {
+ if self.clean && other.clean {
+ self.hash == other.hash
+ } else {
+ self.node.is_some() && self.node == other.node
+ }
+ }
+}
+
+impl Eq for NodePointer {}
+
+/// An internal tree node with two children and possibly a leaf.
+#[derive(Debug, Default)]
+pub struct InternalNode {
+ pub clean: bool,
+ pub hash: Hash,
+ pub label: Key, // label on the incoming edge
+ pub label_bit_length: Depth, // length of the label in bits
+ pub leaf_node: NodePtrRef, // for the key ending at this depth
+ pub left: NodePtrRef,
+ pub right: NodePtrRef,
+}
+
+impl Node for InternalNode {
+ fn is_clean(&self) -> bool {
+ self.clean
+ }
+
+ fn get_hash(&self) -> Hash {
+ self.hash
+ }
+
+ fn update_hash(&mut self) {
+ let leaf_node_hash = self.leaf_node.borrow().hash;
+ let left_hash = self.left.borrow().hash;
+ let right_hash = self.right.borrow().hash;
+
+ self.hash = Hash::digest_bytes_list(&[
+ &[NodeKind::Internal as u8],
+ &self.label_bit_length.marshal_binary().unwrap(),
+ self.label.as_ref(),
+ leaf_node_hash.as_ref(),
+ left_hash.as_ref(),
+ right_hash.as_ref(),
+ ]);
+ }
+
+ fn extract(&self) -> NodeRef {
+ assert!(self.clean, "mkvs: extract called on dirty node");
+
+ Rc::new(RefCell::new(NodeBox::Internal(InternalNode {
+ clean: true,
+ hash: self.hash,
+ label: self.label.clone(),
+ label_bit_length: self.label_bit_length,
+ leaf_node: self.leaf_node.borrow().copy_leaf_ptr(),
+ left: self.left.borrow().extract(),
+ right: self.right.borrow().extract(),
+ })))
+ }
+}
+
+impl PartialEq for InternalNode {
+ fn eq(&self, other: &InternalNode) -> bool {
+ if self.clean && other.clean {
+ self.hash == other.hash
+ } else {
+ self.leaf_node == other.leaf_node
+ && self.left == other.left
+ && self.right == other.right
+ }
+ }
+}
+
+impl Eq for InternalNode {}
+
+/// A leaf node containing a key/value pair.
+#[derive(Debug, Default)]
+pub struct LeafNode {
+ pub clean: bool,
+ pub hash: Hash,
+ pub key: Key,
+ pub value: Value,
+}
+
+impl LeafNode {
+ pub fn copy(&self) -> LeafNode {
+ LeafNode {
+ clean: self.clean,
+ hash: self.hash,
+ key: self.key.to_owned(),
+ value: self.value.clone(),
+ }
+ }
+}
+
+impl Node for LeafNode {
+ fn is_clean(&self) -> bool {
+ self.clean
+ }
+
+ fn get_hash(&self) -> Hash {
+ self.hash
+ }
+
+ fn update_hash(&mut self) {
+ self.hash = Hash::digest_bytes_list(&[
+ &[NodeKind::Leaf as u8],
+ &(self.key.len() as u32).marshal_binary().unwrap(),
+ self.key.as_ref(),
+ &(self.value.len() as u32).marshal_binary().unwrap(),
+ self.value.as_ref(),
+ ]);
+ }
+
+ fn extract(&self) -> NodeRef {
+ assert!(self.clean, "mkvs: extract called on dirty node");
+ Rc::new(RefCell::new(NodeBox::Leaf(LeafNode {
+ clean: true,
+ hash: self.hash,
+ key: self.key.clone(),
+ value: self.value.clone(),
+ })))
+ }
+}
+
+impl PartialEq for LeafNode {
+ fn eq(&self, other: &LeafNode) -> bool {
+ if self.clean && other.clean {
+ self.hash == other.hash
+ } else {
+ self.key == other.key && self.value == other.value
+ }
+ }
+}
+
+impl Eq for LeafNode {}
+
+// Depth determines the maximum length of the key in bits.
+//
+// max length = 2^size_of(Depth)*8
+pub type Depth = u16;
+
+pub trait DepthTrait {
+ // Returns the number of bytes needed to fit given bits.
+ fn to_bytes(&self) -> usize;
+}
+
+impl DepthTrait for Depth {
+ fn to_bytes(&self) -> usize {
+ let size = self / 8;
+ if self % 8 != 0 {
+ (size + 1) as usize
+ } else {
+ size as usize
+ }
+ }
+}
+
+// Key holds variable-length key.
+pub type Key = Vec<u8>;
+
+pub trait KeyTrait {
+ /// Get a single bit from the given hash.
+ fn get_bit(&self, bit: Depth) -> bool;
+ /// Returns the length of the key in bits.
+ fn bit_length(&self) -> Depth;
+ /// Bit-wise splits of the key.
+ fn split(&self, split_point: Depth, key_len: Depth) -> (Key, Key);
+ /// Bit-wise merges key of given length with another key of given length.
+ fn merge(&self, key_len: Depth, k2: &Key, k2_len: Depth) -> Key;
+ /// Appends the given bit to the key.
+ fn append_bit(&self, key_len: Depth, bit: bool) -> Key;
+ /// Computes length of common prefix of k and k2 with given bit lengths.
+ fn common_prefix_len(&self, key_len: Depth, k2: &Key, k2_len: Depth) -> Depth;
+}
+
+impl KeyTrait for Key {
+ fn get_bit(&self, bit: Depth) -> bool {
+ (self[(bit / 8) as usize] & (1 << (7 - (bit % 8)))) != 0
+ }
+
+ fn bit_length(&self) -> Depth {
+ (self.len() * 8) as Depth
+ }
+
+ fn split(&self, split_point: Depth, key_len: Depth) -> (Key, Key) {
+ assert!(
+ split_point <= key_len,
+ "mkvs: split_point {} greater than key_len {}",
+ split_point,
+ key_len
+ );
+
+ let prefix_len = split_point.to_bytes();
+ let suffix_len = (key_len - split_point).to_bytes();
+ let mut prefix: Key = vec![0; prefix_len];
+ let mut suffix: Key = vec![0; suffix_len];
+
+ prefix.clone_from_slice(&self[0..split_point.to_bytes()]);
+
+ // Clean the remainder of the byte.
+ if split_point % 8 != 0 {
+ prefix[prefix_len - 1] &= 0xff << (8 - split_point % 8)
+ }
+
+ for i in 0..suffix_len {
+ // First set the left chunk of the byte
+ suffix[i] = self[i + split_point as usize / 8] << (split_point % 8);
+ // ...and the right chunk, if we haven't reached the end of k yet.
+ if split_point % 8 != 0 && i + split_point as usize / 8 + 1 != self.len() {
+ suffix[i] |=
+ self[i + split_point as usize / 8 + 1] >> (8 - split_point as usize % 8);
+ }
+ }
+
+ (prefix, suffix)
+ }
+
+ fn merge(&self, key_len: Depth, k2: &Key, k2_len: Depth) -> Key {
+ let mut key_len_bytes = (key_len as usize) / 8;
+ if key_len % 8 != 0 {
+ key_len_bytes += 1;
+ }
+
+ let mut new_key: Key = vec![0; (key_len + k2_len).to_bytes()];
+ new_key[..key_len_bytes].clone_from_slice(&self[..key_len_bytes]);
+
+ for i in 0..k2.len() {
+ // First set the right chunk of the previous byte
+ if key_len % 8 != 0 && key_len_bytes > 0 {
+ new_key[key_len_bytes + i - 1] |= k2[i] >> (key_len % 8);
+ }
+ // ...and the next left chunk, if we haven't reached the end of newKey
+ // yet.
+ if key_len_bytes + i < new_key.len() {
+ // another mod 8 to prevent bit shifting for 8 bits
+ new_key[key_len_bytes + i] |= k2[i] << ((8 - key_len % 8) % 8);
+ }
+ }
+
+ new_key
+ }
+
+ fn append_bit(&self, key_len: Depth, val: bool) -> Key {
+ let mut new_key: Key = vec![0; (key_len + 1).to_bytes()];
+ new_key[..self.len()].clone_from_slice(self);
+
+ if val {
+ new_key[key_len as usize / 8] |= 0x80 >> (key_len % 8)
+ } else {
+ new_key[key_len as usize / 8] &= !(0x80 >> (key_len % 8))
+ }
+
+ new_key
+ }
+
+ fn common_prefix_len(&self, key_bit_len: Depth, k2: &Key, k2_bit_len: Depth) -> Depth {
+ let min_key_len = if k2.len() < self.len() {
+ k2.len()
+ } else {
+ self.len()
+ };
+
+ // Compute the common prefix byte-wise.
+ let mut i: usize = 0;
+ while i < min_key_len {
+ if self[i] != k2[i] {
+ break;
+ }
+ i += 1;
+ }
+
+ // Prefixes match i bytes and maybe some more bits below.
+ let mut bit_length = (i * 8) as Depth;
+
+ if i != self.len() && i != k2.len() {
+ // We got a mismatch somewhere along the way. We need to compute how
+ // many additional bits in i-th byte match.
+ bit_length += (self[i] ^ k2[i]).leading_zeros() as Depth;
+ }
+
+ // In any case, bit_length should never exceed length of the shorter key.
+ if bit_length > key_bit_len {
+ bit_length = key_bit_len;
+ }
+ if bit_length > k2_bit_len {
+ bit_length = k2_bit_len;
+ };
+ bit_length
+ }
+}
+
+// Value holds the leaf node value.
+pub type Value = Vec<u8>;
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +
use std::{
+ collections::{btree_map, BTreeMap, HashSet},
+ iter::Peekable,
+};
+
+use anyhow::{Error, Result};
+
+use crate::{
+ common::{crypto::hash::Hash, namespace::Namespace},
+ storage::mkvs::{self, tree::Key, Proof},
+};
+
+/// A key-value tree overlay that holds all updates in memory and only commits them if requested.
+/// This can be used to create snapshots that can be discarded.
+///
+/// While updates (inserts, removes) are stored in the overlay, reads are not cached in the overlay
+/// as the inner tree has its own cache and double caching makes less sense.
+pub struct OverlayTree<T: mkvs::FallibleMKVS> {
+ inner: T,
+ overlay: BTreeMap<Vec<u8>, Vec<u8>>,
+ dirty: HashSet<Vec<u8>>,
+}
+
+impl<T: mkvs::FallibleMKVS> OverlayTree<T> {
+ /// Create a new overlay tree.
+ pub fn new(inner: T) -> Self {
+ Self {
+ inner,
+ overlay: BTreeMap::new(),
+ dirty: HashSet::new(),
+ }
+ }
+
+ /// Get an existing key.
+ pub fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>> {
+ // For dirty values, check the overlay.
+ if self.dirty.contains(key) {
+ return Ok(self.overlay.get(key).cloned());
+ }
+
+ // Otherwise fetch from inner tree.
+ self.inner.get(key)
+ }
+
+ pub fn get_proof(&self, key: &[u8]) -> Result<Option<Proof>> {
+ if !self.dirty.is_empty() {
+ Err(Error::msg(
+ "overlay tree proofs are not supported when there are dirty values",
+ ))?;
+ }
+
+ self.inner.get_proof(key)
+ }
+
+ /// Insert a key/value pair into the tree.
+ pub fn insert(&mut self, key: &[u8], value: &[u8]) -> Result<Option<Vec<u8>>> {
+ let previous = self.get(key)?;
+
+ self.overlay.insert(key.to_owned(), value.to_owned());
+ self.dirty.insert(key.to_owned());
+
+ Ok(previous)
+ }
+
+ /// Remove entry with given key, returning the value at the key if the key was previously
+ /// in the database.
+ pub fn remove(&mut self, key: &[u8]) -> Result<Option<Vec<u8>>> {
+ // For dirty values, remove from the overlay.
+ if self.dirty.contains(key) {
+ return Ok(self.overlay.remove(key));
+ }
+
+ let value = self.inner.get(key)?;
+
+ // Do not treat a value as dirty if it was not dirty before and did not exist in the inner tree.
+ if value.is_some() {
+ self.dirty.insert(key.to_owned());
+ }
+ Ok(value)
+ }
+
+ /// Return an iterator over the tree.
+ pub fn iter(&self) -> OverlayTreeIterator<T> {
+ OverlayTreeIterator::new(self)
+ }
+
+ /// Commit any modifications to the underlying tree.
+ pub fn commit(&mut self) -> Result<mkvs::WriteLog> {
+ let mut log: mkvs::WriteLog = Vec::new();
+
+ // Insert all items present in the overlay.
+ for (key, value) in &self.overlay {
+ self.inner.insert(key, value)?;
+ self.dirty.remove(key);
+
+ log.push(mkvs::LogEntry {
+ key: key.clone(),
+ value: Some(value.clone()),
+ });
+ }
+ self.overlay.clear();
+
+ // Any remaining dirty items must have been removed.
+ for key in &self.dirty {
+ self.inner.remove(key)?;
+
+ log.push(mkvs::LogEntry {
+ key: key.clone(),
+ value: None,
+ });
+ }
+ self.dirty.clear();
+
+ Ok(log)
+ }
+
+ /// Commit any modifications to the underlying tree and then immediately commit the underlying
+ /// tree, returning the new root hash.
+ pub fn commit_both(
+ &mut self,
+ namespace: Namespace,
+ version: u64,
+ ) -> Result<(mkvs::WriteLog, Hash)> {
+ // First commit modifications to the underlying tree.
+ let write_log = self.commit()?;
+ // Then commit the underlying tree.
+ let root_hash = self.inner.commit(namespace, version)?;
+
+ Ok((write_log, root_hash))
+ }
+}
+
+/// An iterator over the `OverlayTree`.
+pub struct OverlayTreeIterator<'tree, T: mkvs::FallibleMKVS> {
+ tree: &'tree OverlayTree<T>,
+
+ inner: Box<dyn mkvs::Iterator + 'tree>,
+ overlay: Peekable<btree_map::Range<'tree, Vec<u8>, Vec<u8>>>,
+ overlay_valid: bool,
+
+ key: Option<Vec<u8>>,
+ value: Option<Vec<u8>>,
+}
+
+impl<'tree, T: mkvs::FallibleMKVS> OverlayTreeIterator<'tree, T> {
+ fn new(tree: &'tree OverlayTree<T>) -> Self {
+ Self {
+ tree,
+ inner: tree.inner.iter(),
+ overlay: tree.overlay.range(vec![]..).peekable(),
+ overlay_valid: true,
+ key: None,
+ value: None,
+ }
+ }
+
+ fn update_iterator_position(&mut self) {
+ // Skip over any dirty entries from the inner iterator.
+ loop {
+ if !self.inner.is_valid()
+ || !self
+ .tree
+ .dirty
+ .contains(self.inner.get_key().as_ref().expect("inner.is_valid"))
+ {
+ break;
+ }
+ self.inner.next();
+ }
+
+ let i_key = self.inner.get_key();
+ let o_item = self.overlay.peek();
+ self.overlay_valid = o_item.is_some();
+
+ if self.inner.is_valid()
+ && (!self.overlay_valid
+ || i_key.as_ref().expect("inner.is_valid") < o_item.expect("overlay_valid").0)
+ {
+ // Key of inner iterator is smaller than the key of the overlay iterator.
+ self.key = i_key.clone();
+ self.value = self.inner.get_value().clone();
+ } else if self.overlay_valid {
+ // Key of overlay iterator is smaller than or equal to the key of the inner iterator.
+ let (o_key, o_value) = o_item.expect("overlay_valid");
+ self.key = Some(o_key.to_vec());
+ self.value = Some(o_value.to_vec());
+ } else {
+ // Both iterators are invalid.
+ self.key = None;
+ self.value = None;
+ }
+ }
+
+ fn next(&mut self) {
+ if !self.overlay_valid
+ || (self.inner.is_valid()
+ && self.inner.get_key().as_ref().expect("inner.is_valid")
+ <= self.overlay.peek().expect("overlay_valid").0)
+ {
+ // Key of inner iterator is smaller or equal than the key of the overlay iterator.
+ self.inner.next();
+ } else {
+ // Key of inner iterator is greater than the key of the overlay iterator.
+ self.overlay.next();
+ }
+
+ self.update_iterator_position();
+ }
+}
+
+impl<'tree, T: mkvs::FallibleMKVS> Iterator for OverlayTreeIterator<'tree, T> {
+ type Item = (Vec<u8>, Vec<u8>);
+
+ fn next(&mut self) -> Option<Self::Item> {
+ use mkvs::Iterator;
+
+ if !self.is_valid() {
+ return None;
+ }
+
+ let key = self.key.as_ref().expect("iterator is valid").clone();
+ let value = self.value.as_ref().expect("iterator is valid").clone();
+ OverlayTreeIterator::next(self);
+
+ Some((key, value))
+ }
+}
+
+impl<'tree, T: mkvs::FallibleMKVS> mkvs::Iterator for OverlayTreeIterator<'tree, T> {
+ fn set_prefetch(&mut self, prefetch: usize) {
+ self.inner.set_prefetch(prefetch)
+ }
+
+ fn is_valid(&self) -> bool {
+ // If either iterator is valid, the merged iterator is valid.
+ self.inner.is_valid() || self.overlay_valid
+ }
+
+ fn error(&self) -> &Option<Error> {
+ self.inner.error()
+ }
+
+ fn rewind(&mut self) {
+ self.seek(&[]);
+ }
+
+ fn seek(&mut self, key: &[u8]) {
+ self.inner.seek(key);
+ self.overlay = self.tree.overlay.range(key.to_vec()..).peekable();
+
+ self.update_iterator_position();
+ }
+
+ fn get_key(&self) -> &Option<Key> {
+ &self.key
+ }
+
+ fn get_value(&self) -> &Option<Vec<u8>> {
+ &self.value
+ }
+
+ fn next(&mut self) {
+ OverlayTreeIterator::next(self)
+ }
+}
+
+impl<T: mkvs::FallibleMKVS> mkvs::MKVS for OverlayTree<T> {
+ fn get(&self, key: &[u8]) -> Option<Vec<u8>> {
+ self.get(key).unwrap()
+ }
+
+ fn get_proof(&self, key: &[u8]) -> Option<Proof> {
+ self.get_proof(key).unwrap()
+ }
+
+ fn cache_contains_key(&self, key: &[u8]) -> bool {
+ // For dirty values, check the overlay.
+ if self.dirty.contains(key) {
+ return self.overlay.contains_key(key);
+ }
+ self.inner.cache_contains_key(key)
+ }
+
+ fn insert(&mut self, key: &[u8], value: &[u8]) -> Option<Vec<u8>> {
+ self.insert(key, value).unwrap()
+ }
+
+ fn remove(&mut self, key: &[u8]) -> Option<Vec<u8>> {
+ self.remove(key).unwrap()
+ }
+
+ fn prefetch_prefixes(&self, prefixes: &[mkvs::Prefix], limit: u16) {
+ self.inner.prefetch_prefixes(prefixes, limit).unwrap()
+ }
+
+ fn iter(&self) -> Box<dyn mkvs::Iterator + '_> {
+ Box::new(self.iter())
+ }
+
+ fn commit(&mut self, namespace: Namespace, version: u64) -> Result<(mkvs::WriteLog, Hash)> {
+ self.commit_both(namespace, version)
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+ use crate::storage::mkvs::{
+ sync::NoopReadSyncer, tree::iterator::test::test_iterator_with, RootType, Tree,
+ };
+
+ #[test]
+ fn test_overlay() {
+ let mut tree = Tree::builder()
+ .with_root_type(RootType::State)
+ .build(Box::new(NoopReadSyncer));
+
+ // Generate some items.
+ let items = vec![
+ (b"key".to_vec(), b"first".to_vec()),
+ (b"key 1".to_vec(), b"one".to_vec()),
+ (b"key 2".to_vec(), b"two".to_vec()),
+ (b"key 5".to_vec(), b"five".to_vec()),
+ (b"key 8".to_vec(), b"eight".to_vec()),
+ (b"key 9".to_vec(), b"nine".to_vec()),
+ ];
+
+ let tests = vec![
+ (b"k".to_vec(), 0),
+ (b"key 1".to_vec(), 1),
+ (b"key 3".to_vec(), 3),
+ (b"key 4".to_vec(), 3),
+ (b"key 5".to_vec(), 3),
+ (b"key 6".to_vec(), 4),
+ (b"key 7".to_vec(), 4),
+ (b"key 8".to_vec(), 4),
+ (b"key 9".to_vec(), 5),
+ (b"key A".to_vec(), -1),
+ ];
+
+ // Create an overlay over an empty tree and insert some items into the overlay.
+ let mut overlay = OverlayTree::new(&mut tree);
+ for (key, value) in items.iter() {
+ overlay.insert(key, value).unwrap();
+ }
+
+ // Test that an overlay-only iterator works correctly.
+ let it = overlay.iter();
+ test_iterator_with(&items, it, &tests);
+
+ // Insert some items into the underlying tree.
+ for (key, value) in items.iter() {
+ tree.insert(key, value).unwrap();
+ }
+
+ // Create a tree pointer so we can unsafely peek into the tree later.
+ let tree_ref = &tree as *const Tree;
+
+ // Create an overlay.
+ let mut overlay = OverlayTree::new(&mut tree);
+
+ // Test that all keys can be fetched from an empty overlay.
+ for (k, expected_v) in &items {
+ let v = overlay.get(&k).unwrap();
+ assert_eq!(v.as_ref(), Some(expected_v));
+ }
+
+ // Test that merged iterator works correctly on an empty overlay (it should behave exactly
+ // the same as for the inner tree).
+ let it = overlay.iter();
+ test_iterator_with(&items, it, &tests);
+
+ // Add some updates to the overlay.
+ overlay.remove(b"key 2").unwrap();
+ overlay.insert(b"key 7", b"seven").unwrap();
+ overlay.remove(b"key 5").unwrap();
+ overlay.insert(b"key 5", b"fivey").unwrap();
+
+ // Make sure updates did not propagate to the inner tree.
+ // NOTE: This is unsafe as we are otherwise not allowed to reference the inner tree.
+ unsafe {
+ let tree_ref = &*tree_ref;
+
+ let value = tree_ref.get(b"key 2").unwrap();
+ assert_eq!(
+ value,
+ Some(b"two".to_vec()),
+ "value in inner tree should be unchanged"
+ );
+ let value = tree_ref.get(b"key 7").unwrap();
+ assert_eq!(value, None, "value should not exist in inner tree");
+ }
+
+ // State of overlay after updates.
+ let items = vec![
+ (b"key".to_vec(), b"first".to_vec()),
+ (b"key 1".to_vec(), b"one".to_vec()),
+ (b"key 5".to_vec(), b"fivey".to_vec()),
+ (b"key 7".to_vec(), b"seven".to_vec()),
+ (b"key 8".to_vec(), b"eight".to_vec()),
+ (b"key 9".to_vec(), b"nine".to_vec()),
+ ];
+
+ let tests = vec![
+ (b"k".to_vec(), 0),
+ (b"key 1".to_vec(), 1),
+ (b"key 3".to_vec(), 2),
+ (b"key 4".to_vec(), 2),
+ (b"key 5".to_vec(), 2),
+ (b"key 6".to_vec(), 3),
+ (b"key 7".to_vec(), 3),
+ (b"key 8".to_vec(), 4),
+ (b"key 9".to_vec(), 5),
+ (b"key A".to_vec(), -1),
+ ];
+
+ // Test that all keys can be fetched from an updated overlay.
+ for (k, expected_v) in &items {
+ let v = overlay.get(&k).unwrap();
+ assert_eq!(v.as_ref(), Some(expected_v));
+ }
+
+ // Make sure that merged overlay iterator works.
+ let it = overlay.iter();
+ test_iterator_with(&items, it, &tests);
+
+ // Commit the overlay.
+ overlay.commit().unwrap();
+
+ // Test that all keys can be fetched from an updated tree.
+ for (k, expected_v) in &items {
+ let v = tree.get(&k).unwrap();
+ assert_eq!(v.as_ref(), Some(expected_v));
+ }
+
+ // Make sure that the updated tree is correct.
+ let it = tree.iter();
+ test_iterator_with(&items, it, &tests);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +
use anyhow::Result;
+
+use crate::storage::mkvs::{
+ cache::{Cache, ReadSyncFetcher},
+ sync::{GetPrefixesRequest, Proof, ReadSync, TreeID},
+ tree::{NodePtrRef, Root, Tree},
+ Prefix,
+};
+
+pub(super) struct FetcherSyncGetPrefixes<'a> {
+ prefixes: &'a [Prefix],
+ limit: u16,
+}
+
+impl<'a> FetcherSyncGetPrefixes<'a> {
+ pub(super) fn new(prefixes: &'a [Prefix], limit: u16) -> Self {
+ Self { prefixes, limit }
+ }
+}
+
+impl<'a> ReadSyncFetcher for FetcherSyncGetPrefixes<'a> {
+ fn fetch(&self, root: Root, ptr: NodePtrRef, rs: &mut Box<dyn ReadSync>) -> Result<Proof> {
+ let rsp = rs.sync_get_prefixes(GetPrefixesRequest {
+ tree: TreeID {
+ root,
+ position: ptr.borrow().hash,
+ },
+ prefixes: self.prefixes.to_vec(),
+ limit: self.limit,
+ })?;
+ Ok(rsp.proof)
+ }
+}
+
+impl Tree {
+ /// Populate the in-memory tree with nodes for keys starting with given prefixes.
+ pub fn prefetch_prefixes(&self, prefixes: &[Prefix], limit: u16) -> Result<()> {
+ let pending_root = self.cache.borrow().get_pending_root();
+ self.cache
+ .borrow_mut()
+ .remote_sync(pending_root, FetcherSyncGetPrefixes::new(prefixes, limit))
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +
use anyhow::Result;
+
+use crate::storage::mkvs::{
+ cache::Cache,
+ tree::{
+ Depth, Key, KeyTrait, NodeBox, NodeKind, NodePointer, NodePtrRef, NodeRef, Tree, Value,
+ },
+};
+
+use super::lookup::FetcherSyncGet;
+
+impl Tree {
+ /// Remove entry with given key, returning the value at the key if the key was previously
+ /// in the database.
+ pub fn remove(&mut self, key: &[u8]) -> Result<Option<Vec<u8>>> {
+ let boxed_key = key.to_vec();
+ let pending_root = self.cache.borrow().get_pending_root();
+
+ // Remember where the path from root to target node ends (will end).
+ self.cache.borrow_mut().mark_position();
+
+ let (new_root, _, old_val) = self._remove(pending_root, 0, &boxed_key)?;
+ self.cache.borrow_mut().set_pending_root(new_root);
+
+ Ok(old_val)
+ }
+
+ fn _remove(
+ &mut self,
+ ptr: NodePtrRef,
+ bit_depth: Depth,
+ key: &Key,
+ ) -> Result<(NodePtrRef, bool, Option<Value>)> {
+ let node_ref = self
+ .cache
+ .borrow_mut()
+ .deref_node_ptr(ptr.clone(), Some(FetcherSyncGet::new(key, true)))?;
+
+ match classify_noderef!(?node_ref) {
+ NodeKind::None => {
+ // Remove from nil node.
+ Ok((NodePointer::null_ptr(), false, None))
+ }
+ NodeKind::Internal => {
+ // Remove from internal node and recursively collapse the path, if needed.
+ let node_ref = node_ref.unwrap();
+ let (changed, old_val): (bool, Option<Value>);
+ let (remaining_leaf, remaining_left, remaining_right): (
+ Option<NodeRef>,
+ Option<NodeRef>,
+ Option<NodeRef>,
+ );
+ if let NodeBox::Internal(ref mut n) = *node_ref.borrow_mut() {
+ // Remove from internal node and recursively collapse the branch, if
+ // needed.
+ let bit_length = bit_depth + n.label_bit_length;
+
+ if key.bit_length() < bit_length {
+ // Lookup key is too short for the current n.Label, so it doesn't exist.
+ return Ok((ptr, false, None));
+ }
+
+ let (new_child, c, o) = if key.bit_length() == bit_length {
+ self._remove(n.leaf_node.clone(), bit_depth, key)?
+ } else if key.get_bit(bit_length) {
+ self._remove(n.right.clone(), bit_length, key)?
+ } else {
+ self._remove(n.left.clone(), bit_length, key)?
+ };
+
+ changed = c;
+ old_val = o;
+
+ if key.bit_length() == bit_length {
+ n.leaf_node = new_child;
+ } else if key.get_bit(bit_length) {
+ n.right = new_child;
+ } else {
+ n.left = new_child;
+ }
+
+ // Fetch and check the remaining children.
+ // NOTE: The leaf node is always included with the internal node.
+ remaining_leaf = n.leaf_node.borrow().node.clone();
+ remaining_left = self
+ .cache
+ .borrow_mut()
+ .deref_node_ptr(n.left.clone(), Some(FetcherSyncGet::new(key, true)))?;
+ remaining_right = self
+ .cache
+ .borrow_mut()
+ .deref_node_ptr(n.right.clone(), Some(FetcherSyncGet::new(key, true)))?;
+ } else {
+ unreachable!("node kind is Internal");
+ }
+
+ // If exactly one child including LeafNode remains, collapse it.
+ match remaining_leaf {
+ Some(_) => match remaining_left {
+ Some(_) => (),
+ None => match remaining_right {
+ None => {
+ let nd_leaf = noderef_as!(node_ref, Internal).leaf_node.clone();
+ noderef_as_mut!(node_ref, Internal).leaf_node =
+ NodePointer::null_ptr();
+ self.cache.borrow_mut().remove_node(ptr);
+ return Ok((nd_leaf, true, old_val));
+ }
+ Some(_) => (),
+ },
+ },
+ None => {
+ let mut nd_child: Option<NodeRef> = None;
+ let mut node_ptr: NodePtrRef = NodePointer::null_ptr();
+ let mut both_children = true;
+ match remaining_left {
+ Some(_) => match remaining_right {
+ None => {
+ node_ptr = noderef_as!(node_ref, Internal).left.clone();
+ noderef_as_mut!(node_ref, Internal).left =
+ NodePointer::null_ptr();
+ nd_child = remaining_left;
+ both_children = false;
+ }
+ Some(_) => (),
+ },
+ None => match remaining_right {
+ None => (),
+ Some(_) => {
+ node_ptr = noderef_as!(node_ref, Internal).right.clone();
+ noderef_as_mut!(node_ref, Internal).right =
+ NodePointer::null_ptr();
+ nd_child = remaining_right;
+ both_children = false;
+ }
+ },
+ }
+
+ if !both_children {
+ // If child is an internal node, also fix the label.
+ if let Some(nd_child) = nd_child {
+ if let NodeKind::Internal = classify_noderef!(nd_child) {
+ if let NodeBox::Internal(ref mut inode) = *nd_child.borrow_mut()
+ {
+ inode.label = noderef_as!(node_ref, Internal).label.merge(
+ noderef_as!(node_ref, Internal).label_bit_length,
+ &inode.label,
+ inode.label_bit_length,
+ );
+ inode.label_bit_length +=
+ noderef_as!(node_ref, Internal).label_bit_length;
+ inode.clean = false;
+ node_ptr.borrow_mut().clean = false;
+ }
+ }
+ }
+
+ self.cache.borrow_mut().remove_node(ptr);
+ return Ok((node_ptr, true, old_val));
+ }
+ }
+ };
+
+ // Two or more children including leaf_node remain, just mark dirty bit.
+ if changed {
+ noderef_as_mut!(node_ref, Internal).clean = false;
+ ptr.borrow_mut().clean = false;
+ // No longer eligible for eviction as it is dirty.
+ self.cache
+ .borrow_mut()
+ .rollback_node(ptr.clone(), NodeKind::Internal);
+ }
+
+ Ok((ptr, changed, old_val))
+ }
+ NodeKind::Leaf => {
+ // Remove from leaf node.
+ let node_ref = node_ref.unwrap();
+ if noderef_as!(node_ref, Leaf).key == *key {
+ let old_val = noderef_as!(node_ref, Leaf).value.clone();
+ self.cache.borrow_mut().remove_node(ptr);
+ return Ok((NodePointer::null_ptr(), true, Some(old_val)));
+ }
+
+ Ok((ptr, false, None))
+ }
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +
//! Runtime storage interfaces and implementations.
+use std::{
+ collections::HashMap,
+ sync::{Arc, Mutex},
+};
+
+use crate::types::Error;
+
+pub mod mkvs;
+
+// Re-exports.
+pub use self::mkvs::MKVS;
+
+/// Trivial key/value storage.
+pub trait KeyValue: Send + Sync {
+ /// Fetch the value for a specific key.
+ fn get(&self, key: Vec<u8>) -> Result<Vec<u8>, Error>;
+
+ /// Store a specific key/value into storage.
+ fn insert(&self, key: Vec<u8>, value: Vec<u8>) -> Result<(), Error>;
+}
+
+impl<T: ?Sized + KeyValue> KeyValue for Arc<T> {
+ fn get(&self, key: Vec<u8>) -> Result<Vec<u8>, Error> {
+ KeyValue::get(&**self, key)
+ }
+
+ fn insert(&self, key: Vec<u8>, value: Vec<u8>) -> Result<(), Error> {
+ KeyValue::insert(&**self, key, value)
+ }
+}
+
+/// Untrusted key/value storage which stores arbitrary binary key/value pairs
+/// in memory.
+pub struct UntrustedInMemoryStorage {
+ store: Mutex<HashMap<Vec<u8>, Vec<u8>>>,
+}
+
+impl UntrustedInMemoryStorage {
+ pub fn new() -> Self {
+ Self {
+ store: Mutex::new(HashMap::new()),
+ }
+ }
+}
+
+impl KeyValue for UntrustedInMemoryStorage {
+ fn get(&self, key: Vec<u8>) -> Result<Vec<u8>, Error> {
+ // Return an empty vector if the key is not found.
+ let cache = self.store.lock().unwrap();
+ let value = cache.get(&key).cloned().unwrap_or_default();
+ Ok(value)
+ }
+
+ fn insert(&self, key: Vec<u8>, value: Vec<u8>) -> Result<(), Error> {
+ let mut cache = self.store.lock().unwrap();
+ cache.insert(key, value);
+ Ok(())
+ }
+}
+
+impl Default for UntrustedInMemoryStorage {
+ fn default() -> Self {
+ Self::new()
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +
//! Runtime call context.
+use std::sync::Arc;
+
+use crate::{
+ consensus::{
+ beacon::EpochTime,
+ roothash::{Header, RoundResults},
+ state::ConsensusState,
+ LightBlock,
+ },
+ protocol::Protocol,
+ storage::MKVS,
+};
+
+/// Transaction context.
+pub struct Context<'a> {
+ /// Low-level access to the underlying Runtime Host Protocol.
+ pub protocol: Arc<Protocol>,
+ /// Consensus light block.
+ pub consensus_block: &'a LightBlock,
+ /// Consensus state tree.
+ pub consensus_state: ConsensusState,
+ /// Runtime state.
+ pub runtime_state: &'a mut dyn MKVS,
+ /// The block header accompanying this transaction.
+ pub header: &'a Header,
+ /// Epoch corresponding to the currently processed block.
+ pub epoch: EpochTime,
+ /// Results of processing the previous successful round.
+ pub round_results: &'a RoundResults,
+ /// The maximum number of messages that can be emitted in this round.
+ pub max_messages: u32,
+ /// Flag indicating whether to only perform transaction check rather than
+ /// running the transaction.
+ pub check_only: bool,
+}
+
+impl<'a> Context<'a> {
+ /// Construct new transaction context.
+ #[allow(clippy::too_many_arguments)]
+ pub fn new(
+ protocol: Arc<Protocol>,
+ consensus_block: &'a LightBlock,
+ consensus_state: ConsensusState,
+ runtime_state: &'a mut dyn MKVS,
+ header: &'a Header,
+ epoch: EpochTime,
+ round_results: &'a RoundResults,
+ max_messages: u32,
+ check_only: bool,
+ ) -> Self {
+ Self {
+ protocol,
+ consensus_block,
+ consensus_state,
+ runtime_state,
+ header,
+ epoch,
+ round_results,
+ max_messages,
+ check_only,
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +
//! Runtime transaction batch dispatcher.
+use std::sync::{atomic::AtomicBool, Arc};
+
+use super::{context::Context, tags::Tags, types::TxnBatch};
+use crate::{
+ common::crypto::hash::Hash,
+ consensus::roothash,
+ types::{CheckTxResult, Error as RuntimeError},
+};
+
+/// Runtime transaction dispatcher trait.
+///
+/// It defines the interface used by the runtime call dispatcher
+/// to process transactions.
+pub trait Dispatcher: Send + Sync {
+ /// Whether dispatch is supported by this dispatcher.
+ fn is_supported(&self) -> bool {
+ true
+ }
+
+ /// Execute the transactions in the given batch.
+ ///
+ /// # Consensus Layer State Integrity
+ ///
+ /// Before this method is invoked, consensus layer state integrity verification is performed.
+ fn execute_batch(
+ &self,
+ ctx: Context,
+ batch: &TxnBatch,
+ in_msgs: &[roothash::IncomingMessage],
+ ) -> Result<ExecuteBatchResult, RuntimeError>;
+
+ /// Schedule and execute transactions in the given batch.
+ ///
+ /// The passed batch is an initial batch. In case the runtime needs additional items it should
+ /// request them from the host.
+ ///
+ /// # Consensus Layer State Integrity
+ ///
+ /// Before this method is invoked, consensus layer state integrity verification is performed.
+ fn schedule_and_execute_batch(
+ &self,
+ _ctx: Context,
+ _initial_batch: &mut TxnBatch,
+ _in_msgs: &[roothash::IncomingMessage],
+ ) -> Result<ExecuteBatchResult, RuntimeError> {
+ Err(RuntimeError::new(
+ "rhp/dispatcher",
+ 3,
+ "scheduling not supported",
+ ))
+ }
+
+ /// Check the transactions in the given batch for validity.
+ ///
+ /// # Consensus Layer State Integrity
+ ///
+ /// No consensus layer state integrity verification is performed for queries by default. The
+ /// runtime dispatcher implementation should perform integrity verification if needed on a
+ /// query-by-query basis.
+ fn check_batch(
+ &self,
+ ctx: Context,
+ batch: &TxnBatch,
+ ) -> Result<Vec<CheckTxResult>, RuntimeError>;
+
+ /// Invoke the finalizer (if any).
+ fn finalize(&self, _new_storage_root: Hash) {
+ // Default implementation does nothing.
+ }
+
+ /// Configure abort batch flag.
+ fn set_abort_batch_flag(&mut self, _abort_batch: Arc<AtomicBool>) {
+ // Default implementation does nothing.
+ }
+
+ /// Process a query.
+ ///
+ /// # Consensus Layer State Integrity
+ ///
+ /// No consensus layer state integrity verification is performed for queries by default. The
+ /// runtime dispatcher implementation should perform integrity verification if needed on a
+ /// query-by-query basis.
+ fn query(&self, _ctx: Context, _method: &str, _args: Vec<u8>) -> Result<Vec<u8>, RuntimeError> {
+ // Default implementation returns an error.
+ Err(RuntimeError::new(
+ "rhp/dispatcher",
+ 2,
+ "query not supported",
+ ))
+ }
+}
+
+impl<T: Dispatcher + ?Sized> Dispatcher for Box<T> {
+ fn execute_batch(
+ &self,
+ ctx: Context,
+ batch: &TxnBatch,
+ in_msgs: &[roothash::IncomingMessage],
+ ) -> Result<ExecuteBatchResult, RuntimeError> {
+ T::execute_batch(&**self, ctx, batch, in_msgs)
+ }
+
+ fn schedule_and_execute_batch(
+ &self,
+ ctx: Context,
+ initial_batch: &mut TxnBatch,
+ in_msgs: &[roothash::IncomingMessage],
+ ) -> Result<ExecuteBatchResult, RuntimeError> {
+ T::schedule_and_execute_batch(&**self, ctx, initial_batch, in_msgs)
+ }
+
+ fn check_batch(
+ &self,
+ ctx: Context,
+ batch: &TxnBatch,
+ ) -> Result<Vec<CheckTxResult>, RuntimeError> {
+ T::check_batch(&**self, ctx, batch)
+ }
+
+ fn finalize(&self, new_storage_root: Hash) {
+ T::finalize(&**self, new_storage_root)
+ }
+
+ fn set_abort_batch_flag(&mut self, abort_batch: Arc<AtomicBool>) {
+ T::set_abort_batch_flag(&mut **self, abort_batch)
+ }
+
+ fn query(&self, ctx: Context, method: &str, args: Vec<u8>) -> Result<Vec<u8>, RuntimeError> {
+ T::query(&**self, ctx, method, args)
+ }
+}
+
+impl<T: Dispatcher + ?Sized> Dispatcher for Arc<T> {
+ fn execute_batch(
+ &self,
+ ctx: Context,
+ batch: &TxnBatch,
+ in_msgs: &[roothash::IncomingMessage],
+ ) -> Result<ExecuteBatchResult, RuntimeError> {
+ T::execute_batch(&**self, ctx, batch, in_msgs)
+ }
+
+ fn schedule_and_execute_batch(
+ &self,
+ ctx: Context,
+ initial_batch: &mut TxnBatch,
+ in_msgs: &[roothash::IncomingMessage],
+ ) -> Result<ExecuteBatchResult, RuntimeError> {
+ T::schedule_and_execute_batch(&**self, ctx, initial_batch, in_msgs)
+ }
+
+ fn check_batch(
+ &self,
+ ctx: Context,
+ batch: &TxnBatch,
+ ) -> Result<Vec<CheckTxResult>, RuntimeError> {
+ T::check_batch(&**self, ctx, batch)
+ }
+
+ fn finalize(&self, new_storage_root: Hash) {
+ T::finalize(&**self, new_storage_root)
+ }
+
+ fn set_abort_batch_flag(&mut self, _abort_batch: Arc<AtomicBool>) {
+ unimplemented!()
+ }
+
+ fn query(&self, ctx: Context, method: &str, args: Vec<u8>) -> Result<Vec<u8>, RuntimeError> {
+ T::query(&**self, ctx, method, args)
+ }
+}
+
+/// Result of processing an ExecuteTx.
+pub struct ExecuteTxResult {
+ /// Transaction output.
+ pub output: Vec<u8>,
+ /// Emitted tags.
+ pub tags: Tags,
+}
+
+/// Result of processing a batch of ExecuteTx.
+pub struct ExecuteBatchResult {
+ /// Per-transaction execution results.
+ pub results: Vec<ExecuteTxResult>,
+ /// Emitted runtime messages.
+ pub messages: Vec<roothash::Message>,
+ /// Number of processed incoming messages.
+ pub in_msgs_count: usize,
+ /// Block emitted tags (not emitted by a specific transaction).
+ pub block_tags: Tags,
+ /// Hashes of transactions to reject.
+ ///
+ /// Note that these are only taken into account in schedule execution mode.
+ pub tx_reject_hashes: Vec<Hash>,
+}
+
+/// No-op dispatcher.
+///
+/// This is mainly used by the runtime dispatcher as a fallback in case
+/// the runtime's initializer doesn't produce its own dispatcher object.
+#[derive(Default)]
+pub struct NoopDispatcher;
+
+impl Dispatcher for NoopDispatcher {
+ fn is_supported(&self) -> bool {
+ false
+ }
+
+ fn execute_batch(
+ &self,
+ _ctx: Context,
+ _batch: &TxnBatch,
+ in_msgs: &[roothash::IncomingMessage],
+ ) -> Result<ExecuteBatchResult, RuntimeError> {
+ Ok(ExecuteBatchResult {
+ results: Vec::new(),
+ messages: Vec::new(),
+ block_tags: Tags::new(),
+ in_msgs_count: in_msgs.len(),
+ tx_reject_hashes: Vec::new(),
+ })
+ }
+
+ fn schedule_and_execute_batch(
+ &self,
+ _ctx: Context,
+ _initial_batch: &mut TxnBatch,
+ in_msgs: &[roothash::IncomingMessage],
+ ) -> Result<ExecuteBatchResult, RuntimeError> {
+ Ok(ExecuteBatchResult {
+ results: Vec::new(),
+ messages: Vec::new(),
+ block_tags: Tags::new(),
+ in_msgs_count: in_msgs.len(),
+ tx_reject_hashes: Vec::new(),
+ })
+ }
+
+ fn check_batch(
+ &self,
+ _ctx: Context,
+ _batch: &TxnBatch,
+ ) -> Result<Vec<CheckTxResult>, RuntimeError> {
+ Ok(Vec::new())
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +
//! Read/write set.
+
+/// A coarsened key prefix that represents any key that starts with
+/// this prefix.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+#[cbor(transparent)]
+pub struct CoarsenedKey(pub Vec<u8>);
+
+impl AsRef<[u8]> for CoarsenedKey {
+ fn as_ref(&self) -> &[u8] {
+ &self.0
+ }
+}
+
+impl From<CoarsenedKey> for Vec<u8> {
+ fn from(val: CoarsenedKey) -> Self {
+ val.0
+ }
+}
+
+impl From<Vec<u8>> for CoarsenedKey {
+ fn from(v: Vec<u8>) -> CoarsenedKey {
+ CoarsenedKey(v)
+ }
+}
+
+/// A set of coarsened keys.
+pub type CoarsenedSet = Vec<CoarsenedKey>;
+
+/// A read/write set.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct ReadWriteSet {
+ /// Size of the key prefixes (in bytes) used for coarsening the keys.
+ pub granularity: u16,
+ /// The read set.
+ pub read_set: CoarsenedSet,
+ /// The write set.
+ pub write_set: CoarsenedSet,
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ #[test]
+ fn test_serialization() {
+ let rw_set = ReadWriteSet {
+ granularity: 3,
+ read_set: vec![b"foo".to_vec().into(), b"bar".to_vec().into()],
+ write_set: vec![b"moo".to_vec().into()],
+ };
+
+ let enc = cbor::to_vec(rw_set.clone());
+
+ let dec_rw_set: ReadWriteSet = cbor::from_slice(&enc).unwrap();
+ assert_eq!(rw_set, dec_rw_set, "serialization should round-trip");
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +
//! Transaction tags.
+use crate::common::crypto::hash::Hash;
+
+/// Tag is a key/value pair of arbitrary byte blobs with runtime-dependent
+/// semantics which can be indexed to allow easier lookup of blocks and
+/// transactions on runtime clients.
+#[derive(Clone, Debug, Default)]
+pub struct Tag {
+ /// The tag key.
+ pub key: Vec<u8>,
+ /// The tag value.
+ pub value: Vec<u8>,
+ /// The hash of the transaction that emitted the tag.
+ pub tx_hash: Hash,
+}
+
+/// A set of tags.
+pub type Tags = Vec<Tag>;
+
+impl Tag {
+ /// Create a new tag.
+ ///
+ /// The transaction hash is not initialized.
+ pub fn new(key: Vec<u8>, value: Vec<u8>) -> Self {
+ Self {
+ key,
+ value,
+ ..Default::default()
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +
//! Transaction I/O tree.
+use anyhow::{anyhow, Result};
+
+use super::tags::Tags;
+use crate::{
+ common::{crypto::hash::Hash, key_format::KeyFormat},
+ storage::mkvs::{self, sync::ReadSync, Root, WriteLog},
+};
+
+// NOTE: This should be kept in sync with go/runtime/transaction/transaction.go.
+
+#[derive(Debug)]
+#[repr(u8)]
+enum ArtifactKind {
+ Input = 1,
+ Output = 2,
+}
+
+// Workaround because rust doesn't support `as u8` inside match arms.
+// See https://github.com/rust-lang/rust/issues/44266
+const ARTIFACT_KIND_INPUT: u8 = ArtifactKind::Input as u8;
+const ARTIFACT_KIND_OUTPUT: u8 = ArtifactKind::Output as u8;
+
+/// Key format used for transaction artifacts.
+#[derive(Debug)]
+struct TxnKeyFormat {
+ /// Transaction hash.
+ tx_hash: Hash,
+ /// Artifact kind.
+ kind: ArtifactKind,
+}
+
+impl KeyFormat for TxnKeyFormat {
+ fn prefix() -> u8 {
+ b'T'
+ }
+
+ fn size() -> usize {
+ 32 + 1
+ }
+
+ fn encode_atoms(self, atoms: &mut Vec<Vec<u8>>) {
+ atoms.push(self.tx_hash.as_ref().to_vec());
+ match self.kind {
+ ArtifactKind::Input => atoms.push(vec![ARTIFACT_KIND_INPUT]),
+ ArtifactKind::Output => atoms.push(vec![ARTIFACT_KIND_OUTPUT]),
+ }
+ }
+
+ fn decode_atoms(data: &[u8]) -> Self {
+ Self {
+ tx_hash: data[..32].into(),
+ kind: match data[32] {
+ ARTIFACT_KIND_INPUT => ArtifactKind::Input,
+ ARTIFACT_KIND_OUTPUT => ArtifactKind::Output,
+ other => panic!("transaction: malformed artifact kind ({:?})", other),
+ },
+ }
+ }
+}
+
+/// Key format used for emitted tags.
+///
+/// This is kept separate so that clients can query only tags they are
+/// interested in instead of needing to go through all transactions.
+#[derive(Debug, Default)]
+struct TagKeyFormat {
+ /// Tag key.
+ key: Vec<u8>,
+ /// Transaction hash of the transaction that emitted the tag.
+ tx_hash: Hash,
+}
+
+/// Hash used for block emitted tags not tied to a specific transaction.
+pub const TAG_BLOCK_TX_HASH: Hash = Hash([0u8; 32]);
+
+impl KeyFormat for TagKeyFormat {
+ fn prefix() -> u8 {
+ b'E'
+ }
+
+ fn size() -> usize {
+ 32
+ }
+
+ fn encode_atoms(self, atoms: &mut Vec<Vec<u8>>) {
+ atoms.push(self.key);
+ atoms.push(self.tx_hash.as_ref().to_vec());
+ }
+
+ fn decode_atoms(data: &[u8]) -> Self {
+ let offset = data.len() - Self::size();
+ let key = data[0..offset].to_vec();
+ let tx_hash = data[offset..].into();
+
+ Self { key, tx_hash }
+ }
+}
+
+/// The input transaction artifacts.
+///
+/// These are the artifacts that are stored CBOR-serialized in the Merkle tree.
+#[derive(Clone, Debug, Default, PartialEq, cbor::Encode, cbor::Decode)]
+#[cbor(as_array)]
+struct InputArtifacts {
+ /// Transaction input.
+ pub input: Vec<u8>,
+ /// Transaction order within the batch.
+ ///
+ /// This is only relevant within the committee that is processing the batch
+ /// and should be ignored once transactions from multiple committees are
+ /// merged together.
+ pub batch_order: u32,
+}
+
+/// The output transaction artifacts.
+///
+/// These are the artifacts that are stored CBOR-serialized in the Merkle tree.
+#[derive(Clone, Debug, Default, PartialEq, cbor::Encode, cbor::Decode)]
+#[cbor(as_array)]
+struct OutputArtifacts {
+ /// Transaction output.
+ pub output: Vec<u8>,
+}
+
+/// A Merkle tree containing transaction artifacts.
+pub struct Tree {
+ io_root: Root,
+ tree: mkvs::OverlayTree<mkvs::Tree>,
+}
+
+impl Tree {
+ /// Create a new transaction artifacts tree.
+ pub fn new(read_syncer: Box<dyn ReadSync>, io_root: Root) -> Self {
+ Self {
+ io_root,
+ tree: mkvs::OverlayTree::new(
+ mkvs::Tree::builder().with_root(io_root).build(read_syncer),
+ ),
+ }
+ }
+
+ /// Add an input transaction artifact.
+ pub fn add_input(&mut self, input: Vec<u8>, batch_order: u32) -> Result<()> {
+ if input.is_empty() {
+ return Err(anyhow!("transaction: no input given"));
+ }
+
+ let tx_hash = Hash::digest_bytes(&input);
+
+ self.tree.insert(
+ &TxnKeyFormat {
+ tx_hash,
+ kind: ArtifactKind::Input,
+ }
+ .encode(),
+ &cbor::to_vec(InputArtifacts { input, batch_order }),
+ )?;
+
+ Ok(())
+ }
+
+ /// Add an output transaction artifact.
+ pub fn add_output(&mut self, tx_hash: Hash, output: Vec<u8>, tags: Tags) -> Result<()> {
+ self.tree.insert(
+ &TxnKeyFormat {
+ tx_hash,
+ kind: ArtifactKind::Output,
+ }
+ .encode(),
+ &cbor::to_vec(OutputArtifacts { output }),
+ )?;
+
+ // Add tags if specified.
+ for tag in tags {
+ self.tree.insert(
+ &TagKeyFormat {
+ key: tag.key,
+ tx_hash,
+ }
+ .encode(),
+ &tag.value,
+ )?;
+ }
+
+ Ok(())
+ }
+
+ /// Add block tags.
+ pub fn add_block_tags(&mut self, tags: Tags) -> Result<()> {
+ for tag in tags {
+ self.tree.insert(
+ &TagKeyFormat {
+ key: tag.key,
+ tx_hash: TAG_BLOCK_TX_HASH,
+ }
+ .encode(),
+ &tag.value,
+ )?;
+ }
+
+ Ok(())
+ }
+
+ /// Commit updates to the underlying Merkle tree and return the write
+ /// log and root hash.
+ pub fn commit(&mut self) -> Result<(WriteLog, Hash)> {
+ self.tree
+ .commit_both(self.io_root.namespace, self.io_root.version)
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use crate::storage::mkvs::sync::*;
+
+ use super::{super::tags::Tag, *};
+
+ #[test]
+ fn test_transaction() {
+ let mut tree = Tree::new(
+ Box::new(NoopReadSyncer),
+ Root {
+ hash: Hash::empty_hash(),
+ ..Default::default()
+ },
+ );
+
+ let input = b"this goes in".to_vec();
+ let tx_hash = Hash::digest_bytes(&input);
+ tree.add_input(input, 0).unwrap();
+ tree.add_output(
+ tx_hash,
+ b"and this comes out".to_vec(),
+ vec![Tag::new(b"tag1".to_vec(), b"value1".to_vec())],
+ )
+ .unwrap();
+
+ for i in 0..20 {
+ let input = format!("this goes in ({})", i).into_bytes();
+ let tx_hash = Hash::digest_bytes(&input);
+
+ tree.add_input(input, i + 1).unwrap();
+ tree.add_output(
+ tx_hash,
+ b"and this comes out".to_vec(),
+ vec![
+ Tag::new(b"tagA".to_vec(), b"valueA".to_vec()),
+ Tag::new(b"tagB".to_vec(), b"valueB".to_vec()),
+ ],
+ )
+ .unwrap();
+ }
+
+ // NOTE: This root is synced with go/runtime/transaction/transaction_test.go.
+ let (_, root_hash) = tree.commit().unwrap();
+ assert_eq!(
+ format!("{:?}", root_hash),
+ "8399ffa753987b00ec6ab251337c6b88e40812662ed345468fcbf1dbdd16321c",
+ );
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +
//! Transaction protocol types.
+use std::{
+ collections::VecDeque,
+ ops::{Deref, DerefMut},
+};
+
+/// Batch of transaction inputs/outputs.
+#[derive(Clone, Debug, Default, Eq, PartialEq, cbor::Encode, cbor::Decode)]
+#[cbor(transparent)]
+pub struct TxnBatch(pub Vec<Vec<u8>>);
+
+impl TxnBatch {
+ pub fn new(txs: Vec<Vec<u8>>) -> TxnBatch {
+ TxnBatch(txs)
+ }
+}
+
+impl Deref for TxnBatch {
+ type Target = Vec<Vec<u8>>;
+
+ fn deref(&self) -> &Self::Target {
+ &self.0
+ }
+}
+
+impl DerefMut for TxnBatch {
+ fn deref_mut(&mut self) -> &mut Self::Target {
+ &mut self.0
+ }
+}
+
+impl From<Vec<Vec<u8>>> for TxnBatch {
+ fn from(other: Vec<Vec<u8>>) -> TxnBatch {
+ TxnBatch(other)
+ }
+}
+
+impl From<VecDeque<Vec<u8>>> for TxnBatch {
+ fn from(other: VecDeque<Vec<u8>>) -> TxnBatch {
+ TxnBatch(other.into())
+ }
+}
+
+impl From<TxnBatch> for Vec<Vec<u8>> {
+ fn from(val: TxnBatch) -> Self {
+ val.0
+ }
+}
+
+impl From<TxnBatch> for VecDeque<Vec<u8>> {
+ fn from(val: TxnBatch) -> Self {
+ val.0.into()
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ use crate::common::crypto::hash::Hash;
+
+ #[test]
+ fn test_consistent_hash() {
+ let batch = TxnBatch(vec![b"foo".to_vec(), b"bar".to_vec(), b"aaa".to_vec()]);
+ let h = Hash::digest_bytes(&cbor::to_vec(batch));
+ assert_eq!(
+ h,
+ Hash::from("c451dd4fd065b815e784aac6b300e479b2167408f0eebbb95a8bd36b9e71e34d")
+ );
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +
//! Types used by the worker-host protocol.
+use std::collections::BTreeMap;
+
+use thiserror::Error;
+
+use crate::{
+ common::{
+ crypto::{
+ hash::Hash,
+ signature::{self, Signature},
+ x25519,
+ },
+ namespace::Namespace,
+ sgx::{ias::AVR, Quote, QuotePolicy},
+ version::Version,
+ },
+ consensus::{
+ self,
+ beacon::EpochTime,
+ registry::EndorsedCapabilityTEE,
+ roothash::{self, Block, ComputeResultsHeader, Header},
+ state::keymanager::Status as KeyManagerStatus,
+ transaction::{Proof, SignedTransaction},
+ LightBlock,
+ },
+ enclave_rpc,
+ storage::mkvs::{sync, WriteLog},
+ transaction::types::TxnBatch,
+};
+
+/// Computed batch.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct ComputedBatch {
+ /// Compute results header.
+ pub header: ComputeResultsHeader,
+ /// Log that generates the I/O tree.
+ pub io_write_log: WriteLog,
+ /// Log of changes to the state tree.
+ pub state_write_log: WriteLog,
+ /// If this runtime uses a TEE, then this is the signature of the batch's
+ /// BatchSigMessage with the node's RAK for this runtime.
+ pub rak_sig: Signature,
+ /// Messages emitted by the runtime.
+ pub messages: Vec<roothash::Message>,
+}
+
+/// Storage sync request.
+#[derive(Debug, cbor::Encode, cbor::Decode)]
+pub enum StorageSyncRequest {
+ SyncGet(sync::GetRequest),
+ SyncGetPrefixes(sync::GetPrefixesRequest),
+ SyncIterate(sync::IterateRequest),
+}
+
+#[derive(Debug)]
+pub struct StorageSyncRequestWithEndpoint {
+ pub endpoint: HostStorageEndpoint,
+ pub request: StorageSyncRequest,
+}
+
+impl cbor::Encode for StorageSyncRequestWithEndpoint {
+ fn into_cbor_value(self) -> cbor::Value {
+ let mut request = cbor::EncodeAsMap::into_cbor_map(self.request);
+ // Add endpoint to the given map.
+ let key = cbor::values::IntoCborValue::into_cbor_value("endpoint");
+ request.push((key, self.endpoint.into_cbor_value()));
+ cbor::Value::Map(request)
+ }
+}
+
+impl cbor::Decode for StorageSyncRequestWithEndpoint {
+ fn try_from_cbor_value(value: cbor::Value) -> Result<Self, cbor::DecodeError> {
+ match value {
+ cbor::Value::Map(mut items) => {
+ // Take the endpoint field from the map and decode the rest.
+ let key = cbor::values::IntoCborValue::into_cbor_value("endpoint");
+ let (index, _) = items
+ .iter()
+ .enumerate()
+ .find(|(_, v)| v.0 == key)
+ .ok_or(cbor::DecodeError::MissingField)?;
+ let endpoint = items.remove(index).1;
+
+ Ok(Self {
+ endpoint: cbor::Decode::try_from_cbor_value(endpoint)?,
+ request: cbor::Decode::try_from_cbor_value(cbor::Value::Map(items))?,
+ })
+ }
+ _ => Err(cbor::DecodeError::UnexpectedType),
+ }
+ }
+}
+
+/// Storage sync response.
+#[derive(Debug, cbor::Encode, cbor::Decode)]
+pub enum StorageSyncResponse {
+ ProofResponse(sync::ProofResponse),
+}
+
+/// Host storage endpoint.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+#[repr(u8)]
+pub enum HostStorageEndpoint {
+ Runtime = 0,
+ Consensus = 1,
+}
+
+/// Runtime host protocol message body.
+#[derive(Debug, cbor::Encode, cbor::Decode)]
+pub enum Body {
+ // An empty body.
+ Empty {},
+
+ // An error response.
+ Error(Error),
+
+ // Runtime interface.
+ RuntimeInfoRequest(RuntimeInfoRequest),
+ RuntimeInfoResponse(RuntimeInfoResponse),
+ RuntimePingRequest {},
+ RuntimeShutdownRequest {},
+ RuntimeAbortRequest {},
+ RuntimeAbortResponse {},
+ RuntimeCapabilityTEERakInitRequest {
+ target_info: Vec<u8>,
+ },
+ RuntimeCapabilityTEERakInitResponse {},
+ RuntimeCapabilityTEERakReportRequest {},
+ RuntimeCapabilityTEERakReportResponse {
+ rak_pub: signature::PublicKey,
+ rek_pub: x25519::PublicKey,
+ report: Vec<u8>,
+ nonce: String,
+ },
+ RuntimeCapabilityTEERakAvrRequest {
+ avr: AVR,
+ },
+ RuntimeCapabilityTEERakAvrResponse {},
+ RuntimeCapabilityTEERakQuoteRequest {
+ quote: Quote,
+ },
+ RuntimeCapabilityTEERakQuoteResponse {
+ height: u64,
+ signature: Signature,
+ },
+ RuntimeCapabilityTEEUpdateEndorsementRequest {
+ ect: EndorsedCapabilityTEE,
+ },
+ RuntimeCapabilityTEEUpdateEndorsementResponse {},
+ RuntimeRPCCallRequest {
+ request: Vec<u8>,
+ kind: enclave_rpc::types::Kind,
+ peer_id: Vec<u8>,
+ },
+ RuntimeRPCCallResponse {
+ response: Vec<u8>,
+ },
+ RuntimeLocalRPCCallRequest {
+ request: Vec<u8>,
+ },
+ RuntimeLocalRPCCallResponse {
+ response: Vec<u8>,
+ },
+ RuntimeCheckTxBatchRequest {
+ consensus_block: LightBlock,
+ inputs: TxnBatch,
+ block: Block,
+ epoch: EpochTime,
+ max_messages: u32,
+ },
+ RuntimeCheckTxBatchResponse {
+ results: Vec<CheckTxResult>,
+ },
+ RuntimeExecuteTxBatchRequest {
+ #[cbor(optional)]
+ mode: ExecutionMode,
+ consensus_block: LightBlock,
+ round_results: roothash::RoundResults,
+ io_root: Hash,
+ #[cbor(optional)]
+ inputs: Option<TxnBatch>,
+ #[cbor(optional)]
+ in_msgs: Vec<roothash::IncomingMessage>,
+ block: Block,
+ epoch: EpochTime,
+ max_messages: u32,
+ },
+ RuntimeExecuteTxBatchResponse {
+ batch: ComputedBatch,
+
+ tx_hashes: Vec<Hash>,
+ tx_reject_hashes: Vec<Hash>,
+ tx_input_root: Hash,
+ tx_input_write_log: WriteLog,
+ },
+ RuntimeKeyManagerStatusUpdateRequest {
+ status: KeyManagerStatus,
+ },
+ RuntimeKeyManagerStatusUpdateResponse {},
+ RuntimeKeyManagerQuotePolicyUpdateRequest {
+ policy: QuotePolicy,
+ },
+ RuntimeKeyManagerQuotePolicyUpdateResponse {},
+ RuntimeQueryRequest {
+ consensus_block: LightBlock,
+ header: Header,
+ epoch: EpochTime,
+ max_messages: u32,
+ method: String,
+ #[cbor(optional)]
+ args: Vec<u8>,
+ },
+ RuntimeQueryResponse {
+ #[cbor(optional)]
+ data: Vec<u8>,
+ },
+ RuntimeConsensusSyncRequest {
+ height: u64,
+ },
+ RuntimeConsensusSyncResponse {},
+ RuntimeNotifyRequest {
+ #[cbor(optional)]
+ runtime_block: Option<roothash::AnnotatedBlock>,
+ #[cbor(optional)]
+ runtime_event: Option<RuntimeNotifyEvent>,
+ },
+ RuntimeNotifyResponse {},
+
+ // Host interface.
+ HostRPCCallRequest {
+ endpoint: String,
+ request_id: u64,
+ request: Vec<u8>,
+ kind: enclave_rpc::types::Kind,
+ nodes: Vec<signature::PublicKey>,
+ },
+ HostRPCCallResponse {
+ response: Vec<u8>,
+ node: signature::PublicKey,
+ },
+ HostSubmitPeerFeedbackRequest {
+ endpoint: String,
+ request_id: u64,
+ peer_feedback: enclave_rpc::types::PeerFeedback,
+ },
+ HostSubmitPeerFeedbackResponse {},
+ HostStorageSyncRequest(StorageSyncRequestWithEndpoint),
+ HostStorageSyncResponse(StorageSyncResponse),
+ HostLocalStorageGetRequest {
+ key: Vec<u8>,
+ },
+ HostLocalStorageGetResponse {
+ value: Vec<u8>,
+ },
+ HostLocalStorageSetRequest {
+ key: Vec<u8>,
+ value: Vec<u8>,
+ },
+ HostLocalStorageSetResponse {},
+ HostFetchConsensusBlockRequest {
+ height: u64,
+ },
+ HostFetchConsensusBlockResponse {
+ block: LightBlock,
+ },
+ HostFetchConsensusEventsRequest(HostFetchConsensusEventsRequest),
+ HostFetchConsensusEventsResponse(HostFetchConsensusEventsResponse),
+ HostFetchTxBatchRequest {
+ #[cbor(optional)]
+ offset: Option<Hash>,
+ limit: u32,
+ },
+ HostFetchTxBatchResponse {
+ #[cbor(optional)]
+ batch: Option<TxnBatch>,
+ },
+ HostFetchBlockMetadataTxRequest {
+ height: u64,
+ },
+ HostFetchBlockMetadataTxResponse {
+ signed_tx: SignedTransaction,
+ proof: Proof,
+ },
+ HostFetchGenesisHeightRequest {},
+ HostFetchGenesisHeightResponse {
+ height: u64,
+ },
+ HostProveFreshnessRequest {
+ blob: Vec<u8>,
+ },
+ HostProveFreshnessResponse {
+ signed_tx: SignedTransaction,
+ proof: Proof,
+ },
+ HostIdentityRequest {},
+ HostIdentityResponse {
+ node_id: signature::PublicKey,
+ },
+ HostSubmitTxRequest {
+ runtime_id: Namespace,
+ data: Vec<u8>,
+ wait: bool,
+ prove: bool,
+ },
+ HostSubmitTxResponse {
+ output: Vec<u8>,
+ round: u64,
+ batch_order: u32,
+ proof: Option<sync::Proof>,
+ },
+ HostRegisterNotifyRequest {
+ #[cbor(optional)]
+ runtime_block: bool,
+ #[cbor(optional)]
+ runtime_event: Option<RegisterNotifyRuntimeEvent>,
+ },
+ HostRegisterNotifyResponse {},
+}
+
+impl Default for Body {
+ fn default() -> Self {
+ Self::Empty {}
+ }
+}
+
+/// A serializable error.
+#[derive(Clone, Debug, Default, Error, cbor::Encode, cbor::Decode)]
+#[error("module: {module} code: {code} message: {message}")]
+pub struct Error {
+ #[cbor(optional)]
+ pub module: String,
+
+ #[cbor(optional)]
+ pub code: u32,
+
+ #[cbor(optional)]
+ pub message: String,
+}
+
+impl Error {
+ /// Create a new error.
+ pub fn new(module: &str, code: u32, msg: &str) -> Self {
+ Self {
+ module: module.to_owned(),
+ code,
+ message: msg.to_owned(),
+ }
+ }
+}
+
+impl From<anyhow::Error> for Error {
+ fn from(err: anyhow::Error) -> Self {
+ Self {
+ module: "unknown".to_string(),
+ code: 1,
+ message: err.to_string(),
+ }
+ }
+}
+
+/// Runtime information request.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct RuntimeInfoRequest {
+ pub runtime_id: Namespace,
+ pub consensus_backend: String,
+ pub consensus_protocol_version: Version,
+ pub consensus_chain_context: String,
+
+ #[cbor(optional)]
+ pub local_config: BTreeMap<String, cbor::Value>,
+}
+
+/// Set of supported runtime features.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub struct Features {
+ /// Schedule control feature.
+ #[cbor(optional)]
+ pub schedule_control: Option<FeatureScheduleControl>,
+ /// A feature specifying that the runtime supports updating key manager's quote policy.
+ #[cbor(optional)]
+ pub key_manager_quote_policy_updates: bool,
+ /// A feature specifying that the runtime supports updating key manager's status.
+ #[cbor(optional)]
+ pub key_manager_status_updates: bool,
+ /// A feature specifying that the runtime supports endorsed TEE capabilities.
+ #[cbor(optional)]
+ pub endorsed_capability_tee: bool,
+}
+
+impl Default for Features {
+ fn default() -> Self {
+ Self {
+ schedule_control: None,
+ key_manager_quote_policy_updates: true,
+ key_manager_status_updates: true,
+ endorsed_capability_tee: true,
+ }
+ }
+}
+
+/// A feature specifying that the runtime supports controlling the scheduling of batches. This means
+/// that the scheduler should only take priority into account and ignore weights, leaving it up to
+/// the runtime to decide which transactions to include.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct FeatureScheduleControl {
+ /// Size of the initial batch of transactions.
+ pub initial_batch_size: u32,
+}
+
+/// Runtime information response.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct RuntimeInfoResponse {
+ /// The runtime protocol version supported by the runtime.
+ pub protocol_version: Version,
+
+ /// The version of the runtime.
+ pub runtime_version: Version,
+
+ /// Describes the features supported by the runtime.
+ pub features: Features,
+}
+
+/// Batch execution mode.
+#[derive(Clone, Debug, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+#[cbor(with_default)]
+pub enum ExecutionMode {
+ /// Execution mode where the batch of transactions is executed as-is without the ability to
+ /// perform and modifications to the batch.
+ Execute = 0,
+ /// Execution mode where the runtime is in control of scheduling and may arbitrarily modify the
+ /// batch during execution.
+ ///
+ /// This execution mode will only be used in case the runtime advertises to support the schedule
+ /// control feature. In this case the call will only contain up to InitialBatchSize transactions
+ /// and the runtime will need to request more if it needs more.
+ Schedule = 1,
+}
+
+impl Default for ExecutionMode {
+ fn default() -> Self {
+ Self::Execute
+ }
+}
+
+/// Result of a CheckTx operation.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct CheckTxResult {
+ pub error: Error,
+ pub meta: Option<CheckTxMetadata>,
+}
+
+/// CheckTx transaction metadata.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct CheckTxMetadata {
+ #[cbor(optional)]
+ pub priority: u64,
+
+ #[cbor(optional)]
+ pub sender: Vec<u8>,
+ #[cbor(optional)]
+ pub sender_seq: u64,
+ #[cbor(optional)]
+ pub sender_state_seq: u64,
+}
+
+/// Consensus event kind.
+#[derive(Clone, Copy, Debug, cbor::Encode, cbor::Decode)]
+#[repr(u8)]
+pub enum EventKind {
+ Staking = 1,
+ Registry = 2,
+ RootHash = 3,
+ Governance = 4,
+}
+
+/// Request to host to fetch the consensus events for the given height.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct HostFetchConsensusEventsRequest {
+ pub height: u64,
+ pub kind: EventKind,
+}
+
+/// Response from host fetching the consensus events for the given height.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct HostFetchConsensusEventsResponse {
+ pub events: Vec<consensus::Event>,
+}
+
+/// Registration for runtime event notifications.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct RegisterNotifyRuntimeEvent {
+ /// Event tags to subscribe to.
+ pub tags: Vec<Vec<u8>>,
+}
+
+/// An event notification.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct RuntimeNotifyEvent {
+ /// Header of the block that emitted the event.
+ pub block: roothash::AnnotatedBlock,
+ /// Matching tags.
+ pub tags: Vec<Vec<u8>>,
+}
+
+#[derive(Clone, Copy, Debug, cbor::Encode, cbor::Decode)]
+#[repr(u8)]
+pub enum MessageType {
+ /// Invalid message (should never be seen on the wire).
+ Invalid = 0,
+ /// Request.
+ Request = 1,
+ /// Response.
+ Response = 2,
+}
+
+impl Default for MessageType {
+ fn default() -> Self {
+ Self::Invalid
+ }
+}
+
+/// Runtime protocol message.
+#[derive(Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Message {
+ /// Unique request identifier.
+ pub id: u64,
+ /// Message type.
+ pub message_type: MessageType,
+ /// Message body.
+ pub body: Body,
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +
//! Handling of different call formats.
+use std::convert::TryInto;
+
+use anyhow::anyhow;
+use byteorder::{BigEndian, WriteBytesExt};
+use oasis_core_runtime::consensus::beacon;
+use rand_core::{OsRng, RngCore};
+
+use crate::{
+ context::Context,
+ core::common::crypto::{mrae::deoxysii, x25519},
+ crypto::signature::context::get_chain_context_for,
+ keymanager, module,
+ modules::core::Error,
+ state::CurrentState,
+ types::{
+ self,
+ transaction::{Call, CallFormat, CallResult},
+ },
+};
+
+/// Maximum age of an ephemeral key in the number of epochs.
+///
+/// This is half the current window as enforced by the key manager as negative results are not
+/// cached and randomized queries could open the scheme to a potential DoS attack.
+const MAX_EPHEMERAL_KEY_AGE: beacon::EpochTime = 5;
+
+/// Additional metadata required by the result encoding function.
+pub enum Metadata {
+ Empty,
+ EncryptedX25519DeoxysII {
+ /// Caller's ephemeral public key used for X25519.
+ pk: x25519::PublicKey,
+ /// Secret key.
+ sk: x25519::PrivateKey,
+ /// Transaction index within the batch.
+ index: usize,
+ },
+}
+
+impl std::fmt::Debug for Metadata {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ match self {
+ Self::Empty => f.debug_struct("Metadata::Empty").finish(),
+ Self::EncryptedX25519DeoxysII { pk, index, .. } => f
+ .debug_struct("Metadata::EncryptedX25519DeoxysII")
+ .field("pk", pk)
+ .field("index", index)
+ .finish_non_exhaustive(),
+ }
+ }
+}
+
+/// Derive the key pair ID for the call data encryption key pair.
+pub fn get_key_pair_id(epoch: beacon::EpochTime) -> keymanager::KeyPairId {
+ keymanager::get_key_pair_id([
+ get_chain_context_for(types::callformat::CALL_DATA_KEY_PAIR_ID_CONTEXT_BASE).as_slice(),
+ &epoch.to_be_bytes(),
+ ])
+}
+
+fn verify_epoch<C: Context>(ctx: &C, epoch: beacon::EpochTime) -> Result<(), Error> {
+ if epoch > ctx.epoch() {
+ return Err(Error::InvalidCallFormat(anyhow!("epoch in the future")));
+ }
+ if epoch < ctx.epoch().saturating_sub(MAX_EPHEMERAL_KEY_AGE) {
+ return Err(Error::InvalidCallFormat(anyhow!(
+ "epoch too far in the past"
+ )));
+ }
+ Ok(())
+}
+
+/// Decode call arguments.
+///
+/// Returns `Some((Call, Metadata))` when processing should proceed and `None` in case further
+/// execution needs to be deferred (e.g., because key manager access is required).
+pub fn decode_call<C: Context>(
+ ctx: &C,
+ call: Call,
+ index: usize,
+) -> Result<Option<(Call, Metadata)>, Error> {
+ decode_call_ex(ctx, call, index, false /* assume_km_reachable */)
+}
+
+/// Decode call arguments.
+///
+/// Returns `Some((Call, Metadata))` when processing should proceed and `None` in case further
+/// execution needs to be deferred (e.g., because key manager access is required).
+/// If `assume_km_reachable` is set, then this method will return errors instead of `None`.
+pub fn decode_call_ex<C: Context>(
+ ctx: &C,
+ call: Call,
+ index: usize,
+ assume_km_reachable: bool,
+) -> Result<Option<(Call, Metadata)>, Error> {
+ match call.format {
+ // In case of the plain-text data format, we simply pass on the call unchanged.
+ CallFormat::Plain => Ok(Some((call, Metadata::Empty))),
+
+ // Encrypted data format using X25519 key exchange and Deoxys-II symmetric encryption.
+ CallFormat::EncryptedX25519DeoxysII => {
+ // Method must be empty.
+ if !call.method.is_empty() {
+ return Err(Error::InvalidCallFormat(anyhow!("non-empty method")));
+ }
+ // Body needs to follow the specified envelope.
+ let envelope: types::callformat::CallEnvelopeX25519DeoxysII =
+ cbor::from_value(call.body)
+ .map_err(|_| Error::InvalidCallFormat(anyhow!("bad call envelope")))?;
+ let pk = envelope.pk;
+
+ // Make sure a key manager is available in this runtime.
+ let key_manager = ctx
+ .key_manager()
+ .ok_or_else(|| Error::InvalidCallFormat(anyhow!("confidential txs unavailable")))?;
+
+ // If we are only doing checks, this is the most that we can do as in this case we may
+ // be unable to access the key manager.
+ if !assume_km_reachable && CurrentState::with_env(|env| !env.is_execute()) {
+ return Ok(None);
+ }
+
+ let decrypt = |epoch: beacon::EpochTime| {
+ let keypair = key_manager
+ .get_or_create_ephemeral_keys(get_key_pair_id(epoch), epoch)
+ .map_err(|err| match err {
+ keymanager::KeyManagerError::InvalidEpoch(..) => {
+ Error::InvalidCallFormat(anyhow!("invalid epoch"))
+ }
+ _ => Error::Abort(err.into()),
+ })?;
+ let sk = keypair.input_keypair.sk;
+ // Derive shared secret via X25519 and open the sealed box.
+ deoxysii::box_open(
+ &envelope.nonce,
+ envelope.data.clone(),
+ vec![],
+ &envelope.pk.0,
+ &sk.0,
+ )
+ .map(|data| (data, sk))
+ };
+
+ // Get transaction key pair from the key manager. Note that only the `input_keypair`
+ // portion is used.
+ let (data, sk) = if envelope.epoch > 0 {
+ verify_epoch(ctx, envelope.epoch)?;
+ decrypt(envelope.epoch)
+ } else {
+ // In case of failure, also try with previous epoch key in case the epoch
+ // transition just occurred.
+ decrypt(ctx.epoch()).or_else(|_| decrypt(ctx.epoch() - 1))
+ }
+ .map_err(Error::InvalidCallFormat)?;
+
+ let read_only = call.read_only;
+ let call: Call = cbor::from_slice(&data)
+ .map_err(|_| Error::InvalidCallFormat(anyhow!("malformed call")))?;
+
+ // Ensure read-only flag is the same as in the outer envelope. This is to prevent
+ // bypassing any authorization based on the read-only flag.
+ if call.read_only != read_only {
+ return Err(Error::InvalidCallFormat(anyhow!("read-only flag mismatch")));
+ }
+
+ Ok(Some((
+ call,
+ Metadata::EncryptedX25519DeoxysII { pk, sk, index },
+ )))
+ }
+ }
+}
+
+#[cfg(any(test, feature = "test"))]
+/// Encodes a call such that it can be decoded by `decode_call[_ex]`.
+pub fn encode_call<C: Context>(
+ ctx: &C,
+ mut call: Call,
+ client_keypair: &(x25519_dalek::PublicKey, x25519_dalek::StaticSecret),
+) -> Result<Call, Error> {
+ match call.format {
+ // In case of the plain-text data format, we simply pass on the call unchanged.
+ CallFormat::Plain => Ok(call),
+
+ // Encrypted data format using X25519 key exchange and Deoxys-II symmetric encryption.
+ CallFormat::EncryptedX25519DeoxysII => {
+ let key_manager = ctx.key_manager().ok_or_else(|| {
+ Error::InvalidCallFormat(anyhow!("confidential transactions not available"))
+ })?;
+ let epoch = ctx.epoch();
+ let runtime_keypair = key_manager
+ .get_or_create_ephemeral_keys(get_key_pair_id(epoch), epoch)
+ .map_err(|err| Error::Abort(err.into()))?;
+ let runtime_pk = runtime_keypair.input_keypair.pk;
+ let nonce = [0u8; deoxysii::NONCE_SIZE];
+
+ Ok(Call {
+ format: call.format,
+ method: std::mem::take(&mut call.method),
+ body: cbor::to_value(types::callformat::CallEnvelopeX25519DeoxysII {
+ pk: client_keypair.0.into(),
+ nonce,
+ epoch,
+ data: deoxysii::box_seal(
+ &nonce,
+ cbor::to_vec(call),
+ vec![],
+ &runtime_pk.0,
+ &client_keypair.1,
+ )
+ .unwrap(),
+ }),
+ ..Default::default()
+ })
+ }
+ }
+}
+
+/// Encode call results.
+pub fn encode_result<C: Context>(
+ ctx: &C,
+ result: module::CallResult,
+ metadata: Metadata,
+) -> CallResult {
+ encode_result_ex(ctx, result, metadata, false /* expose_failure */)
+}
+
+/// Encode call results.
+///
+/// If `expose_failure` is set, then this method will not encrypt errors.
+pub fn encode_result_ex<C: Context>(
+ ctx: &C,
+ result: module::CallResult,
+ metadata: Metadata,
+ expose_failure: bool,
+) -> CallResult {
+ match metadata {
+ // In case of the plain-text data format, we simply pass on the data unchanged.
+ Metadata::Empty => result.into(),
+
+ // Encrypted data format using X25519 key exchange and Deoxys-II symmetric encryption.
+ Metadata::EncryptedX25519DeoxysII { pk, sk, index } => {
+ // Serialize result.
+ let result: CallResult = result.into();
+
+ if expose_failure {
+ if result.is_success() {
+ return CallResult::Ok(encrypt_result_x25519_deoxysii(
+ ctx, result, pk, sk, index,
+ ));
+ }
+
+ return result;
+ }
+
+ CallResult::Unknown(encrypt_result_x25519_deoxysii(ctx, result, pk, sk, index))
+ }
+ }
+}
+
+/// Encrypt a call result using the X25519-Deoxys-II encryption scheme.
+pub fn encrypt_result_x25519_deoxysii<C: Context>(
+ ctx: &C,
+ result: types::transaction::CallResult,
+ pk: x25519::PublicKey,
+ sk: x25519::PrivateKey,
+ index: usize,
+) -> cbor::Value {
+ let mut nonce = Vec::with_capacity(deoxysii::NONCE_SIZE);
+ if CurrentState::with_env(|env| env.is_execute()) {
+ // In execution mode generate nonce for the output as Round (8 bytes) || Index (4 bytes) || 00 00 00.
+ nonce
+ .write_u64::<BigEndian>(ctx.runtime_header().round)
+ .unwrap();
+ nonce
+ .write_u32::<BigEndian>(index.try_into().unwrap())
+ .unwrap();
+ nonce.extend(&[0, 0, 0]);
+ } else {
+ // In non-execution mode randomize the nonce to facilitate private queries.
+ nonce.resize(deoxysii::NONCE_SIZE, 0);
+ OsRng.fill_bytes(&mut nonce);
+ }
+ let nonce = nonce.try_into().unwrap();
+ let result = cbor::to_vec(result);
+ let data = deoxysii::box_seal(&nonce, result, vec![], &pk.0, &sk.0).unwrap();
+
+ // Return an envelope.
+ cbor::to_value(types::callformat::ResultEnvelopeX25519DeoxysII { nonce, data })
+}
+
+#[cfg(any(test, feature = "test"))]
+pub fn decode_result<C: Context>(
+ ctx: &C,
+ format: CallFormat,
+ result: CallResult,
+ client_keypair: &(x25519_dalek::PublicKey, x25519_dalek::StaticSecret),
+) -> Result<module::CallResult, Error> {
+ if matches!(format, CallFormat::Plain) {
+ return Ok(result.into_call_result().expect("CallResult was Unknown"));
+ }
+ let envelope_value = match result {
+ CallResult::Ok(v) | CallResult::Unknown(v) => v,
+ CallResult::Failed {
+ module,
+ code,
+ message,
+ } => {
+ return Ok(module::CallResult::Failed {
+ module,
+ code,
+ message,
+ })
+ }
+ };
+ match format {
+ CallFormat::Plain => unreachable!("checked above"),
+ CallFormat::EncryptedX25519DeoxysII => {
+ let envelope: types::callformat::ResultEnvelopeX25519DeoxysII =
+ cbor::from_value(envelope_value)
+ .map_err(|_| Error::InvalidCallFormat(anyhow!("bad result envelope")))?;
+
+ // Get the runtime pubkey from the KM. A real client would simply use the
+ // session key that has already been derived.
+ let key_manager = ctx
+ .key_manager()
+ .ok_or_else(|| Error::InvalidCallFormat(anyhow!("confidential txs unavailable")))?;
+ let keypair = key_manager
+ .get_or_create_ephemeral_keys(get_key_pair_id(ctx.epoch()), ctx.epoch())
+ .map_err(|err| Error::Abort(err.into()))?;
+ let runtime_pk = keypair.input_keypair.pk;
+
+ let data = deoxysii::box_open(
+ &envelope.nonce,
+ envelope.data,
+ vec![],
+ &runtime_pk.0,
+ &client_keypair.1,
+ )
+ .map_err(Error::InvalidCallFormat)?;
+ let call_result: CallResult = cbor::from_slice(&data)
+ .map_err(|_| Error::InvalidCallFormat(anyhow!("malformed call")))?;
+ Ok(call_result
+ .into_call_result()
+ .expect("CallResult was Unknown"))
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +
//! Configuration types.
+
+/// Runtime schedule control configuration.
+pub struct ScheduleControl {
+ /// Size of the initial batch that the node should provide to the runtime.
+ pub initial_batch_size: u32,
+ /// Size of each extra batch that the runtime should fetch.
+ pub batch_size: u32,
+ /// Minimum amount of gas that needs to be remaining in a batch in order to still consider
+ /// including new transactions.
+ pub min_remaining_gas: u64,
+ /// Maximum number of transactions that can go in a batch.
+ ///
+ /// This is only used as a last resort to avoid the batch going over the runtime's limit.
+ pub max_tx_count: usize,
+}
+
+impl ScheduleControl {
+ /// Construct a default schedule control configuration.
+ pub const fn default() -> Self {
+ Self {
+ initial_batch_size: 50,
+ batch_size: 50,
+ min_remaining_gas: 1_000,
+ max_tx_count: 1_000,
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +
//! Execution context.
+use std::{collections::btree_map::BTreeMap, marker::PhantomData};
+
+use slog::{self, o};
+
+use oasis_core_runtime::{
+ common::{logger::get_logger, namespace::Namespace},
+ consensus,
+ consensus::roothash,
+ protocol::HostInfo,
+};
+
+use crate::{
+ history,
+ keymanager::KeyManager,
+ module::MethodHandler as _,
+ runtime,
+ state::{self, CurrentState},
+};
+
+/// Local configuration key the value of which determines whether expensive queries should be
+/// allowed or not, and also whether smart contracts should be simulated for `core.EstimateGas`.
+/// DEPRECATED and superseded by LOCAL_CONFIG_ESTIMATE_GAS_BY_SIMULATING_CONTRACTS and LOCAL_CONFIG_ALLOWED_QUERIES.
+const LOCAL_CONFIG_ALLOW_EXPENSIVE_QUERIES: &str = "allow_expensive_queries";
+/// Local configuration key the value of which determines whether smart contracts should
+/// be simulated when estimating gas in `core.EstimateGas`.
+const LOCAL_CONFIG_ESTIMATE_GAS_BY_SIMULATING_CONTRACTS: &str =
+ "estimate_gas_by_simulating_contracts";
+/// Local configuration key the value of which determines the set of allowed queries.
+const LOCAL_CONFIG_ALLOWED_QUERIES: &str = "allowed_queries";
+/// Special key inside the `allowed_queries` list; represents the set of all queries.
+const LOCAL_CONFIG_ALLOWED_QUERIES_ALL: &str = "all";
+/// Special key inside the `allowed_queries` list; represents the set of all queries
+/// that are tagged `expensive`.
+const LOCAL_CONFIG_ALLOWED_QUERIES_ALL_EXPENSIVE: &str = "all_expensive";
+
+/// Runtime SDK context.
+pub trait Context {
+ /// Runtime that the context is being invoked in.
+ type Runtime: runtime::Runtime;
+
+ /// Clone this context.
+ fn clone(&self) -> Self;
+
+ /// Returns a logger.
+ fn get_logger(&self, module: &'static str) -> slog::Logger;
+
+ /// Whether smart contracts should be executed in this context.
+ fn should_execute_contracts(&self) -> bool {
+ match CurrentState::with_env(|env| env.mode()) {
+ // When actually executing a transaction, we always run contracts.
+ state::Mode::Execute => true,
+ state::Mode::Simulate => {
+ // Backwards compatibility for the deprecated `allow_expensive_queries`.
+ if let Some(allow_expensive_queries) =
+ self.local_config::<bool>(LOCAL_CONFIG_ALLOW_EXPENSIVE_QUERIES)
+ {
+ slog::warn!(
+ self.get_logger("runtime-sdk"),
+ "The {} config option is DEPRECATED since April 2022 and will be removed in a future release. Use {} and {} instead.",
+ LOCAL_CONFIG_ALLOW_EXPENSIVE_QUERIES,
+ LOCAL_CONFIG_ESTIMATE_GAS_BY_SIMULATING_CONTRACTS,
+ LOCAL_CONFIG_ALLOWED_QUERIES
+ );
+ return allow_expensive_queries;
+ };
+
+ // The non-deprecated config option.
+ self.local_config(LOCAL_CONFIG_ESTIMATE_GAS_BY_SIMULATING_CONTRACTS)
+ .unwrap_or_default()
+ }
+ // When just checking a transaction, we always want to be fast and skip contracts.
+ state::Mode::Check | state::Mode::PreSchedule => false,
+ }
+ }
+
+ /// Whether `method` is an allowed query per policy in the local config.
+ fn is_allowed_query<R: crate::runtime::Runtime>(&self, method: &str) -> bool {
+ let config: Vec<BTreeMap<String, bool>> = self
+ .local_config(LOCAL_CONFIG_ALLOWED_QUERIES)
+ .unwrap_or_default();
+ let is_expensive = R::Modules::is_expensive_query(method);
+
+ // Backwards compatibility for the deprecated `allow_expensive_queries`.
+ if let Some(allow_expensive_queries) =
+ self.local_config::<bool>(LOCAL_CONFIG_ALLOW_EXPENSIVE_QUERIES)
+ {
+ slog::warn!(
+ self.get_logger("runtime-sdk"),
+ "The {} config option is DEPRECATED since April 2022 and will be removed in a future release. Use {} and {} instead.",
+ LOCAL_CONFIG_ALLOW_EXPENSIVE_QUERIES,
+ LOCAL_CONFIG_ESTIMATE_GAS_BY_SIMULATING_CONTRACTS,
+ LOCAL_CONFIG_ALLOWED_QUERIES
+ );
+ return (!is_expensive) || allow_expensive_queries;
+ };
+
+ // The non-deprecated config option.
+ config
+ .iter()
+ .find_map(|item| {
+ item.get(method)
+ .or_else(|| {
+ if !is_expensive {
+ return None;
+ }
+ item.get(LOCAL_CONFIG_ALLOWED_QUERIES_ALL_EXPENSIVE)
+ })
+ .or_else(|| item.get(LOCAL_CONFIG_ALLOWED_QUERIES_ALL))
+ .copied()
+ })
+ // If no config entry matches, the default is to allow only non-expensive queries.
+ .unwrap_or(!is_expensive)
+ }
+
+ /// Returns node operator-provided local configuration.
+ ///
+ /// This method will always return `None` in `Mode::ExecuteTx` contexts.
+ fn local_config<T>(&self, key: &str) -> Option<T>
+ where
+ T: cbor::Decode,
+ {
+ if CurrentState::with_env(|env| env.is_execute()) {
+ return None;
+ }
+
+ self.host_info().local_config.get(key).and_then(|v| {
+ cbor::from_value(v.clone()).unwrap_or_else(|e| {
+ let msg = format!(
+ "Cannot interpret the value of \"{}\" in runtime's local config as a {}: {:?}",
+ key,
+ std::any::type_name::<T>(),
+ e
+ );
+ slog::error!(self.get_logger("runtime-sdk"), "{}", msg);
+ panic!("{}", msg);
+ })
+ })
+ }
+
+ /// Information about the host environment.
+ fn host_info(&self) -> &HostInfo;
+
+ /// Runtime ID.
+ fn runtime_id(&self) -> &Namespace {
+ &self.host_info().runtime_id
+ }
+
+ /// The key manager, if the runtime is confidential.
+ fn key_manager(&self) -> Option<&dyn KeyManager>;
+
+ /// Whether the context has a key manager available (e.g. the runtime is confidential).
+ fn is_confidential(&self) -> bool {
+ self.key_manager().is_some()
+ }
+
+ /// Last runtime block header.
+ fn runtime_header(&self) -> &roothash::Header;
+
+ /// Results of executing the last successful runtime round.
+ fn runtime_round_results(&self) -> &roothash::RoundResults;
+
+ /// Consensus state.
+ fn consensus_state(&self) -> &consensus::state::ConsensusState;
+
+ /// Historical state.
+ fn history(&self) -> &dyn history::HistoryHost;
+
+ /// Current epoch.
+ fn epoch(&self) -> consensus::beacon::EpochTime;
+
+ /// Maximum number of consensus messages that the runtime can emit in this block.
+ fn max_messages(&self) -> u32;
+}
+
+/// Dispatch context for the whole batch.
+pub struct RuntimeBatchContext<'a, R: runtime::Runtime> {
+ host_info: &'a HostInfo,
+ key_manager: Option<Box<dyn KeyManager>>,
+ runtime_header: &'a roothash::Header,
+ runtime_round_results: &'a roothash::RoundResults,
+ consensus_state: &'a consensus::state::ConsensusState,
+ history: &'a dyn history::HistoryHost,
+ epoch: consensus::beacon::EpochTime,
+ logger: slog::Logger,
+
+ /// Maximum number of messages that can be emitted.
+ max_messages: u32,
+
+ _runtime: PhantomData<R>,
+}
+
+impl<'a, R: runtime::Runtime> RuntimeBatchContext<'a, R> {
+ /// Create a new dispatch context.
+ #[allow(clippy::too_many_arguments)]
+ pub fn new(
+ host_info: &'a HostInfo,
+ key_manager: Option<Box<dyn KeyManager>>,
+ runtime_header: &'a roothash::Header,
+ runtime_round_results: &'a roothash::RoundResults,
+ consensus_state: &'a consensus::state::ConsensusState,
+ history: &'a dyn history::HistoryHost,
+ epoch: consensus::beacon::EpochTime,
+ max_messages: u32,
+ ) -> Self {
+ Self {
+ host_info,
+ runtime_header,
+ runtime_round_results,
+ consensus_state,
+ history,
+ epoch,
+ key_manager,
+ logger: get_logger("runtime-sdk"),
+ max_messages,
+ _runtime: PhantomData,
+ }
+ }
+}
+
+impl<'a, R: runtime::Runtime> Context for RuntimeBatchContext<'a, R> {
+ type Runtime = R;
+
+ fn clone(&self) -> Self {
+ Self {
+ host_info: self.host_info,
+ runtime_header: self.runtime_header,
+ runtime_round_results: self.runtime_round_results,
+ consensus_state: self.consensus_state,
+ history: self.history,
+ epoch: self.epoch,
+ key_manager: self.key_manager.clone(),
+ logger: get_logger("runtime-sdk"),
+ max_messages: self.max_messages,
+ _runtime: PhantomData,
+ }
+ }
+
+ fn get_logger(&self, module: &'static str) -> slog::Logger {
+ self.logger.new(o!("sdk_module" => module))
+ }
+
+ fn host_info(&self) -> &HostInfo {
+ self.host_info
+ }
+
+ fn key_manager(&self) -> Option<&dyn KeyManager> {
+ self.key_manager.as_ref().map(Box::as_ref)
+ }
+
+ fn runtime_header(&self) -> &roothash::Header {
+ self.runtime_header
+ }
+
+ fn runtime_round_results(&self) -> &roothash::RoundResults {
+ self.runtime_round_results
+ }
+
+ fn consensus_state(&self) -> &consensus::state::ConsensusState {
+ self.consensus_state
+ }
+
+ fn history(&self) -> &dyn history::HistoryHost {
+ self.history
+ }
+
+ fn epoch(&self) -> consensus::beacon::EpochTime {
+ self.epoch
+ }
+
+ fn max_messages(&self) -> u32 {
+ self.max_messages
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +
use thiserror::Error;
+
+use crate::crypto::signature::{PublicKey, Signature};
+
+#[cfg(test)]
+mod test;
+
+/// Error.
+#[derive(Error, Debug)]
+pub enum Error {
+ #[error("invalid config")]
+ InvalidConfig,
+ #[error("invalid signature set")]
+ InvalidSignatureSet,
+ #[error("insufficient weight")]
+ InsufficientWeight,
+}
+
+/// One of the signers in a multisig configuration.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct Signer {
+ /// The public key of the signer.
+ pub public_key: PublicKey,
+ /// The weight of the signer.
+ pub weight: u64,
+}
+
+/// A set of signatures corresponding to a multisig configuration.
+/// The indices match the configuration's `signers` vec.
+pub type SignatureSet = [Option<Signature>];
+/// A `SignatureSet` owned in a `Vec`.
+pub type SignatureSetOwned = Vec<Option<Signature>>;
+
+/// A multisig configuration.
+/// A set of signers with total "weight" greater than or equal to a "threshold" can authenticate
+/// for the configuration.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Config {
+ /// The signers.
+ pub signers: Vec<Signer>,
+ /// The threshold.
+ pub threshold: u64,
+}
+
+impl Config {
+ /// Performs some sanity checks. This looks at the configuration only. There is no cryptographic
+ /// verification of any signatures.
+ pub fn validate_basic(&self) -> Result<(), Error> {
+ if self.threshold == 0 {
+ return Err(Error::InvalidConfig);
+ }
+ let mut total: u64 = 0;
+ for (i, signer) in self.signers.iter().enumerate() {
+ if self
+ .signers
+ .iter()
+ .take(i)
+ .any(|other_signer| signer.public_key == other_signer.public_key)
+ {
+ return Err(Error::InvalidConfig);
+ }
+ if signer.weight == 0 {
+ return Err(Error::InvalidConfig);
+ }
+ total = total
+ .checked_add(signer.weight)
+ .ok_or(Error::InvalidConfig)?;
+ }
+ if total < self.threshold {
+ return Err(Error::InvalidConfig);
+ }
+ Ok(())
+ }
+
+ /// Checks that the configuration and signature set are acceptable.
+ /// Returns vectors of public keys and signatures for batch verification of included signatures.
+ pub fn batch(
+ &self,
+ signature_set: &SignatureSet,
+ ) -> Result<(Vec<PublicKey>, Vec<Signature>), Error> {
+ self.validate_basic()?;
+ if signature_set.len() != self.signers.len() {
+ return Err(Error::InvalidSignatureSet);
+ }
+ let mut total = 0;
+ let mut public_keys = vec![];
+ let mut signatures = vec![];
+ for (signer, signature_o) in self.signers.iter().zip(signature_set.iter()) {
+ if let Some(signature) = signature_o {
+ total += signer.weight;
+ public_keys.push(signer.public_key.clone());
+ signatures.push(signature.clone());
+ }
+ }
+ if total < self.threshold {
+ return Err(Error::InsufficientWeight);
+ }
+ Ok((public_keys, signatures))
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +
//! Random number generator based on root VRF key and Merlin transcripts.
+use std::cell::RefCell;
+
+use anyhow::anyhow;
+use merlin::{Transcript, TranscriptRng};
+use rand_core::{CryptoRng, OsRng, RngCore};
+use schnorrkel::keys::{ExpansionMode, Keypair, MiniSecretKey};
+
+use oasis_core_runtime::common::crypto::hash::Hash;
+
+use crate::{
+ context::Context, dispatcher, keymanager::KeyManagerError, modules::core::Error, state::Mode,
+};
+
+/// RNG domain separation context.
+const RNG_CONTEXT: &[u8] = b"oasis-runtime-sdk/crypto: rng v1";
+/// Per-block root VRF key domain separation context.
+const VRF_KEY_CONTEXT: &[u8] = b"oasis-runtime-sdk/crypto: root vrf key v1";
+
+/// A root RNG that can be used to derive domain-separated leaf RNGs.
+pub struct RootRng {
+ inner: RefCell<Inner>,
+ mode: Mode,
+ valid: bool,
+}
+
+struct Inner {
+ /// Merlin transcript for initializing the RNG.
+ transcript: Transcript,
+ /// A transcript-based RNG (when initialized).
+ rng: Option<TranscriptRng>,
+}
+
+impl RootRng {
+ /// Create a new root RNG.
+ pub fn new(mode: Mode) -> Self {
+ Self {
+ inner: RefCell::new(Inner {
+ transcript: Transcript::new(RNG_CONTEXT),
+ rng: None,
+ }),
+ mode,
+ valid: true,
+ }
+ }
+
+ /// Create an invalid root RNG which will fail when any leaf RNGs are requested.
+ pub fn invalid() -> Self {
+ Self {
+ inner: RefCell::new(Inner {
+ transcript: Transcript::new(&[]),
+ rng: None,
+ }),
+ mode: Mode::Simulate, // Use a "safe" mode even though it will never be used.
+ valid: false,
+ }
+ }
+
+ fn derive_root_vrf_key<C: Context + ?Sized>(ctx: &C, mode: Mode) -> Result<Keypair, Error> {
+ let km = ctx
+ .key_manager()
+ .ok_or(Error::Abort(dispatcher::Error::KeyManagerFailure(
+ KeyManagerError::NotInitialized,
+ )))?;
+ let round_header_hash = ctx.runtime_header().encoded_hash();
+ let key_id = crate::keymanager::get_key_pair_id([
+ VRF_KEY_CONTEXT,
+ &[mode as u8],
+ round_header_hash.as_ref(),
+ ]);
+ let km_kp = km
+ .get_or_create_ephemeral_keys(key_id, ctx.epoch())
+ .map_err(|err| Error::Abort(dispatcher::Error::KeyManagerFailure(err)))?
+ .input_keypair;
+ // The KM returns an ed25519 key, but it needs to be in "expanded" form to use with
+ // schnorrkel. Please refer to [`schnorrkel::keys::MiniSecretKey`] for further details.
+ let kp = MiniSecretKey::from_bytes(km_kp.sk.0.as_ref())
+ .map_err(|err| {
+ Error::Abort(dispatcher::Error::KeyManagerFailure(
+ KeyManagerError::Other(anyhow::anyhow!("{}", err)),
+ ))
+ })?
+ .expand_to_keypair(ExpansionMode::Uniform);
+
+ Ok(kp)
+ }
+
+ /// Append local entropy to the root RNG.
+ ///
+ /// # Non-determinism
+ ///
+ /// Using this method will result in the RNG being non-deterministic.
+ pub fn append_local_entropy(&self) {
+ if !self.valid {
+ return;
+ }
+
+ let mut bytes = [0u8; 32];
+ OsRng.fill_bytes(&mut bytes);
+
+ let mut inner = self.inner.borrow_mut();
+ inner.transcript.append_message(b"local-rng", &bytes);
+ }
+
+ /// Append an observed transaction hash to RNG transcript.
+ pub fn append_tx(&self, tx_hash: Hash) {
+ if !self.valid {
+ return;
+ }
+
+ let mut inner = self.inner.borrow_mut();
+ inner.transcript.append_message(b"tx", tx_hash.as_ref());
+ }
+
+ /// Append an observed subcontext to RNG transcript.
+ pub fn append_subcontext(&self) {
+ if !self.valid {
+ return;
+ }
+
+ let mut inner = self.inner.borrow_mut();
+ inner.transcript.append_message(b"subctx", &[]);
+ }
+
+ /// Create an independent leaf RNG using this RNG as its parent.
+ pub fn fork<C: Context + ?Sized>(&self, ctx: &C, pers: &[u8]) -> Result<LeafRng, Error> {
+ if !self.valid {
+ return Err(Error::InvalidArgument(anyhow!("rng is not available")));
+ }
+
+ let mut inner = self.inner.borrow_mut();
+
+ // Ensure the RNG is initialized and initialize it if not.
+ if inner.rng.is_none() {
+ // Derive the root VRF key for the current block.
+ let root_vrf_key = Self::derive_root_vrf_key(ctx, self.mode)?;
+
+ // Initialize the root RNG.
+ let rng = root_vrf_key
+ .vrf_create_hash(&mut inner.transcript)
+ .make_merlin_rng(&[]);
+ inner.rng = Some(rng);
+ }
+
+ // Generate the leaf RNG.
+ inner.transcript.append_message(b"fork", pers);
+
+ let rng_builder = inner.transcript.build_rng();
+ let parent_rng = inner.rng.as_mut().expect("rng must be initialized");
+ let rng = rng_builder.finalize(parent_rng);
+
+ Ok(LeafRng(rng))
+ }
+}
+
+/// A leaf RNG.
+pub struct LeafRng(TranscriptRng);
+
+impl RngCore for LeafRng {
+ fn next_u32(&mut self) -> u32 {
+ self.0.next_u32()
+ }
+
+ fn next_u64(&mut self) -> u64 {
+ self.0.next_u64()
+ }
+
+ fn fill_bytes(&mut self, dest: &mut [u8]) {
+ self.0.fill_bytes(dest)
+ }
+
+ fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), rand_core::Error> {
+ self.0.try_fill_bytes(dest)
+ }
+}
+
+impl CryptoRng for LeafRng {}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ use crate::{state::Mode, testing::mock};
+
+ #[test]
+ fn test_rng_basic() {
+ let mut mock = mock::Mock::default();
+ let ctx = mock.create_ctx_for_runtime::<mock::EmptyRuntime>(true);
+
+ // Create first root RNG.
+ let root_rng = RootRng::new(Mode::Execute);
+
+ let mut leaf_rng = root_rng.fork(&ctx, &[]).expect("rng fork should work");
+ let mut bytes1 = [0u8; 32];
+ leaf_rng.fill_bytes(&mut bytes1);
+
+ let mut leaf_rng = root_rng.fork(&ctx, &[]).expect("rng fork should work");
+ let mut bytes1_1 = [0u8; 32];
+ leaf_rng.fill_bytes(&mut bytes1_1);
+
+ assert_ne!(bytes1, bytes1_1, "rng should apply domain separation");
+
+ // Create second root RNG using the same context so the ephemeral key is shared.
+ let root_rng = RootRng::new(Mode::Execute);
+
+ let mut leaf_rng = root_rng.fork(&ctx, &[]).expect("rng fork should work");
+ let mut bytes2 = [0u8; 32];
+ leaf_rng.fill_bytes(&mut bytes2);
+
+ assert_eq!(bytes1, bytes2, "rng should be deterministic");
+
+ let mut leaf_rng = root_rng.fork(&ctx, &[]).expect("rng fork should work");
+ let mut bytes2_1 = [0u8; 32];
+ leaf_rng.fill_bytes(&mut bytes2_1);
+
+ assert_ne!(bytes2, bytes2_1, "rng should apply domain separation");
+ assert_eq!(bytes1_1, bytes2_1, "rng should be deterministic");
+
+ // Create third root RNG using the same context, but with different personalization.
+ let root_rng = RootRng::new(Mode::Execute);
+
+ let mut leaf_rng = root_rng
+ .fork(&ctx, b"domsep")
+ .expect("rng fork should work");
+ let mut bytes3 = [0u8; 32];
+ leaf_rng.fill_bytes(&mut bytes3);
+
+ assert_ne!(bytes2, bytes3, "rng should apply domain separation");
+
+ // Create another root RNG using the same context, but with different history.
+ let root_rng = RootRng::new(Mode::Execute);
+ root_rng
+ .append_tx("0000000000000000000000000000000000000000000000000000000000000001".into());
+
+ let mut leaf_rng = root_rng.fork(&ctx, &[]).expect("rng fork should work");
+ let mut bytes4 = [0u8; 32];
+ leaf_rng.fill_bytes(&mut bytes4);
+
+ assert_ne!(bytes2, bytes4, "rng should apply domain separation");
+
+ // Create another root RNG using the same context, but with different history.
+ let root_rng = RootRng::new(Mode::Execute);
+ root_rng
+ .append_tx("0000000000000000000000000000000000000000000000000000000000000002".into());
+
+ let mut leaf_rng = root_rng.fork(&ctx, &[]).expect("rng fork should work");
+ let mut bytes5 = [0u8; 32];
+ leaf_rng.fill_bytes(&mut bytes5);
+
+ assert_ne!(bytes4, bytes5, "rng should apply domain separation");
+
+ // Create another root RNG using the same context, but with same history as four.
+ let root_rng = RootRng::new(Mode::Execute);
+ root_rng
+ .append_tx("0000000000000000000000000000000000000000000000000000000000000001".into());
+
+ let mut leaf_rng = root_rng.fork(&ctx, &[]).expect("rng fork should work");
+ let mut bytes6 = [0u8; 32];
+ leaf_rng.fill_bytes(&mut bytes6);
+
+ assert_eq!(bytes4, bytes6, "rng should be deterministic");
+
+ // Create another root RNG using the same context, but with different history.
+ let root_rng = RootRng::new(Mode::Execute);
+ root_rng
+ .append_tx("0000000000000000000000000000000000000000000000000000000000000001".into());
+ root_rng
+ .append_tx("0000000000000000000000000000000000000000000000000000000000000002".into());
+
+ let mut leaf_rng = root_rng.fork(&ctx, &[]).expect("rng fork should work");
+ let mut bytes7 = [0u8; 32];
+ leaf_rng.fill_bytes(&mut bytes7);
+
+ assert_ne!(bytes4, bytes7, "rng should apply domain separation");
+
+ // Create another root RNG using the same context, but with different init point.
+ let root_rng = RootRng::new(Mode::Execute);
+ root_rng
+ .append_tx("0000000000000000000000000000000000000000000000000000000000000001".into());
+ let _ = root_rng.fork(&ctx, &[]).expect("rng fork should work"); // Force init.
+ root_rng
+ .append_tx("0000000000000000000000000000000000000000000000000000000000000002".into());
+
+ let mut leaf_rng = root_rng.fork(&ctx, &[]).expect("rng fork should work");
+ let mut bytes8 = [0u8; 32];
+ leaf_rng.fill_bytes(&mut bytes8);
+
+ assert_ne!(bytes7, bytes8, "rng should apply domain separation");
+ assert_ne!(bytes6, bytes8, "rng should apply domain separation");
+ }
+
+ #[test]
+ fn test_rng_fail_nonconfidential() {
+ let mut mock = mock::Mock::default();
+ let ctx = mock.create_ctx_for_runtime::<mock::EmptyRuntime>(false);
+
+ let root_rng = RootRng::new(Mode::Execute);
+ assert!(
+ root_rng.fork(&ctx, &[]).is_err(),
+ "rng fork should fail on non-confidential runtimes"
+ );
+ }
+
+ #[test]
+ fn test_rng_local_entropy() {
+ let mut mock = mock::Mock::default();
+ let ctx = mock.create_ctx_for_runtime::<mock::EmptyRuntime>(true);
+
+ // Create first root RNG.
+ let root_rng = RootRng::new(Mode::Execute);
+
+ let mut leaf_rng = root_rng.fork(&ctx, &[]).expect("rng fork should work");
+ let mut bytes1 = [0u8; 32];
+ leaf_rng.fill_bytes(&mut bytes1);
+
+ // Create second root RNG using the same context, but mix in local entropy.
+ let root_rng = RootRng::new(Mode::Execute);
+ root_rng.append_local_entropy();
+
+ let mut leaf_rng = root_rng.fork(&ctx, &[]).expect("rng fork should work");
+ let mut bytes2 = [0u8; 32];
+ leaf_rng.fill_bytes(&mut bytes2);
+
+ assert_ne!(bytes1, bytes2, "rng should apply domain separation");
+ }
+
+ #[test]
+ fn test_rng_parent_fork_propagation() {
+ let mut mock = mock::Mock::default();
+ let ctx = mock.create_ctx_for_runtime::<mock::EmptyRuntime>(true);
+
+ // Create first root RNG.
+ let root_rng = RootRng::new(Mode::Execute);
+
+ let mut leaf_rng = root_rng.fork(&ctx, b"a").expect("rng fork should work");
+ let mut bytes1 = [0u8; 32];
+ leaf_rng.fill_bytes(&mut bytes1);
+
+ let mut leaf_rng = root_rng.fork(&ctx, b"a").expect("rng fork should work");
+ let mut bytes1_1 = [0u8; 32];
+ leaf_rng.fill_bytes(&mut bytes1_1);
+
+ // Create second root RNG.
+ let root_rng = RootRng::new(Mode::Execute);
+
+ let mut leaf_rng = root_rng.fork(&ctx, b"b").expect("rng fork should work");
+ let mut bytes2 = [0u8; 32];
+ leaf_rng.fill_bytes(&mut bytes2);
+
+ let mut leaf_rng = root_rng.fork(&ctx, b"a").expect("rng fork should work");
+ let mut bytes2_1 = [0u8; 32];
+ leaf_rng.fill_bytes(&mut bytes2_1);
+
+ assert_ne!(
+ bytes1_1, bytes2_1,
+ "forks should propagate domain separator to parent"
+ );
+ }
+
+ #[test]
+ fn test_rng_invalid() {
+ let mut mock = mock::Mock::default();
+ let ctx = mock.create_ctx_for_runtime::<mock::EmptyRuntime>(true);
+
+ let root_rng = RootRng::invalid();
+ assert!(
+ root_rng.fork(&ctx, b"a").is_err(),
+ "rng fork should fail for invalid rng"
+ );
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +
//! Domain separation context helpers.
+use std::sync::Mutex;
+
+use once_cell::sync::Lazy;
+
+use oasis_core_runtime::common::{crypto::hash::Hash, namespace::Namespace};
+
+const CHAIN_CONTEXT_SEPARATOR: &[u8] = b" for chain ";
+
+static CHAIN_CONTEXT: Lazy<Mutex<Option<Vec<u8>>>> = Lazy::new(Default::default);
+
+/// Return the globally configured chain domain separation context.
+///
+/// The returned domain separation context is computed as:
+///
+/// ```plain
+/// <base> || " for chain " || <chain-context>
+/// ```
+///
+/// # Panics
+///
+/// This function will panic in case the global chain domain separation context was not previously
+/// set using `set_chain_context`.
+///
+pub fn get_chain_context_for(base: &[u8]) -> Vec<u8> {
+ let guard = CHAIN_CONTEXT.lock().unwrap();
+ let chain_context = match guard.as_ref() {
+ Some(cc) => cc,
+ None => {
+ drop(guard); // Avoid poisioning the global lock.
+ panic!("chain domain separation context must be configured");
+ }
+ };
+
+ let mut ctx = vec![0; base.len() + CHAIN_CONTEXT_SEPARATOR.len() + chain_context.len()];
+ ctx[..base.len()].copy_from_slice(base);
+ ctx[base.len()..base.len() + CHAIN_CONTEXT_SEPARATOR.len()]
+ .copy_from_slice(CHAIN_CONTEXT_SEPARATOR);
+ ctx[base.len() + CHAIN_CONTEXT_SEPARATOR.len()..].copy_from_slice(chain_context);
+ ctx
+}
+
+/// Configure the global chain domain separation context.
+///
+/// The domain separation context is computed as:
+///
+/// ```plain
+/// Base-16(H(<runtime-id> || <consensus-chain-context>))
+/// ```
+///
+/// # Panics
+///
+/// This function will panic in case the global chain domain separation context was already set.
+///
+pub fn set_chain_context(runtime_id: Namespace, consensus_chain_context: &str) {
+ let ctx = hex::encode(Hash::digest_bytes_list(&[
+ runtime_id.as_ref(),
+ consensus_chain_context.as_bytes(),
+ ]));
+ let mut guard = CHAIN_CONTEXT.lock().unwrap();
+ if let Some(ref existing) = *guard {
+ if cfg!(any(test, feature = "test")) && existing == ctx.as_bytes() {
+ return;
+ }
+ let ex = String::from_utf8(existing.clone()).unwrap();
+ drop(guard); // Avoid poisioning the global lock.
+ panic!("chain domain separation context already set: {ex}");
+ }
+ *guard = Some(ctx.into_bytes());
+}
+
+/// Test helper to serialize unit tests using the global chain context. The chain context is reset
+/// when this method is called.
+///
+/// # Example
+///
+/// ```rust
+/// # use oasis_runtime_sdk::crypto::signature::context::test_using_chain_context;
+/// let _guard = test_using_chain_context();
+/// // ... rest of the test code follows ...
+/// ```
+#[cfg(any(test, feature = "test"))]
+pub fn test_using_chain_context() -> std::sync::MutexGuard<'static, ()> {
+ static TEST_USING_CHAIN_CONTEXT: Lazy<Mutex<()>> = Lazy::new(Default::default);
+ let guard = TEST_USING_CHAIN_CONTEXT.lock().unwrap();
+ *CHAIN_CONTEXT.lock().unwrap() = None;
+
+ guard
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ #[test]
+ fn test_chain_context() {
+ let _guard = test_using_chain_context();
+ set_chain_context(
+ "8000000000000000000000000000000000000000000000000000000000000000".into(),
+ "643fb06848be7e970af3b5b2d772eb8cfb30499c8162bc18ac03df2f5e22520e",
+ );
+
+ let ctx = get_chain_context_for(b"oasis-runtime-sdk/tx: v0");
+ assert_eq!(&String::from_utf8(ctx).unwrap(), "oasis-runtime-sdk/tx: v0 for chain ca4842870b97a6d5c0d025adce0b6a0dec94d2ba192ede70f96349cfbe3628b9");
+ }
+
+ #[test]
+ fn test_chain_context_not_configured() {
+ let _guard = test_using_chain_context();
+
+ let result = std::panic::catch_unwind(|| get_chain_context_for(b"test"));
+ assert!(result.is_err());
+ }
+
+ #[test]
+ fn test_chain_context_already_configured() {
+ let _guard = test_using_chain_context();
+ set_chain_context(
+ "8000000000000000000000000000000000000000000000000000000000000000".into(),
+ "643fb06848be7e970af3b5b2d772eb8cfb30499c8162bc18ac03df2f5e22520e",
+ );
+
+ let result = std::panic::catch_unwind(|| {
+ set_chain_context(
+ "8000000000000000000000000000000000000000000000000000000000000001".into(),
+ "643fb06848be7e970af3b5b2d772eb8cfb30499c8162bc18ac03df2f5e22520e",
+ )
+ });
+ assert!(result.is_err());
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +
/// A digest that either passes through calls to an actual digest or returns
+/// pre-existing hash bytes..
+///
+/// For signing implementations that require a pre-filled digest instance to
+/// sign instead of plain digest bytes, construct an instance of `DummyDigest`
+/// with the bytes of the hash. The instance will return these bytes when
+/// finalized. It will panic if an attempt is made to update its state.
+///
+/// If it was initialized empty, it will pass all calls through to the actual
+/// digest function, useful for signers that do further internal hashing when
+/// signing.
+pub(crate) struct DummyDigest<D> {
+ underlying: Option<D>,
+ preexisting: Vec<u8>,
+}
+
+impl<D> DummyDigest<D> {
+ pub(crate) fn new_precomputed(bytes: &[u8]) -> Self {
+ Self {
+ underlying: None,
+ preexisting: bytes.to_vec(),
+ }
+ }
+}
+
+impl<D> Default for DummyDigest<D>
+where
+ D: Default,
+{
+ fn default() -> Self {
+ Self {
+ underlying: Some(D::default()),
+ preexisting: Vec::new(),
+ }
+ }
+}
+
+impl<D> Clone for DummyDigest<D>
+where
+ D: Clone,
+{
+ fn clone(&self) -> Self {
+ Self {
+ underlying: self.underlying.clone(),
+ preexisting: self.preexisting.clone(),
+ }
+ }
+}
+
+impl<D> digest::OutputSizeUser for DummyDigest<D>
+where
+ D: digest::OutputSizeUser,
+{
+ type OutputSize = <D as digest::OutputSizeUser>::OutputSize;
+}
+
+impl<D> digest::core_api::BlockSizeUser for DummyDigest<D>
+where
+ D: digest::core_api::BlockSizeUser,
+{
+ type BlockSize = <D as digest::core_api::BlockSizeUser>::BlockSize;
+}
+
+impl<D> digest::FixedOutput for DummyDigest<D>
+where
+ D: digest::FixedOutput,
+{
+ fn finalize_into(self, out: &mut digest::Output<Self>) {
+ if let Some(digest) = self.underlying {
+ digest.finalize_into(out);
+ } else {
+ out.as_mut_slice().copy_from_slice(&self.preexisting);
+ }
+ }
+}
+
+impl<D> digest::FixedOutputReset for DummyDigest<D>
+where
+ D: digest::FixedOutputReset,
+{
+ fn finalize_into_reset(&mut self, out: &mut digest::Output<Self>) {
+ if let Some(digest) = &mut self.underlying {
+ digest.finalize_into_reset(out);
+ } else {
+ out.as_mut_slice().copy_from_slice(&self.preexisting);
+ }
+ }
+}
+
+impl<D> digest::Reset for DummyDigest<D>
+where
+ D: digest::Reset,
+{
+ fn reset(&mut self) {
+ if let Some(ref mut digest) = self.underlying {
+ digest.reset();
+ } else {
+ panic!("mutating dummy digest with precomputed hash");
+ }
+ }
+}
+
+impl<D> digest::Update for DummyDigest<D>
+where
+ D: digest::Update,
+{
+ fn update(&mut self, data: &[u8]) {
+ if let Some(ref mut digest) = self.underlying {
+ digest.update(data);
+ } else {
+ panic!("mutating dummy digest with precomputed hash");
+ }
+ }
+}
+
+impl<D> digest::HashMarker for DummyDigest<D> where D: digest::HashMarker {}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +
//! Ed25519 signatures.
+use std::convert::TryInto;
+
+use base64::prelude::*;
+use curve25519_dalek::{digest::consts::U64, edwards::CompressedEdwardsY};
+use ed25519_dalek::Signer as _;
+use rand_core::RngCore;
+use sha2::{Digest as _, Sha512, Sha512_256};
+
+use oasis_core_runtime::common::crypto::signature::{
+ PublicKey as CorePublicKey, Signature as CoreSignature,
+};
+
+use crate::crypto::signature::{Error, Signature, Signer};
+
+/// An Ed25519 public key.
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, cbor::Encode, cbor::Decode)]
+#[cbor(transparent, no_default)]
+pub struct PublicKey(CorePublicKey);
+
+impl PublicKey {
+ /// Return a byte representation of this public key.
+ pub fn as_bytes(&self) -> &[u8] {
+ self.0.as_ref()
+ }
+
+ /// Construct a public key from a slice of bytes.
+ pub fn from_bytes(bytes: &[u8]) -> Result<Self, Error> {
+ // CorePublicKey::from doesn't support error checking.
+ if bytes.len() != CorePublicKey::len() {
+ return Err(Error::MalformedPublicKey);
+ }
+
+ // Ensure that the public key is a valid compressed point.
+ //
+ // Note: This could do the small order public key check,
+ // but just assume that signature verification will impose
+ // whatever semantics it desires.
+ let a = CompressedEdwardsY::from_slice(bytes).unwrap(); // Length is checked above.
+ let _a = match a.decompress() {
+ Some(point) => point,
+ None => return Err(Error::MalformedPublicKey),
+ };
+
+ Ok(PublicKey(CorePublicKey::from(bytes)))
+ }
+
+ /// Verify a signature.
+ pub fn verify(
+ &self,
+ context: &[u8],
+ message: &[u8],
+ signature: &Signature,
+ ) -> Result<(), Error> {
+ // CoreSignature::from doesn't support error checking either.
+ if signature.0.len() != CoreSignature::len() {
+ return Err(Error::MalformedSignature);
+ }
+ let sig: &[u8] = signature.0.as_ref();
+ let sig = CoreSignature::from(sig);
+
+ sig.verify(&self.0, context, message)
+ .map_err(|_| Error::VerificationFailed)
+ }
+
+ /// Verify signature without applying domain separation.
+ pub fn verify_raw(&self, message: &[u8], signature: &Signature) -> Result<(), Error> {
+ // CoreSignature::from doesn't support error checking either.
+ if signature.0.len() != CoreSignature::len() {
+ return Err(Error::MalformedSignature);
+ }
+ let sig: &[u8] = signature.0.as_ref();
+ let sig = CoreSignature::from(sig);
+
+ sig.verify_raw(&self.0, message)
+ .map_err(|_| Error::VerificationFailed)
+ }
+
+ /// Verify signature of a pre-hashed message.
+ pub fn verify_digest<D>(&self, digest: D, signature: &Signature) -> Result<(), Error>
+ where
+ D: ed25519_dalek::Digest<OutputSize = U64>,
+ {
+ let sig: ed25519_dalek::Signature = signature
+ .as_ref()
+ .try_into()
+ .map_err(|_| Error::MalformedSignature)?;
+ let pk: ed25519_dalek::VerifyingKey = self
+ .as_bytes()
+ .try_into()
+ .map_err(|_| Error::MalformedPublicKey)?;
+ pk.verify_prehashed(digest, None, &sig)
+ .map_err(|_| Error::VerificationFailed)
+ }
+}
+
+impl From<&'static str> for PublicKey {
+ fn from(s: &'static str) -> PublicKey {
+ PublicKey::from_bytes(&BASE64_STANDARD.decode(s).unwrap()).unwrap()
+ }
+}
+
+impl From<CorePublicKey> for PublicKey {
+ fn from(pk: CorePublicKey) -> PublicKey {
+ PublicKey(pk)
+ }
+}
+
+impl From<&CorePublicKey> for PublicKey {
+ fn from(pk: &CorePublicKey) -> PublicKey {
+ PublicKey(*pk)
+ }
+}
+
+impl From<PublicKey> for CorePublicKey {
+ fn from(pk: PublicKey) -> CorePublicKey {
+ pk.0
+ }
+}
+
+/// A memory-backed signer for Ed25519.
+pub struct MemorySigner {
+ key: Key,
+}
+
+/// The original version of the Ed25519 signer returned the "expanded" secret key from `to_bytes`.
+/// A contract may have stored the "expanded" key and expects its use to continue to succeed.
+/// For backwards compatibility, the signer works with both "expanded" and regular keys.
+/// New invocations receive a regular/proper key, and from-"expanded" ones get the old behavior.
+enum Key {
+ Expanded {
+ esk: ed25519_dalek::hazmat::ExpandedSecretKey,
+ /// The hash output that is used to create the "expanded" secret key.
+ /// It is stored to return from `from_bytes` because it is not recoverable from `esk`.
+ hash: zeroize::Zeroizing<[u8; 64]>,
+ },
+ Regular(ed25519_dalek::SigningKey),
+}
+
+impl Key {
+ fn from_bytes(bytes: &[u8]) -> Result<Self, Error> {
+ match bytes.len() {
+ // It's a new/correct-style secret key.
+ 32 => bytes
+ .try_into()
+ .map(ed25519_dalek::SigningKey::from_bytes)
+ .map(Self::Regular)
+ .map_err(|_| Error::MalformedPrivateKey),
+ // It's an "expanded" secret key, which is treated as the output of a 64-byte hash function.
+ 64 => bytes
+ .try_into()
+ .map(|hash| Self::Expanded {
+ esk: ed25519_dalek::hazmat::ExpandedSecretKey::from_bytes(&hash),
+ hash: hash.into(),
+ })
+ .map_err(|_| Error::MalformedPrivateKey),
+ _ => Err(Error::MalformedPrivateKey),
+ }
+ }
+
+ fn to_bytes(&self) -> Vec<u8> {
+ match self {
+ Self::Expanded { hash, .. } => hash.to_vec(),
+ Self::Regular(sk) => sk.to_bytes().to_vec(),
+ }
+ }
+
+ fn sign(&self, message: &[u8]) -> Signature {
+ match self {
+ Self::Expanded { esk, .. } => {
+ let verifying_key = ed25519_dalek::VerifyingKey::from(esk);
+ ed25519_dalek::hazmat::raw_sign::<Sha512>(esk, message, &verifying_key)
+ }
+ Self::Regular(sk) => sk.sign(message),
+ }
+ .to_bytes()
+ .to_vec()
+ .into()
+ }
+
+ fn sign_digest<D>(&self, digest: D) -> Result<Signature, Error>
+ where
+ D: ed25519_dalek::Digest<OutputSize = U64>,
+ {
+ match self {
+ Key::Expanded { esk, .. } => {
+ let verifying_key = ed25519_dalek::VerifyingKey::from(esk);
+ ed25519_dalek::hazmat::raw_sign_prehashed::<Sha512, _>(
+ esk,
+ digest,
+ &verifying_key,
+ None,
+ )
+ }
+ Key::Regular(sk) => sk.sign_prehashed(digest, None),
+ }
+ .map_err(|_| Error::SigningError)
+ .map(|sig| sig.to_bytes().to_vec().into())
+ }
+
+ fn public_key(&self) -> super::PublicKey {
+ let pk = match self {
+ Self::Expanded { esk, .. } => ed25519_dalek::VerifyingKey::from(esk),
+ Self::Regular(sk) => sk.verifying_key(),
+ };
+ super::PublicKey::Ed25519(PublicKey::from_bytes(pk.as_bytes()).unwrap())
+ }
+}
+
+impl MemorySigner {
+ pub fn sign_digest<D>(&self, digest: D) -> Result<Signature, Error>
+ where
+ D: ed25519_dalek::Digest<OutputSize = U64>,
+ {
+ self.key.sign_digest(digest)
+ }
+}
+
+impl Signer for MemorySigner {
+ fn random(rng: &mut impl RngCore) -> Result<Self, Error> {
+ let mut seed = [0u8; 32];
+ rng.fill_bytes(&mut seed);
+ Self::new_from_seed(&seed)
+ }
+
+ fn new_from_seed(seed: &[u8]) -> Result<Self, Error> {
+ if seed.len() != 32 {
+ return Err(Error::MalformedPublicKey);
+ }
+ Self::from_bytes(seed)
+ }
+
+ fn from_bytes(bytes: &[u8]) -> Result<Self, Error> {
+ Ok(Self {
+ key: Key::from_bytes(bytes)?,
+ })
+ }
+
+ fn to_bytes(&self) -> Vec<u8> {
+ self.key.to_bytes()
+ }
+
+ fn public_key(&self) -> super::PublicKey {
+ self.key.public_key()
+ }
+
+ fn sign(&self, context: &[u8], message: &[u8]) -> Result<Signature, Error> {
+ let mut digest = Sha512_256::new();
+ digest.update(context);
+ digest.update(message);
+ Ok(self.key.sign(&digest.finalize()))
+ }
+
+ fn sign_raw(&self, message: &[u8]) -> Result<Signature, Error> {
+ Ok(self.key.sign(message))
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ #[test]
+ fn legacy_esk_equivalence() {
+ let seed = [42u8; 32];
+ let signer = MemorySigner::new_from_seed(&seed).unwrap();
+
+ let esk = ed25519_dalek::hazmat::ExpandedSecretKey::from(&seed);
+ let esk_hash = Sha512::digest(seed);
+ let esk_signer = MemorySigner::from_bytes(&esk_hash).unwrap();
+
+ let esk_public_key = super::super::PublicKey::Ed25519(
+ PublicKey::from_bytes(&ed25519_dalek::VerifyingKey::from(&esk).to_bytes()).unwrap(),
+ );
+
+ assert_eq!(
+ esk_signer.to_bytes().as_slice(),
+ esk_hash.as_slice(),
+ "esk roundtrip"
+ );
+ assert_eq!(signer.to_bytes(), seed, "sk roundtrip");
+
+ let context = b"tests";
+ let message = b"hello, world!";
+ let digest = Sha512::new().chain_update(context).chain_update(message);
+
+ let sig = signer.sign(context, message).unwrap();
+ let esk_sig = esk_signer.sign(context, message).unwrap();
+ assert_eq!(sig, esk_sig, "sig != esk_sig");
+
+ let raw_sig = signer.sign_raw(message).unwrap();
+ let esk_raw_sig = esk_signer.sign_raw(message).unwrap();
+ assert_eq!(raw_sig, esk_raw_sig, "raw_sig != esk_raw_sig");
+
+ let digest_sig = signer.sign_digest(digest.clone()).unwrap();
+ let esk_digest_sig = esk_signer.sign_digest(digest).unwrap();
+ assert_eq!(digest_sig, esk_digest_sig, "digest_sig != esk_digest_sig");
+
+ assert_eq!(
+ signer.public_key(),
+ esk_public_key,
+ "signer pk != esk_public_key"
+ );
+ assert_eq!(
+ esk_signer.public_key(),
+ esk_public_key,
+ "esk_signer pk != esk_pubic_key"
+ );
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +765 +766 +767 +768 +769 +770 +771 +772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +
//! Cryptographic signatures.
+use std::convert::TryFrom;
+
+use digest::{typenum::Unsigned as _, Digest as _};
+use rand_core::RngCore;
+use thiserror::Error;
+
+use crate::core::common::crypto::signature::{PublicKey as CorePublicKey, Signer as CoreSigner};
+
+pub mod context;
+mod digests;
+pub mod ed25519;
+pub mod secp256k1;
+pub mod secp256r1;
+pub mod secp384r1;
+pub mod sr25519;
+
+/// A specific combination of signature and hash.
+#[allow(non_camel_case_types)]
+#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq, PartialOrd, Ord, cbor::Encode, cbor::Decode)]
+pub enum SignatureType {
+ #[cbor(rename = "ed25519_oasis")]
+ Ed25519_Oasis,
+ #[cbor(rename = "ed25519_pure")]
+ Ed25519_Pure,
+ #[cbor(rename = "ed25519_prehashed_sha512")]
+ Ed25519_PrehashedSha512,
+ #[cbor(rename = "secp256k1_oasis")]
+ Secp256k1_Oasis,
+ #[cbor(rename = "secp256k1_prehashed_keccak256")]
+ Secp256k1_PrehashedKeccak256,
+ #[cbor(rename = "secp256k1_prehashed_sha256")]
+ Secp256k1_PrehashedSha256,
+ #[cbor(rename = "sr25519")]
+ Sr25519,
+ #[cbor(rename = "secp256r1_prehashed_sha256")]
+ Secp256r1_PrehashedSha256,
+ #[cbor(rename = "secp384r1_prehashed_sha384")]
+ Secp384r1_PrehashedSha384,
+}
+
+impl SignatureType {
+ pub fn as_int(&self) -> u8 {
+ match self {
+ Self::Ed25519_Oasis => 0,
+ Self::Ed25519_Pure => 1,
+ Self::Ed25519_PrehashedSha512 => 2,
+ Self::Secp256k1_Oasis => 3,
+ Self::Secp256k1_PrehashedKeccak256 => 4,
+ Self::Secp256k1_PrehashedSha256 => 5,
+ Self::Sr25519 => 6,
+ Self::Secp256r1_PrehashedSha256 => 7,
+ Self::Secp384r1_PrehashedSha384 => 8,
+ }
+ }
+
+ pub fn is_prehashed(&self) -> bool {
+ matches!(
+ self,
+ Self::Ed25519_PrehashedSha512
+ | Self::Secp256k1_PrehashedKeccak256
+ | Self::Secp256k1_PrehashedSha256
+ | Self::Secp256r1_PrehashedSha256
+ | Self::Secp384r1_PrehashedSha384
+ )
+ }
+
+ pub fn is_ed25519_variant(&self) -> bool {
+ matches!(
+ self,
+ Self::Ed25519_Oasis | Self::Ed25519_Pure | Self::Ed25519_PrehashedSha512
+ )
+ }
+
+ pub fn is_secp256k1_variant(&self) -> bool {
+ matches!(
+ self,
+ Self::Secp256k1_Oasis
+ | Self::Secp256k1_PrehashedKeccak256
+ | Self::Secp256k1_PrehashedSha256
+ )
+ }
+
+ pub fn is_secp256r1_variant(&self) -> bool {
+ matches!(self, Self::Secp256r1_PrehashedSha256)
+ }
+
+ pub fn is_secp384r1_variant(&self) -> bool {
+ matches!(self, Self::Secp384r1_PrehashedSha384)
+ }
+}
+
+impl TryFrom<u8> for SignatureType {
+ type Error = Error;
+
+ fn try_from(value: u8) -> Result<Self, Self::Error> {
+ match value {
+ 0 => Ok(Self::Ed25519_Oasis),
+ 1 => Ok(Self::Ed25519_Pure),
+ 2 => Ok(Self::Ed25519_PrehashedSha512),
+ 3 => Ok(Self::Secp256k1_Oasis),
+ 4 => Ok(Self::Secp256k1_PrehashedKeccak256),
+ 5 => Ok(Self::Secp256k1_PrehashedSha256),
+ 6 => Ok(Self::Sr25519),
+ 7 => Ok(Self::Secp256r1_PrehashedSha256),
+ 8 => Ok(Self::Secp384r1_PrehashedSha384),
+ _ => Err(Error::InvalidArgument),
+ }
+ }
+}
+
+/// A public key used for signing.
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, cbor::Encode, cbor::Decode)]
+pub enum PublicKey {
+ #[cbor(rename = "ed25519")]
+ Ed25519(ed25519::PublicKey),
+
+ #[cbor(rename = "secp256k1")]
+ Secp256k1(secp256k1::PublicKey),
+
+ #[cbor(rename = "secp256r1")]
+ Secp256r1(secp256r1::PublicKey),
+
+ #[cbor(rename = "secp384r1")]
+ Secp384r1(secp384r1::PublicKey),
+
+ #[cbor(rename = "sr25519")]
+ Sr25519(sr25519::PublicKey),
+}
+
+/// Error.
+#[derive(Error, Debug)]
+pub enum Error {
+ #[error("malformed public key")]
+ MalformedPublicKey,
+ #[error("malformed private key")]
+ MalformedPrivateKey,
+ #[error("malformed signature")]
+ MalformedSignature,
+ #[error("signature verification failed")]
+ VerificationFailed,
+ #[error("invalid argument")]
+ InvalidArgument,
+ #[error("invalid digest length")]
+ InvalidDigestLength,
+ #[error("other signing error")]
+ SigningError,
+}
+
+impl PublicKey {
+ /// Return the key type as string.
+ pub fn key_type(&self) -> &str {
+ match self {
+ Self::Ed25519(_) => "ed25519",
+ Self::Secp256k1(_) => "secp256k1",
+ Self::Secp256r1(_) => "secp256r1",
+ Self::Secp384r1(_) => "secp384r1",
+ Self::Sr25519(_) => "sr25519",
+ }
+ }
+
+ /// Return a byte representation of this public key.
+ pub fn as_bytes(&self) -> &[u8] {
+ match self {
+ PublicKey::Ed25519(pk) => pk.as_bytes(),
+ PublicKey::Secp256k1(pk) => pk.as_bytes(),
+ PublicKey::Secp256r1(pk) => pk.as_bytes(),
+ PublicKey::Secp384r1(pk) => pk.as_bytes(),
+ PublicKey::Sr25519(pk) => pk.as_bytes(),
+ }
+ }
+
+ /// Construct a public key from a slice of bytes.
+ pub fn from_bytes(sig_type: SignatureType, bytes: &[u8]) -> Result<Self, Error> {
+ match sig_type {
+ SignatureType::Ed25519_Oasis
+ | SignatureType::Ed25519_Pure
+ | SignatureType::Ed25519_PrehashedSha512 => {
+ Ok(Self::Ed25519(ed25519::PublicKey::from_bytes(bytes)?))
+ }
+ SignatureType::Secp256k1_Oasis
+ | SignatureType::Secp256k1_PrehashedKeccak256
+ | SignatureType::Secp256k1_PrehashedSha256 => {
+ Ok(Self::Secp256k1(secp256k1::PublicKey::from_bytes(bytes)?))
+ }
+ SignatureType::Secp256r1_PrehashedSha256 => {
+ Ok(Self::Secp256r1(secp256r1::PublicKey::from_bytes(bytes)?))
+ }
+ SignatureType::Secp384r1_PrehashedSha384 => {
+ Ok(Self::Secp384r1(secp384r1::PublicKey::from_bytes(bytes)?))
+ }
+ SignatureType::Sr25519 => Ok(Self::Sr25519(sr25519::PublicKey::from_bytes(bytes)?)),
+ }
+ }
+
+ /// Verify a signature.
+ pub fn verify(
+ &self,
+ context: &[u8],
+ message: &[u8],
+ signature: &Signature,
+ ) -> Result<(), Error> {
+ match self {
+ PublicKey::Ed25519(pk) => pk.verify(context, message, signature),
+ PublicKey::Secp256k1(pk) => pk.verify(context, message, signature),
+ PublicKey::Secp256r1(pk) => pk.verify(context, message, signature),
+ PublicKey::Secp384r1(pk) => pk.verify(context, message, signature),
+ PublicKey::Sr25519(pk) => pk.verify(context, message, signature),
+ }
+ }
+
+ /// Verify signature raw using the underlying method, without the domain
+ /// separation schema.
+ pub fn verify_raw(&self, message: &[u8], signature: &Signature) -> Result<(), Error> {
+ match self {
+ PublicKey::Ed25519(pk) => pk.verify_raw(message, signature),
+ PublicKey::Secp256k1(pk) => pk.verify_raw(message, signature),
+ PublicKey::Secp256r1(pk) => pk.verify_raw(message, signature),
+ PublicKey::Secp384r1(pk) => pk.verify_raw(message, signature),
+ PublicKey::Sr25519(_) => Err(Error::InvalidArgument),
+ }
+ }
+
+ /// Verify the signature of a message.
+ pub fn verify_by_type(
+ &self,
+ signature_type: SignatureType,
+ context_or_hash: &[u8],
+ message: &[u8],
+ signature: &Signature,
+ ) -> Result<(), Error> {
+ match self {
+ Self::Ed25519(pk) => match signature_type {
+ SignatureType::Ed25519_Oasis => pk.verify(context_or_hash, message, signature),
+ SignatureType::Ed25519_Pure => pk.verify_raw(message, signature),
+ SignatureType::Ed25519_PrehashedSha512 => {
+ if context_or_hash.len()
+ != <sha2::Sha512 as sha2::digest::OutputSizeUser>::OutputSize::USIZE
+ {
+ return Err(Error::InvalidArgument);
+ }
+ let digest =
+ digests::DummyDigest::<sha2::Sha512>::new_precomputed(context_or_hash);
+ pk.verify_digest(digest, signature)
+ }
+ _ => Err(Error::InvalidArgument),
+ },
+ Self::Secp256k1(pk) => match signature_type {
+ SignatureType::Secp256k1_Oasis => pk.verify(context_or_hash, message, signature),
+ SignatureType::Secp256k1_PrehashedKeccak256 => {
+ if context_or_hash.len()
+ != <sha3::Keccak256 as sha3::digest::OutputSizeUser>::OutputSize::USIZE
+ {
+ return Err(Error::InvalidArgument);
+ }
+ // Use SHA-256 for RFC6979 even if Keccak256 was used for the message.
+ let digest = digests::DummyDigest::<k256::sha2::Sha256>::new_precomputed(
+ context_or_hash,
+ );
+ pk.verify_digest(digest, signature)
+ }
+ SignatureType::Secp256k1_PrehashedSha256 => {
+ if context_or_hash.len()
+ != <sha2::Sha256 as sha2::digest::OutputSizeUser>::OutputSize::USIZE
+ {
+ return Err(Error::InvalidArgument);
+ }
+ let digest = digests::DummyDigest::<k256::sha2::Sha256>::new_precomputed(
+ context_or_hash,
+ );
+ pk.verify_digest(digest, signature)
+ }
+ _ => Err(Error::InvalidArgument),
+ },
+ Self::Secp256r1(pk) => match signature_type {
+ SignatureType::Secp256r1_PrehashedSha256 => {
+ if context_or_hash.len()
+ != <sha2::Sha256 as sha2::digest::OutputSizeUser>::OutputSize::USIZE
+ {
+ return Err(Error::InvalidArgument);
+ }
+ let digest =
+ digests::DummyDigest::<sha2::Sha256>::new_precomputed(context_or_hash);
+ pk.verify_digest(digest, signature)
+ }
+ _ => Err(Error::InvalidArgument),
+ },
+ Self::Secp384r1(pk) => match signature_type {
+ SignatureType::Secp384r1_PrehashedSha384 => {
+ if context_or_hash.len()
+ != <sha2::Sha384 as sha2::digest::OutputSizeUser>::OutputSize::USIZE
+ {
+ return Err(Error::InvalidArgument);
+ }
+ let digest =
+ digests::DummyDigest::<sha2::Sha384>::new_precomputed(context_or_hash);
+ pk.verify_digest(digest, signature)
+ }
+ _ => Err(Error::InvalidArgument),
+ },
+ Self::Sr25519(_) => Err(Error::InvalidArgument),
+ }
+ }
+
+ /// Verify a batch of signatures of the same message.
+ pub fn verify_batch_multisig(
+ context: &[u8],
+ message: &[u8],
+ public_keys: &[PublicKey],
+ signatures: &[Signature],
+ ) -> Result<(), Error> {
+ if public_keys.len() != signatures.len() {
+ return Err(Error::InvalidArgument);
+ }
+
+ // TODO: Use actual batch verification.
+ for (pk, sig) in public_keys.iter().zip(signatures.iter()) {
+ pk.verify(context, message, sig)?;
+ }
+ Ok(())
+ }
+}
+
+impl AsRef<[u8]> for PublicKey {
+ fn as_ref(&self) -> &[u8] {
+ self.as_bytes()
+ }
+}
+
+impl PartialEq<CorePublicKey> for PublicKey {
+ fn eq(&self, other: &CorePublicKey) -> bool {
+ match self {
+ PublicKey::Ed25519(pk) => pk.as_bytes() == other.as_ref(),
+ _ => false,
+ }
+ }
+}
+
+impl TryFrom<PublicKey> for CorePublicKey {
+ type Error = &'static str;
+
+ fn try_from(pk: PublicKey) -> Result<Self, Self::Error> {
+ match pk {
+ PublicKey::Ed25519(pk) => Ok(pk.into()),
+ _ => Err("not an Ed25519 public key"),
+ }
+ }
+}
+
+impl From<CorePublicKey> for PublicKey {
+ fn from(pk: CorePublicKey) -> Self {
+ Self::Ed25519(pk.into())
+ }
+}
+
+/// Variable-length opaque signature.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+#[cbor(transparent)]
+pub struct Signature(Vec<u8>);
+
+impl AsRef<[u8]> for Signature {
+ fn as_ref(&self) -> &[u8] {
+ &self.0
+ }
+}
+
+impl From<Vec<u8>> for Signature {
+ fn from(v: Vec<u8>) -> Signature {
+ Signature(v)
+ }
+}
+
+impl From<Signature> for Vec<u8> {
+ fn from(s: Signature) -> Vec<u8> {
+ s.0
+ }
+}
+
+/// Common trait for memory signers.
+pub trait Signer: Send + Sync {
+ /// Create a new random signer.
+ fn random(rng: &mut impl RngCore) -> Result<Self, Error>
+ where
+ Self: Sized;
+
+ /// Create a new signer from the given seed.
+ fn new_from_seed(seed: &[u8]) -> Result<Self, Error>
+ where
+ Self: Sized;
+
+ /// Recreate signer from a byte serialization.
+ fn from_bytes(bytes: &[u8]) -> Result<Self, Error>
+ where
+ Self: Sized;
+
+ /// Serialize the signer into bytes.
+ fn to_bytes(&self) -> Vec<u8>;
+
+ /// Return the public key counterpart to the signer's secret key.
+ fn public_key(&self) -> PublicKey;
+
+ /// Generate a signature over the context and message.
+ fn sign(&self, context: &[u8], message: &[u8]) -> Result<Signature, Error>;
+
+ /// Generate a signature over the message.
+ fn sign_raw(&self, message: &[u8]) -> Result<Signature, Error>;
+}
+
+impl<T: Signer + ?Sized> Signer for std::sync::Arc<T> {
+ fn random(_rng: &mut impl RngCore) -> Result<Self, Error>
+ where
+ Self: Sized,
+ {
+ Err(Error::InvalidArgument)
+ }
+
+ fn new_from_seed(_seed: &[u8]) -> Result<Self, Error>
+ where
+ Self: Sized,
+ {
+ Err(Error::InvalidArgument)
+ }
+
+ fn from_bytes(_bytes: &[u8]) -> Result<Self, Error>
+ where
+ Self: Sized,
+ {
+ Err(Error::InvalidArgument)
+ }
+
+ fn to_bytes(&self) -> Vec<u8> {
+ T::to_bytes(self)
+ }
+
+ fn public_key(&self) -> PublicKey {
+ T::public_key(self)
+ }
+
+ fn sign(&self, context: &[u8], message: &[u8]) -> Result<Signature, Error> {
+ T::sign(self, context, message)
+ }
+
+ fn sign_raw(&self, message: &[u8]) -> Result<Signature, Error> {
+ T::sign_raw(self, message)
+ }
+}
+
+impl<T: CoreSigner> Signer for &T {
+ fn random(_rng: &mut impl RngCore) -> Result<Self, Error>
+ where
+ Self: Sized,
+ {
+ Err(Error::InvalidArgument)
+ }
+
+ fn new_from_seed(_seed: &[u8]) -> Result<Self, Error>
+ where
+ Self: Sized,
+ {
+ Err(Error::InvalidArgument)
+ }
+
+ fn from_bytes(_bytes: &[u8]) -> Result<Self, Error>
+ where
+ Self: Sized,
+ {
+ Err(Error::InvalidArgument)
+ }
+
+ fn to_bytes(&self) -> Vec<u8> {
+ vec![]
+ }
+
+ fn public_key(&self) -> PublicKey {
+ PublicKey::Ed25519(self.public().into())
+ }
+
+ fn sign(&self, context: &[u8], message: &[u8]) -> Result<Signature, Error> {
+ let raw_sig = CoreSigner::sign(*self, context, message).map_err(|_| Error::SigningError)?;
+ Ok(Signature(raw_sig.as_ref().into()))
+ }
+
+ fn sign_raw(&self, _message: &[u8]) -> Result<Signature, Error> {
+ Err(Error::InvalidArgument)
+ }
+}
+
+impl Signer for crate::core::identity::Identity {
+ fn random(_rng: &mut impl RngCore) -> Result<Self, Error>
+ where
+ Self: Sized,
+ {
+ Err(Error::InvalidArgument)
+ }
+
+ fn new_from_seed(_seed: &[u8]) -> Result<Self, Error>
+ where
+ Self: Sized,
+ {
+ Err(Error::InvalidArgument)
+ }
+
+ fn from_bytes(_bytes: &[u8]) -> Result<Self, Error>
+ where
+ Self: Sized,
+ {
+ Err(Error::InvalidArgument)
+ }
+
+ fn to_bytes(&self) -> Vec<u8> {
+ vec![]
+ }
+
+ fn public_key(&self) -> PublicKey {
+ PublicKey::Ed25519(self.public().into())
+ }
+
+ fn sign(&self, context: &[u8], message: &[u8]) -> Result<Signature, Error> {
+ let raw_sig = CoreSigner::sign(self, context, message).map_err(|_| Error::SigningError)?;
+ Ok(Signature(raw_sig.as_ref().into()))
+ }
+
+ fn sign_raw(&self, _message: &[u8]) -> Result<Signature, Error> {
+ Err(Error::InvalidArgument)
+ }
+}
+
+/// A memory-backed signer.
+pub enum MemorySigner {
+ Ed25519(ed25519::MemorySigner),
+ Secp256k1(secp256k1::MemorySigner),
+ Secp256r1(secp256r1::MemorySigner),
+ Secp384r1(secp384r1::MemorySigner),
+}
+
+impl MemorySigner {
+ /// Create a new memory signer from a seed.
+ pub fn new_from_seed(sig_type: SignatureType, seed: &[u8]) -> Result<Self, Error> {
+ if sig_type.is_ed25519_variant() {
+ Ok(Self::Ed25519(ed25519::MemorySigner::new_from_seed(seed)?))
+ } else if sig_type.is_secp256k1_variant() {
+ Ok(Self::Secp256k1(secp256k1::MemorySigner::new_from_seed(
+ seed,
+ )?))
+ } else if sig_type.is_secp256r1_variant() {
+ Ok(Self::Secp256r1(secp256r1::MemorySigner::new_from_seed(
+ seed,
+ )?))
+ } else if sig_type.is_secp384r1_variant() {
+ Ok(Self::Secp384r1(secp384r1::MemorySigner::new_from_seed(
+ seed,
+ )?))
+ } else {
+ Err(Error::InvalidArgument)
+ }
+ }
+
+ /// Create a new signer for testing purposes.
+ pub fn new_test(sig_type: SignatureType, name: &str) -> Self {
+ if sig_type.is_secp384r1_variant() {
+ Self::new_from_seed(sig_type, &sha2::Sha384::digest(name)).unwrap()
+ } else {
+ Self::new_from_seed(sig_type, &sha2::Sha512_256::digest(name)).unwrap()
+ }
+ }
+
+ /// Reconstruct the signer from its byte representation.
+ pub fn from_bytes(sig_type: SignatureType, bytes: &[u8]) -> Result<Self, Error> {
+ if sig_type.is_ed25519_variant() {
+ Ok(Self::Ed25519(ed25519::MemorySigner::from_bytes(bytes)?))
+ } else if sig_type.is_secp256k1_variant() {
+ Ok(Self::Secp256k1(secp256k1::MemorySigner::from_bytes(bytes)?))
+ } else if sig_type.is_secp256r1_variant() {
+ Ok(Self::Secp256r1(secp256r1::MemorySigner::from_bytes(bytes)?))
+ } else if sig_type.is_secp384r1_variant() {
+ Ok(Self::Secp384r1(secp384r1::MemorySigner::from_bytes(bytes)?))
+ } else {
+ Err(Error::InvalidArgument)
+ }
+ }
+
+ /// Return a byte representation of the signer.
+ pub fn to_bytes(&self) -> Vec<u8> {
+ match self {
+ Self::Ed25519(signer) => signer.to_bytes(),
+ Self::Secp256k1(signer) => signer.to_bytes(),
+ Self::Secp256r1(signer) => signer.to_bytes(),
+ Self::Secp384r1(signer) => signer.to_bytes(),
+ }
+ }
+
+ /// Public key corresponding to the signer.
+ pub fn public_key(&self) -> PublicKey {
+ match self {
+ Self::Ed25519(signer) => signer.public_key(),
+ Self::Secp256k1(signer) => signer.public_key(),
+ Self::Secp256r1(signer) => signer.public_key(),
+ Self::Secp384r1(signer) => signer.public_key(),
+ }
+ }
+
+ /// Generate a signature with the private key over the context and message.
+ pub fn sign(&self, context: &[u8], message: &[u8]) -> Result<Signature, Error> {
+ match self {
+ Self::Ed25519(signer) => signer.sign(context, message),
+ Self::Secp256k1(signer) => signer.sign(context, message),
+ Self::Secp256r1(signer) => signer.sign(context, message),
+ Self::Secp384r1(signer) => signer.sign(context, message),
+ }
+ }
+
+ /// Generate a signature with the private key over the message.
+ pub fn sign_raw(&self, message: &[u8]) -> Result<Signature, Error> {
+ match self {
+ Self::Ed25519(signer) => signer.sign_raw(message),
+ Self::Secp256k1(signer) => signer.sign_raw(message),
+ Self::Secp256r1(signer) => signer.sign_raw(message),
+ Self::Secp384r1(signer) => signer.sign_raw(message),
+ }
+ }
+
+ /// Generate a signature for the specified message and optional context.
+ pub fn sign_by_type(
+ &self,
+ signature_type: SignatureType,
+ context_or_hash: &[u8],
+ message: &[u8],
+ ) -> Result<Signature, Error> {
+ match self {
+ Self::Ed25519(signer) => match signature_type {
+ SignatureType::Ed25519_Oasis => signer.sign(context_or_hash, message),
+ SignatureType::Ed25519_Pure => signer.sign_raw(message),
+ SignatureType::Ed25519_PrehashedSha512 => {
+ if context_or_hash.len()
+ != <sha2::Sha512 as sha2::digest::OutputSizeUser>::OutputSize::USIZE
+ {
+ return Err(Error::InvalidArgument);
+ }
+ let digest =
+ digests::DummyDigest::<sha2::Sha512>::new_precomputed(context_or_hash);
+ signer.sign_digest(digest)
+ }
+ _ => Err(Error::InvalidArgument),
+ },
+ Self::Secp256k1(signer) => match signature_type {
+ SignatureType::Secp256k1_Oasis => signer.sign(context_or_hash, message),
+ SignatureType::Secp256k1_PrehashedKeccak256 => {
+ if context_or_hash.len()
+ != <sha3::Keccak256 as sha3::digest::OutputSizeUser>::OutputSize::USIZE
+ {
+ return Err(Error::InvalidArgument);
+ }
+ // Use SHA-256 for RFC6979 even if Keccak256 was used for the message.
+ let digest = digests::DummyDigest::<k256::sha2::Sha256>::new_precomputed(
+ context_or_hash,
+ );
+ signer.sign_digest(digest)
+ }
+ SignatureType::Secp256k1_PrehashedSha256 => {
+ if context_or_hash.len()
+ != <sha2::Sha256 as sha2::digest::OutputSizeUser>::OutputSize::USIZE
+ {
+ return Err(Error::InvalidArgument);
+ }
+ let digest = digests::DummyDigest::<k256::sha2::Sha256>::new_precomputed(
+ context_or_hash,
+ );
+ signer.sign_digest(digest)
+ }
+ _ => Err(Error::InvalidArgument),
+ },
+ Self::Secp256r1(signer) => match signature_type {
+ SignatureType::Secp256r1_PrehashedSha256 => {
+ if context_or_hash.len()
+ != <sha2::Sha256 as sha2::digest::OutputSizeUser>::OutputSize::USIZE
+ {
+ return Err(Error::InvalidArgument);
+ }
+ let digest =
+ digests::DummyDigest::<sha2::Sha256>::new_precomputed(context_or_hash);
+ signer.sign_digest(digest)
+ }
+ _ => Err(Error::InvalidArgument),
+ },
+ Self::Secp384r1(signer) => match signature_type {
+ SignatureType::Secp384r1_PrehashedSha384 => {
+ if context_or_hash.len()
+ != <sha2::Sha384 as sha2::digest::OutputSizeUser>::OutputSize::USIZE
+ {
+ return Err(Error::InvalidArgument);
+ }
+ let digest =
+ digests::DummyDigest::<sha2::Sha384>::new_precomputed(context_or_hash);
+ signer.sign_digest(digest)
+ }
+ _ => Err(Error::InvalidArgument),
+ },
+ }
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ #[test]
+ fn test_signature_conversion() {
+ let raw = vec![0x00, 0x01, 0x02, 0x03];
+ let sig = Signature::from(raw.clone());
+ let v: Vec<u8> = sig.clone().into();
+ assert_eq!(v, raw);
+
+ let vref: &[u8] = v.as_ref();
+ assert_eq!(vref, sig.as_ref());
+ }
+
+ #[test]
+ fn test_memory_signer() {
+ let ctx = b"oasis-core/test: context";
+ let corrupt_ctx = b"oasis-core/test: wrong context";
+ let message = b"this is a message";
+ let corrupt_message = b"this isn't a message";
+
+ for sig_type in [
+ SignatureType::Ed25519_Oasis,
+ SignatureType::Ed25519_Pure,
+ SignatureType::Secp256k1_Oasis,
+ ] {
+ let signer = MemorySigner::new_test(sig_type, "memory signer test");
+ let pk = signer.public_key();
+
+ let signature = signer
+ .sign_by_type(sig_type, ctx, message)
+ .expect("signing should succeed");
+
+ pk.verify_by_type(sig_type, ctx, message, &signature)
+ .expect("signature should verify");
+ pk.verify_by_type(sig_type, ctx, corrupt_message, &signature)
+ .expect_err("signature should fail verification");
+ if matches!(sig_type, SignatureType::Ed25519_Oasis)
+ || matches!(sig_type, SignatureType::Secp256k1_Oasis)
+ {
+ pk.verify_by_type(sig_type, corrupt_ctx, message, &signature)
+ .expect_err("signature should fail verification");
+ pk.verify_by_type(sig_type, corrupt_ctx, corrupt_message, &signature)
+ .expect_err("signature should fail verification");
+ }
+ }
+ }
+
+ #[test]
+ fn test_memory_signer_prehashed() {
+ let message = b"this is a message";
+ let corrupt_message = b"this isn't a message";
+
+ let sig_types: &[(SignatureType, Box<dyn Fn(&[u8]) -> Vec<u8>>)] = &[
+ (
+ SignatureType::Ed25519_PrehashedSha512,
+ Box::new(|message| sha2::Sha512::digest(message).to_vec()),
+ ),
+ (
+ SignatureType::Secp256k1_PrehashedKeccak256,
+ Box::new(|message| sha3::Keccak256::digest(message).to_vec()),
+ ),
+ (
+ SignatureType::Secp256k1_PrehashedSha256,
+ Box::new(|message| sha2::Sha256::digest(message).to_vec()),
+ ),
+ (
+ SignatureType::Secp256r1_PrehashedSha256,
+ Box::new(|message| sha2::Sha256::digest(message).to_vec()),
+ ),
+ (
+ SignatureType::Secp384r1_PrehashedSha384,
+ Box::new(|message| sha2::Sha384::digest(message).to_vec()),
+ ),
+ ];
+
+ for (sig_type, hasher) in sig_types {
+ let hash = hasher(message);
+ let corrupt_hash = hasher(corrupt_message);
+
+ let signer = MemorySigner::new_test(*sig_type, "memory signer test");
+ let pk = signer.public_key();
+
+ let signature = signer
+ .sign_by_type(*sig_type, &hash, b"")
+ .expect("signing should succeed");
+ pk.verify_by_type(*sig_type, &hash, b"", &signature)
+ .expect("signature should verify");
+ pk.verify_by_type(*sig_type, &corrupt_hash, b"", &signature)
+ .expect_err("corrupt hash shouldn't verify");
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +
//! Secp256k1 signatures.
+use base64::prelude::*;
+use digest::{consts::U32, Digest, FixedOutput};
+use k256::{
+ self,
+ ecdsa::{
+ self,
+ signature::{DigestSigner as _, DigestVerifier, Signer as _, Verifier as _},
+ },
+ elliptic_curve::sec1::{FromEncodedPoint, ToEncodedPoint},
+ sha2::Sha512_256,
+};
+use rand_core::RngCore;
+
+use crate::crypto::signature::{Error, Signature};
+
+/// A Secp256k1 public key (in compressed form).
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct PublicKey(k256::EncodedPoint);
+
+impl PublicKey {
+ /// Return a byte representation of this public key.
+ pub fn as_bytes(&self) -> &[u8] {
+ self.0.as_bytes()
+ }
+
+ /// Return an alternative byte representation used in deriving Ethereum-compatible addresses.
+ pub fn to_uncompressed_untagged_bytes(&self) -> Vec<u8> {
+ // Our wrapper type only accepts compressed points, so we shouldn't get None.
+ let pk = k256::PublicKey::from_encoded_point(&self.0).unwrap();
+ pk.to_encoded_point(false).as_bytes()[1..].to_vec()
+ }
+
+ /// Derive an Ethereum-compatible address.
+ pub fn to_eth_address(&self) -> Vec<u8> {
+ sha3::Keccak256::digest(self.to_uncompressed_untagged_bytes())[32 - 20..].to_vec()
+ }
+
+ /// Construct a public key from a slice of bytes.
+ pub fn from_bytes(bytes: &[u8]) -> Result<Self, Error> {
+ k256::EncodedPoint::from_bytes(bytes)
+ .map_err(|_| Error::MalformedPublicKey)
+ .map(PublicKey)
+ }
+
+ /// Verify a signature.
+ pub fn verify(
+ &self,
+ context: &[u8],
+ message: &[u8],
+ signature: &Signature,
+ ) -> Result<(), Error> {
+ let digest = Sha512_256::new()
+ .chain_update(context)
+ .chain_update(message);
+ self.verify_digest(digest, signature)
+ .map_err(|_| Error::VerificationFailed)
+ }
+
+ /// Verify signature without using any domain separation scheme.
+ pub fn verify_raw(&self, message: &[u8], signature: &Signature) -> Result<(), Error> {
+ let sig = ecdsa::Signature::from_der(signature.0.as_ref())
+ .map_err(|_| Error::MalformedSignature)?;
+ let verify_key = ecdsa::VerifyingKey::from_encoded_point(&self.0)
+ .map_err(|_| Error::MalformedPublicKey)?;
+ verify_key
+ .verify(message, &sig)
+ .map_err(|_| Error::VerificationFailed)
+ }
+
+ /// Verify signature of a pre-hashed message.
+ pub fn verify_digest<D>(&self, digest: D, signature: &Signature) -> Result<(), Error>
+ where
+ D: Digest + FixedOutput<OutputSize = U32>,
+ {
+ let sig = ecdsa::Signature::from_der(signature.as_ref())
+ .map_err(|_| Error::MalformedSignature)?;
+ let verify_key = ecdsa::VerifyingKey::from_encoded_point(&self.0)
+ .map_err(|_| Error::MalformedPublicKey)?;
+ verify_key
+ .verify_digest(digest, &sig)
+ .map_err(|_| Error::VerificationFailed)
+ }
+}
+
+impl From<&'static str> for PublicKey {
+ fn from(s: &'static str) -> PublicKey {
+ PublicKey::from_bytes(&BASE64_STANDARD.decode(s).unwrap()).unwrap()
+ }
+}
+
+impl cbor::Encode for PublicKey {
+ fn into_cbor_value(self) -> cbor::Value {
+ cbor::Value::ByteString(self.as_bytes().to_vec())
+ }
+}
+
+impl cbor::Decode for PublicKey {
+ fn try_from_cbor_value(value: cbor::Value) -> Result<Self, cbor::DecodeError> {
+ match value {
+ cbor::Value::ByteString(data) => {
+ Self::from_bytes(&data).map_err(|_| cbor::DecodeError::UnexpectedType)
+ }
+ _ => Err(cbor::DecodeError::UnexpectedType),
+ }
+ }
+}
+
+/// A memory-backed signer for Secp256k1.
+pub struct MemorySigner {
+ sk: ecdsa::SigningKey,
+}
+
+impl MemorySigner {
+ pub fn sign_digest<D>(&self, digest: D) -> Result<Signature, Error>
+ where
+ D: Digest + FixedOutput<OutputSize = U32>,
+ {
+ let signature: ecdsa::Signature = self.sk.sign_digest(digest);
+ Ok(signature.to_der().as_bytes().to_vec().into())
+ }
+}
+
+impl super::Signer for MemorySigner {
+ fn random(rng: &mut impl RngCore) -> Result<Self, Error> {
+ let mut seed = [0u8; 32];
+ rng.fill_bytes(&mut seed);
+ Self::new_from_seed(&seed)
+ }
+
+ fn new_from_seed(seed: &[u8]) -> Result<Self, Error> {
+ let sk = ecdsa::SigningKey::from_slice(seed).map_err(|_| Error::InvalidArgument)?;
+ Ok(Self { sk })
+ }
+
+ fn from_bytes(bytes: &[u8]) -> Result<Self, Error> {
+ Ok(Self {
+ sk: ecdsa::SigningKey::from_slice(bytes).map_err(|_| Error::MalformedPrivateKey)?,
+ })
+ }
+
+ fn to_bytes(&self) -> Vec<u8> {
+ self.sk.to_bytes().to_vec()
+ }
+
+ fn public_key(&self) -> super::PublicKey {
+ super::PublicKey::Secp256k1(PublicKey(self.sk.verifying_key().to_encoded_point(true)))
+ }
+
+ fn sign(&self, context: &[u8], message: &[u8]) -> Result<Signature, Error> {
+ let digest = Sha512_256::new()
+ .chain_update(context)
+ .chain_update(message);
+ let signature: ecdsa::Signature = self.sk.sign_digest(digest);
+ Ok(signature.to_der().as_bytes().to_vec().into())
+ }
+
+ fn sign_raw(&self, message: &[u8]) -> Result<Signature, Error> {
+ let signature: ecdsa::Signature = self.sk.sign(message);
+ Ok(signature.to_der().as_bytes().to_vec().into())
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +
//! Secp256r1 signatures.
+use base64::prelude::*;
+use digest::{consts::U32, core_api::BlockSizeUser, Digest, FixedOutput, FixedOutputReset};
+use k256::sha2::Sha512_256;
+use p256::{
+ self,
+ ecdsa::{
+ self,
+ signature::{DigestSigner as _, DigestVerifier, Signer as _, Verifier as _},
+ },
+};
+use rand_core::RngCore;
+
+use crate::crypto::signature::{Error, Signature};
+
+/// A Secp256r1 public key (in compressed form).
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct PublicKey(p256::EncodedPoint);
+
+impl PublicKey {
+ /// Return a byte representation of this public key.
+ pub fn as_bytes(&self) -> &[u8] {
+ self.0.as_bytes()
+ }
+
+ /// Construct a public key from a slice of bytes.
+ pub fn from_bytes(bytes: &[u8]) -> Result<Self, Error> {
+ p256::EncodedPoint::from_bytes(bytes)
+ .map_err(|_| Error::MalformedPublicKey)
+ .map(PublicKey)
+ }
+
+ /// Verify a signature.
+ pub fn verify(
+ &self,
+ context: &[u8],
+ message: &[u8],
+ signature: &Signature,
+ ) -> Result<(), Error> {
+ let digest = Sha512_256::new()
+ .chain_update(context)
+ .chain_update(message);
+ self.verify_digest(digest, signature)
+ }
+
+ /// Verify signature without using any domain separation scheme.
+ pub fn verify_raw(&self, message: &[u8], signature: &Signature) -> Result<(), Error> {
+ let sig = ecdsa::Signature::from_der(signature.0.as_ref())
+ .map_err(|_| Error::MalformedSignature)?;
+ let verify_key = ecdsa::VerifyingKey::from_encoded_point(&self.0)
+ .map_err(|_| Error::MalformedPublicKey)?;
+ verify_key
+ .verify(message, &sig)
+ .map_err(|_| Error::VerificationFailed)
+ }
+
+ /// Verify signature of a pre-hashed message.
+ pub fn verify_digest<D>(&self, digest: D, signature: &Signature) -> Result<(), Error>
+ where
+ D: Digest + FixedOutput<OutputSize = U32>,
+ {
+ let sig = ecdsa::Signature::from_der(signature.as_ref())
+ .map_err(|_| Error::MalformedSignature)?;
+ let verify_key = ecdsa::VerifyingKey::from_encoded_point(&self.0)
+ .map_err(|_| Error::MalformedPublicKey)?;
+ verify_key
+ .verify_digest(digest, &sig)
+ .map_err(|_| Error::VerificationFailed)
+ }
+}
+
+impl From<&'static str> for PublicKey {
+ fn from(s: &'static str) -> PublicKey {
+ PublicKey::from_bytes(&BASE64_STANDARD.decode(s).unwrap()).unwrap()
+ }
+}
+
+impl cbor::Encode for PublicKey {
+ fn into_cbor_value(self) -> cbor::Value {
+ cbor::Value::ByteString(self.as_bytes().to_vec())
+ }
+}
+
+impl cbor::Decode for PublicKey {
+ fn try_from_cbor_value(value: cbor::Value) -> Result<Self, cbor::DecodeError> {
+ match value {
+ cbor::Value::ByteString(data) => {
+ Self::from_bytes(&data).map_err(|_| cbor::DecodeError::UnexpectedType)
+ }
+ _ => Err(cbor::DecodeError::UnexpectedType),
+ }
+ }
+}
+
+/// A memory-backed signer for Secp256r1.
+pub struct MemorySigner {
+ sk: ecdsa::SigningKey,
+}
+
+impl MemorySigner {
+ pub fn sign_digest<D>(&self, digest: D) -> Result<Signature, Error>
+ where
+ D: Digest + FixedOutput<OutputSize = U32> + BlockSizeUser + FixedOutputReset,
+ {
+ let signature: ecdsa::Signature = self.sk.sign_digest(digest);
+ Ok(signature.to_der().as_bytes().to_vec().into())
+ }
+}
+
+impl super::Signer for MemorySigner {
+ fn random(rng: &mut impl RngCore) -> Result<Self, Error> {
+ let mut seed = [0u8; 32];
+ rng.fill_bytes(&mut seed);
+ Self::new_from_seed(&seed)
+ }
+
+ fn new_from_seed(seed: &[u8]) -> Result<Self, Error> {
+ let sk = ecdsa::SigningKey::from_slice(seed).map_err(|_| Error::InvalidArgument)?;
+ Ok(Self { sk })
+ }
+
+ fn from_bytes(bytes: &[u8]) -> Result<Self, Error> {
+ Ok(Self {
+ sk: ecdsa::SigningKey::from_slice(bytes).map_err(|_| Error::MalformedPrivateKey)?,
+ })
+ }
+
+ fn to_bytes(&self) -> Vec<u8> {
+ self.sk.to_bytes().to_vec()
+ }
+
+ fn public_key(&self) -> super::PublicKey {
+ super::PublicKey::Secp256r1(PublicKey(self.sk.verifying_key().to_encoded_point(true)))
+ }
+
+ fn sign(&self, context: &[u8], message: &[u8]) -> Result<Signature, Error> {
+ let digest = sha2::Sha256::new()
+ .chain_update(context)
+ .chain_update(message);
+ let signature: ecdsa::Signature = self.sk.sign_digest(digest);
+ Ok(signature.to_der().as_bytes().to_vec().into())
+ }
+
+ fn sign_raw(&self, message: &[u8]) -> Result<Signature, Error> {
+ let signature: ecdsa::Signature = self.sk.sign(message);
+ Ok(signature.to_der().as_bytes().to_vec().into())
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +
//! Secp384r1 signatures.
+use base64::prelude::*;
+use digest::{consts::U48, core_api::BlockSizeUser, Digest, FixedOutput, FixedOutputReset};
+use p384::{
+ self,
+ ecdsa::{
+ self,
+ signature::{DigestSigner as _, DigestVerifier, Signer as _, Verifier as _},
+ },
+};
+use rand_core::RngCore;
+
+use crate::crypto::signature::{Error, Signature};
+
+/// A Secp384r1 public key (in compressed form).
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct PublicKey(p384::EncodedPoint);
+
+impl PublicKey {
+ /// Return a byte representation of this public key.
+ pub fn as_bytes(&self) -> &[u8] {
+ self.0.as_bytes()
+ }
+
+ /// Construct a public key from a slice of bytes.
+ pub fn from_bytes(bytes: &[u8]) -> Result<Self, Error> {
+ p384::EncodedPoint::from_bytes(bytes)
+ .map_err(|_| Error::MalformedPublicKey)
+ .map(PublicKey)
+ }
+
+ /// Verify a signature.
+ pub fn verify(
+ &self,
+ context: &[u8],
+ message: &[u8],
+ signature: &Signature,
+ ) -> Result<(), Error> {
+ let digest = sha2::Sha384::new()
+ .chain_update(context)
+ .chain_update(message);
+ self.verify_digest(digest, signature)
+ }
+
+ /// Verify signature without using any domain separation scheme.
+ pub fn verify_raw(&self, message: &[u8], signature: &Signature) -> Result<(), Error> {
+ let sig = ecdsa::Signature::from_der(signature.0.as_ref())
+ .map_err(|_| Error::MalformedSignature)?;
+ let verify_key = ecdsa::VerifyingKey::from_encoded_point(&self.0)
+ .map_err(|_| Error::MalformedPublicKey)?;
+ verify_key
+ .verify(message, &sig)
+ .map_err(|_| Error::VerificationFailed)
+ }
+
+ /// Verify signature of a pre-hashed message.
+ pub fn verify_digest<D>(&self, digest: D, signature: &Signature) -> Result<(), Error>
+ where
+ D: Digest + FixedOutput<OutputSize = U48>,
+ {
+ let sig = ecdsa::Signature::from_der(signature.as_ref())
+ .map_err(|_| Error::MalformedSignature)?;
+ let verify_key = ecdsa::VerifyingKey::from_encoded_point(&self.0)
+ .map_err(|_| Error::MalformedPublicKey)?;
+ verify_key
+ .verify_digest(digest, &sig)
+ .map_err(|_| Error::VerificationFailed)
+ }
+}
+
+impl From<&'static str> for PublicKey {
+ fn from(s: &'static str) -> PublicKey {
+ PublicKey::from_bytes(&BASE64_STANDARD.decode(s).unwrap()).unwrap()
+ }
+}
+
+impl cbor::Encode for PublicKey {
+ fn into_cbor_value(self) -> cbor::Value {
+ cbor::Value::ByteString(self.as_bytes().to_vec())
+ }
+}
+
+impl cbor::Decode for PublicKey {
+ fn try_from_cbor_value(value: cbor::Value) -> Result<Self, cbor::DecodeError> {
+ match value {
+ cbor::Value::ByteString(data) => {
+ Self::from_bytes(&data).map_err(|_| cbor::DecodeError::UnexpectedType)
+ }
+ _ => Err(cbor::DecodeError::UnexpectedType),
+ }
+ }
+}
+
+/// A memory-backed signer for Secp384r1.
+pub struct MemorySigner {
+ sk: ecdsa::SigningKey,
+}
+
+impl MemorySigner {
+ pub fn sign_digest<D>(&self, digest: D) -> Result<Signature, Error>
+ where
+ D: Digest + FixedOutput<OutputSize = U48> + BlockSizeUser + FixedOutputReset,
+ {
+ let signature: ecdsa::Signature = self.sk.sign_digest(digest);
+ Ok(signature.to_der().as_bytes().to_vec().into())
+ }
+}
+
+impl super::Signer for MemorySigner {
+ fn random(rng: &mut impl RngCore) -> Result<Self, Error> {
+ let mut seed = [0u8; 48];
+ rng.fill_bytes(&mut seed);
+ Self::new_from_seed(&seed)
+ }
+
+ fn new_from_seed(seed: &[u8]) -> Result<Self, Error> {
+ let sk = ecdsa::SigningKey::from_slice(seed).map_err(|_| Error::InvalidArgument)?;
+ Ok(Self { sk })
+ }
+
+ fn from_bytes(bytes: &[u8]) -> Result<Self, Error> {
+ Ok(Self {
+ sk: ecdsa::SigningKey::from_slice(bytes).map_err(|_| Error::MalformedPrivateKey)?,
+ })
+ }
+
+ fn to_bytes(&self) -> Vec<u8> {
+ self.sk.to_bytes().to_vec()
+ }
+
+ fn public_key(&self) -> super::PublicKey {
+ super::PublicKey::Secp384r1(PublicKey(self.sk.verifying_key().to_encoded_point(true)))
+ }
+
+ fn sign(&self, context: &[u8], message: &[u8]) -> Result<Signature, Error> {
+ let digest = sha2::Sha384::new()
+ .chain_update(context)
+ .chain_update(message);
+ let signature: ecdsa::Signature = self.sk.sign_digest(digest);
+ Ok(signature.to_der().as_bytes().to_vec().into())
+ }
+
+ fn sign_raw(&self, message: &[u8]) -> Result<Signature, Error> {
+ let signature: ecdsa::Signature = self.sk.sign(message);
+ Ok(signature.to_der().as_bytes().to_vec().into())
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +
//! Sr25519 signatures.
+use base64::prelude::*;
+use schnorrkel;
+use sha2::{Digest, Sha512_256};
+
+use crate::crypto::signature::{Error, Signature};
+
+/// A Sr25519 public key.
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, cbor::Encode, cbor::Decode)]
+#[cbor(transparent, no_default)]
+pub struct PublicKey(Vec<u8>);
+
+impl PublicKey {
+ /// Return a byte representation of this public key.
+ pub fn as_bytes(&self) -> &[u8] {
+ // schnorrkel::keys::PublicKey only has to_bytes, which
+ // returns a new array.
+ //
+ // Since we need to return a reference the easiest way to
+ // placate the borrow-checker involves just keeping the
+ // byte-serialized form of the public key instead of the
+ // decompressed one, and doing point-decompression each
+ // time we want to actually do something useful.
+ &self.0
+ }
+
+ /// Construct a public key from a slice of bytes.
+ pub fn from_bytes(bytes: &[u8]) -> Result<Self, Error> {
+ // Ensure the bytes represents a valid public key.
+ PublicKey::decompress_public_key(bytes)?;
+ Ok(PublicKey(bytes.to_vec()))
+ }
+
+ /// Verify a signature.
+ pub fn verify(
+ &self,
+ context: &[u8],
+ message: &[u8],
+ signature: &Signature,
+ ) -> Result<(), Error> {
+ let public_key = PublicKey::decompress_public_key(&self.0)?;
+
+ let signature = schnorrkel::Signature::from_bytes(signature.as_ref())
+ .map_err(|_| Error::MalformedSignature)?;
+
+ // Convert the context to a Sr25519 SigningContext.
+ let context = schnorrkel::context::SigningContext::new(context);
+
+ // Generate a SigningTranscript from the context, and a pre-hash
+ // of the message.
+ //
+ // Note: This requires using Sha512_256 instead of our hash,
+ // due to the need for FixedOutput.
+ let mut digest = Sha512_256::new();
+ digest.update(message);
+ let transcript = context.hash256(digest);
+
+ public_key
+ .verify(transcript, &signature)
+ .map_err(|_| Error::VerificationFailed)
+ }
+
+ fn decompress_public_key(bytes: &[u8]) -> Result<schnorrkel::PublicKey, Error> {
+ schnorrkel::PublicKey::from_bytes(bytes).map_err(|_| Error::MalformedPublicKey)
+ }
+}
+
+impl From<&'static str> for PublicKey {
+ fn from(s: &'static str) -> PublicKey {
+ PublicKey::from_bytes(&BASE64_STANDARD.decode(s).unwrap()).unwrap()
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +765 +766 +767 +768 +769 +770 +771 +772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805 +806 +807 +808 +809 +810 +811 +812 +813 +814 +815 +816 +817 +818 +819 +820 +821 +822 +823 +824 +825 +826 +827 +828 +829 +830 +831 +832 +833 +834 +835 +836 +837 +838 +839 +840 +841 +842 +843 +844 +845 +846 +847 +848 +849 +850 +851 +852 +853 +854 +855 +856 +857 +858 +859 +860 +861 +862 +863 +864 +865 +866 +867 +868 +869 +870 +871 +872 +873 +874 +875 +876 +877 +878 +879 +880 +881 +882 +883 +884 +885 +886 +887 +888 +889 +890 +891 +892 +893 +894 +895 +896 +897 +898 +899 +900 +901 +902 +903 +904 +905 +906 +907 +908 +909 +910 +911 +912 +913 +914 +915 +916 +917 +918 +919 +920 +921 +922 +923 +924 +925 +926 +927 +928 +929 +930 +931 +932 +933 +934 +935 +936 +937 +938 +939 +940 +941 +942 +943 +944 +945 +946 +947 +948 +949 +950 +951 +952 +953 +954 +955 +956 +957 +958 +959 +960 +961 +962 +963 +964 +965 +966 +967 +968 +969 +970 +971 +972 +973 +974 +975 +976 +977 +978 +979 +980 +981 +982 +983 +984 +985 +986 +987 +988 +989 +990 +991 +992 +993 +994 +995 +996 +997 +998 +999 +1000 +1001 +1002 +1003 +1004 +1005 +1006 +1007 +1008 +1009 +1010 +1011 +1012 +1013 +1014 +1015 +1016 +1017 +1018 +1019 +1020 +1021 +1022 +1023 +1024 +1025 +1026 +1027 +1028 +1029 +1030 +1031 +1032 +1033 +1034 +1035 +1036 +1037 +1038 +1039 +1040 +1041 +1042 +1043 +1044 +1045 +1046 +1047 +1048 +1049 +1050 +1051 +1052 +1053 +1054 +1055 +1056 +1057 +1058 +1059 +1060 +1061 +1062 +1063 +1064 +1065 +1066 +1067 +1068 +1069 +1070 +1071 +1072 +1073 +1074 +1075 +1076 +1077 +1078 +1079 +1080 +1081 +1082 +1083 +1084 +1085 +1086 +1087 +1088 +1089 +1090 +1091 +1092 +1093 +1094 +1095 +1096 +1097 +1098 +1099 +1100 +1101 +1102 +1103 +1104 +1105 +1106 +1107 +1108 +1109 +1110 +1111 +1112 +1113 +1114 +1115 +1116 +1117 +1118 +1119 +1120 +1121 +1122 +1123 +1124 +1125 +1126 +1127 +1128 +1129 +1130 +1131 +1132 +1133 +1134 +1135 +1136 +1137 +1138 +1139 +1140 +1141 +1142 +1143 +1144 +1145 +1146 +1147 +1148 +1149 +1150 +1151 +1152 +1153 +1154 +1155 +1156 +1157 +1158 +1159 +1160 +1161 +1162 +1163 +1164 +1165 +1166 +1167 +1168 +1169 +1170 +1171 +1172 +1173 +1174 +1175 +1176 +1177 +1178 +1179 +1180 +1181 +1182 +1183 +1184 +1185 +1186 +1187 +1188 +1189 +1190 +1191 +1192 +1193 +1194 +1195 +1196 +1197 +1198 +1199 +1200 +
//! Transaction dispatcher.
+use std::{
+ collections::{BTreeMap, BTreeSet},
+ convert::TryInto,
+ marker::PhantomData,
+ sync::{atomic::AtomicBool, Arc},
+};
+
+use anyhow::anyhow;
+use slog::error;
+use thiserror::Error;
+
+use oasis_core_runtime::{
+ self,
+ common::crypto::hash::Hash,
+ consensus::{roothash, verifier::Verifier},
+ enclave_rpc::dispatcher::Dispatcher as RpcDispatcher,
+ future::block_on,
+ protocol::{HostInfo, Protocol},
+ transaction::{
+ self,
+ dispatcher::{ExecuteBatchResult, ExecuteTxResult},
+ tags::Tags,
+ types::TxnBatch,
+ },
+ types::{CheckTxMetadata, CheckTxResult},
+};
+
+use crate::{
+ callformat,
+ context::{Context, RuntimeBatchContext},
+ enclave_rpc,
+ error::{Error as _, RuntimeError},
+ event::IntoTags,
+ keymanager::{KeyManagerClient, KeyManagerError},
+ module::{self, BlockHandler, MethodHandler, TransactionHandler},
+ modules,
+ modules::core::API as _,
+ runtime::Runtime,
+ schedule_control::ScheduleControlHost,
+ sender::SenderMeta,
+ state::{self, CurrentState, Mode, TransactionResult, TransactionWithMeta},
+ storage::{self, Prefix},
+ types,
+ types::transaction::{AuthProof, Transaction},
+};
+
+/// Unique module name.
+const MODULE_NAME: &str = "dispatcher";
+
+/// Error emitted by the dispatch process. Note that this indicates an error in the dispatch
+/// process itself and should not be used for any transaction-related errors.
+#[derive(Error, Debug, oasis_runtime_sdk_macros::Error)]
+#[sdk_error(abort_self)]
+pub enum Error {
+ #[error("dispatch aborted")]
+ #[sdk_error(code = 1)]
+ Aborted,
+
+ #[error("malformed transaction in batch: {0}")]
+ #[sdk_error(code = 2)]
+ MalformedTransactionInBatch(#[source] anyhow::Error),
+
+ #[error("query aborted: {0}")]
+ #[sdk_error(code = 3)]
+ QueryAborted(String),
+
+ #[error("key manager failure: {0}")]
+ #[sdk_error(code = 4)]
+ KeyManagerFailure(#[from] KeyManagerError),
+
+ #[error("batch out of gas")]
+ #[sdk_error(code = 5)]
+ BatchOutOfGas,
+}
+
+/// Result of dispatching a transaction.
+#[derive(Debug)]
+pub struct DispatchResult {
+ /// Transaction call result.
+ pub result: module::CallResult,
+ /// Transaction tags.
+ pub tags: Tags,
+ /// Transaction priority.
+ pub priority: u64,
+ /// Transaction sender metadata.
+ pub sender_metadata: SenderMeta,
+ /// Call format metadata.
+ pub call_format_metadata: callformat::Metadata,
+}
+
+impl DispatchResult {
+ fn new(
+ result: module::CallResult,
+ tags: Tags,
+ call_format_metadata: callformat::Metadata,
+ ) -> Self {
+ Self {
+ result,
+ tags,
+ priority: 0,
+ sender_metadata: Default::default(),
+ call_format_metadata,
+ }
+ }
+}
+
+impl From<module::CallResult> for DispatchResult {
+ fn from(result: module::CallResult) -> Self {
+ Self::new(result, vec![], callformat::Metadata::Empty)
+ }
+}
+
+/// Additional options for dispatch operations.
+#[derive(Default)]
+pub struct DispatchOptions<'a> {
+ /// Transaction size.
+ pub tx_size: u32,
+ /// Transaction index within the batch.
+ pub tx_index: usize,
+ /// Transaction hash.
+ pub tx_hash: Hash,
+ /// Optionally only allow methods for which the provided authorizer closure returns true.
+ pub method_authorizer: Option<&'a dyn Fn(&str) -> bool>,
+ /// Optionally skip authentication.
+ pub skip_authentication: bool,
+}
+
+/// The runtime dispatcher.
+pub struct Dispatcher<R: Runtime> {
+ host_info: HostInfo,
+ host: Arc<Protocol>,
+ key_manager: Option<Arc<KeyManagerClient>>,
+ consensus_verifier: Arc<dyn Verifier>,
+ schedule_control_host: Arc<dyn ScheduleControlHost>,
+ _runtime: PhantomData<R>,
+}
+
+impl<R: Runtime> Dispatcher<R> {
+ /// Create a new instance of the dispatcher for the given runtime.
+ ///
+ /// Note that the dispatcher is fully static and the constructor is only needed so that the
+ /// instance can be used directly with the dispatcher system provided by Oasis Core.
+ pub(super) fn new(
+ host: Arc<Protocol>,
+ key_manager: Option<Arc<KeyManagerClient>>,
+ consensus_verifier: Arc<dyn Verifier>,
+ ) -> Self {
+ Self {
+ host_info: host.get_host_info(),
+ key_manager,
+ consensus_verifier,
+ schedule_control_host: host.clone(),
+ host,
+ _runtime: PhantomData,
+ }
+ }
+
+ /// Decode a runtime transaction.
+ pub fn decode_tx<C: Context>(
+ ctx: &C,
+ tx: &[u8],
+ ) -> Result<types::transaction::Transaction, modules::core::Error> {
+ // Perform any checks before decoding.
+ R::Modules::approve_raw_tx(ctx, tx)?;
+
+ // Deserialize transaction.
+ let utx: types::transaction::UnverifiedTransaction = cbor::from_slice(tx)
+ .map_err(|e| modules::core::Error::MalformedTransaction(e.into()))?;
+
+ // Perform any checks before signature verification.
+ R::Modules::approve_unverified_tx(ctx, &utx)?;
+
+ match utx.1.as_slice() {
+ [AuthProof::Module(scheme)] => {
+ R::Modules::decode_tx(ctx, scheme, &utx.0)?.ok_or_else(|| {
+ modules::core::Error::MalformedTransaction(anyhow!(
+ "module-controlled transaction decoding scheme {} not supported",
+ scheme
+ ))
+ })
+ }
+ _ => utx
+ .verify()
+ .map_err(|e| modules::core::Error::MalformedTransaction(e.into())),
+ }
+ }
+
+ /// Run the dispatch steps inside a transaction context. This includes the before call hooks,
+ /// the call itself and after call hooks. The after call hooks are called regardless if the call
+ /// succeeds or not.
+ pub fn dispatch_tx_call<C: Context>(
+ ctx: &C,
+ call: types::transaction::Call,
+ opts: &DispatchOptions<'_>,
+ ) -> (module::CallResult, callformat::Metadata) {
+ let read_only = call.read_only;
+
+ // Dispatch the call.
+ let (result, metadata) = Self::_dispatch_tx_call(ctx, call, opts);
+
+ // Unconditionally call after handle call hook.
+ let result = match R::Modules::after_handle_call(ctx, result) {
+ Ok(result) => result,
+ Err(e) => {
+ // If the call failed, return the error.
+ return (e.into_call_result(), metadata);
+ }
+ };
+
+ // Make sure that a read-only call did not result in any modifications.
+ if read_only && CurrentState::with(|state| state.has_pending_store_updates()) {
+ return (
+ modules::core::Error::ReadOnlyTransaction.into_call_result(),
+ metadata,
+ );
+ }
+
+ (result, metadata)
+ }
+
+ fn _dispatch_tx_call<C: Context>(
+ ctx: &C,
+ call: types::transaction::Call,
+ opts: &DispatchOptions<'_>,
+ ) -> (module::CallResult, callformat::Metadata) {
+ if let Err(e) = R::Modules::before_handle_call(ctx, &call) {
+ return (e.into_call_result(), callformat::Metadata::Empty);
+ }
+
+ // Decode call based on specified call format.
+ let (call, call_format_metadata) = match callformat::decode_call(ctx, call, opts.tx_index) {
+ Ok(Some(result)) => result,
+ Ok(None) => {
+ return (
+ module::CallResult::Ok(cbor::Value::Simple(cbor::SimpleValue::NullValue)),
+ callformat::Metadata::Empty,
+ )
+ }
+ Err(err) => return (err.into_call_result(), callformat::Metadata::Empty),
+ };
+
+ // Apply optional method authorization.
+ if let Some(method_authorizer) = opts.method_authorizer {
+ if !method_authorizer(&call.method) {
+ return (
+ modules::core::Error::Forbidden.into_call_result(),
+ call_format_metadata,
+ );
+ }
+ }
+
+ if let Err(e) = R::Modules::before_authorized_call_dispatch(ctx, &call) {
+ return (e.into_call_result(), call_format_metadata);
+ }
+
+ let result = match R::Modules::dispatch_call(ctx, &call.method, call.body) {
+ module::DispatchResult::Handled(result) => result,
+ module::DispatchResult::Unhandled(_) => {
+ modules::core::Error::InvalidMethod(call.method).into_call_result()
+ }
+ };
+
+ (result, call_format_metadata)
+ }
+
+ /// Dispatch a runtime transaction in the given context with the provided options.
+ pub fn dispatch_tx_opts<C: Context>(
+ ctx: &C,
+ tx: types::transaction::Transaction,
+ opts: &DispatchOptions<'_>,
+ ) -> Result<DispatchResult, Error> {
+ // Run pre-processing hooks.
+ if !opts.skip_authentication {
+ if let Err(err) = R::Modules::authenticate_tx(ctx, &tx) {
+ return Ok(err.into_call_result().into());
+ }
+ }
+ let tx_auth_info = tx.auth_info.clone();
+ let is_read_only = tx.call.read_only;
+ let call = tx.call.clone(); // TODO: Avoid clone.
+
+ let result = CurrentState::with_transaction_opts(
+ state::Options::new().with_tx(TransactionWithMeta {
+ data: tx,
+ size: opts.tx_size,
+ index: opts.tx_index,
+ hash: opts.tx_hash,
+ }),
+ || {
+ let (result, call_format_metadata) = Self::dispatch_tx_call(ctx, call, opts);
+ if !result.is_success() || is_read_only {
+ // Retrieve unconditional events.
+ let events = CurrentState::with(|state| state.take_unconditional_events());
+
+ return TransactionResult::Rollback(DispatchResult::new(
+ result,
+ events.into_tags(),
+ call_format_metadata,
+ ));
+ }
+
+ // Load priority.
+ let priority = R::Core::take_priority();
+ // Load sender metadata.
+ let sender_metadata = R::Core::take_sender_meta();
+
+ if CurrentState::with_env(|env| env.is_check_only()) {
+ TransactionResult::Rollback(DispatchResult {
+ result,
+ tags: Vec::new(),
+ priority,
+ sender_metadata,
+ call_format_metadata,
+ })
+ } else {
+ // Merge normal and unconditional events.
+ let tags = CurrentState::with(|state| state.take_all_events().into_tags());
+
+ TransactionResult::Commit(DispatchResult {
+ result,
+ tags,
+ priority,
+ sender_metadata,
+ call_format_metadata,
+ })
+ }
+ },
+ );
+
+ // Run after dispatch hooks.
+ R::Modules::after_dispatch_tx(ctx, &tx_auth_info, &result.result);
+
+ // Propagate batch aborts.
+ if let module::CallResult::Aborted(err) = result.result {
+ return Err(err);
+ }
+
+ Ok(result)
+ }
+
+ /// Dispatch a runtime transaction in the given context.
+ pub fn dispatch_tx<C: Context>(
+ ctx: &C,
+ tx_size: u32,
+ tx: types::transaction::Transaction,
+ tx_index: usize,
+ ) -> Result<DispatchResult, Error> {
+ Self::dispatch_tx_opts(
+ ctx,
+ tx,
+ &DispatchOptions {
+ tx_size,
+ tx_index,
+ ..Default::default()
+ },
+ )
+ }
+
+ /// Check whether the given transaction is valid.
+ pub fn check_tx<C: Context>(
+ ctx: &C,
+ tx_size: u32,
+ tx: Transaction,
+ ) -> Result<CheckTxResult, Error> {
+ // In case of any panics, treat it as a failed check instead of crashing the runtime.
+ let catch_result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+ Self::dispatch_tx(ctx, tx_size, tx, usize::MAX)
+ }));
+ let dispatch = match catch_result {
+ Ok(dispatch) => dispatch?,
+ Err(panic_err) => {
+ // Convert panics into transaction check failures as it is clearly the fault of a
+ // specific transaction.
+ return Ok(CheckTxResult {
+ error: RuntimeError {
+ module: MODULE_NAME.to_string(),
+ code: 1,
+ message: format!("transaction check aborted: {panic_err:?}"),
+ },
+ meta: None,
+ });
+ }
+ };
+
+ match dispatch.result {
+ module::CallResult::Ok(_) => Ok(CheckTxResult {
+ error: Default::default(),
+ meta: Some(CheckTxMetadata {
+ priority: dispatch.priority,
+ sender: dispatch.sender_metadata.id(),
+ sender_seq: dispatch.sender_metadata.tx_nonce,
+ sender_state_seq: dispatch.sender_metadata.state_nonce,
+ }),
+ }),
+
+ module::CallResult::Failed {
+ module,
+ code,
+ message,
+ } => Ok(CheckTxResult {
+ error: RuntimeError {
+ module,
+ code,
+ message,
+ },
+ meta: None,
+ }),
+
+ module::CallResult::Aborted(err) => Err(err),
+ }
+ }
+
+ /// Execute the given transaction, returning unserialized results.
+ pub fn execute_tx_opts<C: Context>(
+ ctx: &C,
+ tx: Transaction,
+ opts: &DispatchOptions<'_>,
+ ) -> Result<(types::transaction::CallResult, Tags), Error> {
+ let dispatch_result = Self::dispatch_tx_opts(ctx, tx, opts)?;
+ let output: types::transaction::CallResult = callformat::encode_result(
+ ctx,
+ dispatch_result.result,
+ dispatch_result.call_format_metadata,
+ );
+
+ Ok((output, dispatch_result.tags))
+ }
+
+ /// Execute the given transaction.
+ pub fn execute_tx<C: Context>(
+ ctx: &C,
+ tx_size: u32,
+ tx_hash: Hash,
+ tx: Transaction,
+ tx_index: usize,
+ ) -> Result<ExecuteTxResult, Error> {
+ let (output, tags) = Self::execute_tx_opts(
+ ctx,
+ tx,
+ &DispatchOptions {
+ tx_size,
+ tx_index,
+ tx_hash,
+ ..Default::default()
+ },
+ )?;
+
+ Ok(ExecuteTxResult {
+ output: cbor::to_vec(output),
+ tags,
+ })
+ }
+
+ /// Prefetch prefixes for the given transaction.
+ pub fn prefetch_tx(
+ prefixes: &mut BTreeSet<Prefix>,
+ tx: types::transaction::Transaction,
+ ) -> Result<(), RuntimeError> {
+ match R::Modules::prefetch(prefixes, &tx.call.method, tx.call.body, &tx.auth_info) {
+ module::DispatchResult::Handled(r) => r,
+ module::DispatchResult::Unhandled(_) => Ok(()), // Unimplemented prefetch is allowed.
+ }
+ }
+
+ fn handle_last_round_messages<C: Context>(ctx: &C) -> Result<(), modules::core::Error> {
+ let message_events = ctx.runtime_round_results().messages.clone();
+
+ let mut handlers = CurrentState::with_store(|store| {
+ let store = storage::TypedStore::new(storage::PrefixStore::new(
+ store,
+ &modules::core::MODULE_NAME,
+ ));
+ let handlers: BTreeMap<u32, types::message::MessageEventHookInvocation> = store
+ .get(modules::core::state::MESSAGE_HANDLERS)
+ .unwrap_or_default();
+
+ handlers
+ });
+
+ for event in message_events {
+ let handler = handlers
+ .remove(&event.index)
+ .ok_or(modules::core::Error::MessageHandlerMissing(event.index))?;
+ let hook_name = handler.hook_name.clone();
+
+ R::Modules::dispatch_message_result(
+ ctx,
+ &hook_name,
+ types::message::MessageResult {
+ event,
+ context: handler.payload,
+ },
+ )
+ .ok_or(modules::core::Error::InvalidMethod(hook_name))?;
+ }
+
+ if !handlers.is_empty() {
+ error!(ctx.get_logger("dispatcher"), "message handler not invoked"; "unhandled" => ?handlers);
+ return Err(modules::core::Error::MessageHandlerNotInvoked);
+ }
+
+ Ok(())
+ }
+
+ fn save_emitted_message_handlers(handlers: Vec<types::message::MessageEventHookInvocation>) {
+ let message_handlers: BTreeMap<u32, types::message::MessageEventHookInvocation> = handlers
+ .into_iter()
+ .enumerate()
+ .map(|(idx, h)| (idx as u32, h))
+ .collect();
+
+ CurrentState::with_store(|store| {
+ let mut store = storage::TypedStore::new(storage::PrefixStore::new(
+ store,
+ &modules::core::MODULE_NAME,
+ ));
+ store.insert(modules::core::state::MESSAGE_HANDLERS, message_handlers);
+ });
+ }
+
+ /// Process the given runtime query.
+ pub fn dispatch_query<C: Context>(
+ ctx: &C,
+ method: &str,
+ args: Vec<u8>,
+ ) -> Result<Vec<u8>, RuntimeError> {
+ let args = cbor::from_slice(&args)
+ .map_err(|err| modules::core::Error::InvalidArgument(err.into()))?;
+
+ CurrentState::with_transaction(|| {
+ // Catch any panics that occur during query dispatch.
+ let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+ // Perform state migrations if required.
+ R::migrate(ctx);
+
+ if !R::is_allowed_query(method) || !ctx.is_allowed_query::<R>(method) {
+ return Err(modules::core::Error::Forbidden.into());
+ }
+
+ R::Modules::dispatch_query(ctx, method, args)
+ .ok_or_else(|| modules::core::Error::InvalidMethod(method.into()))?
+ }));
+
+ // Always rollback any changes to storage. Note that this is usually a no-op because
+ // Oasis Core would rollback any storage changes related to queries, but this makes it
+ // explicit to ensure this remains the case regardless of upstream changes.
+ TransactionResult::Rollback(result)
+ })
+ .map_err(|err| -> RuntimeError { Error::QueryAborted(format!("{err:?}")).into() })?
+ .map(cbor::to_vec)
+ }
+
+ fn execute_batch_common<F>(
+ &self,
+ mut rt_ctx: transaction::Context<'_>,
+ f: F,
+ ) -> Result<ExecuteBatchResult, RuntimeError>
+ where
+ F: FnOnce(&RuntimeBatchContext<'_, R>) -> Result<Vec<ExecuteTxResult>, RuntimeError>,
+ {
+ // Prepare dispatch context.
+ let key_manager = self
+ .key_manager
+ .as_ref()
+ // NOTE: We are explicitly allowing private key operations during execution.
+ .map(|mgr| mgr.with_private_context());
+ let history = self.consensus_verifier.clone();
+
+ let root = storage::MKVSStore::new(&mut rt_ctx.runtime_state);
+ let ctx = RuntimeBatchContext::<'_, R>::new(
+ &self.host_info,
+ key_manager,
+ rt_ctx.header,
+ rt_ctx.round_results,
+ &rt_ctx.consensus_state,
+ &history,
+ rt_ctx.epoch,
+ rt_ctx.max_messages,
+ );
+
+ CurrentState::enter_opts(state::Options::new().with_mode(Mode::Execute), root, || {
+ // Perform state migrations if required.
+ R::migrate(&ctx);
+
+ // Handle last round message results.
+ Self::handle_last_round_messages(&ctx)?;
+
+ // Run begin block hooks.
+ R::Modules::begin_block(&ctx);
+
+ let results = f(&ctx)?;
+
+ // Run end block hooks.
+ R::Modules::end_block(&ctx);
+
+ // Process any emitted messages and block-level events.
+ let (messages, handlers, block_tags) = CurrentState::with(|state| {
+ let (messages, handlers) = state.take_messages().into_iter().unzip();
+ let block_tags = state.take_all_events().into_tags();
+
+ (messages, handlers, block_tags)
+ });
+ Self::save_emitted_message_handlers(handlers);
+
+ Ok(ExecuteBatchResult {
+ results,
+ messages,
+ block_tags,
+ tx_reject_hashes: vec![],
+ in_msgs_count: 0, // TODO: Support processing incoming messages.
+ })
+ })
+ }
+
+ /// Register EnclaveRPC methods.
+ pub fn register_enclaverpc(&self, rpc: &mut RpcDispatcher)
+ where
+ R: Runtime + Send + Sync + 'static,
+ {
+ enclave_rpc::Wrapper::<R>::wrap(
+ rpc,
+ self.host.clone(),
+ self.host_info.clone(),
+ self.key_manager.clone(),
+ self.consensus_verifier.clone(),
+ );
+ }
+}
+
+impl<R: Runtime + Send + Sync> transaction::dispatcher::Dispatcher for Dispatcher<R> {
+ fn execute_batch(
+ &self,
+ rt_ctx: transaction::Context<'_>,
+ batch: &TxnBatch,
+ _in_msgs: &[roothash::IncomingMessage],
+ ) -> Result<ExecuteBatchResult, RuntimeError> {
+ self.execute_batch_common(
+ rt_ctx,
+ |ctx| -> Result<Vec<ExecuteTxResult>, RuntimeError> {
+ // If prefetch limit is set enable prefetch.
+ let prefetch_enabled = R::PREFETCH_LIMIT > 0;
+
+ let mut txs = Vec::with_capacity(batch.len());
+ let mut prefixes: BTreeSet<Prefix> = BTreeSet::new();
+ for tx in batch.iter() {
+ let tx_size = tx.len().try_into().map_err(|_| {
+ Error::MalformedTransactionInBatch(anyhow!("transaction too large"))
+ })?;
+ let tx_hash = Hash::digest_bytes(tx);
+ // It is an error to include a malformed transaction in a batch. So instead of only
+ // reporting a failed execution result, we fail the whole batch. This will make the compute
+ // node vote for failure and the round will fail.
+ //
+ // Correct proposers should only include transactions which have passed check_tx.
+ let tx = Self::decode_tx(ctx, tx)
+ .map_err(|err| Error::MalformedTransactionInBatch(err.into()))?;
+ txs.push((tx_size, tx_hash, tx.clone()));
+
+ if prefetch_enabled {
+ Self::prefetch_tx(&mut prefixes, tx)?;
+ }
+ }
+ if prefetch_enabled {
+ CurrentState::with_store(|store| {
+ store.prefetch_prefixes(prefixes.into_iter().collect(), R::PREFETCH_LIMIT);
+ })
+ }
+
+ // Execute the batch.
+ let mut results = Vec::with_capacity(batch.len());
+ for (index, (tx_size, tx_hash, tx)) in txs.into_iter().enumerate() {
+ results.push(Self::execute_tx(ctx, tx_size, tx_hash, tx, index)?);
+ }
+
+ Ok(results)
+ },
+ )
+ }
+
+ fn schedule_and_execute_batch(
+ &self,
+ rt_ctx: transaction::Context<'_>,
+ batch: &mut TxnBatch,
+ _in_msgs: &[roothash::IncomingMessage],
+ ) -> Result<ExecuteBatchResult, RuntimeError> {
+ let cfg = R::SCHEDULE_CONTROL;
+ let mut tx_reject_hashes = Vec::new();
+
+ let mut result = self.execute_batch_common(
+ rt_ctx,
+ |ctx| -> Result<Vec<ExecuteTxResult>, RuntimeError> {
+ // Schedule and execute the batch.
+ //
+ // The idea is to keep scheduling transactions as long as we have some space
+ // available in the block as determined by gas use.
+ let mut new_batch = Vec::new();
+ let mut results = Vec::with_capacity(batch.len());
+ let mut requested_batch_len = cfg.initial_batch_size;
+ 'batch: loop {
+ // Remember length of last batch.
+ let last_batch_len = batch.len();
+ let last_batch_tx_hash = batch.last().map(|raw_tx| Hash::digest_bytes(raw_tx));
+
+ for raw_tx in batch.drain(..) {
+ // If we don't have enough gas for processing even the cheapest transaction
+ // we are done. Same if we reached the runtime-imposed maximum tx count.
+ let remaining_gas = R::Core::remaining_batch_gas();
+ if remaining_gas < cfg.min_remaining_gas
+ || new_batch.len() >= cfg.max_tx_count
+ {
+ break 'batch;
+ }
+
+ // Decode transaction.
+ let tx_hash = Hash::digest_bytes(&raw_tx);
+ let tx = match Self::decode_tx(ctx, &raw_tx) {
+ Ok(tx) => tx,
+ Err(_) => {
+ // Transaction is malformed, make sure it gets removed from the
+ // queue and don't include it in a block.
+ tx_reject_hashes.push(tx_hash);
+ continue;
+ }
+ };
+ let tx_size = raw_tx.len().try_into().unwrap();
+
+ // If we don't have enough gas remaining to process this transaction, just
+ // skip it.
+ if tx.auth_info.fee.gas > remaining_gas {
+ continue;
+ }
+ // Same if we don't have enough consensus message slots.
+ let remaining_messages = CurrentState::with(|state| {
+ ctx.max_messages()
+ .saturating_sub(state.emitted_messages_count() as u32)
+ });
+ if tx.auth_info.fee.consensus_messages > remaining_messages {
+ continue;
+ }
+
+ // Determine the current transaction index.
+ let tx_index = new_batch.len();
+
+ // First run the transaction in check tx mode in a separate subcontext. If
+ // that fails, skip and (sometimes) reject transaction.
+ let skip = CurrentState::with_transaction_opts(
+ state::Options::new().with_mode(Mode::PreSchedule),
+ || -> Result<_, Error> {
+ // First authenticate the transaction to get any nonce related errors.
+ match R::Modules::authenticate_tx(ctx, &tx) {
+ Err(modules::core::Error::FutureNonce) => {
+ // Only skip transaction as it may become valid in the future.
+ return Ok(true);
+ }
+ Err(_) => {
+ // Skip and reject the transaction.
+ }
+ Ok(_) => {
+ // Run additional checks on the transaction.
+ let check_result = Self::dispatch_tx_opts(
+ ctx,
+ tx.clone(),
+ &DispatchOptions {
+ tx_size,
+ tx_index,
+ tx_hash,
+ skip_authentication: true, // Already done.
+ ..Default::default()
+ },
+ )?;
+ if check_result.result.is_success() {
+ // Checks successful, execute transaction as usual.
+ return Ok(false);
+ }
+ }
+ }
+
+ // Skip and reject the transaction.
+ tx_reject_hashes.push(tx_hash);
+ Ok(true)
+ },
+ )?;
+ if skip {
+ continue;
+ }
+
+ new_batch.push(raw_tx);
+ results.push(Self::execute_tx(ctx, tx_size, tx_hash, tx, tx_index)?);
+ }
+
+ // If there's more room in the block and we got the maximum number of
+ // transactions, request more transactions.
+ if last_batch_tx_hash.is_some()
+ && last_batch_len >= requested_batch_len as usize
+ {
+ if let Some(fetched_batch) = self
+ .schedule_control_host
+ .fetch_tx_batch(last_batch_tx_hash, cfg.batch_size)?
+ {
+ *batch = fetched_batch;
+ requested_batch_len = cfg.batch_size;
+ continue;
+ }
+ // No more transactions, let's just finish.
+ }
+ break;
+ }
+
+ // Replace input batch with newly generated batch.
+ *batch = new_batch.into();
+
+ Ok(results)
+ },
+ )?;
+
+ // Include rejected transaction hashes in the final result.
+ result.tx_reject_hashes = tx_reject_hashes;
+
+ Ok(result)
+ }
+
+ fn check_batch(
+ &self,
+ mut rt_ctx: transaction::Context<'_>,
+ batch: &TxnBatch,
+ ) -> Result<Vec<CheckTxResult>, RuntimeError> {
+ // If prefetch limit is set enable prefetch.
+ let prefetch_enabled = R::PREFETCH_LIMIT > 0;
+
+ // Prepare dispatch context.
+ let key_manager = self.key_manager.as_ref().map(|mgr| mgr.with_context());
+ let history = self.consensus_verifier.clone();
+
+ let root = storage::MKVSStore::new(&mut rt_ctx.runtime_state);
+ let ctx = RuntimeBatchContext::<'_, R>::new(
+ &self.host_info,
+ key_manager,
+ rt_ctx.header,
+ rt_ctx.round_results,
+ &rt_ctx.consensus_state,
+ &history,
+ rt_ctx.epoch,
+ rt_ctx.max_messages,
+ );
+
+ CurrentState::enter_opts(
+ state::Options::new().with_mode(state::Mode::Check),
+ root,
+ || {
+ // Perform state migrations if required.
+ R::migrate(&ctx);
+
+ // Prefetch.
+ let mut txs: Vec<Result<_, RuntimeError>> = Vec::with_capacity(batch.len());
+ let mut prefixes: BTreeSet<Prefix> = BTreeSet::new();
+ for tx in batch.iter() {
+ let tx_size = tx.len().try_into().map_err(|_| {
+ Error::MalformedTransactionInBatch(anyhow!("transaction too large"))
+ })?;
+ let res = match Self::decode_tx(&ctx, tx) {
+ Ok(tx) => {
+ if prefetch_enabled {
+ Self::prefetch_tx(&mut prefixes, tx.clone()).map(|_| (tx_size, tx))
+ } else {
+ Ok((tx_size, tx))
+ }
+ }
+ Err(err) => Err(err.into()),
+ };
+ txs.push(res);
+ }
+ if prefetch_enabled {
+ CurrentState::with_store(|store| {
+ store.prefetch_prefixes(prefixes.into_iter().collect(), R::PREFETCH_LIMIT);
+ });
+ }
+
+ // Check the batch.
+ let mut results = Vec::with_capacity(batch.len());
+ for tx in txs.into_iter() {
+ match tx {
+ Ok((tx_size, tx)) => results.push(Self::check_tx(&ctx, tx_size, tx)?),
+ Err(err) => results.push(CheckTxResult {
+ error: err,
+ meta: None,
+ }),
+ }
+ }
+
+ Ok(results)
+ },
+ )
+ }
+
+ fn set_abort_batch_flag(&mut self, _abort_batch: Arc<AtomicBool>) {
+ // TODO: Implement support for graceful batch aborts (oasis-sdk#129).
+ }
+
+ fn query(
+ &self,
+ mut rt_ctx: transaction::Context<'_>,
+ method: &str,
+ args: Vec<u8>,
+ ) -> Result<Vec<u8>, RuntimeError> {
+ // Determine whether the method is allowed to access confidential state and provide an
+ // appropriately scoped instance of the key manager client.
+ let is_confidential_allowed = R::Modules::is_allowed_private_km_query(method)
+ && R::is_allowed_private_km_query(method);
+ if is_confidential_allowed {
+ // Perform consensus layer state integrity verification for any queries that allow
+ // access to confidential state.
+ block_on(self.consensus_verifier.verify_for_query(
+ rt_ctx.consensus_block.clone(),
+ rt_ctx.header.clone(),
+ rt_ctx.epoch,
+ ))?;
+ // Ensure the runtime is still ready to process requests.
+ rt_ctx.protocol.ensure_initialized()?;
+ }
+ let key_manager = self.key_manager.as_ref().map(|mgr| {
+ if is_confidential_allowed {
+ mgr.with_private_context()
+ } else {
+ mgr.with_context()
+ }
+ });
+
+ // Prepare dispatch context.
+ let history = self.consensus_verifier.clone();
+
+ let root = storage::MKVSStore::new(&mut rt_ctx.runtime_state);
+ let ctx = RuntimeBatchContext::<'_, R>::new(
+ &self.host_info,
+ key_manager,
+ rt_ctx.header,
+ rt_ctx.round_results,
+ &rt_ctx.consensus_state,
+ &history,
+ rt_ctx.epoch,
+ rt_ctx.max_messages,
+ );
+
+ CurrentState::enter_opts(
+ state::Options::new()
+ .with_mode(state::Mode::Check)
+ .with_rng_local_entropy(), // Mix in local (private) entropy for queries.
+ root,
+ || Self::dispatch_query(&ctx, method, args),
+ )
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+ use crate::{
+ handler,
+ module::Module,
+ modules::{accounts, core},
+ sdk_derive,
+ state::{CurrentState, Options},
+ storage::Store,
+ testing::{configmap, keys, mock::Mock},
+ types::{token, transaction},
+ Version,
+ };
+ use cbor::Encode as _;
+
+ struct CoreConfig;
+ impl core::Config for CoreConfig {}
+ type Core = core::Module<CoreConfig>;
+ type Accounts = accounts::Module;
+
+ #[derive(Error, Debug, oasis_runtime_sdk_macros::Error)]
+ enum AlphabetError {
+ #[error("{0}")]
+ #[sdk_error(transparent, abort)]
+ Core(#[source] core::Error),
+ }
+
+ /// A module with multiple no-op methods; intended for testing routing.
+ struct AlphabetModule;
+
+ #[sdk_derive(Module)]
+ impl AlphabetModule {
+ const NAME: &'static str = "alphabet";
+ const VERSION: u32 = 42;
+ type Error = AlphabetError;
+ type Event = ();
+ type Parameters = ();
+ type Genesis = ();
+
+ #[handler(call = "alphabet.ReadOnly")]
+ fn read_only<C: Context>(_ctx: &C, _args: ()) -> Result<u64, AlphabetError> {
+ CurrentState::with_store(|store| {
+ let _ = store.get(b"key"); // Read something and ignore result.
+ });
+ Ok(42)
+ }
+
+ #[handler(call = "alphabet.NotReadOnly")]
+ fn not_read_only<C: Context>(_ctx: &C, _args: ()) -> Result<u64, AlphabetError> {
+ CurrentState::with_store(|store| {
+ store.insert(b"key", b"value");
+ });
+ Ok(10)
+ }
+
+ #[handler(call = "alphabet.Aborting")]
+ fn aborting<C: Context>(_ctx: &C, _args: ()) -> Result<(), AlphabetError> {
+ // Use a deeply nested abort to make sure this is handled correctly.
+ Err(AlphabetError::Core(core::Error::Abort(Error::Aborted)))
+ }
+
+ #[handler(query = "alphabet.Alpha")]
+ fn alpha<C: Context>(_ctx: &C, _args: ()) -> Result<(), AlphabetError> {
+ Ok(())
+ }
+
+ #[handler(query = "alphabet.Omega", expensive)]
+ fn expensive<C: Context>(_ctx: &C, _args: ()) -> Result<(), AlphabetError> {
+ // Nothing actually expensive here. We're just pretending for testing purposes.
+ Ok(())
+ }
+ }
+
+ impl module::BlockHandler for AlphabetModule {}
+ impl module::TransactionHandler for AlphabetModule {}
+ impl module::InvariantHandler for AlphabetModule {}
+
+ struct AlphabetRuntime;
+
+ impl Runtime for AlphabetRuntime {
+ const VERSION: Version = Version::new(0, 0, 0);
+ type Core = Core;
+ type Accounts = Accounts;
+ type Modules = (Core, AlphabetModule);
+
+ fn genesis_state() -> <Self::Modules as module::MigrationHandler>::Genesis {
+ (
+ core::Genesis {
+ parameters: core::Parameters {
+ max_batch_gas: u64::MAX,
+ max_tx_size: 32 * 1024,
+ max_tx_signers: 1,
+ max_multisig_signers: 8,
+ gas_costs: Default::default(),
+ min_gas_price: BTreeMap::from([(token::Denomination::NATIVE, 0)]),
+ dynamic_min_gas_price: Default::default(),
+ },
+ },
+ (),
+ )
+ }
+ }
+
+ #[test]
+ fn test_allowed_queries_defaults() {
+ let mut mock = Mock::with_local_config(BTreeMap::new());
+ let mut ctx = mock.create_ctx_for_runtime::<AlphabetRuntime>(false);
+
+ Dispatcher::<AlphabetRuntime>::dispatch_query(
+ &mut ctx,
+ "alphabet.Alpha",
+ cbor::to_vec(().into_cbor_value()),
+ )
+ .expect("alphabet.Alpha is an inexpensive query, allowed by default");
+
+ Dispatcher::<AlphabetRuntime>::dispatch_query(
+ &mut ctx,
+ "alphabet.Omega",
+ cbor::to_vec(().into_cbor_value()),
+ )
+ .expect_err("alphabet.Omega is an expensive query, disallowed by default");
+ }
+
+ #[test]
+ fn test_allowed_queries_custom() {
+ let local_config = configmap! {
+ // Allow expensive gas estimation and expensive queries so they can be tested.
+ "estimate_gas_by_simulating_contracts" => true,
+ "allowed_queries" => vec![
+ configmap! {"alphabet.Alpha" => false},
+ configmap! {"all_expensive" => true},
+ configmap! {"all" => true} // should have no effect on Alpha
+ ],
+ };
+ let mut mock = Mock::with_local_config(local_config);
+ let mut ctx = mock.create_ctx_for_runtime::<AlphabetRuntime>(false);
+
+ CurrentState::with_transaction_opts(Options::new().with_mode(state::Mode::Check), || {
+ Dispatcher::<AlphabetRuntime>::dispatch_query(
+ &mut ctx,
+ "alphabet.Alpha",
+ cbor::to_vec(().into_cbor_value()),
+ )
+ .expect_err("alphabet.Alpha is a disallowed query");
+
+ Dispatcher::<AlphabetRuntime>::dispatch_query(
+ &mut ctx,
+ "alphabet.Omega",
+ cbor::to_vec(().into_cbor_value()),
+ )
+ .expect("alphabet.Omega is an expensive query and expensive queries are allowed");
+
+ TransactionResult::Rollback(())
+ });
+ }
+
+ #[test]
+ fn test_dispatch_read_only_call() {
+ let mut mock = Mock::default();
+ let mut ctx = mock.create_ctx_for_runtime::<AlphabetRuntime>(false);
+
+ AlphabetRuntime::migrate(&mut ctx);
+
+ let mut tx = transaction::Transaction {
+ version: 1,
+ call: transaction::Call {
+ format: transaction::CallFormat::Plain,
+ method: "alphabet.ReadOnly".to_owned(),
+ read_only: true,
+ ..Default::default()
+ },
+ auth_info: transaction::AuthInfo {
+ signer_info: vec![transaction::SignerInfo::new_sigspec(
+ keys::alice::sigspec(),
+ 0,
+ )],
+ fee: transaction::Fee {
+ amount: token::BaseUnits::new(0, token::Denomination::NATIVE),
+ gas: 1000,
+ ..Default::default()
+ },
+ ..Default::default()
+ },
+ };
+
+ // Dispatch read-only transaction.
+ let dispatch_result =
+ Dispatcher::<AlphabetRuntime>::dispatch_tx(&mut ctx, 1024, tx.clone(), 0)
+ .expect("read only method dispatch should work");
+ let result = dispatch_result.result.unwrap();
+ let result: u64 = cbor::from_value(result).unwrap();
+ assert_eq!(result, 42);
+
+ // Dispatch read-only transaction of a method that writes.
+ tx.call.method = "alphabet.NotReadOnly".to_owned();
+
+ let dispatch_result = Dispatcher::<AlphabetRuntime>::dispatch_tx(&mut ctx, 1024, tx, 0)
+ .expect("read only method dispatch should work");
+ match dispatch_result.result {
+ module::CallResult::Failed {
+ module,
+ code,
+ message,
+ } => {
+ assert_eq!(&module, "core");
+ assert_eq!(code, 25);
+ assert_eq!(&message, "read-only transaction attempted modifications")
+ }
+ _ => panic!("not read only method execution did not fail"),
+ }
+ }
+
+ #[test]
+ fn test_dispatch_abort_forwarding() {
+ let mut mock = Mock::default();
+ let mut ctx = mock.create_ctx_for_runtime::<AlphabetRuntime>(false);
+
+ AlphabetRuntime::migrate(&mut ctx);
+
+ let tx = transaction::Transaction {
+ version: 1,
+ call: transaction::Call {
+ format: transaction::CallFormat::Plain,
+ method: "alphabet.Aborting".to_owned(),
+ ..Default::default()
+ },
+ auth_info: transaction::AuthInfo {
+ signer_info: vec![transaction::SignerInfo::new_sigspec(
+ keys::alice::sigspec(),
+ 0,
+ )],
+ fee: transaction::Fee {
+ amount: token::BaseUnits::new(0, token::Denomination::NATIVE),
+ gas: 1000,
+ ..Default::default()
+ },
+ ..Default::default()
+ },
+ };
+
+ // Dispatch transaction and make sure the abort gets propagated.
+ let dispatch_result =
+ Dispatcher::<AlphabetRuntime>::dispatch_tx(&mut ctx, 1024, tx.clone(), 0);
+ assert!(matches!(dispatch_result, Err(Error::Aborted)));
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +
//! Exposed EnclaveRPC methods.
+use std::{marker::PhantomData, sync::Arc};
+
+use anyhow::{anyhow, bail, Result};
+
+use crate::{
+ context::RuntimeBatchContext,
+ core::{
+ consensus::{
+ roothash::Header,
+ state::{
+ beacon::ImmutableState as BeaconState, registry::ImmutableState as RegistryState,
+ roothash::ImmutableState as RoothashState,
+ },
+ verifier::Verifier,
+ },
+ enclave_rpc::{
+ dispatcher::{
+ Dispatcher as RpcDispatcher, Method as RpcMethod,
+ MethodDescriptor as RpcMethodDescriptor,
+ },
+ types::Kind as RpcKind,
+ Context as RpcContext,
+ },
+ future::block_on,
+ protocol::{HostInfo, Protocol},
+ storage::mkvs,
+ },
+ dispatcher,
+ keymanager::KeyManagerClient,
+ module::MethodHandler,
+ state::{self, CurrentState},
+ storage::HostStore,
+ Runtime,
+};
+
+/// Name of the `query` method.
+pub const METHOD_QUERY: &str = "runtime-sdk/query";
+
+/// Arguments for the `query` method.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct QueryRequest {
+ pub round: u64,
+ pub method: String,
+ pub args: Vec<u8>,
+}
+
+/// EnclaveRPC dispatcher wrapper.
+pub(crate) struct Wrapper<R: Runtime> {
+ host_info: HostInfo,
+ host: Arc<Protocol>,
+ key_manager: Option<Arc<KeyManagerClient>>,
+ consensus_verifier: Arc<dyn Verifier>,
+ _runtime: PhantomData<R>,
+}
+
+impl<R> Wrapper<R>
+where
+ R: Runtime + Send + Sync + 'static,
+{
+ pub(crate) fn wrap(
+ rpc: &mut RpcDispatcher,
+ host: Arc<Protocol>,
+ host_info: HostInfo,
+ key_manager: Option<Arc<KeyManagerClient>>,
+ consensus_verifier: Arc<dyn Verifier>,
+ ) {
+ let wrapper = Box::leak(Box::new(Self {
+ host_info,
+ host,
+ key_manager,
+ consensus_verifier,
+ _runtime: PhantomData,
+ }));
+ rpc.add_methods(wrapper.methods());
+ }
+
+ fn methods(&'static self) -> Vec<RpcMethod> {
+ vec![RpcMethod::new(
+ RpcMethodDescriptor {
+ name: METHOD_QUERY.to_string(),
+ kind: RpcKind::NoiseSession,
+ },
+ move |ctx: &_, req: &_| self.rpc_query(ctx, req),
+ )]
+ }
+
+ fn ensure_session_endorsed(&self, ctx: &RpcContext) -> Result<()> {
+ let endorsed_by = ctx
+ .session_info
+ .as_ref()
+ .ok_or(anyhow!("not authorized"))?
+ .endorsed_by
+ .ok_or(anyhow!("not endorsed by host"))?;
+ let host_identity = self
+ .host
+ .get_identity()
+ .ok_or(anyhow!("local identity not available"))?
+ .node_identity()
+ .ok_or(anyhow!("node identity not available"))?;
+ if endorsed_by != host_identity {
+ bail!("not endorsed by host");
+ }
+ Ok(())
+ }
+
+ fn rpc_query(&self, ctx: &RpcContext, req: &QueryRequest) -> Result<Vec<u8>> {
+ self.ensure_session_endorsed(ctx)?;
+
+ // Determine whether the method is allowed to access confidential state and provide an
+ // appropriately scoped instance of the key manager client.
+ let is_confidential_allowed = R::Modules::is_allowed_private_km_query(&req.method)
+ && R::is_allowed_private_km_query(&req.method);
+ let key_manager = self.key_manager.as_ref().map(|mgr| {
+ if is_confidential_allowed {
+ mgr.with_private_context()
+ } else {
+ mgr.with_context()
+ }
+ });
+
+ // Fetch latest consensus layer state.
+ let state = block_on(self.consensus_verifier.latest_state())?;
+ let roothash = RoothashState::new(&state);
+ let roots = roothash
+ .round_roots(self.host_info.runtime_id, req.round)?
+ .ok_or(anyhow!("root not found"))?;
+ let beacon = BeaconState::new(&state);
+ let epoch = beacon.epoch()?;
+ let registry = RegistryState::new(&state);
+ let runtime = registry
+ .runtime(&self.host_info.runtime_id)?
+ .ok_or(anyhow!("runtime not found"))?;
+
+ // Prepare dispatch context.
+ let history = self.consensus_verifier.clone();
+ let root = HostStore::new(
+ self.host.clone(),
+ mkvs::Root {
+ namespace: self.host_info.runtime_id,
+ version: req.round,
+ root_type: mkvs::RootType::State,
+ hash: roots.state_root,
+ },
+ );
+ // TODO: This is currently limited as we have no nice way of getting a good known header. We
+ // need to expose more stuff in roothash and then limit the query to latest round. Until
+ // then any queries requiring access to features like timestamp will fail as we need to
+ // ensure we use safe values for these arguments.
+ let header = Header {
+ namespace: self.host_info.runtime_id,
+ round: req.round,
+ io_root: roots.io_root,
+ state_root: roots.state_root,
+ ..Default::default()
+ };
+ let round_results = Default::default();
+ let max_messages = runtime.executor.max_messages;
+
+ let ctx = RuntimeBatchContext::<'_, R>::new(
+ &self.host_info,
+ key_manager,
+ &header,
+ &round_results,
+ &state,
+ &history,
+ epoch,
+ max_messages,
+ );
+
+ CurrentState::enter_opts(
+ state::Options::new()
+ .with_mode(state::Mode::Check)
+ .with_rng_local_entropy(), // Mix in local (private) entropy for queries.
+ root,
+ || dispatcher::Dispatcher::<R>::dispatch_query(&ctx, &req.method, req.args.clone()),
+ )
+ .map_err(Into::into)
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +
//! Error types for runtimes.
+pub use oasis_core_runtime::types::Error as RuntimeError;
+
+use crate::{dispatcher, module::CallResult};
+
+/// A runtime error that gets propagated to the caller.
+///
+/// It extends `std::error::Error` with module name and error code so that errors can be easily
+/// serialized and transferred between different processes.
+///
+/// This trait can be derived:
+/// ```
+/// # #[cfg(feature = "oasis-runtime-sdk-macros")]
+/// # mod example {
+/// # use oasis_runtime_sdk_macros::Error;
+/// const MODULE_NAME: &str = "my-module";
+/// #[derive(Clone, Debug, Error, thiserror::Error)]
+/// #[sdk_error(autonumber)] // `module_name` meta is required if `MODULE_NAME` isn't in scope
+/// enum Error {
+/// #[error("invalid argument")]
+/// InvalidArgument, // autonumbered to 0
+///
+/// #[error("forbidden")]
+/// #[sdk_error(code = 401)] // manually numbered to 403 (`code` or autonumbering is required)
+/// Forbidden,
+/// }
+/// # }
+/// ```
+pub trait Error: std::error::Error {
+ /// Name of the module that emitted the error.
+ fn module_name(&self) -> &str;
+
+ /// Error code uniquely identifying the error.
+ fn code(&self) -> u32;
+
+ /// Converts the error into a call result.
+ fn into_call_result(self) -> CallResult
+ where
+ Self: Sized,
+ {
+ match self.into_abort() {
+ Ok(err) => CallResult::Aborted(err),
+ Err(failed) => CallResult::Failed {
+ module: failed.module_name().to_owned(),
+ code: failed.code(),
+ message: failed.to_string(),
+ },
+ }
+ }
+
+ /// Consumes self and returns either `Ok(err)` (where `err` is a dispatcher error) when batch
+ /// should abort or `Err(self)` when this is just a regular error.
+ fn into_abort(self) -> Result<dispatcher::Error, Self>
+ where
+ Self: Sized,
+ {
+ Err(self)
+ }
+}
+
+impl Error for std::convert::Infallible {
+ fn module_name(&self) -> &str {
+ "(none)"
+ }
+
+ fn code(&self) -> u32 {
+ Default::default()
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ const MODULE_NAME_1: &str = "test1";
+ const MODULE_NAME_2: &str = "test2";
+
+ #[derive(thiserror::Error, Debug, oasis_runtime_sdk_macros::Error)]
+ #[sdk_error(module_name = "MODULE_NAME_1")]
+ enum ChildError {
+ #[error("first error")]
+ #[sdk_error(code = 1)]
+ Error1,
+
+ #[error("second error")]
+ #[sdk_error(code = 2)]
+ Error2,
+ }
+
+ #[derive(thiserror::Error, Debug, oasis_runtime_sdk_macros::Error)]
+ #[sdk_error(module_name = "MODULE_NAME_2")]
+ enum ParentError {
+ #[error("first error")]
+ #[sdk_error(code = 1)]
+ NotForwarded(#[source] ChildError),
+
+ #[error("nested error")]
+ #[sdk_error(transparent)]
+ Nested(#[source] ChildError),
+ }
+
+ #[derive(thiserror::Error, Debug, oasis_runtime_sdk_macros::Error)]
+ enum ParentParentError {
+ #[error("nested nested error")]
+ #[sdk_error(transparent)]
+ Nested(#[source] ParentError),
+ }
+
+ #[test]
+ fn test_error_sources_1() {
+ let err = ParentError::Nested(ChildError::Error1);
+ let result = err.into_call_result();
+
+ match result {
+ CallResult::Failed {
+ module,
+ code,
+ message: _,
+ } => {
+ assert_eq!(module, "test1");
+ assert_eq!(code, 1);
+ }
+ _ => panic!("expected failed result, got: {:?}", result),
+ }
+
+ let err = ParentError::Nested(ChildError::Error2);
+ let result = err.into_call_result();
+
+ match result {
+ CallResult::Failed {
+ module,
+ code,
+ message: _,
+ } => {
+ assert_eq!(module, "test1");
+ assert_eq!(code, 2);
+ }
+ _ => panic!("expected failed result, got: {:?}", result),
+ }
+ }
+
+ #[test]
+ fn test_error_sources_2() {
+ let err = ParentError::NotForwarded(ChildError::Error1);
+ let result = err.into_call_result();
+
+ match result {
+ CallResult::Failed {
+ module,
+ code,
+ message: _,
+ } => {
+ assert_eq!(module, "test2");
+ assert_eq!(code, 1);
+ }
+ _ => panic!("expected failed result, got: {:?}", result),
+ }
+
+ let err = ParentError::NotForwarded(ChildError::Error2);
+ let result = err.into_call_result();
+
+ match result {
+ CallResult::Failed {
+ module,
+ code,
+ message: _,
+ } => {
+ assert_eq!(module, "test2");
+ assert_eq!(code, 1);
+ }
+ _ => panic!("expected failed result, got: {:?}", result),
+ }
+ }
+
+ #[test]
+ fn test_error_sources_3() {
+ let err = ParentParentError::Nested(ParentError::Nested(ChildError::Error1));
+ let result = err.into_call_result();
+
+ match result {
+ CallResult::Failed {
+ module,
+ code,
+ message: _,
+ } => {
+ assert_eq!(module, "test1");
+ assert_eq!(code, 1);
+ }
+ _ => panic!("expected failed result, got: {:?}", result),
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +
//! Event types for runtimes.
+use std::collections::BTreeMap;
+
+use oasis_core_runtime::transaction::tags::{Tag, Tags};
+
+/// An event emitted by the runtime.
+///
+/// This trait can be derived:
+/// ```
+/// # #[cfg(feature = "oasis-runtime-sdk-macros")]
+/// # mod example {
+/// # use oasis_runtime_sdk_macros::Event;
+/// const MODULE_NAME: &str = "my-module";
+/// #[derive(Clone, Debug, cbor::Encode, Event)]
+/// #[cbor(untagged)]
+/// #[sdk_event(autonumber)] // `module_name` meta is required if `MODULE_NAME` isn't in scope
+/// enum MyEvent {
+/// Greeting(String), // autonumbered to 0
+/// #[sdk_event(code = 2)] // manually numbered to 2 (`code` is required if not autonumbering)
+/// DontPanic,
+/// Salutation { // autonumbered to 1
+/// plural: bool,
+/// }
+/// }
+/// # }
+/// ```
+pub trait Event: Sized + cbor::Encode {
+ /// Name of the module that emitted the event.
+ fn module_name() -> &'static str;
+
+ /// Code uniquely identifying the event.
+ fn code(&self) -> u32;
+
+ /// Converts an event into an event tag.
+ ///
+ /// # Key
+ ///
+ /// ```text
+ /// <module (variable size bytes)> <code (big-endian u32)>
+ /// ```
+ ///
+ /// # Value
+ ///
+ /// CBOR-serialized event value.
+ ///
+ fn into_event_tag(self) -> EventTag {
+ etag_for_event(Self::module_name(), self.code(), cbor::to_value(self))
+ }
+}
+
+impl Event for () {
+ fn module_name() -> &'static str {
+ "(none)"
+ }
+
+ fn code(&self) -> u32 {
+ Default::default()
+ }
+}
+
+/// Generate an EventTag corresponding to the passed event triple.
+pub fn etag_for_event(module_name: &str, code: u32, value: cbor::Value) -> EventTag {
+ EventTag {
+ key: [module_name.as_bytes(), &code.to_be_bytes()]
+ .concat()
+ .to_vec(),
+ value,
+ }
+}
+
+/// A key-value pair representing an emitted event that will be emitted as a tag.
+#[derive(Clone, Debug)]
+pub struct EventTag {
+ pub key: Vec<u8>,
+ pub value: cbor::Value,
+}
+
+/// Event tags with values accumulated by key.
+pub type EventTags = BTreeMap<Vec<u8>, Vec<cbor::Value>>;
+
+/// Provides method for converting event tags into events.
+pub trait IntoTags {
+ fn into_tags(self) -> Tags;
+}
+
+impl IntoTags for EventTags {
+ fn into_tags(self) -> Tags {
+ self.into_iter()
+ .map(|(k, v)| Tag::new(k, cbor::to_vec(v)))
+ .collect()
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +
//! Historic state access.
+use oasis_core_runtime::{
+ consensus::{state::ConsensusState, verifier::Verifier, Event},
+ future::block_on,
+ types::EventKind,
+};
+
+/// Unique module name.
+const MODULE_NAME: &str = "history";
+
+/// History host errors.
+#[derive(Debug, thiserror::Error, oasis_runtime_sdk_macros::Error)]
+pub enum Error {
+ #[error("failed to fetch block from host")]
+ #[sdk_error(code = 1)]
+ FailedToFetchBlock,
+
+ #[error("failed to fetch events from host")]
+ #[sdk_error(code = 2)]
+ FailedToFetchEvents,
+}
+
+/// Interface to the runtime host to fetch historic information.
+pub trait HistoryHost {
+ /// Fetch historic consensus state after executing the block at given height.
+ fn consensus_state_at(&self, height: u64) -> Result<ConsensusState, Error>;
+
+ /// Fetch events emitted during execution of the block at given height.
+ fn consensus_events_at(&self, height: u64, kind: EventKind) -> Result<Vec<Event>, Error>;
+}
+
+impl HistoryHost for Box<dyn HistoryHost> {
+ fn consensus_state_at(&self, height: u64) -> Result<ConsensusState, Error> {
+ HistoryHost::consensus_state_at(&**self, height)
+ }
+
+ fn consensus_events_at(&self, height: u64, kind: EventKind) -> Result<Vec<Event>, Error> {
+ HistoryHost::consensus_events_at(&**self, height, kind)
+ }
+}
+
+impl<V: Verifier> HistoryHost for V {
+ fn consensus_state_at(&self, height: u64) -> Result<ConsensusState, Error> {
+ block_on(self.state_at(height)).map_err(|_| Error::FailedToFetchBlock)
+ }
+
+ fn consensus_events_at(&self, height: u64, kind: EventKind) -> Result<Vec<Event>, Error> {
+ block_on(self.events_at(height, kind)).map_err(|_| Error::FailedToFetchEvents)
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +
//! Keymanager interface.
+use std::sync::Arc;
+
+use tiny_keccak::{Hasher, TupleHash};
+
+use oasis_core_keymanager::client::{KeyManagerClient as CoreKeyManagerClient, RemoteClient};
+pub use oasis_core_keymanager::{
+ api::KeyManagerError,
+ crypto::{KeyPair, KeyPairId, SignedPublicKey, StateKey},
+ policy::TrustedSigners,
+};
+use oasis_core_runtime::{
+ common::{crypto::signature::PublicKey, namespace::Namespace},
+ consensus::{beacon::EpochTime, verifier::Verifier},
+ future::block_on,
+ identity::Identity,
+ protocol::Protocol,
+ RpcDispatcher,
+};
+
+/// Key manager interface. This is a runtime context-resident convenience
+/// wrapper to the keymanager configured for the runtime.
+pub(crate) struct KeyManagerClient {
+ inner: Arc<dyn CoreKeyManagerClient>,
+}
+
+impl KeyManagerClient {
+ /// Create a new key manager client using the default remote client from oasis-core.
+ pub(crate) fn new(
+ runtime_id: Namespace,
+ protocol: Arc<Protocol>,
+ consensus_verifier: Arc<dyn Verifier>,
+ identity: Arc<Identity>,
+ rpc: &mut RpcDispatcher,
+ key_cache_sizes: usize,
+ signers: TrustedSigners,
+ ) -> Self {
+ let remote_client = Arc::new(RemoteClient::new_runtime(
+ runtime_id,
+ protocol,
+ consensus_verifier,
+ identity,
+ key_cache_sizes,
+ signers,
+ ));
+
+ // Setup the quote policy update handler.
+ let handler_remote_client = remote_client.clone();
+ rpc.set_keymanager_quote_policy_update_handler(Some(Box::new(move |policy| {
+ block_on(handler_remote_client.set_quote_policy(policy));
+ })));
+
+ // Setup the status update handler.
+ let handler_remote_client = remote_client.clone();
+ rpc.set_keymanager_status_update_handler(Some(Box::new(move |status| {
+ block_on(handler_remote_client.set_status(status))
+ .expect("failed to update km client status");
+ })));
+
+ KeyManagerClient {
+ inner: remote_client,
+ }
+ }
+
+ /// Create a client proxy which will forward calls to the inner client using the given context.
+ /// Only public key queries will be allowed.
+ pub(crate) fn with_context(self: &Arc<Self>) -> Box<dyn KeyManager> {
+ Box::new(KeyManagerClientWithContext::new(self.clone(), false)) as Box<dyn KeyManager>
+ }
+
+ /// Create a client proxy which will forward calls to the inner client using the given context.
+ /// Public and private key queries will be allowed.
+ pub(crate) fn with_private_context(self: &Arc<Self>) -> Box<dyn KeyManager> {
+ Box::new(KeyManagerClientWithContext::new(self.clone(), true)) as Box<dyn KeyManager>
+ }
+
+ /// Key manager runtime identifier this client is connected to. It may be `None` in case the
+ /// identifier is not known yet (e.g. the client has not yet been initialized).
+ ///
+ /// See the oasis-core documentation for details.
+ pub(crate) fn runtime_id(&self) -> Option<Namespace> {
+ self.inner.runtime_id()
+ }
+
+ /// Key manager runtime signing key used to sign messages from the key manager.
+ ///
+ /// See the oasis-core documentation for details.
+ pub(crate) fn runtime_signing_key(&self) -> Option<PublicKey> {
+ self.inner.runtime_signing_key()
+ }
+
+ /// Clear local key cache.
+ ///
+ /// See the oasis-core documentation for details.
+ pub(crate) fn clear_cache(&self) {
+ self.inner.clear_cache()
+ }
+
+ /// Get or create named key pair.
+ ///
+ /// See the oasis-core documentation for details.
+ pub(crate) async fn get_or_create_keys(
+ &self,
+ key_pair_id: KeyPairId,
+ ) -> Result<KeyPair, KeyManagerError> {
+ retryable(|| self.inner.get_or_create_keys(key_pair_id, 0)).await
+ }
+
+ /// Get public key for a key pair id.
+ ///
+ /// See the oasis-core documentation for details.
+ pub(crate) async fn get_public_key(
+ &self,
+ key_pair_id: KeyPairId,
+ ) -> Result<SignedPublicKey, KeyManagerError> {
+ retryable(|| self.inner.get_public_key(key_pair_id, 0)).await
+ }
+
+ /// Get or create named ephemeral key pair for given epoch.
+ ///
+ /// See the oasis-core documentation for details.
+ pub(crate) async fn get_or_create_ephemeral_keys(
+ &self,
+ key_pair_id: KeyPairId,
+ epoch: EpochTime,
+ ) -> Result<KeyPair, KeyManagerError> {
+ retryable(|| self.inner.get_or_create_ephemeral_keys(key_pair_id, epoch)).await
+ }
+
+ /// Get ephemeral public key for an epoch and a key pair id.
+ ///
+ /// See the oasis-core documentation for details.
+ pub(crate) async fn get_public_ephemeral_key(
+ &self,
+ key_pair_id: KeyPairId,
+ epoch: EpochTime,
+ ) -> Result<SignedPublicKey, KeyManagerError> {
+ retryable(|| self.inner.get_public_ephemeral_key(key_pair_id, epoch)).await
+ }
+}
+
+/// Decorator for remote method calls that can be safely retried.
+async fn retryable<A>(action: A) -> Result<A::Item, A::Error>
+where
+ A: tokio_retry::Action,
+{
+ let retry_strategy = tokio_retry::strategy::ExponentialBackoff::from_millis(4)
+ .max_delay(std::time::Duration::from_millis(250))
+ .map(tokio_retry::strategy::jitter)
+ .take(5);
+
+ tokio_retry::Retry::spawn(retry_strategy, action).await
+}
+
+/// Key manager interface.
+pub trait KeyManager {
+ /// Key manager runtime identifier this client is connected to. It may be `None` in case the
+ /// identifier is not known yet (e.g. the client has not yet been initialized).
+ ///
+ /// See the oasis-core documentation for details.
+ fn runtime_id(&self) -> Option<Namespace>;
+
+ /// Key manager runtime signing key used to sign messages from the key manager.
+ ///
+ /// See the oasis-core documentation for details.
+ fn runtime_signing_key(&self) -> Option<PublicKey>;
+
+ /// Clear local key cache.
+ ///
+ /// See the oasis-core documentation for details.
+ fn clear_cache(&self);
+
+ /// Get or create named key pair.
+ ///
+ /// See the oasis-core documentation for details. This variant of the method
+ /// synchronously blocks for the result.
+ fn get_or_create_keys(&self, key_pair_id: KeyPairId) -> Result<KeyPair, KeyManagerError>;
+
+ /// Get public key for a key pair id.
+ ///
+ /// See the oasis-core documentation for details. This variant of the method
+ /// synchronously blocks for the result.
+ fn get_public_key(&self, key_pair_id: KeyPairId) -> Result<SignedPublicKey, KeyManagerError>;
+
+ /// Get or create named ephemeral key pair for given epoch.
+ ///
+ /// See the oasis-core documentation for details. This variant of the method
+ /// synchronously blocks for the result.
+ fn get_or_create_ephemeral_keys(
+ &self,
+ key_pair_id: KeyPairId,
+ epoch: EpochTime,
+ ) -> Result<KeyPair, KeyManagerError>;
+
+ /// Get ephemeral public key for an epoch and a key pair id.
+ ///
+ /// See the oasis-core documentation for details. This variant of the method
+ /// synchronously blocks for the result.
+ fn get_public_ephemeral_key(
+ &self,
+ key_pair_id: KeyPairId,
+ epoch: EpochTime,
+ ) -> Result<SignedPublicKey, KeyManagerError>;
+
+ fn box_clone(&self) -> Box<dyn KeyManager>;
+}
+
+impl Clone for Box<dyn KeyManager> {
+ fn clone(&self) -> Box<dyn KeyManager> {
+ self.box_clone()
+ }
+}
+
+/// Convenience wrapper around an existing KeyManagerClient instance which uses
+/// a default io context for all calls.
+#[derive(Clone)]
+pub struct KeyManagerClientWithContext {
+ parent: Arc<KeyManagerClient>,
+ allow_private: bool,
+}
+
+impl KeyManagerClientWithContext {
+ fn new(parent: Arc<KeyManagerClient>, allow_private: bool) -> KeyManagerClientWithContext {
+ KeyManagerClientWithContext {
+ parent,
+ allow_private,
+ }
+ }
+
+ /// Get or create named key pair.
+ ///
+ /// See the oasis-core documentation for details.
+ async fn get_or_create_keys_async(
+ &self,
+ key_pair_id: KeyPairId,
+ ) -> Result<KeyPair, KeyManagerError> {
+ if !self.allow_private {
+ return Err(KeyManagerError::Other(anyhow::anyhow!(
+ "not allowed by local runtime policy"
+ )));
+ }
+
+ self.parent.get_or_create_keys(key_pair_id).await
+ }
+
+ /// Get public key for a key pair id.
+ ///
+ /// See the oasis-core documentation for details.
+ async fn get_public_key_async(
+ &self,
+ key_pair_id: KeyPairId,
+ ) -> Result<SignedPublicKey, KeyManagerError> {
+ self.parent.get_public_key(key_pair_id).await
+ }
+
+ /// Get ephemeral public key for an epoch and a key pair id.
+ ///
+ /// See the oasis-core documentation for details.
+ async fn get_or_create_ephemeral_keys_async(
+ &self,
+ key_pair_id: KeyPairId,
+ epoch: EpochTime,
+ ) -> Result<KeyPair, KeyManagerError> {
+ if !self.allow_private {
+ return Err(KeyManagerError::Other(anyhow::anyhow!(
+ "not allowed by local runtime policy"
+ )));
+ }
+
+ self.parent
+ .get_or_create_ephemeral_keys(key_pair_id, epoch)
+ .await
+ }
+
+ /// Get ephemeral public key for an epoch and a key pair id.
+ ///
+ /// See the oasis-core documentation for details.
+ async fn get_public_ephemeral_key_async(
+ &self,
+ key_pair_id: KeyPairId,
+ epoch: EpochTime,
+ ) -> Result<SignedPublicKey, KeyManagerError> {
+ self.parent
+ .get_public_ephemeral_key(key_pair_id, epoch)
+ .await
+ }
+}
+
+impl KeyManager for KeyManagerClientWithContext {
+ fn runtime_id(&self) -> Option<Namespace> {
+ self.parent.runtime_id()
+ }
+
+ fn runtime_signing_key(&self) -> Option<PublicKey> {
+ self.parent.runtime_signing_key()
+ }
+
+ fn clear_cache(&self) {
+ self.parent.clear_cache();
+ }
+
+ fn get_or_create_keys(&self, key_pair_id: KeyPairId) -> Result<KeyPair, KeyManagerError> {
+ block_on(self.get_or_create_keys_async(key_pair_id))
+ }
+
+ fn get_public_key(&self, key_pair_id: KeyPairId) -> Result<SignedPublicKey, KeyManagerError> {
+ block_on(self.get_public_key_async(key_pair_id))
+ }
+
+ fn get_or_create_ephemeral_keys(
+ &self,
+ key_pair_id: KeyPairId,
+ epoch: EpochTime,
+ ) -> Result<KeyPair, KeyManagerError> {
+ block_on(self.get_or_create_ephemeral_keys_async(key_pair_id, epoch))
+ }
+
+ fn get_public_ephemeral_key(
+ &self,
+ key_pair_id: KeyPairId,
+ epoch: EpochTime,
+ ) -> Result<SignedPublicKey, KeyManagerError> {
+ block_on(self.get_public_ephemeral_key_async(key_pair_id, epoch))
+ }
+
+ fn box_clone(&self) -> Box<dyn KeyManager> {
+ Box::new(self.clone())
+ }
+}
+
+/// Key pair ID domain separation context.
+pub const KEY_PAIR_ID_CONTEXT: &[u8] = b"oasis-runtime-sdk/keymanager: key pair id";
+
+/// Derive a `KeyPairId` for use with the key manager functions.
+pub fn get_key_pair_id<'a, C>(context: C) -> KeyPairId
+where
+ C: IntoIterator<Item = &'a [u8]> + 'a,
+{
+ let mut h = TupleHash::v256(KEY_PAIR_ID_CONTEXT);
+ for item in context.into_iter() {
+ h.update(item);
+ }
+ let mut key_pair_id = [0u8; 32];
+ h.finalize(&mut key_pair_id);
+
+ KeyPairId(key_pair_id)
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +
//! Oasis runtime SDK.
+#![feature(test)]
+#![feature(associated_type_defaults)]
+#![deny(rust_2018_idioms, unreachable_pub)]
+
+pub mod callformat;
+pub mod config;
+pub mod context;
+pub mod crypto;
+pub mod dispatcher;
+pub mod enclave_rpc;
+pub mod error;
+pub mod event;
+pub mod history;
+pub mod keymanager;
+pub mod module;
+pub mod modules;
+pub mod runtime;
+pub mod schedule_control;
+pub mod sender;
+pub mod state;
+pub mod storage;
+pub mod subcall;
+pub mod testing;
+pub mod types;
+
+pub use crate::{
+ context::Context, core::common::version::Version, module::Module, runtime::Runtime,
+ state::CurrentState,
+};
+
+// Re-export the appropriate version of the oasis-core-runtime library.
+pub use oasis_core_runtime as core;
+
+// Re-export the cbor crate.
+pub use cbor;
+
+// Re-export the SDK support proc-macros.
+#[cfg(feature = "oasis-runtime-sdk-macros")]
+pub use oasis_runtime_sdk_macros::*;
+
+// Required so that proc-macros can refer to items within this crate.
+use crate as oasis_runtime_sdk;
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +
//! Runtime modules.
+use std::{
+ collections::{BTreeMap, BTreeSet},
+ fmt::Debug,
+};
+
+use cbor::Encode as _;
+use impl_trait_for_tuples::impl_for_tuples;
+
+use crate::{
+ context::Context,
+ dispatcher, error,
+ error::Error as _,
+ event, modules,
+ modules::core::types::{MethodHandlerInfo, ModuleInfo},
+ state::CurrentState,
+ storage,
+ storage::Prefix,
+ types::{
+ address::Address,
+ message::MessageResult,
+ transaction::{self, AuthInfo, Call, Transaction, UnverifiedTransaction},
+ },
+};
+
+/// Result of invoking the method handler.
+pub enum DispatchResult<B, R> {
+ Handled(R),
+ Unhandled(B),
+}
+
+impl<B, R> DispatchResult<B, R> {
+ /// Transforms `DispatchResult<B, R>` into `Result<R, E>`, mapping `Handled(r)` to `Ok(r)` and
+ /// `Unhandled(_)` to `Err(err)`.
+ pub fn ok_or<E>(self, err: E) -> Result<R, E> {
+ match self {
+ DispatchResult::Handled(result) => Ok(result),
+ DispatchResult::Unhandled(_) => Err(err),
+ }
+ }
+
+ /// Transforms `DispatchResult<B, R>` into `Result<R, E>`, mapping `Handled(r)` to `Ok(r)` and
+ /// `Unhandled(_)` to `Err(err)` using the provided function.
+ pub fn ok_or_else<E, F: FnOnce() -> E>(self, errf: F) -> Result<R, E> {
+ match self {
+ DispatchResult::Handled(result) => Ok(result),
+ DispatchResult::Unhandled(_) => Err(errf()),
+ }
+ }
+}
+
+/// A variant of `types::transaction::CallResult` but used for dispatch purposes so the dispatch
+/// process can use a different representation.
+///
+/// Specifically, this type is not serializable.
+#[derive(Debug)]
+pub enum CallResult {
+ /// Call has completed successfully.
+ Ok(cbor::Value),
+
+ /// Call has completed with failure.
+ Failed {
+ module: String,
+ code: u32,
+ message: String,
+ },
+
+ /// A fatal error has occurred and the batch must be aborted.
+ Aborted(dispatcher::Error),
+}
+
+impl CallResult {
+ /// Check whether the call result indicates a successful operation or not.
+ pub fn is_success(&self) -> bool {
+ matches!(self, CallResult::Ok(_))
+ }
+
+ #[cfg(any(test, feature = "test"))]
+ pub fn unwrap(self) -> cbor::Value {
+ match self {
+ Self::Ok(v) => v,
+ Self::Failed {
+ module,
+ code,
+ message,
+ } => panic!("{module} reported failure with code {code}: {message}"),
+ Self::Aborted(e) => panic!("tx aborted with error: {e}"),
+ }
+ }
+
+ #[cfg(any(test, feature = "test"))]
+ pub fn unwrap_failed(self) -> (String, u32) {
+ match self {
+ Self::Ok(_) => panic!("call result indicates success"),
+ Self::Failed { module, code, .. } => (module, code),
+ Self::Aborted(e) => panic!("tx aborted with error: {e}"),
+ }
+ }
+}
+
+impl From<CallResult> for transaction::CallResult {
+ fn from(v: CallResult) -> Self {
+ match v {
+ CallResult::Ok(data) => Self::Ok(data),
+ CallResult::Failed {
+ module,
+ code,
+ message,
+ } => Self::Failed {
+ module,
+ code,
+ message,
+ },
+ CallResult::Aborted(err) => Self::Failed {
+ module: err.module_name().to_string(),
+ code: err.code(),
+ message: err.to_string(),
+ },
+ }
+ }
+}
+
+/// A convenience function for dispatching method calls.
+pub fn dispatch_call<C, B, R, E, F>(
+ ctx: &C,
+ body: cbor::Value,
+ f: F,
+) -> DispatchResult<cbor::Value, CallResult>
+where
+ C: Context,
+ B: cbor::Decode,
+ R: cbor::Encode,
+ E: error::Error,
+ F: FnOnce(&C, B) -> Result<R, E>,
+{
+ DispatchResult::Handled((|| {
+ let args = match cbor::from_value(body)
+ .map_err(|err| modules::core::Error::InvalidArgument(err.into()))
+ {
+ Ok(args) => args,
+ Err(err) => return err.into_call_result(),
+ };
+
+ match f(ctx, args) {
+ Ok(value) => CallResult::Ok(cbor::to_value(value)),
+ Err(err) => err.into_call_result(),
+ }
+ })())
+}
+
+/// A convenience function for dispatching queries.
+pub fn dispatch_query<C, B, R, E, F>(
+ ctx: &C,
+ body: cbor::Value,
+ f: F,
+) -> DispatchResult<cbor::Value, Result<cbor::Value, error::RuntimeError>>
+where
+ C: Context,
+ B: cbor::Decode,
+ R: cbor::Encode,
+ E: error::Error,
+ error::RuntimeError: From<E>,
+ F: FnOnce(&C, B) -> Result<R, E>,
+{
+ DispatchResult::Handled((|| {
+ let args = cbor::from_value(body).map_err(|err| -> error::RuntimeError {
+ modules::core::Error::InvalidArgument(err.into()).into()
+ })?;
+ Ok(cbor::to_value(f(ctx, args)?))
+ })())
+}
+
+/// Method handler.
+pub trait MethodHandler {
+ /// Add storage prefixes to prefetch.
+ fn prefetch(
+ _prefixes: &mut BTreeSet<Prefix>,
+ _method: &str,
+ body: cbor::Value,
+ _auth_info: &AuthInfo,
+ ) -> DispatchResult<cbor::Value, Result<(), error::RuntimeError>> {
+ // Default implementation indicates that the call was not handled.
+ DispatchResult::Unhandled(body)
+ }
+
+ /// Dispatch a call.
+ fn dispatch_call<C: Context>(
+ _ctx: &C,
+ _method: &str,
+ body: cbor::Value,
+ ) -> DispatchResult<cbor::Value, CallResult> {
+ // Default implementation indicates that the call was not handled.
+ DispatchResult::Unhandled(body)
+ }
+
+ /// Dispatch a query.
+ fn dispatch_query<C: Context>(
+ _ctx: &C,
+ _method: &str,
+ args: cbor::Value,
+ ) -> DispatchResult<cbor::Value, Result<cbor::Value, error::RuntimeError>> {
+ // Default implementation indicates that the query was not handled.
+ DispatchResult::Unhandled(args)
+ }
+
+ /// Dispatch a message result.
+ fn dispatch_message_result<C: Context>(
+ _ctx: &C,
+ _handler_name: &str,
+ result: MessageResult,
+ ) -> DispatchResult<MessageResult, ()> {
+ // Default implementation indicates that the query was not handled.
+ DispatchResult::Unhandled(result)
+ }
+
+ /// Lists the names of all RPC methods exposed by this module. The result is informational
+ /// only. An empty return vector means that the implementor does not care to list the methods,
+ /// or the implementor is a tuple of modules.
+ fn supported_methods() -> Vec<MethodHandlerInfo> {
+ vec![]
+ }
+
+ /// Checks whether the given query method is tagged as expensive.
+ fn is_expensive_query(_method: &str) -> bool {
+ false
+ }
+
+ /// Checks whether the given query is allowed to access private key manager state.
+ fn is_allowed_private_km_query(_method: &str) -> bool {
+ false
+ }
+
+ /// Checks whether the given call is allowed to be called interactively via read-only
+ /// transactions.
+ fn is_allowed_interactive_call(_method: &str) -> bool {
+ false
+ }
+}
+
+#[impl_for_tuples(30)]
+impl MethodHandler for Tuple {
+ fn prefetch(
+ prefixes: &mut BTreeSet<Prefix>,
+ method: &str,
+ body: cbor::Value,
+ auth_info: &AuthInfo,
+ ) -> DispatchResult<cbor::Value, Result<(), error::RuntimeError>> {
+ // Return on first handler that can handle the method.
+ for_tuples!( #(
+ let body = match Tuple::prefetch(prefixes, method, body, auth_info) {
+ DispatchResult::Handled(result) => return DispatchResult::Handled(result),
+ DispatchResult::Unhandled(body) => body,
+ };
+ )* );
+
+ DispatchResult::Unhandled(body)
+ }
+
+ fn dispatch_call<C: Context>(
+ ctx: &C,
+ method: &str,
+ body: cbor::Value,
+ ) -> DispatchResult<cbor::Value, CallResult> {
+ // Return on first handler that can handle the method.
+ for_tuples!( #(
+ let body = match Tuple::dispatch_call::<C>(ctx, method, body) {
+ DispatchResult::Handled(result) => return DispatchResult::Handled(result),
+ DispatchResult::Unhandled(body) => body,
+ };
+ )* );
+
+ DispatchResult::Unhandled(body)
+ }
+
+ fn dispatch_query<C: Context>(
+ ctx: &C,
+ method: &str,
+ args: cbor::Value,
+ ) -> DispatchResult<cbor::Value, Result<cbor::Value, error::RuntimeError>> {
+ // Return on first handler that can handle the method.
+ for_tuples!( #(
+ let args = match Tuple::dispatch_query::<C>(ctx, method, args) {
+ DispatchResult::Handled(result) => return DispatchResult::Handled(result),
+ DispatchResult::Unhandled(args) => args,
+ };
+ )* );
+
+ DispatchResult::Unhandled(args)
+ }
+
+ fn dispatch_message_result<C: Context>(
+ ctx: &C,
+ handler_name: &str,
+ result: MessageResult,
+ ) -> DispatchResult<MessageResult, ()> {
+ // Return on first handler that can handle the method.
+ for_tuples!( #(
+ let result = match Tuple::dispatch_message_result::<C>(ctx, handler_name, result) {
+ DispatchResult::Handled(result) => return DispatchResult::Handled(result),
+ DispatchResult::Unhandled(result) => result,
+ };
+ )* );
+
+ DispatchResult::Unhandled(result)
+ }
+
+ fn is_expensive_query(method: &str) -> bool {
+ for_tuples!( #(
+ if Tuple::is_expensive_query(method) {
+ return true;
+ }
+ )* );
+ false
+ }
+
+ fn is_allowed_private_km_query(method: &str) -> bool {
+ for_tuples!( #(
+ if Tuple::is_allowed_private_km_query(method) {
+ return true;
+ }
+ )* );
+ false
+ }
+
+ fn is_allowed_interactive_call(method: &str) -> bool {
+ for_tuples!( #(
+ if Tuple::is_allowed_interactive_call(method) {
+ return true;
+ }
+ )* );
+ false
+ }
+}
+
+/// An authentication decision for cases where multiple handlers are available.
+#[derive(Clone, Debug)]
+pub enum AuthDecision {
+ /// Authentication passed, continue with the next authentication handler.
+ Continue,
+ /// Authentication passed, no further authentication handlers should be called.
+ Stop,
+}
+
+/// Transaction handler.
+pub trait TransactionHandler {
+ /// Judge if a raw transaction is good enough to undergo decoding.
+ /// This takes place before even decoding the transaction.
+ fn approve_raw_tx<C: Context>(_ctx: &C, _tx: &[u8]) -> Result<(), modules::core::Error> {
+ // Default implementation doesn't do any checks.
+ Ok(())
+ }
+
+ /// Judge if an unverified transaction is good enough to undergo verification.
+ /// This takes place before even verifying signatures.
+ fn approve_unverified_tx<C: Context>(
+ _ctx: &C,
+ _utx: &UnverifiedTransaction,
+ ) -> Result<(), modules::core::Error> {
+ // Default implementation doesn't do any checks.
+ Ok(())
+ }
+
+ /// Decode a transaction that was sent with module-controlled decoding and verify any
+ /// signatures.
+ ///
+ /// Postcondition: if returning a Transaction, that transaction must pass `validate_basic`.
+ ///
+ /// Returns Ok(Some(_)) if the module is in charge of the encoding scheme identified by _scheme
+ /// or Ok(None) otherwise.
+ fn decode_tx<C: Context>(
+ _ctx: &C,
+ _scheme: &str,
+ _body: &[u8],
+ ) -> Result<Option<Transaction>, modules::core::Error> {
+ // Default implementation is not in charge of any schemes.
+ Ok(None)
+ }
+
+ /// Authenticate a transaction.
+ ///
+ /// Note that any signatures have already been verified.
+ fn authenticate_tx<C: Context>(
+ _ctx: &C,
+ _tx: &Transaction,
+ ) -> Result<AuthDecision, modules::core::Error> {
+ // Default implementation accepts all transactions.
+ Ok(AuthDecision::Continue)
+ }
+
+ /// Perform any action after authentication, within the transaction context.
+ ///
+ /// At this point call format has not yet been decoded so peeking into the call may not be
+ /// possible in case the call is encrypted.
+ fn before_handle_call<C: Context>(_ctx: &C, _call: &Call) -> Result<(), modules::core::Error> {
+ // Default implementation doesn't do anything.
+ Ok(())
+ }
+
+ /// Perform any action after authentication and decoding, within the transaction context.
+ ///
+ /// At this point, the call has been decoded according to the call format,
+ /// and method authorizers have run.
+ fn before_authorized_call_dispatch<C: Context>(
+ _ctx: &C,
+ _call: &Call,
+ ) -> Result<(), modules::core::Error> {
+ // Default implementation doesn't do anything.
+ Ok(())
+ }
+
+ /// Perform any action after call, within the transaction context.
+ ///
+ /// If an error is returned the transaction call fails and updates are rolled back.
+ fn after_handle_call<C: Context>(
+ _ctx: &C,
+ result: CallResult,
+ ) -> Result<CallResult, modules::core::Error> {
+ // Default implementation doesn't do anything.
+ Ok(result)
+ }
+
+ /// Perform any action after dispatching the transaction, in batch context.
+ fn after_dispatch_tx<C: Context>(_ctx: &C, _tx_auth_info: &AuthInfo, _result: &CallResult) {
+ // Default implementation doesn't do anything.
+ }
+}
+
+#[impl_for_tuples(30)]
+impl TransactionHandler for Tuple {
+ fn approve_raw_tx<C: Context>(ctx: &C, tx: &[u8]) -> Result<(), modules::core::Error> {
+ for_tuples!( #( Tuple::approve_raw_tx(ctx, tx)?; )* );
+ Ok(())
+ }
+
+ fn approve_unverified_tx<C: Context>(
+ ctx: &C,
+ utx: &UnverifiedTransaction,
+ ) -> Result<(), modules::core::Error> {
+ for_tuples!( #( Tuple::approve_unverified_tx(ctx, utx)?; )* );
+ Ok(())
+ }
+
+ fn decode_tx<C: Context>(
+ ctx: &C,
+ scheme: &str,
+ body: &[u8],
+ ) -> Result<Option<Transaction>, modules::core::Error> {
+ for_tuples!( #(
+ let decoded = Tuple::decode_tx(ctx, scheme, body)?;
+ if (decoded.is_some()) {
+ return Ok(decoded);
+ }
+ )* );
+ Ok(None)
+ }
+
+ fn authenticate_tx<C: Context>(
+ ctx: &C,
+ tx: &Transaction,
+ ) -> Result<AuthDecision, modules::core::Error> {
+ for_tuples!( #(
+ match Tuple::authenticate_tx(ctx, tx)? {
+ AuthDecision::Stop => return Ok(AuthDecision::Stop),
+ AuthDecision::Continue => {},
+ }
+ )* );
+
+ Ok(AuthDecision::Continue)
+ }
+
+ fn before_handle_call<C: Context>(ctx: &C, call: &Call) -> Result<(), modules::core::Error> {
+ for_tuples!( #( Tuple::before_handle_call(ctx, call)?; )* );
+ Ok(())
+ }
+
+ fn before_authorized_call_dispatch<C: Context>(
+ ctx: &C,
+ call: &Call,
+ ) -> Result<(), modules::core::Error> {
+ for_tuples!( #( Tuple::before_authorized_call_dispatch(ctx, call)?; )* );
+ Ok(())
+ }
+
+ fn after_handle_call<C: Context>(
+ ctx: &C,
+ mut result: CallResult,
+ ) -> Result<CallResult, modules::core::Error> {
+ for_tuples!( #(
+ result = Tuple::after_handle_call(ctx, result)?;
+ )* );
+ Ok(result)
+ }
+
+ fn after_dispatch_tx<C: Context>(ctx: &C, tx_auth_info: &AuthInfo, result: &CallResult) {
+ for_tuples!( #( Tuple::after_dispatch_tx(ctx, tx_auth_info, result); )* );
+ }
+}
+
+/// Fee proxy handler.
+pub trait FeeProxyHandler {
+ /// Resolve the proxy payer for the given transaction. If no payer could be resolved, `None`
+ /// should be returned.
+ fn resolve_payer<C: Context>(
+ ctx: &C,
+ tx: &Transaction,
+ ) -> Result<Option<Address>, modules::core::Error>;
+}
+
+#[impl_for_tuples(30)]
+impl FeeProxyHandler for Tuple {
+ fn resolve_payer<C: Context>(
+ ctx: &C,
+ tx: &Transaction,
+ ) -> Result<Option<Address>, modules::core::Error> {
+ for_tuples!( #(
+ if let Some(payer) = Tuple::resolve_payer(ctx, tx)? {
+ return Ok(Some(payer));
+ }
+ )* );
+
+ Ok(None)
+ }
+}
+
+/// Migration handler.
+pub trait MigrationHandler {
+ /// Genesis state type.
+ ///
+ /// If this state is expensive to compute and not often updated, prefer
+ /// to make the genesis type something like `once_cell::unsync::Lazy<T>`.
+ type Genesis;
+
+ /// Initialize state from genesis or perform a migration.
+ ///
+ /// Should return true in case metadata has been changed.
+ fn init_or_migrate<C: Context>(
+ _ctx: &C,
+ _meta: &mut modules::core::types::Metadata,
+ _genesis: Self::Genesis,
+ ) -> bool {
+ // Default implementation doesn't perform any migrations.
+ false
+ }
+}
+
+#[allow(clippy::type_complexity)]
+#[impl_for_tuples(30)]
+impl MigrationHandler for Tuple {
+ for_tuples!( type Genesis = ( #( Tuple::Genesis ),* ); );
+
+ fn init_or_migrate<C: Context>(
+ ctx: &C,
+ meta: &mut modules::core::types::Metadata,
+ genesis: Self::Genesis,
+ ) -> bool {
+ [for_tuples!( #( Tuple::init_or_migrate(ctx, meta, genesis.Tuple) ),* )]
+ .iter()
+ .any(|x| *x)
+ }
+}
+
+/// Block handler.
+pub trait BlockHandler {
+ /// Perform any common actions at the start of the block (before any transactions have been
+ /// executed).
+ fn begin_block<C: Context>(_ctx: &C) {
+ // Default implementation doesn't do anything.
+ }
+
+ /// Perform any common actions at the end of the block (after all transactions have been
+ /// executed).
+ fn end_block<C: Context>(_ctx: &C) {
+ // Default implementation doesn't do anything.
+ }
+}
+
+#[impl_for_tuples(30)]
+impl BlockHandler for Tuple {
+ fn begin_block<C: Context>(ctx: &C) {
+ for_tuples!( #( Tuple::begin_block(ctx); )* );
+ }
+
+ fn end_block<C: Context>(ctx: &C) {
+ for_tuples!( #( Tuple::end_block(ctx); )* );
+ }
+}
+
+/// Invariant handler.
+pub trait InvariantHandler {
+ /// Check invariants.
+ fn check_invariants<C: Context>(_ctx: &C) -> Result<(), modules::core::Error> {
+ // Default implementation doesn't do anything.
+ Ok(())
+ }
+}
+
+#[impl_for_tuples(30)]
+impl InvariantHandler for Tuple {
+ /// Check the invariants in all modules in the tuple.
+ fn check_invariants<C: Context>(ctx: &C) -> Result<(), modules::core::Error> {
+ for_tuples!( #( Tuple::check_invariants(ctx)?; )* );
+ Ok(())
+ }
+}
+
+/// Info handler.
+pub trait ModuleInfoHandler {
+ /// Reports info about the module (or modules, if `Self` is a tuple).
+ fn module_info<C: Context>(_ctx: &C) -> BTreeMap<String, ModuleInfo>;
+}
+
+impl<M: Module + MethodHandler> ModuleInfoHandler for M {
+ fn module_info<C: Context>(_ctx: &C) -> BTreeMap<String, ModuleInfo> {
+ let mut info = BTreeMap::new();
+ info.insert(
+ Self::NAME.to_string(),
+ ModuleInfo {
+ version: Self::VERSION,
+ params: Self::params().into_cbor_value(),
+ methods: Self::supported_methods(),
+ },
+ );
+ info
+ }
+}
+
+#[impl_for_tuples(30)]
+impl ModuleInfoHandler for Tuple {
+ #[allow(clippy::let_and_return)]
+ fn module_info<C: Context>(ctx: &C) -> BTreeMap<String, ModuleInfo> {
+ let mut merged = BTreeMap::new();
+ for_tuples!( #(
+ merged.extend(Tuple::module_info(ctx));
+ )* );
+ merged
+ }
+}
+
+/// A runtime module.
+pub trait Module {
+ /// Module name.
+ const NAME: &'static str;
+
+ /// Module version.
+ const VERSION: u32 = 1;
+
+ /// Module error type.
+ type Error: error::Error + 'static;
+
+ /// Module event type.
+ type Event: event::Event + 'static;
+
+ /// Module parameters.
+ type Parameters: Parameters + 'static;
+
+ /// Return the module's parameters.
+ fn params() -> Self::Parameters {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &Self::NAME);
+ let store = storage::TypedStore::new(store);
+ store.get(Self::Parameters::STORE_KEY).unwrap_or_default()
+ })
+ }
+
+ /// Set the module's parameters.
+ fn set_params(params: Self::Parameters) {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &Self::NAME);
+ let mut store = storage::TypedStore::new(store);
+ store.insert(Self::Parameters::STORE_KEY, params);
+ });
+ }
+}
+
+/// Parameters for a runtime module.
+pub trait Parameters: Debug + Default + cbor::Encode + cbor::Decode {
+ type Error;
+
+ /// Store key used for storing parameters.
+ const STORE_KEY: &'static [u8] = &[0x00];
+
+ /// Perform basic parameter validation.
+ fn validate_basic(&self) -> Result<(), Self::Error> {
+ // No validation by default.
+ Ok(())
+ }
+}
+
+impl Parameters for () {
+ type Error = std::convert::Infallible;
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+ use crate::testing::mock;
+
+ /// An authentication handler that always continues.
+ struct TestAuthContinue;
+ /// An authentication handler that always stops.
+ struct TestAuthStop;
+ /// An authentication handler that always fails.
+ struct TestAuthFail;
+
+ impl super::TransactionHandler for TestAuthContinue {
+ fn authenticate_tx<C: Context>(
+ _ctx: &C,
+ _tx: &Transaction,
+ ) -> Result<AuthDecision, modules::core::Error> {
+ Ok(AuthDecision::Continue)
+ }
+ }
+
+ impl super::TransactionHandler for TestAuthStop {
+ fn authenticate_tx<C: Context>(
+ _ctx: &C,
+ _tx: &Transaction,
+ ) -> Result<AuthDecision, modules::core::Error> {
+ Ok(AuthDecision::Stop)
+ }
+ }
+
+ impl super::TransactionHandler for TestAuthFail {
+ fn authenticate_tx<C: Context>(
+ _ctx: &C,
+ _tx: &Transaction,
+ ) -> Result<AuthDecision, modules::core::Error> {
+ Err(modules::core::Error::NotAuthenticated)
+ }
+ }
+
+ #[test]
+ fn test_authenticate_tx() {
+ let mut mock = mock::Mock::default();
+ let ctx = mock.create_ctx();
+ let tx = mock::transaction();
+
+ // Make sure mock authentication handlers behave as expected.
+ let result = TestAuthContinue::authenticate_tx(&ctx, &tx).unwrap();
+ assert!(matches!(result, AuthDecision::Continue));
+ let result = TestAuthStop::authenticate_tx(&ctx, &tx).unwrap();
+ assert!(matches!(result, AuthDecision::Stop));
+ let _ = TestAuthFail::authenticate_tx(&ctx, &tx).unwrap_err();
+
+ // Make sure that composed variants behave as expected.
+ type Composed1 = (TestAuthContinue, TestAuthContinue, TestAuthContinue);
+ let result = Composed1::authenticate_tx(&ctx, &tx).unwrap();
+ assert!(matches!(result, AuthDecision::Continue));
+
+ type Composed2 = (TestAuthContinue, TestAuthStop, TestAuthContinue);
+ let result = Composed2::authenticate_tx(&ctx, &tx).unwrap();
+ assert!(matches!(result, AuthDecision::Stop));
+
+ type Composed3 = (TestAuthContinue, TestAuthStop, TestAuthFail);
+ let result = Composed3::authenticate_tx(&ctx, &tx).unwrap();
+ assert!(matches!(result, AuthDecision::Stop));
+
+ type Composed4 = (TestAuthFail, TestAuthStop, TestAuthContinue);
+ let _ = Composed4::authenticate_tx(&ctx, &tx).unwrap_err();
+
+ type Composed5 = (TestAuthContinue, TestAuthContinue, TestAuthFail);
+ let _ = Composed5::authenticate_tx(&ctx, &tx).unwrap_err();
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +
//! Method access control module.
+use once_cell::unsync::Lazy;
+use thiserror::Error;
+
+use crate::{
+ context::Context,
+ module::{self, Module as _},
+ modules, sdk_derive,
+ state::CurrentState,
+ types::transaction,
+};
+
+#[cfg(test)]
+mod test;
+pub mod types;
+
+/// Unique module name.
+const MODULE_NAME: &str = "access";
+
+/// Errors emitted by the access module.
+#[derive(Error, Debug, oasis_runtime_sdk_macros::Error)]
+pub enum Error {
+ #[error("caller is not authorized to call method")]
+ #[sdk_error(code = 1)]
+ NotAuthorized,
+}
+
+/// Module configuration.
+#[allow(clippy::declare_interior_mutable_const)]
+pub trait Config: 'static {
+ /// To filter methods by caller address, add them to this mapping.
+ ///
+ /// If the mapping is empty, no method is filtered.
+ const METHOD_AUTHORIZATIONS: Lazy<types::Authorization> = Lazy::new(types::Authorization::new);
+}
+
+/// The method access control module.
+pub struct Module<Cfg: Config> {
+ _cfg: std::marker::PhantomData<Cfg>,
+}
+
+#[sdk_derive(Module)]
+impl<Cfg: Config> Module<Cfg> {
+ const NAME: &'static str = MODULE_NAME;
+ const VERSION: u32 = 1;
+ type Error = Error;
+ type Event = ();
+ type Parameters = ();
+ type Genesis = ();
+}
+
+impl<Cfg: Config> module::TransactionHandler for Module<Cfg> {
+ fn before_authorized_call_dispatch<C: Context>(
+ _ctx: &C,
+ call: &transaction::Call,
+ ) -> Result<(), modules::core::Error> {
+ let tx_caller_address = CurrentState::with_env(|env| env.tx_caller_address());
+ #[allow(clippy::borrow_interior_mutable_const)]
+ if Cfg::METHOD_AUTHORIZATIONS.is_authorized(&call.method, &tx_caller_address) {
+ Ok(())
+ } else {
+ Err(modules::core::Error::InvalidArgument(
+ Error::NotAuthorized.into(),
+ ))
+ }
+ }
+}
+
+impl<Cfg: Config> module::BlockHandler for Module<Cfg> {}
+
+impl<Cfg: Config> module::InvariantHandler for Module<Cfg> {}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +
//! Method access control module types.
+use std::collections::{BTreeMap, BTreeSet};
+
+use crate::types::address::Address;
+
+/// A set of addresses that can be used to define access control for a particular method.
+pub type Addresses = BTreeSet<Address>;
+
+/// A specific kind of method authorization.
+pub enum MethodAuthorization {
+ /// Only allow method calls from these addresses;
+ /// for other callers, the method call will fail.
+ AllowFrom(Addresses),
+}
+
+impl MethodAuthorization {
+ /// Helper for creating a method authorization type that
+ /// only allows callers with the given addresses.
+ pub fn allow_from<I: IntoIterator<Item = Address>>(it: I) -> Self {
+ Self::AllowFrom(BTreeSet::from_iter(it))
+ }
+
+ pub(super) fn is_authorized(&self, address: &Address) -> bool {
+ match self {
+ Self::AllowFrom(addrs) => addrs.contains(address),
+ }
+ }
+}
+
+/// A set of methods that are subject to access control.
+pub type Methods = BTreeMap<String, MethodAuthorization>;
+
+/// A specific kind of access control.
+pub enum Authorization {
+ /// Control a statically configured set of methods, each with a
+ /// statically configured set of addresses that are allowed to call it.
+ FilterOnly(Methods),
+}
+
+impl Authorization {
+ /// Return a new access control configuration.
+ pub fn new() -> Self {
+ Self::FilterOnly(BTreeMap::new())
+ }
+
+ /// Helper for creating a static access control configuration.
+ pub fn with_filtered_methods<S, I>(it: I) -> Self
+ where
+ S: AsRef<str>,
+ I: IntoIterator<Item = (S, MethodAuthorization)>,
+ {
+ Self::FilterOnly(BTreeMap::from_iter(
+ it.into_iter()
+ .map(|(name, authz)| (name.as_ref().to_string(), authz)),
+ ))
+ }
+
+ pub(super) fn is_authorized(&self, method: &str, address: &Address) -> bool {
+ match self {
+ Self::FilterOnly(meths) => meths
+ .get(method)
+ .map(|authz| authz.is_authorized(address))
+ .unwrap_or(true),
+ }
+ }
+}
+
+impl Default for Authorization {
+ fn default() -> Self {
+ Self::FilterOnly(BTreeMap::default())
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +
//! Fee manager.
+use std::collections::BTreeMap;
+
+use crate::types::{address::Address, token};
+
+/// The per-block fee manager that records what fees have been charged by the current transaction,
+/// how much should be refunded and what were all of the fee payments in the current block.
+///
+/// Note that the fee manager does not perform any state modifications by itself.
+#[derive(Clone, Default, Debug)]
+pub struct FeeManager {
+ /// Fees charged for the current transaction.
+ tx_fee: Option<TransactionFee>,
+ /// Fees charged in the current block.
+ block_fees: BTreeMap<token::Denomination, u128>,
+}
+
+/// Information about fees charged for the current transaction.
+#[derive(Clone, Default, Debug)]
+pub struct TransactionFee {
+ /// Transaction fee payer address.
+ payer: Address,
+ /// Denomination of the transaction fee.
+ denomination: token::Denomination,
+ /// Amount charged before transaction execution.
+ charged: u128,
+ /// Amount that should be refunded after transaction execution.
+ refunded: u128,
+}
+
+impl TransactionFee {
+ /// Denomination of the transaction fee.
+ pub fn denomination(&self) -> token::Denomination {
+ self.denomination.clone()
+ }
+
+ /// Transaction fee amount.
+ pub fn amount(&self) -> u128 {
+ self.charged.saturating_sub(self.refunded)
+ }
+
+ /// Transaction fee payer address.
+ pub fn payer(&self) -> Address {
+ self.payer
+ }
+}
+
+impl FeeManager {
+ /// Create a new per-block fee manager.
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ /// Fees charged for the current transaction.
+ pub fn tx_fee(&self) -> Option<&TransactionFee> {
+ self.tx_fee.as_ref()
+ }
+
+ /// Record that a transaction fee has been charged.
+ ///
+ /// This method should only be called after the charged fee has been subtracted from the payer's
+ /// account (e.g. reflected in state).
+ pub fn record_fee(&mut self, payer: Address, amount: &token::BaseUnits) {
+ let tx_fee = self.tx_fee.get_or_insert_with(|| TransactionFee {
+ payer,
+ denomination: amount.denomination().clone(),
+ ..Default::default()
+ });
+
+ assert!(payer == tx_fee.payer, "transaction fee payer cannot change");
+ assert!(
+ amount.denomination() == &tx_fee.denomination,
+ "transaction fee denomination cannot change"
+ );
+
+ tx_fee.charged = tx_fee
+ .charged
+ .checked_add(amount.amount())
+ .expect("should never overflow");
+ }
+
+ /// Record that a portion of the previously charged transaction fee should be refunded.
+ pub fn record_refund(&mut self, amount: u128) {
+ if amount == 0 || self.tx_fee.is_none() {
+ return;
+ }
+
+ let tx_fee = self.tx_fee.as_mut().unwrap();
+ tx_fee.refunded = std::cmp::min(tx_fee.refunded.saturating_add(amount), tx_fee.charged);
+ }
+
+ /// Commit the currently open transaction fee by moving the final recorded amount into the fees
+ /// charged for the current block.
+ ///
+ /// Note that this does not perform any state modifications and the caller is assumed to apply
+ /// any updates after calling this method.
+ #[must_use = "fee updates should be applied after calling commit"]
+ pub fn commit_tx(&mut self) -> FeeUpdates {
+ let tx_fee = self.tx_fee.take().unwrap_or_default();
+ if tx_fee.amount() > 0 {
+ let block_fees = self
+ .block_fees
+ .entry(tx_fee.denomination.clone())
+ .or_default();
+
+ // Add to per-block accumulator.
+ *block_fees = block_fees
+ .checked_add(tx_fee.amount())
+ .expect("should never overflow");
+ }
+
+ FeeUpdates {
+ payer: tx_fee.payer,
+ refund: token::BaseUnits::new(tx_fee.refunded, tx_fee.denomination),
+ }
+ }
+
+ /// Commit the fees accumulated for the current block, returning the resulting map.
+ ///
+ /// Note that this does not perform any state modifications and the caller is assumed to apply
+ /// any updates after calling this method.
+ #[must_use = "accumulated fees should be applied after calling commit"]
+ pub fn commit_block(self) -> BTreeMap<token::Denomination, u128> {
+ self.block_fees
+ }
+}
+
+/// Fee updates to apply to state after `commit_tx`.
+///
+/// This assumes that the initial fee charge has already happened, see the description of
+/// `FeeManager::record_fee` for details.
+pub struct FeeUpdates {
+ /// Fee payer.
+ pub payer: Address,
+ /// Amount that should be refunded to fee payer.
+ pub refund: token::BaseUnits,
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ use crate::{
+ testing::keys,
+ types::token::{self, Denomination},
+ };
+
+ #[test]
+ fn test_basic_refund() {
+ let mut mgr = FeeManager::new();
+
+ assert!(mgr.tx_fee().is_none());
+
+ // First transaction with refund.
+ let fee = token::BaseUnits::new(1_000_000, Denomination::NATIVE);
+ mgr.record_fee(keys::alice::address(), &fee);
+
+ let tx_fee = mgr.tx_fee().expect("tx_fee should be set");
+ assert_eq!(tx_fee.payer(), keys::alice::address());
+ assert_eq!(&tx_fee.denomination(), fee.denomination());
+ assert_eq!(tx_fee.amount(), fee.amount());
+
+ mgr.record_refund(400_000);
+
+ let tx_fee = mgr.tx_fee().expect("tx_fee should be set");
+ assert_eq!(tx_fee.payer(), keys::alice::address());
+ assert_eq!(&tx_fee.denomination(), fee.denomination());
+ assert_eq!(tx_fee.amount(), 600_000, "should take refund into account");
+
+ let fee_updates = mgr.commit_tx();
+ assert_eq!(fee_updates.payer, keys::alice::address());
+ assert_eq!(
+ fee_updates.refund,
+ token::BaseUnits::new(400_000, Denomination::NATIVE)
+ );
+ assert!(mgr.tx_fee().is_none());
+
+ // Some more transactions.
+ mgr.record_fee(
+ keys::bob::address(),
+ &token::BaseUnits::new(50_000, Denomination::NATIVE),
+ );
+ let fee_updates = mgr.commit_tx();
+ assert_eq!(fee_updates.payer, keys::bob::address());
+ assert_eq!(
+ fee_updates.refund,
+ token::BaseUnits::new(0, Denomination::NATIVE)
+ );
+
+ mgr.record_fee(
+ keys::dave::address(),
+ &token::BaseUnits::new(25_000, "TEST".parse().unwrap()),
+ );
+ mgr.record_fee(
+ keys::dave::address(),
+ &token::BaseUnits::new(5_000, "TEST".parse().unwrap()),
+ );
+ let fee_updates = mgr.commit_tx();
+ assert_eq!(fee_updates.payer, keys::dave::address());
+ assert_eq!(
+ fee_updates.refund,
+ token::BaseUnits::new(0, "TEST".parse().unwrap())
+ );
+
+ let block_fees = mgr.commit_block();
+ assert_eq!(block_fees.len(), 2);
+ assert_eq!(block_fees[&Denomination::NATIVE], 650_000);
+ assert_eq!(block_fees[&"TEST".parse().unwrap()], 30_000);
+ }
+
+ #[test]
+ fn test_refund_without_charge() {
+ let mut mgr = FeeManager::new();
+
+ mgr.record_refund(1_000);
+ assert!(
+ mgr.tx_fee().is_none(),
+ "refund should not be recorded if no charge"
+ );
+
+ let fee_updates = mgr.commit_tx();
+ assert_eq!(fee_updates.payer, Default::default());
+ assert_eq!(
+ fee_updates.refund,
+ token::BaseUnits::new(0, Default::default())
+ );
+
+ let block_fees = mgr.commit_block();
+ assert!(block_fees.is_empty(), "there should be no recorded fees");
+ }
+
+ #[test]
+ #[should_panic(expected = "transaction fee payer cannot change")]
+ fn test_fail_payer_change() {
+ let mut mgr = FeeManager::new();
+
+ let fee = token::BaseUnits::new(1_000_000, Denomination::NATIVE);
+ mgr.record_fee(keys::alice::address(), &fee);
+ mgr.record_fee(keys::bob::address(), &fee); // Should panic.
+ }
+
+ #[test]
+ #[should_panic(expected = "transaction fee denomination cannot change")]
+ fn test_fail_denomination_change() {
+ let mut mgr = FeeManager::new();
+
+ let fee = token::BaseUnits::new(1_000_000, Denomination::NATIVE);
+ mgr.record_fee(keys::alice::address(), &fee);
+
+ let fee = token::BaseUnits::new(1_000_000, "TEST".parse().unwrap());
+ mgr.record_fee(keys::alice::address(), &fee); // Should panic.
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +765 +766 +767 +768 +769 +770 +771 +772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805 +806 +807 +808 +809 +810 +811 +812 +813 +814 +815 +816 +817 +818 +819 +820 +821 +822 +823 +824 +825 +826 +827 +828 +829 +830 +831 +832 +833 +834 +835 +836 +837 +838 +839 +840 +841 +842 +843 +844 +845 +846 +847 +848 +849 +850 +851 +852 +853 +854 +855 +856 +857 +858 +859 +860 +861 +862 +863 +864 +865 +866 +867 +868 +869 +870 +871 +872 +873 +874 +875 +876 +877 +878 +879 +880 +881 +882 +883 +884 +885 +886 +887 +888 +889 +890 +891 +892 +893 +894 +895 +896 +897 +898 +899 +900 +901 +902 +903 +904 +905 +906 +907 +908 +909 +910 +911 +912 +913 +914 +915 +916 +917 +918 +919 +920 +921 +922 +923 +924 +925 +926 +927 +928 +929 +930 +931 +932 +933 +934 +935 +936 +937 +938 +939 +940 +941 +942 +943 +944 +945 +946 +947 +948 +949 +950 +951 +952 +953 +954 +955 +956 +957 +958 +959 +960 +961 +962 +963 +964 +965 +966 +967 +968 +969 +970 +971 +972 +973 +974 +975 +976 +977 +978 +979 +980 +981 +982 +983 +984 +985 +986 +987 +988 +989 +990 +991 +992 +993 +994 +995 +996 +997 +998 +999 +1000 +1001 +1002 +1003 +1004 +1005 +1006 +1007 +1008 +1009 +1010 +1011 +1012 +1013 +1014 +1015 +1016 +1017 +1018 +1019 +1020 +1021 +1022 +1023 +1024 +1025 +1026 +1027 +1028 +1029 +1030 +1031 +1032 +1033 +1034 +1035 +1036 +1037 +1038 +1039 +1040 +1041 +1042 +1043 +1044 +1045 +1046 +1047 +1048 +1049 +1050 +1051 +1052 +1053 +1054 +1055 +1056 +1057 +1058 +1059 +1060 +1061 +1062 +1063 +1064 +1065 +1066 +1067 +1068 +1069 +1070 +1071 +1072 +1073 +1074 +1075 +1076 +1077 +1078 +1079 +1080 +1081 +1082 +1083 +1084 +1085 +1086 +1087 +1088 +1089 +1090 +1091 +1092 +1093 +1094 +1095 +1096 +1097 +1098 +1099 +1100 +1101 +1102 +1103 +1104 +1105 +1106 +1107 +1108 +1109 +1110 +1111 +1112 +1113 +1114 +1115 +1116 +1117 +1118 +1119 +1120 +1121 +1122 +1123 +1124 +1125 +1126 +1127 +1128 +1129 +1130 +1131 +1132 +1133 +1134 +1135 +1136 +1137 +1138 +1139 +1140 +1141 +1142 +1143 +1144 +1145 +1146 +1147 +1148 +1149 +1150 +1151 +
//! Accounts module.
+use std::{
+ cmp::Ordering,
+ collections::{BTreeMap, BTreeSet},
+ convert::TryInto,
+};
+
+use num_traits::Zero;
+use once_cell::sync::Lazy;
+use thiserror::Error;
+
+use crate::{
+ context::Context,
+ core::common::quantity::Quantity,
+ handler, migration,
+ module::{self, FeeProxyHandler, Module as _, Parameters as _},
+ modules,
+ modules::core::{Error as CoreError, API as _},
+ runtime::Runtime,
+ sdk_derive,
+ sender::SenderMeta,
+ state::CurrentState,
+ storage,
+ storage::Prefix,
+ types::{
+ address::{Address, SignatureAddressSpec},
+ token,
+ transaction::{AuthInfo, Transaction},
+ },
+};
+
+pub mod fee;
+#[cfg(test)]
+pub(crate) mod test;
+pub mod types;
+
+/// Unique module name.
+const MODULE_NAME: &str = "accounts";
+
+/// Maximum delta that the transaction nonce can be in the future from the current nonce to still
+/// be accepted during transaction checks.
+const MAX_CHECK_NONCE_FUTURE_DELTA: u64 = 0; // Increase once supported in Oasis Core.
+
+/// Errors emitted by the accounts module.
+#[derive(Error, Debug, oasis_runtime_sdk_macros::Error)]
+pub enum Error {
+ #[error("invalid argument")]
+ #[sdk_error(code = 1)]
+ InvalidArgument,
+
+ #[error("insufficient balance")]
+ #[sdk_error(code = 2)]
+ InsufficientBalance,
+
+ #[error("forbidden by policy")]
+ #[sdk_error(code = 3)]
+ Forbidden,
+
+ #[error("not found")]
+ #[sdk_error(code = 4)]
+ NotFound,
+
+ #[error("core: {0}")]
+ #[sdk_error(transparent)]
+ Core(#[from] modules::core::Error),
+}
+
+/// Events emitted by the accounts module.
+#[derive(Debug, cbor::Encode, oasis_runtime_sdk_macros::Event)]
+#[cbor(untagged)]
+pub enum Event {
+ #[sdk_event(code = 1)]
+ Transfer {
+ from: Address,
+ to: Address,
+ amount: token::BaseUnits,
+ },
+
+ #[sdk_event(code = 2)]
+ Burn {
+ owner: Address,
+ amount: token::BaseUnits,
+ },
+
+ #[sdk_event(code = 3)]
+ Mint {
+ owner: Address,
+ amount: token::BaseUnits,
+ },
+}
+
+/// Gas costs.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct GasCosts {
+ pub tx_transfer: u64,
+}
+
+/// Parameters for the accounts module.
+#[derive(Clone, Default, Debug, cbor::Encode, cbor::Decode)]
+pub struct Parameters {
+ pub transfers_disabled: bool,
+ pub gas_costs: GasCosts,
+
+ #[cbor(optional)]
+ pub debug_disable_nonce_check: bool,
+
+ #[cbor(optional)]
+ pub denomination_infos: BTreeMap<token::Denomination, types::DenominationInfo>,
+}
+
+/// Errors emitted during rewards parameter validation.
+#[derive(Error, Debug)]
+pub enum ParameterValidationError {
+ #[error("debug option used: {0}")]
+ DebugOptionUsed(String),
+}
+
+impl module::Parameters for Parameters {
+ type Error = ParameterValidationError;
+
+ #[cfg(not(feature = "unsafe-allow-debug"))]
+ fn validate_basic(&self) -> Result<(), Self::Error> {
+ if self.debug_disable_nonce_check {
+ return Err(ParameterValidationError::DebugOptionUsed(
+ "debug_disable_nonce_check".to_string(),
+ ));
+ }
+
+ Ok(())
+ }
+}
+
+/// Genesis state for the accounts module.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Genesis {
+ pub parameters: Parameters,
+ pub accounts: BTreeMap<Address, types::Account>,
+ pub balances: BTreeMap<Address, BTreeMap<token::Denomination, u128>>,
+ pub total_supplies: BTreeMap<token::Denomination, u128>,
+}
+
+/// Interface that can be called from other modules.
+pub trait API {
+ /// Transfer an amount from one account to the other.
+ fn transfer(from: Address, to: Address, amount: &token::BaseUnits) -> Result<(), Error>;
+
+ /// Transfer an amount from one account to the other without emitting an event.
+ fn transfer_silent(from: Address, to: Address, amount: &token::BaseUnits) -> Result<(), Error>;
+
+ /// Mint new tokens, increasing the total supply.
+ fn mint(to: Address, amount: &token::BaseUnits) -> Result<(), Error>;
+
+ /// Burn existing tokens, decreasing the total supply.
+ fn burn(from: Address, amount: &token::BaseUnits) -> Result<(), Error>;
+
+ /// Sets an account's nonce.
+ fn set_nonce(address: Address, nonce: u64);
+
+ /// Fetch an account's current nonce.
+ fn get_nonce(address: Address) -> Result<u64, Error>;
+
+ /// Increments an account's nonce.
+ fn inc_nonce(address: Address);
+
+ /// Sets an account's balance of the given denomination.
+ ///
+ /// # Warning
+ ///
+ /// This method is dangerous as it can result in invariant violations.
+ fn set_balance(address: Address, amount: &token::BaseUnits);
+
+ /// Fetch an account's balance of the given denomination.
+ fn get_balance(address: Address, denomination: token::Denomination) -> Result<u128, Error>;
+
+ /// Ensures that the given account has at least the specified balance.
+ fn ensure_balance(address: Address, amount: &token::BaseUnits) -> Result<(), Error> {
+ let balance = Self::get_balance(address, amount.denomination().clone())?;
+ if balance < amount.amount() {
+ Err(Error::InsufficientBalance)
+ } else {
+ Ok(())
+ }
+ }
+
+ /// Fetch an account's current balances.
+ fn get_balances(address: Address) -> Result<types::AccountBalances, Error>;
+
+ /// Fetch addresses.
+ fn get_addresses(denomination: token::Denomination) -> Result<Vec<Address>, Error>;
+
+ /// Fetch total supplies.
+ fn get_total_supplies() -> Result<BTreeMap<token::Denomination, u128>, Error>;
+
+ /// Sets the total supply for the given denomination.
+ ///
+ /// # Warning
+ ///
+ /// This method is dangerous as it can result in invariant violations.
+ fn set_total_supply(amount: &token::BaseUnits);
+
+ /// Fetch information about a denomination.
+ fn get_denomination_info(
+ denomination: &token::Denomination,
+ ) -> Result<types::DenominationInfo, Error>;
+
+ /// Moves the amount into the per-transaction fee accumulator.
+ fn charge_tx_fee(from: Address, amount: &token::BaseUnits) -> Result<(), modules::core::Error>;
+
+ /// Indicates that the unused portion of the transaction fee should be refunded after the
+ /// transaction completes (even in case it fails).
+ fn set_refund_unused_tx_fee(refund: bool);
+
+ /// Take the flag indicating that the unused portion of the transaction fee should be refunded
+ /// after the transaction completes is set.
+ ///
+ /// After calling this method the flag is reset to `false`.
+ fn take_refund_unused_tx_fee() -> bool;
+
+ /// Check transaction signer account nonces.
+ /// Return payer address.
+ fn check_signer_nonces<C: Context>(
+ ctx: &C,
+ tx_auth_info: &AuthInfo,
+ ) -> Result<Address, modules::core::Error>;
+
+ /// Update transaction signer account nonces.
+ fn update_signer_nonces<C: Context>(
+ ctx: &C,
+ tx_auth_info: &AuthInfo,
+ ) -> Result<(), modules::core::Error>;
+}
+
+/// State schema constants.
+pub mod state {
+ /// Map of account addresses to account metadata.
+ pub const ACCOUNTS: &[u8] = &[0x01];
+ /// Map of account addresses to map of denominations to balances.
+ pub const BALANCES: &[u8] = &[0x02];
+ /// Map of total supplies (per denomination).
+ pub const TOTAL_SUPPLY: &[u8] = &[0x03];
+}
+
+pub struct Module;
+
+/// Module's address that has the common pool.
+///
+/// oasis1qz78phkdan64g040cvqvqpwkplfqf6tj6uwcsh30
+pub static ADDRESS_COMMON_POOL: Lazy<Address> =
+ Lazy::new(|| Address::from_module(MODULE_NAME, "common-pool"));
+/// Module's address that has the fee accumulator.
+///
+/// oasis1qp3r8hgsnphajmfzfuaa8fhjag7e0yt35cjxq0u4
+pub static ADDRESS_FEE_ACCUMULATOR: Lazy<Address> =
+ Lazy::new(|| Address::from_module(MODULE_NAME, "fee-accumulator"));
+
+/// This is needed to properly iterate over the BALANCES map.
+#[derive(Clone, PartialEq, PartialOrd, Eq, Ord)]
+struct AddressWithDenomination(Address, token::Denomination);
+
+#[derive(Error, Debug)]
+enum AWDError {
+ #[error("malformed address")]
+ MalformedAddress,
+
+ #[error("malformed denomination")]
+ MalformedDenomination,
+}
+
+impl std::convert::TryFrom<&[u8]> for AddressWithDenomination {
+ type Error = AWDError;
+
+ fn try_from(bytes: &[u8]) -> Result<Self, Self::Error> {
+ let address =
+ Address::try_from(&bytes[..Address::SIZE]).map_err(|_| AWDError::MalformedAddress)?;
+ let denomination = token::Denomination::try_from(&bytes[Address::SIZE..])
+ .map_err(|_| AWDError::MalformedDenomination)?;
+ Ok(AddressWithDenomination(address, denomination))
+ }
+}
+
+impl Module {
+ /// Add given amount of tokens to the specified account's balance.
+ fn add_amount(addr: Address, amount: &token::BaseUnits) -> Result<(), Error> {
+ if amount.amount() == 0 {
+ return Ok(());
+ }
+
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let balances = storage::PrefixStore::new(store, &state::BALANCES);
+ let mut account = storage::TypedStore::new(storage::PrefixStore::new(balances, &addr));
+ let mut value: u128 = account.get(amount.denomination()).unwrap_or_default();
+
+ value = value
+ .checked_add(amount.amount())
+ .ok_or(Error::InvalidArgument)?;
+ account.insert(amount.denomination(), value);
+ Ok(())
+ })
+ }
+
+ /// Subtract given amount of tokens from the specified account's balance.
+ fn sub_amount(addr: Address, amount: &token::BaseUnits) -> Result<(), Error> {
+ if amount.amount() == 0 {
+ return Ok(());
+ }
+
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let balances = storage::PrefixStore::new(store, &state::BALANCES);
+ let mut account = storage::TypedStore::new(storage::PrefixStore::new(balances, &addr));
+ let mut value: u128 = account.get(amount.denomination()).unwrap_or_default();
+
+ value = value
+ .checked_sub(amount.amount())
+ .ok_or(Error::InsufficientBalance)?;
+ account.insert(amount.denomination(), value);
+ Ok(())
+ })
+ }
+
+ /// Increment the total supply for the given amount.
+ fn inc_total_supply(amount: &token::BaseUnits) -> Result<(), Error> {
+ if amount.amount() == 0 {
+ return Ok(());
+ }
+
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut total_supplies =
+ storage::TypedStore::new(storage::PrefixStore::new(store, &state::TOTAL_SUPPLY));
+ let mut total_supply: u128 = total_supplies
+ .get(amount.denomination())
+ .unwrap_or_default();
+
+ total_supply = total_supply
+ .checked_add(amount.amount())
+ .ok_or(Error::InvalidArgument)?;
+ total_supplies.insert(amount.denomination(), total_supply);
+ Ok(())
+ })
+ }
+
+ /// Decrement the total supply for the given amount.
+ fn dec_total_supply(amount: &token::BaseUnits) -> Result<(), Error> {
+ if amount.amount() == 0 {
+ return Ok(());
+ }
+
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut total_supplies =
+ storage::TypedStore::new(storage::PrefixStore::new(store, &state::TOTAL_SUPPLY));
+ let mut total_supply: u128 = total_supplies
+ .get(amount.denomination())
+ .unwrap_or_default();
+
+ total_supply = total_supply
+ .checked_sub(amount.amount())
+ .ok_or(Error::InsufficientBalance)?;
+ total_supplies.insert(amount.denomination(), total_supply);
+ Ok(())
+ })
+ }
+
+ /// Get all balances.
+ fn get_all_balances() -> Result<BTreeMap<Address, BTreeMap<token::Denomination, u128>>, Error> {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let balances =
+ storage::TypedStore::new(storage::PrefixStore::new(store, &state::BALANCES));
+
+ // Unfortunately, we can't just return balances.iter().collect() here,
+ // because the stored format doesn't match -- we need this workaround
+ // instead.
+
+ let balmap: BTreeMap<AddressWithDenomination, u128> = balances.iter().collect();
+
+ let mut b: BTreeMap<Address, BTreeMap<token::Denomination, u128>> = BTreeMap::new();
+
+ for (addrden, amt) in &balmap {
+ let addr = &addrden.0;
+ let den = &addrden.1;
+
+ // Fetch existing account's balances or insert blank ones.
+ let addr_bals = b.entry(*addr).or_default();
+
+ // Add to given denomination's balance or insert it if new.
+ addr_bals
+ .entry(den.clone())
+ .and_modify(|a| *a += amt)
+ .or_insert_with(|| *amt);
+ }
+
+ Ok(b)
+ })
+ }
+}
+
+/// Context key for the per-transaction unused fee refund decision.
+const CONTEXT_KEY_TX_FEE_REFUND_UNUSED: &str = "accounts.TxRefundUnusedFee";
+/// Context key for the per block fee manager.
+const CONTEXT_KEY_FEE_MANAGER: &str = "accounts.FeeManager";
+
+impl API for Module {
+ fn transfer(from: Address, to: Address, amount: &token::BaseUnits) -> Result<(), Error> {
+ if CurrentState::with_env(|env| env.is_check_only()) || amount.amount() == 0 {
+ return Ok(());
+ }
+
+ Self::transfer_silent(from, to, amount)?;
+
+ // Emit a transfer event.
+ CurrentState::with(|state| {
+ state.emit_event(Event::Transfer {
+ from,
+ to,
+ amount: amount.clone(),
+ })
+ });
+
+ Ok(())
+ }
+
+ fn transfer_silent(from: Address, to: Address, amount: &token::BaseUnits) -> Result<(), Error> {
+ // Subtract from source account.
+ Self::sub_amount(from, amount)?;
+ // Add to destination account.
+ Self::add_amount(to, amount)?;
+
+ Ok(())
+ }
+
+ fn mint(to: Address, amount: &token::BaseUnits) -> Result<(), Error> {
+ if CurrentState::with_env(|env| env.is_check_only()) || amount.amount() == 0 {
+ return Ok(());
+ }
+
+ // Add to destination account.
+ Self::add_amount(to, amount)?;
+
+ // Increase total supply.
+ Self::inc_total_supply(amount)?;
+
+ // Emit a mint event.
+ CurrentState::with(|state| {
+ state.emit_event(Event::Mint {
+ owner: to,
+ amount: amount.clone(),
+ });
+ });
+
+ Ok(())
+ }
+
+ fn burn(from: Address, amount: &token::BaseUnits) -> Result<(), Error> {
+ if CurrentState::with_env(|env| env.is_check_only()) || amount.amount() == 0 {
+ return Ok(());
+ }
+
+ // Remove from target account.
+ Self::sub_amount(from, amount)?;
+
+ // Decrease total supply.
+ Self::dec_total_supply(amount)
+ .expect("target account had enough balance so total supply should not underflow");
+
+ // Emit a burn event.
+ CurrentState::with(|state| {
+ state.emit_event(Event::Burn {
+ owner: from,
+ amount: amount.clone(),
+ });
+ });
+
+ Ok(())
+ }
+
+ fn set_nonce(address: Address, nonce: u64) {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut accounts =
+ storage::TypedStore::new(storage::PrefixStore::new(store, &state::ACCOUNTS));
+ let mut account: types::Account = accounts.get(address).unwrap_or_default();
+ account.nonce = nonce;
+ accounts.insert(address, account);
+ })
+ }
+
+ fn get_nonce(address: Address) -> Result<u64, Error> {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let accounts =
+ storage::TypedStore::new(storage::PrefixStore::new(store, &state::ACCOUNTS));
+ let account: types::Account = accounts.get(address).unwrap_or_default();
+ Ok(account.nonce)
+ })
+ }
+
+ fn inc_nonce(address: Address) {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut accounts =
+ storage::TypedStore::new(storage::PrefixStore::new(store, &state::ACCOUNTS));
+ let mut account: types::Account = accounts.get(address).unwrap_or_default();
+ account.nonce = account.nonce.saturating_add(1);
+ accounts.insert(address, account);
+ })
+ }
+
+ fn set_balance(address: Address, amount: &token::BaseUnits) {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let balances = storage::PrefixStore::new(store, &state::BALANCES);
+ let mut account =
+ storage::TypedStore::new(storage::PrefixStore::new(balances, &address));
+ account.insert(amount.denomination(), amount.amount());
+ });
+ }
+
+ fn get_balance(address: Address, denomination: token::Denomination) -> Result<u128, Error> {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let balances = storage::PrefixStore::new(store, &state::BALANCES);
+ let account = storage::TypedStore::new(storage::PrefixStore::new(balances, &address));
+
+ Ok(account.get(denomination).unwrap_or_default())
+ })
+ }
+
+ fn get_balances(address: Address) -> Result<types::AccountBalances, Error> {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let balances = storage::PrefixStore::new(store, &state::BALANCES);
+ let account = storage::TypedStore::new(storage::PrefixStore::new(balances, &address));
+
+ Ok(types::AccountBalances {
+ balances: account.iter().collect(),
+ })
+ })
+ }
+
+ fn get_addresses(denomination: token::Denomination) -> Result<Vec<Address>, Error> {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let balances: BTreeMap<AddressWithDenomination, Quantity> =
+ storage::TypedStore::new(storage::PrefixStore::new(store, &state::BALANCES))
+ .iter()
+ .collect();
+
+ Ok(balances
+ .into_keys()
+ .filter(|bal| bal.1 == denomination)
+ .map(|bal| bal.0)
+ .collect())
+ })
+ }
+
+ fn get_total_supplies() -> Result<BTreeMap<token::Denomination, u128>, Error> {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let ts =
+ storage::TypedStore::new(storage::PrefixStore::new(store, &state::TOTAL_SUPPLY));
+
+ Ok(ts.iter().collect())
+ })
+ }
+
+ fn set_total_supply(amount: &token::BaseUnits) {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut total_supplies =
+ storage::TypedStore::new(storage::PrefixStore::new(store, &state::TOTAL_SUPPLY));
+ total_supplies.insert(amount.denomination(), amount.amount());
+ });
+ }
+
+ fn get_denomination_info(
+ denomination: &token::Denomination,
+ ) -> Result<types::DenominationInfo, Error> {
+ Self::params()
+ .denomination_infos
+ .get(denomination)
+ .cloned()
+ .ok_or(Error::NotFound)
+ }
+
+ fn charge_tx_fee(from: Address, amount: &token::BaseUnits) -> Result<(), modules::core::Error> {
+ if CurrentState::with_env(|env| env.is_simulation()) {
+ return Ok(());
+ }
+
+ Self::sub_amount(from, amount).map_err(|_| modules::core::Error::InsufficientFeeBalance)?;
+
+ CurrentState::with(|state| {
+ state
+ .block_value::<fee::FeeManager>(CONTEXT_KEY_FEE_MANAGER)
+ .or_default()
+ .record_fee(from, amount);
+ });
+
+ Ok(())
+ }
+
+ fn set_refund_unused_tx_fee(refund: bool) {
+ CurrentState::with(|state| {
+ if state.env().is_simulation() {
+ return;
+ }
+
+ state
+ .block_value(CONTEXT_KEY_TX_FEE_REFUND_UNUSED)
+ .set(refund);
+ });
+ }
+
+ fn take_refund_unused_tx_fee() -> bool {
+ CurrentState::with(|state| {
+ if state.env().is_simulation() {
+ return false;
+ }
+
+ state
+ .block_value(CONTEXT_KEY_TX_FEE_REFUND_UNUSED)
+ .take()
+ .unwrap_or(false)
+ })
+ }
+
+ fn check_signer_nonces<C: Context>(
+ _ctx: &C,
+ auth_info: &AuthInfo,
+ ) -> Result<Address, modules::core::Error> {
+ let is_pre_schedule = CurrentState::with_env(|env| env.is_pre_schedule());
+ let is_check_only = CurrentState::with_env(|env| env.is_check_only());
+
+ // TODO: Optimize the check/update pair so that the accounts are
+ // fetched only once.
+ let params = Self::params();
+ let sender = CurrentState::with_store(|store| {
+ // Fetch information about each signer.
+ let mut store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let accounts =
+ storage::TypedStore::new(storage::PrefixStore::new(&mut store, &state::ACCOUNTS));
+ let mut sender = None;
+ for si in auth_info.signer_info.iter() {
+ let address = si.address_spec.address();
+ let account: types::Account = accounts.get(address).unwrap_or_default();
+
+ // First signer pays for the fees and is considered the sender.
+ if sender.is_none() {
+ sender = Some(SenderMeta {
+ address,
+ tx_nonce: si.nonce,
+ state_nonce: account.nonce,
+ });
+ }
+
+ // When nonce checking is disabled, skip the rest of the checks.
+ if params.debug_disable_nonce_check {
+ continue;
+ }
+
+ // Check signer nonce against the corresponding account nonce.
+ match si.nonce.cmp(&account.nonce) {
+ Ordering::Less => {
+ // In the past and will never become valid, reject.
+ return Err(modules::core::Error::InvalidNonce);
+ }
+ Ordering::Equal => {} // Ok.
+ Ordering::Greater => {
+ // If too much in the future, reject.
+ if si.nonce - account.nonce > MAX_CHECK_NONCE_FUTURE_DELTA {
+ return Err(modules::core::Error::InvalidNonce);
+ }
+
+ // If in the future and this is before scheduling, reject with separate error
+ // that will make the scheduler skip the transaction.
+ if is_pre_schedule {
+ return Err(modules::core::Error::FutureNonce);
+ }
+
+ // If in the future and this is during execution, reject.
+ if !is_check_only {
+ return Err(modules::core::Error::InvalidNonce);
+ }
+
+ // If in the future and this is during checks, accept.
+ }
+ }
+ }
+
+ Ok(sender)
+ })?;
+
+ // Configure the sender.
+ let sender = sender.expect("at least one signer is always present");
+ let sender_address = sender.address;
+ if is_check_only {
+ <C::Runtime as Runtime>::Core::set_sender_meta(sender);
+ }
+
+ Ok(sender_address)
+ }
+
+ fn update_signer_nonces<C: Context>(
+ _ctx: &C,
+ auth_info: &AuthInfo,
+ ) -> Result<(), modules::core::Error> {
+ CurrentState::with_store(|store| {
+ // Fetch information about each signer.
+ let mut store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut accounts =
+ storage::TypedStore::new(storage::PrefixStore::new(&mut store, &state::ACCOUNTS));
+ for si in auth_info.signer_info.iter() {
+ let address = si.address_spec.address();
+ let mut account: types::Account = accounts.get(address).unwrap_or_default();
+
+ // Update nonce.
+ account.nonce = account
+ .nonce
+ .checked_add(1)
+ .ok_or(modules::core::Error::InvalidNonce)?; // Should never overflow.
+ accounts.insert(address, account);
+ }
+ Ok(())
+ })
+ }
+}
+
+#[sdk_derive(Module)]
+impl Module {
+ const NAME: &'static str = MODULE_NAME;
+ type Error = Error;
+ type Event = Event;
+ type Parameters = Parameters;
+ type Genesis = Genesis;
+
+ #[migration(init)]
+ pub fn init(genesis: Genesis) {
+ CurrentState::with_store(|store| {
+ // Create accounts.
+ let mut store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut accounts =
+ storage::TypedStore::new(storage::PrefixStore::new(&mut store, &state::ACCOUNTS));
+ for (address, account) in genesis.accounts {
+ accounts.insert(address, account);
+ }
+
+ // Create balances.
+ let mut balances = storage::PrefixStore::new(&mut store, &state::BALANCES);
+ let mut computed_total_supply: BTreeMap<token::Denomination, u128> = BTreeMap::new();
+ for (address, denominations) in genesis.balances.iter() {
+ let mut account =
+ storage::TypedStore::new(storage::PrefixStore::new(&mut balances, &address));
+ for (denomination, value) in denominations {
+ account.insert(denomination, value);
+
+ // Update computed total supply.
+ computed_total_supply
+ .entry(denomination.clone())
+ .and_modify(|v| *v += value)
+ .or_insert_with(|| *value);
+ }
+ }
+
+ // Validate and set total supply.
+ let mut total_supplies = storage::TypedStore::new(storage::PrefixStore::new(
+ &mut store,
+ &state::TOTAL_SUPPLY,
+ ));
+ for (denomination, total_supply) in genesis.total_supplies.iter() {
+ let computed = computed_total_supply
+ .remove(denomination)
+ .expect("unexpected total supply");
+ assert!(
+ &computed == total_supply,
+ "unexpected total supply (expected: {total_supply} got: {computed})",
+ );
+
+ total_supplies.insert(denomination, total_supply);
+ }
+ if let Some((denomination, total_supply)) = computed_total_supply.iter().next() {
+ panic!("missing expected total supply: {total_supply} {denomination}",);
+ }
+ });
+
+ // Validate genesis parameters.
+ genesis
+ .parameters
+ .validate_basic()
+ .expect("invalid genesis parameters");
+
+ // Set genesis parameters.
+ Self::set_params(genesis.parameters);
+ }
+
+ #[handler(prefetch = "accounts.Transfer")]
+ fn prefetch_transfer(
+ add_prefix: &mut dyn FnMut(Prefix),
+ body: cbor::Value,
+ auth_info: &AuthInfo,
+ ) -> Result<(), crate::error::RuntimeError> {
+ let args: types::Transfer = cbor::from_value(body).map_err(|_| Error::InvalidArgument)?;
+ let from = auth_info.signer_info[0].address_spec.address();
+
+ // Prefetch accounts 'to'.
+ add_prefix(Prefix::from(
+ [MODULE_NAME.as_bytes(), state::ACCOUNTS, args.to.as_ref()].concat(),
+ ));
+ add_prefix(Prefix::from(
+ [MODULE_NAME.as_bytes(), state::BALANCES, args.to.as_ref()].concat(),
+ ));
+ // Prefetch accounts 'from'.
+ add_prefix(Prefix::from(
+ [MODULE_NAME.as_bytes(), state::ACCOUNTS, from.as_ref()].concat(),
+ ));
+ add_prefix(Prefix::from(
+ [MODULE_NAME.as_bytes(), state::BALANCES, from.as_ref()].concat(),
+ ));
+
+ Ok(())
+ }
+
+ #[handler(call = "accounts.Transfer")]
+ fn tx_transfer<C: Context>(_ctx: &C, body: types::Transfer) -> Result<(), Error> {
+ let params = Self::params();
+
+ // Reject transfers when they are disabled.
+ if params.transfers_disabled {
+ return Err(Error::Forbidden);
+ }
+
+ <C::Runtime as Runtime>::Core::use_tx_gas(params.gas_costs.tx_transfer)?;
+
+ let tx_caller_address = CurrentState::with_env(|env| env.tx_caller_address());
+ Self::transfer(tx_caller_address, body.to, &body.amount)?;
+
+ Ok(())
+ }
+
+ #[handler(query = "accounts.Nonce")]
+ fn query_nonce<C: Context>(_ctx: &C, args: types::NonceQuery) -> Result<u64, Error> {
+ Self::get_nonce(args.address)
+ }
+
+ #[handler(query = "accounts.Addresses", expensive)]
+ fn query_addresses<C: Context>(
+ _ctx: &C,
+ args: types::AddressesQuery,
+ ) -> Result<Vec<Address>, Error> {
+ Self::get_addresses(args.denomination)
+ }
+
+ #[handler(query = "accounts.Balances")]
+ fn query_balances<C: Context>(
+ _ctx: &C,
+ args: types::BalancesQuery,
+ ) -> Result<types::AccountBalances, Error> {
+ Self::get_balances(args.address)
+ }
+
+ #[handler(query = "accounts.DenominationInfo")]
+ fn query_denomination_info<C: Context>(
+ _ctx: &C,
+ args: types::DenominationInfoQuery,
+ ) -> Result<types::DenominationInfo, Error> {
+ Self::get_denomination_info(&args.denomination)
+ }
+}
+
+impl module::TransactionHandler for Module {
+ fn authenticate_tx<C: Context>(
+ ctx: &C,
+ tx: &Transaction,
+ ) -> Result<module::AuthDecision, modules::core::Error> {
+ // Check nonces.
+ let default_payer = Self::check_signer_nonces(ctx, &tx.auth_info)?;
+
+ // Attempt to resolve a proxy fee payer if set.
+ let payer =
+ <C::Runtime as Runtime>::FeeProxy::resolve_payer(ctx, tx)?.unwrap_or(default_payer);
+
+ // Charge the specified amount of fees.
+ if !tx.auth_info.fee.amount.amount().is_zero() {
+ if CurrentState::with_env(|env| env.is_check_only()) {
+ // Do not update balances during transaction checks. In case of checks, only do it
+ // after all the other checks have already passed as otherwise retrying the
+ // transaction will not be possible.
+ Self::ensure_balance(payer, &tx.auth_info.fee.amount)
+ .map_err(|_| modules::core::Error::InsufficientFeeBalance)?;
+
+ // Make sure to record the payer during transaction checks.
+ CurrentState::with(|state| {
+ state
+ .block_value::<fee::FeeManager>(CONTEXT_KEY_FEE_MANAGER)
+ .or_default()
+ .record_fee(payer, &tx.auth_info.fee.amount);
+ });
+ } else {
+ // Actually perform the move.
+ Self::charge_tx_fee(payer, &tx.auth_info.fee.amount)?;
+ }
+
+ let gas_price = tx.auth_info.fee.gas_price();
+ // Set transaction priority.
+ <C::Runtime as Runtime>::Core::set_priority(gas_price.try_into().unwrap_or(u64::MAX));
+ }
+
+ // Do not update nonces early during transaction checks. In case of checks, only do it after
+ // all the other checks have already passed as otherwise retrying the transaction will not
+ // be possible.
+ if !CurrentState::with_env(|env| env.is_check_only()) {
+ Self::update_signer_nonces(ctx, &tx.auth_info)?;
+ }
+
+ Ok(module::AuthDecision::Continue)
+ }
+
+ fn after_handle_call<C: Context>(
+ _ctx: &C,
+ result: module::CallResult,
+ ) -> Result<module::CallResult, modules::core::Error> {
+ // Check whether unused part of the fee should be refunded.
+ let refund_fee = if Self::take_refund_unused_tx_fee() {
+ let remaining_gas = <C::Runtime as Runtime>::Core::remaining_tx_gas();
+ let gas_price = CurrentState::with_env(|env| env.tx_auth_info().fee.gas_price());
+
+ gas_price.saturating_mul(remaining_gas.into())
+ } else {
+ 0
+ };
+
+ CurrentState::with(|state| {
+ let mgr = state
+ .block_value::<fee::FeeManager>(CONTEXT_KEY_FEE_MANAGER)
+ .or_default();
+
+ // Update the per-tx fee accumulator. State must be updated in `after_dispatch_tx` as
+ // otherwise any state updates may be reverted in case call result is a failure.
+ mgr.record_refund(refund_fee);
+
+ // Emit event for paid fee.
+ let tx_fee = mgr.tx_fee().cloned().unwrap_or_default();
+ if tx_fee.amount() > 0 {
+ state.emit_unconditional_event(Event::Transfer {
+ from: tx_fee.payer(),
+ to: *ADDRESS_FEE_ACCUMULATOR,
+ amount: token::BaseUnits::new(tx_fee.amount(), tx_fee.denomination()),
+ });
+ }
+ });
+
+ Ok(result)
+ }
+
+ fn after_dispatch_tx<C: Context>(
+ ctx: &C,
+ tx_auth_info: &AuthInfo,
+ result: &module::CallResult,
+ ) {
+ // Move transaction fees into the per-block fee accumulator.
+ let fee_updates = CurrentState::with(|state| {
+ let mgr = state
+ .block_value::<fee::FeeManager>(CONTEXT_KEY_FEE_MANAGER)
+ .or_default();
+ mgr.commit_tx()
+ });
+ // Refund any fees. This needs to happen after tx dispatch to ensure state is updated.
+ Self::add_amount(fee_updates.payer, &fee_updates.refund).unwrap();
+
+ if !CurrentState::with_env(|env| env.is_check_only()) {
+ // Do nothing further outside transaction checks.
+ return;
+ }
+ if !matches!(result, module::CallResult::Ok(_)) {
+ // Do nothing in case the call failed to allow retries.
+ return;
+ }
+
+ // Update payer balance.
+ Self::sub_amount(fee_updates.payer, &tx_auth_info.fee.amount).unwrap(); // Already checked.
+
+ // Update nonces.
+ Self::update_signer_nonces(ctx, tx_auth_info).unwrap();
+ }
+}
+
+impl module::BlockHandler for Module {
+ fn end_block<C: Context>(ctx: &C) {
+ // Determine the fees that are available for disbursement from the last block.
+ let mut previous_fees = Self::get_balances(*ADDRESS_FEE_ACCUMULATOR)
+ .expect("get_balances must succeed")
+ .balances;
+
+ // Drain previous fees from the fee accumulator.
+ for (denom, remainder) in &previous_fees {
+ Self::sub_amount(
+ *ADDRESS_FEE_ACCUMULATOR,
+ &token::BaseUnits::new(*remainder, denom.clone()),
+ )
+ .expect("sub_amount must succeed");
+ }
+
+ // Disburse transaction fees to entities controlling all the good nodes in the committee.
+ let addrs: Vec<Address> = ctx
+ .runtime_round_results()
+ .good_compute_entities
+ .iter()
+ .map(|pk| Address::from_sigspec(&SignatureAddressSpec::Ed25519(pk.into())))
+ .collect();
+
+ if !addrs.is_empty() {
+ let amounts: Vec<_> = previous_fees
+ .iter()
+ .filter_map(|(denom, fee)| {
+ let fee = fee
+ .checked_div(addrs.len() as u128)
+ .expect("addrs is non-empty");
+
+ // Filter out zero-fee entries to avoid needless operations.
+ if fee.is_zero() {
+ None
+ } else {
+ Some(token::BaseUnits::new(fee, denom.clone()))
+ }
+ })
+ .collect();
+
+ for address in addrs {
+ for amount in &amounts {
+ let remaining = previous_fees
+ .get_mut(amount.denomination())
+ .expect("designated denomination should be there");
+ *remaining = remaining
+ .checked_sub(amount.amount())
+ .expect("there should be enough to disburse");
+
+ Self::add_amount(address, amount)
+ .expect("add_amount must succeed for fee disbursement");
+
+ // Emit transfer event for fee disbursement.
+ CurrentState::with(|state| {
+ state.emit_event(Event::Transfer {
+ from: *ADDRESS_FEE_ACCUMULATOR,
+ to: address,
+ amount: amount.clone(),
+ });
+ });
+ }
+ }
+ }
+
+ // Transfer remainder to a common pool account.
+ for (denom, remainder) in previous_fees.into_iter() {
+ if remainder.is_zero() {
+ continue;
+ }
+
+ let amount = token::BaseUnits::new(remainder, denom);
+ Self::add_amount(*ADDRESS_COMMON_POOL, &amount)
+ .expect("add_amount must succeed for transfer to common pool");
+
+ // Emit transfer event for fee disbursement.
+ CurrentState::with(|state| {
+ state.emit_event(Event::Transfer {
+ from: *ADDRESS_FEE_ACCUMULATOR,
+ to: *ADDRESS_COMMON_POOL,
+ amount,
+ })
+ });
+ }
+
+ // Fees for the active block should be transferred to the fee accumulator address.
+ let block_fees = CurrentState::with(|state| {
+ let mgr = state
+ .block_value::<fee::FeeManager>(CONTEXT_KEY_FEE_MANAGER)
+ .take()
+ .unwrap_or_default();
+ mgr.commit_block().into_iter()
+ });
+
+ for (denom, amount) in block_fees {
+ Self::add_amount(
+ *ADDRESS_FEE_ACCUMULATOR,
+ &token::BaseUnits::new(amount, denom),
+ )
+ .expect("add_amount must succeed for transfer to fee accumulator")
+ }
+ }
+}
+
+impl module::InvariantHandler for Module {
+ /// Check invariants.
+ fn check_invariants<C: Context>(_ctx: &C) -> Result<(), CoreError> {
+ // All account balances should sum up to the total supply for their
+ // corresponding denominations.
+
+ #[allow(clippy::or_fun_call)]
+ let balances = Self::get_all_balances().or(Err(CoreError::InvariantViolation(
+ "unable to get balances of all accounts".to_string(),
+ )))?;
+ #[allow(clippy::or_fun_call)]
+ let total_supplies = Self::get_total_supplies().or(Err(CoreError::InvariantViolation(
+ "unable to get total supplies".to_string(),
+ )))?;
+
+ // First, compute total supplies based on account balances.
+ let mut computed_ts: BTreeMap<token::Denomination, u128> = BTreeMap::new();
+
+ for bals in balances.values() {
+ for (den, amt) in bals {
+ computed_ts
+ .entry(den.clone())
+ .and_modify(|a| *a += amt)
+ .or_insert_with(|| *amt);
+ }
+ }
+
+ // Now check if the computed and given total supplies match.
+ for (den, ts) in &total_supplies {
+ // Return error if total supplies have a denomination that we
+ // didn't encounter when computing total supplies based on account
+ // balances.
+ #[allow(clippy::or_fun_call)]
+ let computed = computed_ts
+ .remove(den)
+ .ok_or(CoreError::InvariantViolation(
+ "unexpected denomination".to_string(),
+ ))?;
+
+ if &computed != ts {
+ // Computed and actual total supplies don't match.
+ return Err(CoreError::InvariantViolation(format!(
+ "computed and actual total supplies don't match (computed={computed}, actual={ts})",
+ )));
+ }
+ }
+
+ // There should be no remaining denominations in the computed supplies,
+ // because that would mean that accounts have denominations that don't
+ // appear in the total supplies table, which would obviously be wrong.
+ if computed_ts.is_empty() {
+ Ok(())
+ } else {
+ Err(CoreError::InvariantViolation(
+ "encountered denomination that isn't present in total supplies table".to_string(),
+ ))
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +
//! Account module types.
+use std::collections::BTreeMap;
+
+use crate::types::{address::Address, token};
+
+/// Transfer call.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Transfer {
+ pub to: Address,
+ pub amount: token::BaseUnits,
+}
+
+/// Account metadata.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Account {
+ #[cbor(optional)]
+ pub nonce: u64,
+}
+
+/// Arguments for the Nonce query.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct NonceQuery {
+ pub address: Address,
+}
+
+/// Arguments for the Addresses query.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct AddressesQuery {
+ pub denomination: token::Denomination,
+}
+
+/// Arguments for the Balances query.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct BalancesQuery {
+ pub address: Address,
+}
+
+/// Balances in an account.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct AccountBalances {
+ pub balances: BTreeMap<token::Denomination, u128>,
+}
+
+/// Arguments for the DenominationInfo query.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct DenominationInfoQuery {
+ pub denomination: token::Denomination,
+}
+
+/// Information about a denomination.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct DenominationInfo {
+ /// Number of decimals that the denomination is using.
+ pub decimals: u8,
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +
//! Consensus module.
+//!
+//! Low level consensus module for communicating with the consensus layer.
+use std::{convert::TryInto, num::NonZeroUsize, str::FromStr, sync::Mutex};
+
+use oasis_runtime_sdk_macros::handler;
+use once_cell::sync::Lazy;
+use thiserror::Error;
+
+use oasis_core_runtime::{
+ common::{namespace::Namespace, versioned::Versioned},
+ consensus::{
+ beacon::EpochTime,
+ roothash::{Message, RoundRoots, StakingMessage},
+ staking,
+ staking::{Account as ConsensusAccount, Delegation as ConsensusDelegation},
+ state::{
+ beacon::ImmutableState as BeaconImmutableState,
+ roothash::ImmutableState as RoothashImmutableState,
+ staking::ImmutableState as StakingImmutableState, StateError,
+ },
+ HEIGHT_LATEST,
+ },
+};
+
+use crate::{
+ context::Context,
+ core::common::crypto::hash::Hash,
+ history, migration, module,
+ module::{Module as _, Parameters as _},
+ modules,
+ modules::core::API as _,
+ sdk_derive,
+ state::CurrentState,
+ types::{
+ address::{Address, SignatureAddressSpec},
+ message::MessageEventHookInvocation,
+ token,
+ transaction::{AddressSpec, CallerAddress},
+ },
+ Runtime,
+};
+
+#[cfg(test)]
+mod test;
+pub mod types;
+
+/// Unique module name.
+const MODULE_NAME: &str = "consensus";
+
+/// Gas costs.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct GasCosts {
+ /// Cost of the internal round_root call.
+ pub round_root: u64,
+}
+
+/// Parameters for the consensus module.
+#[derive(Clone, Debug, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct Parameters {
+ pub gas_costs: GasCosts,
+
+ pub consensus_denomination: token::Denomination,
+ pub consensus_scaling_factor: u64,
+
+ /// Minimum amount that is allowed to be delegated. This should be greater than or equal to what
+ /// is configured in the consensus layer as the consensus layer will do its own checks.
+ ///
+ /// The amount is in consensus units.
+ pub min_delegate_amount: u128,
+}
+
+impl Default for Parameters {
+ fn default() -> Self {
+ Self {
+ gas_costs: Default::default(),
+ consensus_denomination: token::Denomination::from_str("TEST").unwrap(),
+ consensus_scaling_factor: 1,
+ min_delegate_amount: 0,
+ }
+ }
+}
+
+/// Errors emitted during rewards parameter validation.
+#[derive(Error, Debug)]
+pub enum ParameterValidationError {
+ #[error("consensus scaling factor set to zero")]
+ ZeroScalingFactor,
+
+ #[error("consensus scaling factor is not a power of 10")]
+ ScalingFactorNotPowerOf10,
+}
+
+impl module::Parameters for Parameters {
+ type Error = ParameterValidationError;
+
+ fn validate_basic(&self) -> Result<(), Self::Error> {
+ if self.consensus_scaling_factor == 0 {
+ return Err(ParameterValidationError::ZeroScalingFactor);
+ }
+
+ let log = self.consensus_scaling_factor.ilog10();
+ if 10u64.pow(log) != self.consensus_scaling_factor {
+ return Err(ParameterValidationError::ScalingFactorNotPowerOf10);
+ }
+
+ Ok(())
+ }
+}
+/// Events emitted by the consensus module (none so far).
+#[derive(Debug, cbor::Encode, oasis_runtime_sdk_macros::Event)]
+#[cbor(untagged)]
+pub enum Event {}
+
+/// Genesis state for the consensus module.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Genesis {
+ pub parameters: Parameters,
+}
+
+#[derive(Error, Debug, oasis_runtime_sdk_macros::Error)]
+pub enum Error {
+ #[error("invalid argument")]
+ #[sdk_error(code = 1)]
+ InvalidArgument,
+
+ #[error("invalid denomination")]
+ #[sdk_error(code = 2)]
+ InvalidDenomination,
+
+ #[error("internal state: {0}")]
+ #[sdk_error(code = 3)]
+ InternalStateError(#[from] StateError),
+
+ #[error("core: {0}")]
+ #[sdk_error(transparent)]
+ Core(#[from] modules::core::Error),
+
+ #[error("consensus incompatible signer")]
+ #[sdk_error(code = 4)]
+ ConsensusIncompatibleSigner,
+
+ #[error("amount not representable")]
+ #[sdk_error(code = 5)]
+ AmountNotRepresentable,
+
+ #[error("amount is lower than the minimum delegation amount")]
+ #[sdk_error(code = 6)]
+ UnderMinDelegationAmount,
+
+ #[error("history: {0}")]
+ #[sdk_error(transparent)]
+ History(#[from] history::Error),
+}
+
+/// Interface that can be called from other modules.
+pub trait API {
+ /// Transfer an amount from the runtime account.
+ fn transfer<C: Context>(
+ ctx: &C,
+ to: Address,
+ amount: &token::BaseUnits,
+ hook: MessageEventHookInvocation,
+ ) -> Result<(), Error>;
+
+ /// Withdraw an amount into the runtime account.
+ fn withdraw<C: Context>(
+ ctx: &C,
+ from: Address,
+ amount: &token::BaseUnits,
+ hook: MessageEventHookInvocation,
+ ) -> Result<(), Error>;
+
+ /// Escrow an amount of the runtime account funds.
+ fn escrow<C: Context>(
+ ctx: &C,
+ to: Address,
+ amount: &token::BaseUnits,
+ hook: MessageEventHookInvocation,
+ ) -> Result<(), Error>;
+
+ /// Reclaim an amount of runtime staked shares.
+ fn reclaim_escrow<C: Context>(
+ ctx: &C,
+ from: Address,
+ amount: u128,
+ hook: MessageEventHookInvocation,
+ ) -> Result<(), Error>;
+
+ /// Returns consensus token denomination.
+ fn consensus_denomination() -> Result<token::Denomination, Error>;
+
+ /// Ensures transaction signer is consensus compatible.
+ fn ensure_compatible_tx_signer() -> Result<(), Error>;
+
+ /// Query consensus account info.
+ fn account<C: Context>(ctx: &C, addr: Address) -> Result<ConsensusAccount, Error>;
+
+ /// Query consensus delegation info.
+ fn delegation<C: Context>(
+ ctx: &C,
+ delegator_addr: Address,
+ escrow_addr: Address,
+ ) -> Result<ConsensusDelegation, Error>;
+
+ /// Convert runtime amount to consensus amount, scaling as needed.
+ fn amount_from_consensus<C: Context>(ctx: &C, amount: u128) -> Result<u128, Error>;
+
+ /// Convert consensus amount to runtime amount, scaling as needed.
+ fn amount_to_consensus<C: Context>(ctx: &C, amount: u128) -> Result<u128, Error>;
+
+ /// Determine consensus height corresponding to the given epoch transition. This query may be
+ /// expensive in case the epoch is far back.
+ fn height_for_epoch<C: Context>(ctx: &C, epoch: EpochTime) -> Result<u64, Error>;
+
+ /// Round roots return the round roots for the given runtime ID and round.
+ fn round_roots<C: Context>(
+ ctx: &C,
+ runtime_id: Namespace,
+ round: u64,
+ ) -> Result<Option<RoundRoots>, Error>;
+}
+
+pub struct Module;
+
+impl Module {
+ fn ensure_consensus_denomination(denomination: &token::Denomination) -> Result<(), Error> {
+ if denomination != &Self::consensus_denomination()? {
+ return Err(Error::InvalidDenomination);
+ }
+
+ Ok(())
+ }
+}
+
+#[sdk_derive(Module)]
+impl Module {
+ const NAME: &'static str = MODULE_NAME;
+ const VERSION: u32 = 1;
+ type Error = Error;
+ type Event = Event;
+ type Parameters = Parameters;
+ type Genesis = Genesis;
+
+ #[migration(init)]
+ pub fn init(genesis: Genesis) {
+ // Validate genesis parameters.
+ genesis
+ .parameters
+ .validate_basic()
+ .expect("invalid genesis parameters");
+
+ // Set genesis parameters.
+ Self::set_params(genesis.parameters);
+ }
+
+ #[handler(call = "consensus.RoundRoot", internal)]
+ fn internal_round_root<C: Context>(
+ ctx: &C,
+ body: types::RoundRootBody,
+ ) -> Result<Option<Hash>, Error> {
+ let params = Self::params();
+ <C::Runtime as Runtime>::Core::use_tx_gas(params.gas_costs.round_root)?;
+
+ Ok(
+ Self::round_roots(ctx, body.runtime_id, body.round)?.map(|rr| match body.kind {
+ types::RootKind::IO => rr.io_root,
+ types::RootKind::State => rr.state_root,
+ }),
+ )
+ }
+}
+
+impl API for Module {
+ fn transfer<C: Context>(
+ ctx: &C,
+ to: Address,
+ amount: &token::BaseUnits,
+ hook: MessageEventHookInvocation,
+ ) -> Result<(), Error> {
+ Self::ensure_consensus_denomination(amount.denomination())?;
+ let amount = Self::amount_to_consensus(ctx, amount.amount())?;
+
+ CurrentState::with(|state| {
+ state.emit_message(
+ ctx,
+ Message::Staking(Versioned::new(
+ 0,
+ StakingMessage::Transfer(staking::Transfer {
+ to: to.into(),
+ amount: amount.into(),
+ }),
+ )),
+ hook,
+ )
+ })?;
+
+ Ok(())
+ }
+
+ fn withdraw<C: Context>(
+ ctx: &C,
+ from: Address,
+ amount: &token::BaseUnits,
+ hook: MessageEventHookInvocation,
+ ) -> Result<(), Error> {
+ Self::ensure_consensus_denomination(amount.denomination())?;
+ let amount = Self::amount_to_consensus(ctx, amount.amount())?;
+
+ CurrentState::with(|state| {
+ state.emit_message(
+ ctx,
+ Message::Staking(Versioned::new(
+ 0,
+ StakingMessage::Withdraw(staking::Withdraw {
+ from: from.into(),
+ amount: amount.into(),
+ }),
+ )),
+ hook,
+ )
+ })?;
+
+ Ok(())
+ }
+
+ fn escrow<C: Context>(
+ ctx: &C,
+ to: Address,
+ amount: &token::BaseUnits,
+ hook: MessageEventHookInvocation,
+ ) -> Result<(), Error> {
+ Self::ensure_consensus_denomination(amount.denomination())?;
+ let amount = Self::amount_to_consensus(ctx, amount.amount())?;
+
+ if amount < Self::params().min_delegate_amount {
+ return Err(Error::UnderMinDelegationAmount);
+ }
+
+ CurrentState::with(|state| {
+ state.emit_message(
+ ctx,
+ Message::Staking(Versioned::new(
+ 0,
+ StakingMessage::AddEscrow(staking::Escrow {
+ account: to.into(),
+ amount: amount.into(),
+ }),
+ )),
+ hook,
+ )
+ })?;
+
+ Ok(())
+ }
+
+ fn reclaim_escrow<C: Context>(
+ ctx: &C,
+ from: Address,
+ shares: u128,
+ hook: MessageEventHookInvocation,
+ ) -> Result<(), Error> {
+ CurrentState::with(|state| {
+ state.emit_message(
+ ctx,
+ Message::Staking(Versioned::new(
+ 0,
+ StakingMessage::ReclaimEscrow(staking::ReclaimEscrow {
+ account: from.into(),
+ shares: shares.into(),
+ }),
+ )),
+ hook,
+ )
+ })?;
+
+ Ok(())
+ }
+
+ fn consensus_denomination() -> Result<token::Denomination, Error> {
+ Ok(Self::params().consensus_denomination)
+ }
+
+ fn ensure_compatible_tx_signer() -> Result<(), Error> {
+ CurrentState::with_env(|env| match env.tx_auth_info().signer_info[0].address_spec {
+ AddressSpec::Signature(SignatureAddressSpec::Ed25519(_)) => Ok(()),
+ AddressSpec::Internal(CallerAddress::Address(_)) if env.is_simulation() => {
+ // During simulations, the caller may be overriden in case of confidential runtimes
+ // which would cause this check to always fail, making gas estimation incorrect.
+ //
+ // Note that this is optimistic as a `CallerAddres::Address(_)` can still be
+ // incompatible, but as long as this is only allowed during simulations it shouldn't
+ // result in any problems.
+ Ok(())
+ }
+ _ => Err(Error::ConsensusIncompatibleSigner),
+ })
+ }
+
+ fn account<C: Context>(ctx: &C, addr: Address) -> Result<ConsensusAccount, Error> {
+ let state = StakingImmutableState::new(ctx.consensus_state());
+ state
+ .account(addr.into())
+ .map_err(Error::InternalStateError)
+ }
+
+ fn delegation<C: Context>(
+ ctx: &C,
+ delegator_addr: Address,
+ escrow_addr: Address,
+ ) -> Result<ConsensusDelegation, Error> {
+ let state = StakingImmutableState::new(ctx.consensus_state());
+ state
+ .delegation(delegator_addr.into(), escrow_addr.into())
+ .map_err(Error::InternalStateError)
+ }
+
+ fn amount_from_consensus<C: Context>(_ctx: &C, amount: u128) -> Result<u128, Error> {
+ let scaling_factor = Self::params().consensus_scaling_factor;
+ amount
+ .checked_mul(scaling_factor.into())
+ .ok_or(Error::AmountNotRepresentable)
+ }
+
+ fn amount_to_consensus<C: Context>(_ctx: &C, amount: u128) -> Result<u128, Error> {
+ let scaling_factor = Self::params().consensus_scaling_factor;
+ let scaled = amount
+ .checked_div(scaling_factor.into())
+ .ok_or(Error::AmountNotRepresentable)?;
+
+ // Ensure there is no remainder as that is not representable in the consensus layer.
+ let remainder = amount
+ .checked_rem(scaling_factor.into())
+ .ok_or(Error::AmountNotRepresentable)?;
+ if remainder != 0 {
+ return Err(Error::AmountNotRepresentable);
+ }
+
+ Ok(scaled)
+ }
+
+ fn height_for_epoch<C: Context>(ctx: &C, epoch: EpochTime) -> Result<u64, Error> {
+ static HEIGHT_CACHE: Lazy<Mutex<lru::LruCache<EpochTime, u64>>> =
+ Lazy::new(|| Mutex::new(lru::LruCache::new(NonZeroUsize::new(128).unwrap())));
+
+ // Check the cache first to avoid more expensive traversals.
+ let mut cache = HEIGHT_CACHE.lock().unwrap();
+ if let Some(height) = cache.get(&epoch) {
+ return Ok(*height);
+ }
+
+ // Resolve height for the given epoch.
+ let mut height = HEIGHT_LATEST;
+ loop {
+ let state = ctx.history().consensus_state_at(height)?;
+
+ let beacon = BeaconImmutableState::new(&state);
+
+ let mut epoch_state = beacon.future_epoch_state()?;
+ if epoch_state.height > state.height().try_into().unwrap() {
+ // Use current epoch if future epoch is in the future.
+ epoch_state = beacon.epoch_state().unwrap();
+ }
+ height = epoch_state.height.try_into().unwrap();
+
+ // Cache height for later queries.
+ cache.put(epoch_state.epoch, height);
+
+ if epoch_state.epoch == epoch {
+ return Ok(height);
+ }
+
+ assert!(epoch_state.epoch > epoch);
+ assert!(height > 1);
+
+ // Go one height before epoch transition.
+ height -= 1;
+ }
+ }
+
+ fn round_roots<C: Context>(
+ ctx: &C,
+ runtime_id: Namespace,
+ round: u64,
+ ) -> Result<Option<RoundRoots>, Error> {
+ let roothash = RoothashImmutableState::new(ctx.consensus_state());
+ roothash
+ .round_roots(runtime_id, round)
+ .map_err(Error::InternalStateError)
+ }
+}
+
+impl module::TransactionHandler for Module {}
+
+impl module::BlockHandler for Module {}
+
+impl module::InvariantHandler for Module {}
+use oasis_core_runtime::common::namespace::Namespace;
+
+/// Kind of root.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[repr(u8)]
+pub enum RootKind {
+ State = 1,
+ IO = 2,
+}
+
+/// Internal round root call body.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct RoundRootBody {
+ pub runtime_id: Namespace,
+ pub round: u64,
+ pub kind: RootKind,
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +765 +766 +767 +768 +769 +770 +771 +772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805 +806 +807 +808 +809 +810 +811 +812 +813 +814 +815 +816 +817 +818 +819 +820 +821 +822 +823 +824 +825 +826 +827 +828 +829 +830 +831 +832 +833 +834 +835 +836 +837 +838 +839 +840 +841 +842 +843 +844 +845 +846 +847 +848 +849 +850 +851 +852 +853 +854 +855 +856 +857 +858 +859 +860 +861 +862 +863 +864 +865 +866 +867 +868 +869 +870 +871 +872 +873 +874 +875 +876 +877 +878 +879 +880 +881 +882 +883 +884 +885 +886 +887 +888 +889 +890 +891 +892 +893 +894 +895 +896 +897 +898 +899 +900 +901 +902 +903 +904 +905 +906 +907 +908 +909 +910 +911 +912 +913 +914 +915 +916 +917 +918 +919 +920 +921 +922 +923 +924 +925 +926 +927 +928 +929 +930 +931 +932 +933 +934 +935 +936 +937 +938 +939 +940 +941 +942 +943 +944 +945 +946 +947 +948 +949 +950 +951 +952 +953 +954 +955 +956 +957 +958 +959 +960 +961 +962 +963 +964 +965 +966 +967 +968 +969 +970 +971 +972 +973 +974 +975 +976 +977 +978 +979 +980 +981 +982 +983 +984 +985 +986 +987 +988 +989 +990 +991 +992 +993 +994 +995 +996 +997 +998 +999 +
//! Consensus accounts module.
+//!
+//! This module allows consensus transfers in and out of the runtime account,
+//! while keeping track of amount deposited per account.
+use std::{collections::BTreeSet, convert::TryInto, num::NonZeroUsize};
+
+use once_cell::sync::Lazy;
+use thiserror::Error;
+
+use oasis_core_runtime::{
+ consensus::{
+ self,
+ beacon::{EpochTime, EPOCH_INVALID},
+ staking::{self, Account as ConsensusAccount, AddEscrowResult, ReclaimEscrowResult},
+ },
+ types::EventKind,
+};
+use oasis_runtime_sdk_macros::{handler, sdk_derive};
+
+use crate::{
+ context::Context,
+ error, migration, module,
+ module::Module as _,
+ modules,
+ modules::{
+ accounts::API as _,
+ core::{Error as CoreError, API as _},
+ },
+ runtime::Runtime,
+ state::CurrentState,
+ storage::Prefix,
+ types::{
+ address::Address,
+ message::{MessageEvent, MessageEventHookInvocation},
+ token,
+ transaction::AuthInfo,
+ },
+};
+
+pub mod state;
+#[cfg(test)]
+mod test;
+pub mod types;
+
+/// Unique module name.
+const MODULE_NAME: &str = "consensus_accounts";
+
+#[derive(Error, Debug, oasis_runtime_sdk_macros::Error)]
+pub enum Error {
+ #[error("invalid argument")]
+ #[sdk_error(code = 1)]
+ InvalidArgument,
+
+ #[error("invalid denomination")]
+ #[sdk_error(code = 2)]
+ InvalidDenomination,
+
+ #[error("insufficient balance")]
+ #[sdk_error(code = 3)]
+ InsufficientBalance,
+
+ #[error("forbidden by policy")]
+ #[sdk_error(code = 4)]
+ Forbidden,
+
+ #[error("consensus: {0}")]
+ #[sdk_error(transparent)]
+ Consensus(#[from] modules::consensus::Error),
+
+ #[error("core: {0}")]
+ #[sdk_error(transparent)]
+ Core(#[from] modules::core::Error),
+}
+
+/// Gas costs.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct GasCosts {
+ pub tx_deposit: u64,
+ pub tx_withdraw: u64,
+ pub tx_delegate: u64,
+ pub tx_undelegate: u64,
+
+ /// Cost of storing a delegation/undelegation receipt.
+ pub store_receipt: u64,
+ /// Cost of taking a delegation/undelegation receipt.
+ pub take_receipt: u64,
+}
+
+/// Parameters for the consensus module.
+#[derive(Clone, Default, Debug, cbor::Encode, cbor::Decode)]
+pub struct Parameters {
+ pub gas_costs: GasCosts,
+
+ /// Whether delegate functionality should be disabled.
+ pub disable_delegate: bool,
+ /// Whether undelegate functionality should be disabled.
+ pub disable_undelegate: bool,
+ /// Whether deposit functionality should be disabled.
+ pub disable_deposit: bool,
+ /// Whether withdraw functionality should be disabled.
+ pub disable_withdraw: bool,
+}
+
+impl module::Parameters for Parameters {
+ type Error = ();
+}
+
+/// Events emitted by the consensus accounts module.
+#[derive(Debug, cbor::Encode, oasis_runtime_sdk_macros::Event)]
+#[cbor(untagged)]
+pub enum Event {
+ #[sdk_event(code = 1)]
+ Deposit {
+ from: Address,
+ nonce: u64,
+ to: Address,
+ amount: token::BaseUnits,
+ #[cbor(optional)]
+ error: Option<types::ConsensusError>,
+ },
+
+ #[sdk_event(code = 2)]
+ Withdraw {
+ from: Address,
+ nonce: u64,
+ to: Address,
+ amount: token::BaseUnits,
+ #[cbor(optional)]
+ error: Option<types::ConsensusError>,
+ },
+
+ #[sdk_event(code = 3)]
+ Delegate {
+ from: Address,
+ nonce: u64,
+ to: Address,
+ amount: token::BaseUnits,
+ #[cbor(optional)]
+ error: Option<types::ConsensusError>,
+ },
+
+ #[sdk_event(code = 4)]
+ UndelegateStart {
+ from: Address,
+ nonce: u64,
+ to: Address,
+ shares: u128,
+ debond_end_time: EpochTime,
+ #[cbor(optional)]
+ error: Option<types::ConsensusError>,
+ },
+
+ #[sdk_event(code = 5)]
+ UndelegateDone {
+ from: Address,
+ to: Address,
+ shares: u128,
+ amount: token::BaseUnits,
+ },
+}
+
+/// Genesis state for the consensus module.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Genesis {
+ pub parameters: Parameters,
+}
+
+/// Interface that can be called from other modules.
+pub trait API {
+ /// Transfer from consensus staking account to runtime account.
+ ///
+ /// # Arguments
+ ///
+ /// * `nonce`: A caller-provided sequence number that will help identify the success/fail events.
+ /// When called from a deposit transaction, we use the signer nonce.
+ fn deposit<C: Context>(
+ ctx: &C,
+ from: Address,
+ nonce: u64,
+ to: Address,
+ amount: token::BaseUnits,
+ ) -> Result<(), Error>;
+
+ /// Transfer from runtime account to consensus staking account.
+ ///
+ /// # Arguments
+ ///
+ /// * `nonce`: A caller-provided sequence number that will help identify the success/fail events.
+ /// When called from a withdraw transaction, we use the signer nonce.
+ fn withdraw<C: Context>(
+ ctx: &C,
+ from: Address,
+ nonce: u64,
+ to: Address,
+ amount: token::BaseUnits,
+ ) -> Result<(), Error>;
+
+ /// Delegate from runtime account to consensus staking account.
+ ///
+ /// # Arguments
+ ///
+ /// * `nonce`: A caller-provided sequence number that will help identify the success/fail events.
+ /// When called from a delegate transaction, we use the signer nonce.
+ fn delegate<C: Context>(
+ ctx: &C,
+ from: Address,
+ nonce: u64,
+ to: Address,
+ amount: token::BaseUnits,
+ receipt: bool,
+ ) -> Result<(), Error>;
+
+ /// Start the undelegation process of the given number of shares from consensus staking account
+ /// to runtime account.
+ ///
+ /// # Arguments
+ ///
+ /// * `nonce`: A caller-provided sequence number that will help identify the success/fail events.
+ /// When called from an undelegate transaction, we use the signer nonce.
+ fn undelegate<C: Context>(
+ ctx: &C,
+ from: Address,
+ nonce: u64,
+ to: Address,
+ shares: u128,
+ receipt: bool,
+ ) -> Result<(), Error>;
+}
+
+pub struct Module<Consensus: modules::consensus::API> {
+ _consensus: std::marker::PhantomData<Consensus>,
+}
+
+/// Module's address that has the tokens pending withdrawal.
+///
+/// oasis1qr677rv0dcnh7ys4yanlynysvnjtk9gnsyhvm6ln
+pub static ADDRESS_PENDING_WITHDRAWAL: Lazy<Address> =
+ Lazy::new(|| Address::from_module(MODULE_NAME, "pending-withdrawal"));
+
+/// Module's address that has the tokens pending delegation.
+///
+/// oasis1qzcdegtf7aunxr5n5pw7n5xs3u7cmzlz9gwmq49r
+pub static ADDRESS_PENDING_DELEGATION: Lazy<Address> =
+ Lazy::new(|| Address::from_module(MODULE_NAME, "pending-delegation"));
+
+const CONSENSUS_TRANSFER_HANDLER: &str = "consensus.TransferFromRuntime";
+const CONSENSUS_WITHDRAW_HANDLER: &str = "consensus.WithdrawIntoRuntime";
+const CONSENSUS_DELEGATE_HANDLER: &str = "consensus.Delegate";
+const CONSENSUS_UNDELEGATE_HANDLER: &str = "consensus.Undelegate";
+
+impl<Consensus: modules::consensus::API> API for Module<Consensus> {
+ fn deposit<C: Context>(
+ ctx: &C,
+ from: Address,
+ nonce: u64,
+ to: Address,
+ amount: token::BaseUnits,
+ ) -> Result<(), Error> {
+ // XXX: could check consensus state if allowance for the runtime account
+ // exists, but consensus state could be outdated since last block, so
+ // just try to withdraw.
+
+ // Do withdraw from the consensus account and update the account state if
+ // successful.
+ Consensus::withdraw(
+ ctx,
+ from,
+ &amount,
+ MessageEventHookInvocation::new(
+ CONSENSUS_WITHDRAW_HANDLER.to_string(),
+ types::ConsensusWithdrawContext {
+ from,
+ nonce,
+ address: to,
+ amount: amount.clone(),
+ },
+ ),
+ )?;
+
+ Ok(())
+ }
+
+ fn withdraw<C: Context>(
+ ctx: &C,
+ from: Address,
+ nonce: u64,
+ to: Address,
+ amount: token::BaseUnits,
+ ) -> Result<(), Error> {
+ // Transfer out of runtime account and update the account state if successful.
+ Consensus::transfer(
+ ctx,
+ to,
+ &amount,
+ MessageEventHookInvocation::new(
+ CONSENSUS_TRANSFER_HANDLER.to_string(),
+ types::ConsensusTransferContext {
+ to,
+ nonce,
+ address: from,
+ amount: amount.clone(),
+ },
+ ),
+ )?;
+
+ if CurrentState::with_env(|env| env.is_check_only()) {
+ return Ok(());
+ }
+
+ // Transfer the given amount to the module's withdrawal account to make sure the tokens
+ // remain available until actually withdrawn.
+ <C::Runtime as Runtime>::Accounts::transfer(from, *ADDRESS_PENDING_WITHDRAWAL, &amount)
+ .map_err(|_| Error::InsufficientBalance)?;
+
+ Ok(())
+ }
+
+ fn delegate<C: Context>(
+ ctx: &C,
+ from: Address,
+ nonce: u64,
+ to: Address,
+ amount: token::BaseUnits,
+ receipt: bool,
+ ) -> Result<(), Error> {
+ Consensus::escrow(
+ ctx,
+ to,
+ &amount,
+ MessageEventHookInvocation::new(
+ CONSENSUS_DELEGATE_HANDLER.to_string(),
+ types::ConsensusDelegateContext {
+ from,
+ nonce,
+ to,
+ amount: amount.clone(),
+ receipt,
+ },
+ ),
+ )?;
+
+ if CurrentState::with_env(|env| env.is_check_only()) {
+ return Ok(());
+ }
+
+ // Transfer the given amount to the module's delegation account to make sure the tokens
+ // remain available until actually delegated.
+ <C::Runtime as Runtime>::Accounts::transfer(from, *ADDRESS_PENDING_DELEGATION, &amount)
+ .map_err(|_| Error::InsufficientBalance)?;
+
+ Ok(())
+ }
+
+ fn undelegate<C: Context>(
+ ctx: &C,
+ from: Address,
+ nonce: u64,
+ to: Address,
+ shares: u128,
+ receipt: bool,
+ ) -> Result<(), Error> {
+ // Subtract shares from delegation, making sure there are enough there.
+ state::sub_delegation(to, from, shares)?;
+
+ Consensus::reclaim_escrow(
+ ctx,
+ from,
+ shares,
+ MessageEventHookInvocation::new(
+ CONSENSUS_UNDELEGATE_HANDLER.to_string(),
+ types::ConsensusUndelegateContext {
+ from,
+ nonce,
+ to,
+ shares,
+ receipt,
+ },
+ ),
+ )?;
+
+ Ok(())
+ }
+}
+
+#[sdk_derive(Module)]
+impl<Consensus: modules::consensus::API> Module<Consensus> {
+ const NAME: &'static str = MODULE_NAME;
+ const VERSION: u32 = 1;
+ type Error = Error;
+ type Event = Event;
+ type Parameters = Parameters;
+ type Genesis = Genesis;
+
+ #[migration(init)]
+ pub fn init(genesis: Genesis) {
+ // Set genesis parameters.
+ Self::set_params(genesis.parameters);
+ }
+
+ /// Deposit in the runtime.
+ #[handler(call = "consensus.Deposit")]
+ fn tx_deposit<C: Context>(ctx: &C, body: types::Deposit) -> Result<(), Error> {
+ let params = Self::params();
+ <C::Runtime as Runtime>::Core::use_tx_gas(params.gas_costs.tx_deposit)?;
+
+ // Check whether deposit is allowed.
+ if params.disable_deposit {
+ return Err(Error::Forbidden);
+ }
+
+ let signer = CurrentState::with_env(|env| env.tx_auth_info().signer_info[0].clone());
+ Consensus::ensure_compatible_tx_signer()?;
+
+ let address = signer.address_spec.address();
+ let nonce = signer.nonce;
+ Self::deposit(ctx, address, nonce, body.to.unwrap_or(address), body.amount)
+ }
+
+ /// Withdraw from the runtime.
+ #[handler(prefetch = "consensus.Withdraw")]
+ fn prefetch_withdraw(
+ add_prefix: &mut dyn FnMut(Prefix),
+ _body: cbor::Value,
+ auth_info: &AuthInfo,
+ ) -> Result<(), error::RuntimeError> {
+ // Prefetch withdrawing account balance.
+ let addr = auth_info.signer_info[0].address_spec.address();
+ add_prefix(Prefix::from(
+ [
+ modules::accounts::Module::NAME.as_bytes(),
+ modules::accounts::state::BALANCES,
+ addr.as_ref(),
+ ]
+ .concat(),
+ ));
+ Ok(())
+ }
+
+ #[handler(call = "consensus.Withdraw")]
+ fn tx_withdraw<C: Context>(ctx: &C, body: types::Withdraw) -> Result<(), Error> {
+ let params = Self::params();
+ <C::Runtime as Runtime>::Core::use_tx_gas(params.gas_costs.tx_withdraw)?;
+
+ // Check whether withdraw is allowed.
+ if params.disable_withdraw {
+ return Err(Error::Forbidden);
+ }
+
+ // Signer.
+ if body.to.is_none() {
+ // If no `to` field is specified, i.e. withdrawing to the transaction sender's account,
+ // only allow the consensus-compatible single-Ed25519-key signer type. Otherwise, the
+ // tokens would get stuck in an account that you can't sign for on the consensus layer.
+ Consensus::ensure_compatible_tx_signer()?;
+ }
+
+ let signer = CurrentState::with_env(|env| env.tx_auth_info().signer_info[0].clone());
+ let address = signer.address_spec.address();
+ let nonce = signer.nonce;
+ Self::withdraw(ctx, address, nonce, body.to.unwrap_or(address), body.amount)
+ }
+
+ #[handler(call = "consensus.Delegate")]
+ fn tx_delegate<C: Context>(ctx: &C, body: types::Delegate) -> Result<(), Error> {
+ let params = Self::params();
+ <C::Runtime as Runtime>::Core::use_tx_gas(params.gas_costs.tx_delegate)?;
+ let store_receipt = body.receipt > 0;
+ if store_receipt {
+ <C::Runtime as Runtime>::Core::use_tx_gas(params.gas_costs.store_receipt)?;
+ }
+
+ // Check whether delegate is allowed.
+ if params.disable_delegate {
+ return Err(Error::Forbidden);
+ }
+ // Make sure receipts can only be requested internally (e.g. via subcalls).
+ if store_receipt && !CurrentState::with_env(|env| env.is_internal()) {
+ return Err(Error::InvalidArgument);
+ }
+
+ // Signer.
+ let signer = CurrentState::with_env(|env| env.tx_auth_info().signer_info[0].clone());
+ let from = signer.address_spec.address();
+ let nonce = if store_receipt {
+ body.receipt // Use receipt identifier as the nonce.
+ } else {
+ signer.nonce // Use signer nonce as the nonce.
+ };
+ Self::delegate(ctx, from, nonce, body.to, body.amount, store_receipt)
+ }
+
+ #[handler(call = "consensus.Undelegate")]
+ fn tx_undelegate<C: Context>(ctx: &C, body: types::Undelegate) -> Result<(), Error> {
+ let params = Self::params();
+ <C::Runtime as Runtime>::Core::use_tx_gas(params.gas_costs.tx_undelegate)?;
+ let store_receipt = body.receipt > 0;
+ if store_receipt {
+ <C::Runtime as Runtime>::Core::use_tx_gas(params.gas_costs.store_receipt)?;
+ }
+
+ // Check whether undelegate is allowed.
+ if params.disable_undelegate {
+ return Err(Error::Forbidden);
+ }
+ // Make sure receipts can only be requested internally (e.g. via subcalls).
+ if store_receipt && !CurrentState::with_env(|env| env.is_internal()) {
+ return Err(Error::InvalidArgument);
+ }
+
+ // Signer.
+ let signer = CurrentState::with_env(|env| env.tx_auth_info().signer_info[0].clone());
+ let to = signer.address_spec.address();
+ let nonce = if store_receipt {
+ body.receipt // Use receipt identifer as the nonce.
+ } else {
+ signer.nonce // Use signer nonce as the nonce.
+ };
+ Self::undelegate(ctx, body.from, nonce, to, body.shares, store_receipt)
+ }
+
+ #[handler(call = "consensus.TakeReceipt", internal)]
+ fn internal_take_receipt<C: Context>(
+ _ctx: &C,
+ body: types::TakeReceipt,
+ ) -> Result<Option<types::Receipt>, Error> {
+ let params = Self::params();
+ <C::Runtime as Runtime>::Core::use_tx_gas(params.gas_costs.take_receipt)?;
+
+ if !body.kind.is_valid() {
+ return Err(Error::InvalidArgument);
+ }
+
+ Ok(state::take_receipt(
+ CurrentState::with_env(|env| env.tx_caller_address()),
+ body.kind,
+ body.id,
+ ))
+ }
+
+ #[handler(query = "consensus.Balance")]
+ fn query_balance<C: Context>(
+ _ctx: &C,
+ args: types::BalanceQuery,
+ ) -> Result<types::AccountBalance, Error> {
+ let denomination = Consensus::consensus_denomination()?;
+ let balances = <C::Runtime as Runtime>::Accounts::get_balances(args.address)
+ .map_err(|_| Error::InvalidArgument)?;
+ let balance = balances
+ .balances
+ .get(&denomination)
+ .copied()
+ .unwrap_or_default();
+ Ok(types::AccountBalance { balance })
+ }
+
+ #[handler(query = "consensus.Account")]
+ fn query_consensus_account<C: Context>(
+ ctx: &C,
+ args: types::ConsensusAccountQuery,
+ ) -> Result<ConsensusAccount, Error> {
+ Consensus::account(ctx, args.address).map_err(|_| Error::InvalidArgument)
+ }
+
+ #[handler(query = "consensus.Delegation")]
+ fn query_delegation<C: Context>(
+ _ctx: &C,
+ args: types::DelegationQuery,
+ ) -> Result<types::DelegationInfo, Error> {
+ state::get_delegation(args.from, args.to)
+ }
+
+ #[handler(query = "consensus.Delegations")]
+ fn query_delegations<C: Context>(
+ _ctx: &C,
+ args: types::DelegationsQuery,
+ ) -> Result<Vec<types::ExtendedDelegationInfo>, Error> {
+ state::get_delegations(args.from)
+ }
+
+ #[handler(query = "consensus.Undelegations")]
+ fn query_undelegations<C: Context>(
+ _ctx: &C,
+ args: types::UndelegationsQuery,
+ ) -> Result<Vec<types::UndelegationInfo>, Error> {
+ state::get_undelegations(args.to)
+ }
+
+ #[handler(message_result = CONSENSUS_TRANSFER_HANDLER)]
+ fn message_result_transfer<C: Context>(
+ ctx: &C,
+ me: MessageEvent,
+ context: types::ConsensusTransferContext,
+ ) {
+ if !me.is_success() {
+ // Transfer out failed, refund the balance.
+ <C::Runtime as Runtime>::Accounts::transfer(
+ *ADDRESS_PENDING_WITHDRAWAL,
+ context.address,
+ &context.amount,
+ )
+ .expect("should have enough balance");
+
+ // Emit withdraw failed event.
+ CurrentState::with(|state| {
+ state.emit_event(Event::Withdraw {
+ from: context.address,
+ nonce: context.nonce,
+ to: context.to,
+ amount: context.amount.clone(),
+ error: Some(me.into()),
+ });
+ });
+ return;
+ }
+
+ // Burn the withdrawn tokens.
+ <C::Runtime as Runtime>::Accounts::burn(*ADDRESS_PENDING_WITHDRAWAL, &context.amount)
+ .expect("should have enough balance");
+
+ // Emit withdraw successful event.
+ CurrentState::with(|state| {
+ state.emit_event(Event::Withdraw {
+ from: context.address,
+ nonce: context.nonce,
+ to: context.to,
+ amount: context.amount.clone(),
+ error: None,
+ });
+ });
+ }
+
+ #[handler(message_result = CONSENSUS_WITHDRAW_HANDLER)]
+ fn message_result_withdraw<C: Context>(
+ ctx: &C,
+ me: MessageEvent,
+ context: types::ConsensusWithdrawContext,
+ ) {
+ if !me.is_success() {
+ // Transfer in failed, emit deposit failed event.
+ CurrentState::with(|state| {
+ state.emit_event(Event::Deposit {
+ from: context.from,
+ nonce: context.nonce,
+ to: context.address,
+ amount: context.amount.clone(),
+ error: Some(me.into()),
+ });
+ });
+ return;
+ }
+
+ // Update runtime state.
+ <C::Runtime as Runtime>::Accounts::mint(context.address, &context.amount).unwrap();
+
+ // Emit deposit successful event.
+ CurrentState::with(|state| {
+ state.emit_event(Event::Deposit {
+ from: context.from,
+ nonce: context.nonce,
+ to: context.address,
+ amount: context.amount.clone(),
+ error: None,
+ });
+ });
+ }
+
+ #[handler(message_result = CONSENSUS_DELEGATE_HANDLER)]
+ fn message_result_delegate<C: Context>(
+ ctx: &C,
+ me: MessageEvent,
+ context: types::ConsensusDelegateContext,
+ ) {
+ if !me.is_success() {
+ // Delegation failed, refund the balance.
+ <C::Runtime as Runtime>::Accounts::transfer(
+ *ADDRESS_PENDING_DELEGATION,
+ context.from,
+ &context.amount,
+ )
+ .expect("should have enough balance");
+
+ // Store receipt if requested.
+ if context.receipt {
+ state::set_receipt(
+ context.from,
+ types::ReceiptKind::Delegate,
+ context.nonce,
+ types::Receipt {
+ error: Some(me.clone().into()),
+ ..Default::default()
+ },
+ );
+ }
+
+ // Emit delegation failed event.
+ CurrentState::with(|state| {
+ state.emit_event(Event::Delegate {
+ from: context.from,
+ nonce: context.nonce,
+ to: context.to,
+ amount: context.amount,
+ error: Some(me.into()),
+ });
+ });
+ return;
+ }
+
+ // Burn the delegated tokens.
+ <C::Runtime as Runtime>::Accounts::burn(*ADDRESS_PENDING_DELEGATION, &context.amount)
+ .expect("should have enough balance");
+
+ // Record delegation.
+ let result = me
+ .result
+ .expect("event from consensus should have a result");
+ let result: AddEscrowResult = cbor::from_value(result).unwrap();
+ let shares = result.new_shares.try_into().unwrap();
+
+ state::add_delegation(context.from, context.to, shares).unwrap();
+
+ // Store receipt if requested.
+ if context.receipt {
+ state::set_receipt(
+ context.from,
+ types::ReceiptKind::Delegate,
+ context.nonce,
+ types::Receipt {
+ shares,
+ ..Default::default()
+ },
+ );
+ }
+
+ // Emit delegation successful event.
+ CurrentState::with(|state| {
+ state.emit_event(Event::Delegate {
+ from: context.from,
+ nonce: context.nonce,
+ to: context.to,
+ amount: context.amount,
+ error: None,
+ });
+ });
+ }
+
+ #[handler(message_result = CONSENSUS_UNDELEGATE_HANDLER)]
+ fn message_result_undelegate<C: Context>(
+ ctx: &C,
+ me: MessageEvent,
+ context: types::ConsensusUndelegateContext,
+ ) {
+ if !me.is_success() {
+ // Undelegation failed, add shares back.
+ state::add_delegation(context.to, context.from, context.shares).unwrap();
+
+ // Store receipt if requested.
+ if context.receipt {
+ state::set_receipt(
+ context.to,
+ types::ReceiptKind::UndelegateStart,
+ context.nonce,
+ types::Receipt {
+ error: Some(me.clone().into()),
+ ..Default::default()
+ },
+ );
+ }
+
+ // Emit undelegation failed event.
+ CurrentState::with(|state| {
+ state.emit_event(Event::UndelegateStart {
+ from: context.from,
+ nonce: context.nonce,
+ to: context.to,
+ shares: context.shares,
+ debond_end_time: EPOCH_INVALID,
+ error: Some(me.into()),
+ });
+ });
+ return;
+ }
+
+ // Queue undelegation processing at the debond end epoch. Further processing will happen in
+ // the end block handler.
+ let result = me
+ .result
+ .expect("event from consensus should have a result");
+ let result: ReclaimEscrowResult = cbor::from_value(result).unwrap();
+ let debonding_shares = result.debonding_shares.try_into().unwrap();
+
+ let receipt = if context.receipt {
+ context.nonce
+ } else {
+ 0 // No receipt needed for UndelegateEnd.
+ };
+
+ let done_receipt = state::add_undelegation(
+ context.from,
+ context.to,
+ result.debond_end_time,
+ debonding_shares,
+ receipt,
+ )
+ .unwrap();
+
+ // Store receipt if requested.
+ if context.receipt {
+ state::set_receipt(
+ context.to,
+ types::ReceiptKind::UndelegateStart,
+ context.nonce,
+ types::Receipt {
+ epoch: result.debond_end_time,
+ receipt: done_receipt,
+ ..Default::default()
+ },
+ );
+ }
+
+ // Emit undelegation started event.
+ CurrentState::with(|state| {
+ state.emit_event(Event::UndelegateStart {
+ from: context.from,
+ nonce: context.nonce,
+ to: context.to,
+ shares: context.shares,
+ debond_end_time: result.debond_end_time,
+ error: None,
+ });
+ });
+ }
+}
+
+impl<Consensus: modules::consensus::API> module::TransactionHandler for Module<Consensus> {}
+
+impl<Consensus: modules::consensus::API> module::BlockHandler for Module<Consensus> {
+ fn end_block<C: Context>(ctx: &C) {
+ // Only do work in case the epoch has changed since the last processed block.
+ if !<C::Runtime as Runtime>::Core::has_epoch_changed() {
+ return;
+ }
+
+ let logger = ctx.get_logger("consensus_accounts");
+ slog::debug!(logger, "epoch changed, processing queued undelegations";
+ "epoch" => ctx.epoch(),
+ );
+
+ let mut reclaims: lru::LruCache<(EpochTime, Address), (u128, u128)> =
+ lru::LruCache::new(NonZeroUsize::new(128).unwrap());
+
+ let own_address = Address::from_runtime_id(ctx.runtime_id());
+ let denomination = Consensus::consensus_denomination().unwrap();
+ let qd = state::get_queued_undelegations(ctx.epoch()).unwrap();
+ for ud in qd {
+ let udi = state::take_undelegation(&ud).unwrap();
+
+ slog::debug!(logger, "processing undelegation";
+ "shares" => udi.shares,
+ );
+
+ // Determine total amount the runtime got during the reclaim operation.
+ let (total_amount, total_shares) =
+ if let Some(totals) = reclaims.get(&(ud.epoch, ud.from)) {
+ *totals
+ } else {
+ // Fetch consensus height corresponding to the given epoch transition. This
+ // query may be expensive in case the epoch is far back, but the node is
+ // guaranteed to have it as it was the state after the last normal round
+ // (otherwise we would have already processed this epoch).
+ let height = Consensus::height_for_epoch(ctx, ud.epoch)
+ .expect("failed to determine height for epoch");
+
+ // Find the relevant reclaim escrow event.
+ //
+ // There will always be exactly one matching reclaim escrow event here, because
+ // debonding delegations get merged at the consensus layer when there are
+ // multiple reclaims for the same accounts on the same epoch.
+ let totals = ctx
+ .history()
+ .consensus_events_at(height, EventKind::Staking)
+ .expect("failed to fetch historic events")
+ .iter()
+ .find_map(|ev| match ev {
+ consensus::Event::Staking(staking::Event {
+ escrow:
+ Some(staking::EscrowEvent::Reclaim {
+ owner,
+ escrow,
+ amount,
+ shares,
+ }),
+ ..
+ }) if owner == &own_address.into() && escrow == &ud.from.into() => {
+ Some((amount.try_into().unwrap(), shares.try_into().unwrap()))
+ }
+ _ => None,
+ })
+ .expect("reclaim event should have been emitted");
+
+ reclaims.put((ud.epoch, ud.from), totals);
+ totals
+ };
+
+ // Compute proportion of received amount (shares * total_amount / total_shares).
+ let amount = udi
+ .shares
+ .checked_mul(total_amount)
+ .expect("shares * total_amount should not overflow")
+ .checked_div(total_shares)
+ .expect("total_shares should not be zero");
+ let raw_amount = Consensus::amount_from_consensus(ctx, amount).unwrap();
+ let amount = token::BaseUnits::new(raw_amount, denomination.clone());
+
+ // Mint the given number of tokens.
+ <C::Runtime as Runtime>::Accounts::mint(ud.to, &amount).unwrap();
+
+ // Store receipt if requested.
+ if udi.receipt > 0 {
+ state::set_receipt(
+ ud.to,
+ types::ReceiptKind::UndelegateDone,
+ udi.receipt,
+ types::Receipt {
+ amount: raw_amount,
+ ..Default::default()
+ },
+ );
+ }
+
+ // Emit undelegation done event.
+ CurrentState::with(|state| {
+ state.emit_event(Event::UndelegateDone {
+ from: ud.from,
+ to: ud.to,
+ shares: udi.shares,
+ amount,
+ });
+ });
+ }
+ }
+}
+
+impl<Consensus: modules::consensus::API> module::InvariantHandler for Module<Consensus> {
+ /// Check invariants.
+ fn check_invariants<C: Context>(ctx: &C) -> Result<(), CoreError> {
+ // Total supply of the designated consensus layer token denomination
+ // should be less than or equal to the balance of the runtime's general
+ // account in the consensus layer.
+
+ let den = Consensus::consensus_denomination().unwrap();
+ #[allow(clippy::or_fun_call)]
+ let ts = <C::Runtime as Runtime>::Accounts::get_total_supplies().or(Err(
+ CoreError::InvariantViolation("unable to get total supplies".to_string()),
+ ))?;
+
+ let rt_addr = Address::from_runtime_id(ctx.runtime_id());
+ let rt_acct = Consensus::account(ctx, rt_addr).unwrap_or_default();
+ let rt_ga_balance = rt_acct.general.balance;
+ let rt_ga_balance: u128 = rt_ga_balance.try_into().unwrap_or(u128::MAX);
+
+ let rt_ga_balance = Consensus::amount_from_consensus(ctx, rt_ga_balance).map_err(|_| {
+ CoreError::InvariantViolation(
+ "runtime's consensus balance is not representable".to_string(),
+ )
+ })?;
+
+ if let Some(total_supply) = ts.get(&den) {
+ if total_supply > &rt_ga_balance {
+ return Err(CoreError::InvariantViolation(
+ format!("total supply ({total_supply}) is greater than runtime's general account balance ({rt_ga_balance})"),
+ ));
+ }
+ }
+
+ // Check that the number of shares the runtime has escrowed in consensus is >= what is in
+ // its internally tracked delegation state.
+
+ let delegations = state::get_delegations_by_destination()
+ .map_err(|_| CoreError::InvariantViolation("unable to get delegations".to_string()))?;
+
+ for (to, shares) in delegations {
+ let cons_shares = Consensus::delegation(ctx, rt_addr, to)
+ .map_err(|err| {
+ CoreError::InvariantViolation(format!(
+ "unable to fetch consensus delegation {rt_addr} -> {to}: {err}"
+ ))
+ })?
+ .shares;
+
+ if cons_shares < shares.into() {
+ return Err(CoreError::InvariantViolation(format!(
+ "runtime does not have enough shares delegated to {to} (expected: {shares} got: {cons_shares}"
+ )));
+ }
+ }
+
+ Ok(())
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +
//! State schema.
+use std::{
+ collections::BTreeMap,
+ convert::{TryFrom, TryInto},
+};
+
+use oasis_core_runtime::consensus::beacon::EpochTime;
+
+use crate::{
+ state::CurrentState,
+ storage::{self, Store},
+ types::address::Address,
+};
+
+use super::{types, Error, MODULE_NAME};
+
+/// Map of active delegations.
+pub const DELEGATIONS: &[u8] = &[0x01];
+/// Map of undelegations.
+pub const UNDELEGATIONS: &[u8] = &[0x02];
+/// An undelegation queue.
+pub const UNDELEGATION_QUEUE: &[u8] = &[0x03];
+/// Receipts.
+pub const RECEIPTS: &[u8] = &[0x04];
+
+/// Add delegation for a given (from, to) pair.
+///
+/// The given shares are added to any existing delegation that may exist for the same (from, to)
+/// address pair. If no delegation exists a new one is created.
+pub fn add_delegation(from: Address, to: Address, shares: u128) -> Result<(), Error> {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let delegations = storage::PrefixStore::new(store, &DELEGATIONS);
+ let mut account = storage::TypedStore::new(storage::PrefixStore::new(delegations, &from));
+ let mut di: types::DelegationInfo = account.get(to).unwrap_or_default();
+
+ di.shares = di
+ .shares
+ .checked_add(shares)
+ .ok_or(Error::InvalidArgument)?;
+
+ account.insert(to, di);
+
+ Ok(())
+ })
+}
+
+/// Subtract delegation from a given (from, to) pair.
+pub fn sub_delegation(from: Address, to: Address, shares: u128) -> Result<(), Error> {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let delegations = storage::PrefixStore::new(store, &DELEGATIONS);
+ let mut account = storage::TypedStore::new(storage::PrefixStore::new(delegations, &from));
+ let mut di: types::DelegationInfo = account.get(to).unwrap_or_default();
+
+ di.shares = di
+ .shares
+ .checked_sub(shares)
+ .ok_or(Error::InsufficientBalance)?;
+
+ if di.shares > 0 {
+ account.insert(to, di);
+ } else {
+ account.remove(to);
+ }
+
+ Ok(())
+ })
+}
+
+/// Retrieve delegation metadata for a given (from, to) pair.
+///
+/// In case no delegation exists for the given (from, to) address pair, an all-zero delegation
+/// metadata are returned.
+pub fn get_delegation(from: Address, to: Address) -> Result<types::DelegationInfo, Error> {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let delegations = storage::PrefixStore::new(store, &DELEGATIONS);
+ let account = storage::TypedStore::new(storage::PrefixStore::new(delegations, &from));
+ Ok(account.get(to).unwrap_or_default())
+ })
+}
+
+/// Retrieve all delegation metadata originating from a given address.
+pub fn get_delegations(from: Address) -> Result<Vec<types::ExtendedDelegationInfo>, Error> {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let delegations = storage::PrefixStore::new(store, &DELEGATIONS);
+ let account = storage::TypedStore::new(storage::PrefixStore::new(delegations, &from));
+
+ Ok(account
+ .iter()
+ .map(
+ |(to, di): (Address, types::DelegationInfo)| -> types::ExtendedDelegationInfo {
+ types::ExtendedDelegationInfo {
+ to,
+ shares: di.shares,
+ }
+ },
+ )
+ .collect())
+ })
+}
+
+/// This is needed to properly iterate over the DELEGATIONS map.
+#[derive(Clone, PartialEq, PartialOrd, Eq, Ord)]
+struct AddressPair(Address, Address);
+
+#[derive(Error, Debug)]
+enum APError {
+ #[error("malformed address")]
+ MalformedAddress,
+}
+
+impl TryFrom<&[u8]> for AddressPair {
+ type Error = APError;
+
+ fn try_from(bytes: &[u8]) -> Result<Self, Self::Error> {
+ let a =
+ Address::try_from(&bytes[..Address::SIZE]).map_err(|_| APError::MalformedAddress)?;
+ let b =
+ Address::try_from(&bytes[Address::SIZE..]).map_err(|_| APError::MalformedAddress)?;
+ Ok(AddressPair(a, b))
+ }
+}
+
+/// Return the number of delegated shares for each destination escrow account.
+pub fn get_delegations_by_destination() -> Result<BTreeMap<Address, u128>, Error> {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let delegations = storage::TypedStore::new(storage::PrefixStore::new(store, &DELEGATIONS));
+
+ let mut by_destination: BTreeMap<Address, u128> = BTreeMap::new();
+ for (ap, di) in delegations.iter::<AddressPair, types::DelegationInfo>() {
+ let total = by_destination.entry(ap.1).or_default();
+ *total = total.checked_add(di.shares).ok_or(Error::InvalidArgument)?;
+ }
+
+ Ok(by_destination)
+ })
+}
+
+/// Record new undelegation and add to undelegation queue.
+///
+/// In case an undelegation for the given (from, to, epoch) tuple already exists, the undelegation
+/// entry is merged by adding shares. When a non-zero receipt identifier is passed, the identifier
+/// is set in case the existing entry has no such identifier yet.
+///
+/// It returns the receipt identifier of the undelegation done receipt.
+pub fn add_undelegation(
+ from: Address,
+ to: Address,
+ epoch: EpochTime,
+ shares: u128,
+ receipt: u64,
+) -> Result<u64, Error> {
+ CurrentState::with_store(|mut root_store| {
+ let store = storage::PrefixStore::new(&mut root_store, &MODULE_NAME);
+ let undelegations = storage::PrefixStore::new(store, &UNDELEGATIONS);
+ let account = storage::PrefixStore::new(undelegations, &to);
+ let mut entry = storage::TypedStore::new(storage::PrefixStore::new(account, &from));
+ let mut di: types::DelegationInfo = entry.get(epoch.to_storage_key()).unwrap_or_default();
+
+ if receipt > 0 && di.receipt == 0 {
+ di.receipt = receipt;
+ }
+ let done_receipt = di.receipt;
+
+ di.shares = di
+ .shares
+ .checked_add(shares)
+ .ok_or(Error::InvalidArgument)?;
+
+ entry.insert(epoch.to_storage_key(), di);
+
+ // Add to undelegation queue (if existing item is there, this will have no effect).
+ let store = storage::PrefixStore::new(root_store, &MODULE_NAME);
+ let mut queue = storage::PrefixStore::new(store, &UNDELEGATION_QUEUE);
+ queue.insert(
+ &queue_entry_key(from, to, epoch),
+ &[0xF6], /* CBOR NULL */
+ );
+
+ Ok(done_receipt)
+ })
+}
+
+fn queue_entry_key(from: Address, to: Address, epoch: EpochTime) -> Vec<u8> {
+ [&epoch.to_storage_key(), to.as_ref(), from.as_ref()].concat()
+}
+
+/// Remove an existing undelegation and return it.
+///
+/// In case the undelegation doesn't exist, returns a default-constructed DelegationInfo.
+pub fn take_undelegation(ud: &Undelegation) -> Result<types::DelegationInfo, Error> {
+ CurrentState::with_store(|mut root_store| {
+ // Get and remove undelegation metadata.
+ let store = storage::PrefixStore::new(&mut root_store, &MODULE_NAME);
+ let undelegations = storage::PrefixStore::new(store, &UNDELEGATIONS);
+ let account = storage::PrefixStore::new(undelegations, &ud.to);
+ let mut entry = storage::TypedStore::new(storage::PrefixStore::new(account, &ud.from));
+ let di: types::DelegationInfo = entry.get(ud.epoch.to_storage_key()).unwrap_or_default();
+ entry.remove(ud.epoch.to_storage_key());
+
+ // Remove queue entry.
+ let store = storage::PrefixStore::new(root_store, &MODULE_NAME);
+ let mut queue = storage::PrefixStore::new(store, &UNDELEGATION_QUEUE);
+ queue.remove(&queue_entry_key(ud.from, ud.to, ud.epoch));
+
+ Ok(di)
+ })
+}
+
+struct AddressWithEpoch {
+ from: Address,
+ epoch: EpochTime,
+}
+
+impl TryFrom<&[u8]> for AddressWithEpoch {
+ type Error = anyhow::Error;
+
+ fn try_from(value: &[u8]) -> Result<Self, Self::Error> {
+ if value.len() != Address::SIZE + 8 {
+ anyhow::bail!("incorrect address with epoch key size");
+ }
+
+ Ok(Self {
+ from: Address::try_from(&value[..Address::SIZE])?,
+ epoch: EpochTime::from_be_bytes(value[Address::SIZE..].try_into()?),
+ })
+ }
+}
+
+/// Retrieve all undelegation metadata to a given address.
+pub fn get_undelegations(to: Address) -> Result<Vec<types::UndelegationInfo>, Error> {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let undelegations = storage::PrefixStore::new(store, &UNDELEGATIONS);
+ let account = storage::TypedStore::new(storage::PrefixStore::new(undelegations, &to));
+
+ Ok(account
+ .iter()
+ .map(
+ |(ae, di): (AddressWithEpoch, types::DelegationInfo)| -> types::UndelegationInfo {
+ types::UndelegationInfo {
+ from: ae.from,
+ epoch: ae.epoch,
+ shares: di.shares,
+ }
+ },
+ )
+ .collect())
+ })
+}
+
+/// Undelegation metadata.
+pub struct Undelegation {
+ pub from: Address,
+ pub to: Address,
+ pub epoch: EpochTime,
+}
+
+impl<'a> TryFrom<&'a [u8]> for Undelegation {
+ type Error = anyhow::Error;
+
+ fn try_from(value: &'a [u8]) -> Result<Self, Self::Error> {
+ // Decode a storage key of the format (epoch, to, from).
+ if value.len() != 2 * Address::SIZE + 8 {
+ anyhow::bail!("incorrect undelegation key size");
+ }
+
+ Ok(Self {
+ epoch: EpochTime::from_be_bytes(value[..8].try_into()?),
+ to: Address::from_bytes(&value[8..8 + Address::SIZE])?,
+ from: Address::from_bytes(&value[8 + Address::SIZE..])?,
+ })
+ }
+}
+
+/// Retrieve all queued undelegations for epochs earlier than or equal to the passed epoch.
+pub fn get_queued_undelegations(epoch: EpochTime) -> Result<Vec<Undelegation>, Error> {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let queue = storage::TypedStore::new(storage::PrefixStore::new(store, &UNDELEGATION_QUEUE));
+
+ Ok(queue
+ .iter()
+ .map(|(k, _): (Undelegation, ())| k)
+ .take_while(|ud| ud.epoch <= epoch)
+ .collect())
+ })
+}
+
+/// Store the given receipt.
+pub fn set_receipt(owner: Address, kind: types::ReceiptKind, id: u64, receipt: types::Receipt) {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let receipts = storage::PrefixStore::new(store, &RECEIPTS);
+ let of_owner = storage::PrefixStore::new(receipts, &owner);
+ let kind = [kind as u8];
+ let mut of_kind = storage::TypedStore::new(storage::PrefixStore::new(of_owner, &kind));
+
+ of_kind.insert(id.to_be_bytes(), receipt);
+ });
+}
+
+/// Remove the given receipt from storage if it exists and return it, otherwise return `None`.
+pub fn take_receipt(owner: Address, kind: types::ReceiptKind, id: u64) -> Option<types::Receipt> {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let receipts = storage::PrefixStore::new(store, &RECEIPTS);
+ let of_owner = storage::PrefixStore::new(receipts, &owner);
+ let kind = [kind as u8];
+ let mut of_kind = storage::TypedStore::new(storage::PrefixStore::new(of_owner, &kind));
+
+ let receipt = of_kind.get(id.to_be_bytes());
+ of_kind.remove(id.to_be_bytes());
+
+ receipt
+ })
+}
+
+/// A trait that exists solely to convert `beacon::EpochTime` to bytes for use as a storage key.
+trait ToStorageKey {
+ fn to_storage_key(&self) -> [u8; 8];
+}
+
+impl ToStorageKey for EpochTime {
+ fn to_storage_key(&self) -> [u8; 8] {
+ self.to_be_bytes()
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+ use crate::testing::{keys, mock};
+
+ #[test]
+ fn test_delegation() {
+ let _mock = mock::Mock::default();
+
+ add_delegation(keys::alice::address(), keys::bob::address(), 500).unwrap();
+ add_delegation(keys::alice::address(), keys::bob::address(), 500).unwrap();
+
+ let di = get_delegation(keys::bob::address(), keys::alice::address()).unwrap();
+ assert_eq!(di.shares, 0);
+ let di = get_delegation(keys::alice::address(), keys::bob::address()).unwrap();
+ assert_eq!(di.shares, 1000);
+
+ let dis = get_delegations(keys::bob::address()).unwrap();
+ assert!(dis.is_empty());
+ let dis = get_delegations(keys::alice::address()).unwrap();
+ assert_eq!(dis.len(), 1);
+ assert_eq!(dis[0].shares, 1000);
+
+ let totals = get_delegations_by_destination().unwrap();
+ assert_eq!(totals.len(), 1);
+ assert_eq!(totals[&keys::bob::address()], 1000);
+
+ sub_delegation(keys::alice::address(), keys::bob::address(), 100).unwrap();
+
+ let di = get_delegation(keys::alice::address(), keys::bob::address()).unwrap();
+ assert_eq!(di.shares, 900);
+
+ let totals = get_delegations_by_destination().unwrap();
+ assert_eq!(totals.len(), 1);
+ assert_eq!(totals[&keys::bob::address()], 900);
+
+ add_delegation(keys::bob::address(), keys::bob::address(), 200).unwrap();
+
+ let totals = get_delegations_by_destination().unwrap();
+ assert_eq!(totals.len(), 1);
+ assert_eq!(totals[&keys::bob::address()], 1100);
+
+ add_delegation(keys::bob::address(), keys::alice::address(), 100).unwrap();
+
+ let totals = get_delegations_by_destination().unwrap();
+ assert_eq!(totals.len(), 2);
+ assert_eq!(totals[&keys::alice::address()], 100);
+ assert_eq!(totals[&keys::bob::address()], 1100);
+ }
+
+ #[test]
+ fn test_undelegation() {
+ let _mock = mock::Mock::default();
+
+ add_undelegation(keys::alice::address(), keys::bob::address(), 42, 500, 12).unwrap();
+ add_undelegation(keys::alice::address(), keys::bob::address(), 42, 500, 24).unwrap();
+ add_undelegation(keys::alice::address(), keys::bob::address(), 84, 200, 36).unwrap();
+
+ let qd = get_queued_undelegations(10).unwrap();
+ assert!(qd.is_empty());
+ let qd = get_queued_undelegations(42).unwrap();
+ assert_eq!(qd.len(), 1);
+ assert_eq!(qd[0].from, keys::alice::address());
+ assert_eq!(qd[0].to, keys::bob::address());
+ assert_eq!(qd[0].epoch, 42);
+ let qd = get_queued_undelegations(43).unwrap();
+ assert_eq!(qd.len(), 1);
+ assert_eq!(qd[0].from, keys::alice::address());
+ assert_eq!(qd[0].to, keys::bob::address());
+ assert_eq!(qd[0].epoch, 42);
+
+ let udis = get_undelegations(keys::alice::address()).unwrap();
+ assert!(udis.is_empty());
+ let udis = get_undelegations(keys::bob::address()).unwrap();
+ assert_eq!(udis.len(), 2);
+ assert_eq!(udis[0].from, keys::alice::address());
+ assert_eq!(udis[0].shares, 1000);
+ assert_eq!(udis[0].epoch, 42);
+ assert_eq!(udis[1].from, keys::alice::address());
+ assert_eq!(udis[1].shares, 200);
+ assert_eq!(udis[1].epoch, 84);
+
+ let di = take_undelegation(&qd[0]).unwrap();
+ assert_eq!(di.shares, 1000);
+ assert_eq!(di.receipt, 12, "receipt id should not be overwritten");
+
+ let qd = get_queued_undelegations(42).unwrap();
+ assert!(qd.is_empty());
+
+ let udis = get_undelegations(keys::bob::address()).unwrap();
+ assert_eq!(udis.len(), 1);
+ }
+
+ #[test]
+ fn test_receipts() {
+ let _mock = mock::Mock::default();
+
+ let receipt = types::Receipt {
+ shares: 123,
+ ..Default::default()
+ };
+ set_receipt(
+ keys::alice::address(),
+ types::ReceiptKind::Delegate,
+ 42,
+ receipt.clone(),
+ );
+
+ let dec_receipt = take_receipt(keys::alice::address(), types::ReceiptKind::Delegate, 10);
+ assert!(dec_receipt.is_none(), "missing receipt should return None");
+
+ let dec_receipt = take_receipt(
+ keys::alice::address(),
+ types::ReceiptKind::UndelegateStart,
+ 42,
+ );
+ assert!(dec_receipt.is_none(), "missing receipt should return None");
+
+ let dec_receipt = take_receipt(
+ keys::alice::address(),
+ types::ReceiptKind::UndelegateDone,
+ 42,
+ );
+ assert!(dec_receipt.is_none(), "missing receipt should return None");
+
+ let dec_receipt = take_receipt(keys::alice::address(), types::ReceiptKind::Delegate, 42);
+ assert_eq!(dec_receipt, Some(receipt), "receipt should be correct");
+
+ let dec_receipt = take_receipt(keys::alice::address(), types::ReceiptKind::Delegate, 42);
+ assert!(dec_receipt.is_none(), "receipt should have been removed");
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +
//! Consensus module types.
+use oasis_core_runtime::consensus::beacon::EpochTime;
+
+use crate::types::{address::Address, message::MessageEvent, token};
+
+/// Deposit into runtime call.
+/// Transfer from consensus staking to an account in this runtime.
+/// The transaction signer has a consensus layer allowance benefiting this runtime's staking
+/// address. The `to` address runtime account gets the tokens.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Deposit {
+ #[cbor(optional)]
+ pub to: Option<Address>,
+ pub amount: token::BaseUnits,
+}
+
+/// Withdraw from runtime call.
+/// Transfer from an account in this runtime to consensus staking.
+/// The `to` address consensus staking account gets the tokens.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Withdraw {
+ #[cbor(optional)]
+ pub to: Option<Address>,
+ pub amount: token::BaseUnits,
+}
+
+/// Delegate from runtime call.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Delegate {
+ pub to: Address,
+ pub amount: token::BaseUnits,
+ #[cbor(optional)]
+ pub receipt: u64,
+}
+
+/// Undelegate into runtime call.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Undelegate {
+ pub from: Address,
+ pub shares: u128,
+ #[cbor(optional)]
+ pub receipt: u64,
+}
+
+/// Kind of receipt.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+#[cfg_attr(test, derive(PartialEq, Eq))]
+#[repr(u8)]
+pub enum ReceiptKind {
+ #[default]
+ Invalid = 0,
+ Delegate = 1,
+ UndelegateStart = 2,
+ UndelegateDone = 3,
+}
+
+impl ReceiptKind {
+ /// Whether the receipt kind is valid.
+ pub fn is_valid(&self) -> bool {
+ !matches!(self, Self::Invalid)
+ }
+}
+
+/// Take receipt internal runtime call.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct TakeReceipt {
+ pub kind: ReceiptKind,
+ pub id: u64,
+}
+
+/// A receipt.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+#[cfg_attr(test, derive(PartialEq, Eq))]
+pub struct Receipt {
+ /// Shares received (for delegations).
+ #[cbor(optional)]
+ pub shares: u128,
+
+ /// Undelegate end epoch.
+ #[cbor(optional)]
+ pub epoch: EpochTime,
+
+ /// Undelegate end receipt.
+ #[cbor(optional)]
+ pub receipt: u64,
+
+ /// Amount of tokens received.
+ #[cbor(optional)]
+ pub amount: u128,
+
+ /// Consensus layer error.
+ #[cbor(optional)]
+ pub error: Option<ConsensusError>,
+}
+
+/// Balance query.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct BalanceQuery {
+ pub address: Address,
+}
+
+/// Consensus account query.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct ConsensusAccountQuery {
+ pub address: Address,
+}
+
+/// Delegation query.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct DelegationQuery {
+ pub from: Address,
+ pub to: Address,
+}
+
+/// Delegations query.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct DelegationsQuery {
+ pub from: Address,
+}
+
+/// Undelegations query.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct UndelegationsQuery {
+ pub to: Address,
+}
+
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct AccountBalance {
+ pub balance: u128,
+}
+
+/// Information about a delegation.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct DelegationInfo {
+ /// The amount of owned shares.
+ pub shares: u128,
+
+ /// Receipt identifier for this undelegation.
+ #[cbor(optional)]
+ pub receipt: u64,
+}
+
+/// Extended information about a delegation.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct ExtendedDelegationInfo {
+ /// Address delegated to.
+ pub to: Address,
+ /// The amount of owned shares.
+ pub shares: u128,
+}
+
+/// Information about an undelegation.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct UndelegationInfo {
+ /// Address being undelegated from.
+ pub from: Address,
+ /// Epoch when the undelegation will be complete.
+ pub epoch: EpochTime,
+ /// The amount of undelegated shares.
+ pub shares: u128,
+}
+
+/// Context for consensus transfer message handler.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct ConsensusTransferContext {
+ pub address: Address,
+ #[cbor(optional)]
+ pub nonce: u64,
+ #[cbor(optional)]
+ pub to: Address,
+ pub amount: token::BaseUnits,
+}
+
+/// Context for consensus withdraw message handler.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct ConsensusWithdrawContext {
+ #[cbor(optional)]
+ pub from: Address,
+ #[cbor(optional)]
+ pub nonce: u64,
+ pub address: Address,
+ pub amount: token::BaseUnits,
+}
+
+/// Context for consensus delegate message handler.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode, Default)]
+pub struct ConsensusDelegateContext {
+ pub from: Address,
+ pub nonce: u64,
+ pub to: Address,
+ pub amount: token::BaseUnits,
+ #[cbor(optional)]
+ pub receipt: bool,
+}
+
+/// Context for consensus undelegate message handler.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode, Default)]
+pub struct ConsensusUndelegateContext {
+ pub from: Address,
+ pub nonce: u64,
+ pub to: Address,
+ pub shares: u128,
+ #[cbor(optional)]
+ pub receipt: bool,
+}
+
+/// Error details from the consensus layer.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct ConsensusError {
+ #[cbor(optional)]
+ pub module: String,
+
+ #[cbor(optional)]
+ pub code: u32,
+}
+
+impl From<MessageEvent> for ConsensusError {
+ fn from(me: MessageEvent) -> Self {
+ Self {
+ module: me.module,
+ code: me.code,
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +765 +766 +767 +768 +769 +770 +771 +772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805 +806 +807 +808 +809 +810 +811 +812 +813 +814 +815 +816 +817 +818 +819 +820 +821 +822 +823 +824 +825 +826 +827 +828 +829 +830 +831 +832 +833 +834 +835 +836 +837 +838 +839 +840 +841 +842 +843 +844 +845 +846 +847 +848 +849 +850 +851 +852 +853 +854 +855 +856 +857 +858 +859 +860 +861 +862 +863 +864 +865 +866 +867 +868 +869 +870 +871 +872 +873 +874 +875 +876 +877 +878 +879 +880 +881 +882 +883 +884 +885 +886 +887 +888 +889 +890 +891 +892 +893 +894 +895 +896 +897 +898 +899 +900 +901 +902 +903 +904 +905 +906 +907 +908 +909 +910 +911 +912 +913 +914 +915 +916 +917 +918 +919 +920 +921 +922 +923 +924 +925 +926 +927 +928 +929 +930 +931 +932 +933 +934 +935 +936 +937 +938 +939 +940 +941 +942 +943 +944 +945 +946 +947 +948 +949 +950 +951 +952 +953 +954 +955 +956 +957 +958 +959 +960 +961 +962 +963 +964 +965 +966 +967 +968 +969 +970 +971 +972 +973 +974 +975 +976 +977 +978 +979 +980 +981 +982 +983 +984 +985 +986 +987 +988 +989 +990 +991 +992 +993 +994 +995 +996 +997 +998 +999 +1000 +1001 +1002 +1003 +1004 +1005 +1006 +1007 +1008 +1009 +1010 +1011 +1012 +1013 +1014 +1015 +1016 +1017 +1018 +1019 +1020 +1021 +1022 +1023 +1024 +1025 +1026 +1027 +1028 +1029 +1030 +1031 +1032 +1033 +1034 +1035 +1036 +1037 +1038 +1039 +1040 +1041 +1042 +1043 +1044 +1045 +1046 +1047 +1048 +1049 +1050 +1051 +1052 +1053 +1054 +1055 +1056 +1057 +1058 +1059 +1060 +1061 +1062 +1063 +1064 +1065 +1066 +1067 +1068 +1069 +1070 +1071 +1072 +1073 +1074 +1075 +1076 +1077 +1078 +1079 +1080 +1081 +1082 +1083 +1084 +1085 +1086 +1087 +1088 +1089 +1090 +1091 +1092 +1093 +1094 +1095 +1096 +1097 +1098 +1099 +1100 +1101 +1102 +1103 +1104 +1105 +1106 +1107 +1108 +1109 +1110 +1111 +1112 +1113 +1114 +1115 +1116 +1117 +1118 +1119 +1120 +1121 +1122 +1123 +1124 +1125 +1126 +1127 +1128 +1129 +1130 +1131 +1132 +1133 +1134 +1135 +1136 +1137 +1138 +1139 +1140 +1141 +1142 +1143 +1144 +1145 +1146 +1147 +1148 +1149 +1150 +1151 +1152 +1153 +1154 +1155 +1156 +1157 +1158 +1159 +1160 +1161 +1162 +1163 +1164 +1165 +1166 +1167 +1168 +1169 +1170 +1171 +1172 +1173 +1174 +1175 +1176 +1177 +1178 +1179 +1180 +1181 +1182 +1183 +1184 +1185 +1186 +1187 +1188 +1189 +1190 +1191 +1192 +1193 +1194 +1195 +1196 +1197 +1198 +1199 +1200 +1201 +1202 +1203 +1204 +1205 +1206 +1207 +1208 +1209 +1210 +1211 +1212 +1213 +1214 +1215 +1216 +1217 +1218 +1219 +1220 +1221 +1222 +1223 +1224 +1225 +1226 +1227 +1228 +1229 +1230 +1231 +1232 +1233 +1234 +1235 +1236 +1237 +1238 +1239 +1240 +1241 +1242 +1243 +1244 +1245 +1246 +1247 +1248 +1249 +1250 +1251 +1252 +1253 +1254 +1255 +1256 +1257 +1258 +1259 +1260 +1261 +1262 +1263 +1264 +1265 +1266 +1267 +1268 +1269 +1270 +1271 +1272 +1273 +1274 +1275 +1276 +1277 +1278 +1279 +1280 +1281 +1282 +1283 +1284 +1285 +1286 +1287 +1288 +1289 +1290 +1291 +1292 +1293 +1294 +1295 +1296 +1297 +1298 +1299 +1300 +1301 +1302 +1303 +1304 +1305 +1306 +1307 +1308 +1309 +1310 +1311 +1312 +1313 +1314 +1315 +1316 +1317 +1318 +1319 +1320 +1321 +1322 +1323 +1324 +1325 +1326 +1327 +1328 +1329 +1330 +1331 +1332 +1333 +1334 +1335 +1336 +
//! Core definitions module.
+use std::{
+ collections::{BTreeMap, BTreeSet},
+ convert::{TryFrom, TryInto},
+ fmt::Display,
+};
+
+use anyhow::anyhow;
+use oasis_runtime_sdk_macros::{handler, sdk_derive};
+use thiserror::Error;
+
+use crate::{
+ callformat,
+ context::Context,
+ core::consensus::beacon::EpochTime,
+ dispatcher,
+ error::Error as SDKError,
+ keymanager, migration,
+ module::{
+ self, CallResult, InvariantHandler as _, MethodHandler as _, Module as _,
+ ModuleInfoHandler as _,
+ },
+ sender::SenderMeta,
+ state::{CurrentState, Mode, Options, TransactionWithMeta},
+ storage::{self},
+ types::{
+ token::{self, Denomination},
+ transaction::{
+ self, AddressSpec, AuthProof, Call, CallFormat, CallerAddress, SignerInfo, Transaction,
+ UnverifiedTransaction,
+ },
+ },
+ Runtime,
+};
+
+use self::types::RuntimeInfoResponse;
+
+#[cfg(test)]
+mod test;
+pub mod types;
+
+/// Unique module name.
+pub const MODULE_NAME: &str = "core";
+
+/// Errors emitted by the core module.
+#[derive(Error, Debug, oasis_runtime_sdk_macros::Error)]
+pub enum Error {
+ #[error("malformed transaction: {0}")]
+ #[sdk_error(code = 1)]
+ MalformedTransaction(#[source] anyhow::Error),
+
+ #[error("invalid transaction: {0}")]
+ #[sdk_error(code = 2)]
+ InvalidTransaction(#[from] transaction::Error),
+
+ #[error("invalid method: {0}")]
+ #[sdk_error(code = 3)]
+ InvalidMethod(String),
+
+ #[error("invalid nonce")]
+ #[sdk_error(code = 4)]
+ InvalidNonce,
+
+ #[error("insufficient balance to pay fees")]
+ #[sdk_error(code = 5)]
+ InsufficientFeeBalance,
+
+ #[error("out of message slots")]
+ #[sdk_error(code = 6)]
+ OutOfMessageSlots,
+
+ #[error("message handler not invoked")]
+ #[sdk_error(code = 8)]
+ MessageHandlerNotInvoked,
+
+ #[error("missing message handler")]
+ #[sdk_error(code = 9)]
+ MessageHandlerMissing(u32),
+
+ #[error("invalid argument: {0}")]
+ #[sdk_error(code = 10)]
+ InvalidArgument(#[source] anyhow::Error),
+
+ #[error("gas overflow")]
+ #[sdk_error(code = 11)]
+ GasOverflow,
+
+ #[error("out of gas (limit: {0} wanted: {1})")]
+ #[sdk_error(code = 12)]
+ OutOfGas(u64, u64),
+
+ #[error("too many authentication slots")]
+ #[sdk_error(code = 15)]
+ TooManyAuth,
+
+ #[error("multisig too many signers")]
+ #[sdk_error(code = 16)]
+ MultisigTooManySigners,
+
+ #[error("invariant violation: {0}")]
+ #[sdk_error(code = 17)]
+ InvariantViolation(String),
+
+ #[error("invalid call format: {0}")]
+ #[sdk_error(code = 18)]
+ InvalidCallFormat(#[source] anyhow::Error),
+
+ #[error("{0}")]
+ #[sdk_error(transparent, abort)]
+ Abort(#[source] dispatcher::Error),
+
+ #[error("no module could authenticate the transaction")]
+ #[sdk_error(code = 19)]
+ NotAuthenticated,
+
+ #[error("gas price too low")]
+ #[sdk_error(code = 20)]
+ GasPriceTooLow,
+
+ #[error("forbidden in secure build")]
+ #[sdk_error(code = 21)]
+ ForbiddenInSecureBuild,
+
+ #[error("forbidden by node policy")]
+ #[sdk_error(code = 22)]
+ Forbidden,
+
+ #[error("transaction is too large")]
+ #[sdk_error(code = 23)]
+ OversizedTransaction,
+
+ #[error("transaction is expired or not yet valid")]
+ #[sdk_error(code = 24)]
+ ExpiredTransaction,
+
+ #[error("read-only transaction attempted modifications")]
+ #[sdk_error(code = 25)]
+ ReadOnlyTransaction,
+
+ #[error("future nonce")]
+ #[sdk_error(code = 26)]
+ FutureNonce,
+
+ #[error("call depth exceeded (depth: {0} max: {1})")]
+ #[sdk_error(code = 27)]
+ CallDepthExceeded(u16, u16),
+
+ #[error("{0}")]
+ #[sdk_error(transparent)]
+ TxSimulationFailed(#[from] TxSimulationFailure),
+}
+
+impl Error {
+ /// Generate a proper OutOfGas error, depending on whether the module is configured to emit gas
+ /// use information or not.
+ pub fn out_of_gas<Cfg: Config>(limit: u64, wanted: u64) -> Self {
+ if Cfg::EMIT_GAS_USED_EVENTS {
+ Self::OutOfGas(limit, wanted)
+ } else {
+ // Mask gas used information.
+ Self::OutOfGas(0, 0)
+ }
+ }
+}
+
+/// Simulation failure error.
+#[derive(Error, Debug)]
+pub struct TxSimulationFailure {
+ message: String,
+ module_name: String,
+ code: u32,
+}
+
+impl TxSimulationFailure {
+ /// Returns true if the failure is "core::Error::OutOfGas".
+ pub fn is_error_core_out_of_gas(&self) -> bool {
+ self.module_name == MODULE_NAME && self.code == 12
+ }
+}
+
+impl Display for TxSimulationFailure {
+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ write!(f, "{}", self.message)
+ }
+}
+
+impl SDKError for TxSimulationFailure {
+ fn module_name(&self) -> &str {
+ &self.module_name
+ }
+
+ fn code(&self) -> u32 {
+ self.code
+ }
+}
+
+impl TryFrom<CallResult> for TxSimulationFailure {
+ type Error = anyhow::Error;
+
+ fn try_from(value: CallResult) -> Result<Self, Self::Error> {
+ match value {
+ CallResult::Failed {
+ module,
+ code,
+ message,
+ } => Ok(TxSimulationFailure {
+ code,
+ module_name: module,
+ message,
+ }),
+ _ => Err(anyhow!("CallResult not Failed")),
+ }
+ }
+}
+
+/// Events emitted by the core module.
+#[derive(Debug, PartialEq, Eq, cbor::Encode, oasis_runtime_sdk_macros::Event)]
+#[cbor(untagged)]
+pub enum Event {
+ #[sdk_event(code = 1)]
+ GasUsed { amount: u64 },
+}
+
+/// Gas costs.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct GasCosts {
+ pub tx_byte: u64,
+ pub storage_byte: u64,
+
+ pub auth_signature: u64,
+ pub auth_multisig_signer: u64,
+
+ pub callformat_x25519_deoxysii: u64,
+}
+
+/// Dynamic min gas price parameters.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct DynamicMinGasPrice {
+ /// Enables the dynamic min gas price feature which dynamically adjusts the minimum gas price
+ /// based on block fullness, inspired by EIP-1559.
+ ///
+ /// Only takes effect if `min_gas_price`(s) are set.
+ pub enabled: bool,
+
+ /// Target block gas usage indicates the desired block gas usage as a percentage of the total
+ /// block gas limit.
+ ///
+ /// The min gas price will adjust up or down depending on whether the actual gas usage is above
+ /// or below this target.
+ pub target_block_gas_usage_percentage: u8,
+ /// Represents a constant value used to limit the rate at which the min price can change
+ /// between blocks.
+ ///
+ /// For example, if `min_price_max_change_denominator` is set to 8, the maximum change in
+ /// min price is 12.5% between blocks.
+ pub min_price_max_change_denominator: u8,
+}
+
+/// Errors emitted during core parameter validation.
+#[derive(Error, Debug)]
+pub enum ParameterValidationError {
+ #[error("invalid dynamic target block gas usage percentage (10-100)")]
+ InvalidTargetBlockGasUsagePercentage,
+ #[error("invalid dynamic min price max change denominator (1-50)")]
+ InvalidMinPriceMaxChangeDenominator,
+}
+/// Parameters for the core module.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Parameters {
+ pub max_batch_gas: u64,
+ pub max_tx_size: u32,
+ pub max_tx_signers: u32,
+ pub max_multisig_signers: u32,
+ pub gas_costs: GasCosts,
+ pub min_gas_price: BTreeMap<token::Denomination, u128>,
+ pub dynamic_min_gas_price: DynamicMinGasPrice,
+}
+
+impl module::Parameters for Parameters {
+ type Error = ParameterValidationError;
+
+ fn validate_basic(&self) -> Result<(), Self::Error> {
+ // Validate dynamic min gas price parameters.
+ let dmgp = &self.dynamic_min_gas_price;
+ if dmgp.enabled {
+ if dmgp.target_block_gas_usage_percentage < 10
+ || dmgp.target_block_gas_usage_percentage > 100
+ {
+ return Err(ParameterValidationError::InvalidTargetBlockGasUsagePercentage);
+ }
+ if dmgp.min_price_max_change_denominator < 1
+ || dmgp.min_price_max_change_denominator > 50
+ {
+ return Err(ParameterValidationError::InvalidMinPriceMaxChangeDenominator);
+ }
+ }
+ Ok(())
+ }
+}
+
+/// Interface that can be called from other modules.
+pub trait API {
+ /// Module configuration.
+ type Config: Config;
+
+ /// Attempt to use gas. If the gas specified would cause either total used to exceed
+ /// its limit, fails with Error::OutOfGas or Error::BatchOutOfGas, and neither gas usage is
+ /// increased.
+ fn use_batch_gas(gas: u64) -> Result<(), Error>;
+
+ /// Attempt to use gas. If the gas specified would cause either total used to exceed
+ /// its limit, fails with Error::OutOfGas or Error::BatchOutOfGas, and neither gas usage is
+ /// increased.
+ fn use_tx_gas(gas: u64) -> Result<(), Error>;
+
+ /// Returns the remaining batch-wide gas.
+ fn remaining_batch_gas() -> u64;
+
+ /// Returns the total batch-wide gas used.
+ fn used_batch_gas() -> u64;
+
+ /// Return the remaining tx-wide gas.
+ fn remaining_tx_gas() -> u64;
+
+ /// Return the used tx-wide gas.
+ fn used_tx_gas() -> u64;
+
+ /// Configured maximum amount of gas that can be used in a batch.
+ fn max_batch_gas() -> u64;
+
+ /// Configured minimum gas price.
+ fn min_gas_price(denom: &token::Denomination) -> Option<u128>;
+
+ /// Sets the transaction priority to the provided amount.
+ fn set_priority(priority: u64);
+
+ /// Takes and returns the stored transaction priority.
+ fn take_priority() -> u64;
+
+ /// Set transaction sender metadata.
+ fn set_sender_meta(meta: SenderMeta);
+
+ /// Takes and returns the stored transaction sender metadata.
+ fn take_sender_meta() -> SenderMeta;
+
+ /// Returns the configured max iterations in the binary search for the estimate
+ /// gas.
+ fn estimate_gas_search_max_iters<C: Context>(ctx: &C) -> u64;
+
+ /// Check whether the epoch has changed since last processed block.
+ fn has_epoch_changed() -> bool;
+}
+
+/// Genesis state for the accounts module.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Genesis {
+ pub parameters: Parameters,
+}
+
+/// Local configuration that can be provided by the node operator.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct LocalConfig {
+ /// Minimum gas price to accept.
+ #[cbor(optional)]
+ pub min_gas_price: BTreeMap<token::Denomination, u128>,
+
+ /// When estimating gas in `core.EstimateGas`, simulate the tx (and report) only up to this much
+ /// used gas. This limit is more likely to be relevant if `estimate_gas_by_simulating_contracts` is
+ /// enabled in the local config. The special value of 0 means that the maximum amount of gas in a
+ /// batch will be used.
+ #[cbor(optional)]
+ pub max_estimated_gas: u64,
+
+ /// The maximum number of iterations of the binary search to be done when simulating contracts for
+ /// gas estimation in `core.EstimateGas`.
+ /// The special value of 0 means that binary search won't be performed, and the transaction will be
+ /// simulated using maximum possible gas, which might return an overestimation in some special cases.
+ /// This setting should likely be kept at 0, unless the runtime is using the EVM module.
+ #[cbor(optional)]
+ pub estimate_gas_search_max_iters: u64,
+}
+
+/// State schema constants.
+pub mod state {
+ /// Runtime metadata.
+ pub const METADATA: &[u8] = &[0x01];
+ /// Map of message idx to message handlers for messages emitted in previous round.
+ pub const MESSAGE_HANDLERS: &[u8] = &[0x02];
+ /// Last processed epoch for detecting epoch changes.
+ pub const LAST_EPOCH: &[u8] = &[0x03];
+ /// Dynamic min gas price.
+ pub const DYNAMIC_MIN_GAS_PRICE: &[u8] = &[0x04];
+}
+
+/// Module configuration.
+#[allow(clippy::declare_interior_mutable_const)]
+pub trait Config: 'static {
+ /// Default local minimum gas price configuration that is used in case no overrides are set in
+ /// local per-node configuration.
+ const DEFAULT_LOCAL_MIN_GAS_PRICE: once_cell::unsync::Lazy<
+ BTreeMap<token::Denomination, u128>,
+ > = once_cell::unsync::Lazy::new(BTreeMap::new);
+
+ /// Default local estimate gas max search iterations configuration that is used in case no overrides
+ /// are set in the local per-node configuration.
+ const DEFAULT_LOCAL_ESTIMATE_GAS_SEARCH_MAX_ITERS: u64 = 0;
+
+ /// Estimated gas amount to be added to failed transaction simulations for selected methods.
+ const ESTIMATE_GAS_EXTRA_FAIL: once_cell::unsync::Lazy<BTreeMap<&'static str, u64>> =
+ once_cell::unsync::Lazy::new(BTreeMap::new);
+
+ /// Methods which are exempt from minimum gas price requirements.
+ const MIN_GAS_PRICE_EXEMPT_METHODS: once_cell::unsync::Lazy<BTreeSet<&'static str>> =
+ once_cell::unsync::Lazy::new(BTreeSet::new);
+
+ /// Whether gas used events should be emitted for every transaction.
+ ///
+ /// Confidential runtimes may want to disable this as it is a possible side channel.
+ const EMIT_GAS_USED_EVENTS: bool = true;
+
+ /// Whether to allow submission of read-only transactions in an interactive way.
+ ///
+ /// Note that execution of such transactions is allowed to access confidential state.
+ const ALLOW_INTERACTIVE_READ_ONLY_TRANSACTIONS: bool = false;
+
+ /// The gas cost of the internal call to retrieve the current calldata public key.
+ const GAS_COST_CALL_CALLDATA_PUBLIC_KEY: u64 = 20;
+ /// The gas cost of the internal call to retrieve the current epoch.
+ const GAS_COST_CALL_CURRENT_EPOCH: u64 = 10;
+}
+
+pub struct Module<Cfg: Config> {
+ _cfg: std::marker::PhantomData<Cfg>,
+}
+
+const CONTEXT_KEY_GAS_USED: &str = "core.GasUsed";
+const CONTEXT_KEY_PRIORITY: &str = "core.Priority";
+const CONTEXT_KEY_SENDER_META: &str = "core.SenderMeta";
+const CONTEXT_KEY_EPOCH_CHANGED: &str = "core.EpochChanged";
+
+impl<Cfg: Config> API for Module<Cfg> {
+ type Config = Cfg;
+
+ fn use_batch_gas(gas: u64) -> Result<(), Error> {
+ // Do not enforce batch limits for checks.
+ if CurrentState::with_env(|env| env.is_check_only()) {
+ return Ok(());
+ }
+ let batch_gas_limit = Self::params().max_batch_gas;
+ let batch_gas_used = Self::used_batch_gas();
+ // NOTE: Going over the batch limit should trigger an abort as the scheduler should never
+ // allow scheduling past the batch limit but a malicious proposer might include too
+ // many transactions. Make sure to vote for failure in this case.
+ let batch_new_gas_used = batch_gas_used
+ .checked_add(gas)
+ .ok_or(Error::Abort(dispatcher::Error::BatchOutOfGas))?;
+ if batch_new_gas_used > batch_gas_limit {
+ return Err(Error::Abort(dispatcher::Error::BatchOutOfGas));
+ }
+
+ CurrentState::with(|state| {
+ state
+ .block_value::<u64>(CONTEXT_KEY_GAS_USED)
+ .set(batch_new_gas_used);
+ });
+
+ Ok(())
+ }
+
+ fn use_tx_gas(gas: u64) -> Result<(), Error> {
+ let (gas_limit, gas_used) = CurrentState::with(|state| {
+ (
+ state.env().tx_auth_info().fee.gas,
+ *state.local_value::<u64>(CONTEXT_KEY_GAS_USED).or_default(),
+ )
+ });
+ let new_gas_used = {
+ let sum = gas_used.checked_add(gas).ok_or(Error::GasOverflow)?;
+ if sum > gas_limit {
+ return Err(Error::out_of_gas::<Cfg>(gas_limit, sum));
+ }
+ sum
+ };
+
+ Self::use_batch_gas(gas)?;
+
+ CurrentState::with(|state| {
+ *state.local_value::<u64>(CONTEXT_KEY_GAS_USED).or_default() = new_gas_used;
+ });
+
+ Ok(())
+ }
+
+ fn remaining_batch_gas() -> u64 {
+ let batch_gas_limit = Self::params().max_batch_gas;
+ batch_gas_limit.saturating_sub(Self::used_batch_gas())
+ }
+
+ fn used_batch_gas() -> u64 {
+ CurrentState::with(|state| {
+ state
+ .block_value::<u64>(CONTEXT_KEY_GAS_USED)
+ .get()
+ .cloned()
+ .unwrap_or_default()
+ })
+ }
+
+ fn remaining_tx_gas() -> u64 {
+ let (gas_limit, gas_used) = CurrentState::with(|state| {
+ (
+ state.env().tx_auth_info().fee.gas,
+ *state.local_value::<u64>(CONTEXT_KEY_GAS_USED).or_default(),
+ )
+ });
+ let remaining_tx = gas_limit.saturating_sub(gas_used);
+ // Also check remaining batch gas limit and return the minimum of the two.
+ let remaining_batch = Self::remaining_batch_gas();
+ std::cmp::min(remaining_tx, remaining_batch)
+ }
+
+ fn used_tx_gas() -> u64 {
+ CurrentState::with(|state| *state.local_value::<u64>(CONTEXT_KEY_GAS_USED).or_default())
+ }
+
+ fn max_batch_gas() -> u64 {
+ Self::params().max_batch_gas
+ }
+
+ fn min_gas_price(denom: &token::Denomination) -> Option<u128> {
+ Self::min_gas_prices().get(denom).copied()
+ }
+
+ fn set_priority(priority: u64) {
+ CurrentState::with(|state| {
+ state.block_value::<u64>(CONTEXT_KEY_PRIORITY).set(priority);
+ })
+ }
+
+ fn take_priority() -> u64 {
+ CurrentState::with(|state| {
+ state
+ .block_value::<u64>(CONTEXT_KEY_PRIORITY)
+ .take()
+ .unwrap_or_default()
+ })
+ }
+
+ fn set_sender_meta(meta: SenderMeta) {
+ CurrentState::with(|state| {
+ state
+ .block_value::<SenderMeta>(CONTEXT_KEY_SENDER_META)
+ .set(meta);
+ });
+ }
+
+ fn take_sender_meta() -> SenderMeta {
+ CurrentState::with(|state| {
+ state
+ .block_value::<SenderMeta>(CONTEXT_KEY_SENDER_META)
+ .take()
+ .unwrap_or_default()
+ })
+ }
+
+ fn estimate_gas_search_max_iters<C: Context>(ctx: &C) -> u64 {
+ ctx.local_config(MODULE_NAME)
+ .as_ref()
+ .map(|cfg: &LocalConfig| cfg.estimate_gas_search_max_iters)
+ .unwrap_or(Cfg::DEFAULT_LOCAL_ESTIMATE_GAS_SEARCH_MAX_ITERS)
+ }
+
+ fn has_epoch_changed() -> bool {
+ CurrentState::with(|state| {
+ *state
+ .block_value(CONTEXT_KEY_EPOCH_CHANGED)
+ .get()
+ .unwrap_or(&false)
+ })
+ }
+}
+
+#[sdk_derive(Module)]
+impl<Cfg: Config> Module<Cfg> {
+ const NAME: &'static str = MODULE_NAME;
+ type Error = Error;
+ type Event = Event;
+ type Parameters = Parameters;
+ type Genesis = Genesis;
+
+ #[migration(init)]
+ pub fn init(genesis: Genesis) {
+ // Set genesis parameters.
+ Self::set_params(genesis.parameters);
+ }
+
+ /// Run a transaction in simulation and return how much gas it uses. This looks up the method
+ /// in the context's method registry. Transactions that fail still use gas, and this query will
+ /// estimate that and return successfully, so do not use this query to see if a transaction will
+ /// succeed.
+ #[handler(query = "core.EstimateGas", allow_private_km)]
+ pub fn query_estimate_gas<C: Context>(
+ ctx: &C,
+ mut args: types::EstimateGasQuery,
+ ) -> Result<u64, Error> {
+ let mut extra_gas = 0u64;
+ // In case the runtime is confidential we are unable to authenticate the caller so we must
+ // make sure to zeroize it to avoid leaking private information.
+ if ctx.is_confidential() {
+ args.caller = Some(
+ args.caller
+ .unwrap_or_else(|| {
+ args.tx
+ .auth_info
+ .signer_info
+ .first()
+ .map(|si| si.address_spec.caller_address())
+ .unwrap_or(CallerAddress::Address(Default::default()))
+ })
+ .zeroized(),
+ );
+ args.propagate_failures = false; // Likely to fail as caller is zeroized.
+ }
+ // Assume maximum amount of gas in a batch, a reasonable maximum fee and maximum amount of consensus messages.
+ args.tx.auth_info.fee.gas = {
+ let local_max_estimated_gas = Self::get_local_max_estimated_gas(ctx);
+ if local_max_estimated_gas == 0 {
+ Self::params().max_batch_gas
+ } else {
+ local_max_estimated_gas
+ }
+ };
+ args.tx.auth_info.fee.amount =
+ token::BaseUnits::new(u64::MAX.into(), token::Denomination::NATIVE);
+ args.tx.auth_info.fee.consensus_messages = ctx.max_messages();
+ // Estimate transaction size. Since the transaction given to us is not signed, we need to
+ // estimate how large each of the auth proofs would be.
+ let auth_proofs: Result<_, Error> = args
+ .tx
+ .auth_info
+ .signer_info
+ .iter()
+ .map(|si| match si.address_spec {
+ // For the signature address spec we assume a signature auth proof of 64 bytes.
+ transaction::AddressSpec::Signature(_) => {
+ Ok(transaction::AuthProof::Signature(vec![0; 64].into()))
+ }
+ // For the multisig address spec assume all the signers sign with a 64-byte signature.
+ transaction::AddressSpec::Multisig(ref cfg) => {
+ Ok(transaction::AuthProof::Multisig(
+ cfg.signers
+ .iter()
+ .map(|_| Some(vec![0; 64].into()))
+ .collect(),
+ ))
+ }
+ // Internal address specs should never appear as they are not serializable.
+ transaction::AddressSpec::Internal(_) => Err(Error::MalformedTransaction(anyhow!(
+ "internal address spec used"
+ ))),
+ })
+ .collect();
+ let tx_envelope =
+ transaction::UnverifiedTransaction(cbor::to_vec(args.tx.clone()), auth_proofs?);
+ let tx_size: u32 = cbor::to_vec(tx_envelope)
+ .len()
+ .try_into()
+ .map_err(|_| Error::InvalidArgument(anyhow!("transaction too large")))?;
+ let propagate_failures = args.propagate_failures;
+ let bs_max_iters = Self::estimate_gas_search_max_iters(ctx);
+
+ // Update the address used within the transaction when caller address is passed.
+ if let Some(caller) = args.caller.clone() {
+ // Include additional gas for each signature verification since we will be overwriting
+ // the signer infos below.
+ extra_gas = extra_gas.saturating_add(
+ Self::compute_signature_verification_cost(
+ &Self::params(),
+ &args.tx.auth_info.signer_info,
+ )
+ .unwrap_or_default(),
+ );
+
+ args.tx.auth_info.signer_info = vec![transaction::SignerInfo {
+ address_spec: transaction::AddressSpec::Internal(caller),
+ nonce: args
+ .tx
+ .auth_info
+ .signer_info
+ .first()
+ .map(|si| si.nonce)
+ .unwrap_or_default(),
+ }];
+ }
+
+ // Determine if we need to add any extra gas for failing calls.
+ #[allow(clippy::borrow_interior_mutable_const)]
+ let extra_gas_fail = *Cfg::ESTIMATE_GAS_EXTRA_FAIL
+ .get(args.tx.call.method.as_str())
+ .unwrap_or(&0);
+
+ // Simulates transaction with a specific gas limit.
+ let simulate = |tx: &transaction::Transaction, gas: u64, report_failure: bool| {
+ let mut tx = tx.clone();
+ tx.auth_info.fee.gas = gas;
+ let call = tx.call.clone(); // TODO: Avoid clone.
+
+ CurrentState::with_transaction_opts(
+ Options::new()
+ .with_mode(Mode::Simulate)
+ .with_tx(TransactionWithMeta {
+ data: tx,
+ size: tx_size,
+ index: 0,
+ hash: Default::default(),
+ }),
+ || {
+ let (result, _) = dispatcher::Dispatcher::<C::Runtime>::dispatch_tx_call(
+ ctx,
+ call,
+ &Default::default(),
+ );
+ if !result.is_success() && report_failure {
+ // Report failure.
+ let err: TxSimulationFailure = result.try_into().unwrap(); // Guaranteed to be a Failed CallResult.
+ return Err(Error::TxSimulationFailed(err));
+ }
+ // Don't report success or failure. If the call fails, we still report
+ // how much gas it uses while it fails.
+ let gas_used = Self::used_batch_gas();
+ if result.is_success() {
+ Ok(gas_used)
+ } else {
+ Ok(gas_used.saturating_add(extra_gas_fail).clamp(0, gas))
+ }
+ },
+ )
+ };
+
+ // Do a binary search for exact gas limit.
+ let (cap, mut lo, mut hi) = (
+ args.tx.auth_info.fee.gas,
+ 10_u128,
+ args.tx.auth_info.fee.gas as u128,
+ ); // Use u128 to avoid overflows when computing the mid point.
+
+ // Count iterations, and remember if fast path was tried.
+ let (mut iters, mut fast_path_tried) = (0, false);
+ // The following two variables are used to control the special case where a transaction fails
+ // and we check if the error is due to out-of-gas by re-simulating the transaction with maximum
+ // gas limit. This is needed due to EVM transactions failing with a "reverted" error when
+ // not having enough gas for EIP-150 (and not with "out-of-gas").
+ let (mut has_succeeded, mut tried_with_max_gas) = (false, false);
+ while (lo + 1 < hi) && iters < bs_max_iters {
+ iters += 1;
+
+ let mid = (hi + lo) / 2;
+ match simulate(&args.tx, mid as u64, true) {
+ Ok(r) => {
+ // Estimate success. Try with lower gas.
+ hi = mid;
+
+ // The transaction succeeded at least once, meaning any future failure is due
+ // to insufficient gas limit.
+ has_succeeded = true;
+
+ // Optimization: In vast majority of cases the initially returned gas estimate
+ // might already be a good one. Check if this is the case to speed up the convergence.
+ if !fast_path_tried && (lo + 1 < hi) {
+ fast_path_tried = true;
+
+ // If simulate with the returned estimate succeeds, we can further shrink the
+ // high limit of the binary search.
+ match simulate(&args.tx, r, true) {
+ Ok(_) => hi = r as u128,
+ _ => continue,
+ }
+ // If simulate with one unit of gas smaller fails, we know the exact estimate.
+ match simulate(&args.tx, r - 1, true) {
+ Err(_) => {
+ // Stop the gas search.
+ break;
+ }
+ _ => continue,
+ }
+ }
+ }
+ Err(_) if has_succeeded => {
+ // Transaction previously succeeded. Transaction failed due to insufficient gas limit,
+ // regardless of the actual returned error.
+ // Try with higher gas.
+ lo = mid
+ }
+ Err(Error::TxSimulationFailed(failure)) if failure.is_error_core_out_of_gas() => {
+ // Estimate failed due to insufficient gas limit. Try with higher gas.
+ lo = mid
+ }
+ r @ Err(_) => {
+ let mut res = r;
+ if !tried_with_max_gas {
+ tried_with_max_gas = true;
+ // Transaction failed and simulation with max gas was not yet tried.
+ // Try simulating with maximum gas once:
+ // - if fails, the transaction will always fail, stop the binary search.
+ // - if succeeds, remember that transaction is failing due to insufficient gas
+ // and continue the search.
+ res = simulate(&args.tx, cap, true)
+ }
+ match res {
+ Ok(_) => {
+ has_succeeded = true;
+ // Transaction can succeed. Try with higher gas.
+ lo = mid
+ }
+ err if propagate_failures => {
+ // Estimate failed (not with out-of-gas) and caller wants error propagation -> early exit and return the error.
+ return err;
+ }
+ _ => {
+ // Estimate failed (not with out-of-gas) but caller wants to know the gas usage.
+ // Exit loop and do one final estimate without error propagation.
+ // NOTE: don't continue the binary search for failing transactions as the convergence
+ // for these could take somewhat long and the estimate with default max gas is likely good.
+ break;
+ }
+ }
+ }
+ }
+ }
+
+ // hi == cap if binary search is disabled or this is a failing transaction.
+ let result = if hi == cap.into() {
+ // Simulate one last time with maximum gas limit.
+ simulate(&args.tx, cap, propagate_failures)
+ } else {
+ Ok(hi as u64)
+ };
+
+ // Make sure the final result is clamped.
+ result.map(|est| est.saturating_add(extra_gas).clamp(0, cap))
+ }
+
+ /// Check invariants of all modules in the runtime.
+ #[handler(query = "core.CheckInvariants", expensive)]
+ fn query_check_invariants<C: Context>(ctx: &C, _args: ()) -> Result<(), Error> {
+ <C::Runtime as Runtime>::Modules::check_invariants(ctx)
+ }
+
+ fn calldata_public_key_common<C: Context>(
+ ctx: &C,
+ ) -> Result<types::CallDataPublicKeyQueryResponse, Error> {
+ let key_manager = ctx
+ .key_manager()
+ .ok_or_else(|| Error::InvalidArgument(anyhow!("key manager not available")))?;
+ let epoch = ctx.epoch();
+ let public_key = key_manager
+ .get_public_ephemeral_key(callformat::get_key_pair_id(epoch), epoch)
+ .map_err(|err| match err {
+ keymanager::KeyManagerError::InvalidEpoch(..) => {
+ Error::InvalidCallFormat(anyhow!("invalid epoch"))
+ }
+ _ => Error::Abort(err.into()),
+ })?;
+
+ Ok(types::CallDataPublicKeyQueryResponse { public_key, epoch })
+ }
+
+ /// Retrieve the public key for encrypting call data.
+ #[handler(query = "core.CallDataPublicKey")]
+ fn query_calldata_public_key<C: Context>(
+ ctx: &C,
+ _args: (),
+ ) -> Result<types::CallDataPublicKeyQueryResponse, Error> {
+ Self::calldata_public_key_common(ctx)
+ }
+
+ /// Retrieve the public key for encrypting call data (internally exposed call).
+ #[handler(call = "core.CallDataPublicKey", internal)]
+ fn internal_calldata_public_key<C: Context>(
+ ctx: &C,
+ _args: (),
+ ) -> Result<types::CallDataPublicKeyQueryResponse, Error> {
+ <C::Runtime as Runtime>::Core::use_tx_gas(Cfg::GAS_COST_CALL_CALLDATA_PUBLIC_KEY)?;
+ Self::calldata_public_key_common(ctx)
+ }
+
+ /// Retrieve the current epoch.
+ #[handler(call = "core.CurrentEpoch", internal)]
+ fn internal_current_epoch<C: Context>(ctx: &C, _args: ()) -> Result<u64, Error> {
+ <C::Runtime as Runtime>::Core::use_tx_gas(Cfg::GAS_COST_CALL_CURRENT_EPOCH)?;
+ Ok(ctx.epoch())
+ }
+
+ /// Query the minimum gas price.
+ #[handler(query = "core.MinGasPrice")]
+ fn query_min_gas_price<C: Context>(
+ ctx: &C,
+ _args: (),
+ ) -> Result<BTreeMap<token::Denomination, u128>, Error> {
+ let mut mgp = Self::min_gas_prices();
+
+ // Generate a combined view with local overrides.
+ for (denom, price) in mgp.iter_mut() {
+ let local_mgp = Self::get_local_min_gas_price(ctx, denom);
+ if local_mgp > *price {
+ *price = local_mgp;
+ }
+ }
+
+ Ok(mgp)
+ }
+
+ /// Return basic information about the module and the containing runtime.
+ #[handler(query = "core.RuntimeInfo")]
+ fn query_runtime_info<C: Context>(ctx: &C, _args: ()) -> Result<RuntimeInfoResponse, Error> {
+ Ok(RuntimeInfoResponse {
+ runtime_version: <C::Runtime as Runtime>::VERSION,
+ state_version: <C::Runtime as Runtime>::STATE_VERSION,
+ modules: <C::Runtime as Runtime>::Modules::module_info(ctx),
+ })
+ }
+
+ /// Execute a read-only transaction in an interactive mode.
+ ///
+ /// # Warning
+ ///
+ /// This query is allowed access to private key manager state.
+ #[handler(query = "core.ExecuteReadOnlyTx", expensive, allow_private_km)]
+ fn query_execute_read_only_tx<C: Context>(
+ ctx: &C,
+ args: types::ExecuteReadOnlyTxQuery,
+ ) -> Result<types::ExecuteReadOnlyTxResponse, Error> {
+ if !Cfg::ALLOW_INTERACTIVE_READ_ONLY_TRANSACTIONS {
+ return Err(Error::Forbidden);
+ }
+
+ CurrentState::with_transaction_opts(Options::new().with_mode(Mode::Simulate), || {
+ // TODO: Use separate batch gas limit for query execution.
+
+ // Decode transaction and verify signature.
+ let tx_size = args
+ .tx
+ .len()
+ .try_into()
+ .map_err(|_| Error::OversizedTransaction)?;
+ let tx = dispatcher::Dispatcher::<C::Runtime>::decode_tx(ctx, &args.tx)?;
+
+ // Only read-only transactions are allowed in interactive queries.
+ if !tx.call.read_only {
+ return Err(Error::InvalidArgument(anyhow::anyhow!(
+ "only read-only transactions are allowed"
+ )));
+ }
+ // Only transactions with expiry are allowed in interactive queries.
+ if tx.auth_info.not_before.is_none() || tx.auth_info.not_after.is_none() {
+ return Err(Error::InvalidArgument(anyhow::anyhow!(
+ "only read-only transactions with expiry are allowed"
+ )));
+ }
+
+ // Execute transaction.
+ let (result, _) = dispatcher::Dispatcher::<C::Runtime>::execute_tx_opts(
+ ctx,
+ tx,
+ &dispatcher::DispatchOptions {
+ tx_size,
+ method_authorizer: Some(&|method| {
+ // Ensure that the inner method is allowed to be called from an interactive
+ // context to avoid unexpected pitfalls.
+ <C::Runtime as Runtime>::Modules::is_allowed_interactive_call(method)
+ && <C::Runtime as Runtime>::is_allowed_interactive_call(method)
+ }),
+ ..Default::default()
+ },
+ )
+ .map_err(|err| Error::InvalidArgument(err.into()))?;
+
+ Ok(types::ExecuteReadOnlyTxResponse { result })
+ })
+ }
+}
+
+impl<Cfg: Config> Module<Cfg> {
+ fn min_gas_prices() -> BTreeMap<Denomination, u128> {
+ let params = Self::params();
+ if params.dynamic_min_gas_price.enabled {
+ CurrentState::with_store(|store| {
+ let store =
+ storage::TypedStore::new(storage::PrefixStore::new(store, &MODULE_NAME));
+ store
+ .get(state::DYNAMIC_MIN_GAS_PRICE)
+ // Use static min gas price when dynamic price was not yet computed.
+ .unwrap_or(params.min_gas_price)
+ })
+ } else {
+ params.min_gas_price
+ }
+ }
+
+ fn get_local_min_gas_price<C: Context>(ctx: &C, denom: &token::Denomination) -> u128 {
+ #[allow(clippy::borrow_interior_mutable_const)]
+ ctx.local_config(MODULE_NAME)
+ .as_ref()
+ .map(|cfg: &LocalConfig| cfg.min_gas_price.get(denom).copied())
+ .unwrap_or_else(|| Cfg::DEFAULT_LOCAL_MIN_GAS_PRICE.get(denom).copied())
+ .unwrap_or_default()
+ }
+
+ fn get_local_max_estimated_gas<C: Context>(ctx: &C) -> u64 {
+ ctx.local_config(MODULE_NAME)
+ .as_ref()
+ .map(|cfg: &LocalConfig| cfg.max_estimated_gas)
+ .unwrap_or_default()
+ }
+
+ fn enforce_min_gas_price<C: Context>(ctx: &C, call: &Call) -> Result<(), Error> {
+ // If the method is exempt from min gas price requirements, checks always pass.
+ #[allow(clippy::borrow_interior_mutable_const)]
+ if Cfg::MIN_GAS_PRICE_EXEMPT_METHODS.contains(call.method.as_str()) {
+ return Ok(());
+ }
+
+ let fee = CurrentState::with_env(|env| env.tx_auth_info().fee.clone());
+ let denom = fee.amount.denomination();
+
+ match Self::min_gas_price(denom) {
+ // If the denomination is not among the global set, reject.
+ None => return Err(Error::GasPriceTooLow),
+
+ // Otherwise, allow overrides during local checks.
+ Some(min_gas_price) => {
+ if CurrentState::with_env(|env| env.is_check_only()) {
+ let local_mgp = Self::get_local_min_gas_price(ctx, denom);
+
+ // Reject during local checks.
+ if fee.gas_price() < local_mgp {
+ return Err(Error::GasPriceTooLow);
+ }
+ }
+
+ if fee.gas_price() < min_gas_price {
+ return Err(Error::GasPriceTooLow);
+ }
+ }
+ }
+
+ Ok(())
+ }
+
+ fn compute_signature_verification_cost(
+ params: &Parameters,
+ signer_info: &[SignerInfo],
+ ) -> Option<u64> {
+ let mut num_signature: u64 = 0;
+ let mut num_multisig_signer: u64 = 0;
+ for si in signer_info {
+ match &si.address_spec {
+ AddressSpec::Signature(_) => {
+ num_signature = num_signature.checked_add(1)?;
+ }
+ AddressSpec::Multisig(config) => {
+ num_multisig_signer =
+ num_multisig_signer.checked_add(config.signers.len() as u64)?;
+ }
+ AddressSpec::Internal(_) => {}
+ }
+ }
+
+ let signature_cost = num_signature.checked_mul(params.gas_costs.auth_signature)?;
+ let multisig_signer_cost =
+ num_multisig_signer.checked_mul(params.gas_costs.auth_multisig_signer)?;
+ let sum = signature_cost.checked_add(multisig_signer_cost)?;
+
+ Some(sum)
+ }
+}
+
+impl<Cfg: Config> module::TransactionHandler for Module<Cfg> {
+ fn approve_raw_tx<C: Context>(_ctx: &C, tx: &[u8]) -> Result<(), Error> {
+ let params = Self::params();
+ if tx.len() > params.max_tx_size.try_into().unwrap() {
+ return Err(Error::OversizedTransaction);
+ }
+ Ok(())
+ }
+
+ fn approve_unverified_tx<C: Context>(
+ _ctx: &C,
+ utx: &UnverifiedTransaction,
+ ) -> Result<(), Error> {
+ let params = Self::params();
+ if utx.1.len() > params.max_tx_signers as usize {
+ return Err(Error::TooManyAuth);
+ }
+ for auth_proof in &utx.1 {
+ if let AuthProof::Multisig(config) = auth_proof {
+ if config.len() > params.max_multisig_signers as usize {
+ return Err(Error::MultisigTooManySigners);
+ }
+ }
+ }
+ Ok(())
+ }
+
+ fn authenticate_tx<C: Context>(
+ ctx: &C,
+ tx: &Transaction,
+ ) -> Result<module::AuthDecision, Error> {
+ // Check whether the transaction is currently valid.
+ let round = ctx.runtime_header().round;
+ if let Some(not_before) = tx.auth_info.not_before {
+ if round < not_before {
+ // Too early.
+ return Err(Error::ExpiredTransaction);
+ }
+ }
+ if let Some(not_after) = tx.auth_info.not_after {
+ if round > not_after {
+ // Too late.
+ return Err(Error::ExpiredTransaction);
+ }
+ }
+
+ Ok(module::AuthDecision::Continue)
+ }
+
+ fn before_handle_call<C: Context>(ctx: &C, call: &Call) -> Result<(), Error> {
+ // Ensure that specified gas limit is not greater than batch gas limit.
+ let params = Self::params();
+ let fee = CurrentState::with_env(|env| env.tx_auth_info().fee.clone());
+ if fee.gas > params.max_batch_gas {
+ return Err(Error::GasOverflow);
+ }
+ if fee.consensus_messages > ctx.max_messages() {
+ return Err(Error::OutOfMessageSlots);
+ }
+
+ // Skip additional checks/gas payment for internally generated transactions.
+ if CurrentState::with_env(|env| env.is_internal()) {
+ return Ok(());
+ }
+
+ // Enforce minimum gas price constraints.
+ Self::enforce_min_gas_price(ctx, call)?;
+
+ // Charge gas for transaction size.
+ let tx_size = CurrentState::with_env(|env| env.tx_size());
+ Self::use_tx_gas(
+ params
+ .gas_costs
+ .tx_byte
+ .checked_mul(tx_size.into())
+ .ok_or(Error::GasOverflow)?,
+ )?;
+
+ // Charge gas for signature verification.
+ let total = CurrentState::with_env(|env| {
+ Self::compute_signature_verification_cost(¶ms, &env.tx_auth_info().signer_info)
+ })
+ .ok_or(Error::GasOverflow)?;
+ Self::use_tx_gas(total)?;
+
+ // Charge gas for callformat.
+ match call.format {
+ CallFormat::Plain => {} // No additional gas required.
+ CallFormat::EncryptedX25519DeoxysII => {
+ Self::use_tx_gas(params.gas_costs.callformat_x25519_deoxysii)?
+ }
+ }
+
+ Ok(())
+ }
+
+ fn after_handle_call<C: Context>(
+ ctx: &C,
+ result: module::CallResult,
+ ) -> Result<module::CallResult, Error> {
+ // Skip handling for internally generated calls.
+ if CurrentState::with_env(|env| env.is_internal()) {
+ return Ok(result);
+ }
+
+ let params = Self::params();
+
+ // Compute storage update gas cost.
+ let storage_gas = if params.gas_costs.storage_byte > 0 {
+ let storage_update_bytes =
+ CurrentState::with(|state| state.pending_store_update_byte_size());
+ params
+ .gas_costs
+ .storage_byte
+ .saturating_mul(storage_update_bytes as u64)
+ } else {
+ 0
+ };
+
+ // Compute message gas cost.
+ let message_gas = {
+ let emitted_message_count =
+ CurrentState::with(|state| state.emitted_messages_local_count());
+ // Determine how much each message emission costs based on max_batch_gas and the number
+ // of messages that can be emitted per batch.
+ let message_gas_cost = params
+ .max_batch_gas
+ .checked_div(ctx.max_messages().into())
+ .unwrap_or(u64::MAX); // If no messages are allowed, cost is infinite.
+ message_gas_cost.saturating_mul(emitted_message_count as u64)
+ };
+
+ // Compute the gas amount that the transaction should pay in the end.
+ let used_gas = Self::used_tx_gas();
+ let max_gas = std::cmp::max(used_gas, std::cmp::max(storage_gas, message_gas));
+
+ // Make sure the transaction actually pays for the maximum gas. Note that failure here is
+ // fine since the extra resources (storage updates or emitted consensus messages) have not
+ // actually been spent yet (this happens at the end of the round).
+ let maybe_out_of_gas = Self::use_tx_gas(max_gas - used_gas); // Cannot overflow as max_gas >= used_gas.
+
+ // Emit gas used event.
+ if Cfg::EMIT_GAS_USED_EVENTS {
+ let used_gas = Self::used_tx_gas();
+ CurrentState::with(|state| {
+ state.emit_unconditional_event(Event::GasUsed { amount: used_gas });
+ });
+ }
+
+ // Evaluate the result of the above `use_tx_gas` here to make sure we emit the event.
+ maybe_out_of_gas?;
+
+ Ok(result)
+ }
+}
+
+/// Computes the new minimum gas price based on the current gas usage and the target gas usage.
+///
+/// The new price is computed as follows (inspired by EIP-1559):
+/// - If the actual gas used is greater than the target gas used, increase the minimum gas price.
+/// - If the actual gas used is less than the target gas used, decrease the minimum gas price.
+///
+/// The price change is controlled by the `min_price_max_change_denominator` parameter.
+fn min_gas_price_update(
+ gas_used: u128,
+ target_gas_used: u128,
+ min_price_max_change_denominator: u128,
+ current_price: u128,
+) -> u128 {
+ // If the target gas used is zero or the denominator is zero, don't change the price.
+ if target_gas_used == 0 || min_price_max_change_denominator == 0 {
+ return current_price;
+ }
+
+ // Calculate the difference (as a percentage) between the actual gas used in the block and the target gas used.
+ let delta = (gas_used.max(target_gas_used) - gas_used.min(target_gas_used)).saturating_mul(100)
+ / target_gas_used;
+
+ // Calculate the change in gas price and divide by `min_price_max_change_denominator`.
+ let price_change =
+ (current_price.saturating_mul(delta) / 100) / min_price_max_change_denominator;
+
+ // Adjust the current price based on whether the gas used was above or below the target.
+ if gas_used > target_gas_used {
+ current_price.saturating_add(price_change)
+ } else {
+ current_price.saturating_sub(price_change)
+ }
+}
+
+impl<Cfg: Config> module::BlockHandler for Module<Cfg> {
+ fn begin_block<C: Context>(ctx: &C) {
+ CurrentState::with(|state| {
+ let epoch = ctx.epoch();
+
+ // Load previous epoch.
+ let mut store = storage::PrefixStore::new(state.store(), &MODULE_NAME);
+ let mut tstore = storage::TypedStore::new(&mut store);
+ let previous_epoch: EpochTime = tstore.get(state::LAST_EPOCH).unwrap_or_default();
+ if epoch != previous_epoch {
+ tstore.insert(state::LAST_EPOCH, epoch);
+ }
+
+ // Set the epoch changed key as needed.
+ state
+ .block_value(CONTEXT_KEY_EPOCH_CHANGED)
+ .set(epoch != previous_epoch);
+ });
+ }
+
+ fn end_block<C: Context>(_ctx: &C) {
+ let params = Self::params();
+ if !params.dynamic_min_gas_price.enabled {
+ return;
+ }
+
+ // Update dynamic min gas price for next block, inspired by EIP-1559.
+ //
+ // Adjust the min gas price for each block based on the gas used in the previous block and the desired target
+ // gas usage set by `target_block_gas_usage_percentage`.
+ let gas_used = Self::used_batch_gas() as u128;
+ let max_batch_gas = Self::max_batch_gas() as u128;
+ let target_gas_used = max_batch_gas.saturating_mul(
+ params
+ .dynamic_min_gas_price
+ .target_block_gas_usage_percentage as u128,
+ ) / 100;
+
+ // Compute new prices.
+ let mut mgp = Self::min_gas_prices();
+ mgp.iter_mut().for_each(|(d, price)| {
+ let mut new_min_price = min_gas_price_update(
+ gas_used,
+ target_gas_used,
+ params
+ .dynamic_min_gas_price
+ .min_price_max_change_denominator as u128,
+ *price,
+ );
+
+ // Ensure that the new price is at least the minimum gas price.
+ if let Some(min_price) = params.min_gas_price.get(d) {
+ if new_min_price < *min_price {
+ new_min_price = *min_price;
+ }
+ }
+ *price = new_min_price;
+ });
+
+ // Update min prices.
+ CurrentState::with_store(|store| {
+ let mut store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut tstore = storage::TypedStore::new(&mut store);
+ tstore.insert(state::DYNAMIC_MIN_GAS_PRICE, mgp);
+ });
+ }
+}
+
+impl<Cfg: Config> module::InvariantHandler for Module<Cfg> {}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +
use std::collections::BTreeMap;
+
+use crate::{
+ keymanager::SignedPublicKey,
+ types::transaction::{CallResult, CallerAddress, Transaction},
+};
+
+/// Key in the versions map used for the global state version.
+pub const VERSION_GLOBAL_KEY: &str = "";
+
+/// Basic per-module metadata; tracked in core module's state.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Metadata {
+ /// A set of state versions for all supported modules.
+ pub versions: BTreeMap<String, u32>,
+}
+
+/// Arguments for the EstimateGas query.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct EstimateGasQuery {
+ /// The address of the caller for which to do estimation. If not specified the authentication
+ /// information from the passed transaction is used.
+ #[cbor(optional)]
+ pub caller: Option<CallerAddress>,
+ /// The unsigned transaction to estimate.
+ pub tx: Transaction,
+ /// If the estimate gas query should fail in case of transaction failures.
+ /// If true, the query will return the transaction error and not the gas estimation.
+ /// Defaults to false.
+ #[cbor(optional)]
+ pub propagate_failures: bool,
+}
+
+/// Response to the call data public key query.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct CallDataPublicKeyQueryResponse {
+ /// Public key used for deriving the shared secret for encrypting call data.
+ pub public_key: SignedPublicKey,
+ /// Epoch of the ephemeral runtime key.
+ pub epoch: u64,
+}
+
+#[derive(Debug, Copy, Clone, cbor::Encode, cbor::Decode)]
+#[cfg_attr(test, derive(PartialEq, Eq))]
+pub enum MethodHandlerKind {
+ #[cbor(rename = "call")]
+ Call,
+ // `Prefetch` is omitted because it is an implementation detail of handling `Call`s.
+ #[cbor(rename = "query")]
+ Query,
+ #[cbor(rename = "message_result")]
+ MessageResult,
+}
+
+#[derive(Debug, Clone, cbor::Encode, cbor::Decode)]
+#[cfg_attr(test, derive(PartialEq, Eq))]
+#[cbor(no_default)]
+pub struct MethodHandlerInfo {
+ pub kind: MethodHandlerKind,
+ pub name: String,
+}
+
+/// Metadata for an individual module.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cfg_attr(test, derive(PartialEq, Eq))]
+#[cbor(no_default)]
+pub struct ModuleInfo {
+ pub version: u32,
+ pub params: cbor::Value,
+ pub methods: Vec<MethodHandlerInfo>,
+}
+
+/// Response to the RuntimeInfo query.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cfg_attr(test, derive(PartialEq, Eq))]
+#[cbor(no_default)]
+pub struct RuntimeInfoResponse {
+ pub runtime_version: oasis_core_runtime::common::version::Version,
+ pub state_version: u32,
+ pub modules: BTreeMap<String, ModuleInfo>,
+}
+
+/// Arguments for the ExecuteReadOnlyTx query.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct ExecuteReadOnlyTxQuery {
+ pub tx: Vec<u8>,
+}
+
+/// Response to the ExecuteReadOnlyTx query.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct ExecuteReadOnlyTxResponse {
+ pub result: CallResult,
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +
//! Rewards module.
+use std::convert::{TryFrom, TryInto};
+
+use num_traits::Zero;
+use once_cell::sync::Lazy;
+use thiserror::Error;
+
+use crate::{
+ context::Context,
+ core::consensus::beacon,
+ migration,
+ module::{self, Module as _, Parameters as _},
+ modules::{self, accounts::API as _, core::API as _},
+ runtime::Runtime,
+ sdk_derive,
+ state::CurrentState,
+ storage::{self, Store},
+ types::address::{Address, SignatureAddressSpec},
+};
+
+#[cfg(test)]
+mod test;
+pub mod types;
+
+/// Unique module name.
+const MODULE_NAME: &str = "rewards";
+
+/// Errors emitted by the rewards module.
+#[derive(Error, Debug, oasis_runtime_sdk_macros::Error)]
+pub enum Error {
+ #[error("invalid argument")]
+ #[sdk_error(code = 1)]
+ InvalidArgument,
+}
+
+/// Parameters for the rewards module.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Parameters {
+ pub schedule: types::RewardSchedule,
+
+ pub participation_threshold_numerator: u64,
+ pub participation_threshold_denominator: u64,
+}
+
+/// Errors emitted during rewards parameter validation.
+#[derive(Error, Debug)]
+pub enum ParameterValidationError {
+ #[error("invalid participation threshold (numerator > denominator)")]
+ InvalidParticipationThreshold,
+
+ #[error("invalid schedule")]
+ InvalidSchedule(#[from] types::RewardScheduleError),
+}
+
+impl module::Parameters for Parameters {
+ type Error = ParameterValidationError;
+
+ fn validate_basic(&self) -> Result<(), Self::Error> {
+ self.schedule.validate_basic()?;
+
+ if self.participation_threshold_numerator > self.participation_threshold_denominator {
+ return Err(ParameterValidationError::InvalidParticipationThreshold);
+ }
+ if self.participation_threshold_denominator.is_zero() {
+ return Err(ParameterValidationError::InvalidParticipationThreshold);
+ }
+
+ Ok(())
+ }
+}
+
+/// Genesis state for the rewards module.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Genesis {
+ pub parameters: Parameters,
+}
+
+/// State schema constants.
+pub mod state {
+ // 0x01 is reserved.
+
+ /// Map of epochs to rewards pending distribution.
+ pub const REWARDS: &[u8] = &[0x02];
+}
+
+/// Rewards module.
+pub struct Module;
+
+/// Module's address that has the reward pool.
+///
+/// oasis1qp7x0q9qahahhjas0xde8w0v04ctp4pqzu5mhjav
+pub static ADDRESS_REWARD_POOL: Lazy<Address> =
+ Lazy::new(|| Address::from_module(MODULE_NAME, "reward-pool"));
+
+#[sdk_derive(Module)]
+impl Module {
+ const NAME: &'static str = MODULE_NAME;
+ const VERSION: u32 = 2;
+ type Error = Error;
+ type Event = ();
+ type Parameters = Parameters;
+ type Genesis = Genesis;
+
+ #[migration(init)]
+ fn init(genesis: Genesis) {
+ genesis
+ .parameters
+ .validate_basic()
+ .expect("invalid genesis parameters");
+
+ // Set genesis parameters.
+ Self::set_params(genesis.parameters);
+ }
+
+ #[migration(from = 1)]
+ fn migrate_v1_to_v2() {
+ CurrentState::with_store(|store| {
+ // Version 2 removes the LAST_EPOCH storage state which was at 0x01.
+ let mut store = storage::PrefixStore::new(store, &MODULE_NAME);
+ store.remove(&[0x01]);
+ });
+ }
+}
+
+impl module::TransactionHandler for Module {}
+
+impl module::BlockHandler for Module {
+ fn end_block<C: Context>(ctx: &C) {
+ let epoch = ctx.epoch();
+
+ // Load rewards accumulator for the current epoch.
+ let mut rewards: types::EpochRewards = CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let epochs =
+ storage::TypedStore::new(storage::PrefixStore::new(store, &state::REWARDS));
+ epochs.get(epoch.to_storage_key()).unwrap_or_default()
+ });
+
+ // Reward each good entity.
+ for entity_id in &ctx.runtime_round_results().good_compute_entities {
+ let address = Address::from_sigspec(&SignatureAddressSpec::Ed25519(entity_id.into()));
+ rewards.pending.entry(address).or_default().increment();
+ }
+
+ // Punish each bad entity by forbidding rewards for this epoch.
+ for entity_id in &ctx.runtime_round_results().bad_compute_entities {
+ let address = Address::from_sigspec(&SignatureAddressSpec::Ed25519(entity_id.into()));
+ rewards.pending.entry(address).or_default().forbid();
+ }
+
+ // Disburse any rewards for previous epochs when the epoch changes.
+ if <C::Runtime as Runtime>::Core::has_epoch_changed() {
+ let epoch_rewards = CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut epochs =
+ storage::TypedStore::new(storage::PrefixStore::new(store, &state::REWARDS));
+ let epoch_rewards: Vec<(DecodableEpochTime, types::EpochRewards)> =
+ epochs.iter().collect();
+
+ // Remove all epochs that we will process.
+ for (epoch, _) in &epoch_rewards {
+ epochs.remove(epoch.0.to_storage_key());
+ }
+
+ epoch_rewards
+ });
+
+ // Process accumulated rewards for previous epochs.
+ let params = Self::params();
+ 'epochs: for (epoch, rewards) in epoch_rewards {
+ let epoch = epoch.0;
+
+ // Fetch reward schedule for the given epoch.
+ let reward = params.schedule.for_epoch(epoch);
+ if reward.amount().is_zero() {
+ continue;
+ }
+
+ // Disburse rewards.
+ for address in rewards.for_disbursement(
+ params.participation_threshold_numerator,
+ params.participation_threshold_denominator,
+ ) {
+ match <C::Runtime as Runtime>::Accounts::transfer(
+ *ADDRESS_REWARD_POOL,
+ address,
+ &reward,
+ ) {
+ Ok(_) => {}
+ Err(modules::accounts::Error::InsufficientBalance) => {
+ // Since rewards are the same for the whole epoch, if there is not
+ // enough in the pool, just continue with the next epoch which may
+ // specify a lower amount or a different denomination.
+ continue 'epochs;
+ }
+ Err(err) => panic!("failed to disburse rewards: {err:?}"),
+ }
+ }
+ }
+ }
+
+ // Update rewards for current epoch.
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut epochs =
+ storage::TypedStore::new(storage::PrefixStore::new(store, &state::REWARDS));
+ epochs.insert(epoch.to_storage_key(), rewards);
+ });
+ }
+}
+
+impl module::InvariantHandler for Module {}
+
+/// A trait that exists solely to convert `beacon::EpochTime` to bytes for use as a storage key.
+trait ToStorageKey {
+ fn to_storage_key(&self) -> [u8; 8];
+}
+
+impl ToStorageKey for beacon::EpochTime {
+ fn to_storage_key(&self) -> [u8; 8] {
+ self.to_be_bytes()
+ }
+}
+
+/// A struct that exists solely to decode `beacon::EpochTime` previously encoded via `ToStorageKey`.
+struct DecodableEpochTime(beacon::EpochTime);
+
+impl TryFrom<&[u8]> for DecodableEpochTime {
+ type Error = std::array::TryFromSliceError;
+
+ fn try_from(value: &[u8]) -> Result<Self, Self::Error> {
+ Ok(DecodableEpochTime(beacon::EpochTime::from_be_bytes(
+ value.try_into()?,
+ )))
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +
//! Rewards module types.
+use std::collections::BTreeMap;
+
+use thiserror::Error;
+
+use crate::{
+ core::consensus::beacon,
+ types::{address::Address, token},
+};
+
+/// One of the time periods in the reward schedule.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct RewardStep {
+ pub until: beacon::EpochTime,
+ pub amount: token::BaseUnits,
+}
+
+/// A reward schedule.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct RewardSchedule {
+ pub steps: Vec<RewardStep>,
+}
+
+/// Errors emitted during reward schedule validation.
+#[derive(Error, Debug)]
+pub enum RewardScheduleError {
+ #[error("steps not sorted correctly")]
+ StepsNotSorted,
+}
+
+impl RewardSchedule {
+ /// Perform basic reward schedule validation.
+ pub fn validate_basic(&self) -> Result<(), RewardScheduleError> {
+ let mut last_epoch = Default::default();
+ for step in &self.steps {
+ if step.until <= last_epoch {
+ return Err(RewardScheduleError::StepsNotSorted);
+ }
+ last_epoch = step.until;
+ }
+ Ok(())
+ }
+
+ /// Compute the per-entity reward amount for the given epoch based on the schedule.
+ pub fn for_epoch(&self, epoch: beacon::EpochTime) -> token::BaseUnits {
+ for step in &self.steps {
+ if epoch < step.until {
+ return step.amount.clone();
+ }
+ }
+
+ // End of the schedule, default to no rewards.
+ Default::default()
+ }
+}
+
+/// Action that should be taken for a given address when disbursing rewards.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum RewardAction {
+ Reward(u64),
+ NoReward,
+}
+
+impl RewardAction {
+ /// Increment the reward counter associated with the reward.
+ ///
+ /// In case the action is `NoReward` nothing is changed.
+ pub fn increment(&mut self) {
+ match self {
+ RewardAction::Reward(ref mut v) => *v += 1,
+ RewardAction::NoReward => {
+ // Do not change state as the entity has been penalized for the epoch.
+ }
+ }
+ }
+
+ /// Forbids any rewards from accumulating.
+ pub fn forbid(&mut self) {
+ *self = RewardAction::NoReward;
+ }
+
+ /// Value of the reward counter.
+ pub fn value(&self) -> u64 {
+ match self {
+ RewardAction::Reward(v) => *v,
+ RewardAction::NoReward => 0,
+ }
+ }
+}
+
+impl Default for RewardAction {
+ fn default() -> Self {
+ RewardAction::Reward(0)
+ }
+}
+
+impl cbor::Encode for RewardAction {
+ fn into_cbor_value(self) -> cbor::Value {
+ match self {
+ Self::Reward(r) => cbor::Value::Unsigned(r),
+ Self::NoReward => cbor::Value::Simple(cbor::SimpleValue::NullValue),
+ }
+ }
+}
+
+impl cbor::Decode for RewardAction {
+ fn try_default() -> Result<Self, cbor::DecodeError> {
+ Ok(Self::NoReward)
+ }
+
+ fn try_from_cbor_value(value: cbor::Value) -> Result<Self, cbor::DecodeError> {
+ match value {
+ cbor::Value::Unsigned(v) => Ok(Self::Reward(v)),
+ cbor::Value::Simple(cbor::SimpleValue::NullValue) => Ok(Self::NoReward),
+ _ => Err(cbor::DecodeError::UnexpectedType),
+ }
+ }
+}
+
+/// Rewards for the epoch.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct EpochRewards {
+ pub pending: BTreeMap<Address, RewardAction>,
+}
+
+impl EpochRewards {
+ /// Returns an iterator over addresses that should be rewarded.
+ pub fn for_disbursement(
+ &self,
+ threshold_numerator: u64,
+ threshold_denominator: u64,
+ ) -> impl Iterator<Item = Address> + '_ {
+ let max_v = self
+ .pending
+ .iter()
+ .fold(0, |acc, (_, action)| std::cmp::max(acc, action.value()));
+
+ let (_, overflow) = threshold_numerator.overflowing_mul(max_v);
+ let threshold = if overflow {
+ max_v
+ .checked_div(threshold_denominator)
+ .unwrap_or(0)
+ .saturating_mul(threshold_numerator)
+ } else {
+ threshold_numerator
+ .saturating_mul(max_v)
+ .checked_div(threshold_denominator)
+ .unwrap_or(0)
+ };
+
+ self.pending
+ .iter()
+ .filter_map(move |(address, action)| match action {
+ RewardAction::Reward(v) => {
+ if *v < threshold {
+ None
+ } else {
+ Some(*address)
+ }
+ }
+ RewardAction::NoReward => None,
+ })
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use crate::testing::keys;
+
+ use super::*;
+
+ #[test]
+ fn test_reward_action() {
+ let mut act = RewardAction::default();
+ act.increment();
+ act.increment();
+ act.increment();
+
+ assert!(matches!(act, RewardAction::Reward(3)));
+
+ act.forbid();
+
+ act.increment();
+ act.increment();
+
+ assert!(matches!(act, RewardAction::NoReward));
+ }
+
+ #[test]
+ fn test_reward_action_serialization() {
+ let actions = vec![
+ RewardAction::Reward(0),
+ RewardAction::Reward(42),
+ RewardAction::NoReward,
+ ];
+ for act in actions {
+ let encoded = &cbor::to_vec(act.clone());
+ let round_trip: RewardAction =
+ cbor::from_slice(encoded).expect("round-trip should succeed");
+ assert_eq!(round_trip, act, "reward actions should round-trip");
+ }
+ }
+
+ #[test]
+ fn test_reward_schedule_validation_fail_1() {
+ let schedule = RewardSchedule {
+ steps: vec![
+ RewardStep {
+ until: 10,
+ amount: token::BaseUnits::new(1000, token::Denomination::NATIVE),
+ },
+ RewardStep {
+ until: 10,
+ amount: token::BaseUnits::new(1000, token::Denomination::NATIVE),
+ },
+ RewardStep {
+ until: 15,
+ amount: token::BaseUnits::new(1000, token::Denomination::NATIVE),
+ },
+ ],
+ };
+ schedule
+ .validate_basic()
+ .expect_err("validation with duplicate steps should fail");
+ }
+
+ #[test]
+ fn test_reward_schedule_validation_fail_2() {
+ let schedule = RewardSchedule {
+ steps: vec![
+ RewardStep {
+ until: 10,
+ amount: token::BaseUnits::new(1000, token::Denomination::NATIVE),
+ },
+ RewardStep {
+ until: 5,
+ amount: token::BaseUnits::new(1000, token::Denomination::NATIVE),
+ },
+ RewardStep {
+ until: 15,
+ amount: token::BaseUnits::new(1000, token::Denomination::NATIVE),
+ },
+ ],
+ };
+ schedule
+ .validate_basic()
+ .expect_err("validation with unsorted steps should fail");
+ }
+
+ #[test]
+ fn test_reward_schedule_validation_ok() {
+ let schedule = RewardSchedule {
+ steps: vec![
+ RewardStep {
+ until: 5,
+ amount: token::BaseUnits::new(1000, token::Denomination::NATIVE),
+ },
+ RewardStep {
+ until: 10,
+ amount: token::BaseUnits::new(1000, token::Denomination::NATIVE),
+ },
+ RewardStep {
+ until: 15,
+ amount: token::BaseUnits::new(1000, token::Denomination::NATIVE),
+ },
+ ],
+ };
+ schedule
+ .validate_basic()
+ .expect("validation of correct schedule should not fail");
+ }
+
+ #[test]
+ fn test_reward_schedule() {
+ let schedule = RewardSchedule {
+ steps: vec![
+ RewardStep {
+ until: 5,
+ amount: token::BaseUnits::new(3000, token::Denomination::NATIVE),
+ },
+ RewardStep {
+ until: 10,
+ amount: token::BaseUnits::new(2000, token::Denomination::NATIVE),
+ },
+ RewardStep {
+ until: 15,
+ amount: token::BaseUnits::new(1000, token::Denomination::NATIVE),
+ },
+ ],
+ };
+
+ assert_eq!(schedule.for_epoch(1).amount(), 3000);
+ assert_eq!(schedule.for_epoch(3).amount(), 3000);
+ assert_eq!(schedule.for_epoch(5).amount(), 2000);
+ assert_eq!(schedule.for_epoch(6).amount(), 2000);
+ assert_eq!(schedule.for_epoch(9).amount(), 2000);
+ assert_eq!(schedule.for_epoch(10).amount(), 1000);
+ assert_eq!(schedule.for_epoch(14).amount(), 1000);
+ assert_eq!(schedule.for_epoch(15).amount(), 0);
+ assert_eq!(schedule.for_epoch(20).amount(), 0);
+ assert_eq!(schedule.for_epoch(100).amount(), 0);
+ }
+
+ #[test]
+ fn test_epoch_rewards() {
+ let epoch_rewards = EpochRewards {
+ pending: {
+ let mut pending = BTreeMap::new();
+ pending.insert(keys::alice::address(), RewardAction::Reward(10));
+ pending.insert(keys::bob::address(), RewardAction::NoReward);
+ pending.insert(keys::charlie::address(), RewardAction::Reward(5));
+ pending
+ },
+ };
+
+ // Alice and Charlie have >= 0.
+ let rewards: Vec<_> = epoch_rewards.for_disbursement(0, 0).collect();
+ assert_eq!(
+ rewards,
+ vec![keys::charlie::address(), keys::alice::address()]
+ );
+ // Alice and Charlie have >= 0.
+ let rewards: Vec<_> = epoch_rewards.for_disbursement(0, 0).collect();
+ assert_eq!(
+ rewards,
+ vec![keys::charlie::address(), keys::alice::address()]
+ );
+ // Only Alice has >= 7.5.
+ let rewards: Vec<_> = epoch_rewards.for_disbursement(3, 4).collect();
+ assert_eq!(rewards, vec![keys::alice::address()]);
+ }
+
+ #[test]
+ fn test_epoch_rewards_overflow() {
+ let epoch_rewards = EpochRewards {
+ pending: {
+ let mut pending = BTreeMap::new();
+ pending.insert(keys::alice::address(), RewardAction::Reward(u64::MAX));
+ pending.insert(keys::charlie::address(), RewardAction::Reward(u64::MAX / 2));
+ pending
+ },
+ };
+
+ // Alice and Charlie have >= 0.
+ let rewards: Vec<_> = epoch_rewards.for_disbursement(0, 0).collect();
+ assert_eq!(
+ rewards,
+ vec![keys::charlie::address(), keys::alice::address()]
+ );
+ // Alice and Charlie have >= 1/2.
+ let rewards: Vec<_> = epoch_rewards.for_disbursement(1, 2).collect();
+ assert_eq!(
+ rewards,
+ vec![keys::charlie::address(), keys::alice::address()]
+ );
+ // Only Alice has >= 3/4, but due to overflow both will be counted.
+ let rewards: Vec<_> = epoch_rewards.for_disbursement(3, 4).collect();
+ assert_eq!(rewards, vec![keys::alice::address()]);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +
use std::{
+ collections::{BTreeMap, HashSet},
+ sync::{
+ atomic::{AtomicU64, Ordering},
+ Arc,
+ },
+ time::Duration,
+};
+
+use anyhow::{anyhow, Result};
+use tokio::sync::{mpsc, oneshot};
+
+use crate::{
+ core::{
+ consensus::{
+ registry::{SGXConstraints, TEEHardware},
+ state::{
+ beacon::ImmutableState as BeaconState, registry::ImmutableState as RegistryState,
+ },
+ },
+ enclave_rpc::{client::RpcClient, session},
+ host::{self, Host as _},
+ },
+ crypto::signature::{PublicKey, Signer},
+ enclave_rpc::{QueryRequest, METHOD_QUERY},
+ modules::{accounts::types::NonceQuery, core::types::EstimateGasQuery},
+ state::CurrentState,
+ storage::HostStore,
+ types::{
+ address::{Address, SignatureAddressSpec},
+ token,
+ transaction::{self, CallerAddress},
+ },
+};
+
+use super::{processor, App};
+
+/// Size of various command queues.
+const CMDQ_BACKLOG: usize = 16;
+
+/// EnclaveRPC endpoint for communicating with the RONL component.
+const ENCLAVE_RPC_ENDPOINT_RONL: &str = "ronl";
+
+/// Transaction submission options.
+#[derive(Clone, Debug)]
+pub struct SubmitTxOpts {
+ /// Optional timeout when submitting a transaction. Setting this to `None` means that the host
+ /// node timeout will be used.
+ pub timeout: Option<Duration>,
+}
+
+impl Default for SubmitTxOpts {
+ fn default() -> Self {
+ Self {
+ timeout: Some(Duration::from_millis(15_000)), // 15 seconds.
+ }
+ }
+}
+
+/// A runtime client meant for use within runtimes.
+pub struct Client<A: App> {
+ imp: ClientImpl<A>,
+ submission_mgr: Arc<SubmissionManager<A>>,
+}
+
+impl<A> Client<A>
+where
+ A: App,
+{
+ /// Create a new runtime client.
+ pub(super) fn new(
+ state: Arc<processor::State<A>>,
+ cmdq: mpsc::WeakSender<processor::Command>,
+ ) -> Self {
+ let imp = ClientImpl::new(state, cmdq);
+ let mut submission_mgr = SubmissionManager::new(imp.clone());
+ submission_mgr.start();
+
+ Self {
+ imp,
+ submission_mgr: Arc::new(submission_mgr),
+ }
+ }
+
+ /// Retrieve the latest known runtime round.
+ pub async fn latest_round(&self) -> Result<u64> {
+ self.imp.latest_round().await
+ }
+
+ /// Retrieve the nonce for the given account.
+ pub async fn account_nonce(&self, round: u64, address: Address) -> Result<u64> {
+ self.imp.account_nonce(round, address).await
+ }
+
+ /// Retrieve the gas price in the given denomination.
+ pub async fn gas_price(&self, round: u64, denom: &token::Denomination) -> Result<u128> {
+ self.imp.gas_price(round, denom).await
+ }
+
+ /// Securely query the on-chain runtime component.
+ pub async fn query<Rq, Rs>(&self, round: u64, method: &str, args: Rq) -> Result<Rs>
+ where
+ Rq: cbor::Encode,
+ Rs: cbor::Decode + Send + 'static,
+ {
+ self.imp.query(round, method, args).await
+ }
+
+ /// Securely perform gas estimation.
+ pub async fn estimate_gas(&self, req: EstimateGasQuery) -> Result<u64> {
+ self.imp.estimate_gas(req).await
+ }
+
+ /// Sign a given transaction, submit it and wait for block inclusion.
+ ///
+ /// This method supports multiple transaction signers.
+ pub async fn multi_sign_and_submit_tx(
+ &self,
+ signers: &[Arc<dyn Signer>],
+ tx: transaction::Transaction,
+ ) -> Result<transaction::CallResult> {
+ self.multi_sign_and_submit_tx_opts(signers, tx, SubmitTxOpts::default())
+ .await
+ }
+
+ /// Sign a given transaction, submit it and wait for block inclusion.
+ ///
+ /// This method supports multiple transaction signers.
+ pub async fn multi_sign_and_submit_tx_opts(
+ &self,
+ signers: &[Arc<dyn Signer>],
+ tx: transaction::Transaction,
+ opts: SubmitTxOpts,
+ ) -> Result<transaction::CallResult> {
+ self.submission_mgr
+ .multi_sign_and_submit_tx(signers, tx, opts)
+ .await
+ }
+
+ /// Sign a given transaction, submit it and wait for block inclusion.
+ pub async fn sign_and_submit_tx(
+ &self,
+ signer: Arc<dyn Signer>,
+ tx: transaction::Transaction,
+ ) -> Result<transaction::CallResult> {
+ self.multi_sign_and_submit_tx(&[signer], tx).await
+ }
+
+ /// Run a closure inside a `CurrentState` context with store for the given round.
+ pub async fn with_store_for_round<F, R>(&self, round: u64, f: F) -> Result<R>
+ where
+ F: FnOnce() -> Result<R> + Send + 'static,
+ R: Send + 'static,
+ {
+ self.imp.with_store_for_round(round, f).await
+ }
+
+ /// Return a store corresponding to the given round.
+ pub async fn store_for_round(&self, round: u64) -> Result<HostStore> {
+ self.imp.store_for_round(round).await
+ }
+}
+
+impl<A> Clone for Client<A>
+where
+ A: App,
+{
+ fn clone(&self) -> Self {
+ Self {
+ imp: self.imp.clone(),
+ submission_mgr: self.submission_mgr.clone(),
+ }
+ }
+}
+
+struct ClientImpl<A: App> {
+ state: Arc<processor::State<A>>,
+ cmdq: mpsc::WeakSender<processor::Command>,
+ latest_round: Arc<AtomicU64>,
+ rpc: Arc<RpcClient>,
+}
+
+impl<A> ClientImpl<A>
+where
+ A: App,
+{
+ fn new(state: Arc<processor::State<A>>, cmdq: mpsc::WeakSender<processor::Command>) -> Self {
+ Self {
+ cmdq,
+ latest_round: Arc::new(AtomicU64::new(0)),
+ rpc: Arc::new(RpcClient::new_runtime(
+ state.host.clone(),
+ ENCLAVE_RPC_ENDPOINT_RONL,
+ session::Builder::default()
+ .use_endorsement(true)
+ .quote_policy(None) // Forbid all until configured.
+ .local_identity(state.identity.clone())
+ .remote_enclaves(Some(HashSet::new())), // Forbid all until configured.
+ 2, // Maximum number of sessions (one extra for reserve).
+ 1, // Maximum number of sessions per peer (we only communicate with RONL).
+ 1, // Stale session timeout.
+ )),
+ state,
+ }
+ }
+
+ /// Retrieve the latest known runtime round.
+ async fn latest_round(&self) -> Result<u64> {
+ let cmdq = self
+ .cmdq
+ .upgrade()
+ .ok_or(anyhow!("processor has shut down"))?;
+ let (tx, rx) = oneshot::channel();
+ cmdq.send(processor::Command::GetLatestRound(tx)).await?;
+ let round = rx.await?;
+ Ok(self
+ .latest_round
+ .fetch_max(round, Ordering::SeqCst)
+ .max(round))
+ }
+
+ /// Retrieve the nonce for the given account.
+ async fn account_nonce(&self, round: u64, address: Address) -> Result<u64> {
+ self.query(round, "accounts.Nonce", NonceQuery { address })
+ .await
+ }
+
+ /// Retrieve the gas price in the given denomination.
+ async fn gas_price(&self, round: u64, denom: &token::Denomination) -> Result<u128> {
+ let mgp: BTreeMap<token::Denomination, u128> =
+ self.query(round, "core.MinGasPrice", ()).await?;
+ mgp.get(denom)
+ .ok_or(anyhow!("denomination not supported"))
+ .copied()
+ }
+
+ /// Securely query the on-chain runtime component.
+ async fn query<Rq, Rs>(&self, round: u64, method: &str, args: Rq) -> Result<Rs>
+ where
+ Rq: cbor::Encode,
+ Rs: cbor::Decode + Send + 'static,
+ {
+ // TODO: Consider using PolicyVerifier when it has the needed methods (and is async).
+ let state = self.state.consensus_verifier.latest_state().await?;
+ let runtime_id = self.state.host.get_runtime_id();
+ let tee = tokio::task::spawn_blocking(move || -> Result<_> {
+ let beacon = BeaconState::new(&state);
+ let epoch = beacon.epoch()?;
+ let registry = RegistryState::new(&state);
+ let runtime = registry
+ .runtime(&runtime_id)?
+ .ok_or(anyhow!("runtime not available"))?;
+ let ad = runtime
+ .active_deployment(epoch)
+ .ok_or(anyhow!("active runtime deployment not available"))?;
+
+ match runtime.tee_hardware {
+ TEEHardware::TEEHardwareIntelSGX => Ok(ad.try_decode_tee::<SGXConstraints>()?),
+ _ => Err(anyhow!("unsupported TEE platform")),
+ }
+ })
+ .await??;
+
+ let enclaves = HashSet::from_iter(tee.enclaves().clone());
+ let quote_policy = tee.policy();
+ self.rpc.update_enclaves(Some(enclaves)).await;
+ self.rpc.update_quote_policy(quote_policy).await;
+
+ let response: Vec<u8> = self
+ .rpc
+ .secure_call(
+ METHOD_QUERY,
+ QueryRequest {
+ round,
+ method: method.to_string(),
+ args: cbor::to_vec(args),
+ },
+ vec![],
+ )
+ .await
+ .into_result()?;
+
+ Ok(cbor::from_slice(&response)?)
+ }
+
+ /// Securely perform gas estimation.
+ async fn estimate_gas(&self, req: EstimateGasQuery) -> Result<u64> {
+ let round = self.latest_round().await?;
+ self.query(round, "core.EstimateGas", req).await
+ }
+
+ /// Run a closure inside a `CurrentState` context with store for the given round.
+ async fn with_store_for_round<F, R>(&self, round: u64, f: F) -> Result<R>
+ where
+ F: FnOnce() -> Result<R> + Send + 'static,
+ R: Send + 'static,
+ {
+ let store = self.store_for_round(round).await?;
+
+ tokio::task::spawn_blocking(move || CurrentState::enter(store, f)).await?
+ }
+
+ /// Return a store corresponding to the given round.
+ async fn store_for_round(&self, round: u64) -> Result<HostStore> {
+ HostStore::new_for_round(
+ self.state.host.clone(),
+ &self.state.consensus_verifier,
+ self.state.host.get_runtime_id(),
+ round,
+ )
+ .await
+ }
+}
+
+impl<A> Clone for ClientImpl<A>
+where
+ A: App,
+{
+ fn clone(&self) -> Self {
+ Self {
+ state: self.state.clone(),
+ cmdq: self.cmdq.clone(),
+ latest_round: self.latest_round.clone(),
+ rpc: self.rpc.clone(),
+ }
+ }
+}
+
+enum Cmd {
+ SubmitTx(
+ Vec<Arc<dyn Signer>>,
+ transaction::Transaction,
+ SubmitTxOpts,
+ oneshot::Sender<Result<transaction::CallResult>>,
+ ),
+}
+
+/// Transaction submission manager for avoiding nonce conflicts.
+struct SubmissionManager<A: App> {
+ imp: Option<SubmissionManagerImpl<A>>,
+ cmdq_tx: mpsc::Sender<Cmd>,
+}
+
+impl<A> SubmissionManager<A>
+where
+ A: App,
+{
+ /// Create a new submission manager.
+ fn new(client: ClientImpl<A>) -> Self {
+ let (tx, rx) = mpsc::channel(CMDQ_BACKLOG);
+
+ Self {
+ imp: Some(SubmissionManagerImpl {
+ client,
+ cmdq_rx: rx,
+ }),
+ cmdq_tx: tx,
+ }
+ }
+
+ /// Start the submission manager task.
+ fn start(&mut self) {
+ if let Some(imp) = self.imp.take() {
+ imp.start();
+ }
+ }
+
+ /// Sign a given transaction, submit it and wait for block inclusion.
+ async fn multi_sign_and_submit_tx(
+ &self,
+ signers: &[Arc<dyn Signer>],
+ tx: transaction::Transaction,
+ opts: SubmitTxOpts,
+ ) -> Result<transaction::CallResult> {
+ let (ch, rx) = oneshot::channel();
+ self.cmdq_tx
+ .send(Cmd::SubmitTx(signers.to_vec(), tx, opts, ch))
+ .await?;
+ rx.await?
+ }
+}
+
+struct SubmissionManagerImpl<A: App> {
+ client: ClientImpl<A>,
+ cmdq_rx: mpsc::Receiver<Cmd>,
+}
+
+impl<A> SubmissionManagerImpl<A>
+where
+ A: App,
+{
+ /// Start the submission manager task.
+ fn start(self) {
+ tokio::task::spawn(self.run());
+ }
+
+ /// Run the submission manager task.
+ async fn run(mut self) {
+ let (notify_tx, mut notify_rx) = mpsc::channel::<HashSet<PublicKey>>(CMDQ_BACKLOG);
+ let mut queue: Vec<Cmd> = Vec::new();
+ let mut pending: HashSet<PublicKey> = HashSet::new();
+
+ loop {
+ tokio::select! {
+ // Process incoming commands.
+ Some(cmd) = self.cmdq_rx.recv() => queue.push(cmd),
+
+ // Process incoming completion notifications.
+ Some(signers) = notify_rx.recv() => {
+ for pk in signers {
+ pending.remove(&pk);
+ }
+ },
+
+ else => break,
+ }
+
+ // Check if there is anything in the queue that can be executed without conflicts.
+ let mut new_queue = Vec::with_capacity(queue.len());
+ for cmd in queue {
+ match cmd {
+ Cmd::SubmitTx(signers, tx, opts, ch) => {
+ // Check if transaction can be executed (no conflicts with in-flight txs).
+ let signer_set =
+ HashSet::from_iter(signers.iter().map(|signer| signer.public_key()));
+ if !signer_set.is_disjoint(&pending) {
+ // Defer any non-executable commands.
+ new_queue.push(Cmd::SubmitTx(signers, tx, opts, ch));
+ continue;
+ }
+ // Include all signers in the pending set.
+ pending.extend(signer_set.iter().cloned());
+
+ // Execute in a separate task.
+ let client = self.client.clone();
+ let notify_tx = notify_tx.clone();
+
+ tokio::spawn(async move {
+ let result =
+ Self::multi_sign_and_submit_tx(client, &signers, tx, opts).await;
+ let _ = ch.send(result);
+
+ // Notify the submission manager task that submission is done.
+ let _ = notify_tx.send(signer_set).await;
+ });
+ }
+ }
+ }
+ queue = new_queue;
+ }
+ }
+
+ /// Sign a given transaction, submit it and wait for block inclusion.
+ async fn multi_sign_and_submit_tx(
+ client: ClientImpl<A>,
+ signers: &[Arc<dyn Signer>],
+ mut tx: transaction::Transaction,
+ opts: SubmitTxOpts,
+ ) -> Result<transaction::CallResult> {
+ if signers.is_empty() {
+ return Err(anyhow!("no signers specified"));
+ }
+
+ // Resolve signer addresses.
+ let addresses = signers
+ .iter()
+ .map(|signer| -> Result<_> {
+ let sigspec = SignatureAddressSpec::try_from_pk(&signer.public_key())
+ .ok_or(anyhow!("signature scheme not supported"))?;
+ Ok((Address::from_sigspec(&sigspec), sigspec))
+ })
+ .collect::<Result<Vec<_>>>()?;
+
+ let round = client.latest_round().await?;
+
+ // Resolve account nonces.
+ for (address, sigspec) in &addresses {
+ let nonce = client.account_nonce(round, *address).await?;
+
+ tx.append_auth_signature(sigspec.clone(), nonce);
+ }
+
+ // Perform gas estimation after all signer infos have been added as otherwise we may
+ // underestimate the amount of gas needed.
+ if tx.fee_gas() == 0 {
+ let signer = &signers[0]; // Checked to have at least one signer above.
+ let gas = client
+ .estimate_gas(EstimateGasQuery {
+ caller: if let PublicKey::Secp256k1(pk) = signer.public_key() {
+ Some(CallerAddress::EthAddress(
+ pk.to_eth_address().try_into().unwrap(),
+ ))
+ } else {
+ Some(CallerAddress::Address(addresses[0].0)) // Checked above.
+ },
+ tx: tx.clone(),
+ propagate_failures: false,
+ })
+ .await?;
+
+ // The estimate may be off due to current limitations in confidential gas estimation.
+ // Inflate the estimated gas by 20%.
+ let gas = gas.saturating_add(gas.saturating_mul(20).saturating_div(100));
+
+ tx.set_fee_gas(gas);
+ }
+
+ // Determine gas price. Currently we always use the native denomination.
+ let mgp = client
+ .gas_price(round, &token::Denomination::NATIVE)
+ .await?;
+ let fee = mgp.saturating_mul(tx.fee_gas().into());
+ tx.set_fee_amount(token::BaseUnits::new(fee, token::Denomination::NATIVE));
+
+ // Sign the transaction.
+ let mut tx = tx.prepare_for_signing();
+ for signer in signers {
+ tx.append_sign(signer)?;
+ }
+ let tx = tx.finalize();
+
+ // Submit the transaction.
+ let submit_tx_task = client.state.host.submit_tx(
+ cbor::to_vec(tx),
+ host::SubmitTxOpts {
+ wait: true,
+ ..Default::default()
+ },
+ );
+ let result = if let Some(timeout) = opts.timeout {
+ tokio::time::timeout(timeout, submit_tx_task).await?
+ } else {
+ submit_tx_task.await
+ };
+ let result = result?.ok_or(anyhow!("missing result"))?;
+
+ // Update latest known round.
+ client
+ .latest_round
+ .fetch_max(result.round, Ordering::SeqCst);
+
+ cbor::from_slice(&result.output).map_err(|_| anyhow!("malformed result"))
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +
use std::sync::Arc;
+
+use anyhow::{anyhow, Result};
+use tokio::sync::mpsc;
+
+use crate::crypto::signature::Signer;
+
+use super::{client, processor, App};
+
+/// Application environment.
+pub struct Environment<A: App> {
+ client: client::Client<A>,
+ signer: Arc<dyn Signer>,
+ cmdq: mpsc::WeakSender<processor::Command>,
+}
+
+impl<A> Environment<A>
+where
+ A: App,
+{
+ /// Create a new environment talking to the given processor.
+ pub(super) fn new(
+ state: Arc<processor::State<A>>,
+ cmdq: mpsc::WeakSender<processor::Command>,
+ ) -> Self {
+ Self {
+ signer: state.signer.clone(),
+ client: client::Client::new(state, cmdq.clone()),
+ cmdq,
+ }
+ }
+
+ /// Runtime client.
+ pub fn client(&self) -> &client::Client<A> {
+ &self.client
+ }
+
+ /// Transaction signer.
+ pub fn signer(&self) -> Arc<dyn Signer> {
+ self.signer.clone()
+ }
+
+ /// Send a command to the processor.
+ pub(super) async fn send_command(&self, cmd: processor::Command) -> Result<()> {
+ let cmdq = self
+ .cmdq
+ .upgrade()
+ .ok_or(anyhow!("processor has shut down"))?;
+ cmdq.send(cmd).await?;
+ Ok(())
+ }
+}
+
+impl<A> Clone for Environment<A>
+where
+ A: App,
+{
+ fn clone(&self) -> Self {
+ Self {
+ signer: self.signer.clone(),
+ client: self.client.clone(),
+ cmdq: self.cmdq.clone(),
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +
//! Wrapper to make development of ROFL components easier.
+use std::sync::Arc;
+
+use anyhow::Result;
+use async_trait::async_trait;
+use tokio::sync::mpsc;
+
+use crate::{
+ core::{
+ app,
+ common::version,
+ config::Config,
+ consensus::{roothash, verifier::TrustRoot},
+ dispatcher::{PostInitState, PreInitState},
+ start_runtime,
+ },
+ crypto,
+ types::transaction,
+};
+
+mod client;
+mod env;
+mod notifier;
+pub mod prelude;
+mod processor;
+mod registration;
+
+pub use crate::modules::rofl::app_id::AppId;
+pub use client::Client;
+pub use env::Environment;
+
+/// ROFL component application.
+#[allow(unused_variables)]
+#[async_trait]
+pub trait App: Send + Sync + 'static {
+ /// ROFL application version.
+ const VERSION: version::Version;
+
+ /// Identifier of the application (used for registrations).
+ fn id() -> AppId;
+
+ /// Return the consensus layer trust root for this runtime; if `None`, consensus layer integrity
+ /// verification will not be performed.
+ fn consensus_trust_root() -> Option<TrustRoot>;
+
+ /// Create a new unsigned transaction.
+ fn new_transaction<B>(&self, method: &str, body: B) -> transaction::Transaction
+ where
+ B: cbor::Encode,
+ {
+ let mut tx = transaction::Transaction::new(method, body);
+ // Make the ROFL module resolve the payer for all of our transactions.
+ tx.set_fee_proxy("rofl", Self::id().as_ref());
+ tx
+ }
+
+ /// Main application processing loop.
+ async fn run(self: Arc<Self>, env: Environment<Self>)
+ where
+ Self: Sized,
+ {
+ // Default implementation does nothing.
+ }
+
+ /// Logic that runs on each runtime block. Only one of these will run concurrently.
+ async fn on_runtime_block(self: Arc<Self>, env: Environment<Self>, round: u64)
+ where
+ Self: Sized,
+ {
+ // Default implementation does nothing.
+ }
+
+ /// Start the application.
+ fn start(self)
+ where
+ Self: Sized,
+ {
+ start_runtime(
+ Box::new(|state: PreInitState<'_>| -> PostInitState {
+ // Fetch host information and configure domain separation context.
+ let hi = state.protocol.get_host_info();
+ crypto::signature::context::set_chain_context(
+ hi.runtime_id,
+ &hi.consensus_chain_context,
+ );
+
+ PostInitState {
+ app: Some(Box::new(AppWrapper::new(self, &state))),
+ ..Default::default()
+ }
+ }),
+ Config {
+ version: Self::VERSION,
+ trust_root: Self::consensus_trust_root(),
+ ..Default::default()
+ },
+ );
+ }
+}
+
+struct AppWrapper {
+ cmdq: mpsc::Sender<processor::Command>,
+}
+
+impl AppWrapper {
+ fn new<A>(app: A, state: &PreInitState<'_>) -> Self
+ where
+ A: App,
+ {
+ Self {
+ cmdq: processor::Processor::start(app, state),
+ }
+ }
+}
+
+#[async_trait]
+impl app::App for AppWrapper {
+ async fn on_runtime_block(&self, blk: &roothash::AnnotatedBlock) -> Result<()> {
+ self.cmdq
+ .send(processor::Command::ProcessRuntimeBlock(blk.clone()))
+ .await?;
+ Ok(())
+ }
+
+ async fn on_runtime_event(
+ &self,
+ _blk: &roothash::AnnotatedBlock,
+ _tags: &[Vec<u8>],
+ ) -> Result<()> {
+ Ok(())
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +
use std::sync::Arc;
+
+use anyhow::Result;
+use tokio::sync::mpsc;
+
+use crate::core::common::logger::get_logger;
+
+use super::{processor, App, Environment};
+
+/// Notification to deliver to the application.
+pub(super) enum Notify {
+ RuntimeBlock(u64),
+ RuntimeBlockDone,
+ InitialRegistrationCompleted,
+}
+
+#[derive(Default)]
+struct NotifyState {
+ pending: bool,
+ running: bool,
+}
+
+/// Application notifier task.
+pub(super) struct Task<A: App> {
+ imp: Option<Impl<A>>,
+ tx: mpsc::Sender<Notify>,
+}
+
+impl<A> Task<A>
+where
+ A: App,
+{
+ /// Create an application notifier task.
+ pub(super) fn new(state: Arc<processor::State<A>>, env: Environment<A>) -> Self {
+ let (tx, rx) = mpsc::channel(16);
+
+ let imp = Impl {
+ state,
+ env,
+ logger: get_logger("modules/rofl/app/notifier"),
+ notify: rx,
+ notify_tx: tx.downgrade(),
+ };
+
+ Self { imp: Some(imp), tx }
+ }
+
+ /// Start the application notifier task.
+ pub(super) fn start(&mut self) {
+ if let Some(imp) = self.imp.take() {
+ imp.start();
+ }
+ }
+
+ /// Deliver a notification.
+ pub(super) async fn notify(&self, notification: Notify) -> Result<()> {
+ self.tx.send(notification).await?;
+ Ok(())
+ }
+}
+
+struct Impl<A: App> {
+ state: Arc<processor::State<A>>,
+ env: Environment<A>,
+ logger: slog::Logger,
+
+ notify: mpsc::Receiver<Notify>,
+ notify_tx: mpsc::WeakSender<Notify>,
+}
+
+impl<A> Impl<A>
+where
+ A: App,
+{
+ /// Start the application notifier task.
+ pub(super) fn start(self) {
+ tokio::task::spawn(self.run());
+ }
+
+ /// Run the application notifier task.
+ async fn run(mut self) {
+ slog::info!(self.logger, "starting notifier task");
+
+ // Pending notifications.
+ let mut registered = false;
+ let mut block = NotifyState::default();
+ let mut last_round = 0;
+
+ while let Some(notification) = self.notify.recv().await {
+ match notification {
+ Notify::RuntimeBlock(round) if registered => {
+ block.pending = true;
+ last_round = round;
+ }
+ Notify::RuntimeBlock(_) => continue, // Skip blocks before registration.
+ Notify::RuntimeBlockDone => block.running = false,
+ Notify::InitialRegistrationCompleted => registered = true,
+ }
+
+ // Don't do anything unless registered.
+ if !registered {
+ continue;
+ }
+
+ // Block notifications.
+ if block.pending && !block.running {
+ block.pending = false;
+ block.running = true;
+
+ let notify_tx = self.notify_tx.clone();
+ let app = self.state.app.clone();
+ let env = self.env.clone();
+
+ tokio::spawn(async move {
+ app.on_runtime_block(env, last_round).await;
+ if let Some(tx) = notify_tx.upgrade() {
+ let _ = tx.send(Notify::RuntimeBlockDone).await;
+ }
+ });
+ }
+ }
+
+ slog::info!(self.logger, "notifier task stopped");
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +
use std::sync::Arc;
+
+use anyhow::{anyhow, Result};
+use tokio::sync::{mpsc, oneshot};
+
+use crate::{
+ core::{
+ common::logger::get_logger,
+ consensus::{roothash, verifier::Verifier},
+ dispatcher::PreInitState,
+ host::{self, Host as _},
+ identity::Identity,
+ protocol::Protocol,
+ },
+ crypto::signature::{secp256k1, Signer},
+};
+use rand::rngs::OsRng;
+
+use super::{notifier, registration, App, Environment};
+
+/// Size of the processor command queue.
+const CMDQ_BACKLOG: usize = 32;
+
+/// Command sent to the processor task.
+#[allow(clippy::large_enum_variant)]
+#[derive(Debug)]
+pub(super) enum Command {
+ /// Process a notification of a new runtime block.
+ ProcessRuntimeBlock(roothash::AnnotatedBlock),
+ /// Retrieve the latest known round.
+ GetLatestRound(oneshot::Sender<u64>),
+ /// Notification that initial registration has been completed.
+ InitialRegistrationCompleted,
+}
+
+/// Processor state.
+pub(super) struct State<A: App> {
+ pub(super) identity: Arc<Identity>,
+ pub(super) host: Arc<Protocol>,
+ pub(super) consensus_verifier: Arc<dyn Verifier>,
+ pub(super) signer: Arc<dyn Signer>,
+ pub(super) app: Arc<A>,
+}
+
+struct Tasks<A: App> {
+ registration: registration::Task<A>,
+ notifier: notifier::Task<A>,
+}
+
+/// Processor.
+pub(super) struct Processor<A: App> {
+ state: Arc<State<A>>,
+ env: Environment<A>,
+ tasks: Tasks<A>,
+ cmdq: mpsc::Receiver<Command>,
+ logger: slog::Logger,
+
+ latest_round: u64,
+}
+
+impl<A> Processor<A>
+where
+ A: App,
+{
+ /// Create and start a new processor.
+ pub(super) fn start(app: A, state: &PreInitState<'_>) -> mpsc::Sender<Command> {
+ // Create the command channel.
+ let (tx, rx) = mpsc::channel(CMDQ_BACKLOG);
+
+ // Provision keys. Currently we provision a random key for signing transactions to avoid
+ // using the RAK directly as the RAK is an Ed25519 key which cannot easily be used for EVM
+ // calls due to the limitations of the current implementation.
+ let signer = secp256k1::MemorySigner::random(&mut OsRng).unwrap();
+
+ // Prepare state.
+ let state = Arc::new(State {
+ identity: state.identity.clone(),
+ host: state.protocol.clone(),
+ consensus_verifier: state.consensus_verifier.clone(),
+ signer: Arc::new(signer),
+ app: Arc::new(app),
+ });
+
+ // Prepare application environment.
+ let env = Environment::new(state.clone(), tx.downgrade());
+
+ // Create the processor and start it.
+ let processor = Self {
+ tasks: Tasks {
+ registration: registration::Task::new(state.clone(), env.clone()),
+ notifier: notifier::Task::new(state.clone(), env.clone()),
+ },
+ state,
+ env,
+ cmdq: rx,
+ logger: get_logger("modules/rofl/app"),
+ latest_round: 0,
+ };
+ tokio::spawn(processor.run());
+
+ tx
+ }
+
+ /// Run the processor.
+ async fn run(mut self) {
+ slog::info!(self.logger, "starting processor";
+ "app_id" => A::id(),
+ );
+
+ // Register for notifications.
+ if let Err(err) = self
+ .state
+ .host
+ .register_notify(host::RegisterNotifyOpts {
+ runtime_block: true,
+ runtime_event: vec![],
+ })
+ .await
+ {
+ slog::error!(self.logger, "failed to register for notifications";
+ "err" => ?err,
+ );
+ }
+
+ // Start the tasks.
+ self.tasks.registration.start();
+ self.tasks.notifier.start();
+
+ slog::info!(self.logger, "entering processor loop");
+ while let Some(cmd) = self.cmdq.recv().await {
+ if let Err(err) = self.process(cmd).await {
+ slog::error!(self.logger, "failed to process command";
+ "err" => ?err,
+ );
+ }
+ }
+
+ slog::info!(self.logger, "processor stopped");
+ }
+
+ /// Process a command.
+ async fn process(&mut self, cmd: Command) -> Result<()> {
+ match cmd {
+ Command::ProcessRuntimeBlock(blk) => self.cmd_process_runtime_block(blk).await,
+ Command::GetLatestRound(ch) => self.cmd_get_latest_round(ch).await,
+ Command::InitialRegistrationCompleted => {
+ self.cmd_initial_registration_completed().await
+ }
+ }
+ }
+
+ async fn cmd_process_runtime_block(&mut self, blk: roothash::AnnotatedBlock) -> Result<()> {
+ // Update latest known round.
+ if blk.block.header.round <= self.latest_round {
+ return Err(anyhow!("round seems to have moved backwards"));
+ }
+ self.latest_round = blk.block.header.round;
+
+ // Notify registration task.
+ self.tasks.registration.refresh();
+ // Notify notifier task.
+ let _ = self
+ .tasks
+ .notifier
+ .notify(notifier::Notify::RuntimeBlock(self.latest_round))
+ .await;
+
+ Ok(())
+ }
+
+ async fn cmd_get_latest_round(&self, ch: oneshot::Sender<u64>) -> Result<()> {
+ let _ = ch.send(self.latest_round);
+ Ok(())
+ }
+
+ async fn cmd_initial_registration_completed(&self) -> Result<()> {
+ slog::info!(
+ self.logger,
+ "initial registration completed, starting application"
+ );
+
+ // Start application after first registration.
+ tokio::spawn(self.state.app.clone().run(self.env.clone()));
+
+ // Notify notifier task.
+ self.tasks
+ .notifier
+ .notify(notifier::Notify::InitialRegistrationCompleted)
+ .await?;
+
+ Ok(())
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +
use std::sync::Arc;
+
+use anyhow::{anyhow, Result};
+use tokio::sync::mpsc;
+
+use crate::{
+ core::{
+ common::logger::get_logger,
+ consensus::{
+ beacon::EpochTime, state::beacon::ImmutableState as BeaconState, verifier::Verifier,
+ },
+ },
+ modules::rofl::types::Register,
+};
+
+use super::{processor, App, Environment};
+
+/// Registration task.
+pub(super) struct Task<A: App> {
+ imp: Option<Impl<A>>,
+ tx: mpsc::Sender<()>,
+}
+
+impl<A> Task<A>
+where
+ A: App,
+{
+ /// Create a registration task.
+ pub(super) fn new(state: Arc<processor::State<A>>, env: Environment<A>) -> Self {
+ let (tx, rx) = mpsc::channel(1);
+
+ let imp = Impl {
+ state,
+ env,
+ logger: get_logger("modules/rofl/app/registration"),
+ notify: rx,
+ last_registration_epoch: None,
+ };
+
+ Self { imp: Some(imp), tx }
+ }
+
+ /// Start the registration task.
+ pub(super) fn start(&mut self) {
+ if let Some(imp) = self.imp.take() {
+ imp.start();
+ }
+ }
+
+ /// Ask the registration task to refresh the registration.
+ pub(super) fn refresh(&self) {
+ let _ = self.tx.try_send(());
+ }
+}
+
+struct Impl<A: App> {
+ state: Arc<processor::State<A>>,
+ env: Environment<A>,
+ logger: slog::Logger,
+
+ notify: mpsc::Receiver<()>,
+ last_registration_epoch: Option<EpochTime>,
+}
+
+impl<A> Impl<A>
+where
+ A: App,
+{
+ /// Start the registration task.
+ pub(super) fn start(self) {
+ tokio::task::spawn(self.run());
+ }
+
+ /// Run the registration task.
+ async fn run(mut self) {
+ slog::info!(self.logger, "starting registration task");
+
+ // TODO: Handle retries etc.
+ while self.notify.recv().await.is_some() {
+ if let Err(err) = self.refresh_registration().await {
+ slog::error!(self.logger, "failed to refresh registration";
+ "err" => ?err,
+ );
+ }
+ }
+
+ slog::info!(self.logger, "registration task stopped");
+ }
+
+ /// Perform application registration refresh.
+ async fn refresh_registration(&mut self) -> Result<()> {
+ // Determine current epoch.
+ let state = self.state.consensus_verifier.latest_state().await?;
+ let epoch = tokio::task::spawn_blocking(move || {
+ let beacon = BeaconState::new(&state);
+ beacon.epoch()
+ })
+ .await??;
+
+ // Skip refresh in case epoch has not changed.
+ if self.last_registration_epoch == Some(epoch) {
+ return Ok(());
+ }
+
+ slog::info!(self.logger, "refreshing registration";
+ "last_registration_epoch" => self.last_registration_epoch,
+ "epoch" => epoch,
+ );
+
+ // Refresh registration.
+ let ect = self
+ .state
+ .identity
+ .endorsed_capability_tee()
+ .ok_or(anyhow!("endorsed TEE capability not available"))?;
+ let register = Register {
+ app: A::id(),
+ ect,
+ expiration: epoch + 2,
+ extra_keys: vec![self.env.signer().public_key()],
+ };
+
+ let tx = self.state.app.new_transaction("rofl.Register", register);
+ let result = self
+ .env
+ .client()
+ .multi_sign_and_submit_tx(&[self.state.identity.clone(), self.env.signer()], tx)
+ .await?
+ .ok()?;
+
+ slog::info!(self.logger, "refreshed registration"; "result" => ?result);
+
+ if self.last_registration_epoch.is_none() {
+ // If this is the first registration, notify processor that initial registration has
+ // been completed so it can do other stuff.
+ self.env
+ .send_command(processor::Command::InitialRegistrationCompleted)
+ .await?;
+ }
+ self.last_registration_epoch = Some(epoch);
+
+ Ok(())
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +
//! ROFL application identifier.
+use std::fmt;
+
+use bech32::{Bech32, Hrp};
+
+use crate::{core::common::crypto::hash::Hash, types::address::Address};
+
+const APP_ID_VERSION_SIZE: usize = 1;
+const APP_ID_DATA_SIZE: usize = 20;
+const APP_ID_SIZE: usize = APP_ID_VERSION_SIZE + APP_ID_DATA_SIZE;
+
+/// V0 identifier version.
+const APP_ID_V0_VERSION: u8 = 0;
+/// Creator/round/index identifier context.
+const APP_ID_CRI_CONTEXT: &[u8] = b"oasis-sdk/rofl: cri app id";
+/// Creator/nonce identifier context.
+const APP_ID_CN_CONTEXT: &[u8] = b"oasis-sdk/rofl: cn app id";
+/// Global name identifier context.
+const APP_ID_GLOBAL_NAME_CONTEXT: &[u8] = b"oasis-sdk/rofl: global name app id";
+
+/// Human readable part for Bech32-encoded application identifier.
+pub const APP_ID_BECH32_HRP: Hrp = Hrp::parse_unchecked("rofl");
+
+/// Error.
+#[derive(thiserror::Error, Debug)]
+pub enum Error {
+ #[error("malformed identifier")]
+ MalformedIdentifier,
+}
+
+/// ROFL application identifier.
+///
+/// The application identifier is similar to an address, but using its own separate namespace and
+/// derivation scheme as it is not meant to be used as an address.
+#[derive(Copy, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct AppId([u8; APP_ID_SIZE]);
+
+impl AppId {
+ /// Size of an application identifier in bytes.
+ pub const SIZE: usize = APP_ID_SIZE;
+
+ /// Creates a new application identifier from a context, version and data.
+ fn new(ctx: &'static [u8], version: u8, data: &[u8]) -> Self {
+ let h = Hash::digest_bytes_list(&[ctx, &[version], data]);
+
+ let mut a = [0; APP_ID_SIZE];
+ a[..APP_ID_VERSION_SIZE].copy_from_slice(&[version]);
+ a[APP_ID_VERSION_SIZE..].copy_from_slice(h.truncated(APP_ID_DATA_SIZE));
+
+ AppId(a)
+ }
+
+ /// Creates a new v0 application identifier from a global name.
+ pub fn from_global_name(name: &str) -> Self {
+ Self::new(
+ APP_ID_GLOBAL_NAME_CONTEXT,
+ APP_ID_V0_VERSION,
+ name.as_bytes(),
+ )
+ }
+
+ /// Creates a new v0 application identifier from creator/round/index tuple.
+ pub fn from_creator_round_index(creator: Address, round: u64, index: u32) -> Self {
+ Self::new(
+ APP_ID_CRI_CONTEXT,
+ APP_ID_V0_VERSION,
+ &[creator.as_ref(), &round.to_be_bytes(), &index.to_be_bytes()].concat(),
+ )
+ }
+
+ /// Creates a new v0 application identifier from creator/nonce tuple.
+ pub fn from_creator_nonce(creator: Address, nonce: u64) -> Self {
+ Self::new(
+ APP_ID_CN_CONTEXT,
+ APP_ID_V0_VERSION,
+ &[creator.as_ref(), &nonce.to_be_bytes()].concat(),
+ )
+ }
+
+ /// Tries to create a new identifier from raw bytes.
+ pub fn from_bytes(data: &[u8]) -> Result<Self, Error> {
+ if data.len() != APP_ID_SIZE {
+ return Err(Error::MalformedIdentifier);
+ }
+
+ let mut a = [0; APP_ID_SIZE];
+ a.copy_from_slice(data);
+
+ Ok(AppId(a))
+ }
+
+ /// Convert the identifier into raw bytes.
+ pub fn into_bytes(self) -> [u8; APP_ID_SIZE] {
+ self.0
+ }
+
+ /// Tries to create a new identifier from Bech32-encoded string.
+ pub fn from_bech32(data: &str) -> Result<Self, Error> {
+ let (hrp, data) = bech32::decode(data).map_err(|_| Error::MalformedIdentifier)?;
+ if hrp != APP_ID_BECH32_HRP {
+ return Err(Error::MalformedIdentifier);
+ }
+
+ Self::from_bytes(&data)
+ }
+
+ /// Converts an identifier to Bech32 representation.
+ pub fn to_bech32(self) -> String {
+ bech32::encode::<Bech32>(APP_ID_BECH32_HRP, &self.0).unwrap()
+ }
+}
+
+impl AsRef<[u8]> for AppId {
+ fn as_ref(&self) -> &[u8] {
+ &self.0
+ }
+}
+
+impl TryFrom<&[u8]> for AppId {
+ type Error = Error;
+
+ fn try_from(bytes: &[u8]) -> Result<Self, Self::Error> {
+ Self::from_bytes(bytes)
+ }
+}
+
+impl From<&'static str> for AppId {
+ fn from(s: &'static str) -> AppId {
+ AppId::from_bech32(s).unwrap()
+ }
+}
+
+impl fmt::LowerHex for AppId {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ for i in &self.0[..] {
+ write!(f, "{i:02x}")?;
+ }
+ Ok(())
+ }
+}
+
+impl fmt::Debug for AppId {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ write!(f, "{}", self.to_bech32())?;
+ Ok(())
+ }
+}
+
+impl fmt::Display for AppId {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ write!(f, "{}", self.to_bech32())?;
+ Ok(())
+ }
+}
+
+impl cbor::Encode for AppId {
+ fn into_cbor_value(self) -> cbor::Value {
+ cbor::Value::ByteString(self.as_ref().to_vec())
+ }
+}
+
+impl cbor::Decode for AppId {
+ fn try_default() -> Result<Self, cbor::DecodeError> {
+ Ok(Default::default())
+ }
+
+ fn try_from_cbor_value(value: cbor::Value) -> Result<Self, cbor::DecodeError> {
+ match value {
+ cbor::Value::ByteString(data) => {
+ Self::from_bytes(&data).map_err(|_| cbor::DecodeError::UnexpectedType)
+ }
+ _ => Err(cbor::DecodeError::UnexpectedType),
+ }
+ }
+}
+
+impl slog::Value for AppId {
+ fn serialize(
+ &self,
+ _record: &slog::Record<'_>,
+ key: slog::Key,
+ serializer: &mut dyn slog::Serializer,
+ ) -> slog::Result {
+ serializer.emit_str(key, &self.to_bech32())
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+ use crate::testing::keys;
+
+ #[test]
+ fn test_identifier_v0() {
+ let creator = keys::alice::address();
+ let app_id = AppId::from_creator_round_index(creator, 42, 0);
+
+ assert_eq!(
+ app_id.to_bech32(),
+ "rofl1qr98wz5t6q4x8ng6a5l5v7rqlx90j3kcnun5dwht"
+ );
+
+ let creator = keys::bob::address();
+ let app_id = AppId::from_creator_round_index(creator, 42, 0);
+
+ assert_eq!(
+ app_id.to_bech32(),
+ "rofl1qrd45eaj4tf6l7mjw5prcukz75wdmwg6kggt6pnp"
+ );
+
+ let creator = keys::bob::address();
+ let app_id = AppId::from_creator_round_index(creator, 1, 0);
+
+ assert_eq!(
+ app_id.to_bech32(),
+ "rofl1qzmuyfwygnmfralgtwrqx8kcm587kwex9y8hf9hf"
+ );
+
+ let creator = keys::bob::address();
+ let app_id = AppId::from_creator_round_index(creator, 42, 1);
+
+ assert_eq!(
+ app_id.to_bech32(),
+ "rofl1qzmh56f52yd0tcqh757fahzc7ec49s8kaguyylvu"
+ );
+
+ let creator = keys::alice::address();
+ let app_id = AppId::from_creator_nonce(creator, 0);
+
+ assert_eq!(
+ app_id.to_bech32(),
+ "rofl1qqxxv77j6qy3rh50ah9kxehsh26e2hf7p5r6kwsq"
+ );
+
+ let creator = keys::alice::address();
+ let app_id = AppId::from_creator_nonce(creator, 1);
+
+ assert_eq!(
+ app_id.to_bech32(),
+ "rofl1qqfuf7u556prwv0wkdt398prhrpat7r3rvr97khf"
+ );
+
+ let creator = keys::alice::address();
+ let app_id = AppId::from_creator_nonce(creator, 42);
+
+ assert_eq!(
+ app_id.to_bech32(),
+ "rofl1qr90w0m8j7h34c2hhpfmg2wgqmtu0q82vyaxv6e0"
+ );
+
+ let creator = keys::bob::address();
+ let app_id = AppId::from_creator_nonce(creator, 0);
+
+ assert_eq!(
+ app_id.to_bech32(),
+ "rofl1qqzuxsh8fkga366kxrze8vpltdjge3rc7qg6tlrg"
+ );
+
+ let app_id = AppId::from_global_name("test global app");
+
+ assert_eq!(
+ app_id.to_bech32(),
+ "rofl1qrev5wq76npkmcv5wxkdxxcu4dhmu704yyl30h43"
+ );
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +
use crate::types::token;
+
+/// Module configuration.
+pub trait Config: 'static {
+ /// Gas cost of rofl.Create call.
+ const GAS_COST_CALL_CREATE: u64 = 100_000;
+ /// Gas cost of rofl.Update call.
+ const GAS_COST_CALL_UPDATE: u64 = 100_000;
+ /// Gas cost of rofl.Remove call.
+ const GAS_COST_CALL_REMOVE: u64 = 10_000;
+ /// Gas cost of rofl.Register call.
+ const GAS_COST_CALL_REGISTER: u64 = 100_000;
+ /// Gas cost of rofl.IsAuthorizedOrigin call.
+ const GAS_COST_CALL_IS_AUTHORIZED_ORIGIN: u64 = 1000;
+ /// Gas cost of rofl.AuthorizedOriginNode call.
+ const GAS_COST_CALL_AUTHORIZED_ORIGIN_NODE: u64 = 2000;
+ /// Gas cost of rofl.AuthorizedOriginEntity call.
+ const GAS_COST_CALL_AUTHORIZED_ORIGIN_ENTITY: u64 = 2000;
+ /// Gas cost of rofl.StakeThresholds call.
+ const GAS_COST_CALL_STAKE_THRESHOLDS: u64 = 10;
+
+ /// Amount of stake required for maintaining an application.
+ ///
+ /// The stake is held in escrow and is returned to the administrator when the application is
+ /// removed.
+ const STAKE_APP_CREATE: token::BaseUnits =
+ token::BaseUnits::new(0, token::Denomination::NATIVE);
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +
use crate::modules;
+
+use super::MODULE_NAME;
+
+/// Errors emitted by the module.
+#[derive(thiserror::Error, Debug, oasis_runtime_sdk_macros::Error)]
+pub enum Error {
+ #[error("invalid argument")]
+ #[sdk_error(code = 1)]
+ InvalidArgument,
+
+ #[error("unknown application")]
+ #[sdk_error(code = 2)]
+ UnknownApp,
+
+ #[error("tx not signed by RAK")]
+ #[sdk_error(code = 3)]
+ NotSignedByRAK,
+
+ #[error("tx not signed by extra key")]
+ #[sdk_error(code = 4)]
+ NotSignedByExtraKey,
+
+ #[error("unknown enclave")]
+ #[sdk_error(code = 5)]
+ UnknownEnclave,
+
+ #[error("unknown node")]
+ #[sdk_error(code = 6)]
+ UnknownNode,
+
+ #[error("endorsement from given node not allowed")]
+ #[sdk_error(code = 7)]
+ NodeNotAllowed,
+
+ #[error("registration expired")]
+ #[sdk_error(code = 8)]
+ RegistrationExpired,
+
+ #[error("extra key update not allowed")]
+ #[sdk_error(code = 9)]
+ ExtraKeyUpdateNotAllowed,
+
+ #[error("application already exists")]
+ #[sdk_error(code = 10)]
+ AppAlreadyExists,
+
+ #[error("forbidden")]
+ #[sdk_error(code = 11)]
+ Forbidden,
+
+ #[error("unknown instance")]
+ #[sdk_error(code = 12)]
+ UnknownInstance,
+
+ #[error("core: {0}")]
+ #[sdk_error(transparent)]
+ Core(#[from] modules::core::Error),
+
+ #[error("accounts: {0}")]
+ #[sdk_error(transparent)]
+ Accounts(#[from] modules::accounts::Error),
+}
+use super::{app_id::AppId, MODULE_NAME};
+
+/// Events emitted by the ROFL module.
+#[derive(Debug, cbor::Encode, oasis_runtime_sdk_macros::Event)]
+#[cbor(untagged)]
+pub enum Event {
+ #[sdk_event(code = 1)]
+ AppCreated { id: AppId },
+
+ #[sdk_event(code = 2)]
+ AppUpdated { id: AppId },
+
+ #[sdk_event(code = 3)]
+ AppRemoved { id: AppId },
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +
//! On-chain coordination for ROFL components.
+use std::collections::BTreeSet;
+
+use once_cell::sync::Lazy;
+
+use crate::{
+ context::Context,
+ core::{
+ common::crypto::signature::PublicKey as CorePublicKey,
+ consensus::{
+ registry::{Node, RolesMask, VerifiedEndorsedCapabilityTEE},
+ state::registry::ImmutableState as RegistryImmutableState,
+ },
+ },
+ crypto::signature::PublicKey,
+ handler, migration,
+ module::{self, Module as _, Parameters as _},
+ modules::{self, accounts::API as _, core::API as _},
+ sdk_derive,
+ state::CurrentState,
+ types::{address::Address, transaction::Transaction},
+ Runtime,
+};
+
+pub mod app;
+pub mod app_id;
+mod config;
+mod error;
+mod event;
+pub mod policy;
+pub mod state;
+#[cfg(test)]
+mod test;
+pub mod types;
+
+/// Unique module name.
+const MODULE_NAME: &str = "rofl";
+
+pub use config::Config;
+pub use error::Error;
+pub use event::Event;
+
+/// Parameters for the module.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Parameters {}
+
+/// Errors emitted during parameter validation.
+#[derive(thiserror::Error, Debug)]
+pub enum ParameterValidationError {}
+
+impl module::Parameters for Parameters {
+ type Error = ParameterValidationError;
+
+ fn validate_basic(&self) -> Result<(), Self::Error> {
+ Ok(())
+ }
+}
+
+/// Genesis state for the module.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Genesis {
+ pub parameters: Parameters,
+
+ /// Application configurations.
+ pub apps: Vec<types::AppConfig>,
+}
+
+/// Interface that can be called from other modules.
+pub trait API {
+ /// Get the Runtime Attestation Key of the ROFL app instance in case the origin transaction is
+ /// signed by a ROFL instance. Otherwise `None` is returned.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called outside a transaction environment.
+ fn get_origin_rak() -> Option<PublicKey>;
+
+ /// Get the registration descriptor of the ROFL app instance in case the origin transaction is
+ /// signed by a ROFL instance of the specified app. Otherwise `None` is returned.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called outside a transaction environment.
+ fn get_origin_registration(app: app_id::AppId) -> Option<types::Registration>;
+
+ /// Verify whether the origin transaction is signed by an authorized ROFL instance for the given
+ /// application.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called outside a transaction environment.
+ fn is_authorized_origin(app: app_id::AppId) -> bool;
+
+ /// Get a specific registered instance for an application.
+ fn get_registration(app: app_id::AppId, rak: PublicKey) -> Result<types::Registration, Error>;
+
+ /// Get an application's configuration.
+ fn get_app(id: app_id::AppId) -> Result<types::AppConfig, Error>;
+
+ /// Get all registered instances for an application.
+ fn get_instances(id: app_id::AppId) -> Result<Vec<types::Registration>, Error>;
+}
+
+/// Module's address that has the application stake pool.
+///
+/// oasis1qza6sddnalgzexk3ct30gqfvntgth5m4hsyywmff
+pub static ADDRESS_APP_STAKE_POOL: Lazy<Address> =
+ Lazy::new(|| Address::from_module(MODULE_NAME, "app-stake-pool"));
+
+pub struct Module<Cfg: Config> {
+ _cfg: std::marker::PhantomData<Cfg>,
+}
+
+impl<Cfg: Config> API for Module<Cfg> {
+ fn get_origin_rak() -> Option<PublicKey> {
+ let caller_pk = CurrentState::with_env_origin(|env| env.tx_caller_public_key())?;
+
+ // Resolve RAK as the call may be made by an extra key.
+ state::get_endorser(&caller_pk).map(|kei| match kei {
+ // It may point to a RAK.
+ state::KeyEndorsementInfo { rak: Some(rak), .. } => rak.into(),
+ // Or it points to itself.
+ _ => caller_pk,
+ })
+ }
+
+ fn get_origin_registration(app: app_id::AppId) -> Option<types::Registration> {
+ Self::get_origin_rak()
+ .and_then(|rak| state::get_registration(app, &rak.try_into().unwrap()))
+ }
+
+ fn is_authorized_origin(app: app_id::AppId) -> bool {
+ Self::get_origin_registration(app).is_some()
+ }
+
+ fn get_registration(app: app_id::AppId, rak: PublicKey) -> Result<types::Registration, Error> {
+ state::get_registration(app, &rak.try_into().map_err(|_| Error::InvalidArgument)?)
+ .ok_or(Error::UnknownInstance)
+ }
+
+ fn get_app(id: app_id::AppId) -> Result<types::AppConfig, Error> {
+ state::get_app(id).ok_or(Error::UnknownApp)
+ }
+
+ fn get_instances(id: app_id::AppId) -> Result<Vec<types::Registration>, Error> {
+ Ok(state::get_registrations_for_app(id))
+ }
+}
+
+#[sdk_derive(Module)]
+impl<Cfg: Config> Module<Cfg> {
+ const NAME: &'static str = MODULE_NAME;
+ type Error = Error;
+ type Event = Event;
+ type Parameters = Parameters;
+ type Genesis = Genesis;
+
+ #[migration(init)]
+ fn init(genesis: Genesis) {
+ genesis
+ .parameters
+ .validate_basic()
+ .expect("invalid genesis parameters");
+
+ // Set genesis parameters.
+ Self::set_params(genesis.parameters);
+
+ // Insert all applications.
+ for cfg in genesis.apps {
+ if state::get_app(cfg.id).is_some() {
+ panic!("duplicate application in genesis: {:?}", cfg.id);
+ }
+
+ state::set_app(cfg);
+ }
+ }
+
+ /// Create a new ROFL application.
+ #[handler(call = "rofl.Create")]
+ fn tx_create<C: Context>(ctx: &C, body: types::Create) -> Result<app_id::AppId, Error> {
+ <C::Runtime as Runtime>::Core::use_tx_gas(Cfg::GAS_COST_CALL_CREATE)?;
+
+ if CurrentState::with_env(|env| env.is_check_only()) {
+ return Ok(Default::default());
+ }
+
+ let (creator, tx_index) =
+ CurrentState::with_env(|env| (env.tx_caller_address(), env.tx_index()));
+ let app_id = match body.scheme {
+ types::IdentifierScheme::CreatorRoundIndex => app_id::AppId::from_creator_round_index(
+ creator,
+ ctx.runtime_header().round,
+ tx_index.try_into().map_err(|_| Error::InvalidArgument)?,
+ ),
+ types::IdentifierScheme::CreatorNonce => {
+ let nonce = <C::Runtime as Runtime>::Accounts::get_nonce(creator)?;
+
+ app_id::AppId::from_creator_nonce(creator, nonce)
+ }
+ };
+
+ // Sanity check that the application doesn't already exist.
+ if state::get_app(app_id).is_some() {
+ return Err(Error::AppAlreadyExists);
+ }
+
+ // Transfer stake.
+ <C::Runtime as Runtime>::Accounts::transfer(
+ creator,
+ *ADDRESS_APP_STAKE_POOL,
+ &Cfg::STAKE_APP_CREATE,
+ )?;
+
+ // Register the application.
+ let cfg = types::AppConfig {
+ id: app_id,
+ policy: body.policy,
+ admin: Some(creator),
+ stake: Cfg::STAKE_APP_CREATE,
+ };
+ state::set_app(cfg);
+
+ CurrentState::with(|state| state.emit_event(Event::AppCreated { id: app_id }));
+
+ Ok(app_id)
+ }
+
+ /// Ensure caller is the current administrator, return an error otherwise.
+ fn ensure_caller_is_admin(cfg: &types::AppConfig) -> Result<(), Error> {
+ let caller = CurrentState::with_env(|env| env.tx_caller_address());
+ if cfg.admin != Some(caller) {
+ return Err(Error::Forbidden);
+ }
+ Ok(())
+ }
+
+ /// Update a ROFL application.
+ #[handler(call = "rofl.Update")]
+ fn tx_update<C: Context>(ctx: &C, body: types::Update) -> Result<(), Error> {
+ <C::Runtime as Runtime>::Core::use_tx_gas(Cfg::GAS_COST_CALL_UPDATE)?;
+
+ let mut cfg = state::get_app(body.id).ok_or(Error::UnknownApp)?;
+
+ // Ensure caller is the admin and is allowed to update the configuration.
+ Self::ensure_caller_is_admin(&cfg)?;
+
+ if CurrentState::with_env(|env| env.is_check_only()) {
+ return Ok(());
+ }
+
+ // Return early if nothing has actually changed.
+ if cfg.policy == body.policy && cfg.admin == body.admin {
+ return Ok(());
+ }
+
+ cfg.policy = body.policy;
+ cfg.admin = body.admin;
+ state::set_app(cfg);
+
+ CurrentState::with(|state| state.emit_event(Event::AppUpdated { id: body.id }));
+
+ Ok(())
+ }
+
+ /// Remove a ROFL application.
+ #[handler(call = "rofl.Remove")]
+ fn tx_remove<C: Context>(ctx: &C, body: types::Remove) -> Result<(), Error> {
+ <C::Runtime as Runtime>::Core::use_tx_gas(Cfg::GAS_COST_CALL_REMOVE)?;
+
+ let cfg = state::get_app(body.id).ok_or(Error::UnknownApp)?;
+
+ // Ensure caller is the admin and is allowed to update the configuration.
+ Self::ensure_caller_is_admin(&cfg)?;
+
+ if CurrentState::with_env(|env| env.is_check_only()) {
+ return Ok(());
+ }
+
+ state::remove_app(body.id);
+
+ // Return stake to the administrator account.
+ if let Some(admin) = cfg.admin {
+ <C::Runtime as Runtime>::Accounts::transfer(
+ *ADDRESS_APP_STAKE_POOL,
+ admin,
+ &cfg.stake,
+ )?;
+ }
+
+ CurrentState::with(|state| state.emit_event(Event::AppRemoved { id: body.id }));
+
+ Ok(())
+ }
+
+ /// Register a new ROFL instance.
+ #[handler(call = "rofl.Register")]
+ fn tx_register<C: Context>(ctx: &C, body: types::Register) -> Result<(), Error> {
+ <C::Runtime as Runtime>::Core::use_tx_gas(Cfg::GAS_COST_CALL_REGISTER)?;
+
+ if body.expiration <= ctx.epoch() {
+ return Err(Error::RegistrationExpired);
+ }
+
+ let cfg = state::get_app(body.app).ok_or(Error::UnknownApp)?;
+
+ if body.expiration - ctx.epoch() > cfg.policy.max_expiration {
+ return Err(Error::InvalidArgument);
+ }
+
+ // Ensure that the transaction is signed by RAK (and co-signed by extra keys).
+ let signer_pks: BTreeSet<PublicKey> = CurrentState::with_env(|env| {
+ env.tx_auth_info()
+ .signer_info
+ .iter()
+ .filter_map(|si| si.address_spec.public_key())
+ .collect()
+ });
+ if !signer_pks.contains(&body.ect.capability_tee.rak.into()) {
+ return Err(Error::NotSignedByRAK);
+ }
+ for extra_pk in &body.extra_keys {
+ if !signer_pks.contains(extra_pk) {
+ return Err(Error::NotSignedByExtraKey);
+ }
+ }
+
+ if CurrentState::with_env(|env| env.is_check_only()) {
+ return Ok(());
+ }
+
+ // Verify policy.
+ let verified_ect = body
+ .ect
+ .verify(&cfg.policy.quotes)
+ .map_err(|_| Error::InvalidArgument)?;
+
+ // Verify enclave identity.
+ if !cfg
+ .policy
+ .enclaves
+ .contains(&verified_ect.verified_attestation.quote.identity)
+ {
+ return Err(Error::UnknownEnclave);
+ }
+
+ // Verify allowed endorsement.
+ let node = Self::verify_endorsement(ctx, &cfg.policy, &verified_ect)?;
+
+ // Update registration.
+ let registration = types::Registration {
+ app: body.app,
+ node_id: verified_ect.node_id.unwrap(), // Verified above.
+ entity_id: node.map(|n| n.entity_id),
+ rak: body.ect.capability_tee.rak,
+ rek: body.ect.capability_tee.rek.ok_or(Error::InvalidArgument)?, // REK required.
+ expiration: body.expiration,
+ extra_keys: body.extra_keys,
+ };
+ state::update_registration(registration)?;
+
+ Ok(())
+ }
+
+ /// Verify whether the given endorsement is allowed by the application policy.
+ ///
+ /// Returns an optional endorsing node descriptor when available.
+ fn verify_endorsement<C: Context>(
+ ctx: &C,
+ app_policy: &policy::AppAuthPolicy,
+ ect: &VerifiedEndorsedCapabilityTEE,
+ ) -> Result<Option<Node>, Error> {
+ use policy::AllowedEndorsement;
+
+ let endorsing_node_id = ect.node_id.ok_or(Error::UnknownNode)?;
+
+ // Attempt to resolve the node that endorsed the enclave. It may be that the node is not
+ // even registered in the consensus layer which may be acceptable for some policies.
+ let maybe_node = || -> Result<Option<Node>, Error> {
+ let registry = RegistryImmutableState::new(ctx.consensus_state());
+ let node = registry
+ .node(&endorsing_node_id)
+ .map_err(|_| Error::UnknownNode)?;
+ let node = if let Some(node) = node {
+ node
+ } else {
+ return Ok(None);
+ };
+ // Ensure node is not expired.
+ if node.expiration < ctx.epoch() {
+ return Ok(None);
+ }
+
+ Ok(Some(node))
+ }()?;
+
+ // Ensure node is registered for this runtime.
+ let has_runtime = |node: &Node| -> bool {
+ let version = &<C::Runtime as Runtime>::VERSION;
+ node.get_runtime(ctx.runtime_id(), version).is_some()
+ };
+
+ for allowed in &app_policy.endorsements {
+ match (allowed, &maybe_node) {
+ (AllowedEndorsement::Any, _) => {
+ // Any node is allowed.
+ return Ok(maybe_node);
+ }
+ (AllowedEndorsement::ComputeRole, Some(node)) => {
+ if node.has_roles(RolesMask::ROLE_COMPUTE_WORKER) && has_runtime(node) {
+ return Ok(maybe_node);
+ }
+ }
+ (AllowedEndorsement::ObserverRole, Some(node)) => {
+ if node.has_roles(RolesMask::ROLE_OBSERVER) && has_runtime(node) {
+ return Ok(maybe_node);
+ }
+ }
+ (AllowedEndorsement::Entity(entity_id), Some(node)) => {
+ // If a specific entity is required, it may be registered for any runtime.
+ if &node.entity_id == entity_id {
+ return Ok(maybe_node);
+ }
+ }
+ (AllowedEndorsement::Node(node_id), _) => {
+ if endorsing_node_id == *node_id {
+ return Ok(maybe_node);
+ }
+ }
+ _ => continue,
+ }
+ }
+
+ // If nothing matched, this node is not allowed to register.
+ Err(Error::NodeNotAllowed)
+ }
+
+ /// Verify whether the origin transaction is signed by an authorized ROFL instance for the given
+ /// application.
+ #[handler(call = "rofl.IsAuthorizedOrigin", internal)]
+ fn internal_is_authorized_origin<C: Context>(
+ _ctx: &C,
+ app: app_id::AppId,
+ ) -> Result<bool, Error> {
+ <C::Runtime as Runtime>::Core::use_tx_gas(Cfg::GAS_COST_CALL_IS_AUTHORIZED_ORIGIN)?;
+
+ Ok(Self::is_authorized_origin(app))
+ }
+
+ #[handler(call = "rofl.AuthorizedOriginNode", internal)]
+ fn internal_authorized_origin_node<C: Context>(
+ _ctx: &C,
+ app: app_id::AppId,
+ ) -> Result<CorePublicKey, Error> {
+ <C::Runtime as Runtime>::Core::use_tx_gas(Cfg::GAS_COST_CALL_AUTHORIZED_ORIGIN_NODE)?;
+
+ let registration = Self::get_origin_registration(app).ok_or(Error::UnknownInstance)?;
+ Ok(registration.node_id)
+ }
+
+ #[handler(call = "rofl.AuthorizedOriginEntity", internal)]
+ fn internal_authorized_origin_entity<C: Context>(
+ _ctx: &C,
+ app: app_id::AppId,
+ ) -> Result<Option<CorePublicKey>, Error> {
+ <C::Runtime as Runtime>::Core::use_tx_gas(Cfg::GAS_COST_CALL_AUTHORIZED_ORIGIN_ENTITY)?;
+
+ let registration = Self::get_origin_registration(app).ok_or(Error::UnknownInstance)?;
+ Ok(registration.entity_id)
+ }
+
+ /// Returns the configuration for the given ROFL application.
+ #[handler(query = "rofl.App")]
+ fn query_app<C: Context>(_ctx: &C, args: types::AppQuery) -> Result<types::AppConfig, Error> {
+ Self::get_app(args.id)
+ }
+
+ /// Returns a specific registered instance for the given ROFL application.
+ #[handler(query = "rofl.AppInstance")]
+ fn query_app_instance<C: Context>(
+ _ctx: &C,
+ args: types::AppInstanceQuery,
+ ) -> Result<types::Registration, Error> {
+ Self::get_registration(args.app, args.rak)
+ }
+
+ /// Returns a list of all registered instances for the given ROFL application.
+ #[handler(query = "rofl.AppInstances", expensive)]
+ fn query_app_instances<C: Context>(
+ _ctx: &C,
+ args: types::AppQuery,
+ ) -> Result<Vec<types::Registration>, Error> {
+ Self::get_instances(args.id)
+ }
+
+ /// Returns the minimum stake thresholds for managing ROFL.
+ #[handler(query = "rofl.StakeThresholds")]
+ fn query_stake_thresholds<C: Context>(
+ _ctx: &C,
+ _args: (),
+ ) -> Result<types::StakeThresholds, Error> {
+ Ok(types::StakeThresholds {
+ app_create: Cfg::STAKE_APP_CREATE,
+ })
+ }
+
+ /// Returns the minimum stake thresholds for managing ROFL.
+ #[handler(call = "rofl.StakeThresholds", internal)]
+ fn internal_query_stake_thresholds<C: Context>(
+ ctx: &C,
+ _args: (),
+ ) -> Result<types::StakeThresholds, Error> {
+ <C::Runtime as Runtime>::Core::use_tx_gas(Cfg::GAS_COST_CALL_STAKE_THRESHOLDS)?;
+ Ok(types::StakeThresholds {
+ app_create: Cfg::STAKE_APP_CREATE,
+ })
+ }
+
+ fn resolve_payer_from_tx<C: Context>(
+ ctx: &C,
+ tx: &Transaction,
+ app_policy: &policy::AppAuthPolicy,
+ ) -> Result<Option<Address>, anyhow::Error> {
+ let caller_pk = tx
+ .auth_info
+ .signer_info
+ .first()
+ .and_then(|si| si.address_spec.public_key());
+
+ match tx.call.method.as_str() {
+ "rofl.Register" => {
+ // For registration transactions, extract endorsing node.
+ let body: types::Register = cbor::from_value(tx.call.body.clone())?;
+ if body.expiration <= ctx.epoch() {
+ return Err(Error::RegistrationExpired.into());
+ }
+
+ // Ensure that the transaction is signed by RAK.
+ let caller_pk = caller_pk.ok_or(Error::NotSignedByRAK)?;
+ if caller_pk != body.ect.capability_tee.rak {
+ return Err(Error::NotSignedByRAK.into());
+ }
+
+ body.ect.verify_endorsement()?;
+
+ // Checking other details is not relevant for authorizing fee payments as if the
+ // node signed a TEE capability then it is authorizing fees to be spent on its
+ // behalf.
+
+ let node_id = body.ect.node_endorsement.public_key;
+ let payer = Address::from_consensus_pk(&node_id);
+
+ Ok(Some(payer))
+ }
+ _ => {
+ // For others, check if caller is one of the endorsed keys.
+ let caller_pk = match caller_pk {
+ Some(pk) => pk,
+ None => return Ok(None),
+ };
+
+ Ok(state::get_endorser(&caller_pk)
+ .map(|ei| Address::from_consensus_pk(&ei.node_id)))
+ }
+ }
+ }
+}
+
+impl<Cfg: Config> module::FeeProxyHandler for Module<Cfg> {
+ fn resolve_payer<C: Context>(
+ ctx: &C,
+ tx: &Transaction,
+ ) -> Result<Option<Address>, modules::core::Error> {
+ use policy::FeePolicy;
+
+ let proxy = if let Some(ref proxy) = tx.auth_info.fee.proxy {
+ proxy
+ } else {
+ return Ok(None);
+ };
+
+ if proxy.module != MODULE_NAME {
+ return Ok(None);
+ }
+
+ // Look up the per-ROFL app policy.
+ let app_id = app_id::AppId::try_from(proxy.id.as_slice())
+ .map_err(|err| modules::core::Error::InvalidArgument(err.into()))?;
+ let app_policy = state::get_app(app_id).map(|cfg| cfg.policy).ok_or(
+ modules::core::Error::InvalidArgument(Error::UnknownApp.into()),
+ )?;
+
+ match app_policy.fees {
+ FeePolicy::InstancePays => {
+ // Application needs to figure out a way to pay, defer to regular handler.
+ Ok(None)
+ }
+ FeePolicy::EndorsingNodePays => Self::resolve_payer_from_tx(ctx, tx, &app_policy)
+ .map_err(modules::core::Error::InvalidArgument),
+ }
+ }
+}
+
+impl<Cfg: Config> module::TransactionHandler for Module<Cfg> {}
+
+impl<Cfg: Config> module::BlockHandler for Module<Cfg> {
+ fn end_block<C: Context>(ctx: &C) {
+ // Only do work in case the epoch has changed since the last processed block.
+ if !<C::Runtime as Runtime>::Core::has_epoch_changed() {
+ return;
+ }
+
+ // Process enclave expirations.
+ // TODO: Consider processing unprocessed in the next block(s) if there are too many.
+ state::expire_registrations(ctx.epoch(), 128);
+ }
+}
+
+impl<Cfg: Config> module::InvariantHandler for Module<Cfg> {}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +
use crate::core::{
+ common::{
+ crypto::signature::PublicKey,
+ sgx::{EnclaveIdentity, QuotePolicy},
+ },
+ consensus::beacon::EpochTime,
+};
+
+/// Per-application ROFL policy.
+#[derive(Clone, Debug, PartialEq, Eq, Default, cbor::Encode, cbor::Decode)]
+pub struct AppAuthPolicy {
+ /// Quote policy.
+ pub quotes: QuotePolicy,
+ /// The set of allowed enclave identities.
+ pub enclaves: Vec<EnclaveIdentity>,
+ /// The set of allowed endorsements.
+ pub endorsements: Vec<AllowedEndorsement>,
+ /// Gas fee payment policy.
+ pub fees: FeePolicy,
+ /// Maximum number of future epochs for which one can register.
+ pub max_expiration: EpochTime,
+}
+
+/// An allowed endorsement policy.
+#[derive(Clone, Debug, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub enum AllowedEndorsement {
+ /// Any node can endorse the enclave.
+ #[cbor(rename = "any", as_struct)]
+ Any,
+ /// Compute node for the current runtime can endorse the enclave.
+ #[cbor(rename = "role_compute", as_struct)]
+ ComputeRole,
+ /// Observer node for the current runtime can endorse the enclave.
+ #[cbor(rename = "role_observer", as_struct)]
+ ObserverRole,
+ /// Registered node from a specific entity can endorse the enclave.
+ #[cbor(rename = "entity")]
+ Entity(PublicKey),
+ /// Specific node can endorse the enclave.
+ #[cbor(rename = "node")]
+ Node(PublicKey),
+}
+
+/// Gas fee payment policy.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+#[repr(u8)]
+pub enum FeePolicy {
+ /// Application enclave pays the gas fees.
+ InstancePays = 1,
+ /// Endorsing node pays the gas fees.
+ #[default]
+ EndorsingNodePays = 2,
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +
use crate::{
+ core::{
+ common::crypto::{hash::Hash, signature::PublicKey as CorePublicKey},
+ consensus::beacon::EpochTime,
+ },
+ crypto::signature::PublicKey,
+ state::CurrentState,
+ storage::{self, Store},
+};
+
+use super::{app_id::AppId, types, Error, MODULE_NAME};
+
+/// Map of application identifiers to their configs.
+const APPS: &[u8] = &[0x01];
+/// Map of (application identifier, H(RAK)) tuples to their registrations.
+const REGISTRATIONS: &[u8] = &[0x02];
+/// Map of H(pk)s to KeyEndorsementInfos. This is used when just the public key is needed to avoid
+/// fetching entire registrations from storage.
+const ENDORSERS: &[u8] = &[0x03];
+/// A queue of registration expirations.
+const EXPIRATION_QUEUE: &[u8] = &[0x04];
+
+/// Information about an endorsed key.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+#[cbor(as_array)]
+pub struct KeyEndorsementInfo {
+ /// Identifier of node that endorsed the enclave.
+ pub node_id: CorePublicKey,
+ /// RAK of the enclave that endorsed the key. This is only set for endorsements of extra keys.
+ pub rak: Option<CorePublicKey>,
+}
+
+impl KeyEndorsementInfo {
+ /// Create a new key endorsement information for RAK endorsed by given node directly.
+ pub fn for_rak(node_id: CorePublicKey) -> Self {
+ Self {
+ node_id,
+ ..Default::default()
+ }
+ }
+
+ /// Create a new key endorsement information for extra key endorsed by RAK.
+ pub fn for_extra_key(node_id: CorePublicKey, rak: CorePublicKey) -> Self {
+ Self {
+ node_id,
+ rak: Some(rak),
+ }
+ }
+}
+
+/// Retrieves an application configuration.
+pub fn get_app(app_id: AppId) -> Option<types::AppConfig> {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let apps = storage::TypedStore::new(storage::PrefixStore::new(store, &APPS));
+ apps.get(app_id)
+ })
+}
+
+/// Updates an application configuration.
+pub fn set_app(cfg: types::AppConfig) {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut apps = storage::TypedStore::new(storage::PrefixStore::new(store, &APPS));
+ apps.insert(cfg.id, cfg);
+ })
+}
+
+/// Removes an application configuration.
+pub fn remove_app(app_id: AppId) {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut apps = storage::TypedStore::new(storage::PrefixStore::new(store, &APPS));
+ apps.remove(app_id);
+ })
+}
+
+/// Updates registration of the given ROFL enclave.
+pub fn update_registration(registration: types::Registration) -> Result<(), Error> {
+ let hrak = hash_rak(®istration.rak);
+
+ // Update expiration queue.
+ if let Some(existing) = get_registration_hrak(registration.app, hrak) {
+ // Disallow modification of extra keys.
+ if existing.extra_keys != registration.extra_keys {
+ return Err(Error::ExtraKeyUpdateNotAllowed);
+ }
+
+ remove_expiration_queue(existing.expiration, registration.app, hrak);
+ }
+ insert_expiration_queue(registration.expiration, registration.app, hrak);
+
+ // Update registration.
+ CurrentState::with_store(|mut root_store| {
+ let store = storage::PrefixStore::new(&mut root_store, &MODULE_NAME);
+ let mut endorsers = storage::TypedStore::new(storage::PrefixStore::new(store, &ENDORSERS));
+ endorsers.insert(hrak, KeyEndorsementInfo::for_rak(registration.node_id));
+
+ for pk in ®istration.extra_keys {
+ endorsers.insert(
+ hash_pk(pk),
+ KeyEndorsementInfo::for_extra_key(registration.node_id, registration.rak),
+ );
+ }
+
+ let app_id = registration.app;
+ let store = storage::PrefixStore::new(&mut root_store, &MODULE_NAME);
+ let registrations = storage::PrefixStore::new(store, ®ISTRATIONS);
+ let mut app = storage::TypedStore::new(storage::PrefixStore::new(registrations, app_id));
+ app.insert(hrak, registration);
+ });
+
+ Ok(())
+}
+
+fn remove_registration_hrak(app_id: AppId, hrak: Hash) {
+ let registration = match get_registration_hrak(app_id, hrak) {
+ Some(registration) => registration,
+ None => return,
+ };
+
+ // Remove from expiration queue if present.
+ remove_expiration_queue(registration.expiration, registration.app, hrak);
+
+ // Remove registration.
+ CurrentState::with_store(|mut root_store| {
+ let store = storage::PrefixStore::new(&mut root_store, &MODULE_NAME);
+ let mut endorsers = storage::TypedStore::new(storage::PrefixStore::new(store, &ENDORSERS));
+ endorsers.remove(hrak);
+
+ for pk in ®istration.extra_keys {
+ endorsers.remove(hash_pk(pk));
+ }
+
+ let store = storage::PrefixStore::new(&mut root_store, &MODULE_NAME);
+ let registrations = storage::PrefixStore::new(store, ®ISTRATIONS);
+ let mut app = storage::TypedStore::new(storage::PrefixStore::new(registrations, app_id));
+ app.remove(hrak);
+ });
+}
+
+/// Removes an existing registration of the given ROFL enclave.
+pub fn remove_registration(app_id: AppId, rak: &CorePublicKey) {
+ remove_registration_hrak(app_id, hash_rak(rak))
+}
+
+fn get_registration_hrak(app_id: AppId, hrak: Hash) -> Option<types::Registration> {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let registrations = storage::PrefixStore::new(store, ®ISTRATIONS);
+ let app = storage::TypedStore::new(storage::PrefixStore::new(registrations, app_id));
+ app.get(hrak)
+ })
+}
+
+/// Retrieves registration of the given ROFL enclave. In case enclave is not registered, returns
+/// `None`.
+pub fn get_registration(app_id: AppId, rak: &CorePublicKey) -> Option<types::Registration> {
+ get_registration_hrak(app_id, hash_rak(rak))
+}
+
+/// Retrieves all registrations for the given ROFL application.
+pub fn get_registrations_for_app(app_id: AppId) -> Vec<types::Registration> {
+ CurrentState::with_store(|mut root_store| {
+ let store = storage::PrefixStore::new(&mut root_store, &MODULE_NAME);
+ let registrations = storage::PrefixStore::new(store, ®ISTRATIONS);
+ let app = storage::TypedStore::new(storage::PrefixStore::new(registrations, app_id));
+
+ app.iter()
+ .map(|(_, registration): (Hash, types::Registration)| registration)
+ .collect()
+ })
+}
+
+/// Retrieves endorser of the given ROFL enclave. In case enclave is not registered, returns `None`.
+pub fn get_endorser(pk: &PublicKey) -> Option<KeyEndorsementInfo> {
+ let hpk = hash_pk(pk);
+
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let endorsers = storage::TypedStore::new(storage::PrefixStore::new(store, &ENDORSERS));
+ endorsers.get(hpk)
+ })
+}
+
+fn hash_rak(rak: &CorePublicKey) -> Hash {
+ hash_pk(&PublicKey::Ed25519(rak.into()))
+}
+
+fn hash_pk(pk: &PublicKey) -> Hash {
+ Hash::digest_bytes_list(&[pk.key_type().as_bytes(), pk.as_ref()])
+}
+
+fn queue_entry_key(epoch: EpochTime, app_id: AppId, hrak: Hash) -> Vec<u8> {
+ [&epoch.to_be_bytes(), app_id.as_ref(), hrak.as_ref()].concat()
+}
+
+fn insert_expiration_queue(epoch: EpochTime, app_id: AppId, hrak: Hash) {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut queue = storage::PrefixStore::new(store, &EXPIRATION_QUEUE);
+ queue.insert(&queue_entry_key(epoch, app_id, hrak), &[]);
+ })
+}
+
+fn remove_expiration_queue(epoch: EpochTime, app_id: AppId, hrak: Hash) {
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut queue = storage::PrefixStore::new(store, &EXPIRATION_QUEUE);
+ queue.remove(&queue_entry_key(epoch, app_id, hrak));
+ })
+}
+
+struct ExpirationQueueEntry {
+ epoch: EpochTime,
+ app_id: AppId,
+ hrak: Hash,
+}
+
+impl<'a> TryFrom<&'a [u8]> for ExpirationQueueEntry {
+ type Error = anyhow::Error;
+
+ fn try_from(value: &'a [u8]) -> Result<Self, Self::Error> {
+ // Decode a storage key of the format (epoch, hrak).
+ if value.len() != 8 + AppId::SIZE + Hash::len() {
+ anyhow::bail!("incorrect expiration queue key size");
+ }
+
+ Ok(Self {
+ epoch: EpochTime::from_be_bytes(value[..8].try_into()?),
+ app_id: value[8..8 + AppId::SIZE].try_into()?,
+ hrak: value[8 + AppId::SIZE..].into(),
+ })
+ }
+}
+
+/// Removes all expired registrations, e.g. those that expire in epochs earlier than or equal to the
+/// passed epoch.
+pub fn expire_registrations(epoch: EpochTime, limit: usize) {
+ let expired: Vec<_> = CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let queue = storage::TypedStore::new(storage::PrefixStore::new(store, &EXPIRATION_QUEUE));
+
+ queue
+ .iter()
+ .take_while(|(e, _): &(ExpirationQueueEntry, CorePublicKey)| e.epoch <= epoch)
+ .map(|(e, _)| (e.app_id, e.hrak))
+ .take(limit)
+ .collect()
+ });
+
+ for (app_id, hrak) in expired {
+ remove_registration_hrak(app_id, hrak);
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+ use crate::testing::{keys, mock};
+
+ #[test]
+ fn test_app_cfg() {
+ let _mock = mock::Mock::default();
+
+ let app_id = AppId::from_creator_round_index(keys::alice::address(), 0, 0);
+ let app = get_app(app_id);
+ assert!(app.is_none());
+
+ let cfg = types::AppConfig {
+ id: app_id,
+ policy: Default::default(),
+ admin: Some(keys::alice::address()),
+ stake: Default::default(),
+ };
+ set_app(cfg.clone());
+ let app = get_app(app_id).expect("application config should be created");
+ assert_eq!(app, cfg);
+
+ let cfg = types::AppConfig { admin: None, ..cfg };
+ set_app(cfg.clone());
+ let app = get_app(app_id).expect("application config should be updated");
+ assert_eq!(app, cfg);
+
+ remove_app(app_id);
+ let app = get_app(app_id);
+ assert!(app.is_none(), "application should have been removed");
+ }
+
+ #[test]
+ fn test_registration() {
+ let _mock = mock::Mock::default();
+ let app_id = Default::default();
+ let rak = keys::alice::pk().try_into().unwrap(); // Fake RAK.
+ let rak_pk = keys::alice::pk();
+
+ let registration = get_registration(app_id, &rak);
+ assert!(registration.is_none());
+ let endorser = get_endorser(&rak_pk);
+ assert!(endorser.is_none());
+ let endorser = get_endorser(&keys::dave::pk());
+ assert!(endorser.is_none());
+
+ let new_registration = types::Registration {
+ app: app_id,
+ rak,
+ expiration: 42,
+ extra_keys: vec![
+ keys::dave::pk(), // Add dave as an extra endorsed key.
+ ],
+ ..Default::default()
+ };
+ update_registration(new_registration.clone()).expect("registration update should work");
+
+ // Ensure extra endorsed keys cannot be updated later.
+ let bad_registration = types::Registration {
+ app: app_id,
+ extra_keys: vec![],
+ ..new_registration.clone()
+ };
+ update_registration(bad_registration.clone())
+ .expect_err("extra endorsed key update should not be allowed");
+
+ let registration = get_registration(app_id, &rak).expect("registration should be present");
+ assert_eq!(registration, new_registration);
+ let endorser = get_endorser(&rak_pk).expect("endorser should be present");
+ assert_eq!(endorser.node_id, new_registration.node_id);
+ assert!(endorser.rak.is_none());
+ let endorser = get_endorser(&keys::dave::pk()).expect("extra keys should be endorsed");
+ assert_eq!(endorser.node_id, new_registration.node_id);
+ assert_eq!(endorser.rak, Some(rak));
+ let registrations = get_registrations_for_app(new_registration.app);
+ assert_eq!(registrations.len(), 1);
+
+ expire_registrations(42, 128);
+
+ let registration = get_registration(app_id, &rak);
+ assert!(registration.is_none());
+ let endorser = get_endorser(&rak_pk);
+ assert!(endorser.is_none());
+ let endorser = get_endorser(&keys::dave::pk());
+ assert!(endorser.is_none());
+ let registrations = get_registrations_for_app(new_registration.app);
+ assert_eq!(registrations.len(), 0);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +
use crate::{
+ core::{
+ common::crypto::{signature, x25519},
+ consensus::{beacon::EpochTime, registry},
+ },
+ crypto::signature::PublicKey,
+ types::{address::Address, token},
+};
+
+use super::{app_id::AppId, policy::AppAuthPolicy};
+
+/// Create new ROFL application call.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Create {
+ /// Application authentication policy.
+ pub policy: AppAuthPolicy,
+ /// Identifier generation scheme.
+ pub scheme: IdentifierScheme,
+}
+
+/// ROFL application identifier generation scheme.
+#[derive(Clone, Copy, Debug, Default, cbor::Encode, cbor::Decode)]
+#[repr(u8)]
+pub enum IdentifierScheme {
+ #[default]
+ CreatorRoundIndex = 0,
+ CreatorNonce = 1,
+}
+
+/// Update an existing ROFL application call.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Update {
+ /// ROFL application identifier.
+ pub id: AppId,
+ /// Authentication policy.
+ pub policy: AppAuthPolicy,
+ /// Application administrator address.
+ pub admin: Option<Address>,
+}
+
+/// Remove an existing ROFL application call.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Remove {
+ /// ROFL application identifier.
+ pub id: AppId,
+}
+
+/// ROFL application configuration.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+#[cfg_attr(test, derive(PartialEq, Eq))]
+pub struct AppConfig {
+ /// ROFL application identifier.
+ pub id: AppId,
+ /// Authentication policy.
+ pub policy: AppAuthPolicy,
+ /// Application administrator address.
+ pub admin: Option<Address>,
+ /// Staked amount.
+ pub stake: token::BaseUnits,
+}
+
+/// Register ROFL call.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Register {
+ /// ROFL application identifier.
+ pub app: AppId,
+ /// Endorsed TEE capability.
+ pub ect: registry::EndorsedCapabilityTEE,
+ /// Epoch when the ROFL registration expires if not renewed.
+ pub expiration: EpochTime,
+ /// Extra public keys to endorse (e.g. secp256k1 keys).
+ ///
+ /// All of these keys need to co-sign the registration transaction to prove ownership.
+ pub extra_keys: Vec<PublicKey>,
+}
+
+/// ROFL registration descriptor.
+#[derive(Clone, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub struct Registration {
+ /// Application this enclave is registered for.
+ pub app: AppId,
+ /// Identifier of the endorsing node.
+ pub node_id: signature::PublicKey,
+ /// Optional identifier of the endorsing entity.
+ pub entity_id: Option<signature::PublicKey>,
+ /// Runtime Attestation Key.
+ pub rak: signature::PublicKey,
+ /// Runtime Encryption Key.
+ pub rek: x25519::PublicKey,
+ /// Epoch when the ROFL registration expires if not renewed.
+ pub expiration: EpochTime,
+ /// Extra public keys to endorse (e.g. secp256k1 keys).
+ pub extra_keys: Vec<PublicKey>,
+}
+
+/// Application-related query.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct AppQuery {
+ /// ROFL application identifier.
+ pub id: AppId,
+}
+
+/// Application instance query.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct AppInstanceQuery {
+ /// ROFL application identifier.
+ pub app: AppId,
+ /// Runtime Attestation Key.
+ pub rak: PublicKey,
+}
+
+/// Stake thresholds for managing ROFL.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct StakeThresholds {
+ /// Required stake for creating new ROFL application.
+ pub app_create: token::BaseUnits,
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +
//! Runtime.
+use std::sync::Arc;
+
+use oasis_core_runtime::{
+ common::{sgx, version},
+ config::Config,
+ consensus::verifier::TrustRoot,
+ dispatcher::{PostInitState, PreInitState},
+ enclave_rpc::session,
+ start_runtime,
+ types::{FeatureScheduleControl, Features},
+};
+
+use crate::{
+ config,
+ context::Context,
+ crypto, dispatcher,
+ keymanager::{KeyManagerClient, TrustedSigners},
+ module::{
+ BlockHandler, FeeProxyHandler, InvariantHandler, MethodHandler, MigrationHandler,
+ ModuleInfoHandler, TransactionHandler,
+ },
+ modules,
+ state::CurrentState,
+ storage::{self},
+};
+
+/// A runtime.
+pub trait Runtime {
+ /// Runtime version.
+ const VERSION: version::Version;
+ /// State version.
+ const STATE_VERSION: u32 = 0;
+
+ /// Prefetch limit. To enable prefetch set it to a non-zero value.
+ const PREFETCH_LIMIT: u16 = 0;
+
+ /// Runtime schedule control configuration.
+ const SCHEDULE_CONTROL: config::ScheduleControl = config::ScheduleControl::default();
+
+ /// Module that provides the core API.
+ type Core: modules::core::API;
+ /// Module that provides the accounts API.
+ type Accounts: modules::accounts::API;
+ /// Handler for proxy fee payments.
+ type FeeProxy: FeeProxyHandler = ();
+
+ /// Supported modules.
+ type Modules: TransactionHandler
+ + MigrationHandler
+ + MethodHandler
+ + BlockHandler
+ + InvariantHandler
+ + ModuleInfoHandler;
+
+ /// Return the trusted signers for this runtime; if `None`, a key manager connection will not be
+ /// established on startup.
+ fn trusted_signers() -> Option<TrustedSigners> {
+ None
+ }
+
+ /// Return the consensus layer trust root for this runtime; if `None`, consensus layer integrity
+ /// verification will not be performed.
+ fn consensus_trust_root() -> Option<TrustRoot> {
+ None
+ }
+
+ /// Genesis state for the runtime.
+ fn genesis_state() -> <Self::Modules as MigrationHandler>::Genesis;
+
+ /// Perform runtime-specific state migration. This method is only called when the recorded
+ /// state version does not match `STATE_VERSION`.
+ fn migrate_state<C: Context>(_ctx: &C) {
+ // Default implementation doesn't perform any migration.
+ }
+
+ /// Whether a given query method is allowed to be invoked.
+ fn is_allowed_query(_method: &str) -> bool {
+ true
+ }
+
+ /// Whether a given query method is allowed to access private key manager state.
+ ///
+ /// Note that even if this returns `true` for a method, the method also needs to be tagged as
+ /// being allowed to access private key manager state (e.g. with `allow_private_km`).
+ fn is_allowed_private_km_query(_method: &str) -> bool {
+ true
+ }
+
+ /// Whether a given call is allowed to be invoked interactively.
+ ///
+ /// Note that even if this returns `true` for a method, the method also needs to be tagged as
+ /// being allowed to be executed interactively (e.g. with `allow_interactive`)
+ fn is_allowed_interactive_call(_method: &str) -> bool {
+ true
+ }
+
+ /// Perform state migrations if required.
+ fn migrate<C: Context>(ctx: &C) {
+ let mut metadata = CurrentState::with_store(|store| {
+ let store = storage::TypedStore::new(storage::PrefixStore::new(
+ store,
+ &modules::core::MODULE_NAME,
+ ));
+ let metadata: modules::core::types::Metadata = store
+ .get(modules::core::state::METADATA)
+ .unwrap_or_default();
+
+ metadata
+ });
+
+ // Perform state migrations/initialization on all modules.
+ let mut has_changes =
+ Self::Modules::init_or_migrate(ctx, &mut metadata, Self::genesis_state());
+
+ // Check if we need to also apply any global state updates.
+ let global_version = metadata
+ .versions
+ .get(modules::core::types::VERSION_GLOBAL_KEY)
+ .copied()
+ .unwrap_or_default();
+ if global_version != Self::STATE_VERSION
+ && !CurrentState::with_env(|env| env.is_check_only())
+ {
+ assert!(
+ // There should either be no state, or it should be the previous version.
+ global_version == 0 || global_version == Self::STATE_VERSION - 1,
+ "inconsistent existing state version (expected: {} got: {})",
+ Self::STATE_VERSION - 1,
+ global_version
+ );
+
+ Self::migrate_state(ctx);
+
+ // Update metadata.
+ metadata.versions.insert(
+ modules::core::types::VERSION_GLOBAL_KEY.to_string(),
+ Self::STATE_VERSION,
+ );
+ has_changes = true;
+ }
+
+ // If there are any changes, update metadata.
+ if has_changes {
+ CurrentState::with_store(|store| {
+ let mut store = storage::TypedStore::new(storage::PrefixStore::new(
+ store,
+ &modules::core::MODULE_NAME,
+ ));
+ store.insert(modules::core::state::METADATA, metadata);
+ });
+ }
+ }
+
+ /// Start the runtime.
+ fn start()
+ where
+ Self: Sized + Send + Sync + 'static,
+ {
+ // Initializer.
+ let init = |state: PreInitState<'_>| -> PostInitState {
+ // Fetch host information and configure domain separation context.
+ let hi = state.protocol.get_host_info();
+ crypto::signature::context::set_chain_context(
+ hi.runtime_id,
+ &hi.consensus_chain_context,
+ );
+
+ // Cobble together a keymanager client.
+ let key_manager = Self::trusted_signers().map(|signers| {
+ Arc::new(KeyManagerClient::new(
+ hi.runtime_id,
+ state.protocol.clone(),
+ state.consensus_verifier.clone(),
+ state.identity.clone(),
+ state.rpc_dispatcher,
+ 4096,
+ signers,
+ ))
+ });
+
+ // Create the transaction dispatcher.
+ let dispatcher = dispatcher::Dispatcher::<Self>::new(
+ state.protocol.clone(),
+ key_manager,
+ state.consensus_verifier.clone(),
+ );
+ // Register EnclaveRPC methods.
+ dispatcher.register_enclaverpc(state.rpc_dispatcher);
+ // Make sure we allow a wide amount of valid quotes for EnclaveRPC because our clients
+ // are other runtime components and we should accept them all.
+ let session_builder = session::Builder::default()
+ .local_identity(state.identity.clone())
+ .quote_policy(Some(Arc::new(sgx::QuotePolicy {
+ ias: Some(sgx::ias::QuotePolicy {
+ disabled: true, // Disable legacy EPID attestation.
+ ..Default::default()
+ }),
+ pcs: Some(sgx::pcs::QuotePolicy {
+ // Allow TDX since that is not part of the default policy.
+ tdx: Some(sgx::pcs::TdxQuotePolicy {
+ allowed_tdx_modules: vec![],
+ }),
+ ..Default::default()
+ }),
+ })));
+ state.rpc_demux.set_session_builder(session_builder);
+
+ PostInitState {
+ txn_dispatcher: Some(Box::new(dispatcher)),
+ app: None,
+ }
+ };
+
+ // Configure the runtime features.
+ let features = Features {
+ schedule_control: Some(FeatureScheduleControl {
+ initial_batch_size: Self::SCHEDULE_CONTROL.initial_batch_size,
+ }),
+ ..Default::default()
+ };
+
+ // Start the runtime.
+ start_runtime(
+ Box::new(init),
+ Config {
+ version: Self::VERSION,
+ trust_root: Self::consensus_trust_root(),
+ features,
+ persist_check_tx_state: false,
+ ..Default::default()
+ },
+ );
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +
//! Types related to schedule control.
+use oasis_core_runtime::{
+ common::crypto::hash::Hash, transaction::types::TxnBatch, types::Body, Protocol,
+};
+
+/// Unique module name.
+const MODULE_NAME: &str = "schedule_control";
+
+/// Schedule control errors.
+#[derive(Debug, thiserror::Error, oasis_runtime_sdk_macros::Error)]
+pub enum Error {
+ #[error("failed to fetch batch from host")]
+ #[sdk_error(code = 1)]
+ FailedToFetchBatch,
+}
+
+/// Interface to the runtime host that supports schedule control features.
+pub trait ScheduleControlHost: Send + Sync {
+ /// Fetch the specified set of transactions from the host's transaction queue.
+ ///
+ /// Offset specifies the transaction hash that should serve as an offset when returning
+ /// transactions from the pool. Transactions will be skipped until the given hash is encountered
+ /// and only following transactions will be returned.
+ fn fetch_tx_batch(&self, offset: Option<Hash>, limit: u32) -> Result<Option<TxnBatch>, Error>;
+}
+
+impl ScheduleControlHost for Protocol {
+ fn fetch_tx_batch(&self, offset: Option<Hash>, limit: u32) -> Result<Option<TxnBatch>, Error> {
+ match self.call_host(Body::HostFetchTxBatchRequest { offset, limit }) {
+ Ok(Body::HostFetchTxBatchResponse { batch }) => Ok(batch),
+ _ => Err(Error::FailedToFetchBatch),
+ }
+ }
+}
+//! Transaction sender metadata.
+use crate::types::address::Address;
+
+/// Transaction sender metadata.
+#[derive(Clone, Debug, Eq, PartialEq, Default)]
+pub struct SenderMeta {
+ /// Sender address.
+ pub address: Address,
+ /// Sender nonce contained in the transaction.
+ pub tx_nonce: u64,
+ /// Sender nonce contained in runtime state.
+ pub state_nonce: u64,
+}
+
+impl SenderMeta {
+ /// Unique identifier of the sender, currently derived from the sender address.
+ pub fn id(&self) -> Vec<u8> {
+ if self.address == Default::default() {
+ // Use an empty value for the default address as that signals to the host that the
+ // sender should be ignored.
+ vec![]
+ } else {
+ self.address.into_bytes().to_vec()
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +765 +766 +767 +768 +769 +770 +771 +772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805 +806 +807 +808 +809 +810 +811 +812 +813 +814 +815 +816 +817 +818 +819 +820 +821 +822 +823 +824 +825 +826 +827 +828 +829 +830 +831 +832 +833 +834 +835 +836 +837 +838 +839 +840 +841 +842 +843 +844 +845 +846 +847 +848 +849 +850 +851 +852 +853 +854 +855 +856 +857 +858 +859 +860 +861 +862 +863 +864 +865 +866 +867 +868 +869 +870 +871 +872 +873 +874 +875 +876 +877 +878 +879 +880 +881 +882 +883 +884 +885 +886 +887 +888 +889 +890 +891 +892 +893 +894 +895 +896 +897 +898 +899 +900 +901 +902 +903 +904 +905 +906 +907 +908 +909 +910 +911 +912 +913 +914 +915 +916 +917 +918 +919 +920 +921 +922 +923 +924 +925 +926 +927 +928 +929 +930 +931 +932 +933 +934 +935 +936 +937 +938 +939 +940 +941 +942 +943 +944 +945 +946 +947 +948 +949 +950 +951 +952 +953 +954 +955 +956 +957 +958 +959 +960 +961 +962 +963 +964 +965 +966 +967 +968 +969 +970 +971 +972 +973 +974 +975 +976 +977 +978 +979 +980 +981 +982 +983 +984 +985 +986 +987 +988 +989 +990 +991 +992 +993 +994 +995 +996 +997 +998 +999 +1000 +1001 +1002 +1003 +1004 +1005 +1006 +1007 +1008 +1009 +1010 +1011 +1012 +1013 +1014 +1015 +1016 +1017 +1018 +1019 +1020 +1021 +1022 +1023 +1024 +1025 +1026 +1027 +1028 +1029 +1030 +1031 +1032 +1033 +1034 +1035 +1036 +1037 +1038 +1039 +1040 +1041 +1042 +1043 +1044 +1045 +1046 +1047 +1048 +1049 +1050 +1051 +1052 +1053 +1054 +1055 +1056 +1057 +1058 +1059 +1060 +1061 +1062 +1063 +1064 +1065 +1066 +1067 +1068 +1069 +1070 +1071 +1072 +1073 +1074 +1075 +1076 +1077 +1078 +1079 +1080 +1081 +1082 +1083 +1084 +1085 +1086 +1087 +1088 +1089 +1090 +1091 +1092 +1093 +1094 +1095 +1096 +1097 +1098 +1099 +1100 +1101 +1102 +1103 +1104 +1105 +1106 +1107 +1108 +1109 +1110 +1111 +1112 +1113 +1114 +1115 +1116 +1117 +1118 +1119 +1120 +1121 +1122 +1123 +1124 +1125 +1126 +1127 +1128 +1129 +1130 +1131 +1132 +1133 +1134 +1135 +1136 +1137 +1138 +1139 +1140 +1141 +1142 +1143 +1144 +1145 +1146 +1147 +1148 +1149 +1150 +1151 +1152 +1153 +1154 +1155 +1156 +1157 +1158 +1159 +1160 +1161 +1162 +1163 +1164 +1165 +1166 +1167 +1168 +1169 +1170 +1171 +1172 +1173 +1174 +1175 +1176 +1177 +1178 +1179 +1180 +1181 +1182 +1183 +1184 +1185 +1186 +1187 +1188 +1189 +1190 +1191 +1192 +1193 +1194 +1195 +1196 +1197 +1198 +1199 +1200 +1201 +1202 +1203 +1204 +1205 +1206 +1207 +1208 +1209 +1210 +1211 +1212 +1213 +1214 +1215 +1216 +1217 +1218 +1219 +1220 +1221 +1222 +1223 +1224 +1225 +1226 +1227 +1228 +1229 +1230 +1231 +1232 +1233 +1234 +1235 +1236 +1237 +1238 +1239 +1240 +1241 +1242 +1243 +1244 +1245 +1246 +1247 +1248 +1249 +1250 +1251 +1252 +1253 +1254 +1255 +1256 +1257 +1258 +1259 +1260 +1261 +1262 +1263 +1264 +1265 +1266 +1267 +1268 +1269 +1270 +1271 +1272 +1273 +1274 +1275 +1276 +1277 +1278 +1279 +1280 +1281 +1282 +1283 +1284 +1285 +1286 +1287 +1288 +1289 +1290 +1291 +1292 +1293 +1294 +1295 +1296 +1297 +1298 +1299 +1300 +1301 +1302 +1303 +1304 +1305 +1306 +1307 +1308 +1309 +1310 +1311 +1312 +1313 +1314 +1315 +1316 +1317 +1318 +1319 +1320 +1321 +1322 +1323 +1324 +1325 +1326 +1327 +1328 +1329 +1330 +1331 +1332 +1333 +1334 +1335 +1336 +1337 +1338 +1339 +1340 +1341 +1342 +1343 +1344 +1345 +1346 +1347 +1348 +1349 +1350 +1351 +1352 +1353 +1354 +1355 +1356 +1357 +1358 +1359 +1360 +1361 +1362 +1363 +1364 +1365 +1366 +1367 +1368 +1369 +1370 +1371 +1372 +1373 +1374 +1375 +1376 +1377 +1378 +1379 +1380 +1381 +1382 +1383 +1384 +1385 +1386 +1387 +1388 +1389 +1390 +1391 +1392 +1393 +1394 +1395 +1396 +1397 +1398 +1399 +1400 +1401 +1402 +1403 +1404 +1405 +1406 +1407 +1408 +1409 +1410 +1411 +1412 +1413 +1414 +1415 +1416 +1417 +1418 +1419 +1420 +1421 +1422 +1423 +1424 +1425 +1426 +1427 +1428 +1429 +1430 +1431 +1432 +1433 +1434 +1435 +1436 +1437 +1438 +1439 +1440 +1441 +1442 +1443 +1444 +1445 +1446 +1447 +1448 +1449 +1450 +1451 +1452 +1453 +1454 +1455 +1456 +1457 +1458 +1459 +1460 +1461 +1462 +1463 +1464 +1465 +1466 +1467 +1468 +1469 +1470 +1471 +1472 +1473 +1474 +1475 +1476 +1477 +1478 +1479 +1480 +1481 +1482 +1483 +1484 +1485 +1486 +1487 +1488 +1489 +1490 +1491 +1492 +1493 +1494 +1495 +1496 +1497 +1498 +1499 +1500 +1501 +1502 +1503 +1504 +1505 +1506 +1507 +1508 +1509 +1510 +1511 +1512 +1513 +1514 +1515 +1516 +1517 +1518 +1519 +1520 +1521 +1522 +1523 +1524 +1525 +1526 +1527 +1528 +1529 +1530 +1531 +1532 +1533 +1534 +1535 +1536 +1537 +1538 +1539 +1540 +1541 +1542 +1543 +1544 +1545 +1546 +1547 +1548 +1549 +1550 +1551 +1552 +1553 +1554 +1555 +1556 +1557 +1558 +1559 +1560 +1561 +1562 +1563 +1564 +1565 +1566 +1567 +1568 +1569 +1570 +1571 +1572 +1573 +1574 +1575 +1576 +1577 +1578 +1579 +1580 +1581 +1582 +1583 +1584 +1585 +1586 +1587 +1588 +1589 +1590 +1591 +1592 +1593 +1594 +1595 +1596 +1597 +1598 +1599 +1600 +1601 +1602 +1603 +1604 +1605 +1606 +1607 +1608 +1609 +1610 +1611 +1612 +1613 +1614 +1615 +1616 +1617 +1618 +1619 +1620 +1621 +1622 +1623 +1624 +1625 +1626 +1627 +1628 +1629 +1630 +1631 +1632 +1633 +1634 +1635 +1636 +1637 +1638 +1639 +1640 +1641 +1642 +1643 +1644 +1645 +1646 +1647 +1648 +1649 +1650 +1651 +1652 +1653 +1654 +1655 +1656 +1657 +1658 +1659 +1660 +1661 +1662 +1663 +1664 +1665 +1666 +1667 +1668 +1669 +1670 +1671 +1672 +1673 +1674 +1675 +1676 +1677 +1678 +1679 +1680 +1681 +
use std::{
+ any::Any,
+ cell::RefCell,
+ collections::btree_map::{BTreeMap, Entry},
+ fmt,
+ marker::PhantomData,
+ mem,
+};
+
+use oasis_core_runtime::{common::crypto::hash::Hash, consensus::roothash, storage::mkvs};
+
+use crate::{
+ context::Context,
+ crypto::{random::RootRng, signature::PublicKey},
+ event::{Event, EventTag, EventTags},
+ modules::core::Error,
+ storage::{MKVSStore, NestedStore, OverlayStore, Store},
+ types::{address::Address, message::MessageEventHookInvocation, transaction},
+};
+
+/// Execution mode.
+#[derive(Clone, Copy, Default, Debug, PartialEq, Eq)]
+#[repr(u8)]
+pub enum Mode {
+ /// Actually execute transactions during block production.
+ #[default]
+ Execute,
+ /// Check that transactions are valid for local acceptance into the transaction pool.
+ Check,
+ /// Simulate transaction outcomes (e.g. for gas estimation).
+ Simulate,
+ /// Check that transactions are still valid before scheduling.
+ PreSchedule,
+}
+
+const MODE_CHECK: &str = "check";
+const MODE_EXECUTE: &str = "execute";
+const MODE_SIMULATE: &str = "simulate";
+const MODE_PRE_SCHEDULE: &str = "pre_schedule";
+
+impl fmt::Display for Mode {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ f.write_str(self.into())
+ }
+}
+
+impl From<&Mode> for &'static str {
+ fn from(m: &Mode) -> Self {
+ match m {
+ Mode::Check => MODE_CHECK,
+ Mode::Execute => MODE_EXECUTE,
+ Mode::Simulate => MODE_SIMULATE,
+ Mode::PreSchedule => MODE_PRE_SCHEDULE,
+ }
+ }
+}
+
+/// Information about the execution environment.
+#[derive(Clone, Default, Debug)]
+pub struct Environment {
+ mode: Mode,
+ tx: Option<TransactionWithMeta>,
+ internal: bool,
+}
+
+impl Environment {
+ /// Execution mode.
+ pub fn mode(&self) -> Mode {
+ self.mode
+ }
+
+ /// Whether the execution mode is such that only checks should be performed.
+ pub fn is_check_only(&self) -> bool {
+ matches!(self.mode, Mode::Check | Mode::PreSchedule)
+ }
+
+ /// Whether the execution mode is `Mode::PreSchedule`.
+ pub fn is_pre_schedule(&self) -> bool {
+ matches!(self.mode, Mode::PreSchedule)
+ }
+
+ /// Whether the execution mode is `Mode::Simulate`.
+ pub fn is_simulation(&self) -> bool {
+ matches!(self.mode, Mode::Simulate)
+ }
+
+ /// Whether the execution mode is `Mode::Execute`.
+ pub fn is_execute(&self) -> bool {
+ matches!(self.mode, Mode::Execute)
+ }
+
+ /// Whether there is an active transaction in the current environment.
+ pub fn is_transaction(&self) -> bool {
+ self.tx.is_some()
+ }
+
+ /// An active transaction's index (order) within the block.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called outside a transaction environment.
+ pub fn tx_index(&self) -> usize {
+ self.tx
+ .as_ref()
+ .map(|tx| tx.index)
+ .expect("only in transaction environment")
+ }
+
+ /// An active transaction's size in bytes.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called outside a transaction environment.
+ pub fn tx_size(&self) -> u32 {
+ self.tx
+ .as_ref()
+ .map(|tx| tx.size)
+ .expect("only in transaction environment")
+ }
+
+ /// An active transaction's authentication information.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called outside a transaction environment.
+ pub fn tx_auth_info(&self) -> &transaction::AuthInfo {
+ self.tx
+ .as_ref()
+ .map(|tx| &tx.data.auth_info)
+ .expect("only in transaction environment")
+ }
+
+ /// An active transaction's call format.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called outside a transaction environment.
+ pub fn tx_call_format(&self) -> transaction::CallFormat {
+ self.tx
+ .as_ref()
+ .map(|tx| tx.data.call.format)
+ .expect("only in transaction environment")
+ }
+
+ /// An active transaction's read only flag.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called outside a transaction environment.
+ pub fn is_read_only(&self) -> bool {
+ self.tx
+ .as_ref()
+ .map(|tx| tx.data.call.read_only)
+ .expect("only in transaction environment")
+ }
+
+ /// Whether the current execution environment is part of an internal subcall.
+ pub fn is_internal(&self) -> bool {
+ self.internal
+ }
+
+ /// Authenticated address of the caller.
+ ///
+ /// In case there are multiple signers of a transaction, this will return the address
+ /// corresponding to the first signer. If there are no signers, it returns the default address.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called outside a transaction environment.
+ pub fn tx_caller_address(&self) -> Address {
+ self.tx_auth_info()
+ .signer_info
+ .first()
+ .map(|si| si.address_spec.address())
+ .unwrap_or_default()
+ }
+
+ /// Authenticated caller public key if available.
+ ///
+ /// In case there are multiple signers of a transaction, this will return the public key
+ /// corresponding to the first signer. If there are no signers or if the address specification
+ /// does not represent a single public key, it returns `None`.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called outside a transaction environment.
+ pub fn tx_caller_public_key(&self) -> Option<PublicKey> {
+ self.tx_auth_info()
+ .signer_info
+ .first()
+ .and_then(|si| si.address_spec.public_key())
+ }
+}
+
+/// Decoded transaction with additional metadata.
+#[derive(Clone, Debug)]
+pub struct TransactionWithMeta {
+ /// Decoded transaction.
+ pub data: transaction::Transaction,
+ /// Transaction size.
+ pub size: u32,
+ /// Transaction index within the batch.
+ pub index: usize,
+ /// Transaction hash.
+ pub hash: Hash,
+}
+
+impl TransactionWithMeta {
+ /// Create transaction with metadata for an internally generated transaction.
+ ///
+ /// Internally generated transactions have zero size, index and hash.
+ pub fn internal(tx: transaction::Transaction) -> Self {
+ Self {
+ data: tx,
+ size: 0,
+ index: 0,
+ hash: Default::default(),
+ }
+ }
+}
+
+#[cfg(any(test, feature = "test"))]
+impl From<transaction::Transaction> for TransactionWithMeta {
+ fn from(tx: transaction::Transaction) -> Self {
+ Self::internal(tx) // For use in tests.
+ }
+}
+
+/// Environment modification options.
+#[derive(Clone, Default, Debug)]
+pub struct Options {
+ pub mode: Option<Mode>,
+ pub tx: Option<TransactionWithMeta>,
+ pub internal: Option<bool>,
+ pub rng_local_entropy: bool,
+}
+
+impl Options {
+ /// Create options with default values.
+ pub fn new() -> Self {
+ Self::default()
+ }
+
+ /// Change the execution mode of the environment.
+ pub fn with_mode(self, mode: Mode) -> Self {
+ Self {
+ mode: Some(mode),
+ ..self
+ }
+ }
+
+ /// Change the active transaction of the environment.
+ pub fn with_tx(self, tx: TransactionWithMeta) -> Self {
+ Self {
+ tx: Some(tx),
+ ..self
+ }
+ }
+
+ /// Change the internal flag of the environment.
+ pub fn with_internal(self, internal: bool) -> Self {
+ Self {
+ internal: Some(internal),
+ ..self
+ }
+ }
+
+ /// Request for local entropy to be mixed into the current RNG.
+ ///
+ /// # Determinisim
+ ///
+ /// Using this method will result in non-deterministic behavior as the node's local entropy is
+ /// mixed into the RNG. As such, this method should only be used in cases where non-determinism
+ /// is not problematic (e.g. local queries).
+ pub fn with_rng_local_entropy(self) -> Self {
+ Self {
+ rng_local_entropy: true,
+ ..self
+ }
+ }
+}
+
+/// Mutable block state of a runtime.
+///
+/// The state includes storage, emitted events, messages to consensus layer, etc. States can be
+/// nested via `open`, `commit` and `rollback` methods which behave like transactions.
+pub struct State {
+ parent: Option<Box<State>>,
+ store: Option<OverlayStore<Box<dyn Store>>>,
+
+ events: EventTags,
+ unconditional_events: EventTags,
+ messages: Vec<(roothash::Message, MessageEventHookInvocation)>,
+
+ block_values: BTreeMap<&'static str, Box<dyn Any>>,
+ hidden_block_values: Option<BTreeMap<&'static str, Box<dyn Any>>>,
+ local_values: BTreeMap<&'static str, Box<dyn Any>>,
+
+ rng: Option<RootRng>,
+ hidden_rng: Option<RootRng>,
+ env: Environment,
+
+ always_rollback: bool,
+}
+
+impl State {
+ /// Initialize the state with the given options.
+ fn init(&mut self, opts: Options) {
+ if let Some(mode) = opts.mode {
+ // Change mode.
+ self.env.mode = mode;
+ // If we have enabled pre-schedule or simulation mode, always rollback state and hide
+ // block values to prevent leaking them.
+ if matches!(mode, Mode::PreSchedule | Mode::Simulate) {
+ self.always_rollback = true;
+ self.hide_block_values();
+ }
+ }
+
+ if let Some(tx) = opts.tx {
+ // Change RNG state.
+ self.rng.as_mut().unwrap().append_tx(tx.hash);
+ // Change tx metadata.
+ self.env.tx = Some(tx);
+ }
+
+ if let Some(internal) = opts.internal {
+ self.env.internal = internal;
+ if internal {
+ self.hide_block_values();
+ }
+ }
+
+ if opts.rng_local_entropy {
+ // Append local entropy to RNG state.
+ self.rng.as_mut().unwrap().append_local_entropy();
+ }
+
+ if !matches!(self.env.mode, Mode::PreSchedule) {
+ // Record opening a child state in the RNG.
+ self.rng.as_mut().unwrap().append_subcontext();
+ } else {
+ // Use an invalid RNG as its use is not allowed in pre-schedule context.
+ self.disable_rng();
+ }
+ }
+
+ /// Open a child state after which self will point to the child state.
+ pub fn open(&mut self) {
+ let mut parent = Self {
+ parent: None,
+ store: None,
+ events: EventTags::new(),
+ unconditional_events: EventTags::new(),
+ messages: Vec::new(),
+ block_values: BTreeMap::new(),
+ hidden_block_values: None,
+ local_values: BTreeMap::new(),
+ rng: None,
+ hidden_rng: None,
+ env: self.env.clone(),
+ always_rollback: false,
+ };
+ mem::swap(&mut parent, self);
+
+ // Wrap parent store to create an overlay child store.
+ self.store = parent
+ .store
+ .take()
+ .map(|pstore| OverlayStore::new(Box::new(pstore) as Box<dyn Store>));
+
+ // Take block values map. We will put it back after commit/rollback.
+ mem::swap(&mut parent.block_values, &mut self.block_values);
+ // Take RNG. We will put it back after commit/rollback.
+ mem::swap(&mut parent.rng, &mut self.rng);
+
+ self.parent = Some(Box::new(parent));
+ }
+
+ fn convert_store(store: Box<dyn Store>) -> OverlayStore<Box<dyn Store>> {
+ let raw = Box::into_raw(store);
+ unsafe {
+ // SAFETY: This is safe because we always wrap child stores into OverlayStore.
+ *Box::from_raw(raw as *mut OverlayStore<Box<dyn Store>>)
+ }
+ }
+
+ /// Commit the current state and return to its parent state.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic when attempting to commit the root state.
+ pub fn commit(&mut self) {
+ if self.always_rollback {
+ self.rollback();
+ } else {
+ self._commit();
+ }
+ }
+
+ fn _commit(&mut self) {
+ let mut child = *self.parent.take().expect("cannot commit on root state");
+ mem::swap(&mut child, self);
+
+ // Commit storage.
+ self.store = child
+ .store
+ .take()
+ .map(|cstore| Self::convert_store(cstore.commit()));
+
+ // Propagate messages.
+ self.messages.extend(child.messages);
+
+ // Propagate events.
+ for (key, event) in child.events {
+ let events = self.events.entry(key).or_default();
+ events.extend(event);
+ }
+ for (key, event) in child.unconditional_events {
+ let events = self.unconditional_events.entry(key).or_default();
+ events.extend(event);
+ }
+
+ // Put back per-block values.
+ if let Some(mut block_values) = child.hidden_block_values {
+ mem::swap(&mut block_values, &mut self.block_values); // Block values were hidden.
+ } else {
+ mem::swap(&mut child.block_values, &mut self.block_values);
+ }
+ // Always drop local values.
+
+ // Put back RNG.
+ if child.hidden_rng.is_some() {
+ mem::swap(&mut child.hidden_rng, &mut self.rng); // RNG was hidden.
+ } else {
+ mem::swap(&mut child.rng, &mut self.rng);
+ }
+ }
+
+ /// Rollback the current state and return to its parent state.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic when attempting to rollback the root state.
+ pub fn rollback(&mut self) {
+ let mut child = *self.parent.take().expect("cannot rollback on root state");
+ mem::swap(&mut child, self);
+
+ // Rollback storage.
+ self.store = child
+ .store
+ .take()
+ .map(|cstore| Self::convert_store(cstore.rollback()));
+
+ // Always put back per-block values.
+ if let Some(mut block_values) = child.hidden_block_values {
+ mem::swap(&mut block_values, &mut self.block_values); // Block values were hidden.
+ } else {
+ mem::swap(&mut child.block_values, &mut self.block_values);
+ }
+ // Always drop local values.
+
+ // Always put back RNG.
+ if child.hidden_rng.is_some() {
+ mem::swap(&mut child.hidden_rng, &mut self.rng); // RNG was hidden.
+ } else {
+ mem::swap(&mut child.rng, &mut self.rng);
+ }
+ }
+
+ /// Fetches a block state value entry.
+ ///
+ /// Block values live as long as the root `State` and are propagated to child states. They are
+ /// not affected by state rollbacks. If you need state-scoped values, use local values.
+ pub fn block_value<V: Any>(&mut self, key: &'static str) -> StateValue<'_, V> {
+ StateValue::new(self.block_values.entry(key))
+ }
+
+ /// Fetches a local state value entry.
+ ///
+ /// Local values only live as long as the current `State`, are dropped upon exiting to parent
+ /// state and child states start with an empty set. If you need longer-lived values, use block
+ /// values.
+ pub fn local_value<V: Any>(&mut self, key: &'static str) -> StateValue<'_, V> {
+ StateValue::new(self.local_values.entry(key))
+ }
+
+ /// Hides block values from the current state which will have an empty set of values after this
+ /// method returns. Hidden values will be restored upon exit to parent state.
+ pub fn hide_block_values(&mut self) {
+ if self.parent.is_none() {
+ // Allowing hiding on root state would prevent those values from ever being recovered.
+ panic!("cannot hide block values on root state");
+ }
+ if self.hidden_block_values.is_some() {
+ return; // Parent block values already hidden.
+ }
+
+ self.hidden_block_values = Some(mem::take(&mut self.block_values));
+ }
+
+ /// Emitted messages count returns the number of messages emitted so far across this and all
+ /// parent states.
+ pub fn emitted_messages_count(&self) -> usize {
+ self.messages.len()
+ + self
+ .parent
+ .as_ref()
+ .map(|p| p.emitted_messages_count())
+ .unwrap_or_default()
+ }
+
+ /// Emitted messages count returns the number of messages emitted so far in this state, not
+ /// counting any parent states.
+ pub fn emitted_messages_local_count(&self) -> usize {
+ self.messages.len()
+ }
+
+ /// Maximum number of messages that can be emitted.
+ pub fn emitted_messages_max<C: Context>(&self, ctx: &C) -> u32 {
+ if self.env.is_transaction() {
+ let limit = self.env.tx_auth_info().fee.consensus_messages;
+ if limit > 0 {
+ limit
+ } else {
+ ctx.max_messages() // Zero means an implicit limit by gas use.
+ }
+ } else {
+ ctx.max_messages()
+ }
+ }
+
+ /// Queue a message to be emitted by the runtime for consensus layer to process.
+ pub fn emit_message<C: Context>(
+ &mut self,
+ ctx: &C,
+ msg: roothash::Message,
+ hook: MessageEventHookInvocation,
+ ) -> Result<(), Error> {
+ // Check against maximum number of messages that can be emitted per round.
+ if self.emitted_messages_count() >= self.emitted_messages_max(ctx) as usize {
+ return Err(Error::OutOfMessageSlots);
+ }
+
+ self.messages.push((msg, hook));
+
+ Ok(())
+ }
+
+ /// Take all messages accumulated in the current state.
+ pub fn take_messages(&mut self) -> Vec<(roothash::Message, MessageEventHookInvocation)> {
+ mem::take(&mut self.messages)
+ }
+
+ /// Emit an event.
+ pub fn emit_event<E: Event>(&mut self, event: E) {
+ self.emit_event_raw(event.into_event_tag());
+ }
+
+ /// Emit a raw event.
+ pub fn emit_event_raw(&mut self, etag: EventTag) {
+ let events = self.events.entry(etag.key).or_default();
+ events.push(etag.value);
+ }
+
+ /// Emit an unconditional event.
+ ///
+ /// The only difference to regular events is that these are handled as a separate set.
+ pub fn emit_unconditional_event<E: Event>(&mut self, event: E) {
+ let etag = event.into_event_tag();
+ let events = self.unconditional_events.entry(etag.key).or_default();
+ events.push(etag.value);
+ }
+
+ /// Take all regular events accumulated in the current state.
+ pub fn take_events(&mut self) -> EventTags {
+ mem::take(&mut self.events)
+ }
+
+ /// Take all unconditional events accumulated in the current state.
+ pub fn take_unconditional_events(&mut self) -> EventTags {
+ mem::take(&mut self.unconditional_events)
+ }
+
+ /// Take all events accumulated in the current state and return the merged set.
+ pub fn take_all_events(&mut self) -> EventTags {
+ let mut events = self.take_events();
+ let unconditional_events = self.take_unconditional_events();
+
+ for (key, val) in unconditional_events {
+ let tag = events.entry(key).or_default();
+ tag.extend(val)
+ }
+
+ events
+ }
+
+ /// Store associated with the state.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if no store exists.
+ pub fn store(&mut self) -> &mut dyn Store {
+ self.store.as_mut().unwrap()
+ }
+
+ /// Whether the store associated with the state has any pending updates.
+ pub fn has_pending_store_updates(&self) -> bool {
+ self.store
+ .as_ref()
+ .map(|store| store.has_pending_updates())
+ .unwrap_or_default()
+ }
+
+ /// Size (in bytes) of any pending updates in the associated store.
+ pub fn pending_store_update_byte_size(&self) -> usize {
+ self.store
+ .as_ref()
+ .map(|store| store.pending_update_byte_size())
+ .unwrap_or_default()
+ }
+
+ /// Random number generator.
+ pub fn rng(&mut self) -> &mut RootRng {
+ self.rng.as_mut().unwrap()
+ }
+
+ /// Disables the RNG by replacing the instance with an invalid RNG.
+ fn disable_rng(&mut self) {
+ if self.parent.is_none() {
+ // Allowing hiding on root state would prevent the RNG from ever being recovered.
+ panic!("cannot hide the RNG on root state");
+ }
+ if self.hidden_rng.is_some() {
+ return; // Parent RNG already hidden.
+ }
+
+ self.hidden_rng = mem::replace(&mut self.rng, Some(RootRng::invalid()));
+ }
+
+ /// Environment information.
+ pub fn env(&self) -> &Environment {
+ &self.env
+ }
+
+ /// Origin environment information.
+ ///
+ /// The origin environment is the first non-internal environment in the hierarchy.
+ pub fn env_origin(&self) -> &Environment {
+ match self.parent {
+ Some(ref parent) if self.env.internal => parent.env_origin(),
+ _ => &self.env,
+ }
+ }
+
+ /// Returns the nesting level of the current state.
+ pub fn level(&self) -> usize {
+ if let Some(ref parent) = self.parent {
+ parent.level() + 1
+ } else {
+ 0
+ }
+ }
+}
+
+thread_local! {
+ static CURRENT: RefCell<Vec<State>> = const { RefCell::new(Vec::new()) };
+}
+
+struct CurrentStateGuard;
+
+impl Drop for CurrentStateGuard {
+ fn drop(&mut self) {
+ CURRENT.with(|c| {
+ let root = c.borrow_mut().pop().expect("must have current state");
+ // Commit root state as it has been wrapped in an overlay.
+ let store = root
+ .store
+ .expect("must not have open child states after exiting root state");
+ store.commit();
+ });
+ }
+}
+
+struct TransactionGuard(usize);
+
+impl Drop for TransactionGuard {
+ fn drop(&mut self) {
+ let level = CurrentState::with(|state| state.level());
+
+ // If transaction hasn't been either committed or reverted, rollback.
+ if level == self.0 {
+ CurrentState::rollback_transaction();
+ }
+ }
+}
+
+/// Result of a transaction helper closure.
+pub enum TransactionResult<T> {
+ Commit(T),
+ Rollback(T),
+}
+
+impl From<()> for TransactionResult<()> {
+ fn from(_: ()) -> TransactionResult<()> {
+ TransactionResult::Commit(())
+ }
+}
+
+impl<R, E> From<Result<R, E>> for TransactionResult<Result<R, E>> {
+ fn from(v: Result<R, E>) -> TransactionResult<Result<R, E>> {
+ match v {
+ Ok(_) => TransactionResult::Commit(v),
+ Err(_) => TransactionResult::Rollback(v),
+ }
+ }
+}
+
+/// State attached to the current thread.
+pub struct CurrentState;
+
+impl CurrentState {
+ /// Attach a new state to the current thread and enter the state's context.
+ ///
+ /// The passed store is used as the root store.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called from within a `CurrentState::with` block.
+ pub fn enter<S, F, R>(root: S, f: F) -> R
+ where
+ S: Store,
+ F: FnOnce() -> R,
+ {
+ Self::enter_opts(
+ Options {
+ mode: Some(Default::default()), // Make sure there is a default mode.
+ ..Options::default()
+ },
+ root,
+ f,
+ )
+ }
+
+ /// Attach a new state to the current thread and enter the state's context.
+ ///
+ /// The passed store is used as the root store.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called from within a `CurrentState::with` block or if the mode
+ /// has not been explicitly set in `opts`.
+ pub fn enter_opts<S, F, R>(opts: Options, mut root: S, f: F) -> R
+ where
+ S: Store,
+ F: FnOnce() -> R,
+ {
+ let root = unsafe {
+ // SAFETY: Keeping the root store is safe as it can only be accessed from the current
+ // thread while we are running inside `CurrentState::enter` where we are holding a
+ // mutable reference on it.
+ std::mem::transmute::<&mut dyn Store, &mut (dyn Store + 'static)>(
+ &mut root as &mut dyn Store,
+ )
+ };
+ // Initialize the root state.
+ let mode = opts
+ .mode
+ .expect("mode must be explicitly set on root state");
+ let mut root = State {
+ parent: None,
+ store: Some(OverlayStore::new(Box::new(root) as Box<dyn Store>)),
+ events: EventTags::new(),
+ unconditional_events: EventTags::new(),
+ messages: Vec::new(),
+ block_values: BTreeMap::new(),
+ hidden_block_values: None,
+ local_values: BTreeMap::new(),
+ rng: Some(RootRng::new(mode)),
+ hidden_rng: None,
+ env: Default::default(),
+ always_rollback: false,
+ };
+ // Apply options to allow customization of the root state.
+ root.init(opts);
+
+ CURRENT.with(|c| {
+ c.try_borrow_mut()
+ .expect("must not re-enter from with block")
+ .push(root)
+ });
+ let _guard = CurrentStateGuard; // Ensure current state is popped once we return.
+
+ f()
+ }
+
+ /// Create an empty baseline state for the current thread.
+ ///
+ /// This should only be used in tests to have state always available.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if any states have been attached to the local thread or if called
+ /// within a `CurrentState::with` block.
+ #[doc(hidden)]
+ pub(crate) fn init_local_fallback() {
+ thread_local! {
+ static BASE_STATE_INIT: RefCell<bool> = const { RefCell::new(false) };
+ }
+
+ BASE_STATE_INIT.with(|initialized| {
+ // Initialize once per thread.
+ if *initialized.borrow() {
+ return;
+ }
+ *initialized.borrow_mut() = true;
+
+ let root = mkvs::OverlayTree::new(
+ mkvs::Tree::builder()
+ .with_root_type(mkvs::RootType::State)
+ .build(Box::new(mkvs::sync::NoopReadSyncer)),
+ );
+ let root = MKVSStore::new(root);
+
+ // Initialize the root state.
+ let root = State {
+ parent: None,
+ store: Some(OverlayStore::new(Box::new(root) as Box<dyn Store>)),
+ events: EventTags::new(),
+ unconditional_events: EventTags::new(),
+ messages: Vec::new(),
+ block_values: BTreeMap::new(),
+ hidden_block_values: None,
+ local_values: BTreeMap::new(),
+ rng: Some(RootRng::new(Default::default())),
+ hidden_rng: None,
+ env: Default::default(),
+ always_rollback: false,
+ };
+
+ CURRENT.with(|c| {
+ let mut current = c
+ .try_borrow_mut()
+ .expect("must not re-enter from with block");
+ assert!(
+ current.is_empty(),
+ "must have no prior states attached to local thread"
+ );
+
+ current.push(root);
+ });
+ });
+ }
+
+ /// Run a closure with the currently active state.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called outside `CurrentState::enter` or if any transaction methods
+ /// are called from the closure.
+ pub fn with<F, R>(f: F) -> R
+ where
+ F: FnOnce(&mut State) -> R,
+ {
+ CURRENT.with(|c| {
+ let mut current_ref = c.try_borrow_mut().expect("must not re-enter with");
+ let current = current_ref.last_mut().expect("must enter context");
+
+ f(current)
+ })
+ }
+
+ /// Run a closure with the store of the currently active state.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called outside `CurrentState::enter` or if any transaction methods
+ /// are called from the closure.
+ pub fn with_store<F, R>(f: F) -> R
+ where
+ F: FnOnce(&mut dyn Store) -> R,
+ {
+ Self::with(|state| f(state.store()))
+ }
+
+ /// Run a closure with the environment of the currently active state.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called outside `CurrentState::enter` or if any transaction methods
+ /// are called from the closure.
+ pub fn with_env<F, R>(f: F) -> R
+ where
+ F: FnOnce(&Environment) -> R,
+ {
+ Self::with(|state| f(state.env()))
+ }
+
+ /// Run a closure with the origin environment of the currently active state.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called outside `CurrentState::enter` or if any transaction methods
+ /// are called from the closure.
+ pub fn with_env_origin<F, R>(f: F) -> R
+ where
+ F: FnOnce(&Environment) -> R,
+ {
+ Self::with(|state| f(state.env_origin()))
+ }
+
+ /// Start a new transaction by opening a new child state.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called outside `CurrentState::enter` or if called within a
+ /// `CurrentState::with` block.
+ pub fn start_transaction() {
+ Self::with(|state| state.open());
+ }
+
+ /// Commit a previously started transaction.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called outside `CurrentState::enter`, if there is no currently
+ /// open transaction (started via `CurrentState::start_transaction`) or if called within a
+ /// `CurrentState::with` block.
+ pub fn commit_transaction() {
+ Self::with(|state| state.commit());
+ }
+
+ /// Rollback a previously started transaction.
+ ///
+ /// # Panics
+ ///
+ /// This method will panic if called outside `CurrentState::enter`, if there is no currently
+ /// open transaction (started via `CurrentState::start_transaction`) or if called within a
+ /// `CurrentState::with` block.
+ pub fn rollback_transaction() {
+ Self::with(|state| state.rollback());
+ }
+
+ /// Run a closure within a state transaction.
+ ///
+ /// If the closure returns `TransactionResult::Commit(R)` then the child state is committed,
+ /// otherwise the child state is rolled back.
+ pub fn with_transaction<F, R, Rs>(f: F) -> R
+ where
+ F: FnOnce() -> Rs,
+ Rs: Into<TransactionResult<R>>,
+ {
+ Self::with_transaction_opts(Options::default(), f)
+ }
+
+ /// Run a closure within a state transaction, allowing the caller to customize state.
+ ///
+ /// If the closure returns `TransactionResult::Commit(R)` then the child state is committed,
+ /// otherwise the child state is rolled back.
+ pub fn with_transaction_opts<F, R, Rs>(opts: Options, f: F) -> R
+ where
+ F: FnOnce() -> Rs,
+ Rs: Into<TransactionResult<R>>,
+ {
+ let level = Self::with(|state| {
+ state.open();
+ state.init(opts);
+ state.level()
+ });
+ let _guard = TransactionGuard(level); // Ensure transaction is always closed.
+
+ match f().into() {
+ TransactionResult::Commit(result) => {
+ Self::commit_transaction();
+ result
+ }
+ TransactionResult::Rollback(result) => {
+ Self::rollback_transaction();
+ result
+ }
+ }
+ }
+}
+
+/// A per-state arbitrary value.
+pub struct StateValue<'a, V> {
+ inner: Entry<'a, &'static str, Box<dyn Any>>,
+ _value: PhantomData<V>,
+}
+
+impl<'a, V: Any> StateValue<'a, V> {
+ fn new(inner: Entry<'a, &'static str, Box<dyn Any>>) -> Self {
+ Self {
+ inner,
+ _value: PhantomData,
+ }
+ }
+
+ /// Gets a reference to the specified per-state value.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the retrieved type is not the type that was stored.
+ pub fn get(self) -> Option<&'a V> {
+ match self.inner {
+ Entry::Occupied(oe) => Some(
+ oe.into_mut()
+ .downcast_ref()
+ .expect("type should stay the same"),
+ ),
+ _ => None,
+ }
+ }
+
+ /// Gets a mutable reference to the specified per-state value.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the retrieved type is not the type that was stored.
+ pub fn get_mut(&mut self) -> Option<&mut V> {
+ match &mut self.inner {
+ Entry::Occupied(oe) => Some(
+ oe.get_mut()
+ .downcast_mut()
+ .expect("type should stay the same"),
+ ),
+ _ => None,
+ }
+ }
+
+ /// Sets the context value, returning a mutable reference to the set value.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the retrieved type is not the type that was stored.
+ pub fn set(self, value: V) -> &'a mut V {
+ let value = Box::new(value);
+ match self.inner {
+ Entry::Occupied(mut oe) => {
+ oe.insert(value);
+ oe.into_mut()
+ }
+ Entry::Vacant(ve) => ve.insert(value),
+ }
+ .downcast_mut()
+ .expect("type should stay the same")
+ }
+
+ /// Takes the context value, if it exists.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the retrieved type is not the type that was stored.
+ pub fn take(self) -> Option<V> {
+ match self.inner {
+ Entry::Occupied(oe) => {
+ Some(*oe.remove().downcast().expect("type should stay the same"))
+ }
+ Entry::Vacant(_) => None,
+ }
+ }
+}
+
+impl<'a, V: Any + Default> StateValue<'a, V> {
+ /// Retrieves the existing value or inserts and returns the default.
+ ///
+ /// # Panics
+ ///
+ /// Panics if the retrieved type is not the type that was stored.
+ pub fn or_default(self) -> &'a mut V {
+ match self.inner {
+ Entry::Occupied(oe) => oe.into_mut(),
+ Entry::Vacant(ve) => ve.insert(Box::<V>::default()),
+ }
+ .downcast_mut()
+ .expect("type should stay the same")
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use oasis_core_runtime::{
+ common::versioned::Versioned,
+ consensus::{roothash, staking},
+ storage::mkvs,
+ };
+
+ use super::{CurrentState, Mode, Options, TransactionResult, TransactionWithMeta};
+ use crate::{
+ modules::core::Event,
+ storage::{MKVSStore, Store},
+ testing::mock::{self, Mock},
+ types::message::MessageEventHookInvocation,
+ };
+
+ #[test]
+ fn test_value() {
+ CurrentState::init_local_fallback();
+
+ CurrentState::with(|state| {
+ let x = state.block_value::<u64>("module.TestKey").get();
+ assert_eq!(x, None);
+
+ state.block_value::<u64>("module.TestKey").set(42);
+
+ let y = state.block_value::<u64>("module.TestKey").get();
+ assert_eq!(y, Some(&42u64));
+
+ let z = state.block_value::<u64>("module.TestKey").take();
+ assert_eq!(z, Some(42u64));
+
+ let y = state.block_value::<u64>("module.TestKey").get();
+ assert_eq!(y, None);
+ });
+ }
+
+ #[test]
+ #[should_panic]
+ fn test_value_type_change_block_value() {
+ CurrentState::init_local_fallback();
+
+ CurrentState::with(|state| {
+ state.block_value::<u64>("module.TestKey").or_default();
+ state.block_value::<u32>("module.TestKey").get();
+ });
+ }
+
+ #[test]
+ #[should_panic]
+ fn test_value_type_change_local_value() {
+ CurrentState::init_local_fallback();
+
+ CurrentState::with(|state| {
+ state.local_value::<u64>("module.TestKey").or_default();
+ state.local_value::<u32>("module.TestKey").get();
+ });
+ }
+
+ #[test]
+ fn test_value_hidden_block_values() {
+ CurrentState::init_local_fallback();
+
+ CurrentState::with(|state| {
+ state.block_value("module.TestKey").set(42u64);
+
+ state.open();
+ state.hide_block_values();
+
+ let v = state.block_value::<u64>("module.TestKey").get();
+ assert!(v.is_none(), "block values should not propagate when hidden");
+
+ state.block_value("module.TestKey").set(48u64);
+
+ state.commit();
+
+ let v = state.block_value::<u64>("module.TestKey").get();
+ assert_eq!(
+ v,
+ Some(&42u64),
+ "block values should not propagate when hidden"
+ );
+ });
+ }
+
+ #[test]
+ fn test_value_local() {
+ CurrentState::init_local_fallback();
+
+ CurrentState::with(|state| {
+ state.block_value("module.TestKey").set(42u64);
+
+ state.open();
+
+ let mut y = state.block_value::<u64>("module.TestKey");
+ let y = y.get_mut().unwrap();
+ assert_eq!(*y, 42);
+ *y = 48;
+
+ let a = state.local_value::<u64>("module.TestTxKey").get();
+ assert_eq!(a, None);
+ state.local_value::<u64>("module.TestTxKey").set(65);
+
+ let b = state.local_value::<u64>("module.TestTxKey").get();
+ assert_eq!(b, Some(&65));
+
+ let c = state
+ .local_value::<u64>("module.TestTakeTxKey")
+ .or_default();
+ *c = 67;
+ let d = state.local_value::<u64>("module.TestTakeTxKey").take();
+ assert_eq!(d, Some(67));
+ let e = state.local_value::<u64>("module.TestTakeTxKey").get();
+ assert_eq!(e, None);
+
+ state.rollback(); // Block values are always propagated.
+
+ let x = state.block_value::<u64>("module.TestKey").get();
+ assert_eq!(x, Some(&48));
+
+ state.open();
+
+ let z = state.block_value::<u64>("module.TestKey").take();
+ assert_eq!(z, Some(48));
+
+ let a = state.local_value::<u64>("module.TestTxKey").get();
+ assert_eq!(a, None, "local values should not be propagated");
+
+ state.rollback(); // Block values are always propagated.
+
+ let y = state.block_value::<u64>("module.TestKey").get();
+ assert_eq!(y, None);
+ });
+ }
+
+ #[test]
+ fn test_emit_messages() {
+ let mut mock = Mock::default(); // Also creates local fallback state.
+ let max_messages = mock.max_messages as usize;
+ let ctx = mock.create_ctx();
+
+ CurrentState::with(|state| {
+ state.open();
+
+ assert_eq!(state.emitted_messages_count(), 0);
+ assert_eq!(state.emitted_messages_local_count(), 0);
+
+ state
+ .emit_message(
+ &ctx,
+ roothash::Message::Staking(Versioned::new(
+ 0,
+ roothash::StakingMessage::Transfer(staking::Transfer::default()),
+ )),
+ MessageEventHookInvocation::new("test".to_string(), ""),
+ )
+ .expect("message emission should succeed");
+ assert_eq!(state.emitted_messages_count(), 1);
+ assert_eq!(state.emitted_messages_local_count(), 1);
+ assert_eq!(state.emitted_messages_max(&ctx), max_messages as u32);
+
+ state.open(); // Start child state.
+
+ assert_eq!(state.emitted_messages_local_count(), 0);
+
+ state
+ .emit_message(
+ &ctx,
+ roothash::Message::Staking(Versioned::new(
+ 0,
+ roothash::StakingMessage::Transfer(staking::Transfer::default()),
+ )),
+ MessageEventHookInvocation::new("test".to_string(), ""),
+ )
+ .expect("message emission should succeed");
+ assert_eq!(state.emitted_messages_count(), 2);
+ assert_eq!(state.emitted_messages_local_count(), 1);
+ assert_eq!(state.emitted_messages_max(&ctx), max_messages as u32);
+
+ state.rollback(); // Rollback.
+
+ assert_eq!(
+ state.emitted_messages_count(),
+ 1,
+ "emitted message should have been rolled back"
+ );
+ assert_eq!(state.emitted_messages_local_count(), 1);
+
+ state.open(); // Start child state.
+
+ assert_eq!(state.emitted_messages_local_count(), 0);
+
+ state
+ .emit_message(
+ &ctx,
+ roothash::Message::Staking(Versioned::new(
+ 0,
+ roothash::StakingMessage::Transfer(staking::Transfer::default()),
+ )),
+ MessageEventHookInvocation::new("test".to_string(), ""),
+ )
+ .expect("message emission should succeed");
+ assert_eq!(state.emitted_messages_count(), 2);
+ assert_eq!(state.emitted_messages_local_count(), 1);
+
+ state.commit(); // Commit.
+
+ assert_eq!(
+ state.emitted_messages_count(),
+ 2,
+ "emitted message should have been committed"
+ );
+
+ // Emit some more messages.
+ for _ in 0..max_messages - 2 {
+ state
+ .emit_message(
+ &ctx,
+ roothash::Message::Staking(Versioned::new(
+ 0,
+ roothash::StakingMessage::Transfer(staking::Transfer::default()),
+ )),
+ MessageEventHookInvocation::new("test".to_string(), ""),
+ )
+ .expect("message emission should succeed");
+ }
+ assert_eq!(state.emitted_messages_count(), max_messages);
+
+ // Emitting one more message should be rejected.
+ state
+ .emit_message(
+ &ctx,
+ roothash::Message::Staking(Versioned::new(
+ 0,
+ roothash::StakingMessage::Transfer(staking::Transfer::default()),
+ )),
+ MessageEventHookInvocation::new("test".to_string(), ""),
+ )
+ .expect_err("message emission should fail due to out of slots");
+ assert_eq!(state.emitted_messages_count(), max_messages);
+
+ state.rollback(); // Rollback.
+
+ assert_eq!(state.emitted_messages_count(), 0);
+ });
+
+ // Change the maximum amount of messages.
+ let mut tx = mock::transaction();
+ tx.auth_info.fee.consensus_messages = 1; // Limit amount of messages.
+ CurrentState::with_transaction_opts(Options::new().with_tx(tx.into()), || {
+ CurrentState::with(|state| {
+ assert_eq!(state.emitted_messages_max(&ctx), 1);
+ });
+ });
+
+ let mut tx = mock::transaction();
+ tx.auth_info.fee.consensus_messages = 0; // Zero means an implicit limit by gas use.
+ CurrentState::with_transaction_opts(Options::new().with_tx(tx.into()), || {
+ CurrentState::with(|state| {
+ assert_eq!(state.emitted_messages_max(&ctx), max_messages as u32);
+ });
+ });
+ }
+
+ #[test]
+ fn test_emit_events() {
+ CurrentState::init_local_fallback();
+
+ CurrentState::with(|state| {
+ state.open();
+
+ state.open();
+
+ state.emit_event(Event::GasUsed { amount: 41 });
+ state.emit_event(Event::GasUsed { amount: 42 });
+ state.emit_event(Event::GasUsed { amount: 43 });
+
+ state.emit_unconditional_event(Event::GasUsed { amount: 10 });
+
+ state.commit();
+
+ let events = state.take_events();
+ assert_eq!(events.len(), 1, "events should have been propagated");
+ let event_key = b"core\x00\x00\x00\x01".to_vec();
+ assert_eq!(events[&event_key].len(), 3);
+
+ let events = state.take_unconditional_events();
+ assert_eq!(
+ events.len(),
+ 1,
+ "unconditional events should have been propagated"
+ );
+ let event_key = b"core\x00\x00\x00\x01".to_vec();
+ assert_eq!(events[&event_key].len(), 1);
+
+ state.emit_event(Event::GasUsed { amount: 41 });
+ state.emit_event(Event::GasUsed { amount: 42 });
+ state.emit_event(Event::GasUsed { amount: 43 });
+
+ state.emit_unconditional_event(Event::GasUsed { amount: 20 });
+
+ state.rollback();
+
+ let events = state.take_events();
+ assert_eq!(events.len(), 0, "events should not have been propagated");
+
+ let events = state.take_unconditional_events();
+ assert_eq!(
+ events.len(),
+ 0,
+ "unconditional events should not have been propagated"
+ );
+ });
+ }
+
+ fn test_store_basic() {
+ CurrentState::start_transaction();
+
+ assert!(
+ !CurrentState::with(|state| state.has_pending_store_updates()),
+ "should not have pending updates"
+ );
+
+ CurrentState::with_store(|store| {
+ store.insert(b"test", b"value");
+ });
+
+ assert!(
+ CurrentState::with(|state| state.has_pending_store_updates()),
+ "should have pending updates after insert"
+ );
+
+ // Transaction helper.
+ CurrentState::with_transaction(|| {
+ assert!(
+ !CurrentState::with(|state| state.has_pending_store_updates()),
+ "should not have pending updates"
+ );
+
+ CurrentState::with_store(|store| {
+ store.insert(b"test", b"b0rken");
+ });
+
+ assert!(
+ CurrentState::with(|state| state.has_pending_store_updates()),
+ "should have pending updates after insert"
+ );
+
+ TransactionResult::Rollback(())
+ });
+
+ // Transaction helper with options.
+ CurrentState::with_transaction_opts(
+ Options::new()
+ .with_mode(Mode::Check)
+ .with_internal(true)
+ .with_tx(TransactionWithMeta {
+ data: mock::transaction(),
+ size: 888,
+ index: 42,
+ hash: Default::default(),
+ }),
+ || {
+ CurrentState::with_env(|env| {
+ assert!(env.is_check_only(), "environment should be updated");
+ assert!(env.is_internal(), "environment should be updated");
+ assert!(env.is_transaction(), "environment should be updated");
+ assert_eq!(env.tx_index(), 42, "environment should be updated");
+ assert_eq!(env.tx_size(), 888, "environment should be updated");
+ });
+
+ CurrentState::with_env_origin(|env_origin| {
+ assert!(
+ !env_origin.is_check_only(),
+ "origin environment should be correct"
+ );
+ assert!(
+ !env_origin.is_transaction(),
+ "origin environment should be correct"
+ );
+ });
+
+ CurrentState::with_transaction(|| {
+ // Check environment propagation.
+ CurrentState::with_env(|env| {
+ assert!(env.is_check_only(), "environment should propagate");
+ assert!(env.is_internal(), "environment should propagate");
+ assert!(env.is_transaction(), "environment should propagate");
+ assert_eq!(env.tx_index(), 42, "environment should propagate");
+ assert_eq!(env.tx_size(), 888, "environment should propagate");
+ });
+
+ TransactionResult::Rollback(())
+ });
+
+ TransactionResult::Rollback(())
+ },
+ );
+
+ CurrentState::with_env(|env| {
+ assert!(!env.is_transaction(), "environment should not leak");
+ });
+
+ // Nested entering, but with a different store.
+ let unrelated = mkvs::OverlayTree::new(
+ mkvs::Tree::builder()
+ .with_root_type(mkvs::RootType::State)
+ .build(Box::new(mkvs::sync::NoopReadSyncer)),
+ );
+ let mut unrelated = MKVSStore::new(unrelated);
+
+ CurrentState::enter(&mut unrelated, || {
+ CurrentState::start_transaction();
+
+ CurrentState::with_store(|store| {
+ store.insert(b"test", b"should not touch the original root");
+ });
+
+ CurrentState::commit_transaction();
+ });
+
+ CurrentState::with_store(|store| {
+ store.insert(b"another", b"value 2");
+ });
+
+ CurrentState::commit_transaction();
+ }
+
+ #[test]
+ fn test_basic() {
+ let root = mkvs::OverlayTree::new(
+ mkvs::Tree::builder()
+ .with_root_type(mkvs::RootType::State)
+ .build(Box::new(mkvs::sync::NoopReadSyncer)),
+ );
+ let mut root = MKVSStore::new(root);
+
+ CurrentState::enter(&mut root, || {
+ test_store_basic();
+ });
+
+ let value = root.get(b"test").unwrap();
+ assert_eq!(value, b"value");
+ }
+
+ #[test]
+ fn test_local_fallback() {
+ // Initialize the local fallback store.
+ CurrentState::init_local_fallback();
+ CurrentState::init_local_fallback(); // Should be no-op.
+
+ // Test the basic store -- note, no need to enter as fallback current store is available.
+ test_store_basic();
+
+ CurrentState::with_store(|store| {
+ let value = store.get(b"test").unwrap();
+ assert_eq!(value, b"value");
+ });
+
+ // It should be possible to override the fallback by entering explicitly.
+ let root = mkvs::OverlayTree::new(
+ mkvs::Tree::builder()
+ .with_root_type(mkvs::RootType::State)
+ .build(Box::new(mkvs::sync::NoopReadSyncer)),
+ );
+ let mut root = MKVSStore::new(root);
+
+ CurrentState::enter(&mut root, || {
+ CurrentState::with_store(|store| {
+ assert!(store.get(b"test").is_none(), "store should be empty");
+ store.insert(b"unrelated", b"unrelated");
+ });
+
+ test_store_basic();
+ });
+
+ let value = root.get(b"test").unwrap();
+ assert_eq!(value, b"value");
+ let value = root.get(b"unrelated").unwrap();
+ assert_eq!(value, b"unrelated");
+
+ // Changes should not leak to fallback store.
+ CurrentState::with_store(|store| {
+ assert!(store.get(b"unrelated").is_none(), "changes should not leak");
+ });
+ }
+
+ #[test]
+ #[should_panic(expected = "must enter context")]
+ fn test_fail_not_entered() {
+ test_store_basic(); // Should panic due to no current store being available.
+ }
+
+ #[test]
+ #[should_panic(expected = "must not re-enter with")]
+ fn test_fail_reenter_with() {
+ CurrentState::init_local_fallback();
+
+ CurrentState::with(|_| {
+ CurrentState::with(|_| {
+ // Should panic.
+ });
+ });
+ }
+
+ #[test]
+ #[should_panic(expected = "must not re-enter with")]
+ fn test_fail_reenter_with_start_transaction() {
+ CurrentState::init_local_fallback();
+
+ CurrentState::with(|_| {
+ CurrentState::start_transaction(); // Should panic.
+ });
+ }
+
+ #[test]
+ #[should_panic(expected = "must not re-enter with")]
+ fn test_fail_reenter_with_commit_transaction() {
+ CurrentState::init_local_fallback();
+
+ CurrentState::with(|_| {
+ CurrentState::commit_transaction(); // Should panic.
+ });
+ }
+
+ #[test]
+ #[should_panic(expected = "must not re-enter with")]
+ fn test_fail_reenter_with_rollback_transaction() {
+ CurrentState::init_local_fallback();
+
+ CurrentState::with(|_| {
+ CurrentState::rollback_transaction(); // Should panic.
+ });
+ }
+
+ #[test]
+ #[should_panic(expected = "must not re-enter from with block")]
+ fn test_fail_reenter_with_enter() {
+ CurrentState::init_local_fallback();
+
+ CurrentState::with(|_| {
+ let unrelated = mkvs::OverlayTree::new(
+ mkvs::Tree::builder()
+ .with_root_type(mkvs::RootType::State)
+ .build(Box::new(mkvs::sync::NoopReadSyncer)),
+ );
+ let mut unrelated = MKVSStore::new(unrelated);
+
+ CurrentState::enter(&mut unrelated, || {
+ // Should panic.
+ });
+ });
+ }
+
+ #[test]
+ #[should_panic(expected = "must not re-enter from with block")]
+ fn test_fail_local_fallback_within_with() {
+ let root = mkvs::OverlayTree::new(
+ mkvs::Tree::builder()
+ .with_root_type(mkvs::RootType::State)
+ .build(Box::new(mkvs::sync::NoopReadSyncer)),
+ );
+ let mut root = MKVSStore::new(root);
+
+ CurrentState::enter(&mut root, || {
+ CurrentState::with(|_| {
+ CurrentState::init_local_fallback(); // Should panic.
+ })
+ });
+ }
+
+ #[test]
+ #[should_panic(expected = "must have no prior states attached to local thread")]
+ fn test_fail_local_fallback_within_enter() {
+ let root = mkvs::OverlayTree::new(
+ mkvs::Tree::builder()
+ .with_root_type(mkvs::RootType::State)
+ .build(Box::new(mkvs::sync::NoopReadSyncer)),
+ );
+ let mut root = MKVSStore::new(root);
+
+ CurrentState::enter(&mut root, || {
+ CurrentState::init_local_fallback(); // Should panic.
+ });
+ }
+
+ #[test]
+ #[should_panic(expected = "cannot commit on root state")]
+ fn test_fail_commit_transaction_must_exist() {
+ CurrentState::init_local_fallback();
+
+ CurrentState::commit_transaction(); // Should panic.
+ }
+
+ #[test]
+ #[should_panic(expected = "cannot rollback on root state")]
+ fn test_fail_rollback_transaction_must_exist() {
+ CurrentState::init_local_fallback();
+
+ CurrentState::rollback_transaction(); // Should panic.
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +
use std::convert::TryInto as _;
+
+use anyhow;
+use hmac::{Hmac, Mac as _};
+use sha2::Sha512_256;
+use slog::error;
+use thiserror::Error;
+use zeroize::{Zeroize, Zeroizing};
+
+pub use crate::core::common::crypto::mrae::deoxysii::KEY_SIZE;
+use crate::{
+ core::{
+ common::crypto::{
+ hash::Hash,
+ mrae::deoxysii::{self, NONCE_SIZE},
+ },
+ storage::mkvs,
+ },
+ storage::Store,
+};
+
+type Nonce = [u8; NONCE_SIZE];
+type Kdf = Hmac<Sha512_256>;
+
+/// Unpack the concatenation of (nonce || byte_slice) into (Nonce, &[u8]).
+fn unpack_nonce_slice<'a>(packed: &'a [u8]) -> Option<(&'a Nonce, &'a [u8])> {
+ if packed.len() <= NONCE_SIZE {
+ return None;
+ }
+ let nonce_ref: &'a Nonce = packed[..NONCE_SIZE]
+ .try_into()
+ .expect("nonce size mismatch");
+ Some((nonce_ref, &packed[NONCE_SIZE..]))
+}
+
+/// Errors emitted by the confidential store.
+#[derive(Error, Debug)]
+pub enum Error {
+ #[error("corrupt key")]
+ CorruptKey,
+
+ #[error("corrupt value")]
+ CorruptValue,
+
+ #[error("decryption failure: {0}")]
+ DecryptionFailure(anyhow::Error),
+}
+
+/// A key-value store that encrypts all content with DeoxysII.
+pub struct ConfidentialStore<S: Store> {
+ inner: S,
+ deoxys: deoxysii::DeoxysII,
+ base_value_prefix: Vec<u8>,
+ nonce_counter: usize,
+ nonce_key: Zeroizing<Vec<u8>>,
+}
+
+impl<S: Store> ConfidentialStore<S> {
+ /// Create a new confidential store with the given keypair.
+ pub fn new_with_key(inner: S, key: [u8; KEY_SIZE], value_context: &[&[u8]]) -> Self {
+ let actual_key = Zeroizing::new(key);
+
+ // Derive a nonce key for nonces used to encrypt storage keys in the store:
+ // nonce_key = KDF(key)
+ let mut kdf = Kdf::new_from_slice(b"oasis-runtime-sdk/confidential-store: nonce key")
+ .expect("Hmac::new_from_slice");
+ kdf.update(&key);
+ let mut derived = kdf.finalize().into_bytes();
+ // Try to destroy as much of the bytes as possible; there's
+ // no neat way to get from kdf output to a Vec<u8> without copying a lot.
+ let derived = Zeroizing::new(derived.iter_mut());
+
+ ConfidentialStore {
+ inner,
+ deoxys: deoxysii::DeoxysII::new(&actual_key),
+ base_value_prefix: value_context.concat(),
+ nonce_counter: 0,
+ nonce_key: Zeroizing::new(derived.as_slice().to_vec()),
+ }
+ }
+
+ fn pack_nonce_slice(&self, nonce: &Nonce, slice: &[u8]) -> Vec<u8> {
+ let mut ret = Vec::with_capacity(nonce.len() + slice.len());
+ ret.extend_from_slice(nonce);
+ ret.extend_from_slice(slice);
+ ret
+ }
+
+ fn make_key(&self, plain_key: &[u8]) -> (Nonce, Vec<u8>) {
+ // The nonce used to encrypt storage keys is derived from a combination
+ // of a base nonce key (derived from the encryption key) and the
+ // incoming plaintext storage key:
+ // nonce = Trunc(NONCE_SIZE, H(nonce_key || plain_key))
+ let mut nonce = [0u8; NONCE_SIZE];
+
+ let mut nonce_src = self.nonce_key.clone();
+ nonce_src.extend_from_slice(plain_key);
+
+ let hash = Hash::digest_bytes(&nonce_src);
+ nonce.copy_from_slice(hash.truncated(NONCE_SIZE));
+
+ let enc_key = self.deoxys.seal(&nonce, plain_key, vec![]);
+ let key = self.pack_nonce_slice(&nonce, &enc_key);
+ (nonce, key)
+ }
+
+ fn make_value(&mut self, plain_value: &[u8]) -> (Nonce, Vec<u8>) {
+ // Nonces for value encryption are derived from deterministic
+ // environmental data which hopefully changes a lot. In particular,
+ // the base_value_prefix should change every time the store is
+ // instantiated, and the nonce_counter changes during the store's lifetime.
+ // nonce = Trunc(NONCE_SIZE, H(base_prefix || nonce_counter))
+ let mut nonce = [0u8; NONCE_SIZE];
+
+ self.nonce_counter += 1;
+ let hash = Hash::digest_bytes_list(&[
+ self.base_value_prefix.as_slice(),
+ self.nonce_counter.to_le_bytes().as_slice(),
+ ]);
+ nonce.copy_from_slice(hash.truncated(NONCE_SIZE));
+
+ let enc_value = self.deoxys.seal(&nonce, plain_value, vec![]);
+ let value = self.pack_nonce_slice(&nonce, &enc_value);
+ (nonce, value)
+ }
+
+ fn get_item(&self, raw: &[u8]) -> Result<(Nonce, Vec<u8>), Error> {
+ match unpack_nonce_slice(raw) {
+ Some((nonce, enc_ref)) => {
+ let enc = Vec::from(enc_ref);
+ let plain = self
+ .deoxys
+ .open(nonce, enc, vec![])
+ .map_err(|err| Error::DecryptionFailure(err.into()))?;
+ Ok((*nonce, plain))
+ }
+ None => Err(Error::CorruptKey),
+ }
+ }
+}
+
+impl<S: Store> Zeroize for ConfidentialStore<S> {
+ fn zeroize(&mut self) {
+ self.deoxys.zeroize();
+ self.nonce_key.zeroize();
+ }
+}
+
+impl<S: Store> Store for ConfidentialStore<S> {
+ fn get(&self, key: &[u8]) -> Option<Vec<u8>> {
+ let (_, inner_key) = self.make_key(key);
+ self.inner.get(&inner_key).map(|inner_value| {
+ self.get_item(&inner_value)
+ .expect("error decrypting value")
+ .1
+ })
+ }
+
+ fn insert(&mut self, key: &[u8], value: &[u8]) {
+ let (_, inner_key) = self.make_key(key);
+ let (_, inner_value) = self.make_value(value);
+ self.inner.insert(&inner_key, &inner_value)
+ }
+
+ fn remove(&mut self, key: &[u8]) {
+ let (_, inner_key) = self.make_key(key);
+ self.inner.remove(&inner_key)
+ }
+
+ fn iter(&self) -> Box<dyn mkvs::Iterator + '_> {
+ Box::new(ConfidentialStoreIterator::new(self))
+ }
+
+ fn prefetch_prefixes(&mut self, prefixes: Vec<mkvs::Prefix>, limit: u16) {
+ self.inner.prefetch_prefixes(prefixes, limit);
+ }
+}
+
+struct ConfidentialStoreIterator<'store, S: Store> {
+ inner: Box<dyn mkvs::Iterator + 'store>,
+ store: &'store ConfidentialStore<S>,
+
+ key: Option<mkvs::Key>,
+ value: Option<Vec<u8>>,
+ error: Option<anyhow::Error>,
+}
+
+impl<'store, S: Store> ConfidentialStoreIterator<'store, S> {
+ fn new(store: &'store ConfidentialStore<S>) -> ConfidentialStoreIterator<'_, S> {
+ ConfidentialStoreIterator {
+ inner: store.inner.iter(),
+ store,
+ key: None,
+ value: None,
+ error: None,
+ }
+ }
+
+ fn reset(&mut self) {
+ self.key = None;
+ self.value = None;
+ self.error = None;
+ }
+
+ fn load(&mut self, inner_key: &[u8], inner_value: &[u8]) {
+ if !mkvs::Iterator::is_valid(self) {
+ return;
+ }
+
+ match self.store.get_item(inner_key) {
+ Ok((_, key)) => match self.store.get_item(inner_value) {
+ Ok((_, value)) => {
+ self.key = Some(key);
+ self.value = Some(value);
+ }
+ Err(err) => {
+ self.error = Some(err.into());
+ }
+ },
+ Err(err) => {
+ self.error = Some(err.into());
+ }
+ }
+ }
+
+ fn reset_and_load(&mut self) {
+ self.reset();
+ if self.inner.is_valid() {
+ if let Some(ref inner_key) = self.inner.get_key().clone() {
+ if let Some(ref inner_value) = self.inner.get_value().clone() {
+ self.load(inner_key, inner_value);
+ } else {
+ self.error = Some(anyhow::anyhow!("no value in valid inner iterator"));
+ }
+ } else {
+ self.error = Some(anyhow::anyhow!("no key in valid inner iterator"));
+ }
+ }
+ }
+}
+
+impl<'store, S: Store> Iterator for ConfidentialStoreIterator<'store, S> {
+ type Item = (Vec<u8>, Vec<u8>);
+
+ fn next(&mut self) -> Option<Self::Item> {
+ self.reset_and_load();
+ if !mkvs::Iterator::is_valid(self) {
+ return None;
+ }
+ mkvs::Iterator::next(&mut *self.inner);
+ Some((self.key.clone().unwrap(), self.value.clone().unwrap()))
+ }
+}
+
+impl<'store, S: Store> mkvs::Iterator for ConfidentialStoreIterator<'store, S> {
+ fn set_prefetch(&mut self, prefetch: usize) {
+ self.inner.set_prefetch(prefetch)
+ }
+
+ fn is_valid(&self) -> bool {
+ self.error.is_none() && self.inner.is_valid()
+ }
+
+ fn error(&self) -> &Option<anyhow::Error> {
+ match self.error {
+ Some(_) => &self.error,
+ None => self.inner.error(),
+ }
+ }
+
+ fn rewind(&mut self) {
+ self.inner.rewind();
+ self.reset_and_load();
+ }
+
+ fn seek(&mut self, key: &[u8]) {
+ let (_, inner_key) = self.store.make_key(key);
+ self.inner.seek(&inner_key);
+ self.reset_and_load();
+ }
+
+ fn get_key(&self) -> &Option<mkvs::Key> {
+ &self.key
+ }
+
+ fn get_value(&self) -> &Option<Vec<u8>> {
+ &self.value
+ }
+
+ fn next(&mut self) {
+ mkvs::Iterator::next(&mut *self.inner);
+ self.reset_and_load();
+ }
+}
+
+#[cfg(test)]
+mod test {
+ extern crate test;
+ use super::*;
+ use crate::{keymanager::KeyPair, storage, testing::mock::empty_store};
+ use test::Bencher;
+
+ const ITEM_COUNT: usize = 10_000;
+
+ fn confidential<'ctx, S: Store + 'ctx>(inner: S, consistent: bool) -> Box<dyn Store + 'ctx> {
+ let state_key = if consistent {
+ [0xaau8; 32]
+ } else {
+ KeyPair::generate_mock().state_key.0
+ };
+ Box::new(ConfidentialStore::new_with_key(
+ inner,
+ state_key,
+ &[b"confidential store unit tests"],
+ ))
+ }
+
+ fn make_inner<'ctx, S: Store + 'ctx>(
+ store: S,
+ make_confidential: bool,
+ ) -> Box<dyn Store + 'ctx> {
+ let inner = storage::PrefixStore::new(
+ storage::PrefixStore::new(
+ storage::PrefixStore::new(store, "test module"),
+ "instance prefix",
+ ),
+ "type prefix",
+ );
+
+ // Replicate the stack as constructed in modules/contracts.
+ if make_confidential {
+ confidential(inner, false)
+ } else {
+ Box::new(storage::HashedStore::<_, blake3::Hasher>::new(inner))
+ }
+ }
+
+ fn make_items(mut num: usize) -> Vec<(Vec<u8>, Vec<u8>)> {
+ let mut items = Vec::new();
+ if num == 0 {
+ num = ITEM_COUNT;
+ }
+ for i in 0..num {
+ items.push((
+ format!("key{}", i).into_bytes(),
+ format!("value{}", i).into_bytes(),
+ ));
+ }
+ items
+ }
+
+ #[test]
+ fn basic_operations() {
+ let mut store = confidential(empty_store(), true);
+ let items = make_items(10);
+
+ // Nothing should exist at the beginning.
+ for (k, _) in items.iter() {
+ assert!(store.get(k).is_none());
+ }
+ let mut iter = store.iter();
+ iter.rewind();
+ assert!(iter.next().is_none());
+ drop(iter);
+
+ // Insert even items, then verify they're
+ // exactly the ones that exist.
+ for (k, v) in items.iter().step_by(2) {
+ store.insert(k, v);
+ }
+ for (i, (k, v)) in items.iter().enumerate() {
+ if i % 2 == 0 {
+ assert_eq!(&store.get(k).expect("item should exist"), v);
+ } else {
+ assert!(store.get(k).is_none());
+ }
+ }
+ let mut iter = store.iter();
+ iter.rewind();
+ assert_eq!(iter.count(), items.len() / 2);
+
+ // Remove some items that exist and some that don't.
+ // The stepper should remove key0 and key6, and also
+ // try removing key3 and key9.
+ for (k, _) in items.iter().step_by(3) {
+ store.remove(k);
+ }
+ for (i, (k, v)) in items.iter().enumerate() {
+ if i % 2 == 0 && i % 3 != 0 {
+ assert_eq!(&store.get(k).expect("item should exist"), v);
+ } else {
+ assert!(store.get(k).is_none());
+ }
+ }
+ let mut iter = store.iter();
+ iter.rewind();
+ assert_eq!(iter.count(), 3);
+ }
+
+ #[test]
+ fn base_corruption() {
+ let mut plain_store = empty_store();
+ let mut store = confidential(&mut plain_store, true);
+
+ // Insert something, try corrupting its bytes, then see
+ // what the confidential store does with it.
+ const KEY: &[u8] = b"key";
+ const VALUE: &[u8] = b"value";
+
+ // Insert the key and then try getting it out again, because we don't
+ // know the actual bytes in the underlying store.
+ store.insert(KEY, VALUE);
+ drop(store);
+ let mut iter = plain_store.iter();
+ iter.rewind();
+ let (key, value) = Iterator::next(&mut iter).expect("should have one item");
+ drop(iter);
+
+ // Actually encrypted?
+ let (_, enc_key) = unpack_nonce_slice(&key).expect("unpacking encrypted key should work");
+ assert_ne!(enc_key, b"key");
+
+ // Corrupt nonce part of the key.
+ let mut corrupt_key_nonce = key.clone();
+ corrupt_key_nonce[4] ^= 0xaau8;
+ plain_store.insert(&corrupt_key_nonce, &value);
+ plain_store.remove(&key);
+ let store = confidential(&mut plain_store, true);
+ assert!(store.get(KEY).is_none());
+ drop(store);
+ plain_store.remove(&corrupt_key_nonce);
+
+ // Corrupt key part of the key.
+ let mut corrupt_key_key = key.clone();
+ *corrupt_key_key.last_mut().unwrap() ^= 0xaau8;
+ plain_store.insert(&corrupt_key_key, &value);
+ let store = confidential(&mut plain_store, true);
+ assert!(store.get(KEY).is_none());
+ drop(store);
+ plain_store.remove(&corrupt_key_key);
+
+ // Validate inserting into underlying store.
+ plain_store.insert(&key, &value);
+ let store = confidential(&mut plain_store, true);
+ assert_eq!(store.get(KEY).expect("key should exist"), VALUE);
+ }
+
+ #[test]
+ #[should_panic]
+ fn corruption_value_nonce() {
+ let mut plain_store = empty_store();
+ let mut store = confidential(&mut plain_store, true);
+
+ // Insert something, try corrupting its bytes, then see
+ // what the confidential store does with it.
+ const KEY: &[u8] = b"key";
+ const VALUE: &[u8] = b"value";
+
+ // Insert the key and then try getting it out again, because we don't
+ // know the actual bytes in the underlying store.
+ store.insert(KEY, VALUE);
+ assert!(store.get(KEY).is_some());
+ drop(store);
+ let mut iter = plain_store.iter();
+ iter.rewind();
+ let (key, value) = Iterator::next(&mut iter).expect("should have one item");
+ drop(iter);
+
+ // Corrupt the nonce part of the value.
+ let mut corrupt_value_nonce = value;
+ corrupt_value_nonce[4] ^= 0xaau8;
+ plain_store.remove(&key);
+ plain_store.insert(&key, &corrupt_value_nonce);
+ let store = confidential(&mut plain_store, true);
+ store.get(KEY);
+ drop(store);
+ plain_store.remove(&key);
+ }
+
+ #[test]
+ #[should_panic]
+ fn corruption_value_value() {
+ let mut plain_store = empty_store();
+ let mut store = confidential(&mut plain_store, true);
+
+ // Insert something, try corrupting its bytes, then see
+ // what the confidential store does with it.
+ const KEY: &[u8] = b"key";
+ const VALUE: &[u8] = b"value";
+
+ // Insert the key and then try getting it out again, because we don't
+ // know the actual bytes in the underlying store.
+ store.insert(KEY, VALUE);
+ assert!(store.get(KEY).is_some());
+ drop(store);
+ let mut iter = plain_store.iter();
+ iter.rewind();
+ let (key, value) = Iterator::next(&mut iter).expect("should have one item");
+ drop(iter);
+
+ // Corrupt the nonce part of the value.
+ let mut corrupt_value_value = value;
+ *corrupt_value_value.last_mut().unwrap() ^= 0xaau8;
+ plain_store.remove(&key);
+ plain_store.insert(&key, &corrupt_value_value);
+ let store = confidential(&mut plain_store, true);
+ store.get(KEY);
+ drop(store);
+ plain_store.remove(&key);
+ }
+
+ fn run<F>(confidential: bool, inserts: usize, mut cb: F)
+ where
+ F: FnMut(&mut Box<dyn Store + '_>, &Vec<(Vec<u8>, Vec<u8>)>),
+ {
+ let mut store = make_inner(empty_store(), confidential);
+
+ let items = make_items(0);
+ for i in 0..inserts {
+ let item = &items[i % items.len()];
+ store.insert(&item.0, &item.1);
+ }
+
+ cb(&mut store, &items);
+ }
+
+ #[bench]
+ fn plain_insert(b: &mut Bencher) {
+ run(false, 0, |store, items| {
+ let mut i = 0;
+ b.iter(|| {
+ let item = &items[i % items.len()];
+ store.insert(&item.0, &item.1);
+ i += 1;
+ });
+ });
+ }
+
+ #[bench]
+ fn plain_get(b: &mut Bencher) {
+ run(false, ITEM_COUNT / 2, |store, items| {
+ let mut i = 0;
+ b.iter(|| {
+ let j =
+ (2 * i + ((items.len() + 1) % 2) * ((i / (items.len() / 2)) % 2)) % items.len();
+ let item = &items[j % items.len()];
+ store.get(&item.0);
+ i += 1;
+ });
+ });
+ }
+
+ #[bench]
+ fn plain_scan(b: &mut Bencher) {
+ run(false, ITEM_COUNT, |store, _| {
+ let mut it = store.iter();
+ b.iter(|| {
+ match it.next() {
+ Some(_) => {}
+ None => {
+ it = store.iter();
+ }
+ };
+ });
+ });
+ }
+
+ #[bench]
+ fn confidential_insert(b: &mut Bencher) {
+ run(true, 0, |store, items| {
+ let mut i = 0;
+ b.iter(|| {
+ let item = &items[i % items.len()];
+ store.insert(&item.0, &item.1);
+ i += 1;
+ });
+ });
+ }
+
+ #[bench]
+ fn confidential_get(b: &mut Bencher) {
+ run(true, ITEM_COUNT / 2, |store, items| {
+ let mut i = 0;
+ b.iter(|| {
+ let j =
+ (2 * i + ((items.len() + 1) % 2) * ((i / (items.len() / 2)) % 2)) % items.len();
+ let item = &items[j % items.len()];
+ store.get(&item.0);
+ i += 1;
+ });
+ });
+ }
+
+ #[bench]
+ fn confidential_scan(b: &mut Bencher) {
+ run(true, ITEM_COUNT, |store, _| {
+ let mut it = store.iter();
+ b.iter(|| {
+ match it.next() {
+ Some(_) => {}
+ None => {
+ it = store.iter();
+ }
+ };
+ });
+ });
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +
use std::marker::PhantomData;
+
+use oasis_core_runtime::storage::mkvs;
+
+use super::Store;
+
+/// A key-value store that hashes all keys and stores them as `H(k) || k`.
+pub struct HashedStore<S: Store, D: digest::Digest> {
+ parent: S,
+ _digest: PhantomData<D>,
+}
+
+impl<S: Store, D: digest::Digest> HashedStore<S, D> {
+ /// Create a new hashed store.
+ pub fn new(parent: S) -> Self {
+ Self {
+ parent,
+ _digest: PhantomData,
+ }
+ }
+}
+
+impl<S: Store, D: digest::Digest> Store for HashedStore<S, D> {
+ fn get(&self, key: &[u8]) -> Option<Vec<u8>> {
+ self.parent.get(&[&D::digest(key), key].concat())
+ }
+
+ fn insert(&mut self, key: &[u8], value: &[u8]) {
+ self.parent.insert(&[&D::digest(key), key].concat(), value);
+ }
+
+ fn remove(&mut self, key: &[u8]) {
+ self.parent.remove(&[&D::digest(key), key].concat());
+ }
+
+ fn iter(&self) -> Box<dyn mkvs::Iterator + '_> {
+ self.parent.iter()
+ }
+
+ fn prefetch_prefixes(&mut self, prefixes: Vec<mkvs::Prefix>, limit: u16) {
+ self.parent.prefetch_prefixes(prefixes, limit);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +
use std::sync::Arc;
+
+use anyhow::{anyhow, Result};
+
+use crate::{
+ core::{
+ common::namespace::Namespace,
+ consensus::{state::roothash::ImmutableState as RoothashState, verifier::Verifier},
+ protocol::Protocol,
+ storage::mkvs,
+ types::HostStorageEndpoint,
+ },
+ storage,
+};
+
+/// A store for a specific state root that talks to the runtime host.
+pub struct HostStore {
+ tree: mkvs::Tree,
+}
+
+impl HostStore {
+ /// Create a new host store for the given host and root.
+ pub fn new(host: Arc<Protocol>, root: mkvs::Root) -> Self {
+ let read_syncer = mkvs::sync::HostReadSyncer::new(host, HostStorageEndpoint::Runtime);
+ let tree = mkvs::Tree::builder()
+ .with_capacity(10_000, 1024 * 1024)
+ .with_root(root)
+ .build(Box::new(read_syncer));
+
+ Self { tree }
+ }
+
+ /// Create a new host store for the given host and root at the given round.
+ ///
+ /// The corresponding root hash is fetched by looking it up in consensus layer state, verified
+ /// by the passed verifier to be correct.
+ pub async fn new_for_round(
+ host: Arc<Protocol>,
+ consensus_verifier: &Arc<dyn Verifier>,
+ id: Namespace,
+ round: u64,
+ ) -> Result<Self> {
+ // Fetch latest consensus layer state.
+ let state = consensus_verifier.latest_state().await?;
+ // Fetch latest state root for the given namespace.
+ let roots = tokio::task::spawn_blocking(move || {
+ let roothash = RoothashState::new(&state);
+ roothash.round_roots(id, round)
+ })
+ .await??
+ .ok_or(anyhow!("root not found"))?;
+
+ Ok(Self::new(
+ host,
+ mkvs::Root {
+ namespace: id,
+ version: round,
+ root_type: mkvs::RootType::State,
+ hash: roots.state_root,
+ },
+ ))
+ }
+}
+
+impl storage::Store for HostStore {
+ fn get(&self, key: &[u8]) -> Option<Vec<u8>> {
+ self.tree.get(key).unwrap()
+ }
+
+ fn insert(&mut self, key: &[u8], value: &[u8]) {
+ self.tree.insert(key, value).unwrap();
+ }
+
+ fn remove(&mut self, key: &[u8]) {
+ self.tree.remove(key).unwrap();
+ }
+
+ fn iter(&self) -> Box<dyn mkvs::Iterator + '_> {
+ Box::new(self.tree.iter())
+ }
+
+ fn prefetch_prefixes(&mut self, prefixes: Vec<mkvs::Prefix>, limit: u16) {
+ self.tree.prefetch_prefixes(&prefixes, limit).unwrap();
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +
use oasis_core_runtime::storage::mkvs;
+
+use super::{NestedStore, Store};
+
+/// A key-value store backed by MKVS.
+pub struct MKVSStore<M: mkvs::MKVS> {
+ parent: M,
+}
+
+impl<M: mkvs::MKVS> MKVSStore<M> {
+ pub fn new(parent: M) -> Self {
+ Self { parent }
+ }
+}
+
+impl<M: mkvs::MKVS> Store for MKVSStore<M> {
+ fn get(&self, key: &[u8]) -> Option<Vec<u8>> {
+ self.parent.get(key)
+ }
+
+ fn insert(&mut self, key: &[u8], value: &[u8]) {
+ self.parent.insert(key, value);
+ }
+
+ fn remove(&mut self, key: &[u8]) {
+ self.parent.remove(key);
+ }
+
+ fn iter(&self) -> Box<dyn mkvs::Iterator + '_> {
+ self.parent.iter()
+ }
+
+ fn prefetch_prefixes(&mut self, prefixes: Vec<mkvs::Prefix>, limit: u16) {
+ self.parent.prefetch_prefixes(&prefixes, limit);
+ }
+}
+
+impl<M: mkvs::MKVS> NestedStore for MKVSStore<M> {
+ type Inner = M;
+
+ fn commit(self) -> Self::Inner {
+ // Commit is not needed.
+ self.parent
+ }
+
+ fn rollback(self) -> Self::Inner {
+ panic!("attempted to rollback a non-transactional store");
+ }
+
+ fn has_pending_updates(&self) -> bool {
+ true
+ }
+
+ fn pending_update_byte_size(&self) -> usize {
+ 0
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +
//! Storage.
+use oasis_core_runtime::storage::mkvs::Iterator;
+
+pub mod confidential;
+mod hashed;
+mod host;
+mod mkvs;
+mod overlay;
+mod prefix;
+mod typed;
+
+/// A key-value store.
+pub trait Store {
+ /// Fetch entry with given key.
+ fn get(&self, key: &[u8]) -> Option<Vec<u8>>;
+
+ /// Update entry with given key to the given value.
+ fn insert(&mut self, key: &[u8], value: &[u8]);
+
+ /// Remove entry with given key.
+ fn remove(&mut self, key: &[u8]);
+
+ /// Returns an iterator over the tree.
+ fn iter(&self) -> Box<dyn Iterator + '_>;
+
+ /// Populate the in-memory tree with nodes for keys starting with given prefixes.
+ fn prefetch_prefixes(&mut self, prefixes: Vec<Prefix>, limit: u16);
+}
+
+/// A key-value store that supports the commit operation.
+pub trait NestedStore: Store {
+ /// Type of the inner store.
+ type Inner;
+
+ /// Commit any changes to the underlying store.
+ ///
+ /// If this method is not called the changes may be discarded by the store.
+ fn commit(self) -> Self::Inner;
+
+ /// Rollback any changes.
+ fn rollback(self) -> Self::Inner;
+
+ /// Whether there are any store updates pending to be committed.
+ fn has_pending_updates(&self) -> bool;
+
+ /// Size (in bytes) of any pending updates.
+ fn pending_update_byte_size(&self) -> usize;
+}
+
+impl<S: Store + ?Sized> Store for &mut S {
+ fn get(&self, key: &[u8]) -> Option<Vec<u8>> {
+ S::get(self, key)
+ }
+
+ fn insert(&mut self, key: &[u8], value: &[u8]) {
+ S::insert(self, key, value)
+ }
+
+ fn remove(&mut self, key: &[u8]) {
+ S::remove(self, key)
+ }
+
+ fn iter(&self) -> Box<dyn Iterator + '_> {
+ S::iter(self)
+ }
+
+ fn prefetch_prefixes(&mut self, prefixes: Vec<Prefix>, limit: u16) {
+ S::prefetch_prefixes(self, prefixes, limit)
+ }
+}
+
+impl<S: Store + ?Sized> Store for Box<S> {
+ fn get(&self, key: &[u8]) -> Option<Vec<u8>> {
+ S::get(self, key)
+ }
+
+ fn insert(&mut self, key: &[u8], value: &[u8]) {
+ S::insert(self, key, value)
+ }
+
+ fn remove(&mut self, key: &[u8]) {
+ S::remove(self, key)
+ }
+
+ fn iter(&self) -> Box<dyn Iterator + '_> {
+ S::iter(self)
+ }
+
+ fn prefetch_prefixes(&mut self, prefixes: Vec<Prefix>, limit: u16) {
+ S::prefetch_prefixes(self, prefixes, limit)
+ }
+}
+
+pub use confidential::{ConfidentialStore, Error as ConfidentialStoreError};
+pub use hashed::HashedStore;
+pub use host::HostStore;
+pub use mkvs::MKVSStore;
+pub use overlay::OverlayStore;
+pub use prefix::PrefixStore;
+pub use typed::TypedStore;
+
+// Re-export the mkvs storage prefix.
+pub use oasis_core_runtime::storage::mkvs::Prefix;
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +
use std::{
+ collections::{btree_map, BTreeMap, HashSet},
+ iter::{Iterator, Peekable},
+};
+
+use oasis_core_runtime::storage::mkvs;
+
+use super::{NestedStore, Prefix, Store};
+
+/// An overlay store which keeps values locally until explicitly committed.
+pub struct OverlayStore<S: Store> {
+ parent: S,
+ overlay: BTreeMap<Vec<u8>, Vec<u8>>,
+ dirty: HashSet<Vec<u8>>,
+}
+
+impl<S: Store> OverlayStore<S> {
+ /// Create a new overlay store.
+ pub fn new(parent: S) -> Self {
+ Self {
+ parent,
+ overlay: BTreeMap::new(),
+ dirty: HashSet::new(),
+ }
+ }
+}
+
+impl<S: Store> NestedStore for OverlayStore<S> {
+ type Inner = S;
+
+ fn commit(mut self) -> Self::Inner {
+ // Insert all items present in the overlay.
+ for (key, value) in self.overlay {
+ self.dirty.remove(&key);
+ self.parent.insert(&key, &value);
+ }
+
+ // Any remaining dirty items must have been removed.
+ for key in self.dirty {
+ self.parent.remove(&key);
+ }
+
+ self.parent
+ }
+
+ fn rollback(self) -> Self::Inner {
+ self.parent
+ }
+
+ fn has_pending_updates(&self) -> bool {
+ !self.dirty.is_empty()
+ }
+
+ fn pending_update_byte_size(&self) -> usize {
+ let updated_size = self
+ .overlay
+ .iter()
+ .map(|(key, value)| key.len() + value.len())
+ .reduce(|acc, bytes| acc + bytes)
+ .unwrap_or_default();
+
+ let removed_size = self
+ .dirty
+ .iter()
+ .filter(|key| !self.overlay.contains_key(key.as_slice()))
+ .map(|key| key.len())
+ .reduce(|acc, bytes| acc + bytes)
+ .unwrap_or_default();
+
+ updated_size.saturating_add(removed_size)
+ }
+}
+
+impl<S: Store> Store for OverlayStore<S> {
+ fn get(&self, key: &[u8]) -> Option<Vec<u8>> {
+ // For dirty values, check the overlay.
+ if self.dirty.contains(key) {
+ return self.overlay.get(key).cloned();
+ }
+
+ // Otherwise fetch from parent store.
+ self.parent.get(key)
+ }
+
+ fn insert(&mut self, key: &[u8], value: &[u8]) {
+ self.overlay.insert(key.to_owned(), value.to_owned());
+ self.dirty.insert(key.to_owned());
+ }
+
+ fn remove(&mut self, key: &[u8]) {
+ // For dirty values, remove from the overlay.
+ if self.dirty.contains(key) {
+ self.overlay.remove(key);
+ return;
+ }
+
+ // Since we don't care about the previous value, we can just record an update.
+ self.dirty.insert(key.to_owned());
+ }
+
+ fn iter(&self) -> Box<dyn mkvs::Iterator + '_> {
+ Box::new(OverlayStoreIterator::new(self))
+ }
+
+ fn prefetch_prefixes(&mut self, prefixes: Vec<Prefix>, limit: u16) {
+ self.parent.prefetch_prefixes(prefixes, limit);
+ }
+}
+
+/// An iterator over the `OverlayStore`.
+pub(crate) struct OverlayStoreIterator<'store, S: Store> {
+ store: &'store OverlayStore<S>,
+
+ parent: Box<dyn mkvs::Iterator + 'store>,
+
+ overlay: Peekable<btree_map::Range<'store, Vec<u8>, Vec<u8>>>,
+ overlay_valid: bool,
+
+ key: Option<Vec<u8>>,
+ value: Option<Vec<u8>>,
+}
+
+impl<'store, S: Store> OverlayStoreIterator<'store, S> {
+ fn new(store: &'store OverlayStore<S>) -> Self {
+ Self {
+ store,
+ parent: store.parent.iter(),
+ overlay: store.overlay.range(vec![]..).peekable(),
+ overlay_valid: true,
+ key: None,
+ value: None,
+ }
+ }
+
+ fn update_iterator_position(&mut self) {
+ // Skip over any dirty entries from the parent iterator.
+ loop {
+ if !self.parent.is_valid()
+ || !self
+ .store
+ .dirty
+ .contains(self.parent.get_key().as_ref().expect("parent.is_valid"))
+ {
+ break;
+ }
+ self.parent.next();
+ }
+
+ let i_key = self.parent.get_key();
+ let o_item = self.overlay.peek();
+ self.overlay_valid = o_item.is_some();
+
+ if self.parent.is_valid()
+ && (!self.overlay_valid
+ || i_key.as_ref().expect("parent.is_valid") < o_item.expect("overlay_valid").0)
+ {
+ // Key of parent iterator is smaller than the key of the overlay iterator.
+ self.key = i_key.clone();
+ self.value = self.parent.get_value().clone();
+ } else if self.overlay_valid {
+ // Key of overlay iterator is smaller than or equal to the key of the parent iterator.
+ let (o_key, o_value) = o_item.expect("overlay_valid");
+ self.key = Some(o_key.to_vec());
+ self.value = Some(o_value.to_vec());
+ } else {
+ // Both iterators are invalid.
+ self.key = None;
+ self.value = None;
+ }
+ }
+
+ fn next(&mut self) {
+ if !self.overlay_valid
+ || (self.parent.is_valid()
+ && self.parent.get_key().as_ref().expect("parent.is_valid")
+ <= self.overlay.peek().expect("overlay_valid").0)
+ {
+ // Key of parent iterator is smaller or equal than the key of the overlay iterator.
+ self.parent.next();
+ } else {
+ // Key of parent iterator is greater than the key of the overlay iterator.
+ self.overlay.next();
+ }
+
+ self.update_iterator_position();
+ }
+}
+
+impl<'store, S: Store> Iterator for OverlayStoreIterator<'store, S> {
+ type Item = (Vec<u8>, Vec<u8>);
+
+ fn next(&mut self) -> Option<Self::Item> {
+ use mkvs::Iterator;
+
+ if !self.is_valid() {
+ return None;
+ }
+
+ let key = self.key.as_ref().expect("iterator is valid").clone();
+ let value = self.value.as_ref().expect("iterator is valid").clone();
+ OverlayStoreIterator::next(self);
+
+ Some((key, value))
+ }
+}
+
+impl<'store, S: Store> mkvs::Iterator for OverlayStoreIterator<'store, S> {
+ fn set_prefetch(&mut self, prefetch: usize) {
+ self.parent.set_prefetch(prefetch)
+ }
+
+ fn is_valid(&self) -> bool {
+ // If either iterator is valid, the merged iterator is valid.
+ self.parent.is_valid() || self.overlay_valid
+ }
+
+ fn error(&self) -> &Option<anyhow::Error> {
+ self.parent.error()
+ }
+
+ fn rewind(&mut self) {
+ self.seek(&[]);
+ }
+
+ fn seek(&mut self, key: &[u8]) {
+ self.parent.seek(key);
+ self.overlay = self.store.overlay.range(key.to_vec()..).peekable();
+
+ self.update_iterator_position();
+ }
+
+ fn get_key(&self) -> &Option<mkvs::Key> {
+ &self.key
+ }
+
+ fn get_value(&self) -> &Option<Vec<u8>> {
+ &self.value
+ }
+
+ fn next(&mut self) {
+ OverlayStoreIterator::next(self)
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +
use oasis_core_runtime::storage::mkvs;
+
+use super::{Prefix, Store};
+
+/// A key-value store that prefixes all keys with the given prefix.
+pub struct PrefixStore<S: Store, P: AsRef<[u8]>> {
+ parent: S,
+ prefix: P,
+}
+
+impl<S: Store, P: AsRef<[u8]>> PrefixStore<S, P> {
+ /// Create a new prefix store with the given prefix.
+ pub fn new(parent: S, prefix: P) -> Self {
+ Self { parent, prefix }
+ }
+}
+
+impl<S: Store, P: AsRef<[u8]>> Store for PrefixStore<S, P> {
+ fn get(&self, key: &[u8]) -> Option<Vec<u8>> {
+ self.parent.get(&[self.prefix.as_ref(), key].concat())
+ }
+
+ fn insert(&mut self, key: &[u8], value: &[u8]) {
+ self.parent
+ .insert(&[self.prefix.as_ref(), key].concat(), value);
+ }
+
+ fn remove(&mut self, key: &[u8]) {
+ self.parent.remove(&[self.prefix.as_ref(), key].concat());
+ }
+
+ fn iter(&self) -> Box<dyn mkvs::Iterator + '_> {
+ Box::new(PrefixStoreIterator::new(
+ self.parent.iter(),
+ self.prefix.as_ref(),
+ ))
+ }
+
+ fn prefetch_prefixes(&mut self, prefixes: Vec<Prefix>, limit: u16) {
+ self.parent.prefetch_prefixes(prefixes, limit);
+ }
+}
+
+/// An iterator over the `PrefixStore`.
+pub(crate) struct PrefixStoreIterator<'store> {
+ inner: Box<dyn mkvs::Iterator + 'store>,
+ prefix: &'store [u8],
+}
+
+impl<'store> PrefixStoreIterator<'store> {
+ fn new(mut inner: Box<dyn mkvs::Iterator + 'store>, prefix: &'store [u8]) -> Self {
+ inner.seek(prefix);
+ Self { inner, prefix }
+ }
+}
+
+impl<'store> Iterator for PrefixStoreIterator<'store> {
+ type Item = (Vec<u8>, Vec<u8>);
+
+ fn next(&mut self) -> Option<Self::Item> {
+ Iterator::next(&mut self.inner).and_then(|(mut k, v)| {
+ if k.starts_with(self.prefix) {
+ Some((k.split_off(self.prefix.len()), v))
+ } else {
+ None
+ }
+ })
+ }
+}
+
+impl<'store> mkvs::Iterator for PrefixStoreIterator<'store> {
+ fn set_prefetch(&mut self, prefetch: usize) {
+ self.inner.set_prefetch(prefetch)
+ }
+
+ fn is_valid(&self) -> bool {
+ if !self
+ .inner
+ .get_key()
+ .as_ref()
+ .unwrap_or(&vec![])
+ .starts_with(self.prefix)
+ {
+ return false;
+ }
+ self.inner.is_valid()
+ }
+
+ fn error(&self) -> &Option<anyhow::Error> {
+ self.inner.error()
+ }
+
+ fn rewind(&mut self) {
+ self.inner.seek(self.prefix);
+ }
+
+ fn seek(&mut self, key: &[u8]) {
+ self.inner.seek(&[self.prefix, key].concat());
+ }
+
+ fn get_key(&self) -> &Option<mkvs::Key> {
+ self.inner.get_key()
+ }
+
+ fn get_value(&self) -> &Option<Vec<u8>> {
+ self.inner.get_value()
+ }
+
+ fn next(&mut self) {
+ if !self.is_valid() {
+ // Could be invalid due to prefix mismatch.
+ return;
+ }
+ mkvs::Iterator::next(&mut *self.inner)
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +
use std::{convert::TryFrom, marker::PhantomData};
+
+use oasis_core_runtime::storage::mkvs;
+
+use super::Store;
+
+/// A key-value store that transparently handles serialization/deserialization.
+pub struct TypedStore<S: Store> {
+ parent: S,
+}
+
+impl<S: Store> TypedStore<S> {
+ /// Create a new typed store.
+ pub fn new(parent: S) -> Self {
+ Self { parent }
+ }
+
+ /// Fetch entry with given key.
+ pub fn get<K: AsRef<[u8]>, T: cbor::Decode>(&self, key: K) -> Option<T> {
+ self.parent
+ .get(key.as_ref())
+ .map(|data| cbor::from_slice(&data).unwrap())
+ }
+
+ /// Update entry with given key to the given value.
+ pub fn insert<K: AsRef<[u8]>, T: cbor::Encode>(&mut self, key: K, value: T) {
+ self.parent.insert(key.as_ref(), &cbor::to_vec(value))
+ }
+
+ /// Remove entry with given key.
+ pub fn remove<K: AsRef<[u8]>>(&mut self, key: K) {
+ self.parent.remove(key.as_ref())
+ }
+
+ pub fn iter<'store, K, V>(&'store self) -> TypedStoreIterator<'store, K, V>
+ where
+ K: for<'k> TryFrom<&'k [u8]>,
+ V: cbor::Decode + Default,
+ {
+ TypedStoreIterator::new(self.parent.iter())
+ }
+}
+
+/// An iterator over the `TypedStore`.
+pub struct TypedStoreIterator<'store, K, V>
+where
+ K: for<'k> TryFrom<&'k [u8]>,
+ V: Default + cbor::Decode,
+{
+ inner: Box<dyn mkvs::Iterator + 'store>,
+
+ _key: PhantomData<K>,
+ _value: PhantomData<V>,
+}
+
+impl<'store, K, V> TypedStoreIterator<'store, K, V>
+where
+ K: for<'k> TryFrom<&'k [u8]>,
+ V: cbor::Decode + Default,
+{
+ fn new(inner: Box<dyn mkvs::Iterator + 'store>) -> Self {
+ Self {
+ inner,
+ _key: PhantomData,
+ _value: PhantomData,
+ }
+ }
+}
+
+impl<'store, K, V, E> Iterator for TypedStoreIterator<'store, K, V>
+where
+ K: for<'k> TryFrom<&'k [u8], Error = E>,
+ E: std::fmt::Display,
+ V: cbor::Decode + Default,
+{
+ type Item = (K, V);
+
+ fn next(&mut self) -> Option<Self::Item> {
+ Iterator::next(&mut self.inner).map(|(k, v)| {
+ let key = K::try_from(&k).unwrap_or_else(|e| panic!("corrupted storage key: {e}"));
+ let value = if v.is_empty() {
+ // Ignore empty values as those would fail CBOR decoding.
+ Default::default()
+ } else {
+ cbor::from_slice(&v).unwrap()
+ };
+ (key, value)
+ })
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +
//! Subcall dispatch.
+use std::cell::RefCell;
+
+use crate::{
+ context::Context,
+ dispatcher,
+ module::CallResult,
+ modules::core::{Error, API as _},
+ runtime::Runtime,
+ state::{CurrentState, Options, TransactionResult, TransactionWithMeta},
+ types::{token, transaction, transaction::CallerAddress},
+};
+
+thread_local! {
+ /// The subcall stack for tracking depth and other metadata.
+ static SUBCALL_STACK: RefCell<SubcallStack> = RefCell::new(SubcallStack::new());
+}
+
+/// Subcall validator.
+pub trait Validator {
+ /// Validate a subcall before it is performed.
+ fn validate(&self, info: &SubcallInfo) -> Result<(), Error>;
+}
+
+/// A validator which allows everything.
+pub struct AllowAllValidator;
+
+impl Validator for AllowAllValidator {
+ fn validate(&self, _info: &SubcallInfo) -> Result<(), Error> {
+ Ok(())
+ }
+}
+
+/// Information about a subcall to be dispatched.
+#[derive(Clone, Debug)]
+pub struct SubcallInfo {
+ /// Address of the caller.
+ pub caller: CallerAddress,
+ /// Method to call.
+ pub method: String,
+ /// Subcall body.
+ pub body: cbor::Value,
+ /// Maximum subcall depth.
+ pub max_depth: u16,
+ /// Maximum gas amount that can be consumed.
+ pub max_gas: u64,
+}
+
+/// Result of dispatching a subcall.
+#[derive(Debug)]
+pub struct SubcallResult {
+ /// Result of the subcall.
+ pub call_result: CallResult,
+ /// Gas used by the subcall.
+ pub gas_used: u64,
+}
+
+struct SubcallStackEntry {
+ validator: Box<dyn Validator>,
+}
+
+struct SubcallStack {
+ stack: Vec<SubcallStackEntry>,
+}
+
+impl SubcallStack {
+ fn new() -> Self {
+ Self { stack: Vec::new() }
+ }
+
+ fn depth(&self) -> u16 {
+ self.stack.len() as u16
+ }
+
+ fn push(&mut self, entry: SubcallStackEntry) {
+ self.stack.push(entry);
+ }
+
+ fn pop(&mut self) {
+ self.stack.pop();
+ }
+
+ fn run_validators(&self, info: &SubcallInfo) -> Result<(), Error> {
+ for entry in &self.stack {
+ entry.validator.validate(info)?;
+ }
+ Ok(())
+ }
+}
+
+struct SubcallStackGuard;
+
+impl Drop for SubcallStackGuard {
+ fn drop(&mut self) {
+ SUBCALL_STACK.with(|ss| {
+ ss.borrow_mut().pop();
+ });
+ }
+}
+
+/// The current subcall depth.
+pub fn get_current_subcall_depth<C: Context>(_ctx: &C) -> u16 {
+ SUBCALL_STACK.with(|ss| ss.borrow().depth())
+}
+
+/// Perform a subcall.
+pub fn call<C: Context, V: Validator + 'static>(
+ ctx: &C,
+ info: SubcallInfo,
+ validator: V,
+) -> Result<SubcallResult, Error> {
+ // Run validator first.
+ validator.validate(&info)?;
+
+ // Update the subcall stack after doing validation.
+ SUBCALL_STACK.with(|ss| {
+ let mut stack = ss.borrow_mut();
+
+ // Ensure the call depth is not too large.
+ if stack.depth() >= info.max_depth {
+ return Err(Error::CallDepthExceeded(stack.depth() + 1, info.max_depth));
+ }
+
+ // Run existing validators.
+ stack.run_validators(&info)?;
+
+ // Push subcall to stack.
+ stack.push(SubcallStackEntry {
+ validator: Box::new(validator) as Box<dyn Validator>,
+ });
+
+ Ok(())
+ })?;
+ let _guard = SubcallStackGuard; // Ensure subcall is popped from stack.
+
+ // Generate an internal transaction.
+ let tx = transaction::Transaction {
+ version: transaction::LATEST_TRANSACTION_VERSION,
+ call: transaction::Call {
+ format: transaction::CallFormat::Plain,
+ method: info.method,
+ body: info.body,
+ ..Default::default()
+ },
+ auth_info: transaction::AuthInfo {
+ signer_info: vec![transaction::SignerInfo {
+ // The call is being performed on the caller's behalf.
+ address_spec: transaction::AddressSpec::Internal(info.caller),
+ nonce: 0,
+ }],
+ fee: transaction::Fee {
+ amount: token::BaseUnits::new(0, token::Denomination::NATIVE),
+ // Limit gas usage inside the child context to the allocated maximum.
+ gas: info.max_gas,
+ // Propagate consensus message limit.
+ consensus_messages: CurrentState::with(|state| state.emitted_messages_max(ctx)),
+ proxy: None,
+ },
+ ..Default::default()
+ },
+ };
+ let call = tx.call.clone(); // TODO: Avoid clone.
+
+ // Execute a transaction in a child context.
+ let (call_result, gas) = CurrentState::with_transaction_opts(
+ Options::new()
+ .with_internal(true)
+ .with_tx(TransactionWithMeta::internal(tx)),
+ || {
+ // Dispatch the call.
+ let (result, _) = dispatcher::Dispatcher::<C::Runtime>::dispatch_tx_call(
+ &ctx.clone(), // Must clone to avoid infinite type.
+ call,
+ &Default::default(),
+ );
+ // Retrieve remaining gas.
+ let gas = <C::Runtime as Runtime>::Core::remaining_tx_gas();
+
+ // Commit store and return emitted tags and messages on successful dispatch,
+ // otherwise revert state and ignore any emitted events/messages.
+ if result.is_success() {
+ TransactionResult::Commit((result, gas))
+ } else {
+ // Ignore tags/messages on failure.
+ TransactionResult::Rollback((result, gas))
+ }
+ },
+ );
+
+ // Compute the amount of gas used.
+ let gas_used = info.max_gas.saturating_sub(gas);
+
+ Ok(SubcallResult {
+ call_result,
+ gas_used,
+ })
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +
//! Mock key manager implementation.
+
+use std::{collections::HashMap, sync::Mutex};
+
+pub use crate::keymanager::{
+ KeyManagerError, KeyPair, KeyPairId, SignedPublicKey, StateKey, TrustedSigners,
+};
+use crate::{
+ core::{
+ common::{crypto::signature::PublicKey, namespace::Namespace},
+ consensus::beacon::EpochTime,
+ },
+ keymanager::KeyManager,
+};
+
+#[derive(Default)]
+pub struct MockKeyManagerClient {
+ keys: Mutex<HashMap<KeyPairId, KeyPair>>,
+ ephemeral_keys: Mutex<HashMap<KeyPairId, KeyPair>>,
+}
+
+impl Clone for MockKeyManagerClient {
+ fn clone(&self) -> Self {
+ let keys = self.keys.lock().unwrap();
+ let ephemeral_keys = self.ephemeral_keys.lock().unwrap();
+ Self {
+ keys: Mutex::new(keys.clone()),
+ ephemeral_keys: Mutex::new(ephemeral_keys.clone()),
+ }
+ }
+}
+
+impl MockKeyManagerClient {
+ pub fn new() -> Self {
+ Default::default()
+ }
+}
+
+impl KeyManager for MockKeyManagerClient {
+ fn runtime_id(&self) -> Option<Namespace> {
+ None
+ }
+
+ fn runtime_signing_key(&self) -> Option<PublicKey> {
+ None
+ }
+
+ fn clear_cache(&self) {
+ // Nothing to do here, no cache.
+ }
+
+ fn get_or_create_keys(&self, key_pair_id: KeyPairId) -> Result<KeyPair, KeyManagerError> {
+ let mut keys = self.keys.lock().unwrap();
+ Ok(keys
+ .entry(key_pair_id)
+ .or_insert_with(|| {
+ let mut kp = KeyPair::generate_mock();
+ kp.state_key.0.fill(0x33);
+ kp
+ })
+ .clone())
+ }
+
+ fn get_public_key(&self, _key_pair_id: KeyPairId) -> Result<SignedPublicKey, KeyManagerError> {
+ Err(KeyManagerError::NotInitialized)
+ }
+
+ fn get_or_create_ephemeral_keys(
+ &self,
+ key_pair_id: KeyPairId,
+ _epoch: EpochTime,
+ ) -> Result<KeyPair, KeyManagerError> {
+ let mut ephemeral_keys = self.ephemeral_keys.lock().unwrap();
+ Ok(ephemeral_keys
+ .entry(key_pair_id)
+ .or_insert_with(|| {
+ let mut kp = KeyPair::generate_mock();
+ kp.state_key.0.fill(0x33);
+ kp
+ })
+ .clone())
+ }
+
+ fn get_public_ephemeral_key(
+ &self,
+ _key_pair_id: KeyPairId,
+ _epoch: EpochTime,
+ ) -> Result<SignedPublicKey, KeyManagerError> {
+ Err(KeyManagerError::NotInitialized)
+ }
+
+ fn box_clone(&self) -> Box<dyn KeyManager> {
+ Box::new(self.clone())
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +
//! Module that contains known test keys.
+
+// TODO: Should be derived from seeds once implemented in the Rust version.
+
+/// Define an ed25519 test key.
+macro_rules! test_key_ed25519 {
+ ($doc:expr, $name:ident, $pk:expr) => {
+ #[doc = " Test key "]
+ #[doc=$doc]
+ #[doc = "."]
+ pub mod $name {
+ use crate::{
+ crypto::signature::{ed25519, PublicKey},
+ types::address::{Address, SignatureAddressSpec},
+ };
+
+ #[doc = " Test public key "]
+ #[doc=$doc]
+ #[doc = "."]
+ pub fn pk() -> PublicKey {
+ PublicKey::Ed25519(pk_ed25519())
+ }
+
+ #[doc = " Test Ed25519 public key "]
+ #[doc=$doc]
+ #[doc = "."]
+ pub fn pk_ed25519() -> ed25519::PublicKey {
+ $pk.into()
+ }
+
+ #[doc = " Test address derivation information "]
+ #[doc=$doc]
+ #[doc = "."]
+ pub fn sigspec() -> SignatureAddressSpec {
+ SignatureAddressSpec::Ed25519(pk_ed25519())
+ }
+
+ #[doc = " Test address "]
+ #[doc=$doc]
+ #[doc = "."]
+ pub fn address() -> Address {
+ Address::from_sigspec(&sigspec())
+ }
+ }
+ };
+}
+
+/// Define a secp256k1 test key.
+macro_rules! test_key_secp256k1 {
+ ($doc:expr, $name:ident, $pk:expr) => {
+ #[doc = " Test key "]
+ #[doc=$doc]
+ #[doc = "."]
+ pub mod $name {
+ use crate::{
+ crypto::signature::{secp256k1, PublicKey},
+ types::address::{Address, SignatureAddressSpec},
+ };
+
+ #[doc = " Test public key "]
+ #[doc=$doc]
+ #[doc = "."]
+ pub fn pk() -> PublicKey {
+ PublicKey::Secp256k1(pk_secp256k1())
+ }
+
+ #[doc = " Test Secp256k1 public key "]
+ #[doc=$doc]
+ #[doc = "."]
+ pub fn pk_secp256k1() -> secp256k1::PublicKey {
+ $pk.into()
+ }
+
+ #[doc = " Test address derivation information "]
+ #[doc=$doc]
+ #[doc = "."]
+ pub fn sigspec() -> SignatureAddressSpec {
+ SignatureAddressSpec::Secp256k1Eth(pk_secp256k1())
+ }
+
+ #[doc = " Test address "]
+ #[doc=$doc]
+ #[doc = "."]
+ pub fn address() -> Address {
+ Address::from_sigspec(&sigspec())
+ }
+ }
+ };
+}
+
+/// Define an sr25519 test key.
+macro_rules! test_key_sr25519 {
+ ($doc:expr, $name:ident, $pk:expr) => {
+ #[doc = " Test key "]
+ #[doc=$doc]
+ #[doc = "."]
+ pub mod $name {
+ use crate::{
+ crypto::signature::{sr25519, PublicKey},
+ types::address::{Address, SignatureAddressSpec},
+ };
+
+ #[doc = " Test public key "]
+ #[doc=$doc]
+ #[doc = "."]
+ pub fn pk() -> PublicKey {
+ PublicKey::Sr25519(pk_sr25519())
+ }
+
+ #[doc = " Test Sr25519 public key "]
+ #[doc=$doc]
+ #[doc = "."]
+ pub fn pk_sr25519() -> sr25519::PublicKey {
+ $pk.into()
+ }
+
+ #[doc = " Test address derivation information "]
+ #[doc=$doc]
+ #[doc = "."]
+ pub fn sigspec() -> SignatureAddressSpec {
+ SignatureAddressSpec::Sr25519(pk_sr25519())
+ }
+
+ #[doc = " Test address "]
+ #[doc=$doc]
+ #[doc = "."]
+ pub fn address() -> Address {
+ Address::from_sigspec(&sigspec())
+ }
+ }
+ };
+}
+
+test_key_ed25519!("A", alice, "NcPzNW3YU2T+ugNUtUWtoQnRvbOL9dYSaBfbjHLP1pE=");
+test_key_ed25519!("B", bob, "YgkEiVSR4SMQdfXw+ppuFYlqH0seutnCKk8KG8PyAx0=");
+test_key_ed25519!("C", charlie, "8l1AQE+ETOPLckiNJ7NOD+AfZdaPw6wguir/vSF11YI=");
+test_key_secp256k1!("D", dave, "AwF6GNjbybMzhi3XRj5R1oTiMMkO1nAwB7NZAlH1X4BE");
+test_key_secp256k1!("E", erin, "A9i0oSK+5sLSONbMYGmaFUA+Fb8zzqYEMUMspacIgO09");
+test_key_sr25519!("F", frank, "ljm9ZwdAldhlyWM2B4C+3gQZis+ceaxnt6QA4rOcP0k=");
+test_key_sr25519!("G", grace, "0MHrNhjVTOFWmsOgpWcC3L8jIX3ZatKr0/yxMPtwckc=");
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +
//! Mock dispatch context for use in tests.
+use std::collections::BTreeMap;
+
+use oasis_core_runtime::{
+ common::{crypto::mrae::deoxysii, namespace::Namespace, version::Version},
+ consensus::{beacon, roothash, state::ConsensusState, Event},
+ protocol::HostInfo,
+ storage::mkvs,
+ types::EventKind,
+};
+
+use crate::{
+ callformat,
+ context::{Context, RuntimeBatchContext},
+ dispatcher,
+ error::RuntimeError,
+ history,
+ keymanager::KeyManager,
+ module::MigrationHandler,
+ modules,
+ runtime::Runtime,
+ state::{self, CurrentState, TransactionResult},
+ storage::MKVSStore,
+ testing::{configmap, keymanager::MockKeyManagerClient},
+ types::{self, address::SignatureAddressSpec, transaction},
+};
+
+pub struct Config;
+
+impl modules::core::Config for Config {}
+
+/// A mock runtime that only has the core module.
+pub struct EmptyRuntime;
+
+impl Runtime for EmptyRuntime {
+ const VERSION: Version = Version::new(0, 0, 0);
+
+ type Core = modules::core::Module<Config>;
+
+ type Accounts = modules::accounts::Module;
+
+ type Modules = modules::core::Module<Config>;
+
+ fn genesis_state() -> <Self::Modules as MigrationHandler>::Genesis {
+ Default::default()
+ }
+}
+
+struct EmptyHistory;
+
+impl history::HistoryHost for EmptyHistory {
+ fn consensus_state_at(&self, _height: u64) -> Result<ConsensusState, history::Error> {
+ Err(history::Error::FailedToFetchBlock)
+ }
+
+ fn consensus_events_at(
+ &self,
+ _height: u64,
+ _kind: EventKind,
+ ) -> Result<Vec<Event>, history::Error> {
+ Err(history::Error::FailedToFetchEvents)
+ }
+}
+
+/// Mock dispatch context factory.
+pub struct Mock {
+ pub host_info: HostInfo,
+ pub runtime_header: roothash::Header,
+ pub runtime_round_results: roothash::RoundResults,
+ pub consensus_state: ConsensusState,
+ pub history: Box<dyn history::HistoryHost>,
+ pub epoch: beacon::EpochTime,
+
+ pub max_messages: u32,
+}
+
+impl Mock {
+ /// Create a new mock dispatch context.
+ pub fn create_ctx(&mut self) -> RuntimeBatchContext<'_, EmptyRuntime> {
+ self.create_ctx_for_runtime(false)
+ }
+
+ /// Create a new mock dispatch context.
+ pub fn create_ctx_for_runtime<R: Runtime>(
+ &mut self,
+ confidential: bool,
+ ) -> RuntimeBatchContext<'_, R> {
+ RuntimeBatchContext::new(
+ &self.host_info,
+ if confidential {
+ Some(Box::new(MockKeyManagerClient::new()) as Box<dyn KeyManager>)
+ } else {
+ None
+ },
+ &self.runtime_header,
+ &self.runtime_round_results,
+ &self.consensus_state,
+ &self.history,
+ self.epoch,
+ self.max_messages,
+ )
+ }
+
+ /// Create an instance with the given local configuration.
+ pub fn with_local_config(local_config: BTreeMap<String, cbor::Value>) -> Self {
+ // Ensure a current state is always available during tests. Note that one can always use a
+ // different store by calling `CurrentState::enter` explicitly.
+ CurrentState::init_local_fallback();
+
+ let consensus_tree = mkvs::Tree::builder()
+ .with_root_type(mkvs::RootType::State)
+ .build(Box::new(mkvs::sync::NoopReadSyncer));
+
+ Self {
+ host_info: HostInfo {
+ runtime_id: Namespace::default(),
+ consensus_backend: "mock".to_string(),
+ consensus_protocol_version: Version::default(),
+ consensus_chain_context: "test".to_string(),
+ local_config,
+ },
+ runtime_header: roothash::Header::default(),
+ runtime_round_results: roothash::RoundResults::default(),
+ consensus_state: ConsensusState::new(1, consensus_tree),
+ history: Box::new(EmptyHistory),
+ epoch: 1,
+ max_messages: 32,
+ }
+ }
+}
+
+impl Default for Mock {
+ fn default() -> Self {
+ let local_config_for_tests = configmap! {
+ // Allow expensive gas estimation and expensive queries so they can be tested.
+ "estimate_gas_by_simulating_contracts" => true,
+ "allowed_queries" => vec![
+ configmap! {"all_expensive" => true}
+ ],
+ };
+ Self::with_local_config(local_config_for_tests)
+ }
+}
+
+/// Create an empty MKVS store.
+pub fn empty_store() -> MKVSStore<mkvs::OverlayTree<mkvs::Tree>> {
+ let root = mkvs::OverlayTree::new(
+ mkvs::Tree::builder()
+ .with_root_type(mkvs::RootType::State)
+ .build(Box::new(mkvs::sync::NoopReadSyncer)),
+ );
+ MKVSStore::new(root)
+}
+
+/// Create a new mock transaction.
+pub fn transaction() -> transaction::Transaction {
+ transaction::Transaction {
+ version: 1,
+ call: transaction::Call {
+ format: transaction::CallFormat::Plain,
+ method: "mock".to_owned(),
+ body: cbor::Value::Simple(cbor::SimpleValue::NullValue),
+ ..Default::default()
+ },
+ auth_info: transaction::AuthInfo {
+ signer_info: vec![],
+ fee: transaction::Fee {
+ amount: Default::default(),
+ gas: 1_000_000,
+ consensus_messages: 32,
+ ..Default::default()
+ },
+ ..Default::default()
+ },
+ }
+}
+
+/// Options that can be used during mock signer calls.
+#[derive(Clone, Debug)]
+pub struct CallOptions {
+ /// Transaction fee.
+ pub fee: transaction::Fee,
+ /// Should the call be encrypted.
+ pub encrypted: bool,
+}
+
+impl Default for CallOptions {
+ fn default() -> Self {
+ Self {
+ fee: transaction::Fee {
+ amount: Default::default(),
+ gas: 1_000_000,
+ consensus_messages: 0,
+ ..Default::default()
+ },
+ encrypted: false,
+ }
+ }
+}
+
+/// A mock signer for use during tests.
+pub struct Signer {
+ nonce: u64,
+ sigspec: SignatureAddressSpec,
+}
+
+impl Signer {
+ /// Create a new mock signer using the given nonce and signature spec.
+ pub fn new(nonce: u64, sigspec: SignatureAddressSpec) -> Self {
+ Self { nonce, sigspec }
+ }
+
+ /// Address specification for this signer.
+ pub fn sigspec(&self) -> &SignatureAddressSpec {
+ &self.sigspec
+ }
+
+ /// Dispatch a call to the given method.
+ pub fn call<C, B>(&mut self, ctx: &C, method: &str, body: B) -> dispatcher::DispatchResult
+ where
+ C: Context,
+ B: cbor::Encode,
+ {
+ self.call_opts(ctx, method, body, Default::default())
+ }
+
+ /// Dispatch a call to the given method with the given options.
+ pub fn call_opts<C, B>(
+ &mut self,
+ ctx: &C,
+ method: &str,
+ body: B,
+ opts: CallOptions,
+ ) -> dispatcher::DispatchResult
+ where
+ C: Context,
+ B: cbor::Encode,
+ {
+ let mut call = transaction::Call {
+ format: transaction::CallFormat::Plain,
+ method: method.to_owned(),
+ body: cbor::to_value(body),
+ ..Default::default()
+ };
+ if opts.encrypted {
+ let key_pair = deoxysii::generate_key_pair();
+ let nonce = [0u8; deoxysii::NONCE_SIZE];
+ let km = ctx.key_manager().unwrap();
+ let epoch = ctx.epoch();
+ let runtime_keypair = km
+ .get_or_create_ephemeral_keys(callformat::get_key_pair_id(epoch), epoch)
+ .unwrap();
+ let runtime_pk = runtime_keypair.input_keypair.pk;
+ call = transaction::Call {
+ format: transaction::CallFormat::EncryptedX25519DeoxysII,
+ method: "".to_owned(),
+ body: cbor::to_value(types::callformat::CallEnvelopeX25519DeoxysII {
+ pk: key_pair.0.into(),
+ nonce,
+ epoch,
+ data: deoxysii::box_seal(
+ &nonce,
+ cbor::to_vec(call),
+ vec![],
+ &runtime_pk.0,
+ &key_pair.1,
+ )
+ .unwrap(),
+ }),
+ ..Default::default()
+ }
+ };
+ let tx = transaction::Transaction {
+ version: 1,
+ call,
+ auth_info: transaction::AuthInfo {
+ signer_info: vec![transaction::SignerInfo::new_sigspec(
+ self.sigspec.clone(),
+ self.nonce,
+ )],
+ fee: opts.fee,
+ ..Default::default()
+ },
+ };
+
+ let result = dispatcher::Dispatcher::<C::Runtime>::dispatch_tx(ctx, 1024, tx, 0)
+ .expect("dispatch should work");
+
+ // Increment the nonce.
+ self.nonce += 1;
+
+ result
+ }
+
+ /// Dispatch a query to the given method.
+ pub fn query<C, A, R>(&self, ctx: &C, method: &str, args: A) -> Result<R, RuntimeError>
+ where
+ C: Context,
+ A: cbor::Encode,
+ R: cbor::Decode,
+ {
+ let result = CurrentState::with_transaction_opts(
+ state::Options::new().with_mode(state::Mode::Check),
+ || {
+ let result = dispatcher::Dispatcher::<C::Runtime>::dispatch_query(
+ ctx,
+ method,
+ cbor::to_vec(args),
+ );
+
+ TransactionResult::Rollback(result)
+ },
+ )?;
+ Ok(cbor::from_slice(&result).expect("result should decode correctly"))
+ }
+}
+//! Module which contains utilities useful for testing and development.
+
+pub mod keymanager;
+pub mod keys;
+pub mod mock;
+
+/// Constructs a BTreeMap where keys are coerced to strings, and values to cbor::Value.
+/// Syntax: `configmap! { "key" => value, ... }`.
+macro_rules! configmap {
+ // allow trailing comma
+ ( $($key:expr => $value:expr,)+ ) => (configmap!($($key => $value),+));
+ ( $($key:expr => $value:expr),* ) => {
+ {
+ let mut m = BTreeMap::new();
+ $( m.insert($key.to_string(), cbor::to_value($value)); )*
+ m
+ }
+ };
+}
+pub(crate) use configmap;
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +
//! Account address type.
+use std::{convert::TryFrom, fmt};
+
+use bech32::{Bech32, Hrp};
+use thiserror::Error;
+
+use oasis_core_runtime::{
+ common::{
+ crypto::{hash::Hash, signature::PublicKey as ConsensusPublicKey},
+ namespace::Namespace,
+ },
+ consensus::address::Address as ConsensusAddress,
+};
+
+use crate::crypto::{
+ multisig,
+ signature::{ed25519, secp256k1, sr25519, PublicKey},
+};
+
+const ADDRESS_VERSION_SIZE: usize = 1;
+const ADDRESS_DATA_SIZE: usize = 20;
+const ADDRESS_SIZE: usize = ADDRESS_VERSION_SIZE + ADDRESS_DATA_SIZE;
+
+/// V0 address version.
+pub const ADDRESS_V0_VERSION: u8 = 0;
+/// V0 Ed25519 addres context (shared with consensus layer).
+pub const ADDRESS_V0_ED25519_CONTEXT: &[u8] = b"oasis-core/address: staking";
+/// V0 Secp256k1 address context.
+pub const ADDRESS_V0_SECP256K1ETH_CONTEXT: &[u8] = b"oasis-runtime-sdk/address: secp256k1eth";
+/// V0 Sr25519 address context.
+pub const ADDRESS_V0_SR25519_CONTEXT: &[u8] = b"oasis-runtime-sdk/address: sr25519";
+
+/// V0 module address context.
+pub const ADDRESS_V0_MODULE_CONTEXT: &[u8] = b"oasis-runtime-sdk/address: module";
+
+/// V0 runtime address context.
+pub const ADDRESS_RUNTIME_V0_CONTEXT: &[u8] = b"oasis-core/address: runtime";
+/// V0 runtime address version.
+pub const ADDRESS_RUNTIME_V0_VERSION: u8 = 0;
+
+/// V0 multisig address context.
+pub const ADDRESS_V0_MULTISIG_CONTEXT: &[u8] = b"oasis-runtime-sdk/address: multisig";
+
+/// Human readable part for Bech32-encoded addresses.
+pub const ADDRESS_BECH32_HRP: Hrp = Hrp::parse_unchecked("oasis");
+
+/// Information for signature-based authentication and public key-based address derivation.
+#[derive(Clone, Debug, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+pub enum SignatureAddressSpec {
+ /// Ed25519 address derivation compatible with the consensus layer.
+ #[cbor(rename = "ed25519")]
+ Ed25519(ed25519::PublicKey),
+
+ /// Ethereum-compatible address derivation from Secp256k1 public keys.
+ #[cbor(rename = "secp256k1eth")]
+ Secp256k1Eth(secp256k1::PublicKey),
+
+ /// Sr25519 address derivation.
+ #[cbor(rename = "sr25519")]
+ Sr25519(sr25519::PublicKey),
+}
+
+impl SignatureAddressSpec {
+ /// Try to construct an authentication/address derivation specification from the given public
+ /// key. In case the given scheme is not supported, it returns `None`.
+ pub fn try_from_pk(pk: &PublicKey) -> Option<Self> {
+ match pk {
+ PublicKey::Ed25519(pk) => Some(Self::Ed25519(pk.clone())),
+ PublicKey::Secp256k1(pk) => Some(Self::Secp256k1Eth(pk.clone())),
+ PublicKey::Sr25519(pk) => Some(Self::Sr25519(pk.clone())),
+ _ => None,
+ }
+ }
+
+ /// Public key of the authentication/address derivation specification.
+ pub fn public_key(&self) -> PublicKey {
+ match self {
+ Self::Ed25519(pk) => PublicKey::Ed25519(pk.clone()),
+ Self::Secp256k1Eth(pk) => PublicKey::Secp256k1(pk.clone()),
+ Self::Sr25519(pk) => PublicKey::Sr25519(pk.clone()),
+ }
+ }
+}
+
+/// Error.
+#[derive(Error, Debug)]
+pub enum Error {
+ #[error("malformed address")]
+ MalformedAddress,
+}
+
+/// An account address.
+#[derive(Copy, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct Address([u8; ADDRESS_SIZE]);
+
+impl Address {
+ /// Size of an address in bytes.
+ pub const SIZE: usize = ADDRESS_SIZE;
+
+ /// Creates a new address from a context, version and data.
+ pub fn new(ctx: &'static [u8], version: u8, data: &[u8]) -> Self {
+ let h = Hash::digest_bytes_list(&[ctx, &[version], data]);
+
+ let mut a = [0; ADDRESS_SIZE];
+ a[..ADDRESS_VERSION_SIZE].copy_from_slice(&[version]);
+ a[ADDRESS_VERSION_SIZE..].copy_from_slice(h.truncated(ADDRESS_DATA_SIZE));
+
+ Self(a)
+ }
+
+ /// Tries to create a new address from raw bytes.
+ pub fn from_bytes(data: &[u8]) -> Result<Self, Error> {
+ if data.len() != ADDRESS_SIZE {
+ return Err(Error::MalformedAddress);
+ }
+
+ let mut a = [0; ADDRESS_SIZE];
+ a.copy_from_slice(data);
+
+ Ok(Self(a))
+ }
+
+ /// Convert the address into raw bytes.
+ pub fn into_bytes(self) -> [u8; ADDRESS_SIZE] {
+ self.0
+ }
+
+ /// Creates a new address for a specific module and kind.
+ pub fn from_module(module: &str, kind: &str) -> Self {
+ Self::from_module_raw(module, kind.as_bytes())
+ }
+
+ /// Creates a new address for a specific module and raw kind.
+ pub fn from_module_raw(module: &str, kind: &[u8]) -> Self {
+ Self::new(
+ ADDRESS_V0_MODULE_CONTEXT,
+ ADDRESS_V0_VERSION,
+ &[module.as_bytes(), b".", kind].concat(),
+ )
+ }
+
+ /// Creates a new runtime address.
+ pub fn from_runtime_id(id: &Namespace) -> Self {
+ Self::new(
+ ADDRESS_RUNTIME_V0_CONTEXT,
+ ADDRESS_RUNTIME_V0_VERSION,
+ id.as_ref(),
+ )
+ }
+
+ /// Creates a new address from a public key.
+ pub fn from_sigspec(spec: &SignatureAddressSpec) -> Self {
+ match spec {
+ SignatureAddressSpec::Ed25519(pk) => Self::new(
+ ADDRESS_V0_ED25519_CONTEXT,
+ ADDRESS_V0_VERSION,
+ pk.as_bytes(),
+ ),
+ SignatureAddressSpec::Secp256k1Eth(pk) => Self::new(
+ ADDRESS_V0_SECP256K1ETH_CONTEXT,
+ ADDRESS_V0_VERSION,
+ // Use a scheme such that we can compute Secp256k1 addresses from Ethereum
+ // addresses as this makes things more interoperable.
+ &pk.to_eth_address(),
+ ),
+ SignatureAddressSpec::Sr25519(pk) => Self::new(
+ ADDRESS_V0_SR25519_CONTEXT,
+ ADDRESS_V0_VERSION,
+ pk.as_bytes(),
+ ),
+ }
+ }
+
+ /// Creates a new address from a multisig configuration.
+ pub fn from_multisig(config: multisig::Config) -> Self {
+ let config_vec = cbor::to_vec(config);
+ Self::new(ADDRESS_V0_MULTISIG_CONTEXT, ADDRESS_V0_VERSION, &config_vec)
+ }
+
+ /// Creates a new address from an Ethereum-compatible address.
+ pub fn from_eth(eth_address: &[u8]) -> Self {
+ Self::new(
+ ADDRESS_V0_SECP256K1ETH_CONTEXT,
+ ADDRESS_V0_VERSION,
+ eth_address,
+ )
+ }
+
+ /// Creates a new address from a consensus-layer Ed25519 public key.
+ ///
+ /// This is a convenience wrapper and the same result can be obtained by going via the
+ /// `from_sigspec` method using the same Ed25519 public key.
+ pub fn from_consensus_pk(pk: &ConsensusPublicKey) -> Self {
+ Self::from_bytes(ConsensusAddress::from_pk(pk).as_ref()).unwrap()
+ }
+
+ /// Tries to create a new address from Bech32-encoded string.
+ pub fn from_bech32(data: &str) -> Result<Self, Error> {
+ let (hrp, data) = bech32::decode(data).map_err(|_| Error::MalformedAddress)?;
+ if hrp != ADDRESS_BECH32_HRP {
+ return Err(Error::MalformedAddress);
+ }
+
+ Self::from_bytes(&data)
+ }
+
+ /// Converts an address to Bech32 representation.
+ pub fn to_bech32(self) -> String {
+ bech32::encode::<Bech32>(ADDRESS_BECH32_HRP, &self.0).unwrap()
+ }
+}
+
+impl AsRef<[u8]> for Address {
+ fn as_ref(&self) -> &[u8] {
+ &self.0
+ }
+}
+
+impl TryFrom<&[u8]> for Address {
+ type Error = Error;
+
+ fn try_from(bytes: &[u8]) -> Result<Self, Self::Error> {
+ Self::from_bytes(bytes)
+ }
+}
+
+impl From<&'static str> for Address {
+ fn from(s: &'static str) -> Self {
+ Self::from_bech32(s).unwrap()
+ }
+}
+
+impl fmt::LowerHex for Address {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ for i in &self.0[..] {
+ write!(f, "{i:02x}")?;
+ }
+ Ok(())
+ }
+}
+
+impl fmt::Debug for Address {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ write!(f, "{}", self.to_bech32())?;
+ Ok(())
+ }
+}
+
+impl fmt::Display for Address {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ write!(f, "{}", self.to_bech32())?;
+ Ok(())
+ }
+}
+
+impl cbor::Encode for Address {
+ fn into_cbor_value(self) -> cbor::Value {
+ cbor::Value::ByteString(self.as_ref().to_vec())
+ }
+}
+
+impl cbor::Decode for Address {
+ fn try_default() -> Result<Self, cbor::DecodeError> {
+ Ok(Default::default())
+ }
+
+ fn try_from_cbor_value(value: cbor::Value) -> Result<Self, cbor::DecodeError> {
+ match value {
+ cbor::Value::ByteString(data) => {
+ Self::from_bytes(&data).map_err(|_| cbor::DecodeError::UnexpectedType)
+ }
+ _ => Err(cbor::DecodeError::UnexpectedType),
+ }
+ }
+}
+
+impl slog::Value for Address {
+ fn serialize(
+ &self,
+ _record: &slog::Record<'_>,
+ key: slog::Key,
+ serializer: &mut dyn slog::Serializer,
+ ) -> slog::Result {
+ serializer.emit_str(key, &self.to_bech32())
+ }
+}
+
+impl From<Address> for ConsensusAddress {
+ fn from(addr: Address) -> ConsensusAddress {
+ ConsensusAddress::from(&addr.0)
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use base64::prelude::*;
+ use bech32::Bech32m;
+
+ use super::*;
+ use crate::testing::keys;
+
+ #[test]
+ fn test_address_ed25519() {
+ let spec =
+ SignatureAddressSpec::Ed25519("utrdHlX///////////////////////////////////8=".into());
+
+ let addr = Address::from_sigspec(&spec);
+ assert_eq!(
+ addr.to_bech32(),
+ "oasis1qryqqccycvckcxp453tflalujvlf78xymcdqw4vz"
+ );
+ }
+
+ #[test]
+ fn test_address_secp256k1eth() {
+ let spec = SignatureAddressSpec::Secp256k1Eth(
+ "Arra3R5V////////////////////////////////////".into(),
+ );
+
+ let addr = Address::from_sigspec(&spec);
+ assert_eq!(
+ addr.to_bech32(),
+ "oasis1qzd7akz24n6fxfhdhtk977s5857h3c6gf5583mcg"
+ );
+ }
+
+ #[test]
+ fn test_address_multisig() {
+ let config = multisig::Config {
+ signers: vec![
+ multisig::Signer {
+ public_key: keys::alice::pk(),
+ weight: 1,
+ },
+ multisig::Signer {
+ public_key: keys::bob::pk(),
+ weight: 1,
+ },
+ ],
+ threshold: 2,
+ };
+ let addr = Address::from_multisig(config);
+ assert_eq!(
+ addr,
+ Address::from_bech32("oasis1qpcprk8jxpsjxw9fadxvzrv9ln7td69yus8rmtux").unwrap(),
+ );
+ }
+
+ #[test]
+ fn test_address_try_from_bytes() {
+ let bytes_fixture = vec![42u8; ADDRESS_SIZE + 1];
+ assert_eq!(
+ Address::try_from(&bytes_fixture[0..ADDRESS_SIZE]).unwrap(),
+ Address::from_bytes(&bytes_fixture[0..ADDRESS_SIZE]).unwrap()
+ );
+ assert!(matches!(
+ Address::try_from(bytes_fixture.as_slice()).unwrap_err(),
+ Error::MalformedAddress
+ ));
+ }
+
+ #[test]
+ fn test_address_from_bech32_invalid_hrp() {
+ assert!(matches!(
+ Address::from_bech32("sisoa1qpcprk8jxpsjxw9fadxvzrv9ln7td69yus8rmtux").unwrap_err(),
+ Error::MalformedAddress,
+ ));
+ }
+
+ #[test]
+ fn test_address_from_bech32_variants() {
+ let b = vec![42u8; ADDRESS_SIZE];
+ let bech32_addr = bech32::encode::<Bech32>(ADDRESS_BECH32_HRP, &b).unwrap();
+ let bech32m_addr = bech32::encode::<Bech32m>(ADDRESS_BECH32_HRP, &b).unwrap();
+
+ assert!(
+ Address::from_bech32(&bech32_addr).is_ok(),
+ "bech32 address should be ok"
+ );
+ assert!(
+ Address::from_bech32(&bech32m_addr).is_ok(),
+ "bech32m address should be ok",
+ );
+ }
+
+ #[test]
+ fn test_address_into_consensus_address() {
+ let spec =
+ SignatureAddressSpec::Ed25519("utrdHlX///////////////////////////////////8=".into());
+ let addr = Address::from_sigspec(&spec);
+
+ let consensus_addr: ConsensusAddress = addr.into();
+ assert_eq!(addr.to_bech32(), consensus_addr.to_bech32())
+ }
+
+ #[test]
+ fn test_address_from_runtime_id() {
+ let runtime_id =
+ Namespace::from("80000000000000002aff7f6dfb62720cfd735f2b037b81572fad1b7937d826b3");
+ let addr = Address::from_runtime_id(&runtime_id);
+ assert_eq!(
+ addr.to_bech32(),
+ "oasis1qpllh99nhwzrd56px4txvl26atzgg4f3a58jzzad"
+ );
+ }
+
+ #[test]
+ fn test_address_from_module() {
+ let id: u64 = 42;
+ let addr = Address::from_module_raw("contracts", &id.to_be_bytes());
+
+ assert_eq!(
+ addr.to_bech32(),
+ "oasis1qq398yyk4wt2zxhtt8c66raynelgt6ngh5yq87xg"
+ );
+ }
+
+ #[test]
+ fn test_address_from_eth() {
+ let eth_address = hex::decode("dce075e1c39b1ae0b75d554558b6451a226ffe00").unwrap();
+ let addr = Address::from_eth(ð_address);
+ assert_eq!(
+ addr.to_bech32(),
+ "oasis1qrk58a6j2qn065m6p06jgjyt032f7qucy5wqeqpt"
+ );
+ }
+
+ #[test]
+ fn test_address_from_consensus_pk() {
+ // Same test vector as in `test_address_ed25519`.
+ let pk: ConsensusPublicKey = BASE64_STANDARD
+ .decode("utrdHlX///////////////////////////////////8=")
+ .unwrap()
+ .into();
+
+ let addr = Address::from_consensus_pk(&pk);
+ assert_eq!(
+ addr.to_bech32(),
+ "oasis1qryqqccycvckcxp453tflalujvlf78xymcdqw4vz"
+ );
+ }
+
+ #[test]
+ fn test_address_raw() {
+ let eth_address = hex::decode("dce075e1c39b1ae0b75d554558b6451a226ffe00").unwrap();
+ let addr = Address::new(
+ ADDRESS_V0_SECP256K1ETH_CONTEXT,
+ ADDRESS_V0_VERSION,
+ ð_address,
+ );
+ assert_eq!(
+ addr.to_bech32(),
+ "oasis1qrk58a6j2qn065m6p06jgjyt032f7qucy5wqeqpt"
+ );
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +
//! Types related to call formats.
+use crate::core::common::crypto::{mrae::deoxysii, x25519};
+
+/// Call data key pair ID domain separation context base.
+pub const CALL_DATA_KEY_PAIR_ID_CONTEXT_BASE: &[u8] = b"oasis-runtime-sdk/private: tx";
+
+/// A call envelope when using the EncryptedX25519DeoxysII format.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct CallEnvelopeX25519DeoxysII {
+ /// Caller's ephemeral public key used for X25519.
+ pub pk: x25519::PublicKey,
+ /// Nonce.
+ pub nonce: [u8; deoxysii::NONCE_SIZE],
+ /// Epoch of the ephemeral runtime key.
+ #[cbor(optional)]
+ pub epoch: u64,
+ /// Encrypted call data.
+ pub data: Vec<u8>,
+}
+
+/// A result envelope when using the EncryptedX25519DeoxysII format.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct ResultEnvelopeX25519DeoxysII {
+ /// Nonce.
+ pub nonce: [u8; deoxysii::NONCE_SIZE],
+ /// Encrypted call data.
+ pub data: Vec<u8>,
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +
use std::fmt::Debug;
+
+use oasis_core_runtime::consensus;
+
+/// Result of a message being processed by the consensus layer.
+pub type MessageEvent = consensus::roothash::MessageEvent;
+
+/// Handler name and context to be called after message is executed.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct MessageEventHookInvocation {
+ pub hook_name: String,
+ pub payload: cbor::Value,
+}
+
+impl MessageEventHookInvocation {
+ /// Constructs a new message hook invocation.
+ pub fn new<S: cbor::Encode>(name: String, payload: S) -> Self {
+ Self {
+ hook_name: name,
+ payload: cbor::to_value(payload),
+ }
+ }
+}
+
+/// Result of a message being processed by the consensus layer combined with the context for the
+/// result handler.
+#[derive(Clone, Debug)]
+pub struct MessageResult {
+ pub event: MessageEvent,
+ pub context: cbor::Value,
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +
//! Token types.
+use std::{convert::TryFrom, fmt};
+
+/// Name/type of the token.
+#[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash, cbor::Encode)]
+#[cbor(transparent)]
+pub struct Denomination(Vec<u8>);
+
+impl Denomination {
+ /// Maximum length of a denomination.
+ pub const MAX_LENGTH: usize = 32;
+ /// Denomination in native token.
+ pub const NATIVE: Denomination = Denomination(Vec::new());
+
+ /// Whether the denomination represents the native token.
+ pub fn is_native(&self) -> bool {
+ self.0.is_empty()
+ }
+
+ /// Raw representation of a denomination.
+ pub fn into_vec(self) -> Vec<u8> {
+ self.0
+ }
+}
+
+impl AsRef<[u8]> for Denomination {
+ fn as_ref(&self) -> &[u8] {
+ &self.0
+ }
+}
+
+impl fmt::Display for Denomination {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ if self.is_native() {
+ write!(f, "<native>")?;
+ } else {
+ write!(f, "{}", String::from_utf8_lossy(&self.0))?;
+ }
+ Ok(())
+ }
+}
+
+impl std::str::FromStr for Denomination {
+ type Err = Error;
+
+ fn from_str(v: &str) -> Result<Self, Self::Err> {
+ Self::try_from(v.as_bytes())
+ }
+}
+
+impl TryFrom<&[u8]> for Denomination {
+ type Error = Error;
+
+ fn try_from(bytes: &[u8]) -> Result<Self, Self::Error> {
+ if bytes.len() > Self::MAX_LENGTH {
+ return Err(Error::NameTooLong {
+ length: bytes.len(),
+ });
+ }
+ Ok(Self(bytes.to_vec()))
+ }
+}
+
+impl cbor::Decode for Denomination {
+ fn try_default() -> Result<Self, cbor::DecodeError> {
+ Ok(Default::default())
+ }
+
+ fn try_from_cbor_value(value: cbor::Value) -> Result<Self, cbor::DecodeError> {
+ match value {
+ cbor::Value::ByteString(data) => {
+ Self::try_from(data.as_ref()).map_err(|_| cbor::DecodeError::UnexpectedType)
+ }
+ _ => Err(cbor::DecodeError::UnexpectedType),
+ }
+ }
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+ #[error(
+ "denomination name too long. received length {length} exceeded maximum of {}",
+ Denomination::MAX_LENGTH
+ )]
+ NameTooLong { length: usize },
+}
+
+/// Token amount of given denomination in base units.
+#[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, cbor::Encode, cbor::Decode)]
+pub struct BaseUnits(pub u128, pub Denomination);
+
+impl BaseUnits {
+ /// Creates a new token amount of the given denomination.
+ pub const fn new(amount: u128, denomination: Denomination) -> Self {
+ BaseUnits(amount, denomination)
+ }
+
+ /// Token amount in base units.
+ pub fn amount(&self) -> u128 {
+ self.0
+ }
+
+ /// Denomination of the token amount.
+ pub fn denomination(&self) -> &Denomination {
+ &self.1
+ }
+}
+
+impl fmt::Display for BaseUnits {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ write!(f, "{} {}", self.0, self.1)?;
+ Ok(())
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ #[test]
+ fn test_basic() {
+ let cases = vec![
+ // Native denomination.
+ (0, Denomination::NATIVE, "824040"),
+ (1, Denomination::NATIVE, "82410140"),
+ (1000, Denomination::NATIVE, "824203e840"),
+ // Custom denomination.
+ (0, "test".parse().unwrap(), "82404474657374"),
+ (1, "test".parse().unwrap(), "8241014474657374"),
+ (1000, "test".parse().unwrap(), "824203e84474657374"),
+ ];
+
+ for tc in cases {
+ let token = BaseUnits::new(tc.0, tc.1);
+ let enc = cbor::to_vec(token.clone());
+ assert_eq!(hex::encode(&enc), tc.2, "serialization should match");
+
+ let dec: BaseUnits = cbor::from_slice(&enc).expect("deserialization should succeed");
+ assert_eq!(dec, token, "serialization should round-trip");
+ }
+ }
+
+ #[test]
+ fn test_decoding_denomination() {
+ macro_rules! assert_rountrip_ok {
+ ($bytes:expr) => {
+ let enc = cbor::to_vec($bytes.to_vec());
+ let dec: Denomination = cbor::from_slice(&enc).unwrap();
+ assert_eq!(dec, Denomination::try_from($bytes).unwrap());
+ assert_eq!(dec.0, $bytes);
+ };
+ }
+
+ let bytes_fixture = vec![42u8; Denomination::MAX_LENGTH + 1];
+
+ assert_rountrip_ok!(&bytes_fixture[0..0]);
+ assert_rountrip_ok!(&bytes_fixture[0..1]);
+ assert_rountrip_ok!(&bytes_fixture[0..Denomination::MAX_LENGTH]);
+
+ // Too long denomination:
+ let dec_result: Result<Denomination, _> = cbor::from_slice(&cbor::to_vec(bytes_fixture));
+ assert!(dec_result.is_err());
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +
//! Transaction types.
+use anyhow::anyhow;
+use thiserror::Error;
+
+use crate::{
+ crypto::{
+ multisig,
+ signature::{self, PublicKey, Signature, Signer},
+ },
+ types::{
+ address,
+ address::{Address, SignatureAddressSpec},
+ token,
+ },
+};
+
+/// Transaction signature domain separation context base.
+pub const SIGNATURE_CONTEXT_BASE: &[u8] = b"oasis-runtime-sdk/tx: v0";
+/// The latest transaction format version.
+pub const LATEST_TRANSACTION_VERSION: u16 = 1;
+
+/// Error.
+#[derive(Debug, Error)]
+pub enum Error {
+ #[error("unsupported version")]
+ UnsupportedVersion,
+ #[error("malformed transaction: {0}")]
+ MalformedTransaction(anyhow::Error),
+ #[error("signer not found in transaction")]
+ SignerNotFound,
+ #[error("failed to sign: {0}")]
+ FailedToSign(#[from] signature::Error),
+}
+
+/// A container for data that authenticates a transaction.
+#[derive(Clone, Default, Debug, cbor::Encode, cbor::Decode)]
+pub enum AuthProof {
+ /// For _signature_ authentication.
+ #[cbor(rename = "signature")]
+ Signature(Signature),
+ /// For _multisig_ authentication.
+ #[cbor(rename = "multisig")]
+ Multisig(multisig::SignatureSetOwned),
+ /// A flag to use module-controlled decoding. The string is an encoding scheme name that a
+ /// module must handle. The scheme name must not be empty.
+ #[cbor(rename = "module")]
+ Module(String),
+
+ /// A non-serializable placeholder value.
+ #[cbor(skip)]
+ #[default]
+ Invalid,
+}
+
+/// An unverified signed transaction.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct UnverifiedTransaction(pub Vec<u8>, pub Vec<AuthProof>);
+
+impl UnverifiedTransaction {
+ /// Verify and deserialize the unverified transaction.
+ pub fn verify(self) -> Result<Transaction, Error> {
+ // Deserialize the inner body.
+ let body: Transaction =
+ cbor::from_slice(&self.0).map_err(|e| Error::MalformedTransaction(e.into()))?;
+ body.validate_basic()?;
+
+ // Basic structure validation.
+ if self.1.len() != body.auth_info.signer_info.len() {
+ return Err(Error::MalformedTransaction(anyhow!(
+ "unexpected number of auth proofs. expected {} but found {}",
+ body.auth_info.signer_info.len(),
+ self.1.len()
+ )));
+ }
+
+ // Verify all signatures.
+ let ctx = signature::context::get_chain_context_for(SIGNATURE_CONTEXT_BASE);
+ let mut public_keys = vec![];
+ let mut signatures = vec![];
+ for (si, auth_proof) in body.auth_info.signer_info.iter().zip(self.1.iter()) {
+ let (mut batch_pks, mut batch_sigs) = si.address_spec.batch(auth_proof)?;
+ public_keys.append(&mut batch_pks);
+ signatures.append(&mut batch_sigs);
+ }
+ PublicKey::verify_batch_multisig(&ctx, &self.0, &public_keys, &signatures)
+ .map_err(|e| Error::MalformedTransaction(e.into()))?;
+
+ Ok(body)
+ }
+}
+
+/// Transaction signer.
+pub struct TransactionSigner {
+ auth_info: AuthInfo,
+ ut: UnverifiedTransaction,
+}
+
+impl TransactionSigner {
+ /// Construct a new transaction signer for the given transaction.
+ pub fn new(tx: Transaction) -> Self {
+ let mut ts = Self {
+ auth_info: tx.auth_info.clone(),
+ ut: UnverifiedTransaction(cbor::to_vec(tx), vec![]),
+ };
+ ts.allocate_proofs();
+
+ ts
+ }
+
+ /// Allocate proof structures based on the specified authentication info in the transaction.
+ fn allocate_proofs(&mut self) {
+ if !self.ut.1.is_empty() {
+ return;
+ }
+
+ // Allocate proof slots.
+ self.ut
+ .1
+ .resize_with(self.auth_info.signer_info.len(), Default::default);
+
+ for (si, ap) in self.auth_info.signer_info.iter().zip(self.ut.1.iter_mut()) {
+ match (&si.address_spec, ap) {
+ (AddressSpec::Multisig(cfg), ap) => {
+ // Allocate multisig slots.
+ *ap = AuthProof::Multisig(vec![None; cfg.signers.len()]);
+ }
+ _ => continue,
+ }
+ }
+ }
+
+ /// Sign the transaction and append the signature.
+ ///
+ /// The signer must be specified in the `auth_info` field.
+ pub fn append_sign<S>(&mut self, signer: &S) -> Result<(), Error>
+ where
+ S: Signer + ?Sized,
+ {
+ let ctx = signature::context::get_chain_context_for(SIGNATURE_CONTEXT_BASE);
+ let signature = signer.sign(&ctx, &self.ut.0)?;
+
+ let mut matched = false;
+ for (si, ap) in self.auth_info.signer_info.iter().zip(self.ut.1.iter_mut()) {
+ match (&si.address_spec, ap) {
+ (AddressSpec::Signature(spec), ap) => {
+ if spec.public_key() != signer.public_key() {
+ continue;
+ }
+
+ matched = true;
+ *ap = AuthProof::Signature(signature.clone());
+ }
+ (AddressSpec::Multisig(cfg), AuthProof::Multisig(ref mut sigs)) => {
+ for (i, mss) in cfg.signers.iter().enumerate() {
+ if mss.public_key != signer.public_key() {
+ continue;
+ }
+
+ matched = true;
+ sigs[i] = Some(signature.clone());
+ }
+ }
+ _ => {
+ return Err(Error::MalformedTransaction(anyhow!(
+ "malformed address_spec"
+ )))
+ }
+ }
+ }
+ if !matched {
+ return Err(Error::SignerNotFound);
+ }
+ Ok(())
+ }
+
+ /// Finalize the signing process and return the (signed) unverified transaction.
+ pub fn finalize(self) -> UnverifiedTransaction {
+ self.ut
+ }
+}
+
+/// Transaction.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct Transaction {
+ #[cbor(rename = "v")]
+ pub version: u16,
+
+ pub call: Call,
+
+ #[cbor(rename = "ai")]
+ pub auth_info: AuthInfo,
+}
+
+impl Transaction {
+ /// Create a new (unsigned) transaction.
+ pub fn new<B>(method: &str, body: B) -> Self
+ where
+ B: cbor::Encode,
+ {
+ Self {
+ version: LATEST_TRANSACTION_VERSION,
+ call: Call {
+ format: CallFormat::Plain,
+ method: method.to_string(),
+ body: cbor::to_value(body),
+ ..Default::default()
+ },
+ auth_info: Default::default(),
+ }
+ }
+
+ /// Prepare this transaction for signing.
+ pub fn prepare_for_signing(self) -> TransactionSigner {
+ TransactionSigner::new(self)
+ }
+
+ /// Maximum amount of gas that the transaction can use.
+ pub fn fee_gas(&self) -> u64 {
+ self.auth_info.fee.gas
+ }
+
+ /// Set maximum amount of gas that the transaction can use.
+ pub fn set_fee_gas(&mut self, gas: u64) {
+ self.auth_info.fee.gas = gas;
+ }
+
+ /// Amount of fee to pay for transaction execution.
+ pub fn fee_amount(&self) -> &token::BaseUnits {
+ &self.auth_info.fee.amount
+ }
+
+ /// Set amount of fee to pay for transaction execution.
+ pub fn set_fee_amount(&mut self, amount: token::BaseUnits) {
+ self.auth_info.fee.amount = amount;
+ }
+
+ /// Set a proxy for paying the transaction fee.
+ pub fn set_fee_proxy(&mut self, module: &str, id: &[u8]) {
+ self.auth_info.fee.proxy = Some(FeeProxy {
+ module: module.to_string(),
+ id: id.to_vec(),
+ });
+ }
+
+ /// Append a new transaction signer information to the transaction.
+ pub fn append_signer_info(&mut self, address_spec: AddressSpec, nonce: u64) {
+ self.auth_info.signer_info.push(SignerInfo {
+ address_spec,
+ nonce,
+ })
+ }
+
+ /// Append a new transaction signer information with a signature address specification to the
+ /// transaction.
+ pub fn append_auth_signature(&mut self, spec: SignatureAddressSpec, nonce: u64) {
+ self.append_signer_info(AddressSpec::Signature(spec), nonce);
+ }
+
+ /// Append a new transaction signer information with a multisig address specification to the
+ /// transaction.
+ pub fn append_auth_multisig(&mut self, cfg: multisig::Config, nonce: u64) {
+ self.append_signer_info(AddressSpec::Multisig(cfg), nonce);
+ }
+
+ /// Perform basic validation on the transaction.
+ pub fn validate_basic(&self) -> Result<(), Error> {
+ if self.version != LATEST_TRANSACTION_VERSION {
+ return Err(Error::UnsupportedVersion);
+ }
+ if self.auth_info.signer_info.is_empty() {
+ return Err(Error::MalformedTransaction(anyhow!(
+ "transaction has no signers"
+ )));
+ }
+ Ok(())
+ }
+}
+
+/// Format used for encoding the call (and output) information.
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, cbor::Encode, cbor::Decode)]
+#[repr(u8)]
+#[cbor(with_default)]
+pub enum CallFormat {
+ /// Plain text call data.
+ #[default]
+ Plain = 0,
+ /// Encrypted call data using X25519 for key exchange and Deoxys-II for symmetric encryption.
+ EncryptedX25519DeoxysII = 1,
+}
+
+/// Method call.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub struct Call {
+ /// Call format.
+ #[cbor(optional)]
+ pub format: CallFormat,
+ /// Method name.
+ #[cbor(optional)]
+ pub method: String,
+ /// Method body.
+ pub body: cbor::Value,
+ /// Read-only flag.
+ ///
+ /// A read-only call cannot make any changes to runtime state. Any attempt at modifying state
+ /// will result in the call failing.
+ #[cbor(optional, rename = "ro")]
+ pub read_only: bool,
+}
+
+impl Default for Call {
+ fn default() -> Self {
+ Self {
+ format: Default::default(),
+ method: Default::default(),
+ body: cbor::Value::Simple(cbor::SimpleValue::NullValue),
+ read_only: false,
+ }
+ }
+}
+
+/// Transaction authentication information.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct AuthInfo {
+ /// Transaction signer information.
+ #[cbor(rename = "si")]
+ pub signer_info: Vec<SignerInfo>,
+ /// Fee payment information.
+ pub fee: Fee,
+ /// Earliest round when the transaction is valid.
+ #[cbor(optional)]
+ pub not_before: Option<u64>,
+ /// Latest round when the transaction is valid.
+ #[cbor(optional)]
+ pub not_after: Option<u64>,
+}
+
+/// Transaction fee.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Fee {
+ /// Amount of base units paid as fee for transaction processing.
+ pub amount: token::BaseUnits,
+ /// Maximum amount of gas paid for.
+ #[cbor(optional)]
+ pub gas: u64,
+ /// Maximum amount of emitted consensus messages paid for. Zero means that up to the maximum
+ /// number of per-batch messages can be emitted.
+ #[cbor(optional)]
+ pub consensus_messages: u32,
+ /// Proxy which has authorized the fees to be paid.
+ #[cbor(optional)]
+ pub proxy: Option<FeeProxy>,
+}
+
+impl Fee {
+ /// Calculates gas price from fee amount and gas.
+ pub fn gas_price(&self) -> u128 {
+ self.amount
+ .amount()
+ .checked_div(self.gas.into())
+ .unwrap_or_default()
+ }
+}
+
+/// Information about a fee proxy.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct FeeProxy {
+ /// Module that will handle the proxy payment.
+ pub module: String,
+ /// Module-specific identifier that will handle fee payments for the transaction signer.
+ pub id: Vec<u8>,
+}
+
+/// A caller address.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub enum CallerAddress {
+ #[cbor(rename = "address")]
+ Address(Address),
+ #[cbor(rename = "eth_address")]
+ EthAddress([u8; 20]),
+}
+
+impl CallerAddress {
+ /// Derives the address.
+ pub fn address(&self) -> Address {
+ match self {
+ CallerAddress::Address(address) => *address,
+ CallerAddress::EthAddress(address) => Address::new(
+ address::ADDRESS_V0_SECP256K1ETH_CONTEXT,
+ address::ADDRESS_V0_VERSION,
+ address.as_ref(),
+ ),
+ }
+ }
+
+ /// Maps the caller address to one of the same type but with an all-zero address.
+ pub fn zeroized(&self) -> Self {
+ match self {
+ CallerAddress::Address(_) => CallerAddress::Address(Default::default()),
+ CallerAddress::EthAddress(_) => CallerAddress::EthAddress(Default::default()),
+ }
+ }
+}
+
+/// Common information that specifies an address as well as how to authenticate.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub enum AddressSpec {
+ /// For _signature_ authentication.
+ #[cbor(rename = "signature")]
+ Signature(SignatureAddressSpec),
+ /// For _multisig_ authentication.
+ #[cbor(rename = "multisig")]
+ Multisig(multisig::Config),
+
+ /// For internal child calls (cannot be serialized/deserialized).
+ #[cbor(skip)]
+ Internal(CallerAddress),
+}
+
+impl AddressSpec {
+ /// Returns the public key when the address spec represents a single public key.
+ pub fn public_key(&self) -> Option<PublicKey> {
+ match self {
+ AddressSpec::Signature(spec) => Some(spec.public_key()),
+ _ => None,
+ }
+ }
+
+ /// Derives the address.
+ pub fn address(&self) -> Address {
+ match self {
+ AddressSpec::Signature(spec) => Address::from_sigspec(spec),
+ AddressSpec::Multisig(config) => Address::from_multisig(config.clone()),
+ AddressSpec::Internal(caller) => caller.address(),
+ }
+ }
+
+ /// Derives the caller address.
+ pub fn caller_address(&self) -> CallerAddress {
+ match self {
+ AddressSpec::Signature(SignatureAddressSpec::Secp256k1Eth(pk)) => {
+ CallerAddress::EthAddress(pk.to_eth_address().try_into().unwrap())
+ }
+ AddressSpec::Internal(caller) => caller.clone(),
+ _ => CallerAddress::Address(self.address()),
+ }
+ }
+
+ /// Checks that the address specification and the authentication proof are acceptable.
+ /// Returns vectors of public keys and signatures for batch verification of included signatures.
+ pub fn batch(&self, auth_proof: &AuthProof) -> Result<(Vec<PublicKey>, Vec<Signature>), Error> {
+ match (self, auth_proof) {
+ (AddressSpec::Signature(spec), AuthProof::Signature(signature)) => {
+ Ok((vec![spec.public_key()], vec![signature.clone()]))
+ }
+ (AddressSpec::Multisig(config), AuthProof::Multisig(signature_set)) => Ok(config
+ .batch(signature_set)
+ .map_err(|e| Error::MalformedTransaction(e.into()))?),
+ (AddressSpec::Signature(_), AuthProof::Multisig(_)) => {
+ Err(Error::MalformedTransaction(anyhow!(
+ "transaction signer used a single signature, but auth proof was multisig"
+ )))
+ }
+ (AddressSpec::Multisig(_), AuthProof::Signature(_)) => {
+ Err(Error::MalformedTransaction(anyhow!(
+ "transaction signer used multisig, but auth proof was a single signature"
+ )))
+ }
+ (AddressSpec::Internal(_), _) => Err(Error::MalformedTransaction(anyhow!(
+ "transaction signer used internal address spec"
+ ))),
+ (_, AuthProof::Module(_)) => Err(Error::MalformedTransaction(anyhow!(
+ "module-controlled decoding flag in auth proof list"
+ ))),
+ (_, AuthProof::Invalid) => Err(Error::MalformedTransaction(anyhow!(
+ "invalid auth proof in list"
+ ))),
+ }
+ }
+}
+
+/// Transaction signer information.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct SignerInfo {
+ pub address_spec: AddressSpec,
+ pub nonce: u64,
+}
+
+impl SignerInfo {
+ /// Create a new signer info from a signature address specification and nonce.
+ pub fn new_sigspec(spec: SignatureAddressSpec, nonce: u64) -> Self {
+ Self {
+ address_spec: AddressSpec::Signature(spec),
+ nonce,
+ }
+ }
+
+ /// Create a new signer info from a multisig configuration and a nonce.
+ pub fn new_multisig(config: multisig::Config, nonce: u64) -> Self {
+ Self {
+ address_spec: AddressSpec::Multisig(config),
+ nonce,
+ }
+ }
+}
+
+/// Call result.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub enum CallResult {
+ #[cbor(rename = "ok")]
+ Ok(cbor::Value),
+
+ #[cbor(rename = "fail")]
+ Failed {
+ module: String,
+ code: u32,
+
+ #[cbor(optional)]
+ message: String,
+ },
+
+ #[cbor(rename = "unknown")]
+ Unknown(cbor::Value),
+}
+
+impl Default for CallResult {
+ fn default() -> Self {
+ Self::Unknown(cbor::Value::Simple(cbor::SimpleValue::NullValue))
+ }
+}
+
+impl CallResult {
+ /// Check whether the call result indicates a successful operation or not.
+ pub fn is_success(&self) -> bool {
+ !matches!(self, CallResult::Failed { .. })
+ }
+
+ /// Transforms `CallResult` into `anyhow::Result<cbor::Value>`, mapping `Ok(v)` and `Unknown(v)`
+ /// to `Ok(v)` and `Failed` to `Err`.
+ pub fn ok(self) -> anyhow::Result<cbor::Value> {
+ match self {
+ Self::Ok(v) | Self::Unknown(v) => Ok(v),
+ Self::Failed {
+ module,
+ code,
+ message,
+ } => Err(anyhow!(
+ "call failed: module={module} code={code}: {message}"
+ )),
+ }
+ }
+}
+
+#[cfg(any(test, feature = "test"))]
+impl CallResult {
+ pub fn unwrap(self) -> cbor::Value {
+ match self {
+ Self::Ok(v) | Self::Unknown(v) => v,
+ Self::Failed {
+ module,
+ code,
+ message,
+ } => panic!("{module} reported failure with code {code}: {message}"),
+ }
+ }
+
+ pub fn unwrap_failed(self) -> (String, u32) {
+ match self {
+ Self::Ok(_) | Self::Unknown(_) => panic!("call result indicates success"),
+ Self::Failed { module, code, .. } => (module, code),
+ }
+ }
+
+ pub fn into_call_result(self) -> Option<crate::module::CallResult> {
+ Some(match self {
+ Self::Ok(v) => crate::module::CallResult::Ok(v),
+ Self::Failed {
+ module,
+ code,
+ message,
+ } => crate::module::CallResult::Failed {
+ module,
+ code,
+ message,
+ },
+ Self::Unknown(_) => return None,
+ })
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use crate::types::token::{BaseUnits, Denomination};
+
+ use super::*;
+
+ #[test]
+ fn test_fee_gas_price() {
+ let fee = Fee::default();
+ assert_eq!(0, fee.gas_price(), "empty fee - gas price should be zero",);
+
+ let fee = Fee {
+ gas: 100,
+ ..Default::default()
+ };
+ assert_eq!(
+ 0,
+ fee.gas_price(),
+ "empty fee amount - gas price should be zero",
+ );
+
+ let fee = Fee {
+ amount: BaseUnits::new(1_000, Denomination::NATIVE),
+ gas: 0,
+ ..Default::default()
+ };
+ assert_eq!(0, fee.gas_price(), "empty fee 0 - gas price should be zero",);
+
+ let fee = Fee {
+ amount: BaseUnits::new(1_000, Denomination::NATIVE),
+ gas: 10_000,
+ ..Default::default()
+ };
+ assert_eq!(
+ 0,
+ fee.gas_price(),
+ "non empty fee - gas price should be zero"
+ );
+
+ let fee = Fee {
+ amount: BaseUnits::new(1_000, Denomination::NATIVE),
+ gas: 500,
+ ..Default::default()
+ };
+ assert_eq!(2, fee.gas_price(), "non empty fee - gas price should match");
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +
//! Gas metering instrumentation.
+use std::collections::BTreeMap;
+
+use walrus::{ir::*, FunctionBuilder, GlobalId, LocalFunction, Module};
+
+use crate::Error;
+
+/// Name of the exported global that holds the gas limit.
+pub const EXPORT_GAS_LIMIT: &str = "gas_limit";
+/// Name of the exported global that holds the gas limit exhausted flag.
+pub const EXPORT_GAS_LIMIT_EXHAUSTED: &str = "gas_limit_exhausted";
+
+/// Configures the gas limit on the given instance.
+pub fn set_gas_limit<C>(
+ instance: &wasm3::Instance<'_, '_, C>,
+ gas_limit: u64,
+) -> Result<(), Error> {
+ instance
+ .set_global(EXPORT_GAS_LIMIT, gas_limit)
+ .map_err(|err| Error::ExecutionFailed(err.into()))
+}
+
+/// Returns the remaining gas.
+pub fn get_remaining_gas<C>(instance: &wasm3::Instance<'_, '_, C>) -> u64 {
+ instance.get_global(EXPORT_GAS_LIMIT).unwrap_or_default()
+}
+
+/// Returns the amount of gas requested that was over the limit.
+pub fn get_exhausted_amount<C>(instance: &wasm3::Instance<'_, '_, C>) -> u64 {
+ instance
+ .get_global(EXPORT_GAS_LIMIT_EXHAUSTED)
+ .unwrap_or_default()
+}
+
+/// Attempts to use the given amount of gas.
+pub fn use_gas<C>(instance: &wasm3::Instance<'_, '_, C>, amount: u64) -> Result<(), wasm3::Trap> {
+ let gas_limit: u64 = instance
+ .get_global(EXPORT_GAS_LIMIT)
+ .map_err(|_| wasm3::Trap::Abort)?;
+ if gas_limit < amount {
+ let _ = instance.set_global(EXPORT_GAS_LIMIT_EXHAUSTED, amount);
+ return Err(wasm3::Trap::Abort);
+ }
+ instance
+ .set_global(EXPORT_GAS_LIMIT, gas_limit - amount)
+ .map_err(|_| wasm3::Trap::Abort)?;
+ Ok(())
+}
+
+/// Inject gas metering instrumentation into the module.
+pub fn transform(module: &mut Module) {
+ let gas_limit_global = module.globals.add_local(
+ walrus::ValType::I64,
+ true,
+ walrus::InitExpr::Value(Value::I64(0)),
+ );
+ let gas_limit_exhausted_global = module.globals.add_local(
+ walrus::ValType::I64,
+ true,
+ walrus::InitExpr::Value(Value::I64(0)),
+ );
+ module.exports.add(EXPORT_GAS_LIMIT, gas_limit_global);
+ module
+ .exports
+ .add(EXPORT_GAS_LIMIT_EXHAUSTED, gas_limit_exhausted_global);
+
+ for (_, func) in module.funcs.iter_local_mut() {
+ transform_function(func, gas_limit_global, gas_limit_exhausted_global);
+ }
+}
+
+/// Instruction cost function.
+fn instruction_cost(instr: &Instr) -> u64 {
+ match instr {
+ Instr::Loop(_) | Instr::Block(_) => 2,
+
+ Instr::LocalGet(_)
+ | Instr::LocalSet(_)
+ | Instr::LocalTee(_)
+ | Instr::GlobalGet(_)
+ | Instr::GlobalSet(_)
+ | Instr::Const(_) => 1,
+
+ Instr::Call(_) => 15,
+
+ Instr::CallIndirect(_) => 20,
+
+ Instr::Br(_) | Instr::BrIf(_) => 3,
+ Instr::BrTable(_) => 4,
+
+ Instr::Binop(op) => match op.op {
+ BinaryOp::I32Eq
+ | BinaryOp::I32Ne
+ | BinaryOp::I32LtS
+ | BinaryOp::I32LtU
+ | BinaryOp::I32GtS
+ | BinaryOp::I32GtU
+ | BinaryOp::I32LeS
+ | BinaryOp::I32LeU
+ | BinaryOp::I32GeS
+ | BinaryOp::I32GeU
+ | BinaryOp::I64Eq
+ | BinaryOp::I64Ne
+ | BinaryOp::I64LtS
+ | BinaryOp::I64LtU
+ | BinaryOp::I64GtS
+ | BinaryOp::I64GtU
+ | BinaryOp::I64LeS
+ | BinaryOp::I64LeU
+ | BinaryOp::I64GeS
+ | BinaryOp::I64GeU
+ | BinaryOp::I32Add
+ | BinaryOp::I32Sub
+ | BinaryOp::I32Mul
+ | BinaryOp::I32And
+ | BinaryOp::I32Or
+ | BinaryOp::I32Xor
+ | BinaryOp::I32Shl
+ | BinaryOp::I32ShrS
+ | BinaryOp::I32ShrU
+ | BinaryOp::I32Rotl
+ | BinaryOp::I32Rotr
+ | BinaryOp::I64Add
+ | BinaryOp::I64Sub
+ | BinaryOp::I64Mul
+ | BinaryOp::I64And
+ | BinaryOp::I64Or
+ | BinaryOp::I64Xor
+ | BinaryOp::I64Shl
+ | BinaryOp::I64ShrS
+ | BinaryOp::I64ShrU
+ | BinaryOp::I64Rotl
+ | BinaryOp::I64Rotr => 1,
+ BinaryOp::I32DivS
+ | BinaryOp::I32DivU
+ | BinaryOp::I32RemS
+ | BinaryOp::I32RemU
+ | BinaryOp::I64DivS
+ | BinaryOp::I64DivU
+ | BinaryOp::I64RemS
+ | BinaryOp::I64RemU => 4,
+ _ => 3,
+ },
+
+ Instr::Unop(op) => match op.op {
+ UnaryOp::I32Eqz
+ | UnaryOp::I32Clz
+ | UnaryOp::I32Ctz
+ | UnaryOp::I32Popcnt
+ | UnaryOp::I64Eqz
+ | UnaryOp::I64Clz
+ | UnaryOp::I64Ctz
+ | UnaryOp::I64Popcnt => 1,
+
+ _ => 3,
+ },
+
+ _ => 10,
+ }
+}
+
+/// A block of instructions which is metered.
+#[derive(Debug)]
+struct MeteredBlock {
+ /// Instruction sequence where metering code should be injected.
+ seq_id: InstrSeqId,
+ /// Start index of instruction within the instruction sequence before which the metering code
+ /// should be injected.
+ start_index: usize,
+ /// Instruction cost.
+ cost: u64,
+ /// Indication of whether the metered block can be merged in case instruction sequence and start
+ /// index match. In case the block cannot be merged this contains the index
+ merge_index: Option<usize>,
+}
+
+impl MeteredBlock {
+ fn new(seq_id: InstrSeqId, start_index: usize) -> Self {
+ Self {
+ seq_id,
+ start_index,
+ cost: 0,
+ merge_index: None,
+ }
+ }
+
+ /// Create a mergable version of this metered block with the given start index.
+ fn mergable(&self, start_index: usize) -> Self {
+ Self {
+ seq_id: self.seq_id,
+ start_index,
+ cost: 0,
+ merge_index: Some(self.start_index),
+ }
+ }
+}
+
+/// A map of finalized metered blocks.
+#[derive(Default)]
+struct MeteredBlocks {
+ blocks: BTreeMap<InstrSeqId, Vec<MeteredBlock>>,
+}
+
+impl MeteredBlocks {
+ /// Finalize the given metered block. This means that the cost associated with the block cannot
+ /// change anymore.
+ fn finalize(&mut self, block: MeteredBlock) {
+ if block.cost > 0 {
+ self.blocks.entry(block.seq_id).or_default().push(block);
+ }
+ }
+}
+
+fn determine_metered_blocks(func: &LocalFunction) -> BTreeMap<InstrSeqId, Vec<MeteredBlock>> {
+ // NOTE: This is based on walrus::ir::dfs_in_order but we need more information.
+
+ let mut blocks = MeteredBlocks::default();
+ let mut stack: Vec<(InstrSeqId, usize, MeteredBlock)> = vec![(
+ func.entry_block(), // Initial instruction sequence to visit.
+ 0, // Instruction offset within the sequence.
+ MeteredBlock::new(func.entry_block(), 0), // Initial metered block.
+ )];
+
+ 'traversing_blocks: while let Some((seq_id, index, mut metered_block)) = stack.pop() {
+ let seq = func.block(seq_id);
+
+ 'traversing_instrs: for (index, (instr, _)) in seq.instrs.iter().enumerate().skip(index) {
+ // NOTE: Current instruction is always included in the current metered block.
+ metered_block.cost += instruction_cost(instr);
+
+ // Determine whether we need to end/start a metered block.
+ match instr {
+ Instr::Block(Block { seq }) => {
+ // Do not start a new metered block as blocks are unconditional and metered
+ // blocks can encompass many of them to avoid injecting unnecessary
+ // instructions.
+ stack.push((seq_id, index + 1, metered_block.mergable(index + 1)));
+ stack.push((*seq, 0, metered_block));
+ continue 'traversing_blocks;
+ }
+
+ Instr::Loop(Loop { seq }) => {
+ // Finalize current metered block.
+ blocks.finalize(metered_block);
+ // Start a new metered block for remainder of block.
+ stack.push((seq_id, index + 1, MeteredBlock::new(seq_id, index + 1)));
+ // Start a new metered block for loop body.
+ stack.push((*seq, 0, MeteredBlock::new(*seq, 0)));
+ continue 'traversing_blocks;
+ }
+
+ Instr::IfElse(IfElse {
+ consequent,
+ alternative,
+ }) => {
+ // Finalize current metered block.
+ blocks.finalize(metered_block);
+
+ // Start a new metered block for remainder of block.
+ stack.push((seq_id, index + 1, MeteredBlock::new(seq_id, index + 1)));
+ // Start new metered blocks for alternative and consequent blocks.
+ stack.push((*alternative, 0, MeteredBlock::new(*alternative, 0)));
+ stack.push((*consequent, 0, MeteredBlock::new(*consequent, 0)));
+ continue 'traversing_blocks;
+ }
+
+ Instr::Call(_)
+ | Instr::CallIndirect(_)
+ | Instr::Br(_)
+ | Instr::BrIf(_)
+ | Instr::BrTable(_)
+ | Instr::Return(_) => {
+ // Finalize current metered block and start a new one for the remainder.
+ blocks.finalize(std::mem::replace(
+ &mut metered_block,
+ MeteredBlock::new(seq_id, index + 1),
+ ));
+ continue 'traversing_instrs;
+ }
+
+ _ => continue 'traversing_instrs,
+ }
+ }
+
+ // Check if we can merge the blocks.
+ if let Some((_, _, upper)) = stack.last_mut() {
+ match upper.merge_index {
+ Some(index)
+ if upper.seq_id == metered_block.seq_id
+ && index == metered_block.start_index =>
+ {
+ // Blocks can be merged, so overwrite upper.
+ *upper = metered_block;
+ continue 'traversing_blocks;
+ }
+ _ => {
+ // Blocks cannot be merged so treat as new block.
+ }
+ }
+ }
+
+ blocks.finalize(metered_block);
+ }
+
+ blocks.blocks
+}
+
+fn transform_function(
+ func: &mut LocalFunction,
+ gas_limit_global: GlobalId,
+ gas_limit_exhausted_global: GlobalId,
+) {
+ // First pass: determine where metering instructions should be injected.
+ let blocks = determine_metered_blocks(func);
+
+ // Second pass: actually emit metering instructions in correct positions.
+ let builder = func.builder_mut();
+ for (seq_id, blocks) in blocks {
+ let mut seq = builder.instr_seq(seq_id);
+ let instrs = seq.instrs_mut();
+
+ let original_instrs = std::mem::take(instrs);
+ let new_instrs_len = instrs.len() + METERING_INSTRUCTION_COUNT * blocks.len();
+ let mut new_instrs = Vec::with_capacity(new_instrs_len);
+
+ let mut block_iter = blocks.into_iter().peekable();
+ for (index, (instr, loc)) in original_instrs.into_iter().enumerate() {
+ match block_iter.peek() {
+ Some(block) if block.start_index == index => {
+ inject_metering(
+ builder,
+ &mut new_instrs,
+ block_iter.next().unwrap(),
+ gas_limit_global,
+ gas_limit_exhausted_global,
+ );
+ }
+ _ => {}
+ }
+
+ // Push original instruction.
+ new_instrs.push((instr, loc));
+ }
+
+ let mut seq = builder.instr_seq(seq_id);
+ let instrs = seq.instrs_mut();
+ *instrs = new_instrs;
+ }
+}
+
+/// Number of injected metering instructions (needed to calculate final instruction size).
+const METERING_INSTRUCTION_COUNT: usize = 8;
+
+fn inject_metering(
+ builder: &mut FunctionBuilder,
+ instrs: &mut Vec<(Instr, InstrLocId)>,
+ block: MeteredBlock,
+ gas_limit_global: GlobalId,
+ gas_limit_exhausted_global: GlobalId,
+) {
+ let mut builder = builder.dangling_instr_seq(None);
+ let seq = builder
+ // if unsigned(globals[gas_limit]) < unsigned(block.cost) { throw(); }
+ .global_get(gas_limit_global)
+ .i64_const(block.cost as i64)
+ .binop(BinaryOp::I64LtU)
+ .if_else(
+ None,
+ |then| {
+ then.i64_const(block.cost as i64)
+ .global_set(gas_limit_exhausted_global)
+ .unreachable();
+ },
+ |_else| {},
+ )
+ // globals[gas_limit] -= block.cost;
+ .global_get(gas_limit_global)
+ .i64_const(block.cost as i64)
+ .binop(BinaryOp::I64Sub)
+ .global_set(gas_limit_global);
+
+ instrs.append(seq.instrs_mut());
+}
+
+#[cfg(test)]
+mod test {
+ use pretty_assertions::assert_eq;
+
+ macro_rules! test_transform {
+ (name = $name:ident, source = $src:expr, expected = $expected:expr) => {
+ #[test]
+ fn $name() {
+ let src = wat::parse_str($src).unwrap();
+ let expected = wat::parse_str($expected).unwrap();
+
+ let mut result_module = walrus::ModuleConfig::new()
+ .generate_producers_section(false)
+ .parse(&src)
+ .unwrap();
+
+ super::transform(&mut result_module);
+
+ let mut expected_module = walrus::ModuleConfig::new()
+ .generate_producers_section(false)
+ .parse(&expected)
+ .unwrap();
+
+ let result_wasm = result_module.emit_wasm();
+ let expected_wasm = expected_module.emit_wasm();
+ let result = wasmprinter::print_bytes(&result_wasm).unwrap();
+ let expected = wasmprinter::print_bytes(&expected_wasm).unwrap();
+
+ assert_eq!(result, expected);
+ }
+ };
+ }
+
+ test_transform! {
+ name = simple,
+ source = r#"
+ (module
+ (func (result i32)
+ (i32.const 1)))
+ "#,
+ expected = r#"
+ (module
+ (func (result i32)
+ (if
+ (i64.lt_u
+ (global.get 0)
+ (i64.const 1))
+ (then
+ (global.set 1
+ (i64.const 1))
+ (unreachable)))
+ (global.set 0
+ (i64.sub
+ (global.get 0)
+ (i64.const 1)))
+ (i32.const 1))
+ (global (;0;) (mut i64) (i64.const 0))
+ (global (;1;) (mut i64) (i64.const 0))
+ (export "gas_limit" (global 0))
+ (export "gas_limit_exhausted" (global 1)))
+ "#
+ }
+
+ test_transform! {
+ name = nested_blocks,
+ source = r#"
+ (module
+ (func (result i32)
+ (block
+ (block
+ (block
+ (i32.const 1)
+ (drop))))
+ (i32.const 1)))
+ "#,
+ expected = r#"
+ (module
+ (func (result i32)
+ (if
+ (i64.lt_u
+ (global.get 0)
+ (i64.const 18))
+ (then
+ (global.set 1
+ (i64.const 18))
+ (unreachable)))
+ (global.set 0
+ (i64.sub
+ (global.get 0)
+ (i64.const 18)))
+ (block
+ (block
+ (block
+ (i32.const 1)
+ (drop))))
+ (i32.const 1))
+ (global (;0;) (mut i64) (i64.const 0))
+ (global (;1;) (mut i64) (i64.const 0))
+ (export "gas_limit" (global 0))
+ (export "gas_limit_exhausted" (global 1)))
+ "#
+ }
+
+ test_transform! {
+ name = nested_blocks_with_loop,
+ source = r#"
+ (module
+ (func (result i32)
+ (block
+ (block
+ (block
+ (i32.const 1)
+ (drop))
+ (loop
+ (i32.const 1)
+ (drop)
+ (i32.const 1)
+ (drop)
+ (br 0))))
+ (i32.const 1)))
+ "#,
+ expected = r#"
+ (module
+ (func (result i32)
+ (if
+ (i64.lt_u
+ (global.get 0)
+ (i64.const 19))
+ (then
+ (global.set 1
+ (i64.const 19))
+ (unreachable)))
+ (global.set 0
+ (i64.sub
+ (global.get 0)
+ (i64.const 19)))
+ (block
+ (block
+ (block
+ (i32.const 1)
+ (drop))
+ (loop
+ (if
+ (i64.lt_u
+ (global.get 0)
+ (i64.const 25))
+ (then
+ (global.set 1
+ (i64.const 25))
+ (unreachable)))
+ (global.set 0
+ (i64.sub
+ (global.get 0)
+ (i64.const 25)))
+ (i32.const 1)
+ (drop)
+ (i32.const 1)
+ (drop)
+ (br 0))))
+ (if
+ (i64.lt_u
+ (global.get 0)
+ (i64.const 1))
+ (then
+ (global.set 1
+ (i64.const 1))
+ (unreachable)))
+ (global.set 0
+ (i64.sub
+ (global.get 0)
+ (i64.const 1)))
+ (i32.const 1))
+ (global (;0;) (mut i64) (i64.const 0))
+ (global (;1;) (mut i64) (i64.const 0))
+ (export "gas_limit" (global 0))
+ (export "gas_limit_exhausted" (global 1)))
+ "#
+ }
+
+ test_transform! {
+ name = if_else,
+ source = r#"
+ (module
+ (func (result i32)
+ (i32.const 1)
+ (if
+ (then
+ (i32.const 1)
+ (drop)
+ (i32.const 1)
+ (drop))
+ (else
+ (i32.const 1)
+ (drop)))
+ (i32.const 1)))
+ "#,
+ expected = r#"
+ (module
+ (func (result i32)
+ (if
+ (i64.lt_u
+ (global.get 0)
+ (i64.const 11))
+ (then
+ (global.set 1
+ (i64.const 11))
+ (unreachable)))
+ (global.set 0
+ (i64.sub
+ (global.get 0)
+ (i64.const 11)))
+ (i32.const 1)
+ (if
+ (then
+ (if
+ (i64.lt_u
+ (global.get 0)
+ (i64.const 22))
+ (then
+ (global.set 1
+ (i64.const 22))
+ (unreachable)))
+ (global.set 0
+ (i64.sub
+ (global.get 0)
+ (i64.const 22)))
+ (i32.const 1)
+ (drop)
+ (i32.const 1)
+ (drop)
+ )
+ (else
+ (if
+ (i64.lt_u
+ (global.get 0)
+ (i64.const 11))
+ (then
+ (global.set 1
+ (i64.const 11))
+ (unreachable)))
+ (global.set 0
+ (i64.sub
+ (global.get 0)
+ (i64.const 11)))
+ (i32.const 1)
+ (drop)
+ )
+ )
+ (if
+ (i64.lt_u
+ (global.get 0)
+ (i64.const 1))
+ (then
+ (global.set 1
+ (i64.const 1))
+ (unreachable)))
+ (global.set 0
+ (i64.sub
+ (global.get 0)
+ (i64.const 1)))
+ (i32.const 1))
+ (global (;0;) (mut i64) (i64.const 0))
+ (global (;1;) (mut i64) (i64.const 0))
+ (export "gas_limit" (global 0))
+ (export "gas_limit_exhausted" (global 1)))
+ "#
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +
//! WASM ABI supported by the contracts module.
+use oasis_contract_sdk_types::{message::Reply, ExecutionOk};
+use oasis_runtime_sdk::{
+ context::Context,
+ types::{address::Address, token, transaction::CallFormat},
+};
+
+use super::{types, Error, Parameters};
+
+pub mod gas;
+pub mod oasis;
+
+/// Trait for any WASM ABI to implement.
+pub trait Abi<C: Context> {
+ /// Validate that the given WASM module conforms to the ABI.
+ fn validate(&self, module: &mut walrus::Module, params: &Parameters) -> Result<Info, Error>;
+
+ /// Link required functions into the WASM module instance.
+ fn link(
+ &self,
+ instance: &mut wasm3::Instance<'_, '_, ExecutionContext<'_, C>>,
+ ) -> Result<(), Error>;
+
+ /// Set the gas limit for any following executions.
+ ///
+ /// The specified gas limit should be in regular SDK gas units, not in WASM gas units. The ABI
+ /// should perform any necessary conversions if required.
+ fn set_gas_limit(
+ &self,
+ instance: &mut wasm3::Instance<'_, '_, ExecutionContext<'_, C>>,
+ gas_limit: u64,
+ ) -> Result<(), Error>;
+
+ /// Instantiate a contract.
+ fn instantiate<'ctx>(
+ &self,
+ ctx: &mut ExecutionContext<'ctx, C>,
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'ctx, C>>,
+ request: &[u8],
+ deposited_tokens: &[token::BaseUnits],
+ ) -> ExecutionResult;
+
+ /// Call a contract.
+ fn call<'ctx>(
+ &self,
+ ctx: &mut ExecutionContext<'ctx, C>,
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'ctx, C>>,
+ request: &[u8],
+ deposited_tokens: &[token::BaseUnits],
+ ) -> ExecutionResult;
+
+ /// Invoke the contract's reply handler.
+ fn handle_reply<'ctx>(
+ &self,
+ ctx: &mut ExecutionContext<'ctx, C>,
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'ctx, C>>,
+ reply: Reply,
+ ) -> ExecutionResult;
+
+ /// Invoke the contract's pre-upgrade handler.
+ fn pre_upgrade<'ctx>(
+ &self,
+ ctx: &mut ExecutionContext<'ctx, C>,
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'ctx, C>>,
+ request: &[u8],
+ deposited_tokens: &[token::BaseUnits],
+ ) -> ExecutionResult;
+
+ /// Invoke the contract's post-upgrade handler.
+ fn post_upgrade<'ctx>(
+ &self,
+ ctx: &mut ExecutionContext<'ctx, C>,
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'ctx, C>>,
+ request: &[u8],
+ deposited_tokens: &[token::BaseUnits],
+ ) -> ExecutionResult;
+
+ /// Query a contract.
+ fn query<'ctx>(
+ &self,
+ ctx: &mut ExecutionContext<'ctx, C>,
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'ctx, C>>,
+ request: &[u8],
+ ) -> ExecutionResult;
+}
+
+/// Additional information related to the ABI instance.
+pub struct Info {
+ /// ABI sub-version number.
+ pub abi_sv: u32,
+}
+
+/// Execution context.
+pub struct ExecutionContext<'ctx, C: Context> {
+ /// Transaction context.
+ pub tx_context: &'ctx C,
+ /// Contracts module parameters.
+ pub params: &'ctx Parameters,
+
+ /// Code information.
+ pub code_info: &'ctx types::Code,
+ /// Contract instance information.
+ pub instance_info: &'ctx types::Instance,
+ /// Gas limit for this contract execution.
+ pub gas_limit: u64,
+
+ /// Address of the caller.
+ pub caller_address: Address,
+ /// Whether the call is read-only and must not make any storage modifications.
+ pub read_only: bool,
+ /// Call format.
+ pub call_format: CallFormat,
+
+ /// Whether the execution has aborted with an error that should be propagated instead of just
+ /// using the generic "execution failed" error.
+ pub aborted: Option<Error>,
+}
+
+impl<'ctx, C: Context> ExecutionContext<'ctx, C> {
+ /// Create a new execution context.
+ #[allow(clippy::too_many_arguments)]
+ pub fn new(
+ params: &'ctx Parameters,
+ code_info: &'ctx types::Code,
+ instance_info: &'ctx types::Instance,
+ gas_limit: u64,
+ caller_address: Address,
+ read_only: bool,
+ call_format: CallFormat,
+ tx_context: &'ctx C,
+ ) -> Self {
+ Self {
+ tx_context,
+ params,
+ code_info,
+ instance_info,
+ gas_limit,
+ caller_address,
+ read_only,
+ call_format,
+ aborted: None,
+ }
+ }
+}
+
+/// Result of an execution that contains additional metadata like gas used.
+#[must_use]
+pub struct ExecutionResult {
+ /// Actual execution result.
+ pub inner: Result<ExecutionOk, Error>,
+ /// Amount of gas used by the execution.
+ pub gas_used: u64,
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +
//! Crypto function imports.
+use std::convert::TryInto;
+
+use oasis_contract_sdk_crypto as crypto;
+use oasis_contract_sdk_types::crypto::SignatureKind;
+use oasis_runtime_sdk::{context::Context, crypto::signature, state::CurrentState};
+
+use super::{memory::Region, OasisV1};
+use crate::{
+ abi::{gas, ExecutionContext},
+ Config, Error,
+};
+
+impl<Cfg: Config> OasisV1<Cfg> {
+ /// Link crypto helper functions.
+ pub fn link_crypto<C: Context>(
+ instance: &mut wasm3::Instance<'_, '_, ExecutionContext<'_, C>>,
+ ) -> Result<(), Error> {
+ // crypto.ecdsa_recover(input) -> response
+ let _ = instance.link_function(
+ "crypto",
+ "ecdsa_recover",
+ |ctx, request: ((u32, u32), (u32, u32))| -> Result<(), wasm3::Trap> {
+ // Make sure function was called in valid context.
+ let ec = ctx.context.ok_or(wasm3::Trap::Abort)?;
+
+ // Charge gas.
+ gas::use_gas(ctx.instance, ec.params.gas_costs.wasm_crypto_ecdsa_recover)?;
+
+ let rt = ctx.instance.runtime();
+ rt.try_with_memory(|mut memory| -> Result<_, wasm3::Trap> {
+ let input = Region::from_arg(request.0)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?
+ .to_vec();
+
+ let output: &mut [u8; 65] = Region::from_arg(request.1)
+ .as_slice_mut(&mut memory)
+ .map_err(|_| wasm3::Trap::Abort)?
+ .try_into()
+ .map_err(|_| wasm3::Trap::Abort)?;
+
+ match crypto::ecdsa::recover(&input) {
+ Ok(key) => output.copy_from_slice(&key),
+ Err(_) => output.iter_mut().for_each(|b| *b = 0),
+ }
+
+ Ok(())
+ })?
+ },
+ );
+
+ // crypto.signature_verify(public_key, context, message, signature) -> response
+ #[allow(clippy::type_complexity)]
+ let _ = instance.link_function(
+ "crypto",
+ "signature_verify",
+ |ctx,
+ (kind, key, context, message, signature): (
+ u32,
+ (u32, u32),
+ (u32, u32),
+ (u32, u32),
+ (u32, u32),
+ )|
+ -> Result<u32, wasm3::Trap> {
+ // Make sure function was called in valid context.
+ let ec = ctx.context.ok_or(wasm3::Trap::Abort)?;
+
+ // Validate message length.
+ if message.1 > ec.params.max_crypto_signature_verify_message_size_bytes {
+ ec.aborted = Some(Error::CryptoMsgTooLarge(
+ message.1,
+ ec.params.max_crypto_signature_verify_message_size_bytes,
+ ));
+ return Err(wasm3::Trap::Abort);
+ }
+
+ let kind: SignatureKind = kind.try_into().map_err(|_| wasm3::Trap::Abort)?;
+
+ // Charge gas.
+ let cost = match kind {
+ SignatureKind::Ed25519 => {
+ ec.params.gas_costs.wasm_crypto_signature_verify_ed25519
+ }
+ SignatureKind::Secp256k1 => {
+ ec.params.gas_costs.wasm_crypto_signature_verify_secp256k1
+ }
+ SignatureKind::Sr25519 => {
+ ec.params.gas_costs.wasm_crypto_signature_verify_sr25519
+ }
+ };
+ gas::use_gas(ctx.instance, cost)?;
+
+ let rt = ctx.instance.runtime();
+ rt.try_with_memory(|memory| -> Result<_, wasm3::Trap> {
+ let key = get_key(kind, key, &memory).inspect_err(|_| {
+ ec.aborted = Some(Error::CryptoMalformedPublicKey);
+ })?;
+ let message = Region::from_arg(message)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?;
+ let signature: signature::Signature = Region::from_arg(signature)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?
+ .to_vec()
+ .into();
+ if context.0 != 0 && context.1 != 0 && matches!(kind, SignatureKind::Sr25519) {
+ let context = Region::from_arg(context)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?;
+ Ok(1 - key.verify(context, message, &signature).is_ok() as u32)
+ } else {
+ Ok(1 - key.verify_raw(message, &signature).is_ok() as u32)
+ }
+ })?
+ },
+ );
+
+ // crypto.random_bytes(dst) -> bytes_written
+ let _ = instance.link_function(
+ "crypto",
+ "random_bytes",
+ |ctx,
+ ((pers_ptr, pers_len, dst_ptr, dst_len),): ((u32, u32, u32, u32),)|
+ -> Result<u32, wasm3::Trap> {
+ // Make sure function was called in valid context.
+ let ec = ctx.context.ok_or(wasm3::Trap::Abort)?;
+
+ let num_bytes = dst_len.min(1024 /* 1 KiB */);
+
+ // Charge gas.
+ let cost = ec
+ .params
+ .gas_costs
+ .wasm_crypto_random_bytes_byte
+ .checked_mul(num_bytes as u64 + pers_len as u64)
+ .and_then(|g| g.checked_add(ec.params.gas_costs.wasm_crypto_random_bytes_base))
+ .unwrap_or(u64::MAX); // This will certainly exhaust the gas limit.
+ gas::use_gas(ctx.instance, cost)?;
+
+ let rt = ctx.instance.runtime();
+ rt.try_with_memory(|mut memory| -> Result<_, wasm3::Trap> {
+ let pers = Region::from_arg((pers_ptr, pers_len))
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?;
+ let mut rng = CurrentState::with(|state| state.rng().fork(ec.tx_context, pers))
+ .map_err(|e| {
+ ec.aborted = Some(Error::ExecutionFailed(e.into()));
+ wasm3::Trap::Abort
+ })?;
+
+ let output = Region::from_arg((dst_ptr, num_bytes))
+ .as_slice_mut(&mut memory)
+ .map_err(|_| wasm3::Trap::Abort)?;
+ rand_core::RngCore::try_fill_bytes(&mut rng, output).map_err(|e| {
+ ec.aborted = Some(Error::ExecutionFailed(e.into()));
+ wasm3::Trap::Abort
+ })?;
+ Ok(num_bytes)
+ })?
+ },
+ );
+
+ // crypto.x25519_derive_symmetric(public_key, private_key) -> symmetric_key
+ #[allow(clippy::type_complexity)]
+ let _ = instance.link_function(
+ "crypto",
+ "x25519_derive_symmetric",
+ |ctx,
+ (public_key, private_key, output_key): ((u32, u32), (u32, u32), (u32, u32))|
+ -> Result<u32, wasm3::Trap> {
+ // Make sure function was called in valid context.
+ let ec = ctx.context.ok_or(wasm3::Trap::Abort)?;
+
+ gas::use_gas(
+ ctx.instance,
+ ec.params.gas_costs.wasm_crypto_x25519_derive_symmetric,
+ )?;
+
+ ctx.instance
+ .runtime()
+ .try_with_memory(|mut memory| -> Result<_, wasm3::Trap> {
+ let public = Region::from_arg(public_key)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?
+ .to_vec();
+ let private = Region::from_arg(private_key)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?
+ .to_vec();
+ let output: &mut [u8; crypto::x25519::KEY_SIZE] =
+ Region::from_arg(output_key)
+ .as_slice_mut(&mut memory)
+ .map_err(|_| wasm3::Trap::Abort)?
+ .try_into()
+ .map_err(|_| wasm3::Trap::Abort)?;
+ let derived =
+ crypto::x25519::derive_symmetric(&public, &private).map_err(|e| {
+ let err = match e {
+ crypto::x25519::Error::MalformedPublicKey => {
+ Error::CryptoMalformedPublicKey
+ }
+ crypto::x25519::Error::MalformedPrivateKey => {
+ Error::CryptoMalformedPrivateKey
+ }
+ crypto::x25519::Error::KeyDerivationFunctionFailure => {
+ Error::CryptoKeyDerivationFunctionFailure
+ }
+ };
+ ec.aborted = Some(err);
+ wasm3::Trap::Abort
+ })?;
+ if output.len() != derived.len() {
+ return Err(wasm3::Trap::Abort);
+ }
+ output.copy_from_slice(&derived);
+ Ok(0)
+ })?
+ },
+ );
+
+ #[allow(clippy::type_complexity)]
+ let deoxysii_factory =
+ |func: fn(&[u8], &[u8], &[u8], &[u8]) -> Result<Vec<u8>, crypto::deoxysii::Error>| {
+ move |ctx: wasm3::CallContext<'_, ExecutionContext<'_, C>>,
+ (key, nonce, message, additional_data): (
+ (u32, u32),
+ (u32, u32),
+ (u32, u32),
+ (u32, u32),
+ )|
+ -> Result<u32, wasm3::Trap> {
+ // Make sure function was called in valid context.
+ let ec = ctx.context.ok_or(wasm3::Trap::Abort)?;
+
+ gas::use_gas(
+ ctx.instance,
+ ec.params.gas_costs.wasm_crypto_deoxysii_base
+ + ec.params.gas_costs.wasm_crypto_deoxysii_byte
+ * (message.1 as u64 + additional_data.1 as u64),
+ )?;
+
+ let output = ctx.instance.runtime().try_with_memory(
+ |memory| -> Result<Option<Vec<u8>>, wasm3::Trap> {
+ let key = Region::from_arg(key)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?;
+ let nonce = Region::from_arg(nonce)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?;
+ let message = Region::from_arg(message)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?;
+ let additional_data = Region::from_arg(additional_data)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?;
+ func(key, nonce, message, additional_data)
+ .map(Some)
+ .or_else(|e| {
+ let err = match e {
+ crypto::deoxysii::Error::MalformedKey => {
+ Error::CryptoMalformedKey
+ }
+ crypto::deoxysii::Error::MalformedNonce => {
+ Error::CryptoMalformedNonce
+ }
+ crypto::deoxysii::Error::DecryptionFailed => {
+ return Ok(None);
+ }
+ };
+ ec.aborted = Some(err);
+ Err(wasm3::Trap::Abort)
+ })
+ },
+ )??;
+
+ if let Some(output) = output {
+ let output_region = Self::allocate_and_copy(ctx.instance, &output)?;
+ Self::allocate_region(ctx.instance, output_region).map_err(|e| e.into())
+ } else {
+ Ok(0)
+ }
+ }
+ };
+
+ // crypto.deoxysii_seal(key, nonce, plaintext_message, additional_data) -> encrypted_message
+ let _ = instance.link_function(
+ "crypto",
+ "deoxysii_seal",
+ deoxysii_factory(crypto::deoxysii::seal),
+ );
+
+ // crypto.deoxysii_open(key, nonce, encrypted_message, additional_data) -> plaintext_message
+ let _ = instance.link_function(
+ "crypto",
+ "deoxysii_open",
+ deoxysii_factory(crypto::deoxysii::open),
+ );
+
+ Ok(())
+ }
+}
+
+fn get_key(
+ kind: SignatureKind,
+ key: (u32, u32),
+ memory: &wasm3::Memory<'_>,
+) -> Result<signature::PublicKey, wasm3::Trap> {
+ let region = Region::from_arg(key)
+ .as_slice(memory)
+ .map_err(|_| wasm3::Trap::Abort)?;
+
+ match kind {
+ SignatureKind::Ed25519 => {
+ let ed25519 = signature::ed25519::PublicKey::from_bytes(region)
+ .map_err(|_| wasm3::Trap::Abort)?;
+ Ok(signature::PublicKey::Ed25519(ed25519))
+ }
+ SignatureKind::Secp256k1 => {
+ let secp256k1 = signature::secp256k1::PublicKey::from_bytes(region)
+ .map_err(|_| wasm3::Trap::Abort)?;
+ Ok(signature::PublicKey::Secp256k1(secp256k1))
+ }
+ SignatureKind::Sr25519 => {
+ let sr25519 = signature::sr25519::PublicKey::from_bytes(region)
+ .map_err(|_| wasm3::Trap::Abort)?;
+ Ok(signature::PublicKey::Sr25519(sr25519))
+ }
+ }
+}
+
+#[cfg(all(feature = "benchmarks", test))]
+mod test {
+ extern crate test;
+ use super::*;
+ use test::Bencher;
+
+ use k256::{
+ self,
+ ecdsa::{self, signature::Verifier as _},
+ };
+
+ // cargo build --target wasm32-unknown-unknown --release
+ const BENCH_CODE: &[u8] = include_bytes!(
+ "../../../../../../tests/contracts/bench/target/wasm32-unknown-unknown/release/bench.wasm"
+ );
+ const MESSAGE: &[u8] =
+ include_bytes!("../../../../../../tests/contracts/bench/data/message.txt");
+ const SIGNATURE: &[u8] =
+ include_bytes!("../../../../../../tests/contracts/bench/data/signature.bin");
+ const KEY: &[u8] = include_bytes!("../../../../../../tests/contracts/bench/data/key.bin");
+
+ fn verify_signature(message: &[u8], signature: &[u8], key: &[u8]) -> Result<(), ()> {
+ let key = k256::EncodedPoint::from_bytes(key).map_err(|_| ())?;
+ let sig = ecdsa::Signature::from_der(signature).map_err(|_| ())?;
+ let verifying_key = ecdsa::VerifyingKey::from_encoded_point(&key).map_err(|_| ())?;
+ verifying_key.verify(message, &sig).map_err(|_| ())?;
+ Ok(())
+ }
+
+ #[bench]
+ fn bench_crypto_nonwasm_verify(b: &mut Bencher) {
+ b.iter(|| {
+ verify_signature(MESSAGE, SIGNATURE, KEY).unwrap();
+ });
+ }
+
+ #[bench]
+ fn bench_crypto_nonwasm_recover(b: &mut Bencher) {
+ let input = hex::decode("ce0677bb30baa8cf067c88db9811f4333d131bf8bcf12fe7065d211dce97100890f27b8b488db00b00606796d2987f6a5f59ae62ea05effe84fef5b8b0e549984a691139ad57a3f0b906637673aa2f63d1f55cb1a69199d4009eea23ceaddc9301").unwrap();
+ b.iter(|| {
+ assert!(crypto::ecdsa::recover(&input).is_ok());
+ });
+ }
+
+ #[bench]
+ fn bench_crypto_nonwasm_x25519_derive(b: &mut Bencher) {
+ let public = <[u8; 32] as hex::FromHex>::from_hex(
+ "3046db3fa70ce605457dc47c48837ebd8bd0a26abfde5994d033e1ced68e2576",
+ )
+ .unwrap();
+ let private = <[u8; 32] as hex::FromHex>::from_hex(
+ "c07b151fbc1e7a11dff926111188f8d872f62eba0396da97c0a24adb75161750",
+ )
+ .unwrap();
+ b.iter(|| {
+ assert!(crypto::x25519::derive_symmetric(&public, &private).is_ok());
+ });
+ }
+
+ #[bench]
+ fn bench_crypto_nonwasm_deoxysii_seal_tiny(b: &mut Bencher) {
+ let key = <[u8; 32] as hex::FromHex>::from_hex(
+ "e69ac21066a8c2284e8fdc690e579af4513547b9b31dd144792c1904b45cf586",
+ )
+ .unwrap();
+ b.iter(|| {
+ assert!(crypto::deoxysii::seal(&key, b"0123456789abcde", b"b", b"").is_ok());
+ });
+ }
+
+ #[bench]
+ fn bench_crypto_nonwasm_deoxysii_seal_size1(b: &mut Bencher) {
+ let key = <[u8; 32] as hex::FromHex>::from_hex(
+ "e69ac21066a8c2284e8fdc690e579af4513547b9b31dd144792c1904b45cf586",
+ )
+ .unwrap();
+ b.iter(|| {
+ assert!(crypto::deoxysii::seal(&key, b"0123456789abcde", MESSAGE, b"").is_ok());
+ });
+ }
+
+ #[bench]
+ fn bench_crypto_nonwasm_deoxysii_seal_size2(b: &mut Bencher) {
+ let key = <[u8; 32] as hex::FromHex>::from_hex(
+ "e69ac21066a8c2284e8fdc690e579af4513547b9b31dd144792c1904b45cf586",
+ )
+ .unwrap();
+ let mut message = MESSAGE.to_vec();
+ message.extend_from_slice(MESSAGE);
+ b.iter(|| {
+ assert!(crypto::deoxysii::seal(&key, b"0123456789abcde", &message, b"").is_ok());
+ });
+ }
+
+ #[bench]
+ fn bench_crypto_called_from_wasm_included(b: &mut Bencher) {
+ let env =
+ wasm3::Environment::new().expect("creating a new wasm3 environment should succeed");
+ let module = env
+ .parse_module(BENCH_CODE)
+ .expect("parsing the code should succeed");
+ let rt: wasm3::Runtime<'_, wasm3::CallContext<'_, ()>> = env
+ .new_runtime(1 * 1024 * 1024, None)
+ .expect("creating a new wasm3 runtime should succeed");
+ let mut instance = rt
+ .load_module(module)
+ .expect("instance creation should succeed");
+ let _ = instance.link_function(
+ "bench",
+ "verify_signature",
+ |ctx,
+ (message, signature, key): ((u32, u32), (u32, u32), (u32, u32))|
+ -> Result<(), wasm3::Trap> {
+ ctx.instance
+ .runtime()
+ .try_with_memory(|memory| -> Result<_, wasm3::Trap> {
+ let message = Region::from_arg(message)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?;
+ let signature = Region::from_arg(signature)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?;
+ let key = Region::from_arg(key)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?;
+ verify_signature(message, signature, key)
+ .map_err(|_| wasm3::Trap::Abort)?;
+ Ok(())
+ })?
+ },
+ );
+ let func = instance
+ .find_function::<(), ()>("call_verification_included")
+ .expect("finding the entrypoint function should succeed");
+ b.iter(|| {
+ func.call(()).expect("function call should succeed");
+ });
+ }
+
+ #[bench]
+ fn bench_crypto_computed_in_wasm(b: &mut Bencher) {
+ let env =
+ wasm3::Environment::new().expect("creating a new wasm3 environment should succeed");
+ let module = env
+ .parse_module(BENCH_CODE)
+ .expect("parsing the code should succeed");
+ let rt: wasm3::Runtime<'_, wasm3::CallContext<'_, ()>> = env
+ .new_runtime(1 * 1024 * 1024, None)
+ .expect("creating a new wasm3 runtime should succeed");
+ let instance = rt
+ .load_module(module)
+ .expect("instance creation should succeed");
+ let func = instance
+ .find_function::<(), ()>("call_verification_internal")
+ .expect("finding the entrypoint function should succeed");
+ b.iter(|| {
+ func.call(()).expect("function call should succeed");
+ });
+ }
+
+ #[bench]
+ fn bench_crypto_computed_in_wasm_instrumented(_b: &mut Bencher) {
+ let mut module = walrus::ModuleConfig::new()
+ .generate_producers_section(false)
+ .parse(&BENCH_CODE)
+ .unwrap();
+ gas::transform(&mut module);
+ let new_code = module.emit_wasm();
+
+ let env =
+ wasm3::Environment::new().expect("creating a new wasm3 environment should succeed");
+ let module = env
+ .parse_module(&new_code)
+ .expect("parsing the code should succeed");
+ let rt: wasm3::Runtime<'_, wasm3::CallContext<'_, ()>> = env
+ .new_runtime(1 * 1024 * 1024, None)
+ .expect("creating a new wasm3 runtime should succeed");
+ let instance = rt
+ .load_module(module)
+ .expect("instance creation should succeed");
+ let initial_gas = 1_000_000_000_000u64;
+ instance
+ .set_global(gas::EXPORT_GAS_LIMIT, initial_gas)
+ .expect("setting gas limit should succeed");
+ let func = instance
+ .find_function::<(), ()>("call_verification_internal")
+ .expect("finding the entrypoint function should succeed");
+ func.call(()).expect("function call should succeed");
+
+ let gas_limit: u64 = instance
+ .get_global(gas::EXPORT_GAS_LIMIT)
+ .expect("getting gas limit global should succeed");
+ let gas_limit_exhausted: u64 = instance
+ .get_global(gas::EXPORT_GAS_LIMIT_EXHAUSTED)
+ .expect("getting gas limit exhausted global should succeed");
+ println!(
+ " signature verification done, gas remaining {} [used: {}, exhausted flag: {}]",
+ gas_limit,
+ initial_gas - gas_limit,
+ gas_limit_exhausted
+ );
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +
//! Environment query imports.
+use oasis_contract_sdk_types::{
+ env::{AccountsQuery, AccountsResponse, QueryRequest, QueryResponse},
+ InstanceId,
+};
+use oasis_runtime_sdk::{context::Context, modules::accounts::API as _, Runtime};
+
+use super::{memory::Region, OasisV1};
+use crate::{
+ abi::{gas, ExecutionContext},
+ types::Instance,
+ Config, Error,
+};
+
+impl<Cfg: Config> OasisV1<Cfg> {
+ /// Link environment query functions.
+ pub fn link_env<C: Context>(
+ instance: &mut wasm3::Instance<'_, '_, ExecutionContext<'_, C>>,
+ ) -> Result<(), Error> {
+ // env.query(request) -> response
+ let _ = instance.link_function(
+ "env",
+ "query",
+ |ctx, query: (u32, u32)| -> Result<u32, wasm3::Trap> {
+ // Make sure function was called in valid context.
+ let ec = ctx.context.ok_or(wasm3::Trap::Abort)?;
+
+ // Charge base gas amount.
+ gas::use_gas(ctx.instance, ec.params.gas_costs.wasm_env_query_base)?;
+
+ // Decode query argument.
+ let request: QueryRequest = ctx.instance.runtime().try_with_memory(
+ |memory| -> Result<_, wasm3::Trap> {
+ let query = Region::from_arg(query).as_slice(&memory)?;
+ if query.len() > ec.params.max_query_size_bytes as usize {
+ // TODO: Consider returning a nicer error message.
+ return Err(wasm3::Trap::Abort);
+ }
+
+ cbor::from_slice(query).map_err(|_| wasm3::Trap::Abort)
+ },
+ )??;
+
+ // Dispatch query.
+ let result = dispatch_query::<C>(ec.tx_context, request);
+
+ // Create new region by calling `allocate`.
+ //
+ // This makes sure that the call context is unset to avoid any potential issues
+ // with reentrancy as attempting to re-enter one of the linked function will fail.
+ Self::serialize_and_allocate_as_ptr(ctx.instance, result).map_err(|err| err.into())
+ },
+ );
+
+ // env.address_for_instance(instance_id, dst_region)
+ let _ = instance.link_function(
+ "env",
+ "address_for_instance",
+ |ctx, request: (u64, (u32, u32))| -> Result<(), wasm3::Trap> {
+ // Make sure function was called in valid context.
+ let ec = ctx.context.ok_or(wasm3::Trap::Abort)?;
+
+ // Charge base gas amount.
+ // TODO: probably separate gas cost.
+ gas::use_gas(ctx.instance, ec.params.gas_costs.wasm_env_query_base)?;
+
+ ctx.instance
+ .runtime()
+ .try_with_memory(|mut memory| -> Result<_, wasm3::Trap> {
+ let instance_id: InstanceId = request.0.into();
+ let dst = Region::from_arg(request.1).as_slice_mut(&mut memory)?;
+
+ let address = Instance::address_for(instance_id);
+
+ dst.copy_from_slice(address.as_ref());
+
+ Ok(())
+ })?
+ },
+ );
+
+ // env.debug_print(messsage, len)
+ #[cfg(feature = "debug-utils")]
+ let _ = instance.link_function(
+ "env",
+ "debug_print",
+ |ctx, request: (u32, u32)| -> Result<(), wasm3::Trap> {
+ ctx.instance
+ .runtime()
+ .try_with_memory(|memory| -> Result<_, wasm3::Trap> {
+ let msg_bytes = Region::from_arg(request).as_slice(&memory)?;
+ if let Ok(msg) = std::str::from_utf8(msg_bytes) {
+ eprintln!("{msg}");
+ }
+ Ok(())
+ })?
+ },
+ );
+
+ Ok(())
+ }
+}
+
+/// Perform environment query dispatch.
+fn dispatch_query<C: Context>(ctx: &C, query: QueryRequest) -> QueryResponse {
+ match query {
+ // Information about the current runtime block.
+ QueryRequest::BlockInfo => QueryResponse::BlockInfo {
+ round: ctx.runtime_header().round,
+ epoch: ctx.epoch(),
+ timestamp: ctx.runtime_header().timestamp,
+ },
+
+ // Accounts API queries.
+ QueryRequest::Accounts(query) => dispatch_accounts_query::<C>(ctx, query),
+
+ _ => QueryResponse::Error {
+ module: "".to_string(),
+ code: 1,
+ message: "query not supported".to_string(),
+ },
+ }
+}
+
+/// Perform accounts API query dispatch.
+fn dispatch_accounts_query<C: Context>(_ctx: &C, query: AccountsQuery) -> QueryResponse {
+ match query {
+ AccountsQuery::Balance {
+ address,
+ denomination,
+ } => {
+ let balance =
+ <C::Runtime as Runtime>::Accounts::get_balance(address.into(), denomination.into())
+ .unwrap_or_default();
+
+ AccountsResponse::Balance { balance }.into()
+ }
+
+ _ => QueryResponse::Error {
+ module: "".to_string(),
+ code: 1,
+ message: "query not supported".to_string(),
+ },
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +
//! Host-guest memory management.
+use std::convert::TryInto;
+
+use oasis_runtime_sdk::context::Context;
+
+use super::OasisV1;
+use crate::{abi::ExecutionContext, Config};
+
+/// Name of the memory allocation export.
+pub const EXPORT_ALLOCATE: &str = "allocate";
+/// Name of the memory deallocation export.
+pub const EXPORT_DEALLOCATE: &str = "deallocate";
+
+/// Memory region allocated inside the WASM instance, owned by the host.
+#[derive(Debug)]
+pub struct Region {
+ pub offset: usize,
+ pub length: usize,
+}
+
+#[derive(Debug, thiserror::Error)]
+pub enum RegionError {
+ #[error("region too big")]
+ RegionTooBig,
+ #[error("bad allocation function: {0}")]
+ BadAllocationFunction(#[source] anyhow::Error),
+ #[error("region allocation failed: {0}")]
+ AllocationFailed(#[source] anyhow::Error),
+ #[error("region size mismatch")]
+ SizeMismatch,
+ #[error("bad region pointer")]
+ BadPointer,
+}
+
+impl Region {
+ /// Converts a region to WASM function arguments.
+ pub fn to_arg(&self) -> (u32, u32) {
+ (self.offset as u32, self.length as u32)
+ }
+
+ /// Converts WASM arguments to a region.
+ pub fn from_arg(arg: (u32, u32)) -> Self {
+ Region {
+ offset: arg.0 as usize,
+ length: arg.1 as usize,
+ }
+ }
+
+ /// Dereferences a pointer to the region.
+ pub fn deref(memory: &wasm3::Memory<'_>, arg: u32) -> Result<Self, RegionError> {
+ let arg = arg as usize;
+
+ // Make sure the pointer is within WASM memory.
+ if arg + 8 > memory.size() {
+ return Err(RegionError::BadPointer);
+ }
+
+ // WASM uses little-endian encoding.
+ let dst = memory.as_slice();
+ let offset = u32::from_le_bytes(dst[arg..arg + 4].try_into().unwrap()) as usize;
+ let length = u32::from_le_bytes(dst[arg + 4..arg + 8].try_into().unwrap()) as usize;
+
+ // Ensure that the dereferenced region fits in WASM memory.
+ if offset + length > memory.size() {
+ return Err(RegionError::BadPointer);
+ }
+
+ Ok(Region { offset, length })
+ }
+
+ /// Copies slice content into a previously allocated WASM memory region.
+ pub fn copy_from_slice(
+ &self,
+ memory: &mut wasm3::Memory<'_>,
+ src: &[u8],
+ ) -> Result<(), RegionError> {
+ // Make sure the region is the right size.
+ if src.len() != self.length {
+ return Err(RegionError::SizeMismatch);
+ }
+
+ // Make sure the region fits in WASM memory.
+ if (self.offset + self.length) > memory.size() {
+ return Err(RegionError::BadPointer);
+ }
+
+ let dst = &mut memory.as_slice_mut()[self.offset..self.offset + self.length];
+ dst.copy_from_slice(src);
+
+ Ok(())
+ }
+
+ /// Returns the memory region as a slice.
+ pub fn as_slice<'mem>(
+ &self,
+ memory: &'mem wasm3::Memory<'_>,
+ ) -> Result<&'mem [u8], RegionError> {
+ // Make sure the region fits in WASM memory.
+ if (self.offset + self.length) > memory.size() {
+ return Err(RegionError::BadPointer);
+ }
+
+ Ok(&memory.as_slice()[self.offset..self.offset + self.length])
+ }
+
+ /// Returns the memory region as a mutable slice.
+ pub fn as_slice_mut<'mem>(
+ &self,
+ memory: &'mem mut wasm3::Memory<'_>,
+ ) -> Result<&'mem mut [u8], RegionError> {
+ // Make sure the region fits in WASM memory.
+ if (self.offset + self.length) > memory.size() {
+ return Err(RegionError::BadPointer);
+ }
+
+ Ok(&mut memory.as_slice_mut()[self.offset..self.offset + self.length])
+ }
+
+ /// Returns the serialized region.
+ pub fn serialize(&self) -> [u8; 8] {
+ let mut data = [0u8; 8];
+ data[..4].copy_from_slice(&(self.offset as u32).to_le_bytes());
+ data[4..].copy_from_slice(&(self.length as u32).to_le_bytes());
+ data
+ }
+}
+
+impl<Cfg: Config> OasisV1<Cfg> {
+ /// Allocates a chunk of memory inside the WASM instance.
+ pub fn allocate<C: Context>(
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'_, C>>,
+ length: usize,
+ ) -> Result<Region, RegionError> {
+ let length: u32 = length.try_into().map_err(|_| RegionError::RegionTooBig)?;
+
+ // Call the allocation function inside the WASM contract.
+ let func = instance
+ .find_function::<u32, u32>(EXPORT_ALLOCATE)
+ .map_err(|err| RegionError::BadAllocationFunction(err.into()))?;
+ let offset = func
+ .call(length) // Must be called without context.
+ .map_err(|err| RegionError::AllocationFailed(err.into()))?;
+
+ // Generate a region based on the returned value.
+ let region = Region {
+ offset: offset as usize,
+ length: length as usize,
+ };
+
+ // Validate returned region.
+ instance
+ .runtime()
+ .try_with_memory(|memory| -> Result<(), RegionError> {
+ // Make sure the region fits in WASM memory.
+ if (region.offset + region.length) > memory.size() {
+ return Err(RegionError::BadPointer);
+ }
+ Ok(())
+ })
+ .unwrap()?;
+
+ Ok(region)
+ }
+
+ /// Allocates a chunk of memory inside the WASM instance and copies the given slice into it.
+ pub fn allocate_and_copy<C: Context>(
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'_, C>>,
+ data: &[u8],
+ ) -> Result<Region, RegionError> {
+ // Allocate memory for the destination buffer.
+ let dst = Self::allocate(instance, data.len())?;
+ // Copy over data.
+ instance
+ .runtime()
+ .try_with_memory(|mut memory| -> Result<(), RegionError> {
+ dst.copy_from_slice(&mut memory, data)?;
+ Ok(())
+ })
+ .unwrap()?;
+
+ Ok(dst)
+ }
+
+ /// Serializes the given type into CBOR, allocates a chunk of memory inside the WASM instance
+ /// and copies the serialized data into it.
+ pub fn serialize_and_allocate<C, T>(
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'_, C>>,
+ data: T,
+ ) -> Result<Region, RegionError>
+ where
+ C: Context,
+ T: cbor::Encode,
+ {
+ let data = cbor::to_vec(data);
+ Self::allocate_and_copy(instance, &data)
+ }
+
+ /// Serializes the given type into CBOR, allocates a chunk of memory inside the WASM instance
+ /// and copies the region and serialized data into it. Returns a pointer to the serialized region.
+ ///
+ /// This method is useful when you need to a pointer to the region of the serialized data,
+ /// since it avoids an additional allocation for the region itself as it pre-allocates it with the data.
+ /// This is an optimized version of calling `serialize_and_allocate` followed by `allocate_region`
+ /// which does two separate allocations.
+ pub fn serialize_and_allocate_as_ptr<C, T>(
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'_, C>>,
+ data: T,
+ ) -> Result<u32, RegionError>
+ where
+ C: Context,
+ T: cbor::Encode,
+ {
+ let data = cbor::to_vec(data);
+ // Allocate enough for the data and the serialized region.
+ let outer = Self::allocate(instance, data.len() + 8)?;
+ // First 8 bytes are reserved for the region itself. Inner is the region
+ // for the actual data.
+ let inner = Region {
+ offset: outer.offset + 8,
+ length: outer.length - 8,
+ };
+
+ instance
+ .runtime()
+ .try_with_memory(|mut memory| -> Result<(), RegionError> {
+ inner.copy_from_slice(&mut memory, &data)?;
+
+ let dst = &mut memory.as_slice_mut()[outer.offset..outer.offset + 8];
+ dst.copy_from_slice(&inner.serialize());
+
+ Ok(())
+ })
+ .unwrap()?;
+
+ Ok(outer.offset as u32)
+ }
+
+ /// Allocates a region in WASM memory and returns a pointer to it.
+ pub fn allocate_region<C: Context>(
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'_, C>>,
+ region: Region,
+ ) -> Result<u32, RegionError> {
+ let data = region.serialize();
+
+ // Allocate memory for the destination buffer.
+ let dst = Self::allocate(instance, data.len())?;
+ instance
+ .runtime()
+ .try_with_memory(|mut memory| -> Result<(), RegionError> {
+ dst.copy_from_slice(&mut memory, &data)?;
+ Ok(())
+ })
+ .unwrap()?;
+
+ Ok(dst.offset as u32)
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +
//! The Oasis ABIs.
+use oasis_contract_sdk_types as contract_sdk;
+use oasis_runtime_sdk::{context::Context, modules::core, runtime::Runtime, types::token};
+
+use super::{gas, Abi, ExecutionContext, ExecutionResult, Info};
+use crate::{wasm::ContractError, Config, Error, Parameters};
+
+mod crypto;
+mod env;
+mod memory;
+mod storage;
+#[cfg(test)]
+mod test;
+mod validation;
+
+const EXPORT_INSTANTIATE: &str = "instantiate";
+const EXPORT_CALL: &str = "call";
+const EXPORT_HANDLE_REPLY: &str = "handle_reply";
+const EXPORT_PRE_UPGRADE: &str = "pre_upgrade";
+const EXPORT_POST_UPGRADE: &str = "post_upgrade";
+const EXPORT_QUERY: &str = "query";
+
+const GAS_SCALING_FACTOR: u64 = 1;
+
+/// The Oasis V1 ABI.
+pub struct OasisV1<Cfg: Config> {
+ _cfg: std::marker::PhantomData<Cfg>,
+}
+
+impl<Cfg: Config> OasisV1<Cfg> {
+ /// The set of required exports.
+ const REQUIRED_EXPORTS: &'static [&'static str] = &[
+ memory::EXPORT_ALLOCATE,
+ memory::EXPORT_DEALLOCATE,
+ EXPORT_INSTANTIATE,
+ EXPORT_CALL,
+ ];
+
+ /// The set of reserved exports.
+ const RESERVED_EXPORTS: &'static [&'static str] =
+ &[gas::EXPORT_GAS_LIMIT, gas::EXPORT_GAS_LIMIT_EXHAUSTED];
+
+ /// Create a new instance of the ABI.
+ pub fn new() -> Self {
+ Self {
+ _cfg: std::marker::PhantomData,
+ }
+ }
+
+ fn raw_call_with_request_context<'ctx, C: Context>(
+ ctx: &mut ExecutionContext<'ctx, C>,
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'ctx, C>>,
+ request: &[u8],
+ deposited_tokens: &[token::BaseUnits],
+ function_name: &str,
+ ) -> Result<contract_sdk::ExecutionOk, Error> {
+ // Allocate memory for context and request, copy serialized data into the region.
+ let mut ec = contract_sdk::ExecutionContext {
+ instance_id: ctx.instance_info.id,
+ instance_address: ctx.instance_info.address().into(),
+ caller_address: ctx.caller_address.into(),
+ deposited_tokens: deposited_tokens.iter().map(|b| b.into()).collect(),
+ ..Default::default()
+ };
+ if ctx.code_info.abi_sv >= 1 {
+ // Supports read only and call format flags.
+ ec.read_only = ctx.read_only;
+ ec.call_format = ctx.call_format.into();
+ }
+ let context_dst = Self::serialize_and_allocate(instance, ec)
+ .map_err(|err| Error::ExecutionFailed(err.into()))?;
+ let request_dst = Self::allocate_and_copy(instance, request)
+ .map_err(|err| Error::ExecutionFailed(err.into()))?;
+
+ // Call the corresponding function in the smart contract.
+ let result = {
+ // The high-level function signature of the WASM export is as follows:
+ //
+ // fn(ctx: &contract_sdk::ExecutionContext, request: &[u8]) -> contract_sdk::ExecutionResult
+ //
+ let func = instance
+ .find_function::<((u32, u32), (u32, u32)), u32>(function_name)
+ .map_err(|err| Error::ExecutionFailed(err.into()))?;
+ let result = func
+ .call_with_context(ctx, (context_dst.to_arg(), request_dst.to_arg()))
+ .map_err(|err| Error::ExecutionFailed(err.into()))?;
+ instance
+ .runtime()
+ .try_with_memory(|memory| -> Result<_, Error> {
+ memory::Region::deref(&memory, result)
+ .map_err(|err| Error::ExecutionFailed(err.into()))
+ })
+ .unwrap()?
+ };
+
+ // Enforce maximum result size limit before attempting to deserialize it.
+ if result.length as u32 > ctx.params.max_result_size_bytes {
+ return Err(Error::ResultTooLarge(
+ result.length as u32,
+ ctx.params.max_result_size_bytes,
+ ));
+ }
+
+ // Deserialize region into result structure.
+ let result: contract_sdk::ExecutionResult = instance
+ .runtime()
+ .try_with_memory(|memory| -> Result<_, Error> {
+ let data = result
+ .as_slice(&memory)
+ .map_err(|err| Error::ExecutionFailed(err.into()))?;
+
+ cbor::from_slice(data).map_err(|err| Error::ExecutionFailed(err.into()))
+ })
+ .unwrap()?;
+
+ match result {
+ contract_sdk::ExecutionResult::Ok(ok) => Ok(ok),
+ contract_sdk::ExecutionResult::Failed {
+ module,
+ code,
+ message,
+ } => Err(ContractError::new(ctx.instance_info.code_id, &module, code, &message).into()),
+ }
+ }
+
+ fn call_with_request_context<'ctx, C: Context>(
+ ctx: &mut ExecutionContext<'ctx, C>,
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'ctx, C>>,
+ request: &[u8],
+ deposited_tokens: &[token::BaseUnits],
+ function_name: &str,
+ ) -> ExecutionResult {
+ // Fetch initial gas counter value so we can determine how much gas was used.
+ let initial_gas = gas::get_remaining_gas(instance);
+
+ let inner = Self::raw_call_with_request_context(
+ ctx,
+ instance,
+ request,
+ deposited_tokens,
+ function_name,
+ )
+ .map_err(|err| {
+ // Check if an abort flag has been set and propagate the error.
+ if let Some(aborted) = ctx.aborted.take() {
+ return aborted;
+ }
+
+ // Check if call failed due to gas being exhausted and return a proper error.
+ let exhausted_gas = gas::get_exhausted_amount(instance);
+ if exhausted_gas != 0 {
+ // Compute how much gas was wanted.
+ let final_gas = gas::get_remaining_gas(instance);
+ let wanted_gas = initial_gas + exhausted_gas.saturating_sub(final_gas);
+ core::Error::out_of_gas::<<<C::Runtime as Runtime>::Core as core::API>::Config>(
+ initial_gas,
+ wanted_gas,
+ )
+ .into()
+ } else {
+ err
+ }
+ });
+
+ // Compute how much gas (in SDK units) was actually used.
+ let final_gas = gas::get_remaining_gas(instance);
+ let gas_used = initial_gas.saturating_sub(final_gas) / GAS_SCALING_FACTOR;
+
+ ExecutionResult { inner, gas_used }
+ }
+}
+
+impl<Cfg: Config, C: Context> Abi<C> for OasisV1<Cfg> {
+ fn validate(&self, module: &mut walrus::Module, params: &Parameters) -> Result<Info, Error> {
+ let info = self.validate_module(module, params)?;
+
+ // Add gas metering instrumentation.
+ gas::transform(module);
+
+ Ok(info)
+ }
+
+ fn link(
+ &self,
+ instance: &mut wasm3::Instance<'_, '_, ExecutionContext<'_, C>>,
+ ) -> Result<(), Error> {
+ // Storage imports.
+ Self::link_storage(instance)?;
+ // Environment imports.
+ Self::link_env(instance)?;
+ // Crypto imports.
+ Self::link_crypto(instance)?;
+
+ Ok(())
+ }
+
+ fn set_gas_limit(
+ &self,
+ instance: &mut wasm3::Instance<'_, '_, ExecutionContext<'_, C>>,
+ gas_limit: u64,
+ ) -> Result<(), Error> {
+ // Derive gas limit from remaining transaction gas based on a scaling factor.
+ let gas_limit = gas_limit.saturating_mul(GAS_SCALING_FACTOR);
+ gas::set_gas_limit(instance, gas_limit)?;
+
+ Ok(())
+ }
+
+ fn instantiate<'ctx>(
+ &self,
+ ctx: &mut ExecutionContext<'ctx, C>,
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'ctx, C>>,
+ request: &[u8],
+ deposited_tokens: &[token::BaseUnits],
+ ) -> ExecutionResult {
+ Self::call_with_request_context(
+ ctx,
+ instance,
+ request,
+ deposited_tokens,
+ EXPORT_INSTANTIATE,
+ )
+ }
+
+ fn call<'ctx>(
+ &self,
+ ctx: &mut ExecutionContext<'ctx, C>,
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'ctx, C>>,
+ request: &[u8],
+ deposited_tokens: &[token::BaseUnits],
+ ) -> ExecutionResult {
+ Self::call_with_request_context(ctx, instance, request, deposited_tokens, EXPORT_CALL)
+ }
+
+ fn handle_reply<'ctx>(
+ &self,
+ ctx: &mut ExecutionContext<'ctx, C>,
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'ctx, C>>,
+ reply: contract_sdk::message::Reply,
+ ) -> ExecutionResult {
+ Self::call_with_request_context(
+ ctx,
+ instance,
+ &cbor::to_vec(reply),
+ &[],
+ EXPORT_HANDLE_REPLY,
+ )
+ }
+
+ fn pre_upgrade<'ctx>(
+ &self,
+ ctx: &mut ExecutionContext<'ctx, C>,
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'ctx, C>>,
+ request: &[u8],
+ deposited_tokens: &[token::BaseUnits],
+ ) -> ExecutionResult {
+ Self::call_with_request_context(
+ ctx,
+ instance,
+ request,
+ deposited_tokens,
+ EXPORT_PRE_UPGRADE,
+ )
+ }
+
+ fn post_upgrade<'ctx>(
+ &self,
+ ctx: &mut ExecutionContext<'ctx, C>,
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'ctx, C>>,
+ request: &[u8],
+ deposited_tokens: &[token::BaseUnits],
+ ) -> ExecutionResult {
+ Self::call_with_request_context(
+ ctx,
+ instance,
+ request,
+ deposited_tokens,
+ EXPORT_POST_UPGRADE,
+ )
+ }
+
+ fn query<'ctx>(
+ &self,
+ ctx: &mut ExecutionContext<'ctx, C>,
+ instance: &wasm3::Instance<'_, '_, ExecutionContext<'ctx, C>>,
+ request: &[u8],
+ ) -> ExecutionResult {
+ Self::call_with_request_context(ctx, instance, request, &[], EXPORT_QUERY)
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +
//! Storage imports.
+use std::convert::TryInto;
+
+use oasis_contract_sdk_types::storage::StoreKind;
+use oasis_runtime_sdk::{context::Context, storage::Store};
+
+use super::{memory::Region, OasisV1};
+use crate::{
+ abi::{gas, ExecutionContext},
+ store, Config, Error,
+};
+
+impl<Cfg: Config> OasisV1<Cfg> {
+ /// Link storage functions.
+ pub fn link_storage<C: Context>(
+ instance: &mut wasm3::Instance<'_, '_, ExecutionContext<'_, C>>,
+ ) -> Result<(), Error> {
+ // storage.get(store, key) -> value
+ let _ = instance.link_function(
+ "storage",
+ "get",
+ |ctx, (store, key): (u32, (u32, u32))| -> Result<u32, wasm3::Trap> {
+ // Make sure function was called in valid context.
+ let ec = ctx.context.ok_or(wasm3::Trap::Abort)?;
+ let store_kind: StoreKind = store.try_into().map_err(|_| wasm3::Trap::Abort)?;
+
+ ensure_key_size(ec, key.1)?;
+
+ // Charge base gas amount plus size-dependent gas.
+ let total_gas = (|| {
+ let (base, key_base) = match store_kind {
+ StoreKind::Public => (
+ ec.params.gas_costs.wasm_public_storage_get_base,
+ ec.params.gas_costs.wasm_public_storage_key_byte,
+ ),
+ StoreKind::Confidential => (
+ ec.params.gas_costs.wasm_confidential_storage_get_base,
+ ec.params.gas_costs.wasm_confidential_storage_key_byte,
+ ),
+ };
+ let key = key_base.checked_mul(key.1.into())?;
+ let total = base.checked_add(key)?;
+ Some(total)
+ })()
+ .ok_or(wasm3::Trap::Abort)?;
+ gas::use_gas(ctx.instance, total_gas)?;
+
+ // Read from contract state.
+ let value = ctx.instance.runtime().try_with_memory(
+ |memory| -> Result<_, wasm3::Trap> {
+ let key = Region::from_arg(key).as_slice(&memory)?;
+ with_instance_store(ec, store_kind, |store| store.get(key))
+ },
+ )??;
+
+ let value = match value {
+ Some(value) => value,
+ None => return Ok(0),
+ };
+
+ // Charge gas for size of value.
+ let value_byte_cost = match store_kind {
+ StoreKind::Public => ec.params.gas_costs.wasm_public_storage_value_byte,
+ StoreKind::Confidential => {
+ ec.params.gas_costs.wasm_confidential_storage_value_byte
+ }
+ };
+ gas::use_gas(
+ ctx.instance,
+ value_byte_cost
+ .checked_mul(value.len().try_into()?)
+ .ok_or(wasm3::Trap::Abort)?,
+ )?;
+
+ // Create new region by calling `allocate`.
+ //
+ // This makes sure that the call context is unset to avoid any potential issues
+ // with reentrancy as attempting to re-enter one of the linked functions will fail.
+ let value_region = Self::allocate_and_copy(ctx.instance, &value)?;
+
+ // Return a pointer to the region.
+ Self::allocate_region(ctx.instance, value_region).map_err(|e| e.into())
+ },
+ );
+
+ // storage.insert(store, key, value)
+ let _ = instance.link_function(
+ "storage",
+ "insert",
+ |ctx, (store, key, value): (u32, (u32, u32), (u32, u32))| {
+ // Make sure function was called in valid context.
+ let ec = ctx.context.ok_or(wasm3::Trap::Abort)?;
+ let store_kind: StoreKind = store.try_into().map_err(|_| wasm3::Trap::Abort)?;
+
+ ensure_key_size(ec, key.1)?;
+ ensure_value_size(ec, value.1)?;
+
+ // Charge base gas amount plus size-dependent gas.
+ let total_gas = (|| {
+ let (base, key_base, value_base) = match store_kind {
+ StoreKind::Public => (
+ ec.params.gas_costs.wasm_public_storage_insert_base,
+ ec.params.gas_costs.wasm_public_storage_key_byte,
+ ec.params.gas_costs.wasm_public_storage_value_byte,
+ ),
+ StoreKind::Confidential => (
+ ec.params.gas_costs.wasm_confidential_storage_insert_base,
+ ec.params.gas_costs.wasm_confidential_storage_key_byte,
+ ec.params.gas_costs.wasm_confidential_storage_value_byte,
+ ),
+ };
+ let key = key_base.checked_mul(key.1.into())?;
+ let value = value_base.checked_mul(value.1.into())?;
+ let total = base.checked_add(key)?.checked_add(value)?;
+ Some(total)
+ })()
+ .ok_or(wasm3::Trap::Abort)?;
+ gas::use_gas(ctx.instance, total_gas)?;
+
+ // Insert into contract state.
+ ctx.instance
+ .runtime()
+ .try_with_memory(|memory| -> Result<(), wasm3::Trap> {
+ let key = Region::from_arg(key).as_slice(&memory)?;
+ let value = Region::from_arg(value).as_slice(&memory)?;
+ with_instance_store(ec, store_kind, |store| store.insert(key, value))
+ })??;
+
+ Ok(())
+ },
+ );
+
+ // storage.remove(store, key)
+ let _ = instance.link_function(
+ "storage",
+ "remove",
+ |ctx, (store, key): (u32, (u32, u32))| {
+ // Make sure function was called in valid context.
+ let ec = ctx.context.ok_or(wasm3::Trap::Abort)?;
+ let store_kind: StoreKind = store.try_into().map_err(|_| wasm3::Trap::Abort)?;
+
+ ensure_key_size(ec, key.1)?;
+
+ // Charge base gas amount plus size-dependent gas.
+ let total_gas = (|| {
+ let (base, key_base) = match store_kind {
+ StoreKind::Public => (
+ ec.params.gas_costs.wasm_public_storage_remove_base,
+ ec.params.gas_costs.wasm_public_storage_key_byte,
+ ),
+ StoreKind::Confidential => (
+ ec.params.gas_costs.wasm_confidential_storage_remove_base,
+ ec.params.gas_costs.wasm_confidential_storage_key_byte,
+ ),
+ };
+ let key = key_base.checked_mul(key.1.into())?;
+ let total = base.checked_add(key)?;
+ Some(total)
+ })()
+ .ok_or(wasm3::Trap::Abort)?;
+ gas::use_gas(ctx.instance, total_gas)?;
+
+ // Remove from contract state.
+ ctx.instance
+ .runtime()
+ .try_with_memory(|memory| -> Result<(), wasm3::Trap> {
+ let key = Region::from_arg(key).as_slice(&memory)?;
+ with_instance_store(ec, store_kind, |store| store.remove(key))
+ })??;
+
+ Ok(())
+ },
+ );
+
+ Ok(())
+ }
+}
+
+/// Run a closure with the contract instance store.
+fn with_instance_store<C, F, R>(
+ ec: &mut ExecutionContext<'_, C>,
+ store_kind: StoreKind,
+ f: F,
+) -> Result<R, wasm3::Trap>
+where
+ C: Context,
+ F: FnOnce(&mut dyn Store) -> R,
+{
+ store::with_instance_store(ec.tx_context, ec.instance_info, store_kind, |store| {
+ f(store)
+ })
+ .map_err(|err| {
+ // Propagate the underlying error.
+ ec.aborted = Some(err);
+ wasm3::Trap::Abort
+ })
+}
+
+/// Make sure that the key size is within the range specified in module parameters.
+fn ensure_key_size<C: Context>(
+ ec: &mut ExecutionContext<'_, C>,
+ size: u32,
+) -> Result<(), wasm3::Trap> {
+ if size > ec.params.max_storage_key_size_bytes {
+ ec.aborted = Some(Error::StorageKeyTooLarge(
+ size,
+ ec.params.max_storage_key_size_bytes,
+ ));
+ return Err(wasm3::Trap::Abort);
+ }
+ Ok(())
+}
+
+/// Make sure that the value size is within the range specified in module parameters.
+fn ensure_value_size<C: Context>(
+ ec: &mut ExecutionContext<'_, C>,
+ size: u32,
+) -> Result<(), wasm3::Trap> {
+ if size > ec.params.max_storage_value_size_bytes {
+ ec.aborted = Some(Error::StorageValueTooLarge(
+ size,
+ ec.params.max_storage_value_size_bytes,
+ ));
+ return Err(wasm3::Trap::Abort);
+ }
+ Ok(())
+}
+
+#[cfg(all(feature = "benchmarks", test))]
+mod bench {
+ extern crate test;
+ use super::*;
+ use std::{cell::RefCell, rc::Rc};
+ use test::Bencher;
+
+ use oasis_runtime_sdk::{context::Context, storage, testing::mock::Mock};
+
+ // cargo build --target wasm32-unknown-unknown --release
+ const BENCH_CODE: &[u8] = include_bytes!(
+ "../../../../../../tests/contracts/bench/target/wasm32-unknown-unknown/release/bench.wasm"
+ );
+
+ fn make_items(num: usize) -> Vec<(Vec<u8>, Vec<u8>)> {
+ let mut items = Vec::new();
+ for i in 0..num {
+ items.push((
+ format!("key{}", i).into_bytes(),
+ format!("value{}", i).into_bytes(),
+ ));
+ }
+ items
+ }
+
+ struct StoreContext<'a> {
+ store: Box<dyn storage::Store + 'a>,
+ }
+
+ #[bench]
+ fn bench_wasm_plain_get(b: &mut Bencher) {
+ // Set up storage stack and insert some items into it.
+ let mut mock = Mock::default();
+ let mut ctx = mock.create_ctx();
+ let inner = storage::PrefixStore::new(
+ storage::PrefixStore::new(
+ storage::PrefixStore::new(ctx.runtime_state(), "test module"),
+ "instance prefix",
+ ),
+ "type prefix",
+ );
+ let mut store_ctx = StoreContext {
+ store: Box::new(storage::HashedStore::<_, blake3::Hasher>::new(inner)),
+ };
+
+ let items = make_items(10_000);
+ for i in 0..10_000 {
+ let item = &items[i % items.len()];
+ store_ctx.store.insert(&item.0, &item.1);
+ }
+
+ // Set up wasm runtime.
+ let env =
+ wasm3::Environment::new().expect("creating a new wasm3 environment should succeed");
+ let module = env
+ .parse_module(BENCH_CODE)
+ .expect("parsing the code should succeed");
+ let rt: wasm3::Runtime<'_, StoreContext<'_>> = env
+ .new_runtime(1 * 1024 * 1024, None)
+ .expect("creating a new wasm3 runtime should succeed");
+ let mut instance = rt
+ .load_module(module)
+ .expect("instance creation should succeed");
+ let _ = instance.link_function(
+ "bench",
+ "plain_get",
+ |ctx, key: (u32, u32)| -> Result<u32, wasm3::Trap> {
+ let key = ctx.instance.runtime().try_with_memory(
+ |memory| -> Result<Vec<u8>, wasm3::Trap> {
+ Ok(Region::from_arg(key)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?
+ .into())
+ },
+ )??;
+ let store_ctx = ctx.context.ok_or(wasm3::Trap::Abort)?;
+ match store_ctx.store.get(&key) {
+ None => Ok(0),
+ Some(value) => {
+ let alloc = ctx
+ .instance
+ .find_function::<u32, u32>("alloc")
+ .expect("finding alloc function should succeed");
+ let val_len = value.len() as u32;
+ let target_offset = alloc
+ .call(val_len + std::mem::size_of::<u32>() as u32)
+ .expect("alloc should succeed")
+ as usize;
+
+ ctx.instance.runtime().try_with_memory(
+ |mut memory| -> Result<_, wasm3::Trap> {
+ let len_bytes = &mut memory.as_slice_mut()
+ [target_offset..target_offset + std::mem::size_of::<u32>()];
+ len_bytes.copy_from_slice(&val_len.to_le_bytes());
+
+ let val_start = target_offset + std::mem::size_of::<u32>();
+ let target =
+ &mut memory.as_slice_mut()[val_start..val_start + value.len()];
+ target.copy_from_slice(&value);
+ Ok(target_offset as u32)
+ },
+ )?
+ }
+ }
+ },
+ );
+ let func = instance
+ .find_function::<(), ()>("bench_storage_get")
+ .expect("finding the entrypoint function should succeed");
+ b.iter(|| {
+ func.call_with_context(&mut store_ctx, ())
+ .expect("function call should succeed");
+ });
+ }
+
+ #[bench]
+ fn bench_wasm_plain_insert(b: &mut Bencher) {
+ // Set up storage stack and insert some items into it.
+ let mut mock = Mock::default();
+ let mut ctx = mock.create_ctx();
+ let inner = storage::PrefixStore::new(
+ storage::PrefixStore::new(
+ storage::PrefixStore::new(ctx.runtime_state(), "test module"),
+ "instance prefix",
+ ),
+ "type prefix",
+ );
+ let mut store_ctx = StoreContext {
+ store: Box::new(storage::HashedStore::<_, blake3::Hasher>::new(inner)),
+ };
+
+ // Set up wasm runtime.
+ let env =
+ wasm3::Environment::new().expect("creating a new wasm3 environment should succeed");
+ let module = env
+ .parse_module(BENCH_CODE)
+ .expect("parsing the code should succeed");
+ let rt: wasm3::Runtime<'_, StoreContext<'_>> = env
+ .new_runtime(1 * 1024 * 1024, None)
+ .expect("creating a new wasm3 runtime should succeed");
+ let mut instance = rt
+ .load_module(module)
+ .expect("instance creation should succeed");
+ let _ = instance.link_function(
+ "bench",
+ "plain_insert",
+ |ctx, (key, value): ((u32, u32), (u32, u32))| -> Result<u32, wasm3::Trap> {
+ let key = ctx.instance.runtime().try_with_memory(
+ |memory| -> Result<Vec<u8>, wasm3::Trap> {
+ Ok(Region::from_arg(key)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?
+ .into())
+ },
+ )??;
+ let value = ctx.instance.runtime().try_with_memory(
+ |memory| -> Result<Vec<u8>, wasm3::Trap> {
+ Ok(Region::from_arg(value)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?
+ .into())
+ },
+ )??;
+ let store_ctx = ctx.context.ok_or(wasm3::Trap::Abort)?;
+ store_ctx.store.insert(&key, &value);
+ Ok(0)
+ },
+ );
+ let func = instance
+ .find_function::<u32, u32>("bench_storage_insert")
+ .expect("finding the entrypoint function should succeed");
+ let mut counter_base: u32 = 0;
+ b.iter(|| {
+ counter_base += func
+ .call_with_context(&mut store_ctx, counter_base)
+ .expect("function call should succeed");
+ });
+ }
+
+ #[bench]
+ fn bench_wasm_plain_remove(b: &mut Bencher) {
+ // Set up storage stack and insert some items into it.
+ let mut mock = Mock::default();
+ let mut ctx = mock.create_ctx();
+ let inner = storage::PrefixStore::new(
+ storage::PrefixStore::new(
+ storage::PrefixStore::new(ctx.runtime_state(), "test module"),
+ "instance prefix",
+ ),
+ "type prefix",
+ );
+ let mut store_ctx = StoreContext {
+ store: Box::new(storage::HashedStore::<_, blake3::Hasher>::new(inner)),
+ };
+
+ for i in 0..2_000_000 {
+ store_ctx.store.insert(
+ format!("key{}", i).as_bytes(),
+ format!("value{}", i).as_bytes(),
+ );
+ }
+
+ // Set up wasm runtime.
+ let env =
+ wasm3::Environment::new().expect("creating a new wasm3 environment should succeed");
+ let module = env
+ .parse_module(BENCH_CODE)
+ .expect("parsing the code should succeed");
+ let rt: wasm3::Runtime<'_, StoreContext<'_>> = env
+ .new_runtime(1 * 1024 * 1024, None)
+ .expect("creating a new wasm3 runtime should succeed");
+ let mut instance = rt
+ .load_module(module)
+ .expect("instance creation should succeed");
+ let _ = instance.link_function(
+ "bench",
+ "plain_remove",
+ |ctx, key: (u32, u32)| -> Result<u32, wasm3::Trap> {
+ let key = ctx.instance.runtime().try_with_memory(
+ |memory| -> Result<Vec<u8>, wasm3::Trap> {
+ Ok(Region::from_arg(key)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?
+ .into())
+ },
+ )??;
+ let store_ctx = ctx.context.ok_or(wasm3::Trap::Abort)?;
+ store_ctx.store.remove(&key);
+ Ok(0)
+ },
+ );
+ let func = instance
+ .find_function::<u32, u32>("bench_storage_remove")
+ .expect("finding the entrypoint function should succeed");
+ let mut counter_base: u32 = 0;
+ b.iter(|| {
+ counter_base += func
+ .call_with_context(&mut store_ctx, counter_base)
+ .expect("function call should succeed");
+ });
+ }
+
+ #[bench]
+ fn bench_nowasm_get(b: &mut Bencher) {
+ // Set up storage stack and insert some items into it.
+ let mut mock = Mock::default();
+ let mut ctx = mock.create_ctx();
+ let inner = storage::PrefixStore::new(
+ storage::PrefixStore::new(
+ storage::PrefixStore::new(ctx.runtime_state(), "test module"),
+ "instance prefix",
+ ),
+ "type prefix",
+ );
+ let mut store = Box::new(storage::HashedStore::<_, blake3::Hasher>::new(inner));
+
+ let items = make_items(10_000);
+ for i in 0..10_000 {
+ let item = &items[i % items.len()];
+ store.insert(&item.0, &item.1);
+ }
+ b.iter(move || {
+ for i in 0..5_000 {
+ let key = format!("key{}", i);
+ let exp_value = format!("value{}", i);
+ let value = store.get(key.as_bytes()).unwrap();
+ assert_eq!(exp_value.as_bytes(), value.as_slice());
+ }
+ });
+ }
+
+ #[bench]
+ fn bench_wasm_reach_gas_limit(_b: &mut Bencher) {
+ // Set up storage stack and insert some items into it.
+ let mut mock = Mock::default();
+ let mut ctx = mock.create_ctx();
+ let inner = storage::PrefixStore::new(
+ storage::PrefixStore::new(
+ storage::PrefixStore::new(ctx.runtime_state(), "test module"),
+ "instance prefix",
+ ),
+ "type prefix",
+ );
+ let mut store_ctx = StoreContext {
+ store: Box::new(storage::HashedStore::<_, blake3::Hasher>::new(inner)),
+ };
+
+ let params = crate::Parameters::default();
+ let params_cb = params.clone();
+
+ // Set up wasm runtime.
+ let mut module = walrus::ModuleConfig::new()
+ .generate_producers_section(false)
+ .parse(&BENCH_CODE)
+ .unwrap();
+ gas::transform(&mut module);
+ let instrumented_code = module.emit_wasm();
+ let env =
+ wasm3::Environment::new().expect("creating a new wasm3 environment should succeed");
+ let module = env
+ .parse_module(&instrumented_code)
+ .expect("parsing the code should succeed");
+ let rt: wasm3::Runtime<'_, StoreContext<'_>> = env
+ .new_runtime(1 * 1024 * 1024, None)
+ .expect("creating a new wasm3 runtime should succeed");
+ let mut instance = rt
+ .load_module(module)
+ .expect("instance creation should succeed");
+ let initial_gas: u64 = 1_000_000_000;
+ instance
+ .set_global(gas::EXPORT_GAS_LIMIT, initial_gas)
+ .expect("setting gas limit should succeed");
+
+ let bytes_written: Rc<RefCell<usize>> = Rc::new(RefCell::new(0));
+ let bytes_written_cb = bytes_written.clone();
+
+ let _ = instance.link_function(
+ "bench",
+ "plain_insert",
+ move |ctx, (key, value): ((u32, u32), (u32, u32))| -> Result<u32, wasm3::Trap> {
+ let key = ctx.instance.runtime().try_with_memory(
+ |memory| -> Result<Vec<u8>, wasm3::Trap> {
+ Ok(Region::from_arg(key)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?
+ .into())
+ },
+ )??;
+ let value = ctx.instance.runtime().try_with_memory(
+ |memory| -> Result<Vec<u8>, wasm3::Trap> {
+ Ok(Region::from_arg(value)
+ .as_slice(&memory)
+ .map_err(|_| wasm3::Trap::Abort)?
+ .into())
+ },
+ )??;
+
+ let total_gas = (|| {
+ let key_cost = params_cb
+ .gas_costs
+ .wasm_public_storage_key_byte
+ .checked_mul(key.len() as u64)?;
+ let value_cost = params_cb
+ .gas_costs
+ .wasm_public_storage_value_byte
+ .checked_mul(value.len() as u64)?;
+ let total = params_cb
+ .gas_costs
+ .wasm_public_storage_insert_base
+ .checked_add(key_cost)?
+ .checked_add(value_cost)?;
+ Some(total)
+ })()
+ .ok_or(wasm3::Trap::Abort)?;
+ gas::use_gas(ctx.instance, total_gas)?;
+
+ *bytes_written_cb.borrow_mut() += value.len();
+ let store_ctx = ctx.context.ok_or(wasm3::Trap::Abort)?;
+ store_ctx.store.insert(&key, &value);
+ Ok(0)
+ },
+ );
+ let func = instance
+ .find_function::<u32, u32>("bench_storage_gas_consumer")
+ .expect("finding the entrypoint function should succeed");
+ let _ = func.call_with_context(&mut store_ctx, params.max_storage_value_size_bytes as u32);
+ let gas_limit: u64 = instance
+ .get_global(gas::EXPORT_GAS_LIMIT)
+ .expect("getting gas limit global should succeed");
+ let gas_limit_exhausted: u64 = instance
+ .get_global(gas::EXPORT_GAS_LIMIT_EXHAUSTED)
+ .expect("getting gas limit exhausted global should succeed");
+ println!(
+ " storage waster: gas remaining {} [used: {}, exhausted flag: {}], value bytes written: {}",
+ gas_limit,
+ initial_gas - gas_limit,
+ gas_limit_exhausted,
+ *bytes_written.borrow()
+ );
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +
use std::collections::BTreeSet;
+
+use walrus::{
+ ir::{self, dfs_in_order, Value, Visitor},
+ Module, ValType,
+};
+
+use crate::{
+ abi::oasis::{Info, OasisV1},
+ Config, Error, Parameters,
+};
+
+const EXPORT_SUB_VERSION_PREFIX: &str = "__oasis_sv_";
+
+fn check_valtype_acceptable(ty: ValType) -> Result<(), Error> {
+ match ty {
+ ValType::F32 | ValType::F64 => Err(Error::ModuleUsesFloatingPoint),
+ _ => Ok(()),
+ }
+}
+
+struct FloatScanner(bool);
+
+impl<'instr> Visitor<'instr> for FloatScanner {
+ fn visit_const(&mut self, instr: &ir::Const) {
+ match instr.value {
+ Value::F32(_) | Value::F64(_) => self.0 = true,
+ _ => {}
+ }
+ }
+
+ fn visit_binop(&mut self, instr: &ir::Binop) {
+ use ir::BinaryOp::*;
+ match instr.op {
+ F32Eq
+ | F32Ne
+ | F32Lt
+ | F32Gt
+ | F32Le
+ | F32Ge
+ | F64Eq
+ | F64Ne
+ | F64Lt
+ | F64Gt
+ | F64Le
+ | F64Ge
+ | F32Add
+ | F32Sub
+ | F32Mul
+ | F32Div
+ | F32Min
+ | F32Max
+ | F32Copysign
+ | F64Add
+ | F64Sub
+ | F64Mul
+ | F64Div
+ | F64Min
+ | F64Max
+ | F64Copysign
+ | F32x4ReplaceLane { .. }
+ | F64x2ReplaceLane { .. }
+ | F32x4Eq
+ | F32x4Ne
+ | F32x4Lt
+ | F32x4Gt
+ | F32x4Le
+ | F32x4Ge
+ | F64x2Eq
+ | F64x2Ne
+ | F64x2Lt
+ | F64x2Gt
+ | F64x2Le
+ | F64x2Ge
+ | F32x4Add
+ | F32x4Sub
+ | F32x4Mul
+ | F32x4Div
+ | F32x4Min
+ | F32x4Max
+ | F32x4PMin
+ | F32x4PMax
+ | F64x2Add
+ | F64x2Sub
+ | F64x2Mul
+ | F64x2Div
+ | F64x2Min
+ | F64x2Max
+ | F64x2PMin
+ | F64x2PMax => self.0 = true,
+ I32Eq
+ | I32Ne
+ | I32LtS
+ | I32LtU
+ | I32GtS
+ | I32GtU
+ | I32LeS
+ | I32LeU
+ | I32GeS
+ | I32GeU
+ | I64Eq
+ | I64Ne
+ | I64LtS
+ | I64LtU
+ | I64GtS
+ | I64GtU
+ | I64LeS
+ | I64LeU
+ | I64GeS
+ | I64GeU
+ | I32Add
+ | I32Sub
+ | I32Mul
+ | I32DivS
+ | I32DivU
+ | I32RemS
+ | I32RemU
+ | I32And
+ | I32Or
+ | I32Xor
+ | I32Shl
+ | I32ShrS
+ | I32ShrU
+ | I32Rotl
+ | I32Rotr
+ | I64Add
+ | I64Sub
+ | I64Mul
+ | I64DivS
+ | I64DivU
+ | I64RemS
+ | I64RemU
+ | I64And
+ | I64Or
+ | I64Xor
+ | I64Shl
+ | I64ShrS
+ | I64ShrU
+ | I64Rotl
+ | I64Rotr
+ | I8x16ReplaceLane { .. }
+ | I16x8ReplaceLane { .. }
+ | I32x4ReplaceLane { .. }
+ | I64x2ReplaceLane { .. }
+ | I8x16Eq
+ | I8x16Ne
+ | I8x16LtS
+ | I8x16LtU
+ | I8x16GtS
+ | I8x16GtU
+ | I8x16LeS
+ | I8x16LeU
+ | I8x16GeS
+ | I8x16GeU
+ | I16x8Eq
+ | I16x8Ne
+ | I16x8LtS
+ | I16x8LtU
+ | I16x8GtS
+ | I16x8GtU
+ | I16x8LeS
+ | I16x8LeU
+ | I16x8GeS
+ | I16x8GeU
+ | I32x4Eq
+ | I32x4Ne
+ | I32x4LtS
+ | I32x4LtU
+ | I32x4GtS
+ | I32x4GtU
+ | I32x4LeS
+ | I32x4LeU
+ | I32x4GeS
+ | I32x4GeU
+ | I64x2Eq
+ | I64x2Ne
+ | I64x2LtS
+ | I64x2GtS
+ | I64x2LeS
+ | I64x2GeS
+ | V128And
+ | V128Or
+ | V128Xor
+ | V128AndNot
+ | I8x16Shl
+ | I8x16ShrS
+ | I8x16ShrU
+ | I8x16Add
+ | I8x16AddSatS
+ | I8x16AddSatU
+ | I8x16Sub
+ | I8x16SubSatS
+ | I8x16SubSatU
+ | I16x8Shl
+ | I16x8ShrS
+ | I16x8ShrU
+ | I16x8Add
+ | I16x8AddSatS
+ | I16x8AddSatU
+ | I16x8Sub
+ | I16x8SubSatS
+ | I16x8SubSatU
+ | I16x8Mul
+ | I32x4Shl
+ | I32x4ShrS
+ | I32x4ShrU
+ | I32x4Add
+ | I32x4Sub
+ | I32x4Mul
+ | I64x2Shl
+ | I64x2ShrS
+ | I64x2ShrU
+ | I64x2Add
+ | I64x2Sub
+ | I64x2Mul
+ | I8x16NarrowI16x8S
+ | I8x16NarrowI16x8U
+ | I16x8NarrowI32x4S
+ | I16x8NarrowI32x4U
+ | I8x16RoundingAverageU
+ | I16x8RoundingAverageU
+ | I8x16MinS
+ | I8x16MinU
+ | I8x16MaxS
+ | I8x16MaxU
+ | I16x8MinS
+ | I16x8MinU
+ | I16x8MaxS
+ | I16x8MaxU
+ | I32x4MinS
+ | I32x4MinU
+ | I32x4MaxS
+ | I32x4MaxU
+ | I32x4DotI16x8S
+ | I16x8Q15MulrSatS
+ | I16x8ExtMulLowI8x16S
+ | I16x8ExtMulHighI8x16S
+ | I16x8ExtMulLowI8x16U
+ | I16x8ExtMulHighI8x16U
+ | I32x4ExtMulLowI16x8S
+ | I32x4ExtMulHighI16x8S
+ | I32x4ExtMulLowI16x8U
+ | I32x4ExtMulHighI16x8U
+ | I64x2ExtMulLowI32x4S
+ | I64x2ExtMulHighI32x4S
+ | I64x2ExtMulLowI32x4U
+ | I64x2ExtMulHighI32x4U => {
+ // Ignore these. They're all listed so we don't need to use
+ // the catch-all arm and miss any future additions.
+ }
+ }
+ }
+
+ fn visit_unop(&mut self, instr: &ir::Unop) {
+ use ir::UnaryOp::*;
+ match instr.op {
+ F32Abs
+ | F32Neg
+ | F32Ceil
+ | F32Floor
+ | F32Trunc
+ | F32Nearest
+ | F32Sqrt
+ | F64Abs
+ | F64Neg
+ | F64Ceil
+ | F64Floor
+ | F64Trunc
+ | F64Nearest
+ | F64Sqrt
+ | I32TruncSF32
+ | I32TruncUF32
+ | I32TruncSF64
+ | I32TruncUF64
+ | I64TruncSF32
+ | I64TruncUF32
+ | I64TruncSF64
+ | I64TruncUF64
+ | F32ConvertSI32
+ | F32ConvertUI32
+ | F32ConvertSI64
+ | F32ConvertUI64
+ | F32DemoteF64
+ | F64ConvertSI32
+ | F64ConvertUI32
+ | F64ConvertSI64
+ | F64ConvertUI64
+ | F64PromoteF32
+ | I32ReinterpretF32
+ | I64ReinterpretF64
+ | F32ReinterpretI32
+ | F64ReinterpretI64
+ | F32x4Splat
+ | F32x4ExtractLane { .. }
+ | F64x2Splat
+ | F64x2ExtractLane { .. }
+ | F32x4Abs
+ | F32x4Neg
+ | F32x4Sqrt
+ | F32x4Ceil
+ | F32x4Floor
+ | F32x4Trunc
+ | F32x4Nearest
+ | F64x2Abs
+ | F64x2Neg
+ | F64x2Sqrt
+ | F64x2Ceil
+ | F64x2Floor
+ | F64x2Trunc
+ | F64x2Nearest
+ | I32x4TruncSatF64x2SZero
+ | I32x4TruncSatF64x2UZero
+ | F64x2ConvertLowI32x4S
+ | F64x2ConvertLowI32x4U
+ | F32x4DemoteF64x2Zero
+ | F64x2PromoteLowF32x4
+ | I32x4TruncSatF32x4S
+ | I32x4TruncSatF32x4U
+ | F32x4ConvertI32x4S
+ | F32x4ConvertI32x4U
+ | I32TruncSSatF32
+ | I32TruncUSatF32
+ | I32TruncSSatF64
+ | I32TruncUSatF64
+ | I64TruncSSatF32
+ | I64TruncUSatF32
+ | I64TruncSSatF64
+ | I64TruncUSatF64 => self.0 = true,
+ I32Eqz
+ | I32Clz
+ | I32Ctz
+ | I32Popcnt
+ | I64Eqz
+ | I64Clz
+ | I64Ctz
+ | I64Popcnt
+ | I32WrapI64
+ | I64ExtendSI32
+ | I64ExtendUI32
+ | I32Extend8S
+ | I32Extend16S
+ | I64Extend8S
+ | I64Extend16S
+ | I64Extend32S
+ | I8x16Splat
+ | I8x16ExtractLaneS { .. }
+ | I8x16ExtractLaneU { .. }
+ | I16x8Splat
+ | I16x8ExtractLaneS { .. }
+ | I16x8ExtractLaneU { .. }
+ | I32x4Splat
+ | I32x4ExtractLane { .. }
+ | I64x2Splat
+ | I64x2ExtractLane { .. }
+ | V128Not
+ | V128AnyTrue
+ | I8x16Abs
+ | I8x16Popcnt
+ | I8x16Neg
+ | I8x16AllTrue
+ | I8x16Bitmask
+ | I16x8Abs
+ | I16x8Neg
+ | I16x8AllTrue
+ | I16x8Bitmask
+ | I32x4Abs
+ | I32x4Neg
+ | I32x4AllTrue
+ | I32x4Bitmask
+ | I64x2Abs
+ | I64x2Neg
+ | I64x2AllTrue
+ | I64x2Bitmask
+ | I16x8ExtAddPairwiseI8x16S
+ | I16x8ExtAddPairwiseI8x16U
+ | I32x4ExtAddPairwiseI16x8S
+ | I32x4ExtAddPairwiseI16x8U
+ | I64x2ExtendLowI32x4S
+ | I64x2ExtendHighI32x4S
+ | I64x2ExtendLowI32x4U
+ | I64x2ExtendHighI32x4U
+ | I16x8WidenLowI8x16S
+ | I16x8WidenLowI8x16U
+ | I16x8WidenHighI8x16S
+ | I16x8WidenHighI8x16U
+ | I32x4WidenLowI16x8S
+ | I32x4WidenLowI16x8U
+ | I32x4WidenHighI16x8S
+ | I32x4WidenHighI16x8U => {
+ // Ignore these. They're all listed so we don't need to use
+ // the catch-all arm and miss any future additions.
+ }
+ }
+ }
+
+ fn visit_load(&mut self, instr: &ir::Load) {
+ match instr.kind {
+ ir::LoadKind::F32 | ir::LoadKind::F64 => self.0 = true,
+ _ => {}
+ }
+ }
+
+ fn visit_store(&mut self, instr: &ir::Store) {
+ match instr.kind {
+ ir::StoreKind::F32 | ir::StoreKind::F64 => self.0 = true,
+ _ => {}
+ }
+ }
+}
+
+impl<Cfg: Config> OasisV1<Cfg> {
+ pub(super) fn validate_module(
+ &self,
+ module: &Module,
+ params: &Parameters,
+ ) -> Result<Info, Error> {
+ // Verify that all required exports are there.
+ let exports: BTreeSet<&str> = module
+ .exports
+ .iter()
+ .map(|export| export.name.as_str())
+ .collect();
+ for required in Self::REQUIRED_EXPORTS {
+ if !exports.contains(required) {
+ return Err(Error::CodeMissingRequiredExport(required.to_string()));
+ }
+ }
+
+ for reserved in Self::RESERVED_EXPORTS {
+ if exports.contains(reserved) {
+ return Err(Error::CodeDeclaresReservedExport(reserved.to_string()));
+ }
+ }
+
+ // Determine supported ABI sub-version.
+ let sv_exports: Vec<_> = exports
+ .iter()
+ .filter(|export| export.starts_with(EXPORT_SUB_VERSION_PREFIX))
+ .collect();
+ let abi_sv = match sv_exports[..] {
+ [] => {
+ // No versions, this is v0.
+ 0
+ }
+ [sv] => {
+ // A single version, parse which one.
+ sv.strip_prefix(EXPORT_SUB_VERSION_PREFIX)
+ .ok_or(Error::CodeMalformed)?
+ .parse::<u32>()
+ .map_err(|_| Error::CodeMalformed)?
+ }
+ _ => {
+ // Multiple versions.
+ return Err(Error::CodeDeclaresMultipleSubVersions);
+ }
+ };
+
+ // Verify that there is no start function defined.
+ if module.start.is_some() {
+ return Err(Error::CodeDeclaresStartFunction);
+ }
+
+ // Verify that there is at most one memory defined.
+ if module.memories.iter().count() > 1 {
+ return Err(Error::CodeDeclaresTooManyMemories);
+ }
+
+ // Verify that the code doesn't use any floating point instructions.
+ let mut function_count = 0u32;
+ for func in module.functions() {
+ let func_type = module.types.get(func.ty());
+ for val_type in func_type.params().iter().chain(func_type.results().iter()) {
+ check_valtype_acceptable(*val_type)?;
+ }
+ if let walrus::FunctionKind::Local(local) = &func.kind {
+ function_count += 1;
+ if function_count > params.max_wasm_functions {
+ return Err(Error::CodeDeclaresTooManyFunctions);
+ }
+ let mut scanner = FloatScanner(false);
+ dfs_in_order(&mut scanner, local, local.entry_block());
+ if scanner.0 {
+ return Err(Error::ModuleUsesFloatingPoint);
+ }
+ }
+ }
+
+ // ... or tables with floating point elements.
+ for table in module.tables.iter() {
+ check_valtype_acceptable(table.element_ty)?;
+ }
+
+ // ... or floating point elements.
+ for element in module.elements.iter() {
+ check_valtype_acceptable(element.ty)?;
+ }
+
+ // ... or floating point globals.
+ for global in module.globals.iter() {
+ check_valtype_acceptable(global.ty)?;
+ }
+
+ // ... just don't think about floats in any way.
+ let mut local_count = 0u32;
+ for local in module.locals.iter() {
+ local_count += 1;
+ if local_count > params.max_wasm_locals {
+ return Err(Error::CodeDeclaresTooManyLocals);
+ }
+ check_valtype_acceptable(local.ty())?;
+ }
+
+ Ok(Info { abi_sv })
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +
//! Code caching and storage.
+use std::{
+ io::{Read, Write},
+ num::NonZeroUsize,
+ sync::Mutex,
+};
+
+use once_cell::sync::Lazy;
+
+use oasis_runtime_sdk::{
+ core::common::crypto::hash::Hash,
+ state::CurrentState,
+ storage::{self, Store},
+};
+
+use crate::{state, types, Config, Error, Module, MODULE_NAME};
+
+/// A global in-memory LRU cache of code instances.
+static CODE_CACHE: Lazy<Mutex<lru::LruCache<Hash, Vec<u8>>>> =
+ Lazy::new(|| Mutex::new(lru::LruCache::new(NonZeroUsize::new(128).unwrap())));
+
+impl<Cfg: Config> Module<Cfg> {
+ /// Loads code with the specified code identifier.
+ pub fn load_code(code_info: &types::Code) -> Result<Vec<u8>, Error> {
+ let mut cache = CODE_CACHE.lock().unwrap();
+ if let Some(code) = cache.get(&code_info.hash) {
+ return Ok(code.clone());
+ }
+
+ // TODO: Support local untrusted cache to avoid storage queries.
+ let code = CurrentState::with_store(|store| {
+ let mut store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let code_store = storage::PrefixStore::new(&mut store, &state::CODE);
+ code_store
+ .get(&code_info.id.to_storage_key())
+ .ok_or_else(|| Error::CodeNotFound(code_info.id.as_u64()))
+ })?;
+
+ // Decompress code.
+ let mut output = Vec::with_capacity(code.len());
+ let mut decoder = snap::read::FrameDecoder::new(code.as_slice());
+ decoder.read_to_end(&mut output).unwrap();
+
+ // Cache uncompressed code for later use.
+ cache.put(code_info.hash, output.clone());
+
+ Ok(output)
+ }
+
+ /// Stores code with the specified code identifier.
+ pub fn store_code(code_info: &types::Code, code: &[u8]) -> Result<(), Error> {
+ // If the code is currently cached replace it, otherwise don't do anything.
+ let mut cache = CODE_CACHE.lock().unwrap();
+ if cache.contains(&code_info.hash) {
+ cache.put(code_info.hash, code.to_vec());
+ }
+
+ // Compress code before storing it in storage.
+ let mut output = Vec::with_capacity(code.len() << 3);
+ let mut encoder = snap::write::FrameEncoder::new(&mut output);
+ encoder.write_all(code).unwrap();
+ drop(encoder); // Make sure data is flushed.
+
+ CurrentState::with_store(|store| {
+ let mut store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut code_store = storage::PrefixStore::new(&mut store, &state::CODE);
+ code_store.insert(&code_info.id.to_storage_key(), &output);
+ });
+
+ Ok(())
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +626 +627 +628 +629 +630 +631 +632 +633 +634 +635 +636 +637 +638 +639 +640 +641 +642 +643 +644 +645 +646 +647 +648 +649 +650 +651 +652 +653 +654 +655 +656 +657 +658 +659 +660 +661 +662 +663 +664 +665 +666 +667 +668 +669 +670 +671 +672 +673 +674 +675 +676 +677 +678 +679 +680 +681 +682 +683 +684 +685 +686 +687 +688 +689 +690 +691 +692 +693 +694 +695 +696 +697 +698 +699 +700 +701 +702 +703 +704 +705 +706 +707 +708 +709 +710 +711 +712 +713 +714 +715 +716 +717 +718 +719 +720 +721 +722 +723 +724 +725 +726 +727 +728 +729 +730 +731 +732 +733 +734 +735 +736 +737 +738 +739 +740 +741 +742 +743 +744 +745 +746 +747 +748 +749 +750 +751 +752 +753 +754 +755 +756 +757 +758 +759 +760 +761 +762 +763 +764 +765 +766 +767 +768 +769 +770 +771 +772 +773 +774 +775 +776 +777 +778 +779 +780 +781 +782 +783 +784 +785 +786 +787 +788 +789 +790 +791 +792 +793 +794 +795 +796 +797 +798 +799 +800 +801 +802 +803 +804 +805 +806 +807 +808 +809 +810 +811 +812 +813 +814 +815 +816 +817 +818 +819 +820 +821 +822 +823 +824 +825 +826 +827 +828 +829 +830 +831 +832 +833 +834 +835 +836 +837 +838 +839 +840 +841 +842 +843 +844 +845 +846 +847 +848 +849 +850 +851 +852 +853 +854 +855 +856 +857 +858 +859 +860 +861 +862 +863 +864 +
//! Smart contracts module.
+#![deny(rust_2018_idioms)]
+#![forbid(unsafe_code)]
+#![cfg_attr(all(feature = "benchmarks", test), feature(test))]
+
+#[cfg(test)]
+extern crate alloc;
+
+use std::{convert::TryInto, io::Read};
+
+use thiserror::Error;
+
+use oasis_contract_sdk_types::storage::StoreKind;
+use oasis_runtime_sdk::{
+ self as sdk,
+ context::Context,
+ core::common::crypto::hash::Hash,
+ handler, migration, module,
+ module::Module as _,
+ modules,
+ modules::{accounts::API as _, core::API as _},
+ runtime::Runtime,
+ sdk_derive,
+ state::CurrentState,
+ storage,
+ storage::Store,
+ types::transaction::CallFormat,
+};
+
+use crate::store::with_instance_raw_store;
+
+mod abi;
+mod code;
+mod results;
+mod store;
+#[cfg(test)]
+mod test;
+pub mod types;
+mod wasm;
+
+/// Unique module name.
+const MODULE_NAME: &str = "contracts";
+
+/// Errors emitted by the contracts module.
+#[derive(Error, Debug, sdk::Error)]
+pub enum Error {
+ #[error("invalid argument")]
+ #[sdk_error(code = 1)]
+ InvalidArgument,
+
+ #[error("code too large (size: {0} max: {1})")]
+ #[sdk_error(code = 2)]
+ CodeTooLarge(u32, u32),
+
+ #[error("code is malformed")]
+ #[sdk_error(code = 3)]
+ CodeMalformed,
+
+ #[error("specified ABI is not supported")]
+ #[sdk_error(code = 4)]
+ UnsupportedABI,
+
+ #[error("code is missing required ABI export: {0}")]
+ #[sdk_error(code = 5)]
+ CodeMissingRequiredExport(String),
+
+ #[error("code declares reserved ABI export: {0}")]
+ #[sdk_error(code = 6)]
+ CodeDeclaresReservedExport(String),
+
+ #[error("code declares start function")]
+ #[sdk_error(code = 7)]
+ CodeDeclaresStartFunction,
+
+ #[error("code declares too many memories")]
+ #[sdk_error(code = 8)]
+ CodeDeclaresTooManyMemories,
+
+ #[error("code {0} not found")]
+ #[sdk_error(code = 9)]
+ CodeNotFound(u64),
+
+ #[error("instance {0} not found")]
+ #[sdk_error(code = 10)]
+ InstanceNotFound(u64),
+
+ #[error("module loading failed")]
+ #[sdk_error(code = 11)]
+ ModuleLoadingFailed,
+
+ #[error("execution failed: {0}")]
+ #[sdk_error(code = 12)]
+ ExecutionFailed(#[source] anyhow::Error),
+
+ #[error("forbidden by policy")]
+ #[sdk_error(code = 13)]
+ Forbidden,
+
+ #[error("function not supported")]
+ #[sdk_error(code = 14)]
+ Unsupported,
+
+ #[error("insufficient balance in caller account")]
+ #[sdk_error(code = 15)]
+ InsufficientCallerBalance,
+
+ // Error code 16 is reserved.
+ #[error("result size exceeded (size: {0} max: {1})")]
+ #[sdk_error(code = 17)]
+ ResultTooLarge(u32, u32),
+
+ #[error("too many subcalls (count: {0} max: {1})")]
+ #[sdk_error(code = 18)]
+ TooManySubcalls(u16, u16),
+
+ #[error("instance is already using code {0}")]
+ #[sdk_error(code = 19)]
+ CodeAlreadyUpgraded(u64),
+
+ #[error("abort: {0}")]
+ #[sdk_error(code = 20, abort)]
+ Abort(#[from] sdk::dispatcher::Error),
+
+ #[error("storage: key too large (size: {0} max: {1})")]
+ #[sdk_error(code = 21)]
+ StorageKeyTooLarge(u32, u32),
+
+ #[error("storage: value too large (size: {0} max: {1})")]
+ #[sdk_error(code = 22)]
+ StorageValueTooLarge(u32, u32),
+
+ #[error("crypto: msg too large (size: {0} max: {1})")]
+ #[sdk_error(code = 23)]
+ CryptoMsgTooLarge(u32, u32),
+
+ #[error("crypto: malformed public key")]
+ #[sdk_error(code = 24)]
+ CryptoMalformedPublicKey,
+
+ #[error("code declares multiple sub-versions")]
+ #[sdk_error(code = 25)]
+ CodeDeclaresMultipleSubVersions,
+
+ #[error("crypto: malformed private key")]
+ #[sdk_error(code = 26)]
+ CryptoMalformedPrivateKey,
+
+ #[error("crypto: malformed encryption key")]
+ #[sdk_error(code = 27)]
+ CryptoMalformedKey,
+
+ #[error("crypto: malformed nonce")]
+ #[sdk_error(code = 28)]
+ CryptoMalformedNonce,
+
+ #[error("crypto: key derivation function failure")]
+ #[sdk_error(code = 29)]
+ CryptoKeyDerivationFunctionFailure,
+
+ #[error("module uses floating point data or operations")]
+ #[sdk_error(code = 30)]
+ ModuleUsesFloatingPoint,
+
+ #[error("code declares too many functions")]
+ #[sdk_error(code = 31)]
+ CodeDeclaresTooManyFunctions,
+
+ #[error("code declares too many locals")]
+ #[sdk_error(code = 32)]
+ CodeDeclaresTooManyLocals,
+
+ #[error("core: {0}")]
+ #[sdk_error(transparent)]
+ Core(#[from] modules::core::Error),
+
+ #[error("contract error: {0}")]
+ #[sdk_error(transparent)]
+ Contract(#[from] wasm::ContractError),
+}
+
+/// Events emitted by the contracts module.
+#[derive(Debug, cbor::Encode, sdk::Event)]
+#[cbor(untagged)]
+pub enum Event {}
+
+/// Gas costs.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub struct GasCosts {
+ pub tx_upload: u64,
+ pub tx_upload_per_byte: u64,
+ pub tx_instantiate: u64,
+ pub tx_call: u64,
+ pub tx_upgrade: u64,
+ pub tx_change_upgrade_policy: u64,
+
+ // Subcalls.
+ pub subcall_dispatch: u64,
+
+ // Storage operations.
+ pub wasm_public_storage_get_base: u64,
+ pub wasm_public_storage_insert_base: u64,
+ pub wasm_public_storage_remove_base: u64,
+ pub wasm_public_storage_key_byte: u64,
+ pub wasm_public_storage_value_byte: u64,
+ pub wasm_confidential_storage_get_base: u64,
+ pub wasm_confidential_storage_insert_base: u64,
+ pub wasm_confidential_storage_remove_base: u64,
+ pub wasm_confidential_storage_key_byte: u64,
+ pub wasm_confidential_storage_value_byte: u64,
+ pub wasm_env_query_base: u64,
+
+ // Crypto operations.
+ pub wasm_crypto_ecdsa_recover: u64,
+ pub wasm_crypto_signature_verify_ed25519: u64,
+ pub wasm_crypto_signature_verify_secp256k1: u64,
+ pub wasm_crypto_signature_verify_sr25519: u64,
+ pub wasm_crypto_x25519_derive_symmetric: u64,
+ pub wasm_crypto_deoxysii_base: u64,
+ pub wasm_crypto_deoxysii_byte: u64,
+ pub wasm_crypto_random_bytes_base: u64,
+ pub wasm_crypto_random_bytes_byte: u64,
+}
+
+impl Default for GasCosts {
+ fn default() -> Self {
+ // The below assume a batch gas limit of 1_000_000_000 ~ 1s.
+ GasCosts {
+ tx_upload: 30_000_000,
+ tx_upload_per_byte: 400,
+ tx_instantiate: 100_000,
+ tx_call: 50_000,
+ tx_upgrade: 50_000,
+ tx_change_upgrade_policy: 30_000,
+
+ subcall_dispatch: 1_000,
+
+ wasm_public_storage_get_base: 5_000,
+ wasm_public_storage_insert_base: 8_400,
+ wasm_public_storage_remove_base: 6_400,
+ wasm_public_storage_key_byte: 3_000,
+ wasm_public_storage_value_byte: 300,
+ wasm_confidential_storage_get_base: 10_000,
+ wasm_confidential_storage_insert_base: 16_800,
+ wasm_confidential_storage_remove_base: 12_800,
+ wasm_confidential_storage_key_byte: 3_500,
+ wasm_confidential_storage_value_byte: 400,
+ wasm_env_query_base: 100,
+
+ wasm_crypto_ecdsa_recover: 500_000,
+ wasm_crypto_signature_verify_ed25519: 500_000,
+ wasm_crypto_signature_verify_secp256k1: 500_000,
+ wasm_crypto_signature_verify_sr25519: 500_000,
+ wasm_crypto_x25519_derive_symmetric: 250_000,
+ wasm_crypto_deoxysii_base: 1_000,
+ wasm_crypto_deoxysii_byte: 3,
+ wasm_crypto_random_bytes_base: 1_000,
+ wasm_crypto_random_bytes_byte: 3,
+ }
+ }
+}
+
+/// Parameters for the contracts module.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub struct Parameters {
+ pub max_code_size: u32,
+ pub max_stack_size: u32,
+ pub max_memory_pages: u32,
+
+ pub max_wasm_functions: u32,
+ pub max_wasm_locals: u32,
+
+ pub max_subcall_depth: u16,
+ pub max_subcall_count: u16,
+
+ pub max_result_size_bytes: u32,
+ pub max_query_size_bytes: u32,
+ pub max_storage_key_size_bytes: u32,
+ pub max_storage_value_size_bytes: u32,
+ pub max_crypto_signature_verify_message_size_bytes: u32,
+
+ pub gas_costs: GasCosts,
+}
+
+impl Default for Parameters {
+ fn default() -> Self {
+ Parameters {
+ max_code_size: 1024 * 1024, // 1 MiB
+ max_stack_size: 60 * 1024, // 60 KiB
+ max_memory_pages: 160, // 10 MiB
+
+ max_wasm_functions: 10_000,
+ max_wasm_locals: 256_000,
+
+ max_subcall_depth: 8,
+ max_subcall_count: 16,
+
+ max_result_size_bytes: 1024, // 1 KiB
+ max_query_size_bytes: 1024, // 1 KiB
+ max_storage_key_size_bytes: 64,
+ max_storage_value_size_bytes: 16 * 1024, // 16 KiB
+ max_crypto_signature_verify_message_size_bytes: 16 * 1024, // 16KiB
+
+ gas_costs: Default::default(),
+ }
+ }
+}
+
+impl module::Parameters for Parameters {
+ type Error = std::convert::Infallible;
+}
+
+/// Genesis state for the contracts module.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct Genesis {
+ pub parameters: Parameters,
+}
+
+/// Local configuration that can be provided by the node operator.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+pub struct LocalConfig {
+ /// Gas limit for custom queries that invoke smart contracts.
+ #[cbor(optional)]
+ pub query_custom_max_gas: u64,
+
+ /// Maximum number of items per page in InstanceRawStorage query result.
+ #[cbor(optional)]
+ pub max_instance_raw_storage_query_items: u64,
+}
+
+impl Default for LocalConfig {
+ fn default() -> Self {
+ Self {
+ query_custom_max_gas: 10_000_000,
+ max_instance_raw_storage_query_items: 100,
+ }
+ }
+}
+
+/// State schema constants.
+pub mod state {
+ /// Next code identifier (u64).
+ pub const NEXT_CODE_IDENTIFIER: &[u8] = &[0x01];
+ /// Next instance identifier (u64).
+ pub const NEXT_INSTANCE_IDENTIFIER: &[u8] = &[0x02];
+ /// Information about uploaded code.
+ pub const CODE_INFO: &[u8] = &[0x03];
+ /// Information about the deployed contract instance.
+ pub const INSTANCE_INFO: &[u8] = &[0x04];
+ /// Per-instance key/value store.
+ pub const INSTANCE_STATE: &[u8] = &[0x05];
+
+ /// Uploaded code.
+ pub const CODE: &[u8] = &[0xFF];
+}
+
+/// Module configuration.
+pub trait Config: 'static {}
+
+pub struct Module<Cfg: Config> {
+ _cfg: std::marker::PhantomData<Cfg>,
+}
+
+impl<Cfg: Config> Module<Cfg> {
+ /// Loads code information for the specified code identifier.
+ fn load_code_info(code_id: types::CodeId) -> Result<types::Code, Error> {
+ CurrentState::with_store(|store| {
+ let mut store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let code_info_store =
+ storage::TypedStore::new(storage::PrefixStore::new(&mut store, &state::CODE_INFO));
+ let code_info = code_info_store
+ .get(code_id.to_storage_key())
+ .ok_or_else(|| Error::CodeNotFound(code_id.as_u64()))?;
+
+ Ok(code_info)
+ })
+ }
+
+ /// Stores specified code information.
+ fn store_code_info(code_info: types::Code) -> Result<(), Error> {
+ CurrentState::with_store(|store| {
+ let mut store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut code_info_store =
+ storage::TypedStore::new(storage::PrefixStore::new(&mut store, &state::CODE_INFO));
+ code_info_store.insert(code_info.id.to_storage_key(), code_info);
+
+ Ok(())
+ })
+ }
+
+ /// Loads specified instance information.
+ fn load_instance_info(instance_id: types::InstanceId) -> Result<types::Instance, Error> {
+ CurrentState::with_store(|store| {
+ let mut store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let instance_info_store = storage::TypedStore::new(storage::PrefixStore::new(
+ &mut store,
+ &state::INSTANCE_INFO,
+ ));
+ let instance_info = instance_info_store
+ .get(instance_id.to_storage_key())
+ .ok_or_else(|| Error::InstanceNotFound(instance_id.as_u64()))?;
+
+ Ok(instance_info)
+ })
+ }
+
+ /// Stores specified instance information.
+ fn store_instance_info(instance_info: types::Instance) -> Result<(), Error> {
+ CurrentState::with_store(|store| {
+ let mut store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut instance_info_store = storage::TypedStore::new(storage::PrefixStore::new(
+ &mut store,
+ &state::INSTANCE_INFO,
+ ));
+ instance_info_store.insert(instance_info.id.to_storage_key(), instance_info);
+
+ Ok(())
+ })
+ }
+}
+
+#[sdk_derive(Module)]
+impl<Cfg: Config> Module<Cfg> {
+ const NAME: &'static str = MODULE_NAME;
+ type Error = Error;
+ type Event = Event;
+ type Parameters = Parameters;
+ type Genesis = Genesis;
+
+ #[migration(init)]
+ fn init(genesis: Genesis) {
+ // Set genesis parameters.
+ Self::set_params(genesis.parameters);
+ }
+
+ #[handler(call = "contracts.Upload")]
+ pub fn tx_upload<C: Context>(
+ ctx: &C,
+ body: types::Upload,
+ ) -> Result<types::UploadResult, Error> {
+ let params = Self::params();
+ let uploader = CurrentState::with_env(|env| env.tx_caller_address());
+
+ // Validate code size.
+ let code_size: u32 = body
+ .code
+ .len()
+ .try_into()
+ .map_err(|_| Error::CodeTooLarge(u32::MAX, params.max_code_size))?;
+ if code_size > params.max_code_size {
+ return Err(Error::CodeTooLarge(code_size, params.max_code_size));
+ }
+
+ // Account for base gas.
+ <C::Runtime as Runtime>::Core::use_tx_gas(params.gas_costs.tx_upload)?;
+ <C::Runtime as Runtime>::Core::use_tx_gas(
+ params
+ .gas_costs
+ .tx_upload_per_byte
+ .saturating_mul(body.code.len() as u64),
+ )?;
+
+ // Decompress code.
+ let mut code = Vec::with_capacity(body.code.len());
+ let decoder = snap::read::FrameDecoder::new(body.code.as_slice());
+ decoder
+ .take(params.max_code_size.into())
+ .read_to_end(&mut code)
+ .map_err(|_| Error::CodeMalformed)?;
+
+ // Account for extra gas needed after decompression.
+ let plain_code_size: u32 = code.len().try_into().unwrap();
+ <C::Runtime as Runtime>::Core::use_tx_gas(
+ params
+ .gas_costs
+ .tx_upload_per_byte
+ .saturating_mul(plain_code_size.saturating_sub(code_size) as u64),
+ )?;
+
+ if !ctx.should_execute_contracts() {
+ // Only fast checks are allowed.
+ return Ok(types::UploadResult::default());
+ }
+
+ // Validate and transform the code.
+ let (code, abi_info) = wasm::validate_and_transform::<Cfg, C>(&code, body.abi, ¶ms)?;
+ let hash = Hash::digest_bytes(&code);
+
+ // Validate code size again and account for any instrumentation. This is here to avoid any
+ // incentives in generating code that gets maximally inflated after instrumentation.
+ let inst_code_size: u32 = code
+ .len()
+ .try_into()
+ .map_err(|_| Error::CodeTooLarge(u32::MAX, params.max_code_size))?;
+ if inst_code_size > params.max_code_size {
+ return Err(Error::CodeTooLarge(inst_code_size, params.max_code_size));
+ }
+ <C::Runtime as Runtime>::Core::use_tx_gas(
+ params
+ .gas_costs
+ .tx_upload_per_byte
+ .saturating_mul(inst_code_size.saturating_sub(plain_code_size) as u64),
+ )?;
+
+ // Assign next identifier.
+ let id = CurrentState::with_store(|store| {
+ let mut store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut tstore = storage::TypedStore::new(&mut store);
+ let id: types::CodeId = tstore.get(state::NEXT_CODE_IDENTIFIER).unwrap_or_default();
+ tstore.insert(state::NEXT_CODE_IDENTIFIER, id.increment());
+ id
+ });
+
+ // Store information about uploaded code.
+ let code_info = types::Code {
+ id,
+ hash,
+ abi: body.abi,
+ abi_sv: abi_info.abi_sv,
+ uploader,
+ instantiate_policy: body.instantiate_policy,
+ };
+ Self::store_code(&code_info, &code)?;
+ Self::store_code_info(code_info)?;
+
+ Ok(types::UploadResult { id })
+ }
+
+ #[handler(call = "contracts.Instantiate")]
+ pub fn tx_instantiate<C: Context>(
+ ctx: &C,
+ body: types::Instantiate,
+ ) -> Result<types::InstantiateResult, Error> {
+ let params = Self::params();
+ let creator = CurrentState::with_env(|env| env.tx_caller_address());
+
+ <C::Runtime as Runtime>::Core::use_tx_gas(params.gas_costs.tx_instantiate)?;
+
+ if !ctx.should_execute_contracts() {
+ // Only fast checks are allowed.
+ return Ok(types::InstantiateResult::default());
+ }
+
+ // Load code information, enforce instantiation policy and load the code.
+ let code_info = Self::load_code_info(body.code_id)?;
+ code_info.instantiate_policy.enforce(&creator)?;
+ let code = Self::load_code(&code_info)?;
+
+ // Assign next identifier.
+ let id = CurrentState::with_store(|store| {
+ let mut store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let mut tstore = storage::TypedStore::new(&mut store);
+ let id: types::InstanceId = tstore
+ .get(state::NEXT_INSTANCE_IDENTIFIER)
+ .unwrap_or_default();
+ tstore.insert(state::NEXT_INSTANCE_IDENTIFIER, id.increment());
+ id
+ });
+
+ // Store instance information.
+ let instance_info = types::Instance {
+ id,
+ code_id: body.code_id,
+ creator,
+ upgrades_policy: body.upgrades_policy,
+ };
+ Self::store_instance_info(instance_info.clone())?;
+
+ // Transfer any attached tokens.
+ for tokens in &body.tokens {
+ <C::Runtime as Runtime>::Accounts::transfer(creator, instance_info.address(), tokens)
+ .map_err(|_| Error::InsufficientCallerBalance)?
+ }
+ // Run instantiation function.
+ let contract = wasm::Contract {
+ code_info: &code_info,
+ code: &code,
+ instance_info: &instance_info,
+ };
+ let mut exec_ctx = abi::ExecutionContext::new(
+ ¶ms,
+ &code_info,
+ &instance_info,
+ <C::Runtime as Runtime>::Core::remaining_tx_gas(),
+ creator,
+ CurrentState::with_env(|env| env.is_read_only()),
+ CurrentState::with_env(|env| env.tx_call_format()),
+ ctx,
+ );
+ let result = wasm::instantiate::<Cfg, C>(&mut exec_ctx, &contract, &body);
+
+ let result = results::process_execution_result(ctx, result)?;
+ results::process_execution_success::<Cfg, C>(ctx, ¶ms, &contract, result)?;
+ Ok(types::InstantiateResult { id })
+ }
+
+ #[handler(call = "contracts.Call", allow_interactive)]
+ pub fn tx_call<C: Context>(ctx: &C, body: types::Call) -> Result<types::CallResult, Error> {
+ let params = Self::params();
+ let caller = CurrentState::with_env(|env| env.tx_caller_address());
+
+ <C::Runtime as Runtime>::Core::use_tx_gas(params.gas_costs.tx_call)?;
+
+ if !ctx.should_execute_contracts() {
+ // Only fast checks are allowed.
+ return Ok(types::CallResult::default());
+ }
+
+ // Load instance information and code.
+ let instance_info = Self::load_instance_info(body.id)?;
+ let code_info = Self::load_code_info(instance_info.code_id)?;
+ let code = Self::load_code(&code_info)?;
+
+ // Transfer any attached tokens.
+ for tokens in &body.tokens {
+ <C::Runtime as Runtime>::Accounts::transfer(caller, instance_info.address(), tokens)
+ .map_err(|_| Error::InsufficientCallerBalance)?
+ }
+ // Run call function.
+ let contract = wasm::Contract {
+ code_info: &code_info,
+ code: &code,
+ instance_info: &instance_info,
+ };
+ let mut exec_ctx = abi::ExecutionContext::new(
+ ¶ms,
+ &code_info,
+ &instance_info,
+ <C::Runtime as Runtime>::Core::remaining_tx_gas(),
+ caller,
+ CurrentState::with_env(|env| env.is_read_only()),
+ CurrentState::with_env(|env| env.tx_call_format()),
+ ctx,
+ );
+ let result = wasm::call::<Cfg, C>(&mut exec_ctx, &contract, &body);
+
+ let result = results::process_execution_result(ctx, result)?;
+ let data = results::process_execution_success::<Cfg, C>(ctx, ¶ms, &contract, result)?;
+ Ok(types::CallResult(data))
+ }
+
+ #[handler(call = "contracts.ChangeUpgradePolicy")]
+ pub fn tx_change_upgrade_policy<C: Context>(
+ ctx: &C,
+ body: types::ChangeUpgradePolicy,
+ ) -> Result<(), Error> {
+ let params = Self::params();
+ let caller = CurrentState::with_env(|env| env.tx_caller_address());
+
+ <C::Runtime as Runtime>::Core::use_tx_gas(params.gas_costs.tx_change_upgrade_policy)?;
+
+ if CurrentState::with_env(|env| env.is_check_only()) {
+ return Ok(());
+ }
+
+ // Load instance information.
+ let mut instance_info = Self::load_instance_info(body.id)?;
+ instance_info.upgrades_policy.enforce(&caller)?;
+
+ // Change upgrade policy.
+ instance_info.upgrades_policy = body.upgrades_policy;
+ Self::store_instance_info(instance_info.clone())?;
+
+ Ok(())
+ }
+
+ #[handler(call = "contracts.Upgrade")]
+ pub fn tx_upgrade<C: Context>(ctx: &C, body: types::Upgrade) -> Result<(), Error> {
+ let params = Self::params();
+ let caller = CurrentState::with_env(|env| env.tx_caller_address());
+
+ <C::Runtime as Runtime>::Core::use_tx_gas(params.gas_costs.tx_upgrade)?;
+
+ if !ctx.should_execute_contracts() {
+ // Only fast checks are allowed.
+ return Ok(());
+ }
+
+ // Load instance information and code.
+ let mut instance_info = Self::load_instance_info(body.id)?;
+ instance_info.upgrades_policy.enforce(&caller)?;
+ if instance_info.code_id == body.code_id {
+ return Err(Error::CodeAlreadyUpgraded(body.code_id.as_u64()));
+ }
+ let code_info = Self::load_code_info(instance_info.code_id)?;
+ let code = Self::load_code(&code_info)?;
+
+ // Transfer any attached tokens.
+ for tokens in &body.tokens {
+ <C::Runtime as Runtime>::Accounts::transfer(caller, instance_info.address(), tokens)
+ .map_err(|_| Error::InsufficientCallerBalance)?
+ }
+ // Run pre-upgrade function on the previous contract.
+ let contract = wasm::Contract {
+ code_info: &code_info,
+ code: &code,
+ instance_info: &instance_info,
+ };
+ let mut exec_ctx = abi::ExecutionContext::new(
+ ¶ms,
+ &code_info,
+ &instance_info,
+ <C::Runtime as Runtime>::Core::remaining_tx_gas(),
+ caller,
+ CurrentState::with_env(|env| env.is_read_only()),
+ CurrentState::with_env(|env| env.tx_call_format()),
+ ctx,
+ );
+ // Pre-upgrade invocation must succeed for the upgrade to proceed.
+ let result = wasm::pre_upgrade::<Cfg, C>(&mut exec_ctx, &contract, &body);
+
+ results::process_execution_result(ctx, result)?;
+
+ // Update the contract code.
+ instance_info.code_id = body.code_id;
+ let code_info = Self::load_code_info(instance_info.code_id)?;
+ let code = Self::load_code(&code_info)?;
+ Self::store_instance_info(instance_info.clone())?;
+
+ let contract = wasm::Contract {
+ code_info: &code_info,
+ code: &code,
+ instance_info: &instance_info,
+ };
+ let mut exec_ctx = abi::ExecutionContext::new(
+ ¶ms,
+ &code_info,
+ &instance_info,
+ <C::Runtime as Runtime>::Core::remaining_tx_gas(),
+ caller,
+ CurrentState::with_env(|env| env.is_read_only()),
+ CurrentState::with_env(|env| env.tx_call_format()),
+ ctx,
+ );
+
+ // Run post-upgrade function on the new contract.
+ let result = wasm::post_upgrade::<Cfg, C>(&mut exec_ctx, &contract, &body);
+ results::process_execution_result(ctx, result)?;
+ Ok(())
+ }
+
+ #[handler(query = "contracts.Code")]
+ pub fn query_code<C: Context>(_ctx: &C, args: types::CodeQuery) -> Result<types::Code, Error> {
+ Self::load_code_info(args.id)
+ }
+
+ #[handler(query = "contracts.CodeStorage")]
+ pub fn query_code_storage<C: Context>(
+ _ctx: &C,
+ args: types::CodeStorageQuery,
+ ) -> Result<types::CodeStorageQueryResult, Error> {
+ let code_info = Self::load_code_info(args.id)?;
+ let code = Self::load_code(&code_info)?;
+
+ Ok(types::CodeStorageQueryResult { code })
+ }
+
+ #[handler(query = "contracts.Instance")]
+ pub fn query_instance<C: Context>(
+ _ctx: &C,
+ args: types::InstanceQuery,
+ ) -> Result<types::Instance, Error> {
+ Self::load_instance_info(args.id)
+ }
+
+ #[handler(query = "contracts.InstanceStorage")]
+ pub fn query_instance_storage<C: Context>(
+ ctx: &C,
+ args: types::InstanceStorageQuery,
+ ) -> Result<types::InstanceStorageQueryResult, Error> {
+ let instance_info = Self::load_instance_info(args.id)?;
+ // NOTE: We can only access the public store here.
+ let value = store::with_instance_store(ctx, &instance_info, StoreKind::Public, |store| {
+ store.get(&args.key)
+ })?;
+
+ Ok(types::InstanceStorageQueryResult { value })
+ }
+
+ #[handler(query = "contracts.InstanceRawStorage", expensive)]
+ pub fn query_instance_raw_storage<C: Context>(
+ ctx: &C,
+ args: types::InstanceRawStorageQuery,
+ ) -> Result<types::InstanceRawStorageQueryResult, Error> {
+ let cfg: LocalConfig = ctx.local_config(MODULE_NAME).unwrap_or_default();
+ let limit: usize = args
+ .limit
+ .unwrap_or(u64::MAX)
+ .min(cfg.max_instance_raw_storage_query_items)
+ .try_into()
+ .map_err(|_| Error::InvalidArgument)?;
+ let offset: usize = args
+ .offset
+ .unwrap_or(0)
+ .try_into()
+ .map_err(|_| Error::InvalidArgument)?;
+
+ let instance_info = Self::load_instance_info(args.id)?;
+ // Convert contracts API StoreKind to internal storage StoreKind.
+ let sk: StoreKind = (args.store_kind as u32)
+ .try_into()
+ .map_err(|_| Error::InvalidArgument)?;
+
+ let items: Vec<(Vec<u8>, Vec<u8>)> = with_instance_raw_store(&instance_info, sk, |store| {
+ store
+ .iter()
+ // Shave off first 32 bytes of the key to get the contract instance-level key name.
+ .filter(|(k, _)| k.len() >= 32)
+ .map(|(k, v)| (k[32..].to_vec(), v.to_vec()))
+ .skip(offset)
+ .take(limit)
+ .collect()
+ });
+
+ Ok(types::InstanceRawStorageQueryResult { items })
+ }
+
+ #[handler(query = "contracts.PublicKey")]
+ pub fn query_public_key<C: Context>(
+ _ctx: &C,
+ _args: types::PublicKeyQuery,
+ ) -> Result<types::PublicKeyQueryResult, Error> {
+ Err(Error::Unsupported)
+ }
+
+ #[handler(query = "contracts.Custom", expensive)]
+ pub fn query_custom<C: Context>(
+ ctx: &C,
+ args: types::CustomQuery,
+ ) -> Result<types::CustomQueryResult, Error> {
+ let params = Self::params();
+
+ // Load instance information and code.
+ let instance_info = Self::load_instance_info(args.id)?;
+ let code_info = Self::load_code_info(instance_info.code_id)?;
+ let code = Self::load_code(&code_info)?;
+
+ // Load local configuration.
+ let cfg: LocalConfig = ctx.local_config(MODULE_NAME).unwrap_or_default();
+
+ // Run query function.
+ let contract = wasm::Contract {
+ code_info: &code_info,
+ code: &code,
+ instance_info: &instance_info,
+ };
+ let mut exec_ctx = abi::ExecutionContext::new(
+ ¶ms,
+ &code_info,
+ &instance_info,
+ cfg.query_custom_max_gas,
+ Default::default(), // No caller for queries.
+ true,
+ CallFormat::Plain,
+ ctx,
+ );
+ let result = wasm::query::<Cfg, C>(&mut exec_ctx, &contract, &args).inner?; // No need to handle gas.
+
+ Ok(types::CustomQueryResult(result.data))
+ }
+}
+
+impl<Cfg: Config> module::TransactionHandler for Module<Cfg> {}
+impl<Cfg: Config> module::BlockHandler for Module<Cfg> {}
+impl<Cfg: Config> module::InvariantHandler for Module<Cfg> {}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +
//! Processing of execution results.
+use std::convert::TryInto;
+
+use oasis_contract_sdk_types::{
+ event::Event,
+ message::{Message, NotifyReply, Reply},
+ ExecutionOk,
+};
+use oasis_runtime_sdk::{
+ context::Context,
+ event::etag_for_event,
+ modules::core::API as _,
+ runtime::Runtime,
+ state::CurrentState,
+ subcall::{self, SubcallInfo},
+ types::transaction::CallerAddress,
+};
+
+use crate::{
+ abi::{ExecutionContext, ExecutionResult},
+ types::ContractEvent,
+ wasm, Config, Error, Parameters, MODULE_NAME,
+};
+
+/// Process an execution result by performing gas accounting and returning the inner result.
+pub(crate) fn process_execution_result<C: Context>(
+ _ctx: &C,
+ result: ExecutionResult,
+) -> Result<ExecutionOk, Error> {
+ // The following call should never fail as we accounted for all the gas in advance.
+ <C::Runtime as Runtime>::Core::use_tx_gas(result.gas_used)?;
+
+ result.inner
+}
+
+/// Process a successful execution result.
+pub(crate) fn process_execution_success<Cfg: Config, C: Context>(
+ ctx: &C,
+ params: &Parameters,
+ contract: &wasm::Contract<'_>,
+ result: ExecutionOk,
+) -> Result<Vec<u8>, Error> {
+ // Process events.
+ process_events(contract, result.events)?;
+ // Process subcalls.
+ let result = process_subcalls::<Cfg, C>(ctx, params, contract, result.messages, result.data)?;
+
+ Ok(result)
+}
+
+fn process_events(contract: &wasm::Contract<'_>, events: Vec<Event>) -> Result<(), Error> {
+ // Transform contract events into tags using the SDK scheme.
+ CurrentState::with(|state| {
+ for event in events {
+ state.emit_event_raw(etag_for_event(
+ &if event.module.is_empty() {
+ format!("{}.{}", MODULE_NAME, contract.code_info.id.as_u64())
+ } else {
+ format!(
+ "{}.{}.{}",
+ MODULE_NAME,
+ contract.code_info.id.as_u64(),
+ event.module,
+ )
+ },
+ event.code,
+ cbor::to_value(ContractEvent {
+ id: contract.instance_info.id,
+ data: event.data,
+ }),
+ ));
+ }
+ });
+
+ Ok(())
+}
+
+fn process_subcalls<Cfg: Config, C: Context>(
+ ctx: &C,
+ params: &Parameters,
+ contract: &wasm::Contract<'_>,
+ messages: Vec<Message>,
+ data: Vec<u8>,
+) -> Result<Vec<u8>, Error> {
+ // By default the resulting data is what the call returned. Message reply processing may
+ // overwrite this data when it is non-empty.
+ let mut result_data = data;
+
+ // Charge gas for each emitted message.
+ <C::Runtime as Runtime>::Core::use_tx_gas(
+ params
+ .gas_costs
+ .subcall_dispatch
+ .saturating_mul(messages.len() as u64),
+ )?;
+
+ // Make sure the number of subcalls is within limits.
+ let message_count = messages
+ .len()
+ .try_into()
+ .map_err(|_| Error::TooManySubcalls(u16::MAX, params.max_subcall_count))?;
+ if message_count > params.max_subcall_count {
+ return Err(Error::TooManySubcalls(
+ message_count,
+ params.max_subcall_count,
+ ));
+ }
+
+ // Properly propagate original call format and read-only flag.
+ let (orig_call_format, orig_read_only) =
+ CurrentState::with_env(|env| (env.tx_call_format(), env.is_read_only()));
+
+ // Process emitted messages recursively.
+ for msg in messages {
+ match msg {
+ Message::Call {
+ id,
+ data,
+ reply,
+ method,
+ body,
+ max_gas,
+ } => {
+ // Compute the amount of gas that can be used.
+ let remaining_gas = <C::Runtime as Runtime>::Core::remaining_tx_gas();
+ let max_gas = max_gas.unwrap_or(remaining_gas);
+ let max_gas = if max_gas > remaining_gas {
+ remaining_gas
+ } else {
+ max_gas
+ };
+
+ let result = subcall::call(
+ ctx,
+ SubcallInfo {
+ caller: CallerAddress::Address(contract.instance_info.address()),
+ method,
+ body,
+ max_depth: params.max_subcall_depth,
+ max_gas,
+ },
+ subcall::AllowAllValidator,
+ )?;
+
+ // Use any gas that was used inside the child context. This should never fail as we
+ // preconfigured the amount of available gas.
+ <C::Runtime as Runtime>::Core::use_tx_gas(result.gas_used)?;
+
+ // Process replies based on filtering criteria.
+ let result = result.call_result;
+ match (reply, result.is_success()) {
+ (NotifyReply::OnError, false)
+ | (NotifyReply::OnSuccess, true)
+ | (NotifyReply::Always, _) => {
+ // Construct and process reply.
+ let reply = Reply::Call {
+ id,
+ result: result.into(),
+ data,
+ };
+ let mut exec_ctx = ExecutionContext::new(
+ params,
+ contract.code_info,
+ contract.instance_info,
+ <C::Runtime as Runtime>::Core::remaining_tx_gas(),
+ CurrentState::with_env(|env| env.tx_caller_address()),
+ orig_read_only,
+ orig_call_format,
+ ctx,
+ );
+ let reply_result =
+ wasm::handle_reply::<Cfg, C>(&mut exec_ctx, contract, reply);
+ let reply_result = process_execution_result(ctx, reply_result)?;
+ let reply_result = process_execution_success::<Cfg, C>(
+ ctx,
+ params,
+ contract,
+ reply_result,
+ )?;
+
+ // If there is a non-empty reply, it overwrites the returned data.
+ if !reply_result.is_empty() {
+ result_data = reply_result;
+ }
+ }
+ _ => {}
+ }
+ }
+
+ // Message not supported.
+ _ => return Err(Error::Unsupported),
+ }
+ }
+
+ Ok(result_data)
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +
//! Contract storage.
+use oasis_contract_sdk_types::storage::StoreKind;
+use oasis_runtime_sdk::{
+ context::Context,
+ dispatcher,
+ keymanager::{self, StateKey},
+ state::CurrentState,
+ storage::{self, Store},
+ subcall,
+};
+
+use crate::{state, types, Error, MODULE_NAME};
+
+/// Confidential store key pair ID domain separation context base.
+pub const CONFIDENTIAL_STORE_KEY_PAIR_ID_CONTEXT_BASE: &[u8] =
+ b"oasis-runtime-sdk/contracts: state";
+
+const CONTEXT_KEY_CONFIDENTIAL_STORE_INSTANCE_COUNT: &str = "contracts.ConfidentialStoreCounter";
+
+/// Run a closure with the contract instance store.
+///
+/// Confidential stores will only work when private key queries for the key
+/// manager are available. In others, an error will be returned describing the
+/// particular key manager failure.
+pub fn with_instance_store<C, F, R>(
+ ctx: &C,
+ instance_info: &types::Instance,
+ store_kind: StoreKind,
+ f: F,
+) -> Result<R, Error>
+where
+ C: Context,
+ F: FnOnce(&mut dyn Store) -> R,
+{
+ // subcall_count, instance_count, round are all used as nonce derivation context
+ // in the confidential store. Along with confidential_key, they all need ctx,
+ // which becomes unavailable after the first PrefixStore is created, since that
+ // keeps a mutable reference to it (via runtime_state()).
+ let subcall_count = if let StoreKind::Confidential = store_kind {
+ subcall::get_current_subcall_depth(ctx)
+ } else {
+ 0
+ };
+ let instance_count: Option<usize> = if let StoreKind::Confidential = store_kind {
+ CurrentState::with(|state| {
+ let cnt = *state
+ .block_value(CONTEXT_KEY_CONFIDENTIAL_STORE_INSTANCE_COUNT)
+ .or_default();
+ state
+ .block_value(CONTEXT_KEY_CONFIDENTIAL_STORE_INSTANCE_COUNT)
+ .set(cnt + 1);
+ Some(cnt)
+ })
+ } else {
+ None
+ };
+ let round = ctx.runtime_header().round;
+ let confidential_key: Option<StateKey> = if let StoreKind::Confidential = store_kind {
+ let kmgr_client = ctx.key_manager().ok_or(Error::Unsupported)?;
+ let kid = keymanager::get_key_pair_id([
+ CONFIDENTIAL_STORE_KEY_PAIR_ID_CONTEXT_BASE,
+ &instance_info.id.to_storage_key(),
+ ]);
+ let kp = kmgr_client
+ .get_or_create_keys(kid)
+ .map_err(|err| Error::Abort(dispatcher::Error::KeyManagerFailure(err)))?;
+ Some(kp.state_key)
+ } else {
+ None
+ };
+
+ with_instance_raw_store(instance_info, store_kind, |contract_state| {
+ match store_kind {
+ // For public storage we use a hashed store using the Blake3 hash function.
+ StoreKind::Public => Ok(f(&mut storage::HashedStore::<_, blake3::Hasher>::new(
+ contract_state,
+ ))),
+
+ StoreKind::Confidential => {
+ let mut confidential_store = storage::ConfidentialStore::new_with_key(
+ contract_state,
+ confidential_key.unwrap().0,
+ &[
+ round.to_le_bytes().as_slice(),
+ subcall_count.to_le_bytes().as_slice(),
+ instance_count.unwrap().to_le_bytes().as_slice(),
+ ],
+ );
+ Ok(f(&mut confidential_store))
+ }
+ }
+ })
+}
+
+/// Run a closure with the per-contract-instance raw (public) store.
+pub fn with_instance_raw_store<F, R>(
+ instance_info: &types::Instance,
+ store_kind: StoreKind,
+ f: F,
+) -> R
+where
+ F: FnOnce(&mut dyn Store) -> R,
+{
+ CurrentState::with_store(|store| {
+ let store = storage::PrefixStore::new(store, &MODULE_NAME);
+ let instance_prefix = instance_info.id.to_storage_key();
+ let contract_state = storage::PrefixStore::new(
+ storage::PrefixStore::new(store, &state::INSTANCE_STATE),
+ instance_prefix,
+ );
+
+ let mut store = storage::PrefixStore::new(contract_state, store_kind.prefix());
+ f(&mut store)
+ })
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +
//! Contracts module types.
+pub use oasis_contract_sdk_types::{CodeId, InstanceId};
+use oasis_runtime_sdk::{
+ core::common::crypto::hash::Hash,
+ types::{address::Address, token},
+};
+
+use super::{Error, MODULE_NAME};
+
+/// A generic policy that specifies who is allowed to perform an action.
+#[derive(Clone, Copy, Debug, cbor::Encode, cbor::Decode)]
+pub enum Policy {
+ #[cbor(rename = "nobody", as_struct)]
+ Nobody,
+
+ #[cbor(rename = "address")]
+ Address(Address),
+
+ #[cbor(rename = "everyone", as_struct)]
+ Everyone,
+}
+
+impl Policy {
+ /// Enforce the given policy by returning an error if the policy is not satisfied.
+ pub fn enforce(&self, caller: &Address) -> Result<(), Error> {
+ match self {
+ // Nobody is allowed to perform the action.
+ Policy::Nobody => Err(Error::Forbidden),
+ // Only the given caller is allowed to perform the action.
+ Policy::Address(address) if address == caller => Ok(()),
+ Policy::Address(_) => Err(Error::Forbidden),
+ // Anyone is allowed to perform the action.
+ Policy::Everyone => Ok(()),
+ }
+ }
+}
+
+/// ABI that the given contract should conform to.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, cbor::Encode, cbor::Decode)]
+#[repr(u8)]
+pub enum ABI {
+ /// Custom Oasis SDK-specific ABI (v1).
+ OasisV1 = 1,
+}
+
+/// Stored code information.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct Code {
+ /// Unique code identifier.
+ pub id: CodeId,
+
+ /// Code hash.
+ pub hash: Hash,
+
+ /// ABI.
+ pub abi: ABI,
+
+ /// ABI sub-version.
+ #[cbor(optional)]
+ pub abi_sv: u32,
+
+ /// Code uploader address.
+ pub uploader: Address,
+
+ /// Who is allowed to instantiate this code.
+ pub instantiate_policy: Policy,
+}
+
+/// Deployed code instance information.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct Instance {
+ /// Unique instance identifier.
+ pub id: InstanceId,
+
+ /// Identifier of code used by the instance.
+ pub code_id: CodeId,
+
+ /// Instance creator address.
+ pub creator: Address,
+
+ /// Who is allowed to upgrade this instance.
+ pub upgrades_policy: Policy,
+}
+
+impl Instance {
+ /// Address associated with a specific contract instance.
+ pub fn address_for(id: InstanceId) -> Address {
+ Address::from_module_raw(MODULE_NAME, &id.as_u64().to_be_bytes())
+ }
+
+ /// Address associated with the contract.
+ pub fn address(&self) -> Address {
+ Self::address_for(self.id)
+ }
+}
+
+/// Upload call.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct Upload {
+ /// ABI.
+ pub abi: ABI,
+
+ /// Who is allowed to instantiate this code.
+ pub instantiate_policy: Policy,
+
+ /// Compiled contract code.
+ pub code: Vec<u8>,
+}
+
+/// Upload call result.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct UploadResult {
+ /// Assigned code identifier.
+ pub id: CodeId,
+}
+
+/// Instantiate call.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct Instantiate {
+ /// Identifier of code used by the instance.
+ pub code_id: CodeId,
+
+ /// Who is allowed to upgrade this instance.
+ pub upgrades_policy: Policy,
+
+ /// Arguments to contract's instantiation function.
+ pub data: Vec<u8>,
+
+ /// Tokens that should be sent to the contract as part of the instantiate call.
+ pub tokens: Vec<token::BaseUnits>,
+}
+
+/// Instantiate call result.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct InstantiateResult {
+ /// Assigned instance identifier.
+ pub id: InstanceId,
+}
+
+/// Contract call.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct Call {
+ /// Instance identifier.
+ pub id: InstanceId,
+
+ /// Call arguments.
+ pub data: Vec<u8>,
+
+ /// Tokens that should be sent to the contract as part of the call.
+ pub tokens: Vec<token::BaseUnits>,
+}
+
+/// Contract call result.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+#[cbor(transparent)]
+pub struct CallResult(pub Vec<u8>);
+
+/// Upgrade call.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct Upgrade {
+ /// Instance identifier.
+ pub id: InstanceId,
+
+ /// Updated code identifier.
+ pub code_id: CodeId,
+
+ /// Arguments to contract's upgrade function.
+ pub data: Vec<u8>,
+
+ /// Tokens that should be sent to the contract as part of the call.
+ pub tokens: Vec<token::BaseUnits>,
+}
+
+/// Change upgrade policy call.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct ChangeUpgradePolicy {
+ /// Instance identifier.
+ pub id: InstanceId,
+
+ /// Updated upgrade policy.
+ pub upgrades_policy: Policy,
+}
+
+/// Code information query.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct CodeQuery {
+ /// Code identifier.
+ pub id: CodeId,
+}
+
+/// Code storage information query.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct CodeStorageQuery {
+ /// Code identifier.
+ pub id: CodeId,
+}
+
+/// Code storage query result.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct CodeStorageQueryResult {
+ /// Stored contract code.
+ pub code: Vec<u8>,
+}
+
+/// Instance information query.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct InstanceQuery {
+ /// Instance identifier.
+ pub id: InstanceId,
+}
+
+/// Instance storage query.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct InstanceStorageQuery {
+ /// Instance identifier.
+ pub id: InstanceId,
+
+ /// Storage key.
+ pub key: Vec<u8>,
+}
+
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct InstanceStorageQueryResult {
+ /// Storage value or `None` if key doesn't exist.
+ pub value: Option<Vec<u8>>,
+}
+
+/// Exposed wrapper for oasis-contract-sdk-types::StoreKind.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[repr(u32)]
+pub enum StoreKind {
+ Public = 0,
+ Confidential = 1,
+}
+
+/// Instance raw storage query.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct InstanceRawStorageQuery {
+ /// Instance identifier.
+ pub id: InstanceId,
+
+ /// Kind of the store to query.
+ pub store_kind: StoreKind,
+
+ /// Maximum number of items per page.
+ #[cbor(optional)]
+ pub limit: Option<u64>,
+
+ /// Number of skipped items.
+ #[cbor(optional)]
+ pub offset: Option<u64>,
+}
+
+/// Instance raw storage query result.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct InstanceRawStorageQueryResult {
+ /// List of key-value pairs in contract's public store.
+ pub items: Vec<(Vec<u8>, Vec<u8>)>,
+}
+
+/// Public key kind.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[repr(u8)]
+pub enum PublicKeyKind {
+ Transaction = 1,
+}
+
+/// Public key query.
+#[derive(Clone, Debug, cbor::Encode, cbor::Decode)]
+#[cbor(no_default)]
+pub struct PublicKeyQuery {
+ /// Instance identifier.
+ pub id: InstanceId,
+
+ /// Kind of public key.
+ pub kind: PublicKeyKind,
+}
+
+/// Public key query result.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct PublicKeyQueryResult {
+ /// Public key.
+ pub key: Vec<u8>,
+
+ /// Checksum of the key manager state.
+ pub checksum: Vec<u8>,
+
+ /// Sign(sk, (key || checksum)) from the key manager.
+ pub signature: Vec<u8>,
+}
+
+/// Custom contract query.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct CustomQuery {
+ /// Instance identifier.
+ pub id: InstanceId,
+
+ /// Query arguments.
+ pub data: Vec<u8>,
+}
+
+/// Custom query result.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+#[cbor(transparent)]
+pub struct CustomQueryResult(pub Vec<u8>);
+
+/// An event emitted from a contract, wrapped to include additional metadata.
+#[derive(Clone, Debug, Default, cbor::Encode, cbor::Decode)]
+pub struct ContractEvent {
+ /// Identifier of the instance that emitted the event.
+ pub id: InstanceId,
+ /// Raw event data emitted by the instance.
+ #[cbor(optional)]
+ pub data: Vec<u8>,
+}
+
+#[cfg(test)]
+mod test {
+ use super::*;
+
+ #[test]
+ fn test_instanceid_to_address() {
+ let tcs = vec![
+ (
+ InstanceId::from(0),
+ "oasis1qq08mjlkztsgpgrar082rzzxwjaplxmgjs5ftugn",
+ ),
+ (
+ InstanceId::from(1),
+ "oasis1qpg6jv8mxwlv4z578xyjxl7d793jamltdg9czzkx",
+ ),
+ (
+ InstanceId::from(14324),
+ "oasis1qzasj0kq0hlq6vzw4ajhrwgp3tqx6rnwvg2ylu2v",
+ ),
+ (
+ InstanceId::from(u64::MAX),
+ "oasis1qqr0nxsu5aqpu4k85z4h5z08vrfmawnnqycl6gup",
+ ),
+ ];
+
+ for (id, address) in tcs {
+ let instance_address = Instance::address_for(id);
+ assert_eq!(
+ instance_address.to_bech32(),
+ address.to_string(),
+ "instance address should match"
+ );
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +579 +580 +581 +582 +583 +584 +585 +586 +587 +588 +589 +590 +591 +592 +593 +594 +595 +596 +597 +598 +599 +600 +601 +602 +603 +604 +605 +606 +607 +608 +609 +610 +611 +612 +613 +614 +615 +616 +617 +618 +619 +620 +621 +622 +623 +624 +625 +
//! WASM runtime.
+use oasis_contract_sdk_types::message::Reply;
+use oasis_runtime_sdk::context::Context;
+
+use super::{
+ abi::{oasis::OasisV1, Abi, ExecutionContext, ExecutionResult, Info},
+ types, Config, Error, Parameters, MODULE_NAME,
+};
+
+/// Everything needed to run a contract.
+pub struct Contract<'a> {
+ pub code_info: &'a types::Code,
+ pub code: &'a [u8],
+ pub instance_info: &'a types::Instance,
+}
+
+/// Error emitted from within a contract.
+#[derive(Debug, thiserror::Error)]
+#[error("{message}")]
+pub struct ContractError {
+ pub module: String,
+ pub code: u32,
+ pub message: String,
+}
+
+impl ContractError {
+ /// Create a new error emitted within a contract.
+ pub fn new(code_id: types::CodeId, module: &str, code: u32, message: &str) -> Self {
+ Self {
+ module: if module.is_empty() {
+ format!("{}.{}", MODULE_NAME, code_id.as_u64())
+ } else {
+ format!("{}.{}.{}", MODULE_NAME, code_id.as_u64(), module)
+ },
+ code,
+ message: message.to_string(),
+ }
+ }
+}
+
+impl oasis_runtime_sdk::error::Error for ContractError {
+ fn module_name(&self) -> &str {
+ &self.module
+ }
+
+ fn code(&self) -> u32 {
+ self.code
+ }
+}
+
+/// Validate the passed contract code to make sure it conforms to the given ABI and perform any
+/// required transformation passes.
+pub(super) fn validate_and_transform<Cfg: Config, C: Context>(
+ code: &[u8],
+ abi: types::ABI,
+ params: &Parameters,
+) -> Result<(Vec<u8>, Info), Error> {
+ // Parse code.
+ let mut module = walrus::ModuleConfig::new()
+ .generate_producers_section(false)
+ .parse(code)
+ .map_err(|_| Error::CodeMalformed)?;
+
+ // Validate ABI selection and make sure the code conforms to the specified ABI.
+ let abi = create_abi::<Cfg, C>(abi)?;
+ let info = abi.validate(&mut module, params)?;
+
+ Ok((module.emit_wasm(), info))
+}
+
+/// Create a new WASM runtime and link the required functions based on the ABI then run the
+/// provided function passing the ABI and module instance.
+fn with_runtime<'ctx, Cfg, C, F>(
+ ctx: &mut ExecutionContext<'ctx, C>,
+ contract: &Contract<'_>,
+ f: F,
+) -> ExecutionResult
+where
+ Cfg: Config,
+ C: Context,
+ F: FnOnce(
+ &mut ExecutionContext<'ctx, C>,
+ &Box<dyn Abi<C>>,
+ &wasm3::Instance<'_, '_, ExecutionContext<'ctx, C>>,
+ ) -> ExecutionResult,
+{
+ let result = move || -> Result<ExecutionResult, Error> {
+ // Create the appropriate ABI.
+ let abi = create_abi::<Cfg, C>(contract.code_info.abi)?;
+
+ // Create the wasm3 environment, parse and instantiate the module.
+ let env =
+ wasm3::Environment::new().expect("creating a new wasm3 environment should succeed");
+ let module = env
+ .parse_module(contract.code)
+ .map_err(|_| Error::ModuleLoadingFailed)?;
+ let rt = env
+ .new_runtime::<ExecutionContext<'_, C>>(
+ ctx.params.max_stack_size,
+ Some(ctx.params.max_memory_pages),
+ )
+ .expect("creating a new wasm3 runtime should succeed");
+ let mut instance = rt
+ .load_module(module)
+ .map_err(|_| Error::ModuleLoadingFailed)?;
+
+ // Link functions based on the ABI.
+ abi.link(&mut instance)?;
+ // Set gas limit for the execution.
+ abi.set_gas_limit(&mut instance, ctx.gas_limit)?;
+
+ // Run the given function.
+ Ok(f(ctx, &abi, &instance))
+ }();
+
+ match result {
+ Ok(result) => result,
+ Err(err) => ExecutionResult {
+ inner: Err(err),
+ gas_used: 0,
+ },
+ }
+}
+
+/// Instantiate the contract.
+pub(super) fn instantiate<Cfg: Config, C: Context>(
+ ctx: &mut ExecutionContext<'_, C>,
+ contract: &Contract<'_>,
+ call: &types::Instantiate,
+) -> ExecutionResult {
+ with_runtime::<Cfg, _, _>(ctx, contract, |ctx, abi, instance| {
+ abi.instantiate(ctx, instance, &call.data, &call.tokens)
+ })
+}
+
+/// Call the contract.
+pub(super) fn call<Cfg: Config, C: Context>(
+ ctx: &mut ExecutionContext<'_, C>,
+ contract: &Contract<'_>,
+ call: &types::Call,
+) -> ExecutionResult {
+ with_runtime::<Cfg, _, _>(ctx, contract, |ctx, abi, instance| {
+ abi.call(ctx, instance, &call.data, &call.tokens)
+ })
+}
+
+/// Invoke the contract's reply handler.
+pub(super) fn handle_reply<Cfg: Config, C: Context>(
+ ctx: &mut ExecutionContext<'_, C>,
+ contract: &Contract<'_>,
+ reply: Reply,
+) -> ExecutionResult {
+ with_runtime::<Cfg, _, _>(ctx, contract, move |ctx, abi, instance| {
+ abi.handle_reply(ctx, instance, reply)
+ })
+}
+
+/// Invoke the contract's pre-upgrade handler.
+pub(super) fn pre_upgrade<Cfg: Config, C: Context>(
+ ctx: &mut ExecutionContext<'_, C>,
+ contract: &Contract<'_>,
+ upgrade: &types::Upgrade,
+) -> ExecutionResult {
+ with_runtime::<Cfg, _, _>(ctx, contract, |ctx, abi, instance| {
+ abi.pre_upgrade(ctx, instance, &upgrade.data, &upgrade.tokens)
+ })
+}
+
+/// Invoke the contract's post-upgrade handler.
+pub(super) fn post_upgrade<Cfg: Config, C: Context>(
+ ctx: &mut ExecutionContext<'_, C>,
+ contract: &Contract<'_>,
+ upgrade: &types::Upgrade,
+) -> ExecutionResult {
+ with_runtime::<Cfg, _, _>(ctx, contract, |ctx, abi, instance| {
+ abi.post_upgrade(ctx, instance, &upgrade.data, &upgrade.tokens)
+ })
+}
+
+/// Query the contract.
+pub(super) fn query<Cfg: Config, C: Context>(
+ ctx: &mut ExecutionContext<'_, C>,
+ contract: &Contract<'_>,
+ query: &types::CustomQuery,
+) -> ExecutionResult {
+ with_runtime::<Cfg, _, _>(ctx, contract, |ctx, abi, instance| {
+ abi.query(ctx, instance, &query.data)
+ })
+}
+
+/// Create the appropriate ABI based on contract configuration.
+fn create_abi<Cfg: Config, C: Context>(abi: types::ABI) -> Result<Box<dyn Abi<C>>, Error> {
+ match abi {
+ types::ABI::OasisV1 => Ok(Box::new(OasisV1::<Cfg>::new())),
+ }
+}
+
+#[cfg(all(feature = "benchmarks", test))]
+mod bench {
+ extern crate test;
+ use std::time::Instant;
+ use test::Bencher;
+
+ use crate::abi::gas;
+
+ // cargo build --target wasm32-unknown-unknown --release
+ const BENCH_CODE: &[u8] = include_bytes!(
+ "../../../../tests/contracts/bench/target/wasm32-unknown-unknown/release/bench.wasm"
+ );
+ const OPCODE_SPINS: i32 = 1_000_000;
+
+ fn bench_wat_spinner<F>(b: &mut Bencher, param: i32, code: &str, mut linkup: F)
+ where
+ F: FnMut(&mut wasm3::Instance<'_, '_, wasm3::CallContext<'_, ()>>),
+ {
+ let module_bin = wat::parse_str(code).expect("parsing module wat should succeed");
+ let env =
+ wasm3::Environment::new().expect("creating a new wasm3 environment should succeed");
+ let module = env
+ .parse_module(&module_bin)
+ .expect("parsing the code should succeed");
+ let rt: wasm3::Runtime<'_, wasm3::CallContext<'_, ()>> = env
+ .new_runtime(1 * 1024 * 1024, None)
+ .expect("creating a new wasm3 runtime should succeed");
+ let mut instance = rt
+ .load_module(module)
+ .expect("instance creation should succeed");
+ linkup(&mut instance);
+ let func = instance
+ .find_function::<i32, ()>("spinner")
+ .expect("finding the entrypoint function should succeed");
+ b.iter(|| {
+ func.call(param).expect("function call should succeed");
+ });
+ }
+
+ const LOOP_SKEL: &str = r#"
+ (module
+ (global $globaldummy (mut i32) (i32.const 0))
+ (func $spinner (param $lim i32) (local $dummy i32)
+ (loop $spin
+ local.get $lim
+ i32.const 1
+ i32.sub
+ local.tee $lim
+
+ ;; measure this block by comparing runtimes
+ ;; with the module in bench_loop_skel, where
+ ;; this section is empty.
+ {}
+
+ i32.const 0
+ i32.ne
+ br_if $spin
+ )
+ )
+ (export "spinner" (func $spinner))
+ )
+ "#;
+
+ #[bench]
+ fn bench_loop_skel(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace("{}", "");
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_const(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ i32.const 0
+ drop
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_block(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ (block $block
+ i32.const 0
+ drop
+ )
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_block_block(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ (block
+ (block
+ nop
+ )
+ )
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_br_table(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ (block
+ (block
+ i32.const 0
+ (br_table 1 2)
+ )
+ )
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_br(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ (block $block
+ i32.const 1
+ br $block
+ )
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_br_if(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ (block $block
+ i32.const 1
+ br_if $block
+ )
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_if_within_block(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ (block $block
+ i32.const 1
+ (if
+ (then
+ br $block
+ )
+ )
+ )
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_local_set(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ i32.const 42
+ local.set $dummy
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_global_get(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ global.get $globaldummy
+ drop
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_global_set(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ i32.const 1
+ global.set $globaldummy
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_grow_skel(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ local.get $lim
+ i32.const 100000
+ i32.rem_u
+ (if
+ (then
+ nop
+ nop
+ )
+ )
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_grow(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ local.get $lim
+ i32.const 100000
+ i32.rem_u
+ (if
+ (then
+ (memory.grow (i32.const 1))
+ drop
+ )
+ )
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_add(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ i32.const 0
+ i32.add
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_add_64(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ i64.extend_i32_u
+ i64.const 0
+ i64.add
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_mul(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ i32.const 1
+ i32.mul
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_div(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ i32.const 1
+ i32.div_s
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_rotr(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ i32.const 1
+ i32.rotr
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_extend(b: &mut Bencher) {
+ let src = LOOP_SKEL.replace(
+ "{}",
+ r#"
+ i32.const 3
+ i64.extend_i32_u
+ drop
+ "#,
+ );
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_call(b: &mut Bencher) {
+ let src = r#"
+ (module
+ (func $callee
+ return
+ )
+ (func $spinner (param $lim i32)
+ (loop $spin
+ local.get $lim
+ i32.const 1
+ i32.sub
+ local.tee $lim
+
+ ;; measure this block by comparing runtimes
+ ;; with the module in bench_loop_skel, where
+ ;; this section is empty.
+ call $callee
+
+ i32.const 0
+ i32.ne
+ br_if $spin
+ )
+ )
+ (export "spinner" (func $spinner))
+ )
+ "#;
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |_| {});
+ }
+
+ #[bench]
+ fn bench_loop_call_external(b: &mut Bencher) {
+ let src = r#"
+ (module
+ (import "bench" "callee" (func $callee))
+ (func $spinner (param $lim i32)
+ (loop $spin
+ local.get $lim
+ i32.const 1
+ i32.sub
+ local.tee $lim
+
+ ;; measure this block by comparing runtimes
+ ;; with the module in bench_loop_skel, where
+ ;; this section is empty.
+ call $callee
+
+ i32.const 0
+ i32.ne
+ br_if $spin
+ )
+ )
+ (export "spinner" (func $spinner))
+ )
+ "#;
+ bench_wat_spinner(b, OPCODE_SPINS, &src, |instance| {
+ let _ =
+ instance.link_function("bench", "callee", |_, _: ()| -> Result<(), wasm3::Trap> {
+ Ok(())
+ });
+ });
+ }
+
+ #[bench]
+ fn bench_time_waster(_b: &mut Bencher) {
+ let mut module = walrus::ModuleConfig::new()
+ .generate_producers_section(false)
+ .parse(&BENCH_CODE)
+ .unwrap();
+ gas::transform(&mut module);
+ let new_code = module.emit_wasm();
+
+ let env =
+ wasm3::Environment::new().expect("creating a new wasm3 environment should succeed");
+ let module = env
+ .parse_module(&new_code)
+ .expect("parsing the code should succeed");
+ let rt: wasm3::Runtime<'_, wasm3::CallContext<'_, ()>> = env
+ .new_runtime(1 * 1024 * 1024, None)
+ .expect("creating a new wasm3 runtime should succeed");
+ let instance = rt
+ .load_module(module)
+ .expect("instance creation should succeed");
+ let func = instance
+ .find_function::<u64, u64>("waste_time")
+ .expect("finding the entrypoint function should succeed");
+ let initial_gas = 1_000_000_000_000u64;
+ instance
+ .set_global(gas::EXPORT_GAS_LIMIT, initial_gas)
+ .expect("setting gas limit should succeed");
+ let begin = Instant::now();
+ func.call(41).expect("function call should succeed");
+ let gas_limit: u64 = instance
+ .get_global(gas::EXPORT_GAS_LIMIT)
+ .expect("getting gas limit global should succeed");
+ let gas_limit_exhausted: u64 = instance
+ .get_global(gas::EXPORT_GAS_LIMIT_EXHAUSTED)
+ .expect("getting gas limit exhausted global should succeed");
+ let delta = Instant::now().duration_since(begin).as_secs_f64();
+ println!(
+ " time waster runtime: {} seconds, gas remaining {} [used: {}, exhausted flag: {}]",
+ delta,
+ gas_limit,
+ initial_gas - gas_limit,
+ gas_limit_exhausted
+ );
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +
use darling::{util::Flag, FromDeriveInput, FromField, FromVariant};
+use proc_macro2::TokenStream;
+use quote::{format_ident, quote, quote_spanned};
+use syn::{DeriveInput, Ident, Index, Member, Path};
+
+use crate::generators::{self as gen, CodedVariant};
+
+#[derive(FromDeriveInput)]
+#[darling(supports(enum_any), attributes(sdk_error))]
+struct Error {
+ ident: Ident,
+
+ data: darling::ast::Data<ErrorVariant, darling::util::Ignored>,
+
+ /// The path to a const set to the module name.
+ module_name: Option<syn::Path>,
+
+ /// Whether to sequentially autonumber the error codes.
+ /// This option exists as a convenience for runtimes that
+ /// only append errors or release only breaking changes.
+ #[darling(rename = "autonumber")]
+ autonumber: Flag,
+
+ /// Whether the `into_abort` function should return itself. This can only be used when the type
+ /// being annotated is the dispatcher error type so it is only for internal use.
+ #[darling(rename = "abort_self")]
+ abort_self: Flag,
+}
+
+#[derive(FromVariant)]
+#[darling(attributes(sdk_error))]
+struct ErrorVariant {
+ ident: Ident,
+
+ fields: darling::ast::Fields<ErrorField>,
+
+ /// The explicit ID of the error code. Overrides any autonumber set on the error enum.
+ #[darling(rename = "code")]
+ code: Option<u32>,
+
+ #[darling(rename = "transparent")]
+ transparent: Flag,
+
+ #[darling(rename = "abort")]
+ abort: Flag,
+}
+
+impl CodedVariant for ErrorVariant {
+ const FIELD_NAME: &'static str = "code";
+
+ fn ident(&self) -> &Ident {
+ &self.ident
+ }
+
+ fn code(&self) -> Option<u32> {
+ self.code
+ }
+}
+
+#[derive(FromField)]
+#[darling(forward_attrs(source, from))]
+struct ErrorField {
+ ident: Option<Ident>,
+
+ attrs: Vec<syn::Attribute>,
+}
+
+pub fn derive_error(input: DeriveInput) -> TokenStream {
+ let error = match Error::from_derive_input(&input) {
+ Ok(error) => error,
+ Err(e) => return e.write_errors(),
+ };
+
+ let error_ty_ident = &error.ident;
+
+ let module_name = error
+ .module_name
+ .unwrap_or_else(|| syn::parse_quote!(MODULE_NAME));
+
+ let (module_name_body, code_body, abort_body) = convert_variants(
+ &format_ident!("self"),
+ module_name,
+ &error.data.as_ref().take_enum().unwrap(),
+ error.autonumber.is_present(),
+ error.abort_self.is_present(),
+ );
+
+ let sdk_crate = gen::sdk_crate_path();
+
+ gen::wrap_in_const(quote! {
+ use #sdk_crate::{self as __sdk, error::Error as _};
+
+ #[automatically_derived]
+ impl __sdk::error::Error for #error_ty_ident {
+ fn module_name(&self) -> &str {
+ #module_name_body
+ }
+
+ fn code(&self) -> u32 {
+ #code_body
+ }
+
+ fn into_abort(self) -> Result<__sdk::dispatcher::Error, Self> {
+ #abort_body
+ }
+ }
+
+ #[automatically_derived]
+ impl From<#error_ty_ident> for __sdk::error::RuntimeError {
+ fn from(err: #error_ty_ident) -> Self {
+ Self::new(err.module_name(), err.code(), &err.to_string())
+ }
+ }
+ })
+}
+
+fn convert_variants(
+ enum_binding: &Ident,
+ module_name: Path,
+ variants: &[&ErrorVariant],
+ autonumber: bool,
+ abort_self: bool,
+) -> (TokenStream, TokenStream, TokenStream) {
+ if variants.is_empty() {
+ return (quote!(#module_name), quote!(0), quote!(Err(#enum_binding)));
+ }
+
+ let mut next_autonumber = 0u32;
+ let mut reserved_numbers = std::collections::BTreeSet::new();
+
+ let (module_name_matches, (code_matches, abort_matches)): (Vec<_>, (Vec<_>, Vec<_>)) = variants
+ .iter()
+ .map(|variant| {
+ let variant_ident = &variant.ident;
+
+ if variant.transparent.is_present() {
+ // Transparently forward everything to the source.
+ let mut maybe_sources = variant
+ .fields
+ .iter()
+ .enumerate()
+ .filter(|(_, f)| (!f.attrs.is_empty()))
+ .map(|(i, f)| (i, f.ident.clone()));
+ let source = maybe_sources.next();
+ if maybe_sources.count() != 0 {
+ variant_ident
+ .span()
+ .unwrap()
+ .error("multiple error sources specified for variant")
+ .emit();
+ return (quote!(), (quote!(), quote!()));
+ }
+ if source.is_none() {
+ variant_ident
+ .span()
+ .unwrap()
+ .error("no source error specified for variant")
+ .emit();
+ return (quote!(), (quote!(), quote!()));
+ }
+ let (field_index, field_ident) = source.unwrap();
+
+ let field = match field_ident {
+ Some(ident) => Member::Named(ident),
+ None => Member::Unnamed(Index {
+ index: field_index as u32,
+ span: variant_ident.span(),
+ }),
+ };
+
+ // Get all other fields that are needed for forwarding in abort variants.
+ let non_source_fields = variant
+ .fields
+ .iter()
+ .enumerate()
+ .filter(|(i, _)| i != &field_index)
+ .map(|(i, f)| {
+ let pat = match f.ident {
+ Some(ref ident) => Member::Named(ident.clone()),
+ None => Member::Unnamed(Index {
+ index: i as u32,
+ span: variant_ident.span(),
+ }),
+ };
+ let ident = Ident::new(&format!("__a{i}"), variant_ident.span());
+ let binding = quote!( #pat: #ident, );
+
+ binding
+ });
+ let non_source_field_bindings = non_source_fields.clone();
+
+ let source = quote!(source);
+ let module_name = quote_spanned!(variant_ident.span()=> #source.module_name());
+ let code = quote_spanned!(variant_ident.span()=> #source.code());
+ let abort_reclaim = quote!(Self::#variant_ident { #field: e, #(#non_source_fields)* });
+ let abort = quote_spanned!(variant_ident.span()=> #source.into_abort().map_err(|e| #abort_reclaim));
+
+ (
+ quote! {
+ Self::#variant_ident { #field: #source, .. } => #module_name,
+ },
+ (
+ quote! {
+ Self::#variant_ident { #field: #source, .. } => #code,
+ },
+ quote! {
+ Self::#variant_ident { #field: #source, #(#non_source_field_bindings)* } => #abort,
+ },
+ ),
+ )
+ } else {
+ // Regular case without forwarding.
+ let code = match variant.code {
+ Some(code) => {
+ if reserved_numbers.contains(&code) {
+ variant_ident
+ .span()
+ .unwrap()
+ .error(format!("code {code} already used"))
+ .emit();
+ return (quote!(), (quote!(), quote!()));
+ }
+ reserved_numbers.insert(code);
+ code
+ }
+ None if autonumber => {
+ let mut reserved_successors = reserved_numbers.range(next_autonumber..);
+ while reserved_successors.next() == Some(&next_autonumber) {
+ next_autonumber += 1;
+ }
+ let code = next_autonumber;
+ reserved_numbers.insert(code);
+ next_autonumber += 1;
+ code
+ }
+ None => {
+ variant_ident
+ .span()
+ .unwrap()
+ .error("missing `code` for variant")
+ .emit();
+ return (quote!(), (quote!(), quote!()));
+ }
+ };
+
+ let abort = if variant.abort.is_present() {
+ quote!{
+ Self::#variant_ident(err) => Ok(err),
+ }
+ } else {
+ quote!{
+ Self::#variant_ident { .. } => Err(#enum_binding),
+ }
+ };
+
+ (
+ quote! {
+ Self::#variant_ident { .. } => #module_name,
+ },
+ (
+ quote! {
+ Self::#variant_ident { .. } => #code,
+ },
+ abort,
+ ),
+ )
+ }
+ })
+ .unzip();
+
+ let abort_body = if abort_self {
+ quote!(Ok(self))
+ } else {
+ quote! {
+ match #enum_binding {
+ #(#abort_matches)*
+ }
+ }
+ };
+
+ (
+ quote! {
+ match #enum_binding {
+ #(#module_name_matches)*
+ }
+ },
+ quote! {
+ match #enum_binding {
+ #(#code_matches)*
+ }
+ },
+ abort_body,
+ )
+}
+
+#[cfg(test)]
+mod tests {
+ #[test]
+ fn generate_error_impl_auto_abort() {
+ let expected: syn::Stmt = syn::parse_quote!(
+ const _: () = {
+ use ::oasis_runtime_sdk::{self as __sdk, error::Error as _};
+ #[automatically_derived]
+ impl __sdk::error::Error for Error {
+ fn module_name(&self) -> &str {
+ match self {
+ Self::Error0 { .. } => MODULE_NAME,
+ Self::Error2 { .. } => MODULE_NAME,
+ Self::Error1 { .. } => MODULE_NAME,
+ Self::Error3 { .. } => MODULE_NAME,
+ Self::ErrorAbort { .. } => MODULE_NAME,
+ }
+ }
+ fn code(&self) -> u32 {
+ match self {
+ Self::Error0 { .. } => 0u32,
+ Self::Error2 { .. } => 2u32,
+ Self::Error1 { .. } => 1u32,
+ Self::Error3 { .. } => 3u32,
+ Self::ErrorAbort { .. } => 4u32,
+ }
+ }
+ fn into_abort(self) -> Result<__sdk::dispatcher::Error, Self> {
+ match self {
+ Self::Error0 { .. } => Err(self),
+ Self::Error2 { .. } => Err(self),
+ Self::Error1 { .. } => Err(self),
+ Self::Error3 { .. } => Err(self),
+ Self::ErrorAbort(err) => Ok(err),
+ }
+ }
+ }
+ #[automatically_derived]
+ impl From<Error> for __sdk::error::RuntimeError {
+ fn from(err: Error) -> Self {
+ Self::new(err.module_name(), err.code(), &err.to_string())
+ }
+ }
+ };
+ );
+
+ let input: syn::DeriveInput = syn::parse_quote!(
+ #[derive(Error)]
+ #[sdk_error(autonumber)]
+ pub enum Error {
+ Error0,
+ #[sdk_error(code = 2)]
+ Error2 {
+ payload: Vec<u8>,
+ },
+ Error1(String),
+ Error3,
+ #[sdk_error(abort)]
+ ErrorAbort(sdk::dispatcher::Error),
+ }
+ );
+ let error_derivation = super::derive_error(input);
+ let actual: syn::Stmt = syn::parse2(error_derivation).unwrap();
+
+ crate::assert_empty_diff!(actual, expected);
+ }
+
+ #[test]
+ fn generate_error_impl_manual() {
+ let expected: syn::Stmt = syn::parse_quote!(
+ const _: () = {
+ use ::oasis_runtime_sdk::{self as __sdk, error::Error as _};
+ #[automatically_derived]
+ impl __sdk::error::Error for Error {
+ fn module_name(&self) -> &str {
+ THE_MODULE_NAME
+ }
+ fn code(&self) -> u32 {
+ 0
+ }
+ fn into_abort(self) -> Result<__sdk::dispatcher::Error, Self> {
+ Err(self)
+ }
+ }
+ #[automatically_derived]
+ impl From<Error> for __sdk::error::RuntimeError {
+ fn from(err: Error) -> Self {
+ Self::new(err.module_name(), err.code(), &err.to_string())
+ }
+ }
+ };
+ );
+
+ let input: syn::DeriveInput = syn::parse_quote!(
+ #[derive(Error)]
+ #[sdk_error(autonumber, module_name = "THE_MODULE_NAME")]
+ pub enum Error {}
+ );
+ let error_derivation = super::derive_error(input);
+ let actual: syn::Stmt = syn::parse2(error_derivation).unwrap();
+
+ crate::assert_empty_diff!(actual, expected);
+ }
+
+ #[test]
+ fn generate_error_impl_from() {
+ let expected: syn::Stmt = syn::parse_quote!(
+ const _: () = {
+ use ::oasis_runtime_sdk::{self as __sdk, error::Error as _};
+ #[automatically_derived]
+ impl __sdk::error::Error for Error {
+ fn module_name(&self) -> &str {
+ match self {
+ Self::Foo { 0: source, .. } => source.module_name(),
+ }
+ }
+ fn code(&self) -> u32 {
+ match self {
+ Self::Foo { 0: source, .. } => source.code(),
+ }
+ }
+ fn into_abort(self) -> Result<__sdk::dispatcher::Error, Self> {
+ match self {
+ Self::Foo { 0: source } => {
+ source.into_abort().map_err(|e| Self::Foo { 0: e })
+ }
+ }
+ }
+ }
+ #[automatically_derived]
+ impl From<Error> for __sdk::error::RuntimeError {
+ fn from(err: Error) -> Self {
+ Self::new(err.module_name(), err.code(), &err.to_string())
+ }
+ }
+ };
+ );
+
+ let input: syn::DeriveInput = syn::parse_quote!(
+ #[derive(Error)]
+ #[sdk_error(module_name = "THE_MODULE_NAME")]
+ pub enum Error {
+ #[sdk_error(transparent)]
+ Foo(#[from] AnotherError),
+ }
+ );
+ let error_derivation = super::derive_error(input);
+ let actual: syn::Stmt = syn::parse2(error_derivation).unwrap();
+
+ crate::assert_empty_diff!(actual, expected);
+ }
+
+ #[test]
+ fn generate_error_impl_abort_self() {
+ let expected: syn::Stmt = syn::parse_quote!(
+ const _: () = {
+ use ::oasis_runtime_sdk::{self as __sdk, error::Error as _};
+ #[automatically_derived]
+ impl __sdk::error::Error for Error {
+ fn module_name(&self) -> &str {
+ match self {
+ Self::Foo { .. } => THE_MODULE_NAME,
+ Self::Bar { .. } => THE_MODULE_NAME,
+ }
+ }
+ fn code(&self) -> u32 {
+ match self {
+ Self::Foo { .. } => 1u32,
+ Self::Bar { .. } => 2u32,
+ }
+ }
+ fn into_abort(self) -> Result<__sdk::dispatcher::Error, Self> {
+ Ok(self)
+ }
+ }
+ #[automatically_derived]
+ impl From<Error> for __sdk::error::RuntimeError {
+ fn from(err: Error) -> Self {
+ Self::new(err.module_name(), err.code(), &err.to_string())
+ }
+ }
+ };
+ );
+
+ let input: syn::DeriveInput = syn::parse_quote!(
+ #[derive(Error)]
+ #[sdk_error(module_name = "THE_MODULE_NAME", abort_self)]
+ pub enum Error {
+ #[sdk_error(code = 1)]
+ Foo,
+ #[sdk_error(code = 2)]
+ Bar,
+ }
+ );
+ let error_derivation = super::derive_error(input);
+ let actual: syn::Stmt = syn::parse2(error_derivation).unwrap();
+
+ crate::assert_empty_diff!(actual, expected);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +
use darling::{util::Flag, FromDeriveInput, FromVariant};
+use proc_macro2::TokenStream;
+use quote::{format_ident, quote};
+use syn::{DeriveInput, Ident};
+
+use crate::generators::{self as gen, CodedVariant};
+
+#[derive(FromDeriveInput)]
+#[darling(supports(enum_any), attributes(sdk_event))]
+struct Event {
+ ident: Ident,
+
+ data: darling::ast::Data<EventVariant, darling::util::Ignored>,
+
+ /// The path to a const set to the module name.
+ module_name: Option<syn::Path>,
+
+ /// Whether to sequentially autonumber the event codes.
+ /// This option exists as a convenience for runtimes that
+ /// only append events or release only breaking changes.
+ #[darling(rename = "autonumber")]
+ autonumber: Flag,
+}
+
+#[derive(FromVariant)]
+#[darling(attributes(sdk_event))]
+struct EventVariant {
+ ident: Ident,
+
+ /// The explicit ID of the event code. Overrides any autonumber set on the event enum.
+ #[darling(rename = "code")]
+ code: Option<u32>,
+}
+
+impl CodedVariant for EventVariant {
+ const FIELD_NAME: &'static str = "code";
+
+ fn ident(&self) -> &Ident {
+ &self.ident
+ }
+
+ fn code(&self) -> Option<u32> {
+ self.code
+ }
+}
+
+pub fn derive_event(input: DeriveInput) -> TokenStream {
+ let event = match Event::from_derive_input(&input) {
+ Ok(event) => event,
+ Err(e) => return e.write_errors(),
+ };
+
+ let event_ty_ident = &event.ident;
+ let module_name = event
+ .module_name
+ .unwrap_or_else(|| syn::parse_quote!(MODULE_NAME));
+
+ let code_converter = gen::enum_code_converter(
+ &format_ident!("self"),
+ &event.data.as_ref().take_enum().unwrap(),
+ event.autonumber.is_present(),
+ );
+
+ let sdk_crate = gen::sdk_crate_path();
+
+ gen::wrap_in_const(quote! {
+ impl #sdk_crate::event::Event for #event_ty_ident {
+ fn module_name() -> &'static str {
+ #module_name
+ }
+
+ fn code(&self) -> u32 {
+ #code_converter
+ }
+ }
+ })
+}
+
+#[cfg(test)]
+mod tests {
+ #[test]
+ fn generate_event_impl_auto() {
+ let expected: syn::Stmt = syn::parse_quote!(
+ const _: () = {
+ impl ::oasis_runtime_sdk::event::Event for MainEvent {
+ fn module_name() -> &'static str {
+ MODULE_NAME
+ }
+ fn code(&self) -> u32 {
+ match self {
+ Self::Event0 { .. } => 0u32,
+ Self::Event2 { .. } => 2u32,
+ Self::Event1 { .. } => 1u32,
+ Self::Event3 { .. } => 3u32,
+ }
+ }
+ }
+ };
+ );
+
+ let input: syn::DeriveInput = syn::parse_quote!(
+ #[derive(Event)]
+ #[sdk_event(autonumber)]
+ pub enum MainEvent {
+ Event0,
+ #[sdk_event(code = 2)]
+ Event2 {
+ payload: Vec<u8>,
+ },
+ Event1(String),
+ Event3,
+ }
+ );
+ let event_derivation = super::derive_event(input);
+ let actual: syn::Stmt = syn::parse2(event_derivation).unwrap();
+
+ crate::assert_empty_diff!(actual, expected);
+ }
+
+ #[test]
+ fn generate_event_impl_manual() {
+ let expected: syn::Stmt = syn::parse_quote!(
+ const _: () = {
+ impl ::oasis_runtime_sdk::event::Event for MainEvent {
+ fn module_name() -> &'static str {
+ THE_MODULE_NAME
+ }
+ fn code(&self) -> u32 {
+ 0
+ }
+ }
+ };
+ );
+
+ let input: syn::DeriveInput = syn::parse_quote!(
+ #[derive(Event)]
+ #[sdk_event(autonumber, module_name = "THE_MODULE_NAME")]
+ pub enum MainEvent {}
+ );
+ let event_derivation = super::derive_event(input);
+ let actual: syn::Stmt = syn::parse2(event_derivation).unwrap();
+
+ crate::assert_empty_diff!(actual, expected);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +
use proc_macro2::TokenStream;
+use quote::quote;
+use syn::Ident;
+
+/// Wraps the given code block into an anonymous const code block. Useful when
+/// the code block `use`s stuff that should not leak into the containing scope.
+/// See also https://github.com/serde-rs/serde/issues/159#issuecomment-214002626
+pub fn wrap_in_const(tokens: TokenStream) -> TokenStream {
+ quote! {
+ const _: () = {
+ #tokens
+ };
+ }
+}
+
+/// Determines what crate name should be used to refer to `oasis_runtime_sdk` types.
+/// Required for use within the SDK itself (crates cannot refer to their own names).
+pub fn sdk_crate_path() -> syn::Path {
+ let is_internal = std::env::var("CARGO_PKG_NAME")
+ .map(|pkg_name| pkg_name == "oasis-runtime-sdk")
+ .unwrap_or_default();
+ if is_internal {
+ // Doctests are their own crates, but they share the name of the primary crate.
+ // Thus, the primary crate needs to refer to itself. Either that or depend on unstable
+ // rustdoc env vars.
+ syn::parse_quote!(crate::oasis_runtime_sdk)
+ } else {
+ syn::parse_quote!(::oasis_runtime_sdk)
+ }
+}
+
+pub trait CodedVariant {
+ /// The field in the helper attribute that yields the value provided by `code`.
+ /// For instance, in `#[sdk_event(code = 0)]`, the `FIELD_NAME` would be `code`.
+ const FIELD_NAME: &'static str;
+
+ /// The variant ident.
+ fn ident(&self) -> &Ident;
+
+ /// The code to which the variant should be converted.
+ fn code(&self) -> Option<u32>;
+}
+
+/// Returns a `match` expression that encodes an enum's variants as integral codes.
+pub fn enum_code_converter<V: CodedVariant>(
+ enum_binding: &Ident,
+ variants: &[&V],
+ autonumber: bool,
+) -> TokenStream {
+ if variants.is_empty() {
+ return quote!(0); // Early return with default if there are no variants.
+ }
+
+ let mut next_autonumber = 0u32;
+ let mut reserved_numbers = std::collections::BTreeSet::new();
+ let match_arms = variants.iter().map(|variant| {
+ let variant_ident = variant.ident();
+ let code = match variant.code() {
+ Some(code) => {
+ if reserved_numbers.contains(&code) {
+ variant_ident
+ .span()
+ .unwrap()
+ .error(format!("code {code} already used"))
+ .emit();
+ return quote!({});
+ }
+ reserved_numbers.insert(code);
+ code
+ }
+ None if autonumber => {
+ let mut reserved_successors = reserved_numbers.range(next_autonumber..);
+ while reserved_successors.next() == Some(&next_autonumber) {
+ next_autonumber += 1;
+ }
+ let code = next_autonumber;
+ reserved_numbers.insert(code);
+ next_autonumber += 1;
+ code
+ }
+ None => {
+ variant_ident
+ .span()
+ .unwrap()
+ .error(format!("missing `{}` for variant", V::FIELD_NAME))
+ .emit();
+ return quote!();
+ }
+ };
+ quote!(Self::#variant_ident { .. } => { #code })
+ });
+ quote! {
+ match #enum_binding {
+ #(#match_arms)*
+ }
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn generate_empty_enum_converter() {
+ struct DummyVariant {}
+ impl CodedVariant for DummyVariant {
+ const FIELD_NAME: &'static str = "code";
+ fn ident(&self) -> &Ident {
+ unimplemented!()
+ }
+ fn code(&self) -> Option<u32> {
+ unimplemented!()
+ }
+ }
+ let variants: &[&DummyVariant] = &[];
+
+ let expected: syn::Expr = syn::parse_quote!(0);
+ let converter = enum_code_converter("e::format_ident!("the_enum"), variants, false);
+ let actual: syn::Expr = syn::parse2(converter).unwrap();
+ assert_eq!(expected, actual);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +
#![feature(proc_macro_diagnostic)]
+#![deny(rust_2018_idioms)]
+
+use proc_macro::TokenStream;
+
+mod error_derive;
+mod event_derive;
+mod generators;
+mod module_derive;
+#[cfg(test)]
+mod test_utils;
+mod version_from_cargo;
+
+/// Emits a compile-time error `msg` from a macro, and uses the span of the
+/// macro invocation if possible. If span info is not available (should only
+/// happen in unit tests), panics with `msg`.
+fn emit_compile_error<S: Into<String> + Clone + std::panic::RefUnwindSafe>(msg: S) -> ! {
+ std::panic::catch_unwind(|| {
+ proc_macro2::Span::call_site()
+ .unwrap()
+ .error(msg.clone().into())
+ .emit();
+ })
+ .ok()
+ .or_else(|| {
+ panic!("{}", msg.into());
+ });
+ unreachable!(); // error().emit() already halts compilation, but type checker doesn't know that
+}
+
+/// Derives the `Event` trait on an enum.
+#[proc_macro_derive(Event, attributes(sdk_event))]
+pub fn event_derive(input: TokenStream) -> TokenStream {
+ let input = syn::parse_macro_input!(input as syn::DeriveInput);
+ event_derive::derive_event(input).into()
+}
+
+/// Derives the `Error` trait on an enum.
+// The helper attribute is `sdk_error` to avoid conflict with `thiserror::Error`.
+#[proc_macro_derive(Error, attributes(sdk_error, source, from))]
+pub fn error_derive(input: TokenStream) -> TokenStream {
+ let input = syn::parse_macro_input!(input as syn::DeriveInput);
+ error_derive::derive_error(input).into()
+}
+
+/// Derives traits from a non-trait `impl` block (rather than from a `struct`).
+///
+/// Only the `Module` trait is supported. In other words, given an `impl MyModule` block, the macro
+/// derives implementations needed for implementing a module.
+/// See also the `#[handler]` and `#[migration]` attributes.
+#[proc_macro_attribute]
+pub fn sdk_derive(args: TokenStream, input: TokenStream) -> TokenStream {
+ let input = syn::parse_macro_input!(input as syn::ItemImpl);
+ if args.to_string() == "Module" {
+ module_derive::derive_module(input).into()
+ } else {
+ emit_compile_error("#[sdk_derive] only supports #[sdk_derive(Module)]");
+ }
+}
+
+/// A helper attribute for `#[sdk_derive(...)]`. It doesn't do anyting on its own;
+/// it only marks functions that represent a paratime method handler.
+/// The permitted forms are:
+/// - `#[handler(call = "my_module.MyCall")]`: Marks a function that handles
+/// the "my_module.MyCall" call and can be passed to
+/// oasis_runtime_sdk::module::dispatch_call.
+/// - `#[handler(prefetch = "my_module.MyCall")]`: Marks a function that handles
+/// the request to prefetch any data ahead of the "my_module.MyCall" call.
+/// Its signature should be `Fn(
+/// add_prefix: &mut dyn FnMut(Prefix) -> (),
+/// body: cbor::Value,
+/// auth_info: &AuthInfo,
+/// ) -> Result<(), oasis_runtime_sdk::error::RuntimeError>`
+/// - `#[handler(query = "my_module.MyQuery")]`: Marks a function that handles
+/// the "my_module.MyQuery" query and can be passed to
+/// oasis_runtime_sdk::module::dispatch_query.
+/// - `#[handler(message_result = "my_module.MyMR")]`: Marks a function that handles
+/// the "my_module.MyMR" message result and can be passed to
+/// oasis_runtime_sdk::module::dispatch_message_result.
+///
+/// Query handler can also contain the `expensive` tag. Example:
+/// `#[handler(query = "my_module.MyQuery", expensive)]`.
+/// Queries tagged `expensive` can be enabled/disabled are disabled by default to avoid
+/// excessive costs to the node operator. This can be overridden in the node config.
+///
+/// NOTE: This attribute is parsed by the `#[sdk_derive(...)]` macro, which cannot
+/// interpret the attribute name semantically. Use `#[handler]`, not
+/// `#[oasis_runtime_sdk_macros::handler]` or other paths/aliases.
+#[proc_macro_attribute]
+pub fn handler(_args: TokenStream, input: TokenStream) -> TokenStream {
+ input
+}
+
+/// A helper attribute for `#[sdk_derive(...)]`. It doesn't do anything on its own;
+/// it only marks functions that represent a module state migration.
+///
+/// The permitted forms are:
+/// - `#[migration(init)]`: Marks the initial (genesis) migration.
+/// - `#[migration(from = v)]`: Marks a migration from version v to v+1, where v is
+/// a non-negative integer.
+#[proc_macro_attribute]
+pub fn migration(_args: TokenStream, input: TokenStream) -> TokenStream {
+ input
+}
+
+/// Constructs an `oasis_sdk::core::common::version::Version` from the Cargo.toml version.
+#[proc_macro]
+pub fn version_from_cargo(_input: TokenStream) -> TokenStream {
+ version_from_cargo::version_from_cargo().into()
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +
use proc_macro2::TokenStream;
+use quote::quote;
+use syn::parse_quote;
+
+use crate::emit_compile_error;
+
+/// Deriver for the `MethodHandler` trait.
+pub struct DeriveMethodHandler {
+ handlers: Vec<ParsedImplItem>,
+}
+
+impl DeriveMethodHandler {
+ pub fn new() -> Box<Self> {
+ Box::new(Self { handlers: vec![] })
+ }
+}
+
+impl super::Deriver for DeriveMethodHandler {
+ fn preprocess(&mut self, item: syn::ImplItem) -> Option<syn::ImplItem> {
+ let method = match item {
+ syn::ImplItem::Fn(ref f) => f,
+ _ => return Some(item),
+ };
+
+ let attrs = if let Some(attrs) = parse_attrs(&method.attrs) {
+ attrs
+ } else {
+ return Some(item);
+ };
+
+ self.handlers.push(ParsedImplItem {
+ handler: Some(HandlerInfo {
+ attrs,
+ ident: method.sig.ident.clone(),
+ }),
+ item,
+ });
+
+ None // Take the item.
+ }
+
+ fn derive(&mut self, generics: &syn::Generics, ty: &Box<syn::Type>) -> TokenStream {
+ let handlers = &self.handlers;
+ let handler_items = handlers
+ .iter()
+ .map(|ParsedImplItem { item, .. }| item)
+ .collect::<Vec<_>>();
+
+ /// Generates parallel vectors of rpc names and handler idents for all handlers of kind `kind`.
+ fn filter_by_kind(
+ handlers: &[ParsedImplItem],
+ kind: HandlerKind,
+ ) -> (Vec<syn::Expr>, Vec<syn::Ident>) {
+ handlers
+ .iter()
+ .filter_map(|h| h.handler.as_ref())
+ .filter(|h| h.attrs.kind == kind)
+ .map(|h| (h.attrs.rpc_name.clone(), h.ident.clone()))
+ .unzip()
+ }
+
+ let prefetch_impl = {
+ let (handler_names, handler_idents) = filter_by_kind(handlers, HandlerKind::Prefetch);
+
+ // Find call handlers; for every call handler without a corresponding prefetch handler, we'll
+ // generate a dummy prefetch handler.
+ let (call_handler_names, _) = filter_by_kind(handlers, HandlerKind::Call);
+ let handler_names_without_impl: Vec<&syn::Expr> = call_handler_names
+ .iter()
+ .filter(|n| !handler_names.contains(n))
+ .collect();
+
+ if handler_names.is_empty() {
+ quote! {}
+ } else {
+ quote! {
+ fn prefetch(
+ prefixes: &mut BTreeSet<Prefix>,
+ method: &str,
+ body: cbor::Value,
+ auth_info: &AuthInfo,
+ ) -> module::DispatchResult<cbor::Value, Result<(), sdk::error::RuntimeError>> {
+ let mut add_prefix = |p| {prefixes.insert(p);};
+ match method {
+ // "Real", user-defined prefetch handlers.
+ #(
+ #handler_names => module::DispatchResult::Handled(
+ Self::#handler_idents(&mut add_prefix, body, auth_info)
+ ),
+ )*
+ // No-op prefetch handlers.
+ #(
+ #handler_names_without_impl => module::DispatchResult::Handled(Ok(())),
+ )*
+ _ => module::DispatchResult::Unhandled(body),
+ }
+ }
+ }
+ }
+ };
+
+ let dispatch_call_impl = {
+ let (handler_names, handler_fns): (Vec<_>, Vec<_>) = handlers
+ .iter()
+ .filter_map(|h| h.handler.as_ref())
+ .filter(|h| h.attrs.kind == HandlerKind::Call)
+ .map(|h| {
+ (h.attrs.rpc_name.clone(), {
+ let ident = &h.ident;
+
+ if h.attrs.is_internal {
+ quote! {
+ |ctx, body| {
+ if !sdk::state::CurrentState::with_env(|env| env.is_internal()) {
+ return Err(sdk::modules::core::Error::Forbidden.into());
+ }
+ Self::#ident(ctx, body)
+ }
+ }
+ } else {
+ quote! { Self::#ident }
+ }
+ })
+ })
+ .unzip();
+
+ if handler_names.is_empty() {
+ quote! {}
+ } else {
+ quote! {
+ fn dispatch_call<C: Context>(
+ ctx: &C,
+ method: &str,
+ body: cbor::Value,
+ ) -> DispatchResult<cbor::Value, CallResult> {
+ match method {
+ #(
+ #handler_names => module::dispatch_call(ctx, body, #handler_fns),
+ )*
+ _ => DispatchResult::Unhandled(body),
+ }
+ }
+ }
+ }
+ };
+
+ let query_parameters_impl = {
+ quote! {
+ fn query_parameters<C: Context>(_ctx: &C, _args: ()) -> Result<<Self as module::Module>::Parameters, <Self as module::Module>::Error> {
+ Ok(Self::params())
+ }
+ }
+ };
+
+ let dispatch_query_impl = {
+ let (handler_names, handler_idents) = filter_by_kind(handlers, HandlerKind::Query);
+
+ if handler_names.is_empty() {
+ quote! {
+ fn dispatch_query<C: Context>(
+ ctx: &C,
+ method: &str,
+ args: cbor::Value,
+ ) -> DispatchResult<cbor::Value, Result<cbor::Value, sdk::error::RuntimeError>> {
+ match method {
+ q if q == format!("{}.Parameters", Self::NAME) => module::dispatch_query(ctx, args, Self::query_parameters),
+ _ => DispatchResult::Unhandled(args),
+ }
+ }
+ }
+ } else {
+ quote! {
+ fn dispatch_query<C: Context>(
+ ctx: &C,
+ method: &str,
+ args: cbor::Value,
+ ) -> DispatchResult<cbor::Value, Result<cbor::Value, sdk::error::RuntimeError>> {
+ match method {
+ #(
+ #handler_names => module::dispatch_query(ctx, args, Self::#handler_idents),
+ )*
+ q if q == format!("{}.Parameters", Self::NAME) => module::dispatch_query(ctx, args, Self::query_parameters),
+ _ => DispatchResult::Unhandled(args),
+ }
+ }
+ }
+ }
+ };
+
+ let dispatch_message_result_impl = {
+ let (handler_names, handler_idents) =
+ filter_by_kind(handlers, HandlerKind::MessageResult);
+
+ if handler_names.is_empty() {
+ quote! {}
+ } else {
+ quote! {
+ fn dispatch_message_result<C: Context>(
+ ctx: &C,
+ handler_name: &str,
+ result: MessageResult,
+ ) -> DispatchResult<MessageResult, ()> {
+ match handler_name {
+ #(
+ #handler_names => {
+ Self::#handler_idents(
+ ctx,
+ result.event,
+ cbor::from_value(result.context).expect("invalid message handler context"),
+ );
+ DispatchResult::Handled(())
+ }
+ )*
+ _ => DispatchResult::Unhandled(result),
+ }
+ }
+ }
+ }
+ };
+
+ let supported_methods_impl = {
+ let (handler_names, handler_kinds): (Vec<syn::Expr>, Vec<syn::Path>) = handlers
+ .iter()
+ .filter_map(|h| h.handler.as_ref())
+ // `prefetch` is an implementation detail of `call` handlers, so we don't list them
+ .filter(|h| h.attrs.kind != HandlerKind::Prefetch)
+ .map(|h| (h.attrs.rpc_name.clone(), h.attrs.kind.as_sdk_ident()))
+ .unzip();
+ if handler_names.is_empty() {
+ quote! {}
+ } else {
+ quote! {
+ fn supported_methods() -> Vec<core_types::MethodHandlerInfo> {
+ vec![ #(
+ core_types::MethodHandlerInfo {
+ kind: #handler_kinds,
+ name: #handler_names.to_string(),
+ },
+ )* ]
+ }
+ }
+ }
+ };
+
+ let expensive_queries_impl = {
+ let handler_names: Vec<syn::Expr> = handlers
+ .iter()
+ .filter_map(|h| h.handler.as_ref())
+ .filter(|h| h.attrs.kind == HandlerKind::Query && h.attrs.is_expensive)
+ .map(|h| h.attrs.rpc_name.clone())
+ .collect();
+ if handler_names.is_empty() {
+ quote! {}
+ } else {
+ quote! {
+ fn is_expensive_query(method: &str) -> bool {
+ [ #( #handler_names, )* ].contains(&method)
+ }
+ }
+ }
+ };
+
+ let allowed_private_km_queries_impl = {
+ let handler_names: Vec<syn::Expr> = handlers
+ .iter()
+ .filter_map(|h| h.handler.as_ref())
+ .filter(|h| h.attrs.kind == HandlerKind::Query && h.attrs.allow_private_km)
+ .map(|h| h.attrs.rpc_name.clone())
+ .collect();
+ if handler_names.is_empty() {
+ quote! {}
+ } else {
+ quote! {
+ fn is_allowed_private_km_query(method: &str) -> bool {
+ [ #( #handler_names, )* ].contains(&method)
+ }
+ }
+ }
+ };
+
+ let allowed_interactive_calls_impl = {
+ let handler_names: Vec<syn::Expr> = handlers
+ .iter()
+ .filter_map(|h| h.handler.as_ref())
+ .filter(|h| h.attrs.kind == HandlerKind::Call && h.attrs.allow_interactive)
+ .map(|h| h.attrs.rpc_name.clone())
+ .collect();
+ if handler_names.is_empty() {
+ quote! {}
+ } else {
+ quote! {
+ fn is_allowed_interactive_call(method: &str) -> bool {
+ [ #( #handler_names, )* ].contains(&method)
+ }
+ }
+ }
+ };
+
+ quote! {
+ #[automatically_derived]
+ impl #generics sdk::module::MethodHandler for #ty {
+ #prefetch_impl
+ #dispatch_call_impl
+ #dispatch_query_impl
+ #dispatch_message_result_impl
+ #supported_methods_impl
+ #expensive_queries_impl
+ #allowed_private_km_queries_impl
+ #allowed_interactive_calls_impl
+ }
+
+ #[automatically_derived]
+ impl #generics #ty {
+ #query_parameters_impl
+
+ #(#handler_items)*
+ }
+ }
+ }
+}
+
+/// An item (in the `syn` sense, i.e. a fn, type, comment, etc) in an `impl` block,
+/// plus parsed data about its #[handler] attribute, if any.
+#[derive(Clone)]
+struct ParsedImplItem {
+ item: syn::ImplItem,
+ handler: Option<HandlerInfo>,
+}
+
+#[derive(Clone, Debug)]
+struct HandlerInfo {
+ attrs: MethodHandlerAttr,
+ /// Name of the handler function.
+ ident: syn::Ident,
+}
+
+#[derive(Debug, Copy, Clone, PartialEq)]
+enum HandlerKind {
+ Call,
+ Query,
+ MessageResult,
+ Prefetch,
+}
+
+impl HandlerKind {
+ fn as_sdk_ident(&self) -> syn::Path {
+ match self {
+ HandlerKind::Call => parse_quote!(core_types::MethodHandlerKind::Call),
+ HandlerKind::Query => parse_quote!(core_types::MethodHandlerKind::Query),
+ HandlerKind::MessageResult => {
+ parse_quote!(core_types::MethodHandlerKind::MessageResult)
+ }
+ HandlerKind::Prefetch => {
+ unimplemented!("prefetch cannot be expressed in core::types::MethodHandlerKind")
+ }
+ }
+ }
+}
+
+#[derive(Debug, Clone, PartialEq)]
+struct MethodHandlerAttr {
+ kind: HandlerKind,
+ /// Name of the RPC that this handler handles, e.g. "my_module.MyQuery".
+ rpc_name: syn::Expr,
+ /// Whether this handler is tagged as expensive. Only applies to query handlers.
+ is_expensive: bool,
+ /// Whether this handler is tagged as allowing access to private key manager state. Only applies
+ /// to query handlers.
+ allow_private_km: bool,
+ /// Whether this handler is tagged as allowing interactive calls. Only applies to call handlers.
+ allow_interactive: bool,
+ /// Whether this handler is tagged as internal.
+ is_internal: bool,
+}
+impl syn::parse::Parse for MethodHandlerAttr {
+ fn parse(input: syn::parse::ParseStream<'_>) -> syn::Result<Self> {
+ let kind: syn::Ident = input.parse()?;
+ let kind = match kind.to_string().as_str() {
+ "call" => HandlerKind::Call,
+ "query" => HandlerKind::Query,
+ "message_result" => HandlerKind::MessageResult,
+ "prefetch" => HandlerKind::Prefetch,
+ _ => return Err(syn::Error::new(kind.span(), "invalid handler kind")),
+ };
+ let _: syn::token::Eq = input.parse()?;
+ let rpc_name: syn::Expr = input.parse()?;
+
+ // Parse optional comma-separated tags.
+ let mut is_expensive = false;
+ let mut allow_private_km = false;
+ let mut allow_interactive = false;
+ let mut is_internal = false;
+ while input.peek(syn::token::Comma) {
+ let _: syn::token::Comma = input.parse()?;
+ let tag: syn::Ident = input.parse()?;
+
+ if tag == "expensive" {
+ if kind != HandlerKind::Query {
+ return Err(syn::Error::new(
+ tag.span(),
+ "`expensive` tag is only allowed on `query` handlers",
+ ));
+ }
+ is_expensive = true;
+ } else if tag == "allow_private_km" {
+ if kind != HandlerKind::Query {
+ return Err(syn::Error::new(
+ tag.span(),
+ "`allow_private_km` tag is only allowed on `query` handlers",
+ ));
+ }
+ allow_private_km = true;
+ } else if tag == "allow_interactive" {
+ if kind != HandlerKind::Call {
+ return Err(syn::Error::new(
+ tag.span(),
+ "`allow_interactive` tag is only allowed on `call` handlers",
+ ));
+ }
+ allow_interactive = true;
+ } else if tag == "internal" {
+ if kind != HandlerKind::Call {
+ return Err(syn::Error::new(
+ tag.span(),
+ "`internal` tag is only allowed on `call` handlers",
+ ));
+ }
+ is_internal = true;
+ } else {
+ return Err(syn::Error::new(
+ tag.span(),
+ "invalid handler tag; supported: `expensive`, `allow_private_km`, `allow_interactive`, `internal`",
+ ));
+ }
+ }
+
+ if !input.is_empty() {
+ return Err(syn::Error::new(input.span(), "unexpected extra tokens"));
+ }
+ Ok(Self {
+ kind,
+ rpc_name,
+ is_expensive,
+ allow_private_km,
+ allow_interactive,
+ is_internal,
+ })
+ }
+}
+
+fn parse_attrs(attrs: &[syn::Attribute]) -> Option<MethodHandlerAttr> {
+ let handler_meta = attrs.iter().find(|attr| attr.path().is_ident("handler"))?;
+ handler_meta
+ .parse_args()
+ .map_err(|err| {
+ emit_compile_error(format!(
+ "Unsupported format of #[handler(...)] attribute: {err}"
+ ))
+ })
+ .ok()
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +
use std::collections::HashSet;
+
+use proc_macro2::TokenStream;
+use quote::quote;
+
+use crate::emit_compile_error;
+
+/// Deriver for the `MigrationHandler` trait.
+pub struct DeriveMigrationHandler {
+ /// Item defining the `MigrationHandler::Genesis` associated type.
+ genesis_ty: Option<syn::ImplItem>,
+ /// Migration functions.
+ migrate_fns: Vec<MigrateFn>,
+}
+
+struct MigrateFn {
+ item: syn::ImplItem,
+ ident: syn::Ident,
+ from_version: u32,
+}
+
+impl DeriveMigrationHandler {
+ pub fn new() -> Box<Self> {
+ Box::new(Self {
+ genesis_ty: None,
+ migrate_fns: vec![],
+ })
+ }
+}
+
+impl super::Deriver for DeriveMigrationHandler {
+ fn preprocess(&mut self, item: syn::ImplItem) -> Option<syn::ImplItem> {
+ match item {
+ // We are looking for a `type Genesis = ...;` item.
+ syn::ImplItem::Type(ref ty) if &ty.ident.to_string() == "Genesis" => {
+ self.genesis_ty = Some(item);
+
+ None // Take the item.
+ }
+ syn::ImplItem::Fn(ref f) => {
+ // Check whether a `migration` attribute is set for the method.
+ if let Some(attrs) = parse_attrs(&f.attrs) {
+ self.migrate_fns.push(MigrateFn {
+ ident: f.sig.ident.clone(),
+ from_version: attrs.from_version,
+ item,
+ });
+
+ None // Take the item.
+ } else {
+ Some(item) // Return the item.
+ }
+ }
+ _ => Some(item), // Return the item.
+ }
+ }
+
+ fn derive(&mut self, generics: &syn::Generics, ty: &Box<syn::Type>) -> TokenStream {
+ let genesis_ty = if let Some(genesis_ty) = &self.genesis_ty {
+ genesis_ty
+ } else {
+ return quote! {};
+ };
+
+ // Sort by version to ensure migrations are processed in the right order.
+ self.migrate_fns.sort_by_key(|f| f.from_version);
+
+ let mut seen_versions = HashSet::new();
+ let (migrate_fns, mut migrate_arms): (Vec<_>, Vec<_>) = self.migrate_fns.iter().map(|f| {
+ let MigrateFn { item, ident, from_version } = f;
+ if seen_versions.contains(from_version) {
+ emit_compile_error(format!(
+ "Duplicate migration for version: {from_version}"
+ ));
+ }
+ seen_versions.insert(from_version);
+
+ (
+ item,
+ if from_version == &0 {
+ // Version zero is special as initializing from genesis always gets us latest.
+ quote! { if version == #from_version { Self::#ident(genesis); version = Self::VERSION; } }
+ } else {
+ // For other versions, each migration brings us from V to V+1.
+ // TODO: Add a compile-time assert that version < Self::VERSION.
+ quote! { if version == #from_version && version < Self::VERSION { Self::#ident(); version += 1; } }
+ }
+ )
+ }).unzip();
+
+ // Ensure there is a genesis migration, at least an empty one that bumps the version.
+ if !seen_versions.contains(&0) {
+ migrate_arms.push(quote! {
+ if version == 0u32 { version = Self::VERSION; }
+ });
+ }
+
+ quote! {
+ #[automatically_derived]
+ impl #generics sdk::module::MigrationHandler for #ty {
+ #genesis_ty
+
+ fn init_or_migrate<C: Context>(
+ _ctx: &C,
+ meta: &mut sdk::modules::core::types::Metadata,
+ genesis: Self::Genesis,
+ ) -> bool {
+ let mut version = meta.versions.get(Self::NAME).copied().unwrap_or_default();
+ if version == Self::VERSION {
+ return false; // Already the latest version.
+ }
+
+ #(#migrate_arms)*
+
+ if version != Self::VERSION {
+ panic!("no migration for module state from version {version} to {}", Self::VERSION)
+ }
+
+ // Update version information.
+ meta.versions.insert(Self::NAME.to_owned(), Self::VERSION);
+ return true;
+ }
+ }
+
+ #[automatically_derived]
+ impl #generics #ty {
+ #(#migrate_fns)*
+ }
+ }
+ }
+}
+
+#[derive(Debug, Clone, PartialEq)]
+struct MigrationHandlerAttr {
+ /// Version that this handler handles. Zero indicates genesis.
+ from_version: u32,
+}
+impl syn::parse::Parse for MigrationHandlerAttr {
+ fn parse(input: syn::parse::ParseStream<'_>) -> syn::Result<Self> {
+ let kind: syn::Ident = input.parse()?;
+ let from_version = match kind.to_string().as_str() {
+ "init" => 0,
+ "from" => {
+ let _: syn::token::Eq = input.parse()?;
+ let version: syn::LitInt = input.parse()?;
+
+ version.base10_parse()?
+ }
+ _ => return Err(syn::Error::new(kind.span(), "invalid migration kind")),
+ };
+
+ if !input.is_empty() {
+ return Err(syn::Error::new(input.span(), "unexpected extra tokens"));
+ }
+ Ok(Self { from_version })
+ }
+}
+
+fn parse_attrs(attrs: &[syn::Attribute]) -> Option<MigrationHandlerAttr> {
+ let migration_meta = attrs
+ .iter()
+ .find(|attr| attr.path().is_ident("migration"))?;
+ migration_meta
+ .parse_args()
+ .map_err(|err| {
+ emit_compile_error(format!(
+ "Unsupported format of #[migration(...)] attribute: {err}"
+ ))
+ })
+ .ok()
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 +386 +387 +388 +389 +390 +391 +392 +393 +394 +395 +396 +397 +398 +399 +400 +401 +402 +403 +404 +405 +406 +407 +408 +409 +410 +411 +412 +413 +414 +415 +416 +417 +418 +419 +420 +421 +422 +423 +424 +425 +426 +427 +428 +429 +430 +431 +432 +433 +434 +435 +436 +437 +438 +439 +440 +441 +442 +443 +444 +445 +446 +447 +448 +449 +450 +451 +452 +453 +454 +455 +456 +457 +458 +459 +460 +461 +462 +463 +464 +465 +466 +467 +468 +469 +470 +471 +472 +473 +474 +475 +476 +477 +478 +479 +480 +481 +482 +483 +484 +485 +486 +487 +488 +489 +490 +491 +492 +493 +494 +495 +496 +497 +498 +499 +500 +501 +502 +503 +504 +505 +506 +507 +508 +509 +510 +511 +512 +513 +514 +515 +516 +517 +518 +519 +520 +521 +522 +523 +524 +525 +526 +527 +528 +529 +530 +531 +532 +533 +534 +535 +536 +537 +538 +539 +540 +541 +542 +543 +544 +545 +546 +547 +548 +549 +550 +551 +552 +553 +554 +555 +556 +557 +558 +559 +560 +561 +562 +563 +564 +565 +566 +567 +568 +569 +570 +571 +572 +573 +574 +575 +576 +577 +578 +
mod method_handler;
+mod migration_handler;
+mod module;
+
+use proc_macro2::TokenStream;
+use quote::quote;
+
+use crate::generators as gen;
+
+/// Given an `impl MyModule` block, produces an `impl *Handler for MyModule`.
+/// See `sdk_derive()` in lib.rs for details.
+pub fn derive_module(impl_block: syn::ItemImpl) -> TokenStream {
+ let sdk_crate = gen::sdk_crate_path();
+ let module_generics = &impl_block.generics;
+ let module_ty = &impl_block.self_ty;
+
+ let mut base_impls: Vec<TokenStream> = Vec::new();
+ let mut derivations: Vec<TokenStream> = Vec::new();
+
+ let mut derivers: Vec<Box<dyn Deriver>> = vec![
+ module::DeriveModule::new(),
+ migration_handler::DeriveMigrationHandler::new(),
+ method_handler::DeriveMethodHandler::new(),
+ ];
+
+ // Iterate through all impl items, collecting them and then deriving everything.
+ 'items: for item in impl_block.items {
+ let mut item = Some(item);
+
+ for deriver in derivers.iter_mut() {
+ item = deriver.preprocess(item.take().expect("no deriver claimed the item"));
+ if item.is_none() {
+ continue 'items;
+ }
+ }
+
+ // No deriver claimed the item.
+ let item = item.expect("no deriver claimed the item");
+ base_impls.push(quote!(#item));
+ }
+
+ // Perform the derivation process.
+ for deriver in derivers.iter_mut() {
+ let derivation = deriver.derive(module_generics, module_ty);
+ derivations.push(derivation);
+ }
+
+ let base_impls = if base_impls.is_empty() {
+ None
+ } else {
+ Some(quote! {
+ #[automatically_derived]
+ impl #module_generics #module_ty {
+ #(#base_impls)*
+ }
+ })
+ };
+
+ gen::wrap_in_const(quote! {
+ use #sdk_crate::{
+ self as sdk,
+ cbor,
+ error::Error as _,
+ module::{DispatchResult, CallResult},
+ modules::core::types as core_types,
+ types::message::MessageResult
+ };
+
+ #(#derivations)*
+ #base_impls
+ })
+}
+
+trait Deriver {
+ fn preprocess(&mut self, item: syn::ImplItem) -> Option<syn::ImplItem>;
+
+ #[allow(clippy::borrowed_box)]
+ fn derive(&mut self, generics: &syn::Generics, ty: &Box<syn::Type>) -> TokenStream;
+}
+
+#[cfg(test)]
+mod tests {
+ // Helper; asserts that `derive_module` generates the `expected` code from `input`.
+ fn expect_module_impl(input: syn::ItemImpl, expected: syn::Stmt) {
+ let derivation = super::derive_module(input);
+ let actual: syn::Stmt = syn::parse2(derivation).unwrap();
+
+ crate::assert_empty_diff!(actual, expected);
+ }
+
+ // The `uses` statement common to all autogenerated impls.
+ thread_local! {
+ static USES: proc_macro2::TokenStream = quote::quote! {
+ use ::oasis_runtime_sdk::{
+ self as sdk, cbor,
+ error::Error as _,
+ module::{CallResult, DispatchResult},
+ modules::core::types as core_types,
+ types::message::MessageResult,
+ };
+ }
+ }
+
+ /// Unannotated functions in the input impl block should be assumed to be a part of the base
+ /// type implementation.
+ #[test]
+ fn generate_method_handler_impl_unannotated_func() {
+ let input = syn::parse_quote!(
+ impl<C: Cfg> MyModule<C> {
+ fn unannotated_fn_should_be_passed_thru(foo: Bar) -> Baz {}
+ }
+ );
+
+ expect_module_impl(
+ input,
+ USES.with(|uses| {
+ syn::parse_quote!(
+ const _: () = {
+ #uses
+ #[automatically_derived]
+ impl<C: Cfg> sdk::module::MethodHandler for MyModule<C> {
+ fn dispatch_query<C: Context>(
+ ctx: &C,
+ method: &str,
+ args: cbor::Value,
+ ) -> DispatchResult<cbor::Value, Result<cbor::Value, sdk::error::RuntimeError>>
+ {
+ match method {
+ q if q == format!("{}.Parameters", Self::NAME) => {
+ module::dispatch_query(ctx, args, Self::query_parameters)
+ }
+ _ => DispatchResult::Unhandled(args),
+ }
+ }
+ }
+ #[automatically_derived]
+ impl<C: Cfg> MyModule<C> {
+ fn query_parameters<C: Context>(_ctx: &C, _args: ()) -> Result<<Self as module::Module>::Parameters, <Self as module::Module>::Error> {
+ Ok(Self::params())
+ }
+ }
+ #[automatically_derived]
+ impl<C: Cfg> MyModule<C> {
+ fn unannotated_fn_should_be_passed_thru(foo: Bar) -> Baz {}
+ }
+ };
+ )
+ }),
+ );
+ }
+
+ #[test]
+ fn generate_method_handler_impl_calls() {
+ let input = syn::parse_quote!(
+ impl<C: Cfg> MyModule<C> {
+ #[handler(prefetch = "my_module.MyCall")]
+ fn prefetch_for_my_call() {}
+ #[handler(call = "my_module.MyCall")]
+ fn my_call(foo2: Bar2) -> Baz2 {}
+ #[handler(call = "my_module.MyOtherCall")]
+ fn my_other_call(foo3: Bar3) -> Baz3 {}
+ #[handler(call = "my_module.MyInternalCall", internal)]
+ fn my_internal_call(foo4: Bar4) -> Baz4 {}
+ }
+ );
+
+ expect_module_impl(
+ input,
+ USES.with(|uses| {
+ syn::parse_quote!(
+ const _: () = {
+ #uses
+ #[automatically_derived]
+ impl<C: Cfg> sdk::module::MethodHandler for MyModule<C> {
+ fn prefetch(
+ prefixes: &mut BTreeSet<Prefix>,
+ method: &str,
+ body: cbor::Value,
+ auth_info: &AuthInfo,
+ ) -> module::DispatchResult<cbor::Value, Result<(), sdk::error::RuntimeError>> {
+ let mut add_prefix = |p| {
+ prefixes.insert(p);
+ };
+ match method {
+ "my_module.MyCall" => module::DispatchResult::Handled(
+ Self::prefetch_for_my_call(&mut add_prefix, body, auth_info),
+ ),
+ "my_module.MyOtherCall" => module::DispatchResult::Handled(Ok(())),
+ "my_module.MyInternalCall" => module::DispatchResult::Handled(Ok(())),
+ _ => module::DispatchResult::Unhandled(body),
+ }
+ }
+ fn dispatch_call<C: Context>(
+ ctx: &C,
+ method: &str,
+ body: cbor::Value,
+ ) -> DispatchResult<cbor::Value, CallResult> {
+ match method {
+ "my_module.MyCall" => module::dispatch_call(ctx, body, Self::my_call),
+ "my_module.MyOtherCall" => {
+ module::dispatch_call(ctx, body, Self::my_other_call)
+ }
+ "my_module.MyInternalCall" => module::dispatch_call(ctx, body, |ctx, body| {
+ if !sdk::state::CurrentState::with_env(|env| env.is_internal()) {
+ return Err(sdk::modules::core::Error::Forbidden.into());
+ }
+ Self::my_internal_call(ctx, body)
+ }),
+ _ => DispatchResult::Unhandled(body),
+ }
+ }
+ fn dispatch_query<C: Context>(
+ ctx: &C,
+ method: &str,
+ args: cbor::Value,
+ ) -> DispatchResult<cbor::Value, Result<cbor::Value, sdk::error::RuntimeError>>
+ {
+ match method {
+ q if q == format!("{}.Parameters", Self::NAME) => {
+ module::dispatch_query(ctx, args, Self::query_parameters)
+ }
+ _ => DispatchResult::Unhandled(args),
+ }
+ }
+ fn supported_methods() -> Vec<core_types::MethodHandlerInfo> {
+ vec![
+ core_types::MethodHandlerInfo {
+ kind: core_types::MethodHandlerKind::Call,
+ name: "my_module.MyCall".to_string(),
+ },
+ core_types::MethodHandlerInfo {
+ kind: core_types::MethodHandlerKind::Call,
+ name: "my_module.MyOtherCall".to_string(),
+ },
+ core_types::MethodHandlerInfo {
+ kind: core_types::MethodHandlerKind::Call,
+ name: "my_module.MyInternalCall".to_string(),
+ },
+ ]
+ }
+ }
+ #[automatically_derived]
+ impl<C: Cfg> MyModule<C> {
+ fn query_parameters<C: Context>(_ctx: &C, _args: ()) -> Result<<Self as module::Module>::Parameters, <Self as module::Module>::Error> {
+ Ok(Self::params())
+ }
+ #[handler(prefetch = "my_module.MyCall")]
+ fn prefetch_for_my_call() {}
+ #[handler(call = "my_module.MyCall")]
+ fn my_call(foo2: Bar2) -> Baz2 {}
+ #[handler(call = "my_module.MyOtherCall")]
+ fn my_other_call(foo3: Bar3) -> Baz3 {}
+ #[handler(call = "my_module.MyInternalCall", internal)]
+ fn my_internal_call(foo4: Bar4) -> Baz4 {}
+ }
+ };
+ )
+ }),
+ );
+ }
+
+ #[test]
+ fn generate_method_handler_impl_queries() {
+ let input = syn::parse_quote!(
+ impl<C: Cfg> MyModule<C> {
+ #[handler(query = RPC_NAME_OF_MY_QUERY)]
+ fn my_query() -> () {}
+ #[handler(query = "module.OtherQuery", expensive)]
+ fn my_other_query() -> () {}
+ #[handler(query = "module.ConfidentialQuery", expensive, allow_private_km)]
+ fn my_confidential_query() -> () {}
+ }
+ );
+
+ expect_module_impl(
+ input,
+ USES.with(|uses| {
+ syn::parse_quote!(
+ const _: () = {
+ #uses
+ #[automatically_derived]
+ impl<C: Cfg> sdk::module::MethodHandler for MyModule<C> {
+ fn dispatch_query<C: Context>(
+ ctx: &C,
+ method: &str,
+ args: cbor::Value,
+ ) -> DispatchResult<cbor::Value, Result<cbor::Value, sdk::error::RuntimeError>>
+ {
+ match method {
+ RPC_NAME_OF_MY_QUERY => module::dispatch_query(ctx, args, Self::my_query),
+ "module.OtherQuery" => module::dispatch_query(ctx, args, Self::my_other_query),
+ "module.ConfidentialQuery" => module::dispatch_query(ctx, args, Self::my_confidential_query),
+ q if q == format!("{}.Parameters", Self::NAME) => {
+ module::dispatch_query(ctx, args, Self::query_parameters)
+ }
+ _ => DispatchResult::Unhandled(args),
+ }
+ }
+ fn supported_methods() -> Vec<core_types::MethodHandlerInfo> {
+ vec![
+ core_types::MethodHandlerInfo {
+ kind: core_types::MethodHandlerKind::Query,
+ name: RPC_NAME_OF_MY_QUERY.to_string(),
+ },
+ core_types::MethodHandlerInfo {
+ kind: core_types::MethodHandlerKind::Query,
+ name: "module.OtherQuery".to_string(),
+ },
+ core_types::MethodHandlerInfo {
+ kind: core_types::MethodHandlerKind::Query,
+ name: "module.ConfidentialQuery".to_string(),
+ },
+ ]
+ }
+ fn is_expensive_query(method: &str) -> bool {
+ ["module.OtherQuery", "module.ConfidentialQuery"].contains(&method)
+ }
+ fn is_allowed_private_km_query(method: &str) -> bool {
+ ["module.ConfidentialQuery"].contains(&method)
+ }
+ }
+ #[automatically_derived]
+ impl<C: Cfg> MyModule<C> {
+ fn query_parameters<C: Context>(
+ _ctx: &C,
+ _args: (),
+ ) -> Result<<Self as module::Module>::Parameters, <Self as module::Module>::Error>
+ {
+ Ok(Self::params())
+ }
+ #[handler(query = RPC_NAME_OF_MY_QUERY)]
+ fn my_query() -> () {}
+ #[handler(query = "module.OtherQuery", expensive)]
+ fn my_other_query() -> () {}
+ #[handler(query = "module.ConfidentialQuery", expensive, allow_private_km)]
+ fn my_confidential_query() -> () {}
+ }
+ };
+ )
+ }),
+ );
+ }
+
+ #[test]
+ fn generate_method_handler_impl_method_calls() {
+ let input = syn::parse_quote!(
+ impl<C: Cfg> MyModule<C> {
+ #[handler(query = "my_module.MyMC")]
+ fn my_method_call() -> () {}
+ }
+ );
+
+ expect_module_impl(
+ input,
+ USES.with(|uses| {
+ syn::parse_quote!(
+ const _: () = {
+ #uses
+ #[automatically_derived]
+ impl<C: Cfg> sdk::module::MethodHandler for MyModule<C> {
+ fn dispatch_query<C: Context>(
+ ctx: &C,
+ method: &str,
+ args: cbor::Value,
+ ) -> DispatchResult<cbor::Value, Result<cbor::Value, sdk::error::RuntimeError>>
+ {
+ match method {
+ "my_module.MyMC" => module::dispatch_query(ctx, args, Self::my_method_call),
+ q if q == format!("{}.Parameters", Self::NAME) => {
+ module::dispatch_query(ctx, args, Self::query_parameters)
+ }
+ _ => DispatchResult::Unhandled(args),
+ }
+ }
+ fn supported_methods() -> Vec<core_types::MethodHandlerInfo> {
+ vec![core_types::MethodHandlerInfo {
+ kind: core_types::MethodHandlerKind::Query,
+ name: "my_module.MyMC".to_string(),
+ }]
+ }
+ }
+ #[automatically_derived]
+ impl<C: Cfg> MyModule<C> {
+ fn query_parameters<C: Context>(_ctx: &C, _args: ()) -> Result<<Self as module::Module>::Parameters, <Self as module::Module>::Error> {
+ Ok(Self::params())
+ }
+ #[handler(query = "my_module.MyMC")]
+ fn my_method_call() -> () {}
+ }
+ };
+ )
+ }),
+ );
+ }
+
+ #[test]
+ fn generate_module_impl() {
+ let input = syn::parse_quote!(
+ impl<C: Cfg> MyModule<C> {
+ const NAME: &'static str = MODULE_NAME;
+ const VERSION: u32 = 2;
+ type Error = Error;
+ type Event = ();
+ type Parameters = Parameters;
+ type Genesis = Genesis;
+
+ #[migration(init)]
+ fn init(genesis: Genesis) {
+ Self::set_params(genesis.parameters);
+ }
+
+ #[migration(from = 2)]
+ fn migrate_v2_to_v3() {}
+
+ #[migration(from = 1)]
+ fn migrate_v1_to_v2() {}
+
+ #[handler(query = "my_module.MyMC")]
+ fn my_method_call() -> () {}
+ }
+ );
+
+ expect_module_impl(
+ input,
+ USES.with(|uses| {
+ syn::parse_quote!(
+ const _: () = {
+ #uses
+ #[automatically_derived]
+ impl<C: Cfg> sdk::module::Module for MyModule<C> {
+ const NAME: &'static str = MODULE_NAME;
+ const VERSION: u32 = 2;
+ type Error = Error;
+ type Event = ();
+ type Parameters = Parameters;
+ }
+ #[automatically_derived]
+ impl<C: Cfg> sdk::module::MigrationHandler for MyModule<C> {
+ type Genesis = Genesis;
+ fn init_or_migrate<C: Context>(
+ _ctx: &C,
+ meta: &mut sdk::modules::core::types::Metadata,
+ genesis: Self::Genesis,
+ ) -> bool {
+ let mut version = meta.versions.get(Self::NAME).copied().unwrap_or_default();
+ if version == Self::VERSION {
+ return false;
+ }
+ if version == 0u32 {
+ Self::init(genesis);
+ version = Self::VERSION;
+ }
+ if version == 1u32 && version < Self::VERSION {
+ Self::migrate_v1_to_v2();
+ version += 1;
+ }
+ if version == 2u32 && version < Self::VERSION {
+ Self::migrate_v2_to_v3();
+ version += 1;
+ }
+ if version != Self::VERSION {
+ panic!(
+ "no migration for module state from version {version} to {}",
+ Self::VERSION
+ )
+ }
+ meta.versions.insert(Self::NAME.to_owned(), Self::VERSION);
+ return true;
+ }
+ }
+ #[automatically_derived]
+ impl<C: Cfg> MyModule<C> {
+ #[migration(init)]
+ fn init(genesis: Genesis) {
+ Self::set_params(genesis.parameters);
+ }
+ #[migration(from = 1)]
+ fn migrate_v1_to_v2() {}
+ #[migration(from = 2)]
+ fn migrate_v2_to_v3() {}
+ }
+ #[automatically_derived]
+ impl<C: Cfg> sdk::module::MethodHandler for MyModule<C> {
+ fn dispatch_query<C: Context>(
+ ctx: &C,
+ method: &str,
+ args: cbor::Value,
+ ) -> DispatchResult<cbor::Value, Result<cbor::Value, sdk::error::RuntimeError>>
+ {
+ match method {
+ "my_module.MyMC" => module::dispatch_query(ctx, args, Self::my_method_call),
+ q if q == format!("{}.Parameters", Self::NAME) => {
+ module::dispatch_query(ctx, args, Self::query_parameters)
+ }
+ _ => DispatchResult::Unhandled(args),
+ }
+ }
+ fn supported_methods() -> Vec<core_types::MethodHandlerInfo> {
+ vec![core_types::MethodHandlerInfo {
+ kind: core_types::MethodHandlerKind::Query,
+ name: "my_module.MyMC".to_string(),
+ }]
+ }
+ }
+ #[automatically_derived]
+ impl<C: Cfg> MyModule<C> {
+ fn query_parameters<C: Context>(_ctx: &C, _args: ()) -> Result<<Self as module::Module>::Parameters, <Self as module::Module>::Error> {
+ Ok(Self::params())
+ }
+ #[handler(query = "my_module.MyMC")]
+ fn my_method_call() -> () {}
+ }
+ };
+ )
+ }),
+ );
+ }
+
+ #[test]
+ #[should_panic(expected = "invalid handler kind")]
+ fn generate_method_handler_malformed_bad_kind() {
+ let input: syn::ItemImpl = syn::parse_quote!(
+ impl<C: Cfg> MyModule<C> {
+ #[handler(unsupported_key = "some_value")]
+ fn my_method_call() -> () {}
+ }
+ );
+ super::derive_module(input);
+ }
+
+ #[test]
+ #[should_panic(expected = "only allowed on `query` handlers")]
+ fn generate_method_handler_malformed_expensive_nonquery() {
+ let input: syn::ItemImpl = syn::parse_quote!(
+ impl<C: Cfg> MyModule<C> {
+ #[handler(call = "foo", expensive)]
+ fn my_method_call() -> () {}
+ }
+ );
+ super::derive_module(input);
+ }
+
+ #[test]
+ #[should_panic(expected = "only allowed on `query` handlers")]
+ fn generate_method_handler_malformed_allow_private_km_nonquery() {
+ let input: syn::ItemImpl = syn::parse_quote!(
+ impl<C: Cfg> MyModule<C> {
+ #[handler(call = "foo", allow_private_km)]
+ fn my_method_call() -> () {}
+ }
+ );
+ super::derive_module(input);
+ }
+
+ #[test]
+ #[should_panic(expected = "only allowed on `call` handlers")]
+ fn generate_method_handler_malformed_internal_noncall() {
+ let input: syn::ItemImpl = syn::parse_quote!(
+ impl<C: Cfg> MyModule<C> {
+ #[handler(query = "foo", internal)]
+ fn my_method_call() -> () {}
+ }
+ );
+ super::derive_module(input);
+ }
+
+ #[test]
+ #[should_panic]
+ fn generate_method_handler_malformed_multiple_metas() {
+ let input: syn::ItemImpl = syn::parse_quote!(
+ impl<C: Cfg> MyModule<C> {
+ #[handler(call = "foo", query = "bar")]
+ fn my_method_call() -> () {}
+ }
+ );
+ super::derive_module(input);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +
use proc_macro2::TokenStream;
+use quote::quote;
+
+/// Deriver for the `Module` trait.
+pub struct DeriveModule {
+ /// Items specifying the module configuration.
+ module_cfg: Vec<syn::ImplItem>,
+}
+
+impl DeriveModule {
+ pub fn new() -> Box<Self> {
+ Box::new(Self { module_cfg: vec![] })
+ }
+}
+
+impl super::Deriver for DeriveModule {
+ fn preprocess(&mut self, item: syn::ImplItem) -> Option<syn::ImplItem> {
+ match item {
+ syn::ImplItem::Type(ref ty) => {
+ match ty.ident.to_string().as_str() {
+ "Error" | "Event" | "Parameters" => {
+ self.module_cfg.push(item);
+ None // Take the item.
+ }
+ _ => Some(item), // Return the item.
+ }
+ }
+ syn::ImplItem::Const(ref cnst) => {
+ match cnst.ident.to_string().as_str() {
+ "NAME" | "VERSION" => {
+ self.module_cfg.push(item);
+ None // Take the item.
+ }
+ _ => Some(item), // Return the item.
+ }
+ }
+ _ => Some(item), // Return the item.
+ }
+ }
+
+ fn derive(&mut self, generics: &syn::Generics, ty: &Box<syn::Type>) -> TokenStream {
+ if self.module_cfg.is_empty() {
+ return quote! {};
+ }
+ let module_cfg = &self.module_cfg;
+
+ quote! {
+ #[automatically_derived]
+ impl #generics sdk::module::Module for #ty {
+ #(#module_cfg)*
+ }
+ }
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +
use proc_macro2::TokenStream;
+use quote::quote;
+
+macro_rules! parse_cargo_ver {
+ ($ver:literal) => {{
+ let cargo_pkg_version_env_var = if cfg!(test) {
+ concat!("TEST_CARGO_PKG_VERSION_", $ver)
+ } else {
+ concat!("CARGO_PKG_VERSION_", $ver)
+ };
+ std::env::var(cargo_pkg_version_env_var)
+ .unwrap()
+ .parse::<u16>()
+ .unwrap()
+ }};
+}
+
+/// Constructs an `oasis_sdk::core::common::version::Version` from the Cargo.toml version.
+pub fn version_from_cargo() -> TokenStream {
+ let major = parse_cargo_ver!("MAJOR");
+ let minor = parse_cargo_ver!("MINOR");
+ let patch = parse_cargo_ver!("PATCH");
+ quote!(oasis_runtime_sdk::core::common::version::Version::new(#major, #minor, #patch))
+}
+
+#[cfg(test)]
+mod tests {
+ #[test]
+ fn generates_version() {
+ std::env::set_var("TEST_CARGO_PKG_VERSION_MAJOR", "1");
+ std::env::set_var("TEST_CARGO_PKG_VERSION_MINOR", "2");
+ std::env::set_var("TEST_CARGO_PKG_VERSION_PATCH", "3");
+
+ let expected: syn::Expr = syn::parse_quote!(
+ oasis_runtime_sdk::core::common::version::Version::new(1u16, 2u16, 3u16)
+ );
+ let actual: syn::Expr = syn::parse2(super::version_from_cargo()).unwrap();
+
+ crate::assert_empty_diff!(actual, expected);
+ }
+}
+1 +2 +3 +4 +5 +6 +7 +8 +9 +10 +11 +12 +13 +14 +15 +16 +17 +18 +19 +20 +21 +22 +23 +24 +25 +26 +27 +28 +29 +30 +31 +32 +33 +34 +35 +36 +37 +38 +39 +40 +41 +42 +43 +44 +45 +46 +47 +48 +49 +50 +51 +52 +53 +54 +55 +56 +57 +58 +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 +73 +74 +75 +76 +77 +78 +79 +80 +81 +82 +83 +84 +85 +86 +87 +88 +89 +90 +91 +92 +93 +94 +95 +96 +97 +98 +99 +100 +101 +102 +103 +104 +105 +106 +107 +108 +109 +110 +111 +112 +113 +114 +115 +116 +117 +118 +119 +120 +121 +122 +123 +124 +125 +126 +127 +128 +129 +130 +131 +132 +133 +134 +135 +136 +137 +138 +139 +140 +141 +142 +143 +144 +145 +146 +147 +148 +149 +150 +151 +152 +153 +154 +155 +156 +157 +158 +159 +160 +161 +162 +163 +164 +165 +166 +167 +168 +169 +170 +171 +172 +173 +174 +175 +176 +177 +178 +179 +180 +181 +182 +183 +184 +185 +186 +187 +188 +189 +190 +191 +192 +193 +194 +195 +196 +197 +198 +199 +200 +201 +202 +203 +204 +205 +206 +207 +208 +209 +210 +211 +212 +213 +214 +215 +216 +217 +218 +219 +220 +221 +222 +223 +224 +225 +226 +227 +228 +229 +230 +231 +232 +233 +234 +235 +236 +237 +238 +239 +240 +241 +242 +243 +244 +245 +246 +247 +248 +249 +250 +251 +252 +253 +254 +255 +256 +257 +258 +259 +260 +261 +262 +263 +264 +265 +266 +267 +268 +269 +270 +271 +272 +273 +274 +275 +276 +277 +278 +279 +280 +281 +282 +283 +284 +285 +286 +287 +288 +289 +290 +291 +292 +293 +294 +295 +296 +297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +
//! A very simple HTTPS client that can be used inside ROFL apps.
+//!
+//! This simple client is needed because Fortanix EDP does not yet have support for mio/Tokio
+//! networking and so the usual `hyper` and `reqwest` cannot be used without patches.
+use std::{
+ fmt,
+ io::{Read, Write},
+ net::{Ipv4Addr, SocketAddr, SocketAddrV4, TcpStream},
+ sync::{Arc, OnceLock},
+};
+
+use rustls::{ClientConfig, ClientConnection, StreamOwned};
+use rustls_pki_types::ServerName;
+use ureq::{
+ http::Uri,
+ resolver::Resolver,
+ transport::{
+ time::NextTimeout, Buffers, ChainedConnector, ConnectionDetails, Connector, LazyBuffers,
+ Transport, TransportAdapter,
+ },
+ Agent, AgentConfig,
+};
+
+/// An `ureq::Agent` that can be used to perform blocking HTTPS requests.
+///
+/// Note that this forbids non-HTTPS requests. If you need to perform plain HTTP requests consider
+/// using `agent_with_config` and pass a suitable config.
+pub fn agent() -> Agent {
+ let cfg = AgentConfig {
+ https_only: true, // Not using HTTPS is unsafe unless careful.
+ user_agent: "rofl-utils/0.1.0".to_string(),
+ ..Default::default()
+ };
+ agent_with_config(cfg)
+}
+
+/// An `ureq::Agent` with given configuration that can be used to perform blocking HTTPS requests.
+pub fn agent_with_config(cfg: AgentConfig) -> Agent {
+ Agent::with_parts(
+ cfg,
+ ChainedConnector::new([SgxConnector.boxed(), RustlsConnector::default().boxed()]),
+ SgxResolver,
+ )
+}
+
+#[derive(Debug)]
+struct SgxConnector;
+
+impl Connector for SgxConnector {
+ fn connect(
+ &self,
+ details: &ConnectionDetails,
+ _chained: Option<Box<dyn Transport>>,
+ ) -> Result<Option<Box<dyn Transport>>, ureq::Error> {
+ let config = &details.config;
+ // Has already been validated.
+ let scheme = details.uri.scheme().unwrap();
+ let authority = details.uri.authority().unwrap();
+
+ let host_port = ureq::resolver::DefaultResolver::host_and_port(scheme, authority)
+ .ok_or(ureq::Error::HostNotFound)?;
+ let stream = TcpStream::connect(host_port)?;
+
+ let buffers = LazyBuffers::new(config.input_buffer_size, config.output_buffer_size);
+ let transport = TcpTransport::new(stream, buffers);
+
+ Ok(Some(Box::new(transport)))
+ }
+}
+
+struct TcpTransport {
+ stream: TcpStream,
+ buffers: LazyBuffers,
+}
+
+impl TcpTransport {
+ fn new(stream: TcpStream, buffers: LazyBuffers) -> TcpTransport {
+ TcpTransport { stream, buffers }
+ }
+}
+
+impl Transport for TcpTransport {
+ fn buffers(&mut self) -> &mut dyn Buffers {
+ &mut self.buffers
+ }
+
+ fn transmit_output(&mut self, amount: usize, _timeout: NextTimeout) -> Result<(), ureq::Error> {
+ let output = &self.buffers.output()[..amount];
+ self.stream.write_all(output)?;
+
+ Ok(())
+ }
+
+ fn await_input(&mut self, _timeout: NextTimeout) -> Result<bool, ureq::Error> {
+ if self.buffers.can_use_input() {
+ return Ok(true);
+ }
+
+ let input = self.buffers.input_mut();
+ let amount = self.stream.read(input)?;
+ self.buffers.add_filled(amount);
+
+ Ok(amount > 0)
+ }
+
+ fn is_open(&mut self) -> bool {
+ // No way to detect on SGX.
+ true
+ }
+}
+
+impl fmt::Debug for TcpTransport {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ f.debug_struct("TcpTransport")
+ .field("addr", &self.stream.peer_addr().ok())
+ .finish()
+ }
+}
+
+#[derive(Debug)]
+struct SgxResolver;
+
+impl Resolver for SgxResolver {
+ fn resolve(
+ &self,
+ _uri: &Uri,
+ _config: &AgentConfig,
+ _timeout: NextTimeout,
+ ) -> Result<ureq::resolver::ResolvedSocketAddrs, ureq::Error> {
+ // Do not resolve anything as SGX does not support resolution and the endpoint must be
+ // passed as a string. We need to return a dummy address.
+ Ok(vec![SocketAddr::V4(SocketAddrV4::new(
+ Ipv4Addr::new(0, 0, 0, 0),
+ 0,
+ ))]
+ .into())
+ }
+}
+
+#[derive(Default)]
+struct RustlsConnector {
+ config: OnceLock<Arc<ClientConfig>>,
+}
+
+impl Connector for RustlsConnector {
+ fn connect(
+ &self,
+ details: &ConnectionDetails,
+ chained: Option<Box<dyn Transport>>,
+ ) -> Result<Option<Box<dyn Transport>>, ureq::Error> {
+ let Some(transport) = chained else {
+ panic!("RustlsConnector requires a chained transport");
+ };
+
+ // Only add TLS if we are connecting via HTTPS and the transport isn't TLS
+ // already, otherwise use chained transport as is.
+ if !details.needs_tls() || transport.is_tls() {
+ return Ok(Some(transport));
+ }
+
+ // Initialize the config on first run.
+ let config_ref = self.config.get_or_init(build_config);
+ let config = config_ref.clone();
+
+ let name_borrowed: ServerName<'_> = details
+ .uri
+ .authority()
+ .ok_or(ureq::Error::HostNotFound)?
+ .host()
+ .try_into()
+ .map_err(|_| ureq::Error::HostNotFound)?;
+
+ let name = name_borrowed.to_owned();
+
+ let conn =
+ ClientConnection::new(config, name).map_err(|_| ureq::Error::ConnectionFailed)?;
+ let stream = StreamOwned {
+ conn,
+ sock: TransportAdapter::new(transport),
+ };
+
+ let buffers = LazyBuffers::new(
+ details.config.input_buffer_size,
+ details.config.output_buffer_size,
+ );
+
+ let transport = Box::new(RustlsTransport { buffers, stream });
+
+ Ok(Some(transport))
+ }
+}
+
+fn build_config() -> Arc<ClientConfig> {
+ let provider = Arc::new(rustls_mbedcrypto_provider::mbedtls_crypto_provider());
+
+ let builder = ClientConfig::builder_with_provider(provider)
+ .with_safe_default_protocol_versions()
+ .unwrap();
+
+ let builder = builder
+ .dangerous()
+ .with_custom_certificate_verifier(Arc::new(
+ rustls_mbedpki_provider::MbedTlsServerCertVerifier::new(
+ webpki_root_certs::TLS_SERVER_ROOT_CERTS,
+ )
+ .unwrap(),
+ ));
+
+ let config = builder.with_no_client_auth();
+
+ Arc::new(config)
+}
+
+struct RustlsTransport {
+ buffers: LazyBuffers,
+ stream: StreamOwned<ClientConnection, TransportAdapter>,
+}
+
+impl Transport for RustlsTransport {
+ fn buffers(&mut self) -> &mut dyn Buffers {
+ &mut self.buffers
+ }
+
+ fn transmit_output(&mut self, amount: usize, _timeout: NextTimeout) -> Result<(), ureq::Error> {
+ let output = &self.buffers.output()[..amount];
+ self.stream.write_all(output)?;
+
+ Ok(())
+ }
+
+ fn await_input(&mut self, _timeout: NextTimeout) -> Result<bool, ureq::Error> {
+ if self.buffers.can_use_input() {
+ return Ok(true);
+ }
+
+ let input = self.buffers.input_mut();
+ let amount = self.stream.read(input)?;
+ self.buffers.add_filled(amount);
+
+ Ok(amount > 0)
+ }
+
+ fn is_open(&mut self) -> bool {
+ self.stream.get_mut().get_mut().is_open()
+ }
+
+ fn is_tls(&self) -> bool {
+ true
+ }
+}
+
+impl fmt::Debug for RustlsConnector {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ f.debug_struct("RustlsConnector").finish()
+ }
+}
+
+impl fmt::Debug for RustlsTransport {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ f.debug_struct("RustlsTransport").finish()
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use mockito::{mock, server_url};
+
+ use super::{agent, agent_with_config};
+
+ #[test]
+ fn test_get_request() {
+ // Set up a mock server
+ let _mock = mock("GET", "/test")
+ .with_status(200)
+ .with_header("content-type", "text/plain")
+ .with_body("Hello, world!")
+ .create();
+
+ // Create an agent
+ let agent = agent_with_config(Default::default());
+
+ // Make a GET request to the mock server
+ let url = format!("{}/test", server_url());
+ let mut response = agent.get(&url).call().unwrap();
+
+ // Verify the response
+ assert_eq!(response.status(), 200);
+ assert_eq!(
+ response.body_mut().read_to_string().unwrap(),
+ "Hello, world!"
+ );
+ }
+
+ #[test]
+ fn test_post_request() {
+ // Set up a mock server for POST request
+ let _mock = mock("POST", "/submit")
+ .with_status(201)
+ .with_header("content-type", "application/json")
+ .with_body(r#"{"success":true}"#)
+ .create();
+
+ // Create an agent
+ let agent = agent_with_config(Default::default());
+
+ // Make a POST request to the mock server
+ let url = format!("{}/submit", server_url());
+ let mut response = agent
+ .post(&url)
+ .content_type("application/json")
+ .send(r#"{"key":"value"}"#)
+ .unwrap();
+
+ // Verify the response
+ assert_eq!(response.status(), 201);
+ assert_eq!(
+ response.body_mut().read_to_string().unwrap(),
+ r#"{"success":true}"#
+ );
+ }
+
+ #[test]
+ fn test_get_remote_https() {
+ let response = agent().get("https://www.google.com/").call().unwrap();
+
+ // Verify the response
+ assert_eq!(
+ "text/html;charset=ISO-8859-1",
+ response
+ .headers()
+ .get("content-type")
+ .unwrap()
+ .to_str()
+ .unwrap()
+ .replace("; ", ";")
+ );
+ assert_eq!(response.body().mime_type(), Some("text/html"));
+ }
+}
+fn:) to \
+ restrict the search to a given item kind.","Accepted kinds are: fn, mod, struct, \
+ enum, trait, type, macro, \
+ and const.","Search functions by type signature (e.g., vec -> usize or \
+ -> vec or String, enum:Cow -> bool)","You can look for items with an exact name by putting double quotes around \
+ your request: \"string\"","Look for functions that accept or return \
+ slices and \
+ arrays by writing \
+ square brackets (e.g., -> [u8] or [] -> Option)","Look for items inside another one by searching for a path: vec::Vec",].map(x=>""+x+"
").join("");const div_infos=document.createElement("div");addClass(div_infos,"infos");div_infos.innerHTML="${value.replaceAll(" ", " ")}`}else{error[index]=value}});output+=`Self from the given unstructured data. Read moreSelf from the entirety of the given\nunstructured data. Read moreGets an iterator over the entries of the map, sorted by key.
\nuse std::collections::BTreeMap;\n\nlet mut map = BTreeMap::new();\nmap.insert(3, \"c\");\nmap.insert(2, \"b\");\nmap.insert(1, \"a\");\n\nfor (key, value) in map.iter() {\n println!(\"{key}: {value}\");\n}\n\nlet (first_key, first_value) = map.iter().next().unwrap();\nassert_eq!((*first_key, *first_value), (1, \"a\"));Gets a mutable iterator over the entries of the map, sorted by key.
\nuse std::collections::BTreeMap;\n\nlet mut map = BTreeMap::from([\n (\"a\", 1),\n (\"b\", 2),\n (\"c\", 3),\n]);\n\n// add 10 to the value if the key isn't \"a\"\nfor (key, value) in map.iter_mut() {\n if key != &\"a\" {\n *value += 10;\n }\n}Gets an iterator over the keys of the map, in sorted order.
\nuse std::collections::BTreeMap;\n\nlet mut a = BTreeMap::new();\na.insert(2, \"b\");\na.insert(1, \"a\");\n\nlet keys: Vec<_> = a.keys().cloned().collect();\nassert_eq!(keys, [1, 2]);Gets an iterator over the values of the map, in order by key.
\nuse std::collections::BTreeMap;\n\nlet mut a = BTreeMap::new();\na.insert(1, \"hello\");\na.insert(2, \"goodbye\");\n\nlet values: Vec<&str> = a.values().cloned().collect();\nassert_eq!(values, [\"hello\", \"goodbye\"]);Gets a mutable iterator over the values of the map, in order by key.
\nuse std::collections::BTreeMap;\n\nlet mut a = BTreeMap::new();\na.insert(1, String::from(\"hello\"));\na.insert(2, String::from(\"goodbye\"));\n\nfor value in a.values_mut() {\n value.push_str(\"!\");\n}\n\nlet values: Vec<String> = a.values().cloned().collect();\nassert_eq!(values, [String::from(\"hello!\"),\n String::from(\"goodbye!\")]);Returns the number of elements in the map.
\nuse std::collections::BTreeMap;\n\nlet mut a = BTreeMap::new();\nassert_eq!(a.len(), 0);\na.insert(1, \"a\");\nassert_eq!(a.len(), 1);Returns true if the map contains no elements.
use std::collections::BTreeMap;\n\nlet mut a = BTreeMap::new();\nassert!(a.is_empty());\na.insert(1, \"a\");\nassert!(!a.is_empty());btree_cursors)Returns a Cursor pointing at the gap before the smallest key\ngreater than the given bound.
Passing Bound::Included(x) will return a cursor pointing to the\ngap before the smallest key greater than or equal to x.
Passing Bound::Excluded(x) will return a cursor pointing to the\ngap before the smallest key greater than x.
Passing Bound::Unbounded will return a cursor pointing to the\ngap before the smallest key in the map.
#![feature(btree_cursors)]\n\nuse std::collections::BTreeMap;\nuse std::ops::Bound;\n\nlet map = BTreeMap::from([\n (1, \"a\"),\n (2, \"b\"),\n (3, \"c\"),\n (4, \"d\"),\n]);\n\nlet cursor = map.lower_bound(Bound::Included(&2));\nassert_eq!(cursor.peek_prev(), Some((&1, &\"a\")));\nassert_eq!(cursor.peek_next(), Some((&2, &\"b\")));\n\nlet cursor = map.lower_bound(Bound::Excluded(&2));\nassert_eq!(cursor.peek_prev(), Some((&2, &\"b\")));\nassert_eq!(cursor.peek_next(), Some((&3, &\"c\")));\n\nlet cursor = map.lower_bound(Bound::Unbounded);\nassert_eq!(cursor.peek_prev(), None);\nassert_eq!(cursor.peek_next(), Some((&1, &\"a\")));btree_cursors)Returns a CursorMut pointing at the gap before the smallest key\ngreater than the given bound.
Passing Bound::Included(x) will return a cursor pointing to the\ngap before the smallest key greater than or equal to x.
Passing Bound::Excluded(x) will return a cursor pointing to the\ngap before the smallest key greater than x.
Passing Bound::Unbounded will return a cursor pointing to the\ngap before the smallest key in the map.
#![feature(btree_cursors)]\n\nuse std::collections::BTreeMap;\nuse std::ops::Bound;\n\nlet mut map = BTreeMap::from([\n (1, \"a\"),\n (2, \"b\"),\n (3, \"c\"),\n (4, \"d\"),\n]);\n\nlet mut cursor = map.lower_bound_mut(Bound::Included(&2));\nassert_eq!(cursor.peek_prev(), Some((&1, &mut \"a\")));\nassert_eq!(cursor.peek_next(), Some((&2, &mut \"b\")));\n\nlet mut cursor = map.lower_bound_mut(Bound::Excluded(&2));\nassert_eq!(cursor.peek_prev(), Some((&2, &mut \"b\")));\nassert_eq!(cursor.peek_next(), Some((&3, &mut \"c\")));\n\nlet mut cursor = map.lower_bound_mut(Bound::Unbounded);\nassert_eq!(cursor.peek_prev(), None);\nassert_eq!(cursor.peek_next(), Some((&1, &mut \"a\")));btree_cursors)Returns a Cursor pointing at the gap after the greatest key\nsmaller than the given bound.
Passing Bound::Included(x) will return a cursor pointing to the\ngap after the greatest key smaller than or equal to x.
Passing Bound::Excluded(x) will return a cursor pointing to the\ngap after the greatest key smaller than x.
Passing Bound::Unbounded will return a cursor pointing to the\ngap after the greatest key in the map.
#![feature(btree_cursors)]\n\nuse std::collections::BTreeMap;\nuse std::ops::Bound;\n\nlet map = BTreeMap::from([\n (1, \"a\"),\n (2, \"b\"),\n (3, \"c\"),\n (4, \"d\"),\n]);\n\nlet cursor = map.upper_bound(Bound::Included(&3));\nassert_eq!(cursor.peek_prev(), Some((&3, &\"c\")));\nassert_eq!(cursor.peek_next(), Some((&4, &\"d\")));\n\nlet cursor = map.upper_bound(Bound::Excluded(&3));\nassert_eq!(cursor.peek_prev(), Some((&2, &\"b\")));\nassert_eq!(cursor.peek_next(), Some((&3, &\"c\")));\n\nlet cursor = map.upper_bound(Bound::Unbounded);\nassert_eq!(cursor.peek_prev(), Some((&4, &\"d\")));\nassert_eq!(cursor.peek_next(), None);btree_cursors)Returns a CursorMut pointing at the gap after the greatest key\nsmaller than the given bound.
Passing Bound::Included(x) will return a cursor pointing to the\ngap after the greatest key smaller than or equal to x.
Passing Bound::Excluded(x) will return a cursor pointing to the\ngap after the greatest key smaller than x.
Passing Bound::Unbounded will return a cursor pointing to the\ngap after the greatest key in the map.
#![feature(btree_cursors)]\n\nuse std::collections::BTreeMap;\nuse std::ops::Bound;\n\nlet mut map = BTreeMap::from([\n (1, \"a\"),\n (2, \"b\"),\n (3, \"c\"),\n (4, \"d\"),\n]);\n\nlet mut cursor = map.upper_bound_mut(Bound::Included(&3));\nassert_eq!(cursor.peek_prev(), Some((&3, &mut \"c\")));\nassert_eq!(cursor.peek_next(), Some((&4, &mut \"d\")));\n\nlet mut cursor = map.upper_bound_mut(Bound::Excluded(&3));\nassert_eq!(cursor.peek_prev(), Some((&2, &mut \"b\")));\nassert_eq!(cursor.peek_next(), Some((&3, &mut \"c\")));\n\nlet mut cursor = map.upper_bound_mut(Bound::Unbounded);\nassert_eq!(cursor.peek_prev(), Some((&4, &mut \"d\")));\nassert_eq!(cursor.peek_next(), None);Clears the map, removing all elements.
\nuse std::collections::BTreeMap;\n\nlet mut a = BTreeMap::new();\na.insert(1, \"a\");\na.clear();\nassert!(a.is_empty());btreemap_alloc)Makes a new empty BTreeMap with a reasonable choice for B.
\nuse std::collections::BTreeMap;\nuse std::alloc::Global;\n\nlet mut map = BTreeMap::new_in(Global);\n\n// entries can now be inserted into the empty map\nmap.insert(1, \"a\");Returns a reference to the value corresponding to the key.
\nThe key may be any borrowed form of the map’s key type, but the ordering\non the borrowed form must match the ordering on the key type.
\nuse std::collections::BTreeMap;\n\nlet mut map = BTreeMap::new();\nmap.insert(1, \"a\");\nassert_eq!(map.get(&1), Some(&\"a\"));\nassert_eq!(map.get(&2), None);Returns the key-value pair corresponding to the supplied key.
\nThe supplied key may be any borrowed form of the map’s key type, but the ordering\non the borrowed form must match the ordering on the key type.
\nuse std::collections::BTreeMap;\n\nlet mut map = BTreeMap::new();\nmap.insert(1, \"a\");\nassert_eq!(map.get_key_value(&1), Some((&1, &\"a\")));\nassert_eq!(map.get_key_value(&2), None);Returns the first key-value pair in the map.\nThe key in this pair is the minimum key in the map.
\nuse std::collections::BTreeMap;\n\nlet mut map = BTreeMap::new();\nassert_eq!(map.first_key_value(), None);\nmap.insert(1, \"b\");\nmap.insert(2, \"a\");\nassert_eq!(map.first_key_value(), Some((&1, &\"b\")));Returns the first entry in the map for in-place manipulation.\nThe key of this entry is the minimum key in the map.
\nuse std::collections::BTreeMap;\n\nlet mut map = BTreeMap::new();\nmap.insert(1, \"a\");\nmap.insert(2, \"b\");\nif let Some(mut entry) = map.first_entry() {\n if *entry.key() > 0 {\n entry.insert(\"first\");\n }\n}\nassert_eq!(*map.get(&1).unwrap(), \"first\");\nassert_eq!(*map.get(&2).unwrap(), \"b\");Removes and returns the first element in the map.\nThe key of this element is the minimum key that was in the map.
\nDraining elements in ascending order, while keeping a usable map each iteration.
\n\nuse std::collections::BTreeMap;\n\nlet mut map = BTreeMap::new();\nmap.insert(1, \"a\");\nmap.insert(2, \"b\");\nwhile let Some((key, _val)) = map.pop_first() {\n assert!(map.iter().all(|(k, _v)| *k > key));\n}\nassert!(map.is_empty());Returns the last key-value pair in the map.\nThe key in this pair is the maximum key in the map.
\nuse std::collections::BTreeMap;\n\nlet mut map = BTreeMap::new();\nmap.insert(1, \"b\");\nmap.insert(2, \"a\");\nassert_eq!(map.last_key_value(), Some((&2, &\"a\")));Returns the last entry in the map for in-place manipulation.\nThe key of this entry is the maximum key in the map.
\nuse std::collections::BTreeMap;\n\nlet mut map = BTreeMap::new();\nmap.insert(1, \"a\");\nmap.insert(2, \"b\");\nif let Some(mut entry) = map.last_entry() {\n if *entry.key() > 0 {\n entry.insert(\"last\");\n }\n}\nassert_eq!(*map.get(&1).unwrap(), \"a\");\nassert_eq!(*map.get(&2).unwrap(), \"last\");Removes and returns the last element in the map.\nThe key of this element is the maximum key that was in the map.
\nDraining elements in descending order, while keeping a usable map each iteration.
\n\nuse std::collections::BTreeMap;\n\nlet mut map = BTreeMap::new();\nmap.insert(1, \"a\");\nmap.insert(2, \"b\");\nwhile let Some((key, _val)) = map.pop_last() {\n assert!(map.iter().all(|(k, _v)| *k < key));\n}\nassert!(map.is_empty());Returns true if the map contains a value for the specified key.
The key may be any borrowed form of the map’s key type, but the ordering\non the borrowed form must match the ordering on the key type.
\nuse std::collections::BTreeMap;\n\nlet mut map = BTreeMap::new();\nmap.insert(1, \"a\");\nassert_eq!(map.contains_key(&1), true);\nassert_eq!(map.contains_key(&2), false);Returns a mutable reference to the value corresponding to the key.
\nThe key may be any borrowed form of the map’s key type, but the ordering\non the borrowed form must match the ordering on the key type.
\nuse std::collections::BTreeMap;\n\nlet mut map = BTreeMap::new();\nmap.insert(1, \"a\");\nif let Some(x) = map.get_mut(&1) {\n *x = \"b\";\n}\nassert_eq!(map[&1], \"b\");Inserts a key-value pair into the map.
\nIf the map did not have this key present, None is returned.
If the map did have this key present, the value is updated, and the old\nvalue is returned. The key is not updated, though; this matters for\ntypes that can be == without being identical. See the module-level\ndocumentation for more.
use std::collections::BTreeMap;\n\nlet mut map = BTreeMap::new();\nassert_eq!(map.insert(37, \"a\"), None);\nassert_eq!(map.is_empty(), false);\n\nmap.insert(37, \"b\");\nassert_eq!(map.insert(37, \"c\"), Some(\"b\"));\nassert_eq!(map[&37], \"c\");map_try_insert)Tries to insert a key-value pair into the map, and returns\na mutable reference to the value in the entry.
\nIf the map already had this key present, nothing is updated, and\nan error containing the occupied entry and the value is returned.
\n#![feature(map_try_insert)]\n\nuse std::collections::BTreeMap;\n\nlet mut map = BTreeMap::new();\nassert_eq!(map.try_insert(37, \"a\").unwrap(), &\"a\");\n\nlet err = map.try_insert(37, \"b\").unwrap_err();\nassert_eq!(err.entry.key(), &37);\nassert_eq!(err.entry.get(), &\"a\");\nassert_eq!(err.value, \"b\");Removes a key from the map, returning the value at the key if the key\nwas previously in the map.
\nThe key may be any borrowed form of the map’s key type, but the ordering\non the borrowed form must match the ordering on the key type.
\nuse std::collections::BTreeMap;\n\nlet mut map = BTreeMap::new();\nmap.insert(1, \"a\");\nassert_eq!(map.remove(&1), Some(\"a\"));\nassert_eq!(map.remove(&1), None);Removes a key from the map, returning the stored key and value if the key\nwas previously in the map.
\nThe key may be any borrowed form of the map’s key type, but the ordering\non the borrowed form must match the ordering on the key type.
\nuse std::collections::BTreeMap;\n\nlet mut map = BTreeMap::new();\nmap.insert(1, \"a\");\nassert_eq!(map.remove_entry(&1), Some((1, \"a\")));\nassert_eq!(map.remove_entry(&1), None);Retains only the elements specified by the predicate.
\nIn other words, remove all pairs (k, v) for which f(&k, &mut v) returns false.\nThe elements are visited in ascending key order.
use std::collections::BTreeMap;\n\nlet mut map: BTreeMap<i32, i32> = (0..8).map(|x| (x, x*10)).collect();\n// Keep only the elements with even-numbered keys.\nmap.retain(|&k, _| k % 2 == 0);\nassert!(map.into_iter().eq(vec![(0, 0), (2, 20), (4, 40), (6, 60)]));Moves all elements from other into self, leaving other empty.
If a key from other is already present in self, the respective\nvalue from self will be overwritten with the respective value from other.
use std::collections::BTreeMap;\n\nlet mut a = BTreeMap::new();\na.insert(1, \"a\");\na.insert(2, \"b\");\na.insert(3, \"c\"); // Note: Key (3) also present in b.\n\nlet mut b = BTreeMap::new();\nb.insert(3, \"d\"); // Note: Key (3) also present in a.\nb.insert(4, \"e\");\nb.insert(5, \"f\");\n\na.append(&mut b);\n\nassert_eq!(a.len(), 5);\nassert_eq!(b.len(), 0);\n\nassert_eq!(a[&1], \"a\");\nassert_eq!(a[&2], \"b\");\nassert_eq!(a[&3], \"d\"); // Note: \"c\" has been overwritten.\nassert_eq!(a[&4], \"e\");\nassert_eq!(a[&5], \"f\");Constructs a double-ended iterator over a sub-range of elements in the map.\nThe simplest way is to use the range syntax min..max, thus range(min..max) will\nyield elements from min (inclusive) to max (exclusive).\nThe range may also be entered as (Bound<T>, Bound<T>), so for example\nrange((Excluded(4), Included(10))) will yield a left-exclusive, right-inclusive\nrange from 4 to 10.
Panics if range start > end.\nPanics if range start == end and both bounds are Excluded.
use std::collections::BTreeMap;\nuse std::ops::Bound::Included;\n\nlet mut map = BTreeMap::new();\nmap.insert(3, \"a\");\nmap.insert(5, \"b\");\nmap.insert(8, \"c\");\nfor (&key, &value) in map.range((Included(&4), Included(&8))) {\n println!(\"{key}: {value}\");\n}\nassert_eq!(Some((&5, &\"b\")), map.range(4..).next());Constructs a mutable double-ended iterator over a sub-range of elements in the map.\nThe simplest way is to use the range syntax min..max, thus range(min..max) will\nyield elements from min (inclusive) to max (exclusive).\nThe range may also be entered as (Bound<T>, Bound<T>), so for example\nrange((Excluded(4), Included(10))) will yield a left-exclusive, right-inclusive\nrange from 4 to 10.
Panics if range start > end.\nPanics if range start == end and both bounds are Excluded.
use std::collections::BTreeMap;\n\nlet mut map: BTreeMap<&str, i32> =\n [(\"Alice\", 0), (\"Bob\", 0), (\"Carol\", 0), (\"Cheryl\", 0)].into();\nfor (_, balance) in map.range_mut(\"B\"..\"Cheryl\") {\n *balance += 100;\n}\nfor (name, balance) in &map {\n println!(\"{name} => {balance}\");\n}Gets the given key’s corresponding entry in the map for in-place manipulation.
\nuse std::collections::BTreeMap;\n\nlet mut count: BTreeMap<&str, usize> = BTreeMap::new();\n\n// count the number of occurrences of letters in the vec\nfor x in [\"a\", \"b\", \"a\", \"c\", \"a\", \"b\"] {\n count.entry(x).and_modify(|curr| *curr += 1).or_insert(1);\n}\n\nassert_eq!(count[\"a\"], 3);\nassert_eq!(count[\"b\"], 2);\nassert_eq!(count[\"c\"], 1);Splits the collection into two at the given key. Returns everything after the given key,\nincluding the key.
\nuse std::collections::BTreeMap;\n\nlet mut a = BTreeMap::new();\na.insert(1, \"a\");\na.insert(2, \"b\");\na.insert(3, \"c\");\na.insert(17, \"d\");\na.insert(41, \"e\");\n\nlet b = a.split_off(&3);\n\nassert_eq!(a.len(), 2);\nassert_eq!(b.len(), 3);\n\nassert_eq!(a[&1], \"a\");\nassert_eq!(a[&2], \"b\");\n\nassert_eq!(b[&3], \"c\");\nassert_eq!(b[&17], \"d\");\nassert_eq!(b[&41], \"e\");btree_extract_if)Creates an iterator that visits all elements (key-value pairs) in\nascending key order and uses a closure to determine if an element should\nbe removed. If the closure returns true, the element is removed from\nthe map and yielded. If the closure returns false, or panics, the\nelement remains in the map and will not be yielded.
The iterator also lets you mutate the value of each element in the\nclosure, regardless of whether you choose to keep or remove it.
\nIf the returned ExtractIf is not exhausted, e.g. because it is dropped without iterating\nor the iteration short-circuits, then the remaining elements will be retained.\nUse retain with a negated predicate if you do not need the returned iterator.
Splitting a map into even and odd keys, reusing the original map:
\n\n#![feature(btree_extract_if)]\nuse std::collections::BTreeMap;\n\nlet mut map: BTreeMap<i32, i32> = (0..8).map(|x| (x, x)).collect();\nlet evens: BTreeMap<_, _> = map.extract_if(|k, _v| k % 2 == 0).collect();\nlet odds = map;\nassert_eq!(evens.keys().copied().collect::<Vec<_>>(), [0, 2, 4, 6]);\nassert_eq!(odds.keys().copied().collect::<Vec<_>>(), [1, 3, 5, 7]);Creates a consuming iterator visiting all the keys, in sorted order.\nThe map cannot be used after calling this.\nThe iterator element type is K.
use std::collections::BTreeMap;\n\nlet mut a = BTreeMap::new();\na.insert(2, \"b\");\na.insert(1, \"a\");\n\nlet keys: Vec<i32> = a.into_keys().collect();\nassert_eq!(keys, [1, 2]);Creates a consuming iterator visiting all the values, in order by key.\nThe map cannot be used after calling this.\nThe iterator element type is V.
use std::collections::BTreeMap;\n\nlet mut a = BTreeMap::new();\na.insert(1, \"hello\");\na.insert(2, \"goodbye\");\n\nlet values: Vec<&str> = a.into_values().collect();\nassert_eq!(values, [\"hello\", \"goodbye\"]);try_default in case the value is null or\nundefined.extend_one)extend_one)extend_one)extend_one)self and other) and is used by the <=\noperator. Read moreSelf from the given unstructured data. Read moreSelf from the entirety of the given\nunstructured data. Read morebtreemap_alloc)Makes a new BTreeSet with a reasonable choice of B.
use std::collections::BTreeSet;\nuse std::alloc::Global;\n\nlet mut set: BTreeSet<i32> = BTreeSet::new_in(Global);Constructs a double-ended iterator over a sub-range of elements in the set.\nThe simplest way is to use the range syntax min..max, thus range(min..max) will\nyield elements from min (inclusive) to max (exclusive).\nThe range may also be entered as (Bound<T>, Bound<T>), so for example\nrange((Excluded(4), Included(10))) will yield a left-exclusive, right-inclusive\nrange from 4 to 10.
Panics if range start > end.\nPanics if range start == end and both bounds are Excluded.
use std::collections::BTreeSet;\nuse std::ops::Bound::Included;\n\nlet mut set = BTreeSet::new();\nset.insert(3);\nset.insert(5);\nset.insert(8);\nfor &elem in set.range((Included(&4), Included(&8))) {\n println!(\"{elem}\");\n}\nassert_eq!(Some(&5), set.range(4..).next());Visits the elements representing the difference,\ni.e., the elements that are in self but not in other,\nin ascending order.
use std::collections::BTreeSet;\n\nlet mut a = BTreeSet::new();\na.insert(1);\na.insert(2);\n\nlet mut b = BTreeSet::new();\nb.insert(2);\nb.insert(3);\n\nlet diff: Vec<_> = a.difference(&b).cloned().collect();\nassert_eq!(diff, [1]);Visits the elements representing the symmetric difference,\ni.e., the elements that are in self or in other but not in both,\nin ascending order.
use std::collections::BTreeSet;\n\nlet mut a = BTreeSet::new();\na.insert(1);\na.insert(2);\n\nlet mut b = BTreeSet::new();\nb.insert(2);\nb.insert(3);\n\nlet sym_diff: Vec<_> = a.symmetric_difference(&b).cloned().collect();\nassert_eq!(sym_diff, [1, 3]);Visits the elements representing the intersection,\ni.e., the elements that are both in self and other,\nin ascending order.
use std::collections::BTreeSet;\n\nlet mut a = BTreeSet::new();\na.insert(1);\na.insert(2);\n\nlet mut b = BTreeSet::new();\nb.insert(2);\nb.insert(3);\n\nlet intersection: Vec<_> = a.intersection(&b).cloned().collect();\nassert_eq!(intersection, [2]);Visits the elements representing the union,\ni.e., all the elements in self or other, without duplicates,\nin ascending order.
use std::collections::BTreeSet;\n\nlet mut a = BTreeSet::new();\na.insert(1);\n\nlet mut b = BTreeSet::new();\nb.insert(2);\n\nlet union: Vec<_> = a.union(&b).cloned().collect();\nassert_eq!(union, [1, 2]);Clears the set, removing all elements.
\nuse std::collections::BTreeSet;\n\nlet mut v = BTreeSet::new();\nv.insert(1);\nv.clear();\nassert!(v.is_empty());Returns true if the set contains an element equal to the value.
The value may be any borrowed form of the set’s element type,\nbut the ordering on the borrowed form must match the\nordering on the element type.
\nuse std::collections::BTreeSet;\n\nlet set = BTreeSet::from([1, 2, 3]);\nassert_eq!(set.contains(&1), true);\nassert_eq!(set.contains(&4), false);Returns a reference to the element in the set, if any, that is equal to\nthe value.
\nThe value may be any borrowed form of the set’s element type,\nbut the ordering on the borrowed form must match the\nordering on the element type.
\nuse std::collections::BTreeSet;\n\nlet set = BTreeSet::from([1, 2, 3]);\nassert_eq!(set.get(&2), Some(&2));\nassert_eq!(set.get(&4), None);Returns true if self has no elements in common with other.\nThis is equivalent to checking for an empty intersection.
use std::collections::BTreeSet;\n\nlet a = BTreeSet::from([1, 2, 3]);\nlet mut b = BTreeSet::new();\n\nassert_eq!(a.is_disjoint(&b), true);\nb.insert(4);\nassert_eq!(a.is_disjoint(&b), true);\nb.insert(1);\nassert_eq!(a.is_disjoint(&b), false);Returns true if the set is a subset of another,\ni.e., other contains at least all the elements in self.
use std::collections::BTreeSet;\n\nlet sup = BTreeSet::from([1, 2, 3]);\nlet mut set = BTreeSet::new();\n\nassert_eq!(set.is_subset(&sup), true);\nset.insert(2);\nassert_eq!(set.is_subset(&sup), true);\nset.insert(4);\nassert_eq!(set.is_subset(&sup), false);Returns true if the set is a superset of another,\ni.e., self contains at least all the elements in other.
use std::collections::BTreeSet;\n\nlet sub = BTreeSet::from([1, 2]);\nlet mut set = BTreeSet::new();\n\nassert_eq!(set.is_superset(&sub), false);\n\nset.insert(0);\nset.insert(1);\nassert_eq!(set.is_superset(&sub), false);\n\nset.insert(2);\nassert_eq!(set.is_superset(&sub), true);Returns a reference to the first element in the set, if any.\nThis element is always the minimum of all elements in the set.
\nBasic usage:
\n\nuse std::collections::BTreeSet;\n\nlet mut set = BTreeSet::new();\nassert_eq!(set.first(), None);\nset.insert(1);\nassert_eq!(set.first(), Some(&1));\nset.insert(2);\nassert_eq!(set.first(), Some(&1));Returns a reference to the last element in the set, if any.\nThis element is always the maximum of all elements in the set.
\nBasic usage:
\n\nuse std::collections::BTreeSet;\n\nlet mut set = BTreeSet::new();\nassert_eq!(set.last(), None);\nset.insert(1);\nassert_eq!(set.last(), Some(&1));\nset.insert(2);\nassert_eq!(set.last(), Some(&2));Removes the first element from the set and returns it, if any.\nThe first element is always the minimum element in the set.
\nuse std::collections::BTreeSet;\n\nlet mut set = BTreeSet::new();\n\nset.insert(1);\nwhile let Some(n) = set.pop_first() {\n assert_eq!(n, 1);\n}\nassert!(set.is_empty());Removes the last element from the set and returns it, if any.\nThe last element is always the maximum element in the set.
\nuse std::collections::BTreeSet;\n\nlet mut set = BTreeSet::new();\n\nset.insert(1);\nwhile let Some(n) = set.pop_last() {\n assert_eq!(n, 1);\n}\nassert!(set.is_empty());Adds a value to the set.
\nReturns whether the value was newly inserted. That is:
\ntrue is\nreturned.false is returned, and\nthe entry is not updated.See the module-level documentation for more.
\nuse std::collections::BTreeSet;\n\nlet mut set = BTreeSet::new();\n\nassert_eq!(set.insert(2), true);\nassert_eq!(set.insert(2), false);\nassert_eq!(set.len(), 1);Adds a value to the set, replacing the existing element, if any, that is\nequal to the value. Returns the replaced element.
\nuse std::collections::BTreeSet;\n\nlet mut set = BTreeSet::new();\nset.insert(Vec::<i32>::new());\n\nassert_eq!(set.get(&[][..]).unwrap().capacity(), 0);\nset.replace(Vec::with_capacity(10));\nassert_eq!(set.get(&[][..]).unwrap().capacity(), 10);If the set contains an element equal to the value, removes it from the\nset and drops it. Returns whether such an element was present.
\nThe value may be any borrowed form of the set’s element type,\nbut the ordering on the borrowed form must match the\nordering on the element type.
\nuse std::collections::BTreeSet;\n\nlet mut set = BTreeSet::new();\n\nset.insert(2);\nassert_eq!(set.remove(&2), true);\nassert_eq!(set.remove(&2), false);Removes and returns the element in the set, if any, that is equal to\nthe value.
\nThe value may be any borrowed form of the set’s element type,\nbut the ordering on the borrowed form must match the\nordering on the element type.
\nuse std::collections::BTreeSet;\n\nlet mut set = BTreeSet::from([1, 2, 3]);\nassert_eq!(set.take(&2), Some(2));\nassert_eq!(set.take(&2), None);Retains only the elements specified by the predicate.
\nIn other words, remove all elements e for which f(&e) returns false.\nThe elements are visited in ascending order.
use std::collections::BTreeSet;\n\nlet mut set = BTreeSet::from([1, 2, 3, 4, 5, 6]);\n// Keep only the even numbers.\nset.retain(|&k| k % 2 == 0);\nassert!(set.iter().eq([2, 4, 6].iter()));Moves all elements from other into self, leaving other empty.
use std::collections::BTreeSet;\n\nlet mut a = BTreeSet::new();\na.insert(1);\na.insert(2);\na.insert(3);\n\nlet mut b = BTreeSet::new();\nb.insert(3);\nb.insert(4);\nb.insert(5);\n\na.append(&mut b);\n\nassert_eq!(a.len(), 5);\nassert_eq!(b.len(), 0);\n\nassert!(a.contains(&1));\nassert!(a.contains(&2));\nassert!(a.contains(&3));\nassert!(a.contains(&4));\nassert!(a.contains(&5));Splits the collection into two at the value. Returns a new collection\nwith all elements greater than or equal to the value.
\nBasic usage:
\n\nuse std::collections::BTreeSet;\n\nlet mut a = BTreeSet::new();\na.insert(1);\na.insert(2);\na.insert(3);\na.insert(17);\na.insert(41);\n\nlet b = a.split_off(&3);\n\nassert_eq!(a.len(), 2);\nassert_eq!(b.len(), 3);\n\nassert!(a.contains(&1));\nassert!(a.contains(&2));\n\nassert!(b.contains(&3));\nassert!(b.contains(&17));\nassert!(b.contains(&41));btree_extract_if)Creates an iterator that visits all elements in ascending order and\nuses a closure to determine if an element should be removed.
\nIf the closure returns true, the element is removed from the set and\nyielded. If the closure returns false, or panics, the element remains\nin the set and will not be yielded.
If the returned ExtractIf is not exhausted, e.g. because it is dropped without iterating\nor the iteration short-circuits, then the remaining elements will be retained.\nUse retain with a negated predicate if you do not need the returned iterator.
Splitting a set into even and odd values, reusing the original set:
\n\n#![feature(btree_extract_if)]\nuse std::collections::BTreeSet;\n\nlet mut set: BTreeSet<i32> = (0..8).collect();\nlet evens: BTreeSet<_> = set.extract_if(|v| v % 2 == 0).collect();\nlet odds = set;\nassert_eq!(evens.into_iter().collect::<Vec<_>>(), vec![0, 2, 4, 6]);\nassert_eq!(odds.into_iter().collect::<Vec<_>>(), vec![1, 3, 5, 7]);Gets an iterator that visits the elements in the BTreeSet in ascending\norder.
use std::collections::BTreeSet;\n\nlet set = BTreeSet::from([3, 1, 2]);\nlet mut set_iter = set.iter();\nassert_eq!(set_iter.next(), Some(&1));\nassert_eq!(set_iter.next(), Some(&2));\nassert_eq!(set_iter.next(), Some(&3));\nassert_eq!(set_iter.next(), None);try_default in case the value is null or\nundefined.extend_one)extend_one)extend_one)extend_one)manual impl of FromDer, so we do not need to require TryFrom<Any> + CheckDerConstraints
self and other) and is used by the <=\noperator. Read moreVec<u8>.to_vec, but uses provided values without changes.\nThis can generate an invalid encoding for a DER object.to_der, but uses provided values without changes.\nThis can generate an invalid encoding for a DER object.Self from the given unstructured data. Read moreUnstructured this type\nneeds to construct itself. Read moreSelf from the entirety of the given\nunstructured data. Read moreMakes a clone of the Rc pointer.
This creates another pointer to the same allocation, increasing the\nstrong reference count.
\nuse std::rc::Rc;\n\nlet five = Rc::new(5);\n\nlet _ = Rc::clone(&five);source. Read moreDrops the Rc.
This will decrement the strong reference count. If the strong reference\ncount reaches zero then the only other references (if any) are\nWeak, so we drop the inner value.
use std::rc::Rc;\n\nstruct Foo;\n\nimpl Drop for Foo {\n fn drop(&mut self) {\n println!(\"dropped!\");\n }\n}\n\nlet foo = Rc::new(Foo);\nlet foo2 = Rc::clone(&foo);\n\ndrop(foo); // Doesn't print anything\ndrop(foo2); // Prints \"dropped!\"Comparison for two Rcs.
The two are compared by calling cmp() on their inner values.
use std::rc::Rc;\nuse std::cmp::Ordering;\n\nlet five = Rc::new(5);\n\nassert_eq!(Ordering::Less, five.cmp(&Rc::new(6)));Equality for two Rcs.
Two Rcs are equal if their inner values are equal, even if they are\nstored in different allocation.
If T also implements Eq (implying reflexivity of equality),\ntwo Rcs that point to the same allocation are\nalways equal.
use std::rc::Rc;\n\nlet five = Rc::new(5);\n\nassert!(five == Rc::new(5));Inequality for two Rcs.
Two Rcs are not equal if their inner values are not equal.
If T also implements Eq (implying reflexivity of equality),\ntwo Rcs that point to the same allocation are\nalways equal.
use std::rc::Rc;\n\nlet five = Rc::new(5);\n\nassert!(five != Rc::new(6));Partial comparison for two Rcs.
The two are compared by calling partial_cmp() on their inner values.
use std::rc::Rc;\nuse std::cmp::Ordering;\n\nlet five = Rc::new(5);\n\nassert_eq!(Some(Ordering::Less), five.partial_cmp(&Rc::new(6)));Less-than comparison for two Rcs.
The two are compared by calling < on their inner values.
use std::rc::Rc;\n\nlet five = Rc::new(5);\n\nassert!(five < Rc::new(6));‘Less than or equal to’ comparison for two Rcs.
The two are compared by calling <= on their inner values.
use std::rc::Rc;\n\nlet five = Rc::new(5);\n\nassert!(five <= Rc::new(5));Constructs an Rc<T> from a raw pointer.
The raw pointer must have been previously returned by a call to\nRc<U>::into_raw with the following requirements:
U is sized, it must have the same size and alignment as T. This\nis trivially true if U is T.U is unsized, its data pointer must have the same size and\nalignment as T. This is trivially true if Rc<U> was constructed\nthrough Rc<T> and then converted to Rc<U> through an unsized\ncoercion.Note that if U or U’s data pointer is not T but has the same size\nand alignment, this is basically like transmuting references of\ndifferent types. See mem::transmute for more information\non what restrictions apply in this case.
The raw pointer must point to a block of memory allocated by the global allocator
\nThe user of from_raw has to make sure a specific value of T is only\ndropped once.
This function is unsafe because improper use may lead to memory unsafety,\neven if the returned Rc<T> is never accessed.
use std::rc::Rc;\n\nlet x = Rc::new(\"hello\".to_owned());\nlet x_ptr = Rc::into_raw(x);\n\nunsafe {\n // Convert back to an `Rc` to prevent leak.\n let x = Rc::from_raw(x_ptr);\n assert_eq!(&*x, \"hello\");\n\n // Further calls to `Rc::from_raw(x_ptr)` would be memory-unsafe.\n}\n\n// The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling!Convert a slice back into its original array:
\n\nuse std::rc::Rc;\n\nlet x: Rc<[u32]> = Rc::new([1, 2, 3]);\nlet x_ptr: *const [u32] = Rc::into_raw(x);\n\nunsafe {\n let x: Rc<[u32; 3]> = Rc::from_raw(x_ptr.cast::<[u32; 3]>());\n assert_eq!(&*x, &[1, 2, 3]);\n}Increments the strong reference count on the Rc<T> associated with the\nprovided pointer by one.
The pointer must have been obtained through Rc::into_raw, the\nassociated Rc instance must be valid (i.e. the strong count must be at\nleast 1) for the duration of this method, and ptr must point to a block of memory\nallocated by the global allocator.
use std::rc::Rc;\n\nlet five = Rc::new(5);\n\nunsafe {\n let ptr = Rc::into_raw(five);\n Rc::increment_strong_count(ptr);\n\n let five = Rc::from_raw(ptr);\n assert_eq!(2, Rc::strong_count(&five));\n}Decrements the strong reference count on the Rc<T> associated with the\nprovided pointer by one.
The pointer must have been obtained through Rc::into_raw, the\nassociated Rc instance must be valid (i.e. the strong count must be at\nleast 1) when invoking this method, and ptr must point to a block of memory\nallocated by the global allocator. This method can be used to release the final Rc and\nbacking storage, but should not be called after the final Rc has been released.
use std::rc::Rc;\n\nlet five = Rc::new(5);\n\nunsafe {\n let ptr = Rc::into_raw(five);\n Rc::increment_strong_count(ptr);\n\n let five = Rc::from_raw(ptr);\n assert_eq!(2, Rc::strong_count(&five));\n Rc::decrement_strong_count(ptr);\n assert_eq!(1, Rc::strong_count(&five));\n}Constructs a new Rc<T> while giving you a Weak<T> to the allocation,\nto allow you to construct a T which holds a weak pointer to itself.
Generally, a structure circularly referencing itself, either directly or\nindirectly, should not hold a strong reference to itself to prevent a memory leak.\nUsing this function, you get access to the weak pointer during the\ninitialization of T, before the Rc<T> is created, such that you can\nclone and store it inside the T.
new_cyclic first allocates the managed allocation for the Rc<T>,\nthen calls your closure, giving it a Weak<T> to this allocation,\nand only afterwards completes the construction of the Rc<T> by placing\nthe T returned from your closure into the allocation.
Since the new Rc<T> is not fully-constructed until Rc<T>::new_cyclic\nreturns, calling upgrade on the weak reference inside your closure will\nfail and result in a None value.
If data_fn panics, the panic is propagated to the caller, and the\ntemporary Weak<T> is dropped normally.
use std::rc::{Rc, Weak};\n\nstruct Gadget {\n me: Weak<Gadget>,\n}\n\nimpl Gadget {\n /// Construct a reference counted Gadget.\n fn new() -> Rc<Self> {\n // `me` is a `Weak<Gadget>` pointing at the new allocation of the\n // `Rc` we're constructing.\n Rc::new_cyclic(|me| {\n // Create the actual struct here.\n Gadget { me: me.clone() }\n })\n }\n\n /// Return a reference counted pointer to Self.\n fn me(&self) -> Rc<Self> {\n self.me.upgrade().unwrap()\n }\n}new_uninit)Constructs a new Rc with uninitialized contents.
#![feature(new_uninit)]\n#![feature(get_mut_unchecked)]\n\nuse std::rc::Rc;\n\nlet mut five = Rc::<u32>::new_uninit();\n\n// Deferred initialization:\nRc::get_mut(&mut five).unwrap().write(5);\n\nlet five = unsafe { five.assume_init() };\n\nassert_eq!(*five, 5)new_uninit)Constructs a new Rc with uninitialized contents, with the memory\nbeing filled with 0 bytes.
See MaybeUninit::zeroed for examples of correct and\nincorrect usage of this method.
#![feature(new_uninit)]\n\nuse std::rc::Rc;\n\nlet zero = Rc::<u32>::new_zeroed();\nlet zero = unsafe { zero.assume_init() };\n\nassert_eq!(*zero, 0)allocator_api)Constructs a new Rc<T>, returning an error if the allocation fails
#![feature(allocator_api)]\nuse std::rc::Rc;\n\nlet five = Rc::try_new(5);allocator_api)Constructs a new Rc with uninitialized contents, returning an error if the allocation fails
#![feature(allocator_api, new_uninit)]\n#![feature(get_mut_unchecked)]\n\nuse std::rc::Rc;\n\nlet mut five = Rc::<u32>::try_new_uninit()?;\n\n// Deferred initialization:\nRc::get_mut(&mut five).unwrap().write(5);\n\nlet five = unsafe { five.assume_init() };\n\nassert_eq!(*five, 5);allocator_api)Constructs a new Rc with uninitialized contents, with the memory\nbeing filled with 0 bytes, returning an error if the allocation fails
See MaybeUninit::zeroed for examples of correct and\nincorrect usage of this method.
#![feature(allocator_api, new_uninit)]\n\nuse std::rc::Rc;\n\nlet zero = Rc::<u32>::try_new_zeroed()?;\nlet zero = unsafe { zero.assume_init() };\n\nassert_eq!(*zero, 0);Consumes the Rc, returning the wrapped pointer.
To avoid a memory leak the pointer must be converted back to an Rc using\nRc::from_raw.
use std::rc::Rc;\n\nlet x = Rc::new(\"hello\".to_owned());\nlet x_ptr = Rc::into_raw(x);\nassert_eq!(unsafe { &*x_ptr }, \"hello\");allocator_api)Consumes the Rc, returning the wrapped pointer and allocator.
To avoid a memory leak the pointer must be converted back to an Rc using\nRc::from_raw_in.
#![feature(allocator_api)]\nuse std::rc::Rc;\nuse std::alloc::System;\n\nlet x = Rc::new_in(\"hello\".to_owned(), System);\nlet (ptr, alloc) = Rc::into_raw_with_allocator(x);\nassert_eq!(unsafe { &*ptr }, \"hello\");\nlet x = unsafe { Rc::from_raw_in(ptr, alloc) };\nassert_eq!(&*x, \"hello\");Provides a raw pointer to the data.
\nThe counts are not affected in any way and the Rc is not consumed. The pointer is valid\nfor as long there are strong counts in the Rc.
use std::rc::Rc;\n\nlet x = Rc::new(\"hello\".to_owned());\nlet y = Rc::clone(&x);\nlet x_ptr = Rc::as_ptr(&x);\nassert_eq!(x_ptr, Rc::as_ptr(&y));\nassert_eq!(unsafe { &*x_ptr }, \"hello\");allocator_api)Constructs an Rc<T, A> from a raw pointer in the provided allocator.
The raw pointer must have been previously returned by a call to Rc<U, A>::into_raw with the following requirements:
U is sized, it must have the same size and alignment as T. This\nis trivially true if U is T.U is unsized, its data pointer must have the same size and\nalignment as T. This is trivially true if Rc<U> was constructed\nthrough Rc<T> and then converted to Rc<U> through an unsized\ncoercion.Note that if U or U’s data pointer is not T but has the same size\nand alignment, this is basically like transmuting references of\ndifferent types. See mem::transmute for more information\non what restrictions apply in this case.
The raw pointer must point to a block of memory allocated by alloc
The user of from_raw has to make sure a specific value of T is only\ndropped once.
This function is unsafe because improper use may lead to memory unsafety,\neven if the returned Rc<T> is never accessed.
#![feature(allocator_api)]\n\nuse std::rc::Rc;\nuse std::alloc::System;\n\nlet x = Rc::new_in(\"hello\".to_owned(), System);\nlet x_ptr = Rc::into_raw(x);\n\nunsafe {\n // Convert back to an `Rc` to prevent leak.\n let x = Rc::from_raw_in(x_ptr, System);\n assert_eq!(&*x, \"hello\");\n\n // Further calls to `Rc::from_raw(x_ptr)` would be memory-unsafe.\n}\n\n// The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling!Convert a slice back into its original array:
\n\n#![feature(allocator_api)]\n\nuse std::rc::Rc;\nuse std::alloc::System;\n\nlet x: Rc<[u32], _> = Rc::new_in([1, 2, 3], System);\nlet x_ptr: *const [u32] = Rc::into_raw(x);\n\nunsafe {\n let x: Rc<[u32; 3], _> = Rc::from_raw_in(x_ptr.cast::<[u32; 3]>(), System);\n assert_eq!(&*x, &[1, 2, 3]);\n}Gets the number of strong (Rc) pointers to this allocation.
use std::rc::Rc;\n\nlet five = Rc::new(5);\nlet _also_five = Rc::clone(&five);\n\nassert_eq!(2, Rc::strong_count(&five));allocator_api)Increments the strong reference count on the Rc<T> associated with the\nprovided pointer by one.
The pointer must have been obtained through Rc::into_raw, the\nassociated Rc instance must be valid (i.e. the strong count must be at\nleast 1) for the duration of this method, and ptr must point to a block of memory\nallocated by alloc
#![feature(allocator_api)]\n\nuse std::rc::Rc;\nuse std::alloc::System;\n\nlet five = Rc::new_in(5, System);\n\nunsafe {\n let ptr = Rc::into_raw(five);\n Rc::increment_strong_count_in(ptr, System);\n\n let five = Rc::from_raw_in(ptr, System);\n assert_eq!(2, Rc::strong_count(&five));\n}allocator_api)Decrements the strong reference count on the Rc<T> associated with the\nprovided pointer by one.
The pointer must have been obtained through Rc::into_raw, the\nassociated Rc instance must be valid (i.e. the strong count must be at\nleast 1) when invoking this method, and ptr must point to a block of memory\nallocated by alloc. This method can be used to release the final Rc and backing storage,\nbut should not be called after the final Rc has been released.
#![feature(allocator_api)]\n\nuse std::rc::Rc;\nuse std::alloc::System;\n\nlet five = Rc::new_in(5, System);\n\nunsafe {\n let ptr = Rc::into_raw(five);\n Rc::increment_strong_count_in(ptr, System);\n\n let five = Rc::from_raw_in(ptr, System);\n assert_eq!(2, Rc::strong_count(&five));\n Rc::decrement_strong_count_in(ptr, System);\n assert_eq!(1, Rc::strong_count(&five));\n}Returns a mutable reference into the given Rc, if there are\nno other Rc or Weak pointers to the same allocation.
Returns None otherwise, because it is not safe to\nmutate a shared value.
See also make_mut, which will clone\nthe inner value when there are other Rc pointers.
use std::rc::Rc;\n\nlet mut x = Rc::new(3);\n*Rc::get_mut(&mut x).unwrap() = 4;\nassert_eq!(*x, 4);\n\nlet _y = Rc::clone(&x);\nassert!(Rc::get_mut(&mut x).is_none());get_mut_unchecked)Returns a mutable reference into the given Rc,\nwithout any check.
See also get_mut, which is safe and does appropriate checks.
If any other Rc or Weak pointers to the same allocation exist, then\nthey must not be dereferenced or have active borrows for the duration\nof the returned borrow, and their inner type must be exactly the same as the\ninner type of this Rc (including lifetimes). This is trivially the case if no\nsuch pointers exist, for example immediately after Rc::new.
#![feature(get_mut_unchecked)]\n\nuse std::rc::Rc;\n\nlet mut x = Rc::new(String::new());\nunsafe {\n Rc::get_mut_unchecked(&mut x).push_str(\"foo\")\n}\nassert_eq!(*x, \"foo\");Other Rc pointers to the same allocation must be to the same type.
#![feature(get_mut_unchecked)]\n\nuse std::rc::Rc;\n\nlet x: Rc<str> = Rc::from(\"Hello, world!\");\nlet mut y: Rc<[u8]> = x.clone().into();\nunsafe {\n // this is Undefined Behavior, because x's inner type is str, not [u8]\n Rc::get_mut_unchecked(&mut y).fill(0xff); // 0xff is invalid in UTF-8\n}\nprintln!(\"{}\", &*x); // Invalid UTF-8 in a strOther Rc pointers to the same allocation must be to the exact same type, including lifetimes.
#![feature(get_mut_unchecked)]\n\nuse std::rc::Rc;\n\nlet x: Rc<&str> = Rc::new(\"Hello, world!\");\n{\n let s = String::from(\"Oh, no!\");\n let mut y: Rc<&str> = x.clone().into();\n unsafe {\n // this is Undefined Behavior, because x's inner type\n // is &'long str, not &'short str\n *Rc::get_mut_unchecked(&mut y) = &s;\n }\n}\nprintln!(\"{}\", &*x); // Use-after-freeReturns true if the two Rcs point to the same allocation in a vein similar to\nptr::eq. This function ignores the metadata of dyn Trait pointers.
use std::rc::Rc;\n\nlet five = Rc::new(5);\nlet same_five = Rc::clone(&five);\nlet other_five = Rc::new(5);\n\nassert!(Rc::ptr_eq(&five, &same_five));\nassert!(!Rc::ptr_eq(&five, &other_five));Makes a mutable reference into the given Rc.
If there are other Rc pointers to the same allocation, then make_mut will\nclone the inner value to a new allocation to ensure unique ownership. This is also\nreferred to as clone-on-write.
However, if there are no other Rc pointers to this allocation, but some Weak\npointers, then the Weak pointers will be disassociated and the inner value will not\nbe cloned.
See also get_mut, which will fail rather than cloning the inner value\nor disassociating Weak pointers.
use std::rc::Rc;\n\nlet mut data = Rc::new(5);\n\n*Rc::make_mut(&mut data) += 1; // Won't clone anything\nlet mut other_data = Rc::clone(&data); // Won't clone inner data\n*Rc::make_mut(&mut data) += 1; // Clones inner data\n*Rc::make_mut(&mut data) += 1; // Won't clone anything\n*Rc::make_mut(&mut other_data) *= 2; // Won't clone anything\n\n// Now `data` and `other_data` point to different allocations.\nassert_eq!(*data, 8);\nassert_eq!(*other_data, 12);Weak pointers will be disassociated:
use std::rc::Rc;\n\nlet mut data = Rc::new(75);\nlet weak = Rc::downgrade(&data);\n\nassert!(75 == *data);\nassert!(75 == *weak.upgrade().unwrap());\n\n*Rc::make_mut(&mut data) += 1;\n\nassert!(76 == *data);\nassert!(weak.upgrade().is_none());If we have the only reference to T then unwrap it. Otherwise, clone T and return the\nclone.
Assuming rc_t is of type Rc<T>, this function is functionally equivalent to\n(*rc_t).clone(), but will avoid cloning the inner value where possible.
let inner = String::from(\"test\");\nlet ptr = inner.as_ptr();\n\nlet rc = Rc::new(inner);\nlet inner = Rc::unwrap_or_clone(rc);\n// The inner value was not cloned\nassert!(ptr::eq(ptr, inner.as_ptr()));\n\nlet rc = Rc::new(inner);\nlet rc2 = rc.clone();\nlet inner = Rc::unwrap_or_clone(rc);\n// Because there were 2 references, we had to clone the inner value.\nassert!(!ptr::eq(ptr, inner.as_ptr()));\n// `rc2` is the last reference, so when we unwrap it we get back\n// the original `String`.\nlet inner = Rc::unwrap_or_clone(rc2);\nassert!(ptr::eq(ptr, inner.as_ptr()));allocator_api)Returns a reference to the underlying allocator.
\nNote: this is an associated function, which means that you have\nto call it as Rc::allocator(&r) instead of r.allocator(). This\nis so that there is no conflict with a method on the inner type.
allocator_api)Constructs a new Rc in the provided allocator.
#![feature(allocator_api)]\nuse std::rc::Rc;\nuse std::alloc::System;\n\nlet five = Rc::new_in(5, System);allocator_api)Constructs a new Rc with uninitialized contents in the provided allocator.
#![feature(new_uninit)]\n#![feature(get_mut_unchecked)]\n#![feature(allocator_api)]\n\nuse std::rc::Rc;\nuse std::alloc::System;\n\nlet mut five = Rc::<u32, _>::new_uninit_in(System);\n\nlet five = unsafe {\n // Deferred initialization:\n Rc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);\n\n five.assume_init()\n};\n\nassert_eq!(*five, 5)allocator_api)Constructs a new Rc with uninitialized contents, with the memory\nbeing filled with 0 bytes, in the provided allocator.
See MaybeUninit::zeroed for examples of correct and\nincorrect usage of this method.
#![feature(new_uninit)]\n#![feature(allocator_api)]\n\nuse std::rc::Rc;\nuse std::alloc::System;\n\nlet zero = Rc::<u32, _>::new_zeroed_in(System);\nlet zero = unsafe { zero.assume_init() };\n\nassert_eq!(*zero, 0)allocator_api)Constructs a new Rc<T> in the provided allocator, returning an error if the allocation\nfails
#![feature(allocator_api)]\nuse std::rc::Rc;\nuse std::alloc::System;\n\nlet five = Rc::try_new_in(5, System);allocator_api)Constructs a new Rc with uninitialized contents, in the provided allocator, returning an\nerror if the allocation fails
#![feature(allocator_api, new_uninit)]\n#![feature(get_mut_unchecked)]\n\nuse std::rc::Rc;\nuse std::alloc::System;\n\nlet mut five = Rc::<u32, _>::try_new_uninit_in(System)?;\n\nlet five = unsafe {\n // Deferred initialization:\n Rc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);\n\n five.assume_init()\n};\n\nassert_eq!(*five, 5);allocator_api)Constructs a new Rc with uninitialized contents, with the memory\nbeing filled with 0 bytes, in the provided allocator, returning an error if the allocation\nfails
See MaybeUninit::zeroed for examples of correct and\nincorrect usage of this method.
#![feature(allocator_api, new_uninit)]\n\nuse std::rc::Rc;\nuse std::alloc::System;\n\nlet zero = Rc::<u32, _>::try_new_zeroed_in(System)?;\nlet zero = unsafe { zero.assume_init() };\n\nassert_eq!(*zero, 0);allocator_api)Constructs a new Pin<Rc<T>> in the provided allocator. If T does not implement Unpin, then\nvalue will be pinned in memory and unable to be moved.
Returns the inner value, if the Rc has exactly one strong reference.
Otherwise, an Err is returned with the same Rc that was\npassed in.
This will succeed even if there are outstanding weak references.
\nuse std::rc::Rc;\n\nlet x = Rc::new(3);\nassert_eq!(Rc::try_unwrap(x), Ok(3));\n\nlet x = Rc::new(4);\nlet _y = Rc::clone(&x);\nassert_eq!(*Rc::try_unwrap(x).unwrap_err(), 4);Returns the inner value, if the Rc has exactly one strong reference.
Otherwise, None is returned and the Rc is dropped.
This will succeed even if there are outstanding weak references.
\nIf Rc::into_inner is called on every clone of this Rc,\nit is guaranteed that exactly one of the calls returns the inner value.\nThis means in particular that the inner value is not dropped.
Rc::try_unwrap is conceptually similar to Rc::into_inner.\nAnd while they are meant for different use-cases, Rc::into_inner(this)\nis in fact equivalent to Rc::try_unwrap(this).ok().\n(Note that the same kind of equivalence does not hold true for\nArc, due to race conditions that do not apply to Rc!)
use std::rc::Rc;\n\nlet x = Rc::new(3);\nassert_eq!(Rc::into_inner(x), Some(3));\n\nlet x = Rc::new(4);\nlet y = Rc::clone(&x);\n\nassert_eq!(Rc::into_inner(y), None);\nassert_eq!(Rc::into_inner(x), Some(4));Implements the + operator for concatenating two strings.
This consumes the String on the left-hand side and re-uses its buffer (growing it if\nnecessary). This is done to avoid allocating a new String and copying the entire contents on\nevery operation, which would lead to O(n^2) running time when building an n-byte string by\nrepeated concatenation.
The string on the right-hand side is only borrowed; its contents are copied into the returned\nString.
Concatenating two Strings takes the first by value and borrows the second:
let a = String::from(\"hello\");\nlet b = String::from(\" world\");\nlet c = a + &b;\n// `a` is moved and can no longer be used here.If you want to keep using the first String, you can clone it and append to the clone instead:
let a = String::from(\"hello\");\nlet b = String::from(\" world\");\nlet c = a.clone() + &b;\n// `a` is still valid here.Concatenating &str slices can be done by converting the first to a String:
let a = \"hello\";\nlet b = \" world\";\nlet c = a.to_string() + b;Implements the += operator for appending to a String.
This has the same behavior as the push_str method.
+= operation. Read moreSelf from the given unstructured data. Read moreSelf from the entirety of the given\nunstructured data. Read moretry_default in case the value is null or\nundefined.Reader].extend_one)extend_one)extend_one)extend_one)extend_one)extend_one)extend_one)extend_one)extend_one)extend_one)extend_one)extend_one)extend_one)extend_one)Converts a clone-on-write string to an owned\ninstance of String.
This extracts the owned string,\nclones the string if it is not already owned.
\n// If the string is not owned...\nlet cow: Cow<'_, str> = Cow::Borrowed(\"eggplant\");\n// It will allocate on the heap and copy the string.\nlet owned: String = String::from(cow);\nassert_eq!(&owned[..], \"eggplant\");google.protobuf.StringValue
self. Read moreself.self and other) and is used by the <=\noperator. Read moreself and other) and is used by the <=\noperator. Read moreself and other) and is used by the <=\noperator. Read moredst to replace the current match. Read moreCreates a new empty String.
Given that the String is empty, this will not allocate any initial\nbuffer. While that means that this initial operation is very\ninexpensive, it may cause excessive allocation later when you add\ndata. If you have an idea of how much data the String will hold,\nconsider the with_capacity method to prevent excessive\nre-allocation.
let s = String::new();Creates a new empty String with at least the specified capacity.
Strings have an internal buffer to hold their data. The capacity is\nthe length of that buffer, and can be queried with the capacity\nmethod. This method creates an empty String, but one with an initial\nbuffer that can hold at least capacity bytes. This is useful when you\nmay be appending a bunch of data to the String, reducing the number of\nreallocations it needs to do.
If the given capacity is 0, no allocation will occur, and this method\nis identical to the new method.
let mut s = String::with_capacity(10);\n\n// The String contains no chars, even though it has capacity for more\nassert_eq!(s.len(), 0);\n\n// These are all done without reallocating...\nlet cap = s.capacity();\nfor _ in 0..10 {\n s.push('a');\n}\n\nassert_eq!(s.capacity(), cap);\n\n// ...but this may make the string reallocate\ns.push('a');try_with_capacity)Converts a vector of bytes to a String.
A string (String) is made of bytes (u8), and a vector of bytes\n(Vec<u8>) is made of bytes, so this function converts between the\ntwo. Not all byte slices are valid Strings, however: String\nrequires that it is valid UTF-8. from_utf8() checks to ensure that\nthe bytes are valid UTF-8, and then does the conversion.
If you are sure that the byte slice is valid UTF-8, and you don’t want\nto incur the overhead of the validity check, there is an unsafe version\nof this function, from_utf8_unchecked, which has the same behavior\nbut skips the check.
This method will take care to not copy the vector, for efficiency’s\nsake.
\nIf you need a &str instead of a String, consider\nstr::from_utf8.
The inverse of this method is into_bytes.
Returns Err if the slice is not UTF-8 with a description as to why the\nprovided bytes are not UTF-8. The vector you moved in is also included.
Basic usage:
\n\n// some bytes, in a vector\nlet sparkle_heart = vec![240, 159, 146, 150];\n\n// We know these bytes are valid, so we'll use `unwrap()`.\nlet sparkle_heart = String::from_utf8(sparkle_heart).unwrap();\n\nassert_eq!(\"💖\", sparkle_heart);Incorrect bytes:
\n\n// some invalid bytes, in a vector\nlet sparkle_heart = vec![0, 159, 146, 150];\n\nassert!(String::from_utf8(sparkle_heart).is_err());See the docs for FromUtf8Error for more details on what you can do\nwith this error.
Converts a slice of bytes to a string, including invalid characters.
\nStrings are made of bytes (u8), and a slice of bytes\n(&[u8]) is made of bytes, so this function converts\nbetween the two. Not all byte slices are valid strings, however: strings\nare required to be valid UTF-8. During this conversion,\nfrom_utf8_lossy() will replace any invalid UTF-8 sequences with\nU+FFFD REPLACEMENT CHARACTER, which looks like this: �
If you are sure that the byte slice is valid UTF-8, and you don’t want\nto incur the overhead of the conversion, there is an unsafe version\nof this function, from_utf8_unchecked, which has the same behavior\nbut skips the checks.
This function returns a Cow<'a, str>. If our byte slice is invalid\nUTF-8, then we need to insert the replacement characters, which will\nchange the size of the string, and hence, require a String. But if\nit’s already valid UTF-8, we don’t need a new allocation. This return\ntype allows us to handle both cases.
Basic usage:
\n\n// some bytes, in a vector\nlet sparkle_heart = vec![240, 159, 146, 150];\n\nlet sparkle_heart = String::from_utf8_lossy(&sparkle_heart);\n\nassert_eq!(\"💖\", sparkle_heart);Incorrect bytes:
\n\n// some invalid bytes\nlet input = b\"Hello \\xF0\\x90\\x80World\";\nlet output = String::from_utf8_lossy(input);\n\nassert_eq!(\"Hello �World\", output);Decode a UTF-16–encoded vector v into a String, returning Err\nif v contains any invalid data.
// 𝄞music\nlet v = &[0xD834, 0xDD1E, 0x006d, 0x0075,\n 0x0073, 0x0069, 0x0063];\nassert_eq!(String::from(\"𝄞music\"),\n String::from_utf16(v).unwrap());\n\n// 𝄞mu<invalid>ic\nlet v = &[0xD834, 0xDD1E, 0x006d, 0x0075,\n 0xD800, 0x0069, 0x0063];\nassert!(String::from_utf16(v).is_err());Decode a UTF-16–encoded slice v into a String, replacing\ninvalid data with the replacement character (U+FFFD).
Unlike from_utf8_lossy which returns a Cow<'a, str>,\nfrom_utf16_lossy returns a String since the UTF-16 to UTF-8\nconversion requires a memory allocation.
// 𝄞mus<invalid>ic<invalid>\nlet v = &[0xD834, 0xDD1E, 0x006d, 0x0075,\n 0x0073, 0xDD1E, 0x0069, 0x0063,\n 0xD834];\n\nassert_eq!(String::from(\"𝄞mus\\u{FFFD}ic\\u{FFFD}\"),\n String::from_utf16_lossy(v));str_from_utf16_endian)Decode a UTF-16LE–encoded vector v into a String, returning Err\nif v contains any invalid data.
Basic usage:
\n\n#![feature(str_from_utf16_endian)]\n// 𝄞music\nlet v = &[0x34, 0xD8, 0x1E, 0xDD, 0x6d, 0x00, 0x75, 0x00,\n 0x73, 0x00, 0x69, 0x00, 0x63, 0x00];\nassert_eq!(String::from(\"𝄞music\"),\n String::from_utf16le(v).unwrap());\n\n// 𝄞mu<invalid>ic\nlet v = &[0x34, 0xD8, 0x1E, 0xDD, 0x6d, 0x00, 0x75, 0x00,\n 0x00, 0xD8, 0x69, 0x00, 0x63, 0x00];\nassert!(String::from_utf16le(v).is_err());str_from_utf16_endian)Decode a UTF-16LE–encoded slice v into a String, replacing\ninvalid data with the replacement character (U+FFFD).
Unlike from_utf8_lossy which returns a Cow<'a, str>,\nfrom_utf16le_lossy returns a String since the UTF-16 to UTF-8\nconversion requires a memory allocation.
Basic usage:
\n\n#![feature(str_from_utf16_endian)]\n// 𝄞mus<invalid>ic<invalid>\nlet v = &[0x34, 0xD8, 0x1E, 0xDD, 0x6d, 0x00, 0x75, 0x00,\n 0x73, 0x00, 0x1E, 0xDD, 0x69, 0x00, 0x63, 0x00,\n 0x34, 0xD8];\n\nassert_eq!(String::from(\"𝄞mus\\u{FFFD}ic\\u{FFFD}\"),\n String::from_utf16le_lossy(v));str_from_utf16_endian)Decode a UTF-16BE–encoded vector v into a String, returning Err\nif v contains any invalid data.
Basic usage:
\n\n#![feature(str_from_utf16_endian)]\n// 𝄞music\nlet v = &[0xD8, 0x34, 0xDD, 0x1E, 0x00, 0x6d, 0x00, 0x75,\n 0x00, 0x73, 0x00, 0x69, 0x00, 0x63];\nassert_eq!(String::from(\"𝄞music\"),\n String::from_utf16be(v).unwrap());\n\n// 𝄞mu<invalid>ic\nlet v = &[0xD8, 0x34, 0xDD, 0x1E, 0x00, 0x6d, 0x00, 0x75,\n 0xD8, 0x00, 0x00, 0x69, 0x00, 0x63];\nassert!(String::from_utf16be(v).is_err());str_from_utf16_endian)Decode a UTF-16BE–encoded slice v into a String, replacing\ninvalid data with the replacement character (U+FFFD).
Unlike from_utf8_lossy which returns a Cow<'a, str>,\nfrom_utf16le_lossy returns a String since the UTF-16 to UTF-8\nconversion requires a memory allocation.
Basic usage:
\n\n#![feature(str_from_utf16_endian)]\n// 𝄞mus<invalid>ic<invalid>\nlet v = &[0xD8, 0x34, 0xDD, 0x1E, 0x00, 0x6d, 0x00, 0x75,\n 0x00, 0x73, 0xDD, 0x1E, 0x00, 0x69, 0x00, 0x63,\n 0xD8, 0x34];\n\nassert_eq!(String::from(\"𝄞mus\\u{FFFD}ic\\u{FFFD}\"),\n String::from_utf16be_lossy(v));vec_into_raw_parts)Decomposes a String into its raw components: (pointer, length, capacity).
Returns the raw pointer to the underlying data, the length of\nthe string (in bytes), and the allocated capacity of the data\n(in bytes). These are the same arguments in the same order as\nthe arguments to from_raw_parts.
After calling this function, the caller is responsible for the\nmemory previously managed by the String. The only way to do\nthis is to convert the raw pointer, length, and capacity back\ninto a String with the from_raw_parts function, allowing\nthe destructor to perform the cleanup.
#![feature(vec_into_raw_parts)]\nlet s = String::from(\"hello\");\n\nlet (ptr, len, cap) = s.into_raw_parts();\n\nlet rebuilt = unsafe { String::from_raw_parts(ptr, len, cap) };\nassert_eq!(rebuilt, \"hello\");Creates a new String from a pointer, a length and a capacity.
This is highly unsafe, due to the number of invariants that aren’t\nchecked:
\nbuf needs to have been previously allocated by the\nsame allocator the standard library uses, with a required alignment of exactly 1.length needs to be less than or equal to capacity.capacity needs to be the correct value.length bytes at buf need to be valid UTF-8.Violating these may cause problems like corrupting the allocator’s\ninternal data structures. For example, it is normally not safe to\nbuild a String from a pointer to a C char array containing UTF-8\nunless you are certain that array was originally allocated by the\nRust standard library’s allocator.
The ownership of buf is effectively transferred to the\nString which may then deallocate, reallocate or change the\ncontents of memory pointed to by the pointer at will. Ensure\nthat nothing else uses the pointer after calling this\nfunction.
use std::mem;\n\nunsafe {\n let s = String::from(\"hello\");\n\n // Prevent automatically dropping the String's data\n let mut s = mem::ManuallyDrop::new(s);\n\n let ptr = s.as_mut_ptr();\n let len = s.len();\n let capacity = s.capacity();\n\n let s = String::from_raw_parts(ptr, len, capacity);\n\n assert_eq!(String::from(\"hello\"), s);\n}Converts a vector of bytes to a String without checking that the\nstring contains valid UTF-8.
See the safe version, from_utf8, for more details.
This function is unsafe because it does not check that the bytes passed\nto it are valid UTF-8. If this constraint is violated, it may cause\nmemory unsafety issues with future users of the String, as the rest of\nthe standard library assumes that Strings are valid UTF-8.
// some bytes, in a vector\nlet sparkle_heart = vec![240, 159, 146, 150];\n\nlet sparkle_heart = unsafe {\n String::from_utf8_unchecked(sparkle_heart)\n};\n\nassert_eq!(\"💖\", sparkle_heart);Converts a String into a byte vector.
This consumes the String, so we do not need to copy its contents.
let s = String::from(\"hello\");\nlet bytes = s.into_bytes();\n\nassert_eq!(&[104, 101, 108, 108, 111][..], &bytes[..]);Extracts a string slice containing the entire String.
let s = String::from(\"foo\");\n\nassert_eq!(\"foo\", s.as_str());Converts a String into a mutable string slice.
let mut s = String::from(\"foobar\");\nlet s_mut_str = s.as_mut_str();\n\ns_mut_str.make_ascii_uppercase();\n\nassert_eq!(\"FOOBAR\", s_mut_str);Appends a given string slice onto the end of this String.
let mut s = String::from(\"foo\");\n\ns.push_str(\"bar\");\n\nassert_eq!(\"foobar\", s);string_extend_from_within)Copies elements from src range to the end of the string.
Panics if the starting point or end point do not lie on a char\nboundary, or if they’re out of bounds.
#![feature(string_extend_from_within)]\nlet mut string = String::from(\"abcde\");\n\nstring.extend_from_within(2..);\nassert_eq!(string, \"abcdecde\");\n\nstring.extend_from_within(..2);\nassert_eq!(string, \"abcdecdeab\");\n\nstring.extend_from_within(4..8);\nassert_eq!(string, \"abcdecdeabecde\");Returns this String’s capacity, in bytes.
let s = String::with_capacity(10);\n\nassert!(s.capacity() >= 10);Reserves capacity for at least additional bytes more than the\ncurrent length. The allocator may reserve more space to speculatively\navoid frequent allocations. After calling reserve,\ncapacity will be greater than or equal to self.len() + additional.\nDoes nothing if capacity is already sufficient.
Panics if the new capacity overflows usize.
Basic usage:
\n\nlet mut s = String::new();\n\ns.reserve(10);\n\nassert!(s.capacity() >= 10);This might not actually increase the capacity:
\n\nlet mut s = String::with_capacity(10);\ns.push('a');\ns.push('b');\n\n// s now has a length of 2 and a capacity of at least 10\nlet capacity = s.capacity();\nassert_eq!(2, s.len());\nassert!(capacity >= 10);\n\n// Since we already have at least an extra 8 capacity, calling this...\ns.reserve(8);\n\n// ... doesn't actually increase.\nassert_eq!(capacity, s.capacity());Reserves the minimum capacity for at least additional bytes more than\nthe current length. Unlike reserve, this will not\ndeliberately over-allocate to speculatively avoid frequent allocations.\nAfter calling reserve_exact, capacity will be greater than or equal to\nself.len() + additional. Does nothing if the capacity is already\nsufficient.
Panics if the new capacity overflows usize.
Basic usage:
\n\nlet mut s = String::new();\n\ns.reserve_exact(10);\n\nassert!(s.capacity() >= 10);This might not actually increase the capacity:
\n\nlet mut s = String::with_capacity(10);\ns.push('a');\ns.push('b');\n\n// s now has a length of 2 and a capacity of at least 10\nlet capacity = s.capacity();\nassert_eq!(2, s.len());\nassert!(capacity >= 10);\n\n// Since we already have at least an extra 8 capacity, calling this...\ns.reserve_exact(8);\n\n// ... doesn't actually increase.\nassert_eq!(capacity, s.capacity());Tries to reserve capacity for at least additional bytes more than the\ncurrent length. The allocator may reserve more space to speculatively\navoid frequent allocations. After calling try_reserve, capacity will be\ngreater than or equal to self.len() + additional if it returns\nOk(()). Does nothing if capacity is already sufficient. This method\npreserves the contents even if an error occurs.
If the capacity overflows, or the allocator reports a failure, then an error\nis returned.
\nuse std::collections::TryReserveError;\n\nfn process_data(data: &str) -> Result<String, TryReserveError> {\n let mut output = String::new();\n\n // Pre-reserve the memory, exiting if we can't\n output.try_reserve(data.len())?;\n\n // Now we know this can't OOM in the middle of our complex work\n output.push_str(data);\n\n Ok(output)\n}Tries to reserve the minimum capacity for at least additional bytes\nmore than the current length. Unlike try_reserve, this will not\ndeliberately over-allocate to speculatively avoid frequent allocations.\nAfter calling try_reserve_exact, capacity will be greater than or\nequal to self.len() + additional if it returns Ok(()).\nDoes nothing if the capacity is already sufficient.
Note that the allocator may give the collection more space than it\nrequests. Therefore, capacity can not be relied upon to be precisely\nminimal. Prefer try_reserve if future insertions are expected.
If the capacity overflows, or the allocator reports a failure, then an error\nis returned.
\nuse std::collections::TryReserveError;\n\nfn process_data(data: &str) -> Result<String, TryReserveError> {\n let mut output = String::new();\n\n // Pre-reserve the memory, exiting if we can't\n output.try_reserve_exact(data.len())?;\n\n // Now we know this can't OOM in the middle of our complex work\n output.push_str(data);\n\n Ok(output)\n}Shrinks the capacity of this String to match its length.
let mut s = String::from(\"foo\");\n\ns.reserve(100);\nassert!(s.capacity() >= 100);\n\ns.shrink_to_fit();\nassert_eq!(3, s.capacity());Shrinks the capacity of this String with a lower bound.
The capacity will remain at least as large as both the length\nand the supplied value.
\nIf the current capacity is less than the lower limit, this is a no-op.
\nlet mut s = String::from(\"foo\");\n\ns.reserve(100);\nassert!(s.capacity() >= 100);\n\ns.shrink_to(10);\nassert!(s.capacity() >= 10);\ns.shrink_to(0);\nassert!(s.capacity() >= 3);Shortens this String to the specified length.
If new_len is greater than or equal to the string’s current length, this has no\neffect.
Note that this method has no effect on the allocated capacity\nof the string
\nPanics if new_len does not lie on a char boundary.
let mut s = String::from(\"hello\");\n\ns.truncate(2);\n\nassert_eq!(\"he\", s);Removes a char from this String at a byte position and returns it.
This is an O(n) operation, as it requires copying every element in the\nbuffer.
\nPanics if idx is larger than or equal to the String’s length,\nor if it does not lie on a char boundary.
let mut s = String::from(\"abç\");\n\nassert_eq!(s.remove(0), 'a');\nassert_eq!(s.remove(1), 'ç');\nassert_eq!(s.remove(0), 'b');string_remove_matches)Remove all matches of pattern pat in the String.
#![feature(string_remove_matches)]\nlet mut s = String::from(\"Trees are not green, the sky is not blue.\");\ns.remove_matches(\"not \");\nassert_eq!(\"Trees are green, the sky is blue.\", s);Matches will be detected and removed iteratively, so in cases where\npatterns overlap, only the first pattern will be removed:
\n\n#![feature(string_remove_matches)]\nlet mut s = String::from(\"banana\");\ns.remove_matches(\"ana\");\nassert_eq!(\"bna\", s);Retains only the characters specified by the predicate.
\nIn other words, remove all characters c such that f(c) returns false.\nThis method operates in place, visiting each character exactly once in the\noriginal order, and preserves the order of the retained characters.
let mut s = String::from(\"f_o_ob_ar\");\n\ns.retain(|c| c != '_');\n\nassert_eq!(s, \"foobar\");Because the elements are visited exactly once in the original order,\nexternal state may be used to decide which elements to keep.
\n\nlet mut s = String::from(\"abcde\");\nlet keep = [false, true, true, false, true];\nlet mut iter = keep.iter();\ns.retain(|_| *iter.next().unwrap());\nassert_eq!(s, \"bce\");Inserts a character into this String at a byte position.
This is an O(n) operation as it requires copying every element in the\nbuffer.
\nPanics if idx is larger than the String’s length, or if it does not\nlie on a char boundary.
let mut s = String::with_capacity(3);\n\ns.insert(0, 'f');\ns.insert(1, 'o');\ns.insert(2, 'o');\n\nassert_eq!(\"foo\", s);Inserts a string slice into this String at a byte position.
This is an O(n) operation as it requires copying every element in the\nbuffer.
\nPanics if idx is larger than the String’s length, or if it does not\nlie on a char boundary.
let mut s = String::from(\"bar\");\n\ns.insert_str(0, \"foo\");\n\nassert_eq!(\"foobar\", s);Returns a mutable reference to the contents of this String.
This function is unsafe because the returned &mut Vec allows writing\nbytes which are not valid UTF-8. If this constraint is violated, using\nthe original String after dropping the &mut Vec may violate memory\nsafety, as the rest of the standard library assumes that Strings are\nvalid UTF-8.
let mut s = String::from(\"hello\");\n\nunsafe {\n let vec = s.as_mut_vec();\n assert_eq!(&[104, 101, 108, 108, 111][..], &vec[..]);\n\n vec.reverse();\n}\nassert_eq!(s, \"olleh\");Returns the length of this String, in bytes, not chars or\ngraphemes. In other words, it might not be what a human considers the\nlength of the string.
let a = String::from(\"foo\");\nassert_eq!(a.len(), 3);\n\nlet fancy_f = String::from(\"ƒoo\");\nassert_eq!(fancy_f.len(), 4);\nassert_eq!(fancy_f.chars().count(), 3);Returns true if this String has a length of zero, and false otherwise.
let mut v = String::new();\nassert!(v.is_empty());\n\nv.push('a');\nassert!(!v.is_empty());Splits the string into two at the given byte index.
\nReturns a newly allocated String. self contains bytes [0, at), and\nthe returned String contains bytes [at, len). at must be on the\nboundary of a UTF-8 code point.
Note that the capacity of self does not change.
Panics if at is not on a UTF-8 code point boundary, or if it is beyond the last\ncode point of the string.
let mut hello = String::from(\"Hello, World!\");\nlet world = hello.split_off(7);\nassert_eq!(hello, \"Hello, \");\nassert_eq!(world, \"World!\");Truncates this String, removing all contents.
While this means the String will have a length of zero, it does not\ntouch its capacity.
let mut s = String::from(\"foo\");\n\ns.clear();\n\nassert!(s.is_empty());\nassert_eq!(0, s.len());\nassert_eq!(3, s.capacity());Removes the specified range from the string in bulk, returning all\nremoved characters as an iterator.
\nThe returned iterator keeps a mutable borrow on the string to optimize\nits implementation.
\nPanics if the starting point or end point do not lie on a char\nboundary, or if they’re out of bounds.
If the returned iterator goes out of scope without being dropped (due to\ncore::mem::forget, for example), the string may still contain a copy\nof any drained characters, or may have lost characters arbitrarily,\nincluding characters outside the range.
let mut s = String::from(\"α is alpha, β is beta\");\nlet beta_offset = s.find('β').unwrap_or(s.len());\n\n// Remove the range up until the β from the string\nlet t: String = s.drain(..beta_offset).collect();\nassert_eq!(t, \"α is alpha, \");\nassert_eq!(s, \"β is beta\");\n\n// A full range clears the string, like `clear()` does\ns.drain(..);\nassert_eq!(s, \"\");Removes the specified range in the string,\nand replaces it with the given string.\nThe given string doesn’t need to be the same length as the range.
\nPanics if the starting point or end point do not lie on a char\nboundary, or if they’re out of bounds.
let mut s = String::from(\"α is alpha, β is beta\");\nlet beta_offset = s.find('β').unwrap_or(s.len());\n\n// Replace the range up until the β from the string\ns.replace_range(..beta_offset, \"Α is capital alpha; \");\nassert_eq!(s, \"Α is capital alpha; β is beta\");Converts this String into a Box<str>.
Before doing the conversion, this method discards excess capacity like shrink_to_fit.\nNote that this call may reallocate and copy the bytes of the string.
let s = String::from(\"hello\");\n\nlet b = s.into_boxed_str();Consumes and leaks the String, returning a mutable reference to the contents,\n&'a mut str.
The caller has free choice over the returned lifetime, including 'static. Indeed,\nthis function is ideally used for data that lives for the remainder of the program’s life,\nas dropping the returned reference will cause a memory leak.
It does not reallocate or shrink the String, so the leaked allocation may include unused\ncapacity that is not part of the returned slice. If you want to discard excess capacity,\ncall into_boxed_str, and then Box::leak instead. However, keep in mind that\ntrimming the capacity may result in a reallocation and copy.
let x = String::from(\"bucket\");\nlet static_ref: &'static mut str = x.leak();\nassert_eq!(static_ref, \"bucket\");Vec<u8>.to_vec, but uses provided values without changes.\nThis can generate an invalid encoding for a DER object.to_der, but uses provided values without changes.\nThis can generate an invalid encoding for a DER object.SocketAddrs. Read moreSelf from the given unstructured data. Read moreUnstructured this type\nneeds to construct itself. Read moreSelf from the entirety of the given\nunstructured data. Read moreConstructs an Arc<T> from a raw pointer.
The raw pointer must have been previously returned by a call to\nArc<U>::into_raw with the following requirements:
U is sized, it must have the same size and alignment as T. This\nis trivially true if U is T.U is unsized, its data pointer must have the same size and\nalignment as T. This is trivially true if Arc<U> was constructed\nthrough Arc<T> and then converted to Arc<U> through an unsized\ncoercion.Note that if U or U’s data pointer is not T but has the same size\nand alignment, this is basically like transmuting references of\ndifferent types. See mem::transmute for more information\non what restrictions apply in this case.
The user of from_raw has to make sure a specific value of T is only\ndropped once.
This function is unsafe because improper use may lead to memory unsafety,\neven if the returned Arc<T> is never accessed.
use std::sync::Arc;\n\nlet x = Arc::new(\"hello\".to_owned());\nlet x_ptr = Arc::into_raw(x);\n\nunsafe {\n // Convert back to an `Arc` to prevent leak.\n let x = Arc::from_raw(x_ptr);\n assert_eq!(&*x, \"hello\");\n\n // Further calls to `Arc::from_raw(x_ptr)` would be memory-unsafe.\n}\n\n// The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling!Convert a slice back into its original array:
\n\nuse std::sync::Arc;\n\nlet x: Arc<[u32]> = Arc::new([1, 2, 3]);\nlet x_ptr: *const [u32] = Arc::into_raw(x);\n\nunsafe {\n let x: Arc<[u32; 3]> = Arc::from_raw(x_ptr.cast::<[u32; 3]>());\n assert_eq!(&*x, &[1, 2, 3]);\n}Increments the strong reference count on the Arc<T> associated with the\nprovided pointer by one.
The pointer must have been obtained through Arc::into_raw, and the\nassociated Arc instance must be valid (i.e. the strong count must be at\nleast 1) for the duration of this method.
use std::sync::Arc;\n\nlet five = Arc::new(5);\n\nunsafe {\n let ptr = Arc::into_raw(five);\n Arc::increment_strong_count(ptr);\n\n // This assertion is deterministic because we haven't shared\n // the `Arc` between threads.\n let five = Arc::from_raw(ptr);\n assert_eq!(2, Arc::strong_count(&five));\n}Decrements the strong reference count on the Arc<T> associated with the\nprovided pointer by one.
The pointer must have been obtained through Arc::into_raw, and the\nassociated Arc instance must be valid (i.e. the strong count must be at\nleast 1) when invoking this method. This method can be used to release the final\nArc and backing storage, but should not be called after the final Arc has been\nreleased.
use std::sync::Arc;\n\nlet five = Arc::new(5);\n\nunsafe {\n let ptr = Arc::into_raw(five);\n Arc::increment_strong_count(ptr);\n\n // Those assertions are deterministic because we haven't shared\n // the `Arc` between threads.\n let five = Arc::from_raw(ptr);\n assert_eq!(2, Arc::strong_count(&five));\n Arc::decrement_strong_count(ptr);\n assert_eq!(1, Arc::strong_count(&five));\n}Constructs a new Arc<T> while giving you a Weak<T> to the allocation,\nto allow you to construct a T which holds a weak pointer to itself.
Generally, a structure circularly referencing itself, either directly or\nindirectly, should not hold a strong reference to itself to prevent a memory leak.\nUsing this function, you get access to the weak pointer during the\ninitialization of T, before the Arc<T> is created, such that you can\nclone and store it inside the T.
new_cyclic first allocates the managed allocation for the Arc<T>,\nthen calls your closure, giving it a Weak<T> to this allocation,\nand only afterwards completes the construction of the Arc<T> by placing\nthe T returned from your closure into the allocation.
Since the new Arc<T> is not fully-constructed until Arc<T>::new_cyclic\nreturns, calling upgrade on the weak reference inside your closure will\nfail and result in a None value.
If data_fn panics, the panic is propagated to the caller, and the\ntemporary Weak<T> is dropped normally.
use std::sync::{Arc, Weak};\n\nstruct Gadget {\n me: Weak<Gadget>,\n}\n\nimpl Gadget {\n /// Construct a reference counted Gadget.\n fn new() -> Arc<Self> {\n // `me` is a `Weak<Gadget>` pointing at the new allocation of the\n // `Arc` we're constructing.\n Arc::new_cyclic(|me| {\n // Create the actual struct here.\n Gadget { me: me.clone() }\n })\n }\n\n /// Return a reference counted pointer to Self.\n fn me(&self) -> Arc<Self> {\n self.me.upgrade().unwrap()\n }\n}new_uninit)Constructs a new Arc with uninitialized contents.
#![feature(new_uninit)]\n#![feature(get_mut_unchecked)]\n\nuse std::sync::Arc;\n\nlet mut five = Arc::<u32>::new_uninit();\n\n// Deferred initialization:\nArc::get_mut(&mut five).unwrap().write(5);\n\nlet five = unsafe { five.assume_init() };\n\nassert_eq!(*five, 5)new_uninit)Constructs a new Arc with uninitialized contents, with the memory\nbeing filled with 0 bytes.
See MaybeUninit::zeroed for examples of correct and incorrect usage\nof this method.
#![feature(new_uninit)]\n\nuse std::sync::Arc;\n\nlet zero = Arc::<u32>::new_zeroed();\nlet zero = unsafe { zero.assume_init() };\n\nassert_eq!(*zero, 0)Constructs a new Pin<Arc<T>>. If T does not implement Unpin, then\ndata will be pinned in memory and unable to be moved.
allocator_api)Constructs a new Pin<Arc<T>>, return an error if allocation fails.
allocator_api)Constructs a new Arc<T>, returning an error if allocation fails.
#![feature(allocator_api)]\nuse std::sync::Arc;\n\nlet five = Arc::try_new(5)?;allocator_api)Constructs a new Arc with uninitialized contents, returning an error\nif allocation fails.
#![feature(new_uninit, allocator_api)]\n#![feature(get_mut_unchecked)]\n\nuse std::sync::Arc;\n\nlet mut five = Arc::<u32>::try_new_uninit()?;\n\n// Deferred initialization:\nArc::get_mut(&mut five).unwrap().write(5);\n\nlet five = unsafe { five.assume_init() };\n\nassert_eq!(*five, 5);allocator_api)Constructs a new Arc with uninitialized contents, with the memory\nbeing filled with 0 bytes, returning an error if allocation fails.
See MaybeUninit::zeroed for examples of correct and incorrect usage\nof this method.
#![feature(new_uninit, allocator_api)]\n\nuse std::sync::Arc;\n\nlet zero = Arc::<u32>::try_new_zeroed()?;\nlet zero = unsafe { zero.assume_init() };\n\nassert_eq!(*zero, 0);Consumes the Arc, returning the wrapped pointer.
To avoid a memory leak the pointer must be converted back to an Arc using\nArc::from_raw.
use std::sync::Arc;\n\nlet x = Arc::new(\"hello\".to_owned());\nlet x_ptr = Arc::into_raw(x);\nassert_eq!(unsafe { &*x_ptr }, \"hello\");allocator_api)Consumes the Arc, returning the wrapped pointer and allocator.
To avoid a memory leak the pointer must be converted back to an Arc using\nArc::from_raw_in.
#![feature(allocator_api)]\nuse std::sync::Arc;\nuse std::alloc::System;\n\nlet x = Arc::new_in(\"hello\".to_owned(), System);\nlet (ptr, alloc) = Arc::into_raw_with_allocator(x);\nassert_eq!(unsafe { &*ptr }, \"hello\");\nlet x = unsafe { Arc::from_raw_in(ptr, alloc) };\nassert_eq!(&*x, \"hello\");Provides a raw pointer to the data.
\nThe counts are not affected in any way and the Arc is not consumed. The pointer is valid for\nas long as there are strong counts in the Arc.
use std::sync::Arc;\n\nlet x = Arc::new(\"hello\".to_owned());\nlet y = Arc::clone(&x);\nlet x_ptr = Arc::as_ptr(&x);\nassert_eq!(x_ptr, Arc::as_ptr(&y));\nassert_eq!(unsafe { &*x_ptr }, \"hello\");allocator_api)Constructs an Arc<T, A> from a raw pointer.
The raw pointer must have been previously returned by a call to Arc<U, A>::into_raw with the following requirements:
U is sized, it must have the same size and alignment as T. This\nis trivially true if U is T.U is unsized, its data pointer must have the same size and\nalignment as T. This is trivially true if Arc<U> was constructed\nthrough Arc<T> and then converted to Arc<U> through an unsized\ncoercion.Note that if U or U’s data pointer is not T but has the same size\nand alignment, this is basically like transmuting references of\ndifferent types. See mem::transmute for more information\non what restrictions apply in this case.
The raw pointer must point to a block of memory allocated by alloc
The user of from_raw has to make sure a specific value of T is only\ndropped once.
This function is unsafe because improper use may lead to memory unsafety,\neven if the returned Arc<T> is never accessed.
#![feature(allocator_api)]\n\nuse std::sync::Arc;\nuse std::alloc::System;\n\nlet x = Arc::new_in(\"hello\".to_owned(), System);\nlet x_ptr = Arc::into_raw(x);\n\nunsafe {\n // Convert back to an `Arc` to prevent leak.\n let x = Arc::from_raw_in(x_ptr, System);\n assert_eq!(&*x, \"hello\");\n\n // Further calls to `Arc::from_raw(x_ptr)` would be memory-unsafe.\n}\n\n// The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling!Convert a slice back into its original array:
\n\n#![feature(allocator_api)]\n\nuse std::sync::Arc;\nuse std::alloc::System;\n\nlet x: Arc<[u32], _> = Arc::new_in([1, 2, 3], System);\nlet x_ptr: *const [u32] = Arc::into_raw(x);\n\nunsafe {\n let x: Arc<[u32; 3], _> = Arc::from_raw_in(x_ptr.cast::<[u32; 3]>(), System);\n assert_eq!(&*x, &[1, 2, 3]);\n}Gets the number of Weak pointers to this allocation.
This method by itself is safe, but using it correctly requires extra care.\nAnother thread can change the weak count at any time,\nincluding potentially between calling this method and acting on the result.
\nuse std::sync::Arc;\n\nlet five = Arc::new(5);\nlet _weak_five = Arc::downgrade(&five);\n\n// This assertion is deterministic because we haven't shared\n// the `Arc` or `Weak` between threads.\nassert_eq!(1, Arc::weak_count(&five));Gets the number of strong (Arc) pointers to this allocation.
This method by itself is safe, but using it correctly requires extra care.\nAnother thread can change the strong count at any time,\nincluding potentially between calling this method and acting on the result.
\nuse std::sync::Arc;\n\nlet five = Arc::new(5);\nlet _also_five = Arc::clone(&five);\n\n// This assertion is deterministic because we haven't shared\n// the `Arc` between threads.\nassert_eq!(2, Arc::strong_count(&five));allocator_api)Increments the strong reference count on the Arc<T> associated with the\nprovided pointer by one.
The pointer must have been obtained through Arc::into_raw, and the\nassociated Arc instance must be valid (i.e. the strong count must be at\nleast 1) for the duration of this method,, and ptr must point to a block of memory\nallocated by alloc.
#![feature(allocator_api)]\n\nuse std::sync::Arc;\nuse std::alloc::System;\n\nlet five = Arc::new_in(5, System);\n\nunsafe {\n let ptr = Arc::into_raw(five);\n Arc::increment_strong_count_in(ptr, System);\n\n // This assertion is deterministic because we haven't shared\n // the `Arc` between threads.\n let five = Arc::from_raw_in(ptr, System);\n assert_eq!(2, Arc::strong_count(&five));\n}allocator_api)Decrements the strong reference count on the Arc<T> associated with the\nprovided pointer by one.
The pointer must have been obtained through Arc::into_raw, the\nassociated Arc instance must be valid (i.e. the strong count must be at\nleast 1) when invoking this method, and ptr must point to a block of memory\nallocated by alloc. This method can be used to release the final\nArc and backing storage, but should not be called after the final Arc has been\nreleased.
#![feature(allocator_api)]\n\nuse std::sync::Arc;\nuse std::alloc::System;\n\nlet five = Arc::new_in(5, System);\n\nunsafe {\n let ptr = Arc::into_raw(five);\n Arc::increment_strong_count_in(ptr, System);\n\n // Those assertions are deterministic because we haven't shared\n // the `Arc` between threads.\n let five = Arc::from_raw_in(ptr, System);\n assert_eq!(2, Arc::strong_count(&five));\n Arc::decrement_strong_count_in(ptr, System);\n assert_eq!(1, Arc::strong_count(&five));\n}Returns true if the two Arcs point to the same allocation in a vein similar to\nptr::eq. This function ignores the metadata of dyn Trait pointers.
use std::sync::Arc;\n\nlet five = Arc::new(5);\nlet same_five = Arc::clone(&five);\nlet other_five = Arc::new(5);\n\nassert!(Arc::ptr_eq(&five, &same_five));\nassert!(!Arc::ptr_eq(&five, &other_five));Makes a mutable reference into the given Arc.
If there are other Arc pointers to the same allocation, then make_mut will\nclone the inner value to a new allocation to ensure unique ownership. This is also\nreferred to as clone-on-write.
However, if there are no other Arc pointers to this allocation, but some Weak\npointers, then the Weak pointers will be dissociated and the inner value will not\nbe cloned.
See also get_mut, which will fail rather than cloning the inner value\nor dissociating Weak pointers.
use std::sync::Arc;\n\nlet mut data = Arc::new(5);\n\n*Arc::make_mut(&mut data) += 1; // Won't clone anything\nlet mut other_data = Arc::clone(&data); // Won't clone inner data\n*Arc::make_mut(&mut data) += 1; // Clones inner data\n*Arc::make_mut(&mut data) += 1; // Won't clone anything\n*Arc::make_mut(&mut other_data) *= 2; // Won't clone anything\n\n// Now `data` and `other_data` point to different allocations.\nassert_eq!(*data, 8);\nassert_eq!(*other_data, 12);Weak pointers will be dissociated:
use std::sync::Arc;\n\nlet mut data = Arc::new(75);\nlet weak = Arc::downgrade(&data);\n\nassert!(75 == *data);\nassert!(75 == *weak.upgrade().unwrap());\n\n*Arc::make_mut(&mut data) += 1;\n\nassert!(76 == *data);\nassert!(weak.upgrade().is_none());If we have the only reference to T then unwrap it. Otherwise, clone T and return the\nclone.
Assuming arc_t is of type Arc<T>, this function is functionally equivalent to\n(*arc_t).clone(), but will avoid cloning the inner value where possible.
let inner = String::from(\"test\");\nlet ptr = inner.as_ptr();\n\nlet arc = Arc::new(inner);\nlet inner = Arc::unwrap_or_clone(arc);\n// The inner value was not cloned\nassert!(ptr::eq(ptr, inner.as_ptr()));\n\nlet arc = Arc::new(inner);\nlet arc2 = arc.clone();\nlet inner = Arc::unwrap_or_clone(arc);\n// Because there were 2 references, we had to clone the inner value.\nassert!(!ptr::eq(ptr, inner.as_ptr()));\n// `arc2` is the last reference, so when we unwrap it we get back\n// the original `String`.\nlet inner = Arc::unwrap_or_clone(arc2);\nassert!(ptr::eq(ptr, inner.as_ptr()));Returns a mutable reference into the given Arc, if there are\nno other Arc or Weak pointers to the same allocation.
Returns None otherwise, because it is not safe to\nmutate a shared value.
See also make_mut, which will clone\nthe inner value when there are other Arc pointers.
use std::sync::Arc;\n\nlet mut x = Arc::new(3);\n*Arc::get_mut(&mut x).unwrap() = 4;\nassert_eq!(*x, 4);\n\nlet _y = Arc::clone(&x);\nassert!(Arc::get_mut(&mut x).is_none());get_mut_unchecked)Returns a mutable reference into the given Arc,\nwithout any check.
See also get_mut, which is safe and does appropriate checks.
If any other Arc or Weak pointers to the same allocation exist, then\nthey must not be dereferenced or have active borrows for the duration\nof the returned borrow, and their inner type must be exactly the same as the\ninner type of this Rc (including lifetimes). This is trivially the case if no\nsuch pointers exist, for example immediately after Arc::new.
#![feature(get_mut_unchecked)]\n\nuse std::sync::Arc;\n\nlet mut x = Arc::new(String::new());\nunsafe {\n Arc::get_mut_unchecked(&mut x).push_str(\"foo\")\n}\nassert_eq!(*x, \"foo\");Other Arc pointers to the same allocation must be to the same type.
#![feature(get_mut_unchecked)]\n\nuse std::sync::Arc;\n\nlet x: Arc<str> = Arc::from(\"Hello, world!\");\nlet mut y: Arc<[u8]> = x.clone().into();\nunsafe {\n // this is Undefined Behavior, because x's inner type is str, not [u8]\n Arc::get_mut_unchecked(&mut y).fill(0xff); // 0xff is invalid in UTF-8\n}\nprintln!(\"{}\", &*x); // Invalid UTF-8 in a strOther Arc pointers to the same allocation must be to the exact same type, including lifetimes.
#![feature(get_mut_unchecked)]\n\nuse std::sync::Arc;\n\nlet x: Arc<&str> = Arc::new(\"Hello, world!\");\n{\n let s = String::from(\"Oh, no!\");\n let mut y: Arc<&str> = x.clone().into();\n unsafe {\n // this is Undefined Behavior, because x's inner type\n // is &'long str, not &'short str\n *Arc::get_mut_unchecked(&mut y) = &s;\n }\n}\nprintln!(\"{}\", &*x); // Use-after-freeallocator_api)Returns a reference to the underlying allocator.
\nNote: this is an associated function, which means that you have\nto call it as Arc::allocator(&a) instead of a.allocator(). This\nis so that there is no conflict with a method on the inner type.
allocator_api)Constructs a new Arc<T> in the provided allocator.
#![feature(allocator_api)]\n\nuse std::sync::Arc;\nuse std::alloc::System;\n\nlet five = Arc::new_in(5, System);allocator_api)Constructs a new Arc with uninitialized contents in the provided allocator.
#![feature(new_uninit)]\n#![feature(get_mut_unchecked)]\n#![feature(allocator_api)]\n\nuse std::sync::Arc;\nuse std::alloc::System;\n\nlet mut five = Arc::<u32, _>::new_uninit_in(System);\n\nlet five = unsafe {\n // Deferred initialization:\n Arc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);\n\n five.assume_init()\n};\n\nassert_eq!(*five, 5)allocator_api)Constructs a new Arc with uninitialized contents, with the memory\nbeing filled with 0 bytes, in the provided allocator.
See MaybeUninit::zeroed for examples of correct and incorrect usage\nof this method.
#![feature(new_uninit)]\n#![feature(allocator_api)]\n\nuse std::sync::Arc;\nuse std::alloc::System;\n\nlet zero = Arc::<u32, _>::new_zeroed_in(System);\nlet zero = unsafe { zero.assume_init() };\n\nassert_eq!(*zero, 0)allocator_api)Constructs a new Pin<Arc<T, A>> in the provided allocator. If T does not implement Unpin,\nthen data will be pinned in memory and unable to be moved.
allocator_api)Constructs a new Pin<Arc<T, A>> in the provided allocator, return an error if allocation\nfails.
allocator_api)Constructs a new Arc<T, A> in the provided allocator, returning an error if allocation fails.
#![feature(allocator_api)]\n\nuse std::sync::Arc;\nuse std::alloc::System;\n\nlet five = Arc::try_new_in(5, System)?;allocator_api)Constructs a new Arc with uninitialized contents, in the provided allocator, returning an\nerror if allocation fails.
#![feature(new_uninit, allocator_api)]\n#![feature(get_mut_unchecked)]\n\nuse std::sync::Arc;\nuse std::alloc::System;\n\nlet mut five = Arc::<u32, _>::try_new_uninit_in(System)?;\n\nlet five = unsafe {\n // Deferred initialization:\n Arc::get_mut_unchecked(&mut five).as_mut_ptr().write(5);\n\n five.assume_init()\n};\n\nassert_eq!(*five, 5);allocator_api)Constructs a new Arc with uninitialized contents, with the memory\nbeing filled with 0 bytes, in the provided allocator, returning an error if allocation\nfails.
See MaybeUninit::zeroed for examples of correct and incorrect usage\nof this method.
#![feature(new_uninit, allocator_api)]\n\nuse std::sync::Arc;\nuse std::alloc::System;\n\nlet zero = Arc::<u32, _>::try_new_zeroed_in(System)?;\nlet zero = unsafe { zero.assume_init() };\n\nassert_eq!(*zero, 0);Returns the inner value, if the Arc has exactly one strong reference.
Otherwise, an Err is returned with the same Arc that was\npassed in.
This will succeed even if there are outstanding weak references.
\nIt is strongly recommended to use Arc::into_inner instead if you don’t\nkeep the Arc in the Err case.\nImmediately dropping the Err-value, as the expression\nArc::try_unwrap(this).ok() does, can cause the strong count to\ndrop to zero and the inner value of the Arc to be dropped.\nFor instance, if two threads execute such an expression in parallel,\nthere is a race condition without the possibility of unsafety:\nThe threads could first both check whether they own the last instance\nin Arc::try_unwrap, determine that they both do not, and then both\ndiscard and drop their instance in the call to ok.\nIn this scenario, the value inside the Arc is safely destroyed\nby exactly one of the threads, but neither thread will ever be able\nto use the value.
use std::sync::Arc;\n\nlet x = Arc::new(3);\nassert_eq!(Arc::try_unwrap(x), Ok(3));\n\nlet x = Arc::new(4);\nlet _y = Arc::clone(&x);\nassert_eq!(*Arc::try_unwrap(x).unwrap_err(), 4);Returns the inner value, if the Arc has exactly one strong reference.
Otherwise, None is returned and the Arc is dropped.
This will succeed even if there are outstanding weak references.
\nIf Arc::into_inner is called on every clone of this Arc,\nit is guaranteed that exactly one of the calls returns the inner value.\nThis means in particular that the inner value is not dropped.
Arc::try_unwrap is conceptually similar to Arc::into_inner, but it\nis meant for different use-cases. If used as a direct replacement\nfor Arc::into_inner anyway, such as with the expression\nArc::try_unwrap(this).ok(), then it does\nnot give the same guarantee as described in the previous paragraph.\nFor more information, see the examples below and read the documentation\nof Arc::try_unwrap.
Minimal example demonstrating the guarantee that Arc::into_inner gives.
use std::sync::Arc;\n\nlet x = Arc::new(3);\nlet y = Arc::clone(&x);\n\n// Two threads calling `Arc::into_inner` on both clones of an `Arc`:\nlet x_thread = std::thread::spawn(|| Arc::into_inner(x));\nlet y_thread = std::thread::spawn(|| Arc::into_inner(y));\n\nlet x_inner_value = x_thread.join().unwrap();\nlet y_inner_value = y_thread.join().unwrap();\n\n// One of the threads is guaranteed to receive the inner value:\nassert!(matches!(\n (x_inner_value, y_inner_value),\n (None, Some(3)) | (Some(3), None)\n));\n// The result could also be `(None, None)` if the threads called\n// `Arc::try_unwrap(x).ok()` and `Arc::try_unwrap(y).ok()` instead.A more practical example demonstrating the need for Arc::into_inner:
use std::sync::Arc;\n\n// Definition of a simple singly linked list using `Arc`:\n#[derive(Clone)]\nstruct LinkedList<T>(Option<Arc<Node<T>>>);\nstruct Node<T>(T, Option<Arc<Node<T>>>);\n\n// Dropping a long `LinkedList<T>` relying on the destructor of `Arc`\n// can cause a stack overflow. To prevent this, we can provide a\n// manual `Drop` implementation that does the destruction in a loop:\nimpl<T> Drop for LinkedList<T> {\n fn drop(&mut self) {\n let mut link = self.0.take();\n while let Some(arc_node) = link.take() {\n if let Some(Node(_value, next)) = Arc::into_inner(arc_node) {\n link = next;\n }\n }\n }\n}\n\n// Implementation of `new` and `push` omitted\nimpl<T> LinkedList<T> {\n /* ... */\n}\n\n// The following code could have still caused a stack overflow\n// despite the manual `Drop` impl if that `Drop` impl had used\n// `Arc::try_unwrap(arc).ok()` instead of `Arc::into_inner(arc)`.\n\n// Create a long list and clone it\nlet mut x = LinkedList::new();\nlet size = 100000;\nfor i in 0..size {\n x.push(i); // Adds i to the front of x\n}\nlet y = x.clone();\n\n// Drop the clones in parallel\nlet x_thread = std::thread::spawn(|| drop(x));\nlet y_thread = std::thread::spawn(|| drop(y));\nx_thread.join().unwrap();\ny_thread.join().unwrap();This impl allows implementing traits that require AsFd on Arc.
use std::net::UdpSocket;\nuse std::sync::Arc;\n\ntrait MyTrait: AsFd {}\nimpl MyTrait for Arc<UdpSocket> {}\nimpl MyTrait for Box<UdpSocket> {}This impl allows implementing traits that require AsRawFd on Arc.
use std::net::UdpSocket;\nuse std::sync::Arc;\ntrait MyTrait: AsRawFd {\n}\nimpl MyTrait for Arc<UdpSocket> {}\nimpl MyTrait for Box<UdpSocket> {}Makes a clone of the Arc pointer.
This creates another pointer to the same allocation, increasing the\nstrong reference count.
\nuse std::sync::Arc;\n\nlet five = Arc::new(5);\n\nlet _ = Arc::clone(&five);source. Read moreRecord) Read moreis_enabledis_enabledis_enabledis_enabledis_enabledis_enabledDrain Read moreDrain (by level) Read moreDrops the Arc.
This will decrement the strong reference count. If the strong reference\ncount reaches zero then the only other references (if any) are\nWeak, so we drop the inner value.
use std::sync::Arc;\n\nstruct Foo;\n\nimpl Drop for Foo {\n fn drop(&mut self) {\n println!(\"dropped!\");\n }\n}\n\nlet foo = Arc::new(Foo);\nlet foo2 = Arc::clone(&foo);\n\ndrop(foo); // Doesn't print anything\ndrop(foo2); // Prints \"dropped!\"Comparison for two Arcs.
The two are compared by calling cmp() on their inner values.
use std::sync::Arc;\nuse std::cmp::Ordering;\n\nlet five = Arc::new(5);\n\nassert_eq!(Ordering::Less, five.cmp(&Arc::new(6)));Equality for two Arcs.
Two Arcs are equal if their inner values are equal, even if they are\nstored in different allocation.
If T also implements Eq (implying reflexivity of equality),\ntwo Arcs that point to the same allocation are always equal.
use std::sync::Arc;\n\nlet five = Arc::new(5);\n\nassert!(five == Arc::new(5));Inequality for two Arcs.
Two Arcs are not equal if their inner values are not equal.
If T also implements Eq (implying reflexivity of equality),\ntwo Arcs that point to the same value are always equal.
use std::sync::Arc;\n\nlet five = Arc::new(5);\n\nassert!(five != Arc::new(6));Partial comparison for two Arcs.
The two are compared by calling partial_cmp() on their inner values.
use std::sync::Arc;\nuse std::cmp::Ordering;\n\nlet five = Arc::new(5);\n\nassert_eq!(Some(Ordering::Less), five.partial_cmp(&Arc::new(6)));Less-than comparison for two Arcs.
The two are compared by calling < on their inner values.
use std::sync::Arc;\n\nlet five = Arc::new(5);\n\nassert!(five < Arc::new(6));‘Less than or equal to’ comparison for two Arcs.
The two are compared by calling <= on their inner values.
use std::sync::Arc;\n\nlet five = Arc::new(5);\n\nassert!(five <= Arc::new(5));Self from the given unstructured data. Read moreSelf from the entirety of the given\nunstructured data. Read morebuf into the object. Read morebufs into the object using vectored\nIO operations. Read morebuf into the object. Read morepoll_write, except that it writes from a slice of buffers. Read morepoll_write_vectored\nimplementation. Read moreBufMut::remaining_mut(). Note that this can be shorter than the\nwhole remainder of the buffer (this allows non-continuous implementation). Read moreself for more bytes. Read moreself in big-endian byte order. Read moreself in little-endian byte order. Read moreself in native-endian byte order. Read moreself in big-endian byte order. Read moreself in little-endian byte order. Read moreself in native-endian byte order. Read moreself in big-endian byte order. Read moreself in little-endian byte order. Read moreself in native-endian byte order. Read moreself in big-endian byte order. Read moreself in little-endian byte order. Read moreself in native-endian byte order. Read moreself in the big-endian byte order. Read moreself in little-endian byte order. Read moreself in native-endian byte order. Read moreself in the big-endian byte order. Read moreself in little-endian byte order. Read moreself in native-endian byte order. Read moreself in the big-endian byte order. Read moreself in little-endian byte order. Read moreself in native-endian byte order. Read moreself in the big-endian byte order. Read moreself in little-endian byte order. Read moreself in native-endian byte order. Read moreself in big-endian byte order. Read moreself in the little-endian byte order. Read moreself in the native-endian byte order. Read moreself in big-endian byte order. Read moreself in little-endian byte order. Read moreself in native-endian byte order. Read moreself in big-endian byte order. Read moreself in little-endian byte order. Read moreself in native-endian byte order. Read moreOverwrites the contents of self with a clone of the contents of source.
This method is preferred over simply assigning source.clone() to self,\nas it avoids reallocation if possible. Additionally, if the element type\nT overrides clone_from(), this will reuse the resources of self’s\nelements as well.
let x = vec![5, 6, 7];\nlet mut y = vec![8, 9, 10];\nlet yp: *const i32 = y.as_ptr();\n\ny.clone_from(&x);\n\n// The value is the same\nassert_eq!(x, y);\n\n// And no reallocation occurred\nassert_eq!(yp, y.as_ptr());try_default in case the value is null or\nundefined.try_default in case the value is null or\nundefined.Reader].Extend implementation that copies elements out of references before pushing them onto the Vec.
\nThis implementation is specialized for slice iterators, where it uses copy_from_slice to\nappend the entire slice at once.
extend_one)extend_one)extend_one)extend_one)Converts a BinaryHeap<T> into a Vec<T>.
This conversion requires no data movement or allocation, and has\nconstant time complexity.
\nConvert a clone-on-write slice into a vector.
\nIf s already owns a Vec<T>, it will be returned directly.\nIf s is borrowing a slice, a new Vec<T> will be allocated and\nfilled by cloning s’s items into it.
let o: Cow<'_, [i32]> = Cow::Owned(vec![1, 2, 3]);\nlet b: Cow<'_, [i32]> = Cow::Borrowed(&[1, 2, 3]);\nassert_eq!(Vec::from(o), Vec::from(b));Turn a VecDeque<T> into a Vec<T>.
This never needs to re-allocate, but does need to do O(n) data movement if\nthe circular buffer doesn’t happen to be at the beginning of the allocation.
\nuse std::collections::VecDeque;\n\n// This one is *O*(1).\nlet deque: VecDeque<_> = (1..5).collect();\nlet ptr = deque.as_slices().0.as_ptr();\nlet vec = Vec::from(deque);\nassert_eq!(vec, [1, 2, 3, 4]);\nassert_eq!(vec.as_ptr(), ptr);\n\n// This one needs data rearranging.\nlet mut deque: VecDeque<_> = (1..5).collect();\ndeque.push_front(9);\ndeque.push_front(8);\nlet ptr = deque.as_slices().1.as_ptr();\nlet vec = Vec::from(deque);\nassert_eq!(vec, [8, 9, 1, 2, 3, 4]);\nassert_eq!(vec.as_ptr(), ptr);manual impl of FromDer, so we do not need to require TryFrom<Any> + CheckDerConstraints
Collects an iterator into a Vec, commonly called via Iterator::collect()
In general Vec does not guarantee any particular growth or allocation strategy.\nThat also applies to this trait impl.
Note: This section covers implementation details and is therefore exempt from\nstability guarantees.
\nVec may use any or none of the following strategies,\ndepending on the supplied iterator:
\nIterator::size_hint()\npushing one item at a timeThe last case warrants some attention. It is an optimization that in many cases reduces peak memory\nconsumption and improves cache locality. But when big, short-lived allocations are created,\nonly a small fraction of their items get collected, no further use is made of the spare capacity\nand the resulting Vec is moved into a longer-lived structure, then this can lead to the large\nallocations having their lifetimes unnecessarily extended which can result in increased memory\nfootprint.
In cases where this is an issue, the excess capacity can be discarded with Vec::shrink_to(),\nVec::shrink_to_fit() or by collecting into Box<[T]> instead, which additionally reduces\nthe size of the long-lived struct.
static LONG_LIVED: Mutex<Vec<Vec<u16>>> = Mutex::new(Vec::new());\n\nfor i in 0..10 {\n let big_temporary: Vec<u16> = (0..1024).collect();\n // discard most items\n let mut result: Vec<_> = big_temporary.into_iter().filter(|i| i % 100 == 0).collect();\n // without this a lot of unused capacity might be moved into the global\n result.shrink_to_fit();\n LONG_LIVED.lock().unwrap().push(result);\n}The hash of a vector is the same as that of the corresponding slice,\nas required by the core::borrow::Borrow implementation.
use std::hash::BuildHasher;\n\nlet b = std::hash::RandomState::new();\nlet v: Vec<u8> = vec![0xa8, 0x3c, 0x09];\nlet s: &[u8] = &[0xa8, 0x3c, 0x09];\nassert_eq!(b.hash_one(v), b.hash_one(s));Creates a consuming iterator, that is, one that moves each value out of\nthe vector (from start to end). The vector cannot be used after calling\nthis.
\nlet v = vec![\"a\".to_string(), \"b\".to_string()];\nlet mut v_iter = v.into_iter();\n\nlet first_element: Option<String> = v_iter.next();\n\nassert_eq!(first_element, Some(\"a\".to_string()));\nassert_eq!(v_iter.next(), Some(\"b\".to_string()));\nassert_eq!(v_iter.next(), None);google.protobuf.BytesValue
self. Read moreself.Implements ordering of vectors, lexicographically.
\nself and other) and is used by the <=\noperator. Read moreself and other) and is used by the <=\noperator. Read moreImplements comparison of vectors, lexicographically.
\nself and other) and is used by the <=\noperator. Read moreSink to receive a value. Read morepoll_ready which returned Poll::Ready(Ok(())). Read moreVec<u8>.to_vec, but uses provided values without changes.\nThis can generate an invalid encoding for a DER object.to_der, but uses provided values without changes.\nThis can generate an invalid encoding for a DER object.Constructs a new, empty Vec<T>.
The vector will not allocate until elements are pushed onto it.
\nlet mut vec: Vec<i32> = Vec::new();Constructs a new, empty Vec<T> with at least the specified capacity.
The vector will be able to hold at least capacity elements without\nreallocating. This method is allowed to allocate for more elements than\ncapacity. If capacity is 0, the vector will not allocate.
It is important to note that although the returned vector has the\nminimum capacity specified, the vector will have a zero length. For\nan explanation of the difference between length and capacity, see\nCapacity and reallocation.
\nIf it is important to know the exact allocated capacity of a Vec,\nalways use the capacity method after construction.
For Vec<T> where T is a zero-sized type, there will be no allocation\nand the capacity will always be usize::MAX.
Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = Vec::with_capacity(10);\n\n// The vector contains no items, even though it has capacity for more\nassert_eq!(vec.len(), 0);\nassert!(vec.capacity() >= 10);\n\n// These are all done without reallocating...\nfor i in 0..10 {\n vec.push(i);\n}\nassert_eq!(vec.len(), 10);\nassert!(vec.capacity() >= 10);\n\n// ...but this may make the vector reallocate\nvec.push(11);\nassert_eq!(vec.len(), 11);\nassert!(vec.capacity() >= 11);\n\n// A vector of a zero-sized type will always over-allocate, since no\n// allocation is necessary\nlet vec_units = Vec::<()>::with_capacity(10);\nassert_eq!(vec_units.capacity(), usize::MAX);try_with_capacity)Constructs a new, empty Vec<T> with at least the specified capacity.
The vector will be able to hold at least capacity elements without\nreallocating. This method is allowed to allocate for more elements than\ncapacity. If capacity is 0, the vector will not allocate.
Returns an error if the capacity exceeds isize::MAX bytes,\nor if the allocator reports allocation failure.
Creates a Vec<T> directly from a pointer, a length, and a capacity.
This is highly unsafe, due to the number of invariants that aren’t\nchecked:
\nptr must have been allocated using the global allocator, such as via\nthe alloc::alloc function.T needs to have the same alignment as what ptr was allocated with.\n(T having a less strict alignment is not sufficient, the alignment really\nneeds to be equal to satisfy the dealloc requirement that memory must be\nallocated and deallocated with the same layout.)T times the capacity (ie. the allocated size in bytes) needs\nto be the same size as the pointer was allocated with. (Because similar to\nalignment, dealloc must be called with the same layout size.)length needs to be less than or equal to capacity.length values must be properly initialized values of type T.capacity needs to be the capacity that the pointer was allocated with.isize::MAX.\nSee the safety documentation of pointer::offset.These requirements are always upheld by any ptr that has been allocated\nvia Vec<T>. Other allocation sources are allowed if the invariants are\nupheld.
Violating these may cause problems like corrupting the allocator’s\ninternal data structures. For example it is normally not safe\nto build a Vec<u8> from a pointer to a C char array with length\nsize_t, doing so is only safe if the array was initially allocated by\na Vec or String.\nIt’s also not safe to build one from a Vec<u16> and its length, because\nthe allocator cares about the alignment, and these two types have different\nalignments. The buffer was allocated with alignment 2 (for u16), but after\nturning it into a Vec<u8> it’ll be deallocated with alignment 1. To avoid\nthese issues, it is often preferable to do casting/transmuting using\nslice::from_raw_parts instead.
The ownership of ptr is effectively transferred to the\nVec<T> which may then deallocate, reallocate or change the\ncontents of memory pointed to by the pointer at will. Ensure\nthat nothing else uses the pointer after calling this\nfunction.
use std::ptr;\nuse std::mem;\n\nlet v = vec![1, 2, 3];\n\n// Prevent running `v`'s destructor so we are in complete control\n// of the allocation.\nlet mut v = mem::ManuallyDrop::new(v);\n\n// Pull out the various important pieces of information about `v`\nlet p = v.as_mut_ptr();\nlet len = v.len();\nlet cap = v.capacity();\n\nunsafe {\n // Overwrite memory with 4, 5, 6\n for i in 0..len {\n ptr::write(p.add(i), 4 + i);\n }\n\n // Put everything back together into a Vec\n let rebuilt = Vec::from_raw_parts(p, len, cap);\n assert_eq!(rebuilt, [4, 5, 6]);\n}Using memory that was allocated elsewhere:
\n\nuse std::alloc::{alloc, Layout};\n\nfn main() {\n let layout = Layout::array::<u32>(16).expect(\"overflow cannot happen\");\n\n let vec = unsafe {\n let mem = alloc(layout).cast::<u32>();\n if mem.is_null() {\n return;\n }\n\n mem.write(1_000_000);\n\n Vec::from_raw_parts(mem, 1, 16)\n };\n\n assert_eq!(vec, &[1_000_000]);\n assert_eq!(vec.capacity(), 16);\n}Resizes the Vec in-place so that len is equal to new_len.
If new_len is greater than len, the Vec is extended by the\ndifference, with each additional slot filled with value.\nIf new_len is less than len, the Vec is simply truncated.
This method requires T to implement Clone,\nin order to be able to clone the passed value.\nIf you need more flexibility (or want to rely on Default instead of\nClone), use Vec::resize_with.\nIf you only need to resize to a smaller size, use Vec::truncate.
let mut vec = vec![\"hello\"];\nvec.resize(3, \"world\");\nassert_eq!(vec, [\"hello\", \"world\", \"world\"]);\n\nlet mut vec = vec![1, 2, 3, 4];\nvec.resize(2, 0);\nassert_eq!(vec, [1, 2]);Clones and appends all elements in a slice to the Vec.
Iterates over the slice other, clones each element, and then appends\nit to this Vec. The other slice is traversed in-order.
Note that this function is same as extend except that it is\nspecialized to work with slices instead. If and when Rust gets\nspecialization this function will likely be deprecated (but still\navailable).
let mut vec = vec![1];\nvec.extend_from_slice(&[2, 3, 4]);\nassert_eq!(vec, [1, 2, 3, 4]);Copies elements from src range to the end of the vector.
Panics if the starting point is greater than the end point or if\nthe end point is greater than the length of the vector.
\nlet mut vec = vec![0, 1, 2, 3, 4];\n\nvec.extend_from_within(2..);\nassert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4]);\n\nvec.extend_from_within(..2);\nassert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1]);\n\nvec.extend_from_within(4..8);\nassert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);Creates a splicing iterator that replaces the specified range in the vector\nwith the given replace_with iterator and yields the removed items.\nreplace_with does not need to be the same length as range.
range is removed even if the iterator is not consumed until the end.
It is unspecified how many elements are removed from the vector\nif the Splice value is leaked.
The input iterator replace_with is only consumed when the Splice value is dropped.
This is optimal if:
\nrange) is empty,replace_with yields fewer or equal elements than range’s lengthsize_hint() is exact.Otherwise, a temporary vector is allocated and the tail is moved twice.
\nPanics if the starting point is greater than the end point or if\nthe end point is greater than the length of the vector.
\nlet mut v = vec![1, 2, 3, 4];\nlet new = [7, 8, 9];\nlet u: Vec<_> = v.splice(1..3, new).collect();\nassert_eq!(v, &[1, 7, 8, 9, 4]);\nassert_eq!(u, &[2, 3]);extract_if)Creates an iterator which uses a closure to determine if an element should be removed.
\nIf the closure returns true, then the element is removed and yielded.\nIf the closure returns false, the element will remain in the vector and will not be yielded\nby the iterator.
\nIf the returned ExtractIf is not exhausted, e.g. because it is dropped without iterating\nor the iteration short-circuits, then the remaining elements will be retained.\nUse retain with a negated predicate if you do not need the returned iterator.
Using this method is equivalent to the following code:
\n\nlet mut i = 0;\nwhile i < vec.len() {\n if some_predicate(&mut vec[i]) {\n let val = vec.remove(i);\n // your code here\n } else {\n i += 1;\n }\n}\nBut extract_if is easier to use. extract_if is also more efficient,\nbecause it can backshift the elements of the array in bulk.
Note that extract_if also lets you mutate every element in the filter closure,\nregardless of whether you choose to keep or remove it.
Splitting an array into evens and odds, reusing the original allocation:
\n\n#![feature(extract_if)]\nlet mut numbers = vec![1, 2, 3, 4, 5, 6, 8, 9, 11, 13, 14, 15];\n\nlet evens = numbers.extract_if(|x| *x % 2 == 0).collect::<Vec<_>>();\nlet odds = numbers;\n\nassert_eq!(evens, vec![2, 4, 6, 8, 14]);\nassert_eq!(odds, vec![1, 3, 5, 9, 11, 13, 15]);allocator_api)Constructs a new, empty Vec<T, A>.
The vector will not allocate until elements are pushed onto it.
\n#![feature(allocator_api)]\n\nuse std::alloc::System;\n\nlet mut vec: Vec<i32, _> = Vec::new_in(System);allocator_api)Constructs a new, empty Vec<T, A> with at least the specified capacity\nwith the provided allocator.
The vector will be able to hold at least capacity elements without\nreallocating. This method is allowed to allocate for more elements than\ncapacity. If capacity is 0, the vector will not allocate.
It is important to note that although the returned vector has the\nminimum capacity specified, the vector will have a zero length. For\nan explanation of the difference between length and capacity, see\nCapacity and reallocation.
\nIf it is important to know the exact allocated capacity of a Vec,\nalways use the capacity method after construction.
For Vec<T, A> where T is a zero-sized type, there will be no allocation\nand the capacity will always be usize::MAX.
Panics if the new capacity exceeds isize::MAX bytes.
#![feature(allocator_api)]\n\nuse std::alloc::System;\n\nlet mut vec = Vec::with_capacity_in(10, System);\n\n// The vector contains no items, even though it has capacity for more\nassert_eq!(vec.len(), 0);\nassert!(vec.capacity() >= 10);\n\n// These are all done without reallocating...\nfor i in 0..10 {\n vec.push(i);\n}\nassert_eq!(vec.len(), 10);\nassert!(vec.capacity() >= 10);\n\n// ...but this may make the vector reallocate\nvec.push(11);\nassert_eq!(vec.len(), 11);\nassert!(vec.capacity() >= 11);\n\n// A vector of a zero-sized type will always over-allocate, since no\n// allocation is necessary\nlet vec_units = Vec::<(), System>::with_capacity_in(10, System);\nassert_eq!(vec_units.capacity(), usize::MAX);allocator_api)Constructs a new, empty Vec<T, A> with at least the specified capacity\nwith the provided allocator.
The vector will be able to hold at least capacity elements without\nreallocating. This method is allowed to allocate for more elements than\ncapacity. If capacity is 0, the vector will not allocate.
Returns an error if the capacity exceeds isize::MAX bytes,\nor if the allocator reports allocation failure.
allocator_api)Creates a Vec<T, A> directly from a pointer, a length, a capacity,\nand an allocator.
This is highly unsafe, due to the number of invariants that aren’t\nchecked:
\nptr must be currently allocated via the given allocator alloc.T needs to have the same alignment as what ptr was allocated with.\n(T having a less strict alignment is not sufficient, the alignment really\nneeds to be equal to satisfy the dealloc requirement that memory must be\nallocated and deallocated with the same layout.)T times the capacity (ie. the allocated size in bytes) needs\nto be the same size as the pointer was allocated with. (Because similar to\nalignment, dealloc must be called with the same layout size.)length needs to be less than or equal to capacity.length values must be properly initialized values of type T.capacity needs to fit the layout size that the pointer was allocated with.isize::MAX.\nSee the safety documentation of pointer::offset.These requirements are always upheld by any ptr that has been allocated\nvia Vec<T, A>. Other allocation sources are allowed if the invariants are\nupheld.
Violating these may cause problems like corrupting the allocator’s\ninternal data structures. For example it is not safe\nto build a Vec<u8> from a pointer to a C char array with length size_t.\nIt’s also not safe to build one from a Vec<u16> and its length, because\nthe allocator cares about the alignment, and these two types have different\nalignments. The buffer was allocated with alignment 2 (for u16), but after\nturning it into a Vec<u8> it’ll be deallocated with alignment 1.
The ownership of ptr is effectively transferred to the\nVec<T> which may then deallocate, reallocate or change the\ncontents of memory pointed to by the pointer at will. Ensure\nthat nothing else uses the pointer after calling this\nfunction.
#![feature(allocator_api)]\n\nuse std::alloc::System;\n\nuse std::ptr;\nuse std::mem;\n\nlet mut v = Vec::with_capacity_in(3, System);\nv.push(1);\nv.push(2);\nv.push(3);\n\n// Prevent running `v`'s destructor so we are in complete control\n// of the allocation.\nlet mut v = mem::ManuallyDrop::new(v);\n\n// Pull out the various important pieces of information about `v`\nlet p = v.as_mut_ptr();\nlet len = v.len();\nlet cap = v.capacity();\nlet alloc = v.allocator();\n\nunsafe {\n // Overwrite memory with 4, 5, 6\n for i in 0..len {\n ptr::write(p.add(i), 4 + i);\n }\n\n // Put everything back together into a Vec\n let rebuilt = Vec::from_raw_parts_in(p, len, cap, alloc.clone());\n assert_eq!(rebuilt, [4, 5, 6]);\n}Using memory that was allocated elsewhere:
\n\n#![feature(allocator_api)]\n\nuse std::alloc::{AllocError, Allocator, Global, Layout};\n\nfn main() {\n let layout = Layout::array::<u32>(16).expect(\"overflow cannot happen\");\n\n let vec = unsafe {\n let mem = match Global.allocate(layout) {\n Ok(mem) => mem.cast::<u32>().as_ptr(),\n Err(AllocError) => return,\n };\n\n mem.write(1_000_000);\n\n Vec::from_raw_parts_in(mem, 1, 16, Global)\n };\n\n assert_eq!(vec, &[1_000_000]);\n assert_eq!(vec.capacity(), 16);\n}vec_into_raw_parts)Decomposes a Vec<T> into its raw components: (pointer, length, capacity).
Returns the raw pointer to the underlying data, the length of\nthe vector (in elements), and the allocated capacity of the\ndata (in elements). These are the same arguments in the same\norder as the arguments to from_raw_parts.
After calling this function, the caller is responsible for the\nmemory previously managed by the Vec. The only way to do\nthis is to convert the raw pointer, length, and capacity back\ninto a Vec with the from_raw_parts function, allowing\nthe destructor to perform the cleanup.
#![feature(vec_into_raw_parts)]\nlet v: Vec<i32> = vec![-1, 0, 1];\n\nlet (ptr, len, cap) = v.into_raw_parts();\n\nlet rebuilt = unsafe {\n // We can now make changes to the components, such as\n // transmuting the raw pointer to a compatible type.\n let ptr = ptr as *mut u32;\n\n Vec::from_raw_parts(ptr, len, cap)\n};\nassert_eq!(rebuilt, [4294967295, 0, 1]);allocator_api)Decomposes a Vec<T> into its raw components: (pointer, length, capacity, allocator).
Returns the raw pointer to the underlying data, the length of the vector (in elements),\nthe allocated capacity of the data (in elements), and the allocator. These are the same\narguments in the same order as the arguments to from_raw_parts_in.
After calling this function, the caller is responsible for the\nmemory previously managed by the Vec. The only way to do\nthis is to convert the raw pointer, length, and capacity back\ninto a Vec with the from_raw_parts_in function, allowing\nthe destructor to perform the cleanup.
#![feature(allocator_api, vec_into_raw_parts)]\n\nuse std::alloc::System;\n\nlet mut v: Vec<i32, System> = Vec::new_in(System);\nv.push(-1);\nv.push(0);\nv.push(1);\n\nlet (ptr, len, cap, alloc) = v.into_raw_parts_with_alloc();\n\nlet rebuilt = unsafe {\n // We can now make changes to the components, such as\n // transmuting the raw pointer to a compatible type.\n let ptr = ptr as *mut u32;\n\n Vec::from_raw_parts_in(ptr, len, cap, alloc)\n};\nassert_eq!(rebuilt, [4294967295, 0, 1]);Returns the total number of elements the vector can hold without\nreallocating.
\nlet mut vec: Vec<i32> = Vec::with_capacity(10);\nvec.push(42);\nassert!(vec.capacity() >= 10);Reserves capacity for at least additional more elements to be inserted\nin the given Vec<T>. The collection may reserve more space to\nspeculatively avoid frequent reallocations. After calling reserve,\ncapacity will be greater than or equal to self.len() + additional.\nDoes nothing if capacity is already sufficient.
Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1];\nvec.reserve(10);\nassert!(vec.capacity() >= 11);Reserves the minimum capacity for at least additional more elements to\nbe inserted in the given Vec<T>. Unlike reserve, this will not\ndeliberately over-allocate to speculatively avoid frequent allocations.\nAfter calling reserve_exact, capacity will be greater than or equal to\nself.len() + additional. Does nothing if the capacity is already\nsufficient.
Note that the allocator may give the collection more space than it\nrequests. Therefore, capacity can not be relied upon to be precisely\nminimal. Prefer reserve if future insertions are expected.
Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1];\nvec.reserve_exact(10);\nassert!(vec.capacity() >= 11);Tries to reserve capacity for at least additional more elements to be inserted\nin the given Vec<T>. The collection may reserve more space to speculatively avoid\nfrequent reallocations. After calling try_reserve, capacity will be\ngreater than or equal to self.len() + additional if it returns\nOk(()). Does nothing if capacity is already sufficient. This method\npreserves the contents even if an error occurs.
If the capacity overflows, or the allocator reports a failure, then an error\nis returned.
\nuse std::collections::TryReserveError;\n\nfn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {\n let mut output = Vec::new();\n\n // Pre-reserve the memory, exiting if we can't\n output.try_reserve(data.len())?;\n\n // Now we know this can't OOM in the middle of our complex work\n output.extend(data.iter().map(|&val| {\n val * 2 + 5 // very complicated\n }));\n\n Ok(output)\n}Tries to reserve the minimum capacity for at least additional\nelements to be inserted in the given Vec<T>. Unlike try_reserve,\nthis will not deliberately over-allocate to speculatively avoid frequent\nallocations. After calling try_reserve_exact, capacity will be greater\nthan or equal to self.len() + additional if it returns Ok(()).\nDoes nothing if the capacity is already sufficient.
Note that the allocator may give the collection more space than it\nrequests. Therefore, capacity can not be relied upon to be precisely\nminimal. Prefer try_reserve if future insertions are expected.
If the capacity overflows, or the allocator reports a failure, then an error\nis returned.
\nuse std::collections::TryReserveError;\n\nfn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {\n let mut output = Vec::new();\n\n // Pre-reserve the memory, exiting if we can't\n output.try_reserve_exact(data.len())?;\n\n // Now we know this can't OOM in the middle of our complex work\n output.extend(data.iter().map(|&val| {\n val * 2 + 5 // very complicated\n }));\n\n Ok(output)\n}Shrinks the capacity of the vector as much as possible.
\nThe behavior of this method depends on the allocator, which may either shrink the vector\nin-place or reallocate. The resulting vector might still have some excess capacity, just as\nis the case for with_capacity. See Allocator::shrink for more details.
let mut vec = Vec::with_capacity(10);\nvec.extend([1, 2, 3]);\nassert!(vec.capacity() >= 10);\nvec.shrink_to_fit();\nassert!(vec.capacity() >= 3);Shrinks the capacity of the vector with a lower bound.
\nThe capacity will remain at least as large as both the length\nand the supplied value.
\nIf the current capacity is less than the lower limit, this is a no-op.
\nlet mut vec = Vec::with_capacity(10);\nvec.extend([1, 2, 3]);\nassert!(vec.capacity() >= 10);\nvec.shrink_to(4);\nassert!(vec.capacity() >= 4);\nvec.shrink_to(0);\nassert!(vec.capacity() >= 3);Converts the vector into Box<[T]>.
Before doing the conversion, this method discards excess capacity like shrink_to_fit.
let v = vec![1, 2, 3];\n\nlet slice = v.into_boxed_slice();Any excess capacity is removed:
\n\nlet mut vec = Vec::with_capacity(10);\nvec.extend([1, 2, 3]);\n\nassert!(vec.capacity() >= 10);\nlet slice = vec.into_boxed_slice();\nassert_eq!(slice.into_vec().capacity(), 3);Shortens the vector, keeping the first len elements and dropping\nthe rest.
If len is greater or equal to the vector’s current length, this has\nno effect.
The drain method can emulate truncate, but causes the excess\nelements to be returned instead of dropped.
Note that this method has no effect on the allocated capacity\nof the vector.
\nTruncating a five element vector to two elements:
\n\nlet mut vec = vec![1, 2, 3, 4, 5];\nvec.truncate(2);\nassert_eq!(vec, [1, 2]);No truncation occurs when len is greater than the vector’s current\nlength:
let mut vec = vec![1, 2, 3];\nvec.truncate(8);\nassert_eq!(vec, [1, 2, 3]);Truncating when len == 0 is equivalent to calling the clear\nmethod.
let mut vec = vec![1, 2, 3];\nvec.truncate(0);\nassert_eq!(vec, []);Extracts a slice containing the entire vector.
\nEquivalent to &s[..].
use std::io::{self, Write};\nlet buffer = vec![1, 2, 3, 5, 8];\nio::sink().write(buffer.as_slice()).unwrap();Extracts a mutable slice of the entire vector.
\nEquivalent to &mut s[..].
use std::io::{self, Read};\nlet mut buffer = vec![0; 3];\nio::repeat(0b101).read_exact(buffer.as_mut_slice()).unwrap();Returns a raw pointer to the vector’s buffer, or a dangling raw pointer\nvalid for zero sized reads if the vector didn’t allocate.
\nThe caller must ensure that the vector outlives the pointer this\nfunction returns, or else it will end up pointing to garbage.\nModifying the vector may cause its buffer to be reallocated,\nwhich would also make any pointers to it invalid.
\nThe caller must also ensure that the memory the pointer (non-transitively) points to\nis never written to (except inside an UnsafeCell) using this pointer or any pointer\nderived from it. If you need to mutate the contents of the slice, use as_mut_ptr.
This method guarantees that for the purpose of the aliasing model, this method\ndoes not materialize a reference to the underlying slice, and thus the returned pointer\nwill remain valid when mixed with other calls to as_ptr and as_mut_ptr.\nNote that calling other methods that materialize mutable references to the slice,\nor mutable references to specific elements you are planning on accessing through this pointer,\nas well as writing to those elements, may still invalidate this pointer.\nSee the second example below for how this guarantee can be used.
let x = vec![1, 2, 4];\nlet x_ptr = x.as_ptr();\n\nunsafe {\n for i in 0..x.len() {\n assert_eq!(*x_ptr.add(i), 1 << i);\n }\n}Due to the aliasing guarantee, the following code is legal:
\n\nunsafe {\n let mut v = vec![0, 1, 2];\n let ptr1 = v.as_ptr();\n let _ = ptr1.read();\n let ptr2 = v.as_mut_ptr().offset(2);\n ptr2.write(2);\n // Notably, the write to `ptr2` did *not* invalidate `ptr1`\n // because it mutated a different element:\n let _ = ptr1.read();\n}Returns an unsafe mutable pointer to the vector’s buffer, or a dangling\nraw pointer valid for zero sized reads if the vector didn’t allocate.
\nThe caller must ensure that the vector outlives the pointer this\nfunction returns, or else it will end up pointing to garbage.\nModifying the vector may cause its buffer to be reallocated,\nwhich would also make any pointers to it invalid.
\nThis method guarantees that for the purpose of the aliasing model, this method\ndoes not materialize a reference to the underlying slice, and thus the returned pointer\nwill remain valid when mixed with other calls to as_ptr and as_mut_ptr.\nNote that calling other methods that materialize references to the slice,\nor references to specific elements you are planning on accessing through this pointer,\nmay still invalidate this pointer.\nSee the second example below for how this guarantee can be used.
// Allocate vector big enough for 4 elements.\nlet size = 4;\nlet mut x: Vec<i32> = Vec::with_capacity(size);\nlet x_ptr = x.as_mut_ptr();\n\n// Initialize elements via raw pointer writes, then set length.\nunsafe {\n for i in 0..size {\n *x_ptr.add(i) = i as i32;\n }\n x.set_len(size);\n}\nassert_eq!(&*x, &[0, 1, 2, 3]);Due to the aliasing guarantee, the following code is legal:
\n\nunsafe {\n let mut v = vec![0];\n let ptr1 = v.as_mut_ptr();\n ptr1.write(1);\n let ptr2 = v.as_mut_ptr();\n ptr2.write(2);\n // Notably, the write to `ptr2` did *not* invalidate `ptr1`:\n ptr1.write(3);\n}allocator_api)Returns a reference to the underlying allocator.
\nForces the length of the vector to new_len.
This is a low-level operation that maintains none of the normal\ninvariants of the type. Normally changing the length of a vector\nis done using one of the safe operations instead, such as\ntruncate, resize, extend, or clear.
new_len must be less than or equal to capacity().old_len..new_len must be initialized.This method can be useful for situations in which the vector\nis serving as a buffer for other code, particularly over FFI:
\n\npub fn get_dictionary(&self) -> Option<Vec<u8>> {\n // Per the FFI method's docs, \"32768 bytes is always enough\".\n let mut dict = Vec::with_capacity(32_768);\n let mut dict_length = 0;\n // SAFETY: When `deflateGetDictionary` returns `Z_OK`, it holds that:\n // 1. `dict_length` elements were initialized.\n // 2. `dict_length` <= the capacity (32_768)\n // which makes `set_len` safe to call.\n unsafe {\n // Make the FFI call...\n let r = deflateGetDictionary(self.strm, dict.as_mut_ptr(), &mut dict_length);\n if r == Z_OK {\n // ...and update the length to what was initialized.\n dict.set_len(dict_length);\n Some(dict)\n } else {\n None\n }\n }\n}While the following example is sound, there is a memory leak since\nthe inner vectors were not freed prior to the set_len call:
let mut vec = vec![vec![1, 0, 0],\n vec![0, 1, 0],\n vec![0, 0, 1]];\n// SAFETY:\n// 1. `old_len..0` is empty so no elements need to be initialized.\n// 2. `0 <= capacity` always holds whatever `capacity` is.\nunsafe {\n vec.set_len(0);\n}Normally, here, one would use clear instead to correctly drop\nthe contents and thus not leak memory.
Removes an element from the vector and returns it.
\nThe removed element is replaced by the last element of the vector.
\nThis does not preserve ordering of the remaining elements, but is O(1).\nIf you need to preserve the element order, use remove instead.
Panics if index is out of bounds.
let mut v = vec![\"foo\", \"bar\", \"baz\", \"qux\"];\n\nassert_eq!(v.swap_remove(1), \"bar\");\nassert_eq!(v, [\"foo\", \"qux\", \"baz\"]);\n\nassert_eq!(v.swap_remove(0), \"foo\");\nassert_eq!(v, [\"baz\", \"qux\"]);Inserts an element at position index within the vector, shifting all\nelements after it to the right.
Panics if index > len.
let mut vec = vec![1, 2, 3];\nvec.insert(1, 4);\nassert_eq!(vec, [1, 4, 2, 3]);\nvec.insert(4, 5);\nassert_eq!(vec, [1, 4, 2, 3, 5]);Takes O(Vec::len) time. All items after the insertion index must be\nshifted to the right. In the worst case, all elements are shifted when\nthe insertion index is 0.
Removes and returns the element at position index within the vector,\nshifting all elements after it to the left.
Note: Because this shifts over the remaining elements, it has a\nworst-case performance of O(n). If you don’t need the order of elements\nto be preserved, use swap_remove instead. If you’d like to remove\nelements from the beginning of the Vec, consider using\nVecDeque::pop_front instead.
Panics if index is out of bounds.
let mut v = vec![1, 2, 3];\nassert_eq!(v.remove(1), 2);\nassert_eq!(v, [1, 3]);Retains only the elements specified by the predicate.
\nIn other words, remove all elements e for which f(&e) returns false.\nThis method operates in place, visiting each element exactly once in the\noriginal order, and preserves the order of the retained elements.
let mut vec = vec![1, 2, 3, 4];\nvec.retain(|&x| x % 2 == 0);\nassert_eq!(vec, [2, 4]);Because the elements are visited exactly once in the original order,\nexternal state may be used to decide which elements to keep.
\n\nlet mut vec = vec![1, 2, 3, 4, 5];\nlet keep = [false, true, true, false, true];\nlet mut iter = keep.iter();\nvec.retain(|_| *iter.next().unwrap());\nassert_eq!(vec, [2, 3, 5]);Retains only the elements specified by the predicate, passing a mutable reference to it.
\nIn other words, remove all elements e such that f(&mut e) returns false.\nThis method operates in place, visiting each element exactly once in the\noriginal order, and preserves the order of the retained elements.
let mut vec = vec![1, 2, 3, 4];\nvec.retain_mut(|x| if *x <= 3 {\n *x += 1;\n true\n} else {\n false\n});\nassert_eq!(vec, [2, 3, 4]);Removes all but the first of consecutive elements in the vector that resolve to the same\nkey.
\nIf the vector is sorted, this removes all duplicates.
\nlet mut vec = vec![10, 20, 21, 30, 20];\n\nvec.dedup_by_key(|i| *i / 10);\n\nassert_eq!(vec, [10, 20, 30, 20]);Removes all but the first of consecutive elements in the vector satisfying a given equality\nrelation.
\nThe same_bucket function is passed references to two elements from the vector and\nmust determine if the elements compare equal. The elements are passed in opposite order\nfrom their order in the slice, so if same_bucket(a, b) returns true, a is removed.
If the vector is sorted, this removes all duplicates.
\nlet mut vec = vec![\"foo\", \"bar\", \"Bar\", \"baz\", \"bar\"];\n\nvec.dedup_by(|a, b| a.eq_ignore_ascii_case(b));\n\nassert_eq!(vec, [\"foo\", \"bar\", \"baz\", \"bar\"]);Appends an element to the back of a collection.
\nPanics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1, 2];\nvec.push(3);\nassert_eq!(vec, [1, 2, 3]);Takes amortized O(1) time. If the vector’s length would exceed its\ncapacity after the push, O(capacity) time is taken to copy the\nvector’s elements to a larger allocation. This expensive operation is\noffset by the capacity O(1) insertions it allows.
\nvec_push_within_capacity)Appends an element if there is sufficient spare capacity, otherwise an error is returned\nwith the element.
\nUnlike push this method will not reallocate when there’s insufficient capacity.\nThe caller should use reserve or try_reserve to ensure that there is enough capacity.
A manual, panic-free alternative to FromIterator:
#![feature(vec_push_within_capacity)]\n\nuse std::collections::TryReserveError;\nfn from_iter_fallible<T>(iter: impl Iterator<Item=T>) -> Result<Vec<T>, TryReserveError> {\n let mut vec = Vec::new();\n for value in iter {\n if let Err(value) = vec.push_within_capacity(value) {\n vec.try_reserve(1)?;\n // this cannot fail, the previous line either returned or added at least 1 free slot\n let _ = vec.push_within_capacity(value);\n }\n }\n Ok(vec)\n}\nassert_eq!(from_iter_fallible(0..100), Ok(Vec::from_iter(0..100)));Takes O(1) time.
\nRemoves the last element from a vector and returns it, or None if it\nis empty.
If you’d like to pop the first element, consider using\nVecDeque::pop_front instead.
let mut vec = vec![1, 2, 3];\nassert_eq!(vec.pop(), Some(3));\nassert_eq!(vec, [1, 2]);Takes O(1) time.
\nvec_pop_if)Removes and returns the last element in a vector if the predicate\nreturns true, or None if the predicate returns false or the vector\nis empty.
#![feature(vec_pop_if)]\n\nlet mut vec = vec![1, 2, 3, 4];\nlet pred = |x: &mut i32| *x % 2 == 0;\n\nassert_eq!(vec.pop_if(pred), Some(4));\nassert_eq!(vec, [1, 2, 3]);\nassert_eq!(vec.pop_if(pred), None);Removes the specified range from the vector in bulk, returning all\nremoved elements as an iterator. If the iterator is dropped before\nbeing fully consumed, it drops the remaining removed elements.
\nThe returned iterator keeps a mutable borrow on the vector to optimize\nits implementation.
\nPanics if the starting point is greater than the end point or if\nthe end point is greater than the length of the vector.
\nIf the returned iterator goes out of scope without being dropped (due to\nmem::forget, for example), the vector may have lost and leaked\nelements arbitrarily, including elements outside the range.
let mut v = vec![1, 2, 3];\nlet u: Vec<_> = v.drain(1..).collect();\nassert_eq!(v, &[1]);\nassert_eq!(u, &[2, 3]);\n\n// A full range clears the vector, like `clear()` does\nv.drain(..);\nassert_eq!(v, &[]);Clears the vector, removing all values.
\nNote that this method has no effect on the allocated capacity\nof the vector.
\nlet mut v = vec![1, 2, 3];\n\nv.clear();\n\nassert!(v.is_empty());Returns the number of elements in the vector, also referred to\nas its ‘length’.
\nlet a = vec![1, 2, 3];\nassert_eq!(a.len(), 3);Returns true if the vector contains no elements.
let mut v = Vec::new();\nassert!(v.is_empty());\n\nv.push(1);\nassert!(!v.is_empty());Splits the collection into two at the given index.
\nReturns a newly allocated vector containing the elements in the range\n[at, len). After the call, the original vector will be left containing\nthe elements [0, at) with its previous capacity unchanged.
mem::take or mem::replace.Vec::truncate.Vec::drain.Panics if at > len.
let mut vec = vec![1, 2, 3];\nlet vec2 = vec.split_off(1);\nassert_eq!(vec, [1]);\nassert_eq!(vec2, [2, 3]);Resizes the Vec in-place so that len is equal to new_len.
If new_len is greater than len, the Vec is extended by the\ndifference, with each additional slot filled with the result of\ncalling the closure f. The return values from f will end up\nin the Vec in the order they have been generated.
If new_len is less than len, the Vec is simply truncated.
This method uses a closure to create new values on every push. If\nyou’d rather Clone a given value, use Vec::resize. If you\nwant to use the Default trait to generate values, you can\npass Default::default as the second argument.
let mut vec = vec![1, 2, 3];\nvec.resize_with(5, Default::default);\nassert_eq!(vec, [1, 2, 3, 0, 0]);\n\nlet mut vec = vec![];\nlet mut p = 1;\nvec.resize_with(4, || { p *= 2; p });\nassert_eq!(vec, [2, 4, 8, 16]);Consumes and leaks the Vec, returning a mutable reference to the contents,\n&'a mut [T]. Note that the type T must outlive the chosen lifetime\n'a. If the type has only static references, or none at all, then this\nmay be chosen to be 'static.
As of Rust 1.57, this method does not reallocate or shrink the Vec,\nso the leaked allocation may include unused capacity that is not part\nof the returned slice.
This function is mainly useful for data that lives for the remainder of\nthe program’s life. Dropping the returned reference will cause a memory\nleak.
\nSimple usage:
\n\nlet x = vec![1, 2, 3];\nlet static_ref: &'static mut [usize] = x.leak();\nstatic_ref[0] += 1;\nassert_eq!(static_ref, &[2, 2, 3]);Returns the remaining spare capacity of the vector as a slice of\nMaybeUninit<T>.
The returned slice can be used to fill the vector with data (e.g. by\nreading from a file) before marking the data as initialized using the\nset_len method.
// Allocate vector big enough for 10 elements.\nlet mut v = Vec::with_capacity(10);\n\n// Fill in the first 3 elements.\nlet uninit = v.spare_capacity_mut();\nuninit[0].write(0);\nuninit[1].write(1);\nuninit[2].write(2);\n\n// Mark the first 3 elements of the vector as being initialized.\nunsafe {\n v.set_len(3);\n}\n\nassert_eq!(&v, &[0, 1, 2]);vec_split_at_spare)Returns vector content as a slice of T, along with the remaining spare\ncapacity of the vector as a slice of MaybeUninit<T>.
The returned spare capacity slice can be used to fill the vector with data\n(e.g. by reading from a file) before marking the data as initialized using\nthe set_len method.
Note that this is a low-level API, which should be used with care for\noptimization purposes. If you need to append data to a Vec\nyou can use push, extend, extend_from_slice,\nextend_from_within, insert, append, resize or\nresize_with, depending on your exact needs.
#![feature(vec_split_at_spare)]\n\nlet mut v = vec![1, 1, 2];\n\n// Reserve additional space big enough for 10 elements.\nv.reserve(10);\n\nlet (init, uninit) = v.split_at_spare_mut();\nlet sum = init.iter().copied().sum::<u32>();\n\n// Fill in the next 4 elements.\nuninit[0].write(sum);\nuninit[1].write(sum * 2);\nuninit[2].write(sum * 3);\nuninit[3].write(sum * 4);\n\n// Mark the 4 elements of the vector as being initialized.\nunsafe {\n let len = v.len();\n v.set_len(len + 4);\n}\n\nassert_eq!(&v, &[1, 1, 2, 4, 8, 12, 16]);Write is implemented for Vec<u8> by appending to the vector.\nThe vector will grow as needed.
can_vector)write_all_vectored)Self from the given unstructured data. Read moreSelf from the entirety of the given\nunstructured data. Read moreOverwrites the contents of self with a clone of the contents of source.
This method is preferred over simply assigning source.clone() to self,\nas it avoids reallocation if possible. Additionally, if the element type\nT overrides clone_from(), this will reuse the resources of self’s\nelements as well.
let x = vec![5, 6, 7];\nlet mut y = vec![8, 9, 10];\nlet yp: *const i32 = y.as_ptr();\n\ny.clone_from(&x);\n\n// The value is the same\nassert_eq!(x, y);\n\n// And no reallocation occurred\nassert_eq!(yp, y.as_ptr());try_default in case the value is null or\nundefined.Reader].Extend implementation that copies elements out of references before pushing them onto the Vec.
\nThis implementation is specialized for slice iterators, where it uses copy_from_slice to\nappend the entire slice at once.
extend_one)extend_one)extend_one)extend_one)Converts a BinaryHeap<T> into a Vec<T>.
This conversion requires no data movement or allocation, and has\nconstant time complexity.
\nConvert a clone-on-write slice into a vector.
\nIf s already owns a Vec<T>, it will be returned directly.\nIf s is borrowing a slice, a new Vec<T> will be allocated and\nfilled by cloning s’s items into it.
let o: Cow<'_, [i32]> = Cow::Owned(vec![1, 2, 3]);\nlet b: Cow<'_, [i32]> = Cow::Borrowed(&[1, 2, 3]);\nassert_eq!(Vec::from(o), Vec::from(b));Turn a VecDeque<T> into a Vec<T>.
This never needs to re-allocate, but does need to do O(n) data movement if\nthe circular buffer doesn’t happen to be at the beginning of the allocation.
\nuse std::collections::VecDeque;\n\n// This one is *O*(1).\nlet deque: VecDeque<_> = (1..5).collect();\nlet ptr = deque.as_slices().0.as_ptr();\nlet vec = Vec::from(deque);\nassert_eq!(vec, [1, 2, 3, 4]);\nassert_eq!(vec.as_ptr(), ptr);\n\n// This one needs data rearranging.\nlet mut deque: VecDeque<_> = (1..5).collect();\ndeque.push_front(9);\ndeque.push_front(8);\nlet ptr = deque.as_slices().1.as_ptr();\nlet vec = Vec::from(deque);\nassert_eq!(vec, [8, 9, 1, 2, 3, 4]);\nassert_eq!(vec.as_ptr(), ptr);manual impl of FromDer, so we do not need to require TryFrom<Any> + CheckDerConstraints
Collects an iterator into a Vec, commonly called via Iterator::collect()
In general Vec does not guarantee any particular growth or allocation strategy.\nThat also applies to this trait impl.
Note: This section covers implementation details and is therefore exempt from\nstability guarantees.
\nVec may use any or none of the following strategies,\ndepending on the supplied iterator:
\nIterator::size_hint()\npushing one item at a timeThe last case warrants some attention. It is an optimization that in many cases reduces peak memory\nconsumption and improves cache locality. But when big, short-lived allocations are created,\nonly a small fraction of their items get collected, no further use is made of the spare capacity\nand the resulting Vec is moved into a longer-lived structure, then this can lead to the large\nallocations having their lifetimes unnecessarily extended which can result in increased memory\nfootprint.
In cases where this is an issue, the excess capacity can be discarded with Vec::shrink_to(),\nVec::shrink_to_fit() or by collecting into Box<[T]> instead, which additionally reduces\nthe size of the long-lived struct.
static LONG_LIVED: Mutex<Vec<Vec<u16>>> = Mutex::new(Vec::new());\n\nfor i in 0..10 {\n let big_temporary: Vec<u16> = (0..1024).collect();\n // discard most items\n let mut result: Vec<_> = big_temporary.into_iter().filter(|i| i % 100 == 0).collect();\n // without this a lot of unused capacity might be moved into the global\n result.shrink_to_fit();\n LONG_LIVED.lock().unwrap().push(result);\n}The hash of a vector is the same as that of the corresponding slice,\nas required by the core::borrow::Borrow implementation.
use std::hash::BuildHasher;\n\nlet b = std::hash::RandomState::new();\nlet v: Vec<u8> = vec![0xa8, 0x3c, 0x09];\nlet s: &[u8] = &[0xa8, 0x3c, 0x09];\nassert_eq!(b.hash_one(v), b.hash_one(s));Creates a consuming iterator, that is, one that moves each value out of\nthe vector (from start to end). The vector cannot be used after calling\nthis.
\nlet v = vec![\"a\".to_string(), \"b\".to_string()];\nlet mut v_iter = v.into_iter();\n\nlet first_element: Option<String> = v_iter.next();\n\nassert_eq!(first_element, Some(\"a\".to_string()));\nassert_eq!(v_iter.next(), Some(\"b\".to_string()));\nassert_eq!(v_iter.next(), None);Implements ordering of vectors, lexicographically.
\nImplements comparison of vectors, lexicographically.
\nself and other) and is used by the <=\noperator. Read moreSink to receive a value. Read morepoll_ready which returned Poll::Ready(Ok(())). Read moreVec<u8>.to_vec, but uses provided values without changes.\nThis can generate an invalid encoding for a DER object.to_der, but uses provided values without changes.\nThis can generate an invalid encoding for a DER object.Constructs a new, empty Vec<T>.
The vector will not allocate until elements are pushed onto it.
\nlet mut vec: Vec<i32> = Vec::new();Constructs a new, empty Vec<T> with at least the specified capacity.
The vector will be able to hold at least capacity elements without\nreallocating. This method is allowed to allocate for more elements than\ncapacity. If capacity is 0, the vector will not allocate.
It is important to note that although the returned vector has the\nminimum capacity specified, the vector will have a zero length. For\nan explanation of the difference between length and capacity, see\nCapacity and reallocation.
\nIf it is important to know the exact allocated capacity of a Vec,\nalways use the capacity method after construction.
For Vec<T> where T is a zero-sized type, there will be no allocation\nand the capacity will always be usize::MAX.
Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = Vec::with_capacity(10);\n\n// The vector contains no items, even though it has capacity for more\nassert_eq!(vec.len(), 0);\nassert!(vec.capacity() >= 10);\n\n// These are all done without reallocating...\nfor i in 0..10 {\n vec.push(i);\n}\nassert_eq!(vec.len(), 10);\nassert!(vec.capacity() >= 10);\n\n// ...but this may make the vector reallocate\nvec.push(11);\nassert_eq!(vec.len(), 11);\nassert!(vec.capacity() >= 11);\n\n// A vector of a zero-sized type will always over-allocate, since no\n// allocation is necessary\nlet vec_units = Vec::<()>::with_capacity(10);\nassert_eq!(vec_units.capacity(), usize::MAX);try_with_capacity)Constructs a new, empty Vec<T> with at least the specified capacity.
The vector will be able to hold at least capacity elements without\nreallocating. This method is allowed to allocate for more elements than\ncapacity. If capacity is 0, the vector will not allocate.
Returns an error if the capacity exceeds isize::MAX bytes,\nor if the allocator reports allocation failure.
Creates a Vec<T> directly from a pointer, a length, and a capacity.
This is highly unsafe, due to the number of invariants that aren’t\nchecked:
\nptr must have been allocated using the global allocator, such as via\nthe alloc::alloc function.T needs to have the same alignment as what ptr was allocated with.\n(T having a less strict alignment is not sufficient, the alignment really\nneeds to be equal to satisfy the dealloc requirement that memory must be\nallocated and deallocated with the same layout.)T times the capacity (ie. the allocated size in bytes) needs\nto be the same size as the pointer was allocated with. (Because similar to\nalignment, dealloc must be called with the same layout size.)length needs to be less than or equal to capacity.length values must be properly initialized values of type T.capacity needs to be the capacity that the pointer was allocated with.isize::MAX.\nSee the safety documentation of pointer::offset.These requirements are always upheld by any ptr that has been allocated\nvia Vec<T>. Other allocation sources are allowed if the invariants are\nupheld.
Violating these may cause problems like corrupting the allocator’s\ninternal data structures. For example it is normally not safe\nto build a Vec<u8> from a pointer to a C char array with length\nsize_t, doing so is only safe if the array was initially allocated by\na Vec or String.\nIt’s also not safe to build one from a Vec<u16> and its length, because\nthe allocator cares about the alignment, and these two types have different\nalignments. The buffer was allocated with alignment 2 (for u16), but after\nturning it into a Vec<u8> it’ll be deallocated with alignment 1. To avoid\nthese issues, it is often preferable to do casting/transmuting using\nslice::from_raw_parts instead.
The ownership of ptr is effectively transferred to the\nVec<T> which may then deallocate, reallocate or change the\ncontents of memory pointed to by the pointer at will. Ensure\nthat nothing else uses the pointer after calling this\nfunction.
use std::ptr;\nuse std::mem;\n\nlet v = vec![1, 2, 3];\n\n// Prevent running `v`'s destructor so we are in complete control\n// of the allocation.\nlet mut v = mem::ManuallyDrop::new(v);\n\n// Pull out the various important pieces of information about `v`\nlet p = v.as_mut_ptr();\nlet len = v.len();\nlet cap = v.capacity();\n\nunsafe {\n // Overwrite memory with 4, 5, 6\n for i in 0..len {\n ptr::write(p.add(i), 4 + i);\n }\n\n // Put everything back together into a Vec\n let rebuilt = Vec::from_raw_parts(p, len, cap);\n assert_eq!(rebuilt, [4, 5, 6]);\n}Using memory that was allocated elsewhere:
\n\nuse std::alloc::{alloc, Layout};\n\nfn main() {\n let layout = Layout::array::<u32>(16).expect(\"overflow cannot happen\");\n\n let vec = unsafe {\n let mem = alloc(layout).cast::<u32>();\n if mem.is_null() {\n return;\n }\n\n mem.write(1_000_000);\n\n Vec::from_raw_parts(mem, 1, 16)\n };\n\n assert_eq!(vec, &[1_000_000]);\n assert_eq!(vec.capacity(), 16);\n}Resizes the Vec in-place so that len is equal to new_len.
If new_len is greater than len, the Vec is extended by the\ndifference, with each additional slot filled with value.\nIf new_len is less than len, the Vec is simply truncated.
This method requires T to implement Clone,\nin order to be able to clone the passed value.\nIf you need more flexibility (or want to rely on Default instead of\nClone), use Vec::resize_with.\nIf you only need to resize to a smaller size, use Vec::truncate.
let mut vec = vec![\"hello\"];\nvec.resize(3, \"world\");\nassert_eq!(vec, [\"hello\", \"world\", \"world\"]);\n\nlet mut vec = vec![1, 2, 3, 4];\nvec.resize(2, 0);\nassert_eq!(vec, [1, 2]);Clones and appends all elements in a slice to the Vec.
Iterates over the slice other, clones each element, and then appends\nit to this Vec. The other slice is traversed in-order.
Note that this function is same as extend except that it is\nspecialized to work with slices instead. If and when Rust gets\nspecialization this function will likely be deprecated (but still\navailable).
let mut vec = vec![1];\nvec.extend_from_slice(&[2, 3, 4]);\nassert_eq!(vec, [1, 2, 3, 4]);Copies elements from src range to the end of the vector.
Panics if the starting point is greater than the end point or if\nthe end point is greater than the length of the vector.
\nlet mut vec = vec![0, 1, 2, 3, 4];\n\nvec.extend_from_within(2..);\nassert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4]);\n\nvec.extend_from_within(..2);\nassert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1]);\n\nvec.extend_from_within(4..8);\nassert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]);Creates a splicing iterator that replaces the specified range in the vector\nwith the given replace_with iterator and yields the removed items.\nreplace_with does not need to be the same length as range.
range is removed even if the iterator is not consumed until the end.
It is unspecified how many elements are removed from the vector\nif the Splice value is leaked.
The input iterator replace_with is only consumed when the Splice value is dropped.
This is optimal if:
\nrange) is empty,replace_with yields fewer or equal elements than range’s lengthsize_hint() is exact.Otherwise, a temporary vector is allocated and the tail is moved twice.
\nPanics if the starting point is greater than the end point or if\nthe end point is greater than the length of the vector.
\nlet mut v = vec![1, 2, 3, 4];\nlet new = [7, 8, 9];\nlet u: Vec<_> = v.splice(1..3, new).collect();\nassert_eq!(v, &[1, 7, 8, 9, 4]);\nassert_eq!(u, &[2, 3]);extract_if)Creates an iterator which uses a closure to determine if an element should be removed.
\nIf the closure returns true, then the element is removed and yielded.\nIf the closure returns false, the element will remain in the vector and will not be yielded\nby the iterator.
\nIf the returned ExtractIf is not exhausted, e.g. because it is dropped without iterating\nor the iteration short-circuits, then the remaining elements will be retained.\nUse retain with a negated predicate if you do not need the returned iterator.
Using this method is equivalent to the following code:
\n\nlet mut i = 0;\nwhile i < vec.len() {\n if some_predicate(&mut vec[i]) {\n let val = vec.remove(i);\n // your code here\n } else {\n i += 1;\n }\n}\nBut extract_if is easier to use. extract_if is also more efficient,\nbecause it can backshift the elements of the array in bulk.
Note that extract_if also lets you mutate every element in the filter closure,\nregardless of whether you choose to keep or remove it.
Splitting an array into evens and odds, reusing the original allocation:
\n\n#![feature(extract_if)]\nlet mut numbers = vec![1, 2, 3, 4, 5, 6, 8, 9, 11, 13, 14, 15];\n\nlet evens = numbers.extract_if(|x| *x % 2 == 0).collect::<Vec<_>>();\nlet odds = numbers;\n\nassert_eq!(evens, vec![2, 4, 6, 8, 14]);\nassert_eq!(odds, vec![1, 3, 5, 9, 11, 13, 15]);allocator_api)Constructs a new, empty Vec<T, A>.
The vector will not allocate until elements are pushed onto it.
\n#![feature(allocator_api)]\n\nuse std::alloc::System;\n\nlet mut vec: Vec<i32, _> = Vec::new_in(System);allocator_api)Constructs a new, empty Vec<T, A> with at least the specified capacity\nwith the provided allocator.
The vector will be able to hold at least capacity elements without\nreallocating. This method is allowed to allocate for more elements than\ncapacity. If capacity is 0, the vector will not allocate.
It is important to note that although the returned vector has the\nminimum capacity specified, the vector will have a zero length. For\nan explanation of the difference between length and capacity, see\nCapacity and reallocation.
\nIf it is important to know the exact allocated capacity of a Vec,\nalways use the capacity method after construction.
For Vec<T, A> where T is a zero-sized type, there will be no allocation\nand the capacity will always be usize::MAX.
Panics if the new capacity exceeds isize::MAX bytes.
#![feature(allocator_api)]\n\nuse std::alloc::System;\n\nlet mut vec = Vec::with_capacity_in(10, System);\n\n// The vector contains no items, even though it has capacity for more\nassert_eq!(vec.len(), 0);\nassert!(vec.capacity() >= 10);\n\n// These are all done without reallocating...\nfor i in 0..10 {\n vec.push(i);\n}\nassert_eq!(vec.len(), 10);\nassert!(vec.capacity() >= 10);\n\n// ...but this may make the vector reallocate\nvec.push(11);\nassert_eq!(vec.len(), 11);\nassert!(vec.capacity() >= 11);\n\n// A vector of a zero-sized type will always over-allocate, since no\n// allocation is necessary\nlet vec_units = Vec::<(), System>::with_capacity_in(10, System);\nassert_eq!(vec_units.capacity(), usize::MAX);allocator_api)Constructs a new, empty Vec<T, A> with at least the specified capacity\nwith the provided allocator.
The vector will be able to hold at least capacity elements without\nreallocating. This method is allowed to allocate for more elements than\ncapacity. If capacity is 0, the vector will not allocate.
Returns an error if the capacity exceeds isize::MAX bytes,\nor if the allocator reports allocation failure.
allocator_api)Creates a Vec<T, A> directly from a pointer, a length, a capacity,\nand an allocator.
This is highly unsafe, due to the number of invariants that aren’t\nchecked:
\nptr must be currently allocated via the given allocator alloc.T needs to have the same alignment as what ptr was allocated with.\n(T having a less strict alignment is not sufficient, the alignment really\nneeds to be equal to satisfy the dealloc requirement that memory must be\nallocated and deallocated with the same layout.)T times the capacity (ie. the allocated size in bytes) needs\nto be the same size as the pointer was allocated with. (Because similar to\nalignment, dealloc must be called with the same layout size.)length needs to be less than or equal to capacity.length values must be properly initialized values of type T.capacity needs to fit the layout size that the pointer was allocated with.isize::MAX.\nSee the safety documentation of pointer::offset.These requirements are always upheld by any ptr that has been allocated\nvia Vec<T, A>. Other allocation sources are allowed if the invariants are\nupheld.
Violating these may cause problems like corrupting the allocator’s\ninternal data structures. For example it is not safe\nto build a Vec<u8> from a pointer to a C char array with length size_t.\nIt’s also not safe to build one from a Vec<u16> and its length, because\nthe allocator cares about the alignment, and these two types have different\nalignments. The buffer was allocated with alignment 2 (for u16), but after\nturning it into a Vec<u8> it’ll be deallocated with alignment 1.
The ownership of ptr is effectively transferred to the\nVec<T> which may then deallocate, reallocate or change the\ncontents of memory pointed to by the pointer at will. Ensure\nthat nothing else uses the pointer after calling this\nfunction.
#![feature(allocator_api)]\n\nuse std::alloc::System;\n\nuse std::ptr;\nuse std::mem;\n\nlet mut v = Vec::with_capacity_in(3, System);\nv.push(1);\nv.push(2);\nv.push(3);\n\n// Prevent running `v`'s destructor so we are in complete control\n// of the allocation.\nlet mut v = mem::ManuallyDrop::new(v);\n\n// Pull out the various important pieces of information about `v`\nlet p = v.as_mut_ptr();\nlet len = v.len();\nlet cap = v.capacity();\nlet alloc = v.allocator();\n\nunsafe {\n // Overwrite memory with 4, 5, 6\n for i in 0..len {\n ptr::write(p.add(i), 4 + i);\n }\n\n // Put everything back together into a Vec\n let rebuilt = Vec::from_raw_parts_in(p, len, cap, alloc.clone());\n assert_eq!(rebuilt, [4, 5, 6]);\n}Using memory that was allocated elsewhere:
\n\n#![feature(allocator_api)]\n\nuse std::alloc::{AllocError, Allocator, Global, Layout};\n\nfn main() {\n let layout = Layout::array::<u32>(16).expect(\"overflow cannot happen\");\n\n let vec = unsafe {\n let mem = match Global.allocate(layout) {\n Ok(mem) => mem.cast::<u32>().as_ptr(),\n Err(AllocError) => return,\n };\n\n mem.write(1_000_000);\n\n Vec::from_raw_parts_in(mem, 1, 16, Global)\n };\n\n assert_eq!(vec, &[1_000_000]);\n assert_eq!(vec.capacity(), 16);\n}vec_into_raw_parts)Decomposes a Vec<T> into its raw components: (pointer, length, capacity).
Returns the raw pointer to the underlying data, the length of\nthe vector (in elements), and the allocated capacity of the\ndata (in elements). These are the same arguments in the same\norder as the arguments to from_raw_parts.
After calling this function, the caller is responsible for the\nmemory previously managed by the Vec. The only way to do\nthis is to convert the raw pointer, length, and capacity back\ninto a Vec with the from_raw_parts function, allowing\nthe destructor to perform the cleanup.
#![feature(vec_into_raw_parts)]\nlet v: Vec<i32> = vec![-1, 0, 1];\n\nlet (ptr, len, cap) = v.into_raw_parts();\n\nlet rebuilt = unsafe {\n // We can now make changes to the components, such as\n // transmuting the raw pointer to a compatible type.\n let ptr = ptr as *mut u32;\n\n Vec::from_raw_parts(ptr, len, cap)\n};\nassert_eq!(rebuilt, [4294967295, 0, 1]);allocator_api)Decomposes a Vec<T> into its raw components: (pointer, length, capacity, allocator).
Returns the raw pointer to the underlying data, the length of the vector (in elements),\nthe allocated capacity of the data (in elements), and the allocator. These are the same\narguments in the same order as the arguments to from_raw_parts_in.
After calling this function, the caller is responsible for the\nmemory previously managed by the Vec. The only way to do\nthis is to convert the raw pointer, length, and capacity back\ninto a Vec with the from_raw_parts_in function, allowing\nthe destructor to perform the cleanup.
#![feature(allocator_api, vec_into_raw_parts)]\n\nuse std::alloc::System;\n\nlet mut v: Vec<i32, System> = Vec::new_in(System);\nv.push(-1);\nv.push(0);\nv.push(1);\n\nlet (ptr, len, cap, alloc) = v.into_raw_parts_with_alloc();\n\nlet rebuilt = unsafe {\n // We can now make changes to the components, such as\n // transmuting the raw pointer to a compatible type.\n let ptr = ptr as *mut u32;\n\n Vec::from_raw_parts_in(ptr, len, cap, alloc)\n};\nassert_eq!(rebuilt, [4294967295, 0, 1]);Returns the total number of elements the vector can hold without\nreallocating.
\nlet mut vec: Vec<i32> = Vec::with_capacity(10);\nvec.push(42);\nassert!(vec.capacity() >= 10);Reserves capacity for at least additional more elements to be inserted\nin the given Vec<T>. The collection may reserve more space to\nspeculatively avoid frequent reallocations. After calling reserve,\ncapacity will be greater than or equal to self.len() + additional.\nDoes nothing if capacity is already sufficient.
Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1];\nvec.reserve(10);\nassert!(vec.capacity() >= 11);Reserves the minimum capacity for at least additional more elements to\nbe inserted in the given Vec<T>. Unlike reserve, this will not\ndeliberately over-allocate to speculatively avoid frequent allocations.\nAfter calling reserve_exact, capacity will be greater than or equal to\nself.len() + additional. Does nothing if the capacity is already\nsufficient.
Note that the allocator may give the collection more space than it\nrequests. Therefore, capacity can not be relied upon to be precisely\nminimal. Prefer reserve if future insertions are expected.
Panics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1];\nvec.reserve_exact(10);\nassert!(vec.capacity() >= 11);Tries to reserve capacity for at least additional more elements to be inserted\nin the given Vec<T>. The collection may reserve more space to speculatively avoid\nfrequent reallocations. After calling try_reserve, capacity will be\ngreater than or equal to self.len() + additional if it returns\nOk(()). Does nothing if capacity is already sufficient. This method\npreserves the contents even if an error occurs.
If the capacity overflows, or the allocator reports a failure, then an error\nis returned.
\nuse std::collections::TryReserveError;\n\nfn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {\n let mut output = Vec::new();\n\n // Pre-reserve the memory, exiting if we can't\n output.try_reserve(data.len())?;\n\n // Now we know this can't OOM in the middle of our complex work\n output.extend(data.iter().map(|&val| {\n val * 2 + 5 // very complicated\n }));\n\n Ok(output)\n}Tries to reserve the minimum capacity for at least additional\nelements to be inserted in the given Vec<T>. Unlike try_reserve,\nthis will not deliberately over-allocate to speculatively avoid frequent\nallocations. After calling try_reserve_exact, capacity will be greater\nthan or equal to self.len() + additional if it returns Ok(()).\nDoes nothing if the capacity is already sufficient.
Note that the allocator may give the collection more space than it\nrequests. Therefore, capacity can not be relied upon to be precisely\nminimal. Prefer try_reserve if future insertions are expected.
If the capacity overflows, or the allocator reports a failure, then an error\nis returned.
\nuse std::collections::TryReserveError;\n\nfn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {\n let mut output = Vec::new();\n\n // Pre-reserve the memory, exiting if we can't\n output.try_reserve_exact(data.len())?;\n\n // Now we know this can't OOM in the middle of our complex work\n output.extend(data.iter().map(|&val| {\n val * 2 + 5 // very complicated\n }));\n\n Ok(output)\n}Shrinks the capacity of the vector as much as possible.
\nThe behavior of this method depends on the allocator, which may either shrink the vector\nin-place or reallocate. The resulting vector might still have some excess capacity, just as\nis the case for with_capacity. See Allocator::shrink for more details.
let mut vec = Vec::with_capacity(10);\nvec.extend([1, 2, 3]);\nassert!(vec.capacity() >= 10);\nvec.shrink_to_fit();\nassert!(vec.capacity() >= 3);Shrinks the capacity of the vector with a lower bound.
\nThe capacity will remain at least as large as both the length\nand the supplied value.
\nIf the current capacity is less than the lower limit, this is a no-op.
\nlet mut vec = Vec::with_capacity(10);\nvec.extend([1, 2, 3]);\nassert!(vec.capacity() >= 10);\nvec.shrink_to(4);\nassert!(vec.capacity() >= 4);\nvec.shrink_to(0);\nassert!(vec.capacity() >= 3);Converts the vector into Box<[T]>.
Before doing the conversion, this method discards excess capacity like shrink_to_fit.
let v = vec![1, 2, 3];\n\nlet slice = v.into_boxed_slice();Any excess capacity is removed:
\n\nlet mut vec = Vec::with_capacity(10);\nvec.extend([1, 2, 3]);\n\nassert!(vec.capacity() >= 10);\nlet slice = vec.into_boxed_slice();\nassert_eq!(slice.into_vec().capacity(), 3);Shortens the vector, keeping the first len elements and dropping\nthe rest.
If len is greater or equal to the vector’s current length, this has\nno effect.
The drain method can emulate truncate, but causes the excess\nelements to be returned instead of dropped.
Note that this method has no effect on the allocated capacity\nof the vector.
\nTruncating a five element vector to two elements:
\n\nlet mut vec = vec![1, 2, 3, 4, 5];\nvec.truncate(2);\nassert_eq!(vec, [1, 2]);No truncation occurs when len is greater than the vector’s current\nlength:
let mut vec = vec![1, 2, 3];\nvec.truncate(8);\nassert_eq!(vec, [1, 2, 3]);Truncating when len == 0 is equivalent to calling the clear\nmethod.
let mut vec = vec![1, 2, 3];\nvec.truncate(0);\nassert_eq!(vec, []);Extracts a slice containing the entire vector.
\nEquivalent to &s[..].
use std::io::{self, Write};\nlet buffer = vec![1, 2, 3, 5, 8];\nio::sink().write(buffer.as_slice()).unwrap();Extracts a mutable slice of the entire vector.
\nEquivalent to &mut s[..].
use std::io::{self, Read};\nlet mut buffer = vec![0; 3];\nio::repeat(0b101).read_exact(buffer.as_mut_slice()).unwrap();Returns a raw pointer to the vector’s buffer, or a dangling raw pointer\nvalid for zero sized reads if the vector didn’t allocate.
\nThe caller must ensure that the vector outlives the pointer this\nfunction returns, or else it will end up pointing to garbage.\nModifying the vector may cause its buffer to be reallocated,\nwhich would also make any pointers to it invalid.
\nThe caller must also ensure that the memory the pointer (non-transitively) points to\nis never written to (except inside an UnsafeCell) using this pointer or any pointer\nderived from it. If you need to mutate the contents of the slice, use as_mut_ptr.
This method guarantees that for the purpose of the aliasing model, this method\ndoes not materialize a reference to the underlying slice, and thus the returned pointer\nwill remain valid when mixed with other calls to as_ptr and as_mut_ptr.\nNote that calling other methods that materialize mutable references to the slice,\nor mutable references to specific elements you are planning on accessing through this pointer,\nas well as writing to those elements, may still invalidate this pointer.\nSee the second example below for how this guarantee can be used.
let x = vec![1, 2, 4];\nlet x_ptr = x.as_ptr();\n\nunsafe {\n for i in 0..x.len() {\n assert_eq!(*x_ptr.add(i), 1 << i);\n }\n}Due to the aliasing guarantee, the following code is legal:
\n\nunsafe {\n let mut v = vec![0, 1, 2];\n let ptr1 = v.as_ptr();\n let _ = ptr1.read();\n let ptr2 = v.as_mut_ptr().offset(2);\n ptr2.write(2);\n // Notably, the write to `ptr2` did *not* invalidate `ptr1`\n // because it mutated a different element:\n let _ = ptr1.read();\n}Returns an unsafe mutable pointer to the vector’s buffer, or a dangling\nraw pointer valid for zero sized reads if the vector didn’t allocate.
\nThe caller must ensure that the vector outlives the pointer this\nfunction returns, or else it will end up pointing to garbage.\nModifying the vector may cause its buffer to be reallocated,\nwhich would also make any pointers to it invalid.
\nThis method guarantees that for the purpose of the aliasing model, this method\ndoes not materialize a reference to the underlying slice, and thus the returned pointer\nwill remain valid when mixed with other calls to as_ptr and as_mut_ptr.\nNote that calling other methods that materialize references to the slice,\nor references to specific elements you are planning on accessing through this pointer,\nmay still invalidate this pointer.\nSee the second example below for how this guarantee can be used.
// Allocate vector big enough for 4 elements.\nlet size = 4;\nlet mut x: Vec<i32> = Vec::with_capacity(size);\nlet x_ptr = x.as_mut_ptr();\n\n// Initialize elements via raw pointer writes, then set length.\nunsafe {\n for i in 0..size {\n *x_ptr.add(i) = i as i32;\n }\n x.set_len(size);\n}\nassert_eq!(&*x, &[0, 1, 2, 3]);Due to the aliasing guarantee, the following code is legal:
\n\nunsafe {\n let mut v = vec![0];\n let ptr1 = v.as_mut_ptr();\n ptr1.write(1);\n let ptr2 = v.as_mut_ptr();\n ptr2.write(2);\n // Notably, the write to `ptr2` did *not* invalidate `ptr1`:\n ptr1.write(3);\n}allocator_api)Returns a reference to the underlying allocator.
\nForces the length of the vector to new_len.
This is a low-level operation that maintains none of the normal\ninvariants of the type. Normally changing the length of a vector\nis done using one of the safe operations instead, such as\ntruncate, resize, extend, or clear.
new_len must be less than or equal to capacity().old_len..new_len must be initialized.This method can be useful for situations in which the vector\nis serving as a buffer for other code, particularly over FFI:
\n\npub fn get_dictionary(&self) -> Option<Vec<u8>> {\n // Per the FFI method's docs, \"32768 bytes is always enough\".\n let mut dict = Vec::with_capacity(32_768);\n let mut dict_length = 0;\n // SAFETY: When `deflateGetDictionary` returns `Z_OK`, it holds that:\n // 1. `dict_length` elements were initialized.\n // 2. `dict_length` <= the capacity (32_768)\n // which makes `set_len` safe to call.\n unsafe {\n // Make the FFI call...\n let r = deflateGetDictionary(self.strm, dict.as_mut_ptr(), &mut dict_length);\n if r == Z_OK {\n // ...and update the length to what was initialized.\n dict.set_len(dict_length);\n Some(dict)\n } else {\n None\n }\n }\n}While the following example is sound, there is a memory leak since\nthe inner vectors were not freed prior to the set_len call:
let mut vec = vec![vec![1, 0, 0],\n vec![0, 1, 0],\n vec![0, 0, 1]];\n// SAFETY:\n// 1. `old_len..0` is empty so no elements need to be initialized.\n// 2. `0 <= capacity` always holds whatever `capacity` is.\nunsafe {\n vec.set_len(0);\n}Normally, here, one would use clear instead to correctly drop\nthe contents and thus not leak memory.
Removes an element from the vector and returns it.
\nThe removed element is replaced by the last element of the vector.
\nThis does not preserve ordering of the remaining elements, but is O(1).\nIf you need to preserve the element order, use remove instead.
Panics if index is out of bounds.
let mut v = vec![\"foo\", \"bar\", \"baz\", \"qux\"];\n\nassert_eq!(v.swap_remove(1), \"bar\");\nassert_eq!(v, [\"foo\", \"qux\", \"baz\"]);\n\nassert_eq!(v.swap_remove(0), \"foo\");\nassert_eq!(v, [\"baz\", \"qux\"]);Inserts an element at position index within the vector, shifting all\nelements after it to the right.
Panics if index > len.
let mut vec = vec![1, 2, 3];\nvec.insert(1, 4);\nassert_eq!(vec, [1, 4, 2, 3]);\nvec.insert(4, 5);\nassert_eq!(vec, [1, 4, 2, 3, 5]);Takes O(Vec::len) time. All items after the insertion index must be\nshifted to the right. In the worst case, all elements are shifted when\nthe insertion index is 0.
Removes and returns the element at position index within the vector,\nshifting all elements after it to the left.
Note: Because this shifts over the remaining elements, it has a\nworst-case performance of O(n). If you don’t need the order of elements\nto be preserved, use swap_remove instead. If you’d like to remove\nelements from the beginning of the Vec, consider using\nVecDeque::pop_front instead.
Panics if index is out of bounds.
let mut v = vec![1, 2, 3];\nassert_eq!(v.remove(1), 2);\nassert_eq!(v, [1, 3]);Retains only the elements specified by the predicate.
\nIn other words, remove all elements e for which f(&e) returns false.\nThis method operates in place, visiting each element exactly once in the\noriginal order, and preserves the order of the retained elements.
let mut vec = vec![1, 2, 3, 4];\nvec.retain(|&x| x % 2 == 0);\nassert_eq!(vec, [2, 4]);Because the elements are visited exactly once in the original order,\nexternal state may be used to decide which elements to keep.
\n\nlet mut vec = vec![1, 2, 3, 4, 5];\nlet keep = [false, true, true, false, true];\nlet mut iter = keep.iter();\nvec.retain(|_| *iter.next().unwrap());\nassert_eq!(vec, [2, 3, 5]);Retains only the elements specified by the predicate, passing a mutable reference to it.
\nIn other words, remove all elements e such that f(&mut e) returns false.\nThis method operates in place, visiting each element exactly once in the\noriginal order, and preserves the order of the retained elements.
let mut vec = vec![1, 2, 3, 4];\nvec.retain_mut(|x| if *x <= 3 {\n *x += 1;\n true\n} else {\n false\n});\nassert_eq!(vec, [2, 3, 4]);Removes all but the first of consecutive elements in the vector that resolve to the same\nkey.
\nIf the vector is sorted, this removes all duplicates.
\nlet mut vec = vec![10, 20, 21, 30, 20];\n\nvec.dedup_by_key(|i| *i / 10);\n\nassert_eq!(vec, [10, 20, 30, 20]);Removes all but the first of consecutive elements in the vector satisfying a given equality\nrelation.
\nThe same_bucket function is passed references to two elements from the vector and\nmust determine if the elements compare equal. The elements are passed in opposite order\nfrom their order in the slice, so if same_bucket(a, b) returns true, a is removed.
If the vector is sorted, this removes all duplicates.
\nlet mut vec = vec![\"foo\", \"bar\", \"Bar\", \"baz\", \"bar\"];\n\nvec.dedup_by(|a, b| a.eq_ignore_ascii_case(b));\n\nassert_eq!(vec, [\"foo\", \"bar\", \"baz\", \"bar\"]);Appends an element to the back of a collection.
\nPanics if the new capacity exceeds isize::MAX bytes.
let mut vec = vec![1, 2];\nvec.push(3);\nassert_eq!(vec, [1, 2, 3]);Takes amortized O(1) time. If the vector’s length would exceed its\ncapacity after the push, O(capacity) time is taken to copy the\nvector’s elements to a larger allocation. This expensive operation is\noffset by the capacity O(1) insertions it allows.
\nvec_push_within_capacity)Appends an element if there is sufficient spare capacity, otherwise an error is returned\nwith the element.
\nUnlike push this method will not reallocate when there’s insufficient capacity.\nThe caller should use reserve or try_reserve to ensure that there is enough capacity.
A manual, panic-free alternative to FromIterator:
#![feature(vec_push_within_capacity)]\n\nuse std::collections::TryReserveError;\nfn from_iter_fallible<T>(iter: impl Iterator<Item=T>) -> Result<Vec<T>, TryReserveError> {\n let mut vec = Vec::new();\n for value in iter {\n if let Err(value) = vec.push_within_capacity(value) {\n vec.try_reserve(1)?;\n // this cannot fail, the previous line either returned or added at least 1 free slot\n let _ = vec.push_within_capacity(value);\n }\n }\n Ok(vec)\n}\nassert_eq!(from_iter_fallible(0..100), Ok(Vec::from_iter(0..100)));Takes O(1) time.
\nRemoves the last element from a vector and returns it, or None if it\nis empty.
If you’d like to pop the first element, consider using\nVecDeque::pop_front instead.
let mut vec = vec![1, 2, 3];\nassert_eq!(vec.pop(), Some(3));\nassert_eq!(vec, [1, 2]);Takes O(1) time.
\nvec_pop_if)Removes and returns the last element in a vector if the predicate\nreturns true, or None if the predicate returns false or the vector\nis empty.
#![feature(vec_pop_if)]\n\nlet mut vec = vec![1, 2, 3, 4];\nlet pred = |x: &mut i32| *x % 2 == 0;\n\nassert_eq!(vec.pop_if(pred), Some(4));\nassert_eq!(vec, [1, 2, 3]);\nassert_eq!(vec.pop_if(pred), None);Removes the specified range from the vector in bulk, returning all\nremoved elements as an iterator. If the iterator is dropped before\nbeing fully consumed, it drops the remaining removed elements.
\nThe returned iterator keeps a mutable borrow on the vector to optimize\nits implementation.
\nPanics if the starting point is greater than the end point or if\nthe end point is greater than the length of the vector.
\nIf the returned iterator goes out of scope without being dropped (due to\nmem::forget, for example), the vector may have lost and leaked\nelements arbitrarily, including elements outside the range.
let mut v = vec![1, 2, 3];\nlet u: Vec<_> = v.drain(1..).collect();\nassert_eq!(v, &[1]);\nassert_eq!(u, &[2, 3]);\n\n// A full range clears the vector, like `clear()` does\nv.drain(..);\nassert_eq!(v, &[]);Clears the vector, removing all values.
\nNote that this method has no effect on the allocated capacity\nof the vector.
\nlet mut v = vec![1, 2, 3];\n\nv.clear();\n\nassert!(v.is_empty());Returns the number of elements in the vector, also referred to\nas its ‘length’.
\nlet a = vec![1, 2, 3];\nassert_eq!(a.len(), 3);Returns true if the vector contains no elements.
let mut v = Vec::new();\nassert!(v.is_empty());\n\nv.push(1);\nassert!(!v.is_empty());Splits the collection into two at the given index.
\nReturns a newly allocated vector containing the elements in the range\n[at, len). After the call, the original vector will be left containing\nthe elements [0, at) with its previous capacity unchanged.
mem::take or mem::replace.Vec::truncate.Vec::drain.Panics if at > len.
let mut vec = vec![1, 2, 3];\nlet vec2 = vec.split_off(1);\nassert_eq!(vec, [1]);\nassert_eq!(vec2, [2, 3]);Resizes the Vec in-place so that len is equal to new_len.
If new_len is greater than len, the Vec is extended by the\ndifference, with each additional slot filled with the result of\ncalling the closure f. The return values from f will end up\nin the Vec in the order they have been generated.
If new_len is less than len, the Vec is simply truncated.
This method uses a closure to create new values on every push. If\nyou’d rather Clone a given value, use Vec::resize. If you\nwant to use the Default trait to generate values, you can\npass Default::default as the second argument.
let mut vec = vec![1, 2, 3];\nvec.resize_with(5, Default::default);\nassert_eq!(vec, [1, 2, 3, 0, 0]);\n\nlet mut vec = vec![];\nlet mut p = 1;\nvec.resize_with(4, || { p *= 2; p });\nassert_eq!(vec, [2, 4, 8, 16]);Consumes and leaks the Vec, returning a mutable reference to the contents,\n&'a mut [T]. Note that the type T must outlive the chosen lifetime\n'a. If the type has only static references, or none at all, then this\nmay be chosen to be 'static.
As of Rust 1.57, this method does not reallocate or shrink the Vec,\nso the leaked allocation may include unused capacity that is not part\nof the returned slice.
This function is mainly useful for data that lives for the remainder of\nthe program’s life. Dropping the returned reference will cause a memory\nleak.
\nSimple usage:
\n\nlet x = vec![1, 2, 3];\nlet static_ref: &'static mut [usize] = x.leak();\nstatic_ref[0] += 1;\nassert_eq!(static_ref, &[2, 2, 3]);Returns the remaining spare capacity of the vector as a slice of\nMaybeUninit<T>.
The returned slice can be used to fill the vector with data (e.g. by\nreading from a file) before marking the data as initialized using the\nset_len method.
// Allocate vector big enough for 10 elements.\nlet mut v = Vec::with_capacity(10);\n\n// Fill in the first 3 elements.\nlet uninit = v.spare_capacity_mut();\nuninit[0].write(0);\nuninit[1].write(1);\nuninit[2].write(2);\n\n// Mark the first 3 elements of the vector as being initialized.\nunsafe {\n v.set_len(3);\n}\n\nassert_eq!(&v, &[0, 1, 2]);vec_split_at_spare)Returns vector content as a slice of T, along with the remaining spare\ncapacity of the vector as a slice of MaybeUninit<T>.
The returned spare capacity slice can be used to fill the vector with data\n(e.g. by reading from a file) before marking the data as initialized using\nthe set_len method.
Note that this is a low-level API, which should be used with care for\noptimization purposes. If you need to append data to a Vec\nyou can use push, extend, extend_from_slice,\nextend_from_within, insert, append, resize or\nresize_with, depending on your exact needs.
#![feature(vec_split_at_spare)]\n\nlet mut v = vec![1, 1, 2];\n\n// Reserve additional space big enough for 10 elements.\nv.reserve(10);\n\nlet (init, uninit) = v.split_at_spare_mut();\nlet sum = init.iter().copied().sum::<u32>();\n\n// Fill in the next 4 elements.\nuninit[0].write(sum);\nuninit[1].write(sum * 2);\nuninit[2].write(sum * 3);\nuninit[3].write(sum * 4);\n\n// Mark the 4 elements of the vector as being initialized.\nunsafe {\n let len = v.len();\n v.set_len(len + 4);\n}\n\nassert_eq!(&v, &[1, 1, 2, 4, 8, 12, 16]);Self from the given unstructured data. Read moreUnstructured this type\nneeds to construct itself. Read moreSelf from the entirety of the given\nunstructured data. Read moreTakes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err occur, a\ncontainer with the values of each Result is returned.
Here is an example which increments every integer in a vector,\nchecking for overflow:
\n\nlet v = vec![1, 2];\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|\n x.checked_add(1).ok_or(\"Overflow!\")\n).collect();\nassert_eq!(res, Ok(vec![2, 3]));Here is another example that tries to subtract one from another list\nof integers, this time checking for underflow:
\n\nlet v = vec![1, 2, 0];\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32|\n x.checked_sub(1).ok_or(\"Underflow!\")\n).collect();\nassert_eq!(res, Err(\"Underflow!\"));Here is a variation on the previous example, showing that no\nfurther elements are taken from iter after the first Err.
let v = vec![3, 2, 1, 10];\nlet mut shared = 0;\nlet res: Result<Vec<u32>, &'static str> = v.iter().map(|x: &u32| {\n shared += x;\n x.checked_sub(2).ok_or(\"Underflow!\")\n}).collect();\nassert_eq!(res, Err(\"Underflow!\"));\nassert_eq!(shared, 6);Since the third element caused an underflow, no further elements were taken,\nso the final value of shared is 6 (= 3 + 2 + 1), not 16.
try_trait_v2)Residual type. Read moreReturns a consuming iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let x: Result<u32, &str> = Ok(5);\nlet v: Vec<u32> = x.into_iter().collect();\nassert_eq!(v, [5]);\n\nlet x: Result<u32, &str> = Err(\"nothing!\");\nlet v: Vec<u32> = x.into_iter().collect();\nassert_eq!(v, []);self and other) and is used by the <=\noperator. Read moreTakes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err\noccur, the product of all elements is returned.
This multiplies each number in a vector of strings,\nif a string could not be parsed the operation returns Err:
let nums = vec![\"5\", \"10\", \"1\", \"2\"];\nlet total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();\nassert_eq!(total, Ok(100));\nlet nums = vec![\"5\", \"10\", \"one\", \"2\"];\nlet total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();\nassert!(total.is_err());Maps a Result<&mut T, E> to a Result<T, E> by copying the contents of the\nOk part.
let mut val = 12;\nlet x: Result<&mut i32, i32> = Ok(&mut val);\nassert_eq!(x, Ok(&mut 12));\nlet copied = x.copied();\nassert_eq!(copied, Ok(12));Maps a Result<&mut T, E> to a Result<T, E> by cloning the contents of the\nOk part.
let mut val = 12;\nlet x: Result<&mut i32, i32> = Ok(&mut val);\nassert_eq!(x, Ok(&mut 12));\nlet cloned = x.cloned();\nassert_eq!(cloned, Ok(12));Transposes a Result of an Option into an Option of a Result.
Ok(None) will be mapped to None.\nOk(Some(_)) and Err(_) will be mapped to Some(Ok(_)) and Some(Err(_)).
#[derive(Debug, Eq, PartialEq)]\nstruct SomeErr;\n\nlet x: Result<Option<i32>, SomeErr> = Ok(Some(5));\nlet y: Option<Result<i32, SomeErr>> = Some(Ok(5));\nassert_eq!(x.transpose(), y);result_flattening)Converts from Result<Result<T, E>, E> to Result<T, E>
#![feature(result_flattening)]\nlet x: Result<Result<&'static str, u32>, u32> = Ok(Ok(\"hello\"));\nassert_eq!(Ok(\"hello\"), x.flatten());\n\nlet x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));\nassert_eq!(Err(6), x.flatten());\n\nlet x: Result<Result<&'static str, u32>, u32> = Err(6);\nassert_eq!(Err(6), x.flatten());Flattening only removes one level of nesting at a time:
\n\n#![feature(result_flattening)]\nlet x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok(\"hello\")));\nassert_eq!(Ok(Ok(\"hello\")), x.flatten());\nassert_eq!(Ok(\"hello\"), x.flatten().flatten());Returns true if the result is Ok and the value inside of it matches a predicate.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.is_ok_and(|x| x > 1), true);\n\nlet x: Result<u32, &str> = Ok(0);\nassert_eq!(x.is_ok_and(|x| x > 1), false);\n\nlet x: Result<u32, &str> = Err(\"hey\");\nassert_eq!(x.is_ok_and(|x| x > 1), false);Returns true if the result is Err and the value inside of it matches a predicate.
use std::io::{Error, ErrorKind};\n\nlet x: Result<u32, Error> = Err(Error::new(ErrorKind::NotFound, \"!\"));\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), true);\n\nlet x: Result<u32, Error> = Err(Error::new(ErrorKind::PermissionDenied, \"!\"));\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);\n\nlet x: Result<u32, Error> = Ok(123);\nassert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false);Converts from Result<T, E> to Option<E>.
Converts self into an Option<E>, consuming self,\nand discarding the success value, if any.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.err(), None);\n\nlet x: Result<u32, &str> = Err(\"Nothing here\");\nassert_eq!(x.err(), Some(\"Nothing here\"));Converts from &Result<T, E> to Result<&T, &E>.
Produces a new Result, containing a reference\ninto the original, leaving the original in place.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(x.as_ref(), Ok(&2));\n\nlet x: Result<u32, &str> = Err(\"Error\");\nassert_eq!(x.as_ref(), Err(&\"Error\"));Converts from &mut Result<T, E> to Result<&mut T, &mut E>.
fn mutate(r: &mut Result<i32, i32>) {\n match r.as_mut() {\n Ok(v) => *v = 42,\n Err(e) => *e = 0,\n }\n}\n\nlet mut x: Result<i32, i32> = Ok(2);\nmutate(&mut x);\nassert_eq!(x.unwrap(), 42);\n\nlet mut x: Result<i32, i32> = Err(13);\nmutate(&mut x);\nassert_eq!(x.unwrap_err(), 0);Maps a Result<T, E> to Result<U, E> by applying a function to a\ncontained Ok value, leaving an Err value untouched.
This function can be used to compose the results of two functions.
\nPrint the numbers on each line of a string multiplied by two.
\n\nlet line = \"1\\n2\\n3\\n4\\n\";\n\nfor num in line.lines() {\n match num.parse::<i32>().map(|i| i * 2) {\n Ok(n) => println!(\"{n}\"),\n Err(..) => {}\n }\n}Returns the provided default (if Err), or\napplies a function to the contained value (if Ok).
Arguments passed to map_or are eagerly evaluated; if you are passing\nthe result of a function call, it is recommended to use map_or_else,\nwhich is lazily evaluated.
let x: Result<_, &str> = Ok(\"foo\");\nassert_eq!(x.map_or(42, |v| v.len()), 3);\n\nlet x: Result<&str, _> = Err(\"bar\");\nassert_eq!(x.map_or(42, |v| v.len()), 42);Maps a Result<T, E> to U by applying fallback function default to\na contained Err value, or function f to a contained Ok value.
This function can be used to unpack a successful result\nwhile handling an error.
\nlet k = 21;\n\nlet x : Result<_, &str> = Ok(\"foo\");\nassert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 3);\n\nlet x : Result<&str, _> = Err(\"bar\");\nassert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 42);Maps a Result<T, E> to Result<T, F> by applying a function to a\ncontained Err value, leaving an Ok value untouched.
This function can be used to pass through a successful result while handling\nan error.
\nfn stringify(x: u32) -> String { format!(\"error code: {x}\") }\n\nlet x: Result<u32, u32> = Ok(2);\nassert_eq!(x.map_err(stringify), Ok(2));\n\nlet x: Result<u32, u32> = Err(13);\nassert_eq!(x.map_err(stringify), Err(\"error code: 13\".to_string()));Converts from Result<T, E> (or &Result<T, E>) to Result<&<T as Deref>::Target, &E>.
Coerces the Ok variant of the original Result via Deref\nand returns the new Result.
let x: Result<String, u32> = Ok(\"hello\".to_string());\nlet y: Result<&str, &u32> = Ok(\"hello\");\nassert_eq!(x.as_deref(), y);\n\nlet x: Result<String, u32> = Err(42);\nlet y: Result<&str, &u32> = Err(&42);\nassert_eq!(x.as_deref(), y);Converts from Result<T, E> (or &mut Result<T, E>) to Result<&mut <T as DerefMut>::Target, &mut E>.
Coerces the Ok variant of the original Result via DerefMut\nand returns the new Result.
let mut s = \"HELLO\".to_string();\nlet mut x: Result<String, u32> = Ok(\"hello\".to_string());\nlet y: Result<&mut str, &mut u32> = Ok(&mut s);\nassert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);\n\nlet mut i = 42;\nlet mut x: Result<String, u32> = Err(42);\nlet y: Result<&mut str, &mut u32> = Err(&mut i);\nassert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y);Returns an iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let x: Result<u32, &str> = Ok(7);\nassert_eq!(x.iter().next(), Some(&7));\n\nlet x: Result<u32, &str> = Err(\"nothing!\");\nassert_eq!(x.iter().next(), None);Returns a mutable iterator over the possibly contained value.
\nThe iterator yields one value if the result is Result::Ok, otherwise none.
let mut x: Result<u32, &str> = Ok(7);\nmatch x.iter_mut().next() {\n Some(v) => *v = 40,\n None => {},\n}\nassert_eq!(x, Ok(40));\n\nlet mut x: Result<u32, &str> = Err(\"nothing!\");\nassert_eq!(x.iter_mut().next(), None);Returns the contained Ok value, consuming the self value.
Because this function may panic, its use is generally discouraged.\nInstead, prefer to use pattern matching and handle the Err\ncase explicitly, or call unwrap_or, unwrap_or_else, or\nunwrap_or_default.
Panics if the value is an Err, with a panic message including the\npassed message, and the content of the Err.
let x: Result<u32, &str> = Err(\"emergency failure\");\nx.expect(\"Testing expect\"); // panics with `Testing expect: emergency failure`We recommend that expect messages are used to describe the reason you\nexpect the Result should be Ok.
let path = std::env::var(\"IMPORTANT_PATH\")\n .expect(\"env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`\");Hint: If you’re having trouble remembering how to phrase expect\nerror messages remember to focus on the word “should” as in “env\nvariable should be set by blah” or “the given binary should be available\nand executable by the current user”.
\nFor more detail on expect message styles and the reasoning behind our recommendation please\nrefer to the section on “Common Message\nStyles” in the\nstd::error module docs.
Returns the contained Ok value, consuming the self value.
Because this function may panic, its use is generally discouraged.\nInstead, prefer to use pattern matching and handle the Err\ncase explicitly, or call unwrap_or, unwrap_or_else, or\nunwrap_or_default.
Panics if the value is an Err, with a panic message provided by the\nErr’s value.
Basic usage:
\n\nlet x: Result<u32, &str> = Ok(2);\nassert_eq!(x.unwrap(), 2);let x: Result<u32, &str> = Err(\"emergency failure\");\nx.unwrap(); // panics with `emergency failure`Returns the contained Ok value or a default
Consumes the self argument then, if Ok, returns the contained\nvalue, otherwise if Err, returns the default value for that\ntype.
Converts a string to an integer, turning poorly-formed strings\ninto 0 (the default value for integers). parse converts\na string to any other type that implements FromStr, returning an\nErr on error.
let good_year_from_input = \"1909\";\nlet bad_year_from_input = \"190blarg\";\nlet good_year = good_year_from_input.parse().unwrap_or_default();\nlet bad_year = bad_year_from_input.parse().unwrap_or_default();\n\nassert_eq!(1909, good_year);\nassert_eq!(0, bad_year);Returns the contained Err value, consuming the self value.
Panics if the value is an Ok, with a panic message including the\npassed message, and the content of the Ok.
let x: Result<u32, &str> = Ok(10);\nx.expect_err(\"Testing expect_err\"); // panics with `Testing expect_err: 10`Returns the contained Err value, consuming the self value.
Panics if the value is an Ok, with a custom panic message provided\nby the Ok’s value.
let x: Result<u32, &str> = Ok(2);\nx.unwrap_err(); // panics with `2`let x: Result<u32, &str> = Err(\"emergency failure\");\nassert_eq!(x.unwrap_err(), \"emergency failure\");unwrap_infallible)Returns the contained Ok value, but never panics.
Unlike unwrap, this method is known to never panic on the\nresult types it is implemented for. Therefore, it can be used\ninstead of unwrap as a maintainability safeguard that will fail\nto compile if the error type of the Result is later changed\nto an error that can actually occur.
\nfn only_good_news() -> Result<String, !> {\n Ok(\"this is fine\".into())\n}\n\nlet s: String = only_good_news().into_ok();\nprintln!(\"{s}\");unwrap_infallible)Returns the contained Err value, but never panics.
Unlike unwrap_err, this method is known to never panic on the\nresult types it is implemented for. Therefore, it can be used\ninstead of unwrap_err as a maintainability safeguard that will fail\nto compile if the ok type of the Result is later changed\nto a type that can actually occur.
\nfn only_bad_news() -> Result<!, String> {\n Err(\"Oops, it failed\".into())\n}\n\nlet error: String = only_bad_news().into_err();\nprintln!(\"{error}\");Returns res if the result is Ok, otherwise returns the Err value of self.
Arguments passed to and are eagerly evaluated; if you are passing the\nresult of a function call, it is recommended to use and_then, which is\nlazily evaluated.
let x: Result<u32, &str> = Ok(2);\nlet y: Result<&str, &str> = Err(\"late error\");\nassert_eq!(x.and(y), Err(\"late error\"));\n\nlet x: Result<u32, &str> = Err(\"early error\");\nlet y: Result<&str, &str> = Ok(\"foo\");\nassert_eq!(x.and(y), Err(\"early error\"));\n\nlet x: Result<u32, &str> = Err(\"not a 2\");\nlet y: Result<&str, &str> = Err(\"late error\");\nassert_eq!(x.and(y), Err(\"not a 2\"));\n\nlet x: Result<u32, &str> = Ok(2);\nlet y: Result<&str, &str> = Ok(\"different result type\");\nassert_eq!(x.and(y), Ok(\"different result type\"));Calls op if the result is Ok, otherwise returns the Err value of self.
This function can be used for control flow based on Result values.
fn sq_then_to_string(x: u32) -> Result<String, &'static str> {\n x.checked_mul(x).map(|sq| sq.to_string()).ok_or(\"overflowed\")\n}\n\nassert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string()));\nassert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err(\"overflowed\"));\nassert_eq!(Err(\"not a number\").and_then(sq_then_to_string), Err(\"not a number\"));Often used to chain fallible operations that may return Err.
use std::{io::ErrorKind, path::Path};\n\n// Note: on Windows \"/\" maps to \"C:\\\"\nlet root_modified_time = Path::new(\"/\").metadata().and_then(|md| md.modified());\nassert!(root_modified_time.is_ok());\n\nlet should_fail = Path::new(\"/bad/path\").metadata().and_then(|md| md.modified());\nassert!(should_fail.is_err());\nassert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);Returns res if the result is Err, otherwise returns the Ok value of self.
Arguments passed to or are eagerly evaluated; if you are passing the\nresult of a function call, it is recommended to use or_else, which is\nlazily evaluated.
let x: Result<u32, &str> = Ok(2);\nlet y: Result<u32, &str> = Err(\"late error\");\nassert_eq!(x.or(y), Ok(2));\n\nlet x: Result<u32, &str> = Err(\"early error\");\nlet y: Result<u32, &str> = Ok(2);\nassert_eq!(x.or(y), Ok(2));\n\nlet x: Result<u32, &str> = Err(\"not a 2\");\nlet y: Result<u32, &str> = Err(\"late error\");\nassert_eq!(x.or(y), Err(\"late error\"));\n\nlet x: Result<u32, &str> = Ok(2);\nlet y: Result<u32, &str> = Ok(100);\nassert_eq!(x.or(y), Ok(2));Calls op if the result is Err, otherwise returns the Ok value of self.
This function can be used for control flow based on result values.
\nfn sq(x: u32) -> Result<u32, u32> { Ok(x * x) }\nfn err(x: u32) -> Result<u32, u32> { Err(x) }\n\nassert_eq!(Ok(2).or_else(sq).or_else(sq), Ok(2));\nassert_eq!(Ok(2).or_else(err).or_else(sq), Ok(2));\nassert_eq!(Err(3).or_else(sq).or_else(err), Ok(9));\nassert_eq!(Err(3).or_else(err).or_else(err), Err(3));Returns the contained Ok value or a provided default.
Arguments passed to unwrap_or are eagerly evaluated; if you are passing\nthe result of a function call, it is recommended to use unwrap_or_else,\nwhich is lazily evaluated.
let default = 2;\nlet x: Result<u32, &str> = Ok(9);\nassert_eq!(x.unwrap_or(default), 9);\n\nlet x: Result<u32, &str> = Err(\"error\");\nassert_eq!(x.unwrap_or(default), default);Returns the contained Ok value, consuming the self value,\nwithout checking that the value is not an Err.
Calling this method on an Err is undefined behavior.
let x: Result<u32, &str> = Ok(2);\nassert_eq!(unsafe { x.unwrap_unchecked() }, 2);let x: Result<u32, &str> = Err(\"emergency failure\");\nunsafe { x.unwrap_unchecked(); } // Undefined behavior!Returns the contained Err value, consuming the self value,\nwithout checking that the value is not an Ok.
Calling this method on an Ok is undefined behavior.
let x: Result<u32, &str> = Ok(2);\nunsafe { x.unwrap_err_unchecked() }; // Undefined behavior!let x: Result<u32, &str> = Err(\"emergency failure\");\nassert_eq!(unsafe { x.unwrap_err_unchecked() }, \"emergency failure\");Takes each element in the Iterator: if it is an Err, no further\nelements are taken, and the Err is returned. Should no Err\noccur, the sum of all elements is returned.
This sums up every integer in a vector, rejecting the sum if a negative\nelement is encountered:
\n\nlet f = |&x: &i32| if x < 0 { Err(\"Negative element found\") } else { Ok(x) };\nlet v = vec![1, 2];\nlet res: Result<i32, _> = v.iter().map(f).sum();\nassert_eq!(res, Ok(3));\nlet v = vec![1, -2];\nlet res: Result<i32, _> = v.iter().map(f).sum();\nassert_eq!(res, Err(\"Negative element found\"));try_trait_v2)? when not short-circuiting.try_trait_v2)FromResidual::from_residual\nas part of ? when short-circuiting. Read moretry_trait_v2)Output type. Read moretry_trait_v2)? to decide whether the operator should produce a value\n(because this returned ControlFlow::Continue)\nor propagate a value back to the caller\n(because this returned ControlFlow::Break). Read moretry_default in case the value is null or\nundefined.source. Read moretry_default in case the value is null or\nundefined.Returns true if the event indicates that the message was successfully processed.
\nself and other values to be equal, and is used\nby ==.Returns an array of the same size as self, with function f applied to each element\nin order.
If you don’t necessarily need a new fixed-size array, consider using\nIterator::map instead.
Unfortunately, usages of this method are currently not always optimized\nas well as they could be. This mainly concerns large arrays, as mapping\nover small arrays seem to be optimized just fine. Also note that in\ndebug mode (i.e. without any optimizations), this method can use a lot\nof stack space (a few times the size of the array or more).
\nTherefore, in performance-critical code, try to avoid using this method\non large arrays or check the emitted code. Also try to avoid chained\nmaps (e.g. arr.map(...).map(...)).
In many cases, you can instead use Iterator::map by calling .iter()\nor .into_iter() on your array. [T; N]::map is only necessary if you\nreally need a new array of the same size as the result. Rust’s lazy\niterators tend to get optimized very well.
let x = [1, 2, 3];\nlet y = x.map(|v| v + 1);\nassert_eq!(y, [2, 3, 4]);\n\nlet x = [1, 2, 3];\nlet mut temp = 0;\nlet y = x.map(|v| { temp += 1; v * temp });\nassert_eq!(y, [1, 4, 9]);\n\nlet x = [\"Ferris\", \"Bueller's\", \"Day\", \"Off\"];\nlet y = x.map(|v| v.len());\nassert_eq!(y, [6, 9, 3, 3]);array_try_map)A fallible function f applied to each element on array self in order to\nreturn an array the same size as self or the first error encountered.
The return type of this function depends on the return type of the closure.\nIf you return Result<T, E> from the closure, you’ll get a Result<[T; N], E>.\nIf you return Option<T> from the closure, you’ll get an Option<[T; N]>.
#![feature(array_try_map)]\n\nlet a = [\"1\", \"2\", \"3\"];\nlet b = a.try_map(|v| v.parse::<u32>()).unwrap().map(|v| v + 1);\nassert_eq!(b, [2, 3, 4]);\n\nlet a = [\"1\", \"2a\", \"3\"];\nlet b = a.try_map(|v| v.parse::<u32>());\nassert!(b.is_err());\n\nuse std::num::NonZero;\n\nlet z = [1, 2, 0, 3, 4];\nassert_eq!(z.try_map(NonZero::new), None);\n\nlet a = [1, 2, 3];\nlet b = a.try_map(NonZero::new);\nlet c = b.map(|x| x.map(NonZero::get));\nassert_eq!(c, Some(a));Returns a slice containing the entire array. Equivalent to &s[..].
Returns a mutable slice containing the entire array. Equivalent to\n&mut s[..].
Borrows each element and returns an array of references with the same\nsize as self.
let floats = [3.1, 2.7, -1.0];\nlet float_refs: [&f64; 3] = floats.each_ref();\nassert_eq!(float_refs, [&3.1, &2.7, &-1.0]);This method is particularly useful if combined with other methods, like\nmap. This way, you can avoid moving the original\narray if its elements are not Copy.
let strings = [\"Ferris\".to_string(), \"♥\".to_string(), \"Rust\".to_string()];\nlet is_ascii = strings.each_ref().map(|s| s.is_ascii());\nassert_eq!(is_ascii, [true, false, true]);\n\n// We can still access the original array: it has not been moved.\nassert_eq!(strings.len(), 3);Borrows each element mutably and returns an array of mutable references\nwith the same size as self.
\nlet mut floats = [3.1, 2.7, -1.0];\nlet float_refs: [&mut f64; 3] = floats.each_mut();\n*float_refs[0] = 0.0;\nassert_eq!(float_refs, [&mut 0.0, &mut 2.7, &mut -1.0]);\nassert_eq!(floats, [0.0, 2.7, -1.0]);split_array)Divides one array reference into two at an index.
\nThe first will contain all indices from [0, M) (excluding\nthe index M itself) and the second will contain all\nindices from [M, N) (excluding the index N itself).
Panics if M > N.
#![feature(split_array)]\n\nlet v = [1, 2, 3, 4, 5, 6];\n\n{\n let (left, right) = v.split_array_ref::<0>();\n assert_eq!(left, &[]);\n assert_eq!(right, &[1, 2, 3, 4, 5, 6]);\n}\n\n{\n let (left, right) = v.split_array_ref::<2>();\n assert_eq!(left, &[1, 2]);\n assert_eq!(right, &[3, 4, 5, 6]);\n}\n\n{\n let (left, right) = v.split_array_ref::<6>();\n assert_eq!(left, &[1, 2, 3, 4, 5, 6]);\n assert_eq!(right, &[]);\n}split_array)Divides one mutable array reference into two at an index.
\nThe first will contain all indices from [0, M) (excluding\nthe index M itself) and the second will contain all\nindices from [M, N) (excluding the index N itself).
Panics if M > N.
#![feature(split_array)]\n\nlet mut v = [1, 0, 3, 0, 5, 6];\nlet (left, right) = v.split_array_mut::<2>();\nassert_eq!(left, &mut [1, 0][..]);\nassert_eq!(right, &mut [3, 0, 5, 6]);\nleft[1] = 2;\nright[1] = 4;\nassert_eq!(v, [1, 2, 3, 4, 5, 6]);split_array)Divides one array reference into two at an index from the end.
\nThe first will contain all indices from [0, N - M) (excluding\nthe index N - M itself) and the second will contain all\nindices from [N - M, N) (excluding the index N itself).
Panics if M > N.
#![feature(split_array)]\n\nlet v = [1, 2, 3, 4, 5, 6];\n\n{\n let (left, right) = v.rsplit_array_ref::<0>();\n assert_eq!(left, &[1, 2, 3, 4, 5, 6]);\n assert_eq!(right, &[]);\n}\n\n{\n let (left, right) = v.rsplit_array_ref::<2>();\n assert_eq!(left, &[1, 2, 3, 4]);\n assert_eq!(right, &[5, 6]);\n}\n\n{\n let (left, right) = v.rsplit_array_ref::<6>();\n assert_eq!(left, &[]);\n assert_eq!(right, &[1, 2, 3, 4, 5, 6]);\n}split_array)Divides one mutable array reference into two at an index from the end.
\nThe first will contain all indices from [0, N - M) (excluding\nthe index N - M itself) and the second will contain all\nindices from [N - M, N) (excluding the index N itself).
Panics if M > N.
#![feature(split_array)]\n\nlet mut v = [1, 0, 3, 0, 5, 6];\nlet (left, right) = v.rsplit_array_mut::<4>();\nassert_eq!(left, &mut [1, 0]);\nassert_eq!(right, &mut [3, 0, 5, 6][..]);\nleft[1] = 2;\nright[1] = 4;\nassert_eq!(v, [1, 2, 3, 4, 5, 6]);ascii_char)Converts this array of bytes into a array of ASCII characters,\nor returns None if any of the characters is non-ASCII.
#![feature(ascii_char)]\n#![feature(const_option)]\n\nconst HEX_DIGITS: [std::ascii::Char; 16] =\n *b\"0123456789abcdef\".as_ascii().unwrap();\n\nassert_eq!(HEX_DIGITS[1].as_str(), \"1\");\nassert_eq!(HEX_DIGITS[10].as_str(), \"a\");ascii_char)Converts this array of bytes into a array of ASCII characters,\nwithout checking whether they’re valid.
\nEvery byte in the array must be in 0..=127, or else this is UB.
Self from the given unstructured data. Read moreSelf from the entirety of the given\nunstructured data. Read moretry_default in case the value is null or\nundefined.try_default in case the value is null or\nundefined.Reader].