@poa-box/core 0.1.0

package/dist/execute/sponsored.js

@@ -0,0 +1,277 @@
+"use strict";
+/**
+ * EIP-7702 Gas Sponsorship
+ *
+ * Uses the org PaymasterHub to sponsor agent transaction gas.
+ * Flow: Agent EOA → EIP-7702 delegation → UserOp via Pimlico bundler → PaymasterHub pays gas.
+ *
+ * Based on the poa-frontend EOA7702TransactionManager + userOpBuilder implementation.
+ *
+ * Prerequisites:
+ * - Agent registered in UniversalAccountRegistry
+ * - Agent wears a hat in the org
+ * - `pimlicoApiKey` or `bundlerUrl` provided via SponsoredSendOptions
+ *   (the CLI passes PIMLICO_API_KEY / POP_BUNDLER_URL from env)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENTRY_POINT = exports.PAYMASTER_HUB = exports.EOA_DELEGATION = void 0;
+exports.encodePaymasterData = encodePaymasterData;
+exports.isDelegated = isDelegated;
+exports.delegateEOA = delegateEOA;
+exports.getUserOpHash = getUserOpHash;
+exports.sendSponsored = sendSponsored;
+exports.encodeCall = encodeCall;
+const viem_1 = require("viem");
+const chains_1 = require("viem/chains");
+const accounts_1 = require("viem/accounts");
+const pimlico_1 = require("permissionless/clients/pimlico");
+const account_abstraction_1 = require("viem/account-abstraction");
+// Contract addresses (Gnosis)
+exports.EOA_DELEGATION = '0x776ec88A88E86e38d54a985983377f1A2A25ef8b';
+exports.PAYMASTER_HUB = '0xdEf1038C297493c0b5f82F0CDB49e929B53B4108';
+exports.ENTRY_POINT = account_abstraction_1.entryPoint07Address;
+const GAS_BUFFER_PERCENT = 10n;
+const DUMMY_ECDSA_SIGNATURE = ('0x' + 'ff'.repeat(65));
+/**
+ * Encode paymaster data for the PaymasterHub.
+ * Format: version(1) | orgId(32) | subjectType=0x01(1) | hatId(32) | ruleId(4) | mailboxCommit(8)
+ * Total: 78 bytes (must match frontend encoding exactly)
+ */
+function encodePaymasterData(orgId, hatId) {
+    const version = (0, viem_1.toHex)(0x01, { size: 1 });
+    const paddedOrgId = (0, viem_1.pad)(orgId, { size: 32 });
+    const subjectType = (0, viem_1.toHex)(0x01, { size: 1 }); // HAT
+    const paddedHatId = (0, viem_1.toHex)(hatId, { size: 32 });
+    const ruleId = (0, viem_1.toHex)(0, { size: 4 });
+    const mailboxCommit = (0, viem_1.toHex)(0n, { size: 8 });
+    return (0, viem_1.concat)([version, paddedOrgId, subjectType, paddedHatId, ruleId, mailboxCommit]);
+}
+/**
+ * Check if an EOA has already delegated to EOADelegation.
+ */
+async function isDelegated(address, rpcUrl) {
+    const client = (0, viem_1.createPublicClient)({
+        chain: chains_1.gnosis,
+        transport: (0, viem_1.http)(rpcUrl || 'https://rpc.gnosischain.com'),
+    });
+    const code = await client.getCode({ address });
+    return code !== undefined && code !== '0x' && code.startsWith('0xef0100');
+}
+/**
+ * Sign EIP-7702 authorization to delegate EOA to EOADelegation contract.
+ * This is a one-time setup — after delegation, the EOA can receive UserOps.
+ */
+async function delegateEOA(privateKey, rpcUrl) {
+    const account = (0, accounts_1.privateKeyToAccount)(privateKey);
+    const walletClient = (0, viem_1.createWalletClient)({
+        account,
+        chain: chains_1.gnosis,
+        transport: (0, viem_1.http)(rpcUrl || 'https://rpc.gnosischain.com'),
+    });
+    const authorization = await walletClient.signAuthorization({
+        contractAddress: exports.EOA_DELEGATION,
+        executor: 'self',
+    });
+    const hash = await walletClient.sendTransaction({
+        authorizationList: [authorization],
+        to: account.address,
+        data: '0x',
+    });
+    return hash;
+}
+/**
+ * Pack two uint128 values into a single bytes32.
+ * high128 || low128
+ */
+function packUint128Pair(high, low) {
+    return (0, viem_1.pad)((0, viem_1.toHex)((BigInt(high) << 128n) | BigInt(low)), { size: 32 });
+}
+function applyBuffer(value) {
+    return (BigInt(value) * (100n + GAS_BUFFER_PERCENT)) / 100n;
+}
+/**
+ * Compute the UserOp hash per EIP-4337 v0.7 (PackedUserOperation) spec.
+ * Ported from poa-frontend userOpBuilder.js getUserOpHash().
+ */
+function getUserOpHash(userOp, entryPoint, chainId) {
+    // Reconstruct paymasterAndData
+    let paymasterAndData = '0x';
+    if (userOp.paymaster) {
+        const pmVerGas = (0, viem_1.pad)((0, viem_1.toHex)(userOp.paymasterVerificationGasLimit || 0n), { size: 16 });
+        const pmPostGas = (0, viem_1.pad)((0, viem_1.toHex)(userOp.paymasterPostOpGasLimit || 0n), { size: 16 });
+        if (userOp.paymasterData && userOp.paymasterData !== '0x') {
+            paymasterAndData = (0, viem_1.concat)([userOp.paymaster, pmVerGas, pmPostGas, userOp.paymasterData]);
+        }
+        else {
+            paymasterAndData = (0, viem_1.concat)([userOp.paymaster, pmVerGas, pmPostGas]);
+        }
+    }
+    const accountGasLimits = packUint128Pair(userOp.verificationGasLimit, userOp.callGasLimit);
+    const gasFees = packUint128Pair(userOp.maxPriorityFeePerGas, userOp.maxFeePerGas);
+    const packed = (0, viem_1.encodeAbiParameters)((0, viem_1.parseAbiParameters)('address, uint256, bytes32, bytes32, bytes32, uint256, bytes32, bytes32'), [
+        userOp.sender,
+        userOp.nonce,
+        (0, viem_1.keccak256)('0x'), // no initCode for already-deployed EOA
+        (0, viem_1.keccak256)(userOp.callData),
+        accountGasLimits,
+        userOp.preVerificationGas,
+        gasFees,
+        (0, viem_1.keccak256)(paymasterAndData),
+    ]);
+    const userOpPacked = (0, viem_1.keccak256)(packed);
+    return (0, viem_1.keccak256)((0, viem_1.encodeAbiParameters)((0, viem_1.parseAbiParameters)('bytes32, address, uint256'), [userOpPacked, entryPoint, BigInt(chainId)]));
+}
+/**
+ * Send a sponsored transaction via Pimlico bundler.
+ * The PaymasterHub pays for gas — agent pays nothing.
+ *
+ * Follows the same flow as poa-frontend EOA7702TransactionManager:
+ * 1. Encode call in EOADelegation.execute() wrapper
+ * 2. Build UserOp with paymaster data and dummy signature
+ * 3. Estimate gas via bundler
+ * 4. Compute UserOp hash (EIP-4337 v0.7 packed format)
+ * 5. Sign with wallet (ECDSA via signMessage — EIP-191 prefix)
+ * 6. Submit to bundler and wait for receipt
+ */
+async function sendSponsored(privateKey, to, data, orgId, hatId, options) {
+    // Task #425: bundlerUrl (CLI: POP_BUNDLER_URL) for self-hosted bundler support.
+    // When set, uses the local bundler (e.g. Skandha at localhost:14337).
+    // When unset, falls back to Pimlico. Zero-downtime migration path.
+    const bundlerOverride = options?.bundlerUrl;
+    const apiKey = bundlerOverride ? null : options?.pimlicoApiKey;
+    if (!bundlerOverride && !apiKey) {
+        throw new Error('Set bundlerUrl (env: POP_BUNDLER_URL) for self-hosted bundler or pimlicoApiKey (env: PIMLICO_API_KEY) for Pimlico. See reports/research/self-hosted-bundler-research.md.');
+    }
+    const rpcUrl = options?.rpcUrl || 'https://rpc.gnosischain.com';
+    const account = (0, accounts_1.privateKeyToAccount)(privateKey);
+    const pimlicoUrl = bundlerOverride || `https://api.pimlico.io/v2/${chains_1.gnosis.id}/rpc?apikey=${apiKey}`;
+    // Check delegation
+    const delegated = await isDelegated(account.address, rpcUrl);
+    if (!delegated) {
+        throw new Error(`EOA ${account.address} not delegated to EOADelegation. ` +
+            `Run 'pop agent delegate' first to set up EIP-7702 delegation.`);
+    }
+    const walletClient = (0, viem_1.createWalletClient)({
+        account,
+        chain: chains_1.gnosis,
+        transport: (0, viem_1.http)(rpcUrl),
+    });
+    const publicClient = (0, viem_1.createPublicClient)({
+        chain: chains_1.gnosis,
+        transport: (0, viem_1.http)(rpcUrl),
+    });
+    const pimlicoClient = (0, pimlico_1.createPimlicoClient)({
+        chain: chains_1.gnosis,
+        transport: (0, viem_1.http)(pimlicoUrl),
+        entryPoint: {
+            address: exports.ENTRY_POINT,
+            version: '0.7',
+        },
+    });
+    // Encode paymaster data
+    const paymasterData = encodePaymasterData(orgId, hatId);
+    // EOADelegation.execute(target, value, data) — same ABI as PasskeyAccount.execute
+    const executeAbi = [{
+            name: 'execute',
+            type: 'function',
+            inputs: [
+                { name: 'target', type: 'address' },
+                { name: 'value', type: 'uint256' },
+                { name: 'data', type: 'bytes' },
+            ],
+            outputs: [],
+            stateMutability: 'nonpayable',
+        }];
+    const callData = (0, viem_1.encodeFunctionData)({
+        abi: executeAbi,
+        functionName: 'execute',
+        args: [to, options?.value || 0n, data],
+    });
+    // Fetch nonce and gas prices in parallel
+    const [nonce, gasPrices] = await Promise.all([
+        publicClient.readContract({
+            address: exports.ENTRY_POINT,
+            abi: account_abstraction_1.entryPoint07Abi,
+            functionName: 'getNonce',
+            args: [account.address, 0n],
+        }),
+        pimlicoClient.getUserOperationGasPrice(),
+    ]);
+    // Sign 7702 authorization (bundler includes it in the type-4 tx)
+    const authorization = await walletClient.signAuthorization({
+        contractAddress: exports.EOA_DELEGATION,
+    });
+    // Build UserOp with dummy signature for gas estimation
+    // Gas limits must stay within PaymasterHub fee caps (maxCallGas, maxVerificationGas, maxPreVerificationGas)
+    const userOp = {
+        sender: account.address,
+        nonce,
+        callData,
+        callGasLimit: 300000n,
+        verificationGasLimit: 300000n,
+        preVerificationGas: 80000n,
+        maxFeePerGas: gasPrices.fast.maxFeePerGas,
+        maxPriorityFeePerGas: gasPrices.fast.maxPriorityFeePerGas,
+        paymaster: exports.PAYMASTER_HUB,
+        paymasterVerificationGasLimit: 200000n,
+        paymasterPostOpGasLimit: 200000n,
+        paymasterData,
+        authorization,
+        signature: DUMMY_ECDSA_SIGNATURE,
+    };
+    // Estimate gas via bundler — catch validateUserOp errors from dummy signature
+    try {
+        const gasEstimate = await pimlicoClient.estimateUserOperationGas({
+            ...userOp,
+            entryPointAddress: exports.ENTRY_POINT,
+        });
+        // Apply gas estimates with buffer
+        userOp.callGasLimit = applyBuffer(gasEstimate.callGasLimit);
+        userOp.preVerificationGas = applyBuffer(gasEstimate.preVerificationGas);
+        // ECDSA verification is cheap (~3k gas), but enforce a minimum
+        const estimatedVerification = applyBuffer(gasEstimate.verificationGasLimit);
+        userOp.verificationGasLimit = estimatedVerification < 100000n ? 100000n : estimatedVerification;
+        if (gasEstimate.paymasterVerificationGasLimit) {
+            userOp.paymasterVerificationGasLimit = applyBuffer(gasEstimate.paymasterVerificationGasLimit);
+        }
+        if (gasEstimate.paymasterPostOpGasLimit) {
+            userOp.paymasterPostOpGasLimit = applyBuffer(gasEstimate.paymasterPostOpGasLimit);
+        }
+    }
+    catch (estimateError) {
+        const msg = estimateError.message || '';
+        // Paymaster rejections should propagate — caller needs to know
+        if (msg.includes('AA31') || msg.includes('AA32') || msg.includes('AA33')) {
+            throw estimateError;
+        }
+        // validateUserOp fails with dummy sig — use generous defaults
+        // (same pattern as poa-frontend estimateGas() fallback)
+    }
+    // Compute UserOp hash (EIP-4337 v0.7 packed format)
+    const computedHash = getUserOpHash(userOp, exports.ENTRY_POINT, chains_1.gnosis.id);
+    // Sign with wallet — EOADelegation validates via toEthSignedMessageHash(userOpHash)
+    const signature = await walletClient.signMessage({
+        message: { raw: computedHash },
+    });
+    userOp.signature = signature;
+    // Submit to bundler
+    const submittedHash = await pimlicoClient.sendUserOperation({
+        ...userOp,
+        entryPointAddress: exports.ENTRY_POINT,
+    });
+    // Wait for receipt
+    const receipt = await pimlicoClient.waitForUserOperationReceipt({
+        hash: submittedHash,
+        timeout: 120_000,
+    });
+    return {
+        txHash: receipt.receipt.transactionHash,
+        userOpHash: submittedHash,
+    };
+}
+/**
+ * Helper: encode a contract function call for use with sendSponsored.
+ */
+function encodeCall(abi, functionName, args) {
+    return (0, viem_1.encodeFunctionData)({ abi, functionName, args });
+}

