WebSocket Operations

/**
 * Subscribe to blockchain events
 * @param eventName - Type of event to subscribe to
 * @param listener - Callback function to handle events
 * @returns WebSocket instance for chaining
 */
on(eventName: AlchemyEventType, listener: AlchemyEventListener): this;

/**
 * Unsubscribe from blockchain events
 * @param eventName - Type of event to unsubscribe from
 * @param listener - Specific callback function to remove
 * @returns WebSocket instance for chaining
 */
off(eventName: AlchemyEventType, listener: AlchemyEventListener): this;

/**
 * Remove all listeners for an event type
 * @param eventName - Optional event type to remove all listeners for
 * @returns WebSocket instance for chaining
 */
removeAllListeners(eventName?: AlchemyEventType): this;

/**
 * Subscribe to events once (auto-unsubscribe after first event)
 * @param eventName - Type of event to subscribe to once
 * @param listener - Callback function to handle the event
 * @returns WebSocket instance for chaining
 */
once(eventName: AlchemyEventType, listener: AlchemyEventListener): this;

type AlchemyEventListener = (...args: any[]) => void;

enum AlchemyEventType {
  BLOCK = "block",
  PENDING_TRANSACTIONS = "alchemy_pendingTransactions",
  MINED_TRANSACTIONS = "alchemy_minedTransactions",
  NEW_HEADS = "alchemy_newHeads",
  LOGS = "logs",
  ADDRESS = "address",
  NFT_ACTIVITY = "alchemy_nftActivity",
  NFT_METADATA_UPDATE = "alchemy_nftMetadataUpdate",
}

/**
 * Subscribe to new blocks
 * @param listener - Callback receiving block number
 */
on(eventName: "block", listener: (blockNumber: number) => void): this;

/**
 * Subscribe to new block headers
 * @param listener - Callback receiving block header details
 */
on(eventName: "alchemy_newHeads", listener: (blockHeader: BlockHeader) => void): this;

interface BlockHeader {
  number: string;
  hash: string;
  parentHash: string;
  nonce: string;
  sha3Uncles: string;
  logsBloom: string;
  transactionsRoot: string;
  stateRoot: string;
  receiptsRoot: string;
  miner: string;
  difficulty: string;
  totalDifficulty: string;
  extraData: string;
  size: string;
  gasLimit: string;
  gasUsed: string;
  timestamp: string;
  baseFeePerGas?: string;
}

/**
 * Subscribe to pending transactions in mempool
 * @param options - Filter options for pending transactions
 * @param listener - Callback receiving pending transaction data
 */
on(
  eventName: "alchemy_pendingTransactions",
  options: PendingTransactionOptions,
  listener: (transaction: PendingTransaction) => void
): this;

/**
 * Subscribe to mined transactions
 * @param options - Filter options for mined transactions
 * @param listener - Callback receiving mined transaction data
 */
on(
  eventName: "alchemy_minedTransactions",
  options: MinedTransactionOptions,
  listener: (transaction: MinedTransaction) => void
): this;

interface PendingTransactionOptions {
  toAddress?: string | string[];
  fromAddress?: string | string[];
  hashesOnly?: boolean;
}

interface MinedTransactionOptions {
  addresses?: AddressActivityOptions[];
  includeRemoved?: boolean;
  hashesOnly?: boolean;
}

interface AddressActivityOptions {
  to?: string;
  from?: string;
}

interface PendingTransaction {
  hash: string;
  from: string;
  to: string;
  value: string;
  gas: string;
  gasPrice: string;
  maxFeePerGas?: string;
  maxPriorityFeePerGas?: string;
  nonce: string;
  data: string;
  type?: number;
}

interface MinedTransaction {
  hash: string;
  blockNumber: string;
  blockHash: string;
  transactionIndex: string;
  from: string;
  to: string;
  value: string;
  gas: string;
  gasPrice: string;
  gasUsed?: string;
  cumulativeGasUsed?: string;
  status?: string;
  logs?: Log[];
}

