@poa-box/core 0.1.0

package/dist/reads/zkemail.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * ZK Email reads — module resolution + state for `pop zkemail status` /
+ * `pop zkemail claims`. Port of src/commands/zkemail/helpers.ts (client- and
+ * provider-injected) plus the claim-history read from
+ * src/commands/zkemail/claims.ts.
+ *
+ * The ZkEmailInvites module is OPTIONAL per org — `organization.zkEmailInvites`
+ * is null for orgs deployed without it — and a deployed module with
+ * `merkleRoot == 0` is DORMANT (every claim reverts until governance publishes
+ * an allowlist). Both states get a named error rather than a confusing revert.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveZkEmailModule = resolveZkEmailModule;
+exports.readModuleState = readModuleState;
+exports.fetchIndexedActiveRoot = fetchIndexedActiveRoot;
+exports.fetchZkEmailClaims = fetchZkEmailClaims;
+exports.fetchRoleNames = fetchRoleNames;
+exports.labelHat = labelHat;
+exports.normalizeEntries = normalizeEntries;
+const ethers_1 = require("ethers");
+const zkemail_1 = require("../graph/documents/zkemail");
+const resolve_1 = require("./resolve");
+const contracts_1 = require("../contracts");
+const chains_1 = require("../chains");
+const encoding_1 = require("../encoding");
+const errors_1 = require("../errors");
+const exit_codes_1 = require("../exit-codes");
+/**
+ * Resolve the org's ZkEmailInvites proxy from the subgraph. Port of
+ * resolveZkEmailModule in src/commands/zkemail/helpers.ts.
+ * Throws a named error when the org has no module rather than letting a null
+ * address turn into an opaque call failure.
+ */
+async function resolveZkEmailModule(client, orgArg, chainId) {
+    const orgId = await (0, resolve_1.resolveOrgId)(client, orgArg, chainId);
+    // Modern tier carries the wiring + DKIM keys (subgraph-pop #197); the legacy tier is the
+    // allowlist-only shape served before it. tierIndex tells callers whether they still have to
+    // fall back to RPC for the rest.
+    const { data: res, tierIndex } = await client.queryWithFieldFallback(zkemail_1.FETCH_ZKEMAIL_MODULE_TIERS.map((q) => ({ query: q, variables: { orgId } })), { chainId });
+    const indexedWiring = tierIndex === 0;
+    const org = res.organization;
+    if (!org) {
+        throw new errors_1.CliError(`Organization ${orgId} not found on this chain.`, exit_codes_1.EXIT.USAGE);
+    }
+    const mod = org.zkEmailInvites;
+    if (!mod?.id) {
+        throw new errors_1.CliError(`Org "${org.name || orgId}" has no ZkEmailInvites module.`, exit_codes_1.EXIT.PRECONDITION, 'ZK Email invites are opt-in per org — the module is wired at deploy time via '
+            + 'OrgDeployer.deployFullOrgWithZkEmail. Existing orgs need a governance-approved module install.');
+    }
+    return { orgId, orgName: org.name ?? null, address: mod.id, subgraph: mod, indexedWiring };
+}
+/**
+ * Read the module's state, preferring the subgraph. Port of readModuleState in
+ * src/commands/zkemail/helpers.ts (the read behind `pop zkemail status`).
+ *
+ * `activeRoot` and `activeAllowlistCid` are indexed on the ZkEmailInvites entity, so the
+ * allowlist half needs no RPC at all — `resolveZkEmailModule` has already fetched it. Only the
+ * wiring addresses (executor + the four verifier/registry pointers) are unindexed pre-#197, so
+ * they are fetched on demand: pass `withWiring` when the caller actually renders them.
+ *
+ * Pass an existing `provider` to avoid opening a second connection; when omitted and an RPC
+ * read is needed, a JsonRpcProvider is built from resolveNetworkConfig(chainId, env).
+ */
+async function readModuleState(address, orgId, orgName, chainId, provider, opts) {
+    const indexed = opts?.subgraph;
+    // The subgraph stores the CID as a decoded CIDv0 string and the root as Bytes. It is the
+    // authority for both; on-chain reads are only needed when the module is not indexed yet.
+    //
+    // In practice this is always true for the in-repo callers: BOTH tiers of
+    // FETCH_ZKEMAIL_MODULE_TIERS select `activeRoot` (it exists on the Arbitrum pre-#197 schema
+    // too), and resolveZkEmailModule throws before returning a module-less org — so the
+    // merkleRoot()/allowlistCid() pair below never fires today. It is kept because `opts` is
+    // optional on this exported helper: a caller that omits `subgraph` must still get a correct
+    // answer rather than an undefined root.
+    const haveIndexed = indexed != null && indexed.activeRoot !== undefined;
+    let merkleRoot;
+    let allowlistCid;
+    let cidDigest;
+    // Post-#197 the module entity carries the wiring, so `withWiring` needs no RPC either.
+    const indexedHasWiring = indexed != null && indexed.executor !== undefined;
+    const wantsWiring = opts?.withWiring === true || opts?.withDkimRegistry === true;
+    const needsRpc = !haveIndexed || (wantsWiring && !indexedHasWiring);
+    const p = needsRpc
+        ? (provider ?? new ethers_1.ethers.providers.JsonRpcProvider((0, chains_1.resolveNetworkConfig)(chainId, opts?.env).resolvedRpc))
+        : null;
+    const c = p ? (0, contracts_1.createReadContract)(address, 'ZkEmailInvites', p) : null;
+    if (haveIndexed) {
+        merkleRoot = indexed.activeRoot ?? ethers_1.ethers.constants.HashZero;
+        allowlistCid = indexed.activeAllowlistCid ?? null;
+        cidDigest = allowlistCid ? (0, encoding_1.ipfsCidToBytes32)(allowlistCid) : ethers_1.ethers.constants.HashZero;
+    }
+    else {
+        const [root, digest] = await Promise.all([c.merkleRoot(), c.allowlistCid()]);
+        merkleRoot = root;
+        cidDigest = digest;
+        allowlistCid = (0, encoding_1.bytes32ToIpfsCid)(digest);
+    }
+    // Wiring: indexed since subgraph-pop #197, so the six eth_calls below only run against a
+    // deployment that predates it. `dkimRegistry` is an entity reference there, hence the `.id`.
+    //
+    // NOT dead code. Gnosis serves #197, but ARBITRUM (chain 42161) still runs the older
+    // deployment QmYGCS4pXoaqXX7WjaPEhA56kiwgC14z7jsstZzEQgxgUp, whose ZkEmailInvites type is
+    // only {id, organization, activeRoot, activeAllowlistCid, activeAllowlist, createdAt,
+    // lastUpdatedAt} — no executor, no dkimRegistry — so the LEGACY tier is what wins there and
+    // `indexedHasWiring` is false. Verified by introspection 2026-07. Deleting this branch would
+    // break `pop zkemail status --chain 42161` the moment an Arbitrum org installs the module.
+    let executor;
+    let domainVerifier;
+    let emailVerifier;
+    let dkimRegistry;
+    let accountRegistry;
+    let universalFactory;
+    if (indexedHasWiring) {
+        executor = indexed.executor ?? undefined;
+        domainVerifier = indexed.domainVerifier ?? undefined;
+        emailVerifier = indexed.emailVerifier ?? undefined;
+        dkimRegistry = indexed.dkimRegistry?.id ?? undefined;
+        accountRegistry = indexed.accountRegistry ?? undefined;
+        universalFactory = indexed.universalFactory ?? undefined;
+    }
+    else if (opts?.withWiring && c) {
+        [executor, domainVerifier, emailVerifier, dkimRegistry, accountRegistry, universalFactory] =
+            await Promise.all([
+                c.executor(), c.domainVerifier(), c.emailVerifier(),
+                c.dkimRegistry(), c.accountRegistry(), c.universalFactory(),
+            ]);
+    }
+    else if (opts?.withDkimRegistry && c) {
+        // `zkemail check` needs only this one pointer; pulling all six would be five wasted calls.
+        dkimRegistry = await c.dkimRegistry();
+    }
+    return {
+        orgId,
+        orgName,
+        address,
+        merkleRoot,
+        allowlistCidDigest: cidDigest,
+        allowlistCid,
+        dormant: merkleRoot === ethers_1.ethers.constants.HashZero,
+        executor,
+        domainVerifier,
+        emailVerifier,
+        dkimRegistry,
+        accountRegistry,
+        universalFactory,
+        indexedWiring: indexedHasWiring,
+    };
+}
+/**
+ * The indexed active root for an org's module, identity-guarded — the display
+ * read used by `pop zkemail propose-allowlist`
+ * (src/commands/zkemail/propose-allowlist.ts).
+ *
+ * Returns:
+ *   - a root string (HashZero for a dormant module whose row EXISTS), or
+ *   - null when the row is missing / the indexed module id does not match
+ *     `moduleAddress` (a stale org->module pointer must not describe a
+ *     different contract than the one a proposal targets). Callers fall back
+ *     to merkleRoot() on-chain for the null case.
+ */
+async function fetchIndexedActiveRoot(client, orgId, moduleAddress, chainId) {
+    try {
+        const res = await client.query(zkemail_1.FETCH_ZKEMAIL_ACTIVE_ROOT, { orgId }, chainId);
+        const mod = res.organization?.zkEmailInvites;
+        if (!mod?.id || String(mod.id).toLowerCase() !== moduleAddress.toLowerCase())
+            return null;
+        return mod.activeRoot ?? ethers_1.ethers.constants.HashZero;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Claim history for a module, most recent first — the read behind
+ * `pop zkemail claims` (src/commands/zkemail/claims.ts). Indexed since
+ * subgraph-pop #197; on a chain still serving the legacy tier the claim events
+ * were seen but every parameter was discarded, so there is nothing to read —
+ * callers should gate on `indexedWiring` from resolveZkEmailModule like the
+ * CLI does.
+ */
+async function fetchZkEmailClaims(client, moduleAddress, chainId, limit = 50) {
+    const res = await client.query(zkemail_1.FETCH_ZKEMAIL_CLAIMS, { module: moduleAddress.toLowerCase(), first: Math.max(1, Math.min(1000, limit)) }, chainId);
+    return res.zkEmailClaims ?? [];
+}
+/** Map hatId -> role name so allowlists render as "gmail.com -> Member". */
+async function fetchRoleNames(client, orgId, chainId) {
+    const map = new Map();
+    try {
+        const res = await client.query(zkemail_1.FETCH_ORG_ROLE_NAMES, { orgId }, chainId);
+        for (const r of res.organization?.roles ?? []) {
+            if (r.hatId && r.name)
+                map.set(ethers_1.ethers.BigNumber.from(r.hatId).toString(), r.name);
+        }
+    }
+    catch {
+        // Role names are cosmetic — a subgraph hiccup must not fail an allowlist read.
+    }
+    return map;
+}
+/** Render a hat ID as "Member (0x2a)" when the name is known, else the raw id. */
+function labelHat(hatId, names) {
+    const dec = ethers_1.ethers.BigNumber.from(hatId).toString();
+    const name = names.get(dec);
+    return name ? `${name} (${dec})` : dec;
+}
+/** Normalize the subgraph's allowlist entries into a stable shape. */
+function normalizeEntries(allowlist) {
+    return (allowlist?.entries ?? []).map((e) => ({
+        index: Number(e.index),
+        entryType: e.entryType,
+        identifier: e.identifier ?? null,
+        identifierHash: e.identifierHash ?? null,
+        hatIds: (e.hatIds ?? []).map((h) => ethers_1.ethers.BigNumber.from(h).toString()),
+        roleIndexes: (e.roleIndexes ?? []).map((r) => Number(r)),
+    }));
+}

package/dist/similarity.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Text Similarity Utilities
+ * Tokenization + Jaccard similarity used for duplicate detection
+ * (e.g. `pop task create` warns when a similar task title exists).
+ */
+/**
+ * Default stopwords: English filler + common CLI/governance scaffolding words
+ * that carry no signal when comparing task titles.
+ */
+export declare const STOPWORDS: Set<string>;
+/**
+ * Tokenize a string into a set of meaningful lowercase words.
+ * Splits on non-alphanumerics, drops words shorter than `minLen`
+ * (default 4), and filters out stopwords (default STOPWORDS).
+ */
+export declare function tokenize(s: string, opts?: {
+    minLen?: number;
+    stopwords?: Set<string>;
+}): Set<string>;
+/**
+ * Jaccard similarity between two token sets: |intersection| / |union|.
+ * Returns 0 when the union is empty.
+ */
+export declare function jaccard(a: Set<string>, b: Set<string>): number;
+/**
+ * Rank `items` by Jaccard similarity of their text against `queryText`.
+ * Returns matches with score >= threshold (default 0, exclusive of
+ * zero-score items), sorted descending, capped at topN (default all).
+ */
+export declare function bestMatches<T>(queryText: string, items: T[], getText: (t: T) => string, opts?: {
+    threshold?: number;
+    topN?: number;
+}): Array<{
+    item: T;
+    score: number;
+}>;

package/dist/similarity.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * Text Similarity Utilities
+ * Tokenization + Jaccard similarity used for duplicate detection
+ * (e.g. `pop task create` warns when a similar task title exists).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STOPWORDS = void 0;
+exports.tokenize = tokenize;
+exports.jaccard = jaccard;
+exports.bestMatches = bestMatches;
+/**
+ * Default stopwords: English filler + common CLI/governance scaffolding words
+ * that carry no signal when comparing task titles.
+ */
+exports.STOPWORDS = new Set([
+    'the', 'and', 'for', 'with', 'from', 'into', 'onto', 'that', 'this',
+    'task', 'tasks', 'create', 'build', 'make', 'add', 'new', 'fix',
+    'command', 'commands', 'update', 'updates', 'support', 'test',
+    'cli', 'pop', 'org', 'orgs', 'run', 'use', 'using', 'via', 'like',
+    'proposal', 'proposals', 'vote', 'votes', 'write', 'generate',
+]);
+/**
+ * Tokenize a string into a set of meaningful lowercase words.
+ * Splits on non-alphanumerics, drops words shorter than `minLen`
+ * (default 4), and filters out stopwords (default STOPWORDS).
+ */
+function tokenize(s, opts) {
+    const minLen = opts?.minLen ?? 4;
+    const stopwords = opts?.stopwords ?? exports.STOPWORDS;
+    const words = (s || '').toLowerCase().split(/[^a-z0-9]+/).filter(w => w.length >= minLen);
+    return new Set(words.filter(w => !stopwords.has(w)));
+}
+/**
+ * Jaccard similarity between two token sets: |intersection| / |union|.
+ * Returns 0 when the union is empty.
+ */
+function jaccard(a, b) {
+    const union = new Set([...a, ...b]);
+    if (union.size === 0)
+        return 0;
+    let shared = 0;
+    for (const w of a) {
+        if (b.has(w))
+            shared++;
+    }
+    return shared / union.size;
+}
+/**
+ * Rank `items` by Jaccard similarity of their text against `queryText`.
+ * Returns matches with score >= threshold (default 0, exclusive of
+ * zero-score items), sorted descending, capped at topN (default all).
+ */
+function bestMatches(queryText, items, getText, opts) {
+    const threshold = opts?.threshold ?? 0;
+    const topN = opts?.topN ?? items.length;
+    const queryTokens = tokenize(queryText);
+    const scored = [];
+    for (const item of items) {
+        const score = jaccard(queryTokens, tokenize(getText(item)));
+        if (score > 0 && score >= threshold) {
+            scored.push({ item, score });
+        }
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, topN);
+}

package/dist/sponsorship-config.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Sponsorship config resolution (pure, env-injected).
+ *
+ * Kept in its own tiny module — with no viem/permissionless/network deps — so
+ * both the tx layer (which sends sponsored transactions) and preflight logic
+ * (which skips the gas-balance check for sponsored wallets) can import it
+ * without a circular dependency, and so mocking the tx module in a test never
+ * removes this function from preflight's reach.
+ */
+import { EnvSource } from './env';
+/**
+ * Structurally identical to viem's Hex. Declared locally so this module — and
+ * everything that re-exports SponsoredConfig (the root barrel, preflight, the
+ * plain-EOA executor) — never references viem's declarations: viem is an
+ * OPTIONAL peer, and a skipLibCheck:false consumer without it must still
+ * typecheck. Values flow to/from viem's Hex without casts.
+ */
+export type Hex = `0x${string}`;
+export interface SponsoredConfig {
+    privateKey: Hex;
+    orgId: Hex;
+    hatId: bigint;
+}
+/**
+ * Bundler/RPC routing for the sponsored (4337/7702) send path. Lives here —
+ * not in execute/sponsored — for the same optional-peer reason: TxOptions on
+ * the plain-EOA executor references this type, and that executor must not
+ * pull viem-typed declarations into its closure. execute/sponsored re-exports
+ * it, so its historical import path keeps working.
+ */
+export interface SponsoredSendOptions {
+    rpcUrl?: string;
+    value?: bigint;
+    pimlicoApiKey?: string;
+    bundlerUrl?: string;
+}
+/**
+ * Resolve sponsored config from the injected environment. Returns undefined
+ * when any required piece is missing.
+ *
+ * A signing key + org + hat identify the subject; the bundler can be EITHER a
+ * self-hosted endpoint (POP_BUNDLER_URL) OR Pimlico (PIMLICO_API_KEY) — mirror
+ * of sendSponsored(), so a bundler URL alone is a complete setup. Requiring a
+ * Pimlico key here would silently drop self-hosted-bundler users to direct EOA
+ * transactions.
+ */
+export declare function resolveSponsoredConfig(env?: EnvSource): SponsoredConfig | undefined;

package/dist/sponsorship-config.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSponsoredConfig = resolveSponsoredConfig;
+/**
+ * Sponsorship config resolution (pure, env-injected).
+ *
+ * Kept in its own tiny module — with no viem/permissionless/network deps — so
+ * both the tx layer (which sends sponsored transactions) and preflight logic
+ * (which skips the gas-balance check for sponsored wallets) can import it
+ * without a circular dependency, and so mocking the tx module in a test never
+ * removes this function from preflight's reach.
+ */
+const env_1 = require("./env");
+/**
+ * Resolve sponsored config from the injected environment. Returns undefined
+ * when any required piece is missing.
+ *
+ * A signing key + org + hat identify the subject; the bundler can be EITHER a
+ * self-hosted endpoint (POP_BUNDLER_URL) OR Pimlico (PIMLICO_API_KEY) — mirror
+ * of sendSponsored(), so a bundler URL alone is a complete setup. Requiring a
+ * Pimlico key here would silently drop self-hosted-bundler users to direct EOA
+ * transactions.
+ */
+function resolveSponsoredConfig(env = env_1.EMPTY_ENV) {
+    // Read-only mode: sponsorship is a signing capability (userops are signed
+    // with the key) — report "not configured" so no 4337 path ever activates.
+    if (env.POP_READONLY === '1')
+        return undefined;
+    const privateKey = env.POP_PRIVATE_KEY;
+    const orgId = env.POP_ORG_ID;
+    const hatId = env.POP_HAT_ID;
+    const hasBundler = Boolean(env.PIMLICO_API_KEY || env.POP_BUNDLER_URL);
+    if (!privateKey || !orgId || !hatId || !hasBundler) {
+        return undefined;
+    }
+    return {
+        privateKey: (privateKey.startsWith('0x') ? privateKey : `0x${privateKey}`),
+        orgId: orgId,
+        hatId: BigInt(hatId),
+    };
+}

package/dist/stats.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Statistics Utilities
+ * Shared numeric helpers for org analytics commands (audit, health-score).
+ */
+/**
+ * Gini coefficient of a distribution (0 = perfect equality, → 1 = one
+ * holder owns everything). Uses the sorted mean-difference formula:
+ *   G = Σ (2i - n - 1) * x_i / (n * Σ x_i)   with 1-based i over sorted x.
+ * Returns 0 for empty input or when all values sum to 0.
+ */
+export declare function computeGini(values: number[]): number;

package/dist/stats.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * Statistics Utilities
+ * Shared numeric helpers for org analytics commands (audit, health-score).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeGini = computeGini;
+/**
+ * Gini coefficient of a distribution (0 = perfect equality, → 1 = one
+ * holder owns everything). Uses the sorted mean-difference formula:
+ *   G = Σ (2i - n - 1) * x_i / (n * Σ x_i)   with 1-based i over sorted x.
+ * Returns 0 for empty input or when all values sum to 0.
+ */
+function computeGini(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const n = sorted.length;
+    const total = sorted.reduce((s, v) => s + v, 0);
+    if (total === 0)
+        return 0;
+    let numerator = 0;
+    for (let i = 0; i < n; i++) {
+        numerator += (2 * (i + 1) - n - 1) * sorted[i];
+    }
+    return numerator / (n * total);
+}

package/dist/task-lens.d.ts

@@ -0,0 +1,113 @@
+/**
+ * TaskManager Lens Reader
+ * Authoritative on-chain task state via TaskManager.getLensData(uint8,bytes),
+ * bypassing subgraph lag. Key numbering and tuple shapes verified against
+ * contracts repo origin/main src/TaskManager.sol (getLensData dispatcher) and
+ * src/lens/TaskManagerLens.sol (whose getStorage routes through the same
+ * variants).
+ */
+import { ethers } from 'ethers';
+/**
+ * TaskManager.getLensData variant selectors, verified against contracts repo
+ * origin/main src/TaskManager.sol. NOTE: these are NOT the TaskManagerLens.sol
+ * StorageKey enum indexes — that enum keys the lens contract's own
+ * getStorage(); the CLI calls the TaskManager dispatcher directly with the
+ * variant numbers below (TaskManagerLens.sol itself forwards to these).
+ */
+export declare const STORAGE_KEYS: {
+    /** abi.encode(uint256 id) → task tuple (see decodeTaskInfo) */
+    readonly TASK_INFO: 1;
+    /** abi.encode(bytes32 pid) → (uint128 cap, uint128 spent, bool exists) */
+    readonly PROJECT_INFO: 2;
+    /** '' → (address hats) */
+    readonly HATS: 3;
+    /** '' → (address executor) */
+    readonly EXECUTOR: 4;
+    /** '' → (uint256[] hatIds) */
+    readonly CREATOR_HATS: 5;
+    /** '' → (uint256[] hatIds) */
+    readonly PERMISSION_HATS: 6;
+    /** abi.encode(uint256 id) → (address[] applicants) */
+    readonly TASK_APPLICANTS: 7;
+    /** abi.encode(uint256 id, address applicant) → (bytes32 hash) */
+    readonly TASK_APPLICATION: 8;
+    /** abi.encode(bytes32 pid, address token) → (uint128 cap, uint128 spent) */
+    readonly BOUNTY_BUDGET: 9;
+    /** '' → (bytes32 foldersRoot) */
+    readonly FOLDERS_ROOT: 10;
+    /** '' → (uint256[] hatIds) */
+    readonly ORGANIZER_HATS: 11;
+};
+/** Task Status enum (TaskManager.sol). */
+export declare const TASK_STATUS: {
+    readonly UNCLAIMED: 0;
+    readonly CLAIMED: 1;
+    readonly SUBMITTED: 2;
+    readonly COMPLETED: 3;
+    readonly CANCELLED: 4;
+};
+export declare const TASK_STATUS_NAMES: string[];
+export declare function taskStatusName(status: number): string;
+export interface TaskOnChain {
+    projectId: string;
+    payout: ethers.BigNumber;
+    claimer: string;
+    bountyPayout: ethers.BigNumber;
+    requiresApplication: boolean;
+    status: number;
+    bountyToken: string;
+    /** Unix cutoff for any claim (0 = none). Undefined on pre-v6 implementations. */
+    absoluteDeadline?: number;
+    /** Per-claim submission window in seconds (0 = none). Undefined pre-v6. */
+    completionWindow?: number;
+    /** Current claim's deadline, set on claim/assign (0 = none). Undefined pre-v6. */
+    claimDeadline?: number;
+}
+/** Encode a raw eth_call payload for TaskManager.getLensData. */
+export declare function encodeLensCall(key: number, params?: string): string;
+/** Unwrap the `bytes` payload from a raw getLensData return. */
+export declare function decodeLensResult(returnData: string): string;
+/**
+ * Decode the task payload from getLensData variant 1. Tries the v6 10-field
+ * tuple first; pre-v6 payloads are only 7 words, so the v6 decode throws
+ * (out-of-bounds) — fall back to the legacy tuple and leave the deadline
+ * fields undefined.
+ */
+export declare function decodeTaskInfo(data: string): TaskOnChain;
+/**
+ * Read a single task's on-chain state. Accepts plain numeric IDs or
+ * subgraph-format IDs ("contractAddress-taskId").
+ */
+export declare function getTaskOnChain(provider: ethers.providers.Provider, taskManagerAddr: string, taskId: string | number): Promise<TaskOnChain>;
+export interface TaskEnrichmentResult {
+    /** Keyed by the original ID string passed in `ids`. */
+    tasks: Map<string, TaskOnChain>;
+    errors: Array<{
+        id: string;
+        message: string;
+    }>;
+}
+/**
+ * Fetch on-chain state for many tasks with bounded concurrency (default 5,
+ * capped at 50 tasks). Per-task failures are collected, never thrown, so
+ * callers can render partial data.
+ */
+export declare function enrichTasksWithDeadlines(provider: ethers.providers.Provider, taskManagerAddr: string, ids: Array<string | number>, opts?: {
+    concurrency?: number;
+    cap?: number;
+}): Promise<TaskEnrichmentResult>;
+export type ClaimState = 'expired-claimable' | 'expiring-soon' | 'on-track' | 'none';
+/**
+ * Classify a CLAIMED task's deadline state. `claimDeadline` takes precedence
+ * over `absoluteDeadline`; zero/undefined deadlines mean "no deadline".
+ * A deadline strictly in the past means the claim is forfeitable.
+ */
+export declare function deriveClaimState(task: Pick<TaskOnChain, 'status' | 'claimDeadline' | 'absoluteDeadline'>, now?: number): ClaimState;
+/** Read the org's task folders merkle root (getLensData variant 10). */
+export declare function getFoldersRoot(provider: ethers.providers.Provider, taskManagerAddr: string): Promise<string>;
+/** Read organizer hat IDs (getLensData variant 11). */
+export declare function getOrganizerHats(provider: ethers.providers.Provider, taskManagerAddr: string): Promise<ethers.BigNumber[]>;
+/** Read permission hat IDs (getLensData variant 6). */
+export declare function getPermissionHats(provider: ethers.providers.Provider, taskManagerAddr: string): Promise<ethers.BigNumber[]>;
+/** Read a task's applicant addresses (getLensData variant 7). */
+export declare function getTaskApplicants(provider: ethers.providers.Provider, taskManagerAddr: string, taskId: string | number): Promise<string[]>;