Merge pull request #1758 from radixdlt/documentation/update-readmes

Documentation: Add md-book documentation + Rustdocs

radix-blueprint-schema-init/src/lib.rs

@@ -27,15 +27,23 @@ pub enum BlueprintHook {
     OnDrop,
 }
 
+/// An initialization object which describes a blueprint's schema including interface, state, and events
 #[derive(Debug, Clone, PartialEq, Eq, ScryptoSbor, ManifestSbor)]
 pub struct BlueprintSchemaInit {
+    /// List of generic parameters which must be provided on component instantiation and the bounds of these generics
     pub generics: Vec<GenericBound>,
+    /// Sbor schema which describes various types, each identified by a usize
     pub schema: VersionedScryptoSchema,
+    /// Describes schema of state by mapping fields/collection indices as a generic or directly into the Sbor schema
     pub state: BlueprintStateSchemaInit,
+    /// Describes schema of events by mapping event names as a generic or directly into the Sbor schema
     pub events: BlueprintEventSchemaInit,
-    /// Registered types for generic substitution
+    /// Describes schema of types by mapping types names directly into the Sbor schema
+    /// These types are used for external generic substitution
     pub types: BlueprintTypeSchemaInit,
+    /// Describes interface of function by mapping function names to input/output schema and the code exported function name it maps to
     pub functions: BlueprintFunctionsSchemaInit,
+    /// Maps hooks to a code exported function name
     pub hooks: BlueprintHooksInit,
 }
 
@@ -58,6 +66,8 @@ impl Default for BlueprintSchemaInit {
     }
 }
 
