@poa-box/core 0.1.0

package/dist/tx/eligibility.d.ts

@@ -0,0 +1,511 @@
+/**
+ * EligibilityModuleNew transaction builders — the vouch/* and role/* write
+ * surface (both CLI domains write to the same module).
+ *
+ * Level 1 (`build*`): pure, synchronous — resolved module address + prepared
+ * values in, TxIntent out. ALL argument encoding lives here and matches the
+ * CLI's executeTx calls byte-for-byte.
+ *
+ * Level 2 (`*Intent`): async — resolve the org's eligibility module via the
+ * subgraph, replicate the CLI's derivations (role-name→hatId, single-vs-batch
+ * method choice, metadata pinning for role applications, the audit-M-03
+ * vouch/default-eligibility conflict guard), then delegate to Level 1.
+ *
+ * NOT ported into builders (host concerns, run them via reads/eligibility +
+ * preflight.ts exactly as the CLI does): requireSuperAdmin, the vouch-for /
+ * claim / revoke revert-prediction gates, gas-balance checks, idempotency,
+ * and confirmation prompts. The ONE preflight that IS ported is the M-03
+ * conflict guard in configureVouchingIntent / setDefaultEligibilityIntent,
+ * because its state check + callStatic simulation is the only version-proof
+ * predictor of the DefaultEligibilityConflictsWithVouch revert and the CLI
+ * enforces it inline (src/commands/vouch/config.ts,
+ * src/commands/role/eligibility.ts).
+ */
+import { ethers } from 'ethers';
+import type { TxIntent } from './intent';
+import type { PopContext } from '../context';
+export interface VouchForArgs {
+    eligibilityModuleAddress: string;
+    wearer: string;
+    hatId: ethers.BigNumberish;
+    orgId?: string;
+}
+/** Port of `pop vouch for` — src/commands/vouch/for.ts: vouchFor(wearer, hatId). */
+export declare function buildVouchFor(a: VouchForArgs): TxIntent;
+export interface ClaimVouchedHatArgs {
+    eligibilityModuleAddress: string;
+    hatId: ethers.BigNumberish;
+    orgId?: string;
+}
+/**
+ * Port of `pop vouch claim` — src/commands/vouch/claim.ts:
+ * claimVouchedHat(hatId). Claim-based pattern — quorum never auto-mints.
+ */
+export declare function buildClaimVouchedHat(a: ClaimVouchedHatArgs): TxIntent;
+export interface RevokeVouchArgs {
+    eligibilityModuleAddress: string;
+    wearer: string;
+    hatId: ethers.BigNumberish;
+    orgId?: string;
+}
+/** Port of `pop vouch revoke` — src/commands/vouch/revoke.ts: revokeVouch(wearer, hatId). */
+export declare function buildRevokeVouch(a: RevokeVouchArgs): TxIntent;
+export interface ResetVouchesArgs {
+    eligibilityModuleAddress: string;
+    hatId: ethers.BigNumberish;
+    orgId?: string;
+}
+/**
+ * Port of `pop vouch reset` (no --wearer) — src/commands/vouch/reset.ts:
+ * resetVouches(hatId). DESTRUCTIVE, superAdmin-only: DELETES the hat's
+ * VouchConfig (vouching becomes disabled) and bumps the vouch epoch so every
+ * existing vouch for the hat is invalidated.
+ */
+export declare function buildResetVouches(a: ResetVouchesArgs): TxIntent;
+export interface ClearWearerVouchesArgs {
+    eligibilityModuleAddress: string;
+    wearer: string;
+    hatId: ethers.BigNumberish;
+    orgId?: string;
+}
+/**
+ * Port of `pop vouch reset --wearer` — src/commands/vouch/reset.ts:
+ * clearWearerVouches(wearer, hatId). Surgical per-wearer invalidation
+ * (sentinel epoch + count wipe); other wearers' vouches and the hat's config
+ * are untouched. superAdmin-only.
+ */
+export declare function buildClearWearerVouches(a: ClearWearerVouchesArgs): TxIntent;
+export interface ConfigureVouchingArgs {
+    eligibilityModuleAddress: string;
+    hatId: ethers.BigNumberish;
+    /** uint32; 0 disables vouching (`enabled` is derived on-chain as quorum > 0). */
+    quorum: number;
+    membershipHatId: ethers.BigNumberish;
+    combineWithHierarchy: boolean;
+    orgId?: string;
+}
+/**
+ * Port of `pop vouch config set` — src/commands/vouch/config.ts:
+ * configureVouching(hatId, quorum, membershipHatId, combineWithHierarchy).
+ * superAdmin-only; configuring bumps the hat's vouch epoch, invalidating all
+ * existing vouches.
+ */
+export declare function buildConfigureVouching(a: ConfigureVouchingArgs): TxIntent;
+export interface ApplyForRoleArgs {
+    eligibilityModuleAddress: string;
+    hatId: ethers.BigNumberish;
+    /** bytes32 — ipfsCidToBytes32 of the pinned role-application metadata. */
+    applicationHash: string;
+    orgId?: string;
+}
+/**
+ * Port of `pop role apply` — src/commands/role/apply.ts:
+ * applyForRole(hatId, applicationHash). Signaling only — grants no
+ * eligibility.
+ */
+export declare function buildApplyForRole(a: ApplyForRoleArgs): TxIntent;
+export interface WithdrawApplicationArgs {
+    eligibilityModuleAddress: string;
+    hatId: ethers.BigNumberish;
+    orgId?: string;
+}
+/**
+ * Port of `pop role withdraw-application` —
+ * src/commands/role/withdraw-application.ts: withdrawApplication(hatId).
+ */
+export declare function buildWithdrawApplication(a: WithdrawApplicationArgs): TxIntent;
+export interface CreateHatWithEligibilityArgs {
+    eligibilityModuleAddress: string;
+    parentHatId: ethers.BigNumberish;
+    /** Role name — stored as the hat `details` string. */
+    details: string;
+    /** uint32 — max simultaneous wearers. */
+    maxSupply: number;
+    mutable: boolean;
+    /** Hat image URI; empty string when omitted (CLI: `argv.image ?? ''`). */
+    imageURI?: string;
+    defaultEligible: boolean;
+    defaultStanding: boolean;
+    /** Addresses to mint the new hat to immediately; empty when omitted. */
+    mintTo?: string[];
+    /**
+     * Per-mint-to flags. Default TRUE per address — the CLI ALWAYS forces true
+     * so initial wearers are eligible regardless of the hat defaults.
+     */
+    wearerEligibleFlags?: boolean[];
+    wearerStandingFlags?: boolean[];
+    orgId?: string;
+}
+/**
+ * Port of `pop role create` — src/commands/role/create.ts:
+ * createHatWithEligibility(CreateHatParams). The tuple is built in EXACT ABI
+ * order (verified in abi CreateHatParams components):
+ *   (uint256 parentHatId, string details, uint32 maxSupply, bool _mutable,
+ *    string imageURI, bool defaultEligible, bool defaultStanding,
+ *    address[] mintToAddresses, bool[] wearerEligibleFlags,
+ *    bool[] wearerStandingFlags)
+ * superAdmin-only.
+ */
+export declare function buildCreateHatWithEligibility(a: CreateHatWithEligibilityArgs): TxIntent;
+export interface SetWearerEligibilityArgs {
+    eligibilityModuleAddress: string;
+    wearer: string;
+    hatId: ethers.BigNumberish;
+    eligible: boolean;
+    standing: boolean;
+    orgId?: string;
+}
+/**
+ * Port of `pop role eligibility set` (single-wearer) —
+ * src/commands/role/eligibility.ts:
+ * setWearerEligibility(wearer, hatId, eligible, standing). superAdmin-only.
+ */
+export declare function buildSetWearerEligibility(a: SetWearerEligibilityArgs): TxIntent;
+export interface BatchSetWearerEligibilityArgs {
+    eligibilityModuleAddress: string;
+    hatId: ethers.BigNumberish;
+    wearers: string[];
+    eligibleFlags: boolean[];
+    standingFlags: boolean[];
+    orgId?: string;
+}
+/**
+ * Port of `pop role eligibility set --file` (batch) —
+ * src/commands/role/eligibility.ts:
+ * batchSetWearerEligibility(hatId, wearers[], eligibleFlags[], standingFlags[]).
+ * superAdmin-only.
+ */
+export declare function buildBatchSetWearerEligibility(a: BatchSetWearerEligibilityArgs): TxIntent;
+export interface ClearWearerEligibilityArgs {
+    eligibilityModuleAddress: string;
+    wearer: string;
+    hatId: ethers.BigNumberish;
+    orgId?: string;
+}
+/**
+ * Port of `pop role eligibility clear` — src/commands/role/eligibility.ts:
+ * clearWearerEligibility(wearer, hatId) — removes the wearer-specific rule so
+ * the hat DEFAULTS apply again. superAdmin-only.
+ */
+export declare function buildClearWearerEligibility(a: ClearWearerEligibilityArgs): TxIntent;
+export interface SetDefaultEligibilityArgs {
+    eligibilityModuleAddress: string;
+    hatId: ethers.BigNumberish;
+    eligible: boolean;
+    standing: boolean;
+    orgId?: string;
+}
+/**
+ * Port of `pop role eligibility set-default` —
+ * src/commands/role/eligibility.ts:
+ * setDefaultEligibility(hatId, eligible, standing). superAdmin-only. See
+ * setDefaultEligibilityIntent for the audit-M-03 conflict guard the CLI runs
+ * before this write.
+ */
+export declare function buildSetDefaultEligibility(a: SetDefaultEligibilityArgs): TxIntent;
+export interface TransferSuperAdminArgs {
+    eligibilityModuleAddress: string;
+    newSuperAdmin: string;
+    orgId?: string;
+}
+/**
+ * Port of `pop role admin transfer` — src/commands/role/admin.ts:
+ * transferSuperAdmin(newSuperAdmin). DESTRUCTIVE — hands over the ENTIRE
+ * module (roles, eligibility, vouching, pause). superAdmin-only.
+ */
+export declare function buildTransferSuperAdmin(a: TransferSuperAdminArgs): TxIntent;
+export interface MintHatToAddressArgs {
+    eligibilityModuleAddress: string;
+    hatId: ethers.BigNumberish;
+    wearer: string;
+    orgId?: string;
+}
+/**
+ * Port of `pop role admin mint` (single wearer) — src/commands/role/admin.ts:
+ * mintHatToAddress(hatId, wearer). superAdmin-only.
+ */
+export declare function buildMintHatToAddress(a: MintHatToAddressArgs): TxIntent;
+export interface BatchMintHatsArgs {
+    eligibilityModuleAddress: string;
+    hatIds: ethers.BigNumberish[];
+    wearers: string[];
+    orgId?: string;
+}
+/**
+ * Port of `pop role admin mint` (comma-separated wearers) —
+ * src/commands/role/admin.ts: batchMintHats(hatIds[], wearers[]). The CLI
+ * replicates ONE hat per wearer (`wearers.map(() => hatId)`); mintHatsIntent
+ * derives that. superAdmin-only.
+ */
+export declare function buildBatchMintHats(a: BatchMintHatsArgs): TxIntent;
+export interface PauseArgs {
+    eligibilityModuleAddress: string;
+    orgId?: string;
+}
+/** Port of `pop role admin pause` — src/commands/role/admin.ts: pause(). superAdmin-only. */
+export declare function buildPause(a: PauseArgs): TxIntent;
+/** Port of `pop role admin unpause` — src/commands/role/admin.ts: unpause(). superAdmin-only. */
+export declare function buildUnpause(a: PauseArgs): TxIntent;
+export interface SetUserJoinTimeArgs {
+    eligibilityModuleAddress: string;
+    user: string;
+    /** Unix seconds. */
+    joinTime: ethers.BigNumberish;
+    orgId?: string;
+}
+/**
+ * Port of `pop role admin set-join-time --timestamp` —
+ * src/commands/role/admin.ts: setUserJoinTime(user, joinTime). Governs the
+ * new-account vouching grace. superAdmin-only.
+ */
+export declare function buildSetUserJoinTime(a: SetUserJoinTimeArgs): TxIntent;
+export interface SetUserJoinTimeNowArgs {
+    eligibilityModuleAddress: string;
+    user: string;
+    orgId?: string;
+}
+/**
+ * Port of `pop role admin set-join-time` (no --timestamp) —
+ * src/commands/role/admin.ts: setUserJoinTimeNow(user) — uses the current
+ * block time. superAdmin-only.
+ */
+export declare function buildSetUserJoinTimeNow(a: SetUserJoinTimeNowArgs): TxIntent;
+export interface VouchForParams {
+    org: string;
+    /** Address of the user to vouch for. */
+    wearer: string;
+    /** Hat ID; either this or `role` is required. */
+    hat?: string | number;
+    /** Role name — resolved to a hat ID via the subgraph, as the CLI's --role. */
+    role?: string;
+    /**
+     * The signing address, when known — enables the CLI's self-vouch guard
+     * ("You cannot vouch for yourself.").
+     */
+    voucher?: string;
+}
+/** Port of `pop vouch for` — src/commands/vouch/for.ts (org + role-name resolution). */
+export declare function vouchForIntent(ctx: PopContext, params: VouchForParams): Promise<TxIntent>;
+export interface ClaimVouchedHatParams {
+    org: string;
+    hat: string | number;
+}
+/** Port of `pop vouch claim` — src/commands/vouch/claim.ts (org resolution). */
+export declare function claimVouchedHatIntent(ctx: PopContext, params: ClaimVouchedHatParams): Promise<TxIntent>;
+export interface RevokeVouchParams {
+    org: string;
+    /** Address whose vouch to revoke (the wearer YOU vouched for). */
+    wearer: string;
+    hat: string | number;
+}
+/** Port of `pop vouch revoke` — src/commands/vouch/revoke.ts (org resolution). */
+export declare function revokeVouchIntent(ctx: PopContext, params: RevokeVouchParams): Promise<TxIntent>;
+export interface ResetVouchesParams {
+    org: string;
+    hat: string | number;
+    /** When set: surgical clearWearerVouches(wearer, hat); else resetVouches(hat). */
+    wearer?: string;
+}
+/**
+ * Port of `pop vouch reset` — src/commands/vouch/reset.ts. Derives the method
+ * exactly as the CLI does: --wearer → clearWearerVouches (surgical), no
+ * --wearer → resetVouches (deletes the VouchConfig + bumps the epoch).
+ * DESTRUCTIVE, superAdmin-only.
+ */
+export declare function resetVouchesIntent(ctx: PopContext, params: ResetVouchesParams): Promise<TxIntent>;
+export interface ConfigureVouchingParams {
+    org: string;
+    hat: string | number;
+    /** Vouches required to become claimable; 0 disables vouching. */
+    quorum: number;
+    /** Hat whose wearers are allowed to vouch. */
+    membershipHat: string | number;
+    combineHierarchy?: boolean;
+    /**
+     * The signing address — used by the M-03 callStatic simulation, which the
+     * CLI runs from the real superAdmin. Guard is skipped when absent.
+     */
+    from?: string;
+    /** false skips the M-03 conflict guard (the CLI's --no-preflight). */
+    preflight?: boolean;
+}
+/**
+ * Port of `pop vouch config set` — src/commands/vouch/config.ts, including the
+ * audit-M-03 reverse-direction guard: enabling vouching WITH combine-hierarchy
+ * on a hat that is already default-eligible reverts
+ * DefaultEligibilityConflictsWithVouch on modules that implement the check —
+ * everyone is eligible anyway, so the quorum would be a no-op. The state is
+ * detected via getDefaultRules, then the exact call is simulated from `from`
+ * (state alone is version-ambiguous — deployed v6 modules accept it). Only a
+ * contract revert blocks; transport failures degrade and let gas estimation be
+ * the real gate. Requires ctx.provider + params.from to run.
+ */
+export declare function configureVouchingIntent(ctx: PopContext, params: ConfigureVouchingParams): Promise<TxIntent>;
+export interface ApplyForRoleParams {
+    org: string;
+    hat: string | number;
+    notes?: string;
+    experience?: string;
+    /** Override the appliedAt timestamp (unix ms). Default Date.now(). */
+    appliedAt?: number;
+}
+/**
+ * Port of `pop role apply` — src/commands/role/apply.ts. Pins the
+ * {notes, experience, appliedAt} application metadata (metadata/role.ts —
+ * key order preserved for frontend/subgraph parity), converts the CID to
+ * bytes32, then delegates to buildApplyForRole. The pinned document rides in
+ * meta.ipfs.
+ */
+export declare function applyForRoleIntent(ctx: PopContext, params: ApplyForRoleParams): Promise<TxIntent>;
+export interface WithdrawApplicationParams {
+    org: string;
+    hat: string | number;
+}
+/**
+ * Port of `pop role withdraw-application` —
+ * src/commands/role/withdraw-application.ts (org resolution).
+ */
+export declare function withdrawApplicationIntent(ctx: PopContext, params: WithdrawApplicationParams): Promise<TxIntent>;
+/** Parse "--mint-to a,b,c" into checksummed addresses (empty when omitted). */
+export declare function parseMintTo(input: string | undefined): string[];
+export interface CreateRoleParams {
+    org: string;
+    parentHat: string | number;
+    /** Role name (stored as the hat details). */
+    name: string;
+    image?: string;
+    /** Default 1000, as the CLI. */
+    maxSupply?: number;
+    mutable?: boolean;
+    defaultEligible?: boolean;
+    defaultStanding?: boolean;
+    /** Comma-separated string (CLI --mint-to) or a prepared address array. */
+    mintTo?: string | string[];
+}
+/**
+ * Port of `pop role create` — src/commands/role/create.ts: validates
+ * max-supply (uint32), parses/checksums --mint-to, forces the per-mint-to
+ * eligible/standing flags TRUE, then delegates to
+ * buildCreateHatWithEligibility. superAdmin-only.
+ */
+export declare function createHatWithEligibilityIntent(ctx: PopContext, params: CreateRoleParams): Promise<TxIntent>;
+export interface SetWearerEligibilityParams {
+    org: string;
+    hat: string | number;
+    wearer: string;
+    /** Default true (the CLI's --eligible default; --no-eligible → false). */
+    eligible?: boolean;
+    /** Default true (the CLI's --standing default; --no-standing → false). */
+    standing?: boolean;
+}
+/**
+ * Port of `pop role eligibility set` (single wearer) —
+ * src/commands/role/eligibility.ts. superAdmin-only.
+ */
+export declare function setWearerEligibilityIntent(ctx: PopContext, params: SetWearerEligibilityParams): Promise<TxIntent>;
+/** One batch entry — the CLI's --file JSON row shape. */
+export interface EligibilityBatchEntry {
+    wearer: string;
+    /** Default true when omitted, as in the CLI's batch file format. */
+    eligible?: boolean;
+    standing?: boolean;
+}
+export interface BatchSetWearerEligibilityParams {
+    org: string;
+    hat: string | number;
+    entries: EligibilityBatchEntry[];
+}
+/**
+ * Port of `pop role eligibility set --file` —
+ * src/commands/role/eligibility.ts: validates the entries (the CLI's batch
+ * JSON shape, minus the fs read — the host loads the file), defaults
+ * eligible/standing to true, and encodes
+ * batchSetWearerEligibility(hatId, wearers[], eligibles[], standings[]).
+ * superAdmin-only.
+ */
+export declare function batchSetWearerEligibilityIntent(ctx: PopContext, params: BatchSetWearerEligibilityParams): Promise<TxIntent>;
+export interface ClearWearerEligibilityParams {
+    org: string;
+    hat: string | number;
+    wearer: string;
+}
+/**
+ * Port of `pop role eligibility clear` — src/commands/role/eligibility.ts.
+ * superAdmin-only.
+ */
+export declare function clearWearerEligibilityIntent(ctx: PopContext, params: ClearWearerEligibilityParams): Promise<TxIntent>;
+export interface SetDefaultEligibilityParams {
+    org: string;
+    hat: string | number;
+    /** Default true — a bare set-default hits the M-03 guard, as in the CLI. */
+    eligible?: boolean;
+    standing?: boolean;
+    /**
+     * The signing address — used by the M-03 callStatic simulation, which the
+     * CLI runs from the real superAdmin. Guard is skipped when absent.
+     */
+    from?: string;
+    /** false skips the M-03 conflict guard (the CLI's --no-preflight). */
+    preflight?: boolean;
+}
+/**
+ * Port of `pop role eligibility set-default` —
+ * src/commands/role/eligibility.ts, including the audit-M-03 guard: making a
+ * hat default-eligible while it uses vouching WITH combineWithHierarchy
+ * reverts DefaultEligibilityConflictsWithVouch — an open hat makes the vouch
+ * quorum meaningless. The state is detected via getVouchConfig +
+ * vouchConflictsWithDefaultEligibility (../perms — the browser-pure rule the
+ * CLI uses), then the exact call is simulated from `from`, because the state
+ * check alone is version-ambiguous: the deployed v6 modules ACCEPT the write
+ * (verified live — 17/19 live VouchConfig rows are in the "conflicting"
+ * state, so blocking on state alone would refuse a valid write on nearly
+ * every hat). Only a contract revert blocks; transport failures degrade and
+ * let gas estimation be the real gate. Requires ctx.provider + params.from.
+ * superAdmin-only.
+ */
+export declare function setDefaultEligibilityIntent(ctx: PopContext, params: SetDefaultEligibilityParams): Promise<TxIntent>;
+export interface TransferSuperAdminParams {
+    org: string;
+    /** New superAdmin address. */
+    to: string;
+    /** Current signer, when known — enables the CLI's self-transfer guard. */
+    from?: string;
+}
+/**
+ * Port of `pop role admin transfer` — src/commands/role/admin.ts.
+ * DESTRUCTIVE, superAdmin-only.
+ */
+export declare function transferSuperAdminIntent(ctx: PopContext, params: TransferSuperAdminParams): Promise<TxIntent>;
+export interface MintHatsParams {
+    org: string;
+    hat: string | number;
+    /** Comma-separated string (CLI --wearer) or a prepared address array. */
+    wearer: string | string[];
+}
+/**
+ * Port of `pop role admin mint` — src/commands/role/admin.ts. Derives the
+ * method exactly as the CLI does: one wearer → mintHatToAddress(hat, wearer);
+ * several → batchMintHats(hat replicated per wearer, wearers).
+ * superAdmin-only.
+ */
+export declare function mintHatsIntent(ctx: PopContext, params: MintHatsParams): Promise<TxIntent>;
+export interface PauseParams {
+    org: string;
+}
+/** Port of `pop role admin pause` — src/commands/role/admin.ts. superAdmin-only. */
+export declare function pauseIntent(ctx: PopContext, params: PauseParams): Promise<TxIntent>;
+/** Port of `pop role admin unpause` — src/commands/role/admin.ts. superAdmin-only. */
+export declare function unpauseIntent(ctx: PopContext, params: PauseParams): Promise<TxIntent>;
+export interface SetJoinTimeParams {
+    org: string;
+    user: string;
+    /** Unix seconds; omit to use the current block time via setUserJoinTimeNow. */
+    timestamp?: number;
+}
+/**
+ * Port of `pop role admin set-join-time` — src/commands/role/admin.ts.
+ * Derives the method exactly as the CLI does: --timestamp →
+ * setUserJoinTime(user, ts); omitted → setUserJoinTimeNow(user).
+ * superAdmin-only.
+ */
+export declare function setUserJoinTimeIntent(ctx: PopContext, params: SetJoinTimeParams): Promise<TxIntent>;