@pafi-dev/core 0.3.0-beta.10 → 0.3.0-beta.12

package/README.md

@@ -1,1189 +1,170 @@
 # @pafi-dev/core
 
-The core TypeScript SDK for the PAFI point token system. Provides EIP-712
-signing and verification, EIP-4361 (Sign-In with Ethereum) helpers,
-contract ABIs, Relay calldata encoding, on-chain quoting, and swap
-building.
+Core TypeScript SDK for the PAFI point token system. Provides EIP-712 signing/verification, contract ABIs + addresses, UserOp building, swap/perp calldata encoding, and on-chain quoting.
 
-## What's new in 0.3.0-alpha.0 — UserOp primitives (v1.4 preview)
-
-Preview release adding the **sponsored UserOp building blocks** for
-EIP-7702 + ERC-4337 flows. No breaking changes — all v0.2.x exports
-remain. Additions:
-
-- `userop/types.ts` — `UserOperation`, `PartialUserOperation`,
-  `Operation`, `ENTRY_POINT_V07` constant
-- `userop/operations.ts` — `erc20TransferOp`, `erc20ApproveOp`,
-  `erc20BurnOp`, `rawCallOp`
-- `userop/batchExecute.ts` — `encodeBatchExecute()` +
-  `BATCH_EXECUTOR_ABI` (EIP-7702 delegation target)
-- `userop/buildUserOperation.ts` — `buildPartialUserOperation()` +
-  `assembleUserOperation()`
-- `paymaster/` — `PaymasterConfig`, `SponsorshipScenario`, module-level
-  `setPaymasterConfig` / `getPaymasterConfig`
-- `utils/checkEthAndBranch.ts` — decide sponsored-vs-normal path based
-  on the user's native balance
-
-**Deprecated:** `buildSwapFromQuote`, `encodeMintAndSwap`,
-`buildRelaySwapParams` — retired from the app-side flow. Still shipped
-for v0.2.x consumers; removed in 2.0.
-
-**Not yet ready** (blocked on SC team): `MintRequest` v2 + `BurnConsent`
-EIP-712 builders. Comes in 0.3.0-beta.
-
-```bash
-pnpm add @pafi-dev/core@0.3.0-alpha.0
-```
+**Version:** `0.3.0-beta.10` — Base mainnet ready.
 
 ---
 
-**`@pafi-dev/core` is HTTP-client-free on purpose.** It covers only the
-primitives that need a signer or a provider (or neither) — never the
-HTTP wire. The HTTP contract (routes, request/response types) is owned
-by [`@pafi/issuer`](../issuer/README.md) as the single source of truth,
-and frontends import those types `type`-only so browser bundles never
-pull in server code like `jose` or `node:crypto`.
-
-| Runs on | Purpose |
-|---|---|
-| Frontend (web + mobile) | Sign EIP-712 messages, build calldata, quote swaps, construct login messages |
-| Issuer backend | Verify EIP-712 signatures, decode calldata, read on-chain nonces / minter status |
-
 ## Installation
 
 ```bash
 pnpm add @pafi-dev/core viem
+# viem ^2.0.0 is a required peer dependency
 ```
 
-`viem ^2.0.0` is a peer dependency and must be installed alongside this package.
-
 ---
 
-## Quick Start
-
-```ts
-import { createPublicClient, createWalletClient, http } from "viem";
-import { privateKeyToAccount } from "viem/accounts";
-import { PafiSDK } from "@pafi-dev/core";
-
-const account = privateKeyToAccount("0x...");
-
-const sdk = new PafiSDK({
-  chainId: 8453,
-  rpcUrl: "https://base-mainnet.g.alchemy.com/v2/...",
-  signer: createWalletClient({
-    account,
-    transport: http("https://base-mainnet.g.alchemy.com/v2/..."),
-  }),
-  pointTokenAddress: "0xPointToken...",
-  relayContractAddress: "0xRelay...",
-});
-
-// Fetch on-chain nonce then sign a mint request
-const nonce = await sdk.getMintRequestNonce(account.address);
-
-const sig = await sdk.signMintRequest({
-  to: account.address,
-  amount: 1_000_000n,
-  nonce,
-  deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
-});
-
-console.log(sig.serialized);
-```
-
----
+## What this package covers
 
-## Sub-path Imports
-
-Every module is available both from the root entry and via its own sub-path export. Use sub-paths to reduce bundle size in tree-shaking-aware environments.
-
-| Sub-path | Contents |
+| Module | What it does |
 |---|---|
