@poa-box/core 0.1.0

package/dist/tx/token.d.ts

@@ -0,0 +1,96 @@
+/**
+ * ParticipationToken write builders — token request / approve / cancel.
+ *
+ * Level 1: pure, sync builders that take resolved addresses + fully-prepared
+ * values and return a TxIntent. Level 2: async `<action>Intent(ctx, params)`
+ * builders that resolve the org's token address via the subgraph and pin the
+ * request metadata to IPFS, then delegate to Level 1 — replicating exactly
+ * what the CLI commands do before executeTx.
+ *
+ * Preflight (hat gates, requests(id) existence/state probes) is NOT ported:
+ * those are provider-bound revert predictors that stay in the CLI
+ * (src/commands/token/helpers.ts documents why they must stay on RPC).
+ */
+import { ethers } from 'ethers';
+import type { TxIntent } from './intent';
+import type { PopContext } from '../context';
+/**
+ * Parse a PT amount to 18-decimal wei, enforcing the contract's uint96 bound.
+ * Port of parseRequestAmount in `pop token request` —
+ * src/commands/token/request.ts (same messages and exit codes).
+ */
+export declare function parseRequestAmount(amount: number | string): ethers.BigNumber;
+export interface RequestTokensArgs {
+    participationTokenAddress: string;
+    /** 18-decimal wei, bounded to uint96 (see parseRequestAmount). */
+    amountWei: ethers.BigNumberish;
+    /** IPFS CID of the pinned {reason, submittedAt} document — the CID STRING, not bytes32. */
+    ipfsHash: string;
+    orgId?: string;
+}
+/**
+ * Port of `pop token request` — src/commands/token/request.ts.
+ * ParticipationToken.requestTokens(uint96 amount, string ipfsHash): amount in
+ * 18 decimals, ipfsHash as the CID string (not bytes32). isMember-gated
+ * on-chain (executor or any allowed member hat); reverts ZeroAmount on a zero
+ * amount or empty ipfsHash. Emits Requested(id) — parse receipt logs for the
+ * request id.
+ */
+export declare function buildRequestTokens(a: RequestTokensArgs): TxIntent;
+export interface ApproveTokenRequestArgs {
+    participationTokenAddress: string;
+    /** Numeric request id (`pop token requests`). */
+    requestId: ethers.BigNumberish;
+    orgId?: string;
+}
+/**
+ * Port of `pop token approve` — src/commands/token/approve.ts.
+ * ParticipationToken.approveRequest(uint256 id) — DESTRUCTIVE: mints the
+ * requested PT straight to the requester, irreversibly. onlyApprover
+ * (executor or any allowed approver hat); reverts RequestUnknown /
+ * AlreadyApproved, and NotRequester when the approver IS the requester.
+ */
+export declare function buildApproveRequest(a: ApproveTokenRequestArgs): TxIntent;
+/**
+ * Port of `pop token cancel` — src/commands/token/cancel.ts.
+ * ParticipationToken.cancelRequest(uint256 id) — callable by the REQUESTER or
+ * any APPROVER; reverts RequestUnknown for missing ids, AlreadyApproved once
+ * minted, NotApprover for everyone else.
+ */
+export declare function buildCancelRequest(a: ApproveTokenRequestArgs): TxIntent;
+export interface RequestTokensParams {
+    /** Org name or hex ID. */
+    org: string;
+    /** Decimal PT amount, e.g. 12.5 (parsed with parseRequestAmount). */
+    amount: number | string;
+    /** Reason pinned to IPFS as {reason, submittedAt}. */
+    reason: string;
+    /** Override the metadata timestamp (defaults to Date.now(), as the CLI). */
+    submittedAt?: number;
+}
+/**
+ * Resolved builder for `pop token request` — src/commands/token/request.ts.
+ * Validates amount/reason with the CLI's exact errors, resolves the org's
+ * ParticipationToken via the subgraph, pins {reason, submittedAt} to IPFS
+ * (exact key order), then builds the requestTokens intent.
+ */
+export declare function requestTokensIntent(ctx: PopContext, params: RequestTokensParams): Promise<TxIntent>;
+export interface TokenRequestIdParams {
+    /** Org name or hex ID. */
+    org: string;
+    /** Numeric request id (`pop token requests`). */
+    requestId: number;
+}
+/**
+ * Resolved builder for `pop token approve` — src/commands/token/approve.ts.
+ * DESTRUCTIVE: approval mints PT irreversibly to the requester. The CLI's
+ * on-chain request/approver-hat preflight is not ported (revert predictors
+ * stay on RPC in the CLI).
+ */
+export declare function approveRequestIntent(ctx: PopContext, params: TokenRequestIdParams): Promise<TxIntent>;
+/**
+ * Resolved builder for `pop token cancel` — src/commands/token/cancel.ts.
+ * Callable by the requester or any approver; the CLI's on-chain
+ * existence/not-yet-approved preflight is not ported.
+ */
+export declare function cancelRequestIntent(ctx: PopContext, params: TokenRequestIdParams): Promise<TxIntent>;

