Merge pull request #42 from VaitaR/chore/remove-legacy

chore: remove legacy stack and finalize mixin-based client API

Author: VaitaR

.github/workflows/test-install.yml

@@ -55,8 +55,8 @@ jobs:
           # Verify main modules
           python -c "from aiochainscan import ChainscanClient, Method; print('✓ Main classes imported')"
 
-          # Verify facade imports
-          python -c "from aiochainscan import get_balance, get_block, get_transaction; print('✓ Facades imported')"
+          # Verify modern public API
+          python -c "from aiochainscan import ChainscanClient, Method, SmartContract, DecodedEvent, DecodedTransaction; print('✓ Modern public API imported')"
 
           # Verify CLI is available
           which aiochainscan || echo "⚠ CLI not found"
@@ -181,7 +181,7 @@ jobs:
           print(f'Package location: {pkg_path}')
 
           # Check for key modules
-          modules = ['client', 'config', 'network', 'core', 'services', 'adapters', 'ports', 'domain']
+          modules = ['config', 'network', 'core', 'services', 'adapters', 'ports', 'domain']
           for mod in modules:
               mod_path = os.path.join(pkg_path, mod + '.py')
               dir_path = os.path.join(pkg_path, mod)

.importlinter

@@ -16,7 +16,6 @@ forbidden_modules =
     aiochainscan.services
     aiochainscan.adapters
     aiochainscan.core
-    aiochainscan.modules
     aiochainscan.scanners
 
 [importlinter:contract:2]
@@ -28,7 +27,6 @@ forbidden_modules =
     aiochainscan.services
     aiochainscan.adapters
     aiochainscan.core
-    aiochainscan.modules
     aiochainscan.scanners
 
 [importlinter:contract:3]

AGENTS.md

@@ -11,15 +11,18 @@ Async Python wrapper for blockchain explorer APIs (Etherscan, BlockScout). Unifi
 
 ## Quick Start for Agents
 
+> Public API policy: use `ChainscanClient` only.
+> Legacy facade/context/url-builder entrypoints and old pagination-engine docs are removed from agent workflows.
+
 ### Primary Interface (USE THIS)
 ```python
-from aiochainscan.core.client import ChainscanClient
+from aiochainscan import ChainscanClient
 
 async with ChainscanClient.from_config('blockscout_v2', 'ethereum') as client:
     # ── Account ──────────────────────────────────────────────
     balance = await client.get_balance('0x...')                   # Wei string
     txs     = await client.get_transactions('0x...')              # single page
-    all_txs = await client.get_all_transactions('0x...')          # ALL (paginated)
+    all_txs = await client.get_all_transactions('0x...')          # ALL (streaming aggregation → list)
     itxs    = await client.get_internal_transactions('0x...')     # single page
     erc20   = await client.get_token_transfers('0x...')           # single page
     erc721  = await client.get_erc721_transfers('0x...')          # single page
@@ -56,7 +59,7 @@ async with ChainscanClient.from_config('blockscout_v2', 'ethereum') as client:
 
     # ── Event Logs ───────────────────────────────────────────
     logs     = await client.get_logs('0x...', from_block=0)       # single page (≤1000)
-    all_logs = await client.get_all_logs('0x...', from_block=0)   # ALL (paginated)
+    all_logs = await client.get_all_logs('0x...', from_block=0)   # ALL (streaming aggregation → list)
 
     # ── Proxy / JSON-RPC ─────────────────────────────────────
     result  = await client.eth_call('0xTO', '0xDATA')             # eth_call
@@ -82,11 +85,12 @@ async with ChainscanClient.from_config('blockscout_v2', 'ethereum') as client:
 ### ⚠️ Key Gotchas
 - `get_transactions()` returns **one page** (~50-100 items). Use `get_all_transactions()` for complete data.
 - `get_logs()` returns **≤1000 logs**. Use `get_all_logs()` for complete data.
+- `get_all_*()` now uses **streaming aggregation** under the hood; for very large datasets prefer `iter_*_streaming()`.
 - `get_transactions_df()` auto-paginates (uses `iter_transactions` internally).
 - Balance/value/supply values are **Wei strings** — divide by `10**18` for ETH.
 
 > **Note:** Legacy `Client` class and `modules/` were removed in v0.3.0.
-> Facade functions (`get_balance`, etc.) are **DEPRECATED** in v0.4.0 — use `ChainscanClient`.
+> Legacy facade/context/url-builder public entrypoints and old pagination-engine usage were purged in modern API docs.
 
 ---
 
@@ -132,7 +136,7 @@ Every `Method` enum value (28 total) maps to typed convenience methods on `Chain
 | Pattern | Use When | Memory |
 |---|---|---|
 | `get_transactions(address)` | Quick look, small wallets | Low |