+/// Describes the fields and collections some Blueprint has as well
+/// as the schema and properties of each field and collection
 #[derive(Debug, Clone, PartialEq, Eq, Default, ScryptoSbor, ManifestSbor)]
 pub struct BlueprintStateSchemaInit {
     pub fields: Vec<FieldSchema<TypeRef<LocalTypeId>>>,
@@ -170,6 +180,7 @@ pub trait BlueprintFeature {
     fn feature_name(&self) -> &'static str;
 }
 
+/// Expresses a condition based on features enabled on a component
 #[derive(Debug, Clone, PartialEq, Eq, Sbor)]
 pub enum Condition {
     Always,
@@ -197,10 +208,13 @@ pub enum FieldTransience {
     },
 }
 
+/// Describes a field for a Blueprint
 #[derive(Debug, Clone, PartialEq, Eq, ScryptoSbor, ManifestSbor)]
 pub struct FieldSchema<V> {
     pub field: V,
+    /// Condition for this field to exist
     pub condition: Condition,
+    /// Describes if this field should be persisted
     pub transience: FieldTransience,
 }
 

radix-engine-interface/src/api/actor_key_value_entry_api.rs

@@ -5,7 +5,8 @@ use sbor::rust::fmt::Debug;
 use sbor::rust::vec::Vec;
 
 pub trait SystemActorKeyValueEntryApi<E: Debug> {
-    /// If the key value entry doesn't exist, it uses the default "Option::None"
+    /// Returns a handle for a specified key value entry in a collection. If an invalid collection
+    /// index or key is passed an error is returned.
     fn actor_open_key_value_entry(
         &mut self,
         object_handle: ActorStateHandle,
@@ -14,13 +15,17 @@ pub trait SystemActorKeyValueEntryApi<E: Debug> {
         flags: LockFlags,
     ) -> Result<KeyValueEntryHandle, E>;
 
+    /// Removes an entry from a collection. If an invalid collection index or key is passed an
+    /// error is returned, otherwise the encoding of a value of the entry is returned.
     fn actor_remove_key_value_entry(
         &mut self,
         object_handle: ActorStateHandle,
         collection_index: CollectionIndex,
         key: &Vec<u8>,
     ) -> Result<Vec<u8>, E>;
 
+    /// Removes an entry from a collection. If an invalid collection index or key is passed an
+    /// error is returned, otherwise the value of the entry is returned.
     fn actor_remove_key_value_entry_typed<V: ScryptoDecode>(
         &mut self,
         object_handle: ActorStateHandle,

radix-engine-interface/src/api/actor_sorted_index_api.rs

@@ -5,9 +5,6 @@ use radix_engine_interface::api::CollectionIndex;
 use sbor::rust::prelude::*;
 use sbor::rust::vec::Vec;
 
-pub trait SortedIndexKeyPayloadMarker {}
-pub trait SortedIndexEntryPayloadMarker {}
-
 pub trait SystemActorSortedIndexApi<E> {
     /// Inserts an entry into a sorted index
     fn actor_sorted_index_insert(

radix-engine-interface/src/api/blueprint_api.rs

@@ -13,6 +13,7 @@ pub trait SystemBlueprintApi<E> {
         args: Vec<u8>,
     ) -> Result<Vec<u8>, E>;
 
+    /// Retrieves the schema of type under a blueprint
     fn resolve_blueprint_type(
         &mut self,
         blueprint_type_id: &BlueprintTypeIdentifier,

radix-engine-interface/src/api/costing_api.rs

@@ -9,21 +9,30 @@ pub trait SystemCostingApi<E> {
     /// Add cost units to the reserve. This should never fail.
     fn lock_fee(&mut self, locked_fee: LiquidFungibleResource, contingent: bool);
 
+    /// Consume an amount of cost units.
     fn consume_cost_units(&mut self, costing_entry: ClientCostingEntry) -> Result<(), E>;
 
+    /// Retrieve the cost unit limit for the transaction
     fn execution_cost_unit_limit(&mut self) -> Result<u32, E>;
 
+    /// Retrieve the cost unit price in XRD
     fn execution_cost_unit_price(&mut self) -> Result<Decimal, E>;
 
+    /// Retrieve the finalization cost unit limit
     fn finalization_cost_unit_limit(&mut self) -> Result<u32, E>;
 
+    /// Retrieve the finalization cost unit price in XRD
     fn finalization_cost_unit_price(&mut self) -> Result<Decimal, E>;
 
+    /// Retrieve the usd price of XRD
     fn usd_price(&mut self) -> Result<Decimal, E>;
 
+    /// Retrieve the maximum allowable royalty per function
     fn max_per_function_royalty_in_xrd(&mut self) -> Result<Decimal, E>;
 
+    /// Retrieve the tip percentage of the transaction
     fn tip_percentage(&mut self) -> Result<u32, E>;
 
+    /// Retrieve the current fee balance in XRD
     fn fee_balance(&mut self) -> Result<Decimal, E>;
 }

radix-engine-interface/src/api/field_api.rs

@@ -31,18 +31,22 @@ pub trait FieldPayloadMarker {}
 
 impl<T: FieldPayloadMarker> FieldPayloadMarker for &T {}
 
-/// A high level api to read/write fields
+/// System api to read/write fields
 pub trait SystemFieldApi<E: Debug> {
+    /// Retrieve the value of a field
     fn field_read(&mut self, handle: FieldHandle) -> Result<Vec<u8>, E>;
 
+    /// Retrieve the value of a field
     fn field_read_typed<S: ScryptoDecode>(&mut self, handle: FieldHandle) -> Result<S, E> {
         let buf = self.field_read(handle)?;
         let typed_substate: S = scrypto_decode(&buf).map_err(|e| e).unwrap();
         Ok(typed_substate)
     }
 
+    /// Write a value to a field
     fn field_write(&mut self, handle: FieldHandle, buffer: Vec<u8>) -> Result<(), E>;
 
+    /// Write a value to a field
     fn field_write_typed<S: ScryptoEncode>(
         &mut self,
         handle: FieldHandle,
@@ -52,7 +56,9 @@ pub trait SystemFieldApi<E: Debug> {
         self.field_write(handle, buf)
     }
 
+    /// Lock a field such that it becomes immutable
     fn field_lock(&mut self, handle: FieldHandle) -> Result<(), E>;
 
+    /// Close a field handle so that it is no longer usable
     fn field_close(&mut self, handle: FieldHandle) -> Result<(), E>;
 }

radix-engine-interface/src/api/key_value_entry_api.rs

@@ -3,12 +3,11 @@ use sbor::rust::prelude::*;
 
 pub type KeyValueEntryHandle = u32;
 
-pub trait KeyValueKeyPayloadMarker {}
-pub trait KeyValueEntryPayloadMarker {}
-
 pub trait SystemKeyValueEntryApi<E> {
+    /// Reads the value of a key value entry
     fn key_value_entry_get(&mut self, handle: KeyValueEntryHandle) -> Result<Vec<u8>, E>;
 
+    /// Reads the value of a key value entry and decodes it into a specific type
     fn key_value_entry_get_typed<S: ScryptoDecode>(
         &mut self,
         handle: KeyValueEntryHandle,
@@ -18,12 +17,14 @@ pub trait SystemKeyValueEntryApi<E> {
         Ok(value)
     }
 
+    /// Set the value of a key value entry
     fn key_value_entry_set(
         &mut self,
         handle: KeyValueEntryHandle,
         buffer: Vec<u8>,
     ) -> Result<(), E>;
 
+    /// Set the value of a key value entry
     fn key_value_entry_set_typed<S: ScryptoEncode>(
         &mut self,
         handle: KeyValueEntryHandle,
@@ -33,9 +34,12 @@ pub trait SystemKeyValueEntryApi<E> {
         self.key_value_entry_set(handle, buffer)
     }
 
+    /// Remove the value of a key value entry
     fn key_value_entry_remove(&mut self, handle: KeyValueEntryHandle) -> Result<Vec<u8>, E>;
 
+    /// Lock the value of a key value entry making the value immutable
     fn key_value_entry_lock(&mut self, handle: KeyValueEntryHandle) -> Result<(), E>;
 
+    /// Close the handle into the key value entry rendering it unusable after close
     fn key_value_entry_close(&mut self, handle: KeyValueEntryHandle) -> Result<(), E>;
 }

radix-engine-interface/src/api/key_value_store_api.rs

@@ -141,14 +141,15 @@ pub trait SystemKeyValueStoreApi<E> {
     /// Creates a new key value store with a given schema
     fn key_value_store_new(&mut self, data_schema: KeyValueStoreDataSchema) -> Result<NodeId, E>;
 
-    /// Lock a key value store entry for reading/writing
+    /// Open a key value store entry for reading/writing
     fn key_value_store_open_entry(
         &mut self,
         node_id: &NodeId,
         key: &Vec<u8>,
         flags: LockFlags,
     ) -> Result<KeyValueEntryHandle, E>;
 
+    /// Removes an entry from a key value store
     fn key_value_store_remove_entry(
         &mut self,
         node_id: &NodeId,

radix-engine-interface/src/api/mod.rs

@@ -40,7 +40,7 @@ pub const ACTOR_REF_AUTH_ZONE: ActorRefHandle = 8u32;
 pub type FieldIndex = u8;
 pub type CollectionIndex = u8;
 
-/// Interface of the system, for blueprints and Node modules.
+/// Interface of the system, for blueprints and object modules.
 ///
 /// For WASM blueprints, only a subset of the API is exposed at the moment.
 pub trait SystemApi<E: sbor::rust::fmt::Debug>:

radix-engine-interface/src/api/object_api.rs

@@ -241,18 +241,20 @@ pub trait SystemObjectApi<E> {
     /// Get the outer object of a visible object
     fn get_outer_object(&mut self, node_id: &NodeId) -> Result<GlobalAddress, E>;
 
-    /// Pre-allocates a global address, for a future globalization.
+    /// Allocates a global address, for a future globalization.
     fn allocate_global_address(
         &mut self,
         blueprint_id: BlueprintId,
     ) -> Result<(GlobalAddressReservation, GlobalAddress), E>;
 
+    /// Allocates a specific virtual global address
     fn allocate_virtual_global_address(
         &mut self,
         blueprint_id: BlueprintId,
         global_address: GlobalAddress,
     ) -> Result<GlobalAddressReservation, E>;
 
+    /// Retrieve the global address of a given address reservation
     fn get_reservation_address(&mut self, node_id: &NodeId) -> Result<GlobalAddress, E>;
 
     /// Moves an object currently in the heap into the global space making
@@ -264,6 +266,7 @@ pub trait SystemObjectApi<E> {
         address_reservation: Option<GlobalAddressReservation>,
     ) -> Result<GlobalAddress, E>;
 
+    /// Globalizes with a new inner object and emits an event
     fn globalize_with_address_and_create_inner_object_and_emit_event(
         &mut self,
         node_id: NodeId,
@@ -283,6 +286,7 @@ pub trait SystemObjectApi<E> {
         args: Vec<u8>,
     ) -> Result<Vec<u8>, E>;
 
+    /// Calls a direct access method on an object
     fn call_direct_access_method(
         &mut self,
         receiver: &NodeId,

radix-engine-interface/src/api/transaction_runtime_api.rs

@@ -4,13 +4,18 @@ use radix_common::crypto::Hash;
 use radix_common::types::GlobalAddress;
 
 pub trait SystemTransactionRuntimeApi<E> {
+    /// Encode an address into Bech32. The HRP part is dependent on the network which is running.
     fn bech32_encode_address(&mut self, address: GlobalAddress) -> Result<String, E>;
 
+    /// Retrieve the hash of the current transaction which is running.
     fn get_transaction_hash(&mut self) -> Result<Hash, E>;
 
+    /// Generate a unique id
     fn generate_ruid(&mut self) -> Result<[u8; 32], E>;
 
+    /// Emit a log message which will be available in the transaction receipt
     fn emit_log(&mut self, level: Level, message: String) -> Result<(), E>;
 
+    /// End the transaction immediately with a given message to be included in the transaction receipt
     fn panic(&mut self, message: String) -> Result<(), E>;
 }

radix-engine-interface/src/blueprints/package/invocations.rs

@@ -89,11 +89,15 @@ pub struct PackageClaimRoyaltiesInput {}
 
 pub type PackageClaimRoyaltiesOutput = Bucket;
 
+/// The set of blueprints and their associated definitions for a package
 #[derive(Debug, Clone, Eq, PartialEq, Default, ScryptoSbor, ManifestSbor)]
 pub struct PackageDefinition {
     pub blueprints: IndexMap<String, BlueprintDefinitionInit>,
 }
 
+/// A blueprint may be specified as either an Outer or Inner Blueprint. If an inner blueprint, an associated outer
+/// blueprint must be specified and only a component of the outer blueprint may instantiate the inner blueprint.
+/// Inner blueprint components may access the state of its outer blueprint component directly.
 #[derive(Debug, Clone, Eq, PartialEq, ScryptoSbor, ManifestSbor)]
 pub enum BlueprintType {
     Outer,
@@ -106,14 +110,28 @@ impl Default for BlueprintType {
     }
 }
 
+/// Structure which defines static interface qualities of a Blueprint
 #[derive(Debug, Clone, Eq, PartialEq, ScryptoSbor, ManifestSbor)]
 pub struct BlueprintDefinitionInit {
+    /// Whether the blueprint is an Outer or Inner Blueprint
     pub blueprint_type: BlueprintType,
+
+    /// If true, all components of this blueprint type may not be persisted.
     pub is_transient: bool,
+
+    /// The set of all possible features a component instantiator may specify.
     pub feature_set: IndexSet<String>,
+
+    /// A set of addresses which will always be visible to call frames of this blueprint.
     pub dependencies: IndexSet<GlobalAddress>,
+
+    /// The schema of the blueprint including interface, state, and events
     pub schema: BlueprintSchemaInit,
+
+    /// Blueprint module: Royalty configuration
     pub royalty_config: PackageRoyaltyConfig,
+
+    /// Blueprint module: Auth configuration such as role definitions
     pub auth_config: AuthConfig,
 }
 
@@ -172,6 +190,8 @@ impl Default for MethodAuthTemplate {
 #[derive(Debug, Clone, Eq, PartialEq, ScryptoSbor, ManifestSbor)]
 pub enum RoleSpecification {
     /// Roles are specified in the current blueprint and defined in the instantiated object.
+    /// The map contains keys for all possible roles, mapping to a list of roles which may update
+    /// the access rule for each role.
     Normal(IndexMap<RoleKey, RoleList>),
     /// Roles are specified in the *outer* blueprint and defined in the instantiated *outer* object.
     /// This may only be used by inner blueprints and is currently used by the Vault blueprints

radix-engine-monkey-tests/tests/fuzz_kernel.rs

@@ -273,19 +273,6 @@ impl KernelCallbackObject for TestCallbackObject {
     {
         Ok(())
     }
-
-    fn on_move_node<Y>(
-        _node_id: &NodeId,
-        _is_moving_down: bool,
-        _is_to_barrier: bool,
-        _destination_blueprint_id: Option<BlueprintId>,
-        _api: &mut Y,
-    ) -> Result<(), RuntimeError>
-    where
-        Y: KernelApi<Self>,
-    {
-        Ok(())
-    }
 }
 
 struct KernelFuzzer {

radix-engine-tests/tests/kernel/kernel.rs

@@ -246,19 +246,6 @@ impl KernelCallbackObject for TestCallbackObject {
     {
         Ok(())
     }
-
-    fn on_move_node<Y>(
-        _node_id: &NodeId,
-        _is_moving_down: bool,
-        _is_to_barrier: bool,
-        _destination_blueprint_id: Option<BlueprintId>,
-        _api: &mut Y,
-    ) -> Result<(), RuntimeError>
-    where
-        Y: KernelApi<Self>,
-    {
-        Ok(())
-    }
 }
 
 enum MoveVariation {