-| `@pafi-dev/core` | All exports (PafiSDK class + everything below) |
-| `@pafi-dev/core/eip712` | `buildMintRequestTypedData`, `buildReceiverConsentTypedData`, `signMintRequest`, `verifyMintRequest`, `signReceiverConsent`, `verifyReceiverConsent`, `buildDomain` |
-| `@pafi-dev/core/relay` | `encodeMintAndSwap`, `decodeMintAndSwap`, `buildRelaySwapParams`, `encodeExtData`, `decodeExtData` |
-| `@pafi-dev/core/contract` | `getMintRequestNonce`, `getReceiverConsentNonce`, `isMinter`, `getTokenName`, `getIssuer`, `isActiveIssuer`, `verifyMintCap`, `getPointTokenIssuer`, `getFeeBasisPoints`, `getSlippageBasisPoints`, `getUsdt` |
-| `@pafi-dev/core/quoting` | `quoteExactInput`, `quoteExactInputSingle`, `quoteBestRoute`, `findBestQuote`, `buildAllPaths`, `combineRoutes` |
-| `@pafi-dev/core/swap` | `checkAllowance`, `buildErc20ApprovalCalldata`, `buildPermit2ApprovalCalldata`, `buildUniversalRouterExecuteArgs`, `buildSwapFromQuote`, `buildV4SwapInput` |
-| `@pafi-dev/core/auth` | `createLoginMessage`, `parseLoginMessage`, `verifyLoginMessage` (EIP-4361) |
-| `@pafi-dev/core/abi` | All contract ABIs |
-
----
-
-## API Reference
-
-### PafiSDK Class
-
-The `PafiSDK` class is a convenience wrapper around all pure functions. All methods delegate to the same pure functions exported from the sub-path modules.
-
-#### Constructor
-
-```ts
-import { PafiSDK } from "@pafi-dev/core";
-
-const sdk = new PafiSDK(config: PafiSDKConfig);
-```
-
-```ts
-interface PafiSDKConfig {
-  chainId?: number;
-  pointTokenAddress?: Address;
-  relayContractAddress?: Address;
-  signer?: WalletClient;       // viem WalletClient
-  provider?: PublicClient;     // viem PublicClient (takes precedence over rpcUrl)
-  rpcUrl?: string;             // creates a PublicClient automatically if provider is omitted
-}
-```
-
-All fields are optional at construction time. Missing fields are validated lazily when the relevant method is called, throwing a `ConfigurationError` if a required field is absent.
-
-#### Setters
-
-```ts
-sdk.setPointTokenAddress(address: Address): void
-sdk.setRelayContractAddress(address: Address): void
-sdk.setSigner(signer: WalletClient): void
-sdk.setProvider(provider: PublicClient): void
-```
-
-#### Domain
-
-```ts
-// Resolves the EIP-712 domain by reading the token name on-chain.
-// Requires provider, pointTokenAddress, and chainId.
-await sdk.getDomain(): Promise<PointTokenDomainConfig>
-```
-
----
-
-### EIP-712 Signing
-
-#### Pure functions (from `@pafi-dev/core/eip712`)
-
-```ts
-import {
-  buildDomain,
-  signMintRequest,
-  verifyMintRequest,
-  signReceiverConsent,
-  verifyReceiverConsent,
-} from "@pafi-dev/core/eip712";
-```
-
-##### `buildDomain`
-
-```ts
-function buildDomain(config: PointTokenDomainConfig): {
-  name: string;
-  version: "1";
-  chainId: number;
-  verifyingContract: Address;
-}
-```
-
-Constructs the EIP-712 domain object. Version is always `"1"`.
-
-##### `signMintRequest`
-
-```ts
-async function signMintRequest(
-  walletClient: WalletClient,
-  domain: PointTokenDomainConfig,
-  message: MintRequest,
-): Promise<EIP712Signature>
-```
-
-Signs a `MintRequest` struct with the connected wallet.
-
-##### `verifyMintRequest`
-
-```ts
-async function verifyMintRequest(
-  domain: PointTokenDomainConfig,
-  message: MintRequest,
-  signature: Hex,
-  expectedMinter: Address,
-): Promise<SignatureVerification>
-```
-
-Recovers the signer from a `MintRequest` signature and compares against `expectedMinter`.
-
-##### `signReceiverConsent`
-
-```ts
-async function signReceiverConsent(
-  walletClient: WalletClient,
-  domain: PointTokenDomainConfig,
-  message: ReceiverConsent,
-): Promise<EIP712Signature>
-```
-
-Signs a `ReceiverConsent` struct.
-
-##### `verifyReceiverConsent`
-
-```ts
-async function verifyReceiverConsent(
-  domain: PointTokenDomainConfig,
-  message: ReceiverConsent,
-  signature: Hex,
-  expectedReceiver: Address,
-): Promise<SignatureVerification>
-```
-
-Recovers and validates a `ReceiverConsent` signature.
-
-#### PafiSDK methods
-
-```ts
-await sdk.signMintRequest(message: MintRequest): Promise<EIP712Signature>
-await sdk.verifyMintRequest(message: MintRequest, signature: Hex, expectedMinter: Address): Promise<SignatureVerification>
-await sdk.signReceiverConsent(message: ReceiverConsent): Promise<EIP712Signature>
-await sdk.verifyReceiverConsent(message: ReceiverConsent, signature: Hex, expectedReceiver: Address): Promise<SignatureVerification>
-```
-
-All four methods automatically resolve the domain from on-chain state via `getDomain()`.
-
----
-
-### Relay Calldata
-
-#### Pure functions (from `@pafi-dev/core/relay`)
-
-```ts
-import {
-  encodeMintAndSwap,
-  decodeMintAndSwap,
-  encodeMintAndSwapV2,
-  decodeMintAndSwapV2,
-} from "@pafi-dev/core/relay";
-```
+| `eip712/` | Build + sign + verify `MintRequest` and `BurnRequest` EIP-712 typed data |
+| `contracts/` | Deployed contract addresses (Base mainnet 8453) + ABIs |
+| `userop/` | `encodeBatchExecute()`, `buildPartialUserOperation()`, `BATCH_EXECUTOR_ABI` |
+| `swap/` | `buildSwapWithGasDeduction()` — PT→USDT via UniversalRouter |
+| `perp/` | `buildPerpDepositWithGasDeduction()` — USDC deposit to Orderly Vault |
+| `quoting/` | `findBestQuote()` — on-chain V4 Quoter multicall |
+| `auth/` | `createLoginMessage()` — EIP-4361 SIWE message builder |
+| `utils/` | `computeAccountId()` — Orderly perp account ID |
 