-| `get_all_transactions(address)` | Need ALL data, moderate wallets | Grows with data |
+| `get_all_transactions(address)` | Need ALL data (built via streaming aggregation) | Grows with data |
 | `iter_transactions_streaming(address)` | Large wallets (1M+ txs) | Constant ~10MB |
 | `get_transactions_df(address)` | Data analysis (Polars) | Grows with data |
 
@@ -142,8 +146,8 @@ Every `Method` enum value (28 total) maps to typed convenience methods on `Chain
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                      FACADE LAYER                            │
-│  core/client.py (ChainscanClient) | domain/contract.py      │
+│                    CLIENT / DOMAIN LAYER                     │
+│  core/client.py (ChainscanClient) | domain/contract.py       │
 └─────────────────────────┬───────────────────────────────────┘
                           │
 ┌─────────────────────────▼───────────────────────────────────┐
@@ -152,9 +156,9 @@ Every `Method` enum value (28 total) maps to typed convenience methods on `Chain
 └─────────────────────────┬───────────────────────────────────┘
                           │
 ┌─────────────────────────▼───────────────────────────────────┐
-│                    SERVICE LAYER                             │
-│  paging_engine.py | streaming_decoder.py | chunked_fetcher  │
-│  ens_resolver.py | unified_fetch.py | analytics.py          │
+│                   AGGREGATION SERVICES                       │
+│  account.py | logs.py | streaming_decoder.py | analytics.py  │
+│  ens_resolver.py | chunked_fetcher.py                        │
 └─────────────────────────┬───────────────────────────────────┘
                           │
 ┌─────────────────────────▼───────────────────────────────────┐
@@ -262,9 +266,10 @@ Every `Method` enum value (28 total) maps to typed convenience methods on `Chain
 5. Register in `scanners/__init__.py`
 
 ### Adding Bulk Fetch Support
-1. Use `paging_engine.fetch_all_generic()` with `FetchSpec`
-2. For streaming: use `paging_streaming.fetch_all_generic_streaming()`
-3. Always pass `on_progress` callback through to engine
+1. Extend `ChainscanClient` methods and scanner `SPECS` first
+2. Keep `get_all_*` behavior as materialized results from streaming aggregation
+3. Add/maintain matching `iter_*_streaming` path for large datasets
+4. Always thread `on_progress` callbacks through public client methods
 
 ### Modifying HTTP Behavior
 - Rate limiting: `adapters/aiolimiter_adapter.py` (burst=1 for APIs)
@@ -299,7 +304,7 @@ async for batch in client.iter_transactions_streaming(address, batch_size=1000):
 
 ### Get ALL Data (Paginated)
 ```python
-# These handle pagination automatically:
+# These use streaming aggregation internally and return materialized lists:
 all_txs = await client.get_all_transactions(address)
 all_logs = await client.get_all_logs(address, from_block=0, topic0='0xddf252...')
 all_transfers = await client.get_all_token_transfers(address)
@@ -310,9 +315,9 @@ all_internal = await client.get_all_internal_transactions(address)
 ```python
 from aiochainscan.utils.progress_helpers import console_progress
 
-txs = await fetch_all_transactions_fast(
-    ...,
-    on_progress=console_progress()  # Real-time feedback
+txs = await client.get_all_transactions(
+    address,
+    on_progress=console_progress(),  # Real-time feedback
 )
 ```
 

README.md

@@ -18,7 +18,7 @@ Provides a single, consistent API for accessing blockchain data across multiple
 - **⚡ Built-in Rate Limiting** - Automatic throttling with configurable limits and retry policies
 - **🎯 Comprehensive API Coverage** - 28 blockchain operations with typed convenience methods
 - **🔒 Type-safe Operations** - Typed data transfer objects, method enums, 100% mypy --strict
-- **🚀 Optimized Bulk Operations** - Pagination engine, streaming decoder, range-splitting aggregators
+- **🚀 Optimized Bulk Operations** - Streaming aggregation for `get_all_*` plus `iter_*_streaming` for low-memory processing
 - **🧩 Dependency Injection** - Configurable HTTP clients, caching, telemetry, and rate limiters
 - **⛓️ Rust FFI** - Fast ABI decoding via PyO3 with LRU cache
 
@@ -44,7 +44,7 @@ pip install .
 import aiochainscan
 print(f"aiochainscan v{aiochainscan.__version__}")
 
-from aiochainscan import get_balance, get_block
+from aiochainscan import ChainscanClient
 print("✓ Installation successful!")
 ```
 
@@ -152,7 +152,7 @@ The **ChainscanClient** provides a unified interface with **30+ typed convenienc
 
 ```python
 import asyncio
