tinybot-eth 0.5.0__tar.gz → 0.7.0__tar.gz

{tinybot_eth-0.5.0 → tinybot_eth-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tinybot-eth
-Version: 0.5.0
+Version: 0.7.0
 Summary: Minimal Python framework for building crypto bots
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -8,6 +8,7 @@ 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
+Requires-Dist: croniter==6.2.2
 
 # tinybot
 
@@ -23,9 +24,9 @@ pip install tinybot-eth
 
 | 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 |
+| `BOT_ACCESS_TOKEN` | No | Telegram bot token. Unset: `notify_group_chat` does nothing and `telegram_enabled()` is `False` |
+| `GROUP_CHAT_ID` | No | Telegram group for notifications |
+| `DEV_GROUP_CHAT_ID` | No | Telegram group for errors and startup |
 | `PRIVATE_KEY` | No | Private key for onchain execution |
 
 ## Quick Start
@@ -34,6 +35,7 @@ bot = TinyBot(rpc_url, name="my bot")
 
 bot.listen(event="AuctionKicked", handler=on_kick, ...)
 bot.every(180, check_expired)
+bot.cron("0 * * * *", hourly_check)
 
 await bot.run()
 ```
@@ -83,7 +85,7 @@ asyncio.run(main())
 
 ## API
 
-### `TinyBot(rpc_url, name="tinybot", private_key="")`
+### `TinyBot(rpc_url, private_rpc_url="", name="tinybot", private_key="")`
 
 Creates a bot instance.
 
@@ -91,6 +93,7 @@ Creates a bot 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
+- `private_rpc_url` — optional private relay (e.g. `https://rpc.flashbots.net/fast`), used only for txs sent with `execute(..., private=True)`; reads and public txs stay on `rpc_url`
 
 On `run()`, sends a startup message to `DEV_GROUP_CHAT_ID` and prints a polling heartbeat every tick.
 
@@ -132,6 +135,19 @@ Handler signature: `async fn(bot)`
 
 ---
 
+### `bot.cron(expression, handler, name="", notify_errors=True) -> CronTask`
+
+Register a cron-scheduled task. Uses standard cron expressions.
+
+```python
+bot.cron("0 * * * *", notify_ending_soon)      # every hour at :00
+bot.cron("*/30 * * * *", check_something)       # every 30 minutes
+```
+
+Handler signature: `async fn(bot)`
+
+---
+
 ### `bot.get_listener(name) -> EventListener`
 
 Get a registered listener by name. Raises `ValueError` if not found.
@@ -179,16 +195,20 @@ tx_hash = bot.executor.execute(
     max_priority_fee_gwei=0,  # default: 0
     simulate=True,            # default: True — dry-run via eth_call before sending
     wait=120,                 # default: 120 — seconds to wait for mining (0 = fire and forget)
+    private=False,            # default: False — True broadcasts via private_rpc_url
+    replace_pending=False,    # default: False — True reuses the nonce of an unmined tx to replace it
 )
 ```
 
 - `executor.address` — signer address
 - `executor.balance` — signer ETH balance in wei
-- `executor.execute(call, ...)` — sign and broadcast a transaction, returns tx hash hex string
+- `executor.execute(call, ...)` — sign and broadcast a transaction, returns the `0x`-prefixed tx hash
 - `gas_limit=0` (default) — auto-estimates gas with 1.5x buffer; pass a value to override
 - `max_fee_gwei` / `max_priority_fee_gwei` — accept floats (e.g. `0.1`)
 - `simulate=True` (default) — runs `call.call()` first; reverts raise before the tx is sent
 - `wait=120` (default) — wait up to N seconds for the tx to be mined; `0` for fire and forget
+- `replace_pending=False` (default) — nonce from the `pending` block, so a tx sent while an earlier one is unmined queues behind it; `replace_pending=True` — nonce from the `latest` block, so the tx replaces the unmined one (the node requires a ~10% higher fee)
+- `private=False` (default) — broadcasts via `rpc_url`; `private=True` broadcasts via `private_rpc_url` and raises if it is not set. There is no fallback between the two, so a private tx never goes public
 
 ---
 
@@ -205,7 +225,7 @@ In-memory state, available via `bot.state`.
 
 ---
 
-### `multicall(w3, calls) -> list`
+### `multicall(w3, calls, allow_failure=False, batch_size=200) -> list`
 
 Batch contract reads via [Multicall3](https://github.com/mds1/multicall).
 
@@ -214,13 +234,27 @@ symbol, decimals = multicall(bot.w3, [
     token.functions.symbol(),
     token.functions.decimals(),
 ])
+
+# one result per call; None where the call reverted or returned nothing
+keepers = multicall(bot.w3, [s.functions.keeper() for s in strategies], allow_failure=True)
 ```
 
+- `allow_failure=False` (default) — any reverting call reverts the whole batch
+- `allow_failure=True` — a reverting call, empty return data, or undecodable data yields `None`
+- `batch_size=200` — calls are split into chunks of this size to stay under RPC `eth_call` gas caps
+- Functions returning tuples/structs are decoded
+
 ---
 
 ### `notify_group_chat(text, parse_mode="HTML", chat_id=GROUP_CHAT_ID)`
 
-Send a Telegram message. HTML parse mode by default.
+Send a Telegram message. HTML parse mode by default. Does nothing when `BOT_ACCESS_TOKEN` or the chat id is unset.
+
+---
+
+### `telegram_enabled() -> bool`
+
+`True` when `BOT_ACCESS_TOKEN` is set. Use it to skip work whose only output is a Telegram message.
 
 ---
 

{tinybot_eth-0.5.0 → tinybot_eth-0.7.0}/README.md

@@ -12,9 +12,9 @@ pip install tinybot-eth
 
 | 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 |
+| `BOT_ACCESS_TOKEN` | No | Telegram bot token. Unset: `notify_group_chat` does nothing and `telegram_enabled()` is `False` |
+| `GROUP_CHAT_ID` | No | Telegram group for notifications |
+| `DEV_GROUP_CHAT_ID` | No | Telegram group for errors and startup |
 | `PRIVATE_KEY` | No | Private key for onchain execution |
 
 ## Quick Start
@@ -23,6 +23,7 @@ bot = TinyBot(rpc_url, name="my bot")
 
 bot.listen(event="AuctionKicked", handler=on_kick, ...)
 bot.every(180, check_expired)
+bot.cron("0 * * * *", hourly_check)
 
 await bot.run()
 ```
@@ -72,7 +73,7 @@ asyncio.run(main())
 
 ## API
 
-### `TinyBot(rpc_url, name="tinybot", private_key="")`
+### `TinyBot(rpc_url, private_rpc_url="", name="tinybot", private_key="")`
 
 Creates a bot instance.
 
@@ -80,6 +81,7 @@ Creates a bot 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
+- `private_rpc_url` — optional private relay (e.g. `https://rpc.flashbots.net/fast`), used only for txs sent with `execute(..., private=True)`; reads and public txs stay on `rpc_url`
 
 On `run()`, sends a startup message to `DEV_GROUP_CHAT_ID` and prints a polling heartbeat every tick.
 
@@ -121,6 +123,19 @@ Handler signature: `async fn(bot)`
 
 ---
 
+### `bot.cron(expression, handler, name="", notify_errors=True) -> CronTask`
+
+Register a cron-scheduled task. Uses standard cron expressions.
+
+```python
+bot.cron("0 * * * *", notify_ending_soon)      # every hour at :00
+bot.cron("*/30 * * * *", check_something)       # every 30 minutes
+```
+
+Handler signature: `async fn(bot)`
+
+---
+
 ### `bot.get_listener(name) -> EventListener`
 
 Get a registered listener by name. Raises `ValueError` if not found.
@@ -168,16 +183,20 @@ tx_hash = bot.executor.execute(
     max_priority_fee_gwei=0,  # default: 0
     simulate=True,            # default: True — dry-run via eth_call before sending
     wait=120,                 # default: 120 — seconds to wait for mining (0 = fire and forget)
+    private=False,            # default: False — True broadcasts via private_rpc_url
+    replace_pending=False,    # default: False — True reuses the nonce of an unmined tx to replace it
 )
 ```
 
 - `executor.address` — signer address
 - `executor.balance` — signer ETH balance in wei
-- `executor.execute(call, ...)` — sign and broadcast a transaction, returns tx hash hex string
+- `executor.execute(call, ...)` — sign and broadcast a transaction, returns the `0x`-prefixed tx hash
 - `gas_limit=0` (default) — auto-estimates gas with 1.5x buffer; pass a value to override
 - `max_fee_gwei` / `max_priority_fee_gwei` — accept floats (e.g. `0.1`)
 - `simulate=True` (default) — runs `call.call()` first; reverts raise before the tx is sent
 - `wait=120` (default) — wait up to N seconds for the tx to be mined; `0` for fire and forget
+- `replace_pending=False` (default) — nonce from the `pending` block, so a tx sent while an earlier one is unmined queues behind it; `replace_pending=True` — nonce from the `latest` block, so the tx replaces the unmined one (the node requires a ~10% higher fee)
+- `private=False` (default) — broadcasts via `rpc_url`; `private=True` broadcasts via `private_rpc_url` and raises if it is not set. There is no fallback between the two, so a private tx never goes public
 
 ---
 
@@ -194,7 +213,7 @@ In-memory state, available via `bot.state`.
 
 ---
 
-### `multicall(w3, calls) -> list`
+### `multicall(w3, calls, allow_failure=False, batch_size=200) -> list`
 
 Batch contract reads via [Multicall3](https://github.com/mds1/multicall).
 
@@ -203,13 +222,27 @@ symbol, decimals = multicall(bot.w3, [
     token.functions.symbol(),
     token.functions.decimals(),
 ])
+
+# one result per call; None where the call reverted or returned nothing
+keepers = multicall(bot.w3, [s.functions.keeper() for s in strategies], allow_failure=True)
 ```
 
+- `allow_failure=False` (default) — any reverting call reverts the whole batch
+- `allow_failure=True` — a reverting call, empty return data, or undecodable data yields `None`
+- `batch_size=200` — calls are split into chunks of this size to stay under RPC `eth_call` gas caps
+- Functions returning tuples/structs are decoded
+
 ---
 
 ### `notify_group_chat(text, parse_mode="HTML", chat_id=GROUP_CHAT_ID)`
 
-Send a Telegram message. HTML parse mode by default.
+Send a Telegram message. HTML parse mode by default. Does nothing when `BOT_ACCESS_TOKEN` or the chat id is unset.
+
+---
+
+### `telegram_enabled() -> bool`
+
+`True` when `BOT_ACCESS_TOKEN` is set. Use it to skip work whose only output is a Telegram message.
 
 ---
 

{tinybot_eth-0.5.0 → tinybot_eth-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tinybot-eth"
-version = "0.5.0"
+version = "0.7.0"
 description = "Minimal Python framework for building crypto bots"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -9,6 +9,7 @@ dependencies = [
     "eth-abi==5.2.0",
     "eth-account==0.13.7",
     "python-telegram-bot==22.7",
+    "croniter==6.2.2",
 ]
 
 [tool.setuptools.packages.find]

{tinybot_eth-0.5.0 → tinybot_eth-0.7.0}/tinybot/__init__.py

@@ -1,7 +1,7 @@
 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.tg import DEV_GROUP_CHAT_ID, notify_group_chat, telegram_enabled
 from tinybot.utils import event_id
 
 __all__ = [
@@ -11,4 +11,5 @@ __all__ = [
     "event_id",
     "multicall",
     "notify_group_chat",
+    "telegram_enabled",
 ]

{tinybot_eth-0.5.0 → tinybot_eth-0.7.0}/tinybot/bot.py

@@ -8,18 +8,22 @@ 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 croniter import croniter
+
+from tinybot.types import CronTask, 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))
+    def __init__(self, rpc_url: str, private_rpc_url: str = "", name: str = "tinybot", private_key: str = ""):
+        self.w3 = Web3(Web3.HTTPProvider(rpc_url, cache_allowed_requests=True, cacheable_requests={"eth_chainId"}))
         self.name = name
         self.state = State()
-        self.executor = Executor(self.w3, private_key) if private_key else None
+        self._private_w3 = Web3(Web3.HTTPProvider(private_rpc_url)) if private_rpc_url else None
+        self.executor = Executor(self.w3, private_key, self._private_w3) if private_key else None
         self._listeners: list[EventListener] = []
         self._tasks: list[PeriodicTask] = []
+        self._crons: list[tuple[CronTask, croniter]] = []
 
     # -------------------------------------------------------------------------
     # Registration
@@ -77,6 +81,26 @@ class TinyBot:
         self._tasks.append(task)
         return task
 
+    def cron(
+        self,
+        expression: str,
+        handler: TaskHandler,
+        name: str = "",
+        notify_errors: bool = True,
+    ) -> CronTask:
+        name = name or handler.__name__
+        if any(task.name == name for task, _ in self._crons):
+            raise ValueError(f"cron '{name}' already registered")
+        task = CronTask(
+            name=name,
+            expression=expression,
+            handler=handler,
+            notify_errors=notify_errors,
+        )
+        cron = croniter(expression, datetime.now())
+        self._crons.append((task, cron))
+        return task
+
     # -------------------------------------------------------------------------
     # Getters
     # -------------------------------------------------------------------------
@@ -149,7 +173,7 @@ class TinyBot:
         except Exception as e:
             await self._handle_error(e, listener.name, listener.notify_errors)
 
-    async def _poll_task(self, task: PeriodicTask) -> None:
+    async def _poll_periodic(self, task: PeriodicTask) -> None:
         now = time.time()
         if now - task._last_run < task.interval:
             return
@@ -160,6 +184,16 @@ class TinyBot:
         except Exception as e:
             await self._handle_error(e, task.name, task.notify_errors)
 
+    async def _poll_cron(self, task: CronTask, cron: croniter) -> None:
+        now = datetime.now()
+        next_run = cron.get_current(datetime)
+        if now >= next_run:
+            try:
+                await task.handler(self)
+            except Exception as e:
+                await self._handle_error(e, task.name, task.notify_errors)
+            cron.get_next(datetime)
+
     # -------------------------------------------------------------------------
     # Run
     # -------------------------------------------------------------------------
@@ -175,5 +209,7 @@ class TinyBot:
             for listener in self._listeners:
                 await self._poll_listener(listener)
             for task in self._tasks:
-                await self._poll_task(task)
+                await self._poll_periodic(task)
+            for task, cron in self._crons:
+                await self._poll_cron(task, cron)
             await asyncio.sleep(tick)

{tinybot_eth-0.5.0 → tinybot_eth-0.7.0}/tinybot/executor.py

@@ -4,8 +4,9 @@ from web3 import Web3
 
 
 class Executor:
-    def __init__(self, w3: Web3, private_key: str):
+    def __init__(self, w3: Web3, private_key: str, private_w3: Web3 | None = None):
         self._w3 = w3
+        self._private_w3 = private_w3  # optional private relay, used only for txs sent with `private=True`
         self._account: LocalAccount = Account.from_key(private_key)
 
     @property
@@ -25,7 +26,12 @@ class Executor:
         value: int = 0,
         simulate: bool = True,
         wait: int = 120,
+        private: bool = False,
+        replace_pending: bool = False,
     ) -> str:
+        if private and self._private_w3 is None:
+            raise ValueError("private tx requested but no private_rpc_url is set")
+
         if simulate:
             call.call({"from": self._account.address, "value": value})
 
@@ -35,7 +41,9 @@ class Executor:
         tx = call.build_transaction(
             {
                 "from": self._account.address,
-                "nonce": self._w3.eth.get_transaction_count(self._account.address),
+                "nonce": self._w3.eth.get_transaction_count(
+                    self._account.address, "latest" if replace_pending else "pending"
+                ),
                 "gas": gas_limit,
                 "maxFeePerGas": self._w3.to_wei(max_fee_gwei, "gwei"),
                 "maxPriorityFeePerGas": self._w3.to_wei(max_priority_fee_gwei, "gwei"),
@@ -43,7 +51,8 @@ class Executor:
             }
         )
         signed = self._w3.eth.account.sign_transaction(tx, self._account.key)
-        tx_hash = self._w3.eth.send_raw_transaction(signed.raw_transaction)
+        send_w3 = self._private_w3 if private else self._w3
+        tx_hash = send_w3.eth.send_raw_transaction(signed.raw_transaction)
         if wait > 0:
             self._w3.eth.wait_for_transaction_receipt(tx_hash, timeout=wait)
-        return tx_hash.hex()
+        return tx_hash.to_0x_hex()