-##### V1 (Relay.sol)
-
-```ts
-// ABI-encode a mintAndSwap(MintParams, SwapParams) call for Relay.sol
-function encodeMintAndSwap(mint: MintParams, swap: SwapParams): Hex
-
-// Decode calldata produced by encodeMintAndSwap
-function decodeMintAndSwap(calldata: Hex): { mint: MintParams; swap: SwapParams }
-```
-
-##### V2 (RelayV2.sol)
-
-```ts
-// ABI-encode a mintAndSwap(MintParams, SwapParams) call for RelayV2.sol
-function encodeMintAndSwapV2(mint: MintParams, swap: SwapParams): Hex
-
-// Decode calldata produced by encodeMintAndSwapV2
-function decodeMintAndSwapV2(calldata: Hex): { mint: MintParams; swap: SwapParams }
-```
-
-#### Example
-
-```ts
-import { encodeMintAndSwap } from "@pafi-dev/core/relay";
-
-const calldata = encodeMintAndSwap(
-  {
-    pointToken: "0xPointToken...",
-    receiver: "0xReceiver...",
-    amount: 1_000_000n,
-    deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
-    minterSig: "0x...",
-    receiverSig: "0x...",
-  },
-  {
-    path: [
-      {
-        intermediateCurrency: "0xUSDT...",
-        fee: 500,
-        tickSpacing: 10,
-        hooks: "0x0000000000000000000000000000000000000000",
-        hookData: "0x",
-      },
-    ],
-    deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
-  },
-);
-```
-
-#### PafiSDK methods
-
-```ts
-sdk.encodeMintAndSwap(mint: MintParams, swap: SwapParams): Hex
-sdk.decodeMintAndSwap(calldata: Hex): { mint: MintParams; swap: SwapParams }
-sdk.encodeExtData(minAmountOut: bigint, feeInUsdt: bigint): Hex
-sdk.buildRelaySwapParams({ quote, minAmountOut, feeInUsdt, deadline }): { swapParams, extData }
-```
-
----
-
-### Contract Reads
-
-#### PointToken (from `@pafi-dev/core/contract`)
-
-```ts
-import {
-  getMintRequestNonce,
-  getReceiverConsentNonce,
-  isMinter,
-  getTokenName,
-  getPointTokenIssuerAddress,
-} from "@pafi-dev/core/contract";
-```
-
-| Function | Signature | Description |
-|---|---|---|
-| `getMintRequestNonce` | `(client, pointToken, receiver) => Promise<bigint>` | Current `MintRequest` nonce for `receiver` |
-| `getReceiverConsentNonce` | `(client, pointToken, receiver) => Promise<bigint>` | Current `ReceiverConsent` nonce for `receiver` |
-| `isMinter` | `(client, pointToken, account) => Promise<boolean>` | Returns `true` if `account` has the minter role |
-| `getTokenName` | `(client, pointToken) => Promise<string>` | ERC-20 `name()` — used as the EIP-712 domain name |
-| `getPointTokenIssuerAddress` | `(client, pointToken) => Promise<Address>` | Issuer address registered on the token |
-
-#### IssuerRegistry
-
-```ts
-import { getIssuer, isActiveIssuer } from "@pafi-dev/core/contract";
-```
-
-| Function | Signature | Description |
-|---|---|---|
-| `getIssuer` | `(client, registryAddress, issuer) => Promise<Issuer>` | Full `Issuer` struct for the given address |
-| `isActiveIssuer` | `(client, registryAddress, issuer) => Promise<boolean>` | Whether the issuer is currently active |
-
-#### MintingOracle
-
-```ts
-import { verifyMintCap, getPointTokenIssuer } from "@pafi-dev/core/contract";
-```
-
-| Function | Signature | Description |
-|---|---|---|
-| `verifyMintCap` | `(client, oracleAddress, issuer, amount) => Promise<void>` | Reverts if `amount` would exceed the issuer's mint cap |
-| `getPointTokenIssuer` | `(client, oracleAddress, pointToken) => Promise<Address>` | Maps a point token address back to its issuer |
-
-#### Relay helpers
-
-```ts
-import { getFeeBasisPoints, getSlippageBasisPoints, getUsdt } from "@pafi-dev/core/contract";
-```
-
-| Function | Signature | Description |
-|---|---|---|
-| `getFeeBasisPoints` | `(client, relayAddress) => Promise<bigint>` | Protocol fee in basis points |
-| `getSlippageBasisPoints` | `(client, relayAddress) => Promise<bigint>` | Slippage tolerance in basis points |
-| `getUsdt` | `(client, relayAddress) => Promise<Address>` | USDT address used by the Relay contract |
-
-#### PafiSDK methods
-
-```ts
-await sdk.getMintRequestNonce(receiver: Address): Promise<bigint>
-await sdk.getReceiverConsentNonce(receiver: Address): Promise<bigint>
-```
-
-#### PafiSDK quoting + swap methods
-
-```ts
-// Quote — finds the best route via multicall
-await sdk.findBestQuote(tokenIn, tokenOut, amount, pools?, quoterAddress?): Promise<BestQuote>
-
-// Build UniversalRouter execute args from a quote
-sdk.buildSwapFromQuote({ quote, currencyIn, currencyOut, amountIn, minAmountOut }): { commands, inputs }
-
-// Build Relay SwapParams + extData from a quote
-sdk.buildRelaySwapParams({ quote, minAmountOut, feeInUsdt, deadline }): { swapParams, extData }
-
-// Encode extData for ReceiverConsent signing
-sdk.encodeExtData(minAmountOut, feeInUsdt): Hex
-```
+**This package is HTTP-client-free.** It covers signing, calldata encoding, and on-chain reads only — no fetch calls. Use on both frontend and issuer backend.
 
 ---
 
-### Quoting
-
-#### Pure functions (from `@pafi-dev/core/quoting`)
-
-```ts
-import {
-  quoteExactInput,
-  quoteExactInputSingle,
-  quoteBestRoute,
-  findBestQuote,
-  buildAllPaths,
-  combineRoutes,
-} from "@pafi-dev/core/quoting";
-```
-
-##### `quoteExactInput`
-
-```ts
-async function quoteExactInput(
-  client: PublicClient,
-  quoterAddress: Address,
-  exactCurrency: Address,
-  path: PathKey[],
-  exactAmount: bigint,
-): Promise<QuoteResult>
-```
-
-Quotes a multi-hop exact-input swap against the V4 quoter.
-
-##### `quoteExactInputSingle`
+## Contract addresses (Base mainnet 8453)
 
 ```ts
-async function quoteExactInputSingle(
-  client: PublicClient,
-  quoterAddress: Address,
-  poolKey: PoolKey,
-  zeroForOne: boolean,
-  exactAmount: bigint,
-  hookData: Hex,
-): Promise<{ amountOut: bigint; gasEstimate: bigint }>
-```
-
-Quotes a single-hop swap given an explicit pool key and swap direction.
+import { getContractAddresses, POINT_TOKEN_FACTORY_ADDRESSES, POINT_TOKEN_IMPL_ADDRESSES } from "@pafi-dev/core";
 
