@poa-box/core 0.1.0

package/dist/preflight.js

@@ -0,0 +1,269 @@
+"use strict";
+/**
+ * Pre-flight Checks
+ * Read-only validations that run before a write command sends its
+ * transaction, so predictable failures surface as one actionable message
+ * instead of an on-chain revert (or a silent wrong-state write). Contract
+ * reads batch through Multicall3 in a single RPC round-trip; local checks
+ * run concurrently. ALL failures are collected before throwing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPreflight = runPreflight;
+exports.checkGasBalance = checkGasBalance;
+exports.checkHasHat = checkHasHat;
+exports.checkUsernameFree = checkUsernameFree;
+exports.checkTaskStatus = checkTaskStatus;
+exports.checkProposalActive = checkProposalActive;
+const ethers_1 = require("ethers");
+const errors_1 = require("./errors");
+const multicall_1 = require("./multicall");
+const contracts_1 = require("./contracts");
+const format_1 = require("./format");
+const task_lens_1 = require("./task-lens");
+function formatFailure(f) {
+    let line = `  ✗ ${f.label}`;
+    if (f.detail)
+        line += `: ${f.detail}`;
+    if (f.suggestion)
+        line += ` (${f.suggestion})`;
+    return line;
+}
+/**
+ * Run all checks (batched calls + concurrent locals), collect every failure,
+ * and throw a single PreconditionError listing them. `opts.skip` (from a
+ * --skip-checks flag) bypasses everything.
+ */
+async function runPreflight(provider, checks, opts) {
+    if (opts?.skip || checks.length === 0)
+        return;
+    const callIndexes = [];
+    const calls = [];
+    const localIndexes = [];
+    checks.forEach((check, i) => {
+        if (check.call) {
+            callIndexes.push(i);
+            calls.push(check.call);
+        }
+        else if (check.local) {
+            localIndexes.push(i);
+        }
+    });
+    const [callResults, localResults] = await Promise.all([
+        (0, multicall_1.tryAggregate)(provider, calls),
+        Promise.all(localIndexes.map(async (i) => {
+            try {
+                return await checks[i].local();
+            }
+            catch (err) {
+                return { ok: false, detail: err?.message || String(err) };
+            }
+        })),
+    ]);
+    const results = new Array(checks.length);
+    callIndexes.forEach((checkIdx, i) => {
+        const check = checks[checkIdx];
+        const { success, returnData } = callResults[i];
+        try {
+            results[checkIdx] = check.interpret
+                ? check.interpret(returnData, success)
+                : { ok: success, detail: success ? undefined : 'call reverted' };
+        }
+        catch (err) {
+            results[checkIdx] = { ok: false, detail: `could not interpret result: ${err?.message || err}` };
+        }
+    });
+    localIndexes.forEach((checkIdx, i) => {
+        results[checkIdx] = localResults[i];
+    });
+    const failures = [];
+    checks.forEach((check, i) => {
+        const result = results[i];
+        if (result && !result.ok) {
+            failures.push({ label: check.label, detail: result.detail, suggestion: result.suggestion });
+        }
+    });
+    if (failures.length > 0) {
+        throw new errors_1.PreconditionError(`Pre-flight checks failed:\n${failures.map(formatFailure).join('\n')}`);
+    }
+}
+const DEFAULT_MIN_GAS_WEI = ethers_1.ethers.utils.parseEther('0.0001');
+/**
+ * Wallet holds at least `minWei` (default 0.0001 ether) of the chain's
+ * native gas token, read via Multicall3.getEthBalance. Pass the resolved
+ * sponsorship config as `sponsored` to skip the check for sponsored wallets
+ * (the CLI resolves it from env via resolveSponsoredConfig).
+ */
+function checkGasBalance(address, minWei, sponsored) {
+    const min = minWei ?? DEFAULT_MIN_GAS_WEI;
+    // Sponsored writes (EIP-7702 / ERC-4337) don't spend the EOA's own gas, so a
+    // zero balance is expected and fine — the whole point of the "members
+    // transact without ever holding gas" path. When sponsorship is configured,
+    // skip the balance requirement rather than forcing --no-preflight. (If the
+    // EOA isn't actually delegated, executeContractTx falls back to a direct tx
+    // whose own gas estimation surfaces the shortfall with a decoded error.)
+    if (sponsored !== undefined) {
+        return { label: 'gas balance', local: () => ({ ok: true }) };
+    }
+    return {
+        label: 'gas balance',
+        call: (0, multicall_1.getEthBalanceCall)(address),
+        interpret: (returnData, success) => {
+            if (!success || !returnData || returnData === '0x') {
+                return { ok: false, detail: 'could not read wallet balance', suggestion: 'check RPC connectivity' };
+            }
+            const balance = (0, multicall_1.decodeEthBalance)(returnData);
+            if (balance.gte(min))
+                return { ok: true };
+            return {
+                ok: false,
+                detail: `wallet holds ${(0, format_1.formatToken)(balance)} native gas token, below the ${(0, format_1.formatToken)(min)} minimum`,
+                suggestion: `fund ${address} with gas before retrying`,
+            };
+        },
+    };
+}
+const HATS_IFACE = new ethers_1.ethers.utils.Interface([
+    'function balanceOf(address wearer, uint256 hatId) view returns (uint256 balance)',
+]);
+/** Wearer holds the given hat (IHats balanceOf(wearer, hatId) > 0). */
+function checkHasHat(hatsAddress, wearer, hatId) {
+    const id = ethers_1.ethers.BigNumber.from(hatId);
+    return {
+        label: 'role (hat)',
+        call: { to: hatsAddress, data: HATS_IFACE.encodeFunctionData('balanceOf', [wearer, id]) },
+        interpret: (returnData, success) => {
+            if (!success || !returnData || returnData === '0x') {
+                return { ok: false, detail: 'could not read hat balance', suggestion: 'verify the Hats contract address' };
+            }
+            const balance = HATS_IFACE.decodeFunctionResult('balanceOf', returnData)[0];
+            if (!balance.isZero())
+                return { ok: true };
+            return {
+                ok: false,
+                detail: `${wearer} does not wear hat ${id.toString()}`,
+                suggestion: 'list org roles with pop org roles, then request one via pop role apply',
+            };
+        },
+    };
+}
+let uarInterface = null;
+function getUarInterface() {
+    if (!uarInterface) {
+        uarInterface = new ethers_1.ethers.utils.Interface((0, contracts_1.getAbi)('UniversalAccountRegistry'));
+    }
+    return uarInterface;
+}
+/** Username is unregistered (UAR getAddressOfUsername returns the zero address). */
+function checkUsernameFree(registryAddr, username) {
+    return {
+        label: `username "${username}"`,
+        call: {
+            to: registryAddr,
+            data: getUarInterface().encodeFunctionData('getAddressOfUsername', [username]),
+        },
+        interpret: (returnData, success) => {
+            if (!success || !returnData || returnData === '0x') {
+                return { ok: false, detail: 'could not query the account registry', suggestion: 'verify the registry address' };
+            }
+            const holder = getUarInterface().decodeFunctionResult('getAddressOfUsername', returnData)[0];
+            if (holder === ethers_1.ethers.constants.AddressZero)
+                return { ok: true };
+            return {
+                ok: false,
+                detail: `already registered to ${holder}`,
+                suggestion: 'pick a different username',
+            };
+        },
+    };
+}
+/**
+ * Task is in one of `allowedStatuses` (authoritative on-chain read via
+ * TaskManager.getLensData). Options:
+ * - claimerMustBe: task.claimer must equal this address (case-insensitive)
+ * - allowExpiredTakeover: a CLAIMED task outside allowedStatuses still passes
+ *   when its claim deadline has lapsed (deriveClaimState === 'expired-claimable')
+ * - now: injectable unix timestamp for deadline math (tests)
+ */
+function checkTaskStatus(taskManagerAddr, taskId, allowedStatuses, opts) {
+    const id = ethers_1.ethers.BigNumber.from(taskId);
+    return {
+        label: `task ${id.toString()} status`,
+        call: {
+            to: taskManagerAddr,
+            data: (0, task_lens_1.encodeLensCall)(task_lens_1.STORAGE_KEYS.TASK_INFO, ethers_1.ethers.utils.defaultAbiCoder.encode(['uint256'], [id])),
+        },
+        interpret: (returnData, success) => {
+            if (!success || !returnData || returnData === '0x') {
+                return {
+                    ok: false,
+                    detail: 'could not read the task on-chain — it may not exist',
+                    suggestion: 'check the task ID with pop task list',
+                };
+            }
+            let task;
+            try {
+                task = (0, task_lens_1.decodeTaskInfo)((0, task_lens_1.decodeLensResult)(returnData));
+            }
+            catch {
+                return { ok: false, detail: 'could not decode on-chain task data', suggestion: 'check the task ID' };
+            }
+            if (!allowedStatuses.includes(task.status)) {
+                if (opts?.allowExpiredTakeover && task.status === task_lens_1.TASK_STATUS.CLAIMED) {
+                    if ((0, task_lens_1.deriveClaimState)(task, opts.now) === 'expired-claimable') {
+                        return { ok: true, detail: `previous claim by ${task.claimer} expired — takeover allowed` };
+                    }
+                    return {
+                        ok: false,
+                        detail: `claimed by ${task.claimer} and the claim deadline has not passed`,
+                        suggestion: 'wait for the claim to expire or pick another task',
+                    };
+                }
+                return {
+                    ok: false,
+                    detail: `status is ${(0, task_lens_1.taskStatusName)(task.status)}, expected ${allowedStatuses.map(task_lens_1.taskStatusName).join(' or ')}`,
+                    suggestion: 'inspect the task with pop task view',
+                };
+            }
+            if (opts?.claimerMustBe && task.claimer.toLowerCase() !== opts.claimerMustBe.toLowerCase()) {
+                return {
+                    ok: false,
+                    detail: `claimed by ${task.claimer}, not ${opts.claimerMustBe}`,
+                    suggestion: 'only the current claimer can perform this action',
+                };
+            }
+            return { ok: true };
+        },
+    };
+}
+const VOTING_IFACE = new ethers_1.ethers.utils.Interface([
+    'function proposalsCount() view returns (uint256 count)',
+]);
+/**
+ * Proposal ID exists on the voting contract (proposalsCount() > id).
+ *
+ * Kept on RPC on purpose. Counting Proposal/DDVProposal rows in the subgraph
+ * would be semantically equivalent, but it saves nothing and costs something:
+ * this check's `call` rides inside the SAME Multicall3 batch as the gas-balance
+ * check that every write already performs, so dropping it removes zero RPC
+ * round-trips while adding a subgraph round-trip. Worse, the propose→cast
+ * sequence agents run means the proposal is frequently seconds old, and an
+ * un-indexed row would block a perfectly legitimate vote. Net: strictly worse.
+ */
+function checkProposalActive(votingAddr, proposalId) {
+    return {
+        label: `proposal ${proposalId}`,
+        call: { to: votingAddr, data: VOTING_IFACE.encodeFunctionData('proposalsCount') },
+        interpret: (returnData, success) => {
+            if (!success || !returnData || returnData === '0x') {
+                return { ok: false, detail: 'could not read proposalsCount', suggestion: 'verify the voting contract address' };
+            }
+            const count = VOTING_IFACE.decodeFunctionResult('proposalsCount', returnData)[0];
+            if (count.gt(proposalId))
+                return { ok: true };
+            const detail = count.isZero()
+                ? `proposal ${proposalId} does not exist — no proposals have been created yet`
+                : `proposal ${proposalId} does not exist — proposal IDs run 0 to ${count.sub(1).toString()}`;
+            return { ok: false, detail, suggestion: 'list proposals with pop vote list' };
+        },
+    };
+}

