# Quick Start
Silverback lets you create and deploy your own Python bots that respond to on-chain events.
The Silverback library leverages the [Ape](https://docs.apeworx.io/ape/stable/userguides/quickstart) development framework as well as it's ecosystem of plugins and packages to enable you to develop simple-yet-sophisticated automated bots that can listen and respond to live chain data.
Silverback bots are excellent for use cases that involve continuously monitoring and responding to on-chain events, such as newly confirmed blocks or contract event logs.
Some examples of these types of bots:
- Monitoring new pool creations, and depositing liquidity
- Measuring trading activity of popular pools
- Listening for large swaps to update a telegram group
## Documentation
Please read the [development userguide](https://docs.apeworx.io/silverback/stable/userguides/development.html) for more information on how to develop a bot.
## Dependencies
- [python3](https://www.python.org/downloads) version 3.10 or greater, python3-dev
## Installation
Silverback relies heavily on the Ape development framework, so it's worth it to familarize yourself with how to install Ape and it's plugins using the [Ape installation userguide](https://docs.apeworx.io/ape/latest/userguides/quickstart#installation).
```{note}
It is suggested that you use a virtual environment of your choosing, and then install the Silverback package via one of the following options.
```
### via `pip`
You can install the latest release via [`pip`](https://pypi.org/project/pip/):
```bash
pip install silverback
```
### via `setuptools`
You can clone the repository and use [`setuptools`](https://github.com/pypa/setuptools) for the most up-to-date version:
```bash
git clone https://github.com/ApeWorX/silverback.git silverback
cd silverback
python3 setup.py install
```
## Quick Usage
Checkout [the example](https://github.com/ApeWorX/silverback/blob/main/example.py) to see how to use the library.
```{note}
The example makes use of the [Ape Tokens](https://github.com/ApeWorX/ape-tokens) plugin.
Be sure to properly configure your environment for the USDC and YFI tokens on Ethereum mainnet.
```
To run your bot against a live network, this SDK includes a simple bot command you can use via:
```sh
$ silverback run example --network :mainnet:alchemy
```
```{note}
This bot uses an in-memory task broker by default.
If you want to learn more about what that means, please visit the [development userguide](https://docs.apeworx.io/silverback/stable/userguides/development.html).
```
```{note}
It is suggested that you create a bots/ folder in the root of your project.
Silverback will automatically register files in this folder as separate bots that can be run via the `silverback run` command.
```
```{note}
It is also suggested that you treat this as a scripts folder, and do not include an __init__.py
If you have a complicated project, follow the previous example to ensure you run the bot correctly.
```
```{note}
A final suggestion would be to name your `SilverbackBot` object `bot`. Silverback automatically searches
for this object name when running. If you do not do so, once again, ensure you replace `example` with
`example:<name-of-object>` the previous example.
```
To auto-generate Dockerfiles for your bots, from the root of your project, you can run:
```bash
silverback build
```
This will place the generated dockerfiles in a special directory in the root of your project.
As an example, if you have a bots directory that looks like:
```
bots/
├── botA.py
├── botB.py
├── botC.py
```
This method will generate 3 Dockerfiles:
```
.silverback-images/
├── Dockerfile.botA
├── Dockerfile.botB
├── Dockerfile.botC
```
These Dockerfiles can be deployed with the `docker push` command documented in the next section so you can use it in cloud-based deployments.
```{note}
As an aside, if your bots/ directory is a python package, you will cause conflicts with the dockerfile generation feature. This method will warn you that you are generating bots for a python package, but will not stop you from doing so. If you choose to generate dockerfiles, the user should be aware that it will only copy each individual file into the Dockerfile, and will not include any supporting python functionality. Each python file is expected to run independently. If you require more complex bots, you will have to build a custom docker image.
```
## Docker Usage
```sh
$ docker run --volume $PWD:/home/harambe/project --volume ~/.tokenlists:/home/harambe/.tokenlists apeworx/silverback:latest run example --network :mainnet
```
```{note}
The Docker image we publish uses Python 3.11.
```
## Setting Up Your Environment
Running the `Quick Usage` and `Docker Usage` with the provided example will fail if you do not have a fully-configured environment.
Most common issues when using the SDK stem from the proper configuration of Ape plugins to unlock the behavior you desire.
You should use a provider that supports websockets to run silverback.
If you want to use a hosted provider with websocket support like Alchemy to run this example, you will need a Alchemy API key for Ethereum mainnet.
If you attempt to run the `Docker Usage` command without supplying this key, you will get the following error:
```bash
$ docker run --volume $PWD:/home/harambe/project --volume ~/.tokenlists:/home/harambe/.tokenlists apeworx/silverback:latest run example --network :mainnet:alchemy
Traceback (most recent call last):
...
ape_alchemy.exceptions.MissingProjectKeyError: Must set one of $WEB3_ALCHEMY_PROJECT_ID, $WEB3_ALCHEMY_API_KEY, $WEB3_ETHEREUM_MAINNET_ALCHEMY_PROJECT_ID, $WEB3_ETHEREUM_MAINNET_ALCHEMY_API_KEY.
```
Go to [Alchemy](https://alchemy.com), create an account, then create an bot in their dashboard, and copy the API Key.
Another requirement for the command from `Docker Usage` to run the given example is that it uses [ape-tokens](https://github.com/ApeWorX/ape-tokens) plugin to look up token interfaces by symbol.
In order for this to work, you should have installed and configured that plugin using a token list that includes both YFI and USDC on Ethereum mainnet.
Doing this will give you a `~/.tokenlists` hidden folder in your home folder that you must mount into the docker container with the following flag:
```bash
... --volume ~/.tokenlists:/home/harambe/.tokenlists ...
```
```{note}
It is suggested to install the 1inch tokenlist via `ape tokens install tokens.1inch.eth`.
See the [ape-tokens](https://github.com/ApeWorX/ape-tokens?tab=readme-ov-file#quick-usage) README for more information.
```
To check that both of the tokens exist in your configured tokenlist, you can execute this command:
```bash
$ ape tokens token-info YFI
Symbol: YFI
Name: yearn.finance
Chain ID: 1
Address: 0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e
Decimals: 18
$ ape tokens token-info USDC
Symbol: USDC
Name: Circle USD
Chain ID: 1
Address: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
Decimals: 6
```
```{note}
If you want, you can comment out the two functions `exec_event1` and `exec_event2` that handle the contract log events from these contracts if you do not have the configured tokenlist, then your command should work.
```
## Development
This project is under active development in preparation of the release of the [Silverback Platform](https://silverback.apeworx.io).
Things might not be in their final state and breaking changes may occur.
Comments, questions, criticisms and pull requests are welcomed.
See [Contributing](https://github.com/ApeWorX/silverback/blob/main/CONTRIBUTING.md) for more information.
Raw data
{
"_id": null,
"home_page": "https://github.com/ApeWorX/silverback",
"name": "silverback",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.10",
"maintainer_email": null,
"keywords": "ethereum",
"author": "ApeWorX Ltd.",
"author_email": "admin@apeworx.io",
"download_url": "https://files.pythonhosted.org/packages/9d/19/cfa885fbd453f936c400bcdc5bf43df46e0371b3862956d83adae75f98fb/silverback-0.6.5.tar.gz",
"platform": null,
"description": "# Quick Start\n\nSilverback lets you create and deploy your own Python bots that respond to on-chain events.\nThe Silverback library leverages the [Ape](https://docs.apeworx.io/ape/stable/userguides/quickstart) development framework as well as it's ecosystem of plugins and packages to enable you to develop simple-yet-sophisticated automated bots that can listen and respond to live chain data.\n\nSilverback bots are excellent for use cases that involve continuously monitoring and responding to on-chain events, such as newly confirmed blocks or contract event logs.\n\nSome examples of these types of bots:\n\n- Monitoring new pool creations, and depositing liquidity\n- Measuring trading activity of popular pools\n- Listening for large swaps to update a telegram group\n\n## Documentation\n\nPlease read the [development userguide](https://docs.apeworx.io/silverback/stable/userguides/development.html) for more information on how to develop a bot.\n\n## Dependencies\n\n- [python3](https://www.python.org/downloads) version 3.10 or greater, python3-dev\n\n## Installation\n\nSilverback relies heavily on the Ape development framework, so it's worth it to familarize yourself with how to install Ape and it's plugins using the [Ape installation userguide](https://docs.apeworx.io/ape/latest/userguides/quickstart#installation).\n\n```{note}\nIt is suggested that you use a virtual environment of your choosing, and then install the Silverback package via one of the following options.\n```\n\n### via `pip`\n\nYou can install the latest release via [`pip`](https://pypi.org/project/pip/):\n\n```bash\npip install silverback\n```\n\n### via `setuptools`\n\nYou can clone the repository and use [`setuptools`](https://github.com/pypa/setuptools) for the most up-to-date version:\n\n```bash\ngit clone https://github.com/ApeWorX/silverback.git silverback\ncd silverback\npython3 setup.py install\n```\n\n## Quick Usage\n\nCheckout [the example](https://github.com/ApeWorX/silverback/blob/main/example.py) to see how to use the library.\n\n```{note}\nThe example makes use of the [Ape Tokens](https://github.com/ApeWorX/ape-tokens) plugin.\nBe sure to properly configure your environment for the USDC and YFI tokens on Ethereum mainnet.\n```\n\nTo run your bot against a live network, this SDK includes a simple bot command you can use via:\n\n```sh\n$ silverback run example --network :mainnet:alchemy\n```\n\n```{note}\nThis bot uses an in-memory task broker by default.\nIf you want to learn more about what that means, please visit the [development userguide](https://docs.apeworx.io/silverback/stable/userguides/development.html).\n```\n\n```{note}\nIt is suggested that you create a bots/ folder in the root of your project.\nSilverback will automatically register files in this folder as separate bots that can be run via the `silverback run` command.\n```\n\n```{note}\nIt is also suggested that you treat this as a scripts folder, and do not include an __init__.py\nIf you have a complicated project, follow the previous example to ensure you run the bot correctly.\n```\n\n```{note}\nA final suggestion would be to name your `SilverbackBot` object `bot`. Silverback automatically searches \nfor this object name when running. If you do not do so, once again, ensure you replace `example` with \n`example:<name-of-object>` the previous example.\n```\n\nTo auto-generate Dockerfiles for your bots, from the root of your project, you can run:\n\n```bash\nsilverback build\n```\n\nThis will place the generated dockerfiles in a special directory in the root of your project.\n\nAs an example, if you have a bots directory that looks like:\n\n```\nbots/\n\u251c\u2500\u2500 botA.py\n\u251c\u2500\u2500 botB.py\n\u251c\u2500\u2500 botC.py\n```\n\nThis method will generate 3 Dockerfiles:\n\n```\n.silverback-images/\n\u251c\u2500\u2500 Dockerfile.botA\n\u251c\u2500\u2500 Dockerfile.botB\n\u251c\u2500\u2500 Dockerfile.botC\n```\n\nThese Dockerfiles can be deployed with the `docker push` command documented in the next section so you can use it in cloud-based deployments.\n\n```{note}\nAs an aside, if your bots/ directory is a python package, you will cause conflicts with the dockerfile generation feature. This method will warn you that you are generating bots for a python package, but will not stop you from doing so. If you choose to generate dockerfiles, the user should be aware that it will only copy each individual file into the Dockerfile, and will not include any supporting python functionality. Each python file is expected to run independently. If you require more complex bots, you will have to build a custom docker image.\n```\n\n## Docker Usage\n\n```sh\n$ docker run --volume $PWD:/home/harambe/project --volume ~/.tokenlists:/home/harambe/.tokenlists apeworx/silverback:latest run example --network :mainnet\n```\n\n```{note}\nThe Docker image we publish uses Python 3.11.\n```\n\n## Setting Up Your Environment\n\nRunning the `Quick Usage` and `Docker Usage` with the provided example will fail if you do not have a fully-configured environment.\nMost common issues when using the SDK stem from the proper configuration of Ape plugins to unlock the behavior you desire.\n\nYou should use a provider that supports websockets to run silverback.\nIf you want to use a hosted provider with websocket support like Alchemy to run this example, you will need a Alchemy API key for Ethereum mainnet.\nIf you attempt to run the `Docker Usage` command without supplying this key, you will get the following error:\n\n```bash\n$ docker run --volume $PWD:/home/harambe/project --volume ~/.tokenlists:/home/harambe/.tokenlists apeworx/silverback:latest run example --network :mainnet:alchemy\nTraceback (most recent call last):\n ...\nape_alchemy.exceptions.MissingProjectKeyError: Must set one of $WEB3_ALCHEMY_PROJECT_ID, $WEB3_ALCHEMY_API_KEY, $WEB3_ETHEREUM_MAINNET_ALCHEMY_PROJECT_ID, $WEB3_ETHEREUM_MAINNET_ALCHEMY_API_KEY.\n```\n\nGo to [Alchemy](https://alchemy.com), create an account, then create an bot in their dashboard, and copy the API Key.\n\nAnother requirement for the command from `Docker Usage` to run the given example is that it uses [ape-tokens](https://github.com/ApeWorX/ape-tokens) plugin to look up token interfaces by symbol.\nIn order for this to work, you should have installed and configured that plugin using a token list that includes both YFI and USDC on Ethereum mainnet.\nDoing this will give you a `~/.tokenlists` hidden folder in your home folder that you must mount into the docker container with the following flag:\n\n```bash\n... --volume ~/.tokenlists:/home/harambe/.tokenlists ...\n```\n\n```{note}\nIt is suggested to install the 1inch tokenlist via `ape tokens install tokens.1inch.eth`.\nSee the [ape-tokens](https://github.com/ApeWorX/ape-tokens?tab=readme-ov-file#quick-usage) README for more information.\n```\n\nTo check that both of the tokens exist in your configured tokenlist, you can execute this command:\n\n```bash\n$ ape tokens token-info YFI\n Symbol: YFI\n Name: yearn.finance\n Chain ID: 1\n Address: 0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e\n Decimals: 18\n\n$ ape tokens token-info USDC\n Symbol: USDC\n Name: Circle USD\n Chain ID: 1\n Address: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48\n Decimals: 6\n```\n\n```{note}\nIf you want, you can comment out the two functions `exec_event1` and `exec_event2` that handle the contract log events from these contracts if you do not have the configured tokenlist, then your command should work.\n```\n\n## Development\n\nThis project is under active development in preparation of the release of the [Silverback Platform](https://silverback.apeworx.io).\nThings might not be in their final state and breaking changes may occur.\nComments, questions, criticisms and pull requests are welcomed.\n\nSee [Contributing](https://github.com/ApeWorX/silverback/blob/main/CONTRIBUTING.md) for more information.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Ape SDK for the Silverback platform",
"version": "0.6.5",
"project_urls": {
"Homepage": "https://github.com/ApeWorX/silverback"
},
"split_keywords": [
"ethereum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "766fb2bb624a4d4851e47f846cd040350cd80117282e641f649ae2e65d0307ca",
"md5": "52451fdef1f76dfdfac512d724c0ebd2",
"sha256": "fb3f01cd8e33b335c050c4e43d0810daedf7f9043e7270c02eb5edc8e240b0dc"
},
"downloads": -1,
"filename": "silverback-0.6.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "52451fdef1f76dfdfac512d724c0ebd2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.10",
"size": 56876,
"upload_time": "2024-11-24T00:49:32",
"upload_time_iso_8601": "2024-11-24T00:49:32.933011Z",
"url": "https://files.pythonhosted.org/packages/76/6f/b2bb624a4d4851e47f846cd040350cd80117282e641f649ae2e65d0307ca/silverback-0.6.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9d19cfa885fbd453f936c400bcdc5bf43df46e0371b3862956d83adae75f98fb",
"md5": "01f9a1900bb27f915e1cc5da19c2db05",
"sha256": "3cecfb32d2296152f5d1e9b1135e6f86473c814319b1c7183ba0ad35cb02739c"
},
"downloads": -1,
"filename": "silverback-0.6.5.tar.gz",
"has_sig": false,
"md5_digest": "01f9a1900bb27f915e1cc5da19c2db05",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.10",
"size": 74597,
"upload_time": "2024-11-24T00:49:34",
"upload_time_iso_8601": "2024-11-24T00:49:34.886036Z",
"url": "https://files.pythonhosted.org/packages/9d/19/cfa885fbd453f936c400bcdc5bf43df46e0371b3862956d83adae75f98fb/silverback-0.6.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-24 00:49:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ApeWorX",
"github_project": "silverback",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "silverback"
}
JSON
