@pafi-dev/core 0.1.0

package/README.md

@@ -0,0 +1,1157 @@
+# @pafi/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.
+
+**`@pafi/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/core viem
+```
+
+`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/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);
+```
+
+---
+
+## 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 |
+|---|---|
+| `@pafi/core` | All exports (PafiSDK class + everything below) |
+| `@pafi/core/eip712` | `buildMintRequestTypedData`, `buildReceiverConsentTypedData`, `signMintRequest`, `verifyMintRequest`, `signReceiverConsent`, `verifyReceiverConsent`, `buildDomain` |
+| `@pafi/core/relay` | `encodeMintAndSwap`, `decodeMintAndSwap`, `buildRelaySwapParams`, `encodeExtData`, `decodeExtData` |
+| `@pafi/core/contract` | `getMintRequestNonce`, `getReceiverConsentNonce`, `isMinter`, `getTokenName`, `getIssuer`, `isActiveIssuer`, `verifyMintCap`, `getPointTokenIssuer`, `getFeeBasisPoints`, `getSlippageBasisPoints`, `getUsdt` |
+| `@pafi/core/quoting` | `quoteExactInput`, `quoteExactInputSingle`, `quoteBestRoute`, `findBestQuote`, `buildAllPaths`, `combineRoutes` |
+| `@pafi/core/swap` | `checkAllowance`, `buildErc20ApprovalCalldata`, `buildPermit2ApprovalCalldata`, `buildUniversalRouterExecuteArgs`, `buildSwapFromQuote`, `buildV4SwapInput` |
+| `@pafi/core/auth` | `createLoginMessage`, `parseLoginMessage`, `verifyLoginMessage` (EIP-4361) |
+| `@pafi/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/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/core/eip712`)
+
+```ts
+import {
+  buildDomain,
+  signMintRequest,
+  verifyMintRequest,
+  signReceiverConsent,
+  verifyReceiverConsent,
+} from "@pafi/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/core/relay`)
+
+```ts
+import {
+  encodeMintAndSwap,
+  decodeMintAndSwap,
+  encodeMintAndSwapV2,
+  decodeMintAndSwapV2,
+} from "@pafi/core/relay";
+```
+
+##### 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/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/core/contract`)
+
+```ts
+import {
+  getMintRequestNonce,
+  getReceiverConsentNonce,
+  isMinter,
+  getTokenName,
+  getPointTokenIssuerAddress,
+} from "@pafi/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/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/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/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
+```
+
+---
+
+### Quoting
+
+#### Pure functions (from `@pafi/core/quoting`)
+
+```ts
+import {
+  quoteExactInput,
+  quoteExactInputSingle,
+  quoteBestRoute,
+  findBestQuote,
+  buildAllPaths,
+  combineRoutes,
+} from "@pafi/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`
+
+```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.
+
+##### `quoteBestRoute`
+
+```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/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`);
+```
+
+---
+
+### Swap Building
+
+#### Pure functions (from `@pafi/core/swap`)
+
+```ts
+import {
+  checkAllowance,
+  buildErc20ApprovalCalldata,
+  buildPermit2ApprovalCalldata,
+  buildUniversalRouterExecuteArgs,
+  buildV4SwapInput,
+} from "@pafi/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`
+
+```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`.
+
+##### `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/core/quoting";
+import { buildSwapFromQuote } from "@pafi/core/swap";
+
+// 1. Quote
+const { bestRoute } = await findBestQuote(client, 8453, tokenIn, USDC, amountIn, myPools);
+
+// 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,
+});
+
+// 3. Execute via UniversalRouter
+```
+
+---
+
+### Auth helpers (EIP-4361 — Sign-In With Ethereum)
+
+#### Pure functions (from `@pafi/core/auth`)
+
+```ts
+import {
+  createLoginMessage,
+  parseLoginMessage,
+  verifyLoginMessage,
+} from "@pafi/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
+
+```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>
+```
+
+The SDK does not post the signed message for you — the frontend calls
+its own `fetch()` against the issuer backend:
+
+```ts
+// 1. Fetch nonce from the issuer backend
+const { nonce } = await fetch(`${ISSUER_URL}/auth/nonce`).then(r => r.json());
+
+// 2. Build + sign the login message
+const message = await sdk.createLoginMessage({
+  domain: "app.example.com",
+  uri: "https://app.example.com",
+  nonce,
+});
+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/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/core/abi` or from the root import.
+
+```ts
+import {
+  pointTokenAbi,
+  relayAbi,
+  relayV2Abi,
+  issuerRegistryAbi,
+  pointTokenFactoryAbi,
+  mintingOracleAbi,
+  erc20Abi,
+  universalRouterAbi,
+  permit2Abi,
+  v4QuoterAbi,
+} from "@pafi/core/abi";
+```
+
+| 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
+
+```ts
+import {
+  SUPPORTED_CHAINS,
+  COMMON_TOKENS,
+  COMMON_POOLS,
+  POINT_TOKEN_POOLS,
+  mintRequestTypes,
+  receiverConsentTypes,
+} from "@pafi/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/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/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/core";
+import { UNIVERSAL_ROUTER_ADDRESSES } from "@pafi/core";
+import { universalRouterAbi } from "@pafi/core/abi";
+
+const sdk = new PafiSDK({
+  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],
+});
+```
+
+### 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/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/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).
+
+```ts
+import { PafiSDK } from "@pafi/core";
+import { relayAbi } from "@pafi/core/abi";
+
+const sdk = new PafiSDK({
+  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,
+  ],
+});
+```
+
+---
+
+## Development
+
+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.
+
+---
+
+## License
+
+UNLICENSED