easctl 0.1.0

package/src/commands/schema-get.ts

@@ -0,0 +1,30 @@
+import { Command } from 'commander';
+import { createReadOnlyEASClient } from '../client.js';
+import { output, handleError } from '../output.js';
+import { validateBytes32 } from '../validation.js';
+
+export const schemaGetCommand = new Command('schema-get')
+  .description('Get a schema by UID')
+  .requiredOption('-u, --uid <uid>', 'Schema UID')
+  .option('-c, --chain <name>', 'Chain name', 'ethereum')
+  .option('--rpc-url <url>', 'Custom RPC URL')
+  .action(async (opts) => {
+    try {
+      validateBytes32(opts.uid, 'schema UID');
+
+      const client = createReadOnlyEASClient(opts.chain, opts.rpcUrl);
+      const schema = await client.schemaRegistry.getSchema({ uid: opts.uid });
+
+      output({
+        success: true,
+        data: {
+          uid: schema.uid,
+          schema: schema.schema,
+          resolver: schema.resolver,
+          revocable: schema.revocable,
+        },
+      });
+    } catch (err) {
+      handleError(err);
+    }
+  });

package/src/commands/schema-register.ts

@@ -0,0 +1,49 @@
+import { Command } from 'commander';
+import { createEASClient } from '../client.js';
+import { output, handleError } from '../output.js';
+import { validateAddress } from '../validation.js';
+
+export const schemaRegisterCommand = new Command('schema-register')
+  .description('Register a new schema')
+  .requiredOption('-s, --schema <definition>', 'Schema definition (e.g. "uint256 score, string name")')
+  .option('--resolver <address>', 'Resolver contract address', '0x0000000000000000000000000000000000000000')
+  .option('--revocable', 'Whether attestations using this schema can be revoked', true)
+  .option('--no-revocable', 'Make attestations non-revocable')
+  .option('-c, --chain <name>', 'Chain name', 'ethereum')
+  .option('--rpc-url <url>', 'Custom RPC URL')
+  .option('--dry-run', 'Estimate gas without sending the transaction')
+  .action(async (opts) => {
+    try {
+      if (opts.resolver !== '0x0000000000000000000000000000000000000000') {
+        validateAddress(opts.resolver, 'resolver');
+      }
+
+      const client = createEASClient(opts.chain, opts.rpcUrl);
+
+      const tx = await client.schemaRegistry.register({
+        schema: opts.schema,
+        resolverAddress: opts.resolver,
+        revocable: opts.revocable,
+      });
+
+      if (opts.dryRun) {
+        const gasEstimate = await tx.estimateGas();
+        output({ success: true, data: { dryRun: true, estimatedGas: gasEstimate.toString(), chain: opts.chain } });
+      } else {
+        const uid = await tx.wait();
+        output({
+          success: true,
+          data: {
+            uid,
+            txHash: tx.receipt!.hash,
+            schema: opts.schema,
+            resolver: opts.resolver,
+            revocable: opts.revocable,
+            chain: opts.chain,
+          },
+        });
+      }
+    } catch (err) {
+      handleError(err);
+    }
+  });

package/src/commands/set-key.ts

@@ -0,0 +1,19 @@
+import { Command } from 'commander';
+import { ethers } from 'ethers';
+import { setStoredPrivateKey } from '../config.js';
+import { output, handleError } from '../output.js';
+
+export const setKeyCommand = new Command('set-key')
+  .description('Store your private key in ~/.eas-cli for future use')
+  .argument('<key>', 'Wallet private key (hex string, with or without 0x prefix)')
+  .action((key: string) => {
+    const normalized = key.startsWith('0x') ? key : `0x${key}`;
+
+    try {
+      const wallet = new ethers.Wallet(normalized);
+      setStoredPrivateKey(key);
+      output({ success: true, data: { address: wallet.address } });
+    } catch {
+      handleError(new Error('Invalid private key format'));
+    }
+  });

package/src/commands/timestamp.ts

