@elgora/cli 7.1.2 → 7.2.1

package/README.md

@@ -35,8 +35,9 @@ npx @elgora/cli --help
   one exact Solver and Submission pair.
 - `guardian:verdict` publishes a written Verdict and records the same Verdict
   on ElgoraHub.
-- `guardian:deliver-key` repairs delivery for one exact Solver and Submission
-  pair when ElgoraHub still permits it.
+- `guardian:deliver-key` wraps one Solver–Submission content key for delivery
+  so the funding Poster can retrieve the winning work; idempotent, and accepted
+  only for the pair ElgoraHub currently records or the finalized winner.
 - `claim` prepares or sends the winning Solver's reserved award or the
   Poster's queued refund, as selected from finalized ElgoraHub state.
 - `verification-record` is a plain, unauthenticated GET that fetches or lazily

package/dist/cli.js

@@ -196,7 +196,7 @@ function canonicalizeJson(value) {
 // ../../packages/core/src/submission-encryption.ts
 import { Aes256Gcm, CipherSuite, HkdfSha256 } from "@hpke/core";
 import { DhkemX25519HkdfSha256 } from "@hpke/dhkem-x25519";
-import { keccak256 as keccak2562, toBytes as toBytes2 } from "viem";
+import { concatBytes, keccak256 as keccak2562, toBytes as toBytes2 } from "viem";
 import { z as z3 } from "zod";
 
 // ../../packages/core/src/base64.ts
@@ -474,6 +474,78 @@ function buildWinningSolutionDeliveryInfo(contextCommitment) {
     `${WINNING_SOLUTION_DELIVERY_HPKE_INFO_PREFIX}:${contextCommitment}`
   );
 }
