Skip to content

Commit cd63b9c

Browse files
authored
webhook metadata (#15)
* update docs * webhook metadata + eoa retry changes
1 parent 5259777 commit cd63b9c

File tree

13 files changed

+607
-353
lines changed

13 files changed

+607
-353
lines changed

HOW_IT_WORKS.md

Lines changed: 0 additions & 313 deletions
This file was deleted.

README.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,31 @@ Advanced Redis-backed job queue with enterprise features:
6262
- **Webhook Delivery**: Reliable HTTP webhook notifications with configurable retries
6363
- **Transaction Confirmation**: Block confirmation tracking with reorganization handling
6464
- **External Bundler Integration**: UserOperation submission and status monitoring
65+
- **EOA Transaction Processing**: Production-grade EOA (Externally Owned Account) transaction management with advanced nonce handling, crash recovery, and optimal throughput
66+
67+
##### EOA Executor Deep Dive
68+
69+
The EOA executor implements a sophisticated single-worker-per-EOA architecture that ensures transaction consistency while maximizing throughput:
70+
71+
**Key Features:**
72+
- **Crash-Resilient Recovery**: Borrowed transaction pattern prevents loss during worker restarts
73+
- **Intelligent Nonce Management**: Optimistic nonce allocation with recycling for failed transactions
74+
- **Three-Phase Processing**: Recovery → Confirmation → Send phases ensure complete transaction lifecycle management
75+
- **Adaptive Capacity Control**: Dynamic in-flight transaction limits based on network conditions
76+
- **Health Monitoring**: Automatic EOA balance checking with funding state awareness
77+
78+
**Transaction Flow:**
79+
1. **Recovery Phase**: Rebroadcasts any prepared transactions from crashes
80+
2. **Confirmation Phase**: Efficiently tracks transaction confirmations using nonce progression
81+
3. **Send Phase**: Processes new transactions with recycled nonce prioritization and capacity management
82+
83+
**Error Classification:**
84+
- **Deterministic Failures**: Immediate requeue with nonce recycling (invalid signatures, malformed transactions)
85+
- **Success Cases**: Transaction tracking for known/duplicate transactions
86+
- **Indeterminate Cases**: Optimistic handling for network timeouts and unknown errors
87+
88+
This architecture provides strong consistency guarantees while handling high-volume transaction processing with graceful degradation under network stress.
89+
For more details, see [README_EOA.md](README_EOA.md).
6590

6691
### Thirdweb Service Integration (`thirdweb-core/`)
6792
**Purpose**: First-party service integrations
@@ -261,6 +286,11 @@ cargo nextest run -p twmq --profile ci
261286
│ └── src/
262287
│ ├── webhook/ # Webhook delivery
263288
│ └── external_bundler/ # AA bundler integration
289+
│ └── eoa/ # EOA transaction processing
290+
│ ├── worker/ # Main worker logic
291+
│ ├── store/ # Redis-backed state management
292+
│ ├── events.rs # Transaction lifecycle events
293+
│ └── error_classifier.rs # Error categorization
264294
└── thirdweb-core/ # Thirdweb integrations
265295
```
266296

@@ -377,3 +407,4 @@ For issues and questions:
377407
---
378408

379409
**Built with ❤️ by the Thirdweb team**
410+

0 commit comments

Comments
 (0)