@poa-box/core 0.1.0

package/dist/reads/eligibility.js

@@ -0,0 +1,687 @@
+"use strict";
+/**
+ * Shared EligibilityModule read layer for the vouch + role domains.
+ * Port of src/commands/vouch/helpers.ts (plus the subgraph list reads from
+ * src/commands/vouch/list.ts and src/commands/role/applications.ts): functions
+ * take the GraphClient / provider explicitly instead of importing
+ * process-global singletons.
+ *
+ * Both domains read the same module, whose admin surface is superAdmin-gated.
+ * Facts VERIFIED against contracts origin/main src/EligibilityModule.sol:
+ *
+ * - `superAdmin()` public getter exists; every eligibility/hat-admin write is
+ *   `onlySuperAdmin` (setWearerEligibility, setDefaultEligibility,
+ *   clearWearerEligibility, batchSetWearerEligibility, setDefaultEligibility,
+ *   createHatWithEligibility, mintHatToAddress, batchMintHats, pause/unpause,
+ *   transferSuperAdmin, setUserJoinTime, setUserJoinTimeNow, configureVouching,
+ *   resetVouches, clearWearerVouches).
+ * - VouchConfig struct: (uint32 quorum, uint256 membershipHatId, uint8 flags)
+ *   with flags bit 0 = enabled (ENABLED_FLAG 0x01) and bit 1 =
+ *   combineWithHierarchy (COMBINE_HIERARCHY_FLAG 0x02). Getter: getVouchConfig.
+ * - Rate limiting: getMaxDailyVouches() (DEFAULT_MAX_DAILY_VOUCHES = 20 when
+ *   unset), getCurrentDailyVouchCount(user) keyed by UTC day
+ *   (block.timestamp / 86400), getUserJoinTime(user), and the authoritative
+ *   combined answer canUserVouch(user).
+ * - vouchFor does NOT auto-mint at quorum: reaching quorum makes
+ *   getWearerStatus() return eligible, and the wearer claims explicitly via
+ *   claimVouchedHat (claim-based pattern per the contract doc comment).
+ *
+ * READ SOURCING (subgraph vs RPC), settled 2026-07-30 against the live
+ * poa-gnosis-v-1 / poa-arb-v-1 deployments:
+ *
+ * - DISPLAY reads (pop vouch status, pop vouch config show) go SUBGRAPH-FIRST
+ *   with the RPC getter kept as fallback: VouchConfig.{quorum,membershipHatId,
+ *   enabled,combinesWithHierarchy} and a count of active Vouch rows are
+ *   verified-populated and byte-for-byte equal to the on-chain values.
+ * - VOUCH COUNTS ARE EPOCH-SCOPED. configureVouching/batchConfigureVouching/
+ *   resetVouches bump vouchConfigEpoch[hatId] and clearWearerVouches parks
+ *   wearerVouchEpoch on a 2^256-1 sentinel; currentVouchCount() returns 0 when
+ *   the two disagree, and NO event marks the individual vouches dead. Counting
+ *   active Vouch rows therefore overcounts after any reconfiguration and would
+ *   report quorum met against a contract that says zero. Newer deployments
+ *   index the epochs (WearerVouchState), which is exact; older ones can only
+ *   detect the ambiguity and refuse. See graph/documents/vouch.ts for both tiers.
+ * - WRITE PRE-FLIGHT reads stay on RPC. superAdmin(), paused(),
+ *   hasVouched(), hasActiveApplication(), getWearerStatus(), getDefaultRules()
+ *   and the vouch-for/claim gates all exist to PREDICT A REVERT; indexing lag
+ *   there either broadcasts a doomed transaction or blocks a valid one.
+ *   They are instead batched through Multicall3 so each pre-flight costs ONE
+ *   round-trip instead of N.
+ * - NO subgraph field exists for getMaxDailyVouches(),
+ *   getCurrentDailyVouchCount() or canUserVouch(); UserJoinTime has ZERO rows
+ *   on the live Gnosis deployment. The whole VoucherGate therefore stays RPC.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VOUCH_FLAG_COMBINE_HIERARCHY = exports.VOUCH_FLAG_ENABLED = void 0;
+exports.resolveEligibilityModule = resolveEligibilityModule;
+exports.parseHatId = parseHatId;
+exports.decodeVouchConfig = decodeVouchConfig;
+exports.batchEligibilityReadsSettled = batchEligibilityReadsSettled;
+exports.batchEligibilityReads = batchEligibilityReads;
+exports.fetchVouchConfigFromSubgraph = fetchVouchConfigFromSubgraph;
+exports.readVouchConfigStatus = readVouchConfigStatus;
+exports.fetchWearerVouchStateFromSubgraph = fetchWearerVouchStateFromSubgraph;
+exports.readWearerVouchStateOnchain = readWearerVouchStateOnchain;
+exports.readWearerVouchState = readWearerVouchState;
+exports.getSuperAdmin = getSuperAdmin;
+exports.requireSuperAdmin = requireSuperAdmin;
+exports.requireSuperAdminWithRead = requireSuperAdminWithRead;
+exports.readVoucherGate = readVoucherGate;
+exports.vouchRestriction = vouchRestriction;
+exports.vouchQuotaLabel = vouchQuotaLabel;
+exports.readVouchPreflight = readVouchPreflight;
+exports.gateVouch = gateVouch;
+exports.readClaimGate = readClaimGate;
+exports.hasVouched = hasVouched;
+exports.readRevokeGate = readRevokeGate;
+exports.hasActiveApplication = hasActiveApplication;
+exports.isPaused = isPaused;
+exports.listVouches = listVouches;
+exports.listRoleApplications = listRoleApplications;
+exports.resolveRoleNameToHatId = resolveRoleNameToHatId;
+const ethers_1 = require("ethers");
+const resolve_1 = require("./resolve");
+const contracts_1 = require("../contracts");
+const multicall_1 = require("../multicall");
+const vouch_1 = require("../graph/documents/vouch");
+const role_1 = require("../graph/documents/role");
+const format_1 = require("../format");
+const errors_1 = require("../errors");
+const exit_codes_1 = require("../exit-codes");
+const perms_1 = require("../perms");
+Object.defineProperty(exports, "VOUCH_FLAG_ENABLED", { enumerable: true, get: function () { return perms_1.VOUCH_FLAG_ENABLED; } });
+Object.defineProperty(exports, "VOUCH_FLAG_COMBINE_HIERARCHY", { enumerable: true, get: function () { return perms_1.VOUCH_FLAG_COMBINE_HIERARCHY; } });
+/**
+ * Resolve an org to its EligibilityModule address.
+ * Port of src/commands/vouch/helpers.ts resolveEligibilityModule.
+ */
+async function resolveEligibilityModule(client, orgIdOrName, chainId) {
+    const modules = await (0, resolve_1.resolveOrgModules)(client, orgIdOrName, chainId);
+    return {
+        orgId: modules.orgId,
+        eligibilityModuleAddress: (0, resolve_1.requireModule)(modules, 'eligibilityModuleAddress'),
+    };
+}
+/** Parse a --hat argument (decimal or 0x-hex) into a BigNumber hat ID. */
+function parseHatId(input) {
+    try {
+        return ethers_1.ethers.BigNumber.from(String(input).trim());
+    }
+    catch {
+        throw new errors_1.CliError(`Invalid --hat "${input}".`, exit_codes_1.EXIT.USAGE, 'Pass the hat ID as a decimal or 0x-hex integer (see pop org roles).');
+    }
+}
+/** Decode a raw getVouchConfig/vouchConfigs result into named fields. */
+function decodeVouchConfig(raw) {
+    const flags = ethers_1.ethers.BigNumber.from(raw.flags).toNumber();
+    return {
+        quorum: ethers_1.ethers.BigNumber.from(raw.quorum).toNumber(),
+        membershipHatId: ethers_1.ethers.BigNumber.from(raw.membershipHatId).toString(),
+        enabled: (flags & perms_1.VOUCH_FLAG_ENABLED) !== 0,
+        combineWithHierarchy: (flags & perms_1.VOUCH_FLAG_COMBINE_HIERARCHY) !== 0,
+    };
+}
+/**
+ * Batch EligibilityModule view calls into ONE Multicall3 round-trip
+ * (multicall.ts degrades to parallel provider.call on chains without the
+ * canonical deployment, so callers always get one result per call).
+ *
+ * Every caller is a write pre-flight, so a sub-call that reverts must NEVER be
+ * silently decoded as a falsy answer: Multicall3.tryAggregate is invoked with
+ * requireSuccess=false, and any call that comes back unsuccessful is re-issued
+ * through the ethers contract so the original error propagates exactly as it
+ * did before batching.
+ *
+ * Return shape matches `contract.fn(...)`: a single output is unwrapped, a
+ * multi-output (getWearerStatus, getDefaultRules) stays an ethers Result with
+ * both named and positional access.
+ */
+async function batchEligibilityReadsSettled(provider, eligibilityModuleAddress, reads) {
+    const contract = (0, contracts_1.createReadContract)(eligibilityModuleAddress, 'EligibilityModuleNew', provider);
+    const iface = contract.interface;
+    let results = [];
+    try {
+        const calls = reads.map(r => ({
+            to: eligibilityModuleAddress,
+            data: iface.encodeFunctionData(r.fn, r.args),
+        }));
+        results = await (0, multicall_1.tryAggregate)(provider, calls);
+    }
+    catch {
+        results = [];
+    }
+    return Promise.allSettled(reads.map(async (read, i) => {
+        const result = results[i];
+        if (!result || !result.success || !result.returnData || result.returnData === '0x') {
+            // Not batchable / reverted — re-issue so the natural error surfaces.
+            return contract[read.fn](...read.args);
+        }
+        const decoded = iface.decodeFunctionResult(read.fn, result.returnData);
+        return decoded.length === 1 ? decoded[0] : decoded;
+    }));
+}
+/** batchEligibilityReadsSettled, rethrowing the first failure (Promise.all semantics). */
+async function batchEligibilityReads(provider, eligibilityModuleAddress, reads) {
+    const settled = await batchEligibilityReadsSettled(provider, eligibilityModuleAddress, reads);
+    return settled.map((entry) => {
+        if (entry.status === 'rejected')
+            throw entry.reason;
+        return entry.value;
+    });
+}
+/**
+ * Subgraph VouchConfig row → the same VouchConfigView the RPC tuple decodes to.
+ * `enabled` is authoritative in the subgraph (the contract derives it as
+ * quorum > 0 and emits it on VouchConfigSet), so it is used directly rather
+ * than re-derived from flags.
+ */
+function vouchConfigFromSubgraph(row) {
+    if (!row)
+        return null;
+    if (row.quorum === null || row.quorum === undefined)
+        return null;
+    if (row.enabled === null || row.enabled === undefined)
+        return null;
+    if (row.membershipHatId === null || row.membershipHatId === undefined)
+        return null;
+    if (row.combinesWithHierarchy === null || row.combinesWithHierarchy === undefined)
+        return null;
+    return {
+        quorum: Number(row.quorum),
+        membershipHatId: String(row.membershipHatId),
+        enabled: Boolean(row.enabled),
+        combineWithHierarchy: Boolean(row.combinesWithHierarchy),
+    };
+}
+/** The Graph caps a page at 1000 entities; a full page means "cannot derive". */
+const VOUCH_PAGE_CAP = 1000;
+/**
+ * Subgraph read of a hat's vouch config. Returns null — meaning "fall back to
+ * the RPC getter" — when the query fails, when the row is missing (absence is
+ * ambiguous between never-configured and not-yet-indexed), or when a field is
+ * null on an older deployment.
+ */
+async function fetchVouchConfigFromSubgraph(client, eligibilityModuleAddress, hatId, chainId) {
+    try {
+        const data = await client.query(vouch_1.FETCH_VOUCH_CONFIG, { eligibilityModuleId: eligibilityModuleAddress, hatId: hatId.toString() }, chainId);
+        return vouchConfigFromSubgraph(data?.vouchConfigs?.[0]);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Port of `pop vouch config show` — src/commands/vouch/config.ts.
+ * Config is SUBGRAPH-FIRST (display only) with getVouchConfig() as fallback;
+ * `preferSubgraph: false` (the CLI's explicit --rpc) pins the config read to
+ * the provider. getMaxDailyVouches() has no subgraph field and stays on chain.
+ */
+async function readVouchConfigStatus(client, provider, eligibilityModuleAddress, hatId, opts = {}) {
+    const contract = (0, contracts_1.createReadContract)(eligibilityModuleAddress, 'EligibilityModuleNew', provider);
+    const [subgraphConfig, maxDailyVouches] = await Promise.all([
+        opts.preferSubgraph !== false
+            ? fetchVouchConfigFromSubgraph(client, eligibilityModuleAddress, hatId, opts.chainId)
+            : Promise.resolve(null),
+        contract.getMaxDailyVouches(),
+    ]);
+    const config = subgraphConfig ?? decodeVouchConfig(await contract.getVouchConfig(hatId));
+    return {
+        config,
+        maxDailyVouches: Number(maxDailyVouches),
+        source: subgraphConfig ? 'subgraph' : 'rpc',
+    };
+}
+/**
+ * TIER 0 reader — reproduce `currentVouchCount(hatId, wearer)` from the subgraph's
+ * epoch mirror. Returns null to mean "cannot derive, fall back to RPC".
+ */
+function wearerCountFromEpochMirror(data, configRow) {
+    const configEpoch = configRow?.epoch;
+    if (configEpoch === null || configEpoch === undefined)
+        return null;
+    const states = data?.wearerVouchStates;
+    if (!Array.isArray(states))
+        return null;
+    // No row means the wearer has never been vouched for on this hat. The config row
+    // proved the module is indexed, so absence here is a real zero rather than lag.
+    if (states.length === 0)
+        return 0;
+    const state = states[0];
+    if (state?.count === null || state?.count === undefined)
+        return null;
+    if (state?.epoch === null || state?.epoch === undefined)
+        return null;
+    // The contract's getter, verbatim: a tally from a superseded epoch reads as zero.
+    // String compare because epochs are uint256 and exceed Number's safe range.
+    const count = String(state.epoch) === String(configEpoch) ? Number(state.count) : 0;
+    if (!Number.isFinite(count))
+        return null;
+    // effectiveCount is the subgraph's own materialisation of the same expression, kept
+    // in step by a sweep. Disagreement means the deployment is buggy — refuse to pick a
+    // winner and let the authoritative on-chain getter answer.
+    const materialised = state?.effectiveCount;
+    if (materialised !== null && materialised !== undefined && Number(materialised) !== count) {
+        return null;
+    }
+    return count;
+}
+/**
+ * TIER 1 reader — count active Vouch rows on deployments with no epoch mirror.
+ * Returns null to mean "cannot derive, fall back to RPC".
+ */
+function wearerCountFromVouchRows(data, configRow) {
+    const vouches = data?.vouches;
+    if (!Array.isArray(vouches) || vouches.length >= VOUCH_PAGE_CAP)
+        return null;
+    // EPOCH GUARD. These deployments do not index the vouch epoch at all, and the
+    // contract emits no event when a configureVouching/resetVouches invalidates every
+    // outstanding vouch — so the superseded rows are still isActive here. A vouch
+    // created BEFORE the config's last update may therefore be dead on chain, and
+    // counting it would report quorum met when the contract says otherwise. Block-number
+    // ordering is the only signal available, so any such row makes the count underivable.
+    const configBlock = Number(configRow?.updatedAtBlock ?? 0);
+    if (configBlock > 0 && vouches.some((v) => Number(v?.createdAtBlock ?? 0) < configBlock)) {
+        return null;
+    }
+    return vouches.length;
+}
+/**
+ * Subgraph read of a hat's vouch config PLUS the wearer's current vouch count.
+ * Returns null to mean "fall back to RPC".
+ *
+ * Two tiers (graph/documents/vouch.ts): the epoch mirror when the deployment indexes
+ * it — which is exact, and lets a reconfigured hat still be served from the subgraph —
+ * and the legacy active-row count, which can only refuse to answer once an epoch bump
+ * is suspected. `queryWithFieldFallback` drops to the legacy tier on the unknown-field
+ * validation error, so this works before and after the subgraph ships.
+ */
+async function fetchWearerVouchStateFromSubgraph(client, eligibilityModuleAddress, hatId, wearer, chainId) {
+    const variables = {
+        eligibilityModuleId: eligibilityModuleAddress,
+        hatId: hatId.toString(),
+        wearer,
+    };
+    try {
+        const { data, tierIndex } = await client.queryWithFieldFallback([
+            { query: vouch_1.FETCH_VOUCH_STATUS_EPOCH_AWARE, variables },
+            { query: vouch_1.FETCH_VOUCH_STATUS, variables },
+        ], { chainId });
+        const configRow = data?.vouchConfigs?.[0];
+        const config = vouchConfigFromSubgraph(configRow);
+        if (!config)
+            return null;
+        const currentCount = tierIndex === 0
+            ? wearerCountFromEpochMirror(data, configRow)
+            : wearerCountFromVouchRows(data, configRow);
+        if (currentCount === null)
+            return null;
+        return { config, currentCount };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * RPC read of the same wearer-side state, batched into one round-trip.
+ * `enabled` is derived from the config flags rather than a separate
+ * isVouchingEnabled() call — the contract's getter is literally
+ * `_isVouchingEnabled(vouchConfigs[hatId].flags)` (VERIFIED in
+ * src/EligibilityModule.sol), so the answer is identical.
+ */
+async function readWearerVouchStateOnchain(provider, eligibilityModuleAddress, hatId, wearer) {
+    const [rawConfig, currentCount] = await batchEligibilityReads(provider, eligibilityModuleAddress, [
+        { fn: 'vouchConfigs', args: [hatId] },
+        { fn: 'currentVouchCount', args: [hatId, wearer] },
+    ]);
+    return {
+        config: decodeVouchConfig(rawConfig),
+        currentCount: ethers_1.ethers.BigNumber.from(currentCount).toNumber(),
+    };
+}
+/**
+ * Wearer-side vouch progress, SUBGRAPH-FIRST with the RPC batch as fallback.
+ * Display-only (`pop vouch status`) — never used to gate a write.
+ *
+ * `preferSubgraph: false` (set when the caller pinned an explicit RPC node)
+ * skips the subgraph entirely so an explicitly targeted node stays the
+ * source of truth.
+ */
+async function readWearerVouchState(client, provider, eligibilityModuleAddress, hatId, wearer, opts = {}) {
+    if (opts.preferSubgraph !== false) {
+        const fromSubgraph = await fetchWearerVouchStateFromSubgraph(client, eligibilityModuleAddress, hatId, wearer, opts.chainId);
+        if (fromSubgraph)
+            return { state: fromSubgraph, source: 'subgraph' };
+    }
+    const state = await readWearerVouchStateOnchain(provider, eligibilityModuleAddress, hatId, wearer);
+    return { state, source: 'rpc' };
+}
+/**
+ * Read the module's superAdmin address (public getter, verified).
+ *
+ * NOT sourced from the subgraph even though EligibilityModuleContract
+ * .superAdmin is populated and matches on chain (verified: module
+ * 0x27114cb7… → 0x23f90b38… on both). Every caller is requireSuperAdmin, a
+ * pure revert predictor for the onlySuperAdmin modifier. Indexing lag over a
+ * transferSuperAdmin would either broadcast a doomed admin transaction (the
+ * outgoing admin still looks authorised) or hard-block the incoming one, and
+ * these are all write paths where one extra eth_call is noise next to the
+ * transaction itself.
+ */
+async function getSuperAdmin(provider, eligibilityModuleAddress) {
+    const contract = (0, contracts_1.createReadContract)(eligibilityModuleAddress, 'EligibilityModuleNew', provider);
+    return await contract.superAdmin();
+}
+/** Shared superAdmin mismatch/unreadable errors for both requireSuperAdmin forms. */
+function assertSuperAdmin(admin, signerAddress, action) {
+    if (admin.toLowerCase() !== signerAddress.toLowerCase()) {
+        throw new errors_1.PreconditionError(`${action} is superAdmin-only — the module superAdmin is ${admin}, but you are signing as ${signerAddress}.`, 'Run with the superAdmin key. If the superAdmin is the org executor, route this change through a governance proposal instead.');
+    }
+    return admin;
+}
+function unreadableSuperAdmin(eligibilityModuleAddress) {
+    return new errors_1.PreconditionError(`Could not read superAdmin() from the eligibility module at ${eligibilityModuleAddress}.`, 'Check RPC connectivity and that the org has an EligibilityModule deployed.');
+}
+/**
+ * Fail fast (exit 4) when the signer is not the module superAdmin, naming
+ * who the superAdmin actually is — BEFORE any gas is spent. Returns the
+ * superAdmin address on success. All EligibilityModule admin writes are
+ * onlySuperAdmin (verified, see module header).
+ */
+async function requireSuperAdmin(provider, eligibilityModuleAddress, signerAddress, action) {
+    let admin;
+    try {
+        admin = await getSuperAdmin(provider, eligibilityModuleAddress);
+    }
+    catch {
+        throw unreadableSuperAdmin(eligibilityModuleAddress);
+    }
+    return assertSuperAdmin(admin, signerAddress, action);
+}
+/**
+ * requireSuperAdmin PLUS one extra pre-flight read, in ONE Multicall3
+ * round-trip instead of two sequential eth_calls to the same contract.
+ *
+ * The two are independent: a superAdmin() failure raises the same
+ * PreconditionError requireSuperAdmin does, while a failure of the extra read
+ * (older module without the getter, for instance) is returned as
+ * `{ extra: null, extraError }` so callers can keep downgrading it to a
+ * skipped soft check rather than blocking the write.
+ */
+async function requireSuperAdminWithRead(provider, eligibilityModuleAddress, signerAddress, action, extra) {
+    const [adminResult, extraResult] = await batchEligibilityReadsSettled(provider, eligibilityModuleAddress, [{ fn: 'superAdmin', args: [] }, extra]);
+    if (adminResult.status === 'rejected')
+        throw unreadableSuperAdmin(eligibilityModuleAddress);
+    const admin = assertSuperAdmin(adminResult.value, signerAddress, action);
+    return extraResult.status === 'fulfilled'
+        ? { admin, extra: extraResult.value, extraError: null }
+        : { admin, extra: null, extraError: extraResult.reason };
+}
+/**
+ * The four gate reads, in batch order. ALL FOUR ARE RPC-ONLY and cannot be
+ * served by the subgraph (verified 2026-07-30 against poa-gnosis-v-1):
+ *   canUserVouch            — composite of join-grace + daily limit, no field
+ *   getCurrentDailyVouchCount — no field (derivable from Vouch.createdAt, but
+ *                             only by re-deriving the contract's UTC-day
+ *                             bucketing client-side; left on RPC)
+ *   getMaxDailyVouches      — EligibilityModuleContract has no maxDailyVouches
+ *                             field even though MaxDailyVouchesSet is emitted
+ *   getUserJoinTime         — UserJoinTime entity has ZERO rows live
+ */
+const VOUCHER_GATE_READS = (voucher) => [
+    { fn: 'canUserVouch', args: [voucher] },
+    { fn: 'getCurrentDailyVouchCount', args: [voucher] },
+    { fn: 'getMaxDailyVouches', args: [] },
+    { fn: 'getUserJoinTime', args: [voucher] },
+];
+function decodeVoucherGate(raw) {
+    const [canVouch, dailyUsed, maxDaily, joinTime] = raw;
+    return {
+        canVouch: Boolean(canVouch),
+        dailyUsed: ethers_1.ethers.BigNumber.from(dailyUsed).toNumber(),
+        maxDaily: ethers_1.ethers.BigNumber.from(maxDaily).toNumber(),
+        joinTime: ethers_1.ethers.BigNumber.from(joinTime).toNumber(),
+    };
+}
+/**
+ * Read the signer-side vouching gate in ONE Multicall3 round-trip:
+ * canUserVouch (the authoritative on-chain answer), getCurrentDailyVouchCount
+ * vs getMaxDailyVouches, and getUserJoinTime for the new-account grace.
+ */
+async function readVoucherGate(provider, eligibilityModuleAddress, voucher) {
+    const raw = await batchEligibilityReads(provider, eligibilityModuleAddress, VOUCHER_GATE_READS(voucher));
+    return decodeVoucherGate(raw);
+}
+/** Approximate new-user grace used only for the unlock estimate (deployed v4 modules). */
+const NEW_USER_GRACE_SECONDS = 2 * 86400;
+/**
+ * Human reason why a signer cannot vouch right now, derived from the gate
+ * reads. canUserVouch is authoritative; this maps its `false` to the same
+ * friendly reasons the contract enforces (daily rate limit, else the
+ * new-account grace). Returns null when the signer can vouch.
+ */
+function vouchRestriction(gate, now = Math.floor(Date.now() / 1000)) {
+    if (gate.canVouch)
+        return null;
+    if (gate.dailyUsed >= gate.maxDaily) {
+        const nextUtcMidnight = (Math.floor(now / 86400) + 1) * 86400;
+        return {
+            message: `Daily vouch limit reached (${gate.dailyUsed}/${gate.maxDaily} used today).`,
+            suggestion: `The counter resets at the next UTC midnight (${(0, format_1.formatRelativeTime)(nextUtcMidnight, now)}).`,
+        };
+    }
+    const unlockAt = gate.joinTime > 0 ? gate.joinTime + NEW_USER_GRACE_SECONDS : 0;
+    const unlockHint = unlockAt > now
+        ? `Vouching unlocks ${(0, format_1.formatRelativeTime)(unlockAt, now)} (about 2 days after joining).`
+        : 'New accounts must wait out a short grace period before vouching.';
+    return {
+        message: 'Account too new — new members cannot vouch during the join grace period.',
+        suggestion: unlockHint,
+    };
+}
+/** "2/3 used today" quota fragment shared by vouch status + vouch for. */
+function vouchQuotaLabel(gate) {
+    return `${gate.dailyUsed}/${gate.maxDaily} used today`;
+}
+/**
+ * Pre-flight reads for `pop vouch for`, in ONE Multicall3 round-trip (was six
+ * separate eth_calls): the signer gate, the hat's vouch config
+ * (enabled/quorum), and the wearer's current count for the progress line.
+ *
+ * Deliberately RPC — this gates a write, and every field predicts a revert
+ * (VouchingNotEnabled, NewUserVouchingRestricted, VouchingRateLimitExceeded).
+ */
+async function readVouchPreflight(provider, eligibilityModuleAddress, hatId, voucher, wearer) {
+    const raw = await batchEligibilityReads(provider, eligibilityModuleAddress, [
+        ...VOUCHER_GATE_READS(voucher),
+        { fn: 'getVouchConfig', args: [hatId] },
+        { fn: 'currentVouchCount', args: [hatId, wearer] },
+    ]);
+    const [rawConfig, currentCount] = raw.slice(4);
+    return {
+        gate: decodeVoucherGate(raw.slice(0, 4)),
+        config: decodeVouchConfig(rawConfig),
+        currentCount: ethers_1.ethers.BigNumber.from(currentCount).toNumber(),
+    };
+}
+/**
+ * Fail fast (exit 4) on every vouch precondition the contract would revert
+ * on: vouching disabled, daily rate limit, new-account grace. Mirrors
+ * vouchFor's own gate order so the friendly message matches the revert the
+ * tx would have produced. Port of `pop vouch for`'s gateVouch —
+ * src/commands/vouch/for.ts.
+ */
+function gateVouch(state, hatId) {
+    if (!state.config.enabled) {
+        throw new errors_1.PreconditionError(`Vouching is not enabled for hat ${hatId}.`, 'Inspect/enable it with: pop vouch config show --hat ' + hatId);
+    }
+    const restriction = vouchRestriction(state.gate);
+    if (restriction) {
+        throw new errors_1.PreconditionError(restriction.message, restriction.suggestion);
+    }
+}
+/**
+ * Read getWearerStatus + vouch progress for a claim pre-flight, in ONE
+ * Multicall3 round-trip (was three eth_calls).
+ *
+ * getWearerStatus stays RPC on purpose. Besides gating a write, the subgraph's
+ * WearerEligibility entity is NOT equivalent: it only materialises when an
+ * admin sets a wearer-specific rule. VERIFIED live — wearer
+ * 0x1302e867… reached quorum on hat 29089782865237956866… and
+ * getWearerStatus() returns (true, true) on chain, yet the Gnosis subgraph has
+ * ZERO WearerEligibility rows for that address. Sourcing the claim gate from
+ * the subgraph would reject every vouch-eligible claimer.
+ */
+async function readClaimGate(provider, eligibilityModuleAddress, wearer, hatId) {
+    const [status, rawConfig, currentCount] = await batchEligibilityReads(provider, eligibilityModuleAddress, [
+        { fn: 'getWearerStatus', args: [wearer, hatId] },
+        { fn: 'getVouchConfig', args: [hatId] },
+        { fn: 'currentVouchCount', args: [hatId, wearer] },
+    ]);
+    return {
+        eligible: Boolean(status.eligible ?? status[0]),
+        standing: Boolean(status.standing ?? status[1]),
+        config: decodeVouchConfig(rawConfig),
+        currentCount: ethers_1.ethers.BigNumber.from(currentCount).toNumber(),
+    };
+}
+/**
+ * True when the signer's own vouch record exists (raw, epoch-unaware).
+ *
+ * RPC-only: the sole caller is `pop vouch revoke`'s pre-flight, which exists
+ * to predict revokeVouch's HasNotVouched revert. The subgraph could answer it
+ * (Vouch filtered on hatId+wearer+voucher+isActive is populated), but a stale
+ * "false" blocks a legitimate revoke and a stale "true" broadcasts a doomed
+ * one.
+ */
+async function hasVouched(provider, eligibilityModuleAddress, hatId, wearer, voucher) {
+    const contract = (0, contracts_1.createReadContract)(eligibilityModuleAddress, 'EligibilityModuleNew', provider);
+    return Boolean(await contract.hasVouched(hatId, wearer, voucher));
+}
+/**
+ * Revoke pre-flight, RPC-only (it predicts a revert, so indexing lag is not
+ * acceptable) and batched into ONE round-trip.
+ *
+ * `hasVouched` ALONE IS NOT SUFFICIENT: the getter returns the raw `vouchers`
+ * mapping with no epoch filter (VERIFIED, contracts origin/main — it is a bare
+ * `return _layout().vouchers[hatId][wearer][voucher]`), while revokeVouch first
+ * requires `wearerVouchEpoch[hatId][wearer] == vouchConfigEpoch[hatId]`. After a
+ * configureVouching/resetVouches/clearWearerVouches, hasVouched still says true
+ * and the transaction still reverts HasNotVouched.
+ *
+ * currentVouchCount closes most of that gap: it returns 0 for exactly the stale-epoch
+ * case, and a zero count also makes the `newCount = count - 1` underflow unavoidable —
+ * so `currentCount == 0` guarantees a revert and can be blocked with no false negatives.
+ *
+ * One residual case stays unpredictable off-chain: the wearer's epoch is current
+ * (someone else vouched after the bump) but THIS voucher's record is not. There is no
+ * getter for voucherRecordEpoch, so the decoded HasNotVouched revert still covers it.
+ */
+async function readRevokeGate(provider, eligibilityModuleAddress, hatId, wearer, voucher) {
+    const [vouched, currentCount] = await batchEligibilityReads(provider, eligibilityModuleAddress, [
+        { fn: 'hasVouched', args: [hatId, wearer, voucher] },
+        { fn: 'currentVouchCount', args: [hatId, wearer] },
+    ]);
+    return {
+        hasVouched: Boolean(vouched),
+        currentCount: ethers_1.ethers.BigNumber.from(currentCount).toNumber(),
+    };
+}
+/**
+ * True when `applicant` has an active application for `hatId`.
+ *
+ * RPC-only. RoleApplication.active IS populated on the live subgraph, but the
+ * ONLY caller of this helper is `pop role withdraw-application`'s pre-flight
+ * (src/commands/role/withdraw-application.ts), which predicts the
+ * NoActiveApplication revert — there is no display caller. `pop role
+ * applications` reads the subgraph via listRoleApplications below.
+ */
+async function hasActiveApplication(provider, eligibilityModuleAddress, hatId, applicant) {
+    const contract = (0, contracts_1.createReadContract)(eligibilityModuleAddress, 'EligibilityModuleNew', provider);
+    return Boolean(await contract.hasActiveApplication(hatId, applicant));
+}
+/**
+ * Read paused() (superAdmin emergency-pause state).
+ *
+ * RPC-only. EligibilityModuleContract.isPaused is populated and agrees with
+ * chain (verified: false on module 0x27114cb7… both ways), but the only caller
+ * is `pop role admin pause/unpause`, which uses it to predict OpenZeppelin's
+ * ExpectedPause / EnforcedPause revert.
+ */
+async function isPaused(provider, eligibilityModuleAddress) {
+    const contract = (0, contracts_1.createReadContract)(eligibilityModuleAddress, 'EligibilityModuleNew', provider);
+    return Boolean(await contract.paused());
+}
+/**
+ * Port of `pop vouch list` — src/commands/vouch/list.ts. Pure subgraph
+ * (FETCH_VOUCHES_FOR_ORG); display only, never a quorum decision (see the
+ * document's isActive epoch note in graph/documents/vouch.ts). `hatId` filter
+ * is applied client-side by string equality, exactly as the CLI does.
+ */
+async function listVouches(client, eligibilityModuleAddress, opts = {}) {
+    const result = await client.query(vouch_1.FETCH_VOUCHES_FOR_ORG, { eligibilityModuleId: eligibilityModuleAddress }, opts.chainId);
+    let vouches = result.vouches || [];
+    if (opts.hatId) {
+        vouches = vouches.filter((v) => v.hatId === opts.hatId);
+    }
+    return vouches;
+}
+/**
+ * Port of `pop role applications` — src/commands/role/applications.ts.
+ * Pure subgraph: FETCH_USER_ROLE_APPLICATIONS when `applicant` is given
+ * (lowercased, as the CLI does), else FETCH_ALL_ROLE_APPLICATIONS — both
+ * filtered by eligibilityModuleId. `hatId` filter is applied client-side by
+ * string equality, exactly as the CLI does.
+ */
+async function listRoleApplications(client, eligibilityModuleAddress, opts = {}) {
+    const result = opts.applicant
+        ? await client.query(role_1.FETCH_USER_ROLE_APPLICATIONS, { eligibilityModuleId: eligibilityModuleAddress, applicant: opts.applicant.toLowerCase() }, opts.chainId)
+        : await client.query(role_1.FETCH_ALL_ROLE_APPLICATIONS, { eligibilityModuleId: eligibilityModuleAddress }, opts.chainId);
+    let applications = result.roleApplications || [];
+    if (opts.hatId) {
+        applications = applications.filter((a) => a.hatId === opts.hatId);
+    }
+    return applications;
+}
+/**
+ * Resolve a role name to its hat ID by querying the org's roles.
+ * Port of `pop vouch for`'s resolveRoleToHatId — src/commands/vouch/for.ts —
+ * minus the TTY disambiguation select (CLI UX): exact match first, then
+ * partial; multiple matches always fail with the candidate list.
+ */
+async function resolveRoleNameToHatId(client, orgIdOrName, roleName, chainId) {
+    const orgId = await (0, resolve_1.resolveOrgId)(client, orgIdOrName, chainId);
+    const query = `{
+    organization(id: "${orgId}") {
+      roles(where: { isUserRole: true }) { hatId name }
+    }
+  }`;
+    const results = await client.queryAllChains(query, {});
+    const matches = [];
+    for (const r of results) {
+        const roles = r.data?.organization?.roles || [];
+        for (const role of roles) {
+            if (role.name && role.name.toLowerCase() === roleName.toLowerCase()) {
+                matches.push({ hatId: role.hatId, name: role.name });
+            }
+        }
+    }
+    if (matches.length === 0) {
+        // Try partial match
+        for (const r of results) {
+            const roles = r.data?.organization?.roles || [];
+            for (const role of roles) {
+                if (role.name && role.name.toLowerCase().includes(roleName.toLowerCase())) {
+                    matches.push({ hatId: role.hatId, name: role.name });
+                }
+            }
+        }
+    }
+    if (matches.length === 0) {
+        throw new errors_1.CliError(`No role named "${roleName}" found.`, exit_codes_1.EXIT.USAGE, 'Use pop org roles to list available roles.');
+    }
+    if (matches.length > 1) {
+        const names = matches.map(m => `${m.name} (${m.hatId})`).join(', ');
+        throw new errors_1.CliError(`Multiple roles match "${roleName}": ${names}.`, exit_codes_1.EXIT.USAGE, 'Use --hat with the specific hat ID.');
+    }
+    return matches[0].hatId;
+}