@anuragchvn-blip/mandatekit/README.md

Production-ready Web3 autopay SDK for crypto-based recurring payments using EIP-712 mandates

# 🚀 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.

[![npm version](https://badge.fury.io/js/%40anuragchvn-blip%2Fmandatekit.svg)](https://github.com/anuragchvn-blip/MandateKit/packages)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🌟 Live Deployment

**Smart Contract Address (Polygon Mainnet):**
```
0xd9145CCE52D386f254917e481eB44e9943F39138
```

View on [PolygonScan](https://polygonscan.com/address/0xd9145CCE52D386f254917e481eB44e9943F39138)

## ✨ 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

```bash
# 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)

```bash
npm install @anuragchvn-blip/mandatekit viem
```

## 🏃 Quick Start

### Backend (Node.js)

```typescript
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)

```typescript
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)

```typescript
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](./docs/API.md)** - Complete API documentation
- **[Examples](./examples/)** - Full working examples
- **[Smart Contract](./contracts/)** - Solidity source code
- **[Security](./SECURITY.md)** - 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

```text
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

```bash
# 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

```bash
# 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](./CONTRIBUTING.md) first.

## 📄 License

MIT © 2025 MandateKit

## 🔗 Links

- **Repository:** [github.com/anuragchvn-blip/MandateKit](https://github.com/anuragchvn-blip/MandateKit)
- **Issues:** [github.com/anuragchvn-blip/MandateKit/issues](https://github.com/anuragchvn-blip/MandateKit/issues)
- **Polygon Contract:** [0xd9145CCE52D386f254917e481eB44e9943F39138](https://polygonscan.com/address/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.