tidying + multistage txs

docs/dev/data-model/box/box_modeling.md

@@ -4,9 +4,9 @@ tags:
 ---
 # Ergo Box Design: A Comprehensive Guide
 
-The UTXO system is the backbone of many blockchain networks, and at its core are boxes. These boxes are not just containers for the value of a currency within a blockchain, but they are also equipped with [registers](registers.md) that are protected by a contract, enhancing their functionality on the Ergo blockchain.
+The UTXO (Unspent Transaction Output) system is the backbone of many blockchain networks, and at its core are boxes. These boxes are not just containers for the value of a currency within a blockchain; they are also equipped with [registers](registers.md) that are protected by a contract, enhancing their functionality on the Ergo blockchain.
 
-Registers are essentially storage units for data and information at specific addresses in the blockchain. To visualize this, think of these boxes as remote controls, piggy banks on steroids, or cups that only allow liquid to be poured in. For instance, consider a cup:
+Registers are essentially storage units for data and information at specific addresses in the blockchain. To visualize this, think of these boxes as advanced storage units or containers. For instance, consider a cup:
 
 **A Cup:**
 
@@ -32,15 +32,15 @@ A blockchain serves as a financial canvas, allowing developers, engineers, and d
 
 The three pillars of box design are:
 
-##### Security
+### Security
 
 The box should be designed to prevent exploitation by unauthorized users.
 
-##### Scalability
+### Scalability
 
 The system should be designed to handle multiple concurrent requests smoothly.
 
-#####  Efficiency
+### Efficiency
 
 A straightforward design makes it easier for engineers to understand and improve the design.
 
@@ -50,15 +50,15 @@ Before diving into the principles mentioned above, it's essential to understand
 
 When modeling a box, consider the following:
 
-##### What is the box's purpose?
+### What is the box's purpose?
 
 For instance, a lending box is designed to simplify the loan process.
 
-##### What data should the box store?
+### What data should the box store?
 
 The box's function determines the data stored in it. A lending box, for example, would store lending-related information in its registers.
 
-##### How will the box perform its function?
+### How will the box perform its function?
 
 This step involves thinking about the overall transaction, not just the box. It requires scripting the guard script (or smart contract) to perform its intended function using the data stored in the registers.
 
@@ -69,7 +69,7 @@ Registers can store data in various formats, which can be single or multiple ent
 **Single data entries include:**
 
 - `Long`
-- `Coll[Byte]` also known as *String*
+- `Coll[Byte]` (also known as *String*)
 - `Bool`
 
 **Multiple data entries include:**
@@ -78,7 +78,7 @@ Registers can store data in various formats, which can be single or multiple ent
 - `Coll[Coll[Byte]]`
 - `Coll[Bool]`
 
