@poa-box/core 0.1.0

package/dist/task-lens.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TASK_STATUS_NAMES = exports.TASK_STATUS = exports.STORAGE_KEYS = void 0;
+exports.taskStatusName = taskStatusName;
+exports.encodeLensCall = encodeLensCall;
+exports.decodeLensResult = decodeLensResult;
+exports.decodeTaskInfo = decodeTaskInfo;
+exports.getTaskOnChain = getTaskOnChain;
+exports.enrichTasksWithDeadlines = enrichTasksWithDeadlines;
+exports.deriveClaimState = deriveClaimState;
+exports.getFoldersRoot = getFoldersRoot;
+exports.getOrganizerHats = getOrganizerHats;
+exports.getPermissionHats = getPermissionHats;
+exports.getTaskApplicants = getTaskApplicants;
+const ethers_1 = require("ethers");
+const contracts_1 = require("./contracts");
+const encoding_1 = require("./encoding");
+/**
+ * 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).
+ */
+exports.STORAGE_KEYS = {
+    /** abi.encode(uint256 id) → task tuple (see decodeTaskInfo) */
+    TASK_INFO: 1,
+    /** abi.encode(bytes32 pid) → (uint128 cap, uint128 spent, bool exists) */
+    PROJECT_INFO: 2,
+    /** '' → (address hats) */
+    HATS: 3,
+    /** '' → (address executor) */
+    EXECUTOR: 4,
+    /** '' → (uint256[] hatIds) */
+    CREATOR_HATS: 5,
+    /** '' → (uint256[] hatIds) */
+    PERMISSION_HATS: 6,
+    /** abi.encode(uint256 id) → (address[] applicants) */
+    TASK_APPLICANTS: 7,
+    /** abi.encode(uint256 id, address applicant) → (bytes32 hash) */
+    TASK_APPLICATION: 8,
+    /** abi.encode(bytes32 pid, address token) → (uint128 cap, uint128 spent) */
+    BOUNTY_BUDGET: 9,
+    /** '' → (bytes32 foldersRoot) */
+    FOLDERS_ROOT: 10,
+    /** '' → (uint256[] hatIds) */
+    ORGANIZER_HATS: 11,
+};
+/** Task Status enum (TaskManager.sol). */
+exports.TASK_STATUS = {
+    UNCLAIMED: 0,
+    CLAIMED: 1,
+    SUBMITTED: 2,
+    COMPLETED: 3,
+    CANCELLED: 4,
+};
+exports.TASK_STATUS_NAMES = ['UNCLAIMED', 'CLAIMED', 'SUBMITTED', 'COMPLETED', 'CANCELLED'];
+function taskStatusName(status) {
+    return exports.TASK_STATUS_NAMES[status] ?? `UNKNOWN(${status})`;
+}
+/**
+ * v6 task tuple returned by getLensData variant 1 (10 static fields).
+ * Pre-v6 implementations return only the first 7 (no deadline words).
+ */
+const TASK_TUPLE_V6 = ['bytes32', 'uint96', 'address', 'uint96', 'bool', 'uint8', 'address', 'uint48', 'uint32', 'uint48'];
+const TASK_TUPLE_LEGACY = ['bytes32', 'uint96', 'address', 'uint96', 'bool', 'uint8', 'address'];
+let lensInterface = null;
+/** Minimal Interface holding just getLensData from the synced TaskManagerNew ABI. */
+function getLensInterface() {
+    if (!lensInterface) {
+        const fragment = (0, contracts_1.loadAbi)('TaskManagerNew').find((f) => f.type === 'function' && f.name === 'getLensData');
+        if (!fragment) {
+            throw new Error('getLensData not found in TaskManagerNew ABI. Run yarn sync-abis.');
+        }
+        lensInterface = new ethers_1.ethers.utils.Interface([fragment]);
+    }
+    return lensInterface;
+}
+/** Encode a raw eth_call payload for TaskManager.getLensData. */
+function encodeLensCall(key, params = '0x') {
+    return getLensInterface().encodeFunctionData('getLensData', [key, params]);
+}
+/** Unwrap the `bytes` payload from a raw getLensData return. */
+function decodeLensResult(returnData) {
+    return getLensInterface().decodeFunctionResult('getLensData', returnData)[0];
+}
+async function callLens(provider, taskManagerAddr, key, params = '0x') {
+    const raw = await provider.call({ to: taskManagerAddr, data: encodeLensCall(key, params) });
+    return decodeLensResult(raw);
+}
+function asNumber(value) {
+    return typeof value === 'number' ? value : ethers_1.ethers.BigNumber.from(value).toNumber();
+}
+/**
+ * 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.
+ */
+function decodeTaskInfo(data) {
+    try {
+        const d = ethers_1.ethers.utils.defaultAbiCoder.decode(TASK_TUPLE_V6, data);
+        return {
+            projectId: d[0],
+            payout: d[1],
+            claimer: d[2],
+            bountyPayout: d[3],
+            requiresApplication: d[4],
+            status: asNumber(d[5]),
+            bountyToken: d[6],
+            absoluteDeadline: asNumber(d[7]),
+            completionWindow: asNumber(d[8]),
+            claimDeadline: asNumber(d[9]),
+        };
+    }
+    catch {
+        const d = ethers_1.ethers.utils.defaultAbiCoder.decode(TASK_TUPLE_LEGACY, data);
+        return {
+            projectId: d[0],
+            payout: d[1],
+            claimer: d[2],
+            bountyPayout: d[3],
+            requiresApplication: d[4],
+            status: asNumber(d[5]),
+            bountyToken: d[6],
+        };
+    }
+}
+/**
+ * Read a single task's on-chain state. Accepts plain numeric IDs or
+ * subgraph-format IDs ("contractAddress-taskId").
+ */
+async function getTaskOnChain(provider, taskManagerAddr, taskId) {
+    const params = ethers_1.ethers.utils.defaultAbiCoder.encode(['uint256'], [(0, encoding_1.parseTaskId)(taskId)]);
+    const payload = await callLens(provider, taskManagerAddr, exports.STORAGE_KEYS.TASK_INFO, params);
+    return decodeTaskInfo(payload);
+}
+/**
+ * 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.
+ */
+async function enrichTasksWithDeadlines(provider, taskManagerAddr, ids, opts) {
+    const concurrency = Math.max(1, opts?.concurrency ?? 5);
+    const cap = opts?.cap ?? 50;
+    const capped = ids.slice(0, cap);
+    const tasks = new Map();
+    const errors = [];
+    for (let i = 0; i < capped.length; i += concurrency) {
+        const chunk = capped.slice(i, i + concurrency);
+        await Promise.all(chunk.map(async (id) => {
+            const key = String(id);
+            try {
+                tasks.set(key, await getTaskOnChain(provider, taskManagerAddr, id));
+            }
+            catch (err) {
+                errors.push({ id: key, message: err?.message || String(err) });
+            }
+        }));
+    }
+    return { tasks, errors };
+}
+const EXPIRING_SOON_WINDOW_SECONDS = 24 * 60 * 60;
+/**
+ * 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.
+ */
+function deriveClaimState(task, now) {
+    if (task.status !== exports.TASK_STATUS.CLAIMED)
+        return 'none';
+    const deadline = task.claimDeadline || task.absoluteDeadline;
+    if (!deadline)
+        return 'none';
+    const ts = now ?? Math.floor(Date.now() / 1000);
+    if (deadline < ts)
+        return 'expired-claimable';
+    if (deadline <= ts + EXPIRING_SOON_WINDOW_SECONDS)
+        return 'expiring-soon';
+    return 'on-track';
+}
+/** Read the org's task folders merkle root (getLensData variant 10). */
+async function getFoldersRoot(provider, taskManagerAddr) {
+    const payload = await callLens(provider, taskManagerAddr, exports.STORAGE_KEYS.FOLDERS_ROOT);
+    return ethers_1.ethers.utils.defaultAbiCoder.decode(['bytes32'], payload)[0];
+}
+/** Read organizer hat IDs (getLensData variant 11). */
+async function getOrganizerHats(provider, taskManagerAddr) {
+    const payload = await callLens(provider, taskManagerAddr, exports.STORAGE_KEYS.ORGANIZER_HATS);
+    return ethers_1.ethers.utils.defaultAbiCoder.decode(['uint256[]'], payload)[0];
+}
+/** Read permission hat IDs (getLensData variant 6). */
+async function getPermissionHats(provider, taskManagerAddr) {
+    const payload = await callLens(provider, taskManagerAddr, exports.STORAGE_KEYS.PERMISSION_HATS);
+    return ethers_1.ethers.utils.defaultAbiCoder.decode(['uint256[]'], payload)[0];
+}
+/** Read a task's applicant addresses (getLensData variant 7). */
+async function getTaskApplicants(provider, taskManagerAddr, taskId) {
+    const params = ethers_1.ethers.utils.defaultAbiCoder.encode(['uint256'], [(0, encoding_1.parseTaskId)(taskId)]);
+    const payload = await callLens(provider, taskManagerAddr, exports.STORAGE_KEYS.TASK_APPLICANTS, params);
+    return ethers_1.ethers.utils.defaultAbiCoder.decode(['address[]'], payload)[0];
+}

