hyperlane-xyz/hyperlane-monorepo / .agents/skills/debug-rpc-provider
debug-rpc-provider
VerifiedDebug RPC provider health issues for a chain. Use when alerts mention RPC failures, high latency, stale blocks, or provider errors. Diagnoses the issue and recommends fixes.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.6 KB |
SKILL.md
View on GitHub---
name: debug-rpc-provider
description:
Debug RPC provider health issues for a chain. Use when alerts mention
RPC failures, high latency, stale blocks, or provider errors. Diagnoses the issue
and recommends fixes.
---
# Debug RPC Provider
Diagnose RPC provider health issues for a Hyperlane chain and recommend fixes.
## When to Use
1. **Alert-triggered:** RPC error rate alerts, provider timeout alerts, stale block alerts
2. **User request:** "debug RPC for [chain]", "why are RPCs unhealthy on [chain]"
## Input Parameters
```test
/debug-rpc-provider <chain> [environment=mainnet3]
```
| Parameter | Required | Default | Description |
| ------------- | -------- | ---------- | ----------------------------- |
| `chain` | Yes | - | Chain name (e.g., `ethereum`) |
| `environment` | No | `mainnet3` | `mainnet3` or `testnet4` |
## Workflow
### Step 1: Find Monorepo Root
```bash
MONOREPO_ROOT=$(git rev-parse --show-toplevel)
```
### Step 2: Run Debug Script
```bash
pnpm --dir "$MONOREPO_ROOT/typescript/infra" exec tsx scripts/secret-rpc-urls/debug-rpc-url-health.ts \
-e <environment> -c <chain>
```
### Step 3: Analyze Results
Examine the output table and classify each RPC URL:
| Condition | Classification |
| ----------------------------- | ------------------------- |
| Health = ✅, Latency < 500ms | Healthy |
| Health = ✅, Latency >= 500ms | Slow |
| Health = ⚠️ | Stale (block age 30-120s) |
| Health = ❌, has error | Dead |
| Health = ❌, chainId mismatch | Misconfigured |
### Step 4: Output Diagnosis and Recommendation
Output the following structured information:
1. **Summary:** One-line description of the issue (e.g., "2 of 3 private RPCs are dead on ethereum")
2. **Current URL status table:** For each private RPC URL, show status (healthy/slow/stale/dead) and key metrics
3. **Proposed new URL list:** A concrete JSON array of the recommended new private RPC URLs. This should:
- Remove dead/misconfigured URLs
- Keep healthy URLs (reorder so healthiest are first)
- **Always backfill with healthy registry URLs** to replace removed URLs and maintain at least the original URL count. Registry URLs are free and add redundancy.
- Never leave the list empty
Format:
```test
Proposed new RPC URLs for <chain> (<environment>):
["https://full-url-1", "https://full-url-2"]
```
4. **Suggested action:** Either:
- "No action needed" if all private RPCs are healthy
- "Run `/fix-rpc-urls` to apply the proposed URL changes" if URLs need updating
- "Investigate further" if the issue is unclear (e.g., all RPCs stale may indicate chain halt)
### Step 5: Offer to Fix (Confirmation Gate)
If you recommended URL changes in Step 4, end your response with the confirmation convention so the user gets an approve/reject button:
```test
[CONFIRM: Fix RPC URLs for <chain>]
```
This MUST be the very last thing in your message. Do NOT run `/fix-rpc-urls` yourself — wait for user approval.
> **Note:** `[CONFIRM: ...]` is a Haggis-specific harness primitive — Haggis renders it as an inline approve/reject button. In other coding-assistant contexts it is just text, so this skill is intended to be invoked from Haggis.
If all URLs are healthy and no changes are needed, skip this step.
## Important Notes
- Registry URLs are public and don't contain secrets.
- If ALL RPCs (private + registry) are stale/dead, the chain itself may be halted — check block explorers before recommending URL changes.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |