@pafi-dev/core 0.3.0-beta.1 → 0.3.0-beta.11

package/dist/index.d.cts

@@ -1,14 +1,12 @@
 import { Address, Hex, PublicClient, WalletClient } from 'viem';
-import { P as PoolKey, C as ChainConfig, a as PointTokenDomainConfig, E as EIP712Signature, S as SignatureVerification, b as PafiSDKConfig, M as MintRequest, R as ReceiverConsent, c as MintParams, d as SwapParams, B as BestQuote, Q as QuoteResult, e as PathKey } from './types-BDOnH5Le.cjs';
-export { I as Issuer } from './types-BDOnH5Le.cjs';
-export { erc20Abi, issuerRegistryAbi, mintingOracleAbi, permit2Abi, pointTokenAbi, pointTokenFactoryAbi, relayAbi, universalRouterAbi, v4QuoterAbi } from './abi/index.cjs';
-export { buildDomain, buildMintRequestTypedData, buildReceiverConsentTypedData, signMintRequest, signReceiverConsent, verifyMintRequest, verifyReceiverConsent } from './eip712/index.cjs';
-import { SimulationResult } from './relay/index.cjs';
-export { buildRelaySwapParams, decodeExtData, decodeMintAndSwap, encodeExtData, encodeMintAndSwap, simulateMintAndSwap } from './relay/index.cjs';
-export { getIssuer, getMintRequestNonce, getPointTokenBalance, getPointTokenIssuer, getPointTokenIssuerAddress, getReceiverConsentNonce, getTokenName, getUsdt, isActiveIssuer, isMinter, verifyMintCap } from './contract/index.cjs';
+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.cjs';
+export { c as BurnRequest, I as Issuer, d as PathKey } from './types-b5_Tokjl.cjs';
+export { erc20Abi, issuerRegistryAbi, mintingOracleAbi, permit2Abi, pointTokenAbi, pointTokenFactoryAbi, universalRouterAbi, v4QuoterAbi } from './abi/index.cjs';
+export { buildBurnRequestTypedData, buildDomain, buildMintRequestTypedData, buildReceiverConsentTypedData, signBurnRequest, signMintRequest, signReceiverConsent, verifyBurnRequest, verifyMintRequest, verifyReceiverConsent } from './eip712/index.cjs';
+export { getIssuer, getMintRequestNonce, getPointTokenBalance, getPointTokenIssuer, getPointTokenIssuerAddress, getReceiverConsentNonce, getTokenName, isActiveIssuer, isMinter, verifyMintCap } from './contract/index.cjs';
 export { buildAllPaths, combineRoutes, findBestQuote, quoteBestRoute, quoteExactInput, quoteExactInputSingle } from './quoting/index.cjs';
-import { O as Operation, P as PartialUserOperation, U as UserOperation, S as SwapSimulationResult } from './index-BpUYHGu3.cjs';
-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-BpUYHGu3.cjs';
+import { P as PartialUserOperation, O as Operation, U as UserOperation, S as SwapSimulationResult } from './index-B7pGBych.cjs';
+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-B7pGBych.cjs';
 import { LoginMessageParams } from './auth/index.cjs';
 export { VerifyLoginResult, createLoginMessage, parseLoginMessage, verifyLoginMessage } from './auth/index.cjs';
 
@@ -27,6 +25,21 @@ declare const mintRequestTypes: {
         readonly type: "uint256";
     }];
 };