package/dist/tx/education.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Education write builders.
+ *
+ * Ports:
+ *   - `pop education create`   — src/commands/education/create-module.ts
+ *   - `pop education complete` — src/commands/education/complete.ts
+ *   - `pop education update`   — src/commands/education/update.ts
+ *   - `pop education remove`   — src/commands/education/remove.ts
+ *
+ * EducationHub facts (verified contracts origin/main src/EducationHub.sol):
+ *   - createModule hashes the correct answer into the module PERMANENTLY —
+ *     updateModule never touches answerHash, so changing quiz content cannot
+ *     change which answer index passes (remove + recreate to change it).
+ *   - updateModule is a FULL OVERWRITE of title + contentHash + payout.
+ *   - removeModule is a permanent delete with no undo.
+ *   - The chain stores only {answerHash, payout, exists}; module metadata is
+ *     event-only, so preservation reads go through the subgraph/IPFS.
+ */
+import { ethers } from 'ethers';
+import type { TxIntent } from './intent';
+import type { PopContext } from '../context';
+export interface CreateModuleArgs {
+    educationHubAddress: string;
+    /** Module title (encoded with stringToBytes). */
+    name: string;
+    /** bytes32 of the pinned module metadata CID. */
+    contentHash: string;
+    /** PT reward in whole tokens — encoded parseUnits(String(payout), 18) like the CLI. */
+    payout: number | string;
+    /** Index of the correct answer (0-255) — PERMANENT after creation. */
+    correctAnswer: number;
+    orgId?: string;
+}
+/**
+ * Port of `pop education create` — src/commands/education/create-module.ts.
+ * EducationHubNew.createModule(stringToBytes(name), contentHash,
+ * payoutWei(18d), correctAnswer uint8). Validates payout > 0 (the contract
+ * reverts InvalidPayout for 0) and correctAnswer 0-255, same messages as the
+ * CLI.
+ */
+export declare function buildCreateModule(a: CreateModuleArgs): TxIntent;
+export interface CompleteModuleArgs {
+    educationHubAddress: string;
+    /** Module ID — accepts the subgraph "address-id" form (parseModuleId). */
+    moduleId: string | number;
+    /** Answer index (0-based). Wrong answers are only knowable on-chain (InvalidAnswer). */
+    answer: number;
+    orgId?: string;
+}
+/**
+ * Port of `pop education complete` — src/commands/education/complete.ts.
+ * EducationHubNew.completeModule(moduleId, answer uint8) — pays PT once per
+ * account (reverts AlreadyCompleted on a second attempt, ModuleUnknown for
+ * missing modules). Validates answer 0-255, same message as the CLI.
+ */
+export declare function buildCompleteModule(a: CompleteModuleArgs): TxIntent;
+export interface UpdateModuleArgs {
+    educationHubAddress: string;
+    /** Module ID — accepts the subgraph "address-id" form (parseModuleId). */
+    moduleId: string | number;
+    /** FULL replacement title (updateModule overwrites it even when unchanged). */
+    name: string;
+    /** FULL replacement contentHash (pass the current one to keep metadata). */
+    contentHash: string;
+    /**
+     * FULL replacement payout in PT WEI (BigNumber), not whole tokens — the
+     * resolved builder writes back the on-chain value when unchanged, so this
+     * stays in wei end-to-end (unlike createModule, where the CLI parses a
+     * whole-token number).
+     */
+    payoutWei: ethers.BigNumberish;
+    orgId?: string;
+}
+/**
+ * Port of `pop education update` — src/commands/education/update.ts.
+ * EducationHubNew.updateModule(id, stringToBytes(name), contentHash,
+ * payoutWei) — full overwrite of title + contentHash + payout; the answer
+ * hash is IMMUTABLE.
+ */
+export declare function buildUpdateModule(a: UpdateModuleArgs): TxIntent;
+export interface RemoveModuleArgs {
+    educationHubAddress: string;
+    /** Module ID — accepts the subgraph "address-id" form (parseModuleId). */
+    moduleId: string | number;
+    orgId?: string;
+    /** Display-only module title for confirmation UIs. */
+    title?: string;
+}
+/**
+ * Port of `pop education remove` — src/commands/education/remove.ts.
+ * EducationHubNew.removeModule(moduleId) — PERMANENT delete, no undo; past
+ * completions keep their minted PT but the module disappears for everyone.
+ */
+export declare function buildRemoveModule(a: RemoveModuleArgs): TxIntent;
+export interface CreateModuleParams {
+    /** Org name or 0x id. */
+    org: string;
+    name: string;
+    description?: string;
+    link?: string;
+    payout: number | string;
+    quiz?: string[];
+    answers?: string[][];
+    correctAnswer: number;
+}
+/**
+ * Resolved builder for `pop education create` — src/commands/education/create-module.ts.
+ * Resolves the org's EducationHub, pins the module metadata
+ * ({name, description, link, quiz, answers} — key order load-bearing), and
+ * delegates to buildCreateModule.
+ */
+export declare function createModuleIntent(ctx: PopContext, params: CreateModuleParams): Promise<TxIntent>;
+export interface CompleteModuleParams {
+    /** Org name or 0x id. */
+    org: string;
+    /** Module ID. */
+    module: string | number;
+    /** Answer index (0-based). */
+    answer: number;
+}
+/**
+ * Resolved builder for `pop education complete` — src/commands/education/complete.ts.
+ * Resolves the org's EducationHub and delegates to buildCompleteModule. The
+ * CLI's pre-flight (module exists via getModule, not-already-completed via
+ * hasCompleted) is a host concern — see checkModuleExists/checkNotCompleted
+ * in the CLI's education helpers.
+ */
+export declare function completeModuleIntent(ctx: PopContext, params: CompleteModuleParams): Promise<TxIntent>;
+export interface UpdateModuleParams {
+    /** Org name or 0x id. */
+    org: string;
+    /** Module ID. */
+    module: string | number;
+    /** New PT reward in whole tokens (must be > 0). Omit to preserve. */
+    payout?: number;
+    name?: string;
+    description?: string;
+    link?: string;
+    quiz?: string[];
+    answers?: string[][];
+}
+/**
+ * Resolved builder for `pop education update` — src/commands/education/update.ts.
+ *
+ * READ-MERGE issued concurrently (Promise.allSettled): payout + existence
+ * from on-chain getModule — deliberately NOT the indexed payout, because a
+ * full overwrite writes the read-back value and a stale one would silently
+ * ROLL BACK a concurrent raise; the same call is the ModuleUnknown existence
+ * gate. Title/metadata come from FETCH_MODULES_FOR_UPDATE (the chain stores
+ * only {answerHash, payout, exists} — metadata is event-only) with an IPFS
+ * fallback. Metadata is re-pinned ONLY when its content actually changes —
+ * same key order as create ({name, description, link, quiz, answers}).
+ *
+ * Requires ctx.provider (the on-chain getModule read).
+ */
+export declare function updateModuleIntent(ctx: PopContext, params: UpdateModuleParams): Promise<TxIntent>;
+export interface RemoveModuleParams {
+    /** Org name or 0x id. */
+    org: string;
+    /** Module ID to remove (permanent — no undo). */
+    module: string | number;
+}
+/**
+ * Resolved builder for `pop education remove` — src/commands/education/remove.ts.
+ * Resolves the org's EducationHub, fetches a best-effort title for the
+ * confirmation summary (subgraph may lag — never blocks), and delegates to
+ * buildRemoveModule. DESTRUCTIVE: hosts should require explicit confirmation.
+ */
+export declare function removeModuleIntent(ctx: PopContext, params: RemoveModuleParams): Promise<TxIntent>;