{"id":22060651,"url":"https://github.com/krutt/aesir","last_synced_at":"2025-07-24T01:31:49.391Z","repository":{"id":210186759,"uuid":"725944468","full_name":"krutt/aesir","owner":"krutt","description":"Command line interface used for setting up local regtest Bitcoin \u0026 Lightning cluster using Docker Daemon","archived":false,"fork":false,"pushed_at":"2024-11-27T12:13:08.000Z","size":6693,"stargazers_count":18,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-27T18:20:31.963Z","etag":null,"topics":["bitcoin","cashu","cashubtc","chaum","chaumian","devtools","docker","ecash","lightning","lightning-network","nutshell","ord","ordinals","runes"],"latest_commit_sha":null,"homepage":"","language":"Python","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/krutt.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":"2023-12-01T07:43:59.000Z","updated_at":"2024-11-27T12:13:12.000Z","dependencies_parsed_at":"2024-01-02T09:29:01.153Z","dependency_job_id":"99cdd782-2a1f-43bd-a23f-f6bd97a1ecf1","html_url":"https://github.com/krutt/aesir","commit_stats":null,"previous_names":["krutt/tranche","krutt/aesir"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krutt%2Faesir","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krutt%2Faesir/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krutt%2Faesir/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/krutt%2Faesir/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/krutt","download_url":"https://codeload.github.com/krutt/aesir/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227390910,"owners_count":17773034,"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":["bitcoin","cashu","cashubtc","chaum","chaumian","devtools","docker","ecash","lightning","lightning-network","nutshell","ord","ordinals","runes"],"created_at":"2024-11-30T18:01:31.907Z","updated_at":"2025-07-24T01:31:49.373Z","avatar_url":"https://github.com/krutt.png","language":"Python","funding_links":[],"categories":["Ecosystem"],"sub_categories":["Projects"],"readme":"# Aesir\n\n[![Bitcoin-only](https://img.shields.io/badge/bitcoin-only-FF9900?logo=bitcoin)](https://twentyone.world)\n[![LN](https://img.shields.io/badge/lightning-792EE5?logo=lightning)](https://mempool.space/lightning)\n[![Podman](https://img.shields.io/badge/podman-892CA0?\u0026logo=podman\u0026logoColor=white)](https://podman.io)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/krutt/aesir/blob/master/LICENSE)\n[![Top](https://img.shields.io/github/languages/top/krutt/aesir)](https://github.com/krutt/aesir)\n[![Languages](https://img.shields.io/github/languages/count/krutt/aesir)](https://github.com/krutt/aesir)\n[![Size](https://img.shields.io/github/repo-size/krutt/aesir)](https://github.com/krutt/aesir)\n[![Last commit](https://img.shields.io/github/last-commit/krutt/aesir/master)](https://github.com/krutt/aesir)\n\n[![Aesir banner](https://github.com/krutt/aesir/blob/master/static/aesir-banner.svg)](static/aesir-banner.svg)\n\n## Prerequisites\n\n* python (3.9+)\n* pip\n* podman\n\n## Getting started\n\nYou can use `aesir` simply by installing via `pip` on your Terminal.\n\n```sh\npip install aesir\n```\n\nAnd then you can begin deploying local cluster as such:\n\n```sh\naesir deploy\n```\n\nThe initial deployment may take some time at pulling required images from their respective\nrepositories. Results may look as such:\n\n```sh\n$ pip install aesir\n\u003e ...\n\u003e Installing collected packages: aesir\n\u003e Successfully installed aesir-0.4.3\n$ aesir deploy\n\u003e Deploy specified local cluster:            ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:01\n\u003e Generate addresses:                        ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00\n\u003e Mine initial capital for parties:          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00\n```\n\nYou will have podman containers running in the backend, ready to be interfaced by your local\nenvironment applications you are developing.\n\n## Begin local mining\n\nIn order to properly test many functionalities, you will need to send mining commands to local\nsetup. You can achieve completely local and running environment with the following command:\n\n[![Demonstration](static/demo.gif)](https://github.com/krutt/aesir/blob/master/static/demo.gif)\n\n### Cluster types\n\nCurrently there are two supported cluster-types in this project. Specified by flags,\n`--duo` (default), or `--cat`, `--ohm`, `--uno` with the following set-up:\n\n| Type | Description                                                                |\n| ---- | -------------------------------------------------------------------------- |\n|  cat | Customized `aesir-bitcoind-cat` node that has OP_CAT enabled for experiments |\n|  duo | Contains two LND nodes named `aesir-ping` and `aesir-pong` unified by \u003cbr\u003e one single `aesir-bitcoind` service. |\n|  ohm | Only has `aesir-bitcoind` without any Lightning nodes. |\n|  uno | Only has one LND node named `aesir-lnd` connected to `aesir-bitcoind`. |\n\n### Peripheral containers\n\nThis project also helps you setup peripheral services to make development process easier, too.\nFor example, if you want to deploy a duo-cluster with attached postgres database, run the following:\n\n```sh\n$ aesir deploy --with-postgres\n\u003e ...\n$ aesir mine\n\u003e ╭───── containers ─────╮┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┓\n\u003e │ aesir-postgres       │┃ Name          ┃ Nodekey      ┃ Channels  ┃ Peers  ┃ Height ┃ Synced? ┃\n\u003e │ aesir-pong           │┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━━┩\n\u003e │ aesir-ping           ││ aesir-pong    │ 3da33d3eb12  │ 2         │ 1      │ 216    │    true │\n\u003e │ aesir-bitcoind       ││               │ deacf4e1a64  │           │        │        │         │\n\u003e │ ...                  ││ ...           │ ...          │ ...       │ ...    │ ...    │ ...     │\n```\n\nOr run an uno-cluster with both attached postgres database and redis solid store cache like this:\n\n```sh\n$ aesir deploy --uno --with-postgres --with-redis\n\u003e ...\n$ aesir mine\n\u003e ╭───── containers ─────╮┏━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┓\n\u003e │ aesir-postgres       │┃ Name          ┃ Nodekey      ┃ Channels  ┃ Peers  ┃ Height ┃ Synced? ┃\n\u003e │ aesir-redis          │┡━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━╇━━━━━━━━━┩\n\u003e │ aesir-lnd            ││ aesir-lnd     │ c0ae6b158d0  │ 0         │ 0      │ 202    │    true │\n\u003e │ aesir-bitcoind       ││               │ 4194459b8f3  │           │        │        │         │\n\u003e │ ...                  ││ ...           │ ...          │ ...       │ ...    │ ...    │ ...     │\n```\n\n## Cleanup\n\nUse the following command to clean up active `aesir-*` containers:\n\n```sh\naesir clean\n```\n\n🚧  This will resets the current test state, so use with care. Example below:\n\n```sh\n$ aesir clean\n\u003e Remove active containers:                  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:01\n```\n\n## Change-logs\n\n* **0.3.1** Add `aesir-cashu-mint` \u0026 `aesir-lnd-krub` image setups and deployments w/ shared volumes\n* **0.3.2** Define classifiers on `pyproject.toml` for PyPI metadata\n* **0.3.3** Drop `black` and use [ruff](https://github.com/astral-sh/ruff) formatter and linter\n* **0.3.4** Simplify deployment workflows and \n* **0.3.5** Restructure project so that when installed, `src` folder will not be created\n* **0.3.6** Breakdown \"setup\" command into \"build\" and \"pull\"\n* **0.3.7** Lightning cluster now with [ord](https://github.com/ordinals/ord)\n* **0.3.8** Rename \"ord\" to \"ord-server\" to avoid confusion with cli\n* **0.3.9** Remove intermediate containers\n* **0.4.0** Resist electricity with \"ohm\" mode\n* **0.4.1** Remove Ordinals' spiked ball\n* **0.4.2** Disable bitcoind prune mode\n* **0.4.3** Implement dashboard walkthrough using [blessed](https://github.com/chj/blessed)\n* **0.4.4** Add `cat` cluster in deployment and `--bitcoind-cat` flag for customized build\n* **0.4.5** The Yggdrasil update where docker build logs are chunked for display\n* **0.4.6** Create default wallet if no lnd containers\n* **0.4.7** (reverted) Remove unittesting from image build process\n* **0.4.8** Follow [Productivity Notes](https://github.com/bitcoin/bitcoin/blob/master/doc/productivity.md) for `bitcoind-cat`; Fix progress bar overlap.\n* **0.4.9** Change package manager and add `invoice` command\n* **0.5.0** Adopt podman to encourage daemonlessness and rootlessness\n* **0.5.1** Drop podman support for unstable SSH connections, viva Docker\n* **0.5.2** Stricten type definitions and fix undefined/attribute bugs\n* **0.5.3** Define `aesir-bitcoind` and `aesir-lnd` build instructions. Decouple from Polar's\n\n## Roadmap\n\n* Simplify `schemas.yml` and embed commands to service definitions\n* Drop `docker-py` and replace with `podman-py` (rolled back and on hold)\n* Write [click](https://click.palletsprojects.com) tests.\n* Add `aesir-tesla-ball` peripheral service using [tesla-ball](https://github.com/krutt/tesla-ball)\n* Use [joblib](https://github.com/joblib/joblib) to speed up deployment with parallelization.\n* Create and add some type of `ordapi` peripheral service.\n\n## Contributions\n\n### Prerequisites\n\n* [pyenv](https://github.com/pyenv/pyenv) - simple Python version management\n* [uv](https://docs.astral.sh/uv) - extremely fast Python package \u0026 project manager written in Rust\n\n### Set up local environment\n\nThe following guide walks through setting up your local working environment using `pyenv`\nas Python version manager and `uv` as Python package manager. If you do not have `pyenv`\ninstalled, run the following command.\n\n\u003cdetails\u003e\n  \u003csummary\u003e Install using Homebrew (Darwin) \u003c/summary\u003e\n  \n  ```sh\n  brew install pyenv --head\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e Install using standalone installer (Darwin and Linux) \u003c/summary\u003e\n  \n  ```sh\n  curl https://pyenv.run | bash\n  ```\n\u003c/details\u003e\n\nIf you do not have `uv` installed, run the following command.\n\n\u003cdetails\u003e\n  \u003csummary\u003e Install using Homebrew (Darwin) \u003c/summary\u003e\n\n  ```sh\n  brew install uv\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e Install using standalone installer (Darwin and Linux) \u003c/summary\u003e\n\n  ```sh\n  curl -LsSf https://astral.sh/uv/install.sh | sh\n  ```\n\u003c/details\u003e\n\n\nOnce you have `pyenv` Python version manager installed, you can\ninstall any version of Python above version 3.9 for this project.\nThe following commands help you set up and activate a Python virtual\nenvironment where `uv` can download project dependencies from the `PyPI`\nopen-sourced registry defined under `pyproject.toml` file.\n\n\u003cdetails\u003e\n  \u003csummary\u003e Set up environment and synchroniz project dependencies \u003c/summary\u003e\n\n  ```sh\n  pyenv shell 3.11.9\n  uv venv  --python-preference system\n  source .venv/bin/activate\n  uv sync --dev\n  ```\n\u003c/details\u003e\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrutt%2Faesir","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkrutt%2Faesir","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkrutt%2Faesir/lists"}