improve docs, wip

Author: mweinschenk

README.md

@@ -83,6 +83,21 @@ Sample JSON response:
 
 Security note: Private keys are shown once. Persist them securely (e.g. Vault, KMS). Never commit them.
 
+### Log Filtering & Event Decoding
+```php
+use EvmLogs;
+use Farbcode\LaravelEvm\Support\LogFilterBuilder;
+$abi = file_get_contents(storage_path('app/abi/ERC20.abi.json'));
+$logs = EvmLogs::query()
+    ->fromBlock(18_000_000)
+    ->toBlock('latest')
+    ->address('0xToken')
+    ->eventByAbi($abi, 'Transfer')
+    ->topicAny(1, [LogFilterBuilder::padAddress($addrA), LogFilterBuilder::padAddress($addrB)])
+    ->get();
+$decoded = array_map(fn($l) => LogFilterBuilder::decodeEvent($abi, $l), $logs);
+```
+
 ### Facades Overview
 
 Facade aliases (registered in `composer.json`):
@@ -95,6 +110,7 @@ Facade aliases (registered in `composer.json`):
 | `EvmSigner` | Signer |
 | `EvmFees` | FeePolicy |
 | `EvmNonce` | NonceManager |
+| `EvmLogs` | LogFilterBuilder |
 
 Example usage:
 ```php
@@ -105,6 +121,32 @@ $address = \EvmSigner::getAddress();
 // $fees = \EvmFees::suggest();
 ```
 
+### Chainable Casting
+
+`call()` now returns the client instance for fluent casting. Raw hex is stored internally. Use `result()` to fetch it, then `as(type)` to cast.
+
+```php
+$contract = \LaravelEvm::at('0xContract', $abi)->call('name');
+$raw = $contract->result(); // e.g. 0x0000...
+$name = $contract->as('string'); // decoded
+
+$owner = $contract->call('owner')->as('address');
+$supply = $contract->call('totalSupply')->as('uint');
+$flag = $contract->call('isActive')->as('bool');
+```
+
+Supported types: `string`, `address`, `uint|uint256`, `bool`, `bytes32` (returns hex). Unknown types fall back to raw value.
+
+### Signer Robustness & Environment
+
+Address derivation uses secp256k1 (via `kornrunner/ethereum-address`). On some PHP patch builds older GMP versions can throw a `ValueError` during point math with edge-case keys. Recommendations:
+1. Use a freshly generated private key (command above) – most issues disappear.
+2. Prefer latest PHP patch (8.4.x) where GMP edge cases are fixed.
+3. If derivation fails, you will get a `SignerException` with a clear message; do not bypass by hardcoding a mismatched address (nonce and signatures become inconsistent).
+4. For read-only calls in future you can implement a custom Signer driver returning only `getAddress()` without signing logic.
+
+If you consistently see overflow errors, open an issue with your PHP version, GMP version, and the (non-sensitive) pattern of the key (do NOT share the full private key). This helps us improve cross-version resilience without adding unsafe fallbacks.
+
 ## Testing
 
 ```bash

docs/.vitepress/config.mts

@@ -1,12 +1,18 @@
 import { defineConfig } from 'vitepress';
+import pkg from '../package.json'
 
 export default defineConfig({
   title: 'Laravel EVM',
   description: 'Reliable EVM interaction for Laravel (contracts, async transactions, fees, nonces, multi-RPC)',
-  srcDir: '.',
-  outDir: '../build/docs',
+  srcDir: './pages',
   cleanUrls: true,
   lastUpdated: true,
+  markdown: {
+        theme: {
+            light: 'github-light',
+            dark: 'github-dark'
+        }
+    },
   themeConfig: {
     nav: [
       { text: 'Guide', link: '/pages/README' },
@@ -60,7 +66,7 @@ export default defineConfig({
     ],
     footer: {
       message: 'MIT Licensed',
-      copyright: 'Copyright © 2025 Farbcode GmbH'
+      copyright: 'Copyright © 2025 //farbcode GmbH'
     }
   }
 });

docs/pages/architecture.md

@@ -103,3 +103,16 @@ Queue concurrency MUST be limited per address. Recommended: single worker for si
 - Plug-in system for fee strategies.
 - Configurable receipt polling backoff.
 - Adaptive RPC selection based on latency.
+
+## Log Filtering & Event Decoding
+A dedicated fluent builder (`LogFilterBuilder`) powers the `EvmLogs` facade for convenient retrieval and optional decoding of contract events:
+- `event('Transfer(address,address,uint256)')` sets topic0 (keccak hash of signature).
+- `eventByAbi($abi, 'Transfer')` resolves the signature from an ABI entry.
+- `topic(i, value)` / `topicAny(i, [...])` / `topicWildcard(i)` for selective indexed filtering.
+- `padAddress($addr)` produces a 32-byte padded address topic value.
+- `decodeEvent($abi, $log)` returns associative array of decoded indexed + non-indexed params (static types only).
+
+This keeps raw log querying decoupled from higher level transaction flow and enables post-processing / analytics (e.g. U18 election vote counting) without re‑implementing filtering logic.
+
+## Added Facade: EvmLogs
+The `EvmLogs` facade resolves the builder (container binding: `LogFilterBuilder::class`). It integrates seamlessly with other components and uses the already configured `RpcClient` for network access.

docs/pages/examples.md

@@ -93,5 +93,34 @@ If you detect repeated replacements:
 ## 14. Fee Escalation Monitoring
 Listen to `TxReplaced` and log attempt number and fee delta.
 
+## 15. Fetch and Decode Event Logs
+```php
+use EvmLogs; // facade
+use Farbcode\LaravelEvm\Support\LogFilterBuilder;
+
+$abi = file_get_contents(storage_path('app/abi/ERC20.abi.json'));
+$logs = EvmLogs::query()
+    ->fromBlock(18_000_000)
+    ->toBlock('latest')
+    ->address('0xTokenAddress')
+    ->eventByAbi($abi, 'Transfer')
+    ->topic(1, LogFilterBuilder::padAddress('0xSender'))
+    ->get();
+
+$decoded = array_map(fn($l) => LogFilterBuilder::decodeEvent($abi, $l), $logs);
+```
+OR topic match & wildcard:
+```php
+$logs = EvmLogs::query()
+    ->fromBlock('latest')
+    ->address(['0xTokenA','0xTokenB'])
+    ->event('Transfer(address,address,uint256)')
+    ->topicAny(1, [LogFilterBuilder::padAddress($addr1), LogFilterBuilder::padAddress($addr2)])
+    ->topicWildcard(2)
+    ->get();
+```
+
+Performance tip: split large ranges into windows for high-volume contracts.
+
 ---
 Next: [Transactions](/pages/transactions) | Previous: [Facades](/pages/facades)

docs/pages/facades.md

@@ -10,7 +10,8 @@ The package registers multiple facades to streamline access to underlying servic
 | `EvmRpc` | `RpcClient` | Raw JSON-RPC calls and health checks |
 | `EvmSigner` | `Signer` | Access signing key & related helpers |
 | `EvmFees` | `FeePolicy` | Suggest and adjust fees |
-| `EvmNonce` | `NonceManager` | Nonce tracking
+| `EvmNonce` | `NonceManager` | Nonce tracking |
+| `EvmLogs` | `LogFilterBuilder` | Log filtering and event decoding |
 
 ## Using `LaravelEvm`
 ```php