package/dist/exit-codes.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Exit Codes
+ * Single source of truth for process exit codes across the CLI.
+ */
+export declare const EXIT: {
+    /** Success */
+    readonly OK: 0;
+    /** Bad or missing input, unknown entity, generic usage error */
+    readonly USAGE: 1;
+    /** Transaction reverted or gas estimation revealed a revert (existing convention) */
+    readonly TX_FAILED: 2;
+    /** Infrastructure unavailable: RPC, subgraph, or IPFS (matches NetworkError/SubgraphError/IpfsError code 3) */
+    readonly INFRA: 3;
+    /** Pre-flight check failed: wrong status, not a member, duplicate suspected */
+    readonly PRECONDITION: 4;
+    /** User declined confirmation, or non-TTY destructive write without --yes */
+    readonly ABORTED: 5;
+};

package/dist/exit-codes.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Exit Codes
+ * Single source of truth for process exit codes across the CLI.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXIT = void 0;
+exports.EXIT = {
+    /** Success */
+    OK: 0,
+    /** Bad or missing input, unknown entity, generic usage error */
+    USAGE: 1,
+    /** Transaction reverted or gas estimation revealed a revert (existing convention) */
+    TX_FAILED: 2,
+    /** Infrastructure unavailable: RPC, subgraph, or IPFS (matches NetworkError/SubgraphError/IpfsError code 3) */
+    INFRA: 3,
+    /** Pre-flight check failed: wrong status, not a member, duplicate suspected */
+    PRECONDITION: 4,
+    /** User declined confirmation, or non-TTY destructive write without --yes */
+    ABORTED: 5,
+};

