@poa-box/core 0.1.0 → 1.0.0

package/dist/tx/eligibility.d.ts

@@ -1,511 +0,0 @@
-/**
- * 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>;