easctl 0.1.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "easctl",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "CLI tool for the Ethereum Attestation Service — create, revoke, and query attestations from the command line",
   "bin": {
     "easctl": "./dist/index.js"

package/src/__tests__/commands/attest.test.ts

@@ -25,6 +25,7 @@ vi.mock('../../stdin.js', () => ({
 vi.mock('../../validation.js', () => ({
   validateAddress: vi.fn(),
   validateBytes32: vi.fn(),
+  resolveAndValidateSchemaUID: vi.fn((v: string) => v),
 }));
 
 const mockEncodeData = vi.fn().mockReturnValue('0xencoded');

package/src/__tests__/commands/multi-attest.test.ts

@@ -22,6 +22,10 @@ vi.mock('../../stdin.js', () => ({
   resolveInput: vi.fn((v: string) => Promise.resolve(v)),
 }));
 
+vi.mock('../../popular-schemas.js', () => ({
+  resolveSchemaUID: vi.fn((v: string) => v),
+}));
+
 const mockEncodeData = vi.fn().mockReturnValue('0xencoded');
 
 vi.mock('@ethereum-attestation-service/eas-sdk', () => ({

package/src/__tests__/commands/multi-revoke.test.ts

@@ -21,6 +21,10 @@ vi.mock('../../stdin.js', () => ({
   resolveInput: vi.fn((v: string) => Promise.resolve(v)),
 }));
 
+vi.mock('../../popular-schemas.js', () => ({
+  resolveSchemaUID: vi.fn((v: string) => v),
+}));
+
 import { multiRevokeCommand } from '../../commands/multi-revoke.js';
 import { output, handleError } from '../../output.js';
 

package/src/__tests__/commands/offchain-attest.test.ts

@@ -28,6 +28,7 @@ vi.mock('../../stdin.js', () => ({
 }));
 
 vi.mock('../../validation.js', () => ({
+  resolveAndValidateSchemaUID: vi.fn((v: string) => v),
   validateAddress: vi.fn(),
   validateBytes32: vi.fn(),
 }));

package/src/__tests__/commands/query-attestations.test.ts

@@ -16,6 +16,7 @@ vi.mock('../../output.js', () => ({
 vi.mock('../../validation.js', () => ({
   validateAddress: vi.fn(),
   validateBytes32: vi.fn(),
+  resolveAndValidateSchemaUID: vi.fn((v: string) => v),
 }));
 
 import { queryAttestationsCommand } from '../../commands/query-attestations.js';

package/src/__tests__/commands/query-schema.test.ts

@@ -14,6 +14,7 @@ vi.mock('../../output.js', () => ({
 
 vi.mock('../../validation.js', () => ({
   validateBytes32: vi.fn(),
+  resolveAndValidateSchemaUID: vi.fn((v: string) => v),
 }));
 
 import { querySchemaCommand } from '../../commands/query-schema.js';

package/src/__tests__/commands/revoke.test.ts

@@ -19,6 +19,7 @@ vi.mock('../../output.js', () => ({
 
 vi.mock('../../validation.js', () => ({
   validateBytes32: vi.fn(),
+  resolveAndValidateSchemaUID: vi.fn((v: string) => v),
 }));
 
 import { revokeCommand } from '../../commands/revoke.js';

package/src/__tests__/commands/schema-get.test.ts

@@ -21,6 +21,7 @@ vi.mock('../../output.js', () => ({
 
 vi.mock('../../validation.js', () => ({
   validateBytes32: vi.fn(),
+  resolveAndValidateSchemaUID: vi.fn((v: string) => v),
 }));
 
 import { schemaGetCommand } from '../../commands/schema-get.js';

package/src/__tests__/commands/status.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+vi.mock('../../output.js', () => ({
+  output: vi.fn(),
+  handleError: vi.fn(),
+}));
+
+vi.mock('../../config.js', () => ({
+  getStoredPrivateKey: vi.fn(() => undefined),
+}));
+
+import { statusCommand } from '../../commands/status.js';
+import { output } from '../../output.js';
+import { getStoredPrivateKey } from '../../config.js';
+
+describe('status command', () => {
+  const originalEnv = process.env.EAS_PRIVATE_KEY;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    delete process.env.EAS_PRIVATE_KEY;
+  });
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env.EAS_PRIVATE_KEY = originalEnv;
+    } else {
+      delete process.env.EAS_PRIVATE_KEY;
+    }
+  });
+
+  async function runCommand(args: string[] = []) {
+    await statusCommand.parseAsync(['node', 'test', ...args]);
+  }
+
+  it('shows key not set when no key is configured', async () => {
+    await runCommand();
+
+    expect(output).toHaveBeenCalledWith({
+      success: true,
+      data: expect.objectContaining({
+        wallet: { privateKey: 'not set', address: 'n/a' },
+      }),
+    });
+  });
+
+  it('shows address from env var with source', async () => {
+    process.env.EAS_PRIVATE_KEY = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+    await runCommand();
+
+    expect(output).toHaveBeenCalledWith({
+      success: true,
+      data: expect.objectContaining({
+        wallet: {
+          privateKey: 'set (env)',
+          address: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266',
+        },
+      }),
+    });
+  });
+
+  it('shows address from stored key', async () => {
+    vi.mocked(getStoredPrivateKey).mockReturnValue('0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80');
+    await runCommand();
+
+    const call = (output as any).mock.calls[0][0];
+    expect(call.data.wallet.privateKey).toBe('set (stored)');
+    expect(call.data.wallet.address).toBe('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266');
+  });
+
+  it('shows address when key has no 0x prefix', async () => {
+    process.env.EAS_PRIVATE_KEY = 'ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80';
+    await runCommand();
+
+    const call = (output as any).mock.calls[0][0];
+    expect(call.data.wallet.privateKey).toBe('set (env)');
+    expect(call.data.wallet.address).toBe('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266');
+  });
+
+  it('shows invalid format for a bad key', async () => {
+    process.env.EAS_PRIVATE_KEY = 'not-a-real-key';
+    await runCommand();
+
+    const call = (output as any).mock.calls[0][0];
+    expect(call.data.wallet.privateKey).toBe('set (invalid format)');
+    expect(call.data.wallet.address).toBe('n/a');
+  });
+
+  it('defaults to ethereum chain', async () => {
+    await runCommand();
+
+    const call = (output as any).mock.calls[0][0];
+    expect(call.data.chain.name).toBe('ethereum');
+    expect(call.data.chain.chainId).toBe(1);
+  });
+
+  it('shows correct config for --chain base', async () => {
+    await runCommand(['--chain', 'base']);
+
+    const call = (output as any).mock.calls[0][0];
+    expect(call.data.chain.name).toBe('base');
+    expect(call.data.chain.chainId).toBe(8453);
+    expect(call.data.contracts.eas).toBe('0x4200000000000000000000000000000000000021');
+  });
+
+  it('uses custom rpc-url when provided', async () => {
+    await runCommand(['--rpc-url', 'https://custom.rpc']);
+
+    const call = (output as any).mock.calls[0][0];
+    expect(call.data.chain.rpcUrl).toBe('https://custom.rpc');
+  });
+
+  it('lists supported chains', async () => {
+    await runCommand();
+
+    const call = (output as any).mock.calls[0][0];
+    expect(call.data.supportedChains).toContain('ethereum');
+    expect(call.data.supportedChains).toContain('base');
+    expect(call.data.supportedChains).toContain('sepolia');
+  });
+});

package/src/__tests__/config.test.ts

@@ -22,8 +22,8 @@ describe('config module', () => {
   beforeEach(() => vi.clearAllMocks());
 
   describe('getConfigPath', () => {
-    it('returns ~/.eas-cli', () => {
-      expect(getConfigPath()).toBe('/mock/home/.eas-cli');
+    it('returns ~/.easctl', () => {
+      expect(getConfigPath()).toBe('/mock/home/.easctl');
     });
   });
 
@@ -61,7 +61,7 @@ describe('config module', () => {
       vi.mocked(readFileSync).mockReturnValue('{}');
       setStoredPrivateKey('0xabc123');
       expect(writeFileSync).toHaveBeenCalledWith(
-        '/mock/home/.eas-cli',
+        '/mock/home/.easctl',
         JSON.stringify({ privateKey: '0xabc123' }, null, 2) + '\n',
         { mode: 0o600 },
       );
@@ -71,7 +71,7 @@ describe('config module', () => {
       vi.mocked(readFileSync).mockReturnValue('{}');
       setStoredPrivateKey('abc123');
       expect(writeFileSync).toHaveBeenCalledWith(
-        '/mock/home/.eas-cli',
+        '/mock/home/.easctl',
         JSON.stringify({ privateKey: '0xabc123' }, null, 2) + '\n',
         { mode: 0o600 },
       );

package/src/commands/attest.ts

@@ -3,11 +3,11 @@ import { SchemaEncoder, NO_EXPIRATION, ZERO_BYTES32 } from '@ethereum-attestatio
 import { createEASClient } from '../client.js';
 import { output, handleError } from '../output.js';
 import { resolveInput } from '../stdin.js';
-import { validateAddress, validateBytes32 } from '../validation.js';
+import { validateAddress, resolveAndValidateSchemaUID } from '../validation.js';
 
 export const attestCommand = new Command('attest')
   .description('Create an on-chain attestation')
-  .requiredOption('-s, --schema <uid>', 'Schema UID to attest with')
+  .requiredOption('-s, --schema <uid>', 'Schema UID or popular schema name')
   .requiredOption('-d, --data <json>', 'Attestation data as JSON array: [{"name":"field","type":"uint256","value":"123"}]')
   .option('-r, --recipient <address>', 'Recipient address', '0x0000000000000000000000000000000000000000')
   .option('--ref-uid <uid>', 'Referenced attestation UID', ZERO_BYTES32)
@@ -20,7 +20,7 @@ export const attestCommand = new Command('attest')
   .option('--dry-run', 'Estimate gas without sending the transaction')
   .action(async (opts) => {
     try {
-      validateBytes32(opts.schema, 'schema UID');
+      opts.schema = resolveAndValidateSchemaUID(opts.schema, 'schema UID');
       if (opts.recipient !== '0x0000000000000000000000000000000000000000') {
         validateAddress(opts.recipient, 'recipient');
       }

package/src/commands/clear-key.ts

@@ -3,7 +3,7 @@ import { clearStoredPrivateKey, getStoredPrivateKey } from '../config.js';
 import { output } from '../output.js';
 
 export const clearKeyCommand = new Command('clear-key')
-  .description('Remove the stored private key from ~/.eas-cli')
+  .description('Remove the stored private key from ~/.easctl')
   .action(() => {
     if (!getStoredPrivateKey()) {
       output({ success: true, data: { cleared: false, message: 'No private key is currently stored' } });

package/src/commands/multi-attest.ts

@@ -3,6 +3,7 @@ import { SchemaEncoder, NO_EXPIRATION, ZERO_BYTES32 } from '@ethereum-attestatio
 import { createEASClient } from '../client.js';
 import { output, handleError } from '../output.js';
 import { resolveInput } from '../stdin.js';
+import { resolveSchemaUID } from '../popular-schemas.js';
 
 interface AttestationInput {
   schema: string;
@@ -34,6 +35,7 @@ export const multiAttestCommand = new Command('multi-attest')
       const grouped = new Map<string, { schema: string; data: any[] }>();
 
       for (const input of inputs) {
+        input.schema = resolveSchemaUID(input.schema);
         const schemaString = input.data.map((item) => `${item.type} ${item.name}`).join(', ');
         const encoder = new SchemaEncoder(schemaString);
         const encodedData = encoder.encodeData(input.data as any);

package/src/commands/multi-revoke.ts

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import { createEASClient } from '../client.js';
 import { output, handleError } from '../output.js';
 import { resolveInput } from '../stdin.js';
+import { resolveSchemaUID } from '../popular-schemas.js';
 
 interface RevocationInput {
   schema: string;
@@ -29,6 +30,7 @@ export const multiRevokeCommand = new Command('multi-revoke')
       const grouped = new Map<string, { schema: string; data: any[] }>();
 
       for (const input of inputs) {
+        input.schema = resolveSchemaUID(input.schema);
         if (!grouped.has(input.schema)) {
           grouped.set(input.schema, { schema: input.schema, data: [] });
         }

package/src/commands/offchain-attest.ts

@@ -8,12 +8,12 @@ import {
 import { createEASClient } from '../client.js';
 import { output, handleError } from '../output.js';
 import { resolveInput } from '../stdin.js';
-import { validateAddress, validateBytes32 } from '../validation.js';
+import { validateAddress, resolveAndValidateSchemaUID } from '../validation.js';
 import { EASSCAN_URLS } from '../graphql.js';
 
 export const offchainAttestCommand = new Command('offchain-attest')
   .description('Create an off-chain attestation (signed but not submitted on-chain)')
-  .requiredOption('-s, --schema <uid>', 'Schema UID')
+  .requiredOption('-s, --schema <uid>', 'Schema UID or popular schema name')
   .requiredOption('-d, --data <json>', 'Attestation data as JSON array: [{"name":"field","type":"uint256","value":"123"}]')
   .option('-r, --recipient <address>', 'Recipient address', '0x0000000000000000000000000000000000000000')
   .option('--ref-uid <uid>', 'Referenced attestation UID', ZERO_BYTES32)
@@ -24,7 +24,7 @@ export const offchainAttestCommand = new Command('offchain-attest')
   .option('--rpc-url <url>', 'Custom RPC URL')
   .action(async (opts) => {
     try {
-      validateBytes32(opts.schema, 'schema UID');
+      opts.schema = resolveAndValidateSchemaUID(opts.schema, 'schema UID');
       if (opts.recipient !== '0x0000000000000000000000000000000000000000') {
         validateAddress(opts.recipient, 'recipient');
       }

package/src/commands/popular-schemas.ts

@@ -0,0 +1,43 @@
+import { Command } from 'commander';
+import { output, isJsonMode, handleError } from '../output.js';
+import { listPopularSchemas, listPopularSchemasByCategory } from '../popular-schemas.js';
+
+export const popularSchemasCommand = new Command('popular-schemas')
+  .description('List popular EAS schemas with names, UIDs, and descriptions')
+  .option('--category <name>', 'Filter by category (general, identity, social)')
+  .action(async (opts) => {
+    try {
+      if (isJsonMode()) {
+        const schemas = opts.category
+          ? listPopularSchemas().filter((s) => s.category === opts.category)
+          : listPopularSchemas();
+        if (opts.category && schemas.length === 0) {
+          const categories = [...new Set(listPopularSchemas().map((s) => s.category))];
+          throw new Error(`Unknown category "${opts.category}". Available: ${categories.join(', ')}`);
+        }
+        output({ success: true, data: { count: schemas.length, schemas } as any });
+        return;
+      }
+
+      const byCategory = listPopularSchemasByCategory();
+      const categories = opts.category ? { [opts.category]: byCategory[opts.category] } : byCategory;
+
+      if (opts.category && !byCategory[opts.category]) {
+        const available = Object.keys(byCategory).join(', ');
+        throw new Error(`Unknown category "${opts.category}". Available: ${available}`);
+      }
+
+      for (const [category, schemas] of Object.entries(categories)) {
+        console.log(`\n=== ${category} ===\n`);
+        for (const s of schemas) {
+          console.log(`  ${s.name}`);
+          console.log(`    Schema:    ${s.schema}`);
+          console.log(`    UID:       ${s.uid}`);
+          console.log(`    Revocable: ${s.revocable ? 'yes' : 'no'}`);
+          console.log(`    ${s.description}\n`);
+        }
+      }
+    } catch (err) {
+      handleError(err);
+    }
+  });

package/src/commands/query-attestations.ts

@@ -1,11 +1,11 @@
 import { Command } from 'commander';
 import { graphqlQuery, QUERIES } from '../graphql.js';
 import { output, handleError } from '../output.js';
-import { validateAddress, validateBytes32 } from '../validation.js';
+import { validateAddress, resolveAndValidateSchemaUID } from '../validation.js';
 
 export const queryAttestationsCommand = new Command('query-attestations')
   .description('Query attestations by schema or attester from the EAS GraphQL API')
-  .option('-s, --schema <uid>', 'Filter by schema UID')
+  .option('-s, --schema <uid>', 'Filter by schema UID or popular schema name')
   .option('-a, --attester <address>', 'Filter by attester address')
   .option('-n, --limit <number>', 'Max results to return', '10')
   .option('--skip <number>', 'Number of results to skip (for pagination)', '0')
@@ -15,7 +15,7 @@ export const queryAttestationsCommand = new Command('query-attestations')
       if (!opts.schema && !opts.attester) {
         throw new Error('Provide at least one filter: --schema or --attester');
       }
-      if (opts.schema) validateBytes32(opts.schema, 'schema UID');
+      if (opts.schema) opts.schema = resolveAndValidateSchemaUID(opts.schema, 'schema UID');
       if (opts.attester) validateAddress(opts.attester, 'attester');
 
       const take = parseInt(opts.limit, 10);

package/src/commands/query-schema.ts

@@ -1,15 +1,15 @@
 import { Command } from 'commander';
 import { graphqlQuery, QUERIES } from '../graphql.js';
 import { output, handleError } from '../output.js';
-import { validateBytes32 } from '../validation.js';
+import { resolveAndValidateSchemaUID } from '../validation.js';
 
 export const querySchemaCommand = new Command('query-schema')
   .description('Query a schema from the EAS GraphQL API')
-  .requiredOption('-u, --uid <uid>', 'Schema UID')
+  .requiredOption('-u, --uid <uid>', 'Schema UID or popular schema name')
   .option('-c, --chain <name>', 'Chain name', 'ethereum')
   .action(async (opts) => {
     try {
-      validateBytes32(opts.uid, 'schema UID');
+      opts.uid = resolveAndValidateSchemaUID(opts.uid, 'schema UID');
 
       const data = await graphqlQuery(opts.chain, QUERIES.getSchema, { id: opts.uid });
 

package/src/commands/revoke.ts

@@ -1,11 +1,11 @@
 import { Command } from 'commander';
 import { createEASClient } from '../client.js';
 import { output, handleError } from '../output.js';
-import { validateBytes32 } from '../validation.js';
+import { validateBytes32, resolveAndValidateSchemaUID } from '../validation.js';
 
 export const revokeCommand = new Command('revoke')
   .description('Revoke an on-chain attestation')
-  .requiredOption('-s, --schema <uid>', 'Schema UID of the attestation')
+  .requiredOption('-s, --schema <uid>', 'Schema UID or popular schema name')
   .requiredOption('-u, --uid <uid>', 'Attestation UID to revoke')
   .option('--value <wei>', 'ETH value to send (in wei)', '0')
   .option('-c, --chain <name>', 'Chain name', 'ethereum')
@@ -13,7 +13,7 @@ export const revokeCommand = new Command('revoke')
   .option('--dry-run', 'Estimate gas without sending the transaction')
   .action(async (opts) => {
     try {
-      validateBytes32(opts.schema, 'schema UID');
+      opts.schema = resolveAndValidateSchemaUID(opts.schema, 'schema UID');
       validateBytes32(opts.uid, 'attestation UID');
 
       const client = createEASClient(opts.chain, opts.rpcUrl);

package/src/commands/schema-get.ts

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

package/src/commands/set-key.ts

@@ -4,7 +4,7 @@ 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')
+  .description('Store your private key in ~/.easctl 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}`;

package/src/commands/status.ts

@@ -0,0 +1,49 @@
+import { Command } from 'commander';
+import { ethers } from 'ethers';
+import { CHAIN_CONFIGS, listChains } from '../chains.js';
+import { output } from '../output.js';
+import { getStoredPrivateKey } from '../config.js';
+
+export const statusCommand = new Command('status')
+  .description('Show current configuration: wallet, chain, and contract addresses')
+  .option('-c, --chain <name>', 'Chain name', 'ethereum')
+  .option('--rpc-url <url>', 'Custom RPC URL')
+  .action(async (opts) => {
+    const key = process.env.EAS_PRIVATE_KEY || getStoredPrivateKey();
+    const source = process.env.EAS_PRIVATE_KEY ? 'env' : key ? 'stored' : undefined;
+    let address: string | undefined;
+
+    if (key) {
+      try {
+        const normalized = key.startsWith('0x') ? key : `0x${key}`;
+        address = new ethers.Wallet(normalized).address;
+      } catch {
+        // invalid key format
+      }
+    }
+
+    const chainConfig = CHAIN_CONFIGS[opts.chain];
+    const rpcUrl = opts.rpcUrl || chainConfig?.defaultRpc || 'none';
+
+    output({
+      success: true,
+      data: {
+        wallet: {
+          privateKey: source ? (address ? `set (${source})` : `set (invalid format)`) : 'not set',
+          address: address || 'n/a',
+        },
+        chain: {
+          name: opts.chain,
+          chainId: chainConfig?.chainId ?? 'unknown chain',
+          rpcUrl,
+        },
+        contracts: chainConfig
+          ? {
+              eas: chainConfig.eas,
+              schemaRegistry: chainConfig.schemaRegistry,
+            }
+          : 'unknown chain',
+        supportedChains: listChains().join(', '),
+      },
+    });
+  });

package/src/config.ts

@@ -7,7 +7,7 @@ interface EASConfig {
 }
 
 export function getConfigPath(): string {
-  return join(homedir(), '.eas-cli');
+  return join(homedir(), '.easctl');
 }
 
 export function readConfig(): EASConfig {

package/src/index.ts

@@ -17,6 +17,8 @@ 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';
+import { popularSchemasCommand } from './commands/popular-schemas.js';
+import { statusCommand } from './commands/status.js';
 
 const program = new Command();
 
@@ -42,6 +44,7 @@ program.addCommand(getAttestationCommand);
 // Schema commands
 program.addCommand(schemaRegisterCommand);
 program.addCommand(schemaGetCommand);
+program.addCommand(popularSchemasCommand);
 
 // Timestamp commands
 program.addCommand(timestampCommand);
@@ -57,6 +60,9 @@ program.addCommand(querySchemasCommand);
 program.addCommand(setKeyCommand);
 program.addCommand(clearKeyCommand);
 
+// Status command
+program.addCommand(statusCommand);
+
 // Chains command
 program
   .command('chains')