@poa-box/core 0.1.0

package/dist/chains.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Network Configuration
+ * Mirrors frontend networks.js for full parity on POP-deployed chains.
+ *
+ * Chains come in two flavors:
+ *   1. POP-deployed chains (Gnosis, Arbitrum, Sepolia, BaseSepolia) — full
+ *      subgraph + deployment support. Set `isExternal: false` (default).
+ *   2. External chains (Ethereum mainnet, Optimism, Base, Polygon) — no POP
+ *      deployment, no POP subgraph. Used by read-only commands like
+ *      `pop org probe-access` to inspect foreign governance contracts
+ *      (Compound Governor Bravo, Aave V3, Uniswap, etc). Set
+ *      `isExternal: true` so subgraph sweepers skip them.
+ *
+ * Adding an external chain: set `isExternal: true`, leave `subgraphUrl: ''`,
+ * and use an empty `bountyTokens` map. Commands that require a POP subgraph
+ * (org activity, task lists, proposal history) will refuse to run on external
+ * chains — probe-access and other foreign-contract tools work fine.
+ *
+ * Env-derived resolution (getGatewaySubgraphUrl, resolveNetworkConfig) reads
+ * from an injected EnvSource — the CLI passes process.env; browser hosts pass
+ * whatever env object they assemble. Pure lookups need no env at all.
+ */
+import { EnvSource } from './env';
+export interface NetworkConfig {
+    chainId: number;
+    name: string;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
+    };
+    rpcUrl: string;
+    blockExplorer: string;
+    isTestnet: boolean;
+    /**
+     * True if POP is NOT deployed on this chain. External chains are
+     * useful for read-only contract inspection (probe-access) but
+     * cannot be used for POP operations like task management, voting,
+     * treasury, or governance. Defaults to false when omitted.
+     */
+    isExternal?: boolean;
+    /**
+     * Default block range per getLogs chunk for this chain. L2 chains have
+     * stricter RPC limits than L1 — Optimism/Base public RPCs reject ranges
+     * above ~2000-5000 blocks. Commands like audit-vetoken use this value
+     * when the user doesn't pass --chunk. Defaults to 10000 when omitted.
+     */
+    defaultLogsChunkBlocks?: number;
+    subgraphUrl: string;
+    /**
+     * Subgraph ID on The Graph's DECENTRALISED network (the "paid" gateway tier).
+     *
+     * `subgraphUrl` above points at Graph Studio, which is free but capped at
+     * 3K queries/day. The same deployment is also published to the gateway,
+     * where it is addressed by this base58 subgraph ID and billed against
+     * `GRAPH_API_KEY`. lib/subgraph.ts uses Studio first and switches here when
+     * the free quota is spent — see `getGatewaySubgraphUrl` below.
+     *
+     * Leave undefined when the deployment has not been published to the
+     * decentralised network; the chain then has no paid tier unless the
+     * operator supplies one via `POP_<NET>_SUBGRAPH_GATEWAY` /
+     * `POP_<NET>_SUBGRAPH_ID`.
+     */
+    gatewaySubgraphId?: string;
+    bountyTokens: Record<string, string>;
+}
+/**
+ * Base URL for The Graph's decentralised gateway. A full endpoint is
+ * `${base}/${gatewaySubgraphId}`. Override with POP_GRAPH_GATEWAY_URL to point
+ * at a self-hosted or regional gateway.
+ *
+ * NOTE: the LEGACY gateway form embedded the API key in the path
+ * (`/api/<KEY>/subgraphs/id/<ID>`). This modern form does not — the key travels
+ * in the Authorization header instead, so the URL is safe to print.
+ */
+export declare const DEFAULT_GRAPH_GATEWAY_URL = "https://gateway.thegraph.com/api/subgraphs/id";
+export declare const NETWORKS: Record<string, NetworkConfig>;
+/** Home chain for accounts/passkeys */
+export declare const HOME_NETWORK = "arbitrum";
+export declare const HOME_CHAIN_ID: number;
+/** Default chain for org deployment */
+export declare const DEFAULT_DEPLOY_NETWORK = "gnosis";
+export declare const DEFAULT_DEPLOY_CHAIN_ID: number;
+export declare function getNetworkByChainId(chainId: number): NetworkConfig | null;
+export declare function getNetworkNameByChainId(chainId: number): string | null;
+export declare function isNetworkSupported(chainId: number): boolean;
+export declare function getSubgraphUrl(chainId: number): string;
+/**
+ * UPPER_SNAKE env-var infix for a chain: 84532 -> "BASE_SEPOLIA".
+ * Single source of truth for the `POP_<NET>_*` env convention so the RPC,
+ * subgraph and gateway lookups can never drift apart.
+ */
+export declare function getEnvInfixByChainId(chainId: number): string | null;
+/**
+ * Resolve the PAID (decentralised gateway) subgraph endpoint for a chain, or
+ * undefined when none is configured. Requires `GRAPH_API_KEY` at request time —
+ * this function only resolves the URL, it does not check for the key.
+ *
+ * Precedence (first non-empty wins):
+ *   1. `POP_<NET>_SUBGRAPH_GATEWAY`   — explicit full URL
+ *   2. `POP_<NET>_SUBGRAPH_FALLBACK`  — legacy name for the same thing
+ *   3. `POP_<NET>_SUBGRAPH_ID`        — just the base58 ID, joined to the base
+ *   4. `NetworkConfig.gatewaySubgraphId` joined to the base
+ *
+ * The base is `POP_GRAPH_GATEWAY_URL` or DEFAULT_GRAPH_GATEWAY_URL. This
+ * replaces the old one-ad-hoc-env-var-per-chain arrangement where only Gnosis
+ * could ever reach the gateway.
+ */
+export declare function getGatewaySubgraphUrl(chainId: number, env?: EnvSource): string | undefined;
+export declare function getAllSubgraphUrls(): Array<{
+    chainId: number;
+    url: string;
+    name: string;
+}>;
+/**
+ * Resolve the effective network config using env vars + CLI overrides.
+ * Priority: CLI flag > per-chain env var > POP_DEFAULT_CHAIN env > error
+ */
+export declare function resolveNetworkConfig(chainIdOverride?: number, env?: EnvSource): NetworkConfig & {
+    resolvedRpc: string;
+    resolvedSubgraph: string;
+};
+/**
+ * Token configuration — decimals and metadata for known tokens.
+ * Must match frontend token handling for correct amount encoding.
+ */
+export interface TokenInfo {
+    symbol: string;
+    decimals: number;
+    address: string;
+}
+/** Participation Token is always 18 decimals */
+export declare const PARTICIPATION_TOKEN_DECIMALS = 18;
+export declare function getTokenByAddress(address: string): TokenInfo | null;
+/**
+ * Reverse lookup by symbol. Case-insensitive. Returns the first matching
+ * token across all chains — if the same symbol exists on multiple chains
+ * (e.g. USDC on Gnosis/Arbitrum/Sepolia), the caller should narrow by
+ * chain using getTokenByAddress after resolving the chain-specific address
+ * via another channel.
+ */
+export declare function getTokenBySymbol(symbol: string): TokenInfo | null;
+/**
+ * Resolve a user-supplied token identifier to a checksummed address.
+ * If input starts with 0x, returns it unchanged (caller's responsibility
+ * to pre-validate). Otherwise treats it as a symbol and resolves via
+ * getTokenBySymbol, throwing if unknown.
+ */
+export declare function resolveTokenAddress(input: string): string;
+export declare function getTokenDecimals(address: string): number;

