tinybot-eth 0.1.0__tar.gz

tinybot_eth-0.1.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: tinybot-eth
+Version: 0.1.0
+Summary: Minimal Python framework for building crypto bots
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: web3==7.14.1
+Requires-Dist: eth-abi==5.2.0
+Requires-Dist: eth-account==0.13.7
+Requires-Dist: python-telegram-bot==22.7
+
+# tinybot
+
+Minimal Python framework for building crypto bots.
+
+## Installation
+
+```bash
+pip install tinybot-eth
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `BOT_ACCESS_TOKEN` | Yes | Telegram bot token |
+| `GROUP_CHAT_ID` | Yes | Telegram group for notifications |
+| `DEV_GROUP_CHAT_ID` | Yes | Telegram group for errors and startup |
+| `PRIVATE_KEY` | No | Private key for onchain execution |
+
+## Quick Start
+
+```python
+import asyncio
+import os
+from tinybot import TinyBot, multicall, notify_group_chat
+
+ERC20_ABI = [...]
+STRATEGY_ABI = [...]
+
+async def on_transfer(bot, log):
+    print(f"{log.args.sender} -> {log.args.receiver}: {log.args.value}")
+    await notify_group_chat(f"Transfer from {log.args.sender}")
+
+async def check_and_tend(bot):
+    strategy = bot.w3.eth.contract(address="0x...", abi=STRATEGY_ABI)
+    needs_tend, _ = strategy.functions.tendTrigger().call()
+    if needs_tend:
+        tx_hash = bot.executor.execute(
+            strategy.functions.tend(),
+            gas_limit=5_000_000,
+        )
+        await notify_group_chat(f"Tend submitted: {tx_hash}")
+
+async def main():
+    bot = TinyBot(
+        rpc_url=os.environ["RPC_URL"],
+        name="my bot",
+        private_key=os.environ.get("PRIVATE_KEY", ""),
+    )
+
+    bot.listen(
+        name="transfers",
+        event="Transfer",
+        addresses=["0x..."],
+        abi=ERC20_ABI,
+        handler=on_transfer,
+        poll_interval=180,
+        notify_errors=True,
+    )
+
+    bot.every(3600, check_and_tend, notify_errors=True)
+
+    await bot.run()
+
+asyncio.run(main())
+```
+
+## API
+
+### `TinyBot(rpc_url, name="tinybot", private_key="")`
+
+Creates a bot instance.
+
+- `bot.w3` — `web3.Web3` instance
+- `bot.state` — `State` instance (see below)
+- `bot.executor` — `Executor` instance if `private_key` is provided, else `None`
+- `bot.name` — used in logs and Telegram startup message
+
+On `run()`, sends a startup message to `DEV_GROUP_CHAT_ID` and prints a polling heartbeat every tick.
+
+---
+
+### `bot.listen(...) -> EventListener`
+
+Register an event listener.
+
+```python
+bot.listen(
+    name="kicks",            # unique name
+    event="AuctionKicked",   # event name (must exist in ABI)
+    addresses=["0x..."],     # contracts to monitor
+    abi=[...],               # ABI containing the event
+    handler=on_kick,         # async fn(bot, log)
+    poll_interval=180,       # seconds between polls (default: 180)
+    block_buffer=5,          # re-scan buffer in blocks (default: 5)
+    notify_errors=True,      # send errors to Telegram (default: False)
+)
+```
+
+The event signature is derived from the ABI at registration time. Raises `ValueError` if:
+- Event not found in ABI
+- Duplicate listener name
+- Empty addresses
+
+---
+
+### `bot.every(interval, handler, name="", notify_errors=False) -> PeriodicTask`
+
+Register a periodic task.
+
+```python
+bot.every(3600, check_expired, notify_errors=True)
+```
+
+Handler signature: `async fn(bot)`
+
+---
+
+### `bot.get_listener(name) -> EventListener`
+
+Get a registered listener by name. Raises `ValueError` if not found.
+
+---
+
+### `bot.replay(name, from_block, to_block)`
+
+Replay historical events through a listener's handler. Useful for testing with real chain data.
+
+```python
+await bot.replay("kicks", from_block=21000000, to_block=21000500)
+```
+
+---
+
+### `bot.run(tick=10)`
+
+Start the polling loop. `tick` (default: 10s) is the inner loop sleep. Each listener and task fires at its own interval.
+
+---
+
+### `EventListener`
+
+Returned by `bot.listen()`.
+
+- `listener.add_address(address)` — add a contract address at runtime
+- `listener.remove_address(address)` — remove a contract address at runtime
+
+Both handle checksumming and dedup.
+
+---
+
+### `Executor`
+
+Available via `bot.executor` when `private_key` is provided.
+
+```python
+bot = TinyBot(rpc_url, name="my bot", private_key=os.environ["PRIVATE_KEY"])
+
+tx_hash = bot.executor.execute(
+    contract.functions.tend(strategy_addr),
+    gas_limit=5_000_000,
+    max_fee_gwei=100,
+    max_priority_fee_gwei=3,
+)
+```
+
+- `executor.address` — signer address
+- `executor.balance` — signer ETH balance in wei
+- `executor.execute(call, ...)` — sign and broadcast a transaction, returns tx hash immediately (fire and forget)
+
+---
+
+### `State`
+
+In-memory state, available via `bot.state`.
+
+- `state.last_block` — `dict[str, int]` mapping names to last processed block
+- `state.active_items` — `list` of tracked items (e.g. address pairs)
+- `state.add_item(*addrs)` — add an item (deduped)
+- `state.remove_item(item)` — remove an item
+- `state.is_processed(event_id)` — check if event was processed
+- `state.mark_processed(event_id)` — mark event as processed (handled automatically for listeners)
+
+---
+
+### `multicall(w3, calls) -> list`
+
+Batch contract reads via [Multicall3](https://github.com/mds1/multicall).
+
+```python
+symbol, decimals = multicall(bot.w3, [
+    token.functions.symbol(),
+    token.functions.decimals(),
+])
+```
+
+---
+
+### `notify_group_chat(text, parse_mode="HTML", chat_id=GROUP_CHAT_ID)`
+
+Send a Telegram message. HTML parse mode by default.
+
+---
+
+### `event_id(log) -> str`
+
+Unique ID from a log (`txHash:logIndex`). Used internally for dedup, also available for custom event processing in periodic tasks.
+
+## Handler Signatures
+
+```python
+# Event handler
+async def on_event(bot: TinyBot, log) -> None: ...
+
+# Task handler
+async def my_task(bot: TinyBot) -> None: ...
+```
+
+Access `bot.w3`, `bot.state`, `bot.executor`, and `bot.get_listener()` from any handler.
+
+## Error Handling
+
+When `notify_errors=True`, exceptions are caught and sent to `DEV_GROUP_CHAT_ID` as `[name] error message`. The bot continues running.

tinybot_eth-0.1.0/README.md

@@ -0,0 +1,223 @@
+# tinybot
+
+Minimal Python framework for building crypto bots.
+
+## Installation
+
+```bash
+pip install tinybot-eth
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `BOT_ACCESS_TOKEN` | Yes | Telegram bot token |
+| `GROUP_CHAT_ID` | Yes | Telegram group for notifications |
+| `DEV_GROUP_CHAT_ID` | Yes | Telegram group for errors and startup |
+| `PRIVATE_KEY` | No | Private key for onchain execution |
+
+## Quick Start
+
+```python
+import asyncio
+import os
+from tinybot import TinyBot, multicall, notify_group_chat
+
+ERC20_ABI = [...]
+STRATEGY_ABI = [...]
+
+async def on_transfer(bot, log):
+    print(f"{log.args.sender} -> {log.args.receiver}: {log.args.value}")
+    await notify_group_chat(f"Transfer from {log.args.sender}")
+
+async def check_and_tend(bot):
+    strategy = bot.w3.eth.contract(address="0x...", abi=STRATEGY_ABI)
+    needs_tend, _ = strategy.functions.tendTrigger().call()
+    if needs_tend:
+        tx_hash = bot.executor.execute(
+            strategy.functions.tend(),
+            gas_limit=5_000_000,
+        )
+        await notify_group_chat(f"Tend submitted: {tx_hash}")
+
+async def main():
+    bot = TinyBot(
+        rpc_url=os.environ["RPC_URL"],
+        name="my bot",
+        private_key=os.environ.get("PRIVATE_KEY", ""),
+    )
+
+    bot.listen(
+        name="transfers",
+        event="Transfer",
+        addresses=["0x..."],
+        abi=ERC20_ABI,
+        handler=on_transfer,
+        poll_interval=180,
+        notify_errors=True,
+    )
+
+    bot.every(3600, check_and_tend, notify_errors=True)
+
+    await bot.run()
+
+asyncio.run(main())
+```
+
+## API
+
+### `TinyBot(rpc_url, name="tinybot", private_key="")`
+
+Creates a bot instance.
+
+- `bot.w3` — `web3.Web3` instance
+- `bot.state` — `State` instance (see below)
+- `bot.executor` — `Executor` instance if `private_key` is provided, else `None`
+- `bot.name` — used in logs and Telegram startup message
+
+On `run()`, sends a startup message to `DEV_GROUP_CHAT_ID` and prints a polling heartbeat every tick.
+
+---
+
+### `bot.listen(...) -> EventListener`
+
+Register an event listener.
+
+```python
+bot.listen(
+    name="kicks",            # unique name
+    event="AuctionKicked",   # event name (must exist in ABI)
+    addresses=["0x..."],     # contracts to monitor
+    abi=[...],               # ABI containing the event
+    handler=on_kick,         # async fn(bot, log)
+    poll_interval=180,       # seconds between polls (default: 180)
+    block_buffer=5,          # re-scan buffer in blocks (default: 5)
+    notify_errors=True,      # send errors to Telegram (default: False)
+)
+```
+
+The event signature is derived from the ABI at registration time. Raises `ValueError` if:
+- Event not found in ABI
+- Duplicate listener name
+- Empty addresses
+
+---
+
+### `bot.every(interval, handler, name="", notify_errors=False) -> PeriodicTask`
+
+Register a periodic task.
+
+```python
+bot.every(3600, check_expired, notify_errors=True)
+```
+
+Handler signature: `async fn(bot)`
+
+---
+
+### `bot.get_listener(name) -> EventListener`
+
+Get a registered listener by name. Raises `ValueError` if not found.
+
+---
+
+### `bot.replay(name, from_block, to_block)`
+
+Replay historical events through a listener's handler. Useful for testing with real chain data.
+
+```python
+await bot.replay("kicks", from_block=21000000, to_block=21000500)
+```
+
+---
+
+### `bot.run(tick=10)`
+
+Start the polling loop. `tick` (default: 10s) is the inner loop sleep. Each listener and task fires at its own interval.
+
+---
+
+### `EventListener`
+
+Returned by `bot.listen()`.
+
+- `listener.add_address(address)` — add a contract address at runtime
+- `listener.remove_address(address)` — remove a contract address at runtime
+
+Both handle checksumming and dedup.
+
+---
+
+### `Executor`
+
+Available via `bot.executor` when `private_key` is provided.
+
+```python
+bot = TinyBot(rpc_url, name="my bot", private_key=os.environ["PRIVATE_KEY"])
+
+tx_hash = bot.executor.execute(
+    contract.functions.tend(strategy_addr),
+    gas_limit=5_000_000,
+    max_fee_gwei=100,
+    max_priority_fee_gwei=3,
+)
+```
+
+- `executor.address` — signer address
+- `executor.balance` — signer ETH balance in wei
+- `executor.execute(call, ...)` — sign and broadcast a transaction, returns tx hash immediately (fire and forget)
+
+---
+
+### `State`
+
+In-memory state, available via `bot.state`.
+
+- `state.last_block` — `dict[str, int]` mapping names to last processed block
+- `state.active_items` — `list` of tracked items (e.g. address pairs)
+- `state.add_item(*addrs)` — add an item (deduped)
+- `state.remove_item(item)` — remove an item
+- `state.is_processed(event_id)` — check if event was processed
+- `state.mark_processed(event_id)` — mark event as processed (handled automatically for listeners)
+
+---
+
+### `multicall(w3, calls) -> list`
+
+Batch contract reads via [Multicall3](https://github.com/mds1/multicall).
+
+```python
+symbol, decimals = multicall(bot.w3, [
+    token.functions.symbol(),
+    token.functions.decimals(),
+])
+```
+
+---
+
+### `notify_group_chat(text, parse_mode="HTML", chat_id=GROUP_CHAT_ID)`
+
+Send a Telegram message. HTML parse mode by default.
+
+---
+
+### `event_id(log) -> str`
+
+Unique ID from a log (`txHash:logIndex`). Used internally for dedup, also available for custom event processing in periodic tasks.
+
+## Handler Signatures
+
+```python
+# Event handler
+async def on_event(bot: TinyBot, log) -> None: ...
+
+# Task handler
+async def my_task(bot: TinyBot) -> None: ...
+```
+
+Access `bot.w3`, `bot.state`, `bot.executor`, and `bot.get_listener()` from any handler.
+
+## Error Handling
+
+When `notify_errors=True`, exceptions are caught and sent to `DEV_GROUP_CHAT_ID` as `[name] error message`. The bot continues running.

tinybot_eth-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "tinybot-eth"
+version = "0.1.0"
+description = "Minimal Python framework for building crypto bots"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "web3==7.14.1",
+    "eth-abi==5.2.0",
+    "eth-account==0.13.7",
+    "python-telegram-bot==22.7",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["tinybot*"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+lint.select = ["E", "F", "I", "W"]
+fix = true
+lint.ignore = ['E501']
+
+[tool.ruff.format]
+quote-style = "double"
+docstring-code-format = true
+
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"

tinybot_eth-0.1.0/setup.cfg

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

tinybot_eth-0.1.0/tinybot/__init__.py

@@ -0,0 +1,14 @@
+from tinybot.bot import TinyBot
+from tinybot.executor import Executor
+from tinybot.multicall import multicall
+from tinybot.tg import DEV_GROUP_CHAT_ID, notify_group_chat
+from tinybot.utils import event_id
+
+__all__ = [
+    "Executor",
+    "TinyBot",
+    "DEV_GROUP_CHAT_ID",
+    "event_id",
+    "multicall",
+    "notify_group_chat",
+]

tinybot_eth-0.1.0/tinybot/bot.py

@@ -0,0 +1,173 @@
+import asyncio
+import time
+from datetime import datetime
+from typing import Any
+
+from web3 import Web3
+
+from tinybot.executor import Executor
+from tinybot.state import State
+from tinybot.tg import DEV_GROUP_CHAT_ID, notify_group_chat
+from tinybot.types import EventHandler, EventListener, PeriodicTask, TaskHandler
+from tinybot.utils import event_id, event_signature
+
+
+class TinyBot:
+    def __init__(self, rpc_url: str, name: str = "tinybot", private_key: str = ""):
+        self.w3 = Web3(Web3.HTTPProvider(rpc_url))
+        self.name = name
+        self.state = State()
+        self.executor = Executor(self.w3, private_key) if private_key else None
+        self._listeners: list[EventListener] = []
+        self._tasks: list[PeriodicTask] = []
+
+    # -------------------------------------------------------------------------
+    # Registration
+    # -------------------------------------------------------------------------
+
+    def listen(
+        self,
+        name: str,
+        event: str,
+        addresses: list[str],
+        abi: list[dict[str, Any]],
+        handler: EventHandler,
+        poll_interval: int = 180,
+        block_buffer: int = 5,
+        notify_errors: bool = False,
+    ) -> EventListener:
+        if not addresses:
+            raise ValueError(f"listener '{name}': addresses cannot be empty")
+        if any(l.name == name for l in self._listeners):
+            raise ValueError(f"listener '{name}' already registered")
+
+        signature = event_signature(abi, event)
+
+        listener = EventListener(
+            name=name,
+            signature=signature,
+            addresses=[self.w3.to_checksum_address(a) for a in addresses],
+            abi=abi,
+            handler=handler,
+            poll_interval=poll_interval,
+            block_buffer=block_buffer,
+            notify_errors=notify_errors,
+            _w3=self.w3,
+        )
+        self._listeners.append(listener)
+        return listener
+
+    def every(
+        self,
+        interval: int,
+        handler: TaskHandler,
+        name: str = "",
+        notify_errors: bool = False,
+    ) -> PeriodicTask:
+        task = PeriodicTask(
+            name=name or handler.__name__,
+            interval=interval,
+            handler=handler,
+            notify_errors=notify_errors,
+        )
+        self._tasks.append(task)
+        return task
+
+    # -------------------------------------------------------------------------
+    # Getters
+    # -------------------------------------------------------------------------
+
+    def get_listener(self, name: str) -> EventListener:
+        for l in self._listeners:
+            if l.name == name:
+                return l
+        raise ValueError(f"listener '{name}' not found")
+
+    # -------------------------------------------------------------------------
+    # Replay
+    # -------------------------------------------------------------------------
+
+    async def replay(self, name: str, from_block: int, to_block: int) -> None:
+        listener = self.get_listener(name)
+        print(f"[{self.name}] replaying '{name}' from {from_block} to {to_block}...")
+        await self._process_logs(listener, from_block, to_block)
+        print(f"[{self.name}] replay '{name}' done")
+
+    # -------------------------------------------------------------------------
+    # Polling
+    # -------------------------------------------------------------------------
+
+    async def _handle_error(self, e: Exception, name: str, notify: bool) -> None:
+        print(f"[{name}] error: {e}")
+        if notify:
+            await notify_group_chat(f"❌ [{name}] {e}", chat_id=DEV_GROUP_CHAT_ID)
+
+    async def _process_logs(self, listener: EventListener, from_block: int, to_block: int) -> None:
+        topic = self.w3.keccak(text=listener.signature)
+        decoder = self.w3.eth.contract(address=listener.addresses[0], abi=listener.abi)
+        event_name = listener.signature.split("(")[0]
+
+        raw_logs = self.w3.eth.get_logs({
+            "fromBlock": from_block,
+            "toBlock": to_block,
+            "address": listener.addresses,
+            "topics": [topic],
+        })
+
+        for raw_log in raw_logs:
+            event = getattr(decoder.events, event_name)()
+            log = event.process_log(raw_log)
+            eid = event_id(log)
+            if self.state.is_processed(eid):
+                continue
+            await listener.handler(self, log)
+            self.state.mark_processed(eid)
+
+    async def _poll_listener(self, listener: EventListener) -> None:
+        now = time.time()
+        if now - listener._last_run < listener.poll_interval:
+            return
+        listener._last_run = now
+
+        try:
+            current_block: int = self.w3.eth.block_number
+            last = self.state.last_block.get(listener.name, 0)
+            from_block = last - listener.block_buffer if last else current_block
+
+            if from_block >= current_block:
+                self.state.last_block[listener.name] = current_block
+                return
+
+            await self._process_logs(listener, from_block, current_block)
+            self.state.last_block[listener.name] = current_block
+        except Exception as e:
+            await self._handle_error(e, listener.name, listener.notify_errors)
+
+    async def _poll_task(self, task: PeriodicTask) -> None:
+        now = time.time()
+        if now - task._last_run < task.interval:
+            return
+        task._last_run = now
+
+        try:
+            await task.handler(self)
+        except Exception as e:
+            await self._handle_error(e, task.name, task.notify_errors)
+
+    # -------------------------------------------------------------------------
+    # Run
+    # -------------------------------------------------------------------------
+
+    async def run(self, tick: int = 10) -> None:
+        await notify_group_chat(
+            f"🟢 <b>{self.name} started</b>",
+            chat_id=DEV_GROUP_CHAT_ID,
+        )
+
+        while True:
+            print(f"[{self.name}] polling... {datetime.now()}")
+            for listener in self._listeners:
+                await self._poll_listener(listener)
+            for task in self._tasks:
+                await self._poll_task(task)
+            await asyncio.sleep(tick)

tinybot_eth-0.1.0/tinybot/executor.py

@@ -0,0 +1,37 @@
+from web3 import Web3
+from eth_account import Account
+from eth_account.signers.local import LocalAccount
+
+
+class Executor:
+    def __init__(self, w3: Web3, private_key: str):
+        self._w3 = w3
+        self._account: LocalAccount = Account.from_key(private_key)
+
+    @property
+    def address(self) -> str:
+        return self._account.address
+
+    @property
+    def balance(self) -> int:
+        return self._w3.eth.get_balance(self._account.address)
+
+    def execute(
+        self,
+        call,
+        gas_limit: int = 500_000,
+        max_fee_gwei: int = 100,
+        max_priority_fee_gwei: int = 3,
+        value: int = 0,
+    ) -> str:
+        tx = call.build_transaction({
+            "from": self._account.address,
+            "nonce": self._w3.eth.get_transaction_count(self._account.address),
+            "gas": gas_limit,
+            "maxFeePerGas": self._w3.to_wei(max_fee_gwei, "gwei"),
+            "maxPriorityFeePerGas": self._w3.to_wei(max_priority_fee_gwei, "gwei"),
+            "value": value,
+        })
+        signed = self._w3.eth.account.sign_transaction(tx, self._account.key)
+        tx_hash = self._w3.eth.send_raw_transaction(signed.raw_transaction)
+        return tx_hash.hex()

tinybot_eth-0.1.0/tinybot/multicall.py

@@ -0,0 +1,32 @@
+from eth_abi import decode as decode_abi
+from web3 import Web3
+
+# Multicall3 — same address on all chains
+MULTICALL3 = Web3.to_checksum_address("0xcA11bde05977b3631167028862bE2a173976CA11")
+MULTICALL3_ABI = [{
+    "name": "aggregate3",
+    "type": "function",
+    "stateMutability": "payable",
+    "inputs": [{"name": "calls", "type": "tuple[]", "components": [
+        {"name": "target", "type": "address"},
+        {"name": "allowFailure", "type": "bool"},
+        {"name": "callData", "type": "bytes"},
+    ]}],
+    "outputs": [{"name": "returnData", "type": "tuple[]", "components": [
+        {"name": "success", "type": "bool"},
+        {"name": "returnData", "type": "bytes"},
+    ]}],
+}]
+
+
+def multicall(w3: Web3, calls: list) -> list:
+    """Batch contract calls. calls = list of ContractFunction objects."""
+    mc = w3.eth.contract(address=MULTICALL3, abi=MULTICALL3_ABI)
+    encoded = [(call.address, False, call._encode_transaction_data()) for call in calls]
+    results = mc.functions.aggregate3(encoded).call()
+    decoded = []
+    for call, (_, data) in zip(calls, results):
+        types = [o["type"] for o in call.abi["outputs"]]
+        result = decode_abi(types, data)
+        decoded.append(result[0] if len(result) == 1 else result)
+    return decoded

tinybot_eth-0.1.0/tinybot/state.py

@@ -0,0 +1,20 @@
+class State:
+    def __init__(self):
+        self.last_block: dict[str, int] = {}  # listener_name -> block
+        self.active_items: list = []
+        self._processed: set = set()
+
+    def is_processed(self, event_id: str) -> bool:
+        return event_id in self._processed
+
+    def mark_processed(self, event_id: str):
+        self._processed.add(event_id)
+
+    def add_item(self, *addrs: str):
+        item = list(addrs)
+        if item not in self.active_items:
+            self.active_items.append(item)
+
+    def remove_item(self, item: list):
+        if item in self.active_items:
+            self.active_items.remove(item)

tinybot_eth-0.1.0/tinybot/tg.py

@@ -0,0 +1,33 @@
+import os
+
+from telegram import Bot
+
+
+def _require_env(name: str) -> str:
+    val = os.getenv(name, "")
+    if not val:
+        raise RuntimeError(f"!{name}")
+    return val
+
+
+BOT_ACCESS_TOKEN = _require_env("BOT_ACCESS_TOKEN")
+GROUP_CHAT_ID = int(_require_env("GROUP_CHAT_ID"))
+DEV_GROUP_CHAT_ID = int(_require_env("DEV_GROUP_CHAT_ID"))
+
+
+async def notify_group_chat(
+    text: str,
+    parse_mode: str = "HTML",
+    chat_id: int = GROUP_CHAT_ID,
+    disable_web_page_preview: bool = True,
+) -> None:
+    try:
+        bot = Bot(token=BOT_ACCESS_TOKEN)
+        await bot.send_message(
+            chat_id=chat_id,
+            text=text,
+            parse_mode=parse_mode,
+            disable_web_page_preview=disable_web_page_preview,
+        )
+    except Exception as e:
+        print(f"Failed to send message to group chat: {e}")

tinybot_eth-0.1.0/tinybot/types.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from web3 import Web3
+
+if TYPE_CHECKING:
+    from tinybot.bot import TinyBot
+
+EventHandler = Callable[["TinyBot", Any], Awaitable[None]]
+TaskHandler = Callable[["TinyBot"], Awaitable[None]]
+
+
+@dataclass
+class EventListener:
+    name: str
+    signature: str
+    addresses: list[str]
+    abi: list[dict[str, Any]]
+    handler: EventHandler
+    poll_interval: int = 180
+    block_buffer: int = 5
+    notify_errors: bool = False
+    _last_run: float = 0
+    _w3: Web3 | None = None
+
+    def add_address(self, address: str) -> None:
+        checksummed = self._w3.to_checksum_address(address)  # type: ignore[union-attr]
+        if checksummed not in self.addresses:
+            self.addresses.append(checksummed)
+
+    def remove_address(self, address: str) -> None:
+        checksummed = self._w3.to_checksum_address(address)  # type: ignore[union-attr]
+        if checksummed in self.addresses:
+            self.addresses.remove(checksummed)
+
+
+@dataclass
+class PeriodicTask:
+    name: str
+    interval: int
+    handler: TaskHandler
+    notify_errors: bool = False
+    _last_run: float = 0

tinybot_eth-0.1.0/tinybot/utils.py

@@ -0,0 +1,22 @@
+import os
+from typing import Any
+
+
+def event_signature(abi: list[dict[str, Any]], event_name: str) -> str:
+    for item in abi:
+        if item.get("type") == "event" and item.get("name") == event_name:
+            types = ",".join(inp["type"] for inp in item["inputs"])
+            return f"{event_name}({types})"
+    raise ValueError(f"event '{event_name}' not found in ABI")
+
+
+def event_id(log) -> str:
+    return f"{log.transactionHash.hex()}:{log.logIndex}"
+
+
+DEBUG = os.getenv("DEBUG", False)
+
+
+def debug(msg: str):
+    if DEBUG:
+        print(f"DEBUG: {msg}")

tinybot_eth-0.1.0/tinybot_eth.egg-info/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: tinybot-eth
+Version: 0.1.0
+Summary: Minimal Python framework for building crypto bots
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: web3==7.14.1
+Requires-Dist: eth-abi==5.2.0
+Requires-Dist: eth-account==0.13.7
+Requires-Dist: python-telegram-bot==22.7
+
+# tinybot
+
+Minimal Python framework for building crypto bots.
+
+## Installation
+
+```bash
+pip install tinybot-eth
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `BOT_ACCESS_TOKEN` | Yes | Telegram bot token |
+| `GROUP_CHAT_ID` | Yes | Telegram group for notifications |
+| `DEV_GROUP_CHAT_ID` | Yes | Telegram group for errors and startup |
+| `PRIVATE_KEY` | No | Private key for onchain execution |
+
+## Quick Start
+
+```python
+import asyncio
+import os
+from tinybot import TinyBot, multicall, notify_group_chat
+
+ERC20_ABI = [...]
+STRATEGY_ABI = [...]
+
+async def on_transfer(bot, log):
+    print(f"{log.args.sender} -> {log.args.receiver}: {log.args.value}")
+    await notify_group_chat(f"Transfer from {log.args.sender}")
+
+async def check_and_tend(bot):
+    strategy = bot.w3.eth.contract(address="0x...", abi=STRATEGY_ABI)
+    needs_tend, _ = strategy.functions.tendTrigger().call()
+    if needs_tend:
+        tx_hash = bot.executor.execute(
+            strategy.functions.tend(),
+            gas_limit=5_000_000,
+        )
+        await notify_group_chat(f"Tend submitted: {tx_hash}")
+
+async def main():
+    bot = TinyBot(
+        rpc_url=os.environ["RPC_URL"],
+        name="my bot",
+        private_key=os.environ.get("PRIVATE_KEY", ""),
+    )
+
+    bot.listen(
+        name="transfers",
+        event="Transfer",
+        addresses=["0x..."],
+        abi=ERC20_ABI,
+        handler=on_transfer,
+        poll_interval=180,
+        notify_errors=True,
+    )
+
+    bot.every(3600, check_and_tend, notify_errors=True)
+
+    await bot.run()
+
+asyncio.run(main())
+```
+
+## API
+
+### `TinyBot(rpc_url, name="tinybot", private_key="")`
+
+Creates a bot instance.
+
+- `bot.w3` — `web3.Web3` instance
+- `bot.state` — `State` instance (see below)
+- `bot.executor` — `Executor` instance if `private_key` is provided, else `None`
+- `bot.name` — used in logs and Telegram startup message
+
+On `run()`, sends a startup message to `DEV_GROUP_CHAT_ID` and prints a polling heartbeat every tick.
+
+---
+
+### `bot.listen(...) -> EventListener`
+
+Register an event listener.
+
+```python
+bot.listen(
+    name="kicks",            # unique name
+    event="AuctionKicked",   # event name (must exist in ABI)
+    addresses=["0x..."],     # contracts to monitor
+    abi=[...],               # ABI containing the event
+    handler=on_kick,         # async fn(bot, log)
+    poll_interval=180,       # seconds between polls (default: 180)
+    block_buffer=5,          # re-scan buffer in blocks (default: 5)
+    notify_errors=True,      # send errors to Telegram (default: False)
+)
+```
+
+The event signature is derived from the ABI at registration time. Raises `ValueError` if:
+- Event not found in ABI
+- Duplicate listener name
+- Empty addresses
+
+---
+
+### `bot.every(interval, handler, name="", notify_errors=False) -> PeriodicTask`
+
+Register a periodic task.
+
+```python
+bot.every(3600, check_expired, notify_errors=True)
+```
+
+Handler signature: `async fn(bot)`
+
+---
+
+### `bot.get_listener(name) -> EventListener`
+
+Get a registered listener by name. Raises `ValueError` if not found.
+
+---
+
+### `bot.replay(name, from_block, to_block)`
+
+Replay historical events through a listener's handler. Useful for testing with real chain data.
+
+```python
+await bot.replay("kicks", from_block=21000000, to_block=21000500)
+```
+
+---
+
+### `bot.run(tick=10)`
+
+Start the polling loop. `tick` (default: 10s) is the inner loop sleep. Each listener and task fires at its own interval.
+
+---
+
+### `EventListener`
+
+Returned by `bot.listen()`.
+
+- `listener.add_address(address)` — add a contract address at runtime
+- `listener.remove_address(address)` — remove a contract address at runtime
+
+Both handle checksumming and dedup.
+
+---
+
+### `Executor`
+
+Available via `bot.executor` when `private_key` is provided.
+
+```python
+bot = TinyBot(rpc_url, name="my bot", private_key=os.environ["PRIVATE_KEY"])
+
+tx_hash = bot.executor.execute(
+    contract.functions.tend(strategy_addr),
+    gas_limit=5_000_000,
+    max_fee_gwei=100,
+    max_priority_fee_gwei=3,
+)
+```
+
+- `executor.address` — signer address
+- `executor.balance` — signer ETH balance in wei
+- `executor.execute(call, ...)` — sign and broadcast a transaction, returns tx hash immediately (fire and forget)
+
+---
+
+### `State`
+
+In-memory state, available via `bot.state`.
+
+- `state.last_block` — `dict[str, int]` mapping names to last processed block
+- `state.active_items` — `list` of tracked items (e.g. address pairs)
+- `state.add_item(*addrs)` — add an item (deduped)
+- `state.remove_item(item)` — remove an item
+- `state.is_processed(event_id)` — check if event was processed
+- `state.mark_processed(event_id)` — mark event as processed (handled automatically for listeners)
+
+---
+
+### `multicall(w3, calls) -> list`
+
+Batch contract reads via [Multicall3](https://github.com/mds1/multicall).
+
+```python
+symbol, decimals = multicall(bot.w3, [
+    token.functions.symbol(),
+    token.functions.decimals(),
+])
+```
+
+---
+
+### `notify_group_chat(text, parse_mode="HTML", chat_id=GROUP_CHAT_ID)`
+
+Send a Telegram message. HTML parse mode by default.
+
+---
+
+### `event_id(log) -> str`
+
+Unique ID from a log (`txHash:logIndex`). Used internally for dedup, also available for custom event processing in periodic tasks.
+
+## Handler Signatures
+
+```python
+# Event handler
+async def on_event(bot: TinyBot, log) -> None: ...
+
+# Task handler
+async def my_task(bot: TinyBot) -> None: ...
+```
+
+Access `bot.w3`, `bot.state`, `bot.executor`, and `bot.get_listener()` from any handler.
+
+## Error Handling
+
+When `notify_errors=True`, exceptions are caught and sent to `DEV_GROUP_CHAT_ID` as `[name] error message`. The bot continues running.

tinybot_eth-0.1.0/tinybot_eth.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+tinybot/__init__.py
+tinybot/bot.py
+tinybot/executor.py
+tinybot/multicall.py
+tinybot/state.py
+tinybot/tg.py
+tinybot/types.py
+tinybot/utils.py
+tinybot_eth.egg-info/PKG-INFO
+tinybot_eth.egg-info/SOURCES.txt
+tinybot_eth.egg-info/dependency_links.txt
+tinybot_eth.egg-info/requires.txt
+tinybot_eth.egg-info/top_level.txt

tinybot_eth-0.1.0/tinybot_eth.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tinybot_eth-0.1.0/tinybot_eth.egg-info/requires.txt

@@ -0,0 +1,4 @@
+web3==7.14.1
+eth-abi==5.2.0
+eth-account==0.13.7
+python-telegram-bot==22.7

tinybot_eth-0.1.0/tinybot_eth.egg-info/top_level.txt

@@ -0,0 +1 @@
+tinybot