@glideco/paymaster

Vendor-neutral EIP-4337 paymaster interface for EVM gas sponsorship.

import {
  resolvePaymasterProvider,
  registerPaymasterProvider,
  type PaymasterProvider,
  type SponsoredUserOp,
} from '@glideco/paymaster';

// Operator-supplied: Pimlico, Alchemy, Biconomy, mock, etc.
registerPaymasterProvider(myProvider);

const sponsored = await resolvePaymasterProvider('pimlico').sponsorUserOp({
  safeAddress: '0x...',
  calldata: '0x...',
  chain: 'base',
  policyId: 'policy_xyz',
  safeNonce: 5n,
});

Why an interface

Past gas-sponsorship vendors have shifted (Octane shut down April 2026). Locking to one vendor in code is a load-bearing assumption. Future vendor swap = add a new file behind this interface + flip the discriminator column in your DB. No router/orchestrator code changes.

Cancel vs treasury fallback

After a 30s no-receipt timeout + 60s additional poll, the operator's orchestrator should attempt cancelUserOp (if supported) before falling back to treasury-pays. This package defines the interface; the double-spend-prevention nonce-claim state machine lives in your application layer (see apps/web/src/server/lib/gas-sponsorship/safe-nonce-claim.ts in the Glide repo for an example Postgres-advisory-lock impl).

SemVer policy (D18)

@glideco/paymaster is the interface package. Concrete impl packages (@glideco/paymaster-pimlico, @glideco/paymaster-alchemy-solana, future @glideco/paymaster-biconomy, etc.) declare a peer-dep on it using a caret major range:

{
  "peerDependencies": {
    "@glideco/paymaster": "^1.0.0"
  }
}

Major-bump contract. A breaking change to the PaymasterProvider interface (added required method, removed/renamed type, changed signature, etc.) requires a coordinated major bump of every impl package in the same release. The interface package never bumps major in isolation — that would silently strand impls on incompatible versions.

Compatible additions. Adding an optional method (like cancelUserOp? or getReceipt?), a new error code variant, or a new optional field is a minor bump on the interface. Impls don't need to move; ones that implement the new optional surface ship a minor of their own.

Status of v0.13.0.0 packages. All ship at 0.1.0. The first incompatible interface change after publish gates the 1.0.0 release.

License

MIT