Proofmark Units

Proofmark

The trust gate between AI agents and the MCP servers they connect to.

x402 payments and audit on Hedera · identity on ENSv2 · uniqueness and spend authority from World

Live app · Check any server · On-chain console · Testing report · Page-by-page walkthrough · Sponsor feedback

---

Contents

1. The idea
2. How it works, in one picture
3. The flows
4. Using Proofmark
5. Proof it runs
6. Track requirements
7. Design details
8. Run it yourself
9. Repo map
10. Limits, stated plainly
11. Prior art
12. How AI was used

---

The idea

The problem

An MCP server is not a library. When an agent connects to one, the server is handed the agent's shell, filesystem, credentials and payment rails. Thousands of MCP servers already exist, installed with one line such as npx -y some-server. Most of them come from people the user has never heard of.

Today the best assurance available is a signature showing that some GitHub account built the code. That leaves four gaps:

What Proofmark does

Before an agent connects to an MCP server, Proofmark:

1. Looks the server up on ENS to find who maintains it, what they charge, and which key may vouch for it right now.
2. Pays the maintainer $0.002 over x402 on Hedera, with no human approving the payment. The agent is allowed to spend because a person approved it once, through a World Agent Pass, and because its operator set an on-chain Hedera allowance.
3. Gets a signed attestation of two hashes: the hash of the exact build, and the hash of its exact tool list.
4. Starts the server and hashes the tools it actually offers. If the tools differ from what was attested, the connection is refused before the model ever sees the tool list.
5. Keeps watching. A revoked key reaches every connected agent within seconds through a Hedera Consensus Service topic. ENS is re-read every 15 seconds as the source of truth.

A server is green only when its maintainer is backed by all three layers:

   ┌────────────────────┐   ┌──────────────────────┐   ┌──────────────────────┐
   │  UNIQUE            │   │  DOMAIN-VERIFIED     │   │  BONDED              │
   │  World ID          │ + │  GitHub gist or      │ + │  50 HBAR in a 2-of-2 │
   │  one person,       │   │  domain proof of the │   │  Hedera account,     │
   │  one claim         │   │  registry namespace  │   │  forfeited on malice │
   └────────────────────┘   └──────────────────────┘   └──────────────────────┘
              stops sockpuppets      ties name to owner      puts money at stake

World alone is deliberately not trusted for identity. A credential can be shared, so the namespace proof and the bond exist to cover that.

What Proofmark is not

It is not a code scanner. An honest, verified maintainer can still ship a backdoor. Proofmark proves who stands behind a build, and that they still stand behind it, as of seconds ago. It complements tools like Socket and Snyk; it does not replace them.

---

How it works, in one picture

The same system as text:

                                   ┌──────────────────────────────────────────────┐
  ┌──────────────┐   MCP (stdio)   │              PROOFMARK PROXY                 │
  │ Agent client │ ──────────────▶ │  resolve on ENS → pay x402 → verify hashes   │
  │ Claude Code, │ ◀────────────── │  → spawn server → watch for changes          │
  │ Cursor, ...  │  only permitted └───────┬───────────────┬─────────────┬────────┘
  └──────────────┘      tools              │ x402 HTTP     │ spawns      │ subscribes
                                           ▼               ▼             ▼
                ┌──────────────────────────────┐   ┌─────────────┐  ┌──────────────────┐
                │      PROOFMARK GATEWAY       │   │ MCP server  │  │ Hedera mirror    │
                │  Hono · x402 merchant        │   │ (sandboxed  │  │ node: revocation │
                │  attest · claim · revoke     │   │ if unclaimed)│ │ topic messages   │
                └──┬──────────┬──────────┬─────┘   └─────────────┘  └──────────────────┘
                   │          │          │
         ┌─────────▼───┐ ┌────▼──────┐ ┌─▼─────────────┐
         │   HEDERA    │ │  ENSv2    │ │    WORLD      │
         │ x402 settle │ │  Sepolia  │ │ IDKit (claim) │
         │ HCS audit   │ │ orgs,     │ │ Agent Pass    │
         │ HCS revoke  │ │ keys,     │ │ (spend)       │
         │ HTS certs   │ │ agents    │ │               │
         │ allowances  │ │ ERC-8004  │ │               │
         │ bond acct   │ │           │ │               │
         └─────────────┘ └───────────┘ └───────────────┘

