Shib Paymasters provide two different types of paymasters to help abstract away gas fees for users in the Shibarium ecosystem using the ERC-4337 standard. These paymasters allow for more flexibility in how gas fees are handled, either by sponsoring them on behalf of users or by letting users pay using ERC-20 tokens.
Overview
Shib Paymasters enable developers to create seamless user experiences by handling gas fees in two ways:- Sponsored Transactions: Developers pay gas fees on behalf of users
- ERC-20 Token Payments: Users pay gas fees using their preferred tokens
Types of Shib Paymasters
Verifying Paymaster
Sponsor gas fees for your users using an off-chain API and on-chain smart contract verification.
ERC-20 Paymaster
Allow users to pay gas fees using ERC-20 tokens like USDC instead of native tokens.
Verifying Paymaster
The Shib Verifying Paymaster is a system that allows you to sponsor gas fees for your users on Shibarium. By utilizing an off-chain API and an on-chain smart contract, this paymaster lets users perform actions on-chain without needing to worry about gas fees.Get API Key
Developers who wish to use our Paymaster-as-a-service feature go to the Developer Portal and acquire an API key.
Configure Integration
Append your API key to the Paymaster URL, which will be required during the integration through the Account Abstraction SDK.
User Operations
Users, when interacting with an app integrated with Shib’s account-abstraction SDK, can generate on-chain operations. This SDK can submit these operations behind the scenes.
Signature Generation
The paymaster works by receiving an API call from SDK where a signature is generated and returned to the caller.
On-chain Verification
This signature is used by the on-chain smart contract to verify that the gas fees for the user operation should be sponsored.
ERC-20 Paymaster
The Shib ERC-20 Paymaster is a permissionless, on-chain smart contract that allows your users to pay for gas fees using their ERC-20 tokens. This provides flexibility by enabling users to cover gas costs with a wide variety of tokens, such as USDC, rather than native tokens like ETH.User Operations
Users perform operations on-chain and can use their ERC-20 tokens to pay for gas fees.
Developer Registration
Developers register on the Developer Portal, create an ERC-20 paymaster and integrate it in their transactions, via Shib’s Account Abstraction SDK.
Contract Deployment
The Shib ERC-20 Paymaster contracts will be deployed on Shibarium for a specific ERC-20 token, allowing users to pay gas in ERC-20 tokens seamlessly.
Installation
Prerequisites
Before installing the SDK, ensure you have:- Node.js
- npm
Setup Steps
Usage
Basic Setup
To use the SDK, create an instance of theShib4337 class and call its methods:
Paymaster Options
To use Paymaster-as-a-service, you need to provide the configuration for the paymaster in the options object:| Property | Description |
|---|---|
| paymasterUrl | The URL of the paymaster service. Format: https://paymaster.shib.io/shibarium/<api-key>, where the API key is acquired from the developer portal. |
| isSponsored | A boolean value to determine if the transactions are sponsored. |
| sponsorshipPolicyId | The sponsorship policy ID for the paymaster. |
| paymasterAddress | The address of the paymaster contract. |
| paymasterTokenAddress | The address of the token used by the ERC20 paymaster. |
| amountToApprove | The amount to approve for the ERC20 paymaster. |
Creating Transactions
Use thecreateTransaction method to prepare transactions for execution. You can add multiple transactions to a queue and then create a single user operation (userOp).
Adding Transactions
Add transactions to the queue using theaddTransaction method:
transactionObj has the following structure:
| Key | Value |
|---|---|
| to | The destination address. |
| value | The amount of Ether to send (in wei). |
| data | The transaction data (e.g., encoded function call). |
| operation | The operation type (0 for call, 1 for delegate call). |
Creating User Operations
To create a user operation, provide the settings:Paymaster Types
The SDK supports several Paymaster types, each with different requirements:| Type | Number | Description |
|---|---|---|
| NoPaymaster (Default) | 0 | No Paymaster is used; standard transaction fees apply. |
| PaymasterContract | 1 | Uses an on-chain Paymaster contract. Requires paymasterAddress. |
| VerifyingPaymaster | 2 | Uses a sponsored off-chain Paymaster service. Requires paymasterUrl. |
| ERC20Paymaster | 3 | Uses an on-chain ERC-20 Paymaster. Requires paymasterAddress and paymasterTokenAddress. |
| OffchainPaymaster | 4 | Uses a non-sponsored off-chain Paymaster service. Requires paymasterUrl and paymasterTokenAddress. |
| CustomPaymaster | 5 | Allows custom Paymaster configurations. Requires paymasterAndData. |
Options Properties
Theoptions object should have the following properties:
| Property | Required | Description |
|---|---|---|
| type | YES | The Paymaster type (see above). |
| paymasterAndData | For CustomPaymaster, a string specifying custom Paymaster data. | |
| amountToApprove | Amount of tokens to approve for the ERC-20 Paymaster. | |
| validUntil | Expiry time for the Paymaster (timestamp). | |
| validAfter | Start time for the Paymaster (timestamp). | |
| feeEstimator | A function or value to estimate fees for the Paymaster. |
Examples
Sponsored Paymaster Example
API Reference
Shib4337 Class Methods
Initialize the Shib4337 service with configuration options.
Get the safe smart contract address for the user.
Add a transaction to the execution queue.
Retrieve all transactions in the current queue.
Create a user operation from queued transactions with paymaster options.
Execute a user operation on the blockchain.
Get transaction details by user operation hash.
Troubleshooting
Installation Issues
Installation Issues
Problem: Unable to install or build the SDKSolutions:
- Ensure Node.js version is compatible (v16+ recommended)
- Clear npm cache:
npm cache clean --force - Delete node_modules and package-lock.json, then reinstall
- Check for conflicting global packages
- Verify git repository access permissions
Paymaster Configuration Errors
Paymaster Configuration Errors
Problem: Paymaster integration fails or returns errorsSolutions:
- Verify API key is valid and active
- Check paymaster URL format and accessibility
- Ensure paymaster contract addresses are correct
- Validate token addresses for ERC-20 paymasters
- Check network connectivity to paymaster services
Transaction Execution Failures
Transaction Execution Failures
Problem: User operations fail to executeSolutions:
- Verify user has sufficient funds for gas fees
- Check transaction data encoding is correct
- Ensure paymaster has sufficient funds for sponsored transactions
- Validate transaction parameters (to, value, data, operation)
- Monitor gas price and network congestion