@pafi-dev/issuer 0.3.0-alpha.0 → 0.3.0-beta.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Address, Hex, PublicClient, Chain } from 'viem';
-import { PointTokenDomainConfig, MintRequest, EIP712Signature, MintParams, SwapParams, ReceiverConsent, PathKey, PoolKey, SponsorshipScenario, PartialUserOperation } from '@pafi-dev/core';
+import { PointTokenDomainConfig, MintRequest, EIP712Signature, MintParams, SwapParams, MintRequestV2, SignatureStruct, PartialUserOperation, BurnConsent, ReceiverConsent, PathKey, PoolKey, SponsorshipScenario } from '@pafi-dev/core';
 export { encodeExtData } from '@pafi-dev/core';
 
 /**
@@ -565,6 +565,75 @@ declare class RelayService {
      * can ship (blocker B1). Kept for v0.2.x consumers. Removed in 2.0.
      */
     submitMintAndSwap(params: SubmitMintAndSwapParams): Promise<RelayResult>;
+    /**
+     * Build an unsigned UserOp for Scenario 1 (Mint).
+     *
+     * Flow:
+     *   1. Encode `Relayer.mint(request, userSig, issuerSig)` as the inner call
+     *   2. Optionally append a PT fee transfer from user → feeRecipient
+     *      (fee recovery happens on-chain via BatchExecutor, not via an
+     *      operator wallet)
+     *   3. Wrap all inner calls into `BatchExecutor.execute(calls[])`
+     *   4. Return a `PartialUserOperation` ready for:
+     *        - gas estimation (Bundler)
+     *        - paymaster sponsorship (PAFI Backend)
+     *        - user signature (Privy)
+     */
+    prepareMint(params: PrepareMintParams): PartialUserOperation;
+    /**
+     * Build an unsigned UserOp for Scenario 2 (Burn/Redeem).
+     *
+     * Two modes:
+     *   - `mode: 'burn'` — direct `PointToken.burn(amount)`; `msg.sender`
+     *     via EIP-7702 delegation is the user, so no signature needed
+     *     on-chain (the BurnConsent was already verified off-chain by
+     *     the issuer backend before we got here)
+     *   - `mode: 'burnWithSig'` — `PointToken.burnWithSig(consent, sig)`;
+     *     used when the issuer hasn't verified the consent and the
+     *     contract has to do it on-chain
+     */
+    prepareBurn(params: PrepareBurnParams): PartialUserOperation;
+}
+interface PrepareMintParams {
+    /** User EOA that will send the UserOp (via EIP-7702 delegation). */
+    userAddress: Address;
+    /** ERC-4337 account nonce (not the MintRequest nonce — different namespace). */
+    aaNonce: bigint;
+    /** Deployed Relayer v2 contract address (chain-specific). */
+    relayerAddress: Address;
+    /** BatchExecutor delegation target (chain-specific). */
+    batchExecutorAddress: Address;
+    /** PointToken being minted — used for optional fee transfer call. */
+    pointTokenAddress: Address;
+    /** EIP-712-signed MintRequest fields. */
+    mintRequest: MintRequestV2;
+    /** User's EIP-712 signature over `mintRequest`. */
+    userSignature: SignatureStruct;
+    /** Issuer's EIP-712 signature over `mintRequest`. */
+    issuerSignature: SignatureStruct;
+    /** Gas limits — defaults are conservative; caller can tighten. */
+    callGasLimit?: bigint;
+    verificationGasLimit?: bigint;
+    preVerificationGas?: bigint;
+}
+type PrepareBurnParams = PrepareBurnDirectParams | PrepareBurnWithSigParams;
+interface PrepareBurnCommonParams {
+    userAddress: Address;
+    aaNonce: bigint;
+    pointTokenAddress: Address;
+    batchExecutorAddress: Address;
+    callGasLimit?: bigint;
+    verificationGasLimit?: bigint;
+    preVerificationGas?: bigint;
+}
+interface PrepareBurnDirectParams extends PrepareBurnCommonParams {
+    mode: "burn";
+    amount: bigint;
+}
+interface PrepareBurnWithSigParams extends PrepareBurnCommonParams {
+    mode: "burnWithSig";
+    burnConsent: BurnConsent;
+    consentSignature: SignatureStruct;
 }
 
 interface FeeManagerConfig {
@@ -1260,6 +1329,143 @@ declare class IssuerApiHandlers {
     handleClaimAndSwap(userAddress: Address, request: ApiClaimAndSwapRequest): Promise<ApiClaimAndSwapResponse>;
 }
 
+/**
+ * v1.4 reverse flow — **Variant A**: user-initiated PT redeem.
+ *
+ * User has on-chain PT, wants to convert back to off-chain points. They
+ * sign a `BurnConsent`, the issuer backend verifies it, reserves an
+ * off-chain credit, and returns an unsigned UserOp that the frontend
+ * submits via the Bundler. When the burn lands, the `BurnIndexer`
+ * (elsewhere) resolves the credit.
+ *
+ * **Mocked SC contracts** — this handler compiles + wires end-to-end
+ * against `@pafi-dev/core/contracts` mock ABIs. When SC ships real
+ * ABIs, no changes here — only `contracts/index.ts` re-export flips.
+ */
+interface PTRedeemHandlerConfig {
+    ledger: IPointLedger;
+    relayService: RelayService;
+    provider: PublicClient;
+    /** PointToken contract address (chain-specific). */
+    pointTokenAddress: Address;
+    /** BatchExecutor delegation target (chain-specific). */
+    batchExecutorAddress: Address;
+    /** Chain id — used for domain separator when verifying BurnConsent. */
+    chainId: number;
+    /**
+     * EIP-712 domain fields. Must match the on-chain PointToken's domain
+     * separator exactly, or signature verification fails. `name` is
+     * typically the PointToken's ERC-20 name (e.g. "PAFI Starbucks
+     * Points"). `verifyingContract` defaults to `pointTokenAddress`.
+     */
+    domain: {
+        name: string;
+        verifyingContract?: Address;
+    };
+    /**
+     * How long the pending credit stays reserved if the burn never lands.
+     * Default: 15 min — long enough for a bundler submission + confirmation.
+     */
+    redeemLockDurationMs?: number;
+    /** Clock injection for tests; defaults to `Date.now`. */
+    now?: () => number;
+}
+interface PTRedeemRequest {
+    userAddress: Address;
+    amount: bigint;
+    /** Serialized EIP-712 signature over the BurnConsent. */
+    consentSignature: Hex;
+    consent: BurnConsent;
+    /** ERC-4337 account nonce for the user's EOA. */
+    aaNonce: bigint;
+}
+interface PTRedeemResponse {
+    /** Lock id from the ledger — client polls status with this. */
+    lockId: string;
+    /** Unsigned UserOp — FE attaches paymaster + user signature + submits. */
+    userOp: PartialUserOperation;
+    /** Seconds until the lock expires if the burn doesn't land. */
+    expiresInSeconds: number;
+}
+declare class PTRedeemError extends Error {
+    code: "INVALID_CONSENT" | "SIGNATURE_MISMATCH" | "AMOUNT_MISMATCH" | "EXPIRED_CONSENT" | "LEDGER_NOT_SUPPORTED";
+    constructor(code: "INVALID_CONSENT" | "SIGNATURE_MISMATCH" | "AMOUNT_MISMATCH" | "EXPIRED_CONSENT" | "LEDGER_NOT_SUPPORTED", message: string);
+}
+declare class PTRedeemHandler {
+    private readonly ledger;
+    private readonly relayService;
+    private readonly pointTokenAddress;
+    private readonly batchExecutorAddress;
+    private readonly chainId;
+    private readonly domain;
+    private readonly redeemLockDurationMs;
+    private readonly now;
+    constructor(config: PTRedeemHandlerConfig);
+    handle(request: PTRedeemRequest): Promise<PTRedeemResponse>;
+}
+
+/**
+ * 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 (calculating shortfall +
+ * checking on-chain balance) on top.
+ */
+interface TopUpRedemptionHandlerConfig {
+    ledger: IPointLedger;
+    ptRedeemHandler: PTRedeemHandler;
+    provider: PublicClient;
+    /** PointToken contract address (chain-specific). */
+    pointTokenAddress: Address;
+}
+interface TopUpRedemptionRequest {
+    userAddress: Address;
+    /** Total points the voucher redemption requires off-chain. */
+    requiredAmount: bigint;
+    /**
+     * The user's pre-signed `BurnConsent` + signature, prepared by the FE
+     * with amount set to a worst-case upper bound. Handler inspects the
+     * shortfall and uses the consent if the shortfall ≤ consent.amount.
+     */
+    redeemRequest: Pick<PTRedeemRequest, "consent" | "consentSignature" | "aaNonce">;
+}
+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: "INSUFFICIENT_ONCHAIN_BALANCE" | "CONSENT_AMOUNT_TOO_LOW" | "LEDGER_NOT_SUPPORTED";
+    constructor(code: "INSUFFICIENT_ONCHAIN_BALANCE" | "CONSENT_AMOUNT_TOO_LOW" | "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>;
+}
+
 /**
  * Config for `createSubgraphPoolsProvider`.
  */
@@ -1716,4 +1922,4 @@ declare function createIssuerService(config: IssuerServiceConfig): IssuerService
 /** SDK package version — bumped on every release */
 declare const PAFI_ISSUER_SDK_VERSION = "0.1.0";
 
-export { type ApiBuildConsentTypedDataRequest, type ApiBuildConsentTypedDataResponse, type ApiClaimAndSwapRequest, type ApiClaimAndSwapResponse, 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, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IIssuerSigner, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerService, type IssuerServiceConfig, type LockedMintRequest, type LoginResult, MemoryPointLedger, MemorySessionStore, type MemorySessionStoreOptions, type MintAndCashOutRequest, type MintAndCashOutResponse, type MintEvent, MintingGateway, type MintingGatewayConfig, MintingGatewayError, type MintingGatewayErrorCode, type MintingStatus, NonceManager, type OperatorWalletLike, PAFI_ISSUER_SDK_VERSION, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, PrivateKeySigner, type PrivateKeySignerOptions, RelayError, type RelayErrorCode, type RelayResult, RelayService, type RelayServiceConfig, type Session, type SponsorshipRequest, type SponsorshipResponse, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type SubmitMintAndSwapParams, authenticateRequest, createIssuerService, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider };
+export { type ApiBuildConsentTypedDataRequest, type ApiBuildConsentTypedDataResponse, type ApiClaimAndSwapRequest, type ApiClaimAndSwapResponse, 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, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IIssuerSigner, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerService, type IssuerServiceConfig, type LockedMintRequest, type LoginResult, MemoryPointLedger, MemorySessionStore, type MemorySessionStoreOptions, type MintAndCashOutRequest, type MintAndCashOutResponse, type MintEvent, MintingGateway, type MintingGatewayConfig, MintingGatewayError, type MintingGatewayErrorCode, type MintingStatus, NonceManager, type OperatorWalletLike, PAFI_ISSUER_SDK_VERSION, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, PrivateKeySigner, type PrivateKeySignerOptions, RelayError, type RelayErrorCode, type RelayResult, RelayService, type RelayServiceConfig, type Session, type SponsorshipRequest, type SponsorshipResponse, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type SubmitMintAndSwapParams, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Address, Hex, PublicClient, Chain } from 'viem';
-import { PointTokenDomainConfig, MintRequest, EIP712Signature, MintParams, SwapParams, ReceiverConsent, PathKey, PoolKey, SponsorshipScenario, PartialUserOperation } from '@pafi-dev/core';
+import { PointTokenDomainConfig, MintRequest, EIP712Signature, MintParams, SwapParams, MintRequestV2, SignatureStruct, PartialUserOperation, BurnConsent, ReceiverConsent, PathKey, PoolKey, SponsorshipScenario } from '@pafi-dev/core';
 export { encodeExtData } from '@pafi-dev/core';
 
 /**
@@ -565,6 +565,75 @@ declare class RelayService {
      * can ship (blocker B1). Kept for v0.2.x consumers. Removed in 2.0.
      */
     submitMintAndSwap(params: SubmitMintAndSwapParams): Promise<RelayResult>;
+    /**
+     * Build an unsigned UserOp for Scenario 1 (Mint).
+     *
+     * Flow:
+     *   1. Encode `Relayer.mint(request, userSig, issuerSig)` as the inner call
+     *   2. Optionally append a PT fee transfer from user → feeRecipient
+     *      (fee recovery happens on-chain via BatchExecutor, not via an
+     *      operator wallet)
+     *   3. Wrap all inner calls into `BatchExecutor.execute(calls[])`
+     *   4. Return a `PartialUserOperation` ready for:
+     *        - gas estimation (Bundler)
+     *        - paymaster sponsorship (PAFI Backend)
+     *        - user signature (Privy)
+     */
+    prepareMint(params: PrepareMintParams): PartialUserOperation;
+    /**
+     * Build an unsigned UserOp for Scenario 2 (Burn/Redeem).
+     *
+     * Two modes:
+     *   - `mode: 'burn'` — direct `PointToken.burn(amount)`; `msg.sender`
+     *     via EIP-7702 delegation is the user, so no signature needed
+     *     on-chain (the BurnConsent was already verified off-chain by
+     *     the issuer backend before we got here)
+     *   - `mode: 'burnWithSig'` — `PointToken.burnWithSig(consent, sig)`;
+     *     used when the issuer hasn't verified the consent and the
+     *     contract has to do it on-chain
+     */
+    prepareBurn(params: PrepareBurnParams): PartialUserOperation;
+}
+interface PrepareMintParams {
+    /** User EOA that will send the UserOp (via EIP-7702 delegation). */
+    userAddress: Address;
+    /** ERC-4337 account nonce (not the MintRequest nonce — different namespace). */
+    aaNonce: bigint;
+    /** Deployed Relayer v2 contract address (chain-specific). */
+    relayerAddress: Address;
+    /** BatchExecutor delegation target (chain-specific). */
+    batchExecutorAddress: Address;
+    /** PointToken being minted — used for optional fee transfer call. */
+    pointTokenAddress: Address;
+    /** EIP-712-signed MintRequest fields. */
+    mintRequest: MintRequestV2;
+    /** User's EIP-712 signature over `mintRequest`. */
+    userSignature: SignatureStruct;
+    /** Issuer's EIP-712 signature over `mintRequest`. */
+    issuerSignature: SignatureStruct;
+    /** Gas limits — defaults are conservative; caller can tighten. */
+    callGasLimit?: bigint;
+    verificationGasLimit?: bigint;
+    preVerificationGas?: bigint;
+}
+type PrepareBurnParams = PrepareBurnDirectParams | PrepareBurnWithSigParams;
+interface PrepareBurnCommonParams {
+    userAddress: Address;
+    aaNonce: bigint;
+    pointTokenAddress: Address;
+    batchExecutorAddress: Address;
+    callGasLimit?: bigint;
+    verificationGasLimit?: bigint;
+    preVerificationGas?: bigint;
+}
+interface PrepareBurnDirectParams extends PrepareBurnCommonParams {
+    mode: "burn";
+    amount: bigint;
+}
+interface PrepareBurnWithSigParams extends PrepareBurnCommonParams {
+    mode: "burnWithSig";
+    burnConsent: BurnConsent;
+    consentSignature: SignatureStruct;
 }
 
 interface FeeManagerConfig {
@@ -1260,6 +1329,143 @@ declare class IssuerApiHandlers {
     handleClaimAndSwap(userAddress: Address, request: ApiClaimAndSwapRequest): Promise<ApiClaimAndSwapResponse>;
 }
 
+/**
+ * v1.4 reverse flow — **Variant A**: user-initiated PT redeem.
+ *
+ * User has on-chain PT, wants to convert back to off-chain points. They
+ * sign a `BurnConsent`, the issuer backend verifies it, reserves an
+ * off-chain credit, and returns an unsigned UserOp that the frontend
+ * submits via the Bundler. When the burn lands, the `BurnIndexer`
+ * (elsewhere) resolves the credit.
+ *
+ * **Mocked SC contracts** — this handler compiles + wires end-to-end
+ * against `@pafi-dev/core/contracts` mock ABIs. When SC ships real
+ * ABIs, no changes here — only `contracts/index.ts` re-export flips.
+ */
+interface PTRedeemHandlerConfig {
+    ledger: IPointLedger;
+    relayService: RelayService;
+    provider: PublicClient;
+    /** PointToken contract address (chain-specific). */
+    pointTokenAddress: Address;
+    /** BatchExecutor delegation target (chain-specific). */
+    batchExecutorAddress: Address;
+    /** Chain id — used for domain separator when verifying BurnConsent. */
+    chainId: number;
+    /**
+     * EIP-712 domain fields. Must match the on-chain PointToken's domain
+     * separator exactly, or signature verification fails. `name` is
+     * typically the PointToken's ERC-20 name (e.g. "PAFI Starbucks
+     * Points"). `verifyingContract` defaults to `pointTokenAddress`.
+     */
+    domain: {
+        name: string;
+        verifyingContract?: Address;
+    };
+    /**
+     * How long the pending credit stays reserved if the burn never lands.
+     * Default: 15 min — long enough for a bundler submission + confirmation.
+     */
+    redeemLockDurationMs?: number;
+    /** Clock injection for tests; defaults to `Date.now`. */
+    now?: () => number;
+}
+interface PTRedeemRequest {
+    userAddress: Address;
+    amount: bigint;
+    /** Serialized EIP-712 signature over the BurnConsent. */
+    consentSignature: Hex;
+    consent: BurnConsent;
+    /** ERC-4337 account nonce for the user's EOA. */
+    aaNonce: bigint;
+}
+interface PTRedeemResponse {
+    /** Lock id from the ledger — client polls status with this. */
+    lockId: string;
+    /** Unsigned UserOp — FE attaches paymaster + user signature + submits. */
+    userOp: PartialUserOperation;
+    /** Seconds until the lock expires if the burn doesn't land. */
+    expiresInSeconds: number;
+}
+declare class PTRedeemError extends Error {
+    code: "INVALID_CONSENT" | "SIGNATURE_MISMATCH" | "AMOUNT_MISMATCH" | "EXPIRED_CONSENT" | "LEDGER_NOT_SUPPORTED";
+    constructor(code: "INVALID_CONSENT" | "SIGNATURE_MISMATCH" | "AMOUNT_MISMATCH" | "EXPIRED_CONSENT" | "LEDGER_NOT_SUPPORTED", message: string);
+}
+declare class PTRedeemHandler {
+    private readonly ledger;
+    private readonly relayService;
+    private readonly pointTokenAddress;
+    private readonly batchExecutorAddress;
+    private readonly chainId;
+    private readonly domain;
+    private readonly redeemLockDurationMs;
+    private readonly now;
+    constructor(config: PTRedeemHandlerConfig);
+    handle(request: PTRedeemRequest): Promise<PTRedeemResponse>;
+}
+
+/**
+ * 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 (calculating shortfall +
+ * checking on-chain balance) on top.
+ */
+interface TopUpRedemptionHandlerConfig {
+    ledger: IPointLedger;
+    ptRedeemHandler: PTRedeemHandler;
+    provider: PublicClient;
+    /** PointToken contract address (chain-specific). */
+    pointTokenAddress: Address;
+}
+interface TopUpRedemptionRequest {
+    userAddress: Address;
+    /** Total points the voucher redemption requires off-chain. */
+    requiredAmount: bigint;
+    /**
+     * The user's pre-signed `BurnConsent` + signature, prepared by the FE
+     * with amount set to a worst-case upper bound. Handler inspects the
+     * shortfall and uses the consent if the shortfall ≤ consent.amount.
+     */
+    redeemRequest: Pick<PTRedeemRequest, "consent" | "consentSignature" | "aaNonce">;
+}
+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: "INSUFFICIENT_ONCHAIN_BALANCE" | "CONSENT_AMOUNT_TOO_LOW" | "LEDGER_NOT_SUPPORTED";
+    constructor(code: "INSUFFICIENT_ONCHAIN_BALANCE" | "CONSENT_AMOUNT_TOO_LOW" | "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>;
+}
+
 /**
  * Config for `createSubgraphPoolsProvider`.
  */
@@ -1716,4 +1922,4 @@ declare function createIssuerService(config: IssuerServiceConfig): IssuerService
 /** SDK package version — bumped on every release */
 declare const PAFI_ISSUER_SDK_VERSION = "0.1.0";
 
-export { type ApiBuildConsentTypedDataRequest, type ApiBuildConsentTypedDataResponse, type ApiClaimAndSwapRequest, type ApiClaimAndSwapResponse, 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, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IIssuerSigner, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerService, type IssuerServiceConfig, type LockedMintRequest, type LoginResult, MemoryPointLedger, MemorySessionStore, type MemorySessionStoreOptions, type MintAndCashOutRequest, type MintAndCashOutResponse, type MintEvent, MintingGateway, type MintingGatewayConfig, MintingGatewayError, type MintingGatewayErrorCode, type MintingStatus, NonceManager, type OperatorWalletLike, PAFI_ISSUER_SDK_VERSION, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, PrivateKeySigner, type PrivateKeySignerOptions, RelayError, type RelayErrorCode, type RelayResult, RelayService, type RelayServiceConfig, type Session, type SponsorshipRequest, type SponsorshipResponse, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type SubmitMintAndSwapParams, authenticateRequest, createIssuerService, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider };
+export { type ApiBuildConsentTypedDataRequest, type ApiBuildConsentTypedDataResponse, type ApiClaimAndSwapRequest, type ApiClaimAndSwapResponse, 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, type BurnEvent, BurnIndexer, type BurnIndexerConfig, type CombinedBalance, DefaultPolicyEngine, type DefaultPolicyEngineOptions, FeeManager, type FeeManagerConfig, type IIndexerCursorStore, type IIssuerSigner, type IPointLedger, type IPolicyEngine, type ISessionStore, InMemoryCursorStore, IssuerApiHandlers, type IssuerApiHandlersConfig, type IssuerService, type IssuerServiceConfig, type LockedMintRequest, type LoginResult, MemoryPointLedger, MemorySessionStore, type MemorySessionStoreOptions, type MintAndCashOutRequest, type MintAndCashOutResponse, type MintEvent, MintingGateway, type MintingGatewayConfig, MintingGatewayError, type MintingGatewayErrorCode, type MintingStatus, NonceManager, type OperatorWalletLike, PAFI_ISSUER_SDK_VERSION, PTRedeemError, PTRedeemHandler, type PTRedeemHandlerConfig, type PTRedeemRequest, type PTRedeemResponse, PafiBackendClient, type PafiBackendConfig, PafiBackendError, type PafiBackendErrorCode, PointIndexer, type PointIndexerConfig, type PolicyDecision, type PolicyEvalRequest, type PoolsProvider, PrivateKeySigner, type PrivateKeySignerOptions, RelayError, type RelayErrorCode, type RelayResult, RelayService, type RelayServiceConfig, type Session, type SponsorshipRequest, type SponsorshipResponse, type SubgraphNativeUsdtQuoterConfig, type SubgraphPoolsProviderConfig, type SubmitMintAndSwapParams, TopUpRedemptionError, TopUpRedemptionHandler, type TopUpRedemptionHandlerConfig, type TopUpRedemptionRequest, type TopUpRedemptionResponse, authenticateRequest, createIssuerService, createSubgraphNativeUsdtQuoter, createSubgraphPoolsProvider };