{"id":26755224,"url":"https://github.com/henriquemarlon/swapx","last_synced_at":"2025-06-12T07:04:28.387Z","repository":{"id":277406889,"uuid":"932289688","full_name":"henriquemarlon/swapx","owner":"henriquemarlon","description":"An EVM Linux-powered coprocessor as an orderbook for UniswapV4","archived":false,"fork":false,"pushed_at":"2025-03-24T04:50:27.000Z","size":339,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T05:30:27.313Z","etag":null,"topics":["cartesi","defi","evm","restaking"],"latest_commit_sha":null,"homepage":"","language":"Solidity","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/henriquemarlon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-13T17:14:12.000Z","updated_at":"2025-03-24T04:50:30.000Z","dependencies_parsed_at":"2025-02-28T22:25:58.546Z","dependency_job_id":"c643cfee-914a-49b2-aa88-f812be4f2dfb","html_url":"https://github.com/henriquemarlon/swapx","commit_stats":null,"previous_names":["henriquemarlon/swapx"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henriquemarlon%2Fswapx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henriquemarlon%2Fswapx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henriquemarlon%2Fswapx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henriquemarlon%2Fswapx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/henriquemarlon","download_url":"https://codeload.github.com/henriquemarlon/swapx/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246042032,"owners_count":20714150,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cartesi","defi","evm","restaking"],"created_at":"2025-03-28T14:19:08.437Z","updated_at":"2025-03-28T14:19:09.037Z","avatar_url":"https://github.com/henriquemarlon.png","language":"Solidity","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cbr\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/user-attachments/assets/a3ed08f8-d58f-4a3a-94f1-0b4a39c721b9\" align=\"center\" width=\"20%\"\u003e\n\u003c/p\u003e\n\u003cbr\u003e\n\n\u003cdiv align=\"center\"\u003e\n    \u003ci\u003eAn EVM Linux-powered coprocessor as an orderbook for UniswapV4\u003c/i\u003e\n\u003c/div\u003e\n\u003cdiv align=\"center\"\u003e\n\u003cb\u003eCartesi Coprocessor orderbook powered by EigenLayer cryptoeconomic security\u003c/b\u003e\n\u003c/div\u003e\n\u003cbr\u003e\n\u003cp align=\"center\"\u003e\n\t\u003cimg src=\"https://img.shields.io/github/license/henriquemarlon/swapx?style=default\u0026logo=opensourceinitiative\u0026logoColor=white\u0026color=3D8EA5\" alt=\"license\"\u003e\n\t\u003cimg src=\"https://img.shields.io/github/last-commit/henriquemarlon/swapx?style=default\u0026logo=git\u0026logoColor=white\u0026color=868380\" alt=\"last-commit\"\u003e\n\u003c/p\u003e\n\n\u003e [!CAUTION]\n\u003e This is an experimental project under continuous development and should be treated as such. **Its use in production/mainnet is not recommended.** Learn about the known limitations of the application by accessing: [DISCLAIMER](./DISCLAIMER.md).\n\n##  Table of Contents\n- [Overview](#overview)\n- [Architecture](#architecture)\n- [Prerequisites](#prerequisites)\n- [Running](#running)\n- [Interacting](#interacting)\n\n### Overview\nSwapX integrates a decentralized orderbook with Uniswap v4 hooks, replacing the traditional AMM logic with an asynchronous swap system and limit orders. Leveraging EigenLayer's cryptoeconomic security through the Cartesi Coprocessor, it enables swaps to be scheduled, optimized, and auditable, ensuring greater liquidity efficiency and reducing trader uncertainty. This approach eliminates the need for immediate execution, allowing for more sophisticated and flexible strategies for market makers, liquidity protocols, and derivatives.\n\n### Architecture\n![image](https://github.com/user-attachments/assets/f12834c7-769f-4f60-b714-06690cd74f62)\n\n\u003e 1 - The [`SwapXHook.sol`](https://github.com/henriquemarlon/swapx/blob/main/contracts/src/SwapXHook.sol) implementation is a Uniswap hook based on AsyncSwap[^1]. Instead of executing the swap at the market price, it implements a custom logic for [**limit orders**](https://www.investopedia.com/terms/l/limitorder.asp):\n\u003e\n\u003e   - The order value is transferred to the hook upon creation;\n\u003e   - The user can cancel the order and receive the funds back;\n\u003e   - When an order is created, a task is issued to the SwapX order book, which will efficiently and intelligently match orders, including aggregating multiple orders and ensuring that the best orders are matched with the incoming order.\n\n\u003e 2 - The **Assets** in this case are token contracts that will be transacted in the swap between users through the pool and contracts that are part of the [**UniswapV4 SDK**](https://docs.uniswap.org/contracts/v4/overview).\n\n\u003e 3 - The **Operator**, which is part of the **Cartesi Coprocessor**, operates under the **crypto-economic security** of the [**EigenLayer restaking protocol**](https://docs.eigenlayer.xyz/eigenlayer/overview). This gives it the ability to perform operations with guarantees of the computation performed.\n\n\u003e 4 - The **Cartesi Coprocessor** is an EigenLayer AVS that operates through a network of operators, leveraging the runtime provided by the **Cartesi Machine**. It is triggered when a new TaskIssued(bytes32, bytes, address) event is emitted. To learn more, visit: https://docs.mugen.builders/cartesi-co-processor-tutorial/introduction.\n\n\u003e 5 - The **Base Layer Access** is enabled through domain `0x27`, present in the GIO, which allows calls via[`eth_getStorageAt`](https://www.quicknode.com/docs/ethereum/eth_getStorageAt). Based on this, the application can access the base layer (read-only), and this is how previously created orders (up to the previous block) are loaded into the application to be processed within the order book. The request specification is as follows:  \n\u003e   ```json\n\u003e   {\"domain\": \"0x27\", \"id\": \"0x\u003cblock_hash:32_bytes\u003e\u003caddress:20_bytes\u003e\u003cstorage_slot:32_bytes\u003e\"}\n\u003e   ```\n\n###  Prerequisites\n\n1. [Install Docker Desktop for your operating system](https://www.docker.com/products/docker-desktop/).\n\n    To install Docker RISC-V support without using Docker Desktop, run the following command:\n    \n   ```shell\n    docker run --privileged --rm tonistiigi/binfmt --install all\n   ```\n\n2. [Download and install the latest version of Node.js](https://nodejs.org/en/download)\n\n3. Cartesi CLI is an easy-to-use tool to build and deploy your dApps. To install it, run:\n\n   ```shell\n   npm i -g @cartesi/cli\n   ```\n\n4. [Install the Cartesi Coprocessor CLI](https://docs.mugen.builders/cartesi-co-processor-tutorial/installation)\n\n###  Running\n\n1. Start the devnet coprocessor infrastructure:\n\n   ```bash\n   make infra\n   ```\n\n2. Build and Publish the application:\n\n   ```sh\n   cartesi-coprocessor publish --network devnet\n   ```\n   \n\u003e [!WARNING]\n\u003e Before the next step, create a `.env` with the command bellow:\n\u003e ```bash\n\u003e make env\n\u003e ```\n\u003e This should look like:\n\u003e ```env\n\u003e RPC_URL=http://localhost:8545\n\u003e PRIVATE_KEY=0x8b3a350cf5c34c9194ca85829a2df0ec3153be0318b5e2d3348e872092edffba\n\u003e ```\n\n3. Deploy [UniswapV4](https://docs.uniswap.org/contracts/v4/overview) contracts, `SwapXHook.sol` and `SwapXTaskManager.sol` contracts:`\n\n- 3.1 Deploy UniswapV4 contracts:\n   \n   ```sh\n   make v4\n   ```\n\n\u003e [!NOTE]\n\u003e The following step requires some extra information provided by the command bellow:\n\u003e ```bash\n\u003e cartesi-coprocessor address-book\n\u003e ```\n\u003e Output sample:\n\u003e ```bash\n\u003e Machine Hash         0xdb1d7833f57f79c379e01b97ac5a398da31df195b1901746523be0bc348ccc88\n\u003e Devnet_task_issuer   0x95401dc811bb5740090279Ba06cfA8fcF6113778\n\u003e Testnet_task_issuer  0xff35E413F5e22A9e1Cc02F92dcb78a5076c1aaf3\n\u003e payment_token        0xc5a5C42992dECbae36851359345FE25997F5C42d\n\u003e ```\n\n- 3.2 Deploy `SwapXHook.sol` and `SwapXTaskManager.sol`:\n\n   ```bash\n   make hook\n   ```\n\n   Output sample:\n\n  ```bash\n   [⠊] Compiling...\n   No files changed, compilation skipped\n   Enter Coprocessor address: \u003cdevnet_task_issuer\u003e\n   Enter Machine Hash: \u003cmachine_hash\u003e\n  ```\n\n### Interacting\n\n\u003e [!IMPORTANT] \n\u003e If the previous steps were followed precisely, specifically the one that sets up the local infrastructure, accessing [http://localhost:5100](http://localhost:5100) will present you with a block explorer where you can monitor the transactions occurring on the contract of interest. In this project, that contract is the one that implements the Uniswap hook via AsyncSwap[^1]. After that, just search for the contract using that address on Otterscan.\n\n```bash\nmake demo\n```\n\n\n\u003e [!NOTE]\n\u003e You should observe, after a while, four calls targeting the signature method `0x7417ccfb`, each covering one of the following scenarios:\n\u003e \n\u003e |        | Scenario                                       | Description                                                                                                |\n\u003e |--------|----------------------------------------------|------------------------------------------------------------------------------------------------------------|\n\u003e | 0      | Buy Order Fulfilled by One Sell Order       | A buy order is completely fulfilled by a single sell order.                                                |\n\u003e | 1      | Buy Order Fulfilled by Multiple Sell Orders | A buy order is completely matched by a combination of multiple sell orders.                                |\n\u003e | 2      | Sell Order Fulfilled by One Buy Order       | A sell order is completely fulfilled by a single buy order.                                                |\n\u003e | 3      | Sell Order Fulfilled by Multiple Buy Orders | A sell order is completely matched by a combination of multiple buy orders.                                |\n\u003e | 4      | Buy Order Partially Fulfilled by Multiple Sell Orders | A buy order is only partially matched, while multiple sell orders fulfill part of it.                     |\n\nYou can see even more details by accessing the logs tab of one of these transactions, and you'll come across something like this:\n\n![logs](https://github.com/user-attachments/assets/d2161550-aa96-41b2-bb13-0e5ebe457ea3)\n\n[^1]: You can see [here](https://docs.uniswap.org/contracts/v4/quickstart/hooks/async-swap#Configure-a-AsyncSwap-Hook) the reference for enabling the AsyncSwap in a UniswapV4 hook, and [here](https://github.com/henriquemarlon/swapx/blob/demo/contracts/src/SwapXHook.sol#L109) is where it was defined within the application.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhenriquemarlon%2Fswapx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhenriquemarlon%2Fswapx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhenriquemarlon%2Fswapx/lists"}