-from aiochainscan.core.client import ChainscanClient
+from aiochainscan import ChainscanClient
 
 async def main():
     # Create client — async context manager handles cleanup
@@ -162,7 +162,7 @@ async def main():
         print(f"Balance: {int(balance) / 10**18:.6f} ETH")
 
         txs = await client.get_transactions('0x...')           # single page
-        all_txs = await client.get_all_transactions('0x...')    # ALL (paginated)
+        all_txs = await client.get_all_transactions('0x...')    # ALL (streaming aggregation → list)
         tokens = await client.get_token_portfolio('0x...')      # ERC-20 holdings
 
         # Blocks & transactions
@@ -180,9 +180,9 @@ async def main():
 
         # Event logs (single page or ALL)
         logs = await client.get_logs('0x...', from_block=0)
-        all_logs = await client.get_all_logs('0x...', from_block=0)
+        all_logs = await client.get_all_logs('0x...', from_block=0)  # streaming aggregation → list
 
-        # Streaming for large datasets (~10MB RAM for 1M+ txs)
+        # Preferred for large datasets (~10MB RAM for 1M+ txs)
         async for batch in client.iter_transactions_streaming('0x...', batch_size=1000):
             process(batch)
 
@@ -201,63 +201,18 @@ client = ChainscanClient.from_config('blockscout_v2', 'ethereum')
 client = ChainscanClient.from_config('etherscan', 'ethereum')
 ```
 
-### 4. ⚠️ Legacy Facade Functions (Deprecated)
-
-**WARNING**: Facade functions are deprecated in v0.4.0 and will be removed in v0.5.0 due to critical connection pooling issues.
-
-<details>
-<summary>Why are facade functions deprecated? (Click to expand)</summary>
-
-**The Problem**: Each facade function call creates and destroys an HTTP client, preventing connection pooling:
-
-```python
-# ❌ AVOID - Creates 100 separate HTTP clients (very slow!)
-balances = await asyncio.gather(*[
-    get_balance(address=addr, api_kind='eth', network='main', api_key=key)
-    for addr in addresses  # 100 addresses
-])
-```
-
-This causes:
-- 100 TCP connection establishments
-- 100 TLS handshakes
-- Loss of HTTP/2 multiplexing
-- High CPU load and API rate limits
+### 4. Legacy API Purge (v0.5+)
 
-**The Solution**: Use `ChainscanClient` which maintains a persistent connection pool (see examples above).
+Public usage is now **ChainscanClient-only**.
 
-</details>
+Removed legacy surfaces:
+- Top-level facade functions (`get_balance`, `get_block`, etc.)
+- Legacy facade/context/url-builder orchestration services
+- Older pagination engines replaced by modern streaming aggregation
 
-For simple use cases, you can still use facade functions (but expect deprecation warnings):
-
-```python
-import asyncio
-from aiochainscan import get_balance, get_block
-
-async def main():
-    # BlockScout (free, no API key needed)
-    balance = await get_balance(
-        address='0x742d35Cc6634C0532925a3b8D9fa7a3D91D1e9b3',
-        api_kind='blockscout_sepolia',
-        network='sepolia',
-        api_key=''
-    )
-
-    # Etherscan (requires API key)
-    block = await get_block(
-        tag=17000000,
-        api_kind='eth',
-        network='main',
-        api_key='YOUR_ETHERSCAN_API_KEY'
-    )
+Use `get_all_*` when you need fully materialized results (it now uses streaming aggregation internally), and prefer `iter_*_streaming` for large datasets.
 
-    print(f"Balance: {balance} wei")
-    print(f"Block: #{block['block_number']}")
-
-asyncio.run(main())
-```
-
-**Migration Path**: See [MIGRATION_GUIDE.md](docs/MIGRATION_GUIDE.md) for detailed migration instructions.
+Migration details: [MIGRATION_GUIDE.md](docs/MIGRATION_GUIDE.md).
 
 ### 5. Bulk Operations & Streaming
 
@@ -301,7 +256,7 @@ For advanced use cases with custom rate limiting, retries, and dependency inject
 
 ```python
 import asyncio
-from aiochainscan.core.client import ChainscanClient
+from aiochainscan import ChainscanClient
 from aiochainscan.core.method import Method
 from aiochainscan.adapters.simple_rate_limiter import SimpleRateLimiter
 from aiochainscan.adapters.retry_exponential import ExponentialBackoffRetry
@@ -353,7 +308,7 @@ The **ChainscanClient** makes it trivial to switch between different blockchain
 
 ```python
 import asyncio
-from aiochainscan.core.client import ChainscanClient
+from aiochainscan import ChainscanClient
 from aiochainscan.core.method import Method
 
 async def check_multi_scanner_balance():
@@ -395,29 +350,23 @@ async def check_multi_scanner_balance():
 asyncio.run(check_multi_scanner_balance())
 ```
 