-##### `quoteBestRoute`
+const addrs = getContractAddresses(8453);
+// addrs.issuerRegistry  = "0xda2D3338CF70F462Ac175F5f2edfa45660CA4f31"
+// addrs.mintingOracle   = "0xD85165939C700E51c8a45099316C6482634C2Ab9"
+// addrs.pafiHook        = "0x870cAF9882d3160602AaC1769C2B264A2d8EC044"
+// addrs.usdt            = "0x5d313485Ba59C3bb91e1A9C0C11782F0b83d5dcd"
+// addrs.batchExecutor   = "0x7702cb554e6bFb442cb743A7dF23154544a7176C"
+// addrs.pointToken      = "0x7d25E7156E51F865D522fd3ef257a6B5DD41b97e"
 
-```ts
-async function quoteBestRoute(
-  client: PublicClient,
-  quoterAddress: Address,
-  exactCurrency: Address,
-  routes: PathKey[][],
-  exactAmount: bigint,
-): Promise<BestQuote>
-```
-
-Quotes multiple routes via a single `multicall` RPC call and returns the one with the highest `amountOut`. Routes that fail (e.g. pool does not exist) are silently dropped. Throws if no routes succeed.
-
-##### `findBestQuote`
-
-```ts
-async function findBestQuote(
-  client: PublicClient,
-  chainId: number,
-  tokenIn: Address,
-  tokenOut: Address,
-  exactAmount: bigint,
-  pools?: PoolKey[],
-  quoterAddress?: Address,
-  maxHops?: number,
-): Promise<BestQuote>
-```
-
-One-call quoting helper. Merges caller-provided `pools` with `COMMON_POOLS[chainId]`, builds all possible paths via `buildAllPaths`, then quotes them all via multicall. Uses `V4_QUOTER_ADDRESSES[chainId]` unless `quoterAddress` is provided.
-
-##### `buildAllPaths`
-
-```ts
-function buildAllPaths(
-  pools: PoolKey[],
-  tokenIn: Address,
-  tokenOut: Address,
-  maxHops?: number,
-): PathKey[][]
-```
-
-Builds all possible swap paths from `tokenIn` to `tokenOut` using DFS through the given pools. Each pool is used at most once per path. Returns an array of `PathKey[]` routes (up to `maxHops`, default 3).
-
-##### `combineRoutes`
-
-```ts
-function combineRoutes(
-  chainId: number,
-  pointTokenAddress: Address,
-): PoolKey[]
-```
-
-Merges `POINT_TOKEN_POOLS[chainId][pointTokenAddress]` and `COMMON_POOLS[chainId]` into a single pool list, with point token pools listed first.
-
-#### Example
-
-```ts
-import { findBestQuote } from "@pafi-dev/core/quoting";
-
-// Provide only your token-specific pools — COMMON_POOLS are merged automatically
-const pointTokenPools = [
-  { currency0: USDC, currency1: pointToken, fee: 3000, tickSpacing: 60, hooks: ZERO },
-];
-
-const { bestRoute, allRoutes } = await findBestQuote(
-  client,
-  8453,            // Base chain ID — auto-resolves quoter address
-  pointToken,
-  USDC,
-  1_000_000n,
-  pointTokenPools, // merged with COMMON_POOLS[8453]
-);
-
-console.log(bestRoute.amountOut, bestRoute.gasEstimate);
-console.log(`Found ${allRoutes.length} valid routes`);
+// POINT_TOKEN_FACTORY_ADDRESSES[8453] = "0x36c0BAb2faBE45EfA6d13001143e43A266Af673B"
+// POINT_TOKEN_IMPL_ADDRESSES[8453]    = "0x2e6FB1B0C1A51abb83eC974890126a64eC02E995"
 ```
 
 ---
 
-### Swap Building
-
-#### Pure functions (from `@pafi-dev/core/swap`)
-
-```ts
-import {
-  checkAllowance,
-  buildErc20ApprovalCalldata,
-  buildPermit2ApprovalCalldata,
-  buildUniversalRouterExecuteArgs,
-  buildV4SwapInput,
-} from "@pafi-dev/core/swap";
-```
-
-##### `checkAllowance`
-
-```ts
-async function checkAllowance(
-  client: PublicClient,
-  token: Address,
-  owner: Address,
-  spender: Address,
-): Promise<bigint>
-```
-
-Reads the ERC-20 allowance of `spender` on behalf of `owner`.
-
-##### `buildErc20ApprovalCalldata`
-
-```ts
-function buildErc20ApprovalCalldata(spender: Address, amount: bigint): Hex
-```
-
-Encodes `ERC20.approve(spender, amount)`.
-
-##### `buildPermit2ApprovalCalldata`
-
-```ts
-function buildPermit2ApprovalCalldata(
-  token: Address,
-  spender: Address,
-  amount: bigint,
-  expiration: number,
-): Hex
-```
-
-Encodes `Permit2.approve(token, spender, amount, expiration)`.
-
-##### `buildUniversalRouterExecuteArgs`
+## EIP-712 signing (issuer backend)
 
 ```ts
-function buildUniversalRouterExecuteArgs(
-  currencyIn: Address,
-  path: PathKey[],
-  amountIn: bigint,
-  minAmountOut: bigint,
-  outputCurrency: Address,
-): { commands: Hex; inputs: Hex[] }
-```
-
-Builds the `commands` and `inputs` arguments for `UniversalRouter.execute`. The command sequence is `V4_SWAP` (`0x10`). Actions encoded inside the payload are `SWAP_EXACT_IN → SETTLE_ALL → TAKE_ALL`.
+import { signMintRequest, verifyMintRequest, signBurnRequest } from "@pafi-dev/core";
 