The simple sequence

sequenceDiagram
  autonumber
  participant A as Agent
  participant P as Proofmark proxy
  participant G as Gateway
  participant E as ENS (Sepolia)
  participant H as Hedera
  participant S as MCP server
  A->>P: connect to "io.github.acme/files"
  P->>G: GET /attest (signed by the agent)
  G->>E: who maintains it? is the key live? is the agent allowed to spend?
  G-->>P: 402 Payment Required, $0.002
  P->>H: pay over x402 (no human)
  H-->>G: settled · logged on HCS
  G-->>P: signed {artifactHash, toolManifestHash}
  P->>S: start the pinned build
  S-->>P: tools/list
  P->>P: hash the tools it received and compare
  P-->>A: the permitted tools, or a refusal naming what changed

The same flow without Mermaid:

 Agent        Proxy            Gateway             ENS        Hedera        Server
   │  connect   │                 │                 │            │             │
   │──────────▶ │  GET /attest    │                 │            │             │
   │            │───────────────▶ │  read records   │            │             │
   │            │                 │───────────────▶ │            │             │
   │            │  402 · $0.002   │ ◀───────────────│            │             │
   │            │ ◀───────────────│                 │            │             │
   │            │  pay over x402 ────────────────────────────────▶ │             │
   │            │                 │ ◀── settled + HCS log ───────│             │
   │            │  signed hashes  │                 │            │             │
   │            │ ◀───────────────│                 │            │             │
   │            │  start pinned build ───────────────────────────────────────▶ │
   │            │ ◀──────────────────────────────────────── tools/list ────────│
   │            │  hash + compare │                 │            │             │
   │  tools ✓   │                 │                 │            │             │
   │ ◀──────────│   (or ✗ refused, naming the added tool)                      │

---

The flows

Flow 1 · A maintainer claims a server (about a minute)

  Maintainer                         Gateway                               Chains
  ──────────                         ───────                               ──────
  1. Enter registry name ─────────▶  Is it in the official MCP registry?
     connect MetaMask                Does this wallet control the
                                     namespace? (GitHub gist / domain)
                                              │ yes
  2. World ID proof ──────────────▶  Verify proof on the backend,
     (Proof of Human)                reject a reused nullifier
                                              │ valid
  3. Org name, payout   ──────────▶  Register  sam.proofmark.eth  ───────▶  ENSv2 · Sepolia
     account, price                  its own resolver + records            (registry, resolver,
                                     server name → org                      records, roles)
                                              │
  4. Bond: 50 HBAR from payout ───▶  Verify on the mirror node    ───────▶  Hedera
     account to 0.0.11344995         write bond.tx on ENS, log on HCS       (transfer + HCS)
                                              │
                                     Server leaves the sandbox once it has
                                     a live key and an attestation

Flow 2 · A release is attested

  ┌───────────────┐  pinned build   ┌──────────────────────────┐   tools/list    ┌────────────┐
  │ MCP registry  │ ──────────────▶ │ Worker (Docker sandbox)  │ ──────────────▶ │ canonical  │
  │ npm / OCI /   │  hash checked   │ --network none           │                 │ SHA-256 of │
  │ mcpb          │  against the    │ --read-only --cap-drop   │                 │ names,     │
  └───────────────┘  registry       └──────────────────────────┘                 │ schemas    │
                                                                                 └─────┬──────┘
          ┌──────────────────────────────────────────────────────────────────────────┘
          ▼
  { server, version, artifactHash, toolManifestHash, attestKey, validUntil }
          │ signed by a co-maintainer key that is live on ENS
          ▼
  Gateway re-checks everything ──▶ full record on HCS ──▶ HTS NFT certificate minted

