Shred API Notes

[degenRobot]

Shred API Notes

• Timestamp field in Shred type
• Connection status/state methods
• Dynamic subscription management
• Request queuing during disconnection
• Performance metrics and monitoring
• Exponential backoff for reconnection

⚠️ Partially Implemented:

• Shred data structure (types exist but fields not populated correctly)
• Error handling (basic but could be enhanced)

A. Technical API Changes

1. Fix Shred Data Structure (Partially Implemented)

Current State: The type definition includes blockNumber and shredIndex but not shredId or timestamp. In testing, these fields return undefined/null.
Suggestion:

• Add timestamp field to the Shred type
• Ensure shredIndex is properly populated (currently returning undefined)
• Consider adding a computed shredId field that combines blockNumber + shredIndex for unique identification
  Reason: The current implementation returns incomplete data structures, making it impossible to uniquely identify shreds or know when they were created
  Impact: Developers can properly track, deduplicate, and correlate shreds with blockchain events

2. Enhance WebSocket Reconnection Logic (Basic Implementation Exists)

Current State: The transport already includes reconnection with configurable attempts (default: 5) and delay (default: 2000ms), but uses fixed delay not exponential backoff
Suggestion: Enhance the existing reconnection to use exponential backoff instead of fixed delay

// Current: fixed delay
setTimeout(() => this.connect(), this.reconnectDelay);

// Suggested: exponential backoff
const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts);
setTimeout(() => this.connect(), delay);

Reason: Exponential backoff prevents overwhelming the server during outages and follows best practices
Impact: More graceful recovery during server restarts or network issues

3. Add Connection Status Methods (Not Implemented)

Current State: No connection status methods exposed in the public API
Suggestion: Add connection state tracking to the transport and expose it through the client

interface ShredClient {
  getConnectionStatus(): "connecting" | "connected" | "disconnected" | "error";
  onConnectionChange(callback: (status: ConnectionStatus) => void): void;
  isConnected(): boolean;
  getConnectionStats(): {
    connectedAt?: number;
    reconnectAttempts: number;
    lastError?: Error;
  };
}

Reason: Developers have no way to show connection status to users or handle disconnections gracefully
Impact: Enables proper UI feedback and proactive error handling in applications

4. Add Dynamic Subscription Management (Not Implemented)

Current State: Subscriptions are immutable once created - you must unsubscribe and resubscribe to change filters
Suggestion: Add methods to modify active subscriptions without losing event history

interface Subscription {
  id: string;
  addAddress(address: string): Promise<void>;
  removeAddress(address: string): Promise<void>;
  getAddresses(): string[];
  updateTopics(topics: string[]): Promise<void>;
  pause(): void;
  resume(): void;
}

Reason: Factory patterns and dynamic contracts require flexible subscription management without losing connection state
Impact: Enables complex dApp patterns like DEX routers, NFT factories, and multi-contract monitoring

5. Implement Request Queuing (Not Implemented)

Current State: Requests fail immediately if the connection is down - no queuing mechanism exists
Suggestion: Add optional request queuing for resilient operation

interface QueueOptions {
  enabled: boolean;
  maxSize: number;
  maxAge: number; // ms
  onOverflow: "drop-oldest" | "drop-newest" | "reject";
}

class RequestQueue {
  enqueue(request: Request): Promise<Response> {
    if (this.isConnected) {
      return this.send(request);
    }
    return this.queueRequest(request);
  }
}

Reason: Critical requests (like transactions) shouldn't be lost during brief disconnections
Impact: Ensures reliable delivery for important operations, improving user experience significantly

6. Add Performance Metrics (Not Implemented)

Current State: No performance monitoring or metrics collection exists
Suggestion: Add opt-in performance tracking with minimal overhead

interface ShredMetrics {
  connection: {
    uptime: number;
    reconnects: number;
    lastError?: Error;
  };
  performance: {
    avgLatency: number;
    shredsPerSecond: number;
    eventsProcessed: number;
    bytesReceived: number;
  };
  subscriptions: {
    active: number;
    total: number;
  };
}

client.getMetrics(): ShredMetrics;
client.enableMetrics(options?: MetricsOptions): void;

Reason: Production applications need visibility into connection health and performance
Impact: Enables proactive monitoring, debugging, and performance optimization