@pafi-dev/core 0.18.0 → 0.20.1

package/README.md

@@ -74,7 +74,8 @@ import { getContractAddresses } from "@pafi-dev/core";
 
 const addr = getContractAddresses(8453);  // Base mainnet
 // addr.issuerRegistry, addr.mintingOracle, addr.mintFeeWrapper,
-// addr.usdt, addr.batchExecutor, addr.pafiFeeRecipient,
+// addr.usdt, addr.usdc (optional, perp-deposit + sponsor-relayer stable fee),
+// addr.batchExecutor, addr.pafiFeeRecipient,
 // addr.chainlinkEthUsd, addr.orderlyRelay, addr.universalRouter
 ```
 
@@ -139,7 +140,35 @@ to recipients. User receives `gross × (1 - bps/10000)` net.
 
 ## Operator fee quoter
 
-Two helpers for FE direct usage (no backend round-trip):
+Two execution paths depending on whether your caller has access to a
+bundler-driven estimator (recommended) or needs a self-contained quote.
+
+### Recommended: bundler-driven via `FeeManager` (issuer SDK)
+
+For issuer backends (`@pafi-dev/issuer`) and trading helpers
+(`@pafi-dev/trading`), the `FeeManager` class is wired with a
+`BundlerEstimatorClient` (typically `createPafiEstimatorClient(...)`)
+that hits PAFI sponsor-relayer's `POST /v1/estimate-gas-fee`. Server-side
+that endpoint calls Pimlico's `eth_estimateUserOperationGas`, caches by
+`(scenario, contract codehash, paymaster)` in Redis (5 min TTL), applies
+PAFI's 110% premium, and returns gas units. SDK FeeManager then converts
+to PT/USDT via the helpers below with `premiumBps: 10_000` (no
+double-pad). This is the path used by every `/claim/prepare` and
+`/redeem/prepare` flow.
+
+Same Redis key is read by sponsor-relayer's `FeeValidator` when verifying
+the submitted UserOp — so the issuer's quote and PAFI's expected fee
+match exactly (no formula drift; only ±5% slack for ETH-price movement
+between quote-time and submit-time).
+
+### Self-contained: direct helpers (FE / fallback path)
+
+When no backend round-trip is possible (FE direct `swapDirect`, or a
+caller without `BundlerEstimatorClient` wired), use these helpers
+directly. They run the same math but with **hardcoded** `SCENARIO_GAS_UNITS`
+(per-scenario table) and default `premiumBps: 12_000` (legacy 120%
+self-contained margin — higher than bundler-driven because there's no
+PAFI-side premium to layer on).
 
 ```ts
 import { quoteOperatorFeeUsdt, quoteOperatorFeePt } from "@pafi-dev/core";
@@ -149,7 +178,7 @@ const gasFeeUsdt = await quoteOperatorFeeUsdt({
   provider, chainId: 8453, scenario: "mint",
 });
 