+declare const burnRequestTypes: {
+    readonly BurnRequest: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }];
+};
 declare const receiverConsentTypes: {
     readonly ReceiverConsent: readonly [{
         readonly name: "onBehalfOf";
@@ -74,6 +87,256 @@ declare class ApiError extends PafiSDKError {
     constructor(message: string, status?: number | undefined);
 }
 
+/**
+ * Orderly Network Vault — entrypoint for **perp deposit** flow on
+ * Base mainnet (Scenario 3).
+ *
+ * Source of truth for addresses + integration:
+ *   https://orderly.network/docs/build-on-omnichain/addresses#base
+ *
+ * ## Architecture
+ *
+ *   User wallet (Base)
+ *      │ 1. USDC.approve(vault, amount)
+ *      │ 2. vault.deposit{value: layerZeroFee}({
+ *      │      accountId, brokerHash, tokenHash, tokenAmount
+ *      │    })
+ *      ▼
+ *   OrderlyVault (Base)
+ *      │ — locks USDC, emits LayerZero message
+ *      ▼
+ *   Orderly chain (off-chain matching engine)
+ *      │ — credits the user's perp account
+ *      ▼
+ *   User can now place perp orders via Orderly REST/WS API
+ *
+ * **Important:** `value` is required and is the LayerZero cross-chain
+ * fee (paid in native ETH on Base). Quote it via
+ * `vault.getDepositFee(user, data)` BEFORE calling deposit. Fees vary
+ * with destination chain congestion.
+ *
+ * ## Sponsored vs direct
+ *
+ * Coinbase Paymaster sponsors GAS, not `msg.value`. So even on the
+ * sponsored path the user MUST hold enough native ETH on Base to cover
+ * `getDepositFee()` (typically ~0.0002 ETH at quiet times).
+ */
+/** Orderly Vault on Base mainnet (EIP-55 checksum). */
+declare const ORDERLY_VAULT_BASE_MAINNET: Address;
+/**
+ * Per-chain registry of the Orderly Vault. Add chains here as Orderly
+ * deploys them.
+ */
+declare const ORDERLY_VAULT_ADDRESSES: Record<number, Address>;
+/**
+ * Pre-computed broker hashes — `keccak256(abi.encodePacked(brokerId))`.
+ * Add new brokers as they launch.
+ *
+ * Reference: https://orderly.network/docs/build-on-omnichain/user-flows/accountId
+ */
+declare const BROKER_HASHES: {
+    /** Default partner broker on Base — most commonly whitelisted. */
+    readonly woofi_pro: `0x${string}`;
+    /** Orderly's own white-label broker. */
+    readonly orderly: `0x${string}`;
+    /** LogX. */
+    readonly logx: `0x${string}`;
+};
+/**
+ * Pre-computed token hashes — `keccak256(abi.encodePacked(tokenSymbol))`.
+ * The hash maps to the actual ERC-20 address on each chain via
+ * `vault.getAllowedToken(tokenHash)`.
+ *
+ * Note: Orderly canonicalises by symbol (USDC, not "USD Coin").
+ */
+declare const TOKEN_HASHES: {
+    readonly USDC: `0x${string}`;
+};
+/**
+ * Compute Orderly's `accountId` — uniquely identifies a user+broker
+ * tuple. Matches the off-chain formula used by the Orderly SDK so
+ * deposits + future REST API calls reference the same account.
+ *
+ *   accountId = keccak256(abi.encode(user, brokerHash))
+ *
+ * Note `abi.encode` (not `encodePacked`) — uses 32-byte left-padding.
+ */
+declare function computeAccountId(user: Address, brokerHash: Hex): Hex;
+/**
+ * Minimal Orderly Vault ABI — just the functions PAFI needs for
+ * Scenario 3 (perp deposit). Full ABI is on Orderly's docs site.
+ */
+declare const ORDERLY_VAULT_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "deposit";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly name: "data";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "accountId";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "brokerHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "tokenHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "tokenAmount";
+            readonly type: "uint128";
+        }];
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "getDepositFee";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "user";
+        readonly type: "address";
+    }, {
+        readonly name: "data";
+        readonly type: "tuple";
+        readonly components: readonly [{
+            readonly name: "accountId";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "brokerHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "tokenHash";
+            readonly type: "bytes32";
+        }, {
+            readonly name: "tokenAmount";
+            readonly type: "uint128";
+        }];
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "getAllowedBroker";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "brokerHash";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "getAllowedToken";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "tokenHash";
+        readonly type: "bytes32";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}];
+/** Struct mirror of `IOrderlyVault.VaultDepositFE` for type-safe builders. */
+interface VaultDepositFE {
+    accountId: Hex;
+    brokerHash: Hex;
+    tokenHash: Hex;
+    /** uint128 — USDC has 6 decimals. */
+    tokenAmount: bigint;
+}
+
+/**
+ * v1.5 — Scenario 3: deposit USDC from the user's wallet into the
+ * Orderly perp Vault on Base mainnet.
+ *
+ * Builds a `PartialUserOperation` packaging the 2 inner calls:
+ *
+ *   1. `USDC.approve(orderlyVault, amount)` — let the Vault pull USDC
+ *   2. `OrderlyVault.deposit{value: layerZeroFee}(VaultDepositFE)` —
+ *      transfer USDC into the Vault + emit a LayerZero message that
+ *      credits the user's perp account on the Orderly chain
+ *
+ * ## ⚠️ Native ETH constraint
+ *
+ * Coinbase Paymaster sponsors GAS, **not `msg.value`**. The LayerZero
+ * cross-chain fee MUST come from the user's own native ETH balance on
+ * Base — even when the rest of the UserOp is sponsored.
+ *
+ * Quote the fee BEFORE calling this builder via:
+ *
+ *   const fee = await client.readContract({
+ *     address: orderlyVault,
+ *     abi: ORDERLY_VAULT_ABI,
+ *     functionName: 'getDepositFee',
+ *     args: [user, depositData],
+ *   });
+ *
+ * If `user.eth < fee`, surface this error to the FE so the user can
+ * top up before retrying — the Vault `deposit{value: 0}` call will
+ * revert otherwise.
+ *
+ * ## Why no PT/USDC fee deduction?
+ *
+ * Unlike Scenario 1/2/4 which deduct an operator fee in PT/USDC inside
+ * the batch, perp deposit doesn't append a fee transfer because:
+ *
+ *   - User is paying Orderly's LayerZero fee directly via `msg.value`
+ *   - There's no PAFI-specific operator cost on top — Orderly handles
+ *     the off-chain accounting once the LayerZero message lands
+ *
+ * If we want to charge a PAFI service fee on top later, append a
+ * `USDC.transfer(feeRecipient, fee)` op — same pattern as the swap
+ * builder.
+ */
+interface BuildPerpDepositWithGasDeductionParams {
+    /** User EOA (will be `msg.sender` via EIP-7702 delegation). */
+    userAddress: Address;
+    /** ERC-4337 account nonce — fetched from EntryPoint by the caller. */
+    aaNonce: bigint;
+    /** Chain ID for Orderly Vault address resolution. */
+    chainId: number;
+    /**
+     * Override Orderly Vault address (e.g. for fork tests). Defaults to
+     * `ORDERLY_VAULT_ADDRESSES[chainId]`.
+     */
+    vaultAddress?: Address;
+    /**
+     * USDC ERC-20 address — the actual token Orderly accepts. Caller
+     * resolves this via `vault.getAllowedToken(TOKEN_HASHES.USDC)` so we
+     * don't hardcode the wrong USDC variant (native vs bridged).
+     */
+    usdcAddress: Address;
+    /** USDC amount to deposit (uint128, 6 decimals). */
+    amount: bigint;
+    /**
+     * Pre-built `VaultDepositFE` struct — caller computes accountId via
+     * `computeAccountId(user, brokerHash)` and supplies tokenHash.
+     */
+    depositData: VaultDepositFE;
+    /**
+     * LayerZero fee in wei — from `vault.getDepositFee(user, data)`.
+     * Becomes the `msg.value` on the `deposit()` call. User MUST hold
+     * ≥ this much native ETH or the call reverts.
+     */
+    layerZeroFee: bigint;
+    gasLimits?: {
+        callGasLimit?: bigint;
+        verificationGasLimit?: bigint;
+        preVerificationGas?: bigint;
+    };
+}
+/**
+ * Build an unsigned UserOp for Scenario 3. Returns a
+ * `PartialUserOperation` — caller attaches paymaster sponsorship for
+ * gas + the user's UserOp-hash signature, then submits to the Bundler.
+ */
+declare function buildPerpDepositWithGasDeduction(params: BuildPerpDepositWithGasDeductionParams): PartialUserOperation;
+
 /**
  * Build an ERC-20 `transfer(to, amount)` operation. Used inside a batch
  * to move fee tokens from the user to the fee recipient atomically with
@@ -276,238 +539,393 @@ interface CheckEthAndBranchParams {
 declare function checkEthAndBranch(params: CheckEthAndBranchParams): Promise<SubmissionPath>;
 
 /**
- * ⚠️ MOCK — Relayer v2 `mint()` ABI for the v1.4 sponsored flow.
+ * Parse the implementation address out of an EIP-7702 delegation designator.
+ *
+ * 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
+ */
+declare function parseEip7702DelegatedAddress(code: Hex | string | null | undefined): Address | null;
+/**
+ * Read the EIP-7702 delegation status of an EOA from the chain.
+ *
+ * @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`
+ *
+ * @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`.
+ *
+ * Useful for asserting that the delegation points specifically at the expected
+ * BatchExecutor rather than some other implementation (e.g. old deployment).
+ *
+ * @example
+ * import { BATCH_EXECUTOR_ADDRESS_BASE_MAINNET } from '@pafi-dev/core';
+ * const ok = await isDelegatedTo(client, userAddress, BATCH_EXECUTOR_ADDRESS_BASE_MAINNET);
+ */
+declare function isDelegatedTo(client: PublicClient, address: Address, target: Address): Promise<boolean>;
+
+/**
+ * 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 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;
+    };
+}
+/**
+ * Build the minimal `PartialUserOperation` used to sponsor the one-time
+ * EIP-7702 delegation.
+ *
+ * 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 buildDelegationUserOp(params: BuildDelegationUserOpParams): PartialUserOperation;
+/**
+ * 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.
+ *
+ * @param client     - viem PublicClient
+ * @param userAddress - EOA to query
+ * @returns bigint nonce (0n on first-ever UserOp)
+ */
+declare function getAaNonce(client: PublicClient, userAddress: Address): Promise<bigint>;
+
+/**
+ * Real `PointToken` ABI — matches the contract deployed on Base mainnet
+ * (POINT at `0x7d25E7156E51F865D522fd3ef257a6B5DD41b97e`). Sourced from
+ * the Solidity contract shipped by the SC team 2026-04-21.
+ *
+ * ## Mint — two paths
  *
- * Signature guess based on stakeholder memo (`REQUIREMENTS_V2.md §3`):
+ *   Path 1 — Direct (whitelisted minter):
+ *     mint(address to, uint256 amount)
+ *     - msg.sender must be in minters[]
+ *     - Used by off-chain services that hold a minter key
  *
- *   mint(
- *     MintRequest request,      // EIP-712 signed by user + issuer
- *     Signature userSig,        // v, r, s
- *     Signature issuerSig,      // v, r, s
- *     uint256 feeAmount,        // PT units to split off to feeRecipient
- *     address feeRecipient      // typically operator or fee collector
- *   )
+ *   Path 2 — Sig-gated (gasless, v1.4 sponsored flow):
+ *     mint(address to, uint256 amount, uint256 deadline, bytes minterSig)
+ *     - msg.sender MUST equal `to` (the receiver)
+ *     - minterSig is an EIP-712 MintRequest signature from a whitelisted minter
+ *     - Consumes `mintRequestNonces[to]`
+ *     - This is the path v1.4 uses: issuer backend signs, user submits
+ *       via EIP-7702 + Coinbase Paymaster
  *
- * Behaviour expected:
- *   - Verify user + issuer EIP-712 signatures against `request`
- *   - Mint `request.amount` PT to `request.to`
- *   - Atomic transfer `feeAmount` from `request.to` → `feeRecipient`
- *     (net mint = `amount - feeAmount`)
- *   - Increment the on-chain nonce to prevent replay
+ * ## Burn — mirror structure
  *
- * When SC team publishes the real ABI, drop it in under
- * `src/contracts/real/relayerV2.abi.ts` and flip the export in
- * `src/contracts/index.ts` — call sites unchanged.
+ *   Path 1: burn(address from, uint256 amount) — whitelisted burner
+ *   Path 2: burn(address from, uint256 amount, uint256 deadline, bytes burnerSig)
+ *           — msg.sender must equal `from`, burnerSig from whitelisted burner,
+ *           consumes `burnRequestNonces[from]`
  *
- * See [SC_MOCK_PLAN.md §2.1] for the rationale + swap checklist.
+ * Either burn path emits `Transfer(from → 0x0)` so BurnIndexer semantics
+ * don't depend on which path was taken.
+ *
+ * ## EIP-712 type hashes (from contract source)
+ *
+ *   MintRequest(address to,uint256 amount,uint256 nonce,uint256 deadline)
+ *   BurnRequest(address from,uint256 amount,uint256 nonce,uint256 deadline)
+ *
+ *   Domain: EIP-712 standard — name = ERC-20 token name, version = "1",
+ *   chainId, verifyingContract = this PointToken address.
  */