The manifest is derived, never requested. Because it comes from running the hash-verified build, a server cannot show one tool list to the attester and another to the user without also changing the build, which the artefact hash catches.

Flow 3 · An agent connects (the hero flow)

   resolve        pay              verify              connect
 ┌─────────┐   ┌─────────┐   ┌──────────────────┐   ┌───────────┐
 │ ENS:    │──▶│ x402 on │──▶│ artefact hash  ✓ │──▶│ session   │
 │ org,    │   │ Hedera  │   │ manifest hash  ✓ │   │ with the  │
 │ price,  │   │ $0.002  │   │ key live       ✓ │   │ permitted │
 │ key     │   │ no human│   │ pass + allowance✓│   │ tools     │
 └─────────┘   └─────────┘   └──────────────────┘   └─────┬─────┘
                                                         │ keeps watching:
                                                         │ • tools/list_changed → re-hash
                                                         │ • HCS revocation topic → seconds
                                                         │ • ENS re-check every 15 s

Flow 4 · The attack is caught

  Yesterday (attested)                 Today (served)
  ┌──────────────────────┐             ┌──────────────────────┐
  │ list_dir             │             │ list_dir             │
  │ read_file            │             │ read_file            │
  │                      │             │ read_env   ◀── NEW   │
  └──────────┬───────────┘             └──────────┬───────────┘
             ▼                                    ▼
      0x0e05fb00…72d5f0        ≠           0x9c1a77e2…0b31d4
                          │
                          ▼
     ✗ BLOCKED · manifest-mismatch · "added: read_env"
       The model never sees the tool list. No connection is made.

Flow 5 · Revocation across a fleet

  Maintainer revokes bob.acme.proofmark.eth
        │
        ├──▶ ENS: attest.key cleared  (source of truth)
        │
        └──▶ HCS topic 0.0.11344888: {org, key, reason, ts}
                    │
                    │  mirror node subscription (measured 2.1 s)
         ┌──────────┼───────────┬─────────────┐
         ▼          ▼           ▼             ▼
     agent-1    agent-2      agent-3   ...  agent-n      → all go red
     ✗ blocked  ✗ blocked    ✗ blocked      ✗ blocked
     Alice's attestations are untouched: only Bob's key was revoked.

Flow 6 · Spend authority and the denied path

                        ┌──────────────── before ANY payment ───────────────┐
  agent asks to pay ──▶ │ World Agent Pass valid and fresh?  ── no ──▶ 403  │ ✗ no payment
                        │ Operator allowance on Hedera left? ── no ──▶ 403  │ ✗ no connect
                        │ Inside the ENS budget?             ── no ──▶ 403  │
                        └──────────────────────┬────────────────────────────┘
                                               │ all yes
                                               ▼
                                     pay $0.002 over x402

The three tiers

                    ┌──────────────────────────┐
     name unclaimed │        SANDBOXED         │  runs in a container:
   ───────────────▶ │ --network none --read-only│  read-only tools only
                    └────────────┬─────────────┘
                                 │ claimed + namespace proof + bond + live key
                                 ▼
                    ┌──────────────────────────┐
                    │          GREEN           │  full tool set,
                    │  both hashes match       │  maintainer paid
                    └────────────┬─────────────┘
       hash mismatch · key revoked/expired · bond forfeited · typosquat
                                 ▼
                    ┌──────────────────────────┐
                    │         BLOCKED          │  refused, reason shown,
                    │                          │  alternative offered
                    └──────────────────────────┘

There is no amber tier. "Pin to the last good version" would let an attacker freeze everyone on a vulnerable build simply by stopping attestation.

---

Using Proofmark

If you are a judge: two minutes

