@pafi-dev/core 0.3.0-beta.6 → 0.3.0-beta.7

package/dist/index.d.cts

@@ -5,7 +5,7 @@ export { erc20Abi, issuerRegistryAbi, mintingOracleAbi, permit2Abi, pointTokenAb
 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-B7pGBych.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';
@@ -87,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
@@ -1043,4 +1293,4 @@ declare class PafiSDK {
     signLoginMessage(message: string): Promise<Hex>;
 }
 
-export { ApiError, BATCH_EXECUTOR_ABI, BATCH_EXECUTOR_ADDRESS_BASE_MAINNET, BATCH_EXECUTOR_ADDRESS_BASE_SEPOLIA, BestQuote, type BuildPartialUserOpParams, COMMON_POOLS, COMMON_TOKENS, CONTRACT_ADDRESSES, ChainConfig, type CheckEthAndBranchParams, ConfigurationError, type ContractAddresses, EIP712Signature, LoginMessageParams, MintRequest, type ModalOpenOptions, 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, UNIVERSAL_ROUTER_ADDRESSES, UserOperation, V4_QUOTER_ADDRESSES, _resetPaymasterConfigForTests, assembleUserOperation, buildPartialUserOperation, burnRequestTypes, checkEthAndBranch, encodeBatchExecute, erc20ApproveOp, erc20BurnOp, erc20TransferOp, getContractAddresses, getPafiWebModalAdapter, getPaymasterConfig, isPaymasterConfigured, mintRequestTypes, openPafiWebModal, openWebPopup, rawCallOp, receiverConsentTypes, setPafiWebModalAdapter, setPaymasterConfig, webPopupAdapter };
+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, 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, buildPartialUserOperation, buildPerpDepositWithGasDeduction, burnRequestTypes, checkEthAndBranch, computeAccountId, encodeBatchExecute, erc20ApproveOp, erc20BurnOp, erc20TransferOp, getContractAddresses, getPafiWebModalAdapter, getPaymasterConfig, isPaymasterConfigured, mintRequestTypes, openPafiWebModal, openWebPopup, rawCallOp, receiverConsentTypes, setPafiWebModalAdapter, setPaymasterConfig, webPopupAdapter };

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { erc20Abi, issuerRegistryAbi, mintingOracleAbi, permit2Abi, pointTokenAb
 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 { O as Operation, P as PartialUserOperation, U as UserOperation, S as SwapSimulationResult } from './index-B06IJlHe.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 { LoginMessageParams } from './auth/index.js';
 export { VerifyLoginResult, createLoginMessage, parseLoginMessage, verifyLoginMessage } from './auth/index.js';
@@ -87,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
@@ -1043,4 +1293,4 @@ declare class PafiSDK {
     signLoginMessage(message: string): Promise<Hex>;
 }
 
-export { ApiError, BATCH_EXECUTOR_ABI, BATCH_EXECUTOR_ADDRESS_BASE_MAINNET, BATCH_EXECUTOR_ADDRESS_BASE_SEPOLIA, BestQuote, type BuildPartialUserOpParams, COMMON_POOLS, COMMON_TOKENS, CONTRACT_ADDRESSES, ChainConfig, type CheckEthAndBranchParams, ConfigurationError, type ContractAddresses, EIP712Signature, LoginMessageParams, MintRequest, type ModalOpenOptions, 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, UNIVERSAL_ROUTER_ADDRESSES, UserOperation, V4_QUOTER_ADDRESSES, _resetPaymasterConfigForTests, assembleUserOperation, buildPartialUserOperation, burnRequestTypes, checkEthAndBranch, encodeBatchExecute, erc20ApproveOp, erc20BurnOp, erc20TransferOp, getContractAddresses, getPafiWebModalAdapter, getPaymasterConfig, isPaymasterConfigured, mintRequestTypes, openPafiWebModal, openWebPopup, rawCallOp, receiverConsentTypes, setPafiWebModalAdapter, setPaymasterConfig, webPopupAdapter };
+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, 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, buildPartialUserOperation, buildPerpDepositWithGasDeduction, burnRequestTypes, checkEthAndBranch, computeAccountId, encodeBatchExecute, erc20ApproveOp, erc20BurnOp, erc20TransferOp, getContractAddresses, getPafiWebModalAdapter, getPaymasterConfig, isPaymasterConfigured, mintRequestTypes, openPafiWebModal, openWebPopup, rawCallOp, receiverConsentTypes, setPafiWebModalAdapter, setPaymasterConfig, webPopupAdapter };