/**
 * Subscribe to contract event logs
 * @param filter - Log filter parameters
 * @param listener - Callback receiving log events
 */
on(
  eventName: "logs",
  filter: LogFilter,
  listener: (log: Log) => void
): this;

interface LogFilter {
  address?: string | string[];
  topics?: Array<string | string[] | null>;
  fromBlock?: string | number;
  toBlock?: string | number;
}

interface Log {
  removed: boolean;
  logIndex: string;
  transactionIndex: string;
  transactionHash: string;
  blockHash: string;
  blockNumber: string;
  address: string;
  data: string;
  topics: string[];
}

/**
 * Subscribe to address activity events
 * @param addresses - Array of addresses to monitor
 * @param listener - Callback receiving address activity
 */
on(
  eventName: "address",
  addresses: string[],
  listener: (activity: AddressActivity) => void
): this;

interface AddressActivity {
  fromAddress: string;
  toAddress: string;
  blockNum: string;
  hash: string;
  value: number;
  erc721TokenId?: string;
  erc1155Metadata?: Erc1155Metadata[];
  asset: string;
  category: AssetTransfersCategory;
  rawContract: RawContract;
}

/**
 * Subscribe to NFT activity events
 * @param filters - NFT activity filters
 * @param listener - Callback receiving NFT activity
 */
on(
  eventName: "alchemy_nftActivity",
  filters: NftActivityFilter[],
  listener: (activity: NftActivityEvent) => void
): this;

/**
 * Subscribe to NFT metadata updates
 * @param filters - NFT metadata filters
 * @param listener - Callback receiving metadata updates
 */
on(
  eventName: "alchemy_nftMetadataUpdate",
  filters: NftMetadataFilter[],
  listener: (update: NftMetadataUpdate) => void
): this;

interface NftActivityFilter {
  contractAddress?: string;
  tokenId?: string;
  fromAddress?: string;
  toAddress?: string;
}

interface NftMetadataFilter {
  contractAddress?: string;
  tokenId?: string;
}

interface NftActivityEvent {
  network: Network;
  activity: {
    contractAddress: string;
    tokenId: string;
    fromAddress: string;
    toAddress: string;
    transactionHash: string;
    blockNumber: number;
    category: NftActivityType;
  }[];
}

interface NftMetadataUpdate {
  contractAddress: string;
  tokenId: string;
  previousMetadata?: object;
  newMetadata: object;
  updateType: MetadataUpdateType;
}

enum MetadataUpdateType {
  INITIAL = "initial",
  REFRESH = "refresh",
  CHANGE = "change",
}

/**
 * Get WebSocket connection status
 * @returns Connection status information
 */
getConnectionStatus(): ConnectionStatus;

/**
 * Manually reconnect WebSocket
 * @returns Promise resolving when reconnected
 */
reconnect(): Promise<void>;

/**
 * Close WebSocket connection
 * @returns Promise resolving when closed
 */
disconnect(): Promise<void>;

/**
 * Check if WebSocket is connected
 * @returns Boolean indicating connection status
 */
isConnected(): boolean;

/**
 * Get connection statistics
 * @returns Connection performance metrics
 */
getConnectionStats(): ConnectionStats;

interface ConnectionStatus {
  connected: boolean;
  connecting: boolean;
  lastConnected?: number;
  lastDisconnected?: number;
  reconnectAttempts: number;
  error?: string;
}

interface ConnectionStats {
  messagesReceived: number;
  messagesSent: number;
  averageLatency: number;
  uptime: number;
  reconnections: number;
  errors: number;
}

/**
 * Set global event filters
 * @param filters - Global filter configuration
 */
setGlobalFilters(filters: GlobalEventFilters): void;

/**
 * Add event processor middleware
 * @param processor - Event processing function
 */
addEventProcessor(processor: EventProcessor): void;

/**
 * Remove event processor middleware
 * @param processor - Event processing function to remove
 */
removeEventProcessor(processor: EventProcessor): void;