-// PT-denominated (used by mint/burn flows). Adds V3 subgraph call.
+// PT-denominated. Adds V3 subgraph call for ptPerUsdt.
 const gasFeePt = await quoteOperatorFeePt({
   provider, chainId: 8453, scenario: "mint",
   pointTokenAddress: POINT_TOKEN,
@@ -157,13 +186,30 @@ const gasFeePt = await quoteOperatorFeePt({
 });
 ```
 
-Both return `bigint` raw units. Fallback prices (`0.1 USDT/PT` default,
-3000 USD/ETH default) used when oracles unreachable + `allowStaleFallback`
-is true. Sponsor-relayer's `FeeValidator` runs the same math server-side
-with a 5% tolerance window.
+Both return `bigint` raw units. Fallback prices (`0.1 USDT/PT`,
+`3000 USD/ETH`) used when oracles unreachable + `allowStaleFallback: true`.
+
+### Scenario table
+
+| Scenario | `gasUnits` | Notes |
+|---|---|---|
+| `mint` | 500_000n | Standard mint with wrapper |
+| `burn` | 500_000n | Standard burn |
+| `swap` | 700_000n | Single hop; multi-hop adds headroom inside the premium |
+| `perp-deposit` | 800_000n | Heavier — Orderly Vault interaction |
+| `delegate` | 200_000n | EIP-7702 no-op (gratis-sponsored as one-time onboarding) |
+| `erc20-transfer` | 200_000n | Tiny 2-call batch; bypasses bundler estimator (round-trip > savings) |
+
+### Fee math (raw bigint, no scaling shortcuts)
+
+```
+withPremium     = gasUnits × gasPrice × premiumBps / 10000     (wei)
+fee_USDT_6dec   = withPremium × ethPrice_8dec / 10^(18+8-6)
+fee_PT_18dec    = withPremium × ethPrice_8dec × ptPerUsdt_18dec / 10^26
+```
 
-See [`docs/FEE_FLOW.md`](../../../docs/FEE_FLOW.md) in the main repo for
-full math derivation.
+`ptPerUsdt_18dec` comes from the V3 subgraph (`token0Price` /
+`token1Price` inverted to PT-per-USDT, scaled to 18 decimals).
 
 ---
 
@@ -274,7 +320,6 @@ const authorized = await isMinter(provider, pointToken, signerAddress);
 ## References
 
 - Architecture: [`ARCHITECTURE.md`](../../ARCHITECTURE.md) at SDK root
-- Fee math: [`docs/FEE_FLOW.md`](../../../docs/FEE_FLOW.md)
 
 ## License
 

package/dist/abi/index.cjs

@@ -4,15 +4,20 @@
 
 
 
-var _chunkXXLIIWIFcjs = require('../chunk-XXLIIWIF.cjs');
 
 
 
 
-var _chunkC7VB6WTLcjs = require('../chunk-C7VB6WTL.cjs');
 
+var _chunk2DVM77Y2cjs = require('../chunk-2DVM77Y2.cjs');
 
-var _chunkKRHGFUDIcjs = require('../chunk-KRHGFUDI.cjs');
+
+
+
+var _chunk2CU7ZH2Acjs = require('../chunk-2CU7ZH2A.cjs');
+
+
+var _chunk245YA3CQcjs = require('../chunk-245YA3CQ.cjs');
 require('../chunk-JEQ2X3Z6.cjs');
 
 
@@ -24,5 +29,10 @@ require('../chunk-JEQ2X3Z6.cjs');
 
 
 
-exports.erc20Abi = _chunkXXLIIWIFcjs.erc20Abi; exports.issuerRegistryAbi = _chunkC7VB6WTLcjs.issuerRegistryAbi; exports.mintFeeWrapperAbi = _chunkC7VB6WTLcjs.mintFeeWrapperAbi; exports.mintingOracleAbi = _chunkC7VB6WTLcjs.mintingOracleAbi; exports.permit2Abi = _chunkXXLIIWIFcjs.permit2Abi; exports.pointTokenAbi = _chunkKRHGFUDIcjs.pointTokenAbi; exports.pointTokenFactoryAbi = _chunkXXLIIWIFcjs.pointTokenFactoryAbi; exports.universalRouterAbi = _chunkXXLIIWIFcjs.universalRouterAbi; exports.v3QuoterV2Abi = _chunkXXLIIWIFcjs.v3QuoterV2Abi;
+
+
+
+
+
+exports.erc20Abi = _chunk2DVM77Y2cjs.erc20Abi; exports.issuerRegistryAbi = _chunk2CU7ZH2Acjs.issuerRegistryAbi; exports.mintFeeWrapperAbi = _chunk2CU7ZH2Acjs.mintFeeWrapperAbi; exports.mintingOracleAbi = _chunk2CU7ZH2Acjs.mintingOracleAbi; exports.permit2Abi = _chunk2DVM77Y2cjs.permit2Abi; exports.pointModuleCoreAbi = _chunk2DVM77Y2cjs.pointModuleCoreAbi; exports.pointTokenAbi = _chunk245YA3CQcjs.pointTokenAbi; exports.pointTokenFactoryAbi = _chunk2DVM77Y2cjs.pointTokenFactoryAbi; exports.settlementVaultAbi = _chunk2DVM77Y2cjs.settlementVaultAbi; exports.tokenRegistryAbi = _chunk2DVM77Y2cjs.tokenRegistryAbi; exports.universalRouterAbi = _chunk2DVM77Y2cjs.universalRouterAbi; exports.v3QuoterV2Abi = _chunk2DVM77Y2cjs.v3QuoterV2Abi; exports.vaultFactoryAbi = _chunk2DVM77Y2cjs.vaultFactoryAbi; exports.vaultRegistryAbi = _chunk2DVM77Y2cjs.vaultRegistryAbi;
 //# sourceMappingURL=index.cjs.map

package/dist/abi/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/phitran/Pacific-Finance/pafi-backend/pafi-sdk/packages/core/dist/abi/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B;AACE;AACA;AACA;AACF,yDAA8B;AAC9B;AACE;AACF,yDAA8B;AAC9B,iCAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,8hBAAC","file":"/Users/phitran/Pacific-Finance/pafi-backend/pafi-sdk/packages/core/dist/abi/index.cjs"}
+{"version":3,"sources":["/Users/phitran/Pacific-Finance/pafi-backend/pafi-sdk/packages/core/dist/abi/index.cjs"],"names":[],"mappings":"AAAA;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,yDAA8B;AAC9B;AACE;AACA;AACA;AACF,yDAA8B;AAC9B;AACE;AACF,yDAA8B;AAC9B,iCAA8B;AAC9B;AACE;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACF,+1BAAC","file":"/Users/phitran/Pacific-Finance/pafi-backend/pafi-sdk/packages/core/dist/abi/index.cjs"}