Shib Paymaster

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

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.

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.

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.

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

Clone Repository

Clone the account abstraction SDK repository:

git clone https://github.com/shibaone/account-abstraction-sdk.git

Navigate to Project

Change to the project directory:

cd account-abstraction-sdk

Install Dependencies

Install the required dependencies:

npm install

Build Project

Build the project:

npm run build

Install Yalc

Install yalc globally for local package publishing:

npm install -g yalc

Publish Locally

Publish the package locally:

yalc publish

Add to Your Project

Go to your project and install this package:

yalc add shib-account-abstraction-sdk@latest

Link Package

Link the package:

yalc link shib-account-abstraction-sdk@latest

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:

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 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:

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:

const userOp = await shibAAservice.createTransaction({
  transactions: [],
  options: paymasterOptions
});

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

The options 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

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

// Create signer for Shib4337 service
const provider = new ethers.JsonRpcProvider('https://rpc.puppynet.shib.io');
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}`);

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

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

const paymasterTokenAddress = "0x2258900dE1261D70D6D1643B190f3111aC056bD1"
const paymasterAddress = "0x72717b4f7d7af24739992C9B1D22BAf2203E618c"

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

// 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 non-sponsored paymaster
const erc20paymasterOptions = {
  type: 3,
  amountToApprove: 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffn
}

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

// 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

function

required

Initialize the Shib4337 service with configuration options.

function

required

Get the safe smart contract address for the user.

function

required

Add a transaction to the execution queue.

function

required

Retrieve all transactions in the current queue.

function

required

Create a user operation from queued transactions with paymaster options.

function

required

Execute a user operation on the blockchain.

function

required

Get transaction details by user operation hash.

Troubleshooting

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

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

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.

APIs & Data

Development Tools

Overview

Types of Shib Paymasters

Verifying Paymaster

ERC-20 Paymaster

Verifying Paymaster

ERC-20 Paymaster

Installation

Prerequisites

Setup Steps

Usage

Basic Setup

Paymaster Options

Creating Transactions

Adding Transactions

Creating User Operations

Paymaster Types

Options Properties

Examples

Sponsored Paymaster Example

API Reference

Shib4337 Class Methods

Troubleshooting

Best Practices

​Overview

​Types of Shib Paymasters

Verifying Paymaster

ERC-20 Paymaster

​Verifying Paymaster

​ERC-20 Paymaster

​Installation

​Prerequisites

​Setup Steps

​Usage

​Basic Setup

​Paymaster Options

​Creating Transactions

​Adding Transactions

​Creating User Operations

​Paymaster Types

​Options Properties

​Examples

​Sponsored Paymaster Example

​API Reference

​Shib4337 Class Methods

​Troubleshooting

​Best Practices

​Related Resources

Overview

Types of Shib Paymasters

Verifying Paymaster

ERC-20 Paymaster

Installation

Prerequisites

Setup Steps

Usage

Basic Setup

Paymaster Options

Creating Transactions

Adding Transactions

Creating User Operations

Paymaster Types

Options Properties

Examples

Sponsored Paymaster Example

API Reference

Shib4337 Class Methods

Troubleshooting

Best Practices

Related Resources