@pafi-dev/issuer 0.3.0-beta.3 → 0.3.0-beta.4

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { Address, Hex, PublicClient, Chain } from 'viem';
-import { PointTokenDomainConfig, MintRequest, EIP712Signature, MintParams, SwapParams, PartialUserOperation, BurnConsent, SignatureStruct, ReceiverConsent, PathKey, PoolKey, SponsorshipScenario } from '@pafi-dev/core';
+import { Address, Hex, PublicClient, Chain, WalletClient } from 'viem';
+import { PointTokenDomainConfig, MintRequest, EIP712Signature, MintParams, SwapParams, PartialUserOperation, BurnRequest, ReceiverConsent, PathKey, PoolKey, SponsorshipScenario } from '@pafi-dev/core';
 export { encodeExtData } from '@pafi-dev/core';
 
 /**
@@ -523,14 +523,18 @@ interface RelayServiceConfig {
     simulateBeforeSubmit?: boolean;
 }
 /**
- * Submits `mintAndSwap` transactions to the Relay contract on behalf of
- * the issuer. This is the single place the operator wallet is touched; the
- * MintingGateway calls into `submitMintAndSwap()` after it has signed the
- * MintRequest and verified the ReceiverConsent.
+ * Submits `mintAndSwap` transactions to the Relay contract (legacy
+ * v0.2 path) and builds unsigned UserOps for the v1.4 sponsored flow.
  *
- * The service is intentionally thin: calldata encoding stays in `@pafi/core`
- * (`encodeMintAndSwap`), so on-chain ABI changes only ripple through one
- * package.
+ * v1.4 flow (post-Relayer-removal):
+ *   - `prepareMint` — signs `MintRequest` with the issuer signer and
+ *     encodes `PointToken.mint(to, amount, deadline, minterSig)` into
+ *     a UserOp the user submits via EIP-7702 + Paymaster.
+ *   - `prepareBurn` — mirrors on the burn side using `BurnRequest` +
+ *     `PointToken.burn(from, amount, deadline, burnerSig)`.
+ *
+ * Legacy v0.2 `submitMintAndSwap` still broadcasts via operator wallet
+ * for the deprecated `/claim-and-swap` endpoint.
  */
 declare class RelayService {
     private readonly relayAddress;
@@ -548,76 +552,51 @@ declare class RelayService {
      */
     encodeCall(params: SubmitMintAndSwapParams): Hex;
     /**
-     * Submit a `mintAndSwap` transaction. Flow:
-     *
-     *   1. (optional) pre-flight simulate via provider
-     *   2. writeContract through the operator wallet
-     *   3. (optional) wait for the receipt and surface gasUsed / status
-     *
-     * Throws a typed `RelayError` on any failure so the MintingGateway can
-     * decide whether to release the ledger lock (`SUBMIT_FAILED` and
-     * `SIMULATION_FAILED` are safe to release; `TX_REVERTED` and `TIMEOUT`
-     * need manual review because the tx may still land).
+     * Submit a `mintAndSwap` transaction (legacy v0.2 `/claim-and-swap`).
      *
-     * @deprecated Since 0.3.0 — will be replaced by `prepareMint()` +
-     * `prepareBurn()` in the v1.4 sponsored-UserOp flow. The SC team
-     * still needs to finalize Relayer v2 ABI before the replacements
-     * can ship (blocker B1). Kept for v0.2.x consumers. Removed in 2.0.
+     * @deprecated Since 0.3.0 — replaced by `prepareMint` / `prepareBurn`
+     * in the v1.4 sponsored-UserOp flow. Kept for v0.2.x consumers;
+     * scheduled removal in 2.0.
      */
     submitMintAndSwap(params: SubmitMintAndSwapParams): Promise<RelayResult>;
     /**
-     * Build an unsigned UserOp for Scenario 1 (Mint).
+     * Build an unsigned UserOp for Scenario 1 (Mint) — sig-gated
+     * `PointToken.mint(to, amount, deadline, minterSig)`.
      *
      * 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)
-     */
-    /**
-     * Build an unsigned UserOp for Scenario 1 (Mint) — direct
-     * `PointToken.mint(amount)` flow (v1.4 post-Relayer-removal).
-     *
-     * `msg.sender` inside the batch = user EOA via EIP-7702 delegation.
-     * `PointToken.mint` checks the caller is on its `minters` allowlist
-     * (gg56 BE pre-validates this off-chain to avoid wasted gas).
-     *
-     * Optional PT fee transfer is appended after the mint when
-     * `feeAmount > 0` — this is application-level fee recovery (no
-     * Relayer doing it for us). The user must end up with `amount - fee`
-     * net PT after the batch executes.
-     */
-    prepareMint(params: PrepareMintParams): PartialUserOperation;
+     *   1. Issuer backend signs `MintRequest(to=user, amount, nonce, deadline)`
+     *      with its minter signer (HSM/KMS) → `minterSig`.
+     *   2. Encode `PointToken.mint(user, amount, deadline, minterSig)`.
+     *      On-chain, `msg.sender` must equal `to` — satisfied by EIP-7702
+     *      delegating the user EOA to BatchExecutor.
+     *   3. Optional PT fee transfer appended after mint (application-level
+     *      fee recovery since Relayer v2 no longer exists).
+     *   4. Return `PartialUserOperation` ready for Bundler gas estimate +
+     *      Paymaster sponsorship + user signature.
+     */
+    prepareMint(params: PrepareMintParams): Promise<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
+     *   - `mode: 'burn'` — direct `PointToken.burn(from, amount)`; only
+     *     usable if the user is a whitelisted burner. Not the typical
+     *     v1.4 path (users aren't burners); kept for admin/operator tools.
+     *   - `mode: 'burnWithSig'` — `PointToken.burn(from, amount, deadline,
+     *     burnerSig)`. Issuer signs `BurnRequest` off-chain; user submits
+     *     via EIP-7702. `msg.sender == from` enforced on-chain. This is
+     *     the user-initiated redeem path in v1.4.
      */
     prepareBurn(params: PrepareBurnParams): PartialUserOperation;
 }
 /**
- * v1.4 — direct PointToken.mint() flow (no Relayer, no MintRequest sig).
+ * v1.4 — sig-gated `PointToken.mint(to, amount, deadline, minterSig)`.
  *
- * Backend (gg56) validates off-chain:
- *   - User is on `PointToken.minters[]` allowlist
- *   - User has enough off-chain points to claim
- *   - Policy passes (KYC, cap, cooldown)
- *
- * Then locks the off-chain balance and returns this UserOp for the FE
- * to sponsor + submit. On confirmation, PointIndexer watches the
- * `Transfer(0x0, user, amount)` event and resolves the lock.
+ * The issuer backend validates off-chain (balance, policy, KYC), signs
+ * a `MintRequest` EIP-712 with its minter signer, and packages the
+ * whole thing into a UserOp for the user to submit via EIP-7702 +
+ * Paymaster. On confirmation, PointIndexer watches `Transfer(0x0, user,
+ * amount)` and resolves the ledger lock.
  */
 interface PrepareMintParams {
     /** User EOA that will send the UserOp (via EIP-7702 delegation). */
@@ -626,14 +605,25 @@ interface PrepareMintParams {
     aaNonce: bigint;
     /** BatchExecutor delegation target (chain-specific). */
     batchExecutorAddress: Address;
-    /** PointToken contract — the call target. */
+    /** PointToken contract — the call target + EIP-712 verifying contract. */
     pointTokenAddress: Address;
-    /** PT amount to mint to `userAddress` (= msg.sender via EIP-7702). */
+    /** PT amount to mint to `userAddress`. */
     amount: bigint;
+    /**
+     * Issuer minter signer wallet — signs the `MintRequest` EIP-712.
+     * Must be added to `PointToken.minters[]` via `addMinter(signerAddr)`
+     * at provisioning time. Typically HSM/KMS-backed in prod.
+     */
+    issuerSignerWallet: WalletClient;
+    /** EIP-712 domain for MintRequest (name + chainId + verifyingContract). */
+    domain: PointTokenDomainConfig;
+    /** Current `mintRequestNonces[userAddress]` — caller reads from contract. */
+    mintRequestNonce: bigint;
+    /** Unix timestamp after which the signature expires. */
+    deadline: bigint;
     /**
      * Optional — application-level fee transfer appended after mint.
-     * Set both `feeAmount` and `feeRecipient` together. Skipped when
-     * `feeAmount` is undefined or 0.
+     * Set both `feeAmount` and `feeRecipient` together.
      */
     feeAmount?: bigint;
     feeRecipient?: Address;
@@ -658,8 +648,10 @@ interface PrepareBurnDirectParams extends PrepareBurnCommonParams {
 }
 interface PrepareBurnWithSigParams extends PrepareBurnCommonParams {
     mode: "burnWithSig";
-    burnConsent: BurnConsent;
-    consentSignature: SignatureStruct;
+    /** BurnRequest message the issuer burner signer signed. */
+    burnRequest: BurnRequest;
+    /** Serialized EIP-712 signature (bytes) over `burnRequest`. */
+    burnerSignature: Hex;
 }
 
 interface FeeManagerConfig {
@@ -1356,17 +1348,29 @@ declare class IssuerApiHandlers {
 }
 
 /**
- * v1.4 reverse flow — **Variant A**: user-initiated PT redeem.
+ * v1.4 reverse flow — user-initiated PT redeem.
+ *
+ * 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,
+ * `Transfer(user → 0x0)` is emitted; `BurnIndexer` resolves the pending
+ * credit to a real off-chain credit.
  *
- * 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.
+ * Contract path (mock ABI — matches deployed PointToken):
  *
- * **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.
+ *   burn(address from, uint256 amount, uint256 deadline, bytes burnerSig)
+ *
+ * On-chain checks:
+ *   - msg.sender == from (enforced via EIP-7702 delegation on user EOA)
+ *   - burnerSig signer ∈ burners[]
+ *   - nonce == burnRequestNonces[from]
+ *   - now <= deadline
+ *
+ * The user never signs an EIP-712 message in this flow. Their only
+ * signature is the ERC-4337 UserOp signature, which the AA wallet
+ * handles. Consent is implicit: by submitting the UserOp they authorize
+ * the burn.
  */
 interface PTRedeemHandlerConfig {
     ledger: IPointLedger;
@@ -1376,32 +1380,41 @@ interface PTRedeemHandlerConfig {
     pointTokenAddress: Address;
     /** BatchExecutor delegation target (chain-specific). */
     batchExecutorAddress: Address;
-    /** Chain id — used for domain separator when verifying BurnConsent. */
+    /** Chain id — used for the BurnRequest EIP-712 domain. */
     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`.
+     * separator, or on-chain signature recovery fails. `name` is
+     * typically the PointToken's ERC-20 name. `verifyingContract`
+     * defaults to `pointTokenAddress`.
      */
     domain: {
         name: string;
         verifyingContract?: Address;
     };
+    /**
+     * Issuer burner signer wallet — signs the `BurnRequest` EIP-712.
+     * Must be whitelisted via `PointToken.addBurner(signerAddr)` at
+     * provisioning time. Typically HSM/KMS-backed in prod.
+     */
+    burnerSignerWallet: WalletClient;
     /**
      * How long the pending credit stays reserved if the burn never lands.
      * Default: 15 min — long enough for a bundler submission + confirmation.
      */
     redeemLockDurationMs?: number;
+    /**
+     * How far ahead of `now` to set the BurnRequest deadline. Default:
+     * 15 min. Must be long enough for Bundler + EntryPoint to execute;
+     * short enough to prevent replay if the UserOp is abandoned.
+     */
+    signatureDeadlineSeconds?: 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;
 }
@@ -1412,19 +1425,24 @@ interface PTRedeemResponse {
     userOp: PartialUserOperation;
     /** Seconds until the lock expires if the burn doesn't land. */
     expiresInSeconds: number;
+    /** The BurnRequest deadline (unix seconds) — FE uses this to surface a countdown. */
+    signatureDeadline: bigint;
 }
 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);
+    code: "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED";
+    constructor(code: "INVALID_AMOUNT" | "NONCE_READ_FAILED" | "LEDGER_NOT_SUPPORTED" | "SIGNING_FAILED", message: string);
 }
 declare class PTRedeemHandler {
     private readonly ledger;
     private readonly relayService;
+    private readonly provider;
     private readonly pointTokenAddress;
     private readonly batchExecutorAddress;
     private readonly chainId;
     private readonly domain;
+    private readonly burnerSignerWallet;
     private readonly redeemLockDurationMs;
+    private readonly signatureDeadlineSeconds;
     private readonly now;
     constructor(config: PTRedeemHandlerConfig);
     handle(request: PTRedeemRequest): Promise<PTRedeemResponse>;
@@ -1445,8 +1463,12 @@ declare class PTRedeemHandler {
  *   → 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.
+ * — 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;
@@ -1459,12 +1481,8 @@ 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">;
+    /** ERC-4337 account nonce for the user's EOA. */
+    aaNonce: bigint;
 }
 type TopUpRedemptionResponse = {
     action: "NO_TOP_UP_NEEDED";
@@ -1480,8 +1498,8 @@ type TopUpRedemptionResponse = {
     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);
+    code: "INSUFFICIENT_ONCHAIN_BALANCE" | "LEDGER_NOT_SUPPORTED";
+    constructor(code: "INSUFFICIENT_ONCHAIN_BALANCE" | "LEDGER_NOT_SUPPORTED", message: string);
 }
 declare class TopUpRedemptionHandler {
     private readonly ledger;