easctl 0.1.3 → 0.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 Command-line interface for the [Ethereum Attestation Service](https://attest.org). Built on [EAS SDK v2](https://github.com/ethereum-attestation-service/eas-sdk-v2) and [ethers](https://docs.ethers.org).
 
-All commands support `--json` for structured output and `--dry-run` for gas estimation without sending transactions.
+All commands support `--json` for structured output, `--dry-run` for gas estimation, and popular schema names (e.g. `--schema make-a-statement`) instead of raw UIDs.
 
 ## Installation
 
@@ -88,8 +88,24 @@ easctl schema-register --schema "uint256 score, string comment" --chain sepolia
 
 # Get a schema by UID (read-only)
 easctl schema-get --uid 0xSchemaUID --chain sepolia
+
+# Browse popular schemas
+easctl popular-schemas
+easctl popular-schemas --category social
+easctl popular-schemas --json
+```
+
+#### Popular Schema Names
+
+Instead of raw UIDs, you can use popular schema names anywhere a schema UID is accepted:
+
+```bash
+easctl attest --schema make-a-statement --data '[{"name":"statement","type":"string","value":"Hello EAS"}]'
+easctl query-attestations --schema is-a-friend --chain base
 ```
 
+Run `easctl popular-schemas` to see all available names.
+
 ### Timestamps
 
 ```bash
@@ -122,6 +138,10 @@ easctl query-schemas --creator 0xAddress --limit 20 --chain sepolia
 ### Utility
 
 ```bash
+# Show wallet, chain, and contract configuration
+easctl status
+easctl status --chain base
+
 # List supported chains
 easctl chains
 ```

package/dist/index.js

@@ -22504,13 +22504,16 @@ var require_dist4 = __commonJS({
 });
 
 // src/index.ts
-var import_commander17 = require("commander");
+var import_commander19 = require("commander");
 
 // src/output.ts
 var jsonMode = false;
 function setJsonMode(enabled) {
   jsonMode = enabled;
 }
+function isJsonMode() {
+  return jsonMode;
+}
 function output(result) {
   if (jsonMode) {
     console.log(JSON.stringify(result, bigintReplacer, 2));
@@ -30611,7 +30614,7 @@ var import_fs = require("fs");
 var import_os = require("os");
 var import_path = require("path");
 function getConfigPath() {
-  return (0, import_path.join)((0, import_os.homedir)(), ".eas-cli");
+  return (0, import_path.join)((0, import_os.homedir)(), ".easctl");
 }
 function readConfig() {
   try {
@@ -30689,6 +30692,108 @@ async function resolveInput(value) {
   return value === "-" ? readStdin() : value;
 }
 
+// src/popular-schemas.ts
+var POPULAR_SCHEMAS = [
+  // 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"
+  }
+];
+var byName = new Map(POPULAR_SCHEMAS.map((s) => [s.name, s]));
+function resolveSchemaUID(value) {
+  const schema = byName.get(value);
+  return schema ? schema.uid : value;
+}
+function listPopularSchemas() {
+  return POPULAR_SCHEMAS;
+}
+function listPopularSchemasByCategory() {
+  const grouped = {};
+  for (const s of POPULAR_SCHEMAS) {
+    (grouped[s.category] ??= []).push(s);
+  }
+  return grouped;
+}
+
 // src/validation.ts
 var ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
 function validateAddress(value, label) {
@@ -30702,11 +30807,16 @@ function validateBytes32(value, label) {
     throw new Error(`Invalid ${label}: expected 0x + 64 hex characters, got "${value}"`);
   }
 }
+function resolveAndValidateSchemaUID(value, label) {
+  const resolved = resolveSchemaUID(value);
+  validateBytes32(resolved, label);
+  return resolved;
+}
 
 // src/commands/attest.ts
-var attestCommand = new import_commander.Command("attest").description("Create an on-chain attestation").requiredOption("-s, --schema <uid>", "Schema UID to attest with").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).option("--expiration <timestamp>", "Expiration timestamp (0 for none)", "0").option("--revocable", "Whether the attestation is revocable", true).option("--no-revocable", "Make the attestation non-revocable").option("--value <wei>", "ETH value to send (in wei)", "0").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) => {
+var attestCommand = new import_commander.Command("attest").description("Create an on-chain attestation").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).option("--expiration <timestamp>", "Expiration timestamp (0 for none)", "0").option("--revocable", "Whether the attestation is revocable", true).option("--no-revocable", "Make the attestation non-revocable").option("--value <wei>", "ETH value to send (in wei)", "0").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 {
-    validateBytes32(opts.schema, "schema UID");
+    opts.schema = resolveAndValidateSchemaUID(opts.schema, "schema UID");
     if (opts.recipient !== "0x0000000000000000000000000000000000000000") {
       validateAddress(opts.recipient, "recipient");
     }
@@ -30756,9 +30866,9 @@ var attestCommand = new import_commander.Command("attest").description("Create a
 
 // src/commands/revoke.ts
 var import_commander2 = require("commander");
-var revokeCommand = new import_commander2.Command("revoke").description("Revoke an on-chain attestation").requiredOption("-s, --schema <uid>", "Schema UID of the attestation").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").option("--rpc-url <url>", "Custom RPC URL").option("--dry-run", "Estimate gas without sending the transaction").action(async (opts) => {
+var revokeCommand = new import_commander2.Command("revoke").description("Revoke an on-chain 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").option("--rpc-url <url>", "Custom RPC URL").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);
     const tx = await client.eas.revoke({
@@ -30871,9 +30981,9 @@ var schemaRegisterCommand = new import_commander4.Command("schema-register").des
 
 // src/commands/schema-get.ts
 var import_commander5 = require("commander");
-var schemaGetCommand = new import_commander5.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) => {
+var schemaGetCommand = new import_commander5.Command("schema-get").description("Get a schema by 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 });
     output({
@@ -30904,6 +31014,7 @@ var multiAttestCommand = new import_commander6.Command("multi-attest").descripti
     }
     const grouped = /* @__PURE__ */ new Map();
     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);
@@ -31053,6 +31164,24 @@ var QUERIES = {
       }
     }
   `,
+  getAttestationsByRecipient: `
+    query GetAttestationsByRecipient($recipient: String!, $take: Int, $skip: Int) {
+      attestations(
+        where: { recipient: { equals: $recipient } }
+        take: $take
+        skip: $skip
+        orderBy: [{ time: desc }]
+      ) {
+        id
+        attester
+        schemaId
+        time
+        revoked
+        decodedDataJson
+        isOffchain
+      }
+    }
+  `,
   getSchemata: `
     query GetSchemata($take: Int, $skip: Int) {
       schemata(
@@ -31087,9 +31216,9 @@ var QUERIES = {
 };
 
 // src/commands/offchain-attest.ts
-var offchainAttestCommand = new import_commander7.Command("offchain-attest").description("Create an off-chain attestation (signed but not submitted on-chain)").requiredOption("-s, --schema <uid>", "Schema UID").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).option("--expiration <timestamp>", "Expiration timestamp (0 for none)", "0").option("--revocable", "Whether the attestation is revocable", true).option("--no-revocable", "Make the attestation non-revocable").option("-c, --chain <name>", "Chain name", "ethereum").option("--rpc-url <url>", "Custom RPC URL").action(async (opts) => {
+var offchainAttestCommand = new import_commander7.Command("offchain-attest").description("Create an off-chain attestation (signed but not submitted on-chain)").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).option("--expiration <timestamp>", "Expiration timestamp (0 for none)", "0").option("--revocable", "Whether the attestation is revocable", true).option("--no-revocable", "Make the attestation non-revocable").option("-c, --chain <name>", "Chain name", "ethereum").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");
     }
@@ -31164,9 +31293,9 @@ var timestampCommand = new import_commander8.Command("timestamp").description("T
 
 // src/commands/query-schema.ts
 var import_commander9 = require("commander");
-var querySchemaCommand = new import_commander9.Command("query-schema").description("Query a schema from the EAS GraphQL API").requiredOption("-u, --uid <uid>", "Schema UID").option("-c, --chain <name>", "Chain name", "ethereum").action(async (opts) => {
+var querySchemaCommand = new import_commander9.Command("query-schema").description("Query a schema from the EAS GraphQL API").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 });
     if (!data.schema) {
       throw new Error(`Schema ${opts.uid} not found on ${opts.chain}`);
@@ -31201,13 +31330,14 @@ var queryAttestationCommand = new import_commander10.Command("query-attestation"
 
 // src/commands/query-attestations.ts
 var import_commander11 = require("commander");
-var queryAttestationsCommand = new import_commander11.Command("query-attestations").description("Query attestations by schema or attester from the EAS GraphQL API").option("-s, --schema <uid>", "Filter by schema UID").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").option("-c, --chain <name>", "Chain name", "ethereum").action(async (opts) => {
+var queryAttestationsCommand = new import_commander11.Command("query-attestations").description("Query attestations by schema or attester from the EAS GraphQL API").option("-s, --schema <uid>", "Filter by schema UID or popular schema name").option("-a, --attester <address>", "Filter by attester address").option("-r, --recipient <address>", "Filter by recipient address").option("-n, --limit <number>", "Max results to return", "10").option("--skip <number>", "Number of results to skip (for pagination)", "0").option("-c, --chain <name>", "Chain name", "ethereum").action(async (opts) => {
   try {
-    if (!opts.schema && !opts.attester) {
-      throw new Error("Provide at least one filter: --schema or --attester");
+    if (!opts.schema && !opts.attester && !opts.recipient) {
+      throw new Error("Provide at least one filter: --schema, --attester, or --recipient");
     }
-    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");
+    if (opts.recipient) validateAddress(opts.recipient, "recipient");
     const take = parseInt(opts.limit, 10);
     const skip = parseInt(opts.skip, 10);
     if (isNaN(take) || take < 1) throw new Error("--limit must be a positive integer");
@@ -31219,12 +31349,18 @@ var queryAttestationsCommand = new import_commander11.Command("query-attestation
         take,
         skip
       });
-    } else {
+    } else if (opts.attester) {
       data = await graphqlQuery(opts.chain, QUERIES.getAttestationsByAttester, {
         attester: opts.attester,
         take,
         skip
       });
+    } else {
+      data = await graphqlQuery(opts.chain, QUERIES.getAttestationsByRecipient, {
+        recipient: opts.recipient,
+        take,
+        skip
+      });
     }
     const attestations = data.attestations || [];
     for (const att of attestations) {
@@ -31281,6 +31417,7 @@ var multiRevokeCommand = new import_commander13.Command("multi-revoke").descript
     }
     const grouped = /* @__PURE__ */ new Map();
     for (const input of inputs) {
+      input.schema = resolveSchemaUID(input.schema);
       if (!grouped.has(input.schema)) {
         grouped.set(input.schema, { schema: input.schema, data: [] });
       }
@@ -31345,7 +31482,7 @@ var multiTimestampCommand = new import_commander14.Command("multi-timestamp").de
 // src/commands/set-key.ts
 var import_commander15 = require("commander");
 var import_ethers12 = require("ethers");
-var setKeyCommand = new import_commander15.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) => {
+var setKeyCommand = new import_commander15.Command("set-key").description("Store your private key in ~/.easctl for future use").argument("<key>", "Wallet private key (hex string, with or without 0x prefix)").action((key) => {
   const normalized = key.startsWith("0x") ? key : `0x${key}`;
   try {
     const wallet = new import_ethers12.ethers.Wallet(normalized);
@@ -31358,7 +31495,7 @@ var setKeyCommand = new import_commander15.Command("set-key").description("Store
 
 // src/commands/clear-key.ts
 var import_commander16 = require("commander");
-var clearKeyCommand = new import_commander16.Command("clear-key").description("Remove the stored private key from ~/.eas-cli").action(() => {
+var clearKeyCommand = new import_commander16.Command("clear-key").description("Remove the stored private key from ~/.easctl").action(() => {
   if (!getStoredPrivateKey()) {
     output({ success: true, data: { cleared: false, message: "No private key is currently stored" } });
     return;
@@ -31367,9 +31504,83 @@ var clearKeyCommand = new import_commander16.Command("clear-key").description("R
   output({ success: true, data: { cleared: true } });
 });
 
+// src/commands/popular-schemas.ts
+var import_commander17 = require("commander");
+var popularSchemasCommand = new import_commander17.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 categories2 = [...new Set(listPopularSchemas().map((s) => s.category))];
+        throw new Error(`Unknown category "${opts.category}". Available: ${categories2.join(", ")}`);
+      }
+      output({ success: true, data: { count: schemas.length, schemas } });
+      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(`
+=== ${category} ===
+`);
+      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}
+`);
+      }
+    }
+  } catch (err2) {
+    handleError(err2);
+  }
+});
+
+// src/commands/status.ts
+var import_commander18 = require("commander");
+var import_ethers13 = require("ethers");
+var statusCommand = new import_commander18.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" : void 0;
+  let address;
+  if (key) {
+    try {
+      const normalized = key.startsWith("0x") ? key : `0x${key}`;
+      address = new import_ethers13.ethers.Wallet(normalized).address;
+    } catch {
+    }
+  }
+  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(", ")
+    }
+  });
+});
+
 // src/index.ts
-var program = new import_commander17.Command();
-program.name("easctl").description("Ethereum Attestation Service CLI \u2014 create, revoke, and query attestations").version("0.1.2").option("--json", "Output results as JSON (useful for agents and scripting)").hook("preAction", (thisCommand, actionCommand) => {
+var program = new import_commander19.Command();
+program.name("easctl").description("Ethereum Attestation Service CLI \u2014 create, revoke, and query attestations").version("0.2.1").option("--json", "Output results as JSON (useful for agents and scripting)").hook("preAction", (thisCommand, actionCommand) => {
   if (thisCommand.opts().json || actionCommand.opts().json) {
     setJsonMode(true);
   }
@@ -31382,6 +31593,7 @@ program.addCommand(multiRevokeCommand);
 program.addCommand(getAttestationCommand);
 program.addCommand(schemaRegisterCommand);
 program.addCommand(schemaGetCommand);
+program.addCommand(popularSchemasCommand);
 program.addCommand(timestampCommand);
 program.addCommand(multiTimestampCommand);
 program.addCommand(querySchemaCommand);
@@ -31390,6 +31602,7 @@ program.addCommand(queryAttestationsCommand);
 program.addCommand(querySchemasCommand);
 program.addCommand(setKeyCommand);
 program.addCommand(clearKeyCommand);
+program.addCommand(statusCommand);
 program.command("chains").description("List supported chains and their EAS contract addresses").action(() => {
   const chains = listChains();
   output({ success: true, data: { chains } });