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

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
@@ -288,6 +538,202 @@ 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.
+ *
+ * Keep in sync with `SponsorshipScenario` in the paymaster module —
+ * SponsorAuth replaces the Coinbase paymaster flow but reuses the
+ * scenario taxonomy.
+ */
+type SponsorAuthScenario = "mint" | "burn" | "swap" | "perp_deposit";
+/**
+ * Canonical SponsorAuth payload — the EIP-712 message that PAFI
+ * sponsor-relayer signs and Privy native verifies before funding gas.
+ *
+ * See `SPONSOR_AUTH_DESIGN.md` for full architecture.
+ *
+ * ## Replay protection layers
+ *
+ *   - `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
+ *
+ * Mutation of any field invalidates the signature.
+ */
+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;
+}
+/**
+ * Optional extension fields — keep separate so the canonical payload
+ * stays minimal. Privy verifier may or may not enforce these depending
+ * on dashboard config.
+ */
+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;
+    };
+}
+/**
+ * EIP-712 domain for SponsorAuth signatures.
+ *
+ * `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.
+ */
+declare function buildSponsorAuthDomain(chainId: number): {
+    readonly name: "PAFI SponsorAuth";
+    readonly version: "1";
+    readonly chainId: number;
+    readonly verifyingContract: Address;
+};
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+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;
+    };
+};
+/**
+ * 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`.
+ */
+declare function signSponsorAuth(walletClient: WalletClient, payload: SponsorAuthPayload): Promise<Hex>;
+/**
+ * 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
+ *
+ * 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.
+ *
+ * @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)
+ *
+ * @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.
+ *
+ * Bind this hash into the SponsorAuth payload BEFORE signing, so the
+ * sig is invalid for any other UserOp.
+ */
+declare function computeCallDataHash(callData: Hex): Hex;
+
 /**
  * Real `PointToken` ABI — matches the contract deployed on Base mainnet
  * (POINT at `0x7d25E7156E51F865D522fd3ef257a6B5DD41b97e`). Sourced from
@@ -1043,4 +1489,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, 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 };