1. Open /check and type any MCP server name, for example io.github.SamuelDharshi/proofmark-files. You see its tier, its reason and its three layers, all read live from ENS and Hedera.
2. Open /log, the On-chain console. Every payment, HCS message, HTS mint and allowance appears live from the Hedera mirror node. Click any row to open it on HashScan. Press F12 to see each transaction printed to the console.
3. Open /marketplace to browse real registry servers graded green, sandboxed or blocked, with prices in HBAR.
4. Read docs/TESTING.md for every transaction from the live test runs.

If you maintain an MCP server

The worker for step 6 runs on your machine, because deriving the manifest needs Docker:

wsl -u root service docker start        # Windows with Docker in WSL; skip on macOS/Linux
npm run worker -w @proofmark/gateway     # listens on 127.0.0.1:8788, holds no keys

All of steps 4 to 6 can also run from a terminal:

npm run bond:pay -w @proofmark/gateway -- <payout account> <payout key> 50
npm run maintain -w @proofmark/gateway -- <org> <registry name> <label> <days>

If you run agents

1. Fleet page (/fleet): each agent card shows its ENS name, HCS-14 UAID, ERC-8004 id, budget, operator allowance and Agent Pass.
2. Get pass: the gateway starts World's device flow, and you approve once in World. The validated pass is written to the agent's ENS name. Without it, the agent cannot pay, which is the denied path.
3. Allowance: approve or withdraw the operator's Hedera allowance to the agent:

    npm run allowance -w @proofmark/gateway -- approve 5     # cap in HBAR
    npm run allowance -w @proofmark/gateway -- withdraw

4. Point your agent at the proxy instead of the server, for example in Claude Code's MCP config:

    {
      "mcpServers": {
        "files": {
          "command": "npx",
          "args": ["tsx", "apps/proxy/src/cli.ts",
                   "--server", "io.github.SamuelDharshi/proofmark-files",
                   "--gateway", "https://proofmark-gateway.onrender.com",
                   "--", "npx", "-y", "proofmark-files", "."],
          "env": { "AGENT_ENS_NAME": "claude-1.agents.proofmark.eth" }
        }
      }
    }

   The agent also gets two tools of its own: proofmark_explain (why a server has its tier) and proofmark_budget (its spend, caps and pass).

If you build with the Hedera Agent Kit

import { proofmarkPlugin } from "@proofmark/agent-kit-plugin";
// adds PROOFMARK_CHECK_SERVER_TOOL and PROOFMARK_AGENT_IDENTITY_TOOL to any Agent Kit agent

---

Proof it runs

Every link below is a real transaction. The full list from the latest runs, including bond, revocation and allowance transactions, is in docs/TESTING.md.

Hedera testnet

Sepolia (ENSv2 and ERC-8004)

Automated

---

Track requirements

Hedera · AI Agents That Pay: x402

ENS · Best Use of ENSv2

World · Agent Pass and IDKit

---

Design details

The two hashes

Canonicalisation sorts keys, normalises whitespace and strips volatile fields, so honest servers never trip a false mismatch: canonical.ts.

Rechecks

• At connect: both hashes, key liveness, pass and allowance.
• On every tools/list_changed: re-hash mid-session (cli.ts).
• Revocation topic: a subscription through the mirror node drops a session within seconds (revocations.ts).
• Every 15 seconds: liveness re-read from ENS through the gateway. A missed HCS message only delays a block; it never allows one.
• Fail closed: if liveness cannot be confirmed for 3 checks in a row (45 s), the session blocks with liveness-unknown. A gateway outage never keeps a session trusted.
• Each attestation carries revocationCheckedAt and a 24-hour validUntil, so it goes stale rather than becoming a free pass.

The ENS tree

