From b85db79dd079df0a882a94afe80d1a536dbf9743 Mon Sep 17 00:00:00 2001 From: Lucas Tortora <85233773+lucas-tortora@users.noreply.github.com> Date: Mon, 20 Nov 2023 08:49:51 -0300 Subject: [PATCH 1/9] remove outdated terms (#1336) --- common/jargon.js | 28 ------------------- .../core-concepts/consensus/preliminaries.md | 6 ++-- .../consensus/relevant-algorithms.md | 2 +- .../consensus/tip-selection-algorithm.md | 2 +- .../iota2.0/core-concepts/data-flow.md | 2 +- .../protocols/iota2.0/core-concepts/mana.md | 2 +- 6 files changed, 7 insertions(+), 35 deletions(-) diff --git a/common/jargon.js b/common/jargon.js index 0aff85f0fd8..c5871ffa2a4 100644 --- a/common/jargon.js +++ b/common/jargon.js @@ -60,13 +60,10 @@ module.exports = { 'An attack where a node downloads malicious snapshot files, including invalid transactions and balances.', 'bootstrapping phase': 'The initial phase of the IOTA 2.0 network where rewards and delegation mechanisms are designed to encourage early contributions to the network"s security.', - branch: - 'In IOTA 2.0, this term refers to a version of the ledger that temporarily coexists with other versions, each spawned by conflicting transactions.', 'causal order': 'The order of events in the Tangle that reflects the causal relationships between transactions.', 'chain-switching rule': 'The Chain-Switching Rule is an algorithm that allows nodes to switch their Slot Commitment Chain to the heaviest one, resolving divergent network conditions and discrepancies in the commitments.', - child: 'In IOTA 2.0, a transaction that is referenced by Parents.', chronicle: "A permanode solution from the IOTA Foundation. It enables storing all transactions reaching a node in a secure and scalable distributed database. Chronicle allows the Tangle's unlimited data flow to be stored indefinitely and makes it easily accessible.", chrysalis: 'The name of the IOTA 1.5 network upgrade.', @@ -100,10 +97,6 @@ module.exports = { 'Hardware components or devices that are affordable for individual consumers.', coordinator: "(only up to iota 2.0) A trusted entity used as protection against malicious transactions. The Tangle is still in its beta phase and relies on the coordinator. This is open-source and runs on a Hornet node. The COO acts as a centralized, voluntary, and temporary alternative consensus mechanism for the Tangle by regularly sending honest transactions to the full nodes. These transactions contain a signed message with no value, called a milestone. Full nodes consider a transaction as confirmed only if it is approved by a milestone. The coordinator can confirm transactions but can't bypass consensus rules. Hence, creating, freezing, or stealing tokens is impossible for it. The coordinator's influence on the tangle is limited as the tangle is continuously monitored by all other full nodes. The COO will be switched off with the IOTA 2.0 upgrade.", - 'core application': - 'In IOTA 2.0, a core application is an application that all nodes must execute. For instance, the value transfer application.', - 'core object type': - 'In IOTA 2.0, this is an object type that all nodes must parse. Parsers are computer programs that decompose and convert input into a format more suitable for further processing.', cryptocurrency: 'A digital or virtual form of currency maintained by a distributed ledger.', CTPS: 'Confirmed transactions per second.', @@ -145,7 +138,6 @@ module.exports = { DLT: 'Distributed Ledger Technologyl; A type of technology that enables the secure and decentralized storage and sharing of information across a network and allows unaligned parties to maintain a common state. A DLT is a database system that enables the peer-to-peer transfer and recording of digital assets. Each transaction within a DLT is recorded in a distributed ledger, which is maintained across all network nodes.', 'double-spending': 'Two transactions that attempt to consume the same UTXO. Double-spending represents a major threat to digital currency systems. It involves spending the same digital token more than once. Digital tokens, unlike physical currency, comprise digital files that can be easily duplicated or counterfeited.', - dRNG: 'Decentralized Random Number Generator; dRNG is crucial for the Fast Probabilistic Consensus (FPC) as it fortifies the consensus model against attacks. For conflicting transactions, the FPC conducts several rounds of voting. The decision threshold for nodes is 50% plus or minus a slight random deviation generated by dRNG. This randomness prevents potential adversaries from manipulating the vote.', 'dust protection': '(iota 1.5) To prevent IOTA from being exploited, one might continually send 1i to newly generated addresses for years, causing the ledger’s memory requirements to surge until only large servers could operate a full node. With Chrysalis, microtransactions (<1Mi) require the recipient address to enable dust. This permits a limited amount of dust transactions. Additionally, addresses with Colored Coins must be tokenized. Post-Coordicide, IOTA 2.0 will introduce a different solution.', 'dynamic availability': @@ -164,7 +156,6 @@ module.exports = { 'Malicious actions or vulnerabilities that can be used to manipulate or compromise a system or network.', 'fair access': 'A property that ensures accessibility to network resources and functionalities for all participants, based in some Sybil protection algorithm.', - FPC: 'Fast Probabilistic Consensus; FPC is a consensus mechanism that employs a random number and node opinions to achieve consensus. In On-Tangle Voting, FPC is utilized only in specific edge cases. For more details, refer to OTVFPCS.', faucet: 'A faucet is a reservoir of tokens. Users can easily request a limited quantity of tokens for testing purposes, which proves particularly useful for app developers.', fees: 'Amount in Mana consumed by users for the creation of blocks.', @@ -185,16 +176,12 @@ module.exports = { "Full nodes constitute the network's backbone. For a full node to be part of the peer-to-peer network, it must always be online and connected to other full nodes. Moreover, it has to synchronize its transaction database with every other full node in the network. Full nodes process transactions from clients (like wallets and DApps), append them to the ledger, and share them with all other network nodes.", 'future cone': 'The future cone refers to all messages that directly or indirectly reference a particular message.', - 'generic data object': - 'In IOTA 2.0, this is the most elementary object type. All unrecognized data objects are treated as generic data objects.', 'genesis commitment': 'Every slot commitment chain starts with the genesis commitment (commitment of slot 0) in order to be considered valid.', 'genesis slot': 'The initial slot in the protocol"s timeline from which all subsequent slots are linked.', 'genesis transaction': "The Genesis transaction is the inaugural transaction that spawned all IOTA and Shimmer tokens, distributing them to the purchasers' addresses.", - 'goshimmer (no main net)': - 'GoShimmer is a prototype of IOTA’s coordinator-less version written in the Go language. GoShimmer encapsulates various Coordicide modules, like auto peering, node identities, Mana, among others. It serves as a testing ground for the first alpha version and the testnet. Components tested in GoShimmer are systematically integrated with Hornet.', 'gossip protocol': 'A protocol for relaying information among nodes in a network.', 'hash values': @@ -259,8 +246,6 @@ module.exports = { mana: 'A reward resource generated by holding IOTA tokens. It is utilized for block issuance, access to network throughput, and protecting against Sybil attacks.', 'mana burn': 'The process of consuming a specific amount of Mana to create a block. The amount of Mana burned depends on recent congestion level.', - markers: - 'In IOTA 2.0, a local tool that enhances efficiency in certain calculations, such as the computation of approval weight or determining the presence of specific messages in the past or future cone of another message.', MEV: 'Maximal or Miner Extractable Value; The potential profit that miners or validators can extract from information they glean from your transaction while it waits in the mempool.', mempool: 'Where transactions are kept in waiting before being processed and where all details of a transaction can be seen by anyone. ', @@ -295,16 +280,11 @@ module.exports = { 'A node is any computer that communicates with other nodes in the network using specific software. Essentially, nodes act as connection points for data transfers. The Tangle employs various node types, including full nodes (Hornet, Bee), permanodes (Chronicle), and smart contract nodes (Wasp).', NFT: 'Non-Fungible Token; A type of digital token that represents ownership or proof of authenticity of a unique item or asset.', 'non-validator nodes': 'Nodes in the network that are not validators.', - object: - 'In IOTA 2.0, the fundamental unit of information in the IOTA protocol. Each object possesses a type, size, and data.', oracles: 'Oracles establish a secure, decentralized bridge between digital and physical realms. They introduce off-chain data to decentralized applications and smart contracts within the network.', orphan: 'A transaction (or block) lacking references from any subsequent transaction (or block). Orphans are unconfirmed and remain excluded from consensus.', 'orphaned block': 'A block that is not accepted becomes orphaned.', - OTV: "On Tangle Voting; In IOTA 2.0, known as the multiverse consensus articulated by Hans Moog. It's a novel consensus mechanism allowing nodes to vote on conflicts by publishing a message to the tangle.", - otvfpcs: - 'In IOTA 2.0, On Tangle Voting with FPCS (Fast Probabilistic Consensus on a Set) is a method designed to resolve metastability. In IOTA 2.0, achieving high approval weight signals finality. If this weight is sufficiently high, the message/transaction is confirmed. With OTVFPC, OTV forms the initial opinion. If node opinions remain divided over time, FPC initiates to resolve this metastable state, expediting transaction finality.', outbox: 'A buffer where soon-to-be-scheduled blocks are enqueued before they are gossiped to the network.', output: @@ -313,8 +293,6 @@ module.exports = { 'A network where all nodes have equal roles and perform the same actions, running on top of another network like the internet.', 'parallel processing': 'The parallel validation of transactions without requiring total ordering. Processing can be done on multiple cores at the same time.', - 'parallel reality ledger state': - 'In IOTA 2.0, a state to monitor tangle conflicts. Two conflicting but causally valid ledger entries (e.g., Double Spend) are placed into separate "realities". These represent potential but exclusive future ledger states. The consensus mechanism, aided by FPC, operates until most nodes" perceptions align, leading to the acceptance of one true ledger state.', 'parallel write access': 'The ability for multiple participants to simultaneously write to the Tangle in the IOTA 2.0 protocol.', 'parasite chain attacks': @@ -401,8 +379,6 @@ module.exports = { 'Solidification time is when a node has received the entire history of a transaction.', solidifier: 'Ensures blocks are consistently linked to past blocks, creating solidity and preventing missing information when tracing back in time.', - solidity: - 'In IOTA 2.0, a message is marked as solid if its entire past cone up to the Genesis (or the latest snapshot) is known.', 'soul-bound token': 'Non-transferable tokens representing traits/features/achievements of a person/entity.', 'splitting attacks': @@ -490,12 +466,8 @@ module.exports = { 'The process of registering as a validator by issuing a block with a special payload type. The registration is only considered successful when the registration block and the mutating transaction get accepted', 'value extraction': 'The act of taking or deriving value from a system or network without contributing to its growth or sustainability.', - 'value layer': - 'In IOTA 2.0, the Value layer builds on the Communication layer. It works exclusively with payloads of type Value object. This layer has several responsibilities: forming the ledger state, processing, validating and outputting transactions, conflict detection, conflict resolution via FPC, forming a DAG from value objects, tip selection (on value object tips).', 'value transactions': 'Value transactions either withdraw tokens from an address or deposit them to an address. Nodes verify these transactions to ensure that the sender owns the Shimmer tokens and that additional tokens are not generated. To do this, the following checks are performed: All Shimmer tokens withdrawn from an address are also deposited into one or more other addresses; the value of each transaction does not exceed the total global supply; signatures are valid.', - 'version number': - 'In IOTA 2.0, the version number indicates the correct format of each type.', VM: 'Virtual Machine; A component responsible for executing transactions within the ledger.', 'volume and velocity': 'The capacity to handle a large number of transactions quickly, with fast confirmation times.', diff --git a/docs/learn/protocols/iota2.0/core-concepts/consensus/preliminaries.md b/docs/learn/protocols/iota2.0/core-concepts/consensus/preliminaries.md index 8d59f00d93a..2f903cec59a 100644 --- a/docs/learn/protocols/iota2.0/core-concepts/consensus/preliminaries.md +++ b/docs/learn/protocols/iota2.0/core-concepts/consensus/preliminaries.md @@ -132,11 +132,11 @@ Block references are crucial in the consensus protocol as they guide the [tip se ###### Strong -Nodes randomly select strong parents from their _tip pool_ and attach their newly issued blocks to these selected tips. The number of strong parents sets a tradeoff between [confirmation time](consensus-flags.md#confirmation-of-blocks-and-non-conflicting-transactions) and the block size. More strong parents lead to shorter confirmation times and larger block sizes. When [computing the branch](relevant-algorithms.md#algorithm-to-compute-a-blocks-branch) of a new block, the branches of strong parents are directly inherited by the _branch_ of the new block. +Nodes randomly select strong parents from their _tip pool_ and attach their newly issued blocks to these selected tips. The number of strong parents sets a tradeoff between [confirmation time](consensus-flags.md#confirmation-of-blocks-and-non-conflicting-transactions) and the block size. More strong parents lead to shorter confirmation times and larger block sizes. When [computing the branch](relevant-algorithms.md#algorithm-to-compute-a-blocks-branch) of a new block, the branches of strong parents are directly inherited by the branch of the new block. ###### Shallow Like -Shallow like references are essential for rectifying the preliminary [block's branch](relevant-algorithms.md#algorithm-to-compute-a-blocks-branch) constructed from the strong parents. They align the block's _branch_ with the issuer's [preferred reality](relevant-algorithms.md#algorithm-to-compute-the-preferred-reality). +Shallow like references are essential for rectifying the preliminary [block's branch](relevant-algorithms.md#algorithm-to-compute-a-blocks-branch) constructed from the strong parents. They align the block's branch with the issuer's [preferred reality](relevant-algorithms.md#algorithm-to-compute-the-preferred-reality). ###### Weak @@ -262,7 +262,7 @@ The set of all conflicts in the causal history of a transaction $tx$ is called t #### Branch of a block -For a block $b$, there is the branch of $b$, which is encoded through the references. This _branch_ is denoted as $Branch(b)$ and it can be computed using an [algorithm](relevant-algorithms.md#algorithm-to-compute-a-blocks-branch). +For a block $b$, there is the branch of $b$, which is encoded through the references. This branch is denoted as $Branch(b)$ and it can be computed using an [algorithm](relevant-algorithms.md#algorithm-to-compute-a-blocks-branch). #### Vote diff --git a/docs/learn/protocols/iota2.0/core-concepts/consensus/relevant-algorithms.md b/docs/learn/protocols/iota2.0/core-concepts/consensus/relevant-algorithms.md index 72fb828177c..320dceb7892 100644 --- a/docs/learn/protocols/iota2.0/core-concepts/consensus/relevant-algorithms.md +++ b/docs/learn/protocols/iota2.0/core-concepts/consensus/relevant-algorithms.md @@ -27,7 +27,7 @@ $$ removeConflicts \gets ConflictWith(addLikeBranch), $$ -The function $ConflictWith(S)$ returns the set of all conflicts conflicting with at least one element from $S$. Finally, you can define the _branch_ of the block $b$ in two steps. First: +The function $ConflictWith(S)$ returns the set of all conflicts conflicting with at least one element from $S$. Finally, you can define the branch of the block $b$ in two steps. First: $$ Branch(b)\gets \left(addStrongBranch \cup addWeakBranch \cup addLikeBranch\right) \setminus removeConflicts. diff --git a/docs/learn/protocols/iota2.0/core-concepts/consensus/tip-selection-algorithm.md b/docs/learn/protocols/iota2.0/core-concepts/consensus/tip-selection-algorithm.md index b2b0d3b9bf3..487face2238 100644 --- a/docs/learn/protocols/iota2.0/core-concepts/consensus/tip-selection-algorithm.md +++ b/docs/learn/protocols/iota2.0/core-concepts/consensus/tip-selection-algorithm.md @@ -16,7 +16,7 @@ The node selects uniformly at random at most `blockMaxParent` (or `blockTypeVali After adding a new strong parent to the list of references $L$, the node attempts to select shallow-like references to align the current [branch of the block](relevant-algorithms.md#algorithm-to-compute-a-blocks-branch) with the [preferred reality](relevant-algorithms.md#algorithm-to-compute-the-preferred-reality). -If `blockMaxParent` (or `blockTypeValidatorMaxParent`) shallow-like references are not sufficient to align the _branch_, the strong parent is removed from the list of references $L$ and moved to the weak tip pool $\mathcal{W}$, which is initialized as an empty set before running the _tip selection_ algorithm. +If `blockMaxParent` (or `blockTypeValidatorMaxParent`) shallow-like references are not sufficient to align the branch, the strong parent is removed from the list of references $L$ and moved to the weak tip pool $\mathcal{W}$, which is initialized as an empty set before running the _tip selection_ algorithm. ### 3. Weak References diff --git a/docs/learn/protocols/iota2.0/core-concepts/data-flow.md b/docs/learn/protocols/iota2.0/core-concepts/data-flow.md index 8f803e4986b..b2ba3e90322 100644 --- a/docs/learn/protocols/iota2.0/core-concepts/data-flow.md +++ b/docs/learn/protocols/iota2.0/core-concepts/data-flow.md @@ -28,7 +28,7 @@ modules control when and how many blocks can be gossiped. The _application layer_ lives on top of the _communication layer_. The _application layer_ is mainly related to objects called payloads (e.g., transactions are a type of payload). Anybody can develop applications on this layer, and nodes can choose which applications to run. Of course, these applications can also be dependent on each other. -Nodes must also run several _core application_s, such as the engine, which maintains the [ledger state](data-structures.md) and a quantity called [Mana](mana.md). Mana is a scarce resource that serves as a _Sybil protection mechanism_ and spam protection. All nodes must also run the [Approval Weight and Finality Gadget](consensus/introduction.md) application, which provides a protocol that produces consensus between nodes on whether blocks are to be included in the Tangle (instead of being orphaned) and on whether transactions inside included blocks should mutate the ledger (instead of being deemed non-mutating). Lastly, the same gadget enables nodes to reorganize their perception of the Tangle when necessary, using the _fork-choice rule_. +Nodes must also run several core applications, such as the engine, which maintains the [ledger state](data-structures.md) and a quantity called [Mana](mana.md). Mana is a scarce resource that serves as a _Sybil protection mechanism_ and spam protection. All nodes must also run the [Approval Weight and Finality Gadget](consensus/introduction.md) application, which provides a protocol that produces consensus between nodes on whether blocks are to be included in the Tangle (instead of being orphaned) and on whether transactions inside included blocks should mutate the ledger (instead of being deemed non-mutating). Lastly, the same gadget enables nodes to reorganize their perception of the Tangle when necessary, using the _fork-choice rule_. ## 4. Data Flow diff --git a/docs/learn/protocols/iota2.0/core-concepts/mana.md b/docs/learn/protocols/iota2.0/core-concepts/mana.md index 5687a973808..1caab54c34c 100644 --- a/docs/learn/protocols/iota2.0/core-concepts/mana.md +++ b/docs/learn/protocols/iota2.0/core-concepts/mana.md @@ -92,7 +92,7 @@ The purpose of BIC is to convert UTXO Mana into a form of Mana that can be used Congestion control decides whether blocks should be gossiped to _neighbors_ based on whether the Mana burned by the block is larger than a certain cost that is deterministically calculated and known upfront. By default, the wallet will try to burn exactly the cost indicated by this calculation. It is important to distinguish between **blocks** and **transactions**: congestion control only deals with blocks, which are the containers that carry transactions around the network. -Because BIC do not live on the UTXO ledger, the protocol rules do not allow them to be moved using a transaction, so they can not be transferred. This makes BIC _soulbound_ because they are bound to a single account (even though an account can still issue blocks on someone else's behalf). To ensure that the _branch_ logic and the congestion control do not become entangled, we only allot the BIC specified in the corresponding transaction upon its commitment, i.e., after any conflicts have been resolved and we are certain that the transaction is accepted. We also burn BIC when the blocks are committed to. +Because BIC do not live on the UTXO ledger, the protocol rules do not allow them to be moved using a transaction, so they can not be transferred. This makes BIC _soulbound_ because they are bound to a single account (even though an account can still issue blocks on someone else's behalf). To ensure that the branch logic and the congestion control do not become entangled, we only allot the BIC specified in the corresponding transaction upon its commitment, i.e., after any conflicts have been resolved and we are certain that the transaction is accepted. We also burn BIC when the blocks are committed to. In summary, **BIC** have the following properties From 7194cd8564d6c718170cb4816723eaa13edc3b5b Mon Sep 17 00:00:00 2001 From: Dr-Electron Date: Mon, 20 Nov 2023 13:23:58 +0100 Subject: [PATCH 2/9] Update Coordinator page --- .../getting-started/networks-endpoints.mdx | 6 ++++++ docs/learn/protocols/coordinator.md | 18 ++++++++++++++---- 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/docs/build/getting-started/networks-endpoints.mdx b/docs/build/getting-started/networks-endpoints.mdx index d295b636bc8..8f8db9f08d4 100644 --- a/docs/build/getting-started/networks-endpoints.mdx +++ b/docs/build/getting-started/networks-endpoints.mdx @@ -30,6 +30,12 @@ have more control and to not run into any limits. [The IOTA Mainnet](https://explorer.iota.org/mainnet) is the production network within the IOTA ecosystem using the IOTA token. +:::info + +This network runs under a [Coordinator PoA scheme](/learn/protocols/coordinator/) with validators operated by [Akkodis](https://www.akkodis.com), [ETO GRUPPE](https://www.etogruppe.com/), [Software AG](https://softwareag.com/), [University of Zurich](https://www.uzh.ch/cmsssl/en.html), [Imperial College London](https://www.imperial.ac.uk) and the IOTA Foundation. + +::: + | Base Token | Protocol | HTTP REST API | Event API | Permanode API | | ---------- | -------- | ------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------- | | IOTA Token | Stardust | https://api.stardust-mainnet.iotaledger.net | wss://api.stardust-mainnet.iotaledger.net:443 (MQTT 3.1, /mqtt) | https://chronicle.stardust-mainnet.iotaledger.net | diff --git a/docs/learn/protocols/coordinator.md b/docs/learn/protocols/coordinator.md index 915ef513569..11bc1ab6c2e 100644 --- a/docs/learn/protocols/coordinator.md +++ b/docs/learn/protocols/coordinator.md @@ -9,21 +9,31 @@ keywords: # The Coordinator - PoA Consensus :::note + The Coordinator is a temporary feature running under the Chrysalis and Stardust protocol versions and will be removed with the upcoming IOTA 2.0 update. + ::: -The Coordinator is a node controlled by the IOTA Foundation that sends signed blocks called milestones that nodes trust -and use to confirm blocks and reach _consensus_. Blocks which are directly or indirectly referenced by a milestone block +The Coordinator is a [node plugin](https://github.com/iotaledger/inx-tendercoo) that sends signed blocks called milestones that nodes trust +and use to confirm blocks and reach _consensus_. Blocks that are directly or indirectly referenced by a milestone block are automatically deemed confirmed, though whether they mutate the ledger depends on the [White-Flag consensus](/learn/protocols/chrysalis/core-concepts/white-flag-consensus) -approach. Before the [White-Flag consensus](/learn/protocols/chrysalis/core-concepts/white-flag-consensus) was introduced, nodes would instead compute mutations via cumulative weight -calculations. +approach. +The current Coordinator is based on the Tendermint Core BFT consensus, which enables a committee of validators to operate as a distributed Coordinator. + +:::info + +In the current Shimmer network, all instances of the Coordinator are run by the IOTA Foundation. In the IOTA Mainnet they are run by [Akkodis](https://www.akkodis.com), [ETO GRUPPE](https://www.etogruppe.com/), [Software AG](https://softwareag.com/), [University of Zurich](https://www.uzh.ch/cmsssl/en.html), [Imperial College London](https://www.imperial.ac.uk) and the IOTA Foundation. + +::: :::note + Even though the Coordinator acts as a centralized _confirmation_ device or finality gadget, it is not able to move or alter the ledger in any other way than given by the user issued transactions in the _DAG_. Therefore, the Coordinator can only censor transactions (which would be more visible than in traditional blockchains) but not actively mint or remove tokens from the ledger. + ::: Nodes within an IOTA network running under PoA via the Coordinator have its public keys saved in the configuration and From ba3fe30de6b41d2f01e6afc2921fce657597e44f Mon Sep 17 00:00:00 2001 From: Lucas Tortora <85233773+lucas-tortora@users.noreply.github.com> Date: Mon, 20 Nov 2023 11:05:18 -0300 Subject: [PATCH 3/9] Apply diataxis to Identity 1.0.0 docs --- articleRedirects.js | 100 ++++++++++ banners/identity-deprecated.mdx | 2 +- docs/build/getting-started/welcome.md | 4 +- .../docs/libraries/wasm/getting_started.mdx | 2 +- .../tutorials/validate_university_degree.mdx | 6 +- .../decentralized_identifiers/alias.mdx | 32 --- .../decentralized_identifiers/create.mdx | 60 ------ .../decentralized_identifiers/overview.mdx | 82 -------- .../docs/concepts/key_storage/key_storage.mdx | 105 ---------- .../verifiable_credentials/create.mdx | 101 ---------- .../verifiable_credentials/overview.mdx | 48 ----- .../verifiable_credentials/revocation.mdx | 72 ------- .../verifiable_presentations.mdx | 184 ------------------ .../1.0/docs/decentralized_identity.mdx | 113 ----------- .../docs/explanations/about-alias-outputs.mdx | 65 +++++++ .../decentralized-identifiers.mdx | 136 +++++++++++++ .../explanations/verifiable-credentials.mdx | 74 +++++++ .../explanations/verifiable-presentations.mdx | 40 ++++ .../rust.mdx} | 6 +- .../wasm.mdx} | 95 +++++---- .../getting_started/create_and_publish.mdx | 46 ----- .../1.0/docs/getting_started/install.mdx | 65 ------- .../1.0/docs/getting_started/overview.mdx | 40 ---- .../decentralized-identifiers/create.mdx | 181 +++++++++++++++++ .../decentralized-identifiers}/delete.mdx | 35 +++- .../decentralized-identifiers}/resolve.mdx | 36 +++- .../decentralized-identifiers}/update.mdx | 138 +++++++------ .../domain-linkage/create-and-verify.mdx} | 65 +++++-- .../1.0/docs/how-tos/key-storage.mdx | 152 +++++++++++++++ .../how-tos/verifiable-credentials/create.mdx | 160 +++++++++++++++ .../verifiable-credentials/revocation.mdx | 129 ++++++++++++ .../create-and-validate.mdx | 164 ++++++++++++++++ .../identity.rs/1.0/docs/introduction.mdx | 68 ------- .../1.0/docs/libraries/overview.mdx | 14 -- .../api/wasm.mdx} | 2 +- .../specifications/iota-did-method-spec.mdx} | 8 +- .../specifications}/overview.mdx | 6 +- .../revocation-bitmap-2022.mdx} | 2 +- .../1.0/docs/specs/did/overview.mdx | 11 -- docs/build/identity.rs/1.0/docs/welcome.mdx | 91 +++++++++ docs/build/identity.rs/1.0/sidebars.js | 101 +++++----- .../tutorials/in-app-tutorial.md | 6 +- .../HomeLayout/AppLibrariesSection.tsx | 6 +- 43 files changed, 1605 insertions(+), 1248 deletions(-) delete mode 100644 docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/alias.mdx delete mode 100644 docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/create.mdx delete mode 100644 docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/overview.mdx delete mode 100644 docs/build/identity.rs/1.0/docs/concepts/key_storage/key_storage.mdx delete mode 100644 docs/build/identity.rs/1.0/docs/concepts/verifiable_credentials/create.mdx delete mode 100644 docs/build/identity.rs/1.0/docs/concepts/verifiable_credentials/overview.mdx delete mode 100644 docs/build/identity.rs/1.0/docs/concepts/verifiable_credentials/revocation.mdx delete mode 100644 docs/build/identity.rs/1.0/docs/concepts/verifiable_credentials/verifiable_presentations.mdx delete mode 100644 docs/build/identity.rs/1.0/docs/decentralized_identity.mdx create mode 100644 docs/build/identity.rs/1.0/docs/explanations/about-alias-outputs.mdx create mode 100644 docs/build/identity.rs/1.0/docs/explanations/decentralized-identifiers.mdx create mode 100644 docs/build/identity.rs/1.0/docs/explanations/verifiable-credentials.mdx create mode 100644 docs/build/identity.rs/1.0/docs/explanations/verifiable-presentations.mdx rename docs/build/identity.rs/1.0/docs/{libraries/rust/getting_started.mdx => getting-started/rust.mdx} (93%) rename docs/build/identity.rs/1.0/docs/{libraries/wasm/getting_started.mdx => getting-started/wasm.mdx} (77%) delete mode 100644 docs/build/identity.rs/1.0/docs/getting_started/create_and_publish.mdx delete mode 100644 docs/build/identity.rs/1.0/docs/getting_started/install.mdx delete mode 100644 docs/build/identity.rs/1.0/docs/getting_started/overview.mdx create mode 100644 docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/create.mdx rename docs/build/identity.rs/1.0/docs/{concepts/decentralized_identifiers => how-tos/decentralized-identifiers}/delete.mdx (54%) rename docs/build/identity.rs/1.0/docs/{concepts/decentralized_identifiers => how-tos/decentralized-identifiers}/resolve.mdx (67%) rename docs/build/identity.rs/1.0/docs/{concepts/decentralized_identifiers => how-tos/decentralized-identifiers}/update.mdx (77%) rename docs/build/identity.rs/1.0/docs/{concepts/domain_linkage/domain_linkage.mdx => how-tos/domain-linkage/create-and-verify.mdx} (56%) create mode 100644 docs/build/identity.rs/1.0/docs/how-tos/key-storage.mdx create mode 100644 docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/create.mdx create mode 100644 docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/revocation.mdx create mode 100644 docs/build/identity.rs/1.0/docs/how-tos/verifiable-presentations/create-and-validate.mdx delete mode 100644 docs/build/identity.rs/1.0/docs/introduction.mdx delete mode 100644 docs/build/identity.rs/1.0/docs/libraries/overview.mdx rename docs/build/identity.rs/1.0/docs/{libraries/wasm/api_reference.mdx => references/api/wasm.mdx} (99%) rename docs/build/identity.rs/1.0/docs/{specs/did/iota_did_method_spec.mdx => references/specifications/iota-did-method-spec.mdx} (94%) rename docs/build/identity.rs/1.0/docs/{specs => references/specifications}/overview.mdx (56%) rename docs/build/identity.rs/1.0/docs/{specs/revocation_bitmap_2022.mdx => references/specifications/revocation-bitmap-2022.mdx} (99%) delete mode 100644 docs/build/identity.rs/1.0/docs/specs/did/overview.mdx create mode 100644 docs/build/identity.rs/1.0/docs/welcome.mdx diff --git a/articleRedirects.js b/articleRedirects.js index 38db2dddb67..70a1b92c8d6 100644 --- a/articleRedirects.js +++ b/articleRedirects.js @@ -542,4 +542,104 @@ exports.articleRedirects = [ from: '/use/wallets/what-is-a-wallet', to: '/get-started/wallets/firefly', }, + { + from: '/identity.rs/concepts/decentralized_identifiers/alias/', + to: '/identity.rs/explanations/about-alias-outputs/', + }, + { + from: '/identity.rs/concepts/decentralized_identifiers/create/', + to: '/identity.rs/how-tos/decentralized-identifiers/create/', + }, + { + from: '/identity.rs/concepts/decentralized_identifiers/delete/', + to: '/identity.rs/how-tos/decentralized-identifiers/delete/', + }, + { + from: '/identity.rs/concepts/decentralized_identifiers/overview/', + to: '/identity.rs/explanations/decentralized-identifiers/', + }, + { + from: '/identity.rs/concepts/decentralized_identifiers/resolve/', + to: '/identity.rs/how-tos/decentralized-identifiers/resolve/', + }, + { + from: '/identity.rs/concepts/decentralized_identifiers/update/', + to: '/identity.rs/how-tos/decentralized-identifiers/update/', + }, + { + from: '/identity.rs/concepts/domain_linkage/', + to: '/identity.rs/how-tos/domain-linkage/create-and-verify/', + }, + { + from: '/identity.rs/concepts/key_storage/', + to: '/identity.rs/how-tos/key-storage/', + }, + { + from: '/identity.rs/concepts/verifiable_credentials/create/', + to: '/identity.rs/how-tos/verifiable-credentials/create/', + }, + { + from: '/identity.rs/concepts/verifiable_credentials/overview/', + to: '/identity.rs/explanations/verifiable-credentials/', + }, + { + from: '/identity.rs/concepts/verifiable_credentials/revocation/', + to: '/identity.rs/how-tos/verifiable-credentials/revocation/', + }, + { + from: '/identity.rs/concepts/verifiable_credentials/verifiable_presentations/', + to: '/identity.rs/explanations/verifiable-presentations/', + }, + { + from: '/identity.rs/decentralized_identity/', + to: '/identity.rs/explanations/decentralized-identifiers/', + }, + { + from: '/identity.rs/getting_started/create_and_publish/', + to: '/identity.rs/how-tos/decentralized-identifiers/create/', + }, + { + from: '/identity.rs/getting_started/install/', + to: '/identity.rs/getting-started/rust/', + }, + { + from: '/identity.rs/getting_started/overview/', + to: '/identity.rs/getting-started/rust/', + }, + { + from: '/identity.rs/introduction/', + to: '/identity.rs/welcome/', + }, + { + from: '/identity.rs/libraries/overview/', + to: '/identity.rs/welcome/', + }, + { + from: '/identity.rs/libraries/rust/getting_started/', + to: '/identity.rs/getting-started/rust/', + }, + { + from: '/identity.rs/libraries/wasm/api_reference/', + to: '/identity.rs/references/api/wasm/', + }, + { + from: '/identity.rs/libraries/wasm/getting_started/', + to: '/identity.rs/getting-started/wasm/', + }, + { + from: '/identity.rs/specs/did/iota_did_method_spec/', + to: '/identity.rs/references/specifications/iota-did-method-spec/', + }, + { + from: '/identity.rs/specs/did/overview/', + to: '/identity.rs/references/specifications/overview/', + }, + { + from: '/identity.rs/specs/overview/', + to: '/identity.rs/references/specifications/overview/', + }, + { + from: '/identity.rs/specs/revocation_bitmap_2022/', + to: '/identity.rs/references/specifications/revocation-bitmap-2022/', + }, ]; diff --git a/banners/identity-deprecated.mdx b/banners/identity-deprecated.mdx index ee325efc7f8..271441c16e4 100644 --- a/banners/identity-deprecated.mdx +++ b/banners/identity-deprecated.mdx @@ -1 +1 @@ -This version of IOTA Identity is deprecated. Please upgrade to [Identity 0.6 for Chrysalis Networks](/identity.rs/introduction/) and follow the migration instructions for upgrading Stronghold Snapshot files [here](/identity.rs/tutorials/migrate-stronghold/), or upgrade to the latest version of [IOTA Identity for Stardust Networks](/identity.rs/0.7/introduction/). +This version of IOTA Identity is deprecated. Please upgrade to [Identity 0.6 for Chrysalis Networks](/identity.rs/welcome/) and follow the migration instructions for upgrading Stronghold Snapshot files [here](/identity.rs/tutorials/migrate-stronghold/), or upgrade to the latest version of [IOTA Identity for Stardust Networks](/identity.rs/0.7/introduction/). diff --git a/docs/build/getting-started/welcome.md b/docs/build/getting-started/welcome.md index db6c577debe..f3c69cc36e1 100644 --- a/docs/build/getting-started/welcome.md +++ b/docs/build/getting-started/welcome.md @@ -38,8 +38,8 @@ tokens and NFTs, and more. ### Identity -You can use the [IOTA Identity Framework](/identity.rs/introduction) to create and manage -[Self-Sovereign Identities (SSI)](/identity.rs/decentralized_identity) for people, organizations, or +You can use the [IOTA Identity Framework](/identity.rs/welcome) to create and manage +[Self-Sovereign Identities (SSI)](/identity.rs/explanations/decentralized-identifiers) for people, organizations, or any object in a GDPR-compliant, cost-efficient, and privacy-enabling manner. ## Layer 2 diff --git a/docs/build/identity.rs/0.6/docs/libraries/wasm/getting_started.mdx b/docs/build/identity.rs/0.6/docs/libraries/wasm/getting_started.mdx index 6e8373c265e..ed745a94422 100644 --- a/docs/build/identity.rs/0.6/docs/libraries/wasm/getting_started.mdx +++ b/docs/build/identity.rs/0.6/docs/libraries/wasm/getting_started.mdx @@ -17,7 +17,7 @@ keywords: > This is the beta version of the official WASM bindings for [IOTA Identity](https://github.com/iotaledger/identity.rs). -## [API Reference](/identity.rs/libraries/wasm/api_reference) +## [API Reference](./api_reference.mdx) ## [Account Examples](https://github.com/iotaledger/identity.rs/blob/support/v0.6/bindings/wasm/examples-account/README.md) diff --git a/docs/build/identity.rs/0.6/docs/tutorials/validate_university_degree.mdx b/docs/build/identity.rs/0.6/docs/tutorials/validate_university_degree.mdx index e7b65d81461..fa92ffe83f9 100644 --- a/docs/build/identity.rs/0.6/docs/tutorials/validate_university_degree.mdx +++ b/docs/build/identity.rs/0.6/docs/tutorials/validate_university_degree.mdx @@ -79,7 +79,7 @@ npm run start create-did alice alice-password This will create a minimal DID document for alice, and publish it to the Tangle. A Stronghold file `alice.hodl` will be created under `/stronghold-files` which contains the Account's state and the private key of the main verification method of the DID. `alice-password` will be used as a password for the stronghold storage. Obviously this password must be more secure in production applications. -See [Creating a Decentralized Identity](/identity.rs/concepts/decentralized_identifiers/create) for more information about generating DIDs. +See [Creating a Decentralized Identity](../concepts/decentralized_identifiers/create.mdx) for more information about generating DIDs. ### 2. **Issuer**: Create a DID @@ -94,7 +94,7 @@ with that `uni-of-oslo.hodl` will be created under `/stronhold-files`. ### 3. **Issuer**: Add a Verification Method Since the university will need to issue a signed verifiable credential for Alice, a verification method should be added to the university's DID document. -Read more about adding verification methods in [update DID Documents](/identity.rs/concepts/decentralized_identifiers/update). +Read more about adding verification methods in [update DID Documents](../concepts/decentralized_identifiers/update.mdx). To add a Verification Method the following command can be used: @@ -123,7 +123,7 @@ npm run start create-vm alice alice-password key-1 ### 5: **Issuer**: Create Revocation list -In order for the issuer to be able to revoke credentials in the future, a revocation list is needed. See [Verifiable Credential Revocation](/identity.rs/concepts/verifiable_credentials/revocation) for further details. +In order for the issuer to be able to revoke credentials in the future, a revocation list is needed. See [Verifiable Credential Revocation](../concepts/verifiable_credentials/revocation.mdx) for further details. The following command can be used to create a revocation list: ```bash diff --git a/docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/alias.mdx b/docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/alias.mdx deleted file mode 100644 index 1e7dcdf10a4..00000000000 --- a/docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/alias.mdx +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Alias Output -sidebar_label: Alias Output -description: UTXO Alias Ouput -image: /img/Identity_icon.png -keywords: - - public keys - - utxo - - Method Specification - - Decentralized Identifiers - - overview - - DLT ---- - -# Alias Output - -The IOTA method uses the IOTA ledger which uses the [unspent transaction output (_UTXO_) model](/learn/protocols/chrysalis/core-concepts/switch-to-UTXO/). Also, the features of the [Stardust](/introduction/stardust/explanations/what_is_stardust) upgrade are fundamental to the IOTA DID method. - -The Alias _Output_ is used for storing the DID Document on the ledger. It is a specific implementation of the UTXO _state machine_ that can hold arbitrary data in its `State Metadata`. The Alias Output has two kinds of controllers, a state controller and a governor. A state controller can execute a state transition which allows updating the data in the `State Metadata`. The governor, on the contrary, can't update the `State Metadata` but can change both controllers and destroy the Alias Output. -A controller can be either Ed25519 Address, Alias Address or an _NFT_ Address and at most one of each can be set for an Alias Output. - -In order to create a new Alias Output, a transaction must be made that includes another Output, for example a Basic Output, as input and the new Alias Output, along with other outputs if needed, as outputs. - -### Storage Deposit - -The arbitrary data stored in the `State Metadata` of the Alias output must be covered by a storage deposit using IOTA coins. This helps to control the ledger size from growing uncontrollably while guaranteeing the data is indefinitely stored on the ledger which is important for resolving DID Documents. This deposit is fully refundable and can be reclaimed when the output is destroyed. Both, the state controller and the governor can control the IOTA coins stored in the Alias Output. _Nodes_ expose an API to calculate the required deposit depending on the size of the data stored. - -### Alias Id - -Each Alias Output has an `Alias ID`. This ID is assigned after a transaction creates a new Alias Output. The actual DID is derived from this `Alias ID`, hence it is be unknown before publishing the transaction. Consequently, the DID inside the `State Metadata` will be replaced by the placeholder `did:0:0` to indicate self. - -If a transaction has an Alias Output as input, its `Alias ID` can be kept by one of its outputs. This feature is necessary for updating the DID Documents since the DID itself is derived from the Alias Output. diff --git a/docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/create.mdx b/docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/create.mdx deleted file mode 100644 index 9ec7285033a..00000000000 --- a/docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/create.mdx +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Creating a Decentralized Identity -sidebar_label: Create and Publish -description: Create DID Documents and publish them to the Tangle -image: /img/Identity_icon.png -keywords: - - Documents - - DID - - Tangle - - Create - - Publish ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -When someone or something wants to benefit from Self-Sovereign Identity, they must first create a Decentralized Identity. This identity consists of many parts that have different functions. This page will cover both the basics and the details about identity creation and publishing. - -## Creating an Identity - - - - -```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs -``` - - - - -```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts -``` - - - - -This examples creates a new address with funds using the _faucet_ on a private network. Next, it creates a new DID Document with a verification method. This DID Document is then published in an Alias Output making the DID available in the ledger state and resolvable by any node. - -Note that using the faucet is only possible on private networks or public testnets. Once the Stardust update is released on the Shimmer network or the IOTA network, an output with actual Shimmer or IOTA funds is required to create a new Alias Output that represents a DID. - -Updating the identity is also possible, which will be discussed in the next section, but all previous states of the DID Document will still be stored in permanodes or any third party recording the network activity. - -### Identity Generation Process - -In order to create a Alias Output, an existing output is required to make a transaction. For that a new Address is generated and a Basic Output controlled by this address is created using the faucet. - -A DID Document is then created which includes one verification method. At this point the DID itself is unknown since the Alias Output is not published yet and didn't get an `Alias ID` assigned. For that a placeholder `did:iota:0x0000000000000000000000000000000000000000000000000000000000000000` is used to reference the DID inside the document. - -An Alias Output is created which contains an encoded version of the DID Document in its `State Metadata` and has the state controller and the governor set to the generated Ed25519 address. Note that controllers don't have to be Ed25519 addresses, they can be any type of output. However, they must be unlocked in order perform a state or governance transition when the DID Document is updated or destroyed. - -The byte cost for the document is then automatically calculated and a new transaction is published that includes the Basic Output as input and the newly generated Alias Output as output as well as a Basic Output which contains the remaining IOTA coins. - -Once the transaction is confirmed, the `Alias ID` would be assigned and the DID can be derived from it. Now The DID Document is stored on the ledger and can be resolved using any node. See the further examples for [updating](./update.mdx) and [resolving](./resolve.mdx) DID. - -## Running a private network - -In order to run the examples, a private network (sometimes also called a private Tangle) needs to run locally. You can refer to [Hornet wiki](https://github.com/iotaledger/hornet/tree/develop/private_tangle) for instructions on how to run a private network. - -If your local private network uses different ports than Hornet, modify the API and faucet endpoints in the examples to match your local setup. diff --git a/docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/overview.mdx b/docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/overview.mdx deleted file mode 100644 index ce240db6540..00000000000 --- a/docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/overview.mdx +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: DID Introduction -sidebar_label: Introduction -description: The Decentralized Identifiers (DID) standard from W3C is the fundamental standard that supports the concept of a decentralized digital identity. Explore the basic aspects of the DID standard. -image: /img/Identity_icon.png -keywords: - - public keys - - Method Specification - - Decentralized Identifiers - - overview - - DLT ---- - -# Decentralized Identifiers (DID) - -A DID is a unique identifier that can be resolved to a DID Document. This document contains data such as public keys, enabling the holder to prove ownership over their personal data, but also URIs that link to public information about the identity. DIDs are the fundamental building blocks of decentralized digital identity. -This implementation complies to the [DID specifications v1.0](https://www.w3.org/TR/did-core//) from the World Wide Web Consortium (W3C). - -In the IOTA Identity framework, we have implemented the DID standard according to the `iota` [DID Method Specification](../../specs/did/iota_did_method_spec.mdx). Other implementations of DID on IOTA must follow the `iota` DID Method Specification if they also want to use the `iota` method name. It should not be necessary to re-implement the specification, if you can use library though. - -An example of a DID conforming to the `iota` method specification: -`did:iota:0xe4edef97da1257e83cbeb49159cfdd2da6ac971ac447f233f8439cf29376ebfe` - -## Chapter Overview - -In this chapter, we will explain the basic aspects of the DID standard. We will explore the how and why of DID Documents and why IOTA is a very suitable technology to host the DID Documents and the rest of a Self-Sovereign Identity (SSI) Framework. - -## Decentralized Identifiers - -A Decentralized Identifier, or DID, is a unique identifier that is tied to a subject. This subject can be anything, like a person, an organization, an IoT device, or even an object. The identifier can be used by the subject to identify themselves through a digital format, providing a basis for online identification. The identifier looks like a set of random characters that includes some prefixes to determine which standard and implementation is used: - -`did:iota:0xe4edef97da1257e83cbeb49159cfdd2da6ac971ac447f233f8439cf29376ebfe` - -The World Wide Web Consortium (W3C) is a well-known standardization body that has standardized how DIDs should look and work. This provides a basis for different technologies that implement the DID standard to achieve interoperability. A full list of all implementations can be found [here.](https://www.w3.org/TR/did-spec-registries/#did-methods) Please keep in mind that unfortunately most of these methods are outdated and not maintained. - -## DID Documents - -The purpose of a DID is to help navigate to a DID Document, which is a document containing more information regarding the identity subject. This document contains data such as public keys, enabling the subject to prove ownership over their personal data, but can contain additional information on how to interact with the subject. - -The identifier contains all information to resolve a DID, providing the latest DID Document. The first three characters `did` indicate that the DID standard from W3C must be used to resolve the identifier. It is followed by a unique method name, in our case `iota`, to indicate that the IOTA method is used. The IOTA method is a specific implementation following the [IOTA DID Method Specification](../../specs/did/iota_did_method_spec.mdx). This provides unique rules for the protocol to follow in order to manage a DID Document. In our case, it describes how DID Documents are uploaded and queried to and from the IOTA ledger. Lastly, a DID contains a set of random characters that are unique per identity, this makes the identity unique and makes sure every identity resolves to a unique DID Document. - -:::tip Requires basic knowledge of Asymmetric Encryption - -The following and later sections require some basic knowledge of Asymmetric Encryption. Please read or view some materials on the subject before continuing. - -::: - -A DID Document mostly contains two important pieces of data: public keys and services. The public keys can be used to prove ownership over the identity, by cryptographically signing something with the associated private key. The public key can be used to verify that the identity subject signed the data and therefore controls the private key. Ownership over the private keys, therefore, proves ownership over the identity. This also means that it is very important to keep the private keys safe and secure. In addition, the public keys allow users to send encrypted data to the identity, using their public key, that only the identity owner can decrypt. - -:::caution - -Never share your private keys, seeds, passphrases with anyone. Not even IOTA Foundation members. This may lead to loss of IOTA funds or control over your own digital identity. - -::: - -Services are URIs that point to more information about the identity. This could be something as simple as a website for an organizational identity. These services are publicly available for all to read and should therefore not contain Personal Identifiable Information (PII) in the case of human identities. - -## Why use DIDs? - -DIDs allow any subject to have a unique identifier, that they can prove ownership of and at the same time provide a way to send them encrypted messages. The Identity is Self-Sovereign, meaning the subject is in control of when the identity is created but also destroyed. - -DIDs become more interesting in combination with Verifiable Credentials, which will be covered in a later section. In essence, Verifiable Credentials (VCs) are signed statements by trusted third parties about a certain identity. The signer, or Issuer, is referenced by the DID and so is the subject, often called the Holder. The Holder controls a copy of this statement and share it with other parties, the Verifiers, that can verify the statement and check which party made the statement, without having to ask the Issuer. Instead, they can verify the signature of the Issuer by checking the Issuers DID Document. This whole setup puts Holders back in control over their own data, but also makes the data much more trustworthy as it has become verifiable. - -## Why use IOTA Identity over other implementations? - -IOTA Identity is a framework to implement Self-Sovereign Identities on IOTA. Inherently, IOTA provides some unique features that have a major impact on the usability of the framework. - -### IOTA ledger benefits - -As DID Documents are stored in the ledger state by being covered by the storage deposit, this guarantees that all nodes will have an up-to-date copy of the latest DID Document. Resolving a DID into its document can usually be done by any IOTA node in the network. This solves many issues regarding availability, accessibility or synchronization. - -### Layer1 interactions - -DID Document are stored in an Alias Outputs, this allows them to directly interact with Layer 1 artifacts like NFTs and native assets. For instance an Alias Output representing a DID can hold native assets or control NFTs. Transferring funds between DIDs is also possible on Layer 1. - -### Ease-of-use - -Iota Identity helps with abstracting the details of the DID standard by providing easy-to-use APIs that allow standardized behavior. It also allows more flexible and complex management of DID Documents. - -### Storage solution - -IOTA Identity provides a [Stronghold](/stronghold.rs/welcome/ 'Stronghold is an open-source software library that was originally built to protect IOTA Seeds, but can be used to protect any digital secret.') solution for managing secrets securely, without requiring developers to reinvent the security wheel. diff --git a/docs/build/identity.rs/1.0/docs/concepts/key_storage/key_storage.mdx b/docs/build/identity.rs/1.0/docs/concepts/key_storage/key_storage.mdx deleted file mode 100644 index 582019f4a43..00000000000 --- a/docs/build/identity.rs/1.0/docs/concepts/key_storage/key_storage.mdx +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Key Storage -sidebar_label: Key Storage -description: Explain the use of the storage interfaces and how they can be implemented -image: /img/Identity_icon.png -keywords: - - key storage - - storage interfaces - - json web key - - json web algorithm - - signing ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -## Introduction - -The `JwkDocumentExt` API allows modifying a DID document like adding new verification methods. It enables storing the secrets that verification methods represent in a secure manner. It does so by using the two storage interfaces, namely the `JwkStorage` and `KeyIdStorage`. We'll refer to both of these as the _key storage_. In this section, we will go into more depth on those interfaces, and how to implement them yourself. - -The key idea behind the key storage is strongly inspired by the architecture of key management systems (KMS) or secure enclaves: once private keys are entered into the system, they can never be retrieved again. Instead, all operations using the key will have to go through that system. This approach is what allows the key storage to be architected more securely than simply storing and loading private keys from a regular database. Of course, the security is directly dependent on the concrete implementation, which is why we provide one such implementation by default, using [Stronghold](https://github.com/iotaledger/stronghold.rs/), a best-effort in-software enclave. However, there are cases where one cannot use `Stronghold` or may want to integrate key management of identities into their own KMS or similar, which is why the key storage is an abstraction over such systems. Any implementation of a key storage can then be used by the `JwkDocumentExt` API. - -The two interfaces making up the key storage have two respective responsibilities. - -:::info -Even though there are two separate interfaces, they can be implemented using the same backing storage, if desired. -::: - -A brief overview of those functions: - -- `JwkStorage`: CRUD and signing operations on [JSON Web Keys](https://www.rfc-editor.org/rfc/rfc7517). - - `generate`: Generate a new key represented as a JSON Web Key. - - `insert`: Insert an existing JSON Web Key into the storage. - - `sign`: Signs the provided data using the stored private key. - - `delete`: Permanently deletes a key. - - `exists`: Returns whether a key exists. -- `KeyIdStorage`: Stores the mappings from verification methods to their corresponding key identifier in the `JwkStorage`. - - `insert_key_id`: Inserts a mapping from a verification method identifier to a key identifier. - - `get_key_id`: Returns the key identifier for a given verification method identifier. - - `delete_key_id`: Deletes a mapping. - -## Key Identifier - -A `JwkStorage` stores and operates on keys and so they must be identified. In general, Key Management Systems use some form of an identifier for their keys. To abstract over those, the `JwkStorage` interface has a general-purpose `KeyId` type, which is effectively a wrapper around a string. -A `KeyIdStorage` is needed to store the key id that represents the private key for a given verification method. To that end a verification method itself must be identified. While within a document, each fragment must be unique, the same is not true given multiple documents, hence why we cannot only rely on fragments if we don't want to partition the `KeyIdStorage` by DID. The solution to this is using a `MethodDigest`, a hash over a verification method. When following best security practices, each verification method has its own key associated, and thus a unique public key. That, plus the fragment of a method ensures the `MethodDigest` is unique. -So in essence, a `JwkStorage` stores a `KeyId -> JWK` mapping while a `KeyIdStorage` stores a `MethodDigest -> KeyId` mapping. - -:::caution -Given the construction and limitations of the method digest, no two documents should contain a method that shares both the same fragment and public key. This should not happen under typical circumstances, but is good to keep in mind. -::: - -## Key Types - -To express what key types a given `JwkStorage` implementation supports , the `KeyType` is used, which is another simple wrapper around a string. - -:::info -The reason for this design might seem odd in Rust, given the existence of associated types. This more simplistic design is necessary to accommodate implementing the interface via the bindings to the library. -::: - -Implementations are expected to export constants of the key types they support, so users have an easy way to discover the supported types. -In general, storage implementations are free to support any [JSON Web Algorithm](https://www.rfc-editor.org/rfc/rfc7518.html)-compatible key, however the recommended default used by IOTA Identity is the `EdDSA` algorithm with curve `Ed25519`. - -## Implementation - -The IOTA Identity library ships two implementations of key storage. The `JwkMemStore` and `KeyIdMemstore` are insecure in-memory implementations intended as example implementations and for testing. The default key storage implementation is `Stronghold`, which is an example of a storage that implements both storage interfaces simultaneously. `Stronghold` may be interesting for implementers to look at, too, as it needs to deal with some challenges the in-memory version does not have to deal with. Note that the `Stronghold` implementation is only available in Rust. - -This section will detail some common challenges and embeds the `MemStore` implementations in Rust and TypeScript. - -### Examples - -This section shows the Rust and TypeScript Memstore implementations. - - - - -```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/lib/jwk_storage.ts -``` - - - - -```rust reference -https://github.com/iotaledger/identity.rs/blob/main/identity_storage/src/key_storage/memstore.rs -``` - - - - - - - -```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/lib/key_id_storage.ts -``` - - - - -```rust reference -https://github.com/iotaledger/identity.rs/blob/main/identity_storage/src/key_id_storage/memstore.rs -``` - - - diff --git a/docs/build/identity.rs/1.0/docs/concepts/verifiable_credentials/create.mdx b/docs/build/identity.rs/1.0/docs/concepts/verifiable_credentials/create.mdx deleted file mode 100644 index f1d9b47c2b6..00000000000 --- a/docs/build/identity.rs/1.0/docs/concepts/verifiable_credentials/create.mdx +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Create a Verifiable Credential -sidebar_label: Create and Sign -description: Explain how a VC is created and verified -image: /img/Identity_icon.png -keywords: - - verifiable - - credentials - - Create - - sign ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -A [verifiable credential (VC)](./overview.mdx) can represent all -information that a physical credential represents, such as a passport or university -degree. However, by allowing other parties to cryptographically verify the authorship -and integrity of the claims, verifiable credentials can be seen as more tamper-evident -and more trustworthy than their physical counterparts. - -In the IOTA Identity Framework you can create a Verifiable Credential with the following properties: - -- [**Context**](https://www.w3.org/TR/vc-data-model/#contexts): list of JSON-LD context URIs. Includes `"https://www.w3.org/2018/credentials/v1"` by default. -- [**Types**](https://www.w3.org/TR/vc-data-model/#types): list of types describing the credential. Includes `"VerifiableCredential"` by default. -- [**Subject**](https://www.w3.org/TR/vc-data-model/#credential-subject): the claims of the issuer; a set of objects that contain one or more properties that are each related to a subject. -- [**Issuer**](https://www.w3.org/TR/vc-data-model/#issuer): the identifier of the issuer, typically their DID. -- [**ID**](https://www.w3.org/TR/vc-data-model/#identifiers): optional URI identifier for the credential. -- [**Issuance Date**](https://www.w3.org/TR/vc-data-model/#issuance-date): optional timestamp for expressing the date and time when a credential becomes valid. -- [**Expiration Date**](https://www.w3.org/TR/vc-data-model/#expiration): optional timestamp for expressing the date and time when a credential ceases to be valid. -- [**Status**](https://www.w3.org/TR/vc-data-model/#status): optional information used to determine the current status of a credential, i.e. whether or not it has been [revoked](./revocation.mdx). -- [**Schema**](https://www.w3.org/TR/vc-data-model/#data-schemas): optional list of objects specifying the schema that the data must conform to. -- [**Refresh Service**](https://www.w3.org/TR/vc-data-model/#refreshing): optional link to a service where the recipient may refresh the included credentials. -- [**Terms of Use**](https://www.w3.org/TR/vc-data-model/#terms-of-use): optional list of policies defining obligations, prohibitions, or permissions of the presentation recipient. -- [**Evidence**](https://www.w3.org/TR/vc-data-model/#evidence): optional list of objects that can be used by the issuer to provide the verifier with additional supporting information in a verifiable credential. -- [**Non-Transferable**](https://www.w3.org/TR/vc-data-model/#nontransferable-property): optional flag that indicates that a verifiable credential must only be encapsulated in a [verifiable presentation](./verifiable_presentations.mdx) whose proof was issued by the credential subject. - -## Signing {#signing} - -After creation, the issuer signs the verifiable credential using one of their private keys, embedding the digital signature in its [proof](https://www.w3.org/TR/vc-data-model/#proofs-signatures) section. This is what allows verifiers to independently validate the credential using the corresponding public key from the issuer's DID Document. - -### Proof Options {#proof-options} - -A digital signature on a verifiable credential both provides data integrity and proves the DID of the issuer. -The proof section embedded in a credential may also include additional metadata. - -The following metadata properties can be configured by the framework and are optional and omitted by default: - -- **Created**: timestamp of when the credential was signed, recommended. -- **Expires**: timestamp after which the signature is no longer considered valid. Implementers should prefer to set the dedicated **Expiration Date** property on credentials instead. -- **Proof Purpose**: indicates the purpose of the signature. - - **AssertionMethod**: to assert a claim. The signing verification method must have an [`assertionMethod`](https://www.w3.org/TR/did-core/#assertion) relationship to be valid. - - **Authentication**: to authenticate the signer. The signing verification method must have an [`authentication`](https://www.w3.org/TR/did-core/#authentication) relationship to be valid. - -Most verifiable credentials should be signed with the assertion method proof purpose to clearly indicate that the signature is asserting a claim and restrict it to valid verification methods. Whereas a proof may be attached to a [verifiable presentation](./verifiable_presentations.mdx) for authentication purposes. - -Other metadata fields such as `challenge` and `domain` may be included, however they are more pertinent for [verifiable presentations](./verifiable_presentations.mdx). - -## Validation {#validation} - -Verifiers should ensure certain properties of a credential are valid when receiving one or more in a [verifiable presentation](./verifiable_presentations.mdx). Both issuers and holders may also wish to validate their credentials, particularly directly after creating or receiving one. Validation may be performed at any point in time and can be a useful way of checking whether a credential has expired or been revoked. - -The IOTA Identity Framework supports the following checks during credential validation: - -- **Semantic structure**: ensures the credential adheres to the specification. -- **Proof**: verifies the signature against the DID Document of the issuer. -- **Optional validations**: additional checks on credential properties and the signature can be configured by specifying [Validation Options](#validation-options). - -### Validation Options {#validation-options} - -These options specify conditions that specific properties in a credential must satisfy. - -- **Expiry Date**: check that the [`expirationDate`](https://www.w3.org/TR/vc-data-model/#expiration) property, if present, is not before a specific datetime. Defaults to the current datetime if unset. -- **Issuance Date**: check that that [`issuanceDate`](https://www.w3.org/TR/vc-data-model/#issuance-date) property, if present, is not after a specific datetime. Defaults to the current datetime if unset. -- **Verifier Options**: validates aspects of the credential signature and its metadata, see [Proof Options](#proof-options). - -### Sharing Verifiable Credentials {#sharing-verifiable-credentials} - -A [verifiable presentation](./verifiable_presentations.mdx) is the recommended data format for sharing one or more verifiable credentials, as it provides cryptographic means of proving the DID of the holder presenting them, and for enforcing [subject-holder relationships](https://www.w3.org/TR/vc-data-model/#subject-holder-relationships). See the [Verifiable Presentations](./verifiable_presentations.mdx) page for further detail. - -## Example - -The following code exemplifies how an issuer can create, sign, and validate a verifiable credential. In this example, the issuer signs a UniversityDegreeCredential with Alice's name and DID. -This Verifiable Credential can be [verified by anyone](./verifiable_presentations.mdx), allowing Alice to take control of it and share it with anyone. - - - - -```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/5_create_vc.rs -``` - - - - -```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/5_create_vc.ts -``` - - - diff --git a/docs/build/identity.rs/1.0/docs/concepts/verifiable_credentials/overview.mdx b/docs/build/identity.rs/1.0/docs/concepts/verifiable_credentials/overview.mdx deleted file mode 100644 index e4e8f10d884..00000000000 --- a/docs/build/identity.rs/1.0/docs/concepts/verifiable_credentials/overview.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Verifiable Credentials Overview -sidebar_label: Overview -description: Verifiable Credentials are statements about the holder. They can be verified online or in person, and the holder decides who to share them with. -image: /img/Identity_icon.png -keywords: - - verifiable - - credentials - - person ---- - -Credentials are statements about an entity, such as properties that the entity possesses or capabilities that they have (like drivers licences, passports, or a person's age). Verifiable Credentials (VCs) are statements (eg. Alice has a drivers licence) that can be cryptographically verified by a third party, either online or in person. Additionally, the holder of the VC decides what is shared and who it is shared with. - -There are several types of actors that play different roles in a verifiable credential system. We'll start with a common example of how things work in the world today using physical credentials and centralized databases, and outline the roles that various entities play in the Verifiable Credential system. - -:::tip Example - Passport Issuance - -A government (the _Issuer_) issues a passport asserting citizenship (the _Verifiable Credential_) to Alice (the _Subject_ and _Holder_), and writes the information to a database (the _Verifiable Data Registry_). When crossing the border, Alice (the _Holder_) presents her passport to a border agent (the _Verifier_) who can verify that Alice (the _Subject_) is indeed a citizen. - -::: - -**Subject:** An entity about which claims are made – Alice (the _Subject_) is a citizen of this country. - -**Holder:** An entity which possesses verifiable credentials – Alice (the _Holder_) possesses the passport (the _VC_). - -**Issuer:** An entity which asserts claims about a subject – The governing body (the _Issuer_), which is trusted, issues Alice a passport. - -**Verifier:** An entity which check's if the VC a holder presents is legitimate – The border agent (the _Verifier_) trusts the government (the _Issuer_) which issued Alice her passport, and validates that Alice (the _Subject_) is a citizen. - -:::note - -See the [Verifiable Credentials Data Model 1.0 Specification](https://w3c.github.io/vc-data-model/) for more information. - -::: - -### Verifiable Credentials in IOTA - -In the IOTA Identity framework, instead of a physical passport being given to Alice with the passport information being written into a centralized database owned by the government, Alice receives a digital verifiable credential, and the information required for verification in the future is written to the Tangle. - -At a high level, the creation and verification of a VC on IOTA works as follows: - -The first step is to create a verifiable credential which requires the subject (Alice) and issuer (the government) to have DIDs published to the Tangle, and a set of statements being asserted (that Alice has a passport). The issuer signs the credential with their private key and publishes the public key to the Tangle. - -Once the issuer is confident that the credential satisfies its expectation (after validating the credential's properties), the credential is stored and transmitted to the subject in a secure manner (off-chain). - -Validation is performed by looking up the issuer's public key on the Tangle, the holder proving ownership of their DID to the verifier (evidence), and validating that the credential has indeed been signed by the issuing party. - -The remaining chapters in this section explore creation, verification, and revocation of VCs in more detail. diff --git a/docs/build/identity.rs/1.0/docs/concepts/verifiable_credentials/revocation.mdx b/docs/build/identity.rs/1.0/docs/concepts/verifiable_credentials/revocation.mdx deleted file mode 100644 index 281fd249acb..00000000000 --- a/docs/build/identity.rs/1.0/docs/concepts/verifiable_credentials/revocation.mdx +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Verifiable Credential Revocation -sidebar_label: Revocation -description: Explain how a VC can be revoked -image: /img/Identity_icon.png -keywords: - - verifiable - - credentials - - revoke - - revocation ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -## Overview - -The [example](#example) below demonstrates two methods that an issuer can use to revoke a verifiable credential using the IOTA Identity Framework: - -1. By using the [`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) field in a credential and linking to a revocation bitmap, using the [`RevocationBitmap2022`](../../specs/revocation_bitmap_2022.mdx). -2. By removing the verification method that signed the credential. This invalidates all credentials that were signed with that verification method. - -## Revocation Bitmap - -One of the ways for an issuer to control the status of its credentials is by using a revocation list. At the most basic level, revocation information for all verifiable credentials issued by an issuer are expressed as simple binary values. The issuer keeps a list of all verifiable credentials it has issued in a bitmap. Each verifiable credential is associated with a unique index in the list. If the binary value of the index in the bitmap is 1 (one), the verifiable credential is revoked, if it is 0 (zero) it is not revoked. - -For example, with this approach the issuer adds an index to a credential in the `credentialStatus` field, such as `"5"`. This part of the credential might then look like this: - -```json -"credentialStatus": { - "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation", - "type": "RevocationBitmap2022", - "revocationBitmapIndex": "5" -}, -``` - -The verifier uses the `id` field (`did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation`) to look up the service in the issuer's DID document. This is an example of such a service: - -```json -{ - "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation", - "type": "RevocationBitmap2022", - "serviceEndpoint": "data:application/octet-stream;base64,ZUp5ek1tQmdZR1NBQUFFZ1ptVUFBQWZPQUlF" -} -``` - -During verification the verifier decodes the revocation bitmap embedded in the `data` url. This bitmap written as a bitstring looks like this: `000001`. Here, the 5th bit is set, which means the credential with that index is revoked, while all other credentials aren't revoked. - -## Removing the verification method - -A less efficient alternative is to remove the verification method that signed the credential from the DID Document of the issuer. This means the VC can no longer be validated. However, this would invalidate every VC signed with that verification method, meaning the issuer would have to sign every VC with a different key to retain precise control over which credential is revoked. - -## Example {#example} - -The following code exemplifies how you can revoke a [Verifiable Credential (VC)](./overview.mdx). - - - - -```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/7_revoke_vc.rs -``` - - - - -```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts -``` - - - diff --git a/docs/build/identity.rs/1.0/docs/concepts/verifiable_credentials/verifiable_presentations.mdx b/docs/build/identity.rs/1.0/docs/concepts/verifiable_credentials/verifiable_presentations.mdx deleted file mode 100644 index 7c60aa49e8d..00000000000 --- a/docs/build/identity.rs/1.0/docs/concepts/verifiable_credentials/verifiable_presentations.mdx +++ /dev/null @@ -1,184 +0,0 @@ ---- -title: Verifiable Presentations -sidebar_label: Verifiable Presentations -description: Explain how a VC is created and verified -image: /img/Identity_icon.png -keywords: - - verifiable - - presentations ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -A verifiable presentation is the recommended data format for sharing one or more [verifiable credentials](./overview.mdx). -It is constructed and signed by a holder to prove control over their credentials and can be presented to a verifier for [validation](#validation). - -For instance: after an issuer [creates and issues a verifiable credential](./create.mdx) to a holder, such as a university issuing a degree to a graduate, -the holder stores it securely until asked to present it. -A company could then request proof of that university degree: the holder can [create a verifiable presentation](#creation) -containing their credential, which is already signed by their university, and present it to the company to [validate](#validation). - -Note that verifiable presentations that contain personal data should, as with verifiable credentials, be transmitted and stored securely off-chain to satisfy data privacy regulations such as [GDPR](https://gdpr.eu/). - -:::note - -See the [Verifiable Credentials Data Model Specification](https://www.w3.org/TR/vc-data-model/#presentations) for more information on verifiable presentations. - -::: - -## Creation {#creation} - -The IOTA Identity Framework enables holders to construct verifiable presentations easily. -As demonstrated in the [example](#example), holders need only pass in their credentials to present and sign the presentation. - -The following properties may be specified on a presentation: - -- [**ID**](https://www.w3.org/TR/vc-data-model/#identifiers): optional URI identifier for the presentation. -- [**Context**](https://www.w3.org/TR/vc-data-model/#contexts): list of JSON-LD context URIs. Includes `"https://www.w3.org/2018/credentials/v1"` by default. -- [**Types**](https://www.w3.org/TR/vc-data-model/#types): list of types describing the presentation. Includes `"VerifiablePresentation"` by default. -- [**Credentials**](https://www.w3.org/TR/vc-data-model/#dfn-verifiable-credentials): list of verifiable credentials to present. -- [**Holder**](https://www.w3.org/TR/vc-data-model/#dfn-holders): optional URI, typically a DID, of the entity that generated the presentation. -- [**Refresh Service**](https://www.w3.org/TR/vc-data-model/#refreshing): optional link to a service where the recipient may refresh the included credentials. -- [**Terms of Use**](https://www.w3.org/TR/vc-data-model/#terms-of-use): optional list of policies defining obligations, prohibitions, or permissions of the presentation recipient. - -Of the above, only the list of credentials is required when creating a presentation using the framework. -However, the holder property should be included to satisfy [subject-holder relationship](#subject-holder-relationship) checks during validation. - -After creation, the holder signs the verifiable presentation using a private key linked to one of the verification methods in their -DID Document and transmits it to a verifier for [validation](#validation). - -### Proof Options {#proof-options} - -A digital signature on a verifiable presentation both provides data integrity and proves the DID of the holder. -The proof section embedded in a presentation may also include additional metadata. - -The following metadata properties can be configured by the framework and are optional and omitted by default: - -- **Created**: timestamp of when the presentation was signed. -- **Expires**: timestamp after which the presentation is no longer considered valid. -- **Challenge**: arbitrary random string. Sent by the verifier and mitigates replay attacks; should be sufficiently random and uniquely generated per presentation request. -- **Domain**: arbitrary string. Sent by the verifier and can help mitigate replay attacks when used with a challenge. -- **Proof Purpose**: indicates the purpose of the signature. - - **AssertionMethod**: to assert a claim. The signing verification method must have an [`assertionMethod`](https://www.w3.org/TR/did-core/#assertion) relationship to be valid. - - **Authentication**: to authenticate the signer. The signing verification method must have an [`authentication`](https://www.w3.org/TR/did-core/#authentication) relationship to be valid. - -:::note - -Verifiers should always send a challenge and domain to mitigate replay attacks, see [Security Considerations](#security-considerations). - -::: - -A verifier could also choose to ignore some or all of these options. -See [Proof Verifier Options](#proof-verifier-options) for more information. - -## Validation {#validation} - -The IOTA Identity Framework provides several options for verifiers to validate various sections of a verifiable presentation. -See the [example](#example) for a demonstration of how to validate a presentation. - -The framework checks: - -- **Semantic structure**: ensures the presentation and its credentials adhere to the specification. -- **Presentation proof**: verifies the presentation signature against the DID Document of the holder. -- **Credential proofs**: verifies the credential signatures against the DID Documents of their respective issuers. -- **Optional validations**: additional checks on signatures and credential fields can be configured by the verifier. - -Note that a verifier may specify which DID Documents to use for the holder and issuers, otherwise they are resolved from the Tangle automatically. - -Currently, the following are _not_ checked automatically: - -- **Data schemas**: credentials that specify a [schema](https://www.w3.org/TR/vc-data-model/#data-schemas) property should be examined to ensure conformance. -- **Fitness for purpose**: whether the credentials in a presentation and the data within them are acceptable and valid depends on the context in which they are used. Verifiers should ensure that the credential types, subjects, and schemas sent by a holder match what was requested. -- **Issuer trustworthiness**: verifiers must check that they trust the issuer on each individual credential in a presentation. The framework only verifies that the issuer's signature on each credential is current and valid against the given options. - -The default validation behaviour may be modified by the following options. - -### Proof Verifier Options {#proof-verifier-options} - -While the framework always verifies that the digital signature on a verifiable presentation is valid, a verifier may validate additional fields in the proof on a presentation. -Notably, to mitigate potential replay attacks a verifier should always check that the challenge and domain fields match what was sent to the holder when requesting the presentation. -See [Security Considerations](#security-considerations) for more information. - -The following options are available: - -- **Method Scope**: check the signing verification method has a particular [verification relationship](https://www.w3.org/TR/did-core/#verification-relationships). Overridden by the proof purpose check. -- **Method Type**: check the signing verification method has a particular type. -- **Challenge**: check the challenge field matches this string. -- **Domain**: check the domain field matches this string. -- **Proof Purpose**: require a specific purpose on the proof. See [Proof Options](#proof-options). -- **Allow Expired**: accept proofs where the current datetime is after their expiration. Default is to reject expired proofs. - -See [Proof Options](#proof-options) for more information on setting these properties as a holder when signing a verifiable presentation. - -### Subject-Holder Relationship {#subject-holder-relationship} - -Specifies the expected relationship between the holder that signed the verifiable presentation and the subject specified in each verifiable credential. -This can be restricted by the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property, -which indicates that a verifiable credential must only be encapsulated into a verifiable presentation whose holder matches the credential subject. - -By default, the framework always enforces that the holder matches the subject on all credentials. -The following options are available to modify that behaviour: - -- **`AlwaysSubject` (default)**: the holder DID that signed the presentation must match the [`credentialSubject` `id`](https://www.w3.org/TR/vc-data-model/#credential-subject) field in each of the attached credentials. This is the safest option which ensures holders may only present credentials that were directly issued to their DID. An error is thrown on a mismatch or if no subject `id` is present. -- **`SubjectOnNonTransferable`**: the holder DID must match the subject only for credentials where the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property is `true`. This is appropriate for accepting [bearer credentials](https://www.w3.org/TR/vc-data-model/#bearer-credentials) while still adhering to the specification. -- **`Any`**: the holder DID is not required to have any kind of relationship to any credential subject. This option performs no checks and ignores the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property. - -:::note - -See the [Verifiable Credentials Data Model Specification](https://www.w3.org/TR/vc-data-model/#subject-holder-relationships) for further discussion on the different subject-holder relationships. - -::: - -### Credential Validation Options {#credential-validation-options} - -These options specify conditions that all credentials in a verifiable presentation must satisfy. - -- **Expiry Date**: check that the [`expirationDate`](https://www.w3.org/TR/vc-data-model/#expiration) property, if present, is not before a specific datetime. Defaults to the current datetime if unset. -- **Issuance Date**: check that the [`issuanceDate`](https://www.w3.org/TR/vc-data-model/#issuance-date) property, if present, is not after a specific datetime. Defaults to the current datetime if unset. -- **Verifier Options**: see [Proof Verifier Options](#proof-verifier-options) for details. - -## Security Considerations {#security-considerations} - -### Replay Attacks {#replay-attacks} - -A verifiable presentation without challenge and domain properties could potentially be stored by a malicious actor -and replayed to a different verifier, impersonating the holder. -This is because the holder's signature on a presentation would still be seen as valid indefinitely, -until they [rotate](https://www.w3.org/TR/did-core/#verification-method-rotation) the verification method used. - -To mitigate this, verifiers should always send a unique challenge and domain when requesting a verifiable presentation. -These properties are then included in the proof section of the presentation by the holder during signing using [Proof Options](#proof-options). -The digital signature prevents these properties from being altered as it would invalidate the signature, effectively preventing a malicious -actor from injecting different values into old verifiable presentations. A presentation without a challenge and domain -in its proof that matches what was sent by the verifier should be considered invalid. - -The challenge string should be sufficiently random and unique for each verifiable presentation requested by a verifier to avoid -being predicted. The domain, which does not need to be random, is an additional measure. In the unlikely occurrence -of two verifiers generating the same random challenge, the domain would sufficiently distinguish those requests. - -Holders may additionally specify that their signature on a verifiable presentation expires after a short duration, as -per [Proof Options](#proof-options). However, verifiers and different implementations could choose to ignore that property, -so setting a signature expiration alone should not be relied upon. - -## Example {#example} - -The following code demonstrates how to use the IOTA Identity Framework end-to-end to create and sign a verifiable presentation as a holder, -serialize it to JSON for transmission, deserialize it on the receiving side as a verifier, and finally validate it with various options. - - - - -```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/6_create_vp.rs -``` - - - - -```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/6_create_vp.ts -``` - - - diff --git a/docs/build/identity.rs/1.0/docs/decentralized_identity.mdx b/docs/build/identity.rs/1.0/docs/decentralized_identity.mdx deleted file mode 100644 index 35e9b936cab..00000000000 --- a/docs/build/identity.rs/1.0/docs/decentralized_identity.mdx +++ /dev/null @@ -1,113 +0,0 @@ ---- -description: Decentralized Identity defines a new method for identity management and authentication by removing centralized aspects. -image: /img/Identity_icon.png -keywords: - - Self Sovereign Identity - - decentralized - - Permissionless - - authentication - - explanation ---- - -# Introduction to Decentralized Identity - -![IOTA Decentralized Identity](/img/banner/banner_decentralized_identity.svg) - -Decentralized Identity or Self-Sovereign Identity (SSI) defines a new method for identity management and authentication. It removes the centralized aspects and puts the Identity subject in full control over its own identity. Decentralized Identity provides a solution for the increasing amount of database breaches, the lack of trust in any digital setting, and the increasingly difficult to comply with privacy legislation, such as GDPR. - -There are three levels of privacy when interacting on the internet: full privacy, verifiable identities, and pseudonymity. With full privacy, neither parties, nor observers, can identify the interacting parties. With verifiable identities, parties can trust each other because they can both provide proof about their identities. With pseudonymity, both parties recognize each other through a pseudonymous identifier. Pseudonymity is the default setting of the internet. However, data harvesting platforms, like -Google and Facebook, can now link these “random” identifiers, though imprecisely, to identities in the real world. The associated data and insights have become extremely valuable to advertising agencies, product developers, and numerous local and global businesses. - -The need for verifiable personal information can be fulfilled by digital identity. Digital identity allows users to bridge the gap between the online and the real world. When users provide personal information to someone online, in a “Bring Your Own Identity” (BYOI) manner, they will be able to prove that their personal information is perfectly accurate. Whereas in the current system, where companies like Google and Facebook provide an estimation of identity, there can be insufficient depth to user profiles or, in some cases, the information is altogether false. - -With digital identity, the user can decide what information to share and with whom they would like to share it. This will maintain and even improve online privacy, while allowing for new features and new business opportunities. Businesses will be able to trust BYOI information, enhancing interactions between company and customer, but also reducing fraudulent cases and endemic security risks. - - - -## Identity for People - -:::note - -IOTA Identity builds a new internet, without usernames, passwords, endless repeated forums, or uncontrolled data harvesting. - -::: - -Information about anyone's life is spread across many locations. Most people have numerous unorganized important documents at home, hundreds of online accounts, and many more online footprints. Through statistical predictive analysis, computer programs can harvest unverified online information sources and create a reasonably accurate profile about our lives. These profiles are accurate enough for targeted advertising and personalized content but lack the proof and trust for them to be used in business. This results in an antiquated customer experience where we have to submit our age and address for every purchase we make and every account we create. It also inhibits our ability to do many online tasks like requesting and extending licenses or taking out a mortgage. - -Self-Sovereign Identity is about returning autonomy and privacy to the individual, while also improving our online experience. Some movements focus on data privacy, preventing companies from using our information altogether, but with the IOTA Identity framework you control which part of the information you want to reveal. The user can create a single online profile containing all our personal information. They can decide who they share what information with, and a Verifier checks if the information is correct, making the data trustworthy. This moves their online profile from a statistical estimation by corporate entities to an accurate and verifiable profile under their own control. - -IOTA Identity allows a new internet without usernames, passwords, endless repeated forms, or data harvesting. Users have ultimate control and can choose to supply service providers with their personal data, who in return provide personalized experiences. Data will still flow, and perhaps even more than before, but it will always be in the interest of the individual, instead of a corporation. People will gain additional benefits in sharing their data, either in monetary value or improved customer experience. This sort of system is not possible in a non-neutral environment such as permissioned or fee-based ledgers. - -Governmental mechanisms for building _digital identities_ are currently being established throughout Europe and Asia, with demand increasing around the globe. However, they are managed by single entities and restricted to the governments that created them. By decentralizing a framework for these standards to adapt to, we have a system for intergovernmental verification of individuals and devices. A person’s digital identification will be transferable across borders like a passport. However, it will no longer require the trust of the issuing government due to the digital trust established by the open and auditable system. - -## Identity for Organizations - -:::note GDPR - -IOTA Identity allows organizations to comply with GDPR in a cost-efficient and privacy-enabling manner - -::: - -Corporations are associated with greed and abuse of power. This reputation stems from the role some have chosen to take within society. Corporations are trusted with our data, but often do not act responsibly; vulnerability, fix, patch, repeat. In software and systems, we have seen this cycle repeat. Headlines on data leaks are now an ever-present feature in the news. - -IOTA Identity presents an opportunity for companies to embrace a new role in the ecosystem. Traditional approaches do not provide cost-efficient solutions to new legislation like GDPR. IOTA Identity enables organizations to change their processes to comply with the new regulations in a cost-efficient and privacy-enabling manner. Features of “Data Protection and Privacy by Design” shift responsibility over Personal Identifiable Information (PII) from organization to customer, and organizations no longer need to store that data. The relationship between customer and organization is also tightened as communication via a third party Identity provider like Google or Facebook is no longer needed. - -Due to Know-Your-Customer (KYC) and Anti-Money Laundering (AML) obligations, companies can be certain who their customers are. These services also provide unique insight into the state of their customers’ data. These insights can be combined and translated into verifiable credentials, providing a new “Trust Anchor” service with a potential for new business models. KYC and AML credentials would return the autonomy of personal data back to the customer. Once companies accept the KYC and AML credentials of other companies, the enrollment time for new customers is significantly reduced, as are the costs. With the personal data secured by the customer, companies can afford to store less data in their own databases, reducing risk and responsibility and fulfilling the goals of legislation such as GDPR. - -Organizations that have their own decentralized identities can also combat fraud and increase control over their online brand. Companies can sign invoices and agreements using their decentralized identities. While interacting with the customers, they will also be able to reliably identify themselves. - -## Identity for Things - -:::note TRUST - -IOTA Identity adds the missing key ingredient for the "Economy of Things": Trust. - -::: - -With Identity of Things (IDoT), devices are provided with a unique global identity that are able to prove many attributes including their capabilities, specifications, and authenticity. People, organizations, and other devices will only pay devices that can prove their ability to fulfill the required task. This basis of trust prevents fraudulent activity. Additonally, by using the IOTA ledger, the progress of the task can be immutably logged. With the combination of the IOTA protocol and the IOTA Identity framework, we can automate the entire interaction between all parties, without requiring predefined trust. The [Industry Marketplace](https://industry.iota.org/) provides a perfect example of how this framework and level of autonomy work. - -There is a growth in applications that generate Digital Twins for physical devices or objects, such as the Asset Administration Shell (AAS) developed for our Industry Marketplace. Digital twins are online profiles representing a device or object. They provide a virtual state that mirrors reality by emulating the device or object’s physical state through data input sources like sensors. A digital twin is often used to monitor states and execute actions based on the information. Digital twins are only rarely shared outside the associated application and organization due to the complexities in sharing and matching profiles. However, empowered with a digital identity, digital twin sharing would become possible. Once data is verifiable and trusted, digital twins can form the basis for the digital representation of physical devices and objects. This allows other identities to interact with them automatically and provide services such as predictive maintenance. - -Security is a major barrier in advancing technologies that use IoT. Whether it is the smart devices in our own homes, or at a larger scale, the critical infrastructure of organizations and cities, security must be at the core. It is central to any globally-unifying identity solution. By integrating advanced research in cryptography and digital ledgers, and combining it with a scalable access and management system, security will become a core functionality of the systems we build. By using scalable device DIDs, integrating verification and reputation schemes, and allowing for transparent tamper-proof accountability, we begin to understand how we can future-proof the security of our systems, allowing us to start trusting the process, and not the patch. - -## One Framework. Any Identity - -:::note Framework - -The IOTA Identity framework serves as the invisible layer of trust for the internet. This framework must be open, scalable, and free, so that everyone and everything can enjoy trust as a basic digital right. - -::: - -With various types of actors requiring an identity protocol, it is a strong proposition to use the same underlying protocol for all of them. This IOTA Identity framework enables anyone or anything to create a digital identity, build an online profile of trust by collecting verifiable credentials, and share them with other actors they interact with. Interaction between people, companies, things, and objects becomes seamless. And just as we can trust a person, we will also be able to trust a car, or even a luxury coat. Different identities can also be linked together, creating trustworthy relationships, such as ownership of an object. IOTA already provides a protocol that enables these actors to transact value or data with one another. IOTA will now combine identity features into a single platform, creating the base protocol for the next generation of smart applications. - -## Why IOTA? - -:::note Neutral and Free - -IOTA is a neutral and free-to-use public infrastructure acting as a trustworthy public commons. - -::: - -IOTA is a scalable and feeless Distributed Ledger Technology (DLT). Similar to Blockchain technology, IOTA provides an immutable and decentralized ledger that can transact value through the IOTA token. Unlike Blockchain, IOTA uses a non-linear data structure called the [Tangle](/learn/about-iota/an-introduction-to-iota#the-tangle-data-structure) which makes it feeless and vastly more scalable. The Tangle also facilitates feeless transactions of data, such as DID registrations and credential revocations. As a single source of truth and trust in data, the Tangle can provide the trust infrastructure in a highly networked world. - -IOTA is uniquely suited for a single unifying identity implementation. The network is designed for both humans and devices, providing a platform for trusted communication between individuals, organizations, and things. The IOTA Foundation’s principles of full transparency, openness, and permissionless innovation provide an open and neutral environment: - -1. **Permissionless & Decentralized**: Unlike a permissioned network such as Hyperledger or Corda, everyone can participate in consensus without being granted access. No party incentivized by profit-making has collective control over the network (unlike all blockchains). This makes IOTA neutral and censorship-resistant. -2. **Public**: Everyone can observe (unless using optional encryption) the transactions in the network. The network is inherently transparent. -3. **Feeless**: All data and _value transactions_ on the network are free. Unlike other DLTs such as Bitcoin or Ethereum, registration and communication of identities can be written to the network without a requirement to purchase a cryptocurrency token. -4. **Open Source**: Everyone can view and contribute to the code. -5. **Easy to use**: IOTA Identity is inherently easier to use due to the lack of fees or requirements to set up an entire private network. In addition, the framework is designed to have an easy to use high-level API, with accessibility to the low-level, more complex and more flexible API. Through integration with the [Stronghold](/stronghold.rs/welcome 'Stronghold is an open-source software library that was originally built to protect IOTA Seeds, but can be used to protect any digital secret.') project, we also provide out-of-the-box security for secrets. - -Data must be immutably stored on a distributed ledger to ensure the decentralized nature of the digital identity protocol. With the network’s continual uptime, credentials are always verifiable without a dependency on the servers of credential issuers. This system also increases individual privacy, because contact with the Issuer is removed from the interaction between Holder and Verifier. Issuers will not be able to track when and how often the Holder uses their credentials. The flexibility afforded from the Tangle means that the digital identity framework remains extendable in the future. - -Within the digital identity framework, the Tangle is used for the following functionalities: - -1. **Public Key Registry**: The Tangle enables a decentralized public key infrastructure (DPKI) for Issuers using DID standards. This allows Verifiers to verify a signature without reliance on a centralized server. The DID standard also adds service endpoints, extending the usability of Identities beyond a public key registry, to, for example, registering verifiable credential standards. -2. **Revocation**: A verifiable credential can be revoked, meaning it will no longer be able to pass verification. The revocation is immutably stored on the Tangle, making sure no Holder can attempt to use their revoked credentials. This is designed to be a simple public key deactivation to guarantee GDPR compliance. diff --git a/docs/build/identity.rs/1.0/docs/explanations/about-alias-outputs.mdx b/docs/build/identity.rs/1.0/docs/explanations/about-alias-outputs.mdx new file mode 100644 index 00000000000..082ade130fa --- /dev/null +++ b/docs/build/identity.rs/1.0/docs/explanations/about-alias-outputs.mdx @@ -0,0 +1,65 @@ +--- +title: Alias Outputs +description: UTXO Alias Ouput +image: /img/Identity_icon.png +keywords: + - public keys + - utxo + - Method Specification + - Decentralized Identifiers + - overview + - DLT +--- + +# Alias Outputs + +:::info TL;DR + +The IOTA DID method users Alias Outputs for storing DID Documents. +Alias Outputs are created via transactions, +and require a [storage deposit](/learn/protocols/stardust/core-concepts/storage-deposit/) to cover the data storage. +The deposit is refundable upon destruction of the output. + +Each Alias Output has an `Alias ID` that becomes the basis for the DID, +and which can be transferred through transactions to update DID Documents. + +::: + + +The IOTA DID method uses the IOTA ledger, which is baed on the [unspent transaction output (_UTXO_) model](/learn/protocols/chrysalis/core-concepts/switch-to-UTXO/), +as well as the features of the [Stardust](/introduction/stardust/explanations/what_is_stardust) upgrade, +which are fundamental to the IOTA DID method. + +The Alias _Output_ is used to store a DID Document on the ledger. +It is a specific implementation of the UTXO _state machine_ that can hold arbitrary data in its `State Metadata`. +The Alias Output has two kinds of controllers, a state controller and a governor. + +A state controller can execute a state transition which allows updating the data in the `State Metadata`. + +The governor, on the contrary, can't update the `State Metadata` but can change both controllers and destroy the Alias Output. + +A controller can be either [Ed25519 Address](/learn/protocols/chrysalis/core-concepts/switch-to-UTXO/), [Alias Address or an _NFT_ Address](/learn/protocols/stardust/core-concepts/multi-asset-ledger/) +and at most one of each can be set for an Alias Output. + +In order to create a new Alias Output, a transaction must be made that includes another Output, for example, +a Basic Output, as input and the new Alias Output, along with other outputs if needed, as outputs. + +### Storage Deposit + +The arbitrary data stored in the `State Metadata` of the Alias output must be covered by a +[storage deposit](/learn/protocols/stardust/core-concepts/storage-deposit/). +This helps to control the ledger size from growing uncontrollably while guaranteeing the data +is indefinitely stored on the ledger which is important for resolving DID Documents. +This deposit is fully refundable and can be reclaimed when the output is destroyed. + +Both the state controller and the governor can control the tokens stored in the Alias Output. +_Nodes_ expose an API to calculate the required deposit depending on the size of the data stored. + +### Alias ID + +Each Alias Output has an `Alias ID`. This ID is assigned after a transaction creates a new Alias Output. +The actual DID is derived from this `Alias ID`, hence it is unknown before publishing the transaction. +Consequently, the DID inside the `State Metadata` will be replaced by the placeholder `did:0:0` to indicate self. + +If a transaction has an Alias Output as input, its `Alias ID` can be kept by one of its outputs. +This feature is necessary for updating the DID Documents since the DID itself is derived from the Alias Output. diff --git a/docs/build/identity.rs/1.0/docs/explanations/decentralized-identifiers.mdx b/docs/build/identity.rs/1.0/docs/explanations/decentralized-identifiers.mdx new file mode 100644 index 00000000000..9702b23e8a6 --- /dev/null +++ b/docs/build/identity.rs/1.0/docs/explanations/decentralized-identifiers.mdx @@ -0,0 +1,136 @@ +--- +description: The Decentralized Identifiers (DID) standard from W3C is the fundamental standard that supports the concept of a decentralized digital identity. Explore the basic aspects of the DID standard. +image: /img/Identity_icon.png +keywords: + - public keys + - Method Specification + - Decentralized Identifiers + - overview + - DLT +--- + +# Decentralized Identifiers (DID) + +:::info TL;DR + +DIDs are unique identifiers that can be resolved to DID Documents containing public keys and URIs for identity verification and public information. + +Adhering to the W3C's DID specifications, IOTA's implementation ensures interoperability and security within its ledger. + +DIDs support self-sovereign identity, allowing identity owners to control their creation and destruction, +while facilitating encrypted communication. + +::: + + +A DID is a unique identifier that can be resolved to a DID Document. This document contains data such as public keys, enabling the holder to prove ownership over their personal data, but also URIs that link to public information about the identity. DIDs are the fundamental building blocks of decentralized digital identity. +This implementation complies to the [DID specifications v1.0](https://www.w3.org/TR/did-core//) from the World Wide Web Consortium (W3C). + +In the IOTA Identity framework, we have implemented the DID standard according to the `iota` [DID Method Specification](/identity.rs/references/specifications/iota-did-method-spec/). Other implementations of DID on IOTA must follow the `iota` DID Method Specification if they also want to use the `iota` method name. Libraries implementing the `iota` DID Method Specification are provided for [Rust](../getting-started/rust.mdx) and [WASM](../getting-started/wasm.mdx). + +An example of a DID conforming to the `iota` method specification: +`did:iota:0xe4edef97da1257e83cbeb49159cfdd2da6ac971ac447f233f8439cf29376ebfe` + +## Decentralized Identifiers + +A Decentralized Identifier, or DID, is a unique identifier that is tied to a subject. This subject can be anything, like a person, an organization, an IoT device, or even an object. The identifier can be used by the subject to identify themselves through a digital format, providing a basis for online identification. The identifier looks like a set of random characters that includes some prefixes to determine which standard and implementation is used: + +`did:iota:0xe4edef97da1257e83cbeb49159cfdd2da6ac971ac447f233f8439cf29376ebfe` + +The World Wide Web Consortium (W3C) is a well-known standardization body that has standardized how DIDs should look and work. +This provides a basis for different technologies that implement the [DID standard](https://www.w3.org/TR/did-spec-registries/#did-methods) to achieve interoperability. +Keep in mind that, unfortunately, most of these methods are outdated and not maintained. + +## DID Documents + +The purpose of a DID is to help navigate to a DID Document, +which is a document containing more information regarding the identity subject. +This document contains data such as public keys, enabling the subject to prove ownership over their personal data, +but can contain additional information on how to interact with the subject. + +The identifier contains all information to resolve a DID, providing the latest DID Document. +The first three characters `did` indicate that the DID standard from W3C must be used to resolve the identifier. +It is followed by a unique method name, in our case `iota`, to indicate that the IOTA method is used. + +The IOTA method is a specific implementation following the [IOTA DID Method Specification](/identity.rs/references/specifications/iota-did-method-spec/). +This provides unique rules for the protocol to follow in order to manage a DID Document. +In our case, it describes how DID Documents are uploaded and queried to and from the IOTA ledger. + +Lastly, a DID also contains a set of random characters that are unique per identity and resolve to a single DID Document. + +:::tip Requires basic knowledge of Asymmetric Encryption + +The following sections require some basic knowledge of Asymmetric Encryption. +Please read or view some materials on the subject before continuing. + +::: + +A DID Document mostly contains two important pieces of data: verification methods and services. + +Verification methods contain public key material that can be used to prove ownership over the identity, +by cryptographically signing something with the associated private key. +The public key can be used to verify that the identity subject signed the data and therefore controls the private key. +Ownership over the private keys, therefore, proves ownership over the identity. + +This also means that it is very important to keep the private keys safe and secure. +In addition, the public keys allow users to send encrypted data to the identity that only the identity owner can decrypt. + +:::caution + +Never share your private keys, seeds, passphrases with anyone. Not even IOTA Foundation members. +This may lead to loss of funds or control over your own digital identity. + +::: + +Services are URIs that point to more information about the identity. +This could be something as simple as a website for an organizational identity. +These services are publicly available for all to read, +and should not contain Personal Identifiable Information (PII) in the case of human identities. + +## Why Use DIDs? + +DIDs allow any subject to have a unique identifier that they can prove ownership of, +and at the same time provide a way to send them encrypted messages. +The Identity is Self-Sovereign, meaning the subject is always in control; +whether it is creating, updating or destroying it. + +DIDs become more interesting when you combine them with [verifiable credentials (VC)](verifiable-credentials.mdx). +In essence, verifiable credentials (VCs) are signed statements by trusted third parties about a certain identity. +The signer, or Issuer, is referenced by the DID and so is the subject, often called the holder. +The holder controls a copy of this statement and can share it with other parties, the _Verifiers_, +that can verify the statement and check which party made the statement, without having to ask the Issuer. +Instead, they can verify the signature of the issuer by checking the issuers DID Document. + +This puts Holders back in control over their own data, +while making the data much more trustworthy as it has become verifiable. + +## Why Use Iota Identity Over Other Implementations? + +IOTA Identity is a framework to implement Self-Sovereign Identities on IOTA. +Inherently, IOTA provides some unique features that have a major impact on the usability of the framework. + +### Availability and Accessibility + +DID Documents are stored in the ledger state and are covered [storage deposit](/learn/protocols/stardust/core-concepts/storage-deposit/). +This guarantees that all nodes will have an up-to-date copy of the latest DID Document. +Resolving a DID into its document can usually be done by any IOTA node in the network. +This solves many issues regarding availability, accessibility or synchronization. + +### Layer1 Interactions + +DID Document are stored in an [Alias Outputs](./about-alias-outputs.mdx), +this allows them to directly interact with Layer 1 artifacts like [NFTs and native assets](/learn/protocols/stardust/core-concepts/multi-asset-ledger/). + +For instance, an Alias Output representing a DID can hold native assets or control NFTs. +Transferring funds between DIDs is also possible on Layer 1. + +### Ease-of-use + +IOTA Identity abstracts the details of the DID standard by providing easy-to-use APIs that allow standardized behavior. +It also allows more flexible and complex management of DID Documents. + +### Secure Storage + +IOTA Identity provides a +[Stronghold](/stronghold.rs/welcome/ 'Stronghold is an open-source software library that was originally built to protect IOTA Seeds, but can be used to protect any digital secret.') solution +for managing secrets securely, without requiring developers to reinvent the security wheel. diff --git a/docs/build/identity.rs/1.0/docs/explanations/verifiable-credentials.mdx b/docs/build/identity.rs/1.0/docs/explanations/verifiable-credentials.mdx new file mode 100644 index 00000000000..c06a74426f7 --- /dev/null +++ b/docs/build/identity.rs/1.0/docs/explanations/verifiable-credentials.mdx @@ -0,0 +1,74 @@ +--- +description: Verifiable credentials are statements about the holder. They can be verified online or in person, and the holder decides who to share them with. +image: /img/Identity_icon.png +keywords: + - verifiable + - credentials + - person +--- +# Verifiable Credentials + +:::info TL;DR + +Verifiable credentials (VCs) are digital statements that can be cryptographically proven, like a digital passport, +and are used within systems to assert certain properties or capabilities of an entity. + +In the IOTA Identity framework, this is managed with decentralized identifiers (DIDs) on the Tangle. +Subjects and issuers use their DIDs for the creation and verification of credentials. + +::: + +Credentials are statements about an entity, +such as properties that the entity possesses or capabilities that they have, +like a driver's license, passports, or a person's age. +Verifiable credentials (VCs) are statements (e.g., Alice has a driver's license) +that can be cryptographically verified by a third party, either online or in person. +Additionally, the holder of the VC decides what is shared and who it is shared with. + +There are several types of actors that play different roles in a verifiable credential system. +We'll start with a common example of how things work in the world today using physical credentials and centralized databases, +and outline the roles that various entities play in the Verifiable Credential system. + +## Example - Passport Issuance + +A government (the _issuer_) issues a passport asserting citizenship (the _Verifiable Credential_) to Alice (the _subject_ and _Holder_), +and writes the information to a database (the _Verifiable Data Registry_). +When crossing the border, Alice (the _Holder_) presents her passport to a border agent (the _Verifier_), +who can verify that Alice (the _subject_) is indeed a citizen. + + + +**Subject:** An entity about which claims are made – Alice (the _subject_) is a citizen of this country. + +**Holder:** An entity which possesses verifiable credentials – Alice (the _Holder_) possesses the passport (the _VC_). + +**Issuer:** An entity which asserts claims about a subject – The governing body (the _issuer_), which is trusted, issues Alice a passport. + +**Verifier:** An entity which check's if the VC a holder presents is legitimate – The border agent (the _Verifier_) trusts the government (the _issuer_) which issued Alice her passport, and validates that Alice (the _subject_) is a citizen. + +:::note + +See the [Verifiable Credentials Data Model 1.0 Specification](https://w3c.github.io/vc-data-model/) for more information. + +::: + +## Verifiable Credentials in IOTA + +In the IOTA Identity framework, instead of a physical passport being given to Alice with the information being written +into a centralized database owned by the government, Alice receives a digital verifiable credential, +and the information required for verification in the future is written to the Tangle. + +At a high level, the creation and verification of a VC on IOTA works as follows: + + +The first step is to create a verifiable credential which requires the subject (Alice) and issuer (the government) to +have [DIDs](./decentralized-identifiers.mdx) published on the Tangle, and a set of statements being asserted (that Alice has a passport). +The issuer signs the credential with their private key and publishes the public key to the Tangle. + +Once the issuer is confident that the credential satisfies its expectation, +the credential is stored and transmitted to the subject in a secure manner (off-chain). + +Validation is performed by looking up the issuer's public key on the Tangle, +the holder proving ownership of their DID to the verifier (evidence), +and validating that the credential has indeed been signed by the issuing party. + diff --git a/docs/build/identity.rs/1.0/docs/explanations/verifiable-presentations.mdx b/docs/build/identity.rs/1.0/docs/explanations/verifiable-presentations.mdx new file mode 100644 index 00000000000..096ec3734ff --- /dev/null +++ b/docs/build/identity.rs/1.0/docs/explanations/verifiable-presentations.mdx @@ -0,0 +1,40 @@ +# Verifiable Presentations + +A verifiable presentation is the recommended data format for sharing one or more [verifiable credentials](./verifiable-credentials.mdx). +It is constructed and signed by a holder to prove control over their credentials and can be presented to a verifier for [validation](#validation). + +For instance: after an issuer [creates and issues](./../how-tos/verifiable-credentials/create.mdx) a [verifiable credential](./verifiable-credentials.mdx) to a holder, such as a university issuing a degree to a graduate, +the holder stores it securely until asked to present it. +A company could then request proof of that university degree: the holder can [create a verifiable presentation](./../how-tos/verifiable-credentials/create.mdx) +containing their credential, which is already signed by their university, and present it to the company to [validate](./../how-tos/verifiable-credentials/create.mdx#validate-a-vc). + +Note that verifiable presentations that contain personal data should, as with verifiable credentials, be transmitted and stored securely off-chain to satisfy data privacy regulations such as [GDPR](https://gdpr.eu/). + +:::note + +See the [Verifiable Credentials Data Model Specification](https://www.w3.org/TR/vc-data-model/#presentations) for more information on verifiable presentations. + +::: + +## Security Considerations + +### Replay Attacks + +A verifiable presentation without a challenge and domain properties could potentially be stored by a malicious actor +and replayed to a different verifier, impersonating the holder. +This is because the holder's signature on a presentation would still be seen as valid indefinitely, +until they [rotate](https://www.w3.org/TR/did-core/#verification-method-rotation) the verification method used. + +To mitigate this, verifiers should always send a unique challenge and domain when requesting a verifiable presentation. +These properties are then included in the proof section of the presentation by the holder during signing using [Proof Options](#proof-options). +The digital signature prevents these properties from being altered as it would invalidate the signature, effectively preventing a malicious +actor from injecting different values into old verifiable presentations. A presentation without a challenge and domain +in its proof that matches what was sent by the verifier should be considered invalid. + +The challenge string should be sufficiently random and unique for each verifiable presentation requested by a verifier to avoid +being predicted. The domain, which does not need to be random, is an additional measure. In the unlikely occurrence +of two verifiers generating the same random challenge, the domain would sufficiently distinguish those requests. + +Holders may additionally specify that their signature on a verifiable presentation expires after a short duration, as +per [Proof Options](./../how-tos/verifiable-presentations/create-and-validate.mdx#proof-options). However, verifiers and different implementations could choose to ignore that property, +so setting a signature expiration alone should not be relied upon. \ No newline at end of file diff --git a/docs/build/identity.rs/1.0/docs/libraries/rust/getting_started.mdx b/docs/build/identity.rs/1.0/docs/getting-started/rust.mdx similarity index 93% rename from docs/build/identity.rs/1.0/docs/libraries/rust/getting_started.mdx rename to docs/build/identity.rs/1.0/docs/getting-started/rust.mdx index cc0b4ec55c4..431e991c5f0 100644 --- a/docs/build/identity.rs/1.0/docs/libraries/rust/getting_started.mdx +++ b/docs/build/identity.rs/1.0/docs/getting-started/rust.mdx @@ -1,12 +1,12 @@ --- -title: Getting Started with Rust -sidebar_label: Getting Started +sidebar_label: Rust description: Getting started with the IOTA Identity Rust Library. image: /img/Identity_icon.png keywords: - Rust - Identity --- +# Getting Started with Rust ## Requirements @@ -23,7 +23,7 @@ This version is published to crates.io and is **stable**, following semantic ver ```toml [dependencies] -identity_iota = { version = "0.7.0-alpha" } +identity_iota = { version = "1.0.0" } ``` ### Development Release diff --git a/docs/build/identity.rs/1.0/docs/libraries/wasm/getting_started.mdx b/docs/build/identity.rs/1.0/docs/getting-started/wasm.mdx similarity index 77% rename from docs/build/identity.rs/1.0/docs/libraries/wasm/getting_started.mdx rename to docs/build/identity.rs/1.0/docs/getting-started/wasm.mdx index 0a6d783c737..22978fca285 100644 --- a/docs/build/identity.rs/1.0/docs/libraries/wasm/getting_started.mdx +++ b/docs/build/identity.rs/1.0/docs/getting-started/wasm.mdx @@ -1,6 +1,5 @@ --- -title: Getting Started with WASM -sidebar_label: Getting Started +sidebar_label: Wasm description: Getting started with the IOTA Identity WASM Library. image: /img/Identity_icon.png keywords: @@ -12,54 +11,76 @@ keywords: - nodejs - webpack --- +# Getting Started with WASM -# IOTA Identity WASM - -> This is the beta version of the official WASM bindings for [IOTA Identity](https://github.com/iotaledger/identity.rs). +## Minimum Requirements -## [API Reference](/identity.rs/libraries/wasm/api_reference) +- [Node.js](https://nodejs.org/en) (>= `v16`) -## [Examples](https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/README.md) +## Install the Library -## Install the library +**Latest Release**: This version matches the `main` branch of this repository. -Latest Release: this version matches the `main` branch of this repository. +You can install the library by running the following command: -```bash -npm install @iota/identity-wasm@alpha +```bash npm2yarn +npm install @iota/identity-wasm ``` -## Build +## Build the Library + +Alternatively, you can build the bindings yourself if you have Rust installed. +If not, refer to [rustup.rs](https://rustup.rs) for the installation. + +### Requirements -Alternatively, you can build the bindings yourself if you have Rust installed. If not, refer to [rustup.rs](https://rustup.rs) for the installation. +- [Node.js](https://nodejs.org/en) (>= `v16`) +- [Rust](https://www.rust-lang.org/) (>= 1.62) +- [Cargo](https://doc.rust-lang.org/cargo/) (>= 1.62) -Install [`wasm-bindgen-cli`](https://github.com/rustwasm/wasm-bindgen). A manual installation is required because we use the [Weak References](https://rustwasm.github.io/wasm-bindgen/reference/weak-references.html) feature, which [`wasm-pack` does not expose](https://github.com/rustwasm/wasm-pack/issues/930). +### 1. Install `wasm-bindgen-cli` + +If you want to build the library from source, +you will first need to manually install [`wasm-bindgen-cli`](https://github.com/rustwasm/wasm-bindgen). +A manual installation is required because we use the [Weak References](https://rustwasm.github.io/wasm-bindgen/reference/weak-references.html) feature, +which [`wasm-pack` does not expose](https://github.com/rustwasm/wasm-pack/issues/930). ```bash cargo install --force wasm-bindgen-cli ``` -Then, install the necessary dependencies using: +### 2. Install Dependencies -```bash +After installing `wasm-bindgen-cli`, you can install the necessary dependencies using the following command: + +```bash npm2yarn npm install ``` -and build the bindings for `node.js` with +### 3. Build -```bash + + + + +You can build the bindings for `node.js` using the following command: + +```bash npm2yarn npm run build:nodejs ``` -or for the `web` with -```bash + + + +You can build the bindings for the `web` using the following command: + +```bash npm2yarn npm run build:web ``` -## Minimum Requirements - -The minimum supported version for node is: `v16` + + ## NodeJS Usage @@ -138,7 +159,7 @@ async function main() { main(); ``` -which prints +### Expected Output ``` Created document { @@ -170,17 +191,17 @@ Created document { } ``` -**NOTE: see the [examples](https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/README.md) for how to publish an IOTA DID Document.** +## Web Usage -## Web Setup +### Set Up -The library loads the WASM file with an HTTP GET request, so the .wasm file must be copied to the root of the dist folder. +The library loads the WASM file with an HTTP GET request, so you must copy the `.wasm` file the root of the `dist` folder. -### Rollup +#### Rollup - Install `rollup-plugin-copy`: -```bash +```bash npm2yarn npm install rollup-plugin-copy --save-dev ``` @@ -207,11 +228,11 @@ copy({ }); ``` -### Webpack +#### Webpack - Install `copy-webpack-plugin`: -```bash +```bash npm2yarn npm install copy-webpack-plugin --save-dev ``` @@ -235,7 +256,7 @@ new CopyWebPlugin({ }), ``` -### Web Usage +### Web Usage Example ```typescript import * as client from '@iota/client-wasm/web'; @@ -305,12 +326,16 @@ client await identity.init('./static/identity_wasm_bg.wasm'); ``` -Calling `identity.init().then()` or `await identity.init()` is required to load the Wasm file from the server if not available, because of that it will only be slow for the first time. - -**NOTE: see the [examples](https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/README.md) for how to publish an IOTA DID Document.** +You need to call `identity.init().then()`, +or `await identity.init()` to load the Wasm file from the server if not available, +because of that **it will only be slow for the first time**. ## Examples in the Wild You may find it useful to see how the WASM bindings are being used in existing applications: - [Zebra IOTA Edge SDK](https://github.com/ZebraDevs/Zebra-Iota-Edge-SDK) (mobile apps using Capacitor.js + Svelte) + +## [API Reference](/identity.rs/references/api/wasm) + +## [Examples](https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/README.md) diff --git a/docs/build/identity.rs/1.0/docs/getting_started/create_and_publish.mdx b/docs/build/identity.rs/1.0/docs/getting_started/create_and_publish.mdx deleted file mode 100644 index 811a538514a..00000000000 --- a/docs/build/identity.rs/1.0/docs/getting_started/create_and_publish.mdx +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Create a Decentralized Identity -sidebar_label: Create a DID Document -description: Create DID Documents and publish them -image: /img/Identity_icon.png -keywords: - - Documents - - DID - - Create - - Publish ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -If you want to benefit from Self-Sovereign Identity, you need to create a [Decentralized Identity](../concepts/decentralized_identifiers/overview.mdx). This identity consists of many parts that have different functions. This page will cover the basics about identity creation and publishing. - -## Identity Generation Process - -1. The generation of an identity requires a address with funds to cover the [Storage Deposit](../concepts/decentralized_identifiers/alias.mdx#storage-deposit). In test networks, a faucet can be used to request funds. -2. Create the content of the DID Document, a minimal document contains one verification method. -3. Construct a new [Alias Output](../concepts/decentralized_identifiers/alias.mdx) that includes the DID Document in the [State Metadata](../concepts/decentralized_identifiers/alias.mdx). -4. Publish the generated Alias Output. - -The DID is only known once the [Alias Output](../concepts/decentralized_identifiers/alias.mdx) is successfully published, since the DID's [Tag](../specs/did/iota_did_method_spec.mdx#iota-tag) contains the [Alias ID](../concepts/decentralized_identifiers/alias.mdx#alias-id). - -See the example below to create an identity in Rust or Node.js. - -As this page is a simple overview about creating an identity, further wiki pages are available for more in-depth explanation. Note that the Iota Identity Framework follows [IOTA DID Method Specification](../specs/did/iota_did_method_spec.mdx). - - - - -```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs -``` - - - - -```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts -``` - - - diff --git a/docs/build/identity.rs/1.0/docs/getting_started/install.mdx b/docs/build/identity.rs/1.0/docs/getting_started/install.mdx deleted file mode 100644 index c6afa7e3838..00000000000 --- a/docs/build/identity.rs/1.0/docs/getting_started/install.mdx +++ /dev/null @@ -1,65 +0,0 @@ ---- -description: Install the IOTA Identity Rust Library or its WASM binding in a few simple steps -image: /img/Identity_icon.png -sidebar_label: Install the Library -title: Install the Library -keywords: - - Identity - - install - - npm - - cargo - - Rust - - WASM ---- - -## Rust - -### Requirements - -- [Rust](https://www.rust-lang.org/tools/install) -- [Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) - -### Include the Library - -You can include the IOTA Identity Library in your project by adding it as a dependency in your `Cargo.toml`. - -#### Latest Stable Release - -This version is published to crates.io and is **stable**, following semantic versioning. - -```toml -[dependencies] -identity_iota = { version = "0.7.0-alpha" } -``` - -#### Development Release - -This version matches the `main` branch of this repository. It has all the **latest features**, but as such it **may also have undocumented breaking changes**. - -```toml -[dependencies] -identity_iota = { git = "https://github.com/iotaledger/identity.rs", branch = "main"} -``` - -You can find detailed installation instructions in the [Getting Started With Rust](../libraries/rust/getting_started.mdx) section. - -## WASM - -### Requirements - -- [Npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) -- [Node.js](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) - -### Install the Library - -You can install the WASM binding of the IOTA Identity Library using [npm](https://www.npmjs.com/). - -#### Latest Stable Release - -This version published to npm is **stable**, following semantic versioning. - -```bash -npm install @iota/identity-wasm@alpha -``` - -You can find detailed installation instructions in the [Getting Started With WASM](../libraries/wasm/getting_started.mdx) section. diff --git a/docs/build/identity.rs/1.0/docs/getting_started/overview.mdx b/docs/build/identity.rs/1.0/docs/getting_started/overview.mdx deleted file mode 100644 index 2220e3deca9..00000000000 --- a/docs/build/identity.rs/1.0/docs/getting_started/overview.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -description: Using IOTA Identity, a new digital identity can be created by anyone or anything at any time by generating a Decentralized Identifier (DID) combined with Verifiable Credentials -image: /img/Identity_icon.png -keywords: - - Identity - - verifiable - - credentials - - Rust - - WASM - - reference ---- - -# Overview - -![Identity getting started](/img/banner/banner_identity_getting_started.svg) - -Using the [standards proposed by W3C](https://www.w3.org/TR/did-core/), this section explains the IOTA Identity implementation. You can use this implementation to create a new digital identity for anyone or anything at any time. To do so, you must first generate a [Decentralized Identifier (DID)](../concepts/decentralized_identifiers/overview.mdx) that will serve as a reference to the [DID Document](../concepts/decentralized_identifiers/overview.mdx#did-documents). The DID Document contains public keys and other mechanisms to enable the subject to prove their association with the DID. - -However, you cannot tell much about the subject from a DID. You need to combine the DID with [Verifiable Credentials](../concepts/verifiable_credentials/overview.mdx). Verifiable Credentials are statements about the creator of the DID. They can be shared and verified online in a "Bring Your Own Identity" (BYOI) manner, and the DID creator remains in complete control of the process. - -You can use this framework in processes such as: - -- Address validation: Customers can prove where they live for shipping and billing addresses. -- Age verification: Customers can prove they are 18+ for online purchases. -- (Authority) Login: Customers can prove who they are and gain access to their account, - without passwords. This can be useful for many websites, including eGovernment and - banking. - -## Implementations - -The IOTA Identity framework is developed in the Rust programming language. We also provide bindings, or "Foreign Function Interfaces" (FFI), to other languages. The full set of language bindings currently available is: - -- [Rust](../libraries/rust/getting_started.mdx) -- [WASM](../libraries/wasm/getting_started.mdx) - -## Applications - -The following applications are currently utilizing the IOTA Identity framework: - -- [Selv app](https://selv.iota.org/) diff --git a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/create.mdx b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/create.mdx new file mode 100644 index 00000000000..b5aed539e40 --- /dev/null +++ b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/create.mdx @@ -0,0 +1,181 @@ +--- +title: Creating a Decentralized Identity +sidebar_label: Create and Publish +description: Create DID Documents and publish them to the Tangle +image: /img/Identity_icon.png +keywords: + - Documents + - DID + - Tangle + - Create + - Publish +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +If you want to benefit from Self-Sovereign Identity, +you need to create a [Decentralized Identity](../../explanations/decentralized-identifiers.mdx). +This identity consists of many parts that have different functions. + +:::note DID method Specification + +Note that the Iota Identity Framework follows [IOTA DID Method Specification](../../references/specifications/iota-did-method-spec.mdx). + +::: + +## Identity Generation Process + + +### 1. Get Funds to Cover the Storage Deposit + +The first thing you will need to generate an identity is an address with enough funds to cover +the [Storage Deposit](../../explanations/about-alias-outputs.mdx#storage-deposit). +In test networks, you can use a [faucet](https://faucet.testnet.shimmer.network/) to request funds. + +:::tip + +If you want to use the main Shimmer or IOTA networks, +you will need an output with actual Shimmer or IOTA funds to create a new Alias Output that represents a DID. + +::: + +
+ + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs#L52 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts#L40-L51 +``` + + + +
+ +### 2. Create the Content for the DID Document + +As a bare minimum, a [DID document](../../explanations/decentralized-identifiers.mdx) needs at least one verification method. + +At this point the DID itself is unknown since the Alias Output is not published yet and didn't get an `Alias ID` assigned. + +:::tip + +You can use a placeholder `did:iota:0x0000000000000000000000000000000000000000000000000000000000000000` to reference +the DID inside the document. + +::: + +
+ + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs#L59-L71 +``` + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts#L55C44-L65 +``` + + + +
+ +### 3. Construct a New Alias Output + +Next, you need to construct a new [Alias Output](../../explanations/about-alias-outputs.mdx) that includes the +DID Document in the [State Metadata](../../explanations/about-alias-outputs.mdx). +The created Alias Output contains an encoded version of the DID Document in its `State Metadata`, and has the state +controller and the governor set to the generated [Ed25519](/learn/protocols/chrysalis/core-concepts/EdDSA-support/) address. + +Note that controllers don't need to be Ed25519 addresses, they can be any type of output. +However, they must be unlocked in order perform a state or governance transition when the DID Document is updated or destroyed. + + +
+ + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs#L75 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts#L70 +``` + + + +
+ +### 4. Publish the generated Alias Output. + +The byte cost for the document is automatically calculated and a new transaction is published that includes +the Basic Output as input and the newly generated Alias Output as output, as well as another Basic Output which contains +the remaining token. + +The DID is only known once the [Alias Output](../../explanations/about-alias-outputs.mdx) is successfully published, +since the DID's [Tag](../../references/specifications/iota-did-method-spec.mdx#iota-tag) contains the +[Alias ID](../../explanations/about-alias-outputs.mdx#alias-id). +Once the transaction is confirmed, the `Alias ID` is assigned, and the DID can be derived from it, +the DID Document is stored on the ledger and can be [resolved](resolve.mdx) using any node. + + +
+ + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs#L78 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts#L74 +``` + + + +
+ +## Full Example Code + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts +``` + + + + +## Running a Private Network + +In order to run the examples, you will need to run a private network needs to run locally. +You can refer to [Hornet repository](https://github.com/iotaledger/hornet/tree/develop/private_tangle) for instructions on how to run a private network. + +If your local private network uses different ports than Hornet, modify the API and faucet endpoints in the examples +to match your local setup. diff --git a/docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/delete.mdx b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/delete.mdx similarity index 54% rename from docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/delete.mdx rename to docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/delete.mdx index ded6065d318..465cafff339 100644 --- a/docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/delete.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/delete.mdx @@ -19,20 +19,28 @@ There are two approaches to delete an IOTA Identity, with different implications ## Deactivate -As detailed in the [IOTA DID Method Specification](../../specs/did/iota_did_method_spec.mdx#deactivate), the state controller of an IOTA Identity may [deactivate](https://www.w3.org/TR/did-core/#did-document-metadata) it by publishing an update that either: +As detailed in the [IOTA DID Method Specification](../../references/specifications/iota-did-method-spec.mdx#deactivate), +the state controller of an IOTA Identity may [deactivate](https://www.w3.org/TR/did-core/#did-document-metadata) it by publishing an update that either: - deletes the contents of the DID Document entirely, leaving the state metadata empty, OR - sets the `deactivated` field in the DID Document metadata to `true`. In both cases, the DID Document will be marked as `deactivated` when resolved. -This operation is reversible: the identity can subsequently be reactivated at any time, by publishing an update restoring the DID Document's contents, or unsetting the `deactivated` field in the metadata respectively, depending on how it was initially deactivated. +:::tip Reversible -Note that the governor (if different from the state controller) cannot deactivate an identity directly because it is disallowed from updating the DID Document, but it may [destroy](#destroy) it. +The identity can be reactivated at any time, by publishing an update restoring the DID Document's contents, +or unsetting the `deactivated` field in the metadata respectively, depending on how it was initially deactivated. + +Note that if the governor is different from the state controller, it cannot deactivate an identity directly because +it is disallowed from updating the DID Document, but it may [destroy](#destroy) it. + +::: ### Example -The following example demonstrates deactivating and reactivating an IOTA DID Document, and optionally reclaiming the storage deposit. +The following example demonstrates deactivating and reactivating an IOTA DID Document, +and optionally reclaiming the storage deposit. @@ -53,23 +61,32 @@ https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0 ## Destroy -Alternatively, an IOTA Identity can be permanently [destroyed](../../specs/did/iota_did_method_spec.mdx#destroy). +Alternatively, you can [destroy](../../references/specifications/iota-did-method-spec.mdx#destroy) an IOTA Identity can be permanently. + +:::warning Irreversible + +Destroying an IOTA Identity is permanent and irreversible. + +::: -This is achieved by the governor of a DID publishing a transaction consuming the [Alias Output](../../specs/did/iota_did_method_spec.mdx#alias-output) containing the IOTA DID Document, without a corresponding Alias Output on the output side. + +This is achieved by the governor of a DID publishing a transaction consuming the [Alias Output](../../references/specifications/iota-did-method-spec.mdx#alias-output) +containing the IOTA DID Document, without a corresponding Alias Output on the output side. Any coins and tokens in the Alias Output are reclaimed and can be sent to another address. :::warning -Destroying an IOTA Identity is permanent and irreversible. +Note that historical versions may still be stored off-ledger, or on a permanode, +so sensitive or Personal Identifiable Information (PII) should NEVER be stored in a DID Document. ::: -Note that historical versions may still be stored off-ledger or on a permanode, so sensitive or Personal Identifiable Information (PII) should NEVER be stored in a DID Document. Even with a previous version available, a destroyed DID can never be restored. +Even with a previous version available, a destroyed DID can never be restored. ### Example -The following example demonstrates a governor destroying an IOTA Identity and sending the storage deposit back to itself. +The following example demonstrates a governor destroys an IOTA Identity and sends the storage deposit back to itself. diff --git a/docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/resolve.mdx b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/resolve.mdx similarity index 67% rename from docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/resolve.mdx rename to docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/resolve.mdx index c4738ac5de8..87814227334 100644 --- a/docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/resolve.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/resolve.mdx @@ -10,9 +10,14 @@ keywords: import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -DID resolution is the process of fetching and decoding a [DID Document](https://www.w3.org/TR/did-core/#dfn-did-documents) corresponding to a given [DID](https://www.w3.org/TR/did-core/#dfn-decentralized-identifiers). The [IOTA Identity framework](https://github.com/iotaledger/identity.rs) supports resolving DID Documents that are stored on the IOTA and Shimmer networks and enables users to plug in handlers for additional methods. +DID resolution is the process of fetching and decoding a [DID Document](https://www.w3.org/TR/did-core/#dfn-did-documents) corresponding to a given [DID](https://www.w3.org/TR/did-core/#dfn-decentralized-identifiers). +The [IOTA Identity framework](https://github.com/iotaledger/identity.rs) supports resolving DID Documents that are +stored on the IOTA and Shimmer networks and enables users to plug in handlers for additional methods. -This is similar to, but not to be confused with, the [W3C DID Resolution specification](https://w3c-ccg.github.io/did-resolution/), which defines function signatures for resolution in the context of web or REST APIs, whereas the IOTA Identity framework provides strongly-typed resolution for a better developer experience. +This is similar to, but not to be confused with, +the [W3C DID Resolution specification](https://w3c-ccg.github.io/did-resolution/), +which defines function signatures for resolution in the context of web or REST APIs, +whereas the IOTA Identity framework provides strongly-typed resolution for a better developer experience. This functionality is primarily provided by the `Resolver`, which can: @@ -26,7 +31,10 @@ The following examples demonstrate how to resolve an IOTA DID Document from its ### Resolver -Once the `Resolver` has been configured with a `Client` it will resolve IOTA DID Documents according to the read procedure defined in the [IOTA DID Method Specification](../../specs/did/iota_did_method_spec.mdx#read). It fetches the latest [Alias Output](../../specs/did/iota_did_method_spec.mdx#alias-output) from the network specified in the DID (see [DID Format](../../specs/did/iota_did_method_spec.mdx#did-format)), then extracts and validates the DID Document from it. +Once you have configured `Resolver` with a [`Client`](/iota-sdk/welcome), it will resolve +IOTA DID Documents according to the read procedure defined in the [IOTA DID Method Specification](../../references/specifications/iota-did-method-spec.mdx#read). +It fetches the latest [Alias Output](../../references/specifications/iota-did-method-spec.mdx#alias-output) from the network specified in the DID (see [DID Format](../../references/specifications/iota-did-method-spec.mdx#did-format)), +then extracts and validates the DID Document from it. @@ -92,7 +100,7 @@ const document = await resolver.resolve(did); ### Client -The `Client` can also be used directly, to resolve individual DIDs from its configured network. +You can also use the [`Client`](/iota-sdk/welcome) directly to resolve individual DIDs from its configured network. @@ -143,12 +151,17 @@ const document = await didClient.resolveDid(did); -## Advanced Resolver configuration +## Advanced Resolver Configuration -The `Resolver` can be configured to support many use cases by attaching custom resolution handlers. This enables the resolver to resolve multiple DID methods as well as customizing how -a particular DID method (such as for instance the IOTA method) gets resolved. This feature is mainly intended to be used together with the Resolver's convenience methods for handling verifiable presentations and credentials. +You can configure the `Resolver` to support many use cases by attaching custom resolution handlers. +This enables the `Resolver` to resolve multiple DID methods as well as customizing how +a particular DID method (such as the IOTA method) gets resolved. -### Resolving multiple DID methods +This feature is mainly intended to be used together with the Resolver's convenience methods for +handling [verifiable presentations](../verifiable-presentations/create-and-validate.mdx) +and [credentials](./../../explanations/verifiable-credentials.mdx). + +### Resolving Multiple DID Methods @@ -169,7 +182,12 @@ https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/1 ## Resolution for Verifiable Presentations -When validating [verifiable presentations](../verifiable_credentials/verifiable_presentations.mdx), it is necessary to resolve the DID Documents of the [verifiable credential](../verifiable_credentials/overview.mdx) issuers and presentation holder to verify their signatures. Resolving the necessary DID Documents is performed automatically when verifying presentations via the `Resolver` (see this [example](../verifiable_credentials/verifiable_presentations.mdx#example)). +When validating [verifiable presentations](./../verifiable-presentations/create-and-validate.mdx), you need to +resolve the DID Documents of the [verifiable credential](./../../explanations/verifiable-credentials.mdx) issuers +and presentation holder to verify their signatures. + +Resolving the necessary DID Documents is +[performed automatically when verifying presentations via the `Resolver`](../verifiable-presentations/create-and-validate.mdx#example) When direct access to these DID Documents is desired, the `Resolver` also provides standalone methods to: diff --git a/docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/update.mdx b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/update.mdx similarity index 77% rename from docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/update.mdx rename to docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/update.mdx index 598f8e8a0fd..35c7bed31ae 100644 --- a/docs/build/identity.rs/1.0/docs/concepts/decentralized_identifiers/update.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/update.mdx @@ -1,5 +1,4 @@ --- -title: Update DID Documents sidebar_label: Update description: How DID Documents can be manipulated and how updates should be published image: /img/Identity_icon.png @@ -14,79 +13,71 @@ keywords: import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -DID Documents can be extended by adding [verification methods](#verification-methods), [services](#services) and custom properties. -A verification method adds public keys, which can be used to digitally sign things like a DID message or a verifiable credential, while a service can provide metadata around the identity via URIs. +# Update DID Documents -### Verification Methods +You can extend DID Documents by adding [verification methods](#verification-methods), [services](#services) and custom properties. +A verification method adds public keys, which can be used to digitally sign things like a DID message or a verifiable credential, +while a service can provide metadata around the identity via URIs. -As demonstrated by the [example](#example) below, the IOTA Identity framework offers easy-to-use methods for adding [verification methods](https://www.w3.org/TR/did-core/#verification-methods). +## Verification Methods -The following properties can be specified for a verification method: +As demonstrated by the [example](#example) below, the IOTA Identity framework offers easy-to-use methods for adding +[verification methods](https://www.w3.org/TR/did-core/#verification-methods). -- **id**: a [DID URL](https://www.w3.org/TR/did-core/#did-url-syntax) for the verification method. It can be specified by setting the [fragment](https://www.w3.org/TR/did-core/#fragment); -- **type**: specifies the type of the verification method. The framework supports `Ed25519` and `X25519` key types. This property is automatically filled by the framework when specifying the verification material. -- **publicKeyMultibase**: multibase encoded public key which concludes the [verification material](https://www.w3.org/TR/did-core/#verification-material). This can be automatically generated by the framework or manually provided by users. +### Properties -### Verification Relationships +You can specify the following properties for a verification method: -[Verification relationships](https://www.w3.org/TR/did-core/#verification-relationships) express the relationship between the DID subject and the verification method. It can be used to specify the -the purpose of the verification method. +- **id**: A [DID URL](https://www.w3.org/TR/did-core/#did-url-syntax) for the verification method. You can specify it by setting the [fragment](https://www.w3.org/TR/did-core/#fragment). +- **type**: Specifies the type of the verification method. The framework supports `Ed25519` and `X25519` key types. This property is automatically filled by the framework when specifying the verification material. +- **publicKeyMultibase**: A multi-base encoded public key which concludes the [verification material](https://www.w3.org/TR/did-core/#verification-material). This can be automatically generated by the framework or manually provided by users. + +## Verification Relationships + +[Verification relationships](https://www.w3.org/TR/did-core/#verification-relationships) express the relationship between the DID subject and the verification method. +You can use it to specify the purpose of the verification method. + +### Relationships The following relationships are supported by the Identity Framework: -- **[Authentication](https://www.w3.org/TR/did-core/#authentication)**: used to specify authentication methods for the DID subject. -- **[Assertion](https://www.w3.org/TR/did-core/#assertion)**: can be used for verifiable credential verification. -- **[Key Agreement](https://www.w3.org/TR/did-core/#assertion)**: used for establishing secure communication channels. -- **[Capability Invocation](https://www.w3.org/TR/did-core/#capability-invocation)**: can be used to authorize updates to the DID Document. -- **[Capability Delegation](https://www.w3.org/TR/did-core/#capability-delegation)**: a mechanism to delegate cryptographic capability to another party. +- **[Authentication](https://www.w3.org/TR/did-core/#authentication)**: Used to specify authentication methods for the DID subject. +- **[Assertion](https://www.w3.org/TR/did-core/#assertion)**: Used to verify verifiable credentials. +- **[Key Agreement](https://www.w3.org/TR/did-core/#assertion)**: Used for establishing secure communication channels. +- **[Capability Invocation](https://www.w3.org/TR/did-core/#capability-invocation)**: Can be used to authorize updates to the DID Document. +- **[Capability Delegation](https://www.w3.org/TR/did-core/#capability-delegation)**: A mechanism to delegate cryptographic capability to another party. Verification methods can be either [embedded or referenced](https://www.w3.org/TR/did-core/#referring-to-verification-methods). Referencing verification -methods allow them to be used by more than one verification relationship. -Upon creating a verification method using the identity framework, specifying the `MethodScope` option will result in an embedded verification method. Leaving that option unset will create the verification method as -a map entry of the `verificationMethod` property. Verification relationships can be added afterwards using references. +methods allows them to be used by more than one verification relationship. +When you create a verification method using the identity framework, specifying the `MethodScope` option will result in an embedded verification method. +Leaving that option unset will create the verification method as a map entry of the `verificationMethod` property. +You can also add verification relationships afterward using references. :::note -Updates to the DID Document are done through a state transition of the [Alias Output](../../specs/did/iota_did_method_spec.mdx#alias-output) by its state controller. The public key or address of the state controller does not need to be a verification method in the DID Document, since it is defined in the containing Alias Output. +Updates to the DID Document are done through a state transition of the [Alias Output](../../references/specifications/iota-did-method-spec.mdx#alias-output) by its state controller. +The public key or address of the state controller does not need to be a verification method in the DID Document, +since it is defined in the containing Alias Output. ::: -### Services +## Services -[Services](https://www.w3.org/TR/did-core/#services) allow adding other ways of communicating with the DID subject. An endpoint included in the DID Document can offer a way of reaching services for different purposes +[Services](https://www.w3.org/TR/did-core/#services) allow you to add other ways of communicating with the DID subject. +An endpoint included in the DID Document can offer a way of reaching services for different purposes like authentication, communicating, and discovery. -The following properties can be specified for a service: - -- **id**: a [DID URL](https://www.w3.org/TR/did-core/#did-url-syntax) for referencing the service in the DID document. - It can be specified by setting the [fragment](https://www.w3.org/TR/did-core/#fragment). -- **type**: a string used to maximize interoperability between services. The framework does not perform any checks on the content of this string. -- **serviceEndpoint**: a URL that points to the service endpoint. - -## Example - -The following example demonstrates managing verification methods and services in a DID Document. - - - - -```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/1_update_did.rs -``` - - - +### Properties -```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/1_update_did.ts -``` +You can specify the following properties for a service: - - +- **id**: A [DID URL](https://www.w3.org/TR/did-core/#did-url-syntax) for referencing the service in the DID document. You can specify it by setting the [fragment](https://www.w3.org/TR/did-core/#fragment). +- **type**: A string used to maximize interoperability between services. The framework does not perform any checks on the content of this string. +- **serviceEndpoint**: A URL that points to the service endpoint. -### Creating Identity +## Create Identity -The example above starts by [creating an identity](./create.mdx). +Before you can update anything, you will need to [create an Identity](./create.mdx). @@ -104,7 +95,6 @@ StrongholdSecretManager::builder() // Create a new DID in an Alias Output for us to modify. let (_, did): (Address, StardustDID) = create_did(&client, &mut secret_manager).await?; - ``` @@ -139,7 +129,7 @@ This creates and publishes an Alias Output containing a DID Document with one ve } ``` -### Adding Verification Method +## Add a Verification Method @@ -198,11 +188,11 @@ This creates a new verification method that includes a newly generated Ed25519 p } ``` -Notice that these changes to the document are not published yet. This will be done in a later stage. +Notice that these changes to the document are not [published](#publish-your-updates) yet. -### Adding Verification Relationships +## Add Verification Relationships -Verification relationship can be attached to a verification method by referencing its fragment. +You can attach verification relationships to a verification method by referencing its fragment. @@ -229,9 +219,10 @@ document.attachMethodRelationship( -This will add `Authentication` relationship to the verification method with the fragment `key-1`. Note that `Authentication` references the already included verification method: +This will add `Authentication` relationship to the verification method with the fragment `key-1`. +Note that `Authentication` references the already included `key-2` verification method: -```json +```json {12,19} { "doc": { "id": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483", @@ -260,7 +251,9 @@ This will add `Authentication` relationship to the verification method with the } ``` -### Adding a Service +## Add a Service + +You can also add custom properties can to a service by setting `properties`: @@ -293,11 +286,9 @@ document.setMetadataUpdated(Timestamp.nowUTC()); -Additionally, custom properties can be added to a service by setting `properties` in both Rust and JavaScript. - The updated Document with the newly created service looks as follows. -```json +```json {21-27} { "doc": { "id": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483", @@ -333,7 +324,9 @@ The updated Document with the newly created service looks as follows. } ``` -### Removing Verification Method +## Remove a Verification Method + +You can also remove verification methods at any time using the following snippet: @@ -388,7 +381,7 @@ This removes the original verification method with the fragment `key-1`. } ``` -### Publishing +## Publish Your Updates Publish the updated DID Document inside the Alias Output taking into account the increase in the storage deposit needed. @@ -434,3 +427,22 @@ const updated: StardustDocument = await didClient.publishDidOutput( + +## Full Example Code + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/1_update_did.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/1_update_did.ts +``` + + + \ No newline at end of file diff --git a/docs/build/identity.rs/1.0/docs/concepts/domain_linkage/domain_linkage.mdx b/docs/build/identity.rs/1.0/docs/how-tos/domain-linkage/create-and-verify.mdx similarity index 56% rename from docs/build/identity.rs/1.0/docs/concepts/domain_linkage/domain_linkage.mdx rename to docs/build/identity.rs/1.0/docs/how-tos/domain-linkage/create-and-verify.mdx index 550386d5750..c01de0c4c23 100644 --- a/docs/build/identity.rs/1.0/docs/concepts/domain_linkage/domain_linkage.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/domain-linkage/create-and-verify.mdx @@ -1,7 +1,6 @@ --- -title: Domain Linkage +description: How to link a domain and a DID sidebar_label: Create and Verify -description: Explain how to link a domain and a DID image: /img/Identity_icon.png keywords: - well-known @@ -21,16 +20,24 @@ To use Domain Linkage in Rust you have to enable the `domain-linkage` feature. ## Overview -Domain Linkage can provide proof for a connection between a DID and a domain being controlled by the same entity. This linkage can transfer trust from a domain to a DID and vice verca. For instance, if an entity trusts a domain, it can also trust the linked DID and all documents signed by verification methods included in the DID Document. A use case coud be a verifier that trusts `www.example.com` and receives a Verifiable Presentation issued by `did:foo:abc`. By `did:foo:abc` being linked to `www.example.com`, the verifier can trust that the Verifiable Presentation is issued by the same entity controlling `www.example.com`. -The DIF has approved a [Well Known DID Configuration](https://identity.foundation/.well-known/resources/did-configuration/) draft to standardize this connection by introducing the [DID Configuration Resource](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource) and the [Linked Domain Service Endpoint](https://identity.foundation/.well-known/resources/did-configuration/#linked-domain-service-endpoint). +Domain Linkage can provide proof for a connection between a DID and a domain being controlled by the same entity. +This linkage can transfer trust from a domain to a DID and vice versa. +For instance, if an entity trusts a domain, it can also trust the linked DID and all documents signed by +the verification methods included in the DID Document. + +A use case could be a verifier that trusts `www.example.com`, and receives a verifiable presentation issued by `did:foo:abc`. +If `did:foo:abc` is linked to `www.example.com`, the verifier can trust that the verifiable presentation is issued by +the same entity controlling `www.example.com`. +The DIF has approved a [Well Known DID Configuration](https://identity.foundation/.well-known/resources/did-configuration/) draft to standardize this connection by introducing +the [DID Configuration Resource](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource) and the [Linked Domain Service Endpoint](https://identity.foundation/.well-known/resources/did-configuration/#linked-domain-service-endpoint). ![Identity getting started](/img/domain-linkage-diagram.png) ### DID Configuration Resource -Suppose that a DID `did:foo:example` with the following DID Document only containing a `verificationMethod` `key-1` +Suppose that a DID `did:foo:example` with the following DID Document only contains one `verificationMethod`, `key-1`: -```json +```json {5} { "id": "did:foo:abc", "verificationMethod": [ @@ -44,17 +51,25 @@ Suppose that a DID `did:foo:example` with the following DID Document only contai }, ``` -and the domain `https://www.example.com` represents the same entity and need be linked to increase trust in the DID. +The domain `https://www.example.com` represents the same entity and needs to be linked to increase trust in the DID. -To establish this linkage, A [DID Configuration Resource](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource) must be created and made available on the [DID Configuration URL](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-uri). In this case it's `https://example.com/.well-known/did-configuration.json`. +To establish this link, you must create a [DID Configuration Resource](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource), +and make it available on the [DID Configuration URL](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-uri). +In this case it's `https://example.com/.well-known/did-configuration.json`. -The [DID Configuration Resource](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource) is a JSON-LD object containing verifiable credentials called `Domain Linkage Credentials`. Each credential represents a linkage to a single DID. +The [DID Configuration Resource](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource) is a JSON-LD object containing verifiable credentials called `Domain Linkage Credentials`. +Each credential represents a linkage to a single DID. :::note -Note that one `DID Configuration Resource` can include multiple `Domain Linkage Credentials` effectivaly linking the same domain to multiple DIDs. + +Note that one `DID Configuration Resource` can include multiple `Domain Linkage Credentials`, +effectively linking the same domain to multiple DIDs. + ::: -In this example, the domain `https://www.example.com` needs to be linked to the DID `did:foo:abc`. This means that the `DID Configuration Resource` will have one `Domain Linkage Credential`. This credential must have the following properties: +In this example, the domain `https://www.example.com` needs to be linked to the DID `did:foo:abc`. +This means that the `DID Configuration Resource` will have one `Domain Linkage Credential`. +This credential must have the following properties: - Its `type` includes `DomainLinkageCredential`. - It includes the DID Configuration context. @@ -89,13 +104,19 @@ In this example, the domain `https://www.example.com` needs to be linked to the } ``` -Now this `DID Configuration Resource` must be made available on `https://example.com/.well-known/did-configuration.json` which establishes the linkage. +Now this `DID Configuration Resource` must be made available on `https://example.com/.well-known/did-configuration.json`, +which establishes the linkage. ### Linked Domain Service Endpoint -By having a domain, one can discover what DIDs are linked to it by fetching the `DID Configuration Resource` and investigating the `Domain Linkage Credentials`. To enable discovery from the other direction, when having a DID and wanting to discover which domains are linked to it, a [Linked Domain Service Endpoint](https://identity.foundation/.well-known/resources/did-configuration/#linked-domain-service-endpoint) can be added to the DID Document. The DID Document from this example will be extended as follows to enable discovery of `https://www.example.com`: +By having a domain, one can discover what DIDs are linked to it by fetching the `DID Configuration Resource` and +investigating the `Domain Linkage Credentials`. -```json +If you want to enable discovery from the other direction, that is, if you have a DID and want to discover which +domains are linked to it, you can add a [Linked Domain Service Endpoint](https://identity.foundation/.well-known/resources/did-configuration/#linked-domain-service-endpoint) to the DID Document. +The DID Document from this example will be extended as follows to enable discovery of `https://www.example.com`: + +```json {11-17} { "id": "did:foo:abc", "verificationMethod": [ @@ -120,17 +141,25 @@ By having a domain, one can discover what DIDs are linked to it by fetching the Note that a DID Document can have multiple `Linked Domain Services` and each service can link to multiple domains. ::: -### Verifying DID and Domain Linkage +### Verifying a DID and Domain Linkage -As mentioned above, the discovery of the Domain Linkage can happen from either direction. But verifying the linkage in both cases involves only verifying the DID Configuration Resource. The process is as follows: +As mentioned above, you can discover the Domain Linkage from either direction. +But verifying the linkage in both cases involves only verifying the DID Configuration Resource. +The process is as follows: 1. Fetch `DID Configuration Resource` from `https://www.example.com/.well-known/did-configuration.json`. 2. Resolve the DID Document of `did:foo:abc`. 3. Verify the `DID Configuration Resource` and its `Domain Linkage Credential` that references `did:foo:abc`. -Here you can learn more about [DID Configuration Resource Verification](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource-verification). -### Example +:::tip About DID Configuration Resource Verification + +You can learn more +[about DID Configuration Resource Verification on the Identity Foundation website](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource-verification). + +::: + +## Example Code diff --git a/docs/build/identity.rs/1.0/docs/how-tos/key-storage.mdx b/docs/build/identity.rs/1.0/docs/how-tos/key-storage.mdx new file mode 100644 index 00000000000..1e1fdb28673 --- /dev/null +++ b/docs/build/identity.rs/1.0/docs/how-tos/key-storage.mdx @@ -0,0 +1,152 @@ +--- +title: Key Storage +sidebar_label: Key Storage +description: Explain the use of the storage interfaces and how they can be implemented +image: /img/Identity_icon.png +keywords: + - key storage + - storage interfaces + - json web key + - json web algorithm + - signing +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Introduction + +The `JwkDocumentExt` API allows you to modify a DID document, for example, adding new verification methods. +It enables storing the secrets that verification methods represent in a secure manner. +It does so by using the two storage interfaces, namely the `JwkStorage` and `KeyIdStorage`. +We refer to both of these as the **key storage**. + +The main idea behind the key storage is strongly inspired by the architecture of key management systems (KMS) +or secure enclaves: once private keys are entered into the system, they can never be retrieved again. +Instead, all operations using the key will have to go through that system. + +This approach allows the key storage to be architected more securely than simply storing and loading private keys from +a regular database. +Of course, security is directly dependent on the concrete implementation, +which is why we provide [Stronghold](https://github.com/iotaledger/stronghold.rs/), a best-effort in-software enclave, by default. + +However, there are cases where one cannot use `Stronghold`, +or may want to integrate key management of identities into their own KMS or similar, +which is why the key storage is an abstraction over such systems. +Any implementation of a key storage can be used by the `JwkDocumentExt` API. + +The two interfaces making up the key storage have two respective responsibilities. + +:::info + +Even though there are two separate interfaces, you can implement them using the same backing storage, if desired. + +::: + +## Function Overview + +A brief overview of those functions: + +- `JwkStorage`: CRUD and signing operations on [JSON Web Keys](https://www.rfc-editor.org/rfc/rfc7517). + - `generate`: Generate a new key represented as a JSON Web Key. + - `insert`: Insert an existing JSON Web Key into the storage. + - `sign`: Signs the provided data using the stored private key. + - `delete`: Permanently deletes a key. + - `exists`: Returns whether a key exists. +- `KeyIdStorage`: Stores the mappings from verification methods to their corresponding key identifier in the `JwkStorage`. + - `insert_key_id`: Inserts a mapping from a verification method identifier to a key identifier. + - `get_key_id`: Returns the key identifier for a given verification method identifier. + - `delete_key_id`: Deletes a mapping. + +## Key Identifier + +A `JwkStorage` stores and operates on keys, so they must be identified. +In general, Key Management Systems use some form of an identifier for their keys. +To abstract over those, the `JwkStorage` interface has a general-purpose `KeyId` type, +which is effectively a wrapper around a string. + +A `KeyIdStorage` is needed to store the key id that represents the private key for a given verification method. +To that end, a verification method itself must be identified. + +While within a document, each fragment must be unique, the same is not true given multiple documents, +so we cannot rely only on fragments if we don't want to partition the `KeyIdStorage` by DID. +The solution to this is using a `MethodDigest`, a hash over a verification method. + +When following best security practices, each verification method has its own key associated, and thus a unique public key. +That, plus the fragment of a method ensures the `MethodDigest` is unique. + +So in essence, a `JwkStorage` stores a `KeyId -> JWK` mapping while a `KeyIdStorage` stores a `MethodDigest -> KeyId` mapping. + +:::caution + +Given the construction and limitations of the method digest, +no two documents should contain a method that shares both the same fragment and public key. +This should not happen under typical circumstances, but is good to keep in mind. + +::: + +## Key Types + +To express what key types a given `JwkStorage` implementation supports, you should use the `KeyType`, +which is another simple wrapper around a string. + +The reason for this design might seem odd in Rust, given the existence of associated types. +This more simplistic design is necessary to accommodate implementing the interface via the bindings to the library. + +Implementations are expected to export constants of the key types they support, +so users have an easy way to discover the supported types. +In general, storage implementations are free to support any [JSON Web Algorithm](https://www.rfc-editor.org/rfc/rfc7518.html)-compatible key. +However, the recommended default used by IOTA Identity is the `EdDSA` algorithm with curve `Ed25519`. + +## Implementation + +The IOTA Identity library ships two implementations of key storage. +The `JwkMemStore` and `KeyIdMemstore` are insecure in-memory implementations +intended as example implementations and for testing. + +The default key storage implementation is `Stronghold`, +which is an example of a storage that implements both storage interfaces simultaneously. +[`Stronghold`](https://github.com/iotaledger/stronghold.rs/) may be interesting for implementers to look at, +as it needs to deal with some challenges the in-memory version does not have to deal with. Note that the `Stronghold` implementation is only available in Rust. + +## Examples + +This section shows the Rust and TypeScript `Memstore` implementations. + +### `JwkMemStore` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/lib/jwk_storage.ts +``` + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/identity_storage/src/key_storage/memstore.rs +``` + + + + +### `KeyIdMemstore` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/lib/key_id_storage.ts +``` + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/identity_storage/src/key_id_storage/memstore.rs +``` + + + diff --git a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/create.mdx b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/create.mdx new file mode 100644 index 00000000000..fab18662724 --- /dev/null +++ b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/create.mdx @@ -0,0 +1,160 @@ +--- +title: Create a Verifiable Credential +sidebar_label: Create and Sign +description: Explain how a VC is created and verified +image: /img/Identity_icon.png +keywords: + - verifiable + - credentials + - Create + - sign +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +A [verifiable credential (VC)](./../../explanations/verifiable-credentials.mdx) can represent all +information that a physical credential represents, such as a passport or university +degree. However, by allowing other parties to cryptographically verify the authorship +and integrity of the claims, verifiable credentials can be seen as more tamper-evident +and more trustworthy than their physical counterparts. + +## Verifiable Credential Properties + +In the IOTA Identity Framework, you can create a Verifiable Credential with the following properties: + +- [**Context**](https://www.w3.org/TR/vc-data-model/#contexts): List of JSON-LD context URIs. Includes `"https://www.w3.org/2018/credentials/v1"` by default. +- [**Types**](https://www.w3.org/TR/vc-data-model/#types): List of types describing the credential. Includes `"VerifiableCredential"` by default. +- [**Subject**](https://www.w3.org/TR/vc-data-model/#credential-subject): The issuer's claims; a set of objects that contain one or more properties that are each related to a subject. +- [**Issuer**](https://www.w3.org/TR/vc-data-model/#issuer): The identifier of the issuer, typically their [DID](../../explanations/decentralized-identifiers.mdx). +- [**ID**](https://www.w3.org/TR/vc-data-model/#identifiers): Optional URI identifier for the credential. +- [**Issuance Date**](https://www.w3.org/TR/vc-data-model/#issuance-date): Optional timestamp for expressing the date and time when a credential becomes valid. +- [**Expiration Date**](https://www.w3.org/TR/vc-data-model/#expiration): Optional timestamp for expressing the date and time when a credential ceases to be valid. +- [**Status**](https://www.w3.org/TR/vc-data-model/#status): Optional information used to determine the current status of a credential, i.e. whether or not it has been [revoked](./revocation.mdx). +- [**Schema**](https://www.w3.org/TR/vc-data-model/#data-schemas): Optional list of objects specifying the schema that the data must conform to. +- [**Refresh Service**](https://www.w3.org/TR/vc-data-model/#refreshing): Optional link to a service where the recipient may refresh the included credentials. +- [**Terms of Use**](https://www.w3.org/TR/vc-data-model/#terms-of-use): Optional list of policies defining obligations, prohibitions, or permissions of the presentation recipient. +- [**Evidence**](https://www.w3.org/TR/vc-data-model/#evidence): Optional list of objects that can be used by the issuer to provide the verifier with additional supporting information in a verifiable credential. +- [**Non-Transferable**](https://www.w3.org/TR/vc-data-model/#nontransferable-property): Optional flag that indicates that a verifiable credential must only be encapsulated in a [verifiable presentation](./../../explanations/verifiable-presentations.mdx) whose proof was issued by the credential subject. + +## Signing {#signing} + +After creation, the issuer signs the verifiable credential using one of their private keys, +embedding the digital signature in its [proof](https://www.w3.org/TR/vc-data-model/#proofs-signatures) section. + +This is what allows verifiers to independently validate the credential using the corresponding public key from the issuer's DID Document. + +### Proof Options {#proof-options} + +A digital signature on a verifiable credential both provides data integrity and proves the DID of the issuer. +The proof section embedded in a credential may also include additional metadata. + +The following metadata properties can be configured by the framework and are optional and omitted by default: + +- **Created**: Timestamp of when the credential was signed, recommended. +- **Expires**: Timestamp after which the signature is no longer considered valid. Implementers should prefer to set the dedicated **Expiration Date** property on credentials instead. +- **Proof Purpose**: Indicates the purpose of the signature. + - **AssertionMethod**: To assert a claim. The signing verification method must have an [`assertionMethod`](https://www.w3.org/TR/did-core/#assertion) relationship to be valid. + - **Authentication**: To authenticate the signer. The signing verification method must have an [`authentication`](https://www.w3.org/TR/did-core/#authentication) relationship to be valid. + +Most verifiable credentials should be signed with the assertion method proof purpose +to clearly indicate that the signature is asserting a claim and restrict it to valid verification methods. +Whereas a proof may be attached to a [verifiable presentation](./../../explanations/verifiable-presentations.mdx) for authentication purposes. + +Other metadata fields such as `challenge` and `domain` may be included, however they are more pertinent for [verifiable presentations](./../../explanations/verifiable-presentations.mdx). + +## Validation + +Verifiers should ensure certain properties of a credential are valid when receiving one or more in a [verifiable presentation](./../../explanations/verifiable-presentations.mdx). Both issuers and holders may also wish to validate their credentials, particularly directly after creating or receiving one. Validation may be performed at any point in time and can be a useful way of checking whether a credential has expired or been revoked. + +### Validation Checks + +The IOTA Identity Framework supports the following checks during credential validation: + +- **Semantic structure**: Ensures the credential adheres to the specification. +- **Proof**: Verifies the signature against the DID Document of the issuer. +- **Optional validations**: Additional checks on credential properties, and the signature can be configured by specifying [Validation Options](#validation-options). + +### Validation Options + +These options specify conditions that specific properties in a credential must satisfy. + +- **Expiry Date**: Check that the [`expirationDate`](https://www.w3.org/TR/vc-data-model/#expiration) property, if present, is not before a specific datetime. Defaults to the current datetime if unset. +- **Issuance Date**: Check that that [`issuanceDate`](https://www.w3.org/TR/vc-data-model/#issuance-date) property, if present, is not after a specific datetime. Defaults to the current datetime if unset. +- **Verifier Options**: Validates aspects of the credential signature and its metadata, see [Proof Options](#proof-options). + +## Sharing Verifiable Credentials + +A [verifiable presentation](./../../explanations/verifiable-presentations.mdx) is the recommended data format for sharing one or more verifiable credentials, +as it provides cryptographic means of proving the DID of the holder presenting them, +and for enforcing [subject-holder relationships](https://www.w3.org/TR/vc-data-model/#subject-holder-relationships). + +## Example + +The following code showcases how an issuer can [create, sign](#create-and-sign-vc), +and [validate](#validate-a-vc) a verifiable credential. +In this example, the issuer signs a `UniversityDegreeCredential` with Alice's name and DID. + +### Create and Sign a VC + + +
+ + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/5_create_vc.rs#L67-L98 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/5_create_vc.ts#L51-L74 +``` + + + +
+ +### Validate a VC + +
+ + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/5_create_vc.rs#L105-L113 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/5_create_vc.ts#L83-L88 +``` + + + +
+ +This Verifiable Credential can be [verified by anyone](./../../explanations/verifiable-presentations.mdx), +allowing Alice to take control of it and share it with anyone. + +### Full Example Code + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/5_create_vc.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/5_create_vc.ts +``` + + + diff --git a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/revocation.mdx b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/revocation.mdx new file mode 100644 index 00000000000..51efdcd78ee --- /dev/null +++ b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/revocation.mdx @@ -0,0 +1,129 @@ +--- +sidebar_label: Revoke +description: Explain how a VC can be revoked +image: /img/Identity_icon.png +keywords: + - verifiable + - credentials + - revoke + - revocation +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Revoke a Verifiable Credential + +The [example](#example) below demonstrates two methods that an issuer can use to revoke a verifiable credential +using the IOTA Identity Framework: + +1. By using the [`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) field in a credential and linking to a +[revocation bitmap](#revocation-bitmap), +using the [`RevocationBitmap2022`](/identity.rs/references/specifications/revocation-bitmap-2022/). +2. By [removing the verification method](#removing-the-verification-method) that signed the credential. +This invalidates all credentials that were signed with that verification method. + +## Revocation Bitmap + + +One of the ways for an issuer to control the status of its credentials is by using a revocation list. +At the most basic level, revocation information for all verifiable credentials issued by an issuer are expressed as +simple binary values. +The issuer keeps a list of all verifiable credentials it has issued in a bitmap. +Each verifiable credential is associated with a unique index in the list. + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/7_revoke_vc.rs#L167 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L156 +``` + + + + +If the binary value of the index in the bitmap is 1 (one), the verifiable credential is revoked, +if it is 0 (zero) it is not revoked. + +For example, with this approach the issuer adds an index to a credential in the `credentialStatus` field, such as `"5"`. +This part of the credential might then look like this: + +```json +"credentialStatus": { + "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation", + "type": "RevocationBitmap2022", + "revocationBitmapIndex": "5" +}, +``` + +The verifier uses the `id` field (`did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation`) to look up the +service in the issuer's DID document: + +```json +{ + "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation", + "type": "RevocationBitmap2022", + "serviceEndpoint": "data:application/octet-stream;base64,ZUp5ek1tQmdZR1NBQUFFZ1ptVUFBQWZPQUlF" +} +``` + +During verification, the verifier decodes the revocation bitmap embedded in the `data` url. +This bitmap written as a bitstring looks like this: `000001`. +Here, the 5th bit is set, which means the credential with that index is revoked, +while all other credentials aren't revoked. + +## Removing the Verification Method + +A less efficient alternative is to remove the verification method that signed the credential from the DID Document of +the issuer. +This means the VC can no longer be validated. + +However, this will also invalidate every VC signed with that verification method, +meaning that the issuer will have to sign every VC with a different key to retain +precise control over which credential is revoked. + + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/7_revoke_vc.rs#L197-L204 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L192C1-L195 +``` + + + + +## Full Example Code + +The following code exemplifies how you can revoke a [Verifiable Credential (VC)](../../explanations/verifiable-credentials.mdx). + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/7_revoke_vc.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts +``` + + + diff --git a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-presentations/create-and-validate.mdx b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-presentations/create-and-validate.mdx new file mode 100644 index 00000000000..7ae2620df99 --- /dev/null +++ b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-presentations/create-and-validate.mdx @@ -0,0 +1,164 @@ +--- +sidebar_label: Create and Validate +description: Explain how a VP is created and verified +image: /img/Identity_icon.png +keywords: + - verifiable + - presentations +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Create and Validate Verifiable Presentations + +The IOTA Identity Framework enables holders tos easily construct +[verifiable presentations](./../../explanations/verifiable-presentations.mdx). +As demonstrated in the [example](#example), +holders only need to pass in their credentials to present and sign the presentation. + +## Properties + +You can specify the following properties in a presentation: + +- [**ID**](https://www.w3.org/TR/vc-data-model/#identifiers): Optional URI identifier for the presentation. +- [**Context**](https://www.w3.org/TR/vc-data-model/#contexts): List of JSON-LD context URIs. Includes `"https://www.w3.org/2018/credentials/v1"` by default. +- [**Types**](https://www.w3.org/TR/vc-data-model/#types): List of types describing the presentation. Includes `"VerifiablePresentation"` by default. +- [**Credentials**](https://www.w3.org/TR/vc-data-model/#dfn-verifiable-credentials): List of verifiable credentials to present. +- [**Holder**](https://www.w3.org/TR/vc-data-model/#dfn-holders): Optional URI, typically a DID, of the entity that generated the presentation. +- [**Refresh Service**](https://www.w3.org/TR/vc-data-model/#refreshing): Optional link to a service where the recipient may refresh the included credentials. +- [**Terms of Use**](https://www.w3.org/TR/vc-data-model/#terms-of-use): Optional list of policies defining obligations, prohibitions, or permissions of the presentation recipient. + +Of the above, **only the list of credentials is required** when creating a presentation using the framework. +However, the holder property should be included to satisfy [subject-holder relationship](#subject-holder-relationship) checks during validation. + +After creation, the holder signs the verifiable presentation using a private key linked to one of the verification +methods in their DID Document and transmits it to a verifier for validation. + +## Proof Options + +A digital signature on a verifiable presentation provides data integrity, +and also proves the [DID](../../explanations/decentralized-identifiers.mdx) of the holder. + +### Metadata Properties + +The proof section embedded in a presentation may also include additional metadata. + +The following metadata properties can be configured by the framework and are optional and omitted by default: + +- **Created**: Timestamp of when the presentation was signed. +- **Expires**: Timestamp after which the presentation is no longer considered valid. +- **Challenge**: Arbitrary random string. Sent by the verifier and mitigates replay attacks; should be sufficiently random and uniquely generated per presentation request. +- **Domain**: Arbitrary string. Sent by the verifier and can help mitigate replay attacks when used with a challenge. +- **Proof Purpose**: Indicates the purpose of the signature. + - **AssertionMethod**: To assert a claim. The signing verification method must have an [`assertionMethod`](https://www.w3.org/TR/did-core/#assertion) relationship to be valid. + - **Authentication**: To authenticate the signer. The signing verification method must have an [`authentication`](https://www.w3.org/TR/did-core/#authentication) relationship to be valid. + +:::note + +Verifiers should always send a challenge and domain +to [mitigate replay attacks](./../../explanations/verifiable-presentations.mdx#security-considerations). + +::: + +A verifier could also choose to ignore some or all of these options. +See [Proof Verifier Options](#proof-verifier-options) for more information. + +## Validation + +The IOTA Identity Framework provides several options for verifiers to validate various sections of a verifiable presentation. +See the [example](#example) for a demonstration of how to validate a presentation. + +The framework checks: + +- **Semantic structure**: Ensures the presentation and its credentials adhere to the specification. +- **Presentation proof**: Verifies the presentation signature against the DID Document of the holder. +- **Credential proofs**: Verifies the credential signatures against the DID Documents of their respective issuers. +- **Optional validations**: Additional checks on signatures and credential fields can be configured by the verifier. + +Note that a verifier may specify which DID Documents to use for the holder and issuers. +Otherwise, they are resolved from the Tangle automatically. + +Currently, the following are **not** checked automatically: + +- **Data schemas**: Credentials that specify a [schema](https://www.w3.org/TR/vc-data-model/#data-schemas) property +should be examined to ensure conformance. +- **Fitness for purpose**: Whether the credentials in a presentation and the data within them are acceptable and +valid depends on the context in which they are used. Verifiers should ensure that the credential types, subjects, +and schemas sent by a holder match what was requested. +- **Issuer trustworthiness**: Verifiers must check that they trust the issuer on each individual credential in a +presentation. The framework only verifies that the issuer's signature on each credential is current and valid +against the given options. + +The default validation behavior may be modified by the following options. + +### Proof Verifier Options + +While the framework always verifies that the digital signature on a verifiable presentation is valid, +a verifier may validate additional fields in the proof on a presentation. +Notably, to mitigate potential [replay attacks](./../../explanations/verifiable-presentations.mdx#security-considerations), +a verifier should always check that the challenge and domain fields match what was sent to the holder when +requesting the presentation. + +The following options are available: + +- **Method Scope**: check the signing verification method has a particular [verification relationship](https://www.w3.org/TR/did-core/#verification-relationships). Overridden by the proof purpose check. +- **Method Type**: check the signing verification method has a particular type. +- **Challenge**: check the challenge field matches this string. +- **Domain**: check the domain field matches this string. +- **Proof Purpose**: require a specific purpose on the proof. See [Proof Options](#proof-options). +- **Allow Expired**: accept proofs where the current datetime is after their expiration. Default is to reject expired proofs. + +See [Proof Options](#proof-options) for more information on setting these properties as a holder when signing a verifiable presentation. + +## Subject-Holder Relationship + +Specifies the expected relationship between the holder that signed the verifiable presentation and the subject +specified in each [verifiable credential](./../../explanations/verifiable-credentials.mdx). +This can be restricted by the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property, +which indicates that a verifiable credential must only be encapsulated into a verifiable presentation whose holder matches the credential subject. + +By default, the framework always enforces that the holder matches the subject on all credentials. + +The following options are available to modify that behavior: + +- **`AlwaysSubject` (default)**: The holder DID that signed the presentation must match the [`credentialSubject` `id`](https://www.w3.org/TR/vc-data-model/#credential-subject) field in each of the attached credentials. This is the safest option which ensures holders may only present credentials that were directly issued to their DID. An error is thrown on a mismatch or if no subject `id` is present. +- **`SubjectOnNonTransferable`**: The holder DID must match the subject only for credentials where the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property is `true`. This is appropriate for accepting [bearer credentials](https://www.w3.org/TR/vc-data-model/#bearer-credentials) while still adhering to the specification. +- **`Any`**: The holder DID is not required to have any kind of relationship to any credential subject. This option performs no checks and ignores the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property. + +:::note + +See the [Verifiable Credentials Data Model Specification](https://www.w3.org/TR/vc-data-model/#subject-holder-relationships) +for further discussion on the different subject-holder relationships. + +::: + +### Credential Validation Options + +These options specify conditions that all credentials in a verifiable presentation must satisfy. + +- **Expiry Date**: Check that the [`expirationDate`](https://www.w3.org/TR/vc-data-model/#expiration) property, if present, is not before a specific datetime. Defaults to the current datetime if unset. +- **Issuance Date**: Check that the [`issuanceDate`](https://www.w3.org/TR/vc-data-model/#issuance-date) property, if present, is not after a specific datetime. Defaults to the current datetime if unset. +- **Verifier Options**: See [Proof Verifier Options](#proof-verifier-options) for details. + +## Example Code + +The following code demonstrates how to use the IOTA Identity Framework end-to-end to create and sign a verifiable +presentation as a holder, serialize it to JSON for transmission, deserialize it on the receiving side as a verifier, +and finally validate it with various options. + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/6_create_vp.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/6_create_vp.ts +``` + + + diff --git a/docs/build/identity.rs/1.0/docs/introduction.mdx b/docs/build/identity.rs/1.0/docs/introduction.mdx deleted file mode 100644 index 995841b7e36..00000000000 --- a/docs/build/identity.rs/1.0/docs/introduction.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -description: The most important concepts that developers will need to know to utilize IOTA Identity to its full potential. -image: /img/Identity_icon.png -keywords: - - Identity - - guide - - TOC - - overview - - reference ---- - -# IOTA Identity Framework Guide - -![IOTA Identity](/img/banner/banner_identity.svg) - -The IOTA Identity framework implements the most common standards and patterns for Decentralized Identity in both a DLT agnostic and `iota` method specification manner. It is designed to work for Identity for People, Organizations, Things, and Objects acting as a unifying-layer of trust between everyone and everything. - -In this guide, we will go through the most important concepts that developers will need to know to utilize IOTA Identity to its full potential. - -## Overview - -### [Chapter 1: Decentralized Identity](./decentralized_identity.mdx) - -Describes the concept of Decentralized or Self-Sovereign Identities (SSI), how it applies to People, Organizations and Things, and why IOTA is used. - -### [Chapter 2: Getting Started](./getting_started/overview.mdx) - -Gives a quick overview of how to install the library and creating your first DID. - -### Chapter 3: Concepts - -Describes relevant concepts of SSI and how to utilize them in the library. - -### [Chapter 3.1: Decentralized Identifiers (DID)](./concepts/decentralized_identifiers/overview.mdx) - -Explains the DID standard from W3C and how to manipulate DID Documents. - -### [Chapter 3.2: Verifiable Credentials (VC)](./concepts/verifiable_credentials/overview.mdx) - -Explains the VC standard from W3C, how to create and revoke VCs, and how to use Verifiable Presentations. - -### [Chapter 4: Programming Languages](./libraries/overview.mdx) - -While the framework itself is developed in the Rust programming language, we also provide bindings, or "Foreign Function Interfaces" (FFI), to other languages. These will have separate getting started sections, making the rest of the guide language agnostic, focusing on the conceptual level. - -### [Chapter 5: Specification](./specs/overview.mdx) - -While IOTA Identity implements many existing standards, it also adds some additional features we would like to standardize ourselves. This chapter covers these features and how they work in great detail. These are not light reads and can be skipped. - -### [Chapter 6: Glossary](./glossary.mdx) - -A list of all terminology used in this guide, the framework, and all materials surrounding it. - -### [Chapter 7: Contribute](./contribute.mdx) - -A simple guide on how to contribute to the framework. - -### [Chapter 8: Workflow](./workflow.mdx) - -An overview of the workflow to design, develop and release the framework. - -### [Chapter 9: Contact](./contact.mdx) - -How to contact the maintainers. - -### [Chapter 10: FAQ](./faq.mdx) - -Overview of the most Frequently Asked Questions and their answers. diff --git a/docs/build/identity.rs/1.0/docs/libraries/overview.mdx b/docs/build/identity.rs/1.0/docs/libraries/overview.mdx deleted file mode 100644 index 0a9bb2ff187..00000000000 --- a/docs/build/identity.rs/1.0/docs/libraries/overview.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Libraries Overview -sidebar_label: Overview -description: Provide overview of the libraries -image: /img/Identity_icon.png -keywords: - - libraries ---- - -While the framework itself is developed in the Rust programming language, we also provide bindings, or "Foreign Function Interfaces" (FFI), to other languages. - -For the Rust implementation see the [Rust Getting Started](./rust/getting_started.mdx). - -For the Wasm bindings see the [Wasm Getting Started](./wasm/getting_started.mdx). diff --git a/docs/build/identity.rs/1.0/docs/libraries/wasm/api_reference.mdx b/docs/build/identity.rs/1.0/docs/references/api/wasm.mdx similarity index 99% rename from docs/build/identity.rs/1.0/docs/libraries/wasm/api_reference.mdx rename to docs/build/identity.rs/1.0/docs/references/api/wasm.mdx index 49759b579e5..c3f1323dcf0 100644 --- a/docs/build/identity.rs/1.0/docs/libraries/wasm/api_reference.mdx +++ b/docs/build/identity.rs/1.0/docs/references/api/wasm.mdx @@ -1,12 +1,12 @@ --- title: WASM API Reference -sidebar_label: API Reference description: WASM API reference. image: /img/Identity_icon.png keywords: - WASM - API Reference --- +# Wasm Api Reference ## Classes diff --git a/docs/build/identity.rs/1.0/docs/specs/did/iota_did_method_spec.mdx b/docs/build/identity.rs/1.0/docs/references/specifications/iota-did-method-spec.mdx similarity index 94% rename from docs/build/identity.rs/1.0/docs/specs/did/iota_did_method_spec.mdx rename to docs/build/identity.rs/1.0/docs/references/specifications/iota-did-method-spec.mdx index 6ebd73e529f..b6978034c5e 100644 --- a/docs/build/identity.rs/1.0/docs/specs/did/iota_did_method_spec.mdx +++ b/docs/build/identity.rs/1.0/docs/references/specifications/iota-did-method-spec.mdx @@ -28,7 +28,7 @@ Data types and subschemas used throughout this TIP are defined in [TIP-21](https ### UTXO Ledger -The unspent transaction output ([UTXO](/introduction/reference/details#unspent-transaction-output-utxo)) model defines a ledger state which is comprised of unspent outputs. Outputs are created by a transaction consuming outputs of previous transactions as inputs. The Stardust version of the protocol defines several output types, the relevant ones for the IOTA DID Method are: Basic Outputs for _value transactions_, and Alias Outputs for storage of DID Documents. +The unspent transaction output ([UTXO](/tips/tips/TIP-0020/)) model defines a ledger state which is comprised of unspent outputs. Outputs are created by a transaction consuming outputs of previous transactions as inputs. The Stardust version of the protocol defines several output types, the relevant ones for the IOTA DID Method are: Basic Outputs for _value transactions_, and Alias Outputs for storage of DID Documents. All outputs must hold a minimum amount of tokens to be stored on the ledger. For output types that can hold arbitrary data, for instance the Alias Output, the amount of tokens held by the output must cover the byte cost of the data stored. This prevents the ledger size from growing uncontrollably while guaranteeing that the data is not pruned from the nodes, which is important for resolving DID Documents. This deposit is fully refundable and can be reclaimed when the output is destroyed. @@ -232,7 +232,7 @@ The `did:iota` method is implemented in the [IOTA Identity framework](https://gi ### Revocation -Revocation of Verifiable Credentials and signatures can be achieved using the [Revocation Bitmap 2022](../revocation_bitmap_2022.mdx) where issuers store a bitmap of indices in the DID Document. These indices correspond to verifiable credentials they have issued. If the binary value of the index in the bitmap is 1 (one), the verifiable credential is revoked, if it is 0 (zero) it is not revoked. +Revocation of verifiable credentials and signatures can be achieved using the [Revocation Bitmap 2022](./revocation-bitmap-2022.mdx) where issuers store a bitmap of indices in the DID Document. These indices correspond to verifiable credentials they have issued. If the binary value of the index in the bitmap is 1 (one), the verifiable credential is revoked, if it is 0 (zero) it is not revoked. ### Standardized Services @@ -240,7 +240,7 @@ The IOTA Identity framework also standardized certain `services` that are embedd Currently standardized `services`: -- [Revocation Bitmap Service](../revocation_bitmap_2022.mdx#revocation-bitmap-service) +- [Revocation Bitmap Service](./revocation-bitmap-2022.mdx#revocation-bitmap-service) ## Security Considerations @@ -256,7 +256,7 @@ All private keys or seeds used for the `did:iota` method should be equally well The public IOTA and Shimmer networks are immutable. This means that once something is included, it can never be completely removed. For example, destroying an Alias Output will remove it from the ledger state, but it can still be stored in permanodes or by any party that records historical ledger states. -That directly conflicts with certain privacy laws such as GDPR, which have a 'right-to-be-forgotten' for Personal Identifiable Information (PII). As such, users should NEVER upload any PII, including inside DID Documents. While Verifiable Credentials can be made public, this should only be utilized by Identity for Organisations and Identity for Things. +That directly conflicts with certain privacy laws such as GDPR, which have a 'right-to-be-forgotten' for Personal Identifiable Information (PII). As such, users should NEVER upload any PII, including inside DID Documents. While verifiable credentials can be made public, this should only be utilized by Identity for Organisations and Identity for Things. ### Correlation Risks diff --git a/docs/build/identity.rs/1.0/docs/specs/overview.mdx b/docs/build/identity.rs/1.0/docs/references/specifications/overview.mdx similarity index 56% rename from docs/build/identity.rs/1.0/docs/specs/overview.mdx rename to docs/build/identity.rs/1.0/docs/references/specifications/overview.mdx index 2129d120b2d..8ffb0951bd7 100644 --- a/docs/build/identity.rs/1.0/docs/specs/overview.mdx +++ b/docs/build/identity.rs/1.0/docs/references/specifications/overview.mdx @@ -7,9 +7,9 @@ keywords: - specifications --- -While IOTA Identity implements many existing standards, it also adds some additional features we would like to standardize ourselves. This chapter covers these features and how they work in great detail. These are not light reads and can be skipped. +While IOTA Identity implements many existing standards, it also adds some additional features we would like to standardize ourselves. This section covers these features and how they work in great detail. These are not light reads and can be skipped. The current specifications are: -- [IOTA DID](./did/overview.mdx): The specification for the IOTA DID Method implemented on the _Tangle_. -- [Revocation Bitmap 2022](./revocation_bitmap_2022.mdx): The specification for an on-Tangle credential revocation mechanism. +- [IOTA DID](iota-did-method-spec.mdx): The specification for the IOTA DID Method implemented on the _Tangle_. +- [Revocation Bitmap 2022](revocation-bitmap-2022.mdx): The specification for an on-Tangle credential revocation mechanism. diff --git a/docs/build/identity.rs/1.0/docs/specs/revocation_bitmap_2022.mdx b/docs/build/identity.rs/1.0/docs/references/specifications/revocation-bitmap-2022.mdx similarity index 99% rename from docs/build/identity.rs/1.0/docs/specs/revocation_bitmap_2022.mdx rename to docs/build/identity.rs/1.0/docs/references/specifications/revocation-bitmap-2022.mdx index 3cd124cc34d..e44aa2c11b0 100644 --- a/docs/build/identity.rs/1.0/docs/specs/revocation_bitmap_2022.mdx +++ b/docs/build/identity.rs/1.0/docs/references/specifications/revocation-bitmap-2022.mdx @@ -15,7 +15,7 @@ keywords: ## Abstract -This specification describes a mechanism for publishing the revocation status of [Verifiable Credentials](../concepts/verifiable_credentials/overview.mdx) embedded in an issuer's DID document. +This specification describes a mechanism for publishing the revocation status of [verifiable credentials](../../explanations/verifiable-credentials.mdx) embedded in an issuer's DID document. ## Introduction diff --git a/docs/build/identity.rs/1.0/docs/specs/did/overview.mdx b/docs/build/identity.rs/1.0/docs/specs/did/overview.mdx deleted file mode 100644 index 91277d73bf7..00000000000 --- a/docs/build/identity.rs/1.0/docs/specs/did/overview.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Overview -sidebar_label: Overview -description: IOTA Identity specifications overview. -image: /img/Identity_icon.png -keywords: - - specs - - specifications ---- - -TODO diff --git a/docs/build/identity.rs/1.0/docs/welcome.mdx b/docs/build/identity.rs/1.0/docs/welcome.mdx new file mode 100644 index 00000000000..c34a7f161ce --- /dev/null +++ b/docs/build/identity.rs/1.0/docs/welcome.mdx @@ -0,0 +1,91 @@ +--- +description: The most important concepts that developers will need to know to utilize IOTA Identity to its full potential. +image: /img/Identity_icon.png +keywords: + - Identity + - guide + - TOC + - overview + - reference +--- +# IOTA Identity Framework + +![IOTA Identity](/img/banner/banner_identity.svg) + +The IOTA Identity framework implements the most common standards and patterns for Decentralized Identity in both a DLT agnostic and `iota` method specific manner. +It is designed to work for Identity for [People](#identity-for-people), [Organizations](#identity-for-organizations), +[Things, and Objects](#identity-for-things) acting as a unifying-layer of trust between everyone and everything. + +## Introduction to Decentralized Identity + +Decentralized or Self-Sovereign Identity (SSI) gives individuals full control over their online identity, +offering a remedy for database breaches, lack of digital trust, and stringent privacy laws like GDPR. +Digital identity bridges the gap between online pseudonyms and real-world personas, enabling true verifiable identities. This gives individuals the power to choose which data to share and with whom. + + + +### Identity for People + +:::info Privacy + +IOTA Identity builds a new internet, without usernames, passwords, endless repeated forums, or uncontrolled data harvesting. + +::: + +Information about anyone's life is spread across many locations. Most people have numerous unorganized important documents at home, hundreds of online accounts, and many more online footprints. Through statistical predictive analysis, computer programs can harvest unverified online information sources and create a reasonably accurate profile about our lives. These profiles are accurate enough for targeted advertising and personalized content but lack the proof and trust for them to be used in business. This results in an antiquated customer experience where we have to submit our age and address for every purchase we make and every account we create. It also inhibits our ability to do many online tasks like requesting and extending licenses or taking out a mortgage. + +Self-Sovereign Identity is about returning autonomy and privacy to the individual, while also improving our online experience. Some movements focus on data privacy, preventing companies from using our information altogether, but with the IOTA Identity framework you control which part of the information you want to reveal. The user can create a single online profile containing all our personal information. They can decide who they share what information with, and a verifier checks if the information is correct, making the data trustworthy. This moves their online profile from a statistical estimation by corporate entities to an accurate and verifiable profile under their own control. + +IOTA Identity allows a new internet without usernames, passwords, endless repeated forms, or data harvesting. Users have ultimate control and can choose to supply service providers with their personal data, who in return provide personalized experiences. Data will still flow, and perhaps even more than before, but it will always be in the interest of the individual, instead of a corporation. People will gain additional benefits in sharing their data, either in monetary value or improved customer experience. This sort of system is not possible in a non-neutral environment such as permissioned or fee-based ledgers. + +Governmental mechanisms for building _digital identities_ are currently being established throughout Europe and Asia, with demand increasing around the globe. However, they are managed by single entities and restricted to the governments that created them. By decentralizing a framework for these standards to adapt to, we have a system for intergovernmental verification of individuals and devices. A person’s digital identification will be transferable across borders like a passport. However, it will no longer require the trust of the issuing government due to the digital trust established by the open and auditable system. + +### Identity for Organizations + +:::info GDPR + +IOTA Identity allows organizations to comply with GDPR in a cost-efficient and privacy-enabling manner + +::: + +Corporations are associated with greed and abuse of power. This reputation stems from the role some have chosen to take within society. Corporations are trusted with our data, but often do not act responsibly; vulnerability, fix, patch, repeat. In software and systems, we have seen this cycle repeat. Headlines on data leaks are now an ever-present feature in the news. + +IOTA Identity presents an opportunity for companies to embrace a new role in the ecosystem. Traditional approaches do not provide cost-efficient solutions to new legislation like GDPR. IOTA Identity enables organizations to change their processes to comply with the new regulations in a cost-efficient and privacy-enabling manner. Features of “Data Protection and Privacy by Design” shift responsibility over Personal Identifiable Information (PII) from organization to customer, and organizations no longer need to store that data. The relationship between customer and organization is also tightened as communication via a third party Identity provider like Google or Facebook is no longer needed. + +Due to Know-Your-Customer (KYC) and Anti-Money Laundering (AML) obligations, companies can be certain who their customers are. These services also provide unique insight into the state of their customers’ data. These insights can be combined and translated into verifiable credentials, providing a new “Trust Anchor” service with a potential for new business models. KYC and AML credentials would return the autonomy of personal data back to the customer. Once companies accept the KYC and AML credentials of other companies, the enrollment time for new customers is significantly reduced, as are the costs. With the personal data secured by the customer, companies can afford to store less data in their own databases, reducing risk and responsibility and fulfilling the goals of legislation such as GDPR. + +Organizations that have their own decentralized identities can also combat fraud and increase control over their online brand. Companies can sign invoices and agreements using their decentralized identities. While interacting with the customers, they will also be able to reliably identify themselves. + +### Identity for Things + +:::info TRUST + +IOTA Identity adds the missing key ingredient for the "Economy of Things": Trust. + +::: + +With Identity of Things (IDoT), devices are provided with a unique global identity that are able to prove many attributes including their capabilities, specifications, and authenticity. People, organizations, and other devices will only pay devices that can prove their ability to fulfill the required task. This basis of trust prevents fraudulent activity. Additonally, by using the IOTA ledger, the progress of the task can be immutably logged. With the combination of the IOTA protocol and the IOTA Identity framework, we can automate the entire interaction between all parties, without requiring predefined trust. The [Industry Marketplace](https://industry.iota.org/) provides a perfect example of how this framework and level of autonomy work. + +There is a growth in applications that generate Digital Twins for physical devices or objects, such as the Asset Administration Shell (AAS) developed for our Industry Marketplace. Digital twins are online profiles representing a device or object. They provide a virtual state that mirrors reality by emulating the device or object’s physical state through data input sources like sensors. A digital twin is often used to monitor states and execute actions based on the information. Digital twins are only rarely shared outside the associated application and organization due to the complexities in sharing and matching profiles. However, empowered with a digital identity, digital twin sharing would become possible. Once data is verifiable and trusted, digital twins can form the basis for the digital representation of physical devices and objects. This allows other identities to interact with them automatically and provide services such as predictive maintenance. + +Security is a major barrier in advancing technologies that use IoT. Whether it is the smart devices in our own homes, or at a larger scale, the critical infrastructure of organizations and cities, security must be at the core. It is central to any globally-unifying identity solution. By integrating advanced research in cryptography and digital ledgers, and combining it with a scalable access and management system, security will become a core functionality of the systems we build. By using scalable device DIDs, integrating verification and reputation schemes, and allowing for transparent tamper-proof accountability, we begin to understand how we can future-proof the security of our systems, allowing us to start trusting the process, and not the patch. + +### One Framework. Any Identity + +The IOTA Identity framework serves as a ubiquitous layer of trust for the internet. Whether it's people, organizations, or things, the framework enables the creation of digital identities, fosters trust-building through verifiable credentials, and ensures seamless interaction among different entities. + +### Why IOTA? + +IOTA stands apart as a scalable, feeless Distributed Ledger Technology (DLT), suitable for a universal identity solution. Some features of IOTA include: + +* **Cost-effectiveness**: Usually, minting decentralized identities costs fees. IOTA Identity has redeemable and predictable deposits but no fees. +* **High availability**: Identities are always available on all network nodes - for holders, issuers, and verifiers. +* **Security**: Write access to identities is secured through multi-level control structures with key rotation capabilities, allowing for backup access and recoverability. +* **Integrity**: Updates go through the same mechanisms that secure the IOTA network, guaranteeing consistent state and history of all identities. diff --git a/docs/build/identity.rs/1.0/sidebars.js b/docs/build/identity.rs/1.0/sidebars.js index 54574303ea9..242088be3b6 100644 --- a/docs/build/identity.rs/1.0/sidebars.js +++ b/docs/build/identity.rs/1.0/sidebars.js @@ -18,85 +18,90 @@ module.exports = { docs: [ { type: 'doc', - id: 'introduction', - label: 'Introduction', - }, - { - type: 'doc', - id: 'decentralized_identity', - label: 'Decentralized Identity', + id: 'welcome', + label: 'Welcome', }, { type: 'category', label: 'Getting Started', collapsed: false, - items: [ - 'getting_started/overview', - 'getting_started/install', - 'getting_started/create_and_publish', - ], + items: ['getting-started/rust', 'getting-started/wasm'], }, { type: 'category', - label: 'Concepts', - collapsed: false, + label: 'Explanations', items: [ - { - 'Decentralized Identifiers (DID)': [ - 'concepts/decentralized_identifiers/overview', - 'concepts/decentralized_identifiers/alias', - 'concepts/decentralized_identifiers/create', - 'concepts/decentralized_identifiers/update', - 'concepts/decentralized_identifiers/resolve', - 'concepts/decentralized_identifiers/delete', - ], - 'Verifiable Credentials': [ - 'concepts/verifiable_credentials/overview', - 'concepts/verifiable_credentials/create', - 'concepts/verifiable_credentials/revocation', - 'concepts/verifiable_credentials/verifiable_presentations', - ], - 'Domain Linkage': ['concepts/domain_linkage/domain_linkage'], - 'Key Storage': ['concepts/key_storage/key_storage'], - }, + 'explanations/decentralized-identifiers', + 'explanations/verifiable-credentials', + 'explanations/verifiable-presentations', + 'explanations/about-alias-outputs', ], }, { type: 'category', - label: 'Programming Languages', - collapsed: true, + label: 'How To', items: [ - 'libraries/overview', { type: 'category', - label: 'Rust', - collapsed: true, - items: ['libraries/rust/getting_started'], + label: 'Decentralized Identifiers (DID)', + items: [ + 'how-tos/decentralized-identifiers/create', + 'how-tos/decentralized-identifiers/update', + 'how-tos/decentralized-identifiers/resolve', + 'how-tos/decentralized-identifiers/delete', + ], }, { type: 'category', - label: 'WASM', - collapsed: true, + label: 'Verifiable Credentials', items: [ - 'libraries/wasm/getting_started', - 'libraries/wasm/api_reference', + 'how-tos/verifiable-credentials/create', + 'how-tos/verifiable-credentials/revocation', ], }, + { + type: 'category', + label: 'Verifiable Presentations', + items: ['how-tos/verifiable-presentations/create-and-validate'], + }, + { + type: 'category', + label: 'Domain Linkage', + items: ['how-tos/domain-linkage/create-and-verify'], + }, + 'how-tos/key-storage', ], }, { type: 'category', - label: 'Specifications', + label: 'References', collapsed: true, items: [ - 'specs/overview', { type: 'category', - label: 'IOTA DID', - collapsed: true, - items: ['specs/did/overview', 'specs/did/iota_did_method_spec'], + label: 'API', + items: [ + { + type: 'doc', + id: 'references/api/wasm', + label: 'Wasm', + }, + { + type: 'link', + label: 'Rust', + href: 'https://docs.rs/identity_iota/latest/identity_iota/index.html', + }, + ], + }, + { + type: 'category', + label: 'Specifications', + items: [ + 'references/specifications/overview', + 'references/specifications/iota-did-method-spec', + 'references/specifications/revocation-bitmap-2022', + ], }, - 'specs/revocation_bitmap_2022', ], }, 'glossary', diff --git a/docs/build/zebra-iota-edge-sdk/tutorials/in-app-tutorial.md b/docs/build/zebra-iota-edge-sdk/tutorials/in-app-tutorial.md index 1f06ab15fe0..12c33a914c8 100644 --- a/docs/build/zebra-iota-edge-sdk/tutorials/in-app-tutorial.md +++ b/docs/build/zebra-iota-edge-sdk/tutorials/in-app-tutorial.md @@ -13,9 +13,9 @@ For each step, a function is defined that you should be able to reuse in your ap ## Before you begin -If you are unfamiliar with W3C Decentralized Identifiers (DID) and Verifiable Credentials (VCs), we recommend reading the overviews of chapters 2, 3.1 and 3.2 of the [IOTA Identity guide](/identity.rs/introduction). +If you are unfamiliar with W3C Decentralized Identifiers (DID) and Verifiable Credentials (VCs), we recommend reading the overviews of chapters 2, 3.1 and 3.2 of the [IOTA Identity guide](/identity.rs/welcome). -The IOTA Identity framework is implemented in Rust. In order to use it in JavaScript, WASM bindings are available from the NPM package `@iota/identity-wasm`. Please refer to [IOTA Identity WASM - Getting Started](/identity.rs/libraries/wasm/getting_started) for set up instructions in both NodeJS and web (browser) contexts. This tutorial assumes a web context, but code comments show where usage is not the same as in NodeJS. +The IOTA Identity framework is implemented in Rust. In order to use it in JavaScript, WASM bindings are available from the NPM package `@iota/identity-wasm`. Please refer to [IOTA Identity WASM - Getting Started](/identity.rs/getting-started/wasm) for set up instructions in both NodeJS and web (browser) contexts. This tutorial assumes a web context, but code comments show where usage is not the same as in NodeJS. To complete the tutorial, you will need the following imports: @@ -207,4 +207,4 @@ run() ## Further Reading -To engross yourself further, please refer to the [IOTA Identity Wiki](/identity.rs/introduction) and the [GitHub repository](https://github.com/iotaledger/identity.rs). +To engross yourself further, please refer to the [IOTA Identity Wiki](/identity.rs/welcome) and the [GitHub repository](https://github.com/iotaledger/identity.rs). diff --git a/src/components/HomeLayout/AppLibrariesSection.tsx b/src/components/HomeLayout/AppLibrariesSection.tsx index 18581f56d23..5030f8457e0 100644 --- a/src/components/HomeLayout/AppLibrariesSection.tsx +++ b/src/components/HomeLayout/AppLibrariesSection.tsx @@ -39,8 +39,8 @@ const LibrariesSection: FC = () => ( @@ -52,7 +52,7 @@ const LibrariesSection: FC = () => ( individuals, organizations, and objects.

Create an identity From 850f787539d27f4a68f9fdf83d91b61fb1a249b3 Mon Sep 17 00:00:00 2001 From: Andrew Cullen <45826600+cyberphysic4l@users.noreply.github.com> Date: Mon, 20 Nov 2023 14:13:12 +0000 Subject: [PATCH 4/9] Dix rmc and DRR pseudocode in icca wiki (#1335) --- .../core-concepts/communication-layer.md | 32 +++++++++---------- 1 file changed, 15 insertions(+), 17 deletions(-) diff --git a/docs/learn/protocols/iota2.0/core-concepts/communication-layer.md b/docs/learn/protocols/iota2.0/core-concepts/communication-layer.md index b2394b0a4d8..487ca917466 100644 --- a/docs/learn/protocols/iota2.0/core-concepts/communication-layer.md +++ b/docs/learn/protocols/iota2.0/core-concepts/communication-layer.md @@ -62,10 +62,10 @@ RMC is computed according to an algorithm based on recent traffic activity, wher Let the number of blocks issued by accounts not in debt at slot $i-$MCA be $n_{i-MCA}$. Hence, if $n_{i-MCA}$ is lower than a given threshold $T_{low}$, then RMC decreases; otherwise, if $n_{i-MCA}$ is larger than a threshold $T_{high}$, then RMC increases. The value RMC at slot $i$ is calculated as: $$ -RMC*i = \begin{cases} -\min(RMC*{i-1} + \alpha; RMC*{max}) &\text{if $n*{i-MCA}>T*{high}$}\\ -\max(RMC*{i-1} - \beta; RMC*{min}) &\text{if $n*{i-MCA}T_{high}$}\\ +\max(RMC_{i-1} - \beta; RMC_{min}) &\text{if $n_{i-MCA} 0 - b = outbox[ID].head - WHILE ID.deficit < b.work_score OR b.timestamp > now() OR (parents(b) not scheduled OR not accepted) - ID.deficit += mana[ID] - IF ID.deficit > maxDeficit - ID.deficit = maxDeficit - ID++ - ID.deficit -= b.work_score - IF ID.deficit < 0 - ID.deficit = 0 - schedule(b) -pause(mu*b.work_score) +FOR ID in round robin over all accounts + ID.deficit += ID.quantum + IF ID.deficit > maxDeficit + ID.deficit = maxDeficit + IF Len(outbox[ID]) > 0 + b = outbox[ID].head + IF ID.deficit >= b.workScore AND (parents(b) scheduled OR accepted) + ID.deficit -= b.workScore + schedule(b) + pause(mu*b.workScore) ``` In order to provide a high-performance system, each validator issues a fixed number of special blocks per slot, called *validation blocks*, which receive special treatment during scheduling and do not burn any Mana. A second scheduling buffer, reserved for validation blocks only, includes a set of queues, one for each validator, in which blocks are scheduled in the order they are received. If a validator issues more validation blocks than its allowance, the validator will not receive rewards for the given epoch, and its Mana balance will be decreased by an amount proportional to its stake. From 173d24b9dbf664437b250f9f9437449302d53847 Mon Sep 17 00:00:00 2001 From: Abdulrahim Al Methiab <31316147+abdulmth@users.noreply.github.com> Date: Mon, 20 Nov 2023 20:36:54 +0100 Subject: [PATCH 5/9] Fix outdated Identity wiki pages for 1.0 (#1338) --- .../docs/explanations/about-alias-outputs.mdx | 4 +- .../decentralized-identifiers/update.mdx | 348 +++++++++++------- 2 files changed, 219 insertions(+), 133 deletions(-) diff --git a/docs/build/identity.rs/1.0/docs/explanations/about-alias-outputs.mdx b/docs/build/identity.rs/1.0/docs/explanations/about-alias-outputs.mdx index 082ade130fa..a18cea25fcb 100644 --- a/docs/build/identity.rs/1.0/docs/explanations/about-alias-outputs.mdx +++ b/docs/build/identity.rs/1.0/docs/explanations/about-alias-outputs.mdx @@ -58,8 +58,8 @@ _Nodes_ expose an API to calculate the required deposit depending on the size of ### Alias ID Each Alias Output has an `Alias ID`. This ID is assigned after a transaction creates a new Alias Output. -The actual DID is derived from this `Alias ID`, hence it is unknown before publishing the transaction. +The actual DID is derived from this `Alias ID`, hence it will be unknown before publishing the transaction. Consequently, the DID inside the `State Metadata` will be replaced by the placeholder `did:0:0` to indicate self. If a transaction has an Alias Output as input, its `Alias ID` can be kept by one of its outputs. -This feature is necessary for updating the DID Documents since the DID itself is derived from the Alias Output. +This feature is necessary for updating the DID Documents since the DID itself is derived from the `Alias ID`. diff --git a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/update.mdx b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/update.mdx index 35c7bed31ae..c888221877b 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/update.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/update.mdx @@ -83,25 +83,49 @@ Before you can update anything, you will need to [create an Identity](./create.m ```rust -// Create a new client to interact with the IOTA ledger. -let client: Client = Client::builder().with_primary_node(NETWORK_ENDPOINT, None)?.finish()?; - -// Create a new secret manager backed by a Stronghold. -let mut secret_manager: SecretManager = SecretManager::Stronghold( -StrongholdSecretManager::builder() - .password("secure_password") - .build(random_stronghold_path())?, -); - -// Create a new DID in an Alias Output for us to modify. -let (_, did): (Address, StardustDID) = create_did(&client, &mut secret_manager).await?; + // Create a new client to interact with the IOTA ledger. + let client: Client = Client::builder() + .with_primary_node(API_ENDPOINT, None)? + .finish() + .await?; + + // Create a new secret manager backed by a Stronghold. + let mut secret_manager: SecretManager = SecretManager::Stronghold( + StrongholdSecretManager::builder() + .password(Password::from("secure_password".to_owned())) + .build(random_stronghold_path())?, + ); + + // Create a new DID in an Alias Output for us to modify. + let storage: MemStorage = MemStorage::new(JwkMemStore::new(), KeyIdMemstore::new()); + let (_, document, fragment_1): (Address, IotaDocument, String) = + create_did(&client, &mut secret_manager, &storage).await?; + let did: IotaDID = document.id().clone(); + ``` ```js -const { didClient, secretManager, did } = await createIdentity(); + const client = new Client({ + primaryNode: API_ENDPOINT, + localPow: true, + }); + const didClient = new IotaIdentityClient(client); + + // Generate a random mnemonic for our wallet. + const secretManager: MnemonicSecretManager = { + mnemonic: Utils.generateMnemonic(), + }; + + // Creates a new wallet and identity (see "0_create_did" example). + const storage: Storage = new Storage(new JwkMemStore(), new KeyIdMemStore()); + let { document, fragment } = await createDid( + client, + secretManager, + storage, + ); ``` @@ -112,19 +136,27 @@ This creates and publishes an Alias Output containing a DID Document with one ve ```json { "doc": { - "id": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483", + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", "verificationMethod": [ { - "id": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483#key-1", - "controller": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "z94fP8Vo6qJtejpycjUcYtiSTbLGuCNYUTrjQX9hT2gSv" + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "crv": "Ed25519", + "x": "475CGLtezvySFMCHhx6hE9S97MIYMLb4B-pbVEHaCtY" + } } ] }, "meta": { - "created": "2022-09-12T21:58:06Z", - "updated": "2022-09-12T21:58:06Z" + "created": "2023-11-16T20:40:03Z", + "updated": "2023-11-16T20:40:03Z", + "governorAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd", + "stateControllerAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd" } } ``` @@ -136,25 +168,29 @@ This creates and publishes an Alias Output containing a DID Document with one ve ```rust // Insert a new Ed25519 verification method in the DID document. - let keypair: KeyPair = KeyPair::new(KeyType::Ed25519)?; - let method: IotaVerificationMethod = - IotaVerificationMethod::new(document.id().clone(), keypair.type_(), keypair.public(), "#key-2")?; - document.insert_method(method, MethodScope::VerificationMethod)?; + let fragment_2: String = document + .generate_method( + &storage, + JwkMemStore::ED25519_KEY_TYPE, + JwsAlgorithm::EdDSA, + None, + MethodScope::VerificationMethod, + ) + .await?; ``` ```js -// Insert a new Ed25519 verification method in the DID document. -let keypair = new KeyPair(KeyType.Ed25519); -let method = new IotaVerificationMethod( - document.id(), - keypair.type(), - keypair.public(), - '#key-2', -); -document.insertMethod(method, MethodScope.VerificationMethod()); + // Insert a new Ed25519 verification method in the DID document. + await document.generateMethod( + storage, + JwkMemStore.ed25519KeyType(), + JwsAlgorithm.EdDSA, + "#key-2", + MethodScope.VerificationMethod(), + ); ``` @@ -165,25 +201,39 @@ This creates a new verification method that includes a newly generated Ed25519 p ```json { "doc": { - "id": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483", + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", "verificationMethod": [ { - "id": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483#key-1", - "controller": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "z94fP8Vo6qJtejpycjUcYtiSTbLGuCNYUTrjQX9hT2gSv" + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "crv": "Ed25519", + "x": "475CGLtezvySFMCHhx6hE9S97MIYMLb4B-pbVEHaCtY" + } }, { - "id": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483#key-2", - "controller": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "zHiCj7kbZdWznNvBhqxXwgoEChYseKrArLFdi5kPKAVRq" + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "crv": "Ed25519", + "x": "h8ndZ4_Urmzf4xN4emqS8r5q4pAQvAh0k2YHq5JLBBo" + } } ] }, "meta": { - "created": "2022-09-12T21:58:06Z", - "updated": "2022-09-12T21:58:06Z" + "created": "2023-11-16T20:40:03Z", + "updated": "2023-11-16T20:40:03Z", + "governorAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd", + "stateControllerAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd" } } ``` @@ -198,10 +248,10 @@ You can attach verification relationships to a verification method by referencin ```rust -// Attach a new method relationship to the existing method. +// Attach a new method relationship to the inserted method. document.attach_method_relationship( - &document.id().to_url().join("#key-1")?, - MethodRelationship::Authentication, + &document.id().to_url().join(format!("#{fragment_2}"))?, + MethodRelationship::Authentication, )?; ``` @@ -209,11 +259,11 @@ document.attach_method_relationship( ```js -// Attach a new method relationship to the existing method. -document.attachMethodRelationship( - did.join('#key-1'), - MethodRelationship.Authentication, -); +// Attach a new method relationship to the inserted method. +document.attach_method_relationship( + &document.id().to_url().join(format!("#{fragment_2}"))?, + MethodRelationship::Authentication, +)?; ``` @@ -225,28 +275,42 @@ Note that `Authentication` references the already included `key-2` verification ```json {12,19} { "doc": { - "id": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483", + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", "verificationMethod": [ { - "id": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483#key-1", - "controller": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "z94fP8Vo6qJtejpycjUcYtiSTbLGuCNYUTrjQX9hT2gSv" + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "crv": "Ed25519", + "x": "475CGLtezvySFMCHhx6hE9S97MIYMLb4B-pbVEHaCtY" + } }, { - "id": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483#key-2", - "controller": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "zHiCj7kbZdWznNvBhqxXwgoEChYseKrArLFdi5kPKAVRq" + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "crv": "Ed25519", + "x": "h8ndZ4_Urmzf4xN4emqS8r5q4pAQvAh0k2YHq5JLBBo" + } } ], "authentication": [ - "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483#key-2" + "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE" ] }, "meta": { - "created": "2022-09-12T21:58:06Z", - "updated": "2022-09-12T21:58:06Z" + "created": "2023-11-16T20:40:03Z", + "updated": "2023-11-16T20:40:03Z", + "governorAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd", + "stateControllerAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd" } } ``` @@ -259,28 +323,28 @@ You can also add custom properties can to a service by setting `properties`: ```rust -// Add a new Service. -let service: StardustService = Service::from_json_value(json!({ + // Add a new Service. + let service: Service = Service::from_json_value(json!({ "id": document.id().to_url().join("#linked-domain")?, "type": "LinkedDomains", "serviceEndpoint": "https://iota.org/" -}))?; -assert!(document.insert_service(service)); -document.metadata.updated = Some(Timestamp::now_utc()); + }))?; + assert!(document.insert_service(service).is_ok()); + document.metadata.updated = Some(Timestamp::now_utc()); ``` ```js -// Add a new Service. -const service: StardustService = new StardustService({ - id: did.join('#linked-domain'), - type: 'LinkedDomains', - serviceEndpoint: 'https://iota.org/', -}); -document.insertService(service); -document.setMetadataUpdated(Timestamp.nowUTC()); + // Add a new Service. + const service: Service = new Service({ + id: did.join("#linked-domain"), + type: "LinkedDomains", + serviceEndpoint: "https://iota.org/", + }); + document.insertService(service); + document.setMetadataUpdated(Timestamp.nowUTC()); ``` @@ -291,35 +355,49 @@ The updated Document with the newly created service looks as follows. ```json {21-27} { "doc": { - "id": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483", + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", "verificationMethod": [ { - "id": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483#key-1", - "controller": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "z94fP8Vo6qJtejpycjUcYtiSTbLGuCNYUTrjQX9hT2gSv" + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "crv": "Ed25519", + "x": "475CGLtezvySFMCHhx6hE9S97MIYMLb4B-pbVEHaCtY" + } }, { - "id": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483#key-2", - "controller": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "zHiCj7kbZdWznNvBhqxXwgoEChYseKrArLFdi5kPKAVRq" + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "crv": "Ed25519", + "x": "h8ndZ4_Urmzf4xN4emqS8r5q4pAQvAh0k2YHq5JLBBo" + } } ], "authentication": [ - "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483#key-2" + "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE" ], "service": [ { - "id": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483#linked-domain", + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#linked-domain", "type": "LinkedDomains", "serviceEndpoint": "https://iota.org/" } ] }, "meta": { - "created": "2022-09-12T21:58:06Z", - "updated": "2022-09-12T21:58:19Z" + "created": "2023-11-16T20:40:03Z", + "updated": "2023-11-16T20:40:08Z", + "governorAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd", + "stateControllerAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd" } } ``` @@ -333,8 +411,8 @@ You can also remove verification methods at any time using the following snippet ```rust // Remove a verification method. -let original_method: DIDUrl = document.resolve_method("key-1", None).unwrap().id().clone(); -document.remove_method(&original_method).unwrap(); +let original_method: DIDUrl = document.resolve_method(fragment_1.as_str(), None).unwrap().id().clone(); +document.purge_method(&storage, &original_method).await.unwrap(); ``` @@ -342,8 +420,8 @@ document.remove_method(&original_method).unwrap(); ```js // Remove a verification method. -let originalMethod = document.resolveMethod("key-1") as IotaVerificationMethod; -document.removeMethod(originalMethod?.id()); +let originalMethod = document.resolveMethod(fragment) as VerificationMethod; +await document.purgeMethod(storage, originalMethod?.id()); ``` @@ -354,29 +432,37 @@ This removes the original verification method with the fragment `key-1`. ```json { "doc": { - "id": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483", + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", "verificationMethod": [ { - "id": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483#key-2", - "controller": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "zHiCj7kbZdWznNvBhqxXwgoEChYseKrArLFdi5kPKAVRq" + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "crv": "Ed25519", + "x": "h8ndZ4_Urmzf4xN4emqS8r5q4pAQvAh0k2YHq5JLBBo" + } } ], "authentication": [ - "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483#key-2" + "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE" ], "service": [ { - "id": "did:iota:rms:0x6fdcc441ab461aaee2ec1837ea5068fe2bc643a9ac0729a055ef5df42a762483#linked-domain", + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#linked-domain", "type": "LinkedDomains", "serviceEndpoint": "https://iota.org/" } ] }, "meta": { - "created": "2022-09-12T21:58:06Z", - "updated": "2022-09-12T21:58:19Z" + "created": "2023-11-16T20:40:03Z", + "updated": "2023-11-16T20:40:08Z", + "governorAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd", + "stateControllerAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd" } } ``` @@ -389,40 +475,40 @@ Publish the updated DID Document inside the Alias Output taking into account the ```rust -// Resolve the latest output and update it with the given document. -let alias_output: AliasOutput = client.update_did_output(document.clone()).await?; - -// Because the size of the DID document increased, we have to increase the allocated storage deposit. -// This increases the deposit amount to the new minimum. -let rent_structure: RentStructure = client.get_rent_structure().await?; -let alias_output: AliasOutput = AliasOutputBuilder::from(&alias_output) - .with_minimum_storage_deposit(rent_structure) - .finish()?; - -// Publish the updated Alias Output. -let updated: StardustDocument = client.publish_did_output(&secret_manager, alias_output).await?; + // Resolve the latest output and update it with the given document. + let alias_output: AliasOutput = client.update_did_output(document.clone()).await?; + + // Because the size of the DID document increased, we have to increase the allocated storage deposit. + // This increases the deposit amount to the new minimum. + let rent_structure: RentStructure = client.get_rent_structure().await?; + let alias_output: AliasOutput = AliasOutputBuilder::from(&alias_output) + .with_minimum_storage_deposit(rent_structure) + .finish()?; + + // Publish the updated Alias Output. + let updated: IotaDocument = client.publish_did_output(&secret_manager, alias_output).await?; ``` ```js -// Resolve the latest output and update it with the given document. -const aliasOutput: IAliasOutput = await didClient.updateDidOutput(document); - -// Because the size of the DID document increased, we have to increase the allocated storage deposit. -// This increases the deposit amount to the new minimum. -const rentStructure: IRent = await didClient.getRentStructure(); -aliasOutput.amount = TransactionHelper.getStorageDeposit( - aliasOutput, - rentStructure, -).toString(); - -// Publish the output. -const updated: StardustDocument = await didClient.publishDidOutput( - secretManager, - aliasOutput, -); + // Resolve the latest output and update it with the given document. + let aliasOutput: AliasOutput = await didClient.updateDidOutput(document); + + // Because the size of the DID document increased, we have to increase the allocated storage deposit. + // This increases the deposit amount to the new minimum. + const rentStructure: IRent = await didClient.getRentStructure(); + + aliasOutput = await client.buildAliasOutput({ + ...aliasOutput, + amount: Utils.computeStorageDeposit(aliasOutput, rentStructure), + aliasId: aliasOutput.getAliasId(), + unlockConditions: aliasOutput.getUnlockConditions(), + }); + + // Publish the output. + const updated: IotaDocument = await didClient.publishDidOutput(secretManager, aliasOutput); ``` From a5311f23e0bd851b7c8debbdaf85995fabbd8556 Mon Sep 17 00:00:00 2001 From: Lucas Tortora <85233773+lucas-tortora@users.noreply.github.com> Date: Mon, 20 Nov 2023 18:26:48 -0300 Subject: [PATCH 6/9] Fix protocol version and remove Chrysalis preview images --- docs/get-started/introduction/iota/introduction.md | 4 ++-- docs/get-started/introduction/iota/iota-token.md | 2 +- docs/get-started/research-papers.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/get-started/introduction/iota/introduction.md b/docs/get-started/introduction/iota/introduction.md index fa58c1e5ad1..7c97431d088 100644 --- a/docs/get-started/introduction/iota/introduction.md +++ b/docs/get-started/introduction/iota/introduction.md @@ -1,6 +1,6 @@ --- description: Explore the key features of IOTA, including the Tangle, feeless transactions, data transfer, and energy efficiency. Learn how IOTA revolutionizes the blockchain industry with its innovative protocols. -image: /img/logo/Chrysalis_logo_dark.png +image: /img/logo/preview.png keywords: - IOTA - Tangle @@ -34,7 +34,7 @@ performant _consensus_ and ledger solution. ## IOTA Mainnet The IOTA mainnet is the production grade network on which the [IOTA token](/get-started/introduction/iota/iota-token) -is available. It currently runs the [Chrysalis protocol version](/learn/protocols/chrysalis/introduction). +is available. It currently runs the [Stardust protocol version](/learn/protocols/stardust/introduction). ## Feeless Transactions diff --git a/docs/get-started/introduction/iota/iota-token.md b/docs/get-started/introduction/iota/iota-token.md index 16232bccde1..e2312c46141 100644 --- a/docs/get-started/introduction/iota/iota-token.md +++ b/docs/get-started/introduction/iota/iota-token.md @@ -1,6 +1,6 @@ --- description: The IOTA token is designed to facilitate value transfer between humans and machines, with fair distribution and a focus on sustainability. It enables feeless transactions and supports a wide range of use cases. -image: /img/logo/Chrysalis_logo_dark.png +image: /img/logo/preview.png keywords: - IOTA token - value transfer diff --git a/docs/get-started/research-papers.md b/docs/get-started/research-papers.md index 7366fca1293..8befc46d78d 100644 --- a/docs/get-started/research-papers.md +++ b/docs/get-started/research-papers.md @@ -1,6 +1,6 @@ --- description: Links to all the Research papers published from IOTA Foundation Researchers. -image: /img/logo/Chrysalis_logo_dark.png +image: /img/logo/preview.png keywords: - keyword1 - keyword2 From 82373536600945d58baa37a7762f5ca7cd48b4bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marc=20Esp=C3=ADn?= Date: Wed, 22 Nov 2023 16:53:50 +0100 Subject: [PATCH 7/9] fix: Wrap up Mana Calculator (#1345) --- .../iota2.0/core-concepts/mana-calculator.md | 41 ++++--- .../ManaCalculator/actions/calculateBPS.ts | 4 +- .../components/BlocksAllowance.tsx | 60 ---------- .../components/DelegatorSettings.tsx | 40 +++++++ .../components/ManaCalculator.tsx | 4 +- .../components/OtherParametersSection.tsx | 9 +- .../ManaCalculator/components/OutputForm.tsx | 112 ++++++++++++++---- .../ManaCalculator/components/RoleSection.tsx | 55 ++------- .../components/ValidatorSettings.tsx | 57 +++------ .../ManaCalculator/components/index.ts | 2 +- src/components/ManaCalculator/constants.ts | 8 +- .../ManaCalculator/enums/parameters.enum.ts | 1 + .../ManaCalculator/hooks/useManaState.ts | 31 ++--- .../ManaCalculator/hooks/useResults.ts | 52 ++++++-- .../hooks/useResultsWithUnit.ts | 2 - src/components/ManaCalculator/utils.ts | 3 +- 16 files changed, 249 insertions(+), 232 deletions(-) delete mode 100644 src/components/ManaCalculator/components/BlocksAllowance.tsx create mode 100644 src/components/ManaCalculator/components/DelegatorSettings.tsx diff --git a/docs/learn/protocols/iota2.0/core-concepts/mana-calculator.md b/docs/learn/protocols/iota2.0/core-concepts/mana-calculator.md index 441d8987aea..c47b57c4940 100644 --- a/docs/learn/protocols/iota2.0/core-concepts/mana-calculator.md +++ b/docs/learn/protocols/iota2.0/core-concepts/mana-calculator.md @@ -6,35 +6,42 @@ Mana is a reward resource generated by holding IOTA tokens. It is utilized for b Here, we introduce the Mana calculator: a tool to help you make decisions about the type of participation that will suit you best, to help you predict the Mana generation you’ll be granted, and to decide the number of IOTA tokens you should hold to guarantee your desired level of access in the future. -## How to use the Calculator: Step-by-step instructions +## How to use the Calculator: Simplified Step-by-step instructions -- **Choose your network:** This calculator works for both Shimmer and the future IOTA 2.0 network. Both networks will have their own type of Mana (IOTA Mana and Shimmer Mana), with their own parameters and, consequently, their own behavior. Be sure you select the correct scenario you want to simulate! +- **Network Configuration:** This calculator works for Shimmer and the future IOTA 2.0 network. Both networks will have their own type of Mana (IOTA Mana and Shimmer Mana), with their own parameters and, consequently, their own behavior. Be sure you select the correct scenario you want to simulate! -- **Choose your role:** Will you delegate to a validator, become a validator yourself, or just hold tokens? To be a validator, you must run a node and lock your tokens while performing validation services, which will give you higher rewards. If you want to delegate to a validator, your tokens will not be locked and you won’t need to run a node, but this will give you fewer rewards than validating. Finally, just holding tokens grants you a certain amount of Mana, which will be less than by validating or delegating. +- **Role Configuration:** Will you delegate to a validator, become a validator yourself, or just hold tokens? To be a validator, you must run a node and lock your tokens while performing validation services, giving you higher rewards. If you want to delegate to a validator, your tokens will not be locked and you won’t need to run a node, but this will give you fewer rewards than validating. Finally, just holding tokens grants you a certain amount of Mana, which will be less than by validating or delegating. Additionally, no matter which network and role you choose, your Mana generation will depend on how many available tokens you have. Pay attention to the units! The input should be done in IOTA or Shimmer (not microIota or Glow). -- **Input the number of tokens you own:** No matter which network and role you choose, your Mana generation will depend on how many available tokens you have. Pay attention to the units! The input should be done in IOTA or Shimmer (not microIota or Glow). +With above inputs, you can already estimate how much Mana you’ll be granted per epoch. But what does it mean in BPS? How many blocks per second does your Mana grant you? The answer depends on the size of your block and the network congestion levels. However, we can use a default block size, which will be enough for most applications, and assume particular congestion levels. This takes us to the last essential configuration step in this calculator: -With the inputs above, you can already estimate how much Mana you’ll be granted per epoch. But what does it mean in BPS? How many blocks per second does your Mana grant you? The answer depends on the size of your block and the network congestion levels. However, we can use a default block size, which will be enough for most applications, and assume certain levels of congestion. This takes us to the last step in this calculator: +- **Choose a congestion level:** Given a particular Mana generation per epoch, this can be translated into a number of blocks issued per second that depend on the congestion level. Choose one of the given congestion levels (low, stable, or extreme) to estimate the time until block issuance, which tells you in which periodicity you’ll be able to issue a block. + +By default, this calculator shows you the acquired Mana and Block Allowance you have granted by participating between epochs 1 and 10. +But you can also play with these values! +Inputting different values for `Initial Epoch` and `Final Epoch` allows you to visualize results for any period desired. +Additionally, you can edit several other default parameters used in this tool in the advanced settings tabs. +In case you want more details, see the description of these parameters [here](/learn/protocols/iota2.0/core-concepts/mana-calculator/#advanced-settings) -- **Choose a congestion level:** Given a certain Mana generation per epoch, this can be translated into a number of blocks issued per second that depends on the congestion level. Choose one of the given congestion levels (low, stable, or extreme) to estimate how many blocks per second your tokens and participation grant you! This metric is also shown in another way: time until block issuance, which tells you in which periodicity you’ll be able to issue a block. ## Advanced settings -The steps outlined above can give you a rough estimate of your Mana generation and granted BPS. However, playing with the advanced settings will give you more precise results. +The steps outlined above can give you a rough estimate of your Mana generation and granted blocks allowance. However, playing with the advanced settings will give you more precise results. -- **Change the state of the system:** The calculator's default settings assume a certain level of participation in the consensus (i.e., locked stake, delegated stake, and performance factor of validators). Those settings can be changed under the “Advanced Settings - State of the System” tab. You can also add or delete validators and change their fixed costs. +- **Change the system’s state:** The calculator’s default settings assume a certain level of participation in the consensus (i.e., locked stake, delegated stake, and the performance factor of validators). Those settings can be changed under the “Advanced Settings - Validators” tab. You can also add or delete validators and change their fixed costs. -- If you choose to delegate: - - **Change the validator you delegate to:** Under the default settings, you'll delegate to Validator 1 (which is pool that, technically speaking, is under the "equilibrium state", see the WP for more details). However, you can change this setting and know your rewards if you participate in other pools, with different share of delegated to locked stake, and different performance factors. +- If you choose to delegate, you can change two default values under the "Delegator Settings" tab in "Role Configuration": + - **Change the validator you delegate to:** Under the default settings, you'll delegate to Validator 1 (which is a pool that, technically speaking, is under the "equilibrium state"; see the Whitepaper for more details). However, you can change this setting and know your rewards if you participate in other pools, with different shares of delegated to locked stakes and different performance factors. + - **Change the number of delegated tokens:** By default, you will delegate all your tokens to the pool selected above. + However, you can also simulate a scenario where you only delegate part of your tokens, with the rest remaining undelegated. + As usual, pay attention to the units! The input should be done in IOTA or Shimmer (not microIota or Glow). - If you choose to validate: - - **Change the amount of stake delegated to you:** The calculator's default settings automatically assign you a certain share of the delegated stake when you start validating. However, you can change this setting to know your rewards should you manage to attract more (or less) delegated stake than the default setting. - - **Change your performance factor:** Your performance factor under the calculator's default settings is 0.95. However, you can change this to simulate larger or smaller shares of online time. - - **Change your fixed costs:** By the default settings of the calculator, your fixed costs are zero. This setting can be changed so you spare part of the pool rowards just for yourself. However, notice that the fixed cost is a public parameter, that you define during registration. This means that the delegator knows how you set this value and might consider it when choosing a validator to delegate. Furthermore, if you set this value too high, you'll be punished and won't get any rewards. - -- **Simulate your Mana accumulation**: the default setting of the calculator assumes a stationary regime and calculates the block creation rate you guarantee depending on your stake and level of participation. However, especially in the early stages of the network, you might want to save your Mana to sell later. This tab simulates how much Mana you'll accumulate in a certain time period. For that (besides the other already defined inputs), you just need to choose an initial and final epoch, and the tool will plot a graph of your accumulation during that period. In the same graph, you can also have an idea of how many blocks can be issued with this accumulated amount of Mana, for the different congestion levels (already defined in the non-advanced settings). - - + - **Change the number of staked tokens:** As in the case of delegators, by default, you will stake all your tokens. + However, you can also simulate a scenario where you only stake part of your tokens, with the rest remaining unstaked. + As usual, pay attention to the units! The input should be done in IOTA or Shimmer (not microIota or Glow). + - **Change your performance factor:** Under the calculator's default settings, your performance factor is 1.0. However, you can change this to simulate smaller shares of online time. + - **Change your fixed costs:** By the calculator's default settings, your fixed costs are zero. This setting can be changed so you can spare part of the pool rewards for yourself. However, notice that the fixed cost is a public parameter you define during registration. This means that the delegator knows how you set this value and might consider it when choosing a validator to delegate. Furthermore, if you select this value too high, you'll be punished and won't get any rewards. + - **Change the amount of stake delegated to you:** The calculator's default settings automatically assign you a particular share of the delegated stake when you start validating, based on a specific "equilibrium state" (see the [Whitepaper](https://files.iota.org/papers/IOTA_2.0_Incentives_And_Tokenomics_Whitepaper.pdf) for more details). However, you can change this setting to know your rewards should you attract more (or less) delegated stakes than in the default setting. diff --git a/src/components/ManaCalculator/actions/calculateBPS.ts b/src/components/ManaCalculator/actions/calculateBPS.ts index adf6427c0ca..869be2b1e4b 100644 --- a/src/components/ManaCalculator/actions/calculateBPS.ts +++ b/src/components/ManaCalculator/actions/calculateBPS.ts @@ -1,5 +1,3 @@ -import { EPOCH_DURATION } from '../constants'; - export function calculateBPS(mana: number, congestion: number): number { - return mana / congestion / EPOCH_DURATION; + return mana / congestion; } diff --git a/src/components/ManaCalculator/components/BlocksAllowance.tsx b/src/components/ManaCalculator/components/BlocksAllowance.tsx deleted file mode 100644 index 3eb412d3566..00000000000 --- a/src/components/ManaCalculator/components/BlocksAllowance.tsx +++ /dev/null @@ -1,60 +0,0 @@ -import React from 'react'; -import { - Area, - AreaChart, - CartesianGrid, - ResponsiveContainer, - Tooltip, - XAxis, - YAxis, -} from 'recharts'; -import { stringifyUnit, Unit } from '../hooks'; -import { EpochReward } from '../types'; -import { chartTooltip } from './ChartTooltip'; - -export function BlocksAllowance({ - results, - unit, -}: { - results: EpochReward[]; - unit: Unit; -}) { - const unitString = stringifyUnit(unit); - return ( - <> -

Blocks Allowance

- - - - - - - - - - - - - - - - - ); -} diff --git a/src/components/ManaCalculator/components/DelegatorSettings.tsx b/src/components/ManaCalculator/components/DelegatorSettings.tsx new file mode 100644 index 00000000000..37c8f0f3f10 --- /dev/null +++ b/src/components/ManaCalculator/components/DelegatorSettings.tsx @@ -0,0 +1,40 @@ +import React from 'react'; +import { Details } from '@docusaurus/theme-common/Details'; +import { useManaState } from '../hooks'; +import { fromMicro, toMicro } from '../utils'; +import Select from 'react-select'; + +export function DelegatorSettings() { + const { state, handleOwnStakeChange, handleValidatorChange } = useManaState(); + + const validatorOptions = state.validators.map((_, i) => { + return { value: i, label: `Validator ${i + 1}` }; + }); + + return ( +
+ + handleOwnStakeChange(toMicro(Number(e.target.value)))} + > +
+ ); +} diff --git a/src/components/ManaCalculator/components/ManaCalculator.tsx b/src/components/ManaCalculator/components/ManaCalculator.tsx index c28102e6dd8..131ae08dfe5 100644 --- a/src/components/ManaCalculator/components/ManaCalculator.tsx +++ b/src/components/ManaCalculator/components/ManaCalculator.tsx @@ -14,14 +14,13 @@ import { RoleSection, OtherParametersSection, ManaAccumulation, - BlocksAllowance, } from './'; export function ManaCalculator() { const [state, setState] = useState(getDefaultParameters(NetworkType.IOTA)); const manaState = useGivenManaState(state, setState); const results = useResultsPerEpoch(manaState.state); - const { data, manaUnit, blocksUnit } = useResultsWithUnit(results); + const { data, manaUnit } = useResultsWithUnit(results); return (

Configuration

@@ -32,7 +31,6 @@ export function ManaCalculator() {

Results

- ); } diff --git a/src/components/ManaCalculator/components/OtherParametersSection.tsx b/src/components/ManaCalculator/components/OtherParametersSection.tsx index 5d60e49610d..197e68d5ddd 100644 --- a/src/components/ManaCalculator/components/OtherParametersSection.tsx +++ b/src/components/ManaCalculator/components/OtherParametersSection.tsx @@ -1,6 +1,7 @@ import React from 'react'; import { useManaState } from '../hooks/useManaState'; import Select from 'react-select'; +import { UserType } from '../enums'; import { CongestionType } from '../enums'; import { AdvancedSettingsValidator } from './AdvancedSettingsValidator'; @@ -45,7 +46,13 @@ export function OtherParametersSection() { value={state.finalEpoch} onChange={(e) => handleFinalEpochChange(Number(e.target.value))} > - + {state.userType === UserType.HOLDER ? ( + <> + ) : ( + <> + + + )} ); } diff --git a/src/components/ManaCalculator/components/OutputForm.tsx b/src/components/ManaCalculator/components/OutputForm.tsx index 4a7a88340d0..711a873930c 100644 --- a/src/components/ManaCalculator/components/OutputForm.tsx +++ b/src/components/ManaCalculator/components/OutputForm.tsx @@ -1,6 +1,7 @@ import React from 'react'; import { useManaState, useResults } from '../hooks'; import { fromMicro, roundMax } from '../utils'; +import { UserType } from '../enums'; import humanizeDuration from 'humanize-duration'; export function OutputForm() { @@ -8,7 +9,7 @@ export function OutputForm() { const results = useResults(state); const passiveRewards = roundMax(fromMicro(results.passiveRewards), 6); const manaGenerated = roundMax(fromMicro(results.generatedRewards), 6); - const totalBPS = roundMax(results.totalBPS, 2); + const blockAllowance = roundMax(results.blockAllowance, 2); const humanizer = humanizeDuration.humanizer({ units: ['y', 'mo', 'w', 'd', 'h', 'm', 's', 'ms'], maxDecimalPoints: 3, @@ -18,27 +19,94 @@ export function OutputForm() { return (
-
- Mana generation (by holding):{' '} - {passiveRewards} -
-
- Mana rewards: {manaGenerated} -
-
- Total BPS granted: {totalBPS} -
-
- Time it takes to accumulate enough mana for a standard transaction... -
-
- ...as a delegator/validator:{' '} - {msToTransaction} -
-
- ...as a holder:{' '} - {passiveMsToTransaction} -
+ {state.userType === UserType.VALIDATOR ? ( + <> +
+ Generation (by just holding) in the input period:{' '} + {passiveRewards} Mana +
+
+ Mana rewards from staking in the input period:{' '} + {manaGenerated} Mana +
+
+ Total Block Allowance granted after the input period:{' '} + + {roundMax(blockAllowance, 3)} standard blocks + +
+
+ Time it takes to accumulate enough mana for a standard block... +
+
+ ...as a holder (owning{' '} + {fromMicro(state.heldTokens)}{' '} + tokens and not staking any of them):{' '} + {passiveMsToTransaction} +
+
+ ...as a validator (owning{' '} + {fromMicro(state.heldTokens)}{' '} + tokens and staking{' '} + + {fromMicro(state.stakedOrDelegatedTokens)} + {' '} + of them): {msToTransaction} +
+ + ) : state.userType === UserType.DELEGATOR ? ( + <> +
+ Generation (by just holding) in the input period:{' '} + {passiveRewards} Mana +
+
+ Mana rewards from delegating in the input period:{' '} + {manaGenerated} Mana +
+
+ Total Block Allowance granted after the input period:{' '} + + {roundMax(blockAllowance, 3)} standard blocks + +
+
+ Time it takes to accumulate enough mana for a standard block... +
+
+ ...as a holder (owning{' '} + {fromMicro(state.heldTokens)}{' '} + tokens and not delegating any of them):{' '} + {passiveMsToTransaction} +
+
+ ...as a delegator (owning{' '} + {fromMicro(state.heldTokens)}{' '} + tokens and delegating{' '} + + {fromMicro(state.stakedOrDelegatedTokens)} + {' '} + of them): {msToTransaction} +
+ + ) : ( + <> +
+ Generation in the input period:{' '} + {passiveRewards} Mana +
+
+ Total Block Allowance granted after the input period:{' '} + + {roundMax(blockAllowance, 3)} standard blocks + +
+
+ Time it takes to accumulate enough mana for a standard block:{' '} + {passiveMsToTransaction} +
+ + )}
); } diff --git a/src/components/ManaCalculator/components/RoleSection.tsx b/src/components/ManaCalculator/components/RoleSection.tsx index 48c4bc26f21..6897fdcb869 100644 --- a/src/components/ManaCalculator/components/RoleSection.tsx +++ b/src/components/ManaCalculator/components/RoleSection.tsx @@ -4,19 +4,10 @@ import Select from 'react-select'; import { UserType } from '../enums'; import { fromMicro, toMicro } from '../utils'; import { ValidatorSettings } from './ValidatorSettings'; +import { DelegatorSettings } from './DelegatorSettings'; export function RoleSection() { - const { - state, - handleOwnStakeChange, - handleUserChange, - handleValidatorChange, - handleOwnHoldChange, - } = useManaState(); - const validatorOptions = state.validators.map((_, i) => { - return { value: i, label: `Validator ${i + 1}` }; - }); - + const { state, handleUserChange, handleOwnHoldChange } = useManaState(); return (

Role configuration

@@ -31,10 +22,11 @@ export function RoleSection() { options={[ { value: UserType.DELEGATOR, label: `Delegator` }, { value: UserType.VALIDATOR, label: `Validator` }, + { value: UserType.HOLDER, label: `Holder` }, ]} />
- +
{state.userType === UserType.VALIDATOR ? ( - <> - - - handleOwnStakeChange(toMicro(Number(e.target.value))) - } - > -
- - + + ) : state.userType === UserType.DELEGATOR ? ( + ) : ( - <> - - - handleOwnStakeChange(toMicro(Number(e.target.value))) - } - > - + <> )}
); diff --git a/src/components/ManaCalculator/components/ValidatorSettings.tsx b/src/components/ManaCalculator/components/ValidatorSettings.tsx index 95be4df6508..bf69089a2da 100644 --- a/src/components/ManaCalculator/components/ValidatorSettings.tsx +++ b/src/components/ManaCalculator/components/ValidatorSettings.tsx @@ -1,35 +1,36 @@ import React from 'react'; import { Details } from '@docusaurus/theme-common/Details'; import { useManaState } from '../hooks'; +import { fromMicro, toMicro, roundMax } from '../utils'; export function ValidatorSettings() { const { - state: { - validator: { - performanceFactor, - fixedCost, - shareOfYourStakeLocked, - attractedNewDelegatedStake, - attractedDelegatedStakeFromOtherPools, - }, - }, + state, handleOwnPFChange, handleOwnFCChange, - handleShareOfYourStakeLockedChange, + handleOwnStakeChange, handleAttractedNewDelegatedStakeChange, - handleAttractedDelegatedStakeFromOtherPoolsChange, } = useManaState(); return (
+ + handleOwnStakeChange(toMicro(Number(e.target.value)))} + > +
handleOwnPFChange(Number(e.target.value))} >
@@ -38,42 +39,22 @@ export function ValidatorSettings() { className='mana_calculator__compact input--vertical-spaced' type='number' step='0.01' - value={fixedCost} + value={state.validator.fixedCost} onChange={(e) => handleOwnFCChange(Number(e.target.value))} > -
- - - handleShareOfYourStakeLockedChange(Number(e.target.value)) - } - > -
handleAttractedNewDelegatedStakeChange(Number(e.target.value)) } > -
- - - handleAttractedDelegatedStakeFromOtherPoolsChange( - Number(e.target.value), - ) - } - >
); } diff --git a/src/components/ManaCalculator/components/index.ts b/src/components/ManaCalculator/components/index.ts index 144baf9e54b..92fa8d84681 100644 --- a/src/components/ManaCalculator/components/index.ts +++ b/src/components/ManaCalculator/components/index.ts @@ -3,8 +3,8 @@ export * from './ManaCalculator'; export * from './OtherParametersSection'; export * from './ValidatorCard'; export * from './ValidatorSettings'; +export * from './DelegatorSettings'; export * from './RoleSection'; export * from './OutputForm'; export * from './NetworkSection'; export * from './ManaAcculation'; -export * from './BlocksAllowance'; diff --git a/src/components/ManaCalculator/constants.ts b/src/components/ManaCalculator/constants.ts index 3eeccf01891..2ccf3c798e7 100644 --- a/src/components/ManaCalculator/constants.ts +++ b/src/components/ManaCalculator/constants.ts @@ -3,7 +3,7 @@ import { CongestionType } from './enums/parameters.enum'; // GENERIC export const INITIAL_EPOCH = 1; -export const FINAL_EPOCH = 1000; +export const FINAL_EPOCH = 10; export const SLOT_DURATION = 10; export const SLOTS_IN_EPOCH = 8192; export const EPOCH_DURATION = SLOTS_IN_EPOCH * SLOT_DURATION; @@ -21,7 +21,7 @@ export const IOTA_SUPPLY = 4600000000000000; export const IOTA_CONGESTION = { [CongestionType.HIGH]: 350000000, [CongestionType.MEDIUM]: 0, // Dynamic - [CongestionType.LOW]: 5000000, + [CongestionType.LOW]: 500000, }; export const IOTA_GENERATION_PER_SLOT = Math.pow(2, -17); @@ -37,9 +37,9 @@ export const IOTA_DELEGATED = 600; // IOTA export const SHIMMER_SUPPLY = 1813620509000000; export const SHIMMER_CONGESTION = { - [CongestionType.HIGH]: 350000000, + [CongestionType.HIGH]: 275000000, [CongestionType.MEDIUM]: 0, // Dynamic - [CongestionType.LOW]: 5000000, + [CongestionType.LOW]: 500000, }; export const SHIMMER_GENERATION_PER_SLOT = Math.pow(2, -16); diff --git a/src/components/ManaCalculator/enums/parameters.enum.ts b/src/components/ManaCalculator/enums/parameters.enum.ts index faff9332bdb..5f5a8e8f4a5 100644 --- a/src/components/ManaCalculator/enums/parameters.enum.ts +++ b/src/components/ManaCalculator/enums/parameters.enum.ts @@ -1,6 +1,7 @@ export enum UserType { DELEGATOR, VALIDATOR, + HOLDER, } export enum NetworkType { diff --git a/src/components/ManaCalculator/hooks/useManaState.ts b/src/components/ManaCalculator/hooks/useManaState.ts index 92f5c47b90c..75cd3d844d0 100644 --- a/src/components/ManaCalculator/hooks/useManaState.ts +++ b/src/components/ManaCalculator/hooks/useManaState.ts @@ -122,13 +122,6 @@ export function useGivenManaState( }); } - function handleShareOfYourStakeLockedChange(value: number) { - setState({ - ...state, - validator: { ...state.validator, shareOfYourStakeLocked: value }, - }); - } - function handleAttractedNewDelegatedStakeChange(value: number) { setState({ ...state, @@ -136,16 +129,6 @@ export function useGivenManaState( }); } - function handleAttractedDelegatedStakeFromOtherPoolsChange(value: number) { - setState({ - ...state, - validator: { - ...state.validator, - attractedDelegatedStakeFromOtherPools: value, - }, - }); - } - function handleInitialEpochChange(value: number) { setState({ ...state, @@ -199,7 +182,6 @@ export function useGivenManaState( handleDelete, handleStakeChange, handleAddValidator, - handleAttractedDelegatedStakeFromOtherPoolsChange, handleAttractedNewDelegatedStakeChange, handleCongestionChange, handleDelegatedStakeChange, @@ -210,7 +192,6 @@ export function useGivenManaState( handleOwnFCChange, handleOwnPFChange, handleUserChange, - handleShareOfYourStakeLockedChange, handleOwnStakeChange, handlePFChange, handleValidatorChange, @@ -235,12 +216,13 @@ export function getDefaultParameters( }; const finalNetworkParams = networkParams[network]; + const validators = getValidators(network); return { ...finalNetworkParams, initialEpoch: INITIAL_EPOCH, finalEpoch: FINAL_EPOCH, - validators: getValidators(network), + validators, userType: UserType.DELEGATOR, congestion: CongestionType.LOW, delegator: { @@ -249,9 +231,12 @@ export function getDefaultParameters( validator: { performanceFactor: 1.0, fixedCost: 0.0, - shareOfYourStakeLocked: 100.0, - attractedNewDelegatedStake: finalNetworkParams.stakedTokens * 1.5, - attractedDelegatedStakeFromOtherPools: 0.1, + shareOfYourStakeLocked: 1.0, + attractedNewDelegatedStake: + (finalNetworkParams.stakedTokens * + validators.reduce((a, b) => a + b.delegatedStake, 0)) / + validators.reduce((a, b) => a + b.lockedStake, 0), + attractedDelegatedStakeFromOtherPools: 0, }, network, } as ManaCalculatorProps; diff --git a/src/components/ManaCalculator/hooks/useResults.ts b/src/components/ManaCalculator/hooks/useResults.ts index 3d883be690e..0750edaa79a 100644 --- a/src/components/ManaCalculator/hooks/useResults.ts +++ b/src/components/ManaCalculator/hooks/useResults.ts @@ -1,8 +1,5 @@ -import { - calculateManaRewards, - calculatePassiveRewards, - calculateBPS, -} from '../actions'; +import { calculateManaRewards, calculatePassiveRewards } from '../actions'; +import { EPOCH_DURATION } from '../constants'; import { UserType } from '../enums'; import { ManaState, ValidatorParameters } from '../types'; @@ -14,8 +11,6 @@ export function useResults(state: ManaState) { state.generationPerSlot, ); - const passiveBPS = calculateBPS(passiveRewards, state.congestionAmount); - const validatorParameters = state.userType === UserType.VALIDATOR ? ({ @@ -41,16 +36,53 @@ export function useResults(state: ManaState) { state.generationPerSlot, ); - const generatedBPS = calculateBPS(generatedRewards, state.congestionAmount); - const totalBPS = generatedBPS + passiveBPS; + const passiveRewardsInTheFirstEpoch = calculatePassiveRewards( + state.heldTokens, + state.initialEpoch, + state.initialEpoch + 1, + state.generationPerSlot, + ); + + const generatedRewardsInTheFirstEpoch = calculateManaRewards( + state.stakedOrDelegatedTokens, + state.delegator.validator, + validatorParameters, + state.validators, + state.initialEpoch, + state.initialEpoch + 1, + state.userType, + state.network, + state.generationPerSlot, + ); + + const yourPassiveBlocksInPeriod = passiveRewards / state.congestionAmount; + const yourAdditionalBlocksInPeriod = + generatedRewards / state.congestionAmount; + + const yourPassiveBlocksInTheFirstEpoch = + passiveRewardsInTheFirstEpoch / state.congestionAmount; + const yourAdditionalBlocksInTheFirstEpoch = + generatedRewardsInTheFirstEpoch / state.congestionAmount; + + const yourTotalBlocksInPeriod = + yourPassiveBlocksInPeriod + yourAdditionalBlocksInPeriod; + + const yourTotalBlocksInTheFirstEpoch = + yourPassiveBlocksInTheFirstEpoch + yourAdditionalBlocksInTheFirstEpoch; + + const blockAllowance = yourTotalBlocksInPeriod; + + const yourBPSasHolder = yourPassiveBlocksInTheFirstEpoch / EPOCH_DURATION; + const totalBPS = yourTotalBlocksInTheFirstEpoch / EPOCH_DURATION; const msToTransaction = (1 / totalBPS) * 1_000; - const passiveMsToTransaction = (1 / passiveBPS) * 1_000; + const passiveMsToTransaction = (1 / yourBPSasHolder) * 1_000; return { generatedRewards, passiveRewards, totalBPS, + blockAllowance, msToTransaction, passiveMsToTransaction, }; diff --git a/src/components/ManaCalculator/hooks/useResultsWithUnit.ts b/src/components/ManaCalculator/hooks/useResultsWithUnit.ts index 3f437dbd262..72fb955136d 100644 --- a/src/components/ManaCalculator/hooks/useResultsWithUnit.ts +++ b/src/components/ManaCalculator/hooks/useResultsWithUnit.ts @@ -49,7 +49,6 @@ const getUnit = (value: number): Unit => { interface UseResultsWithUnit { data: EpochReward[]; manaUnit: Unit; - blocksUnit: Unit; } export function getSizeOfUnit(unit: Unit): number { @@ -79,6 +78,5 @@ export function useResultsWithUnit(results: EpochReward[]): UseResultsWithUnit { return { data, manaUnit, - blocksUnit, }; } diff --git a/src/components/ManaCalculator/utils.ts b/src/components/ManaCalculator/utils.ts index 9a6ca572255..5d1f2f870f8 100644 --- a/src/components/ManaCalculator/utils.ts +++ b/src/components/ManaCalculator/utils.ts @@ -7,6 +7,7 @@ import { SHIMMER_GENERATION_PER_SLOT, SHIMMER_SUPPLY, SHIMMER_THROUGHPUT, + SLOT_DURATION, SLOTS_IN_EPOCH, } from './constants'; import { CongestionType, NetworkType, UserType } from './enums'; @@ -51,7 +52,7 @@ export function getNetworkCongestion( const generation = getNetworkGenerationPerSlot(network); const throughput = getNetworkThroughput(network); - return (supply * generation) / (10 * throughput); + return (supply * generation) / (SLOT_DURATION * throughput); } else { if (network == NetworkType.IOTA) { return IOTA_CONGESTION[congestionType]; From 4e5e13b5bbb69ab5072ca1235494b256e3e3c355 Mon Sep 17 00:00:00 2001 From: Dr-Electron Date: Wed, 22 Nov 2023 16:55:55 +0100 Subject: [PATCH 8/9] Add Mana Calculator to sidebar (#1348) --- docs/learn/sidebars.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/learn/sidebars.ts b/docs/learn/sidebars.ts index e80f585c449..8560b796872 100644 --- a/docs/learn/sidebars.ts +++ b/docs/learn/sidebars.ts @@ -66,6 +66,7 @@ module.exports = { 'protocols/iota2.0/core-concepts/data-flow', 'protocols/iota2.0/core-concepts/data-structures', 'protocols/iota2.0/core-concepts/mana', + 'protocols/iota2.0/core-concepts/mana-calculator', { type: 'category', label: 'Consensus', From 7a48bf04f002f7e5fabfdedab906e285918ef364 Mon Sep 17 00:00:00 2001 From: Dr-Electron Date: Wed, 22 Nov 2023 16:56:16 +0100 Subject: [PATCH 9/9] Fix broken regex in api docs creation --- docs/build/apis/sidebars.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build/apis/sidebars.js b/docs/build/apis/sidebars.js index d0d51854227..9b23147e54b 100644 --- a/docs/build/apis/sidebars.js +++ b/docs/build/apis/sidebars.js @@ -16,7 +16,7 @@ function resolveSidebarPaths(category) { } function generateDirectoryPath(basePath, label) { - const directoryName = label.toLowerCase().replaceAll(/s+/g, '-'); + const directoryName = label.toLowerCase().replaceAll(/\s+/g, '-'); const directoryPath = path.join(__dirname, basePath, directoryName); return directoryPath; }