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
This system leverages the ERC-4337 Account Abstraction standard to provide flexible gas fee management across the Shibarium ecosystem.

Types of Shib Paymasters

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:
git clone https://github.com/shibaone/account-abstraction-sdk.git
2

Navigate to Project

Change to the project directory:
cd account-abstraction-sdk
3

Install Dependencies

Install the required dependencies:
npm install
4

Build Project

Build the project:
npm run build
5

Install Yalc

Install yalc globally for local package publishing:
npm install -g yalc
6

Publish Locally

Publish the package locally:
yalc publish
7

Add to Your Project

Go to your project and install this package:
yalc add shib-account-abstraction-sdk@latest
8

Link Package

Link the package:
yalc link shib-account-abstraction-sdk@latest
9

Install in Project

Now you can use this package in your project:
npm install shib-account-abstraction-sdk

Usage

Basic Setup

To use the SDK, create an instance of the Shib4337 class and call its methods:
const shibAAservice = Shib4337.init({
  signer,
  options,
  paymasterOptions
});

Paymaster Options

To use Paymaster-as-a-service, you need to provide the configuration for the paymaster in the options object:
PropertyDescription
paymasterUrlThe URL of the paymaster service. Format: https://paymaster.shib.io/shibarium/<api-key>, where the API key is acquired from the developer portal.
isSponsoredA boolean value to determine if the transactions are sponsored.
sponsorshipPolicyIdThe sponsorship policy ID for the paymaster.
paymasterAddressThe address of the paymaster contract.
paymasterTokenAddressThe address of the token used by the ERC20 paymaster.
amountToApproveThe amount to approve for the ERC20 paymaster.

Creating Transactions

Use the createTransaction 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 the addTransaction method:
await shibAAservice.addTransaction(transactionObj);
The transactionObj has the following structure:
KeyValue
toThe destination address.
valueThe amount of Ether to send (in wei).
dataThe transaction data (e.g., encoded function call).
operationThe operation type (0 for call, 1 for delegate call).

Creating User Operations

To create a user operation, provide the settings:
const userOp = await shibAAservice.createTransaction({
  transactions: [],
  options: paymasterOptions
});

Paymaster Types

The SDK supports several Paymaster types, each with different requirements:
TypeNumberDescription
NoPaymaster (Default)0No Paymaster is used; standard transaction fees apply.
PaymasterContract1Uses an on-chain Paymaster contract. Requires paymasterAddress.
VerifyingPaymaster2Uses a sponsored off-chain Paymaster service. Requires paymasterUrl.
ERC20Paymaster3Uses an on-chain ERC-20 Paymaster. Requires paymasterAddress and paymasterTokenAddress.
OffchainPaymaster4Uses a non-sponsored off-chain Paymaster service. Requires paymasterUrl and paymasterTokenAddress.
CustomPaymaster5Allows custom Paymaster configurations. Requires paymasterAndData.

Options Properties

The options object should have the following properties:
PropertyRequiredDescription
typeYESThe Paymaster type (see above).
paymasterAndDataFor CustomPaymaster, a string specifying custom Paymaster data.
amountToApproveAmount of tokens to approve for the ERC-20 Paymaster.
validUntilExpiry time for the Paymaster (timestamp).
validAfterStart time for the Paymaster (timestamp).
feeEstimatorA function or value to estimate fees for the Paymaster.

Examples

import { Shib4337 } from 'shib-account-abstraction-sdk';
import { ethers } from 'ethers';

// Create signer for Shib4337 service
const provider = new ethers.JsonRpcProvider('https://puppynet.shibrpc.com');
const signer = new ethers.Wallet(PRIVATE_KEY, provider);

const paymasterUrl = 'https://offchainpaymaster.shibinternal.com/';

// Initialize the Shib4337 service
const shibAAservice = Shib4337.init({
    signer,
    options: {
      owners: [signer.address],
      threshold: 1,
      saltNonce: '0'
    },
    paymasterOptions: {
      paymasterUrl: paymasterUrl,
      isSponsored: true,
      sponsorshipPolicyId: ''
    }
  })

// Get the safe smart contract address of user
const address = await shibAAservice.getWalletAddress()

// Create transaction object
const transactionObj = {
  to: destinationAddress,
  value: etherValue,
  data: transactionData,
  operation: operationType // 0 for call, 1 for delegate call
}

// Add transaction to the queue
const res = await shibAAservice.addTransaction(transaction1)

// Get transaction queue
const res = await shibAAservice.getTransactions()

// Create options for sponsored paymaster
const sponsoredPaymasterOptions = {
  type: 2
}

// Create the transaction operation
const userOp = await shibAAservice.createTransaction({
  transactions:[],
  options: sponsoredPaymasterOptions
});

// Execute the transaction
const executeResponse = await shibAAservice.executeTransaction({
      userOp,
      signer
    });

const userOpHash = executeResponse.userOpHash;
const receipt = await executeResponse.wait();
console.log({receipt});

// Get transaction status
const res = await shibAAservice.getUserOpsByHash(userOpHash);
console.log(`Find the transaction on explorer at: https://puppynet.shib.io/tx/${res.transactionHash}`);

API Reference

Shib4337 Class Methods

init
function
required
Initialize the Shib4337 service with configuration options.
getWalletAddress
function
required
Get the safe smart contract address for the user.
addTransaction
function
required
Add a transaction to the execution queue.
getTransactions
function
required
Retrieve all transactions in the current queue.
createTransaction
function
required
Create a user operation from queued transactions with paymaster options.
executeTransaction
function
required
Execute a user operation on the blockchain.
getUserOpsByHash
function
required
Get transaction details by user operation hash.

Troubleshooting

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.