@pafi-dev/core 0.3.0-beta.8 → 0.4.0

package/dist/index.d.ts

@@ -1,14 +1,14 @@
-import { Address, Hex, PublicClient, WalletClient } from 'viem';
+import { Address, Hex, PublicClient, HttpTransport, WalletClient } from 'viem';
 import { P as PoolKey, C as ChainConfig, a as PafiSDKConfig, b as PointTokenDomainConfig, M as MintRequest, R as ReceiverConsent, E as EIP712Signature, S as SignatureVerification, B as BestQuote, Q as QuoteResult } from './types-b5_Tokjl.js';
 export { c as BurnRequest, I as Issuer, d as PathKey } from './types-b5_Tokjl.js';
 export { erc20Abi, issuerRegistryAbi, mintingOracleAbi, permit2Abi, pointTokenAbi, pointTokenFactoryAbi, universalRouterAbi, v4QuoterAbi } from './abi/index.js';
 export { buildBurnRequestTypedData, buildDomain, buildMintRequestTypedData, buildReceiverConsentTypedData, signBurnRequest, signMintRequest, signReceiverConsent, verifyBurnRequest, verifyMintRequest, verifyReceiverConsent } from './eip712/index.js';
 export { getIssuer, getMintRequestNonce, getPointTokenBalance, getPointTokenIssuer, getPointTokenIssuerAddress, getReceiverConsentNonce, getTokenName, isActiveIssuer, isMinter, verifyMintCap } from './contract/index.js';
 export { buildAllPaths, combineRoutes, findBestQuote, quoteBestRoute, quoteExactInput, quoteExactInputSingle } from './quoting/index.js';
-import { P as PartialUserOperation, O as Operation, U as UserOperation, S as SwapSimulationResult } from './index-B06IJlHe.js';
-export { B as BuildSwapWithGasDeductionParams, E as ENTRY_POINT_V07, a as PaymasterFields, b as SETTLE_ALL, c as SWAP_EXACT_IN, T as TAKE_ALL, d as UserOpReceipt, V as V4_SWAP, Z as ZERO_VALUE, e as buildErc20ApprovalCalldata, f as buildPermit2ApprovalCalldata, g as buildSwapFromQuote, h as buildSwapWithGasDeduction, i as buildUniversalRouterExecuteArgs, j as buildV4SwapInput, k as checkAllowance, s as simulateSwap } from './index-B06IJlHe.js';
+import { P as PartialUserOperation, O as Operation, U as UserOperation, S as SwapSimulationResult } from './index-C1FGQ004.js';
+export { B as BuildSwapWithGasDeductionParams, E as ENTRY_POINT_V07, a as PaymasterFields, b as SETTLE_ALL, c as SWAP_EXACT_IN, T as TAKE_ALL, d as UserOpReceipt, V as V4_SWAP, Z as ZERO_VALUE, e as buildErc20ApprovalCalldata, f as buildPermit2ApprovalCalldata, g as buildSwapFromQuote, h as buildSwapWithGasDeduction, i as buildUniversalRouterExecuteArgs, j as buildV4SwapInput, k as checkAllowance, s as simulateSwap } from './index-C1FGQ004.js';
 import { LoginMessageParams } from './auth/index.js';