-##### `buildV4SwapInput`
-
-```ts
-function buildV4SwapInput(
-  currencyIn: Address,
-  path: PathKey[],
-  amountIn: bigint,
-  minAmountOut: bigint,
-  outputCurrency: Address,
-): Hex
-```
-
-Encodes only the V4_SWAP command payload (`inputs[0]`). Use `buildUniversalRouterExecuteArgs` unless you need the raw payload for custom command composition.
-
-##### `buildSwapFromQuote`
-
-```ts
-function buildSwapFromQuote(params: {
-  quote: QuoteResult;
-  currencyIn: Address;
-  currencyOut: Address;
-  amountIn: bigint;
-  minAmountOut: bigint;
-}): { commands: Hex; inputs: Hex[] }
-```
-
-Build UniversalRouter execute args directly from a `QuoteResult` (returned by `findBestQuote` or `quoteBestRoute`). The caller provides `minAmountOut` after applying their own slippage tolerance.
-
-#### Example
-
-```ts
-import { findBestQuote } from "@pafi-dev/core/quoting";
-import { buildSwapFromQuote } from "@pafi-dev/core/swap";
-
-// 1. Quote
-const { bestRoute } = await findBestQuote(client, 8453, tokenIn, USDC, amountIn, myPools);
+const domain = {
+  name: "Test Point",          // must match PointToken.name() on-chain
+  chainId: 8453,
+  verifyingContract: "0x7d25E7156E51F865D522fd3ef257a6B5DD41b97e",
+};
 
-// 2. Build swap calldata (apply slippage externally)
-const minReceive = bestRoute.amountOut * 99n / 100n; // 1% slippage
-const { commands, inputs } = buildSwapFromQuote({
-  quote: bestRoute,
-  currencyIn: tokenIn,
-  currencyOut: USDC,
-  amountIn,
-  minAmountOut: minReceive,
+// Sign MintRequest (issuer backend)
+const { signature } = await signMintRequest(walletClient, domain, {
+  to: "0xUser",
+  amount: 500n * 10n ** 18n,
+  nonce: 0n,
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 900),
 });
 
-// 3. Execute via UniversalRouter
+// Verify (optional offline check)
+const { valid } = await verifyMintRequest(domain, request, signature, expectedMinter);
 ```
 
 ---
 
-### Auth helpers (EIP-4361 — Sign-In With Ethereum)
-
-#### Pure functions (from `@pafi-dev/core/auth`)
-
-```ts
-import {
-  createLoginMessage,
-  parseLoginMessage,
-  verifyLoginMessage,
-} from "@pafi-dev/core/auth";
-```
-
-These are stateless helpers — they build, parse, and verify EIP-4361
-login messages without touching the network. The frontend uses them to
-construct the message the wallet signs; the backend uses `verifyLoginMessage`
-inside its own `AuthService` (see `@pafi/issuer`).
-
-```ts
-function createLoginMessage(params: {
-  domain: string;           // e.g. "app.example.com"
-  address: Address;         // user's wallet
-  chainId: number;
-  nonce: string;            // from issuer backend /auth/nonce
-  uri: string;              // e.g. "https://app.example.com"
-  statement?: string;       // human-readable sign-in message
-  version?: string;         // defaults to "1"
-  issuedAt?: Date;
-  expirationTime?: Date;
-  notBefore?: Date;
-  requestId?: string;
-}): string
-
-function parseLoginMessage(message: string): LoginMessageParams
-
-async function verifyLoginMessage(
-  message: string,
-  signature: Hex,
-): Promise<{ valid: boolean; address: Address }>
-```
-
-#### PafiSDK helpers
+## Swap calldata — PT -> USDT
 
 ```ts
-// Build a login message for the current signer + chain
-await sdk.createLoginMessage(params: Omit<LoginMessageParams, "address" | "chainId">): Promise<string>
-
-// Sign a login message with the current signer (personal_sign)
-await sdk.signLoginMessage(message: string): Promise<Hex>
-```
+import { buildSwapWithGasDeduction, findBestQuote, getContractAddresses } from "@pafi-dev/core";
 
-The SDK does not post the signed message for you — the frontend calls
-its own `fetch()` against the issuer backend:
+const addrs = getContractAddresses(8453);
 
-```ts
-// 1. Fetch nonce from the issuer backend
-const { nonce } = await fetch(`${ISSUER_URL}/auth/nonce`).then(r => r.json());
+// Quote (on-chain V4 Quoter multicall)
+const quote = await findBestQuote(
+  publicClient, 8453,
+  addrs.pointToken, addrs.usdt,
+  500n * 10n ** 18n,
+  pools, // from gg56-backend POST /swap response
+);
 
-// 2. Build + sign the login message
-const message = await sdk.createLoginMessage({
-  domain: "app.example.com",
-  uri: "https://app.example.com",
-  nonce,
+// Build BatchExecutor callData
+const userOp = buildSwapWithGasDeduction({
+  chainId: 8453,
+  sender: "0xUser",
+  pointTokenAddress: addrs.pointToken,
+  usdtAddress: addrs.usdt,
+  universalRouterAddress: "0xUniversalRouter...",
+  pafiHookAddress: addrs.pafiHook,
+  quote,
+  slippageBps: 50,
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 300),
+  aaNonce: 0n,
+  batchExecutorAddress: addrs.batchExecutor,
+  gasFeePt: 0n,
 });
-const signature = await sdk.signLoginMessage(message);
-
-// 3. POST to the issuer backend, receive a JWT
-const { token, userAddress } = await fetch(`${ISSUER_URL}/auth/login`, {
-  method: "POST",
-  headers: { "Content-Type": "application/json" },
-  body: JSON.stringify({ message, signature }),
-}).then(r => r.json());
-
-// 4. Store the JWT and attach it to subsequent protected requests
-// (handled by the frontend's own state management — @pafi-dev/core does
-// not manage tokens)
-```
-
-> **Why isn't there an HTTP client?** The HTTP contract (routes,
-> request/response shapes) is owned by `@pafi/issuer`. Frontends import
-> those types `type`-only and build their own `fetch()` calls. This
-> keeps the frontend bundle free of server-side dependencies like
-> `jose` and `node:crypto`, and ensures the protocol has exactly one
-> source of truth.
-
----
-
-### ABIs
-
-All ABIs are available from `@pafi-dev/core/abi` or from the root import.
-
-```ts
-import {
-  pointTokenAbi,
-  relayAbi,
-  relayV2Abi,
-  issuerRegistryAbi,
-  pointTokenFactoryAbi,
-  mintingOracleAbi,
-  erc20Abi,
-  universalRouterAbi,
-  permit2Abi,
-  v4QuoterAbi,
-} from "@pafi-dev/core/abi";
+// userOp.callData -> BatchExecutor.execute([approve, swap])
 ```
 