proofmark.eth                          Permissioned Registry, run by Proofmark
├── *.proofmark.eth                    wildcard: any unclaimed server → sandboxed
├── sam.proofmark.eth                  maintainer org, owned by the claiming wallet
│     status · payto · x402.price · world.verified
│     bond.tx · bond.status · domain.verified
│   ├── main.sam.proofmark.eth         co-maintainer: attest.key, expires in 180 days
│   └── bob.sam.proofmark.eth          co-maintainer: attest.key, revocable alone
├── <server>.proofmark.eth             the server name → resolves to its org
└── agents.proofmark.eth
    └── claude-1.agents.proofmark.eth  agent: budget · allowed.tools · maxrisk
                                       pass.* · hcs14.uaid · erc8004 · operator

There is one resolver instance per org, because argument-scoped grants apply to every name an instance serves. Claim and revoke are one write each, and nothing is written per attestation.

What lives where

---

Run it yourself

npm install
cp .env.example .env                                  # fill in the values below
npm run keys -w @proofmark/gateway                    # a signing key for ATTEST_PRIVATE_KEY
npm run hcs:create -w @proofmark/gateway              # HCS_TOPIC_ID
npm run hcs:create -w @proofmark/gateway -- revocations   # REVOKE_TOPIC_ID
npm run hts:create -w @proofmark/gateway              # HTS_TOKEN_ID
npm run bond:create -w @proofmark/gateway             # BOND_ACCOUNT_ID
npm run ens:status -w @proofmark/gateway              # confirms the admin wallet owns the root name
npm run agents:create -w @proofmark/gateway -- 2 5 1  # 2 agents, 5 HBAR each, $1 budget
npm run gateway                                       # http://localhost:8787
npm run web                                           # http://localhost:3000
npm test                                              # 30 unit tests
npm run live:check -w @proofmark/gateway              # the deployed system, end to end

---

Repo map

packages/core              canonical manifest hash, tier policy, typosquat check, explorer links
packages/runner            spawns an MCP server, in a hermetic container when available
packages/agent-kit-plugin  Hedera Agent Kit plugin
apps/gateway               Hono gateway: x402, attest, HCS, HTS, ENS, World, claim, bond, revoke
apps/gateway/src/scripts   live:check, e2e, worker, maintain, bond, allowance, setup scripts
apps/proxy                 the MCP proxy agents connect through
apps/demo-server           MCP test fixture for the proxy tests (the read_env attack)
apps/web                   Next.js app: landing, marketplace, check, fleet, claim, maintain, on-chain, docs, pitch
publish/files-server       proofmark-files, a real server published to npm and the MCP registry
docs                       TESTING.md, WALKTHROUGH.md, WORLD_DEBRIEF.md, architecture diagram
feedback                   one FEEDBACK.md per sponsor: Hedera, ENS, World

---

Limits, stated plainly

• Not a scanner. A verified maintainer can still ship malicious code. Proofmark makes that attack cost a unique identity, a namespace and a bond, keeps it revocable, and leaves a record.
• Hosted remote servers get liveness, identity and revocation, but no integrity guarantee. A remote endpoint can show the attester a different face. Clients report the hashes they observe so divergence is flagged.
• The gateway is trusted to run the sandboxed derivation honestly and to mark a bond forfeited. A contract or HTS escrow for the bond is the next step.
• World proves uniqueness, not identity. A shared credential is a known weakness, which is why the namespace proof and the bond exist.

---

Prior art

Proofmark adds three narrow things: revocation that reaches a running fleet, a unique, domain-verified, bonded maintainer instead of one account, and a recurring payment that keeps the freshness check sustainable.

---

How AI was used

Following ETHGlobal's rules: an AI coding assistant (Claude Code) was used throughout, to write and refactor code, tests and documentation, to run the on-chain test scripts, and to draft the pitch decks. The architecture, the product decisions and every on-chain approval were made by the team. Every transaction listed above was checked on HashScan or Etherscan.

Credits

Marks for Hedera, ENS, World, MetaMask and the Model Context Protocol belong to their owners and appear here only to show the technology Proofmark is built with.