From dd218bb6dc6f5e03e1e3121a420942350ff58c00 Mon Sep 17 00:00:00 2001 From: M Glasgow Date: Wed, 2 Oct 2024 15:54:07 +0100 Subject: [PATCH] tidying + multistage txs --- docs/dev/data-model/box/box_modeling.md | 24 +++--- docs/dev/data-model/box/registers.md | 4 +- docs/dev/protocol/tx/format.md | 6 +- docs/dev/protocol/tx/min-fee.md | 6 +- docs/dev/protocol/tx/multi-stage-txs.md | 51 ++++++++++++ docs/dev/protocol/tx/read-only-inputs.md | 22 ++--- docs/dev/protocol/tx/signing.md | 20 ++--- docs/dev/scs/ergoscript.md | 5 +- docs/dev/scs/multi.md | 17 ++-- docs/off-chain.md | 101 ++++++++++++----------- 10 files changed, 156 insertions(+), 100 deletions(-) create mode 100644 docs/dev/protocol/tx/multi-stage-txs.md diff --git a/docs/dev/data-model/box/box_modeling.md b/docs/dev/data-model/box/box_modeling.md index f48f4dec..af7fe7bd 100644 --- a/docs/dev/data-model/box/box_modeling.md +++ b/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) \ No newline at end of file diff --git a/docs/dev/data-model/box/registers.md b/docs/dev/data-model/box/registers.md index eec669d6..6c28c086 100644 --- a/docs/dev/data-model/box/registers.md +++ b/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`. diff --git a/docs/dev/protocol/tx/format.md b/docs/dev/protocol/tx/format.md index 4b84a128..189e4d8b 100644 --- a/docs/dev/protocol/tx/format.md +++ b/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. diff --git a/docs/dev/protocol/tx/min-fee.md b/docs/dev/protocol/tx/min-fee.md index 32990760..9d1f9bab 100644 --- a/docs/dev/protocol/tx/min-fee.md +++ b/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. diff --git a/docs/dev/protocol/tx/multi-stage-txs.md b/docs/dev/protocol/tx/multi-stage-txs.md new file mode 100644 index 00000000..5b6f8f21 --- /dev/null +++ b/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. | diff --git a/docs/dev/protocol/tx/read-only-inputs.md b/docs/dev/protocol/tx/read-only-inputs.md index 8a0f3d0c..ee02a5c5 100644 --- a/docs/dev/protocol/tx/read-only-inputs.md +++ b/docs/dev/protocol/tx/read-only-inputs.md @@ -5,38 +5,38 @@ tags: # Data Inputs in ErgoScript -Data inputs are a unique and powerful feature in ErgoScript that extend the capabilities of traditional UTXO-based blockchains. This section provides an in-depth overview of data inputs, their benefits, and how they can be used in Ergo transactions. +ErgoScript's data inputs are a novel feature that enhances the traditional UTXO-based blockchain's functionality. This section delves into the concept of data inputs, their advantages, and their application within Ergo transactions. ## Understanding Data Inputs -In traditional UTXO-based blockchains, transactions typically involve spending and consuming inputs, which are then destroyed. However, Ergo introduces **data inputs**—a concept that allows transactions to reference existing UTXOs (unspent transaction outputs) and read their data without consuming them. This innovation addresses several limitations inherent in traditional UTXO models and brings enhanced flexibility and efficiency to the extended UTXO (eUTXO) model used by Ergo. +Traditional UTXO-based blockchains involve the consumption and subsequent destruction of inputs during transactions. Ergo innovates on this model with **data inputs**, which permit transactions to reference and read from existing UTXOs without the need to consume them. This breakthrough overcomes several limitations of the classic UTXO model, adding a layer of flexibility and efficiency to Ergo's extended UTXO (eUTXO) model. ### Key Features of Data Inputs -- **Non-Destructive Access:** Data inputs enable transactions to access the contents of UTXOs without consuming or spending them. This means that the referenced UTXOs remain intact and can be used in future transactions. -- **Concurrent Data Access:** Multiple transactions within the same block can reference and read the data from a single UTXO simultaneously, as none of the transactions actually spend the UTXO. This capability supports parallel processing and reduces bottlenecks in transaction execution. +- **Non-Destructive Access:** Data inputs grant transactions the ability to tap into UTXO contents without the need to spend or consume them, preserving the UTXOs for future transactions. +- **Concurrent Data Access:** Data inputs allow for the simultaneous referencing and reading of a UTXO's data by multiple transactions within a single block, without any of them spending the UTXO. This feature facilitates parallel processing and alleviates transaction execution bottlenecks. ## Benefits of Data Inputs -Incorporating data inputs into ErgoScript provides several significant advantages: +The integration of data inputs into ErgoScript offers several notable benefits: -1. **Reduced Transaction Fees:** Data inputs do not trigger the execution of scripts or the need to create additional outputs, leading to lower transaction fees. This makes them a cost-effective solution for complex transactions. +1. **Reduced Transaction Fees:** Since data inputs do not necessitate script execution or the generation of new outputs, they contribute to lower transaction fees, making them an economical choice for intricate transactions. -2. **Enhanced DeFi Applications:** Data inputs are particularly useful for decentralized finance (DeFi) applications, such as decentralized exchanges (DEXs) or order-book systems. They allow contracts to reference external data (e.g., oracle data or order book states) without consuming the data boxes, ensuring that multiple participants can interact with the same state concurrently. +2. **Enhanced DeFi Applications:** Data inputs prove invaluable for decentralized finance (DeFi) applications, such as decentralized exchanges (DEXs) or order-book systems. They enable contracts to reference external data, like oracle data or order book states, without the need to consume the data boxes, facilitating concurrent interactions with the same state by multiple parties. -3. **Improved Scalability and Efficiency:** By allowing multiple transactions to read from the same data input concurrently, data inputs help improve the scalability and efficiency of the network. This reduces the need for additional outputs and mitigates the risk of transaction conflicts. +3. **Improved Scalability and Efficiency:** Data inputs contribute to network scalability and efficiency by allowing several transactions to concurrently read from the same data input, reducing the necessity for extra outputs and lessening the likelihood of transaction conflicts. ## Working with Data Inputs -Data inputs are unique to Ergo and are not yet present in other eUTXO-based systems. When working with data inputs in ErgoScript, it’s important to understand how they function and how they can be utilized effectively in your smart contracts. +Ergo's data inputs are a distinctive feature not found in other eUTXO-based systems. When employing data inputs in ErgoScript, it's crucial to grasp their operation and how to leverage them effectively in smart contracts. ### Usage in Transactions -Data inputs in ErgoScript are essentially "read-only" boxes that provide necessary information for contract validation without being consumed by the transaction. For example, a DeFi contract might use a data input to check the current price of an asset from an oracle box, ensuring that the transaction adheres to certain conditions without altering the oracle box itself. +In ErgoScript, data inputs are "read-only" boxes that supply vital information for contract validation without being spent in the transaction. For instance, a DeFi contract might utilize a data input to verify an asset's current price from an oracle box, ensuring the transaction complies with specific conditions without modifying the oracle box. ### Example Use Case -Consider a transaction where a box with the ID `d2b9b6536287b242f436436ce5a1e4a117d7b4843a13ce3abe3168bff99924a1` is referenced as both an input and a data input. This scenario demonstrates the flexibility of data inputs, allowing a transaction to read and possibly update a box’s state in a single operation, provided the box existed before the transaction was applied. +Imagine a transaction that references a box with the ID `d2b9b6536287b242f436436ce5a1e4a117d7b4843a13ce3abe3168bff99924a1` as both an input and a data input. This illustrates the versatility of data inputs, enabling a transaction to read and potentially update a box's state in one operation, assuming the box pre-existed the transaction. In ErgoScript, you can refer to other boxes in the transaction using constructs like: diff --git a/docs/dev/protocol/tx/signing.md b/docs/dev/protocol/tx/signing.md index dde253d4..4b026c4c 100644 --- a/docs/dev/protocol/tx/signing.md +++ b/docs/dev/protocol/tx/signing.md @@ -16,19 +16,17 @@ Complex expressions, such as $dlog(x_1) \lor (dlog(x2) /\ dlog(x3))$, where $dlo 1. **Bottom-up:** Each node, whether real or simulated, is marked according to the following rule. DLogNode -- if the secret is known, then it's real, else it's simulated. $\lor$: if at least one child is real, then it's real; else it's simulated. $\land$: if at least one child is simulated, then it's simulated; else it's real. + - Note: All descendants of a simulated node will be simulated later, even if they were initially marked as real. + - The root should end up being real according to this rule -- otherwise, the proof cannot be carried out. -> Note: All descendants of a simulated node will be simulated later, even if they were initially marked as real. +2. **Top-down:** Every child of a simulated node is marked as *simulated*. If two or more children of a real $\lor$ are real, all but one are marked as simulated. +3. **Top-down:** A challenge is computed for every simulated child of every $\lor$ and $\land$, according to the following rules. If $\lor$, then every simulated child gets a fresh random challenge. If $\land$ (which means $\land$ itself is simulated, and all its children are), then every child gets the same challenge as the $\land$. +4. **Bottom-up:** For every simulated leaf, a response and a commitment (i.e., second and first prover message) are simulated according to the Schnorr simulator. For every real leaf, the commitment (i.e., first prover message) is computed according to the Schnorr protocol. For every $\lor$/$\land$ node, the commitment is the union (as a set) of commitments below it. + - The Schnorr challenge is computed as the hash of the commitment of the root (plus other inputs -- probably the tree being proven and the message). +6. **Top-down:** The challenge for every real child of every real $\lor$ and $\land$ is computed as follows. If $\lor$, then the challenge for the one real child of $\lor$ is equal to the XOR of the challenge of $\lor$ and the challenges for all the simulated children of $\lor$. If $\land$, then the challenge for every real child of $\land$ is equal to the challenge of the $\land$. -The root should end up being real according to this rule -- otherwise, the proof cannot be carried out. + - **Note:** Simulated $\land$ and $\lor$ only have simulated descendants, so there is no need to recurse down from them. -1. **Top-down:** Every child of a simulated node is marked as *simulated*. If two or more children of a real $\lor$ are real, all but one are marked as simulated. -2. **Top-down:** A challenge is computed for every simulated child of every $\lor$ and $\land$, according to the following rules. If $\lor$, then every simulated child gets a fresh random challenge. If $\land$ (which means $\land$ itself is simulated, and all its children are), then every child gets the same challenge as the $\land$. -3. **Bottom-up:** For every simulated leaf, a response and a commitment (i.e., second and first prover message) are simulated according to the Schnorr simulator. For every real leaf, the commitment (i.e., first prover message) is computed according to the Schnorr protocol. For every $\lor$/$\land$ node, the commitment is the union (as a set) of commitments below it. -4. The Schnorr challenge is computed as the hash of the commitment of the root (plus other inputs -- probably the tree being proven and the message). -5. **Top-down:** The challenge for every real child of every real $\lor$ and $\land$ is computed as follows. If $\lor$, then the challenge for the one real child of $\lor$ is equal to the XOR of the challenge of $\lor$ and the challenges for all the simulated children of $\lor$. If $\land$, then the challenge for every real child of $\land$ is equal to the challenge of the $\land$. - -> Note: Simulated $\land$ and $\lor$ only have simulated descendants, so there is no need to recurse down from them. - -Finally, to obtain a flat binary string containing $(e, z)$ pairs (challenge and prover's response for a leaf sub-protocol) from the tree, follow these steps: +Finally, to obtain a flat binary string containing $(e, z)$ pairs (challenge and prover's response for a leaf sub-protocol) from the tree, follow these steps: (TODO) \ No newline at end of file diff --git a/docs/dev/scs/ergoscript.md b/docs/dev/scs/ergoscript.md index 1a4d5995..05e3f620 100644 --- a/docs/dev/scs/ergoscript.md +++ b/docs/dev/scs/ergoscript.md @@ -10,7 +10,7 @@ tags: /// admonition | Sigma Protocols type: tip -Ergo's support for [sigma-protocols](sigma.md) (aka generalized Schnorr proofs) are truly unique as building blocks for composable statements. Schnorr protocols and proof-of-Diffie-Hellman-tuples are supported by default, with more options available that the community can add via soft forks. +Ergo's support for [sigma-protocols](sigma.md) (aka generalized Schnorr proofs) are truly unique as building blocks for composable statements. [Schnorr protocols](schnorr.md) and [proof-of-Diffie-Hellman-tuples](diffe.md) are supported by default, with more options available that the community can add via soft forks. /// @@ -18,7 +18,8 @@ ErgoScript is built considering Bitcoin’s security and privacy to make all kin -//// admonition | Background Reading +//// details | Background Reading + {type: info, open: false} /// details | **What are the key aspects of the Ergo contract model that make it different?** {type: info, open: false} diff --git a/docs/dev/scs/multi.md b/docs/dev/scs/multi.md index 587d69fb..9eebe836 100644 --- a/docs/dev/scs/multi.md +++ b/docs/dev/scs/multi.md @@ -1,21 +1,20 @@ # Multi-Stage Protocols -While UTXOs scale better and are less error-prone, Ethereum's accounts allow for persistent storage and shared global context.* Multi-Stage Contracts* refers to a a technique using [*transaction trees*](tx-tree.md) that can emulate persistent storage in UTXO-based systems by linking several UTXOs containing small pieces of code to form a large multi-stage protocol. Adding _on-chain computations_ and making it possible to process parallelised actions on top of smart contracts. +Unspent Transaction Outputs (UTXOs) are known for their scalability and reduced error rates. However, Ethereum's account model provides the advantages of persistent storage and a shared global context. *Multi-Stage Contracts* utilize a technique involving [*transaction trees*](tx-tree.md) to mimic persistent storage in UTXO-based systems. This is achieved by interlinking multiple UTXOs, each containing snippets of code, to create an extensive multi-stage protocol. This approach introduces _on-chain computations_ and enables the **execution of parallel actions within smart contracts**. -This enables functionality similar to Ethereum's accounts without the overhead of accounts. - -For more information see the *Multi-Stage Contracts in the UTXO Model* [(Paper)](https://storage.googleapis.com/ergo-cms-media/docs/paper_26.pdf) & [(Video Presentation)](https://www.youtube.com/watch?v=g3FlM_WOwBU) +This method offers a functionality akin to Ethereum's accounts but without the associated overhead. +For additional insights, refer to the *Multi-Stage Contracts in the UTXO Model* [(Paper)](https://storage.googleapis.com/ergo-cms-media/docs/paper_26.pdf) and [(Video Presentation)](https://www.youtube.com/watch?v=g3FlM_WOwBU). ## Examples -We demonstrate this via several examples which include contracts for a [A Rock Paper Scissors game with provable fairness](rock-paper-scissor.md), [Reversible Address with anti-theft features](reversible-address.md) and an [A full-featured ICO](ico.md). +The concept is illustrated through various examples, including contracts for [A Rock Paper Scissors game with provable fairness](rock-paper-scissor.md), [Reversible Address with anti-theft features](reversible-address.md), and [A comprehensive ICO](ico.md). - ## Tutorials & Guides -- [Secure User Entry/Bootstrap Funneling In Multi Stage Protocols](https://www.ergoforum.org/t/secure-user-entry-bootstrap-funneling-in-multi-stage-protocols/228) -- [Multi-Stage Protocol Off-Chain & On-Chain Development Workflow](https://www.ergoforum.org/t/multi-stage-protocol-off-chain-on-chain-development-workflow/269) -- [Secure User Entry/Bootstrap Funneling In Multi Stage Protocols](https://www.ergoforum.org/t/secure-user-entry-bootstrap-funneling-in-multi-stage-protocols/228) +Explore the following resources for a deeper understanding of Multi-Stage Protocols: +- [Ensuring Secure User Entry and Bootstrap Funneling in Multi-Stage Protocols](https://www.ergoforum.org/t/secure-user-entry-bootstrap-funneling-in-multi-stage-protocols/228) +- [Workflow for Multi-Stage Protocol Development: Off-Chain and On-Chain](https://www.ergoforum.org/t/multi-stage-protocol-off-chain-on-chain-development-workflow/269) +(Note: The third link is a duplicate and has been omitted to improve the page's clarity and usefulness.) diff --git a/docs/off-chain.md b/docs/off-chain.md index 6cbd69e4..fcf83cd9 100644 --- a/docs/off-chain.md +++ b/docs/off-chain.md @@ -1,106 +1,113 @@ --- tags: - Off-Chain Bots - - Off Chain Bots - - Grid Bots - - Dex Bots - - Bots + - Off-Chain Components + - Automation Bots + - Decentralized Finance + - Ergo Ecosystem --- -# Off-Chain Bots +# Off-Chain Components in DeFi -[ErgoDex off-chain services](dex_bots.md) +Within the dynamic realm of Ergo's decentralized finance (DeFi), off-chain components are essential for augmenting the capabilities of on-chain processes. This guide explores the implementation of off-chain elements like watchers, oracles, and bots, which are pivotal for reinforcing the robustness of the ecosystem and opening up opportunities for passive income generation. +## On-chain vs. Off-chain -The Ergo ecosystem, known for its innovative approach to decentralized finance (DeFi), offers numerous opportunities for users to earn rewards not only through on-chain activities but also through off-chain mechanisms. This guide explores how participants can leverage off-chain earnings through roles such as watchers, oracles, and bots, contributing to the ecosystem's health while securing passive income. +On-chain elements pertain to the aspects of a decentralized application (dApp) that are directly integrated into the blockchain. These include smart contracts associated with boxes and the data within the registers of those boxes. The typical development flow of a dApp begins with the creation of transactions, followed by crafting smart contracts to facilitate the dApp's decentralized functionality on the blockchain. +In contrast, off-chain elements refer to the components of a dApp that operate outside the blockchain. Systems are needed to process Unspent Transaction Outputs (UTxOs) and advance them through the stages of a dApp's lifecycle. Off-chain systems often encompass REST endpoints and bots that execute several vital tasks, such as: -## Watchers on Rosen Bridge +- Retrieving data from the blockchain +- Composing transactions for user signatures +- Processing transactions poised for the next phase in the dApp's workflow + +### Case Study: Transaction Bot + +A transaction bot exemplifies an off-chain system designed to streamline the composition and processing of transactions. The Exle Tx Bot is an exemplary model of such a system. Detailed information about the Exle Tx Bot and its architecture can be found in their documentation: [Exle Tx Bot](https://exlebot.com/docs). -Watchers are integral to Rosen Bridge, serving as cross-chain oracles. They observe and report deposit events on their network to Ergo, contributing to the network's security and expansion. +A thorough grasp of the distinctions between on-chain and off-chain components, along with their respective roles, empowers developers to create more sophisticated and efficient dApps within the Ergo Blockchain ecosystem. +## ErgoDex Off-Chain Services + +For a comprehensive understanding of the off-chain services that support the functionality of ErgoDex, refer to the detailed documentation provided in [ErgoDEX off-chain services](dex_bots.md). + +## Watchers on Rosen Bridge +Watchers, functioning as cross-chain oracles, are vital to the Rosen Bridge's operations. They diligently monitor and relay deposit events from their respective networks to Ergo, bolstering the network's security and reach. ### How to Become a Watcher: -1. **Technical Setup**: Running a watcher node requires a stable internet connection and a machine that meets the technical specifications detailed in [Ergo's documentation](https://docs.ergoplatform.com/eco/rosen/rosen-watcher/) for more information. -2. **Provide Collateral**: Each instance requires 800 ERG and 30,000 RSN as collateral. This collateral is fully redeemable and the amount is adjustable. -3. **Monitor Transactions**: Watchers need to continuously monitor cross-chain transactions, validating them according to the protocol's rules. -4. **Earn Rewards**: Successful watchers earn rewards in ERG, distributed according to their contributions to the network's security and operation. +1. **Technical Setup**: To operate a watcher node, ensure a stable internet connection and a system that aligns with the technical requirements outlined in [Ergo's documentation](https://docs.ergoplatform.com/eco/rosen/rosen-watcher/). +2. **Provide Collateral**: A collateral of 800 ERG and 30,000 RSN is mandated for each instance, with the flexibility of redemption and adjustment. +3. **Monitor Transactions**: Vigilant monitoring of cross-chain transactions is imperative for watchers to validate them in adherence to the protocol's guidelines. +4. **Earn Rewards**: Watchers are remunerated in ERG for their pivotal role, with the distribution reflecting their contribution to network security and functionality. ### Estimated Rewards -The following data represents an example of the reward distribution for a single watcher on the Rosen network within the period from January 22, 2024, to February 3, 2024. The actual rewards can vary based on the traffic on the bridge. +The reward distribution for a watcher on the Rosen network from January 22, 2024, to February 3, 2024, is exemplified below. Note that rewards are contingent on bridge traffic and may fluctuate. - ERG Watcher Rewards: 100.217 ERG - ADA Watcher Rewards: 25.37 ADA - Total Rewards (ERG + ADA): 125.59 -Please note that these figures are subject to change and depend on the actual bridge traffic. The more traffic the bridge has, the higher the potential rewards for the watcher. - +These figures are indicative and subject to variation based on actual bridge usage. Increased traffic correlates with higher potential rewards for watchers. ## Oracles: Empowering Ergo's dApps -Oracles play a pivotal role in DeFi by providing external data (e.g., price feeds) to smart contracts. Ergo's ecosystem utilizes oracles for various applications, including stablecoins and financial instruments. +Oracles are the linchpin in DeFi, supplying smart contracts with indispensable external data, such as price feeds. Ergo's ecosystem leverages oracles for an array of applications, including stablecoins and sophisticated financial instruments. -> To join the existing Gold oracle pool, you will need a *Gold Pool Oracle Token*. These tokens are periodically made available through [auctions](https://ergoauctions.org/artwork/78263e5613557e129f075f0a241287e09c4204be76ad53d77d6e7feebcccb001), providing a fair and transparent process for potential participants. +> To participate in the Gold oracle pool, acquire a *Gold Pool Oracle Token* through [auctions](https://ergoauctions.org/artwork/78263e5613557e129f075f0a241287e09c4204be76ad53d77d6e7feebcccb001), ensuring a transparent entry process for aspirants. {.is-warning} - #### Becoming an Oracle Provider: - - -1. **Data Source Integration**: Oracle providers need to integrate reliable data sources with the Ergo blockchain, ensuring the information is accurate and timely. -2. **Deploy Oracle Contracts**: Deploy smart contracts on Ergo that will serve as the interface for your data feeds. -3. **Maintain Reliability**: Continuous monitoring and maintenance are required to ensure your oracle remains reliable and trustworthy. -4. **Compensation**: Oracle providers are typically compensated by the users or contracts that rely on their data feeds, often through transaction fees or subscriptions. Operating an Gold oracle nets approximately 24 GORT (Gold Oracle Reward Tokens) per day. - +1. **Data Source Integration**: Oracle providers must integrate dependable data sources with the Ergo blockchain to deliver precise and current information. +2. **Deploy Oracle Contracts**: Implement smart contracts on Ergo to act as conduits for your data streams. +3. **Maintain Reliability**: Consistent monitoring and upkeep are essential to sustain the credibility and reliability of your oracle service. +4. **Compensation**: Oracle providers typically receive compensation from the users or contracts utilizing their data, often via transaction fees or subscription models. Operating a Gold oracle yields an estimated 24 GORT (Gold Oracle Reward Tokens) daily. ## Bots for Automated Trading and Order Matching -Decentralized grid trading is a powerful concept implemented on the Ergo blockchain. It allows for automated trading orders while ensuring users maintain control over their funds. Two notable implementations of this concept are the Off the Grid and Machina Finance projects. - -Learn more about grid trading on [Investopedia](https://www.investopedia.com/terms/g/grid-trading.asp). +The Ergo blockchain embraces the potent concept of decentralized grid trading, enabling automated trading orders while retaining user control over funds. Prominent examples include the Off the Grid and Machina Finance projects. +Discover more about grid trading on [Investopedia](https://www.investopedia.com/terms/g/grid-trading.asp). ### Off the Grid -Off the Grid is a decentralized application (dApp) that builds on the grid trading contract proposed by kushti. It includes an execution bot/batcher for automating order matching without user interaction. +Off the Grid, a dApp, capitalizes on the grid trading contract proposed by kushti. It incorporates an execution bot/batcher to facilitate automated order matching. Explore the project [here](https://github.com/Telefragged/off-the-grid/) -Off the Grid provides the following features: +Key features of Off the Grid: -- Utilizes a contract that permits spending only if orders are correctly filled or with the order owner's signature. This contract can manage multiple orders simultaneously. -- Employs off-chain bots/batchers to monitor grid orders and match them against other liquidity sources. -- Currently, it matches orders against Spectrum Automated Market Makers (AMMs). However, it can be extended to other sources like the SigUSD bank. -- Supports trading of ERG against any token, with profits accumulated in ERGs. -- Enables grid orders to profit from repeated execution of the same orders, while bot operators benefit from arbitraging the price difference between the liquidity source and grid orders. +- A contract that authorizes spending solely for correctly filled orders or with the order owner's consent, capable of managing multiple orders concurrently. +- Off-chain bots/batchers that scrutinize grid orders and pair them with other liquidity sources, such as Spectrum AMMs, with potential extensions to other sources like the SigUSD bank. +- Support for ERG trading against any token, accruing profits in ERG. +- Grid orders benefit from the repeated execution of identical orders, while bot operators gain from arbitraging price discrepancies between liquidity sources and grid orders. -This concept was introduced by `@kushti` on [ergoforum](https://www.ergoforum.org/t/decentralized-grid-trading-on-ergo/). +The concept was introduced by `@kushti` on [ergoforum](https://www.ergoforum.org/t/decentralized-grid-trading-on-ergo/). -> "We can do decentralized grid trading on Ergo (which is automatically compatible with existing DEXes, such as Spectrum LP pools and babel fees). Grid trading is a good way to make profits from volatility, and many CEXes offer it." +> "Decentralized grid trading on Ergo is inherently compatible with existing DEXes, such as Spectrum LP pools and babel fees. It's an effective strategy to capitalize on market volatility, akin to offerings on many centralized exchanges (CEXes)." -Check out the [first decentralized grid order transaction on Ergo](https://twitter.com/chepurnoy/status/1582657292834861057). +View the [inaugural decentralized grid order transaction on Ergo](https://twitter.com/chepurnoy/status/1582657292834861057). ### Machina Finance -Machina Finance is another project on Ergo that is exploring the concept of grid trading. It is developing a decentralized exchange (DEX) that utilizes grid order contracts. +Machina Finance is an Ergo-based initiative exploring grid trading and developing a DEX that harnesses grid order contracts. Explore the project [here](machina-finance.md) ### Other bots -- [HummingBot: Using Dashboard to Deploy and Backtest Strategies](https://hummingbot.org/academy-content/using-dashboard-to-deploy-and-backtest-strategies/) -- [KuPyBot](https://github.com/FlyingPig69/KuPyBot): A simply buy low sell high bot written in python using Kucoins python library. +- [HummingBot: Deploying and Backtesting Strategies via Dashboard](https://hummingbot.org/academy-content/using-dashboard-to-deploy-and-backtest-strategies/) +- [KuPyBot](https://github.com/FlyingPig69/KuPyBot): A Python-based bot for Kucoin's platform, designed to execute a simple buy low, sell high strategy. ## Best Practices for Off-Chain Earnings -- **Stay Informed**: Keep up-to-date with the latest developments in the Ergo ecosystem, including updates to protocols and new opportunities for off-chain earnings. -- **Security**: Ensure your setup is secure, especially if you are handling private keys or large amounts of ERG. -- **Community Engagement**: Join Ergo's community forums and channels. Sharing insights and collaborating with others can enhance your strategies and impact. -- **Compliance**: Be aware of and comply with any legal or regulatory requirements applicable to your activities, especially when dealing with financial data or assets. +- **Stay Informed**: Remain abreast of the latest Ergo ecosystem developments, including protocol updates and emerging off-chain earning opportunities. +- **Security**: Prioritize the security of your setup, particularly when managing private keys or substantial ERG quantities. +- **Community Engagement**: Engage with Ergo's community forums and channels to share insights and collaborate, thereby enhancing your strategies and influence. +- **Compliance**: Adhere to all relevant legal and regulatory requirements associated with your financial data or asset-related activities. ## Conclusion -Ergo's ecosystem offers diverse opportunities for off-chain earnings through roles like watchers, oracles, and automated bots. These positions not only provide ways to earn passive income but also contribute significantly to the functionality and security of the Ergo blockchain. By engaging with these opportunities, users can support the decentralized ecosystem while benefiting from its growth and success. \ No newline at end of file +Ergo's ecosystem presents a plethora of off-chain earning prospects through roles such as watchers, oracles, and automated bots. These roles not only offer passive income streams but also significantly contribute to the Ergo blockchain's functionality and security. By participating in these opportunities, users can bolster the decentralized ecosystem and reap the benefits of its progression and success. \ No newline at end of file