-| Export | Contract |
-|---|---|
-| `pointTokenAbi` | PointToken ERC-20 with minting and nonce functions |
-| `relayAbi` | Relay.sol — `mintAndSwap`, fee and slippage reads |
-| `relayV2Abi` | RelayV2.sol — same interface, new deployment |
-| `issuerRegistryAbi` | IssuerRegistry — `getIssuer`, `isActiveIssuer` |
-| `pointTokenFactoryAbi` | PointTokenFactory |
-| `mintingOracleAbi` | MintingOracle — `verifyMintCap`, `pointTokenToIssuer` |
-| `erc20Abi` | Standard ERC-20 (`allowance`, `approve`, `transfer`, `balanceOf`) |
-| `universalRouterAbi` | Uniswap UniversalRouter — `execute` |
-| `permit2Abi` | Uniswap Permit2 — `approve` |
-| `v4QuoterAbi` | Uniswap V4 Quoter — `quoteExactInput`, `quoteExactInputSingle` |
-
 ---
 
-### Constants
+## Perp deposit calldata — USDC -> Orderly
 
 ```ts
 import {
-  SUPPORTED_CHAINS,
-  COMMON_TOKENS,
-  COMMON_POOLS,
-  POINT_TOKEN_POOLS,
-  mintRequestTypes,
-  receiverConsentTypes,
+  buildPerpDepositWithGasDeduction,
+  computeAccountId,
+  BROKER_HASHES, TOKEN_HASHES, ORDERLY_VAULT_ADDRESSES,
 } from "@pafi-dev/core";
-```
-
-| Constant | Type | Description |
-|---|---|---|
-| `SUPPORTED_CHAINS` | `Record<number, ChainConfig>` | Chain ID to chain metadata map |
-| `COMMON_TOKENS` | `Record<number, Record<string, Address>>` | Chain ID to `{ symbol → address }` token map |
-| `COMMON_POOLS` | `Record<number, PoolKey[]>` | Chain ID to common pool list (e.g. stablecoin pairs) |
-| `POINT_TOKEN_POOLS` | `Record<number, Record<Address, PoolKey[]>>` | Chain ID to per-point-token pool list |
-| `mintRequestTypes` | `const` | EIP-712 typed data types for `MintRequest` |
-| `receiverConsentTypes` | `const` | EIP-712 typed data types for `ReceiverConsent` |
-
-`COMMON_POOLS` and `POINT_TOKEN_POOLS` are consumed by `combineRoutes` to assemble candidate routes for quoting.
-
----
-
-### Errors
-
-All errors extend `PafiSDKError`, which extends `Error`.
-
-```ts
-import { PafiSDKError, ConfigurationError, SigningError, ApiError } from "@pafi-dev/core";
-```
-
-| Class | Thrown when |
-|---|---|
-| `PafiSDKError` | Base class — not thrown directly |
-| `ConfigurationError` | A required field (`pointTokenAddress`, `signer`, `provider`, etc.) is not set when a method requires it |
-| `SigningError` | A signing operation fails |
-| `ApiError` | Generic HTTP error helper for callers writing their own `fetch()` against the issuer backend; carries an optional `status` |
-
-#### Example
-
-```ts
-import { ConfigurationError, SigningError } from "@pafi-dev/core";
-
-try {
-  await sdk.signMintRequest(message);
-} catch (err) {
-  if (err instanceof ConfigurationError) {
-    console.error(`SDK misconfigured: ${err.message}`);
-  } else if (err instanceof SigningError) {
-    console.error(`Signing failed: ${err.message}`);
-  }
-}
-```
-
----
-
-## EIP-712 Type Reference
-
-The PointToken contract is the authoritative EIP-712 domain contract.
-
-### Domain
-
-```
-name: <token name from ERC-20 name()>
-version: "1"
-chainId: <network chain ID>
-verifyingContract: <PointToken address>
-```
-
-### MintRequest
-
-```
-MintRequest(address to, uint256 amount, uint256 nonce, uint256 deadline)
-```
-
-| Field | Type | Description |
-|---|---|---|
-| `to` | `address` | Recipient of the minted tokens |
-| `amount` | `uint256` | Token amount to mint |
-| `nonce` | `uint256` | Anti-replay nonce from `mintRequestNonces(to)` |
-| `deadline` | `uint256` | Unix timestamp after which the signature expires |
-
-The minter (issuer signer) signs this struct. The nonce must match `pointToken.mintRequestNonces(to)` at the time of execution.
-
-### ReceiverConsent
-
-```
-ReceiverConsent(address onBehalfOf, address originalReceiver, uint256 amount, uint256 nonce, uint256 deadline)
-```
-
-| Field | Type | Description |
-|---|---|---|
-| `onBehalfOf` | `address` | Address whose points are being redirected |
-| `originalReceiver` | `address` | The original recipient who is granting consent |
-| `amount` | `uint256` | Token amount involved in the consent |
-| `nonce` | `uint256` | Anti-replay nonce from `receiverConsentNonces(originalReceiver)` |
-| `deadline` | `uint256` | Unix timestamp after which the signature expires |
-
-The original receiver signs this struct to authorize minting on behalf of another address.
-
----
-
-## PointToken Mint Paths
-
-The Relay contract supports three mint paths depending on which signatures are provided:
-
-| Path | Signer | Receiver consent required | Description |
-|---|---|---|---|
-| 1 | Minter (issuer signer) | No | Issuer mints directly to `receiver`. Only the `minterSig` is validated. |
-| 2 | Minter + Receiver | Yes | Issuer mints on behalf of `receiver`, who has pre-signed a `ReceiverConsent`. Both signatures are validated. |
-| 3 | Minter + Relayer | No | Issuer authorizes a relayer to execute the mint-and-swap. The relayer submits the transaction. |
-
-In all paths, the `MintParams.minterSig` is a `MintRequest` EIP-712 signature. Path 2 additionally requires `MintParams.receiverSig`, which is a `ReceiverConsent` EIP-712 signature.
-
----
-
-## Type Reference
-
-### Core types
-
-```ts
-interface MintRequest {
-  to: Address;
-  amount: bigint;
-  nonce: bigint;
-  deadline: bigint;
-}
-
-interface ReceiverConsent {
-  onBehalfOf: Address;
-  originalReceiver: Address;
-  amount: bigint;
-  nonce: bigint;
-  deadline: bigint;
-}
-
-interface EIP712Signature {
-  v: number;
-  r: Hex;
-  s: Hex;
-  serialized: Hex;
-}
-
-interface SignatureVerification {
-  isValid: boolean;
-  recoveredAddress: Address;
-}
-
-interface PointTokenDomainConfig {
-  name: string;
-  verifyingContract: Address;
-  chainId: number;
-}
-```
-
-### Relay types
-
-```ts
-interface MintParams {
-  pointToken: Address;
-  receiver: Address;
-  amount: bigint;
-  deadline: bigint;
-  minterSig: Hex;
-  receiverSig: Hex;
-}
-
-interface PathKey {
-  intermediateCurrency: Address;
-  fee: number;
-  tickSpacing: number;
-  hooks: Address;
-  hookData: Hex;
-}
-
-interface SwapParams {
-  path: PathKey[];
-  deadline: bigint;
-}
-```
-
-### Pool and issuer types
-
-```ts
-interface PoolKey {
-  currency0: Address;
-  currency1: Address;
-  fee: number;
-  tickSpacing: number;
-  hooks: Address;
-}
-
-interface Issuer {
-  issuerAddress: Address;
-  signerAddress: Address;
-  name: string;
-  symbol: string;
-  declaredTotalSupply: bigint;
-  capBasisPoints: number;
-  active: boolean;
-  pointToken: Address;
-  mintingOracle: Address;
-}
-```
-
-### Quoting types
-
-```ts
-interface QuoteResult {
-  amountOut: bigint;
-  gasEstimate: bigint;
-  path: PathKey[];
-}
-
-interface BestQuote {
-  bestRoute: QuoteResult;
-  allRoutes: QuoteResult[];
-}
-```
-
----
-
-## Integration Guide
-
-### Flow 1: Direct swap via UniversalRouter
-
-Use this when a user wants to swap tokens directly (not through the PAFI Relay).
 
