chain-sniper 0.1.0__tar.gz

chain_sniper-0.1.0/.gitignore

@@ -0,0 +1,113 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+pytest_cache/
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# Type checkers
+.mypy_cache/
+.pyre/
+.pytype/
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# dotenv
+.env.*
+!.env.example
+
+# IDEs and editors
+.vscode/
+.idea/
+*.sublime-project
+*.sublime-workspace
+
+# OS files
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Logs
+*.log
+
+# SQLite database files
+*.sqlite3
+*.db
+
+# FastAPI / Flask instance folder
+instance/
+
+# MkDocs documentation
+/site
+
+# Ruff
+.ruff_cache/
+
+# Poetry
+poetry.lock
+
+# PDM
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# pipenv
+Pipfile.lock
+dump.rdb
+.todo

chain_sniper-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: chain-sniper
+Version: 0.1.0
+Summary: A high-performance EVM blockchain listener and transaction monitor
+Project-URL: Homepage, https://github.com/rakibhossain72/chain-sniper
+Project-URL: Repository, https://github.com/rakibhossain72/chain-sniper
+License: MIT
+Keywords: blockchain,ethereum,evm,listener,monitor,web3
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Requires-Dist: aiofiles>=25.1.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: redis>=7.2.1
+Requires-Dist: web3>=7.14.1
+Requires-Dist: websockets>=15.0.1
+Description-Content-Type: text/markdown
+
+# Chain Sniper
+
+A high-performance EVM blockchain listener and transaction monitor.
+
+## Install
+
+```bash
+git clone https://github.com/rakibhossain72/chain-sniper.git
+cd chain-sniper
+uv sync
+```
+
+Or with pip:
+
+```bash
+pip install chain-sniper
+```
+
+## Quick Start
+
+```python
+from chain_sniper import ChainSniper
+
+ERC20_ABI = [...]  # Transfer event ABI
+USDT = "0x55d398326f99059fF775485246999027B3197955"
+
+sniper = ChainSniper("wss://bsc-ws-node.nariox.org:443")
+
+@sniper.event(contract=USDT, abi=ERC20_ABI, name="Transfer")
+async def handle_transfer(event):
+    print(f"Transfer: {event['args']['value'] / 10**18} USDT")
+
+await sniper.start()
+```
+
+Use a WebSocket URL (`wss://` or `ws://`) — that's the only supported transport.
+
+## RPC Pool (fault-tolerant)
+
+```python
+from chain_sniper.rpc_pool import RPCPool
+
+pool = await RPCPool.create(
+    rpcs=[
+        "https://bsc-dataseed1.binance.org",
+        "wss://bsc-ws-node.nariox.org:443",
+    ],
+    expected_chain_id=56,
+)
+sniper = ChainSniper(pool)
+```
+
+## Transaction Monitoring
+
+```python
+sniper.block_detail("full_block")
+
+@sniper.on_transaction
+async def handle_tx(tx):
+    print(f"{tx['hash']} | {tx['from']} -> {tx['to']}")
+```
+
+## Filtering
+
+MongoDB-style rules with operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$regex`, `$exists`.
+
+```python
+from chain_sniper import Filter
+
+f = Filter()
+f.add_tx_rule({"value": {"_op": "$gte", "_value": 10**18}})
+f.add_log_rule({"args.value": {"_op": "$gte", "_value": 1000 * 10**18}})
+
+sniper.filter(f)
+```
+
+## Dynamic Rules via Redis
+
+Inject or remove filter rules at runtime without restarting:
+
+```python
+from chain_sniper.listener import RedisRuleListener
+
+redis_listener = RedisRuleListener(
+    dynamic_filter=f,
+    redis_url="redis://localhost",
+    channel="sniper_rules",
+)
+await redis_listener.start()
+```
+
+Push rules from anywhere:
+
+```python
+import redis, json
+
+r = redis.Redis(host="localhost", port=6379, decode_responses=True)
+r.publish("sniper_rules", json.dumps({"action": "add_tx", "rule": {"to": "0x..."}}))
+```
+
+## Key API
+
+| Method | Description |
+|--------|-------------|
+| `@sniper.event(contract, abi, name)` | Register an event handler |
+| `@sniper.on_transaction` | Handle individual transactions |
+| `@sniper.on_block` | Handle new blocks |
+| `@sniper.on_reorg` | Handle chain reorgs |
+| `sniper.filter(f)` | Attach a Filter |
+| `sniper.block_detail("header" \| "full_block")` | Set block detail level |
+| `sniper.start() / .stop()` | Start or stop monitoring |
+
+See `examples/` for complete usage patterns.
+
+## License
+
+MIT

chain_sniper-0.1.0/README.md

@@ -0,0 +1,117 @@
+# Chain Sniper
+
+A high-performance EVM blockchain listener and transaction monitor.
+
+## Install
+
+```bash
+git clone https://github.com/rakibhossain72/chain-sniper.git
+cd chain-sniper
+uv sync
+```
+
+Or with pip:
+
+```bash
+pip install chain-sniper
+```
+
+## Quick Start
+
+```python
+from chain_sniper import ChainSniper
+
+ERC20_ABI = [...]  # Transfer event ABI
+USDT = "0x55d398326f99059fF775485246999027B3197955"
+
+sniper = ChainSniper("wss://bsc-ws-node.nariox.org:443")
+
+@sniper.event(contract=USDT, abi=ERC20_ABI, name="Transfer")
+async def handle_transfer(event):
+    print(f"Transfer: {event['args']['value'] / 10**18} USDT")
+
+await sniper.start()
+```
+
+Use a WebSocket URL (`wss://` or `ws://`) — that's the only supported transport.
+
+## RPC Pool (fault-tolerant)
+
+```python
+from chain_sniper.rpc_pool import RPCPool
+
+pool = await RPCPool.create(
+    rpcs=[
+        "https://bsc-dataseed1.binance.org",
+        "wss://bsc-ws-node.nariox.org:443",
+    ],
+    expected_chain_id=56,
+)
+sniper = ChainSniper(pool)
+```
+
+## Transaction Monitoring
+
+```python
+sniper.block_detail("full_block")
+
+@sniper.on_transaction
+async def handle_tx(tx):
+    print(f"{tx['hash']} | {tx['from']} -> {tx['to']}")
+```
+
+## Filtering
+
+MongoDB-style rules with operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$regex`, `$exists`.
+
+```python
+from chain_sniper import Filter
+
+f = Filter()
+f.add_tx_rule({"value": {"_op": "$gte", "_value": 10**18}})
+f.add_log_rule({"args.value": {"_op": "$gte", "_value": 1000 * 10**18}})
+
+sniper.filter(f)
+```
+
+## Dynamic Rules via Redis
+
+Inject or remove filter rules at runtime without restarting:
+
+```python
+from chain_sniper.listener import RedisRuleListener
+
+redis_listener = RedisRuleListener(
+    dynamic_filter=f,
+    redis_url="redis://localhost",
+    channel="sniper_rules",
+)
+await redis_listener.start()
+```
+
+Push rules from anywhere:
+
+```python
+import redis, json
+
+r = redis.Redis(host="localhost", port=6379, decode_responses=True)
+r.publish("sniper_rules", json.dumps({"action": "add_tx", "rule": {"to": "0x..."}}))
+```
+
+## Key API
+
+| Method | Description |
+|--------|-------------|
+| `@sniper.event(contract, abi, name)` | Register an event handler |
+| `@sniper.on_transaction` | Handle individual transactions |
+| `@sniper.on_block` | Handle new blocks |
+| `@sniper.on_reorg` | Handle chain reorgs |
+| `sniper.filter(f)` | Attach a Filter |
+| `sniper.block_detail("header" \| "full_block")` | Set block detail level |
+| `sniper.start() / .stop()` | Start or stop monitoring |
+
+See `examples/` for complete usage patterns.
+
+## License
+
+MIT

chain_sniper-0.1.0/__init__.py

@@ -0,0 +1,4 @@
+from .rpc_node import RpcNode
+from .rpc_pool import RPCPool, HttpRPCPool, WssRPCPool
+
+__all__ = ["RPCPool", "HttpRPCPool", "WssRPCPool", "RpcNode"]

chain_sniper-0.1.0/chain_sniper/__init__.py

@@ -0,0 +1,14 @@
+"""
+Chain Sniper - Simple blockchain event monitoring.
+"""
+
+from .sniper import ChainSniper
+from .listener.common import BlockDetail
+from .filters import TransactionFilter, LogFilter
+
+__all__ = [
+    "ChainSniper",
+    "BlockDetail",
+    "TransactionFilter",
+    "LogFilter",
+]

chain_sniper-0.1.0/chain_sniper/abstracts/base_filter.py

@@ -0,0 +1,32 @@
+"""
+Abstract base classes for filters.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseTransactionFilter(ABC):
+    """Abstract base for transaction / block filters."""
+
+    @abstractmethod
+    def match(self, tx: Any) -> bool: ...
+
+    @abstractmethod
+    def add_rule(self, rule: dict) -> str: ...
+
+    @abstractmethod
+    def remove_rule(self, rule_id: str) -> bool: ...
+
+
+class BaseLogFilter(ABC):
+    """Abstract base for log subscription + post-filter managers."""
+
+    @abstractmethod
+    def subscribe(self, **kwargs) -> str: ...
+
+    @abstractmethod
+    def unsubscribe(self, sub_id: str) -> bool: ...
+
+    @abstractmethod
+    def match(self, log: Any) -> bool: ...

chain_sniper-0.1.0/chain_sniper/abstracts/base_strategy.py

@@ -0,0 +1,11 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+class BaseStrategy(ABC):
+
+    @abstractmethod
+    async def execute(self, data: Any) -> None:
+        ...
+    
+    async def execute_log(self, log: Any) -> None:
+        ...

chain_sniper-0.1.0/chain_sniper/core/config.py

@@ -0,0 +1,3 @@
+RPC_URL = "wss://bsc.drpc.org"
+
+POLL_INTERVAL = 2

chain_sniper-0.1.0/chain_sniper/engine/pipeline.py

@@ -0,0 +1,41 @@
+"""
+Processing pipeline that pairs a TransactionFilter + LogFilter with a Strategy.
+"""
+
+from typing import Optional
+from chain_sniper.parser.block_parser import parse_block
+from chain_sniper.parser.log_decoder import parse_log
+from chain_sniper.filters import TransactionFilter, LogFilter
+from chain_sniper.abstracts.base_strategy import BaseStrategy
+
+
+class Pipeline:
+
+    def __init__(
+        self,
+        *,
+        tx_filter: Optional[TransactionFilter] = None,
+        log_filter: Optional[LogFilter] = None,
+        strategy: Optional[BaseStrategy] = None,
+    ) -> None:
+        self.tx_filter = tx_filter
+        self.log_filter = log_filter
+        self.strategy = strategy
+
+    async def process_block(self, block) -> None:
+        txs = parse_block(block)
+
+        for tx in txs:
+            if self.tx_filter and self.tx_filter.match(tx):
+                await self.strategy.execute(tx)
+
+    async def process_log(self, log) -> None:
+        log = parse_log(log)
+        log_args = log.get("args", {})
+        print(f"Decoded log args: {log_args}")
+
+        # LogFilter post-filter rules (optional — if none, all pass)
+        if self.log_filter and not self.log_filter.match(log_args):
+            return
+
+        await self.strategy.execute_log(log_args)

chain_sniper-0.1.0/chain_sniper/engine/worker.py

@@ -0,0 +1,7 @@
+class Worker:
+    def __init__(self):
+        pass
+
+    async def run(self):
+        # Implementation for parallel or background worker
+        pass

chain_sniper-0.1.0/chain_sniper/filters/__init__.py

@@ -0,0 +1,14 @@
+"""
+Filter implementations for Chain Sniper.
+
+- ``TransactionFilter`` — local block / transaction rule matching.
+- ``LogFilter``          — node-level log subscriptions + optional post-filter.
+"""
+
+from ._transaction_filter import TransactionFilter
+from ._log_filter import LogFilter
+
+__all__ = [
+    "TransactionFilter",
+    "LogFilter",
+]