{tinybot_eth-0.5.0 → tinybot_eth-0.7.0}/tinybot/multicall.py

@@ -1,4 +1,5 @@
 from eth_abi import decode as decode_abi
+from eth_utils import get_abi_output_types
 from web3 import Web3
 
 # Multicall3 — same address on all chains
@@ -33,14 +34,28 @@ MULTICALL3_ABI = [
 ]
 
 
-def multicall(w3: Web3, calls: list) -> list:
-    """Batch contract calls. calls = list of ContractFunction objects."""
+def multicall(w3: Web3, calls: list, allow_failure: bool = False, batch_size: int = 200) -> list:
+    """Batch contract calls. calls = list of ContractFunction objects.
+
+    With allow_failure=True, a reverting call (or one that returns no data) yields None instead of
+    reverting the whole batch. Calls are sent in chunks of batch_size to stay under eth_call gas caps.
+    """
     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)
+    for i in range(0, len(calls), batch_size):
+        chunk = calls[i : i + batch_size]
+        encoded = [(call.address, allow_failure, call._encode_transaction_data()) for call in chunk]
+        results = mc.functions.aggregate3(encoded).call()
+        for call, (success, data) in zip(chunk, results):
+            if allow_failure and (not success or not data):
+                decoded.append(None)
+                continue
+            try:
+                result = decode_abi(get_abi_output_types(call.abi), data)
+            except Exception:
+                if not allow_failure:
+                    raise
+                decoded.append(None)
+                continue
+            decoded.append(result[0] if len(result) == 1 else result)
     return decoded

