gblin-treasury-risk-regime

# GBLIN MCP Server

> **Market risk regime and treasury tools for AI agents on Base mainnet.** A Model Context Protocol (MCP) server that answers two questions an autonomous agent has to ask before it moves money:
>
> 1. **Is the market risk-off right now?** Read the live regime — `calm` | `elevated` | `crash` — derived from an on-chain Crash Shield. **Free, no API key, no wallet.** If you need to prove to a counterparty that you checked, buy a signed EIP-712 **risk attestation** as portable proof-of-diligence.
> 2. **Where does idle USDC sit between jobs?** In GBLIN, a collateral-backed cbBTC/WETH/USDC index that mints and redeems at NAV, with a Just-In-Time swap back to USDC the millisecond the agent needs to pay an [x402](https://docs.cdp.coinbase.com/x402/welcome) invoice. No lockup, unsigned calldata only — your wallet signs, we never hold keys.

[![npm](https://img.shields.io/npm/v/@gblin-protocol/mcp-server.svg)](https://www.npmjs.com/package/@gblin-protocol/mcp-server)
[![CI](https://github.com/gblinproject/gblin-treasury-risk-regime/actions/workflows/ci.yml/badge.svg)](https://github.com/gblinproject/gblin-treasury-risk-regime/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Base Mainnet](https://img.shields.io/badge/network-Base%20mainnet-0052FF)](https://basescan.org/address/0x36C81d7E1966310F305eA637e761Cf77F90852f0)
[![Governance: 48h Timelock](https://img.shields.io/badge/governance-48h%20Timelock-1f6feb)](https://basescan.org/address/0x6aBeC8716fFeEcf7C3D6e68255b4797113E8e5Dd)
[![Base MCP Plugin](https://img.shields.io/badge/Base%20MCP-PR%20%2356-blue)](https://github.com/base/skills/pull/56)
[![x402 Manifest](https://img.shields.io/badge/x402-manifest-green)](https://gblin.digital/.well-known/x402)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-Active-success)](https://registry.modelcontextprotocol.io)
[![Glama Score](https://img.shields.io/badge/Glama-100%25-brightgreen)](https://glama.ai/mcp/servers/gblinproject/GBLIN-MCP)
[![Smithery](https://img.shields.io/badge/Smithery-gblin--protocol-orange)](https://smithery.ai/servers/gblin-protocol/mcp)

📖 **Full documentation and Quick Start:** [gblin.digital/agents](https://gblin.digital/agents)

⚡ **Copy-paste starter examples:** [`examples/`](examples/) — [ElizaOS](examples/elizaos.md) · [AgentKit / TypeScript](examples/agentkit.ts) · [Claude / any MCP client](examples/claude.md) — each with the recommended treasury-policy system prompt and safe-default security env.

▶️ **Runnable full-cycle demo** (read-only, no keys): `npx tsx examples/full-cycle.ts` — live against Base: treasury state → risk regime → attestation verified offline → invest calldata → JIT redemption calldata. [Source](examples/full-cycle.ts).

🌐 **Hosted MCP (Streamable HTTP, no install):** `https://gblin-mcp.gblin-mcp-worker.workers.dev/mcp` — **8 free tools** in a dot-notation tree, no auth, no session: `risk.regime`, `risk.attestation_sample`, `protocol.stats`, `protocol.info`, `coherence.report`, plus AI Action Receipts (`receipts.seal` demo 5/day/IP, `receipts.get`, `receipts.verify` — pure-math verification, no trust in this server). Two prompts: `risk_gate`, `seal_and_verify`. The pre-rename flat names still work as unlisted aliases until 2026-11-21. Docs are **MCP resources**, not tools: `gblin://howto/attestation`, `gblin://howto/seal`, `gblin://limits`, `gblin://keys` (verifier keys + key-rotation policy). Nothing is paid over MCP.
> **GET-only audit** (for reviewers and clients that cannot POST): [`/meta`](https://gblin-mcp.gblin-mcp-worker.workers.dev/meta) (counts + `manifest_hash`) · [`/tools.json`](https://gblin-mcp.gblin-mcp-worker.workers.dev/tools.json) · [`/resources.json`](https://gblin-mcp.gblin-mcp-worker.workers.dev/resources.json) · [`/conformance`](https://gblin-mcp.gblin-mcp-worker.workers.dev/conformance) · [`/v1/verify/:index`](https://gblin-mcp.gblin-mcp-worker.workers.dev/v1/verify/0) (per-check booleans + on-chain anchor consistency).
> This hosted surface is **deliberately different** from the npm stdio package below (13 tools, treasury/governance included). Also on [Smithery](https://smithery.ai/servers/gblin-protocol/mcp). Source in [`worker/`](worker/).

---

## ElizaOS Plugin

For agents running on **ElizaOS**, install the companion plugin — now listed in the **official ElizaOS plugin registry** (v0.4.0, security-hardened):

```bash
npm install plugin-gblin
# or: elizaos plugins add gblin
```

It exposes four native Actions (`CHECK_GBLIN_TREASURY_HEALTH`, `INVEST_IDLE_USDC_GBLIN`, `RESCUE_USDC_FROM_GBLIN`, `GET_GBLIN_RISK_ATTESTATION`) and a Provider that injects live NAV + Crash Shield status into the agent context on every loop.

→ [Full Eliza plugin docs](https://github.com/gblinproject/GBLIN_PLUGIN)

---

## AI Action Receipts — a witnessed transparency log for what your agent did

The problem this attacks is the #1 barrier to AI adoption in 2026: **nobody can
prove, after the fact, exactly what an AI did** (surveys: workers burn 2–4 h/week
verifying AI output; 70% of orgs say they cannot govern their agents). Our answer
is the smallest honest primitive: a public, append-only **RFC 6962 transparency
log** for AI actions. Input and output go in as **hashes only** (never content);
the short `action` label, `agent_id`, `tool` and `meta` strings you send are
published in the public log — put identifiers there, never secrets. You get back
a portable receipt any third party can verify offline, forever.

```
receipt = canonical payload
        + Ed25519 signature            (key: gblin.digital/receipts-log)
        + RFC 6962 inclusion proof     (leaf → Merkle root)
        + C2SP signed checkpoint       (origin, tree size, root)
```

Canonicalization is frozen as **`gblin-canonical-json/1`**: object keys sorted by
UTF-16 code unit, no whitespace, `JSON.stringify` semantics for primitives,
recursion for objects/arrays. Test vector: payload `{"b":1,"a":null}` →
canonical `{"a":null,"b":1}` → leaf = `SHA256(0x00 || canonical_bytes)`. The
receipt signature is Ed25519 over `"gblin-receipt/v1\n" + canonical`.

- Seal (paid, unlimited): `POST https://gblin.digital/api/x402/seal` — $0.01 USDC via x402.
- Seal (demo, 5/day/IP): `POST <worker>/v1/seal-demo` or hosted MCP tool `receipts.seal` (verify with `receipts.verify`).
- Read free forever: `<worker>/v1/receipt/:index` · `/log` · `/log/checkpoint` · `/log/proof/:index` · human page `/receipt/:index`.
- Daily EAS anchor on Base of the tree root (verifiable on base.easscan.org, schema `0x9f433a96…`, promiseId `keccak256("gblin-receipts-log")`).
- **Offline verifier, zero dependencies:** [`verify-receipt.mjs`](./verify-receipt.mjs) — `node verify-receipt.mjs receipt.json`.

A seal proves **existence and time** in a signed append-only log whose root is
anchored daily on Base. The checkpoint is currently signed by the log operator
(us); **independent witness cosigning is an open invitation** — we already
cosign a third-party transparency log (C2SP tlog-witness) and will list any
witness that cosigns ours. Until then, honest wording: operator-signed, chain-anchored.
It is **not** a compliance certificate and **not** an endorsement of the content.
Worker: `<worker>` = `https://gblin-mcp.gblin-mcp-worker.workers.dev`.

## Coherence Proof — verify GBLIN keeps its promises

GBLIN pre-registers hash-pinned public promises, then runs an automaton that probes them every 10 minutes and seals each closed day as an [EAS attestation](https://base.easscan.org/schema/view/0x9f433a96467ab75530009970e5aa938ec94d8a49f08f66e7381822d557b448ef) on Base. Reading is free forever; the paid service is being observed — the certifier submits itself to its own instrument first.

- **Free report:** [`/coherence`](https://gblin-mcp.gblin-mcp-worker.workers.dev/coherence) (JSON) or the hosted MCP tool `coherence.report`.
- **Live promises:** P1 (uptime of the paid Risk Attestation endpoint) and P2 (honesty of the public agent-economy counters, with our own wallets disclosed and excluded).
- **On-chain:** each closed day is sealed as an EAS attestation on Base by a dedicated observer wallet. GBLIN is a discoverable ERC-8004 agent (#59286).

---

## AI assistant discovery — `gblin-init`

Drop an `AGENTS.md` treasury policy into your repo so every modern AI coding
assistant (Claude Code, Cursor, Windsurf, GitHub Copilot, Codex) automatically
discovers GBLIN when it works on your codebase:

```bash
npx -p @gblin-protocol/mcp-server gblin-init
```

The command is **idempotent and safe**:

- If `AGENTS.md` does not exist → creates it from the canonical template at
  [`gblin.digital/AGENTS.template.md`](https://gblin.digital/AGENTS.template.md).
- If `AGENTS.md` exists → appends a clearly delimited GBLIN block at the
  bottom; your own content is never touched.
- Re-running is a no-op (detected via stable HTML markers).
- `--dry-run` prints what it would do without writing.
- `--force` refreshes the block to the latest version.

It also runs offline thanks to a bundled fallback template.

### Postinstall hint

When the package is installed as a regular dependency (`npm i @gblin-protocol/mcp-server`),
a short tip is printed once suggesting the command above. **No files are
written** during postinstall — security-friendly and Socket-compliant. Set
`GBLIN_SKIP_HINT=1` to silence it.

---

## Trust & Governance

**GBLIN V6 is governed by a 48h Timelock Controller** — every admin operation (parameter change, oracle update, ownership transfer) is enforced on-chain to wait **172,800 seconds** before execution. Agents and integrators can verify this directly on BaseScan.

| Component | Address | Role |
|---|---|---|
| **GBLIN V6 token** | [`0x36C81d7E...52f0`](https://basescan.org/address/0x36C81d7E1966310F305eA637e761Cf77F90852f0) | Index contract (production) |
| **Timelock Controller** | [`0x6aBeC8716...8e5Dd`](https://basescan.org/address/0x6aBeC8716fFeEcf7C3D6e68255b4797