boost

Goldsky Boost

Boost 是一个位于用户已付费使用的 RPC 端点前面的 CDN。每个请求都会先与 Goldsky 的索引数据进行比对：如果 Boost 有答案，就直接返回，服务提供商不会收到调用（因此也不会为此收费）。如果没有，请求会原样转发到用户的端点，响应也会原样返回。

Boost 免费。 CDN 命中和转发请求都不会产生 Goldsky 费用。这决定了介绍它的方式：这里不存在升级销售，用户唯一需要关注的数字是其现有服务提供商账单能减少多少。

避免大多数错误的基本认知

以下三个事实几乎可以解释用户提出的所有问题：

1. API 密钥就是一个 Boost 端点。 配置保存在密钥上，而不是请求中。URL 中的密钥是 Boost 确定要转发到哪个上游的依据。用户自己的服务提供商 URL 不会随请求发送。
2. 一个项目恰好有一个 Boost。 无需创建或列出命名的 Boost 端点。如果你想运行 goldsky boost create 或 goldsky boost list，这些命令并不存在——请参阅命令界面。
3. Boost 不会猜测链的头部。 区块标签始终会被转发。这是最常见的“为什么没有缓存？”问题，原因是这是刻意设计的，并非 Bug。

端点格式

https://edge.goldsky.com/boost/{chain}?key={GOLDSKY_API_KEY}

{chain} 是链名称或链 ID，且不区分大小写——/boost/ethereum 和 /boost/1 是同一个端点。

每个请求都必须包含 ?key=，而它缺失时可能出现两种不同情况。两种情况都已在生产环境中验证：

请求	响应	含义
没有 ?key=、?key= 为空，或 ?KEY=（名称区分大小写）	401，响应体为空	Edge 根本没有解析到密钥
?key=<something unrecognised>	404 + {"error":{"code":-32000,"message":"no Boost configuration for this key"}}	已读取密钥，但该密钥没有 Boost 配置

这一区别是最快的诊断方法：响应体为空的 401 表示 URL 格式错误（参数缺失、为空或名称有误——检查是否有未设置的环境变量插值为空），而 JSON 404 表示这是一个真实密钥，但它指向了错误的项目，或从未启用 Boost。

文档页面称，不带密钥的调用方会收到 x402 付款质询。这是 Edge 在 /standard/evm/... 上的行为，它确实会返回带有大型 JSON 响应体的 402。/boost/... 则绝不会这样。真正的 x402 质询非常明显，因此空响应体本身就能证明这不是 x402 质询——告诉用户他们会收到付款质询，只会让他们去排查一个在免费产品上根本不可能存在的账单问题。

密钥还能区分身份验证标头——请参阅发送服务提供商自己的身份验证信息。

直接替换

全部价值就在于其他任何内容都无需更改。向用户展示这个，而不是迁移指南：

import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({
  chain: mainnet,
  transport: http('https://edge.goldsky.com/boost/ethereum?key=YOUR_KEY'),
})

方法相同、参数相同、响应格式也相同。

验证是否正常工作

curl -i "https://edge.goldsky.com/boost/ethereum?key=YOUR_KEY" \
  -X POST -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBlockByNumber","params":["0x1b4",false]}'

运行两次。 对于 Boost 最近没有处理过的区块，第一次调用可能会返回 MISS，因为读取器正在从存储中预热该范围。只测试一次就看到 MISS 的用户会以为 Boost 出了问题——请告诉他们在下结论前再试一次。

CDN 提供的内容

方法	从 CDN 提供的条件
eth_getBlockByNumber	区块高度是具体的十六进制值
eth_getBlockByHash	始终符合条件
eth_getTransactionByHash	始终符合条件
eth_getTransactionReceipt	始终符合条件
eth_getLogs	fromBlock 和 toBlock 是具体的十六进制值，或已设置 blockHash
eth_getBlockReceipts	区块高度是具体的十六进制值

eth_chainId 和 net_version 会在边缘节点直接响应，不会访问任一后端。

其他所有请求都会免费转发。 写入请求、追踪、eth_call、eth_getBalance——全部透传。符合条件不代表一定命中：即使方法列在此表中，如果 Boost 尚未缓存特定数据，该请求仍会转发。

区块标签始终会转发

对于 latest、pending、safe、finalized 或 earliest 的请求，CDN 始终不会提供响应。Goldsky 对链头的视图可能比用户的服务商落后一两个区块，因此响应 latest 偶尔会返回过时或即将被重组的区块。用户的端点才是链头的权威来源。

