diff --git a/radix-engine/book/src/README.md b/radix-engine/book/src/README.md index 68624dab250..8ca2d72df11 100644 --- a/radix-engine/book/src/README.md +++ b/radix-engine/book/src/README.md @@ -9,4 +9,9 @@ shared computing environment in terms of usability, security, performance, and m Unlike the EVM and other blockchain VMs, Radix Engine: * Is Object-Oriented and Type-Safe * Enforces move/ownership semantics -* Has the ability to add system plugins to extend system functionality +* Has the ability to add system plugins to extend/modify system functionality + +## Radix Babylon Network + +The Radix Engine running on the Radix Babylon network is a specific system configuration of +Radix Engine which makes asset and auth management a native/core feature of the system. \ No newline at end of file diff --git a/radix-engine/book/src/SUMMARY.md b/radix-engine/book/src/SUMMARY.md index 096be6ed8da..6e9b7883d39 100644 --- a/radix-engine/book/src/SUMMARY.md +++ b/radix-engine/book/src/SUMMARY.md @@ -11,6 +11,7 @@ - [Outer Object](architecture/application/object/inner_outer_objects.md) - [Features](architecture/application/object/features.md) - [Generic Substitutions](architecture/application/object/generic_substitutions.md) + - [Application State](architecture/application/object/application_state.md) - [Object Modules](architecture/application/object/object_modules.md) - [Blueprint](architecture/application/blueprint/README.md) - [Inner and Outer Blueprints](architecture/application/blueprint/inner_outer.md) @@ -24,6 +25,7 @@ - [Hooks](architecture/application/blueprint/hooks.md) - [Types](architecture/application/blueprint/types.md) - [Blueprint Modules](architecture/application/blueprint/blueprint_modules.md) + - [Package](architecture/application/package/README.md) - [Type System](architecture/application/type_system/README.md) - [Actor](architecture/application/actor/README.md) - [VM Layer](architecture/vm/README.md) @@ -32,6 +34,8 @@ - [System Layer](architecture/system/README.md) - [Object Impl](architecture/system/object_impl.md) - [Blueprint Impl](architecture/system/blueprint_impl.md) + - [Package Impl](architecture/system/package_impl.md) + - [Type System Impl](architecture/system/type_system_impl.md) - [Actor Impl](architecture/system/actor_impl.md) - [System Modules](architecture/system/system_modules.md) - [Kernel Layer](architecture/kernel/README.md) diff --git a/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md b/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md index cc8694b6560..6b2c82d4a2c 100644 --- a/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md +++ b/radix-engine/book/src/architecture/application/blueprint/blueprint_modules.md @@ -3,6 +3,7 @@ The system may define additional state to be stored per blueprint known as Blueprint modules. If defined, every blueprint definition must initialize these modules. -Currently there exists two blueprint modules: -* [Auth Blueprint Module](../../../native/auth/blueprint_module.md) -* [Package Royalties Blueprint Module](../../../native/royalties/package_royalties.md) \ No newline at end of file +> **_NOTE:_** In [Radix Babylon Network](../../../#radix-babylon-network), there currently +> exists two blueprint modules: +> * [Auth Blueprint Module](../../../native/auth/blueprint_module.md) +> * [Package Royalties Blueprint Module](../../../native/royalties/package_royalties.md) \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/blueprint/collections.md b/radix-engine/book/src/architecture/application/blueprint/collections.md index 664460ebaac..4cf9e795934 100644 --- a/radix-engine/book/src/architecture/application/blueprint/collections.md +++ b/radix-engine/book/src/architecture/application/blueprint/collections.md @@ -1,6 +1,7 @@ # Collections -> **_NOTE:_** Collections are currently only available for use by native packages. +> **_NOTE:_** In [Radix Babylon Network](../../../#radix-babylon-network), +> Collections are currently only available for use by native packages. A collection is a set of data which share the same schema. There are currently three types of collections: diff --git a/radix-engine/book/src/architecture/application/blueprint/features.md b/radix-engine/book/src/architecture/application/blueprint/features.md index 5001312f8c9..931a47e93d2 100644 --- a/radix-engine/book/src/architecture/application/blueprint/features.md +++ b/radix-engine/book/src/architecture/application/blueprint/features.md @@ -1,6 +1,7 @@ # Features -> **_NOTE:_** Features are currently only available for use by native packages. +> **_NOTE:_** In [Radix Babylon Network](../../../#radix-babylon-network), Features +> are currently only available for use by native packages. Features provide a mechanism to express conditional execution and conditional stored state (using [Field Conditions](fields.md#field-condition)). The set of features to be used are specified diff --git a/radix-engine/book/src/architecture/application/blueprint/fields.md b/radix-engine/book/src/architecture/application/blueprint/fields.md index 729b653b8f0..2663311977c 100644 --- a/radix-engine/book/src/architecture/application/blueprint/fields.md +++ b/radix-engine/book/src/architecture/application/blueprint/fields.md @@ -1,6 +1,7 @@ # Fields -> **_NOTE:_** Use of more than one Field, Field Conditions and Field Transience are currently only available for use by native packages. +> **_NOTE:_** In [Radix Babylon Network](../../../#radix-babylon-network), +> use of more than one Field, Field Conditions and Field Transience are currently only available for use by native packages. A field is object state which gets loaded at once and maps to a single substate. A schema which describes what is in the data must be specified for every field. diff --git a/radix-engine/book/src/architecture/application/blueprint/generics.md b/radix-engine/book/src/architecture/application/blueprint/generics.md index 0919e7a13a6..3cad82788d0 100644 --- a/radix-engine/book/src/architecture/application/blueprint/generics.md +++ b/radix-engine/book/src/architecture/application/blueprint/generics.md @@ -1,6 +1,7 @@ # Generics -> **_NOTE:_** Generics are currently only available for use by native packages. +> **_NOTE:_** In [Radix Babylon Network](../../../#radix-babylon-network), +> Generics are currently only available for use by native packages. Generics to a blueprint requires an object instantiator to specify [generic substitutions](../object/generic_substitutions.md) during instantiation. Such a generic can then be used in defining function or state schemas. diff --git a/radix-engine/book/src/architecture/application/blueprint/hooks.md b/radix-engine/book/src/architecture/application/blueprint/hooks.md index 3e67f5454e5..b8388e4f314 100644 --- a/radix-engine/book/src/architecture/application/blueprint/hooks.md +++ b/radix-engine/book/src/architecture/application/blueprint/hooks.md @@ -1,6 +1,7 @@ # Hooks -> **_NOTE:_** Hooks are currently only available for use by native packages. +> **_NOTE:_** In [Radix Babylon Network](../../../#radix-babylon-network), +> Hooks are currently only available for use by native packages. Hooks define logic which get executed when certain system events occur. diff --git a/radix-engine/book/src/architecture/application/blueprint/inner_outer.md b/radix-engine/book/src/architecture/application/blueprint/inner_outer.md index 3a7974f550d..7728dcf007d 100644 --- a/radix-engine/book/src/architecture/application/blueprint/inner_outer.md +++ b/radix-engine/book/src/architecture/application/blueprint/inner_outer.md @@ -1,6 +1,7 @@ # Inner and Outer Blueprints -> **_NOTE:_** Inner Blueprints are currently only available for use by native packages. +> **_NOTE:_** In [Radix Babylon Network](../../../#radix-babylon-network), +> Inner Blueprints are currently only available for use by native packages. A blueprint may be specified as either an Outer or Inner Blueprint. Inner blueprints must specify an associated outer blueprint defined in the same package. diff --git a/radix-engine/book/src/architecture/application/blueprint/transience.md b/radix-engine/book/src/architecture/application/blueprint/transience.md index 263e1472951..c10620747c4 100644 --- a/radix-engine/book/src/architecture/application/blueprint/transience.md +++ b/radix-engine/book/src/architecture/application/blueprint/transience.md @@ -1,6 +1,6 @@ # Transience -> **_NOTE:_** Transience is currently only available for use by native packages. +> **_NOTE:_** In [Radix Babylon Network](../../../#radix-babylon-network), Transience is currently only available for use by native packages. If a blueprint is specified to be transient, all objects of this blueprint cannot be persisted and must be created/dropped within the lifecycle of a transaction. diff --git a/radix-engine/book/src/architecture/application/object/README.md b/radix-engine/book/src/architecture/application/object/README.md index a9d92c0fdb7..c7c0f77a53e 100644 --- a/radix-engine/book/src/architecture/application/object/README.md +++ b/radix-engine/book/src/architecture/application/object/README.md @@ -7,8 +7,10 @@ parent in the tree hierarchy. Each root object is assigned a *global address*. ![](object_model.drawio.svg) Each object has: -* A [BlueprintId](blueprint_id.md) (type) -* An optional [Outer Object](inner_outer_objects.md) -* A list of [Features](features.md) -* A list of [Generic Substitutions](generic_substitutions.md) +* Static Type Information which includes: + * A [BlueprintId](blueprint_id.md) + * An optional [Outer Object](inner_outer_objects.md) + * A list of [Features](features.md) + * A list of [Generic Substitutions](generic_substitutions.md) +* Application State * A set of [Object Modules](object_modules.md) \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/object/application_state.md b/radix-engine/book/src/architecture/application/object/application_state.md new file mode 100644 index 00000000000..fbcfdb8349d --- /dev/null +++ b/radix-engine/book/src/architecture/application/object/application_state.md @@ -0,0 +1,6 @@ +# Application State + +Each object may have a set of [fields](../blueprint/fields.md) and +[collections](../blueprint/collections.md) which represent that object's state. +When created or updated, these fields and collections must conform to the schema specified +by the object's [blueprint](blueprint_id.md). diff --git a/radix-engine/book/src/architecture/application/object/blueprint_id.md b/radix-engine/book/src/architecture/application/object/blueprint_id.md index 393e275dc8c..20f70151a91 100644 --- a/radix-engine/book/src/architecture/application/object/blueprint_id.md +++ b/radix-engine/book/src/architecture/application/object/blueprint_id.md @@ -1,5 +1,7 @@ # Blueprint Id Every object is associated with a blueprint id which consists of -` + `. A blueprint id uniquely identifies the -[blueprint](../blueprint/README.md) of an object. +` + `. + +A blueprint id uniquely identifies the [blueprint](../blueprint) of an object. +The blueprint of an object specifies both the structure and the logic of the object. diff --git a/radix-engine/book/src/architecture/application/object/features.md b/radix-engine/book/src/architecture/application/object/features.md index 8c9415c91ae..4499dfe8e07 100644 --- a/radix-engine/book/src/architecture/application/object/features.md +++ b/radix-engine/book/src/architecture/application/object/features.md @@ -1,5 +1,5 @@ # Features -An object's features describes is a subset of the total [features](../blueprint/features.md) defined -in the object's blueprint. Having a feature enabled/disabled can modify both behavior and state stored -for the object. \ No newline at end of file +An object's features describes a subset of the total [features](../blueprint/features.md) defined +in the object's blueprint. Having a feature enabled/disabled can modify both behavior and +state stored for the object. \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/object/object_modules.md b/radix-engine/book/src/architecture/application/object/object_modules.md index e092afa0878..1c13dcb272b 100644 --- a/radix-engine/book/src/architecture/application/object/object_modules.md +++ b/radix-engine/book/src/architecture/application/object/object_modules.md @@ -8,7 +8,9 @@ the state of the object module. ![](object_modules.drawio.svg) -Currently, there exists three object modules: -* [RoleAssignment](../../../native/auth/role_assignment.md) (Required) -* [Metadata](../../../native/metadata/object_module.md) (Required) -* [Component Royalties](../../../native/royalties/component_royalties.md) (Optional) +> **_NOTE:_** In [Radix Babylon Network](../../../#radix-babylon-network), there currently +> exists three object modules: +> * [RoleAssignment](../../../native/auth/role_assignment.md) (Required) +> * [Metadata](../../../native/metadata/object_module.md) (Required) +> * [Component Royalties](../../../native/royalties/component_royalties.md) (Optional) + diff --git a/radix-engine/book/src/architecture/application/package/README.md b/radix-engine/book/src/architecture/application/package/README.md new file mode 100644 index 00000000000..ba08ddf3314 --- /dev/null +++ b/radix-engine/book/src/architecture/application/package/README.md @@ -0,0 +1,24 @@ +# Package + +A package is a special native object which contains 0 or more blueprint definitions. Because it is an +object, packages inherit object-like qualities such as the ability to have object modules +(like metadata). + +## Package Blueprint and Package Package + +This type of relationship creates the following circular definition: + +`An Object is of some Blueprint type.` + +`A Blueprint is part of a Package.` + +`A Package is an Object.` + +This circular definition creates the notion of the Package Blueprint and the +Package Package (similar to Class.class in java). A Package Blueprint is the +blueprint type of a Package object and Package Package is the package which +contains the Package Blueprint. + +Due to the circular dependency, the first object (Package object) is created +without following standard object creation process. It's directly [flashed into +the database](../../../protocol/genesis_bootstrap.md). \ No newline at end of file diff --git a/radix-engine/book/src/architecture/application/type_system/README.md b/radix-engine/book/src/architecture/application/type_system/README.md index f27fa99c94b..1a868e3edd1 100644 --- a/radix-engine/book/src/architecture/application/type_system/README.md +++ b/radix-engine/book/src/architecture/application/type_system/README.md @@ -8,4 +8,4 @@ the Blueprint. This includes: The Type Checking System supports generics. -![](type_checking_arch.drawio.svg) \ No newline at end of file +![](type_checking_arch.drawio.svg) diff --git a/radix-engine/book/src/architecture/layers.md b/radix-engine/book/src/architecture/layers.md index 3814035f61b..94eb642f6c7 100644 --- a/radix-engine/book/src/architecture/layers.md +++ b/radix-engine/book/src/architecture/layers.md @@ -10,5 +10,5 @@ layer above must implement. | [VM](vm/README.md) | Executes Application Code | | [System](system/README.md) | Defines Actor abstraction (Memory Protection)
Defines Package, Blueprint, Object abstractions
Defines System Standards such as Authorization and Versioning | | [Kernel](kernel/README.md) | Defines Node, Partition, Substate abstractions
Maintains Call Frame Stack
Maintains Ownership/Reference invariants | -| Database | Defines PartitionKey, SortKey abstractions | +| [Database](database/README.md) | Defines PartitionKey, SortKey abstractions | diff --git a/radix-engine/book/src/architecture/system/README.md b/radix-engine/book/src/architecture/system/README.md index 530700c1220..37d1b5ccf50 100644 --- a/radix-engine/book/src/architecture/system/README.md +++ b/radix-engine/book/src/architecture/system/README.md @@ -1,7 +1,7 @@ # System Layer The System Layer is responsible for: -* Defining the [Object](object_impl.md), [Blueprint](blueprint_impl.md), and Package abstraction +* Defining the [Object](object_impl.md), [Blueprint](blueprint_impl.md), [Type System](type_system_impl.md), and [Package](package_impl.md) abstraction * Defining [Actor](actor_impl.md) abstraction and memory protection * Maintaining a set of [System Modules](system_modules.md), or pluggable software, which extends the functionality of the system. diff --git a/radix-engine/book/src/architecture/system/blueprint_impl.md b/radix-engine/book/src/architecture/system/blueprint_impl.md index 66d4b5697d1..99067370535 100644 --- a/radix-engine/book/src/architecture/system/blueprint_impl.md +++ b/radix-engine/book/src/architecture/system/blueprint_impl.md @@ -2,7 +2,8 @@ ## State to Partition Mapping -The mapping from Fields and Collection indices to Partition Number is managed by the System Layer -and done at a per blueprint basis. +The mapping from the Fields and Collection indices to Partition Number is managed by the System Layer +and done at a per blueprint basis. This includes the Fields and Collection indices of the object modules +for and object. ![](bp_partition_mapping.drawio.svg) \ No newline at end of file diff --git a/radix-engine/book/src/architecture/system/bp_partition_mapping.drawio b/radix-engine/book/src/architecture/system/bp_partition_mapping.drawio index cc86218ed3e..c5b2b9d5c13 100644 --- a/radix-engine/book/src/architecture/system/bp_partition_mapping.drawio +++ b/radix-engine/book/src/architecture/system/bp_partition_mapping.drawio @@ -1,35 +1,35 @@ - + - + - + - + - - + + - - + + - - + + - - + + - - + + @@ -49,6 +49,72 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/radix-engine/book/src/architecture/system/bp_partition_mapping.drawio.svg b/radix-engine/book/src/architecture/system/bp_partition_mapping.drawio.svg index 72313571bf0..6042d5e79cc 100644 --- a/radix-engine/book/src/architecture/system/bp_partition_mapping.drawio.svg +++ b/radix-engine/book/src/architecture/system/bp_partition_mapping.drawio.svg @@ -1,4 +1,4 @@ -
Fields
Collection0
Collection1
Base Partition + 0
Base Partition + 1
Base Partition + 2
Base Partition
 \ No newline at end of file +