-declare const MOCK_RELAYER_V2_ABI: readonly [{
+declare const POINT_TOKEN_ABI: readonly [{
     readonly name: "mint";
     readonly type: "function";
     readonly stateMutability: "nonpayable";
     readonly inputs: readonly [{
-        readonly type: "tuple";
-        readonly components: readonly [{
-            readonly type: "address";
-            readonly name: "to";
-        }, {
-            readonly type: "uint256";
-            readonly name: "amount";
-        }, {
-            readonly type: "uint256";
-            readonly name: "feeAmount";
-        }, {
-            readonly type: "address";
-            readonly name: "feeRecipient";
-        }, {
-            readonly type: "uint256";
-            readonly name: "nonce";
-        }, {
-            readonly type: "uint256";
-            readonly name: "deadline";
-        }, {
-            readonly type: "bytes";
-            readonly name: "extData";
-        }];
-        readonly name: "request";
-    }, {
-        readonly type: "tuple";
-        readonly components: readonly [{
-            readonly type: "uint8";
-            readonly name: "v";
-        }, {
-            readonly type: "bytes32";
-            readonly name: "r";
-        }, {
-            readonly type: "bytes32";
-            readonly name: "s";
-        }];
-        readonly name: "userSig";
+        readonly type: "address";
+        readonly name: "to";
     }, {
-        readonly type: "tuple";
-        readonly components: readonly [{
-            readonly type: "uint8";
-            readonly name: "v";
-        }, {
-            readonly type: "bytes32";
-            readonly name: "r";
-        }, {
-            readonly type: "bytes32";
-            readonly name: "s";
-        }];
-        readonly name: "issuerSig";
+        readonly type: "uint256";
+        readonly name: "amount";
     }];
     readonly outputs: readonly [];
 }, {
-    readonly name: "mintRequestNonce";
+    readonly name: "mint";
     readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [{
-        readonly type: "address";
-        readonly name: "user";
-    }];
-    readonly outputs: readonly [{
-        readonly type: "uint256";
-    }];
-}, {
-    readonly name: "Minted";
-    readonly type: "event";
+    readonly stateMutability: "nonpayable";
     readonly inputs: readonly [{
         readonly type: "address";
-        readonly name: "user";
-        readonly indexed: true;
+        readonly name: "to";
     }, {
         readonly type: "uint256";
         readonly name: "amount";
     }, {
         readonly type: "uint256";
-        readonly name: "feeAmount";
-    }, {
-        readonly type: "address";
-        readonly name: "feeRecipient";
-        readonly indexed: true;
+        readonly name: "deadline";
     }, {
-        readonly type: "bytes32";
-        readonly name: "requestHash";
+        readonly type: "bytes";
+        readonly name: "minterSig";
     }];
-}];
-/**
- * Calldata function selector for `mint((...),(...),(...))` as encoded
- * by viem against {@link MOCK_RELAYER_V2_ABI}. Callers compare against
- * this to sanity-check decoded UserOp inner calls.
- *
- * Recompute when the real ABI lands — almost certainly differs.
- */
-declare const MOCK_RELAYER_V2_MINT_SELECTOR: "0xMOCKED__";
-/**
- * Struct shape that matches {@link MOCK_RELAYER_V2_ABI}. Exported so
- * builders can accept a typed input without `as const` gymnastics.
- */
-interface MockMintRequestV2 {
-    to: Address;
-    amount: bigint;
-    feeAmount: bigint;
-    feeRecipient: Address;
-    nonce: bigint;
-    deadline: bigint;
-    extData: `0x${string}`;
-}
-interface MockSignatureStruct {
-    v: number;
-    r: `0x${string}`;
-    s: `0x${string}`;
-}
-
-/**
- * ⚠️ MOCK — `PointToken` v1.4 burn surface.
- *
- * Two variants mocked — SC team will pick ONE before stable; the other
- * gets deleted during Phase B swap.
- *
- *   Variant A (simpler, most likely):
- *     burn(uint256 amount)
- *     - burns from `msg.sender`
- *     - caller handles authorization (the user is `msg.sender` via
- *       EIP-7702 delegation, so `msg.sender == user`)
- *
- *   Variant B (signature-based, if SC prefers explicit consent on-chain):
- *     burnWithSig(BurnConsent consent, Signature sig)
- *     - verifies EIP-712 signature before burning
- *     - used when the caller isn't the user (e.g. a relayer burns on
- *       behalf of the user)
- *
- * Either way the ERC-20 emits `Transfer(from, address(0), amount)` so
- * `BurnIndexer` semantics don't change.
- */
-declare const MOCK_POINT_TOKEN_V2_ABI: readonly [{
+    readonly outputs: readonly [];
+}, {
     readonly name: "burn";
     readonly type: "function";
     readonly stateMutability: "nonpayable";
     readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "from";
+    }, {
         readonly type: "uint256";
         readonly name: "amount";
     }];
     readonly outputs: readonly [];
 }, {
-    readonly name: "burnWithSig";
+    readonly name: "burn";
     readonly type: "function";
     readonly stateMutability: "nonpayable";
     readonly inputs: readonly [{
-        readonly type: "tuple";
-        readonly components: readonly [{
-            readonly type: "address";
-            readonly name: "user";
-        }, {
-            readonly type: "address";
-            readonly name: "pointToken";
-        }, {
-            readonly type: "uint256";
-            readonly name: "amount";
-        }, {
-            readonly type: "uint256";
-            readonly name: "nonce";
-        }, {
-            readonly type: "uint256";
-            readonly name: "deadline";
-        }];
-        readonly name: "consent";
+        readonly type: "address";
+        readonly name: "from";
     }, {
-        readonly type: "tuple";
-        readonly components: readonly [{
-            readonly type: "uint8";
-            readonly name: "v";
-        }, {
-            readonly type: "bytes32";
-            readonly name: "r";
-        }, {
-            readonly type: "bytes32";
-            readonly name: "s";
-        }];
-        readonly name: "sig";
+        readonly type: "uint256";
+        readonly name: "amount";
+    }, {
+        readonly type: "uint256";
+        readonly name: "deadline";
+    }, {
+        readonly type: "bytes";
+        readonly name: "burnerSig";
     }];
     readonly outputs: readonly [];
 }, {
-    readonly name: "balanceOf";
+    readonly name: "minters";
     readonly type: "function";
     readonly stateMutability: "view";
     readonly inputs: readonly [{
         readonly type: "address";
-        readonly name: "user";
+        readonly name: "account";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "burners";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "account";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly name: "addMinter";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "minter";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "removeMinter";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "minter";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "addBurner";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "burner";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "removeBurner";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "burner";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "mintRequestNonces";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "receiver";
     }];
     readonly outputs: readonly [{
         readonly type: "uint256";
     }];
 }, {
-    readonly name: "burnNonce";
+    readonly name: "burnRequestNonces";
     readonly type: "function";
     readonly stateMutability: "view";
     readonly inputs: readonly [{
         readonly type: "address";
-        readonly name: "user";
+        readonly name: "from";
     }];
     readonly outputs: readonly [{
         readonly type: "uint256";
     }];
+}, {
+    readonly name: "mintingOracle";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "address";
+    }];
+}, {
+    readonly name: "setMintingOracle";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "_mintingOracle";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly name: "issuer";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "address";
+    }];
+}, {
+    readonly name: "balanceOf";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "account";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "totalSupply";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "name";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}, {
+    readonly name: "symbol";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}, {
+    readonly name: "decimals";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint8";
+    }];
+}, {
+    readonly name: "DOMAIN_SEPARATOR";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "bytes32";
+    }];
+}, {
+    readonly name: "eip712Domain";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "bytes1";
+        readonly name: "fields";
+    }, {
+        readonly type: "string";
+        readonly name: "name";
+    }, {
+        readonly type: "string";
+        readonly name: "version";
+    }, {
+        readonly type: "uint256";
+        readonly name: "chainId";
+    }, {
+        readonly type: "address";
+        readonly name: "verifyingContract";
+    }, {
+        readonly type: "bytes32";
+        readonly name: "salt";
+    }, {
+        readonly type: "uint256[]";
+        readonly name: "extensions";
+    }];
 }, {
     readonly name: "Transfer";
     readonly type: "event";
@@ -523,236 +941,360 @@ declare const MOCK_POINT_TOKEN_V2_ABI: readonly [{
         readonly type: "uint256";
         readonly name: "value";
     }];
+}, {
+    readonly name: "MinterAdded";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "minter";
+        readonly indexed: true;
+    }];
+}, {
+    readonly name: "MinterRemoved";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "minter";
+        readonly indexed: true;
+    }];
+}, {
+    readonly name: "BurnerAdded";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "burner";
+        readonly indexed: true;
+    }];
+}, {
+    readonly name: "BurnerRemoved";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "burner";
+        readonly indexed: true;
+    }];
+}, {
+    readonly name: "MintingOracleUpdated";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "mintingOracle";
+        readonly indexed: true;
+    }];
 }];
 
 /**
- * ⚠️ MOCK — placeholder BatchExecutor address.
+ * BatchExecutor delegation target addresses.
+ *
+ * ## Status
  *
- * Real deployment:
- *   - Coinbase may pre-deploy a canonical BatchExecutor that we target
- *     via EIP-7702 delegation (see blocker B2 in V1.4_V1.5_READINESS.md)
- *   - Otherwise PAFI deploys a minimal one and publishes the address
+ * Base mainnet: points at **Coinbase Smart Wallet v2**
+ * (`0x7702cb554e6bFb442cb743A7dF23154544a7176C`). Coinbase publishes
+ * this as the canonical EIP-7702 delegation target on Base — every
+ * user that wants gas sponsorship via Coinbase Paymaster delegates to
+ * this single contract. One contract, all issuers.
  *
- * The ABI itself (`execute(Call[])`) is stable and lives under
- * `../../userop/batchExecute.ts` — that's the real one, unchanged
- * by the mock swap. Only the **address** is mocked here.
+ * Base Sepolia: placeholder; Sepolia is not in active use for PAFI.
  *
- * Pattern: checksum address with hex "DEAD0001" suffix per chain so
- * it's obvious in logs which chain is using a mock.
+ * The ABI (`execute(Call[])`) is exported from
+ * `../../userop/batchExecute.ts` and works against the Coinbase
+ * contract without change — Coinbase Smart Wallet v2 implements the
+ * same call-array signature we already use.
  */