-> This guide is based on the [article by Keith Lim](https://keitodot.medium.com/ergo-box-m-f58f444e00d5)
-
-
+## Resources
 
+- This guide is based on the [article by Keith Lim](https://keitodot.medium.com/ergo-box-m-f58f444e00d5)
+- For more technical details on the format of a box, please see [this page](format.md)

docs/dev/data-model/box/registers.md

@@ -8,7 +8,7 @@ tags:
 
 In Ergo's blockchain model, a [box](box.md) is a versatile entity that not only holds the value of cryptocurrency but also contains additional data in the form of registers. This makes it a more functional and flexible version of the Unspent Transaction Output (UTXO) found in Bitcoin and many other cryptocurrencies.
 
-Each box contains at least four essential pieces of information:
+**Each box contains at least four essential pieces of information:**
 
 1. The value in NanoErgs (1 Erg = 1000000000 NanoErgs).
 2. The protection script (similar to Bitcoin's `scriptPubKey`) or "smart contract", which secures the box's expenditure.
@@ -49,7 +49,7 @@ Register R2 contains a collection of tokens stored in the box. Each token is ide
 
 Register R3 holds information about the box’s creation, such as the originating transaction id, the box's output index (i.e., the index used in `OUTPUTS`), and the block height at the creation time of the transaction from which the box originates. Use `Box.creationInfo` to access this register. The creation height is part of Ergo's unique storage rent feature, where boxes can be spent after four years, allowing miners to charge a small fee and recycle ERGs back into the blockchain.
 
-### Optional Registers R4 - R9
+### Registers R4 - R9 (Optional)
 
 These registers can contain any data defined when the box first originates from a transaction. The data could be of any common type found in ErgoScript, along with more complex types built from Pairs and Collections. These registers may also contain complex types such as `Box`, `SigmaProp`, `GroupElement`, and `AVLTree`.
 

docs/dev/protocol/tx/format.md

@@ -45,9 +45,9 @@ Once the transaction is confirmed on the blockchain, the placeholder in $R_3$ is
 An Ergo transaction consists of three parts:
 
 1. **Inputs**: Links to boxes that will be removed from the state during transaction application. Each input consists of:
-   - A box ID.
-   - A proof for the final Sigma proposition of this box-protecting script.
-   - A context extension used during script evaluation.
+    - A box ID.
+    - A proof for the final Sigma proposition of this box-protecting script.
+    - A context extension used during script evaluation.
 
 2. **Data Inputs**: Links to boxes that will not be removed from the state but will be available in the context of regular input scripts. This allows transactions to reference additional data without consuming the box.
 

docs/dev/protocol/tx/min-fee.md

@@ -6,13 +6,13 @@ tags:
 
 # Transaction Fees in Ergo
 
-Each Ergo [transaction](transactions.md) is an atomic state transition operation, which involves the destruction of one or more [boxes](format.md) from the state and the creation of new ones. Unlike Bitcoin's implicit fee system, Ergo's fee structure is explicit and requires a separate output to a specific address for fees.
+Each Ergo [transaction](transactions.md) is an atomic state transition operation, involving the destruction of one or more [boxes](format.md) from the state and the creation of new ones. Unlike Bitcoin's implicit fee system, Ergo's fee structure is explicit, requiring a separate output to a specific address for fees.
 
-Ergo's transaction fee system is designed to be both flexible and explicit. The protocol does not enforce a minimum transaction fee, however transactions without a fee are less likely to be included in a block by miners. As such, it is generally recommended to include a fee to incentivize miners to process your transaction. The larger the fee, the higher the likelihood of your transaction being included in a block and processed quickly.
+Ergo's transaction fee system is designed to be both flexible and explicit. While the protocol does not enforce a minimum transaction fee, transactions without a fee are less likely to be included in a block by miners. Therefore, it is generally recommended to include a fee to incentivize miners to process your transaction. The larger the fee, the higher the likelihood of your transaction being included in a block and processed quickly.
 
 ## Minimum Values
 
-Although the protocol does not enforce a specific transaction fee, it does employs a spam-prevention strategy that requires each box to contain a minimum amount of ERG. This minimum value is determined by a parameter voted on by miners and the size of the box. Every output box in a transaction must adhere to this rule. This strategy helps prevent the creation of dust in Ergo, thereby mitigating potential spam attacks.
+Although the protocol does not enforce a specific transaction fee, it employs a spam-prevention strategy that requires each box to contain a minimum amount of ERG. This minimum value is determined by a parameter voted on by miners and the size of the box. Every output box in a transaction must adhere to this rule. This strategy helps prevent the creation of dust in Ergo, thereby mitigating potential spam attacks.
 
 This fee is calculated based on the serialized size of the boxes being created, with a minimum threshold set at **360 nanoerg per byte** and is adjustable via [miner voting](governance.md). As a guideline, it is suggested to allocate **0.001 ERG (1,000,000 NanoErg) for each box** involved in the transaction.
 

docs/dev/protocol/tx/multi-stage-txs.md

@@ -0,0 +1,51 @@
+# Multi-Stage Transactions
+
+A simple transaction (tx) is the foundation of all transactions, representing a direct exchange between two parties. The advent of Smart Contracts enables the creation of autonomous systems that can handle complex real-world scenarios on the blockchain.
+
+## What Are Multi-Stage Transactions?
+
+Multi-stage transactions involve multiple steps, where each step is a separate transaction that must be successfully executed to complete a larger objective. Unlike simple one-to-one transfers, these transactions require coordination across various stages, often governed by intricate smart contract logic.
+
+For example, multi-stage transactions may be required in scenarios involving complex conditions or timed events, such as escrow services, staged payments, or multi-party agreements. Each stage relies on the execution of a preceding step, making the entire process more secure and robust.
+
+A classic illustration of a multi-stage transaction is the **pin-lock contract**, where multiple layers of validation or condition checks must be met before the final transaction can occur. The complexity of multi-stage transactions can vary, but their key feature is the chaining of multiple transactions to complete a scenario.
+
+## Real-World Lending as a Multi-Stage Transaction
+
+Let’s use a traditional lending process as an example. While in the real world, lending may seem like a single transaction, when mapped onto a blockchain, it can be broken down into a **multi-stage transaction** process:
+
+### Stages of a Lending Process in Blockchain
+
+1. **Loan Request Stage**:
+   - **Real World**: A borrower requests a loan from a lender with agreed terms, such as the loan amount and interest rate.
+   - **Blockchain**: The borrower creates a smart contract (or box) requesting funds. This smart contract includes conditions, such as the repayment terms and the interest rate.
+
+2. **Loan Approval and Funding Stage**:
+   - **Real World**: The lender approves the request and disburses the loan.
+   - **Blockchain**: The lender funds the borrower’s smart contract, which triggers the transfer of funds to the borrower upon satisfying the conditions set in the contract.
+
+3. **Loan Utilization Stage**:
+   - **Real World**: The borrower uses the loan for business purposes.
+   - **Blockchain**: The borrower accesses the funded box, transferring the loaned amount into their own account for use.
+
+4. **Repayment Stage** (This is where the multi-stage aspect becomes evident):
+   - **Real World**: The borrower repays the loan with interest in agreed-upon installments.
+   - **Blockchain**: The borrower initiates a series of transactions, where each monthly repayment is a separate transaction executed on the blockchain. These repayments continue until the full amount (plus interest) has been transferred back to the lender.
+
+5. **Completion Stage**:
+   - **Real World**: The loan agreement concludes when the borrower pays off the debt.
+   - **Blockchain**: The smart contract governing the loan automatically closes once the final repayment transaction is executed, concluding the multi-stage process.
+
+### Why is This a Multi-Stage Transaction?
+
+Each step in the lending process on the blockchain is **linked** to the success of the previous one. The loan cannot be funded until the borrower’s smart contract is created, and repayments cannot occur until the funds are utilized. The entire process involves **multiple transactions** (loan request, funding, repayments, and final closure), making it a perfect example of a multi-stage transaction.
+
+## Translating Real-World Scenarios to Blockchain: A Summary
+
+| Real-World Lending Scenario                                                                                         | Equivalent Blockchain Transaction                                                                                                                       |
+| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1. Borrower requests a loan with specified terms.                                                                   | Borrower creates a smart contract requesting the loan amount, specifying the conditions for release.                                                     |
+| 2. Lender approves and sends the loan.                                                                              | Lender funds the borrower’s smart contract.                                                                                                             |
+| 3. Borrower utilizes the loan.                                                                                      | Borrower accesses the funds.                                                                                                                            |
+| 4. Borrower repays the loan in installments.                                                                        | Borrower makes multiple transactions over time to repay the loan with interest.                                                                          |
+| 5. Loan transaction concludes.                                                                                      | Smart contract closes once all repayments are made, completing the multi-stage transaction.                                                              |