@poa-box/core 0.1.0 → 1.0.0

package/dist/reads/eligibility.d.ts

@@ -1,377 +0,0 @@
-/**
- * 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.
- */
-import { ethers } from 'ethers';
-import type { GraphClient } from '../graph/client';
-import { VOUCH_FLAG_ENABLED, VOUCH_FLAG_COMBINE_HIERARCHY } from '../perms';
-export { VOUCH_FLAG_ENABLED, VOUCH_FLAG_COMBINE_HIERARCHY };
-/**
- * Resolve an org to its EligibilityModule address.
- * Port of src/commands/vouch/helpers.ts resolveEligibilityModule.
- */
-export declare function resolveEligibilityModule(client: GraphClient, orgIdOrName: string | undefined, chainId?: number): Promise<{
-    orgId: string;
-    eligibilityModuleAddress: string;
-}>;
-/** Parse a --hat argument (decimal or 0x-hex) into a BigNumber hat ID. */
-export declare function parseHatId(input: string | number): ethers.BigNumber;
-/** Decoded VouchConfig tuple (quorum, membershipHatId, flags). */
-export interface VouchConfigView {
-    quorum: number;
-    membershipHatId: string;
-    enabled: boolean;
-    combineWithHierarchy: boolean;
-}
-/** Decode a raw getVouchConfig/vouchConfigs result into named fields. */
-export declare function decodeVouchConfig(raw: {
-    quorum: ethers.BigNumberish;
-    membershipHatId: ethers.BigNumberish;
-    flags: ethers.BigNumberish;
-}): VouchConfigView;
-/** One EligibilityModule view call in a Multicall3 batch. */
-export interface EligibilityRead {
-    fn: string;
-    args: any[];
-}
-/**
- * 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.
- */
-export declare function batchEligibilityReadsSettled(provider: ethers.providers.Provider, eligibilityModuleAddress: string, reads: EligibilityRead[]): Promise<PromiseSettledResult<any>[]>;
-/** batchEligibilityReadsSettled, rethrowing the first failure (Promise.all semantics). */
-export declare function batchEligibilityReads(provider: ethers.providers.Provider, eligibilityModuleAddress: string, reads: EligibilityRead[]): Promise<any[]>;
-/**
- * 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.
- */
-export declare function fetchVouchConfigFromSubgraph(client: GraphClient, eligibilityModuleAddress: string, hatId: ethers.BigNumber, chainId?: number): Promise<VouchConfigView | null>;
-/** What `pop vouch config show` reads: the hat config + the org-wide rate limit. */
-export interface VouchConfigStatus {
-    config: VouchConfigView;
-    /** getMaxDailyVouches() — ALWAYS RPC, no subgraph field exists. */
-    maxDailyVouches: number;
-    source: 'subgraph' | 'rpc';
-}
-/**
- * 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.
- */
-export declare function readVouchConfigStatus(client: GraphClient, provider: ethers.providers.Provider, eligibilityModuleAddress: string, hatId: ethers.BigNumber, opts?: {
-    chainId?: number;
-    preferSubgraph?: boolean;
-}): Promise<VouchConfigStatus>;
-/** Wearer-side vouch progress for `pop vouch status` (display only). */
-export interface WearerVouchState {
-    config: VouchConfigView;
-    currentCount: number;
-}
-/**
- * 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.
- */
-export declare function fetchWearerVouchStateFromSubgraph(client: GraphClient, eligibilityModuleAddress: string, hatId: ethers.BigNumber, wearer: string, chainId?: number): Promise<WearerVouchState | 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.
- */
-export declare function readWearerVouchStateOnchain(provider: ethers.providers.Provider, eligibilityModuleAddress: string, hatId: ethers.BigNumberish, wearer: string): Promise<WearerVouchState>;
-/**
- * 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.
- */
-export declare function readWearerVouchState(client: GraphClient, provider: ethers.providers.Provider, eligibilityModuleAddress: string, hatId: ethers.BigNumber, wearer: string, opts?: {
-    chainId?: number;
-    preferSubgraph?: boolean;
-}): Promise<{
-    state: WearerVouchState;
-    source: 'subgraph' | '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.
- */
-export declare function getSuperAdmin(provider: ethers.providers.Provider, eligibilityModuleAddress: string): Promise<string>;
-/**
- * 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).
- */
-export declare function requireSuperAdmin(provider: ethers.providers.Provider, eligibilityModuleAddress: string, signerAddress: string, action: string): Promise<string>;
-/**
- * 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.
- */
-export declare function requireSuperAdminWithRead<T = any>(provider: ethers.providers.Provider, eligibilityModuleAddress: string, signerAddress: string, action: string, extra: EligibilityRead): Promise<{
-    admin: string;
-    extra: T | null;
-    extraError: any;
-}>;
-/** Signer-side vouching gate: the rate-limit/grace reads behind canUserVouch. */
-export interface VoucherGate {
-    canVouch: boolean;
-    dailyUsed: number;
-    maxDaily: number;
-    /** Unix seconds; 0 = never set (no restriction applies). */
-    joinTime: number;
-}
-/**
- * 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.
- */
-export declare function readVoucherGate(provider: ethers.providers.Provider, eligibilityModuleAddress: string, voucher: string): Promise<VoucherGate>;
-/**
- * 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.
- */
-export declare function vouchRestriction(gate: VoucherGate, now?: number): {
-    message: string;
-    suggestion: string;
-} | null;
-/** "2/3 used today" quota fragment shared by vouch status + vouch for. */
-export declare function vouchQuotaLabel(gate: VoucherGate): string;
-/** Everything `pop vouch for` pre-flights in one read batch. */
-export interface VouchPreflightState {
-    gate: VoucherGate;
-    config: VouchConfigView;
-    /** Wearer's current (epoch-aware) vouch count for the hat. */
-    currentCount: number;
-}
-/**
- * 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).
- */
-export declare function readVouchPreflight(provider: ethers.providers.Provider, eligibilityModuleAddress: string, hatId: ethers.BigNumberish, voucher: string, wearer: string): Promise<VouchPreflightState>;
-/**
- * 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.
- */
-export declare function gateVouch(state: VouchPreflightState, hatId: string): void;
-/** Claim-side pre-flight state for `pop vouch claim`. */
-export interface ClaimGateState {
-    eligible: boolean;
-    standing: boolean;
-    config: VouchConfigView;
-    currentCount: number;
-}
-/**
- * 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.
- */
-export declare function readClaimGate(provider: ethers.providers.Provider, eligibilityModuleAddress: string, wearer: string, hatId: ethers.BigNumberish): Promise<ClaimGateState>;
-/**
- * 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.
- */
-export declare function hasVouched(provider: ethers.providers.Provider, eligibilityModuleAddress: string, hatId: ethers.BigNumberish, wearer: string, voucher: string): Promise<boolean>;
-/** What `pop vouch revoke` pre-flights, in one Multicall3 round-trip. */
-export interface RevokeGate {
-    /** Raw `vouchers[hat][wearer][voucher]` — true even for a superseded epoch. */
-    hasVouched: boolean;
-    /** Epoch-aware `currentVouchCount(hat, wearer)`; 0 proves revokeVouch reverts. */
-    currentCount: number;
-}
-/**
- * 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.
- */
-export declare function readRevokeGate(provider: ethers.providers.Provider, eligibilityModuleAddress: string, hatId: ethers.BigNumberish, wearer: string, voucher: string): Promise<RevokeGate>;
-/**
- * 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.
- */
-export declare function hasActiveApplication(provider: ethers.providers.Provider, eligibilityModuleAddress: string, hatId: ethers.BigNumberish, applicant: string): Promise<boolean>;
-/**
- * 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.
- */
-export declare function isPaused(provider: ethers.providers.Provider, eligibilityModuleAddress: string): Promise<boolean>;
-/** One row of FETCH_VOUCHES_FOR_ORG (raw subgraph entity shape). */
-export interface VouchRow {
-    id: string;
-    hatId: string;
-    wearer: string;
-    wearerUsername: string | null;
-    voucher: string;
-    voucherUsername: string | null;
-    vouchCount: string | null;
-    isActive: boolean;
-    createdAt: string | null;
-}
-/**
- * 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.
- */
-export declare function listVouches(client: GraphClient, eligibilityModuleAddress: string, opts?: {
-    hatId?: string;
-    chainId?: number;
-}): Promise<VouchRow[]>;
-/** One row of FETCH_ALL/USER_ROLE_APPLICATIONS (raw subgraph entity shape). */
-export interface RoleApplicationRow {
-    id: string;
-    hatId: string;
-    applicant: string;
-    applicantUsername: string | null;
-    applicationHash: string;
-    active: boolean;
-    appliedAt: string | null;
-}
-/**
- * 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.
- */
-export declare function listRoleApplications(client: GraphClient, eligibilityModuleAddress: string, opts?: {
-    applicant?: string;
-    hatId?: string;
-    chainId?: number;
-}): Promise<RoleApplicationRow[]>;
-/**
- * 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.
- */
-export declare function resolveRoleNameToHatId(client: GraphClient, orgIdOrName: string, roleName: string, chainId?: number): Promise<string>;