package/dist/tx/token.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * ParticipationToken write builders — token request / approve / cancel.
+ *
+ * Level 1: pure, sync builders that take resolved addresses + fully-prepared
+ * values and return a TxIntent. Level 2: async `<action>Intent(ctx, params)`
+ * builders that resolve the org's token address via the subgraph and pin the
+ * request metadata to IPFS, then delegate to Level 1 — replicating exactly
+ * what the CLI commands do before executeTx.
+ *
+ * Preflight (hat gates, requests(id) existence/state probes) is NOT ported:
+ * those are provider-bound revert predictors that stay in the CLI
+ * (src/commands/token/helpers.ts documents why they must stay on RPC).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRequestAmount = parseRequestAmount;
+exports.buildRequestTokens = buildRequestTokens;
+exports.buildApproveRequest = buildApproveRequest;
+exports.buildCancelRequest = buildCancelRequest;
+exports.requestTokensIntent = requestTokensIntent;
+exports.approveRequestIntent = approveRequestIntent;
+exports.cancelRequestIntent = cancelRequestIntent;
+const ethers_1 = require("ethers");
+const contracts_1 = require("../contracts");
+const ipfs_1 = require("../ipfs");
+const errors_1 = require("../errors");
+const exit_codes_1 = require("../exit-codes");
+const token_1 = require("../metadata/token");
+const token_2 = require("../reads/token");
+const UINT96_MAX = ethers_1.ethers.BigNumber.from(2).pow(96).sub(1);
+/**
+ * Parse a PT amount to 18-decimal wei, enforcing the contract's uint96 bound.
+ * Port of parseRequestAmount in `pop token request` —
+ * src/commands/token/request.ts (same messages and exit codes).
+ */
+function parseRequestAmount(amount) {
+    let wei;
+    try {
+        wei = ethers_1.ethers.utils.parseUnits(String(amount), 18);
+    }
+    catch {
+        throw new errors_1.CliError(`Invalid --amount "${amount}".`, exit_codes_1.EXIT.USAGE, 'Pass a decimal PT amount, e.g. --amount 12.5');
+    }
+    if (wei.lte(0)) {
+        throw new errors_1.CliError('--amount must be greater than zero (the contract reverts ZeroAmount).', exit_codes_1.EXIT.USAGE);
+    }
+    if (wei.gt(UINT96_MAX)) {
+        throw new errors_1.CliError(`--amount overflows the contract's uint96 amount field.`, exit_codes_1.EXIT.USAGE, 'Request a smaller amount.');
+    }
+    return wei;
+}
+/**
+ * Port of `pop token request` — src/commands/token/request.ts.
+ * ParticipationToken.requestTokens(uint96 amount, string ipfsHash): amount in
+ * 18 decimals, ipfsHash as the CID string (not bytes32). isMember-gated
+ * on-chain (executor or any allowed member hat); reverts ZeroAmount on a zero
+ * amount or empty ipfsHash. Emits Requested(id) — parse receipt logs for the
+ * request id.
+ */
+function buildRequestTokens(a) {
+    return {
+        to: a.participationTokenAddress,
+        abi: (0, contracts_1.getAbi)('ParticipationToken'),
+        method: 'requestTokens',
+        args: [a.amountWei, a.ipfsHash],
+        meta: {
+            domain: 'token',
+            action: 'request',
+            orgId: a.orgId,
+            summary: { amountWei: String(a.amountWei), ipfsHash: a.ipfsHash },
+        },
+    };
+}
+/**
+ * Port of `pop token approve` — src/commands/token/approve.ts.
+ * ParticipationToken.approveRequest(uint256 id) — DESTRUCTIVE: mints the
+ * requested PT straight to the requester, irreversibly. onlyApprover
+ * (executor or any allowed approver hat); reverts RequestUnknown /
+ * AlreadyApproved, and NotRequester when the approver IS the requester.
+ */
+function buildApproveRequest(a) {
+    return {
+        to: a.participationTokenAddress,
+        abi: (0, contracts_1.getAbi)('ParticipationToken'),
+        method: 'approveRequest',
+        args: [a.requestId],
+        meta: {
+            domain: 'token',
+            action: 'approve',
+            orgId: a.orgId,
+            summary: { requestId: String(a.requestId) },
+        },
+    };
+}
+/**
+ * Port of `pop token cancel` — src/commands/token/cancel.ts.
+ * ParticipationToken.cancelRequest(uint256 id) — callable by the REQUESTER or
+ * any APPROVER; reverts RequestUnknown for missing ids, AlreadyApproved once
+ * minted, NotApprover for everyone else.
+ */
+function buildCancelRequest(a) {
+    return {
+        to: a.participationTokenAddress,
+        abi: (0, contracts_1.getAbi)('ParticipationToken'),
+        method: 'cancelRequest',
+        args: [a.requestId],
+        meta: {
+            domain: 'token',
+            action: 'cancel',
+            orgId: a.orgId,
+            summary: { requestId: String(a.requestId) },
+        },
+    };
+}
+/**
+ * Resolved builder for `pop token request` — src/commands/token/request.ts.
+ * Validates amount/reason with the CLI's exact errors, resolves the org's
+ * ParticipationToken via the subgraph, pins {reason, submittedAt} to IPFS
+ * (exact key order), then builds the requestTokens intent.
+ */
+async function requestTokensIntent(ctx, params) {
+    const amountWei = parseRequestAmount(params.amount);
+    if (!params.reason || !String(params.reason).trim()) {
+        throw new errors_1.CliError('--reason cannot be empty (the contract requires a non-empty ipfsHash).', exit_codes_1.EXIT.USAGE);
+    }
+    const { orgId, tokenAddress } = await (0, token_2.resolveParticipationToken)(ctx.client, params.org, ctx.chainId);
+    const metadata = (0, token_1.buildTokenRequestMetadata)(params.reason, params.submittedAt);
+    const cid = await (0, ipfs_1.pinJson)((0, token_1.serializeTokenRequestMetadata)(metadata), ctx.ipfs);
+    const intent = buildRequestTokens({
+        participationTokenAddress: tokenAddress,
+        amountWei,
+        ipfsHash: cid,
+        orgId,
+    });
+    intent.meta.ipfs = { cid, metadata };
+    return intent;
+}
+/** Shared id validation — same message/exit code as the approve/cancel commands. */
+function requireRequestId(requestId) {
+    if (!Number.isInteger(requestId) || requestId <= 0) {
+        throw new errors_1.CliError(`Invalid --request "${requestId}".`, exit_codes_1.EXIT.USAGE, 'Pass the numeric request ID (pop token requests).');
+    }
+    return requestId;
+}
+/**
+ * Resolved builder for `pop token approve` — src/commands/token/approve.ts.
+ * DESTRUCTIVE: approval mints PT irreversibly to the requester. The CLI's
+ * on-chain request/approver-hat preflight is not ported (revert predictors
+ * stay on RPC in the CLI).
+ */
+async function approveRequestIntent(ctx, params) {
+    const requestId = requireRequestId(params.requestId);
+    const { orgId, tokenAddress } = await (0, token_2.resolveParticipationToken)(ctx.client, params.org, ctx.chainId);
+    return buildApproveRequest({ participationTokenAddress: tokenAddress, requestId, orgId });
+}
+/**
+ * Resolved builder for `pop token cancel` — src/commands/token/cancel.ts.
+ * Callable by the requester or any approver; the CLI's on-chain
+ * existence/not-yet-approved preflight is not ported.
+ */
+async function cancelRequestIntent(ctx, params) {
+    const requestId = requireRequestId(params.requestId);
+    const { orgId, tokenAddress } = await (0, token_2.resolveParticipationToken)(ctx.client, params.org, ctx.chainId);
+    return buildCancelRequest({ participationTokenAddress: tokenAddress, requestId, orgId });
+}