-declare const MOCK_BATCH_EXECUTOR_ADDRESS_BASE_SEPOLIA: Address;
-declare const MOCK_BATCH_EXECUTOR_ADDRESS_BASE_MAINNET: Address;
+declare const BATCH_EXECUTOR_ADDRESS_BASE_SEPOLIA: Address;
+declare const BATCH_EXECUTOR_ADDRESS_BASE_MAINNET: Address;
 
 /**
- * ⚠️ MOCK — per-chain contract addresses for the v1.4 sponsored flow.
+ * Per-chain deployed contract addresses — v1.4 flow.
+ *
+ * ## Status (2026-04-22)
  *
- * Real addresses come from SC team once they deploy Relayer v2 and
- * pick a BatchExecutor. Until then we use placeholders so the SDK
- * code path compiles + tests execute end-to-end.
+ * Base mainnet (8453): **all real**. BatchExecutor now points at the
+ * canonical Coinbase Smart Wallet v2 contract which PAFI reuses as the
+ * EIP-7702 delegation target (no per-app deploy required — one
+ * contract, every issuer).
  *
- * **Intentionally not merge-safe to mainnet** — callers that resolve
- * a mainnet address here get a `0x...DEAD` placeholder which will
- * revert at contract-level. That's the point: prod refuses to run
- * on mocks.
+ * Base Sepolia (84532): entire row is placeholder — not in active use.
  *
- * Chain id map:
- *   - 8453     Base mainnet
- *   - 84532    Base Sepolia
+ * ## What lives where
  *
- * Swap workflow when SC delivers:
- *   1. Rename this file → `addresses.ts` under `src/contracts/real/`
- *   2. Fill real addresses per chain
- *   3. Update `src/contracts/index.ts` re-export
- *   4. Delete MOCK_* named exports
+ *   pointToken      — live POINT instance (clone of PointToken impl)
+ *   batchExecutor   — EIP-7702 delegation target (Coinbase Smart Wallet v2)
+ *   usdt            — MockERC20 used by Uniswap pools
+ *   issuerRegistry  — registry of all issuers on this chain
+ *   mintingOracle   — per-issuer mint cap enforcer
+ *   pafiHook        — Uniswap V4 hook enforcing the 10% PT→USDT fee
+ *
+ * PointTokenFactory + PointToken implementation addresses live in
+ * separate exports below — they're only needed at provisioning /
+ * observability time, not in the hot mint/burn path, so excluded from
+ * the per-chain bundle.
  */
 interface ContractAddresses {
-    relayerV2: Address;
     pointToken: Address;
     batchExecutor: Address;
     usdt: Address;
     issuerRegistry: Address;
     mintingOracle: Address;
+    /**
+     * Uniswap V4 hook that enforces the 10% fee on PT→USDT swaps
+     * (USDT→PT is free). FE reads this to build `PoolKey.hooks` when
+     * constructing a swap; quoters + routers need it to resolve the
+     * correct pool.
+     */
+    pafiHook: Address;
 }