-```ts
-import { PafiSDK } from "@pafi-dev/core";
-import { UNIVERSAL_ROUTER_ADDRESSES } from "@pafi-dev/core";
-import { universalRouterAbi } from "@pafi-dev/core/abi";
+const accountId = computeAccountId("0xUser", BROKER_HASHES["woofi_pro"]);
 
-const sdk = new PafiSDK({
+const userOp = buildPerpDepositWithGasDeduction({
   chainId: 8453,
-  rpcUrl: "https://base-mainnet.g.alchemy.com/v2/...",
-  signer: walletClient,
-});
-
-// 1. Quote — discovers all routes and picks the best via multicall
-const { bestRoute, allRoutes } = await sdk.findBestQuote(
-  tokenIn,               // e.g. WETH address
-  USDC,                  // output token
-  parseEther("1"),       // input amount
-  myPools,               // optional: your own pools (merged with COMMON_POOLS)
-);
-
-console.log(`Best route: ${formatUnits(bestRoute.amountOut, 6)} USDC`);
-console.log(`Found ${allRoutes.length} valid routes`);
-
-// 2. Build swap calldata — caller decides minAmountOut (slippage)
-const minReceive = bestRoute.amountOut * 99n / 100n; // 1% slippage
-const { commands, inputs } = sdk.buildSwapFromQuote({
-  quote: bestRoute,
-  currencyIn: tokenIn,
-  currencyOut: USDC,
-  amountIn: parseEther("1"),
-  minAmountOut: minReceive,
-});
-
-// 3. Approve (one-time): token → Permit2 → UniversalRouter
-//    ERC20.approve(PERMIT2, MAX)
-//    Permit2.approve(token, UNIVERSAL_ROUTER, MAX, MAX_EXPIRY)
-
-// 4. Execute swap
-const deadline = BigInt(Math.floor(Date.now() / 1000) + 1800);
-await walletClient.writeContract({
-  address: UNIVERSAL_ROUTER_ADDRESSES[8453],
-  abi: universalRouterAbi,
-  functionName: "execute",
-  args: [commands, inputs, deadline],
+  sender: "0xUser",
+  usdcAddress: "0xUSDC...",
+  vaultAddress: ORDERLY_VAULT_ADDRESSES[8453],
+  amount: 100n * 10n ** 6n,
+  accountId,
+  brokerHash: BROKER_HASHES["woofi_pro"],
+  tokenHash: TOKEN_HASHES["USDC"],
+  layerZeroFee: layerZeroFeeWei, // from Vault.getDepositFee()
+  aaNonce: 0n,
+  batchExecutorAddress: addrs.batchExecutor,
 });
 ```
 