Fields
Collection0
Collection1
App
BasePartition + 0
App
BasePartition + 1
App
BasePartition + 2
App
BasePartition = 64
Application
ObjectModule0
Collection0
ObjectModule1
Fields
ObjectModule0 BasePartition + 0
ObjectModule1 BasePartition + 0
ObjectModule1 BasePartition + 1
Collection0
ObjectModule0
BasePartition = 2
ObjectModule1 BasePartition = 4
Object
 \ No newline at end of file diff --git a/radix-engine/book/src/architecture/system/object_impl.md b/radix-engine/book/src/architecture/system/object_impl.md index 8f2c24dc90f..bdbdb086d40 100644 --- a/radix-engine/book/src/architecture/system/object_impl.md +++ b/radix-engine/book/src/architecture/system/object_impl.md @@ -13,3 +13,13 @@ mapped in the following manner: | Object Modules | 2-31 | | Reserved | 32-63 | | Application State | 64-255 | + +## Type Info + +For a given object, type-related info is stored under the object's `NodeId` in the TypeInfo +substate found in `PartitionNumber 0` and `SubstateKey::Field 0`. This includes information such as: +* [BlueprintId](../application/object/blueprint_id.md) +* [Features](../application/object/features.md) +* [Generic Substitutions](../application/object/generic_substitutions.md) +* [Inner/Outer](../application/object/inner_outer_objects.md) + diff --git a/radix-engine/book/src/architecture/system/package_impl.md b/radix-engine/book/src/architecture/system/package_impl.md new file mode 100644 index 00000000000..21c27886afb --- /dev/null +++ b/radix-engine/book/src/architecture/system/package_impl.md @@ -0,0 +1,6 @@ +# Package Implementation + +The package abstraction is implemented as a native blueprint. In order to get around the +[circular definition problem](../application/package/README.md#package-blueprint-and-package-package), +the package logic and structure must be [flashed into the system](../../protocol/genesis_bootstrap.md) +at genesis. diff --git a/radix-engine/book/src/architecture/system/type_system_impl.md b/radix-engine/book/src/architecture/system/type_system_impl.md new file mode 100644 index 00000000000..71eb75422c9 --- /dev/null +++ b/radix-engine/book/src/architecture/system/type_system_impl.md @@ -0,0 +1,12 @@ +# Type System + +The system layer is responsible for implementing the [type system abstraction](../application/type_system/README.md). + +For a given object, the `BlueprintId`, `GenericSubstitutions`, and other type-related info is stored +under the object's `NodeId` in the TypeInfo substate found in `PartitionNumber 0` and `SubstateKey::Field 0`. + +Local Scrypto Schemas for the object are stored in the object's `NodeId` with `PartitionNumber 2` with +a content addressable substate key. + +Remote Scrypto Schemas are stored in the blueprint's package `NodeId` with `PartitionNumber 2` with +a content addressable substate key.