Polygon WebSocket RPC：WSS 端点、eth_subscribe 与重连

直接回答：关于 Polygon WebSocket RPC 你需要了解什么

Polygon WebSocket RPC (WSS) 允许你从 Polygon PoS 网络接收实时区块链事件。Polygon 主网的主要 WSS 端点是 wss://polygon-bor-rpc.publicnode.com，Amoy 测试网是 wss://polygon-amoy-bor-rpc.publicnode.com。你也可以使用来自 OnFinality、Ankr 或 Dwellir 等提供商的特定端点。通过 eth_subscribe，你可以监听新区块、待处理交易以及匹配特定过滤器的日志。本指南涵盖机制、可运行示例以及常见断连问题的故障排除。

重要提示：本文介绍的是 Polygon 区块链（MATIC/POL），而非 polygon.io（一个独立的股票市场数据提供商）。如果你在寻找金融市场数据，那是另一项服务。

• 主网 WSS：wss://polygon-bor-rpc.publicnode.com
• 测试网 WSS (Amoy)：wss://polygon-amoy-bor-rpc.publicnode.com
• 方法：eth_subscribe 配合 newHeads、logs、newPendingTransactions、syncing

Polygon 架构：Bor 和 Heimdall

Polygon PoS 使用两层架构：Bor（区块生产者层，兼容 EVM）和 Heimdall（验证者层，基于 Tendermint）。Bor 以快速节奏（约 2 秒）生成区块，而 Heimdall 定期将这些区块检查点到以太坊。这意味着当你订阅 Polygon WSS 端点上的 newHeads 时，你会收到每个 Bor 区块的通知，但数据可能不会立即最终确定，直到 Heimdall 检查点被确认。对于大多数用例来说，这没问题，但要注意 Bor 上可能的重组。

Polygon PoS 的区块时间约为 2 秒，因此你会收到大量 newHeads 通知。这对于速率限制和连接稳定性很重要。

• Bor：每约 2 秒生成区块
• Heimdall：将区块检查点到以太坊，提供最终性
• 数据新鲜度：newHeads 是实时的，但在检查点之前并非最终

Polygon 主网和测试网的 WSS 端点

你可以使用公共端点或提供商端点。公共端点是免费的，但通常有速率限制，并且可能断开空闲连接。提供商端点（如 OnFinality）提供更高的可靠性和专门支持。始终查看最新文档以获取最新的 URL。

以下是一些常用的 WSS 端点（由各提供商记录）：

• PublicNode：wss://polygon-bor-rpc.publicnode.com（主网），wss://polygon-amoy-bor-rpc.publicnode.com（Amoy 测试网）
• Ankr：wss://rpc.ankr.com/polygon（主网），wss://rpc.ankr.com/polygon_amoy（测试网）
• Dwellir：wss://polygon-rpc.dwellir.com（主网）
• OnFinality：可通过你的 API 密钥使用，参见 API 服务

eth_subscribe：方法和负载

eth_subscribe 方法允许你订阅实时事件。标准订阅包括：

newHeads：通知你新区块头。负载包括区块号、哈希、父哈希、时间戳和其他头部字段。

logs：通知你匹配过滤器（地址和主题）的日志。这对于跟踪合约事件很有用。

newPendingTransactions：通知你进入交易池的交易哈希。请注意，这可能数量很大，并且并非所有提供商都支持。

syncing：当节点开始或停止同步时通知你。很少使用。

• 请求格式：{"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}
• 响应：{"jsonrpc":"2.0","id":1,"result":"0x9cef..."}（订阅 ID）
• 通知：{"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0x9cef...","result":{...}}}

// 订阅日志的示例请求
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_subscribe",
  "params": ["logs", {"address": "0x...", "topics": ["0x..."]}]
}

使用 ethers.js 和 web3.js 连接

你可以使用 ethers.js 或 web3.js 连接到 WSS 端点。使用 ethers.js 时，使用 new ethers.WebSocketProvider(url)。使用 web3.js 时，使用 new Web3.providers.WebsocketProvider(url)。两者都通过提供者的 on 方法支持 eth_subscribe。

下面是一个使用 ethers.js 的可运行 Node.js 示例，它连接到 Polygon 主网，订阅 newHeads 和 logs，并包含带有重新订阅的重连循环。

const { ethers } = require('ethers');

const WSS_URL = 'wss://polygon-bor-rpc.publicnode.com';
let provider;
let subscriptionIds = [];

async function connect() {
  console.log('正在连接 Polygon WSS...');
  provider = new ethers.WebSocketProvider(WSS_URL);

  provider.on('error', (error) => {
    console.error('WebSocket 错误:', error);
    reconnect();
  });

  provider.on('close', () => {
    console.log('WebSocket 已关闭。正在重新连接...');
    reconnect();
  });

  // 订阅 newHeads
  const headSub = await provider.send('eth_subscribe', ['newHeads']);
  subscriptionIds.push(headSub);
  provider.on('newHeads', (head) => {
    console.log('新区块:', head.number);
  });

  // 订阅日志（示例：USDT 转账事件）
  const logSub = await provider.send('eth_subscribe', ['logs', {
    address: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F', // Polygon 上的 USDT
    topics: [ethers.id('Transfer(address,address,uint256)')]
  }]);
  subscriptionIds.push(logSub);
  provider.on('logs', (log) => {
    console.log('日志:', log.transactionHash);
  });

  console.log('订阅已激活:', subscriptionIds);
}

function reconnect() {
  if (provider) {
    provider.removeAllListeners();
    provider.destroy();
  }
  setTimeout(connect, 5000); // 等待 5 秒后重新连接
}

connect();

// 预期输出：新区块号和交易哈希的日志
// 脚本将持续运行，并在断开连接时重新连接。

重连和重新订阅策略

公共 WSS 端点通常会在超时（例如 60 秒）或客户端超过速率限制时断开空闲连接。为了保持可靠的流，你需要实现心跳和重连逻辑。上面的示例在关闭时重新连接，但你还应该定期发送 ping 帧以保持连接活跃。许多库会自动执行此操作，但你也可以使用计时器，如果在某个间隔内没有收到任何通知，则再次发送 eth_subscribe。

重新连接时，你必须重新订阅所有订阅，因为之前的订阅 ID 已失效。此外，要准备好处理重复通知：如果你重新连接并重新订阅，可能会收到相同的区块或日志两次。使用幂等处理（例如，跟踪已处理的区块号或交易哈希）以避免重复计数。

• 心跳：每 30-60 秒发送一次 ping（例如，使用 provider.send('eth_subscribe', ['newHeads']) 作为保持活动，或使用 WebSocket ping 帧）
• 重新订阅：重新连接时，重新发出所有订阅
• 重复处理：维护一组已见区块号或日志哈希
• 退避：对重连尝试使用指数退避，以避免压垮服务器

常见故障和故障排除

以下是你可能遇到的常见问题以及如何修复它们。

订阅超额代码：某些提供商在订阅过多时返回错误代码，如 -32005（超出限制）。减少订阅数量，或使用包含多个地址/主题的单个过滤器。

每 IP 连接限制：公共端点通常限制每个 IP 的并发连接数。如果达到此限制，请使用限制更高的提供商或轮换端点。

区块高度滞后：如果你的节点落后，你可能会收到过时数据。检查提供商的同步状态，并考虑使用专用端点。

• 错误 -32005：订阅过多。合并过滤器。
• 连接限制：使用限制更高的提供商或多个端点。
• 滞后：监控区块高度并与参考（例如 Polygonscan）进行比较。
• 空闲断开：实现心跳和重连。
• 速率限制：使用速率限制更高的提供商或降低请求频率。

权衡和限制

WebSocket RPC 非常适合实时应用，但它有局限性。公共端点可能不支持 newPendingTransactions，因为数据量很大。此外，如果你订阅像 USDT 这样的热门合约，logs 订阅可能会很重。使用过滤器来缩小数据范围。

对于高吞吐量的生产环境，请考虑使用像 OnFinality 这样的专用提供商，它提供 RPC 定价 和 API 服务，并保证正常运行时间。另外，请注意 WebSocket 连接是有状态的，因此你需要优雅地处理重连。

有关断连修复的更多信息，请参阅我们的 通用 WebSocket RPC 断连修复。有关性能考虑，请查看 Polygon RPC 延迟和性能。

后续步骤和进一步阅读

既然你了解了 Polygon WebSocket RPC，你就可以构建实时应用，如交易监控器、DEX 套利机器人或 NFT 铸造追踪器。有关更多详细信息，请参阅 docs.polygon.technology 上的官方 Polygon 文档。

在 OnFinality Learn 中心 探索更多指南。如果你需要 Polygon RPC 帮助，请参阅我们的 Polygon RPC 指南（RPC 助手）。有关 Polygon 网络的一般信息，请访问 Polygon 网络页面。

• 官方 Polygon 文档：https://docs.polygon.technology
• 以太坊 JSON-RPC 规范：https://ethereum.org/en/developers/docs/apis/json-rpc/
• OnFinality API 服务：API 服务