-### Legacy Multiple Networks (Facade Functions)
-
-For simple cases, you can still use the legacy facade functions:
+### Multiple Networks with ChainscanClient
 
 ```python
 import asyncio
-from aiochainscan import get_balance
+from aiochainscan import ChainscanClient
 
 async def check_balances():
-    # Works with multiple scanners using legacy interface
-    networks = [
-        ('blockscout_sepolia', 'sepolia', ''),          # Blockscout (free)
-        ('eth', 'main', 'YOUR_ETHERSCAN_KEY'),          # Etherscan
+    address = "0x742d35Cc6634C0532925a3b8D9fa7a3D91D1e9b3"
+    targets = [
+        ("blockscout_v2", "ethereum"),
+        ("etherscan", "ethereum"),
     ]
 
-    for api_kind, network, api_key in networks:
-        balance = await get_balance(
-            address="0x742d35Cc6634C0532925a3b8D9fa7a3D91D1e9b3",
-            api_kind=api_kind,
-            network=network,
-            api_key=api_key
-        )
-        print(f"{api_kind} {network}: {balance} wei")
+    for scanner_name, network in targets:
+        async with ChainscanClient.from_config(scanner_name, network) as client:
+            balance = await client.get_balance(address)
+            print(f"{scanner_name} {network}: {balance} wei")
 
 asyncio.run(check_balances())
 ```
@@ -435,7 +384,7 @@ export ETHERSCAN_KEY="your_etherscan_api_key"
 
 When using `ChainscanClient.from_config()`, you need to specify three key parameters:
 
-- **scanner_name**: Provider name (`'etherscan'`, `'blockscout'`, `'moralis'`, etc.)
+- **scanner_name**: Provider name (`'etherscan'`, `'blockscout'`, `'blockscout_v2'`)
 - **scanner_version**: API version (`'v1'`, `'v2'`)
 - **network**: Chain name/ID (`'eth'`, `'ethereum'`, `1`, `'base'`, `8453`, etc.)
 
@@ -456,20 +405,20 @@ When using `ChainscanClient.from_config()`, you need to specify three key parame
 
 ## Available Interfaces
 
-The library provides two main interfaces for accessing blockchain data:
+The public interface is **ChainscanClient**.
 
 ### 1. ChainscanClient (Recommended)
 
 The **unified client** provides 30+ typed convenience methods:
 
 ```python
-from aiochainscan.core.client import ChainscanClient
+from aiochainscan import ChainscanClient
 
 async with ChainscanClient.from_config('blockscout_v2', 'ethereum') as client:
     # Account
     balance = await client.get_balance('0x...')                   # Wei string
     txs     = await client.get_transactions('0x...')              # single page
-    all_txs = await client.get_all_transactions('0x...')          # ALL (paginated)
+    all_txs = await client.get_all_transactions('0x...')          # ALL (streaming aggregation → list)
     itxs    = await client.get_internal_transactions('0x...')     # internal txs
     erc20   = await client.get_token_transfers('0x...')           # ERC-20 transfers
     erc721  = await client.get_erc721_transfers('0x...')          # ERC-721 transfers
@@ -506,7 +455,7 @@ async with ChainscanClient.from_config('blockscout_v2', 'ethereum') as client:
 
     # Event Logs
     logs     = await client.get_logs('0x...', from_block=0)       # single page
-    all_logs = await client.get_all_logs('0x...', from_block=0)   # ALL (paginated)
+    all_logs = await client.get_all_logs('0x...', from_block=0)   # ALL (streaming aggregation → list)
 
     # Proxy / JSON-RPC
     result  = await client.eth_call('0xTO', '0xDATA')             # eth_call
@@ -535,24 +484,18 @@ from aiochainscan.core.method import Method
 result = await client.call(Method.ACCOUNT_BALANCE, address='0x...')
 ```
 
-### 3. Legacy Facade Functions (Deprecated)
-
-Facade functions are deprecated in v0.4.0. Use `ChainscanClient` instead.
-
 ## Error Handling
 
 ```python
 import asyncio
+from aiochainscan import ChainscanClient
 from aiochainscan.exceptions import ChainscanClientApiError
 
 async def main():
     try:
-        balance = await get_balance(
-            address='0x...',
-            api_kind='eth',
-            network='main',
-            api_key='YOUR_API_KEY'
-        )
+        async with ChainscanClient.from_config('etherscan', 'ethereum') as client:
+            balance = await client.get_balance('0x...')
+            print(balance)
     except ChainscanClientApiError as e:
         print(f"API Error: {e}")