-declare const MOCK_ADDRESSES: Record<number, ContractAddresses>;
+declare const CONTRACT_ADDRESSES: Record<number, ContractAddresses>;
+/**
+ * PointTokenFactory address — separate from `ContractAddresses` because
+ * it's only used at provisioning time (issuer onboard + token creation),
+ * not in the hot mint/burn path.
+ */
+declare const POINT_TOKEN_FACTORY_ADDRESSES: Record<number, Address>;
+/**
+ * PointToken implementation address — the EIP-1167 clone target used
+ * by PointTokenFactory. Exposed for observability / proxy verification;
+ * consumers should never call this directly.
+ */
+declare const POINT_TOKEN_IMPL_ADDRESSES: Record<number, Address>;
 /**
  * Lookup helper — throws if the chain isn't in the map so callers fail
  * loudly on misconfiguration instead of silently using `undefined`.
  */
-declare function getMockAddresses(chainId: number): ContractAddresses;
+declare function getContractAddresses(chainId: number): ContractAddresses;
 
 /**
- * ⚠️ MOCK — `MintRequest` v2 EIP-712 types.
+ * Public contract surface for `@pafi-dev/core/contracts`.
+ *
+ * Consumers import ABIs + per-chain addresses from this module. EIP-712
+ * helpers (`signMintRequest`, `signBurnRequest`, etc.) live under
+ * `./eip712/` and are re-exported from the package root — not duplicated
+ * here.
+ *
+ * ## v1.4 flow — no Relayer, sig-gated mint/burn
  *
- * Extends v0.2.x `MintRequest` (4 fields) with three new fields needed
- * for the v1.4 sponsored flow:
+ * Relayer contract dropped. Users call `PointToken.mint(to, amount,
+ * deadline, minterSig)` directly via an EIP-7702 delegated UserOp —
+ * `msg.sender == user == to`. `minterSig` is an EIP-712 `MintRequest`
+ * signed off-chain by the issuer's minter signer (HSM/KMS). Mirror
+ * structure on the burn side with `BurnRequest` + `burn(from, amount,
+ * deadline, burnerSig)`.
  *
- *   + feeAmount      PT units taken from the mint for the operator
- *   + feeRecipient   where the fee goes (operator or treasury)
- *   + extData        arbitrary bytes for future extensions (swap path, etc.)
+ * Exports:
+ *   - `POINT_TOKEN_V2_ABI`      — full mint + burn + admin surface
+ *   - `BATCH_EXECUTOR_*`        — EIP-7702 delegation target (ABI real,
+ *                                 address still placeholder on all
+ *                                 chains until SC delivers)
+ *   - `CONTRACT_ADDRESSES`      — per-chain map (real on 8453 except
+ *                                 `batchExecutor` — pending SC)
+ *   - `POINT_TOKEN_FACTORY_ADDRESSES`, `POINT_TOKEN_IMPL_ADDRESSES`
+ *                               — provisioning / observability helpers
  *
- * When SC team confirms the real struct, drop this file's content into
- * the real builder and remove the MOCK_ prefix. The function signatures
- * below stay stable — only `MOCK_MINT_REQUEST_V2_TYPES` changes.
+ * Status: all real except BatchExecutor address (single remaining
+ * placeholder, flagged inline in `real/addresses.ts`).
  */