package/dist/reads/education.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Education reads — typed wrappers over the education subgraph documents.
+ *
+ * Ports the read layer of:
+ *   - `pop education list`   — src/commands/education/list.ts
+ *   - `pop education update` — src/commands/education/update.ts (read-merge query)
+ *   - `pop education remove` — src/commands/education/remove.ts (title lookup)
+ *
+ * NOTE: the chain stores only {answerHash, payout, exists} per module; title
+ * and contentHash are EVENT-ONLY, so the subgraph is the sole source for
+ * current metadata. A missing row can mean "not indexed yet", not
+ * "nonexistent" — existence is only provable on-chain via getModule
+ * (which reverts ModuleUnknown).
+ */
+import type { GraphClient } from '../graph/client';
+/** Indexed education-module metadata (from the pinned IPFS doc). */
+export interface EducationModuleMetadataRow {
+    description: string | null;
+    link: string | null;
+    quiz: string[] | null;
+    /** JSON-serialized string[][] — parse before use. */
+    answersJson: string | null;
+}
+export interface EducationCompletionRow {
+    learner: string;
+    completedAt: string;
+}
+/** Raw subgraph EducationModule row (`pop education list` field set). */
+export interface EducationModuleRow {
+    id: string;
+    moduleId: string;
+    title: string | null;
+    contentHash: string;
+    metadata: EducationModuleMetadataRow | null;
+    /** PT wei as a decimal string. */
+    payout: string;
+    status: string;
+    createdAt: string;
+    completions: EducationCompletionRow[];
+}
+/** Verbatim from src/commands/education/list.ts. */
+export declare const FETCH_EDUCATION_DATA = "\n  query FetchEducationData($orgId: Bytes!) {\n    organization(id: $orgId) {\n      id\n      educationHub {\n        id\n        modules(first: 50) {\n          id\n          moduleId\n          title\n          contentHash\n          metadata {\n            description\n            link\n            quiz\n            answersJson\n          }\n          payout\n          status\n          createdAt\n          completions {\n            learner\n            completedAt\n          }\n        }\n      }\n    }\n  }\n";
+/**
+ * Same field set as list.ts (schema-safe); title/contentHash for the merge.
+ * Verbatim from src/commands/education/update.ts.
+ */
+export declare const FETCH_MODULES_FOR_UPDATE = "\n  query FetchModulesForUpdate($orgId: Bytes!) {\n    organization(id: $orgId) {\n      id\n      educationHub {\n        id\n        modules(first: 100) {\n          id\n          moduleId\n          title\n          contentHash\n          payout\n          metadata {\n            description\n            link\n            quiz\n            answersJson\n          }\n        }\n      }\n    }\n  }\n";
+/**
+ * Best-effort title lookup so a destructive confirm can name the module.
+ * Verbatim from src/commands/education/remove.ts.
+ */
+export declare const FETCH_MODULE_TITLE = "\n  query FetchModuleTitle($orgId: Bytes!) {\n    organization(id: $orgId) {\n      educationHub {\n        modules(first: 100) {\n          moduleId\n          title\n        }\n      }\n    }\n  }\n";
+/**
+ * Port of the `pop education list` read — src/commands/education/list.ts.
+ * Returns the raw module rows ([] when the org has no education hub or no
+ * modules indexed yet).
+ */
+export declare function listEducationModules(client: GraphClient, orgId: string, chainId?: number): Promise<EducationModuleRow[]>;
+/** Row shape FETCH_MODULES_FOR_UPDATE returns (no status/completions). */
+export interface EducationModuleForUpdateRow {
+    id: string;
+    moduleId: string;
+    title: string | null;
+    contentHash: string;
+    payout: string;
+    metadata: EducationModuleMetadataRow | null;
+}
+/**
+ * The indexed row `pop education update` merges from — null when the module
+ * is not indexed (subgraph lag) OR does not exist; only on-chain getModule
+ * distinguishes the two.
+ */
+export declare function getModuleForUpdate(client: GraphClient, orgId: string, moduleId: string | number, chainId?: number): Promise<EducationModuleForUpdateRow | null>;
+/**
+ * Best-effort module title (`pop education remove` confirm summary).
+ * Returns undefined when not indexed; throws on transport failure — callers
+ * that only want a label should catch.
+ */
+export declare function getModuleTitle(client: GraphClient, orgId: string, moduleId: string | number, chainId?: number): Promise<string | undefined>;

