@actalink/erc20-paymaster
Advanced tools
ERC20 Paymaster service for Acta Account Abstraction
A service for sponsoring ERC20 token payments, and scheduling token transfers using Actalink Account Abstraction infrastructure.
The @actalink/erc20-paymaster enables smart contract wallets to pay gas fees using ERC20 tokens instead of native ETH. This package provides a paymaster service that can be integrated with Account Abstraction infrastructure to allow for a more flexible user experience.
The ERC20 Paymaster implements a modular service architecture for handling token-based gas fee payments:
PaymasterService: The core class that orchestrates all components and manages the paymaster lifecycle.
The PaymasterService follows microservice architecture to better manage the complexity of the system. The service is divided into several components, each responsible for a specific task:
Express Application: Handles HTTP requests and provides API endpoints for:
API Routes: Endpoints for client interaction, mounted at /api/*.
Worker Thread: Background process for:
SQLite Database: Persistent storage designed to run within microservices for:
The ERC20 Paymaster service uses Sign-In with Ethereum (SIWE) for authentication. This provides a secure, web3-native way to authenticate users using their Ethereum wallets.
Request Challenge
/api/challenge-siwe with their wallet addressMessage Signing
Authentication
x-siwe-message headerx-siwe-signature header// 1. Get SIWE challenge
const challengeResponse = await fetch('/api/challenge-siwe', {
method: 'POST',
body: JSON.stringify({ walletAddress: account.address })
});
const { message } = await challengeResponse.json();
// 2. Sign message with wallet
const signature = await wallet.signMessage(message);
// 3. Make authenticated request
const response = await fetch('/api/protected-endpoint', {
headers: {
'x-siwe-message': Buffer.from(message).toString('base64'),
'x-siwe-signature': signature
}
});
npm install @actalink/erc20-paymaster
import { ERC20PaymasterService } from '@actalink/erc20-paymaster';
// Initialize the paymaster
const service = new PaymasterService({
// Configuration options
port: 4000, // Port to run the service on
enableLuciaAuth: false, // Enable Lucia authentication
enableSIWEe2eAuth: true, // Enable Sign-In with Ethereum authentication
enableWorker: true, // Enable background worker for transaction processing
bodyLimit: "1024kb", // Request body size limit
logFormat: "dev", // Morgan logging format
onUserOpSuccess: (userOp: UserOperationAndProps) => {
const { userOpHash, transactionHash } = userOp;
console.log(`UserOperation ${userOpHash} succeeded with transaction ${transactionHash}`);
// Add custom logic here (e.g., update database, notify user)
}
});
// Start the service
await service.start();
The service exposes the following REST API endpoints:
Schedules user operations for future execution. This endpoint allows you to schedule one or more user operations to be executed at a specific time.
Request Body:
[
{
"userOp": {
// UserOperation object (RpcUserOperation<'0.7'>)
"sender": "0x...",
"nonce": "0x...",
// ... other UserOperation fields
},
"userOpHash": "0x...",
"entryPoint": "0x...",
"executionTime": 1234567890000, // Unix timestamp in milliseconds
"signerAddress": "0x..."
}
// ... more operations
]
Validation:
Response:
"N UserOperations scheduled successfully!" where N is the number of operations scheduledNotes:
/cancelops endpoint before executionGenerates a Sign-In with Ethereum (SIWE) challenge message for authentication.
Request Body:
{
"walletAddress": "0x..." // The wallet address to authenticate
}
Response:
{
"message": "service.acta.link wants you to sign in with your Ethereum account:\n0x...\n\nI accept the ServiceOrg Terms of Service: https://service.org/tos\n\nURI: https://service.org/login\nVersion: 1\nChain ID: 1\nNonce: ...\nIssued At: ..."
}
Status Codes:
Usage:
Sponsors a user operation with ERC20 token payment.
Request Body:
{
"method": "pm_sponsorUserOperation",
"params": [
userOperation, // UserOperation object
entryPointAddress, // Entry point contract address
{
"type": "sponsor" // Sponsorship type
}
]
}
Response:
{
"result": {
...userOperation,
"paymasterData": "0x...", // Signed paymaster data
"paymasterVerificationGasLimit": "0x...",
"paymasterPostOpGasLimit": "0x..."
}
}
Cancels pending user operations for an authenticated user. Requires SIWE (Sign-In with Ethereum) authentication.
Headers:
x-siwe-message: <base64 encoded SIWE message>
x-siwe-signature: <signature>
Response:
[
"0x...", // Array of cancelled userOpHashes
"0x..."
]
Authentication: This endpoint requires SIWE authentication. To authenticate:
/api/challenge-siweStatus Codes:
Lists all scheduled user operations for a given smart wallet address.
Request Body:
{
"validators": ["0x..."], // Array of validator addresses
"salt": "0x..." // Salt for smart wallet address calculation
}
Response:
[
{
"userOpHash": "0x...",
"signerAddress": "0x...",
"userOp": {
// UserOperation object
},
"entryPoint": "0x...",
"executionTime": 1234567890000,
"status": "pending",
"transactionHash": ""
}
// ... more operations
]
Authentication: Requires user authentication. The endpoint verifies that the authenticated user owns the smart wallet.
Status Codes:
Lists all pending user operations for a given smart wallet address.
Request Body:
{
"validators": ["0x..."], // Array of validator addresses
"salt": "0x..." // Salt for smart wallet address calculation
}
Response:
[
{
"userOpHash": "0x...",
"signerAddress": "0x...",
"userOp": {
// UserOperation object
},
"entryPoint": "0x...",
"executionTime": 1234567890000,
"status": "pending",
"transactionHash": ""
}
// ... more operations
]
Notes:
/cancelops to manage pending operationsRetrieves a list of unique nonce keys from pending user operations for a given smart wallet address. This is useful for checking which nonce slots are currently in use by pending operations.
Request Body:
{
"validators": ["0x..."], // Array of validator addresses
"salt": "0x..." // Salt for smart wallet address calculation
}
Response:
[
"0x1234...", // Array of unique nonce keys (first 42 characters of the nonce)
"0x5678..."
]
Notes:
The PaymasterService class provides the following methods:
start(): Starts the HTTP server and worker thread (if enabled)stop(): Stops the service and terminates the worker threadgetApp(): Returns the Express application instance for custom configurationFor detailed API documentation including TypeScript types and interfaces, run:
npm run docs
Then open docs/index.html in your browser.
The PaymasterService accepts the following configuration options:
| Option | Type | Description | Default |
|---|---|---|---|
port | number | Port number for the HTTP server | 4000 |
enableSIWEe2eAuth | boolean | Enable Sign-In with Ethereum authentication | true |
enableWorker | boolean | Enable background worker for transaction processing | true |
workerPath | string | Path to worker thread script | "build/workers/scheduler.js" |
bodyLimit | string | Request body size limit | "1024kb" |
logFormat | string | Morgan logging format | "dev" |
onUserOpSuccess | (userOp: UserOperationAndProps) => void | Optional callback function executed by the background worker when a scheduled UserOperation is successfully mined on-chain. The function receives a single argument of type UserOperationAndProps, which includes the original userOp object, userOpHash, the final transactionHash, the updated status, and other details. | undefined |
app | express.Application | Provide an existing Express application instance | express() |
The service requires the following environment variables:
PAYMASTER_PORT=4000 # Service port (optional, defaults to 4000)
PVT_KEY= # Private key for the paymaster account
PROVIDER= # RPC provider URL
CHAIN_ID= # Chain ID for the network (e.g. 137 for Polygon)
The paymaster service currently supports the following networks:
See the examples directory for integration examples.
The underlying Express router used by the service is also exported as paymasterRouter. You can use this to add custom routes or middleware to the service instance:
import { PaymasterService, paymasterRouter } from '@actalink/erc20-paymaster';
import express from 'express';
const service = new PaymasterService();
const app = service.getApp(); // Get the Express app instance
// Add custom middleware
app.use('/api', (req, res, next) => {
console.log('Custom middleware for API routes');
next();
});
// Add a custom route
app.get('/custom-status', (req, res) => {
res.json({ custom: 'status OK' });
});
// You can also add routes directly to the exported router
paymasterRouter.get('/custom-paymaster-route', (req, res) => {
res.json({ message: 'Custom route within paymaster router' });
});
await service.start();
The package also exports several utility functions that might be useful for advanced integrations or direct database interaction. Use these with caution as they might expose internal implementation details.
getSignerFromMerkleSignature(root: Hex, proof: Hex[], leaf: Hex): Address
getScheduledUserOpsByHash(hashes: string[]): UserOperationAndProps[]
getScheduledUserOps(address: Address): UserOperationAndProps[]
removeUserOpByHash(hash: string): void
getInsertQuery(): Database.Statement
MIT
FAQs
ERC20 Paymaster service for Acta Account Abstraction
The npm package @actalink/erc20-paymaster receives a total of 1 weekly downloads. As such, @actalink/erc20-paymaster popularity was classified as not popular.
We found that @actalink/erc20-paymaster demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Following last week’s supply chain attack, Nx published findings on the GitHub Actions exploit and moved npm publishing to Trusted Publishers.
Security News
AGENTS.md is a fast-growing open format giving AI coding agents a shared, predictable way to understand project setup, style, and workflows.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.