docs: clarify batch optimizer preview status and limitations

Address CodeRabbit review feedback by clearly documenting that:
- Gas estimation uses average values (71k/tx) not actual estimateGas calls
- Execute endpoint provides cost estimates only, does not queue transactions
- Status endpoint returns placeholder data pending queue integration

Changes:
- Add prominent "Preview Status" warning section to BATCH_OPTIMIZER.md
- Update execute endpoint to return "estimated" status with clear warning message
- Update status endpoint to indicate "estimated" state with limitation notice
- Add warning field to batchStatusSchema for API transparency
- Add detailed TODO comments explaining integration needs

This makes it crystal clear to users that this is a demonstration/preview
feature showing the API design and cost analysis capabilities, while actual
transaction execution requires integration with SendTransactionQueue.

Addresses CodeRabbit issues: placeholder gas estimation, non-functional
execute endpoint, and placeholder status tracking

Author: anuragchvn-blip

docs/BATCH_OPTIMIZER.md

@@ -1,8 +1,33 @@
 # Smart Transaction Batch Optimizer 🚀
 
+## ⚠️ Preview Status
+
+**This feature is currently in PREVIEW mode for demonstration and testing purposes.**
+
+**Current Limitations:**
+- ✅ Gas price analysis and cost estimation - **WORKING**
+- ✅ Batch metadata caching and tracking - **WORKING**  
+- ⚠️ **Gas estimation uses average values (71k gas/tx) instead of actual estimateGas calls**
+- ⚠️ **Execute endpoint does NOT actually queue transactions to blockchain**
+- ⚠️ **Status endpoint returns placeholder data only**
+
+**Use this feature to:**
+- Explore the batch optimizer API design
+- Test cost estimation and gas price analysis
+- Evaluate potential gas savings for your use case
+
+**Production Integration Required:**
+- Integration with `SendTransactionQueue` for actual execution
+- Real `eth_estimateGas` calls for accurate gas estimates
+- Database/queue polling for transaction status tracking
+
+See "Future Enhancements" section for full production roadmap.
+
+---
+
 ## Overview
 
-A game-changing feature that helps users **save 15-30% on gas costs** while giving thirdweb Engine unprecedented scalability through intelligent transaction batching and cost optimization.
+A feature designed to help users **save 15-30% on gas costs** while giving thirdweb Engine unprecedented scalability through intelligent transaction batching and cost optimization.
 
 ## Why This Matters
 

src/server/routes/transaction/batch-optimizer.ts

@@ -119,6 +119,7 @@ const executeBatchRequestSchema = Type.Object({
 const batchStatusSchema = Type.Object({
   batchId: Type.String(),
   status: Type.Literal("pending")
+    .Or(Type.Literal("estimated"))
     .Or(Type.Literal("queued"))
     .Or(Type.Literal("processing"))
     .Or(Type.Literal("completed"))
@@ -133,6 +134,7 @@ const batchStatusSchema = Type.Object({
       transactionHash: Type.Optional(Type.String()),
     }),
   ),
+  warning: Type.Optional(Type.String()),
 });
 
 // Helper to generate batch ID
@@ -151,12 +153,17 @@ const getBatchData = async (batchId: string) => {
 };
 
 // Estimate gas for transactions
+// NOTE: This is a simplified estimation using average gas values.
+// TODO: Replace with actual estimateGas calls for production accuracy.
+// Current implementation provides conservative estimates but may not reflect
+// actual gas costs for complex contract interactions.
 const estimateGasForBatch = async (
   chainId: number,
   transactions: any[],
 ): Promise<bigint> => {
-  // Simplified estimation - in production, would call estimateGas for each
-  const avgGasPerTx = 21000n + 50000n; // Base + avg contract interaction
+  // Using average gas: 21k (base transfer) + 50k (avg contract call)
+  // Real implementation should call eth_estimateGas for each transaction
+  const avgGasPerTx = 21000n + 50000n;
   return BigInt(transactions.length) * avgGasPerTx;
 };
 
@@ -374,25 +381,27 @@ export async function executeBatchTransactions(fastify: FastifyInstance) {
 
       const { fromAddress, chainId, transactions, optimization } = batchData;
 
-      // TODO: Integrate with actual transaction queue
-      // For now, return success with placeholder queue IDs
+      // IMPORTANT: This is a placeholder implementation
+      // TODO: Integrate with SendTransactionQueue to actually queue transactions
+      // Current implementation only estimates and caches batch data for demonstration
       const queueIds = transactions.map(
         (_: any, i: number) => `${batchId}_tx_${i}`,
       );
 
       // Update batch status in Redis
       await cacheBatchData(batchId, {
         ...batchData,
-        status: "queued",
+        status: "estimated", // Changed from "queued" to reflect actual state
         queueIds,
-        executedAt: Date.now(),
+        estimatedAt: Date.now(),
       });
 
       reply.status(StatusCodes.OK).send({
         batchId,
-        status: "queued",
-        message: `Batch of ${transactions.length} transactions queued for execution with ${optimization} optimization`,
+        status: "estimated",
+        message: `Batch of ${transactions.length} transactions estimated. Note: Actual execution integration pending - this endpoint currently provides cost estimates only.`,
         queueIds,
+        warning: "Batch optimizer is in preview mode. Transactions are not actually queued for execution yet.",
       });
     },
   );
@@ -430,20 +439,23 @@ export async function getBatchStatus(fastify: FastifyInstance) {
 
       const { transactions, queueIds = [] } = batchData;
 
-      // TODO: Get actual transaction statuses from queue
+      // IMPORTANT: Placeholder status implementation
+      // TODO: Query actual transaction statuses from SendTransactionQueue/database
+      // Current implementation only returns cached estimation data
       const txStatuses = queueIds.map((queueId: string, i: number) => ({
         queueId,
-        status: "pending",
+        status: "estimated", // Reflects that transactions are not actually queued
         transactionHash: undefined,
       }));
 
       const response = {
         batchId,
-        status: batchData.status || "pending",
+        status: batchData.status || "estimated",
         transactionCount: transactions.length,
         completedCount: 0,
         failedCount: 0,
         transactions: txStatuses,
+        warning: "Batch optimizer is in preview mode. Status tracking not yet implemented.",
       } satisfies Static<typeof batchStatusSchema>;
 
       reply.status(StatusCodes.OK).send(response);