interface GlobalEventFilters {
  minValue?: string; // Minimum transaction value
  maxGasUsed?: string; // Maximum gas used
  contractAddresses?: string[]; // Contract whitelist
  excludeAddresses?: string[]; // Address blacklist
}

type EventProcessor = (event: any, eventType: AlchemyEventType) => any | null;

/**
 * Subscribe to WebSocket errors
 * @param listener - Error callback function
 */
on(eventName: "error", listener: (error: WebSocketError) => void): this;

/**
 * Subscribe to connection events
 * @param listener - Connection callback function
 */
on(eventName: "connect", listener: () => void): this;

/**
 * Subscribe to disconnection events
 * @param listener - Disconnection callback function
 */
on(eventName: "disconnect", listener: (reason: string) => void): this;

/**
 * Subscribe to reconnection events
 * @param listener - Reconnection callback function
 */
on(eventName: "reconnect", listener: (attempt: number) => void): this;

interface WebSocketError {
  code: number;
  message: string;
  type: ErrorType;
  recoverable: boolean;
}

enum ErrorType {
  CONNECTION = "connection",
  AUTHENTICATION = "authentication",
  RATE_LIMIT = "rate_limit",
  PARSE = "parse",
  SUBSCRIPTION = "subscription",
}

import { Alchemy, Network, AlchemyEventType } from "alchemy-sdk";

const alchemy = new Alchemy({
  apiKey: "your-api-key",
  network: Network.ETH_MAINNET,
});

// Subscribe to new blocks
alchemy.ws.on("block", (blockNumber) => {
  console.log("New block:", blockNumber);
});

// Subscribe to pending transactions for specific addresses
alchemy.ws.on("alchemy_pendingTransactions", {
  toAddress: ["0x...", "0x..."],
  hashesOnly: false,
}, (transaction) => {
  console.log("Pending transaction:", transaction.hash);
  console.log("From:", transaction.from, "To:", transaction.to);
  console.log("Value:", transaction.value);
});

// Subscribe to mined transactions
alchemy.ws.on("alchemy_minedTransactions", {
  addresses: [
    { from: "0x..." },
    { to: "0x..." },
  ],
  includeRemoved: false,
}, (transaction) => {
  console.log("Transaction mined:", transaction.hash);
  console.log("Block:", transaction.blockNumber);
});

// Subscribe to contract event logs
alchemy.ws.on("logs", {
  address: "0x...", // Contract address
  topics: [
    "0x...", // Event signature hash
  ],
}, (log) => {
  console.log("Contract event:", log);
});

// Subscribe to address activity
alchemy.ws.on("address", ["0x...", "0x..."], (activity) => {
  console.log("Address activity:", activity);
  console.log("Asset:", activity.asset);
  console.log("Category:", activity.category);
});

// Subscribe to NFT activity
alchemy.ws.on("alchemy_nftActivity", [{
  contractAddress: "0x...", // Specific NFT collection
}], (activity) => {
  console.log("NFT activity:", activity.activity);
});

// Handle connection events
alchemy.ws.on("connect", () => {
  console.log("WebSocket connected");
});

alchemy.ws.on("disconnect", (reason) => {
  console.log("WebSocket disconnected:", reason);
});

alchemy.ws.on("error", (error) => {
  console.error("WebSocket error:", error.message);
  if (error.recoverable) {
    console.log("Attempting to recover...");
  }
});

// Subscribe once to next block
alchemy.ws.once("block", (blockNumber) => {
  console.log("Next block received:", blockNumber);
  // This callback will only fire once
});

// Check connection status
const status = alchemy.ws.getConnectionStatus();
console.log("Connected:", status.connected);

// Get connection statistics
const stats = alchemy.ws.getConnectionStats();
console.log("Messages received:", stats.messagesReceived);
console.log("Average latency:", stats.averageLatency, "ms");

// Clean up subscriptions
alchemy.ws.removeAllListeners("block");
alchemy.ws.off("alchemy_pendingTransactions");

// Manually reconnect if needed
if (!alchemy.ws.isConnected()) {
  await alchemy.ws.reconnect();
}