🚀 MandateKit

Production-ready Web3 autopay SDK for crypto-based recurring payments on Polygon

MandateKit enables developers to easily create and manage recurring payments using EIP-712 mandates, relayer automation, pull-based billing, cadence enforcement, and secure non-custodial payments.

🌟 Live Deployment

Smart Contract Address (Polygon Mainnet):

0xd9145CCE52D386f254917e481eB44e9943F39138

View on PolygonScan

✨ Features

• 🔐 EIP-712 Typed Signatures - Secure, human-readable mandate signing (no phishing)
• 🤖 Relayer Automation - Automated pull-based payment execution with fee incentives
• ⏰ Cadence Enforcement - Flexible scheduling (daily, weekly, monthly, yearly, custom)
• 🔄 Replay Protection - Built-in nonce and timestamp validation
• 🛡️ Security Hardened - Checks-Effects-Interactions pattern, ReentrancyGuard
• 💰 Non-Custodial - Users always maintain control of their funds
• 🧩 Modular & Tree-shakeable - Import only what you need
• 💪 TypeScript First - Full type safety and IntelliSense
• 🔌 Adapter Support - Permit2, vaults, account abstraction ready
• 📦 Modern Stack - Built with Viem v2, ES2020+, OpenZeppelin v5

📦 Installation

From GitHub Packages

# Configure npm to use GitHub Packages
echo "@anuragchvn-blip:registry=https://npm.pkg.github.com" >> .npmrc

# Install the package
npm install @anuragchvn-blip/mandatekit viem

From npm (Coming Soon)

npm install @anuragchvn-blip/mandatekit viem

🏃 Quick Start

Backend (Node.js)

import { createMandateClient } from '@anuragchvn-blip/mandatekit/client';
import { privateKeyToAccount } from 'viem/accounts';
import { polygon } from 'viem/chains';

const account = privateKeyToAccount('0x...');
const client = createMandateClient({ 
  account,
  chain: polygon 
});

// Create a mandate for recurring USDC payments
const mandate = await client.signMandate({
  subscriber: '0x123...', // Payer address
  token: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174', // USDC on Polygon
  amount: '10000000', // 10 USDC (6 decimals)
  cadence: { interval: 'monthly', count: 1 },
  recipient: '0x456...', // Recipient address
  validAfter: Math.floor(Date.now() / 1000),
  validBefore: Math.floor(Date.now() / 1000) + 31536000, // 1 year
  maxPayments: 12, // Optional: auto-cancel after 12 payments
  metadata: 'Netflix subscription', // Optional
});

console.log('Mandate ID:', mandate.mandateId);
console.log('Signature:', mandate.signature);

Frontend (Browser with MetaMask)

import { createMandateClient } from '@anuragchvn-blip/mandatekit/client';
import { createWalletClient, custom } from 'viem';
import { polygon } from 'viem/chains';

const walletClient = createWalletClient({
  chain: polygon,
  transport: custom(window.ethereum),
});

const [address] = await walletClient.getAddresses();
const client = createMandateClient({ 
  walletClient, 
  address 
});

// User signs mandate in MetaMask
const mandate = await client.signMandate({
  subscriber: address,
  token: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174', // USDC
  amount: '10000000', // 10 USDC
  cadence: { interval: 'monthly', count: 1 },
  recipient: '0x456...',
  validAfter: Math.floor(Date.now() / 1000),
  validBefore: Math.floor(Date.now() / 1000) + 31536000,
});

// Register mandate on-chain
const txHash = await client.registerMandate(mandate);
console.log('Registered:', txHash);

Relayer (Automated Execution)

import { createRelayerClient } from '@anuragchvn-blip/mandatekit/relayer';
import { privateKeyToAccount } from 'viem/accounts';
import { polygon } from 'viem/chains';

const relayerAccount = privateKeyToAccount('0x...');
const relayer = createRelayerClient({
  account: relayerAccount,
  chain: polygon,
  registryAddress: '0xd9145CCE52D386f254917e481eB44e9943F39138',
  pollInterval: 60000, // Check every minute
});

// Schedule mandate for automated execution
await relayer.scheduleMandate(mandate);

// Relayer earns 0.5% fee for executing payments
console.log('Relayer monitoring active mandates...');

📚 Documentation

• API Reference - Complete API documentation
• Examples - Full working examples
• Smart Contract - Solidity source code
• Security - Security practices and audit info

🎯 Use Cases

• 💳 Subscription Services - Netflix-style recurring billing in crypto
• 💼 Payroll - Pay employees/contractors on a schedule
• 📈 Dollar-Cost Averaging (DCA) - Automated periodic token purchases
• 🏠 Rent/Bills - Recurring payments for utilities, rent, etc.
• 🎮 Gaming - Season passes and recurring in-game purchases
• 📱 SaaS - Decentralized software subscriptions

🏗️ Architecture

MandateKit
├── client/       → Mandate signing & verification (EIP-712)
├── relayer/      → Automated execution engine
├── contracts/    → Smart contract ABIs & addresses
├── utils/        → Cryptographic & validation utilities
└── adapters/     → Protocol integrations (Permit2, vaults, AA)

🔒 Security

Smart Contract Security

• ✅ Checks-Effects-Interactions Pattern - Prevents reentrancy attacks
• ✅ ReentrancyGuard - OpenZeppelin's reentrancy protection
• ✅ SafeERC20 - Secure token transfers with proper error handling
• ✅ Nonce-based Replay Protection - Each mandate uses unique nonce
• ✅ Timestamp Validation - Enforces validAfter/validBefore windows
• ✅ Cadence Enforcement - Contract-level payment scheduling
• ✅ Signature Verification - EIP-712 typed data signatures
• ✅ Owner Access Control - Only owner can modify critical parameters

SDK Security

• ✅ EIP-712 Typed Data - Human-readable signatures prevent phishing
• ✅ Input Validation - Comprehensive validation before signing
• ✅ TypeScript Type Safety - Compile-time error prevention
• ✅ No Private Key Storage - Uses viem's secure account handling

Deployed Contract

Polygon Mainnet: 0xd9145CCE52D386f254917e481eB44e9943F39138

• Owner: 0x5B38Da6a701c568545dCfcB03FcB875f56beddC4
• Fee Collector: 0x2913411D27f5d6716590F952b50088779Ae4a699
• Relayer Fee: 0.5% (50 basis points)
• Max Fee Cap: 5% (500 basis points)

🛠️ Development

Setup

# Clone repository
git clone https://github.com/anuragchvn-blip/MandateKit.git
cd MandateKit

# Install dependencies
npm install

# Build SDK
npm run build

# Run examples
npm run example:backend
npm run example:relayer

Publishing to GitHub Packages

# Authenticate with GitHub
npm login --registry=https://npm.pkg.github.com

# Build and publish
npm run build
npm publish

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide first.

📄 License

MIT © 2025 MandateKit

🔗 Links

• Repository: github.com/anuragchvn-blip/MandateKit
• Issues: github.com/anuragchvn-blip/MandateKit/issues
• Polygon Contract: 0xd9145CCE52D386f254917e481eB44e9943F39138

⚠️ Disclaimer

This software is provided "as is", without warranty of any kind. Use at your own risk. Always test thoroughly before using in production with real funds.