# anchor-debug

> CLI tool that makes Anchor program failures understandable.

When your Anchor test fails with `custom program error: 0x1770`, anchor-debug tells you exactly **what broke, where, and why**.

## Before vs After

**Without anchor-debug:**
```
Error: failed to send transaction: Transaction simulation failed: Error processing Instruction 0: custom program error: 0x7d2
```

**With anchor-debug:**
```
✗ Transaction failed

  Error: ConstraintHasOne
  Code:  0x7d2 (2002)
  Msg:   A has_one constraint was violated — account field does not match expected value
  Program: my_program (9uvbWC...)

  CPI call stack:
  └─ ✗ my_program (9uvbWC...) ← failed here
     Error: A has_one constraint was violated — account field does not match expected value
     └─ ✓ TokenkegQfeZy... (Token Program)
     └─ ✗ my_program::validate_authority ← failed here
```

---

## Installation

```bash
npm install -g anchor-debug
# or use directly with npx
npx anchor-debug --help
```

---

## Usage

### Pipe anchor test output

```bash
anchor test 2>&1 | npx anchor-debug
```

anchor-debug reads stdin, finds the failure, and prints a human-readable error. If the test succeeds, output is passed through unchanged.

### Debug a transaction by signature

```bash
npx anchor-debug tx <SIGNATURE> --cluster devnet
npx anchor-debug tx <SIGNATURE> --cluster mainnet-beta
npx anchor-debug tx <SIGNATURE> --cluster http://localhost:8899
```

Fetches the transaction from the RPC, extracts its logs, and formats the error.

### Run tests with automatic error formatting

```bash
npx anchor-debug test
npx anchor-debug test --skip-build
```

Runs `anchor test` for you and prints the parsed error on failure.

---

## Options

| Flag | Description |
|---|---|
| `--raw` | Also show raw log lines |
| `-v, --verbose` | Show all program log messages |
| `-c, --cluster <cluster>` | Cluster or RPC URL (tx command) |
| `--skip-build` | Pass --skip-build to anchor test |

---

## How it works

1. **Log parser** — reads Solana program logs line-by-line using a regex state machine
2. **Error database** — 60+ Anchor framework errors mapped by hex code (both new 0x7d0+ and legacy 0x1770+ ranges)
3. **CPI tracer** — rebuilds the full `Program invoke [N]` call tree and marks the innermost failing invocation
4. **IDL resolver** — reads `Anchor.toml` and `target/idl/*.json` to show program names instead of pubkeys

---

## Supported error ranges

| Range | Source |
|---|---|
| `0x64–0x67` (100–103) | Instruction errors |
| `0x3e8–0x3ea` (1000–1002) | IDL errors |
| `0x7d1–0x7f8` (2001–2040) | Constraint errors (Anchor ≥ 0.24) |
| `0xbb8–0xbc1` (3000–3017) | Account errors |
| `0xfa0–0xfa2` (4000–4002) | State errors |
| `0x1770–0x1783` (6000–6019) | Legacy constraint errors (Anchor < 0.24) |

---

## MCP Server (for AI agents)

anchor-debug works as an [MCP](https://modelcontextprotocol.io) server, giving AI coding agents (Claude Code, Cursor, etc.) structured access to Solana error data.

Add to `.mcp.json` in your project:

```json
{
  "mcpServers": {
    "anchor-debug": {
      "command": "npx",
      "args": ["anchor-debug", "mcp"]
    }
  }
}
```

Or globally in `~/.claude/mcp.json`.

**Available tools:**

| Tool | What it does |
|---|---|
| `parse_logs` | Takes raw log lines → structured error + CPI stack |
| `debug_transaction` | Takes signature + cluster → fetches and parses |
| `lookup_error` | Takes hex code → error name + message |

**Example agent response after calling `parse_logs`:**

```json
{
  "failed": true,
  "error": {
    "name": "ConstraintHasOne",
    "code": 2002,
    "hex": "0x7d2",
    "message": "A has_one constraint was violated — account field does not match expected value",
    "category": "constraint"
  },
  "failedProgram": "my_program",
  "failedNode": {
    "program": "my_program",
    "depth": 2,
    "errorMessage": "A has_one constraint was violated"
  },
  "cpiStack": [...]
}
```

Instead of reasoning about `0x1770`, the agent immediately knows what failed and can fix it in one shot.

---

## Programmatic API

```typescript
import { parseLogsFromString, formatResult } from "anchor-debug";

const logs = [
  "Program MyProg invoke [1]",
  "Program MyProg failed: custom program error: 0x7d2",
];

const parsed = parseLogsFromString(logs.join("\n"));
console.log(formatResult(parsed));
```

---

## Milestones

- [x] M1 — npm package, log parser, Anchor error database
- [x] M2 — CPI call stack visualizer, IDL integration
- [ ] M3 — VS Code extension (inline hints)

---

## License

MIT