对使用标签作为范围边界的 eth_getLogs 请求也是如此——因此，用户如果将范围设为 fromBlock: "0x..." 到 toBlock: "latest"，命中率会是 0%。将 toBlock 固定为具体高度，CDN 才会开始提供响应。

当有人反馈命中率较低时，这是最值得优先检查的一点。

查看响应头

请求头	值	含义
x-cache	HIT、MISS	Boost 是提供了响应，还是转发了请求
x-edge-source	cache、static、endpoint	实际响应方
x-edge-billable	整数	Boost 提供的条目数量。这个名称早于 Boost 免费化——它表示数量，而非费用
x-edge-duration-ms	整数	Boost 提供响应所用的实际时间
x-edge-region	AWS 区域	提供响应的边缘区域
x-edge-version	构建字符串	提供响应的 Boost 构建版本

建议绘制 x-cache 的统计图——这是标准 CDN 请求头，现有工具已能识别。统计 HIT 次数即可得出服务商未计费的调用准确数量。

浏览器 JavaScript 可以读取所有响应头（Access-Control-Expose-Headers: *）。

批处理

Boost 会按条目处理 JSON-RPC 批处理：可缓存的条目由 CDN 提供，其余条目则会在一个后续批次中转发给服务商。无需启用任何设置——向同一地址提交一个数组即可。

有两点容易踩坑：

• 只有在所有条目都由 CDN 提供时，x-cache 才会是 HIT。 一个有 45 个条目的批次，即使其中 44 个来自 CDN，仍会报告 MISS。对于批次，请读取 x-edge-billable（已提供的条目数量），而不是 x-cache。
• 超过 100 个条目的数组会整体转发，作为一次免费的透传，不进行 CDN 查询。请将较大的批次拆分成每批 100 个条目，以保持命中率。

为每个条目指定唯一的 id——JSON-RPC 不保证响应顺序，因此应按 id 而非位置匹配。

支持的网络

Boost 仅提供 CDN 从创世区块开始覆盖的链。如果某条链的覆盖从较晚的区块开始，则完全不会提供该链，因为 CDN 会返回近期历史记录，却悄无声息地遗漏起始区块以下的所有内容——这与 Boost 的用途正好相反。

网络	路径名称	Chain ID
Ethereum	ethereum	1
Base	base	8453
Polygon	polygon	137
Optimism	optimism	10
Avalanche	avalanche	43114
HyperEVM	hyperevm	999
Arc	arc	5042
Robinhood Chain	robinhood	4663
Ethereum Sepolia	sepolia	11155111
Base Sepolia	base-sepolia	84532

Goldsky 会索引但目前不提供 Boost 服务的链包括 Arbitrum、BNB Chain、Celo、Gnosis、Sei、Tron、Abstract 和 Monad——这些链的覆盖范围都从远高于创世区块的位置开始。如果用户询问其中某条链，原因就在这里，替代方案是 Edge（/edge）。

goldsky boost chains 会显示实时列表；一旦完成回填，该列表就比这张表更准确。请运行该命令，而不要凭记忆作答。

命令概览

一个项目只有一个 Boost，因此所有命令都不需要名称。 旧文档中提到的 boost create <name>、list、pause、resume 和 delete 已被移除。如果用户参考的页面中列出了这些命令，该页面已经过时——当前命令结构如下，如有争议，请以 goldsky boost --help 为准。

命令	功能
goldsky boost enable	启用项目的 Boost；首次启用时会引导用户完成提供商设置
goldsky boost disable	停止提供服务，但保留配置和密钥
goldsky boost get	查看各链的提供商、服务 URL 和状态
goldsky boost update	设置 --allowed-domains、--provider-rate
goldsky boost reveal	显示 Boost 使用的 API 密钥
goldsky boost metrics	JSON：命中次数、延迟、未命中原因、各提供商统计数据、节省金额
goldsky boost requests	查看逐请求历史：方法、链、命中或转发、所用提供商、耗时
goldsky boost chains	查看 Boost 可缓存的链，以及各链缓存历史记录的时间范围
goldsky boost validate <url>	探测提供商 URL：检测其所属链并检查是否能正常响应
goldsky boost set --chain <c>	开启或关闭某条链，设置 --forward-timeout / --cache-timeout
goldsky boost provider …	管理上游——见下文

常用标志：