@@ -41,6 +42,39 @@ $key = EvmSigner::privateKey(); // avoid logging this
 $current = EvmNonce::current('0xSignerAddress');
 ```
 
+## EvmLogs (Log Filtering & Decoding)
+Fluent access to log filtering and basic event decoding.
+
+Methods:
+- `query()` start a builder.
+- `fromBlock($n)` / `toBlock($n)` / `blockHash($hash)` define range.
+- `address($addrOrArray)` filter by one or multiple contract addresses.
+- `event($signature)` set topic0 via keccak hash.
+- `eventByAbi($abi, $name)` resolve signature from ABI.
+- `topic($i, $value)` exact match at index.
+- `topicAny($i, [...])` OR match alternatives.
+- `topicWildcard($i)` allow any topic value at index.
+- `padAddress($addr)` helper to produce a 32-byte topic form for indexed addresses.
+- `decodeEvent($abi, $log)` return associative array of values.
+
+Example:
+```php
+$logs = EvmLogs::query()
+    ->fromBlock(18_000_000)
+    ->toBlock('latest')
+    ->address('0xContract')
+    ->event('Transfer(address,address,uint256)')
+    ->topic(1, LogFilterBuilder::padAddress($sender))
+    ->topicAny(2, [LogFilterBuilder::padAddress($recipientA), LogFilterBuilder::padAddress($recipientB)])
+    ->get();
+
+$decoded = array_map(fn($l) => LogFilterBuilder::decodeEvent($abi, $l), $logs);
+```
+
+Performance tip: For very large ranges split block intervals (e.g. batches of 5k blocks) and merge results.
+
+Security tip: Do not feed unvalidated user input directly into `event()` or `topic()` without sanity checks.
+
 ## Static Analysis
 The `LaravelEvm` facade includes `@method` annotations for IDE autocomplete and PHPStan awareness.