-export { VerifyLoginResult, createLoginMessage, parseLoginMessage, verifyLoginMessage } from './auth/index.js';
+export { SPONSOR_AUTH_DOMAIN_NAME, SPONSOR_AUTH_TYPES, SponsorAuthPayload, SponsorAuthVerifyResult, VerifyLoginResult, buildSponsorAuthDomain, buildSponsorAuthTypedData, computeCallDataHash, createLoginMessage, parseLoginMessage, signSponsorAuth, verifyLoginMessage, verifySponsorAuth } from './auth/index.js';
 
 declare const mintRequestTypes: {
     readonly MintRequest: readonly [{
@@ -117,7 +117,7 @@ declare class ApiError extends PafiSDKError {
  *
  * ## Sponsored vs direct
  *
- * Coinbase Paymaster sponsors GAS, not `msg.value`. So even on the
+ * ERC-4337 paymasters sponsor GAS, not `msg.value`. Even on the
  * sponsored path the user MUST hold enough native ETH on Base to cover
  * `getDepositFee()` (typically ~0.0002 ETH at quiet times).
  */
@@ -539,200 +539,180 @@ interface CheckEthAndBranchParams {
 declare function checkEthAndBranch(params: CheckEthAndBranchParams): Promise<SubmissionPath>;
 
 /**
- * Identifies the user-flow scenario the sponsorship covers. Used by
- * sponsor-relayer for per-scenario rate limits + by Privy verifier
- * to log sponsorship reason.
+ * Parse the implementation address out of an EIP-7702 delegation designator.
  *
- * Keep in sync with `SponsorshipScenario` in the paymaster module —
- * SponsorAuth replaces the Coinbase paymaster flow but reuses the
- * scenario taxonomy.
+ * Returns `null` when:
+ *   - `code` is undefined / empty / `"0x"` (plain EOA, no code)
+ *   - `code` does not contain the EIP-7702 magic prefix (regular contract)
+ *
+ * @param code - bytecode returned by `eth_getCode` / `client.getCode()`
+ * @returns the 20-byte implementation address (checksummed), or `null`
+ *
+ * @example
+ * const code = await client.getCode({ address });
+ * const impl = parseEip7702DelegatedAddress(code);
+ * // null  → not delegated
+ * // '0x7702cb554e6bFb442cb743A7dF23154544a7176C' → delegated to BatchExecutor
  */
-type SponsorAuthScenario = "mint" | "burn" | "swap" | "perp_deposit";
+declare function parseEip7702DelegatedAddress(code: Hex | string | null | undefined): Address | null;
 /**
- * Canonical SponsorAuth payload — the EIP-712 message that PAFI
- * sponsor-relayer signs and Privy native verifies before funding gas.
+ * Read the EIP-7702 delegation status of an EOA from the chain.
  *
- * See `SPONSOR_AUTH_DESIGN.md` for full architecture.
+ * @param client  - viem PublicClient (any provider — only `eth_getCode` is called)
+ * @param address - EOA address to inspect
+ * @returns the implementation address the EOA is delegated to, or `null`
  *
- * ## Replay protection layers
+ * @example
+ * const impl = await checkDelegation(publicClient, userAddress);
+ * if (impl === null) {
+ *   // show "Setup Wallet" button
+ * } else {
+ *   // EOA already delegated; safe to send UserOps
+ * }
+ */
+declare function checkDelegation(client: PublicClient, address: Address): Promise<Address | null>;
+/**
+ * Return `true` when the EOA at `address` is currently delegated to `target`.
  *
- *   - `nonce`        — per-(sender, scenario), allocated by sponsor-relayer
- *   - `expiresAt`    — short window (60-120s recommended)
- *   - `callDataHash` — binds payload to ONE specific UserOp callData
- *   - `sender`       — binds to one EOA
- *   - `chainId`      — binds to one chain
+ * Useful for asserting that the delegation points specifically at the expected
+ * BatchExecutor rather than some other implementation (e.g. old deployment).
  *
- * Mutation of any field invalidates the signature.
+ * @example
+ * import { BATCH_EXECUTOR_ADDRESS_BASE_MAINNET } from '@pafi-dev/core';
+ * const ok = await isDelegatedTo(client, userAddress, BATCH_EXECUTOR_ADDRESS_BASE_MAINNET);
  */
-interface SponsorAuthPayload {
-    chainId: number;
-    sender: Address;
-    /** keccak256(userOp.callData) — caller computes from the UserOp they intend to submit. */
-    callDataHash: Hex;
-    /** Per-(sender, scenario) monotonic counter from sponsor-relayer. */
-    nonce: bigint;
-    /** Unix seconds. After this, Privy verifier rejects. */
-    expiresAt: number;
-    scenario: SponsorAuthScenario;
-    /** Issuer that originated this sponsorship request (e.g. "gg56"). */
-    issuerId: string;
-}
+declare function isDelegatedTo(client: PublicClient, address: Address, target: Address): Promise<boolean>;
+
 /**
- * Optional extension fields — keep separate so the canonical payload
- * stays minimal. Privy verifier may or may not enforce these depending
- * on dashboard config.
+ * Parameters for building a delegation-only UserOperation.
+ *
+ * This UserOp carries no calldata — its sole purpose is to anchor the
+ * EIP-7702 authorization (signed externally via `signAuthorization`) into
+ * a sponsored transaction so the user doesn't need native ETH to delegate.
  */
-interface SponsorAuthPayloadExtended extends SponsorAuthPayload {
-    /** Max gas (units) sponsor-relayer pre-approved. */
-    maxGasLimit?: bigint;
-    /** Max gas price (wei) sponsor-relayer pre-approved. */
-    maxGasPrice?: bigint;
-    /** Audit metadata — surfaced in logs only, not used for verification. */
-    intent?: {
-        amount?: string;
-        pointToken?: Address;
-        targetContract?: Address;
+interface BuildDelegationUserOpParams {
+    /** User EOA to delegate. */
+    userAddress: Address;
+    /** ERC-4337 account nonce — fetched from EntryPoint. Pass 0n on first ever op. */
+    aaNonce: bigint;
+    gasLimits?: {
+        callGasLimit?: bigint;
+        verificationGasLimit?: bigint;
+        preVerificationGas?: bigint;
     };
 }
 /**
- * EIP-712 domain for SponsorAuth signatures.
+ * Build the minimal `PartialUserOperation` used to sponsor the one-time
+ * EIP-7702 delegation.
  *
- * `verifyingContract` is `0x0` because verification is OFF-CHAIN
- * (Privy native verifier reads sig + payload, recovers signer,
- * compares with PAFI public key registered in Privy dashboard).
- * The domain is still EIP-712 to leverage existing tooling.
- */
-declare const SPONSOR_AUTH_DOMAIN_NAME: "PAFI SponsorAuth";
-declare const SPONSOR_AUTH_DOMAIN_VERSION: "1";
-/** EIP-712 typed-data shape — matches `SponsorAuthPayload` field order. */
-declare const SPONSOR_AUTH_TYPES: {
-    readonly SponsorAuth: readonly [{
-        readonly name: "chainId";
-        readonly type: "uint256";
-    }, {
-        readonly name: "sender";
-        readonly type: "address";
-    }, {
-        readonly name: "callDataHash";
-        readonly type: "bytes32";
-    }, {
-        readonly name: "nonce";
-        readonly type: "uint256";
-    }, {
-        readonly name: "expiresAt";
-        readonly type: "uint256";
-    }, {
-        readonly name: "scenario";
-        readonly type: "string";
-    }, {
-        readonly name: "issuerId";
-        readonly type: "string";
-    }];
-};
-/**
- * Build the EIP-712 domain object Privy verifier expects. Same
- * `chainId` as the SponsorAuth payload.
+ * The caller must:
+ *   1. Sign the EIP-7702 authorization via `signAuthorization()` (Privy hook).
+ *   2. Pass the authorization as `authorization` alongside `calls` (or alone)
+ *      to `smartClient.sendTransaction()`.
+ *
+ * The permissionless SDK + Pimlico bundler handle the rest: they detect the
+ * `authorization` field and submit an EIP-7702 type-4 transaction that sets
+ * the EOA's bytecode to `0xef0100<batchExecutorAddress>`.
+ *
+ * This builder is a convenience wrapper — in practice you can also pass
+ * `{ to: userAddress, value: 0n, data: '0x', authorization }` directly to
+ * `smartClient.sendTransaction()` without calling this function at all.
+ * Use it when you need a `PartialUserOperation` struct for inspection or
+ * custom paymaster flows.
+ *
+ * @example
+ * // Typical flow — no need to call this builder directly:
+ * const nonce = await publicClient.getTransactionCount({ address, blockTag: 'pending' });
+ * const authorization = await signAuthorization({ contractAddress: BATCH_EXECUTOR, chainId: 8453, nonce });
+ * const txHash = await smartClient.sendTransaction({
+ *   to: address,
+ *   value: 0n,
+ *   data: '0x',
+ *   authorization,
+ *   paymasterContext: { sponsorshipPolicyId },
+ * });
  */
-declare function buildSponsorAuthDomain(chainId: number): {
-    readonly name: "PAFI SponsorAuth";
-    readonly version: "1";
-    readonly chainId: number;
-    readonly verifyingContract: Address;
-};
-
+declare function buildDelegationUserOp(params: BuildDelegationUserOpParams): PartialUserOperation;
 /**
- * Build the EIP-712 typed data object for a SponsorAuth payload.
- * Returned shape is compatible with `walletClient.signTypedData()`,
- * `viem.recoverTypedDataAddress()`, and any other EIP-712 tooling.
+ * Fetch the AA nonce for a user EOA from the EntryPoint v0.7.
+ *
+ * Convenience helper so callers don't need to import the EntryPoint ABI
+ * themselves when building the delegation UserOp.
  *
- * Use this when you need the full typed-data object (e.g. to display
- * to a hardware-wallet user, or to feed into an off-chain audit log).
- * Most callers only need `signSponsorAuth` / `verifySponsorAuth` below.
+ * @param client     - viem PublicClient
+ * @param userAddress - EOA to query
+ * @returns bigint nonce (0n on first-ever UserOp)
  */
-declare function buildSponsorAuthTypedData(payload: SponsorAuthPayload): {
-    domain: {
-        readonly name: "PAFI SponsorAuth";
-        readonly version: "1";
-        readonly chainId: number;
-        readonly verifyingContract: Address;
-    };
-    types: {
-        readonly SponsorAuth: readonly [{
-            readonly name: "chainId";
-            readonly type: "uint256";
-        }, {
-            readonly name: "sender";
-            readonly type: "address";
-        }, {
-            readonly name: "callDataHash";
-            readonly type: "bytes32";
-        }, {
-            readonly name: "nonce";
-            readonly type: "uint256";
-        }, {
-            readonly name: "expiresAt";
-            readonly type: "uint256";
-        }, {
-            readonly name: "scenario";
-            readonly type: "string";
-        }, {
-            readonly name: "issuerId";
-            readonly type: "string";
-        }];
-    };
-    primaryType: "SponsorAuth";
-    message: {
-        chainId: bigint;
-        sender: `0x${string}`;
-        callDataHash: `0x${string}`;
-        nonce: bigint;
-        expiresAt: bigint;
-        scenario: SponsorAuthScenario;
-        issuerId: string;
-    };
-};
+declare function getAaNonce(client: PublicClient, userAddress: Address): Promise<bigint>;
+
 /**
- * Sign a SponsorAuth payload using a viem `WalletClient`. Production
- * sponsor-relayer should use a KMS-backed signer instead — this helper
- * is for tests + local dev where you hold a raw private key.
- *
- * Returns the **serialized 65-byte signature** ready to put into
- * `SponsorAuthResponse.sponsorAuth`.
+ * Parameters for `createPafiProxyTransport`.
  */
-declare function signSponsorAuth(walletClient: WalletClient, payload: SponsorAuthPayload): Promise<Hex>;
+interface PafiProxyTransportParams {
+    /**
+     * Full URL of the PAFI sponsor-relayer Pimlico proxy endpoint.
+     * @example "https://sponsor-relayer.pacificfinance.org/pimlico"
+     * @example "http://localhost:4000/pimlico"
+     */
+    proxyUrl: string;
+    /**
+     * Called on every request to get the current Privy identity token.
+     * Use a getter (or a ref's `.current`) so the transport always sends
+     * the latest token without needing to be rebuilt when it rotates.
+     *
+     * @example () => identityTokenRef.current
+     * @example () => privyHook.identityToken
+     */
+    getIdentityToken: () => string | null | undefined;
+    /**
+     * Issuer ID sent as `X-Issuer-Id` header.
+     * sponsor-relayer uses this to look up per-issuer rate limits and policy.
+     * Obtain from PAFI team during onboarding.
+     */
+    issuerId: string;
+}
 /**
- * Verify a SponsorAuth signature offline. Use to:
- *
- *   - Smoke-test that sponsor-relayer's output is well-formed (FE)
- *   - Unit tests in SDK
- *   - Defense-in-depth check before submitting to Privy
+ * Create a viem `HttpTransport` that proxies all Pimlico JSON-RPC calls
+ * through the PAFI sponsor-relayer (`POST /pimlico`).
  *
- * Privy verifier does the same check on their side — this is NOT a
- * substitute for Privy verification. It exists so consumers can fail
- * fast on a mangled sig before round-tripping through Privy.
+ * The transport:
+ *   - Sets `Authorization: Bearer <identityToken>` on every request
+ *   - Sets `X-Issuer-Id: <issuerId>` on every request
+ *   - Reads the identity token lazily via `getIdentityToken()` so it is
+ *     always fresh without rebuilding the SmartAccountClient on each rotation
  *
- * @param payload          The exact payload PAFI BE returned
- * @param signature        The serialized signature (sponsorAuth field)
- * @param expectedSigner   PAFI's SponsorAuth signing-key address
- *                         (registered in Privy dashboard)
+ * Pass the returned transport to both `createPimlicoClient` and
+ * `createSmartAccountClient` so ALL Pimlico RPC calls (paymaster + bundler)
+ * go through the proxy with auth headers attached.
  *
- * @returns `true` if signature recovers to `expectedSigner`,
- *          and the payload hasn't expired (`expiresAt > now`).
- *          Returns `false` on any failure — does NOT throw.
- */
-declare function verifySponsorAuth(payload: SponsorAuthPayload, signature: Hex, expectedSigner: Address): Promise<{
-    ok: boolean;
-    reason?: "INVALID_SIGNER" | "EXPIRED" | "INVALID_SIGNATURE_FORMAT";
-    recoveredAddress?: Address;
-}>;
-/**
- * Helper — compute `callDataHash` from a UserOperation's `callData`.
- * Same hash function (`keccak256`) Privy verifier uses.
+ * @example
+ * ```ts
+ * import { createPafiProxyTransport, BATCH_EXECUTOR_ADDRESS_BASE_MAINNET } from '@pafi-dev/core';
+ * import { createSmartAccountClient } from 'permissionless';
+ * import { createPimlicoClient } from 'permissionless/clients/pimlico';
+ * import { useIdentityToken } from '@privy-io/react-auth';
+ *
+ * const { identityToken } = useIdentityToken();
+ * const identityTokenRef = useRef<string | null>(null);
+ * useEffect(() => { identityTokenRef.current = identityToken; }, [identityToken]);
+ *
+ * const proxyTransport = createPafiProxyTransport({
+ *   proxyUrl: process.env.NEXT_PUBLIC_PIMLICO_PROXY_URL!,
+ *   getIdentityToken: () => identityTokenRef.current,
+ *   issuerId: process.env.NEXT_PUBLIC_ISSUER_ID!,
+ * });
  *
- * Bind this hash into the SponsorAuth payload BEFORE signing, so the
- * sig is invalid for any other UserOp.
+ * const pimlicoClient = createPimlicoClient({ chain: base, transport: proxyTransport });
+ * const smartClient  = createSmartAccountClient({
+ *   client: publicClient,
+ *   chain: base,
+ *   account,
+ *   paymaster: pimlicoClient,
+ *   bundlerTransport: proxyTransport,
+ * });
+ * ```
  */
-declare function computeCallDataHash(callData: Hex): Hex;
+declare function createPafiProxyTransport(params: PafiProxyTransportParams): HttpTransport;
 
 /**
  * Real `PointToken` ABI — matches the contract deployed on Base mainnet
@@ -1489,4 +1469,4 @@ declare class PafiSDK {
     signLoginMessage(message: string): Promise<Hex>;
 }
 
-export { ApiError, BATCH_EXECUTOR_ABI, BATCH_EXECUTOR_ADDRESS_BASE_MAINNET, BATCH_EXECUTOR_ADDRESS_BASE_SEPOLIA, BROKER_HASHES, BestQuote, type BuildPartialUserOpParams, type BuildPerpDepositWithGasDeductionParams, COMMON_POOLS, COMMON_TOKENS, CONTRACT_ADDRESSES, ChainConfig, type CheckEthAndBranchParams, ConfigurationError, type ContractAddresses, EIP712Signature, LoginMessageParams, MintRequest, type ModalOpenOptions, ORDERLY_VAULT_ABI, ORDERLY_VAULT_ADDRESSES, ORDERLY_VAULT_BASE_MAINNET, Operation, POINT_TOKEN_FACTORY_ADDRESSES, POINT_TOKEN_IMPL_ADDRESSES, POINT_TOKEN_POOLS, POINT_TOKEN_ABI as POINT_TOKEN_V2_ABI, PafiSDK, PafiSDKConfig, PafiSDKError, type PafiWebModalAdapter, type PafiWebModalHandle, PartialUserOperation, type PaymasterConfig, PointTokenDomainConfig, PoolKey, QuoteResult, ReceiverConsent, SPONSOR_AUTH_DOMAIN_NAME, SPONSOR_AUTH_DOMAIN_VERSION, SPONSOR_AUTH_TYPES, SUPPORTED_CHAINS, type SignatureStruct, SignatureVerification, SigningError, SimulationError, type SponsorAuthPayload, type SponsorAuthPayloadExtended, type SponsorAuthScenario, type SponsorshipScenario, type SubmissionPath, SwapSimulationResult, TOKEN_HASHES, UNIVERSAL_ROUTER_ADDRESSES, UserOperation, V4_QUOTER_ADDRESSES, type VaultDepositFE, _resetPaymasterConfigForTests, assembleUserOperation, buildPartialUserOperation, buildPerpDepositWithGasDeduction, buildSponsorAuthDomain, buildSponsorAuthTypedData, burnRequestTypes, checkEthAndBranch, computeAccountId, computeCallDataHash, encodeBatchExecute, erc20ApproveOp, erc20BurnOp, erc20TransferOp, getContractAddresses, getPafiWebModalAdapter, getPaymasterConfig, isPaymasterConfigured, mintRequestTypes, openPafiWebModal, openWebPopup, rawCallOp, receiverConsentTypes, setPafiWebModalAdapter, setPaymasterConfig, signSponsorAuth, verifySponsorAuth, webPopupAdapter };
+export { ApiError, BATCH_EXECUTOR_ABI, BATCH_EXECUTOR_ADDRESS_BASE_MAINNET, BATCH_EXECUTOR_ADDRESS_BASE_SEPOLIA, BROKER_HASHES, BestQuote, type BuildDelegationUserOpParams, type BuildPartialUserOpParams, type BuildPerpDepositWithGasDeductionParams, COMMON_POOLS, COMMON_TOKENS, CONTRACT_ADDRESSES, ChainConfig, type CheckEthAndBranchParams, ConfigurationError, type ContractAddresses, EIP712Signature, LoginMessageParams, MintRequest, type ModalOpenOptions, ORDERLY_VAULT_ABI, ORDERLY_VAULT_ADDRESSES, ORDERLY_VAULT_BASE_MAINNET, Operation, POINT_TOKEN_FACTORY_ADDRESSES, POINT_TOKEN_IMPL_ADDRESSES, POINT_TOKEN_POOLS, POINT_TOKEN_ABI as POINT_TOKEN_V2_ABI, type PafiProxyTransportParams, PafiSDK, PafiSDKConfig, PafiSDKError, type PafiWebModalAdapter, type PafiWebModalHandle, PartialUserOperation, type PaymasterConfig, PointTokenDomainConfig, PoolKey, QuoteResult, ReceiverConsent, SUPPORTED_CHAINS, type SignatureStruct, SignatureVerification, SigningError, SimulationError, type SponsorshipScenario, type SubmissionPath, SwapSimulationResult, TOKEN_HASHES, UNIVERSAL_ROUTER_ADDRESSES, UserOperation, V4_QUOTER_ADDRESSES, type VaultDepositFE, _resetPaymasterConfigForTests, assembleUserOperation, buildDelegationUserOp, buildPartialUserOperation, buildPerpDepositWithGasDeduction, burnRequestTypes, checkDelegation, checkEthAndBranch, computeAccountId, createPafiProxyTransport, encodeBatchExecute, erc20ApproveOp, erc20BurnOp, erc20TransferOp, getAaNonce, getContractAddresses, getPafiWebModalAdapter, getPaymasterConfig, isDelegatedTo, isPaymasterConfigured, mintRequestTypes, openPafiWebModal, openWebPopup, parseEip7702DelegatedAddress, rawCallOp, receiverConsentTypes, setPafiWebModalAdapter, setPaymasterConfig, webPopupAdapter };