@poa-box/core 0.1.0

package/dist/tx/education.js

@@ -0,0 +1,344 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCreateModule = buildCreateModule;
+exports.buildCompleteModule = buildCompleteModule;
+exports.buildUpdateModule = buildUpdateModule;
+exports.buildRemoveModule = buildRemoveModule;
+exports.createModuleIntent = createModuleIntent;
+exports.completeModuleIntent = completeModuleIntent;
+exports.updateModuleIntent = updateModuleIntent;
+exports.removeModuleIntent = removeModuleIntent;
+const ethers_1 = require("ethers");
+const contracts_1 = require("../contracts");
+const encoding_1 = require("../encoding");
+const ipfs_1 = require("../ipfs");
+const errors_1 = require("../errors");
+const exit_codes_1 = require("../exit-codes");
+const resolve_1 = require("../reads/resolve");
+const education_1 = require("../metadata/education");
+const education_2 = require("../reads/education");
+/**
+ * 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.
+ */
+function buildCreateModule(a) {
+    const payoutNum = Number(a.payout);
+    if (!(payoutNum > 0) || !isFinite(payoutNum)) {
+        throw new errors_1.CliError(`--payout must be a positive number (the contract reverts InvalidPayout for 0), got: ${a.payout}`, exit_codes_1.EXIT.USAGE);
+    }
+    if (!Number.isInteger(a.correctAnswer) || a.correctAnswer < 0 || a.correctAnswer > 255) {
+        throw new errors_1.CliError(`--correct-answer must be an integer 0-255 (uint8), got: ${a.correctAnswer}`, exit_codes_1.EXIT.USAGE);
+    }
+    const titleBytes = (0, encoding_1.stringToBytes)(a.name);
+    const payoutWei = ethers_1.ethers.utils.parseUnits(a.payout.toString(), 18);
+    return {
+        to: a.educationHubAddress,
+        abi: (0, contracts_1.getAbi)('EducationHubNew'),
+        method: 'createModule',
+        args: [titleBytes, a.contentHash, payoutWei, a.correctAnswer],
+        meta: {
+            domain: 'education',
+            action: 'create-module',
+            orgId: a.orgId,
+            summary: {
+                name: a.name,
+                payout: `${a.payout} PT`,
+                correctAnswer: `index ${a.correctAnswer} (permanent)`,
+            },
+        },
+    };
+}
+/**
+ * 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.
+ */
+function buildCompleteModule(a) {
+    if (!Number.isInteger(a.answer) || a.answer < 0 || a.answer > 255) {
+        throw new errors_1.CliError(`--answer must be an integer 0-255 (uint8), got: ${a.answer}`, exit_codes_1.EXIT.USAGE);
+    }
+    const moduleId = (0, encoding_1.parseModuleId)(a.moduleId);
+    return {
+        to: a.educationHubAddress,
+        abi: (0, contracts_1.getAbi)('EducationHubNew'),
+        method: 'completeModule',
+        args: [moduleId, a.answer],
+        meta: {
+            domain: 'education',
+            action: 'complete',
+            orgId: a.orgId,
+            summary: { moduleId, answer: `index ${a.answer}` },
+        },
+    };
+}
+/**
+ * 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.
+ */
+function buildUpdateModule(a) {
+    const moduleId = (0, encoding_1.parseModuleId)(a.moduleId);
+    return {
+        to: a.educationHubAddress,
+        abi: (0, contracts_1.getAbi)('EducationHubNew'),
+        method: 'updateModule',
+        args: [moduleId, (0, encoding_1.stringToBytes)(a.name), a.contentHash, a.payoutWei],
+        meta: {
+            domain: 'education',
+            action: 'update',
+            orgId: a.orgId,
+            summary: { moduleId, title: a.name },
+        },
+    };
+}
+/**
+ * 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.
+ */
+function buildRemoveModule(a) {
+    const moduleId = (0, encoding_1.parseModuleId)(a.moduleId);
+    return {
+        to: a.educationHubAddress,
+        abi: (0, contracts_1.getAbi)('EducationHubNew'),
+        method: 'removeModule',
+        args: [moduleId],
+        meta: {
+            domain: 'education',
+            action: 'remove',
+            orgId: a.orgId,
+            summary: {
+                module: a.title ? `#${moduleId} — ${a.title}` : `#${moduleId}`,
+                warning: 'permanent removal — no undo; the module and its payout disappear for everyone',
+            },
+        },
+    };
+}
+/**
+ * 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.
+ */
+async function createModuleIntent(ctx, params) {
+    const quiz = params.quiz || [];
+    const answers = params.answers || [];
+    if (quiz.length > 0 && answers.length > 0 && quiz.length !== answers.length) {
+        throw new errors_1.CliError(`Quiz has ${quiz.length} questions but ${answers.length} answer sets. They must match.`, exit_codes_1.EXIT.USAGE);
+    }
+    const modules = await (0, resolve_1.resolveOrgModules)(ctx.client, params.org, ctx.chainId);
+    const educationHubAddress = (0, resolve_1.requireModule)(modules, 'educationHubAddress');
+    const metadata = (0, education_1.buildEducationModuleMetadata)({
+        name: params.name,
+        description: params.description,
+        link: params.link,
+        quiz,
+        answers,
+    });
+    const cid = await (0, ipfs_1.pinJson)((0, education_1.serializeEducationModuleMetadata)(metadata), ctx.ipfs);
+    const contentHash = (0, encoding_1.ipfsCidToBytes32)(cid);
+    const intent = buildCreateModule({
+        educationHubAddress,
+        name: params.name,
+        contentHash,
+        payout: params.payout,
+        correctAnswer: params.correctAnswer,
+        orgId: modules.orgId,
+    });
+    intent.meta.ipfs = { cid, metadata };
+    return intent;
+}
+/**
+ * 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.
+ */
+async function completeModuleIntent(ctx, params) {
+    const modules = await (0, resolve_1.resolveOrgModules)(ctx.client, params.org, ctx.chainId);
+    const educationHubAddress = (0, resolve_1.requireModule)(modules, 'educationHubAddress');
+    return buildCompleteModule({
+        educationHubAddress,
+        moduleId: params.module,
+        answer: params.answer,
+        orgId: modules.orgId,
+    });
+}
+/**
+ * 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).
+ */
+async function updateModuleIntent(ctx, params) {
+    // ── 0. Fail fast on input problems before any network work ─────────
+    const metadataChanging = params.name !== undefined
+        || params.description !== undefined
+        || params.link !== undefined
+        || params.quiz !== undefined
+        || params.answers !== undefined;
+    const payoutChanging = params.payout !== undefined;
+    if (!metadataChanging && !payoutChanging) {
+        throw new errors_1.CliError('Nothing to update — pass at least one field flag.', exit_codes_1.EXIT.USAGE, 'Available: --payout, --name, --description, --link, --quiz, --answers');
+    }
+    if (payoutChanging && (!(params.payout > 0) || !isFinite(params.payout))) {
+        throw new errors_1.CliError(`--payout must be a positive number (the contract reverts InvalidPayout for 0), got: ${params.payout}`, exit_codes_1.EXIT.USAGE);
+    }
+    if (!ctx.provider) {
+        throw new errors_1.CliError('updateModuleIntent requires ctx.provider (on-chain getModule read — see the payout note above)', exit_codes_1.EXIT.USAGE);
+    }
+    const modules = await (0, resolve_1.resolveOrgModules)(ctx.client, params.org, ctx.chainId);
+    const educationHubAddress = (0, resolve_1.requireModule)(modules, 'educationHubAddress');
+    const moduleId = (0, encoding_1.parseModuleId)(params.module);
+    // ── 1+2. READ: on-chain payout/existence AND the indexed metadata ──
+    const hub = (0, contracts_1.createReadContract)(educationHubAddress, 'EducationHubNew', ctx.provider);
+    const [chainRead, indexedRead] = await Promise.allSettled([
+        hub.getModule(moduleId),
+        ctx.client.query(education_2.FETCH_MODULES_FOR_UPDATE, { orgId: modules.orgId }, ctx.chainId),
+    ]);
+    if (chainRead.status === 'rejected') {
+        throw new errors_1.PreconditionError(`Could not read module ${moduleId} on-chain — it may not exist (getModule reverts ModuleUnknown).`, 'List modules with: pop education list');
+    }
+    const currentPayout = chainRead.value[0];
+    // Subgraph unavailable — handled below based on what the merge needs.
+    let subgraphModule = null;
+    if (indexedRead.status === 'fulfilled') {
+        const rows = indexedRead.value.organization?.educationHub?.modules || [];
+        subgraphModule = rows.find((m) => String(m.moduleId) === String(moduleId)) || null;
+    }
+    let ipfsMetadata = null;
+    const currentCid = subgraphModule?.contentHash ? (0, encoding_1.bytes32ToIpfsCid)(subgraphModule.contentHash) : null;
+    if (currentCid) {
+        try {
+            ipfsMetadata = await (0, ipfs_1.fetchJson)(currentCid, ctx.ipfs);
+        }
+        catch { /* IPFS lag — fall back to subgraph fields */ }
+    }
+    const currentName = ipfsMetadata?.name ?? subgraphModule?.title ?? undefined;
+    const currentDescription = ipfsMetadata?.description ?? subgraphModule?.metadata?.description ?? undefined;
+    const currentLink = ipfsMetadata?.link ?? subgraphModule?.metadata?.link ?? undefined;
+    const currentQuiz = ipfsMetadata?.quiz ?? subgraphModule?.metadata?.quiz ?? undefined;
+    let currentAnswers = ipfsMetadata?.answers;
+    if (currentAnswers === undefined && subgraphModule?.metadata?.answersJson) {
+        try {
+            currentAnswers = JSON.parse(subgraphModule.metadata.answersJson);
+        }
+        catch { /* unparseable — treated as unknown */ }
+    }
+    const currentContentHash = subgraphModule?.contentHash ?? undefined;
+    // updateModule overwrites title + contentHash even when only payout
+    // changed — so the current values must be recoverable.
+    if (!metadataChanging && (currentName === undefined || !currentContentHash)) {
+        throw new errors_1.CliError(`Module ${moduleId} metadata is not indexed yet (subgraph lag) — cannot preserve the current title/metadata through a full-overwrite update.`, exit_codes_1.EXIT.INFRA, 'Retry in a few seconds, or pass --name and --description explicitly.');
+    }
+    if (metadataChanging
+        && (params.name === undefined || params.description === undefined)
+        && (currentName === undefined || currentDescription === undefined)) {
+        throw new errors_1.CliError(`Module ${moduleId} metadata is not indexed yet (subgraph lag) — cannot merge a partial metadata edit.`, exit_codes_1.EXIT.INFRA, 'Retry in a few seconds, or pass BOTH --name and --description.');
+    }
+    // ── 3. MERGE: passed fields override, everything else preserved ────
+    const finalPayout = payoutChanging
+        ? ethers_1.ethers.utils.parseUnits(params.payout.toString(), 18)
+        : currentPayout;
+    const finalName = params.name ?? currentName ?? '';
+    const finalDescription = params.description ?? currentDescription ?? '';
+    const finalLink = params.link ?? currentLink ?? '';
+    const finalQuiz = params.quiz ?? currentQuiz ?? [];
+    const finalAnswers = params.answers ?? currentAnswers ?? [];
+    if (finalQuiz.length > 0 && finalAnswers.length > 0 && finalQuiz.length !== finalAnswers.length) {
+        throw new errors_1.CliError(`Quiz has ${finalQuiz.length} questions but ${finalAnswers.length} answer sets. They must match.`, exit_codes_1.EXIT.USAGE);
+    }
+    // Re-pin only when the metadata content actually changes.
+    let finalContentHash = currentContentHash
+        ? currentContentHash
+        : ethers_1.ethers.constants.HashZero;
+    let newCid;
+    let metadataDoc;
+    const metadataActuallyChanged = metadataChanging && (finalName !== currentName
+        || finalDescription !== (currentDescription ?? '')
+        || finalLink !== (currentLink ?? '')
+        || JSON.stringify(finalQuiz) !== JSON.stringify(currentQuiz ?? [])
+        || JSON.stringify(finalAnswers) !== JSON.stringify(currentAnswers ?? []));
+    if (metadataActuallyChanged) {
+        // NOTE (CLI warns here): when neither IPFS nor the subgraph could supply
+        // the current metadata, unspecified fields reset to defaults in the
+        // re-pinned JSON.
+        // Key order MUST match metadata/education.ts (frontend/subgraph parity).
+        metadataDoc = (0, education_1.buildEducationModuleMetadata)({
+            name: finalName,
+            description: finalDescription,
+            link: finalLink,
+            quiz: finalQuiz,
+            answers: finalAnswers,
+        });
+        newCid = await (0, ipfs_1.pinJson)((0, education_1.serializeEducationModuleMetadata)(metadataDoc), ctx.ipfs);
+        finalContentHash = (0, encoding_1.ipfsCidToBytes32)(newCid);
+    }
+    const intent = buildUpdateModule({
+        educationHubAddress,
+        moduleId,
+        name: finalName,
+        contentHash: finalContentHash,
+        payoutWei: finalPayout,
+        orgId: modules.orgId,
+    });
+    intent.meta.summary.metadataChanged = metadataActuallyChanged;
+    if (newCid)
+        intent.meta.ipfs = { cid: newCid, metadata: metadataDoc };
+    return intent;
+}
+/**
+ * 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.
+ */
+async function removeModuleIntent(ctx, params) {
+    const modules = await (0, resolve_1.resolveOrgModules)(ctx.client, params.org, ctx.chainId);
+    const educationHubAddress = (0, resolve_1.requireModule)(modules, 'educationHubAddress');
+    const moduleId = (0, encoding_1.parseModuleId)(params.module);
+    // Best-effort title for the confirmation summary (subgraph may lag).
+    let title;
+    try {
+        title = await (0, education_2.getModuleTitle)(ctx.client, modules.orgId, moduleId, ctx.chainId);
+    }
+    catch { /* confirm falls back to the bare ID */ }
+    return buildRemoveModule({
+        educationHubAddress,
+        moduleId,
+        orgId: modules.orgId,
+        title,
+    });
+}