easctl 0.1.3 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "easctl",
-  "version": "0.1.3",
+  "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/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/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/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/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')

package/src/popular-schemas.ts

@@ -0,0 +1,119 @@
+export interface PopularSchema {
+  name: string;
+  schema: string;
+  uid: string;
+  description: string;
+  revocable: boolean;
+  category: string;
+}
+
+// UIDs are deterministic: keccak256(abi.encodePacked(schema, address(0), revocable))
+// Same UID on every chain (no resolver).
+export const POPULAR_SCHEMAS: PopularSchema[] = [
+  // General
+  {
+    name: 'make-a-statement',
+    schema: 'string statement',
+    uid: '0xf58b8b212ef75ee8cd7e8d803c37c03e0519890502d5e99ee2412aae1456cafe',
+    description: 'General-purpose text statement or note',
+    revocable: true,
+    category: 'general',
+  },
+  {
+    name: 'is-true',
+    schema: 'bool isTrue',
+    uid: '0x4eb603f49d68888d7f8b1fadd351b35a252f287ba465408ceb2b1e1e1efd90d5',
+    description: 'Simple boolean assertion',
+    revocable: true,
+    category: 'general',
+  },
+  {
+    name: 'score',
+    schema: 'uint256 score',
+    uid: '0xef2dbf5e8da46ea760bb4c6eb2635bf04adfc1ade6158e594263363db2a55bcf',
+    description: 'Numeric score or rating',
+    revocable: true,
+    category: 'general',
+  },
+  {
+    name: 'tag',
+    schema: 'bytes32 tag',
+    uid: '0x7d105b048bfc4c781474627045d2fb9008016018b3f2af686eef31ee6d1d5857',
+    description: 'Arbitrary tag or label',
+    revocable: true,
+    category: 'general',
+  },
+  // Identity
+  {
+    name: 'is-a-human',
+    schema: 'bool isHuman',
+    uid: '0x8af15e65888f2e3b487e536a4922e277dcfe85b4b18187b0cf9afdb802ba6bb6',
+    description: 'Humanity verification attestation',
+    revocable: true,
+    category: 'identity',
+  },
+  {
+    name: 'verified-account',
+    schema: 'string platform, string username',
+    uid: '0xa0ce1ea8fd393b308ec22d86a9a4451bb16e61f455f964374f2105a371077d02',
+    description: 'Social account verification (platform + username)',
+    revocable: true,
+    category: 'identity',
+  },
+  // Social
+  {
+    name: 'is-a-friend',
+    schema: 'bool isFriend',
+    uid: '0x27d06e3659317e9a4f8154d1e849eb53d43d91fb4f219884d1684f86d797804a',
+    description: 'Friendship attestation',
+    revocable: true,
+    category: 'social',
+  },
+  {
+    name: 'met-irl',
+    schema: 'bool metIRL',
+    uid: '0xc59265615401143689cbfe73046a922c975c99d97e4c248070435b1104b2dea7',
+    description: 'Attest that you met someone in real life',
+    revocable: true,
+    category: 'social',
+  },
+  {
+    name: 'vouch',
+    schema: 'address vouched, string context',
+    uid: '0xec3decee9f94f4ef4d1a95b23743ac4904b1b8687164e266564945efd435cf48',
+    description: 'Vouch for an address with context',
+    revocable: true,
+    category: 'social',
+  },
+  {
+    name: 'endorsement',
+    schema: 'string endorsement',
+    uid: '0xb7fb3a3cae206db4784b42600aaaa640d20babf3b2d4b45161c4856f2b6c6aec',
+    description: 'Open-ended endorsement',
+    revocable: true,
+    category: 'social',
+  },
+];
+
+const byName = new Map(POPULAR_SCHEMAS.map((s) => [s.name, s]));
+
+export function getPopularSchemaByName(name: string): PopularSchema | undefined {
+  return byName.get(name);
+}
+
+export function resolveSchemaUID(value: string): string {
+  const schema = byName.get(value);
+  return schema ? schema.uid : value;
+}
+
+export function listPopularSchemas(): PopularSchema[] {
+  return POPULAR_SCHEMAS;
+}
+
+export function listPopularSchemasByCategory(): Record<string, PopularSchema[]> {
+  const grouped: Record<string, PopularSchema[]> = {};
+  for (const s of POPULAR_SCHEMAS) {
+    (grouped[s.category] ??= []).push(s);
+  }
+  return grouped;
+}

package/src/validation.ts

@@ -1,3 +1,5 @@
+import { resolveSchemaUID } from './popular-schemas.js';
+
 const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
 
 export function validateAddress(value: string, label: string): void {
@@ -13,3 +15,9 @@ export function validateBytes32(value: string, label: string): void {
     throw new Error(`Invalid ${label}: expected 0x + 64 hex characters, got "${value}"`);
   }
 }
+
+export function resolveAndValidateSchemaUID(value: string, label: string): string {
+  const resolved = resolveSchemaUID(value);
+  validateBytes32(resolved, label);
+  return resolved;
+}