package/dist/chains.js

@@ -0,0 +1,320 @@
+"use strict";
+/**
+ * Network Configuration
+ * Mirrors frontend networks.js for full parity on POP-deployed chains.
+ *
+ * Chains come in two flavors:
+ *   1. POP-deployed chains (Gnosis, Arbitrum, Sepolia, BaseSepolia) — full
+ *      subgraph + deployment support. Set `isExternal: false` (default).
+ *   2. External chains (Ethereum mainnet, Optimism, Base, Polygon) — no POP
+ *      deployment, no POP subgraph. Used by read-only commands like
+ *      `pop org probe-access` to inspect foreign governance contracts
+ *      (Compound Governor Bravo, Aave V3, Uniswap, etc). Set
+ *      `isExternal: true` so subgraph sweepers skip them.
+ *
+ * Adding an external chain: set `isExternal: true`, leave `subgraphUrl: ''`,
+ * and use an empty `bountyTokens` map. Commands that require a POP subgraph
+ * (org activity, task lists, proposal history) will refuse to run on external
+ * chains — probe-access and other foreign-contract tools work fine.
+ *
+ * Env-derived resolution (getGatewaySubgraphUrl, resolveNetworkConfig) reads
+ * from an injected EnvSource — the CLI passes process.env; browser hosts pass
+ * whatever env object they assemble. Pure lookups need no env at all.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PARTICIPATION_TOKEN_DECIMALS = exports.DEFAULT_DEPLOY_CHAIN_ID = exports.DEFAULT_DEPLOY_NETWORK = exports.HOME_CHAIN_ID = exports.HOME_NETWORK = exports.NETWORKS = exports.DEFAULT_GRAPH_GATEWAY_URL = void 0;
+exports.getNetworkByChainId = getNetworkByChainId;
+exports.getNetworkNameByChainId = getNetworkNameByChainId;
+exports.isNetworkSupported = isNetworkSupported;
+exports.getSubgraphUrl = getSubgraphUrl;
+exports.getEnvInfixByChainId = getEnvInfixByChainId;
+exports.getGatewaySubgraphUrl = getGatewaySubgraphUrl;
+exports.getAllSubgraphUrls = getAllSubgraphUrls;
+exports.resolveNetworkConfig = resolveNetworkConfig;
+exports.getTokenByAddress = getTokenByAddress;
+exports.getTokenBySymbol = getTokenBySymbol;
+exports.resolveTokenAddress = resolveTokenAddress;
+exports.getTokenDecimals = getTokenDecimals;
+const env_1 = require("./env");
+/**
+ * Base URL for The Graph's decentralised gateway. A full endpoint is
+ * `${base}/${gatewaySubgraphId}`. Override with POP_GRAPH_GATEWAY_URL to point
+ * at a self-hosted or regional gateway.
+ *
+ * NOTE: the LEGACY gateway form embedded the API key in the path
+ * (`/api/<KEY>/subgraphs/id/<ID>`). This modern form does not — the key travels
+ * in the Authorization header instead, so the URL is safe to print.
+ */
+exports.DEFAULT_GRAPH_GATEWAY_URL = 'https://gateway.thegraph.com/api/subgraphs/id';
+exports.NETWORKS = {
+    arbitrum: {
+        chainId: 42161,
+        name: 'Arbitrum One',
+        nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+        rpcUrl: 'https://arbitrum-one-rpc.publicnode.com',
+        defaultLogsChunkBlocks: 2000,
+        blockExplorer: 'https://arbiscan.io',
+        isTestnet: false,
+        subgraphUrl: 'https://api.studio.thegraph.com/query/73367/poa-arb-v-1/version/latest',
+        // No gatewaySubgraphId: the Arbitrum deployment has not been published to
+        // the decentralised network (or its ID is not known here), so Arbitrum has
+        // no paid tier by default. Set POP_ARBITRUM_SUBGRAPH_ID once it is published.
+        bountyTokens: {
+            USDC: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
+        },
+    },
+    gnosis: {
+        chainId: 100,
+        name: 'Gnosis',
+        nativeCurrency: { name: 'xDAI', symbol: 'xDAI', decimals: 18 },
+        rpcUrl: 'https://rpc.gnosischain.com',
+        blockExplorer: 'https://gnosisscan.io',
+        isTestnet: false,
+        subgraphUrl: 'https://api.studio.thegraph.com/query/73367/poa-gnosis-v-1/version/latest',
+        // Verified against the live gateway: this ID serves the same deployment as
+        // the Studio URL above (identical `_meta.block` within one block).
+        gatewaySubgraphId: '576YA6oF16nA2uG5Q9KFfBSvJm4ZNKzWZkwh8eWXaxJs',
+        bountyTokens: {
+            BREAD: '0xa555d5344f6FB6c65da19e403Cb4c1eC4a1a5Ee3',
+            USDC: '0xDDAfbb505ad214D7b80b1f830fcCc89B60fB7A83',
+            WXDAI: '0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d',
+            sDAI: '0xaf204776c7245bF4147c2612BF6e5972Ee483701',
+        },
+    },
+    sepolia: {
+        chainId: 11155111,
+        name: 'Sepolia',
+        nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+        rpcUrl: 'https://ethereum-sepolia-rpc.publicnode.com',
+        blockExplorer: 'https://sepolia.etherscan.io',
+        isTestnet: true,
+        // No POP subgraph is deployed here — the Graph Studio deployment was removed (the frontend
+        // dropped these endpoints in its PR #441; the URL now answers "deployment does not exist").
+        // Empty means "RPC-only chain": getAllSubgraphUrls() filters on truthiness, and
+        // lib/subgraph.ts turns a subgraph-backed command into one actionable error.
+        subgraphUrl: '',
+        bountyTokens: {
+            USDC: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238',
+        },
+    },
+    baseSepolia: {
+        chainId: 84532,
+        name: 'Base Sepolia',
+        nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+        rpcUrl: 'https://base-sepolia-rpc.publicnode.com',
+        blockExplorer: 'https://sepolia.basescan.org',
+        isTestnet: true,
+        // No POP subgraph deployed — see the Sepolia note above.
+        subgraphUrl: '',
+        bountyTokens: {
+            USDC: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+        },
+    },
+    // ---------------------------------------------------------------------
+    // External chains (HB#326, task #341) — read-only probe targets.
+    // POP is NOT deployed on any of these. Added so `pop org probe-access
+    // --chain <id>` works without the --rpc workaround from HB#336. See
+    // the NetworkConfig.isExternal field comment at the top of this file
+    // for the semantics.
+    // ---------------------------------------------------------------------
+    ethereum: {
+        chainId: 1,
+        name: 'Ethereum',
+        nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+        rpcUrl: 'https://ethereum.publicnode.com',
+        blockExplorer: 'https://etherscan.io',
+        isTestnet: false,
+        isExternal: true,
+        subgraphUrl: '',
+        bountyTokens: {},
+    },
+    optimism: {
+        chainId: 10,
+        name: 'Optimism',
+        nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+        rpcUrl: 'https://optimism-rpc.publicnode.com',
+        blockExplorer: 'https://optimistic.etherscan.io',
+        isTestnet: false,
+        isExternal: true,
+        defaultLogsChunkBlocks: 2000,
+        subgraphUrl: '',
+        bountyTokens: {},
+    },
+    base: {
+        chainId: 8453,
+        name: 'Base',
+        nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+        rpcUrl: 'https://base-rpc.publicnode.com',
+        blockExplorer: 'https://basescan.org',
+        isTestnet: false,
+        isExternal: true,
+        defaultLogsChunkBlocks: 2000,
+        subgraphUrl: '',
+        bountyTokens: {},
+    },
+    polygon: {
+        chainId: 137,
+        name: 'Polygon',
+        nativeCurrency: { name: 'MATIC', symbol: 'MATIC', decimals: 18 },
+        rpcUrl: 'https://polygon-bor-rpc.publicnode.com',
+        blockExplorer: 'https://polygonscan.com',
+        isTestnet: false,
+        isExternal: true,
+        subgraphUrl: '',
+        bountyTokens: {},
+    },
+};
+/** Home chain for accounts/passkeys */
+exports.HOME_NETWORK = 'arbitrum';
+exports.HOME_CHAIN_ID = exports.NETWORKS[exports.HOME_NETWORK].chainId;
+/** Default chain for org deployment */
+exports.DEFAULT_DEPLOY_NETWORK = 'gnosis';
+exports.DEFAULT_DEPLOY_CHAIN_ID = exports.NETWORKS[exports.DEFAULT_DEPLOY_NETWORK].chainId;
+function getNetworkByChainId(chainId) {
+    return Object.values(exports.NETWORKS).find(n => n.chainId === chainId) || null;
+}
+function getNetworkNameByChainId(chainId) {
+    const entry = Object.entries(exports.NETWORKS).find(([_, config]) => config.chainId === chainId);
+    return entry ? entry[0] : null;
+}
+function isNetworkSupported(chainId) {
+    return !!getNetworkByChainId(chainId);
+}
+function getSubgraphUrl(chainId) {
+    return getNetworkByChainId(chainId)?.subgraphUrl || exports.NETWORKS[exports.HOME_NETWORK].subgraphUrl;
+}
+/**
+ * UPPER_SNAKE env-var infix for a chain: 84532 -> "BASE_SEPOLIA".
+ * Single source of truth for the `POP_<NET>_*` env convention so the RPC,
+ * subgraph and gateway lookups can never drift apart.
+ */
+function getEnvInfixByChainId(chainId) {
+    const name = getNetworkNameByChainId(chainId);
+    return name ? name.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase() : null;
+}
+/**
+ * Resolve the PAID (decentralised gateway) subgraph endpoint for a chain, or
+ * undefined when none is configured. Requires `GRAPH_API_KEY` at request time —
+ * this function only resolves the URL, it does not check for the key.
+ *
+ * Precedence (first non-empty wins):
+ *   1. `POP_<NET>_SUBGRAPH_GATEWAY`   — explicit full URL
+ *   2. `POP_<NET>_SUBGRAPH_FALLBACK`  — legacy name for the same thing
+ *   3. `POP_<NET>_SUBGRAPH_ID`        — just the base58 ID, joined to the base
+ *   4. `NetworkConfig.gatewaySubgraphId` joined to the base
+ *
+ * The base is `POP_GRAPH_GATEWAY_URL` or DEFAULT_GRAPH_GATEWAY_URL. This
+ * replaces the old one-ad-hoc-env-var-per-chain arrangement where only Gnosis
+ * could ever reach the gateway.
+ */
+function getGatewaySubgraphUrl(chainId, env = env_1.EMPTY_ENV) {
+    const infix = getEnvInfixByChainId(chainId);
+    if (!infix)
+        return undefined;
+    const explicit = (env[`POP_${infix}_SUBGRAPH_GATEWAY`] || '').trim()
+        || (env[`POP_${infix}_SUBGRAPH_FALLBACK`] || '').trim();
+    if (explicit)
+        return explicit;
+    const id = (env[`POP_${infix}_SUBGRAPH_ID`] || '').trim()
+        || (getNetworkByChainId(chainId)?.gatewaySubgraphId || '').trim();
+    if (!id)
+        return undefined;
+    const base = ((env.POP_GRAPH_GATEWAY_URL || '').trim() || exports.DEFAULT_GRAPH_GATEWAY_URL).replace(/\/+$/, '');
+    return `${base}/${id}`;
+}
+function getAllSubgraphUrls() {
+    // External chains (Ethereum mainnet, Optimism, Base, Polygon) have no
+    // POP subgraph and are read-only probe targets only. Filter them out
+    // here so the subgraph sweeper never tries to query a nonexistent URL.
+    return Object.values(exports.NETWORKS)
+        .filter(n => !n.isTestnet && !n.isExternal && n.subgraphUrl)
+        .map(n => ({ chainId: n.chainId, url: n.subgraphUrl, name: n.name }));
+}
+/**
+ * Resolve the effective network config using env vars + CLI overrides.
+ * Priority: CLI flag > per-chain env var > POP_DEFAULT_CHAIN env > error
+ */
+function resolveNetworkConfig(chainIdOverride, env = env_1.EMPTY_ENV) {
+    const chainId = chainIdOverride
+        || (env.POP_DEFAULT_CHAIN ? parseInt(env.POP_DEFAULT_CHAIN, 10) : undefined);
+    if (!chainId) {
+        throw new Error('No chain specified. Set POP_DEFAULT_CHAIN in .env or pass --chain flag.');
+    }
+    const network = getNetworkByChainId(chainId);
+    if (!network) {
+        throw new Error(`Unsupported chain ID: ${chainId}. Supported: ${Object.values(exports.NETWORKS).map(n => `${n.name} (${n.chainId})`).join(', ')}`);
+    }
+    // Convert camelCase to UPPER_SNAKE: baseSepolia → BASE_SEPOLIA
+    const networkName = getEnvInfixByChainId(chainId);
+    // An override that is present-but-empty (`POP_SUBGRAPH_URL=` on its own line,
+    // which is exactly what the shipped .env templates contain) must NOT shadow
+    // the built-in default. `''` is already falsy, but trim first so a stray
+    // space or CR from a hand-edited .env behaves the same way.
+    const envUrl = (name) => {
+        const raw = env[name];
+        const trimmed = typeof raw === 'string' ? raw.trim() : '';
+        return trimmed || undefined;
+    };
+    const resolvedRpc = envUrl(`POP_${networkName}_RPC`)
+        || (chainIdOverride ? undefined : envUrl('POP_RPC_URL'))
+        || network.rpcUrl;
+    const resolvedSubgraph = envUrl(`POP_${networkName}_SUBGRAPH`)
+        || (chainIdOverride ? undefined : envUrl('POP_SUBGRAPH_URL'))
+        || network.subgraphUrl;
+    return { ...network, resolvedRpc, resolvedSubgraph };
+}
+/** Participation Token is always 18 decimals */
+exports.PARTICIPATION_TOKEN_DECIMALS = 18;
+/** Known tokens across all chains, keyed by lowercase address */
+const KNOWN_TOKENS = {
+    // Arbitrum
+    '0xaf88d065e77c8cc2239327c5edb3a432268e5831': { symbol: 'USDC', decimals: 6, address: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831' },
+    // Gnosis
+    '0xa555d5344f6fb6c65da19e403cb4c1ec4a1a5ee3': { symbol: 'BREAD', decimals: 18, address: '0xa555d5344f6FB6c65da19e403Cb4c1eC4a1a5Ee3' },
+    '0xddafbb505ad214d7b80b1f830fccc89b60fb7a83': { symbol: 'USDC', decimals: 6, address: '0xDDAfbb505ad214D7b80b1f830fcCc89B60fB7A83' },
+    '0xe91d153e0b41518a2ce8dd3d7944fa863463a97d': { symbol: 'WXDAI', decimals: 18, address: '0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d' },
+    // Sepolia
+    '0x1c7d4b196cb0c7b01d743fbc6116a902379c7238': { symbol: 'USDC', decimals: 6, address: '0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238' },
+    // Base Sepolia
+    '0x036cbd53842c5426634e7929541ec2318f3dcf7e': { symbol: 'USDC', decimals: 6, address: '0x036CbD53842c5426634e7929541eC2318f3dCF7e' },
+};
+function getTokenByAddress(address) {
+    return KNOWN_TOKENS[address.toLowerCase()] || null;
+}
+/**
+ * Reverse lookup by symbol. Case-insensitive. Returns the first matching
+ * token across all chains — if the same symbol exists on multiple chains
+ * (e.g. USDC on Gnosis/Arbitrum/Sepolia), the caller should narrow by
+ * chain using getTokenByAddress after resolving the chain-specific address
+ * via another channel.
+ */
+function getTokenBySymbol(symbol) {
+    const want = symbol.toUpperCase();
+    for (const t of Object.values(KNOWN_TOKENS)) {
+        if (t.symbol.toUpperCase() === want)
+            return t;
+    }
+    return null;
+}
+/**
+ * Resolve a user-supplied token identifier to a checksummed address.
+ * If input starts with 0x, returns it unchanged (caller's responsibility
+ * to pre-validate). Otherwise treats it as a symbol and resolves via
+ * getTokenBySymbol, throwing if unknown.
+ */
+function resolveTokenAddress(input) {
+    if (input.startsWith('0x'))
+        return input;
+    const token = getTokenBySymbol(input);
+    if (!token) {
+        throw new Error(`Unknown token symbol: ${input}. Add it to config/tokens.ts or pass a 0x address.`);
+    }
+    return token.address;
+}
+function getTokenDecimals(address) {
+    const token = getTokenByAddress(address);
+    if (!token) {
+        throw new Error(`Unknown bounty token: ${address}. Add it to config/tokens.ts or use a known token.`);
+    }
+    return token.decimals;
+}

package/dist/context.d.ts

@@ -0,0 +1,48 @@
+/**
+ * PopContext — the bag of injected services that resolved (async) builders and
+ * read helpers take as their first argument.
+ *
+ * Hosts construct it once: the CLI from process.env + its fs-backed tier
+ * store, a frontend from its wagmi/Apollo wiring, an integrator from nothing
+ * but a chainId. createPop() (index.ts) wraps one of these in a bound facade.
+ */
+import type { ethers } from 'ethers';
+import { GraphClient } from './graph/client';
+import type { GraphClientOptions } from './graph/client';
+import type { IpfsOptions } from './ipfs';
+import type { EnvSource } from './env';
+export interface PopContext {
+    /** Subgraph reads (tier-routed). */
+    client: GraphClient;
+    /** Default chain for reads and address resolution. */
+    chainId?: number;
+    /** Only builders that feature-detect or preflight need a provider. */
+    provider?: ethers.providers.Provider;
+    /** Only builders that pin metadata need IPFS options. */
+    ipfs?: IpfsOptions;
+    /** Never read directly by domain code; passed to helpers that take env. */
+    env?: EnvSource;
+}
+export interface CreatePopContextOptions {
+    /** Default chain for reads and address resolution. */
+    chainId?: number;
+    /** Env overrides (endpoint/tier/IPFS vars). Pure defaults when omitted. */
+    env?: EnvSource;
+    /** Needed only for feature detection / preflight / live decimals reads. */
+    provider?: ethers.providers.Provider;
+    /** Graph transport overrides (state store, fetch, warn reporter). */
+    graph?: Omit<GraphClientOptions, 'env'>;
+    /** IPFS endpoints / readonly flag. */
+    ipfs?: IpfsOptions;
+}
+/**
+ * One-call setup for integrators:
+ *
+ *   const ctx = createPopContext({ chainId: 100 });
+ *   const org = await resolveOrgModules(ctx.client, 'my-org');
+ *   const intent = await createTaskIntent(ctx, { org: 'my-org', ... });
+ *
+ * Every resolved builder takes this ctx as its first argument; execution is
+ * host-chosen (executeIntent for ethers EOA, encodeIntent for anything else).
+ */
+export declare function createPopContext(options?: CreatePopContextOptions): PopContext;

package/dist/context.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * PopContext — the bag of injected services that resolved (async) builders and
+ * read helpers take as their first argument.
+ *
+ * Hosts construct it once: the CLI from process.env + its fs-backed tier
+ * store, a frontend from its wagmi/Apollo wiring, an integrator from nothing
+ * but a chainId. createPop() (index.ts) wraps one of these in a bound facade.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPopContext = createPopContext;
+const client_1 = require("./graph/client");
+/**
+ * One-call setup for integrators:
+ *
+ *   const ctx = createPopContext({ chainId: 100 });
+ *   const org = await resolveOrgModules(ctx.client, 'my-org');
+ *   const intent = await createTaskIntent(ctx, { org: 'my-org', ... });
+ *
+ * Every resolved builder takes this ctx as its first argument; execution is
+ * host-chosen (executeIntent for ethers EOA, encodeIntent for anything else).
+ */
+function createPopContext(options = {}) {
+    // The context chain is also the client's default chain: reads documented as
+    // `fn(ctx.client, …)` must work without repeating the chainId per call.
+    const client = new client_1.GraphClient({
+        env: options.env,
+        defaultChainId: options.chainId,
+        ...options.graph,
+    });
+    return {
+        client,
+        chainId: options.chainId,
+        provider: options.provider,
+        ipfs: options.ipfs,
+        env: options.env,
+    };
+}

package/dist/contracts.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Contract Utilities
+ * ABI lookup from the generated registry (no fs — browser-pure) and
+ * ethers Contract construction helpers.
+ */
+import { ethers } from 'ethers';
+/**
+ * Look up an ABI by its historical abi/ file base name (e.g. 'TaskManagerNew').
+ * Searches first-party POP ABIs, then the third-party probe-target ABIs.
+ *
+ * Returns a mutable-typed array (the registry consts are readonly) so ethers v5
+ * Interface construction typechecks.
+ */
+export declare function getAbi(name: string): any[];
+/** Back-compat alias — the CLI's fs-based loader was named loadAbi. */
+export declare const loadAbi: typeof getAbi;
+/**
+ * Create a read-only contract instance.
+ */
+export declare function createReadContract(address: string, abiName: string, provider: ethers.providers.Provider): ethers.Contract;
+/**
+ * Create a writable contract instance (with signer).
+ */
+export declare function createWriteContract(address: string, abiName: string, signer: ethers.Signer): ethers.Contract;

package/dist/contracts.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Contract Utilities
+ * ABI lookup from the generated registry (no fs — browser-pure) and
+ * ethers Contract construction helpers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAbi = void 0;
+exports.getAbi = getAbi;
+exports.createReadContract = createReadContract;
+exports.createWriteContract = createWriteContract;
+const ethers_1 = require("ethers");
+const abis_1 = require("./abis");
+/**
+ * Look up an ABI by its historical abi/ file base name (e.g. 'TaskManagerNew').
+ * Searches first-party POP ABIs, then the third-party probe-target ABIs.
+ *
+ * Returns a mutable-typed array (the registry consts are readonly) so ethers v5
+ * Interface construction typechecks.
+ */
+function getAbi(name) {
+    const abi = abis_1.ALL_ABIS[name] ?? abis_1.EXTERNAL_ABIS[name];
+    if (!abi) {
+        throw new Error(`ABI not found: ${name}. Check that packages/core/src/abis exports it (yarn gen-abis).`);
+    }
+    return abi;
+}
+/** Back-compat alias — the CLI's fs-based loader was named loadAbi. */
+exports.loadAbi = getAbi;
+/**
+ * Create a read-only contract instance.
+ */
+function createReadContract(address, abiName, provider) {
+    return new ethers_1.ethers.Contract(address, getAbi(abiName), provider);
+}
+/**
+ * Create a writable contract instance (with signer).
+ */
+function createWriteContract(address, abiName, signer) {
+    return new ethers_1.ethers.Contract(address, getAbi(abiName), signer);
+}