From 631605808b240534e22d33288cd6240cb279f9b1 Mon Sep 17 00:00:00 2001 From: M Glasgow Date: Mon, 23 Dec 2024 13:29:43 +0000 Subject: [PATCH] grid trading and arbit updates --- docs/dev/data-model/nizk.md | 56 ++++---- docs/uses/arbit.md | 178 +++++++++++++++++++++++++ docs/uses/grid_trading.md | 26 +--- docs/uses/off_the_grid.md | 21 +++ docs/uses/off_the_grid_tut.md | 237 ++++++++++++++++++++++++++++++++++ mkdocs.yml | 9 +- 6 files changed, 479 insertions(+), 48 deletions(-) create mode 100644 docs/uses/arbit.md create mode 100644 docs/uses/off_the_grid.md create mode 100644 docs/uses/off_the_grid_tut.md diff --git a/docs/dev/data-model/nizk.md b/docs/dev/data-model/nizk.md index 4f777970..001079f5 100644 --- a/docs/dev/data-model/nizk.md +++ b/docs/dev/data-model/nizk.md @@ -11,30 +11,35 @@ NIZKs in Ergo are primarily implemented through **Sigma Protocols** (Σ-protocol ### Key Characteristics - **Non-Interactive**: Proofs can be verified without direct communication - - Unlike traditional interactive zero-knowledge proofs, NIZKs can be verified asynchronously - - Reduces computational overhead and network complexity + + - Unlike traditional interactive zero-knowledge proofs, NIZKs can be verified asynchronously + - Reduces computational overhead and network complexity - **Zero-Knowledge**: No information about the secret is revealed - - Cryptographically guarantees that only the validity of a statement is proven - - Protects sensitive information while maintaining verifiability + + - Cryptographically guarantees that only the validity of a statement is proven + - Protects sensitive information while maintaining verifiability - **Composable**: Can be combined using logical operators like AND, OR, and THRESHOLD - - Enables creation of complex cryptographic conditions - - Supports advanced smart contract logic and privacy-preserving protocols + + - Enables creation of complex cryptographic conditions + - Supports advanced smart contract logic and privacy-preserving protocols ## Cryptographic Primitives Ergo supports several fundamental zero-knowledge proof types: 1. **Discrete Logarithm Proofs** - - Prove knowledge of a secret key without revealing it - - Fundamental to [Schnorr signature verification](schnorr.md) - - Implemented using `proveDlog()` predicate in [ErgoScript](ergoscript.md) + + - Prove knowledge of a secret key without revealing it + - Fundamental to [Schnorr signature verification](schnorr.md) + - Implemented using `proveDlog()` predicate in [ErgoScript](ergoscript.md) 2. **Diffie-Hellman Tuple Proofs** - - Prove equality of discrete logarithms across different generators - - Enables privacy-preserving key exchange and contract designs - - Critical for advanced cryptographic protocols + + - Prove equality of discrete logarithms across different generators + - Enables privacy-preserving key exchange and contract designs + - Critical for advanced cryptographic protocols ## Implementation Techniques @@ -43,6 +48,7 @@ Ergo supports several fundamental zero-knowledge proof types: Ergo makes proofs non-interactive using the Fiat-Shamir transformation, which converts interactive proofs into non-interactive ones by using a cryptographic hash function. Key steps: + - Transform an interactive proof into a non-interactive version - Use a cryptographic hash function to generate a challenge - Eliminates the need for real-time communication between prover and verifier @@ -72,19 +78,22 @@ val thresholdProof = prove { ### Privacy-Preserving Techniques 1. **Ring Signatures** - - Prove one of multiple possible signers without revealing the exact signer - - Enables anonymous transactions - - Detailed in [Ring Signatures](ring.md) documentation + + - Prove one of multiple possible signers without revealing the exact signer + - Enables anonymous transactions + - Detailed in [Ring Signatures](ring.md) documentation 2. **Threshold Signatures** - - Require k-out-of-n participants to sign - - Supports multi-party computational scenarios - - Explored in [Threshold Signatures](threshold.md) documentation + + - Require k-out-of-n participants to sign + - Supports multi-party computational scenarios + - Explored in [Threshold Signatures](threshold.md) documentation 3. **Stealth Addresses** - - Generate one-time addresses for enhanced transaction privacy - - Prevent linking of transactions to a specific public address - - Crucial for maintaining financial privacy + + - Generate one-time addresses for enhanced transaction privacy + - Prevent linking of transactions to a specific public address + - Crucial for maintaining financial privacy ### Mixer Protocols @@ -129,8 +138,9 @@ NIZKs in Ergo are designed with performance in mind: - [Cryptographic Foundations](crypto.md) - [Zero-Knowledge Proofs in Ergo](zkp.md) - Academic Papers: - - [Sigma Protocols: A Survey](https://eprint.iacr.org/2021/1022) - - [Non-Interactive Zero-Knowledge Proofs](https://eprint.iacr.org/2016/263) + + - [Sigma Protocols: A Survey](https://eprint.iacr.org/2021/1022) + - [Non-Interactive Zero-Knowledge Proofs](https://eprint.iacr.org/2016/263) ## Conclusion diff --git a/docs/uses/arbit.md b/docs/uses/arbit.md new file mode 100644 index 00000000..0794c7ef --- /dev/null +++ b/docs/uses/arbit.md @@ -0,0 +1,178 @@ +# Arbit Documentation + +[Arbit](https://github.com/ConnecMent/arbit) is a simple and intuitive arbitrage platform designed for decentralized trading on the Ergo and Cardano blockchains. It aims to simplify the arbitrage process, enabling users to identify and execute profitable swaps with minimal setup. + +/// details | WIP + {type: warning, open: true} +This project is a work in progress and is not yet ready for production use. +/// + + +--- + +## Overview + +**What is Arbit?** + +Arbit streamlines the process of arbitrage trading by providing a clean and simple interface. The platform identifies opportunities where a user can buy and sell tokens across different decentralized exchanges to make a profit. + +- **Supported Tokens:** ERG, ADA, and RSN. +- **Supported Exchanges:** Ergo Dex and Splash. +- **Core Features:** + + - Predefined arbitrage strategies (called "Arbits"). + - Focus on simplicity and usability. + - Execution of swaps with just a few clicks. + +**What is an Arbit?** + +An Arbit is a series of swaps that generate profit. For example: + +1. Sell 100 X tokens on Exchange A for $100. +2. Buy 105 Y tokens on Exchange B for the same $100. +3. Profit from the additional 5 Y tokens. + +--- + +## Key Features + +### Simplicity and Usability + +- Designed for users with basic blockchain knowledge. +- Clear interface with no distractions or unnecessary complexity. +- Profitability of swaps displayed prominently. + +### Fixed Arbitrage Strategies + +- Supports predefined arbitrage paths, such as: + + - ERG ↔ ADA + - RSN ↔ ADA + +- Profit calculations are based on fixed USD values ($50 and $100). + +--- + +## How It Works + +1. **Arbitrage Strategy Execution:** + + - Predefined paths calculate profitability based on current market conditions. + - Fixed token values ($50 and $100) are used for calculations to avoid complexity. + +2. **Supported Providers:** + + - **Ergo Dex:** Facilitates ERG and ADA swaps. + - **Splash:** Enables swapping of RSN and ADA tokens. + +3. **Profit Calculation:** + + - Example for a $50 swap: + - Sell $50 worth of rsADA on Ergo Dex for ERG. + - Swap ERG for ADA on Splash. + - Compare the ADA received with the initial $50 equivalent. + +--- + +## Deployment + +### Local Setup + +1. **Clone the Repository:** + + ```bash + git clone https://github.com/ConnecMent/arbit.git + cd arbit + ``` + +2. **Set Up Environment Variables:** + + Create a `.env` file in the root directory with the following variables: + + - `SPLASH_API_URL`: API URL for Splash exchange. + - `ERGO_EXPLORER_API_URL`: API URL for Ergo Explorer. + + Example: + + ```env + SPLASH_API_URL=https://api.splash.exchange + ERGO_EXPLORER_API_URL=https://api.ergoplatform.com + ``` + +3. **Run the Development Server:** + + Install dependencies and start the development server: + + ```bash + pnpm install + pnpm run dev + ``` + + The application will be available at `http://localhost:3000`. + +--- + +## Arbitrage Strategies + +The following strategies are implemented in Arbit: + +### ERG ↔ ADA Arbitrage + +- Leverages Ergo Dex and Splash to identify profitable swaps between ERG and ADA. +- Calculations consider both direct and reverse swap paths for maximum opportunities. + +### RSN ↔ ADA Arbitrage + +- Utilizes Ergo Dex and Splash for swaps between RSN and ADA tokens. +- Similar profit calculation methods as the ERG ↔ ADA strategy. + +--- + +## Technical Details + +### Core Arbitrage Logic + +The core logic for arbitrage is implemented in `src/arbitrategy.ts`. It defines a set of predefined strategies for swapping between supported tokens and providers. + +### Provider Integrations + +- **Ergo Dex (`src/providers/ergodex.ts`):** + + - Interacts with the Ergo Dex SDK for swapping tokens. + - Supports `x2y` and `y2x` operations. + +- **Splash (`src/providers/splash.ts`):** + + - Uses the Splash API to fetch order book data. + - Supports bid/ask matching for liquidity and price calculations. + +--- + +## Usage Guide + +1. **Prepare Tokens:** + + - Ensure you have supported tokens (ERG, ADA, RSN) on Ergo and Cardano chains. + - Use [Rosen Bridge](https://app.rosen.tech) to bridge assets if necessary. + +2. **Visit the App:** + + - Open the application and review the displayed arbitrage opportunities. + +3. **Execute a Swap:** + + - If a profitable Arbit is available, execute the swap by following the on-screen instructions. + +--- + +## Contributing + +The project is maintained by [ConnecMent](https://github.com/ConnecMent). Contributions are welcome via pull requests. + +**Team:** + +- Mentors: [@mkermani144](https://github.com/mkermani144), [@fatemeh-ra](https://github.com/fatemeh-ra) +- Mentee: [@SeyedMojtaba1](https://github.com/SeyedMojtaba1) + +Special thanks to [@zargarzadehm](https://github.com/zargarzadehm) for Ergo Dex SDK insights. + diff --git a/docs/uses/grid_trading.md b/docs/uses/grid_trading.md index eb650906..1ae01a41 100644 --- a/docs/uses/grid_trading.md +++ b/docs/uses/grid_trading.md @@ -6,31 +6,11 @@ Decentralized grid trading is a powerful concept implemented on the Ergo blockch Learn more about grid trading on [Investopedia](https://www.investopedia.com/terms/g/grid-trading.asp). -## Off the Grid +## [Off the Grid](off_the_grid.md) 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. -Explore the project [here](https://github.com/Telefragged/off-the-grid/) +## [Machina Finance](machina-finance.md) -### Features - -Off the Grid provides the following features: - -- 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. - -This 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." - -Check out the [first 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. - -Explore the project [here](../eco/machina-finance.md) +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. \ No newline at end of file diff --git a/docs/uses/off_the_grid.md b/docs/uses/off_the_grid.md new file mode 100644 index 00000000..d25e9959 --- /dev/null +++ b/docs/uses/off_the_grid.md @@ -0,0 +1,21 @@ +## 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. + +Explore the project [here](https://github.com/Telefragged/off-the-grid/) and check out our [Getting Started Guide](off_the_grid_tut.md). + +### Features + +Off the Grid provides the following features: + +- 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. + +This 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." + +Check out the [first decentralized grid order transaction on Ergo](https://twitter.com/chepurnoy/status/1582657292834861057). \ No newline at end of file diff --git a/docs/uses/off_the_grid_tut.md b/docs/uses/off_the_grid_tut.md new file mode 100644 index 00000000..b63eccb7 --- /dev/null +++ b/docs/uses/off_the_grid_tut.md @@ -0,0 +1,237 @@ +# Getting Started with Off-the-Grid Ergo Trading Bot + +This guide provides a thorough walkthrough for setting up and operating the **[Off-the-Grid Ergo Trading Bot](https://github.com/Telefragged/off-the-grid)** decentralized grid trading bot on the Ergo blockchain. + +/// details | Video Guide + {type: info, open: true} +Alternatively, a video walkthrough from MarcTheShark can be found here: [Ergo Grid Trading Bot Setup](https://www.youtube.com/watch?v=LsRb8_G9rzE) +/// + +--- + +## Prerequisites + +Before proceeding, ensure the following: + +1. **Knowledge and Tools:** + + - Basic understanding of the Ergo blockchain and grid trading strategies. + - Familiarity with Rust programming language and CLI tools. + +2. **Environment Setup:** + + - Installed [Rust](https://rustup.rs/) and Cargo (Rust's package manager). + - Configured Ergo node and wallet. Follow [Ergo Node Setup](https://docs.ergoplatform.com/node/install/) and [Wallet Guide](https://docs.ergoplatform.com/node/wallet/). + +3. **Nix Installation (Optional):** + + - For easier building and execution, install [Nix](https://nixos.org/). + +--- + +## Overview of Off-the-Grid + +**Off-the-Grid** enables decentralized, automated grid trading on the Ergo blockchain, providing features such as: + +- Secure contract-based trading ensuring order safety. +- Off-chain bots for order tracking and execution. +- Compatibility with Spectrum AMM for liquidity matching. + +**Limitations:** + +- Contracts are not audited—exercise caution with significant assets. +- Profits are not guaranteed, and risks depend on market conditions. + +--- + +## Step-by-Step Guide + +### 1. Clone and Build the Repository + +1. **Clone the Repository:** + + ```bash + git clone https://github.com/Telefragged/off-the-grid.git + cd off-the-grid + ``` + +2. **Build with Cargo or Nix:** + + - **With Nix:** (Recommended for simplicity) + + ```bash + nix build + ``` + + The executable is placed in `./result/bin/off-the-grid`. + + - **With Cargo:** + + ```bash + cargo build --release + ``` + + The executable is in `./target/release/off-the-grid`. + +--- + +### 2. Node Setup + +1. **Node Configuration:** + + Update the `node_config.json` file with: + + - `api_url`: Your Ergo node's API URL (e.g., `http://127.0.0.1:9053`). + - `api_key`: API key from your Ergo node. + + Example: + + ```json + { + "api_url": "http://127.0.0.1:9053", + "api_key": "your-wallet-api-key" + } + ``` + +2. **Set Up Wallet:** + + Follow the Ergo wallet setup guide. Ensure the wallet is initialized and synchronized. + +3. **Generate Scans Configuration:** + + Run the following command to generate `scan_config.json`: + + ```bash + off-the-grid scans create-config + ``` + + To include all existing boxes, add `--rescan` to the command. + +--- + +### 3. Fetch Token Information (Optional) + +For better usability, update the token list: + +```bash +off-the-grid tokens update +``` + +This fetches token details from Spectrum's API and saves them locally. + +--- + +### 4. Create Grid Orders + +1. **Define a Grid Order:** + + Use the `grid create` command to specify trading parameters: + + ```bash + off-the-grid grid create -t -v -o -r - -i + ``` + + - ``: Name of the token to trade. + - ``: Total Ergo value for the grid. + - ``: Number of grid orders. + - `` and ``: Price range for the grid. + - ``: Unique identifier for the grid. + + **Example:** + + ```bash + off-the-grid grid create -t COMET -v 10 -o 50 -r 50000-100000 -i comet + ``` + +2. **Confirm Transaction:** + + After generating the grid order, review and confirm using on-screen prompts. + +--- + +### 5. Manage and Monitor Grids + +1. **List Active Grids:** + + ```bash + off-the-grid grid list + ``` + + This command displays all active grids with details like bid/ask prices and profit. + +2. **View Grid Details:** + + ```bash + off-the-grid grid details -i + ``` + + Replace `` with the grid's unique identifier. + +3. **Redeem Grid Orders:** + + Close or redeem grid orders with: + + ```bash + off-the-grid grid redeem -i + ``` + +--- + +### 6. Run the Matching Bot + +1. **Configure Matcher:** + + Set up the reward address in `matcher_config.json`: + + ```json + { + "reward_address": "your_reward_address" + } + ``` + + Alternatively, use an environment variable: + + ```bash + export MATCHER_REWARD_ADDRESS="your_reward_address" + ``` + +2. **Start the Matcher:** + + ```bash + off-the-grid matcher + ``` + + The bot logs successful transactions and errors. Multiple matchers may compete for transactions, so occasional failures are expected. + +--- + +### 7. Optimize and Analyze + +1. **Performance Monitoring:** + + Check logs to identify issues or opportunities for improvement: + + ```bash + off-the-grid logs tail + ``` + +2. **Experiment with Parameters:** + + Test various configurations to find optimal settings for market conditions. + +3. **Integrate Analytics:** + + Use tools like Spectrum to track market trends and evaluate the bot's performance. + +--- + +## Best Practices + +- **Security:** Safeguard your API keys and wallet credentials. + +- **Caution:** Avoid over-investing in untested strategies or assets. + +- **Stay Updated:** Keep the bot, tokens, and configs up-to-date with regular updates. + +For additional assistance, consult the repository's documentation or contact the community. + diff --git a/mkdocs.yml b/mkdocs.yml index 98755bdf..d5c40fcb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -313,12 +313,17 @@ nav: - Tooling: - Crux Finance: eco/crux.md # - Azorus: eco/azorus.md - - ErgoNames: eco/ergonames.md - Reputation System: eco/reputation-system.md - SigmaRand: eco/sigmarand.md - Moria Finance: eco/moria-finance.md - - Grid Trading: uses/grid_trading.md + - Trading: + - Arbit: uses/arbit.md + - Grid Trading: + - uses/grid_trading.md + - Off the Grid: + - uses/off_the_grid.md + - Tutorial: uses/off_the_grid_tut.md - Applications: - Thz.FM: eco/thz-fm.md - TabbyPOS: eco/tabbypos.md