Add Identity Rebased Docs

docs/content/iota-identity/explanations/about-identity-objects.mdx

@@ -9,39 +9,113 @@ tags:
   - getting-started
 ---
 
+# Introduction to on-chain identities
+DID documents allow to digitally represent an entity’s identity, where with "entity" we refer to either a person,
+an object, an institution / company, etc. DID documents can therefore be thought of as digital identities.
+
+When a DID document is stored on a blockchain network, its SSI properties are enriched by the security guarantees of the DLT,
+obtaining an on-chain identity.
+
+## On-chain Identities with multiple controllers
+The [DID method specification](https://www.w3.org/TR/did-core/#did-controller) defines the DID controller as _an entity that
+is authorized to make changes to a DID Document_. 
+We leverage this definition to define an Identity's controller as an entity that is a DID controller to the Identity's
+DID Document.
+
+A DID document may have multiple controllers which can enact control over the document in two ways:
+- [indipendent control](https://www.w3.org/TR/did-core/#independent-control);
+- [group control](https://www.w3.org/TR/did-core/#group-control);
+
+Similarly on-chain Identities can have more than one controller and the two control strategies mentioned above are instantiated
+like so:
+- [**independent control**](https://www.w3.org/TR/did-core/#independent-control): each controller accesses the identity
+  through its own address.  
+- [**group control**](https://www.w3.org/TR/did-core/#group-control): the access to the Identity is multiplexed through an 
+  address that is shared by all controllers (e.g. multisig address).
+
 # Identity Object
+With "identity" or "Identity Object" we refer to an on-chain identity instanced on an IOTA network and that complies with the
+[IOTA DID method specification](../../references/iota-identity/iota-did-method-spec.mdx).
+
+More specifically, an Identity Object is a **shared** _Move_ object that stores a single DID Document on the network,
+allowing both on-chain and off-chain actors to interact with it.
+Designing Identity as a shared object enables both aforementioned control strategies. This wouldn't be possible using owned 
+objects, as they can only be referenced in transactions by their owner address - making _group control_ the only viable strategy
+for shared control.
 
-An Identity Object is a **shared** _Move_ object that stores a single DID Document on the network, allowing both
-on-chain and off-chain actors to interact with it.
 
 The Identity Object's unique ID is used to derive the actual DID of the DID Document it contains.
 
+:::warning
+Migrated Identities - i.e. Identities that are derived from legacy Stardust Identities through a migration operation - do not
+share this property. In fact, the unique ID of a migrated Identity is not used to derive the Identity's DID but instead it 
+appears in the Identity's DID Document's `alsoKnownAs` property. 
+:::
+
 ## Identity's Access Control
 
 An `Identity` is a shared object and is thus accessible by anyone. For this reason, it is of paramount importance to 
 limit the use of an `Identity`'s APIs - especially its mutable ones - to only the intended actors.
 
-### Controllers and `ControllerCap`
+### Controllers, `ControllerCap`, and `DelegationToken`
+An Identity controller is an entity that is authorized to make changes to an Identity.
+In order to allow a broader range of 
+actors to act as an `Identity`'s controller - e.g. an `Identity` controlling another `Identity` - a controller is identified 
+through its **controller capability** `ControllerCap`.
+A `ControllerCap` is a token that allows anyone who possess it to invoke a controller-restricted capability on a given Identity.
 
-The [DID specification](https://www.w3.org/TR/did-core/) defines **DID controller** as the entity allowed to make changes to
-a DID document. Since an `Identity` may be viewed as a simple wrapper over a DID Document, we extend the definition of _DID controller_ to be:
-_the entity allowed to make changes to an `Identity`_.
+Specifically, `ControllerCap`s are _non-store Move_ objects that behaves in a similar way to **soul-bound tokens** - i.e. they are attached to the address that owns them indefinitely and can only be destroyed after the controllers committee allows it.
 
-In order to allow a broader range of actors to act as an `Identity`'s controller - e.g. an `Identity` controlling another `Identity` -
-a controller is identified through its **controller capability** `ControllerCap`.
-A `ControllerCap` is a _Move_ object that acts as a blind token, allowing anyone who presents it to the corresponding `Identity` to access
-the `Identity`'s APIs that are only invocable by its controllers.
+Given the restrictive nature of `ControllerCap`, in order to support use-cases where the access to an Identity wants to be traded -
+e.g. leasing it for some time, or given to a smart contract - a new kind of `store`-able token is needed.
+`DelegationToken` exists for this exact reason.
+
+`DelegationToken` is a `store` _Move_ object that can only be minted from a `ControllerCap` and that allows whoever presents it
+to act as a **delegate** of the controller who minted it. `DelegationToken`s can be revoked at any moment by the controllers 
+committee. 
+Furthermore, `DelegationToken`s come with a permissions list - that is set by the minting controller upon the token creation - that limits their capabilities.
+
+:::warning
+Not all `ControllerCap`s are allowed to mint `DelegationToken`s. When a new controller is added to the controllers committee it
+is necessary to specify whether the new controller is allowed to delegate its access or not.
+:::
 
 ### Voting power and threshold
+When an `Identity` has more than a single controller, an access control (AC) policy for the `Identity` must be established. Such 
+a policy is represented by an unsigned integer **threshold** that is established upon the `Identity`'s creation.
+Together with the `Identity`'s threshold, each controller is assigned with a **voting power**, i.e. an unsigned integer that 
+acts as a sort of _weight_ in the evaluation of an AC control policy.   
 
-When an `Identity` has more than a single controller, an access control (AC) policy for the `Identity` must be established. Such a policy is 
-represented by an unsigned integer **threshold** that is established upon the `Identity`'s creation. Together with the `Identity`'s threshold, each controller
-is assigned with a **voting power**, i.e. an unsigned integer that acts as a sort of _weight_ in the evaluation of an AC control policy.   
+Giving different voting power or weights to each controllers enable a wider range of AC policy that can be enforced on an 
+Identity.
 
 ### Proposals
+Whenever a controller wants to make a change to its `Identity`, a **proposal** encapsulating that change is created instead of 
+carrying out the update right away.
+In order to execute the changes contained in a `Proposal` enough controllers need to approve it. The exact number of approvals 
+depends on the controllers' voting powers as well as the `Identity`'s threshold. 
+`Proposal`s keep track of the approvals they receive by internally storing the sum of all approving controllers' voting powers 
+in a field called `votes`.
+A `Proposal` can only be executed after `votes` exceeds the `Identity`'s threshold.
+
+# Identities Hierarchies
+Creating hierarchies of identities can be extremely useful for modeling situations like subsidiaries for companies or custodians 
+for humans.
+In order to create such hierarchies, an Identity must be able to control another. Achieving this is as simple as making an 
+Identity a controller of another Identity.
+
+More concretely, assuming we have two Identities: Identity **A**, and Identity **B**; if we want to model the fact that **A** 
+controls **B**, we add **A** to the list of **B**'s controllers by sending to **A**'s address a `ControllerCap` for Identity 
+**B**.
+With this setup in place, controllers of Identity **A** can borrow **A**'s `ControllerCap` to **B** and use it to invoke **A**'s
+capability on **B**.
+
+## Assets ownership and transfers
+
+Identities, just like any other _Move_ object, can own assets - e.g. coins, NFTs, `ControllerCap`s. Controllers can access
+an Identity's assets through different proposals to either borrow or send them.
+
+Borrowing an Identity's assets allows a controller to reference them in a trasaction, in order to use them or update them;
+the only restriction is that they have to be returned to the Identity in the same transaction.
 
-Whenever a controller wants to make a change to its `Identity`, a **proposal** encapsulating that change is created instead of carrying out the update
-right away. In order to execute the changes contained in a `Proposal` enough controllers need to approve it. The exact number of approvals depends on 
-the controllers' voting powers as well as the `Identity`'s threshold. 
-`Proposal`s keep track of the approvals they receive by internally storing the sum of all approving controllers' voting powers in a field called `votes`.
-A `Proposal` can only be executed after `votes` exceeds `Identity`'s threshold.
+Instead, sending an Identity's assets enables controllers to transfer them to another address, even their own.

docs/content/iota-identity/explanations/authenticated-assets.mdx

@@ -0,0 +1,47 @@
+---
+title: Authenticated Asset
+description: A configurable asset that keeps track of its origin and owner.
+image: /img/identity/icon.png
+tags:
+  - explanation
+  - getting-started
+  - move
+  - identity
+---
+
+# Authenticated Asset
+
+Storing data on-chain automatically enriches it with all the security guarantees inherent to DLTs and is therefore
+a widely used practice - especially for data that requires to be persisted indefinitely and that has a small footprint,
+e.g. revocation lists, or proof of inclusions.
+
+In order to store data on an IOTA network, said data must be encapsulated within a _Move_ object with the _store_ ability.
+This operation can become quite tedious as it requires to model an object that holds the data even for data types that does not 
+require to be stored in a human-readable or accessible manner, e.g. raw bytes, strings.
+
+In the aim of solving this issue, we introduce a new configurable object type `AuthenticatedAsset`, that can store arbitrary
+data whilst keeping track of the address that created it and the address that owns it. After data is wrapped in an
+`AuthenticatedAsset` it is persisted on-chain and can be referenced through `AuthenticatedAsset`'s ID.
+
+## Authenticated Asset configuration
+
+`AuthenticatedAsset` is a configurable data container. Upon its creation, users can configure it to make it: **mutable**,
+**deletable**, and **tradable**.
+
+:::info
+By default an `AuthenticatedAsset` is immutable, non-tradable, and impossible to delete.
+:::
+
+`AuthenticatedAsset`'s configuration allows it to be a good fit for different use cases. For instance, when storing revocation
+lists we want to be able to update it, hence we need `AuthenticatedAsset` to be mutable, but at the same time we need to make
+sure its content is never deleted and always accessible. 
+On the other hand, when storing proof of inclusions, we want them to be immutable.
+
+## Authenticated Asset origin and ownership
+
+When storing data on an IOTA network, the owner of said data as well as the address that created it, could be easily be
+retrieved by off-chain actors through the network indexer. This information though is not accessible on-chain unless made it
+explicit within the object that wraps the data. 
+
+`AuthenticatedAsset` keeps track of its origin and ownership by default, in order to enable the access of this information
+on-chain.