# Groundline

**A hallucination firewall for personal AI agents.** Before your agent tells you something or commits code, Groundline buys independent checks from [Telegraph](https://telegraphprotocol.com)'s ranked miners and marks each claim ✓ verified, ? uncertain or ✗ contradicted, with sources and a verifiable receipt for every check.

Built for Telegraph Hackathon Season II, Apps & Agents track. Missions: **09 Personal Agent** and **10 Model Economy**. Runs on Telegraph beta 2 (Ethereum Sepolia, test USDC).

```
# abbreviated output from a real testnet run
$ groundline verify "GPT-3 was released by OpenAI in 2020 and has 175 billion parameters. BERT was introduced by Meta in 2012."

UNRELIABLE  trust 49  ·  paid checks · $0.16
 ✓ GPT-3 was released by OpenAI in 2020 and has 175 billion parameters.   VERIFIED 80%  (TxLens: True)
 ✗ BERT was introduced by Meta in 2012.   CONTRADICTED 85%
     "BERT was introduced in October 2018 by researchers at Google, not by Meta in 2012."
```

## How it works

| Check | Telegraph intents bought | How |
|---|---|---|
| **Claim** | `FACT_CHECK_GENERAL` + `WEB_SEARCH_GENERAL` or `ACADEMIC_SEARCH_GENERAL` (ML or science claims) | Asks the top-ranked fact checker. If it abstains ("Unverified"), Groundline works down Telegraph's ranking until a miner gives a decisive verdict. Searches run on keyword queries and also move down the ranking when the answer has no sources. When no fact checker settles a claim, a search result only counts as support if it repeats every figure in the claim. Echoed queries and numbers inside URLs/DOIs are ignored. |
| **Answer** | the above per claim + `LLM_OUTPUT_EVALUATION_GENERAL` | 0–100 trust score, TRUSTWORTHY / REVIEW / UNRELIABLE, annotated answer with `[✓1] [?2] [✗3]` footnotes |
| **Links** | `URL_SAFE_GENERAL` per link cited in the answer (max 5) + a free reachability check | ✓ reachable & safe, ✗ BROKEN (dead or invented link, e.g. a fake arXiv id) or UNSAFE (suspicious/malicious). An unsafe link makes the answer UNRELIABLE, a broken one keeps it at REVIEW. |
| **Code** | `CODE_REVIEW_GENERAL` + `SECURITY_REVIEW_GENERAL` + `CVE_LOOKUP_CVSS` per CVE in the diff | PASS / WARN / BLOCK; exits 1 on BLOCK so it works as a git pre-commit hook |

Every purchase goes into `~/.groundline/ledger.jsonl` with intent, miner, cost, latency, `signal_hash` and `receipt_hash`. Anyone can re-verify a check:

```bash
curl -s https://devnode.telegraphprotocol.com/engine/v1/signal/<signal_hash> | jq .verification
# {"algorithm":"keccak256","commitment":"payload","verified":true}
```

## Where it runs

- **MCP server** (`groundline-mcp`), for Claude Code, Cursor, OpenClaw, Hermes, Goose or any MCP client. Tools: `groundline_verify_answer`, `groundline_verify_claim`, `groundline_code_guard`, `groundline_spend`, `groundline_status`.
- **CLI**: `groundline verify | claim | guard | extract | spend | status | serve | hook install`.
- **Local API + live spend dashboard** at `http://127.0.0.1:8787`, showing a spend leaderboard per intent and per miner, recent receipts, and a "verify an answer" box.
- **Browser extension** (`extension/`) that adds **Verify with Groundline** under ChatGPT, Claude and Gemini answers, plus a floating **Check whole answer / Check selection** dock, highlights each claim in place and lists every link with its status.

## Quick start

Requires Node 20+.

```bash
git clone https://github.com/AadithyaAle/groundline && cd groundline
npm install && npx tsc
```

Once published to npm, the package will be **`groundline-ai`** (commands `groundline` and `groundline-mcp`): `npx -y -p groundline-ai groundline serve`. Until then, use the clone and `node dist/cli.js …` as below.

**1. Wallet (testnet only, no real money).** Create a fresh burner wallet and put its key in `.env`. Never use a wallet that holds real funds.

```bash
cat > .env <<'EOF'
TELEGRAPH_PRIVATE_KEY=0x<burner private key>
GROUNDLINE_MAX_SPEND_USD=1.00
EOF
chmod 600 .env
```

Send it a little free Sepolia ETH from a faucet. Then mint test USDC and move part of it into Telegraph escrow:

```bash
node scripts/fund.mjs 10 2      # mint 10 test USDC, deposit 2 into escrow
node dist/cli.js status
```

**2. Try it.**

```bash
node dist/cli.js extract "The transformer was introduced in 2017. GPT-3 has 175 billion parameters."   # free
node dist/cli.js claim "BERT was introduced by Meta in 2012."                                          # ~$0.02-0.05
git diff --cached | node dist/cli.js guard                                                             # ~$0.03
node dist/cli.js serve        # dashboard at http://127.0.0.1:8787
```

**3. Add it to your agent (MCP).**

```bash
claude mcp add groundline -e GROUNDLINE_ENV_FILE=$PWD/.env -- node $PWD/dist/mcp.js
```

Other clients use the same `command` / `args` / `env` block, as in the Telegraph MCP examples.

**4. Browser extension.** Run `node dist/cli.js serve`. Then open `chrome://extensions`, enable Developer mode, click **Load unpacked** and select `extension/`. See [extension/README.md](extension/README.md).

**5. Pre-commit guard.** In any repo, run `node /path/to/groundline/dist/cli.js hook install`.

## Settings

| Variable | Default | Meaning |
|---|---|---|
| `TELEGRAPH_PRIVATE_KEY` | none | Burner wallet that pays for checks. Free commands work without it. |
| `GROUNDLINE_MAX_SPEND_USD` | `1` | Total budget across runs. Enforced from the ledger before any payment is signed. |
| `GROUNDLINE_MAX_PER_CALL_USD` | `0.05` | Refuse any single check priced above this |
| `TELEGRAPH_PAYMENT` | `auto` | `auto` (escrow first, then x402), `escrow` or `x402` |
| `TELEGRAPH_URL` | `https://devnode.telegraphprotocol.com` | Telegraph node |
| `GROUNDLINE_PORT` | `8787` | Local API / dashboard port |
| `GROUNDLINE_ENV_FILE` | | Explicit settings file. Otherwise `~/.groundline/.env`, then this package's `.env`. The current directory is never read. |

## Safety

- The private key stays in the local process. It is never sent to the model, the browser or the logs.
- Spend limits are checked before each payment is signed. A failed ask is never billed: escrow isn't charged, and x402 payments are credited back to escrow.
- The local server binds to `127.0.0.1` only. It accepts only the chat sites, the extension and loopback origins, checks the Host header against DNS rebinding, and limits request bodies to 200KB.

## Limitations (honest)

- Testnet only (Telegraph beta 2). Prices and miners change as the network evolves.
- Network fact checkers often abstain. Moving down the ranking helps, but some claims honestly end up **UNCERTAIN**.
- Claim extraction is heuristic unless the calling agent passes its own claims, which the MCP tool asks it to do.
- The extension's site selectors may need updating when ChatGPT, Claude or Gemini change their DOM.

## Development

```bash
npx tsc           # build
npm test          # 118 unit tests, mocked network, no spending
```

The payment flow is adapted from [telegraphprotocol/Telegraph-MCP](https://github.com/telegraphprotocol/Telegraph-MCP) (MIT). License: MIT.