@@ -0,0 +1,35 @@
+import { Command } from 'commander';
+import { createEASClient } from '../client.js';
+import { output, handleError } from '../output.js';
+
+export const timestampCommand = new Command('timestamp')
+  .description('Timestamp data on-chain')
+  .requiredOption('-d, --data <bytes32>', 'Data to timestamp (bytes32 hex string)')
+  .option('-c, --chain <name>', 'Chain name', 'ethereum')
+  .option('--rpc-url <url>', 'Custom RPC URL')
+  .option('--dry-run', 'Estimate gas without sending the transaction')
+  .action(async (opts) => {
+    try {
+      const client = createEASClient(opts.chain, opts.rpcUrl);
+
+      const tx = await client.eas.timestamp(opts.data);
+
+      if (opts.dryRun) {
+        const gasEstimate = await tx.estimateGas();
+        output({ success: true, data: { dryRun: true, estimatedGas: gasEstimate.toString(), chain: opts.chain } });
+      } else {
+        const timestamp = await tx.wait();
+        output({
+          success: true,
+          data: {
+            timestamp: timestamp.toString(),
+            txHash: tx.receipt!.hash,
+            data: opts.data,
+            chain: opts.chain,
+          },
+        });
+      }
+    } catch (err) {
+      handleError(err);
+    }
+  });

package/src/config.ts