{tinybot_eth-0.5.0 → tinybot_eth-0.7.0}/tinybot/tg.py

@@ -2,17 +2,13 @@ import os
 
 from telegram import Bot
 
+BOT_ACCESS_TOKEN = os.getenv("BOT_ACCESS_TOKEN", "")
+GROUP_CHAT_ID = int(os.getenv("GROUP_CHAT_ID", "0"))
+DEV_GROUP_CHAT_ID = int(os.getenv("DEV_GROUP_CHAT_ID", "0"))
 
-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"))
+def telegram_enabled() -> bool:
+    return bool(BOT_ACCESS_TOKEN)
 
 
 async def notify_group_chat(
@@ -21,6 +17,8 @@ async def notify_group_chat(
     chat_id: int = GROUP_CHAT_ID,
     disable_web_page_preview: bool = True,
 ) -> None:
+    if not BOT_ACCESS_TOKEN or not chat_id:
+        return
     try:
         bot = Bot(token=BOT_ACCESS_TOKEN)
         await bot.send_message(

{tinybot_eth-0.5.0 → tinybot_eth-0.7.0}/tinybot/types.py

@@ -44,3 +44,11 @@ class PeriodicTask:
     handler: TaskHandler
     notify_errors: bool = True
     _last_run: float = 0
+
+
+@dataclass
+class CronTask:
+    name: str
+    expression: str
+    handler: TaskHandler
+    notify_errors: bool = True

{tinybot_eth-0.5.0 → tinybot_eth-0.7.0}/tinybot_eth.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tinybot-eth
-Version: 0.5.0
+Version: 0.7.0
 Summary: Minimal Python framework for building crypto bots
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -8,6 +8,7 @@ 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
+Requires-Dist: croniter==6.2.2
 
 # tinybot
 
@@ -23,9 +24,9 @@ pip install tinybot-eth
 
 | 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 |
+| `BOT_ACCESS_TOKEN` | No | Telegram bot token. Unset: `notify_group_chat` does nothing and `telegram_enabled()` is `False` |
+| `GROUP_CHAT_ID` | No | Telegram group for notifications |
+| `DEV_GROUP_CHAT_ID` | No | Telegram group for errors and startup |
 | `PRIVATE_KEY` | No | Private key for onchain execution |
 
 ## Quick Start
@@ -34,6 +35,7 @@ bot = TinyBot(rpc_url, name="my bot")
 
 bot.listen(event="AuctionKicked", handler=on_kick, ...)
 bot.every(180, check_expired)
+bot.cron("0 * * * *", hourly_check)
 
 await bot.run()
 ```
@@ -83,7 +85,7 @@ asyncio.run(main())
 
 ## API
 
-### `TinyBot(rpc_url, name="tinybot", private_key="")`
+### `TinyBot(rpc_url, private_rpc_url="", name="tinybot", private_key="")`
 
 Creates a bot instance.
 
@@ -91,6 +93,7 @@ Creates a bot 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
+- `private_rpc_url` — optional private relay (e.g. `https://rpc.flashbots.net/fast`), used only for txs sent with `execute(..., private=True)`; reads and public txs stay on `rpc_url`
 
 On `run()`, sends a startup message to `DEV_GROUP_CHAT_ID` and prints a polling heartbeat every tick.
 
@@ -132,6 +135,19 @@ Handler signature: `async fn(bot)`
 
 ---
 
+### `bot.cron(expression, handler, name="", notify_errors=True) -> CronTask`
+
+Register a cron-scheduled task. Uses standard cron expressions.
+
+```python
+bot.cron("0 * * * *", notify_ending_soon)      # every hour at :00
+bot.cron("*/30 * * * *", check_something)       # every 30 minutes
+```
+
+Handler signature: `async fn(bot)`
+
+---
+
 ### `bot.get_listener(name) -> EventListener`
 
 Get a registered listener by name. Raises `ValueError` if not found.
@@ -179,16 +195,20 @@ tx_hash = bot.executor.execute(
     max_priority_fee_gwei=0,  # default: 0
     simulate=True,            # default: True — dry-run via eth_call before sending
     wait=120,                 # default: 120 — seconds to wait for mining (0 = fire and forget)
+    private=False,            # default: False — True broadcasts via private_rpc_url
+    replace_pending=False,    # default: False — True reuses the nonce of an unmined tx to replace it
 )
 ```
 
 - `executor.address` — signer address
 - `executor.balance` — signer ETH balance in wei
-- `executor.execute(call, ...)` — sign and broadcast a transaction, returns tx hash hex string
+- `executor.execute(call, ...)` — sign and broadcast a transaction, returns the `0x`-prefixed tx hash
 - `gas_limit=0` (default) — auto-estimates gas with 1.5x buffer; pass a value to override
 - `max_fee_gwei` / `max_priority_fee_gwei` — accept floats (e.g. `0.1`)
 - `simulate=True` (default) — runs `call.call()` first; reverts raise before the tx is sent
 - `wait=120` (default) — wait up to N seconds for the tx to be mined; `0` for fire and forget
+- `replace_pending=False` (default) — nonce from the `pending` block, so a tx sent while an earlier one is unmined queues behind it; `replace_pending=True` — nonce from the `latest` block, so the tx replaces the unmined one (the node requires a ~10% higher fee)
+- `private=False` (default) — broadcasts via `rpc_url`; `private=True` broadcasts via `private_rpc_url` and raises if it is not set. There is no fallback between the two, so a private tx never goes public
 
 ---
 
@@ -205,7 +225,7 @@ In-memory state, available via `bot.state`.
 
 ---
 
-### `multicall(w3, calls) -> list`
+### `multicall(w3, calls, allow_failure=False, batch_size=200) -> list`
 
 Batch contract reads via [Multicall3](https://github.com/mds1/multicall).
 
@@ -214,13 +234,27 @@ symbol, decimals = multicall(bot.w3, [
     token.functions.symbol(),
     token.functions.decimals(),
 ])
+
+# one result per call; None where the call reverted or returned nothing
+keepers = multicall(bot.w3, [s.functions.keeper() for s in strategies], allow_failure=True)
 ```
 
+- `allow_failure=False` (default) — any reverting call reverts the whole batch
+- `allow_failure=True` — a reverting call, empty return data, or undecodable data yields `None`
+- `batch_size=200` — calls are split into chunks of this size to stay under RPC `eth_call` gas caps
+- Functions returning tuples/structs are decoded
+
 ---
 
 ### `notify_group_chat(text, parse_mode="HTML", chat_id=GROUP_CHAT_ID)`
 
-Send a Telegram message. HTML parse mode by default.
+Send a Telegram message. HTML parse mode by default. Does nothing when `BOT_ACCESS_TOKEN` or the chat id is unset.
+
+---
+
+### `telegram_enabled() -> bool`
+
+`True` when `BOT_ACCESS_TOKEN` is set. Use it to skip work whose only output is a Telegram message.
 
 ---
 

{tinybot_eth-0.5.0 → tinybot_eth-0.7.0}/tinybot_eth.egg-info/requires.txt

@@ -2,3 +2,4 @@ web3==7.14.1
 eth-abi==5.2.0
 eth-account==0.13.7
 python-telegram-bot==22.7
+croniter==6.2.2