@pafi-dev/issuer 0.5.41 → 0.5.43

package/dist/index.d.cts

@@ -507,15 +507,13 @@ declare class RelayService {
      */
     prepareMint(params: PrepareMintParams): Promise<PartialUserOperation>;
     /**
-     * Build an unsigned UserOp for Scenario 2 (Burn/Redeem).
+     * Build an unsigned UserOp for Scenario 2 (Burn/Redeem) — sig-gated
+     * `PointToken.burn(from, amount, deadline, burnerSig)`. Caller
+     * provides a pre-signed `BurnRequest` + sig bytes (typically from
+     * `PTRedeemHandler`).
      *
-     * Two modes:
-     *   - `mode: 'burn'` — direct `PointToken.burn(from, amount)`; only
-     *     usable if the caller (via EIP-7702) is whitelisted as a burner.
-     *     Rare in v1.4; kept for admin/operator tools.
-     *   - `mode: 'burnWithSig'` — `PointToken.burn(from, amount, deadline,
-     *     burnerSig)`. Caller provides a pre-signed `BurnRequest` + sig
-     *     bytes (typically from `PTRedeemHandler`).
+     * Direct burn (no sig) was dropped in v1.4 — every burn now goes
+     * through the issuer-signed `BurnRequest` path.
      */
     prepareBurn(params: PrepareBurnParams): Promise<PartialUserOperation>;
 }
@@ -562,12 +560,24 @@ interface PrepareMintParams {
     verificationGasLimit?: bigint;
     preVerificationGas?: bigint;
 }