package/dist/format.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Display Formatting Helpers
+ * Pure functions for tokens, times, and USD amounts.
+ * Time functions accept an injectable `now` (unix seconds) for testability.
+ *
+ * NOTE: statusColor (chalk-based) did NOT move here — it stays CLI-side.
+ */
+import { ethers } from 'ethers';
+/**
+ * Format a wei-denominated amount as a human string, e.g. "12.5 PT".
+ * Trims trailing zeros, adds thousands separators to the integer part,
+ * shows at most 4 decimal places — unless the value is nonzero and
+ * < 0.0001, in which case full precision is kept.
+ */
+export declare function formatToken(wei: ethers.BigNumberish, decimals?: number, symbol?: string): string;
+/** "3h ago" for past timestamps, "in 2d" for future ones. */
+export declare function formatRelativeTime(unixSecs: number | string, now?: number): string;
+/** "2d 4h left" | "expired 3h ago" | "none" for a zero deadline. */
+export declare function formatCountdown(deadlineUnixSecs: number, now?: number): string;
+/** "$1,234.50" */
+export declare function formatUsd(n: number): string;

package/dist/format.js

@@ -0,0 +1,89 @@
+"use strict";
+/**
+ * Display Formatting Helpers
+ * Pure functions for tokens, times, and USD amounts.
+ * Time functions accept an injectable `now` (unix seconds) for testability.
+ *
+ * NOTE: statusColor (chalk-based) did NOT move here — it stays CLI-side.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatToken = formatToken;
+exports.formatRelativeTime = formatRelativeTime;
+exports.formatCountdown = formatCountdown;
+exports.formatUsd = formatUsd;
+const ethers_1 = require("ethers");
+function nowSecs() {
+    return Math.floor(Date.now() / 1000);
+}
+function addThousandsSeparators(intPart) {
+    return intPart.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+/**
+ * Format a wei-denominated amount as a human string, e.g. "12.5 PT".
+ * Trims trailing zeros, adds thousands separators to the integer part,
+ * shows at most 4 decimal places — unless the value is nonzero and
+ * < 0.0001, in which case full precision is kept.
+ */
+function formatToken(wei, decimals = 18, symbol) {
+    const raw = ethers_1.ethers.utils.formatUnits(wei, decimals);
+    let [intPart, fracPart = ''] = raw.split('.');
+    const negative = intPart.startsWith('-');
+    if (negative)
+        intPart = intPart.slice(1);
+    fracPart = fracPart.replace(/0+$/, '');
+    let frac = fracPart;
+    if (fracPart.length > 4) {
+        const isSubDust = /^0+$/.test(intPart) && /^0{4}/.test(fracPart);
+        if (!isSubDust) {
+            frac = fracPart.slice(0, 4).replace(/0+$/, '');
+        }
+    }
+    let result = addThousandsSeparators(intPart) + (frac ? '.' + frac : '');
+    if (negative && !/^0(\.0*)?$/.test(result))
+        result = '-' + result;
+    return symbol ? `${result} ${symbol}` : result;
+}
+/** Bucket a positive elapsed/remaining span in seconds: s/m/h/d/mo. */
+function bucket(seconds) {
+    const abs = Math.abs(Math.round(seconds));
+    if (abs < 60)
+        return `${abs}s`;
+    if (abs < 3600)
+        return `${Math.floor(abs / 60)}m`;
+    if (abs < 86400)
+        return `${Math.floor(abs / 3600)}h`;
+    if (abs < 30 * 86400)
+        return `${Math.floor(abs / 86400)}d`;
+    return `${Math.floor(abs / (30 * 86400))}mo`;
+}
+/** "3h ago" for past timestamps, "in 2d" for future ones. */
+function formatRelativeTime(unixSecs, now = nowSecs()) {
+    const ts = Number(unixSecs);
+    const diff = now - ts;
+    if (diff >= 0)
+        return `${bucket(diff)} ago`;
+    return `in ${bucket(-diff)}`;
+}
+/** "2d 4h left" | "expired 3h ago" | "none" for a zero deadline. */
+function formatCountdown(deadlineUnixSecs, now = nowSecs()) {
+    if (deadlineUnixSecs === 0)
+        return 'none';
+    const remaining = deadlineUnixSecs - now;
+    if (remaining <= 0)
+        return `expired ${bucket(-remaining)} ago`;
+    const d = Math.floor(remaining / 86400);
+    const h = Math.floor((remaining % 86400) / 3600);
+    const m = Math.floor((remaining % 3600) / 60);
+    const s = remaining % 60;
+    if (d > 0)
+        return `${d}d ${h}h left`;
+    if (h > 0)
+        return `${h}h ${m}m left`;
+    if (m > 0)
+        return `${m}m left`;
+    return `${s}s left`;
+}
+/** "$1,234.50" */
+function formatUsd(n) {
+    return n.toLocaleString('en-US', { style: 'currency', currency: 'USD' });
+}