@poa-box/core 0.1.0

package/dist/reads/paymaster.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Paymaster reads — PaymasterHub infrastructure resolution + org sponsorship
+ * state. Port of src/commands/paymaster/helpers.ts (client-injected) plus the
+ * pure epoch helper from src/commands/paymaster/status.ts.
+ *
+ * The PaymasterHub is a singleton shared across all orgs (one proxy per
+ * chain), so its address comes from the infrastructure query, not the org's
+ * module list.
+ *
+ * ── Where the numbers come from (KEEP — verified field-by-field) ────────────
+ * ENTRY_POINT, the OrgConfig, the fee caps and EVERY budget come from the
+ * subgraph (see graph/documents/paymaster.ts for the field-by-field
+ * verification against both live deployments). Three things deliberately
+ * STAY ON RPC — the schema has fields for some of them, but the VALUES are
+ * wrong on live rows:
+ *   • getOrgFinancials — PaymasterOrgConfig.totalSpent/.depositBalance are
+ *     indexed WITHOUT the 1.01x solidarity fee the hub also debits, so they
+ *     sit at exactly 1/1.01 of the contract's `spent` on both live chains
+ *     (proven to the wei on Gnosis and Arbitrum). `available` decides whether
+ *     sponsorship still works, so it must be the chain's number. The call also
+ *     carries solidarityUsedThisPeriod + periodStart, which have no subgraph
+ *     field at all.
+ *   • getSolidarityFund — numActiveOrgs and feePercentageBps have no field,
+ *     the indexed solidarityBalance is stale on Gnosis (6376552300000000 wei
+ *     high), and solidarityDistributionPaused reads `false` on Arbitrum while
+ *     the contract reports `true`.
+ *   • EntryPoint.balanceOf — the ERC-4337 singleton is not a subgraph data
+ *     source.
+ *
+ * Two ways to read an org's paymaster config, and the difference matters:
+ *
+ *   readPaymasterOrgConfig()               — authoritative eth_call. Use it
+ *     wherever the answer decides whether a transaction gets broadcast
+ *     (deposit's OrgNotRegistered gate). Subgraph lag there means knowingly
+ *     sending a doomed tx.
+ *   readPaymasterOrgConfigPreferSubgraph() — subgraph first, but ONLY trusts a
+ *     POSITIVE "registered" answer; a negative one is always re-confirmed on
+ *     chain before anything is written. The subgraph can lag behind a fresh
+ *     registration, it can never invent one, so a positive is safe to trust and
+ *     a negative is not.
+ */
+import { ethers } from 'ethers';
+import type { GraphClient } from '../graph/client';
+export interface PaymasterInfra {
+    paymasterHubAddress: string;
+    poaManagerAddress: string | null;
+}
+/** Resolve the chain's PaymasterHub proxy (+ PoaManager) from the subgraph. */
+export declare function resolvePaymasterInfra(client: GraphClient, chainId?: number): Promise<PaymasterInfra>;
+export interface PaymasterOrgConfig {
+    adminHatId: ethers.BigNumber;
+    operatorHatId: ethers.BigNumber;
+    paused: boolean;
+    registeredAt: number;
+    bannedFromSolidarity: boolean;
+    registered: boolean;
+}
+/** Fee caps in raw contract units (wei per gas / gas units). */
+export interface PaymasterFeeCaps {
+    maxFeePerGas: ethers.BigNumber;
+    maxPriorityFeePerGas: ethers.BigNumber;
+    maxCallGas: number;
+    maxVerificationGas: number;
+    maxPreVerificationGas: number;
+}
+/** One budget row as the subgraph has it. `totalUsed` is null on the legacy tier. */
+export interface PaymasterBudgetRecord {
+    subjectKey: string;
+    capPerEpoch: ethers.BigNumber;
+    usedInEpoch: ethers.BigNumber;
+    epochLen: number;
+    epochStart: number;
+    totalUsed: ethers.BigNumber | null;
+}
+export interface PaymasterSubgraphState {
+    /** Hub address the indexer knows about — cross-check before trusting the rest. */
+    hubAddress: string | null;
+    /** Checksummed to match what ENTRY_POINT() would have returned. */
+    entryPoint: string | null;
+    orgConfig: PaymasterOrgConfig | null;
+    /**
+     * All-zero when the org row exists but has no PaymasterFeeCaps edge — that is
+     * the contract's "never configured" default, verified against getFeeCaps() on
+     * five orgs across both live deployments. Null only when the org row itself is
+     * missing, in which case the caller must fall back to RPC.
+     */
+    feeCaps: PaymasterFeeCaps | null;
+    /** Null (not empty) when the org row is missing, so "no budgets" stays distinguishable. */
+    budgets: PaymasterBudgetRecord[] | null;
+}
+/**
+ * Read the hub state the subgraph can serve accurately: the immutable
+ * ENTRY_POINT, the org's OrgConfig, its fee caps and ALL of its budgets.
+ * Subgraph half of `pop paymaster status` (src/commands/paymaster/status.ts).
+ *
+ * Never throws — every failure (unreachable subgraph, chain with no deployment,
+ * unindexed org) degrades to nulls so the caller falls back to eth_calls.
+ *
+ * Financials and the solidarity fund are deliberately NOT here; see the module
+ * header for the measurements that disqualified them.
+ */
+export declare function fetchPaymasterSubgraphState(client: GraphClient, orgId: string, chainId?: number): Promise<PaymasterSubgraphState>;
+/**
+ * True when the indexed hub is the hub we independently resolved. A mismatch
+ * (redeployed hub the indexer has not caught up with, a hand-set
+ * POP_*_SUBGRAPH pointing at another network) means the org row describes a
+ * different contract, so the caller must ignore the whole state object.
+ */
+export declare function subgraphMatchesHub(state: PaymasterSubgraphState, hubAddress: string): boolean;
+/**
+ * Read the hub's OrgConfig for an org. `registered` is derived the same way
+ * the contract does it (adminHatId != 0 — see PaymasterHub._registerOrg).
+ *
+ * Authoritative eth_call. Keep using this one for revert-predicting gates.
+ */
+export declare function readPaymasterOrgConfig(provider: ethers.providers.Provider, hubAddress: string, orgId: string): Promise<PaymasterOrgConfig>;
+/**
+ * Registration read for callers that may go on to WRITE.
+ *
+ * Asymmetric on purpose: an indexed registration is trusted (saves the eth_call
+ * on the common "already registered" path), an absent one is re-read on chain
+ * before any decision is made. The subgraph only ever lags reality, so a
+ * false-negative is possible and a false-positive is not — re-confirming just
+ * the negative keeps revert prediction exactly as strong as pure RPC.
+ */
+export declare function readPaymasterOrgConfigPreferSubgraph(client: GraphClient, provider: ethers.providers.Provider, hubAddress: string, orgId: string, chainId?: number): Promise<{
+    config: PaymasterOrgConfig;
+    source: 'subgraph' | 'rpc';
+}>;
+/** Subject key for a hat-scoped paymaster budget: the hat ID as bytes32. */
+export declare function hatSubjectKey(hatId: ethers.BigNumberish): string;
+/**
+ * Has this budget's epoch elapsed? Pure port of budgetEpochState from
+ * src/commands/paymaster/status.ts.
+ *
+ * PaymasterHub resets `usedInEpoch` LAZILY, on the next sponsored
+ * UserOperation, so a budget whose epoch elapsed months ago still reports the
+ * old spend — and getBudget() returns exactly the same stale figure the
+ * subgraph does (verified: both return 7993482525000000 for a Gnosis epoch
+ * that ended in May). Rather than present a stale number as current spend,
+ * check each row against epochStart + epochLen and report it as lapsed, with
+ * the effective (post-reset) spend of zero alongside the raw counter.
+ */
+export declare function budgetEpochState(epochStart: number, epochLen: number, now: number): {
+    epochEnd: number | null;
+    expired: boolean;
+};

package/dist/reads/paymaster.js

@@ -0,0 +1,235 @@
+"use strict";
+/**
+ * Paymaster reads — PaymasterHub infrastructure resolution + org sponsorship
+ * state. Port of src/commands/paymaster/helpers.ts (client-injected) plus the
+ * pure epoch helper from src/commands/paymaster/status.ts.
+ *
+ * The PaymasterHub is a singleton shared across all orgs (one proxy per
+ * chain), so its address comes from the infrastructure query, not the org's
+ * module list.
+ *
+ * ── Where the numbers come from (KEEP — verified field-by-field) ────────────
+ * ENTRY_POINT, the OrgConfig, the fee caps and EVERY budget come from the
+ * subgraph (see graph/documents/paymaster.ts for the field-by-field
+ * verification against both live deployments). Three things deliberately
+ * STAY ON RPC — the schema has fields for some of them, but the VALUES are
+ * wrong on live rows:
+ *   • getOrgFinancials — PaymasterOrgConfig.totalSpent/.depositBalance are
+ *     indexed WITHOUT the 1.01x solidarity fee the hub also debits, so they
+ *     sit at exactly 1/1.01 of the contract's `spent` on both live chains
+ *     (proven to the wei on Gnosis and Arbitrum). `available` decides whether
+ *     sponsorship still works, so it must be the chain's number. The call also
+ *     carries solidarityUsedThisPeriod + periodStart, which have no subgraph
+ *     field at all.
+ *   • getSolidarityFund — numActiveOrgs and feePercentageBps have no field,
+ *     the indexed solidarityBalance is stale on Gnosis (6376552300000000 wei
+ *     high), and solidarityDistributionPaused reads `false` on Arbitrum while
+ *     the contract reports `true`.
+ *   • EntryPoint.balanceOf — the ERC-4337 singleton is not a subgraph data
+ *     source.
+ *
+ * Two ways to read an org's paymaster config, and the difference matters:
+ *
+ *   readPaymasterOrgConfig()               — authoritative eth_call. Use it
+ *     wherever the answer decides whether a transaction gets broadcast
+ *     (deposit's OrgNotRegistered gate). Subgraph lag there means knowingly
+ *     sending a doomed tx.
+ *   readPaymasterOrgConfigPreferSubgraph() — subgraph first, but ONLY trusts a
+ *     POSITIVE "registered" answer; a negative one is always re-confirmed on
+ *     chain before anything is written. The subgraph can lag behind a fresh
+ *     registration, it can never invent one, so a positive is safe to trust and
+ *     a negative is not.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePaymasterInfra = resolvePaymasterInfra;
+exports.fetchPaymasterSubgraphState = fetchPaymasterSubgraphState;
+exports.subgraphMatchesHub = subgraphMatchesHub;
+exports.readPaymasterOrgConfig = readPaymasterOrgConfig;
+exports.readPaymasterOrgConfigPreferSubgraph = readPaymasterOrgConfigPreferSubgraph;
+exports.hatSubjectKey = hatSubjectKey;
+exports.budgetEpochState = budgetEpochState;
+const ethers_1 = require("ethers");
+const infrastructure_1 = require("../graph/documents/infrastructure");
+const paymaster_1 = require("../graph/documents/paymaster");
+const contracts_1 = require("../contracts");
+const errors_1 = require("../errors");
+/** Resolve the chain's PaymasterHub proxy (+ PoaManager) from the subgraph. */
+async function resolvePaymasterInfra(client, chainId) {
+    const infra = await client.query(infrastructure_1.FETCH_INFRASTRUCTURE_ADDRESSES, {}, chainId);
+    const record = infra.poaManagerContracts?.[0];
+    const paymasterHubAddress = record?.paymasterHubProxy;
+    if (!paymasterHubAddress) {
+        throw new errors_1.PreconditionError('PaymasterHub not indexed for this chain.', 'The subgraph may still be syncing, or gas sponsorship is not deployed on this chain.');
+    }
+    return { paymasterHubAddress, poaManagerAddress: record?.id ?? null };
+}
+const EMPTY_STATE = {
+    hubAddress: null,
+    entryPoint: null,
+    orgConfig: null,
+    feeCaps: null,
+    budgets: null,
+};
+const ZERO_FEE_CAPS = {
+    maxFeePerGas: ethers_1.ethers.BigNumber.from(0),
+    maxPriorityFeePerGas: ethers_1.ethers.BigNumber.from(0),
+    maxCallGas: 0,
+    maxVerificationGas: 0,
+    maxPreVerificationGas: 0,
+};
+/**
+ * Read the hub state the subgraph can serve accurately: the immutable
+ * ENTRY_POINT, the org's OrgConfig, its fee caps and ALL of its budgets.
+ * Subgraph half of `pop paymaster status` (src/commands/paymaster/status.ts).
+ *
+ * Never throws — every failure (unreachable subgraph, chain with no deployment,
+ * unindexed org) degrades to nulls so the caller falls back to eth_calls.
+ *
+ * Financials and the solidarity fund are deliberately NOT here; see the module
+ * header for the measurements that disqualified them.
+ */
+async function fetchPaymasterSubgraphState(client, orgId, chainId) {
+    let data;
+    try {
+        const result = await client.queryWithFieldFallback(paymaster_1.FETCH_PAYMASTER_STATE_TIERS.map(q => ({ query: q, variables: { orgId: orgId.toLowerCase() } })), { chainId });
+        data = result.data;
+    }
+    catch {
+        return EMPTY_STATE;
+    }
+    const hub = data?.paymasterHubContracts?.[0];
+    const row = data?.paymasterOrgConfigs?.[0];
+    let entryPoint = null;
+    if (hub?.entryPoint) {
+        // The subgraph stores Bytes lowercased; ENTRY_POINT() returns a checksummed
+        // address. Re-checksum so output is byte-identical either way.
+        try {
+            const checksummed = ethers_1.ethers.utils.getAddress(hub.entryPoint);
+            // The zero address is a documented PLACEHOLDER, not an answer. The mapping
+            // seeds hub.entryPoint = Address.zero() in getOrCreateHub, and the deploy
+            // path only fills it via a try_ENTRY_POINT() call that falls back to zero
+            // (PaymasterInitialized fires before InfrastructureDeployed, so
+            // handlePaymasterInitialized never runs for the initial deploy).
+            //
+            // getAddress() happily accepts it, so without this guard a placeholder
+            // becomes a non-null `entryPoint` that callers then use as an eth_call
+            // TARGET: balanceOf against address(0) returns '0x' and decoding throws
+            // CALL_EXCEPTION. null makes callers fall back to the ENTRY_POINT() read.
+            entryPoint = checksummed === ethers_1.ethers.constants.AddressZero ? null : checksummed;
+        }
+        catch {
+            entryPoint = null;
+        }
+    }
+    if (!row) {
+        return { ...EMPTY_STATE, hubAddress: hub?.id ?? null, entryPoint };
+    }
+    let orgConfig = null;
+    try {
+        const adminHatId = ethers_1.ethers.BigNumber.from(row.adminHatId);
+        orgConfig = {
+            adminHatId,
+            operatorHatId: ethers_1.ethers.BigNumber.from(row.operatorHatId),
+            paused: Boolean(row.isPaused),
+            registeredAt: Number(row.registeredAt ?? 0) || 0,
+            bannedFromSolidarity: Boolean(row.isBannedFromSolidarity),
+            // Derived exactly like PaymasterHub._registerOrg does it.
+            registered: !adminHatId.isZero(),
+        };
+    }
+    catch {
+        return { ...EMPTY_STATE, hubAddress: hub?.id ?? null, entryPoint };
+    }
+    const feeCaps = row.feeCaps
+        ? {
+            maxFeePerGas: ethers_1.ethers.BigNumber.from(row.feeCaps.maxFeePerGas),
+            maxPriorityFeePerGas: ethers_1.ethers.BigNumber.from(row.feeCaps.maxPriorityFeePerGas),
+            maxCallGas: Number(row.feeCaps.maxCallGas ?? 0),
+            maxVerificationGas: Number(row.feeCaps.maxVerificationGas ?? 0),
+            maxPreVerificationGas: Number(row.feeCaps.maxPreVerificationGas ?? 0),
+        }
+        : ZERO_FEE_CAPS;
+    const budgets = (row.budgets ?? []).map(b => ({
+        subjectKey: b.subjectKey,
+        capPerEpoch: ethers_1.ethers.BigNumber.from(b.capPerEpoch),
+        usedInEpoch: ethers_1.ethers.BigNumber.from(b.usedInEpoch),
+        epochLen: Number(b.epochLen ?? 0),
+        epochStart: Number(b.epochStart ?? 0),
+        totalUsed: b.totalUsed !== undefined && b.totalUsed !== null
+            ? ethers_1.ethers.BigNumber.from(b.totalUsed)
+            : null,
+    }));
+    return {
+        hubAddress: row.paymasterHub?.id ?? hub?.id ?? null,
+        entryPoint,
+        orgConfig,
+        feeCaps,
+        budgets,
+    };
+}
+/**
+ * True when the indexed hub is the hub we independently resolved. A mismatch
+ * (redeployed hub the indexer has not caught up with, a hand-set
+ * POP_*_SUBGRAPH pointing at another network) means the org row describes a
+ * different contract, so the caller must ignore the whole state object.
+ */
+function subgraphMatchesHub(state, hubAddress) {
+    return !!state.hubAddress && state.hubAddress.toLowerCase() === hubAddress.toLowerCase();
+}
+/**
+ * Read the hub's OrgConfig for an org. `registered` is derived the same way
+ * the contract does it (adminHatId != 0 — see PaymasterHub._registerOrg).
+ *
+ * Authoritative eth_call. Keep using this one for revert-predicting gates.
+ */
+async function readPaymasterOrgConfig(provider, hubAddress, orgId) {
+    const hub = (0, contracts_1.createReadContract)(hubAddress, 'PaymasterHub', provider);
+    const cfg = await hub.getOrgConfig(orgId);
+    const adminHatId = ethers_1.ethers.BigNumber.from(cfg.adminHatId);
+    return {
+        adminHatId,
+        operatorHatId: ethers_1.ethers.BigNumber.from(cfg.operatorHatId),
+        paused: Boolean(cfg.paused),
+        registeredAt: Number(cfg.registeredAt ?? 0),
+        bannedFromSolidarity: Boolean(cfg.bannedFromSolidarity),
+        registered: !adminHatId.isZero(),
+    };
+}
+/**
+ * Registration read for callers that may go on to WRITE.
+ *
+ * Asymmetric on purpose: an indexed registration is trusted (saves the eth_call
+ * on the common "already registered" path), an absent one is re-read on chain
+ * before any decision is made. The subgraph only ever lags reality, so a
+ * false-negative is possible and a false-positive is not — re-confirming just
+ * the negative keeps revert prediction exactly as strong as pure RPC.
+ */
+async function readPaymasterOrgConfigPreferSubgraph(client, provider, hubAddress, orgId, chainId) {
+    const state = await fetchPaymasterSubgraphState(client, orgId, chainId);
+    if (state.orgConfig?.registered && subgraphMatchesHub(state, hubAddress)) {
+        return { config: state.orgConfig, source: 'subgraph' };
+    }
+    return { config: await readPaymasterOrgConfig(provider, hubAddress, orgId), source: 'rpc' };
+}
+/** Subject key for a hat-scoped paymaster budget: the hat ID as bytes32. */
+function hatSubjectKey(hatId) {
+    return ethers_1.ethers.utils.hexZeroPad(ethers_1.ethers.BigNumber.from(hatId).toHexString(), 32);
+}
+/**
+ * Has this budget's epoch elapsed? Pure port of budgetEpochState from
+ * src/commands/paymaster/status.ts.
+ *
+ * PaymasterHub resets `usedInEpoch` LAZILY, on the next sponsored
+ * UserOperation, so a budget whose epoch elapsed months ago still reports the
+ * old spend — and getBudget() returns exactly the same stale figure the
+ * subgraph does (verified: both return 7993482525000000 for a Gnosis epoch
+ * that ended in May). Rather than present a stale number as current spend,
+ * check each row against epochStart + epochLen and report it as lapsed, with
+ * the effective (post-reset) spend of zero alongside the raw counter.
+ */
+function budgetEpochState(epochStart, epochLen, now) {
+    if (!epochLen || !epochStart)
+        return { epochEnd: null, expired: false };
+    const epochEnd = epochStart + epochLen;
+    return { epochEnd, expired: now >= epochEnd };
+}

package/dist/reads/project.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Project-domain subgraph reads and project-id resolution.
+ *
+ * Ports the read path of `pop project list` (src/commands/project/list.ts) and
+ * the project-input resolver shared by `pop project delete`
+ * (src/commands/project/delete.ts resolveProjectInput) onto the injected
+ * GraphClient. Projects live under the task domain's FETCH_PROJECTS_DATA
+ * document — there is no separate projects query.
+ */
+import type { GraphClient } from '../graph/client';
+import type { SubgraphProject } from './task';
+/**
+ * List an org's (non-deleted) projects, tasks included.
+ * Port of the read at src/commands/project/list.ts:37 — a bare
+ * FETCH_PROJECTS_DATA query (no tier fallback; `pop project list` never used
+ * the deadline/release fields, so the base document always validates).
+ */
+export declare function listProjects(client: GraphClient, orgId: string, chainId?: number): Promise<SubgraphProject[]>;
+/**
+ * Resolve project input to the on-chain bytes32 pid:
+ * bytes32 hex and subgraph composite IDs resolve locally; a plain decimal
+ * maps to bytes32(uint) (on-chain pids are counters — verified against
+ * _createProjectCore in TaskManager.sol); anything else is treated as a
+ * project title and matched via the subgraph.
+ *
+ * Port of src/commands/project/delete.ts resolveProjectInput (same messages,
+ * same resolution order — note decimal beats title here, unlike task create's
+ * resolver which tries the title first).
+ */
+export declare function resolveProjectInput(client: GraphClient, input: string, orgId: string, chainId?: number): Promise<{
+    pid: string;
+    title?: string;
+}>;

package/dist/reads/project.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Project-domain subgraph reads and project-id resolution.
+ *
+ * Ports the read path of `pop project list` (src/commands/project/list.ts) and
+ * the project-input resolver shared by `pop project delete`
+ * (src/commands/project/delete.ts resolveProjectInput) onto the injected
+ * GraphClient. Projects live under the task domain's FETCH_PROJECTS_DATA
+ * document — there is no separate projects query.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listProjects = listProjects;
+exports.resolveProjectInput = resolveProjectInput;
+const ethers_1 = require("ethers");
+const task_1 = require("../graph/documents/task");
+const encoding_1 = require("../encoding");
+const errors_1 = require("../errors");
+const exit_codes_1 = require("../exit-codes");
+/**
+ * List an org's (non-deleted) projects, tasks included.
+ * Port of the read at src/commands/project/list.ts:37 — a bare
+ * FETCH_PROJECTS_DATA query (no tier fallback; `pop project list` never used
+ * the deadline/release fields, so the base document always validates).
+ */
+async function listProjects(client, orgId, chainId) {
+    const result = await client.query(task_1.FETCH_PROJECTS_DATA, { orgId }, chainId);
+    return result.organization?.taskManager?.projects || [];
+}
+/**
+ * Resolve project input to the on-chain bytes32 pid:
+ * bytes32 hex and subgraph composite IDs resolve locally; a plain decimal
+ * maps to bytes32(uint) (on-chain pids are counters — verified against
+ * _createProjectCore in TaskManager.sol); anything else is treated as a
+ * project title and matched via the subgraph.
+ *
+ * Port of src/commands/project/delete.ts resolveProjectInput (same messages,
+ * same resolution order — note decimal beats title here, unlike task create's
+ * resolver which tries the title first).
+ */
+async function resolveProjectInput(client, input, orgId, chainId) {
+    if (input.startsWith('0x') && input.length === 66)
+        return { pid: input };
+    if (/^0x[a-fA-F0-9]{40}-/.test(input))
+        return { pid: (0, encoding_1.parseProjectId)(input) };
+    if (/^\d+$/.test(input)) {
+        return { pid: ethers_1.ethers.utils.hexZeroPad(ethers_1.ethers.BigNumber.from(input).toHexString(), 32) };
+    }
+    // Title lookup via the subgraph (case-insensitive).
+    let projects = [];
+    try {
+        const result = await client.query(task_1.FETCH_PROJECTS_DATA, { orgId }, chainId);
+        projects = result.organization?.taskManager?.projects || [];
+    }
+    catch {
+        throw new errors_1.CliError(`Could not resolve project "${input}" — the subgraph is unavailable for title lookup.`, exit_codes_1.EXIT.INFRA, 'Pass the 0x-prefixed bytes32 project ID instead (pop project list --json).');
+    }
+    const match = projects.find((p) => (p.title || '').toLowerCase() === input.toLowerCase());
+    if (match)
+        return { pid: (0, encoding_1.parseProjectId)(match.id), title: match.title ?? undefined };
+    const available = projects.map((p) => p.title).filter(Boolean).join(', ');
+    throw new errors_1.CliError(`Project "${input}" not found.`, exit_codes_1.EXIT.USAGE, `Available projects: ${available || 'none'} (or pass the 0x-prefixed bytes32 project ID).`);
+}

package/dist/reads/resolve.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared org/contract resolution helpers.
+ * Single source of truth for resolving org names to IDs and fetching contract
+ * addresses. Port of src/lib/resolve.ts: functions take the GraphClient
+ * explicitly instead of importing a process-global one.
+ */
+import type { GraphClient } from '../graph/client';
+/**
+ * Resolve an org identifier (name or hex ID) to its bytes32 ID.
+ * Throws a helpful error if org is not provided.
+ */
+export declare function resolveOrgId(client: GraphClient, orgIdOrName: string | undefined, chainId?: number): Promise<string>;
+export interface OrgModules {
+    orgId: string;
+    taskManagerAddress: string | null;
+    hybridVotingAddress: string | null;
+    ddVotingAddress: string | null;
+    participationTokenAddress: string | null;
+    educationHubAddress: string | null;
+    executorAddress: string | null;
+    quickJoinAddress: string | null;
+    eligibilityModuleAddress: string | null;
+    paymentManagerAddress: string | null;
+    /** ZkEmailInvites proxy — null for orgs deployed without the optional ZK Email module. */
+    zkEmailInvitesAddress: string | null;
+}
+/**
+ * Resolve an org's deployed module addresses via subgraph.
+ */
+export declare function resolveOrgModules(client: GraphClient, orgIdOrName: string | undefined, chainId?: number): Promise<OrgModules>;
+/**
+ * Require a specific module address, throwing a helpful error if not deployed.
+ */
+export declare function requireModule(modules: OrgModules, moduleName: keyof OrgModules): string;

package/dist/reads/resolve.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * Shared org/contract resolution helpers.
+ * Single source of truth for resolving org names to IDs and fetching contract
+ * addresses. Port of src/lib/resolve.ts: functions take the GraphClient
+ * explicitly instead of importing a process-global one.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveOrgId = resolveOrgId;
+exports.resolveOrgModules = resolveOrgModules;
+exports.requireModule = requireModule;
+const org_1 = require("../graph/documents/org");
+/**
+ * Resolve an org identifier (name or hex ID) to its bytes32 ID.
+ * Throws a helpful error if org is not provided.
+ */
+async function resolveOrgId(client, orgIdOrName, chainId) {
+    if (!orgIdOrName) {
+        throw new Error('Missing --org flag. Provide --org or set POP_DEFAULT_ORG in .env');
+    }
+    if (orgIdOrName.startsWith('0x')) {
+        return orgIdOrName;
+    }
+    const result = await client.query(org_1.GET_ORG_BY_NAME, { name: orgIdOrName }, chainId);
+    if (!result.organizations?.length) {
+        throw new Error(`Organization "${orgIdOrName}" not found. Use the hex ID or check the org name.`);
+    }
+    return result.organizations[0].id;
+}
+/**
+ * Resolve an org's deployed module addresses via subgraph.
+ */
+async function resolveOrgModules(client, orgIdOrName, chainId) {
+    const orgId = await resolveOrgId(client, orgIdOrName, chainId);
+    const result = await client.query(org_1.FETCH_ORG_BY_ID, { id: orgId }, chainId);
+    if (!result.organization) {
+        throw new Error(`Organization ${orgId} not found on this chain`);
+    }
+    const org = result.organization;
+    return {
+        orgId: org.id,
+        taskManagerAddress: org.taskManager?.id || null,
+        hybridVotingAddress: org.hybridVoting?.id || null,
+        ddVotingAddress: org.directDemocracyVoting?.id || null,
+        participationTokenAddress: org.participationToken?.id || null,
+        educationHubAddress: org.educationHub?.id || null,
+        executorAddress: org.executorContract?.id || null,
+        quickJoinAddress: org.quickJoin?.id || null,
+        eligibilityModuleAddress: org.eligibilityModule?.id || null,
+        paymentManagerAddress: org.paymentManager?.id || null,
+        zkEmailInvitesAddress: org.zkEmailInvites?.id || null,
+    };
+}
+/**
+ * Require a specific module address, throwing a helpful error if not deployed.
+ */
+function requireModule(modules, moduleName) {
+    const addr = modules[moduleName];
+    if (!addr || typeof addr !== 'string') {
+        const friendlyName = moduleName.replace('Address', '').replace(/([A-Z])/g, ' $1').trim();
+        throw new Error(`Organization has no ${friendlyName} deployed`);
+    }
+    return addr;
+}