-### Flow 2: Mint-and-swap via Relay (the PAFI cash-out flow)
-
-The frontend signs, the issuer backend submits. This is the primary PAFI flow.
-
-#### Frontend (signs + sends to backend)
-
-The SDK builds the EIP-712 typed data object. You can sign it with any signer:
-- **viem WalletClient** — use `sdk.signReceiverConsent()` directly
-- **Privy / WalletConnect / external** — use `sdk.buildReceiverConsentTypedData()` to get the typed data, then pass it to the external signer's `signTypedData`
-
-```ts
-import { PafiSDK } from "@pafi-dev/core";
-
-const sdk = new PafiSDK({
-  chainId: 8453,
-  rpcUrl: "https://base-mainnet.g.alchemy.com/v2/...",
-  pointTokenAddress: "0xPointToken...",
-  // signer is optional — not needed if using Privy/external signer
-});
-
-// 1. Quote
-const { bestRoute } = await sdk.findBestQuote(
-  pointTokenAddress, USDC, amount, pointTokenPools,
-);
-
-// 2. Set swap terms
-const minReceive = bestRoute.amountOut * 99n / 100n;
-const feeInUsdt = 1_000_000n; // 1 USDC relayer fee
-const extData = sdk.encodeExtData(minReceive, feeInUsdt);
-
-// 3. Read nonce + build typed data
-const nonce = await sdk.getReceiverConsentNonce(userAddress);
-const deadline = BigInt(Math.floor(Date.now() / 1000) + 1800);
-const consentMessage = {
-  onBehalfOf: relayAddress,
-  originalReceiver: userAddress,
-  amount,
-  nonce,
-  deadline,
-  extData,
-};
-
-// 4a. Sign with Privy (or any external signer)
-const typedData = await sdk.buildReceiverConsentTypedData(consentMessage);
-const receiverSig = await privy.signTypedData(typedData);
-// receiverSig is a 0x-prefixed hex string (65 bytes)
-
-// 4b. Or sign with viem WalletClient (if signer is set on SDK)
-// const { serialized: receiverSig } = await sdk.signReceiverConsent(consentMessage);
-
-// 5. Send to issuer backend (HTTP — not part of @pafi-dev/core)
-await fetch(`${ISSUER_URL}/claim-and-swap`, {
-  method: "POST",
-  headers: { "Content-Type": "application/json" },
-  body: JSON.stringify({
-    receiver: userAddress,
-    amount: amount.toString(),
-    deadline: deadline.toString(),
-    receiverSig,
-    path: bestRoute.path,
-    minAmountOut: minReceive.toString(),
-    feeInUsdt: feeInUsdt.toString(),
-  }),
-});
-```
-
-#### Issuer backend (signs + submits tx)
+---
 
-The backend can sign with a viem WalletClient, or use `buildMintRequestTypedData`
-to get the typed data for an external signer (HSM/KMS).
+## SIWE login message
 
 ```ts
-import { PafiSDK } from "@pafi-dev/core";
-import { relayAbi } from "@pafi-dev/core/abi";
+import { createLoginMessage } from "@pafi-dev/core";
 
-const sdk = new PafiSDK({
+const message = createLoginMessage({
+  address: "0xUser",
+  domain: "app.gg56.com",
   chainId: 8453,
-  rpcUrl: "...",
-  pointTokenAddress: "0xPointToken...",
-  // signer is optional — not needed if using HSM/KMS via buildMintRequestTypedData
-});
-
-// 1. Issuer signs MintRequest
-const mintNonce = await sdk.getMintRequestNonce(receiver);
-const mintMessage = { to: receiver, amount, nonce: mintNonce, deadline };
-
-// Option A: Sign with viem WalletClient (set signer on SDK)
-// const { serialized: minterSig } = await sdk.signMintRequest(mintMessage);
-
-// Option B: Build typed data for external signer (HSM/KMS/Privy)
-const typedData = await sdk.buildMintRequestTypedData(mintMessage);
-const minterSig = await externalSigner.signTypedData(typedData);
-
-// 2. Build Relay params from the frontend's quote path
-const { swapParams, extData } = sdk.buildRelaySwapParams({
-  quote: { path: requestBody.path },
-  minAmountOut: BigInt(requestBody.minAmountOut),
-  feeInUsdt: BigInt(requestBody.feeInUsdt),
-  deadline: BigInt(requestBody.deadline),
-});
-
-// 3. Submit to Relay contract
-await relayerWallet.writeContract({
-  address: relayAddress,
-  abi: relayAbi,
-  functionName: "mintAndSwap",
-  args: [
-    {
-      pointToken: pointTokenAddress,
-      receiver,
-      amount,
-      deadline,
-      minterSig,
-      receiverSig: requestBody.receiverSig,
-      extData,
-    },
-    swapParams,
-  ],
+  nonce: "abc123",          // from GET /auth/nonce
+  issuedAt: new Date().toISOString(),
+  uri: "https://app.gg56.com",
 });
 ```
 
 ---
 
-## Development
+## Changelog
 
-This package is part of the `pafi-sdk` monorepo. To work on it in isolation:
-
-```bash
-cd packages/core
-pnpm build       # Compile TypeScript with tsup (ESM + CJS dual output)
-pnpm test        # Run vitest test suite
-pnpm typecheck   # Type-check without emitting (tsc --noEmit)
-```
-
-From the monorepo root:
-
-```bash
-pnpm build       # Build all packages
-pnpm test        # Test all packages
-pnpm typecheck   # Type-check all packages
-```
-
-### Output
-
-`tsup` produces dual ESM + CJS output under `dist/`. Each sub-path export (`./eip712`, `./relay`, etc.) has its own entry in the bundle with full type declarations.
-
----
+### 0.3.0-beta.10
+- Removed `sponsor-auth/` module (PAFI-signed EIP-712 SponsorAuth — superseded by Pimlico proxy)
+- All Base mainnet contract addresses live and verified against deployed contracts
 
-## License
+### 0.3.0-beta.8/9
+- Full 4-scenario UserOp builders (mint, burn, swap, perp_deposit)
+- Added `SponsorAuth` signing helpers (removed in beta.10)
 
-UNLICENSED
+### 0.3.0-alpha.0
+- Initial EIP-7702 BatchExecutor support, UserOp primitives