Skip to content

Commit

Permalink
feat(docs): port glossary over from current Wiki (#3716)
Browse files Browse the repository at this point in the history
  • Loading branch information
Dr-Electron authored Dec 13, 2024
1 parent 3befead commit 6157226
Show file tree
Hide file tree
Showing 15 changed files with 339 additions and 132 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ Move allows for shared assets. Although these shared assets are public in princi

### Certification and Finalization

When you submit a transaction in IOTA, all the validators must agree that it's valid. Once they agree, they create a certificate to confirm its validity, and this certificate must also be shared with all validators. Even if some validators don't follow the rules, the transaction can still be finalized by the majority of validators who do follow the IOTA protocol. This process uses cryptographic methods to ensure that validators who don't follow the rules can't trick the system into accepting false information and that misbehaving validators can't stop the system from processing transactions.
When you submit a transaction in IOTA, all the validators must agree that it's valid. Once they agree, they create a _certificate_ to confirm its validity, and this _certificate_ must also be shared with all validators. Even if some validators don't follow the rules, the transaction can still be finalized by the majority of validators who do follow the IOTA protocol. This process uses cryptographic methods to ensure that validators who don't follow the rules can't trick the system into accepting false information and that misbehaving validators can't stop the system from processing transactions.

### Gas and Transaction Execution

Expand Down
30 changes: 15 additions & 15 deletions docs/content/about-iota/iota-architecture/transaction-lifecycle.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,13 +18,13 @@ import ThemedImage from '@theme/ThemedImage';

2. **Submit to Validators**: The IOTA protocol sends the transaction to every validator. The validators validate the transaction. If valid, the validators sign it and return the signed transaction to the client.

3. **Form a Transaction Certificate**: After collecting responses from a supermajority of validators, the client can form a transaction certificate. Unlike consensus-based blockchains, IOTA validators are not burdened by needing to propagate signatures or aggregate certificates; this is the responsibility of the client or gateway.
3. **Form a Transaction Certificate**: After collecting responses from a supermajority of validators, the client can form a transaction _certificate_. Unlike consensus-based blockchains, IOTA validators are not burdened by needing to propagate signatures or aggregate _certificate_s; this is the responsibility of the client or gateway.

4. **Send the Certificate**: The client sends the assembled certificate back to all validators. The validators check its validity and acknowledge receipt. If the transaction involves only owned objects, IOTA can process and execute it immediately without waiting for consensus (**fast path consensus**). All certificates are forwarded to the IOTA DAG-based consensus protocol.
4. **Send the Certificate**: The client sends the assembled _certificate_ back to all validators. The validators check its validity and acknowledge receipt. If the transaction involves only owned objects, IOTA can process and execute it immediately without waiting for consensus (**fast path consensus**). All _certificate_s are forwarded to the IOTA DAG-based consensus protocol.

5. **Consensus and Execution**: The IOTA DAG-based consensus protocol eventually produces a total order of certificates. Validators check and execute certificates that involve shared objects.
5. **Consensus and Execution**: The IOTA DAG-based consensus protocol eventually produces a total order of _certificate_s. Validators check and execute _certificate_s that involve shared objects.

6. **Effect Certificate**: Clients can gather responses from a supermajority of validators, assemble them into an effect certificate, and use it as proof that the transaction is settled.
6. **Effect Certificate**: Clients can gather responses from a supermajority of validators, assemble them into an effect _certificate_, and use it as proof that the transaction is settled.

7. **Checkpoints and Reconfiguration**: IOTA forms checkpoints for every consensus commit, which are also used to drive the reconfiguration protocol.

Expand All @@ -42,13 +42,13 @@ Your wallet app sends the signed transaction to a full node, which then broadcas

### Transaction Certification

Validators receive the transaction from the full node. They check if it's valid and lock the involved objects to prevent double-spending. After validation, they send their signature back to the full node. When the full node collects enough validator signatures (a quorum), it creates a transaction certificate, which includes the transaction and the validator signatures.
Validators receive the transaction from the full node. They check if it's valid and lock the involved objects to prevent double-spending. After validation, they send their signature back to the full node. When the full node collects enough validator signatures (a quorum), it creates a transaction _certificate_, which includes the transaction and the validator signatures.

### Transaction Finalization

The full node broadcasts this transaction certificate to all validators. Validators verify the certificate, execute the transaction, and unlock the previously locked objects. They then sign the transaction effects (a detailed list of changes) and return these signed effects to the full node. The full node verifies these effects and, once it has enough signatures, forms an effects certificate.
The full node broadcasts this transaction _certificate_ to all validators. Validators verify the _certificate_, execute the transaction, and unlock the previously locked objects. They then sign the transaction effects (a detailed list of changes) and return these signed effects to the full node. The full node verifies these effects and, once it has enough signatures, forms an effects _certificate_.

Your wallet app receives this effects certificate, which you can show to the coffee shop to prove that the transaction is complete and irreversible.
Your wallet app receives this effects _certificate_, which you can show to the coffee shop to prove that the transaction is complete and irreversible.

## Transaction Life Cycle

Expand All @@ -67,13 +67,13 @@ After submission to a full node, the certification process begins. The full node

If these checks pass, the validator locks the input objects to the transaction, preventing double-spending, and proceeds to sign the transaction and returns the signature to the node. The node needs signatures from a majority of validators to certify the transaction.

The full node collects these signatures in parallel to speed up the process. Once it has enough signatures (a quorum), the transaction is certified, forming a **transaction certificate**.
The full node collects these signatures in parallel to speed up the process. Once it has enough signatures (a quorum), the transaction is certified, forming a **transaction _certificate_**.

Even if some validators are dishonest, the principle of "quorum intersection" ensures that as long as most validators are honest, double-spending is prevented. An honest validator will not sign two transactions that try to use the same object at the same time.

### Execution

Certified transactions are then sent to validators for **execution**. Validators verify the certificate signatures to ensure the transaction is valid and not attempting to double-spend.
Certified transactions are then sent to validators for **execution**. Validators verify the _certificate_ signatures to ensure the transaction is valid and not attempting to double-spend.

Depending on whether the transaction uses shared input objects, the validators will either:

Expand All @@ -90,9 +90,9 @@ After the transaction is executed, the validator signs off on the effects of the
* The amount of gas spent.
* The transaction's execution status (either success or an error code).

The full node then gathers these signed effects from a majority of validators, forming an **effects certificate**, which guarantees that the transaction is final.
The full node then gathers these signed effects from a majority of validators, forming an **effects _certificate_**, which guarantees that the transaction is final.

Once you or the full node sees an effects certificate, you can be sure that the transaction will be included in a [checkpoint](#checkpoints), meaning it can't be undone. This certificate can also serve as proof that you sent the NFT to your friend since it can't be faked due to the validator signatures.
Once you or the full node sees an effects _certificate_, you can be sure that the transaction will be included in a [checkpoint](#checkpoints), meaning it can't be undone. This _certificate_ can also serve as proof that you sent the NFT to your friend since it can't be faked due to the validator signatures.

### Checkpoints

Expand All @@ -109,25 +109,25 @@ Transaction finality means that once a transaction is executed, it can't be reve

### Settlement Finality

After executing a transaction, validators send back the signed effects to the network. When a majority of validators have executed the transaction and the [effects certificate](#effects-certificate) exists, the transaction's effects (like transfers or newly created objects) are implemented. This allows the network to process new transactions that depend on these effects.
After executing a transaction, validators send back the signed effects to the network. When a majority of validators have executed the transaction and the [effects _certificate_](#effects-certificate) exists, the transaction's effects (like transfers or newly created objects) are implemented. This allows the network to process new transactions that depend on these effects.

Settlement finality depends on [object ownership](../../developer/iota-101/objects/object-ownership/object-ownership.mdx). For transactions involving only owned objects, this happens quickly, in under half a second. For those involving shared objects, it happens shortly after consensus, which can take a few seconds. At this point, the transaction reaches settlement finality, meaning the network can now process more transactions using the same input objects.

### Checkpoint Processing

The [real-world example](#real-world-example) at the beginning of the article demonstrates a finalized transaction through an effects certificate. However, if a full node goes offline before collecting all signatures, your wallet app will try another full node. If your phone dies during this process, the coffee shop will still see your payment on its terminal connected to a different full node, thanks to checkpoints.
The [real-world example](#real-world-example) at the beginning of the article demonstrates a finalized transaction through an effects _certificate_. However, if a full node goes offline before collecting all signatures, your wallet app will try another full node. If your phone dies during this process, the coffee shop will still see your payment on its terminal connected to a different full node, thanks to checkpoints.

A checkpoint contains a list of transactions and is signed by a majority of validators, making it final. If a full node learns about your transaction through checkpoints, it ensures that the transaction will be finalized.

### Local Execution on a Full Node

Before sending back an effects certificate, a full node might execute the transaction locally if the request asks it to. This is more important for high-frequency applications like gaming but can add unnecessary delay for simple transactions like buying coffee. The `WaitForLocalExecution` parameter requests this local execution, while you can use the `WaitForEffects` parameter for a quicker response.
Before sending back an effects _certificate_, a full node might execute the transaction locally if the request asks it to. This is more important for high-frequency applications like gaming but can add unnecessary delay for simple transactions like buying coffee. The `WaitForLocalExecution` parameter requests this local execution, while you can use the `WaitForEffects` parameter for a quicker response.

Additionally, when any app builds a transaction, the full node is usually in charge of choosing the object that is used to pay for the transaction's gas. Since gas is paid in IOTA, which is a shared object, if the full node is not up-to-date, it could potentially lead to an invalid transaction or even a [client equivocation](../../developer/iota-101/transactions/sponsored-transactions/about-sponsored-transactions.mdx#risk-considerations). You can avoid this unwanted behavior by sending the `WaitForLocalExecution` parameter.

### Epoch Change

Every ~24 hours, the IOTA network undergoes an epoch change, during which staking rewards are calculated and distributed, validator metadata is updated, and other network processes occur. User transactions are paused during this time. If your transaction is submitted at the epoch boundary, it may need resubmission in the new epoch. Transactions that were certified but not yet finalized will be reverted. Any transaction certificate from the previous epoch will become invalid, so the full node will resubmit the invalid transactions.
Every ~24 hours, the IOTA network undergoes an epoch change, during which staking rewards are calculated and distributed, validator metadata is updated, and other network processes occur. User transactions are paused during this time. If your transaction is submitted at the epoch boundary, it may need resubmission in the new epoch. Transactions that were certified but not yet finalized will be reverted. Any transaction _certificate_ from the previous epoch will become invalid, so the full node will resubmit the invalid transactions.

### Verifying Finality

Expand Down
2 changes: 1 addition & 1 deletion docs/content/operator/genesis.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Genesis
---

Genesis is the initial state of the IOTA blockchain. To launch a network, the initial committee of validators collaborate by providing their validator information (public keys, network addresses, and so on) to a shared workspace. After all of the initial validators have contributed their information, IOTA generates the initial, unsigned genesis checkpoint (checkpoint with sequence number 0) and each validator provides their signature. IOTA aggregates these signatures to form a certificate on the genesis checkpoint. IOTA bundles this checkpoint, as well as the initial objects, together into a single genesis.blob file that is used to initialize the state when running the `iota-node` binary for both validators and Full nodes.
Genesis is the initial state of the IOTA blockchain. To launch a network, the initial committee of validators collaborate by providing their validator information (public keys, network addresses, and so on) to a shared workspace. After all of the initial validators have contributed their information, IOTA generates the initial, unsigned genesis checkpoint (checkpoint with sequence number 0) and each validator provides their signature. IOTA aggregates these signatures to form a _certificate_ on the genesis checkpoint. IOTA bundles this checkpoint, as well as the initial objects, together into a single genesis.blob file that is used to initialize the state when running the `iota-node` binary for both validators and Full nodes.

## Genesis blob locations

Expand Down
2 changes: 1 addition & 1 deletion docs/content/operator/iota-full-node/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ IOTA Full nodes:

IOTA Full nodes sync with validators to receive new transactions on the network.

A transaction requires a few round trips to 2f+1 validators to form a transaction certificate (TxCert).
A transaction requires a few round trips to 2f+1 validators to form a transaction _certificate_ (TxCert).

This synchronization process includes:

Expand Down
2 changes: 1 addition & 1 deletion docs/content/operator/observability.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ To generate detailed span start and end logs, define the `IOTA_JSON_SPAN_LOGS` e

You can send this output to a tool or service for indexing, alerts, aggregation, and analysis.

The following example output shows certificate processing in the authority with span logging. Note the `START` and `END` annotations, and notice how `DB_UPDATE_STATE` which is nested is embedded within `PROCESS_CERT`. Also notice `elapsed_milliseconds`, which logs the duration of each span.
The following example output shows _certificate_ processing in the authority with span logging. Note the `START` and `END` annotations, and notice how `DB_UPDATE_STATE` which is nested is embedded within `PROCESS_CERT`. Also notice `elapsed_milliseconds`, which logs the duration of each span.

```bash
{"v":0,"name":"iota","msg":"[PROCESS_CERT - START]","level":20,"hostname":"Evan-MLbook.lan","pid":51425,"time":"2022-03-08T22:48:11.241421Z","target":"iota_core::authority_server","line":67,"file":"iota_core/src/authority_server.rs","tx_digest":"t#d1385064287c2ad67e4019dd118d487a39ca91a40e0fd8e678dbc32e112a1493"}
Expand Down
Loading

0 comments on commit 6157226

Please sign in to comment.