feat: add WebSocket subscription support for consensus events

[AgustinRamiroDiaz]

Summary

• Add WebSocket-based event subscription methods to GenLayerClient for real-time consensus event streaming
• New subscription methods: subscribeToNewTransaction, subscribeToTransactionAccepted, subscribeToTransactionActivated, subscribeToTransactionUndetermined, subscribeToTransactionLeaderTimeout
• Returns typed async iterable streams (ConsensusEventStream<T>) that can be consumed with for await...of
• Add webSocketEndpoint config option to createClient()

Features

• Typed event streams: Each subscription returns a strongly-typed ConsensusEventStream<T>
• Shared WebSocket client: Uses WeakMap cache to share a single WS connection per GenLayerClient
• Memory safety: Bounded event queue (max 1000 events) prevents unbounded memory growth
• Error handling: Errors propagate through the async iterator with proper logging
• Clean unsubscribe: Call stream.unsubscribe() to stop listening and clean up resources

Usage

const client = createClient({
  chain: testnetAsimov,
  webSocketEndpoint: 'wss://genlayer-testnet.rpc.caldera.xyz/ws',
});

// Subscribe to new transactions
const stream = client.subscribeToNewTransaction();

for await (const event of stream) {
  console.log('New tx:', event.txId, event.recipient);
}

// Or manually control the subscription
stream.unsubscribe();

Test plan

• Build passes (npm run build)
• TypeScript compiles (tsc --noEmit)
• Lint passes (npm run lint)
• Unit tests pass (npm test)
• Manual test with actual WebSocket endpoint

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

• 🔍 Trigger a full review

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch new-features-for-appealers

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}