Features & Architecture (deep dive)

4.1 Modular Structure

• server.js

• services/

• routes/

• database/

• blockchain/

• middleware/

• utils/

Real-time Contract Discovery

Discovery is driven by live WebSocket event monitoring. The backend listens for Stylus-specific deployment events (e.g., ProgramActivated) and for developer-driven opt-ins such as AutoCacheOptIn. When a relevant event appears, the discovery pipeline:

• records the contract in the DB,

• runs a quick isCacheable() probe call to validate cache eligibility,

• tags the contract state (discovered → checked → opted-in).

Manual checks are also supported through API endpoints, so operators can force re-evaluation if necessary.

Why WebSockets?

WebSockets provide low-latency, continuous event streams. The backend centralizes provider management (automatic reconnection, per-network providers) so event handling stays robust under transient network issues.

---

ROI-Based Bidding Logic

Bidding is not blind: the backend runs a return-on-investment evaluation before placing any bid. The bidding pipeline includes:

• fetching the latest suggested bid values (cached per-network),

• projecting gas savings using historic/estimated usage,

• comparing expected savings vs. required bid + gas costs,

• validating wallet balance and gas estimates,

• placing a transaction only if expected ROI > configured threshold.

The ROI threshold is configurable (default 10%). All bid attempts are recorded (success/failure) with detail for post-mortem analysis.

---

Structured Logging & Monitoring

Observability is first-class. The backend uses Winston to produce structured logs with multiple transport layers. Logs include:

• request/response traces with unique request IDs,

• blockchain event logs (deployments, opt-ins, bid outcomes),

• database operation logs and performance warnings,

• unhandled exceptions and promise rejection logs.

Operators can tail logs/combined.log for activity or inspect logs/error.log for failures.

---

WebSocket & Provider Management

The backend centralizes WebSocket connections using a provider manager. Key features:

• single place to configure WS endpoints (via env variables),

• automatic reconnection with exponential backoff,

• topic-based listeners for ProgramActivated, AutoCacheOptIn, and other relevant topics,

• graceful shutdown to close sockets cleanly on process exit.

Environment variable support ensures you can swap endpoints without changing code.

---

Automatic Caching Flow (step-by-step)

1. Detect: ProgramActivated event arrives via WebSocket.

2. Probe: call isCacheable() to confirm backend-level eligibility.

3. Analyze: run ROI calculation using the latest bid_values and usage estimates.

4. Decide: if ROI > threshold, prepare bid with gas estimate and wallet checks.

5. Execute: submit bid transaction to CacheManager and persist bid record.

6. Track: update contract status, persist logs, and emit monitoring metrics.

7. Repeat: backend continues monitoring and may refresh decisions as data evolves.

Database Integration & Schema

MongoDB stores contracts, bids, and bid value caches. Key contract document fields include contractAddress, deployedBy, network, minBidRequired, gasSaved, deployedAt, and roiAnalysis. The background updater refreshes bid_values per network and the system prunes old metadata using eviction thresholds to avoid storage blowup.

---

Multi-Network Support

The backend supports monitoring and bidding across multiple networks simultaneously. Configuration options:

• NETWORK for single-network operation (default)

• NETWORKS for parallel monitoring (e.g., NETWORKS=arbitrum-sepolia,arbitrum-one)

Bid values and CacheManager interactions are stored and handled per-network. Sample CacheManager addresses used by the backend:

• Arbitrum Sepolia: 0x0C9043D042aB52cFa8d0207459260040Cca54253

• Arbitrum One: 0x51dEDBD2f190E0696AFbEE5E60bFdE96d86464ec

Block-range and pagination strategies differ by network to respect RPC provider limits (e.g., Alchemy pagination on mainnet).