Revoke

Documentation

Install & use the infra

Revoke is a revocable ENS capability layer for agent payments. Capabilities are granted as ENS subname records on Sepolia, indexed by a subgraph on The Graph, and enforced by an x402-gated settle service that writes receipts to a Hedera HCS topic. This page shows how to point at the live infrastructure and how to run each service locally.

Want to verify the live claims without installing anything? See VERIFY.md — read-only curl commands, no wallet needed.

01

What's live

CapabilityRegistry0xE2867033aa5963a838c85aC2aE3A9452B715750d
AgentRegistrar0x94CC95937aD2d1Fc8e7D46500553443732049b37
AgentResolver0x9cB3881E62B5C9e55DAde607d5FC93F6bB719150
Network
Sepolia testnet
Subgraph
https://api.studio.thegraph.com/query/1760021/revoke-ens/v0.0.2
HCS topic
0.0.10456766
02

Prerequisites

  • Node 20+ and pnpm (npm i -g pnpm)
  • A Sepolia RPC URL (e.g. Alchemy or any public endpoint)
  • For settlement: a funded Hedera testnet account (id + private key)
  • A browser wallet (MetaMask) with Sepolia test ETH — only for grant/revoke, not for read-only use
03

Install

git clone https://github.com/Dragoon4002/revoke.eth.git
cd revoke.eth
pnpm install

Copy the env template and fill in your keys. The defaults already point at the live deployed contracts, subgraph, and HCS topic:

cp .env.example .env
# edit .env — set at minimum:
#   SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/<key>
#   GRAPH_QUERY_URL=https://api.studio.thegraph.com/query/1760021/revoke-ens/v0.0.2
#   HEDERA_ACCOUNT_ID=0.0.xxxxx      (for settlement writes)
#   HEDERA_PRIVATE_KEY=<key>
#   HEDERA_TOPIC_ID=0.0.10456766
04

Run the services

Two backend services back the app. Both are read-only over the public subgraph except the settle service, which also writes HCS receipts.

Index server — capability lookup & freshness

cd packages/index
pnpm dev            # listens on :4000

Endpoints:

  • GET /delegation/:agent — capabilities + provenance
  • GET /authorize/:agent/:cap — authorized? + reason
  • GET /provenance — indexed block, chain head, lag, verdict

Settle server — x402 gate & HCS receipts

cd packages/settle
pnpm dev            # listens on :5000

GET /service/:endpoint with an X-Agent-Name header returns:

  • 200capability valid + paid → HCS receipt written
  • 402no capability → payment required
  • 403revoked / expired → paying never unlocks it
05

Run the web app

Point the frontend at your local services (or omit to use built-in fixtures):

cd apps/web
# apps/web/.env.local
NEXT_PUBLIC_GRAPH_QUERY_URL=http://localhost:4000
NEXT_PUBLIC_SETTLE_URL=http://localhost:5000

pnpm dev            # http://localhost:3000

Then open /app to grant, revoke, and settle against your running stack.

06

Read-only sanity check

No install required — query the live subgraph for the demo agent alpha.eth directly:

curl -s -X POST https://api.studio.thegraph.com/query/1760021/revoke-ens/v0.0.2 \
  -H "Content-Type: application/json" \
  -d '{"query":"{ agentDelegation(id: \"0x6dfc21ac0c8c2db036305d8bc6f887630d35e156f37d5a7e2275bc05bc004846\") { capabilities { active expiryTimestamp } } _meta { block { number } } }"}'

Pull a settlement receipt straight from Hedera's public mirror node:

curl -s https://testnet.mirrornode.hedera.com/api/v1/topics/0.0.10456766/messages/4
07

Add your own agent

The scripts/register-agent.mjs script registers a new agent (creates the ENS subname <label>.agents.revoke.eth) and grants it one capability, both on Sepolia, using the wallet in PRIVATE_KEY. It takes no CLI args — you edit two hardcoded constants at the top before running.

Heads up — on the live deployment, registerAgent is onlyOwner on the AgentRegistrar, so only the contract deployer wallet can register new agents. A third party running this against the live contracts will get a revert. To register your own agents, deploy your own contracts first.

1. Edit the constants

Open scripts/register-agent.mjs and set:

const AGENT_LABEL  = "alpha";     // → your agent name (becomes <label>.agents.revoke.eth)
const SERVICE_NAME = "summarise"; // → the capability to grant

2. Run it

Requires PRIVATE_KEY and SEPOLIA_RPC_URL in .env:

node --env-file=.env --import tsx/esm scripts/register-agent.mjs

This runs registerAgent then grantCapability and prints both tx hashes.

3. Verify the delegation indexed

curl http://localhost:4000/delegation/<label>.eth

4. Test the gate

curl http://localhost:5000/service/<capability> -H "X-Agent-Name: <label>.eth"

Expect the same 200 / 402 / 403 outcomes documented above.

5. Revoke anytime

Edit the hardcoded label and service in scripts/revoke-capability.mjs, then run:

node --env-file=.env --import tsx/esm scripts/revoke-capability.mjs

Once revoked, paying never unlocks the endpoint — the gate returns 403.