-declare const MOCK_MINT_REQUEST_V2_TYPES: {
-    readonly MintRequest: readonly [{
-        readonly name: "to";
-        readonly type: "address";
-    }, {
-        readonly name: "amount";
-        readonly type: "uint256";
-    }, {
-        readonly name: "feeAmount";
-        readonly type: "uint256";
-    }, {
-        readonly name: "feeRecipient";
-        readonly type: "address";
-    }, {
-        readonly name: "nonce";
-        readonly type: "uint256";
-    }, {
-        readonly name: "deadline";
-        readonly type: "uint256";
-    }, {
-        readonly name: "extData";
-        readonly type: "bytes";
-    }];
-};
+
 /**
- * Build the typed-data envelope that any EIP-712 signer (viem, ethers,
- * Privy) can consume. Callers typically pass the result to
- * `walletClient.signTypedData()` or `privy.signTypedData()`.
+ * Signature struct — kept for consumers that want the tuple form.
+ * Most v1.4 paths pass `bytes` (serialized signature) directly to the
+ * contract; this struct is only needed if you're manually splitting
+ * for other on-chain verifiers.
  */
-declare function buildMockMintRequestV2TypedData(domain: PointTokenDomainConfig, message: MockMintRequestV2): {
-    domain: {
-        name: string;
-        version: "1";
-        chainId: number;
-        verifyingContract: `0x${string}`;
-    };
-    types: {
-        readonly MintRequest: readonly [{
-            readonly name: "to";
-            readonly type: "address";
-        }, {
-            readonly name: "amount";
-            readonly type: "uint256";
-        }, {
-            readonly name: "feeAmount";
-            readonly type: "uint256";
-        }, {
-            readonly name: "feeRecipient";
-            readonly type: "address";
-        }, {
-            readonly name: "nonce";
-            readonly type: "uint256";
-        }, {
-            readonly name: "deadline";
-            readonly type: "uint256";
-        }, {
-            readonly name: "extData";
-            readonly type: "bytes";
-        }];
-    };
-    primaryType: "MintRequest";
-    message: MockMintRequestV2;
-};
+interface SignatureStruct {
+    v: number;
+    r: `0x${string}`;
+    s: `0x${string}`;
+}
+
 /**
- * Sign a `MintRequest` v2 with a viem WalletClient — server-side flow
- * where the issuer holds the private key directly (KMS-backed signer
- * is the production path; see `@pafi-dev/issuer` KMSSignerAdapter).
+ * Options for opening a PAFI Web modal — passed through by all adapters.
+ * Web-only fields (width/height/windowName) are ignored by mobile
+ * adapters that can't resize a system in-app browser.
  */
-declare function signMockMintRequestV2(walletClient: WalletClient, domain: PointTokenDomainConfig, message: MockMintRequestV2): Promise<EIP712Signature>;
+interface ModalOpenOptions {
+    /** Web popup pixel width. Default 900. Ignored on mobile. */
+    width?: number;
+    /** Web popup pixel height. Default 700. Ignored on mobile. */
+    height?: number;
+    /**
+     * `window.open()` target name. Same name across calls re-uses an
+     * already-open popup. Default: `"pafi-web"`. Web-only.
+     */
+    windowName?: string;
+    /**
+     * Called when the modal closes — either user-initiated (clicked
+     * close, swiped down on mobile) or programmatically via `handle.close()`.
+     */
+    onClose?: () => void;
+    /**
+     * Called when the opened window posts a message back to the parent
+     * via `window.opener.postMessage(data, origin)`. PAFI Web uses this
+     * to signal "swap complete" / "perp deposit complete" back to the
+     * issuer app without needing a redirect.
+     *
+     * `origin` is the posting window's origin — caller MUST verify it
+     * matches the expected PAFI Web host before trusting `data`.
+     */
+    onMessage?: (data: unknown, origin: string) => void;
+    /**
+     * Allowed origins for `onMessage` — messages from other origins are
+     * silently dropped. Pass the PAFI Web host(s), e.g.
+     * `["https://app.pacificfinance.org", "https://app-dev.pacificfinance.org"]`.
+     *
+     * Default: empty (all messages rejected). Set explicitly for security.
+     */
+    allowedOrigins?: string[];
+}
 /**
- * Verify a `MintRequest` v2 signature and check it came from the
- * expected signer (either user or issuer depending on which side is
- * being verified).
+ * Handle to an open PAFI Web modal. Methods are no-ops when the modal
+ * has already closed — safe to call without tracking state yourself.
  */
-declare function verifyMockMintRequestV2(domain: PointTokenDomainConfig, message: MockMintRequestV2, signature: Hex, expectedSigner: Address): Promise<SignatureVerification>;
-
+interface PafiWebModalHandle {
+    /** True when the modal is still open. */
+    readonly isOpen: boolean;
+    /** Close the modal. Fires `onClose` if the callback was supplied. */
+    close(): void;
+    /** Bring the modal to focus (web popup only; mobile ignores). */
+    focus(): void;
+    /**
+     * Post a message INTO the modal — useful for ping/pong handshakes
+     * with PAFI Web. The modal page must be on the same origin or
+     * explicitly listen for the message.
+     */
+    postMessage(data: unknown): void;
+}
 /**
- * ⚠️ MOCK — `BurnConsent` EIP-712 type for the v1.4 reverse flow.
+ * Adapter that knows how to open a URL in the right UX for the host
+ * platform. Callers register one via `setPafiWebModalAdapter()`; if
+ * none is registered, the core module falls back to `openWebPopup()`
+ * (if `window` is present) or throws (in Node / React Native without
+ * an adapter set).
  *
- * New type entirely — v0.2.x had no burn-for-credit flow.
+ * ## Mobile adapter example (React Native)
  *
- * User signs `BurnConsent` to authorize burning `amount` PT from their
- * wallet in exchange for an off-chain credit of (amount - gasFee).
- * Signature is consumed either by:
- *   - A relayer calling `PointToken.burnWithSig(...)` (Variant B)
- *   - The paymaster-proxy-sponsored UserOp calling `PointToken.burn(...)`
- *     with msg.sender = user via EIP-7702 (Variant A)
+ * ```ts
+ * import { setPafiWebModalAdapter } from '@pafi-dev/core';
+ * import InAppBrowser from 'react-native-inappbrowser-reborn';
  *
- * Either way the tx emits `Transfer(user → 0x0)` which the issuer's
- * `BurnIndexer` watches for and uses to credit the off-chain ledger.
+ * setPafiWebModalAdapter({
+ *   async open(url, options) {
+ *     const result = await InAppBrowser.open(url, {
+ *       // iOS: SFSafariViewController
+ *       dismissButtonStyle: 'close',
+ *       preferredBarTintColor: '#1a1a1a',
+ *       preferredControlTintColor: 'white',
+ *       // Android: Chrome Custom Tab
+ *       toolbarColor: '#1a1a1a',
+ *       secondaryToolbarColor: 'black',
+ *     });
+ *     options?.onClose?.();
+ *     return {
+ *       isOpen: false,
+ *       close: () => InAppBrowser.close(),
+ *       focus: () => {},
+ *       postMessage: () => {},
+ *     };
+ *   },
+ * });
+ * ```
  *
- * Field list is a best-guess — SC team may add fields (e.g. `feeAmount`
- * explicit, `extData`). Update this mock when they freeze the spec.
+ * ## Expo adapter example
+ *
+ * ```ts
+ * import * as WebBrowser from 'expo-web-browser';
+ *
+ * setPafiWebModalAdapter({
+ *   async open(url, options) {
+ *     await WebBrowser.openBrowserAsync(url);
+ *     options?.onClose?.();
+ *     return { isOpen: false, close: WebBrowser.dismissBrowser, focus: () => {}, postMessage: () => {} };
+ *   },
+ * });
+ * ```
  */
