| Name | solana-mev-agent-py JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Aleph is Urani's Python in-house MEV agent, designed to take advantage of MEV opportunities on the Solana Blockchain through the Urani Protocol. |
| upload_time | 2025-01-26 01:06:33 |
| maintainer | None |
| docs_url | None |
| author | Urani Labs |
| requires_python | <4.0,>=3.10 |
| license | GPL-3.0 license |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
## MEV Agent Aleph
<br>
<p align="center">
<img src="https://github.com/user-attachments/assets/78cb883e-8ba4-4a63-8f67-1f33f4a827bf" width="20%" align="center" style="padding:1px;border:1px solid black;"/>
</p>
<br>
#### 👉🏼 [Agent Aleph](https://docs.urani.trade/mev-agents/agents) is Urani's in-house arbitrage agent written in Python. Although the private version of Aleph is private for the Urani Protocol, this template brings its basic proprieties to the public.
#### 👉🏼 Authors: **[bt3gl](https://github.com/von-steinkirch)** and **[luca-nik](https://github.com/luca-nik)**.
#### 👉🏼 **[Details on how the public version of Aleph v0.1 works](#how-aleph-works)**.
#### 👉🏼 **[Details on how to run Aleph thorugh its CLI](#run-aleph-through-the-cli)**.
<br>
----
## How Aleph Works
<br>
1️⃣ Listen for incoming batches: Aleph fetches the orders from the Urani's orderbook;<br>
2️⃣ Parse these batches to extract the order intents;<br>
3️⃣ Check for peer-to-peer matches among the intents: naive 1-hop search, partial fills are not supported at this time; <br>
4️⃣ Spin a new thread for each intent with no P2P match to calculate solutions for best quotes through arbitrage in different AMMs;<br>
5️⃣ Pack the solutions and send them to the protocol.<br>
<br>
For this particular release, we bring an example of Aleph sending quote requests to **[Jupiter](https://station.jup.ag/)** to obtain the optimal route for each intent. Future versions will expand routing algorithms and fetch AMMs from different venues.
<br>
---
### Aleph's Structure
<br>
Aleph's source code is structured as the following:
* `main.py`: The entry point when running the command line.
* `agents/`: Contains the main classes for the "bots". Also, the entry point for running the agent.
* `solana/`: Contains an extensive wrapper for operations on the Solana blockchain.
* `orders/`: Contains the classes to process intents and batches.
* `liquidity/`: Contains wrapper classes for liquidity venues on the Solana blockchain.
* `p2p/`: Contains algorithms and optimizations for off-chain peer-to-peer matches.
* `protocol_server/`: Contains the API for the local server that mimick the Urani protocol.
* `oracles/`: Contain wrapper for price discovery.
* `utils/`: Contains several helper classes and methods for network operations, mathematics, system procedures, oracles, etc.
<br>
```bash
src
├── main.py
├── agents
│ ├── aleph.py
│ ├── base.py
│ └── main.py
├── liquidity
│ ├── base.py
│ ├── cexes
│ └── jupiter.py
├── oracles
│ ├── dexscreener.py
│ ├── helius.py
│ └── pyth.py
├── orders
│ ├── batch.py
│ ├── intent.py
│ ├── quote.py
│ └── solution.py
├── p2p
│ └── level_one.py
├── protocol_server
│ ├── _server.py
│ ├── orderbook
│ ├── server.log
│ ├── server_utils.py
│ ├── static
│ └── templates
├── sol
│ ├── accounts.py
│ ├── base.py
│ ├── blocks.py
│ └── transactions.py
└── utils
├── config.py
├── logging.py
├── maths.py
├── network.py
└── system.py
```
<br>
----
## Run Aleph through the CLI
<br>
### Local Setup
<br>
Create a `.env` file :
```bash
cp .env.example .env
vim .env
```
<br>
Fill in the following information:
| Parameter | Description | Default |
|-------------------------|----------------------------------|:-------------------------------------:|
| `WALLET_PRIVATE_KEY` | Your private key for signing. | - |
| `HELIUS_API_KEY` | Your helius api key | - |
| `LOG_LEVEL` | The level of logging you desire. | `info` |
| `RPC_HTTPS` | The RPC HTTP URL to connect. | `https://api.mainnet-beta.solana.com/`|
<br>
Install the program cli:
```bash
make install
```
<br>
---
### Test the installation
<br>
You can test the installation with:
```bash
poetry run pytest
```
```console
====================================================================== test session starts =======================================================================
platform darwin -- Python 3.12.4, pytest-8.3.2, pluggy-1.5.0
rootdir: XXX
configfile: pyproject.toml
plugins: order-1.2.1, anyio-4.4.0, ordering-0.6
collected 7 items
tests/test_cli.py .... [ 57%]
tests/test_server.py .. [ 85%]
tests/test_aleph.py . [100%]
======================================================================= 7 passed in 16.25s =======================================================================
```
<br>
---
### Running the CLI
<br>
You can get information on the CLI commands by running:
```bash
poetry run mcli -h
```
```console
88 88 8b,dPPYba, ,adPPYYba, 8b,dPPYba, 88
88 88 88P' "Y8 "" `Y8 88P' `"8a 88
88 88 88 ,adPPPPP88 88 88 88
"8a, ,a88 88 88, ,88 88 88 88
`"YbbdP'Y8 88 `"8bbdP"Y8 88 88 88
Aleph CLI: Urani MEV Agent.
options:
-h, --help show this help message and exit
-s Print info on the Solana blockchain.
-a [AGENT], --agents [AGENT]
Print info on the available agents or on specific [AGENT]
-d [AGENT], --deploy [AGENT]
Deploy a specific [AGENT].
-l Print info on liquidity sources.
-o Print info on the Oracles.
```
<br>
----
### Usage
<br>
This first version of Aleph interacts with a local-server initialized by the user that mimics the Urani Protocol.
<br>
Start a local server:
```bash
poetry run start_server
```
<br>
This server can be visited at:
```bash
http://127.0.0.1:8000/
```
<br>
Once the server is running, you can deploy Aleph by running the CLI, adding the flag `--deploy` or `-d` and the string `aleph`:
```bash
poetry run mcli -d aleph
# OR
poetry run python ./src/main.py -d aleph
```
<br>
This will output:
```console
88 88 8b,dPPYba, ,adPPYYba, 8b,dPPYba, 88
88 88 88P' "Y8 "" `Y8 88P' `"8a 88
88 88 88 ,adPPPPP88 88 88 88
"8a, ,a88 88 88, ,88 88 88 88
`"YbbdP'Y8 88 `"8bbdP"Y8 88 88 88
Loading environment variables...
🛹 Deploying Agent Aleph ...
Aleph is the first Urani MEV in-house agent.
.Version: v0.1
.Language: Python
.Routing algorithm: Jupiter
.P2P matches: Naive 1-hop
.Partial fill: No
.Ring trades: No
--> Check the README to learn more about Aleph <--
🛹 Starting Agent Aleph...
🛹 Aleph is running...
🛹 Fetching current batch from http://127.0.0.1:8000/batches
⏳ Aleph is waiting for a valid batch ...
```
<br>
This means Aleph is waiting for a batch to be posted in the orderbook.
To post a valid batch in the orderbook, open a new terminal window and go into the folder `orders_templates`.
Post post the `order_example.json` via:
```@console
curl -X POST "http://127.0.0.1:8000/batches" -H "Content-Type: application/json" -d @example_batch.json
```
<br>
Now look what Aleph does:
```console
88 88 8b,dPPYba, ,adPPYYba, 8b,dPPYba, 88
88 88 88P' "Y8 "" `Y8 88P' `"8a 88
88 88 88 ,adPPPPP88 88 88 88
"8a, ,a88 88 88, ,88 88 88 88
`"YbbdP'Y8 88 `"8bbdP"Y8 88 88 88
Loading environment variables...
🛹 Deploying Agent Aleph ...
Aleph is the first Urani MEV in-house agent.
.Version: v0.1
.Language: Python
.Routing algorithm: Jupiter
.P2P matches: Naive 1-hop
.Partial fill: No
.Ring trades: No
--> Check the README to learn more about Aleph <--
🛹 Starting Agent Aleph...
🛹 Aleph is running...
🛹 Fetching current batch from http://127.0.0.1:8000/batches
⏳ Aleph is waiting for a valid batch ...
🛹 Aleph found a valid batch ...
🤙 Aleph is solving the order...
⚙️ Searching for p2p matches ...
🤙 Found p2p matches.
⚙️ Searching optimal execution path for 2 intents ...
🤙 Sending solutions to http://127.0.0.1:8000/solutions
🛹 Agent Aleph has finished
```
<br>
You can check the solutions by visiting: `http://127.0.0.1:8000/solutions`.
If you want to try with another batch, modify the template `orders_templates/order_example.json` as you wish and post it to the orderbook.
This will override the last batch.
Then run again Aleph.
When you are finished, stop the server with:
```bash
poetry run stop_server
```
<br>
---
### License and Contributing
<br>
This project is distributed under the **[Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0)**.
You are welcome to contribute. See the guidelines **[here](.internal/CONTRIBUTING.md)**.
<br>
Raw data
{
"_id": null,
"home_page": null,
"name": "solana-mev-agent-py",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Urani Labs",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/0f/29/6d9d101c58074fd07e63d20cd7edd2ad76f53992d1ad8ca0028cfc9e64b7/solana_mev_agent_py-0.1.0.tar.gz",
"platform": null,
"description": "## MEV Agent Aleph\n\n<br>\n\n<p align=\"center\">\n<img src=\"https://github.com/user-attachments/assets/78cb883e-8ba4-4a63-8f67-1f33f4a827bf\" width=\"20%\" align=\"center\" style=\"padding:1px;border:1px solid black;\"/>\n</p>\n\n\n\n<br>\n\n#### \ud83d\udc49\ud83c\udffc [Agent Aleph](https://docs.urani.trade/mev-agents/agents) is Urani's in-house arbitrage agent written in Python. Although the private version of Aleph is private for the Urani Protocol, this template brings its basic proprieties to the public.\n\n#### \ud83d\udc49\ud83c\udffc Authors: **[bt3gl](https://github.com/von-steinkirch)** and **[luca-nik](https://github.com/luca-nik)**.\n\n#### \ud83d\udc49\ud83c\udffc **[Details on how the public version of Aleph v0.1 works](#how-aleph-works)**.\n#### \ud83d\udc49\ud83c\udffc **[Details on how to run Aleph thorugh its CLI](#run-aleph-through-the-cli)**.\n\n\n<br>\n\n----\n\n## How Aleph Works\n\n<br>\n\n1\ufe0f\u20e3 Listen for incoming batches: Aleph fetches the orders from the Urani's orderbook;<br>\n2\ufe0f\u20e3 Parse these batches to extract the order intents;<br>\n3\ufe0f\u20e3 Check for peer-to-peer matches among the intents: naive 1-hop search, partial fills are not supported at this time; <br>\n4\ufe0f\u20e3 Spin a new thread for each intent with no P2P match to calculate solutions for best quotes through arbitrage in different AMMs;<br>\n5\ufe0f\u20e3 Pack the solutions and send them to the protocol.<br>\n\n<br>\n\nFor this particular release, we bring an example of Aleph sending quote requests to **[Jupiter](https://station.jup.ag/)** to obtain the optimal route for each intent. Future versions will expand routing algorithms and fetch AMMs from different venues.\n\n<br>\n\n---\n\n### Aleph's Structure\n\n<br>\n\nAleph's source code is structured as the following:\n\n* `main.py`: The entry point when running the command line.\n* `agents/`: Contains the main classes for the \"bots\". Also, the entry point for running the agent.\n* `solana/`: Contains an extensive wrapper for operations on the Solana blockchain.\n* `orders/`: Contains the classes to process intents and batches.\n* `liquidity/`: Contains wrapper classes for liquidity venues on the Solana blockchain.\n* `p2p/`: Contains algorithms and optimizations for off-chain peer-to-peer matches.\n* `protocol_server/`: Contains the API for the local server that mimick the Urani protocol.\n* `oracles/`: Contain wrapper for price discovery.\n* `utils/`: Contains several helper classes and methods for network operations, mathematics, system procedures, oracles, etc. \n\n<br>\n\n```bash\nsrc\n \u251c\u2500\u2500 main.py\n \u251c\u2500\u2500 agents\n \u2502 \u251c\u2500\u2500 aleph.py\n \u2502 \u251c\u2500\u2500 base.py\n \u2502 \u2514\u2500\u2500 main.py\n \u251c\u2500\u2500 liquidity\n \u2502 \u251c\u2500\u2500 base.py\n \u2502 \u251c\u2500\u2500 cexes\n \u2502 \u2514\u2500\u2500 jupiter.py\n \u251c\u2500\u2500 oracles\n \u2502 \u251c\u2500\u2500 dexscreener.py\n \u2502 \u251c\u2500\u2500 helius.py\n \u2502 \u2514\u2500\u2500 pyth.py\n \u251c\u2500\u2500 orders\n \u2502 \u251c\u2500\u2500 batch.py\n \u2502 \u251c\u2500\u2500 intent.py\n \u2502 \u251c\u2500\u2500 quote.py\n \u2502 \u2514\u2500\u2500 solution.py\n \u251c\u2500\u2500 p2p\n \u2502 \u2514\u2500\u2500 level_one.py\n \u251c\u2500\u2500 protocol_server\n \u2502 \u251c\u2500\u2500 _server.py\n \u2502 \u251c\u2500\u2500 orderbook\n \u2502 \u251c\u2500\u2500 server.log\n \u2502 \u251c\u2500\u2500 server_utils.py\n \u2502 \u251c\u2500\u2500 static\n \u2502 \u2514\u2500\u2500 templates\n \u251c\u2500\u2500 sol\n \u2502 \u251c\u2500\u2500 accounts.py\n \u2502 \u251c\u2500\u2500 base.py\n \u2502 \u251c\u2500\u2500 blocks.py\n \u2502 \u2514\u2500\u2500 transactions.py\n \u2514\u2500\u2500 utils\n \u251c\u2500\u2500 config.py\n \u251c\u2500\u2500 logging.py\n \u251c\u2500\u2500 maths.py\n \u251c\u2500\u2500 network.py\n \u2514\u2500\u2500 system.py\n```\n\n<br>\n\n----\n\n## Run Aleph through the CLI\n\n<br>\n\n### Local Setup\n\n<br>\n\nCreate a `.env` file :\n\n```bash\ncp .env.example .env\nvim .env\n```\n\n<br>\n\nFill in the following information:\n\n| Parameter | Description | Default |\n|-------------------------|----------------------------------|:-------------------------------------:|\n| `WALLET_PRIVATE_KEY` | Your private key for signing. | - |\n| `HELIUS_API_KEY` | Your helius api key | - |\n| `LOG_LEVEL` | The level of logging you desire. | `info` |\n| `RPC_HTTPS` | The RPC HTTP URL to connect. | `https://api.mainnet-beta.solana.com/`|\n\n\n<br>\n\nInstall the program cli:\n\n```bash\nmake install\n```\n\n<br>\n\n---\n\n### Test the installation \n\n<br>\n\nYou can test the installation with:\n\n```bash\npoetry run pytest\n```\n\n```console\n====================================================================== test session starts =======================================================================\nplatform darwin -- Python 3.12.4, pytest-8.3.2, pluggy-1.5.0\nrootdir: XXX\nconfigfile: pyproject.toml\nplugins: order-1.2.1, anyio-4.4.0, ordering-0.6\ncollected 7 items \n\ntests/test_cli.py .... [ 57%]\ntests/test_server.py .. [ 85%]\ntests/test_aleph.py . [100%]\n\n======================================================================= 7 passed in 16.25s =======================================================================\n```\n\n<br>\n\n---\n\n### Running the CLI\n\n<br>\n\nYou can get information on the CLI commands by running:\n\n```bash\npoetry run mcli -h\n```\n\n```console\n 88 88 8b,dPPYba, ,adPPYYba, 8b,dPPYba, 88 \n 88 88 88P' \"Y8 \"\" `Y8 88P' `\"8a 88 \n 88 88 88 ,adPPPPP88 88 88 88 \n \"8a, ,a88 88 88, ,88 88 88 88 \n `\"YbbdP'Y8 88 `\"8bbdP\"Y8 88 88 88 \n\n\nAleph CLI: Urani MEV Agent.\n\noptions:\n -h, --help show this help message and exit\n -s Print info on the Solana blockchain.\n -a [AGENT], --agents [AGENT]\n Print info on the available agents or on specific [AGENT]\n -d [AGENT], --deploy [AGENT]\n Deploy a specific [AGENT].\n -l Print info on liquidity sources.\n -o Print info on the Oracles.\n\n```\n\n<br>\n\n----\n\n### Usage\n\n<br>\n\nThis first version of Aleph interacts with a local-server initialized by the user that mimics the Urani Protocol.\n\n<br>\n\nStart a local server:\n\n```bash\npoetry run start_server\n```\n\n<br>\n\nThis server can be visited at:\n\n```bash\nhttp://127.0.0.1:8000/\n```\n\n<br>\n\nOnce the server is running, you can deploy Aleph by running the CLI, adding the flag `--deploy` or `-d` and the string `aleph`:\n\n```bash\npoetry run mcli -d aleph\n\n# OR\n\npoetry run python ./src/main.py -d aleph\n```\n\n<br>\n\nThis will output: \n\n```console\n\n\n 88 88 8b,dPPYba, ,adPPYYba, 8b,dPPYba, 88 \n 88 88 88P' \"Y8 \"\" `Y8 88P' `\"8a 88 \n 88 88 88 ,adPPPPP88 88 88 88 \n \"8a, ,a88 88 88, ,88 88 88 88 \n `\"YbbdP'Y8 88 `\"8bbdP\"Y8 88 88 88 \n \nLoading environment variables...\n\n\ud83d\udef9 Deploying Agent Aleph ...\n Aleph is the first Urani MEV in-house agent.\n .Version: v0.1\n .Language: Python\n .Routing algorithm: Jupiter\n .P2P matches: Naive 1-hop\n .Partial fill: No\n .Ring trades: No\n\n --> Check the README to learn more about Aleph <--\n\n\ud83d\udef9 Starting Agent Aleph...\n\ud83d\udef9 Aleph is running...\n\ud83d\udef9 Fetching current batch from http://127.0.0.1:8000/batches\n\n\u23f3 Aleph is waiting for a valid batch ...\n```\n\n<br>\n\nThis means Aleph is waiting for a batch to be posted in the orderbook. \nTo post a valid batch in the orderbook, open a new terminal window and go into the folder `orders_templates`. \nPost post the `order_example.json` via:\n\n```@console\ncurl -X POST \"http://127.0.0.1:8000/batches\" -H \"Content-Type: application/json\" -d @example_batch.json\n```\n\n<br>\n\nNow look what Aleph does:\n\n```console \n\n\n 88 88 8b,dPPYba, ,adPPYYba, 8b,dPPYba, 88 \n 88 88 88P' \"Y8 \"\" `Y8 88P' `\"8a 88 \n 88 88 88 ,adPPPPP88 88 88 88 \n \"8a, ,a88 88 88, ,88 88 88 88 \n `\"YbbdP'Y8 88 `\"8bbdP\"Y8 88 88 88 \n\n \nLoading environment variables...\n\n\ud83d\udef9 Deploying Agent Aleph ...\n Aleph is the first Urani MEV in-house agent.\n .Version: v0.1\n .Language: Python\n .Routing algorithm: Jupiter\n .P2P matches: Naive 1-hop\n .Partial fill: No\n .Ring trades: No\n --> Check the README to learn more about Aleph <--\n\n\ud83d\udef9 Starting Agent Aleph...\n\ud83d\udef9 Aleph is running...\n\ud83d\udef9 Fetching current batch from http://127.0.0.1:8000/batches\n\u23f3 Aleph is waiting for a valid batch ...\n\ud83d\udef9 Aleph found a valid batch ...\n\ud83e\udd19 Aleph is solving the order...\n\n\u2699\ufe0f Searching for p2p matches ...\n\ud83e\udd19 Found p2p matches.\n\n\u2699\ufe0f Searching optimal execution path for 2 intents ...\n\ud83e\udd19 Sending solutions to http://127.0.0.1:8000/solutions\n\n\ud83d\udef9 Agent Aleph has finished\n```\n\n<br>\n\nYou can check the solutions by visiting: `http://127.0.0.1:8000/solutions`.\n\nIf you want to try with another batch, modify the template `orders_templates/order_example.json` as you wish and post it to the orderbook.\nThis will override the last batch.\n\nThen run again Aleph.\n\nWhen you are finished, stop the server with:\n\n```bash\npoetry run stop_server\n```\n\n<br>\n\n\n---\n\n### License and Contributing\n\n<br>\n\nThis project is distributed under the **[Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0)**. \n\nYou are welcome to contribute. See the guidelines **[here](.internal/CONTRIBUTING.md)**.\n\n<br>\n\n",
"bugtrack_url": null,
"license": "GPL-3.0 license",
"summary": "Aleph is Urani's Python in-house MEV agent, designed to take advantage of MEV opportunities on the Solana Blockchain through the Urani Protocol.",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4efdf4b6882145de943028dc70e82eee441981f183acfbf8112ec4758d6f4b18",
"md5": "546038793d69d0b26e52f346e1e23bad",
"sha256": "6296a53339c98cdbf8941cded80826266a4099995bd0622d0b24d6b053ba7333"
},
"downloads": -1,
"filename": "solana_mev_agent_py-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "546038793d69d0b26e52f346e1e23bad",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 3020512,
"upload_time": "2025-01-26T01:06:29",
"upload_time_iso_8601": "2025-01-26T01:06:29.808738Z",
"url": "https://files.pythonhosted.org/packages/4e/fd/f4b6882145de943028dc70e82eee441981f183acfbf8112ec4758d6f4b18/solana_mev_agent_py-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0f296d9d101c58074fd07e63d20cd7edd2ad76f53992d1ad8ca0028cfc9e64b7",
"md5": "d551532e1989728abccec3490acdc811",
"sha256": "86295adca464a1642882e4071ab0dc8916d6fff313aba6b4990f1fb6ee7990bc"
},
"downloads": -1,
"filename": "solana_mev_agent_py-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "d551532e1989728abccec3490acdc811",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 3008492,
"upload_time": "2025-01-26T01:06:33",
"upload_time_iso_8601": "2025-01-26T01:06:33.010069Z",
"url": "https://files.pythonhosted.org/packages/0f/29/6d9d101c58074fd07e63d20cd7edd2ad76f53992d1ad8ca0028cfc9e64b7/solana_mev_agent_py-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-26 01:06:33",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "solana-mev-agent-py"
}
