brawny 0.1.0__tar.gz

brawny-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: brawny
+Version: 0.1.0
+Summary: Block-driven Ethereum job/transaction execution framework
+Author-email: yearn <dev@yearn.fi>
+License: MIT
+Project-URL: Homepage, https://github.com/yearn/brawny
+Project-URL: Documentation, https://github.com/yearn/brawny#readme
+Project-URL: Repository, https://github.com/yearn/brawny.git
+Project-URL: Issues, https://github.com/yearn/brawny/issues
+Keywords: ethereum,web3,blockchain,jobs,transactions
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: web3<8.0,>=7.0
+Requires-Dist: click<9.0,>=8.1
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: python-dotenv<2.0,>=1.0
+Requires-Dist: structlog<25.0,>=24.1
+Requires-Dist: httpx<1.0,>=0.26
+Requires-Dist: psycopg[binary]<4.0,>=3.1
+Requires-Dist: psycopg-pool<4.0,>=3.2
+Requires-Dist: rich<14.0,>=13.0
+Requires-Dist: prometheus-client<1.0,>=0.20
+Requires-Dist: prompt_toolkit<4.0,>=3.0
+Requires-Dist: pygments<3.0,>=2.17
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio<1.0,>=0.23; extra == "dev"
+Requires-Dist: pytest-cov<5.0,>=4.1; extra == "dev"
+Requires-Dist: mypy<2.0,>=1.8; extra == "dev"
+Requires-Dist: ruff<1.0,>=0.2; extra == "dev"
+Requires-Dist: black<25.0,>=24.1; extra == "dev"
+Requires-Dist: pre-commit<4.0,>=3.6; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest<9.0,>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio<1.0,>=0.23; extra == "test"
+Requires-Dist: pytest-cov<5.0,>=4.1; extra == "test"
+
+# brawny
+
+Block-driven Ethereum job and transaction execution framework, inspired by [eth-brownie](https://github.com/eth-brownie/brownie).
+
+**Brownie-style ergonomics**: brawny mirrors Brownie's developer experience with familiar patterns—`accounts`, `Contract()`, `chain`, `history`, and an interactive console. If you've used Brownie, you'll feel right at home.
+
+## Installation (Local Development)
+
+```bash
+# Clone and install the framework
+git clone https://github.com/yearn/brawny.git
+cd brawny
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+# Create a new keeper project
+mkdir my-keeper && cd my-keeper
+brawny init
+
+# Install your project (brawny is already installed from above)
+pip install -e .
+
+# Configure
+cp .env.example .env
+# Edit .env: set RPC_URL and BRAWNY_KEYSTORE_PASSWORD_WORKER
+
+# Import a signer key (will prompt for password)
+brawny accounts import --name worker --private-key 0xYOUR_PRIVATE_KEY
+
+# Run
+brawny start
+```
+
+See `docs/quickstart.md` for a longer walkthrough.
+
+## Project Structure
+
+After `brawny init`, your project looks like:
+
+```
+my-keeper/
+├── my_keeper/              # Your Python package
+│   └── __init__.py
+├── jobs/
+│   ├── __init__.py
+│   └── _examples.py        # Reference implementations (not registered)
+├── interfaces/             # Place ABI JSON files here
+├── monitoring/             # Prometheus + Grafana stack
+│   ├── docker-compose.yml
+│   └── grafana/...
+├── pyproject.toml
+├── config.yaml
+├── .env.example
+├── .gitignore
+└── AGENTS.md               # AI agent guide for writing jobs
+```
+
+The `AGENTS.md` file contains a comprehensive guide for AI agents to generate correct, idiomatic jobs.
+
+## Minimal Job Example
+
+Create `jobs/harvester.py`:
+
+```python
+from brawny import Job, job, Contract, trigger, intent, block
+
+
+@job(signer="worker")
+class HarvestJob(Job):
+    name = "Harvest Example"
+    check_interval_blocks = 50
+    vault_address = "0xYourVault"
+
+    def check(self):
+        vault = Contract(self.vault_address)
+        pending = vault.pendingRewards()
+        if pending > 1_000_000_000_000_000_000:
+            return trigger(
+                reason="Harvest pending rewards",
+                data={"pending": pending},
+                idempotency_parts=[block.number // 50],
+            )
+        return None
+
+    def build_intent(self, trig):
+        vault = Contract(self.vault_address)
+        return intent(
+            signer_address=self._signer_name,
+            to_address=self.vault_address,
+            data=vault.harvest.encode_input(),
+            min_confirmations=2,
+        )
+
+    def alert_triggered(self, ctx):
+        return f"Harvest triggered: {ctx.trigger.data['pending'] / 1e18:.4f}"
+
+    def alert_confirmed(self, ctx):
+        return f"Harvest confirmed: {ctx.tx.hash}"
+```
+
+## Docs
+
+- `docs/quickstart.md`
+- `docs/cli.md`
+- `docs/job-lifecycle.md`
+- `docs/alerts.md`

brawny-0.1.0/README.md

@@ -0,0 +1,109 @@
+# brawny
+
+Block-driven Ethereum job and transaction execution framework, inspired by [eth-brownie](https://github.com/eth-brownie/brownie).
+
+**Brownie-style ergonomics**: brawny mirrors Brownie's developer experience with familiar patterns—`accounts`, `Contract()`, `chain`, `history`, and an interactive console. If you've used Brownie, you'll feel right at home.
+
+## Installation (Local Development)
+
+```bash
+# Clone and install the framework
+git clone https://github.com/yearn/brawny.git
+cd brawny
+pip install -e .
+```
+
+## Quick Start
+
+```bash
+# Create a new keeper project
+mkdir my-keeper && cd my-keeper
+brawny init
+
+# Install your project (brawny is already installed from above)
+pip install -e .
+
+# Configure
+cp .env.example .env
+# Edit .env: set RPC_URL and BRAWNY_KEYSTORE_PASSWORD_WORKER
+
+# Import a signer key (will prompt for password)
+brawny accounts import --name worker --private-key 0xYOUR_PRIVATE_KEY
+
+# Run
+brawny start
+```
+
+See `docs/quickstart.md` for a longer walkthrough.
+
+## Project Structure
+
+After `brawny init`, your project looks like:
+
+```
+my-keeper/
+├── my_keeper/              # Your Python package
+│   └── __init__.py
+├── jobs/
+│   ├── __init__.py
+│   └── _examples.py        # Reference implementations (not registered)
+├── interfaces/             # Place ABI JSON files here
+├── monitoring/             # Prometheus + Grafana stack
+│   ├── docker-compose.yml
+│   └── grafana/...
+├── pyproject.toml
+├── config.yaml
+├── .env.example
+├── .gitignore
+└── AGENTS.md               # AI agent guide for writing jobs
+```
+
+The `AGENTS.md` file contains a comprehensive guide for AI agents to generate correct, idiomatic jobs.
+
+## Minimal Job Example
+
+Create `jobs/harvester.py`:
+
+```python
+from brawny import Job, job, Contract, trigger, intent, block
+
+
+@job(signer="worker")
+class HarvestJob(Job):
+    name = "Harvest Example"
+    check_interval_blocks = 50
+    vault_address = "0xYourVault"
+
+    def check(self):
+        vault = Contract(self.vault_address)
+        pending = vault.pendingRewards()
+        if pending > 1_000_000_000_000_000_000:
+            return trigger(
+                reason="Harvest pending rewards",
+                data={"pending": pending},
+                idempotency_parts=[block.number // 50],
+            )
+        return None
+
+    def build_intent(self, trig):
+        vault = Contract(self.vault_address)
+        return intent(
+            signer_address=self._signer_name,
+            to_address=self.vault_address,
+            data=vault.harvest.encode_input(),
+            min_confirmations=2,
+        )
+
+    def alert_triggered(self, ctx):
+        return f"Harvest triggered: {ctx.trigger.data['pending'] / 1e18:.4f}"
+
+    def alert_confirmed(self, ctx):
+        return f"Harvest confirmed: {ctx.tx.hash}"
+```
+
+## Docs
+
+- `docs/quickstart.md`
+- `docs/cli.md`
+- `docs/job-lifecycle.md`
+- `docs/alerts.md`

brawny-0.1.0/pyproject.toml

@@ -0,0 +1,126 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "brawny"
+version = "0.1.0"
+description = "Block-driven Ethereum job/transaction execution framework"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "yearn", email = "dev@yearn.fi"}
+]
+keywords = ["ethereum", "web3", "blockchain", "jobs", "transactions"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "web3>=7.0,<8.0",
+    "click>=8.1,<9.0",
+    "pyyaml>=6.0,<7.0",
+    "python-dotenv>=1.0,<2.0",
+    "structlog>=24.1,<25.0",
+    "httpx>=0.26,<1.0",
+    "psycopg[binary]>=3.1,<4.0",
+    "psycopg-pool>=3.2,<4.0",
+    "rich>=13.0,<14.0",
+    "prometheus-client>=0.20,<1.0",
+    "prompt_toolkit>=3.0,<4.0",
+    "pygments>=2.17,<3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0,<9.0",
+    "pytest-asyncio>=0.23,<1.0",
+    "pytest-cov>=4.1,<5.0",
+    "mypy>=1.8,<2.0",
+    "ruff>=0.2,<1.0",
+    "black>=24.1,<25.0",
+    "pre-commit>=3.6,<4.0",
+]
+test = [
+    "pytest>=8.0,<9.0",
+    "pytest-asyncio>=0.23,<1.0",
+    "pytest-cov>=4.1,<5.0",
+]
+
+[project.scripts]
+brawny = "brawny.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/yearn/brawny"
+Documentation = "https://github.com/yearn/brawny#readme"
+Repository = "https://github.com/yearn/brawny.git"
+Issues = "https://github.com/yearn/brawny/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+brawny = ["py.typed", "db/migrations/*.sql"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+strict_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+show_error_codes = true
+exclude = ["tests/", "docs/"]
+
+[[tool.mypy.overrides]]
+module = ["web3.*", "eth_account.*", "hexbytes.*"]
+ignore_missing_imports = true
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # Pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "ARG",    # flake8-unused-arguments
+    "SIM",    # flake8-simplify
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+    "B008",   # do not perform function calls in argument defaults
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["brawny"]
+
+[tool.black]
+line-length = 100
+target-version = ["py310", "py311"]
+include = '\.pyi?$'

brawny-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

brawny-0.1.0/src/brawny/__init__.py

@@ -0,0 +1,104 @@
+"""
+brawny: Block-driven Ethereum job/transaction execution framework.
+
+This package provides a robust, production-ready framework for scheduling
+and executing Ethereum transactions based on block events.
+"""
+
+from brawny.jobs.base import Job
+from brawny.jobs.registry import registry, job
+from brawny.model.types import (
+    BlockInfo,
+    Trigger,
+    TxAttempt,
+    TxIntent,
+    TxIntentSpec,
+    to_wei,
+)
+from brawny.model.contexts import (
+    BlockContext,
+    CheckContext,
+    BuildContext,
+    AlertContext,
+)
+from brawny.model.events import DecodedEvent, find_event, events_by_name
+from brawny.telegram import telegram, get_telegram, TelegramBot
+from brawny.testing import job_context
+from brawny.interfaces import interface
+
+# Implicit context helpers (Flask-like pattern)
+from brawny.api import (
+    block,
+    ctx,       # Get current phase context (CheckContext or BuildContext)
+    trigger,
+    intent,
+    shorten,
+    explorer_link,
+    gas_ok,
+    gas_quote,
+    kv,        # Persistent KV store
+    rpc,       # RPC proxy (internal package renamed to _rpc to avoid collision)
+    get_address_from_alias,
+    Contract,  # Brownie-style
+    Wei,       # Brownie-style
+    web3,      # Brownie-style
+)
+
+# Brownie-style singletons for scripts
+from brawny.accounts import accounts, Account
+from brawny.history import history
+from brawny.chain import chain
+from brawny.networks import network
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "Job",
+    "job",
+    "registry",
+    "BlockInfo",
+    "Trigger",
+    "TxAttempt",
+    "TxIntent",
+    "TxIntentSpec",
+    "to_wei",
+    # Phase-specific contexts (OE7)
+    "BlockContext",
+    "CheckContext",
+    "BuildContext",
+    "AlertContext",
+    # Events
+    "DecodedEvent",
+    "find_event",
+    "events_by_name",
+    # Implicit context helpers
+    "block",
+    "ctx",
+    "trigger",
+    "intent",
+    "shorten",
+    "explorer_link",
+    "gas_ok",
+    "gas_quote",
+    "kv",
+    "rpc",
+    "get_address_from_alias",
+    # Brownie-style helpers
+    "Contract",
+    "Wei",
+    "web3",
+    # Brownie-style singletons
+    "accounts",
+    "Account",
+    "history",
+    "chain",
+    "network",
+    # Telegram
+    "telegram",
+    "get_telegram",
+    "TelegramBot",
+    # Testing
+    "job_context",
+    "interface",
+]