• boost enable --chain <c> --provider-url <url> --header k:v — 一次性设置，在启用后立即配置第一个提供商。
• boost metrics --from <iso> --to <iso> --bucket-size 1m|5m|1h|6h|1d --chain <c>
• boost requests --chain <c> --method eth_getLogs --errors --limit <n>（每页 50 条）
• boost validate <url> --chain <c> 用于验证 URL 所属链是否与用户预期一致。

提供商（上游）

命令	必需标志
boost provider connect	--vendor quicknode|alchemy、--key、可重复指定的 --chain
boost provider add	--chain、--url、可重复指定的 --header k:v、可选的 --id
boost provider replace	--chain、--id、--url、--header、--clear-headers
boost provider activate	--chain、--id
boost provider remove	--chain、--id、--force
boost provider set	--chain、--id、--timeout、--vendor
boost provider disconnect	--vendor、--force

使用 provider connect 时不要提供 --key。 CLI 会提示输入该值，从而避免凭据留在 shell 历史记录中。切勿要求用户在聊天中粘贴提供商凭据——这与 /auth-setup 中 Goldsky 令牌的处理规则相同。

每条链可以配置多个上游，但只有一个处于启用状态。故障切换需要显式执行 provider activate，Boost 不会静默处理——因此，如果用户认为系统会自动故障切换，请纠正这一预期。

设置

有两种方式。应先询问用户想用哪种，不要自行假设：

连接服务商账号 — Boost 会为每条链创建端点。

服务商	凭据	Boost 会创建什么
QuickNode	具有 Admin API 访问权限的 API 密钥（Dashboard → API Keys）。仅限付费套餐	在其账号中为每条链创建一个端点
Alchemy	具有 Admin API App Management 读写权限的访问密钥（Dashboard → Settings → Security）。不是应用的 API 密钥	创建一个应用，并将其允许列表限制为所选链

Boost 只会操作自己创建的内容：断开连接时会删除这些端点，不会删除其他任何内容。

或粘贴 URL — 任何可通过 https 访问的端点，包括自行运行的节点或 Goldsky 自己的 Edge RPC。私有、环回和链路本地地址会被拒绝。

提交前先验证：

goldsky boost validate https://my-provider.example/rpc --chain ethereum

验证门槛

启用 Boost 及之后对其进行更改，都需要已验证的组织。只要团队中有一名权限高于 Viewer的成员使用企业邮箱，团队就会自动符合条件；个人邮箱（gmail.com、outlook.com、proton.me）不符合要求。无需填写表单，也无需审核；系统会在执行操作时检查，且批准永久有效。

用户遇到此情况时，关键是：验证是控制平面的门槛，而非运行时门槛。

操作	是否需要验证
启用 Boost；连接/断开服务商；添加、替换、激活、移除上游；切换链或更改超时时间；显示 API 密钥	是
读取配置、链和指标	否
禁用或删除 Boost	否
在已存在的端点上提供流量服务	否

无论验证状态如何，已配置的端点都会继续响应。这里的任何操作都不会中断用户正在提供的流量——请明确说明这一点，因为“需要验证”听起来像是有服务中断风险，但实际并非如此。

通常只需添加一名使用企业邮箱的队友，立即生效。如果这不适用（共享域名、设置前评估、域名被误分类），请引导用户通过 dashboard URL 中的团队 ID 联系 [email protected]。如果根本无法检查验证状态，系统会拒绝此次更改并要求重试，而不是判定不通过，并且不会写入任何状态。

发送服务商自己的身份验证信息

由于 Goldsky 密钥位于查询字符串中，请求中的 Authorization 和 X-API-Key 标头明确属于服务商，并会原样转发。只有存在 ?key= 时此功能才有效——没有它，Boost 就无法判断 Authorization 标头中的凭据属于谁。

对于不会更改的凭据，建议使用端点配置的标头（provider add --header k:v）：只需存储一次，每次转发时都会应用，调用方也无需持有这些凭据。

以 URL 用户信息形式提供的凭据（https://user:pass@…）会在请求离开 Goldsky 前转换为 Authorization: Basic。URL 和标头在静态存储时会加密，绝不会写入日志、错误信息或指标中。

故障排查

按以下列表依次排查——每项按其实际成因的常见程度排序。