+var GUARDIAN_ROSTER_KEY_PROOF_INFO = "elgora/guardian-roster-key-proof/hpke-fixture/v0";
+var GUARDIAN_ROSTER_KEY_PROOF_MESSAGE_TYPE = "elgora_guardian_roster_key_proof_v0";
+var GUARDIAN_ROSTER_KEY_PROOF_FIXTURE_BYTES = 32;
+var guardianRosterKeyProofContextSchema = z3.strictObject({
+  chain_id: chainIdSchema,
+  hub_address: lowerAddressSchema,
+  proposed_account: lowerAddressSchema,
+  proposed_encryption_public_key: x25519PublicKeySchema
+});
+async function prepareGuardianRosterKeyProof(input) {
+  const context = guardianRosterKeyProofContextSchema.parse({
+    ...input.context,
+    hub_address: input.context.hub_address.toLowerCase(),
+    proposed_account: input.context.proposed_account.toLowerCase()
+  });
+  const fixture = (input.random_bytes ?? secureRandomBytes)(
+    GUARDIAN_ROSTER_KEY_PROOF_FIXTURE_BYTES
+  );
+  const suite = createHpkeSuite();
+  const recipientPublicKey = await suite.kem.deserializePublicKey(
+    base64UrlToBytes(context.proposed_encryption_public_key)
+  );
+  const sealed = await suite.seal(
+    { recipientPublicKey, info: toBytes2(GUARDIAN_ROSTER_KEY_PROOF_INFO) },
+    fixture
+  );
+  const ciphertext = bytesToBase64Url(toUint8Array(sealed.ct));
+  const message = canonicalizeJson({
+    type: GUARDIAN_ROSTER_KEY_PROOF_MESSAGE_TYPE,
+    chain_id: context.chain_id,
+    hub_address: context.hub_address,
+    proposed_account: context.proposed_account,
+    proposed_encryption_public_key: context.proposed_encryption_public_key,
+    ciphertext_sha256: await computeSha256Hex(toUint8Array(sealed.ct))
+  });
+  return {
+    challenge: {
+      context,
+      message,
+      enc: bytesToBase64Url(toUint8Array(sealed.enc)),
+      ciphertext
+    },
+    fixture
+  };
+}
+async function openGuardianRosterKeyProofFixture(input) {
+  const suite = createHpkeSuite();
+  const info = toBytes2(GUARDIAN_ROSTER_KEY_PROOF_INFO);
+  const enc = base64UrlToBytes(input.challenge.enc);
+  const ciphertext = base64UrlToBytes(input.challenge.ciphertext);
+  for (const privateKey of input.recipientPrivateKeys) {
+    try {
+      const recipientKey = await suite.kem.deserializePrivateKey(
+        base64UrlToBytes(x25519PrivateKeySchema.parse(privateKey))
+      );
+      const fixture = await suite.open({ recipientKey, enc, info }, ciphertext);
+      return toUint8Array(fixture);
+    } catch {
+    }
+  }
+  throw new Error(
+    "none of the supplied private keys could open this guardian roster key proof fixture"
+  );
+}
+function buildGuardianRosterKeyProofSignedPayload(message, fixture) {
+  if (fixture.length !== GUARDIAN_ROSTER_KEY_PROOF_FIXTURE_BYTES) {
+    throw new Error(
+      `guardian roster key proof fixture must be ${GUARDIAN_ROSTER_KEY_PROOF_FIXTURE_BYTES} bytes`
+    );
+  }
+  return concatBytes([toBytes2(message), fixture]);
+}
 async function sealPrivateArtifactEnvelope(input) {
   const context = privateArtifactContextSchema.parse(
     normalizeContext(input.context)
@@ -3424,6 +3496,11 @@ var ELGORA_HUB_BOUNTY_READ_ABI = [
   getAbiItem2({ abi: ELGORA_HUB_ABI, name: "activeSubmissionCommitment" }),
   ...ELGORA_HUB_ERRORS
 ];
+var ELGORA_HUB_OWNERSHIP_READ_ABI = [
+  getAbiItem2({ abi: ELGORA_HUB_ABI, name: "owner" }),
+  getAbiItem2({ abi: ELGORA_HUB_ABI, name: "pendingOwner" }),
+  ...ELGORA_HUB_ERRORS
+];
 var ELGORA_HUB_BOUNTY_CREATED_EVENT = getAbiItem2({
   abi: ELGORA_HUB_ABI,
   name: "BountyCreated"
@@ -3453,6 +3530,30 @@ var ELGORA_HUB_CLAIM_ABI = [
   getAbiItem2({ abi: ELGORA_HUB_ABI, name: "claim" }),
   ...ELGORA_HUB_ERRORS
 ];
+var ELGORA_HUB_ADD_GUARDIAN_ABI = [
+  getAbiItem2({ abi: ELGORA_HUB_ABI, name: "guardianRosterAdmin" }),
+  getAbiItem2({ abi: ELGORA_HUB_ABI, name: "getGuardianRoster" }),
+  getAbiItem2({ abi: ELGORA_HUB_ABI, name: "addGuardian" }),
+  ...ELGORA_HUB_ERRORS
+];
+function encodeAddGuardianTransaction(input) {
+  return {
+    chain_id: input.chainId,
+    to: input.hubAddress,
+    value: "0",
+    data: encodeFunctionData({
+      abi: ELGORA_HUB_ADD_GUARDIAN_ABI,
+      functionName: "addGuardian",
+      args: [input.name, input.account, input.encryptionPublicKey]
+    }),
+    function_name: "add_guardian",
+    args: {
+      name: input.name,
+      account: input.account,
+      encryption_public_key: input.encryptionPublicKey
+    }
+  };
+}
 function encodeSubmitTransaction(input) {
   return {
     chain_id: input.chainId,
@@ -3496,6 +3597,7 @@ var artifactUploadUrlRequestSchema = z4.object({
 }).strict();
 
 // ../../packages/core/src/api/config.ts
+import { createHash } from "crypto";
 import { z as z5 } from "zod";
 function withDeploymentEnvDefaults(env) {
   const merged = { ...env };
@@ -3559,7 +3661,6 @@ var envShape = {
   ELGORA_ARTIFACT_STORAGE_BUCKET: z5.string().min(1, "ELGORA_ARTIFACT_STORAGE_BUCKET is required"),
   ELGORA_ARTIFACT_STORAGE_ACCESS_KEY_ID: z5.string().min(1, "ELGORA_ARTIFACT_STORAGE_ACCESS_KEY_ID is required"),
   ELGORA_ARTIFACT_STORAGE_SECRET_ACCESS_KEY: z5.string().min(1, "ELGORA_ARTIFACT_STORAGE_SECRET_ACCESS_KEY is required"),
-  ELGORA_DELIVERY_KEY_ID: z5.string().min(1, "ELGORA_DELIVERY_KEY_ID is required").default("delivery_v0"),
   ELGORA_DELIVERY_PUBLIC_KEY: z5.string().min(1, "ELGORA_DELIVERY_PUBLIC_KEY is required"),
   ELGORA_DELIVERY_PRIVATE_KEY: z5.string().min(1, "ELGORA_DELIVERY_PRIVATE_KEY is required")
 };
@@ -3588,23 +3689,25 @@ var ELGORA_HUB_FEE_POLICY_ABI = [
 // ../../packages/core/src/api/orchestrator-readiness.ts
 import { z as z6 } from "zod";
 var MAX_ORCHESTRATOR_ISSUES = 20;
-var boundedText = (maxLength) => z6.string().trim().min(1).transform((value) => value.slice(0, maxLength));
+var boundedText = (maxLength) => z6.string().trim().min(1).max(maxLength);
 var readinessIssueSchema = z6.object({
   path: boundedText(120),
   message: boundedText(500)
 }).strict();
 var readinessResponseSchema = z6.object({
   judgeable: z6.boolean(),
-  issues: z6.array(readinessIssueSchema).transform((issues) => issues.slice(0, MAX_ORCHESTRATOR_ISSUES))
+  issues: z6.array(readinessIssueSchema).max(MAX_ORCHESTRATOR_ISSUES)
 }).strict();
-var anthropicMessageSchema = z6.object({
-  content: z6.array(
+var providerMessageSchema = z6.object({
+  id: z6.string().optional(),
+  choices: z6.array(
     z6.object({
-      type: z6.string(),
-      text: z6.string().optional()
+      message: z6.object({
+        content: z6.string().nullable().optional()
+      }).passthrough(),
+      finish_reason: z6.string().nullable().optional()
     }).passthrough()
-  ),
-  stop_reason: z6.string().nullable().optional()
+  ).min(1)
 }).passthrough();
 
 // ../../packages/core/src/api/solver-submission-responses.ts
@@ -4862,6 +4965,7 @@ var SUBMISSION_FIELDS = `
   recordedAt
   recordedBlockNumber
   recordedTxHash
+  submissionCallCount
 `;
 var VERDICT_FIELDS = `
   guardian
@@ -5343,7 +5447,11 @@ function mapSubmissionFields(row) {
       record.recordedBlockNumber,
       "recordedBlockNumber"
     ),
-    recordedTxHash: asHex(record.recordedTxHash, "recordedTxHash")
+    recordedTxHash: asHex(record.recordedTxHash, "recordedTxHash"),
+    submissionCallCount: asNumber(
+      record.submissionCallCount,
+      "submissionCallCount"
+    )
   };
 }
 function mapGuardianRosterMember(row) {
@@ -5548,7 +5656,10 @@ async function main4(env = process.env, argv = process.argv.slice(2)) {
       },
       submissions: submissions.map((submission) => ({
         solver: submission.solver,
-        submission_commitment: submission.submissionCommitment
+        submission_commitment: submission.submissionCommitment,
+        submitted_at: submission.recordedAt,
+        submitted_at_block: submission.recordedBlockNumber,
+        submission_call_count: submission.submissionCallCount
       }))
     });
   }
@@ -5596,10 +5707,88 @@ function requiredUrl(env, name) {
   }
 }
 
-// src/guardian-verdict.ts
+// src/guardian-prove-roster-key.ts
 import { readFile } from "fs/promises";
-import { zeroAddress as zeroAddress4 } from "viem";
+import { text as readStdinText } from "stream/consumers";
 import { privateKeyToAccount as privateKeyToAccount5 } from "viem/accounts";
+async function main5(env = process.env, argv = process.argv.slice(2)) {
+  const [path5] = argv;
+  if (!path5) {
+    throw new Error(
+      "Usage: elgora-cli guardian:prove-roster-key <challenge_json_path|->"
+    );
+  }
+  const challenge = parseChallenge(
+    path5 === "-" ? await readStdinText(process.stdin) : await readFile(path5, "utf8")
+  );
+  const envWithDefaults = withDeploymentDefaults(env);
+  const { chainId, hubAddress } = loadPublicDeploymentConfig(envWithDefaults);
+  if (challenge.context.chain_id !== chainId || challenge.context.hub_address.toLowerCase() !== hubAddress.toLowerCase()) {
+    throw new Error(
+      `Challenge names chain ${challenge.context.chain_id} / Hub ${challenge.context.hub_address}, not this deployment's chain ${chainId} / Hub ${hubAddress}`
+    );
+  }
+  const guardianAccountPrivateKey = envWithDefaults.ELGORA_GUARDIAN_ACCOUNT_PRIVATE_KEY?.trim().toLowerCase();
+  if (!guardianAccountPrivateKey || !isHexBytes32(guardianAccountPrivateKey)) {
+    throw new Error(
+      "ELGORA_GUARDIAN_ACCOUNT_PRIVATE_KEY must be a 32-byte hex private key"
+    );
+  }
+  const account = privateKeyToAccount5(guardianAccountPrivateKey);
+  if (account.address.toLowerCase() !== challenge.context.proposed_account) {
+    throw new Error(
+      `ELGORA_GUARDIAN_ACCOUNT_PRIVATE_KEY resolves to ${account.address.toLowerCase()}, but this challenge names proposed_account ${challenge.context.proposed_account}`
+    );
+  }
+  const guardianPrivateKeys = readGuardianPrivateKeys(env).map(
+    (key) => key.private_key
+  );
+  const fixture = await openGuardianRosterKeyProofFixture({
+    challenge,
+    recipientPrivateKeys: guardianPrivateKeys
+  });
+  const signedPayload = buildGuardianRosterKeyProofSignedPayload(
+    challenge.message,
+    fixture
+  );
+  const signature = await account.signMessage({
+    message: { raw: signedPayload }
+  });
+  console.log(
+    JSON.stringify({
+      event: "guardian_prove_roster_key.signed",
+      guardian_account: account.address.toLowerCase(),
+      proposed_encryption_public_key: challenge.context.proposed_encryption_public_key,
+      signature
+    })
+  );
+}
+function parseChallenge(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new Error("Challenge input must be valid JSON", { cause: error });
+  }
+  const challenge = parsed && typeof parsed === "object" && "send_to_guardian" in parsed ? parsed.send_to_guardian : parsed;
+  if (!challenge || typeof challenge !== "object" || typeof challenge.message !== "string" || typeof challenge.enc !== "string" || typeof challenge.ciphertext !== "string") {
+    throw new Error(
+      "Challenge JSON must contain context, message, enc, and ciphertext (the object roster:prepare-guardian-proof printed as send_to_guardian)"
+    );
+  }
+  const context = challenge.context;
+  if (!context || typeof context !== "object" || typeof context.chain_id !== "number" || typeof context.hub_address !== "string" || typeof context.proposed_account !== "string" || typeof context.proposed_encryption_public_key !== "string") {
+    throw new Error(
+      "Challenge context must contain chain_id, hub_address, proposed_account, and proposed_encryption_public_key"
+    );
+  }
+  return challenge;
+}
+
+// src/guardian-verdict.ts
+import { readFile as readFile2 } from "fs/promises";
+import { zeroAddress as zeroAddress4 } from "viem";
+import { privateKeyToAccount as privateKeyToAccount6 } from "viem/accounts";
 var OUTCOME = {
   no_valid_submission: 0,
   awarded: 1
@@ -5634,7 +5823,7 @@ function parseVerdictArgs(argv) {
   }
   throw usageError();
 }
-async function main5(env = process.env, argv = process.argv.slice(2)) {
+async function main6(env = process.env, argv = process.argv.slice(2)) {
   const { apiBaseUrl: apiBaseUrlOverride, argv: positionalArgs } = extractApiBaseUrlFlag(argv);
   const args = parseVerdictArgs(positionalArgs);
   const envWithDefaults = withDeploymentDefaults(env);
@@ -5650,11 +5839,11 @@ async function main5(env = process.env, argv = process.argv.slice(2)) {
       "ELGORA_GUARDIAN_ACCOUNT_PRIVATE_KEY must be a 32-byte hex private key"
     );
   }
-  const account = privateKeyToAccount5(guardianPrivateKey.toLowerCase());
+  const account = privateKeyToAccount6(guardianPrivateKey.toLowerCase());
   const publicClient = createChainPublicClient(config.chainId, rpcUrl);
   const walletClient = createChainWalletClient(config.chainId, rpcUrl, account);
   await assertHubDeployment(publicClient, config.chainId, config.hubAddress);
-  const verdictBody = await readFile(args.verdictBodyPath, "utf8");
+  const verdictBody = await readFile2(args.verdictBodyPath, "utf8");
   const markdown = args.outcome === "awarded" ? buildWrittenVerdictMarkdown({
     config,
     bountyId: args.bountyId,
@@ -5921,9 +6110,9 @@ function resolveChainId(selector) {
 // src/poster-open-winning-submission.ts
 import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
 import path2 from "path";
-import { privateKeyToAccount as privateKeyToAccount6 } from "viem/accounts";
+import { privateKeyToAccount as privateKeyToAccount7 } from "viem/accounts";
 var DEFAULT_OUTPUT_ROOT2 = "./winning-submission";
-async function main6(env = process.env, argv = process.argv.slice(2)) {
+async function main7(env = process.env, argv = process.argv.slice(2)) {
   const { apiBaseUrl: apiBaseUrlOverride, argv: remainingArgv } = extractApiBaseUrlFlag(argv);
   const args = readPosterOpenWinningSubmissionArgs(remainingArgv);
   const envWithDefaults = withDeploymentDefaults(env);
@@ -5938,7 +6127,7 @@ async function main6(env = process.env, argv = process.argv.slice(2)) {
       "ELGORA_POSTER_PRIVATE_KEY must be a 32-byte hex private key"
     );
   }
-  const account = privateKeyToAccount6(posterPrivateKey.toLowerCase());
+  const account = privateKeyToAccount7(posterPrivateKey.toLowerCase());
   const publicClient = createChainPublicClient(config.chainId, rpcUrl);
   await assertHubDeployment(publicClient, config.chainId, config.hubAddress);
   const ephemeral = await generateX25519KeyPair();
@@ -6062,26 +6251,26 @@ function required3(env, name) {
 }
 
 // src/publish-fund.ts
-import { readFile as readFile2 } from "fs/promises";
-import { text as readStdinText } from "stream/consumers";
+import { readFile as readFile3 } from "fs/promises";
+import { text as readStdinText2 } from "stream/consumers";
 import {
   parseAbi,
   parseEventLogs
 } from "viem";
-import { privateKeyToAccount as privateKeyToAccount7 } from "viem/accounts";
+import { privateKeyToAccount as privateKeyToAccount8 } from "viem/accounts";
 var PUBLISH_FUND_USAGE = "Usage: elgora-cli poster:publish-fund <bounty_challenge_md_path>\n   or: elgora-cli poster:publish-fund -";
 var usdcAbi = parseAbi([
   "function approve(address spender,uint256 value) returns (bool)",
   "function balanceOf(address account) view returns (uint256)"
 ]);
-async function main7(env = process.env, argv = process.argv.slice(2)) {
+async function main8(env = process.env, argv = process.argv.slice(2)) {
   const { apiBaseUrl: apiBaseUrlOverride, argv: remainingArgv } = extractApiBaseUrlFlag(argv);
   const config = loadPublishFundConfig(
     withDeploymentDefaults(env),
     apiBaseUrlOverride
   );
   const bountyChallengeMarkdown = await readBountyChallengeMarkdown(remainingArgv);
-  const account = privateKeyToAccount7(config.posterPrivateKey);
+  const account = privateKeyToAccount8(config.posterPrivateKey);
   const publicClient = createChainPublicClient(config.chainId, config.rpcUrl);
   const walletClient = createChainWalletClient(
     config.chainId,
@@ -6238,9 +6427,9 @@ async function readBountyChallengeMarkdown(argv) {
     throw new Error(PUBLISH_FUND_USAGE);
   }
   if (path5 === "-") {
-    return readStdinText(process.stdin);
+    return readStdinText2(process.stdin);
   }
-  return readFile2(path5, "utf8");
+  return readFile3(path5, "utf8");
 }
 function loadPublishFundConfig(env, apiBaseUrlOverride) {
   const clientConfig = loadClientDeploymentConfig(env, apiBaseUrlOverride);
@@ -6268,11 +6457,311 @@ function loadPublishFundConfig(env, apiBaseUrlOverride) {
   };
 }
 
+// src/roster-add-guardian.ts
+import { isAddress as isAddress4 } from "viem";
+import { privateKeyToAccount as privateKeyToAccount9 } from "viem/accounts";
+var ROSTER_ADMIN_ADDRESS_FLAG = "--roster-admin-address";
+var ENCRYPTION_PUBLIC_KEY_RE = /^[A-Za-z0-9_-]{43}$/;
+async function main9(env = process.env, argv = process.argv.slice(2)) {
+  const args = parseRosterAddGuardianArgs(argv);
+  const config = loadRosterAddGuardianConfig(env, args.rosterAdminAddress);
+  const account = config.rosterAdminPrivateKey ? privateKeyToAccount9(config.rosterAdminPrivateKey) : null;
+  const rosterAdmin = account?.address ?? args.rosterAdminAddress;
+  if (!rosterAdmin) throw new Error("Roster admin address is required");
+  const normalizedRosterAdmin = rosterAdmin.toLowerCase();
+  const publicClient = createChainPublicClient(config.chainId, config.rpcUrl);
+  await assertHubDeployment(publicClient, config.chainId, config.hubAddress);
+  const liveRosterAdmin = await publicClient.readContract({
+    address: config.hubAddress,
+    abi: ELGORA_HUB_ADD_GUARDIAN_ABI,
+    functionName: "guardianRosterAdmin"
+  });
+  if (liveRosterAdmin.toLowerCase() !== normalizedRosterAdmin) {
+    throw new Error(
+      `${normalizedRosterAdmin} is not the live guardianRosterAdmin (${liveRosterAdmin.toLowerCase()})`
+    );
+  }
+  const roster = await publicClient.readContract({
+    address: config.hubAddress,
+    abi: ELGORA_HUB_ADD_GUARDIAN_ABI,
+    functionName: "getGuardianRoster"
+  });
+  if (roster.some(
+    (guardian) => guardian.account.toLowerCase() === args.guardianAccount
+  )) {
+    throw new Error(
+      `${args.guardianAccount} is already on the Guardian roster`
+    );
+  }
+  const contractArgs = [
+    args.name,
+    args.guardianAccount,
+    args.encryptionPublicKey
+  ];
+  if (!account) {
+    await publicClient.simulateContract({
+      account: normalizedRosterAdmin,
+      address: config.hubAddress,
+      abi: ELGORA_HUB_ADD_GUARDIAN_ABI,
+      functionName: "addGuardian",
+      args: contractArgs
+    });
+    const prepared = encodeAddGuardianTransaction({
+      chainId: config.chainId,
+      hubAddress: config.hubAddress,
+      name: args.name,
+      account: args.guardianAccount,
+      encryptionPublicKey: args.encryptionPublicKey
+    });
+    console.log(
+      JSON.stringify({
+        event: "roster_add_guardian.transaction_prepared",
+        ...prepared
+      })
+    );
+    return;
+  }
+  const walletClient = createChainWalletClient(
+    config.chainId,
+    config.rpcUrl,
+    account
+  );
+  const ethBalance = await publicClient.getBalance({
+    address: account.address
+  });
+  if (ethBalance === 0n) {
+    throw new Error(
+      `Roster admin has no gas token balance: ${account.address}`
+    );
+  }
+  await publicClient.simulateContract({
+    account: account.address,
+    address: config.hubAddress,
+    abi: ELGORA_HUB_ADD_GUARDIAN_ABI,
+    functionName: "addGuardian",
+    args: contractArgs
+  });
+  const transactionHash = await walletClient.writeContract({
+    address: config.hubAddress,
+    abi: ELGORA_HUB_ADD_GUARDIAN_ABI,
+    functionName: "addGuardian",
+    args: contractArgs
+  });
+  const receipt = await publicClient.waitForTransactionReceipt({
+    hash: transactionHash
+  });
+  if (receipt.status !== "success") {
+    throw new Error(`addGuardian transaction reverted: ${transactionHash}`);
+  }
+  console.log(
+    JSON.stringify({
+      event: "roster_add_guardian.recorded",
+      tx_hash: transactionHash,
+      block_number: receipt.blockNumber.toString(),
+      name: args.name,
+      account: args.guardianAccount,
+      encryption_public_key: args.encryptionPublicKey
+    })
+  );
+}
+function parseRosterAddGuardianArgs(argv) {
+  const usesRosterAdminAddress = argv[0] === ROSTER_ADMIN_ADDRESS_FLAG;
+  const rosterAdminAddress = usesRosterAdminAddress ? argv[1]?.trim() : void 0;
+  if (usesRosterAdminAddress && (!rosterAdminAddress || !isAddress4(rosterAdminAddress))) {
+    throw usageError2();
+  }
+  const positional = usesRosterAdminAddress ? argv.slice(2) : argv;
+  if (positional.length !== 3) throw usageError2();
+  const name = positional[0]?.trim();
+  const guardianAccount = positional[1]?.trim();
+  const encryptionPublicKey = positional[2]?.trim();
+  if (!name) throw usageError2();
+  if (!guardianAccount || !isAddress4(guardianAccount)) {
+    throw new Error("guardian_account must be a valid EVM address");
+  }
+  if (!encryptionPublicKey || !ENCRYPTION_PUBLIC_KEY_RE.test(encryptionPublicKey)) {
+    throw new Error(
+      "encryption_public_key must be an unpadded base64url X25519 public key (43 characters)"
+    );
+  }
+  return {
+    name,
+    guardianAccount: guardianAccount.toLowerCase(),
+    encryptionPublicKey,
+    ...rosterAdminAddress ? { rosterAdminAddress: rosterAdminAddress.toLowerCase() } : {}
+  };
+}
+function loadRosterAddGuardianConfig(env, rosterAdminAddress) {
+  const envWithDefaults = withDeploymentDefaults(env);
+  const publicDeploymentConfig = loadPublicDeploymentConfig(envWithDefaults);
+  const rpcUrl = envWithDefaults.ELGORA_RPC_URL?.trim();
+  if (!rpcUrl) {
+    throw new Error("ELGORA_RPC_URL is required");
+  }
+  const rosterAdminPrivateKey = envWithDefaults.ELGORA_GUARDIAN_ROSTER_ADMIN_PRIVATE_KEY?.trim();
+  if (!rosterAdminAddress && (!rosterAdminPrivateKey || !isHexBytes32(rosterAdminPrivateKey))) {
+    throw new Error(
+      "ELGORA_GUARDIAN_ROSTER_ADMIN_PRIVATE_KEY must be a 32-byte hex private key unless --roster-admin-address is provided"
+    );
+  }
+  return {
+    ...publicDeploymentConfig,
+    rpcUrl,
+    rosterAdminPrivateKey: rosterAdminAddress ? null : rosterAdminPrivateKey?.toLowerCase()
+  };
+}
+function usageError2() {
+  return new Error(
+    "Usage: elgora-cli roster:add-guardian [--roster-admin-address <address>] <name> <guardian_account> <encryption_public_key>"
+  );
+}
+
+// src/roster-prepare-guardian-proof.ts
+import { isAddress as isAddress5 } from "viem";
+var ENCRYPTION_PUBLIC_KEY_RE2 = /^[A-Za-z0-9_-]{43}$/;
+async function main10(env = process.env, argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  const envWithDefaults = withDeploymentDefaults(env);
+  const { chainId, hubAddress } = loadPublicDeploymentConfig(envWithDefaults);
+  const { challenge, fixture } = await prepareGuardianRosterKeyProof({
+    context: {
+      chain_id: chainId,
+      hub_address: hubAddress,
+      proposed_account: args.guardianAccount,
+      proposed_encryption_public_key: args.encryptionPublicKey
+    }
+  });
+  console.log(
+    JSON.stringify({
+      event: "roster_guardian_proof.challenge_prepared",
+      send_to_guardian: challenge,
+      keep_local_do_not_share: {
+        fixture: bytesToBase64Url(fixture),
+        note: "Needed for roster:verify-guardian-proof once the Guardian replies. Never send this to the Guardian \u2014 sending it defeats the proof."
+      }
+    })
+  );
+}
+function parseArgs(argv) {
+  if (argv.length !== 2) throw usageError3();
+  const guardianAccount = argv[0]?.trim();
+  const encryptionPublicKey = argv[1]?.trim();
+  if (!guardianAccount || !isAddress5(guardianAccount)) {
+    throw new Error("guardian_account must be a valid EVM address");
+  }
+  if (!encryptionPublicKey || !ENCRYPTION_PUBLIC_KEY_RE2.test(encryptionPublicKey)) {
+    throw new Error(
+      "encryption_public_key must be an unpadded base64url X25519 public key (43 characters)"
+    );
+  }
+  return {
+    guardianAccount: guardianAccount.toLowerCase(),
+    encryptionPublicKey
+  };
+}
+function usageError3() {
+  return new Error(
+    "Usage: elgora-cli roster:prepare-guardian-proof <guardian_account> <encryption_public_key>"
+  );
+}
+
+// src/roster-verify-guardian-proof.ts
+import { readFile as readFile4 } from "fs/promises";
+import { isAddress as isAddress6, isHex as isHex5, recoverMessageAddress } from "viem";
+async function main11(_env = process.env, argv = process.argv.slice(2)) {
+  const [preparedPath, responsePath] = argv;
+  if (!preparedPath || !responsePath) {
+    throw new Error(
+      "Usage: elgora-cli roster:verify-guardian-proof <prepared_json_path> <response_json_path>"
+    );
+  }
+  const prepared = parsePrepared(await readFile4(preparedPath, "utf8"));
+  const response = parseResponse(await readFile4(responsePath, "utf8"));
+  const fixture = base64UrlToBytes(prepared.fixture);
+  const signedPayload = buildGuardianRosterKeyProofSignedPayload(
+    prepared.message,
+    fixture
+  );
+  const recoveredAddress = (await recoverMessageAddress({
+    message: { raw: signedPayload },
+    signature: response.signature
+  })).toLowerCase();
+  const proposedAccount = prepared.proposedAccount;
+  const succeeded = recoveredAddress === proposedAccount && response.guardianAccount === proposedAccount;
+  console.log(
+    JSON.stringify({
+      event: succeeded ? "roster_guardian_proof.verified" : "roster_guardian_proof.failed",
+      proposed_account: proposedAccount,
+      recovered_signer: recoveredAddress,
+      response_guardian_account: response.guardianAccount,
+      succeeded
+    })
+  );
+  if (!succeeded) {
+    throw new Error(
+      `Guardian roster key proof FAILED for ${proposedAccount}: recovered signer ${recoveredAddress} does not match`
+    );
+  }
+}
+function parsePrepared(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new Error("Prepared proof JSON must be valid JSON", {
+      cause: error
+    });
+  }
+  const sendToGuardian = get(parsed, "send_to_guardian");
+  const message = get(sendToGuardian, "message");
+  const context = get(sendToGuardian, "context");
+  const proposedAccount = get(context, "proposed_account");
+  const keepLocal = get(parsed, "keep_local_do_not_share");
+  const fixture = get(keepLocal, "fixture");
+  if (typeof message !== "string" || typeof proposedAccount !== "string" || !isAddress6(proposedAccount) || typeof fixture !== "string") {
+    throw new Error(
+      "Prepared proof JSON must be the unmodified stdout of roster:prepare-guardian-proof"
+    );
+  }
+  return {
+    message,
+    fixture,
+    proposedAccount: proposedAccount.toLowerCase()
+  };
+}
+function parseResponse(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new Error("Guardian response JSON must be valid JSON", {
+      cause: error
+    });
+  }
+  const guardianAccount = get(parsed, "guardian_account");
+  const signature = get(parsed, "signature");
+  if (typeof guardianAccount !== "string" || !isAddress6(guardianAccount) || typeof signature !== "string" || !isHex5(signature) || signature.length !== 132) {
+    throw new Error(
+      "Guardian response JSON must be the unmodified stdout of guardian:prove-roster-key"
+    );
+  }
+  return {
+    guardianAccount: guardianAccount.toLowerCase(),
+    signature
+  };
+}
+function get(value, key) {
+  if (!value || typeof value !== "object" || !(key in value)) {
+    return void 0;
+  }
+  return value[key];
+}
+
 // src/spec-commitment.ts
-import { readFile as readFile3 } from "fs/promises";
-import { text as readStdinText2 } from "stream/consumers";
+import { readFile as readFile5 } from "fs/promises";
+import { text as readStdinText3 } from "stream/consumers";
 var SPEC_COMMITMENT_USAGE = "Usage: elgora-cli spec-commitment <bounty_challenge_md_path>\n   or: elgora-cli spec-commitment -";
-async function main8(_env = process.env, argv = process.argv.slice(2)) {
+async function main12(_env = process.env, argv = process.argv.slice(2)) {
   const markdown = await readBountyChallengeMarkdown2(argv);
   const specCommitment = deriveBountyChallengeContentCommitment(markdown);
   console.log(
@@ -6289,25 +6778,25 @@ async function readBountyChallengeMarkdown2(argv) {
     throw new Error(SPEC_COMMITMENT_USAGE);
   }
   if (path5 === "-") {
-    return readStdinText2(process.stdin);
+    return readStdinText3(process.stdin);
   }
-  return readFile3(path5, "utf8");
+  return readFile5(path5, "utf8");
 }
 
 // src/submit.ts
-import { readdir, readFile as readFile4, stat } from "fs/promises";
+import { readdir, readFile as readFile6, stat } from "fs/promises";
 import path3 from "path";
 import { createInterface } from "readline";
-import { isAddress as isAddress4 } from "viem";
-import { privateKeyToAccount as privateKeyToAccount8 } from "viem/accounts";
+import { isAddress as isAddress7 } from "viem";
+import { privateKeyToAccount as privateKeyToAccount10 } from "viem/accounts";
 
 // src/external-api-approval-signer.ts
-import { isHex as isHex5 } from "viem";
+import { isHex as isHex6 } from "viem";
 function createExternalApiApprovalSigner(input) {
   return async (typedData) => {
     input.writePrompt(input.renderPrompt(typedData));
     const signature = (await input.readSignature())?.trim();
-    if (!signature || signature === "0x" || !isHex5(signature)) {
+    if (!signature || signature === "0x" || !isHex6(signature)) {
       throw new Error(
         "External signer must return one non-empty 0x-prefixed hex signature line on stdin"
       );
@@ -6349,13 +6838,13 @@ var MEDIA_TYPE_BY_EXTENSION = {
   diff: "text/x-diff"
 };
 var DEFAULT_MEDIA_TYPE = "application/octet-stream";
-async function main9(env = process.env, argv = process.argv.slice(2)) {
+async function main13(env = process.env, argv = process.argv.slice(2)) {
   const { solverAddress, argv: argvWithoutSolverAddress } = extractSolverAddressFlag(argv);
   const { apiBaseUrl: apiBaseUrlOverride, argv: remainingArgv } = extractApiBaseUrlFlag(argvWithoutSolverAddress);
   const config = loadSubmitConfig(env, apiBaseUrlOverride, solverAddress);
   const args = readSubmitArgs(remainingArgv);
   const bountyIdText = args.bountyId.toString();
-  const account = config.solverPrivateKey ? privateKeyToAccount8(config.solverPrivateKey) : null;
+  const account = config.solverPrivateKey ? privateKeyToAccount10(config.solverPrivateKey) : null;
   const solverAddressFromConfig = account?.address ?? config.solverAddress;
   if (!solverAddressFromConfig) throw new Error("Solver address is required");
   const solver = solverAddressFromConfig.toLowerCase();
@@ -6694,7 +7183,7 @@ function extractSolverAddressFlag(argv) {
     }
     if (arg !== void 0) remaining.push(arg);
   }
-  if (solverAddress !== void 0 && !isAddress4(solverAddress)) {
+  if (solverAddress !== void 0 && !isAddress7(solverAddress)) {
     throw new Error("--solver-address must be a valid EVM address");
   }
   return {
@@ -6724,7 +7213,7 @@ async function readArtifactDirectory(artifactDir) {
   }
   return Promise.all(
     entries.map(async (entry) => {
-      const bytes = await readFile4(path3.join(artifactDir, entry.name));
+      const bytes = await readFile6(path3.join(artifactDir, entry.name));
       return {
         name: entry.name,
         media_type: guessMediaType(entry.name),
@@ -6834,7 +7323,7 @@ function readTimelockRevealDelaySeconds(env) {
 
 // src/verification-record.ts
 var VERIFICATION_RECORD_USAGE = "Usage: elgora-cli verification-record <bounty_id>";
-async function main10(env = process.env, argv = process.argv.slice(2)) {
+async function main14(env = process.env, argv = process.argv.slice(2)) {
   const { apiBaseUrl: apiBaseUrlOverride, argv: remainingArgv } = extractApiBaseUrlFlag(argv);
   const args = readVerificationRecordArgs(remainingArgv);
   const envWithDefaults = withDeploymentDefaults(env);
@@ -6891,11 +7380,11 @@ function readVerificationRecordArgs(argv) {
   const [bountyIdText] = argv;
   const bountyId = bountyIdText?.trim();
   if (argv.length !== 1 || !bountyId || !isBountyId(bountyId)) {
-    throw usageError2();
+    throw usageError4();
   }
   return { bountyId: BigInt(bountyId) };
 }
-function usageError2() {
+function usageError4() {
   return new Error(VERIFICATION_RECORD_USAGE);
 }
 
@@ -6912,14 +7401,18 @@ process.stderr.write(
 var COMMANDS = {
   "guardian:judgeable": main4,
   "guardian:open": main2,
-  "guardian:verdict": main5,
+  "guardian:prove-roster-key": main5,
+  "guardian:verdict": main6,
   "guardian:deliver-key": main3,
-  "poster:open-winning-submission": main6,
-  "poster:publish-fund": main7,
-  "solver:submit": main9,
+  "poster:open-winning-submission": main7,
+  "poster:publish-fund": main8,
+  "roster:add-guardian": main9,
+  "roster:prepare-guardian-proof": main10,
+  "roster:verify-guardian-proof": main11,
+  "solver:submit": main13,
   claim: main,
-  "spec-commitment": main8,
-  "verification-record": main10
+  "spec-commitment": main12,
+  "verification-record": main14
 };
 var COMMAND_HELP = {
   "guardian:judgeable": {
@@ -6949,6 +7442,16 @@ var COMMAND_HELP = {
     ],
     apiBaseUrlFlag: true
   },
+  "guardian:prove-roster-key": {
+    usage: "elgora-cli guardian:prove-roster-key <challenge_json_path|->",
+    title: "Prove control of a proposed roster account and HPKE key.",
+    description: "Run asynchronously, independent of anything on chain: open the sealed\n  fixture from roster:prepare-guardian-proof's send_to_guardian output\n  (pass the whole prepared JSON, or just its send_to_guardian object;\n  '-' reads stdin), then EIP-191 personal_sign proof that this account\n  recovered it. Refuses to sign if the challenge names a different\n  chain, Hub, or proposed_account than this key resolves to. Send the\n  printed response back to the roster admin for\n  roster:verify-guardian-proof. This is advisory only \u2014 it is never\n  submitted to ElgoraHub and enforces nothing there.",
+    required: [
+      "ELGORA_GUARDIAN_ACCOUNT_PRIVATE_KEY",
+      "ELGORA_GUARDIAN_PRIVATE_KEYS_JSON"
+    ],
+    defaulted: ["ELGORA_CHAIN_ID", "ELGORA_HUB_ADDRESS"]
+  },
   "guardian:verdict": {
     usage: "elgora-cli guardian:verdict <bounty_id> awarded <solver> <submission_commitment> <verdict_body_path>\n   or: elgora-cli guardian:verdict <bounty_id> no_valid_submission <verdict_body_path>",
     title: "Publish and record this Guardian's Verdict.",
@@ -6964,8 +7467,8 @@ var COMMAND_HELP = {
   },
   "guardian:deliver-key": {
     usage: "elgora-cli guardian:deliver-key <bounty_id> <solver> <submission_commitment>",
-    title: "Repair delivery for one exact Submission.",
-    description: "Ask the API to wrap the key for the explicit Solver and Submission.\n  ElgoraHub decides whether the pair is still active or is the finalized\n  winner; written Verdicts and local state do not authorize delivery.",
+    title: "Deliver the finalized winner's content key for Poster retrieval.",
+    description: "Required after a bounty finalizes `awarded`: wrap the winning\n  Submission's key so the funding Poster can retrieve the work. Read the\n  winning Solver and Submission from ElgoraHub's finalized state (the\n  subgraph), not from a local Verdict, and pass exactly that pair. The\n  API rechecks against ElgoraHub and accepts only the current active or\n  finalized winner; written Verdicts and local state authorize nothing.\n  Idempotent \u2014 safe to re-run and safe if another Guardian already did it.",
     required: [
       "ELGORA_GUARDIAN_ACCOUNT_PRIVATE_KEY",
       "ELGORA_GUARDIAN_PRIVATE_KEYS_JSON"
@@ -7005,6 +7508,26 @@ var COMMAND_HELP = {
     ],
     apiBaseUrlFlag: true
   },
+  "roster:add-guardian": {
+    usage: "elgora-cli roster:add-guardian [--roster-admin-address <address>]\n   <name> <guardian_account> <encryption_public_key>",
+    title: "Append one Guardian to the live roster.",
+    description: "Call ElgoraHub's guardianRosterAdmin-only addGuardian directly. Only\n  future bounties see the new roster; open bounties keep judging\n  against the hash pinned when they were created. With\n  --roster-admin-address, the transaction is simulated and printed\n  unsigned (to, data, value) for an external signer such as a Safe,\n  instead of being sent. Run roster:prepare-guardian-proof,\n  guardian:prove-roster-key, and roster:verify-guardian-proof against\n  the proposed Guardian before ever calling this.",
+    required: [],
+    defaulted: ["ELGORA_CHAIN_ID", "ELGORA_HUB_ADDRESS", "ELGORA_RPC_URL"]
+  },
+  "roster:prepare-guardian-proof": {
+    usage: "elgora-cli roster:prepare-guardian-proof <guardian_account> <encryption_public_key>",
+    title: "Start the key-custody proof for a proposed Guardian.",
+    description: "Picks a fresh random secret, seals it only to the proposed HPKE\n  public key, and builds the message the Guardian must sign alongside\n  the recovered bytes. Send only the printed send_to_guardian object to\n  the Guardian, over whatever channel you already trust them on \u2014 never\n  keep_local_do_not_share; that half stays with the roster admin and\n  feeds roster:verify-guardian-proof once the Guardian responds with\n  guardian:prove-roster-key. Pure local computation: no chain read, no\n  wallet, no network call, nothing enforced on ElgoraHub.",
+    required: [],
+    defaulted: ["ELGORA_CHAIN_ID", "ELGORA_HUB_ADDRESS"]
+  },
+  "roster:verify-guardian-proof": {
+    usage: "elgora-cli roster:verify-guardian-proof <prepared_json_path> <response_json_path>",
+    title: "Check a Guardian's key-custody proof response.",
+    description: "Takes the unmodified stdout of roster:prepare-guardian-proof and of\n  the Guardian's guardian:prove-roster-key, reconstructs the signed\n  payload from the fixture the admin generated (never sent to the\n  Guardian), and checks the recovered signer is the exact proposed\n  account. Exits non-zero on any mismatch. Advisory only \u2014 convinces\n  the admin, proves nothing to ElgoraHub, and does not itself add the\n  Guardian; run roster:add-guardian separately once satisfied.",
+    required: []
+  },
   "solver:submit": {
     usage: "elgora-cli solver:submit [--api-base-url <url>] [--solver-address <address>] <bounty_id> <artifact_dir>",
     title: "Encrypt and submit a Solver's private artifacts.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elgora/cli",
-  "version": "7.1.2",
+  "version": "7.2.1",
   "description": "Command-line client for Elgora, a decentralized bounty marketplace for science. Lets Posters, Solvers, and Guardians interact with Elgora's public API and on-chain contracts.",
   "type": "module",
   "license": "MIT",