@@ -0,0 +1,41 @@
+import { readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+interface EASConfig {
+  privateKey?: string;
+}
+
+export function getConfigPath(): string {
+  return join(homedir(), '.eas-cli');
+}
+
+export function readConfig(): EASConfig {
+  try {
+    const data = readFileSync(getConfigPath(), 'utf-8');
+    return JSON.parse(data);
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(config: EASConfig): void {
+  writeFileSync(getConfigPath(), JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+}
+
+export function getStoredPrivateKey(): string | undefined {
+  return readConfig().privateKey;
+}
+
+export function setStoredPrivateKey(key: string): void {
+  const normalized = key.startsWith('0x') ? key : `0x${key}`;
+  const config = readConfig();
+  config.privateKey = normalized;
+  writeConfig(config);
+}
+
+export function clearStoredPrivateKey(): void {
+  const config = readConfig();
+  delete config.privateKey;
+  writeConfig(config);
+}

package/src/graphql.ts

@@ -0,0 +1,136 @@
+export const EASSCAN_URLS: Record<string, string> = {
+  ethereum: 'https://easscan.org',
+  sepolia: 'https://sepolia.easscan.org',
+  base: 'https://base.easscan.org',
+  'base-sepolia': 'https://base-sepolia.easscan.org',
+  optimism: 'https://optimism.easscan.org',
+  'optimism-sepolia': 'https://optimism-sepolia.easscan.org',
+  arbitrum: 'https://arbitrum.easscan.org',
+  'arbitrum-sepolia': 'https://arbitrum-sepolia.easscan.org',
+  polygon: 'https://polygon.easscan.org',
+  scroll: 'https://scroll.easscan.org',
+  linea: 'https://linea.easscan.org',
+  celo: 'https://celo.easscan.org',
+};
+
+export function getEASScanUrl(chainName: string): string {
+  const url = EASSCAN_URLS[chainName];
+  if (!url) {
+    throw new Error(`No EASScan URL for chain "${chainName}"`);
+  }
+  return url;
+}
+
+export function getGraphQLEndpoint(chainName: string): string {
+  return `${getEASScanUrl(chainName)}/graphql`;
+}
+
+export async function graphqlQuery(
+  chainName: string,
+  query: string,
+  variables: Record<string, unknown> = {}
+): Promise<any> {
+  const endpoint = getGraphQLEndpoint(chainName);
+  const res = await fetch(endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ query, variables }),
+  });
+
+  if (!res.ok) {
+    throw new Error(`GraphQL request failed: ${res.status} ${res.statusText}`);
+  }
+
+  const json = await res.json();
+  if (json.errors?.length) {
+    throw new Error(`GraphQL error: ${json.errors[0].message}`);
+  }
+  return json.data;
+}
+
+export const QUERIES = {
+  getSchema: `
+    query GetSchema($id: String!) {
+      schema(where: { id: $id }) {
+        id
+        schema
+        creator
+        resolver
+        revocable
+        txid
+        time
+      }
+    }
+  `,
+  getAttestation: `
+    query GetAttestation($id: String!) {
+      attestation(where: { id: $id }) {
+        id
+        attester
+        recipient
+        time
+        expirationTime
+        revocationTime
+        revoked
+        revocable
+        schemaId
+        data
+        decodedDataJson
+        isOffchain
+        txid
+      }
+    }
+  `,
+  getAttestationsBySchema: `
+    query GetAttestationsBySchema($schemaId: String!, $take: Int, $skip: Int) {
+      attestations(
+        where: { schemaId: { equals: $schemaId } }
+        take: $take
+        skip: $skip
+        orderBy: [{ time: desc }]
+      ) {
+        id
+        attester
+        recipient
+        time
+        revoked
+        decodedDataJson
+        isOffchain
+      }
+    }
+  `,
+  getAttestationsByAttester: `
+    query GetAttestationsByAttester($attester: String!, $take: Int, $skip: Int) {
+      attestations(
+        where: { attester: { equals: $attester } }
+        take: $take
+        skip: $skip
+        orderBy: [{ time: desc }]
+      ) {
+        id
+        recipient
+        schemaId
+        time
+        revoked
+        decodedDataJson
+        isOffchain
+      }
+    }
+  `,
+  getSchemata: `
+    query GetSchemata($creator: String, $take: Int, $skip: Int) {
+      schemata(
+        where: { creator: { equals: $creator } }
+        take: $take
+        skip: $skip
+        orderBy: [{ time: desc }]
+      ) {
+        id
+        schema
+        creator
+        revocable
+        time
+      }
+    }
+  `,
+};

package/src/index.ts

@@ -0,0 +1,74 @@
+import { Command } from 'commander';
+import { setJsonMode, output } from './output.js';
+import { listChains } from './chains.js';
+import { attestCommand } from './commands/attest.js';
+import { revokeCommand } from './commands/revoke.js';
+import { getAttestationCommand } from './commands/get-attestation.js';
+import { schemaRegisterCommand } from './commands/schema-register.js';
+import { schemaGetCommand } from './commands/schema-get.js';
+import { multiAttestCommand } from './commands/multi-attest.js';
+import { offchainAttestCommand } from './commands/offchain-attest.js';
+import { timestampCommand } from './commands/timestamp.js';
+import { querySchemaCommand } from './commands/query-schema.js';
+import { queryAttestationCommand } from './commands/query-attestation.js';
+import { queryAttestationsCommand } from './commands/query-attestations.js';
+import { querySchemasCommand } from './commands/query-schemas.js';
+import { multiRevokeCommand } from './commands/multi-revoke.js';
+import { multiTimestampCommand } from './commands/multi-timestamp.js';
+import { setKeyCommand } from './commands/set-key.js';
+import { clearKeyCommand } from './commands/clear-key.js';
+
+const program = new Command();
+
+program
+  .name('easctl')
+  .description('Ethereum Attestation Service CLI — create, revoke, and query attestations')
+  .version(process.env.CLI_VERSION || '0.0.0-dev')
+  .option('--json', 'Output results as JSON (useful for agents and scripting)')
+  .hook('preAction', (thisCommand, actionCommand) => {
+    if (thisCommand.opts().json || actionCommand.opts().json) {
+      setJsonMode(true);
+    }
+  });
+
+// Attestation commands
+program.addCommand(attestCommand);
+program.addCommand(multiAttestCommand);
+program.addCommand(offchainAttestCommand);
+program.addCommand(revokeCommand);
+program.addCommand(multiRevokeCommand);
+program.addCommand(getAttestationCommand);
+
+// Schema commands
+program.addCommand(schemaRegisterCommand);
+program.addCommand(schemaGetCommand);
+
+// Timestamp commands
+program.addCommand(timestampCommand);
+program.addCommand(multiTimestampCommand);
+
+// GraphQL query commands
+program.addCommand(querySchemaCommand);
+program.addCommand(queryAttestationCommand);
+program.addCommand(queryAttestationsCommand);
+program.addCommand(querySchemasCommand);
+
+// Key management commands
+program.addCommand(setKeyCommand);
+program.addCommand(clearKeyCommand);
+
+// Chains command
+program
+  .command('chains')
+  .description('List supported chains and their EAS contract addresses')
+  .action(() => {
+    const chains = listChains();
+    output({ success: true, data: { chains } });
+  });
+
+// Add --json to every subcommand so it works regardless of position
+for (const cmd of program.commands) {
+  cmd.option('--json', 'Output results as JSON');
+}
+
+program.parse();

package/src/output.ts

@@ -0,0 +1,50 @@
+export interface CLIOutput {
+  success: boolean;
+  data?: Record<string, unknown>;
+  error?: string;
+}
+
+let jsonMode = false;
+
+export function setJsonMode(enabled: boolean) {
+  jsonMode = enabled;
+}
+
+export function isJsonMode(): boolean {
+  return jsonMode;
+}
+
+export function output(result: CLIOutput) {
+  if (jsonMode) {
+    console.log(JSON.stringify(result, bigintReplacer, 2));
+  } else if (result.success && result.data) {
+    for (const [key, value] of Object.entries(result.data)) {
+      if (typeof value === 'object' && value !== null) {
+        console.log(`${key}:`);
+        for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+          console.log(`  ${k}: ${formatValue(v)}`);
+        }
+      } else {
+        console.log(`${key}: ${formatValue(value)}`);
+      }
+    }
+  } else if (!result.success && result.error) {
+    console.error(`Error: ${result.error}`);
+  }
+}
+
+function formatValue(v: unknown): string {
+  if (typeof v === 'bigint') return v.toString();
+  if (typeof v === 'object' && v !== null) return JSON.stringify(v, bigintReplacer);
+  return String(v);
+}
+
+function bigintReplacer(_key: string, value: unknown): unknown {
+  return typeof value === 'bigint' ? value.toString() : value;
+}
+
+export function handleError(err: unknown): never {
+  const message = err instanceof Error ? err.message : String(err);
+  output({ success: false, error: message });
+  process.exit(1);
+}