-interface MockBurnConsent {
-    user: Address;
-    pointToken: Address;
-    amount: bigint;
-    nonce: bigint;
-    deadline: bigint;
+interface PafiWebModalAdapter {
+    open(url: string, options?: ModalOpenOptions): PafiWebModalHandle | Promise<PafiWebModalHandle>;
 }
-declare const MOCK_BURN_CONSENT_TYPES: {
-    readonly BurnConsent: readonly [{
-        readonly name: "user";
-        readonly type: "address";
-    }, {
-        readonly name: "pointToken";
-        readonly type: "address";
-    }, {
-        readonly name: "amount";
-        readonly type: "uint256";
-    }, {
-        readonly name: "nonce";
-        readonly type: "uint256";
-    }, {
-        readonly name: "deadline";
-        readonly type: "uint256";
-    }];
-};
-declare function buildMockBurnConsentTypedData(domain: PointTokenDomainConfig, message: MockBurnConsent): {
-    domain: {
-        name: string;
-        version: "1";
-        chainId: number;
-        verifyingContract: `0x${string}`;
-    };
-    types: {
-        readonly BurnConsent: readonly [{
-            readonly name: "user";
-            readonly type: "address";
-        }, {
-            readonly name: "pointToken";
-            readonly type: "address";
-        }, {
-            readonly name: "amount";
-            readonly type: "uint256";
-        }, {
-            readonly name: "nonce";
-            readonly type: "uint256";
-        }, {
-            readonly name: "deadline";
-            readonly type: "uint256";
-        }];
-    };
-    primaryType: "BurnConsent";
-    message: MockBurnConsent;
-};
-declare function signMockBurnConsent(walletClient: WalletClient, domain: PointTokenDomainConfig, message: MockBurnConsent): Promise<EIP712Signature>;
-declare function verifyMockBurnConsent(domain: PointTokenDomainConfig, message: MockBurnConsent, signature: Hex, expectedUser: Address): Promise<SignatureVerification>;
+
+/**
+ * Web browser popup adapter. Opens the given URL in a centered
+ * `window.open()` popup, polls for close, and optionally forwards
+ * `postMessage` events back to the caller.
+ *
+ * Runtime requirement: `window.open` must exist. Throws if called
+ * under Node / SSR / React Native — use `setPafiWebModalAdapter()` to
+ * provide a platform-specific adapter in those environments.
+ *
+ * ## Popup blocking
+ *
+ * Browsers block `window.open()` unless it happens inside a user
+ * gesture (click handler). Callers MUST wire this into a direct click
+ * handler — wrapping it in a `setTimeout` or async await before the
+ * open call will trigger the blocker.
+ */
+declare function openWebPopup(url: string, options?: ModalOpenOptions): PafiWebModalHandle;
+/**
+ * The web popup packaged as a {@link PafiWebModalAdapter} so callers
+ * can register it explicitly (e.g. in a test harness).
+ */
+declare const webPopupAdapter: PafiWebModalAdapter;
+
+/**
+ * Register the adapter used by `openPafiWebModal()`. Typically called
+ * once during app initialization — mobile apps register a
+ * SFSafariViewController / Chrome Custom Tabs adapter, desktop apps
+ * can leave it unset (web popup is the default).
+ *
+ * Pass `null` to unregister and fall back to the default.
+ */
+declare function setPafiWebModalAdapter(adapter: PafiWebModalAdapter | null): void;
+/**
+ * Return the currently registered adapter, or `null` when none is set.
+ * Useful for tests that want to snapshot-and-restore the adapter.
+ */
+declare function getPafiWebModalAdapter(): PafiWebModalAdapter | null;
+/**
+ * Open PAFI Web in the host platform's appropriate UX:
+ *
+ *   - Browser (window.open): centered popup, 900×700 by default
+ *   - React Native (with adapter registered): SFSafariViewController
+ *     / Chrome Custom Tabs via `react-native-inappbrowser-reborn` or
+ *     `expo-web-browser`
+ *   - Desktop (with adapter registered): custom BrowserWindow / new tab
+ *
+ * Resolution order:
+ *   1. If an adapter was registered via `setPafiWebModalAdapter()`, use it.
+ *   2. Else if `window.open` is available, use the built-in web popup.
+ *   3. Else throw with a clear error pointing at the adapter registry.
+ *
+ * @example
+ * ```ts
+ * // User clicks "Trade on PAFI" button
+ * button.addEventListener('click', async () => {
+ *   const modal = await openPafiWebModal('https://app.pacificfinance.org', {
+ *     allowedOrigins: ['https://app.pacificfinance.org'],
+ *     onMessage: (data, origin) => {
+ *       if (typeof data === 'object' && data && 'txHash' in data) {
+ *         console.log('Swap confirmed:', data.txHash);
+ *         modal.close();
+ *       }
+ *     },
+ *     onClose: () => {
+ *       console.log('User closed modal');
+ *     },
+ *   });
+ * });
+ * ```
+ */
+declare function openPafiWebModal(url: string, options?: ModalOpenOptions): Promise<PafiWebModalHandle>;
 
 declare class PafiSDK {
     private _pointTokenAddress?;
-    private _relayContractAddress?;
     private _signer?;
     private _provider?;
     private _chainId?;
     constructor(config: PafiSDKConfig);
     setPointTokenAddress(address: Address): void;
-    setRelayContractAddress(address: Address): void;
     setSigner(signer: WalletClient): void;
     setProvider(provider: PublicClient): void;
     private requirePointToken;
@@ -760,10 +1302,6 @@ declare class PafiSDK {
     private requireSigner;
     private requireChainId;
     getDomain(): Promise<PointTokenDomainConfig>;
-    /**
-     * Build the EIP-712 typed data for a MintRequest.
-     * Pass the result to any external signer (Privy, WalletConnect, etc.).
-     */
     buildMintRequestTypedData(message: MintRequest): Promise<{
         domain: {
             name: string;
@@ -789,10 +1327,6 @@ declare class PafiSDK {
         primaryType: "MintRequest";
         message: MintRequest;
     }>;
-    /**
-     * Build the EIP-712 typed data for a ReceiverConsent.
-     * Pass the result to any external signer (Privy, WalletConnect, etc.).
-     */
     buildReceiverConsentTypedData(message: ReceiverConsent): Promise<{
         domain: {
             name: string;
@@ -830,11 +1364,6 @@ declare class PafiSDK {
     verifyReceiverConsent(message: ReceiverConsent, signature: Hex, expectedReceiver: Address): Promise<SignatureVerification>;
     getMintRequestNonce(receiver: Address): Promise<bigint>;
     getReceiverConsentNonce(receiver: Address): Promise<bigint>;
-    encodeMintAndSwap(mint: MintParams, swap: SwapParams): Hex;
-    decodeMintAndSwap(calldata: Hex): {
-        mint: MintParams;
-        swap: SwapParams;
-    };
     /**
      * Find the best swap route from `tokenIn` to `tokenOut`.
      * Merges `pools` with COMMON_POOLS for the configured chain, builds all
@@ -855,36 +1384,6 @@ declare class PafiSDK {
         commands: Hex;
         inputs: Hex[];
     };
-    /**
-     * Build Relay SwapParams + extData from a quote result.
-     * Returns ready-to-use args for `Relay.mintAndSwap`.
-     */
-    buildRelaySwapParams(params: {
-        quote: {
-            path: PathKey[];
-        };
-        minAmountOut: bigint;
-        feeInUsdt: bigint;
-        deadline: bigint;
-    }): {
-        swapParams: SwapParams;
-        extData: Hex;
-    };
-    /**
-     * Encode extData for ReceiverConsent and MintParams.
-     * extData = abi.encode(minAmountOut, feeInUsdt)
-     */
-    encodeExtData(minAmountOut: bigint, feeInUsdt: bigint): Hex;
-    /**
-     * Simulate a Relay.mintAndSwap call. Catches reverts (bad signatures,
-     * expired deadlines, insufficient mint cap, pool errors) before submitting.
-     *
-     * @param relayAddress - Relay contract address
-     * @param mint         - MintParams with real signatures
-     * @param swap         - SwapParams (path + deadline)
-     * @param from         - Relayer address that will submit the tx
-     */
-    simulateMintAndSwap(relayAddress: Address, mint: MintParams, swap: SwapParams, from: Address): Promise<SimulationResult>;
     /**
      * Simulate a UniversalRouter.execute swap call. Catches reverts (bad
      * approvals, insufficient balance, pool errors) before submitting.
@@ -896,14 +1395,9 @@ declare class PafiSDK {
      * @param from          - Address that will execute the swap
      */
     simulateSwap(routerAddress: Address, commands: Hex, inputs: Hex[], deadline: bigint, from: Address): Promise<SwapSimulationResult>;
-    /**
-     * Build an EIP-4361 login message for the current signer + chain. The
-     * caller supplies the issuer-specific fields (domain, nonce, uri); the SDK
-     * fills in the wallet address and chain id from its own config.
-     */
     createLoginMessage(params: Omit<LoginMessageParams, "address" | "chainId">): Promise<string>;
     /** Sign a login message string with the current signer (personal_sign) */
     signLoginMessage(message: string): Promise<Hex>;
 }
 
-export { ApiError, BATCH_EXECUTOR_ABI, MOCK_BATCH_EXECUTOR_ADDRESS_BASE_MAINNET as BATCH_EXECUTOR_ADDRESS_BASE_MAINNET, MOCK_BATCH_EXECUTOR_ADDRESS_BASE_SEPOLIA as BATCH_EXECUTOR_ADDRESS_BASE_SEPOLIA, MOCK_BURN_CONSENT_TYPES as BURN_CONSENT_TYPES, BestQuote, type BuildPartialUserOpParams, type MockBurnConsent as BurnConsent, COMMON_POOLS, COMMON_TOKENS, MOCK_ADDRESSES as CONTRACT_ADDRESSES, ChainConfig, type CheckEthAndBranchParams, ConfigurationError, type ContractAddresses, EIP712Signature, LoginMessageParams, MOCK_MINT_REQUEST_V2_TYPES as MINT_REQUEST_V2_TYPES, MintParams, MintRequest, type MockMintRequestV2 as MintRequestV2, Operation, POINT_TOKEN_POOLS, MOCK_POINT_TOKEN_V2_ABI as POINT_TOKEN_V2_ABI, PafiSDK, PafiSDKConfig, PafiSDKError, PartialUserOperation, PathKey, type PaymasterConfig, PointTokenDomainConfig, PoolKey, QuoteResult, MOCK_RELAYER_V2_ABI as RELAYER_V2_ABI, MOCK_RELAYER_V2_MINT_SELECTOR as RELAYER_V2_MINT_SELECTOR, ReceiverConsent, SUPPORTED_CHAINS, type MockSignatureStruct as SignatureStruct, SignatureVerification, SigningError, SimulationError, SimulationResult, type SponsorshipScenario, type SubmissionPath, SwapParams, SwapSimulationResult, UNIVERSAL_ROUTER_ADDRESSES, UserOperation, V4_QUOTER_ADDRESSES, _resetPaymasterConfigForTests, assembleUserOperation, buildMockBurnConsentTypedData as buildBurnConsentTypedData, buildMockMintRequestV2TypedData as buildMintRequestV2TypedData, buildPartialUserOperation, checkEthAndBranch, encodeBatchExecute, erc20ApproveOp, erc20BurnOp, erc20TransferOp, getMockAddresses as getContractAddresses, getPaymasterConfig, isPaymasterConfigured, mintRequestTypes, rawCallOp, receiverConsentTypes, setPaymasterConfig, signMockBurnConsent as signBurnConsent, signMockMintRequestV2 as signMintRequestV2, verifyMockBurnConsent as verifyBurnConsent, verifyMockMintRequestV2 as verifyMintRequestV2 };
+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, 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, encodeBatchExecute, erc20ApproveOp, erc20BurnOp, erc20TransferOp, getAaNonce, getContractAddresses, getPafiWebModalAdapter, getPaymasterConfig, isDelegatedTo, isPaymasterConfigured, mintRequestTypes, openPafiWebModal, openWebPopup, parseEip7702DelegatedAddress, rawCallOp, receiverConsentTypes, setPafiWebModalAdapter, setPaymasterConfig, webPopupAdapter };