package/dist/reads/education.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * Education reads — typed wrappers over the education subgraph documents.
+ *
+ * Ports the read layer of:
+ *   - `pop education list`   — src/commands/education/list.ts
+ *   - `pop education update` — src/commands/education/update.ts (read-merge query)
+ *   - `pop education remove` — src/commands/education/remove.ts (title lookup)
+ *
+ * NOTE: the chain stores only {answerHash, payout, exists} per module; title
+ * and contentHash are EVENT-ONLY, so the subgraph is the sole source for
+ * current metadata. A missing row can mean "not indexed yet", not
+ * "nonexistent" — existence is only provable on-chain via getModule
+ * (which reverts ModuleUnknown).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FETCH_MODULE_TITLE = exports.FETCH_MODULES_FOR_UPDATE = exports.FETCH_EDUCATION_DATA = void 0;
+exports.listEducationModules = listEducationModules;
+exports.getModuleForUpdate = getModuleForUpdate;
+exports.getModuleTitle = getModuleTitle;
+/** Verbatim from src/commands/education/list.ts. */
+exports.FETCH_EDUCATION_DATA = `
+  query FetchEducationData($orgId: Bytes!) {
+    organization(id: $orgId) {
+      id
+      educationHub {
+        id
+        modules(first: 50) {
+          id
+          moduleId
+          title
+          contentHash
+          metadata {
+            description
+            link
+            quiz
+            answersJson
+          }
+          payout
+          status
+          createdAt
+          completions {
+            learner
+            completedAt
+          }
+        }
+      }
+    }
+  }
+`;
+/**
+ * Same field set as list.ts (schema-safe); title/contentHash for the merge.
+ * Verbatim from src/commands/education/update.ts.
+ */
+exports.FETCH_MODULES_FOR_UPDATE = `
+  query FetchModulesForUpdate($orgId: Bytes!) {
+    organization(id: $orgId) {
+      id
+      educationHub {
+        id
+        modules(first: 100) {
+          id
+          moduleId
+          title
+          contentHash
+          payout
+          metadata {
+            description
+            link
+            quiz
+            answersJson
+          }
+        }
+      }
+    }
+  }
+`;
+/**
+ * Best-effort title lookup so a destructive confirm can name the module.
+ * Verbatim from src/commands/education/remove.ts.
+ */
+exports.FETCH_MODULE_TITLE = `
+  query FetchModuleTitle($orgId: Bytes!) {
+    organization(id: $orgId) {
+      educationHub {
+        modules(first: 100) {
+          moduleId
+          title
+        }
+      }
+    }
+  }
+`;
+/**
+ * Port of the `pop education list` read — src/commands/education/list.ts.
+ * Returns the raw module rows ([] when the org has no education hub or no
+ * modules indexed yet).
+ */
+async function listEducationModules(client, orgId, chainId) {
+    const result = await client.query(exports.FETCH_EDUCATION_DATA, { orgId }, chainId);
+    return result.organization?.educationHub?.modules || [];
+}
+/**
+ * The indexed row `pop education update` merges from — null when the module
+ * is not indexed (subgraph lag) OR does not exist; only on-chain getModule
+ * distinguishes the two.
+ */
+async function getModuleForUpdate(client, orgId, moduleId, chainId) {
+    const result = await client.query(exports.FETCH_MODULES_FOR_UPDATE, { orgId }, chainId);
+    const modules = result.organization?.educationHub?.modules || [];
+    return modules.find((m) => String(m.moduleId) === String(moduleId)) || null;
+}
+/**
+ * Best-effort module title (`pop education remove` confirm summary).
+ * Returns undefined when not indexed; throws on transport failure — callers
+ * that only want a label should catch.
+ */
+async function getModuleTitle(client, orgId, moduleId, chainId) {
+    const result = await client.query(exports.FETCH_MODULE_TITLE, { orgId }, chainId);
+    const modules = result.organization?.educationHub?.modules || [];
+    return modules.find((m) => String(m.moduleId) === String(moduleId))?.title ?? undefined;
+}