package/src/stdin.ts

@@ -0,0 +1,15 @@
+export async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const text = Buffer.concat(chunks).toString('utf-8').trim();
+  if (!text) {
+    throw new Error('No data received from stdin');
+  }
+  return text;
+}
+
+export async function resolveInput(value: string): Promise<string> {
+  return value === '-' ? readStdin() : value;
+}

package/src/validation.ts

@@ -0,0 +1,15 @@
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+
+export function validateAddress(value: string, label: string): void {
+  if (!ADDRESS_RE.test(value)) {
+    throw new Error(`Invalid ${label} address: expected 0x + 40 hex characters, got "${value}"`);
+  }
+}
+
+const BYTES32_RE = /^0x[0-9a-fA-F]{64}$/;
+
+export function validateBytes32(value: string, label: string): void {
+  if (!BYTES32_RE.test(value)) {
+    throw new Error(`Invalid ${label}: expected 0x + 64 hex characters, got "${value}"`);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from 'tsup';
+import pkg from './package.json';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  format: ['cjs'],
+  target: 'node18',
+  clean: true,
+  sourcemap: true,
+  noExternal: [
+    '@ethereum-attestation-service/eas-sdk',
+    '@ethereum-attestation-service/eas-contracts',
+    '@ethereum-attestation-service/eas-contracts-legacy',
+  ],
+  define: {
+    'process.env.CLI_VERSION': JSON.stringify(pkg.version),
+  },
+  banner: {
+    js: '#!/usr/bin/env node',
+  },
+});

package/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['src/__tests__/**/*.test.ts'],
+  },
+});