症状	可能的原因和解决方法
返回 401 且响应体为空	未解析到密钥：缺少 ?key=、值为空或参数名错误（?KEY= 会失败，因为区分大小写）。通常是未设置的环境变量插值后为空。这不是计费问题；Boost 免费。
返回 404 和 -32000 no Boost configuration for this key	已读取密钥，但该密钥没有 Boost 配置——项目错误，或从未启用 Boost。运行 goldsky boost get 确认，运行 goldsky boost reveal 获取正确的密钥。
命中率接近于零	请求中包含区块标签。latest/pending/safe/finalized/earliest 始终会转发，包括作为 eth_getLogs 的范围边界时。请指定具体的十六进制区块高度。
首次调用返回 MISS，用户就此停止	读取器会从存储中预热该范围。请重复调用。
大批量请求明显有命中，却报告 MISS	对于批量请求，只有每项都由缓存提供时，x-cache 才会是 HIT。请读取 x-edge-billable。还要检查数组是否不超过 100 项——超过时会整体转发。
符合条件的方法仍被转发	Boost 目前尚未保存该特定数据。符合条件不等于保证命中；运行 boost requests --method <m> 确认，该命令会显示未命中的原因。
某条链上的请求被拒绝	该链没有活跃的上游，或已关闭。goldsky boost get 会显示每条链的状态；运行 boost set --chain <c> --enabled true 可重新启用。
完全无法使用某条链	Boost 仅提供创世区块已覆盖的链。运行 goldsky boost chains 检查；如果列表中没有该链，Edge（/edge）是替代方案。
配置更改被拒绝	触发了验证门槛。参见上文，并确认现有流量不受影响。
提供商拒绝转发的调用	没有固定的出口 IP 地址列表可供加入允许名单；Boost 从 us-east-1、us-west-2、eu-central-1 中的 Fargate 任务转发，请求地址会轮换。请使用凭据（端点 URL 或已配置的标头）对 Boost 进行身份验证，而不要将其加入允许名单。
订阅无法使用	Boost 仅支持 HTTP，不支持 WebSocket。请继续将 eth_subscribe / wss:// 指向提供商。
浏览器调用被 CORS 阻止	允许的域名在端点上设置（boost update --allowed-domains），而不是在提供商上设置。不允许带凭据的请求。
关于速率限制的疑问	Boost 的预算由 Goldsky 管理，API 会拒绝为 Boost 端点发送的速率限制预算——这与 Edge 不同。在合理使用范围内不设限制。

请用以下命令开始实际诊断：

goldsky boost get                                  # per-chain status and active upstreams
goldsky boost requests --limit 50                  # what actually happened, with miss reasons
goldsky boost metrics --from <iso> --bucket-size 1h

标头转发

转发时，提供商会收到调用方的标头，以及端点上配置的任何标头（名称冲突时以已配置的标头为准）。Boost 仅会扣留其管理的标头：X-ERPC-Secret-Token、Host、Content-Type/Accept（固定为 application/json）、Content-Length、Accept-Encoding/Content-Encoding、Cookie、Proxy-Authorization，以及逐跳标头。跟踪上下文（traceparent、tracestate、b3、baggage）、User-Agent 和自定义 x-* 标头都会透传。

X-Forwarded-For 会以完整且未经修改的链传递给提供商。读取最后一项——这是 Goldsky 负载均衡器观测到的地址；之前的各项由调用方提供，不可信。

返回时，提供商的 Cache-Control、Retry-After、ETag 和自定义 x-* 标头会透传。以下标头会被丢弃：Content-Encoding、Content-Type、Content-Length、Set-Cookie、Access-Control-*、x-cache/x-edge-*、x-goldsky-*。

Boost 还是 Edge？

它们共用一个主机，容易混淆：

• Boost 为用户已有的提供商提供前置服务。免费，使用自带上游，仅支持创世区块已覆盖的链，只支持 HTTP。适用于降低现有账单。
• Edge（/edge）是 Goldsky 自营的托管 RPC，用户可以购买它来替代提供商。支持的链多得多，并可配置速率限制、请求竞速和故障转移。

“我想减少在 Alchemy 上的支出” → Boost。“我想停止使用 Alchemy” → Edge。用户也可以将 Boost 的上游指向 Edge。

相关内容

• 文档：https://docs.goldsky.com/boost — 控制面板：https://app.goldsky.com/dashboard/edge/boost
• API：https://api.goldsky.com/api/v1/docs/#all/tag/boost（持有者令牌，按项目限定）
• /edge — Goldsky 托管的 RPC；/auth-setup — CLI 登录和项目选择
• 关于 CLI 语法，请以 goldsky boost --help 为准，而非任何文档页面。