solidity-debug

A troubleshooting workflow for failed Ethereum smart-contract transactions using Foundry’s command-line tools. It checks transaction receipts and details, then helps identify whether the failure involved gas, a revert, or another cause.

In plain words
What is it for?
Use it to inspect a transaction hash, compare the gas used with the gas limit, decode the called function, and investigate failed contract calls. The provided excerpt does not show the complete workflow for retrieving or decoding the revert reason.
Why use it?
It replaces guesswork with transaction data such as success status, gas usage, and the called contract function. This helps narrow down why a transaction failed before investigating the contract code.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/comeonoliver/skillshub/solidity-debug
Any agent
npx skills add ComeOnOliver/skillshub --skill solidity-debug
Clone the repo
git clone --depth 1 https://github.com/ComeOnOliver/skillshub

Made for: Claude Code, Codex.

Per session 57 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 1,315 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00057 $0.01315
Opus 5 $0.00028 $0.00658
Sonnet 5 $0.00011 $0.00263
Haiku 4.5 $0.00006 $0.00131

Measured 3d ago against content hash e2be914b2a34, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

solidity-debug scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 3d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

Origin

Copies of this mod

1 near-identical copy found in the catalogue:

skills/0xlayerghost/solidity-agent-kit/solidity-debug/SKILL.md · 121 lines

How it starts

The opening of the file, as written. The whole thing — 121 lines — stays where its author put it; the contents beside it link to each section on GitHub.

Failed Transaction Debug Workflow

Language Rule

  • Always respond in the same language the user is using. If the user asks in Chinese, respond in Chinese. If in English, respond in English.

Step 1: 获取交易回执 — 判断成功/失败

使用 Foundry cast CLI 查询交易回执(receipt),传入 tx hash 和 RPC endpoint。

关注字段:

字段 含义
status 0 = 失败, 1 = 成功
gasUsed 实际消耗的 gas
logs 空数组 [] = 交易 revert,无事件发出
to 目标合约地址

Step 2: 获取交易详情 — 拿到 gas limit 和 input

使用 Foundry cast CLI 查询交易详情(tx),传入 tx hash 和 RPC endpoint。

关注字段:

字段 含义
gas 发送方设置的 gas limit
input 调用的 calldata(函数选择器 + 参数编码)
from / to 发送方和目标合约
value 发送的原生代币数量

Step 3: 判断失败类型 — gasUsed vs gas limit

现象 判断 解决方向
gasUsed / gas ≈ 100%(如 999,472 / 1,000,000) Out of Gas (OOG) 提高 gas limit 或估算 gas
gasUsed 远低于 gas limit(如 50,000 / 1,000,000) Revert 需获取 revert reason,见 Step 6
gasUsed 正常但 status=0 内部调用失败 检查余额、授权、内部 call 返回值
交易根本没上链 Nonce/Gas Price 问题 检查 pending 队列

Step 4: 解码函数选择器 — 确定调用了什么函数

使用 Foundry cast 的 4byte 功能,传入 input 的前 4 字节,查询对应的函数签名。

示例:输入 0xb51a038a → 输出 unstake(uint256,address[],uint256[])

Step 5: 解码完整 calldata — 还原调用参数

使用 Foundry cast 的 calldata-decode 功能,传入 Step 4 得到的函数签名和完整 input data。

解码后的参数可用于:

  • 分析入参是否有误
  • 直接用于重试交易

Step 6: 获取 Revert Reason(非 OOG 场景)

方法 说明
模拟调用 使用 Foundry cast call 在失败区块号上模拟,指定 from 地址和 block number,还原 revert 信息
重放交易 使用 Foundry cast run 重放交易(需要 archive 节点)
在线分析平台 使用第三方交易分析平台查看详细调用栈(备用方案)

Step 7: 查询链上状态 — 确认交易失败后数据已回滚

使用 Foundry cast call 查询合约的 public 变量和 mapping,传入合约地址、函数签名及参数。

对于 struct 类型返回值,需按 ABI 顺序指定返回类型。

失败交易的状态变更会完全回滚,需确认数据仍在原始状态。

Step 8: 对比成功 vs 失败交易 — 找差异

将成功和失败的交易放在一起对比:

对比维度 说明
gas 消耗 判断是否 OOG
调用参数 判断是否入参问题
目标地址 判断是否调错合约
区块时间 判断是否有时间锁等限制
合约状态 判断是否前置条件不满足

Step 9: 重试交易

场景 方法
正常重试 使用 Foundry cast send,不指定 gas limit(让节点自动估算)
已知消耗范围 使用 Foundry cast send,指定较高 gas limit

Read the full file on GitHub · 121 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 3d ago First seen · 121 lines · 57 tokens per session scan A e2be914b2a34

Subscribe to this mod's changes

solidity-debug is a skill published in the GitHub repository ComeOnOliver/skillshub (63 stars, last pushed 2mo ago), licensed MIT. It adds 57 tokens to every session and 1,315 once invoked, about $0.0003 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Related

Other skills, from other repositories

frontend-design

Create distinctive, production-grade Stellar dApp UI. Combines bold aesthetic direction with smart contract integration patterns — wallet connection flows, transaction UX, contract data displays, and agentic kit hook wiring. No generic "AI slop" aesthetics.

rylsherdamz-rgb/stellar-forge · 51 tokens

onchainai-crypto-tools

Find, vet, and install crypto/onchain tools such as MCP servers, CLIs, SDKs, APIs, x402 services, and AI-agent tools through the OnchainAI directory. Use when the user needs an onchain capability, asks which tool fits a chain or task, wants install steps for Claude/Cursor, or needs trust, install risk, or x402 payment…

Coinyak/onchainai · 89 tokens

copy-trading-solana

Copy trade Solana wallets - mirror trades automatically.

alsk1992/CloddsBot · 15 tokens

omd:orchestrator

멀티 에이전트 디자인 워크플로우 supervisor. writer, locale adaptation, humanize, UI slop audit, designer review, final QA, image materialization을 routing한다. 2-round revision cap을 유지하며 다국어 문서·UI 개선·출간 준비처럼 여러 역할이 필요한 요청에 사용한다.

kwakseongjae/oh-my-design · 77 tokens

define-jtbd-canvas

Creates a Jobs to be Done canvas capturing the functional, emotional, and social dimensions of a customer job. Use when deeply understanding customer motivations, designing for jobs, or reframing product positioning.

product-on-purpose/pm-skills · 45 tokens

define-problem-statement

Creates a clear problem framing document with user impact, business context, and success criteria. Use when starting a new initiative, realigning a drifted project, or communicating up to leadership.

product-on-purpose/pm-skills · 43 tokens