@poa-box/core 0.1.0 → 1.0.0

package/dist/reads/eligibility.js

@@ -1,687 +0,0 @@
-"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;
-}