-type PrepareBurnParams = PrepareBurnDirectParams | PrepareBurnWithSigParams;
-interface PrepareBurnCommonParams {
+/**
+ * v1.4 — sig-gated burn only. Direct (no-sig) burn was dropped because
+ * every burn now goes through `BurnRequest` EIP-712 signed by the
+ * issuer burner. The `mode: 'burnWithSig'` discriminant is preserved
+ * for backwards-compat with existing callers but is no longer
+ * branched on internally.
+ */
+interface PrepareBurnParams {
     userAddress: Address;
     aaNonce: bigint;
     pointTokenAddress: Address;
     batchExecutorAddress: Address;
+    /** Discriminant kept for backwards compat. Always `'burnWithSig'`. */
+    mode?: "burnWithSig";
+    /** BurnRequest message the issuer burner signer signed. */
+    burnRequest: BurnRequest;
+    /** Serialized EIP-712 signature (bytes) over `burnRequest`. */
+    burnerSignature: Hex;
     /**
      * Optional — application-level PT fee transfer appended after burn.
      * Used for gas reimbursement on the sponsored path. Set both
@@ -580,17 +590,6 @@ interface PrepareBurnCommonParams {
     verificationGasLimit?: bigint;
     preVerificationGas?: bigint;
 }
-interface PrepareBurnDirectParams extends PrepareBurnCommonParams {
-    mode: "burn";
-    amount: bigint;
-}
-interface PrepareBurnWithSigParams extends PrepareBurnCommonParams {
-    mode: "burnWithSig";
-    /** BurnRequest message the issuer burner signer signed. */
-    burnRequest: BurnRequest;
-    /** Serialized EIP-712 signature (bytes) over `burnRequest`. */
-    burnerSignature: Hex;
-}
 
 interface FeeManagerConfig {
     /** Provider used for gas price reads. */
@@ -627,7 +626,7 @@ interface FeeManagerConfig {
  * (PT for mint/burn, USDT for swap/perp_deposit) — not hardcoded to USDT.
  *
  * **Operator rebalancing is gone.** In v1.4 the operator no longer holds
- * ETH directly — gas is paid by Coinbase Paymaster via the paymaster-proxy
+ * ETH directly — gas is paid by PAFI sponsor-relayer via the paymaster-proxy
  * (see [SPONSORED_PATH_FLOW.md]). The fee collected here is an
  * application-level ERC-20 transfer inside the same UserOp batch, not a
  * reimbursement to a wallet that needs topping up.
@@ -985,67 +984,6 @@ interface ApiUserResponse {
     balance: bigint;
     isMinter: boolean;
 }
-interface ApiRedeemRequest {
-    userAddress: Address;
-    /** PT amount to burn. */
-    amount: bigint;
-    /** ERC-4337 account nonce for the user's EOA. */
-    aaNonce: bigint;
-}
-interface ApiRedeemResponse {
-    /** Pending credit lock id — poll `/user` to track PENDING → CREDITED. */
-    lockId: string;
-    /** Unsigned UserOp — attach paymaster data + user signature, then submit. */
-    userOp: PartialUserOperation;
-    /** Seconds until the pending credit lock expires if the burn doesn't land. */
-    expiresInSeconds: number;
-    /** BurnRequest deadline (unix seconds) — FE can surface a countdown. */
-    signatureDeadline: bigint;
-}
-interface ApiTopUpRequest {
-    userAddress: Address;
-    /** Total points the voucher requires off-chain. */
-    requiredAmount: bigint;
-    /** ERC-4337 account nonce for the user's EOA. */
-    aaNonce: bigint;
-}
-type ApiTopUpResponse = {
-    /** Off-chain balance already covers the required amount — no burn needed. */
-    action: "NO_TOP_UP_NEEDED";
-    offChainBalance: bigint;
-} | {
-    /** Combined off-chain + on-chain is still insufficient — cannot fulfill. */
-    action: "INSUFFICIENT_ONCHAIN";
-    offChainBalance: bigint;
-    onChainBalance: bigint;
-    shortfall: bigint;
-} | {
-    /** Burn of `shortfall` PT initiated — FE submits the returned UserOp. */
-    action: "TOP_UP_STARTED";
-    shortfall: bigint;
-    redeem: ApiRedeemResponse;
-};
-interface ApiClaimRequest {
-    chainId: number;
-    pointTokenAddress: Address;
-    /** PT amount to mint. */
-    amount: bigint;
-    /** ERC-4337 account nonce for the user's EOA (from EntryPoint). */
-    aaNonce: bigint;
-    /** Unix seconds — when the MintRequest signature expires. */
-    deadline: bigint;
-    /** Optional operator fee (PT) deducted inside the same UserOp batch. */
-    feeAmount?: bigint;
-    feeRecipient?: Address;
-}
-interface ApiClaimResponse {
-    /** Off-chain lock id — poll `/user` to track PENDING → MINTED. */
-    lockId: string;
-    /** Unsigned UserOp — attach paymaster data + user signature, then submit. */
-    userOp: PartialUserOperation;
-    /** Seconds until the off-chain lock expires if the UserOp is not submitted. */
-    expiresInSeconds: number;
-}
 type PoolsProvider = (request: ApiPoolsRequest) => Promise<ApiPoolsResponse>;
 
 interface IssuerApiHandlersConfig {
@@ -1075,20 +1013,6 @@ interface IssuerApiHandlersConfig {
     feeManager?: FeeManager;
     /** Required by `handlePools`; omit to disable the endpoint. */
     poolsProvider?: PoolsProvider;
-    /**
-     * Required by `handleClaim`; omit to disable the endpoint.
-     * Wires policy evaluation + ledger locking + MintRequest signing
-     * into a single atomic handler so callers cannot accidentally skip
-     * the policy check.
-     */
-    claim?: {
-        policy: IPolicyEngine;
-        relayService: RelayService;
-        issuerSignerWallet: WalletClient;
-        batchExecutorAddress: Address;
-        /** How long to hold the off-chain lock while the UserOp is in flight. Default: 15 min. */
-        lockDurationMs?: number;
-    };
 }
 /**
  * Framework-agnostic HTTP handlers that match the endpoints a `PafiSDK`
@@ -1115,7 +1039,6 @@ declare class IssuerApiHandlers {
     private readonly pafiWebUrl?;
     private readonly feeManager?;
     private readonly poolsProvider?;
-    private readonly claim?;
     constructor(config: IssuerApiHandlersConfig);
     /** `GET /auth/nonce` */
     handleGetNonce(): Promise<ApiNonceResponse>;
@@ -1147,22 +1070,6 @@ declare class IssuerApiHandlers {
      * balance.
      */
     handleUser(userAddress: Address, request: ApiUserRequest): Promise<ApiUserResponse>;
-    /**
-     * `POST /claim`
-     *
-     * Policy gate + ledger lock + MintRequest signing in a single atomic
-     * step. Returns an unsigned UserOp the frontend attaches paymaster data
-     * to and submits via EIP-7702 + Bundler.
-     *
-     * Order of operations:
-     *   1. Validate request fields.
-     *   2. policy.evaluate() — throws if denied; cannot be bypassed.
-     *   3. ledger.lockForMinting() — reserves the balance.
-     *   4. Read on-chain mintRequestNonce + token name in parallel.
-     *   5. relayService.prepareMint() — sign MintRequest + encode UserOp.
-     *   6. On any error after step 3, release the lock before re-throwing.
-     */
-    handleClaim(userAddress: Address, request: ApiClaimRequest): Promise<ApiClaimResponse>;
 }
 
 /**
@@ -1171,7 +1078,7 @@ declare class IssuerApiHandlers {
  * User has on-chain PT, wants to convert back to off-chain points. The
  * issuer backend signs a `BurnRequest` with its burner signer, reserves
  * an off-chain pending credit, and returns an unsigned UserOp. The FE
- * submits the UserOp via EIP-7702 + Coinbase Paymaster. On confirmation,
+ * submits the UserOp via EIP-7702 + PAFI sponsor-relayer. On confirmation,
  * `Transfer(user → 0x0)` is emitted; `BurnIndexer` resolves the pending
  * credit to a real off-chain credit.
  *
@@ -1333,70 +1240,6 @@ declare class PTRedeemHandler {
     private _handleAfterNonceLock;
 }
 
-/**
- * v1.4 reverse flow — **Variant B**: auto top-up on voucher redemption.
- *
- * User tries to redeem a voucher for `requiredAmount` off-chain points
- * but their off-chain balance is short. If their on-chain PT balance is
- * enough to cover the shortfall, this handler auto-triggers a burn for
- * exactly the shortfall amount so the voucher can proceed.
- *
- *   Required off-chain:   500
- *   Available off-chain:  300
- *   Shortfall:            200
- *   On-chain PT:          250    ← enough, top-up fires
- *   → burn 200 PT, credit 200 off-chain, voucher proceeds with 500
- *
- * Delegates the actual burn construction to {@link PTRedeemHandler}
- * — this handler is pure business logic (shortfall math + on-chain
- * balance check) on top.
- *
- * v1.4 note: user no longer pre-signs a `BurnConsent`. The issuer
- * backend signs a `BurnRequest` itself (see `PTRedeemHandler`), so
- * this handler only needs `userAddress + requiredAmount + aaNonce`.
- */
-interface TopUpRedemptionHandlerConfig {
-    ledger: IPointLedger;
-    ptRedeemHandler: PTRedeemHandler;
-    provider: PublicClient;
-    /** PointToken contract address (chain-specific). */
-    pointTokenAddress: Address;
-}
-interface TopUpRedemptionRequest {
-    /** Address extracted from the verified JWT — must match `userAddress`. */
-    authenticatedAddress: Address;
-    userAddress: Address;
-    /** Total points the voucher redemption requires off-chain. */
-    requiredAmount: bigint;
-    /** ERC-4337 account nonce for the user's EOA. */
-    aaNonce: bigint;
-}
-type TopUpRedemptionResponse = {
-    action: "NO_TOP_UP_NEEDED";
-    offChainBalance: bigint;
-} | {
-    action: "INSUFFICIENT_ONCHAIN";
-    offChainBalance: bigint;
-    onChainBalance: bigint;
-    shortfall: bigint;
-} | {
-    action: "TOP_UP_STARTED";
-    shortfall: bigint;
-    redeem: PTRedeemResponse;
-};
-declare class TopUpRedemptionError extends Error {
-    code: "UNAUTHORIZED" | "INSUFFICIENT_ONCHAIN_BALANCE" | "LEDGER_NOT_SUPPORTED";
-    constructor(code: "UNAUTHORIZED" | "INSUFFICIENT_ONCHAIN_BALANCE" | "LEDGER_NOT_SUPPORTED", message: string);
-}
-declare class TopUpRedemptionHandler {
-    private readonly ledger;
-    private readonly ptRedeemHandler;
-    private readonly provider;
-    private readonly pointTokenAddress;
-    constructor(config: TopUpRedemptionHandlerConfig);
-    handle(request: TopUpRedemptionRequest): Promise<TopUpRedemptionResponse>;
-}
-
 interface RetryConfig {
     maxAttempts?: number;
     initialDelayMs?: number;
@@ -1656,6 +1499,29 @@ interface IPendingUserOpStore {
  */
 declare function serializeEntryToJsonRpc(entry: PendingUserOpEntry, signature: Hex, variant?: "sponsored" | "fallback"): Record<string, string | null>;
 
+/**
+ * In-memory `IPendingUserOpStore` for **single-instance dev / test
+ * harnesses only**.
+ *
+ * Multi-instance deployments (k8s, PM2 cluster) MUST use a shared store
+ * — typically Redis with a TTL key or Postgres with `expires_at`. If
+ * `prepare` lands on instance A and `submit` on instance B, an
+ * in-memory store on A loses the entry.
+ *
+ * Entries are evicted lazily on `get()` if expired. Periodic sweep is
+ * not implemented — the in-memory map's footprint scales with
+ * outstanding pending UserOps, which is bounded by the issuer's lock
+ * duration (default 15 min).
+ */
+declare class MemoryPendingUserOpStore implements IPendingUserOpStore {
+    private readonly entries;
+    private readonly now;
+    constructor(now?: () => number);
+    save(lockId: string, entry: PendingUserOpEntry, ttlSeconds: number): Promise<void>;
+    get(lockId: string): Promise<PendingUserOpEntry | null>;
+    delete(lockId: string): Promise<void>;
+}
+
 /**
  * Re-shape `UserOpTypedData` so all `bigint` fields become hex strings —
  * required for JSON transport over HTTP. Mirrors the inverse of what
@@ -2367,17 +2233,6 @@ interface IssuerServiceConfig {
      * throws "not configured" at request time.
      */
     poolsProvider?: PoolsProvider;
-    /**
-     * Enables `handleClaim`. The factory combines these with the shared
-     * `policy` + `relayService` instances already wired by the factory.
-     * Omit to disable the `/claim` endpoint.
-     */
-    claim?: {
-        issuerSignerWallet: WalletClient;
-        /** Defaults to the PAFI-deployed BatchExecutor for the target chain. */
-        batchExecutorAddress?: Address;
-        lockDurationMs?: number;
-    };
     indexer?: {
         fromBlock?: bigint;
         cursorStore?: IIndexerCursorStore;
@@ -2457,13 +2312,13 @@ interface IssuerApiAdapterConfig {
     /** Optional issuer id — when omitted, sponsorAuth is skipped (returns `undefined`). */
     pafiIssuerId?: string;
     /** Sig-gated mint handler. Required for `claim` / `claimPrepare`. */
-    ptClaimHandler: PTClaimHandler;
+    ptClaimHandler?: PTClaimHandler | null;
     /** Reverse-flow handler. Required for `redeem` / `redeemPrepare`. */
     ptRedeemHandler?: PTRedeemHandler | null;
     /** PT → USDT swap handler. Required for `swap`. */
-    swapHandler: SwapHandler;
+    swapHandler?: SwapHandler | null;
     /** Orderly perp-deposit handler. Required for `perpDeposit`. */
-    perpHandler: PerpDepositHandler;
+    perpHandler?: PerpDepositHandler | null;
     /** Pending UserOp store — required for mobile prepare/submit. */
     pendingUserOpStore: IPendingUserOpStore;
     /** PAFI backend client — required for mobile submit + delegate submit + status fallback. */
@@ -2661,6 +2516,13 @@ declare class IssuerApiAdapter {
     private buildSponsorAuth;
     private runMobilePrepare;
     private assertRedeemHandler;
+    /**
+     * Narrow an optional handler to non-null and throw a clear error when
+     * the issuer wired the adapter without it. Lets issuers opt out of
+     * flows they don't expose (gg56 ships only mobile claim/redeem, so
+     * `swapHandler` + `perpHandler` aren't constructed).
+     */
+    private assertHandler;
 }
 
 /**
@@ -3074,4 +2936,4 @@ declare class IssuerStateValidator {
 /** SDK package version — bumped on every release */
 declare const PAFI_ISSUER_SDK_VERSION = "0.4.0";
 
-export { type ApiClaimRequest, type ApiClaimResponse, type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiRedeemRequest, type ApiRedeemResponse, type ApiTopUpRequest, type ApiTopUpResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BalanceAggregator, type BalanceAggregatorConfig, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type ClaimDto, type CombinedBalance, type ConfigDto, type DecodedCallDto, DefaultPolicyEngine, type DefaultPolicyEngineOptions, type DelegatePrepareDto, type DelegateStatusDto, FeeManager, type FeeManagerConfig, type GasFeeDto, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiAdapter, type IssuerApiAdapterConfig, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type MobilePrepareDto, type MobileSubmitDto, type NativePtQuoterConfig, NonceManager, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, PafiSdkError, type PendingCredit, type PendingUserOpEntry, PendingUserOpForbiddenError, PendingUserOpNotFoundError, type PerpDepositDto, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsDto, type PoolsProvider, type PreValidateMintResult, type PrepareBurnDirectParams, type PrepareBurnParams, type PrepareBurnWithSigParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, type QuoteDto, type QuotePointTokenToUsdtParams, type QuotePointTokenToUsdtResult, type RedeemDto, type RedeemPrepareDto, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type RetryConfig, type SdkErrorBody, type SdkErrorHttpStatus, type SdkErrorMapperFactories, type SdkErrorStatus, type SerializedUserOpTypedData, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type SwapDto, SwapError, SwapHandler, type SwapHandlerConfig, type SwapRequest, type SwapResponse, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, type UserDto, authenticateRequest, createIssuerService, createNativePtQuoter, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, quotePointTokenToUsdt, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };
+export { type ApiConfigResponse, type ApiGasFeeResponse, type ApiLoginRequest, type ApiLoginResponse, type ApiNonceResponse, type ApiPoolsRequest, type ApiPoolsResponse, type ApiUserRequest, type ApiUserResponse, type AuthContext, AuthError, type AuthErrorCode, AuthService, type AuthServiceConfig, BalanceAggregator, type BalanceAggregatorConfig, BundlerNotConfiguredError, BundlerRejectedError, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type BurnStatusParams, type BurnStatusResponse, type ClaimDto, type CombinedBalance, type ConfigDto, type DecodedCallDto, DefaultPolicyEngine, type DefaultPolicyEngineOptions, type DelegatePrepareDto, type DelegateStatusDto, FeeManager, type FeeManagerConfig, type GasFeeDto, type HandleDelegateSubmitParams, type HandleDelegateSubmitResult, type HandleMobilePrepareParams, type HandleMobilePrepareResult, type HandleMobileSubmitParams, type IIndexerCursorStore, type IPendingUserOpStore, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiAdapter, type IssuerApiAdapterConfig, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerRegistryRecord, type IssuerService, type IssuerServiceConfig, IssuerStateError, IssuerStateValidator, LockNotFoundError, type LockedMintRequest, type LoginResult, MemoryPendingUserOpStore, MemorySessionStore, type MemorySessionStoreOptions, type MintEvent, type MintStatusParams, type MintStatusResponse, type MintingStatus, type MobilePrepareDto, type MobileSubmitDto, type NativePtQuoterConfig, NonceManager, PAFI_ISSUER_SDK_VERSION, PTClaimError, PTClaimHandler, type PTClaimHandlerConfig, type PTClaimRequest, type PTClaimResponse, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, PafiSdkError, type PendingCredit, type PendingUserOpEntry, PendingUserOpForbiddenError, PendingUserOpNotFoundError, type PerpDepositDto, PerpDepositError, PerpDepositHandler, type PerpDepositHandlerConfig, type PerpDepositRequest, type PerpDepositResponse, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsDto, type PoolsProvider, type PreValidateMintResult, type PrepareBurnParams, type PrepareMintParams, type PrepareMobileUserOpParams, type PrepareMobileUserOpResult, type PreparedUserOp, type QuoteDto, type QuotePointTokenToUsdtParams, type QuotePointTokenToUsdtResult, type RedeemDto, type RedeemPrepareDto, RelayError, type RelayErrorCode, RelayService, type RelayUserOpParams, type RelayUserOpRequest, type RelayUserOpResponse, type RequestPaymasterParams, type RetryConfig, type SdkErrorBody, type SdkErrorHttpStatus, type SdkErrorMapperFactories, type SdkErrorStatus, type SerializedUserOpTypedData, type Session, type SponsorshipRequest, type SponsorshipResponse, type SponsorshipTarget, type SponsorshipUserOp, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type SwapDto, SwapError, SwapHandler, type SwapHandlerConfig, type SwapRequest, type SwapResponse, type UserDto, authenticateRequest, createIssuerService, createNativePtQuoter, createSdkErrorMapper, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider, handleClaimStatus, handleDelegateSubmit, handleMobilePrepare, handleMobileSubmit, handleRedeemStatus, mergePaymasterFields, prepareMobileUserOp, quotePointTokenToUsdt, relayUserOp, requestPaymaster, serializeEntryToJsonRpc, serializeUserOpTypedData };