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.1
Get API Key
Developers who wish to use our Paymaster-as-a-service feature go to the Developer Portal and acquire an API key.
2
Configure Integration
Append your API key to the Paymaster URL, which will be required during the integration through the Account Abstraction SDK.
3
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.
4
Signature Generation
The paymaster works by receiving an API call from SDK where a signature is generated and returned to the caller.
5
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.
6
Fee Payment
The gas fees are paid from funds added by the developers who built the application into the paymaster smart contract.
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.1
User Operations
Users perform operations on-chain and can use their ERC-20 tokens to pay for gas fees.
2
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.
3
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.
4
Price Oracle Integration
This ERC-20 Paymaster contract will have an owner address, ERC-20 token address and oracles that fetch the latest price of ERC-20 token and native asset.
Installation
Prerequisites
Before installing the SDK, ensure you have:- Node.js
- npm
Setup Steps
1
Clone Repository
Clone the account abstraction SDK repository:
2
Navigate to Project
Change to the project directory:
3
Install Dependencies
Install the required dependencies:
4
Build Project
Build the project:
5
Install Yalc
Install yalc globally for local package publishing:
6
Publish Locally
Publish the package locally:
7
Add to Your Project
Go to your project and install this package:
8
Link Package
Link the package:
9
Install in Project
Now you can use this package in your project:
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
Best Practices
- Always test paymaster integration on testnet before mainnet deployment
- Implement proper error handling for all SDK method calls
- Monitor paymaster balance and replenish funds as needed
- Use appropriate gas estimation for transaction planning
- Implement retry logic for failed transactions
- Keep API keys secure and rotate them regularly
Never expose private keys or sensitive credentials in client-side code. Always use secure key management practices.